@caperjs/core 0.6.0 → 0.7.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@caperjs/core",
-  "version": "0.6.0",
+  "version": "0.7.0",
   "title": "Caper",
   "description": "An opinionated HTML game framework built on PixiJS v8",
   "bin": {
@@ -98,7 +98,7 @@
   "peerDependencies": {
     "@pixi/sound": "^6.0.1",
     "gsap": "^3.15.0",
-    "pixi.js": "8.19.0",
+    "pixi.js": "8.20.0",
     "vite": "^8.0.7",
     "workbox-window": "^7.4.0"
   },
@@ -117,7 +117,7 @@
     "npm-run-all": "^4.1.5",
     "oxc-parser": "^0.124.0",
     "pixi-filters": "^6.1.2",
-    "pixi.js": "8.19.0",
+    "pixi.js": "8.20.0",
     "prettier": "^3.2.5",
     "rimraf": "^5.0.5",
     "shelljs": "^0.8.5",

package/src/core/Application.ts

@@ -66,6 +66,7 @@ import { IFullScreenPlugin } from '../plugins/FullScreenPlugin';
 import { type IGSAPPlugin } from '../plugins/GSAPPlugin';
 import { ILookupPlugin } from '../plugins/LookupPlugin';
 import { ITimerPlugin } from '../plugins/TimerPlugin';
+import { shouldEnableScreenDebug } from '../plugins/screenDebugFlag';
 import { Signal } from '../signals';
 
 type App = AppTypeOverrides['App'];
@@ -1014,6 +1015,13 @@ export class Application extends PIXIPApplication implements IApplication {
         namedExport: 'StatsPlugin',
       });
     }
+    if (shouldEnableScreenDebug()) {
+      await this.loadPlugin({
+        id: 'screenDebug',
+        module: () => import('../plugins/ScreenDebugPlugin'),
+        namedExport: 'ScreenDebugPlugin',
+      });
+    }
     if (this.config.useVoiceover) {
       await this.loadPlugin({
         id: 'voiceover',

package/src/plugins/ScreenDebugPlugin.test.ts

@@ -0,0 +1,61 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+vi.mock('../core', () => ({ coreFunctionRegistry: {}, coreSignalRegistry: {} }));
+vi.mock('../core/Application', () => ({
+  Application: {
+    getInstance: () => ({
+      renderer: { canvas: null, width: 320, height: 480, resolution: 1 },
+      size: { width: 320, height: 480 },
+      resizer: { scale: 1, safeArea: { top: 0, right: 0, bottom: 0, left: 0 } },
+    }),
+  },
+}));
+
+import { ScreenDebugPlugin } from './ScreenDebugPlugin';
+
+describe('ScreenDebugPlugin', () => {
+  let plugin: ScreenDebugPlugin;
+
+  beforeEach(() => {
+    vi.useFakeTimers();
+    plugin = new ScreenDebugPlugin();
+  });
+
+  afterEach(() => {
+    plugin.destroy();
+    vi.useRealTimers();
+    document.querySelectorAll('[data-caper-screen-debug]').forEach((node) => node.remove());
+  });
+
+  it('appends the overlay and populates metrics on a tick', () => {
+    plugin.initialize();
+    expect(document.querySelectorAll('[data-caper-screen-debug]')).toHaveLength(3);
+
+    vi.advanceTimersByTime(500);
+
+    const panel = document.querySelector('[data-caper-screen-debug="panel"]');
+    expect(panel?.textContent).toContain('inner ');
+    expect(panel?.textContent).toContain('standalone ');
+  });
+
+  it('repopulates the panel from the interval tick, not just the initial call', () => {
+    plugin.initialize();
+    const panel = document.querySelector('[data-caper-screen-debug="panel"]')!;
+    panel.textContent = '';
+
+    vi.advanceTimersByTime(500);
+
+    expect(panel.textContent).toContain('inner ');
+  });
+
+  it('removes every overlay node and clears its interval on destroy', () => {
+    const clearInterval = vi.spyOn(window, 'clearInterval');
+    plugin.initialize();
+
+    plugin.destroy();
+
+    expect(document.querySelectorAll('[data-caper-screen-debug]')).toHaveLength(0);
+    expect(clearInterval).toHaveBeenCalledOnce();
+    expect(vi.getTimerCount()).toBe(0);
+  });
+});

package/src/plugins/ScreenDebugPlugin.ts

@@ -0,0 +1,174 @@
+import { Plugin } from './Plugin';
+
+type TimelineEntry = { t: number; type: string; innerH: number; vvH: number };
+
+export class ScreenDebugPlugin extends Plugin {
+  public readonly id = 'screenDebug';
+
+  private _panel: HTMLDivElement | null = null;
+  private _visibleBottom: HTMLDivElement | null = null;
+  private _canvasBottom: HTMLDivElement | null = null;
+  private _safeAreaProbe: HTMLDivElement | null = null;
+  private _startedAt = 0;
+  private _timeline: TimelineEntry[] = [];
+  private _initialVvH = 0;
+
+  public initialize(): void {
+    if (typeof document === 'undefined') {
+      return;
+    }
+
+    this._startedAt = performance.now();
+    this._initialVvH = window.visualViewport?.height ?? window.innerHeight;
+
+    this._panel = document.createElement('div');
+    this._panel.dataset.caperScreenDebug = 'panel';
+    this._panel.style.cssText =
+      'position:fixed;top:8px;left:8px;z-index:999999;pointer-events:none;font:10px/1.4 monospace;' +
+      'color:#9f9;background:rgba(0,0,0,.75);padding:6px 8px;border-radius:4px;max-width:86vw;white-space:pre;';
+    this._visibleBottom = this._makeMarker('red', 'visible-bottom');
+    this._canvasBottom = this._makeMarker('cyan', 'canvas-bottom');
+    document.body.append(this._panel, this._visibleBottom, this._canvasBottom);
+
+    this.listen(window, 'resize', () => this._onViewportEvent('resize'));
+    this.listen(window, 'orientationchange', () => this._onViewportEvent('orientationchange'));
+    if (window.visualViewport) {
+      this.listen(window.visualViewport, 'resize', () => this._onViewportEvent('vv.resize'));
+    }
+
+    const interval = window.setInterval(() => this._update(), 500);
+    this.addDisposer(
+      () => window.clearInterval(interval),
+      () => {
+        this._panel?.remove();
+        this._visibleBottom?.remove();
+        this._canvasBottom?.remove();
+        this._safeAreaProbe?.remove();
+        this._panel = this._visibleBottom = this._canvasBottom = this._safeAreaProbe = null;
+      },
+    );
+    this._update();
+  }
+
+  private _makeMarker(color: string, name: string): HTMLDivElement {
+    const marker = document.createElement('div');
+    marker.dataset.caperScreenDebug = name;
+    marker.style.cssText =
+      `position:fixed;left:0;width:100%;height:2px;background:${color};` +
+      'z-index:999999;pointer-events:none;';
+    return marker;
+  }
+
+  private _onViewportEvent(type: string): void {
+    const innerH = window.innerHeight;
+    const vvH = window.visualViewport?.height ?? innerH;
+    this._timeline.push({ t: performance.now() - this._startedAt, type, innerH, vvH });
+    if (this._timeline.length > 20) {
+      this._timeline.shift();
+    }
+    this._update();
+  }
+
+  private _update(): void {
+    if (!this._panel || !this._visibleBottom || !this._canvasBottom) {
+      return;
+    }
+
+    const vv = window.visualViewport;
+    const canvas = this._getCanvas();
+    const canvasRect = canvas?.getBoundingClientRect();
+    const safeArea = this._measureSafeAreaCssPx();
+    const renderer = this._getRenderer();
+    const appSize = this._getAppSize();
+    const resizer = this._getResizer();
+    const r = (n: number) => Math.round(n * 10) / 10;
+    const viewportUnits = ['dvh', 'svh', 'lvh', 'vh'].map((unit) => `${unit} ${r(this._measureViewportUnit(unit))}`);
+    const events = this._timeline.map((event, index) => {
+      const prior = this._timeline[index - 1];
+      return `+${Math.round(event.t)}ms ${event.type} ${r(prior?.vvH ?? this._initialVvH)}→${r(event.vvH)}`;
+    });
+
+    this._panel.textContent = [
+      `inner ${window.innerWidth}x${window.innerHeight}`,
+      `client ${document.documentElement.clientHeight}`,
+      `vv ${vv ? `${r(vv.width)}x${r(vv.height)} scale ${vv.scale} offsetTop ${r(vv.offsetTop)}` : 'n/a'}`,
+      ...viewportUnits,
+      `screen ${window.screen.width}x${window.screen.height}`,
+      `dpr ${window.devicePixelRatio}`,
+      `standalone ${window.matchMedia('(display-mode: standalone)').matches}`,
+      `env ${safeArea.top},${safeArea.right},${safeArea.bottom},${safeArea.left}`,
+      `canvas ${canvasRect ? `top ${r(canvasRect.top)} bottom ${r(canvasRect.bottom)} height ${r(canvasRect.height)}` : 'n/a'} style ${canvas?.style.height || 'n/a'}`,
+      `renderer ${renderer ? `${renderer.width}x${renderer.height} resolution ${renderer.resolution}` : 'n/a'}`,
+      `app.size ${appSize ? `${appSize.width}x${appSize.height}` : 'n/a'}`,
+      `resizer ${resizer ? `scale ${Math.round(resizer.scale * 1000) / 1000} safeArea ${JSON.stringify(resizer.safeArea)}` : 'n/a'}`,
+      ...events,
+    ].join('\n');
+
+    this._visibleBottom.style.top = `${(vv ? vv.offsetTop + vv.height : window.innerHeight) - 2}px`;
+    if (canvasRect) {
+      this._canvasBottom.style.top = `${canvasRect.bottom - 2}px`;
+      this._canvasBottom.style.display = 'block';
+    } else {
+      this._canvasBottom.style.display = 'none';
+    }
+  }
+
+  private _measureViewportUnit(unit: string): number {
+    const probe = document.createElement('div');
+    probe.style.cssText = `position:fixed;height:100${unit};visibility:hidden;pointer-events:none;`;
+    document.body.appendChild(probe);
+    const height = probe.getBoundingClientRect().height;
+    probe.remove();
+    return height;
+  }
+
+  private _measureSafeAreaCssPx(): { top: number; right: number; bottom: number; left: number } {
+    if (!this._safeAreaProbe) {
+      this._safeAreaProbe = document.createElement('div');
+      this._safeAreaProbe.style.cssText =
+        'position:fixed;top:0;left:0;width:0;height:0;visibility:hidden;pointer-events:none;' +
+        'padding-top:env(safe-area-inset-top, 0px);padding-right:env(safe-area-inset-right, 0px);' +
+        'padding-bottom:env(safe-area-inset-bottom, 0px);padding-left:env(safe-area-inset-left, 0px);';
+      document.body.appendChild(this._safeAreaProbe);
+    }
+    const style = getComputedStyle(this._safeAreaProbe);
+    return {
+      top: parseFloat(style.paddingTop) || 0,
+      right: parseFloat(style.paddingRight) || 0,
+      bottom: parseFloat(style.paddingBottom) || 0,
+      left: parseFloat(style.paddingLeft) || 0,
+    };
+  }
+
+  private _getCanvas(): HTMLCanvasElement | null {
+    try {
+      return (this.app.renderer?.canvas as HTMLCanvasElement | undefined) ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  private _getRenderer(): { width: number; height: number; resolution: number } | null {
+    try {
+      return this.app.renderer ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  private _getAppSize(): { width: number; height: number } | null {
+    try {
+      return this.app.size ?? null;
+    } catch {
+      return null;
+    }
+  }
+
+  private _getResizer(): { scale: number; safeArea: unknown } | null {
+    try {
+      return this.app.resizer ?? null;
+    } catch {
+      return null;
+    }
+  }
+}

package/src/plugins/index.ts

@@ -13,6 +13,8 @@ export * from './LookupPlugin';
 export * from './Plugin';
 export * from './PopupManagerPlugin';
 export * from './ResizerPlugin';
+export * from './ScreenDebugPlugin';
+export * from './screenDebugFlag';
 export * from './SceneManagerPlugin';
 export * from './TimerPlugin';
 export * from './WebEventsPlugin';

package/src/plugins/screenDebugFlag.test.ts

@@ -0,0 +1,45 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import { shouldEnableScreenDebug } from './screenDebugFlag';
+
+describe('shouldEnableScreenDebug', () => {
+  beforeEach(() => {
+    window.history.replaceState({}, '', '/');
+    window.localStorage.clear();
+  });
+
+  afterEach(() => {
+    vi.restoreAllMocks();
+    window.history.replaceState({}, '', '/');
+    window.localStorage.clear();
+  });
+
+  it('enables and persists from the query string', () => {
+    window.history.replaceState({}, '', '/?caper-screen-debug=1');
+    expect(shouldEnableScreenDebug()).toBe(true);
+    expect(window.localStorage.getItem('caper:screen-debug')).toBe('1');
+  });
+
+  it('disables and clears persistence from the query string', () => {
+    window.localStorage.setItem('caper:screen-debug', '1');
+    window.history.replaceState({}, '', '/?caper-screen-debug=0');
+    expect(shouldEnableScreenDebug()).toBe(false);
+    expect(window.localStorage.getItem('caper:screen-debug')).toBeNull();
+  });
+
+  it('enables from a persisted key without a query value', () => {
+    window.localStorage.setItem('caper:screen-debug', '1');
+    expect(shouldEnableScreenDebug()).toBe(true);
+  });
+
+  it('stays disabled without a query value or persisted key', () => {
+    expect(shouldEnableScreenDebug()).toBe(false);
+  });
+
+  it('falls back to the query value when localStorage throws', () => {
+    vi.spyOn(Storage.prototype, 'setItem').mockImplementation(() => {
+      throw new Error('unavailable');
+    });
+    window.history.replaceState({}, '', '/?caper-screen-debug=true');
+    expect(shouldEnableScreenDebug()).toBe(true);
+  });
+});

package/src/plugins/screenDebugFlag.ts

@@ -0,0 +1,26 @@
+const queryKey = 'caper-screen-debug';
+const storageKey = 'caper:screen-debug';
+
+export function shouldEnableScreenDebug(): boolean {
+  if (typeof window === 'undefined') {
+    return false;
+  }
+
+  const value = new URLSearchParams(window.location.search).get(queryKey);
+  const enabledByQuery = value === '1' || value === 'true';
+  const disabledByQuery = value === '0' || value === 'false';
+
+  try {
+    if (enabledByQuery) {
+      window.localStorage.setItem(storageKey, '1');
+      return true;
+    }
+    if (disabledByQuery) {
+      window.localStorage.removeItem(storageKey);
+      return false;
+    }
+    return window.localStorage.getItem(storageKey) === '1';
+  } catch {
+    return enabledByQuery;
+  }
+}

package/src/version.ts

@@ -1,3 +1,3 @@
 // This file is auto-generated during the build process.
-export const version: string = '0.6.0';
-export const pixiVersion: string = '8.19.0';
+export const version: string = '0.7.0';
+export const pixiVersion: string = '8.20.0';