overmux 0.0.8 → 0.0.10

package/docs/100-introduction/300-why-i-built-overmux.md

@@ -19,4 +19,4 @@ I lived in a customized tmux setup. But kept noticing that that the terminal, fo
 
 [Herdr](https://github.com/herdrdev/herdr) (a TUI) and [Orca](https://github.com/stablyai/orca) (web based) offer a decent default experience. But they lack the customizability I love with the terminal and neovim. They use their own muxer implementations and dictate workflows.
 
-This future filled me with existential dread, so I built Overmux to embed my terminal in a Desktop webapp and build my own experience with a mix of tmux terminals + custom web uis.
+This future didn't _spark joy_ for me, so I built Overmux to embed my terminal in a Desktop webapp and build my own experience with a mix of tmux terminals + custom web uis.

package/docs/200-getting-started/200-install-overmux-desktop.md

@@ -22,6 +22,19 @@ Download the ZIP for your Mac from the [Overmux releases](https://github.com/ric
 
 Overmux is not currently signed or notarized. Follow [Apple's instructions for opening an app from an unidentified developer](https://support.apple.com/en-us/102445) to allow it to run.
 
+<details>
+<summary>macOS says Overmux is damaged or the developer cannot be verified</summary>
+
+For quarantine-related blocking, run this **only for a trusted download from [official Overmux releases](https://github.com/richardgill/overmux/releases)**:
+
+```bash
+xattr -dr com.apple.quarantine "$HOME/Applications/Overmux.app"
+```
+
+Use `/Applications/Overmux.app` instead if you installed it there. Then reopen Overmux in Finder.
+
+</details>
+
 ## Linux
 
 Download the AppImage or Debian package from the [Overmux releases](https://github.com/richardgill/overmux/releases).

package/docs/400-reference/500-server/100-resources.md

@@ -73,6 +73,31 @@ When the subscription ends, Overmux calls the cleanup function returned by `subs
 
 The React code stays the same: `useResource({ id: "ls" })`.
 
+### Asynchronous setup
+
+`subscribe` can be synchronous or asynchronous. Both forms return a cleanup function. For example, replace the `ls` resource's `subscribe` handler to resolve the directory's canonical path before watching it:
+
+```ts
+import { watch } from "node:fs";
+import { realpath } from "node:fs/promises";
+
+// Inside the resource definition:
+subscribe: async (_input, invalidate, context) => {
+  const directory = await realpath("/");
+  // The subscription may have ended while resolving the path.
+  context.signal.throwIfAborted();
+
+  const watcher = watch(directory, { signal: context.signal }, () => {
+    invalidate();
+  });
+  return () => watcher.close();
+},
+```
+
+`context.signal` is an `AbortSignal` that Overmux aborts when the client unsubscribes, disconnects, or the server shuts down. Cancellation does not automatically stop an async function: pass the signal to APIs that support it and check it after awaiting setup. Here, `realpath` does not accept a signal, so `throwIfAborted()` prevents starting a watcher if cancellation happened during that work.
+
+Overmux calls the returned cleanup function once, even if setup finishes after cancellation. Cleanup may also be asynchronous. In this example, the signal can close the watcher before Overmux calls cleanup; `watcher.close()` is safe to call again. If setup throws before returning cleanup, your handler must release any resources it already acquired.
+
 ## Derived
 
 Derived resources compute a value from other resources.

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

@@ -47,7 +47,7 @@ A resource definition has a `contract` created with `defineResourceContract({ in
 | Kind | Required handler API |
 | --- | --- |
 | `query` | `read(input, context) => output \| Promise<output>` |
-| `subscription` | `read(input, context)` and `subscribe(input, invalidate, context) => disposer` |
+| `subscription` | `read(input, context)` and `subscribe(input, invalidate, context) => (() => void \| Promise<void>) \| Promise<() => void \| Promise<void>>` |
 | `derived` | `dependencies` and `combine(dependencies) => output` |
 
 ```ts
@@ -69,7 +69,9 @@ const resources = {
 };
 ```
 
-`subscribe` must synchronously return a cleanup function. Overmux calls it when that client subscription, or the server runtime, closes. A derived resource reads the resources named by `dependencies`; invalidating a dependency also invalidates its dependants. See [Resources](./100-resources.md) for contracts, derived dependencies, and invalidation.
+`subscribe` returns a cleanup function, directly or asynchronously. Overmux aborts `context.signal` when the subscription ends, including during setup, on client disconnect, or on server shutdown. Overmux calls the returned cleanup function once, even if setup returns it after cancellation. The cleanup function itself may also be asynchronous. If setup throws before returning cleanup, the handler must release any resources it already acquired. See [Asynchronous setup](./100-resources.md#asynchronous-setup) for an example.
+
+A derived resource reads the resources named by `dependencies`; invalidating a dependency also invalidates its dependants. See [Resources](./100-resources.md) for contracts, derived dependencies, and invalidation.
 
 ## Stream handlers
 

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

@@ -158,32 +158,3 @@ const CommandMenu = () => {
 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/030-native-web-view.md

@@ -0,0 +1,166 @@
+---
+title: Native web views
+---
+
+`NativeWebView` embeds a website in Overmux Desktop using a chrome native webview.
+
+```tsx
+import { NativeWebView } from "overmux/client";
+
+export const Website = () => (
+  <NativeWebView
+    url="https://example.com"
+    style={{ width: "100%", height: 600 }}
+    fallback={
+      <a href="https://example.com" target="_blank" rel="noopener noreferrer">
+        Open website in browser
+      </a>
+    }
+  />
+);
+```
+
+## Props
+
+`NativeWebViewProps` and `NativeWebViewLoadError` are exported from `overmux/client`.
+
+### `url`
+
+**Required.** Type: `string`. The initial website URL.
+
+```tsx
+import { NativeWebView } from "overmux/client";
+
+<NativeWebView url="https://example.com" style={{ height: 600 }} />;
+```
+
+Changing this string navigates; rerendering the same URL preserves in-page navigation. A remount starts again at `url`, retaining cookies and site storage.
+
+A blocked `url` prop clears the native page, including when an HTTP allowance is revoked. Blocked in-page links leave the current page in place. See [`allowedHttpOrigins`](#allowedhttporigins) for permitted destinations.
+
+New-window links open in the system browser, not another embedded surface. The system browser has its own login state. Popup-based authentication flows may therefore not complete inside the embedded view; use in-page sign-in where supported.
+
+### `className`
+
+**Optional.** Type: `string`. No default. Applies a CSS class to the desktop placeholder `div`, not the embedded website.
+
+```tsx
+import { NativeWebView } from "overmux/client";
+
+<NativeWebView
+  url="https://example.com"
+  className="website-pane"
+  style={{ height: 600 }}
+/>;
+```
+
+Define the class in your application's stylesheet. See [Theming and CSS](./theming) for loading styles.
+
+### `style`
+
+**Optional.** Type: `React.CSSProperties`. No default. Applies inline styles to the desktop placeholder `div`.
+
+```tsx
+import { NativeWebView } from "overmux/client";
+
+<NativeWebView
+  url="https://example.com"
+  style={{ width: "100%", height: 600 }}
+/>;
+```
+
+Give the placeholder a **nonzero width and height**. The component has no default height. Desktop follows its rectangular position and size as the layout moves, scrolls or resizes. Hidden and zero-size placeholders hide the native surface without clearing its site data. See [Layout limitations](#layout-limitations) before using overlapping panes or CSS effects.
+
+### `fallback`
+
+**Optional.** Type: `React.ReactNode`. Content shown in browsers, PWAs and desktop versions without native web view support.
+
+```tsx
+import { NativeWebView } from "overmux/client";
+
+<NativeWebView
+  url="https://example.com"
+  style={{ height: 600 }}
+  fallback={
+    <a href="https://example.com" target="_blank" rel="noopener noreferrer">
+      Open website in browser
+    </a>
+  }
+/>;
+```
+
+
+### `onLoadError`
+
+**Optional.** Type: `(error: NativeWebViewLoadError) => void`. No default handler. Receives `{ url, code, message }` for main-page load failures, blocked destinations, invalid configuration or bridge errors.
+
+```tsx
+import { NativeWebView, type NativeWebViewLoadError } from "overmux/client";
+
+const reportLoadError = (error: NativeWebViewLoadError) => console.error(error);
+
+<NativeWebView
+  url="https://example.com"
+  style={{ height: 600 }}
+  onLoadError={reportLoadError}
+/>;
+```
+
+Main-page failures exclude subresource failures and aborted navigation superseded by a newer request.
+
+| Code | Meaning |
+| --- | --- |
+| Numeric string, such as `"-105"` | Chromium load error |
+| `ERR_URL_BLOCKED` | Destination rejected by navigation policy |
+| `ERR_DESKTOP_BRIDGE` | Bridge or configuration failure |
+| `ERR_OPEN_EXTERNAL` | Failed to open the system browser |
+| `ERR_RENDER_PROCESS_GONE` | Native renderer crashed; the surface is destroyed |
+
+Remount to retry after a native renderer crash.
+
+### `allowedHttpOrigins`
+
+**Optional.** Type: `string[]`. Defaults to `[]`. Additional plain-HTTP origins to permit. An origin is the scheme, hostname and port, without a path.
+
+```tsx
+import { NativeWebView } from "overmux/client";
+
+<NativeWebView
+  url="http://devbox.local:3000"
+  style={{ height: 600 }}
+  allowedHttpOrigins={["http://devbox.local:3000"]}
+/>;
+```
+
+HTTPS is allowed. HTTP is allowed for `localhost`, `127.0.0.1` and `[::1]`, plus exact origins in this list. Entries must be HTTP origins, optionally with a trailing slash. Wildcards, credentials, paths, queries and fragments are rejected. Matching includes the port. Other schemes are denied. Policy is enforced in Electron main for requested URLs, page navigation, redirects and new-window links.
+
+### `passthroughBindings`
+
+**Optional.** Type: `readonly ShortcutBinding[]`. Defaults to `[]`. Keyboard bindings to forward to the owning Overmux UI while the embedded page has focus. `ShortcutBinding` is exported from `overmux/client`.
+
+```tsx
+import { NativeWebView } from "overmux/client";
+
+<NativeWebView
+  url="https://example.com"
+  style={{ height: 600 }}
+  passthroughBindings={["Escape", "Control+Shift+X", ["F12", "P", "R"]]}
+/>;
+```
+
+Uses the same binding and chord syntax as [command shortcuts](./shortcuts), but does not require a matching command registration. A chord is a sequence of key presses, such as F12, then P, then R.
+
+Overmux desktop intercepts a completed configured binding before the embedded page receives it and forwards its keyboard input, including modifiers and releases, to the owning Overmux UI. That UI then handles it through its ordinary DOM listeners - for example, a dialog's Escape handler, a local `onKeyDown`, or the normal shortcut host. The embedded page remains sandboxed and receives no Overmux bridge or command capability.
+
+
+## Security and shared sessions
+
+Embedded pages have no Overmux bridge, preload script or Node access. Sandbox, context isolation and web security stay enabled. Permissions and downloads are denied.
+
+All native views across connected Overmux instances share **one persistent desktop browser session**, `persist:overmux-native-web`. Cookies and login state survive unmounting, switching instances and restarting Desktop. This session is separate from Overmux authentication and from the system browser. Unmounting destroys the surface, not site data. Clearing an Overmux instance does not clear native website logins. There is no per-view profile or partition option.
+
+## Layout limitations
+
+Native surfaces paint **above the DOM**, including React modals, menus and dropdowns. Use ordinary, non-overlapping rectangular panes. DOM stacking order, rounded corners, CSS transforms, ancestor clipping and arbitrary CSS effects are not faithfully reproduced. Bounds are clipped to the host window, not arbitrary DOM containers. Avoid layouts that depend on those effects; unmount the view when its native surface must not cover other content.
+
+There is no `visible` prop, toolbar, zoom or history API, overlap coordination, or pane/session restoration. Host document reloads, crashes, instance changes and window destruction also destroy its native surfaces.

package/docs/400-reference/600-client/300-tech-stack-recommendations.md

@@ -8,5 +8,6 @@ We recommend:
 - [TanStack Router](https://tanstack.com/router) for routing.
 - [shadcn/ui](https://ui.shadcn.com/) for UI components.
 - [Zod](https://zod.dev/) for schemas and runtime validation.
+- [@pierre/diffs](https://diffs.com/) for building custom Git diff views.
 
 If your app already uses a different stack, follow its existing conventions.

package/docs/400-reference/700-cli/600-docs.md

@@ -122,7 +122,7 @@ Inspect these files so guidance matches the versions used by the application.
 #### `tech-stack-recommendations`
 
 ```text
-Prefer pnpm as the package manager, TanStack Router for routing, shadcn/ui for UI components, and Zod for schemas and runtime validation. Follow the application's established stack when it already differs.
+Prefer pnpm as the package manager, TanStack Router for routing, shadcn/ui for UI components, and Zod for schemas and runtime validation. For custom Git diff views, prefer @pierre/diffs (https://diffs.com/). Follow the application's established stack when it already differs.
 ```
 
 [//]: # (END GENERATED AI CONTEXT)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overmux",
-  "version": "0.0.8",
+  "version": "0.0.10",
   "license": "MIT",
   "homepage": "https://github.com/richardgill/overmux",
   "repository": {
@@ -53,7 +53,7 @@
     "typescript": "5.9.3",
     "web-push": "3.6.7",
     "ws": "8.21.3",
-    "@overmux/keybindings": "0.0.6"
+    "@overmux/keybindings": "0.0.7"
   },
   "devDependencies": {
     "@playwright/test": "1.58.0",

package/src/internal/client/client-definition.ts

@@ -1,18 +1,23 @@
 import type { OvermuxContrast, OvermuxScheme } from "./theme-scope";
 import type { ComponentType } from "react";
 import {
-  formatKeyBinding,
   keyBindingSchema,
   matchesKeyBinding,
+  shortcutBindingSchema,
   type KeyBinding,
+  type KeySequence,
+  type ShortcutBinding,
+} from "@overmux/keybindings";
+export { formatShortcutBinding } from "@overmux/keybindings";
+export type {
+  KeyBinding,
+  KeySequence,
+  ShortcutBinding,
 } from "@overmux/keybindings";
-export type { KeyBinding } from "@overmux/keybindings";
 import { z } from "zod";
 
 import type { OvermuxServerApi } from "./browser-api";
 
-export type KeySequence = readonly [KeyBinding, KeyBinding, ...KeyBinding[]];
-export type ShortcutBinding = KeyBinding | KeySequence;
 export type ConditionalShortcutBinding = {
   binding: ShortcutBinding;
   when: { media: string };
@@ -23,10 +28,6 @@ export type ChordPrefix = {
   unmatched: "replay-to-focused-input";
 };
 
-const shortcutBindingSchema = z.union([
-  keyBindingSchema,
-  z.array(keyBindingSchema).min(2),
-]);
 const commandBindingSchema = z.union([
   shortcutBindingSchema,
   z.object({
@@ -39,11 +40,6 @@ const chordPrefixSchema = z.object({
   unmatched: z.literal("replay-to-focused-input"),
 });
 
-export const formatShortcutBinding = (binding: ShortcutBinding) =>
-  typeof binding === "string"
-    ? formatKeyBinding(binding)
-    : binding.map(formatKeyBinding).join(" ");
-
 type CommandRunResult = Promise<unknown> | unknown;
 type CommandRun<TServerConfig, TParams> = (input: {
   overmuxServerApi: OvermuxServerApi<TServerConfig>;

package/src/internal/client/host/desktop-host.ts

@@ -1,6 +1,34 @@
+import type { ShortcutBinding } from "@overmux/keybindings";
+
+import type { NativeWebViewLoadError } from "../native-web-view";
+
+// This capability is independently versioned from the host envelope.
+export type NativeWebViewBridge = {
+  version: 1;
+  command: (
+    input:
+      | { type: "create" | "destroy"; id: string }
+      | {
+          type: "configure";
+          id: string;
+          url: string;
+          allowedHttpOrigins: string[];
+          passthroughBindings: readonly ShortcutBinding[];
+        },
+  ) => Promise<void>;
+  setBounds: (
+    id: string,
+    bounds: { x: number; y: number; width: number; height: number },
+  ) => void;
+  onLoadError: (
+    callback: (input: { id: string; error: NativeWebViewLoadError }) => void,
+  ) => () => void;
+};
+
 type DesktopHost = {
   version: 1;
   platform: string;
+  nativeWebView?: NativeWebViewBridge;
   instance?: { report: (identity: { instanceId: string }) => void; version: 1 };
   clipboard?: { writeText: (text: string) => void; version: 1 };
   notifications?: { show: (notification: unknown) => void; version: 1 };
@@ -11,5 +39,3 @@ declare global {
     overmuxHost?: DesktopHost;
   }
 }
-
-export {};

package/src/internal/client/native-web-view.tsx

@@ -0,0 +1,158 @@
+import { useEffect, useRef, type CSSProperties, type ReactNode } from "react";
+
+import type { ShortcutBinding } from "@overmux/keybindings";
+
+import type { NativeWebViewBridge } from "./host/desktop-host";
+
+export type NativeWebViewLoadError = {
+  url: string;
+  code: string;
+  message: string;
+};
+export type NativeWebViewProps = {
+  url: string;
+  className?: string;
+  style?: CSSProperties;
+  fallback?: ReactNode;
+  onLoadError?: (error: NativeWebViewLoadError) => void;
+  allowedHttpOrigins?: string[];
+  passthroughBindings?: readonly ShortcutBinding[];
+};
+
+type MountedView = {
+  id: string;
+  active: boolean;
+  bridge: NativeWebViewBridge;
+  report: (error: NativeWebViewLoadError) => void;
+};
+
+const command = async (
+  view: MountedView,
+  input: Parameters<NativeWebViewBridge["command"]>[0],
+  url: string,
+) => {
+  try {
+    await view.bridge.command(input);
+  } catch (error) {
+    view.report({ url, code: "ERR_DESKTOP_BRIDGE", message: String(error) });
+  }
+};
+
+const trackBounds = (element: HTMLDivElement, view: MountedView) => {
+  let previous = "";
+  let frame = 0;
+  const measure = () => {
+    const rect = element.getBoundingClientRect();
+    const visible =
+      !document.hidden &&
+      element.checkVisibility({
+        opacityProperty: true,
+        visibilityProperty: true,
+      });
+    const bounds = {
+      x: Math.round(rect.x),
+      y: Math.round(rect.y),
+      width: visible ? Math.max(0, Math.round(rect.width)) : 0,
+      height: visible ? Math.max(0, Math.round(rect.height)) : 0,
+    };
+    const key = JSON.stringify(bounds);
+    if (key !== previous) {
+      previous = key;
+      view.bridge.setBounds(view.id, bounds);
+    }
+  };
+  const tick = () => {
+    measure();
+    frame = requestAnimationFrame(tick);
+  };
+  // ResizeObserver alone misses position-only changes (siblings, scrolling and
+  // animation). Sample once per frame, but send IPC only for changed pixel bounds.
+  tick();
+  document.addEventListener("visibilitychange", measure);
+  return () => {
+    cancelAnimationFrame(frame);
+    document.removeEventListener("visibilitychange", measure);
+  };
+};
+
+export const NativeWebView = ({
+  url,
+  className,
+  style,
+  fallback,
+  onLoadError,
+  allowedHttpOrigins = [],
+  passthroughBindings = [],
+}: NativeWebViewProps) => {
+  const bridge =
+    typeof window === "undefined" ||
+    window.overmuxHost?.version !== 1 ||
+    window.overmuxHost.nativeWebView?.version !== 1
+      ? undefined
+      : window.overmuxHost.nativeWebView;
+  const element = useRef<HTMLDivElement>(null);
+  const mounted = useRef<MountedView | undefined>(undefined);
+  const latest = useRef({ url, onLoadError });
+  latest.current = { url, onLoadError };
+  // Equal array contents are not a navigation or a policy change.
+  const origins = JSON.stringify(allowedHttpOrigins);
+  const bindings = JSON.stringify(passthroughBindings);
+
+  useEffect(() => {
+    if (!bridge || !element.current) {
+      return;
+    }
+    const view: MountedView = {
+      id: crypto.randomUUID(),
+      active: true,
+      bridge,
+      report: (error) => {
+        // Keep caller exceptions out of IPC promise chains.
+        queueMicrotask(() => {
+          if (view.active) {
+            latest.current.onLoadError?.(error);
+          }
+        });
+      },
+    };
+    mounted.current = view;
+    const unsubscribe = bridge.onLoadError(({ id, error }) => {
+      if (id === view.id) {
+        view.report(error);
+      }
+    });
+    void command(view, { type: "create", id: view.id }, latest.current.url);
+    const stopTracking = trackBounds(element.current, view);
+    return () => {
+      view.active = false;
+      mounted.current = undefined;
+      stopTracking();
+      unsubscribe();
+      // Creation and destruction are ordered commands, not asynchronous load waits.
+      void command(view, { type: "destroy", id: view.id }, latest.current.url);
+    };
+  }, [bridge]);
+
+  useEffect(() => {
+    const view = mounted.current;
+    if (view) {
+      void command(
+        view,
+        {
+          type: "configure",
+          id: view.id,
+          url,
+          allowedHttpOrigins: JSON.parse(origins) as string[],
+          passthroughBindings: JSON.parse(bindings) as ShortcutBinding[],
+        },
+        url,
+      );
+    }
+  }, [bindings, bridge, url, origins]);
+
+  return bridge ? (
+    <div ref={element} className={className} style={style} />
+  ) : (
+    <>{fallback}</>
+  );
+};