osra 0.6.3 → 0.6.5

package/README.md

@@ -1,84 +1,99 @@
-# osra
+<p align="center">
+  <h2 align="center">Osra</h2>
+</p>
 
-[![npm version](https://img.shields.io/npm/v/osra.svg)](https://www.npmjs.com/package/osra)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[Documentation](https://osra.banou.dev)
 
-osra is a zero-runtime-dependency TypeScript RPC library that connects two JavaScript contexts over any message channel. Both sides call `expose(value, { transport })` and each receives the other's value with live semantics: functions become callable async proxies, async generators stream with `for await`, streams keep backpressure, errors keep their built-in subclasses, `AbortSignal`s propagate aborts. It works across Workers, SharedWorkers, windows/iframes, MessagePorts, WebSockets, web extensions, and anything else you can wrap in a custom `{ emit, receive }` pair, degrading gracefully to a JSON-only mode on text channels.
+Strictly typed, ergonomic, and lightweight (13kb gzipped) RPC library in Typescript. Send complex types and call functions across contexts with inferred typing, pluggable transports.
 
-## Features
-
-- **Zero runtime dependencies**: one ESM module; the single declared dependency (`@types/webextension-polyfill`) is types-only, supporting the published declarations
-- **Symmetric API**: both sides call `expose()`; either side can pass functions, both can call
-- **Deep type support**: functions, promises, async generators, `ReadableStream`/`WritableStream`, `MessagePort`, `AbortSignal`, `Error` subclasses, `File`/`FileList`, `Request`/`Response`, `Map`/`Set`, typed arrays, `BigInt`, `Symbol`, …
-- **JSON-mode degradation**: most value types work over text-only transports (WebSocket, extension messaging); `Date`, `Map`, typed arrays, even `NaN`/`±Infinity` survive
-- **`identity()`** for reference-preserving sends, **`transfer()`** for zero-copy moves
-- **Strict TypeScript**: `Remote<T>` maps your API type across the wire; a compile-time `Capable` check rejects non-serializable values with the offending path pinpointed
-- **Tested** on Chromium, Firefox, and WebKit via Playwright
-
-## Install
-
-```sh
-npm install osra
-```
+TL;DR: Osra makes your multi-context code looks like normal code. Zero boilerplate and gives you the best error messages you've ever seen.
 
-## Quick Start
-
-```ts
-// worker.ts
+`worker.ts`
+```typescript
 import { expose } from 'osra'
 
-const api = {
-  add: async (a: number, b: number) => a + b,
-  makeCounter: async () => {
+const payload = {
+  hash: crypto.getRandomValues(new Uint8Array(10)),
+  add: (a: number, b: number) => a + b,
+  makeCounter: () => {
     let count = 0
-    return async () => ++count
-  },
-  streamData: async function* () {
-    for (let i = 0; i < 3; i++) yield i
+    return () => ++count
   },
+  streamData: async function* () { yield* [0, 1, 2] }
 }
+export type Payload = typeof payload
 
-export type Api = typeof api
-
-expose(api, { transport: globalThis })
+expose(payload, { transport: globalThis })
 ```
 
-```ts
-// main.ts
-import type { Api } from './worker'
-
+`main.ts`
+```typescript
+import type { Payload } from './worker'
 import { expose } from 'osra'
 
 const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' })
 
-const remote = await expose<Api>({}, { transport: worker })
+export const {
+  hash, // Uint8Array
+  add, // (a: number, b: number) => Promise<number>
+  makeCounter, // () => Promise<() => Promise<number>>,
+  streamData, // () => Promise<AsyncIterableIterator<number>>
+} = await expose<Payload>({}, { transport: worker })
+
+hash.byteLength // 10
 
-await remote.add(40, 2) // 42
+await add(40, 2) // 42
 
-const counter = await remote.makeCounter()
+const counter = await makeCounter()
 await counter() // 1
 await counter() // 2
 
-for await (const n of await remote.streamData()) {
+for await (const n of await streamData()) {
   console.log(n) // 0, 1, 2
 }
 ```
 
-Both sides call `expose()`; the returned promise resolves with the remote side's value once the handshake completes. A side that only serves (like the worker above) can ignore the returned promise.
-
-### Options
-
-| Option | Default | Description |
-|---|---|---|
-| `transport` | required | The channel to communicate over (see [Transports](#transports)) |
-| `key` | `'__OSRA_DEFAULT_KEY__'` | Namespacing tag that lets multiple independent osra connections share one channel; it does not identify peers |
-| `origin` | `'*'` | On window transports: sets the outbound `postMessage` target origin **and** filters inbound messages by `event.origin`; the initial announce beacon alone goes out with `'*'` (see Window ↔ iframe) |
-| `name` / `remoteName` | - | Label your endpoint / only accept envelopes from a matching peer name |
-| `unregisterSignal` | - | `AbortSignal` that tears the connection down (see [Lifecycle](#error-handling--lifecycle)) |
-| `uuid` / `remoteUuid` | random / - | Pin instance uuids (`remoteUuid` is otherwise learned from the peer's announce); when both sides preset each other's `remoteUuid`, the announce handshake is skipped |
-| `revivableModules` | - | `defaults => modules` function to add, drop, reorder, or override revivable modules |
+## Features
 
-If multiple peers connect over the same transport, the returned promise resolves with the **first** peer's value; later peers still connect and can call your exposed value.
+- **Efficient transport modes**:
+  - Structured-clone (default for `Window`, `Worker`, [etc...](#transport-modes)) is the fastest transport mode, being able to clone and transfer values to other contexts efficiently.
+  - JSON (default for `WebSocket`, WebExtensions, [etc...](#transport-modes)) is slower but supports more transport targets (e.g WebSocket, WebExtensions, etc...).
+
+- **Wide type support**: Support all of the native platform types like `Function`, `Promise`, `ReadableStream`, `Response`, `Map`, `Uint8Array`, and [many more](#supported-types)...
+
+- **Explicit typescript errors**: The codebase is entirely and extensively strictly typed. Anything that CAN cause issues at runtime will throw compile time errors.
+
+As an example, trying to transfer a `File` value over a JSON transport, like so, will throw a compile time error:
+```typescript
+┌─────────────────────────────────────────────────────────────────────────────────────────────────────────┐
+│ ... {                                                                                                   │
+│   [ErrorMessage]: "Value type is only supported on structured-clone transports, not on JSON transports";│
+│   [BadValue]: File;                                                                                     │
+│   [Path]: "foo";                                                                                        │
+│   [ParentObject]: { ...; };                                                                             │
+│ }'.                                                                                                     │
+│   Type '{ foo: File; }' ...                                                                             │
+└─────────────────────────────────────────────────────────────────────────────────────────────────────────┘
+       ^^^^^^^^^^^^^^^^^^^^^^^^^
+expose({ foo: new File([], '') }, { transport: new WebSocket('') })
+```
+
+- **Extensive automated test suite** on Chromium, Firefox, and WebKit via Playwright
+
+## Transport modes
+
+- **Structured-clone** (
+[Window](https://developer.mozilla.org/en-US/docs/Web/API/Window),
+[Worker](https://developer.mozilla.org/en-US/docs/Web/API/Worker/Worker),
+[SharedWorker](https://developer.mozilla.org/en-US/docs/Web/API/SharedWorker),
+[ServiceWorker](https://developer.mozilla.org/en-US/docs/Web/API/ServiceWorker),
+[MessagePort](https://developer.mozilla.org/en-US/docs/Web/API/MessagePort),
+custom transports)
+- **JSON** (
+[WebSocket](https://developer.mozilla.org/en-US/docs/Web/API/WebSocket),
+[WebExtension runtime](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions) `connect()` and `onMessage`,
+[WebExtension port](https://developer.mozilla.org/en-US/docs/Mozilla/Add-ons/WebExtensions/API/runtime/Port),
+custom transports with `isJson: true`)
 
 ## Supported types
 
@@ -87,226 +102,131 @@ Transports are either **structured-clone** (Worker, Window, MessagePort, SharedW
 | Type | Clone | JSON | Notes |
 |---|---|---|---|
 | JSON primitives, plain objects, arrays | ✅ | ✅ | |
-| `undefined`, `NaN`, `±Infinity` | ✅ | ✅ | preserved even over JSON |
+| `undefined`, `NaN`, `±Infinity` | ✅ | ✅ | |
 | `Date`, `BigInt`, `Map`, `Set` | ✅ | ✅ | |
-| Typed arrays, `ArrayBuffer` | ✅ | ✅ | subarray views round-trip their visible bytes; the revived view is full-length over a fresh buffer (`byteOffset` 0, length preserved) |
-| `Error` + subclasses | ✅ | ✅ | built-ins (`TypeError`, `RangeError`, `AggregateError` with nested errors, `DOMException`, …) revive as their own class; custom subclasses revive as `Error` with `name`, `message`, `stack`, `cause` preserved (`DOMException` drops `cause`) |
-| `Symbol` | ✅ | ✅ | `Symbol.for` registry symbols round-trip by key; others keep per-connection identity |
+| `ArrayBuffer`, `Int8Array`, `Uint8Array`, `Uint8ClampedArray`, `Int16Array`, `Uint16Array`, `Int32Array`, `Uint32Array`, `Float16Array`, `Float32Array`, `Float64Array`, `BigInt64Array`, `BigUint64Array` | ✅ | ✅ | |
+| `Error` + subclasses | ✅ | ✅ | built-ins errors properly preserve their subclass; custom error classes becomes generic `Error` |
+| `Symbol` | ✅ | ✅ | `Symbol.for` properly preserves the Symbol's key; `Symbol()` is automatically wrapped with [`identity()`](#identity) |
 | `RegExp` | ✅ | ❌ | |
-| `SharedArrayBuffer` | ✅ | ❌ | shared memory across the contexts |
-| Function | ✅ | ✅ | becomes `(...args) => Promise<result>`; arguments and results recurse through the same boxing |
+| `SharedArrayBuffer` | ✅ | ❌ | |
+| Function | ✅ | ✅ | becomes `(...args) => Promise<result>`; arguments and results are properly handled too |
 | `Promise` | ✅ | ✅ | |
-| Async generators / async iterables | ✅ | ✅ | `next`/`return`/`throw` proxied; `for await` works; early `break` runs the source's `finally` |
-| `ReadableStream` | ✅ | ✅ | credit-window backpressure; cancel reason crosses |
-| `WritableStream` | ✅ | ✅ | write/close/abort with acks; sink errors reject the writer with an `Error` carrying the message string only |
-| `MessagePort` | ✅ | ✅ | revives as a real `MessagePort` on both transport kinds; on clone transports the sent port is moved (no longer usable on the sender), over JSON it is bridged by port-id messages |
-| `AbortSignal` | ✅ | ✅ | abort and reason propagate |
-| `File` / `FileList` | ✅ | ❌ | revive as themselves via structured clone (clone transports only); `Blob` is **not** supported |
-| `Request` / `Response` / `Headers` | ✅ | ✅ | streamed bodies; `Request.signal` propagates; `Response.url`/`redirected` restored; opaque status-0 revives as `Response.error()` |
-| `Event` / `CustomEvent` | ✅ | ✅ | subclass fields beyond `detail` are dropped |
+| Async generators / async iterables | ✅ | ✅ | |
+| `ReadableStream` | ✅ | ✅ | |
+| `WritableStream` | ✅ | ✅ | |
+| `MessagePort` | ✅ | ✅ | |
+| `AbortSignal` | ✅ | ✅ | |
+| `File` / `FileList` / `Blob` | ✅ | ❌ | |
+| `Request` / `Response` / `Headers` | ✅ | ✅ | |
+| `Event` / `CustomEvent` | ✅ | ✅ | Event subclass is not preserved |
 | `EventTarget` | ✅ | ✅ | revives as a listener-only façade: `add`/`removeEventListener` proxy to the source; you can't dispatch through it |
-| Other structured-clonables (`ImageData`, `DOMRect`, `CryptoKey`, …) | ✅ | ❌ | pass through structured clone untouched |
-| Transfer-only host objects (`OffscreenCanvas`, `MediaStreamTrack`, `RTCDataChannel`, …) | ✅ | ❌ | always moved to the peer |
-| `ImageBitmap`, `VideoFrame`, `AudioData` | ✅ | ❌ | copied by structured clone; wrap in `transfer()` to move |
-| `WeakMap` / `WeakSet`, other unclonables | ❌ | ❌ | coerce to `{}` at runtime, rejected at compile time |
-
-## Transports
-
-### Worker
+| Structured-clonables (`ImageData`, `DOMRect`, `CryptoKey`, …) | ✅ | ❌ | |
+| Transfer-only host objects (`OffscreenCanvas`, `MediaStreamTrack`, `RTCDataChannel`, …) | ✅ | ❌ | |
+| `ImageBitmap`, `VideoFrame`, `AudioData` | ✅ | ❌ | |
+| `WeakMap` / `WeakSet`, other unclonables | ❌ | ❌ | |
 
-Pass the `Worker` on the page side and `globalThis` (the `DedicatedWorkerGlobalScope`) inside the worker; see [Quick Start](#quick-start). Inside a worker, pass `globalThis` directly; the `Transport` union includes a structural `WorkerSelf` member, so it typechecks without a cast even in code compiled under `lib.dom`.
 
-### Window ↔ iframe
+## Identity
 
-`message` events fire on the window that receives them, so each side pairs the *other* window for emit with its *own* window for receive. `origin` is applied in both directions, with one exception: the initial announce beacon (which carries only channel identifiers) is posted with target origin `'*'` so it can reach an iframe whose document has not committed yet; announce replies and all later traffic use the configured origin, and inbound filtering always applies.
+`identity(value)` preserves reference equality across contexts, sending the same identity wrapped value twice results in the same object reference on the peer.
 
+`worker.ts`
 ```ts
-// parent
-const iframe = document.querySelector('iframe')!
-const remote = await expose<IframeApi>(parentApi, {
-  transport: { emit: iframe.contentWindow!, receive: window },
-  origin: 'https://app.example.com',
-})
-```
-
-```ts
-// iframe
-const remote = await expose<ParentApi>(iframeApi, {
-  transport: { emit: window.parent, receive: window },
-  origin: 'https://host.example.com',
-})
-```
-
-### SharedWorker
+import { expose, identity } from 'osra'
 
-Pass the `SharedWorker` instance directly on the page side; osra rides its `.port` internally. Inside the worker, expose per connected port:
+const value = { foo: 'bar' }
+const payload = { value, ref1: identity(value), ref2: identity(value) }
 
-```ts
-// page
-const sharedWorker = new SharedWorker(new URL('./shared.ts', import.meta.url), { type: 'module' })
-const remote = await expose<Api>({}, { transport: sharedWorker })
+expose(payload, { transport: globalThis })
+export type Payload = typeof payload
 ```
 
+`main.ts`
 ```ts
-// shared.ts
+import type { Payload } from './worker'
 import { expose } from 'osra'
 
-const api = { add: async (a: number, b: number) => a + b }
-
-globalThis.addEventListener('connect', event => {
-  for (const port of (event as MessageEvent).ports) expose(api, { transport: port })
-})
-```
-
-### WebSocket
-
-JSON mode. You can `expose()` while the socket is still `CONNECTING`; outbound envelopes queue until open. The other end is anything that relays frames to a peer also running osra:
+const worker = new Worker(new URL('./worker.ts', import.meta.url), { type: 'module' })
+const { value, ref1, ref2 } = await expose<Payload>({}, { transport: worker })
 
-```ts
-const socket = new WebSocket('wss://relay.example.com')
-const remote = await expose<PeerApi>(localApi, { transport: socket })
+value === ref1 // false
+ref1 === ref2 // true
 ```
 
-### Service worker
-
-A `ServiceWorker` can only emit and a `ServiceWorkerContainer` can only receive, so combine them as a custom pair:
-
-```ts
-const registration = await navigator.serviceWorker.ready
-const remote = await expose<SwApi>(pageApi, {
-  transport: { emit: registration.active!, receive: navigator.serviceWorker },
-})
-```
 
-### Web extension
+## Transfer
 
-JSON mode. `runtime.Port` and the runtime itself (`sendMessage`/`onMessage`) work as standalone transports. `onConnect` and `onMessage` are receive-only: pass them as the `receive` half of a custom `{ emit, receive }` pair, or expose per connected port as below; `expose()` requires a transport that can both emit and receive.
+By default, osra will always copy values, if the value you want to send is a [transferable](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API/Transferable_objects), wrapping it with `transfer(value)` will properly transfer it to the other context. [Transfer behavior](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#transfer) is preserved, which means the value can no longer be used in the sender context once it has been transferred.
 
 ```ts
-// content script
-const port = browser.runtime.connect()
-const background = await expose<BackgroundApi>(contentApi, { transport: port })
-```
+import { transfer } from 'osra'
 
-```ts
-// background
-browser.runtime.onConnect.addListener(port => {
-  expose(backgroundApi, { transport: port })
-})
+const buffer = new ArrayBuffer(16_000_000)
+await remote.transferBuffer(transfer(buffer)) // moved - buffer is detached locally
 ```
 
-If you accept `onConnectExternal`/`onMessageExternal`, filter senders yourself inside a custom `receive` wrapper before invoking osra's listener; `expose()` does not surface the per-message context. The `MessageContext` (with `sender`) reaches only direct users of `registerOsraMessageListener`.
+### Options
 
-### Custom transports
+| Option | Default | Description |
+|---|---|---|
+| `transport` | required | The channel to communicate over (see [Transport modes](#transport-modes)), should be equal to the place where `addEventListener('message')` and `postMessage()` calls target the remote context you want to communicate with |
+| `key` | `'__OSRA_DEFAULT_KEY__'` | Namespacing tag that lets multiple independent osra connections share one channel |
+| `origin` | `'*'` | Similar to [`postMessage`'s `origin`](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage#origin), It restricts the remote origin |
+| `name` | - | Defines the name that will be used for the announcement |
+| `remoteName` | - | Filters any incoming messages that are not equal to the `name` of the remote peer |
+| `unregisterSignal` | - | `AbortSignal` that will tear down the connection when aborted |
+| `uuid` / `remoteUuid` | random / - | Same as `name` and `remoteName`, but automatically generated at announce time |
+| `revivableModules` | - | `defaults => modules` function to add, drop, reorder, or override revivable modules |
+| `connection` | `({ value }) => value` | What one connection resolves to, for the await and for iteration alike (see [Connections](#connections)) |
 
-Any plain object with `emit` and `receive` works. Each may be a platform transport or a function; a function `receive` may return an unsubscribe callback. Set `isJson: true` when the channel can't carry transferables:
+## Connections
 
-```ts
-const channel = new BroadcastChannel('app')
-
-const remote = await expose<PeerApi>(localApi, {
-  transport: {
-    isJson: true,
-    emit: message => channel.postMessage(message),
-    receive: listener => {
-      const handler = (event: MessageEvent) => listener(event.data, {})
-      channel.addEventListener('message', handler)
-      return () => channel.removeEventListener('message', handler)
-    },
-  },
-})
-```
+`expose()` is awaitable and async-iterable. Awaiting gives the first peer, iterating gives every peer as it connects:
 
-Custom transports **must be plain objects**: prototype-based objects (e.g. Node `EventEmitter`s) with `emit` methods are deliberately not detected as custom transports.
+```typescript
+import { expose } from 'osra'
 
-## `identity()`
+type PeerApi = { version: () => string }
 
-`identity(value)` preserves reference identity across the connection: sending the same wrapped value twice revives as the same object on the peer, and when the peer wraps the revived object in `identity()` and sends it back, you receive your original reference (`===`). Without it, every send produces an independent copy, including the return trip: a revived value passed back *bare* arrives as a fresh copy, so the returning side must re-wrap it.
+const api = { log: (line: string) => console.log(line) }
 
-```ts
-import { expose, identity } from 'osra'
+// the first peer to connect
+const remote = await expose<PeerApi>(api, { transport: window })
+await remote.version()
 
-const settings = { theme: 'dark' }
-expose({
-  getSettings: async () => identity(settings),
-  saveSettings: async (saved: typeof settings) => {
-    // when the remote sends back identity(saved): saved === settings
-  },
-}, { transport: worker })
+// every peer, as each one arrives
+for await (const peer of expose<PeerApi>(api, { transport: window })) {
+  console.log('peer connected, running', await peer.version())
+}
 ```
 
-## `transfer()`
-
-`transfer(value)` opts a `Transferable` (`ArrayBuffer`, typed-array views, `ImageBitmap`, `VideoFrame`, `AudioData`, …) into move semantics: ownership transfers to the peer instead of copying. Detachment applies to full-window views only (`byteOffset` 0 spanning the whole buffer): `transfer()` on a subarray view ships a copy of just its window and leaves the sender's buffer intact. On JSON transports it silently degrades to a copy. `ReadableStream`/`WritableStream` are never moved: they are proxied chunk by chunk, so `transfer()` adds nothing for them.
+Each loop is one peer, so a page embedding several iframes serves them all from one `expose()`. Several loops over the same `expose()` each see every peer, and peers that connect before anything iterates are buffered and replayed.
 
-```ts
-import { transfer } from 'osra'
+Pass `connection` to decide what a peer resolves to, which is also how you reach its origin and its per-peer `abort`:
 
-const pixels = new ArrayBuffer(16_000_000)
-await remote.render(transfer(pixels)) // moved - pixels is detached locally
+```typescript
+for await (const peer of expose({}, {
+  transport: window,
+  connection: ({ value, context }) => ({ value, context })
+})) {
+  if (!allowed(peer.context.origin)) peer.context.abort?.()
+}
 ```
 
-## Error handling & lifecycle
+The context holds only what the transport observed, plus `abort`. A window or iframe gives `origin` and `source`; a WebExtension gives `port` and `sender`; a WebSocket gives the socket URL as `origin`; a `MessagePort` or `Worker` observes nothing at all.
 
-- Remote functions that throw reject the caller's promise with the revived error. Built-in classes (`TypeError`, `RangeError`, `SyntaxError`, `ReferenceError`, `EvalError`, `URIError`, `AggregateError`, `DOMException`) revive as instances of the same class; custom `Error` subclasses revive as plain `Error` with `name`, `message`, `stack`, and `cause` preserved.
-- `expose()` rejects when the transport can't both emit and receive (`{ emit }` or `{ receive }` alone is a configuration error), and when a peer sends a malformed `init` payload (the revive error surfaces instead of hanging).
-- Aborting `unregisterSignal`:
-  - the pending `expose()` rejects with the abort reason,
-  - a protocol `close` is sent to every connected peer and per-connection state is disposed,
-  - pending RPC calls reject with `'osra: connection closed'` on **both** sides (the peer receiving `close` rejects its pending calls too),
-  - proxied streams on wire-routed channels (JSON transports) are cancelled/aborted with the same error.
-- An already-aborted `unregisterSignal` short-circuits: nothing starts and `expose()` rejects immediately with the signal's abort reason.
-- Promises and streams riding real transferred `MessagePort`s on structured-clone transports live independently of the connection and survive its closure; wire-routed traffic does not.
-- After aborting, calling `expose()` again on the same transport performs a fresh handshake.
+Wrap a value in `context()` to build it once per connection, so one server can answer each realm differently instead of sharing one object with all of them:
 
-```ts
-const controller = new AbortController()
-const remote = await expose<Api>({}, { transport: worker, unregisterSignal: controller.signal })
+```typescript
+import { expose, context } from 'osra'
 
-const pending = remote.slowCall()
-controller.abort(new Error('shutting down'))
-// pending rejects with 'osra: connection closed'
+expose(context(({ origin }) => ({ read: readFor(origin) })), { transport: window })
 ```
 
-**Trust model**: `key` is a namespacing tag that lets independent connections share one channel; it does not identify peers. `origin` scopes window messaging to a named origin in both directions; set it whenever you talk across origins. Malformed payloads surface as errors rather than hangs, and per-connection port buffers are bounded (2048-message reorder buffer per port, 1024 pending ports, 128 remembered closed ports); flood-resistance hardening beyond these caps is incomplete.
+It runs before your value is sent, so calling `ctx.abort()` inside it refuses that peer outright.
 
 ## Limitations
 
 - **Circular structures throw** a `TypeError` at send time; break the cycle or restructure.
-- **Shared references duplicate**: two fields pointing at the same object arrive as two copies unless wrapped with `identity()`.
-- **Classes/prototypes are not preserved**: class instances are not walked by the serializer; structured-clonable ones cross as prototype-less data, and an instance carrying function-valued own properties silently coerces to `{}` via the unclonable path (the compile-time `Capable` check flags it first). Expose plain objects and functions.
-- **Unclonable values** (`WeakMap`, `WeakSet`, exotic host objects) coerce to `{}` and fail the compile-time check.
-- **One-shot bodies**: sending the same `Request`/`Response`/`ReadableStream` twice fails; the body locks at first send.
-- **Generic functions collapse** in `Remote<T>`: mapped types can't preserve generic signatures.
-- **Multi-peer**: only the first peer's value is accessible through the returned promise.
-- **Everything is async**: sync return values still arrive as `Promise`s.
-
-## TypeScript
-
-`Remote<T>` is what the other side sees: functions become `(...args) => Promise<Awaited<R>>`, containers map recursively, platform objects revive as themselves.
-
-`expose()` validates the value you pass at compile time against `Capable`, the union of everything serializable for the inferred transport (narrower on JSON transports). Failures pinpoint the offending path (for elements of non-tuple arrays the report stops at the array itself; only tuples are indexed element by element):
-
-```ts
-expose({ ok: async () => 1, cache: new WeakMap() }, { transport: worker })
-// type error: Value type must resolve to a Capable, with `cache` identified as the bad field
-```
-
-The published declarations require **TypeScript >= 5.9** with `strict` mode (validated on 5.9 by the documentation build, which type-checks every example against the published types, and on TypeScript 7 by `npm run check-consumer-types`).
-
-## Documentation
-
-- [API reference](./docs/API.md)
-- [Advanced usage](./docs/ADVANCED.md)
-
-## Development
-
-```sh
-npm test                      # build lib + test bundle, run the Playwright matrix (chromium/firefox/webkit)
-npm run test-extension        # web extension suite (needs a headed browser/display)
-npm run check-consumer-types  # validate the published .d.ts as an npm consumer sees it
-```
-
-## License
-
-[MIT](./LICENSE)
+- **Classes/prototypes are not preserved**: Classes and their instances are not preserved, please use plain objects and functions instead.
+- **Synchronous functions become asynchronous**: `() => number` will become `() => Promise<number>`.

package/build/connections/bidirectional.d.ts

@@ -46,10 +46,11 @@ export declare const startBidirectionalConnection: <TModules extends readonly Re
     readonly box: (value: import("../revivables/fallbacks.js").Transferable, _context: import("../index.js").RevivableContext<any>) => import("../revivables/fallbacks.js").Transferable;
     readonly revive: (value: import("../revivables/fallbacks.js").BoxedTransferable, _context: import("../index.js").RevivableContext<any>) => import("../revivables/fallbacks.js").Transferable;
 }, {
-    readonly type: 'blobGuard';
-    readonly isType: (value: unknown) => value is never;
-    readonly box: (value: never, context: import("../index.js").RevivableContext<any>) => Blob;
-    readonly revive: (value: import("../revivables/fallbacks.js").BoxedBlobGuard, _context: import("../index.js").RevivableContext<any>) => Blob;
+    readonly type: 'blob';
+    readonly capableOnly: true;
+    readonly isType: (value: unknown) => value is Blob;
+    readonly box: (value: Blob, context: import("../index.js").RevivableContext<any>) => Blob;
+    readonly revive: (value: import("../revivables/fallbacks.js").BoxedBlob, _context: import("../index.js").RevivableContext<any>) => Blob;
 }, typeof import("../revivables/event-target.js"), {
     readonly type: 'unclonable';
     readonly isType: (value: unknown) => value is never;

package/build/connections/index.d.ts

@@ -2,6 +2,7 @@ import type { DefaultRevivableModules, RevivableModule } from '../revivables/ind
 import type { ConnectionContext as BidirectionalConnectionContext } from './bidirectional.js';
 import type { Capable } from '../types.js';
 import type { ProtocolContext, StartConnectionsOptions } from './utils.js';
+import type { Contextual, Exposed } from './utils.js';
 import * as bidirectional from './bidirectional.js';
 export * from './bidirectional.js';
 export * from './relay.js';
@@ -18,4 +19,4 @@ export type ConnectionMessage<TModules extends readonly RevivableModule[] = Defa
     Messages: (modules: TModules, value: T) => infer R;
 } ? R : never;
 export type ConnectionContext<TModules extends readonly RevivableModule[] = DefaultRevivableModules> = BidirectionalConnectionContext<TModules>;
-export declare const startConnections: <T = unknown, const TModules extends readonly RevivableModule[] = DefaultRevivableModules>(value: Capable<TModules>, { transport: _transport, name, remoteName, key, origin, unregisterSignal, revivableModules: configureRevivableModules, uuid: _uuid, remoteUuid: presetRemoteUuid, }: StartConnectionsOptions<TModules>) => Promise<T>;
+export declare const startConnections: <T = unknown, const TModules extends readonly RevivableModule[] = DefaultRevivableModules, TResult = T>(value: Capable<TModules> | Contextual<Capable<TModules>>, { transport: _transport, name, remoteName, key, origin, unregisterSignal, revivableModules: configureRevivableModules, uuid: _uuid, remoteUuid: presetRemoteUuid, connection: selectConnection, }: StartConnectionsOptions<TModules>) => Exposed<TResult>;

package/build/connections/utils.d.ts

@@ -1,6 +1,6 @@
 import type { Message, MessageVariant, Uuid, Capable, MessageEventMap } from '../types.js';
 import type { DefaultRevivableModules, RevivableModule } from '../revivables/index.js';
-import type { Transport } from '../utils/transport.js';
+import type { Context, Transport } from '../utils/transport.js';
 import type { ConnectionContext } from './index.js';
 import type { TypedEventTarget } from '../utils/typed-event-target.js';
 export declare const normalizeTransport: (transport: Transport) => Transport;
@@ -10,12 +10,17 @@ export declare const normalizeTransport: (transport: Transport) => Transport;
  *  omitted, the defaults are used as-is. */
 export declare const mergeRevivableModules: <TModules extends readonly RevivableModule[] = DefaultRevivableModules>(configure: ((defaults: DefaultRevivableModules) => TModules) | undefined) => TModules;
 export type ProtocolEventMap<TModules extends readonly RevivableModule[] = DefaultRevivableModules> = {
-    message: CustomEvent<Message<TModules>>;
+    message: CustomEvent<{
+        message: Message<TModules>;
+        peer: () => Context;
+    }>;
 };
 export type ProtocolEventTarget<TModules extends readonly RevivableModule[] = DefaultRevivableModules> = TypedEventTarget<ProtocolEventMap<TModules>>;
 export type ProtocolContext<TModules extends readonly RevivableModule[] = DefaultRevivableModules> = {
     transport: Transport;
-    value: Capable<TModules>;
+    /** The exposed value for ONE peer. A factory rather than a value so a server can answer each realm
+     *  differently (scoped resolvers per origin) instead of sharing one object across every connection. */
+    valueFor: (peer: Context) => Capable<TModules>;
     revivableModules: TModules;
     connectionContexts: Map<string, ConnectionContext<TModules>>;
     getUuid: () => Uuid;
@@ -24,8 +29,14 @@ export type ProtocolContext<TModules extends readonly RevivableModule[] = Defaul
      *  the unsolicited announce beacon broadcasts with '*'. */
     sendMessage: (message: MessageVariant, targetOrigin?: string) => void;
     protocolEventTarget: ProtocolEventTarget<TModules>;
-    resolveRemoteValue: (value: Capable<TModules>) => void;
     rejectRemoteValue: (error: unknown) => void;
+    /** reports an established connection: settles the first-connection promise and feeds iteration, so
+     *  a caller sees every realm rather than only the one that happened to connect first */
+    addConnection: (ctx: Context, value: Capable<TModules>) => void;
+    /** tears down one connection: close to the peer, teardown locally, drop it from tracking */
+    abortConnection: (remoteUuid: Uuid) => void;
+    /** true when this uuid was aborted before it was registered, which means refuse the registration */
+    claimPendingAbort: (remoteUuid: Uuid) => boolean;
     createConnectionEventTarget: () => TypedEventTarget<MessageEventMap<TModules>>;
     unregisterSignal?: AbortSignal;
 };
@@ -42,4 +53,75 @@ export type StartConnectionsOptions<TModules extends readonly RevivableModule[]
     revivableModules?: (defaults: DefaultRevivableModules) => TModules;
     uuid?: Uuid;
     remoteUuid?: Uuid;
+    /** Decides what one connection resolves to, for the await and for iteration alike. Omit it and that
+     *  is the peer's value, which is what `expose` has always given back:
+     *
+     *  ```ts
+     *  const remote = await expose(api, { transport })
+     *
+     *  const { value, context } = await expose(api, {
+     *    transport,
+     *    connection: ({ value, context }) => ({ value, context }),
+     *  })
+     *
+     *  for await (const origin of expose(api, {
+     *    transport,
+     *    connection: ({ context }) => context.origin,
+     *  })) { }
+     *  ```
+     *
+     *  It runs per connection, on this side, after the handshake. It cannot change what is sent, and
+     *  nothing it returns crosses the wire. */
+    connection?: (connected: Connected<unknown>) => unknown;
 };
+/** An established connection: the value that realm exposed, and what this side knows about the realm
+ *  it came from. `context` is whatever the transport observed, plus an `abort` that drops this one
+ *  peer. Anything derived from it is the caller's to compute, in the value factory or in
+ *  `connection:`, rather than something to declare up front. */
+export type Connected<TValue> = {
+    value: TValue;
+    context: Context;
+};
+/** The result of `expose`. Awaiting it gives the first peer, iterating it gives every peer as it
+ *  connects, and both hand back the same thing: one shape, read once or read repeatedly.
+ *
+ *  What that shape IS comes from the `connection:` option. Without one it is the peer's value, which
+ *  is what `expose` has always resolved to. With one it is whatever that function returns. */
+export type Exposed<TResult> = Promise<TResult> & AsyncIterable<TResult>;
+export type ConnectionQueue<TRemote> = {
+    push: (connection: Connected<TRemote>) => void;
+    close: () => void;
+    iterate: () => AsyncIterableIterator<Connected<TRemote>>;
+};
+/** @internal protocol plumbing, not part of the public api */
+export declare const createConnectionQueue: <TRemote>() => ConnectionQueue<TRemote>;
+/** The awaited-and-iterable result, with every connection passed through `select` first. The promise
+ *  is DERIVED from the first-connection promise, so it needs its own no-op catch: a fire-and-forget
+ *  `expose(...)` handles the original, and an unhandled derived rejection would still reach the
+ *  console. */
+/** @internal not part of the public api */
+export declare const asExposed: <T, TResult>(first: Promise<Connected<T>>, queue: ConnectionQueue<T>, select: (connected: Connected<T>) => TResult) => Exposed<TResult>;
+/** An exposed value can itself be a function - osra exposes functions as endpoints - so a bare
+ *  `typeof value === 'function'` cannot tell a per-peer factory from a plain function value. The
+ *  marker makes the intent explicit and unambiguous. */
+/** @internal */
+export declare const CONTEXT: unique symbol;
+export type Contextual<TValue> = {
+    [CONTEXT]: (ctx: Context) => TValue;
+};
+/** Build the exposed value once per connection, from that connection's context, rather than sharing
+ *  one value across every realm that connects. It runs BEFORE the value is boxed and sent, which is
+ *  what lets one server answer each realm differently:
+ *
+ *  ```ts
+ *  expose(context(({ origin }) => resolvers(idFor(origin))), { transport })
+ *  ```
+ *
+ *  A wrapper rather than "pass a function", because osra exposes functions as endpoints, so a bare
+ *  `typeof value === 'function'` cannot tell a per-peer factory from a plain function value.
+ *
+ *  What the read side needs is not declared here: `connection:` sees the same context and derives its
+ *  own. */
+export declare const context: <TValue>(make: (ctx: Context) => TValue) => Contextual<TValue>;
+/** @internal */
+export declare const isContextual: <TValue>(value: unknown) => value is Contextual<TValue>;