osra 0.3.2 → 0.4.0

package/build/revivables/abort-signal.d.ts

@@ -1,20 +1,17 @@
 import type { Capable } from '../types';
 import type { RevivableContext, BoxBase as BoxBaseType } from './utils';
-import type { UnderlyingType } from '../utils/type';
 import type { BoxedMessagePort } from './message-port';
 export declare const type: 'abortSignal';
 type AbortMessage = {
     type: 'abort';
     reason?: Capable;
 };
-export type BoxedAbortSignal<T extends AbortSignal = AbortSignal> = BoxBaseType<typeof type> & {
+export type BoxedAbortSignal = BoxBaseType<typeof type> & {
     aborted: boolean;
     reason?: Capable;
     port: BoxedMessagePort<AbortMessage>;
-} & {
-    [UnderlyingType]: T;
 };
 export declare const isType: (value: unknown) => value is AbortSignal;
-export declare const box: <T extends AbortSignal, T2 extends RevivableContext>(value: T, context: T2) => BoxedAbortSignal<T>;
+export declare const box: <T extends AbortSignal, T2 extends RevivableContext>(value: T, context: T2) => BoxedAbortSignal;
 export declare const revive: <T extends BoxedAbortSignal, T2 extends RevivableContext>(value: T, context: T2) => AbortSignal;
 export {};

package/build/revivables/array-buffer.d.ts

@@ -1,12 +1,8 @@
-import type { RevivableContext, UnderlyingType, BoxedBuffer } from './utils';
-import { BoxBase } from './utils';
+import type { RevivableContext } from './utils';
 export declare const type: 'arrayBuffer';
-type BoxedArrayBuffer<T extends ArrayBuffer, T2 extends RevivableContext> = typeof BoxBase & {
-    type: typeof type;
-} & BoxedBuffer<T2> & {
-    [UnderlyingType]: T;
-};
 export declare const isType: (value: unknown) => value is ArrayBuffer;
-export declare const box: <T extends ArrayBuffer, T2 extends RevivableContext>(value: T, context: T2) => BoxedArrayBuffer<T, T2>;
-export declare const revive: <T extends BoxedArrayBuffer<ArrayBuffer, RevivableContext>>(value: T, _context: RevivableContext) => T[UnderlyingType];
-export {};
+export declare const box: <T extends ArrayBuffer, T2 extends RevivableContext>(value: T, context: T2) => {
+    __OSRA_BOX__: 'revivable';
+    type: "arrayBuffer";
+} & import("./utils").BoxedBuffer<T2>;
+export declare const revive: <T extends ReturnType<typeof box>>(value: T, _context: RevivableContext) => ArrayBuffer;

package/build/revivables/bigint.d.ts

@@ -1,14 +1,9 @@
-import type { RevivableContext, UnderlyingType } from './utils';
-import { BoxBase } from './utils';
+import type { RevivableContext } from './utils';
 export declare const type: 'bigint';
-type BoxedBigInt<T extends bigint> = typeof BoxBase & {
-    type: typeof type;
-} & {
+export declare const isType: (value: unknown) => value is bigint;
+export declare const box: <T extends bigint, T2 extends RevivableContext>(value: T, _context: T2) => {
+    __OSRA_BOX__: 'revivable';
+    type: "bigint";
     value: string;
-} & {
-    [UnderlyingType]: T;
 };
-export declare const isType: (value: unknown) => value is bigint;
-export declare const box: <T extends bigint, T2 extends RevivableContext>(value: T, _context: T2) => BoxedBigInt<T>;
-export declare const revive: <T extends BoxedBigInt<bigint>>(value: T, _context: RevivableContext) => T[UnderlyingType];
-export {};
+export declare const revive: <T extends ReturnType<typeof box>>(value: T, _context: RevivableContext) => bigint;

package/build/revivables/blob.d.ts

@@ -0,0 +1,17 @@
+import type { RevivableContext, BoxBase as BoxBaseType } from './utils';
+import type { UnderlyingType } from '../utils/type';
+import type { BoxedPromise } from './promise';
+export declare const type: 'blob';
+export type BoxedBlob<T extends Blob = Blob> = BoxBaseType<typeof type> & {
+    mimeType: string;
+} & {
+    buffer: BoxedPromise<ArrayBuffer>;
+} & {
+    fileName?: string;
+    lastModified?: number;
+} & {
+    [UnderlyingType]: Promise<T>;
+};
+export declare const isType: (value: unknown) => value is Blob;
+export declare const box: <T extends Blob, T2 extends RevivableContext>(value: T, context: T2) => BoxedBlob<T>;
+export declare const revive: <T extends BoxedBlob, T2 extends RevivableContext>(value: T, context: T2) => T[UnderlyingType];

package/build/revivables/error.d.ts

@@ -1,10 +1,12 @@
-import type { RevivableContext } from './utils';
+import type { Capable } from '../types';
+import type { RevivableContext, BoxBase as BoxBaseType } from './utils';
 export declare const type: 'error';
-export declare const isType: (value: unknown) => value is Error;
-export declare const box: <T extends Error, T2 extends RevivableContext>(value: T, _context: T2) => {
-    __OSRA_BOX__: 'revivable';
-    type: "error";
+export type BoxedError = BoxBaseType<typeof type> & {
+    name: string;
     message: string;
     stack: string;
+    cause?: Capable;
 };
-export declare const revive: <T extends ReturnType<typeof box>, T2 extends RevivableContext>(value: T, _context: T2) => Error;
+export declare const isType: (value: unknown) => value is Error;
+export declare const box: <T extends Error, T2 extends RevivableContext>(value: T, context: T2) => BoxedError;
+export declare const revive: <T extends BoxedError, T2 extends RevivableContext>(value: T, context: T2) => Error;

package/build/revivables/event-target.d.ts

@@ -1,29 +1,18 @@
-import type { Capable } from '../types';
-import type { RevivableContext, BoxBase as BoxBaseType, UnderlyingType } from './utils';
-import type { BoxedMessagePort } from './message-port';
+import { type RevivableContext } from './utils';
 export declare const type: 'eventTarget';
-type EventTargetMessage = {
-    kind: 'subscribe';
-    eventType: string;
-} | {
-    kind: 'unsubscribe';
-    eventType: string;
-} | {
-    kind: 'close';
-} | {
-    kind: 'event';
-    eventType: string;
-    bubbles: boolean;
-    cancelable: boolean;
-    composed: boolean;
-    detail?: Capable;
-};
-export type BoxedEventTarget<T extends EventTarget = EventTarget> = BoxBaseType<typeof type> & {
-    port: BoxedMessagePort<EventTargetMessage>;
-} & {
-    [UnderlyingType]: T;
+type ListenerOpts = boolean | {
+    capture?: boolean;
+    once?: boolean;
+    passive?: boolean;
+    signal?: AbortSignal;
 };
 export declare const isType: (value: unknown) => value is EventTarget;
-export declare const box: <T extends EventTarget, T2 extends RevivableContext>(value: T, context: T2) => BoxedEventTarget<T>;
-export declare const revive: <T extends BoxedEventTarget, T2 extends RevivableContext>(value: T, context: T2) => T[UnderlyingType];
+export declare const box: <T extends EventTarget, T2 extends RevivableContext>(value: T, context: T2) => {
+    __OSRA_BOX__: 'revivable';
+    type: "eventTarget";
+    addListener: import("./function").BoxedFunction<(type: string, listener: EventListener, options?: ListenerOpts) => void>;
+    removeListener: import("./function").BoxedFunction<(type: string, listener: EventListener, options?: ListenerOpts) => void>;
+};
+export type BoxedEventTarget = ReturnType<typeof box>;
+export declare const revive: <T extends ReturnType<typeof box>, T2 extends RevivableContext>(value: T, context: T2) => EventTarget;
 export {};

package/build/revivables/event.d.ts

@@ -0,0 +1,15 @@
+import type { Capable } from '../types';
+import type { RevivableContext, BoxBase as BoxBaseType } from './utils';
+export declare const type: 'event';
+/** Boxes Event/CustomEvent only. Subclass-specific fields (MessageEvent.data,
+ *  ErrorEvent.error, ProgressEvent.loaded, etc.) are dropped on the wire. */
+export type BoxedEvent = BoxBaseType<typeof type> & {
+    eventType: string;
+    bubbles: boolean;
+    cancelable: boolean;
+    composed: boolean;
+    detail?: Capable;
+};
+export declare const isType: (value: unknown) => value is Event;
+export declare const box: <T extends Event, T2 extends RevivableContext>(value: T, context: T2) => BoxedEvent;
+export declare const revive: <T extends BoxedEvent, T2 extends RevivableContext>(value: T, context: T2) => Event;

package/build/revivables/fallbacks.d.ts

@@ -0,0 +1,136 @@
+import type { BoxBase as BoxBaseType, RevivableContext } from './utils';
+declare const TYPED_CLONABLE_CTORS: readonly [{
+    new (fileBits: BlobPart[], fileName: string, options?: FilePropertyBag): File;
+    prototype: File;
+}, {
+    new (): FileList;
+    prototype: FileList;
+}, RegExpConstructor, DataViewConstructor, {
+    new (sw: number, sh: number, settings?: ImageDataSettings): ImageData;
+    new (data: ImageDataArray, sw: number, sh?: number, settings?: ImageDataSettings): ImageData;
+    prototype: ImageData;
+}, {
+    new (form?: HTMLFormElement, submitter?: HTMLElement | null): FormData;
+    prototype: FormData;
+}, {
+    new (message?: string, name?: string): DOMException;
+    prototype: DOMException;
+    readonly INDEX_SIZE_ERR: 1;
+    readonly DOMSTRING_SIZE_ERR: 2;
+    readonly HIERARCHY_REQUEST_ERR: 3;
+    readonly WRONG_DOCUMENT_ERR: 4;
+    readonly INVALID_CHARACTER_ERR: 5;
+    readonly NO_DATA_ALLOWED_ERR: 6;
+    readonly NO_MODIFICATION_ALLOWED_ERR: 7;
+    readonly NOT_FOUND_ERR: 8;
+    readonly NOT_SUPPORTED_ERR: 9;
+    readonly INUSE_ATTRIBUTE_ERR: 10;
+    readonly INVALID_STATE_ERR: 11;
+    readonly SYNTAX_ERR: 12;
+    readonly INVALID_MODIFICATION_ERR: 13;
+    readonly NAMESPACE_ERR: 14;
+    readonly INVALID_ACCESS_ERR: 15;
+    readonly VALIDATION_ERR: 16;
+    readonly TYPE_MISMATCH_ERR: 17;
+    readonly SECURITY_ERR: 18;
+    readonly NETWORK_ERR: 19;
+    readonly ABORT_ERR: 20;
+    readonly URL_MISMATCH_ERR: 21;
+    readonly QUOTA_EXCEEDED_ERR: 22;
+    readonly TIMEOUT_ERR: 23;
+    readonly INVALID_NODE_TYPE_ERR: 24;
+    readonly DATA_CLONE_ERR: 25;
+}, {
+    new (init?: string | number[]): DOMMatrix;
+    prototype: DOMMatrix;
+    fromFloat32Array(array32: Float32Array<ArrayBuffer>): DOMMatrix;
+    fromFloat64Array(array64: Float64Array<ArrayBuffer>): DOMMatrix;
+    fromMatrix(other?: DOMMatrixInit): DOMMatrix;
+}, {
+    new (init?: string | number[]): DOMMatrixReadOnly;
+    prototype: DOMMatrixReadOnly;
+    fromFloat32Array(array32: Float32Array<ArrayBuffer>): DOMMatrixReadOnly;
+    fromFloat64Array(array64: Float64Array<ArrayBuffer>): DOMMatrixReadOnly;
+    fromMatrix(other?: DOMMatrixInit): DOMMatrixReadOnly;
+}, {
+    new (x?: number, y?: number, z?: number, w?: number): DOMPoint;
+    prototype: DOMPoint;
+    fromPoint(other?: DOMPointInit): DOMPoint;
+}, {
+    new (x?: number, y?: number, z?: number, w?: number): DOMPointReadOnly;
+    prototype: DOMPointReadOnly;
+    fromPoint(other?: DOMPointInit): DOMPointReadOnly;
+}, {
+    new (p1?: DOMPointInit, p2?: DOMPointInit, p3?: DOMPointInit, p4?: DOMPointInit): DOMQuad;
+    prototype: DOMQuad;
+    fromQuad(other?: DOMQuadInit): DOMQuad;
+    fromRect(other?: DOMRectInit): DOMQuad;
+}, {
+    new (x?: number, y?: number, width?: number, height?: number): DOMRect;
+    prototype: DOMRect;
+    fromRect(other?: DOMRectInit): DOMRect;
+}, {
+    new (x?: number, y?: number, width?: number, height?: number): DOMRectReadOnly;
+    prototype: DOMRectReadOnly;
+    fromRect(other?: DOMRectInit): DOMRectReadOnly;
+}, {
+    new (): CryptoKey;
+    prototype: CryptoKey;
+}, {
+    new (): FileSystemHandle;
+    prototype: FileSystemHandle;
+}, {
+    new (): FileSystemFileHandle;
+    prototype: FileSystemFileHandle;
+}, {
+    new (): FileSystemDirectoryHandle;
+    prototype: FileSystemDirectoryHandle;
+}, {
+    new (): RTCCertificate;
+    prototype: RTCCertificate;
+}];
+export type Clonable = InstanceType<(typeof TYPED_CLONABLE_CTORS)[number]>;
+export type BoxedClonable = BoxBaseType<'clonable'>;
+export declare const clonable: {
+    readonly type: 'clonable';
+    readonly capableOnly: true;
+    readonly isType: (value: unknown) => value is Clonable;
+    readonly box: (value: Clonable, _context: RevivableContext<any>) => Clonable;
+    readonly revive: (value: BoxedClonable, _context: RevivableContext<any>) => Clonable;
+};
+declare const TYPED_TRANSFERABLE_CTORS: readonly [{
+    new (): ImageBitmap;
+    prototype: ImageBitmap;
+}, {
+    new (width: number, height: number): OffscreenCanvas;
+    prototype: OffscreenCanvas;
+}, {
+    new <W = any>(underlyingSink?: UnderlyingSink<W>, strategy?: QueuingStrategy<W>): WritableStream<W>;
+    prototype: WritableStream;
+}, {
+    new <I = any, O = any>(transformer?: Transformer<I, O>, writableStrategy?: QueuingStrategy<I>, readableStrategy?: QueuingStrategy<O>): TransformStream<I, O>;
+    prototype: TransformStream;
+}, {
+    new (): MediaStreamTrack;
+    prototype: MediaStreamTrack;
+}, {
+    new (): RTCDataChannel;
+    prototype: RTCDataChannel;
+}];
+export type Transferable = InstanceType<(typeof TYPED_TRANSFERABLE_CTORS)[number]>;
+export type BoxedTransferable = BoxBaseType<'transferable'>;
+export declare const transferable: {
+    readonly type: 'transferable';
+    readonly capableOnly: true;
+    readonly isType: (value: unknown) => value is Transferable;
+    readonly box: (value: Transferable, _context: RevivableContext<any>) => Transferable;
+    readonly revive: (value: BoxedTransferable, _context: RevivableContext<any>) => Transferable;
+};
+export type BoxedUnclonable = BoxBaseType<'unclonable'>;
+export declare const unclonable: {
+    readonly type: 'unclonable';
+    readonly isType: (value: unknown) => value is never;
+    readonly box: (_value: never, _context: RevivableContext<any>) => BoxedUnclonable;
+    readonly revive: (_value: BoxedUnclonable, _context: RevivableContext<any>) => Record<string, never>;
+};
+export {};

package/build/revivables/function.d.ts

@@ -1,24 +1,11 @@
 import type { Capable } from '../types';
 import type { UnderlyingType, RevivableContext, BoxBase as BoxBaseType } from './utils';
-import type { AnyPort } from './message-port';
+import { type EventPort } from '../utils/event-channel';
 import { BoxedMessagePort } from './message-port';
 export declare const type: 'function';
-type ResultMessage = {
-    __osra_ok__: true;
-    value: Capable;
-} | {
-    __osra_err__: true;
-    error: string;
-};
-type CallMessage = CallContext | {
-    __osra_close__: true;
-};
-/** Call-site payload as received by the callee, after box-side revival: the
- *  return port is now a live AnyPort<ResultMessage> (ProtocolPort on clone,
- *  EventPort on JSON); args are revived. */
-export type CallContext = [AnyPort<ResultMessage>, Capable[]];
+type CallContext = [EventPort<Capable>, Capable[]];
 export type BoxedFunction<T extends (...args: any[]) => any = (...args: any[]) => any> = BoxBaseType<typeof type> & {
-    port: BoxedMessagePort<CallMessage>;
+    port: BoxedMessagePort<CallContext>;
 } & {
     [UnderlyingType]: (...args: Parameters<T>) => Promise<Awaited<ReturnType<T>>>;
 };

package/build/revivables/identity.d.ts

@@ -5,7 +5,6 @@ export declare const type: 'identity';
 export type Messages = {
     type: 'identity-dispose';
     remoteUuid: Uuid;
-    /** id of the identity-wrapped value that was collected */
     id: string;
 };
 export declare const Messages: Messages;
@@ -19,21 +18,16 @@ export type BoxedIdentity<T extends Capable = Capable> = BoxBaseType<typeof type
     inner?: Capable;
     [UnderlyingType]: T;
 };
-/**
- * Wrap a value so that osra preserves its reference identity across the
- * RPC boundary, per connection. Calling identity(X) twice on the same
- * value produces the same wrapper, and both wrapper sends resolve to the
- * same revived reference on the remote side.
- *
- * - Primitives pass through unchanged (there is no identity to preserve).
- * - Already-wrapped values pass through unchanged (idempotent).
- *
- * NOTE: This lies at the type level — the runtime value for object/function
- * inputs is an IdentityWrapper<T>, typed as T so the user's surrounding
- * code stays unchanged. The box-site unwraps it.
- */
+/** Wrap a value so osra preserves reference identity across the RPC
+ *  boundary. Idempotent; primitives pass through unchanged. Lies at the
+ *  type level — runtime value is an IdentityWrapper<T> typed as T. */
 export declare const identity: <T>(value: T) => T;
 export declare const isType: (value: unknown) => value is IdentityWrapper;
 export declare const box: <T extends Capable, TContext extends RevivableContext>(wrapper: IdentityWrapper<T>, context: TContext) => BoxedIdentity<T>;
+/** Identity-box a referenceable value with a caller-supplied inner box,
+ *  bypassing the recursive-box step. Used by revivables (symbol with
+ *  description=undefined) where recursing back through their own box
+ *  would loop into this module again. */
+export declare const boxByReference: <T extends WeakKey, TContext extends RevivableContext>(value: T, innerBox: Capable, context: TContext) => BoxedIdentity;
 export declare const revive: <T extends BoxedIdentity, TContext extends RevivableContext>(value: T, context: TContext) => T[UnderlyingType];
 export {};

package/build/revivables/index.d.ts

@@ -18,7 +18,10 @@ import * as transfer from './transfer';
 import * as map from './map';
 import * as set from './set';
 import * as bigInt from './bigint';
+import * as event from './event';
 import * as eventTarget from './event-target';
+import * as blob from './blob';
+import * as symbol from './symbol';
 export { identity } from './identity';
 export { transfer } from './transfer';
 export * from './utils';
@@ -30,7 +33,24 @@ export type RevivableModule<T extends string = string, T2 = any, T3 extends BoxB
     readonly init?: (context: RevivableContext<any>) => void;
     readonly Messages?: T4;
 };
-export declare const defaultRevivableModules: readonly [typeof transfer, typeof identity, typeof arrayBuffer, typeof date, typeof headers, typeof error, typeof typedArray, typeof promise, typeof func, typeof messagePort, typeof readableStream, typeof abortSignal, typeof response, typeof request, typeof map, typeof set, typeof bigInt, typeof eventTarget];
+export declare const defaultRevivableModules: readonly [typeof transfer, typeof identity, typeof arrayBuffer, typeof date, typeof headers, typeof error, typeof typedArray, typeof blob, typeof promise, typeof func, typeof messagePort, typeof readableStream, typeof abortSignal, typeof response, typeof request, typeof map, typeof set, typeof bigInt, typeof symbol, typeof event, typeof eventTarget, {
+    readonly type: 'clonable';
+    readonly capableOnly: true;
+    readonly isType: (value: unknown) => value is import("./fallbacks").Clonable;
+    readonly box: (value: import("./fallbacks").Clonable, _context: RevivableContext<any>) => import("./fallbacks").Clonable;
+    readonly revive: (value: import("./fallbacks").BoxedClonable, _context: RevivableContext<any>) => import("./fallbacks").Clonable;
+}, {
+    readonly type: 'transferable';
+    readonly capableOnly: true;
+    readonly isType: (value: unknown) => value is import("./fallbacks").Transferable;
+    readonly box: (value: import("./fallbacks").Transferable, _context: RevivableContext<any>) => import("./fallbacks").Transferable;
+    readonly revive: (value: import("./fallbacks").BoxedTransferable, _context: RevivableContext<any>) => import("./fallbacks").Transferable;
+}, {
+    readonly type: 'unclonable';
+    readonly isType: (value: unknown) => value is never;
+    readonly box: (_value: never, _context: RevivableContext<any>) => import("./fallbacks").BoxedUnclonable;
+    readonly revive: (_value: import("./fallbacks").BoxedUnclonable, _context: RevivableContext<any>) => Record<string, never>;
+}];
 export type DefaultRevivableModules = typeof defaultRevivableModules;
 export type DefaultRevivableModule = DefaultRevivableModules[number];
 export declare const box: <T extends Capable, TModules extends readonly RevivableModule[]>(value: T, context: RevivableContext<TModules>) => ReplaceWithBox<T, TModules[number]>;

package/build/revivables/message-port.d.ts

@@ -9,46 +9,21 @@ export type Messages = {
     type: 'message';
     remoteUuid: Uuid;
     data: Capable;
-    /** uuid of the messagePort that the message was sent through */
     portId: Uuid;
 } | {
     type: 'message-port-close';
     remoteUuid: Uuid;
-    /** uuid of the messagePort that closed */
     portId: Uuid;
 };
 export declare const Messages: Messages;
-/** Any port-shape the message-port revivable is happy to accept. Real
- *  MessagePorts (from `new MessageChannel()`) and synthetic EventPorts
- *  (from `new EventChannel()`) both flow through here. Messages can be any
- *  Capable value — message-port boxes/revives as they cross the transport,
- *  and the in-realm side uses pass-by-reference via EventChannel. */
 export type AnyPort<T = Capable> = TypedMessagePort<T> | EventPort<T>;
-export type BoxedMessagePort<T = Capable> = BoxBaseType<typeof type> & (
-/** The origin was a synthetic EventPort — revive must reproduce an
- *  EventPort on the other side so live (non-clonable) Promises/Functions
- *  etc. can flow through by reference. */
-{
+export type BoxedMessagePort<T = Capable> = BoxBaseType<typeof type> & ({
     portId: Uuid;
     synthetic: true;
-}
-/** The origin was a real MessagePort but the transport can't carry
- *  ports (JSON-only) — revive produces a real MessagePort proxy so the
- *  receiver sees it as if it had been transferred. Payloads must be
- *  structured-clonable; live (non-clonable) values nested in a
- *  user-level MessagePort aren't supported in this mode. */
- | {
+} | {
     portId: Uuid;
     synthetic: false;
-}
-/** The origin was a real MessagePort and the transport supports
- *  structured clone — the port is transferred on the wire. When
- *  `autoBox` is true, the revive side wraps it in a `ProtocolPort`
- *  that auto-boxes outgoing / auto-revives incoming payloads so
- *  live values (Promises/Functions) flow through unchanged. When
- *  `autoBox` is absent/false, the receiver gets the raw MessagePort
- *  with structured-clone semantics (used for user-owned ports). */
- | {
+} | {
     port: AnyPort<T>;
     autoBox?: boolean;
 }) & {
@@ -66,16 +41,9 @@ export declare const box: <T, T2 extends RevivableContext = RevivableContext>(va
     autoBox?: boolean;
 }) => BoxedMessagePort<T>;
 export declare const revive: <T extends Capable, T2 extends RevivableContext>(value: BoxedMessagePort<T>, context: T2) => TypedMessagePort<T>;
-/**
- * Factory for revivable-internal channels. Returns a local port used by the
- * revivable and a pre-boxed remote port ready to embed in the revivable's
- * Boxed* structure. The local port auto-boxes/revives on clone transports
- * (via ProtocolPort over a MessageChannel) and passes by reference on JSON
- * transports (via EventChannel → portId routing).
- *
- * Revivables can post live values (Promises/Functions/…) on `localPort`
- * without caring about the transport mode.
- */
+/** Factory for revivable-internal channels. Returns a local port that
+ *  auto-boxes live values regardless of transport, plus a pre-boxed remote
+ *  port the revivable embeds in its Boxed* structure. */
 export declare const createRevivableChannel: <T extends Capable>(context: RevivableContext) => {
     localPort: AnyPort<T>;
     boxedRemote: BoxedMessagePort<T>;

package/build/revivables/symbol.d.ts

@@ -0,0 +1,11 @@
+import type { RevivableContext } from './utils';
+export declare const type: 'symbol';
+export declare const isType: (value: unknown) => value is symbol;
+export declare const box: <T extends symbol, T2 extends RevivableContext>(value: T, context: T2) => {
+    __OSRA_BOX__: 'revivable';
+    type: "symbol";
+    description: string | undefined;
+} | import("./identity").BoxedIdentity<import("..").Capable>;
+export declare const revive: <T extends {
+    description: string | undefined;
+}, T2 extends RevivableContext>(value: T, _context: T2) => symbol;

package/build/revivables/transfer.d.ts

@@ -11,25 +11,10 @@ export type BoxedTransfer<T extends Capable = Capable> = BoxBaseType<typeof type
     degraded: boolean;
     [UnderlyingType]: T;
 };
-/**
- * Opt into transfer semantics for a transferable value. Without this wrapper
- * osra sends transferables as structured clones (copies) — the sender-side
- * reference stays usable after the RPC. Wrapping hands the underlying storage
- * off to the receiver and neuters the sender-side reference, matching what
- * you'd get by listing it in the transfer list of `postMessage(msg, [buf])`.
- *
- * - Primitives, null, undefined, plain objects, Promises, Dates, etc. are
- *   returned unchanged.
- * - Typed array views (`Uint8Array`, `DataView`, …) are accepted as a
- *   convenience — their underlying `.buffer` is what actually gets moved.
- * - `transfer(transfer(x))` returns the same wrapper as `transfer(x)`.
- * - If the current platform cannot transfer the given type, the wrapper
- *   silently degrades to a copy — nothing throws.
- *
- * NOTE: This lies at the type level — the runtime value for transferable
- * inputs is a TransferWrapper<T>, typed as T so the user's surrounding
- * code stays unchanged. The box-site unwraps it.
- */
+/** Opt into transfer (move) semantics for a transferable value. Idempotent;
+ *  non-transferable inputs pass through unchanged. Silently degrades to a
+ *  copy when the platform/transport can't transfer the given type. Lies at
+ *  the type level — runtime value is a TransferWrapper<T> typed as T. */
 export declare const transfer: <T>(value: T) => T;
 export declare const isType: (value: unknown) => value is TransferWrapper;
 export declare const box: <T extends Capable, TContext extends RevivableContext>(wrapper: TransferWrapper<T>, context: TContext) => BoxedTransfer<T>;

package/build/revivables/utils.d.ts

@@ -20,7 +20,14 @@ export type RevivableContext<TModules extends readonly RevivableModule[] = Defau
     revivableModules: TModules;
     eventTarget: MessageEventTarget<TModules>;
 };
-export type ExtractType<T> = T extends {
+/** Extract the type a module's `isType` narrows to. Modules marked
+ *  `capableOnly: true` (clonable, transferable) contribute `never` on JSON
+ *  transports so users can't type values JSON would silently drop. */
+export type ExtractType<T, Ctx extends RevivableContext = RevivableContext> = T extends {
+    capableOnly: true;
+} ? IsJsonOnlyTransport<Ctx['transport']> extends true ? never : T extends {
+    isType: (value: unknown) => value is infer S;
+} ? S : never : T extends {
     isType: (value: unknown) => value is infer S;
 } ? S : never;
 export type ExtractBox<T> = T extends {
@@ -32,16 +39,11 @@ export type ExtractMessages<T> = T extends {
     type: string;
 } ? string extends B['type'] ? never : B : never : never;
 export type InferMessages<TModules extends readonly unknown[]> = ExtractMessages<TModules[number]>;
-export type InferRevivables<TModules extends readonly unknown[]> = ExtractType<TModules[number]>;
+export type InferRevivables<TModules extends readonly unknown[], Ctx extends RevivableContext = RevivableContext> = ExtractType<TModules[number], Ctx>;
 export type InferRevivableBox<TModules extends readonly unknown[]> = ExtractBox<TModules[number]>;
 export declare const isRevivableBox: (value: unknown) => value is BoxBase;
-/** Stable string form for an unknown rejection value. Errors keep their stack;
- *  everything else gets coerced via `String()`. Used wherever a Promise/Function
- *  rejection has to cross the wire as a serialisable string. */
 export declare const serializeError: (error: unknown) => string;
-/** Wire shape for an ArrayBuffer carried by a JSON or clone transport. JSON
- *  paths emit a base64 string (so the buffer survives JSON.stringify); clone
- *  paths pass the buffer through structured-clone unchanged. */
+/** Wire shape for an ArrayBuffer: base64 on JSON, raw on clone. */
 export type BoxedBuffer<TCtx extends RevivableContext = RevivableContext> = IsJsonOnlyTransport<TCtx['transport']> extends true ? {
     base64Buffer: string;
 } : IsJsonOnlyTransport<TCtx['transport']> extends false ? {

package/build/types.d.ts

@@ -1,6 +1,7 @@
 import type { ConnectionMessage } from './connections';
 import type { TypedEventTarget } from './utils';
-import type { DefaultRevivableModules, RevivableModule, InferMessages, InferRevivables } from './revivables';
+import type { IsJsonOnlyTransport } from './utils/type-guards';
+import type { DefaultRevivableModules, RevivableModule, InferMessages, InferRevivables, RevivableContext } from './revivables';
 export declare const OSRA_KEY: '__OSRA_KEY__';
 export declare const OSRA_DEFAULT_KEY: '__OSRA_DEFAULT_KEY__';
 export declare const OSRA_BOX: '__OSRA_BOX__';
@@ -16,9 +17,14 @@ export type Structurable = Jsonable
 export type StructurableTransferable = Structurable | Transferable | {
     [key: string]: StructurableTransferable;
 } | Array<StructurableTransferable> | Map<StructurableTransferable, StructurableTransferable> | Set<StructurableTransferable>;
-export type Capable<TModules extends readonly RevivableModule[] = DefaultRevivableModules> = StructurableTransferable | InferRevivables<TModules> | {
-    [key: string]: Capable<TModules>;
-} | Array<Capable<TModules>> | Map<Capable<TModules>, Capable<TModules>> | Set<Capable<TModules>>;
+/** "Free" types in `Capable` — narrows to `Jsonable` on JSON transports so
+ *  user code can't type a `Date`/`Blob`/etc. that JSON would silently coerce.
+ *  Modules that DO support JSON (date, map, set, bigint, …) put their type
+ *  back via `InferRevivables`. */
+type CapableBase<Ctx extends RevivableContext> = IsJsonOnlyTransport<Ctx['transport']> extends true ? Jsonable | undefined | void : StructurableTransferable;
+export type Capable<TModules extends readonly RevivableModule[] = DefaultRevivableModules, Ctx extends RevivableContext = RevivableContext> = CapableBase<Ctx> | InferRevivables<TModules, Ctx> | {
+    [key: string]: Capable<TModules, Ctx>;
+} | Array<Capable<TModules, Ctx>> | Map<Capable<TModules, Ctx>, Capable<TModules, Ctx>> | Set<Capable<TModules, Ctx>>;
 export type MessageFields = {
     type: string;
     remoteUuid: Uuid;
@@ -31,7 +37,6 @@ export type MessageBase = {
 };
 export type ProtocolMessage = {
     type: 'announce';
-    /** Only set when acknowledging a remote announcement */
     remoteUuid?: Uuid;
 } | {
     type: 'close';
@@ -43,3 +48,4 @@ export type MessageEventMap<TModules extends readonly RevivableModule[] = Defaul
     message: CustomEvent<Message<TModules>>;
 };
 export type MessageEventTarget<TModules extends readonly RevivableModule[] = DefaultRevivableModules> = TypedEventTarget<MessageEventMap<TModules>>;
+export {};

package/build/utils/gc-tracker.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Run `cleanup` after `target` is garbage-collected. Returns a handle to
+ * cancel the tracking before that happens.
+ *
+ * Backed by a single shared FinalizationRegistry — every revivable that
+ * needs FR semantics goes through this so the boilerplate (token,
+ * unregister, cycle-safety contract) lives in one place.
+ *
+ * Contract: `cleanup` MUST NOT (transitively) reference `target`. The
+ * registry strong-holds the cleanup callback, the cleanup would then
+ * strong-hold target, and the engine would never see target as
+ * collectable. Use a `WeakRef` if cleanup needs something that points
+ * back at target.
+ *
+ * Errors thrown from cleanup are swallowed: the callback fires from the
+ * FR thread, where there's no caller to surface them to.
+ */
+export type GcUnregister = () => void;
+export declare const trackGc: (target: WeakKey, cleanup: () => void) => GcUnregister;

package/build/utils/index.d.ts

@@ -9,3 +9,4 @@ export * from './typed-message-channel';
 export * from './event-channel';
 export * from './type';
 export * from './capable-check';
+export * from './gc-tracker';