ugly-game 0.5.19 → 0.5.21

package/dist/index.d.ts

@@ -3,6 +3,7 @@ export * from './mat4';
 export * from './noise';
 export * from './moat';
 export * from './stateIR';
+export * from './telemetry';
 export * from './playtestIR';
 export * from './visualIR';
 export * from './gpuShadow';
@@ -10,3 +11,5 @@ export * from './input/resolve';
 export * from './input/browserBackend';
 export * from './input/ControlHints';
 export * from './input/TouchControls';
+export * from './loop/pageState';
+export * from './loop/gameLoop';

package/dist/index.js

@@ -5,6 +5,7 @@ export * from './mat4';
 export * from './noise';
 export * from './moat';
 export * from './stateIR';
+export * from './telemetry';
 export * from './playtestIR';
 export * from './visualIR';
 export * from './gpuShadow';
@@ -12,3 +13,5 @@ export * from './input/resolve';
 export * from './input/browserBackend';
 export * from './input/ControlHints';
 export * from './input/TouchControls';
+export * from './loop/pageState';
+export * from './loop/gameLoop';

package/dist/loop/gameLoop.d.ts

@@ -0,0 +1,47 @@
+import { type PageState, type PageTier } from './pageState';
+/** The three methods the loop needs to restore a networked sim after a pause. */
+export interface NetAdapter {
+    window: number;
+    catchUp(gapTicks: number): void;
+    resync(): void;
+}
+export interface ResumeInfo {
+    hiddenMs: number;
+    gapTicks: number;
+    tier: PageTier;
+}
+export interface FrameInfo {
+    tier: PageTier;
+    frame: number;
+    dt: number;
+    t: number;
+}
+export interface GameLoopOpts {
+    render: (info: FrameInfo) => void;
+    /** Render FPS per tier. Default { active: 60, blurred: 20, hidden: 0 }. */
+    gameFps?: {
+        active: number;
+        blurred: number;
+        hidden: number;
+    };
+    /** Fixed sim timestep + catch-up clamp. Default { fps: 60, maxCatchUpFrames: 6 }. */
+    sim?: {
+        fps: number;
+        maxCatchUpFrames: number;
+    };
+    /** Fixed-step sim callback. Omit if the sim lives elsewhere (e.g. a worker). */
+    tick?: (dt: number) => void;
+    /** Enables the default resume policy (catchUp vs resync). */
+    net?: NetAdapter;
+    /** Fully overrides the default resume policy. */
+    onResume?: (info: ResumeInfo) => void;
+    pageState?: PageState;
+    now?: () => number;
+    raf?: (cb: (t: number) => void) => number;
+    caf?: (id: number) => void;
+}
+export interface GameLoop {
+    stop(): void;
+    state(): PageTier;
+}
+export declare function runGameLoop(opts: GameLoopOpts): GameLoop;

package/dist/loop/gameLoop.js

@@ -0,0 +1,94 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// GAME LOOP — the one rAF loop a game hands its render (and optionally its sim) to.
+// It owns three things a hand-rolled loop keeps getting wrong:
+//   1. RENDER PACING by page tier — active 60 / blurred 20 / hidden 0 (overridable).
+//   2. A FIXED-STEP SIM accumulator (opt-in via `tick`) that advances on wall time
+//      while visible and FREEZES while hidden, with a catch-up clamp.
+//   3. SIM RESTORE on resume — the part games forget. Hand it a NetAdapter and it
+//      does the correct thing automatically: small gap → deterministic catch-up,
+//      large gap → snapshot resync. Override with onResume for anything bespoke.
+// A single-player game passes neither net nor onResume and still gets correct
+// catch-up clamping for free. Clock/rAF/pageState are injectable for tests.
+// ─────────────────────────────────────────────────────────────────────────────
+import { createPageState } from './pageState';
+const DEFAULT_GAME_FPS = { active: 60, blurred: 20, hidden: 0 };
+const DEFAULT_SIM = { fps: 60, maxCatchUpFrames: 6 };
+export function runGameLoop(opts) {
+    const gameFps = opts.gameFps ?? DEFAULT_GAME_FPS;
+    const sim = opts.sim ?? DEFAULT_SIM;
+    const now = opts.now ?? (() => performance.now());
+    const raf = opts.raf ?? ((cb) => requestAnimationFrame(cb));
+    const caf = opts.caf ??
+        ((id) => {
+            cancelAnimationFrame(id);
+        });
+    const page = opts.pageState ?? createPageState({ now });
+    const fixedDt = 1 / sim.fps; // seconds per sim tick
+    const maxCatchUp = sim.maxCatchUpFrames * fixedDt; // seconds
+    let handle = 0;
+    let last = -1; // ms of the previous rAF callback
+    let acc = 0; // sim accumulator (seconds)
+    let renderAcc = 0; // render accumulator (seconds)
+    let frame = 0;
+    let stopped = false;
+    page.onResumeFromHidden((hiddenMs) => {
+        // Reset frame timing so the first frame after resume carries no dt/step spike.
+        last = -1;
+        acc = 0;
+        renderAcc = 0;
+        const gapTicks = Math.round(hiddenMs / (1000 * fixedDt));
+        const info = { hiddenMs, gapTicks, tier: page.tier() };
+        if (opts.onResume)
+            opts.onResume(info);
+        else if (opts.net) {
+            if (gapTicks <= opts.net.window)
+                opts.net.catchUp(gapTicks);
+            else
+                opts.net.resync();
+        }
+    });
+    const loop = (t) => {
+        if (stopped)
+            return;
+        if (last < 0)
+            last = t;
+        const wallDt = (t - last) / 1000;
+        last = t;
+        const tier = page.tier();
+        // SIM: advance whenever not hidden; freeze while hidden.
+        if (opts.tick && tier !== 'hidden') {
+            acc += Math.min(wallDt, maxCatchUp);
+            while (acc >= fixedDt) {
+                opts.tick(fixedDt);
+                acc -= fixedDt;
+            }
+        }
+        // RENDER: gate to the tier's FPS. 0 ⇒ never render (also covers a hidden tab
+        // whose browser still fires the occasional rAF).
+        const fps = gameFps[tier];
+        if (fps > 0) {
+            renderAcc += wallDt;
+            const period = 1 / fps;
+            // Carry the remainder (subtract the period, don't reset) so exact frame
+            // boundaries fire deterministically instead of being lost to fp jitter. The
+            // epsilon absorbs the last ulp when wallDt lands right on the period.
+            if (renderAcc + 1e-9 >= period) {
+                renderAcc -= period;
+                if (renderAcc > period)
+                    renderAcc = 0; // shed backlog; never render twice per frame
+                opts.render({ tier, frame, dt: wallDt, t });
+                frame++;
+            }
+        }
+        handle = raf(loop);
+    };
+    handle = raf(loop);
+    return {
+        stop: () => {
+            stopped = true;
+            caf(handle);
+            page.stop();
+        },
+        state: () => page.tier(),
+    };
+}

package/dist/loop/pageState.d.ts

@@ -0,0 +1,17 @@
+export type PageTier = 'active' | 'blurred' | 'hidden';
+export interface PageStateTarget {
+    hidden(): boolean;
+    hasFocus(): boolean;
+    onVisibilityChange(cb: () => void): void;
+    offVisibilityChange(cb: () => void): void;
+}
+export interface PageStateDeps {
+    now?: () => number;
+    target?: PageStateTarget | null;
+}
+export interface PageState {
+    tier(): PageTier;
+    onResumeFromHidden(cb: (hiddenMs: number) => void): void;
+    stop(): void;
+}
+export declare function createPageState(deps?: PageStateDeps): PageState;

package/dist/loop/pageState.js

@@ -0,0 +1,62 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// PAGE STATE — "how present is this tab right now?" resolves the coarse tier that
+// drives frame pacing (active / blurred / hidden), and timestamps hidden spans so a
+// game can restore its sim on resume. requestAnimationFrame STOPS firing while a tab
+// is hidden, so a running loop cannot detect its own return — this module owns the
+// one visibilitychange listener that can. tier() polls hidden()/hasFocus() live, so
+// blur/focus need no listeners. The DOM is injected (defaults to the real document/
+// window) to keep it pure/testable, matching SharedClock's injected-clock style.
+// ─────────────────────────────────────────────────────────────────────────────
+function realTarget() {
+    if (typeof document === 'undefined' || typeof window === 'undefined')
+        return null;
+    return {
+        hidden: () => document.hidden,
+        hasFocus: () => document.hasFocus(),
+        onVisibilityChange: (cb) => {
+            document.addEventListener('visibilitychange', cb);
+        },
+        offVisibilityChange: (cb) => {
+            document.removeEventListener('visibilitychange', cb);
+        },
+    };
+}
+export function createPageState(deps = {}) {
+    const now = deps.now ?? (() => performance.now());
+    const target = deps.target === undefined ? realTarget() : deps.target;
+    const resumeCbs = [];
+    let hiddenAt = -1;
+    const tier = () => {
+        if (!target)
+            return 'active';
+        if (target.hidden())
+            return 'hidden';
+        return target.hasFocus() ? 'active' : 'blurred';
+    };
+    const onVisibility = () => {
+        if (!target)
+            return;
+        if (target.hidden()) {
+            if (hiddenAt < 0)
+                hiddenAt = now();
+        }
+        else if (hiddenAt >= 0) {
+            const hiddenMs = now() - hiddenAt;
+            hiddenAt = -1;
+            for (const cb of resumeCbs)
+                cb(hiddenMs);
+        }
+    };
+    if (target)
+        target.onVisibilityChange(onVisibility);
+    return {
+        tier,
+        onResumeFromHidden: (cb) => {
+            resumeCbs.push(cb);
+        },
+        stop: () => {
+            if (target)
+                target.offVisibilityChange(onVisibility);
+        },
+    };
+}

package/dist/telemetry.d.ts

@@ -0,0 +1,34 @@
+/** A registered provider: returns a JSON-able snapshot of some subsystem's state, evaluated lazily at report time. */
+export type SnapshotProvider = () => unknown;
+/** Register a lazy snapshot provider under `key`. Returns an unregister fn (useEffect-friendly). The provider is
+ *  only invoked when a report is actually assembled, so an expensive full-state serialize costs nothing otherwise. */
+export declare function registerSnapshotProvider(key: string, fn: SnapshotProvider): () => void;
+/** Run every registered provider (best-effort — a throwing provider is recorded as `{_error}`, not fatal). */
+export declare function collectSnapshots(): Record<string, unknown>;
+/** A compact, storable reference to a packed snapshot — goes into the report's `context` JSON. Either the gzip is
+ *  inlined (`gzB64`) or it was uploaded and only the `url` is kept. `bytes`/`gzBytes` let a viewer show the size. */
+export interface PackedSnapshot {
+    key: string;
+    gzip: true;
+    bytes: number;
+    gzBytes: number;
+    gzB64?: string;
+    url?: string;
+    truncated?: boolean;
+}
+export interface PackOpts {
+    /** gzip size (bytes) at/below which we INLINE as base64; above it we upload. Default 48000 (headroom under the
+     *  60KB keepalive-body cap once base64's ~1.37× expansion is applied). */
+    maxInlineBytes?: number;
+    /** Uploads the gzip blob to object storage and resolves to its URL. If absent, oversize payloads inline anyway. */
+    upload?: (gz: Uint8Array, meta: {
+        key: string;
+        bytes: number;
+        gzBytes: number;
+    }) => Promise<string>;
+}
+/** Serialize → gzip → inline if small (base64) else upload. Returns the compact reference to store in the report. */
+export declare function packSnapshot(key: string, snap: unknown, opts?: PackOpts): Promise<PackedSnapshot>;
+/** Inverse of packSnapshot for tooling: recover the original object from a PackedSnapshot. Inline payloads decode
+ *  locally; uploaded ones are fetched (pass a `fetchUrl` for non-browser contexts). Enables local-sim repro. */
+export declare function unpackSnapshot(ref: PackedSnapshot, fetchUrl?: (url: string) => Promise<Uint8Array>): Promise<unknown>;

package/dist/telemetry.js

@@ -0,0 +1,95 @@
+// ─────────────────────────────────────────────────────────────────────────────
+// ugly-game TELEMETRY ENRICH — attach a game's structured IR snapshot to a feedback / error report so a bug can be
+// LOCALLY REPRODUCED, not just described. Generic + engine-side: the app supplies the snapshot (typically an
+// AgentDebuggable.snapshot() carrying the full deterministic sim state) and, for big payloads, an uploader; this
+// module handles JSON serialization, gzip compression (CompressionStream — browser + Node ≥18), the
+// inline-vs-upload SIZE decision, and the compact reference you store in the report's `context`.
+//
+// Why gzip + upload: a full-state snapshot (edit overlays, entity lists, CA fields) routinely blows past the 60KB
+// keepalive-body line and bloats the single D1 report row. Gzip alone usually gets it back under the line (inline);
+// genuinely huge snapshots upload to object storage (R2) and the report keeps only the URL.
+// ─────────────────────────────────────────────────────────────────────────────
+const providers = new Map();
+/** Register a lazy snapshot provider under `key`. Returns an unregister fn (useEffect-friendly). The provider is
+ *  only invoked when a report is actually assembled, so an expensive full-state serialize costs nothing otherwise. */
+export function registerSnapshotProvider(key, fn) {
+    providers.set(key, fn);
+    return () => {
+        if (providers.get(key) === fn)
+            providers.delete(key);
+    };
+}
+/** Run every registered provider (best-effort — a throwing provider is recorded as `{_error}`, not fatal). */
+export function collectSnapshots() {
+    const out = {};
+    for (const [k, fn] of providers) {
+        try {
+            out[k] = fn();
+        }
+        catch (e) {
+            out[k] = { _error: String(e) };
+        }
+    }
+    return out;
+}
+async function gzipBytes(bytes) {
+    const cs = new CompressionStream('gzip');
+    const w = cs.writable.getWriter();
+    void w.write(bytes);
+    void w.close();
+    return new Uint8Array(await new Response(cs.readable).arrayBuffer());
+}
+async function gunzipBytes(bytes) {
+    const ds = new DecompressionStream('gzip');
+    const w = ds.writable.getWriter();
+    void w.write(bytes);
+    void w.close();
+    return new Uint8Array(await new Response(ds.readable).arrayBuffer());
+}
+function toB64(bytes) {
+    let s = '';
+    for (const b of bytes)
+        s += String.fromCharCode(b);
+    return btoa(s);
+}
+function fromB64(b64) {
+    const bin = atob(b64);
+    const out = new Uint8Array(bin.length);
+    for (let i = 0; i < bin.length; i++)
+        out[i] = bin.charCodeAt(i);
+    return out;
+}
+/** Serialize → gzip → inline if small (base64) else upload. Returns the compact reference to store in the report. */
+export async function packSnapshot(key, snap, opts = {}) {
+    const maxInline = opts.maxInlineBytes ?? 48_000;
+    const json = JSON.stringify(snap);
+    const raw = new TextEncoder().encode(json);
+    const gz = await gzipBytes(raw);
+    const truncated = !!snap && typeof snap === 'object' && '_truncated' in snap
+        ? true
+        : undefined;
+    const ref = {
+        key,
+        gzip: true,
+        bytes: raw.length,
+        gzBytes: gz.length,
+        truncated,
+    };
+    if (gz.length <= maxInline || !opts.upload)
+        return { ...ref, gzB64: toB64(gz) };
+    return {
+        ...ref,
+        url: await opts.upload(gz, { key, bytes: raw.length, gzBytes: gz.length }),
+    };
+}
+/** Inverse of packSnapshot for tooling: recover the original object from a PackedSnapshot. Inline payloads decode
+ *  locally; uploaded ones are fetched (pass a `fetchUrl` for non-browser contexts). Enables local-sim repro. */
+export async function unpackSnapshot(ref, fetchUrl = async (url) => new Uint8Array(await (await fetch(url)).arrayBuffer())) {
+    const gz = ref.gzB64
+        ? fromB64(ref.gzB64)
+        : ref.url
+            ? await fetchUrl(ref.url)
+            : new Uint8Array();
+    const raw = await gunzipBytes(gz);
+    return JSON.parse(new TextDecoder().decode(raw));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ugly-game",
-  "version": "0.5.19",
+  "version": "0.5.21",
   "type": "module",
   "exports": {
     ".": {