Generate WaveEvent as a typed discriminated union with explicit null payloads for no-data events (#2899)

This updates WaveEvent typing to be event-aware instead of `data?: any`,
while keeping safe fallback behavior for unmapped events. It also
codifies known no-payload events as `null` payloads and documents event
payload expectations alongside the Go event constants.

- **Event registry + payload documentation (Go)**
- Added `AllEvents` in `pkg/wps/wpstypes.go` as the canonical list of
Wave event names.
  - Added/updated inline payload annotations on `Event_*` constants.
- Marked confirmed no-payload events with `// type: none` (e.g.
`route:up`, `route:down`, `workspace:update`, `waveapp:appgoupdated`).

- **Dedicated WaveEvent TS generation path**
- Added `pkg/tsgen/tsgenevent.go` with `event -> reflect.Type` metadata
(`WaveEventDataTypes`).
  - Supports three cases:
    - mapped concrete type → strong TS payload type
    - mapped `nil` → `data?: null` (explicit no-data contract)
    - unmapped event → `data?: any` (non-breaking fallback)

- **Custom WaveEvent output and default suppression**
- Suppressed default struct-based `WaveEvent` emission in
`gotypes.d.ts`.
  - Added generated `frontend/types/waveevent.d.ts` containing:
    - `WaveEventName` string-literal union from `AllEvents`
    - discriminated `WaveEvent` union keyed by `event`.

- **Generator wiring + focused coverage**
- Hooked custom event generation into
`cmd/generatets/main-generatets.go`.
  - Added `pkg/tsgen/tsgenevent_test.go` assertions for:
    - typed mapped events
    - explicit `null` for known no-data events
    - `any` fallback for unmapped events.

```ts
type WaveEvent = {
  event: WaveEventName;
  scopes?: string[];
  sender?: string;
  persist?: number;
  data?: any;
} & (
  { event: "block:jobstatus"; data?: BlockJobStatusData } |
  { event: "route:up"; data?: null } |
  { event: "workspace:update"; data?: null } |
  { event: "some:future:event"; data?: any } // fallback if unmapped
);
```

<!-- START COPILOT CODING AGENT TIPS -->
---

💬 We'd love your input! Share your thoughts on Copilot coding agent in
our [2 minute survey](https://gh.io/copilot-coding-agent-survey).

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: sawka <2722291+sawka@users.noreply.github.com>
Co-authored-by: sawka <mike@commandline.dev>

Author: Copilot

.github/copilot-instructions.md

@@ -0,0 +1,23 @@
+# Wave Terminal — Copilot Instructions
+
+## Project Rules
+
+Read and follow all guidelines in [`.roo/rules/rules.md`](./.roo/rules/rules.md).
+
+---
+
+## Skill Guides
+
+This project uses a set of "skill" guides — focused how-to documents for common implementation tasks. When your task matches one of the descriptions below, **read the linked SKILL.md file before proceeding** and follow its instructions precisely.
+
+| Skill | Description |
+|-------|-------------|
+| [add-config](./.kilocode/skills/add-config/SKILL.md) | Guide for adding new configuration settings to Wave Terminal. Use when adding a new setting to the configuration system, implementing a new config key, or adding user-customizable settings. |
+| [add-rpc](./.kilocode/skills/add-rpc/SKILL.md) | Guide for adding new RPC calls to Wave Terminal. Use when implementing new RPC commands, adding server-client communication methods, or extending the RPC interface with new functionality. |
+| [add-wshcmd](./.kilocode/skills/add-wshcmd/SKILL.md) | Guide for adding new wsh commands to Wave Terminal. Use when implementing new CLI commands, adding command-line functionality, or extending the wsh command interface. |
+| [context-menu](./.kilocode/skills/context-menu/SKILL.md) | Guide for creating and displaying context menus in Wave Terminal. Use when implementing right-click menus, adding context menu items, creating submenus, or handling menu interactions with checkboxes and separators. |
+| [create-view](./.kilocode/skills/create-view/SKILL.md) | Guide for implementing a new view type in Wave Terminal. Use when creating a new view component, implementing the ViewModel interface, registering a new view type in BlockRegistry, or adding a new content type to display within blocks. |
+| [electron-api](./.kilocode/skills/electron-api/SKILL.md) | Guide for adding new Electron APIs to Wave Terminal. Use when implementing new frontend-to-electron communications via preload/IPC. |
+| [wps-events](./.kilocode/skills/wps-events/SKILL.md) | Guide for working with Wave Terminal's WPS (Wave PubSub) event system. Use when implementing new event types, publishing events, subscribing to events, or adding asynchronous communication between components. |
+
+> **How skills work:** Each skill is a self-contained guide covering the exact files to edit, patterns to follow, and steps to take for a specific type of task in this codebase. If your task matches a skill's description, open that SKILL.md and treat it as your primary reference for the implementation.

.kilocode/skills/wps-events/SKILL.md

@@ -40,7 +40,7 @@ const (
     Event_BlockClose       = "blockclose"
     Event_ConnChange       = "connchange"
     // ... other events ...
-    Event_YourNewEvent     = "your:newevent"  // Use colon notation for namespacing
+    Event_YourNewEvent     = "your:newevent"  // type: YourEventData (or "none" if no data)
 )
 ```
 
@@ -49,8 +49,37 @@ const (
 - Use descriptive PascalCase for the constant name with `Event_` prefix
 - Use lowercase with colons for the string value (e.g., "namespace:eventname")
 - Group related events with the same namespace prefix
+- Always add a `// type: <TypeName>` comment; use `// type: none` if no data is sent
 
-### Step 2: Define Event Data Structure (Optional)
+### Step 2: Add to AllEvents
+
+Add your new constant to the `AllEvents` slice in `pkg/wps/wpstypes.go`:
+
+```go
+var AllEvents []string = []string{
+    // ... existing events ...
+    Event_YourNewEvent,
+}
+```
+
+### Step 3: Register in WaveEventDataTypes (REQUIRED)
+
+You **must** add an entry to `WaveEventDataTypes` in `pkg/tsgen/tsgenevent.go`. This drives TypeScript type generation for the event's `data` field:
+
+```go
+var WaveEventDataTypes = map[string]reflect.Type{
+    // ... existing entries ...
+    wps.Event_YourNewEvent: reflect.TypeOf(YourEventData{}),        // value type
+    // wps.Event_YourNewEvent: reflect.TypeOf((*YourEventData)(nil)), // pointer type
+    // wps.Event_YourNewEvent: nil,                                   // no data (type: none)
+}
+```
+
+- Use `reflect.TypeOf(YourType{})` for value types
+- Use `reflect.TypeOf((*YourType)(nil))` for pointer types
+- Use `nil` if no data is sent for the event
+
+### Step 4: Define Event Data Structure (Optional)
 
 If your event carries structured data, define a type for it:
 
@@ -61,7 +90,7 @@ type YourEventData struct {
 }
 ```
 
-### Step 3: Expose Type to Frontend (If Needed)
+### Step 5: Expose Type to Frontend (If Needed)
 
 If your event data type isn't already exposed via an RPC call, you need to add it to `pkg/tsgen/tsgen.go` so TypeScript types are generated:
 
@@ -299,9 +328,11 @@ To debug event flow:
 
 When adding a new event:
 
-- [ ] Add event constant to `pkg/wps/wpstypes.go`
+- [ ] Add event constant to [`pkg/wps/wpstypes.go`](pkg/wps/wpstypes.go) with a `// type: <TypeName>` comment (use `none` if no data)
+- [ ] Add the constant to `AllEvents` in [`pkg/wps/wpstypes.go`](pkg/wps/wpstypes.go)
+- [ ] **REQUIRED**: Add an entry to `WaveEventDataTypes` in [`pkg/tsgen/tsgenevent.go`](pkg/tsgen/tsgenevent.go) — use `nil` for events with no data
 - [ ] Define event data structure (if needed)
-- [ ] Add data type to `pkg/tsgen/tsgen.go` for frontend use
+- [ ] Add data type to `pkg/tsgen/tsgen.go` for frontend use (if not already exposed via RPC)
 - [ ] Run `task generate` to update TypeScript types
 - [ ] Publish events using `wps.Broker.Publish()`
 - [ ] Use goroutines for non-blocking publish when appropriate

.roo/rules/rules.md

@@ -92,7 +92,7 @@ The full API is defined in custom.d.ts as type ElectronApi.
 - **Match response length to question complexity** - For simple, direct questions in Ask mode (especially those that can be answered in 1-2 sentences), provide equally brief answers. Save detailed explanations for complex topics or when explicitly requested.
 - **CRITICAL** - useAtomValue and useAtom are React HOOKS. They cannot be used inline in JSX code, they must appear at the top of a component in the hooks area of the react code.
 - for simple functions, we prefer `if (!cond) { return }; functionality;` pattern overn `if (cond) { functionality }` because it produces less indentation and is easier to follow.
-- It is now 2026, so if you write new files use 2026 for the copyright year
+- It is now 2026, so if you write new files, or update files use 2026 for the copyright year
 
 ### Strict Comment Rules
 

cmd/generatets/main-generatets.go

@@ -21,6 +21,7 @@ func generateTypesFile(tsTypesMap map[reflect.Type]string) error {
 	fileName := "frontend/types/gotypes.d.ts"
 	fmt.Fprintf(os.Stderr, "generating types file to %s\n", fileName)
 	tsgen.GenerateWaveObjTypes(tsTypesMap)
+	tsgen.GenerateWaveEventTypes(tsTypesMap)
 	err := tsgen.GenerateServiceTypes(tsTypesMap)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "Error generating service types: %v\n", err)
@@ -31,7 +32,7 @@ func generateTypesFile(tsTypesMap map[reflect.Type]string) error {
 		return fmt.Errorf("error generating wsh server types: %w", err)
 	}
 	var buf bytes.Buffer
-	fmt.Fprintf(&buf, "// Copyright 2025, Command Line Inc.\n")
+	fmt.Fprintf(&buf, "// Copyright 2026, Command Line Inc.\n")
 	fmt.Fprintf(&buf, "// SPDX-License-Identifier: Apache-2.0\n\n")
 	fmt.Fprintf(&buf, "// generated by cmd/generate/main-generatets.go\n\n")
 	fmt.Fprintf(&buf, "declare global {\n\n")
@@ -62,11 +63,29 @@ func generateTypesFile(tsTypesMap map[reflect.Type]string) error {
 	return err
 }
 
+func generateWaveEventFile(tsTypesMap map[reflect.Type]string) error {
+	fileName := "frontend/types/waveevent.d.ts"
+	fmt.Fprintf(os.Stderr, "generating waveevent file to %s\n", fileName)
+	var buf bytes.Buffer
+	fmt.Fprintf(&buf, "// Copyright 2026, Command Line Inc.\n")
+	fmt.Fprintf(&buf, "// SPDX-License-Identifier: Apache-2.0\n\n")
+	fmt.Fprintf(&buf, "// generated by cmd/generate/main-generatets.go\n\n")
+	fmt.Fprintf(&buf, "declare global {\n\n")
+	fmt.Fprint(&buf, utilfn.IndentString("    ", tsgen.GenerateWaveEventTypes(tsTypesMap)))
+	fmt.Fprintf(&buf, "}\n\n")
+	fmt.Fprintf(&buf, "export {}\n")
+	written, err := utilfn.WriteFileIfDifferent(fileName, buf.Bytes())
+	if !written {
+		fmt.Fprintf(os.Stderr, "no changes to %s\n", fileName)
+	}
+	return err
+}
+
 func generateServicesFile(tsTypesMap map[reflect.Type]string) error {
 	fileName := "frontend/app/store/services.ts"
 	var buf bytes.Buffer
 	fmt.Fprintf(os.Stderr, "generating services file to %s\n", fileName)
-	fmt.Fprintf(&buf, "// Copyright 2025, Command Line Inc.\n")
+	fmt.Fprintf(&buf, "// Copyright 2026, Command Line Inc.\n")
 	fmt.Fprintf(&buf, "// SPDX-License-Identifier: Apache-2.0\n\n")
 	fmt.Fprintf(&buf, "// generated by cmd/generate/main-generatets.go\n\n")
 	fmt.Fprintf(&buf, "import * as WOS from \"./wos\";\n\n")
@@ -89,7 +108,7 @@ func generateWshClientApiFile(tsTypeMap map[reflect.Type]string) error {
 	var buf bytes.Buffer
 	declMap := wshrpc.GenerateWshCommandDeclMap()
 	fmt.Fprintf(os.Stderr, "generating wshclientapi file to %s\n", fileName)
-	fmt.Fprintf(&buf, "// Copyright 2025, Command Line Inc.\n")
+	fmt.Fprintf(&buf, "// Copyright 2026, Command Line Inc.\n")
 	fmt.Fprintf(&buf, "// SPDX-License-Identifier: Apache-2.0\n\n")
 	fmt.Fprintf(&buf, "// generated by cmd/generate/main-generatets.go\n\n")
 	fmt.Fprintf(&buf, "import { WshClient } from \"./wshclient\";\n\n")
@@ -128,6 +147,11 @@ func main() {
 		fmt.Fprintf(os.Stderr, "Error generating services file: %v\n", err)
 		os.Exit(1)
 	}
+	err = generateWaveEventFile(tsTypesMap)
+	if err != nil {
+		fmt.Fprintf(os.Stderr, "Error generating wave event file: %v\n", err)
+		os.Exit(1)
+	}
 	err = generateWshClientApiFile(tsTypesMap)
 	if err != nil {
 		fmt.Fprintf(os.Stderr, "Error generating wshserver file: %v\n", err)

emain/emain-menu.ts

@@ -1,7 +1,7 @@
 // Copyright 2025, Command Line Inc.
 // SPDX-License-Identifier: Apache-2.0
 
-import { waveEventSubscribe } from "@/app/store/wps";
+import { waveEventSubscribeSingle } from "@/app/store/wps";
 import { RpcApi } from "@/app/store/wshclientapi";
 import * as electron from "electron";
 import { fireAndForget } from "../frontend/util/util";
@@ -385,7 +385,7 @@ export function makeAndSetAppMenu() {
 }
 
 function initMenuEventSubscriptions() {
-    waveEventSubscribe({
+    waveEventSubscribeSingle({
         eventType: "workspace:update",
         handler: makeAndSetAppMenu,
     });

frontend/app/store/global.ts

@@ -31,7 +31,7 @@ import { globalStore } from "./jotaiStore";
 import { modalsModel } from "./modalmodel";
 import { ClientService, ObjectService } from "./services";
 import * as WOS from "./wos";
-import { getFileSubject, waveEventSubscribe } from "./wps";
+import { getFileSubject, waveEventSubscribeSingle } from "./wps";
 
 let atoms: GlobalAtomsType;
 let globalEnvironment: "electron" | "renderer";
@@ -198,65 +198,56 @@ function initGlobalAtoms(initOpts: GlobalInitOptions) {
 }
 
 function initGlobalWaveEventSubs(initOpts: WaveInitOpts) {
-    waveEventSubscribe(
-        {
-            eventType: "waveobj:update",
-            handler: (event) => {
-                // console.log("waveobj:update wave event handler", event);
-                const update: WaveObjUpdate = event.data;
-                WOS.updateWaveObject(update);
-            },
+    waveEventSubscribeSingle({
+        eventType: "waveobj:update",
+        handler: (event) => {
+            // console.log("waveobj:update wave event handler", event);
+            WOS.updateWaveObject(event.data);
         },
-        {
-            eventType: "config",
-            handler: (event) => {
-                // console.log("config wave event handler", event);
-                const fullConfig = (event.data as WatcherUpdate).fullconfig;
-                globalStore.set(atoms.fullConfigAtom, fullConfig);
-            },
+    });
+    waveEventSubscribeSingle({
+        eventType: "config",
+        handler: (event) => {
+            // console.log("config wave event handler", event);
+            globalStore.set(atoms.fullConfigAtom, event.data.fullconfig);
         },
-        {
-            eventType: "waveai:modeconfig",
-            handler: (event) => {
-                const modeConfigs = (event.data as AIModeConfigUpdate).configs;
-                globalStore.set(atoms.waveaiModeConfigAtom, modeConfigs);
-            },
+    });
+    waveEventSubscribeSingle({
+        eventType: "waveai:modeconfig",
+        handler: (event) => {
+            globalStore.set(atoms.waveaiModeConfigAtom, event.data.configs);
         },
-        {
-            eventType: "userinput",
-            handler: (event) => {
-                // console.log("userinput event handler", event);
-                const data: UserInputRequest = event.data;
-                modalsModel.pushModal("UserInputModal", { ...data });
-            },
-            scope: initOpts.windowId,
+    });
+    waveEventSubscribeSingle({
+        eventType: "userinput",
+        handler: (event) => {
+            // console.log("userinput event handler", event);
+            modalsModel.pushModal("UserInputModal", { ...event.data });
         },
-        {
-            eventType: "blockfile",
-            handler: (event) => {
-                // console.log("blockfile event update", event);
-                const fileData: WSFileEventData = event.data;
-                const fileSubject = getFileSubject(fileData.zoneid, fileData.filename);
-                if (fileSubject != null) {
-                    fileSubject.next(fileData);
-                }
-            },
+        scope: initOpts.windowId,
+    });
+    waveEventSubscribeSingle({
+        eventType: "blockfile",
+        handler: (event) => {
+            // console.log("blockfile event update", event);
+            const fileSubject = getFileSubject(event.data.zoneid, event.data.filename);
+            if (fileSubject != null) {
+                fileSubject.next(event.data);
+            }
         },
-        {
-            eventType: "waveai:ratelimit",
-            handler: (event) => {
-                const rateLimitInfo: RateLimitInfo = event.data;
-                globalStore.set(atoms.waveAIRateLimitInfoAtom, rateLimitInfo);
-            },
+    });
+    waveEventSubscribeSingle({
+        eventType: "waveai:ratelimit",
+        handler: (event) => {
+            globalStore.set(atoms.waveAIRateLimitInfoAtom, event.data);
         },
-        {
-            eventType: "tab:indicator",
-            handler: (event) => {
-                const data: TabIndicatorEventData = event.data;
-                setTabIndicatorInternal(data.tabid, data.indicator);
-            },
-        }
-    );
+    });
+    waveEventSubscribeSingle({
+        eventType: "tab:indicator",
+        handler: (event) => {
+            setTabIndicatorInternal(event.data.tabid, event.data.indicator);
+        },
+    });
 }
 
 const blockCache = new Map<string, Map<string, any>>();
@@ -762,11 +753,11 @@ async function loadTabIndicators() {
 }
 
 function subscribeToConnEvents() {
-    waveEventSubscribe({
+    waveEventSubscribeSingle({
         eventType: "connchange",
-        handler: (event: WaveEvent) => {
+        handler: (event) => {
             try {
-                const connStatus = event.data as ConnStatus;
+                const connStatus = event.data;
                 if (connStatus == null || isBlank(connStatus.connection)) {
                     return;
                 }
@@ -852,7 +843,7 @@ function setTabIndicator(tabId: string, indicator: TabIndicator) {
         data: {
             tabid: tabId,
             indicator: indicator,
-        } as TabIndicatorEventData,
+        },
     };
     fireAndForget(() => RpcApi.EventPublishCommand(TabRpcClient, eventData));
 }

frontend/app/store/services.ts

@@ -1,4 +1,4 @@
-// Copyright 2025, Command Line Inc.
+// Copyright 2026, Command Line Inc.
 // SPDX-License-Identifier: Apache-2.0
 
 // generated by cmd/generate/main-generatets.go

frontend/app/store/wos.ts

@@ -3,7 +3,7 @@
 
 // WaveObjectStore
 
-import { waveEventSubscribe } from "@/app/store/wps";
+import { waveEventSubscribeSingle } from "@/app/store/wps";
 import { getWebServerEndpoint } from "@/util/endpoints";
 import { fetch } from "@/util/fetchutil";
 import { fireAndForget } from "@/util/util";
@@ -79,7 +79,7 @@ function debugLogBackendCall(methodName: string, durationStr: string, args: any[
 }
 
 function wpsSubscribeToObject(oref: string): () => void {
-    return waveEventSubscribe({
+    return waveEventSubscribeSingle({
         eventType: "waveobj:update",
         scope: oref,
         handler: (event) => {