From 8b39384c267e17d1e36101bd547cd4c95c34147a Mon Sep 17 00:00:00 2001
From: Erik Marks <rekmarks@protonmail.com>
Date: Mon, 29 Jul 2024 13:49:54 +0200
Subject: [PATCH 1/9] feat: Add streams package

---
 constraints.pro                               |  12 +-
 packages/extension/package.json               |   1 +
 packages/extension/src/iframe-manager.test.ts | 193 +++++++++-------
 packages/extension/src/iframe-manager.ts      | 161 ++++++-------
 packages/extension/src/iframe.ts              | 164 ++++++-------
 packages/extension/src/offscreen.ts           | 125 +++++-----
 packages/extension/src/shared.test.ts         |   4 +-
 packages/extension/src/shared.ts              |   8 +-
 packages/extension/tsconfig.build.json        |   5 +-
 packages/extension/tsconfig.json              |   4 +-
 packages/streams/CHANGELOG.md                 |  10 +
 packages/streams/README.md                    |   7 +
 packages/streams/package.json                 |  68 ++++++
 packages/streams/src/index.test.ts            |  16 ++
 packages/streams/src/index.ts                 |   5 +
 packages/streams/src/message-channel.test.ts  | 216 ++++++++++++++++++
 packages/streams/src/message-channel.ts       | 104 +++++++++
 packages/streams/src/streams.test.ts          | 166 ++++++++++++++
 packages/streams/src/streams.ts               | 182 +++++++++++++++
 packages/streams/tsconfig.build.json          |  12 +
 packages/streams/tsconfig.json                |  10 +
 packages/streams/typedoc.json                 |   7 +
 packages/streams/vitest.config.ts             |  17 ++
 tsconfig.build.json                           |   3 +-
 tsconfig.json                                 |   1 +
 yarn.lock                                     |  81 ++++++-
 26 files changed, 1272 insertions(+), 310 deletions(-)
 create mode 100644 packages/streams/CHANGELOG.md
 create mode 100644 packages/streams/README.md
 create mode 100644 packages/streams/package.json
 create mode 100644 packages/streams/src/index.test.ts
 create mode 100644 packages/streams/src/index.ts
 create mode 100644 packages/streams/src/message-channel.test.ts
 create mode 100644 packages/streams/src/message-channel.ts
 create mode 100644 packages/streams/src/streams.test.ts
 create mode 100644 packages/streams/src/streams.ts
 create mode 100644 packages/streams/tsconfig.build.json
 create mode 100644 packages/streams/tsconfig.json
 create mode 100644 packages/streams/typedoc.json
 create mode 100644 packages/streams/vitest.config.ts

diff --git a/constraints.pro b/constraints.pro
index 64f16b016..bfe1280c9 100644
--- a/constraints.pro
+++ b/constraints.pro
@@ -208,10 +208,12 @@ gen_enforced_field(WorkspaceCwd, 'module', './dist/index.mjs') :-
   \+ workspace_field(WorkspaceCwd, 'private', true).
 % Non-published packages must not specify an entrypoint.
 gen_enforced_field(WorkspaceCwd, 'main', null) :-
-  WorkspaceCwd \= 'packages/shims'.
+  WorkspaceCwd \= 'packages/shims',
+  WorkspaceCwd \= 'packages/streams',
   workspace_field(WorkspaceCwd, 'private', true).
 gen_enforced_field(WorkspaceCwd, 'module', null) :-
-  WorkspaceCwd \= 'packages/shims'.
+  WorkspaceCwd \= 'packages/shims',
+  WorkspaceCwd \= 'packages/streams',
   workspace_field(WorkspaceCwd, 'private', true).
 
 % The type definitions entrypoint for all publishable packages must be the same.
@@ -219,7 +221,8 @@ gen_enforced_field(WorkspaceCwd, 'types', './dist/index.d.cts') :-
   \+ workspace_field(WorkspaceCwd, 'private', true).
 % Non-published packages must not specify a type definitions entrypoint.
 gen_enforced_field(WorkspaceCwd, 'types', null) :-
-  WorkspaceCwd \= 'packages/shims'.
+  WorkspaceCwd \= 'packages/shims',
+  WorkspaceCwd \= 'packages/streams',
   workspace_field(WorkspaceCwd, 'private', true).
 
 % The exports for all published packages must be the same.
@@ -246,7 +249,8 @@ gen_enforced_field(WorkspaceCwd, 'sideEffects', false) :-
   \+ workspace_field(WorkspaceCwd, 'private', true).
 % Non-published packages must not specify side effects.
 gen_enforced_field(WorkspaceCwd, 'sideEffects', null) :-
-  WorkspaceCwd \= 'packages/shims'.
+  WorkspaceCwd \= 'packages/shims',
+  WorkspaceCwd \= 'packages/streams',
   workspace_field(WorkspaceCwd, 'private', true).
 
 % The list of files included in published packages must only include files
diff --git a/packages/extension/package.json b/packages/extension/package.json
index 192af388f..b3cce458e 100644
--- a/packages/extension/package.json
+++ b/packages/extension/package.json
@@ -31,6 +31,7 @@
     "@metamask/snaps-utils": "^7.8.0",
     "@metamask/utils": "^9.1.0",
     "@ocap/shims": "workspace:^",
+    "@ocap/streams": "workspace:^",
     "ses": "^1.7.0"
   },
   "devDependencies": {
diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index c2a00c5e5..3413b8177 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -1,54 +1,22 @@
 import type { makePromiseKit } from '@endo/promise-kit';
 import * as snapsUtils from '@metamask/snaps-utils';
-import { vi, beforeEach, describe, it, expect } from 'vitest';
+import { delay, makePromiseKitMock } from '@ocap/test-utils';
+import { vi, describe, it, expect } from 'vitest';
 
+import { IframeManager } from './iframe-manager.js';
 import { Command } from './shared.js';
 
-vi.mock('@endo/promise-kit', () => ({
-  makePromiseKit: (): ReturnType<typeof makePromiseKit> => {
-    let resolve: (value: unknown) => void, reject: (reason?: unknown) => void;
-    const promise = new Promise((_resolve, _reject) => {
-      resolve = _resolve;
-      reject = _reject;
-    });
-    // @ts-expect-error We have in fact assigned resolve and reject.
-    return { promise, resolve, reject };
-  },
-}));
+vi.mock('@endo/promise-kit', () => makePromiseKitMock());
 
 vi.mock('@metamask/snaps-utils', () => ({
   createWindow: vi.fn(),
 }));
 
 describe('IframeManager', () => {
-  // eslint-disable-next-line @typescript-eslint/consistent-type-imports
-  let IframeManager: typeof import('./iframe-manager.js').IframeManager;
-
-  beforeEach(async () => {
-    vi.resetModules();
-    IframeManager = (await import('./iframe-manager.js')).IframeManager;
-  });
-
-  describe('getInstance', () => {
-    it('is a singleton', () => {
-      expect(IframeManager.getInstance()).toBe(IframeManager.getInstance());
-    });
-
-    it('sets up event listener on construction', () => {
-      const addEventListenerSpy = vi.spyOn(window, 'addEventListener');
-      let manager = IframeManager.getInstance();
-
-      expect(manager).toBeInstanceOf(IframeManager);
-      expect(addEventListenerSpy).toHaveBeenCalledOnce();
-      expect(addEventListenerSpy).toHaveBeenCalledWith(
-        'message',
-        expect.any(Function),
-      );
-
-      manager = IframeManager.getInstance();
-      expect(addEventListenerSpy).toHaveBeenCalledOnce();
-    });
-  });
+  const makeGetPort =
+    (port: MessagePort = new MessageChannel().port1) =>
+    async (_window: Window) =>
+      Promise.resolve(port);
 
   describe('create', () => {
     it('creates a new iframe', async () => {
@@ -56,12 +24,11 @@ describe('IframeManager', () => {
       vi.mocked(snapsUtils.createWindow).mockResolvedValueOnce(
         mockWindow as Window,
       );
-
-      const manager = IframeManager.getInstance();
+      const manager = new IframeManager();
       const sendMessageSpy = vi
         .spyOn(manager, 'sendMessage')
         .mockImplementation(vi.fn());
-      const [newWindow, id] = await manager.create();
+      const [newWindow, id] = await manager.create({ getPort: makeGetPort() });
 
       expect(newWindow).toBe(mockWindow);
       expect(id).toBeTypeOf('string');
@@ -78,12 +45,15 @@ describe('IframeManager', () => {
         mockWindow as Window,
       );
 
-      const manager = IframeManager.getInstance();
+      const manager = new IframeManager();
       const sendMessageSpy = vi
         .spyOn(manager, 'sendMessage')
         .mockImplementation(vi.fn());
       const id = 'foo';
-      const [newWindow, returnedId] = await manager.create(id);
+      const [newWindow, returnedId] = await manager.create({
+        id,
+        getPort: makeGetPort(),
+      });
 
       expect(newWindow).toBe(mockWindow);
       expect(returnedId).toBe(id);
@@ -93,6 +63,35 @@ describe('IframeManager', () => {
         data: null,
       });
     });
+
+    it('creates a new iframe with the default getPort function', async () => {
+      vi.resetModules();
+      vi.doMock('@ocap/streams', () => ({
+        initializeMessageChannel: vi.fn(),
+        MessagePortReader: class Mock1 {},
+        MessagePortWriter: class Mock2 {},
+      }));
+      const IframeManager2 = (await import('./iframe-manager.js'))
+        .IframeManager;
+
+      const mockWindow = {};
+      vi.mocked(snapsUtils.createWindow).mockResolvedValueOnce(
+        mockWindow as Window,
+      );
+      const manager = new IframeManager2();
+      const sendMessageSpy = vi
+        .spyOn(manager, 'sendMessage')
+        .mockImplementation(vi.fn());
+      const [newWindow, id] = await manager.create();
+
+      expect(newWindow).toBe(mockWindow);
+      expect(id).toBeTypeOf('string');
+      expect(sendMessageSpy).toHaveBeenCalledOnce();
+      expect(sendMessageSpy).toHaveBeenCalledWith(id, {
+        type: 'ping',
+        data: null,
+      });
+    });
   });
 
   describe('delete', () => {
@@ -107,22 +106,22 @@ describe('IframeManager', () => {
         return iframe.contentWindow as Window;
       });
 
-      const manager = IframeManager.getInstance();
+      const manager = new IframeManager();
       vi.spyOn(manager, 'sendMessage').mockImplementation(vi.fn());
 
-      await manager.create(id);
-      manager.delete(id);
+      await manager.create({ id, getPort: makeGetPort() });
+      await manager.delete(id);
 
       expect(removeSpy).toHaveBeenCalledOnce();
     });
 
     it('ignores attempt to delete unrecognized iframe', async () => {
       const id = 'foo';
-      const manager = IframeManager.getInstance();
+      const manager = new IframeManager();
       const iframe = document.createElement('iframe');
 
       const removeSpy = vi.spyOn(iframe, 'remove');
-      manager.delete(id);
+      await manager.delete(id);
 
       expect(removeSpy).not.toHaveBeenCalled();
     });
@@ -130,72 +129,98 @@ describe('IframeManager', () => {
 
   describe('sendMessage', () => {
     it('sends a message to an iframe', async () => {
-      const iframeWindow = { postMessage: vi.fn() };
-      vi.mocked(snapsUtils.createWindow).mockResolvedValueOnce(
-        iframeWindow as unknown as Window,
-      );
+      vi.mocked(snapsUtils.createWindow).mockResolvedValueOnce({} as Window);
 
-      const manager = IframeManager.getInstance();
+      const manager = new IframeManager();
       const sendMessageSpy = vi.spyOn(manager, 'sendMessage');
+      // Intercept the ping message in create()
       sendMessageSpy.mockImplementationOnce(async () => Promise.resolve());
 
+      const { port1, port2 } = new MessageChannel();
+      const portPostMessageSpy = vi.spyOn(port1, 'postMessage');
       const id = 'foo';
-      await manager.create(id);
+      await manager.create({ id, getPort: makeGetPort(port1) });
 
       const message = { type: Command.Evaluate, data: '2+2' };
 
       const messagePromise = manager.sendMessage(id, message);
       const messageId: string | undefined =
-        iframeWindow.postMessage.mock.lastCall?.[0]?.id;
+        portPostMessageSpy.mock.lastCall?.[0]?.id;
       expect(messageId).toBeTypeOf('string');
 
-      window.dispatchEvent(
-        new MessageEvent('message', {
-          data: {
-            id: messageId,
-            message: {
-              type: Command.Evaluate,
-              data: '4',
-            },
-          },
-        }),
-      );
+      port2.postMessage({
+        id: messageId,
+        message: {
+          type: Command.Evaluate,
+          data: '4',
+        },
+      });
 
-      expect(iframeWindow.postMessage).toHaveBeenCalledOnce();
-      expect(iframeWindow.postMessage).toHaveBeenCalledWith(
-        { id: messageId, message },
-        '*',
-      );
+      expect(portPostMessageSpy).toHaveBeenCalledOnce();
+      expect(portPostMessageSpy).toHaveBeenCalledWith({
+        id: messageId,
+        message,
+      });
       expect(await messagePromise).toBe('4');
     });
 
     it('throws if iframe not found', async () => {
-      const manager = IframeManager.getInstance();
+      const manager = new IframeManager();
       const id = 'foo';
       const message = { type: Command.Ping, data: null };
 
       await expect(manager.sendMessage(id, message)).rejects.toThrow(
-        `No iframe with id "${id}"`,
+        `No vat with id "${id}"`,
       );
     });
   });
 
-  describe('warnings', () => {
-    it('calls console.warn when receiving unexpected message', () => {
-      // Initialize manager
-      IframeManager.getInstance();
+  describe('miscellaneous', () => {
+    it('calls console.warn when receiving unexpected message', async () => {
+      vi.mocked(snapsUtils.createWindow).mockResolvedValueOnce({} as Window);
+
+      const manager = new IframeManager();
       const warnSpy = vi.spyOn(console, 'warn');
+      const sendMessageSpy = vi.spyOn(manager, 'sendMessage');
+      // Intercept the ping message in create()
+      sendMessageSpy.mockImplementationOnce(async () => Promise.resolve());
 
-      window.dispatchEvent(
-        new MessageEvent('message', {
-          data: 'foo',
-        }),
-      );
+      const { port1, port2 } = new MessageChannel();
+      await manager.create({ getPort: makeGetPort(port1) });
+
+      port2.postMessage('foo');
+      await delay(10);
 
       expect(warnSpy).toHaveBeenCalledWith(
         'Offscreen received message with unexpected format',
         'foo',
       );
     });
+
+    it('calls console.error when receiving message with unknown id', async () => {
+      vi.mocked(snapsUtils.createWindow).mockResolvedValueOnce({} as Window);
+
+      const manager = new IframeManager();
+      const errorSpy = vi.spyOn(console, 'error');
+      const sendMessageSpy = vi.spyOn(manager, 'sendMessage');
+      // Intercept the ping message in create()
+      sendMessageSpy.mockImplementationOnce(async () => Promise.resolve());
+
+      const { port1, port2 } = new MessageChannel();
+      await manager.create({ getPort: makeGetPort(port1) });
+
+      port2.postMessage({
+        id: 'foo',
+        message: {
+          type: Command.Evaluate,
+          data: '"bar"',
+        },
+      });
+      await delay(10);
+
+      expect(errorSpy).toHaveBeenCalledWith(
+        'No unresolved message with id "foo".',
+      );
+    });
   });
 });
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index 4ccfd0f80..d19798b79 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -1,99 +1,108 @@
 import type { PromiseKit } from '@endo/promise-kit';
 import { makePromiseKit } from '@endo/promise-kit';
 import { createWindow } from '@metamask/snaps-utils';
-
-import type { IframeMessage } from './shared.js';
+import {
+  initializeMessageChannel,
+  MessagePortReader,
+  MessagePortWriter,
+} from '@ocap/streams';
+
+import type {
+  IframeMessage,
+  PortStreams,
+  WrappedIframeMessage,
+} from './shared.js';
 import { Command, isWrappedIframeMessage } from './shared.js';
 
 const IFRAME_URI = 'iframe.html';
 
-// The actual <iframe> id, for greater collision resistance.
+/**
+ * Get a DOM id for our iframes, for greater collision resistance.
+ * @param id - The id to base the DOM id on.
+ * @returns The DOM id.
+ */
 const getHtmlId = (id: string): string => `ocap-iframe-${id}`;
 
 type PromiseCallbacks = Omit<PromiseKit<unknown>, 'promise'>;
 
+type GetPort = (targetWindow: Window) => Promise<MessagePort>;
+
 /**
  * A singleton class to manage and message iframes.
  */
 export class IframeManager {
-  static #instance: IframeManager;
-
   #currentId: number;
 
   readonly #unresolvedMessages: Map<string, PromiseCallbacks>;
 
-  readonly #iframes: Map<string, Window>;
+  #vats: Map<string, PortStreams>;
 
   /**
    * Create a new IframeManager.
    */
-  // Our lint config wants #-private, but we can't do that to the constructor.
-  // eslint-disable-next-line no-restricted-syntax
-  private constructor() {
-    /* v8 ignore next 3: We're just not going to do this to ourselves. */
-    if (IframeManager.#instance !== undefined) {
-      throw new Error('IframeManager is a singleton');
-    }
-
+  constructor() {
     this.#currentId = 0;
-    this.#iframes = new Map();
+    this.#vats = new Map();
     this.#unresolvedMessages = new Map();
-
-    window.addEventListener('message', (event: MessageEvent) =>
-      this.#handleMessage(event),
-    );
-
-    IframeManager.#instance = this;
-  }
-
-  /**
-   * Get the singleton instance of IframeManager.
-   *
-   * @returns The singleton instance of IframeManager.
-   */
-  public static getInstance(): IframeManager {
-    if (!IframeManager.#instance) {
-      IframeManager.#instance = new IframeManager();
-    }
-    return IframeManager.#instance;
   }
 
   /**
-   * Create a new iframe.
-   *
-   * @param id - The id of the iframe to create.
-   * @returns The iframe's content window, and its id.
+   * Create a new vat, in the form of an iframe.
+   * @param args - Options bag.
+   * @param args.id - The id of the vat to create.
+   * @param args.getPort - A function to get the message port for the iframe.
+   * @returns The iframe's content window, and its internal id.
    */
-  async create(id?: string): Promise<readonly [Window, string]> {
-    const actualId = id ?? this.#nextId();
-    const newWindow = await createWindow(IFRAME_URI, getHtmlId(actualId));
-    this.#iframes.set(actualId, newWindow);
-    await this.sendMessage(actualId, { type: Command.Ping, data: null });
-    console.debug(`Created iframe with id "${actualId}"`);
-    return [newWindow, actualId] as const;
+  async create(
+    args: { id?: string; getPort?: GetPort } = {},
+  ): Promise<readonly [Window, string]> {
+    const id = args.id ?? this.#nextId();
+    const getPort = args.getPort ?? initializeMessageChannel;
+
+    const newWindow = await createWindow(IFRAME_URI, getHtmlId(id));
+    const port = await getPort(newWindow);
+    const streams: PortStreams = harden({
+      reader: new MessagePortReader(port),
+      writer: new MessagePortWriter(port),
+    });
+    this.#vats.set(id, streams);
+    /* v8 ignore next 4: Not known to be possible. */
+    this.#receiveMessages(streams.reader).catch((error) => {
+      console.error(`Unexpected read error from vat "${id}"`, error);
+      this.delete(id).catch(() => undefined);
+    });
+
+    await this.sendMessage(id, { type: Command.Ping, data: null });
+    console.debug(`Created vat with id "${id}"`);
+    return [newWindow, id] as const;
   }
 
   /**
    * Delete an iframe.
    *
    * @param id - The id of the iframe to delete.
+   * @returns A promise that resolves when the iframe is deleted.
    */
-  delete(id: string): void {
-    if (this.#iframes.has(id)) {
+  async delete(id: string): Promise<void> {
+    if (this.#vats.has(id)) {
+      const { reader, writer } = this.#vats.get(id) as PortStreams;
+      const closeP = Promise.all([reader.return(), writer.return()]).then(
+        () => undefined,
+      );
       // TODO: Handle orphaned messages
-      this.#iframes.delete(id);
+      this.#vats.delete(id);
 
       const iframe = document.getElementById(getHtmlId(id));
-      /* v8 ignore next 6: Currently impossible. */
+      /* v8 ignore next 6: Not known to be possible. */
       if (iframe === null) {
-        console.error(
-          `Registered iframe with id "${id}" already removed from DOM`,
-        );
-        return;
+        console.error(`iframe of vat with id "${id}" already removed from DOM`);
+        return undefined;
       }
-
       iframe.remove();
+
+      return closeP;
     }
+    return undefined;
   }
 
   /**
@@ -107,37 +116,39 @@ export class IframeManager {
     id: string,
     message: IframeMessage<Command, string | null>,
   ): Promise<unknown> {
-    const iframeWindow = this.#get(id);
-    if (iframeWindow === undefined) {
-      throw new Error(`No iframe with id "${id}"`);
+    const streams = this.#vats.get(id);
+    if (streams === undefined) {
+      throw new Error(`No vat with id "${id}"`);
     }
 
     const { promise, reject, resolve } = makePromiseKit();
     const messageId = this.#nextId();
     this.#unresolvedMessages.set(messageId, { reject, resolve });
-    iframeWindow.postMessage({ id: messageId, message }, '*');
+    await streams.writer.next({ id: messageId, message });
     return promise;
   }
 
-  #handleMessage(event: MessageEvent): void {
-    console.debug('Offscreen received message', event);
+  async #receiveMessages(reader: MessagePortReader<WrappedIframeMessage>): Promise<void> {
+    for await (const rawMessage of reader) {
+      console.debug('Offscreen received message', rawMessage);
 
-    if (!isWrappedIframeMessage(event.data)) {
-      console.warn(
-        'Offscreen received message with unexpected format',
-        event.data,
-      );
-      return;
-    }
+      if (!isWrappedIframeMessage(rawMessage)) {
+        console.warn(
+          'Offscreen received message with unexpected format',
+          rawMessage,
+        );
+        return;
+      }
 
-    const { id, message } = event.data;
-    const promiseCallbacks = this.#unresolvedMessages.get(id);
-    if (promiseCallbacks === undefined) {
-      console.error(`No unresolved message with id "${id}".`);
-      return;
-    }
+      const { id, message } = rawMessage;
+      const promiseCallbacks = this.#unresolvedMessages.get(id);
+      if (promiseCallbacks === undefined) {
+        console.error(`No unresolved message with id "${id}".`);
+        continue;
+      }
 
-    promiseCallbacks.resolve(message.data);
+      promiseCallbacks.resolve(message.data);
+    }
   }
 
   #nextId(): string {
@@ -145,8 +156,4 @@ export class IframeManager {
     this.#currentId += 1;
     return String(id);
   }
-
-  #get(id: string): Window | undefined {
-    return this.#iframes.get(id);
-  }
 }
diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index 59d68f19b..bbf5df807 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -1,94 +1,104 @@
+import {
+  receiveMessagePort,
+  MessagePortReader,
+  MessagePortWriter,
+} from '@ocap/streams';
+
+import type { PortStreams } from './shared.js';
 import { Command, isWrappedIframeMessage } from './shared.js';
 
 const defaultCompartment = new Compartment({ URL });
 
-type MessageEventWithSource = Omit<MessageEvent, 'source'> & {
-  source: NonNullable<MessageEvent['source']>;
-};
+main().catch(console.error);
 
-const isEventWithSource = (
-  event: MessageEvent,
-): event is MessageEventWithSource => event.source !== null;
+/**
+ * The main function for the iframe.
+ */
+async function main(): Promise<void> {
+  const port = await receiveMessagePort();
+  const streams: PortStreams = harden({
+    reader: new MessagePortReader(port),
+    writer: new MessagePortWriter(port),
+  });
 
-window.addEventListener('message', (event: MessageEvent) => {
-  console.debug('iframe received message', event);
+  for await (const wrappedMessage of streams.reader) {
+    console.debug('iframe received message', wrappedMessage);
 
-  if (!isEventWithSource(event)) {
-    console.warn('iframe received message with null source');
-    return;
-  }
-  if (!isWrappedIframeMessage(event.data)) {
-    console.warn('iframe received message with unexpected format', event.data);
-    return;
-  }
+    if (!isWrappedIframeMessage(wrappedMessage)) {
+      console.error(
+        'iframe received message with unexpected format',
+        wrappedMessage,
+      );
+      return;
+    }
 
-  const { id, message } = event.data;
+    const { id, message } = wrappedMessage;
 
-  switch (message.type) {
-    case Command.Evaluate: {
-      const result = safelyEvaluate(message.data);
-      reply(event, id, Command.Evaluate, stringifyResult(result));
-      break;
+    switch (message.type) {
+      case Command.Evaluate: {
+        if (typeof message.data !== 'string') {
+          console.error(
+            'iframe received message with unexpected data type',
+            message.data,
+          );
+          return;
+        }
+        const result = safelyEvaluate(message.data);
+        await reply(id, Command.Evaluate, stringifyResult(result));
+        break;
+      }
+      case Command.Ping:
+        await reply(id, Command.Ping, 'pong');
+        break;
+      default:
+        console.error(
+          // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+          `iframe received unexpected message type: "${message.type}"`,
+        );
     }
-    case Command.Ping:
-      reply(event, id, Command.Ping, 'pong');
-      break;
-    default:
-      console.error(
-        // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-        `iframe received unexpected message type: "${message.type}"`,
-      );
   }
-});
 
-/**
- * Evaluate a string in the default compartment.
- *
- * @param source - The source string to evaluate.
- * @returns The result of the evaluation, or an error message.
- */
-function safelyEvaluate(source: string): string {
-  try {
-    return defaultCompartment.evaluate(source);
-  } catch (error) {
-    if (error instanceof Error) {
-      return `Error: ${error.message}`;
-    }
-    return `Error: Unknown error during evaluation.`;
+  await Promise.all([streams.reader.return(), streams.writer.return()]).catch(
+    () => undefined,
+  );
+  throw new Error('MessagePortReader ended unexpectedly.');
+
+  /**
+   * Reply to the parent window.
+   * @param id - The id of the message to reply to.
+   * @param messageType - The message type.
+   * @param data - The message data.
+   */
+  async function reply(id: string, messageType: Command, data: string): Promise<void> {
+    await streams.writer.next({ id, message: { type: messageType, data } });
   }
-}
 
-/**
- * Stringify an evaluation result.
- *
- * @param result - The result to stringify.
- * @returns The stringified result.
- */
-function stringifyResult(result: unknown): string {
-  try {
-    return JSON.stringify(result, null, 2);
-  } catch {
-    return String(result);
+  /**
+   * Evaluate a string in the default compartment.
+   * @param source - The source string to evaluate.
+   * @returns The result of the evaluation, or an error message.
+   */
+  function safelyEvaluate(source: string): string {
+    try {
+      return defaultCompartment.evaluate(source);
+    } catch (error) {
+      if (error instanceof Error) {
+        return `Error: ${error.message}`;
+      }
+      return `Error: Unknown error during evaluation.`;
+    }
   }
-}
 
-/**
- * Reply to the parent window.
- *
- * @param event - The message event to respond to.
- * @param id - The id of the message to reply to.
- * @param messageType - The message type.
- * @param data - The message data.
- */
-function reply(
-  event: MessageEventWithSource,
-  id: string,
-  messageType: Command,
-  data: string,
-): void {
-  event.source.postMessage(
-    { id, message: { type: messageType, data } },
-    // @ts-expect-error Incorrect DOM types
-    event.origin,
-  );
+  /**
+   * Stringify an evaluation result.
+   * @param result - The result to stringify.
+   * @returns The stringified result.
+   */
+  function stringifyResult(result: unknown): string {
+    try {
+      return JSON.stringify(result, null, 2);
+    } catch {
+      return String(result);
+    }
+  }
 }
diff --git a/packages/extension/src/offscreen.ts b/packages/extension/src/offscreen.ts
index a15ee4524..68e9ed3eb 100644
--- a/packages/extension/src/offscreen.ts
+++ b/packages/extension/src/offscreen.ts
@@ -2,70 +2,79 @@ import { IframeManager } from './iframe-manager.js';
 import type { ExtensionMessage } from './shared.js';
 import { Command, makeHandledCallback } from './shared.js';
 
-// Handle messages from the background service worker
-chrome.runtime.onMessage.addListener(
-  makeHandledCallback(async (message: ExtensionMessage<Command, string>) => {
-    if (message.target !== 'offscreen') {
-      console.warn(
-        `Offscreen received message with unexpected target: "${message.target}"`,
-      );
-      return;
-    }
+main().catch(console.error);
 
-    switch (message.type) {
-      case Command.Evaluate:
-        await reply(Command.Evaluate, await evaluate(message.data));
-        break;
-      case Command.Ping:
-        await reply(Command.Ping, 'pong');
-        break;
-      default:
-        console.error(
-          // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
-          `Offscreen received unexpected message type: "${message.type}"`,
+/**
+ * The main function for the offscreen script.
+ */
+async function main(): Promise<void> {
+  // Hard-code a single iframe for now.
+  const IFRAME_ID = 'default';
+  const iframeManager = new IframeManager();
+  const iframeReadyP = iframeManager
+    .create({ id: IFRAME_ID })
+    .catch((error) => {
+      throw error;
+    });
+
+  // Handle messages from the background service worker
+  chrome.runtime.onMessage.addListener(
+    makeHandledCallback(async (message: ExtensionMessage<Command, string>) => {
+      if (message.target !== 'offscreen') {
+        console.warn(
+          `Offscreen received message with unexpected target: "${message.target}"`,
         );
-    }
-  }),
-);
+        return;
+      }
 
-// Hard-code a single iframe for now.
-const IFRAME_ID = 'default';
-const iframeManager = IframeManager.getInstance();
-iframeManager.create(IFRAME_ID).catch((error) => {
-  throw error;
-});
+      await iframeReadyP;
 
-/**
- * Reply to the background script.
- *
- * @param type - The message type.
- * @param data - The message data.
- */
-async function reply(type: Command, data?: string): Promise<void> {
-  await chrome.runtime.sendMessage({
-    data: data ?? null,
-    target: 'background',
-    type,
-  });
-}
+      switch (message.type) {
+        case Command.Evaluate:
+          await reply(Command.Evaluate, await evaluate(message.data));
+          break;
+        case Command.Ping:
+          await reply(Command.Ping, 'pong');
+          break;
+        default:
+          console.error(
+            // eslint-disable-next-line @typescript-eslint/restrict-template-expressions
+            `Offscreen received unexpected message type: "${message.type}"`,
+          );
+      }
+    }),
+  );
 
-/**
- * Evaluate a string in the default iframe.
- *
- * @param source - The source string to evaluate.
- * @returns The result of the evaluation, or an error message.
- */
-async function evaluate(source: string): Promise<string> {
-  try {
-    const result = await iframeManager.sendMessage(IFRAME_ID, {
-      type: Command.Evaluate,
-      data: source,
+  /**
+   * Reply to the background script.
+   * @param type - The message type.
+   * @param data - The message data.
+   */
+  async function reply(type: Command, data?: string): Promise<void> {
+    await chrome.runtime.sendMessage({
+      data: data ?? null,
+      target: 'background',
+      type,
     });
-    return String(result);
-  } catch (error) {
-    if (error instanceof Error) {
-      return `Error: ${error.message}`;
+  }
+
+  /**
+   * Evaluate a string in the default iframe.
+   * @param source - The source string to evaluate.
+   * @returns The result of the evaluation, or an error message.
+   */
+  async function evaluate(source: string): Promise<string> {
+    try {
+      const result = await iframeManager.sendMessage(IFRAME_ID, {
+        type: Command.Evaluate,
+        data: source,
+      });
+      return String(result);
+    } catch (error) {
+      if (error instanceof Error) {
+        return `Error: ${error.message}`;
+      }
+      return `Error: Unknown error during evaluation.`;
     }
-    return `Error: Unknown error during evaluation.`;
   }
 }
diff --git a/packages/extension/src/shared.test.ts b/packages/extension/src/shared.test.ts
index fb96f0987..2412a8716 100644
--- a/packages/extension/src/shared.test.ts
+++ b/packages/extension/src/shared.test.ts
@@ -1,3 +1,4 @@
+import { delay } from '@ocap/test-utils';
 import { vi, describe, it, expect } from 'vitest';
 
 import { isWrappedIframeMessage, makeHandledCallback } from './shared.js';
@@ -52,8 +53,7 @@ describe('shared', () => {
 
       // eslint-disable-next-line n/callback-return
       callback();
-      // eslint-disable-next-line @typescript-eslint/await-thenable
-      await null;
+      await delay();
 
       expect(consoleErrorSpy).toHaveBeenCalledOnce();
       expect(consoleErrorSpy).toHaveBeenCalledWith(
diff --git a/packages/extension/src/shared.ts b/packages/extension/src/shared.ts
index bec740312..9e6297a6a 100644
--- a/packages/extension/src/shared.ts
+++ b/packages/extension/src/shared.ts
@@ -1,4 +1,5 @@
 import { isObject } from '@metamask/utils';
+import type { MessagePortReader, MessagePortWriter } from '@ocap/streams';
 
 export enum Command {
   Evaluate = 'evaluate',
@@ -24,9 +25,14 @@ export type IframeMessage<
 
 export type WrappedIframeMessage = {
   id: string;
-  message: IframeMessage<Command, string>;
+  message: IframeMessage<Command, string | null>;
 };
 
+export type PortStreams = Readonly<{
+  reader: MessagePortReader<WrappedIframeMessage>;
+  writer: MessagePortWriter<WrappedIframeMessage>;
+}>;
+
 export const isWrappedIframeMessage = (
   value: unknown,
 ): value is WrappedIframeMessage =>
diff --git a/packages/extension/tsconfig.build.json b/packages/extension/tsconfig.build.json
index eccdcd4a5..faa7420d1 100644
--- a/packages/extension/tsconfig.build.json
+++ b/packages/extension/tsconfig.build.json
@@ -9,6 +9,9 @@
     "rootDir": "./src",
     "types": ["chrome", "ses"]
   },
-  "references": [{ "path": "../shims/tsconfig.build.json" }],
+  "references": [
+    { "path": "../shims/tsconfig.build.json" },
+    { "path": "../streams/tsconfig.build.json" }
+  ],
   "include": ["./src/**/*.ts", "./src/dev-console.js"]
 }
diff --git a/packages/extension/tsconfig.json b/packages/extension/tsconfig.json
index 026e18577..426fa1808 100644
--- a/packages/extension/tsconfig.json
+++ b/packages/extension/tsconfig.json
@@ -9,6 +9,6 @@
     "skipLibCheck": true,
     "types": ["chrome", "ses", "vitest", "vitest/jsdom"]
   },
-  "references": [{ "path": "../test-utils" }],
-  "include": ["./src/**/*.ts", "src/dev-console.js"]
+  "references": [{ "path": "../streams" }, { "path": "../test-utils" }],
+  "include": ["./src/**/*.ts", "./src/dev-console.js"]
 }
diff --git a/packages/streams/CHANGELOG.md b/packages/streams/CHANGELOG.md
new file mode 100644
index 000000000..0c82cb1ed
--- /dev/null
+++ b/packages/streams/CHANGELOG.md
@@ -0,0 +1,10 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+[Unreleased]: https://github.com/MetaMask/ocap-kernel/
diff --git a/packages/streams/README.md b/packages/streams/README.md
new file mode 100644
index 000000000..c0aa9d831
--- /dev/null
+++ b/packages/streams/README.md
@@ -0,0 +1,7 @@
+# `streams`
+
+Ocap Kernel streams, compatible with `@endo/stream`, and therefore assumed to run under SES.
+
+## Contributing
+
+This package is part of a monorepo. Instructions for contributing can be found in the [monorepo README](https://github.com/MetaMask/ocap-kernel#readme).
diff --git a/packages/streams/package.json b/packages/streams/package.json
new file mode 100644
index 000000000..3d71b13b0
--- /dev/null
+++ b/packages/streams/package.json
@@ -0,0 +1,68 @@
+{
+  "name": "@ocap/streams",
+  "version": "0.0.0",
+  "private": true,
+  "description": "Ocap Kernel streams",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MetaMask/ocap-kernel.git"
+  },
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.mts",
+        "default": "./dist/index.mjs"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "ts-bridge --project tsconfig.build.json --clean",
+    "build:docs": "typedoc",
+    "changelog:validate": "../../scripts/validate-changelog.sh streams",
+    "clean": "rimraf --glob ./dist './*.tsbuildinfo'",
+    "publish:preview": "yarn npm publish --tag preview",
+    "test": "vitest run --config vitest.config.ts",
+    "test:clean": "yarn test --no-cache --coverage.clean",
+    "test:dev": "yarn test --coverage false",
+    "test:verbose": "yarn test --reporter verbose",
+    "test:watch": "vitest --config vitest.config.ts"
+  },
+  "dependencies": {
+    "@endo/promise-kit": "^1.1.2",
+    "@endo/stream": "^1.2.2",
+    "@metamask/utils": "^9.1.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.15.3",
+    "@metamask/auto-changelog": "^3.4.4",
+    "@ocap/test-utils": "workspace:^",
+    "@ts-bridge/cli": "^0.3.0",
+    "@ts-bridge/shims": "^0.1.1",
+    "@types/jsdom": "^21.1.7",
+    "@vitest/coverage-v8": "^2.0.5",
+    "deepmerge": "^4.3.1",
+    "jsdom": "^24.1.1",
+    "rimraf": "^6.0.1",
+    "typedoc": "^0.24.8",
+    "typedoc-plugin-missing-exports": "^2.0.0",
+    "typescript": "~4.9.5",
+    "vite": "^5.3.5",
+    "vitest": "^2.0.5"
+  },
+  "engines": {
+    "node": "^18.18 || >=20"
+  }
+}
diff --git a/packages/streams/src/index.test.ts b/packages/streams/src/index.test.ts
new file mode 100644
index 000000000..36695bd9c
--- /dev/null
+++ b/packages/streams/src/index.test.ts
@@ -0,0 +1,16 @@
+import { describe, it, expect } from 'vitest';
+
+import * as indexModule from './index.js';
+
+describe('index', () => {
+  it('has the expected exports', () => {
+    expect(Object.keys(indexModule)).toStrictEqual(
+      expect.arrayContaining([
+        'MessagePortReader',
+        'MessagePortWriter',
+        'initializeMessageChannel',
+        'receiveMessagePort',
+      ]),
+    );
+  });
+});
diff --git a/packages/streams/src/index.ts b/packages/streams/src/index.ts
new file mode 100644
index 000000000..bf89703c7
--- /dev/null
+++ b/packages/streams/src/index.ts
@@ -0,0 +1,5 @@
+export {
+  initializeMessageChannel,
+  receiveMessagePort,
+} from './message-channel.js';
+export { MessagePortReader, MessagePortWriter } from './streams.js';
diff --git a/packages/streams/src/message-channel.test.ts b/packages/streams/src/message-channel.test.ts
new file mode 100644
index 000000000..1c843c7ff
--- /dev/null
+++ b/packages/streams/src/message-channel.test.ts
@@ -0,0 +1,216 @@
+import { delay, makePromiseKitMock } from '@ocap/test-utils';
+import { JSDOM } from 'jsdom';
+import { vi, describe, it, beforeEach, afterEach, beforeAll } from 'vitest';
+
+import {
+  initializeMessageChannel,
+  MessageType,
+  receiveMessagePort,
+} from './message-channel.js';
+
+vi.mock('@endo/promise-kit', () => makePromiseKitMock());
+
+describe.concurrent('initializeMessageChannel', () => {
+  it('calls targetWindow.postMessage', async ({ expect }) => {
+    const targetWindow = new JSDOM().window;
+    const postMessageSpy = vi.spyOn(targetWindow, 'postMessage');
+    // We intentionally let this one go. It will never settle.
+    // eslint-disable-next-line @typescript-eslint/no-floating-promises
+    initializeMessageChannel(targetWindow as unknown as Window);
+
+    expect(postMessageSpy).toHaveBeenCalledOnce();
+    expect(postMessageSpy).toHaveBeenCalledWith(
+      {
+        type: MessageType.Initialize,
+      },
+      '*',
+      [expect.any(MessagePort)],
+    );
+  });
+
+  it('resolves a port with no message handler once sent acknowledgment via message channel', async ({
+    expect,
+  }) => {
+    const targetWindow = new JSDOM().window;
+    const postMessageSpy = vi.spyOn(targetWindow, 'postMessage');
+    const messageChannelP = initializeMessageChannel(
+      targetWindow as unknown as Window,
+    );
+
+    // @ts-expect-error Wrong types for window.postMessage()
+    const remotePort: MessagePort = postMessageSpy.mock.lastCall[2][0];
+    remotePort.postMessage({ type: MessageType.Acknowledge });
+
+    const resolvedValue = await messageChannelP;
+    expect(resolvedValue).toBeInstanceOf(MessagePort);
+    expect(resolvedValue.onmessage).toBe(null);
+  });
+
+  it.for([
+    { type: MessageType.Initialize },
+    { type: 'foo' },
+    { foo: 'bar' },
+    {},
+    [],
+    'foo',
+    400,
+    null,
+    undefined,
+  ])(
+    'rejects if sent unexpected message via message channel: %#',
+    async (unexpectedMessage, { expect }) => {
+      const targetWindow = new JSDOM().window;
+      const postMessageSpy = vi.spyOn(targetWindow, 'postMessage');
+      const messageChannelP = initializeMessageChannel(
+        targetWindow as unknown as Window,
+      );
+
+      // @ts-expect-error Wrong types for window.postMessage()
+      const remotePort: MessagePort = postMessageSpy.mock.lastCall[2][0];
+      remotePort.postMessage(unexpectedMessage);
+
+      await expect(messageChannelP).rejects.toThrow(
+        /^Received unexpected message via message port/u,
+      );
+    },
+  );
+});
+
+describe('receiveMessagePort', () => {
+  let messageEventListeners: [string, EventListenerOrEventListenerObject][] =
+    [];
+  let originalAddEventListener: typeof window.addEventListener;
+
+  beforeAll(() => {
+    originalAddEventListener = window.addEventListener;
+  });
+
+  beforeEach(() => {
+    // JSDOM apparently affords no way to clear all event listeners between test runs,
+    // so we have to do it manually.
+    window.addEventListener = (
+      ...args: Parameters<typeof window.addEventListener>
+    ) => {
+      messageEventListeners.push([args[0], args[1]]);
+      originalAddEventListener.call(window, ...args);
+    };
+  });
+
+  afterEach(() => {
+    messageEventListeners.forEach(([messageType, listener]) => {
+      window.removeEventListener(messageType, listener);
+    });
+    messageEventListeners = [];
+    window.addEventListener = originalAddEventListener;
+  });
+
+  it('receives and acknowledges a message port', async ({ expect }) => {
+    const messagePortP = receiveMessagePort();
+
+    const { port2 } = new MessageChannel();
+    const portPostMessageSpy = vi.spyOn(port2, 'postMessage');
+
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: { type: MessageType.Initialize },
+        ports: [port2],
+      }),
+    );
+
+    const resolvedValue = await messagePortP;
+
+    expect(resolvedValue).toBe(port2);
+    expect(portPostMessageSpy).toHaveBeenCalledOnce();
+    expect(portPostMessageSpy).toHaveBeenCalledWith({
+      type: MessageType.Acknowledge,
+    });
+  });
+
+  it('cleans up event listeners', async ({ expect }) => {
+    const addEventListenerSpy = vi.spyOn(window, 'addEventListener');
+    const removeEventListenerSpy = vi.spyOn(window, 'removeEventListener');
+
+    const messagePortP = receiveMessagePort();
+
+    const { port2 } = new MessageChannel();
+    window.dispatchEvent(
+      new MessageEvent('message', {
+        data: { type: MessageType.Initialize },
+        ports: [port2],
+      }),
+    );
+
+    await messagePortP;
+
+    expect(addEventListenerSpy).toHaveBeenCalledOnce();
+    expect(addEventListenerSpy).toHaveBeenCalledWith(
+      'message',
+      expect.any(Function),
+    );
+    expect(removeEventListenerSpy).toHaveBeenCalledOnce();
+    expect(removeEventListenerSpy).toHaveBeenCalledWith(
+      'message',
+      expect.any(Function),
+    );
+  });
+
+  it.for([
+    { type: MessageType.Acknowledge },
+    { type: 'foo' },
+    { foo: 'bar' },
+    {},
+    [],
+    'foo',
+    400,
+    null,
+    undefined,
+  ])(
+    'ignores message events with unexpected data dispatched on window: %#',
+    async (unexpectedMessage, { expect }) => {
+      const messagePortP = receiveMessagePort();
+
+      const { port2 } = new MessageChannel();
+      const portPostMessageSpy = vi.spyOn(port2, 'postMessage');
+
+      const fulfillmentDetector = vi.fn();
+      messagePortP.finally(fulfillmentDetector);
+
+      window.dispatchEvent(
+        new MessageEvent('message', {
+          data: unexpectedMessage,
+        }),
+      );
+
+      await delay();
+
+      expect(fulfillmentDetector).not.toHaveBeenCalled();
+      expect(portPostMessageSpy).not.toHaveBeenCalled();
+    },
+  );
+
+  it.for([{}, { ports: [] }, { ports: [{}, {}] }])(
+    'ignores message events with unexpected ports dispatched on window: %#',
+    async (unexpectedPorts, { expect }) => {
+      const messagePortP = receiveMessagePort();
+
+      const { port2 } = new MessageChannel();
+      const portPostMessageSpy = vi.spyOn(port2, 'postMessage');
+
+      const fulfillmentDetector = vi.fn();
+      messagePortP.finally(fulfillmentDetector);
+
+      window.dispatchEvent(
+        // @ts-expect-error Intentionally destructive testing.
+        new MessageEvent('message', {
+          data: { type: MessageType.Initialize },
+          ...unexpectedPorts,
+        }),
+      );
+
+      await delay();
+
+      expect(fulfillmentDetector).not.toHaveBeenCalled();
+      expect(portPostMessageSpy).not.toHaveBeenCalled();
+    },
+  );
+});
diff --git a/packages/streams/src/message-channel.ts b/packages/streams/src/message-channel.ts
new file mode 100644
index 000000000..9c043be28
--- /dev/null
+++ b/packages/streams/src/message-channel.ts
@@ -0,0 +1,104 @@
+/**
+ * This module establishes a simple protocol for establishing a MessageChannel between
+ * a parent window and its iframe, as follows:
+ * 1. The parent window creates an iframe and appends it to the DOM. The iframe must be
+ *    loaded and the `contentWindow` property must be accessible.
+ * 2. The iframe calls `receiveMessagePort()` on startup in one of its scripts. The script
+ *    element in question should not have the `async` attribute.
+ * 3. The parent window calls `initializeMessageChannel()` which sends a message port to
+ *    the iframe. When the returned promise resolves, the parent window and the iframe have
+ *    established a message channel.
+ * @module MessageChannel utilities
+ */
+
+import { makePromiseKit } from '@endo/promise-kit';
+import { isObject } from '@metamask/utils';
+
+export enum MessageType {
+  Initialize = 'INIT_MESSAGE_CHANNEL',
+  Acknowledge = 'ACK_MESSAGE_CHANNEL',
+}
+
+type InitializeMessage = { type: MessageType.Initialize };
+type AcknowledgeMessage = { type: MessageType.Acknowledge };
+
+const isInitMessage = (
+  event: MessageEvent,
+): event is MessageEvent<InitializeMessage> =>
+  isObject(event.data) &&
+  event.data.type === MessageType.Initialize &&
+  Array.isArray(event.ports) &&
+  event.ports.length === 1 &&
+  event.ports[0] instanceof MessagePort;
+
+const isAckMessage = (value: unknown): value is AcknowledgeMessage =>
+  isObject(value) && value.type === MessageType.Acknowledge;
+
+const stringify = (value: unknown) => JSON.stringify(value, null, 2);
+
+/**
+ * Creates a message channel and sends one of the ports to the target window. The iframe
+ * associated with the target window must be loaded, and it must have called
+ * {@link receiveMessagePort} to receive the remote message port. Rejects if the first
+ * message received over the channel is not an {@link AcknowledgeMessage}.
+ * @param targetWindow - The iframe window to send the message port to.
+ * @returns A promise that resolves with the local message port, once the target window
+ * has acknowledged its receipt of the remote port.
+ */
+export async function initializeMessageChannel(
+  targetWindow: Window,
+): Promise<MessagePort> {
+  const { port1, port2 } = new MessageChannel();
+
+  const { promise, resolve, reject } = makePromiseKit<MessagePort>();
+  // Assigning to the `onmessage` property initializes the port's message queue.
+  port1.onmessage = (message: MessageEvent) => {
+    if (!isAckMessage(message.data)) {
+      reject(
+        new Error(
+          `Received unexpected message via message port:\n${stringify(
+            message.data,
+          )}`,
+        ),
+      );
+      return;
+    }
+
+    resolve(port1);
+  };
+  promise.catch(() => port1.close()).finally(() => (port1.onmessage = null));
+
+  const initMessage: InitializeMessage = {
+    type: MessageType.Initialize,
+  };
+  targetWindow.postMessage(initMessage, '*', [port2]);
+  return promise;
+}
+
+/**
+ * Receives a message port from the parent window, and sends an {@link AcknowledgeMessage}
+ * over the port. Should be called in a script _without_ the `async` attribute on startup.
+ * The parent window must call {@link initializeMessageChannel} to send the message port
+ * after this iframe has loaded. Ignores any message events dispatched on the local
+ * `window` that are not an {@link InitializeMessage}.
+ * @returns A promise that resolves with a message port that can be used to communicate
+ * with the parent window.
+ */
+export async function receiveMessagePort(): Promise<MessagePort> {
+  const { promise, resolve } = makePromiseKit<MessagePort>();
+
+  const listener = (message: MessageEvent) => {
+    if (!isInitMessage(message)) {
+      return;
+    }
+
+    const port = message.ports[0] as MessagePort;
+    const ackMessage: AcknowledgeMessage = { type: MessageType.Acknowledge };
+    port.postMessage(ackMessage);
+    resolve(port);
+  };
+
+  window.addEventListener('message', listener);
+  promise.finally(() => window.removeEventListener('message', listener));
+  return promise;
+}
diff --git a/packages/streams/src/streams.test.ts b/packages/streams/src/streams.test.ts
new file mode 100644
index 000000000..819444a6a
--- /dev/null
+++ b/packages/streams/src/streams.test.ts
@@ -0,0 +1,166 @@
+import { delay, makePromiseKitMock } from '@ocap/test-utils';
+import { describe, expect, it, vi } from 'vitest';
+
+import { MessagePortReader, MessagePortWriter } from './streams.js';
+
+vi.mock('@endo/promise-kit', () => makePromiseKitMock());
+
+describe.concurrent('MessagePortReader', () => {
+  it('constructs a MessagePortReader', () => {
+    const { port1 } = new MessageChannel();
+    const reader = new MessagePortReader(port1);
+
+    expect(reader).toBeInstanceOf(MessagePortReader);
+    expect(reader[Symbol.asyncIterator]()).toBe(reader);
+    expect(port1.onmessage).toBeInstanceOf(Function);
+  });
+
+  it('emits message port message received before next()', async () => {
+    const { port1, port2 } = new MessageChannel();
+    const reader = new MessagePortReader(port1);
+
+    const message = { foo: 'bar' };
+    port2.postMessage(message);
+    await delay(100);
+
+    expect(await reader.next()).toStrictEqual({
+      done: false,
+      value: message,
+    });
+  });
+
+  it('emits message port message received after next()', async () => {
+    const { port1, port2 } = new MessageChannel();
+    const reader = new MessagePortReader(port1);
+    const nextP = reader.next();
+
+    const message = { foo: 'bar' };
+    port2.postMessage(message);
+
+    expect(await nextP).toStrictEqual({ done: false, value: message });
+  });
+
+  it('iterates over multiple port messages', async () => {
+    const { port1, port2 } = new MessageChannel();
+    const reader = new MessagePortReader(port1);
+
+    const messages = [{ foo: 'bar' }, { bar: 'baz' }, { baz: 'qux' }];
+    messages.forEach((message) => port2.postMessage(message));
+
+    for (const message of messages) {
+      expect(await reader.next()).toStrictEqual({
+        done: false,
+        value: message,
+      });
+    }
+  });
+
+  it('ends after returning', async () => {
+    const { port1 } = new MessageChannel();
+    const reader = new MessagePortReader(port1);
+
+    const result = reader.return();
+    expect(await result).toStrictEqual({
+      done: true,
+      value: undefined,
+    });
+    expect(port1.onmessage).toBeNull();
+  });
+
+  it('resolves pending promises after returning', async () => {
+    const { port1 } = new MessageChannel();
+    const reader = new MessagePortReader(port1);
+
+    const nextP = reader.next();
+    const returnP = reader.return();
+
+    expect(await nextP).toStrictEqual({
+      done: true,
+      value: undefined,
+    });
+    expect(await returnP).toStrictEqual({
+      done: true,
+      value: undefined,
+    });
+  });
+
+  it('ends after throwing', async () => {
+    const { port1 } = new MessageChannel();
+    const reader = new MessagePortReader(port1);
+
+    const result = reader.throw();
+    expect(await result).toStrictEqual({
+      done: true,
+      value: undefined,
+    });
+    expect(port1.onmessage).toBeNull();
+  });
+
+  it('resolves pending promises after throwing', async () => {
+    const { port1 } = new MessageChannel();
+    const reader = new MessagePortReader(port1);
+
+    const nextP = reader.next();
+    const returnP = reader.throw();
+
+    expect(await nextP).toStrictEqual({
+      done: true,
+      value: undefined,
+    });
+    expect(await returnP).toStrictEqual({
+      done: true,
+      value: undefined,
+    });
+  });
+});
+
+describe.concurrent('MessagePortWriter', () => {
+  it('constructs a MessagePortWriter', () => {
+    const { port1 } = new MessageChannel();
+    const writer = new MessagePortWriter(port1);
+
+    expect(writer).toBeInstanceOf(MessagePortWriter);
+    expect(writer[Symbol.asyncIterator]()).toBe(writer);
+  });
+
+  it('posts messages to the port', async () => {
+    const { port1, port2 } = new MessageChannel();
+    const writer = new MessagePortWriter(port1);
+
+    const message = { foo: 'bar' };
+    const messageP = new Promise((resolve) => {
+      port2.onmessage = (messageEvent) => resolve(messageEvent.data);
+    });
+    const nextP = writer.next(message);
+
+    expect(await nextP).toStrictEqual({
+      done: false,
+      value: undefined,
+    });
+    expect(await messageP).toStrictEqual(message);
+  });
+
+  it('ends after returning', async () => {
+    const { port1 } = new MessageChannel();
+    const writer = new MessagePortWriter(port1);
+
+    const result = writer.return();
+    expect(await result).toStrictEqual({
+      done: true,
+      value: undefined,
+    });
+    expect(port1.onmessage).toBeNull();
+  });
+
+  it('ends after throwing', async () => {
+    const { port1 } = new MessageChannel();
+    const writer = new MessagePortWriter(port1);
+
+    const result = writer.throw();
+    expect(await result).toStrictEqual({
+      done: true,
+      value: undefined,
+    });
+    expect(port1.onmessage).toBeNull();
+  });
+});
diff --git a/packages/streams/src/streams.ts b/packages/streams/src/streams.ts
new file mode 100644
index 000000000..ffd5d7b4a
--- /dev/null
+++ b/packages/streams/src/streams.ts
@@ -0,0 +1,182 @@
+/**
+ * This module provides a pair of classes for creating readable and writable streams
+ * over a [MessagePort](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort).
+ * The classes are naive passthrough mechanisms for data. Because there is no ergonomic
+ * way to detect the closure of a message port at the time of writing, closure must be
+ * handled at a higher level of abstraction. The lifetime of the underlying message port
+ * is expected to be coextensive with "the other side".
+ *
+ * In addition, the message port mechanism is assumed to be 100% reliable, and the classes
+ * therefore have no concept of errors or error handling. This is instead also delegated
+ * to a higher level of abstraction.
+ *
+ * Regarding limitations around detecting `MessagePort` closure, see:
+ * - https://github.com/fergald/explainer-messageport-close
+ * - https://github.com/whatwg/html/issues/10201
+ * @module MessagePort streams
+ */
+
+import { makePromiseKit } from '@endo/promise-kit';
+import type { Reader, Writer } from '@endo/stream';
+
+type PromiseCallbacks = {
+  resolve: (value: unknown) => void;
+  reject: (reason: unknown) => void;
+};
+
+const makeDoneResult = () =>
+  ({ done: true, value: undefined } as { done: true; value: undefined });
+
+/**
+ * A readable stream over a {@link MessagePort}.
+ *
+ * This class is a naive passthrough mechanism for data over a pair of linked message
+ * ports. The message port mechanism is assumed to be completely reliable, and this
+ * class therefore has no concept of errors or error handling. Errors and closure
+ * are expected to be handled at a higher level of abstraction.
+ *
+ * @see
+ * - {@link MessagePortWriter} for the corresponding writable stream.
+ * - The module-level documentation for more details.
+ */
+export class MessagePortReader<Yield> implements Reader<Yield> {
+  #port: MessagePort;
+
+  /**
+   * For buffering messages to manage backpressure.
+   */
+  #messageQueue: MessageEvent[];
+
+  /**
+   * For buffering reads to manage drain.
+   */
+  #readQueue: PromiseCallbacks[];
+
+  constructor(port: MessagePort) {
+    this.#port = port;
+    this.#messageQueue = [];
+    this.#readQueue = [];
+
+    // Assigning to the `onmessage` property initializes the port's message queue.
+    this.#port.onmessage = this.#handleMessage.bind(this);
+    harden(this);
+  }
+
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+
+  #handleMessage(message: MessageEvent): void {
+    if (this.#readQueue.length > 0) {
+      const { resolve } = this.#readQueue.shift() as PromiseCallbacks;
+      resolve({ done: false, value: message.data });
+    } else {
+      this.#messageQueue.push(message);
+    }
+  }
+
+  /**
+   * Reads the next message from the port.
+   * @returns The next message from the port.
+   */
+  async next(): Promise<IteratorResult<Yield, undefined>> {
+    const { promise, resolve, reject } = makePromiseKit();
+    if (this.#messageQueue.length > 0) {
+      const message = this.#messageQueue.shift() as MessageEvent;
+      resolve({ done: false, value: message.data });
+    } else {
+      this.#readQueue.push({ resolve, reject });
+    }
+    return promise as Promise<IteratorResult<Yield, undefined>>;
+  }
+
+  /**
+   * Closes the underlying port and returns.
+   * @returns The final result for this stream.
+   */
+  async return(): Promise<IteratorResult<Yield, undefined>> {
+    while (this.#readQueue.length > 0) {
+      const { resolve } = this.#readQueue.shift() as PromiseCallbacks;
+      resolve(makeDoneResult());
+    }
+    return this.#end();
+  }
+
+  /**
+   * Alias for {@link return}.
+   * @deprecated This method only exists for interface conformance. Due to limitations
+   * of the underlying communication mechanism, this class has no concept of errors.
+   * Use {@link return} instead.
+   * @returns The final result for this stream.
+   */
+  async throw(): Promise<IteratorResult<Yield, undefined>> {
+    return this.return();
+  }
+
+  #end(): IteratorResult<Yield, undefined> {
+    this.#port.close();
+    this.#port.onmessage = null;
+    return makeDoneResult();
+  }
+}
+harden(MessagePortReader);
+
+/**
+ * A writable stream over a {@link MessagePort}.
+ *
+ * This class is a naive passthrough mechanism for data over a pair of linked message
+ * ports. The message port mechanism is assumed to be completely reliable, and this
+ * class therefore has no concept of errors or error handling. Errors and closure
+ * are expected to be handled at a higher level of abstraction.
+ *
+ * @see
+ * - {@link MessagePortReader} for the corresponding readable stream.
+ * - The module-level documentation for more details.
+ */
+export class MessagePortWriter<Yield> implements Writer<Yield> {
+  #port: MessagePort;
+
+  constructor(port: MessagePort) {
+    this.#port = port;
+    harden(this);
+  }
+
+  [Symbol.asyncIterator]() {
+    return this;
+  }
+
+  /**
+   * Writes the next message to the port.
+   * @param value - The next message to write to the port.
+   * @returns The result of writing the message.
+   */
+  async next(value: Yield): Promise<IteratorResult<undefined, undefined>> {
+    this.#port.postMessage(value);
+    return { done: false, value: undefined };
+  }
+
+  /**
+   * Closes the underlying port and returns.
+   * @returns The final result for this stream.
+   */
+  async return(): Promise<IteratorResult<undefined, undefined>> {
+    return this.#end();
+  }
+
+  /**
+   * Alias for {@link return}.
+   * @deprecated This method only exists for interface conformance. Due to limitations
+   * of the underlying communication mechanism, this class has no concept of errors.
+   * Use {@link return} instead.
+   * @returns The final result for this stream.
+   */
+  async throw(): Promise<IteratorResult<undefined, undefined>> {
+    return this.#end();
+  }
+
+  #end(): IteratorResult<undefined, undefined> {
+    this.#port.close();
+    return makeDoneResult();
+  }
+}
+harden(MessagePortWriter);
diff --git a/packages/streams/tsconfig.build.json b/packages/streams/tsconfig.build.json
new file mode 100644
index 000000000..b1e6f4092
--- /dev/null
+++ b/packages/streams/tsconfig.build.json
@@ -0,0 +1,12 @@
+{
+  "extends": "../../tsconfig.packages.build.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "lib": ["DOM", "ES2020"],
+    "outDir": "./dist",
+    "rootDir": "./src",
+    "types": ["ses"]
+  },
+  "references": [],
+  "include": ["./src"]
+}
diff --git a/packages/streams/tsconfig.json b/packages/streams/tsconfig.json
new file mode 100644
index 000000000..076246c94
--- /dev/null
+++ b/packages/streams/tsconfig.json
@@ -0,0 +1,10 @@
+{
+  "extends": "../../tsconfig.packages.json",
+  "compilerOptions": {
+    "baseUrl": "./",
+    "lib": ["DOM", "ES2020"],
+    "types": ["ses", "vitest", "vitest/jsdom"]
+  },
+  "references": [{ "path": "../test-utils" }],
+  "include": ["./src"]
+}
diff --git a/packages/streams/typedoc.json b/packages/streams/typedoc.json
new file mode 100644
index 000000000..3d60644d9
--- /dev/null
+++ b/packages/streams/typedoc.json
@@ -0,0 +1,7 @@
+{
+  "entryPoints": ["./src/streams.ts", "./src/message-channel.ts"],
+  "excludePrivate": true,
+  "hideGenerator": true,
+  "out": "docs",
+  "tsconfig": "./tsconfig.build.json"
+}
diff --git a/packages/streams/vitest.config.ts b/packages/streams/vitest.config.ts
new file mode 100644
index 000000000..68aa3a1b5
--- /dev/null
+++ b/packages/streams/vitest.config.ts
@@ -0,0 +1,17 @@
+// eslint-disable-next-line spaced-comment
+/// <reference types="vitest" />
+
+import { defineConfig, mergeConfig } from 'vite';
+
+import { getDefaultConfig } from '../../vitest.config.packages.js';
+
+const defaultConfig = getDefaultConfig();
+
+export default mergeConfig(
+  defaultConfig,
+  defineConfig({
+    test: {
+      setupFiles: '../test-utils/src/env/mock-endo.ts',
+    },
+  }),
+);
diff --git a/tsconfig.build.json b/tsconfig.build.json
index 5107ebe6e..34acb2854 100644
--- a/tsconfig.build.json
+++ b/tsconfig.build.json
@@ -3,6 +3,7 @@
   "include": [],
   "references": [
     { "path": "./packages/extension/tsconfig.build.json" },
-    { "path": "./packages/shims/tsconfig.build.json" }
+    { "path": "./packages/shims/tsconfig.build.json" },
+    { "path": "./packages/streams/tsconfig.build.json" }
   ]
 }
diff --git a/tsconfig.json b/tsconfig.json
index b2cf5851c..2cd76ded6 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -11,6 +11,7 @@
   "references": [
     { "path": "./packages/extension" },
     { "path": "./packages/shims" },
+    { "path": "./packages/streams" },
     { "path": "./packages/test-utils" }
   ]
 }
diff --git a/yarn.lock b/yarn.lock
index 0102093e0..4999c5386 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -334,7 +334,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@endo/eventual-send@npm:^1.2.3, @endo/eventual-send@npm:^1.2.4":
+"@endo/eventual-send@npm:^1.2.2, @endo/eventual-send@npm:^1.2.3, @endo/eventual-send@npm:^1.2.4":
   version: 1.2.4
   resolution: "@endo/eventual-send@npm:1.2.4"
   dependencies:
@@ -377,7 +377,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"@endo/promise-kit@npm:^1.1.3, @endo/promise-kit@npm:^1.1.4":
+"@endo/promise-kit@npm:^1.1.2, @endo/promise-kit@npm:^1.1.3, @endo/promise-kit@npm:^1.1.4":
   version: 1.1.4
   resolution: "@endo/promise-kit@npm:1.1.4"
   dependencies:
@@ -386,6 +386,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@endo/stream@npm:^1.2.2":
+  version: 1.2.2
+  resolution: "@endo/stream@npm:1.2.2"
+  dependencies:
+    "@endo/eventual-send": "npm:^1.2.2"
+    "@endo/promise-kit": "npm:^1.1.2"
+    ses: "npm:^1.5.0"
+  checksum: 10/2c0ebea133c7a184672679dd1597903fd14df1d6ddd3103f44ef476d9b86a58a8c04ecf42f960a79c8ba85f138e2020bf86ae1cd9a483633326bfc2d874473a4
+  languageName: node
+  linkType: hard
+
 "@endo/where@npm:^1.0.6":
   version: 1.0.6
   resolution: "@endo/where@npm:1.0.6"
@@ -1246,6 +1257,7 @@ __metadata:
     "@metamask/snaps-utils": "npm:^7.8.0"
     "@metamask/utils": "npm:^9.1.0"
     "@ocap/shims": "workspace:^"
+    "@ocap/streams": "workspace:^"
     "@ocap/test-utils": "workspace:^"
     "@types/chrome": "npm:^0.0.268"
     "@vitest/coverage-v8": "npm:^2.0.5"
@@ -1316,6 +1328,31 @@ __metadata:
   languageName: unknown
   linkType: soft
 
+"@ocap/streams@workspace:^, @ocap/streams@workspace:packages/streams":
+  version: 0.0.0-use.local
+  resolution: "@ocap/streams@workspace:packages/streams"
+  dependencies:
+    "@arethetypeswrong/cli": "npm:^0.15.3"
+    "@endo/promise-kit": "npm:^1.1.2"
+    "@endo/stream": "npm:^1.2.2"
+    "@metamask/auto-changelog": "npm:^3.4.4"
+    "@metamask/utils": "npm:^9.1.0"
+    "@ocap/test-utils": "workspace:^"
+    "@ts-bridge/cli": "npm:^0.3.0"
+    "@ts-bridge/shims": "npm:^0.1.1"
+    "@types/jsdom": "npm:^21.1.7"
+    "@vitest/coverage-v8": "npm:^2.0.5"
+    deepmerge: "npm:^4.3.1"
+    jsdom: "npm:^24.1.1"
+    rimraf: "npm:^6.0.1"
+    typedoc: "npm:^0.24.8"
+    typedoc-plugin-missing-exports: "npm:^2.0.0"
+    typescript: "npm:~4.9.5"
+    vite: "npm:^5.3.5"
+    vitest: "npm:^2.0.5"
+  languageName: unknown
+  linkType: soft
+
 "@ocap/test-utils@workspace:^, @ocap/test-utils@workspace:packages/test-utils":
   version: 0.0.0-use.local
   resolution: "@ocap/test-utils@workspace:packages/test-utils"
@@ -1682,6 +1719,17 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/jsdom@npm:^21.1.7":
+  version: 21.1.7
+  resolution: "@types/jsdom@npm:21.1.7"
+  dependencies:
+    "@types/node": "npm:*"
+    "@types/tough-cookie": "npm:*"
+    parse5: "npm:^7.0.0"
+  checksum: 10/a5ee54aec813ac928ef783f69828213af4d81325f584e1fe7573a9ae139924c40768d1d5249237e62d51b9a34ed06bde059c86c6b0248d627457ec5e5d532dfa
+  languageName: node
+  linkType: hard
+
 "@types/minimatch@npm:^3.0.3":
   version: 3.0.5
   resolution: "@types/minimatch@npm:3.0.5"
@@ -1730,6 +1778,13 @@ __metadata:
   languageName: node
   linkType: hard
 
+"@types/tough-cookie@npm:*":
+  version: 4.0.5
+  resolution: "@types/tough-cookie@npm:4.0.5"
+  checksum: 10/01fd82efc8202670865928629697b62fe9bf0c0dcbc5b1c115831caeb073a2c0abb871ff393d7df1ae94ea41e256cb87d2a5a91fd03cdb1b0b4384e08d4ee482
+  languageName: node
+  linkType: hard
+
 "@typescript-eslint/eslint-plugin@npm:^8.1.0":
   version: 8.1.0
   resolution: "@typescript-eslint/eslint-plugin@npm:8.1.0"
@@ -5853,7 +5908,7 @@ __metadata:
   languageName: node
   linkType: hard
 
-"ses@npm:^1.1.0, ses@npm:^1.7.0":
+"ses@npm:^1.1.0, ses@npm:^1.5.0, ses@npm:^1.7.0":
   version: 1.7.0
   resolution: "ses@npm:1.7.0"
   dependencies:
@@ -6437,6 +6492,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"typescript@npm:~4.9.5":
+  version: 4.9.5
+  resolution: "typescript@npm:4.9.5"
+  bin:
+    tsc: bin/tsc
+    tsserver: bin/tsserver
+  checksum: 10/458f7220ab11e0fc191514cc41be1707645ec9a8c2d609448a448e18c522cef9646f58728f6811185a4c35613dacdf6c98cf8965c88b3541d0288c47291e4300
+  languageName: node
+  linkType: hard
+
 "typescript@npm:~5.5.4":
   version: 5.5.4
   resolution: "typescript@npm:5.5.4"
@@ -6457,6 +6522,16 @@ __metadata:
   languageName: node
   linkType: hard
 
+"typescript@patch:typescript@npm%3A~4.9.5#optional!builtin<compat/typescript>":
+  version: 4.9.5
+  resolution: "typescript@patch:typescript@npm%3A4.9.5#optional!builtin<compat/typescript>::version=4.9.5&hash=289587"
+  bin:
+    tsc: bin/tsc
+    tsserver: bin/tsserver
+  checksum: 10/5659316360b5cc2d6f5931b346401fa534107b68b60179cf14970e27978f0936c1d5c46f4b5b8175f8cba0430f522b3ce355b4b724c0ea36ce6c0347fab25afd
+  languageName: node
+  linkType: hard
+
 "typescript@patch:typescript@npm%3A~5.5.4#optional!builtin<compat/typescript>":
   version: 5.5.4
   resolution: "typescript@patch:typescript@npm%3A5.5.4#optional!builtin<compat/typescript>::version=5.5.4&hash=b45daf"

From bb51367ec37f583583f3a430ae3b68aade63991e Mon Sep 17 00:00:00 2001
From: Erik Marks <rekmarks@protonmail.com>
Date: Fri, 9 Aug 2024 18:33:59 +0100
Subject: [PATCH 2/9] feat(streams): Add makeMessagePortStreams

---
 packages/extension/src/iframe-manager.test.ts |  1 +
 packages/extension/src/iframe-manager.ts      | 53 +++++++++----------
 packages/extension/src/iframe.ts              | 13 ++---
 packages/extension/src/shared.ts              |  6 ---
 packages/streams/src/index.test.ts            |  1 +
 packages/streams/src/index.ts                 |  7 ++-
 packages/streams/src/message-channel.ts       |  4 +-
 packages/streams/src/streams.test.ts          | 16 +++++-
 packages/streams/src/streams.ts               | 19 ++++++-
 9 files changed, 69 insertions(+), 51 deletions(-)

diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index 3413b8177..a0815d72f 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -68,6 +68,7 @@ describe('IframeManager', () => {
       vi.resetModules();
       vi.doMock('@ocap/streams', () => ({
         initializeMessageChannel: vi.fn(),
+        makeMessagePortStreams: vi.fn(() => ({ reader: {}, writer: {} })),
         MessagePortReader: class Mock1 {},
         MessagePortWriter: class Mock2 {},
       }));
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index d19798b79..44a8aafa7 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -1,17 +1,13 @@
 import type { PromiseKit } from '@endo/promise-kit';
 import { makePromiseKit } from '@endo/promise-kit';
 import { createWindow } from '@metamask/snaps-utils';
+import type { MessagePortReader, MessagePortStreams } from '@ocap/streams';
 import {
   initializeMessageChannel,
-  MessagePortReader,
-  MessagePortWriter,
+  makeMessagePortStreams,
 } from '@ocap/streams';
 
-import type {
-  IframeMessage,
-  PortStreams,
-  WrappedIframeMessage,
-} from './shared.js';
+import type { IframeMessage, WrappedIframeMessage } from './shared.js';
 import { Command, isWrappedIframeMessage } from './shared.js';
 
 const IFRAME_URI = 'iframe.html';
@@ -35,7 +31,7 @@ export class IframeManager {
 
   readonly #unresolvedMessages: Map<string, PromiseCallbacks>;
 
-  #vats: Map<string, PortStreams>;
+  #vats: Map<string, MessagePortStreams<WrappedIframeMessage>>;
 
   /**
    * Create a new IframeManager.
@@ -61,10 +57,7 @@ export class IframeManager {
 
     const newWindow = await createWindow(IFRAME_URI, getHtmlId(id));
     const port = await getPort(newWindow);
-    const streams: PortStreams = harden({
-      reader: new MessagePortReader(port),
-      writer: new MessagePortWriter(port),
-    });
+    const streams = makeMessagePortStreams<WrappedIframeMessage>(port);
     this.#vats.set(id, streams);
     /* v8 ignore next 4: Not known to be possible. */
     this.#receiveMessages(streams.reader).catch((error) => {
@@ -84,25 +77,27 @@ export class IframeManager {
    * @returns A promise that resolves when the iframe is deleted.
    */
   async delete(id: string): Promise<void> {
-    if (this.#vats.has(id)) {
-      const { reader, writer } = this.#vats.get(id) as PortStreams;
-      const closeP = Promise.all([reader.return(), writer.return()]).then(
-        () => undefined,
-      );
-      // TODO: Handle orphaned messages
-      this.#vats.delete(id);
-
-      const iframe = document.getElementById(getHtmlId(id));
-      /* v8 ignore next 6: Not known to be possible. */
-      if (iframe === null) {
-        console.error(`iframe of vat with id "${id}" already removed from DOM`);
-        return undefined;
-      }
-      iframe.remove();
+    const streams = this.#vats.get(id);
+    if (streams === undefined) {
+      return undefined;
+    }
 
-      return closeP;
+    const { reader, writer } = streams;
+    const closeP = Promise.all([reader.return(), writer.return()]).then(
+      () => undefined,
+    );
+    // TODO: Handle orphaned messages
+    this.#vats.delete(id);
+
+    const iframe = document.getElementById(getHtmlId(id));
+    /* v8 ignore next 6: Not known to be possible. */
+    if (iframe === null) {
+      console.error(`iframe of vat with id "${id}" already removed from DOM`);
+      return undefined;
     }
-    return undefined;
+    iframe.remove();
+
+    return closeP;
   }
 
   /**
diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index bbf5df807..296bd45de 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -1,10 +1,6 @@
-import {
-  receiveMessagePort,
-  MessagePortReader,
-  MessagePortWriter,
-} from '@ocap/streams';
+import { receiveMessagePort, makeMessagePortStreams } from '@ocap/streams';
 
-import type { PortStreams } from './shared.js';
+import type { WrappedIframeMessage } from './shared.js';
 import { Command, isWrappedIframeMessage } from './shared.js';
 
 const defaultCompartment = new Compartment({ URL });
@@ -16,10 +12,7 @@ main().catch(console.error);
  */
 async function main(): Promise<void> {
   const port = await receiveMessagePort();
-  const streams: PortStreams = harden({
-    reader: new MessagePortReader(port),
-    writer: new MessagePortWriter(port),
-  });
+  const streams = makeMessagePortStreams<WrappedIframeMessage>(port);
 
   for await (const wrappedMessage of streams.reader) {
     console.debug('iframe received message', wrappedMessage);
diff --git a/packages/extension/src/shared.ts b/packages/extension/src/shared.ts
index 9e6297a6a..99c82f6b9 100644
--- a/packages/extension/src/shared.ts
+++ b/packages/extension/src/shared.ts
@@ -1,5 +1,4 @@
 import { isObject } from '@metamask/utils';
-import type { MessagePortReader, MessagePortWriter } from '@ocap/streams';
 
 export enum Command {
   Evaluate = 'evaluate',
@@ -28,11 +27,6 @@ export type WrappedIframeMessage = {
   message: IframeMessage<Command, string | null>;
 };
 
-export type PortStreams = Readonly<{
-  reader: MessagePortReader<WrappedIframeMessage>;
-  writer: MessagePortWriter<WrappedIframeMessage>;
-}>;
-
 export const isWrappedIframeMessage = (
   value: unknown,
 ): value is WrappedIframeMessage =>
diff --git a/packages/streams/src/index.test.ts b/packages/streams/src/index.test.ts
index 36695bd9c..7ae188e08 100644
--- a/packages/streams/src/index.test.ts
+++ b/packages/streams/src/index.test.ts
@@ -6,6 +6,7 @@ describe('index', () => {
   it('has the expected exports', () => {
     expect(Object.keys(indexModule)).toStrictEqual(
       expect.arrayContaining([
+        'makeMessagePortStreams',
         'MessagePortReader',
         'MessagePortWriter',
         'initializeMessageChannel',
diff --git a/packages/streams/src/index.ts b/packages/streams/src/index.ts
index bf89703c7..2f0d877c8 100644
--- a/packages/streams/src/index.ts
+++ b/packages/streams/src/index.ts
@@ -2,4 +2,9 @@ export {
   initializeMessageChannel,
   receiveMessagePort,
 } from './message-channel.js';
-export { MessagePortReader, MessagePortWriter } from './streams.js';
+export type { MessagePortStreams } from './streams.js';
+export {
+  makeMessagePortStreams,
+  MessagePortReader,
+  MessagePortWriter,
+} from './streams.js';
diff --git a/packages/streams/src/message-channel.ts b/packages/streams/src/message-channel.ts
index 9c043be28..0e5cd2b32 100644
--- a/packages/streams/src/message-channel.ts
+++ b/packages/streams/src/message-channel.ts
@@ -1,6 +1,6 @@
 /**
- * This module establishes a simple protocol for establishing a MessageChannel between
- * a parent window and its iframe, as follows:
+ * This module establishes a simple protocol for creating a MessageChannel between a
+ * window and one of its iframes, as follows:
  * 1. The parent window creates an iframe and appends it to the DOM. The iframe must be
  *    loaded and the `contentWindow` property must be accessible.
  * 2. The iframe calls `receiveMessagePort()` on startup in one of its scripts. The script
diff --git a/packages/streams/src/streams.test.ts b/packages/streams/src/streams.test.ts
index 819444a6a..aac92cfdd 100644
--- a/packages/streams/src/streams.test.ts
+++ b/packages/streams/src/streams.test.ts
@@ -1,10 +1,24 @@
 import { delay, makePromiseKitMock } from '@ocap/test-utils';
 import { describe, expect, it, vi } from 'vitest';
 
-import { MessagePortReader, MessagePortWriter } from './streams.js';
+import {
+  makeMessagePortStreams,
+  MessagePortReader,
+  MessagePortWriter,
+} from './streams.js';
 
 vi.mock('@endo/promise-kit', () => makePromiseKitMock());
 
+describe('makeMessagePorts', () => {
+  it('returns a pair of message ports', () => {
+    const { port1 } = new MessageChannel();
+    const { reader, writer } = makeMessagePortStreams(port1);
+
+    expect(reader).toBeInstanceOf(MessagePortReader);
+    expect(writer).toBeInstanceOf(MessagePortWriter);
+  });
+});
+
 describe.concurrent('MessagePortReader', () => {
   it('constructs a MessagePortReader', () => {
     const { port1 } = new MessageChannel();
diff --git a/packages/streams/src/streams.ts b/packages/streams/src/streams.ts
index ffd5d7b4a..18ec467fb 100644
--- a/packages/streams/src/streams.ts
+++ b/packages/streams/src/streams.ts
@@ -43,12 +43,13 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
   #port: MessagePort;
 
   /**
-   * For buffering messages to manage backpressure.
+   * For buffering messages to manage backpressure, i.e. the input rate exceeding the
+   * read rate.
    */
   #messageQueue: MessageEvent[];
 
   /**
-   * For buffering reads to manage drain.
+   * For buffering reads to manage "suction", i.e. the read rate exceeding the input rate.
    */
   #readQueue: PromiseCallbacks[];
 
@@ -58,6 +59,7 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
     this.#readQueue = [];
 
     // Assigning to the `onmessage` property initializes the port's message queue.
+    // https://developer.mozilla.org/en-US/docs/Web/API/MessagePort/message_event
     this.#port.onmessage = this.#handleMessage.bind(this);
     harden(this);
   }
@@ -180,3 +182,16 @@ export class MessagePortWriter<Yield> implements Writer<Yield> {
   }
 }
 harden(MessagePortWriter);
+
+export type MessagePortStreams<Value> = Readonly<{
+  reader: MessagePortReader<Value>;
+  writer: MessagePortWriter<Value>;
+}>;
+
+export const makeMessagePortStreams = <Value>(
+  port: MessagePort,
+): MessagePortStreams<Value> =>
+  harden({
+    reader: new MessagePortReader(port),
+    writer: new MessagePortWriter(port),
+  });

From 8435c0542b83543bb16c5d21f79462d182559c3a Mon Sep 17 00:00:00 2001
From: Erik Marks <rekmarks@protonmail.com>
Date: Sun, 18 Aug 2024 17:55:20 +0200
Subject: [PATCH 3/9] refactor(streams): Fix Promise-related issues

---
 packages/streams/src/message-channel.ts | 11 ++++++++---
 1 file changed, 8 insertions(+), 3 deletions(-)

diff --git a/packages/streams/src/message-channel.ts b/packages/streams/src/message-channel.ts
index 0e5cd2b32..6a9a4bcb7 100644
--- a/packages/streams/src/message-channel.ts
+++ b/packages/streams/src/message-channel.ts
@@ -66,13 +66,18 @@ export async function initializeMessageChannel(
 
     resolve(port1);
   };
-  promise.catch(() => port1.close()).finally(() => (port1.onmessage = null));
 
   const initMessage: InitializeMessage = {
     type: MessageType.Initialize,
   };
   targetWindow.postMessage(initMessage, '*', [port2]);
-  return promise;
+
+  return promise
+    .catch((error) => {
+      port1.close();
+      throw error;
+    })
+    .finally(() => (port1.onmessage = null));
 }
 
 /**
@@ -91,6 +96,7 @@ export async function receiveMessagePort(): Promise<MessagePort> {
     if (!isInitMessage(message)) {
       return;
     }
+    window.removeEventListener('message', listener);
 
     const port = message.ports[0] as MessagePort;
     const ackMessage: AcknowledgeMessage = { type: MessageType.Acknowledge };
@@ -99,6 +105,5 @@ export async function receiveMessagePort(): Promise<MessagePort> {
   };
 
   window.addEventListener('message', listener);
-  promise.finally(() => window.removeEventListener('message', listener));
   return promise;
 }

From 7a76033a223ec7a9ecf74528e3ceaac0c8c35423 Mon Sep 17 00:00:00 2001
From: Erik Marks <rekmarks@protonmail.com>
Date: Mon, 19 Aug 2024 12:20:40 +0200
Subject: [PATCH 4/9] feat(streams): Add error handling

The streams originally did not have any error handling capabilities,
since the underlying MessagePort was assumed to be completely reliable.
This was a bad asssumption, because `MessagePort.postMessage()` does in
fact throw DOMException errors under various conditions. These
conditions are not necessarily plausible, but we should handle the
possibility nevertheless.

Therefore, the streams now include error handling, and throwing a writer
will cause the reader on the opposite side to throw as well.
---
 packages/extension/src/iframe-manager.test.ts |  35 +-
 packages/extension/src/iframe-manager.ts      |  13 +-
 packages/extension/src/iframe.ts              |   8 +-
 packages/streams/src/index.test.ts            |   2 +-
 packages/streams/src/index.ts                 |   4 +-
 packages/streams/src/streams.test.ts          | 361 ++++++++++++------
 packages/streams/src/streams.ts               | 238 +++++++++---
 7 files changed, 482 insertions(+), 179 deletions(-)

diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index a0815d72f..19c615ed3 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -68,7 +68,7 @@ describe('IframeManager', () => {
       vi.resetModules();
       vi.doMock('@ocap/streams', () => ({
         initializeMessageChannel: vi.fn(),
-        makeMessagePortStreams: vi.fn(() => ({ reader: {}, writer: {} })),
+        makeMessagePortStreamPair: vi.fn(() => ({ reader: {}, writer: {} })),
         MessagePortReader: class Mock1 {},
         MessagePortWriter: class Mock2 {},
       }));
@@ -146,21 +146,27 @@ describe('IframeManager', () => {
 
       const messagePromise = manager.sendMessage(id, message);
       const messageId: string | undefined =
-        portPostMessageSpy.mock.lastCall?.[0]?.id;
+        portPostMessageSpy.mock.lastCall?.[0]?.value?.id;
       expect(messageId).toBeTypeOf('string');
 
       port2.postMessage({
-        id: messageId,
-        message: {
-          type: Command.Evaluate,
-          data: '4',
+        done: false,
+        value: {
+          id: messageId,
+          message: {
+            type: Command.Evaluate,
+            data: '4',
+          },
         },
       });
 
       expect(portPostMessageSpy).toHaveBeenCalledOnce();
       expect(portPostMessageSpy).toHaveBeenCalledWith({
-        id: messageId,
-        message,
+        done: false,
+        value: {
+          id: messageId,
+          message,
+        },
       });
       expect(await messagePromise).toBe('4');
     });
@@ -189,7 +195,7 @@ describe('IframeManager', () => {
       const { port1, port2 } = new MessageChannel();
       await manager.create({ getPort: makeGetPort(port1) });
 
-      port2.postMessage('foo');
+      port2.postMessage({ done: false, value: 'foo' });
       await delay(10);
 
       expect(warnSpy).toHaveBeenCalledWith(
@@ -211,10 +217,13 @@ describe('IframeManager', () => {
       await manager.create({ getPort: makeGetPort(port1) });
 
       port2.postMessage({
-        id: 'foo',
-        message: {
-          type: Command.Evaluate,
-          data: '"bar"',
+        done: false,
+        value: {
+          id: 'foo',
+          message: {
+            type: Command.Evaluate,
+            data: '"bar"',
+          },
         },
       });
       await delay(10);
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index 44a8aafa7..75dcfa785 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -1,10 +1,10 @@
 import type { PromiseKit } from '@endo/promise-kit';
 import { makePromiseKit } from '@endo/promise-kit';
 import { createWindow } from '@metamask/snaps-utils';
-import type { MessagePortReader, MessagePortStreams } from '@ocap/streams';
+import type { MessagePortReader, MessagePortStreamPair } from '@ocap/streams';
 import {
   initializeMessageChannel,
-  makeMessagePortStreams,
+  makeMessagePortStreamPair,
 } from '@ocap/streams';
 
 import type { IframeMessage, WrappedIframeMessage } from './shared.js';
@@ -31,7 +31,7 @@ export class IframeManager {
 
   readonly #unresolvedMessages: Map<string, PromiseCallbacks>;
 
-  #vats: Map<string, MessagePortStreams<WrappedIframeMessage>>;
+  #vats: Map<string, MessagePortStreamPair<WrappedIframeMessage>>;
 
   /**
    * Create a new IframeManager.
@@ -57,7 +57,7 @@ export class IframeManager {
 
     const newWindow = await createWindow(IFRAME_URI, getHtmlId(id));
     const port = await getPort(newWindow);
-    const streams = makeMessagePortStreams<WrappedIframeMessage>(port);
+    const streams = makeMessagePortStreamPair<WrappedIframeMessage>(port);
     this.#vats.set(id, streams);
     /* v8 ignore next 4: Not known to be possible. */
     this.#receiveMessages(streams.reader).catch((error) => {
@@ -82,10 +82,7 @@ export class IframeManager {
       return undefined;
     }
 
-    const { reader, writer } = streams;
-    const closeP = Promise.all([reader.return(), writer.return()]).then(
-      () => undefined,
-    );
+    const closeP = streams.return();
     // TODO: Handle orphaned messages
     this.#vats.delete(id);
 
diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index 296bd45de..1bb838d0e 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -1,4 +1,4 @@
-import { receiveMessagePort, makeMessagePortStreams } from '@ocap/streams';
+import { receiveMessagePort, makeMessagePortStreamPair } from '@ocap/streams';
 
 import type { WrappedIframeMessage } from './shared.js';
 import { Command, isWrappedIframeMessage } from './shared.js';
@@ -12,7 +12,7 @@ main().catch(console.error);
  */
 async function main(): Promise<void> {
   const port = await receiveMessagePort();
-  const streams = makeMessagePortStreams<WrappedIframeMessage>(port);
+  const streams = makeMessagePortStreamPair<WrappedIframeMessage>(port);
 
   for await (const wrappedMessage of streams.reader) {
     console.debug('iframe received message', wrappedMessage);
@@ -51,9 +51,7 @@ async function main(): Promise<void> {
     }
   }
 
-  await Promise.all([streams.reader.return(), streams.writer.return()]).catch(
-    () => undefined,
-  );
+  await streams.return();
   throw new Error('MessagePortReader ended unexpectedly.');
 
   /**
diff --git a/packages/streams/src/index.test.ts b/packages/streams/src/index.test.ts
index 7ae188e08..3ddc0dee0 100644
--- a/packages/streams/src/index.test.ts
+++ b/packages/streams/src/index.test.ts
@@ -6,7 +6,7 @@ describe('index', () => {
   it('has the expected exports', () => {
     expect(Object.keys(indexModule)).toStrictEqual(
       expect.arrayContaining([
-        'makeMessagePortStreams',
+        'makeMessagePortStreamPair',
         'MessagePortReader',
         'MessagePortWriter',
         'initializeMessageChannel',
diff --git a/packages/streams/src/index.ts b/packages/streams/src/index.ts
index 2f0d877c8..7fbe64309 100644
--- a/packages/streams/src/index.ts
+++ b/packages/streams/src/index.ts
@@ -2,9 +2,9 @@ export {
   initializeMessageChannel,
   receiveMessagePort,
 } from './message-channel.js';
-export type { MessagePortStreams } from './streams.js';
+export type { MessagePortStreamPair } from './streams.js';
 export {
-  makeMessagePortStreams,
+  makeMessagePortStreamPair,
   MessagePortReader,
   MessagePortWriter,
 } from './streams.js';
diff --git a/packages/streams/src/streams.test.ts b/packages/streams/src/streams.test.ts
index aac92cfdd..50873fd67 100644
--- a/packages/streams/src/streams.test.ts
+++ b/packages/streams/src/streams.test.ts
@@ -2,23 +2,14 @@ import { delay, makePromiseKitMock } from '@ocap/test-utils';
 import { describe, expect, it, vi } from 'vitest';
 
 import {
-  makeMessagePortStreams,
+  makeDoneResult,
+  makeMessagePortStreamPair,
   MessagePortReader,
   MessagePortWriter,
 } from './streams.js';
 
 vi.mock('@endo/promise-kit', () => makePromiseKitMock());
 
-describe('makeMessagePorts', () => {
-  it('returns a pair of message ports', () => {
-    const { port1 } = new MessageChannel();
-    const { reader, writer } = makeMessagePortStreams(port1);
-
-    expect(reader).toBeInstanceOf(MessagePortReader);
-    expect(writer).toBeInstanceOf(MessagePortWriter);
-  });
-});
-
 describe.concurrent('MessagePortReader', () => {
   it('constructs a MessagePortReader', () => {
     const { port1 } = new MessageChannel();
@@ -29,101 +20,139 @@ describe.concurrent('MessagePortReader', () => {
     expect(port1.onmessage).toBeInstanceOf(Function);
   });
 
-  it('emits message port message received before next()', async () => {
-    const { port1, port2 } = new MessageChannel();
-    const reader = new MessagePortReader(port1);
+  describe('next and iteration', () => {
+    it('emits message port message received before next()', async () => {
+      const { port1, port2 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
 
-    const message = { foo: 'bar' };
-    port2.postMessage(message);
-    await delay(100);
+      const message = { foo: 'bar' };
+      port2.postMessage({ done: false, value: message });
+      await delay(100);
 
-    expect(await reader.next()).toStrictEqual({
-      done: false,
-      value: message,
+      expect(await reader.next()).toStrictEqual({
+        done: false,
+        value: message,
+      });
     });
-  });
 
-  it('emits message port message received after next()', async () => {
-    const { port1, port2 } = new MessageChannel();
-    const reader = new MessagePortReader(port1);
-    const nextP = reader.next();
+    it('emits message port message received after next()', async () => {
+      const { port1, port2 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
 
-    const message = { foo: 'bar' };
-    port2.postMessage(message);
+      const nextP = reader.next();
+      const message = { foo: 'bar' };
+      port2.postMessage({ done: false, value: message });
 
-    expect(await nextP).toStrictEqual({ done: false, value: message });
-  });
+      expect(await nextP).toStrictEqual({ done: false, value: message });
+    });
 
-  it('iterates over multiple port messages', async () => {
-    const { port1, port2 } = new MessageChannel();
-    const reader = new MessagePortReader(port1);
+    it('iterates over multiple port messages', async () => {
+      const { port1, port2 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
 
-    const messages = [{ foo: 'bar' }, { bar: 'baz' }, { baz: 'qux' }];
-    messages.forEach((message) => port2.postMessage(message));
+      const messages = [{ foo: 'bar' }, { bar: 'baz' }, { baz: 'qux' }];
+      messages.forEach((message) =>
+        port2.postMessage({ done: false, value: message }),
+      );
 
-    for (const message of messages) {
-      expect(await reader.next()).toStrictEqual({
-        done: false,
-        value: message,
-      });
-    }
-  });
+      let index = 0;
+      for await (const message of reader) {
+        expect(message).toStrictEqual(messages[index]);
 
-  it('ends after returning', async () => {
-    const { port1 } = new MessageChannel();
-    const reader = new MessagePortReader(port1);
-
-    const result = reader.return();
-    expect(await result).toStrictEqual({
-      done: true,
-      value: undefined,
+        index += 1;
+        if (index >= messages.length) {
+          break;
+        }
+      }
     });
-    expect(port1.onmessage).toBeNull();
-  });
 
-  it('resolves pending promises after returning', async () => {
-    const { port1 } = new MessageChannel();
-    const reader = new MessagePortReader(port1);
+    it('throws when receiving unexpected message from port', async () => {
+      const { port1, port2 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
 
-    const nextP = reader.next();
-    const returnP = reader.return();
+      const nextP = reader.next();
+      const unexpectedMessage = { foo: 'bar' };
+      port2.postMessage(unexpectedMessage);
 
-    expect(await nextP).toStrictEqual({
-      done: true,
-      value: undefined,
+      await expect(nextP).rejects.toThrow(
+        'Received unexpected message via message port',
+      );
     });
-    expect(await returnP).toStrictEqual({
-      done: true,
-      value: undefined,
+
+    it('ends if receiving final iterator result from port', async () => {
+      const { port1, port2 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
+
+      const nextP = reader.next();
+      port2.postMessage(makeDoneResult());
+
+      expect(await nextP).toStrictEqual(makeDoneResult());
+      expect(port1.onmessage).toBeNull();
+      expect(await reader.next()).toStrictEqual(makeDoneResult());
     });
   });
 
-  it('ends after throwing', async () => {
-    const { port1 } = new MessageChannel();
-    const reader = new MessagePortReader(port1);
+  describe('return', () => {
+    it('ends the stream', async () => {
+      const { port1 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
 
-    const result = reader.throw();
-    expect(await result).toStrictEqual({
-      done: true,
-      value: undefined,
+      expect(await reader.return()).toStrictEqual(makeDoneResult());
+      expect(port1.onmessage).toBeNull();
+      expect(await reader.next()).toStrictEqual(makeDoneResult());
+    });
+
+    it('is idempotent', async () => {
+      const { port1 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
+
+      expect(await reader.return()).toStrictEqual(makeDoneResult());
+      expect(await reader.return()).toStrictEqual(makeDoneResult());
+    });
+
+    it('resolves pending read promises', async () => {
+      const { port1 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
+
+      const nextP1 = reader.next();
+      const nextP2 = reader.next();
+      const returnP = reader.return();
+
+      expect(await nextP1).toStrictEqual(makeDoneResult());
+      expect(await nextP2).toStrictEqual(makeDoneResult());
+      expect(await returnP).toStrictEqual(makeDoneResult());
     });
-    expect(port1.onmessage).toBeNull();
   });
 
-  it('resolves pending promises after throwing', async () => {
-    const { port1 } = new MessageChannel();
-    const reader = new MessagePortReader(port1);
+  describe('throw', () => {
+    it('ends the stream', async () => {
+      const { port1 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
 
-    const nextP = reader.next();
-    const returnP = reader.throw();
+      expect(await reader.throw(new Error())).toStrictEqual(makeDoneResult());
+      expect(port1.onmessage).toBeNull();
+      expect(await reader.next()).toStrictEqual(makeDoneResult());
+    });
+
+    it('is idempotent', async () => {
+      const { port1 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
 
-    expect(await nextP).toStrictEqual({
-      done: true,
-      value: undefined,
+      expect(await reader.throw(new Error())).toStrictEqual(makeDoneResult());
+      expect(await reader.throw(new Error())).toStrictEqual(makeDoneResult());
     });
-    expect(await returnP).toStrictEqual({
-      done: true,
-      value: undefined,
+
+    it('rejects pending read promises', async () => {
+      const { port1 } = new MessageChannel();
+      const reader = new MessagePortReader(port1);
+
+      const nextP1 = reader.next();
+      const nextP2 = reader.next();
+      const throwP = reader.throw(new Error('foo'));
+
+      await expect(nextP1).rejects.toThrow(new Error('foo'));
+      await expect(nextP2).rejects.toThrow(new Error('foo'));
+      expect(await throwP).toStrictEqual(makeDoneResult());
     });
   });
 });
@@ -137,44 +166,162 @@ describe.concurrent('MessagePortWriter', () => {
     expect(writer[Symbol.asyncIterator]()).toBe(writer);
   });
 
-  it('posts messages to the port', async () => {
-    const { port1, port2 } = new MessageChannel();
-    const writer = new MessagePortWriter(port1);
+  describe('next and sending messages', () => {
+    it('posts messages to the port', async () => {
+      const { port1, port2 } = new MessageChannel();
+      const writer = new MessagePortWriter(port1);
+
+      const message = { foo: 'bar' };
+      const messageP = new Promise((resolve) => {
+        port2.onmessage = (messageEvent) => resolve(messageEvent.data);
+      });
+      const nextP = writer.next(message);
+
+      expect(await nextP).toStrictEqual({
+        done: false,
+        value: undefined,
+      });
+      expect(await messageP).toStrictEqual({ done: false, value: message });
+    });
+
+    it('throws if failing to send a message', async () => {
+      const { port1 } = new MessageChannel();
+      const postMessageSpy = vi
+        .spyOn(port1, 'postMessage')
+        .mockImplementationOnce(() => {
+          throw new Error('foo');
+        });
+      const writer = new MessagePortWriter(port1);
+
+      expect(await writer.next(null)).toStrictEqual(makeDoneResult());
+      expect(postMessageSpy).toHaveBeenCalledTimes(2);
+      expect(postMessageSpy).toHaveBeenNthCalledWith(1, {
+        done: false,
+        value: null,
+      });
+      expect(postMessageSpy).toHaveBeenNthCalledWith(2, new Error('foo'));
+    });
 
-    const message = { foo: 'bar' };
-    const messageP = new Promise((resolve) => {
-      port2.onmessage = (messageEvent) => resolve(messageEvent.data);
+    it('failing to send a message logs the error', async () => {
+      const { port1 } = new MessageChannel();
+      vi.spyOn(port1, 'postMessage').mockImplementationOnce(() => {
+        throw new Error('foo');
+      });
+      const consoleErrorSpy = vi.spyOn(console, 'error');
+      const writer = new MessagePortWriter(port1);
+
+      expect(await writer.next(null)).toStrictEqual(makeDoneResult());
+      expect(consoleErrorSpy).toHaveBeenCalledOnce();
+      expect(consoleErrorSpy).toHaveBeenCalledWith(
+        'MessagePortWriter experienced a send failure:',
+        new Error('foo'),
+      );
     });
-    const nextP = writer.next(message);
 
-    expect(await nextP).toStrictEqual({
-      done: false,
-      value: undefined,
+    it('handles repeated failures to send messages', async () => {
+      const { port1 } = new MessageChannel();
+      const postMessageSpy = vi
+        .spyOn(port1, 'postMessage')
+        .mockImplementation(() => {
+          throw new Error('foo');
+        });
+      const writer = new MessagePortWriter(port1);
+
+      expect(await writer.next(null)).toStrictEqual(makeDoneResult());
+      expect(postMessageSpy).toHaveBeenCalledTimes(3);
+      expect(postMessageSpy).toHaveBeenNthCalledWith(1, {
+        done: false,
+        value: null,
+      });
+      expect(postMessageSpy).toHaveBeenNthCalledWith(2, new Error('foo'));
+      expect(postMessageSpy).toHaveBeenNthCalledWith(
+        3,
+        new Error(
+          'MessagePortWriter experienced repeated send failures. Giving up on notifying other side.',
+        ),
+      );
     });
-    expect(await messageP).toStrictEqual(message);
   });
 
-  it('ends after returning', async () => {
-    const { port1 } = new MessageChannel();
-    const writer = new MessagePortWriter(port1);
+  describe('return', () => {
+    it('ends the stream', async () => {
+      const { port1 } = new MessageChannel();
+      const writer = new MessagePortWriter(port1);
 
-    const result = writer.return();
-    expect(await result).toStrictEqual({
-      done: true,
-      value: undefined,
+      expect(await writer.return()).toStrictEqual(makeDoneResult());
+      expect(await writer.next(null)).toStrictEqual(makeDoneResult());
+    });
+
+    it('is idempotent', async () => {
+      const { port1 } = new MessageChannel();
+      const writer = new MessagePortWriter(port1);
+
+      expect(await writer.return()).toStrictEqual(makeDoneResult());
+      expect(await writer.return()).toStrictEqual(makeDoneResult());
     });
-    expect(port1.onmessage).toBeNull();
   });
 
-  it('ends after throwing', async () => {
-    const { port1 } = new MessageChannel();
-    const writer = new MessagePortWriter(port1);
+  describe('throw', () => {
+    it('ends the stream', async () => {
+      const { port1 } = new MessageChannel();
+      const writer = new MessagePortWriter(port1);
 
-    const result = writer.throw();
-    expect(await result).toStrictEqual({
-      done: true,
-      value: undefined,
+      expect(await writer.throw(new Error())).toStrictEqual(makeDoneResult());
+      expect(await writer.next(null)).toStrictEqual(makeDoneResult());
     });
+
+    it('is idempotent', async () => {
+      const { port1 } = new MessageChannel();
+      const writer = new MessagePortWriter(port1);
+
+      expect(await writer.throw(new Error())).toStrictEqual(makeDoneResult());
+      expect(await writer.throw(new Error())).toStrictEqual(makeDoneResult());
+    });
+  });
+});
+
+describe('makeMessagePortStreamPair', () => {
+  it('returns a pair of message ports', () => {
+    const { port1 } = new MessageChannel();
+    const { reader, writer } = makeMessagePortStreamPair(port1);
+
+    expect(reader).toBeInstanceOf(MessagePortReader);
+    expect(writer).toBeInstanceOf(MessagePortWriter);
+  });
+
+  it('return() calls return() on both streams', async () => {
+    const { port1, port2 } = new MessageChannel();
+    const streamPair = makeMessagePortStreamPair(port1);
+    const remoteReader = new MessagePortReader(port2);
+    const remoteReadP = remoteReader.next();
+
+    expect(port1.onmessage).toBeDefined();
+    expect(port2.onmessage).toBeDefined();
+
+    await streamPair.return();
+
+    expect(port1.onmessage).toBeNull();
+
+    expect(await remoteReadP).toStrictEqual(makeDoneResult());
+    expect(port2.onmessage).toBeNull();
+  });
+
+  it('throw() calls throw() on the writer but return on the reader', async () => {
+    const { port1, port2 } = new MessageChannel();
+    const streamPair = makeMessagePortStreamPair(port1);
+    const remoteReader = new MessagePortReader(port2);
+    const localReadP = streamPair.reader.next();
+    const remoteReadP = remoteReader.next();
+
+    expect(port1.onmessage).toBeDefined();
+    expect(port2.onmessage).toBeDefined();
+
+    await streamPair.throw(new Error('foo'));
+
+    expect(await localReadP).toStrictEqual(makeDoneResult());
     expect(port1.onmessage).toBeNull();
+
+    await expect(remoteReadP).rejects.toThrow(new Error('foo'));
+    expect(port2.onmessage).toBeNull();
   });
 });
diff --git a/packages/streams/src/streams.ts b/packages/streams/src/streams.ts
index 18ec467fb..92176274d 100644
--- a/packages/streams/src/streams.ts
+++ b/packages/streams/src/streams.ts
@@ -1,14 +1,15 @@
 /**
  * This module provides a pair of classes for creating readable and writable streams
  * over a [MessagePort](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort).
- * The classes are naive passthrough mechanisms for data. Because there is no ergonomic
- * way to detect the closure of a message port at the time of writing, closure must be
- * handled at a higher level of abstraction. The lifetime of the underlying message port
- * is expected to be coextensive with "the other side".
+ * The classes are naive passthrough mechanisms for data that assume exclusive access
+ * to their ports. The lifetime of the underlying message port is expected to be
+ * coextensive with "the other side".
  *
- * In addition, the message port mechanism is assumed to be 100% reliable, and the classes
- * therefore have no concept of errors or error handling. This is instead also delegated
- * to a higher level of abstraction.
+ * At the time of writing, there is no ergonomic way to detect the closure of a port. For
+ * this reason, ports have to be ended manually via `.return()` or `.throw()`. Ending a
+ * {@link MessagePortWriter} will end any {@link MessagePortReader} reading from the
+ * remote port and close the entangled ports, but it will not affect any other streams
+ * connected to the remote or local port, which must also be ended manually.
  *
  * Regarding limitations around detecting `MessagePort` closure, see:
  * - https://github.com/fergald/explainer-messageport-close
@@ -18,35 +19,43 @@
 
 import { makePromiseKit } from '@endo/promise-kit';
 import type { Reader, Writer } from '@endo/stream';
+import { hasProperty, isObject } from '@metamask/utils';
 
 type PromiseCallbacks = {
   resolve: (value: unknown) => void;
   reject: (reason: unknown) => void;
 };
 
-const makeDoneResult = () =>
+const isIteratorResult = (
+  value: unknown,
+): value is IteratorResult<unknown, unknown> =>
+  isObject(value) &&
+  (!hasProperty(value, 'done') || typeof value.done === 'boolean') &&
+  hasProperty(value, 'value');
+
+export const makeDoneResult = () =>
   ({ done: true, value: undefined } as { done: true; value: undefined });
 
 /**
  * A readable stream over a {@link MessagePort}.
  *
  * This class is a naive passthrough mechanism for data over a pair of linked message
- * ports. The message port mechanism is assumed to be completely reliable, and this
- * class therefore has no concept of errors or error handling. Errors and closure
- * are expected to be handled at a higher level of abstraction.
+ * ports. Expects exclusive access to its port.
  *
  * @see
  * - {@link MessagePortWriter} for the corresponding writable stream.
  * - The module-level documentation for more details.
  */
 export class MessagePortReader<Yield> implements Reader<Yield> {
+  #isDone: boolean;
+
   #port: MessagePort;
 
   /**
    * For buffering messages to manage backpressure, i.e. the input rate exceeding the
    * read rate.
    */
-  #messageQueue: MessageEvent[];
+  #messageQueue: MessageEvent<IteratorResult<unknown, unknown>>[];
 
   /**
    * For buffering reads to manage "suction", i.e. the read rate exceeding the input rate.
@@ -54,6 +63,7 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
   #readQueue: PromiseCallbacks[];
 
   constructor(port: MessagePort) {
+    this.#isDone = false;
     this.#port = port;
     this.#messageQueue = [];
     this.#readQueue = [];
@@ -69,9 +79,32 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
   }
 
   #handleMessage(message: MessageEvent): void {
+    if (message.data instanceof Error) {
+      this.#throw(message.data);
+      return;
+    }
+
+    if (!isIteratorResult(message.data)) {
+      this.#throw(
+        new Error(
+          `Received unexpected message via message port:\n${JSON.stringify(
+            message.data,
+            null,
+            2,
+          )}`,
+        ),
+      );
+      return;
+    }
+
+    if (message.data.done === true) {
+      this.#return();
+      return;
+    }
+
     if (this.#readQueue.length > 0) {
       const { resolve } = this.#readQueue.shift() as PromiseCallbacks;
-      resolve({ done: false, value: message.data });
+      resolve({ ...message.data });
     } else {
       this.#messageQueue.push(message);
     }
@@ -82,10 +115,16 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
    * @returns The next message from the port.
    */
   async next(): Promise<IteratorResult<Yield, undefined>> {
+    if (this.#isDone) {
+      return makeDoneResult();
+    }
+
     const { promise, resolve, reject } = makePromiseKit();
     if (this.#messageQueue.length > 0) {
-      const message = this.#messageQueue.shift() as MessageEvent;
-      resolve({ done: false, value: message.data });
+      const message = this.#messageQueue.shift() as MessageEvent<
+        IteratorResult<unknown, unknown>
+      >;
+      resolve({ ...message.data });
     } else {
       this.#readQueue.push({ resolve, reject });
     }
@@ -93,32 +132,50 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
   }
 
   /**
-   * Closes the underlying port and returns.
+   * Closes the underlying port and returns. Any unread messages will be lost.
    * @returns The final result for this stream.
    */
   async return(): Promise<IteratorResult<Yield, undefined>> {
+    if (!this.#isDone) {
+      this.#return();
+    }
+    return makeDoneResult();
+  }
+
+  #return(): void {
     while (this.#readQueue.length > 0) {
       const { resolve } = this.#readQueue.shift() as PromiseCallbacks;
       resolve(makeDoneResult());
     }
-    return this.#end();
+    this.#end();
   }
 
   /**
-   * Alias for {@link return}.
-   * @deprecated This method only exists for interface conformance. Due to limitations
-   * of the underlying communication mechanism, this class has no concept of errors.
-   * Use {@link return} instead.
+   * Rejects all pending reads with the specified error, closes the underlying port,
+   * and returns.
+   * @param error - The error to reject pending reads with.
    * @returns The final result for this stream.
    */
-  async throw(): Promise<IteratorResult<Yield, undefined>> {
-    return this.return();
+  async throw(error: Error): Promise<IteratorResult<Yield, undefined>> {
+    if (!this.#isDone) {
+      this.#throw(error);
+    }
+    return makeDoneResult();
   }
 
-  #end(): IteratorResult<Yield, undefined> {
+  #throw(error: Error): void {
+    while (this.#readQueue.length > 0) {
+      const { reject } = this.#readQueue.shift() as PromiseCallbacks;
+      reject(error);
+    }
+    this.#end();
+  }
+
+  #end(): void {
+    this.#isDone = true;
+    this.#messageQueue = [];
     this.#port.close();
     this.#port.onmessage = null;
-    return makeDoneResult();
   }
 }
 harden(MessagePortReader);
@@ -136,9 +193,12 @@ harden(MessagePortReader);
  * - The module-level documentation for more details.
  */
 export class MessagePortWriter<Yield> implements Writer<Yield> {
+  #isDone: boolean;
+
   #port: MessagePort;
 
   constructor(port: MessagePort) {
+    this.#isDone = false;
     this.#port = port;
     harden(this);
   }
@@ -153,45 +213,137 @@ export class MessagePortWriter<Yield> implements Writer<Yield> {
    * @returns The result of writing the message.
    */
   async next(value: Yield): Promise<IteratorResult<undefined, undefined>> {
-    this.#port.postMessage(value);
-    return { done: false, value: undefined };
+    if (this.#isDone) {
+      return makeDoneResult();
+    }
+    return this.#send({ done: false, value });
   }
 
   /**
-   * Closes the underlying port and returns.
+   * Closes the underlying port and returns. Idempotent.
    * @returns The final result for this stream.
    */
   async return(): Promise<IteratorResult<undefined, undefined>> {
-    return this.#end();
+    if (!this.#isDone) {
+      this.#send(makeDoneResult());
+      this.#end();
+    }
+    return makeDoneResult();
   }
 
   /**
-   * Alias for {@link return}.
-   * @deprecated This method only exists for interface conformance. Due to limitations
-   * of the underlying communication mechanism, this class has no concept of errors.
-   * Use {@link return} instead.
+   * Forwards the error to the port and closes this stream. Idempotent.
+   * @param error - The error to forward to the port.
    * @returns The final result for this stream.
    */
-  async throw(): Promise<IteratorResult<undefined, undefined>> {
-    return this.#end();
+  async throw(error: Error): Promise<IteratorResult<undefined, undefined>> {
+    if (!this.#isDone) {
+      this.#throw(error);
+    }
+    return makeDoneResult();
   }
 
-  #end(): IteratorResult<undefined, undefined> {
+  /**
+   * Forwards the error the port and calls `#finish()`. Mutually recursive with `#send()`.
+   * For this reason, includes a flag indicating past failure, so that `#send()` can avoid
+   * infinite recursion. See `#send()` for more details.
+   * @param error - The error to forward.
+   * @param hasFailed - Whether sending has failed previously.
+   * @returns The final result for this stream.
+   */
+  #throw(
+    error: Error,
+    hasFailed = false,
+  ): IteratorResult<undefined, undefined> {
+    const result = this.#send(error, hasFailed);
+    !this.#isDone && this.#end();
+    return result;
+  }
+
+  /**
+   * Sends the value over the port. If sending the value fails, calls `#throw()`, and is
+   * therefore mutually recursive with this method. For this reason, includes a flag
+   * indicating past failure to send a value, which is used to avoid infinite recursion.
+   * If sending the value succeeds, returns a finished result (`{ done: true }`) if the
+   * value was an {@link Error} or itself a finished result, otherwise returns an
+   * unfinished result (`{ done: false }`).
+   * @param value - The value to send over the port.
+   * @param hasFailed - Whether sending has failed previously.
+   * @returns The result of sending the value.
+   */
+  #send(
+    value: IteratorResult<Yield, undefined> | Error,
+    hasFailed = false,
+  ): IteratorResult<undefined, undefined> {
+    try {
+      this.#port.postMessage(value);
+      return value instanceof Error || value.done === true
+        ? makeDoneResult()
+        : { done: false, value: undefined };
+    } catch (error) {
+      console.error('MessagePortWriter experienced a send failure:', error);
+
+      if (hasFailed) {
+        // Break out of repeated failure to send an error. It is unclear how this would occur
+        // in practice, but it's the kind of failure mode where it's better to be sure.
+        try {
+          const repeatedFailureError = new Error(
+            'MessagePortWriter experienced repeated send failures. Giving up on notifying other side.',
+          );
+          console.error(repeatedFailureError);
+          this.#port.postMessage(repeatedFailureError);
+        } catch {
+          // At this point, we are in a profoundly unrecoverable hellhole, and just swallow
+          // the error.
+        }
+      } else {
+        // postMessage throws only DOMExceptions, which inherit from Error
+        this.#throw(error as Error, true);
+      }
+      return makeDoneResult();
+    }
+  }
+
+  #end(): void {
+    this.#isDone = true;
     this.#port.close();
-    return makeDoneResult();
   }
 }
 harden(MessagePortWriter);
 
-export type MessagePortStreams<Value> = Readonly<{
+export type MessagePortStreamPair<Value> = Readonly<{
   reader: MessagePortReader<Value>;
   writer: MessagePortWriter<Value>;
+  /**
+   * Calls `.return()` on both streams.
+   */
+  return: () => Promise<void>;
+  /**
+   * Calls `.throw()` on the writer, forwarding the error to the other side. Returns
+   * the reader.
+   * @param error - The error to forward.
+   */
+  throw: (error: Error) => Promise<void>;
 }>;
 
-export const makeMessagePortStreams = <Value>(
+/**
+ * Makes a reader / writer pair over the same port, and provides convenience methods
+ * for cleaning them up.
+ * @param port - The message port to make the streams over.
+ * @returns The reader and writer streams, and cleanup methods.
+ */
+export const makeMessagePortStreamPair = <Value>(
   port: MessagePort,
-): MessagePortStreams<Value> =>
-  harden({
-    reader: new MessagePortReader(port),
-    writer: new MessagePortWriter(port),
+): MessagePortStreamPair<Value> => {
+  const reader = new MessagePortReader<Value>(port);
+  const writer = new MessagePortWriter<Value>(port);
+
+  return harden({
+    reader,
+    writer,
+    return: async () =>
+      Promise.all([writer.return(), reader.return()]).then(() => undefined),
+    throw: async (error: Error) =>
+      Promise.all([writer.throw(error), reader.return()]).then(() => undefined),
   });
+};

From 3c30f9cd6604502eb25ae5360f6423ba2b0d64da Mon Sep 17 00:00:00 2001
From: Erik Marks <rekmarks@protonmail.com>
Date: Mon, 19 Aug 2024 16:42:13 +0200
Subject: [PATCH 5/9] chore: Post-rebase fixup

---
 packages/streams/package.json | 2 +-
 yarn.lock                     | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/packages/streams/package.json b/packages/streams/package.json
index 3d71b13b0..8fb920b07 100644
--- a/packages/streams/package.json
+++ b/packages/streams/package.json
@@ -41,7 +41,7 @@
     "test:watch": "vitest --config vitest.config.ts"
   },
   "dependencies": {
-    "@endo/promise-kit": "^1.1.2",
+    "@endo/promise-kit": "^1.1.4",
     "@endo/stream": "^1.2.2",
     "@metamask/utils": "^9.1.0"
   },
diff --git a/yarn.lock b/yarn.lock
index 4999c5386..e404bf3a1 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1333,7 +1333,7 @@ __metadata:
   resolution: "@ocap/streams@workspace:packages/streams"
   dependencies:
     "@arethetypeswrong/cli": "npm:^0.15.3"
-    "@endo/promise-kit": "npm:^1.1.2"
+    "@endo/promise-kit": "npm:^1.1.4"
     "@endo/stream": "npm:^1.2.2"
     "@metamask/auto-changelog": "npm:^3.4.4"
     "@metamask/utils": "npm:^9.1.0"

From b1d30df76d552e53383547f19e44854de2a6d39d Mon Sep 17 00:00:00 2001
From: Erik Marks <rekmarks@protonmail.com>
Date: Tue, 20 Aug 2024 00:12:29 +0200
Subject: [PATCH 6/9] refactor(extension): Remove useless .catch() clause

---
 packages/extension/src/offscreen.ts | 6 +-----
 1 file changed, 1 insertion(+), 5 deletions(-)

diff --git a/packages/extension/src/offscreen.ts b/packages/extension/src/offscreen.ts
index 68e9ed3eb..e9b223279 100644
--- a/packages/extension/src/offscreen.ts
+++ b/packages/extension/src/offscreen.ts
@@ -11,11 +11,7 @@ async function main(): Promise<void> {
   // Hard-code a single iframe for now.
   const IFRAME_ID = 'default';
   const iframeManager = new IframeManager();
-  const iframeReadyP = iframeManager
-    .create({ id: IFRAME_ID })
-    .catch((error) => {
-      throw error;
-    });
+  const iframeReadyP = iframeManager.create({ id: IFRAME_ID });
 
   // Handle messages from the background service worker
   chrome.runtime.onMessage.addListener(

From 762c9665e46ddcd994772292a276cb887a6364b8 Mon Sep 17 00:00:00 2001
From: Erik Marks <rekmarks@protonmail.com>
Date: Tue, 20 Aug 2024 00:15:19 +0200
Subject: [PATCH 7/9] chore: Bump TypeScript lib to ES2022

Bumps the default TypeScript lib for all packages from ES2020 to ES2022.
This is not currently compatible with the minimum Chrome version used in
the MetaMask extension (v89), but the target version (v93, ref:
https://caniuse.com/?feats=mdn-javascript_builtins_array_at,mdn-javascript_builtins_regexp_hasindices,mdn-javascript_builtins_object_hasown,mdn-javascript_builtins_error_cause,mdn-javascript_operators_await_top_level,mdn-javascript_classes_private_class_fields,mdn-javascript_classes_private_class_methods,mdn-javascript_classes_static_class_fields,mdn-javascript_classes_static_initialization_blocks)
is only a few versions ahead, and likely to be below the minimum by the
time the Ocap Kernel makes it to production.
---
 packages/extension/tsconfig.build.json | 2 +-
 packages/extension/tsconfig.json       | 2 +-
 packages/streams/tsconfig.build.json   | 2 +-
 packages/streams/tsconfig.json         | 2 +-
 tsconfig.packages.json                 | 2 +-
 5 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/packages/extension/tsconfig.build.json b/packages/extension/tsconfig.build.json
index faa7420d1..ab2ce37fb 100644
--- a/packages/extension/tsconfig.build.json
+++ b/packages/extension/tsconfig.build.json
@@ -4,7 +4,7 @@
     "allowJs": true,
     "baseUrl": "./",
     "emitDeclarationOnly": false,
-    "lib": ["DOM", "ES2020"],
+    "lib": ["DOM", "ES2022"],
     "noEmit": true,
     "rootDir": "./src",
     "types": ["chrome", "ses"]
diff --git a/packages/extension/tsconfig.json b/packages/extension/tsconfig.json
index 426fa1808..060acd4ab 100644
--- a/packages/extension/tsconfig.json
+++ b/packages/extension/tsconfig.json
@@ -4,7 +4,7 @@
     "allowJs": true,
     "baseUrl": "./",
     "isolatedModules": true,
-    "lib": ["DOM", "ES2020"],
+    "lib": ["DOM", "ES2022"],
     "noEmit": true,
     "skipLibCheck": true,
     "types": ["chrome", "ses", "vitest", "vitest/jsdom"]
diff --git a/packages/streams/tsconfig.build.json b/packages/streams/tsconfig.build.json
index b1e6f4092..e600b10be 100644
--- a/packages/streams/tsconfig.build.json
+++ b/packages/streams/tsconfig.build.json
@@ -2,7 +2,7 @@
   "extends": "../../tsconfig.packages.build.json",
   "compilerOptions": {
     "baseUrl": "./",
-    "lib": ["DOM", "ES2020"],
+    "lib": ["DOM", "ES2022"],
     "outDir": "./dist",
     "rootDir": "./src",
     "types": ["ses"]
diff --git a/packages/streams/tsconfig.json b/packages/streams/tsconfig.json
index 076246c94..85b667185 100644
--- a/packages/streams/tsconfig.json
+++ b/packages/streams/tsconfig.json
@@ -2,7 +2,7 @@
   "extends": "../../tsconfig.packages.json",
   "compilerOptions": {
     "baseUrl": "./",
-    "lib": ["DOM", "ES2020"],
+    "lib": ["DOM", "ES2022"],
     "types": ["ses", "vitest", "vitest/jsdom"]
   },
   "references": [{ "path": "../test-utils" }],
diff --git a/tsconfig.packages.json b/tsconfig.packages.json
index 0dd744a1e..31f77b215 100644
--- a/tsconfig.packages.json
+++ b/tsconfig.packages.json
@@ -3,7 +3,7 @@
     "composite": true,
     "exactOptionalPropertyTypes": true,
     "forceConsistentCasingInFileNames": true,
-    "lib": ["ES2020"],
+    "lib": ["ES2022"],
     "module": "Node16",
     "moduleResolution": "Node16",
     "noErrorTruncation": true,

From 710525173bd3e368eb85393b3054275ea1e1a263 Mon Sep 17 00:00:00 2001
From: Erik Marks <rekmarks@protonmail.com>
Date: Tue, 20 Aug 2024 00:22:32 +0200
Subject: [PATCH 8/9] refactor(streams): Throw on repeated failure to send

---
 packages/streams/src/streams.test.ts | 13 ++++++++-----
 packages/streams/src/streams.ts      | 16 ++++++----------
 2 files changed, 14 insertions(+), 15 deletions(-)

diff --git a/packages/streams/src/streams.test.ts b/packages/streams/src/streams.test.ts
index 50873fd67..fb8f1d32f 100644
--- a/packages/streams/src/streams.test.ts
+++ b/packages/streams/src/streams.test.ts
@@ -222,12 +222,17 @@ describe.concurrent('MessagePortWriter', () => {
       const { port1 } = new MessageChannel();
       const postMessageSpy = vi
         .spyOn(port1, 'postMessage')
-        .mockImplementation(() => {
+        .mockImplementationOnce(() => {
+          throw new Error('foo');
+        })
+        .mockImplementationOnce(() => {
           throw new Error('foo');
         });
       const writer = new MessagePortWriter(port1);
 
-      expect(await writer.next(null)).toStrictEqual(makeDoneResult());
+      await expect(writer.next(null)).rejects.toThrow(
+        'MessagePortWriter experienced repeated send failures.',
+      );
       expect(postMessageSpy).toHaveBeenCalledTimes(3);
       expect(postMessageSpy).toHaveBeenNthCalledWith(1, {
         done: false,
@@ -236,9 +241,7 @@ describe.concurrent('MessagePortWriter', () => {
       expect(postMessageSpy).toHaveBeenNthCalledWith(2, new Error('foo'));
       expect(postMessageSpy).toHaveBeenNthCalledWith(
         3,
-        new Error(
-          'MessagePortWriter experienced repeated send failures. Giving up on notifying other side.',
-        ),
+        new Error('MessagePortWriter experienced repeated send failures.'),
       );
     });
   });
diff --git a/packages/streams/src/streams.ts b/packages/streams/src/streams.ts
index 92176274d..9dd8813e1 100644
--- a/packages/streams/src/streams.ts
+++ b/packages/streams/src/streams.ts
@@ -286,16 +286,12 @@ export class MessagePortWriter<Yield> implements Writer<Yield> {
       if (hasFailed) {
         // Break out of repeated failure to send an error. It is unclear how this would occur
         // in practice, but it's the kind of failure mode where it's better to be sure.
-        try {
-          const repeatedFailureError = new Error(
-            'MessagePortWriter experienced repeated send failures. Giving up on notifying other side.',
-          );
-          console.error(repeatedFailureError);
-          this.#port.postMessage(repeatedFailureError);
-        } catch {
-          // At this point, we are in a profoundly unrecoverable hellhole, and just swallow
-          // the error.
-        }
+        const repeatedFailureError = new Error(
+          'MessagePortWriter experienced repeated send failures.',
+          { cause: error },
+        );
+        this.#port.postMessage(repeatedFailureError);
+        throw repeatedFailureError;
       } else {
         // postMessage throws only DOMExceptions, which inherit from Error
         this.#throw(error as Error, true);

From 28f3659eb5171734b654b57d5153cb193ecdf599 Mon Sep 17 00:00:00 2001
From: Erik Marks <rekmarks@protonmail.com>
Date: Tue, 20 Aug 2024 00:33:22 +0200
Subject: [PATCH 9/9] fix: Post-rebase fixup

---
 package.json                                  |  2 +-
 packages/extension/package.json               |  2 +-
 packages/extension/src/iframe-manager.test.ts |  3 +--
 packages/extension/src/iframe-manager.ts      |  8 ++++--
 packages/extension/src/iframe.ts              |  9 ++++++-
 packages/extension/src/offscreen.ts           |  2 ++
 packages/streams/src/message-channel.test.ts  |  6 ++---
 packages/streams/src/message-channel.ts       | 17 +++++++-----
 packages/streams/src/streams.test.ts          |  2 +-
 packages/streams/src/streams.ts               | 27 ++++++++++++++-----
 packages/test-utils/package.json              |  2 +-
 yarn.lock                                     | 26 +++---------------
 12 files changed, 57 insertions(+), 49 deletions(-)

diff --git a/package.json b/package.json
index 3b413a28d..7a56debe7 100644
--- a/package.json
+++ b/package.json
@@ -59,7 +59,7 @@
     "prettier-plugin-packagejson": "^2.3.0",
     "rimraf": "^6.0.1",
     "typedoc": "^0.24.8",
-    "typescript": "~5.5.4",
+    "typescript": "~4.9.5",
     "vite": "^5.3.5",
     "vite-tsconfig-paths": "^4.3.2",
     "vitest": "^2.0.5"
diff --git a/packages/extension/package.json b/packages/extension/package.json
index b3cce458e..3fcdf03ac 100644
--- a/packages/extension/package.json
+++ b/packages/extension/package.json
@@ -47,7 +47,7 @@
     "rimraf": "^6.0.1",
     "typedoc": "^0.24.8",
     "typedoc-plugin-missing-exports": "^2.0.0",
-    "typescript": "~5.5.4",
+    "typescript": "~4.9.5",
     "vite": "^5.3.5",
     "vite-plugin-static-copy": "^1.0.6",
     "vitest": "^2.0.5"
diff --git a/packages/extension/src/iframe-manager.test.ts b/packages/extension/src/iframe-manager.test.ts
index 19c615ed3..6c3d4c9a1 100644
--- a/packages/extension/src/iframe-manager.test.ts
+++ b/packages/extension/src/iframe-manager.test.ts
@@ -1,4 +1,3 @@
-import type { makePromiseKit } from '@endo/promise-kit';
 import * as snapsUtils from '@metamask/snaps-utils';
 import { delay, makePromiseKitMock } from '@ocap/test-utils';
 import { vi, describe, it, expect } from 'vitest';
@@ -15,7 +14,7 @@ vi.mock('@metamask/snaps-utils', () => ({
 describe('IframeManager', () => {
   const makeGetPort =
     (port: MessagePort = new MessageChannel().port1) =>
-    async (_window: Window) =>
+    async (_window: Window): Promise<MessagePort> =>
       Promise.resolve(port);
 
   describe('create', () => {
diff --git a/packages/extension/src/iframe-manager.ts b/packages/extension/src/iframe-manager.ts
index 75dcfa785..5e5c1866d 100644
--- a/packages/extension/src/iframe-manager.ts
+++ b/packages/extension/src/iframe-manager.ts
@@ -14,6 +14,7 @@ const IFRAME_URI = 'iframe.html';
 
 /**
  * Get a DOM id for our iframes, for greater collision resistance.
+ *
  * @param id - The id to base the DOM id on.
  * @returns The DOM id.
  */
@@ -31,7 +32,7 @@ export class IframeManager {
 
   readonly #unresolvedMessages: Map<string, PromiseCallbacks>;
 
-  #vats: Map<string, MessagePortStreamPair<WrappedIframeMessage>>;
+  readonly #vats: Map<string, MessagePortStreamPair<WrappedIframeMessage>>;
 
   /**
    * Create a new IframeManager.
@@ -44,6 +45,7 @@ export class IframeManager {
 
   /**
    * Create a new vat, in the form of an iframe.
+   *
    * @param args - Options bag.
    * @param args.id - The id of the vat to create.
    * @param args.getPort - A function to get the message port for the iframe.
@@ -120,7 +122,9 @@ export class IframeManager {
     return promise;
   }
 
-  async #receiveMessages(reader: MessagePortReader<WrappedIframeMessage>): Promise<void> {
+  async #receiveMessages(
+    reader: MessagePortReader<WrappedIframeMessage>,
+  ): Promise<void> {
     for await (const rawMessage of reader) {
       console.debug('Offscreen received message', rawMessage);
 
diff --git a/packages/extension/src/iframe.ts b/packages/extension/src/iframe.ts
index 1bb838d0e..e5940f27c 100644
--- a/packages/extension/src/iframe.ts
+++ b/packages/extension/src/iframe.ts
@@ -56,16 +56,22 @@ async function main(): Promise<void> {
 
   /**
    * Reply to the parent window.
+   *
    * @param id - The id of the message to reply to.
    * @param messageType - The message type.
    * @param data - The message data.
    */
-  async function reply(id: string, messageType: Command, data: string): Promise<void> {
+  async function reply(
+    id: string,
+    messageType: Command,
+    data: string,
+  ): Promise<void> {
     await streams.writer.next({ id, message: { type: messageType, data } });
   }
 
   /**
    * Evaluate a string in the default compartment.
+   *
    * @param source - The source string to evaluate.
    * @returns The result of the evaluation, or an error message.
    */
@@ -82,6 +88,7 @@ async function main(): Promise<void> {
 
   /**
    * Stringify an evaluation result.
+   *
    * @param result - The result to stringify.
    * @returns The stringified result.
    */
diff --git a/packages/extension/src/offscreen.ts b/packages/extension/src/offscreen.ts
index e9b223279..5c48b8d13 100644
--- a/packages/extension/src/offscreen.ts
+++ b/packages/extension/src/offscreen.ts
@@ -43,6 +43,7 @@ async function main(): Promise<void> {
 
   /**
    * Reply to the background script.
+   *
    * @param type - The message type.
    * @param data - The message data.
    */
@@ -56,6 +57,7 @@ async function main(): Promise<void> {
 
   /**
    * Evaluate a string in the default iframe.
+   *
    * @param source - The source string to evaluate.
    * @returns The result of the evaluation, or an error message.
    */
diff --git a/packages/streams/src/message-channel.test.ts b/packages/streams/src/message-channel.test.ts
index 1c843c7ff..d05d2ab6b 100644
--- a/packages/streams/src/message-channel.test.ts
+++ b/packages/streams/src/message-channel.test.ts
@@ -90,7 +90,7 @@ describe('receiveMessagePort', () => {
     // so we have to do it manually.
     window.addEventListener = (
       ...args: Parameters<typeof window.addEventListener>
-    ) => {
+    ): void => {
       messageEventListeners.push([args[0], args[1]]);
       originalAddEventListener.call(window, ...args);
     };
@@ -173,7 +173,7 @@ describe('receiveMessagePort', () => {
       const portPostMessageSpy = vi.spyOn(port2, 'postMessage');
 
       const fulfillmentDetector = vi.fn();
-      messagePortP.finally(fulfillmentDetector);
+      messagePortP.then(fulfillmentDetector, fulfillmentDetector);
 
       window.dispatchEvent(
         new MessageEvent('message', {
@@ -197,7 +197,7 @@ describe('receiveMessagePort', () => {
       const portPostMessageSpy = vi.spyOn(port2, 'postMessage');
 
       const fulfillmentDetector = vi.fn();
-      messagePortP.finally(fulfillmentDetector);
+      messagePortP.then(fulfillmentDetector, fulfillmentDetector);
 
       window.dispatchEvent(
         // @ts-expect-error Intentionally destructive testing.
diff --git a/packages/streams/src/message-channel.ts b/packages/streams/src/message-channel.ts
index 6a9a4bcb7..42ce3f1cd 100644
--- a/packages/streams/src/message-channel.ts
+++ b/packages/streams/src/message-channel.ts
@@ -2,12 +2,13 @@
  * This module establishes a simple protocol for creating a MessageChannel between a
  * window and one of its iframes, as follows:
  * 1. The parent window creates an iframe and appends it to the DOM. The iframe must be
- *    loaded and the `contentWindow` property must be accessible.
+ * loaded and the `contentWindow` property must be accessible.
  * 2. The iframe calls `receiveMessagePort()` on startup in one of its scripts. The script
- *    element in question should not have the `async` attribute.
+ * element in question should not have the `async` attribute.
  * 3. The parent window calls `initializeMessageChannel()` which sends a message port to
- *    the iframe. When the returned promise resolves, the parent window and the iframe have
- *    established a message channel.
+ * the iframe. When the returned promise resolves, the parent window and the iframe have
+ * established a message channel.
+ *
  * @module MessageChannel utilities
  */
 
@@ -34,13 +35,14 @@ const isInitMessage = (
 const isAckMessage = (value: unknown): value is AcknowledgeMessage =>
   isObject(value) && value.type === MessageType.Acknowledge;
 
-const stringify = (value: unknown) => JSON.stringify(value, null, 2);
+const stringify = (value: unknown): string => JSON.stringify(value, null, 2);
 
 /**
  * Creates a message channel and sends one of the ports to the target window. The iframe
  * associated with the target window must be loaded, and it must have called
  * {@link receiveMessagePort} to receive the remote message port. Rejects if the first
  * message received over the channel is not an {@link AcknowledgeMessage}.
+ *
  * @param targetWindow - The iframe window to send the message port to.
  * @returns A promise that resolves with the local message port, once the target window
  * has acknowledged its receipt of the remote port.
@@ -52,7 +54,7 @@ export async function initializeMessageChannel(
 
   const { promise, resolve, reject } = makePromiseKit<MessagePort>();
   // Assigning to the `onmessage` property initializes the port's message queue.
-  port1.onmessage = (message: MessageEvent) => {
+  port1.onmessage = (message: MessageEvent): void => {
     if (!isAckMessage(message.data)) {
       reject(
         new Error(
@@ -86,13 +88,14 @@ export async function initializeMessageChannel(
  * The parent window must call {@link initializeMessageChannel} to send the message port
  * after this iframe has loaded. Ignores any message events dispatched on the local
  * `window` that are not an {@link InitializeMessage}.
+ *
  * @returns A promise that resolves with a message port that can be used to communicate
  * with the parent window.
  */
 export async function receiveMessagePort(): Promise<MessagePort> {
   const { promise, resolve } = makePromiseKit<MessagePort>();
 
-  const listener = (message: MessageEvent) => {
+  const listener = (message: MessageEvent): void => {
     if (!isInitMessage(message)) {
       return;
     }
diff --git a/packages/streams/src/streams.test.ts b/packages/streams/src/streams.test.ts
index fb8f1d32f..f2375fe25 100644
--- a/packages/streams/src/streams.test.ts
+++ b/packages/streams/src/streams.test.ts
@@ -173,7 +173,7 @@ describe.concurrent('MessagePortWriter', () => {
 
       const message = { foo: 'bar' };
       const messageP = new Promise((resolve) => {
-        port2.onmessage = (messageEvent) => resolve(messageEvent.data);
+        port2.onmessage = (messageEvent): void => resolve(messageEvent.data);
       });
       const nextP = writer.next(message);
 
diff --git a/packages/streams/src/streams.ts b/packages/streams/src/streams.ts
index 9dd8813e1..f7a13109a 100644
--- a/packages/streams/src/streams.ts
+++ b/packages/streams/src/streams.ts
@@ -14,6 +14,7 @@
  * Regarding limitations around detecting `MessagePort` closure, see:
  * - https://github.com/fergald/explainer-messageport-close
  * - https://github.com/whatwg/html/issues/10201
+ *
  * @module MessagePort streams
  */
 
@@ -33,8 +34,10 @@ const isIteratorResult = (
   (!hasProperty(value, 'done') || typeof value.done === 'boolean') &&
   hasProperty(value, 'value');
 
-export const makeDoneResult = () =>
-  ({ done: true, value: undefined } as { done: true; value: undefined });
+export const makeDoneResult = (): { done: true; value: undefined } => ({
+  done: true,
+  value: undefined,
+});
 
 /**
  * A readable stream over a {@link MessagePort}.
@@ -49,7 +52,7 @@ export const makeDoneResult = () =>
 export class MessagePortReader<Yield> implements Reader<Yield> {
   #isDone: boolean;
 
-  #port: MessagePort;
+  readonly #port: MessagePort;
 
   /**
    * For buffering messages to manage backpressure, i.e. the input rate exceeding the
@@ -60,7 +63,7 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
   /**
    * For buffering reads to manage "suction", i.e. the read rate exceeding the input rate.
    */
-  #readQueue: PromiseCallbacks[];
+  readonly #readQueue: PromiseCallbacks[];
 
   constructor(port: MessagePort) {
     this.#isDone = false;
@@ -74,7 +77,7 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
     harden(this);
   }
 
-  [Symbol.asyncIterator]() {
+  [Symbol.asyncIterator](): MessagePortReader<Yield> {
     return this;
   }
 
@@ -112,6 +115,7 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
 
   /**
    * Reads the next message from the port.
+   *
    * @returns The next message from the port.
    */
   async next(): Promise<IteratorResult<Yield, undefined>> {
@@ -133,6 +137,7 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
 
   /**
    * Closes the underlying port and returns. Any unread messages will be lost.
+   *
    * @returns The final result for this stream.
    */
   async return(): Promise<IteratorResult<Yield, undefined>> {
@@ -153,6 +158,7 @@ export class MessagePortReader<Yield> implements Reader<Yield> {
   /**
    * Rejects all pending reads with the specified error, closes the underlying port,
    * and returns.
+   *
    * @param error - The error to reject pending reads with.
    * @returns The final result for this stream.
    */
@@ -195,7 +201,7 @@ harden(MessagePortReader);
 export class MessagePortWriter<Yield> implements Writer<Yield> {
   #isDone: boolean;
 
-  #port: MessagePort;
+  readonly #port: MessagePort;
 
   constructor(port: MessagePort) {
     this.#isDone = false;
@@ -203,12 +209,13 @@ export class MessagePortWriter<Yield> implements Writer<Yield> {
     harden(this);
   }
 
-  [Symbol.asyncIterator]() {
+  [Symbol.asyncIterator](): MessagePortWriter<Yield> {
     return this;
   }
 
   /**
    * Writes the next message to the port.
+   *
    * @param value - The next message to write to the port.
    * @returns The result of writing the message.
    */
@@ -221,6 +228,7 @@ export class MessagePortWriter<Yield> implements Writer<Yield> {
 
   /**
    * Closes the underlying port and returns. Idempotent.
+   *
    * @returns The final result for this stream.
    */
   async return(): Promise<IteratorResult<undefined, undefined>> {
@@ -233,6 +241,7 @@ export class MessagePortWriter<Yield> implements Writer<Yield> {
 
   /**
    * Forwards the error to the port and closes this stream. Idempotent.
+   *
    * @param error - The error to forward to the port.
    * @returns The final result for this stream.
    */
@@ -247,6 +256,7 @@ export class MessagePortWriter<Yield> implements Writer<Yield> {
    * Forwards the error the port and calls `#finish()`. Mutually recursive with `#send()`.
    * For this reason, includes a flag indicating past failure, so that `#send()` can avoid
    * infinite recursion. See `#send()` for more details.
+   *
    * @param error - The error to forward.
    * @param hasFailed - Whether sending has failed previously.
    * @returns The final result for this stream.
@@ -267,6 +277,7 @@ export class MessagePortWriter<Yield> implements Writer<Yield> {
    * If sending the value succeeds, returns a finished result (`{ done: true }`) if the
    * value was an {@link Error} or itself a finished result, otherwise returns an
    * unfinished result (`{ done: false }`).
+   *
    * @param value - The value to send over the port.
    * @param hasFailed - Whether sending has failed previously.
    * @returns The result of sending the value.
@@ -317,6 +328,7 @@ export type MessagePortStreamPair<Value> = Readonly<{
   /**
    * Calls `.throw()` on the writer, forwarding the error to the other side. Returns
    * the reader.
+   *
    * @param error - The error to forward.
    */
   throw: (error: Error) => Promise<void>;
@@ -325,6 +337,7 @@ export type MessagePortStreamPair<Value> = Readonly<{
 /**
  * Makes a reader / writer pair over the same port, and provides convenience methods
  * for cleaning them up.
+ *
  * @param port - The message port to make the streams over.
  * @returns The reader and writer streams, and cleanup methods.
  */
diff --git a/packages/test-utils/package.json b/packages/test-utils/package.json
index b4d43eb12..c239be901 100644
--- a/packages/test-utils/package.json
+++ b/packages/test-utils/package.json
@@ -19,7 +19,7 @@
   "devDependencies": {
     "rimraf": "^6.0.1",
     "ses": "^1.7.0",
-    "typescript": "~5.5.4",
+    "typescript": "~4.9.5",
     "vitest": "^2.0.5"
   },
   "engines": {
diff --git a/yarn.lock b/yarn.lock
index e404bf3a1..d5df286f8 100644
--- a/yarn.lock
+++ b/yarn.lock
@@ -1269,7 +1269,7 @@ __metadata:
     ses: "npm:^1.7.0"
     typedoc: "npm:^0.24.8"
     typedoc-plugin-missing-exports: "npm:^2.0.0"
-    typescript: "npm:~5.5.4"
+    typescript: "npm:~4.9.5"
     vite: "npm:^5.3.5"
     vite-plugin-static-copy: "npm:^1.0.6"
     vitest: "npm:^2.0.5"
@@ -1306,7 +1306,7 @@ __metadata:
     prettier-plugin-packagejson: "npm:^2.3.0"
     rimraf: "npm:^6.0.1"
     typedoc: "npm:^0.24.8"
-    typescript: "npm:~5.5.4"
+    typescript: "npm:~4.9.5"
     vite: "npm:^5.3.5"
     vite-tsconfig-paths: "npm:^4.3.2"
     vitest: "npm:^2.0.5"
@@ -1359,7 +1359,7 @@ __metadata:
   dependencies:
     rimraf: "npm:^6.0.1"
     ses: "npm:^1.7.0"
-    typescript: "npm:~5.5.4"
+    typescript: "npm:~4.9.5"
     vitest: "npm:^2.0.5"
   languageName: unknown
   linkType: soft
@@ -6502,16 +6502,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"typescript@npm:~5.5.4":
-  version: 5.5.4
-  resolution: "typescript@npm:5.5.4"
-  bin:
-    tsc: bin/tsc
-    tsserver: bin/tsserver
-  checksum: 10/1689ccafef894825481fc3d856b4834ba3cc185a9c2878f3c76a9a1ef81af04194849840f3c69e7961e2312771471bb3b460ca92561e1d87599b26c37d0ffb6f
-  languageName: node
-  linkType: hard
-
 "typescript@patch:typescript@npm%3A5.3.3#optional!builtin<compat/typescript>":
   version: 5.3.3
   resolution: "typescript@patch:typescript@npm%3A5.3.3#optional!builtin<compat/typescript>::version=5.3.3&hash=e012d7"
@@ -6532,16 +6522,6 @@ __metadata:
   languageName: node
   linkType: hard
 
-"typescript@patch:typescript@npm%3A~5.5.4#optional!builtin<compat/typescript>":
-  version: 5.5.4
-  resolution: "typescript@patch:typescript@npm%3A5.5.4#optional!builtin<compat/typescript>::version=5.5.4&hash=b45daf"
-  bin:
-    tsc: bin/tsc
-    tsserver: bin/tsserver
-  checksum: 10/2c065f0ef81855eac25c9b658a3c9da65ffc005260c12854c2286f40f3667e1b1ecf8bdbdd37b59aa0397920378ce7900bff8cb32e0f1c7af6fd86efc676718c
-  languageName: node
-  linkType: hard
-
 "undici-types@npm:~5.26.4":
   version: 5.26.5
   resolution: "undici-types@npm:5.26.5"