overmux 0.0.4 → 0.0.5

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

@@ -0,0 +1,191 @@
+---
+title: Resources
+---
+
+Resources expose server-side data to your Overmux UI. 
+
+There are three kinds of resource: [query](#query), [subscription](#subscription), and [derived](#derived).
+
+## Query
+
+Query resources read server-side data on request.
+
+For example, to run `ls /` on your server and expose the result:
+
+```ts
+// server.ts
+defineOvermuxServer({
+  resources: {
+    ls: {
+      kind: "query",
+      contract: defineResourceContract({
+        input: noInputSchema,
+        output: z.array(z.string()),
+      }),
+      read: async () => {
+        const { stdout } = await execFileAsync("ls", ["/"]);
+        return stdout.split("\n").filter(Boolean);
+      },
+    },
+  },
+});
+```
+
+See [Accessing resources from your Overmux UI](#accessing-resources-from-your-overmux-ui) to display the listing in React.
+
+## Subscription
+
+Subscription resources read server-side data and notify clients when it changes.
+
+To keep the `ls /` listing up to date, watch the directory for changes:
+
+```ts
+import { watch } from "node:fs";
+
+// server.ts
+defineOvermuxServer({
+  resources: {
+    ls: {
+      kind: "subscription",
+      contract: defineResourceContract({
+        input: noInputSchema,
+        output: z.array(z.string()),
+      }),
+      read: async () => {
+        const { stdout } = await execFileAsync("ls", ["/"]);
+        return stdout.split("\n").filter(Boolean);
+      },
+      subscribe: (_input, invalidate) => {
+        // Watch the root directory for filesystem changes.
+        const watcher = watch("/", () => {
+          // Tell Overmux the data may have changed so it reads it again.
+          invalidate();
+        });
+        // Subscription cleanup function.
+        return () => watcher.close();
+      },
+    },
+  },
+});
+```
+
+When the subscription ends, Overmux calls the cleanup function returned by `subscribe`. In this example, it closes the filesystem watcher.
+
+The React code stays the same: `useResource({ id: "ls" })`.
+
+## Derived
+
+Derived resources compute a value from other resources.
+
+For example, count the entries returned by the `ls` resource above. Add `entryCount` alongside `ls` in your `resources` object:
+
+```ts
+defineOvermuxServer({
+  resources: {
+    ls: {
+      // The subscription resource above:
+      // reads ls / and watches for directory changes.
+    },
+    entryCount: {
+      kind: "derived",
+      contract: defineResourceContract({
+        input: noInputSchema,
+        output: z.number(),
+      }),
+      dependencies: { ls: "ls" },
+      combine: ({ ls }) => ls.length,
+    },
+  },
+});
+```
+
+`dependencies` maps the names used in `combine` to resource IDs. Here, `combine` receives the value of `ls` and returns its length.
+
+If `ls` returns `["bin", "etc", "home"]`, `entryCount` returns `3`. With the subscription version of `ls`, the count updates when the directory listing changes.
+
+Access it from your UI with `useResource({ id: "entryCount" })`.
+
+## Accessing resources from your Overmux UI
+
+Use `useResource` to access query, subscription, and derived resources. Create your typed hooks with `createOvermuxHooks` from `overmux/client`:
+
+```ts
+// hooks.ts
+import { createOvermuxHooks } from "overmux/client";
+import type { serverConfig } from "./server";
+
+export const { useResource } = createOvermuxHooks<typeof serverConfig>();
+```
+
+Here, `serverConfig` is the exported result of `defineOvermuxServer`. The type-only import provides type checking without including your server code in the browser.
+
+Use the hook inside a component under your Overmux provider:
+
+```tsx
+import { useResource } from "./hooks";
+
+const DirectoryListing = () => {
+  const ls = useResource({ id: "ls" });
+
+  if (ls.status === "pending") return <p>Loading...</p>;
+  if (ls.status === "error") return <p>{ls.error.message}</p>;
+
+  return (
+    <div>
+      {ls.data.map((name) => (
+        <div key={name}>{name}</div>
+      ))}
+    </div>
+  );
+};
+```
+
+The same component works with either `ls` example above. Overmux handles reads and change notifications, updating your component when fresh data arrives.
+
+See [Client API: Resources](../600-client/100-api.md#resources) for input arguments, return values, and manual refreshes.
+
+## Invalidating resources
+
+After server-side data changes, call `invalidate()` to tell clients: **“Your data may be out of date. Read this resource again.”**
+
+Clients will request the data by calling the resource's `read` function again.
+
+### From a subscription
+
+Call the `invalidate` callback provided to `subscribe` when your watcher detects a change:
+
+```ts
+subscribe: (_input, invalidate) => {
+  const watcher = watch("/", () => {
+    // Tell clients to read the directory listing again.
+    invalidate();
+  });
+
+  return () => watcher.close();
+},
+```
+
+### From an operation
+
+After changing server-side state in an [operation](./200-operations.md), call `context.invalidate(resourceId)`:
+
+```ts
+handle: async ({ path }, context) => {
+  await mkdir(path);
+
+  // Refresh clients using the directory listing resource.
+  context.invalidate("ls");
+},
+```
+
+Pass the resource's key in `resources`. Here, `"ls"` identifies the directory listing.
+
+Omit the second argument to invalidate all inputs. For a resource that accepts input, pass it to refresh only matching data: `context.invalidate("files", { path: "/" })`.
+
+## How resources work
+
+Resources communicate over a persistent WebSocket connection between your browser and server. This connection lets the client request data and the server send change notifications.
+
+When you call `useResource`, the client requests the resource's value. For subscription resources, it also listens for change notifications.
+
+Calling `invalidate()` tells the client its data may be stale. It does not send the updated value; the client requests a fresh read, and React updates with the result.

package/dist/docs/400-reference/500-server/200-operations.md

@@ -0,0 +1,111 @@
+---
+title: Operations
+---
+
+Operations expose server-side functions you can call from your UI or the `overmux call` CLI.
+
+## Defining an operation
+
+Define operations in your server's `operations` object:
+
+```ts
+// server.ts
+export const serverConfig = defineOvermuxServer({
+  operations: {
+    echo: {
+      input: z.object({ message: z.string() }),
+      output: z.string(),
+      handle: ({ message }) => message,
+    },
+  },
+});
+```
+
+The object key, `echo`, is the operation's ID. `handle` runs on your Overmux server machine and returns the message it receives.
+
+### Input and output
+
+Use [Zod schemas](https://zod.dev/) to define the input an operation accepts and the result it returns. Here, `echo` accepts an object with a `message` string and returns that string unchanged.
+
+Handlers can be asynchronous, so you can run commands, access files, or call other services before returning a result.
+
+### Handler API
+
+The `handle` function receives the operation's input and a `context` object:
+
+```ts
+handle: async (input, context) => {
+  // Run your server-side logic here.
+},
+```
+
+`context` provides:
+
+- **`invalidate(resourceId, input?)`**: tells clients to read an affected resource again after you change server-side data. See [Invalidating resources](./100-resources.md#invalidating-resources).
+- **[`notifications.send(...)`](./400-notifications.md)**: sends a notification through Overmux.
+
+See [Server API](./500-api.md#handler-context) for the full handler context.
+
+## Calling operations from your Overmux UI
+
+Create typed hooks with `createOvermuxHooks` from `overmux/client`:
+
+```ts
+// hooks.ts
+import { createOvermuxHooks } from "overmux/client";
+import type { serverConfig } from "./server";
+
+export const { useOperation } = createOvermuxHooks<typeof serverConfig>();
+```
+
+The type-only import provides type checking without including server code in the browser.
+
+Use the hook inside a component under your Overmux provider:
+
+```tsx
+import { useOperation } from "./hooks";
+
+const EchoButton = () => {
+  const echo = useOperation({ id: "echo" });
+
+  return (
+    <button onClick={() => echo.mutate({ message: "Hello world" })}>
+      Echo message
+    </button>
+  );
+};
+```
+
+Pass the operation's input to `mutate`.
+
+Use `mutateAsync` when you need to await the result:
+
+```ts
+const message = await echo.mutateAsync({ message: "Hello world" });
+```
+
+See [Client API](../600-client/100-api.md) for operation hooks, pending state, errors, and results.
+
+## Calling operations from the CLI
+
+Call an operation by its ID and pass input as JSON:
+
+```sh
+overmux call echo --input '{"message":"Hello world"}'
+```
+
+The CLI prints the returned result as JSON:
+
+```json
+"Hello world"
+```
+
+Agents can use the same CLI commands to call your operations.
+
+## How operations work
+
+Each call sends an HTTP `POST` to `/api/operations/{operationName}`, with any input encoded as JSON.
+
+Overmux handles authentication, validates the input, and calls your handler. If an output schema is defined, Overmux validates the result before returning it.
+
+Unlike resource subscriptions, an operation is a single request and response. It returns a result or an error; it does not keep listening for updates.

package/dist/docs/400-reference/500-server/300-streams.md

@@ -0,0 +1,140 @@
+---
+title: Streams
+---
+
+Streams send and receive messages between your Overmux UI and server over a persistent connection. Use them for ongoing communication, such as terminal input and output or live logs.
+
+Unlike [operations](./200-operations.md), streams can send and receive multiple messages. Unlike [resources](./100-resources.md), they deliver individual messages rather than a value clients read again when it changes.
+
+## Defining a stream
+
+Define streams in your server's `streams` object:
+
+```ts
+// server.ts
+import {
+  defineOvermuxServer,
+  defineStreamContract,
+  defineStreamHandler,
+  noInputSchema,
+} from "overmux";
+import { z } from "zod";
+
+const echoContract = defineStreamContract({
+  input: noInputSchema,
+  clientMessage: z.object({ message: z.string() }),
+  serverMessage: z.object({ message: z.string() }),
+});
+
+export const serverConfig = defineOvermuxServer({
+  streams: {
+    echo: defineStreamHandler(echoContract, (_input, { emit }) => ({
+      onMessage: ({ message }) => {
+        emit({ message });
+      },
+    })),
+  },
+});
+```
+
+The object key, `echo`, is the stream's ID. Each time a client opens the stream, Overmux calls its handler to create a session.
+
+Here, `onMessage` receives a message from the client and `emit` sends it back to that client.
+
+### Input and messages
+
+Use [Zod schemas](https://zod.dev/) to define:
+
+- **`input`**: the input provided when opening the stream.
+- **`clientMessage`**: messages sent from the UI to the server.
+- **`serverMessage`**: messages sent from the server to the UI.
+
+This example needs no opening input. Other streams might accept a terminal ID or a log file name.
+
+The server can also call `emit` independently of client messages, for example when a process produces output.
+
+## Accessing streams from your Overmux UI
+
+Create typed hooks with `createOvermuxHooks` from `overmux/client`:
+
+```ts
+// hooks.ts
+import { createOvermuxHooks } from "overmux/client";
+import type { serverConfig } from "./server";
+
+export const { useStream } = createOvermuxHooks<typeof serverConfig>();
+```
+
+The type-only import provides type checking without including server code in the browser.
+
+Use the hook inside a component under your Overmux provider:
+
+```tsx
+import { useEffect, useState } from "react";
+import { useStream } from "./hooks";
+
+const Echo = () => {
+  const { status, error, send, subscribe } = useStream({ id: "echo" });
+  const [message, setMessage] = useState("");
+
+  useEffect(
+    () => subscribe(({ message }) => setMessage(message)),
+    [subscribe],
+  );
+
+  if (error) return <p>{error.message}</p>;
+
+  return (
+    <div>
+      <button
+        disabled={status !== "open"}
+        onClick={() => send({ message: "Hello world" })}
+      >
+        Send message
+      </button>
+      <p>{message}</p>
+    </div>
+  );
+};
+```
+
+`send` sends a client message. `subscribe` registers a listener for server messages and returns a function that removes it, which the effect uses for cleanup.
+
+Unlike `useResource`, `useStream` does not store the latest message as `data`. Your component decides how to display or process incoming messages.
+
+See [Client API: Streams](../600-client/100-api.md#streams) for connection state and reconnection details.
+
+## Cleaning up a stream
+
+Return `dispose` from your handler to release resources when the session closes:
+
+```ts
+defineStreamHandler(echoContract, (_input, { emit }) => {
+  const timer = setInterval(() => {
+    emit({ message: "Still connected" });
+  }, 1_000);
+
+  return {
+    onMessage: ({ message }) => {
+      emit({ message });
+    },
+    dispose: () => {
+      clearInterval(timer);
+    },
+  };
+});
+```
+
+Overmux calls `dispose` once when the session closes. Use it to stop timers, remove listeners, or release other session-owned resources.
+
+`useStream` closes its session when the component unmounts. You can also close it explicitly with `close()`.
+
+The handler context provides an abort `signal` for cancelling background work and `fail(cause)` for failing and closing the session. See [Server API: Stream handlers](./500-api.md#stream-handlers).
+
+## How streams work
+
+Streams communicate over a persistent WebSocket connection between your browser and server.
+
+Overmux validates the opening input and messages against the stream contract. Client messages are passed to `onMessage` in order; calls to `emit` send messages to that session's client.
+
+A restored stream after a WebSocket reconnect creates a new server session. Do not assume that state held by the previous session survives.

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

@@ -0,0 +1,32 @@
+---
+title: Notifications
+---
+
+Send notifications from an [operation handler](./200-operations.md#handler-api) using `context.notifications.send()`. There is no separate notification API to import; Overmux provides it through the handler's `context`:
+
+```ts
+// server.ts
+import { defineOperation, defineOvermuxServer, noInputSchema } from "overmux";
+
+export const serverConfig = defineOvermuxServer({
+  resources: {},
+  operations: {
+    myOperation: defineOperation({
+      input: noInputSchema,
+      handle: async (_input, context) => {
+        await context.notifications.send({
+          title: "Task finished",
+          body: "Your results are ready.",
+          open: { link: "/results" },
+        });
+      },
+    }),
+  },
+});
+```
+
+- `title`: required, non-empty text.
+- `body`: optional text.
+- `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>`.

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

@@ -0,0 +1,118 @@
+---
+title: Server API
+---
+
+## Server definitions
+
+Import definition helpers from `overmux`:
+
+```ts
+import {
+  defineOperation,
+  defineOvermuxServer,
+  defineResourceContract,
+  defineStreamContract,
+  defineStreamHandler,
+} from "overmux";
+```
+
+`defineOvermuxServer()` defines the capabilities available from one server. It preserves types for `overmux/client` hooks and defaults omitted operation output schemas to `z.void()`.
+
+```ts
+export const serverConfig = defineOvermuxServer({
+  resources: {
+    // Resource definitions, keyed by resource ID.
+  },
+  operations: {
+    // defineOperation(...) values, keyed by operation ID.
+  },
+  streams: {
+    // defineStreamHandler(...) values, keyed by stream ID.
+  },
+});
+```
+
+| Option | Required | Value |
+| --- | --- | --- |
+| `resources` | Yes | An object of query, subscription, or derived resource definitions. |
+| `operations` | No | Inline operation definitions or reusable `defineOperation(...)` values. |
+| `streams` | No | An object of `defineStreamHandler(...)` definitions. |
+
+Object keys are the IDs used by clients. See [Resources](./100-resources.md), [Operations](./200-operations.md), and [Streams](./300-streams.md) for usage guides.
+
+## Resource handlers
+
+A resource definition has a `contract` created with `defineResourceContract({ input, output })`. Overmux parses handler input with `input` and validates every result with `output`.
+
+| Kind | Required handler API |
+| --- | --- |
+| `query` | `read(input, context) => output \| Promise<output>` |
+| `subscription` | `read(input, context)` and `subscribe(input, invalidate, context) => disposer` |
+| `derived` | `dependencies` and `combine(dependencies) => output` |
+
+```ts
+const count = defineResourceContract({
+  input: noInputSchema,
+  output: z.number(),
+});
+
+const resources = {
+  count: {
+    kind: "subscription",
+    contract: count,
+    read: () => readCount(),
+    subscribe: (_input, invalidate) => {
+      const stop = watchCount(invalidate);
+      return () => stop();
+    },
+  },
+};
+```
+
+`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.
+
+## Stream handlers
+
+A stream contract defines `input`, `clientMessage`, and `serverMessage` schemas. Define its handler with:
+
+```ts
+const terminal = defineStreamHandler(contract, (input, context) => ({
+  onMessage: async (message) => {
+    // Handle a validated client message.
+  },
+  dispose: async () => {
+    // Release per-session resources.
+  },
+}));
+```
+
+`open(input, context)` may return the session object or a promise for it. Its context extends the [handler context](#handler-context) with:
+
+| API | Purpose |
+| --- | --- |
+| `emit(message)` | Validate and send a server message to this session. Calls after closure are ignored. |
+| `fail(cause)` | Fail and close this session. A later call has no effect. |
+
+The returned `StreamSession` may contain:
+
+| API | Purpose |
+| --- | --- |
+| `onMessage(message)` | Receive validated client messages. Calls are processed in order. |
+| `dispose()` | Release session resources. It may be async and is called once when the session closes. |
+
+The stream `signal` aborts when its session or the runtime closes. Stop background work in response to it, and put resource cleanup in `dispose`. See [Streams](./300-streams.md) for stream usage from the client.
+
+## Handler context
+
+Inline resource, operation, and stream handlers infer valid resource IDs and inputs.
+
+Resource and stream handlers receive a context with:
+
+| API | Purpose |
+| --- | --- |
+| `invalidate(resourceId, input?)` | Ask clients to [read a resource again](./100-resources.md#invalidating-resources). Pass the resource's key in `resources`. Omit `input` to invalidate all inputs; otherwise it is validated and only matching inputs are invalidated. Unknown IDs throw. |
+| `signal` | An `AbortSignal` that aborts when the request or session, or the server runtime, closes. |
+| `instance.getInstanceId()` | Get this server instance's ID. |
+| `instance.getDeepLinkPrefix()` | Get this instance's Overmux deep-link prefix. |
+
+Operation handlers receive the same context plus `notifications.send(notification)`, which returns `Promise<void>`. See [Notifications](./400-notifications.md).

package/dist/docs/400-reference/600-client/000-index.md

@@ -0,0 +1,9 @@
+---
+title: Client
+---
+
+Overmux's client is your React application, running in a browser or Overmux Desktop.
+
+- [Client API](./100-api.md): Define your application, connect to the server, and register commands.
+- [Theming](./200-theming.md): Customize your application's appearance.
+- [Tech Stack Recommendations](./300-tech-stack-recommendations.md): Choose libraries for your UI.