overmux 0.0.5 → 0.0.6

package/CHANGELOG.md

@@ -1,5 +1,14 @@
 # overmux
 
+## 0.0.6
+
+### Patch Changes
+
+- [`a84e0c8`](https://github.com/richardgill/overmux/commit/a84e0c82d6d259a650af7c52b18dfb79c76562f6) Thanks [@richardgill](https://github.com/richardgill)! - Republish all npm packages with the latest changes.
+
+- Updated dependencies [[`a84e0c8`](https://github.com/richardgill/overmux/commit/a84e0c82d6d259a650af7c52b18dfb79c76562f6)]:
+  - @overmux/keybindings@0.0.4
+
 ## 0.0.5
 
 ### Patch Changes

package/README.md

@@ -2,6 +2,20 @@
 
 Overmux is a local or self-hosted web UI for terminal sessions, agents, and Git workspaces.
 
-Documentation for this exact package version is included in [`docs`](./docs). Run `overmux docs path` to print the absolute path to the installed documentation directory.
+## Installation
 
-Start with [How Overmux Works](./docs/100-introduction/200-how-overmux-works.md) and [Install and Run Overmux](./docs/200-getting-started/100-install-and-run-overmux.md).
+Install the CLI with Mise:
+
+```sh
+mise use --global npm:overmux
+```
+
+Or with pnpm:
+
+```sh
+pnpm add --global overmux
+```
+
+## Documentation
+
+See the [Overmux documentation](./docs/000-index.md).

package/dist/docs/200-getting-started/500-set-up-overmux-with-packages.md

@@ -0,0 +1,42 @@
+---
+title: Set Up with Packages
+---
+
+To understand how Overmux works and how to configure your Overmux, start with the [reference docs](/docs/reference/project-structure). They cover your project structure, configuration, server, and browser UI.
+
+To get the most out of Overmux you'll want to use some packages.
+
+## What are packages?
+
+Packages are building blocks for your Overmux. They can provide server functionality, UI components, or both.
+
+Overmux packages are just standard npm packages you install and use in your Overmux project.
+
+## Packages to start with
+
+### Terminals with xterm and tmux
+
+Use these two packages together to add interactive terminals backed by persistent tmux sessions.
+
+- **[tmux](/docs/packages/tmux)** connects your Overmux to your machine's tmux sessions, windows, and panes. It provides live state, terminal streaming, and operations for controlling tmux, along with React components and hooks for your UI.
+- **[xterm](/docs/packages/xterm)** renders an [xterm.js](https://xtermjs.org/) terminal in your browser. It handles terminal display and input, but doesn't start a shell or manage sessions.
+
+Together, they let you interact with your terminals through Overmux UI while tmux keeps your sessions running when you disconnect.
+
+Follow the package docs for installation and wiring examples.
+
+### Source control with git
+
+The **[git package](/docs/packages/git)** adds repository changes and diffs to your Overmux, with ready-made UI components for browsing them.
+
+You choose which repository paths your server can access. You can also enable actions such as staging, unstaging, and discarding changes; write permissions are off by default.
+
+## Explore more packages
+
+Depending on your setup, you might also want:
+
+- **[Zellij](/docs/packages/zellij)** for a Zellij-backed terminal setup instead of tmux. Experimental; compatibility is not guaranteed.
+- **[Pi](/docs/packages/pi)** for viewing AI agent conversations and interacting with running agents. Experimental; compatibility is not guaranteed.
+- **[JSONL store](/docs/packages/jsonl-store)** for storing schema-validated records in a local file.
+
+Start with the pieces you need. Each package's documentation explains what it provides and how to connect it to your Overmux.

package/dist/docs/400-reference/200-configuration.md

@@ -111,7 +111,7 @@ IDs must be 1-253 lowercase ASCII characters, start and end with a letter or dig
 
 An ID function runs once at startup using the actual listening port. Every address serving the same running instance reports the same ID. Distinct instances need distinct IDs; IDs are not credentials.
 
-See [Deep-link navigation](/docs/reference/client/api#deep-link-navigation) and [`overmux instance`](/docs/reference/cli/instance).
+See [Deep links](./600-client/007-deep-links.md) and [`overmux instance`](/docs/reference/cli/instance).
 
 ### `vite`
 

package/dist/docs/400-reference/500-server/500-api.md

@@ -1,5 +1,5 @@
 ---
-title: Server API
+title: Server API Reference
 ---
 
 ## Server definitions

package/dist/docs/400-reference/600-client/005-setting-up-your-ui.md

@@ -0,0 +1,137 @@
+---
+title: Setting up your UI
+---
+
+Your Overmux UI is a React application served and built with Vite. You own its layout, components, and styles; `OvermuxHost` provides the runtime for Overmux’s client APIs.
+
+Run `overmux init` to generate a starter project with the UI setup below.
+
+## File layout
+
+```text
+overmux.config.ts
+vite.config.ts
+src/ui/
+  index.html
+  main.tsx
+  app.tsx
+  styles.css
+```
+
+## Configure Vite
+
+Set your UI directory as Vite’s root and enable React:
+
+```ts title="vite.config.ts"
+import react from "@vitejs/plugin-react";
+import { defineConfig } from "vite";
+
+export default defineConfig({
+  root: "src/ui",
+  plugins: [react()],
+  build: {
+    emptyOutDir: true,
+    outDir: "../../dist",
+  },
+});
+```
+
+Point your Overmux configuration at this file, keeping your existing server and authentication settings:
+
+```ts title="overmux.config.ts"
+import { defineOvermuxConfig } from "overmux";
+import server from "./src/server/index";
+
+export default defineOvermuxConfig({
+  server,
+  auth: { mode: "cli-login" },
+  vite: "./vite.config.ts",
+  productionWebAssetsDir: "./dist",
+});
+```
+
+Vite’s output directory is relative to its UI root; `productionWebAssetsDir` points to the same directory from your Overmux configuration.
+
+## The HTML entry point
+
+Provide a root element and load your React entry point:
+
+```html title="src/ui/index.html"
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>My Overmux</title>
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/main.tsx"></script>
+  </body>
+</html>
+```
+
+## Mount OvermuxHost
+
+Mount your client definition inside `OvermuxHost`. It supplies the runtime required by hooks such as `useCommand` and `useCommands`.
+
+```tsx title="src/ui/main.tsx"
+import { OvermuxHost } from "overmux/client";
+import { createRoot } from "react-dom/client";
+
+import { client } from "./app";
+import "./styles.css";
+
+const root = document.querySelector("#root");
+if (!root) {
+  throw new Error("Missing root element");
+}
+
+createRoot(root).render(<OvermuxHost definition={client} />);
+```
+
+## Define your client
+
+Use `defineOvermuxClient` to connect your root React component and command registry:
+
+```tsx title="src/ui/app.tsx"
+import { defineOvermuxClient } from "overmux/client";
+
+const App = () => <main>My Overmux UI</main>;
+
+export const client = defineOvermuxClient({
+  component: App,
+  commands: {},
+});
+```
+
+`App` is an ordinary React component. Add your own components, state, and layout, or compose components from ecosystem packages.
+
+Start with an empty command registry. See [Commands](./commands) when you want named actions for menus, command palettes, or keyboard shortcuts.
+
+## Add styles
+
+Import your application CSS from `main.tsx`:
+
+```css title="src/ui/styles.css"
+body {
+  margin: 0;
+  font-family: system-ui, sans-serif;
+}
+
+main {
+  padding: 1rem;
+}
+```
+
+Individual ecosystem components may require additional stylesheet imports.
+
+## Run your Overmux server
+
+Run your instance through Overmux so the UI has access to its server:
+
+```sh
+overmux serve --config ./overmux.config.ts
+```
+
+Open the UI URL shown by the server. Vite updates the UI as you edit your React components and styles.

package/dist/docs/400-reference/600-client/007-deep-links.md

@@ -0,0 +1,87 @@
+---
+title: Deep links
+---
+
+Your Overmux UI is a website, so each page has a URL. Deep links let you open those same routes in a specific Overmux instance using `overmux://` instead of an `http://` web address.
+
+```text
+overmux://work-laptop/my-page?tab=logs
+          instance   UI route
+```
+
+## Instances
+
+An **instance** is one Overmux server. Its ID defaults to `<hostname>-<port>`. Set [`instanceId`](../200-configuration.md#instanceid) in `overmux.config.ts` to give it a stable identity.
+
+The instance ID is not a network address. Desktop remembers how to reach an instance when you connect to it.
+
+Run [`overmux instance --json`](../700-cli/350-instance.md) to get the running server’s `instanceId` and `deepLinkPrefix`.
+
+## Creating links
+
+Append your Overmux UI’s route to the instance’s deep-link prefix.
+
+Server handlers receive `instance` through their context argument:
+
+```ts
+import { defineOperation } from "overmux/server";
+import { z } from "zod";
+
+export const getPageLink = defineOperation({
+  input: z.void(),
+  output: z.string(),
+  handle: (_input, { instance }) =>
+    `${instance.getDeepLinkPrefix()}/my-page?tab=logs`,
+});
+```
+
+In React, use `useInstance` from your `createOvermuxHooks` setup. It re-renders when the server’s identity becomes available or changes:
+
+```tsx
+import { useInstance } from "./overmux";
+
+const PageLink = () => {
+  const instance = useInstance();
+  if (!instance) return null;
+
+  return (
+    <a href={`${instance.deepLinkPrefix}/my-page?tab=logs`}>
+      View logs
+    </a>
+  );
+};
+```
+
+`useInstance()` returns `undefined` until the server identifies itself.
+
+## Routing in your Overmux UI
+
+Your Overmux UI owns routing. We recommend [TanStack Router](https://tanstack.com/router/latest) for routing with React. See [Tech stack recommendations](./300-tech-stack-recommendations.md).
+
+Overmux passes the path, query, and fragment to your client’s `navigate` callback. Connect this callback to your router to navigate without reloading the page. Without that callback, Overmux loads the route normally.
+
+With an existing TanStack Router instance exported from `./router`:
+
+```tsx
+import { RouterProvider } from "@tanstack/react-router";
+import { defineOvermuxClient } from "overmux/client";
+import { router } from "./router";
+
+const App = () => <RouterProvider router={router} />;
+
+export const client = defineOvermuxClient({
+  commands: {},
+  component: App,
+  navigate: (route) => router.navigate({ href: route }),
+});
+```
+
+For `overmux://work-laptop/my-page?tab=logs#latest`, `route` is `/my-page?tab=logs#latest`.
+
+## Opening links
+
+- **Inside your Overmux UI or PWA:** same-instance links navigate locally. No OS protocol handler is needed.
+- **Desktop:** opening a link launches or focuses Desktop. Links can also switch to another known instance after confirmation. Connect to that instance first so Desktop knows its address.
+- **Browser/PWA:** links to different or not-yet-discovered instances are blocked.
+
+Installing the PWA does not register it as an OS-wide `overmux://` handler. Links clicked outside your Overmux UI require Overmux Desktop.

package/dist/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/dist/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/dist/docs/400-reference/600-client/100-api.md

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