Problem
Server-side frame observability lands via the onFrameIn / onFrameOut hooks in the sibling issue. The client side still has no zero-setup way to inspect what the browser is actually sending/receiving over the WebSocket. Downstream consumers have built ad-hoc ChatDebugPanel components with a DebugFrame type that's generic over the wire protocol — that primitive should ship once.
This is a design-needed ticket, not an implementation ticket
Open questions we need to answer before committing to code:
-
Package shape. @workkit/chat is currently backend-only (Cloudflare Workers WebSocket server, no React dependency). Options:
a. Add a @workkit/chat/react sub-export — requires React peer dep, violates "zero runtime overhead" spirit for non-React consumers even though tree-shaking would keep it out.
b. Ship a new @workkit/chat-react package — cleaner separation, more release overhead.
c. Keep the hook in userland and only ship the DebugFrame TYPE from @workkit/chat. Lightweight, but doesn't actually save consumers much.
Preference: (b) — matches how the workspace already splits packages by runtime concern.
-
Scope of the hook. Just frame in/out stream? Or also connection state, heartbeat, reconnect attempts, last-N ring buffer, filter-by-type?
-
Panel component. Ship a styled panel, or just the hook + a headless primitive that consumers style? Headless is more aligned with how the rest of the workspace treats UI (we don't ship styled components anywhere else).
-
Dev-only by default. Should the panel refuse to mount in production builds? Or is that a consumer concern?
Proposed minimum viable shape (for discussion)
```ts
// @workkit/chat-react
const { frames, clear, connectionState } = useChatDebugFrames(socket, {
bufferSize: 100,
include: ["message", "error"], // optional filter
});
```
Why "help wanted"
This is farther from the Workers core than most of the workspace. A contributor who lives in the frontend side of a Workkit app is better positioned to drive the design than I am. Good first-architecture ticket for a frontend-leaning contributor.
Not in scope
- Production telemetry — this is a dev tool, not APM.
- Replay / time-travel debugging — nice-to-have; out of scope for v1.
Problem
Server-side frame observability lands via the
onFrameIn/onFrameOuthooks in the sibling issue. The client side still has no zero-setup way to inspect what the browser is actually sending/receiving over the WebSocket. Downstream consumers have built ad-hocChatDebugPanelcomponents with aDebugFrametype that's generic over the wire protocol — that primitive should ship once.This is a design-needed ticket, not an implementation ticket
Open questions we need to answer before committing to code:
Package shape.
@workkit/chatis currently backend-only (Cloudflare Workers WebSocket server, no React dependency). Options:a. Add a
@workkit/chat/reactsub-export — requires React peer dep, violates "zero runtime overhead" spirit for non-React consumers even though tree-shaking would keep it out.b. Ship a new
@workkit/chat-reactpackage — cleaner separation, more release overhead.c. Keep the hook in userland and only ship the
DebugFrameTYPE from@workkit/chat. Lightweight, but doesn't actually save consumers much.Preference: (b) — matches how the workspace already splits packages by runtime concern.
Scope of the hook. Just frame in/out stream? Or also connection state, heartbeat, reconnect attempts, last-N ring buffer, filter-by-type?
Panel component. Ship a styled panel, or just the hook + a headless primitive that consumers style? Headless is more aligned with how the rest of the workspace treats UI (we don't ship styled components anywhere else).
Dev-only by default. Should the panel refuse to mount in production builds? Or is that a consumer concern?
Proposed minimum viable shape (for discussion)
```ts
// @workkit/chat-react
const { frames, clear, connectionState } = useChatDebugFrames(socket, {
bufferSize: 100,
include: ["message", "error"], // optional filter
});
```
Why "help wanted"
This is farther from the Workers core than most of the workspace. A contributor who lives in the frontend side of a Workkit app is better positioned to drive the design than I am. Good first-architecture ticket for a frontend-leaning contributor.
Not in scope