overmux 0.0.5 → 0.0.6

package/docs/400-reference/600-client/010-commands.md

@@ -0,0 +1,189 @@
+---
+title: Commands
+---
+
+Commands let you centralize a collection of named actions in your Overmux UI, such as “Close pane” or “Open settings”, so you can build a command palette, menu, or similar feature. They could also be triggered by [keyboard shortcuts](./shortcuts) or buttons.
+
+Packages may also provide commands that you can use in your UI.
+
+## Registering a command
+
+Declare a command with `defineCommandRegistry`, then register its behavior inside a React component with `useCommand`.
+
+### Basic registration
+
+The handler can access the component’s state:
+
+```tsx
+import { useState } from "react";
+import {
+  defineCommandRegistry,
+  defineOvermuxClient,
+  useCommand,
+} from "overmux/client";
+import type { serverConfig } from "./server";
+
+const commands = defineCommandRegistry<typeof serverConfig>()({
+  openSettings: {
+    title: "Open settings",
+  },
+});
+
+const App = () => {
+  const [settingsOpen, setSettingsOpen] = useState(false);
+
+  useCommand(commands.openSettings, {
+    run: () => setSettingsOpen(true),
+  });
+
+  return settingsOpen ? <Settings /> : <Workspace />;
+};
+
+export const client = defineOvermuxClient({
+  commands,
+  component: App,
+});
+```
+
+`openSettings` is the command’s ID; `title` is its display name. `Settings` and `Workspace` represent your own components.
+
+The handler is registered while `App` is mounted and removed when it unmounts. Registration does not execute the command.
+
+### Disabling a command
+
+Set `enabled` to prevent execution while keeping the command registered and visible through `useCommands()`:
+
+```tsx
+useCommand(commands.openSettings, {
+  enabled: !settingsOpen,
+  run: () => setSettingsOpen(true),
+});
+```
+
+`enabled` defaults to `true`.
+
+### Passing parameters to a shared handler
+
+Declare `params` with a Zod schema and provide `run` in the registry when the behavior can live outside React:
+
+```tsx
+import { z } from "zod";
+
+const commands = defineCommandRegistry<typeof serverConfig>()({
+  killTmuxPane: {
+    title: "Kill pane",
+    params: z.object({ paneId: z.string() }),
+    run: ({ params, overmuxServerApi }) =>
+      overmuxServerApi.executeOperation("killTmuxPane", params),
+  },
+});
+```
+
+This assumes your server defines a `killTmuxPane` operation accepting `{ paneId: string }`. The handler runs client-side and calls that server operation.
+
+The component supplies the current values:
+
+```tsx
+useCommand(commands.killTmuxPane, {
+  params: { paneId: pane.id },
+});
+```
+
+Parameters are type-checked and validated before execution. A registration can supply its own `run` to override the shared handler; that local handler takes no arguments and can read component state directly.
+
+### Conditional registration
+
+Pass `skipToken` when a parameterized command’s required context is missing:
+
+```tsx
+import { skipToken } from "overmux/client";
+
+useCommand(
+  commands.killTmuxPane,
+  pane ? { params: { paneId: pane.id } } : skipToken,
+);
+```
+
+Unlike `enabled: false`, this skips registration entirely. Without another registration, the command will not appear in `useCommands()`. Keep the hook call unconditional.
+
+### Registering a command in multiple components
+
+Use `element` to associate each registration with a UI region:
+
+```tsx
+const paneRef = useRef<HTMLDivElement>(null);
+
+useCommand(commands.killTmuxPane, {
+  params: { paneId: pane.id },
+  element: paneRef,
+});
+
+return <div ref={paneRef}>...</div>;
+```
+
+Import `useRef` from React. When the command is triggered, Overmux prefers the registration whose element contains keyboard focus. For nested elements, the innermost wins.
+
+If none contains focus, the most recently registered handler wins. `element` is a preference, not a restriction; use `enabled` to control availability. If the selected registration is disabled, nothing runs.
+
+### Adding keyboard shortcuts
+
+Set `defaultBindings` on a command declaration to give it keyboard triggers. See [Shortcuts](./shortcuts) for bindings and client overrides.
+
+## Listing all registered commands
+
+Use `useCommands()` to build a menu or command palette with all your registered commands.
+
+```tsx
+import { useCommands } from "overmux/client";
+
+const CommandMenu = () => {
+  const commands = useCommands();
+
+  return (
+    <div>
+      {commands.map((command) => (
+        <button
+          key={command.id}
+          disabled={!command.enabled}
+          onClick={() => void command.execute()}
+        >
+          {command.title}
+        </button>
+      ))}
+    </div>
+  );
+};
+```
+
+Each entry exposes `id`, `title`, `bindings`, `enabled`, and `execute()`. The list includes disabled commands but excludes commands without a registration.
+
+Each command appears once, even if multiple components register it. `execute()` selects the handler using the current focus and runs it only if enabled.
+
+## Using commands from packages
+
+Packages can export commands to include alongside your own:
+
+```tsx
+import { sourceControlCommands } from "@overmux/git/react";
+
+export const client = defineOvermuxClient({
+  commands: {
+    ...commands,
+    ...sourceControlCommands,
+  },
+  component: App,
+});
+```
+
+Adding commands to the registry does not register their handlers. For this package, pass the commands to `SourceControlView`:
+
+```tsx
+<SourceControlView
+  {...sourceControlProps}
+  commandHandles={sourceControlCommands}
+/>
+```
+
+The view registers handlers for navigating changed files and scrolling diffs. They then appear in `useCommands()` alongside your own registered commands.
+
+Keep command IDs unique when combining registries, and pass the same command objects to the client and the component.

package/docs/400-reference/600-client/020-shortcuts.md

@@ -0,0 +1,171 @@
+---
+title: Shortcuts
+---
+
+Shortcuts trigger [commands](./commands) from the keyboard. Define bindings on commands, then customize them in your client configuration.
+
+## Adding shortcuts
+
+Set `defaultBindings` on a command:
+
+```tsx
+const commands = defineCommandRegistry<typeof serverConfig>()({
+  openSettings: {
+    title: "Open settings",
+    defaultBindings: ["Mod+,"],
+  },
+});
+```
+
+The command must have a registered, enabled handler. See [Registering a command](./commands#registering-a-command).
+
+## Binding syntax
+
+A binding combines optional modifiers with a key:
+
+```tsx
+defaultBindings: ["Mod+K"]
+```
+
+Use `Control`, `Alt`, `Shift`, or `Meta` for explicit modifiers. `Mod` means `Meta` (Command) on macOS and `Control` elsewhere.
+
+Key names include uppercase letters, digits, `F1`–`F12`, and named keys such as `Enter`, `Escape`, `Space`, `Tab`, and `ArrowLeft`. Supported punctuation includes `/`, `[`, `]`, `\`, `=`, `-`, `,`, `.`, `;`, `:`, backtick, `'`, and `§`.
+
+Modifiers use a fixed order: `Control+Alt+Shift+Meta`. With `Mod`, use `Mod+Alt+Shift`. Omit modifiers you do not need.
+
+Use `Shift` with letters, function keys, or named keys, not digits or punctuation. For a colon, use `":"`, not `"Shift+;"`.
+
+Multiple bindings provide alternative ways to trigger the same command:
+
+```tsx
+defaultBindings: ["Mod+K", "F2"]
+```
+
+Bindings match the key reported by the keyboard layout, not a physical key position. Holding a key does not repeatedly execute its command.
+
+## Key sequences (chords)
+
+Nest an array to require keys pressed in order:
+
+```tsx
+defaultBindings: [["F12", "X"]]
+```
+
+Press F12, then X to trigger the command. Each step can include modifiers:
+
+```tsx
+defaultBindings: [["Control+K", "Control+C"]]
+```
+
+Overmux waits up to one second between steps. Escape cancels the pending sequence. A nonmatching key ends it.
+
+Avoid assigning a complete shortcut to another sequence’s prefix: the complete shortcut runs immediately rather than waiting for more keys.
+
+## Overriding shortcuts
+
+Use `shortcutOverrides` in your client configuration, keyed by command ID:
+
+```tsx
+export const client = defineOvermuxClient({
+  commands,
+  component: App,
+  shortcutOverrides: {
+    openSettings: ["Mod+Shift+O"],
+  },
+});
+```
+
+An override replaces all default bindings for that command. An empty array removes its keyboard shortcuts without disabling the command:
+
+```tsx
+shortcutOverrides: {
+  openSettings: [],
+}
+```
+
+## Conditional shortcuts
+
+Wrap a binding with `when.media` to activate it only while a CSS media query matches:
+
+```tsx
+defaultBindings: [
+  {
+    binding: "Mod+,",
+    when: { media: "(min-width: 800px)" },
+  },
+]
+```
+
+Conditional bindings work in both `defaultBindings` and `shortcutOverrides`, and update when the media query changes.
+
+## Text inputs and terminals
+
+Shortcuts do not run while an ordinary input, textarea, select, or editable text element has focus.
+
+Terminals are an exception: modified keys, function keys, and multi-key sequences can trigger commands while typing. Plain single-key shortcuts are also allowed in terminal copy mode.
+
+Matched shortcuts prevent the key’s normal browser or terminal behavior. Browser or operating-system shortcuts that never reach the page cannot be handled by Overmux.
+
+### Replaying unmatched sequences
+
+By default, keys intercepted for an incomplete sequence are discarded when it times out or fails to match.
+
+Configure a prefix to replay those keys into a registered input instead. For example, suppose F12, then X closes a pane:
+
+```tsx
+const commands = defineCommandRegistry<typeof serverConfig>()({
+  closePane: {
+    title: "Close pane",
+    defaultBindings: [["F12", "X"]],
+  },
+});
+```
+
+Enable replay for F12 in your client configuration:
+
+```tsx
+export const client = defineOvermuxClient({
+  commands,
+  component: App,
+  chordPrefixes: [
+    { binding: "F12", unmatched: "replay-to-focused-input" },
+  ],
+});
+```
+
+With the command’s handler registered and enabled, while a terminal has focus:
+
+- **F12 → X:** closes the pane; neither key reaches the terminal.
+- **F12 → Y:** no shortcut matches, so both F12 and Y are forwarded to the terminal.
+- **F12 → wait one second:** F12 is forwarded to the terminal.
+- **F12 → Escape:** cancels; neither key reaches the terminal.
+
+This lets Overmux share a prefix with a terminal application rather than always swallowing it.
+
+The tmux and Zellij terminal components already register replay targets. Custom terminal integrations can register one with:
+
+```tsx
+import { useShortcutInputTarget } from "overmux/client";
+
+useShortcutInputTarget({
+  container: containerRef,
+  input: inputRef,
+});
+```
+
+`container` identifies the focused UI region; `input` receives replayed keyboard events. If regions are nested, the innermost containing focus is selected when the sequence begins. Without a matching input target, intercepted keys cannot be replayed.
+
+## Displaying bindings
+
+Use `formatShortcutBinding` to format a binding for the current platform:
+
+```tsx
+import { formatShortcutBinding } from "overmux/client";
+
+formatShortcutBinding("Mod+K");
+formatShortcutBinding(["F12", "X"]);
+```
+
+On macOS, modifiers appear as symbols such as `⌘`; sequences display their steps separated by spaces.
+
+Entries returned by [`useCommands()`](./commands#listing-all-registered-commands) expose their active, overridden bindings through `bindings`. Format those values to show shortcuts alongside command titles.

package/docs/400-reference/600-client/100-api.md

@@ -1,5 +1,5 @@
 ---
-title: Client API
+title: Client API Reference
 ---
 
 ## defineOvermuxClient

package/docs/400-reference/600-client/200-theming.md

@@ -2,93 +2,208 @@
 title: Theming and CSS
 ---
 
-Your app owns its UI and CSS. Overmux provides scoped component styles and optional CSS variables for customization.
+Your Overmux UI owns its CSS. Overmux provides shared theme variables, light/dark defaults, and theme scopes for individual sections.
 
-## Appearance
+## Load your CSS
 
-Set `appearance` in `defineOvermuxClient({ appearance, commands, component })`. Types are exported from `overmux/client`.
+Import your stylesheet from your browser entry point:
 
-| Property | Values | Default | Behavior |
-| --- | --- | --- | --- |
-| `scheme` | `"light"`, `"dark"`, `"system"` | `"system"` | Selects the fallback palette and CSS `color-scheme`. System follows `prefers-color-scheme`. |
-| `contrast` | `"normal"`, `"high"`, `"auto"` | `"auto"` | High selects system-color fallbacks; auto responds to `prefers-contrast: more`. |
+```tsx
+import { OvermuxHost } from "overmux/client";
+import { createRoot } from "react-dom/client";
+
+import definition from "./app";
+import "./styles.css";
+
+createRoot(document.getElementById("root")!).render(
+  <OvermuxHost definition={definition} />,
+);
+```
 
-Browser forced colors apply regardless of `contrast`, with `forced-color-adjust: auto`. Explicit color tokens override palette fallbacks; test custom colors in each mode. Appearance does not persist preferences or configure third-party themes.
+Overmux components load their own styles automatically. Use ordinary CSS and component `className` props to customize them. Overmux defaults use CSS layers, so normal unlayered application styles take precedence.
 
-## Tokens
+## Choose light or dark
 
-Set public tokens on `:root` for the whole document, or on a theme scope for one subtree. `OvermuxStyle` provides typed inline styles for these tokens alongside React CSS properties.
+Set appearance in your client definition:
 
-| Token | CSS value | Purpose |
-| --- | --- | --- |
-| `--om-color-canvas` | Color | Page background |
-| `--om-color-surface` | Color | Main surface |
-| `--om-color-panel` | Color | Secondary background |
-| `--om-color-fg` | Color | Primary text |
-| `--om-color-muted` | Color | Secondary text |
-| `--om-color-border` | Color | Borders and separators |
-| `--om-color-accent` | Color | Interactive accents |
-| `--om-color-accent-fg` | Color | Foreground on accent backgrounds, where consumed |
-| `--om-color-danger` | Color | Errors and destructive states |
-| `--om-color-success` | Color | Success and added-content states |
-| `--om-font-sans` | Font-family list | Interface text |
-| `--om-font-mono` | Font-family list | Code and diagnostics |
-| `--om-spacing` | Length | Spacing unit; components may scale it |
-| `--om-radius` | Length | Corner radius; components may scale it |
-| `--om-elevation` | Box-shadow | Panel and popover shadows |
-| `--om-focus-ring` | Box-shadow | Focus-ring shadows |
-| `--om-motion-duration` | Time | Transition duration |
+```tsx
+import { defineOvermuxClient } from "overmux/client";
+
+export default defineOvermuxClient({
+  commands: {},
+  component: App,
+  appearance: {
+    scheme: "dark",
+    contrast: "auto",
+  },
+});
+```
 
-Tokens apply only where components consume them. Fallbacks vary by component; runtime palette variables beginning with `--_om-` are private. **Public tokens are not populated with default palette values:** app CSS using `var(--om-color-canvas)` must define it or provide a fallback. Explicit tokens inherit normally and do not change automatically with the scheme.
+- `scheme`: `"system"` (default), `"light"`, or `"dark"`.
+- `contrast`: `"auto"` (default), `"normal"`, or `"high"`.
 
-## `OvermuxThemeScope`
+`"system"` follows the system color preference. `"auto"` follows the system preference for increased contrast.
 
-Import from `overmux/client`. The host already supplies an outer scope; add scopes for local themes or portal placement.
+Appearance applies to your app and Overmux-owned UI inside `OvermuxHost`. It changes built-in defaults, not custom CSS variables.
+
+## Set colors, fonts, and other theme variables
+
+Define shared variables in your stylesheet. This example supplies a custom dark palette and every shared theme variable:
+
+```css
+:root {
+  --om-color-canvas: #111318;
+  --om-color-surface: #191c24;
+  --om-color-panel: #222735;
+  --om-color-fg: #eef0f6;
+  --om-color-muted: #a3adc2;
+  --om-color-border: #394156;
+  --om-color-accent: #b59aff;
+  --om-color-accent-fg: #111318;
+  --om-color-danger: #ff8b82;
+  --om-color-success: #65d6a2;
+
+  --om-font-sans: "Inter", sans-serif;
+  --om-font-mono: "JetBrains Mono", monospace;
+
+  --om-spacing: 0.75rem;
+  --om-radius: 0.5rem;
+  --om-elevation: 0 0.75rem 2rem rgb(0 0 0 / 30%);
+  --om-focus-ring: 0 0 0 3px rgb(181 154 255 / 30%);
+  --om-motion-duration: 120ms;
+}
+```
+
+### Colors
+
+- `--om-color-canvas`: page background.
+- `--om-color-surface`: content surface background.
+- `--om-color-panel`: panel and grouped-content background.
+- `--om-color-fg`: primary text.
+- `--om-color-muted`: secondary text.
+- `--om-color-border`: borders and separators.
+- `--om-color-accent`: highlighted controls and actions.
+- `--om-color-accent-fg`: text on an accent background.
+- `--om-color-danger`: errors and destructive states.
+- `--om-color-success`: success states.
+
+### Fonts
+
+- `--om-font-sans`: interface font family.
+- `--om-font-mono`: monospace font family.
+
+Load custom fonts yourself; these variables only select them.
+
+#### Loading custom fonts
+
+Load fonts with `@font-face`, then reference their family names in your theme variables:
+
+```css
+@font-face {
+  font-family: "My Font";
+  src: url("./fonts/my-font.woff2") format("woff2");
+  font-display: swap;
+}
+
+:root {
+  --om-font-sans: "My Font", sans-serif;
+}
+```
+
+For a monospace font, use the same approach with `--om-font-mono`.
+
+### Spacing and effects
+
+- `--om-spacing`: base spacing used by components.
+- `--om-radius`: base corner radius.
+- `--om-elevation`: elevated-surface box shadow.
+- `--om-focus-ring`: additional focus box shadow.
+- `--om-motion-duration`: transition duration.
+
+Components decide which variables they use.
+
+### Applying your theme
+
+Variables on `:root` reach both your application and Overmux-owned UI, including recovery, update, and settings screens. The separate login screen does not load userland CSS.
+
+Use the same variables in your own components:
+
+```css
+body {
+  margin: 0;
+  background: var(--om-color-canvas);
+}
+
+.panel {
+  color: var(--om-color-fg);
+  background: var(--om-color-surface);
+  border: 1px solid var(--om-color-border);
+  border-radius: var(--om-radius);
+  padding: var(--om-spacing);
+}
+```
+
+Overmux does not paint your application's page background for you.
+
+Public `--om-*` variables are override inputs: Overmux does not populate them with its built-in palette. Define them before using them in your own CSS, or supply CSS fallbacks.
+
+Custom values remain in effect when `scheme` changes. If you supply a custom palette, you also own its light/dark variants and any saved theme preference.
+
+## Theme one section
+
+Wrap a section in `OvermuxThemeScope`:
 
 ```tsx
-<OvermuxThemeScope scheme="light" style={{ "--om-color-accent": "purple" }}>
+import { OvermuxThemeScope } from "overmux/client";
+
+<OvermuxThemeScope
+  scheme="light"
+  contrast="normal"
+  className="preview"
+  style={{ "--om-color-accent": "rebeccapurple" }}
+>
   <Preview />
-</OvermuxThemeScope>
+</OvermuxThemeScope>;
 ```
 
-| Prop | Type | Default |
-| --- | --- | --- |
-| `children` | `ReactNode` | Required |
-| `scheme` | `OvermuxScheme` | `"system"` |
-| `contrast` | `OvermuxContrast` | `"auto"` |
-| `className` | `string` | Unset |
-| `style` | `OvermuxStyle` | Unset |
+The scope renders a wrapper `<div>` and applies appearance to its contents.
 
-Renders a `div` with `data-om-scope`, `data-om-scheme`, `data-om-contrast`, and an internal overlay container. Sets foreground, font family, and `color-scheme`, but does not paint a background.
+Custom CSS variables inherit normally. A light scope inside a custom dark palette will still inherit those custom colors unless you override them.
 
-Nested scopes resolve their own defaults, not their parent's appearance props. Public token overrides still inherit and take precedence over the nested palette. Tokens placed inside the app cannot affect ancestor host UI.
+`OvermuxHost` already creates an application-wide scope. A scope inside your app affects only that section, not surrounding Overmux-owned UI.
 
-## `OvermuxPortal`
+## Keep overlays themed
 
-Import from `overmux/client`. Use `<OvermuxPortal><Popup /></OvermuxPortal>` to render overlays within the nearest theme scope.
+Use `OvermuxPortal` for menus, dialogs, and other overlays:
 
-| Context | Destination |
-| --- | --- |
-| Inside a scope | Nearest scope's internal overlay container |
-| Outside a scope, in a browser | `document.body` |
-| Scope container not mounted, or no document | Nothing rendered |
-| `external={{ container, scopeAttributesAndVariables: "caller-owned" }}` | Supplied element; caller owns its scope attributes and variables |
+```tsx
+import { OvermuxPortal, OvermuxThemeScope } from "overmux/client";
+
+<OvermuxThemeScope scheme="dark">
+  <Editor />
+  <OvermuxPortal>
+    <EditorMenu />
+  </OvermuxPortal>
+</OvermuxThemeScope>;
+```
 
-The overlay container is a sibling of the scope's children. Put shared overlay tokens on the scope, not a descendant around the portal call site. External containers receive no automatic copying of scope attributes or variables. Portals supply placement, not positioning, focus trapping, or dismissal.
+The overlay renders inside the nearest theme scope, preserving its appearance and inherited variables.
 
-## CSS and integrations
+If you supply an external container, you own its theme attributes and CSS variables:
 
-Import app CSS from browser code with `import "./styles.css"`. Theme scopes, the UI package, and Git, Pi, xterm, and Zellij React components import their own styles. Layout, resets, and font loading remain app-owned.
+```tsx
+<OvermuxPortal
+  external={{
+    container: overlayElement,
+    scopeAttributesAndVariables: "caller-owned",
+  }}
+>
+  <EditorMenu />
+</OvermuxPortal>;
+```
 
-Built-in styles use `@scope` and the `om.components` cascade layer, with top-level ordering `theme, base, om`. Normal unlayered app CSS takes precedence over layered styles. Theme rules stop at nested scopes, but global app selectors and inherited properties can still affect components. Browser support for `@scope` and cascade layers is required.
+## Packages
 
-| Component family | Shared styling | Separate configuration |
-| --- | --- | --- |
-| Runtime host UI | Theme tokens where consumed | Client `appearance` |
-| UI split views | Border and accent tokens | App owns pane contents |
-| Git React UI | Colors, fonts, spacing, radius | Diff options and themes; `registerGitDiffTheme` registers custom themes |
-| Pi React UI | Colors, fonts, spacing, radius, elevation | Code highlighting uses Tokyo Night |
-| xterm | Wrapper background: `--om-xterm-terminal-background` | `options.theme` for terminal colors; options such as `fontFamily` for fonts |
-| tmux / Zellij terminal wrappers | xterm wrapper styles | Forwarded xterm props |
+Packages use shared `--om-*` variables where applicable. They may also expose additional CSS variables, `className`, `classNames`, or other styling props.
 
-Scope appearance does not automatically update terminal palettes or syntax-highlighting themes.
+Some rendered content has separate theme options rather than inheriting CSS colors. See each package's documentation for its styling controls.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overmux",
-  "version": "0.0.5",
+  "version": "0.0.6",
   "homepage": "https://github.com/richardgill/overmux",
   "repository": {
     "type": "git",
@@ -52,7 +52,7 @@
     "web-push": "3.6.7",
     "ws": "8.21.3",
     "zod": "4.4.3",
-    "@overmux/keybindings": "0.0.3"
+    "@overmux/keybindings": "0.0.4"
   },
   "devDependencies": {
     "@playwright/test": "1.58.0",