@bloopjs/web 0.0.48 → 0.0.50

package/dist/netcode/mod.d.ts

@@ -2,6 +2,8 @@ export type { PeerId, BrokerMessage, PeerMessage } from "./protocol.ts";
 export type { Log, LogOpts, LogDirection, LogSeverity, OnLogCallback, } from "./logs.ts";
 export type { WebRtcPipe } from "./transport.ts";
 export type { RoomEvents } from "./broker.ts";
+export type { JoinRollbackRoomOptions } from "./scaffold.ts";
 export { PacketType } from "./protocol.ts";
 export { logger } from "./logs.ts";
+export { joinRollbackRoom } from "./scaffold.ts";
 //# sourceMappingURL=mod.d.ts.map

package/dist/netcode/mod.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/netcode/mod.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EACV,GAAG,EACH,OAAO,EACP,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC"}
+{"version":3,"file":"mod.d.ts","sourceRoot":"","sources":["../../src/netcode/mod.ts"],"names":[],"mappings":"AACA,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AACxE,YAAY,EACV,GAAG,EACH,OAAO,EACP,YAAY,EACZ,WAAW,EACX,aAAa,GACd,MAAM,WAAW,CAAC;AACnB,YAAY,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,YAAY,EAAE,uBAAuB,EAAE,MAAM,eAAe,CAAC;AAE7D,OAAO,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAC3C,OAAO,EAAE,MAAM,EAAE,MAAM,WAAW,CAAC;AACnC,OAAO,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC"}

package/dist/netcode/scaffold.d.ts

@@ -0,0 +1,13 @@
+import type { App } from "../App.ts";
+export type JoinRollbackRoomOptions = {
+    /** Called when session becomes active */
+    onSessionStart?: () => void;
+    /** Called when session ends */
+    onSessionEnd?: () => void;
+};
+/**
+ * Join a rollback netcode room and wire up packet processing.
+ * This is a scaffold/stopgap - not the final architecture.
+ */
+export declare function joinRollbackRoom(roomId: string, app: App, opts?: JoinRollbackRoomOptions): void;
+//# sourceMappingURL=scaffold.d.ts.map

package/dist/netcode/scaffold.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scaffold.d.ts","sourceRoot":"","sources":["../../src/netcode/scaffold.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,WAAW,CAAC;AAIrC,MAAM,MAAM,uBAAuB,GAAG;IACpC,yCAAyC;IACzC,cAAc,CAAC,EAAE,MAAM,IAAI,CAAC;IAC5B,+BAA+B;IAC/B,YAAY,CAAC,EAAE,MAAM,IAAI,CAAC;CAC3B,CAAC;AAEF;;;GAGG;AACH,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,GAAG,EAAE,GAAG,EACR,IAAI,CAAC,EAAE,uBAAuB,GAC7B,IAAI,CAqJN"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bloopjs/web",
-  "version": "0.0.48",
+  "version": "0.0.50",
   "author": "Neil Sarkar",
   "type": "module",
   "repository": {
@@ -22,7 +22,7 @@
     "README.md"
   ],
   "scripts": {
-    "build": "bun build src/mod.ts --outdir=dist --sourcemap=linked && bunx tsc -p publish/tsconfig.publish.json",
+    "build": "bun build src/mod.ts --outdir=dist --sourcemap=linked --jsx-import-source=preact --jsx-runtime=automatic && bunx tsc -p publish/tsconfig.publish.json",
     "ci:jsr": "bunx jsr publish --dry-run --allow-dirty",
     "ci:tsc": "tsc --noEmit"
   },
@@ -33,8 +33,10 @@
     "typescript": "^5"
   },
   "dependencies": {
-    "@bloopjs/bloop": "0.0.48",
-    "@bloopjs/engine": "0.0.48",
-    "partysocket": "^1.1.6"
+    "@bloopjs/bloop": "0.0.50",
+    "@bloopjs/engine": "0.0.50",
+    "@preact/signals": "^1.3.1",
+    "partysocket": "^1.1.6",
+    "preact": "^10.25.4"
   }
 }

package/src/App.ts

@@ -6,6 +6,7 @@ import {
   type RoomEvents,
 } from "./netcode/broker";
 import { logger } from "./netcode/logs.ts";
+import { DebugUi, type DebugUiOptions } from "./debugui/mod.ts";
 
 export type StartOptions = {
   /** A bloop game instance */
@@ -20,6 +21,8 @@ export type StartOptions = {
   startRecording?: boolean;
   /** URL for the WebRTC signaling broker (e.g. "wss://broker.example.com/ws") */
   brokerUrl?: string;
+  /** Enable debug UI with optional configuration */
+  debugUi?: boolean | DebugUiOptions;
 };
 
 const DEFAULT_BROKER_URL = "wss://webrtc-divine-glade-8064.fly.dev/ws";
@@ -35,11 +38,19 @@ export async function start(opts: StartOptions): Promise<App> {
     opts.sim = sim;
   }
 
+  const debugOpts = opts.debugUi
+    ? typeof opts.debugUi === "boolean"
+      ? {}
+      : opts.debugUi
+    : undefined;
+
   const app = new App(
     opts.sim,
     opts.game,
     opts.brokerUrl ?? DEFAULT_BROKER_URL,
+    debugOpts,
   );
+
   return app;
 }
 
@@ -59,12 +70,22 @@ export class App {
   #rafHandle: number | null = null;
   #unsubscribe: UnsubscribeFn | null = null;
   #now: number = performance.now();
-
-  constructor(sim: Sim, game: Bloop<any>, brokerUrl: string) {
+  #debugUi: DebugUi | null = null;
+
+  constructor(
+    sim: Sim,
+    game: Bloop<any>,
+    brokerUrl: string,
+    debugUiOpts?: DebugUiOptions,
+  ) {
     this.#sim = sim;
     this.game = game;
     this.brokerUrl = brokerUrl;
 
+    if (debugUiOpts) {
+      this.#initDebugUi(debugUiOpts);
+    }
+
     this.game.hooks.beforeFrame = (frame: number) => {
       logger.frameNumber = this.#sim.time.frame;
       logger.matchFrame = this.#sim.wasm.get_match_frame();
@@ -83,6 +104,23 @@ export class App {
     this.#sim = sim;
   }
 
+  /** Initialize debug UI (creates shadow DOM and mounts Preact) */
+  #initDebugUi(opts: DebugUiOptions = {}): DebugUi {
+    if (this.#debugUi) return this.#debugUi;
+    this.#debugUi = new DebugUi(opts);
+    return this.#debugUi;
+  }
+
+  /** Access debug UI instance */
+  get debugUi(): DebugUi | null {
+    return this.#debugUi;
+  }
+
+  /** Get the canvas element from debug UI (for game rendering) */
+  get canvas(): HTMLCanvasElement | null {
+    return this.#debugUi?.canvas ?? null;
+  }
+
   /** Join a multiplayer room via the broker */
   joinRoom(roomId: string, callbacks: RoomEvents): void {
     joinRoomInternal(this.brokerUrl, roomId, callbacks);
@@ -207,6 +245,7 @@ export class App {
     this.sim.unmount();
     this.beforeFrame.unsubscribeAll();
     this.afterFrame.unsubscribeAll();
+    this.#debugUi?.unmount();
   }
 
   /**

package/src/debugui/DebugUi.ts

@@ -0,0 +1,111 @@
+import { type ComponentChild, render } from "preact";
+import { Root } from "./components/Root.tsx";
+import { type DebugState, debugState } from "./state.ts";
+import { styles } from "./styles.ts";
+
+export type DebugUiOptions = {
+  /** Hotkey to toggle debug mode (default: 'Escape') */
+  hotkey?: string;
+  /** Initial debug visibility (default: false, or true if ?debug in URL) */
+  initiallyVisible?: boolean;
+  /** Container element to mount to (default: document.body) */
+  container?: HTMLElement;
+};
+
+export class DebugUi {
+  #host: HTMLElement;
+  #shadow: ShadowRoot;
+  #canvas: HTMLCanvasElement;
+  #mountPoint: HTMLElement;
+  #cleanup: (() => void) | null = null;
+  #hotkey: string;
+
+  constructor(options: DebugUiOptions = {}) {
+    this.#hotkey = options.hotkey ?? "Escape";
+    const container = options.container ?? document.body;
+    const initiallyVisible =
+      options.initiallyVisible ??
+      new URLSearchParams(window.location.search).has("debug");
+
+    // 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;";
+
+    // Attach shadow DOM
+    this.#shadow = this.#host.attachShadow({ mode: "open" });
+
+    // Inject styles
+    const styleEl = document.createElement("style");
+    styleEl.textContent = styles;
+    this.#shadow.appendChild(styleEl);
+
+    // Create mount point
+    this.#mountPoint = document.createElement("div");
+    this.#mountPoint.id = "debug-root";
+    this.#mountPoint.style.cssText = "width:100%;height:100%;";
+    this.#shadow.appendChild(this.#mountPoint);
+
+    // Initialize state
+    debugState.isVisible.value = initiallyVisible;
+
+    // Create canvas element (game renders here)
+    this.#canvas = document.createElement("canvas");
+
+    // Render Preact app
+    this.#render();
+
+    // Append to container
+    container.appendChild(this.#host);
+
+    // Set up hotkey listener
+    this.#cleanup = this.#setupHotkey();
+
+    // Re-render when isVisible changes
+    debugState.isVisible.subscribe(() => {
+      this.#render();
+    });
+  }
+
+  #render(): void {
+    render(
+      Root({ canvas: this.#canvas, hotkey: this.#hotkey }) as ComponentChild,
+      this.#mountPoint,
+    );
+  }
+
+  #setupHotkey(): () => void {
+    const handler = (e: KeyboardEvent) => {
+      if (e.key === this.#hotkey) {
+        debugState.isVisible.value = !debugState.isVisible.value;
+      }
+    };
+    window.addEventListener("keydown", handler);
+    return () => window.removeEventListener("keydown", handler);
+  }
+
+  /** The canvas element for game rendering */
+  get canvas(): HTMLCanvasElement {
+    return this.#canvas;
+  }
+
+  /** Access to state signals for external updates */
+  get state(): DebugState {
+    return debugState;
+  }
+
+  /** Whether the debug panel is currently visible */
+  get isVisible(): boolean {
+    return debugState.isVisible.value;
+  }
+
+  set isVisible(value: boolean) {
+    debugState.isVisible.value = value;
+  }
+
+  unmount(): void {
+    this.#cleanup?.();
+    render(null, this.#mountPoint);
+    this.#host.remove();
+  }
+}

package/src/debugui/components/DebugToggle.tsx

@@ -0,0 +1,25 @@
+import { debugState } from "../state.ts";
+
+type DebugToggleProps = {
+  hotkey?: string;
+};
+
+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}
+      onMouseDown={(e) => e.stopPropagation()}
+      onMouseUp={(e) => e.stopPropagation()}
+      title={isVisible ? `Hide debug (${hotkey})` : `Show debug (${hotkey})`}
+    >
+      {isVisible ? "\u2715" : "\u2699"}
+    </button>
+  );
+}

package/src/debugui/components/Logs.tsx

@@ -0,0 +1,57 @@
+import { useSignalEffect } from "@preact/signals";
+import { debugState } from "../state.ts";
+import { useAutoScroll } from "../hooks/useAutoScroll.ts";
+import type { Log } from "../../netcode/logs.ts";
+
+function formatTimestamp(ms: number): string {
+  const date = new Date(ms);
+  const hours = date.getHours() % 12;
+  const minutes = date.getMinutes().toString().padStart(2, "0");
+  const seconds = date.getSeconds().toString().padStart(2, "0");
+  const millis = date.getMilliseconds().toString().padStart(3, "0");
+  return `${hours}:${minutes}:${seconds}.${millis}`;
+}
+
+export function Logs() {
+  const { containerRef, onContentUpdated } = useAutoScroll(80);
+  const logs = debugState.logs.value;
+
+  // Trigger auto-scroll when logs change
+  useSignalEffect(() => {
+    const _ = debugState.logs.value.length;
+    onContentUpdated();
+  });
+
+  return (
+    <ul className="logs-list" ref={containerRef}>
+      {logs.map((log: Log, index: number) => (
+        <LogEntry key={index} log={log} />
+      ))}
+    </ul>
+  );
+}
+
+function LogEntry({ log }: { log: Log }) {
+  return (
+    <li className={`log ${log.source}`}>
+      <div className="contents">
+        <h3 className={log.source}>
+          <span className="source">{log.source} | </span>
+          {log.match_frame != null ? (
+            <span className="frame-number">m{log.match_frame} | </span>
+          ) : (
+            <span className="frame-number">f{log.frame_number} | </span>
+          )}
+          <span className="timestamp">{formatTimestamp(log.timestamp)}</span>
+        </h3>
+        <div className="content">
+          {log.label && <p>{log.label}</p>}
+          {log.json && (
+            <pre className="json">{JSON.stringify(log.json, null, 2)}</pre>
+          )}
+          {log.packet && <div>{log.packet.size} bytes</div>}
+        </div>
+      </div>
+    </li>
+  );
+}

package/src/debugui/components/Root.tsx

@@ -0,0 +1,54 @@
+import { useRef, useEffect } from "preact/hooks";
+import { debugState } from "../state.ts";
+import { Stats } from "./Stats.tsx";
+import { Logs } from "./Logs.tsx";
+import { DebugToggle } from "./DebugToggle.tsx";
+
+type RootProps = {
+  canvas: HTMLCanvasElement;
+  hotkey?: string;
+};
+
+export function Root({ canvas, hotkey = "Escape" }: RootProps) {
+  const isVisible = debugState.isVisible.value;
+
+  return (
+    <>
+      {isVisible ? (
+        <main className="layout">
+          <section className="game">
+            <GameCanvas canvas={canvas} />
+          </section>
+          <section className="stats">
+            <Stats />
+          </section>
+          <section className="logs">
+            <Logs />
+          </section>
+        </main>
+      ) : (
+        <main className="fullscreen">
+          <GameCanvas canvas={canvas} />
+        </main>
+      )}
+      <DebugToggle hotkey={hotkey} />
+    </>
+  );
+}
+
+function GameCanvas({ canvas }: { canvas: HTMLCanvasElement }) {
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    const container = containerRef.current;
+    if (container && !container.contains(canvas)) {
+      container.appendChild(canvas);
+    }
+
+    return () => {
+      // Don't remove canvas on cleanup - it may need to persist
+    };
+  }, [canvas]);
+
+  return <div className="canvas-container" ref={containerRef} />;
+}

package/src/debugui/components/Stats.tsx

@@ -0,0 +1,68 @@
+import { useSignal, useSignalEffect } from "@preact/signals";
+import { debugState } from "../state.ts";
+
+export function Stats() {
+  const peer = debugState.peer.value;
+  const netStatus = debugState.netStatus.value;
+
+  // Live-updating "time since last packet"
+  const lastPacketTime = useSignal<string | null>(null);
+
+  useSignalEffect(() => {
+    const p = debugState.peer.value;
+    if (!p) {
+      lastPacketTime.value = null;
+      return;
+    }
+
+    const update = () => {
+      lastPacketTime.value = (performance.now() - p.lastPacketTime).toFixed(0);
+    };
+    update();
+    const id = setInterval(update, 100);
+    return () => clearInterval(id);
+  });
+
+  if (!peer) {
+    return (
+      <div className="stats-panel">
+        <h3>Network Stats</h3>
+        <p>No peer connected</p>
+      </div>
+    );
+  }
+
+  return (
+    <div className="stats-panel">
+      <h3>Network Stats - {peer.nickname}</h3>
+      <table>
+        <tbody>
+          <tr>
+            <td>Our Peer ID</td>
+            <td>{netStatus.ourId}</td>
+          </tr>
+          <tr>
+            <td>Remote Peer ID</td>
+            <td>{netStatus.remoteId}</td>
+          </tr>
+          <tr>
+            <td>Advantage</td>
+            <td>{peer.seq - peer.ack}</td>
+          </tr>
+          <tr>
+            <td>Current Seq</td>
+            <td>{peer.seq}</td>
+          </tr>
+          <tr>
+            <td>Current Ack</td>
+            <td>{peer.ack}</td>
+          </tr>
+          <tr>
+            <td>Time since last packet</td>
+            <td>{lastPacketTime.value}ms</td>
+          </tr>
+        </tbody>
+      </table>
+    </div>
+  );
+}

package/src/debugui/hooks/useAutoScroll.ts

@@ -0,0 +1,62 @@
+import { useRef, useCallback, useEffect } from "preact/hooks";
+
+export function useAutoScroll(threshold = 80) {
+  const containerRef = useRef<HTMLElement | null>(null);
+  const autoScrollRef = useRef(true);
+
+  const onScroll = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    const distanceFromBottom =
+      el.scrollHeight - el.scrollTop - el.clientHeight;
+    autoScrollRef.current = distanceFromBottom < threshold;
+  }, [threshold]);
+
+  const scrollToBottom = useCallback(() => {
+    const el = containerRef.current;
+    if (!el) return;
+
+    // Use requestAnimationFrame for DOM update timing
+    requestAnimationFrame(() => {
+      el.scrollTop = el.scrollHeight;
+    });
+  }, []);
+
+  const onContentUpdated = useCallback(() => {
+    if (autoScrollRef.current) {
+      scrollToBottom();
+    }
+  }, [scrollToBottom]);
+
+  // Set up scroll listener when ref changes
+  useEffect(() => {
+    const el = containerRef.current;
+    if (el) {
+      el.addEventListener("scroll", onScroll);
+      return () => el.removeEventListener("scroll", onScroll);
+    }
+  }, [onScroll]);
+
+  // Return ref callback to set containerRef
+  const setRef = useCallback(
+    (el: HTMLElement | null) => {
+      // Clean up old listener
+      if (containerRef.current) {
+        containerRef.current.removeEventListener("scroll", onScroll);
+      }
+      containerRef.current = el;
+      // Add new listener
+      if (el) {
+        el.addEventListener("scroll", onScroll);
+      }
+    },
+    [onScroll],
+  );
+
+  return {
+    containerRef: setRef,
+    onContentUpdated,
+    scrollToBottom,
+  };
+}

package/src/debugui/mod.ts

@@ -0,0 +1,2 @@
+export { DebugUi, type DebugUiOptions } from "./DebugUi.ts";
+export * from "./state.ts";

package/src/debugui/state.ts

@@ -0,0 +1,127 @@
+import {
+  computed,
+  type ReadonlySignal,
+  type Signal,
+  signal,
+} from "@preact/signals";
+import type { Log } from "../netcode/logs.ts";
+
+export type FrameNumber = number;
+
+export type Peer = {
+  id: string;
+  nickname: string;
+  ack: FrameNumber;
+  seq: FrameNumber;
+  lastPacketTime: number;
+};
+
+export type NetStatus = {
+  ourId: number | null;
+  remoteId: number | null;
+  rtt: number | null;
+  peers: Peer[];
+};
+
+export type DebugState = {
+  isVisible: Signal<boolean>;
+  netStatus: Signal<NetStatus>;
+  logs: Signal<Log[]>;
+  peer: ReadonlySignal<Peer | null>;
+  advantage: ReadonlySignal<number | null>;
+};
+
+const isVisible = signal(false);
+const netStatus = signal<NetStatus>({
+  ourId: null,
+  remoteId: null,
+  rtt: null,
+  peers: [],
+});
+const logs = signal<Log[]>([]);
+
+export const debugState: DebugState = {
+  /** Whether debug UI is visible */
+  isVisible,
+
+  /** Network status */
+  netStatus,
+
+  /** Log entries */
+  logs,
+
+  /** First connected peer (for Stats panel) */
+  peer: computed(() => netStatus.value.peers[0] ?? null),
+
+  /** Advantage calculation (seq - ack) */
+  advantage: computed(() => {
+    const peer = netStatus.value.peers[0];
+    return peer ? peer.seq - peer.ack : null;
+  }),
+};
+
+export function addLog(log: Log): void {
+  debugState.logs.value = [...debugState.logs.value, log];
+}
+
+export function updatePeer(id: string, updates: Partial<Peer>): void {
+  const peers = [...debugState.netStatus.value.peers];
+  const idx = peers.findIndex((p) => p.id === id);
+  const existing = peers[idx];
+  if (idx >= 0 && existing) {
+    peers[idx] = {
+      id: updates.id ?? existing.id,
+      nickname: updates.nickname ?? existing.nickname,
+      ack: updates.ack ?? existing.ack,
+      seq: updates.seq ?? existing.seq,
+      lastPacketTime: updates.lastPacketTime ?? existing.lastPacketTime,
+    };
+    debugState.netStatus.value = {
+      ...debugState.netStatus.value,
+      peers,
+    };
+  }
+}
+
+export function addPeer(peer: Peer): void {
+  debugState.netStatus.value = {
+    ...debugState.netStatus.value,
+    peers: [...debugState.netStatus.value.peers, peer],
+  };
+}
+
+export function removePeer(id: string): void {
+  debugState.netStatus.value = {
+    ...debugState.netStatus.value,
+    peers: debugState.netStatus.value.peers.filter((p) => p.id !== id),
+  };
+}
+
+export function setLocalId(id: number): void {
+  debugState.netStatus.value = {
+    ...debugState.netStatus.value,
+    ourId: id,
+  };
+}
+
+export function setRemoteId(id: number): void {
+  debugState.netStatus.value = {
+    ...debugState.netStatus.value,
+    remoteId: id,
+  };
+}
+
+export function clearLogs(): void {
+  debugState.logs.value = [];
+}
+
+export function resetState(): void {
+  debugState.isVisible.value = false;
+  debugState.logs.value = [];
+  debugState.netStatus.value = {
+    ourId: null,
+    remoteId: null,
+    rtt: null,
+    peers: [],
+  };
+}