From 5fea7a66eb2719ae81e956f2ba86aefd025181f2 Mon Sep 17 00:00:00 2001 From: Frog Date: Mon, 19 Oct 2026 16:23:28 +0200 Subject: [PATCH 1/3] docs for Process returning exit code --- .../docs/13-reference/00-BrowserPod/08-run.md | 14 ++++++++++---- .../docs/13-reference/00-BrowserPod/index.md | 4 ++-- .../content/docs/13-reference/04-Process/index.md | 12 +++++------- 3 files changed, 17 insertions(+), 13 deletions(-) diff --git a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/08-run.md b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/08-run.md index 47d0a1714..60e6aa823 100644 --- a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/08-run.md +++ b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/08-run.md @@ -1,6 +1,6 @@ --- title: run -description: "Run an executable inside a BrowserPod Pod, attach it to a terminal for input and output, and get back a Process handle for its result." +description: "Run an executable inside a BrowserPod Pod, attach it to a terminal for input and output, and wait for its exit code." --- ```ts @@ -14,7 +14,7 @@ class BrowserPod { cwd?: string; echo?: boolean; } - ): Promise; + ): Process; } ``` @@ -33,8 +33,14 @@ class BrowserPod { ## Returns -`run` returns a [Promise] which resolves to a [Process] object once the command finishes running. +`run` returns a [Process], a thenable object. Awaiting it resolves to the exit code of the process once it exits, so you can check whether it succeeded or failed: + +```ts +const exitCode = await pod.run("npm", ["install"], { terminal }); +if (exitCode !== 0) { + console.error(`npm install failed with exit code ${exitCode}`); +} +``` -[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise [Terminal]: /docs/reference/Terminal [Process]: /docs/reference/Process diff --git a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/index.md b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/index.md index 1ec706391..b253a7a86 100644 --- a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/index.md +++ b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/index.md @@ -41,10 +41,10 @@ const pod = await BrowserPod.boot({ apiKey: "...", storageKey: "my-project" }); ### Run programs -Use [`run`](/docs/reference/BrowserPod/run) to execute a program and get back a [Process](/docs/reference/Process): +Use [`run`](/docs/reference/BrowserPod/run) to execute a program. It returns a [Process](/docs/reference/Process) that resolves to the exit code when awaited: ```ts -const process = await pod.run("node", ["script.js"], { terminal }); +const exitCode = await pod.run("node", ["script.js"], { terminal }); ``` ### Manage the filesystem diff --git a/sites/browserpod/src/content/docs/13-reference/04-Process/index.md b/sites/browserpod/src/content/docs/13-reference/04-Process/index.md index ef6cefaca..8809b79f7 100644 --- a/sites/browserpod/src/content/docs/13-reference/04-Process/index.md +++ b/sites/browserpod/src/content/docs/13-reference/04-Process/index.md @@ -1,9 +1,11 @@ --- title: Process -description: A handle to a process that ran inside a Pod +description: A handle to a process running inside a Pod --- -A `Process` is an opaque handle to a program that ran inside a [Pod](/docs/reference/BrowserPod). It is returned by [`run`](/docs/reference/BrowserPod/run) once the process has exited. +A `Process` is a handle to a process running inside a [Pod](/docs/reference/BrowserPod). It is returned by [`run`](/docs/reference/BrowserPod/run). + +`Process` exposes no methods yet, but it is a thenable object: awaiting it resolves to the exit code of the process once it exits. ```ts class Process {} @@ -12,9 +14,5 @@ class Process {} ## Creating a Process ```ts -const process = await pod.run("node", ["script.js"], { terminal }); +const exitCode = await pod.run("node", ["script.js"], { terminal }); ``` - -The [Promise] resolves to a `Process` when the program exits. - -[Promise]: https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Promise From e4510652abdf050970500a044586166ba583b955 Mon Sep 17 00:00:00 2001 From: Frog Date: Mon, 19 Oct 2026 16:24:04 +0200 Subject: [PATCH 2/3] corrects onoutputs buffer data type --- .../13-reference/00-BrowserPod/01-createCustomTerminal.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/01-createCustomTerminal.md b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/01-createCustomTerminal.md index 9308fbf1f..d72b763b3 100644 --- a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/01-createCustomTerminal.md +++ b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/01-createCustomTerminal.md @@ -8,7 +8,7 @@ class BrowserPod { createCustomTerminal(opts: { cols?: number; rows?: number; - onOutput: (buffer: ArrayBuffer, vt?: unknown) => void; + onOutput: (buffer: Uint8Array, vt?: unknown) => void; }): Promise; } ``` @@ -21,7 +21,7 @@ class BrowserPod { - **cols (`number`, _optional_)** - The number of columns (width) for the terminal display. If not specified, a default width will be used. - **rows (`number`, _optional_)** - The number of rows (height) for the terminal display. If not specified, a default height will be used. -- **onOutput (`function(buffer: ArrayBuffer, vt?: unknown) => void`)** - Callback function invoked whenever the terminal produces output. The buffer contains the raw terminal data, and vt contains optional VT escape sequence information. +- **onOutput (`function(buffer: Uint8Array, vt?: unknown) => void`)** - Callback function invoked whenever the terminal produces output. The buffer contains the raw terminal data, and vt contains optional VT escape sequence information. ## Returns From bd073a481ad4a2fe1a15d3a187cb3f63143f5c3c Mon Sep 17 00:00:00 2001 From: Frog Date: Wed, 21 Oct 2026 16:06:53 +0200 Subject: [PATCH 3/3] BP docs for: VT, terminal.write, and pod.run error throwing --- .../00-BrowserPod/01-createCustomTerminal.md | 4 ++-- .../docs/13-reference/00-BrowserPod/08-run.md | 2 ++ .../docs/13-reference/03-Terminal/index.md | 15 +++++++++++++-- .../content/docs/13-reference/04-Process/index.md | 2 +- 4 files changed, 18 insertions(+), 5 deletions(-) diff --git a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/01-createCustomTerminal.md b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/01-createCustomTerminal.md index d72b763b3..944501767 100644 --- a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/01-createCustomTerminal.md +++ b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/01-createCustomTerminal.md @@ -8,7 +8,7 @@ class BrowserPod { createCustomTerminal(opts: { cols?: number; rows?: number; - onOutput: (buffer: Uint8Array, vt?: unknown) => void; + onOutput: (buffer: Uint8Array, vt?: number) => void; }): Promise; } ``` @@ -21,7 +21,7 @@ class BrowserPod { - **cols (`number`, _optional_)** - The number of columns (width) for the terminal display. If not specified, a default width will be used. - **rows (`number`, _optional_)** - The number of rows (height) for the terminal display. If not specified, a default height will be used. -- **onOutput (`function(buffer: Uint8Array, vt?: unknown) => void`)** - Callback function invoked whenever the terminal produces output. The buffer contains the raw terminal data, and vt contains optional VT escape sequence information. +- **onOutput (`function(buffer: Uint8Array, vt?: number) => void`)** - Callback function invoked whenever the terminal produces output. The buffer contains the raw terminal data, and vt is the ID of the terminal that produced it. ## Returns diff --git a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/08-run.md b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/08-run.md index 60e6aa823..65ff905ba 100644 --- a/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/08-run.md +++ b/sites/browserpod/src/content/docs/13-reference/00-BrowserPod/08-run.md @@ -42,5 +42,7 @@ if (exitCode !== 0) { } ``` +If the process cannot be started or is killed by a signal, awaiting it throws an error instead. + [Terminal]: /docs/reference/Terminal [Process]: /docs/reference/Process diff --git a/sites/browserpod/src/content/docs/13-reference/03-Terminal/index.md b/sites/browserpod/src/content/docs/13-reference/03-Terminal/index.md index 936eee9c6..02cabb8fa 100644 --- a/sites/browserpod/src/content/docs/13-reference/03-Terminal/index.md +++ b/sites/browserpod/src/content/docs/13-reference/03-Terminal/index.md @@ -3,10 +3,12 @@ title: Terminal description: A handle to a terminal emulator running inside a Pod --- -A `Terminal` is an opaque handle to a terminal emulator running inside a [Pod](/docs/reference/BrowserPod). It is created by [`createDefaultTerminal`](/docs/reference/BrowserPod/createDefaultTerminal) or [`createCustomTerminal`](/docs/reference/BrowserPod/createCustomTerminal), and passed to [`run`](/docs/reference/BrowserPod/run) to connect a process to I/O. +A `Terminal` is a handle to a terminal emulator running inside a [Pod](/docs/reference/BrowserPod). It is created by [`createDefaultTerminal`](/docs/reference/BrowserPod/createDefaultTerminal) or [`createCustomTerminal`](/docs/reference/BrowserPod/createCustomTerminal), and passed to [`run`](/docs/reference/BrowserPod/run) to connect a process to I/O. ```ts -class Terminal {} +class Terminal { + write(data: string | Uint8Array): void; +} ``` ## Creating a Terminal @@ -20,3 +22,12 @@ class Terminal {} const terminal = await pod.createDefaultTerminal(element); await pod.run("node", ["script.js"], { terminal }); ``` + +## Writing to a terminal + +`write` sends text or bytes directly to the terminal's output, without going through a process in the Pod. Running processes do not receive it as input. Use it to show your own messages alongside program output, such as the command about to run: + +```ts +terminal.write("$ npm install\r\n"); +await pod.run("npm", ["install"], { terminal }); +``` diff --git a/sites/browserpod/src/content/docs/13-reference/04-Process/index.md b/sites/browserpod/src/content/docs/13-reference/04-Process/index.md index 8809b79f7..8182494c6 100644 --- a/sites/browserpod/src/content/docs/13-reference/04-Process/index.md +++ b/sites/browserpod/src/content/docs/13-reference/04-Process/index.md @@ -5,7 +5,7 @@ description: A handle to a process running inside a Pod A `Process` is a handle to a process running inside a [Pod](/docs/reference/BrowserPod). It is returned by [`run`](/docs/reference/BrowserPod/run). -`Process` exposes no methods yet, but it is a thenable object: awaiting it resolves to the exit code of the process once it exits. +`Process` is a thenable object: awaiting it resolves to the exit code of the process once it exits. If the process cannot be started or is killed by a signal, awaiting it throws an error instead. ```ts class Process {}