ugly-game 0.5.20 → 0.5.22

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';

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';

package/dist/loop/gameLoop.js

@@ -27,6 +27,7 @@ export function runGameLoop(opts) {
     const maxCatchUp = sim.maxCatchUpFrames * fixedDt; // seconds
     let handle = 0;
     let last = -1; // ms of the previous rAF callback
+    let lastRender = -1; // ms of the previous ACTUAL render (not every rAF fires one)
     let acc = 0; // sim accumulator (seconds)
     let renderAcc = 0; // render accumulator (seconds)
     let frame = 0;
@@ -34,6 +35,7 @@ export function runGameLoop(opts) {
     page.onResumeFromHidden((hiddenMs) => {
         // Reset frame timing so the first frame after resume carries no dt/step spike.
         last = -1;
+        lastRender = -1;
         acc = 0;
         renderAcc = 0;
         const gapTicks = Math.round(hiddenMs / (1000 * fixedDt));
@@ -76,7 +78,15 @@ export function runGameLoop(opts) {
                 renderAcc -= period;
                 if (renderAcc > period)
                     renderAcc = 0; // shed backlog; never render twice per frame
-                opts.render({ tier, frame, dt: wallDt, t });
+                // dt is time since the previous RENDER, not the previous rAF. On a display faster than the render cap (a
+                // 120Hz panel with a 60fps cap) rAF fires more often than we render, so `wallDt` (inter-rAF) is a fraction of
+                // the real inter-render time. A game that steps a fixed-step sim inside render off `info.dt` would then gain
+                // only that fraction of wall time and run slow (30 UPS on 120Hz). Report the true inter-render delta so the
+                // in-render accumulator advances real time. (A worker/`tick`-driven sim is immune either way — this keeps the
+                // main-thread render-driven path correct too.)
+                const renderDt = lastRender < 0 ? wallDt : (t - lastRender) / 1000;
+                lastRender = t;
+                opts.render({ tier, frame, dt: renderDt, t });
                 frame++;
             }
         }

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.20",
+  "version": "0.5.22",
   "type": "module",
   "exports": {
     ".": {
@@ -15,6 +15,14 @@
   "files": [
     "dist"
   ],
+  "scripts": {
+    "preinstall": "npx only-allow pnpm",
+    "build": "tsc -p tsconfig.json",
+    "lint": "ugly-app lint",
+    "lint:fix": "ugly-app lint --fix",
+    "pretty": "prettier --write .",
+    "prepublishOnly": "pnpm run pretty && ugly-app lint && tsc -p tsconfig.json"
+  },
   "dependencies": {
     "meshoptimizer": "^1.2.0"
   },
@@ -27,12 +35,5 @@
     "@webgpu/types": "^0.1.40",
     "prettier": "^3.9.5",
     "ugly-app": "^0.1.841"
-  },
-  "scripts": {
-    "preinstall": "npx only-allow pnpm",
-    "build": "tsc -p tsconfig.json",
-    "lint": "ugly-app lint",
-    "lint:fix": "ugly-app lint --fix",
-    "pretty": "prettier --write ."
   }
-}
+}