@textjs/app 0.0.0-stage → 1.0.2

package/dist/mcp/cli.js

@@ -0,0 +1,177 @@
+/**
+ * `text mcp [dir]` — serve a headless Text.js app to coding agents over MCP
+ * (stdio). stdout carries JSON-RPC only: app `console.*` output and stray
+ * `process.stdout.write` calls are captured into the `logs` tool instead.
+ */
+import { resolve } from "node:path";
+import { txMessage } from "@textjs/core";
+import { captureConsole, LogBuffer } from "./logs.js";
+export const MCP_HELP = `Usage: text mcp [dir] [options]
+
+Serve the app in [dir] to coding agents over the Model Context Protocol (stdio).
+The app runs headless, in-process: same routes, layouts and route handlers.
+
+Options:
+  --path <pathname>   Initial route (default /)
+  --cols <n>          Grid width (default: text.config.ts viewport, else 100)
+  --rows <n>          Grid height (default: text.config.ts viewport, else 32)
+  --theme <name>      Theme preset
+  --no-config         Ignore text.config.ts
+  --verbose           Mirror captured logs to stderr
+  -h, --help          Show this help
+
+Tools: list_routes navigate read_frame press type paste scroll resize
+       inspect_tree find wait_for logs fetch reload
+`;
+export function parseMcpArgs(argv) {
+    const out = { dir: ".", skipConfig: false, verbose: false, help: false, unknown: [] };
+    const positional = [];
+    const num = (v) => {
+        const n = Number(v);
+        return v !== undefined && Number.isFinite(n) && n > 0 ? Math.floor(n) : undefined;
+    };
+    for (let i = 0; i < argv.length; i++) {
+        const a = argv[i];
+        const eq = a.indexOf("=");
+        const flag = a.startsWith("--") && eq > 0 ? a.slice(0, eq) : a;
+        const inline = a.startsWith("--") && eq > 0 ? a.slice(eq + 1) : undefined;
+        const value = () => inline ?? argv[++i];
+        if (flag === "-h" || flag === "--help")
+            out.help = true;
+        else if (flag === "--path")
+            out.path = value();
+        else if (flag === "--cols")
+            out.cols = num(value());
+        else if (flag === "--rows")
+            out.rows = num(value());
+        else if (flag === "--theme")
+            out.theme = value();
+        else if (flag === "--no-config")
+            out.skipConfig = true;
+        else if (flag === "--verbose")
+            out.verbose = true;
+        else if (a.startsWith("-") && a !== "-")
+            out.unknown.push(a);
+        else
+            positional.push(a);
+    }
+    // argv includes the command itself ("mcp") when called from `text`.
+    if (positional[0] === "mcp")
+        positional.shift();
+    if (positional[0])
+        out.dir = positional[0];
+    return out;
+}
+function formatEntry(e) {
+    return `[text mcp] ${e.level}${e.source !== "console" ? ` (${e.source})` : ""}: ${e.message}\n`;
+}
+/** Run the stdio server until stdin closes or a signal arrives. Resolves with the exit code. */
+export async function runMcpCli(argv) {
+    const args = parseMcpArgs(argv);
+    const stderr = (s) => void process.stderr.write(s);
+    if (args.help) {
+        // Only a human asks for help, so stdout is not carrying JSON-RPC yet.
+        process.stdout.write(MCP_HELP);
+        return 0;
+    }
+    if (args.unknown.length > 0) {
+        stderr(`text mcp: unknown option${args.unknown.length > 1 ? "s" : ""} ${args.unknown.join(", ")}. See \`text mcp --help\`.\n`);
+        return 2;
+    }
+    if (typeof process.versions.bun !== "string") {
+        stderr(`${txMessage("TX019", "mcp", "mcp")}\n`);
+        return 1;
+    }
+    // 1. Own stdout before anything can write to it.
+    const realWrite = process.stdout.write.bind(process.stdout);
+    const logs = new LogBuffer();
+    const mirror = args.verbose ? (e) => stderr(formatEntry(e)) : undefined;
+    const capture = captureConsole(logs, mirror);
+    const strayWrite = ((chunk, encodingOrCb, cb) => {
+        const text = typeof chunk === "string" ? chunk : new TextDecoder().decode(chunk);
+        const entry = logs.push("log", "process", [text.replace(/\n$/, "")]);
+        mirror?.(entry);
+        const done = typeof encodingOrCb === "function" ? encodingOrCb : cb;
+        if (typeof done === "function")
+            queueMicrotask(() => done());
+        return true;
+    });
+    process.stdout.write = strayWrite;
+    const transportOut = {
+        write: (chunk) => realWrite(chunk),
+        once: (event, listener) => {
+            process.stdout.once(event, listener);
+            return transportOut;
+        },
+        on: (event, listener) => {
+            process.stdout.on(event, listener);
+            return transportOut;
+        },
+    };
+    const onRejection = (reason) => {
+        const e = logs.push("error", "process", ["Unhandled promise rejection:", reason]);
+        mirror?.(e);
+    };
+    const onException = (error) => {
+        const e = logs.push("error", "process", ["Uncaught exception:", error]);
+        mirror?.(e);
+    };
+    process.on("unhandledRejection", onRejection);
+    process.on("uncaughtException", onException);
+    const [{ StdioServerTransport }, { createTextMcpServer }] = await Promise.all([import("@modelcontextprotocol/sdk/server/stdio.js"), import("./server.js")]);
+    const root = resolve(args.dir);
+    const { server, controller } = createTextMcpServer({
+        root,
+        path: args.path,
+        cols: args.cols,
+        rows: args.rows,
+        theme: args.theme,
+        skipConfig: args.skipConfig,
+        logs,
+        captureConsole: false,
+    });
+    const transport = new StdioServerTransport(process.stdin, transportOut);
+    let resolveExit = () => undefined;
+    const exited = new Promise((r) => {
+        resolveExit = r;
+    });
+    let closing = false;
+    const shutdown = async (code) => {
+        if (closing)
+            return;
+        closing = true;
+        try {
+            await Promise.race([controller.dispose(), new Promise((r) => setTimeout(r, 2000))]);
+            await server.close().catch(() => undefined);
+        }
+        finally {
+            process.off("unhandledRejection", onRejection);
+            process.off("uncaughtException", onException);
+            capture.restore();
+            process.stdout.write = realWrite;
+            resolveExit(code);
+            // App timers or sockets must not keep a disconnected server alive.
+            setTimeout(() => process.exit(code), 500).unref();
+        }
+    };
+    process.stdin.once("end", () => void shutdown(0));
+    process.stdin.once("close", () => void shutdown(0));
+    process.once("SIGINT", () => void shutdown(130));
+    process.once("SIGTERM", () => void shutdown(143));
+    // The client went away mid-write (EPIPE): nothing can be delivered any more.
+    process.stdout.on("error", () => void shutdown(0));
+    await server.connect(transport);
+    // After connect: `Protocol.connect` installs its own transport `onclose`.
+    const onServerClose = server.server.onclose;
+    server.server.onclose = () => {
+        onServerClose?.();
+        void shutdown(0);
+    };
+    stderr(`▼ Text.js MCP server · ${root}\n`);
+    // Load the app in the background; tools wait for it and report load errors.
+    controller.start().catch((error) => {
+        stderr(`[text mcp] failed to start the app: ${error instanceof Error ? error.message : String(error)}\n`);
+    });
+    return exited;
+}
+//# sourceMappingURL=cli.js.map

package/dist/mcp/cli.js.map

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

package/dist/mcp/frame.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Frame extraction for agents: plain text, styled runs and text search, all in
+ * cell coordinates (wide graphemes such as CJK and emoji occupy two columns).
+ */
+import { type CellBuffer, type PackedColor } from "@textjs/core";
+export interface Region {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface StyledRun {
+    /** Column of the first cell. */
+    x: number;
+    /** Width in cells. */
+    width: number;
+    text: string;
+    /** `#rrggbb` (or `#rrggbbaa` when translucent); `null` = terminal default. */
+    fg: string | null;
+    bg: string | null;
+    /** Subset of `bold dim italic underline strikethrough inverse`. */
+    attrs?: string[];
+}
+export interface StyledRow {
+    y: number;
+    runs: StyledRun[];
+}
+export interface TextMatch {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+    /** The full (trimmed) row the match is on. */
+    line: string;
+}
+export declare function colorHex(c: PackedColor): string | null;
+export declare function attrNames(attrs: number): string[];
+/** Clamp `region` to the buffer (the whole buffer when omitted). */
+export declare function clampRegion(buffer: CellBuffer, region?: Partial<Region>): Region;
+/** Plain text of `region`, one line per row (trailing spaces and blank rows trimmed). */
+export declare function frameText(buffer: CellBuffer, region?: Partial<Region>, trim?: boolean): string;
+/**
+ * Run-length encoded styled rows for `region`. Rows that are entirely blank,
+ * default-styled cells are omitted (each row carries its `y`).
+ */
+export declare function styledRows(buffer: CellBuffer, region?: Partial<Region>): StyledRow[];
+export interface FindOptions {
+    /** Treat `query` as a regular expression (JavaScript syntax, no flags but `i`). */
+    regex?: boolean;
+    ignoreCase?: boolean;
+    /** Max matches (default 50). */
+    limit?: number;
+}
+/** Find `query` in the frame, row by row (matches never span rows). */
+export declare function findText(buffer: CellBuffer, query: string, options?: FindOptions): TextMatch[];
+/** Whether `text` appears anywhere in the frame (row by row). */
+export declare function frameContains(buffer: CellBuffer, text: string): boolean;
+//# sourceMappingURL=frame.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"frame.d.ts","sourceRoot":"","sources":["../../src/mcp/frame.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAQL,KAAK,UAAU,EACf,KAAK,WAAW,EACjB,MAAM,cAAc,CAAC;AAEtB,MAAM,WAAW,MAAM;IACrB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,SAAS;IACxB,gCAAgC;IAChC,CAAC,EAAE,MAAM,CAAC;IACV,sBAAsB;IACtB,KAAK,EAAE,MAAM,CAAC;IACd,IAAI,EAAE,MAAM,CAAC;IACb,8EAA8E;IAC9E,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAClB,mEAAmE;IACnE,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;CAClB;AAED,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,IAAI,EAAE,SAAS,EAAE,CAAC;CACnB;AAED,MAAM,WAAW,SAAS;IACxB,CAAC,EAAE,MAAM,CAAC;IACV,CAAC,EAAE,MAAM,CAAC;IACV,KAAK,EAAE,MAAM,CAAC;IACd,MAAM,EAAE,MAAM,CAAC;IACf,8CAA8C;IAC9C,IAAI,EAAE,MAAM,CAAC;CACd;AAaD,wBAAgB,QAAQ,CAAC,CAAC,EAAE,WAAW,GAAG,MAAM,GAAG,IAAI,CAMtD;AAED,wBAAgB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAIjD;AAED,oEAAoE;AACpE,wBAAgB,WAAW,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAMhF;AA2CD,yFAAyF;AACzF,wBAAgB,SAAS,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,EAAE,IAAI,UAAO,GAAG,MAAM,CAS3F;AAED;;;GAGG;AACH,wBAAgB,UAAU,CAAC,MAAM,EAAE,UAAU,EAAE,MAAM,CAAC,EAAE,OAAO,CAAC,MAAM,CAAC,GAAG,SAAS,EAAE,CAgCpF;AAWD,MAAM,WAAW,WAAW;IAC1B,mFAAmF;IACnF,KAAK,CAAC,EAAE,OAAO,CAAC;IAChB,UAAU,CAAC,EAAE,OAAO,CAAC;IACrB,gCAAgC;IAChC,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB;AAED,uEAAuE;AACvE,wBAAgB,QAAQ,CAAC,MAAM,EAAE,UAAU,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,GAAE,WAAgB,GAAG,SAAS,EAAE,CAuBlG;AAED,iEAAiE;AACjE,wBAAgB,aAAa,CAAC,MAAM,EAAE,UAAU,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAGvE"}

package/dist/mcp/frame.js

@@ -0,0 +1,169 @@
+/**
+ * Frame extraction for agents: plain text, styled runs and text search, all in
+ * cell coordinates (wide graphemes such as CJK and emoji occupy two columns).
+ */
+import { ATTR_BOLD, ATTR_DIM, ATTR_INVERSE, ATTR_ITALIC, ATTR_STRIKETHROUGH, ATTR_UNDERLINE, ATTR_WIDE_CONT, } from "@textjs/core";
+const ATTR_NAMES = [
+    [ATTR_BOLD, "bold"],
+    [ATTR_DIM, "dim"],
+    [ATTR_ITALIC, "italic"],
+    [ATTR_UNDERLINE, "underline"],
+    [ATTR_STRIKETHROUGH, "strikethrough"],
+    [ATTR_INVERSE, "inverse"],
+];
+const STYLE_MASK = ATTR_BOLD | ATTR_DIM | ATTR_ITALIC | ATTR_UNDERLINE | ATTR_STRIKETHROUGH | ATTR_INVERSE;
+export function colorHex(c) {
+    if (c === 0)
+        return null;
+    const v = c >>> 0;
+    const rgb = (v >>> 8).toString(16).padStart(6, "0");
+    const a = v & 0xff;
+    return a === 0xff ? `#${rgb}` : `#${rgb}${a.toString(16).padStart(2, "0")}`;
+}
+export function attrNames(attrs) {
+    const out = [];
+    for (const [bit, name] of ATTR_NAMES)
+        if ((attrs & bit) !== 0)
+            out.push(name);
+    return out;
+}
+/** Clamp `region` to the buffer (the whole buffer when omitted). */
+export function clampRegion(buffer, region) {
+    const x = Math.max(0, Math.min(buffer.width, Math.floor(region?.x ?? 0)));
+    const y = Math.max(0, Math.min(buffer.height, Math.floor(region?.y ?? 0)));
+    const width = Math.max(0, Math.min(buffer.width - x, Math.floor(region?.width ?? buffer.width - x)));
+    const height = Math.max(0, Math.min(buffer.height - y, Math.floor(region?.height ?? buffer.height - y)));
+    return { x, y, width, height };
+}
+/**
+ * Display text of a cell: empty and control cells read as a space, and so
+ * does U+00A0 (fields draw their block cursor on a no-break space), so
+ * `find` / `wait_for` match what is visible.
+ */
+function cellText(ch) {
+    return ch === "" || ch === "\u00a0" || ch.charCodeAt(0) < 0x20 ? " " : ch;
+}
+/** A row slice as text plus a string-index → column map. */
+function rowCells(buffer, y, x0, x1) {
+    let text = "";
+    const colsList = [];
+    for (let x = x0; x < x1; x++) {
+        const cell = buffer.getCell(x, y);
+        if (!cell)
+            break;
+        if ((cell.attrs & ATTR_WIDE_CONT) !== 0) {
+            // A wide grapheme cut by the region's left edge renders as a blank.
+            if (x === x0) {
+                colsList.push(x);
+                text += " ";
+            }
+            continue;
+        }
+        // The lead half of a wide glyph cut by the right edge must occupy one
+        // blank column (the symmetric case of a continuation at the left edge).
+        const clipped = x === x1 - 1 && ((buffer.getCell(x + 1, y)?.attrs ?? 0) & ATTR_WIDE_CONT) !== 0;
+        const ch = clipped ? " " : cellText(cell.char);
+        for (let i = 0; i < ch.length; i++)
+            colsList.push(x);
+        text += ch;
+    }
+    colsList.push(x1);
+    return { text, cols: Int32Array.from(colsList) };
+}
+/** Plain text of `region`, one line per row (trailing spaces and blank rows trimmed). */
+export function frameText(buffer, region, trim = true) {
+    const r = clampRegion(buffer, region);
+    const lines = [];
+    for (let y = r.y; y < r.y + r.height; y++) {
+        const text = rowCells(buffer, y, r.x, r.x + r.width).text;
+        lines.push(trim ? text.trimEnd() : text);
+    }
+    if (trim)
+        while (lines.length > 0 && lines[lines.length - 1] === "")
+            lines.pop();
+    return lines.join("\n");
+}
+/**
+ * Run-length encoded styled rows for `region`. Rows that are entirely blank,
+ * default-styled cells are omitted (each row carries its `y`).
+ */
+export function styledRows(buffer, region) {
+    const r = clampRegion(buffer, region);
+    const rows = [];
+    for (let y = r.y; y < r.y + r.height; y++) {
+        const runs = [];
+        let cur = null;
+        for (let x = r.x; x < r.x + r.width; x++) {
+            const cell = buffer.getCell(x, y);
+            if (!cell)
+                break;
+            const attrs = cell.attrs & STYLE_MASK;
+            const key = `${cell.fg}|${cell.bg}|${attrs}`;
+            const wideCont = (cell.attrs & ATTR_WIDE_CONT) !== 0;
+            // A wide grapheme's second cell extends its run; cut by the region's left edge, it reads as a blank.
+            if (wideCont && cur) {
+                cur.width++;
+                continue;
+            }
+            const clipped = x === r.x + r.width - 1 && ((buffer.getCell(x + 1, y)?.attrs ?? 0) & ATTR_WIDE_CONT) !== 0;
+            const ch = wideCont || clipped ? " " : cellText(cell.char);
+            if (cur && cur.key === key) {
+                cur.text += ch;
+                cur.width++;
+                continue;
+            }
+            if (cur)
+                runs.push(stripKey(cur));
+            cur = { key, x, width: 1, text: ch, fg: colorHex(cell.fg), bg: colorHex(cell.bg), ...(attrs ? { attrs: attrNames(attrs) } : {}) };
+        }
+        if (cur)
+            runs.push(stripKey(cur));
+        if (runs.every(isBlankRun))
+            continue;
+        rows.push({ y, runs });
+    }
+    return rows;
+}
+function isBlankRun(run) {
+    return run.bg === null && run.attrs === undefined && run.text.trim() === "";
+}
+function stripKey(run) {
+    const { key: _key, ...rest } = run;
+    return rest;
+}
+/** Find `query` in the frame, row by row (matches never span rows). */
+export function findText(buffer, query, options = {}) {
+    const limit = options.limit ?? 50;
+    const out = [];
+    if (query === "")
+        return out;
+    let re;
+    if (options.regex)
+        re = new RegExp(query, options.ignoreCase ? "gi" : "g");
+    else
+        re = new RegExp(query.replace(/[.*+?^${}()|[\]\\]/g, "\\$&"), options.ignoreCase ? "gi" : "g");
+    for (let y = 0; y < buffer.height && out.length < limit; y++) {
+        const row = rowCells(buffer, y, 0, buffer.width);
+        re.lastIndex = 0;
+        for (let m = re.exec(row.text); m !== null && out.length < limit; m = re.exec(row.text)) {
+            if (m[0] === "") {
+                re.lastIndex++;
+                continue;
+            }
+            const x = row.cols[m.index];
+            const end = row.cols[m.index + m[0].length];
+            // A match ending inside a wide grapheme extends to cover it.
+            const width = Math.max(1, end - x);
+            out.push({ x, y, width, height: 1, line: row.text.trimEnd() });
+        }
+    }
+    return out;
+}
+/** Whether `text` appears anywhere in the frame (row by row). */
+export function frameContains(buffer, text) {
+    for (let y = 0; y < buffer.height; y++)
+        if (rowCells(buffer, y, 0, buffer.width).text.includes(text))
+            return true;
+    return false;
+}
+//# sourceMappingURL=frame.js.map

package/dist/mcp/frame.js.map

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

package/dist/mcp/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * `@textjs/app/mcp` — drive Text.js apps from coding agents.
+ *
+ * `text mcp [dir]` serves these tools over stdio; `createTextMcpServer()`
+ * embeds the same server in another process (any MCP transport), and
+ * `HeadlessSession` is the transport-free core.
+ */
+export { createTextMcpServer, formatFrame, SessionController, type TextMcpServerOptions } from "./server.js";
+export { HeadlessSession, SessionError, purgeModuleCache, type FetchResult, type FocusSummary, type FrameSnapshot, type SessionOptions, type SettleResult } from "./session.js";
+export { findText, frameText, styledRows, type Region, type StyledRow, type StyledRun, type TextMatch } from "./frame.js";
+export { FiberProbe, formatTree, inspect, type Bounds, type FocusableInfo, type InspectOptions, type InspectResult, type TreeNode } from "./inspect.js";
+export { parseKeyInput, textToKeyEvents, KeySpecError, MAX_KEYS_PER_CALL } from "./keys.js";
+export { captureConsole, LogBuffer, type LogEntry, type LogLevel } from "./logs.js";
+export { MCP_HELP, parseMcpArgs, runMcpCli } from "./cli.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,iBAAiB,EAAE,KAAK,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAC1G,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,EAAE,KAAK,WAAW,EAAE,KAAK,YAAY,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,YAAY,EAAE,MAAM,WAAW,CAAC;AAC7K,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAAE,KAAK,MAAM,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,KAAK,SAAS,EAAE,MAAM,SAAS,CAAC;AACvH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAAE,KAAK,MAAM,EAAE,KAAK,aAAa,EAAE,KAAK,cAAc,EAAE,KAAK,aAAa,EAAE,KAAK,QAAQ,EAAE,MAAM,WAAW,CAAC;AACrJ,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AACzF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAE,KAAK,QAAQ,EAAE,KAAK,QAAQ,EAAE,MAAM,QAAQ,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC"}

package/dist/mcp/index.js

@@ -0,0 +1,15 @@
+/**
+ * `@textjs/app/mcp` — drive Text.js apps from coding agents.
+ *
+ * `text mcp [dir]` serves these tools over stdio; `createTextMcpServer()`
+ * embeds the same server in another process (any MCP transport), and
+ * `HeadlessSession` is the transport-free core.
+ */
+export { createTextMcpServer, formatFrame, SessionController } from "./server.js";
+export { HeadlessSession, SessionError, purgeModuleCache } from "./session.js";
+export { findText, frameText, styledRows } from "./frame.js";
+export { FiberProbe, formatTree, inspect } from "./inspect.js";
+export { parseKeyInput, textToKeyEvents, KeySpecError, MAX_KEYS_PER_CALL } from "./keys.js";
+export { captureConsole, LogBuffer } from "./logs.js";
+export { MCP_HELP, parseMcpArgs, runMcpCli } from "./cli.js";
+//# sourceMappingURL=index.js.map

package/dist/mcp/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/mcp/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,OAAO,EAAE,mBAAmB,EAAE,WAAW,EAAE,iBAAiB,EAA6B,MAAM,UAAU,CAAC;AAC1G,OAAO,EAAE,eAAe,EAAE,YAAY,EAAE,gBAAgB,EAAmG,MAAM,WAAW,CAAC;AAC7K,OAAO,EAAE,QAAQ,EAAE,SAAS,EAAE,UAAU,EAA+D,MAAM,SAAS,CAAC;AACvH,OAAO,EAAE,UAAU,EAAE,UAAU,EAAE,OAAO,EAA2F,MAAM,WAAW,CAAC;AACrJ,OAAO,EAAE,aAAa,EAAE,eAAe,EAAE,YAAY,EAAE,iBAAiB,EAAE,MAAM,QAAQ,CAAC;AACzF,OAAO,EAAE,cAAc,EAAE,SAAS,EAAgC,MAAM,QAAQ,CAAC;AACjF,OAAO,EAAE,QAAQ,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,OAAO,CAAC"}

package/dist/mcp/inspect.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Component + scene tree inspection for `text mcp`.
+ *
+ * The React tree is read from fibers: `<FiberProbe>` (a class component
+ * mounted around the app) exposes its fiber via `_reactInternals`, which React
+ * sets on every class instance in development and production builds alike.
+ * Host fibers (`tx-box` / `tx-text` / raw text) point at their `SceneNode`
+ * (`stateNode`), whose `screenRect` from the last paint gives cell bounds.
+ */
+import { Component, type ReactNode } from "react";
+import type { SceneNode } from "@textjs/core";
+import type { FocusManager } from "@textjs/react";
+export declare class FiberProbe extends Component<{
+    children?: ReactNode;
+}> {
+    render(): ReactNode;
+}
+export interface Bounds {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+export interface TreeNode {
+    /**
+     * `component` (React function/class), `box` / `text` (host scene nodes),
+     * `suspense`, or `portal` (content `<Modal>` / `<Dialog>` / toasts render
+     * into the root layer; its bounds are not part of the parent's).
+     */
+    kind: "component" | "box" | "text" | "suspense" | "portal";
+    name: string;
+    key?: string;
+    /** Screen bounds from the last painted frame (union of painted host descendants for components). */
+    bounds?: Bounds;
+    /** Text content (text hosts; truncated). */
+    text?: string;
+    /** Focus id owned by this component (`useFocus`), when it can be attributed. */
+    focusId?: string;
+    focused?: boolean;
+    /** `wireframeLabel` / `title` of a box host, when set. */
+    label?: string;
+    children?: TreeNode[];
+}
+export interface FocusableInfo {
+    id: string;
+    focused: boolean;
+    /** Included in Tab order and not blocked by a focus trap (e.g. an open `<Modal>`). */
+    tabbable: boolean;
+    component?: string;
+    bounds?: Bounds;
+}
+export interface InspectOptions {
+    /** Include host `box` / `text` nodes (default `true`). */
+    hosts?: boolean;
+    /** Levels of the returned tree (default 40), counted from the top level, or from each match with `component`. */
+    maxDepth?: number;
+    /** Only return subtrees rooted at components whose name matches (case-insensitive substring). */
+    component?: string;
+    /** Hide components that render nothing visible (default `true`). */
+    hideEmpty?: boolean;
+}
+export interface InspectResult {
+    tree: TreeNode | null;
+    focusables: FocusableInfo[];
+    activeFocusId: string | null;
+}
+/**
+ * Walk the React tree under `probe`. Components are attributed to the focus id
+ * they registered with `useFocus()` (its `FOCUS_OWNER` hook-state marker).
+ */
+export declare function inspect(probe: FiberProbe | null, focus: FocusManager, options?: InspectOptions): InspectResult;
+/** Render a tree as indented text: `Name  [x,y w×h]  "text"  focus=id`. */
+export declare function formatTree(node: TreeNode, indent?: string): string;
+export interface SceneGrid {
+    /** The console root's scene node (`ConsoleRoot.rootNode`). */
+    root: SceneNode;
+    cols: number;
+    rows: number;
+}
+export interface HitResult {
+    /** Nearest component above the topmost painted host at the cell. */
+    component: string | null;
+    /** Component names from the app root down to `component`. */
+    path: string[];
+}
+/**
+ * Hit-tester for cells: the topmost painted host scene node at `(x, y)` in
+ * paint order (overflow clipping, scroll offsets, absolute `zIndex` layers
+ * and portals such as `<Modal>`), attributed to its component chain.
+ * Ownership is computed once per tester.
+ */
+export declare function createHitTester(probe: FiberProbe | null, grid: SceneGrid): (x: number, y: number) => HitResult;
+/** {@link createHitTester} for a single cell. */
+export declare function hitTest(probe: FiberProbe | null, grid: SceneGrid, x: number, y: number): HitResult;
+//# sourceMappingURL=inspect.d.ts.map

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

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