@love-moon/chat-web 0.3.2

package/dist/core/browser.js

@@ -0,0 +1,96 @@
+import { chromium } from "playwright";
+import { BrowserLaunchError } from "./errors.js";
+import { autoInstallDisabled, hasAttemptedAutoInstall, installChromium, isBrowserMissingError, markAutoInstallAttempted, } from "./install-chromium.js";
+import { defaultLogger } from "./logger.js";
+import { createProfileManager } from "./profile-manager.js";
+/**
+ * Launch (or reattach to) a persistent Chromium context for a provider.
+ *
+ * Important: we use `launchPersistentContext`, NOT `browser.newContext`,
+ * because ChatGPT / DeepSeek depend on more than just cookies (see RFC §19.1).
+ *
+ * First-run UX: if Playwright reports that the Chromium binary is not
+ * installed (a very common state under pnpm 10+, which silently blocks
+ * the `playwright` postinstall script), we run
+ * `npx playwright install chromium` once and retry the launch. Disable
+ * via `CHAT_WEB_NO_AUTO_INSTALL=1` (or `noAutoInstall: true` on the call).
+ */
+export async function launchProviderBrowser(provider, options = {}) {
+    const profileManager = options.profileManager ?? createProfileManager();
+    const userDataDir = await profileManager.ensureProfile(provider);
+    const logger = options.logger ?? defaultLogger;
+    const launchArgs = {
+        headless: resolveHeadless(options.headless),
+        viewport: options.viewport ?? { width: 1280, height: 900 },
+        args: [
+            // Hide the obvious "I'm an automated browser" signal that several
+            // chat sites probe via navigator.webdriver. RFC §19.3.
+            "--disable-blink-features=AutomationControlled",
+            ...(options.args ?? []),
+        ],
+        ...resolveBrowserBinary(options),
+    };
+    try {
+        return await launch(userDataDir, launchArgs);
+    }
+    catch (err) {
+        // First-failure recovery path: if Chromium isn't installed, try to
+        // install it once and retry the launch.
+        const shouldAutoInstall = isBrowserMissingError(err) &&
+            !hasAttemptedAutoInstall() &&
+            !(options.noAutoInstall || autoInstallDisabled());
+        if (!shouldAutoInstall) {
+            throw new BrowserLaunchError(provider, `Failed to launch Chromium for "${provider}" at ${userDataDir}: ${err.message}`, err);
+        }
+        markAutoInstallAttempted();
+        logger.warn(`chat-web: Chromium binary not found; attempting one-time install (\`npx playwright install chromium\`).`);
+        try {
+            await installChromium({ logger });
+        }
+        catch (installErr) {
+            throw new BrowserLaunchError(provider, `Auto-install of Chromium failed for "${provider}". Run manually: \`npx playwright install chromium\` (cause: ${installErr.message})`, installErr);
+        }
+        try {
+            return await launch(userDataDir, launchArgs);
+        }
+        catch (retryErr) {
+            throw new BrowserLaunchError(provider, `Failed to launch Chromium for "${provider}" at ${userDataDir} even after auto-install: ${retryErr.message}`, retryErr);
+        }
+    }
+}
+async function launch(userDataDir, launchArgs) {
+    const context = await chromium.launchPersistentContext(userDataDir, launchArgs);
+    const existing = context.pages();
+    const page = existing.length > 0 ? existing[0] : await context.newPage();
+    return { context, page, userDataDir };
+}
+function resolveHeadless(explicit) {
+    if (typeof explicit === "boolean")
+        return explicit;
+    const env = process.env.CHAT_WEB_HEADLESS;
+    if (env === "1" || env === "true")
+        return true;
+    // Default to headed, per RFC §19.3 (better against anti-bot heuristics).
+    return false;
+}
+/**
+ * Decide which Chromium-family binary to launch:
+ *
+ *   - Explicit `options.executablePath` (or env `CHAT_WEB_BROWSER_EXECUTABLE`)
+ *     wins outright.
+ *   - Otherwise `options.channel` (or env `CHAT_WEB_BROWSER_CHANNEL`)
+ *     selects a Playwright "channel" — `"chrome"` for system Google
+ *     Chrome, `"msedge"` for system Edge, etc.
+ *   - Otherwise undefined → Playwright defaults to its bundled
+ *     `chrome-headless-shell` build.
+ */
+function resolveBrowserBinary(options) {
+    const explicitExec = options.executablePath?.trim() || process.env.CHAT_WEB_BROWSER_EXECUTABLE?.trim();
+    if (explicitExec)
+        return { executablePath: explicitExec };
+    const explicitChannel = options.channel?.trim() || process.env.CHAT_WEB_BROWSER_CHANNEL?.trim();
+    if (explicitChannel)
+        return { channel: explicitChannel };
+    return {};
+}
+//# sourceMappingURL=browser.js.map

package/dist/core/browser.js.map

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

package/dist/core/errors.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Typed error classes used across chat-web.
+ *
+ * Each subclass carries a `code` field (machine-friendly) and a `hint`
+ * field (human-friendly next action), so CLI / daemon callers can both
+ * branch on the code and surface a useful remediation step.
+ */
+export type ChatWebErrorCode = "NOT_LOGGED_IN" | "INPUT_NOT_FOUND" | "SEND_BUTTON_NOT_FOUND" | "RESPONSE_TIMEOUT" | "RESPONSE_EXTRACTION" | "PROVIDER_RATE_LIMITED" | "PROVIDER_CAPTCHA" | "PROVIDER_API_KEY_REQUIRED" | "PROVIDER_PERMISSION_DENIED" | "PROVIDER_AUTOMATION_BLOCKED" | "SELECTOR_VERIFICATION" | "UNKNOWN_PROVIDER" | "PROFILE_ERROR" | "BROWSER_LAUNCH_FAILED";
+export declare class ChatWebError extends Error {
+    readonly code: ChatWebErrorCode;
+    readonly hint?: string;
+    readonly provider?: string;
+    constructor(code: ChatWebErrorCode, message: string, options?: {
+        hint?: string;
+        provider?: string;
+        cause?: unknown;
+    });
+}
+export declare class NotLoggedInError extends ChatWebError {
+    constructor(provider: string);
+}
+export declare class InputNotFoundError extends ChatWebError {
+    constructor(provider: string);
+}
+export declare class SendButtonNotFoundError extends ChatWebError {
+    constructor(provider: string);
+}
+export declare class ResponseTimeoutError extends ChatWebError {
+    constructor(provider: string, timeoutMs: number);
+}
+export declare class ResponseExtractionError extends ChatWebError {
+    constructor(provider: string, message?: string);
+}
+export declare class ProviderRateLimitedError extends ChatWebError {
+    constructor(provider: string);
+}
+export declare class ProviderCaptchaError extends ChatWebError {
+    constructor(provider: string);
+}
+export declare class ProviderApiKeyRequiredError extends ChatWebError {
+    constructor(provider: string, detail?: string);
+}
+export declare class ProviderAutomationBlockedError extends ChatWebError {
+    constructor(provider: string, detail?: string);
+}
+export declare class ProviderPermissionDeniedError extends ChatWebError {
+    constructor(provider: string, detail?: string);
+}
+export declare class SelectorVerificationError extends ChatWebError {
+    constructor(provider: string, what: string);
+}
+export declare class UnknownProviderError extends ChatWebError {
+    constructor(provider: string, known: readonly string[]);
+}
+export declare class ProfileError extends ChatWebError {
+    constructor(provider: string, message: string, cause?: unknown);
+}
+export declare class BrowserLaunchError extends ChatWebError {
+    constructor(provider: string, message: string, cause?: unknown);
+}

package/dist/core/errors.js

@@ -0,0 +1,153 @@
+export class ChatWebError extends Error {
+    code;
+    hint;
+    provider;
+    constructor(code, message, options = {}) {
+        super(message);
+        this.name = "ChatWebError";
+        this.code = code;
+        this.hint = options.hint;
+        this.provider = options.provider;
+        if (options.cause !== undefined) {
+            this.cause = options.cause;
+        }
+    }
+}
+export class NotLoggedInError extends ChatWebError {
+    constructor(provider) {
+        super("NOT_LOGGED_IN", `Provider "${provider}" is not logged in.`, {
+            provider,
+            hint: `Run: chat-web login ${provider}`,
+        });
+        this.name = "NotLoggedInError";
+    }
+}
+export class InputNotFoundError extends ChatWebError {
+    constructor(provider) {
+        super("INPUT_NOT_FOUND", `Could not locate the input box for "${provider}".`, {
+            provider,
+            hint: `Run: chat-web doctor ${provider} --snapshot`,
+        });
+        this.name = "InputNotFoundError";
+    }
+}
+export class SendButtonNotFoundError extends ChatWebError {
+    constructor(provider) {
+        super("SEND_BUTTON_NOT_FOUND", `Could not locate the send button for "${provider}".`, {
+            provider,
+            hint: `Run: chat-web doctor ${provider} --snapshot`,
+        });
+        this.name = "SendButtonNotFoundError";
+    }
+}
+export class ResponseTimeoutError extends ChatWebError {
+    constructor(provider, timeoutMs) {
+        super("RESPONSE_TIMEOUT", `Timed out after ${timeoutMs}ms waiting for "${provider}" response.`, {
+            provider,
+            hint: `Try: chat-web ask ${provider} --timeout ${timeoutMs * 2} "..."`,
+        });
+        this.name = "ResponseTimeoutError";
+    }
+}
+export class ResponseExtractionError extends ChatWebError {
+    constructor(provider, message = "Failed to extract assistant message.") {
+        super("RESPONSE_EXTRACTION", message, {
+            provider,
+            hint: `Run: chat-web doctor ${provider} --snapshot`,
+        });
+        this.name = "ResponseExtractionError";
+    }
+}
+export class ProviderRateLimitedError extends ChatWebError {
+    constructor(provider) {
+        super("PROVIDER_RATE_LIMITED", `Provider "${provider}" appears to be rate limiting us.`, {
+            provider,
+            hint: "Slow down request rate, or wait a few minutes before retrying.",
+        });
+        this.name = "ProviderRateLimitedError";
+    }
+}
+export class ProviderCaptchaError extends ChatWebError {
+    constructor(provider) {
+        super("PROVIDER_CAPTCHA", `Provider "${provider}" is requesting human verification.`, {
+            provider,
+            hint: `Run: chat-web login ${provider} and pass the verification flow in the headed browser.`,
+        });
+        this.name = "ProviderCaptchaError";
+    }
+}
+export class ProviderApiKeyRequiredError extends ChatWebError {
+    constructor(provider, detail) {
+        const base = `Provider "${provider}" needs an API key configured in its web console.`;
+        super("PROVIDER_API_KEY_REQUIRED", detail ? `${base} ${detail}` : base, {
+            provider,
+            hint: provider === "gemini"
+                ? "Two common causes: (a) you've hit AI Studio's free-tier daily quota " +
+                    "— wait a day for the quota to reset, OR (b) no API key is configured. " +
+                    "If you need uninterrupted access, open https://aistudio.google.com/app/apikey, " +
+                    "create a key, then in AI Studio click the 'Get API key' / 'No API key selected' " +
+                    "button and select that key."
+                : `Configure an API key for ${provider} in its web console.`,
+        });
+        this.name = "ProviderApiKeyRequiredError";
+    }
+}
+export class ProviderAutomationBlockedError extends ChatWebError {
+    constructor(provider, detail) {
+        const base = `Provider "${provider}" appears to be blocking automated access ` +
+            "(model invocation never started after the input was submitted; the page sits on 'Thinking' indefinitely).";
+        super("PROVIDER_AUTOMATION_BLOCKED", detail ? `${base} ${detail}` : base, {
+            provider,
+            hint: provider === "gemini"
+                ? "Google AI Studio runs an anti-abuse challenge (WAA) before invoking the model. " +
+                    "Headless / scripted browsers routinely fail this challenge silently. " +
+                    "Workarounds: (1) use chat-web's `chatgpt` provider instead — ChatGPT is far more permissive of automation; " +
+                    "(2) call the Gemini API directly with an API key from https://aistudio.google.com/app/apikey (outside chat-web); " +
+                    "(3) try again later — the challenge sometimes passes."
+                : "The provider's anti-bot system is silently blocking model invocation. Try a different provider.",
+        });
+        this.name = "ProviderAutomationBlockedError";
+    }
+}
+export class ProviderPermissionDeniedError extends ChatWebError {
+    constructor(provider, detail) {
+        const base = `Provider "${provider}" denied the request (permission denied).`;
+        super("PROVIDER_PERMISSION_DENIED", detail ? `${base} ${detail}` : base, {
+            provider,
+            hint: "Common causes: missing/invalid API key, model not enabled on the account, region restriction, quota exhausted. Open the provider's web console to inspect.",
+        });
+        this.name = "ProviderPermissionDeniedError";
+    }
+}
+export class SelectorVerificationError extends ChatWebError {
+    constructor(provider, what) {
+        super("SELECTOR_VERIFICATION", `Selector verification failed for "${provider}" while probing ${what}.`, {
+            provider,
+            hint: `Run: chat-web doctor ${provider} --snapshot`,
+        });
+        this.name = "SelectorVerificationError";
+    }
+}
+export class UnknownProviderError extends ChatWebError {
+    constructor(provider, known) {
+        super("UNKNOWN_PROVIDER", `Unknown provider "${provider}". Known providers: ${known.join(", ")}`, { provider, hint: `Use one of: ${known.join(", ")}` });
+        this.name = "UnknownProviderError";
+    }
+}
+export class ProfileError extends ChatWebError {
+    constructor(provider, message, cause) {
+        super("PROFILE_ERROR", message, { provider, cause });
+        this.name = "ProfileError";
+    }
+}
+export class BrowserLaunchError extends ChatWebError {
+    constructor(provider, message, cause) {
+        super("BROWSER_LAUNCH_FAILED", message, {
+            provider,
+            cause,
+            hint: "Check Playwright install: `npx playwright install chromium`",
+        });
+        this.name = "BrowserLaunchError";
+    }
+}
+//# sourceMappingURL=errors.js.map

package/dist/core/errors.js.map

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

package/dist/core/install-chromium.d.ts

@@ -0,0 +1,55 @@
+import { type ChildProcess, type SpawnOptions } from "node:child_process";
+import { type Logger } from "./logger.js";
+/**
+ * Returns true when an error thrown by Playwright's `launchPersistentContext`
+ * / `launch` is the well-known "Chromium binary not installed" condition.
+ *
+ * We match on multiple hint substrings rather than a single regex because
+ * Playwright has historically rephrased this error every couple of
+ * minor releases; missing only the "browsertype.launch" prefix would break
+ * detection on first contact with a new wording.
+ */
+export declare function isBrowserMissingError(err: unknown): boolean;
+/**
+ * Honour `CHAT_WEB_NO_AUTO_INSTALL` / `CHAT_WEB_SKIP_BROWSER_INSTALL` to
+ * disable the auto-install path entirely. Useful in CI / Docker where the
+ * operator wants explicit control over browser provisioning.
+ */
+export declare function autoInstallDisabled(env?: NodeJS.ProcessEnv): boolean;
+export interface InstallChromiumOptions {
+    logger?: Logger;
+    /** Override the command (mostly for tests). Default: "npx". */
+    command?: string;
+    /** Override the args (mostly for tests). Default: ["--yes", "playwright", "install", "chromium"]. */
+    args?: string[];
+    /** Custom spawn function (for tests). Defaults to node:child_process.spawn. */
+    spawnFn?: (command: string, args: readonly string[], options: SpawnOptions) => ChildProcess;
+    /** Override environment passed to the child. Default: process.env. */
+    env?: NodeJS.ProcessEnv;
+    /** Cancel the install. */
+    signal?: AbortSignal;
+    /** Hard cap on the install duration. Default: 5 minutes. */
+    timeoutMs?: number;
+}
+export interface InstallChromiumResult {
+    command: string;
+    args: readonly string[];
+    exitCode: number;
+    durationMs: number;
+    stdoutTail: string;
+    stderrTail: string;
+}
+/**
+ * Runs `npx --yes playwright install chromium` to its conclusion.
+ *
+ * Resolves with the exit info on success (exitCode === 0), rejects with
+ * an `Error` whose message includes the stderr tail otherwise. We don't
+ * stream the binary download to stdout — that's noisy — but we keep the
+ * last ~2KB of each stream so callers can attach useful diagnostics if
+ * the install fails.
+ */
+export declare function installChromium(options?: InstallChromiumOptions): Promise<InstallChromiumResult>;
+export declare function hasAttemptedAutoInstall(): boolean;
+export declare function markAutoInstallAttempted(): void;
+/** Test-only: reset the once-per-process guard. */
+export declare function _resetAutoInstallGuardForTests(): void;

package/dist/core/install-chromium.js

@@ -0,0 +1,156 @@
+import { spawn, } from "node:child_process";
+import { defaultLogger } from "./logger.js";
+/**
+ * Substrings (lower-cased) that identify Playwright's "browser binary is
+ * missing" error. Playwright's exact wording has shifted across versions
+ * but the core sentinels stay stable.
+ */
+const BROWSER_MISSING_HINTS = [
+    "executable doesn't exist",
+    "please run the following command to download new browsers",
+    "browsertype.launch", // every variant starts with this when the binary is missing
+    "npx playwright install",
+];
+/**
+ * Returns true when an error thrown by Playwright's `launchPersistentContext`
+ * / `launch` is the well-known "Chromium binary not installed" condition.
+ *
+ * We match on multiple hint substrings rather than a single regex because
+ * Playwright has historically rephrased this error every couple of
+ * minor releases; missing only the "browsertype.launch" prefix would break
+ * detection on first contact with a new wording.
+ */
+export function isBrowserMissingError(err) {
+    const msg = String(err?.message ?? "").toLowerCase();
+    if (!msg)
+        return false;
+    return BROWSER_MISSING_HINTS.some((hint) => msg.includes(hint));
+}
+/**
+ * Honour `CHAT_WEB_NO_AUTO_INSTALL` / `CHAT_WEB_SKIP_BROWSER_INSTALL` to
+ * disable the auto-install path entirely. Useful in CI / Docker where the
+ * operator wants explicit control over browser provisioning.
+ */
+export function autoInstallDisabled(env = process.env) {
+    for (const key of ["CHAT_WEB_NO_AUTO_INSTALL", "CHAT_WEB_SKIP_BROWSER_INSTALL"]) {
+        const v = env[key];
+        if (v === "1" || v === "true" || v === "yes")
+            return true;
+    }
+    return false;
+}
+/**
+ * Runs `npx --yes playwright install chromium` to its conclusion.
+ *
+ * Resolves with the exit info on success (exitCode === 0), rejects with
+ * an `Error` whose message includes the stderr tail otherwise. We don't
+ * stream the binary download to stdout — that's noisy — but we keep the
+ * last ~2KB of each stream so callers can attach useful diagnostics if
+ * the install fails.
+ */
+export function installChromium(options = {}) {
+    const command = options.command ?? "npx";
+    const args = options.args ?? ["--yes", "playwright", "install", "chromium"];
+    const spawnFn = options.spawnFn ?? spawn;
+    const env = options.env ?? process.env;
+    const logger = options.logger ?? defaultLogger;
+    const timeoutMs = options.timeoutMs ?? 5 * 60 * 1000;
+    const start = Date.now();
+    logger.info(`chat-web: installing Chromium via \`${command} ${args.join(" ")}\` (first-run only) …`);
+    return new Promise((resolve, reject) => {
+        let settled = false;
+        let stdoutTail = "";
+        let stderrTail = "";
+        const child = spawnFn(command, args, {
+            stdio: ["ignore", "pipe", "pipe"],
+            env,
+        });
+        const onAbort = () => {
+            if (settled)
+                return;
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                // best effort
+            }
+        };
+        options.signal?.addEventListener("abort", onAbort);
+        const timeoutTimer = setTimeout(() => {
+            if (settled)
+                return;
+            try {
+                child.kill("SIGTERM");
+            }
+            catch {
+                // best effort
+            }
+            finalize(new Error(`chat-web: Chromium install timed out after ${timeoutMs}ms. Run manually: \`${command} ${args.join(" ")}\``));
+        }, timeoutMs);
+        if (typeof timeoutTimer.unref === "function")
+            timeoutTimer.unref();
+        const appendTail = (current, chunk) => {
+            const combined = current + chunk;
+            return combined.length > 2048 ? combined.slice(-2048) : combined;
+        };
+        child.stdout?.on("data", (chunk) => {
+            const s = chunk.toString("utf8");
+            stdoutTail = appendTail(stdoutTail, s);
+            // Surface progress lines at debug level — full output is noisy.
+            logger.debug(s.replace(/\n+$/, ""));
+        });
+        child.stderr?.on("data", (chunk) => {
+            const s = chunk.toString("utf8");
+            stderrTail = appendTail(stderrTail, s);
+            logger.debug(s.replace(/\n+$/, ""));
+        });
+        child.on("error", (err) => finalize(err));
+        child.on("exit", (code, signal) => {
+            if (code === 0) {
+                finalize(null);
+            }
+            else {
+                const reason = code !== null ? `exit code ${code}` : `signal ${signal}`;
+                finalize(new Error(`chat-web: \`${command} ${args.join(" ")}\` failed (${reason}). Last stderr:\n${stderrTail.trim() || "(empty)"}`));
+            }
+        });
+        function finalize(err) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timeoutTimer);
+            options.signal?.removeEventListener("abort", onAbort);
+            if (err) {
+                reject(err);
+                return;
+            }
+            const durationMs = Date.now() - start;
+            logger.info(`chat-web: Chromium install finished in ${Math.round(durationMs / 1000)}s.`);
+            resolve({
+                command,
+                args,
+                exitCode: 0,
+                durationMs,
+                stdoutTail,
+                stderrTail,
+            });
+        }
+    });
+}
+/**
+ * Module-private flag so we attempt auto-install at most once per process.
+ * Subsequent failures fall through to the original BrowserLaunchError so
+ * we don't loop on a genuinely broken environment.
+ */
+let attempted = false;
+export function hasAttemptedAutoInstall() {
+    return attempted;
+}
+export function markAutoInstallAttempted() {
+    attempted = true;
+}
+/** Test-only: reset the once-per-process guard. */
+export function _resetAutoInstallGuardForTests() {
+    attempted = false;
+}
+//# sourceMappingURL=install-chromium.js.map

package/dist/core/install-chromium.js.map

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

package/dist/core/keyboard.d.ts

@@ -0,0 +1,39 @@
+import type { Page } from "playwright";
+/**
+ * A single instruction in the typing plan: either type literal text, or
+ * press a key sequence. Exposed separately from the executor so we can
+ * unit-test the *plan* without a real Playwright Page.
+ */
+export type TypingAction = {
+    type: "type";
+    text: string;
+} | {
+    type: "press";
+    key: string;
+};
+/**
+ * Plan how to type a (potentially multi-line) string into a chat composer.
+ *
+ * Why this exists:
+ *   ChatGPT's ProseMirror and Google AI Studio's Angular textarea both
+ *   bind `Enter` to "submit prompt" and `Shift+Enter` to "soft line
+ *   break". `page.keyboard.type(text)` literally emits an `Enter` key
+ *   event for every `\n` in `text`, which causes a multi-line prompt to
+ *   be submitted line-by-line — exactly the bug we saw on the ATLAS
+ *   arXiv prompt (task 09b34cf4-…), where one logical message landed on
+ *   the assistant as 5 fragments.
+ *
+ * The fix: split the text on newlines, type each segment as literal
+ * characters, and emit `Shift+Enter` between segments. The composer ends
+ * up with the same visual content but is never prematurely submitted.
+ */
+export declare function planMultilineTyping(text: string): TypingAction[];
+/**
+ * Execute a typing plan against a Playwright Page.
+ *
+ * Kept as a thin wrapper over `planMultilineTyping` so the interesting
+ * logic stays in the pure function. Adapters call this from
+ * `sendMessage`; they MUST NOT fall back to `page.keyboard.type(message)`
+ * directly on user-supplied prompts.
+ */
+export declare function typeMultiline(page: Page, text: string): Promise<void>;

package/dist/core/keyboard.js

@@ -0,0 +1,54 @@
+/**
+ * Plan how to type a (potentially multi-line) string into a chat composer.
+ *
+ * Why this exists:
+ *   ChatGPT's ProseMirror and Google AI Studio's Angular textarea both
+ *   bind `Enter` to "submit prompt" and `Shift+Enter` to "soft line
+ *   break". `page.keyboard.type(text)` literally emits an `Enter` key
+ *   event for every `\n` in `text`, which causes a multi-line prompt to
+ *   be submitted line-by-line — exactly the bug we saw on the ATLAS
+ *   arXiv prompt (task 09b34cf4-…), where one logical message landed on
+ *   the assistant as 5 fragments.
+ *
+ * The fix: split the text on newlines, type each segment as literal
+ * characters, and emit `Shift+Enter` between segments. The composer ends
+ * up with the same visual content but is never prematurely submitted.
+ */
+export function planMultilineTyping(text) {
+    if (!text)
+        return [];
+    // Normalise line endings so \r\n and \r both collapse to \n splitting.
+    const normalised = text.replace(/\r\n?/g, "\n");
+    const segments = normalised.split("\n");
+    const actions = [];
+    for (let i = 0; i < segments.length; i++) {
+        const segment = segments[i];
+        if (segment) {
+            actions.push({ type: "type", text: segment });
+        }
+        if (i < segments.length - 1) {
+            actions.push({ type: "press", key: "Shift+Enter" });
+        }
+    }
+    return actions;
+}
+/**
+ * Execute a typing plan against a Playwright Page.
+ *
+ * Kept as a thin wrapper over `planMultilineTyping` so the interesting
+ * logic stays in the pure function. Adapters call this from
+ * `sendMessage`; they MUST NOT fall back to `page.keyboard.type(message)`
+ * directly on user-supplied prompts.
+ */
+export async function typeMultiline(page, text) {
+    const actions = planMultilineTyping(text);
+    for (const action of actions) {
+        if (action.type === "type") {
+            await page.keyboard.type(action.text);
+        }
+        else {
+            await page.keyboard.press(action.key);
+        }
+    }
+}
+//# sourceMappingURL=keyboard.js.map

package/dist/core/keyboard.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"keyboard.js","sourceRoot":"","sources":["../../src/core/keyboard.ts"],"names":[],"mappings":"AAWA;;;;;;;;;;;;;;;GAeG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,CAAC,IAAI;QAAE,OAAO,EAAE,CAAC;IACrB,uEAAuE;IACvE,MAAM,UAAU,GAAG,IAAI,CAAC,OAAO,CAAC,QAAQ,EAAE,IAAI,CAAC,CAAC;IAChD,MAAM,QAAQ,GAAG,UAAU,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IACxC,MAAM,OAAO,GAAmB,EAAE,CAAC;IACnC,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,QAAQ,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACzC,MAAM,OAAO,GAAG,QAAQ,CAAC,CAAC,CAAE,CAAC;QAC7B,IAAI,OAAO,EAAE,CAAC;YACZ,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,CAAC,CAAC;QAChD,CAAC;QACD,IAAI,CAAC,GAAG,QAAQ,CAAC,MAAM,GAAG,CAAC,EAAE,CAAC;YAC5B,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,OAAO,EAAE,GAAG,EAAE,aAAa,EAAE,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED;;;;;;;GAOG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CAAC,IAAU,EAAE,IAAY;IAC1D,MAAM,OAAO,GAAG,mBAAmB,CAAC,IAAI,CAAC,CAAC;IAC1C,KAAK,MAAM,MAAM,IAAI,OAAO,EAAE,CAAC;QAC7B,IAAI,MAAM,CAAC,IAAI,KAAK,MAAM,EAAE,CAAC;YAC3B,MAAM,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC;QACxC,CAAC;aAAM,CAAC;YACN,MAAM,IAAI,CAAC,QAAQ,CAAC,KAAK,CAAC,MAAM,CAAC,GAAG,CAAC,CAAC;QACxC,CAAC;IACH,CAAC;AACH,CAAC"}