@downdraft/engine 0.1.1 → 0.1.2-alpha.5

package/dist/core/src/physics/realm.js

@@ -0,0 +1,137 @@
+export class PhysicsRealm {
+    id;
+    name;
+    tier;
+    backend;
+    bodies = new Map();
+    nextBodyId = 1;
+    constructor(backend, config) {
+        this.backend = backend;
+        this.id = config.id ?? Math.floor(Math.random() * 0x7fffffff);
+        this.name = config.name;
+        this.tier = config.tier;
+        this.backend.createRealm({ ...config, id: this.id });
+    }
+    createBody(desc, entity) {
+        const body = this.backend.createBody(this.id, desc, entity);
+        this.bodies.set(body.id, body);
+        return body;
+    }
+    destroyBody(body) {
+        this.backend.destroyBody(body);
+        this.bodies.delete(body.id);
+    }
+    addCollider(body, desc) {
+        return this.backend.addCollider(body, desc);
+    }
+    removeCollider(body, colliderId) {
+        this.backend.removeCollider(body, colliderId);
+    }
+    setBodyType(body, type) {
+        this.backend.setBodyType(body, type);
+    }
+    setPosition(body, pos) {
+        this.backend.setPosition(body, pos);
+    }
+    getPosition(body) {
+        return this.backend.getPosition(body);
+    }
+    setRotation(body, rot) {
+        this.backend.setRotation(body, rot);
+    }
+    getRotation(body) {
+        return this.backend.getRotation(body);
+    }
+    setLinearVelocity(body, vel) {
+        this.backend.setLinearVelocity(body, vel);
+    }
+    getLinearVelocity(body) {
+        return this.backend.getLinearVelocity(body);
+    }
+    setAngularVelocity(body, vel) {
+        this.backend.setAngularVelocity(body, vel);
+    }
+    getAngularVelocity(body) {
+        return this.backend.getAngularVelocity(body);
+    }
+    applyForce(body, force) {
+        this.backend.applyForce(body, force);
+    }
+    applyImpulse(body, impulse) {
+        this.backend.applyImpulse(body, impulse);
+    }
+    raycast(origin, direction, maxDistance, filter) {
+        return this.backend.raycast(this.id, origin, direction, maxDistance, filter);
+    }
+    raycastMulti(origin, direction, maxDistance, filter) {
+        return this.backend.raycastMulti(this.id, origin, direction, maxDistance, filter);
+    }
+    step(dt) {
+        this.backend.step(this.id, dt);
+    }
+    setSolverIterations(iterations) {
+        this.backend.setSolverIterations(this.id, iterations);
+    }
+    setMinIslandSize(size) {
+        if (this.backend.setMinIslandSize)
+            this.backend.setMinIslandSize(this.id, size);
+    }
+    setSleepThresholds(linearThreshold, angularThreshold) {
+        this.backend.setSleepThresholds(this.id, linearThreshold, angularThreshold);
+    }
+    getIslands() {
+        return this.backend.getIslands(this.id);
+    }
+    serialize() {
+        return this.backend.serializeRealm(this.id);
+    }
+    deserialize(data) {
+        this.backend.deserializeRealm(this.id, data);
+    }
+    getContacts() {
+        return this.backend.getContacts(this.id);
+    }
+    getIntersections() {
+        return this.backend.getIntersections(this.id);
+    }
+    createCharacterController(desc, entity) {
+        return this.backend.createCharacterController(this.id, desc, entity);
+    }
+    destroyCharacterController(handle) {
+        this.backend.destroyCharacterController(handle);
+    }
+    characterMove(handle, desiredMovement, dt) {
+        return this.backend.characterMove(handle, desiredMovement, dt);
+    }
+    createJoint(parentBody, childBody, desc) {
+        return this.backend.createJoint(this.id, parentBody, childBody, desc);
+    }
+    destroyJoint(jointId) {
+        this.backend.destroyJoint(this.id, jointId);
+    }
+    syncTransforms(transformBuffer, entityCount) {
+        this.backend.syncTransforms(this.id, transformBuffer, entityCount);
+    }
+    readTransforms(transformBuffer, entityCount) {
+        this.backend.readTransforms(this.id, transformBuffer, entityCount);
+    }
+    listBodies() {
+        return [...this.bodies.values()];
+    }
+    getBody(bodyId) {
+        return this.bodies.get(bodyId);
+    }
+    getBodyCount() {
+        return this.bodies.size;
+    }
+    getBackend() {
+        return this.backend;
+    }
+    getTier() {
+        return this.tier;
+    }
+    destroy() {
+        this.bodies.clear();
+        this.backend.destroyRealm(this.id);
+    }
+}

package/dist/core/src/physics/registry.js

@@ -0,0 +1,43 @@
+class PhysicsBackendRegistry {
+    backends = new Map();
+    defaultBackend = null;
+    register(name, backend) {
+        this.backends.set(name, backend);
+        if (!this.defaultBackend) {
+            this.defaultBackend = backend;
+        }
+    }
+    unregister(name) {
+        const backend = this.backends.get(name);
+        if (backend) {
+            backend.destroy();
+            this.backends.delete(name);
+            if (this.defaultBackend === backend) {
+                this.defaultBackend = this.backends.values().next().value ?? null;
+            }
+        }
+    }
+    get(name) {
+        return this.backends.get(name);
+    }
+    getDefault() {
+        return this.defaultBackend;
+    }
+    setDefault(name) {
+        const backend = this.backends.get(name);
+        if (!backend)
+            throw new Error(`Physics backend "${name}" not registered`);
+        this.defaultBackend = backend;
+    }
+    list() {
+        return [...this.backends.keys()];
+    }
+    destroyAll() {
+        for (const backend of this.backends.values()) {
+            backend.destroy();
+        }
+        this.backends.clear();
+        this.defaultBackend = null;
+    }
+}
+export const physicsBackendRegistry = new PhysicsBackendRegistry();

package/dist/core/src/physics/safety.js

@@ -0,0 +1,211 @@
+import { createLogger } from "../util/logger.js";
+const log = createLogger();
+export class SafetyLayer {
+    devMode;
+    states = new Map();
+    /** Sliding window size for recurrence tracking. */
+    windowSize = 100;
+    /** Recurrence threshold before escalating to hard kinematic lock. */
+    recurrenceThreshold = 3;
+    /** Bodies that have been hard-locked due to persistent NaN. */
+    hardLocked = new Set();
+    /** Consecutive valid ticks required before a hard-locked body is restored. */
+    hardLockRecoveryTicks = 60;
+    sweepTickCounter = 0;
+    constructor(opts = {}) {
+        this.devMode = opts.devMode ?? false;
+    }
+    /** Assert a number is finite. Branchless hot-path variant available. */
+    assertFinite(x, name) {
+        // Branchless check: NaN !== NaN, Inf - Inf !== 0
+        if (x !== x || !Number.isFinite(x)) {
+            this.reportViolation(`Non-finite value for ${name}: ${x}`);
+        }
+    }
+    /** Fast branchless finiteness check (for hot paths). */
+    isFiniteFast(x) {
+        return (x - x) === 0;
+    }
+    /** Assert a vector is finite. */
+    assertFiniteVec3(v, name) {
+        this.assertFinite(v[0], `${name}.x`);
+        this.assertFinite(v[1], `${name}.y`);
+        this.assertFinite(v[2], `${name}.z`);
+    }
+    /** Assert a quaternion is finite and non-degenerate. */
+    assertFiniteQuat(q, name) {
+        this.assertFinite(q[0], `${name}.x`);
+        this.assertFinite(q[1], `${name}.y`);
+        this.assertFinite(q[2], `${name}.z`);
+        this.assertFinite(q[3], `${name}.w`);
+        const len = Math.sqrt(q[0] ** 2 + q[1] ** 2 + q[2] ** 2 + q[3] ** 2);
+        if (len < 1e-9) {
+            this.reportViolation(`Degenerate (zero-norm) quaternion for ${name}`);
+        }
+    }
+    /** Assert physical validity of a body descriptor. */
+    assertBodyDescValid(desc) {
+        if (desc.type === "dynamic") {
+            const mass = desc.mass ?? 1;
+            if (mass <= 0) {
+                this.reportViolation(`Dynamic body has non-positive mass: ${mass}`);
+            }
+        }
+        this.assertFiniteVec3(desc.position, "desc.position");
+        this.assertFiniteQuat(desc.rotation, "desc.rotation");
+        if (desc.linearVelocity)
+            this.assertFiniteVec3(desc.linearVelocity, "desc.linearVelocity");
+        if (desc.angularVelocity)
+            this.assertFiniteVec3(desc.angularVelocity, "desc.angularVelocity");
+    }
+    /** Sanitize a value: clamp to 0 if non-finite (shipped) or throw (dev). */
+    sanitize(x) {
+        if (x !== x || !Number.isFinite(x)) {
+            this.reportViolation(`Sanitizing non-finite value: ${x}`);
+            return 0;
+        }
+        return x;
+    }
+    /** Sanitize a vec3 in place. */
+    sanitizeVec3(v) {
+        return [this.sanitize(v[0]), this.sanitize(v[1]), this.sanitize(v[2])];
+    }
+    /** Sanitize a quaternion (normalize, fallback to identity if degenerate). */
+    sanitizeQuat(q) {
+        let x = this.sanitize(q[0]);
+        let y = this.sanitize(q[1]);
+        let z = this.sanitize(q[2]);
+        let w = this.sanitize(q[3]);
+        const len = Math.sqrt(x * x + y * y + z * z + w * w);
+        if (len < 1e-9) {
+            this.reportViolation("Degenerate quaternion sanitized to identity");
+            return [0, 0, 0, 1];
+        }
+        return [x / len, y / len, z / len, w / len];
+    }
+    /**
+     * Post-step sanitization sweep. Checks finiteness of pos/rot/linVel/angVel
+     * for the given bodies. On invalid: zero velocities, revert to
+     * lastKnownGood, and track recurrence. Persistent offenders are
+     * hard-locked to kinematic.
+     */
+    sanitizeSolverOutput(backend, bodies) {
+        for (let _i = 0, _it = bodies, _n = _it.length; _i < _n; _i++) {
+            const body = _it[_i];
+            if (this.hardLocked.has(body.id))
+                continue;
+            const pos = backend.getPosition(body);
+            const rot = backend.getRotation(body);
+            const linVel = backend.getLinearVelocity(body);
+            const angVel = backend.getAngularVelocity(body);
+            const posOk = this.isFiniteFast(pos[0]) && this.isFiniteFast(pos[1]) && this.isFiniteFast(pos[2]);
+            const rotOk = this.isFiniteFast(rot[0]) && this.isFiniteFast(rot[1]) && this.isFiniteFast(rot[2]) && this.isFiniteFast(rot[3]);
+            const velOk = this.isFiniteFast(linVel[0]) && this.isFiniteFast(linVel[1]) && this.isFiniteFast(linVel[2]);
+            const angOk = this.isFiniteFast(angVel[0]) && this.isFiniteFast(angVel[1]) && this.isFiniteFast(angVel[2]);
+            if (posOk && rotOk && velOk && angOk) {
+                // Update lastKnownGood and reset recurrence counter
+                let state = this.states.get(body.id);
+                if (!state) {
+                    state = {
+                        lastKnownGoodPos: [...pos],
+                        lastKnownGoodRot: [...rot],
+                        recurrenceCount: 0,
+                        validTickCount: 0,
+                    };
+                    this.states.set(body.id, state);
+                }
+                else {
+                    state.lastKnownGoodPos = [...pos];
+                    state.lastKnownGoodRot = [...rot];
+                    state.recurrenceCount = 0;
+                }
+                // Recovery path for hard-locked bodies: after enough consecutive
+                // valid ticks, restore the body to dynamic and remove from hardLocked.
+                if (this.hardLocked.has(body.id)) {
+                    state.validTickCount++;
+                    if (state.validTickCount >= this.hardLockRecoveryTicks) {
+                        this.reportViolation(`Body ${body.id} recovered after ${state.validTickCount} valid ticks — restoring to dynamic`);
+                        backend.setBodyType(body, "dynamic");
+                        this.hardLocked.delete(body.id);
+                        state.validTickCount = 0;
+                    }
+                }
+                else if (state.validTickCount > 0) {
+                    state.validTickCount = 0;
+                }
+                continue;
+            }
+            // Invalid state detected — sanitize
+            this.reportViolation(`Solver output invalid for body ${body.id}: pos=${pos}, rot=${rot}`);
+            let state = this.states.get(body.id);
+            if (!state) {
+                state = {
+                    lastKnownGoodPos: [0, 0, 0],
+                    lastKnownGoodRot: [0, 0, 0, 1],
+                    recurrenceCount: 0,
+                    validTickCount: 0,
+                };
+                this.states.set(body.id, state);
+            }
+            // Revert to lastKnownGood
+            backend.setPosition(body, state.lastKnownGoodPos);
+            backend.setRotation(body, state.lastKnownGoodRot);
+            // Zero velocities
+            backend.setLinearVelocity(body, [0, 0, 0]);
+            backend.setAngularVelocity(body, [0, 0, 0]);
+            // Track recurrence
+            state.recurrenceCount++;
+            if (state.recurrenceCount >= this.recurrenceThreshold) {
+                // Escalate: hard kinematic lock
+                this.reportViolation(`Body ${body.id} hard-locked due to persistent NaN (${state.recurrenceCount}/${this.windowSize})`);
+                backend.setBodyType(body, "kinematic");
+                this.hardLocked.add(body.id);
+            }
+        }
+    }
+    /**
+     * Periodic finite sweep — trust-but-verify for internally-generated bad
+     * state (solver output, realm-transfer state). Runs every `interval` ticks.
+     * Only sweeps bodies above `velocityThreshold` (skip sleeping/stationary).
+     */
+    periodicFiniteSweep(backend, bodies, interval, velocityThreshold) {
+        this.sweepTickCounter++;
+        if (this.sweepTickCounter % interval !== 0)
+            return;
+        for (let _i = 0, _it = bodies, _n = _it.length; _i < _n; _i++) {
+            const body = _it[_i];
+            if (this.hardLocked.has(body.id))
+                continue;
+            const vel = backend.getLinearVelocity(body);
+            const speed = Math.sqrt(vel[0] ** 2 + vel[1] ** 2 + vel[2] ** 2);
+            if (speed < velocityThreshold)
+                continue;
+            // Check finiteness
+            const pos = backend.getPosition(body);
+            if (!this.isFiniteFast(pos[0]) || !this.isFiniteFast(pos[1]) || !this.isFiniteFast(pos[2])) {
+                this.reportViolation(`Periodic sweep found invalid pos for body ${body.id}`);
+                // Delegate to sanitizeSolverOutput for full handling
+            }
+        }
+    }
+    isHardLocked(bodyId) {
+        return this.hardLocked.has(bodyId);
+    }
+    getHardLockedCount() {
+        return this.hardLocked.size;
+    }
+    reset() {
+        this.states.clear();
+        this.hardLocked.clear();
+        this.sweepTickCounter = 0;
+    }
+    reportViolation(msg) {
+        if (this.devMode) {
+            throw new Error(`[Physics Safety] ${msg}`);
+        }
+        else {
+            // Shipped: log and continue (never crash)
+            log.warn("physics-safety", msg);
+        }
+    }
+}

package/dist/core/src/physics/snapshot-manager.js

@@ -0,0 +1,118 @@
+import { RealmTier } from "./interface.js";
+/**
+ * Snapshot manager for multiplayer / save-state support.
+ *
+ * - Realms are snapshotted independently at configurable frequencies.
+ * - Near realm: every `snapshotInterval` ticks (default 30).
+ * - Mid/far realms: less frequent (2× / 4× the interval).
+ * - `onLateJoin(playerId)`: full snapshot + hook.
+ * - `onReconnect(playerId, lastSeenTick)`: delta from lastSeen.
+ * - `predictionMode` configures snapshot frequency + reconciliation needs.
+ *
+ * API surface only — no networking transport (games provide their own).
+ */
+export class SnapshotManager {
+    realmManager;
+    backend;
+    snapshotInterval;
+    predictionMode;
+    hooks = null;
+    tickCount = 0;
+    /** Last snapshot per realm tier. */
+    lastSnapshots = new Map();
+    /** Per-player last-seen tick (for reconnect delta). */
+    playerLastSeen = new Map();
+    constructor(opts) {
+        this.realmManager = opts.realmManager;
+        this.backend = opts.backend;
+        this.snapshotInterval = opts.snapshotInterval ?? 30;
+        this.predictionMode = opts.predictionMode ?? "server-authoritative";
+    }
+    setSnapshotHooks(hooks) {
+        this.hooks = hooks;
+    }
+    /**
+     * Called every tick. Snapshots realms at their respective frequencies.
+     */
+    tick() {
+        this.tickCount++;
+        // Near: every snapshotInterval ticks
+        if (this.tickCount % this.snapshotInterval === 0) {
+            this.snapshotRealm(RealmTier.Near);
+        }
+        // Mid: every 2× the interval
+        if (this.tickCount % (this.snapshotInterval * 2) === 0) {
+            this.snapshotRealm(RealmTier.Mid);
+        }
+        // Far: every 4× the interval
+        if (this.tickCount % (this.snapshotInterval * 4) === 0) {
+            this.snapshotRealm(RealmTier.Far);
+        }
+    }
+    /**
+     * Snapshot a specific realm tier.
+     */
+    snapshotRealm(tier) {
+        const realm = this.realmManager.getRealm(tier);
+        const data = realm.serialize();
+        this.lastSnapshots.set(tier, { data, tick: this.tickCount });
+        this.hooks?.onSnapshot?.(tier, data, this.tickCount);
+        return data;
+    }
+    /**
+     * Restore a realm from snapshot data.
+     */
+    restoreRealm(tier, data) {
+        const realm = this.realmManager.getRealm(tier);
+        realm.deserialize(data);
+        this.hooks?.onRestore?.(tier, this.tickCount);
+    }
+    /**
+     * Snapshot all realms. Returns a map of tier → snapshot data.
+     */
+    snapshotAll() {
+        const result = new Map();
+        [RealmTier.Near, RealmTier.Mid, RealmTier.Far].forEach((tier) => {
+            result.set(tier, this.snapshotRealm(tier));
+        });
+        return result;
+    }
+    /**
+     * Late join: full snapshot of all realms for a new player.
+     * Invokes the `onLateJoin` hook if set.
+     */
+    onLateJoin(playerId) {
+        const snapshots = this.snapshotAll();
+        this.playerLastSeen.set(playerId, this.tickCount);
+        this.hooks?.onLateJoin?.(playerId, snapshots, this.tickCount);
+        return snapshots;
+    }
+    /**
+     * Reconnect: delta snapshot from the player's last seen tick.
+     * In server-authoritative mode, this is a full snapshot (no delta).
+     * In client-prediction mode, the hook can compute a delta.
+     */
+    onReconnect(playerId, lastSeenTick) {
+        const snapshots = this.snapshotAll();
+        this.playerLastSeen.set(playerId, this.tickCount);
+        this.hooks?.onReconnect?.(playerId, lastSeenTick, snapshots, this.tickCount);
+        return snapshots;
+    }
+    /**
+     * Get the last snapshot for a realm tier (or null if none).
+     */
+    getLastSnapshot(tier) {
+        return this.lastSnapshots.get(tier) ?? null;
+    }
+    getTickCount() {
+        return this.tickCount;
+    }
+    getPredictionMode() {
+        return this.predictionMode;
+    }
+    reset() {
+        this.tickCount = 0;
+        this.lastSnapshots.clear();
+        this.playerLastSeen.clear();
+    }
+}

package/dist/core/src/physics/worker-protocol.js

@@ -0,0 +1 @@
+export {};

package/dist/core/src/platform/bun-preload.js

@@ -0,0 +1,175 @@
+import { fileURLToPath as __ddFileURLToPath } from "node:url";
+const __ddMetaDir = __ddFileURLToPath(new URL(".", import.meta.url));
+// ============================================================================
+// Bun preload — registers plugin loaders for Vite-specific import patterns
+//
+// This file is referenced by bunfig.toml's `preload` field and executes before
+// any user code. It registers Bun.plugin() loaders that handle:
+//
+//   1. `*.wgsl?raw` — WGSL shader imports (returns the file text as default export)
+//   2. `*.wgsl`     — bare WGSL imports (same as ?raw)
+//   3. `*.css`      — CSS imports (returns empty string — no DOM in native mode)
+//   4. `*?url`      — asset URL imports (returns the file path as default export)
+//   5. `*.glsl?raw` — GLSL shader imports (if any exist)
+//   6. `*.txt?raw`  — raw text imports
+//
+// In Vite mode, Vite's own loaders handle these patterns. In Bun-native mode,
+// this preload script is the replacement.
+//
+// This file MUST be safe to import under both Bun and Node/Vite. Under Node/Vite
+// it's a no-op (Bun.plugin is undefined).
+// ============================================================================
+// Guard: only register under Bun
+if (typeof globalThis.Bun !== "undefined" && typeof globalThis.Bun.plugin === "function") {
+    const Bun = globalThis.Bun;
+    // ── WGSL shader loader (?raw and bare) ──
+    // Matches: "./foo.wgsl?raw", "./foo.wgsl"
+    // Also validates with naga in-process via libdowndraft_platform (build-time
+    // parity with the Vite wgslValidatePlugin). Disabled when
+    // DOWNDRAFT_SHADER_VALIDATE=0 or the native validator is unavailable.
+    Bun.plugin({
+        name: "downdraft-wgsl-loader",
+        setup(build) {
+            // Native validator resolution — best-effort, cached after first call.
+            let validateNative = undefined;
+            function getValidator() {
+                if (validateNative !== undefined)
+                    return validateNative;
+                try {
+                    const { validateWgslNative } = require("@downdraft/platform-native");
+                    validateNative = validateWgslNative;
+                }
+                catch {
+                    validateNative = null;
+                }
+                return validateNative;
+            }
+            // Fragment shaders that only compile when concatenated with shared
+            // preludes declare them with `// wgsl-validate: prelude <file>`
+            // (mirrors the Vite wgslValidatePlugin). Unconcatenable chunks opt out
+            // entirely with `// wgsl-validate: skip`.
+            function applyPreludePragmas(source, filePath) {
+                const { readFileSync } = require("node:fs");
+                const { dirname, resolve } = require("node:path");
+                const parts = [];
+                for (const m of source.matchAll(/^\/\/\s*wgsl-validate:\s*prelude\s+(\S+)\s*$/gm)) {
+                    try {
+                        parts.push(readFileSync(resolve(dirname(filePath), m[1]), "utf-8"));
+                    }
+                    catch { }
+                }
+                return parts.length ? parts.join("\n") + "\n" + source : source;
+            }
+            function validateWgsl(path, text) {
+                if (process.env.DOWNDRAFT_SHADER_VALIDATE === "0")
+                    return;
+                if (/^\/\/\s*wgsl-validate:\s*skip\s*$/m.test(text))
+                    return;
+                const validate = getValidator();
+                if (!validate)
+                    return;
+                const result = validate(applyPreludePragmas(text, path), path);
+                if (result !== null && !result.ok) {
+                    throw new Error(`WGSL validation failed for ${path}:\n${result.errors.join("\n")}`);
+                }
+            }
+            // ?raw variant
+            build.onLoad({ filter: /\.wgsl\?raw$/ }, async (args) => {
+                const path = args.path.replace(/\?raw$/, "");
+                const text = await Bun.file(path).text();
+                validateWgsl(path, text);
+                return { exports: { default: text }, loader: "object" };
+            });
+            // Bare .wgsl (no ?raw suffix) — also return text
+            build.onLoad({ filter: /[^?]\.wgsl$/ }, async (args) => {
+                const text = await Bun.file(args.path).text();
+                validateWgsl(args.path, text);
+                return { exports: { default: text }, loader: "object" };
+            });
+        },
+    });
+    // ── GLSL shader loader (?raw) ──
+    Bun.plugin({
+        name: "downdraft-glsl-loader",
+        setup(build) {
+            build.onLoad({ filter: /\.glsl\?raw$/ }, async (args) => {
+                const path = args.path.replace(/\?raw$/, "");
+                const text = await Bun.file(path).text();
+                return { exports: { default: text }, loader: "object" };
+            });
+        },
+    });
+    // ── CSS loader (returns empty string — no DOM in native mode) ──
+    // Matches: "./globals.css", "@fontsource/doto/400.css"
+    Bun.plugin({
+        name: "downdraft-css-loader",
+        setup(build) {
+            const { resolve } = require("node:path");
+            // Resolve EVERY .css import — real files and exports-map-hidden package
+            // CSS alike — to a real stub file. Bun bakes the resolved specifier into
+            // its persistent transpile cache (~/.bun/install/cache/@t@/*.pile), so
+            // the result must be a plain path that replays without this plugin
+            // (e.g. `bun dev-shell.mjs` / `bun run` from a game dir, where the root
+            // bunfig.toml preload doesn't apply). A virtual "dd-css:<path>"
+            // namespace gets cached as a package-looking specifier: re-resolution
+            // wraps it in another "dd-css:<dir>" layer per ancestor walked, looping
+            // forever at "/" until ENAMETOOLONG.
+            // Prefer the .ts sibling in source layouts; the transpiled npm dist
+            // ships css-stub.js. Both are safe baked specifiers — neither
+            // re-matches this /\.css$/ filter.
+            const { existsSync } = require("node:fs");
+            const tsStub = resolve(__ddMetaDir, "css-stub.ts");
+            const stub = existsSync(tsStub)
+                ? tsStub
+                : resolve(__ddMetaDir, "css-stub.js");
+            build.onResolve({ filter: /\.css$/ }, () => ({ path: stub }));
+            // Transpile-cache entries written by older versions still carry
+            // "dd-css:<...>" specifiers — Bun routes those straight to the namespace
+            // loader, so keep answering them until the entries age out.
+            build.onLoad({ filter: /.*/, namespace: "dd-css" }, () => ({
+                exports: { default: "" }, loader: "object",
+            }));
+        },
+    });
+    // ── ?url asset loader (returns file path as string) ──
+    // Matches: "./model.fbx?url", "./texture.png?url"
+    Bun.plugin({
+        name: "downdraft-url-loader",
+        setup(build) {
+            build.onLoad({ filter: /\?url$/ }, async (args) => {
+                const path = args.path.replace(/\?url$/, "");
+                return { exports: { default: path }, loader: "object" };
+            });
+        },
+    });
+    // ── ?raw text loader (generic, non-shader) ──
+    // Matches: "./data.txt?raw", "./config.json?raw"
+    Bun.plugin({
+        name: "downdraft-raw-text-loader",
+        setup(build) {
+            build.onLoad({ filter: /\?raw$/ }, async (args) => {
+                // Skip if already handled by wgsl/glsl loaders
+                if (args.path.endsWith(".wgsl?raw") || args.path.endsWith(".glsl?raw"))
+                    return undefined;
+                const path = args.path.replace(/\?raw$/, "");
+                const text = await Bun.file(path).text();
+                return { exports: { default: text }, loader: "object" };
+            });
+        },
+    });
+    // ── import.meta.glob ──
+    // Vite's import.meta.glob() is a compile-time transform — there is no way to
+    // polyfill it from a preload script (assigning to this module's import.meta
+    // has no effect on callers). Callers that need globbing in native mode must
+    // use createGlob(import.meta.dir) from "./glob-polyfill" — see
+    // games/to-the-ocean/src/engine/webgpu-renderer.ts for the pattern.
+}
+// ── Native-host marker ──
+// Games detect the native runtime via globalThis.__nativeHost. Module-eval-time
+// checks (top-level import.meta.glob fallbacks, feature gates) run BEFORE
+// createNativeHost() can install the real host object, so seed a truthy marker
+// here — createNativeHost() replaces it with the actual host instance later.
+if (typeof globalThis.Bun !== "undefined") {
+    globalThis.__nativeHost ??= true;
+}
+export {};