@downdraft/engine 0.1.0 → 0.1.2-alpha.5

package/dist/core/src/platform/css-stub.js

@@ -0,0 +1,4 @@
+// CSS import stub for the native runtime — bun-preload.ts resolves every
+// `.css` import here (a real file, never a virtual namespace) so Bun's
+// persistent transpile cache only ever stores a plain, replayable path.
+export default "";

package/dist/core/src/platform/glob-polyfill.js

@@ -0,0 +1,137 @@
+// ============================================================================
+// 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) {
+    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) {
+    // 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, results = []) {
+    let entries;
+    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) {
+    const fsCallerDir = mapCallerDir(callerDir);
+    return function glob(pattern, options) {
+        // Extract the non-glob prefix to find the search root
+        const patternParts = pattern.split("/");
+        let rootParts = [];
+        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 = {};
+        const normalizedPattern = pattern.replace(/^\.\//, "");
+        const matchRegex = globToRegex(normalizedPattern);
+        allFiles.forEach((file) => {
+            const relPath = relative(fsCallerDir, file).replace(/\\/g, "/");
+            // Vite-style keys: `./x` for same-dir/child paths, `../x` for parent
+            // traversal — NOT `./../x`. Callers match on these keys (startsWith
+            // on the pattern's literal prefix, endsWith on subpaths).
+            const key = relPath.startsWith("..") ? relPath : "./" + relPath;
+            if (matchRegex.test(relPath) || matchRegex.test(key)) {
+                // For ?url queries, return the file:// URL
+                result[key] = 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` — a real implementation only ever exists when a
+//      Vite transform rewrote a LITERAL `import.meta.glob(` call at the call
+//      site; a passed-around meta object can't carry it. On Vite's
+//      ModuleRunner the meta object DOES expose a `glob` property — but it
+//      is a stub that throws ("statically replaced during file
+//      transformation"), so the probe must tolerate the throw.
+//   3. `createGlob(callerDir)` — filesystem glob relative to the caller's
+//      module dir (packaged binaries, bare runtimes without the host global,
+//      and the dev ModuleRunner where `meta.glob` is the throwing stub).
+//
+// 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, meta, options) {
+    const callerDir = meta.dir ?? (meta.url ? dirname(fileURLToPath(meta.url)) : process.cwd());
+    const opts = { eager: true, query: "?url", ...options };
+    const native = globalThis.__nativeGlob;
+    if (typeof native === "function") {
+        return native(pattern, opts, callerDir);
+    }
+    if (typeof meta.glob === "function") {
+        try {
+            return meta.glob(pattern, opts);
+        }
+        catch { /* ModuleRunner stub — fall through to the filesystem glob */ }
+    }
+    return createGlob(callerDir)(pattern, opts);
+}

package/dist/core/src/platform/hidpi.js

@@ -0,0 +1,52 @@
+/**
+ * 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() {
+    if (typeof window !== "undefined" && typeof window.devicePixelRatio === "number") {
+        return window.devicePixelRatio;
+    }
+    return 1;
+}
+export class HiDPIManager {
+    scaleFactor = 1;
+    handlers = [];
+    detectScaleFactor() {
+        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() {
+        return this.scaleFactor;
+    }
+    setScaleFactor(scale) {
+        if (scale === this.scaleFactor)
+            return;
+        this.scaleFactor = scale;
+        for (let i = 0; i < this.handlers.length; i++) {
+            this.handlers[i](scale);
+        }
+    }
+    onScaleChange(fn) {
+        this.handlers.push(fn);
+    }
+    init() {
+        this.scaleFactor = this.detectScaleFactor();
+    }
+}

package/dist/core/src/platform/pkg-root.js

@@ -0,0 +1,27 @@
+// ============================================================================
+// pkg-root.ts — package-root resolution for module-relative paths
+//
+// Modules that resolve package-relative paths (native crate dirs, staged
+// asset roots) must anchor at the package root rather than hardcoding a
+// ".." segment count: the transpiled npm dist/ nests modules one level
+// deeper than src/, so source-relative math escapes into dist/.
+// ============================================================================
+import { existsSync } from "node:fs";
+import { dirname, join } from "node:path";
+/**
+ * Nearest ancestor directory containing a package.json, walking up from
+ * `fromDir`. Layout-agnostic — a module under src/ and its transpiled copy
+ * under dist/src/ resolve to the same package root. Falls back to
+ * `fromDir` when no package.json ancestor exists (bare file imports).
+ */
+export function findPackageRoot(fromDir) {
+    let dir = fromDir;
+    for (;;) {
+        if (existsSync(join(dir, "package.json")))
+            return dir;
+        const parent = dirname(dir);
+        if (parent === dir)
+            return fromDir;
+        dir = parent;
+    }
+}

package/dist/core/src/platform/render-surface.js

@@ -0,0 +1,15 @@
+// ============================================================================
+// 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.
+// ============================================================================
+export {};

package/dist/core/src/platform/rpc.js

@@ -0,0 +1,82 @@
+export class RPC {
+    handlers = new Map();
+    pending = new Map();
+    eventListeners = new Map();
+    messageIdCounter = 0;
+    sendFn = null;
+    static MAX_PENDING = 1024;
+    setSendFn(fn) {
+        this.sendFn = fn;
+    }
+    registerHandler(channel, handler) {
+        this.handlers.set(channel, handler);
+    }
+    async call(channel, payload, timeoutMs = 5000) {
+        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, payload) {
+        this.send({ type: "event", id: 0, channel, payload });
+    }
+    on(channel, fn) {
+        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) {
+        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);
+                }
+            }
+        }
+    }
+    send(msg) {
+        if (this.sendFn) {
+            this.sendFn(msg);
+        }
+    }
+}

package/dist/core/src/platform/runtime.js

@@ -0,0 +1,93 @@
+// ============================================================================
+// 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 = typeof globalThis.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 = isBun && /^\/\$bunfs\//.test(globalThis.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 = (() => {
+    // 1. Explicit env var
+    const env = globalThis.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.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 = isDev;
+/** True when HMR (hot module replacement) is available (Vite dev mode only). */
+export const hasHMR = (() => {
+    try {
+        return !!import.meta.hot;
+    }
+    catch {
+        return false;
+    }
+})();
+export const NATIVE_HOST_CAPABILITIES = {
+    runtime: "native",
+    hasDom: false,
+    hasOpfs: false,
+    supportsMultiWorkerGpu: true,
+};
+const DOM_HOST_CAPABILITIES = {
+    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() {
+    const caps = globalThis
+        .downdraft?.capabilities;
+    if (caps)
+        return caps;
+    if (globalThis.__nativeHost) {
+        return NATIVE_HOST_CAPABILITIES;
+    }
+    return DOM_HOST_CAPABILITIES;
+}
+/** 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() {
+    const host = globalThis.__nativeHost;
+    return host && typeof host === "object" ? host : null;
+}

package/dist/core/src/plugin/context.js

@@ -0,0 +1,144 @@
+// ============================================================================
+// Plugin context — the tiered capability surface exposed to a plugin.
+//
+// A plugin's `register(ctx)` receives a context whose shape depends on its
+// declared tier:
+//   - `data`   → no context (asset plugins just register assets at load).
+//   - `script` → ScriptPluginContext (events + KV state + tick + log).
+//   - `native` → NativePluginContext (extends ModuleContext-shape: ECS
+//                systems/components, typed-token provide/inject, SAB channels,
+//                onDispose, devtools). GPU/render-pass access is deferred.
+//
+// The host constructs the appropriate facade and the TypeScript types ensure
+// a script-tier plugin literally cannot call native-only APIs (the methods
+// aren't on the narrower type). At runtime the facade simply doesn't expose
+// them.
+//
+// For worker-js / wasm / quickjs plugins that run off-thread or in a VM,
+// `ctx` is a `MessageChannel`- / marshal-backed proxy to the host's real
+// context object. The interfaces below are the contract both sides share.
+// ============================================================================
+// ── Permission gating ──
+//
+// When the host passes a `granted` permission set, context APIs the plugin
+// didn't request are replaced with throwing stubs (matching the sandbox
+// shim's trap style: clear error naming the missing permission). When
+// `granted` is undefined the context is ungated — used by tests and by
+// first-party in-process callers that bypass the permission system.
+function permError(apiName, perm, pluginId) {
+    return new Error(`[downdraft:plugin] "${apiName}" requires the "${perm}" permission, which plugin "${pluginId}" was not granted ` +
+        `(check permissions[] in the manifest — requested ∩ tier-allowed ∩ game-allowlist).`);
+}
+function deniedEvents(perm, id) {
+    return {
+        subscribe: () => { throw permError("events.subscribe", perm, id); },
+        publish: () => { throw permError("events.publish", perm, id); },
+    };
+}
+function deniedState(perm, id) {
+    return {
+        get: () => { throw permError("state.get", perm, id); },
+        set: () => { throw permError("state.set", perm, id); },
+        delete: () => { throw permError("state.delete", perm, id); },
+        keys: () => { throw permError("state.keys", perm, id); },
+        save: () => Promise.reject(permError("state.save", perm, id)),
+        load: () => Promise.reject(permError("state.load", perm, id)),
+    };
+}
+function deniedTick(perm, id) {
+    return {
+        onTick: () => { throw permError("tick.onTick", perm, id); },
+    };
+}
+/** Gate the state store: `state` perm gates KV access; `storage` gates persistence. */
+function gateState(state, granted, id) {
+    if (!granted)
+        return state;
+    if (!granted.has("state"))
+        return deniedState("state", id);
+    if (!granted.has("storage")) {
+        return {
+            ...state,
+            save: () => Promise.reject(permError("state.save", "storage", id)),
+            load: () => Promise.reject(permError("state.load", "storage", id)),
+        };
+    }
+    return state;
+}
+/** Build a ScriptPluginContext facade from the backing object. */
+export function makeScriptContext(b, granted) {
+    return {
+        id: b.id,
+        events: granted && !granted.has("events") ? deniedEvents("events", b.id) : b.events,
+        state: gateState(b.state, granted, b.id),
+        tick: granted && !granted.has("tick") ? deniedTick("tick", b.id) : b.tick,
+        log: b.log,
+        onDispose: b.onDispose,
+    };
+}
+/** Host-call method → permission(s) required to invoke it. */
+const HOST_CALL_PERMS = {
+    spawnProp: ["assets", "ecs"],
+    removeProp: ["ecs"],
+    setPhysics: ["physics"],
+    getPhysics: ["physics"],
+    applyImpulse: ["physics"],
+    applyTorque: ["physics"],
+    getAssetRef: ["assets"],
+};
+/** Build a NativePluginContext facade. Throws if native backing is missing. */
+export function makeNativeContext(b, granted) {
+    if (!b.registerComponent ||
+        !b.registerSystem ||
+        !b.allocateSABChannel ||
+        !b.provide ||
+        !b.inject ||
+        !b.injectOptional ||
+        !b.devtools) {
+        throw new Error(`makeNativeContext: backing is missing native APIs (plugin "${b.id}" declared native tier but host didn't wire them).`);
+    }
+    // Gate a host-call method: check the declared permission(s) first (a clear
+    // permission error beats a missing-bridge error), then forward to the
+    // game's PluginHostCalls impl.
+    const hostCall = (name) => {
+        return (...args) => {
+            if (granted) {
+                for (let _i = 0, _it = HOST_CALL_PERMS[name] ?? [], _n = _it.length; _i < _n; _i++) {
+                    const perm = _it[_i];
+                    if (!granted.has(perm)) {
+                        return Promise.reject(permError(name, perm, b.id));
+                    }
+                }
+            }
+            const hostCalls = b.hostCalls;
+            return hostCalls?.[name]
+                ? hostCalls[name].apply(hostCalls, args)
+                : Promise.reject(new Error(`${name}: no host-call bridge wired (plugin "${b.id}")`));
+        };
+    };
+    return {
+        id: b.id,
+        events: granted && !granted.has("events") ? deniedEvents("events", b.id) : b.events,
+        state: gateState(b.state, granted, b.id),
+        tick: granted && !granted.has("tick") ? deniedTick("tick", b.id) : b.tick,
+        log: b.log,
+        onDispose: b.onDispose,
+        registerComponent: b.registerComponent,
+        registerSystem: b.registerSystem,
+        allocateSABChannel: granted && !granted.has("sab")
+            ? () => { throw permError("allocateSABChannel", "sab", b.id); }
+            : b.allocateSABChannel,
+        provide: b.provide,
+        inject: b.inject,
+        injectOptional: b.injectOptional,
+        devtools: b.devtools,
+        // Host-call bridge: permission-gated, then forwarded to the game's impl.
+        spawnProp: hostCall("spawnProp"),
+        removeProp: hostCall("removeProp"),
+        setPhysics: hostCall("setPhysics"),
+        getPhysics: hostCall("getPhysics"),
+        applyImpulse: hostCall("applyImpulse"),
+        applyTorque: hostCall("applyTorque"),
+        getAssetRef: hostCall("getAssetRef"),
+    };
+}

package/dist/core/src/plugin/diagnostics.js

@@ -0,0 +1,20 @@
+// ============================================================================
+// Plugin diagnostics — snapshot type for the doctor panel + cross-thread report.
+// ============================================================================
+/** Build a PluginInfo from a manifest + runtime status. */
+export function pluginInfoFromManifest(m, status, extra) {
+    return {
+        id: m.id,
+        name: m.name,
+        version: m.version,
+        format: m.format,
+        tier: m.tier,
+        thread: m.thread,
+        permissions: m.permissions ?? [],
+        provides: m.provides ?? [],
+        requires: m.requires ?? [],
+        dependencies: m.dependencies ?? [],
+        status,
+        ...extra,
+    };
+}