fix(types): keep crossws out of the devframe/types declaration graph

[antfubot]

Problem

@vitejs/devtools v0.7.2 started importing devframe/types from its config surface, and vitejs/vite's strict typecheck CI (skipLibCheck: false) began failing with Cannot find name 'HeadersInit', Cannot find module 'bun', Cannot find module '@cloudflare/workers-types', etc.

The devframe/types declaration graph reached crossws through two type-level imports of the WS peer type:

• src/types/rpc.ts imported the session types from devframe/rpc/transports/ws-server (whose declarations import crossws and crossws/adapters/node)
• src/types/devframe.ts → src/node/auth/handler.ts imported DevframeRpcConnection from the same entry

crossws's own declarations require the DOM, Bun, and Cloudflare type libs, so every downstream consumer of devframe/types inherited that requirement.

Fix

• DevframeRpcConnection.peer / DevframeNodeRpcSessionMeta.peer are now typed by a local structural DevframeWsPeer that mirrors the transport-independent slice of crossws's Peer (id, send, pub/sub, close, backpressure) using only ES lib types. Code needing the full crossws API can still import Peer from crossws and cast, opting into its lib requirements explicitly.
• types/rpc.ts and node/auth/handler.ts import the session types from rpc/transports/session directly, so the bundled dist/types chunk graph no longer touches the ws-server chunk. External type imports of devframe/types are now only birpc, cac, @standard-schema/spec, and nostics.
• New regression test (test/types-lib-neutral.test.ts) typechecks the shipped dist/types/index.d.mts with lib: ES2022 + @types/node only and skipLibCheck: false — the exact failure mode of the Vite CI (verified it reproduces the HeadersInit / bun errors when pointed at a crossws-importing entry).

Note on API surface

tsnapi flags the peer field as narrowed (crossws Peer → structural DevframeWsPeer); the snapshot was updated with TSNAPI_ALLOW_BREAKING=1. A consumer reading peer.request / peer.websocket types-first now needs an explicit crossws cast. The entries that genuinely wrap crossws (rpc/transports/ws-server, ws-bun, ws-deno) keep their real crossws types.

---

This PR was created with the help of an agent.

[coldtea-pr-lens]

◈ PR Lens

🟢 +2 new · 🟠 ~4 changed · 🔴 -1 removed · 0 flows · 6 files · commit fd0e514

Architecture

7 components touched across 4 lanes.

Open the interactive canvas

Inside the changed components — 1 view

Component view — RPC transport and type definitions

Internal structural types and neutrality tests decoupling devframe from crossws

Data flow

No data-flow sequence changed in this PR.

Drill down

Devframe Core Engine — 6 components

🟡 CHANGED Single-Tool Instance Shell

Coordinates devframe runtime state, authentication, and instance lifecycle.

• packages/devframe/package.json:118-122
• packages/devframe/src/node/auth/handler.ts:1-6

🟡 CHANGED Devframe RPC Engine

Manages RPC transports and sessions, now decoupled from third-party WebSocket types.

• packages/devframe/src/rpc/transports/session.ts:1-95
• packages/devframe/src/rpc/transports/ws-server.ts:22-26
• packages/devframe/src/types/rpc.ts:1-16
• packages/devframe/test/types-lib-neutral.test.ts:1-42

🟢 NEW DevframeWsPeer interface

A structural view of the WebSocket peer interface specifying only transport-independent methods and properties.

• packages/devframe/src/rpc/transports/session.ts:1-35

🟡 CHANGED Session transport types

Defines RPC connection, session metadata, and transport kind using the local DevframeWsPeer type.

• packages/devframe/src/rpc/transports/session.ts:37-95
• packages/devframe/src/rpc/transports/ws-server.ts:22-26
• packages/devframe/src/types/rpc.ts:1-16

🟡 CHANGED Auth handler types

Imports DevframeRpcConnection directly from transport session instead of ws-server.

• packages/devframe/src/node/auth/handler.ts:1-6

🟢 NEW Typecheck neutrality test

Uses the TypeScript Compiler API to verify devframe/types compiles with only Node types and skipLibCheck: false.

• packages/devframe/test/types-lib-neutral.test.ts:1-42

Shared Wire Services — 1 component

🔴 REMOVED crossws library

WebSocket engine whose type declarations previously required DOM, Bun, and Cloudflare type libraries in consuming packages.

View

• Architecture lens
• Data flow lens
• Expand every detail
• Show unchanged neighbours

Tip

GitHub will not let you zoom an image in a comment. The link under each diagram opens it on an interactive canvas, where you can zoom, pan and step through the flow.

🪧 More tips

• Run PR Lens on your own machine: npx skills add coldteadotai/pr-lens installs the agent skill. Then tell your coding agent: "Diagram the change you just made with PR Lens and attach it to the pull request."
• Draw a diff before it is even a pull request: npx @coldtea/pr-lens-cli analyze --base origin/main reads the diff with your own model key, and npx @coldtea/pr-lens-cli render .pr-lens/graph.json draws the same lenses on your machine.
• The boxes under View are live. Tick Architecture lens or Data flow lens to choose which diagrams appear, or Expand every detail to open every drill-down at once. The comment redraws in place a few seconds later.
• Show unchanged neighbours lists the components this change did not touch alongside the ones it did, so the drill-down shows what the changed code sits next to.
• The CLI's render picks up .github/pr-lens.yml automatically and applies your corrections (renames, exclusions, lane pins) at draw time.
• Would you rather run it from CI on a key of your own? Add .github/workflows/pr-lens.yml with coldteadotai/pr-lens/packages/action@v0 and a model key in your repository secrets, say GEMINI_API_KEY. The Action asks Gemini by default, or OpenAI and any endpoint speaking /chat/completions through its provider input.
• PR Lens is free for open source. A star on the repository is what keeps it going.
• Push a new commit and the whole comment re-renders for the new head. An older run never overwrites a newer one, so a slow render cannot put a stale diagram back.
• The diagrams follow your GitHub theme, so dark mode gets the dark render and light mode the light one, and the moving dots show this pull request's data in motion.

---

◈ Rendered by PR Lens · crafted with ❤️ by the Coldtea team · Come say hi on Discord

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated
devframe	Ready	Preview	Sep 8, 2026 5:37am UTC