@gjsify/cli 0.64.5 → 0.64.6

package/lib/utils/bin-shim.d.ts

@@ -173,12 +173,23 @@ export declare function buildNativeEnvPreamble(scanRoot: string, bakedDirs?: rea
  * cannot go stale the way baking `systemGiLibraryDirs()` in would (a launcher is
  * routinely written before `brew install gtk4`), and it re-derives nothing —
  * four literals from `dyld(1)`, shared with {@link dyldDefaultFallbackDirs}.
- * An inherited value stays AHEAD of it; the export only ADDS BACK what dyld
- * would have searched on its own.
+ * An inherited value stays AHEAD of it.
  *
- * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
- * either, so an ARM Mac has that gap with or without gjsify —
- * `status/open-todos/README.md`.
+ * NOT SUFFICIENT ON ITS OWN, so the `lib/` beside the `gjs` this shim execs is
+ * appended: "set to the documented default" is NOT "unset". Measured on macOS 27 / arm64 with Homebrew
+ * gjs 1.88.1 and a fresh glib keg: `gjs -c "imports.gi.Gio"` loads with the
+ * variable unset and dies with the documented default exported —
+ * `Failed to load shared library 'libgjs.0.dylib' referenced by the typelib`,
+ * then `Unsupported type void` from Gio's override `_init`. `GjsPrivate-1.0`
+ * names GJS's own library by bare leaf, and once the variable is SET dyld only
+ * finds it in a listed directory; `gjs`'s rpath names GLib's keg, not its own.
+ * That broke every `gjsify` command on an Apple-silicon Mac, `--version`
+ * included, until a symlink was planted in GLib's keg by hand (the CI step
+ * `Make libgjs resolvable without a DYLD_ variable`) — and a `brew upgrade glib`
+ * silently removes it again. `<dir of gjs>/../lib` is where every prefix
+ * (Homebrew on either arch, MacPorts) links `libgjs`, resolved at LAUNCH from
+ * the same `PATH` lookup the `exec` uses, so it cannot go stale either. It goes
+ * LAST: it only has to catch what the defaults miss.
  */
 export declare function dyldFallbackPreamble(platform: string): string;
 /** POSIX `sh` single-quoting for a launcher's target path. */

package/lib/utils/bin-shim.js

@@ -444,12 +444,23 @@ export function buildNativeEnvPreamble(scanRoot, bakedDirs = [], target = {}) {
  * cannot go stale the way baking `systemGiLibraryDirs()` in would (a launcher is
  * routinely written before `brew install gtk4`), and it re-derives nothing —
  * four literals from `dyld(1)`, shared with {@link dyldDefaultFallbackDirs}.
- * An inherited value stays AHEAD of it; the export only ADDS BACK what dyld
- * would have searched on its own.
+ * An inherited value stays AHEAD of it.
  *
- * NOT the host's GI libdirs: `/opt/homebrew/lib` was never in dyld's default
- * either, so an ARM Mac has that gap with or without gjsify —
- * `status/open-todos/README.md`.
+ * NOT SUFFICIENT ON ITS OWN, so the `lib/` beside the `gjs` this shim execs is
+ * appended: "set to the documented default" is NOT "unset". Measured on macOS 27 / arm64 with Homebrew
+ * gjs 1.88.1 and a fresh glib keg: `gjs -c "imports.gi.Gio"` loads with the
+ * variable unset and dies with the documented default exported —
+ * `Failed to load shared library 'libgjs.0.dylib' referenced by the typelib`,
+ * then `Unsupported type void` from Gio's override `_init`. `GjsPrivate-1.0`
+ * names GJS's own library by bare leaf, and once the variable is SET dyld only
+ * finds it in a listed directory; `gjs`'s rpath names GLib's keg, not its own.
+ * That broke every `gjsify` command on an Apple-silicon Mac, `--version`
+ * included, until a symlink was planted in GLib's keg by hand (the CI step
+ * `Make libgjs resolvable without a DYLD_ variable`) — and a `brew upgrade glib`
+ * silently removes it again. `<dir of gjs>/../lib` is where every prefix
+ * (Homebrew on either arch, MacPorts) links `libgjs`, resolved at LAUNCH from
+ * the same `PATH` lookup the `exec` uses, so it cannot go stale either. It goes
+ * LAST: it only has to catch what the defaults miss.
  */
 export function dyldFallbackPreamble(platform) {
     if (platform !== 'darwin')
@@ -457,7 +468,10 @@ export function dyldFallbackPreamble(platform) {
     // `HOME: '$HOME'` on purpose — the shim must expand it at LAUNCH, not bake
     // the writing machine's home directory into every launcher.
     const dirs = dyldDefaultFallbackDirs({ HOME: '$HOME' }).join(':');
-    return (`DYLD_FALLBACK_LIBRARY_PATH="\${DYLD_FALLBACK_LIBRARY_PATH:+$DYLD_FALLBACK_LIBRARY_PATH:}${dirs}"\n` +
+    return (`gjsify_gjs=$(command -v gjs 2>/dev/null)\n` +
+        `DYLD_FALLBACK_LIBRARY_PATH="\${DYLD_FALLBACK_LIBRARY_PATH:+$DYLD_FALLBACK_LIBRARY_PATH:}${dirs}` +
+        `\${gjsify_gjs:+:\${gjsify_gjs%/*}/../lib}"\n` +
+        `unset gjsify_gjs\n` +
         `export DYLD_FALLBACK_LIBRARY_PATH\n`);
 }
 /** POSIX `sh` single-quoting for a launcher's target path. */

package/lib/utils/install-backend-native.js

@@ -72,7 +72,7 @@ import { getCachedPackument, putCachedPackument } from './install-packument-cach
 import { assertNativeBackendNodeVersion } from './node-version.js';
 import { buildCmdShim, buildLauncherShims, buildNativeEnvPreamble, buildShLauncher, isGjsBundlePath, parseShebang, pickBinMap, } from './bin-shim.js';
 import { detectNativePackages } from './detect-native-packages.js';
-import { findExtraneous, formatExtraneousError } from './install-extraneous.js';
+import { droppedInstallPaths, findExtraneous, formatExtraneousError } from './install-extraneous.js';
 import { devLinkPath, devLinkRoot } from './dev-link.js';
 import { scanPrefix } from './prune-prefix.js';
 import { badPlatformError, checkPlatform, declaresPlatform, describePlatformTarget, readPlatformForce, resolveHostPlatform, } from './platform-check.js';
@@ -293,6 +293,12 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     await downloadAndExtractAll(installable, opts.prefix, npmrc, log, opts.signal, progress);
     await linkBins(installable, opts.prefix, log);
     warnMissingNativeBuilds(installable, opts.prefix, log);
+    // Only after a resolve that rewrote the lockfile: that is when a placement can
+    // be dropped, and the previous lockfile is the record of what this installer
+    // put there. After the extract, so a failed download leaves the tree as it was.
+    if (resolved && opts.lockfile && existingLock) {
+        removeDroppedPackages(opts.prefix, droppedInstallPaths(Object.keys(existingLock.packages), nodes), new Set([...(opts.workspaceNames ?? []), ...(opts.linkedNames ?? [])]), log);
+    }
     log('install: done');
     // Top-level requested packages only, so callers can write the resolved version
     // back into package.json (`npm install --save`). From `nodes`, NEVER from
@@ -300,6 +306,38 @@ async function installPackagesNativeLocked(opts, npmrc, log) {
     // downloaded", and a provided package is installed.
     return topLevelResolutions(opts.specs, nodes);
 }
+/**
+ * Remove what {@link droppedInstallPaths} planned, and say so in one line.
+ *
+ * A symlink is never removed (a workspace or `gjsify link` checkout, i.e. the user's
+ * sources), and neither is a name a workspace or a dev link provides, whatever its
+ * path: the same two guards `extractOne` applies before it overwrites anything.
+ */
+function removeDroppedPackages(prefix, installPaths, providedNames, log) {
+    const removed = [];
+    for (const installPath of installPaths) {
+        if (providedNames.has(nameFromInstallPath(installPath)))
+            continue;
+        const dir = path.join(prefix, installPath);
+        let stat;
+        try {
+            stat = fs.lstatSync(dir);
+        }
+        catch {
+            continue;
+        }
+        if (!stat.isDirectory())
+            continue;
+        fs.rmSync(dir, { recursive: true, force: true });
+        removed.push(installPath);
+    }
+    if (removed.length === 0)
+        return;
+    log('install: removed %d dropped placement(s): %s', removed.length, removed.join(', '));
+    const names = removed.map(nameFromInstallPath);
+    const shown = names.slice(0, 5).join(', ') + (names.length > 5 ? `, … ${names.length - 5} more` : '');
+    console.log(`gjsify: removed ${removed.length} package(s) the lockfile no longer names (${shown})`);
+}
 /**
  * `--immutable` only: refuse a `node_modules` holding packages the lockfile does not
  * describe, naming every one of them.

package/lib/utils/install-extraneous.d.ts

@@ -91,3 +91,28 @@ export declare const EXTRANEOUS_REPORT_LIMIT = 20;
  * hand them a command that changes nothing and a refusal that repeats verbatim.
  */
 export declare function formatExtraneousError(entries: readonly ExtraneousPackage[], prefix: string): string;
+/**
+ * Install paths the PREVIOUS lockfile placed and a fresh resolve no longer does —
+ * what a plain install DROPPED, and the only thing it removes.
+ *
+ * THE INCIDENT (2026-10-22). A project removed `@gjsify/gtk-runtime-darwin-*` from its
+ * `optionalDependencies`; `gjsify install` rewrote the lockfile without them and left
+ * the 0.64.2 copies in `node_modules`. On a Mac every darwin prebuild's rpath prefers
+ * that bundle's GLib over Homebrew's, so every build kept dying with `No signal
+ * 'context_response' on object 'GVolumeMonitor'` — after the fix, from a dependency
+ * the project no longer declared. npm removes such a package; this installer only
+ * ever added.
+ *
+ * WHY THE LOCKFILE DIFF, and not "everything {@link findExtraneous} reports". The tree
+ * legitimately holds packages no lockfile names: `ensureProjectGjsEngine` lays the GJS
+ * bundler engine down after the install and on purpose keeps it out of the lockfile.
+ * Sweeping the undescribed set would delete that engine on every install and fetch it
+ * again. A path some earlier lockfile of THIS project placed is this installer's own
+ * output, so removing it cannot take anything another writer put there.
+ *
+ * Nested placements under a dropped root collapse into the root, like
+ * {@link findExtraneous}, so the caller removes each directory once.
+ */
+export declare function droppedInstallPaths(previous: Iterable<string>, next: readonly {
+    installPath: string;
+}[]): string[];

package/lib/utils/install-extraneous.js

@@ -129,3 +129,44 @@ export function formatExtraneousError(entries, prefix) {
             'In CI this usually means a cache entry was restored from a DIFFERENT lockfile.',
     ].join('\n');
 }
+/**
+ * Install paths the PREVIOUS lockfile placed and a fresh resolve no longer does —
+ * what a plain install DROPPED, and the only thing it removes.
+ *
+ * THE INCIDENT (2026-10-22). A project removed `@gjsify/gtk-runtime-darwin-*` from its
+ * `optionalDependencies`; `gjsify install` rewrote the lockfile without them and left
+ * the 0.64.2 copies in `node_modules`. On a Mac every darwin prebuild's rpath prefers
+ * that bundle's GLib over Homebrew's, so every build kept dying with `No signal
+ * 'context_response' on object 'GVolumeMonitor'` — after the fix, from a dependency
+ * the project no longer declared. npm removes such a package; this installer only
+ * ever added.
+ *
+ * WHY THE LOCKFILE DIFF, and not "everything {@link findExtraneous} reports". The tree
+ * legitimately holds packages no lockfile names: `ensureProjectGjsEngine` lays the GJS
+ * bundler engine down after the install and on purpose keeps it out of the lockfile.
+ * Sweeping the undescribed set would delete that engine on every install and fetch it
+ * again. A path some earlier lockfile of THIS project placed is this installer's own
+ * output, so removing it cannot take anything another writer put there.
+ *
+ * Nested placements under a dropped root collapse into the root, like
+ * {@link findExtraneous}, so the caller removes each directory once.
+ */
+export function droppedInstallPaths(previous, next) {
+    const kept = new Set(next.map((n) => normalizePath(n.installPath)));
+    const dropped = [...new Set([...previous].map(normalizePath))]
+        .filter((p) => p.startsWith('node_modules/') && !kept.has(p))
+        .sort((a, b) => (a < b ? -1 : a > b ? 1 : 0));
+    const keptList = [...kept];
+    const roots = [];
+    for (const p of dropped) {
+        const parent = roots[roots.length - 1];
+        if (parent && p.startsWith(`${parent}/`))
+            continue;
+        // A directory still holding a kept placement is not removed whole; its own
+        // dropped descendants are still listed, one by one.
+        if (keptList.some((k) => k.startsWith(`${p}/`)))
+            continue;
+        roots.push(p);
+    }
+    return roots;
+}

package/lib/utils/ship/app-runtime.d.ts

@@ -1,4 +1,4 @@
-import type { Layout, LayoutIdentity } from './layout.js';
+import { type Layout, type LayoutIdentity } from './layout.js';
 import { type ResolveInstalledPackageOptions } from '../resolve-npm-package.js';
 import type { StagedFile } from './types.js';
 /**
@@ -161,8 +161,11 @@ export interface AppRuntimePaths {
     /** `<prebuildDir>/node_gi.node` — what `NODE_GI_NATIVE` pins. */
     addonPath: string;
     /**
-     * `<App>.app/Contents/MacOS/node`, or `<program dir>/node.exe` — beside the
-     * launcher that execs it, under the name the target's own release uses.
+     * `<App>.app/Contents/Helpers/<display name>`, or `<program dir>/node.exe`
+     * beside the launcher — darwin names it after the app (`layout.ts`'s
+     * `dirs.helpers`) so Activity Monitor and System Events show the app
+     * instead of `node`; Windows keeps the interpreter's own release name
+     * beside the `.cmd`, where nothing reads a process list by file name.
      */
     interpreterPath: string;
     /** Node's own LICENSE, under `Contents/Resources` (macOS) or `share/` (Windows). */

package/lib/utils/ship/app-runtime.js

@@ -80,6 +80,7 @@
 import { existsSync, readdirSync, statSync } from 'node:fs';
 import { dirname, join, posix, sep } from 'node:path';
 import { listFilesRecursive } from './discover.js';
+import { assertUsableAsHelperName } from './layout.js';
 import { nodeRuntimeBinaryName } from './node-runtime.js';
 import { isExecutableAsset } from './plan.js';
 import { resolveInstalledPackage } from '../resolve-npm-package.js';
@@ -264,20 +265,34 @@ export function appRuntimePaths(layout, identity, target) {
         prebuildDir,
         gtkDir: posix.join(prebuildDir, 'gtk'),
         addonPath: posix.join(prebuildDir, NODE_GI_ADDON_FILENAME),
-        // `Contents/MacOS`, because that is where a `.app` keeps executables and
-        // because `$here` — which the launcher already computes — is then the whole
-        // path expression. `dirs.native` would work for dyld and would make
-        // the launcher walk back up for the one file it execs. On Windows
-        // `dirs.launcher` is the program directory itself, so the interpreter lands
-        // beside the `.cmd` for the same reason.
+        // ON DARWIN, `Contents/Helpers/<display name>` — NEVER `Contents/MacOS`,
+        // because that directory already holds the launcher at `binaryName`, and
+        // APFS is case-insensitive by default: `stamped` and `Stamped` are the
+        // same file there, so no capitalisation of `binaryName` can share the
+        // directory with it. `Contents/Helpers` is one of Apple's own
+        // nested-code locations (`codesign(1)`'s bundle format, beside
+        // `Frameworks`, `PlugIns`, `XPCServices`), and naming the leaf after
+        // `identity.name` rather than `binaryName` is the whole point: Activity
+        // Monitor and System Events read a Mach-O process's name off its own
+        // FILE NAME, not off `exec -a` or any argv — measured by hand-editing a
+        // released `.app`, moving its interpreter to `Contents/Helpers/<App>`
+        // and rewriting the launcher's `exec` line, after which `ps -o comm` and
+        // System Events both read the app's name instead of `node`.
         //
-        // THE LEAF COMES FROM `node-runtime.ts`, which is the module that already
-        // decided it for the SOURCE file — `node.exe` on win32, `node` elsewhere,
-        // read off the TARGET and never `process.platform` (assembling a Windows
-        // program directory on Linux is the supported path). Restating the rule here
-        // would let the two drift into a stage that copies `node.exe` to `node` and a
-        // launcher that execs neither.
-        interpreterPath: posix.join(dirs.launcher, nodeRuntimeBinaryName(target)),
+        // Derived from the LAYOUT (`dirs.helpers !== ''`) rather than from
+        // `layout.name === 'darwin'`: only the darwin row sets `helpers` to a
+        // real directory (`layout.ts`), so this branch is "does this layout have
+        // a helpers seam", not a second darwin-specific fact typed out here.
+        //
+        // ON WINDOWS AND LINUX, unchanged: `dirs.launcher` and the leaf
+        // `node-runtime.ts` already decided for the SOURCE file — `node.exe` on
+        // win32, read off the TARGET and never `process.platform` (assembling a
+        // Windows program directory on Linux is the supported path). A Windows
+        // program directory has no launcher-collision to dodge in the first
+        // place, so its interpreter stays beside the `.cmd`.
+        interpreterPath: dirs.helpers === ''
+            ? posix.join(dirs.launcher, nodeRuntimeBinaryName(target))
+            : posix.join(dirs.helpers, assertUsableAsHelperName(identity.name)),
         // rpm's `share/licenses/<name>/LICENSE` shape, which the `macos-app` row
         // already uses for the app's own licence — one layout for a reader to learn,
         // and `node` is a name no `binaryName` can collide with silently: `placeStage`

package/lib/utils/ship/launcher.js

@@ -181,7 +181,16 @@ function renderPrefixLauncher(settings, bundleRelPath, layout) {
  * IT EXECS WHAT THE BUNDLE CARRIES. `runtime` comes from
  * `utils/ship/app-runtime.ts` and names the interpreter, the relocated GTK
  * closure and the node-gi addon staged inside `Contents/` — so the exec line is
- * `"$here/node"` and the two locators below point into `dirs.native`.
+ * `"$here/../Helpers/<display name>"` and the two locators below point into
+ * `dirs.native`. The interpreter is staged under `Contents/Helpers`, not
+ * `Contents/MacOS` beside this very script, and named after `identity.name`
+ * rather than kept as `node`: Activity Monitor and System Events read a
+ * process's name off the FILE NAME of the Mach-O that is running, not off argv
+ * or any `exec -a`, so a bundle whose carried interpreter is still called `node`
+ * shows up as `node` everywhere a user looks for it (`layout.ts`'s `dirs.helpers`,
+ * `app-runtime.ts`'s `appRuntimePaths`). `beside()` computes the relative hop
+ * from the actual two directories rather than assuming a sibling, so this
+ * function needs no special case for the rename.
  * When the stage carries none of them every line here is byte-identical to what
  * M2a wrote, which is what keeps a bundle assembled without the runtime packages
  * exactly as (un)usable as it was rather than differently broken.
@@ -308,10 +317,14 @@ function renderAppBundleLauncher(settings, bundleRelPath, layout, runtime) {
     if (settings.fontFiles.length > 0) {
         lines.push(`GJSIFY_FONT_DIR="$contents/${stagedFontDir(under(dirs.data), settings.appId)}"`, 'export GJSIFY_FONT_DIR');
     }
-    // `"$here/node"`, not `node`. The bare name is true of a developer's machine
-    // and false of a `.app` a stranger downloads, and the difference is not a
-    // degraded experience: macOS ships no Node at all, so the launcher's first act
-    // would be `exec: node: not found`.
+    // `"$here/../Helpers/<display name>"`, not a bare `node`. The bare name is
+    // true of a developer's machine and false of a `.app` a stranger downloads,
+    // and the difference is not a degraded experience: macOS ships no Node at
+    // all, so the launcher's first act would be `exec: node: not found`. The path
+    // is relative rather than the literal `../Helpers/…` written out, because
+    // `beside()` already carries the relation between `dirs.launcher` and
+    // wherever `appRuntimePaths` staged the interpreter — this function does not
+    // need to know that the leaf changed from `node` to `identity.name`.
     const interpreter = runtime.interpreter === undefined ? undefined : `"$here/${beside(runtime.interpreter)}"`;
     lines.push(`exec ${execLine(layout, `"$contents/${under(dirs.bundle)}/${bundleRelPath}"`, settings, interpreter)} "$@"`, '');
     return lines.join('\n');
@@ -462,8 +475,8 @@ function windowsPath(rel) {
  * `@gjsify/node-runtime-<target>` exists for; this comment used to say "the day a
  * stage carries one, THIS is the line that names it by a layout-relative path
  * instead", and #1354 M2b is that day — `utils/ship/app-runtime.ts` stages the
- * interpreter into `Contents/MacOS/node` and the `.app` launcher execs
- * `"$here/node"`.
+ * interpreter into `Contents/Helpers/<display name>` and the `.app` launcher
+ * execs `"$here/../Helpers/<display name>"`.
  *
  * #1354 M3 is the same day one OS over: the Windows layout stages `node.exe` into
  * the program directory and its `.cmd` runs `"%HERE%node.exe"`.

package/lib/utils/ship/layout.d.ts

@@ -128,6 +128,15 @@ export interface LayoutDirs {
      * bundle can address it and `codesign` later refuses the bundle.
      */
     other: string;
+    /**
+     * macOS only: where a carried interpreter lives when it must NOT be named
+     * `binaryName` inside {@link LayoutDirs.launcher} — see
+     * `utils/ship/app-runtime.ts`'s `appRuntimePaths`. `''` on linux and windows,
+     * where nothing reads it: Linux takes its interpreter from the distribution,
+     * and a Windows program directory has no launcher-collision to dodge in the
+     * first place, so its interpreter stays beside the `.cmd`.
+     */
+    helpers: string;
 }
 /**
  * One operating system's layout.
@@ -290,6 +299,20 @@ export interface LayoutArches {
  * {@link LAYOUTS.linux.icon} for what asked for each of the three.
  */
 export declare const HICOLOR_RASTER_SIZES: readonly [64, 128, 256];
+/**
+ * Refuse an `identity.name` that cannot be the carried interpreter's own file
+ * name under `Contents/Helpers` (`dirs.helpers`) — `appRuntimePaths` in
+ * `utils/ship/app-runtime.ts` is the only caller.
+ *
+ * A SUPERSET of {@link BUNDLE_NAME_FORBIDDEN}, not a restatement: the bundle
+ * directory wraps the same string in `.app`, so a name of "." or ".." becomes
+ * "..app" or "....app" — both ordinary directory names — while this leaf is
+ * `identity.name` taken LITERALLY, where "." and ".." name the directory
+ * itself and its parent. An empty name and a NUL byte are refused for the same
+ * reason `windowsProgramDirName` refuses them one OS over: neither is a name a
+ * filesystem can hold.
+ */
+export declare function assertUsableAsHelperName(name: string): string;
 export declare const LAYOUTS: Record<LayoutName, Layout>;
 /** Every layout name, derived from the table so a new row cannot be missed. */
 export declare const LAYOUT_NAMES: LayoutName[];

package/lib/utils/ship/layout.js

@@ -75,6 +75,28 @@ function appBundleDir(identity) {
     }
     return `${identity.name}.app`;
 }
+/**
+ * Refuse an `identity.name` that cannot be the carried interpreter's own file
+ * name under `Contents/Helpers` (`dirs.helpers`) — `appRuntimePaths` in
+ * `utils/ship/app-runtime.ts` is the only caller.
+ *
+ * A SUPERSET of {@link BUNDLE_NAME_FORBIDDEN}, not a restatement: the bundle
+ * directory wraps the same string in `.app`, so a name of "." or ".." becomes
+ * "..app" or "....app" — both ordinary directory names — while this leaf is
+ * `identity.name` taken LITERALLY, where "." and ".." name the directory
+ * itself and its parent. An empty name and a NUL byte are refused for the same
+ * reason `windowsProgramDirName` refuses them one OS over: neither is a name a
+ * filesystem can hold.
+ */
+export function assertUsableAsHelperName(name) {
+    if (name === '' || name === '.' || name === '..' || BUNDLE_NAME_FORBIDDEN.test(name) || name.includes('\u0000')) {
+        throw new Error(`gjsify ship: the macOS layout would name the carried interpreter "${name}" under ` +
+            '`Contents/Helpers`, and that is not usable as a file name — empty, ".", ".." and anything ' +
+            'containing "/", ":", "\\" or a NUL byte are refused. Set `gjsify.ship.name` to the display ' +
+            'name you want.');
+    }
+    return name;
+}
 /**
  * The rasters a row writes its icon from, or nothing for a CLI — and a refusal
  * for an application that arrives without them.
@@ -117,6 +139,7 @@ export const LAYOUTS = {
             native: `lib/${identity.binaryName}/gi`,
             data: 'share',
             other: '',
+            helpers: '',
         }),
         // THE RASTERS THE BUILD-TIME READERS OF THE THEME NEED, and the one row
         // whose icon is written as ordinary payload files rather than into a
@@ -280,6 +303,14 @@ export const LAYOUTS = {
                 native: `${app}/Contents/Resources/native`,
                 data: `${app}/Contents/Resources/share`,
                 other: `${app}/Contents/Resources`,
+                // Apple's own nested-code location (alongside `Frameworks`,
+                // `PlugIns`, `XPCServices` — `codesign(1)`'s bundle format), and the
+                // one place `appRuntimePaths` can put the interpreter under a name
+                // that is not `binaryName`: `Contents/MacOS` already holds the
+                // launcher, and APFS is case-insensitive by default, so a second
+                // file there named `<BinaryName>` collides with it bytewise even
+                // when the casing differs.
+                helpers: `${app}/Contents/Helpers`,
             };
         },
         // The two files that make the directory a BUNDLE. Without `Info.plist`
@@ -411,7 +442,7 @@ export const LAYOUTS = {
         // LOADER: `lib/` is what the launcher prepends to `PATH`, because Windows
         // has no rpath — a DLL is found on `PATH`, in the directory of the image
         // that loaded it, or not at all.
-        dirs: () => ({ launcher: '', bundle: 'app', native: 'lib', data: 'share', other: '' }),
+        dirs: () => ({ launcher: '', bundle: 'app', native: 'lib', data: 'share', other: '', helpers: '' }),
         // NO METADATA, and one PROGRAM. A Windows installer's metadata lives in the
         // `.msi`'s own tables, not in a file inside the program directory —
         // `msi.ts` puts every such fact in the `Product`/`Package` attributes of the

package/lib/utils/ship/node-runtime.js

@@ -28,12 +28,14 @@
 // THE CALLER IS `utils/ship/app-runtime.ts` (#1354 M2b), and this paragraph used
 // to say there was none — "⚠️ NOTHING CALLS THIS YET, outside its own spec … a
 // promise to a caller that does not exist yet". It exists: the macOS layout stages
-// `nodePath` into `Contents/MacOS/node` and `licensePath` beside it, and the
-// `null`-not-throw contract is what lets that caller stage the GTK closure it DID
-// find while naming the interpreter package it did not. #1354 M3 adds the second
-// caller — the Windows program directory stages `node.exe` beside its `.cmd` — so
-// both non-Linux rows of the table above are now used, and this paragraph no
-// longer has a "still has none" half to record.
+// `nodePath` into `Contents/Helpers/<display name>` and `licensePath` beside it in
+// `Contents/Resources`, and the `null`-not-throw contract is what lets that caller
+// stage the GTK closure it DID find while naming the interpreter package it did
+// not. #1354 M3 adds the second caller — the Windows program directory stages
+// `node.exe` beside its `.cmd` — so both non-Linux rows of the table above are now
+// used, and this paragraph no longer has a "still has none" half to record.
+// `node.exe` keeps that name verbatim: nothing collides with it on Windows, and
+// only the darwin leaf changed — see `layout.ts`'s `dirs.helpers`.
 //
 // The tests keep the by-name claim honest independently of any caller: they
 // resolve a real installed package out of a throwaway consumer tree holding

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@gjsify/cli",
-    "version": "0.64.5",
+    "version": "0.64.6",
     "description": "CLI for Gjsify",
     "type": "module",
     "main": "lib/index.js",
@@ -142,22 +142,22 @@
         "cli"
     ],
     "dependencies": {
-        "@gjsify/blueprint": "^0.64.5",
-        "@gjsify/buffer": "^0.64.5",
-        "@gjsify/create-app": "^0.64.5",
-        "@gjsify/node-globals": "^0.64.5",
-        "@gjsify/node-polyfills": "^0.64.5",
-        "@gjsify/npm-registry": "^0.64.5",
-        "@gjsify/resolve-npm": "^0.64.5",
-        "@gjsify/rolldown-plugin-gjsify": "^0.64.5",
-        "@gjsify/vite-plugin-blueprint": "^0.64.5",
-        "@gjsify/rolldown-plugin-pnp": "^0.64.5",
-        "@gjsify/semver": "^0.64.5",
-        "@gjsify/tar": "^0.64.5",
-        "@gjsify/tsc": "^0.64.5",
-        "@gjsify/utils": "^0.64.5",
-        "@gjsify/web-polyfills": "^0.64.5",
-        "@gjsify/workspace": "^0.64.5",
+        "@gjsify/blueprint": "^0.64.6",
+        "@gjsify/buffer": "^0.64.6",
+        "@gjsify/create-app": "^0.64.6",
+        "@gjsify/node-globals": "^0.64.6",
+        "@gjsify/node-polyfills": "^0.64.6",
+        "@gjsify/npm-registry": "^0.64.6",
+        "@gjsify/resolve-npm": "^0.64.6",
+        "@gjsify/rolldown-plugin-gjsify": "^0.64.6",
+        "@gjsify/vite-plugin-blueprint": "^0.64.6",
+        "@gjsify/rolldown-plugin-pnp": "^0.64.6",
+        "@gjsify/semver": "^0.64.6",
+        "@gjsify/tar": "^0.64.6",
+        "@gjsify/tsc": "^0.64.6",
+        "@gjsify/utils": "^0.64.6",
+        "@gjsify/web-polyfills": "^0.64.6",
+        "@gjsify/workspace": "^0.64.6",
         "acorn": "^8.17.0",
         "cosmiconfig": "^9.0.2",
         "get-tsconfig": "^4.14.0",
@@ -166,13 +166,13 @@
         "yargs": "^18.0.0"
     },
     "devDependencies": {
-        "@gjsify/unit": "^0.64.5",
+        "@gjsify/unit": "^0.64.6",
         "@types/yargs": "^17.0.35",
         "typescript": "^6.0.3"
     },
     "peerDependencies": {
-        "@gjsify/oxfmt-native": "^0.64.5",
-        "@gjsify/rolldown-native": "^0.64.5"
+        "@gjsify/oxfmt-native": "^0.64.6",
+        "@gjsify/rolldown-native": "^0.64.6"
     },
     "peerDependenciesMeta": {
         "@gjsify/oxfmt-native": {