add-ws-frames

name	add-ws-frames
description	Add or modify a WebSocket frame type when WS is genuinely required (bidirectional, binary, or true full-duplex). This is the ONLY place where hand-written TS types are allowed in this project. Keeps the Go struct and TS interface in lock-step so the wire format never drifts.

First, reconsider

OpenAPI 3.x has no concept of WS frames. The whole codegen chain (Go struct → openapi.yaml → schema.ts) does not apply, which is why this is an exception and not the rule.

Before writing WS code, ask:

• Can this be one or many SSE streams? If yes, use add-sse-endpoint instead.
• Is the client-to-server direction just a control command? Then a regular POST + SSE for responses is simpler.

Use WS only when you need either bidirectional streaming with low latency, binary frames, or session state that genuinely belongs on a long-lived socket.

Where things live

• Go side: WS handler under internal/api/ (or a sub-package). Register it on the mux. Note that bare mux.HandleFunc paths are not in OpenAPI — that's expected here.
• TS side: frame interfaces under electron/src/api/ws/. This directory is the documented escape hatch from the "never hand-write TS types" rule.

Workflow

1. Define frame types in Go

Use a single Go file per logical channel, with one struct per frame variant and a wrapper for the discriminated union. The discriminator field convention is type.

// internal/api/ws/<channel>.go
package ws

// IMPORTANT: any change here must be mirrored in
// electron/src/api/ws/<channel>.ts (same file basename).
 ClientFrame  {
    Type            
    Body json.RawMessage 
}

 SubscribeBody  {
    Topic  
}

 ServerFrame  {
    Type            
    Body json.RawMessage 
}

 EventBody  {
    Topic             
    Payload json.RawMessage 
}