@pix3/vite-plugin 0.0.0-stage → 2.0.0-alpha.1

package/dist/module-paths.js

@@ -0,0 +1,32 @@
+import { realpathSync } from 'node:fs';
+import { isAbsolute, relative, sep } from 'node:path';
+/** A module id without its query (`/a/b.ts?v=1` → `/a/b.ts`). */
+export const fileOf = (id) => id.split('?')[0];
+/** A platform path with `/` separators. */
+export const posixPath = (path) => path.split(sep).join('/');
+/** `file` relative to `dir`, `/`-separated, when it lies strictly inside `dir`; else null. */
+export const relativeInside = (dir, file) => {
+    const rel = relative(dir, file);
+    return rel !== '' && !rel.startsWith('..') && !isAbsolute(rel) ? posixPath(rel) : null;
+};
+export const isUnder = (file, dir) => dir !== null && relativeInside(dir, file) !== null;
+const realPaths = new Map();
+/**
+ * The real path of a module id (query dropped; the id itself when it is not a file), cached. The
+ * runtime's `src/` is a real path, and module ids are not always (`resolve.preserveSymlinks`, a
+ * linked workspace): comparing the two as written would silently strip nothing.
+ */
+export const realFileOf = (id) => {
+    const file = fileOf(id);
+    let real = realPaths.get(file);
+    if (real === undefined) {
+        try {
+            real = realpathSync.native(file);
+        }
+        catch {
+            real = file;
+        }
+        realPaths.set(file, real);
+    }
+    return real;
+};

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;
+}