osra 0.6.2 → 0.6.3

package/README.md

@@ -3,14 +3,14 @@
 [![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)
 
-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 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.
+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.
 
 ## Features
 
-- **Zero runtime dependencies**: one ESM module
+- **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**: the same value types work over text-only transports (WebSocket, extension messaging); `Date`, `Map`, typed arrays, even `NaN`/`±Infinity` survive
+- **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
@@ -25,8 +25,6 @@ npm install osra
 
 ```ts
 // worker.ts
-import type { Transport } from 'osra'
-
 import { expose } from 'osra'
 
 const api = {
@@ -42,7 +40,7 @@ const api = {
 
 export type Api = typeof api
 
-expose(api, { transport: globalThis as unknown as Transport })
+expose(api, { transport: globalThis })
 ```
 
 ```ts
@@ -73,12 +71,12 @@ Both sides call `expose()`; the returned promise resolves with the remote side's
 | 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. **Not authentication.** |
-| `origin` | `'*'` | On window transports: sets the outbound `postMessage` target origin **and** filters inbound messages by `event.origin` |
+| `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 type-handling modules |
+| `revivableModules` | - | `defaults => modules` function to add, drop, reorder, or override revivable modules |
 
 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.
 
@@ -91,17 +89,17 @@ Transports are either **structured-clone** (Worker, Window, MessagePort, SharedW
 | JSON primitives, plain objects, arrays | ✅ | ✅ | |
 | `undefined`, `NaN`, `±Infinity` | ✅ | ✅ | preserved even over JSON |
 | `Date`, `BigInt`, `Map`, `Set` | ✅ | ✅ | |
-| Typed arrays, `ArrayBuffer` | ✅ | ✅ | subarray views keep `byteOffset`/`length` |
-| `Error` + subclasses | ✅ | ✅ | `TypeError`, `RangeError`, `AggregateError` (nested errors), `DOMException`, … with `cause` and `stack` |
+| 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 |
 | `RegExp` | ✅ | ❌ | |
 | `SharedArrayBuffer` | ✅ | ❌ | shared memory across the contexts |
 | Function | ✅ | ✅ | becomes `(...args) => Promise<result>`; arguments and results recurse through the same boxing |
 | `Promise` | ✅ | ✅ | |
 | Async generators / async iterables | ✅ | ✅ | `next`/`return`/`throw` proxied; `for await` works; early `break` runs the source's `finally` |
-| `ReadableStream` | ✅ | ✅ | pull-based backpressure; cancel reason crosses |
-| `WritableStream` | ✅ | ✅ | write/close/abort with acks; sink errors reject the writer |
-| `MessagePort` | ✅ | ✅ | revives as a real `MessagePort` on both transport kinds |
+| `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()` |
@@ -116,11 +114,11 @@ Transports are either **structured-clone** (Worker, Window, MessagePort, SharedW
 
 ### Worker
 
-Pass the `Worker` on the page side and `globalThis` (the `DedicatedWorkerGlobalScope`) inside the worker; see [Quick Start](#quick-start). The worker scope is detected at runtime but isn't part of the `Transport` type union, so cast it: `globalThis as unknown as Transport`.
+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
 
-`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:
+`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.
 
 ```ts
 // parent
@@ -182,7 +180,7 @@ const remote = await expose<SwApi>(pageApi, {
 
 ### Web extension
 
-JSON mode. `runtime.Port`, the runtime itself (`sendMessage`/`onMessage`), `onConnect`, and `onMessage` are all accepted:
+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.
 
 ```ts
 // content script
@@ -197,7 +195,7 @@ browser.runtime.onConnect.addListener(port => {
 })
 ```
 
-If you accept `onConnectExternal`/`onMessageExternal`, validate senders yourself; the `MessageContext` passed to custom receive listeners exposes `sender`.
+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`.
 
 ### Custom transports
 
@@ -239,7 +237,7 @@ expose({
 
 ## `transfer()`
 
-`transfer(value)` opts a `Transferable` (`ArrayBuffer`, `MessagePort`, streams, `ImageBitmap`, `OffscreenCanvas`, …) into move semantics: ownership transfers to the peer instead of copying. On JSON transports it silently degrades to a copy.
+`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.
 
 ```ts
 import { transfer } from 'osra'
@@ -250,13 +248,14 @@ await remote.render(transfer(pixels)) // moved - pixels is detached locally
 
 ## Error handling & lifecycle
 
-- Remote functions that throw reject the caller's promise with the revived error, subclass and 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.
 
@@ -269,13 +268,13 @@ controller.abort(new Error('shutting down'))
 // pending rejects with 'osra: connection closed'
 ```
 
-**Trust model**: `key` is namespacing, not authentication. `origin` filters window messages in both directions; set it whenever you talk across origins. Treat peers as semi-trusted: malformed payloads are handled, but DoS-hardening against hostile peers is not complete.
+**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.
 
 ## 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**: values cross as plain data; a class instance's methods are not proxied. Expose plain objects and functions.
+- **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.
@@ -286,14 +285,14 @@ controller.abort(new Error('shutting down'))
 
 `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:
+`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.
+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
 

package/build/index.js

@@ -251,7 +251,9 @@ var de = (e) => {
 	globalThis.WritableStream,
 	globalThis.TransformStream,
 	globalThis.ImageBitmap,
-	globalThis.OffscreenCanvas
+	globalThis.OffscreenCanvas,
+	globalThis.VideoFrame,
+	globalThis.AudioData
 ]) : !1, Ze = (e) => Xe(e) ? {
 	[qe]: !0,
 	value: e
@@ -1525,7 +1527,7 @@ var de = (e) => {
 		createConnectionEventTarget: Er,
 		unregisterSignal: c
 	};
-	l({
+	if (l({
 		listener: (e, t) => {
 			e.uuid !== v && x.dispatchEvent(new CustomEvent("message", { detail: e }));
 		},
@@ -1534,7 +1536,8 @@ var de = (e) => {
 		key: o,
 		origin: s,
 		unregisterSignal: c
-	}), c?.addEventListener("abort", () => {
+	}), c?.aborted) return _(c.reason), g;
+	c?.addEventListener("abort", () => {
 		for (let [e, t] of h) y({
 			type: "close",
 			remoteUuid: e