From a36c641db6e6007fd46b7f1055f8b40ff32dc445 Mon Sep 17 00:00:00 2001
From: imccyu <276526105+imccyu@users.noreply.github.com>
Date: Tue, 4 Aug 2026 16:21:09 +0800
Subject: [PATCH] chore(docs): refresh WebSocket API catalogs

---
 docs/config-catalog.md                         |  4 ++--
 docs/cordis-catalog/services.md                | 10 +++++++++-
 packages/cordis/tool-cordis/src/api-catalog.ts |  8 ++++++++
 scripts/gen-cordis-catalog.ts                  |  2 ++
 4 files changed, 21 insertions(+), 3 deletions(-)

diff --git a/docs/config-catalog.md b/docs/config-catalog.md
index 6d0de60ab9..0c6d58384e 100644
--- a/docs/config-catalog.md
+++ b/docs/config-catalog.md
@@ -296,7 +296,7 @@ export interface ConnectionConfig {
 }
 ```
 
-Source: [`packages/client/connection/src/index.ts:20`](../packages/client/connection/src/index.ts)
+Source: [`packages/client/connection/src/index.ts:21`](../packages/client/connection/src/index.ts)
 
 ## `@deepseek-ai/dsh-client-hmr`
 
@@ -574,7 +574,7 @@ export interface Config {
 }
 ```
 
-Source: [`packages/host/webserver/src/index.ts:39`](../packages/host/webserver/src/index.ts)
+Source: [`packages/host/webserver/src/index.ts:47`](../packages/host/webserver/src/index.ts)
 
 ## `@deepseek-ai/dsh-invariants`
 
diff --git a/docs/cordis-catalog/services.md b/docs/cordis-catalog/services.md
index a713efa09c..cb8cb3b3b2 100644
--- a/docs/cordis-catalog/services.md
+++ b/docs/cordis-catalog/services.md
@@ -770,6 +770,14 @@ The web-shape HTTP carrier service. Activation listens immediately (route regist
  */
 register(route: WebRoute): () => void
 
+/**
+ * Register an exact-path HTTP upgrade route. Duplicate paths throw because
+ * one socket can have only one protocol owner.
+ * @param route - pathname and handler owning negotiation plus socket use.
+ * @returns the disposer removing the route.
+ */
+registerUpgrade(route: WebUpgradeRoute): () => void
+
 /**
  * Register an index.html transform, applied to every index response in
  * registration order.
@@ -779,7 +787,7 @@ register(route: WebRoute): () => void
 tapIndex(transform: (html: string) => string): () => void
 ```
 
-Source: [`packages/host/webserver/src/index.ts:55`](../../packages/host/webserver/src/index.ts)
+Source: [`packages/host/webserver/src/index.ts:63`](../../packages/host/webserver/src/index.ts)
 
 ## `ctx.invariants` — `InvariantService`
 
diff --git a/packages/cordis/tool-cordis/src/api-catalog.ts b/packages/cordis/tool-cordis/src/api-catalog.ts
index 5f9af11105..6efc54849c 100644
--- a/packages/cordis/tool-cordis/src/api-catalog.ts
+++ b/packages/cordis/tool-cordis/src/api-catalog.ts
@@ -388,6 +388,10 @@ export const SERVICE_API: readonly ServiceApiEntry[] = [
         signature: 'register(route: WebRoute): () => void',
         jsDoc: '/**\n * Register a named route. Duplicate (kind, path) throws — route patterns are\n * a composition-level contract, so a collision is a misconfiguration.\n * @param route - kind, path, and the owning handler.\n * @returns the disposer removing the route.\n */',
       },
+      {
+        signature: 'registerUpgrade(route: WebUpgradeRoute): () => void',
+        jsDoc: '/**\n * Register an exact-path HTTP upgrade route. Duplicate paths throw because\n * one socket can have only one protocol owner.\n * @param route - pathname and handler owning negotiation plus socket use.\n * @returns the disposer removing the route.\n */',
+      },
       {
         signature: 'tapIndex(transform: (html: string) => string): () => void',
         jsDoc: '/**\n * Register an index.html transform, applied to every index response in\n * registration order.\n * @param transform - pure html-to-html function.\n * @returns the disposer removing the transform.\n */',
@@ -3129,6 +3133,10 @@ export const TYPE_API: readonly TypeApiEntry[] = [
     name: 'WebSource',
     declaration: 'export interface WebSource {\n    url: string;\n    title?: string;\n    snippet?: string;\n    publishedAt?: string;\n}',
   },
+  {
+    name: 'WebUpgradeRoute',
+    declaration: 'export interface WebUpgradeRoute {\n    path: string;\n    handler: (req: IncomingMessage, socket: Duplex, head: Buffer) => void | Promise<void>;\n}',
+  },
   {
     name: 'WorkflowMeta',
     declaration: 'export interface WorkflowMeta {\n    name: string;\n    description: string;\n    whenToUse?: string;\n    phases?: WorkflowPhase[];\n}',
diff --git a/scripts/gen-cordis-catalog.ts b/scripts/gen-cordis-catalog.ts
index bdbd3a0ceb..4dd381af69 100644
--- a/scripts/gen-cordis-catalog.ts
+++ b/scripts/gen-cordis-catalog.ts
@@ -277,6 +277,8 @@ export const TYPE_LINK_EXEMPTIONS: Readonly<Record<string, string>> = {
   LocaleDict: 'service-local dictionary shape is owned by packages/client/i18n/src/index.ts',
   WebBootGraph: 'web boot graph wire shape is owned by packages/client/modules/src/client/index.ts',
   WebRoute: 'route registration contract is owned by packages/host/webserver/src/index.ts',
+  WebUpgradeRoute:
+    'upgrade route registration contract is owned by packages/host/webserver/src/index.ts',
   ThemeTokens: 'service-local token dictionary is owned by packages/client/ui-theme/src/index.ts',
   Translate: 'service-local bound translator is owned by packages/client/i18n/src/index.ts',
   InvariantRegistration: 'service-local lifecycle handle is owned by packages/support/invariants/README.md',