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

package/dist/player/debug/overlay.js

@@ -0,0 +1,320 @@
+import { openEditor } from '../dev/editor-link';
+import { LONG_FRAME_MS } from './frame-stats';
+/**
+ * The debug overlay's DOM: a panel over the game's top-right corner, in a shadow root so the
+ * game's CSS cannot reach it (and its CSS cannot reach the game). The chart repaints at 8 Hz and
+ * the text at 2 Hz (each text refresh closes an averaging window), from timers rather than the game's frame listener, so a slow page shows a
+ * slow overlay instead of a slower game.
+ */
+const CHART_MS = 125;
+const TEXT_EVERY = 4;
+const CHART_CEILING_MS = 50;
+const COLLAPSED_KEY = 'pix3:debug:collapsed';
+const STYLE = `
+:host { all: initial; }
+.panel {
+  position: fixed; top: 8px; right: 8px; z-index: 2147483647;
+  width: min(320px, calc(100vw - 16px)); max-height: calc(100vh - 16px);
+  overflow: hidden auto; scrollbar-width: thin; scrollbar-color: rgba(255,255,255,0.25) transparent;
+  box-sizing: border-box; padding: 8px 10px;
+  font: 11px/1.45 ui-monospace, SFMono-Regular, Menlo, Consolas, monospace;
+  color: #e8e8e8; background: rgba(18, 18, 20, 0.88); border: 1px solid rgba(255,255,255,0.12);
+  border-radius: 6px; backdrop-filter: blur(4px); -webkit-backdrop-filter: blur(4px);
+  user-select: text;
+}
+.panel.collapsed { width: auto; }
+.panel.collapsed .body { display: none; }
+header { display: flex; align-items: center; gap: 6px; }
+.title { font-weight: 600; color: #ffcf33; margin-right: auto; white-space: nowrap; }
+.fps { font-weight: 600; min-width: 4.5em; text-align: right; white-space: nowrap; }
+button {
+  font: inherit; color: inherit; background: rgba(255,255,255,0.08);
+  border: 1px solid rgba(255,255,255,0.16); border-radius: 4px; padding: 1px 7px; cursor: pointer;
+}
+button:hover:not(:disabled) { background: rgba(255,255,255,0.16); }
+button:disabled { opacity: 0.4; cursor: default; }
+button[aria-pressed="true"] { background: rgba(255,207,51,0.25); border-color: #ffcf33; }
+canvas { display: block; width: 100%; height: 64px; margin-top: 6px; }
+.legend { display: flex; flex-wrap: wrap; gap: 2px 10px; color: #a0a0a0; margin-top: 2px; }
+.legend > span { white-space: nowrap; }
+.legend i { display: inline-block; width: 8px; height: 8px; margin-right: 4px; vertical-align: -1px; }
+section { margin-top: 8px; }
+h3 { all: unset; display: block; color: #a0a0a0; text-transform: uppercase; font-size: 10px;
+  letter-spacing: 0.06em; border-bottom: 1px solid rgba(255,255,255,0.08); margin-bottom: 3px; }
+.row { display: flex; justify-content: space-between; gap: 8px; }
+.row > :first-child { min-width: 0; color: #a0a0a0; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.row > :last-child { flex: none; max-width: 70%; text-align: right; white-space: nowrap; overflow: hidden; text-overflow: ellipsis; }
+.warn { color: #ffb454; }
+.bad { color: #ff6b6b; }
+.muted { color: #707070; }
+.error { color: #ff6b6b; word-break: break-word; margin-top: 2px; }
+.error small { display: block; color: #a0a0a0; }
+pre { margin: 0; white-space: pre-wrap; word-break: break-word; max-height: 160px; overflow: auto; }
+`;
+const COLORS = {
+    logic: '#ffcf33',
+    render: '#4ea1ff',
+    other: 'rgba(255,255,255,0.22)',
+    grid: 'rgba(255,255,255,0.18)',
+    over: '#ff6b6b',
+};
+const ms = (value, digits = 1) => value === null ? '–' : `${value.toFixed(digits)} ms`;
+const num = (value) => value === null || value === undefined ? '–' : value.toLocaleString('en-US');
+const escapeHtml = (text) => text.replace(/[&<>"']/g, ch => `&#${ch.charCodeAt(0)};`);
+const row = (label, value, cls = '') => `<div class="row"><span>${escapeHtml(label)}</span><span class="${cls}">${value}</span></div>`;
+const section = (title, body) => `<section><h3>${escapeHtml(title)}</h3>${body}</section>`;
+const readCollapsed = () => {
+    try {
+        return localStorage.getItem(COLLAPSED_KEY) === '1';
+    }
+    catch {
+        return false;
+    }
+};
+const writeCollapsed = (collapsed) => {
+    try {
+        localStorage.setItem(COLLAPSED_KEY, collapsed ? '1' : '0');
+    }
+    catch {
+        // Per-viewer convenience only.
+    }
+};
+export class DebugOverlay {
+    session;
+    editorUrl;
+    host = document.createElement('div');
+    root;
+    panel;
+    canvas;
+    fps;
+    sections;
+    pauseButton;
+    stepButton;
+    collapseButton;
+    timer = null;
+    ticks = 0;
+    constructor(session, editorUrl = null) {
+        this.session = session;
+        this.editorUrl = editorUrl;
+        this.host.className = 'pix3-debug-overlay';
+        const root = this.host.attachShadow({ mode: 'open' });
+        this.root = root;
+        root.innerHTML = `<style>${STYLE}</style>
+<div class="panel" part="panel">
+  <header>
+    <span class="title">Pix3 debug</span>
+    <span class="fps">– fps</span>
+    <button type="button" data-action="pause" aria-pressed="false" title="Freeze the game (manual time mode)">Pause</button>
+    <button type="button" data-action="step" title="Advance one frame while paused" disabled>Step</button>
+    ${editorUrl ? '<button type="button" data-action="editor" title="Open this project in the Pix3 editor">Editor</button>' : ''}
+    <button type="button" data-action="collapse" title="Collapse">Hide</button>
+  </header>
+  <div class="body">
+    <canvas></canvas>
+    <div class="legend"><span><i style="background:${COLORS.logic}"></i>logic</span><span><i style="background:${COLORS.render}"></i>render</span><span><i style="background:${COLORS.other}"></i>other</span><span class="muted">lines: 16.7 / 33.3 ms</span></div>
+    <div class="sections"></div>
+    <section><button type="button" data-action="reset" title="Reset percentiles, long frames and the program count">Reset stats</button></section>
+  </div>
+</div>`;
+        const pick = (selector) => root.querySelector(selector);
+        this.panel = pick('.panel');
+        this.canvas = pick('canvas');
+        this.fps = pick('.fps');
+        this.sections = pick('.sections');
+        this.pauseButton = pick('[data-action="pause"]');
+        this.stepButton = pick('[data-action="step"]');
+        this.collapseButton = pick('[data-action="collapse"]');
+        root.addEventListener('click', this.onClick);
+        // Keep the game's own listeners (a tap-to-jump on `window`) out of the panel's clicks.
+        for (const type of ['pointerdown', 'pointerup', 'touchstart', 'touchend', 'wheel', 'keydown']) {
+            this.panel.addEventListener(type, event => event.stopPropagation());
+        }
+        this.setCollapsed(readCollapsed());
+    }
+    mount() {
+        document.body.appendChild(this.host);
+        this.render();
+        this.timer = setInterval(() => this.tick(), CHART_MS);
+    }
+    dispose() {
+        if (this.timer !== null)
+            clearInterval(this.timer);
+        this.timer = null;
+        this.host.remove();
+    }
+    /** The timer: the chart every tick; every {@link TEXT_EVERY}th, a new window and the text. */
+    tick() {
+        this.ticks += 1;
+        const withText = this.ticks % TEXT_EVERY === 0;
+        // Only the timer closes windows: a click must not cut one short (an empty window reads "–").
+        if (withText)
+            this.session.rollWindow();
+        if (!this.panel.classList.contains('collapsed'))
+            drawChart(this.canvas, this.session.ring);
+        if (withText)
+            this.render();
+    }
+    render() {
+        const snapshot = this.session.snapshot();
+        this.renderHeader(snapshot);
+        if (this.panel.classList.contains('collapsed'))
+            return;
+        drawChart(this.canvas, this.session.ring);
+        this.sections.innerHTML = renderSections(snapshot);
+    }
+    renderHeader(snapshot) {
+        const fps = snapshot.window.fps;
+        this.fps.textContent = snapshot.paused
+            ? 'paused'
+            : fps === null
+                ? '– fps'
+                : `${fps.toFixed(0)} fps`;
+        this.fps.className = `fps ${fps !== null && fps < 50 && !snapshot.paused ? 'warn' : ''}`;
+        this.pauseButton.textContent = snapshot.paused ? 'Resume' : 'Pause';
+        this.pauseButton.setAttribute('aria-pressed', String(snapshot.paused));
+        this.stepButton.disabled = !snapshot.paused;
+    }
+    onClick = (event) => {
+        const action = event.target
+            ?.closest('[data-action]')
+            ?.getAttribute('data-action');
+        switch (action) {
+            case 'pause':
+                if (this.session.paused)
+                    this.session.resume();
+                else
+                    this.session.pause();
+                break;
+            case 'step':
+                this.session.step();
+                break;
+            case 'reset':
+                this.session.resetStats();
+                break;
+            case 'editor':
+                if (this.editorUrl) {
+                    const button = this.root.querySelector('[data-action="editor"]');
+                    void openEditor(this.editorUrl).then(outcome => {
+                        if (outcome !== 'already-open')
+                            return;
+                        button.textContent = 'Editor is open';
+                        setTimeout(() => (button.textContent = 'Editor'), 3000);
+                    });
+                }
+                return;
+            case 'collapse':
+                this.setCollapsed(!this.panel.classList.contains('collapsed'));
+                break;
+            default:
+                return;
+        }
+        this.render();
+    };
+    setCollapsed(collapsed) {
+        this.panel.classList.toggle('collapsed', collapsed);
+        this.collapseButton.textContent = collapsed ? 'Show' : 'Hide';
+        this.collapseButton.title = collapsed ? 'Expand' : 'Collapse';
+        writeCollapsed(collapsed);
+    }
+}
+/** Stacked bars, oldest left: logic, render, then the rest of the frame (`dt` − work). */
+const drawChart = (canvas, ring) => {
+    const dpr = window.devicePixelRatio || 1;
+    const width = Math.max(1, Math.round(canvas.clientWidth * dpr));
+    const height = Math.max(1, Math.round(canvas.clientHeight * dpr));
+    if (canvas.width !== width)
+        canvas.width = width;
+    if (canvas.height !== height)
+        canvas.height = height;
+    const g = canvas.getContext('2d');
+    if (!g)
+        return;
+    g.clearRect(0, 0, width, height);
+    const y = (valueMs) => height - (Math.min(valueMs, CHART_CEILING_MS) / CHART_CEILING_MS) * height;
+    const bar = width / ring.capacity;
+    const offset = ring.capacity - ring.length;
+    for (let i = 0; i < ring.length; i += 1) {
+        const at = ring.indexOf(i);
+        const x = (offset + i) * bar;
+        const w = Math.max(1, bar - (bar > 2 ? 0.5 * dpr : 0));
+        const logic = ring.logicMs[at];
+        const render = ring.renderMs[at];
+        const frame = Math.max(ring.frameMs[at], logic + render);
+        g.fillStyle = COLORS.other;
+        g.fillRect(x, y(frame), w, height - y(frame));
+        g.fillStyle = COLORS.render;
+        g.fillRect(x, y(logic + render), w, y(logic) - y(logic + render));
+        g.fillStyle = COLORS.logic;
+        g.fillRect(x, y(logic), w, height - y(logic));
+        if (frame > LONG_FRAME_MS) {
+            g.fillStyle = COLORS.over;
+            g.fillRect(x, 0, w, 2 * dpr);
+        }
+    }
+    g.fillStyle = COLORS.grid;
+    for (const line of [1000 / 60, 1000 / 30])
+        g.fillRect(0, Math.round(y(line)), width, dpr);
+};
+const renderSections = (s) => {
+    const w = s.window;
+    const st = s.stability;
+    const parts = [];
+    parts.push(section('Frame', row('frame (avg)', ms(w.frameMs)) +
+        row('logic / render', `${ms(w.logicMs, 2)} / ${ms(w.renderMs, 2)}`) +
+        row('other (not the game)', ms(w.unaccountedMs)) +
+        row('rAF lateness', ms(w.rafLatenessMs, 2)) +
+        row('p50 / p95 / p99', `${ms(st.p50Ms, 0)} / ${ms(st.p95Ms, 0)} / ${ms(st.p99Ms, 0)}`) +
+        row(`> ${LONG_FRAME_MS.toFixed(0)} ms`, `${num(st.longCount)} of ${num(st.sampleCount)}${st.longPercent === null ? '' : ` (${st.longPercent.toFixed(1)}%)`}`, st.longPercent !== null && st.longPercent > 1 ? 'warn' : '') +
+        row('worst', ms(st.worstMs), st.worstMs !== null && st.worstMs > 50 ? 'bad' : '') +
+        row('frame #', num(s.frameNumber))));
+    if (w.activities.length > 0) {
+        parts.push(section('Activities (self, per frame)', w.activities
+            .slice(0, 8)
+            .map(activity => row(activity.label, ms(activity.ms, 2)))
+            .join('')));
+    }
+    const r = s.renderer;
+    parts.push(section('Renderer', r
+        ? row('draw calls', num(r.calls)) +
+            row('triangles', num(r.triangles)) +
+            row('geometries / textures', `${num(r.geometries)} / ${num(r.textures)}`) +
+            row('programs', `${num(r.programs)}${s.programsLinked > 0 ? ` (+${s.programsLinked} linked)` : ''}`, s.programsLinked > 0 ? 'warn' : '')
+        : '<div class="muted">no frame rendered yet</div>'));
+    const lf = s.longFrames;
+    parts.push(section('Long frames (browser)', lf.supported
+        ? row('count', num(lf.count), lf.count > 0 ? 'warn' : '') +
+            lf.worst
+                .map(frame => row(frame.script ?? 'no JS (GC, compositing, vsync)', ms(frame.durationMs, 0), frame.durationMs > 100 ? 'bad' : 'warn'))
+                .join('')
+        : '<div class="muted">not reported by this browser</div>'));
+    parts.push(section(`Audio (${s.audio.active})`, s.audio.playbacks.length > 0
+        ? s.audio.playbacks
+            .map(playback => row(playback.label, `${playback.bus}${playback.loop ? ' · loop' : ''} · ${(playback.elapsedMs / 1000).toFixed(1)} s`))
+            .join('')
+        : '<div class="muted">nothing playing</div>'));
+    parts.push(section(`Errors (${s.errors.count})`, s.errors.recent.length > 0
+        ? s.errors.recent
+            .slice(-4)
+            .reverse()
+            .map(error => `<div class="error">${escapeHtml(error.message)}${error.where ? `<small>${escapeHtml(error.where)}</small>` : ''}</div>`)
+            .join('')
+        : '<div class="muted">none</div>'));
+    if (s.game) {
+        let text;
+        try {
+            text = JSON.stringify(s.game.snapshot, null, 1) ?? 'null';
+        }
+        catch {
+            text = '(not JSON-serialisable)';
+        }
+        parts.push(section(`Game · ${s.game.name}`, `<pre>${escapeHtml(text.slice(0, 4000))}</pre>`));
+    }
+    const d = s.device;
+    parts.push(section('Device', row('scene', escapeHtml(s.scene ?? '–')) +
+        row('status', escapeHtml(s.status), s.status === 'failed' ? 'bad' : '') +
+        row('GPU', escapeHtml(d.gpu ?? '–')) +
+        row('screen / viewport', `${d.screen} / ${d.viewport} @${d.devicePixelRatio}x`) +
+        row('memory / cores', `${d.memoryGb === null ? '–' : `${d.memoryGb} GB`} / ${num(d.cores)}`) +
+        row('JS heap', s.heapMb === null ? '–' : `${s.heapMb.toFixed(1)} MB`)));
+    return parts.join('');
+};

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

@@ -0,0 +1,92 @@
+import { type RuntimeRendererStatsSnapshot } from '@pix3/runtime';
+import type { Pix3DebugContext } from './context';
+import { type DeviceInfo } from './device-info';
+import { FrameRing, type FrameStability, type FrameWindow } from './frame-stats';
+import { type LongFrameStats } from './long-frames';
+/**
+ * The debug mode's model, DOM-free: subscribes to the runner's frame stats, keeps the numbers the
+ * overlay draws, and owns the pause / step controls. `snapshot()` is also what
+ * `__PIX3_PLAYER__.debug.snapshot()` answers, so an agent reads the same numbers a human sees.
+ */
+interface DebugError {
+    readonly at: number;
+    readonly message: string;
+    /** `phase · node · component` for a script error, null for a page error. */
+    readonly where: string | null;
+}
+export interface DebugSnapshot {
+    readonly status: string;
+    readonly scene: string | null;
+    readonly frameNumber: number;
+    readonly paused: boolean;
+    /** The last closed window (≈0.5 s): FPS, the frame split, activities. */
+    readonly window: FrameWindow;
+    /** Since the session started or the last reset. */
+    readonly stability: FrameStability;
+    /** Counters of the last rendered frame. */
+    readonly renderer: RuntimeRendererStatsSnapshot | null;
+    /** WebGL programs linked since the session started or the last reset (each one a stall). */
+    readonly programsLinked: number;
+    readonly audio: {
+        readonly active: number;
+        readonly playbacks: readonly {
+            readonly label: string;
+            readonly bus: string;
+            readonly loop: boolean;
+            readonly elapsedMs: number;
+        }[];
+    };
+    readonly longFrames: LongFrameStats;
+    readonly heapMb: number | null;
+    readonly device: DeviceInfo;
+    readonly errors: {
+        readonly count: number;
+        readonly recent: readonly DebugError[];
+    };
+    /** The game's own `registerGameDebug` provider snapshot, when it registered one. */
+    readonly game: {
+        readonly name: string;
+        readonly snapshot: unknown;
+    } | null;
+}
+export declare class DebugSession {
+    private readonly context;
+    readonly ring: FrameRing;
+    private readonly histogram;
+    private readonly accumulator;
+    private readonly longFrames;
+    private window;
+    private renderer;
+    private wantRendererStats;
+    private programsAtReset;
+    private frameNumber;
+    private readonly errors;
+    private errorCount;
+    private pageErrorsSeen;
+    /** The time mode pause replaced, or null while the overlay has not paused the game. */
+    private pausedFrom;
+    private readonly disposers;
+    constructor(context: Pix3DebugContext);
+    start(): void;
+    dispose(): void;
+    /** Close the current averaging window (the overlay calls this at its text cadence). */
+    rollWindow(): void;
+    /** Forget the session's percentiles, long frames and program count; keep the errors. */
+    resetStats(): void;
+    get paused(): boolean;
+    /**
+     * Freeze the game in `manual` time mode rather than `SceneRunner.pause()`: a paused runner
+     * cannot `stepFrames`. Audio is muted by the mode (`muteAudio`), not suspended.
+     */
+    pause(): void;
+    resume(): void;
+    /** One tick at the paused mode's `fixedDeltaSec`; a no-op unless the overlay paused the game. */
+    step(): void;
+    snapshot(): DebugSnapshot;
+    private readonly onFrame;
+    private readonly onScriptError;
+    /** `__PIX3_PLAYER__.errors` (window errors, rejections, a failed boot), new ones only. */
+    private collectPageErrors;
+    private pushError;
+}
+export {};

package/dist/player/debug/session.js

@@ -0,0 +1,156 @@
+import { getGameDebug, registerScriptErrorSink, } from '@pix3/runtime';
+import { readDeviceInfo, readHeapMb } from './device-info';
+import { EMPTY_WINDOW, FrameIntervalHistogram, FrameRing, FrameWindowAccumulator, } from './frame-stats';
+import { LongFrameObserver } from './long-frames';
+const KEEP_ERRORS = 20;
+const SHOWN_PLAYBACKS = 6;
+export class DebugSession {
+    context;
+    ring = new FrameRing();
+    histogram = new FrameIntervalHistogram();
+    accumulator = new FrameWindowAccumulator();
+    longFrames = new LongFrameObserver();
+    window = EMPTY_WINDOW;
+    renderer = null;
+    wantRendererStats = true;
+    programsAtReset = null;
+    frameNumber = 0;
+    errors = [];
+    errorCount = 0;
+    pageErrorsSeen = 0;
+    /** The time mode pause replaced, or null while the overlay has not paused the game. */
+    pausedFrom = null;
+    disposers = [];
+    constructor(context) {
+        this.context = context;
+    }
+    start() {
+        this.disposers.push(this.context.runner.subscribeFrameStats(this.onFrame));
+        // The player registers no script-error sink of its own; the editor's lives in another page.
+        this.disposers.push(registerScriptErrorSink(this.onScriptError));
+        this.longFrames.start();
+        this.disposers.push(() => this.longFrames.stop());
+    }
+    dispose() {
+        if (this.pausedFrom)
+            this.resume();
+        for (const dispose of this.disposers.splice(0))
+            dispose();
+    }
+    /** Close the current averaging window (the overlay calls this at its text cadence). */
+    rollWindow() {
+        this.window = this.accumulator.close();
+        this.wantRendererStats = true;
+    }
+    /** Forget the session's percentiles, long frames and program count; keep the errors. */
+    resetStats() {
+        this.histogram.reset();
+        this.ring.clear();
+        this.longFrames.reset();
+        this.programsAtReset = this.renderer?.programs ?? null;
+    }
+    get paused() {
+        return this.pausedFrom !== null;
+    }
+    /**
+     * Freeze the game in `manual` time mode rather than `SceneRunner.pause()`: a paused runner
+     * cannot `stepFrames`. Audio is muted by the mode (`muteAudio`), not suspended.
+     */
+    pause() {
+        const runner = this.context.runner;
+        if (this.pausedFrom || !runner.running)
+            return;
+        const current = runner.getTimeMode();
+        if (current.mode === 'manual')
+            return; // the game drives its own ticks
+        this.pausedFrom = current;
+        runner.setTimeMode({ mode: 'manual', fixedDeltaSec: current.fixedDeltaSec, muteAudio: true });
+    }
+    resume() {
+        if (!this.pausedFrom)
+            return;
+        const previous = this.pausedFrom;
+        this.pausedFrom = null;
+        this.context.runner.setTimeMode(previous);
+    }
+    /** One tick at the paused mode's `fixedDeltaSec`; a no-op unless the overlay paused the game. */
+    step() {
+        if (this.pausedFrom)
+            this.context.runner.stepFrames(1);
+    }
+    snapshot() {
+        this.collectPageErrors();
+        const { audio, state } = this.context;
+        const playbacks = audio.getActivePlaybackSnapshot();
+        const programs = this.renderer?.programs ?? null;
+        if (programs !== null && this.programsAtReset === null)
+            this.programsAtReset = programs;
+        const provider = getGameDebug();
+        return {
+            status: state.status,
+            scene: state.scene,
+            frameNumber: this.frameNumber,
+            paused: this.paused,
+            window: this.window,
+            stability: this.histogram.snapshot(),
+            renderer: this.renderer,
+            programsLinked: programs === null ? 0 : programs - (this.programsAtReset ?? programs),
+            audio: {
+                active: playbacks.length,
+                playbacks: playbacks.slice(0, SHOWN_PLAYBACKS).map(playback => ({
+                    label: playback.label,
+                    bus: playback.bus,
+                    loop: playback.loop,
+                    elapsedMs: playback.elapsedMs,
+                })),
+            },
+            longFrames: this.longFrames.stats(),
+            heapMb: readHeapMb(),
+            device: readDeviceInfo(),
+            errors: { count: this.errorCount, recent: [...this.errors] },
+            game: provider ? { name: provider.name, snapshot: readGameSnapshot(provider) } : null,
+        };
+    }
+    onFrame = (sample) => {
+        this.frameNumber = sample.frameNumber;
+        const frameMs = sample.dt * 1000;
+        this.histogram.record(frameMs);
+        this.ring.push(sample.logicMs, sample.renderMs, frameMs);
+        this.accumulator.add(sample);
+        // The counters are reset at every tick's start, so only a tick that painted has them; one
+        // read per window, not per frame.
+        if (this.wantRendererStats && sample.renderMs > 0) {
+            this.wantRendererStats = false;
+            this.renderer = this.context.renderer.getStatsSnapshot();
+        }
+    };
+    onScriptError = (error) => {
+        const where = [error.phase, error.nodeName ?? error.nodeId, error.componentType]
+            .filter(Boolean)
+            .join(' · ');
+        this.pushError({ at: Date.now(), message: error.message, where });
+    };
+    /** `__PIX3_PLAYER__.errors` (window errors, rejections, a failed boot), new ones only. */
+    collectPageErrors() {
+        const errors = this.context.state.errors;
+        for (; this.pageErrorsSeen < errors.length; this.pageErrorsSeen += 1) {
+            this.pushError({ at: Date.now(), message: errors[this.pageErrorsSeen], where: null });
+        }
+    }
+    pushError(error) {
+        this.errorCount += 1;
+        this.errors.push(error);
+        if (this.errors.length > KEEP_ERRORS)
+            this.errors.shift();
+    }
+}
+const readGameSnapshot = (provider) => {
+    if (!provider.snapshot)
+        return null;
+    try {
+        return provider.snapshot();
+    }
+    catch (error) {
+        return { error: error instanceof Error ? error.message : String(error) };
+    }
+};

package/dist/player/dev/editor-link.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The "Pix3 editor" link over the game in dev (`virtual:pix3/dev`; not on `?clean`, not in a
+ * frame, not in a build). A second editor tab would open read-only (the writer lock), so the link
+ * first asks over a `BroadcastChannel` whether an editor of this dev server is open: if one
+ * answers, the page says so and tries to bring its opener forward; if none does, this tab becomes
+ * the editor. The editor answers in `packages/editor-core/src/host/editor-presence.ts`.
+ */
+/** Keep in step with `editor-presence.ts` in editor-core. */
+export declare const EDITOR_PRESENCE_CHANNEL = "pix3-editor-presence";
+export type OpenEditorOutcome = 'navigated' | 'already-open';
+/** True when an editor tab of this origin answers within {@link ANSWER_MS}. */
+export declare const isEditorOpen: (timeoutMs?: number) => Promise<boolean>;
+/** Go to the editor: this tab becomes it, unless one is already open. */
+export declare const openEditor: (editorUrl: string) => Promise<OpenEditorOutcome>;
+/** Mount the link; returns the teardown. Hidden for the rest of the tab's session by its close button. */
+export declare function mountEditorLink(editorUrl: string): () => void;