electron-effect-rpc 0.8.0 → 0.10.0

package/dist/renderer.js

@@ -1,7 +1,8 @@
-import * as S from "@effect/schema/Schema";
-import { Cause, Effect, Exit, Stream } from "effect";
+import * as S from "effect/Schema";
+import { Cause, Effect, Exit, Queue, Result, Stream } from "effect";
+import { isRecord, toDiagnosticCause, } from "./boundary.js";
 import { exitSchemaFor, isNoErrorSchema, } from "./contract.js";
-import { extractStreamIdFromRaw, formatUnknown, isRecord, parseRpcResponseEnvelope, parseStreamFrame, safelyCall, } from "./protocol.js";
+import { extractStreamIdFromRaw, formatUnknown, parseRpcResponseEnvelope, parseStreamFrame, safelyCall, } from "./protocol.js";
 import { RpcDefectError, } from "./types.js";
 function requireInvoke(options) {
     if (!options?.invoke) {
@@ -15,6 +16,9 @@ function requireSubscribe(options) {
     }
     return options.subscribe;
 }
+function emptyRpcClient() {
+    return Object.create(null);
+}
 function rpcDefect(code, message, cause) {
     return new RpcDefectError(code, message, cause);
 }
@@ -32,13 +36,13 @@ function decodeLegacyExit(method, raw) {
         if (Exit.isSuccess(exit)) {
             return Effect.succeed(exit.value);
         }
-        const failureOption = Cause.failureOption(exit.cause);
+        const failureOption = Cause.findErrorOption(exit.cause);
         if (failureOption._tag === "Some") {
             return Effect.fail(failureOption.value);
         }
-        const defectOption = Cause.dieOption(exit.cause);
-        if (defectOption._tag === "Some") {
-            const defect = defectOption.value;
+        const defectResult = Cause.findDefect(exit.cause);
+        if (Result.isSuccess(defectResult)) {
+            const defect = defectResult.success;
             const message = defect instanceof Error ? defect.message : String(defect);
             return Effect.fail(rpcDefect("remote_defect", message, defect));
         }
@@ -59,7 +63,7 @@ export function createRpcClient(contract, options) {
                             scope: "rpc-response",
                             name: method.name,
                             payload: envelope.data,
-                            cause,
+                            cause: toDiagnosticCause(cause),
                         });
                         return rpcDefect("success_payload_decoding_failed", `RPC ${method.name} success payload decoding failed: ${formatUnknown(cause)}`, cause);
                     },
@@ -75,7 +79,7 @@ export function createRpcClient(contract, options) {
                             scope: "rpc-response",
                             name: method.name,
                             payload: envelope.error,
-                            cause,
+                            cause: toDiagnosticCause(cause),
                         });
                         return rpcDefect("failure_payload_decoding_failed", `RPC ${method.name} failure payload decoding failed: ${formatUnknown(cause)}`, cause);
                     },
@@ -90,8 +94,8 @@ export function createRpcClient(contract, options) {
             safelyCall(diagnostics?.onDecodeFailure, {
                 scope: "rpc-request",
                 name: method.name,
-                payload: input,
-                cause,
+                payload: toDiagnosticCause(input),
+                cause: toDiagnosticCause(cause),
             });
             return rpcDefect("request_encoding_failed", `RPC ${method.name} request encoding failed: ${formatUnknown(cause)}`, cause);
         },
@@ -101,7 +105,7 @@ export function createRpcClient(contract, options) {
             safelyCall(diagnostics?.onProtocolError, {
                 method: method.name,
                 response: undefined,
-                cause,
+                cause: toDiagnosticCause(cause),
             });
             return rpcDefect("invoke_failed", `RPC ${method.name} invoke failed: ${formatUnknown(cause)}`, cause);
         },
@@ -116,7 +120,7 @@ export function createRpcClient(contract, options) {
                     return Effect.sync(() => safelyCall(diagnostics?.onProtocolError, {
                         method: method.name,
                         response: raw,
-                        cause,
+                        cause: toDiagnosticCause(cause),
                     }));
                 }
                 return Effect.void;
@@ -126,18 +130,17 @@ export function createRpcClient(contract, options) {
         safelyCall(diagnostics?.onProtocolError, {
             method: method.name,
             response: raw,
-            cause,
+            cause: toDiagnosticCause(cause),
         });
         return Effect.fail(cause);
     }));
-    const client = Object.create(null);
-    const clientRecord = client;
+    const client = emptyRpcClient();
     for (const method of contract.methods) {
         const caller = (...args) => {
             const payload = args.length === 0 ? {} : args[0];
             return call(method, payload);
         };
-        clientRecord[method.name] = caller;
+        Object.assign(client, { [method.name]: caller });
     }
     return client;
 }
@@ -176,13 +179,16 @@ export function createEventSubscriber(contract, options) {
                 decoded = decoder(payload);
             }
             catch (cause) {
-                reportDecodeFailure(mode, event.name, payload, cause, options);
+                reportDecodeFailure(mode, event.name, payload, toDiagnosticCause(cause), options);
                 return;
             }
             handler(decoded);
         });
         return registerUnsubscribe(unsubscribe);
     };
+    const streamEvent = (event) => Stream.callback((queue) => Effect.acquireRelease(Effect.sync(() => subscribeEvent(event, (payload) => {
+        Queue.offerUnsafe(queue, payload);
+    })), (unsubscribe) => Effect.sync(unsubscribe)));
     const subscribeByName = (name, handler) => {
         const event = eventMap.get(name);
         if (!event) {
@@ -195,7 +201,7 @@ export function createEventSubscriber(contract, options) {
                 decoded = decoder(payload);
             }
             catch (cause) {
-                reportDecodeFailure(mode, name, payload, cause, options);
+                reportDecodeFailure(mode, name, payload, toDiagnosticCause(cause), options);
                 return;
             }
             handler(decoded);
@@ -220,6 +226,7 @@ export function createEventSubscriber(contract, options) {
     return {
         subscribe: subscribeEvent,
         subscribeByName,
+        stream: streamEvent,
         dispose,
     };
 }
@@ -237,6 +244,15 @@ export function createStreamRpcClient(contract, options) {
     const diagnostics = options.diagnostics;
     const streamBuffer = options.streamBuffer ?? { bufferSize: "unbounded" };
     const frameDispatcher = new Map();
+    const recentlyClosedStreams = new Map();
+    const rememberRecentlyClosed = (streamId, report) => {
+        recentlyClosedStreams.set(streamId, report);
+        queueMicrotask(() => {
+            if (recentlyClosedStreams.get(streamId) === report) {
+                recentlyClosedStreams.delete(streamId);
+            }
+        });
+    };
     // Set up central frame listener
     const centralCleanup = onStreamFrame((raw) => {
         const frame = parseStreamFrame(raw);
@@ -258,8 +274,14 @@ export function createStreamRpcClient(contract, options) {
             return;
         }
         const handler = frameDispatcher.get(frame.streamId);
-        if (!handler)
-            return; // stale frame for completed/cancelled stream
+        if (!handler) {
+            const report = recentlyClosedStreams.get(frame.streamId);
+            if (report) {
+                recentlyClosedStreams.delete(frame.streamId);
+                report(raw);
+            }
+            return;
+        }
         switch (frame.type) {
             case "data":
                 handler.data(frame.payload);
@@ -273,105 +295,152 @@ export function createStreamRpcClient(contract, options) {
                 frameDispatcher.delete(frame.streamId);
                 break;
             case "defect":
-                handler.defect(frame.message);
+                handler.defect(frame.message, true);
                 frameDispatcher.delete(frame.streamId);
                 break;
         }
     });
     const streamMethods = contract.streamMethods ?? [];
-    const client = Object.create(null);
-    const clientRecord = client;
+    const callbackOptions = streamBuffer.bufferSize === "unbounded"
+        ? undefined
+        : { bufferSize: streamBuffer.bufferSize, strategy: streamBuffer.strategy };
+    function emptyStreamRpcClient() {
+        return Object.create(null);
+    }
+    const client = emptyStreamRpcClient();
     for (const method of streamMethods) {
         const decodeChunk = S.decodeUnknownSync(method.chunk);
         const encodeInput = S.encodeSync(method.req);
         const decodeTypedError = isNoErrorSchema(method.err) ? null : S.decodeUnknownSync(method.err);
         const caller = (...args) => {
             const payload = args.length === 0 ? {} : args[0];
-            return Stream.asyncPush((emit) => Effect.gen(function* () {
-                const streamId = crypto.randomUUID();
-                // 1. Register in dispatch map BEFORE calling invoke
-                frameDispatcher.set(streamId, {
-                    data: (rawPayload) => {
-                        let decoded;
-                        try {
-                            decoded = decodeChunk(rawPayload);
-                        }
-                        catch (cause) {
-                            const context = {
-                                scope: "stream-chunk",
-                                name: method.name,
-                                payload: rawPayload,
-                                cause,
-                            };
-                            safelyCall(diagnostics?.onDecodeFailure, context);
-                            emit.fail(rpcDefect("stream_chunk_decode_failed", `Stream ${method.name} chunk decode failed: ${formatUnknown(cause)}`, cause));
-                            return;
-                        }
-                        // `emit.single(...) === false` indicates a closed emitter, not
-                        // bounded-buffer overflow.
-                        const accepted = emit.single(decoded);
-                        if (!accepted) {
-                            // Stream has already finished. Remove dispatcher entry on the
-                            // first post-close frame to avoid repeated diagnostics.
-                            frameDispatcher.delete(streamId);
-                            safelyCall(diagnostics?.onProtocolError, {
-                                method: method.name,
-                                response: rawPayload,
-                                cause: new Error(`Stream ${method.name} received a post-close data frame; frame ignored`),
-                            });
-                        }
-                    },
-                    end: () => emit.end(),
-                    error: (err) => {
-                        if (!decodeTypedError) {
-                            emit.fail(rpcDefect("stream_error_decode_failed", `Stream ${method.name} received typed error but declares NoError`, err));
-                            return;
-                        }
-                        try {
-                            const decoded = decodeNonEmptyError(method.err, err.data);
-                            emit.fail(decoded);
-                        }
-                        catch (cause) {
-                            const errContext = {
-                                scope: "stream-error",
-                                name: method.name,
-                                payload: err,
-                                cause,
-                            };
-                            safelyCall(diagnostics?.onDecodeFailure, errContext);
-                            emit.fail(rpcDefect("stream_error_decode_failed", `Stream ${method.name} error decode failed: ${formatUnknown(cause)}`, cause));
+            return Stream.callback((queue) => {
+                let queueClosed = false;
+                let postCloseReported = false;
+                const reportPostClose = (response) => {
+                    if (postCloseReported)
+                        return;
+                    postCloseReported = true;
+                    safelyCall(diagnostics?.onProtocolError, {
+                        method: method.name,
+                        response,
+                        cause: new Error(`Stream ${method.name} received a post-close data frame; frame ignored`),
+                    });
+                };
+                const failQueue = (error) => {
+                    if (queueClosed)
+                        return;
+                    queueClosed = true;
+                    Queue.failCauseUnsafe(queue, Cause.fail(error));
+                };
+                const endQueue = () => {
+                    if (queueClosed)
+                        return;
+                    queueClosed = true;
+                    Queue.endUnsafe(queue);
+                };
+                return Effect.gen(function* () {
+                    const streamId = crypto.randomUUID();
+                    // Once main has sent a terminal frame (end/error/defect) there is
+                    // nothing left to cancel; the finalizer skips the cancel invoke.
+                    let serverTerminated = false;
+                    // 1. Register in dispatch map BEFORE calling invoke
+                    frameDispatcher.set(streamId, {
+                        data: (rawPayload) => {
+                            let decoded;
+                            try {
+                                decoded = decodeChunk(rawPayload);
+                            }
+                            catch (cause) {
+                                const context = {
+                                    scope: "stream-chunk",
+                                    name: method.name,
+                                    payload: rawPayload,
+                                    cause: toDiagnosticCause(cause),
+                                };
+                                safelyCall(diagnostics?.onDecodeFailure, context);
+                                failQueue(rpcDefect("stream_chunk_decode_failed", `Stream ${method.name} chunk decode failed: ${formatUnknown(cause)}`, toDiagnosticCause(cause)));
+                                return;
+                            }
+                            const accepted = !queueClosed && Queue.offerUnsafe(queue, decoded);
+                            if (!accepted && (queueClosed || queue.state._tag !== "Open")) {
+                                // Stream has already finished. Remove dispatcher entry on the
+                                // first post-close frame to avoid repeated diagnostics.
+                                frameDispatcher.delete(streamId);
+                                reportPostClose(rawPayload);
+                            }
+                        },
+                        end: () => {
+                            serverTerminated = true;
+                            endQueue();
+                        },
+                        error: (err) => {
+                            serverTerminated = true;
+                            if (!decodeTypedError) {
+                                failQueue(rpcDefect("stream_error_decode_failed", `Stream ${method.name} received typed error but declares NoError`, err));
+                                return;
+                            }
+                            try {
+                                const decoded = decodeNonEmptyError(method.err, err.data);
+                                failQueue(decoded);
+                            }
+                            catch (cause) {
+                                const errContext = {
+                                    scope: "stream-error",
+                                    name: method.name,
+                                    payload: err,
+                                    cause: toDiagnosticCause(cause),
+                                };
+                                safelyCall(diagnostics?.onDecodeFailure, errContext);
+                                failQueue(rpcDefect("stream_error_decode_failed", `Stream ${method.name} error decode failed: ${formatUnknown(cause)}`, toDiagnosticCause(cause)));
+                            }
+                        },
+                        defect: (message, fromServer = false) => {
+                            if (fromServer) {
+                                serverTerminated = true;
+                            }
+                            failQueue(rpcDefect("remote_defect", message, undefined));
+                        },
+                    });
+                    // 2. Register cleanup finalizer
+                    yield* Effect.addFinalizer(() => Effect.sync(() => {
+                        frameDispatcher.delete(streamId);
+                        if (queueClosed && !postCloseReported) {
+                            rememberRecentlyClosed(streamId, reportPostClose);
                         }
-                    },
-                    defect: (message) => emit.fail(rpcDefect("remote_defect", message, undefined)),
-                });
-                // 2. Register cleanup finalizer
-                yield* Effect.addFinalizer(() => Effect.sync(() => {
-                    frameDispatcher.delete(streamId);
-                }).pipe(Effect.andThen(Effect.tryPromise(() => invoke(`stream-cancel`, { streamId })).pipe(Effect.ignore))));
-                // 3. Encode input
-                const encodedInput = yield* Effect.try({
-                    try: () => encodeInput(payload),
-                    catch: (cause) => rpcDefect("request_encoding_failed", `Stream ${method.name} request encoding failed: ${formatUnknown(cause)}`, cause),
-                });
-                // 4. Initiate the stream on main
-                const response = yield* Effect.tryPromise({
-                    try: () => invoke(`stream/${method.name}`, {
-                        data: encodedInput,
-                        streamId,
-                    }),
-                    catch: (cause) => rpcDefect("stream_invoke_failed", `Stream ${method.name} invoke failed: ${formatUnknown(cause)}`, cause),
-                });
-                // 5. Validate handshake response
-                const envelope = parseRpcResponseEnvelope(response);
-                if (envelope?.type === "defect") {
-                    return yield* Effect.fail(rpcDefect("remote_defect", envelope.message, envelope.cause));
-                }
-                if (!isStreamStartedResponse(response)) {
-                    return yield* Effect.fail(rpcDefect("stream_handshake_invalid", `Stream ${method.name} unexpected handshake response`, response));
-                }
-            }), streamBuffer);
+                    }).pipe(Effect.andThen(Effect.suspend(() => serverTerminated
+                        ? Effect.void
+                        : Effect.tryPromise(() => invoke(`stream-cancel`, { streamId })).pipe(Effect.ignore)))));
+                    // 3. Encode input
+                    const encodedInput = yield* Effect.try({
+                        try: () => encodeInput(payload),
+                        catch: (cause) => rpcDefect("request_encoding_failed", `Stream ${method.name} request encoding failed: ${formatUnknown(cause)}`, cause),
+                    });
+                    // 4. Initiate the stream on main
+                    const response = yield* Effect.tryPromise({
+                        try: () => invoke(`stream/${method.name}`, {
+                            data: encodedInput,
+                            streamId,
+                        }),
+                        catch: (cause) => rpcDefect("stream_invoke_failed", `Stream ${method.name} invoke failed: ${formatUnknown(cause)}`, cause),
+                    });
+                    // 5. Validate handshake response
+                    const envelope = parseRpcResponseEnvelope(response);
+                    if (envelope?.type === "defect") {
+                        return yield* Effect.fail(rpcDefect("remote_defect", envelope.message, envelope.cause));
+                    }
+                    if (!isStreamStartedResponse(response)) {
+                        return yield* Effect.fail(rpcDefect("stream_handshake_invalid", `Stream ${method.name} unexpected handshake response`, response));
+                    }
+                }).pipe(Effect.catchCause((cause) => Effect.sync(() => {
+                    if (queueClosed)
+                        return;
+                    queueClosed = true;
+                    Queue.failCauseUnsafe(queue, cause);
+                })));
+            }, callbackOptions);
         };
-        clientRecord[method.name] = caller;
+        Object.assign(client, { [method.name]: caller });
     }
     function dispose() {
         // Fail all active streams so consumers don't hang
@@ -379,6 +448,7 @@ export function createStreamRpcClient(contract, options) {
             handler.defect("Stream client disposed");
             frameDispatcher.delete(streamId);
         }
+        recentlyClosedStreams.clear();
         centralCleanup();
     }
     return {

package/dist/testing.d.ts

@@ -1,15 +1,16 @@
+import type { IpcEncodedValue } from "./boundary.ts";
 import type { RpcInvoke } from "./types.ts";
 export type Invocation = {
     readonly method: string;
-    readonly payload: unknown;
+    readonly payload: IpcEncodedValue;
 };
 export type InvokeStub = RpcInvoke & {
     readonly invocations: Invocation[];
 };
 export declare const createInvokeStub: (impl: RpcInvoke) => InvokeStub;
-export declare const createDeferred: <T>() => {
+export declare const createDeferred: <T, E = Error>() => {
     promise: Promise<T>;
     resolve: (value: T | PromiseLike<T>) => void;
-    reject: (reason?: unknown) => void;
+    reject: (reason?: E) => void;
 };
 //# sourceMappingURL=testing.d.ts.map

package/dist/testing.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC;AAE5E,eAAO,MAAM,gBAAgB,GAAI,MAAM,SAAS,KAAG,UAYlD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,CAAC;;qBACT,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI;sBAC1B,OAAO,KAAK,IAAI;CAOvC,CAAC"}
+{"version":3,"file":"testing.d.ts","sourceRoot":"","sources":["../src/testing.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,YAAY,CAAC;AAE5C,MAAM,MAAM,UAAU,GAAG;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,OAAO,EAAE,eAAe,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,UAAU,GAAG,SAAS,GAAG;IAAE,QAAQ,CAAC,WAAW,EAAE,UAAU,EAAE,CAAA;CAAE,CAAC;AAE5E,eAAO,MAAM,gBAAgB,GAAI,MAAM,SAAS,KAAG,UAYlD,CAAC;AAEF,eAAO,MAAM,cAAc,GAAI,CAAC,EAAE,CAAC,GAAG,KAAK;;qBACpB,CAAC,GAAG,WAAW,CAAC,CAAC,CAAC,KAAK,IAAI;sBAC1B,CAAC,KAAK,IAAI;CAOjC,CAAC"}

package/dist/types.d.ts

@@ -1,20 +1,39 @@
+import type * as Context from "effect/Context";
 import type * as Effect from "effect/Effect";
-import type * as Runtime from "effect/Runtime";
 import type * as Stream from "effect/Stream";
+import type { DiagnosticCause, IpcEncodedValue } from "./boundary.ts";
 import type { AnyEvent, AnyMethod, AnyStreamMethod, ExtractMethod, ExtractStreamMethod, RpcContract, RpcError, RpcEventPayload, RpcInput, RpcOutput, StreamChunk, StreamError, StreamInput } from "./contract.ts";
 export type { AnyEvent, AnyMethod, AnyStreamMethod, ErrorSchema, ExtractMethod, ExtractStreamMethod, RpcContract, RpcError, RpcEvent, RpcEventPayload, RpcInput, RpcMethod, RpcOutput, SchemaNoContext, StreamChunk, StreamError, StreamInput, StreamRpcMethod, } from "./contract.ts";
+/**
+ * Per-request context passed as the second argument to handlers.
+ * Handlers that don't need it can simply omit the parameter.
+ */
+export type RpcHandlerContext = {
+    /** The webContents that sent the request, when the transport exposes it. */
+    readonly sender: WebContentsLike | null;
+};
 export type Implementations<C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[], readonly AnyStreamMethod[]>, R = never> = {
-    readonly [Name in C["methods"][number]["name"]]: (input: RpcInput<ExtractMethod<C["methods"], Name>>) => Effect.Effect<RpcOutput<ExtractMethod<C["methods"], Name>>, RpcError<ExtractMethod<C["methods"], Name>>, R>;
+    readonly [Name in C["methods"][number]["name"]]: (input: RpcInput<ExtractMethod<C["methods"], Name>>, context: RpcHandlerContext) => Effect.Effect<RpcOutput<ExtractMethod<C["methods"], Name>>, RpcError<ExtractMethod<C["methods"], Name>>, R>;
 };
 export type StreamImplementations<C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[], readonly AnyStreamMethod[]>, R = never> = {
-    readonly [Name in C["streamMethods"][number]["name"]]: (input: StreamInput<ExtractStreamMethod<C["streamMethods"], Name>>) => Stream.Stream<StreamChunk<ExtractStreamMethod<C["streamMethods"], Name>>, StreamError<ExtractStreamMethod<C["streamMethods"], Name>>, R>;
+    readonly [Name in C["streamMethods"][number]["name"]]: (input: StreamInput<ExtractStreamMethod<C["streamMethods"], Name>>, context: RpcHandlerContext) => Stream.Stream<StreamChunk<ExtractStreamMethod<C["streamMethods"], Name>>, StreamError<ExtractStreamMethod<C["streamMethods"], Name>>, R>;
 };
 export type WebContentsLike = {
     readonly id: number;
     readonly isDestroyed: () => boolean;
-    readonly send: (channel: string, payload: unknown) => void;
-};
-type IsEmptyObject<T> = T extends object ? (keyof T extends never ? true : false) : false;
+    readonly send: (channel: string, payload: IpcEncodedValue) => void;
+    /**
+     * Optional EventEmitter surface (present on real Electron WebContents).
+     * When available, active stream fibers are interrupted as soon as the
+     * renderer is destroyed; otherwise termination happens on the next chunk.
+     */
+    readonly once?: (event: "destroyed", listener: () => void) => void;
+    readonly removeListener?: (event: "destroyed", listener: () => void) => void;
+};
+export type IpcInvokeEvent = {
+    readonly sender?: WebContentsLike;
+};
+type IsEmptyObject<T> = T extends object ? keyof T extends never ? string extends T ? true : false : false : false;
 export type RpcDefectCode = "request_encoding_failed" | "invoke_failed" | "success_payload_decoding_failed" | "failure_payload_decoding_failed" | "noerror_contract_violation" | "invalid_response_envelope" | "legacy_decode_failed" | "remote_defect" | "stream_invoke_failed" | "stream_handshake_invalid" | "stream_chunk_decode_failed" | "stream_error_decode_failed";
 export declare class RpcDefectError extends Error {
     readonly code: RpcDefectCode;
@@ -37,32 +56,38 @@ export type ChannelPrefix = {
     readonly event: string;
 };
 export declare const defaultChannelPrefix: ChannelPrefix;
+/**
+ * RPC and event prefixes must differ: with identical prefixes an event named
+ * like a method (or named "sf"/"stream-cancel") would collide with RPC and
+ * stream transport channels.
+ */
+export declare function assertValidChannelPrefix(prefix: ChannelPrefix): ChannelPrefix;
 export type DecodeFailureScope = "rpc-request" | "rpc-response" | "event-payload" | "stream-request" | "stream-chunk" | "stream-error";
 export type DecodeFailureContext = {
     readonly scope: DecodeFailureScope;
     readonly name: string;
-    readonly payload: unknown;
-    readonly cause: unknown;
+    readonly payload: DiagnosticCause;
+    readonly cause: DiagnosticCause;
 };
 export type ProtocolErrorContext = {
     readonly method: string;
-    readonly response: unknown;
-    readonly cause: unknown;
+    readonly response: DiagnosticCause;
+    readonly cause: DiagnosticCause;
 };
 export type DispatchFailureContext = {
     readonly event: string;
-    readonly payload: unknown;
-    readonly cause: unknown;
+    readonly payload: DiagnosticCause;
+    readonly cause: DiagnosticCause;
 };
 export type DroppedEventReason = "queue_full" | "encoding_failed" | "window_unavailable" | "dispatch_failed";
 export type DroppedEventContext = {
     readonly event: string;
-    readonly payload: unknown;
+    readonly payload: DiagnosticCause;
     readonly reason: DroppedEventReason;
     readonly queued: number;
     readonly dropped: number;
 };
-export type RpcInvoke = (method: string, payload: unknown) => Promise<unknown>;
+export type RpcInvoke = (method: string, payload: IpcEncodedValue) => Promise<IpcEncodedValue>;
 export type RpcResponseDecodeMode = "envelope" | "dual";
 export type RpcClientDiagnostics = {
     readonly onDecodeFailure?: (context: DecodeFailureContext) => void;
@@ -77,9 +102,10 @@ export type RpcEndpointDiagnostics = {
     readonly onDecodeFailure?: (context: DecodeFailureContext) => void;
     readonly onProtocolError?: (context: ProtocolErrorContext) => void;
 };
+export type IpcInvokeResult = IpcEncodedValue | Promise<IpcEncodedValue>;
 export type IpcMainLike = {
-    readonly handle: (channel: string, listener: (event: unknown, payload: unknown) => unknown) => unknown;
-    readonly removeHandler: (channel: string) => unknown;
+    readonly handle: (channel: string, listener: (event: IpcInvokeEvent, payload: IpcEncodedValue) => IpcInvokeResult) => void;
+    readonly removeHandler: (channel: string) => void;
 };
 export interface RpcEndpoint {
     readonly start: () => void;
@@ -89,7 +115,7 @@ export interface RpcEndpoint {
 }
 export type RpcEndpointOptions<C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[], readonly AnyStreamMethod[]> = RpcContract<readonly AnyMethod[], readonly AnyEvent[], readonly []>, R = never> = {
     readonly channelPrefix?: ChannelPrefix;
-    readonly runtime: Runtime.Runtime<R>;
+    readonly context: Context.Context<R>;
     readonly diagnostics?: RpcEndpointDiagnostics;
     readonly streamHandlers?: StreamImplementations<C, R>;
 };
@@ -101,7 +127,7 @@ export type EventPublisherDiagnostics = {
 export type RendererWindowLike = {
     readonly isDestroyed: () => boolean;
     readonly webContents: {
-        readonly send: (channel: string, payload: unknown) => void;
+        readonly send: (channel: string, payload: IpcEncodedValue) => void;
     };
 };
 export type EventPublisherOptions = {
@@ -111,18 +137,29 @@ export type EventPublisherOptions = {
     readonly diagnostics?: EventPublisherDiagnostics;
 };
 export interface RpcEventPublisher<C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[], readonly AnyStreamMethod[]>> {
+    /**
+     * Enqueue an event for delivery. Never fails: after `dispose()` the event
+     * is silently discarded, and delivery problems surface only through the
+     * diagnostics hooks and `stats()`.
+     */
     readonly publish: <E extends C["events"][number]>(event: E, payload: RpcEventPayload<E>) => Effect.Effect<void, never>;
     readonly start: () => void;
     readonly stop: () => void;
     readonly dispose: () => void;
     readonly isRunning: () => boolean;
-    readonly stats: () => {
-        readonly queued: number;
-        readonly dropped: number;
-    };
+    /**
+     * `dropped` counts failed deliveries, not whole events: an event that
+     * reaches two of three windows increments it once (per failed window),
+     * as do queue evictions and encoding failures.
+     */
+    readonly stats: () => EventPublisherStats;
 }
 export type EventDecodeMode = "safe" | "strict";
-export type EventSubscribe = (name: string, handler: (payload: unknown) => void) => () => void;
+export type EventPublisherStats = {
+    readonly queued: number;
+    readonly dropped: number;
+};
+export type EventSubscribe = (name: string, handler: (payload: IpcEncodedValue) => void) => () => void;
 export type EventSubscriberDiagnostics = {
     readonly onDecodeFailure?: (context: DecodeFailureContext) => void;
 };
@@ -133,16 +170,22 @@ export type EventSubscriberOptions = {
 };
 export interface EventSubscriber<C extends RpcContract<readonly AnyMethod[], readonly AnyEvent[], readonly AnyStreamMethod[]>> {
     readonly subscribe: <E extends C["events"][number]>(event: E, handler: (payload: RpcEventPayload<E>) => void) => () => void;
-    readonly subscribeByName: (name: string, handler: (payload: unknown) => void) => () => void;
+    readonly subscribeByName: (name: string, handler: (payload: IpcEncodedValue) => void) => () => void;
+    /**
+     * Effect-native subscription: a Stream of decoded payloads that
+     * subscribes when run and unsubscribes when its scope closes.
+     * Payloads that fail to decode are skipped (reported via diagnostics).
+     */
+    readonly stream: <E extends C["events"][number]>(event: E) => Stream.Stream<RpcEventPayload<E>>;
     readonly dispose: () => void;
 }
-export type OnStreamFrame = (listener: (frame: unknown) => void) => () => void;
+export type OnStreamFrame = (listener: (frame: IpcEncodedValue) => void) => () => void;
 /**
  * Stream chunk buffering policy in the renderer.
  * Prefer `bufferSize: "unbounded"` for lossless streams such as token deltas.
  *
- * Bounded buffers are lossy. With the current Effect `Stream.asyncPush`
- * internals, terminal signals can also be lost under sustained pressure.
+ * Bounded buffers are lossy for chunks. Effect v4's callback queue still
+ * preserves terminal completion and failure signals.
  */
 export type StreamBufferOptions = {
     readonly bufferSize: "unbounded";
@@ -160,5 +203,6 @@ export interface StreamRpcClientHandle<C extends RpcContract<readonly AnyMethod[
     readonly client: StreamRpcClient<C>;
     readonly dispose: () => void;
 }
+export type { DiagnosticCause, IpcEncodedRecord, IpcEncodedValue } from "./boundary.ts";
 export type { IpcBridge, IpcBridgeGlobal, IpcKit, IpcKitOptions, IpcMainHandle } from "./kit.ts";
 //# sourceMappingURL=types.d.ts.map