overmux 0.0.10 → 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overmux",
-  "version": "0.0.10",
+  "version": "0.0.11",
   "license": "MIT",
   "homepage": "https://github.com/richardgill/overmux",
   "repository": {
@@ -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/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/push-service-worker.ts

@@ -0,0 +1,118 @@
+import { notificationLinkSchema } from "@overmux/shared";
+import { notificationEventSchema } from "../shared/protocol";
+import {
+  pushNotificationBadgePath,
+  pushNotificationIconPath,
+} from "../shared/routes";
+
+// Only the worker APIs this push-only entry uses. No fetch handler or offline shell.
+type WorkerClient = {
+  url: string;
+  focus: () => Promise<WorkerClient>;
+  navigate: (url: string) => Promise<WorkerClient | null>;
+};
+type LifetimeEvent = { waitUntil: (work: Promise<unknown>) => void };
+type WorkerEvents = {
+  install: LifetimeEvent;
+  push: LifetimeEvent & { data?: { json: () => unknown } };
+  notificationclick: LifetimeEvent & {
+    notification: { close: () => void; data?: { link?: unknown } };
+  };
+};
+const worker = globalThis as unknown as {
+  addEventListener: <Type extends keyof WorkerEvents>(
+    type: Type,
+    listener: (event: WorkerEvents[Type]) => void,
+  ) => void;
+  clients: {
+    matchAll: (options: {
+      includeUncontrolled: boolean;
+      type: "window";
+    }) => Promise<WorkerClient[]>;
+    openWindow: (url: string) => Promise<WorkerClient | null>;
+  };
+  location: Location;
+  registration: {
+    showNotification: (
+      title: string,
+      options: NotificationOptions,
+    ) => Promise<void>;
+  };
+  skipWaiting: () => Promise<void>;
+};
+
+const notificationDestination = (link: unknown) => {
+  const parsed = notificationLinkSchema.safeParse(link);
+  if (!parsed.success) {
+    return undefined;
+  }
+  const destination = new URL(parsed.data, worker.location.origin);
+  // Notification links support relative paths and HTTP URLs, but background clicks
+  // must never send an authenticated PWA window to another origin.
+  return destination.origin === worker.location.origin
+    ? destination.href
+    : undefined;
+};
+
+const focusOrOpen = async (link: unknown) => {
+  const destination = notificationDestination(link);
+  const clients = await worker.clients.matchAll({
+    includeUncontrolled: true,
+    type: "window",
+  });
+  const client =
+    clients.find((candidate) => candidate.url === destination) ??
+    clients.find(
+      (candidate) => new URL(candidate.url).origin === worker.location.origin,
+    );
+  if (!client) {
+    await worker.clients.openWindow(
+      destination ?? new URL("/", worker.location.origin).href,
+    );
+    return;
+  }
+  // Without a safe link, preserve the user's current route. A disappearing client
+  // can return null from navigate; open a fresh window rather than lose the click.
+  const navigated =
+    destination && client.url !== destination
+      ? await client.navigate(destination)
+      : client;
+  if (navigated) {
+    await navigated.focus();
+  } else {
+    await worker.clients.openWindow(destination!);
+  }
+};
+
+worker.addEventListener("install", (event) => {
+  // This worker owns no caches or page traffic, so replacing it need not wait for tabs.
+  event.waitUntil(worker.skipWaiting());
+});
+
+worker.addEventListener("push", (event) => {
+  let input: unknown;
+  try {
+    input = event.data?.json();
+  } catch {
+    return;
+  }
+  const payload = notificationEventSchema.safeParse(input);
+  if (!payload.success) {
+    return;
+  }
+  const { notification } = payload.data;
+  event.waitUntil(
+    worker.registration.showNotification(notification.title, {
+      body: notification.body,
+      // Bypass cached transparent icons after adding the light background.
+      icon: `${pushNotificationIconPath}?v=2`,
+      badge: pushNotificationBadgePath,
+      data: { link: notification.open?.link },
+    }),
+  );
+});
+
+worker.addEventListener("notificationclick", (event) => {
+  event.notification.close();
+  event.waitUntil(focusOrOpen(event.notification.data?.link));
+});

package/src/internal/client/register-push-worker.ts

@@ -0,0 +1,63 @@
+// Bound registration as well as activation: serviceWorker.ready can wait forever
+// when no worker exists, and an installing worker can fail or stall indefinitely.
+export const registerPushWorker = () =>
+  new Promise<ServiceWorkerRegistration>((resolve, reject) => {
+    let watched: ServiceWorker | null = null;
+    let settled = false;
+    const finish = (
+      error?: Error,
+      registration?: ServiceWorkerRegistration,
+    ) => {
+      if (settled) {
+        return;
+      }
+      settled = true;
+      clearTimeout(timeout);
+      watched?.removeEventListener("statechange", onStateChange);
+      if (error) {
+        reject(error);
+      } else {
+        resolve(registration!);
+      }
+    };
+    let registered: ServiceWorkerRegistration | undefined;
+    const onStateChange = () => {
+      if (watched?.state === "activated") {
+        finish(undefined, registered);
+      } else if (watched?.state === "redundant") {
+        finish(
+          new Error("The background notification worker failed to activate"),
+        );
+      }
+    };
+    const timeout = setTimeout(() => {
+      finish(
+        new Error("Timed out starting the background notification worker"),
+      );
+    }, 10_000);
+    void navigator.serviceWorker
+      .register("/sw.js", { scope: "/", updateViaCache: "none" })
+      .then(
+        (registration) => {
+          // The browser registration itself cannot be cancelled; ignore late results.
+          if (settled) {
+            return;
+          }
+          registered = registration;
+          watched =
+            registration.active ??
+            registration.installing ??
+            registration.waiting;
+          if (!watched) {
+            finish(
+              new Error("No background notification worker was installed"),
+            );
+            return;
+          }
+          watched.addEventListener("statechange", onStateChange);
+          onStateChange();
+        },
+        (error: unknown) =>
+          finish(error instanceof Error ? error : new Error(String(error))),
+      );
+  });

package/src/internal/server/http/routes.ts

@@ -1,6 +1,8 @@
 import { serveStatic } from "@hono/node-server/serve-static";
 import type { Handler, Hono, MiddlewareHandler } from "hono";
-import { join } from "node:path";
+import { readFile } from "node:fs/promises";
+import { basename, join } from "node:path";
+import { fileURLToPath } from "node:url";
 
 import {
   createHttpAuthenticationHandlers,
@@ -21,7 +23,11 @@ import { createOperationHandler } from "./operation-handler";
 import { createRequestLoggingMiddleware } from "./request-logging";
 import { createRuntimeManifestHandler } from "./runtime-manifest-handler";
 import { overmuxLogoutPath, overmuxSettingsPath } from "@overmux/shared";
-import { viteInfrastructurePath } from "../../shared/routes";
+import {
+  pushNotificationBadgePath,
+  pushNotificationIconPath,
+  viteInfrastructurePath,
+} from "../../shared/routes";
 
 // Registration order is the public/protected boundary. Authentication state,
 // login, and health are registered before the session gate; runtime APIs and
@@ -105,6 +111,28 @@ export const registerHttpRoutes = ({
       handler: createRequestLoggingMiddleware({ serverLogger }),
     },
     // BEGIN: UNAUTHENTICATED
+    // Public branding must remain fetchable when a push wakes the worker after
+    // session expiry. Serve only these packaged PNGs, never userland assets.
+    ...[pushNotificationIconPath, pushNotificationBadgePath].map(
+      (path): RouteDescriptor => ({
+        method: "GET",
+        path,
+        handler: async (context) => {
+          const asset = await readFile(
+            fileURLToPath(
+              new URL(
+                `../push/${basename(path)}`,
+                import.meta.resolve("overmux"),
+              ),
+            ),
+          );
+          context.header("Cache-Control", "public, max-age=86400");
+          context.header("Content-Type", "image/png");
+          context.header("X-Content-Type-Options", "nosniff");
+          return context.body(new Uint8Array(asset));
+        },
+      }),
+    ),
     {
       method: "GET",
       path: "/_overmux/auth-shell/*",
@@ -138,6 +166,23 @@ export const registerHttpRoutes = ({
       handler: authentication.authenticate,
     },
     // BEGIN: AUTHENTICATED
+    // Runtime-owned in both Vite development and production; never the SPA fallback.
+    {
+      method: "GET",
+      path: "/sw.js",
+      handler: async (context) => {
+        const script = await readFile(
+          fileURLToPath(
+            new URL("../push/sw.js", import.meta.resolve("overmux")),
+          ),
+          "utf8",
+        );
+        context.header("Cache-Control", "no-cache");
+        context.header("Content-Type", "text/javascript; charset=UTF-8");
+        context.header("X-Content-Type-Options", "nosniff");
+        return context.body(script);
+      },
+    },
     {
       method: "POST",
       path: "/api/auth/logout",

package/src/internal/shared/routes.ts

@@ -1,3 +1,5 @@
+export const pushNotificationIconPath = "/_overmux/push/icon.png";
+export const pushNotificationBadgePath = "/_overmux/push/badge.png";
 export const runtimeWebSocketPath = "/api/socket";
 export const viteHmrPath = "/_overmux/vite/hmr";
 export const viteInfrastructurePath = "/_overmux/vite/*";