@driftengine/package 3.61.0

package/dist/preload/bridge.d.ts

@@ -0,0 +1,77 @@
+import type { DisplayInfo, WindowMode } from '@driftengine/core';
+/**
+ * The single surface the renderer can see, and the only one it ever gets.
+ *
+ * **This file is a security boundary, and it is deliberately small enough to read in full.**
+ * `contextIsolation` is on and `nodeIntegration` is off, so a game — which may run third-party
+ * code, a shader from a URL, or a mod — reaches the operating system through exactly these
+ * members and nothing else. Adding one is a decision about what a compromised renderer can do.
+ *
+ * **`storeSnapshot` is a snapshot, not a live view.** `KeyValueStore.read` is synchronous by the
+ * engine's contract, because preferences are read during boot and an await there is a visible
+ * flicker on every load. IPC is asynchronous. So the main process reads the store from disk once,
+ * before the window exists, and hands it over whole; writes go the other way and do not block.
+ * **What this costs**: two windows of one application would not see each other's writes, which is
+ * why the main process makes the application single-instance.
+ */
+export interface DriftHostBridge {
+    readonly storeSnapshot: Readonly<Record<string, string>>;
+    writeKey(key: string, value: string): void;
+    removeKey(key: string): void;
+    setFullscreen(on: boolean): Promise<void>;
+    isFullscreen(): boolean;
+    /**
+     * A call rather than a value, unlike the store snapshot beside it.
+     *
+     * Every other read here is taken once at preload because it cannot change; these can. A window
+     * dragged to a second monitor changes its refresh rate, its size and which display it is on, and
+     * a settings screen showing the value from boot would be showing the wrong monitor's.
+     */
+    refreshHz(): number | null;
+    mode(): WindowMode;
+    setMode(mode: WindowMode): Promise<boolean>;
+    size(): {
+        width: number;
+        height: number;
+    };
+    /**
+     * Whether `setSize` would work right now.
+     *
+     * Synchronous like `size()` beside it, and for the same reason: a settings screen asks while it
+     * is drawing a control, and an answer that arrived a frame later would draw the control twice.
+     * The main process decides it with the same function that decides whether `setSize` refuses —
+     * two conditions written twice would drift into a greyed control that works.
+     */
+    canSetSize(): boolean;
+    setSize(width: number, height: number): Promise<boolean>;
+    displays(): readonly DisplayInfo[];
+    onFocusChange(handler: (focused: boolean) => void): () => void;
+    onQuitRequest(handler: () => void): () => void;
+    /** Whether `requestQuit` ends the process here. False on a platform that does not exit. */
+    canQuit: boolean;
+    requestQuit(): void;
+    openFile(accept: readonly string[]): Promise<{
+        name: string;
+        bytes: Uint8Array;
+    } | null>;
+    saveFile(name: string, bytes: Uint8Array): Promise<boolean>;
+    /**
+     * A store's own features, when there is a store and it answered.
+     *
+     * **The SDK lives in the main process and can only live there.** `steamworks.js` is a native
+     * Node module and the renderer runs sandboxed with no Node at all, so a game reaching for Steam
+     * directly is a game reaching for something that is not in its process. It crosses here like
+     * every other capability.
+     *
+     * `available` is false when the manifest named no app, when the module is not installed, or when
+     * the copy was launched outside Steam — all three of which are ordinary, and none of which is a
+     * reason for a game to refuse to start.
+     */
+    readonly platform: {
+        readonly available: boolean;
+        unlockAchievement(id: string): void;
+        setRichPresence(text: string): void;
+    };
+}
+/** Where the bridge lands on `globalThis`. One name, so a game can feature-detect the shell. */
+export declare const BRIDGE_KEY = "__driftHost";

package/dist/preload/bridge.js

@@ -0,0 +1,2 @@
+/** Where the bridge lands on `globalThis`. One name, so a game can feature-detect the shell. */
+export const BRIDGE_KEY = '__driftHost';

package/dist/preload/entry.d.ts

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

package/dist/preload/entry.js

@@ -0,0 +1,77 @@
+import { contextBridge, ipcRenderer } from 'electron';
+/**
+ * Everything the renderer will ever be able to reach, assembled once.
+ *
+ * `contextBridge` is what keeps this a boundary rather than a suggestion: the renderer sees the
+ * object below and no `require`, no `ipcRenderer`, and no `process`.
+ *
+ * **Written as an ES module and emitted as CommonJS.** A sandboxed preload is loaded before ES
+ * modules exist in that context, so the artifact must be `preload.cjs` — but the module format is
+ * the builder's decision rather than the source's, and a `.cts` file cannot use `import` at all
+ * under this repository's `verbatimModuleSyntax`.
+ *
+ * **Three values are read synchronously at load.** The store snapshot is what lets the engine's
+ * `KeyValueStore` stay synchronous — see `bridge.ts` — and fullscreen and refresh rate are read
+ * once here rather than per call so a settings screen never blocks a frame on IPC.
+ */
+const snapshot = ipcRenderer.sendSync('drift:snapshot');
+const bridge = {
+    storeSnapshot: snapshot,
+    writeKey: (key, value) => {
+        ipcRenderer.send('drift:write', key, value);
+    },
+    removeKey: (key) => {
+        ipcRenderer.send('drift:remove', key);
+    },
+    setFullscreen: (on) => ipcRenderer.invoke('drift:setFullscreen', on),
+    isFullscreen: () => ipcRenderer.sendSync('drift:isFullscreen'),
+    /* Read on every call, not once: a window moved to another monitor changes all four of these,
+       and a settings screen is exactly where somebody looks after moving it. */
+    refreshHz: () => ipcRenderer.sendSync('drift:refreshHz'),
+    mode: () => ipcRenderer.sendSync('drift:mode'),
+    setMode: (mode) => ipcRenderer.invoke('drift:setMode', mode),
+    size: () => ipcRenderer.sendSync('drift:size'),
+    canSetSize: () => ipcRenderer.sendSync('drift:canSetSize'),
+    setSize: (width, height) => ipcRenderer.invoke('drift:setSize', width, height),
+    displays: () => ipcRenderer.sendSync('drift:displays'),
+    onFocusChange: (handler) => {
+        const listener = (_event, focused) => handler(focused);
+        ipcRenderer.on('drift:focus', listener);
+        return () => {
+            ipcRenderer.removeListener('drift:focus', listener);
+        };
+    },
+    onQuitRequest: (handler) => {
+        /*
+         * **Registering interest is what makes a quit fast for everybody else.** The main process
+         * defers a window close only for a game that asked to be told; without this signal the only
+         * correct implementation waits a grace period on every close, including for the games that
+         * had nothing to say.
+         */
+        ipcRenderer.send('drift:quitInterest');
+        const listener = () => handler();
+        ipcRenderer.on('drift:quitRequest', listener);
+        return () => {
+            ipcRenderer.removeListener('drift:quitRequest', listener);
+        };
+    },
+    /* A desktop shell can always close its own window, which is most of the point of having one. */
+    canQuit: true,
+    requestQuit: () => {
+        ipcRenderer.send('drift:quit');
+    },
+    openFile: (accept) => ipcRenderer.invoke('drift:openFile', accept),
+    saveFile: (name, bytes) => ipcRenderer.invoke('drift:saveFile', name, bytes),
+    platform: {
+        /* Read once: whether a store answered is decided before the window exists and does not
+           change while the game is running. */
+        available: ipcRenderer.sendSync('drift:platformAvailable'),
+        unlockAchievement: (id) => {
+            ipcRenderer.send('drift:achievement', id);
+        },
+        setRichPresence: (text) => {
+            ipcRenderer.send('drift:presence', text);
+        },
+    },
+};
+contextBridge.exposeInMainWorld('__driftHost', bridge);

package/dist/renderer/fileStore.d.ts

@@ -0,0 +1,23 @@
+import type { KeyValueStore } from '@driftengine/core';
+import type { DriftHostBridge } from '../preload/bridge.ts';
+/**
+ * The engine's persistence seam, backed by a file the shell owns.
+ *
+ * Reads come from a snapshot taken before the window opened and from this session's own writes;
+ * writes go to the main process and do not block. That is precisely the arrangement
+ * `KeyValueStore`'s own doc comment prescribes for an asynchronous backend — hydrate a cache
+ * first, make `write` fire-and-forget — and it is why the interface never needed widening for
+ * this.
+ *
+ * **What this costs**: a write that fails on disk is not reported here. The main process logs it;
+ * the game continues with the value in memory, which is the same degradation `BrowserStore` makes
+ * when `localStorage` throws. A preference is never worth failing a boot for.
+ */
+export declare class FileStore implements KeyValueStore {
+    private readonly bridge;
+    private readonly entries;
+    constructor(bridge: DriftHostBridge);
+    read(key: string): string | null;
+    write(key: string, value: string): void;
+    remove(key: string): void;
+}

package/dist/renderer/fileStore.js

@@ -0,0 +1,33 @@
+/**
+ * The engine's persistence seam, backed by a file the shell owns.
+ *
+ * Reads come from a snapshot taken before the window opened and from this session's own writes;
+ * writes go to the main process and do not block. That is precisely the arrangement
+ * `KeyValueStore`'s own doc comment prescribes for an asynchronous backend — hydrate a cache
+ * first, make `write` fire-and-forget — and it is why the interface never needed widening for
+ * this.
+ *
+ * **What this costs**: a write that fails on disk is not reported here. The main process logs it;
+ * the game continues with the value in memory, which is the same degradation `BrowserStore` makes
+ * when `localStorage` throws. A preference is never worth failing a boot for.
+ */
+export class FileStore {
+    bridge;
+    entries = new Map();
+    constructor(bridge) {
+        this.bridge = bridge;
+        for (const [key, value] of Object.entries(bridge.storeSnapshot))
+            this.entries.set(key, value);
+    }
+    read(key) {
+        return this.entries.get(key) ?? null;
+    }
+    write(key, value) {
+        this.entries.set(key, value);
+        this.bridge.writeKey(key, value);
+    }
+    remove(key) {
+        this.entries.delete(key);
+        this.bridge.removeKey(key);
+    }
+}

package/dist/renderer/host.d.ts

@@ -0,0 +1,45 @@
+import type { DisplayControl, FileDialogs, KeyValueStore, Lifecycle, PlatformServices, ScreenPresentation } from '@driftengine/core';
+/**
+ * Every capability the engine takes, chosen for wherever this build is running.
+ *
+ * **One call, at boot, and no platform test anywhere else.** A game shipped to a browser and
+ * packaged for a desktop is one bundle; the difference between them is which objects these five
+ * fields hold, and finding that out is this function's job rather than a game's. What a game
+ * writes against is the interfaces — so its own settings menu calls `display.setMode`,
+ * `display.setSize` and `display.displays()` the same way in both, and reads `false` from the ones
+ * a browser genuinely cannot do rather than discovering nothing happened.
+ *
+ * ```ts
+ * const host = createHost(canvas);
+ * const { renderer } = await createRenderer(canvas, quality);
+ * const settings = loadPreferences(host.store, SCHEMA);
+ * await host.display.setMode(settings.fullscreen ? 'fullscreen' : 'windowed');
+ * ```
+ *
+ * **`screen` is the browser implementation on every platform including the shell**, and that is
+ * not an omission: orientation, safe-area insets and the wake lock are answered by Chromium
+ * itself, so a native override would be a second implementation of the same answers. A phone host
+ * supplies its own where the WebView cannot answer — see the mobile plan.
+ *
+ * **`native` is for telling somebody**, not for branching: a build badge, a bug report, a
+ * "restart required" line. A game that branches on it is doing what this function exists to
+ * prevent.
+ */
+export interface Host {
+    /** Whether a shell supplied these, rather than the browser. */
+    readonly native: boolean;
+    readonly display: DisplayControl;
+    readonly lifecycle: Lifecycle;
+    readonly files: FileDialogs;
+    readonly store: KeyValueStore;
+    readonly screen: ScreenPresentation;
+    /**
+     * A store's own features, or null where there is no store.
+     *
+     * Null in a browser, null in a shell whose manifest named no app, and null when the copy was
+     * launched outside the store — a game checks once and never calls it, rather than calling into
+     * something that quietly does nothing.
+     */
+    readonly services: PlatformServices | null;
+}
+export declare function createHost(surface: HTMLElement): Host;

package/dist/renderer/host.js

@@ -0,0 +1,30 @@
+import { BrowserDisplay, BrowserFileDialogs, BrowserLifecycle, BrowserScreenPresentation, BrowserStore, } from '@driftengine/core';
+import { showDeviceReport } from '../mobile/report.js';
+import { FileStore } from './fileStore.js';
+import { NativeDisplay, NativeFileDialogs, NativeLifecycle, NativePlatformServices, hostBridge, } from './nativeHost.js';
+export function createHost(surface) {
+    /* `?report=1` draws what the device says about itself over the game, on every platform. It is
+       how a shader that compiles here and not on a phone gets attributed to a WebView build. */
+    showDeviceReport();
+    const bridge = hostBridge();
+    if (bridge === null) {
+        return {
+            native: false,
+            display: new BrowserDisplay(surface),
+            lifecycle: new BrowserLifecycle(),
+            files: new BrowserFileDialogs(),
+            store: new BrowserStore(),
+            screen: new BrowserScreenPresentation(),
+            services: null,
+        };
+    }
+    return {
+        native: true,
+        display: new NativeDisplay(bridge),
+        lifecycle: new NativeLifecycle(bridge),
+        files: new NativeFileDialogs(bridge),
+        store: new FileStore(bridge),
+        screen: new BrowserScreenPresentation(),
+        services: bridge.platform.available ? new NativePlatformServices(bridge) : null,
+    };
+}

package/dist/renderer/nativeHost.d.ts

@@ -0,0 +1,83 @@
+import type { DisplayControl, DisplayInfo, FileDialogs, Lifecycle, OpenedFile, PlatformServices, WindowMode } from '@driftengine/core';
+import type { DriftHostBridge } from '../preload/bridge.ts';
+/**
+ * The engine's capability interfaces, implemented over the shell's one bridge.
+ *
+ * Each of these is the native half of a pair whose browser half ships in the engine. The pairs
+ * differ in exactly the places a browser cannot answer honestly: a refresh rate is a number here
+ * and null there, and quitting works here and warns there.
+ *
+ * **A game is one bundle.** `hostBridge()` answers null in a plain browser rather than throwing,
+ * so a consumer picks its implementations at boot and ships the same code to both.
+ */
+export declare function hostBridge(): DriftHostBridge | null;
+/**
+ * The video half of a settings screen, on a platform that can actually answer it.
+ *
+ * Every member here is the same call the browser implementation makes and refuses. That is the
+ * point of the pair: a game writes one settings screen against `DisplayControl`, and it is fully
+ * populated in a shell and honestly degraded in a tab — a resolution list that reports `false`
+ * from `setSize` is a control the game greys out rather than one that silently does nothing.
+ */
+export declare class NativeDisplay implements DisplayControl {
+    private readonly bridge;
+    constructor(bridge: DriftHostBridge);
+    /**
+     * A real number, which is the whole reason the browser implementation returns null.
+     *
+     * Read on each access rather than captured in the constructor: a window moved to another
+     * monitor changes it, and a value from boot would be the previous monitor's.
+     */
+    get refreshHz(): number | null;
+    isFullscreen(): boolean;
+    setFullscreen(on: boolean): Promise<void>;
+    mode(): WindowMode;
+    setMode(mode: WindowMode): Promise<boolean>;
+    size(): {
+        readonly width: number;
+        readonly height: number;
+    };
+    /**
+     * The question, asked without performing the resize.
+     *
+     * The shell decides it with the same function that decides whether `setSize` refuses, so the two
+     * cannot disagree — see `main/ipc.ts`. Before this existed the only way to learn the answer was
+     * to call `setSize`, and a consumer's settings screen probed it at boot by resizing the window to
+     * the size it already had.
+     */
+    canSetSize(): boolean;
+    setSize(width: number, height: number): Promise<boolean>;
+    displays(): readonly DisplayInfo[];
+}
+export declare class NativeLifecycle implements Lifecycle {
+    private readonly bridge;
+    constructor(bridge: DriftHostBridge);
+    /** What the shell says, rather than what a desktop assumes: an iOS host answers false. */
+    get canQuit(): boolean;
+    onFocusChange(handler: (focused: boolean) => void): () => void;
+    onQuitRequest(handler: () => void): () => void;
+    requestQuit(): void;
+}
+export declare class NativeFileDialogs implements FileDialogs {
+    private readonly bridge;
+    constructor(bridge: DriftHostBridge);
+    openFile(accept: readonly string[]): Promise<OpenedFile | null>;
+    saveFile(name: string, bytes: Uint8Array): Promise<boolean>;
+}
+/**
+ * A store's achievements and presence, over the bridge.
+ *
+ * **Only created where a store answered.** `createHost` returns `null` for `services` otherwise,
+ * which is the same shape the engine's own interface has: there is no browser implementation of
+ * `PlatformServices` because there is nothing honest for one to do, and a game that gets null
+ * simply never calls it.
+ *
+ * Neither method reports failure, deliberately. An achievement that does not unlock is not a
+ * reason for a frame to stop, and a store that is offline is an ordinary state.
+ */
+export declare class NativePlatformServices implements PlatformServices {
+    private readonly bridge;
+    constructor(bridge: DriftHostBridge);
+    unlockAchievement(id: string): void;
+    setRichPresence(text: string): void;
+}

package/dist/renderer/nativeHost.js

@@ -0,0 +1,125 @@
+import { BRIDGE_KEY } from '../preload/bridge.js';
+/**
+ * The engine's capability interfaces, implemented over the shell's one bridge.
+ *
+ * Each of these is the native half of a pair whose browser half ships in the engine. The pairs
+ * differ in exactly the places a browser cannot answer honestly: a refresh rate is a number here
+ * and null there, and quitting works here and warns there.
+ *
+ * **A game is one bundle.** `hostBridge()` answers null in a plain browser rather than throwing,
+ * so a consumer picks its implementations at boot and ships the same code to both.
+ */
+export function hostBridge() {
+    const found = globalThis[BRIDGE_KEY];
+    return found === undefined || found === null ? null : found;
+}
+/**
+ * The video half of a settings screen, on a platform that can actually answer it.
+ *
+ * Every member here is the same call the browser implementation makes and refuses. That is the
+ * point of the pair: a game writes one settings screen against `DisplayControl`, and it is fully
+ * populated in a shell and honestly degraded in a tab — a resolution list that reports `false`
+ * from `setSize` is a control the game greys out rather than one that silently does nothing.
+ */
+export class NativeDisplay {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    /**
+     * A real number, which is the whole reason the browser implementation returns null.
+     *
+     * Read on each access rather than captured in the constructor: a window moved to another
+     * monitor changes it, and a value from boot would be the previous monitor's.
+     */
+    get refreshHz() {
+        return this.bridge.refreshHz();
+    }
+    isFullscreen() {
+        return this.bridge.isFullscreen();
+    }
+    async setFullscreen(on) {
+        await this.bridge.setFullscreen(on);
+    }
+    mode() {
+        return this.bridge.mode();
+    }
+    async setMode(mode) {
+        return this.bridge.setMode(mode);
+    }
+    size() {
+        return this.bridge.size();
+    }
+    /**
+     * The question, asked without performing the resize.
+     *
+     * The shell decides it with the same function that decides whether `setSize` refuses, so the two
+     * cannot disagree — see `main/ipc.ts`. Before this existed the only way to learn the answer was
+     * to call `setSize`, and a consumer's settings screen probed it at boot by resizing the window to
+     * the size it already had.
+     */
+    canSetSize() {
+        return this.bridge.canSetSize();
+    }
+    async setSize(width, height) {
+        return this.bridge.setSize(width, height);
+    }
+    displays() {
+        return this.bridge.displays();
+    }
+}
+export class NativeLifecycle {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    /** What the shell says, rather than what a desktop assumes: an iOS host answers false. */
+    get canQuit() {
+        return this.bridge.canQuit;
+    }
+    onFocusChange(handler) {
+        return this.bridge.onFocusChange(handler);
+    }
+    onQuitRequest(handler) {
+        return this.bridge.onQuitRequest(handler);
+    }
+    requestQuit() {
+        this.bridge.requestQuit();
+    }
+}
+export class NativeFileDialogs {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    async openFile(accept) {
+        const picked = await this.bridge.openFile(accept);
+        return picked === null ? null : { name: picked.name, bytes: picked.bytes };
+    }
+    async saveFile(name, bytes) {
+        return this.bridge.saveFile(name, bytes);
+    }
+}
+/**
+ * A store's achievements and presence, over the bridge.
+ *
+ * **Only created where a store answered.** `createHost` returns `null` for `services` otherwise,
+ * which is the same shape the engine's own interface has: there is no browser implementation of
+ * `PlatformServices` because there is nothing honest for one to do, and a game that gets null
+ * simply never calls it.
+ *
+ * Neither method reports failure, deliberately. An achievement that does not unlock is not a
+ * reason for a frame to stop, and a store that is offline is an ordinary state.
+ */
+export class NativePlatformServices {
+    bridge;
+    constructor(bridge) {
+        this.bridge = bridge;
+    }
+    unlockAchievement(id) {
+        this.bridge.platform.unlockAchievement(id);
+    }
+    setRichPresence(text) {
+        this.bridge.platform.setRichPresence(text);
+    }
+}

package/dist/resources.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Where the packager's own resources are: `assets/`, `android/` and `ios/`.
+ *
+ * **This module exists because four call sites climbed out of `src/` on their own, and a consumer
+ * could not tell them where to look instead.** `stage.ts` and `ios.ts` copied `../assets`,
+ * `android.ts` copied `../android`, `ios.ts` copied `../ios`, and `build.ts` reached into
+ * `../assets/icon.png` for a default icon — each computed from its own module's URL, with no
+ * option, flag or variable that moved any of them. The first of those runs on **every** desktop
+ * build: the whole assets directory becomes the artifact's `drift://shell/` origin.
+ *
+ * That is fine inside this repository and a wall outside it. **A consumer that vendors engine
+ * source** copies `packages/<name>/src/**` to `<name>/**`
+ * — which flattens away exactly the level those four paths climbed to. Reported from outside,
+ * where the workaround was a layout exception in the vendor script: this one package kept the
+ * engine's own shape while the other ten were copied flat, plus a directory-copying branch so
+ * every asset still landed in the integrity hash, plus a per-package entry in the bundler's alias
+ * table. Small, and permanently in the way of reading that file.
+ *
+ * **What it cost before it was understood** is the part worth keeping: copied flat, `cp` threw
+ * `ENOENT` on a directory nobody would think to look for, before a single artifact existed, naming
+ * a path that is not in the project. `resourceDir` refuses instead, naming both the path it looked
+ * in and the way to move it.
+ *
+ * **Two doors and deliberately not three.** A caller passes `resourceRoot`; the CLI takes
+ * `--resources=<dir>` and fills it. There is no environment variable: a build's inputs should be
+ * visible in the command that ran it, and an environment variable is the one input that is invisible
+ * in a log somebody is reading a week later. **What would change that** is a consumer whose build
+ * system cannot pass an argument, which no consumer here has.
+ */
+/** The three directories this package ships beside its sources. */
+export type ResourceName = 'assets' | 'android' | 'ios';
+/**
+ * The root the three live under: the given one, or this package's own directory.
+ *
+ * Resolved against the working directory when it is relative, because a flag typed on a command
+ * line is relative to where somebody typed it.
+ */
+export declare function resourceRoot(given?: string | undefined): string;
+/**
+ * One resource directory, checked before anything is copied out of it.
+ *
+ * **The check is the point.** Every caller's next move is a recursive `cp`, whose failure names a
+ * path a consumer has never seen and says nothing about what would fix it. This says both, once,
+ * before the build has done any work — which is what `AGENTS.md` means by failing fast at init with
+ * an actionable message.
+ */
+export declare function resourceDir(name: ResourceName, given?: string | undefined): Promise<string>;
+/** One file inside a resource directory, checked the same way. */
+export declare function resourceFile(name: ResourceName, file: string, given?: string | undefined): Promise<string>;
+/** What every entry point takes so a caller can move the three. */
+export interface ResourceOptions {
+    /**
+     * Where `assets/`, `android/` and `ios/` are, if not beside this package's sources.
+     *
+     * A vendored engine is the case this is for: a copy that flattened every package's `src` has left
+     * the three somewhere this package cannot compute.
+     */
+    readonly resourceRoot?: string;
+    /**
+     * Where builds write, if not `out/` inside the project.
+     *
+     * **A staging copy that cannot leave the project is a copy that can refuse itself.** `fs.cp`
+     * compares `dev` and `ino` up the destination's ancestors, and a shared or network folder can
+     * answer the same identity for a file and a directory — at which point the very first copy of a
+     * build fails, naming the one thing that is not happening. See `outDir.ts` for the measurement.
+     *
+     * The same two doors and no third: a caller passes `outRoot`, the CLI takes `--out=<dir>` and
+     * fills it. No environment variable, for the reason this module's header already gives.
+     */
+    readonly outRoot?: string;
+}

package/dist/resources.js

@@ -0,0 +1,83 @@
+import { access } from 'node:fs/promises';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * A file only the real thing has, one per directory, so a directory is identified and not merely
+ * named.
+ *
+ * **Reported from outside 2026-08-28, the day the root became configurable.** A vendored consumer
+ * flattens each package's `src`, so the *default* root — one level above this package's sources —
+ * is the vendor root, the directory holding every copied package. One of those packages is
+ * `@driftengine/assets`. So `join(root, 'assets')` exists, an existence check passes, and the
+ * packager stages a directory of TypeScript source as the shell: verified from this repository,
+ * `shell/` came out holding 25 files — `assetPath.ts`, `gltf.ts`, `fbx.ts` — and no `splash.html`,
+ * with no error at any stage. The artifact builds, installs and launches, and the badge is a 404
+ * nobody sees, because the splash is what would have shown it.
+ *
+ * **That failure mode is one the old arrangement did not have**, which is the part worth keeping:
+ * copied flat with no root given, `cp` threw `ENOENT` and stopped. Making the path configurable
+ * made its absence quiet in exactly one layout — the common one.
+ *
+ * **Each marker is a file the packager itself reads**, so it cannot be deleted without breaking
+ * something louder than this check: `main/splash.ts` loads `drift://shell/splash.html`, `ios.ts`
+ * reads and rewrites `project.yml`, and Gradle will not open a project without its settings file. A
+ * marker nothing used would be a sentinel that could rot while the check went on passing.
+ */
+const MARKER = {
+    assets: 'splash.html',
+    android: 'settings.gradle.kts',
+    ios: 'project.yml',
+};
+/**
+ * The root the three live under: the given one, or this package's own directory.
+ *
+ * Resolved against the working directory when it is relative, because a flag typed on a command
+ * line is relative to where somebody typed it.
+ */
+export function resourceRoot(given) {
+    if (given !== undefined && given.length > 0)
+        return resolve(process.cwd(), given);
+    return join(dirname(fileURLToPath(import.meta.url)), '..');
+}
+/**
+ * One resource directory, checked before anything is copied out of it.
+ *
+ * **The check is the point.** Every caller's next move is a recursive `cp`, whose failure names a
+ * path a consumer has never seen and says nothing about what would fix it. This says both, once,
+ * before the build has done any work — which is what `AGENTS.md` means by failing fast at init with
+ * an actionable message.
+ */
+export async function resourceDir(name, given) {
+    const root = resourceRoot(given);
+    const dir = join(root, name);
+    const marker = MARKER[name];
+    const move = '— pass `--resources=<dir>` (or `resourceRoot` to the API) naming the directory that holds ' +
+        'assets/, android/ and ios/.';
+    try {
+        await access(dir);
+    }
+    catch {
+        throw new Error(`[drift-package] the packager's own \`${name}\` directory is not at ${dir}. It ships beside ` +
+            `this package's sources, so a copy of the engine that flattened them has moved it ${move}`);
+    }
+    try {
+        await access(join(dir, marker));
+        return dir;
+    }
+    catch {
+        /*
+         * **The confusing one, so the message explains the coincidence rather than the rule.** A
+         * consumer meeting this has a directory of the right name in the right place, and it is
+         * somebody else's — `@driftengine/assets` sitting in a vendor root beside the packager.
+         */
+        throw new Error(`[drift-package] ${dir} exists and is not the packager's \`${name}\` directory: it has no ` +
+            `\`${marker}\`. A vendored engine puts every package in one directory, and one of them is ` +
+            `\`@driftengine/assets\` — so a root that looks right can hold a package's source instead ` +
+            `of the shell's. Staging that produces an artifact that launches with no splash and no ` +
+            `error ${move}`);
+    }
+}
+/** One file inside a resource directory, checked the same way. */
+export async function resourceFile(name, file, given) {
+    return join(await resourceDir(name, given), file);
+}