overmux 0.0.9 → 0.0.11

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

@@ -255,3 +255,38 @@ export default defineOvermuxDesktopConfig({
   macosTrafficLights: "hidden",
 });
 ```
+
+### `onBeforeInputEvent`
+
+The optional `onBeforeInputEvent` callback exposes Electron's [`before-input-event`](https://www.electronjs.org/docs/latest/api/web-contents#event-before-input-event), receiving the actual Electron `Event`, `Input`, and receiving [`WebContents`](https://www.electronjs.org/docs/latest/api/web-contents).
+
+You can use this callback to intercept Electron key presses.
+
+
+```ts
+import { defineOvermuxDesktopConfig } from "@overmux/desktop";
+
+export default defineOvermuxDesktopConfig({
+  onBeforeInputEvent: ({ event, input, webContents }) => {
+    const key = input.key.toLowerCase();
+    if (
+      process.platform !== "linux" ||
+      input.type !== "keyDown" ||
+      !input.meta ||
+      input.control ||
+      input.alt ||
+      input.shift ||
+      (key !== "c" && key !== "v")
+    ) {
+      return;
+    }
+
+    event.preventDefault();
+    if (key === "c") {
+      webContents.copy();
+    } else {
+      webContents.paste();
+    }
+  },
+});
+```

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

@@ -30,3 +30,7 @@ export const serverConfig = defineOvermuxServer({
 - `open.link`: optional destination to open when the notification is activated. Use an app-relative path starting with `/` or an HTTP(S) URL without credentials.
 
 Each text field and link has a maximum length of 4,096 characters. `send()` returns `Promise<void>`.
+
+## PWA background notifications
+
+Open `/_overmux/settings` on your Overmux server, and enable browser notifications. This requires HTTPS, or localhost for development. See [Hosted pages](../../500-hosted-pages.md) for adding a settings link to your application.

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.9",
+  "version": "0.0.11",
   "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",
@@ -82,7 +82,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "node ../../../scripts/generate-ai-context-docs.ts && rm -rf dist && vite build && vite build --config vite.auth.config.ts && vp pack && node scripts/clean-declarations.ts && node scripts/add-client-styles.mjs && cp -R docs dist/docs",
+    "build": "node ../../../scripts/generate-ai-context-docs.ts && rm -rf dist && vite build && vite build --config vite.auth.config.ts && vite build --config vite.push.config.ts && vp pack && node scripts/clean-declarations.ts && node scripts/add-client-styles.mjs && cp -R docs dist/docs",
     "dev": "pnpm run dev:cli",
     "dev:cli": "node --import jiti/register src/internal/cli/bin.ts serve",
     "serve": "node dist/bin.js serve",

package/src/internal/client/background-notifications.ts

@@ -5,6 +5,8 @@ import {
   backgroundNotificationSubscriptionSchema,
 } from "../shared/index";
 
+import { registerPushWorker } from "./register-push-worker";
+
 const enabledStorageKey = "overmux.backgroundNotificationsEnabled";
 
 export type BackgroundNotificationStatus =
@@ -132,7 +134,7 @@ const removeCurrentSubscription = async () => {
 };
 
 const reconcileBackgroundNotifications = async () => {
-  const registration = await navigator.serviceWorker.ready;
+  const registration = await registerPushWorker();
   const publicKey = await getPublicKey();
   let subscription = await registration.pushManager.getSubscription();
   const subscriptionKey = subscription

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/host/hosted-pages/browser-notification-settings.tsx

@@ -25,6 +25,7 @@ const statusMessage = (status: BackgroundNotificationStatus) => {
 export const BrowserNotificationSettings = () => {
   const [status, setStatus] =
     useState<BackgroundNotificationStatus>("checking");
+  const [error, setError] = useState<string>();
 
   useEffect(() => {
     let active = true;
@@ -35,8 +36,9 @@ export const BrowserNotificationSettings = () => {
             setStatus(next);
           }
         })
-        .catch(() => {
+        .catch((cause: unknown) => {
           if (active) {
+            setError(cause instanceof Error ? cause.message : undefined);
             setStatus("error");
           }
         });
@@ -70,7 +72,8 @@ export const BrowserNotificationSettings = () => {
             ? "denied"
             : "disabled",
       );
-    } catch {
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : undefined);
       setStatus("error");
     }
   }, []);
@@ -80,7 +83,8 @@ export const BrowserNotificationSettings = () => {
       setStatus("checking");
       await disableBackgroundNotifications();
       setStatus("disabled");
-    } catch {
+    } catch (cause) {
+      setError(cause instanceof Error ? cause.message : undefined);
       setStatus("error");
     }
   }, []);
@@ -92,6 +96,7 @@ export const BrowserNotificationSettings = () => {
       <h3>Browser notifications</h3>
       <p aria-live="polite" data-om-background-notifications-status="">
         {statusMessage(status)}
+        {status === "error" && error ? ` ${error}` : null}
       </p>
       <div data-om-hosted-actions="">
         {canEnable ? (

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}</>
+  );
+};