Merge remote-tracking branch 'origin/master' into worktree/web-multimodal-image-input

# Conflicts: # apps/cli/src/web.ts # apps/web/tests/smoke-fixture.e2e.ts # docs/architecture.i18n.yaml # packages/client/connection/src/client/fixture.ts # packages/client/runtime/src/client/sessions/conversation.ts # packages/client/runtime/src/client/sessions/session.ts # packages/client/ui-conversation/package.json # packages/client/ui-conversation/src/client/contract/slots.ts # packages/client/ui-conversation/src/client/index.ts # packages/client/ui-conversation/src/client/service.ts # packages/client/ui-conversation/src/client/skeleton/ConversationRoot.tsx # packages/client/ui-conversation/tests/apply-inject.spec.tsx # packages/client/ui-conversation/tests/service-orchestration.spec.ts # packages/host/runtime/src/api-proxy.ts # packages/host/runtime/src/boot.ts # packages/host/webserver/tests/webserver.spec.ts # pnpm-lock.yaml
2026-07-24 16:29:03 +08:00
parent 0d657f4dfa 65d29da8a1
commit 6b7984a85e
503 changed files with 19038 additions and 3597 deletions
--- a/packages/host/webserver/tests/invariant.spec.ts
+++ b/packages/host/webserver/tests/invariant.spec.ts
@@ -1,7 +1,7 @@
 /**
- * Webserver invariant companion: the boot-manifest consistency audit — every
- * registry snapshot row must resolve a clientPath, checked on fiber lifecycle
- * events against the assembly-published 'webPlugins' context key.
+ * Webserver invariant companion: the boot-graph consistency audit — every
+ * fetch-arrival graph row must resolve a clientPath, checked on fiber
+ * lifecycle events against the assembly-published 'webPlugins' context key.
 */
 import { Context } from 'cordis'
 import { describe, expect, it } from 'vitest'
@@ -9,7 +9,7 @@ import InvariantService from '@deepseek-ai/dsh-invariants'
 import * as WebserverInvariant from '../src/invariant.ts'

 interface RegistryStub {
-  snapshot(): { id: string; url: string }[]
+  graph(): { entries: { id: string; url: string }[] }
  clientPath(id: string): string | undefined
 }

@@ -33,18 +33,18 @@ describe('webserver manifest invariant', () => {
    expect(() => { trigger(bare) }).not.toThrow() // no 'webPlugins' key published

    const consistent = await setup({
-      snapshot: () => [{ id: 'p1', url: '/plugins/p1/client.js' }],
-      clientPath: () => '/tmp/p1/lib/client.js',
+      graph: () => ({ entries: [{ id: 'p1', url: '/plugins/p1/client.js?rev=abc' }] }),
+      clientPath: id => id === 'p1' ? '/tmp/p1/lib/client.js' : undefined,
    })
    expect(() => { trigger(consistent) }).not.toThrow()
  })

-  it('throws on a manifest row whose bundle path no longer resolves', async () => {
+  it('throws on a graph row whose bundle path no longer resolves', async () => {
    const ctx = await setup({
-      snapshot: () => [{ id: 'ghost', url: '/plugins/ghost/client.js' }],
+      graph: () => ({ entries: [{ id: 'ghost', url: '/plugins/ghost/client.js?rev=abc' }] }),
      clientPath: () => undefined,
    })
    expect(() => { trigger(ctx) })
-      .toThrow(/manifest row "ghost".*resolves no client bundle path/)
+      .toThrow(/graph row "ghost".*resolves no client bundle path/)
  })
 })
--- a/packages/host/webserver/tests/web-plugins.spec.ts
+++ b/packages/host/webserver/tests/web-plugins.spec.ts
@@ -2,7 +2,7 @@ import { mkdirSync, mkdtempSync, writeFileSync } from 'node:fs'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { Context } from 'cordis'
-import { describe, expect, it } from 'vitest'
+import { describe, expect, it, vi } from 'vitest'
 import { createHostWebPluginRegistry, injectBootManifest } from '../src/index.ts'
 import type { LoaderEntryView, WebPluginRegistryDeps } from '../src/index.ts'

@@ -25,6 +25,7 @@ interface Fixture {
  entries: LoaderEntryView[]
  errors: Error[]
  ctx: Context
+  root: string
 }

 function makeDeps(
@@ -48,32 +49,30 @@ function makeDeps(
    },
    onError: err => void errors.push(err),
  }
-  return { deps, entries, errors, ctx }
+  return { deps, entries, errors, ctx, root }
 }

 describe('createHostWebPluginRegistry', () => {
-  it('collects loaded web-declared plugins with url/inject/immediately and client paths', () => {
+  it('discovers dshClient rows with rev-stamped urls, manifest inject edges, and the declared immediately mark', () => {
    const { deps } = makeDeps([
      { name: '@deepseek-ai/dsh-client-connection', pkg: webDecl({ immediately: true }) },
      { name: '@deepseek-ai/dsh-client-ui-layout', pkg: webDecl({ inject: ['@deepseek-ai/dsh-client-runtime'] }) },
      { name: '@deepseek-ai/dsh-agent', pkg: { exports: { '.': './lib/index.js' } } }, // no dshClient: skipped
    ])
    const registry = createHostWebPluginRegistry(deps)
-    const rows = registry.snapshot()
-    expect(rows).toEqual([
-      {
-        id: '@deepseek-ai/dsh-client-connection',
-        url: '/plugins/@deepseek-ai/dsh-client-connection/client.js',
-        inject: [],
-        immediately: true,
-      },
-      {
-        id: '@deepseek-ai/dsh-client-ui-layout',
-        url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js',
-        inject: ['@deepseek-ai/dsh-client-runtime'],
-      },
-    ])
-    expect(registry.clientPath('@deepseek-ai/dsh-client-connection')).toMatch(/lib[/\\]client\.js$/)
+    const graph = registry.graph()
+    expect(graph.rev).toMatch(/^[0-9a-f]{12}$/)
+    const connection = graph.entries[0]
+    expect(connection?.id).toBe('@deepseek-ai/dsh-client-connection')
+    expect(connection?.rev).toMatch(/^[0-9a-f]{12}$/)
+    expect(connection?.url).toBe(`/plugins/@deepseek-ai/dsh-client-connection/client.js?rev=${connection?.rev ?? ''}`)
+    expect(connection?.immediately).toBe(true)
+    const layout = graph.entries[1]
+    expect(layout?.id).toBe('@deepseek-ai/dsh-client-ui-layout')
+    expect(layout?.inject).toEqual(['@deepseek-ai/dsh-client-runtime'])
+    expect(layout?.immediately).toBeUndefined()
+    expect(graph.entries).toHaveLength(2)
+    expect(registry.clientPath('@deepseek-ai/dsh-client-ui-layout')).toMatch(/lib[/\\]client\.js$/)
    expect(registry.clientPath('@deepseek-ai/dsh-agent')).toBeUndefined()
    registry.dispose()
  })
@@ -85,7 +84,7 @@ describe('createHostWebPluginRegistry', () => {
      { name: 'electron-only', pkg: { dshClient: { platform: 'electron' }, exports: { './client': './lib/client.js' } } },
    ])
    const registry = createHostWebPluginRegistry(deps)
-    expect(registry.snapshot()).toEqual([])
+    expect(registry.graph().entries).toEqual([])
    registry.dispose()
  })

@@ -96,6 +95,11 @@ describe('createHostWebPluginRegistry', () => {
    expect(() => createHostWebPluginRegistry(deps)).toThrow(/declares dshClient but exports no/)
  })

+  it('fails loud at build time on a registered bundle that is not built (rev hashing reads the file)', () => {
+    const { deps } = makeDeps([{ name: 'unbuilt', pkg: webDecl(), withBundle: false }])
+    expect(() => createHostWebPluginRegistry(deps)).toThrow(/ENOENT/)
+  })
+
  it('fails loud on malformed declaration fields', () => {
    for (const dshClient of [42, { platform: 7 }, { platform: 'web', inject: 'nope' }, { platform: 'web', immediately: 'yes' }]) {
      const { deps } = makeDeps([{ name: 'bad', pkg: { dshClient, exports: { './client': './lib/client.js' } } }])
@@ -103,26 +107,74 @@ describe('createHostWebPluginRegistry', () => {
    }
  })

-  it('rescans on internal/plugin (debounced) and keeps the old table when a rescan fails', async () => {
+  it('rebuilt(id) re-hashes the bundle, updates the row and graph rev, and keeps the immediately mark', () => {
+    const { deps, root } = makeDeps([{ name: 'hot', pkg: webDecl({ immediately: true }) }])
+    const registry = createHostWebPluginRegistry(deps)
+    const before = registry.graph()
+    const beforeRow = before.entries.find(e => e.id === 'hot')
+    writeFileSync(join(root, 'hot', 'lib', 'client.js'), '// rebuilt bundle contents')
+    const rev = registry.rebuilt('hot')
+    expect(rev).toMatch(/^[0-9a-f]{12}$/)
+    expect(rev).not.toBe(beforeRow?.rev)
+    const after = registry.graph()
+    const afterRow = after.entries.find(e => e.id === 'hot')
+    expect(afterRow?.rev).toBe(rev)
+    expect(afterRow?.url).toBe(`/plugins/hot/client.js?rev=${rev ?? ''}`)
+    expect(afterRow?.immediately).toBe(true)
+    expect(after.rev).not.toBe(before.rev)
+    // Unknown ids are not rebuildable.
+    expect(registry.rebuilt('nope')).toBeUndefined()
+    registry.dispose()
+  })
+
+  it('watch mode: a bundle content change re-hashes the row and notifies onRebuilt; dispose stops the watch', async () => {
+    const { deps, root } = makeDeps([{ name: 'watched', pkg: webDecl() }])
+    deps.watch = { intervalMs: 20 }
+    const registry = createHostWebPluginRegistry(deps)
+    const before = registry.graph().entries[0]?.rev
+    const rebuilds: { id: string; rev: string }[] = []
+    registry.onRebuilt((id, rev) => rebuilds.push({ id, rev }))
+
+    writeFileSync(join(root, 'watched', 'lib', 'client.js'), '// new bundle contents')
+    await vi.waitFor(() => { expect(rebuilds).toHaveLength(1) }, { timeout: 5000 })
+    expect(rebuilds[0]?.id).toBe('watched')
+    expect(rebuilds[0]?.rev).not.toBe(before)
+    expect(registry.graph().entries[0]?.rev).toBe(rebuilds[0]?.rev)
+
+    registry.dispose()
+    writeFileSync(join(root, 'watched', 'lib', 'client.js'), '// post-dispose contents')
+    await new Promise((resolve) => { setTimeout(resolve, 100) })
+    expect(rebuilds).toHaveLength(1)
+  })
+
+  it('rejects a non-positive or non-integer watch interval at build time', () => {
+    for (const intervalMs of [0, -5, 1.5]) {
+      const { deps } = makeDeps([{ name: 'p', pkg: webDecl() }])
+      deps.watch = { intervalMs }
+      expect(() => createHostWebPluginRegistry(deps)).toThrow(/watch\.intervalMs/)
+    }
+  })
+
+  it('rescans on internal/plugin (debounced) and keeps the old graph when a rescan fails', async () => {
    const { deps, entries, errors, ctx } = makeDeps([
      { name: 'late-loader', pkg: webDecl(), loaded: false },
    ])
    const registry = createHostWebPluginRegistry(deps)
-    expect(registry.snapshot()).toEqual([])
+    expect(registry.graph().entries).toEqual([])

    // Entry finishes loading; a fiber lifecycle event triggers the debounced rescan.
    ;(entries[0] as { fiber?: unknown }).fiber = {}
    ctx.emit('internal/plugin', ctx.fiber)
    ctx.emit('internal/plugin', ctx.fiber) // debounce: two emissions, one rescan
    await Promise.resolve()
-    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+    expect(registry.graph().entries.map(row => row.id)).toEqual(['late-loader'])

-    // A failing rescan reports the error and keeps serving the previous table.
+    // A failing rescan reports the error and keeps serving the previous graph.
    entries.push({ options: { name: 'ghost' }, fiber: {}, disabled: false })
    ctx.emit('internal/plugin', ctx.fiber)
    await Promise.resolve()
    expect(errors).toHaveLength(1)
-    expect(registry.snapshot().map(row => row.id)).toEqual(['late-loader'])
+    expect(registry.graph().entries.map(row => row.id)).toEqual(['late-loader'])

    // After dispose, further fiber events no longer rescan.
    registry.dispose()
@@ -134,16 +186,19 @@ describe('createHostWebPluginRegistry', () => {
 })

 describe('injectBootManifest', () => {
-  it('injects the manifest as the first script inside <head> and escapes </script> breakouts', () => {
+  it('injects the graph as the first script inside <head> and escapes </script> breakouts', () => {
    const html = '<html><head><script src="app.js"></script></head><body></body></html>'
-    const out = injectBootManifest(html, [{ id: 'x</script><script>alert(1)', url: '/plugins/x/client.js', inject: [] }])
+    const out = injectBootManifest(html, {
+      rev: 'r1',
+      entries: [{ id: 'x</script><script>alert(1)', url: '/plugins/x/client.js?rev=r2', rev: 'r2' }],
+    })
    expect(out.indexOf('window.__DSH_BOOT__')).toBeLessThan(out.indexOf('app.js'))
    expect(out).not.toContain('</script><script>alert(1)')
    expect(out).toContain('\\u003c/script')
  })

  it('prepends when the page has no <head>', () => {
-    const out = injectBootManifest('<body>x</body>', [])
+    const out = injectBootManifest('<body>x</body>', { rev: 'r0', entries: [] })
    expect(out.startsWith('<script>window.__DSH_BOOT__')).toBe(true)
  })
 })
@@ -181,7 +236,7 @@ describe('clientExportOf shapes (through the registry build)', () => {
    entries.push({ options: { name: 'dup-entry' }, fiber: {}, disabled: false })
    void first
    const registry = createHostWebPluginRegistry(deps)
-    expect(registry.snapshot().filter(r => r.id === 'dup-entry')).toHaveLength(1)
+    expect(registry.graph().entries.filter(r => r.id === 'dup-entry')).toHaveLength(1)
    registry.dispose()
  })

--- a/packages/host/webserver/tests/webserver.spec.ts
+++ b/packages/host/webserver/tests/webserver.spec.ts
@@ -1,6 +1,6 @@
 import { mkdtempSync, mkdirSync, writeFileSync } from 'node:fs'
 import { request as httpRequest } from 'node:http'
-import { createServer as createNetServer, Server as NetServer, type AddressInfo } from 'node:net'
+import { Server as NetServer } from 'node:net'
 import { tmpdir } from 'node:os'
 import { join } from 'node:path'
 import { afterEach, describe, expect, it, vi } from 'vitest'
@@ -8,18 +8,6 @@ import { startWebServer, type RunningWebServer } from '../src/index.ts'

 const MAX_REQUEST_BODY_BYTES = 64 * 1024

-/** Reserve a loopback port for tests that need to address a second server. */
-function freePort(): Promise<number> {
-  return new Promise((resolve, reject) => {
-    const probe = createNetServer()
-    probe.once('error', reject)
-    probe.listen(0, '127.0.0.1', () => {
-      const port = (probe.address() as AddressInfo).port
-      probe.close(() => { resolve(port) })
-    })
-  })
-}
-
 /** dist fixture: index.html + one asset of each MIME class + a subdir. */
 function makeDist(): { distIndex: string; distRoot: string } {
  const distRoot = mkdtempSync(join(tmpdir(), 'dsh-webserver-'))
@@ -112,9 +100,12 @@ async function boot(
  maxRequestBodyBytes = MAX_REQUEST_BODY_BYTES,
 ): Promise<string> {
  const { distIndex } = makeDist()
-  const port = await freePort()
  server = await startWebServer({
-    host: '127.0.0.1', port, distIndex, apiHandler: echoingApi, maxRequestBodyBytes,
+    host: '127.0.0.1',
+    port: 0,
+    distIndex,
+    apiHandler: echoingApi,
+    maxRequestBodyBytes,
  }, onError)
  return `http://127.0.0.1:${String(server.port)}`
 }
@@ -134,7 +125,11 @@ describe('startWebServer', () => {
  it('reports the listening port and closes idempotently', async () => {
    const { distIndex } = makeDist()
    server = await startWebServer({
-      host: '127.0.0.1', port: 0, distIndex, apiHandler: echoingApi, maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+      host: '127.0.0.1',
+      port: 0,
+      distIndex,
+      apiHandler: echoingApi,
+      maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
    }, () => undefined)
    expect(server.port).toBeGreaterThan(0)
    const first = server.close()
@@ -158,7 +153,11 @@ describe('startWebServer', () => {
    const address = vi.spyOn(NetServer.prototype, 'address').mockReturnValue({ address: host, family: 'IPv4', port })
    try {
      const inertServer = await startWebServer({
-        host, port, distIndex, apiHandler: echoingApi, maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+        host,
+        port,
+        distIndex,
+        apiHandler: echoingApi,
+        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
      }, () => undefined)
      expect(listen).toHaveBeenCalledWith(port, host, expect.any(Function))
      await inertServer.close()
@@ -170,12 +169,20 @@ describe('startWebServer', () => {

  it('rejects when the port is already taken', async () => {
    const { distIndex } = makeDist()
-    const port = await freePort()
    server = await startWebServer({
-      host: '127.0.0.1', port, distIndex, apiHandler: echoingApi, maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+      host: '127.0.0.1',
+      port: 0,
+      distIndex,
+      apiHandler: echoingApi,
+      maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
    }, () => undefined)
+    const { port } = server
    await expect(startWebServer({
-      host: '127.0.0.1', port, distIndex, apiHandler: echoingApi, maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+      host: '127.0.0.1',
+      port,
+      distIndex,
+      apiHandler: echoingApi,
+      maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
    }, () => undefined))
      .rejects.toMatchObject({ code: 'EADDRINUSE' })
  })
@@ -219,35 +226,55 @@ describe.skipIf(process.platform === 'win32')('static serving', () => {
  })
 })

-describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injection + bundle endpoint)', () => {
-  const rows = [
-    { id: '@deepseek-ai/dsh-client-connection', url: '/plugins/@deepseek-ai/dsh-client-connection/client.js', inject: [], immediately: true },
-    { id: '@deepseek-ai/dsh-client-ui-layout', url: '/plugins/@deepseek-ai/dsh-client-ui-layout/client.js', inject: ['@deepseek-ai/dsh-client-runtime'] },
-  ]
+describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injection + bundle endpoint + events channel)', () => {
+  const FETCH_ID = '@deepseek-ai/dsh-client-ui-layout'
+  const graphValue = {
+    rev: 'graphrev00001',
+    entries: [
+      { id: '@deepseek-ai/dsh-client-connection', url: '/plugins/@deepseek-ai/dsh-client-connection/client.js?rev=eeee2222ffff', rev: 'eeee2222ffff', immediately: true },
+      { id: FETCH_ID, url: `/plugins/${FETCH_ID}/client.js?rev=aaaa0000bbbb`, rev: 'aaaa0000bbbb', inject: [] },
+    ],
+  }

-  async function bootWithPlugins(): Promise<string> {
+  /** Captures the server's onRebuilt subscription so tests can fire registry notifications by hand. */
+  interface RebuiltHarness {
+    notify: (id: string, rev: string) => void
+    unsubscribed: boolean
+  }
+
+  async function bootWithPlugins(harness?: RebuiltHarness): Promise<string> {
    const { distIndex, distRoot } = makeDist()
    writeFileSync(join(distRoot, 'bundle.js'), 'window.DSHClientProxy.loadPlugin({})')
    const webPlugins = {
-      snapshot: () => rows,
-      clientPath: (id: string) => id === rows[0]?.id ? join(distRoot, 'bundle.js') : undefined,
+      graph: () => graphValue,
+      clientPath: (id: string) => id === FETCH_ID ? join(distRoot, 'bundle.js') : undefined,
+      onRebuilt: (listener: (id: string, rev: string) => void) => {
+        if (harness !== undefined) harness.notify = listener
+        return () => {
+          if (harness !== undefined) harness.unsubscribed = true
+        }
+      },
    }
-    const port = await freePort()
    server = await startWebServer(
      {
-        host: '127.0.0.1', port, distIndex, apiHandler: echoingApi,
-        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES, webPlugins,
-      }, () => undefined,
+        host: '127.0.0.1',
+        port: 0,
+        distIndex,
+        apiHandler: echoingApi,
+        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+        webPlugins,
+      },
+      () => undefined,
    )
    return `http://127.0.0.1:${String(server.port)}`
  }

-  it('injects window.__DSH_BOOT__ into / and SPA fallbacks; asset requests stay verbatim', async () => {
+  it('injects the window.__DSH_BOOT__ graph into / and SPA fallbacks; asset requests stay verbatim', async () => {
    const base = await bootWithPlugins()
    const index = await (await fetch(`${base}/`)).text()
    expect(index).toContain('window.__DSH_BOOT__')
    const manifest = /window\.__DSH_BOOT__ = (.*?)<\/script>/.exec(index)?.[1]
-    expect(JSON.parse(manifest ?? '')).toEqual({ plugins: rows })
+    expect(JSON.parse(manifest ?? '')).toEqual(graphValue)

    const fallback = await (await fetch(`${base}/routes/deep/link`)).text()
    expect(fallback).toContain('window.__DSH_BOOT__')
@@ -257,11 +284,12 @@ describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injecti
    expect(await (await fetch(`${base}/app.js`)).text()).toBe('console.log(1)')
  })

-  it('serves registered client bundles and 404s unknown ids (no SPA fallback)', async () => {
+  it('serves registered client bundles with no-cache (rev query ignored) and 404s unknown ids (no SPA fallback)', async () => {
    const base = await bootWithPlugins()
-    const bundle = await fetch(`${base}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    const bundle = await fetch(`${base}/plugins/${FETCH_ID}/client.js?rev=whatever`)
    expect(bundle.status).toBe(200)
    expect(bundle.headers.get('content-type')).toBe('text/javascript; charset=utf-8')
+    expect(bundle.headers.get('cache-control')).toBe('no-cache')
    expect(await bundle.text()).toContain('DSHClientProxy')

    expect((await fetch(`${base}/plugins/unknown/client.js`)).status).toBe(404)
@@ -270,27 +298,67 @@ describe.skipIf(process.platform === 'win32')('web plugin surfaces (boot injecti
  it('404s a registered id whose bundle file is unreadable (unbuilt dist must fail loud, not fall back to HTML)', async () => {
    const { distIndex } = makeDist()
    const webPlugins = {
-      snapshot: () => rows,
+      graph: () => graphValue,
      clientPath: () => '/nonexistent/lib/client.js',
+      onRebuilt: () => () => undefined,
    }
-    const port = await freePort()
    server = await startWebServer(
      {
-        host: '127.0.0.1', port, distIndex, apiHandler: echoingApi,
-        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES, webPlugins,
-      }, () => undefined,
+        host: '127.0.0.1',
+        port: 0,
+        distIndex,
+        apiHandler: echoingApi,
+        maxRequestBodyBytes: MAX_REQUEST_BODY_BYTES,
+        webPlugins,
+      },
+      () => undefined,
    )
-    const res = await fetch(`http://127.0.0.1:${String(server.port)}/plugins/@deepseek-ai/dsh-client-connection/client.js`)
+    const res = await fetch(`http://127.0.0.1:${String(server.port)}/plugins/${FETCH_ID}/client.js`)
    expect(res.status).toBe(404)
  })

-  it('keeps both surfaces off without the webPlugins option', async () => {
+  it('keeps all plugin surfaces off without the webPlugins option', async () => {
    const base = await boot()
    expect(await (await fetch(`${base}/`)).text()).toBe('<html>INDEX</html>')
-    // No plugin route: falls through to static SPA fallback semantics.
+    // No plugin routes: fall through to static SPA fallback semantics.
    const res = await fetch(`${base}/plugins/x/client.js`)
    expect(res.status).toBe(200)
    expect(await res.text()).toBe('<html>INDEX</html>')
+    const events = await fetch(`${base}/plugins/events`)
+    expect(await events.text()).toBe('<html>INDEX</html>')
+  })
+
+  it('GET /plugins/events opens SSE with the current graph frame; a registry rebuild notification broadcasts', async () => {
+    const harness: RebuiltHarness = { notify: () => { throw new Error('onRebuilt never subscribed') }, unsubscribed: false }
+    const base = await bootWithPlugins(harness)
+    const events = await fetch(`${base}/plugins/events`)
+    expect(events.status).toBe(200)
+    expect(events.headers.get('content-type')).toBe('text/event-stream')
+    const reader = events.body?.getReader()
+    const decoder = new TextDecoder()
+    let buffer = ''
+    async function readUntil(marker: string): Promise<void> {
+      while (!buffer.includes(marker)) {
+        const chunk = await reader?.read()
+        if (chunk?.done !== false) throw new Error('SSE stream ended early')
+        buffer += decoder.decode(chunk.value, { stream: true })
+      }
+    }
+    await readUntil('"type":"graph"')
+    expect(buffer).toContain(': connected')
+    const graphLine = /data: (.*)\n\n/.exec(buffer)?.[1]
+    expect(JSON.parse(graphLine ?? '')).toEqual({ type: 'graph', graph: graphValue })
+
+    // The registry's bundle watch observed a rebuild: the server relays it as an SSE frame.
+    harness.notify(FETCH_ID, 'cccc1111dddd')
+    await readUntil('"type":"rebuilt"')
+    expect(buffer).toContain(JSON.stringify({ type: 'rebuilt', id: FETCH_ID, rev: 'cccc1111dddd' }))
+    await reader?.cancel()
+
+    // Shutdown unsubscribes the relay (no broadcast into a closed channel).
+    await server?.close()
+    server = undefined
+    expect(harness.unsubscribed).toBe(true)
  })
 })