@driftengine/package 3.61.0

package/dist/flags.js

@@ -0,0 +1,122 @@
+/**
+ * The Electron the Linux WebGPU switch below is written against, and measured on.
+ *
+ * **Not the version the feature was introduced in, which nobody here has established.** It is the
+ * version this repository has run the switch against and watched WebGPU come up: Electron 43.4.1,
+ * Chromium 150.0.7871.224, an RX 9070 XT, where `requestAdapter` answers null without the switch
+ * and hands back an `amd`/`rdna-4` adapter with it. Reported from outside against Electron 33.4.11,
+ * Chromium 130: the feature name is not in that binary at all, and the switch is inert there.
+ *
+ * So a runtime older than this is *unverified*, not known-broken — and the plan declines to ship an
+ * unverified switch rather than shipping one that may do nothing silently.
+ */
+export const WEBGPU_INTEROP_ELECTRON = 43;
+/**
+ * @param electronMajor The major version of the Electron these switches will be applied to, or
+ *   `null` where a caller genuinely cannot know. Both callers in this package can: the build reads
+ *   it out of the installed package, and the main process reads it out of `process.versions`.
+ */
+export function planFlags(manifest, target, electronMajor = null) {
+    /*
+     * **A mobile host has no command line to pass switches on.** The renderer is the platform's own
+     * WebView, updated by the store rather than by us, and every decision below is about a Chromium
+     * this package ships. Returning nothing is the honest answer rather than switches that would be
+     * silently dropped — and it is why the Linux refusal further down cannot fire on a phone.
+     */
+    if (target === 'android' || target === 'ios')
+        return { switches: [], refusal: null, notes: [] };
+    const switches = [];
+    const notes = [];
+    const wantsWebGpu = manifest.backend.webgpu !== 'off';
+    const linux = target === 'linux-x64';
+    /*
+     * **A software rasteriser is never chosen silently.** Plain headless Chromium selects
+     * SwiftShader on a development machine, measured, and says nothing about it — every
+     * frame it produces is a lie about what a player sees and it saturates the CPU producing it.
+     * `requireHardwareGpu()` refuses it in the capture harness; this refuses it in the product.
+     */
+    if (!manifest.backend.allowSoftwareRenderer) {
+        switches.push(['disable-software-rasterizer', '']);
+    }
+    if (linux && wantsWebGpu) {
+        /*
+         * **Electron does not enable WebGPU on Linux although Chrome does** (`electron#40929`), so
+         * without this there is no WebGPU on that target at all — `requestAdapter` simply answers null
+         * and the engine falls back, correctly and invisibly.
+         *
+         * **The interop feature, and deliberately not `--use-angle=vulkan --enable-features=Vulkan`.**
+         * Both yield WebGPU. The second also breaks video encoding under Wayland: measured on an
+         * RX 9070 XT, canvas frames encode as all-zero YUV — a green clip — with nothing reporting it,
+         * since `VideoEncoder.error` never fires and the muxer finalises a file of the expected size.
+         * `ForceEnableWebGpuInterop` composites WebGPU through GL instead of moving ANGLE onto Vulkan,
+         * and both survive: measured in a packaged build on this machine, WebGPU drew and a vp8 round
+         * trip came back magenta rather than green.
+         *
+         * **This is why clip export and WebGPU are no longer refused together.** They were, for as
+         * long as the only switch known to work was the one that broke encoding.
+         *
+         * **What would make it wrong** is a Chromium that retires the feature, at which point WebGPU
+         * quietly stops being offered on Linux and the acceptance probe reports the fallback — which
+         * is the failure mode to watch for rather than a green clip.
+         *
+         * **Reported from outside as hanging a Wayland session, and it does not do that here.** The
+         * report is a packaged game that never paints on AMD under Wayland: an adapter is offered and
+         * the renderer's creation never returns. Chromium does print
+         * `'--ozone-platform=wayland' is not compatible with Vulkan` on stderr while this switch is
+         * applied, on this machine too. But run against the engine's own starter — an RX 9070 XT on a
+         * Wayland session under COSMIC, Electron 43.4.1, Chromium 150 — the acquisition completes in
+         * **153 ms, three runs of three**, and the example draws with WebGPU. The bare path completes
+         * as well: adapter, device, canvas context, swapchain, submit, and a one-pixel readback that
+         * comes back magenta.
+         *
+         * **Chromium's own advice is worse here.** Pairing this with `--ozone-platform=x11`, which is
+         * what that message suggests, takes the GPU process down on this machine: `exit_code=139`, and
+         * a screenshot request answers `UnknownVizError`. So it is not offered.
+         *
+         * The switch is therefore kept, because withdrawing it on every Wayland session would take a
+         * measured-working backend away from every machine like this one. What the report is right
+         * about is that a stall had no floor under it, and that is closed where it belongs: see
+         * `BACKEND_TIMEOUT_MS` in the engine's backend selection, which answers WebGL2 rather than
+         * waiting for a device that is not coming.
+         */
+        /*
+         * **And it is only asked for on a runtime it has been seen to work on.** The switch was
+         * verified once and then travelled, unchecked, into whatever Electron a consumer's install
+         * happened to resolve — which is how a build reached a Chromium whose binary does not contain
+         * the feature name at all. Nothing reported it, because nothing could: an ignored feature name
+         * and an absent adapter produce the same product.
+         */
+        /*
+         * **And there is no second-best route on an older runtime, deliberately.**
+         *
+         * There is one that works: measured on Electron 33.4.11 against this machine, WebGPU comes up
+         * under `--enable-unsafe-webgpu` *and* `--enable-features=Vulkan` together — neither alone
+         * produces an adapter, nor does `--use-angle=vulkan` beside them. It is not offered, for two
+         * reasons that hold together. This package declares the Electron it is written against, so a
+         * build resolving an older one has an install to fix rather than a workaround to adopt; and the
+         * route costs video encoding under Wayland, where canvas frames encode as all-zero YUV — a
+         * green clip, with `VideoEncoder.error` never firing and the muxer finalising a file of the
+         * expected size. Shipping an unsafe flag and that trade, to a configuration this package says
+         * it does not support, is a worse answer than saying so.
+         */
+        if (electronMajor === null || electronMajor >= WEBGPU_INTEROP_ELECTRON) {
+            switches.push(['enable-features', 'ForceEnableWebGpuInterop']);
+        }
+        else if (manifest.backend.webgpu === 'require') {
+            return {
+                switches,
+                notes,
+                refusal: `backend.webgpu is "require" and Electron ${electronMajor} cannot deliver it on Linux. ` +
+                    `This package declares Electron ${WEBGPU_INTEROP_ELECTRON}; an install resolving an older ` +
+                    'one is the thing to fix. Otherwise set backend.webgpu to "prefer" or "off" to ship ' +
+                    'WebGL2 on this target deliberately.',
+            };
+        }
+        else {
+            notes.push(`no WebGPU on Linux: Electron ${electronMajor} predates the interop switch this package is ` +
+                `written against (${WEBGPU_INTEROP_ELECTRON}), so this build falls back to WebGL2 there. ` +
+                'Install the Electron this package declares to get it back.');
+        }
+    }
+    return { switches, refusal: null, notes };
+}

package/dist/identity.d.ts

@@ -0,0 +1,51 @@
+/** The two fields Node compares to decide whether two paths are the same thing. */
+export interface Identity {
+    readonly dev: bigint;
+    readonly ino: bigint;
+}
+/**
+ * Node's own `areIdentical`, which is what decides whether a copy is refused.
+ *
+ * The two zeros are excluded there and here: a filesystem that hands out no index answers 0, and
+ * Node declines to believe it.
+ *
+ * **`bigint` and not `number`.** A Windows file index is 64 bits and loses precision as a double
+ * exactly in the high half where those values live, so two different indices can arrive equal and
+ * two equal ones different — the check would be wrong in both directions on precisely the platform
+ * it exists for.
+ */
+export declare function sameIdentity(a: Identity, b: Identity): boolean;
+/**
+ * Refuse a filesystem that cannot tell a file from a directory, before a build spends its minutes.
+ *
+ * **The failure this replaces is a sentence about the one thing that is not happening.** `stage.ts`
+ * copies `drift.package.json` into the staging directory, and Node's `fs.cp` refuses to copy a
+ * thing into itself — deciding that by walking the destination's ancestors and comparing each
+ * one's `dev` and `ino` against the source's. On a filesystem that reports those honestly it never
+ * fires. On a network share it can, and what comes out is
+ *
+ *     cannot copy …\drift.package.json to a subdirectory of self …\out\win-x64\stage\…
+ *
+ * ten minutes into a build, about the thing furthest from the cause you could imagine. Reported
+ * from a Windows VM building over a mapped drive, where a file and a directory both answered
+ * `dev=66313 ino=-112686486700016`: a redirector that gets no file index from the server invents a
+ * constant one, and on Windows `dev` is already the volume serial number.
+ *
+ * **The witnesses are not the directories Node will really compare, and that is fine.**
+ * `checkParentPaths` walks up from `out/<target>/stage` and stops at the source's parent, so it
+ * compares `stage`, `<target>` and `out` — which on a first build do not exist yet and cannot be
+ * stat'ed here. What is being established is not *which* directory collides but that this volume
+ * gives a file and a directory the same identity, which is a property of the volume. The project
+ * root and `out/` are witnesses as good as any.
+ *
+ * **The remedy it names is `--out=<dir>`, and that is what changed.** Until that flag existed the
+ * only answer was to clone onto a local disk, which for a project with tens of gigabytes of assets
+ * is a real cost. Now the output can simply be sent somewhere that tells the truth, and the copy is
+ * the second suggestion rather than the first.
+ *
+ * **`look` is a seam and exists for one reason**: the condition cannot be reproduced on any
+ * filesystem this suite can create, so without it the refusal — the whole point of the function —
+ * would ship having never been seen to fire. The default is `statSync` and no caller passes
+ * anything else.
+ */
+export declare function refuseLyingFilesystem(cwd: string, outRoot: string | undefined, look?: (path: string) => Identity): void;

package/dist/identity.js

@@ -0,0 +1,75 @@
+import { existsSync, statSync } from 'node:fs';
+import { join, resolve } from 'node:path';
+/**
+ * Node's own `areIdentical`, which is what decides whether a copy is refused.
+ *
+ * The two zeros are excluded there and here: a filesystem that hands out no index answers 0, and
+ * Node declines to believe it.
+ *
+ * **`bigint` and not `number`.** A Windows file index is 64 bits and loses precision as a double
+ * exactly in the high half where those values live, so two different indices can arrive equal and
+ * two equal ones different — the check would be wrong in both directions on precisely the platform
+ * it exists for.
+ */
+export function sameIdentity(a, b) {
+    return a.ino !== 0n && a.dev !== 0n && a.ino === b.ino && a.dev === b.dev;
+}
+/**
+ * Refuse a filesystem that cannot tell a file from a directory, before a build spends its minutes.
+ *
+ * **The failure this replaces is a sentence about the one thing that is not happening.** `stage.ts`
+ * copies `drift.package.json` into the staging directory, and Node's `fs.cp` refuses to copy a
+ * thing into itself — deciding that by walking the destination's ancestors and comparing each
+ * one's `dev` and `ino` against the source's. On a filesystem that reports those honestly it never
+ * fires. On a network share it can, and what comes out is
+ *
+ *     cannot copy …\drift.package.json to a subdirectory of self …\out\win-x64\stage\…
+ *
+ * ten minutes into a build, about the thing furthest from the cause you could imagine. Reported
+ * from a Windows VM building over a mapped drive, where a file and a directory both answered
+ * `dev=66313 ino=-112686486700016`: a redirector that gets no file index from the server invents a
+ * constant one, and on Windows `dev` is already the volume serial number.
+ *
+ * **The witnesses are not the directories Node will really compare, and that is fine.**
+ * `checkParentPaths` walks up from `out/<target>/stage` and stops at the source's parent, so it
+ * compares `stage`, `<target>` and `out` — which on a first build do not exist yet and cannot be
+ * stat'ed here. What is being established is not *which* directory collides but that this volume
+ * gives a file and a directory the same identity, which is a property of the volume. The project
+ * root and `out/` are witnesses as good as any.
+ *
+ * **The remedy it names is `--out=<dir>`, and that is what changed.** Until that flag existed the
+ * only answer was to clone onto a local disk, which for a project with tens of gigabytes of assets
+ * is a real cost. Now the output can simply be sent somewhere that tells the truth, and the copy is
+ * the second suggestion rather than the first.
+ *
+ * **`look` is a seam and exists for one reason**: the condition cannot be reproduced on any
+ * filesystem this suite can create, so without it the refusal — the whole point of the function —
+ * would ship having never been seen to fire. The default is `statSync` and no caller passes
+ * anything else.
+ */
+export function refuseLyingFilesystem(cwd, outRoot, look = (path) => statSync(path, { bigint: true })) {
+    /* Already pointed off this volume: whatever it answers about itself no longer decides a copy. */
+    if (outRoot !== undefined && !resolve(process.cwd(), outRoot).startsWith(resolve(cwd)))
+        return;
+    const manifest = join(cwd, 'drift.package.json');
+    if (!existsSync(manifest))
+        return;
+    const its = look(manifest);
+    for (const witness of [cwd, join(cwd, 'out')]) {
+        if (!existsSync(witness))
+            continue;
+        const theirs = look(witness);
+        if (!sameIdentity(its, theirs))
+            continue;
+        throw new Error(`${cwd} is on a filesystem that gives a file and a directory the same identity.\n\n` +
+            `  ${manifest}\n      dev=${its.dev} ino=${its.ino}\n` +
+            `  ${witness}\n      dev=${theirs.dev} ino=${theirs.ino}\n\n` +
+            'Node uses those two fields to avoid copying something into itself, so the first copy of ' +
+            'the staging step fails with "cannot copy … to a subdirectory of self …" — a message ' +
+            'about the thing furthest from the cause, ten minutes into a build. It is what a network ' +
+            'share does: the redirector invents a constant file index when the server gives it none.\n\n' +
+            'Send the output somewhere that tells the truth:\n\n' +
+            '    drift-package build --out=/a/local/disk\n\n' +
+            'Or build from a local copy of the project, if the assets are small enough to move.');
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * What a game imports from the packager.
+ *
+ * **The renderer half only.** The main process, the CLI, the builder and the staging step are
+ * Node and are reached through the `drift-package` command rather than through this barrel — a
+ * game bundling `electron` or `esbuild` into its own payload is the failure this boundary exists
+ * to prevent.
+ *
+ * `createHost` is the one call most consumers need; the classes beside it are for a game that
+ * assembles its capabilities itself.
+ */
+export { createHost } from './renderer/host.ts';
+export type { Host } from './renderer/host.ts';
+export { FileStore } from './renderer/fileStore.ts';
+export { NativeDisplay, NativeFileDialogs, NativeLifecycle, hostBridge, } from './renderer/nativeHost.ts';
+export { NativePlatformServices } from './renderer/nativeHost.ts';
+export { BRIDGE_KEY } from './preload/bridge.ts';
+export type { DriftHostBridge } from './preload/bridge.ts';

package/dist/index.js

@@ -0,0 +1,24 @@
+/*! DriftEngine | Copyright 2026 Drift Technologies | Apache-2.0 | https://github.com/drftrun/driftengine */
+/**
+ * What a game imports from the packager.
+ *
+ * **The renderer half only.** The main process, the CLI, the builder and the staging step are
+ * Node and are reached through the `drift-package` command rather than through this barrel — a
+ * game bundling `electron` or `esbuild` into its own payload is the failure this boundary exists
+ * to prevent.
+ *
+ * `createHost` is the one call most consumers need; the classes beside it are for a game that
+ * assembles its capabilities itself.
+ */
+export { createHost } from './renderer/host.js';
+export { FileStore } from './renderer/fileStore.js';
+export { NativeDisplay, NativeFileDialogs, NativeLifecycle, hostBridge, } from './renderer/nativeHost.js';
+/*
+ * A store's own features, when a store answered.
+ *
+ * `createHost().services` is how a game reaches these — null in a browser, null where the manifest
+ * named no app, and null when the copy was launched outside the store. The SDK itself is not here:
+ * it is a native Node module held by the main process, because the renderer has no Node at all.
+ */
+export { NativePlatformServices } from './renderer/nativeHost.js';
+export { BRIDGE_KEY } from './preload/bridge.js';

package/dist/init.d.ts

@@ -0,0 +1,24 @@
+import type { PackageManifest } from './manifest.ts';
+/** A file `init` writes, and where it goes relative to the project. */
+export interface InitFile {
+    readonly path: string;
+    readonly content: string;
+}
+/**
+ * The files a consumer cannot avoid owning, and deliberately only those.
+ *
+ * **The rule that decides what is here**: if it can be done once inside `drift-package`, it is not
+ * allowed to be in a file somebody copies. A Windows build needs a `.ps1` because something has to
+ * start Node on that machine and that something cannot live inside a Node program; a project needs
+ * a launcher because the engine may be vendored, where `npx drift-package` resolves nothing.
+ * Everything else the first three-platform consumer wrote — 421 lines of it — is now `runtime.ts`,
+ * `identity.ts`, `outDir.ts` and the deletion at the top of `cli.ts`.
+ */
+export declare function initFiles(manifest: PackageManifest): readonly InitFile[];
+/**
+ * Write them into a project, refusing to overwrite without `--force`.
+ *
+ * **The refusal names the file rather than the directory**, because a consumer who has edited one
+ * of these has edited a specific one and wants to know which is in the way.
+ */
+export declare function init(cwd: string, manifest: PackageManifest, force: boolean): Promise<void>;

package/dist/init.js

@@ -0,0 +1,45 @@
+import { existsSync } from 'node:fs';
+import { mkdir, writeFile } from 'node:fs/promises';
+import { dirname, join } from 'node:path';
+import { buildWindowsScript } from './templates/buildWindows.js';
+import { packageWrapperScript } from './templates/packageWrapper.js';
+/**
+ * The files a consumer cannot avoid owning, and deliberately only those.
+ *
+ * **The rule that decides what is here**: if it can be done once inside `drift-package`, it is not
+ * allowed to be in a file somebody copies. A Windows build needs a `.ps1` because something has to
+ * start Node on that machine and that something cannot live inside a Node program; a project needs
+ * a launcher because the engine may be vendored, where `npx drift-package` resolves nothing.
+ * Everything else the first three-platform consumer wrote — 421 lines of it — is now `runtime.ts`,
+ * `identity.ts`, `outDir.ts` and the deletion at the top of `cli.ts`.
+ */
+export function initFiles(manifest) {
+    return [
+        { path: 'scripts/build-windows.ps1', content: buildWindowsScript(manifest) },
+        { path: 'scripts/package.mjs', content: packageWrapperScript(manifest) },
+    ];
+}
+/**
+ * Write them into a project, refusing to overwrite without `--force`.
+ *
+ * **The refusal names the file rather than the directory**, because a consumer who has edited one
+ * of these has edited a specific one and wants to know which is in the way.
+ */
+export async function init(cwd, manifest, force) {
+    const files = initFiles(manifest);
+    if (!force) {
+        const existing = files.map((f) => join(cwd, f.path)).filter((p) => existsSync(p));
+        if (existing.length > 0) {
+            throw new Error(`init would overwrite:\n${existing.map((p) => `  ${p}`).join('\n')}\n\n` +
+                'These are yours once you have edited them. Pass --force to replace them anyway, or ' +
+                'move them aside first and diff.');
+        }
+    }
+    for (const file of files) {
+        const full = join(cwd, file.path);
+        await mkdir(dirname(full), { recursive: true });
+        await writeFile(full, file.content, 'utf8');
+        console.log(`ok: ${full}`);
+    }
+    console.log(`\n  node scripts/package.mjs doctor\n  node scripts/package.mjs build --target=${manifest.targets[0] ?? 'linux-x64'}\n`);
+}

package/dist/ios.d.ts

@@ -0,0 +1,27 @@
+import type { PackageManifest } from './manifest.ts';
+import type { ResourceOptions } from './resources.ts';
+/**
+ * An iOS application, from the same web build every other target uses.
+ *
+ * **Unsigned unless a team is named, and that is the useful default.** Apple's free tier signs a
+ * build for your own device for seven days at a time and does it through Xcode's own UI rather
+ * than through anything a script can drive. So this produces an archive and an unsigned `.ipa` —
+ * the shape a sideloading tool re-signs — and takes the signed path only when `APPLE_TEAM_ID` is
+ * in the environment, where automatic signing has something to work with.
+ *
+ * **Written, and not yet run.** No Mac has built this: the Swift, the spec and this file were
+ * written against Apple's documented behaviour, and the first person to run it should expect to
+ * fix something. What is *not* guessed is the shape of the bridge — that is shared with Android
+ * and tested — and the containment rule in the scheme handler, which mirrors the desktop shell's.
+ *
+ * **One question is still open and it gates the whole tier**: whether WebKit treats a custom
+ * scheme as a *secure context*. If it does not, `crossOriginIsolated` is false and the answer is a
+ * loopback server instead — `SchemeHandler.swift` is the only file that changes.
+ * `drift://localhost/__drift/originProbe.html` answers it in one look on a device. **That URL is
+ * the answer as much as the page is**: the host has to be `localhost`, because that is the whole
+ * of why the origin is trustworthy, and the shell's own assets are served under `__drift/`
+ * rather than from a second host, because a second host would not be `localhost`. Every earlier
+ * spelling of this in the documentation named the desktop shell's `drift://shell/` form, which
+ * on this platform resolves against the game's bundle root and answers with nothing.
+ */
+export declare function buildIos(manifest: PackageManifest, projectDir: string, outDir: string, options?: ResourceOptions): Promise<void>;

package/dist/ios.js

@@ -0,0 +1,152 @@
+import { spawn } from 'node:child_process';
+import { cp, mkdir, readFile, rm, writeFile } from 'node:fs/promises';
+import { build as esbuild } from 'esbuild';
+import { basename, dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { missingReferences } from './mobile/assetCheck.js';
+import { versionCodeFor } from './mobile/versionCode.js';
+import { resourceDir } from './resources.js';
+import { findXcodeGen } from './toolchain.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+/**
+ * An iOS application, from the same web build every other target uses.
+ *
+ * **Unsigned unless a team is named, and that is the useful default.** Apple's free tier signs a
+ * build for your own device for seven days at a time and does it through Xcode's own UI rather
+ * than through anything a script can drive. So this produces an archive and an unsigned `.ipa` —
+ * the shape a sideloading tool re-signs — and takes the signed path only when `APPLE_TEAM_ID` is
+ * in the environment, where automatic signing has something to work with.
+ *
+ * **Written, and not yet run.** No Mac has built this: the Swift, the spec and this file were
+ * written against Apple's documented behaviour, and the first person to run it should expect to
+ * fix something. What is *not* guessed is the shape of the bridge — that is shared with Android
+ * and tested — and the containment rule in the scheme handler, which mirrors the desktop shell's.
+ *
+ * **One question is still open and it gates the whole tier**: whether WebKit treats a custom
+ * scheme as a *secure context*. If it does not, `crossOriginIsolated` is false and the answer is a
+ * loopback server instead — `SchemeHandler.swift` is the only file that changes.
+ * `drift://localhost/__drift/originProbe.html` answers it in one look on a device. **That URL is
+ * the answer as much as the page is**: the host has to be `localhost`, because that is the whole
+ * of why the origin is trustworthy, and the shell's own assets are served under `__drift/`
+ * rather than from a second host, because a second host would not be `localhost`. Every earlier
+ * spelling of this in the documentation named the desktop shell's `drift://shell/` form, which
+ * on this platform resolves against the game's bundle root and answers with nothing.
+ */
+export async function buildIos(manifest, projectDir, outDir, options = {}) {
+    if (process.platform !== 'darwin') {
+        throw new Error('ios is built on macOS: Xcode is not available anywhere else');
+    }
+    const xcodegen = await findXcodeGen();
+    if (xcodegen === null) {
+        throw new Error('XcodeGen is not here. Run `drift-package bootstrap --target=ios`, which fetches it; ' +
+            'Xcode itself comes from the App Store.');
+    }
+    const projectRoot = join(outDir, 'project');
+    await rm(projectRoot, { recursive: true, force: true });
+    await mkdir(projectRoot, { recursive: true });
+    await cp(await resourceDir('ios', options.resourceRoot), projectRoot, { recursive: true });
+    /* The game keeps its own directory here, unlike Android: `SchemeHandler` resolves against a
+       `www` root inside the bundle, so absolute references land where they point. */
+    const distDir = resolve(projectDir, dirname(manifest.entry));
+    await cp(distDir, join(projectRoot, 'www'), { recursive: true });
+    await checkReferences(join(projectRoot, 'www'), basename(manifest.entry));
+    /* Served under `drift://localhost/__drift/`, so the origin probe and the mark are reachable
+       without a second host — which would not be `localhost`, and so would not be secure. */
+    await cp(await resourceDir('assets', options.resourceRoot), join(projectRoot, 'shell'), {
+        recursive: true,
+    });
+    await esbuild({
+        stdin: {
+            contents: `import { attachIosShim } from ${JSON.stringify(join(HERE, 'mobile', 'iosShim.ts'))};\nattachIosShim('__driftHost');\n`,
+            resolveDir: HERE,
+            loader: 'ts',
+        },
+        outfile: join(projectRoot, 'drift-shim.js'),
+        bundle: true,
+        format: 'iife',
+        platform: 'browser',
+        target: 'es2022',
+        logLevel: 'warning',
+    });
+    const version = await consumerVersion(projectDir);
+    const team = process.env.APPLE_TEAM_ID ?? '';
+    const spec = (await readFile(join(projectRoot, 'project.yml'), 'utf8'))
+        .replace(/__DRIFT_APP_NAME__/g, manifest.name)
+        .replace(/__DRIFT_APP_ID__/g, manifest.id)
+        .replace(/__DRIFT_VERSION_NAME__/g, version)
+        .replace(/__DRIFT_VERSION_CODE__/g, String(versionCodeFor(version)))
+        .replace(/__DRIFT_TEAM_ID__/g, team);
+    await writeFile(join(projectRoot, 'project.yml'), spec, 'utf8');
+    console.log(`[drift-package] ios: ${team === '' ? 'unsigned — a sideloading tool re-signs it' : `signing with team ${team}`}`);
+    await runTool(xcodegen, ['generate', '--spec', 'project.yml'], projectRoot);
+    const archive = join(outDir, 'DriftHost.xcarchive');
+    await runTool('xcodebuild', [
+        '-project',
+        'DriftHost.xcodeproj',
+        '-scheme',
+        'DriftHost',
+        '-configuration',
+        'Release',
+        '-destination',
+        'generic/platform=iOS',
+        '-archivePath',
+        archive,
+        'archive',
+        ...(team === ''
+            ? ['CODE_SIGNING_ALLOWED=NO', 'CODE_SIGNING_REQUIRED=NO', 'CODE_SIGN_IDENTITY=']
+            : [`DEVELOPMENT_TEAM=${team}`]),
+    ], projectRoot);
+    /*
+     * An `.ipa` is a zip with the app inside a `Payload` directory, which is all `xcodebuild
+     * -exportArchive` produces for a development build — and that step needs a provisioning profile
+     * this may not have. Built by hand so an unsigned archive still leaves something installable by
+     * a tool that signs it afterwards.
+     */
+    const payload = join(outDir, 'Payload');
+    await rm(payload, { recursive: true, force: true });
+    await mkdir(payload, { recursive: true });
+    await cp(join(archive, 'Products', 'Applications', `${manifest.name}.app`), join(payload, `${manifest.name}.app`), { recursive: true });
+    const ipa = join(outDir, `${manifest.name.replace(/[^\w.-]+/g, '-')}-${version}.ipa`);
+    await rm(ipa, { force: true });
+    await runTool('zip', ['-qry', ipa, 'Payload'], outDir);
+    await rm(payload, { recursive: true, force: true });
+    console.log(`[drift-package] ios: ${ipa}`);
+}
+async function checkReferences(root, entryName) {
+    const html = await readFile(join(root, entryName), 'utf8');
+    const { readdir } = await import('node:fs/promises');
+    const { relative } = await import('node:path');
+    const walk = async (dir) => {
+        const out = [];
+        for (const entry of await readdir(dir, { withFileTypes: true })) {
+            const full = join(dir, entry.name);
+            if (entry.isDirectory())
+                out.push(...(await walk(full)));
+            else
+                out.push(relative(root, full).split('\\').join('/'));
+        }
+        return out;
+    };
+    const missing = missingReferences(html, new Set(await walk(root)));
+    if (missing.length === 0)
+        return;
+    throw new Error(`the entry page references ${missing.length} file(s) that are not in the bundle: ` +
+        `${missing.slice(0, 5).join(', ')}.`);
+}
+async function consumerVersion(projectDir) {
+    try {
+        const raw = JSON.parse(await readFile(join(projectDir, 'package.json'), 'utf8'));
+        const version = raw.version;
+        return typeof version === 'string' && version.length > 0 ? version : '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+async function runTool(command, args, cwd) {
+    await new Promise((done, fail) => {
+        const child = spawn(command, [...args], { stdio: 'inherit', cwd });
+        child.on('error', fail);
+        child.on('close', (code) => code === 0 ? done() : fail(new Error(`${command} exited with ${String(code)}`)));
+    });
+}

package/dist/macCrossSign.d.ts

@@ -0,0 +1,34 @@
+export interface CrossSignOptions {
+    /** The `.app` directory, which is what rcodesign is pointed at. */
+    readonly app: string;
+    /** The rcodesign binary, from the cache or from the machine. */
+    readonly rcodesign: string;
+    /** The slice the artifact is supposed to carry, so a silently wrong one is caught here. */
+    readonly arch: 'arm64' | 'x64';
+}
+/**
+ * Ad-hoc sign a `.app` in place, then refuse it if the result is not what was asked for.
+ *
+ * Ad-hoc is the only mode offered: a Developer ID would need a certificate this host cannot use,
+ * and `planSigning` refuses that combination before a build gets this far.
+ */
+export declare function crossSignMacApp(options: CrossSignOptions): Promise<void>;
+/**
+ * The `.zip` a cross-built Mac artifact ships as, archived here rather than by electron-builder.
+ *
+ * **electron-builder cannot produce this one correctly off a Mac, and says so in its own source**:
+ * its archiver picks 7-Zip everywhere except macOS, guarded by a comment reading *"7zip
+ * dereferences symlinks, corrupting .framework structure and breaking codesign"*. The guard is
+ * written as `process.platform === "darwin"`, so on Linux it takes the 7-Zip path regardless.
+ *
+ * **A `.framework` is symlinks by construction.** `Electron Framework` points into
+ * `Versions/Current`, which points at `Versions/A`. Dereferenced, the archive carries the
+ * framework's 192 MB payload twice and no links at all, and macOS rejects that layout as
+ * unrecognised — the signature that was correct on disk no longer validates against it. Measured
+ * on this repository before this function existed: a 404 MB archive with zero symlink entries,
+ * against 353 MB on disk.
+ *
+ * `zip -y` stores a symlink as a symlink, `-r` recurses, and Unix permission bits are kept, which
+ * every executable inside the bundle depends on.
+ */
+export declare function zipMacApp(app: string, into: string): Promise<void>;