@anvia/react-ui 1.1.9 → 1.2.0

package/README.md

@@ -67,6 +67,10 @@ semantic attributes and behavior; it has no package stylesheet.
 - Images, selection toolbars, and optional streaming presentation smoothing.
 - Graph exploration primitives through `@anvia/react-ui/graph-explorer`; install `@anvia/graph`
   when using that integration.
+- A remote sandbox terminal through `@anvia/react-ui/sandbox-terminal`; install `@xterm/xterm` and
+  `@xterm/addon-fit` when using it.
+- A remote sandbox desktop viewer with take-over control through
+  `@anvia/react-ui/sandbox-desktop`; install `@novnc/novnc` when using it.
 
 ## Learn more
 

package/dist/chunk-5FZKTDZR.js

@@ -0,0 +1,201 @@
+// src/relay/connection.ts
+var ticketSubprotocolPrefix = "anvia.ticket.";
+var defaultInitialDelayMs = 500;
+var defaultMaxDelayMs = 15e3;
+var defaultMaxAttempts = 10;
+var subprotocolToken = /^[!#$%&'*+\-.^_`|~0-9A-Za-z]+$/;
+var RelayConnection = class {
+  constructor(options) {
+    this.options = options;
+  }
+  options;
+  socketInUse;
+  timer;
+  attempt = 0;
+  everReady = false;
+  disposed = false;
+  finished = false;
+  fatalMessage;
+  start() {
+    void this.connect();
+  }
+  /** Try again now, for a link that gave up. */
+  retry() {
+    if (this.disposed || !this.finished) return;
+    clearTimeout(this.timer);
+    this.finished = false;
+    this.attempt = 0;
+    void this.connect();
+  }
+  /** Send a JSON message, if the socket is open. */
+  sendJson(value) {
+    if (this.socketInUse?.readyState === WebSocket.OPEN) {
+      this.socketInUse.send(JSON.stringify(value));
+    }
+  }
+  /** Send bytes, if the socket is open. */
+  sendBinary(data) {
+    if (this.socketInUse?.readyState === WebSocket.OPEN) this.socketInUse.send(data);
+  }
+  dispose() {
+    this.disposed = true;
+    clearTimeout(this.timer);
+    const socket = this.socketInUse;
+    this.socketInUse = void 0;
+    socket?.close(1e3);
+  }
+  async connect() {
+    if (this.disposed) return;
+    const { label } = this.options.protocol;
+    this.options.onStatus({ state: "connecting" });
+    this.fatalMessage = void 0;
+    let ticket;
+    try {
+      ticket = await this.options.getTicket?.();
+    } catch (error) {
+      if (this.disposed) return;
+      const detail = error instanceof Error ? `: ${error.message}` : "";
+      this.scheduleReconnect(`Could not get a ${label} ticket${detail}`);
+      return;
+    }
+    if (this.disposed) return;
+    let socket;
+    try {
+      socket = new WebSocket(this.resolveUrl(), this.resolveProtocols(ticket));
+    } catch (error) {
+      this.fail(error instanceof Error ? error.message : `Could not open the ${label}.`);
+      return;
+    }
+    if (this.disposed) {
+      socket.close(1e3);
+      return;
+    }
+    this.socketInUse = socket;
+    socket.binaryType = "arraybuffer";
+    const session = {
+      ready: () => {
+        const reconnected = this.everReady;
+        this.everReady = true;
+        this.attempt = 0;
+        this.options.onStatus({ state: "open" });
+        return reconnected;
+      },
+      ended: (info) => {
+        this.finished = true;
+        const status = { state: "ended", message: info.message ?? "ended" };
+        if (info.exitCode !== void 0) status.exitCode = info.exitCode;
+        this.options.onStatus(status);
+      },
+      fatal: (message) => {
+        this.fatalMessage = message;
+      }
+    };
+    const { protocol } = this.options;
+    socket.addEventListener("open", () => protocol.open(socket, session));
+    socket.addEventListener("message", (event) => protocol.message(event, session));
+    socket.addEventListener("close", (event) => {
+      if (this.socketInUse === socket) this.socketInUse = void 0;
+      protocol.close?.(event, session);
+      if (this.disposed || this.finished) return;
+      if (this.fatalMessage !== void 0) this.fail(this.fatalMessage);
+      else this.scheduleReconnect();
+    });
+  }
+  scheduleReconnect(reason) {
+    const { initialDelayMs, maxDelayMs, maxAttempts } = {
+      initialDelayMs: defaultInitialDelayMs,
+      maxDelayMs: defaultMaxDelayMs,
+      maxAttempts: defaultMaxAttempts,
+      ...this.options.reconnect
+    };
+    if (this.attempt >= maxAttempts) {
+      this.fail(reason ?? `The connection to the ${this.options.protocol.label} was lost.`);
+      return;
+    }
+    const delay = Math.min(maxDelayMs, initialDelayMs * 2 ** this.attempt) * (0.8 + Math.random() * 0.4);
+    this.attempt += 1;
+    this.options.onStatus({
+      state: "reconnecting",
+      attempt: this.attempt,
+      retryInMs: Math.round(delay)
+    });
+    this.timer = setTimeout(() => void this.connect(), delay);
+  }
+  fail(message) {
+    this.finished = true;
+    this.options.onStatus({ state: "failed", message });
+  }
+  resolveUrl() {
+    const url = new URL(this.options.url, globalThis.location?.href);
+    if (url.protocol === "http:") url.protocol = "ws:";
+    else if (url.protocol === "https:") url.protocol = "wss:";
+    if (this.options.sessionName !== void 0) {
+      url.searchParams.set("session", this.options.sessionName);
+    }
+    return url.toString();
+  }
+  /** The subprotocols to offer: the relay's, plus the ticket when there is one. */
+  resolveProtocols(ticket) {
+    const { subprotocol, label } = this.options.protocol;
+    if (ticket === void 0) return [subprotocol];
+    if (!subprotocolToken.test(ticket)) {
+      throw new Error(`The ${label} ticket must use only URL-safe characters (A-Z a-z 0-9 - _ .).`);
+    }
+    return [subprotocol, `${ticketSubprotocolPrefix}${ticket}`];
+  }
+};
+
+// src/relay/status.tsx
+import { Fragment, jsx, jsxs } from "react/jsx-runtime";
+var statusStyle = {
+  position: "absolute",
+  top: 8,
+  right: 8,
+  padding: "2px 8px",
+  borderRadius: 4,
+  fontSize: 12,
+  background: "rgba(0, 0, 0, 0.7)",
+  color: "#fff"
+};
+function DefaultStatus({ status, retry }) {
+  if (status.state === "open") return null;
+  return /* @__PURE__ */ jsxs("div", { role: "status", "data-relay-status": status.state, style: statusStyle, children: [
+    describe(status),
+    status.state === "failed" ? /* @__PURE__ */ jsxs(Fragment, { children: [
+      " ",
+      /* @__PURE__ */ jsx("button", { type: "button", onClick: retry, children: "Retry" })
+    ] }) : null
+  ] });
+}
+function describe(status) {
+  switch (status.state) {
+    case "loading":
+    case "connecting":
+      return "Connecting\u2026";
+    case "reconnecting":
+      return `Reconnecting in ${Math.max(1, Math.round((status.retryInMs ?? 0) / 1e3))}s\u2026`;
+    case "ended":
+      return status.exitCode === void 0 ? "Session ended" : `Session ended (exit ${status.exitCode})`;
+    case "failed":
+      return status.message ?? "Disconnected";
+    case "open":
+      return "";
+  }
+}
+
+// src/relay/ticket.ts
+function resolveTicket(read) {
+  if (read() === void 0) return void 0;
+  return () => {
+    const ticket = read();
+    return typeof ticket === "function" ? ticket() : ticket;
+  };
+}
+
+export {
+  DefaultStatus,
+  resolveTicket,
+  ticketSubprotocolPrefix,
+  RelayConnection
+};
+//# sourceMappingURL=chunk-5FZKTDZR.js.map

package/dist/chunk-5FZKTDZR.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/relay/connection.ts","../src/relay/status.tsx","../src/relay/ticket.ts"],"sourcesContent":["/** The prefix a ticket travels under in `Sec-WebSocket-Protocol`. */\nexport const ticketSubprotocolPrefix = \"anvia.ticket.\";\n\nexport type RelayState =\n  /** The viewer library is still loading. */\n  | \"loading\"\n  | \"connecting\"\n  | \"open\"\n  /** The link dropped and another attempt is scheduled. */\n  | \"reconnecting\"\n  /** The session itself ended; reconnecting would not help. */\n  | \"ended\"\n  /** Gave up: a fatal error, or reconnect attempts ran out. */\n  | \"failed\";\n\nexport interface RelayStatus {\n  state: RelayState;\n  /** Reconnect attempt number while `reconnecting`. */\n  attempt?: number;\n  /** Delay before the next attempt while `reconnecting`. */\n  retryInMs?: number;\n  /** Exit code when the session ended with one. */\n  exitCode?: number;\n  /** Human-readable cause for `ended` and `failed`. */\n  message?: string;\n}\n\nexport interface RelayReconnectOptions {\n  initialDelayMs?: number;\n  maxDelayMs?: number;\n  /** Consecutive failed attempts before giving up. Default 10. */\n  maxAttempts?: number;\n}\n\n/** What a relay protocol can tell the connection about the socket it is driving. */\nexport interface RelaySession {\n  /**\n   * The relay accepted this attachment. Returns whether an earlier attachment had also been\n   * accepted, so a viewer knows to start clean after a reconnect.\n   */\n  ready(): boolean;\n  /** The session itself is over, so the socket closing is not a reason to reconnect. */\n  ended(info: { message?: string | undefined; exitCode?: number | undefined }): void;\n  /** Something retrying cannot fix. It takes effect when the socket closes. */\n  fatal(message: string): void;\n}\n\n/** The part of a relay connection that differs between a terminal and a desktop. */\nexport interface RelayProtocol {\n  /** The subprotocol the hub's upgrade handler selects. */\n  subprotocol: string;\n  /** Names the thing in error messages: \"terminal\", \"desktop\". */\n  label: string;\n  /** The socket opened. */\n  open(socket: WebSocket, session: RelaySession): void;\n  message(event: MessageEvent, session: RelaySession): void;\n  /** The socket closed. A protocol that learns why from the close frame can call `fatal` here. */\n  close?(event: CloseEvent, session: RelaySession): void;\n}\n\nexport interface RelayConnectionOptions {\n  /** `ws:`, `wss:`, `http:`, `https:`, or a path relative to the page. */\n  url: string;\n  /** Appended as `?session=` so the server can pick the session. The server stays in charge. */\n  sessionName?: string | undefined;\n  /** Called for every attempt, because tickets are single use. */\n  getTicket?: (() => string | Promise<string>) | undefined;\n  onStatus: (status: RelayStatus) => void;\n  reconnect?: RelayReconnectOptions | undefined;\n  protocol: RelayProtocol;\n}\n\nconst defaultInitialDelayMs = 500;\nconst defaultMaxDelayMs = 15_000;\nconst defaultMaxAttempts = 10;\n/** Characters a ticket may use, since it travels as a WebSocket subprotocol (an HTTP token). */\nconst subprotocolToken = /^[!#$%&'*+\\-.^_`|~0-9A-Za-z]+$/;\n\n/**\n * One browser link to a hub relay: opens the socket with a fresh ticket, reconnects with backoff,\n * and reports its state. What the socket carries is the protocol's business, so this knows nothing\n * about terminals or desktops and is shared by both.\n */\nexport class RelayConnection {\n  private socketInUse: WebSocket | undefined;\n  private timer: ReturnType<typeof setTimeout> | undefined;\n  private attempt = 0;\n  private everReady = false;\n  private disposed = false;\n  private finished = false;\n  private fatalMessage: string | undefined;\n\n  constructor(private readonly options: RelayConnectionOptions) {}\n\n  start(): void {\n    void this.connect();\n  }\n\n  /** Try again now, for a link that gave up. */\n  retry(): void {\n    // Only a link that gave up needs this; otherwise an attempt is already under way.\n    if (this.disposed || !this.finished) return;\n    clearTimeout(this.timer);\n    this.finished = false;\n    this.attempt = 0;\n    void this.connect();\n  }\n\n  /** Send a JSON message, if the socket is open. */\n  sendJson(value: Record<string, unknown>): void {\n    if (this.socketInUse?.readyState === WebSocket.OPEN) {\n      this.socketInUse.send(JSON.stringify(value));\n    }\n  }\n\n  /** Send bytes, if the socket is open. */\n  sendBinary(data: ArrayBufferLike | ArrayBufferView): void {\n    if (this.socketInUse?.readyState === WebSocket.OPEN) this.socketInUse.send(data);\n  }\n\n  dispose(): void {\n    this.disposed = true;\n    clearTimeout(this.timer);\n    const socket = this.socketInUse;\n    this.socketInUse = undefined;\n    socket?.close(1000);\n  }\n\n  private async connect(): Promise<void> {\n    if (this.disposed) return;\n    const { label } = this.options.protocol;\n    this.options.onStatus({ state: \"connecting\" });\n    // A fatal error belongs to the attempt that hit it. Without this, one that was retried away\n    // would fail every later drop.\n    this.fatalMessage = undefined;\n\n    let ticket: string | undefined;\n    try {\n      ticket = await this.options.getTicket?.();\n    } catch (error) {\n      // Fetching a ticket usually fails because the control plane is restarting, which is exactly\n      // when reconnecting is wanted, so it backs off like a dropped socket.\n      if (this.disposed) return;\n      const detail = error instanceof Error ? `: ${error.message}` : \"\";\n      this.scheduleReconnect(`Could not get a ${label} ticket${detail}`);\n      return;\n    }\n    if (this.disposed) return;\n\n    let socket: WebSocket;\n    try {\n      socket = new WebSocket(this.resolveUrl(), this.resolveProtocols(ticket));\n    } catch (error) {\n      // A bad URL or a malformed ticket: trying again cannot fix either.\n      this.fail(error instanceof Error ? error.message : `Could not open the ${label}.`);\n      return;\n    }\n    if (this.disposed) {\n      socket.close(1000);\n      return;\n    }\n    this.socketInUse = socket;\n    socket.binaryType = \"arraybuffer\";\n\n    const session: RelaySession = {\n      ready: () => {\n        const reconnected = this.everReady;\n        this.everReady = true;\n        this.attempt = 0;\n        this.options.onStatus({ state: \"open\" });\n        return reconnected;\n      },\n      ended: (info) => {\n        this.finished = true;\n        const status: RelayStatus = { state: \"ended\", message: info.message ?? \"ended\" };\n        if (info.exitCode !== undefined) status.exitCode = info.exitCode;\n        this.options.onStatus(status);\n      },\n      fatal: (message) => {\n        this.fatalMessage = message;\n      },\n    };\n    const { protocol } = this.options;\n    socket.addEventListener(\"open\", () => protocol.open(socket, session));\n    socket.addEventListener(\"message\", (event: MessageEvent) => protocol.message(event, session));\n    socket.addEventListener(\"close\", (event: CloseEvent) => {\n      if (this.socketInUse === socket) this.socketInUse = undefined;\n      protocol.close?.(event, session);\n      if (this.disposed || this.finished) return;\n      if (this.fatalMessage !== undefined) this.fail(this.fatalMessage);\n      else this.scheduleReconnect();\n    });\n  }\n\n  private scheduleReconnect(reason?: string): void {\n    const { initialDelayMs, maxDelayMs, maxAttempts } = {\n      initialDelayMs: defaultInitialDelayMs,\n      maxDelayMs: defaultMaxDelayMs,\n      maxAttempts: defaultMaxAttempts,\n      ...this.options.reconnect,\n    };\n    if (this.attempt >= maxAttempts) {\n      this.fail(reason ?? `The connection to the ${this.options.protocol.label} was lost.`);\n      return;\n    }\n    const delay =\n      Math.min(maxDelayMs, initialDelayMs * 2 ** this.attempt) * (0.8 + Math.random() * 0.4);\n    this.attempt += 1;\n    this.options.onStatus({\n      state: \"reconnecting\",\n      attempt: this.attempt,\n      retryInMs: Math.round(delay),\n    });\n    this.timer = setTimeout(() => void this.connect(), delay);\n  }\n\n  private fail(message: string): void {\n    this.finished = true;\n    this.options.onStatus({ state: \"failed\", message });\n  }\n\n  private resolveUrl(): string {\n    const url = new URL(this.options.url, globalThis.location?.href);\n    if (url.protocol === \"http:\") url.protocol = \"ws:\";\n    else if (url.protocol === \"https:\") url.protocol = \"wss:\";\n    if (this.options.sessionName !== undefined) {\n      url.searchParams.set(\"session\", this.options.sessionName);\n    }\n    return url.toString();\n  }\n\n  /** The subprotocols to offer: the relay's, plus the ticket when there is one. */\n  private resolveProtocols(ticket: string | undefined): string[] {\n    const { subprotocol, label } = this.options.protocol;\n    if (ticket === undefined) return [subprotocol];\n    if (!subprotocolToken.test(ticket)) {\n      throw new Error(`The ${label} ticket must use only URL-safe characters (A-Z a-z 0-9 - _ .).`);\n    }\n    return [subprotocol, `${ticketSubprotocolPrefix}${ticket}`];\n  }\n}\n","import type { CSSProperties } from \"react\";\n\nimport type { RelayStatus } from \"./connection\";\n\nconst statusStyle: CSSProperties = {\n  position: \"absolute\",\n  top: 8,\n  right: 8,\n  padding: \"2px 8px\",\n  borderRadius: 4,\n  fontSize: 12,\n  background: \"rgba(0, 0, 0, 0.7)\",\n  color: \"#fff\",\n};\n\nexport function DefaultStatus({ status, retry }: { status: RelayStatus; retry: () => void }) {\n  if (status.state === \"open\") return null;\n  return (\n    <div role=\"status\" data-relay-status={status.state} style={statusStyle}>\n      {describe(status)}\n      {status.state === \"failed\" ? (\n        <>\n          {\" \"}\n          <button type=\"button\" onClick={retry}>\n            Retry\n          </button>\n        </>\n      ) : null}\n    </div>\n  );\n}\n\nfunction describe(status: RelayStatus): string {\n  switch (status.state) {\n    case \"loading\":\n    case \"connecting\":\n      return \"Connecting…\";\n    case \"reconnecting\":\n      return `Reconnecting in ${Math.max(1, Math.round((status.retryInMs ?? 0) / 1_000))}s…`;\n    case \"ended\":\n      return status.exitCode === undefined\n        ? \"Session ended\"\n        : `Session ended (exit ${status.exitCode})`;\n    case \"failed\":\n      return status.message ?? \"Disconnected\";\n    case \"open\":\n      return \"\";\n  }\n}\n","/** What a viewer's `ticket` prop can be: a ticket, or a function returning one per connection. */\nexport type TicketSource = string | (() => string | Promise<string>);\n\n/**\n * Turn the latest `ticket` prop into the per-attempt function a connection wants. The prop is read\n * on every attempt, so a function is called afresh each time: tickets are single use.\n */\nexport function resolveTicket(\n  read: () => TicketSource | undefined,\n): (() => string | Promise<string>) | undefined {\n  if (read() === undefined) return undefined;\n  return () => {\n    const ticket = read();\n    return typeof ticket === \"function\" ? ticket() : (ticket as string);\n  };\n}\n"],"mappings":"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","names":[]}

package/dist/sandbox-desktop/index.d.ts

@@ -0,0 +1,122 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { P as PrimitiveProps } from '../render-CRKWam2v.js';
+import { T as TicketSource, R as RelayReconnectOptions, a as RelayStatus } from '../ticket-pexI1zIa.js';
+export { b as SandboxDesktopState, t as ticketSubprotocolPrefix } from '../ticket-pexI1zIa.js';
+
+/** Subprotocol the hub's `handleDesktopUpgrade` selects. */
+declare const desktopSubprotocol = "anvia.desktop.v1";
+/** Who is driving the desktop, as the relay reports it to this viewer. */
+interface SandboxDesktopControl {
+    /** Someone has taken control, which pauses the agent. */
+    held: boolean;
+    /** Who. Present when `held`. */
+    holder?: string;
+    /** When the hold lapses unless renewed. */
+    expiresAt?: string;
+    /** This viewer is the holder. */
+    you: boolean;
+    /** This viewer may only watch. */
+    readOnly: boolean;
+}
+
+interface SandboxDesktopHandle {
+    focus(): void;
+    /** Reconnect now, after the viewer gave up. */
+    reconnect(): void;
+    /** Take control, which pauses the agent. */
+    takeOver(): void;
+    /** Hand control back. */
+    release(): void;
+}
+interface SandboxDesktopNotice {
+    code: string;
+    message: string;
+}
+/** What `renderControls` is given to draw its own take-over bar. */
+interface SandboxDesktopControlsState {
+    status: RelayStatus;
+    /** Undefined until the relay has said who has control. */
+    control: SandboxDesktopControl | undefined;
+    /** This viewer cannot send input, because of the prop or because the ticket says so. */
+    readOnly: boolean;
+    /** The latest failed request, such as taking over while someone else holds control. */
+    notice: SandboxDesktopNotice | undefined;
+    takeOver(): void;
+    release(): void;
+}
+type SandboxDesktopProps = Omit<PrimitiveProps<"div">, "children" | "onError"> & {
+    /**
+     * The hub's desktop endpoint (`hub.handleDesktopUpgrade`): `ws:`/`wss:`, `http:`/`https:`, or a
+     * path relative to this page.
+     */
+    url: string;
+    /**
+     * A one-time ticket, or a function returning one. Pass a function: tickets are single use, so
+     * each reconnect needs a fresh one. It travels as a WebSocket subprotocol, not in the URL.
+     */
+    ticket?: TicketSource;
+    /** Watch only. The server enforces it too; this also stops the viewer sending input. */
+    readOnly?: boolean;
+    /** Scale the desktop to fit the element. Default true. */
+    scaleToFit?: boolean;
+    /**
+     * JPEG quality asked of the server, 0 (smallest, blockiest) to 9 (best, most data). Default 6.
+     * Lower it for a slow link; it applies to the live connection.
+     */
+    qualityLevel?: number;
+    /**
+     * How hard the server compresses, 0 (fastest, most data) to 9 (slowest, least data). Default 2,
+     * which keeps the server's CPU low. Raise it for a slow link; it applies to the live connection.
+     */
+    compressionLevel?: number;
+    reconnect?: RelayReconnectOptions;
+    onStatusChange?: (status: RelayStatus) => void;
+    /** Called whenever the relay reports who has control. */
+    onControlChange?: (control: SandboxDesktopControl) => void;
+    /** Replace the default status line. Return null to show nothing. */
+    renderStatus?: (status: RelayStatus, retry: () => void) => ReactNode;
+    /** Replace the default take-over bar. Return null to show nothing. */
+    renderControls?: (state: SandboxDesktopControlsState) => ReactNode;
+};
+/**
+ * A viewer for a remote sandbox's desktop, drawn with noVNC. noVNC is loaded on demand, so it costs
+ * nothing until a desktop mounts. It connects to the hub's desktop relay, reconnects with a fresh
+ * ticket when the link drops, and lets a person take over control from the agent.
+ */
+declare const SandboxDesktop: react.ForwardRefExoticComponent<Omit<PrimitiveProps<"div">, "children" | "onError"> & {
+    /**
+     * The hub's desktop endpoint (`hub.handleDesktopUpgrade`): `ws:`/`wss:`, `http:`/`https:`, or a
+     * path relative to this page.
+     */
+    url: string;
+    /**
+     * A one-time ticket, or a function returning one. Pass a function: tickets are single use, so
+     * each reconnect needs a fresh one. It travels as a WebSocket subprotocol, not in the URL.
+     */
+    ticket?: TicketSource;
+    /** Watch only. The server enforces it too; this also stops the viewer sending input. */
+    readOnly?: boolean;
+    /** Scale the desktop to fit the element. Default true. */
+    scaleToFit?: boolean;
+    /**
+     * JPEG quality asked of the server, 0 (smallest, blockiest) to 9 (best, most data). Default 6.
+     * Lower it for a slow link; it applies to the live connection.
+     */
+    qualityLevel?: number;
+    /**
+     * How hard the server compresses, 0 (fastest, most data) to 9 (slowest, least data). Default 2,
+     * which keeps the server's CPU low. Raise it for a slow link; it applies to the live connection.
+     */
+    compressionLevel?: number;
+    reconnect?: RelayReconnectOptions;
+    onStatusChange?: (status: RelayStatus) => void;
+    /** Called whenever the relay reports who has control. */
+    onControlChange?: (control: SandboxDesktopControl) => void;
+    /** Replace the default status line. Return null to show nothing. */
+    renderStatus?: (status: RelayStatus, retry: () => void) => ReactNode;
+    /** Replace the default take-over bar. Return null to show nothing. */
+    renderControls?: (state: SandboxDesktopControlsState) => ReactNode;
+} & react.RefAttributes<SandboxDesktopHandle>>;
+
+export { SandboxDesktop, type SandboxDesktopControl, type SandboxDesktopControlsState, type SandboxDesktopHandle, type SandboxDesktopNotice, type SandboxDesktopProps, RelayReconnectOptions as SandboxDesktopReconnectOptions, RelayStatus as SandboxDesktopStatus, desktopSubprotocol };

package/dist/sandbox-desktop/index.js

@@ -0,0 +1,356 @@
+import {
+  DefaultStatus,
+  RelayConnection,
+  resolveTicket,
+  ticketSubprotocolPrefix
+} from "../chunk-5FZKTDZR.js";
+
+// src/sandbox-desktop/desktop.tsx
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState
+} from "react";
+
+// src/sandbox-desktop/vnc-channel.ts
+var OPEN = 1;
+var CLOSED = 3;
+var VncChannel = class {
+  constructor(link, protocol = "") {
+    this.link = link;
+    this.protocol = protocol;
+  }
+  link;
+  binaryType = "arraybuffer";
+  protocol;
+  onerror = null;
+  onopen = null;
+  onclose = null;
+  handler = null;
+  backlog = [];
+  state = OPEN;
+  get readyState() {
+    return this.state;
+  }
+  get onmessage() {
+    return this.handler;
+  }
+  set onmessage(handler) {
+    this.handler = handler;
+    if (handler === null) return;
+    for (const data of this.backlog.splice(0)) handler({ data });
+  }
+  send(data) {
+    if (this.state === OPEN) this.link.send(data);
+  }
+  /** noVNC is done with the connection. */
+  close() {
+    if (this.state !== OPEN) return;
+    this.state = CLOSED;
+    this.link.close();
+  }
+  /** A VNC frame arrived from the relay. */
+  receive(data) {
+    if (this.handler === null) this.backlog.push(data);
+    else this.handler({ data });
+  }
+  /** The relay closed the socket. */
+  closed(event) {
+    if (this.state === CLOSED) return;
+    this.state = CLOSED;
+    this.backlog = [];
+    this.onclose?.(event);
+  }
+};
+
+// src/sandbox-desktop/connection.ts
+var desktopSubprotocol = "anvia.desktop.v1";
+var retryableCodes = /* @__PURE__ */ new Set(["sandbox_unavailable", "timeout"]);
+var closeReason = /^([a-z_]+): (.*)$/s;
+var policyViolation = 1008;
+var DesktopConnection = class {
+  relay;
+  constructor(options) {
+    let channel;
+    let accepted = false;
+    const protocol = {
+      subprotocol: desktopSubprotocol,
+      label: "desktop",
+      open: (socket) => {
+        accepted = false;
+        channel = new VncChannel(
+          { send: (data) => socket.send(data), close: () => socket.close(1e3) },
+          socket.protocol
+        );
+      },
+      message: (event, session) => {
+        if (!accepted && channel !== void 0) {
+          accepted = true;
+          options.onChannel(channel, session.ready());
+        }
+        if (typeof event.data !== "string") {
+          channel?.receive(event.data);
+          return;
+        }
+        const message = parseText(event.data);
+        if (message?.type === "control") {
+          const { type: _type, ...control } = message;
+          options.onControl(control);
+        } else if (message?.type === "error") {
+          options.onNotice?.({
+            code: message.code ?? "protocol",
+            message: message.message ?? "The request failed."
+          });
+        }
+      },
+      close: (event, session) => {
+        channel?.closed(event);
+        const match = closeReason.exec(event.reason);
+        if (match !== null && !retryableCodes.has(match[1] ?? "")) {
+          session.fatal(match[2] ?? "The desktop could not be opened.");
+        } else if (event.code === policyViolation) {
+          session.fatal(event.reason || "The desktop relay refused what the viewer sent.");
+        }
+      }
+    };
+    this.relay = new RelayConnection({
+      url: options.url,
+      getTicket: options.getTicket,
+      onStatus: options.onStatus,
+      reconnect: options.reconnect,
+      protocol
+    });
+  }
+  start() {
+    this.relay.start();
+  }
+  retry() {
+    this.relay.retry();
+  }
+  /** Ask for control, which pauses the agent's inputs. The answer arrives as a `control` update. */
+  takeOver() {
+    this.relay.sendJson({ type: "takeover" });
+  }
+  release() {
+    this.relay.sendJson({ type: "release" });
+  }
+  dispose() {
+    this.relay.dispose();
+  }
+};
+function parseText(text) {
+  try {
+    const value = JSON.parse(text);
+    if (typeof value !== "object" || value === null) return void 0;
+    const type = value.type;
+    return type === "control" || type === "error" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/sandbox-desktop/desktop.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var defaultQualityLevel = 6;
+var defaultCompressionLevel = 2;
+function level(value, fallback) {
+  if (value === void 0 || !Number.isFinite(value)) return fallback;
+  return Math.min(9, Math.max(0, Math.round(value)));
+}
+var rootStyle = { position: "relative", width: "100%", height: "100%" };
+var screenStyle = { width: "100%", height: "100%" };
+var SandboxDesktop = forwardRef(
+  function SandboxDesktop2({
+    url,
+    ticket,
+    readOnly = false,
+    scaleToFit = true,
+    qualityLevel,
+    compressionLevel,
+    reconnect,
+    onStatusChange,
+    onControlChange,
+    renderStatus,
+    renderControls,
+    style,
+    ...rest
+  }, ref) {
+    const screen = useRef(null);
+    const connection = useRef(void 0);
+    const viewer = useRef(void 0);
+    const [status, setStatus] = useState({ state: "loading" });
+    const [control, setControl] = useState(void 0);
+    const [notice, setNotice] = useState(void 0);
+    const viewOnly = readOnly || control?.readOnly === true || control?.held === true && !control.you;
+    const latest = useRef({
+      ticket,
+      reconnect,
+      onStatusChange,
+      onControlChange,
+      scaleToFit,
+      viewOnly,
+      quality: level(qualityLevel, defaultQualityLevel),
+      compression: level(compressionLevel, defaultCompressionLevel)
+    });
+    latest.current = {
+      ticket,
+      reconnect,
+      onStatusChange,
+      onControlChange,
+      scaleToFit,
+      viewOnly,
+      quality: level(qualityLevel, defaultQualityLevel),
+      compression: level(compressionLevel, defaultCompressionLevel)
+    };
+    useImperativeHandle(
+      ref,
+      () => ({
+        focus: () => viewer.current?.focus(),
+        reconnect: () => connection.current?.retry(),
+        takeOver: () => connection.current?.takeOver(),
+        release: () => connection.current?.release()
+      }),
+      []
+    );
+    useEffect(() => {
+      if (viewer.current !== void 0) viewer.current.viewOnly = viewOnly;
+    }, [viewOnly]);
+    useEffect(() => {
+      if (viewer.current !== void 0) viewer.current.scaleViewport = scaleToFit;
+    }, [scaleToFit]);
+    useEffect(() => {
+      if (viewer.current !== void 0) viewer.current.qualityLevel = latest.current.quality;
+    }, [qualityLevel]);
+    useEffect(() => {
+      if (viewer.current !== void 0) {
+        viewer.current.compressionLevel = latest.current.compression;
+      }
+    }, [compressionLevel]);
+    useEffect(() => {
+      const container = screen.current;
+      if (container === null) return void 0;
+      let disposed = false;
+      let teardown;
+      const publish = (next) => {
+        if (disposed) return;
+        setStatus(next);
+        if (next.state !== "open") setControl(void 0);
+        latest.current.onStatusChange?.(next);
+      };
+      publish({ state: "loading" });
+      void (async () => {
+        const { default: Rfb } = await import("@novnc/novnc");
+        if (disposed) return;
+        const link = new DesktopConnection({
+          url,
+          getTicket: resolveTicket(() => latest.current.ticket),
+          reconnect: latest.current.reconnect,
+          onStatus: publish,
+          onChannel: (channel) => {
+            viewer.current?.disconnect();
+            const rfb = new Rfb(container, channel);
+            rfb.scaleViewport = latest.current.scaleToFit;
+            rfb.clipViewport = false;
+            rfb.resizeSession = false;
+            rfb.viewOnly = latest.current.viewOnly;
+            rfb.qualityLevel = latest.current.quality;
+            rfb.compressionLevel = latest.current.compression;
+            viewer.current = rfb;
+          },
+          onControl: (next) => {
+            if (disposed) return;
+            setControl(next);
+            setNotice(void 0);
+            latest.current.onControlChange?.(next);
+          },
+          onNotice: (next) => {
+            if (!disposed) setNotice(next);
+          }
+        });
+        connection.current = link;
+        link.start();
+        teardown = () => {
+          link.dispose();
+          viewer.current?.disconnect();
+          viewer.current = void 0;
+          connection.current = void 0;
+        };
+      })().catch((error) => {
+        publish({
+          state: "failed",
+          message: error instanceof Error ? error.message : "Could not load the desktop viewer."
+        });
+      });
+      return () => {
+        disposed = true;
+        teardown?.();
+      };
+    }, [url]);
+    const retry = () => connection.current?.retry();
+    const takeOver = () => connection.current?.takeOver();
+    const release = () => connection.current?.release();
+    const statusNode = renderStatus === void 0 ? /* @__PURE__ */ jsx(DefaultStatus, { status, retry }) : renderStatus(status, retry);
+    const controlsState = {
+      status,
+      control,
+      readOnly: readOnly || control?.readOnly === true,
+      notice,
+      takeOver,
+      release
+    };
+    const controlsNode = renderControls === void 0 ? /* @__PURE__ */ jsx(DefaultControls, { ...controlsState }) : renderControls(controlsState);
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ...rest,
+        "data-state": status.state,
+        "data-readonly": viewOnly ? "" : void 0,
+        "data-control": control?.you === true ? "you" : control?.held === true ? "other" : "none",
+        style: { ...rootStyle, ...style },
+        children: [
+          /* @__PURE__ */ jsx("div", { ref: screen, style: screenStyle }),
+          controlsNode,
+          statusNode
+        ]
+      }
+    );
+  }
+);
+var controlsStyle = {
+  position: "absolute",
+  top: 8,
+  left: 8,
+  zIndex: 1,
+  display: "flex",
+  gap: 8,
+  alignItems: "center",
+  padding: "2px 8px",
+  borderRadius: 4,
+  fontSize: 12,
+  background: "rgba(0, 0, 0, 0.7)",
+  color: "#fff"
+};
+function DefaultControls({
+  status,
+  control,
+  readOnly,
+  notice,
+  takeOver,
+  release
+}) {
+  if (status.state !== "open" || control === void 0) return null;
+  const who = control.you ? "You have control" : control.held ? `${control.holder ?? "Someone"} has control` : readOnly ? "View only" : "The agent has control";
+  return /* @__PURE__ */ jsxs("div", { "data-sandbox-desktop-controls": "", style: controlsStyle, children: [
+    /* @__PURE__ */ jsx("span", { children: who }),
+    control.you ? /* @__PURE__ */ jsx("button", { type: "button", onClick: release, children: "Release" }) : !readOnly && !control.held ? /* @__PURE__ */ jsx("button", { type: "button", onClick: takeOver, children: "Take over" }) : null,
+    notice === void 0 ? null : /* @__PURE__ */ jsx("span", { role: "alert", children: notice.message })
+  ] });
+}
+export {
+  SandboxDesktop,
+  desktopSubprotocol,
+  ticketSubprotocolPrefix
+};
+//# sourceMappingURL=index.js.map

package/dist/sandbox-desktop/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sandbox-desktop/desktop.tsx","../../src/sandbox-desktop/vnc-channel.ts","../../src/sandbox-desktop/connection.ts"],"sourcesContent":["import type RFB from \"@novnc/novnc\";\nimport {\n  forwardRef,\n  useEffect,\n  useImperativeHandle,\n  useRef,\n  useState,\n  type CSSProperties,\n  type ReactNode,\n} from \"react\";\n\nimport { type PrimitiveProps } from \"../primitives\";\nimport type { RelayReconnectOptions, RelayStatus } from \"../relay/connection\";\nimport { DefaultStatus } from \"../relay/status\";\nimport { type TicketSource, resolveTicket } from \"../relay/ticket\";\nimport { DesktopConnection, type SandboxDesktopControl } from \"./connection\";\n\nexport interface SandboxDesktopHandle {\n  focus(): void;\n  /** Reconnect now, after the viewer gave up. */\n  reconnect(): void;\n  /** Take control, which pauses the agent. */\n  takeOver(): void;\n  /** Hand control back. */\n  release(): void;\n}\n\nexport interface SandboxDesktopNotice {\n  code: string;\n  message: string;\n}\n\n/** What `renderControls` is given to draw its own take-over bar. */\nexport interface SandboxDesktopControlsState {\n  status: RelayStatus;\n  /** Undefined until the relay has said who has control. */\n  control: SandboxDesktopControl | undefined;\n  /** This viewer cannot send input, because of the prop or because the ticket says so. */\n  readOnly: boolean;\n  /** The latest failed request, such as taking over while someone else holds control. */\n  notice: SandboxDesktopNotice | undefined;\n  takeOver(): void;\n  release(): void;\n}\n\nexport type SandboxDesktopProps = Omit<PrimitiveProps<\"div\">, \"children\" | \"onError\"> & {\n  /**\n   * The hub's desktop endpoint (`hub.handleDesktopUpgrade`): `ws:`/`wss:`, `http:`/`https:`, or a\n   * path relative to this page.\n   */\n  url: string;\n  /**\n   * A one-time ticket, or a function returning one. Pass a function: tickets are single use, so\n   * each reconnect needs a fresh one. It travels as a WebSocket subprotocol, not in the URL.\n   */\n  ticket?: TicketSource;\n  /** Watch only. The server enforces it too; this also stops the viewer sending input. */\n  readOnly?: boolean;\n  /** Scale the desktop to fit the element. Default true. */\n  scaleToFit?: boolean;\n  /**\n   * JPEG quality asked of the server, 0 (smallest, blockiest) to 9 (best, most data). Default 6.\n   * Lower it for a slow link; it applies to the live connection.\n   */\n  qualityLevel?: number;\n  /**\n   * How hard the server compresses, 0 (fastest, most data) to 9 (slowest, least data). Default 2,\n   * which keeps the server's CPU low. Raise it for a slow link; it applies to the live connection.\n   */\n  compressionLevel?: number;\n  reconnect?: RelayReconnectOptions;\n  onStatusChange?: (status: RelayStatus) => void;\n  /** Called whenever the relay reports who has control. */\n  onControlChange?: (control: SandboxDesktopControl) => void;\n  /** Replace the default status line. Return null to show nothing. */\n  renderStatus?: (status: RelayStatus, retry: () => void) => ReactNode;\n  /** Replace the default take-over bar. Return null to show nothing. */\n  renderControls?: (state: SandboxDesktopControlsState) => ReactNode;\n};\n\nconst defaultQualityLevel = 6;\nconst defaultCompressionLevel = 2;\n\n/** A level noVNC accepts: a whole number from 0 to 9. Anything else falls back to the default. */\nfunction level(value: number | undefined, fallback: number): number {\n  if (value === undefined || !Number.isFinite(value)) return fallback;\n  return Math.min(9, Math.max(0, Math.round(value)));\n}\n\nconst rootStyle: CSSProperties = { position: \"relative\", width: \"100%\", height: \"100%\" };\nconst screenStyle: CSSProperties = { width: \"100%\", height: \"100%\" };\n\n/**\n * A viewer for a remote sandbox's desktop, drawn with noVNC. noVNC is loaded on demand, so it costs\n * nothing until a desktop mounts. It connects to the hub's desktop relay, reconnects with a fresh\n * ticket when the link drops, and lets a person take over control from the agent.\n */\nexport const SandboxDesktop = forwardRef<SandboxDesktopHandle, SandboxDesktopProps>(\n  function SandboxDesktop(\n    {\n      url,\n      ticket,\n      readOnly = false,\n      scaleToFit = true,\n      qualityLevel,\n      compressionLevel,\n      reconnect,\n      onStatusChange,\n      onControlChange,\n      renderStatus,\n      renderControls,\n      style,\n      ...rest\n    },\n    ref,\n  ) {\n    const screen = useRef<HTMLDivElement>(null);\n    const connection = useRef<DesktopConnection | undefined>(undefined);\n    const viewer = useRef<RFB | undefined>(undefined);\n    const [status, setStatus] = useState<RelayStatus>({ state: \"loading\" });\n    const [control, setControl] = useState<SandboxDesktopControl | undefined>(undefined);\n    const [notice, setNotice] = useState<SandboxDesktopNotice | undefined>(undefined);\n\n    // The viewer may send input unless it is read-only, or someone else holds control.\n    const viewOnly =\n      readOnly || control?.readOnly === true || (control?.held === true && !control.you);\n\n    // The latest props, read by long-lived callbacks without restarting the connection.\n    const latest = useRef({\n      ticket,\n      reconnect,\n      onStatusChange,\n      onControlChange,\n      scaleToFit,\n      viewOnly,\n      quality: level(qualityLevel, defaultQualityLevel),\n      compression: level(compressionLevel, defaultCompressionLevel),\n    });\n    latest.current = {\n      ticket,\n      reconnect,\n      onStatusChange,\n      onControlChange,\n      scaleToFit,\n      viewOnly,\n      quality: level(qualityLevel, defaultQualityLevel),\n      compression: level(compressionLevel, defaultCompressionLevel),\n    };\n\n    useImperativeHandle(\n      ref,\n      () => ({\n        focus: () => viewer.current?.focus(),\n        reconnect: () => connection.current?.retry(),\n        takeOver: () => connection.current?.takeOver(),\n        release: () => connection.current?.release(),\n      }),\n      [],\n    );\n\n    useEffect(() => {\n      if (viewer.current !== undefined) viewer.current.viewOnly = viewOnly;\n    }, [viewOnly]);\n    useEffect(() => {\n      if (viewer.current !== undefined) viewer.current.scaleViewport = scaleToFit;\n    }, [scaleToFit]);\n    useEffect(() => {\n      if (viewer.current !== undefined) viewer.current.qualityLevel = latest.current.quality;\n    }, [qualityLevel]);\n    useEffect(() => {\n      if (viewer.current !== undefined) {\n        viewer.current.compressionLevel = latest.current.compression;\n      }\n    }, [compressionLevel]);\n\n    useEffect(() => {\n      const container = screen.current;\n      if (container === null) return undefined;\n      let disposed = false;\n      let teardown: (() => void) | undefined;\n\n      const publish = (next: RelayStatus) => {\n        if (disposed) return;\n        setStatus(next);\n        // Who has control is unknown while the link is down.\n        if (next.state !== \"open\") setControl(undefined);\n        latest.current.onStatusChange?.(next);\n      };\n      publish({ state: \"loading\" });\n\n      void (async () => {\n        const { default: Rfb } = await import(\"@novnc/novnc\");\n        if (disposed) return;\n\n        const link = new DesktopConnection({\n          url,\n          getTicket: resolveTicket(() => latest.current.ticket),\n          reconnect: latest.current.reconnect,\n          onStatus: publish,\n          onChannel: (channel) => {\n            // noVNC clients are single-use: each attachment gets a new one.\n            viewer.current?.disconnect();\n            const rfb = new Rfb(container, channel);\n            rfb.scaleViewport = latest.current.scaleToFit;\n            rfb.clipViewport = false;\n            // The desktop's size is set through the hub's API, never by a viewer.\n            rfb.resizeSession = false;\n            rfb.viewOnly = latest.current.viewOnly;\n            // Set outright, not left to noVNC's defaults, so what a viewer asks of the server is\n            // stated here and can be changed.\n            rfb.qualityLevel = latest.current.quality;\n            rfb.compressionLevel = latest.current.compression;\n            viewer.current = rfb;\n          },\n          onControl: (next) => {\n            if (disposed) return;\n            setControl(next);\n            setNotice(undefined);\n            latest.current.onControlChange?.(next);\n          },\n          onNotice: (next) => {\n            if (!disposed) setNotice(next);\n          },\n        });\n        connection.current = link;\n        link.start();\n        teardown = () => {\n          link.dispose();\n          viewer.current?.disconnect();\n          viewer.current = undefined;\n          connection.current = undefined;\n        };\n      })().catch((error: unknown) => {\n        publish({\n          state: \"failed\",\n          message: error instanceof Error ? error.message : \"Could not load the desktop viewer.\",\n        });\n      });\n\n      return () => {\n        disposed = true;\n        teardown?.();\n      };\n    }, [url]);\n\n    const retry = () => connection.current?.retry();\n    const takeOver = () => connection.current?.takeOver();\n    const release = () => connection.current?.release();\n    const statusNode =\n      renderStatus === undefined ? (\n        <DefaultStatus status={status} retry={retry} />\n      ) : (\n        renderStatus(status, retry)\n      );\n    const controlsState: SandboxDesktopControlsState = {\n      status,\n      control,\n      readOnly: readOnly || control?.readOnly === true,\n      notice,\n      takeOver,\n      release,\n    };\n    const controlsNode =\n      renderControls === undefined ? (\n        <DefaultControls {...controlsState} />\n      ) : (\n        renderControls(controlsState)\n      );\n\n    return (\n      <div\n        {...rest}\n        data-state={status.state}\n        data-readonly={viewOnly ? \"\" : undefined}\n        data-control={control?.you === true ? \"you\" : control?.held === true ? \"other\" : \"none\"}\n        style={{ ...rootStyle, ...style }}\n      >\n        <div ref={screen} style={screenStyle} />\n        {controlsNode}\n        {statusNode}\n      </div>\n    );\n  },\n);\n\nconst controlsStyle: CSSProperties = {\n  position: \"absolute\",\n  top: 8,\n  left: 8,\n  zIndex: 1,\n  display: \"flex\",\n  gap: 8,\n  alignItems: \"center\",\n  padding: \"2px 8px\",\n  borderRadius: 4,\n  fontSize: 12,\n  background: \"rgba(0, 0, 0, 0.7)\",\n  color: \"#fff\",\n};\n\nfunction DefaultControls({\n  status,\n  control,\n  readOnly,\n  notice,\n  takeOver,\n  release,\n}: SandboxDesktopControlsState) {\n  if (status.state !== \"open\" || control === undefined) return null;\n  const who = control.you\n    ? \"You have control\"\n    : control.held\n      ? `${control.holder ?? \"Someone\"} has control`\n      : readOnly\n        ? \"View only\"\n        : \"The agent has control\";\n  return (\n    <div data-sandbox-desktop-controls=\"\" style={controlsStyle}>\n      <span>{who}</span>\n      {control.you ? (\n        <button type=\"button\" onClick={release}>\n          Release\n        </button>\n      ) : !readOnly && !control.held ? (\n        <button type=\"button\" onClick={takeOver}>\n          Take over\n        </button>\n      ) : null}\n      {notice === undefined ? null : <span role=\"alert\">{notice.message}</span>}\n    </div>\n  );\n}\n","/** What a {@link VncChannel} needs from the socket it wraps. */\nexport interface VncLink {\n  send(data: ArrayBufferLike | ArrayBufferView): void;\n  close(): void;\n}\n\n// WebSocket ready states, written out so this works wherever noVNC's own checks do.\nconst OPEN = 1;\nconst CLOSED = 3;\n\n/**\n * A WebSocket-shaped channel for noVNC to attach to. The hub's desktop relay mixes binary VNC frames\n * with JSON control frames on one socket, and noVNC understands only the former, so the link\n * hands this channel just the binary ones.\n *\n * The VNC server speaks first, so frames can arrive before noVNC has attached. They wait here\n * until it installs its `onmessage`.\n *\n * noVNC checks a channel for these property names (`send`, `close`, `binaryType`, `onerror`,\n * `onmessage`, `onopen`, `protocol`, `readyState`), as it does for a WebSocket or an\n * RTCDataChannel, so they must all be present.\n */\nexport class VncChannel {\n  binaryType = \"arraybuffer\";\n  protocol: string;\n  onerror: ((event: unknown) => void) | null = null;\n  onopen: ((event: unknown) => void) | null = null;\n  onclose: ((event: unknown) => void) | null = null;\n  private handler: ((event: { data: ArrayBuffer }) => void) | null = null;\n  private backlog: ArrayBuffer[] = [];\n  private state = OPEN;\n\n  constructor(\n    private readonly link: VncLink,\n    protocol = \"\",\n  ) {\n    this.protocol = protocol;\n  }\n\n  get readyState(): number {\n    return this.state;\n  }\n\n  get onmessage(): ((event: { data: ArrayBuffer }) => void) | null {\n    return this.handler;\n  }\n\n  set onmessage(handler: ((event: { data: ArrayBuffer }) => void) | null) {\n    this.handler = handler;\n    if (handler === null) return;\n    for (const data of this.backlog.splice(0)) handler({ data });\n  }\n\n  send(data: ArrayBufferLike | ArrayBufferView): void {\n    if (this.state === OPEN) this.link.send(data);\n  }\n\n  /** noVNC is done with the connection. */\n  close(): void {\n    if (this.state !== OPEN) return;\n    this.state = CLOSED;\n    this.link.close();\n  }\n\n  /** A VNC frame arrived from the relay. */\n  receive(data: ArrayBuffer): void {\n    if (this.handler === null) this.backlog.push(data);\n    else this.handler({ data });\n  }\n\n  /** The relay closed the socket. */\n  closed(event: { code: number; reason: string }): void {\n    if (this.state === CLOSED) return;\n    this.state = CLOSED;\n    this.backlog = [];\n    this.onclose?.(event);\n  }\n}\n","import {\n  type RelayProtocol,\n  type RelayReconnectOptions,\n  type RelaySession,\n  type RelayStatus,\n  RelayConnection,\n} from \"../relay/connection\";\nimport { VncChannel } from \"./vnc-channel\";\n\n/** Subprotocol the hub's `handleDesktopUpgrade` selects. */\nexport const desktopSubprotocol = \"anvia.desktop.v1\";\n\n/** Who is driving the desktop, as the relay reports it to this viewer. */\nexport interface SandboxDesktopControl {\n  /** Someone has taken control, which pauses the agent. */\n  held: boolean;\n  /** Who. Present when `held`. */\n  holder?: string;\n  /** When the hold lapses unless renewed. */\n  expiresAt?: string;\n  /** This viewer is the holder. */\n  you: boolean;\n  /** This viewer may only watch. */\n  readOnly: boolean;\n}\n\nexport interface DesktopConnectionOptions {\n  url: string;\n  getTicket?: (() => string | Promise<string>) | undefined;\n  reconnect?: RelayReconnectOptions | undefined;\n  onStatus: (status: RelayStatus) => void;\n  /** The relay accepted this attachment. Attach a VNC client to the channel. */\n  onChannel: (channel: VncChannel, reconnected: boolean) => void;\n  onControl: (control: SandboxDesktopControl) => void;\n  /** A request over the control channel failed, such as taking over while someone else holds it. */\n  onNotice?: ((notice: { code: string; message: string }) => void) | undefined;\n}\n\n/** Errors worth another attempt: the sandbox may simply not be reachable yet. */\nconst retryableCodes = new Set([\"sandbox_unavailable\", \"timeout\"]);\n/** The hub closes a socket it could not set up with `<error code>: <message>`. */\nconst closeReason = /^([a-z_]+): (.*)$/s;\n/** The relay closes with this code when the viewer sent something it could not account for. */\nconst policyViolation = 1008;\n\ntype ControlMessage = { type: \"control\" } & SandboxDesktopControl;\ntype ErrorMessage = { type: \"error\"; code?: string; message?: string };\n\n/**\n * One browser link to the hub's desktop relay, over a {@link RelayConnection}. It hands each\n * accepted attachment to the owner as a channel for a VNC client, and speaks the relay's small\n * JSON control protocol (`takeover`, `release`, and the `control` updates that come back).\n */\nexport class DesktopConnection {\n  private readonly relay: RelayConnection;\n\n  constructor(options: DesktopConnectionOptions) {\n    let channel: VncChannel | undefined;\n    let accepted = false;\n    const protocol: RelayProtocol = {\n      subprotocol: desktopSubprotocol,\n      label: \"desktop\",\n      open: (socket) => {\n        accepted = false;\n        channel = new VncChannel(\n          { send: (data) => socket.send(data), close: () => socket.close(1000) },\n          socket.protocol,\n        );\n      },\n      message: (event, session: RelaySession) => {\n        // The first thing the relay sends means it set the viewer up; a failure closes instead.\n        if (!accepted && channel !== undefined) {\n          accepted = true;\n          options.onChannel(channel, session.ready());\n        }\n        if (typeof event.data !== \"string\") {\n          channel?.receive(event.data as ArrayBuffer);\n          return;\n        }\n        const message = parseText(event.data);\n        if (message?.type === \"control\") {\n          const { type: _type, ...control } = message;\n          options.onControl(control);\n        } else if (message?.type === \"error\") {\n          options.onNotice?.({\n            code: message.code ?? \"protocol\",\n            message: message.message ?? \"The request failed.\",\n          });\n        }\n      },\n      close: (event, session) => {\n        channel?.closed(event);\n        const match = closeReason.exec(event.reason);\n        if (match !== null && !retryableCodes.has(match[1] ?? \"\")) {\n          session.fatal(match[2] ?? \"The desktop could not be opened.\");\n        } else if (event.code === policyViolation) {\n          session.fatal(event.reason || \"The desktop relay refused what the viewer sent.\");\n        }\n      },\n    };\n    this.relay = new RelayConnection({\n      url: options.url,\n      getTicket: options.getTicket,\n      onStatus: options.onStatus,\n      reconnect: options.reconnect,\n      protocol,\n    });\n  }\n\n  start(): void {\n    this.relay.start();\n  }\n\n  retry(): void {\n    this.relay.retry();\n  }\n\n  /** Ask for control, which pauses the agent's inputs. The answer arrives as a `control` update. */\n  takeOver(): void {\n    this.relay.sendJson({ type: \"takeover\" });\n  }\n\n  release(): void {\n    this.relay.sendJson({ type: \"release\" });\n  }\n\n  dispose(): void {\n    this.relay.dispose();\n  }\n}\n\nfunction parseText(text: string): ControlMessage | ErrorMessage | undefined {\n  try {\n    const value: unknown = JSON.parse(text);\n    if (typeof value !== \"object\" || value === null) return undefined;\n    const type = (value as { type?: unknown }).type;\n    return type === \"control\" || type === \"error\"\n      ? (value as ControlMessage | ErrorMessage)\n      : undefined;\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":"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","names":["SandboxDesktop"]}

package/dist/sandbox-terminal/index.d.ts

@@ -0,0 +1,68 @@
+import * as react from 'react';
+import { ReactNode } from 'react';
+import { ITerminalOptions } from '@xterm/xterm';
+import { P as PrimitiveProps } from '../render-CRKWam2v.js';
+import { R as RelayReconnectOptions, a as RelayStatus, b as RelayState, T as TicketSource } from '../ticket-pexI1zIa.js';
+export { t as ticketSubprotocolPrefix } from '../ticket-pexI1zIa.js';
+
+/** Subprotocol the hub's `handleTerminalUpgrade` requires. */
+declare const terminalSubprotocol = "anvia.terminal.v1";
+type SandboxTerminalState = RelayState;
+type SandboxTerminalStatus = RelayStatus;
+type SandboxTerminalReconnectOptions = RelayReconnectOptions;
+
+interface SandboxTerminalHandle {
+    focus(): void;
+    /** Reconnect now, after the terminal gave up. */
+    reconnect(): void;
+}
+type SandboxTerminalProps = Omit<PrimitiveProps<"div">, "children" | "onError"> & {
+    /**
+     * The hub's terminal endpoint (`hub.handleTerminalUpgrade`): `ws:`/`wss:`, `http:`/`https:`, or a
+     * path relative to this page.
+     */
+    url: string;
+    /** Sent as `?session=` so your `authorizeTerminal` can choose the session. The server decides. */
+    sessionName?: string;
+    /**
+     * A one-time ticket, or a function returning one. Pass a function: tickets are single use, so
+     * each reconnect needs a fresh one. It travels as a WebSocket subprotocol, not in the URL.
+     */
+    ticket?: TicketSource;
+    /** Show output only. The server enforces it too; this also stops the terminal taking input. */
+    readOnly?: boolean;
+    reconnect?: SandboxTerminalReconnectOptions;
+    /** xterm options, such as `fontSize` or `theme`. Applied when the terminal is created. */
+    terminalOptions?: ITerminalOptions;
+    onStatusChange?: (status: SandboxTerminalStatus) => void;
+    /** Replace the default status line. Return null to show nothing. */
+    renderStatus?: (status: SandboxTerminalStatus, retry: () => void) => ReactNode;
+};
+/**
+ * A terminal for a remote sandbox session, drawn with xterm.js. xterm is loaded on demand, so it
+ * costs nothing until a terminal mounts. Import `@xterm/xterm/css/xterm.css` once in your app.
+ */
+declare const SandboxTerminal: react.ForwardRefExoticComponent<Omit<PrimitiveProps<"div">, "children" | "onError"> & {
+    /**
+     * The hub's terminal endpoint (`hub.handleTerminalUpgrade`): `ws:`/`wss:`, `http:`/`https:`, or a
+     * path relative to this page.
+     */
+    url: string;
+    /** Sent as `?session=` so your `authorizeTerminal` can choose the session. The server decides. */
+    sessionName?: string;
+    /**
+     * A one-time ticket, or a function returning one. Pass a function: tickets are single use, so
+     * each reconnect needs a fresh one. It travels as a WebSocket subprotocol, not in the URL.
+     */
+    ticket?: TicketSource;
+    /** Show output only. The server enforces it too; this also stops the terminal taking input. */
+    readOnly?: boolean;
+    reconnect?: SandboxTerminalReconnectOptions;
+    /** xterm options, such as `fontSize` or `theme`. Applied when the terminal is created. */
+    terminalOptions?: ITerminalOptions;
+    onStatusChange?: (status: SandboxTerminalStatus) => void;
+    /** Replace the default status line. Return null to show nothing. */
+    renderStatus?: (status: SandboxTerminalStatus, retry: () => void) => ReactNode;
+} & react.RefAttributes<SandboxTerminalHandle>>;
+
+export { SandboxTerminal, type SandboxTerminalHandle, type SandboxTerminalProps, type SandboxTerminalReconnectOptions, type SandboxTerminalState, type SandboxTerminalStatus, terminalSubprotocol };

package/dist/sandbox-terminal/index.js

@@ -0,0 +1,216 @@
+import {
+  DefaultStatus,
+  RelayConnection,
+  resolveTicket,
+  ticketSubprotocolPrefix
+} from "../chunk-5FZKTDZR.js";
+
+// src/sandbox-terminal/terminal.tsx
+import {
+  forwardRef,
+  useEffect,
+  useImperativeHandle,
+  useRef,
+  useState
+} from "react";
+
+// src/sandbox-terminal/connection.ts
+var terminalSubprotocol = "anvia.terminal.v1";
+var retryableCodes = /* @__PURE__ */ new Set(["sandbox_unavailable", "timeout"]);
+var TerminalConnection = class {
+  relay;
+  constructor(options) {
+    let ready = false;
+    const protocol = {
+      subprotocol: terminalSubprotocol,
+      label: "terminal",
+      open: (socket) => {
+        ready = false;
+        const { cols, rows } = options.size();
+        socket.send(JSON.stringify({ type: "open", cols, rows }));
+      },
+      message: (event, session) => {
+        if (typeof event.data !== "string") {
+          if (ready) options.onOutput(new Uint8Array(event.data));
+          return;
+        }
+        const message = parseMessage(event.data);
+        if (message === void 0) return;
+        if (message.type === "ready") {
+          ready = true;
+          options.onOpen(session.ready());
+        } else if (message.type === "exit") {
+          session.ended({ message: message.reason ?? "exited", exitCode: message.exitCode });
+        } else if (!retryableCodes.has(message.code ?? "")) {
+          session.fatal(message.message ?? "The terminal could not be opened.");
+        }
+      }
+    };
+    this.relay = new RelayConnection({
+      url: options.url,
+      sessionName: options.sessionName,
+      getTicket: options.getTicket,
+      onStatus: options.onStatus,
+      reconnect: options.reconnect,
+      protocol
+    });
+  }
+  start() {
+    this.relay.start();
+  }
+  /** Try again now, for a link that gave up. */
+  retry() {
+    this.relay.retry();
+  }
+  sendInput(data) {
+    this.relay.sendJson({ type: "input", data });
+  }
+  sendResize(cols, rows) {
+    this.relay.sendJson({ type: "resize", cols, rows });
+  }
+  dispose() {
+    this.relay.dispose();
+  }
+};
+function parseMessage(text) {
+  try {
+    const value = JSON.parse(text);
+    if (typeof value !== "object" || value === null) return void 0;
+    const type = value.type;
+    return type === "ready" || type === "exit" || type === "error" ? value : void 0;
+  } catch {
+    return void 0;
+  }
+}
+
+// src/sandbox-terminal/terminal.tsx
+import { jsx, jsxs } from "react/jsx-runtime";
+var rootStyle = { position: "relative", width: "100%", height: "100%" };
+var screenStyle = { width: "100%", height: "100%" };
+var SandboxTerminal = forwardRef(
+  function SandboxTerminal2({
+    url,
+    sessionName,
+    ticket,
+    readOnly = false,
+    reconnect,
+    terminalOptions,
+    onStatusChange,
+    renderStatus,
+    style,
+    ...rest
+  }, ref) {
+    const screen = useRef(null);
+    const connection = useRef(void 0);
+    const terminal = useRef(void 0);
+    const [status, setStatus] = useState({ state: "loading" });
+    const latest = useRef({ ticket, reconnect, terminalOptions, onStatusChange });
+    latest.current = { ticket, reconnect, terminalOptions, onStatusChange };
+    useImperativeHandle(
+      ref,
+      () => ({
+        focus: () => terminal.current?.focus(),
+        reconnect: () => connection.current?.retry()
+      }),
+      []
+    );
+    useEffect(() => {
+      const container = screen.current;
+      if (container === null) return void 0;
+      let disposed = false;
+      let teardown;
+      const publish = (next) => {
+        if (disposed) return;
+        setStatus(next);
+        latest.current.onStatusChange?.(next);
+      };
+      publish({ state: "loading" });
+      void (async () => {
+        const [{ Terminal: XTerm }, { FitAddon }] = await Promise.all([
+          import("@xterm/xterm"),
+          import("@xterm/addon-fit")
+        ]);
+        if (disposed) return;
+        const xterm = new XTerm({
+          cursorBlink: !readOnly,
+          disableStdin: readOnly,
+          scrollback: 5e3,
+          ...latest.current.terminalOptions
+        });
+        const fit = new FitAddon();
+        xterm.loadAddon(fit);
+        xterm.open(container);
+        fit.fit();
+        terminal.current = xterm;
+        const link = new TerminalConnection({
+          url,
+          sessionName,
+          getTicket: resolveTicket(() => latest.current.ticket),
+          size: () => ({ cols: xterm.cols, rows: xterm.rows }),
+          onOutput: (bytes) => xterm.write(bytes),
+          // The hub redraws the session on every attach, so start from a clean screen.
+          onOpen: (reconnected) => {
+            if (reconnected) xterm.reset();
+            if (!readOnly) xterm.focus();
+          },
+          onStatus: publish,
+          reconnect: latest.current.reconnect
+        });
+        connection.current = link;
+        const input = xterm.onData((data) => {
+          if (!readOnly) link.sendInput(data);
+        });
+        const resized = xterm.onResize(({ cols, rows }) => {
+          if (!readOnly) link.sendResize(cols, rows);
+        });
+        let frame = 0;
+        const observer = new ResizeObserver(() => {
+          cancelAnimationFrame(frame);
+          frame = requestAnimationFrame(() => fit.fit());
+        });
+        observer.observe(container);
+        link.start();
+        teardown = () => {
+          cancelAnimationFrame(frame);
+          observer.disconnect();
+          input.dispose();
+          resized.dispose();
+          link.dispose();
+          xterm.dispose();
+          connection.current = void 0;
+          terminal.current = void 0;
+        };
+      })().catch((error) => {
+        publish({
+          state: "failed",
+          message: error instanceof Error ? error.message : "Could not load the terminal."
+        });
+      });
+      return () => {
+        disposed = true;
+        teardown?.();
+      };
+    }, [url, sessionName, readOnly]);
+    const retry = () => connection.current?.retry();
+    const statusNode = renderStatus === void 0 ? /* @__PURE__ */ jsx(DefaultStatus, { status, retry }) : renderStatus(status, retry);
+    return /* @__PURE__ */ jsxs(
+      "div",
+      {
+        ...rest,
+        "data-state": status.state,
+        "data-readonly": readOnly ? "" : void 0,
+        style: { ...rootStyle, ...style },
+        children: [
+          /* @__PURE__ */ jsx("div", { ref: screen, style: screenStyle }),
+          statusNode
+        ]
+      }
+    );
+  }
+);
+export {
+  SandboxTerminal,
+  terminalSubprotocol,
+  ticketSubprotocolPrefix
+};
+//# sourceMappingURL=index.js.map

package/dist/sandbox-terminal/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/sandbox-terminal/terminal.tsx","../../src/sandbox-terminal/connection.ts"],"sourcesContent":["import type { ITerminalOptions, Terminal } from \"@xterm/xterm\";\nimport {\n  forwardRef,\n  useEffect,\n  useImperativeHandle,\n  useRef,\n  useState,\n  type CSSProperties,\n  type ReactNode,\n} from \"react\";\n\nimport { type PrimitiveProps } from \"../primitives\";\nimport { DefaultStatus } from \"../relay/status\";\nimport { type TicketSource, resolveTicket } from \"../relay/ticket\";\nimport {\n  type SandboxTerminalReconnectOptions,\n  type SandboxTerminalStatus,\n  TerminalConnection,\n} from \"./connection\";\n\nexport interface SandboxTerminalHandle {\n  focus(): void;\n  /** Reconnect now, after the terminal gave up. */\n  reconnect(): void;\n}\n\nexport type SandboxTerminalProps = Omit<PrimitiveProps<\"div\">, \"children\" | \"onError\"> & {\n  /**\n   * The hub's terminal endpoint (`hub.handleTerminalUpgrade`): `ws:`/`wss:`, `http:`/`https:`, or a\n   * path relative to this page.\n   */\n  url: string;\n  /** Sent as `?session=` so your `authorizeTerminal` can choose the session. The server decides. */\n  sessionName?: string;\n  /**\n   * A one-time ticket, or a function returning one. Pass a function: tickets are single use, so\n   * each reconnect needs a fresh one. It travels as a WebSocket subprotocol, not in the URL.\n   */\n  ticket?: TicketSource;\n  /** Show output only. The server enforces it too; this also stops the terminal taking input. */\n  readOnly?: boolean;\n  reconnect?: SandboxTerminalReconnectOptions;\n  /** xterm options, such as `fontSize` or `theme`. Applied when the terminal is created. */\n  terminalOptions?: ITerminalOptions;\n  onStatusChange?: (status: SandboxTerminalStatus) => void;\n  /** Replace the default status line. Return null to show nothing. */\n  renderStatus?: (status: SandboxTerminalStatus, retry: () => void) => ReactNode;\n};\n\nconst rootStyle: CSSProperties = { position: \"relative\", width: \"100%\", height: \"100%\" };\nconst screenStyle: CSSProperties = { width: \"100%\", height: \"100%\" };\n\n/**\n * A terminal for a remote sandbox session, drawn with xterm.js. xterm is loaded on demand, so it\n * costs nothing until a terminal mounts. Import `@xterm/xterm/css/xterm.css` once in your app.\n */\nexport const SandboxTerminal = forwardRef<SandboxTerminalHandle, SandboxTerminalProps>(\n  function SandboxTerminal(\n    {\n      url,\n      sessionName,\n      ticket,\n      readOnly = false,\n      reconnect,\n      terminalOptions,\n      onStatusChange,\n      renderStatus,\n      style,\n      ...rest\n    },\n    ref,\n  ) {\n    const screen = useRef<HTMLDivElement>(null);\n    const connection = useRef<TerminalConnection | undefined>(undefined);\n    const terminal = useRef<Terminal | undefined>(undefined);\n    const [status, setStatus] = useState<SandboxTerminalStatus>({ state: \"loading\" });\n\n    // The latest props, read by long-lived callbacks without restarting the terminal.\n    const latest = useRef({ ticket, reconnect, terminalOptions, onStatusChange });\n    latest.current = { ticket, reconnect, terminalOptions, onStatusChange };\n\n    useImperativeHandle(\n      ref,\n      () => ({\n        focus: () => terminal.current?.focus(),\n        reconnect: () => connection.current?.retry(),\n      }),\n      [],\n    );\n\n    useEffect(() => {\n      const container = screen.current;\n      if (container === null) return undefined;\n      let disposed = false;\n      let teardown: (() => void) | undefined;\n\n      const publish = (next: SandboxTerminalStatus) => {\n        if (disposed) return;\n        setStatus(next);\n        latest.current.onStatusChange?.(next);\n      };\n      publish({ state: \"loading\" });\n\n      void (async () => {\n        const [{ Terminal: XTerm }, { FitAddon }] = await Promise.all([\n          import(\"@xterm/xterm\"),\n          import(\"@xterm/addon-fit\"),\n        ]);\n        if (disposed) return;\n\n        const xterm = new XTerm({\n          cursorBlink: !readOnly,\n          disableStdin: readOnly,\n          scrollback: 5_000,\n          ...latest.current.terminalOptions,\n        });\n        const fit = new FitAddon();\n        xterm.loadAddon(fit);\n        xterm.open(container);\n        fit.fit();\n        terminal.current = xterm;\n\n        const link = new TerminalConnection({\n          url,\n          sessionName,\n          getTicket: resolveTicket(() => latest.current.ticket),\n          size: () => ({ cols: xterm.cols, rows: xterm.rows }),\n          onOutput: (bytes) => xterm.write(bytes),\n          // The hub redraws the session on every attach, so start from a clean screen.\n          onOpen: (reconnected) => {\n            if (reconnected) xterm.reset();\n            if (!readOnly) xterm.focus();\n          },\n          onStatus: publish,\n          reconnect: latest.current.reconnect,\n        });\n        connection.current = link;\n\n        const input = xterm.onData((data) => {\n          if (!readOnly) link.sendInput(data);\n        });\n        const resized = xterm.onResize(({ cols, rows }) => {\n          if (!readOnly) link.sendResize(cols, rows);\n        });\n        let frame = 0;\n        const observer = new ResizeObserver(() => {\n          cancelAnimationFrame(frame);\n          frame = requestAnimationFrame(() => fit.fit());\n        });\n        observer.observe(container);\n\n        link.start();\n        teardown = () => {\n          cancelAnimationFrame(frame);\n          observer.disconnect();\n          input.dispose();\n          resized.dispose();\n          link.dispose();\n          xterm.dispose();\n          connection.current = undefined;\n          terminal.current = undefined;\n        };\n      })().catch((error: unknown) => {\n        publish({\n          state: \"failed\",\n          message: error instanceof Error ? error.message : \"Could not load the terminal.\",\n        });\n      });\n\n      return () => {\n        disposed = true;\n        teardown?.();\n      };\n    }, [url, sessionName, readOnly]);\n\n    const retry = () => connection.current?.retry();\n    const statusNode =\n      renderStatus === undefined ? (\n        <DefaultStatus status={status} retry={retry} />\n      ) : (\n        renderStatus(status, retry)\n      );\n\n    return (\n      <div\n        {...rest}\n        data-state={status.state}\n        data-readonly={readOnly ? \"\" : undefined}\n        style={{ ...rootStyle, ...style }}\n      >\n        <div ref={screen} style={screenStyle} />\n        {statusNode}\n      </div>\n    );\n  },\n);\n","import {\n  type RelayProtocol,\n  type RelayReconnectOptions,\n  type RelaySession,\n  type RelayState,\n  type RelayStatus,\n  RelayConnection,\n} from \"../relay/connection\";\n\nexport { ticketSubprotocolPrefix } from \"../relay/connection\";\n\n/** Subprotocol the hub's `handleTerminalUpgrade` requires. */\nexport const terminalSubprotocol = \"anvia.terminal.v1\";\n\nexport type SandboxTerminalState = RelayState;\nexport type SandboxTerminalStatus = RelayStatus;\nexport type SandboxTerminalReconnectOptions = RelayReconnectOptions;\n\nexport interface TerminalConnectionOptions {\n  /** `ws:`, `wss:`, `http:`, `https:`, or a path relative to the page. */\n  url: string;\n  /** Appended as `?session=` so the server can pick the session. The server stays in charge. */\n  sessionName?: string | undefined;\n  /** Called for every attempt, because tickets are single use. */\n  getTicket?: (() => string | Promise<string>) | undefined;\n  size: () => { cols: number; rows: number };\n  onOutput: (bytes: Uint8Array) => void;\n  /** The terminal is attached. `reconnected` is true when an earlier attachment existed. */\n  onOpen: (reconnected: boolean) => void;\n  onStatus: (status: SandboxTerminalStatus) => void;\n  reconnect?: SandboxTerminalReconnectOptions | undefined;\n}\n\n/** Errors worth another attempt: the sandbox may simply not be reachable yet. */\nconst retryableCodes = new Set([\"sandbox_unavailable\", \"timeout\"]);\n\ntype ServerMessage =\n  | { type: \"ready\"; readOnly?: boolean }\n  | { type: \"exit\"; reason?: string; exitCode?: number }\n  | { type: \"error\"; code?: string; message?: string };\n\n/**\n * One browser terminal link: speaks the hub's terminal relay protocol over a {@link\n * RelayConnection}. It knows nothing about xterm, so it is testable on its own.\n */\nexport class TerminalConnection {\n  private readonly relay: RelayConnection;\n\n  constructor(options: TerminalConnectionOptions) {\n    // The relay only sends output once it has opened the terminal, which starts with our size.\n    let ready = false;\n    const protocol: RelayProtocol = {\n      subprotocol: terminalSubprotocol,\n      label: \"terminal\",\n      open: (socket) => {\n        ready = false;\n        const { cols, rows } = options.size();\n        socket.send(JSON.stringify({ type: \"open\", cols, rows }));\n      },\n      message: (event, session: RelaySession) => {\n        if (typeof event.data !== \"string\") {\n          if (ready) options.onOutput(new Uint8Array(event.data as ArrayBuffer));\n          return;\n        }\n        const message = parseMessage(event.data);\n        if (message === undefined) return;\n        if (message.type === \"ready\") {\n          ready = true;\n          options.onOpen(session.ready());\n        } else if (message.type === \"exit\") {\n          session.ended({ message: message.reason ?? \"exited\", exitCode: message.exitCode });\n        } else if (!retryableCodes.has(message.code ?? \"\")) {\n          session.fatal(message.message ?? \"The terminal could not be opened.\");\n        }\n      },\n    };\n    this.relay = new RelayConnection({\n      url: options.url,\n      sessionName: options.sessionName,\n      getTicket: options.getTicket,\n      onStatus: options.onStatus,\n      reconnect: options.reconnect,\n      protocol,\n    });\n  }\n\n  start(): void {\n    this.relay.start();\n  }\n\n  /** Try again now, for a link that gave up. */\n  retry(): void {\n    this.relay.retry();\n  }\n\n  sendInput(data: string): void {\n    this.relay.sendJson({ type: \"input\", data });\n  }\n\n  sendResize(cols: number, rows: number): void {\n    this.relay.sendJson({ type: \"resize\", cols, rows });\n  }\n\n  dispose(): void {\n    this.relay.dispose();\n  }\n}\n\nfunction parseMessage(text: string): ServerMessage | undefined {\n  try {\n    const value: unknown = JSON.parse(text);\n    if (typeof value !== \"object\" || value === null) return undefined;\n    const type = (value as { type?: unknown }).type;\n    return type === \"ready\" || type === \"exit\" || type === \"error\"\n      ? (value as ServerMessage)\n      : undefined;\n  } catch {\n    return undefined;\n  }\n}\n"],"mappings":"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","names":["SandboxTerminal"]}

package/dist/ticket-pexI1zIa.d.ts

@@ -0,0 +1,33 @@
+/** The prefix a ticket travels under in `Sec-WebSocket-Protocol`. */
+declare const ticketSubprotocolPrefix = "anvia.ticket.";
+type RelayState = 
+/** The viewer library is still loading. */
+"loading" | "connecting" | "open"
+/** The link dropped and another attempt is scheduled. */
+ | "reconnecting"
+/** The session itself ended; reconnecting would not help. */
+ | "ended"
+/** Gave up: a fatal error, or reconnect attempts ran out. */
+ | "failed";
+interface RelayStatus {
+    state: RelayState;
+    /** Reconnect attempt number while `reconnecting`. */
+    attempt?: number;
+    /** Delay before the next attempt while `reconnecting`. */
+    retryInMs?: number;
+    /** Exit code when the session ended with one. */
+    exitCode?: number;
+    /** Human-readable cause for `ended` and `failed`. */
+    message?: string;
+}
+interface RelayReconnectOptions {
+    initialDelayMs?: number;
+    maxDelayMs?: number;
+    /** Consecutive failed attempts before giving up. Default 10. */
+    maxAttempts?: number;
+}
+
+/** What a viewer's `ticket` prop can be: a ticket, or a function returning one per connection. */
+type TicketSource = string | (() => string | Promise<string>);
+
+export { type RelayReconnectOptions as R, type TicketSource as T, type RelayStatus as a, type RelayState as b, ticketSubprotocolPrefix as t };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anvia/react-ui",
-  "version": "1.1.9",
+  "version": "1.2.0",
   "description": "Composable, headless React UI primitives for Anvia applications.",
   "author": "anvia",
   "license": "MIT",
@@ -51,6 +51,14 @@
       "types": "./dist/message/index.d.ts",
       "import": "./dist/message/index.js"
     },
+    "./sandbox-terminal": {
+      "types": "./dist/sandbox-terminal/index.d.ts",
+      "import": "./dist/sandbox-terminal/index.js"
+    },
+    "./sandbox-desktop": {
+      "types": "./dist/sandbox-desktop/index.d.ts",
+      "import": "./dist/sandbox-desktop/index.js"
+    },
     "./selection-toolbar": {
       "types": "./dist/selection-toolbar/index.d.ts",
       "import": "./dist/selection-toolbar/index.js"
@@ -87,33 +95,48 @@
   "peerDependencies": {
     "react": ">=18",
     "react-dom": ">=18",
-    "@anvia/graph": "^1.1.5",
+    "@xterm/xterm": ">=5.5.0",
+    "@xterm/addon-fit": ">=0.10.0",
+    "@novnc/novnc": ">=1.5.0",
     "@anvia/client": "^1.6.0",
+    "@anvia/graph": "^1.1.5",
     "@anvia/react": "^1.1.5"
   },
   "peerDependenciesMeta": {
     "@anvia/graph": {
       "optional": true
+    },
+    "@xterm/xterm": {
+      "optional": true
+    },
+    "@xterm/addon-fit": {
+      "optional": true
+    },
+    "@novnc/novnc": {
+      "optional": true
     }
   },
   "devDependencies": {
+    "@novnc/novnc": "^1.7.0",
     "@testing-library/react": "^16.3.3",
     "@types/node": "^24.9.1",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
     "@vitest/coverage-v8": "4.1.11",
+    "@xterm/addon-fit": "^0.10.0",
+    "@xterm/xterm": "^5.5.0",
     "happy-dom": "20.9.0",
     "react": "19.3.0",
     "react-dom": "19.3.0",
     "tsup": "^8.5.0",
     "typescript": "^5.9.3",
     "vitest": "^4.1.11",
-    "@anvia/client": "1.6.0",
     "@anvia/react": "1.1.5",
+    "@anvia/client": "1.6.0",
     "@anvia/graph": "1.1.5"
   },
   "scripts": {
-    "build": "tsup src/index.ts src/attachment/index.ts src/chat/index.ts src/completion/index.ts src/graph-explorer/index.ts src/human-input/index.ts src/image/index.ts src/message/index.ts src/selection-toolbar/index.ts src/shared.ts src/stream/index.ts src/thread-list/index.ts --format esm --dts --sourcemap --clean --external react --external react-dom",
+    "build": "tsup src/index.ts src/attachment/index.ts src/chat/index.ts src/completion/index.ts src/graph-explorer/index.ts src/human-input/index.ts src/image/index.ts src/message/index.ts src/sandbox-desktop/index.ts src/sandbox-terminal/index.ts src/selection-toolbar/index.ts src/shared.ts src/stream/index.ts src/thread-list/index.ts --format esm --dts --sourcemap --clean --external react --external react-dom --external @xterm/xterm --external @xterm/addon-fit --external @novnc/novnc",
     "coverage": "vitest run --coverage",
     "test": "vitest run",
     "typecheck": "tsc --noEmit"