@bloopjs/web 0.0.56 → 0.0.58

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloopjs/web",
-  "version": "0.0.56",
+  "version": "0.0.58",
   "author": "Neil Sarkar",
   "type": "module",
   "repository": {
@@ -33,8 +33,8 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@bloopjs/bloop": "0.0.56",
-    "@bloopjs/engine": "0.0.56",
+    "@bloopjs/bloop": "0.0.58",
+    "@bloopjs/engine": "0.0.58",
     "@preact/signals": "^1.3.1",
     "partysocket": "^1.1.6",
     "preact": "^10.25.4"

package/src/App.ts

@@ -7,6 +7,7 @@ import {
 } from "./netcode/broker";
 import { logger } from "./netcode/logs.ts";
 import { DebugUi, type DebugUiOptions } from "./debugui/mod.ts";
+import { debugState, triggerHmrFlash } from "./debugui/state.ts";
 
 export type StartOptions = {
   /** A bloop game instance */
@@ -130,6 +131,8 @@ export class App {
   beforeFrame: ReturnType<typeof createListener> = createListener<[number]>();
   /** Event listeners for after a frame is processed */
   afterFrame: ReturnType<typeof createListener> = createListener<[number]>();
+  /** Event listeners for HMR events */
+  onHmr: ReturnType<typeof createListener> = createListener<[HmrEvent]>();
 
   /** Subscribe to the browser events and start the render loop */
   subscribe(): void {
@@ -208,8 +211,38 @@ export class App {
     };
     window.addEventListener("keydown", playbarHotkeys);
 
+    // FPS calculation
+    let fpsFrames = 0;
+    let fpsLastTime = performance.now();
+
     const frame = () => {
-      this.sim.step(performance.now() - this.#now);
+      const stepStart = performance.now();
+      const ticks = this.sim.step(stepStart - this.#now);
+
+      // Update debug metrics only when we actually ran simulation
+      if (ticks > 0) {
+        const stepEnd = performance.now();
+        debugState.frameTime.value = stepEnd - stepStart;
+        debugState.frameNumber.value = this.sim.time.frame;
+
+        // Measure snapshot size when debug UI is visible (letterboxed mode)
+        if (debugState.layoutMode.value === "letterboxed") {
+          const bag = this.game.bag;
+          if (bag) {
+            debugState.snapshotSize.value = JSON.stringify(bag).length;
+          }
+        }
+
+        // Calculate FPS every second
+        fpsFrames++;
+        const elapsed = stepEnd - fpsLastTime;
+        if (elapsed >= 1000) {
+          debugState.fps.value = Math.round((fpsFrames * 1000) / elapsed);
+          fpsFrames = 0;
+          fpsLastTime = stepEnd;
+        }
+      }
+
       if (!this.sim.isPaused) {
         try {
           this.afterFrame.notify(this.sim.time.frame);
@@ -245,6 +278,7 @@ export class App {
     this.sim.unmount();
     this.beforeFrame.unsubscribeAll();
     this.afterFrame.unsubscribeAll();
+    this.onHmr.unsubscribeAll();
     this.#debugUi?.unmount();
   }
 
@@ -257,10 +291,14 @@ export class App {
    * import.meta.hot?.accept("./game", async (newModule) => {
    *   await app.acceptHmr(newModule?.game, {
    *   wasmUrl: monorepoWasmUrl,
+   *   files: ["./game"],
    * });
    * ```
    */
-  async acceptHmr(module: any, opts?: Partial<MountOpts>): Promise<void> {
+  async acceptHmr(
+    module: any,
+    opts?: Partial<MountOpts> & { files?: string[] },
+  ): Promise<void> {
     const game = (module.game ?? module) as Bloop<any>;
     if (!game.hooks) {
       throw new Error(
@@ -279,6 +317,10 @@ export class App {
     this.sim.unmount();
     this.sim = sim;
     this.game = game;
+
+    // Trigger HMR flash and notify listeners
+    triggerHmrFlash();
+    this.onHmr.notify({ files: opts?.files ?? [] });
   }
 }
 
@@ -312,3 +354,7 @@ function createListener<T extends any[]>(): {
 }
 
 export type UnsubscribeFn = () => void;
+
+export type HmrEvent = {
+  files: string[];
+};

package/src/debugui/DebugUi.ts

@@ -1,6 +1,6 @@
 import { type ComponentChild, render } from "preact";
 import { Root } from "./components/Root.tsx";
-import { type DebugState, debugState } from "./state.ts";
+import { type DebugState, cycleLayout, debugState } from "./state.ts";
 import { styles } from "./styles.ts";
 
 export type DebugUiOptions = {
@@ -30,7 +30,7 @@ export class DebugUi {
     // Create host element
     this.#host = document.createElement("bloop-debug-ui");
     this.#host.style.cssText =
-      "display:block;width:100%;height:100%;position:absolute;top:0;left:0;";
+      "display:block;width:100%;height:100%;position:absolute;top:0;left:0;overflow:hidden;overscroll-behavior:none;";
 
     // Attach shadow DOM
     this.#shadow = this.#host.attachShadow({ mode: "open" });
@@ -47,7 +47,7 @@ export class DebugUi {
     this.#shadow.appendChild(this.#mountPoint);
 
     // Initialize state
-    debugState.isVisible.value = initiallyVisible;
+    debugState.layoutMode.value = initiallyVisible ? "letterboxed" : "off";
 
     // Create canvas element (game renders here)
     this.#canvas = document.createElement("canvas");
@@ -61,8 +61,8 @@ export class DebugUi {
     // Set up hotkey listener
     this.#cleanup = this.#setupHotkey();
 
-    // Re-render when isVisible changes
-    debugState.isVisible.subscribe(() => {
+    // Re-render when layoutMode changes
+    debugState.layoutMode.subscribe(() => {
       this.#render();
     });
   }
@@ -77,7 +77,7 @@ export class DebugUi {
   #setupHotkey(): () => void {
     const handler = (e: KeyboardEvent) => {
       if (e.key === this.#hotkey) {
-        debugState.isVisible.value = !debugState.isVisible.value;
+        cycleLayout();
       }
     };
     window.addEventListener("keydown", handler);
@@ -100,7 +100,7 @@ export class DebugUi {
   }
 
   set isVisible(value: boolean) {
-    debugState.isVisible.value = value;
+    debugState.layoutMode.value = value ? "letterboxed" : "off";
   }
 
   unmount(): void {

package/src/debugui/components/BottomBar.tsx

@@ -0,0 +1,68 @@
+type BottomBarProps = {
+  tapeUtilization: number; // 0-1, how full the tape is
+  playheadPosition: number; // 0-1, current position in tape
+  isPlaying: boolean;
+};
+
+export function BottomBar({
+  tapeUtilization = 0,
+  playheadPosition = 0,
+  isPlaying = true,
+}: BottomBarProps) {
+  // Placeholder handlers - behavior not wired up yet
+  const handleJumpBack = () => {};
+  const handleStepBack = () => {};
+  const handlePlayPause = () => {};
+  const handleStepForward = () => {};
+  const handleJumpForward = () => {};
+  const handleSeek = () => {};
+
+  return (
+    <div className="bottom-bar">
+      <div className="playbar-controls">
+        <button className="playbar-btn" onClick={handleJumpBack}>
+          {"<<"}
+          <span className="tooltip tooltip-left">
+            Jump back <kbd>4</kbd>
+          </span>
+        </button>
+        <button className="playbar-btn" onClick={handleStepBack}>
+          {"<"}
+          <span className="tooltip">
+            Step back <kbd>5</kbd>
+          </span>
+        </button>
+        <button className="playbar-btn" onClick={handlePlayPause}>
+          {isPlaying ? "||" : ">"}
+          <span className="tooltip">
+            {isPlaying ? "Pause" : "Play"} <kbd>6</kbd>
+          </span>
+        </button>
+        <button className="playbar-btn" onClick={handleStepForward}>
+          {">"}
+          <span className="tooltip">
+            Step forward <kbd>7</kbd>
+          </span>
+        </button>
+        <button className="playbar-btn" onClick={handleJumpForward}>
+          {">>"}
+          <span className="tooltip">
+            Jump forward <kbd>8</kbd>
+          </span>
+        </button>
+      </div>
+      <div className="seek-bar" onClick={handleSeek}>
+        <div
+          className="seek-bar-fill"
+          style={{ width: `${tapeUtilization * 100}%` }}
+        />
+        {tapeUtilization > 0 && (
+          <div
+            className="seek-bar-position"
+            style={{ left: `${playheadPosition * tapeUtilization * 100}%` }}
+          />
+        )}
+      </div>
+    </div>
+  );
+}

package/src/debugui/components/DebugToggle.tsx

@@ -1,4 +1,4 @@
-import { debugState } from "../state.ts";
+import { cycleLayout, debugState } from "../state.ts";
 
 type DebugToggleProps = {
   hotkey?: string;
@@ -7,14 +7,10 @@ type DebugToggleProps = {
 export function DebugToggle({ hotkey = "Escape" }: DebugToggleProps) {
   const isVisible = debugState.isVisible.value;
 
-  const toggle = () => {
-    debugState.isVisible.value = !debugState.isVisible.value;
-  };
-
   return (
     <button
       className="debug-toggle"
-      onClick={toggle}
+      onClick={cycleLayout}
       onMouseDown={(e) => e.stopPropagation()}
       onMouseUp={(e) => e.stopPropagation()}
       title={isVisible ? `Hide debug (${hotkey})` : `Show debug (${hotkey})`}

package/src/debugui/components/Root.tsx

@@ -3,6 +3,9 @@ import { debugState } from "../state.ts";
 import { Stats } from "./Stats.tsx";
 import { Logs } from "./Logs.tsx";
 import { DebugToggle } from "./DebugToggle.tsx";
+import { TopBar } from "./TopBar.tsx";
+import { VerticalBar } from "./VerticalBar.tsx";
+import { BottomBar } from "./BottomBar.tsx";
 
 type RootProps = {
   canvas: HTMLCanvasElement;
@@ -10,32 +13,96 @@ type RootProps = {
 };
 
 export function Root({ canvas, hotkey = "Escape" }: RootProps) {
-  const isVisible = debugState.isVisible.value;
+  const layoutMode = debugState.layoutMode.value;
 
-  return (
-    <>
-      {isVisible ? (
-        <main className="layout">
-          <section className="game">
-            <GameCanvas canvas={canvas} />
-          </section>
-          <section className="stats">
-            <Stats />
-          </section>
-          <section className="logs">
-            <Logs />
-          </section>
-        </main>
-      ) : (
+  if (layoutMode === "off") {
+    return (
+      <>
         <main className="fullscreen">
           <GameCanvas canvas={canvas} />
         </main>
-      )}
+        <DebugToggle hotkey={hotkey} />
+      </>
+    );
+  }
+
+  if (layoutMode === "letterboxed") {
+    return (
+      <>
+        <LetterboxedLayout canvas={canvas} />
+        <DebugToggle hotkey={hotkey} />
+      </>
+    );
+  }
+
+  // Full layout (netcode debug)
+  return (
+    <>
+      <main className="layout">
+        <section className="game">
+          <GameCanvas canvas={canvas} />
+        </section>
+        <section className="stats">
+          <Stats />
+        </section>
+        <section className="logs">
+          <Logs />
+        </section>
+      </main>
       <DebugToggle hotkey={hotkey} />
     </>
   );
 }
 
+function LetterboxedLayout({ canvas }: { canvas: HTMLCanvasElement }) {
+  const isOnline = debugState.netStatus.value.peers.length > 0;
+  const advantage = debugState.advantage.value ?? 0;
+  const frameTime = debugState.frameTime.value;
+  const snapshotSize = debugState.snapshotSize.value;
+  const hmrFlash = debugState.hmrFlash.value;
+
+  // Left bar: frame advantage (online) or frame time % (offline)
+  const leftValue = isOnline ? Math.abs(advantage) : frameTime;
+  const leftMax = isOnline ? 10 : 16.67; // 10 frames advantage or 16.67ms budget
+  const leftLabel = isOnline ? "ADV" : "MS";
+  const leftColor = isOnline
+    ? advantage >= 0
+      ? "#4a9eff"
+      : "#ff4a4a"
+    : frameTime > 16.67
+      ? "#ff4a4a"
+      : "#4aff4a";
+
+  // Right bar: rollback depth (online) or snapshot size (offline)
+  // For now, we don't have rollback depth exposed, so use a placeholder
+  const rightValue = isOnline ? 0 : snapshotSize;
+  const rightMax = isOnline ? 10 : 10000; // 10 frames rollback or 10KB
+  const rightLabel = isOnline ? "RB" : "KB";
+
+  const gameClassName = hmrFlash ? "letterboxed-game hmr-flash" : "letterboxed-game";
+
+  return (
+    <main className="layout-letterboxed">
+      <TopBar leftLabel={leftLabel} rightLabel={rightLabel} />
+      <VerticalBar
+        value={leftValue}
+        max={leftMax}
+        side="left"
+        color={leftColor}
+      />
+      <div className={gameClassName}>
+        <GameCanvas canvas={canvas} />
+      </div>
+      <VerticalBar
+        value={rightValue}
+        max={rightMax}
+        side="right"
+      />
+      <BottomBar tapeUtilization={0.67} playheadPosition={0.8} isPlaying={true} />
+    </main>
+  );
+}
+
 function GameCanvas({ canvas }: { canvas: HTMLCanvasElement }) {
   const containerRef = useRef<HTMLDivElement>(null);
 

package/src/debugui/components/TopBar.tsx

@@ -0,0 +1,36 @@
+import { debugState } from "../state.ts";
+
+type TopBarProps = {
+  leftLabel: string;
+  rightLabel: string;
+};
+
+export function TopBar({ leftLabel, rightLabel }: TopBarProps) {
+  const fps = debugState.fps.value;
+  const frameNumber = debugState.frameNumber.value;
+  const rtt = debugState.netStatus.value.rtt;
+  const isOnline = debugState.netStatus.value.peers.length > 0;
+
+  return (
+    <div className="top-bar">
+      <span className="top-bar-side-label">{leftLabel}</span>
+      <div className="top-bar-center">
+        <div className="top-bar-item">
+          <span className="top-bar-label">FPS</span>
+          <span className="top-bar-value">{fps}</span>
+        </div>
+        <div className="top-bar-item">
+          <span className="top-bar-label">Frame</span>
+          <span className="top-bar-value">{frameNumber}</span>
+        </div>
+        {isOnline && rtt !== null && (
+          <div className="top-bar-item">
+            <span className="top-bar-label">Ping</span>
+            <span className="top-bar-value">{rtt}ms</span>
+          </div>
+        )}
+      </div>
+      <span className="top-bar-side-label">{rightLabel}</span>
+    </div>
+  );
+}

package/src/debugui/components/VerticalBar.tsx

@@ -0,0 +1,26 @@
+type VerticalBarProps = {
+  value: number;
+  max: number;
+  side: "left" | "right";
+  color?: string;
+};
+
+export function VerticalBar({
+  value,
+  max,
+  side,
+  color = "#4a9eff",
+}: VerticalBarProps) {
+  const percentage = max > 0 ? Math.min(100, (value / max) * 100) : 0;
+
+  return (
+    <div className={`${side}-bar`}>
+      <div className="vertical-bar">
+        <div
+          className="vertical-bar-fill"
+          style={{ height: `${percentage}%`, background: color }}
+        />
+      </div>
+    </div>
+  );
+}

package/src/debugui/state.ts

@@ -8,6 +8,8 @@ import type { Log } from "../netcode/logs.ts";
 
 export type FrameNumber = number;
 
+export type LayoutMode = "off" | "letterboxed" | "full";
+
 export type Peer = {
   id: string;
   nickname: string;
@@ -24,14 +26,22 @@ export type NetStatus = {
 };
 
 export type DebugState = {
-  isVisible: Signal<boolean>;
+  layoutMode: Signal<LayoutMode>;
+  isVisible: ReadonlySignal<boolean>;
   netStatus: Signal<NetStatus>;
   logs: Signal<Log[]>;
   peer: ReadonlySignal<Peer | null>;
   advantage: ReadonlySignal<number | null>;
+  // Metrics for letterboxed layout
+  fps: Signal<number>;
+  frameTime: Signal<number>; // ms per frame
+  snapshotSize: Signal<number>; // bytes
+  frameNumber: Signal<number>;
+  // HMR flash indicator
+  hmrFlash: Signal<boolean>;
 };
 
-const isVisible = signal(false);
+const layoutMode = signal<LayoutMode>("off");
 const netStatus = signal<NetStatus>({
   ourId: null,
   remoteId: null,
@@ -39,10 +49,18 @@ const netStatus = signal<NetStatus>({
   peers: [],
 });
 const logs = signal<Log[]>([]);
+const fps = signal(0);
+const frameTime = signal(0);
+const snapshotSize = signal(0);
+const frameNumber = signal(0);
+const hmrFlash = signal(false);
 
 export const debugState: DebugState = {
-  /** Whether debug UI is visible */
-  isVisible,
+  /** Layout mode: off, letterboxed, or full */
+  layoutMode,
+
+  /** Whether debug UI is visible (derived from layoutMode) */
+  isVisible: computed(() => layoutMode.value !== "off"),
 
   /** Network status */
   netStatus,
@@ -58,8 +76,62 @@ export const debugState: DebugState = {
     const peer = netStatus.value.peers[0];
     return peer ? peer.seq - peer.ack : null;
   }),
+
+  /** Metrics for letterboxed layout */
+  fps,
+  frameTime,
+  snapshotSize,
+  frameNumber,
+
+  /** HMR flash indicator */
+  hmrFlash,
 };
 
+/** Cycle through layout modes: off -> letterboxed -> full -> off */
+export function cycleLayout(): void {
+  const current = layoutMode.value;
+  if (current === "off") {
+    layoutMode.value = "letterboxed";
+  } else if (current === "letterboxed") {
+    layoutMode.value = "full";
+  } else {
+    layoutMode.value = "off";
+  }
+}
+
+let hmrFlashQueued = false;
+
+/** Trigger HMR flash (only when debug UI is visible) */
+export function triggerHmrFlash(): void {
+  if (!debugState.isVisible.value) return;
+
+  // If window doesn't have focus, queue the flash for when focus returns
+  if (!document.hasFocus()) {
+    if (!hmrFlashQueued) {
+      hmrFlashQueued = true;
+      window.addEventListener("focus", onWindowFocus);
+    }
+    return;
+  }
+
+  doFlash();
+}
+
+function onWindowFocus(): void {
+  if (hmrFlashQueued) {
+    hmrFlashQueued = false;
+    window.removeEventListener("focus", onWindowFocus);
+    doFlash();
+  }
+}
+
+function doFlash(): void {
+  debugState.hmrFlash.value = true;
+  setTimeout(() => {
+    debugState.hmrFlash.value = false;
+  }, 300);
+}
+
 export function addLog(log: Log): void {
   debugState.logs.value = [...debugState.logs.value, log];
 }
@@ -116,7 +188,7 @@ export function clearLogs(): void {
 }
 
 export function resetState(): void {
-  debugState.isVisible.value = false;
+  debugState.layoutMode.value = "off";
   debugState.logs.value = [];
   debugState.netStatus.value = {
     ourId: null,
@@ -124,4 +196,9 @@ export function resetState(): void {
     rtt: null,
     peers: [],
   };
+  debugState.fps.value = 0;
+  debugState.frameTime.value = 0;
+  debugState.snapshotSize.value = 0;
+  debugState.frameNumber.value = 0;
+  debugState.hmrFlash.value = false;
 }