@pix3/vite-plugin 2.0.0-alpha.0 → 2.0.0-alpha.1

package/dist/build/player-modules.js

@@ -17,6 +17,7 @@ export const PROJECT_SCRIPTS_ID = 'virtual:pix3/project-scripts';
 export const SPINE_ID = 'virtual:pix3/spine';
 export const POSTPROCESSING_ID = 'virtual:pix3/postprocessing';
 export const NETWORK_ID = 'virtual:pix3/network';
+export const DEV_ID = 'virtual:pix3/dev';
 /** What `postprocessing` resolves to in a single-file build whose scenes place no `PostProcess`. */
 export const POSTPROCESSING_STUB_ID = 'virtual:pix3/postprocessing-stub';
 /** What `yaml` resolves to for the runtime when the scenes ship as JSON. */
@@ -30,6 +31,7 @@ export const PLAYER_VIRTUAL_IDS = [
     SPINE_ID,
     POSTPROCESSING_ID,
     NETWORK_ID,
+    DEV_ID,
     POSTPROCESSING_STUB_ID,
     YAML_STUB_ID,
     GLTF_LOADER_STUB_ID,
@@ -202,3 +204,51 @@ export const networkSource = (usesNetwork) => usesNetwork
         'export function installNetworkService() {}',
         '',
     ].join('\n');
+/**
+ * `virtual:pix3/dev`: the player's dev-only hooks. In dev:
+ *
+ * - `devSceneOverride()` is the URL's `?scene=` (`res://` stripped), the scene the editor's
+ *   "Play in Browser Tab / with Profiler" asks for; the player checks it against its scene list;
+ * - `installDevTools(context)` imports the debug overlay when the URL has `debug`, otherwise the
+ *   "Pix3 editor" link (top-level page, editor on, no `?clean`), so a plain `/` costs one small
+ *   module and `/?clean` none.
+ *
+ * In a build both are no-ops and nothing of the overlay or the link is bundled (a single-file
+ * HTML cannot fetch a chunk anyway). The modules are imported by file path, not by a package
+ * subpath: Vite's resolver answers bare specifiers from `exports` before any plugin's
+ * `resolveId` runs.
+ */
+export const devSource = (mode, options) => {
+    if (mode === 'none' || !options) {
+        return [
+            '// A build has no dev tools: the debug overlay, the editor link and ?scene= are dev-only.',
+            'export function devSceneOverride() { return null; }',
+            'export function installDevTools() {}',
+            '',
+        ].join('\n');
+    }
+    return [
+        `const editorUrl = ${JSON.stringify(options.editorUrl)};`,
+        `const params = new URLSearchParams(location.search);`,
+        `const failed = what => error => console.error('[pix3] The ' + what + ' failed to load:', error);`,
+        `export function devSceneOverride() {`,
+        `  const scene = params.get('scene');`,
+        `  return scene ? scene.replace(/^res:\\/\\//i, '').replace(/^\\/+/, '') : null;`,
+        `}`,
+        `export function installDevTools(context) {`,
+        `  if (params.has('debug')) {`,
+        `    import(${JSON.stringify(options.overlayPath)}).then(`,
+        `      overlay => overlay.mountDebugOverlay(context, { editorUrl }),`,
+        `      failed('debug overlay')`,
+        `    );`,
+        `    return;`,
+        `  }`,
+        `  if (!editorUrl || window.top !== window || params.has('clean')) return;`,
+        `  import(${JSON.stringify(options.editorLinkPath)}).then(`,
+        `    link => link.mountEditorLink(editorUrl),`,
+        `    failed('editor link')`,
+        `  );`,
+        `}`,
+        '',
+    ].join('\n');
+};

package/dist/editor-page.js

@@ -21,33 +21,33 @@ const VITE_CLIENT_PROBE = 'window.__PIX3_VITE_CLIENT__=false;try{performance.set
 const escapeHtml = (text) => text.replace(/[&<>"']/g, ch => `&#${ch.charCodeAt(0)};`);
 /** The `<meta>` the page client reads (and removes) the editor session token from. */
 export const SESSION_META = 'pix3-session';
-export const editorPageHtml = (base, options = {}) => `<!doctype html>
-<html lang="en">
-  <head>
-    <meta charset="utf-8" />
+export const editorPageHtml = (base, options = {}) => `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1" />${options.session
     ? `\n    <meta name="${SESSION_META}" content="${escapeHtml(options.session)}" />`
-    : ''}
-    <title>Pix3</title>
-    <style>html,body,#pix3-editor{margin:0;height:100%}</style>
-    <script>${VITE_CLIENT_PROBE}</script>${options.css ? `\n    <link rel="stylesheet" href="${base}__pix3/editor.css" />` : ''}
-  </head>
-  <body>
-    <div id="pix3-editor"></div>
-    <script type="module" src="${base}@id/__x00__${EDITOR_HOST_ID}"></script>
-  </body>
-</html>
+    : ''}
+    <title>Pix3</title>
+    <style>html,body,#pix3-editor{margin:0;height:100%}</style>
+    <script>${VITE_CLIENT_PROBE}</script>${options.css ? `\n    <link rel="stylesheet" href="${base}__pix3/editor.css" />` : ''}
+  </head>
+  <body>
+    <div id="pix3-editor"></div>
+    <script type="module" src="${base}@id/__x00__${EDITOR_HOST_ID}"></script>
+  </body>
+</html>
 `;
 /** What `/__pix3/` shows instead of the editor when the version gate fails (plan §A.3). */
-export const versionGatePageHtml = (message) => `<!doctype html>
-<html lang="en">
-  <head><meta charset="utf-8" /><title>Pix3 — version mismatch</title></head>
-  <body style="font:15px/1.5 system-ui,sans-serif;margin:3rem;max-width:44rem">
-    <h1 style="font-size:1.4rem">Pix3 cannot open this project yet</h1>
-    <p>${escapeHtml(message)}</p>
-    <p>Then restart the dev server.</p>
-  </body>
-</html>
+export const versionGatePageHtml = (message) => `<!doctype html>
+<html lang="en">
+  <head><meta charset="utf-8" /><title>Pix3 — version mismatch</title></head>
+  <body style="font:15px/1.5 system-ui,sans-serif;margin:3rem;max-width:44rem">
+    <h1 style="font-size:1.4rem">Pix3 cannot open this project yet</h1>
+    <p>${escapeHtml(message)}</p>
+    <p>Then restart the dev server.</p>
+  </body>
+</html>
 `;
 /**
  * Source of `virtual:pix3/editor-host`. The script roots are imported statically, so they are in

package/dist/index.js

@@ -7,7 +7,7 @@ import { devSceneManifestSource } from "./build/dev-manifest.js";
 import { finishBuild } from "./build/finish.js";
 import { libraryStubsPlugin, singleFilePlugins } from "./build/output-plugins.js";
 import { flushEditor, planBuild, runtimeModulePath, shippedBytes, } from "./build/plan.js";
-import { EMBEDDED_ASSETS_ID, embeddedAssetsSource, GLTF_LOADER_STUB_ID, gltfLoaderStubSource, NETWORK_ID, networkSource, noEmbeddedAssetsSource, PLAYER_VIRTUAL_IDS, POSTPROCESSING_ID, POSTPROCESSING_STUB_ID, postprocessingSource, postprocessingStubSource, PROJECT_SCRIPTS_ID, projectScriptsSource, SCENE_MANIFEST_ID, sceneManifestSource, SPINE_ID, spineSource, YAML_STUB_ID, yamlStubSource, } from "./build/player-modules.js";
+import { DEV_ID, devSource, EMBEDDED_ASSETS_ID, embeddedAssetsSource, GLTF_LOADER_STUB_ID, gltfLoaderStubSource, NETWORK_ID, networkSource, noEmbeddedAssetsSource, PLAYER_VIRTUAL_IDS, POSTPROCESSING_ID, POSTPROCESSING_STUB_ID, postprocessingSource, postprocessingStubSource, PROJECT_SCRIPTS_ID, projectScriptsSource, SCENE_MANIFEST_ID, sceneManifestSource, SPINE_ID, spineSource, YAML_STUB_ID, yamlStubSource, } from "./build/player-modules.js";
 import { normalizeResRoot } from "./build/project-manifest.js";
 import { buildStrippedModuleSource } from "./build/strippable-runtime-modules.js";
 import { installedVersion, pluginVersion } from "./dev-info.js";
@@ -33,6 +33,10 @@ const FROM_SOURCE = import.meta.url.endsWith('.ts');
 const CLIENT_ENTRY = fileURLToPath(new URL(`./client/index.${FROM_SOURCE ? 'ts' : 'js'}`, import.meta.url));
 /** The player (`player/` beside `src/`; `dist/player/` once built). */
 const PLAYER_ENTRY = fileURLToPath(new URL(FROM_SOURCE ? '../player/index.ts' : './player/index.js', import.meta.url));
+/** The player's dev tools, imported by path from `virtual:pix3/dev`: the debug overlay (`/?debug`)… */
+const DEBUG_OVERLAY_ENTRY = fileURLToPath(new URL(FROM_SOURCE ? '../player/debug/index.ts' : './player/debug/index.js', import.meta.url));
+/** …and the "Pix3 editor" link on the game. */
+const EDITOR_LINK_ENTRY = fileURLToPath(new URL(FROM_SOURCE ? '../player/dev/editor-link.ts' : './player/dev/editor-link.js', import.meta.url));
 export function pix3(options = {}) {
     const settings = {
         resRoot: normalizeResRoot(options.resRoot ?? '.'),
@@ -222,6 +226,14 @@ export function pix3(options = {}) {
                     return postprocessingStubSource();
                 case NETWORK_ID:
                     return networkSource(build ? build.scan.usesNetwork : true);
+                case DEV_ID:
+                    return config?.command === 'serve'
+                        ? devSource('dev', {
+                            overlayPath: normalizePath(DEBUG_OVERLAY_ENTRY),
+                            editorLinkPath: normalizePath(EDITOR_LINK_ENTRY),
+                            editorUrl: settings.editor ? `${baseUrl()}__pix3/` : null,
+                        })
+                        : devSource('none');
                 default:
                     return null;
             }

package/dist/module-paths.js

@@ -21,7 +21,7 @@ export const realFileOf = (id) => {
     let real = realPaths.get(file);
     if (real === undefined) {
         try {
-            real = realpathSync(file);
+            real = realpathSync.native(file);
         }
         catch {
             real = file;

package/dist/player/debug/context.d.ts

@@ -0,0 +1,9 @@
+import type { AudioService, RuntimeRenderer, SceneRunner } from '@pix3/runtime';
+import type { Pix3PlayerState } from '../index';
+/** What the player hands the debug overlay (`virtual:pix3/dev`'s `installDevTools`). */
+export interface Pix3DebugContext {
+    readonly runner: SceneRunner;
+    readonly renderer: RuntimeRenderer;
+    readonly audio: AudioService;
+    readonly state: Pix3PlayerState;
+}

package/dist/player/debug/context.js

@@ -0,0 +1 @@
+export {};

package/dist/player/debug/device-info.d.ts

@@ -0,0 +1,15 @@
+/** What the debug overlay shows about the device (the 1.x remote preview's `device-info`). */
+export interface DeviceInfo {
+    readonly userAgent: string;
+    /** `UNMASKED_RENDERER_WEBGL` when the browser exposes it, else `RENDERER`. */
+    readonly gpu: string | null;
+    readonly devicePixelRatio: number;
+    readonly screen: string;
+    readonly viewport: string;
+    /** `navigator.deviceMemory` (Chromium, coarse and capped at 8). */
+    readonly memoryGb: number | null;
+    readonly cores: number | null;
+}
+export declare const readDeviceInfo: () => DeviceInfo;
+/** Used JS heap in MiB (`performance.memory`, Chromium only). */
+export declare const readHeapMb: () => number | null;

package/dist/player/debug/device-info.js

@@ -0,0 +1,36 @@
+/** A throwaway GL context: the game's own context is not touched. */
+const readGpu = () => {
+    try {
+        const canvas = document.createElement('canvas');
+        const gl = canvas.getContext('webgl2') ?? canvas.getContext('webgl');
+        if (!gl)
+            return null;
+        const debugInfo = gl.getExtension('WEBGL_debug_renderer_info');
+        const renderer = gl.getParameter(debugInfo ? debugInfo.UNMASKED_RENDERER_WEBGL : gl.RENDERER);
+        gl.getExtension('WEBGL_lose_context')?.loseContext();
+        return typeof renderer === 'string' && renderer.length > 0 ? renderer : null;
+    }
+    catch {
+        return null;
+    }
+};
+let gpu;
+export const readDeviceInfo = () => {
+    if (gpu === undefined)
+        gpu = readGpu();
+    const nav = navigator;
+    return {
+        userAgent: navigator.userAgent,
+        gpu,
+        devicePixelRatio: window.devicePixelRatio || 1,
+        screen: `${window.screen?.width ?? 0}×${window.screen?.height ?? 0}`,
+        viewport: `${window.innerWidth}×${window.innerHeight}`,
+        memoryGb: typeof nav.deviceMemory === 'number' ? nav.deviceMemory : null,
+        cores: typeof navigator.hardwareConcurrency === 'number' ? navigator.hardwareConcurrency : null,
+    };
+};
+/** Used JS heap in MiB (`performance.memory`, Chromium only). */
+export const readHeapMb = () => {
+    const used = performance.memory?.usedJSHeapSize;
+    return typeof used === 'number' && Number.isFinite(used) ? used / (1024 * 1024) : null;
+};

package/dist/player/debug/frame-stats.d.ts

@@ -0,0 +1,79 @@
+import type { SceneRunnerFrameSample } from '@pix3/runtime';
+/**
+ * The debug overlay's frame bookkeeping, DOM-free: a fixed-bucket interval histogram for the
+ * session's percentiles, a ring of recent frames for the chart, and a rolling window of averages
+ * (frame split, FPS, `FrameProfiler` activities) that the overlay swaps at its text cadence.
+ * Everything here is O(1) per frame and allocates nothing per frame.
+ */
+/** Frames past this count as hitches: ~2 missed vsyncs at 60 Hz. */
+export declare const LONG_FRAME_MS = 33.4;
+export interface FrameStability {
+    readonly sampleCount: number;
+    readonly p50Ms: number | null;
+    readonly p95Ms: number | null;
+    readonly p99Ms: number | null;
+    readonly worstMs: number | null;
+    /** Frames longer than {@link LONG_FRAME_MS}. */
+    readonly longCount: number;
+    readonly longPercent: number | null;
+}
+/**
+ * 1 ms buckets up to 100 ms plus an overflow bucket (the 1.x Profiler's `FrameIntervalHistogram`):
+ * a session can run for hours, so nothing keeps every frame. Percentiles are nearest-rank and
+ * report the bucket's upper edge clamped to the worst frame, so they are never optimistic.
+ */
+export declare class FrameIntervalHistogram {
+    private readonly buckets;
+    private count;
+    private long;
+    private worst;
+    reset(): void;
+    record(intervalMs: number): void;
+    snapshot(): FrameStability;
+    private percentile;
+}
+/** The last {@link capacity} frames, split the way the chart stacks them. */
+export declare class FrameRing {
+    readonly capacity: number;
+    readonly logicMs: Float32Array;
+    readonly renderMs: Float32Array;
+    /** Frame duration (`dt`), the bar's full height; the rest above logic + render is "not us". */
+    readonly frameMs: Float32Array;
+    private next;
+    private filled;
+    constructor(capacity?: number);
+    push(logicMs: number, renderMs: number, frameMs: number): void;
+    get length(): number;
+    /** Ring index of the `i`-th oldest retained frame (`0` = oldest). */
+    indexOf(i: number): number;
+    clear(): void;
+}
+export interface FrameWindow {
+    readonly frames: number;
+    /** Frames per second of wall clock in the window (`frames / Σdt`), null when empty. */
+    readonly fps: number | null;
+    readonly frameMs: number | null;
+    readonly logicMs: number | null;
+    readonly renderMs: number | null;
+    readonly unaccountedMs: number | null;
+    readonly rafLatenessMs: number | null;
+    /** `FrameProfiler` activities, mean self time per frame, largest first. */
+    readonly activities: readonly {
+        readonly label: string;
+        readonly ms: number;
+    }[];
+}
+export declare const EMPTY_WINDOW: FrameWindow;
+/** Sums since the last {@link close}; `close` turns them into a {@link FrameWindow}. */
+export declare class FrameWindowAccumulator {
+    private frames;
+    private dtSec;
+    private logic;
+    private render;
+    private unaccounted;
+    private lateness;
+    private readonly activitySums;
+    add(sample: SceneRunnerFrameSample): void;
+    close(): FrameWindow;
+    private addActivities;
+}

package/dist/player/debug/frame-stats.js

@@ -0,0 +1,159 @@
+/**
+ * The debug overlay's frame bookkeeping, DOM-free: a fixed-bucket interval histogram for the
+ * session's percentiles, a ring of recent frames for the chart, and a rolling window of averages
+ * (frame split, FPS, `FrameProfiler` activities) that the overlay swaps at its text cadence.
+ * Everything here is O(1) per frame and allocates nothing per frame.
+ */
+/** Frames past this count as hitches: ~2 missed vsyncs at 60 Hz. */
+export const LONG_FRAME_MS = 33.4;
+const HISTOGRAM_MAX_MS = 100;
+/**
+ * 1 ms buckets up to 100 ms plus an overflow bucket (the 1.x Profiler's `FrameIntervalHistogram`):
+ * a session can run for hours, so nothing keeps every frame. Percentiles are nearest-rank and
+ * report the bucket's upper edge clamped to the worst frame, so they are never optimistic.
+ */
+export class FrameIntervalHistogram {
+    buckets = new Uint32Array(HISTOGRAM_MAX_MS + 1);
+    count = 0;
+    long = 0;
+    worst = 0;
+    reset() {
+        this.buckets.fill(0);
+        this.count = 0;
+        this.long = 0;
+        this.worst = 0;
+    }
+    record(intervalMs) {
+        if (!Number.isFinite(intervalMs) || intervalMs < 0)
+            return;
+        this.buckets[Math.min(Math.floor(intervalMs), HISTOGRAM_MAX_MS)] += 1;
+        this.count += 1;
+        if (intervalMs > this.worst)
+            this.worst = intervalMs;
+        if (intervalMs > LONG_FRAME_MS)
+            this.long += 1;
+    }
+    snapshot() {
+        const empty = this.count === 0;
+        return {
+            sampleCount: this.count,
+            p50Ms: this.percentile(50),
+            p95Ms: this.percentile(95),
+            p99Ms: this.percentile(99),
+            worstMs: empty ? null : this.worst,
+            longCount: this.long,
+            longPercent: empty ? null : (this.long / this.count) * 100,
+        };
+    }
+    percentile(percent) {
+        if (this.count === 0)
+            return null;
+        const rank = Math.max(1, Math.ceil((percent / 100) * this.count));
+        let cumulative = 0;
+        for (let bucket = 0; bucket < this.buckets.length; bucket += 1) {
+            cumulative += this.buckets[bucket];
+            if (cumulative >= rank) {
+                // The overflow bucket has no upper edge: the worst frame is the only honest answer.
+                return bucket === HISTOGRAM_MAX_MS ? this.worst : Math.min(bucket + 1, this.worst);
+            }
+        }
+        return this.worst;
+    }
+}
+/** The last {@link capacity} frames, split the way the chart stacks them. */
+export class FrameRing {
+    capacity;
+    logicMs;
+    renderMs;
+    /** Frame duration (`dt`), the bar's full height; the rest above logic + render is "not us". */
+    frameMs;
+    next = 0;
+    filled = 0;
+    constructor(capacity = 240) {
+        this.capacity = capacity;
+        this.logicMs = new Float32Array(capacity);
+        this.renderMs = new Float32Array(capacity);
+        this.frameMs = new Float32Array(capacity);
+    }
+    push(logicMs, renderMs, frameMs) {
+        this.logicMs[this.next] = logicMs;
+        this.renderMs[this.next] = renderMs;
+        this.frameMs[this.next] = frameMs;
+        this.next = (this.next + 1) % this.capacity;
+        this.filled = Math.min(this.filled + 1, this.capacity);
+    }
+    get length() {
+        return this.filled;
+    }
+    /** Ring index of the `i`-th oldest retained frame (`0` = oldest). */
+    indexOf(i) {
+        return (this.next - this.filled + i + this.capacity) % this.capacity;
+    }
+    clear() {
+        this.next = 0;
+        this.filled = 0;
+    }
+}
+export const EMPTY_WINDOW = Object.freeze({
+    frames: 0,
+    fps: null,
+    frameMs: null,
+    logicMs: null,
+    renderMs: null,
+    unaccountedMs: null,
+    rafLatenessMs: null,
+    activities: Object.freeze([]),
+});
+/** Sums since the last {@link close}; `close` turns them into a {@link FrameWindow}. */
+export class FrameWindowAccumulator {
+    frames = 0;
+    dtSec = 0;
+    logic = 0;
+    render = 0;
+    unaccounted = 0;
+    lateness = 0;
+    activitySums = new Map();
+    add(sample) {
+        this.frames += 1;
+        this.dtSec += sample.dt;
+        this.logic += sample.logicMs;
+        this.render += sample.renderMs;
+        this.unaccounted += sample.unaccountedMs;
+        this.lateness += sample.rafLatenessMs;
+        if (sample.profilerActivities)
+            this.addActivities(sample.profilerActivities);
+    }
+    close() {
+        const n = this.frames;
+        if (n === 0)
+            return EMPTY_WINDOW;
+        const activities = [...this.activitySums]
+            .map(([label, sum]) => ({ label, ms: sum / n }))
+            .sort((a, b) => b.ms - a.ms);
+        const window = {
+            frames: n,
+            fps: this.dtSec > 0 ? n / this.dtSec : null,
+            frameMs: (this.dtSec * 1000) / n,
+            logicMs: this.logic / n,
+            renderMs: this.render / n,
+            unaccountedMs: this.unaccounted / n,
+            rafLatenessMs: this.lateness / n,
+            activities,
+        };
+        this.frames = 0;
+        this.dtSec = 0;
+        this.logic = 0;
+        this.render = 0;
+        this.unaccounted = 0;
+        this.lateness = 0;
+        this.activitySums.clear();
+        return window;
+    }
+    addActivities(activities) {
+        for (const activity of activities) {
+            if (!Number.isFinite(activity.selfTimeMs))
+                continue;
+            this.activitySums.set(activity.label, (this.activitySums.get(activity.label) ?? 0) + activity.selfTimeMs);
+        }
+    }
+}

package/dist/player/debug/index.d.ts

@@ -0,0 +1,10 @@
+import type { Pix3DebugContext } from './context';
+/**
+ * Debug mode (`/?debug` on the dev server; `virtual:pix3/dev` imports this only then, and a
+ * build never). Mounts the overlay over the running game and exposes
+ * `__PIX3_PLAYER__.debug.snapshot()` for an agent. `editorUrl` (null with `editor: false`) adds
+ * the header's Editor button. Returns the teardown.
+ */
+export declare function mountDebugOverlay(context: Pix3DebugContext, options?: {
+    readonly editorUrl?: string | null;
+}): () => void;

package/dist/player/debug/index.js

@@ -0,0 +1,20 @@
+import { DebugOverlay } from './overlay';
+import { DebugSession } from './session';
+/**
+ * Debug mode (`/?debug` on the dev server; `virtual:pix3/dev` imports this only then, and a
+ * build never). Mounts the overlay over the running game and exposes
+ * `__PIX3_PLAYER__.debug.snapshot()` for an agent. `editorUrl` (null with `editor: false`) adds
+ * the header's Editor button. Returns the teardown.
+ */
+export function mountDebugOverlay(context, options = {}) {
+    const session = new DebugSession(context);
+    session.start();
+    const overlay = new DebugOverlay(session, options.editorUrl ?? null);
+    overlay.mount();
+    context.state.debug = { snapshot: () => session.snapshot() };
+    return () => {
+        overlay.dispose();
+        session.dispose();
+        delete context.state.debug;
+    };
+}

package/dist/player/debug/long-frames.d.ts

@@ -0,0 +1,46 @@
+/**
+ * The browser's **Long Animation Frame** entries (LoAF, Chromium), a port of the 1.x Profiler's
+ * `LongAnimationFrameObserver`. The runner's own stopwatch only sees its logic and paint; LoAF is
+ * the browser's view of the same frame and the only source that says what else ran. LoAF
+ * attributes only scripts that ran longer than ~5 ms, so a long frame with no script is a finding
+ * (late delivery, compositing, GC), not a gap: it is kept as `script: null`.
+ */
+/** One `scripts[]` entry of a LoAF timing (TS's DOM lib has no LoAF types yet). */
+interface LoafScriptLike {
+    readonly sourceURL?: string;
+    readonly sourceFunctionName?: string;
+    readonly duration?: number;
+    readonly invoker?: string;
+}
+interface LoafEntryLike {
+    readonly duration?: number;
+    readonly blockingDuration?: number;
+    readonly scripts?: readonly LoafScriptLike[];
+}
+export interface LongFrameRecord {
+    readonly durationMs: number;
+    readonly blockingMs: number;
+    /** `basename.js · function` of the longest attributed script, or null: none was attributed. */
+    readonly script: string | null;
+}
+export interface LongFrameStats {
+    /** False where the browser has no `long-animation-frame` entries (Firefox, Safari). */
+    readonly supported: boolean;
+    readonly count: number;
+    /** The worst few of the session, longest first. */
+    readonly worst: readonly LongFrameRecord[];
+}
+export declare class LongFrameObserver {
+    readonly supported: boolean;
+    private observer;
+    private count;
+    private worst;
+    constructor();
+    start(): void;
+    stop(): void;
+    reset(): void;
+    stats(): LongFrameStats;
+    /** One entry, as the observer's callback hands it over (public for the spec). */
+    record(entry: LoafEntryLike): void;
+}
+export {};

package/dist/player/debug/long-frames.js

@@ -0,0 +1,79 @@
+/**
+ * The browser's **Long Animation Frame** entries (LoAF, Chromium), a port of the 1.x Profiler's
+ * `LongAnimationFrameObserver`. The runner's own stopwatch only sees its logic and paint; LoAF is
+ * the browser's view of the same frame and the only source that says what else ran. LoAF
+ * attributes only scripts that ran longer than ~5 ms, so a long frame with no script is a finding
+ * (late delivery, compositing, GC), not a gap: it is kept as `script: null`.
+ */
+const KEEP_WORST = 4;
+export class LongFrameObserver {
+    supported;
+    observer = null;
+    count = 0;
+    worst = [];
+    constructor() {
+        const types = typeof PerformanceObserver === 'undefined'
+            ? undefined
+            : PerformanceObserver.supportedEntryTypes;
+        this.supported = Array.isArray(types) && types.includes('long-animation-frame');
+    }
+    start() {
+        if (!this.supported || this.observer)
+            return;
+        this.observer = new PerformanceObserver(list => {
+            for (const entry of list.getEntries())
+                this.record(entry);
+        });
+        this.observer.observe({ type: 'long-animation-frame' });
+    }
+    stop() {
+        this.observer?.disconnect();
+        this.observer = null;
+    }
+    reset() {
+        this.count = 0;
+        this.worst = [];
+    }
+    stats() {
+        return { supported: this.supported, count: this.count, worst: [...this.worst] };
+    }
+    /** One entry, as the observer's callback hands it over (public for the spec). */
+    record(entry) {
+        const durationMs = typeof entry.duration === 'number' ? entry.duration : 0;
+        if (!Number.isFinite(durationMs) || durationMs <= 0)
+            return;
+        this.count += 1;
+        const record = {
+            durationMs,
+            blockingMs: Number.isFinite(entry.blockingDuration) ? entry.blockingDuration : 0,
+            script: describeScript(longestScript(entry.scripts)),
+        };
+        const at = this.worst.findIndex(existing => durationMs > existing.durationMs);
+        if (at === -1) {
+            if (this.worst.length < KEEP_WORST)
+                this.worst.push(record);
+            return;
+        }
+        this.worst.splice(at, 0, record);
+        if (this.worst.length > KEEP_WORST)
+            this.worst.length = KEEP_WORST;
+    }
+}
+const longestScript = (scripts) => {
+    let longest = null;
+    for (const script of scripts ?? []) {
+        if (!longest || (script.duration ?? 0) > (longest.duration ?? 0))
+            longest = script;
+    }
+    return longest;
+};
+const describeScript = (script) => {
+    if (!script)
+        return null;
+    const url = script.sourceURL?.trim().split(/[?#]/)[0];
+    const basename = url ? url.slice(url.lastIndexOf('/') + 1) || url : null;
+    const fn = script.sourceFunctionName?.trim();
+    if (basename && fn)
+        return `${basename} · ${fn}`;
+    return basename || fn || script.invoker?.trim() || null;
+};

package/dist/player/debug/overlay.d.ts

@@ -0,0 +1,25 @@
+import type { DebugSession } from './session';
+export declare class DebugOverlay {
+    private readonly session;
+    private readonly editorUrl;
+    private readonly host;
+    private readonly root;
+    private readonly panel;
+    private readonly canvas;
+    private readonly fps;
+    private readonly sections;
+    private readonly pauseButton;
+    private readonly stepButton;
+    private readonly collapseButton;
+    private timer;
+    private ticks;
+    constructor(session: DebugSession, editorUrl?: string | null);
+    mount(): void;
+    dispose(): void;
+    /** The timer: the chart every tick; every {@link TEXT_EVERY}th, a new window and the text. */
+    private tick;
+    private render;
+    private renderHeader;
+    private readonly onClick;
+    private setCollapsed;
+}