bunite-core 0.12.1 → 0.16.0

package/src/host/core/SurfaceRegistry.ts

@@ -21,6 +21,13 @@ export function trackSurface(surfaceId: number, record: SurfaceRecord) {
   ids.add(surfaceId);
 }
 
+type DisposeHook = (surfaceId: number) => void;
+const disposeHooks: DisposeHook[] = [];
+
+export function onSurfaceDispose(cb: DisposeHook) {
+  disposeHooks.push(cb);
+}
+
 export function untrackSurface(surfaceId: number) {
   const record = surfaces.get(surfaceId);
   if (!record) return;
@@ -30,6 +37,7 @@ export function untrackSurface(surfaceId: number) {
     ids.delete(surfaceId);
     if (ids.size === 0) hostSurfaceIds.delete(record.hostViewId);
   }
+  for (const cb of disposeHooks) cb(surfaceId);
 }
 
 export function getOwnedSurface(surfaceId: number, ctx: { viewId: number }): SurfaceRecord | null {
@@ -54,7 +62,7 @@ export function removeSurfacesForHostView(hostViewId: number) {
   for (const surfaceId of Array.from(ids)) {
     const record = surfaces.get(surfaceId);
     if (!record) continue;
-    untrackSurface(surfaceId);
+    untrackSurface(surfaceId);  // fires disposeHooks
     record.view.remove();
   }
 }

package/src/host/core/inputDispatch.ts

@@ -0,0 +1,147 @@
+// Input dispatch helpers — modifier encoding + DOM `key` → Win32 VK + macOS
+// Quartz key code + DOM `code` + char. Backends translate the FFI bitmask
+// (Alt=1, Ctrl=2, Meta=4, Shift=8) to native form. Stage B keymap covers
+// ASCII + the named keys Playwright-style automation relies on.
+
+import type { Modifier } from "../../rpc/framework";
+
+export function encodeModifiers(mods: Modifier[] | undefined): number {
+  if (!mods) return 0;
+  let bits = 0;
+  for (const m of mods) {
+    if (m === "alt") bits |= 1;
+    else if (m === "ctrl") bits |= 2;
+    else if (m === "meta") bits |= 4;
+    else if (m === "shift") bits |= 8;
+  }
+  return bits;
+}
+
+export interface ResolvedKey {
+  windowsVkCode: number;
+  macKeyCode: number;
+  /** DOM `KeyboardEvent.key` — pass-through; native dispatchers forward to engines. */
+  key: string;
+  /** DOM `KeyboardEvent.code` — derived from US keyboard mapping. */
+  code: string;
+  /** Text payload for the CHAR / insertText event; empty = skip char. */
+  character: string;
+  /** Win scancode 0xE0 prefix: nav cluster (Arrow/Insert/Delete/Home/End/
+   *  PageUp/PageDown/Meta/ContextMenu) AND Numpad-Enter. Distinct from
+   *  `location` — most extended keys are NOT numpad (location 0). */
+  extended: boolean;
+  /** DOM `KeyboardEvent.location`: 0=standard, 1=left mod, 2=right mod,
+   *  3=numpad. WV2 CDP uses this; CEF derives from scancode 0xE0 prefix. */
+  location: 0 | 1 | 2 | 3;
+}
+
+/** Maps a DOM `KeyboardEvent.key` value to backend-neutral identifiers. */
+export function resolveKey(domKey: string): ResolvedKey {
+  if (domKey.length === 0) {
+    return { windowsVkCode: 0, macKeyCode: 0, key: "", code: "", character: "", extended: false, location: 0 };
+  }
+
+  // Named key (Enter, Tab, ArrowLeft …).
+  const named = NAMED_KEYS[domKey];
+  if (named) {
+    return {
+      windowsVkCode: named.win,
+      macKeyCode: named.mac,
+      key: domKey,
+      code: named.code,
+      // Space/Tab/Enter generate text in CDP automatically; we pass an explicit
+      // character so DOM `keypress` fires consistently across engines.
+      character: named.character ?? "",
+      extended: named.ext === true,
+      location: named.loc ?? 0,
+    };
+  }
+
+  // Single Unicode codepoint — letter / digit / printable / extended.
+  if ([...domKey].length === 1) {
+    const cp = domKey.codePointAt(0)!;
+    // ASCII A-Z / a-z → matching Win VK + mac keyCode + DOM code "KeyX".
+    if ((cp >= 0x41 && cp <= 0x5A) || (cp >= 0x61 && cp <= 0x7A)) {
+      const upper = cp & ~0x20;  // strip lowercase bit
+      return {
+        windowsVkCode: upper,
+        macKeyCode: MAC_KEY_LETTER[upper - 0x41],
+        key: domKey,
+        code: `Key${String.fromCharCode(upper)}`,
+        character: domKey,
+        extended: false,
+        location: 0,
+      };
+    }
+    // ASCII 0-9.
+    if (cp >= 0x30 && cp <= 0x39) {
+      return {
+        windowsVkCode: cp,
+        macKeyCode: MAC_KEY_DIGIT[cp - 0x30],
+        key: domKey,
+        code: `Digit${domKey}`,
+        character: domKey,
+        extended: false,
+        location: 0,
+      };
+    }
+    // Other printable codepoint — char event only, no virtual key.
+    return { windowsVkCode: 0, macKeyCode: 0, key: domKey, code: "", character: domKey, extended: false, location: 0 };
+  }
+
+  // Multi-codepoint string we don't recognise as a named key — pass-through.
+  return { windowsVkCode: 0, macKeyCode: 0, key: domKey, code: "", character: "", extended: false, location: 0 };
+}
+
+// Win32 VK_* + Quartz Event Services kVK_* + DOM code + literal character +
+// LPARAM extended-key flag. `ext: true` for nav-cluster keys (separate from
+// numpad equivalents) and Numpad-Enter — Chromium derives `KeyboardEvent.code`
+// from LPARAM scancode + extended bit. Sources:
+//   learn.microsoft.com/windows/win32/inputdev/virtual-key-codes
+//   chromium/ui/events/keycodes/dom/keycode_converter_data.inc
+type NamedKey = { win: number; mac: number; code: string; character?: string; ext?: true; loc?: 1 | 2 | 3 };
+const NAMED_KEYS: Record<string, NamedKey> = {
+  Backspace:    { win: 0x08, mac: 0x33, code: "Backspace" },
+  Tab:          { win: 0x09, mac: 0x30, code: "Tab", character: "\t" },
+  Enter:        { win: 0x0D, mac: 0x24, code: "Enter", character: "\r" },
+  NumpadEnter:  { win: 0x0D, mac: 0x4C, code: "NumpadEnter", character: "\r", ext: true, loc: 3 },
+  Escape:       { win: 0x1B, mac: 0x35, code: "Escape" },
+  " ":          { win: 0x20, mac: 0x31, code: "Space", character: " " },
+  Space:        { win: 0x20, mac: 0x31, code: "Space", character: " " },
+  PageUp:       { win: 0x21, mac: 0x74, code: "PageUp", ext: true },
+  PageDown:     { win: 0x22, mac: 0x79, code: "PageDown", ext: true },
+  End:          { win: 0x23, mac: 0x77, code: "End", ext: true },
+  Home:         { win: 0x24, mac: 0x73, code: "Home", ext: true },
+  ArrowLeft:    { win: 0x25, mac: 0x7B, code: "ArrowLeft", ext: true },
+  ArrowUp:      { win: 0x26, mac: 0x7E, code: "ArrowUp", ext: true },
+  ArrowRight:   { win: 0x27, mac: 0x7C, code: "ArrowRight", ext: true },
+  ArrowDown:    { win: 0x28, mac: 0x7D, code: "ArrowDown", ext: true },
+  Insert:       { win: 0x2D, mac: 0x72, code: "Insert", ext: true },
+  Delete:       { win: 0x2E, mac: 0x75, code: "Delete", ext: true },
+  Meta:         { win: 0x5B, mac: 0x37, code: "MetaLeft", ext: true },
+  ContextMenu:  { win: 0x5D, mac: 0x6E, code: "ContextMenu", ext: true },
+  F1:  { win: 0x70, mac: 0x7A, code: "F1" },
+  F2:  { win: 0x71, mac: 0x78, code: "F2" },
+  F3:  { win: 0x72, mac: 0x63, code: "F3" },
+  F4:  { win: 0x73, mac: 0x76, code: "F4" },
+  F5:  { win: 0x74, mac: 0x60, code: "F5" },
+  F6:  { win: 0x75, mac: 0x61, code: "F6" },
+  F7:  { win: 0x76, mac: 0x62, code: "F7" },
+  F8:  { win: 0x77, mac: 0x64, code: "F8" },
+  F9:  { win: 0x78, mac: 0x65, code: "F9" },
+  F10: { win: 0x79, mac: 0x6D, code: "F10" },
+  F11: { win: 0x7A, mac: 0x67, code: "F11" },
+  F12: { win: 0x7B, mac: 0x6F, code: "F12" },
+};
+
+// US keyboard layout — Quartz hardware key code per ASCII letter (A → 0x00, …, Z → 0x06).
+const MAC_KEY_LETTER = [
+  // A    B    C    D    E    F    G    H    I    J    K    L    M
+  0x00, 0x0B, 0x08, 0x02, 0x0E, 0x03, 0x05, 0x04, 0x22, 0x26, 0x28, 0x25, 0x2E,
+  // N    O    P    Q    R    S    T    U    V    W    X    Y    Z
+  0x2D, 0x1F, 0x23, 0x0C, 0x0F, 0x01, 0x11, 0x20, 0x09, 0x0D, 0x07, 0x10, 0x06,
+];
+// US keyboard layout — Quartz hardware key code per digit (0 → 0x1D, 1 → 0x12 …).
+const MAC_KEY_DIGIT = [
+  0x1D, 0x12, 0x13, 0x14, 0x15, 0x17, 0x16, 0x1A, 0x1C, 0x19,
+];

package/src/host/events/webviewEvents.ts

@@ -8,5 +8,29 @@ export default {
     new BuniteEvent("new-window-open", data),
   permissionRequested: (data: { requestId: number; kind: number; url?: string }) =>
     new BuniteEvent("permission-requested", data),
-  titleChanged: (data: { detail: string }) => new BuniteEvent("title-changed", data)
+  titleChanged: (data: { detail: string }) => new BuniteEvent("title-changed", data),
+  loadStart: (data: { detail: string }) => new BuniteEvent("load-start", data),
+  loadFinish: (data: { detail: string }) => new BuniteEvent("load-finish", data),
+  loadFail: (data: { url: string; reason?: string }) => new BuniteEvent("load-fail", data),
+  dialog: (data: { requestId: number; kind: "alert" | "confirm" | "prompt" | "beforeunload"; message: string; defaultPrompt?: string }) =>
+    new BuniteEvent("dialog", data),
+  consoleMessage: (data: { level: "log" | "warn" | "error" | "info" | "debug"; args: string[]; ts: number }) =>
+    new BuniteEvent("console-message", data),
+  downloadEvent: (data: {
+    kind: "started" | "progress" | "completed" | "failed" | "blocked";
+    id: string;
+    url?: string;
+    suggestedFilename?: string;
+    mimeType?: string;
+    sizeBytes?: number;
+    receivedBytes?: number;
+    totalBytes?: number;
+    localPath?: string;
+    reason?: string;
+  }) => new BuniteEvent("download-event", data),
+  popupRequested: (data: {
+    newSurfaceId: number;
+    url: string;
+    disposition: "tab" | "window" | "popup";
+  }) => new BuniteEvent("popup-requested", data),
 };

package/src/host/log.ts

@@ -8,7 +8,12 @@ const levels: Record<LogLevel, number> = {
   silent: 4
 };
 
-let currentLevel: LogLevel = "warn";
+function initialLevel(): LogLevel {
+  const v = (typeof process !== "undefined" ? process.env?.BUNITE_LOG_LEVEL : undefined);
+  return v === "debug" || v === "info" || v === "warn" || v === "error" || v === "silent" ? v : "warn";
+}
+
+let currentLevel: LogLevel = initialLevel();
 
 function shouldLog(level: LogLevel): boolean {
   return levels[level] >= levels[currentLevel];

package/src/host/native.ts

@@ -102,6 +102,51 @@ type NativeSymbols = {
   bunite_view_reload: (viewId: number) => void;
   bunite_view_execute_javascript: (viewId: number, script: CStringPointer) => void;
   bunite_view_evaluate: (viewId: number, requestId: number, script: CStringPointer) => void;
+  bunite_view_click: (
+    viewId: number, x: number, y: number,
+    button: number, clickCount: number, modifiers: number
+  ) => void;
+  bunite_view_type: (viewId: number, text: CStringPointer) => void;
+  bunite_view_press: (
+    viewId: number, windowsVkCode: number, macKeyCode: number,
+    key: CStringPointer, code: CStringPointer, character: CStringPointer,
+    modifiers: number, action: number, extended: boolean, location: number
+  ) => void;
+  bunite_view_scroll: (
+    viewId: number, dx: number, dy: number,
+    x: number, y: number, modifiers: number
+  ) => void;
+  bunite_view_mouse: (
+    viewId: number, action: number, x: number, y: number,
+    button: number, modifiers: number
+  ) => void;
+  bunite_view_respond_dialog: (
+    viewId: number, requestId: number, accept: boolean, text: CStringPointer
+  ) => void;
+  bunite_view_screenshot: (
+    viewId: number, requestId: number, format: CStringPointer, quality: number
+  ) => void;
+  bunite_view_accessibility_snapshot: (
+    viewId: number, requestId: number, interestingOnly: number
+  ) => void;
+  bunite_view_list_frames: (viewId: number, requestId: number) => void;
+  bunite_view_evaluate_in_frame: (
+    viewId: number, requestId: number, script: CStringPointer, frameId: CStringPointer
+  ) => void;
+  bunite_view_resolve_and_click: (
+    viewId: number, requestId: number,
+    selector: CStringPointer, frameId: CStringPointer,
+    button: number, clickCount: number, modifiers: number
+  ) => void;
+  bunite_view_set_download_policy: (
+    viewId: number, policy: number, downloadDir: CStringPointer
+  ) => void;
+  bunite_view_popup_accept: (
+    newViewId: number, hostWindowId: number,
+    x: number, y: number, w: number, h: number,
+  ) => void;
+  bunite_view_popup_dismiss: (newViewId: number) => void;
+  bunite_view_capabilities: (viewId: number) => number;
   bunite_view_load_url: (viewId: number, url: CStringPointer) => void;
   bunite_view_load_html: (viewId: number, html: CStringPointer) => void;
   bunite_view_remove: (viewId: number) => void;
@@ -289,6 +334,66 @@ const nativeSymbolDefinitions = {
     args: [FFIType.u32, FFIType.u32, FFIType.cstring],
     returns: FFIType.void
   },
+  bunite_view_click: {
+    args: [FFIType.u32, FFIType.f64, FFIType.f64, FFIType.i32, FFIType.i32, FFIType.u32],
+    returns: FFIType.void
+  },
+  bunite_view_type: {
+    args: [FFIType.u32, FFIType.cstring],
+    returns: FFIType.void
+  },
+  bunite_view_press: {
+    args: [FFIType.u32, FFIType.i32, FFIType.i32, FFIType.cstring, FFIType.cstring, FFIType.cstring, FFIType.u32, FFIType.i32, FFIType.bool, FFIType.i32],
+    returns: FFIType.void
+  },
+  bunite_view_scroll: {
+    args: [FFIType.u32, FFIType.f64, FFIType.f64, FFIType.f64, FFIType.f64, FFIType.u32],
+    returns: FFIType.void
+  },
+  bunite_view_mouse: {
+    args: [FFIType.u32, FFIType.i32, FFIType.f64, FFIType.f64, FFIType.i32, FFIType.u32],
+    returns: FFIType.void
+  },
+  bunite_view_respond_dialog: {
+    args: [FFIType.u32, FFIType.u32, FFIType.bool, FFIType.cstring],
+    returns: FFIType.void
+  },
+  bunite_view_screenshot: {
+    args: [FFIType.u32, FFIType.u32, FFIType.cstring, FFIType.i32],
+    returns: FFIType.void
+  },
+  bunite_view_accessibility_snapshot: {
+    args: [FFIType.u32, FFIType.u32, FFIType.i32],
+    returns: FFIType.void
+  },
+  bunite_view_list_frames: {
+    args: [FFIType.u32, FFIType.u32],
+    returns: FFIType.void
+  },
+  bunite_view_evaluate_in_frame: {
+    args: [FFIType.u32, FFIType.u32, FFIType.cstring, FFIType.cstring],
+    returns: FFIType.void
+  },
+  bunite_view_resolve_and_click: {
+    args: [FFIType.u32, FFIType.u32, FFIType.cstring, FFIType.cstring, FFIType.i32, FFIType.i32, FFIType.u32],
+    returns: FFIType.void
+  },
+  bunite_view_set_download_policy: {
+    args: [FFIType.u32, FFIType.i32, FFIType.cstring],
+    returns: FFIType.void
+  },
+  bunite_view_popup_accept: {
+    args: [FFIType.u32, FFIType.u32, FFIType.f64, FFIType.f64, FFIType.f64, FFIType.f64],
+    returns: FFIType.void
+  },
+  bunite_view_popup_dismiss: {
+    args: [FFIType.u32],
+    returns: FFIType.void
+  },
+  bunite_view_capabilities: {
+    args: [FFIType.u32],
+    returns: FFIType.u32
+  },
   bunite_view_load_url: {
     args: [FFIType.u32, FFIType.cstring],
     returns: FFIType.void
@@ -350,6 +455,75 @@ export function setEvaluateResultHandler(handler: (viewId: number, result: Nativ
   evaluateResultHandler = handler;
 }
 
+export type NativeScreenshotResult = {
+  requestId: number;
+  ok: boolean;
+  format?: "png" | "jpeg";
+  mime?: string;
+  dataBase64?: string;
+  code?: string;
+  message?: string;
+};
+let screenshotResultHandler: ((viewId: number, result: NativeScreenshotResult) => void) | null = null;
+export function setScreenshotResultHandler(handler: (viewId: number, result: NativeScreenshotResult) => void) {
+  screenshotResultHandler = handler;
+}
+
+export type NativeAccessibilityResult = {
+  requestId: number;
+  ok: boolean;
+  tree?: unknown;       // CDP Accessibility.AXNode tree as JSON value
+  code?: string;
+  message?: string;
+};
+let accessibilityResultHandler: ((viewId: number, result: NativeAccessibilityResult) => void) | null = null;
+export function setAccessibilityResultHandler(handler: (viewId: number, result: NativeAccessibilityResult) => void) {
+  accessibilityResultHandler = handler;
+}
+
+export type NativeListFramesResult = {
+  requestId: number;
+  ok: boolean;
+  /** Raw CDP `Page.getFrameTree` result (`{frameTree: {frame, childFrames}}`). TS flattens. */
+  raw?: unknown;
+  code?: string;
+  message?: string;
+};
+let listFramesResultHandler: ((viewId: number, result: NativeListFramesResult) => void) | null = null;
+export function setListFramesResultHandler(handler: (viewId: number, result: NativeListFramesResult) => void) {
+  listFramesResultHandler = handler;
+}
+
+export type NativeResolveAndClickResult = {
+  requestId: number;
+  ok: boolean;
+  rect?: { x: number; y: number; width: number; height: number };
+  isTrustedEvent?: boolean;
+  code?: string;
+  message?: string;
+};
+let resolveAndClickResultHandler: ((viewId: number, result: NativeResolveAndClickResult) => void) | null = null;
+export function setResolveAndClickResultHandler(handler: (viewId: number, result: NativeResolveAndClickResult) => void) {
+  resolveAndClickResultHandler = handler;
+}
+
+export type NativeDownloadEvent = {
+  kind: "started" | "progress" | "completed" | "failed" | "blocked";
+  id: string;
+  url?: string;
+  suggestedFilename?: string;
+  mimeType?: string;
+  sizeBytes?: number;
+  receivedBytes?: number;
+  totalBytes?: number;
+  localPath?: string;
+  reason?: string;
+};
+let downloadEventHandler: ((viewId: number, event: NativeDownloadEvent) => void) | null = null;
+export function setDownloadEventHandler(handler: (viewId: number, event: NativeDownloadEvent) => void) {
+  downloadEventHandler = handler;
+}
+
 // Per-view deferred resolvers for "view-ready" (OnAfterCreated).
 const viewReadyResolvers = new Map<number, () => void>();
 
@@ -499,6 +673,47 @@ function registerNativeCallbacks(library: LoadedNativeLibrary) {
             evaluateResultHandler?.(viewId, parsed);
             break;
           }
+          case "screenshot-result": {
+            const parsed = maybeParsePayload(payload) as NativeScreenshotResult;
+            screenshotResultHandler?.(viewId, parsed);
+            break;
+          }
+          case "accessibility-result": {
+            const parsed = maybeParsePayload(payload) as NativeAccessibilityResult;
+            accessibilityResultHandler?.(viewId, parsed);
+            break;
+          }
+          case "list-frames-result": {
+            const parsed = maybeParsePayload(payload) as NativeListFramesResult;
+            listFramesResultHandler?.(viewId, parsed);
+            break;
+          }
+          case "resolve-and-click-result": {
+            const parsed = maybeParsePayload(payload) as NativeResolveAndClickResult;
+            resolveAndClickResultHandler?.(viewId, parsed);
+            break;
+          }
+          case "download-event": {
+            const parsed = maybeParsePayload(payload) as NativeDownloadEvent;
+            downloadEventHandler?.(viewId, parsed);
+            buniteEventEmitter.emitEvent(
+              buniteEventEmitter.events.webview.downloadEvent(parsed),
+              viewId
+            );
+            break;
+          }
+          case "popup-requested": {
+            const parsed = maybeParsePayload(payload) as {
+              newSurfaceId: number;
+              url: string;
+              disposition: "tab" | "window" | "popup";
+            };
+            buniteEventEmitter.emitEvent(
+              buniteEventEmitter.events.webview.popupRequested(parsed),
+              viewId
+            );
+            break;
+          }
           case "title-changed": {
             const parsed = maybeParsePayload(payload) as { title: string };
             buniteEventEmitter.emitEvent(
@@ -507,6 +722,53 @@ function registerNativeCallbacks(library: LoadedNativeLibrary) {
             );
             break;
           }
+          case "load-start":
+            buniteEventEmitter.emitEvent(
+              buniteEventEmitter.events.webview.loadStart({ detail: payload }),
+              viewId
+            );
+            break;
+          case "load-finish":
+            buniteEventEmitter.emitEvent(
+              buniteEventEmitter.events.webview.loadFinish({ detail: payload }),
+              viewId
+            );
+            break;
+          case "load-fail": {
+            const parsed = maybeParsePayload(payload) as { url?: string; reason?: string };
+            buniteEventEmitter.emitEvent(
+              buniteEventEmitter.events.webview.loadFail({
+                url: parsed.url ?? "", reason: parsed.reason,
+              }),
+              viewId
+            );
+            break;
+          }
+          case "dialog": {
+            const parsed = maybeParsePayload(payload) as {
+              requestId: number;
+              kind: "alert" | "confirm" | "prompt" | "beforeunload";
+              message: string;
+              defaultPrompt?: string;
+            };
+            buniteEventEmitter.emitEvent(
+              buniteEventEmitter.events.webview.dialog(parsed),
+              viewId
+            );
+            break;
+          }
+          case "console-message": {
+            const parsed = maybeParsePayload(payload) as {
+              level: "log" | "warn" | "error" | "info" | "debug";
+              args: string[];
+              ts: number;
+            };
+            buniteEventEmitter.emitEvent(
+              buniteEventEmitter.events.webview.consoleMessage(parsed),
+              viewId
+            );
+            break;
+          }
         }
       },
       {
@@ -656,7 +918,7 @@ export async function initNativeRuntime(
     throw new Error(`bunite: failed to load native library at ${artifacts.nativeLibPath}.`);
   }
 
-  const EXPECTED_ABI = 5;
+  const EXPECTED_ABI = 11;
   const nativeAbi = nativeLibrary.symbols.bunite_abi_version();
   if (nativeAbi !== EXPECTED_ABI) {
     throw new Error(

package/src/host/preloadBundle.ts

@@ -70,11 +70,16 @@ export function buildViewPreloadScript(options: {
 }) {
   const secretKeyBase64 = Buffer.from(options.secretKey).toString("base64");
 
-  // Per-view config — these globals are consumed by the pre-built runtime
+  // Per-view config — these globals are consumed by the pre-built runtime.
   const config = `var __buniteWebviewId=${options.webviewId},__buniteRpcSocketPort=${options.rpcSocketPort},__buniteSecretKeyBase64=${JSON.stringify(secretKeyBase64)};`;
 
   const runtime = getPreloadRuntime();
   const customPreload = readCustomPreload(options.preload, options.appresRoot).trim();
 
-  return [config, runtime, customPreload].filter(Boolean).join("\n");
+  // `;\n` between segments guards against ASI / token-boundary issues.
+  const inner = [config, runtime, customPreload].filter(Boolean).join(";\n");
+  // Catch top-level errors so a broken segment doesn't abort the surrounding
+  // native IIFE wrapper. Stashes the error on globalThis for programmatic
+  // inspection in addition to console.error.
+  return `try{${inner}\n}catch(e){try{globalThis.__bunitePreloadError=e}catch(_){}try{console.error("[bunite preload] failed:",e&&e.stack||e)}catch(_){}}`;
 }