@textjs/app 0.0.0-stage → 1.0.2

package/dist/mcp/session.d.ts

@@ -0,0 +1,230 @@
+/**
+ * A headless Text.js app session for `text mcp`: the `app/` directory mounted
+ * in-process (same route manifest and in-process route handlers as `text run`,
+ * memory history), rendered into an offscreen cell grid and driven with keys.
+ *
+ * Frame pacing is deterministic for agents: every input waits for the app to
+ * go idle — no scheduled frame, no in-flight `fetch`, and no commit or frame
+ * for `quietMs` — before the frame is read.
+ */
+import { type ConsoleRoot, type ThemeName } from "@textjs/react";
+import { type FlatRoute } from "../routing.js";
+import { type ApiRoute } from "../server/scan.js";
+import { type Region, type StyledRow } from "./frame.js";
+import { FiberProbe, type Bounds, type InspectOptions, type InspectResult, type SceneGrid } from "./inspect.js";
+import { LogBuffer } from "./logs.js";
+export interface SessionOptions {
+    /** Project root (the directory containing `app/`). */
+    root: string;
+    /** Initial pathname (default `/`). */
+    path?: string;
+    /** Grid size (default: `text.config.ts` `viewport`, else 100×32). */
+    cols?: number;
+    rows?: number;
+    theme?: ThemeName;
+    /** Skip `text.config.ts`. */
+    skipConfig?: boolean;
+    /** Shared log buffer (console capture writes into the same buffer). */
+    logs?: LogBuffer;
+    /** Origin same-origin `fetch()` paths resolve against (default `http://localhost:3000`). */
+    origin?: string;
+    /** Quiet period that counts as idle (default 50ms). */
+    quietMs?: number;
+}
+export interface SettleResult {
+    idle: boolean;
+    waitedMs: number;
+}
+export interface FocusSummary {
+    id: string;
+    component?: string;
+    bounds?: Bounds;
+}
+export interface FrameSnapshot {
+    text: string;
+    cols: number;
+    rows: number;
+    /** Current location (`pathname + search + hash`). */
+    href: string;
+    /** Matched route pattern (`/deployments/[id]`, or `/_not-found`). */
+    route: string;
+    title?: string;
+    /** Count of distinct frames painted since the session started. */
+    frame: number;
+    idle: boolean;
+    focus: FocusSummary | null;
+    /** Block-cursor position inside the focused component, when one is visible. */
+    cursor: {
+        x: number;
+        y: number;
+    } | null;
+    /** Errors logged since the previous frame read (see the `logs` tool). */
+    newErrors: number;
+    /** Set when the app is not mounted (it called `exit()`, crashed, or failed to load). */
+    status: "running" | "exited" | "crashed" | "failed";
+    styles?: StyledRow[];
+    /** Effective (clamped) rectangle for region reads. */
+    region?: Region;
+}
+export interface FetchResult {
+    status: number;
+    statusText: string;
+    headers: Record<string, string>;
+    body: string;
+    /** Body was cut at `maxBytes`, or an event stream was cut after `streamMs`. */
+    truncated: boolean;
+    /** The response was still streaming when reading stopped (event streams). */
+    streaming?: boolean;
+    /** Matched `app/**\/route.ts` pattern. */
+    route: string | null;
+}
+/** A tool-facing error with an optional `TX###` code. */
+export declare class SessionError extends Error {
+    readonly code: string | undefined;
+    constructor(message: string, code?: string);
+}
+export declare class HeadlessSession {
+    readonly logs: LogBuffer;
+    readonly rootDir: string;
+    private readonly options;
+    private scan;
+    private manifest;
+    private appRoot;
+    private scheduler;
+    private probe;
+    private readonly history;
+    private theme;
+    private cols;
+    private rows;
+    private resized;
+    private generation;
+    private frameSeq;
+    private lastActivity;
+    /** In-flight `fetch` calls per mount generation (a stale app's hung request never blocks idleness). */
+    private readonly inflight;
+    private errorCursor;
+    /** Normalized `options.origin` (no trailing slash). */
+    private readonly origin;
+    private status;
+    private loadError;
+    private disposed;
+    /** Async Server Components' promises (pending ones keep the session busy). */
+    private readonly serverCache;
+    readonly quietMs: number;
+    private constructor();
+    /** Load `text.config.ts`, import every route module and mount the app. */
+    static start(options: SessionOptions): Promise<HeadlessSession>;
+    private touch;
+    private loadConfig;
+    private trackFetch;
+    /**
+     * The app's `fetch`: same-origin URLs (`"/api/health"`,
+     * `"http://localhost:3000/api/x"`) run `app/**\/route.ts` handlers in-process
+     * exactly like `text dev`; everything else goes to the network.
+     */
+    handleFetch(input: RequestInfo | URL, init?: RequestInit): Promise<Response>;
+    private recordError;
+    private mount;
+    private unmountApp;
+    private requireRoot;
+    /** Throw a tool error unless the app is mounted and running (not exited, crashed or failed to load). */
+    assertRunning(): void;
+    /** Whether the app is idle right now (see the module comment). */
+    isIdle(quietMs?: number): boolean;
+    /**
+     * Wait until the app is idle or `timeout` elapses. On timeout (a spinner or
+     * live chart that never stops), the pending frame is flushed so reads still
+     * see the latest committed tree.
+     */
+    settle(options?: {
+        quietMs?: number;
+        timeout?: number;
+        signal?: AbortSignal;
+    }): Promise<SettleResult>;
+    /**
+     * Send events in order, letting each one's effects and follow-up commits
+     * land before the next. Stops if the app exits or `signal` aborts (a timed
+     * out tool call must not keep typing into the next call's frame).
+     */
+    private dispatch;
+    press(keys: string | readonly string[], signal?: AbortSignal): Promise<number>;
+    type(text: string, signal?: AbortSignal): Promise<number>;
+    paste(text: string, signal?: AbortSignal): Promise<void>;
+    /**
+     * Mouse-wheel scroll by `rows` (positive scrolls down) and `cols`, sent in
+     * one-row steps like a wheel. Wheel input is not positional: it reaches the
+     * focused `<ScrollBox>` first, else every wheel-enabled one.
+     */
+    scroll(rows: number, cols?: number, signal?: AbortSignal): Promise<number>;
+    resize(cols: number, rows: number): {
+        cols: number;
+        rows: number;
+    };
+    navigate(target: {
+        path: string;
+        replace?: boolean;
+    } | "back" | "forward"): void;
+    get href(): string;
+    routes(): {
+        pages: FlatRoute[];
+        api: ApiRoute[];
+        current: string;
+    };
+    /** Read the current frame. Errors logged since the previous read are counted in `newErrors`. */
+    frame(options?: {
+        styles?: boolean;
+        region?: Partial<Region>;
+        trim?: boolean; /** Don't reset the `newErrors` counter. */
+        peek?: boolean;
+    }): FrameSnapshot;
+    contains(text: string): boolean;
+    get buffer(): ConsoleRoot["renderer"]["buffer"] | null;
+    get fiberProbe(): FiberProbe | null;
+    /** The mounted scene and grid size, for paint-order hit testing. */
+    get sceneGrid(): SceneGrid | null;
+    inspect(options?: InspectOptions): InspectResult;
+    private focusSummary;
+    /**
+     * Call an `app/**\/route.ts` handler in-process. The body is read up to
+     * `maxBytes` (then cancelled); event streams are read for `streamMs` and
+     * cancelled, so an SSE route returns its first events instead of hanging.
+     */
+    request(path: string, init?: {
+        method?: string;
+        headers?: Record<string, string>;
+        body?: string;
+        maxBytes?: number;
+        streamMs?: number;
+    }, signal?: AbortSignal): Promise<FetchResult>;
+    /**
+     * Re-import the app after file changes: unmount, purge every module under
+     * the project root from the module cache, re-scan `app/`, re-import and
+     * remount at the current location (history is kept).
+     */
+    reload(): Promise<{
+        purged: number;
+    }>;
+    dispose(): Promise<void>;
+}
+/**
+ * Delete every cached module under `root` (except dependencies and Text.js
+ * itself) so the next `import()` re-evaluates it. Bun's `require.cache`
+ * covers ES modules too.
+ */
+export declare function purgeModuleCache(root: string): number;
+/**
+ * `raw` as a URL on `origin`, or `null` when it targets anything else.
+ * Paths like `//evil.com` and `/\evil.com` (a backslash is a slash in
+ * special-scheme URLs) are protocol-relative, not same-origin.
+ */
+export declare function sameOriginUrl(raw: string, origin: string): URL | null;
+/**
+ * Read at most `maxBytes` of a response body, for at most `windowMs`, then
+ * cancel it. `open` is set when the body was still streaming.
+ */
+export declare function readBody(response: Response, maxBytes: number, windowMs: number, signal?: AbortSignal): Promise<{
+    bytes: Uint8Array;
+    truncated: boolean;
+    open: boolean;
+}>;
+//# sourceMappingURL=session.d.ts.map

package/dist/mcp/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/mcp/session.ts"],"names":[],"mappings":"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"}