@agent-native/toolkit 0.23.1 → 0.198.1

package/src/app/terminal/AgentTerminal.tsx

@@ -0,0 +1,542 @@
+import { parseSubmitChatMessage } from "@agent-native/core/client/agent-chat";
+import { agentNativePath } from "@agent-native/core/client/api-path";
+import {
+  getFrameOrigin,
+  isTrustedFrameMessage,
+} from "@agent-native/core/client/frame";
+import { useRef, useEffect, useState, type CSSProperties } from "react";
+
+export interface AgentTerminalProps {
+  command?: string;
+  flags?: string;
+  wsUrl?: string;
+  hideInFrame?: boolean;
+  theme?: Record<string, string>;
+  fontSize?: number;
+  autoFocus?: boolean;
+  className?: string;
+  style?: CSSProperties;
+  onConnectionChange?: (connected: boolean) => void;
+  onAgentRunningChange?: (running: boolean) => void;
+  submitRequest?: AgentTerminalSubmitRequest;
+  onPromptSubmitted?: (request: AgentTerminalSubmitRequest) => void;
+}
+
+export interface AgentTerminalSubmitRequest {
+  id: string | number;
+  text: string;
+}
+
+let cssInjected = false;
+function injectXtermCss() {
+  if (cssInjected || typeof document === "undefined") return;
+  cssInjected = true;
+  const style = document.createElement("style");
+  style.textContent = `
+    .xterm { position: relative; user-select: none; }
+    .xterm.focus, .xterm:focus { outline: none; }
+    .xterm .xterm-helpers { position: absolute; top: 0; z-index: 5; }
+    .xterm .xterm-helper-textarea {
+      padding: 0; border: 0; margin: 0;
+      position: absolute; opacity: 0; left: -9999em; top: 0;
+      width: 0; height: 0; z-index: -5;
+      white-space: nowrap; overflow: hidden; resize: none;
+    }
+    .xterm .composition-view { display: none; position: absolute; white-space: nowrap; z-index: 1; }
+    .xterm .composition-view.active { display: block; }
+    .xterm .xterm-viewport {
+      background-color: var(--agent-terminal-background); overflow-y: auto;
+      scrollbar-width: thin;
+      scrollbar-color: hsl(var(--muted-foreground) / 0.22) transparent;
+      cursor: default; position: absolute; right: 0; left: 0; top: 0; bottom: 0;
+    }
+    .xterm .xterm-viewport::-webkit-scrollbar { width: 8px; height: 8px; }
+    .xterm .xterm-viewport::-webkit-scrollbar-track { background: transparent; }
+    .xterm .xterm-viewport::-webkit-scrollbar-thumb {
+      background: hsl(var(--muted-foreground) / 0.22);
+      border-radius: 999px;
+    }
+    .xterm .xterm-viewport::-webkit-scrollbar-thumb:hover {
+      background: hsl(var(--muted-foreground) / 0.36);
+    }
+    .xterm .xterm-screen { position: relative; }
+    .xterm .xterm-screen canvas { position: absolute; left: 0; top: 0; }
+    .xterm .xterm-scroll-area { visibility: hidden; }
+    .xterm-char-measure-element {
+      display: inline-block; visibility: hidden; position: absolute; top: 0; left: -9999em;
+      line-height: normal;
+    }
+    .xterm.enable-mouse-events { cursor: default; }
+    .xterm.xterm-cursor-pointer, .xterm .xterm-cursor-pointer { cursor: pointer; }
+    .xterm.column-select.focus { cursor: crosshair; }
+    .xterm .xterm-accessibility:not(.debug),
+    .xterm .xterm-message { position: absolute; left: 0; top: 0; bottom: 0; right: 0; z-index: 10; color: transparent; pointer-events: none; }
+    .xterm .xterm-accessibility-tree:not(.debug) *::selection { color: transparent; }
+    .xterm .xterm-accessibility-tree { user-select: text; white-space: pre; }
+    .xterm .live-region { position: absolute; left: -9999px; width: 1px; height: 1px; overflow: hidden; }
+    .xterm .xterm-dim { opacity: 0.5; }
+    .xterm .xterm-underline-1 { text-decoration: underline; }
+    .xterm .xterm-underline-2 { text-decoration: double underline; }
+    .xterm .xterm-underline-3 { text-decoration: wavy underline; }
+    .xterm .xterm-underline-4 { text-decoration: dotted underline; }
+    .xterm .xterm-underline-5 { text-decoration: dashed underline; }
+    .xterm .xterm-overline { text-decoration: overline; }
+    .xterm .xterm-strikethrough { text-decoration: line-through; }
+    .xterm .xterm-screen .xterm-decoration-container .xterm-decoration { z-index: 6; position: absolute; }
+    .xterm .xterm-screen .xterm-decoration-container .xterm-decoration.xterm-decoration-top-layer { z-index: 7; }
+    .xterm .xterm-decoration-overview-ruler { z-index: 8; position: absolute; top: 0; right: 0; pointer-events: none; }
+    .xterm .xterm-decoration-top { z-index: 2; position: relative; }
+  `;
+  document.head.appendChild(style);
+}
+
+const DEFAULT_THEME = {
+  background: "#111",
+  foreground: "#e0e0e0",
+  cursor: "#58a6ff",
+  selectionBackground: "#264f78",
+  black: "#484f58",
+  red: "#ff7b72",
+  green: "#3fb950",
+  yellow: "#d29922",
+  blue: "#58a6ff",
+  magenta: "#bc8cff",
+  cyan: "#39d353",
+  white: "#b1bac4",
+};
+
+interface TerminalInfo {
+  available: boolean;
+  wsPort?: number;
+  command?: string;
+  error?: string;
+}
+
+export function formatWebSocketHostname(hostname: string) {
+  return hostname.includes(":") && !hostname.startsWith("[")
+    ? `[${hostname}]`
+    : hostname;
+}
+
+export function AgentTerminal({
+  command,
+  flags,
+  wsUrl: wsUrlProp,
+  hideInFrame = true,
+  theme,
+  fontSize = 12,
+  autoFocus = true,
+  className,
+  style,
+  onConnectionChange,
+  onAgentRunningChange,
+  submitRequest,
+  onPromptSubmitted,
+}: AgentTerminalProps) {
+  const termRef = useRef<HTMLDivElement>(null);
+  const submitPromptRef = useRef<
+    ((request: AgentTerminalSubmitRequest) => void) | null
+  >(null);
+  const pendingSubmitRequestRef = useRef<AgentTerminalSubmitRequest | null>(
+    null,
+  );
+  const autoFocusRef = useRef(autoFocus);
+  autoFocusRef.current = autoFocus;
+  const focusTerminalRef = useRef<(() => void) | null>(null);
+  const onPromptSubmittedRef = useRef(onPromptSubmitted);
+  onPromptSubmittedRef.current = onPromptSubmitted;
+  const [connected, setConnected] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [inFrame, setInFrame] = useState(false);
+
+  useEffect(() => {
+    if (!hideInFrame) return;
+    const check = () => {
+      if (getFrameOrigin()) setInFrame(true);
+    };
+    check();
+    const timer = setTimeout(check, 500);
+    return () => clearTimeout(timer);
+  }, [hideInFrame]);
+
+  useEffect(() => {
+    onConnectionChange?.(connected);
+  }, [connected, onConnectionChange]);
+
+  useEffect(() => {
+    if (autoFocus) {
+      focusTerminalRef.current?.();
+      return;
+    }
+    const activeElement = document.activeElement;
+    if (
+      activeElement instanceof HTMLElement &&
+      termRef.current?.contains(activeElement)
+    ) {
+      activeElement.blur();
+    }
+  }, [autoFocus]);
+
+  useEffect(() => {
+    if (typeof window === "undefined") return;
+    if (hideInFrame && inFrame) return;
+
+    const containerRaw = termRef.current;
+    if (!containerRaw) return;
+    const container: HTMLDivElement = containerRaw;
+
+    let disposed = false;
+    let ws: WebSocket | null = null;
+    let cleanupMessageHandler: (() => void) | null = null;
+
+    async function init() {
+      const [{ Terminal }, { FitAddon }, { WebLinksAddon }] = await Promise.all(
+        [
+          import("@xterm/xterm"),
+          import("@xterm/addon-fit"),
+          import("@xterm/addon-web-links"),
+        ],
+      );
+
+      if (disposed || !container) return;
+
+      injectXtermCss();
+
+      const term = new Terminal({
+        cursorBlink: true,
+        fontSize,
+        fontFamily: "'SF Mono', 'Fira Code', 'Cascadia Code', Menlo, monospace",
+        theme: { ...DEFAULT_THEME, ...theme },
+      });
+
+      const fitAddon = new FitAddon();
+      const webLinksAddon = new WebLinksAddon((_event, uri) => {
+        window.open(uri, "_blank", "noopener");
+      });
+
+      term.loadAddon(fitAddon);
+      term.loadAddon(webLinksAddon);
+      term.open(container);
+      const focusTerminal = () => term.focus();
+      focusTerminalRef.current = focusTerminal;
+      if (autoFocusRef.current) focusTerminal();
+
+      let fitPending = false;
+      function fitAndResize() {
+        if (fitPending) return;
+        fitPending = true;
+        requestAnimationFrame(() => {
+          fitPending = false;
+          if (
+            disposed ||
+            !container.isConnected ||
+            container.clientWidth <= 0 ||
+            container.clientHeight <= 0
+          ) {
+            return;
+          }
+          try {
+            fitAddon.fit();
+            sendResize();
+          } catch {}
+        });
+      }
+
+      fitAndResize();
+      const initialFitTimers = [
+        setTimeout(fitAndResize, 50),
+        setTimeout(fitAndResize, 250),
+      ];
+
+      const handleVisibilityOrFocus = () => fitAndResize();
+      window.addEventListener("focus", handleVisibilityOrFocus);
+      document.addEventListener("visibilitychange", handleVisibilityOrFocus);
+
+      const resizeObserver = new ResizeObserver(() => {
+        fitAndResize();
+      });
+      resizeObserver.observe(container);
+
+      let terminalDisposed = false;
+      function disposeTerminal() {
+        if (terminalDisposed) return;
+        terminalDisposed = true;
+        initialFitTimers.forEach(clearTimeout);
+        window.removeEventListener("focus", handleVisibilityOrFocus);
+        document.removeEventListener(
+          "visibilitychange",
+          handleVisibilityOrFocus,
+        );
+        resizeObserver.disconnect();
+        if (focusTerminalRef.current === focusTerminal) {
+          focusTerminalRef.current = null;
+        }
+        term.dispose();
+      }
+
+      function disposeIfCancelled() {
+        if (!disposed) return false;
+        disposeTerminal();
+        return true;
+      }
+
+      let wsUrl = wsUrlProp;
+      let resolvedCommand = command;
+      if (!wsUrl) {
+        try {
+          const res = await fetch(
+            agentNativePath("/_agent-native/agent-terminal-info"),
+          );
+          if (disposeIfCancelled()) return;
+          const info: TerminalInfo = await res.json();
+          if (disposeIfCancelled()) return;
+          if (!info.available) {
+            setError(info.error || "Agent terminal not available");
+            disposeTerminal();
+            return;
+          }
+          const protocol = location.protocol === "https:" ? "wss:" : "ws:";
+          const host = formatWebSocketHostname(location.hostname);
+          wsUrl = `${protocol}//${host}:${info.wsPort}/ws`;
+          if (!resolvedCommand && info.command) {
+            resolvedCommand = info.command;
+          }
+        } catch (err) {
+          if (disposeIfCancelled()) return;
+          setError("Failed to discover terminal server");
+          disposeTerminal();
+          return;
+        }
+      }
+
+      const fullWsUrl = new URL(wsUrl);
+      if (resolvedCommand) {
+        fullWsUrl.searchParams.set("command", resolvedCommand);
+      }
+      if (flags) fullWsUrl.searchParams.set("flags", flags);
+
+      let agentRunning = false;
+      let idleTimer: ReturnType<typeof setTimeout> | null = null;
+      let connectionId = 0;
+
+      function submitPrompt(request: AgentTerminalSubmitRequest) {
+        const text = request.text.trim();
+        if (!text) return;
+        if (!ws || ws.readyState !== WebSocket.OPEN) {
+          pendingSubmitRequestRef.current = request;
+          return;
+        }
+        ws.send(text + "\r");
+        agentRunning = true;
+        notifyAgentRunning(true);
+        if (pendingSubmitRequestRef.current?.id === request.id) {
+          pendingSubmitRequestRef.current = null;
+        }
+        onPromptSubmittedRef.current?.(request);
+      }
+
+      function sendResize() {
+        if (ws && ws.readyState === WebSocket.OPEN && term) {
+          ws.send(
+            JSON.stringify({
+              type: "resize",
+              cols: term.cols,
+              rows: term.rows,
+            }),
+          );
+        }
+      }
+
+      function notifyAgentRunning(running: boolean) {
+        onAgentRunningChange?.(running);
+        window.dispatchEvent(
+          new CustomEvent("agentNative.chatRunning", {
+            detail: { isRunning: running },
+          }),
+        );
+      }
+
+      function connect(url: string) {
+        const thisId = ++connectionId;
+
+        if (ws) {
+          ws.close();
+          ws = null;
+        }
+
+        const socket = new WebSocket(url);
+        socket.binaryType = "arraybuffer";
+        ws = socket;
+
+        socket.onopen = () => {
+          setConnected(true);
+          setError(null);
+          if (autoFocusRef.current) focusTerminal();
+          socket.send(
+            JSON.stringify({
+              type: "resize",
+              cols: term.cols,
+              rows: term.rows,
+            }),
+          );
+          const pendingRequest = pendingSubmitRequestRef.current;
+          if (pendingRequest) submitPrompt(pendingRequest);
+        };
+
+        socket.onmessage = (event) => {
+          const data =
+            event.data instanceof ArrayBuffer
+              ? new TextDecoder().decode(event.data)
+              : event.data;
+
+          try {
+            const msg = JSON.parse(data);
+            if (msg.type === "setup-status") {
+              if (msg.status === "not-found" || msg.status === "failed") {
+                setError(msg.message);
+                connectionId++;
+              }
+              return;
+            }
+          } catch {
+            // Not JSON — regular terminal output
+          }
+
+          setError(null);
+          term.write(data);
+
+          if (data.includes("❯") || data.includes("\x1b[?25h")) {
+            if (idleTimer) clearTimeout(idleTimer);
+            idleTimer = setTimeout(() => {
+              if (agentRunning) {
+                agentRunning = false;
+                notifyAgentRunning(false);
+              }
+            }, 600);
+          } else if (agentRunning) {
+            if (idleTimer) clearTimeout(idleTimer);
+          }
+        };
+
+        socket.onclose = () => {
+          setConnected(false);
+          if (connectionId === thisId && !disposed) {
+            setTimeout(() => {
+              if (connectionId === thisId && !disposed) {
+                connect(url);
+              }
+            }, 3000);
+          }
+        };
+
+        socket.onerror = () => socket.close();
+      }
+
+      term.onData((data) => {
+        if (ws && ws.readyState === WebSocket.OPEN) {
+          ws.send(data);
+        }
+      });
+
+      const messageHandler = (event: MessageEvent) => {
+        if (!isTrustedFrameMessage(event)) return;
+        const parsed = parseSubmitChatMessage(event);
+        if (parsed && ws && ws.readyState === WebSocket.OPEN) {
+          ws.send(parsed.message + "\r");
+          agentRunning = true;
+          notifyAgentRunning(true);
+        }
+      };
+      window.addEventListener("message", messageHandler);
+      cleanupMessageHandler = () =>
+        window.removeEventListener("message", messageHandler);
+
+      submitPromptRef.current = submitPrompt;
+      const initialRequest = pendingSubmitRequestRef.current;
+      if (initialRequest) submitPrompt(initialRequest);
+      connect(fullWsUrl.toString());
+
+      return () => {
+        disposed = true;
+        connectionId++;
+        if (idleTimer) clearTimeout(idleTimer);
+        disposeTerminal();
+        if (ws) {
+          ws.close();
+          ws = null;
+        }
+        submitPromptRef.current = null;
+      };
+    }
+
+    let cleanup: (() => void) | undefined;
+    void init().then((fn) => {
+      if (disposed) {
+        fn?.();
+        cleanupMessageHandler?.();
+        return;
+      }
+      cleanup = fn;
+    });
+
+    return () => {
+      disposed = true;
+      cleanup?.();
+      cleanupMessageHandler?.();
+    };
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [hideInFrame, inFrame, command, flags, wsUrlProp]);
+
+  useEffect(() => {
+    if (!submitRequest) return;
+    pendingSubmitRequestRef.current = submitRequest;
+    submitPromptRef.current?.(submitRequest);
+  }, [submitRequest?.id, submitRequest?.text]);
+
+  if (hideInFrame && inFrame) {
+    return null;
+  }
+
+  const terminalBackground = theme?.background ?? DEFAULT_THEME.background;
+  const mergedStyle = {
+    ...style,
+    background: terminalBackground,
+    backgroundColor: terminalBackground,
+    "--agent-terminal-background": terminalBackground,
+  };
+
+  return (
+    <div
+      ref={termRef}
+      className={className}
+      style={{
+        width: "100%",
+        height: "100%",
+        padding: "4px 12px",
+        position: "relative",
+        ...mergedStyle,
+      }}
+    >
+      {error && (
+        <div
+          style={{
+            position: "absolute",
+            inset: 0,
+            display: "flex",
+            alignItems: "center",
+            justifyContent: "center",
+            backgroundColor: terminalBackground,
+            color: "#ff7b72",
+            fontSize: "13px",
+            fontFamily: "monospace",
+            padding: "20px",
+            textAlign: "center",
+            zIndex: 1,
+          }}
+        >
+          {error}
+        </div>
+      )}
+    </div>
+  );
+}

package/src/app/terminal/index.ts

@@ -0,0 +1,6 @@
+export {
+  AgentTerminal,
+  type AgentTerminalProps,
+  type AgentTerminalSubmitRequest,
+  formatWebSocketHostname,
+} from "./AgentTerminal.js";

package/src/app/transcription/BuilderTranscriptionCta.spec.tsx

@@ -0,0 +1,59 @@
+// @vitest-environment happy-dom
+
+import React, { act } from "react";
+import { createRoot, type Root } from "react-dom/client";
+import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
+
+const mocks = vi.hoisted(() => ({
+  cancel: vi.fn(),
+  useBuilderConnectFlow: vi.fn(),
+}));
+
+vi.mock("../settings/useBuilderStatus.js", () => ({
+  useBuilderConnectFlow: mocks.useBuilderConnectFlow,
+}));
+vi.mock("../i18n.js", () => ({
+  useT: () => (key: string) => key,
+}));
+
+import { BuilderTranscriptionCta } from "./BuilderTranscriptionCta.js";
+
+describe("BuilderTranscriptionCta while connecting", () => {
+  let container: HTMLDivElement;
+  let root: Root;
+
+  beforeEach(() => {
+    vi.stubGlobal("IS_REACT_ACT_ENVIRONMENT", true);
+    mocks.useBuilderConnectFlow.mockReturnValue({
+      cancel: mocks.cancel,
+      configured: false,
+      connecting: true,
+      envManaged: false,
+      error: null,
+      hasFetchedStatus: true,
+      statusResolved: true,
+    });
+    container = document.createElement("div");
+    document.body.appendChild(container);
+    root = createRoot(container);
+    act(() => root.render(<BuilderTranscriptionCta />));
+  });
+
+  afterEach(() => {
+    act(() => root.unmount());
+    container.remove();
+    vi.clearAllMocks();
+    vi.unstubAllGlobals();
+  });
+
+  it("keeps a localized cancel action available", () => {
+    const button = container.querySelector<HTMLButtonElement>("button");
+    expect(button?.textContent).toBe("common.cancel");
+    act(() => {
+      button?.dispatchEvent(
+        new MouseEvent("click", { bubbles: true, cancelable: true }),
+      );
+    });
+    expect(mocks.cancel).toHaveBeenCalledOnce();
+  });
+});

package/src/app/transcription/BuilderTranscriptionCta.tsx

@@ -0,0 +1,65 @@
+import { useT } from "@agent-native/core/client/i18n";
+import { Button } from "@agent-native/toolkit/ui/button";
+import { IconBolt, IconLoader2 } from "@tabler/icons-react";
+
+import { DeferredBuilderConnectPopover } from "../settings/deferred-builder-connect-popover.js";
+import { useBuilderConnectFlow } from "../settings/useBuilderStatus.js";
+
+export function BuilderTranscriptionCta() {
+  const t = useT();
+  const flow = useBuilderConnectFlow({
+    provisionAccount: true,
+    trackingSource: "builder_transcription_cta",
+    trackingFlow: "transcription",
+  });
+  const configured = flow.statusResolved
+    ? flow.configured || flow.envManaged
+    : null;
+  const statusUnavailable = flow.hasFetchedStatus && !flow.statusResolved;
+
+  if (configured || (configured === null && !statusUnavailable)) return null;
+
+  return (
+    <div className="flex items-center gap-2 rounded-md border border-border/50 bg-muted/30 px-3 py-2 text-xs text-muted-foreground">
+      <IconBolt
+        size={14}
+        className="shrink-0 text-muted-foreground/70"
+        aria-hidden="true"
+      />
+      <span className="flex-1">
+        {flow.connecting
+          ? "Waiting for Builder.io…"
+          : statusUnavailable
+            ? "Builder status unavailable. Try again."
+            : "Connect Builder.io for higher-quality transcription — free credits, no API key needed."}
+      </span>
+      {flow.error && (
+        <span className="text-destructive text-[10px]">{flow.error}</span>
+      )}
+      {flow.connecting ? (
+        <>
+          <IconLoader2 size={12} className="shrink-0 animate-spin" />
+          <Button
+            type="button"
+            variant="ghost"
+            size="sm"
+            className="h-6 shrink-0 px-2 py-1 text-[10px]"
+            onClick={flow.cancel}
+          >
+            {t("common.cancel")}
+          </Button>
+        </>
+      ) : (
+        <DeferredBuilderConnectPopover flow={flow}>
+          <button
+            type="button"
+            disabled={flow.connecting}
+            className="ml-auto shrink-0 inline-flex items-center gap-1 rounded bg-foreground px-2 py-1 text-[10px] font-semibold text-background transition-opacity hover:opacity-90 disabled:cursor-wait disabled:opacity-60"
+          >
+            {statusUnavailable || flow.error ? "Retry" : "Connect"}
+          </button>
+        </DeferredBuilderConnectPopover>
+      )}
+    </div>
+  );
+}

package/src/app/transcription/index.ts

@@ -0,0 +1 @@
+export * from "./BuilderTranscriptionCta.js";

package/src/app-shell/prompt-home.css

@@ -54,6 +54,10 @@
   gap: 1rem;
 }
 
+.agent-context-reference-gallery .agent-template-library-grid {
+  grid-template-columns: repeat(auto-fill, minmax(min(100%, 15rem), 1fr));
+}
+
 .agent-template-library-preview {
   position: relative;
   aspect-ratio: 16 / 9;