overmux 0.0.4 → 0.0.6

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

@@ -0,0 +1,128 @@
+---
+title: "`overmux docs`"
+---
+
+Overmux documentation and AI context commands
+
+## `overmux docs path`
+
+`overmux docs path` prints the installed Overmux CLI’s absolute documentation path.
+
+```console
+$ overmux docs path
+/path/to/somewhere/node_modules/overmux/docs
+```
+
+## `overmux docs ai-context`
+
+`overmux docs ai-context` prints `CLAUDE.md`/`AGENTS.md` guidance for coding agents.
+
+### Usage
+
+```text
+overmux docs ai-context
+```
+
+Prints the selected snippets shown in [available snippets](#available-snippets).
+
+### Set up your coding agent
+
+Tell your agent how to load Overmux guidance using `overmux docs ai-context`.
+
+<CodeBlockTabs defaultValue="agents">
+  <CodeBlockTabsList>
+    <CodeBlockTabsTrigger value="agents">AGENTS.md</CodeBlockTabsTrigger>
+    <CodeBlockTabsTrigger value="claude">CLAUDE.md</CodeBlockTabsTrigger>
+  </CodeBlockTabsList>
+  <CodeBlockTab value="agents">
+
+```bash
+echo 'Run `overmux docs ai-context` for help configuring Overmux.' >> AGENTS.md
+```
+
+  </CodeBlockTab>
+  <CodeBlockTab value="claude">
+
+```bash
+echo 'Run `overmux docs ai-context` for help configuring Overmux.' >> CLAUDE.md
+```
+
+  </CodeBlockTab>
+</CodeBlockTabs>
+
+### Configure context snippets
+
+Use `aiContextSnippets` in `overmux.config.ts` to select which snippets `overmux docs ai-context` prints.
+
+```ts
+import {
+  coreAiContextSnippets,
+  defineOvermuxConfig,
+} from "overmux";
+
+export default defineOvermuxConfig({
+  aiContextSnippets: coreAiContextSnippets,
+  // ...
+});
+```
+
+When `aiContextSnippets` is omitted, Overmux uses `defaultAiContextSnippets`. Set it to an empty array to emit no context.
+
+You can compose an explicit selection from the individual exports:
+
+```ts
+import {
+  defineOvermuxConfig,
+  packageSourceSnippet,
+  techStackRecommendationsSnippet,
+} from "overmux";
+
+export default defineOvermuxConfig({
+  aiContextSnippets: [
+    packageSourceSnippet,
+    techStackRecommendationsSnippet,
+  ],
+  // ...
+});
+```
+
+### Options
+
+| Flag | Description | Default |
+| --- | --- | --- |
+| `--config <path>, -c <path>` | Configuration file | `$XDG_CONFIG_HOME/overmux/overmux.config.ts` |
+
+### Snippet presets
+
+[//]: # (BEGIN GENERATED AI CONTEXT PRESETS)
+
+| Export | Included snippets |
+| --- | --- |
+| `defaultAiContextSnippets` | `package-source`, `tech-stack-recommendations` |
+| `coreAiContextSnippets` | `package-source` |
+
+[//]: # (END GENERATED AI CONTEXT PRESETS)
+
+### Available snippets
+
+[//]: # (BEGIN GENERATED AI CONTEXT)
+
+#### `package-source`
+
+```text
+Overmux ships with documentation and TypeScript source.
+
+Run `overmux docs path` to find the installed documentation directory for the Overmux CLI. This prints a documentation directory, not source paths.
+
+Inspect TypeScript source in installed packages, e.g. `node_modules/overmux/src` and `node_modules/@overmux/xterm/src`.
+
+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.
+```
+
+[//]: # (END GENERATED AI CONTEXT)

package/docs/400-reference/{400-cli → 700-cli}/700-desktop.md

@@ -1,9 +1,7 @@
 ---
-title: "overmux desktop"
+title: "`overmux desktop`"
 ---
 
-# `overmux desktop`
-
 Install or upgrade the experimental macOS desktop preview. The desktop version is independent from the `overmux` npm package version.
 
 ## Install

package/docs/500-hosted-pages.md

@@ -1,6 +1,5 @@
 ---
 title: Hosted pages
-description: Link to Overmux-owned settings and logout pages.
 ---
 
 # Hosted pages

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "overmux",
-  "version": "0.0.4",
+  "version": "0.0.6",
   "homepage": "https://github.com/richardgill/overmux",
   "repository": {
     "type": "git",
@@ -52,7 +52,7 @@
     "web-push": "3.6.7",
     "ws": "8.21.3",
     "zod": "4.4.3",
-    "@overmux/keybindings": "0.0.3"
+    "@overmux/keybindings": "0.0.4"
   },
   "devDependencies": {
     "@playwright/test": "1.58.0",
@@ -65,6 +65,7 @@
     "react-dom": "19.2.3",
     "vite": "8.2.2",
     "vitest": "4.1.10",
+    "@overmux/ai-context": "0.0.1",
     "@overmux/lib": "0.0.1",
     "@overmux/shared": "0.0.1",
     "@overmux/tsconfig": "0.0.1"
@@ -78,7 +79,7 @@
     "access": "public"
   },
   "scripts": {
-    "build": "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 && 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/cli/app.ts

@@ -6,12 +6,11 @@ import {
   text_en,
 } from "@stricli/core";
 
-import { createAiRoute } from "./commands/ai";
 import { authRoute } from "./commands/auth";
 import { checkCommand } from "./commands/check";
 import { callCommand } from "./commands/call";
 import { desktopRoute } from "./commands/desktop";
-import { createDocsCommand, resolveInstalledDocsRoot } from "./commands/docs";
+import { createDocsRoute, resolveInstalledDocsRoot } from "./commands/docs";
 import { createInitCommand } from "./commands/init";
 import { integrationCommand } from "./commands/integration";
 import { createInstanceCommand } from "./commands/instance";
@@ -23,14 +22,13 @@ export const createCliApp = (process = globalThis.process) =>
     buildRouteMap<string, CliCommandContext>({
       docs: { brief: "Initialize and manage Overmux applications" },
       routes: {
-        ai: createAiRoute(process),
         auth: authRoute,
         check: checkCommand,
         call: callCommand,
         desktop: desktopRoute,
-        docs: createDocsCommand({
+        docs: createDocsRoute({
           docsRoot: resolveInstalledDocsRoot(import.meta.url),
-          output: process.stdout,
+          process,
         }),
         init: createInitCommand(process),
         integration: integrationCommand,

package/src/internal/cli/commands/docs-ai-context.ts

@@ -0,0 +1,33 @@
+import { loadOvermuxConfig } from "@overmux/shared/node";
+import { buildCommand } from "@stricli/core";
+
+import {
+  composeAiContext,
+  defaultAiContextSnippets,
+} from "../../../public/ai-context";
+import { getDefaultConfigPath } from "../../server/paths";
+
+type AiContextFlags = { config: string };
+
+export const createAiContextCommand = (process: NodeJS.Process) =>
+  buildCommand({
+    func: async (flags: AiContextFlags) => {
+      const { config } = await loadOvermuxConfig({ configPath: flags.config });
+      process.stdout.write(
+        composeAiContext(config.aiContextSnippets ?? defaultAiContextSnippets),
+      );
+    },
+    parameters: {
+      aliases: { c: "config" },
+      flags: {
+        config: {
+          brief: "Configuration file",
+          default: getDefaultConfigPath(),
+          kind: "parsed",
+          parse: String,
+          placeholder: "path",
+        },
+      },
+    },
+    docs: { brief: "Print the configured Overmux AI context" },
+  });

package/src/internal/cli/commands/docs.ts

@@ -1,8 +1,10 @@
-import { buildCommand } from "@stricli/core";
+import { buildCommand, buildRouteMap } from "@stricli/core";
 import { existsSync } from "node:fs";
 import { resolve } from "node:path";
 import { fileURLToPath } from "node:url";
 
+import { createAiContextCommand } from "./docs-ai-context";
+
 type DocsOutput = { write: (text: string) => unknown };
 
 export const resolveInstalledDocsRoot = (moduleUrl: string) => {
@@ -16,7 +18,7 @@ export const resolveInstalledDocsRoot = (moduleUrl: string) => {
   return resolve(docsRoot);
 };
 
-export const createDocsCommand = ({
+const createDocsPathCommand = ({
   docsRoot,
   output,
 }: {
@@ -32,3 +34,18 @@ export const createDocsCommand = ({
       brief: "Print the installed documentation directory",
     },
   });
+
+export const createDocsRoute = ({
+  docsRoot,
+  process,
+}: {
+  docsRoot: string;
+  process: NodeJS.Process;
+}) =>
+  buildRouteMap({
+    docs: { brief: "Find documentation and print coding-agent guidance" },
+    routes: {
+      path: createDocsPathCommand({ docsRoot, output: process.stdout }),
+      "ai-context": createAiContextCommand(process),
+    },
+  });

package/src/internal/cli/commands/init-template.ts

@@ -53,7 +53,7 @@ export const createInitScaffold = ({
 }): Readonly<Record<string, string>> => ({
   ".gitignore": "node_modules\ndist\n",
   "AGENTS.md":
-    "Immediately run `overmux ai context` for documentation about Overmux.\n",
+    "Immediately run `overmux docs ai-context` for documentation about Overmux.\n",
   "CLAUDE.md": "@AGENTS.md\n",
   ...(toolchain === "mise"
     ? {

package/src/internal/cli/commands/serve.ts

@@ -184,6 +184,9 @@ const announceServeLogin = async ({
     return;
   }
   printLoginGrant({ ...(await issueLoginGrant(port)), output: process });
+  process.stdout.write(
+    `\nNeed another grant? Run \`overmux auth login --port ${port}\`.\n`,
+  );
 };
 
 export const runServe = async ({

package/src/internal/cli/login.ts

@@ -19,11 +19,9 @@ export const printLoginFallback = (port: number, { stdout }: CliOutput) => {
 export const printLoginGrant = ({
   login,
   output,
-  port,
 }: {
   login: LoginGrant;
   output: CliOutput;
-  port: number;
 }) => {
   const expiresIn = Math.max(
     0,
@@ -31,16 +29,18 @@ export const printLoginGrant = ({
   );
   output.stdout.write(
     [
-      `Code: ${login.code}`,
-      ...login.urls.map((url) => `Open: ${url}`),
-      "This single-use grant authenticates one origin. Create another grant to authenticate another origin.",
-      "Enter the code on the login page shown by an unauthenticated Overmux origin.",
-      `Expires at ${login.expiresAt} (in ${expiresIn} minutes).`,
-      `Need another grant? Run \`overmux auth login --port ${port}\`.`,
+      `Code: ${login.code} (enter on the login page)`,
+      "",
+      ...(login.urls.length === 1
+        ? [`Login URL: ${login.urls[0]}`]
+        : ["Login URLs:", ...login.urls.map((url) => `  ${url}`)]),
+      "",
+      `Expiry in ${expiresIn} minutes (at ${login.expiresAt}).`,
+      "",
       "",
     ].join("\n"),
   );
   output.stderr.write(
-    "The login URL is a temporary credential; avoid sharing terminal output or screenshots.\n",
+    `Keep the code and link${login.urls.length === 1 ? "" : "s"} private.\n`,
   );
 };

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/overmux-host.tsx

@@ -22,6 +22,7 @@ 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";
@@ -137,6 +138,14 @@ const OvermuxRuntime = ({
   );
   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

@@ -99,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;
@@ -200,67 +204,94 @@ 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,
   };
 };
 

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;