bunite-core 0.0.1 → 0.0.4

package/src/bun/core/BrowserWindow.ts

@@ -1,11 +1,11 @@
-import type { Pointer } from "bun:ffi";
+import { dirname, isAbsolute, relative, resolve, sep } from "node:path";
 import { BuniteEvent } from "../events/event";
 import { buniteEventEmitter } from "../events/eventEmitter";
 import { ensureNativeRuntime, getNativeLibrary, toCString } from "../proc/native";
 import { BrowserView, type BrowserViewOptions } from "./BrowserView";
 import type { RPCWithTransport } from "../../shared/rpc";
 import { getNextWindowId } from "./windowIds";
-import { resolveDefaultViewsRoot } from "../../shared/paths";
+import { getBaseDir, resolveDefaultAppResRoot } from "../../shared/paths";
 
 export type WindowOptionsType<T = undefined> = {
   title: string;
@@ -20,7 +20,8 @@ export type WindowOptionsType<T = undefined> = {
   url: string | null;
   html: string | null;
   preload: string | null;
-  viewsRoot: string | null;
+  appresRoot: string | null;
+  preloadOrigins?: string[];
   rpc?: T;
   titleBarStyle: "hidden" | "hiddenInset" | "default";
   transparent: boolean;
@@ -40,7 +41,8 @@ const defaultOptions: WindowOptionsType = {
   url: null,
   html: null,
   preload: null,
-  viewsRoot: null,
+  appresRoot: null,
+  preloadOrigins: undefined,
   titleBarStyle: "default",
   transparent: false,
   hidden: false,
@@ -50,15 +52,22 @@ const defaultOptions: WindowOptionsType = {
 
 const BrowserWindowMap: Record<number, BrowserWindow<any>> = {};
 
+let lastFocusedWindowId: number | null = null;
+
+export function getLastFocusedWindowId(): number | null {
+  return lastFocusedWindowId;
+}
+
 export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
   id = getNextWindowId();
-  ptr: Pointer | null = null;
+  private nativeAttached = false;
   title: string;
   frame: WindowOptionsType["frame"];
   url: string | null;
   html: string | null;
   preload: string | null;
-  viewsRoot: string | null;
+  appresRoot: string | null;
+  preloadOrigins?: string[];
   titleBarStyle: WindowOptionsType["titleBarStyle"];
   transparent: boolean;
   hidden: boolean;
@@ -106,12 +115,16 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
       return;
     }
     this.closed = true;
-    this.ptr = null;
+    this.nativeAttached = false;
+    if (lastFocusedWindowId === this.id) {
+      lastFocusedWindowId = null;
+    }
     BrowserView.getById(this.webviewId)?.detachFromNative();
     delete BrowserWindowMap[this.id];
     buniteEventEmitter.off(`move-${this.id}`, this.handleNativeMove);
     buniteEventEmitter.off(`resize-${this.id}`, this.handleNativeResize);
     buniteEventEmitter.off(`close-${this.id}`, this.handleNativeClose);
+    buniteEventEmitter.removeAllListeners(`close-requested-${this.id}`);
   };
 
   constructor(options: Partial<WindowOptionsType<T>> = {}) {
@@ -119,10 +132,27 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
 
     this.title = options.title ?? defaultOptions.title;
     this.frame = { ...defaultOptions.frame, ...options.frame };
-    this.url = options.url ?? defaultOptions.url;
     this.html = options.html ?? defaultOptions.html;
     this.preload = options.preload ?? defaultOptions.preload;
-    this.viewsRoot = options.viewsRoot ?? defaultOptions.viewsRoot ?? resolveDefaultViewsRoot();
+    this.preloadOrigins = options.preloadOrigins ?? defaultOptions.preloadOrigins;
+
+    const baseDir = getBaseDir();
+
+    let url = options.url ?? defaultOptions.url;
+    let appresRoot = options.appresRoot ?? defaultOptions.appresRoot;
+    if (appresRoot && !isAbsolute(appresRoot)) {
+      appresRoot = resolve(baseDir, appresRoot);
+    }
+    if (url && !url.includes("://")) {
+      const resolved = isAbsolute(url) ? url : resolve(baseDir, url);
+      if (!appresRoot) {
+        appresRoot = dirname(resolved);
+      }
+      const rel = relative(appresRoot!, resolved).replaceAll(sep, "/");
+      url = `appres://app.internal/${rel}`;
+    }
+    this.url = url;
+    this.appresRoot = appresRoot ?? resolveDefaultAppResRoot();
     this.titleBarStyle = options.titleBarStyle ?? defaultOptions.titleBarStyle;
     this.transparent = options.transparent ?? defaultOptions.transparent;
     this.hidden = options.hidden ?? defaultOptions.hidden!;
@@ -130,7 +160,7 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
     this.sandbox = options.sandbox ?? defaultOptions.sandbox;
 
     const native = getNativeLibrary();
-    this.ptr =
+    this.nativeAttached =
       native?.symbols.bunite_window_create(
         this.id,
         this.frame.x,
@@ -143,9 +173,10 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
         this.hidden,
         Boolean(this.frame.minimized),
         Boolean(this.frame.maximized)
-      ) ?? null;
+      ) ?? false;
 
     BrowserWindowMap[this.id] = this;
+    buniteEventEmitter.on(`focus-${this.id}`, () => { lastFocusedWindowId = this.id; });
     buniteEventEmitter.on(`move-${this.id}`, this.handleNativeMove);
     buniteEventEmitter.on(`resize-${this.id}`, this.handleNativeResize);
     buniteEventEmitter.on(`close-${this.id}`, this.handleNativeClose);
@@ -154,8 +185,8 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
       url: this.url,
       html: this.html,
       preload: this.preload,
-      viewsRoot: this.viewsRoot,
-      windowPtr: this.ptr,
+      appresRoot: this.appresRoot,
+      preloadOrigins: this.preloadOrigins,
       frame: {
         x: 0,
         y: 0,
@@ -175,14 +206,18 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
     return BrowserWindowMap[id];
   }
 
+  static getAll() {
+    return Object.values(BrowserWindowMap);
+  }
+
   get webview() {
     return BrowserView.getById(this.webviewId) as BrowserView<T>;
   }
 
   show() {
     this.hidden = false;
-    if (this.ptr) {
-      getNativeLibrary()?.symbols.bunite_window_show(this.ptr);
+    if (this.nativeAttached) {
+      getNativeLibrary()?.symbols.bunite_window_show(this.id);
     }
   }
 
@@ -190,25 +225,37 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
     if (this.closed) {
       return;
     }
-    this.closed = true;
-    const hadNativePtr = Boolean(this.ptr);
-    if (this.ptr) {
-      getNativeLibrary()?.symbols.bunite_window_close(this.ptr);
-      this.ptr = null;
+    if (this.nativeAttached) {
+      // Triggers WM_CLOSE → "close-requested" event → vetoable
+      getNativeLibrary()?.symbols.bunite_window_close(this.id);
     } else {
-      BrowserView.getById(this.webviewId)?.remove();
+      this.destroy();
+    }
+  }
+
+  destroy() {
+    if (this.closed) {
+      return;
+    }
+    this.closed = true;
+    BrowserView.getById(this.webviewId)?.detachFromNative();
+    const hadNative = this.nativeAttached;
+    if (this.nativeAttached) {
+      getNativeLibrary()?.symbols.bunite_window_destroy(this.id);
+      this.nativeAttached = false;
     }
     delete BrowserWindowMap[this.id];
     buniteEventEmitter.off(`move-${this.id}`, this.handleNativeMove);
     buniteEventEmitter.off(`resize-${this.id}`, this.handleNativeResize);
     buniteEventEmitter.off(`close-${this.id}`, this.handleNativeClose);
-    if (!hadNativePtr) {
+    buniteEventEmitter.removeAllListeners(`close-requested-${this.id}`);
+    if (!hadNative) {
       buniteEventEmitter.emitEvent(buniteEventEmitter.events.window.close({ id: this.id }), this.id);
     }
   }
 
   maximize() {
-    if (!this.ptr) {
+    if (!this.nativeAttached) {
       this.frame.maximized = true;
       this.frame.minimized = false;
       return;
@@ -219,13 +266,13 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
       return;
     }
 
-    native.symbols.bunite_window_maximize(this.ptr);
-    this.frame.minimized = native.symbols.bunite_window_is_minimized(this.ptr);
-    this.frame.maximized = native.symbols.bunite_window_is_maximized(this.ptr);
+    native.symbols.bunite_window_maximize(this.id);
+    this.frame.minimized = native.symbols.bunite_window_is_minimized(this.id);
+    this.frame.maximized = native.symbols.bunite_window_is_maximized(this.id);
   }
 
   unmaximize() {
-    if (!this.ptr) {
+    if (!this.nativeAttached) {
       this.frame.maximized = false;
       return;
     }
@@ -235,23 +282,23 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
       return;
     }
 
-    native.symbols.bunite_window_unmaximize(this.ptr);
-    this.frame.minimized = native.symbols.bunite_window_is_minimized(this.ptr);
-    this.frame.maximized = native.symbols.bunite_window_is_maximized(this.ptr);
+    native.symbols.bunite_window_unmaximize(this.id);
+    this.frame.minimized = native.symbols.bunite_window_is_minimized(this.id);
+    this.frame.maximized = native.symbols.bunite_window_is_maximized(this.id);
   }
 
   isMaximized() {
-    if (!this.ptr) {
+    if (!this.nativeAttached) {
       return Boolean(this.frame.maximized);
     }
 
-    const maximized = getNativeLibrary()?.symbols.bunite_window_is_maximized(this.ptr) ?? false;
+    const maximized = getNativeLibrary()?.symbols.bunite_window_is_maximized(this.id) ?? false;
     this.frame.maximized = maximized;
     return maximized;
   }
 
   minimize() {
-    if (!this.ptr) {
+    if (!this.nativeAttached) {
       this.restoreMaximizedAfterMinimize = Boolean(this.frame.maximized);
       this.frame.minimized = true;
       this.frame.maximized = false;
@@ -263,13 +310,13 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
       return;
     }
 
-    native.symbols.bunite_window_minimize(this.ptr);
-    this.frame.minimized = native.symbols.bunite_window_is_minimized(this.ptr);
-    this.frame.maximized = native.symbols.bunite_window_is_maximized(this.ptr);
+    native.symbols.bunite_window_minimize(this.id);
+    this.frame.minimized = native.symbols.bunite_window_is_minimized(this.id);
+    this.frame.maximized = native.symbols.bunite_window_is_maximized(this.id);
   }
 
   unminimize() {
-    if (!this.ptr) {
+    if (!this.nativeAttached) {
       this.frame.minimized = false;
       this.frame.maximized = this.restoreMaximizedAfterMinimize;
       this.restoreMaximizedAfterMinimize = false;
@@ -281,32 +328,32 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
       return;
     }
 
-    native.symbols.bunite_window_unminimize(this.ptr);
-    this.frame.minimized = native.symbols.bunite_window_is_minimized(this.ptr);
-    this.frame.maximized = native.symbols.bunite_window_is_maximized(this.ptr);
+    native.symbols.bunite_window_unminimize(this.id);
+    this.frame.minimized = native.symbols.bunite_window_is_minimized(this.id);
+    this.frame.maximized = native.symbols.bunite_window_is_maximized(this.id);
   }
 
   isMinimized() {
-    if (!this.ptr) {
+    if (!this.nativeAttached) {
       return Boolean(this.frame.minimized);
     }
 
-    const minimized = getNativeLibrary()?.symbols.bunite_window_is_minimized(this.ptr) ?? false;
+    const minimized = getNativeLibrary()?.symbols.bunite_window_is_minimized(this.id) ?? false;
     this.frame.minimized = minimized;
     return minimized;
   }
 
   setTitle(title: string) {
     this.title = title;
-    if (this.ptr) {
-      getNativeLibrary()?.symbols.bunite_window_set_title(this.ptr, toCString(title));
+    if (this.nativeAttached) {
+      getNativeLibrary()?.symbols.bunite_window_set_title(this.id, toCString(title));
     }
   }
 
   setFrame(x: number, y: number, width: number, height: number) {
     this.frame = { ...this.frame, x, y, width, height };
-    if (this.ptr) {
-      getNativeLibrary()?.symbols.bunite_window_set_frame(this.ptr, x, y, width, height);
+    if (this.nativeAttached) {
+      getNativeLibrary()?.symbols.bunite_window_set_frame(this.id, x, y, width, height);
     }
   }
 
@@ -314,7 +361,7 @@ export class BrowserWindow<T extends RPCWithTransport = RPCWithTransport> {
     return this.frame;
   }
 
-  on(name: "close" | "focus" | "blur" | "move" | "resize", handler: (event: unknown) => void) {
+  on(name: "close-requested" | "close" | "focus" | "blur" | "move" | "resize", handler: (event: unknown) => void) {
     const specificName = `${name}-${this.id}`;
     buniteEventEmitter.on(specificName, handler);
     return () => buniteEventEmitter.off(specificName, handler);

package/src/bun/core/Socket.ts

@@ -3,6 +3,7 @@ import type { BrowserView } from "./BrowserView";
 import { createCipheriv, createDecipheriv, randomBytes } from "node:crypto";
 import type { RPCPacket, RPCRequestPacket } from "../../shared/rpc";
 import type { GlobalIPCHandler } from "./App";
+import { log } from "../../shared/log";
 import {
   asUint8Array,
   createEncryptedRPCFrame,
@@ -114,7 +115,7 @@ export function ensureRPCServer() {
 
               view.handleIncomingRPC(packet);
             } catch (error) {
-              console.error("[bunite] Failed to parse RPC payload", error);
+              log.error("Failed to parse RPC payload", error);
             }
           }
         }

package/src/bun/core/SurfaceBrowserIPC.ts

@@ -0,0 +1,65 @@
+import { getOwnedSurface } from "./SurfaceRegistry";
+import { sendMessageToView } from "./Socket";
+import { onSurfaceInit } from "./SurfaceManager";
+
+import type { GlobalIPCHandler } from "./App";
+
+// --- did-navigate forwarding ---
+
+onSurfaceInit((surfaceId, hostViewId, view) => {
+  view.on("did-navigate", (event: any) => {
+    sendMessageToView(hostViewId, {
+      type: "event",
+      channel: "__bunite:webview.didNavigate",
+      data: { surfaceId, url: event.data.detail }
+    });
+  });
+});
+
+// --- Helpers ---
+
+function assertNum(v: unknown, label: string): number {
+  if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`Invalid ${label}`);
+  return v;
+}
+
+function assertStr(v: unknown, label: string): string {
+  if (typeof v !== "string") throw new Error(`Invalid ${label}`);
+  return v;
+}
+
+function assertObj(v: unknown, label: string): Record<string, unknown> {
+  if (!v || typeof v !== "object") throw new Error(`Invalid ${label}`);
+  return v as Record<string, unknown>;
+}
+
+// --- Handlers ---
+
+const handleGoBack: GlobalIPCHandler = async (params, ctx) => {
+  const record = getOwnedSurface(assertNum(assertObj(params, "p").surfaceId, "surfaceId"), ctx);
+  if (record) record.view.goBack();
+  return {};
+};
+
+const handleReload: GlobalIPCHandler = async (params, ctx) => {
+  const record = getOwnedSurface(assertNum(assertObj(params, "p").surfaceId, "surfaceId"), ctx);
+  if (record) record.view.reload();
+  return {};
+};
+
+const handleNavigate: GlobalIPCHandler = async (params, ctx) => {
+  const p = assertObj(params, "webview.navigate params");
+  const surfaceId = assertNum(p.surfaceId, "surfaceId");
+  const url = assertStr(p.url, "url");
+  const record = getOwnedSurface(surfaceId, ctx);
+  if (record) record.view.loadURL(url);
+  return {};
+};
+
+export function getWebviewIPCHandlers(): Map<string, GlobalIPCHandler> {
+  return new Map([
+    ["__bunite:webview.goBack", handleGoBack],
+    ["__bunite:webview.reload", handleReload],
+    ["__bunite:webview.navigate", handleNavigate]
+  ]);
+}

package/src/bun/core/SurfaceManager.ts

@@ -0,0 +1,201 @@
+import { BrowserView } from "./BrowserView";
+import {
+  trackSurface, untrackSurface, getOwnedSurface,
+  getHostSurfaceIds, getSurfaceRecord,
+  MAX_SURFACES_PER_HOST
+} from "./SurfaceRegistry";
+
+import type { GlobalIPCHandler } from "./App";
+
+// --- Helpers ---
+
+function applyHostOffset(hostView: BrowserView, x: number, y: number) {
+  return { x: x + hostView.frame.x, y: y + hostView.frame.y };
+}
+
+function assertNum(v: unknown, label: string): number {
+  if (typeof v !== "number" || !Number.isFinite(v)) throw new Error(`Invalid ${label}`);
+  return v;
+}
+
+function assertBool(v: unknown, label: string): boolean {
+  if (typeof v !== "boolean") throw new Error(`Invalid ${label}`);
+  return v;
+}
+
+function assertStr(v: unknown, label: string): string {
+  if (typeof v !== "string") throw new Error(`Invalid ${label}`);
+  return v;
+}
+
+function assertObj(v: unknown, label: string): Record<string, unknown> {
+  if (!v || typeof v !== "object") throw new Error(`Invalid ${label}`);
+  return v as Record<string, unknown>;
+}
+
+// --- Surface lifecycle callbacks (called by SurfaceBrowserIPC after init) ---
+
+type SurfaceInitCallback = (surfaceId: number, hostViewId: number, view: BrowserView) => void;
+const initCallbacks: SurfaceInitCallback[] = [];
+
+export function onSurfaceInit(cb: SurfaceInitCallback) {
+  initCallbacks.push(cb);
+}
+
+// --- Handlers ---
+
+const handleSurfaceInit: GlobalIPCHandler = async (params, ctx) => {
+  const p = assertObj(params, "surface.init params");
+  const src = assertStr(p.src, "src");
+  const x = assertNum(p.x, "x");
+  const y = assertNum(p.y, "y");
+  const width = assertNum(p.width, "width");
+  const height = assertNum(p.height, "height");
+  const hidden = typeof p.hidden === "boolean" ? p.hidden : false;
+
+  const hostView = BrowserView.getById(ctx.viewId);
+  if (!hostView) throw new Error(`Host view not found: ${ctx.viewId}`);
+  if (!hostView.windowId) throw new Error(`Host window not found for view: ${ctx.viewId}`);
+
+  const hostIds = getHostSurfaceIds(ctx.viewId);
+  if (hostIds && hostIds.size >= MAX_SURFACES_PER_HOST) {
+    throw new Error(`Surface limit reached (${MAX_SURFACES_PER_HOST}) for host view ${ctx.viewId}`);
+  }
+
+  const offset = applyHostOffset(hostView, x, y);
+  const view = new BrowserView({
+    url: src,
+    windowId: hostView.windowId,
+    appresRoot: hostView.appresRoot,
+    frame: { x: offset.x, y: offset.y, width, height },
+    autoResize: false
+  });
+  trackSurface(view.id, { view, hostViewId: ctx.viewId, hidden });
+  try {
+    await view.whenReady();
+  } catch {
+    untrackSurface(view.id);
+    view.remove();
+    throw new Error("Surface browser creation failed or timed out");
+  }
+
+  for (const cb of initCallbacks) cb(view.id, ctx.viewId, view);
+
+  if (hidden) {
+    view.setVisible(false);
+  } else {
+    view.bringToFront();
+  }
+  return { surfaceId: view.id };
+};
+
+const handleSurfaceResize: GlobalIPCHandler = async (params, ctx) => {
+  const p = assertObj(params, "surface.resize params");
+  const surfaceId = assertNum(p.surfaceId, "surfaceId");
+  const x = assertNum(p.x, "x");
+  const y = assertNum(p.y, "y");
+  const w = assertNum(p.w, "w");
+  const h = assertNum(p.h, "h");
+
+  const record = getOwnedSurface(surfaceId, ctx);
+  if (!record) return {};
+
+  const hostView = BrowserView.getById(ctx.viewId);
+  if (hostView) {
+    const offset = applyHostOffset(hostView, x, y);
+    record.view.setBoundsAsync(offset.x, offset.y, w, h);
+  }
+  return {};
+};
+
+const handleSurfaceRemove: GlobalIPCHandler = async (params, ctx) => {
+  const p = assertObj(params, "surface.remove params");
+  const surfaceId = assertNum(p.surfaceId, "surfaceId");
+
+  const record = getOwnedSurface(surfaceId, ctx);
+  if (!record) return {};
+
+  untrackSurface(surfaceId);
+  record.view.remove();
+  return {};
+};
+
+const handleSurfaceSetHidden: GlobalIPCHandler = async (params, ctx) => {
+  const p = assertObj(params, "surface.setHidden params");
+  const surfaceId = assertNum(p.surfaceId, "surfaceId");
+  const hidden = assertBool(p.hidden, "hidden");
+
+  const record = getOwnedSurface(surfaceId, ctx);
+  if (!record) return {};
+
+  record.hidden = hidden;
+  record.view.setVisible(!hidden);
+  if (!hidden) {
+    record.view.bringToFront();
+  }
+  return {};
+};
+
+const handleSurfaceSetMasks: GlobalIPCHandler = async (params, ctx) => {
+  const p = assertObj(params, "surface.setMasks params");
+  const surfaceId = assertNum(p.surfaceId, "surfaceId");
+  const masksRaw = Array.isArray(p.masks) ? p.masks : [];
+
+  const record = getOwnedSurface(surfaceId, ctx);
+  if (!record) return {};
+
+  const hostView = BrowserView.getById(ctx.viewId);
+  if (!hostView) return {};
+
+  const offset = applyHostOffset(hostView, 0, 0);
+  const rects = masksRaw.map((r: any) => ({
+    x: assertNum(r.x, "mask.x") + offset.x,
+    y: assertNum(r.y, "mask.y") + offset.y,
+    w: assertNum(r.w, "mask.w"),
+    h: assertNum(r.h, "mask.h")
+  }));
+
+  record.view.setMaskRegion(rects);
+  return {};
+};
+
+const handleSurfaceSetAllPassthrough: GlobalIPCHandler = async (params, ctx) => {
+  const p = assertObj(params, "surface.setAllPassthrough params");
+  const passthrough = assertBool(p.passthrough, "passthrough");
+
+  const ids = getHostSurfaceIds(ctx.viewId);
+  if (!ids) return {};
+
+  for (const surfaceId of ids) {
+    const record = getSurfaceRecord(surfaceId);
+    if (record) {
+      record.view.setInputPassthrough(passthrough);
+    }
+  }
+  return {};
+};
+
+const handleSurfaceBringAllVisiblesToFront: GlobalIPCHandler = async (_params, ctx) => {
+  const ids = getHostSurfaceIds(ctx.viewId);
+  if (!ids) return {};
+
+  for (const surfaceId of ids) {
+    const record = getSurfaceRecord(surfaceId);
+    if (record && !record.hidden) {
+      record.view.bringToFront();
+    }
+  }
+  return {};
+};
+
+export function getSurfaceIPCHandlers(): Map<string, GlobalIPCHandler> {
+  return new Map([
+    ["__bunite:surface.init", handleSurfaceInit],
+    ["__bunite:surface.resize", handleSurfaceResize],
+    ["__bunite:surface.remove", handleSurfaceRemove],
+    ["__bunite:surface.setHidden", handleSurfaceSetHidden],
+    ["__bunite:surface.setMasks", handleSurfaceSetMasks],
+    ["__bunite:surface.setAllPassthrough", handleSurfaceSetAllPassthrough],
+    ["__bunite:surface.bringAllVisiblesToFront", handleSurfaceBringAllVisiblesToFront]
+  ]);
+}

package/src/bun/core/SurfaceRegistry.ts

@@ -0,0 +1,60 @@
+import type { BrowserView } from "./BrowserView";
+
+export type SurfaceRecord = {
+  view: BrowserView;
+  hostViewId: number;
+  hidden: boolean;
+};
+
+export const MAX_SURFACES_PER_HOST = 32;
+
+const surfaces = new Map<number, SurfaceRecord>();
+const hostSurfaceIds = new Map<number, Set<number>>();
+
+export function trackSurface(surfaceId: number, record: SurfaceRecord) {
+  surfaces.set(surfaceId, record);
+  let ids = hostSurfaceIds.get(record.hostViewId);
+  if (!ids) {
+    ids = new Set();
+    hostSurfaceIds.set(record.hostViewId, ids);
+  }
+  ids.add(surfaceId);
+}
+
+export function untrackSurface(surfaceId: number) {
+  const record = surfaces.get(surfaceId);
+  if (!record) return;
+  surfaces.delete(surfaceId);
+  const ids = hostSurfaceIds.get(record.hostViewId);
+  if (ids) {
+    ids.delete(surfaceId);
+    if (ids.size === 0) hostSurfaceIds.delete(record.hostViewId);
+  }
+}
+
+export function getOwnedSurface(surfaceId: number, ctx: { viewId: number }): SurfaceRecord | null {
+  const record = surfaces.get(surfaceId);
+  if (!record) return null;
+  if (record.hostViewId !== ctx.viewId) throw new Error("Surface access denied.");
+  return record;
+}
+
+export function getHostSurfaceIds(hostViewId: number): Set<number> | undefined {
+  return hostSurfaceIds.get(hostViewId);
+}
+
+export function getSurfaceRecord(surfaceId: number): SurfaceRecord | undefined {
+  return surfaces.get(surfaceId);
+}
+
+export function removeSurfacesForHostView(hostViewId: number) {
+  const ids = hostSurfaceIds.get(hostViewId);
+  if (!ids || ids.size === 0) return;
+
+  for (const surfaceId of Array.from(ids)) {
+    const record = surfaces.get(surfaceId);
+    if (!record) continue;
+    untrackSurface(surfaceId);
+    record.view.remove();
+  }
+}