overmux 0.0.3 → 0.0.5

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

@@ -6,11 +6,6 @@ import {
   matchesKeyBinding,
   type KeyBinding,
 } from "@overmux/keybindings";
-export {
-  formatKeyBinding,
-  keyBindingSchema,
-  matchesKeyBinding,
-} from "@overmux/keybindings";
 export type { KeyBinding } from "@overmux/keybindings";
 import { z } from "zod";
 
@@ -28,18 +23,18 @@ export type ChordPrefix = {
   unmatched: "replay-to-focused-input";
 };
 
-export const shortcutBindingSchema = z.union([
+const shortcutBindingSchema = z.union([
   keyBindingSchema,
   z.array(keyBindingSchema).min(2),
 ]);
-export const commandBindingSchema = z.union([
+const commandBindingSchema = z.union([
   shortcutBindingSchema,
   z.object({
     binding: shortcutBindingSchema,
     when: z.object({ media: z.string().trim().min(1) }),
   }),
 ]);
-export const chordPrefixSchema = z.object({
+const chordPrefixSchema = z.object({
   binding: keyBindingSchema,
   unmatched: z.literal("replay-to-focused-input"),
 });
@@ -132,6 +127,9 @@ export type ClientAppDefinition<
   chordPrefixes?: readonly ChordPrefix[];
   commands: TCommands;
   component: ComponentType;
+  // Receives validated same-instance deep-link routes, including query and fragment.
+  // Defaults to document navigation on the current origin; supply your router to avoid a reload.
+  navigate?: (route: string) => unknown;
   shortcutOverrides?: Partial<
     Record<Extract<keyof TCommands, string>, readonly CommandBinding[]>
   >;

package/src/internal/client/host/deep-link-navigation.ts

@@ -0,0 +1,75 @@
+import { parseDeepLink } from "@overmux/shared";
+import type { ClientTransport } from "../transport";
+import type {} from "./desktop-host";
+
+const defaultNavigate = (route: string) => window.location.assign(route);
+
+/**
+ * Intercepts overmux:// anchor activation inside the running app, including the
+ * temporary anchors created by xterm's default link handler. Without this,
+ * browser/PWA clicks dispatch the custom protocol to the OS, which fails in
+ * Android PWAs where it is not possible to install an Overmux protocol handler.
+ *
+ * Validates the original URL and compares its instance ID with authenticated
+ * runtime discovery. For same-instance links, preventDefault stops OS dispatch
+ * and navigate receives only the local path, query, and fragment. By default,
+ * this loads that route on the current origin; a supplied router callback avoids
+ * a document reload. Instance IDs are never treated as network hostnames.
+ *
+ * Valid cross-instance links remain Desktop's responsibility. Browsers/PWAs
+ * block unknown or different instances; all hosts block invalid links. Ordinary
+ * links and clicks already cancelled by application code are left untouched.
+ * Returns cleanup for the document listeners when the runtime unmounts.
+ */
+export const installDeepLinkNavigation = ({
+  getInstance,
+  navigate = defaultNavigate,
+}: {
+  getInstance: ClientTransport["getInstance"];
+  navigate?: (route: string) => unknown;
+}) => {
+  const onClick = (event: MouseEvent) => {
+    if (event.defaultPrevented || event.button > 1) {
+      return;
+    }
+    const anchor = event
+      .composedPath()
+      .find(
+        (target): target is HTMLAnchorElement =>
+          target instanceof HTMLAnchorElement,
+      );
+    if (anchor?.protocol !== "overmux:") {
+      return;
+    }
+    let link;
+    try {
+      // Inspect the original attribute before URL normalization can hide unsafe text.
+      link = parseDeepLink(anchor.getAttribute("href") ?? "");
+    } catch {
+      event.preventDefault();
+      console.warn("Cannot open an invalid Overmux deep link.");
+      return;
+    }
+    if (link.instanceId !== getInstance()?.instanceId) {
+      // Desktop owns registry lookup and cross-instance confirmation. Browsers must
+      // never interpret an instance ID as a hostname or assume it names this server.
+      if (window.overmuxHost?.version !== 1) {
+        event.preventDefault();
+        console.warn(
+          "Cannot open an Overmux link to an unknown or different instance in this browser.",
+        );
+      }
+      return;
+    }
+    event.preventDefault();
+    navigate(link.route);
+  };
+  // Bubble after application handlers so preventDefault remains an explicit opt-out.
+  // Read identity on activation, not installation: discovery and reconnects can change it.
+  document.addEventListener("click", onClick);
+  document.addEventListener("auxclick", onClick);
+  return () => {
+    document.removeEventListener("click", onClick);
+    document.removeEventListener("auxclick", onClick);
+  };
+};

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

@@ -1,4 +1,7 @@
 type DesktopHost = {
+  version: 1;
+  platform: string;
+  instance?: { report: (identity: { instanceId: string }) => void; version: 1 };
   clipboard?: { writeText: (text: string) => void; version: 1 };
   notifications?: { show: (notification: unknown) => void; version: 1 };
 };

package/src/internal/client/host/environment.ts

@@ -0,0 +1,67 @@
+import "./desktop-host";
+
+type Platform = "macos" | "windows" | "linux" | "android" | "ios" | "unknown";
+type BrowserNavigator = Navigator & {
+  standalone?: boolean;
+  userAgentData?: { platform: string };
+};
+
+const browserPlatform = (navigator: BrowserNavigator): Platform => {
+  const { userAgent, maxTouchPoints } = navigator;
+  const platform = navigator.userAgentData?.platform ?? navigator.platform;
+  const identity = `${platform} ${userAgent}`;
+  // iPadOS can advertise itself as a Mac when requesting desktop websites.
+  if (
+    /iPad|iPhone|iPod/i.test(identity) ||
+    (/Mac/i.test(identity) && maxTouchPoints > 1)
+  ) {
+    return "ios";
+  }
+  if (/Android/i.test(identity)) {
+    return "android";
+  }
+  if (/Win/i.test(identity)) {
+    return "windows";
+  }
+  if (/Mac/i.test(identity)) {
+    return "macos";
+  }
+  return /Linux/i.test(identity) ? "linux" : "unknown";
+};
+
+const desktopPlatform = (platform: string): Platform => {
+  if (platform === "darwin") {
+    return "macos";
+  }
+  if (platform === "win32") {
+    return "windows";
+  }
+  return platform === "linux" ? "linux" : "unknown";
+};
+
+export const installEnvironmentSelectors = () => {
+  const html = document.documentElement;
+  const host = window.overmuxHost;
+  const desktop = host?.version === 1;
+  const navigator: BrowserNavigator = window.navigator;
+  html.dataset.omPlatform = desktop
+    ? desktopPlatform(host.platform)
+    : browserPlatform(navigator);
+  if (desktop) {
+    html.dataset.omHost = "desktop";
+    return () => {};
+  }
+
+  // Fullscreen alone is not evidence of an installed app.
+  const displayMode = window.matchMedia(
+    "(display-mode: standalone), (display-mode: minimal-ui), (display-mode: window-controls-overlay)",
+  );
+  const updateHost = () => {
+    html.dataset.omHost =
+      displayMode.matches || navigator.standalone === true ? "pwa" : "browser";
+  };
+  updateHost();
+  displayMode.addEventListener("change", updateHost);
+  // The document owns these attributes; disposal only releases the live listener.
+  return () => displayMode.removeEventListener("change", updateHost);
+};

package/src/internal/client/host/instance-forwarding.ts

@@ -0,0 +1,21 @@
+import type { ClientTransport } from "../transport";
+import type {} from "./desktop-host";
+
+export const installInstanceForwarding = (transport: ClientTransport) => {
+  const report = () => {
+    const identity = transport.getInstance();
+    const bridge = window.overmuxHost?.instance;
+    if (!identity || bridge?.version !== 1) {
+      return;
+    }
+    try {
+      bridge.report({ instanceId: identity.instanceId });
+    } catch (cause) {
+      // A host integration failure must not interrupt browser discovery or traffic.
+      console.error("Overmux host instance reporting failed", cause);
+    }
+  };
+  const unsubscribe = transport.subscribeInstance(report);
+  report();
+  return unsubscribe;
+};

package/src/internal/client/host/overmux-host.tsx

@@ -21,6 +21,8 @@ import { OvermuxThemeScope } from "../theme-scope";
 import { createOvermuxServerApi } from "../browser-api";
 import { installBrowserLogForwarding } from "./browser-log-forwarding";
 import { installNotificationForwarding } from "./notification-forwarding";
+import { installInstanceForwarding } from "./instance-forwarding";
+import { installDeepLinkNavigation } from "./deep-link-navigation";
 import type { ClientAppDefinition } from "../client-definition";
 import { type RegisteredCommand, RuntimeContext } from "../commands";
 import { ShortcutHost } from "../shortcuts";
@@ -29,6 +31,12 @@ import { HostedLogoutPage } from "./hosted-pages/logout-page";
 import { HostedSettingsPage } from "./hosted-pages/settings-page";
 import { RecoveryScreen } from "./recovery-screen";
 import { UpdatePopover } from "./update-popover";
+import { installEnvironmentSelectors } from "./environment";
+
+// Userland owns createRoot. Initialize on import, before any React tree mounts.
+const disposeEnvironment =
+  typeof window === "undefined" ? undefined : installEnvironmentSelectors();
+import.meta.hot?.dispose(() => disposeEnvironment?.());
 
 type ErrorBoundaryProps = {
   children: ReactNode;
@@ -129,6 +137,15 @@ const OvermuxRuntime = ({
     [transport],
   );
   useEffect(() => installNotificationForwarding(transport), [transport]);
+  useEffect(() => installInstanceForwarding(transport), [transport]);
+  useEffect(
+    () =>
+      installDeepLinkNavigation({
+        getInstance: transport.getInstance,
+        navigate: definition.navigate,
+      }),
+    [transport, definition.navigate],
+  );
   const refreshCommands = useCallback(
     () => setRegistrationRevision((revision) => revision + 1),
     [],

package/src/internal/client/index.ts

@@ -19,15 +19,9 @@ export type {
   OvermuxThemeToken,
 } from "./theme-scope";
 export {
-  chordPrefixSchema,
-  commandBindingSchema,
   defineCommandRegistry,
   defineOvermuxClient,
-  formatKeyBinding,
   formatShortcutBinding,
-  keyBindingSchema,
-  matchesKeyBinding,
-  shortcutBindingSchema,
 } from "./client-definition";
 export { skipToken, useCommand, useCommands } from "./commands";
 export { useShortcutInputTarget } from "./shortcuts";

package/src/internal/client/overmux-react.ts

@@ -1,11 +1,21 @@
-import type { ContractInputArguments } from "../../public/index";
+import type {
+  ContractInputArguments,
+  InstanceIdentity,
+} from "../../public/index";
 import {
   useMutation,
   useQuery,
   useQueryClient,
   type UseMutationResult,
 } from "@tanstack/react-query";
-import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import {
+  useCallback,
+  useEffect,
+  useMemo,
+  useRef,
+  useState,
+  useSyncExternalStore,
+} from "react";
 import type { z } from "zod";
 
 import { skipToken, type SkipToken, useRuntime } from "./commands";
@@ -89,6 +99,10 @@ export type ResourceResult<T> =
     };
 
 export type StreamResult<TClientMessage, TServerMessage> = {
+  // Identifies one server-confirmed stream lifetime, not this hook or its stable methods.
+  // Undefined until stream-opened; reconnects and effect restarts receive a fresh identity.
+  // Replacement renders report opening, never readiness inherited from the old stream.
+  connectionId: symbol | undefined;
   close: () => void;
   error?: Error;
   send: (message: TClientMessage) => boolean;
@@ -190,71 +204,110 @@ const useStreamById = <TClientMessage, TServerMessage>(
 ): StreamResult<TClientMessage, TServerMessage> => {
   const { manifest, overmuxServerApi } = useRuntime();
   const streamAvailable = manifest.streams.includes(id);
+  const canonicalInput = useCanonicalInput(input);
+  // This scope owns the stream-opening effect. Fast Refresh invalidates the memo
+  // and restarts that effect; the previous scope's open state is never exposed as
+  // readiness for the replacement, even before its passive effect has run.
+  const scope = useMemo(
+    () => ({ canonicalInput, id, overmuxServerApi, streamAvailable }),
+    [canonicalInput, id, overmuxServerApi, streamAvailable],
+  );
   const [state, setState] = useState<{
+    scope: typeof scope;
+    connectionId?: symbol;
     error?: Error;
     status: "closed" | "open" | "opening";
-  }>({ status: "opening" });
-  const listeners = useMemo(
+  }>({ scope, status: "opening" });
+  // Unlike memoized callbacks, state survives Fast Refresh. Existing consumers
+  // keep their subscriptions and methods while the real stream lifetime changes.
+  const [listeners] = useState(
     () => new Set<(message: TServerMessage) => void>(),
-    [],
   );
-  const canonicalInput = useCanonicalInput(input);
   const streamRef = useRef<
     ReturnType<typeof overmuxServerApi.openStream> | undefined
   >(undefined);
   useEffect(() => {
     streamRef.current?.close();
     streamRef.current = undefined;
-    if (!streamAvailable) {
-      setState({ status: "closed" });
+    if (!scope.streamAvailable) {
+      setState({ scope, status: "closed" });
       return;
     }
-    setState({ status: "opening" });
-    const stream = overmuxServerApi.openStream({
-      id,
-      input: canonicalInput,
-      onClose: () => setState({ status: "closed" }),
-      onError: (error) => setState({ error, status: "closed" }),
-      onOpen: () => setState({ status: "open" }),
+    setState({ scope, status: "opening" });
+    let active = true;
+    const stream = scope.overmuxServerApi.openStream({
+      id: scope.id,
+      input: scope.canonicalInput,
+      onClose: () => active && setState({ scope, status: "closed" }),
+      onError: (error) =>
+        active && setState({ scope, error, status: "closed" }),
+      // The transport reuses its handle on reconnect, but acknowledges a new server stream.
+      onOpen: () =>
+        active &&
+        setState({ scope, connectionId: Symbol(scope.id), status: "open" }),
       onMessage: (message) =>
+        active &&
         listeners.forEach((listener) => listener(message as TServerMessage)),
     });
-    streamRef.current = stream;
-    return () => {
-      stream.close();
-      if (streamRef.current === stream) {
-        streamRef.current = undefined;
-      }
+    const connection = {
+      close: () => {
+        if (!active) {
+          return;
+        }
+        // Old callbacks must not overwrite the stream created by an effect restart (including HMR).
+        active = false;
+        if (streamRef.current === connection) {
+          streamRef.current = undefined;
+        }
+        setState({ scope, status: "closed" });
+        stream.close();
+      },
+      send: stream.send,
     };
-  }, [canonicalInput, id, listeners, overmuxServerApi, streamAvailable]);
-  const close = useCallback(() => {
-    streamRef.current?.close();
-    streamRef.current = undefined;
-    setState({ status: "closed" });
-  }, []);
-  const send = useCallback(
-    (message: TClientMessage) => streamRef.current?.send(message) ?? false,
-    [],
-  );
-  const subscribe = useCallback(
-    (listener: (message: TServerMessage) => void) => {
+    streamRef.current = connection;
+    return connection.close;
+  }, [listeners, scope]);
+  const [methods] = useState(() => ({
+    close: () => streamRef.current?.close(),
+    send: (message: TClientMessage) =>
+      streamRef.current?.send(message) ?? false,
+    subscribe: (listener: (message: TServerMessage) => void) => {
       listeners.add(listener);
       return () => listeners.delete(listener);
     },
-    [listeners],
-  );
+  }));
+  if (!streamAvailable) {
+    return {
+      ...methods,
+      connectionId: undefined,
+      error: new Error(`Stream is not available: ${id}`),
+      status: "closed",
+    };
+  }
+  if (state.scope !== scope) {
+    return { ...methods, connectionId: undefined, status: "opening" };
+  }
   return {
-    close,
-    error: streamAvailable
-      ? state.error
-      : new Error(`Stream is not available: ${id}`),
-    send,
-    status: streamAvailable ? state.status : "closed",
-    subscribe,
+    ...methods,
+    connectionId: state.connectionId,
+    error: state.error,
+    status: state.status,
   };
 };
 
+const undiscoveredInstance = () => undefined;
+
+const useInstance = (): InstanceIdentity | undefined => {
+  const { overmuxServerApi } = useRuntime();
+  return useSyncExternalStore(
+    overmuxServerApi.subscribeInstance,
+    overmuxServerApi.getInstance,
+    undiscoveredInstance,
+  );
+};
+
 export const createOvermuxHooks = <TServerConfig>() => ({
+  useInstance,
   useOperation: <TId extends Extract<keyof Operations<TServerConfig>, string>>({
     id,
     signal,

package/src/internal/client/websocket.ts

@@ -1,5 +1,7 @@
 import {
   clientProtocolMessageSchema,
+  createInstanceIdentity,
+  type InstanceIdentity,
   decodeProtocolFrame,
   encodeProtocolMessage,
   serverProtocolMessageSchema,
@@ -42,6 +44,8 @@ export type TransportStatus =
   | "disconnected";
 
 export type WebSocketTransport = {
+  getInstance: () => InstanceIdentity | undefined;
+  subscribeInstance: (listener: () => void) => () => void;
   activate: () => void;
   dispose: () => void;
   openStream: (input: {
@@ -99,6 +103,12 @@ export const createWebSocketTransport = ({
   let reconnectTimer: ReturnType<typeof setTimeout> | undefined;
   let socket: WebSocket | undefined;
   let status: TransportStatus = "disconnected";
+  let instance: InstanceIdentity | undefined;
+  const instanceListeners = new Set<() => void>();
+  const setInstance = (next: InstanceIdentity | undefined) => {
+    instance = next;
+    instanceListeners.forEach((listener) => listener());
+  };
   const diagnosticQueue: ClientDiagnosticEvent[] = [];
   const requests = new Map<string, Request>();
   const subscriptions = new Map<string, Subscription>();
@@ -115,7 +125,7 @@ export const createWebSocketTransport = ({
     statusListeners.forEach((listener) => listener(status));
   };
   const send = (message: unknown) => {
-    if (socket?.readyState !== WebSocket.OPEN) {
+    if (socket?.readyState !== WebSocket.OPEN || !instance) {
       return false;
     }
     // Apply outbound backpressure before queued messages consume unbounded memory.
@@ -189,6 +199,7 @@ export const createWebSocketTransport = ({
     requests.clear();
   };
   const reportDisconnect = () => {
+    setInstance(undefined);
     const error = disconnected();
     rejectRequests(error);
     subscriptions.forEach(({ onError }) => onError(error));
@@ -208,17 +219,8 @@ export const createWebSocketTransport = ({
     const next = createSocket();
     next.binaryType = "arraybuffer";
     socket = next;
-    next.addEventListener("open", () => {
-      if (socket !== next) {
-        return;
-      }
-      reconnectDelay = 250;
-      setStatus("connected");
-      flushDiagnostics();
-      restore();
-    });
     next.addEventListener("message", (event) => {
-      if (socket !== next) {
+      if (socket !== next || disposed) {
         return;
       }
       let decoded: unknown;
@@ -238,6 +240,19 @@ export const createWebSocketTransport = ({
         return;
       }
       const message = parsed.data;
+      if (message.type === "server-info" && !instance) {
+        setInstance(createInstanceIdentity(message.instanceId));
+        reconnectDelay = 250;
+        setStatus("connected");
+        flushDiagnostics();
+        restore();
+        return;
+      }
+      if (!instance || message.type === "server-info") {
+        reportDisconnect();
+        next.close(1002, "expected server discovery before traffic");
+        return;
+      }
       if (
         message.type === "update-available" ||
         message.type === "restarting"
@@ -312,6 +327,11 @@ export const createWebSocketTransport = ({
   };
 
   return {
+    getInstance: () => instance,
+    subscribeInstance: (listener) => {
+      instanceListeners.add(listener);
+      return () => instanceListeners.delete(listener);
+    },
     activate: () => {
       active = true;
       connect();
@@ -354,7 +374,7 @@ export const createWebSocketTransport = ({
       // Initial connection is not a failure: restore sends stream-open when the socket
       // opens, then stream-opened flushes queued messages. Actual failures still reject.
       stream.status =
-        socket?.readyState === WebSocket.CONNECTING ||
+        status === "connecting" ||
         send({
           input,
           operationId: streamId,

package/src/internal/server/auth/auth-service.ts

@@ -129,7 +129,7 @@ const randomCode = () => {
 const durationMilliseconds = (
   duration: Exclude<
     AuthConfigDefinition["sessionLifetime"],
-    "never" | undefined
+    "forever" | undefined
   >,
 ) => {
   const milliseconds = durationToMilliseconds(
@@ -357,7 +357,7 @@ export const createAuthService = ({
     const token = randomToken();
     const createdAt = new Date(now()).toISOString();
     const configuredLifetime =
-      config.sessionLifetime && config.sessionLifetime !== "never"
+      config.sessionLifetime && config.sessionLifetime !== "forever"
         ? durationMilliseconds(config.sessionLifetime)
         : undefined;
     const expiresIn = lifetimeMs ?? configuredLifetime;