refactor: Rename background-kref to kref-presence for clarity

- Rename background-kref.ts to kref-presence.ts
- Rename makeBackgroundKref to makePresenceManager
- Rename BackgroundKref type to PresenceManager
- Rename BackgroundKrefOptions to PresenceManagerOptions
- Update all imports and references across affected packages
- Update JSDoc comments to reflect new naming
- All tests pass for kernel-browser-runtime, extension, omnium-gatherum

Co-Authored-By: Claude <[email protected]>

Author: rekmarks

packages/extension/src/background.ts

@@ -1,7 +1,7 @@
 import { E } from '@endo/eventual-send';
 import {
   makeBackgroundCapTP,
-  makeBackgroundKref,
+  makePresenceManager,
   makeCapTPNotification,
   isCapTPNotification,
   getCapTPMessage,
@@ -117,9 +117,9 @@ async function main(): Promise<void> {
     logger.info(result);
   };
 
-  // Create background kref system for E() calls on vat objects
-  const bgKref = makeBackgroundKref({ kernelFacade: kernelP });
-  Object.assign(globalThis.captp, bgKref);
+  // Create presence manager for E() calls on vat objects
+  const presenceManager = makePresenceManager({ kernelFacade: kernelP });
+  Object.assign(globalThis.captp, presenceManager);
 
   // Handle incoming CapTP messages from the kernel
   const drainPromise = offscreenStream.drain((message) => {

packages/extension/src/global.d.ts

@@ -1,5 +1,5 @@
 import type {
-  BackgroundKref,
+  PresenceManager,
   KernelFacade,
 } from '@metamask/kernel-browser-runtime';
 
@@ -31,7 +31,7 @@ declare global {
    * ```
    */
   // eslint-disable-next-line no-var
-  var captp: BackgroundKref;
+  var captp: PresenceManager;
 }
 
 export {};

packages/kernel-browser-runtime/src/index.test.ts

@@ -13,9 +13,9 @@ describe('index', () => {
       'getRelaysFromCurrentLocation',
       'isCapTPNotification',
       'makeBackgroundCapTP',
-      'makeBackgroundKref',
       'makeCapTPNotification',
       'makeIframeVatWorker',
+      'makePresenceManager',
       'parseRelayQueryString',
       'receiveInternalConnections',
       'rpcHandlers',

packages/kernel-browser-runtime/src/index.ts

@@ -22,7 +22,7 @@ export {
   type CapTPMessage,
 } from './background-captp.ts';
 export {
-  makeBackgroundKref,
-  type BackgroundKref,
-  type BackgroundKrefOptions,
-} from './background-kref.ts';
+  makePresenceManager,
+  type PresenceManager,
+  type PresenceManagerOptions,
+} from './kref-presence.ts';

…l-browser-runtime/src/background-kref.ts …nel-browser-runtime/src/kref-presence.tspackages/kernel-browser-runtime/src/background-kref.ts renamed to packages/kernel-browser-runtime/src/kref-presence.ts packages/kernel-browser-runtime/src/background-kref.ts renamed to packages/kernel-browser-runtime/src/kref-presence.ts

@@ -1,5 +1,5 @@
 /**
- * Background kref system for creating E()-usable presences from kernel krefs.
+ * Presence manager for creating E()-usable presences from kernel krefs.
  *
  * This module provides "slot translation" - converting kernel krefs (ko*, kp*)
  * into presences that can receive eventual sends via E(). Method calls on these
@@ -24,9 +24,9 @@ type SendToKernelFn = (
 ) => Promise<unknown>;
 
 /**
- * Options for creating a background kref system.
+ * Options for creating a presence manager.
  */
-export type BackgroundKrefOptions = {
+export type PresenceManagerOptions = {
   /**
    * The kernel facade remote presence from CapTP.
    * Can be a promise since E() works with promises.
@@ -35,9 +35,9 @@ export type BackgroundKrefOptions = {
 };
 
 /**
- * The background kref system interface.
+ * The presence manager interface.
  */
-export type BackgroundKref = {
+export type PresenceManager = {
   /**
    * Resolve a kref string to an E()-usable presence.
    *
@@ -137,26 +137,26 @@ function makeKrefPresence(
 }
 
 /**
- * Create a background kref system for E() on vat objects.
+ * Create a presence manager for E() on vat objects.
  *
  * This creates presences from kernel krefs that forward method calls
  * to kernel.queueMessage() via the existing CapTP connection.
  *
  * @param options - Options including the kernel facade.
- * @returns The background kref system.
+ * @returns The presence manager.
  */
-export function makeBackgroundKref(
-  options: BackgroundKrefOptions,
-): BackgroundKref {
+export function makePresenceManager(
+  options: PresenceManagerOptions,
+): PresenceManager {
   const { kernelFacade } = options;
 
   // State for kref↔presence mapping
   const krefToPresence = new Map<KRef, object>();
   const presenceToKref = new WeakMap<object, KRef>();
 
-  // Forward declaration for sendToKernel (needs bgMarshal)
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any, prefer-const
-  let bgMarshal: any;
+  // Forward declaration for sendToKernel
+  // eslint-disable-next-line prefer-const
+  let marshal: ReturnType<typeof makeMarshal<string>>;
 
   /**
    * Send a message to the kernel and deserialize the result.
@@ -190,7 +190,7 @@ export function makeBackgroundKref(
     );
 
     // Deserialize result (krefs become presences)
-    return bgMarshal.fromCapData(result);
+    return marshal.fromCapData(result);
   };
 
   /**
@@ -232,9 +232,8 @@ export function makeBackgroundKref(
     throw new Error('Cannot serialize unknown remotable object');
   };
 
-  // Create marshal with smallcaps format (same as kernel)
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  bgMarshal = makeMarshal(convertValToSlot, convertSlotToVal as any, {
+  // Same options as kernel-marshal.ts
+  marshal = makeMarshal(convertValToSlot, convertSlotToVal, {
     serializeBodyFormat: 'smallcaps',
     errorTagging: 'off',
   });
@@ -249,8 +248,8 @@ export function makeBackgroundKref(
     },
 
     fromCapData: (data: CapData<KRef>): unknown => {
-      return bgMarshal.fromCapData(data);
+      return marshal.fromCapData(data);
     },
   });
 }
-harden(makeBackgroundKref);
+harden(makePresenceManager);

packages/omnium-gatherum/src/background.ts

@@ -1,7 +1,7 @@
 import { E } from '@endo/eventual-send';
 import {
   makeBackgroundCapTP,
-  makeBackgroundKref,
+  makePresenceManager,
   makeCapTPNotification,
   isCapTPNotification,
   getCapTPMessage,
@@ -125,8 +125,8 @@ async function main(): Promise<void> {
     return kernelP;
   };
 
-  // Create background kref system for E() on vat objects
-  const bgKref = makeBackgroundKref({ kernelFacade: kernelP });
+  // Create presence manager for E() on vat objects
+  const presenceManager = makePresenceManager({ kernelFacade: kernelP });
 
   // Create storage adapter
   const storageAdapter = makeChromeStorageAdapter();
@@ -214,10 +214,10 @@ async function main(): Promise<void> {
       }),
     },
     resolveKref: {
-      value: bgKref.resolveKref,
+      value: presenceManager.resolveKref,
     },
     krefOf: {
-      value: bgKref.krefOf,
+      value: presenceManager.krefOf,
     },
   });
   harden(globalThis.omnium);