ts-procedures 5.9.1 → 5.10.2

package/build/src/implementations/http/hono-stream/index.test.js

@@ -0,0 +1,1356 @@
+/* eslint-disable @typescript-eslint/no-empty-object-type, @typescript-eslint/explicit-function-return-type */
+import { describe, expect, test, vi, beforeEach } from 'vitest';
+import { Hono } from 'hono';
+import { v } from 'suretype';
+import { Procedures } from '../../../index.js';
+import { HonoStreamAppBuilder, sse } from './index.js';
+import { ProcedureValidationError } from '../../../errors.js';
+/**
+ * HonoStreamAppBuilder Test Suite
+ *
+ * Tests the streaming Hono integration for ts-procedures.
+ * This builder creates GET and POST routes for streaming procedures (SSE and text modes).
+ */
+describe('HonoStreamAppBuilder', () => {
+    // --------------------------------------------------------------------------
+    // Constructor Tests
+    // --------------------------------------------------------------------------
+    describe('constructor', () => {
+        test('creates default Hono app', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('StreamMessages', { scope: 'messages', version: 1 }, async function* () {
+                yield { message: 'hello' };
+                yield { message: 'world' };
+            });
+            builder.register(RPC, () => ({ userId: '123' }));
+            const app = builder.build();
+            const res = await app.request('/messages/stream-messages/1', {
+                method: 'GET',
+            });
+            expect(res.status).toBe(200);
+            expect(res.headers.get('content-type')).toContain('text/event-stream');
+        });
+        test('uses provided Hono app', async () => {
+            const customApp = new Hono();
+            customApp.get('/custom', (c) => c.json({ custom: true }));
+            const builder = new HonoStreamAppBuilder({ app: customApp });
+            const RPC = Procedures();
+            RPC.CreateStream('StreamData', { scope: 'data', version: 1 }, async function* () {
+                yield { data: 1 };
+            });
+            builder.register(RPC, () => ({ userId: '123' }));
+            const app = builder.build();
+            // Custom route should still work
+            const customRes = await app.request('/custom');
+            expect(customRes.status).toBe(200);
+            const customBody = await customRes.json();
+            expect(customBody).toEqual({ custom: true });
+            // Stream route should also work
+            const streamRes = await app.request('/data/stream-data/1');
+            expect(streamRes.status).toBe(200);
+        });
+        test('handles empty config', () => {
+            const builder = new HonoStreamAppBuilder({});
+            expect(builder.app).toBeDefined();
+            expect(builder.docs).toEqual([]);
+        });
+        test('handles undefined config', () => {
+            const builder = new HonoStreamAppBuilder(undefined);
+            expect(builder.app).toBeDefined();
+            expect(builder.docs).toEqual([]);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // SSE Streaming Tests
+    // --------------------------------------------------------------------------
+    describe('SSE streaming mode', () => {
+        test('streams multiple values as SSE events', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Counter', { scope: 'counter', version: 1 }, async function* () {
+                yield { count: 1 };
+                yield { count: 2 };
+                yield { count: 3 };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/counter/counter/1');
+            expect(res.status).toBe(200);
+            expect(res.headers.get('content-type')).toContain('text/event-stream');
+            const text = await res.text();
+            expect(text).toContain('event: Counter');
+            expect(text).toContain('data: {"count":1}');
+            expect(text).toContain('data: {"count":2}');
+            expect(text).toContain('data: {"count":3}');
+            expect(text).toContain('id: 0');
+            expect(text).toContain('id: 1');
+            expect(text).toContain('id: 2');
+        });
+        test('uses SSE mode by default', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/test/test/1');
+            expect(res.headers.get('content-type')).toContain('text/event-stream');
+        });
+        test('explicitly set SSE mode works', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/test/test/1');
+            expect(res.headers.get('content-type')).toContain('text/event-stream');
+        });
+        test('sends event: return when generator returns a value', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Summary', { scope: 'summary', version: 1 }, async function* () {
+                yield 'hello';
+                yield 'world';
+                return { total: 42 };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/summary/summary/1', { method: 'POST', body: JSON.stringify({}) });
+            expect(res.status).toBe(200);
+            const text = await res.text();
+            expect(text).toContain('event: return');
+            expect(text).toContain('data: {"total":42}');
+            // yield events have id: 0 and id: 1; return event should have id: 2
+            expect(text).toContain('id: 2');
+        });
+        test('does not send return event when generator returns undefined', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('NoReturn', { scope: 'no-return', version: 1 }, async function* () {
+                yield { item: 1 };
+                yield { item: 2 };
+                // no explicit return — implicitly returns undefined
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/no-return/no-return/1');
+            expect(res.status).toBe(200);
+            const text = await res.text();
+            expect(text).not.toContain('event: return');
+        });
+        test('return event works with zero yields', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            // eslint-disable-next-line require-yield
+            RPC.CreateStream('ImmediateReturn', { scope: 'immediate', version: 1 }, async function* () {
+                return { status: 'done' };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/immediate/immediate-return/1');
+            expect(res.status).toBe(200);
+            const text = await res.text();
+            expect(text).toContain('event: return');
+            expect(text).toContain('data: {"status":"done"}');
+            // first (and only) event has id: 0
+            expect(text).toContain('id: 0');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Text Streaming Tests
+    // --------------------------------------------------------------------------
+    describe('text streaming mode', () => {
+        test('streams multiple values as newline-delimited JSON', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('Counter', { scope: 'counter', version: 1 }, async function* () {
+                yield { count: 1 };
+                yield { count: 2 };
+                yield { count: 3 };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/counter/counter/1');
+            expect(res.status).toBe(200);
+            expect(res.headers.get('content-type')).toContain('text/plain');
+            const text = await res.text();
+            const lines = text.trim().split('\n');
+            expect(lines).toHaveLength(3);
+            expect(JSON.parse(lines[0])).toEqual({ count: 1 });
+            expect(JSON.parse(lines[1])).toEqual({ count: 2 });
+            expect(JSON.parse(lines[2])).toEqual({ count: 3 });
+        });
+        test('per-factory streamMode overrides default', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}), { streamMode: 'text' });
+            const app = builder.build();
+            const res = await app.request('/test/test/1');
+            expect(res.headers.get('content-type')).toContain('text/plain');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // HTTP Method Tests (GET and POST)
+    // --------------------------------------------------------------------------
+    describe('HTTP methods', () => {
+        test('GET request works', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { method: 'works' };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/test/test/1', { method: 'GET' });
+            expect(res.status).toBe(200);
+        });
+        test('POST request works', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { method: 'works' };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/test/test/1', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({}),
+            });
+            expect(res.status).toBe(200);
+        });
+        test('GET request passes query params to handler', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('Echo', { scope: 'echo', version: 1 }, async function* (ctx, params) {
+                yield { received: params };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/echo/echo/1?foo=bar&baz=qux');
+            const text = await res.text();
+            const data = JSON.parse(text.trim());
+            expect(data.received).toEqual({ foo: 'bar', baz: 'qux' });
+        });
+        test('POST request passes JSON body to handler', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('Echo', { scope: 'echo', version: 1 }, async function* (ctx, params) {
+                yield { received: params };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/echo/echo/1', {
+                method: 'POST',
+                headers: { 'Content-Type': 'application/json' },
+                body: JSON.stringify({ complex: { nested: 'data' }, array: [1, 2, 3] }),
+            });
+            const text = await res.text();
+            const data = JSON.parse(text.trim());
+            expect(data.received).toEqual({ complex: { nested: 'data' }, array: [1, 2, 3] });
+        });
+    });
+    // --------------------------------------------------------------------------
+    // pathPrefix Option Tests
+    // --------------------------------------------------------------------------
+    describe('pathPrefix option', () => {
+        test('uses custom pathPrefix for all routes', async () => {
+            const builder = new HonoStreamAppBuilder({ pathPrefix: '/api/v1' });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/api/v1/test/test/1');
+            expect(res.status).toBe(200);
+        });
+        test('pathPrefix without leading slash gets normalized', async () => {
+            const builder = new HonoStreamAppBuilder({ pathPrefix: 'custom' });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/custom/test/test/1');
+            expect(res.status).toBe(200);
+        });
+        test('pathPrefix appears in generated docs', () => {
+            const builder = new HonoStreamAppBuilder({ pathPrefix: '/api' });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield {};
+            });
+            builder.register(RPC, () => ({}));
+            builder.build();
+            expect(builder.docs[0].path).toBe('/api/test/test/1');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Lifecycle Hooks Tests
+    // --------------------------------------------------------------------------
+    describe('lifecycle hooks', () => {
+        test('onRequestStart is called with context object', async () => {
+            const onRequestStart = vi.fn();
+            const builder = new HonoStreamAppBuilder({ onRequestStart });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            await app.request('/test/test/1');
+            expect(onRequestStart).toHaveBeenCalledTimes(1);
+            expect(onRequestStart.mock.calls[0][0]).toHaveProperty('req');
+        });
+        test('onRequestEnd is called after response', async () => {
+            const onRequestEnd = vi.fn();
+            const builder = new HonoStreamAppBuilder({ onRequestEnd });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const response = await app.request('/test/test/1');
+            await response.text(); // Consume stream to trigger onRequestEnd
+            expect(onRequestEnd).toHaveBeenCalledTimes(1);
+            expect(onRequestEnd.mock.calls[0][0]).toHaveProperty('req');
+        });
+        test('onStreamStart is called before streaming begins with streamMode', async () => {
+            const onStreamStart = vi.fn();
+            const builder = new HonoStreamAppBuilder({ onStreamStart });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            await app.request('/test/test/1');
+            expect(onStreamStart).toHaveBeenCalledTimes(1);
+            expect(onStreamStart.mock.calls[0][0]).toHaveProperty('name', 'Test');
+            expect(onStreamStart.mock.calls[0][2]).toBe('sse');
+        });
+        test('onStreamEnd is called after stream completes with streamMode', async () => {
+            const onStreamEnd = vi.fn();
+            const builder = new HonoStreamAppBuilder({ onStreamEnd });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/test/test/1');
+            // Consume the stream to ensure it completes
+            await res.text();
+            expect(onStreamEnd).toHaveBeenCalledTimes(1);
+            expect(onStreamEnd.mock.calls[0][0]).toHaveProperty('name', 'Test');
+            expect(onStreamEnd.mock.calls[0][2]).toBe('sse');
+        });
+        test('hooks execute in correct order', async () => {
+            const order = [];
+            const builder = new HonoStreamAppBuilder({
+                onRequestStart: () => order.push('request-start'),
+                onRequestEnd: () => order.push('request-end'),
+                onStreamStart: () => order.push('stream-start'),
+                onStreamEnd: () => order.push('stream-end'),
+            });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                order.push('handler');
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/test/test/1');
+            // Consume the stream to ensure it completes
+            await res.text();
+            // Note: onRequestEnd middleware runs when response starts (before stream completes)
+            // while onStreamEnd runs when the stream finishes
+            expect(order).toContain('request-start');
+            expect(order).toContain('stream-start');
+            expect(order).toContain('handler');
+            expect(order).toContain('stream-end');
+            expect(order).toContain('request-end');
+            // request-start should be first
+            expect(order[0]).toBe('request-start');
+            // stream-start should be before handler
+            expect(order.indexOf('stream-start')).toBeLessThan(order.indexOf('handler'));
+            // request-end should be last
+            expect(order[order.length - 1]).toBe('request-end');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Error Handling Tests
+    // --------------------------------------------------------------------------
+    describe('error handling', () => {
+        test('custom error handler receives procedure, context, and error', async () => {
+            const errorHandler = vi.fn((procedure, c, error) => {
+                return c.json({ customError: error.message }, 400);
+            });
+            const builder = new HonoStreamAppBuilder({ onPreStreamError: errorHandler });
+            const RPC = Procedures();
+            RPC.CreateStream('ValidatedStream', {
+                scope: 'validated',
+                version: 1,
+                schema: {
+                    params: v.object({ count: v.number() }),
+                },
+            }, async function* (ctx, params) {
+                yield { count: params.count };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/validated/validated-stream/1?count=not-a-number');
+            expect(res.status).toBe(400);
+            const body = await res.json();
+            expect(body.customError).toContain('Validation error');
+            expect(errorHandler).toHaveBeenCalledTimes(1);
+            expect(errorHandler.mock.calls[0][0].name).toBe('ValidatedStream');
+            expect(errorHandler.mock.calls[0][2].message).toContain('Validation error');
+        });
+        test('errors during streaming are sent as error events (SSE mode)', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+                yield { count: 1 };
+                throw new Error('Stream error');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/error/error-stream/1');
+            const text = await res.text();
+            expect(text).toContain('data: {"count":1}');
+            expect(text).toContain('event: error');
+            expect(text).toContain('Stream error');
+        });
+        test('errors during streaming are sent as JSON lines (text mode)', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+                yield { count: 1 };
+                throw new Error('Stream error');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/error/error-stream/1');
+            const text = await res.text();
+            const lines = text.trim().split('\n');
+            expect(JSON.parse(lines[0])).toEqual({ count: 1 });
+            // Error is wrapped by Procedures with "Error in streaming handler for {name}" prefix
+            expect(JSON.parse(lines[1]).error).toContain('Stream error');
+        });
+        test('validation errors return 400 by default when no error handler', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('ValidatedStream', {
+                scope: 'validated',
+                version: 1,
+                schema: {
+                    params: v.object({ count: v.number() }),
+                },
+            }, async function* (ctx, params) {
+                yield { count: params.count };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/validated/validated-stream/1?count=not-a-number');
+            // Default: returns 400 JSON error
+            expect(res.status).toBe(400);
+            const body = await res.json();
+            expect(body.error).toContain('Validation error');
+        });
+        // Tests for onPreStreamError and onMidStreamError callbacks
+        test('onPreStreamError handles validation errors with custom Response', async () => {
+            const onPreStreamError = vi.fn((procedure, c, error) => {
+                return c.json({ customError: true, procedureName: procedure.name, details: error.message }, 422);
+            });
+            const builder = new HonoStreamAppBuilder({ onPreStreamError });
+            const RPC = Procedures();
+            RPC.CreateStream('ValidatedStream', {
+                scope: 'validated',
+                version: 1,
+                schema: {
+                    params: v.object({ count: v.number() }),
+                },
+            }, async function* (ctx, params) {
+                yield { count: params.count };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/validated/validated-stream/1?count=not-a-number');
+            expect(res.status).toBe(422);
+            const body = await res.json();
+            expect(body.customError).toBe(true);
+            expect(body.procedureName).toBe('ValidatedStream');
+            expect(body.details).toContain('Validation error');
+            expect(onPreStreamError).toHaveBeenCalledTimes(1);
+        });
+        test('onPreStreamError handles context resolution errors', async () => {
+            const onPreStreamError = vi.fn((procedure, c, error) => {
+                return c.json({ contextError: error.message }, 401);
+            });
+            const builder = new HonoStreamAppBuilder({ onPreStreamError });
+            const RPC = Procedures();
+            RPC.CreateStream('SecureStream', { scope: 'secure', version: 1 }, async function* (ctx) {
+                yield { userId: ctx.userId };
+            });
+            builder.register(RPC, () => {
+                throw new Error('Authentication required');
+            });
+            const app = builder.build();
+            const res = await app.request('/secure/secure-stream/1');
+            expect(res.status).toBe(401);
+            const body = await res.json();
+            expect(body.contextError).toBe('Authentication required');
+            expect(onPreStreamError).toHaveBeenCalledTimes(1);
+        });
+        test('onMidStreamError returns custom value written to SSE stream', async () => {
+            const onMidStreamError = vi.fn((procedure, c, error) => {
+                return {
+                    data: {
+                        type: 'error',
+                        code: 'STREAM_FAILED',
+                        message: error.message,
+                        retryable: false,
+                    },
+                    closeStream: true,
+                };
+            });
+            const builder = new HonoStreamAppBuilder({ onMidStreamError });
+            const RPC = Procedures();
+            RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+                yield { type: 'data', value: 1 };
+                throw new Error('Something broke');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/error/error-stream/1');
+            const text = await res.text();
+            // First yield should be present
+            expect(text).toContain('data: {"type":"data","value":1}');
+            // Error should use custom format from onMidStreamError
+            expect(text).toContain('data: {"type":"error","code":"STREAM_FAILED"');
+            expect(text).toContain('"retryable":false');
+            // Event should use procedure name (not 'error') since custom value provided
+            expect(text).toContain('event: ErrorStream');
+            expect(onMidStreamError).toHaveBeenCalledTimes(1);
+        });
+        test('onMidStreamError returns custom value written to text stream', async () => {
+            const onMidStreamError = vi.fn((procedure, c, error) => {
+                return {
+                    data: { type: 'error', message: error.message },
+                };
+            });
+            const builder = new HonoStreamAppBuilder({
+                defaultStreamMode: 'text',
+                onMidStreamError,
+            });
+            const RPC = Procedures();
+            RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+                yield { type: 'data', value: 'hello' };
+                throw new Error('Stream failed');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/error/error-stream/1');
+            const text = await res.text();
+            const lines = text.trim().split('\n');
+            expect(JSON.parse(lines[0])).toEqual({ type: 'data', value: 'hello' });
+            // Error message may be wrapped by Procedures with "Error in streaming handler for X - " prefix
+            const errorLine = JSON.parse(lines[1]);
+            expect(errorLine.type).toBe('error');
+            expect(errorLine.message).toContain('Stream failed');
+            expect(onMidStreamError).toHaveBeenCalledTimes(1);
+        });
+        test('onMidStreamError returning undefined falls back to default error format', async () => {
+            const onMidStreamError = vi.fn(() => undefined);
+            const builder = new HonoStreamAppBuilder({
+                defaultStreamMode: 'text',
+                onMidStreamError,
+            });
+            const RPC = Procedures();
+            RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+                yield { value: 1 };
+                throw new Error('Fallback test');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/error/error-stream/1');
+            const text = await res.text();
+            const lines = text.trim().split('\n');
+            expect(JSON.parse(lines[0])).toEqual({ value: 1 });
+            // Falls back to default { error: message } format
+            expect(JSON.parse(lines[1]).error).toContain('Fallback test');
+            expect(onMidStreamError).toHaveBeenCalledTimes(1);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Context Resolution Tests
+    // --------------------------------------------------------------------------
+    describe('context resolution', () => {
+        test('context can be a static object', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('GetId', { scope: 'get-id', version: 1 }, async function* (ctx) {
+                yield { id: ctx.requestId };
+            });
+            builder.register(RPC, { requestId: 'static-123' });
+            const app = builder.build();
+            const res = await app.request('/get-id/get-id/1');
+            const text = await res.text();
+            expect(JSON.parse(text.trim())).toEqual({ id: 'static-123' });
+        });
+        test('context can be sync function', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('GetId', { scope: 'get-id', version: 1 }, async function* (ctx) {
+                yield { id: ctx.requestId };
+            });
+            builder.register(RPC, (c) => ({ requestId: c.req.header('x-request-id') || 'unknown' }));
+            const app = builder.build();
+            const res = await app.request('/get-id/get-id/1', {
+                headers: { 'X-Request-Id': 'req-456' },
+            });
+            const text = await res.text();
+            expect(JSON.parse(text.trim())).toEqual({ id: 'req-456' });
+        });
+        test('context can be async function', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('GetId', { scope: 'get-id', version: 1 }, async function* (ctx) {
+                yield { id: ctx.requestId };
+            });
+            builder.register(RPC, async () => {
+                await new Promise((r) => setTimeout(r, 10));
+                return { requestId: 'async-789' };
+            });
+            const app = builder.build();
+            const res = await app.request('/get-id/get-id/1');
+            const text = await res.text();
+            expect(JSON.parse(text.trim())).toEqual({ id: 'async-789' });
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Documentation Tests
+    // --------------------------------------------------------------------------
+    describe('documentation', () => {
+        test('generates complete route documentation', () => {
+            const paramsSchema = v.object({ id: v.string() });
+            const yieldSchema = v.object({ message: v.string() });
+            const returnSchema = v.object({ total: v.number() });
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('StreamMessages', {
+                scope: 'messages',
+                version: 1,
+                schema: { params: paramsSchema, yieldType: yieldSchema, returnType: returnSchema },
+            }, async function* () {
+                yield { message: 'test' };
+            });
+            builder.register(RPC, () => ({}));
+            builder.build();
+            const doc = builder.docs[0];
+            expect(doc.path).toBe('/messages/stream-messages/1');
+            expect(doc.methods).toEqual(['get', 'post']);
+            expect(doc.streamMode).toBe('sse');
+            expect(doc.jsonSchema.params).toBeDefined();
+            expect(doc.jsonSchema.returnType).toBeDefined();
+            // yieldType is nested under SSE envelope's data property
+            const yt = doc.jsonSchema.yieldType;
+            expect(yt.description).toBe('SSE message envelope. The data field contains the procedure yield value.');
+            expect(yt.required).toEqual(['data', 'event', 'id']);
+            expect(yt.properties.event).toEqual({ type: 'string' });
+            expect(yt.properties.id).toEqual({ type: 'string' });
+            expect(yt.properties.retry).toEqual({ type: 'number' });
+            // Developer's yieldType is nested under data
+            expect(yt.properties.data.properties.message).toBeDefined();
+        });
+        test('SSE mode generates SSE envelope even when no yieldType is defined', () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('NoYield', { scope: 'test', version: 1 }, async function* () {
+                yield {};
+            });
+            builder.register(RPC, () => ({}));
+            builder.build();
+            const yt = builder.docs[0].jsonSchema.yieldType;
+            expect(yt).toBeDefined();
+            expect(yt.type).toBe('object');
+            expect(yt.description).toBe('SSE message envelope. The data field contains the procedure yield value.');
+            expect(yt.required).toEqual(['data', 'event', 'id']);
+            // data is empty schema when no yieldType defined
+            expect(yt.properties.data).toEqual({});
+            expect(yt.properties.event).toEqual({ type: 'string' });
+            expect(yt.properties.id).toEqual({ type: 'string' });
+            expect(yt.properties.retry).toEqual({ type: 'number' });
+        });
+        test('text mode passes yieldType through as-is', () => {
+            const yieldSchema = v.object({ chunk: v.string() });
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('TextStream', { scope: 'test', version: 1, schema: { yieldType: yieldSchema } }, async function* () {
+                yield { chunk: 'hi' };
+            });
+            builder.register(RPC, () => ({}));
+            builder.build();
+            const yt = builder.docs[0].jsonSchema.yieldType;
+            expect(yt).toBeDefined();
+            // Text mode should NOT have SSE envelope fields injected
+            expect(yt.properties?.event).toBeUndefined();
+            expect(yt.properties?.id).toBeUndefined();
+            expect(yt.properties?.retry).toBeUndefined();
+        });
+        test('yieldType with id property does not collide with SSE id field', () => {
+            // User's yieldType has an `id` field (number) — this should be nested under
+            // the SSE envelope's `data` property, not collide with the SSE `id` (string)
+            const yieldSchema = v.object({
+                id: v.number(),
+                message: v.string(),
+            });
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Notifications', { scope: 'test', version: 1, schema: { yieldType: yieldSchema } }, async function* () {
+                yield { id: 42, message: 'hello' };
+            });
+            builder.register(RPC, () => ({}));
+            builder.build();
+            const yt = builder.docs[0].jsonSchema.yieldType;
+            expect(yt.required).toEqual(['data', 'event', 'id']);
+            // SSE envelope id is a string
+            expect(yt.properties.id).toEqual({ type: 'string' });
+            // User's id (number) is safely nested under data
+            expect(yt.properties.data.properties.id.type).toBe('number');
+            expect(yt.properties.data.properties.message.type).toBe('string');
+        });
+        test('streamMode is recorded in docs', () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield {};
+            });
+            builder.register(RPC, () => ({}));
+            builder.build();
+            expect(builder.docs[0].streamMode).toBe('text');
+        });
+        test('per-factory streamMode is recorded in docs', () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'sse' });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield {};
+            });
+            builder.register(RPC, () => ({}), { streamMode: 'text' });
+            builder.build();
+            expect(builder.docs[0].streamMode).toBe('text');
+        });
+        test("doc.kind is 'stream'", () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('StreamEvents', { scope: 'events', version: 1 }, async function* () {
+                yield {};
+            });
+            builder.register(RPC, () => ({}));
+            builder.build();
+            const doc = builder.docs[0];
+            expect(doc.kind).toBe('stream');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Filter Tests (Only Streaming Procedures)
+    // --------------------------------------------------------------------------
+    describe('procedure filtering', () => {
+        test('only registers streaming procedures', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            // Regular procedure (should be ignored)
+            RPC.Create('NonStream', { scope: 'non-stream', version: 1 }, async () => ({
+                ok: true,
+            }));
+            // Streaming procedure (should be registered)
+            RPC.CreateStream('Stream', { scope: 'stream', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            // Only streaming procedure should be in docs
+            expect(builder.docs).toHaveLength(1);
+            expect(builder.docs[0].name).toBe('Stream');
+            // Non-streaming route should 404
+            const nonStreamRes = await app.request('/non-stream/non-stream/1', { method: 'POST' });
+            expect(nonStreamRes.status).toBe(404);
+            // Streaming route should work
+            const streamRes = await app.request('/stream/stream/1');
+            expect(streamRes.status).toBe(200);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // extendProcedureDoc Tests
+    // --------------------------------------------------------------------------
+    describe('extendProcedureDoc', () => {
+        test('adds custom properties to generated documentation', () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('StreamEvents', { scope: 'events', version: 1 }, async function* () {
+                yield {};
+            });
+            builder.register(RPC, () => ({}), {
+                extendProcedureDoc: ({ procedure }) => ({
+                    summary: `Stream events endpoint`,
+                    tags: ['events'],
+                    operationId: procedure.name,
+                }),
+            });
+            builder.build();
+            const doc = builder.docs[0];
+            expect(doc).toHaveProperty('summary', 'Stream events endpoint');
+            expect(doc).toHaveProperty('tags', ['events']);
+            expect(doc).toHaveProperty('operationId', 'StreamEvents');
+        });
+        test('base properties take precedence over extended properties', () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield {};
+            });
+            builder.register(RPC, () => ({}), {
+                extendProcedureDoc: () => ({
+                    name: 'OverriddenName',
+                    path: '/overridden/path',
+                    methods: ['put'],
+                    customField: 'custom-value',
+                }),
+            });
+            builder.build();
+            const doc = builder.docs[0];
+            // Base properties should NOT be overridden
+            expect(doc.name).toBe('Test');
+            expect(doc.path).toBe('/test/test/1');
+            expect(doc.methods).toEqual(['get', 'post']);
+            // Custom field should be present
+            expect(doc).toHaveProperty('customField', 'custom-value');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Multiple Factory Tests
+    // --------------------------------------------------------------------------
+    describe('multiple factories', () => {
+        test('supports registering multiple factories', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const PublicRPC = Procedures();
+            const PrivateRPC = Procedures();
+            PublicRPC.CreateStream('PublicStream', { scope: 'public', version: 1 }, async function* (ctx) {
+                yield { isPublic: ctx.public };
+            });
+            PrivateRPC.CreateStream('PrivateStream', { scope: 'private', version: 1 }, async function* (ctx) {
+                yield { isPrivate: ctx.private };
+            });
+            builder
+                .register(PublicRPC, () => ({ public: true }))
+                .register(PrivateRPC, () => ({ private: true }));
+            const app = builder.build();
+            const publicRes = await app.request('/public/public-stream/1');
+            const publicText = await publicRes.text();
+            expect(JSON.parse(publicText.trim())).toEqual({ isPublic: true });
+            const privateRes = await app.request('/private/private-stream/1');
+            const privateText = await privateRes.text();
+            expect(JSON.parse(privateText.trim())).toEqual({ isPrivate: true });
+        });
+        test('different factories can have different stream modes', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const SSERPC = Procedures();
+            const TextRPC = Procedures();
+            SSERPC.CreateStream('SSEStream', { scope: 'sse', version: 1 }, async function* () {
+                yield { mode: 'sse' };
+            });
+            TextRPC.CreateStream('TextStream', { scope: 'text', version: 1 }, async function* () {
+                yield { mode: 'text' };
+            });
+            builder
+                .register(SSERPC, () => ({}), { streamMode: 'sse' })
+                .register(TextRPC, () => ({}), { streamMode: 'text' });
+            const app = builder.build();
+            const sseRes = await app.request('/sse/sse-stream/1');
+            expect(sseRes.headers.get('content-type')).toContain('text/event-stream');
+            const textRes = await app.request('/text/text-stream/1');
+            expect(textRes.headers.get('content-type')).toContain('text/plain');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Path Generation Tests
+    // --------------------------------------------------------------------------
+    describe('makeStreamHttpRoutePath', () => {
+        let builder;
+        beforeEach(() => {
+            builder = new HonoStreamAppBuilder();
+        });
+        test("simple scope: 'events' + 'StreamUpdates' → /events/stream-updates/1", () => {
+            const path = builder.makeStreamHttpRoutePath('StreamUpdates', { scope: 'events', version: 1 });
+            expect(path).toBe('/events/stream-updates/1');
+        });
+        test("array scope: ['events', 'live'] + 'Watch' → /events/live/watch/1", () => {
+            const path = builder.makeStreamHttpRoutePath('Watch', {
+                scope: ['events', 'live'],
+                version: 1,
+            });
+            expect(path).toBe('/events/live/watch/1');
+        });
+        test('version number included in path', () => {
+            const pathV1 = builder.makeStreamHttpRoutePath('Test', { scope: 'test', version: 1 });
+            const pathV2 = builder.makeStreamHttpRoutePath('Test', { scope: 'test', version: 2 });
+            expect(pathV1).toBe('/test/test/1');
+            expect(pathV2).toBe('/test/test/2');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // isPrevalidated Tests
+    // --------------------------------------------------------------------------
+    describe('isPrevalidated context property', () => {
+        test('skips procedure-level validation since HonoStreamAppBuilder already validated', async () => {
+            let handlerCalled = false;
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('CheckPrevalidated', {
+                scope: 'check',
+                version: 1,
+                schema: {
+                    params: v.object({ name: v.string() }),
+                },
+            }, async function* () {
+                handlerCalled = true;
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            // Valid params pass HonoStreamAppBuilder validation, handler runs without double validation
+            const res = await app.request('/check/check-prevalidated/1?name=test');
+            await res.text();
+            expect(res.status).toBe(200);
+            expect(handlerCalled).toBe(true);
+        });
+        test('valid params work correctly with pre-validation flow', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('ValidParams', {
+                scope: 'valid',
+                version: 1,
+                schema: {
+                    params: v.object({ count: v.number() }),
+                },
+            }, async function* (ctx, params) {
+                const count = params.count ?? 0;
+                for (let i = 0; i < count; i++) {
+                    yield { index: i };
+                }
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            // With valid params, both HonoStreamAppBuilder validation and procedure validation should work
+            const res = await app.request('/valid/valid-params/1?count=2');
+            expect(res.status).toBe(200);
+            const text = await res.text();
+            const lines = text.trim().split('\n');
+            expect(lines).toHaveLength(2);
+            expect(JSON.parse(lines[0])).toEqual({ index: 0 });
+            expect(JSON.parse(lines[1])).toEqual({ index: 1 });
+        });
+        test('invalid params are caught by HonoStreamAppBuilder before handler runs', async () => {
+            let handlerCalled = false;
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('InvalidParams', {
+                scope: 'invalid',
+                version: 1,
+                schema: {
+                    params: v.object({ count: v.number() }),
+                },
+            }, async function* () {
+                handlerCalled = true;
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            // With invalid params, HonoStreamAppBuilder catches the error before streaming starts
+            const res = await app.request('/invalid/invalid-params/1?count=not-a-number');
+            expect(res.status).toBe(400);
+            const body = await res.json();
+            expect(body.error).toContain('Validation error');
+            // Handler should never be called since validation fails before streaming
+            expect(handlerCalled).toBe(false);
+        });
+    });
+    // --------------------------------------------------------------------------
+    // SSE Yield Shape Tests
+    // --------------------------------------------------------------------------
+    describe('SSE yield shape', () => {
+        test('custom event names via sse() helper', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Events', { scope: 'events', version: 1 }, async function* () {
+                yield sse({ type: 'user_joined' }, { event: 'join' });
+                yield sse({ type: 'message' }, { event: 'chat' });
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/events/events/1');
+            const text = await res.text();
+            expect(text).toContain('event: join');
+            expect(text).toContain('event: chat');
+            expect(text).not.toContain('event: Events');
+        });
+        test('custom id via sse() helper', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Events', { scope: 'events', version: 1 }, async function* () {
+                yield sse({ msg: 'first' }, { id: 'msg-001' });
+                yield sse({ msg: 'second' }, { id: 'msg-002' });
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/events/events/1');
+            const text = await res.text();
+            expect(text).toContain('id: msg-001');
+            expect(text).toContain('id: msg-002');
+        });
+        test('string data pass-through without double-stringify', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Events', { scope: 'events', version: 1 }, async function* () {
+                yield 'already a string';
+                yield { needs: 'stringify' };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/events/events/1');
+            const text = await res.text();
+            // String data should be passed through as-is (not JSON-stringified again)
+            expect(text).toContain('data: already a string');
+            // Object data should be JSON-stringified
+            expect(text).toContain('data: {"needs":"stringify"}');
+        });
+        test('default event falls back to procedure name when omitted', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('MyProcedure', { scope: 'test', version: 1 }, async function* () {
+                yield { value: 1 };
+                yield sse({ value: 2 }, { event: 'custom' });
+                yield { value: 3 };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/test/my-procedure/1');
+            const text = await res.text();
+            // Split into individual SSE messages
+            const messages = text.split('\n\n').filter(Boolean);
+            // First and third should use procedure name as event
+            expect(messages[0]).toContain('event: MyProcedure');
+            // Second should use custom event
+            expect(messages[1]).toContain('event: custom');
+            // Third should fall back to procedure name
+            expect(messages[2]).toContain('event: MyProcedure');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // sse() Helper Tests
+    // --------------------------------------------------------------------------
+    describe('sse() helper', () => {
+        test('tagged yields with custom event/id/retry', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Tagged', { scope: 'tagged', version: 1 }, async function* () {
+                yield sse({ count: 1 }, { event: 'tick', id: 'evt-1', retry: 5000 });
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/tagged/tagged/1');
+            const text = await res.text();
+            expect(text).toContain('event: tick');
+            expect(text).toContain('id: evt-1');
+            expect(text).toContain('retry: 5000');
+            expect(text).toContain('data: {"count":1}');
+        });
+        test('plain domain objects use procedure name and auto-incremented id', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Plain', { scope: 'plain', version: 1 }, async function* () {
+                yield { a: 1 };
+                yield { a: 2 };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/plain/plain/1');
+            const text = await res.text();
+            const messages = text.split('\n\n').filter(Boolean);
+            expect(messages[0]).toContain('event: Plain');
+            expect(messages[0]).toContain('id: 0');
+            expect(messages[0]).toContain('data: {"a":1}');
+            expect(messages[1]).toContain('event: Plain');
+            expect(messages[1]).toContain('id: 1');
+            expect(messages[1]).toContain('data: {"a":2}');
+        });
+        test('sse() metadata is invisible in text mode', async () => {
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text' });
+            const RPC = Procedures();
+            RPC.CreateStream('TextTagged', { scope: 'text', version: 1 }, async function* () {
+                yield sse({ count: 1 }, { event: 'tick' });
+                yield { count: 2 };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/text/text-tagged/1');
+            const text = await res.text();
+            const lines = text.trim().split('\n');
+            // Text mode just JSON-stringifies — sse() metadata is not visible
+            expect(JSON.parse(lines[0])).toEqual({ count: 1 });
+            expect(JSON.parse(lines[1])).toEqual({ count: 2 });
+        });
+        test('sse() with partial options', async () => {
+            const builder = new HonoStreamAppBuilder();
+            const RPC = Procedures();
+            RPC.CreateStream('Partial', { scope: 'partial', version: 1 }, async function* () {
+                yield sse({ v: 1 }, { event: 'custom' });
+                yield sse({ v: 2 }, { id: 'my-id' });
+                yield sse({ v: 3 });
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/partial/partial/1');
+            const text = await res.text();
+            const messages = text.split('\n\n').filter(Boolean);
+            // First: custom event, auto id
+            expect(messages[0]).toContain('event: custom');
+            expect(messages[0]).toContain('id: 0');
+            // Second: default event, custom id
+            expect(messages[1]).toContain('event: Partial');
+            expect(messages[1]).toContain('id: my-id');
+            // Third: sse() with no options — same as plain object (defaults)
+            expect(messages[2]).toContain('event: Partial');
+            expect(messages[2]).toContain('id: 2');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // streamMode in Lifecycle Hooks
+    // --------------------------------------------------------------------------
+    describe('streamMode in lifecycle hooks', () => {
+        test('onStreamStart receives sse streamMode', async () => {
+            const onStreamStart = vi.fn();
+            const builder = new HonoStreamAppBuilder({ onStreamStart });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            await app.request('/test/test/1');
+            expect(onStreamStart).toHaveBeenCalledTimes(1);
+            const [, , streamMode] = onStreamStart.mock.calls[0];
+            expect(streamMode).toBe('sse');
+        });
+        test('onStreamEnd receives text streamMode', async () => {
+            const onStreamEnd = vi.fn();
+            const builder = new HonoStreamAppBuilder({ defaultStreamMode: 'text', onStreamEnd });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/test/test/1');
+            await res.text();
+            expect(onStreamEnd).toHaveBeenCalledTimes(1);
+            const [, , streamMode] = onStreamEnd.mock.calls[0];
+            expect(streamMode).toBe('text');
+        });
+        test('onStreamStart and onStreamEnd receive matching streamMode', async () => {
+            const modes = {};
+            const builder = new HonoStreamAppBuilder({
+                defaultStreamMode: 'text',
+                onStreamStart: (_proc, _c, mode) => { modes.start = mode; },
+                onStreamEnd: (_proc, _c, mode) => { modes.end = mode; },
+            });
+            const RPC = Procedures();
+            RPC.CreateStream('Test', { scope: 'test', version: 1 }, async function* () {
+                yield { ok: true };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/test/test/1');
+            await res.text();
+            expect(modes.start).toBe('text');
+            expect(modes.end).toBe('text');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // sse() in onMidStreamError
+    // --------------------------------------------------------------------------
+    describe('sse() in onMidStreamError', () => {
+        test('sse() wraps error data with custom event and id', async () => {
+            const builder = new HonoStreamAppBuilder({
+                onMidStreamError: (procedure, c, error) => {
+                    return {
+                        data: sse({ type: 'error', message: error.message }, { event: 'custom-error', id: 'err-1' }),
+                    };
+                },
+            });
+            const RPC = Procedures();
+            RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+                yield { type: 'data', value: 1 };
+                throw new Error('Something broke');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/error/error-stream/1');
+            const text = await res.text();
+            // Normal yield
+            expect(text).toContain('data: {"type":"data","value":1}');
+            // Error yield with sse() metadata
+            expect(text).toContain('event: custom-error');
+            expect(text).toContain('id: err-1');
+            expect(text).toContain('"type":"error"');
+        });
+        test('string error data without sse() uses default event and id', async () => {
+            const builder = new HonoStreamAppBuilder({
+                onMidStreamError: () => {
+                    return { data: 'plain error string' };
+                },
+            });
+            const RPC = Procedures();
+            RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+                yield { count: 1 };
+                throw new Error('fail');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/error/error-stream/1');
+            const text = await res.text();
+            // String data can't use sse() (not an object), so defaults apply
+            expect(text).toContain('data: plain error string');
+            // event defaults to procedure name when data is provided
+            expect(text).toContain('event: ErrorStream');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Generic TErrorData
+    // --------------------------------------------------------------------------
+    describe('generic TErrorData', () => {
+        test('typed builder constrains onMidStreamError return type', async () => {
+            const builder = new HonoStreamAppBuilder({
+                onMidStreamError: (_procedure, _c, error) => {
+                    // This satisfies MidStreamErrorResult<ErrorPayload>
+                    return {
+                        data: { type: 'error', code: 'STREAM_FAILED', message: error.message },
+                    };
+                },
+            });
+            const RPC = Procedures();
+            RPC.CreateStream('ErrorStream', { scope: 'error', version: 1 }, async function* () {
+                yield { value: 1 };
+                throw new Error('typed error');
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/error/error-stream/1');
+            const text = await res.text();
+            expect(text).toContain('"code":"STREAM_FAILED"');
+            // Error message may be wrapped by Procedures with prefix
+            expect(text).toContain('typed error');
+        });
+    });
+    // --------------------------------------------------------------------------
+    // ProcedureValidationError narrowing in onPreStreamError
+    // --------------------------------------------------------------------------
+    describe('ProcedureValidationError narrowing', () => {
+        test('instanceof check works in onPreStreamError', async () => {
+            let wasValidationError = false;
+            const builder = new HonoStreamAppBuilder({
+                onPreStreamError: (procedure, c, error) => {
+                    if (error instanceof ProcedureValidationError) {
+                        wasValidationError = true;
+                        return c.json({ validation: true, errors: error.errors }, 422);
+                    }
+                    return c.json({ error: error.message }, 500);
+                },
+            });
+            const RPC = Procedures();
+            RPC.CreateStream('Validated', {
+                scope: 'validated',
+                version: 1,
+                schema: { params: v.object({ count: v.number() }) },
+            }, async function* (ctx, params) {
+                yield { count: params.count };
+            });
+            builder.register(RPC, () => ({}));
+            const app = builder.build();
+            const res = await app.request('/validated/validated/1?count=not-a-number');
+            expect(res.status).toBe(422);
+            expect(wasValidationError).toBe(true);
+            const body = await res.json();
+            expect(body.validation).toBe(true);
+            expect(body.errors).toBeDefined();
+        });
+    });
+    // --------------------------------------------------------------------------
+    // Integration Test
+    // --------------------------------------------------------------------------
+    describe('integration', () => {
+        test('full workflow with streaming procedures', async () => {
+            const RPC = Procedures();
+            RPC.CreateStream('WatchNotifications', {
+                scope: ['user', 'notifications'],
+                version: 1,
+                schema: {
+                    params: v.object({ limit: v.number() }),
+                    yieldType: v.object({ id: v.number(), message: v.string() }),
+                },
+            }, async function* (ctx, params) {
+                const limit = params?.limit ?? 3;
+                for (let i = 1; i <= limit; i++) {
+                    yield { id: i, message: `Notification ${i} for ${ctx.userId}` };
+                }
+            });
+            // Also create a non-streaming procedure to ensure it's filtered out
+            RPC.Create('GetNotificationCount', { scope: ['user', 'notifications'], version: 1 }, async () => ({
+                count: 10,
+            }));
+            const events = [];
+            const builder = new HonoStreamAppBuilder({
+                defaultStreamMode: 'text',
+                onRequestStart: () => events.push('request-start'),
+                onRequestEnd: () => events.push('request-end'),
+                onStreamStart: () => events.push('stream-start'),
+                onStreamEnd: () => events.push('stream-end'),
+            });
+            builder.register(RPC, (c) => ({
+                userId: c.req.header('x-user-id') || 'anonymous',
+            }));
+            const app = builder.build();
+            // Only streaming procedure should be registered
+            expect(builder.docs).toHaveLength(1);
+            expect(builder.docs[0].name).toBe('WatchNotifications');
+            expect(builder.docs[0].methods).toEqual(['get', 'post']);
+            // Test streaming
+            const res = await app.request('/user/notifications/watch-notifications/1?limit=2', {
+                headers: { 'X-User-Id': 'user-123' },
+            });
+            expect(res.status).toBe(200);
+            const text = await res.text();
+            const lines = text.trim().split('\n');
+            expect(lines).toHaveLength(2);
+            expect(JSON.parse(lines[0])).toEqual({ id: 1, message: 'Notification 1 for user-123' });
+            expect(JSON.parse(lines[1])).toEqual({ id: 2, message: 'Notification 2 for user-123' });
+            // Verify hooks were called
+            expect(events).toContain('request-start');
+            expect(events).toContain('stream-start');
+            expect(events).toContain('stream-end');
+            expect(events).toContain('request-end');
+        });
+    });
+});
+//# sourceMappingURL=index.test.js.map