@gjsify/node-gi 0.26.0 → 0.27.0

package/index.d.ts

@@ -3,12 +3,12 @@
 
 /** Result of requiring a GObject-Introspection namespace. */
 export interface RequiredNamespace {
-  /** The namespace name, e.g. "GLib". */
-  namespace: string;
-  /** The resolved typelib version, e.g. "2.0". */
-  version: string;
-  /** Number of top-level introspection infos in the namespace. */
-  infoCount: number;
+    /** The namespace name, e.g. "GLib". */
+    namespace: string;
+    /** The resolved typelib version, e.g. "2.0". */
+    version: string;
+    /** Number of top-level introspection infos in the namespace. */
+    infoCount: number;
 }
 
 /**
@@ -22,16 +22,16 @@ export function listInfoNames(namespace: string): string[];
 
 /** The introspection kind of a top-level namespace member. */
 export type InfoKind =
-  | 'function'
-  | 'object'
-  | 'interface'
-  | 'struct'
-  | 'union'
-  | 'enum'
-  | 'flags'
-  | 'constant'
-  | 'callback'
-  | 'other';
+    | 'function'
+    | 'object'
+    | 'interface'
+    | 'struct'
+    | 'union'
+    | 'enum'
+    | 'flags'
+    | 'constant'
+    | 'callback'
+    | 'other';
 
 /**
  * Classify a top-level namespace member so the L1 wrapper can decide how to
@@ -53,17 +53,14 @@ export function getEnumValues(namespace: string, name: string): Record<string, n
  * For an enum type registered as a GError domain (e.g. `Gio.IOErrorEnum`), report
  * its domain quark name + numeric quark; `null` for a plain enum.
  */
-export function getErrorDomain(
-  namespace: string,
-  name: string,
-): { name: string; quark: number } | null;
+export function getErrorDomain(namespace: string, name: string): { name: string; quark: number } | null;
 
 /**
  * Register the L1 GLib.Error factory the engine calls when a GI invoke fails, so
  * a failed sync call throws a real `GLib.Error` (instanceof, with `.matches()`).
  */
 export function setErrorBuilder(
-  builder: (domainName: string, domainQuark: number, code: number, message: string) => Error,
+    builder: (domainName: string, domainQuark: number, code: number, message: string) => Error,
 ): void;
 
 /** Prepend a directory to the GIRepository typelib search path. */
@@ -106,12 +103,7 @@ export function hasMethod(handle: GObjectHandle, methodName: string): boolean;
  * twin of `Ns.Class.method(...)`. OUT/INOUT params follow {@link callFunction}'s
  * return-tuple convention.
  */
-export function callStaticMethod(
-  namespace: string,
-  typeName: string,
-  methodName: string,
-  args?: unknown[],
-): unknown;
+export function callStaticMethod(namespace: string, typeName: string, methodName: string, args?: unknown[]): unknown;
 
 /**
  * Construct a boxed/plain struct instance — the `new <Struct>()` path (GJS
@@ -133,11 +125,7 @@ export type GObjectHandle = { readonly __nodeGiGObject: unique symbol };
  * properties. Milestone 1: fundamental-typed properties (numbers, booleans,
  * strings, enums/flags).
  */
-export function newObject(
-  namespace: string,
-  typeName: string,
-  props?: Record<string, unknown>,
-): GObjectHandle;
+export function newObject(namespace: string, typeName: string, props?: Record<string, unknown>): GObjectHandle;
 
 /**
  * Opaque handle to a registered GType (from {@link registerClass}). Pass it to
@@ -147,30 +135,30 @@ export type TypeHandle = { readonly __nodeGiGType: unique symbol };
 
 /** A custom GObject property declaration for {@link registerClass}. */
 export interface PropertySpec {
-  /** Property name (canonical, e.g. "my-prop"). */
-  name: string;
-  /** Value type. */
-  type: 'string' | 'boolean' | 'int' | 'uint' | 'int64' | 'uint64' | 'double' | 'float';
-  /** `GParamFlags` bitfield (default `G_PARAM_READWRITE`). */
-  flags?: number;
-  /** Default value (type-appropriate). */
-  default?: string | number | boolean;
-  /** Minimum (numeric types). */
-  minimum?: number;
-  /** Maximum (numeric types). */
-  maximum?: number;
+    /** Property name (canonical, e.g. "my-prop"). */
+    name: string;
+    /** Value type. */
+    type: 'string' | 'boolean' | 'int' | 'uint' | 'int64' | 'uint64' | 'double' | 'float';
+    /** `GParamFlags` bitfield (default `G_PARAM_READWRITE`). */
+    flags?: number;
+    /** Default value (type-appropriate). */
+    default?: string | number | boolean;
+    /** Minimum (numeric types). */
+    minimum?: number;
+    /** Maximum (numeric types). */
+    maximum?: number;
 }
 
 /** A custom GObject signal declaration for {@link registerClass}. */
 export interface SignalSpec {
-  /** Signal name (e.g. "my-signal"). */
-  name: string;
-  /** Parameter types (same vocabulary as {@link PropertySpec.type}, plus "object"). */
-  paramTypes?: string[];
-  /** Return type ("void" by default). */
-  returnType?: string;
-  /** `GSignalFlags` bitfield (default `G_SIGNAL_RUN_LAST`). */
-  flags?: number;
+    /** Signal name (e.g. "my-signal"). */
+    name: string;
+    /** Parameter types (same vocabulary as {@link PropertySpec.type}, plus "object"). */
+    paramTypes?: string[];
+    /** Return type ("void" by default). */
+    returnType?: string;
+    /** `GSignalFlags` bitfield (default `G_SIGNAL_RUN_LAST`). */
+    flags?: number;
 }
 
 /**
@@ -185,23 +173,23 @@ export type VFuncMap = Record<string, (this: GObjectHandle, ...args: unknown[])
 
 /** Custom properties, signals + vfunc overrides installed on a {@link registerClass} subtype. */
 export interface RegisterClassOptions {
-  properties?: PropertySpec[];
-  signals?: SignalSpec[];
-  vfuncs?: VFuncMap;
-  /**
-   * A Gtk.Widget composite template. Either inline UI-XML (a `Uint8Array`/Buffer
-   * or a string) installed via `gtk_widget_class_set_template`, or a
-   * `"resource:///…"` path string installed via
-   * `gtk_widget_class_set_template_from_resource`. Installed in the subtype's
-   * `class_init`; `gtk_widget_init_template` runs at construction.
-   */
-  template?: Uint8Array | string;
-  /** `gtk_widget_class_set_css_name` for the subtype (optional). */
-  cssName?: string;
-  /** Template child ids to bind + expose publicly (via `gtk_widget_get_template_child`). */
-  children?: string[];
-  /** Template child ids to bind as internal children + expose privately. */
-  internalChildren?: string[];
+    properties?: PropertySpec[];
+    signals?: SignalSpec[];
+    vfuncs?: VFuncMap;
+    /**
+     * A Gtk.Widget composite template. Either inline UI-XML (a `Uint8Array`/Buffer
+     * or a string) installed via `gtk_widget_class_set_template`, or a
+     * `"resource:///…"` path string installed via
+     * `gtk_widget_class_set_template_from_resource`. Installed in the subtype's
+     * `class_init`; `gtk_widget_init_template` runs at construction.
+     */
+    template?: Uint8Array | string;
+    /** `gtk_widget_class_set_css_name` for the subtype (optional). */
+    cssName?: string;
+    /** Template child ids to bind + expose publicly (via `gtk_widget_get_template_child`). */
+    children?: string[];
+    /** Template child ids to bind as internal children + expose privately. */
+    internalChildren?: string[];
 }
 
 /**
@@ -214,10 +202,10 @@ export interface RegisterClassOptions {
  * parent vtable pointer it displaces, so it can chain up via {@link callParentVfunc}.
  */
 export function registerClass(
-  name: string,
-  parentNamespace: string,
-  parentTypeName: string,
-  options?: RegisterClassOptions,
+    name: string,
+    parentNamespace: string,
+    parentTypeName: string,
+    options?: RegisterClassOptions,
 ): TypeHandle;
 
 /**
@@ -231,11 +219,7 @@ export function registerClass(
  * OUT/INOUT argument (chain-up of those is not yet supported — a catchable throw,
  * never a crash).
  */
-export function callParentVfunc(
-  handle: GObjectHandle,
-  vfuncName: string,
-  args?: unknown[],
-): unknown;
+export function callParentVfunc(handle: GObjectHandle, vfuncName: string, args?: unknown[]): unknown;
 
 /**
  * Construct a GObject of a registered type handle (from {@link registerClass})
@@ -463,10 +447,10 @@ export function setMicrotaskDrain(drain: () => void): void;
  * milestone).
  */
 export function connectSignal(
-  handle: GObjectHandle,
-  signalName: string,
-  callback: (...args: unknown[]) => unknown,
-  after?: boolean,
+    handle: GObjectHandle,
+    signalName: string,
+    callback: (...args: unknown[]) => unknown,
+    after?: boolean,
 ): number;
 
 /** Emit a signal; returns the signal's return value (undefined for void signals). */
@@ -480,10 +464,7 @@ export function disconnectSignal(handle: GObjectHandle, handlerId: number): void
  * name to the instance's bound JS method (engine template-callback scope).
  */
 export function setTemplateCallbackResolver(
-  resolver: (
-    handle: GObjectHandle,
-    handlerName: string,
-  ) => ((...args: unknown[]) => unknown) | undefined,
+    resolver: (handle: GObjectHandle, handlerName: string) => ((...args: unknown[]) => unknown) | undefined,
 ): void;
 
 /**
@@ -494,7 +475,7 @@ export function setTemplateCallbackResolver(
  * process (a second aborts in GLib).
  */
 export function logSetWriterFunc(
-  writer: ((logLevel: number, fields: Record<string, Uint8Array | null>) => number) | null,
+    writer: ((logLevel: number, fields: Record<string, Uint8Array | null>) => number) | null,
 ): void;
 
 /** Route structured logs back to the default writer (GLib.log_set_writer_default). */
@@ -506,13 +487,13 @@ export function logSetWriterDefault(): void;
  * `(binding, sourceValue) => [ok: boolean, targetValue]`. Returns the GBinding handle.
  */
 export function bindPropertyFull(
-  source: GObjectHandle,
-  sourceProperty: string,
-  target: GObjectHandle,
-  targetProperty: string,
-  flags: number,
-  transformTo: ((...args: unknown[]) => unknown) | null,
-  transformFrom: ((...args: unknown[]) => unknown) | null,
+    source: GObjectHandle,
+    sourceProperty: string,
+    target: GObjectHandle,
+    targetProperty: string,
+    flags: number,
+    transformTo: ((...args: unknown[]) => unknown) | null,
+    transformFrom: ((...args: unknown[]) => unknown) | null,
 ): GObjectHandle;
 
 /**
@@ -520,66 +501,66 @@ export function bindPropertyFull(
  * GObject.BindingGroup.bind_full). Same transform contract as {@link bindPropertyFull}.
  */
 export function bindingGroupBindFull(
-  group: GObjectHandle,
-  sourceProperty: string,
-  target: GObjectHandle,
-  targetProperty: string,
-  flags: number,
-  transformTo: ((...args: unknown[]) => unknown) | null,
-  transformFrom: ((...args: unknown[]) => unknown) | null,
+    group: GObjectHandle,
+    sourceProperty: string,
+    target: GObjectHandle,
+    targetProperty: string,
+    flags: number,
+    transformTo: ((...args: unknown[]) => unknown) | null,
+    transformFrom: ((...args: unknown[]) => unknown) | null,
 ): void;
 
 declare const native: {
-  requireNamespace: typeof requireNamespace;
-  listInfoNames: typeof listInfoNames;
-  findInfo: typeof findInfo;
-  getConstantValue: typeof getConstantValue;
-  getEnumValues: typeof getEnumValues;
-  getErrorDomain: typeof getErrorDomain;
-  setErrorBuilder: typeof setErrorBuilder;
-  prependSearchPath: typeof prependSearchPath;
-  callFunction: typeof callFunction;
-  callMethod: typeof callMethod;
-  hasMethod: typeof hasMethod;
-  callStaticMethod: typeof callStaticMethod;
-  constructStruct: typeof constructStruct;
-  newObject: typeof newObject;
-  registerClass: typeof registerClass;
-  constructType: typeof constructType;
-  getTemplateChild: typeof getTemplateChild;
-  getProperty: typeof getProperty;
-  setProperty: typeof setProperty;
-  hasProperty: typeof hasProperty;
-  getTypeName: typeof getTypeName;
-  getGType: typeof getGType;
-  isInstanceOf: typeof isInstanceOf;
-  isGObjectHandle: typeof isGObjectHandle;
-  newGValue: typeof newGValue;
-  callBoxedMethod: typeof callBoxedMethod;
-  isBoxedHandle: typeof isBoxedHandle;
-  boxedMemberKind: typeof boxedMemberKind;
-  getBoxedField: typeof getBoxedField;
-  setBoxedField: typeof setBoxedField;
-  boxedTypeName: typeof boxedTypeName;
-  isParamSpecHandle: typeof isParamSpecHandle;
-  paramSpecProp: typeof paramSpecProp;
-  variantNew: typeof variantNew;
-  variantUnpack: typeof variantUnpack;
-  variantGetTypeString: typeof variantGetTypeString;
-  isVariantHandle: typeof isVariantHandle;
-  startMainLoop: typeof startMainLoop;
-  iterateMainContext: typeof iterateMainContext;
-  mainContextHasPending: typeof mainContextHasPending;
-  makePumpPendingCount: typeof makePumpPendingCount;
-  pumpKick: typeof pumpKick;
-  setMicrotaskDrain: typeof setMicrotaskDrain;
-  connectSignal: typeof connectSignal;
-  emitSignal: typeof emitSignal;
-  disconnectSignal: typeof disconnectSignal;
-  setTemplateCallbackResolver: typeof setTemplateCallbackResolver;
-  logSetWriterFunc: typeof logSetWriterFunc;
-  logSetWriterDefault: typeof logSetWriterDefault;
-  bindPropertyFull: typeof bindPropertyFull;
-  bindingGroupBindFull: typeof bindingGroupBindFull;
+    requireNamespace: typeof requireNamespace;
+    listInfoNames: typeof listInfoNames;
+    findInfo: typeof findInfo;
+    getConstantValue: typeof getConstantValue;
+    getEnumValues: typeof getEnumValues;
+    getErrorDomain: typeof getErrorDomain;
+    setErrorBuilder: typeof setErrorBuilder;
+    prependSearchPath: typeof prependSearchPath;
+    callFunction: typeof callFunction;
+    callMethod: typeof callMethod;
+    hasMethod: typeof hasMethod;
+    callStaticMethod: typeof callStaticMethod;
+    constructStruct: typeof constructStruct;
+    newObject: typeof newObject;
+    registerClass: typeof registerClass;
+    constructType: typeof constructType;
+    getTemplateChild: typeof getTemplateChild;
+    getProperty: typeof getProperty;
+    setProperty: typeof setProperty;
+    hasProperty: typeof hasProperty;
+    getTypeName: typeof getTypeName;
+    getGType: typeof getGType;
+    isInstanceOf: typeof isInstanceOf;
+    isGObjectHandle: typeof isGObjectHandle;
+    newGValue: typeof newGValue;
+    callBoxedMethod: typeof callBoxedMethod;
+    isBoxedHandle: typeof isBoxedHandle;
+    boxedMemberKind: typeof boxedMemberKind;
+    getBoxedField: typeof getBoxedField;
+    setBoxedField: typeof setBoxedField;
+    boxedTypeName: typeof boxedTypeName;
+    isParamSpecHandle: typeof isParamSpecHandle;
+    paramSpecProp: typeof paramSpecProp;
+    variantNew: typeof variantNew;
+    variantUnpack: typeof variantUnpack;
+    variantGetTypeString: typeof variantGetTypeString;
+    isVariantHandle: typeof isVariantHandle;
+    startMainLoop: typeof startMainLoop;
+    iterateMainContext: typeof iterateMainContext;
+    mainContextHasPending: typeof mainContextHasPending;
+    makePumpPendingCount: typeof makePumpPendingCount;
+    pumpKick: typeof pumpKick;
+    setMicrotaskDrain: typeof setMicrotaskDrain;
+    connectSignal: typeof connectSignal;
+    emitSignal: typeof emitSignal;
+    disconnectSignal: typeof disconnectSignal;
+    setTemplateCallbackResolver: typeof setTemplateCallbackResolver;
+    logSetWriterFunc: typeof logSetWriterFunc;
+    logSetWriterDefault: typeof logSetWriterDefault;
+    bindPropertyFull: typeof bindPropertyFull;
+    bindingGroupBindFull: typeof bindingGroupBindFull;
 };
 export default native;

package/index.js

@@ -11,9 +11,8 @@
 // Deno — the three runtimes that implement Node-API. Runtime-specific behaviour
 // (the libuv main-loop bridge is Node-only) is gated in gi.js off RUNTIME below.
 import { createRequire } from 'node:module';
-import { fileURLToPath } from 'node:url';
-import { dirname, join } from 'node:path';
 import { existsSync } from 'node:fs';
+import { hostTarget, nativeCandidates, packageRoot } from './native-paths.js';
 import {
     activateBundledGtkRuntime,
     maybePrependGtkRuntimeDllPath,
@@ -46,7 +45,7 @@ maybePrependGtkRuntimeDllPath();
 maybeWireGtkWindowingEnv();
 
 const require = createRequire(import.meta.url);
-const here = dirname(fileURLToPath(import.meta.url)); // package root
+const here = packageRoot; // the package root, from the shared native-paths module
 
 /**
  * Which JS runtime we are on. The Node-API addon loads on all four: Node, Bun
@@ -61,35 +60,17 @@ const here = dirname(fileURLToPath(import.meta.url)); // package root
  * @type {'bun' | 'deno' | 'gjs' | 'node'}
  */
 export const RUNTIME =
-  typeof globalThis.imports !== 'undefined' && typeof globalThis.print === 'function'
-    ? 'gjs'
-    : typeof globalThis.Bun !== 'undefined'
-      ? 'bun'
-      : typeof globalThis.Deno !== 'undefined'
-        ? 'deno'
-        : 'node';
+    typeof globalThis.imports !== 'undefined' && typeof globalThis.print === 'function'
+        ? 'gjs'
+        : typeof globalThis.Bun !== 'undefined'
+          ? 'bun'
+          : typeof globalThis.Deno !== 'undefined'
+            ? 'deno'
+            : 'node';
 
 /** Whether we are on Node.js (the only runtime with the libuv main-loop bridge). */
 export const isNodeRuntime = RUNTIME === 'node';
 
-function nativeCandidates() {
-  const prebuild = join(here, 'prebuilds', `${process.platform}-${process.arch}`, 'node_gi.node');
-  const release = join(here, 'build', 'Release', 'node_gi.node');
-  const debug = join(here, 'build', 'Debug', 'node_gi.node');
-  // NODE_GI_NATIVE pins which binary loads. The package's own test scripts set
-  // `build` so local verification always exercises the JUST-BUILT addon — a stale
-  // staged prebuild would otherwise shadow build/Release and silently validate
-  // the wrong binary (the consumer-facing default below prefers the prebuild).
-  const prefer = process.env.NODE_GI_NATIVE;
-  if (prefer === 'build') return [release, debug, prebuild];
-  if (prefer === 'prebuild') return [prebuild];
-  if (prefer) return [prefer]; // an explicit path to a node_gi.node
-  // Default: prefer a shipped prebuild so a consumer needs no C toolchain and no
-  // node-gyp — the only install path Deno supports (it runs no postinstall build
-  // script). Fall back to a locally built addon (Release, then Debug).
-  return [prebuild, release, debug];
-}
-
 // GJS host mode: the addon is loaded through the @gjsify/napi shim, not
 // `require()`. The loader native is `globalThis.__gjsifyNapiLoadAddon`,
 // installed by `GjsifyNapi.init()`; if another consumer (the @gjsify/napi L1)
@@ -97,40 +78,40 @@ function nativeCandidates() {
 // GjsifyNapi typelib must be resolvable (GI_TYPELIB_PATH/LD_LIBRARY_PATH →
 // the shim prebuild).
 function gjsLoadAddon(path) {
-  let load = globalThis.__gjsifyNapiLoadAddon;
-  if (typeof load !== 'function') {
-    const GjsifyNapi = globalThis.imports?.gi?.GjsifyNapi;
-    if (!GjsifyNapi || !GjsifyNapi.init()) {
-      throw new Error(
-        '@gjsify/node-gi: GJS host mode needs the @gjsify/napi shim — the GjsifyNapi ' +
-          'typelib is not loadable (point GI_TYPELIB_PATH and LD_LIBRARY_PATH at its prebuild).',
-      );
-    }
-    load = globalThis.__gjsifyNapiLoadAddon;
+    let load = globalThis.__gjsifyNapiLoadAddon;
     if (typeof load !== 'function') {
-      throw new Error('@gjsify/node-gi: GjsifyNapi.init() did not install the addon loader.');
+        const GjsifyNapi = globalThis.imports?.gi?.GjsifyNapi;
+        if (!GjsifyNapi || !GjsifyNapi.init()) {
+            throw new Error(
+                '@gjsify/node-gi: GJS host mode needs the @gjsify/napi shim — the GjsifyNapi ' +
+                    'typelib is not loadable (point GI_TYPELIB_PATH and LD_LIBRARY_PATH at its prebuild).',
+            );
+        }
+        load = globalThis.__gjsifyNapiLoadAddon;
+        if (typeof load !== 'function') {
+            throw new Error('@gjsify/node-gi: GjsifyNapi.init() did not install the addon loader.');
+        }
+        // Capture-then-delete, the same no-side-channel discipline as the L1.
+        delete globalThis.__gjsifyNapiLoadAddon;
     }
-    // Capture-then-delete, the same no-side-channel discipline as the L1.
-    delete globalThis.__gjsifyNapiLoadAddon;
-  }
-  return load(path);
+    return load(path);
 }
 
 function loadNative() {
-  for (const candidate of nativeCandidates()) {
-    if (existsSync(candidate)) {
-      return RUNTIME === 'gjs' ? gjsLoadAddon(candidate) : require(candidate);
+    for (const candidate of nativeCandidates()) {
+        if (existsSync(candidate)) {
+            return RUNTIME === 'gjs' ? gjsLoadAddon(candidate) : require(candidate);
+        }
     }
-  }
-  throw new Error(
-    `@gjsify/node-gi: native addon not found for ${RUNTIME} on ${process.platform}-${process.arch}. ` +
-      `Expected a prebuild at prebuilds/${process.platform}-${process.arch}/node_gi.node or a local build. ` +
-      'Run `node-gyp rebuild` in ' +
-      here +
-      ' (requires a C++ toolchain and the girepository-2.0 / glib-2.0 development headers), ' +
-      'or install a package build that ships a prebuild for your platform. ' +
-      'Under a bundled GJS app (import.meta anchors at the bundle), set NODE_GI_NATIVE to the addon path.',
-  );
+    throw new Error(
+        `@gjsify/node-gi: native addon not found for ${RUNTIME} on ${hostTarget()}. ` +
+            `Expected a prebuild at prebuilds/${hostTarget()}/node_gi.node or a local build. ` +
+            'Run `node-gyp rebuild` in ' +
+            here +
+            ' (requires a C++ toolchain and the girepository-2.0 / glib-2.0 development headers), ' +
+            'or install a package build that ships a prebuild for your platform. ' +
+            'Under a bundled GJS app (import.meta anchors at the bundle), set NODE_GI_NATIVE to the addon path.',
+    );
 }
 
 const native = loadNative();
@@ -142,12 +123,13 @@ const native = loadNative();
 // staged prebuilds/<platform>-<arch>/gtk/). This prepends the bundle's typelib
 // dir to the GIRepository search path (env-free) so gi:// namespaces load with
 // no Homebrew/system GTK. No-op on platforms without a bundle, and harmless when
-// none is present (the addon then uses the host's GTK as before). Darwin-only
-// today — see gtk-runtime.js + @gjsify/gtk-runtime-darwin-arm64.
+// none is present (the addon then uses the host's GTK as before). Scoped to
+// darwin + win32 — see gtk-runtime.js + @gjsify/gtk-runtime-{darwin-arm64,
+// darwin-x64,win32-x64}.
 try {
-  activateBundledGtkRuntime(native);
+    activateBundledGtkRuntime(native);
 } catch {
-  // Never fatal: a missing/partial bundle just leaves the host GTK in charge.
+    // Never fatal: a missing/partial bundle just leaves the host GTK in charge.
 }
 
 // ---- cross-runtime microtask checkpoint (Bun/Deno) --------------------------
@@ -172,47 +154,47 @@ try {
 // own main-loop source whenever the last JS frame exits — the exact semantic
 // this checkpoint recreates for Bun/Deno.
 if (!isNodeRuntime && RUNTIME !== 'gjs') {
-  try {
-    let drain = null;
-    if (RUNTIME === 'bun') {
-      // JSC: drains the VM's microtask queue; callable mid-stack by design
-      // (Bun's own processTicksAndRejections calls it from JS).
-      ({ drainMicrotasks: drain } = require('bun:jsc'));
-    } else if (typeof globalThis.Deno?.internal === 'symbol') {
-      // V8: the checkpoint needs BOTH queues. core.runMicrotasks is only
-      // Isolate::PerformMicrotaskCheckpoint; Deno's node-compat
-      // process.nextTick queue is a SEPARATE deno_core queue
-      // (ext:deno_node/_next_tick.ts → core.queueNextTick) that only the
-      // runtime's own event loop drains — and that loop is paused for the
-      // whole lifetime of a blocking run(). node:stream delivers stream
-      // 'end' via process.nextTick (endReadableNT), so with a
-      // microtask-only drain any body consumption over a Readable
-      // (@gjsify/fetch consumeBody → XHR arrayBuffer/text) got its chunks
-      // (microtask-delivered) but never the end: every asset load hung at
-      // readyState 3 forever on Deno while the SAME bundle settled on Bun,
-      // whose nextTick rides JSC's microtask queue (bun:jsc
-      // drainMicrotasks covers it). core.runNextTicks mirrors node's
-      // task_queues.js runNextTicks: microtask checkpoint when no ticks
-      // are scheduled, full processTicksAndRejections (ticks + microtasks
-      // interleaved) when there are — one call, both queues. Regression:
-      // test/blocking-run-checkpoint.test.mjs.
-      const core = globalThis.Deno[globalThis.Deno.internal]?.core;
-      if (typeof core?.runNextTicks === 'function') {
-        drain = () => core.runNextTicks();
-      } else if (typeof core?.runMicrotasks === 'function') {
-        // Older deno_core without runNextTicks: microtask-only drain
-        // (pre-fix behaviour — promise continuations settle, nextTick
-        // consumers like node:stream 'end' still starve).
-        drain = () => core.runMicrotasks();
-      }
+    try {
+        let drain = null;
+        if (RUNTIME === 'bun') {
+            // JSC: drains the VM's microtask queue; callable mid-stack by design
+            // (Bun's own processTicksAndRejections calls it from JS).
+            ({ drainMicrotasks: drain } = require('bun:jsc'));
+        } else if (typeof globalThis.Deno?.internal === 'symbol') {
+            // V8: the checkpoint needs BOTH queues. core.runMicrotasks is only
+            // Isolate::PerformMicrotaskCheckpoint; Deno's node-compat
+            // process.nextTick queue is a SEPARATE deno_core queue
+            // (ext:deno_node/_next_tick.ts → core.queueNextTick) that only the
+            // runtime's own event loop drains — and that loop is paused for the
+            // whole lifetime of a blocking run(). node:stream delivers stream
+            // 'end' via process.nextTick (endReadableNT), so with a
+            // microtask-only drain any body consumption over a Readable
+            // (@gjsify/fetch consumeBody → XHR arrayBuffer/text) got its chunks
+            // (microtask-delivered) but never the end: every asset load hung at
+            // readyState 3 forever on Deno while the SAME bundle settled on Bun,
+            // whose nextTick rides JSC's microtask queue (bun:jsc
+            // drainMicrotasks covers it). core.runNextTicks mirrors node's
+            // task_queues.js runNextTicks: microtask checkpoint when no ticks
+            // are scheduled, full processTicksAndRejections (ticks + microtasks
+            // interleaved) when there are — one call, both queues. Regression:
+            // test/blocking-run-checkpoint.test.mjs.
+            const core = globalThis.Deno[globalThis.Deno.internal]?.core;
+            if (typeof core?.runNextTicks === 'function') {
+                drain = () => core.runNextTicks();
+            } else if (typeof core?.runMicrotasks === 'function') {
+                // Older deno_core without runNextTicks: microtask-only drain
+                // (pre-fix behaviour — promise continuations settle, nextTick
+                // consumers like node:stream 'end' still starve).
+                drain = () => core.runMicrotasks();
+            }
+        }
+        if (typeof drain === 'function') native.setMicrotaskDrain(drain);
+    } catch {
+        // Unregistered ⇒ pre-fix behaviour on this runtime build: promise
+        // continuations drain only when the runtime's own loop runs
+        // (startMainContextPump); async DBus replies inside a BLOCKING run stay
+        // unavailable. Never fatal — the sync surface is unaffected.
     }
-    if (typeof drain === 'function') native.setMicrotaskDrain(drain);
-  } catch {
-    // Unregistered ⇒ pre-fix behaviour on this runtime build: promise
-    // continuations drain only when the runtime's own loop runs
-    // (startMainContextPump); async DBus replies inside a BLOCKING run stay
-    // unavailable. Never fatal — the sync surface is unaffected.
-  }
 }
 
 /**