pw-repl 0.1.0

package/lib/help.js

@@ -0,0 +1,210 @@
+// Three levels: `help` (what this is + topics), `help <topic>` (one line per
+// command), `help <command>` (usage and caveats). Keep each level short enough
+// that a reader only goes deeper when they need to. Help describes what the
+// tool does; instructions for agents belong in skill/SKILL.md.
+
+const OVERVIEW = `playwright-repl drives Chromium over CDP. Commands act on the selected tab (\`tab\` shows which).
+The browser may be a shared session, with other people's tabs open in it.
+
+Common tasks:
+  where am I?                       tab, info
+  what is on the page?              snapshot, screenshot
+  do something on it                click, fill, press
+  what did the page request?        requests, then body <#> for what one got back
+  console messages and errors       console
+  show an agent what I do           watch on, click around, then watch
+  see each step as I click          watch on --live
+  requests and console together     capture on, then capture off
+  break the backend on purpose      route <glob> <status> <json>, network off
+  clean up                          modes off
+
+Modes (watch, capture, route, network off) stay on until turned off; the prompt shows the selected tab's:
+(watch routes:1) pw>. tab, watch, capture, route, network and modes on their own show their state and
+what you can run next.
+
+Topics (help <topic>):
+  tabs      open, select, close, navigate        network   requests, bodies, console, fakes, network off
+  interact  click, fill, type, press, select     devtools  eval, CDP commands, cookie and storage names
+  inspect   snapshot, watch, text, screenshots   session   modes, markers, server, quitting
+
+help <command> for usage and caveats (e.g. help route); help --all for everything.`;
+
+const TOPICS = {
+  tabs: {
+    intro: 'The REPL selects tab [0] when it starts; tab on its own lists them all. After tab close, see help tab.',
+    commands: ['tab', 'goto', 'back', 'forward', 'reload', 'info'],
+  },
+  interact: {
+    intro: 'Selectors are Playwright selectors (CSS, text=..., role=...). Commands use the first match.',
+    commands: ['click', 'dblclick', 'hover', 'fill', 'type', 'press', 'select', 'check', 'uncheck'],
+  },
+  inspect: {
+    intro: 'Output is capped; put --all right after the command for everything (e.g. text --all body).',
+    commands: ['snapshot', 'watch', 'text', 'html', 'attrs', 'count', 'visible', 'links', 'inputs', 'screenshot', 'viewport', 'wait', 'sleep'],
+  },
+  network: {
+    intro: 'requests and console record all the time; a capture records only while it runs.',
+    commands: ['requests', 'body', 'console', 'capture', 'route', 'network'],
+  },
+  devtools: {
+    intro: 'Cookie and storage listings omit values. eval, html, screenshots and URLs can still show sensitive data.',
+    commands: ['eval', 'cdp', 'cookies', 'storage'],
+  },
+  session: {
+    intro: `Completion: @<id> <command> makes the REPL print [[pw-done:<id>:ok|error]] when it finishes.
+
+Unknown outcome: a timed-out command may still be running, so the REPL disconnects instead of continuing.
+
+Server: pw-repl serve also takes commands on /tmp/playwright-repl.sock; they show here as [server] lines.
+
+The prompt is pw[serve]> while the server is on and pw> without it. Before it are the modes on in the
+selected tab, if any: (watch network:off routes:2 capture) pw>. modes lists them for every tab.
+
+Times (requests, console, watch) are local, with their UTC offset: 18:16:15.721-06:00.
+
+Dialogs are reported and never answered automatically.`,
+    commands: ['modes', 'help', 'quit'],
+  },
+};
+
+const COMMANDS = {
+  tab: {
+    usage: 'tab [<index>|<url-part>|new [url]|close [url-part]]',
+    summary: 'list tabs (* is selected); select, open or close one',
+    detail: 'tab <index> uses the numbers from the latest tab listing; they change when tabs open or close.\n\ntab <url-part> selects the one tab whose URL contains it, and refuses if none or several do.\n\ntab new opens and selects a tab. tab close closes the selected tab, or the one matching url-part.\n\nClosing the selected tab goes back to the previous tab if tab new opened it; otherwise no tab is\nselected, and commands that need one refuse until one is.',
+  },
+  goto: { usage: 'goto <url>', summary: 'navigate the selected tab; https:// is assumed' },
+  back: { usage: 'back', summary: 'go back one history entry' },
+  forward: { usage: 'forward', summary: 'go forward one history entry' },
+  reload: { usage: 'reload', summary: 'reload the selected tab' },
+  info: { usage: 'info', summary: 'selected tab URL, title and viewport' },
+  click: { usage: 'click <selector>', summary: 'click the first match' },
+  dblclick: { usage: 'dblclick <selector>', summary: 'double-click the first match' },
+  hover: { usage: 'hover <selector>', summary: 'hover the first match' },
+  fill: { usage: 'fill <selector> => <value>', summary: 'clear an input and fill it' },
+  type: { usage: 'type <selector> => <text>', summary: 'type into an input key by key' },
+  press: { usage: 'press <key> | press <selector> => <key>', summary: 'press a key, optionally on an element' },
+  select: { usage: 'select <selector> => <value>', summary: 'choose an option in a select' },
+  check: { usage: 'check <selector>', summary: 'check a checkbox' },
+  uncheck: { usage: 'uncheck <selector>', summary: 'uncheck a checkbox' },
+  snapshot: {
+    usage: 'snapshot [--full] [--grep <text> | <eN> | selector]',
+    summary: 'outline by role and name, with [ref=eN] labels',
+    detail: 'Playwright\'s accessibility snapshot, with unnamed layout wrappers (generic) and cursor hints left\nout; --full shows it unchanged.\n\n--grep <text> prints only the lines containing text (role, name or flag such as [disabled], any\ncase), each with the named elements around it. A hit with no named element around it prints without\na path.\n\nsnapshot e3 outlines one element. A label (e3, or f1e3 in newer Playwright) works as a selector:\nclick aria-ref=e3. Labels can change when the page navigates (e102 may become f4e98), so take a new\nsnapshot after one.\n\nOutput over 60 lines ends with a line count.',
+  },
+  watch: {
+    usage: 'watch on [--changes] [--live] | off | [n|new]',
+    summary: 'record what happens in the tab; show the last n steps',
+    detail: 'Off until watch on. Records clicks, typing (once it pauses), Enter and Escape, form changes, submits\nand navigations, each described by role and name like snapshot, with up to 5 of the requests it\ncaused underneath (their numbers in requests; body <#> for one), leaving out scripts and what\nrequests hides. The REPL\'s own fill is recorded as type.\n\nwatch on its own says whether it is on and shows the last 20 steps; watch <n> shows the last n.\nwatch new shows only the steps it has not shown yet, and requests that have since arrived for the\nlast one.\n\n--live also prints each step in the REPL window (never in the server\'s answer to a command) once it\nsettles, with its requests and changes, marked [watch], or [watch <url>] for a tab that is not the\nselected one. A step cut short by the next one, or by watch off, prints at once; changes it made\nthen show under the next step.\n\n--changes also shows what each step changed on the page once it settles, in up to 5 lines: + added,\n- removed, ~ changed, each element once with the first names inside it. Not for navigations.\n\nTyped values are not recorded, and password fields not at all; --changes leaves out field values,\nbut what the page itself shows (e.g. "Hello <name>") is shown. Nothing is replayed.',
+  },
+  text: { usage: 'text [--all] <selector>', summary: 'visible text of the first match' },
+  html: { usage: 'html [--all] <selector>', summary: 'outer HTML of the first match' },
+  attrs: { usage: 'attrs [--all] <selector>', summary: 'attributes of the first match' },
+  count: { usage: 'count <selector>', summary: 'number of matches' },
+  visible: { usage: 'visible <selector>', summary: 'whether the first match is visible' },
+  links: { usage: 'links [--all]', summary: 'links on the page (text and href)' },
+  inputs: { usage: 'inputs [--all]', summary: 'form controls on the page; values are omitted' },
+  screenshot: {
+    usage: 'screenshot [--full] [--delay|-d <seconds>] [name]',
+    summary: 'save a PNG of the viewport (or --full page)',
+    detail: 'Saved as screenshot-<name or timestamp>.png in $PW_SCREENSHOT_DIR (default /tmp).\n\n--delay counts down out loud first (maximum 60s), so someone can hold a hover or open a menu.',
+  },
+  viewport: { usage: 'viewport [WxH]', summary: 'show or set the viewport size' },
+  wait: {
+    usage: 'wait [text|request] <what> [secs]',
+    summary: 'wait for an element, text, or a response (default 10s)',
+    detail: 'wait <selector> waits for a matching element; wait text <text> for text to be visible; wait request\n<url-part|glob> for a matching response, counting one that finished since the previous command began\n(so click, then wait request, does not miss it).\n\nUp to 120s. A wait that times out is an error; the REPL carries on.',
+  },
+  sleep: { usage: 'sleep <ms>', summary: 'wait a fixed time (maximum 3600000)' },
+  requests: {
+    usage: 'requests [--all] [n] [url-filter]',
+    summary: 'the selected tab\'s last n requests (default 20)',
+    detail: 'Recording starts when the REPL connects; the last 200 per tab are kept. Each line: #number, time,\nmethod, status (HTTP code, pending, no response, failed: <reason>, or <code> faked), duration, URL.\nA request that finished a moment ago can still show pending.\n\nbody <#> shows what a request got back.\n\nImages, fonts, stylesheets, media and extension requests are hidden unless --all is given.\n\nurl-filter is a substring: requests 20 /api/ shows API calls only, e.g. when dev-server scripts\ncrowd the list.',
+  },
+  body: {
+    usage: 'body [--all] <#>',
+    summary: 'the response body of request <#> from requests',
+    detail: 'Read from the browser on demand: JSON is pretty-printed, binary is not shown, output is capped. The\nbrowser may drop a body (e.g. after the tab navigates); then body reports not available.\n\nBodies can contain sensitive data.',
+  },
+  console: {
+    usage: 'console [--all] [n] [filter]',
+    summary: 'the last n console messages and page errors',
+    detail: 'Recording starts when the REPL connects; the last 200 per tab are kept. Each line: time, [type],\ntext. Types are console levels (log, warning, error, ...) and pageerror for uncaught exceptions.\n\nfilter matches the type or the text, e.g. console error.',
+  },
+  capture: {
+    usage: 'capture on [requests|console] [secs] | off',
+    summary: 'record requests and console together, in time order',
+    detail: 'capture on records both until capture off, which prints them; requests or console records only one.\nWith secs (1-3600 seconds) it records that long, then prints; the REPL waits meanwhile.\n\nOne capture runs at a time, on the tab selected when it started. Unlike requests and console it\nkeeps more than the last 200 and lists both together.\n\ncapture on its own says whether one is running, or shows the last one.',
+  },
+  route: {
+    usage: 'route <glob> <status> <json> | off <glob>|--all',
+    summary: 'answer the selected tab\'s matching requests with fake JSON',
+    detail: 'The fake is fulfilled inside the browser, so the page handles it as a real response and the request\nnever reaches the network. Each one prints "Faked: #<n> <METHOD> <url> -> <status>", with #<n> as in\nrequests. If fulfilling fails it prints "Fake failed" and aborts the request, so it never reaches\nthe network.\n\nStatus: 200-599. wait request <glob> after the page loads prints the request with its status, so a\nfake shows as <status> faked.\n\nRoutes belong to the tab and last until route off <glob> (or route off --all) or the REPL exits.\nRouting the same glob again replaces it. route on its own lists the selected tab\'s routes.\n\nExample: route **/api/health_check 503 {"detail":{"code":"service_unavailable"}}',
+  },
+  network: {
+    usage: 'network [on|off]',
+    summary: 'cut or restore the tab\'s network, like dropped wifi',
+    detail: 'Stopping a service is not the same: a dev proxy in front of it usually holds the request open, so\nthe page spins instead of failing.\n\nPer tab; lasts until network on or the REPL exits.',
+  },
+  eval: {
+    usage: 'eval [--all] <JavaScript>',
+    summary: 'evaluate JavaScript in the selected tab and print the result',
+    detail: 'Promises are awaited. eval fetch(...) sends a new request, which can change state on the server; it\ncannot read one that already happened (requests lists those).',
+  },
+  cdp: {
+    usage: 'cdp [--all] <method> <JSON object>',
+    summary: 'send one CDP command through a temporary session',
+    detail: 'The session is detached afterwards, so subscriptions and settings do not persist.\n\nBrowser.close and Target.closeTarget are refused.',
+  },
+  cookies: { usage: 'cookies [--all]', summary: 'cookie names, domains and flags; values are omitted' },
+  storage: { usage: 'storage [--all]', summary: 'localStorage keys; values are omitted' },
+  modes: {
+    usage: 'modes [off]',
+    summary: 'the modes on in every tab; modes off turns them all off',
+    detail: 'The modes are watch, network off, route and capture. Each is turned on and off with its own command:\nwatch on|off, network off|on, route <glob> ... | route off, capture on|off.\n\nmodes off turns off every one in every tab; a capture it stops is kept for capture to show.',
+  },
+  help: { usage: 'help [topic | command | --all]', summary: 'this help; --all prints every topic and command in full' },
+  quit: {
+    usage: 'quit',
+    summary: 'disconnect, leaving Chromium running',
+    detail: 'Runs immediately, even while another command is waiting. Only available at the prompt.',
+  },
+};
+
+function commandLines(names) {
+  const width = Math.max(...names.map(n => COMMANDS[n].usage.length));
+  return names.map(n => `  ${COMMANDS[n].usage.padEnd(width)}  ${COMMANDS[n].summary}`);
+}
+
+function renderCommand(name) {
+  const entry = COMMANDS[name];
+  return [`${entry.usage} — ${entry.summary}`, ...(entry.detail ? ['', entry.detail] : [])].join('\n');
+}
+
+// Every topic's command list, with each command's details indented under it.
+function renderAll() {
+  const sections = Object.entries(TOPICS).map(([name, topic]) => {
+    const lines = commandLines(topic.commands).flatMap((line, i) => {
+      const detail = COMMANDS[topic.commands[i]].detail;
+      return detail ? [line, ...detail.split('\n').map(d => (d ? `      ${d}` : '')), ''] : [line];
+    });
+    if (lines[lines.length - 1] === '') lines.pop();
+    return [`== ${name} ==`, topic.intro, '', ...lines].join('\n');
+  });
+  return [OVERVIEW, ...sections].join('\n\n');
+}
+
+function render(topicOrCommand) {
+  if (!topicOrCommand) return OVERVIEW;
+  if (topicOrCommand === '--all') return renderAll();
+  if (Object.hasOwn(TOPICS, topicOrCommand)) {
+    const topic = TOPICS[topicOrCommand];
+    const text = [topic.intro, '', ...commandLines(topic.commands)].join('\n');
+    // A topic can share its name with a command (network); both are shown.
+    return Object.hasOwn(COMMANDS, topicOrCommand) ? `${text}\n\n${renderCommand(topicOrCommand)}` : text;
+  }
+  if (Object.hasOwn(COMMANDS, topicOrCommand)) return renderCommand(topicOrCommand);
+  return null;
+}
+
+module.exports = { render, TOPICS, COMMANDS };

package/lib/output.js

@@ -0,0 +1,70 @@
+// All command output goes through here rather than straight to console, so a
+// command run through the server can have its output collected and returned.
+const OUTPUT_LIMIT = 12000;
+
+let sink = null;
+
+function log(text) {
+  console.log(text);
+  if (sink) sink.push(String(text));
+}
+
+function error(text) {
+  console.error(text);
+  if (sink) sink.push(String(text));
+}
+
+// Commands run one at a time, so a single sink is enough. Lines printed by
+// background events while it is open (e.g. a Faked line) are collected too.
+async function collect(fn) {
+  const lines = sink = [];
+  try {
+    await fn();
+    return lines.join('\n');
+  } finally {
+    if (sink === lines) sink = null;
+  }
+}
+
+// Ends the open collection early and returns what it has so far, so a quit
+// can answer the command it interrupts without its own output mixed in.
+function take() {
+  const lines = sink || [];
+  sink = null;
+  return lines.join('\n');
+}
+
+// Lines the browser causes on its own (a faked request, a dialog) can arrive
+// while the prompt is showing. The entry point registers how to print above
+// the prompt and redraw it, so the pane still ends on a bare prompt.
+let idlePrinter = null;
+
+function onIdlePrint(printer) {
+  idlePrinter = printer;
+}
+
+function notice(text) {
+  if (!sink && idlePrinter && idlePrinter.idle()) idlePrinter.print(String(text));
+  else log(text);
+}
+
+// Like notice, but never part of a command's answer: for what the person at
+// the browser does, which is not the output of the command running now.
+function aside(text) {
+  if (!sink && idlePrinter && idlePrinter.idle()) idlePrinter.print(String(text));
+  else console.log(text);
+}
+
+function printOutput(value, all = false) {
+  let text;
+  if (typeof value === 'string') text = value;
+  else text = JSON.stringify(value, null, 2);
+  if (text === undefined) text = 'undefined';
+  if (!all && text.length > OUTPUT_LIMIT) {
+    log(`${text.slice(0, OUTPUT_LIMIT)}\n[truncated; use --all after the command to show all]`);
+  } else {
+    log(text);
+  }
+}
+
+module.exports = { OUTPUT_LIMIT, log, error, collect, take, notice, aside, onIdlePrint, printOutput };

package/lib/runner.js

@@ -0,0 +1,163 @@
+// Runs commands one at a time, whether they come from the prompt or the server.
+// A prompt command tagged @<id> reports completion with a marker the caller can wait for.
+const readline = require('readline');
+const { state, shutdown, beforeExit } = require('./state');
+const out = require('./output');
+const { commands, activeModes } = require('./commands');
+
+// A timeout here cannot have changed anything, so it is reported as an error
+// and the REPL carries on. Any other command that times out may still be
+// acting on the page, so the REPL disconnects rather than continue.
+const READ_ONLY = new Set(['info', 'text', 'html', 'attrs', 'count', 'visible', 'links', 'inputs',
+  'snapshot', 'screenshot', 'wait', 'sleep', 'requests', 'body', 'console', 'cookies', 'storage', 'capture', 'help']);
+
+// Commands that work with no tab selected.
+const NO_TAB_NEEDED = new Set(['tab', 'modes', 'capture', 'help', 'quit']);
+
+// Commands that accept a leading --all to lift the output limit.
+const INSPECTION = ['info', 'text', 'html', 'attrs', 'links', 'inputs', 'eval', 'cdp', 'cookies', 'storage', 'capture', 'body', 'console', 'snapshot', 'watch'];
+
+let queue = Promise.resolve();
+// The server command running now, so a quit at the prompt can answer it.
+let inFlight = null;
+
+function parseInput(line) {
+  const trimmed = line.trim();
+  const match = /^@([A-Za-z0-9][A-Za-z0-9._-]*)\s+([\s\S]+)$/.exec(trimmed);
+  return { text: match ? match[2] : trimmed, token: match ? match[1] : null };
+}
+
+function isUncertain(error) {
+  return /timed out|timeout|connection (?:lost|closed)/i.test(error.message || '');
+}
+
+let running = 0;
+
+// True while a command is running: its own output ends with a fresh prompt.
+function busy() {
+  return running > 0;
+}
+
+async function execute(text) {
+  running += 1;
+  try {
+    return await executeCommand(text);
+  } finally {
+    running -= 1;
+  }
+}
+
+async function executeCommand(text) {
+  if (state.connectionLost) return { status: 'error', cmd: '' };
+  if (!text) return { status: 'ok', cmd: '' };
+  const spaceIdx = text.indexOf(' ');
+  const cmd = spaceIdx === -1 ? text : text.slice(0, spaceIdx);
+  let args = spaceIdx === -1 ? '' : text.slice(spaceIdx + 1);
+  const all = INSPECTION.includes(cmd) && /^--all(?:\s|$)/.test(args);
+  if (all) args = args.slice(5).trimStart();
+  // wait request counts responses since the previous command began.
+  state.previousCommandAt = state.currentCommandAt;
+  state.currentCommandAt = Date.now();
+  if (!Object.hasOwn(commands, cmd)) {
+    out.log(`Unknown command: ${cmd}. Type 'help' for commands.`);
+    return { status: 'error', cmd };
+  }
+  if (!NO_TAB_NEEDED.has(cmd) && (!state.page || state.page.isClosed())) {
+    out.error('Error: No tab is selected; select one with tab <index|url-part>, or open one with tab new');
+    return { status: 'error', cmd };
+  }
+  try {
+    await commands[cmd](args, all);
+  } catch (e) {
+    out.error(`Error: ${e.message}`);
+    return { status: 'error', cmd, uncertain: !READ_ONLY.has(cmd) && isUncertain(e) };
+  }
+  if (cmd === 'quit' && state.shutdownFailed) return { status: 'error', cmd };
+  return { status: 'ok', cmd };
+}
+
+// A timed-out browser command may still be running, so nothing after it can
+// be trusted to act on the page the caller thinks it is acting on.
+function giveUp() {
+  out.error('Browser command outcome is unknown; disconnecting instead of continuing.');
+  void shutdown().then(beforeExit).then(() => process.exit(process.exitCode || 1));
+}
+
+// A quit does not wait for the running server command, which may never finish
+// once the browser is gone, so its sender is answered now. A read-only command
+// changed nothing; any other may or may not have done what it was sent to do.
+function answerInterrupted() {
+  if (!inFlight) return;
+  const flight = inFlight;
+  inFlight = null;
+  flight.answered = true;
+  const cmd = flight.text.split(' ')[0];
+  const known = READ_ONLY.has(cmd);
+  const note = known ? 'The REPL quit before this command finished.' : 'The REPL quit before this command finished; its outcome is unknown.';
+  const output = out.take();
+  flight.resolve({ status: 'error', output: output ? `${output}\n${note}` : note, uncertain: !known, interrupted: true });
+}
+
+async function handleLine(line) {
+  const input = parseInput(line);
+  const done = status => { if (input.token) out.log(`[[pw-done:${input.token}:${status}]]`); };
+  if (state.stopping) return done('error');
+  if (/^quit(?:\s|$)/.test(input.text)) answerInterrupted();
+  const result = await execute(input.text);
+  done(result.status);
+  if (result.cmd === 'quit') { await beforeExit(); process.exit(process.exitCode || 0); }
+  if (result.uncertain) return giveUp();
+  if (!state.stopping) prompt();
+}
+
+// The prompt starts with the modes on in the selected tab: (watch network:off) pw>.
+function prompt(preserveCursor) {
+  const modes = state.page && !state.page.isClosed() ? activeModes(state.page) : [];
+  state.rl.setPrompt(`${modes.length ? `(${modes.join(' ')}) ` : ''}${state.promptBase}`);
+  state.rl.prompt(preserveCursor);
+}
+
+// quit skips the queue so it still works while a long command is running.
+function enqueue(line) {
+  const direct = /^(?:@[A-Za-z0-9][A-Za-z0-9._-]*\s+)?quit(?:\s|$)/.test(line.trim());
+  const run = () => handleLine(line);
+  if (direct) run().catch(e => out.error(`Error: ${e.message}`));
+  else queue = queue.then(run).catch(e => out.error(`Error: ${e.message}`));
+}
+
+// Server commands share the prompt's queue and are echoed to the pane, so
+// someone watching sees everything an agent does.
+function submit(text) {
+  return new Promise(resolve => {
+    queue = queue.then(async () => {
+      if (state.stopping) return resolve({ status: 'error', output: 'The REPL is shutting down.' });
+      // Printed above whatever the person at the prompt is typing, which is
+      // redrawn afterwards rather than broken up.
+      if (process.stdout.isTTY) { readline.clearLine(process.stdout, 0); readline.cursorTo(process.stdout, 0); }
+      out.log(`[server] ${text}`);
+      // So the person at the prompt can bring an agent's command back with up-arrow.
+      if (state.rl.history && state.rl.history[0] !== text) {
+        state.rl.history.unshift(text);
+        state.rl.history.length = Math.min(state.rl.history.length, 1000);
+      }
+      if (/^quit(?:\s|$)/.test(text)) {
+        const output = await out.collect(async () => out.error('Error: quit is only available at the prompt'));
+        resolve({ status: 'error', output });
+      } else {
+        let result;
+        const flight = { text, resolve, answered: false };
+        inFlight = flight;
+        const output = await out.collect(async () => { result = await execute(text); });
+        if (inFlight === flight) inFlight = null;
+        if (!flight.answered) resolve({ status: result.status, output, uncertain: result.uncertain });
+      }
+      if (!state.stopping) prompt(true);
+    }).catch(e => { out.error(`Error: ${e.message}`); resolve({ status: 'error', output: e.message }); });
+  });
+}
+
+function drained() {
+  return queue;
+}
+
+module.exports = { enqueue, submit, giveUp, answerInterrupted, drained, busy };

package/lib/send.js

@@ -0,0 +1,127 @@
+// pw-repl send / where: one command to a running REPL, through its server
+// when there is one and through its tmux pane otherwise.
+//
+// Exit status: 0 ok, 1 command error, 2 completion not confirmed, 64 usage or unreachable.
+const fs = require('fs');
+const crypto = require('crypto');
+const { execFileSync } = require('child_process');
+const client = require('./client');
+
+// The prompt, after the modes on in the selected tab if any: (watch network:off) pw[serve]>
+const PROMPT = /^(?:\([^()]*\) )?pw(\[serve\])?>\s*$/;
+
+function tmux(...args) {
+  return execFileSync('tmux', args, { encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
+}
+
+function hasSession(session) {
+  try { tmux('has-session', '-t', session); return true; } catch { return false; }
+}
+
+// Which way a command goes: an explicit -e or -s wins; otherwise the server
+// when its socket exists, else tmux.
+function route(options) {
+  const socket = process.env.PW_SOCKET || client.DEFAULT_SOCKET;
+  const endpoint = options.endpoint || process.env.PW_ENDPOINT || '';
+  const session = options.session || process.env.PW_TMUX_SESSION || 'playwright-repl';
+  if (options.session) return { kind: 'tmux', session };
+  if (endpoint) return { kind: 'server', endpoint: client.parseEndpoint(endpoint), explicit: true };
+  if (fs.existsSync(socket) && fs.statSync(socket).isSocket()) return { kind: 'server', endpoint: client.parseEndpoint(socket), explicit: false, socket };
+  return { kind: 'tmux', session };
+}
+
+function fail(message) {
+  console.error(`pw-repl: ${message}`);
+  return 64;
+}
+
+// Checks a pane is running the REPL and sitting at a bare prompt. A REPL that
+// is exiting is still node for a moment but never shows a fresh prompt again,
+// and its last messages print on the prompt line ("pw> Browser command outcome
+// is unknown; ..."), so only a bare prompt counts. That also refuses while a
+// command runs or someone is typing.
+function paneProblem(session) {
+  if (!hasSession(session)) return `no tmux session '${session}'; ask the user before creating one (pw-repl skill: Start it)`;
+  const running = tmux('display-message', '-p', '-t', session, '#{pane_current_command}').trim();
+  if (running !== 'node') return `the REPL is not running in '${session}' (pane is running '${running}'); start it there with pw-repl run (pw-repl skill: Start it)`;
+  const lines = tmux('capture-pane', '-t', session, '-p').split('\n').filter(line => line.trim());
+  if (!PROMPT.test(lines[lines.length - 1] || '')) {
+    return `the REPL in '${session}' is not at a bare pw> or pw[serve]> prompt (busy, being typed at, or exiting); retry once it is, or check with pw-repl where`;
+  }
+  return null;
+}
+
+async function viaTmux(session, command, timeoutMs) {
+  const problem = paneProblem(session);
+  if (problem) return fail(problem);
+  // Random, so a marker left in the scrollback by an earlier command never matches.
+  const id = crypto.randomBytes(4).toString('hex');
+  tmux('send-keys', '-t', session, '-l', `@${id} ${command}`);
+  tmux('send-keys', '-t', session, 'Enter');
+  // -J joins lines tmux wrapped at the pane width, so long URLs stay whole.
+  const capture = () => tmux('capture-pane', '-t', session, '-p', '-J', '-S', '-10000');
+  const marker = new RegExp(`\\[\\[pw-done:${id}:(ok|error)\\]\\]`);
+  const deadline = Date.now() + timeoutMs;
+  let status = null;
+  let screen = '';
+  while (Date.now() < deadline) {
+    await new Promise(resolve => setTimeout(resolve, 500));
+    screen = capture();
+    const match = marker.exec(screen);
+    if (match) { status = match[1]; break; }
+  }
+  // Everything after the echoed input line; up to the marker when there is one.
+  const lines = screen.split('\n');
+  const start = lines.findIndex(line => line.includes(`@${id} `));
+  const output = [];
+  for (const line of start === -1 ? [] : lines.slice(start + 1)) {
+    if (line.includes(`[[pw-done:${id}:`)) break;
+    output.push(line);
+  }
+  if (output.length) console.log(output.join('\n'));
+  if (status === 'ok') return 0;
+  if (status === 'error') return 1;
+  console.error('completion not confirmed');
+  return 2;
+}
+
+async function send(options) {
+  const command = options.command;
+  if (!command) return fail('no command given');
+  // A newline would reach the REPL as a second, unmarked command.
+  if (/[\r\n]/.test(command)) return fail('the command must be a single line');
+  const timeoutMs = options.timeout * 1000;
+  const way = route(options);
+  if (way.kind === 'tmux') return viaTmux(way.session, command, timeoutMs);
+  const answer = await client.request(way.endpoint, command, timeoutMs);
+  if (answer.result) {
+    if (answer.result.output) console.log(answer.result.output);
+    if (answer.result.unconfirmed) { console.error('completion not confirmed'); return 2; }
+    return answer.result.status === 'ok' ? 0 : 1;
+  }
+  if (answer.timeout) { console.error('completion not confirmed'); return 2; }
+  if (answer.dropped) { console.error(`completion not confirmed: the REPL closed the connection (${answer.dropped})`); return 2; }
+  if (way.explicit) return fail(`cannot reach the REPL server at ${client.describe(way.endpoint)} (${answer.unreachable})`);
+  // The server was expected, so the REPL has most likely just exited or is
+  // exiting. Falling back to tmux now could type into the shell it leaves behind.
+  return fail(`the REPL server at ${way.socket} is not answering (${answer.unreachable}); not falling back to tmux. Check with pw-repl where; if the REPL now runs without the server, use -s or remove ${way.socket}`);
+}
+
+// Reports the route a command would take, checking it the way a command would.
+async function where(options) {
+  const way = route(options);
+  if (way.kind === 'server') {
+    const name = client.describe(way.endpoint);
+    if (await client.health(way.endpoint, 5000)) { console.log(`server: ${name} (the REPL was started with pw-repl serve)`); return 0; }
+    console.error(`server: ${name} is not answering`);
+    if (way.explicit) return 64;
+  }
+  const session = options.session || process.env.PW_TMUX_SESSION || 'playwright-repl';
+  if (!hasSession(session)) { console.error(`tmux: no session '${session}'`); return 64; }
+  const running = tmux('display-message', '-p', '-t', session, '#{pane_current_command}').trim();
+  if (running === 'node') { console.log(`tmux: session '${session}' (the REPL was started with pw-repl run; no server)`); return 0; }
+  console.error(`tmux: session '${session}' is running '${running}', not the REPL`);
+  return 64;
+}
+
+module.exports = { send, where };