Merge remote-tracking branch 'origin/main' into copilot/create-waveenv-for-tabbar

sawka · sawka · commit 2bb1f2880f6b · 2026-03-10T20:57:42.000-07:00
diff --git a/.github/copilot-instructions.md b/.github/copilot-instructions.md
@@ -2,22 +2,45 @@
 
 ## Project Rules
 
-Read and follow all guidelines in [`.roo/rules/rules.md`](./.roo/rules/rules.md).
+- See the overview of the project in `.kilocode/rules/overview.md`
+- Read and follow all guidelines in `.kilocode/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. |
+| Skill        | File                                     | 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.                                                                                                         |
+| waveenv      | `.kilocode/skills/waveenv/SKILL.md`      | Guide for creating WaveEnv narrowings in Wave Terminal. Use when writing a named subset type of WaveEnv for a component tree, documenting environmental dependencies, or enabling mock environments for preview/test server usage.          |
+| 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.
+
+---
+
+## Preview Server
+
+To run the standalone component preview (no Electron, no backend required):
+
+```
+task preview
+```
+
+This runs `cd frontend/preview && npx vite` and serves at **http://localhost:7007** (port configured in `frontend/preview/vite.config.ts`).
+
+To build a static preview: `task build:preview`
+
+**Do NOT use any of the following to start the preview — they all launch the full Electron app or serve the wrong content:**
+
+- `npm run dev` — runs `electron-vite dev`, launches Electron
+- `npm run start` — also launches Electron
+- `npx vite` from the repo root — uses the Electron-Vite config, not the preview app
+- Serving the `dist/` directory — the preview app is never built there; it has its own build output
diff --git a/docs/docs/wsh-reference.mdx b/docs/docs/wsh-reference.mdx
@@ -6,6 +6,7 @@ title: "wsh reference"
 
 import { Kbd } from "@site/src/components/kbd";
 import { PlatformProvider, PlatformSelectorButton } from "@site/src/components/platformcontext";
+import { VersionBadge } from "@site/src/components/versionbadge";
 
 <PlatformProvider>
 
@@ -262,6 +263,57 @@ Use `--print` to preview the metadata for any background configuration without a
 
 ---
 
+## badge <VersionBadge version="v0.14.2" />
+
+The `badge` command sets or clears a visual badge indicator on a block or tab header.
+
+```sh
+wsh badge [icon]
+wsh badge --clear
+```
+
+Badges are used to draw attention to a block or tab, such as indicating a process has completed or needs attention. If no icon is provided, it defaults to `circle-small`. Icon names are [Font Awesome](https://fontawesome.com/icons) icon names (without the `fa-` prefix).
+
+Flags:
+
+- `--color string` - set the badge color (CSS color name or hex)
+- `--priority float` - set the badge priority (default 10; higher priority badges take precedence)
+- `--clear` - remove the badge from the block or tab
+- `--beep` - play the system bell sound when setting the badge
+- `--pid int` - watch a PID and automatically clear the badge when it exits (sets default priority to 5)
+- `-b, --block` - target a specific block or tab (same format as `getmeta`)
+
+Examples:
+
+```sh
+# Set a default badge on the current block
+wsh badge
+
+# Set a badge with a custom icon and color
+wsh badge circle-check --color green
+
+# Set a high-priority badge on a specific block
+wsh badge triangle-exclamation --color red --priority 20 -b 2
+
+# Set a badge that clears when a process exits
+wsh badge --pid 12345
+
+# Play the bell and set a badge when done
+wsh badge circle-check --beep
+
+# Clear the badge on the current block
+wsh badge --clear
+
+# Clear the badge on a specific tab
+wsh badge --clear -b tab
+```
+
+:::note
+The `--pid` flag is not supported on Windows.
+:::
+
+---
+
 ## run
 
 The `run` command creates a new terminal command block and executes a specified command within it. The command can be provided either as arguments after `--` or using the `-c` flag. Unless the `-x` or `-X` flags are passed, commands can be re-executed by pressing `Enter` once the command has finished running.
