ts-procedures 5.9.1 → 5.10.2

package/src/implementations/http/hono-stream/index.test.ts

@@ -0,0 +1,1768 @@
+/* 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, MidStreamErrorResult } from './index.js'
+import { RPCConfig, StreamMode } from '../../types.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<{ userId: string }, RPCConfig>()
+
+      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<{ userId: string }, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      // 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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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: string[] = []
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{ userId: string }, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{ requestId: string }, RPCConfig>()
+
+      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<{ requestId: string }, RPCConfig>()
+
+      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<{ requestId: string }, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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 as Record<string, any>
+      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<{}, RPCConfig>()
+
+      RPC.CreateStream('NoYield', { scope: 'test', version: 1 }, async function* () {
+        yield {}
+      })
+
+      builder.register(RPC, () => ({}))
+      builder.build()
+
+      const yt = builder.docs[0]!.jsonSchema.yieldType as Record<string, any>
+      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<{}, RPCConfig>()
+
+      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 as Record<string, any>
+      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<{}, RPCConfig>()
+
+      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 as Record<string, any>
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      // 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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{ public: true }, RPCConfig>()
+      const PrivateRPC = Procedures<{ private: true }, RPCConfig>()
+
+      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 as const }))
+        .register(PrivateRPC, () => ({ private: true as const }))
+
+      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<{}, RPCConfig>()
+      const TextRPC = Procedures<{}, RPCConfig>()
+
+      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: HonoStreamAppBuilder
+
+    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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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: { start?: StreamMode; end?: StreamMode } = {}
+      const builder = new HonoStreamAppBuilder({
+        defaultStreamMode: 'text',
+        onStreamStart: (_proc, _c, mode) => { modes.start = mode },
+        onStreamEnd: (_proc, _c, mode) => { modes.end = mode },
+      })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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 () => {
+      type ErrorPayload = { type: 'error'; code: string; message: string }
+
+      const builder = new HonoStreamAppBuilder<ErrorPayload>({
+        onMidStreamError: (_procedure, _c, error) => {
+          // This satisfies MidStreamErrorResult<ErrorPayload>
+          return {
+            data: { type: 'error', code: 'STREAM_FAILED', message: error.message },
+          }
+        },
+      })
+      const RPC = Procedures<{}, RPCConfig>()
+
+      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<{}, RPCConfig>()
+
+      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 () => {
+      type StreamContext = { userId: string }
+
+      const RPC = Procedures<StreamContext, RPCConfig>()
+
+      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: string[] = []
+
+      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')
+    })
+  })
+})