@downdraft/engine 0.0.0 → 0.1.1

package/core/src/platform/glob-polyfill.ts

@@ -0,0 +1,124 @@
+// ============================================================================
+// glob-polyfill.ts — import.meta.glob replacement for the native runtime
+//
+// This module is imported by the bun-preload glob plugin. It provides a
+// filesystem-based implementation of Vite's import.meta.glob().
+// ============================================================================
+
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { fileURLToPath, pathToFileURL } from "node:url";
+
+// Compiled-binary layout: `bun build --compile` embeds modules under
+// /$bunfs/root/<repo-rel> (Windows: B:\~BUN\root\). Asset files aren't
+// embedded — package-native.mjs stages them at <execDir>/dd-assets/
+// <repo-rel>, so a $bunfs callerDir maps onto the staged tree. The keys
+// stay identical because both trees share the same relative structure.
+const BUNFS_ROOT_RE = /^\/\$bunfs\/root\/|^B:\\~BUN\\root\\/i;
+
+function mapCallerDir(callerDir: string): string {
+  if (!BUNFS_ROOT_RE.test(callerDir)) return callerDir;
+  const rel = callerDir.replace(BUNFS_ROOT_RE, "");
+  const root = process.env.DOWNDRAFT_ASSET_ROOT
+    ?? join(dirname(process.execPath), "dd-assets");
+  return join(root, rel);
+}
+
+function globToRegex(pattern: string): RegExp {
+  // Order matters: `**` must be handled before `*` (a single `*` matches one
+  // path segment; `**` matches zero or more segments). `**/` additionally
+  // collapses to zero segments so `a/**/b` also matches `a/b`.
+  let regex = pattern
+    .replace(/[.+^$()|[\]\\]/g, "\\$&")
+    .replace(/\*\*\//g, "\x00")
+    .replace(/\*\*/g, "\x01")
+    .replace(/\*/g, "[^/]*")
+    .replace(/\{([^}]+)\}/g, (_, group) => `(${group.replace(/,/g, "|")})`)
+    .replace(/\x00/g, "(?:.*/)?")
+    .replace(/\x01/g, ".*");
+  return new RegExp(`^${regex}$`, "i");
+}
+
+function walkDir(dir: string, results: string[] = []): string[] {
+  let entries: string[];
+  try { entries = readdirSync(dir); } catch { return results; }
+  for (let _i = 0, _it = entries, _n = _it.length; _i < _n; _i++) { const entry = _it[_i];
+    const fullPath = join(dir, entry);
+    let stat;
+    try { stat = statSync(fullPath); } catch { continue; }
+    if (stat.isDirectory()) walkDir(fullPath, results);
+    else results.push(fullPath);
+  }
+  return results;
+}
+
+export function createGlob(callerDir: string): (pattern: string, options?: any) => Record<string, string> {
+  const fsCallerDir = mapCallerDir(callerDir);
+  return function glob(pattern: string, options?: any): Record<string, string> {
+    // Extract the non-glob prefix to find the search root
+    const patternParts = pattern.split("/");
+    let rootParts: string[] = [];
+    for (let _i = 0, _it = patternParts, _n = _it.length; _i < _n; _i++) { const part = _it[_i];
+      if (part.includes("*") || part.includes("{")) break;
+      rootParts.push(part);
+    }
+    const searchDir = resolve(fsCallerDir, ...rootParts);
+    if (!existsSync(searchDir) || !statSync(searchDir).isDirectory()) return {};
+
+    const allFiles = walkDir(searchDir);
+    const result: Record<string, string> = {};
+    const normalizedPattern = pattern.replace(/^\.\//, "");
+    const matchRegex = globToRegex(normalizedPattern);
+
+    allFiles.forEach((file) => {
+      const relPath = relative(fsCallerDir, file).replace(/\\/g, "/");
+      const prefixedPath = relPath.startsWith("..") ? relPath : "./" + relPath;
+      if (matchRegex.test(relPath) || matchRegex.test(prefixedPath)) {
+        // For ?url queries, return the file:// URL
+        result["./" + relPath] = pathToFileURL(file).href;
+      }
+    });
+    return result;
+  };
+}
+
+// ── globAssets — the canonical asset-glob call ──
+//
+// Games used to hand-roll the same shim at every call site:
+//
+//   const _glob = (import.meta as any).glob ?? ((pattern) => {
+//     const { createGlob } = require("@downdraft/engine/platform/glob-polyfill");
+//     return createGlob(import.meta.dir)(pattern, { query: "?url", eager: true });
+//   });
+//
+// This is that shim, done once. Resolution order matches what the shims
+// converged on:
+//   1. `__nativeGlob` — installed by the native host (platform-native's
+//      installAssetGlob); caller-relative via the baseDir argument.
+//   2. `import.meta.glob` — present only under a Vite transform that injected
+//      it; a plain property read is undefined on native, so this is a safe
+//      second probe.
+//   3. `createGlob(callerDir)` — filesystem glob relative to the caller's
+//      module dir (packaged binaries, bare runtimes without the host global).
+//
+// Usage:
+//   const models = globAssets("../assets/models/*.glb", import.meta);
+//
+// `meta` is the CALLER's import.meta — a module-level helper can't see it.
+export function globAssets(
+  pattern: string,
+  meta: { url?: string; dir?: string; glob?: unknown },
+  options?: { query?: string; import?: string; eager?: boolean },
+): Record<string, string> {
+  const callerDir = meta.dir ?? (meta.url ? dirname(fileURLToPath(meta.url)) : process.cwd());
+  const opts = { eager: true, query: "?url", ...options };
+
+  const native = (globalThis as { __nativeGlob?: unknown }).__nativeGlob;
+  if (typeof native === "function") {
+    return (native as (p: string, o?: unknown, baseDir?: string) => Record<string, string>)(pattern, opts, callerDir);
+  }
+  if (typeof meta.glob === "function") {
+    return (meta.glob as (p: string, o?: unknown) => Record<string, string>)(pattern, opts);
+  }
+  return createGlob(callerDir)(pattern, opts);
+}

package/core/src/platform/hidpi.ts

@@ -0,0 +1,57 @@
+/**
+ * Get the current device pixel ratio (DPR), safely callable from any context
+ * (returns 1 in non-browser environments like Web Workers without `window`).
+ *
+ * Games use this to scale layout constants (tile sizes, HUD margins, grid cell
+ * sizes) so they render correctly on high-DPI mobile displays and Retina
+ * desktops. Equivalent to `window.devicePixelRatio || 1` but worker-safe.
+ */
+export function getDpr(): number {
+  if (typeof window !== "undefined" && typeof window.devicePixelRatio === "number") {
+    return window.devicePixelRatio;
+  }
+  return 1;
+}
+
+export class HiDPIManager {
+  private scaleFactor: number = 1;
+  private handlers: Array<(scale: number) => void> = [];
+
+  detectScaleFactor(): number {
+    if (typeof window !== "undefined" && typeof window.devicePixelRatio === "number") {
+      return window.devicePixelRatio;
+    }
+    if (typeof process !== "undefined" && process.platform) {
+      if (process.platform === "darwin") {
+        return 2;
+      }
+      if (process.platform === "win32") {
+        return 1;
+      }
+      if (process.platform === "linux") {
+        return 1;
+      }
+    }
+    return 1;
+  }
+
+  getScaleFactor(): number {
+    return this.scaleFactor;
+  }
+
+  setScaleFactor(scale: number): void {
+    if (scale === this.scaleFactor) return;
+    this.scaleFactor = scale;
+    for (let i = 0; i < this.handlers.length; i++) {
+      this.handlers[i](scale);
+    }
+  }
+
+  onScaleChange(fn: (scale: number) => void): void {
+    this.handlers.push(fn);
+  }
+
+  init(): void {
+    this.scaleFactor = this.detectScaleFactor();
+  }
+}

package/core/src/platform/render-surface.ts

@@ -0,0 +1,77 @@
+// ============================================================================
+// RenderSurface — the engine's renderer-facing surface contract
+//
+// A RenderSurface is the thing a game renderer draws into: a WebGPU
+// presentation target with a size, a resize event, and an input event
+// target. It is intentionally NOT a DOM type — on the native host it is
+// backed by an SDL window + wgpu surface (`NativeSurface`), on a DOM host
+// it is the HTMLCanvasElement itself (which satisfies this interface
+// structurally).
+//
+// Canvas-era APIs that are NOT part of this contract (2d contexts, toBlob,
+// style, focus/blur, DOM tree traversal) live behind the canvas/DOM compat
+// layer — engine code must never require them.
+// ============================================================================
+
+/**
+ * The WebGPU context for a RenderSurface. Structurally matches the slice of
+ * GPUCanvasContext the engine uses — both the real DOM GPUCanvasContext and
+ * the native NativeCanvasContext satisfy it. (GPUCanvasContext itself is a
+ * branded type that cannot be `implements`-ed, so this minimal shape is the
+ * engine's own contract.)
+ */
+export interface RenderSurfaceContext {
+  /** Configure the surface for presentation from a device. */
+  configure(config: GPUCanvasConfiguration): void;
+  /** Release the surface configuration. */
+  unconfigure(): void;
+  /** Acquire the next frame's texture for rendering. Can return null when
+   *  the swapchain can't produce a frame (resize in flight, occluded
+   *  window) — callers must treat null as "skip this frame". */
+  getCurrentTexture(): GPUTexture | null;
+}
+
+/** Listener signature — the native event target dispatches plain event
+ *  objects; DOM hosts dispatch real Events. Keep the parameter `any` so
+ *  both event shapes flow through without casts. */
+export type RenderSurfaceListener = (event: any) => void;
+
+/**
+ * The renderer-facing surface: size + WebGPU context + event target.
+ *
+ * `width`/`height` are the backing (pixel) size and are assignable —
+ * `surface.width = w` resizes the backing store, matching canvas
+ * semantics. `clientWidth`/`clientHeight` are the CSS-space size (equal to
+ * the backing size on native; DPR-scaled on DOM hosts).
+ *
+ * Events: `"resize"` fires when the host resizes the surface; input events
+ * (pointer/mouse/wheel/keyboard) are dispatched here on native and by the
+ * DOM on browser hosts.
+ */
+export interface RenderSurface {
+  /** Backing pixel width. Assignable — resizes the surface. */
+  width: number;
+  /** Backing pixel height. Assignable — resizes the surface. */
+  height: number;
+  /** CSS-space width (== width on native). */
+  readonly clientWidth: number;
+  /** CSS-space height (== height on native). */
+  readonly clientHeight: number;
+  /** Element-space bounding box for pointer coordinate mapping. */
+  getBoundingClientRect(): { left: number; top: number; right: number; bottom: number; width: number; height: number };
+  /** Acquire a rendering context. Only "webgpu" is part of the contract —
+   *  other context ids return null (2d lives in the compat layer). */
+  getContext(contextId: "webgpu"): RenderSurfaceContext | null;
+  getContext(contextId: string): unknown;
+  /** Input + "resize" event target. */
+  addEventListener(type: string, listener: RenderSurfaceListener, options?: unknown): void;
+  removeEventListener(type: string, listener: RenderSurfaceListener, options?: unknown): void;
+  /** Dispatch an event — `Event` on DOM hosts, a plain `{ type, ...fields }`
+   *  object on native. Typed `any` because the two event shapes share no
+   *  common supertype and both flow through the same listeners. */
+  dispatchEvent(event: any): boolean;
+  /** Pointer lock (pointer-lock games). Optional — absent where the
+   *  concept doesn't exist; presence is the feature check. */
+  requestPointerLock?(): Promise<void> | void;
+  exitPointerLock?(): void;
+}

package/core/src/platform/rpc.ts

@@ -0,0 +1,98 @@
+export type RPCMessageType = "request" | "response" | "event";
+
+export interface RPCMessage {
+  type: RPCMessageType;
+  id: number;
+  channel: string;
+  payload?: unknown;
+}
+
+export type RPCHandler = (payload: unknown) => Promise<unknown> | unknown;
+
+export class RPC {
+  private handlers: Map<string, RPCHandler> = new Map();
+  private pending: Map<number, { resolve: (v: unknown) => void; reject: (e: Error) => void }> = new Map();
+  private eventListeners: Map<string, Set<(payload: unknown) => void>> = new Map();
+  private messageIdCounter: number = 0;
+  private sendFn: ((msg: RPCMessage) => void) | null = null;
+  private static readonly MAX_PENDING = 1024;
+
+  setSendFn(fn: (msg: RPCMessage) => void): void {
+    this.sendFn = fn;
+  }
+
+  registerHandler(channel: string, handler: RPCHandler): void {
+    this.handlers.set(channel, handler);
+  }
+
+  async call(channel: string, payload?: unknown, timeoutMs: number = 5000): Promise<unknown> {
+    if (!this.sendFn) {
+      return Promise.reject(new Error(`[RPC] No send function set for channel "${channel}"`));
+    }
+    if (this.pending.size >= RPC.MAX_PENDING) {
+      return Promise.reject(new Error(`[RPC] Pending map full (${RPC.MAX_PENDING}), cannot call "${channel}"`));
+    }
+    const id = this.messageIdCounter = (this.messageIdCounter + 1) % 0xFFFFFFFF;
+    return new Promise((resolve, reject) => {
+      const timer = setTimeout(() => {
+        if (this.pending.has(id)) {
+          this.pending.delete(id);
+          reject(new Error(`[RPC] Call to "${channel}" timed out after ${timeoutMs}ms`));
+        }
+      }, timeoutMs);
+      this.pending.set(id, {
+        resolve: (v) => { clearTimeout(timer); resolve(v); },
+        reject: (e) => { clearTimeout(timer); reject(e); },
+      });
+      this.send({ type: "request", id, channel, payload });
+    });
+  }
+
+  emit(channel: string, payload?: unknown): void {
+    this.send({ type: "event", id: 0, channel, payload });
+  }
+
+  on(channel: string, fn: (payload: unknown) => void): () => void {
+    let listeners = this.eventListeners.get(channel);
+    if (!listeners) {
+      listeners = new Set();
+      this.eventListeners.set(channel, listeners);
+    }
+    listeners.add(fn);
+    return () => listeners!.delete(fn);
+  }
+
+  receive(msg: RPCMessage): void {
+    if (msg.type === "response") {
+      const pending = this.pending.get(msg.id);
+      if (pending) {
+        this.pending.delete(msg.id);
+        pending.resolve(msg.payload);
+      }
+    } else if (msg.type === "request") {
+      const handler = this.handlers.get(msg.channel);
+      if (handler) {
+        Promise.resolve(handler(msg.payload))
+          .then((result) => {
+            this.send({ type: "response", id: msg.id, channel: msg.channel, payload: result });
+          })
+          .catch((err) => {
+            this.send({ type: "response", id: msg.id, channel: msg.channel, payload: { error: String(err) } });
+          });
+      }
+    } else if (msg.type === "event") {
+      const listeners = this.eventListeners.get(msg.channel);
+      if (listeners) {
+        for (const fn of listeners.values()) {
+          fn(msg.payload);
+        }
+      }
+    }
+  }
+
+  private send(msg: RPCMessage): void {
+    if (this.sendFn) {
+      this.sendFn(msg);
+    }
+  }
+}

package/core/src/platform/runtime.ts

@@ -0,0 +1,132 @@
+// ============================================================================
+// Runtime detection — capability-based, not runtime-name-based
+//
+// Every platform seam in the engine checks for capabilities, not runtime names.
+// This file provides the few boolean helpers that are genuinely useful for
+// dev/prod mode detection and logging, but the engine code should prefer
+// direct capability checks (e.g. `navigator.gpu ?? globalThis.__nativeGpu`)
+// over these helpers.
+// ============================================================================
+
+/** True when running under Bun (typeof Bun !== "undefined"). */
+export const isBun: boolean = typeof (globalThis as any).Bun !== "undefined";
+
+/**
+ * True inside a `bun build --compile` binary. In compiled executables
+ * `Bun.main` is `/$bunfs/root/<entry>` instead of a real filesystem path —
+ * this is a global and stays correct even in bundles where a packager has
+ * rewritten a module's own `import.meta.url` to the staged asset tree.
+ */
+export const isCompiledBinary: boolean =
+  isBun && /^\/\$bunfs\//.test((globalThis as any).Bun?.main ?? "");
+
+/**
+ * Dev mode. Resolved from (in priority order):
+ *   1. DOWNDRAFT_DEV=1 env var
+ *   2. Vite's import.meta.env.DEV (injected at build time by Vite)
+ *   3. NODE_ENV !== "production" (Bun / Node)
+ *
+ * In native mode (Bun/Node/Deno), set DOWNDRAFT_DEV=1 or NODE_ENV=development.
+ * In Vite mode, Vite injects import.meta.env.DEV automatically.
+ */
+export const isDev: boolean = (() => {
+  // 1. Explicit env var
+  const env = (globalThis as any).process?.env;
+  if (env?.DOWNDRAFT_DEV === "1") return true;
+  if (env?.DOWNDRAFT_DEV === "0") return false;
+  // 2. Vite's import.meta.env.DEV — only available under Vite.
+  //    In Bun, import.meta.env is process.env, so DEV is undefined (falsy).
+  //    We use a try/catch because import.meta.env may not be accessible in
+  //    all contexts (e.g. workers).
+  try {
+    const metaEnv = (import.meta as any).env;
+    if (metaEnv?.DEV === true) return true;
+  } catch {}
+  // 3. NODE_ENV
+  if (env?.NODE_ENV && env.NODE_ENV !== "production") return true;
+  return false;
+})();
+
+/** Alias for {@link isDev} — used by engine seams as `isDevMode`. */
+export const isDevMode: boolean = isDev;
+
+/** True when HMR (hot module replacement) is available (Vite dev mode only). */
+export const hasHMR: boolean = (() => {
+  try {
+    return !!(import.meta as any).hot;
+  } catch {
+    return false;
+  }
+})();
+
+// ---------------------------------------------------------------------------
+// Host capability surface
+//
+// `isBun` answers "what am I running
+// on" — feature gates need "what can this host do". getHostCapabilities()
+// answers that: it prefers the bridge-installed descriptor, then falls back
+// to the `__nativeHost` marker (seeded by bun-preload before createNativeHost
+// runs, so module-eval-time checks work), then to browser defaults.
+// ---------------------------------------------------------------------------
+
+export type HostRuntime = "native" | "browser";
+
+export interface HostCapabilities {
+  readonly runtime: HostRuntime;
+  /** A real DOM compositor exists — DOM overlays, framework roots, real
+   *  elementFromPoint. False on native (the DOM there is a polyfill for
+   *  canvas-shaped APIs, not a compositor). */
+  readonly hasDom: boolean;
+  /** OPFS persistence is reachable (navigator.storage.getDirectory). */
+  readonly hasOpfs: boolean;
+  /** The host can expose its wgpu device to multiple worker threads.
+   *  True on native: wgpu handles are process-global and workers attach a
+   *  non-owning view via shareDevice/attachSharedDevice. Intended for
+   *  coarse-grained work — per-pass splitting loses to worker overhead. */
+  readonly supportsMultiWorkerGpu: boolean;
+}
+
+export const NATIVE_HOST_CAPABILITIES: HostCapabilities = {
+  runtime: "native",
+  hasDom: false,
+  hasOpfs: false,
+  supportsMultiWorkerGpu: true,
+};
+
+const DOM_HOST_CAPABILITIES: HostCapabilities = {
+  runtime: "browser",
+  hasDom: true,
+  hasOpfs: true,
+  supportsMultiWorkerGpu: false,
+};
+
+/** The host's capability descriptor. Prefers `downdraft.capabilities` when a
+ *  bridge is installed; otherwise detects the native host marker and finally
+ *  assumes a plain browser/DOM host. */
+export function getHostCapabilities(): HostCapabilities {
+  const caps = (globalThis as { downdraft?: { capabilities?: HostCapabilities } })
+    .downdraft?.capabilities;
+  if (caps) return caps;
+  if ((globalThis as { __nativeHost?: unknown }).__nativeHost) {
+    return NATIVE_HOST_CAPABILITIES;
+  }
+  return DOM_HOST_CAPABILITIES;
+}
+
+/** The subset of the live native host object games legitimately reach for —
+ *  primarily its GPU handles until the renderer gets an injected device
+ *  (Phase 2 of the native re-architecture). */
+export interface NativeHostHandle {
+  device?: GPUDevice;
+  adapter?: GPUAdapter;
+  [key: string]: unknown;
+}
+
+/** The live native host object, or null when not on native — or when only
+ *  the pre-boot `__nativeHost = true` marker exists (no device yet). Prefer
+ *  `getHostCapabilities()` for feature gates; use this only when the host's
+ *  concrete handles are genuinely needed. */
+export function getNativeHost(): NativeHostHandle | null {
+  const host = (globalThis as { __nativeHost?: unknown }).__nativeHost;
+  return host && typeof host === "object" ? (host as NativeHostHandle) : null;
+}