zx-kit 0.32.1 → 0.33.0

package/dist/debug.d.ts

@@ -0,0 +1,98 @@
+import { type SpectrumColor } from './palette.js';
+/**
+ * A snapshot of debug/telemetry numbers for one frame, produced by {@link sampleDebug}.
+ *
+ * Only what a 2D-canvas browser game can honestly measure: frame pacing and JS main-thread work.
+ * There is **no VRAM or GPU figure** — neither is observable from a Canvas2D context (that would
+ * need WebGL + driver hooks the browser does not expose). `cpuLoad` is the JS update+render cost
+ * against the frame budget, not the GPU's blit time. Resolution, JS heap, draw-call counters and
+ * estimated bitmap memory are planned for later slices.
+ */
+export interface DebugInfo {
+    /** Smoothed frames per second (exponential moving average). */
+    fps: number;
+    /** Duration of the last frame in milliseconds (delta between consecutive `beginFrame` calls). */
+    frameMs: number;
+    /** Measured update+render time in ms (between `beginFrame` and `endFrame`); `0` if `endFrame` was not called. */
+    workMs: number;
+    /** Target per-frame budget in ms (`1000 / targetFps`, e.g. `16.67` at 60 fps). */
+    budgetMs: number;
+    /** `workMs / budgetMs` (0..1+): JS main-thread load against the budget. Above `1` means the frame overran. */
+    cpuLoad: number;
+    /** Game-supplied fields merged into the snapshot — e.g. `{ mines: 12, level: 3 }`. */
+    custom: Record<string, string | number>;
+}
+/**
+ * Per-frame timing state. Create with {@link createDebugMonitor}, bracket each frame with
+ * {@link beginFrame} / {@link endFrame}, then read with {@link sampleDebug}.
+ * Holds no DOM references — safe to keep at module scope.
+ */
+export interface DebugMonitor {
+    /** Target frame rate used for `budgetMs` / `cpuLoad` (default `60`). */
+    targetFps: number;
+    /** EMA smoothing factor 0..1 applied to `fps` (default `0.1`; higher = snappier, noisier). */
+    smoothing: number;
+    /** Timestamp of the last `beginFrame`, or `null` before the first frame. */
+    lastTime: number | null;
+    /** Timestamp captured at `beginFrame`, used by `endFrame` to compute `workMs`. */
+    workStart: number;
+    /** Current smoothed fps. */
+    fps: number;
+    /** Last frame delta in ms. */
+    frameMs: number;
+    /** Last measured work time in ms. */
+    workMs: number;
+}
+/**
+ * Creates a frame-timing monitor.
+ *
+ * @param opts.targetFps - Frame rate the budget/load are measured against (default `60`)
+ * @param opts.smoothing - EMA factor 0..1 for the fps readout (default `0.1`)
+ *
+ * @example
+ * const dbg = createDebugMonitor()                       // 60 fps budget
+ * const dbg = createDebugMonitor({ targetFps: 50 })      // PAL
+ */
+export declare function createDebugMonitor(opts?: {
+    targetFps?: number;
+    smoothing?: number;
+}): DebugMonitor;
+/**
+ * Marks the start of a frame. Updates `frameMs` (delta since the previous `beginFrame`) and the
+ * smoothed `fps`, and starts the work-time clock for {@link endFrame}.
+ * Call once at the top of your `requestAnimationFrame` loop.
+ *
+ * @param now - Timestamp in ms (default `performance.now()`); pass the rAF timestamp for accuracy.
+ */
+export declare function beginFrame(m: DebugMonitor, now?: number): void;
+/**
+ * Marks the end of the frame's JS work (after update + render). Sets `workMs` to the time since
+ * {@link beginFrame}. Optional — skip it and `workMs` / `cpuLoad` stay `0`.
+ *
+ * @param now - Timestamp in ms (default `performance.now()`).
+ */
+export declare function endFrame(m: DebugMonitor, now?: number): void;
+/**
+ * Reads the current numbers as a fresh {@link DebugInfo}. Merge game-specific fields via `custom`.
+ *
+ * @example
+ * const info = sampleDebug(dbg, { mines: mineCount, level })
+ */
+export declare function sampleDebug(m: DebugMonitor, custom?: Record<string, string | number>): DebugInfo;
+/**
+ * Draws a small Spectrum-style debug overlay: `FPS` + frame ms, then `CPU %` (only when work time
+ * was measured), then one line per `custom` field. Lines are `CELL`-spaced down from `(x, y)`.
+ *
+ * The game owns the toggle key and placement — this is just a convenience renderer over
+ * {@link drawText}.
+ *
+ * @param x     - Left edge in game pixels (default `1`)
+ * @param y     - Top edge in game pixels (default `1`)
+ * @param ink   - Text colour (default `C.B_YELLOW`)
+ * @param paper - Background colour for readability (default `C.BLACK`)
+ *
+ * @example
+ * if (showDebug) drawDebugOverlay(ctx, sampleDebug(dbg, { mines }))
+ */
+export declare function drawDebugOverlay(ctx: CanvasRenderingContext2D, info: DebugInfo, x?: number, y?: number, ink?: SpectrumColor, paper?: SpectrumColor): void;
+//# sourceMappingURL=debug.d.ts.map

package/dist/debug.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.d.ts","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,aAAa,EAAE,MAAM,cAAc,CAAA;AAG1D;;;;;;;;GAQG;AACH,MAAM,WAAW,SAAS;IACxB,+DAA+D;IAC/D,GAAG,EAAE,MAAM,CAAA;IACX,iGAAiG;IACjG,OAAO,EAAE,MAAM,CAAA;IACf,iHAAiH;IACjH,MAAM,EAAE,MAAM,CAAA;IACd,kFAAkF;IAClF,QAAQ,EAAE,MAAM,CAAA;IAChB,8GAA8G;IAC9G,OAAO,EAAE,MAAM,CAAA;IACf,sFAAsF;IACtF,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,CAAA;CACxC;AAED;;;;GAIG;AACH,MAAM,WAAW,YAAY;IAC3B,wEAAwE;IACxE,SAAS,EAAE,MAAM,CAAA;IACjB,8FAA8F;IAC9F,SAAS,EAAE,MAAM,CAAA;IACjB,4EAA4E;IAC5E,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,kFAAkF;IAClF,SAAS,EAAE,MAAM,CAAA;IACjB,4BAA4B;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,8BAA8B;IAC9B,OAAO,EAAE,MAAM,CAAA;IACf,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAChC,IAAI,GAAE;IAAE,SAAS,CAAC,EAAE,MAAM,CAAC;IAAC,SAAS,CAAC,EAAE,MAAM,CAAA;CAAO,GACpD,YAAY,CAUd;AAED;;;;;;GAMG;AACH,wBAAgB,UAAU,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,GAAE,MAA0B,GAAG,IAAI,CASjF;AAED;;;;;GAKG;AACH,wBAAgB,QAAQ,CAAC,CAAC,EAAE,YAAY,EAAE,GAAG,GAAE,MAA0B,GAAG,IAAI,CAE/E;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CACzB,CAAC,EAAE,YAAY,EACf,MAAM,GAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAM,GAC3C,SAAS,CAUX;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,gBAAgB,CAC9B,GAAG,EAAE,wBAAwB,EAC7B,IAAI,EAAE,SAAS,EACf,CAAC,GAAE,MAAU,EACb,CAAC,GAAE,MAAU,EACb,GAAG,GAAE,aAA0B,EAC/B,KAAK,GAAE,aAAuB,GAC7B,IAAI,CAON"}

package/dist/debug.js

@@ -0,0 +1,92 @@
+import { C, CELL } from './palette.js';
+import { drawText } from './renderer.js';
+/**
+ * Creates a frame-timing monitor.
+ *
+ * @param opts.targetFps - Frame rate the budget/load are measured against (default `60`)
+ * @param opts.smoothing - EMA factor 0..1 for the fps readout (default `0.1`)
+ *
+ * @example
+ * const dbg = createDebugMonitor()                       // 60 fps budget
+ * const dbg = createDebugMonitor({ targetFps: 50 })      // PAL
+ */
+export function createDebugMonitor(opts = {}) {
+    return {
+        targetFps: opts.targetFps ?? 60,
+        smoothing: opts.smoothing ?? 0.1,
+        lastTime: null,
+        workStart: 0,
+        fps: 0,
+        frameMs: 0,
+        workMs: 0,
+    };
+}
+/**
+ * Marks the start of a frame. Updates `frameMs` (delta since the previous `beginFrame`) and the
+ * smoothed `fps`, and starts the work-time clock for {@link endFrame}.
+ * Call once at the top of your `requestAnimationFrame` loop.
+ *
+ * @param now - Timestamp in ms (default `performance.now()`); pass the rAF timestamp for accuracy.
+ */
+export function beginFrame(m, now = performance.now()) {
+    if (m.lastTime !== null) {
+        m.frameMs = now - m.lastTime;
+        const inst = m.frameMs > 0 ? 1000 / m.frameMs : 0;
+        // First real sample primes directly; afterwards apply EMA smoothing.
+        m.fps = m.fps === 0 ? inst : m.fps + m.smoothing * (inst - m.fps);
+    }
+    m.lastTime = now;
+    m.workStart = now;
+}
+/**
+ * Marks the end of the frame's JS work (after update + render). Sets `workMs` to the time since
+ * {@link beginFrame}. Optional — skip it and `workMs` / `cpuLoad` stay `0`.
+ *
+ * @param now - Timestamp in ms (default `performance.now()`).
+ */
+export function endFrame(m, now = performance.now()) {
+    m.workMs = Math.max(0, now - m.workStart);
+}
+/**
+ * Reads the current numbers as a fresh {@link DebugInfo}. Merge game-specific fields via `custom`.
+ *
+ * @example
+ * const info = sampleDebug(dbg, { mines: mineCount, level })
+ */
+export function sampleDebug(m, custom = {}) {
+    const budgetMs = m.targetFps > 0 ? 1000 / m.targetFps : 0;
+    return {
+        fps: m.fps,
+        frameMs: m.frameMs,
+        workMs: m.workMs,
+        budgetMs,
+        cpuLoad: budgetMs > 0 ? m.workMs / budgetMs : 0,
+        custom,
+    };
+}
+/**
+ * Draws a small Spectrum-style debug overlay: `FPS` + frame ms, then `CPU %` (only when work time
+ * was measured), then one line per `custom` field. Lines are `CELL`-spaced down from `(x, y)`.
+ *
+ * The game owns the toggle key and placement — this is just a convenience renderer over
+ * {@link drawText}.
+ *
+ * @param x     - Left edge in game pixels (default `1`)
+ * @param y     - Top edge in game pixels (default `1`)
+ * @param ink   - Text colour (default `C.B_YELLOW`)
+ * @param paper - Background colour for readability (default `C.BLACK`)
+ *
+ * @example
+ * if (showDebug) drawDebugOverlay(ctx, sampleDebug(dbg, { mines }))
+ */
+export function drawDebugOverlay(ctx, info, x = 1, y = 1, ink = C.B_YELLOW, paper = C.BLACK) {
+    const lines = [`${Math.round(info.fps)} FPS ${info.frameMs.toFixed(1)}ms`];
+    if (info.workMs > 0)
+        lines.push(`CPU ${Math.round(info.cpuLoad * 100)}%`);
+    for (const key of Object.keys(info.custom))
+        lines.push(`${key} ${info.custom[key]}`);
+    for (let i = 0; i < lines.length; i++) {
+        drawText(ctx, lines[i], x, y + i * CELL, ink, paper);
+    }
+}
+//# sourceMappingURL=debug.js.map

package/dist/debug.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"debug.js","sourceRoot":"","sources":["../src/debug.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -22,4 +22,5 @@ export * from './attrscreen.js';
 export * from './monoscreen.js';
 export * from './music.js';
 export * from './presentation.js';
+export * from './debug.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA"}

package/dist/index.js

@@ -22,4 +22,5 @@ export * from './attrscreen.js';
 export * from './monoscreen.js';
 export * from './music.js';
 export * from './presentation.js';
+export * from './debug.js';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,cAAc,CAAA;AAC5B,cAAc,SAAS,CAAA;AACvB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,YAAY,CAAA;AAC1B,cAAc,SAAS,CAAA;AACvB,cAAc,cAAc,CAAA;AAC5B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,aAAa,CAAA;AAC3B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,UAAU,CAAA;AACxB,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,YAAY,CAAA;AAC1B,cAAc,WAAW,CAAA;AACzB,cAAc,WAAW,CAAA;AACzB,cAAc,eAAe,CAAA;AAC7B,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,YAAY,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "zx-kit",
-  "version": "0.32.1",
+  "version": "0.33.0",
   "repository": {
     "type": "git",
     "url": "https://github.com/zrebec/zx-kit.git"