@driftengine/package 3.61.0

package/src/mobile/bridgeShim.ts

@@ -0,0 +1,292 @@
+import type { DisplayInfo, WindowMode } from '@driftengine/core';
+
+import type { DriftHostBridge } from '../preload/bridge.ts';
+import { showDeviceReport } from './report.ts';
+
+/**
+ * One bridge shape, assembled from what a mobile WebView is able to hand over.
+ *
+ * **Android's `@JavascriptInterface` can pass strings, numbers and booleans and nothing else.** It
+ * cannot return a promise, an object, an array or a callback. So the native surface is flat,
+ * synchronous and string-only — `snapshot()` returns JSON, `displays()` returns JSON — and this
+ * file turns it into the same `DriftHostBridge` the desktop shell exposes. The engine then sees
+ * **one** seam with three shells behind it rather than three seams, which is the whole design.
+ *
+ * **Naming them differently is deliberate.** The native object is `__driftHostNative`; the one a
+ * game reaches is `__driftHost`. A single half-typed object would hide the adaptation; two names
+ * make it a file somebody can read.
+ *
+ * **Events come the other way through a global**, because a WebView cannot call into the page: the
+ * host evaluates `globalThis.__driftHostEvents.focus(false)` when the activity pauses. Installed
+ * here rather than in the host, so the subscription bookkeeping is written once in TypeScript.
+ */
+export interface NativeShimSurface {
+  snapshot(): string;
+  write(key: string, value: string): void;
+  remove(key: string): void;
+  isFullscreen(): boolean;
+  setFullscreen(on: boolean): void;
+  refreshHz(): number;
+  mode(): string;
+  setMode(mode: string): boolean;
+  size(): string;
+  setSize(width: number, height: number): boolean;
+  canSetSize(): boolean;
+  displays(): string;
+  /**
+   * Whether this platform lets an application end itself.
+   *
+   * Android does — `finish()` closes the activity. iOS does not, and Apple's guidance is explicit
+   * that an application should not: a game there answers false and draws no exit button.
+   */
+  canQuit(): boolean;
+  /**
+   * Writing a file, in three calls, because a bridge that can only carry strings cannot carry a
+   * twenty megabyte clip in one.
+   *
+   * `saveBegin` returns false where the platform refused to start — no space, no permission — and
+   * `saveEnd` returns where the file landed, in words a person can be told.
+   */
+  saveBegin(name: string, mime: string): boolean;
+  saveChunk(base64: string): boolean;
+  saveEnd(): string;
+  saveAbort(): void;
+  requestQuit(): void;
+}
+
+/** What the host pushes in. Installed on `globalThis` so a WebView can evaluate against it. */
+interface HostEvents {
+  focus(on: boolean): void;
+  quitRequest(): void;
+  /**
+   * The back gesture. **True means the game dealt with it and the host must do nothing.**
+   *
+   * Answered in the order a game would want it answered: a registered quit handler first, because
+   * a game that asked to be told about leaving has a confirmation to show; then an Escape key,
+   * because a game with no quit handler almost certainly has a pause menu bound to one, and
+   * `preventDefault` is the page saying that keystroke was its own. False means neither, and the
+   * host is then free to close — after asking twice, which is its own business.
+   */
+  back(): boolean;
+  /**
+   * A download the host intercepted, completed here.
+   *
+   * The host cannot read a `blob:` URL — it belongs to the page — so it hands it back and the page
+   * fetches its own blob, then sends the bytes over the same chunked road as `saveFile`.
+   */
+  saveBlob(url: string, name: string): Promise<boolean>;
+}
+
+/**
+ * Half a megabyte of bytes a call, which is about seven hundred kilobytes of base64.
+ *
+ * Large enough that a twenty megabyte clip is forty calls rather than four thousand, and small
+ * enough that neither the string nor the argument list is anywhere near a limit.
+ */
+export const SAVE_CHUNK_BYTES = 512 * 1024;
+
+/**
+ * Bytes as base64, built in pieces.
+ *
+ * `String.fromCharCode(...bytes)` on a whole file overflows the argument list and throws — at a
+ * size that depends on the engine, so it works in a test and fails on a real clip.
+ */
+export function base64Of(bytes: Uint8Array): string {
+  let binary = '';
+  const step = 8192;
+  for (let at = 0; at < bytes.length; at += step) {
+    binary += String.fromCharCode(...bytes.subarray(at, at + step));
+  }
+  return btoa(binary);
+}
+
+/**
+ * What the platform files a name under.
+ *
+ * Android sorts a download by its declared type, so a clip saved as `application/octet-stream`
+ * lands somewhere a gallery will not look for it. Wrong is worse than unknown here, so anything
+ * unrecognised stays octet-stream rather than being guessed at.
+ */
+export function mimeForName(name: string): string {
+  const dot = name.lastIndexOf('.');
+  switch (dot === -1 ? '' : name.slice(dot + 1).toLowerCase()) {
+    case 'webm':
+      return 'video/webm';
+    case 'mp4':
+      return 'video/mp4';
+    case 'png':
+      return 'image/png';
+    case 'jpg':
+    case 'jpeg':
+      return 'image/jpeg';
+    case 'gif':
+      return 'image/gif';
+    case 'json':
+      return 'application/json';
+    case 'txt':
+      return 'text/plain';
+    default:
+      return 'application/octet-stream';
+  }
+}
+
+function parseJson<T>(raw: string, fallback: T): T {
+  try {
+    const parsed: unknown = JSON.parse(raw);
+    return (parsed ?? fallback) as T;
+  } catch {
+    /* A malformed payload is a host bug, and a game that cannot start because its preferences
+       did not parse is a worse one. Empty is the same degradation `BrowserStore` makes. */
+    return fallback;
+  }
+}
+
+/**
+ * Synthesise the key a pause menu is bound to, and report whether the page took it.
+ *
+ * **A keydown and a keyup**, because a game that tracks held keys and only ever receives the down
+ * ends up with Escape held forever — which is a menu that will not close, from a fix meant to stop
+ * one closing too easily.
+ *
+ * Dispatched at the focused element so it bubbles the way a real keystroke does; a game listening
+ * on `window`, on `document` or on its canvas all receive it.
+ */
+function pressEscape(): boolean {
+  const target =
+    (globalThis as { document?: { activeElement?: unknown; body?: unknown } }).document ?? null;
+  if (target === null) return false;
+  const node = (target.activeElement ?? target.body) as
+    { dispatchEvent(event: unknown): boolean } | undefined;
+  if (node === undefined || node === null || typeof node.dispatchEvent !== 'function') return false;
+
+  const make = (type: string): unknown =>
+    new KeyboardEvent(type, {
+      key: 'Escape',
+      code: 'Escape',
+      bubbles: true,
+      cancelable: true,
+    });
+  const consumed = !node.dispatchEvent(make('keydown'));
+  node.dispatchEvent(make('keyup'));
+  return consumed;
+}
+
+export function installShim(native: NativeShimSurface): DriftHostBridge {
+  const focusHandlers = new Set<(focused: boolean) => void>();
+  const quitHandlers = new Set<() => void>();
+
+  const events: HostEvents = {
+    focus: (on) => {
+      for (const handler of focusHandlers) handler(on);
+    },
+    quitRequest: () => {
+      for (const handler of quitHandlers) handler();
+    },
+    saveBlob: async (url, name) => {
+      let bytes: Uint8Array;
+      try {
+        bytes = new Uint8Array(await (await fetch(url)).arrayBuffer());
+      } catch {
+        /* A revoked or cross-origin URL. Nothing is opened, so no empty file is left behind. */
+        return false;
+      }
+      return saveFile(name, bytes);
+    },
+    back: () => {
+      if (quitHandlers.size > 0) {
+        for (const handler of quitHandlers) handler();
+        return true;
+      }
+      return pressEscape();
+    },
+  };
+  (globalThis as { __driftHostEvents?: HostEvents }).__driftHostEvents = events;
+
+  const saveFile = async (name: string, bytes: Uint8Array): Promise<boolean> => {
+    if (!native.saveBegin(name, mimeForName(name))) return false;
+    try {
+      for (let at = 0; at < bytes.length; at += SAVE_CHUNK_BYTES) {
+        if (!native.saveChunk(base64Of(bytes.subarray(at, at + SAVE_CHUNK_BYTES)))) {
+          native.saveAbort();
+          return false;
+        }
+      }
+      native.saveEnd();
+      return true;
+    } catch {
+      /* Half a clip on disk looks exactly like a whole one to a file manager, and the person who
+         finds it there has no way to know. Abandoned rather than finished. */
+      native.saveAbort();
+      return false;
+    }
+  };
+
+  const noPicker = (): never => {
+    /*
+     * A game does not open files; an editor does, and an editor is not a phone application. The
+     * refusal is loud rather than a null, for the same reason `BrowserFileDialogs` throws where a
+     * browser has no picker: a cancel and an absent capability are different answers.
+     */
+    throw new Error('[driftengine] no file picker on this platform; a desktop shell has one');
+  };
+
+  return {
+    storeSnapshot: parseJson<Record<string, string>>(native.snapshot(), {}),
+    writeKey: (key, value) => native.write(key, value),
+    removeKey: (key) => native.remove(key),
+    isFullscreen: () => native.isFullscreen(),
+    setFullscreen: async (on) => {
+      native.setFullscreen(on);
+    },
+    refreshHz: () => {
+      const hz = native.refreshHz();
+      /* Zero is what a platform reports when it will not say, and a plausible 60 is exactly what
+         the engine's rule forbids inventing. */
+      return typeof hz === 'number' && hz > 0 ? hz : null;
+    },
+    mode: () => (native.mode() === 'windowed' ? 'windowed' : 'fullscreen') as WindowMode,
+    setMode: async (mode) => native.setMode(mode),
+    size: () =>
+      parseJson<{ width: number; height: number }>(native.size(), { width: 0, height: 0 }),
+    setSize: async (width, height) => native.setSize(width, height),
+    /* Asked of the host rather than answered here, so the refusal and the question stay one
+       decision: `HostBridge.java` answers both beside each other. */
+    canSetSize: () => native.canSetSize(),
+    displays: () => parseJson<DisplayInfo[]>(native.displays(), []),
+    onFocusChange: (handler) => {
+      focusHandlers.add(handler);
+      return () => focusHandlers.delete(handler);
+    },
+    onQuitRequest: (handler) => {
+      quitHandlers.add(handler);
+      return () => quitHandlers.delete(handler);
+    },
+    canQuit: native.canQuit(),
+    requestQuit: () => native.requestQuit(),
+    /* No store on a phone: neither platform's own is integrated, and a game reads `available`
+       and never calls the rest. */
+    platform: {
+      available: false,
+      unlockAchievement: () => undefined,
+      setRichPresence: () => undefined,
+    },
+    openFile: async () => noPicker(),
+    saveFile,
+  };
+}
+
+/**
+ * Wire the native surface into the global the engine's `hostBridge()` looks for.
+ *
+ * Called by the injected shim script, which the host evaluates before the game's own scripts run —
+ * `WebViewCompat.addDocumentStartJavaScript` on Android, a user script on iOS. That timing is what
+ * makes this the mobile equivalent of the desktop preload rather than something a game has to
+ * remember to import.
+ */
+export function attachShim(key: string): void {
+  const native = (globalThis as Record<string, unknown>).__driftHostNative as
+    NativeShimSurface | undefined;
+  if (native === undefined) return;
+  (globalThis as Record<string, unknown>)[key] = installShim(native);
+  showDeviceReport();
+}

package/src/mobile/iosShim.ts

@@ -0,0 +1,148 @@
+import type { DisplayInfo, WindowMode } from '@driftengine/core';
+
+import type { DriftHostBridge } from '../preload/bridge.ts';
+import { SAVE_CHUNK_BYTES, base64Of, mimeForName } from './bridgeShim.ts';
+import { showDeviceReport } from './report.ts';
+
+/**
+ * The same bridge again, from a platform with no synchronous return.
+ *
+ * **This is why iOS needs its own adapter rather than Android's.** `@JavascriptInterface` on
+ * Android returns a value; `WKScriptMessageHandler` does not — it is one-way and asynchronous, and
+ * there is no synchronous path from native code into JavaScript on this platform at all. The
+ * engine's `KeyValueStore` is synchronous by contract, because preferences are read during boot
+ * and an await there is a frame drawn with the wrong settings and corrected afterwards, which is a
+ * visible flicker on every load.
+ *
+ * So the split is: **everything that must be read is injected**, as a literal object written into
+ * the page before its first line of script runs, and **everything that changes something is a
+ * message**. The host keeps that object current — a rotation replaces its `size` — which is why
+ * this reads through it on every call rather than copying the values once.
+ *
+ * The mutations that report a result ride on `WKScriptMessageHandlerWithReply`, which does hand a
+ * promise back, and which is why the deployment target is iOS 15 rather than something older.
+ */
+export interface IosState {
+  snapshot: Record<string, string>;
+  refreshHz: number | null;
+  mode: WindowMode;
+  size: { width: number; height: number };
+  displays: DisplayInfo[];
+  fullscreen: boolean;
+  canQuit: boolean;
+}
+
+/** One message to the host. Resolves with whatever it replied, or rejects if it did not. */
+export type IosCall = (name: string, payload: unknown) => Promise<unknown>;
+
+export function installIosShim(state: IosState, call: IosCall): DriftHostBridge {
+  const focusHandlers = new Set<(focused: boolean) => void>();
+  const quitHandlers = new Set<() => void>();
+
+  const send = (name: string, payload: unknown): void => {
+    void call(name, payload).catch(() => undefined);
+  };
+
+  const ask = async (name: string, payload: unknown): Promise<boolean> => {
+    try {
+      return (await call(name, payload)) === true;
+    } catch {
+      /* The host went away, or the handler is not registered. A game must not see an exception
+         from a settings screen. */
+      return false;
+    }
+  };
+
+  (globalThis as { __driftHostEvents?: unknown }).__driftHostEvents = {
+    focus: (on: boolean) => {
+      for (const handler of focusHandlers) handler(on);
+    },
+    quitRequest: () => {
+      for (const handler of quitHandlers) handler();
+    },
+  };
+
+  const noPicker = (): never => {
+    throw new Error('[driftengine] no file picker on this platform; a desktop shell has one');
+  };
+
+  return {
+    storeSnapshot: state.snapshot,
+    writeKey: (key, value) => send('write', { key, value }),
+    removeKey: (key) => send('remove', { key }),
+    isFullscreen: () => state.fullscreen,
+    setFullscreen: async (on) => {
+      /* The status bar is the only thing there is to hide, and hiding it is not refused — so this
+         is a message rather than a question. */
+      send('fullscreen', { on });
+    },
+    refreshHz: () => state.refreshHz,
+    mode: () => state.mode,
+    setMode: async (mode) => ask('mode', { mode }),
+    size: () => state.size,
+    /* Constant rather than a round trip: there is no window on this platform to give a size to. */
+    setSize: async () => false,
+    /* The question, beside the refusal it must agree with. Both are constants here for the same
+       reason, and the day iOS gains a resizable window they move together. */
+    canSetSize: () => false,
+    displays: () => state.displays,
+    onFocusChange: (handler) => {
+      focusHandlers.add(handler);
+      return () => focusHandlers.delete(handler);
+    },
+    onQuitRequest: (handler) => {
+      quitHandlers.add(handler);
+      return () => quitHandlers.delete(handler);
+    },
+    /** False, always: an iOS application does not exit itself, and Apple asks that it not try. */
+    canQuit: false,
+    requestQuit: () => {
+      console.warn('[driftengine] requestQuit: an iOS application does not exit itself');
+    },
+    /* No store on a phone: neither platform's own is integrated, and a game reads `available`
+       and never calls the rest. */
+    platform: {
+      available: false,
+      unlockAchievement: () => undefined,
+      setRichPresence: () => undefined,
+    },
+    openFile: async () => noPicker(),
+    /**
+     * Saving goes to the share sheet, which is where a file goes on this platform.
+     *
+     * The bytes travel base64 in one message rather than in chunks: a reply-capable handler takes
+     * a string of whatever size, and iOS has no equivalent of Android's per-call binder limit. The
+     * chunk size is still respected for the encode itself, because building one enormous string
+     * from a twenty megabyte clip is what overflows an argument list.
+     */
+    saveFile: async (name, bytes) => {
+      const pieces: string[] = [];
+      for (let at = 0; at < bytes.length; at += SAVE_CHUNK_BYTES) {
+        pieces.push(base64Of(bytes.subarray(at, at + SAVE_CHUNK_BYTES)));
+      }
+      return ask('save', { name, mime: mimeForName(name), data: pieces });
+    },
+  };
+}
+
+/**
+ * Install the bridge from what the host injected.
+ *
+ * Called by the bundled shim script, which the host evaluates at document start — the same timing
+ * as the desktop preload and Android's document-start script.
+ */
+export function attachIosShim(key: string): void {
+  const holder = globalThis as {
+    __driftHostState?: IosState;
+    webkit?: {
+      messageHandlers?: Record<string, { postMessage(value: unknown): Promise<unknown> }>;
+    };
+  };
+  const state = holder.__driftHostState;
+  const handler = holder.webkit?.messageHandlers?.driftHost;
+  if (state === undefined || handler === undefined) return;
+  (globalThis as Record<string, unknown>)[key] = installIosShim(state, async (name, payload) =>
+    handler.postMessage({ name, payload }),
+  );
+  showDeviceReport();
+}

package/src/mobile/report.ts

@@ -0,0 +1,121 @@
+/**
+ * What a device says about itself, collected rather than assumed.
+ *
+ * **A pinned desktop Chromium cannot see the failures this tier exists to catch.** WebKit enforces
+ * a sixteen-byte stride for arrays in the uniform address space where Dawn does not, so the shaders
+ * that draw everything compiled on every desktop browser and on no iPhone — and nothing in the
+ * pipeline could have known. A mobile build that ships without collecting what devices report
+ * throws away the only reason mobile is in this delivery at all.
+ *
+ * **Every value is what the device said**, and a value that could not be read is the empty string.
+ * An invented renderer string is what the capability clamp then matches against, which is how a
+ * phone ends up in the wrong tier — the same rule `AGENTS.md` sets for a backend that cannot answer.
+ *
+ * Reached in a packaged build with `?report=1` on the entry URL. Not a hidden gesture: a tester who
+ * has to be told a secret is a tester who reports the wrong thing.
+ */
+export function deviceReport(): Record<string, string> {
+  const agent = typeof navigator === 'undefined' ? '' : navigator.userAgent;
+  return {
+    userAgent: agent,
+    platform: platformOf(agent),
+    engine: engineOf(agent),
+    webgpu:
+      (globalThis as { navigator?: { gpu?: unknown } }).navigator?.gpu === undefined
+        ? 'absent'
+        : 'present',
+    webglRenderer: unmaskedRenderer(),
+    secureContext: String(Boolean((globalThis as { isSecureContext?: boolean }).isSecureContext)),
+    host: (globalThis as Record<string, unknown>).__driftHost === undefined ? 'absent' : 'present',
+    pixelRatio: String((globalThis as { devicePixelRatio?: number }).devicePixelRatio ?? ''),
+  };
+}
+
+/**
+ * The part number the driver reports, which is the only string worth having.
+ *
+ * `WEBGL_debug_renderer_info` is the extension that gives it. Where a browser withholds it — some
+ * do, for fingerprinting — the answer is empty rather than the vendor-neutral placeholder, because
+ * an empty string is visibly nothing and `WebKit WebGL` is visibly a device.
+ */
+function unmaskedRenderer(): string {
+  try {
+    const canvas = document.createElement('canvas');
+    const gl = canvas.getContext('webgl2') ?? canvas.getContext('webgl');
+    if (gl === null) return '';
+    const info = (gl as WebGLRenderingContext).getExtension('WEBGL_debug_renderer_info') as {
+      UNMASKED_RENDERER_WEBGL: number;
+    } | null;
+    if (info === null) return '';
+    const value: unknown = (gl as WebGLRenderingContext).getParameter(info.UNMASKED_RENDERER_WEBGL);
+    return typeof value === 'string' ? value : '';
+  } catch {
+    return '';
+  }
+}
+
+/** `iOS 18.2` or `Android 14`, from the agent string, or empty where it says neither. */
+function platformOf(agent: string): string {
+  const ios = agent.match(/(?:iPhone|iPad|CPU) OS (\d+)[._](\d+)/);
+  if (ios !== null) return `iOS ${ios[1]}.${ios[2]}`;
+  const android = agent.match(/Android (\d+(?:\.\d+)?)/);
+  if (android !== null) return `Android ${android[1]}`;
+  return '';
+}
+
+/**
+ * Which browser engine build this is.
+ *
+ * The number that matters when a shader fails to compile: an Android WebView is updated through
+ * the store independently of the OS, so two phones on the same Android version can disagree.
+ */
+function engineOf(agent: string): string {
+  const chrome = agent.match(/Chrome\/([\d.]+)/);
+  if (chrome !== null) return `Chrome ${chrome[1]}`;
+  const safari = agent.match(/Version\/([\d.]+).*Safari/);
+  if (safari !== null) return `Safari ${safari[1]}`;
+  return '';
+}
+
+/** The query that turns the table on. Documented rather than secret, for the reason above. */
+const REPORT_QUERY = 'report=1';
+
+/**
+ * Draw the report over whatever is on screen, if this build was asked for it.
+ *
+ * **Over the game rather than instead of it**, so a tester can see that the game is running behind
+ * the numbers they are reading — a report on a blank page cannot distinguish a device that failed
+ * to draw from one that was never asked to.
+ *
+ * Does nothing at all unless the entry URL carries `?report=1`, which is the whole of the switch.
+ */
+export function showDeviceReport(): void {
+  try {
+    if (!globalThis.location?.search?.includes(REPORT_QUERY)) return;
+  } catch {
+    return;
+  }
+
+  const draw = (): void => {
+    try {
+      const panel = document.createElement('pre');
+      panel.style.cssText =
+        'position:fixed;inset:auto 8px 8px 8px;z-index:2147483647;margin:0;padding:10px;' +
+        'background:rgba(11,11,13,.92);color:#ececf0;font:12px/1.5 ui-monospace,monospace;' +
+        'border:1px solid #26262d;border-radius:6px;white-space:pre-wrap;max-height:60vh;' +
+        'overflow:auto;pointer-events:none';
+      panel.textContent = Object.entries(deviceReport())
+        .map(([key, value]) => `${key.padEnd(14)} ${value === '' ? '—' : value}`)
+        .join('\n');
+      document.body?.appendChild(panel);
+    } catch {
+      /* No DOM yet, or a page that replaced its own body. A diagnostic is never worth a throw. */
+    }
+  };
+
+  if (document.readyState === 'loading') {
+    document.addEventListener('DOMContentLoaded', draw, { once: true });
+  } else {
+    draw();
+  }
+}

package/src/mobile/versionCode.ts

@@ -0,0 +1,17 @@
+/**
+ * The integer Android orders upgrades by, derived from the version name.
+ *
+ * **Two digits per part**, so `1.4.2` is `10402`. That holds until a part reaches a hundred, which
+ * is stated here rather than discovered on the release that stops installing — at which point the
+ * scheme has to widen and every prior code has to stay below the new ones.
+ *
+ * **Never zero.** A project with no `package.json` has no version, `0.0.0` computes to nothing, and
+ * Gradle refuses the build with a message about a positive integer rather than about the missing
+ * file. One is the floor, and it is a real version code rather than an error.
+ */
+export function versionCodeFor(version: string): number {
+  const [major = 0, minor = 0, patch = 0] = version
+    .split('.')
+    .map((part) => Number.parseInt(part, 10) || 0);
+  return Math.max(1, major * 10000 + minor * 100 + patch);
+}

package/src/outDir.ts

@@ -0,0 +1,37 @@
+import { join, resolve } from 'node:path';
+
+import type { Target } from './manifest.ts';
+import type { ResourceOptions } from './resources.ts';
+
+/**
+ * Where a build writes, which used to be `join(cwd, 'out', target)` in four places and nowhere
+ * else.
+ *
+ * **This is a flag and not tidiness, and the reason is a copy that refuses itself.** Node's
+ * `fs.cp` will not copy a thing into itself and decides that by walking the destination's
+ * ancestors comparing each one's `dev` and `ino` against the source's. On a filesystem that
+ * reports those honestly it never fires. On a shared or network folder it can: measured by a
+ * consumer on a Windows VM with the project on a drive mapped to a folder on a Linux machine,
+ * `drift.package.json` and `out/` both answered `dev=66313 ino=-112686486700016` — the same
+ * identity for a file and for a directory — and the first staging copy failed with
+ *
+ *     cannot copy …\drift.package.json to a subdirectory of self …\out\win-x64\stage\…
+ *
+ * which is a sentence about the one thing that is not happening. A junction at `out/` closes it,
+ * because the walk calls `stat` and not `lstat`, and that is a filesystem trick standing in for
+ * this flag.
+ *
+ * **The layout under the root is unchanged**, so `--out=C:\drift-out` gives
+ * `C:\drift-out\win-x64\stage` and nothing that reads `out/<target>/…` has to learn a second
+ * shape.
+ *
+ * **A relative root resolves against the invoking directory and deliberately not against
+ * `--project=`.** Those two differ exactly when the flag matters — a packager run from somewhere
+ * other than the project it is packaging — and resolving against the project would put the output
+ * back inside the thing the flag exists to escape.
+ */
+export function outFor(cwd: string, target: Target, options: ResourceOptions): string {
+  const root =
+    options.outRoot === undefined ? join(cwd, 'out') : resolve(process.cwd(), options.outRoot);
+  return join(root, target);
+}