From 5a4c6242ca4383d9a62968680f674e22faa05519 Mon Sep 17 00:00:00 2001
From: Reynaldi Chernando <reynaldichernando@gmail.com>
Date: Mon, 10 Aug 2026 12:42:31 +0700
Subject: [PATCH] Fix puter.js docs and types drift 10 aug

---
 src/docs/src/AI.md                          |  1 +
 src/docs/src/AI/txt2img.md                  |  3 +
 src/docs/src/Apps/create.md                 |  6 +-
 src/docs/src/Auth.md                        |  2 +
 src/docs/src/Auth/signIn.md                 |  2 +
 src/docs/src/FS.md                          |  1 +
 src/docs/src/FS/move.md                     |  1 +
 src/docs/src/FS/readdir.md                  |  2 +
 src/docs/src/FS/stat.md                     |  1 +
 src/docs/src/FS/upload.md                   | 15 +++++
 src/docs/src/FS/write.md                    |  4 +-
 src/docs/src/KV/decr.md                     |  2 +-
 src/docs/src/Objects.md                     |  2 +
 src/docs/src/Objects/app.md                 |  4 +-
 src/docs/src/Objects/chatresponsechunk.md   | 10 +++
 src/docs/src/Objects/puterpeerconnection.md | 70 +++++++++++++++++++++
 src/docs/src/Objects/puterpeerserver.md     | 50 +++++++++++++++
 src/docs/src/Peer/connect.md                | 15 +----
 src/docs/src/Peer/serve.md                  | 12 +---
 src/docs/src/Perms.md                       |  2 +-
 src/docs/src/UI.md                          |  5 +-
 src/docs/src/UI/contextMenu.md              |  6 ++
 src/docs/src/UI/setMenubar.md               |  4 ++
 src/docs/src/Utils/env.md                   |  6 ++
 src/docs/src/Utils/print.md                 |  6 +-
 src/docs/src/sidebar.js                     | 14 +++++
 src/puter-js/types/modules/ai.d.ts          | 39 +++++++++++-
 src/puter-js/types/modules/auth.d.ts        |  6 +-
 src/puter-js/types/modules/filesystem.d.ts  | 14 ++++-
 src/puter-js/types/modules/kv.d.ts          | 12 +++-
 src/puter-js/types/modules/ui.d.ts          | 10 +++
 31 files changed, 286 insertions(+), 41 deletions(-)
 create mode 100644 src/docs/src/Objects/puterpeerconnection.md
 create mode 100644 src/docs/src/Objects/puterpeerserver.md

diff --git a/src/docs/src/AI.md b/src/docs/src/AI.md
index a82cedb9ad..3b9aa8544d 100644
--- a/src/docs/src/AI.md
+++ b/src/docs/src/AI.md
@@ -193,6 +193,7 @@ These AI features are supported out of the box when using Puter.js:
 
 - **[`puter.ai.chat()`](/AI/chat/)** - Chat with AI models like Claude, GPT, and others
 - **[`puter.ai.listModels()`](/AI/listModels/)** - List available AI chat models (and providers) that Puter currently exposes.
+- **[`puter.ai.listModelProviders()`](/AI/listModelProviders/)** - List the AI providers that Puter currently exposes.
 - **[`puter.ai.txt2img()`](/AI/txt2img/)** - Generate images from text descriptions
 - **[`puter.ai.img2txt()`](/AI/img2txt/)** - Extract text from images (OCR)
 - **[`puter.ai.txt2speech()`](/AI/txt2speech/)** - Convert text to speech
diff --git a/src/docs/src/AI/txt2img.md b/src/docs/src/AI/txt2img.md
index 69632064a4..5f644eeae7 100755
--- a/src/docs/src/AI/txt2img.md
+++ b/src/docs/src/AI/txt2img.md
@@ -37,11 +37,14 @@ Additional settings for the generation request. Available options depend on the
 | `puter_output_path` | `String` | When set, the generated image is automatically saved to this path on the Puter filesystem. Relative paths are resolved against the app's data directory (or `~/` outside an app). The caller must have write permission to the destination |
 | `input_images` | `Array<String>` | Input image(s) for image-to-image — the canonical, cross-provider field (see below). |
 | `input_image` | `String` | Single-image shorthand for `input_images`. |
+| `input_image_mime_type` | `String` | MIME type of the input image(s), e.g. `'image/png'`. Used as a fallback when the type cannot be detected from the input — pass it when supplying raw base64 without a data-URI prefix. |
 
 #### Input images (image-to-image)
 
 `input_images` is the universal way to pass image-to-image inputs across providers; `input_image` is the single-image shorthand. Each entry may be a **public URL**, a **data-URI**, or **raw base64** — providers that need base64 fetch URLs server-side (SSRF-guarded), so a URL works everywhere.
 
+Raw base64 carries no MIME type of its own. When it cannot be detected from the bytes, set `input_image_mime_type` (e.g. `'image/png'`) — Gemini rejects the request otherwise, and OpenAI, xAI, and Replicate use it to label the upload.
+
 | Provider | Multiple images? | Accepted input forms |
 |----------|------------------|----------------------|
 | OpenAI `gpt-image-*` | Yes | URL, base64 / data-URI |
diff --git a/src/docs/src/Apps/create.md b/src/docs/src/Apps/create.md
index 366d5827e5..98c8df06df 100755
--- a/src/docs/src/Apps/create.md
+++ b/src/docs/src/Apps/create.md
@@ -22,7 +22,7 @@ The name of the app to create. This name must be unique to the user's apps. If a
 
 #### `indexURL` (required)
 
-The URL of the app's index page. This URL must be accessible to the user. If this parameter is not provided, the app will be created with no index page. The index page is the page that will be displayed when the app is started.
+The URL of the app's index page. This URL must be accessible to the user. The index page is the page that will be displayed when the app is started. If this parameter is not provided, the promise will be rejected.
 
 **IMPORTANT**: The URL _must_ start with either `http://` or `https://`. Any other protocols (including `file://`, `ftp://`, etc.) are not allowed and will result in an error. For example:
 
@@ -31,7 +31,7 @@ The URL of the app's index page. This URL must be accessible to the user. If thi
 ❌ `file:///path/to/index.html` <br>
 ❌ `ftp://example.com/index.html` <br>
 
-#### `title` (required)
+#### `title` (Optional)
 
 The title of the app. If this parameter is not provided, the app will be created with `name` as its title.
 
@@ -40,7 +40,7 @@ The title of the app. If this parameter is not provided, the app will be created
 An object containing the options for the app to create. The object can contain the following properties:
 
 - `name` (String) (required): The name of the app to create. This name must be unique to the user's apps. If an app with this name already exists, the promise will be rejected.
-- `indexURL` (String) (required): The URL of the app's index page. This URL must be accessible to the user. If this parameter is not provided, the app will be created with no index page.
+- `indexURL` (String) (required): The URL of the app's index page. This URL must be accessible to the user. If this parameter is not provided, the promise will be rejected.
 - `title` (String) (optional): The human-readable title of the app. If this parameter is not provided, the app will be created with `name` as its title.
 - `description` (String) (optional): The description of the app aimed at the end user.
 - `icon` (String) (optional): The new icon of the app.
diff --git a/src/docs/src/Auth.md b/src/docs/src/Auth.md
index ab677684b4..9d3c67e794 100644
--- a/src/docs/src/Auth.md
+++ b/src/docs/src/Auth.md
@@ -101,6 +101,8 @@ These authentication features are supported out of the box when using Puter.js:
 - **[`puter.auth.signOut()`](/Auth/signOut/)** - Sign out the current user
 - **[`puter.auth.isSignedIn()`](/Auth/isSignedIn/)** - Check if a user is signed in
 - **[`puter.auth.getUser()`](/Auth/getUser/)** - Get information about the current user
+- **[`puter.auth.getMonthlyUsage()`](/Auth/getMonthlyUsage/)** - Get the user's current monthly resource usage
+- **[`puter.auth.getDetailedAppUsage()`](/Auth/getDetailedAppUsage/)** - Get detailed usage statistics for an application
 
 ## Examples
 
diff --git a/src/docs/src/Auth/signIn.md b/src/docs/src/Auth/signIn.md
index 009427d3c2..6731e34301 100755
--- a/src/docs/src/Auth/signIn.md
+++ b/src/docs/src/Auth/signIn.md
@@ -29,6 +29,8 @@ puter.auth.signIn(options)
 
 - `attempt_temp_user_creation`: A boolean value that indicates whether to Puter should automatically create a temporary user. This is useful if you want to quickly onboard a user without requiring them to sign up. They can always sign up later if they want to.
 
+- `request_auth`: A boolean value that asks the popup to let the user re-pick their account, even when your site already holds a token for them. Puter otherwise skips that prompt for a site it has seen before. Useful for an explicit "switch account" button.
+
 ## Return value
 
 A `Promise` that will resolve to a [`SignInResult`](/Objects/signinresult/) object when the user has signed in.
diff --git a/src/docs/src/FS.md b/src/docs/src/FS.md
index 54673dc23e..68d505bb31 100644
--- a/src/docs/src/FS.md
+++ b/src/docs/src/FS.md
@@ -306,6 +306,7 @@ These cloud storage features are supported out of the box when using Puter.js:
 - **[`puter.fs.stat()`](/FS/stat/)** - Get information about a file or directory
 - **[`puter.fs.delete()`](/FS/delete/)** - Delete a file or directory
 - **[`puter.fs.upload()`](/FS/upload/)** - Upload a file from the local system
+- **[`puter.fs.getReadURL()`](/FS/getReadURL/)** - Generate a URL that can be used to read a file
 
 ## Examples
 
diff --git a/src/docs/src/FS/move.md b/src/docs/src/FS/move.md
index 251db0cd5c..e5e62244ea 100755
--- a/src/docs/src/FS/move.md
+++ b/src/docs/src/FS/move.md
@@ -32,6 +32,7 @@ The options for the `move` operation. The following options are supported:
 - `destination` (String) - Path to the destination. Required when passing options as the only argument.
 - `overwrite` (Boolean) - Whether to overwrite the destination file or directory if it already exists. Defaults to `false`.
 - `dedupeName` (Boolean) - Whether to deduplicate the file or directory name if it already exists. Defaults to `false`.
+- `newName` (String) - The name to give the moved file or directory. When set, `destination` is always treated as the directory to move into. Defaults to the source's own name.
 - `createMissingParents` (Boolean) - Whether to create missing parent directories. Defaults to `false`.
 
 ## Return value
diff --git a/src/docs/src/FS/readdir.md b/src/docs/src/FS/readdir.md
index fc8d900f7e..a51a03a35e 100755
--- a/src/docs/src/FS/readdir.md
+++ b/src/docs/src/FS/readdir.md
@@ -31,6 +31,8 @@ An object with the following properties:
 - `offset` (Number) (optional) - Skips the given number of entries. Prefer `cursor` for paging through large directories.
 - `sortBy` (String) (optional) - Sort field: `name`, `modified`, `type`, or `size`. Default is `name`.
 - `sortOrder` (String) (optional) - `asc` or `desc`. Default is `asc`.
+- `recursive` (Boolean) (optional) - If `true`, the contents of subdirectories are listed too. Defaults to `false`.
+- `depth` (Number) (optional) - How many levels to descend when `recursive` is `true`. Defaults to unlimited.
 - `cursor` (String | null) (optional) - Opts into paginated results. Pass `null` for the first page, then the `cursor` from each page to fetch the next one. The cursor pins the sort, so later pages must not request a different `sortBy`/`sortOrder`.
 - `includeTotal` (Boolean) (optional) - If `true`, the paginated result includes a `total` count of all entries in the directory.
 - `stream` (Boolean) (optional) - If `true`, the method returns an async iterator of page objects instead of a promise, for use with `for await ... of`. Combine with `limit` to control the page size, or `cursor` to resume from a previous page. Cannot be combined with `offset`. With `includeTotal`, only the first page carries `total`.
diff --git a/src/docs/src/FS/stat.md b/src/docs/src/FS/stat.md
index c2465a7ac1..77ccc22b43 100755
--- a/src/docs/src/FS/stat.md
+++ b/src/docs/src/FS/stat.md
@@ -27,6 +27,7 @@ An object with the following properties:
 - `path` (String) - Path to the file or directory. Required when passing options as the only argument.
 - `uid` (String) - The UID of the file or directory. Can be used instead of `path`.
 - `returnSubdomains` (Boolean) - Whether to return subdomain information. Defaults to `false`.
+- `returnWorkers` (Boolean) - Whether to return the workers attached to the item. Workers are served alongside subdomains, so this is an alias of `returnSubdomains` — setting either one returns both. Defaults to `false`.
 - `returnPermissions` (Boolean) - Whether to return permission information. Defaults to `false`.
 - `returnVersions` (Boolean) - Whether to return version information. Defaults to `false`.
 - `returnSize` (Boolean) - Whether to return size information. Defaults to `false`.
diff --git a/src/docs/src/FS/upload.md b/src/docs/src/FS/upload.md
index 0be4e0b1fb..9f04b5efda 100755
--- a/src/docs/src/FS/upload.md
+++ b/src/docs/src/FS/upload.md
@@ -32,6 +32,21 @@ A set of key/value pairs that configure the upload process. The following option
 - `dedupeName` (Boolean) - Whether to deduplicate the file name if it already exists. Defaults to `true`. Ignored when `overwrite` is `true`.
 - `createMissingParents` (Boolean) - Whether to create missing parent directories. Defaults to `false`.
 
+The following callbacks report on the upload as it runs. `operationId` identifies the upload, so a page running several uploads at once can tell them apart:
+
+- `init` (Function) - Called with `(operationId, xhr)` once the request has been created, before it is sent. The `XMLHttpRequest` is passed so you can abort the upload yourself.
+- `start` (Function) - Called with no arguments when the upload starts sending.
+- `progress` (Function) - Called with `(operationId, progress)` as bytes are sent, where `progress` is a percentage between `0` and `100`.
+- `abort` (Function) - Called with `(operationId)` if the upload is aborted.
+
+```js
+puter.fs.upload(items, './uploads', {
+    progress: (operationId, progress) => {
+        console.log(`${Math.round(progress)}%`);
+    },
+});
+```
+
 ## Return value
 
 Returns a `Promise` that resolves to:
diff --git a/src/docs/src/FS/write.md b/src/docs/src/FS/write.md
index f1c696b20b..0323de5bf0 100755
--- a/src/docs/src/FS/write.md
+++ b/src/docs/src/FS/write.md
@@ -22,9 +22,9 @@ puter.fs.write(file)
 The path to the file to write to.
 If path is not absolute, it will be resolved relative to the app's root directory.
 
-#### `data` (String|File|Blob) (required)
+#### `data` (String|File|Blob|ArrayBuffer|TypedArray) (optional)
 
-The data to write to the file.
+The data to write to the file. If omitted, an empty file is created.
 
 #### `options` (Object)
 
diff --git a/src/docs/src/KV/decr.md b/src/docs/src/KV/decr.md
index d026edb96f..40c46b148d 100755
--- a/src/docs/src/KV/decr.md
+++ b/src/docs/src/KV/decr.md
@@ -4,7 +4,7 @@ description: Decrement numeric values in key-value store by a specified amount.
 platforms: [websites, apps, nodejs, workers]
 ---
 
-Decrements the value of a key. If the key does not exist, it is initialized with 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer.
+Decrements the value of a key. If the key does not exist, it is initialized with 0 before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64 bit signed integers.
 
 ## Syntax
 
diff --git a/src/docs/src/Objects.md b/src/docs/src/Objects.md
index 600fa6b558..227068f952 100644
--- a/src/docs/src/Objects.md
+++ b/src/docs/src/Objects.md
@@ -15,6 +15,8 @@ Various object types and classes that represent different entities in the Puter
 - **[FSItem](/Objects/fsitem/)** - Represents a file or directory
 - **[KVPair](/Objects/kvpair/)** - Represents a key-value pair
 - **[MonthlyUsage](/Objects/monthlyusage/)** - Represents user's monthly resource usage information
+- **[PuterPeerConnection](/Objects/puterpeerconnection/)** - Represents a data-channel connection to a peer
+- **[PuterPeerServer](/Objects/puterpeerserver/)** - Represents a peer server and its connected clients
 - **[Speech2TxtResult](/Objects/speech2txtresult/)** - Represents speech-to-text transcription results
 - **[Subdomain](/Objects/subdomain/)** - Represents a subdomain
 - **[TTSEngine](/Objects/ttsengine/)** - Represents an available text-to-speech engine/model
diff --git a/src/docs/src/Objects/app.md b/src/docs/src/Objects/app.md
index c7cdf7e824..0214c93236 100755
--- a/src/docs/src/Objects/app.md
+++ b/src/docs/src/Objects/app.md
@@ -78,7 +78,9 @@ __Parameters__
 
 __Return value__
 
-Iterable objects each containing `{username, user_uuid}`.
+Iterable objects each containing `{username, user_uuid}`, plus an optional `user_email`.
+
+`user_email` is only present when the user granted this app the `user:<uuid>:email:read` permission (for example via [`puter.perms.requestEmail()`](/Perms/requestEmail/)); it is omitted otherwise, and may be `null` if the user granted access but has no email on file.
 
 __Example__
 
diff --git a/src/docs/src/Objects/chatresponsechunk.md b/src/docs/src/Objects/chatresponsechunk.md
index 5f56c61323..e10075167e 100644
--- a/src/docs/src/Objects/chatresponsechunk.md
+++ b/src/docs/src/Objects/chatresponsechunk.md
@@ -15,10 +15,12 @@ The kind of chunk. One of:
 
 - `"text"` - A portion of the response text.
 - `"reasoning"` - A portion of the model's reasoning/thinking output.
+- `"image"` - An image generated by an image-capable model.
 - `"tool_use"` - A tool/function the model wants to call.
 - `"compaction"` - An inline-compaction summary of earlier context (when `compaction` is enabled).
 - `"extra_content"` - Provider-specific metadata.
 - `"usage"` - Token usage totals, emitted as the final chunk.
+- `"error"` - An error raised while the response was streaming. Ends the stream.
 
 #### `text` (String)
 
@@ -28,6 +30,10 @@ A portion of the chat response text. Present on `text` chunks.
 
 A portion of the model's reasoning output. Present on `reasoning` chunks.
 
+#### `image` (Object)
+
+A generated image, in the form `{ type: "image_url", image_url: { url } }` where `url` is a data URI. Present on `image` chunks.
+
 #### `id` (String)
 
 The unique identifier for the tool call (`tool_use` chunks) or the compaction item (`compaction` chunks).
@@ -51,3 +57,7 @@ Provider-specific metadata attached to the stream.
 #### `usage` (Object)
 
 An object containing token usage totals. Present on the final `usage` chunk.
+
+#### `message` (String)
+
+A description of the error that interrupted the response. Present on `error` chunks.
diff --git a/src/docs/src/Objects/puterpeerconnection.md b/src/docs/src/Objects/puterpeerconnection.md
new file mode 100644
index 0000000000..5009c4259e
--- /dev/null
+++ b/src/docs/src/Objects/puterpeerconnection.md
@@ -0,0 +1,70 @@
+---
+title: PuterPeerConnection
+description: The PuterPeerConnection object representing a WebRTC data-channel connection to a peer.
+---
+
+The `PuterPeerConnection` object representing a WebRTC data-channel connection to a peer. [`puter.peer.connect()`](/Peer/connect/) resolves to one, and a [`PuterPeerServer`](/Objects/puterpeerserver/) hands one to its `connection` event for every client that joins.
+
+`PuterPeerConnection` extends [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), so events are subscribed to with `addEventListener()`.
+
+## Attributes
+
+#### `owner` (Object)
+
+Information about the user who created the server, with `username` and `uuid`.
+
+#### `connected` (Boolean)
+
+Whether the data channel is currently open.
+
+#### `closed` (Boolean)
+
+Whether the connection has been closed.
+
+#### `peerconnection` (RTCPeerConnection)
+
+The raw underlying [`RTCPeerConnection`](https://developer.mozilla.org/en-US/docs/Web/API/RTCPeerConnection) handle, for cases the Puter API does not cover.
+
+## Methods
+
+#### `send(data)`
+
+Sends a message to the peer. `data` may be a `String`, `Blob`, `ArrayBuffer`, or `ArrayBufferView`.
+
+#### `close(reason)`
+
+Closes the connection. The optional `reason` string is delivered to the peer on its `close` event.
+
+## Events
+
+#### `open`
+
+Fired when the data channel is ready. Wait for this before calling `send()`.
+
+#### `message`
+
+Fired when a message is received. `event.data` holds the payload.
+
+#### `close`
+
+Fired when the connection closes. `event.reason` holds the reason, if one was given.
+
+#### `error`
+
+Fired when a connection error occurs. `event.error` holds the error.
+
+## Example
+
+```js
+const conn = await puter.peer.connect(inviteCode);
+
+conn.addEventListener('open', () => {
+    conn.send('Hello from the client!');
+});
+conn.addEventListener('message', (msg) => {
+    puter.print('Server says:', msg.data);
+});
+conn.addEventListener('close', (event) => {
+    puter.print('Connection closed:', event.reason);
+});
+```
diff --git a/src/docs/src/Objects/puterpeerserver.md b/src/docs/src/Objects/puterpeerserver.md
new file mode 100644
index 0000000000..5203dfa8da
--- /dev/null
+++ b/src/docs/src/Objects/puterpeerserver.md
@@ -0,0 +1,50 @@
+---
+title: PuterPeerServer
+description: The PuterPeerServer object returned by puter.peer.serve(), representing a peer server and its connected clients.
+---
+
+The `PuterPeerServer` object returned by [`puter.peer.serve()`](/Peer/serve/). It holds the invite code other clients use to reach you, and tracks every client that connects.
+
+`PuterPeerServer` extends [`EventTarget`](https://developer.mozilla.org/en-US/docs/Web/API/EventTarget), so events are subscribed to with `addEventListener()`.
+
+## Attributes
+
+#### `inviteCode` (String)
+
+The code to share with other clients so they can connect with [`puter.peer.connect()`](/Peer/connect/).
+
+#### `connections` (Map)
+
+A `Map` of every connected client, keyed by connection id. The values are [`PuterPeerConnection`](/Objects/puterpeerconnection/) objects.
+
+## Methods
+
+#### `close()`
+
+Closes every client connection and the signalling connection. The invite code stops working.
+
+## Events
+
+#### `connection`
+
+Fired when a client connects. The event has the following attributes:
+
+- `conn` ([`PuterPeerConnection`](/Objects/puterpeerconnection/)) - The connection to the client.
+- `user` (Object) - Metadata about the connecting user, with `username` and `uuid` (if available).
+
+## Example
+
+```js
+const server = await puter.peer.serve();
+puter.print(`Invite code: ${server.inviteCode}`);
+
+server.addEventListener('connection', (event) => {
+    const conn = event.conn;
+    conn.addEventListener('open', () => {
+        conn.send('Hello from the server!');
+    });
+    conn.addEventListener('message', (msg) => {
+        puter.print('Client says:', msg.data);
+    });
+});
+```
diff --git a/src/docs/src/Peer/connect.md b/src/docs/src/Peer/connect.md
index d3e3335c89..207bacaff4 100644
--- a/src/docs/src/Peer/connect.md
+++ b/src/docs/src/Peer/connect.md
@@ -5,7 +5,7 @@ platforms: [websites, apps]
 ---
 
 
-Connects to a peer server and returns a `PuterPeerConnection` instance.
+Connects to a peer server and returns a [`PuterPeerConnection`](/Objects/puterpeerconnection/) instance.
 
 <div class="info">
 
@@ -35,18 +35,7 @@ A string invite code created by `puter.peer.serve()`.
 
 ## Return value
 
-A `Promise` that resolves to a `PuterPeerConnection` instance.
-
-### `PuterPeerConnection` methods and events
-
-- `send(data)` - Send a message to the peer. Supports strings, `Blob`, `ArrayBuffer`, or `ArrayBufferView`.
-- `close(reason)` - Close the connection.
-- `owner` (`object`) - Information about the user who created the server.
-- `peerconnection` (`RTCPeerConnection`) - the raw underlying RTC handle for this connection.
-- `open` event: Fired when the data channel is ready.
-- `message` event: Fired when a message is received (`event.data`).
-- `close` event: Fired when the connection closes (`event.reason`).
-- `error` event: Fired when a connection error occurs (`event.error`).
+A `Promise` that resolves to a [`PuterPeerConnection`](/Objects/puterpeerconnection/) instance, which carries `send()` and `close()` methods and the `open`, `message`, `close`, and `error` events.
 
 ## Example
 
diff --git a/src/docs/src/Peer/serve.md b/src/docs/src/Peer/serve.md
index e8ba914b57..6cb43e4521 100644
--- a/src/docs/src/Peer/serve.md
+++ b/src/docs/src/Peer/serve.md
@@ -5,7 +5,7 @@ platforms: [websites, apps]
 ---
 
 
-Creates a peer server and returns a `PuterPeerServer` instance. The server will generate an invite code that other clients can use to connect.
+Creates a peer server and returns a [`PuterPeerServer`](/Objects/puterpeerserver/) instance. The server will generate an invite code that other clients can use to connect.
 
 <div class="info">
 
@@ -31,15 +31,7 @@ const server = await puter.peer.serve(options);
 
 ## Return value
 
-A `Promise` that resolves to a `PuterPeerServer` instance.
-
-### `PuterPeerServer` properties and events
-
-- `inviteCode` (`string`) The code you share with other clients.
-- `connections` (`Map<string, PuterPeerConnection>`) map of all connected clients
-- `connection` event: Fired when a client connects.
-  - `event.conn` (`PuterPeerConnection`) The connection to the client.
-  - `event.user` (`object`) Metadata about the connecting user (if available).
+A `Promise` that resolves to a [`PuterPeerServer`](/Objects/puterpeerserver/) instance, which carries the `inviteCode` to share, the `connections` map of connected clients, and a `connection` event fired as each client joins.
 
 ## Example
 
diff --git a/src/docs/src/Perms.md b/src/docs/src/Perms.md
index 9ce3c8d5c3..8de4eba03e 100644
--- a/src/docs/src/Perms.md
+++ b/src/docs/src/Perms.md
@@ -1,7 +1,7 @@
 ---
 title: Perms
 description: Request permissions to access user data and resources with Puter.js Permissions API
-platforms: [apps]
+platforms: [websites, apps]
 ---
 
 The Permissions API enables your application to request access to user data and resources such as email addresses, special folders (Desktop, Documents, Pictures, Videos), apps, subdomains, and other apps' saved data.
diff --git a/src/docs/src/UI.md b/src/docs/src/UI.md
index df8ad0c99e..62e3e5bcd1 100644
--- a/src/docs/src/UI.md
+++ b/src/docs/src/UI.md
@@ -24,6 +24,8 @@ The UI API provides a comprehensive set of tools for creating rich user interfac
 - **[`puter.ui.setWindowHeight()`](/UI/setWindowHeight/)** - Set window height
 - **[`puter.ui.setWindowX()`](/UI/setWindowX/)** - Set window X position
 - **[`puter.ui.setWindowY()`](/UI/setWindowY/)** - Set window Y position
+- **[`puter.ui.showWindow()`](/UI/showWindow/)** - Show the application's window
+- **[`puter.ui.hideWindow()`](/UI/hideWindow/)** - Hide the application's window
 
 ### File Pickers
 - **[`puter.ui.showOpenFilePicker()`](/UI/showOpenFilePicker/)** - Show file open dialog
@@ -33,7 +35,7 @@ The UI API provides a comprehensive set of tools for creating rich user interfac
 ### System Integration
 - **[`puter.ui.launchApp()`](/UI/launchApp/)** - Launch other applications
 - **[`puter.ui.parentApp()`](/UI/parentApp/)** - Get parent application info
-- **[`puter.ui.exit()`](/UI/exit/)** - Exit the application
+- **[`puter.exit()`](/UI/exit/)** - Exit the application
 - **[`puter.ui.setMenubar()`](/UI/setMenubar/)** - Set application menubar
 - **[`puter.ui.getLanguage()`](/UI/getLanguage/)** - Get current language/locale code
 
@@ -45,6 +47,7 @@ The UI API provides a comprehensive set of tools for creating rich user interfac
 - **[`puter.ui.onWindowClose()`](/UI/onWindowClose/)** - Handle window close events
 
 ### Additional UI Elements
+- **[`puter.ui.contextMenu()`](/UI/contextMenu/)** - Show a context menu at the cursor
 - **[`puter.ui.hideSpinner()`](/UI/hideSpinner/)** - Hide spinner
 - **[`puter.ui.showColorPicker()`](/UI/showColorPicker/)** - Show color picker
 - **[`puter.ui.showFontPicker()`](/UI/showFontPicker/)** - Show font picker
diff --git a/src/docs/src/UI/contextMenu.md b/src/docs/src/UI/contextMenu.md
index 743192ab89..c3700f6225 100644
--- a/src/docs/src/UI/contextMenu.md
+++ b/src/docs/src/UI/contextMenu.md
@@ -26,6 +26,12 @@ An object that configures the context menu.
     - `items` (Array, optional): An array of submenu items. Creates a submenu when specified.
   - **Separator**: A string `'-'` to create a visual separator between menu items.
 
+* `theme` (String, optional): Forces the menu's color theme — `'dark'` or `'light'`. When unset, the menu follows the system color-scheme preference.
+* `x` (Number, optional): X position of the menu, in pixels. Defaults to the cursor position.
+* `y` (Number, optional): Y position of the menu, in pixels. Defaults to the cursor position.
+
+`theme`, `x`, and `y` only apply when running standalone (`puter.env === 'web'`). Inside the Puter desktop (`puter.env === 'app'`) the menu is rendered by the desktop, which places it at the cursor and uses its own theme.
+
 ## Return value 
 This method does not return a value. The context menu is displayed immediately and menu item actions are executed when clicked.
 
diff --git a/src/docs/src/UI/setMenubar.md b/src/docs/src/UI/setMenubar.md
index a4b8e74099..f34c6ba246 100755
--- a/src/docs/src/UI/setMenubar.md
+++ b/src/docs/src/UI/setMenubar.md
@@ -14,6 +14,10 @@ puter.ui.setMenubar(options)
 
 ## Parameters
 
+#### `options.theme` (String) (optional)
+
+Forces the menubar's color theme — `'dark'` or `'light'`. When unset, the menubar follows the system color-scheme preference. Only applies when running standalone (`puter.env === 'web'`); inside the Puter desktop the menubar is rendered by the desktop, which uses its own theme.
+
 #### `options.items` (Array)
 
 An array of menu items. Each item can be a menu or a menu item. Each menu item can have a label, an action, and a submenu. An item can also be the string `'-'`, which indicates a separator (renders as a horizontal divider between groups of items).
diff --git a/src/docs/src/Utils/env.md b/src/docs/src/Utils/env.md
index 3f4ccb02da..fcfaf17532 100644
--- a/src/docs/src/Utils/env.md
+++ b/src/docs/src/Utils/env.md
@@ -22,6 +22,12 @@ A string containing the environment in which Puter.js is being used:
 
 - `gui` - Puter.js is running inside the Puter GUI. e.g. `https://puter.com/`
 
+- `nodejs` - Puter.js is running in Node.js.
+
+- `web-worker` - Puter.js is running inside a [Web Worker](https://developer.mozilla.org/en-US/docs/Web/API/Web_Workers_API).
+
+- `service-worker` - Puter.js is running inside a [Puter Worker](/Workers/). Serverless workers execute in a service worker global scope, which is what this value reports.
+
 ## Examples
 
 <strong class="example-title">Get the environment in which Puter.js is running</strong>
diff --git a/src/docs/src/Utils/print.md b/src/docs/src/Utils/print.md
index 7dd4263ea8..f5ef743596 100755
--- a/src/docs/src/Utils/print.md
+++ b/src/docs/src/Utils/print.md
@@ -10,6 +10,7 @@ Prints a string by appending it to the body of the document. This is useful for
 
 ```js
 puter.print(text)
+puter.print(text, options)
 ```
 
 ## Parameters
@@ -20,9 +21,10 @@ The text to print.
 
 #### `options` (Object, optional)
 
-An object containing options for the print function.
+An object containing options for the print function. It must be the last argument.
 
-- `code` (Boolean, optional): If true, the text will be printed as code by wrapping it in a `<code>` and `<pre>` tag. Defaults to `false`.
+- `code` (Boolean, optional): If true, the text will be printed as code by wrapping it in a `<code>` and `<pre>` tag. Defaults to `false`. Implies `escapeHTML`.
+- `escapeHTML` (Boolean, optional): If true, HTML in the text is escaped rather than rendered. Defaults to `false`.
 
 ## Examples
 
diff --git a/src/docs/src/sidebar.js b/src/docs/src/sidebar.js
index ff3ba1951e..c4da918b37 100755
--- a/src/docs/src/sidebar.js
+++ b/src/docs/src/sidebar.js
@@ -1245,6 +1245,20 @@ let sidebar = [
                 source: '/Objects/monthlyusage.md',
                 path: '/Objects/monthlyusage',
             },
+            {
+                title: '<code>PuterPeerConnection</code>',
+                title_tag: 'PuterPeerConnection',
+                icon: '/assets/img/object.svg',
+                source: '/Objects/puterpeerconnection.md',
+                path: '/Objects/puterpeerconnection',
+            },
+            {
+                title: '<code>PuterPeerServer</code>',
+                title_tag: 'PuterPeerServer',
+                icon: '/assets/img/object.svg',
+                source: '/Objects/puterpeerserver.md',
+                path: '/Objects/puterpeerserver',
+            },
             {
                 title: '<code>SignInResult</code>',
                 title_tag: 'SignInResult',
diff --git a/src/puter-js/types/modules/ai.d.ts b/src/puter-js/types/modules/ai.d.ts
index 11255c83bd..4b179f361d 100644
--- a/src/puter-js/types/modules/ai.d.ts
+++ b/src/puter-js/types/modules/ai.d.ts
@@ -11,7 +11,8 @@ export interface ChatMessage {
     tool_calls?: ToolCall[];
     tool_call_id?: string;
     cache_control?: { type: string };
-    images: ImageContent[];
+    /** Images attached to the message. Present on responses from image-capable models. */
+    images?: ImageContent[];
 }
 
 export interface ToolCall {
@@ -105,12 +106,14 @@ export interface ChatResponse {
  * discriminator; which other fields are present depends on that `type`.
  */
 export interface ChatResponseChunk {
-    /** The kind of chunk: `"text"`, `"reasoning"`, `"tool_use"`, `"compaction"`, `"extra_content"`, or `"usage"`. */
+    /** The kind of chunk: `"text"`, `"reasoning"`, `"image"`, `"tool_use"`, `"compaction"`, `"extra_content"`, `"usage"`, or `"error"`. */
     type: string;
     /** Text delta. Present on `"text"` chunks. */
     text?: string;
     /** Reasoning/thinking delta. Present on `"reasoning"` chunks. */
     reasoning?: string;
+    /** A generated image. Present on `"image"` chunks from image-capable models. */
+    image?: ImageContent;
     /** Tool call id (`"tool_use"`) or compaction item id (`"compaction"`). */
     id?: string;
     /** Tool/function name. Present on `"tool_use"` chunks. */
@@ -127,6 +130,8 @@ export interface ChatResponseChunk {
     extra_content?: unknown;
     /** Token usage totals. Present on the final `"usage"` chunk. */
     usage?: Record<string, number>;
+    /** Error description. Present on `"error"` chunks, which end the stream. */
+    message?: string;
 }
 
 export interface Img2TxtOptions {
@@ -221,6 +226,36 @@ export interface Txt2ImgOptions {
      * output format, e.g. `'webp'` | `'jpg'` | `'png'`.
      */
     response_format?: string;
+    /** Guidance scale (Replicate `flux-2-klein-9b-base`). */
+    guidance?: number;
+    /**
+     * Use the model's optimized fast mode (Replicate `flux-2-dev`). Defaults to
+     * `true` for that model, and affects pricing.
+     */
+    go_fast?: boolean;
+    /** Output quality, 0-100 (Replicate, flux family). */
+    output_quality?: number;
+    /**
+     * Approximate output size in megapixels (Replicate, flux family), e.g.
+     * `'0.25'` | `'0.5'` | `'1'` | `'2'`.
+     */
+    output_megapixels?: string;
+    /** Safety tolerance level (Replicate `flux-2-pro`, `flux-1.1-pro`). */
+    safety_tolerance?: number;
+    /** Enable prompt upsampling (Replicate `flux-1.1-pro`). */
+    prompt_upsampling?: boolean;
+    /**
+     * Generation tier for Replicate Leonardo models, which affects pricing:
+     * `'standard'` | `'ultra'` (`lucid-origin`), `'fast'` | `'quality'` |
+     * `'ultra'` (`phoenix-1.0`).
+     */
+    generation_mode?: string;
+    /** Stylistic preset (Replicate Leonardo models). */
+    style?: string;
+    /** Contrast preset (Replicate Leonardo models). */
+    contrast?: string;
+    /** Server-side prompt enhancement (Replicate Leonardo models). */
+    prompt_enhance?: boolean;
     /** When `true`, returns a sample image without using credits. */
     test_mode?: boolean;
     /**
diff --git a/src/puter-js/types/modules/auth.d.ts b/src/puter-js/types/modules/auth.d.ts
index 664810b9b8..6174a5ffa3 100644
--- a/src/puter-js/types/modules/auth.d.ts
+++ b/src/puter-js/types/modules/auth.d.ts
@@ -108,8 +108,12 @@ export class Auth {
      *
      * Set `attempt_temp_user_creation` to `true` to have Puter automatically create
      * a temporary user, useful for onboarding without requiring sign-up.
+     *
+     * Set `request_auth` to `true` to have the popup let the user re-pick their
+     * account even when this site already holds a token for them — Puter
+     * otherwise skips that prompt for a site it has seen before.
      */
-    signIn (options?: { attempt_temp_user_creation?: boolean }): Promise<SignInResult>;
+    signIn (options?: { attempt_temp_user_creation?: boolean, request_auth?: boolean }): Promise<SignInResult>;
     /** Signs the user out of the application. */
     signOut (): void;
     /** Returns `true` if the user is signed in, `false` otherwise. */
diff --git a/src/puter-js/types/modules/filesystem.d.ts b/src/puter-js/types/modules/filesystem.d.ts
index 8c537dd717..1c55844508 100644
--- a/src/puter-js/types/modules/filesystem.d.ts
+++ b/src/puter-js/types/modules/filesystem.d.ts
@@ -106,6 +106,10 @@ export interface ReaddirOptions extends RequestCallbacks<FSItem[]> {
     sortBy?: 'name' | 'modified' | 'type' | 'size';
     /** Sort direction. Default is `asc`. */
     sortOrder?: 'asc' | 'desc';
+    /** Whether to also list the contents of subdirectories. Defaults to `false`. */
+    recursive?: boolean;
+    /** How many levels to descend when `recursive` is `true`. Defaults to unlimited. */
+    depth?: number;
 }
 
 /**
@@ -133,6 +137,12 @@ export interface StatOptions extends RequestCallbacks<FSItem> {
     consistency?: 'strong' | 'eventual';
     /** Whether to return subdomain information. Defaults to `false`. */
     returnSubdomains?: boolean;
+    /**
+     * Whether to return the workers attached to the item. Workers are served
+     * alongside subdomains, so this is an alias of `returnSubdomains` — setting
+     * either one returns both. Defaults to `false`.
+     */
+    returnWorkers?: boolean;
     /** Whether to return permission information. Defaults to `false`. */
     returnPermissions?: boolean;
     /** Whether to return version information. Defaults to `false`. */
@@ -313,10 +323,10 @@ export class FS {
      * Writes data to a file, creating it if it does not exist. Resolves to the `FSItem`
      * of the written file. If `path` is not absolute, it is resolved relative to the app's
      * root directory. A `File` may be written directly, in which case its path is derived
-     * from the file's name.
+     * from the file's name. Omitting `data` creates an empty file.
      */
     write (file: File): Promise<FSItem>;
-    write (path: string, data: string | File | Blob | ArrayBuffer | ArrayBufferView, options?: WriteOptions): Promise<FSItem>;
+    write (path: string, data?: string | File | Blob | ArrayBuffer | ArrayBufferView, options?: WriteOptions): Promise<FSItem>;
 
     sign (appUid: string, items: unknown | unknown[], success?: (result: SignResult) => void, error?: (reason: unknown) => void): Promise<SignResult>;
 
diff --git a/src/puter-js/types/modules/kv.d.ts b/src/puter-js/types/modules/kv.d.ts
index b3bbb7db5f..56c5f9cc8f 100644
--- a/src/puter-js/types/modules/kv.d.ts
+++ b/src/puter-js/types/modules/kv.d.ts
@@ -112,9 +112,17 @@ export interface KVListOptions {
     optConfig?: KVOptConfig;
 }
 
+/**
+ * The options that switch `list()` from a flat array to a `KVListPage`. Any
+ * one of them is enough — they are the same set the runtime treats as a
+ * paginated request.
+ */
 export type KVListPaginationOptions =
-    | { limit: number; cursor?: string }
-    | { cursor: string; limit?: number };
+    | { limit: number }
+    | { cursor: string }
+    | { offset: number }
+    | { includeTotal: boolean }
+    | { fetchUntilFull: boolean };
 
 /**
  * The `stream: true` form of `list()`: returns an async iterator of
diff --git a/src/puter-js/types/modules/ui.d.ts b/src/puter-js/types/modules/ui.d.ts
index a70f9aa56c..ec304ec6f8 100644
--- a/src/puter-js/types/modules/ui.d.ts
+++ b/src/puter-js/types/modules/ui.d.ts
@@ -59,6 +59,16 @@ export interface ContextMenuOptions {
      * When unset, the menu follows the system color-scheme preference.
      */
     theme?: 'dark' | 'light';
+    /**
+     * X position of the menu, in pixels. Defaults to the cursor position.
+     * Standalone only, with the same caveat as `theme`.
+     */
+    x?: number;
+    /**
+     * Y position of the menu, in pixels. Defaults to the cursor position.
+     * Standalone only, with the same caveat as `theme`.
+     */
+    y?: number;
 }
 
 /** Options that configure a window created by `createWindow()`. */