@firstpick/pi-package-webui 0.5.1 → 0.5.3

package/README.md

@@ -2,7 +2,7 @@
 
 Local browser UI for [Pi coding agent](https://www.npmjs.com/package/@earendil-works/pi-coding-agent).
 
-![Pi Web UI workspace dashboard showing the active project, model, session state, and quick actions](https://raw.githubusercontent.com/Firstp1ck/npm-packages/main/pi-package-webui/images/Webui_Workspace_v0.4.8.png)
+![Pi Web UI main window showing multi-tab chat, streaming output, footer status, composer, and side controls](https://raw.githubusercontent.com/Firstp1ck/npm-packages/main/pi-package-webui/images/Webui_MainWindow_v0.4.8.png)
 
 Pi Web UI gives you a local browser companion for Pi: multi-tab chat, streaming output, model controls, uploads, slash-command helpers, workspace navigation, and optional extension widgets.
 
@@ -119,34 +119,75 @@ PI_WEBUI_PI_BIN=/path/to/pi pi-webui --no-session
 
 Environment variables:
 
-- `PI_WEBUI_HOST`
-- `PI_WEBUI_PORT`
-- `PI_WEBUI_PI_BIN`
-- `PI_WEBUI_REMOTE_AUTH=1` to start with remote PIN authentication enabled
-- `PI_WEBUI_SETTINGS_FILE=/path/to/settings.json` to override where Web UI stores persisted settings such as the Remote PIN auth preference
+- `PI_WEBUI_HOST` and `PI_WEBUI_PORT` set the default bind address.
+- `PI_WEBUI_PI_BIN=/path/to/pi` selects the Pi executable when `--pi` is not passed.
+- `PI_WEBUI_REMOTE_AUTH=1` starts with Remote PIN authentication enabled.
+- `PI_WEBUI_SETTINGS_FILE=/path/to/settings.json` overrides persisted Web UI settings such as the Remote PIN auth preference.
+- `PI_WEBUI_OPTIONAL_FEATURE_INSTALL_ROOT=/path/to/package-root` overrides the npm prefix used for optional companion installs.
+- `PI_WEBUI_FAST_PICKS_FILE=/path/to/paths.json` overrides saved cwd fast-pick storage.
+- `PI_WEBUI_NPM_BIN=/path/to/npm` selects the npm executable used by optional feature install/update actions.
 
 ## Main features
 
 - Pathless `pi-webui` startup: the server opens first, then the browser prompts for the first terminal CWD.
-- Multi-tab Pi sessions with isolated processes, working directories, prompt drafts, activity state, and a workspace dashboard for common actions.
-- Unified command palette (`Ctrl/Cmd+K`) for commands, tabs, models, sessions, settings, and frequent Web UI actions.
+- Multi-tab Pi sessions with isolated processes, working directories, prompt drafts, activity state, per-tab settings, and a workspace dashboard for common actions.
+- Unified command palette (`Ctrl/Cmd+K`) for commands, tabs, models, sessions, settings, app controls, and frequent Web UI actions.
 - Automatic tab naming from the first prompt, with `--name <name>` still available for an explicit initial tab name.
-- Streaming chat transcript with Markdown, thinking output, tool/bash cards, queue and compaction events, edit-and-retry from user prompts, and guarded abort controls that require holding Esc or the Abort button for 3 seconds.
-- Prompt composer with uploads, drag/drop/paste, inline image support, slash-command autocomplete, and `@` file/path references with live suggestions.
-- Browser dialogs for common Pi selectors such as `/model`, `/settings`, `/theme`, `/fork`, `/clone`, `/resume`, `/tree`, `/scoped-models`, `/tools`, and `/skills`.
-- Model, thinking, session, workspace, theme, optional-feature, Codex usage, optional Remote WebUI, update/restart, event, and notification controls in the side panel.
-- Persistent context-window meter with manual compact and auto-compaction controls near the composer.
+- Streaming chat transcript with Markdown, thinking output, tool/bash cards, queue and compaction events, edit-and-retry from user prompts, transcript search, copy buttons, and guarded abort controls that require holding Esc or the Abort button for 3 seconds.
+- Prompt composer with uploads, drag/drop/paste, inline image support, generated text attachments for long input or clipboard text, editable text attachments, slash-command autocomplete, and `@` file/path references with live suggestions.
+- Leading `!` and `!!` user-bash commands from the composer, serialized per tab; `!` keeps output in the next model context and `!!` excludes it.
+- Browser-native Pi dialogs for `/model`, `/settings`, `/theme`, `/fork`, `/clone`, `/name`, `/resume`, `/tree`, `/login`, `/logout`, `/scoped-models`, `/tools`, and `/skills`, plus native-command adapter output for `/copy`, `/session`, `/new`, `/compact`, `/reload`, and `/export`.
+- Runtime `/tools` and `/skills` selectors backed by the hidden Web UI RPC helper; skill toggles persist on the session branch, disabled skills are removed from the system prompt, and tracked `SKILL.md` files can be opened/edited from skill tags.
+- Session resume/switch, metadata rename, and localhost-only safe delete with active/open-tab/session-directory guards.
+- Model, thinking, session, workspace, theme, optional-feature, Codex usage, optional Remote WebUI, update/restart/stop, event, notification, thinking-visibility, terminal-tab-layout, and custom-background controls in collapsible side-panel sections.
+- Persistent context-window meter with manual compact and auto-compaction controls near the composer; side-panel thinking changes made while a tab is busy are queued for the next prompt.
 - Side-panel theme picker backed by optional `@firstpick/pi-themes-bundle` themes when loaded.
-- Per-tab cwd changes, a clickable footer cwd picker, saved path fast picks, server-persisted fast picks, and restart-safe restoration of open tabs.
+- Per-tab cwd changes, a clickable footer cwd picker, directory creation/search in the picker, saved path fast picks, server-persisted fast picks, and restart-safe restoration of open tabs.
 - Detected app runner dropdown for the active tab cwd, including Cargo, Bun, npm/npx/pnpm, Python/uv, Go/Golang, Zig, C/C++, Docker Compose, root/dev/scripts shell scripts, and other common project runners with live output pinned at the top of the terminal. Running app runners expose line-oriented stdin in the widget for interactive scripts. Projects can add browseable custom runners in `.pi-webui-runners.json` with a command (default `./`) plus a relative path to the file to run.
+- Guided Git workflow for existing repos and new repos: initialize, create README/.gitignore, initial commit, rename to `main`, add a GitHub remote, pull fetched incoming changes, stage, generate or type commit messages, push, and optionally create a PR.
 - Browser support for Pi extension UI prompts, widgets, status updates, `/btw` side-question output widgets with optional context transfer/live steering, browser notifications when a tab needs an extension UI response, and an optional side-panel toggle for agent-done notifications.
 - Localhost-only Pi/Web UI update checks with a top-right update notification and confirmed restart actions: **Update Pi & restart** runs `pi update` for Pi-only updates, while **Update Pi + Packages & Restart** runs `pi update --all` for Pi plus configured packages.
 - Feedback reactions (`👍`, `👎`, `?`) on final assistant output plus tool/bash action cards, which can ask Pi to create or update a LEARNING.
-- Mobile-friendly layout and PWA install support where the browser allows it.
+- Mobile-friendly layout, PWA install support where the browser allows it, backend-offline recovery, and a dedicated server-restart overlay while confirmed restart/update actions run.
 
-## v0.4.8 feature gallery
+## Native Pi command coverage
 
-These screenshots show the v0.4.8 Web UI surfaces. Unless noted otherwise, actions apply to the active tab and its current working directory.
+Web UI keeps a packaged parity matrix at `dev/docs/WEBUI_TUI_NATIVE_PARITY.json` and exposes it at `GET /api/native-parity`.
+
+| Status | Commands and behavior |
+| --- | --- |
+| Implemented | `/model`, `/settings`, `/tools`, `/skills`, `/copy`, `/name`, `/session`, `/clone`, `/logout`, `/new`, `/compact`, and `/reload` use browser-native dialogs or structured native-command cards. |
+| Degraded / browser-specific | `/theme` changes the browser Web UI theme only; `/scoped-models` points to the footer scoped-model picker; `/export` supports no-path HTML downloads plus explicit new `.html`/`.jsonl` server paths; `/hotkeys` lists Web UI shortcuts; `/fork`, `/tree`, `/login`, and `/resume` have browser flows with documented gaps. |
+| Unsupported in Web UI | `/import`, `/share`, `/changelog`, and `/quit` return structured unavailable output instead of raw HTTP errors. |
+
+Sensitive native flows use shared trust-boundary guards: localhost-only APIs, trusted-context checks for LAN clients, confirmation-oriented dialogs, and session-directory confinement for session file operations.
+
+## Keyboard shortcuts
+
+| Shortcut | Action |
+| --- | --- |
+| `Ctrl/Cmd+K` | Open the command palette. |
+| `Ctrl/Cmd+L` | Open the model selector. |
+| `Ctrl/Cmd+P` / `Shift+Ctrl/Cmd+P` | Cycle scoped or available models forward/backward. |
+| `Shift+Tab` | Cycle thinking effort. |
+| `Ctrl/Cmd+T` | Toggle thinking-output visibility. |
+| `Ctrl/Cmd+O` | Toggle global expansion for tool and bash output cards. |
+| `Alt+Enter` | Queue the composer as a follow-up. |
+| `Alt+Up` | Restore the latest observed steering/follow-up queue snapshot into the composer. |
+| hold `Esc` | Abort active user bash first, then active agent work. |
+| `Ctrl/Cmd+C` in an empty, focused composer | Clear the prompt. |
+| `Ctrl/Cmd+F` | Search the transcript. |
+
+## Feature gallery (screenshots from v0.4.8)
+
+These screenshots show the v0.4.8 Web UI surfaces. Current implementations include the additional native-command, shortcut, attachment, Git, app-runner, server-control, and safety features documented above. Unless noted otherwise, actions apply to the active tab and its current working directory.
+
+### Main window
+
+![Pi Web UI main window showing multi-tab chat, streaming output, footer status, composer, and side controls](https://raw.githubusercontent.com/Firstp1ck/npm-packages/main/pi-package-webui/images/Webui_MainWindow_v0.4.8.png)
+
+- **What it is:** The primary Web UI workspace for Pi, with terminal tabs, chat transcript, live assistant output, footer metrics, prompt composer, attachments, and side-panel controls in one browser view.
+- **What you can do:** Run multiple Pi sessions, send prompts or follow-ups, monitor tokens/cache/cost/context/git/model state, attach files, launch quick actions, and control the active session without returning to the terminal.
 
 ### Workspace dashboard
 
@@ -262,12 +303,25 @@ These screenshots show the v0.4.8 Web UI surfaces. Unless noted otherwise, actio
 
 Useful browser endpoints exposed by the local server include:
 
+- `GET /api/health` and `GET /api/webui-status?detailed=1` for server health, network exposure, tabs, sessions, models/providers, update state, and recent events.
+- `GET /api/tabs`, `POST /api/tabs`, `PATCH /api/tabs/<tabId>`, and tab close/delete routes for multi-tab lifecycle management.
+- `GET /api/messages?tab=<tabId>&since=<index>` for transcript snapshots or delta refreshes.
+- `POST /api/prompt`, `POST /api/follow-up`, `POST /api/steer`, `POST /api/bash`, `POST /api/abort`, and `POST /api/abort-bash` for tab-scoped Pi interaction.
+- `POST /api/attachments` for uploaded/generated prompt attachments and inline images.
 - `GET /api/path-suggestions?tab=<tabId>&query=<path>` for `@` file/path references with live suggestions.
+- `GET /api/path-fast-picks` and `POST /api/path-fast-picks` for server-persisted cwd fast picks.
+- `GET /api/native-parity` for the packaged native TUI/Web UI parity matrix.
+- `GET /api/settings`, `POST /api/settings`, `GET /api/tools`, `POST /api/tools`, `GET /api/skills`, and `POST /api/skills` for browser-native Pi settings/tool/skill selectors.
+- `GET /api/skill-file` and localhost-only `POST /api/skill-file` for guarded `SKILL.md` editing from tracked skill tags.
+- `GET /api/sessions`, `GET /api/session-tree`, `POST /api/switch-session`, `POST /api/session-rename`, and localhost-only `POST /api/session-delete` for resume/tree/session metadata flows.
+- `GET /api/auth-providers` and localhost-only `POST /api/auth-logout` for provider-auth status and stored-credential removal.
+- `GET /api/app-runners`, `POST /api/app-runner`, `POST /api/app-runner/input`, `POST /api/app-runner/stop`, `GET/POST/DELETE /api/app-runner-config`, and `GET /api/app-runner-files` for detected and custom project runners.
+- `GET /api/git-changes`, `POST /api/git-changes/pull`, `GET /api/git-branches`, `POST /api/git-branch`, and `/api/git-workflow/*` for browser Git status, diff, branch, init, commit, push, and PR helpers.
 - `POST /api/action-feedback?tab=<tabId>` for feedback on final assistant output and action cards.
 - `GET /api/optional-features` for optional companion package install/update status.
 - `POST /api/optional-feature-install` for installing or updating known optional companion packages from the side panel.
-- `GET /api/update-status` and localhost-only `POST /api/update` for checking Pi/Web UI updates and running `pi update` followed by a Web UI server restart. Use `POST /api/update?all=1` to run `pi update --all` for Pi plus configured packages.
-- `GET /api/remote-auth`, `POST /api/remote-auth`, and localhost-only `POST /api/remote-auth/settings` for optional 4-digit PIN authentication when serving non-local browser clients.
+- `GET /api/update-status`, localhost-only `POST /api/restart`, and localhost-only `POST /api/update` for checking Pi/Web UI updates and restarting the Web UI. Use `POST /api/update?all=1` to run `pi update --all` for Pi plus configured packages.
+- `GET /api/network`, localhost-only `POST /api/network/open`, localhost-only `POST /api/network/close`, `GET /api/remote-auth`, `POST /api/remote-auth`, and localhost-only `POST /api/remote-auth/settings` for trusted-LAN exposure and optional 4-digit PIN authentication when serving non-local browser clients.
 
 For local development, run the checkout helper directly, for example:
 
@@ -301,19 +355,32 @@ Optional companions:
 
 ## Guided Git workflow
 
-The Git workflow button runs local git commands in the active Pi working directory:
+The Git workflow button runs local git commands in the active Pi working directory. It now covers both empty/new projects and existing repositories.
+
+For a new project, the browser flow can:
+
+1. Run `git init` when the active cwd is not yet a repository.
+2. Check for `README.md` and `.gitignore`.
+3. Create and stage starter `README.md`/`.gitignore` files without overwriting existing files.
+4. Create an initial commit.
+5. Rename the branch to `main`.
+6. Add a GitHub remote from a confirmed `owner/repo`.
+7. Push the initialized branch when you confirm the remote target.
+
+For an existing repository, the workflow can:
 
-1. `git add .`
-2. Send `/git-staged-msg` to Pi
-3. Read the generated commit message files from `dev/COMMIT/`
-4. Commit with the selected generated message, or type a manual message in the Message stage and use **Commit input**
-5. Run `git push`
+1. Show staged, unstaged, untracked, and fetched incoming changes.
+2. Fast-forward pull fetched incoming commits when the repository is safely behind.
+3. Run `git add .`.
+4. Send `/git-staged-msg` to Pi and read generated commit message files from `dev/COMMIT/`.
+5. Use a generated short/long message, a generated single-file default such as `updated file.txt`, or a manual **Commit input** message.
+6. Run `git push`.
 
 After the message is generated, **Create PR** asks Pi to generate `dev/COMMIT/staged-branch-name.txt`, lets you confirm or edit the `type/feature-name` branch, then switches with `git switch -c` before committing. In PR mode, choose **Commit short**, **Commit long**, or type a message and use **Commit input**, then **Push and Create PR** pushes the branch, sends `/pr`, shows the generated `dev/PR/<branch>.md` description for editing/confirmation, and creates the pull request with `gh pr create`. Use **Manual branch** to skip agent branch-name generation and type the branch directly.
 
-Use the workflow process buttons to jump directly to **Stage**, **Message**, **Commit**, or **Push** when earlier work was already completed manually. Selecting **Message** lets you either run `/git-staged-msg` or type a commit message and use **Commit input** directly. Selecting **Commit** loads the current generated files from `dev/COMMIT/` before enabling the commit choices. A yellow dot means that process was selected or is available but its action has not completed in this workflow; green means the process action completed.
+Use the workflow process buttons to jump directly to **Initialize**, **Stage**, **Message**, **Commit**, **Push**, or PR steps when earlier work was already completed manually. Selecting **Message** lets you either run `/git-staged-msg` or type a commit message and use **Commit input** directly. Selecting **Commit** loads the current generated files from `dev/COMMIT/` before enabling the commit choices. A yellow dot means that process was selected or is available but its action has not completed in this workflow; green means the process action completed.
 
-This requires `/git-staged-msg` and `/pr` from `@firstpick/pi-prompts-git-pr`; branch-name generation uses `/git-branch-name` when available and otherwise sends an equivalent inline prompt. Creating the PR also requires an authenticated GitHub CLI (`gh`). Review the generated commit message, branch name, and PR description before committing, pushing, or creating a PR.
+This requires `/git-staged-msg` and `/pr` from `@firstpick/pi-prompts-git-pr`; branch-name generation uses `/git-branch-name` when available and otherwise sends an equivalent inline prompt. Creating the PR also requires an authenticated GitHub CLI (`gh`). Review the generated commit message, branch name, remote URL, and PR description before committing, pushing, or creating a PR.
 
 ## Mobile and PWA notes
 

package/bin/pi-webui.mjs

@@ -26,6 +26,7 @@ import {
   guardsForNativeCommand,
   isLocalRequest,
   remoteShellTrustWarning,
+  requireLocalhost,
   requireLocalhostRoute,
 } from "../lib/trust-boundaries.mjs";
 import {
@@ -54,6 +55,7 @@ try {
 }
 const nativeParityMatrix = JSON.parse(await readFile(path.join(packageRoot, "dev", "docs", "WEBUI_TUI_NATIVE_PARITY.json"), "utf8"));
 const webuiDevServer = isTruthyEnv(process.env.PI_WEBUI_DEV) || isSourceCheckout(packageRoot);
+let remoteQrCorePromise = null;
 
 const DEFAULT_HOST = "127.0.0.1";
 const DEFAULT_PORT = 31415;
@@ -6977,6 +6979,45 @@ function networkStatus({ includeAuthPin = false } = {}) {
   };
 }
 
+async function loadRemoteQrCore() {
+  if (!remoteQrCorePromise) {
+    remoteQrCorePromise = (async () => {
+      const candidates = [];
+      try {
+        candidates.push(require.resolve("@firstpick/pi-package-remote-webui/lib/remote-core.mjs", { paths: [packageRoot] }));
+      } catch {
+        // Optional companion package is not installed; try the monorepo sibling below.
+      }
+      candidates.push(path.resolve(packageRoot, "..", "pi-package-remote-webui", "lib", "remote-core.mjs"));
+      let lastError;
+      for (const candidate of candidates) {
+        try {
+          await access(candidate);
+          return await import(pathToFileURL(candidate).href);
+        } catch (error) {
+          lastError = error;
+        }
+      }
+      throw lastError || new Error("Remote WebUI QR support is unavailable");
+    })();
+  }
+  return remoteQrCorePromise;
+}
+
+function networkQrDisplayUrl(network) {
+  const urls = Array.isArray(network?.networkUrls) ? network.networkUrls : [];
+  return urls.find((candidate) => typeof candidate === "string" && /^https?:\/\//i.test(candidate)) || network?.localUrl || `http://127.0.0.1:${options.port}/`;
+}
+
+async function remoteNetworkQrPayload() {
+  const network = networkStatus({ includeAuthPin: true });
+  const { generateQrLines, remoteAuthQrUrl } = await loadRemoteQrCore();
+  const displayUrl = networkQrDisplayUrl(network);
+  const qrUrl = remoteAuthQrUrl(displayUrl, network);
+  const qrLines = await generateQrLines(qrUrl);
+  return { url: displayUrl, qrUrl, qrLines, network };
+}
+
 function closeSseClientsForRebind(nextHost) {
   for (const tab of tabs.values()) {
     const rebindEvent = {
@@ -7406,6 +7447,12 @@ const server = createServer(async (req, res) => {
       return;
     }
 
+    if (url.pathname === "/api/network/qr" && req.method === "GET") {
+      requireLocalhost(req, "Remote QR generation is only allowed from localhost");
+      sendJson(res, 200, { ok: true, data: await remoteNetworkQrPayload() });
+      return;
+    }
+
     if (url.pathname === "/api/network/open" && req.method === "POST") {
       requireLocalhostRoute(req, url.pathname);
       const before = networkStatus({ includeAuthPin: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@firstpick/pi-package-webui",
-  "version": "0.5.1",
+  "version": "0.5.3",
   "description": "Pi Web UI companion package with a local browser UI CLI plus /webui-start and /webui-status commands.",
   "license": "MIT",
   "homepage": "https://github.com/Firstp1ck/npm-packages/tree/main/pi-package-webui#readme",
@@ -20,7 +20,7 @@
     "extension"
   ],
   "pi": {
-    "image": "https://unpkg.com/@firstpick/pi-package-webui/images/WebUI_v0.3.7.png",
+    "image": "https://raw.githubusercontent.com/Firstp1ck/npm-packages/main/pi-package-webui/images/Webui_MainWindow_v0.4.8.png",
     "extensions": [
       "./index.ts",
       "node_modules/@firstpick/pi-extension-btw/index.ts",

package/public/app.js

@@ -141,6 +141,13 @@ const elements = {
   remoteAuthToggle: $("#remoteAuthToggle"),
   remoteAuthStatus: $("#remoteAuthStatus"),
   openNetworkButton: $("#openNetworkButton"),
+  remoteQrDialog: $("#remoteQrDialog"),
+  remoteQrMessage: $("#remoteQrMessage"),
+  remoteQrBody: $("#remoteQrBody"),
+  remoteQrCopyButton: $("#remoteQrCopyButton"),
+  remoteQrOpenButton: $("#remoteQrOpenButton"),
+  remoteQrCloseButton: $("#remoteQrCloseButton"),
+  remoteQrCloseMenuButton: $("#remoteQrCloseMenuButton"),
   serverActionSelect: $("#serverActionSelect"),
   runServerActionButton: $("#runServerActionButton"),
   serverActionStatus: $("#serverActionStatus"),
@@ -322,6 +329,9 @@ let btwWidgetInputDraft = "";
 let btwWidgetFocusAfterRender = false;
 let latestWorkspace = null;
 let latestNetwork = null;
+let latestRemoteWebuiQrUrl = "";
+let remoteQrAutoPopupShown = false;
+let networkStatusLoaded = false;
 let webuiVersion = "";
 let webuiDevServer = false;
 let latestCodexUsage = null;
@@ -4660,7 +4670,7 @@ function restoreActiveDraft() {
 
 function focusPromptInput({ defer = false } = {}) {
   const focus = () => {
-    if (!elements.promptInput || elements.dialog.open || elements.pathPickerDialog.open || elements.gitChangesDialog?.open || elements.commandPaletteDialog?.open || elements.editRetryDialog?.open || elements.nativeCommandDialog.open || elements.appRunnerInfoDialog?.open || elements.promptListDialog?.open || elements.attachmentTextDialog?.open || elements.skillEditorDialog?.open || document.visibilityState === "hidden") return;
+    if (!elements.promptInput || elements.dialog.open || elements.pathPickerDialog.open || elements.gitChangesDialog?.open || elements.commandPaletteDialog?.open || elements.editRetryDialog?.open || elements.nativeCommandDialog.open || elements.remoteQrDialog?.open || elements.appRunnerInfoDialog?.open || elements.promptListDialog?.open || elements.attachmentTextDialog?.open || elements.skillEditorDialog?.open || document.visibilityState === "hidden") return;
     try {
       elements.promptInput.focus({ preventScroll: true });
     } catch {
@@ -10440,6 +10450,289 @@ function remoteWebuiWidgetLines(lines = []) {
     .filter((line, index, array) => line.trim() || (index > 0 && index < array.length - 1));
 }
 
+function remoteWebuiLineUrl(line) {
+  const text = String(line || "").trim();
+  const match = text.match(/https?:\/\/[^\s<>"']+/i);
+  if (!match) return "";
+  const candidate = match[0].replace(/[),.;]+$/, "");
+  return safeHttpUrl(candidate);
+}
+
+function remoteWebuiQrPayload(lines = []) {
+  const cleanLines = remoteWebuiWidgetLines(lines);
+  const url = remoteWebuiLineUrl(cleanLines.find((line) => remoteWebuiLineUrl(line)) || "");
+  const scanIndex = cleanLines.findIndex((line) => /scan with your phone/i.test(line));
+  const urlIndex = cleanLines.findIndex((line, index) => index > scanIndex && remoteWebuiLineUrl(line));
+  const qrStart = scanIndex >= 0 ? scanIndex + 1 : -1;
+  const qrEnd = urlIndex >= 0 ? urlIndex : cleanLines.length;
+  const qrLines = qrStart >= 0
+    ? cleanLines.slice(qrStart, qrEnd).filter((line, index, array) => line.trim() || (index > 0 && index < array.length - 1))
+    : [];
+  const detailLines = cleanLines.filter((line, index) => {
+    if (!line.trim()) return false;
+    if (/^Pi Remote WebUI$/i.test(line.trim())) return false;
+    if (/scan with your phone/i.test(line)) return false;
+    if (qrStart >= 0 && index >= qrStart && index < qrEnd) return false;
+    return true;
+  });
+  return { cleanLines, detailLines, qrLines, url };
+}
+
+function remoteWebuiQrMatrix(qrLines = []) {
+  const lines = qrLines.map((line) => String(line ?? "")).filter((line) => /[█▀▄]/u.test(line));
+  if (!lines.length) return null;
+  const width = Math.max(...lines.map((line) => Array.from(line).length));
+  if (!Number.isFinite(width) || width <= 0) return null;
+
+  const matrix = [];
+  for (const line of lines) {
+    const chars = Array.from(line);
+    while (chars.length < width) chars.push(" ");
+    const top = [];
+    const bottom = [];
+    for (const char of chars) {
+      if (char === "█") {
+        top.push(false);
+        bottom.push(false);
+      } else if (char === "▀") {
+        top.push(false);
+        bottom.push(true);
+      } else if (char === "▄") {
+        top.push(true);
+        bottom.push(false);
+      } else {
+        top.push(true);
+        bottom.push(true);
+      }
+    }
+    matrix.push(top, bottom);
+  }
+
+  while (matrix.length > width && matrix[0]?.every(Boolean)) matrix.shift();
+  while (matrix.length > width && matrix.at(-1)?.every(Boolean)) matrix.pop();
+  if (matrix.length !== width || matrix.some((row) => row.length !== width)) return null;
+  if (!matrix.some((row) => row.some(Boolean))) return null;
+  return matrix;
+}
+
+function remoteWebuiQrSvg(qrLines = []) {
+  const matrix = remoteWebuiQrMatrix(qrLines);
+  if (!matrix) return null;
+  const size = matrix.length;
+  const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+  svg.setAttribute("class", "remote-qr-svg");
+  svg.setAttribute("viewBox", `0 0 ${size} ${size}`);
+  svg.setAttribute("role", "img");
+  svg.setAttribute("aria-label", "/remote QR code");
+  svg.setAttribute("shape-rendering", "crispEdges");
+  svg.setAttribute("focusable", "false");
+
+  const background = document.createElementNS(svg.namespaceURI, "rect");
+  background.setAttribute("class", "remote-qr-svg-bg");
+  background.setAttribute("width", String(size));
+  background.setAttribute("height", String(size));
+  svg.append(background);
+
+  for (let y = 0; y < size; y++) {
+    for (let x = 0; x < size; x++) {
+      if (!matrix[y][x]) continue;
+      const rect = document.createElementNS(svg.namespaceURI, "rect");
+      rect.setAttribute("class", "remote-qr-svg-dark");
+      rect.setAttribute("x", String(x));
+      rect.setAttribute("y", String(y));
+      rect.setAttribute("width", "1");
+      rect.setAttribute("height", "1");
+      svg.append(rect);
+    }
+  }
+  return svg;
+}
+
+function closeRemoteWebuiQrPopup() {
+  latestRemoteWebuiQrUrl = "";
+  elements.remoteQrDialog?.classList.remove("is-loading");
+  if (elements.remoteQrDialog?.open) elements.remoteQrDialog.close();
+}
+
+function openRemoteWebuiQrUrl() {
+  const url = latestRemoteWebuiQrUrl;
+  if (!url) return;
+  const anchor = document.createElement("a");
+  anchor.href = url;
+  anchor.target = "_blank";
+  anchor.rel = "noopener noreferrer";
+  anchor.hidden = true;
+  document.body.append(anchor);
+  anchor.click();
+  anchor.remove();
+  addEvent("opened /remote URL", "info");
+}
+
+async function copyRemoteWebuiQrUrl() {
+  if (!latestRemoteWebuiQrUrl) return;
+  try {
+    await copyText(latestRemoteWebuiQrUrl);
+    addEvent("copied /remote URL", "info");
+  } catch (error) {
+    addEvent(`copy /remote URL failed: ${error.message || String(error)}`, "error");
+  }
+}
+
+function isLocalWebuiBrowserOrigin() {
+  const host = window.location.hostname.toLowerCase();
+  return host === "localhost" || host === "127.0.0.1" || host === "::1" || host === "[::1]";
+}
+
+function remoteWebuiQrLinesFromData(data = {}) {
+  const network = data.network || latestNetwork || {};
+  const auth = network.auth || {};
+  const networkUrls = Array.isArray(network.networkUrls) ? network.networkUrls : [];
+  const displayUrl = data.url || networkUrls.find((candidate) => /^https?:\/\//i.test(String(candidate || ""))) || network.localUrl || "";
+  const qrLines = Array.isArray(data.qrLines) ? data.qrLines.map((line) => String(line ?? "")) : [];
+  const hasAutoAuthQr = !!(auth.enabled && auth.pin && data.qrUrl && displayUrl && data.qrUrl !== displayUrl);
+  const authLine = auth.enabled ? `Remote PIN auth: on${auth.pin ? ` · PIN ${auth.pin}` : ""}` : "Remote PIN auth: off";
+  const warningLine = hasAutoAuthQr
+    ? "Trusted LAN only. The QR signs in with the embedded PIN; keep it private."
+    : auth.enabled
+      ? "Trusted LAN only. Anyone with this URL and PIN can control Pi/WebUI."
+      : "Trusted LAN only. Remote PIN auth is off; anyone with this URL can control Pi/WebUI.";
+  return [
+    "Pi Remote WebUI",
+    "",
+    hasAutoAuthQr ? "Scan with your phone (auto-auth QR):" : "Scan with your phone:",
+    "",
+    ...qrLines,
+    "",
+    displayUrl,
+    authLine,
+    "",
+    warningLine,
+    "Close LAN access with: /remote close",
+  ];
+}
+
+function showRemoteWebuiQrLoadingPopup(message = "Opening Remote WebUI QR…") {
+  if (!elements.remoteQrDialog || !elements.remoteQrBody) return;
+  latestRemoteWebuiQrUrl = "";
+  elements.remoteQrDialog.classList.add("is-loading");
+
+  const loading = make("div", "remote-qr-loading");
+  loading.setAttribute("role", "status");
+  loading.setAttribute("aria-live", "polite");
+  const spinner = make("div", "remote-qr-spinner");
+  spinner.setAttribute("aria-hidden", "true");
+  const copy = make("div", "remote-qr-loading-copy");
+  copy.append(
+    make("strong", "", message),
+    make("span", "muted", "Starting /remote and generating a QR code. This can take a moment."),
+  );
+  loading.append(spinner, copy);
+
+  elements.remoteQrBody.replaceChildren(loading);
+  if (elements.remoteQrMessage) elements.remoteQrMessage.textContent = "Preparing trusted-LAN browser access…";
+  if (elements.remoteQrCopyButton) elements.remoteQrCopyButton.disabled = true;
+  if (elements.remoteQrOpenButton) elements.remoteQrOpenButton.disabled = true;
+
+  try {
+    if (!elements.remoteQrDialog.open) elements.remoteQrDialog.showModal();
+  } catch (error) {
+    addEvent(`remote QR loading popup unavailable: ${error.message || String(error)}`, "warn");
+  }
+}
+
+function isRemoteWebuiQrPopupLoading() {
+  return !!elements.remoteQrDialog?.classList.contains("is-loading");
+}
+
+function remoteWebuiStatusLoadingMessage(statusText) {
+  const text = String(statusText || "").toLowerCase();
+  if (text.includes("refresh")) return "Refreshing Remote WebUI QR…";
+  if (text.includes("pin auth")) return "Preparing Remote PIN auth and QR…";
+  return "Opening Remote WebUI QR…";
+}
+
+function handleRemoteWebuiStatus(statusText) {
+  const text = String(statusText || "").toLowerCase();
+  if (text.includes("opening remote webui") || text.includes("refreshing remote qr") || text.includes("enabling remote pin auth")) {
+    showRemoteWebuiQrLoadingPopup(remoteWebuiStatusLoadingMessage(statusText));
+    return;
+  }
+  if (text.includes("closing remote webui")) {
+    closeRemoteWebuiQrPopup();
+    return;
+  }
+  if (!statusText && isRemoteWebuiQrPopupLoading()) closeRemoteWebuiQrPopup();
+}
+
+async function showRemoteWebuiQrPopupFromNetwork({ auto = false } = {}) {
+  if (auto) remoteQrAutoPopupShown = true;
+  showRemoteWebuiQrLoadingPopup("Preparing Remote WebUI QR…");
+  try {
+    const response = await api("/api/network/qr", { scoped: false });
+    openRemoteWebuiQrPopup(remoteWebuiQrLinesFromData(response.data || {}));
+    return true;
+  } catch (error) {
+    if (isRemoteWebuiQrPopupLoading()) closeRemoteWebuiQrPopup();
+    addEvent(`remote QR popup failed: ${error.message || String(error)}`, auto ? "warn" : "error");
+    return false;
+  }
+}
+
+function openRemoteWebuiQrPopup(lines = []) {
+  if (!elements.remoteQrDialog || !elements.remoteQrBody) return;
+  const { cleanLines, detailLines, qrLines, url } = remoteWebuiQrPayload(lines);
+  latestRemoteWebuiQrUrl = url;
+  elements.remoteQrDialog.classList.remove("is-loading");
+
+  const qrText = (qrLines.length ? qrLines : cleanLines).join("\n").trimEnd();
+  const card = make("div", "remote-qr-card");
+  const svgQr = remoteWebuiQrSvg(qrLines);
+  if (svgQr) {
+    card.append(svgQr);
+  } else {
+    const code = make("pre", "remote-qr-code", qrText || "QR code unavailable.");
+    code.setAttribute("aria-label", "/remote QR code");
+    card.append(code);
+  }
+
+  const details = make("div", "remote-qr-details");
+  if (url) {
+    const urlRow = make("div", "remote-qr-url-row");
+    const urlLabel = make("span", "remote-qr-url-label", "URL");
+    const link = make("a", "remote-qr-url", url);
+    link.href = url;
+    link.target = "_blank";
+    link.rel = "noopener noreferrer";
+    urlRow.append(urlLabel, link);
+    details.append(urlRow);
+  }
+  for (const line of detailLines.filter((line) => !remoteWebuiLineUrl(line))) {
+    details.append(make("p", "remote-qr-note", line));
+  }
+  if (!details.childElementCount) details.append(make("p", "remote-qr-note muted", "Scan from a trusted device on the same local network."));
+
+  elements.remoteQrBody.replaceChildren(card, details);
+  if (elements.remoteQrMessage) {
+    elements.remoteQrMessage.textContent = url
+      ? "Scan this /remote QR code from a trusted local-network device."
+      : "The /remote QR output is ready. Use the transcript if this terminal QR cannot be scanned.";
+  }
+  if (elements.remoteQrCopyButton) elements.remoteQrCopyButton.disabled = !url;
+  if (elements.remoteQrOpenButton) elements.remoteQrOpenButton.disabled = !url;
+
+  try {
+    if (!elements.remoteQrDialog.open) elements.remoteQrDialog.showModal();
+  } catch (error) {
+    addEvent(`remote QR popup unavailable; see /remote output in transcript: ${error.message || String(error)}`, "warn");
+  }
+}
+
+function showRemoteWebuiQrPopup(widgetKey, lines = [], request = {}) {
+  if (widgetKey !== "pi-remote-webui" || !Array.isArray(lines)) return;
+  remoteQrAutoPopupShown = true;
+  openRemoteWebuiQrPopup(lines);
+}
+
 function mirrorRemoteWebuiWidgetToTranscript(widgetKey, lines = [], request = {}) {
   if (widgetKey !== "pi-remote-webui" || request.replayed) return;
   const content = remoteWebuiWidgetLines(lines).join("\n").trimEnd();
@@ -16719,6 +17012,8 @@ function renderNetworkStatus() {
 }
 
 async function refreshNetworkStatus() {
+  const hadNetworkStatus = networkStatusLoaded;
+  const wasOpen = !!latestNetwork?.open;
   try {
     const response = await api("/api/network", { scoped: false });
     latestNetwork = response.data || null;
@@ -16727,6 +17022,22 @@ async function refreshNetworkStatus() {
     latestNetwork = health.network || { open: false, opening: false, localUrl: window.location.origin };
   }
   renderNetworkStatus();
+  networkStatusLoaded = true;
+
+  const open = !!latestNetwork?.open;
+  if (!open) {
+    remoteQrAutoPopupShown = false;
+    return;
+  }
+
+  if (!hadNetworkStatus) {
+    remoteQrAutoPopupShown = true;
+    return;
+  }
+
+  if (!wasOpen && !remoteQrAutoPopupShown && isLocalWebuiBrowserOrigin()) {
+    showRemoteWebuiQrPopupFromNetwork({ auto: true }).catch((error) => addEvent(error.message || String(error), "warn"));
+  }
 }
 
 async function runRemoteWebuiCommand(command) {
@@ -18145,6 +18456,7 @@ function handleExtensionUiRequest(request) {
       }
       if (statusKey === STATS_WEBUI_STATUS_KEY) handleStatsWebuiStatus(request.statusText);
       if (statusKey === BTW_WEBUI_STATUS_KEY) handleBtwWebuiStatus(request.statusText);
+      if (statusKey === "pi-remote-webui") handleRemoteWebuiStatus(request.statusText);
       updateOptionalFeatureAvailability();
       if (statusKey === GIT_FOOTER_WEBUI_STATUS_KEY) {
         if (currentState?.isStreaming || runIndicatorLocallyActive) return;
@@ -18162,7 +18474,12 @@ function handleExtensionUiRequest(request) {
       const widgetKey = request.widgetKey || request.id;
       if (widgetKey === "pi-remote-webui") {
         widgets.delete(widgetKey);
-        if (Array.isArray(request.widgetLines)) mirrorRemoteWebuiWidgetToTranscript(widgetKey, request.widgetLines, request);
+        if (Array.isArray(request.widgetLines)) {
+          mirrorRemoteWebuiWidgetToTranscript(widgetKey, request.widgetLines, request);
+          showRemoteWebuiQrPopup(widgetKey, request.widgetLines, request);
+        } else {
+          closeRemoteWebuiQrPopup();
+        }
       } else if (Array.isArray(request.widgetLines)) {
         widgets.set(widgetKey, request);
       } else {
@@ -18185,6 +18502,7 @@ function handleExtensionUiRequest(request) {
     case "confirm":
     case "input":
     case "editor":
+      if (isRemoteWebuiQrPopupLoading()) closeRemoteWebuiQrPopup();
       if (hasQueuedDialogRequest(request.id)) return;
       if (request.pendingExtensionUiRequestCount === undefined) {
         const tab = tabs.find((item) => item.id === request.tabId);
@@ -19290,6 +19608,14 @@ if (elements.backgroundClearButton) {
 }
 elements.remoteAuthToggle.addEventListener("change", () => toggleRemoteAuth().catch((error) => addEvent(error.message || String(error), "error")));
 elements.openNetworkButton.addEventListener("click", openToNetwork);
+elements.remoteQrCopyButton?.addEventListener("click", () => copyRemoteWebuiQrUrl().catch((error) => addEvent(error.message || String(error), "error")));
+elements.remoteQrOpenButton?.addEventListener("click", openRemoteWebuiQrUrl);
+elements.remoteQrCloseButton?.addEventListener("click", closeRemoteWebuiQrPopup);
+elements.remoteQrCloseMenuButton?.addEventListener("click", closeRemoteWebuiQrPopup);
+elements.remoteQrDialog?.addEventListener("close", () => {
+  latestRemoteWebuiQrUrl = "";
+  elements.remoteQrDialog?.classList.remove("is-loading");
+});
 elements.serverActionSelect.addEventListener("change", updateServerActionButton);
 elements.runServerActionButton.addEventListener("click", () => runSelectedServerAction().catch((error) => addEvent(error.message || String(error), "error")));
 elements.updateNotificationUpdateButton?.addEventListener("click", () => runPiUpdateAndRestart().catch((error) => addEvent(error.message || String(error), "error")));

package/public/index.html

@@ -12,7 +12,7 @@
     <link rel="manifest" href="/manifest.webmanifest" />
     <link rel="icon" type="image/svg+xml" href="/favicon.svg" />
     <link rel="apple-touch-icon" href="/apple-touch-icon.png" />
-    <link rel="stylesheet" href="/styles.css?v=54" />
+    <link rel="stylesheet" href="/styles.css?v=56" />
   </head>
   <body>
     <button id="sidePanelExpandButton" class="side-panel-expand-button" type="button" aria-controls="sidePanel" aria-expanded="false" aria-label="Expand side panel" title="Expand side panel">
@@ -645,6 +645,25 @@
       </form>
     </dialog>
 
+    <dialog id="remoteQrDialog" class="extension-dialog remote-qr-dialog">
+      <form method="dialog">
+        <div class="remote-qr-header">
+          <div>
+            <span class="remote-qr-kicker">/remote</span>
+            <h2>Remote WebUI QR</h2>
+            <p id="remoteQrMessage" class="muted">Scan this QR code from a trusted local-network device.</p>
+          </div>
+          <button id="remoteQrCloseButton" class="remote-qr-close-button" type="button" aria-label="Close Remote WebUI QR popup">Close</button>
+        </div>
+        <div id="remoteQrBody" class="remote-qr-body"></div>
+        <menu>
+          <button id="remoteQrCopyButton" type="button" disabled>Copy URL</button>
+          <button id="remoteQrOpenButton" type="button" disabled>Open URL</button>
+          <button id="remoteQrCloseMenuButton" class="primary" type="button">Done</button>
+        </menu>
+      </form>
+    </dialog>
+
     <dialog id="nativeCommandDialog" class="extension-dialog native-command-dialog">
       <form method="dialog">
         <h2 id="nativeCommandTitle">Pi command</h2>
@@ -721,6 +740,6 @@
       </form>
     </dialog>
 
-    <script type="module" src="/app.js?v=52"></script>
+    <script type="module" src="/app.js?v=55"></script>
   </body>
 </html>

package/public/styles.css

@@ -5626,6 +5626,161 @@ button.composer-skill-tag:focus-visible {
   padding: 0;
   margin: 1rem 0 0;
 }
+.extension-dialog.remote-qr-dialog {
+  width: min(34rem, calc(100vw - 2rem));
+  border-color: rgba(148, 226, 213, 0.44);
+  box-shadow: 0 2rem 5rem var(--shadow), 0 0 2rem rgba(148, 226, 213, 0.18);
+}
+.remote-qr-dialog form {
+  display: grid;
+  gap: 0.85rem;
+}
+.remote-qr-header {
+  display: flex;
+  align-items: flex-start;
+  justify-content: space-between;
+  gap: 1rem;
+}
+.remote-qr-kicker {
+  display: block;
+  color: var(--ctp-teal);
+  font-size: 0.72rem;
+  font-weight: 900;
+  letter-spacing: 0.12em;
+  text-transform: uppercase;
+}
+.remote-qr-header h2 {
+  margin: 0.12rem 0 0;
+  color: var(--ctp-text);
+}
+.remote-qr-header p {
+  margin: 0.28rem 0 0;
+  line-height: 1.45;
+}
+.remote-qr-close-button {
+  min-height: 34px;
+  padding: 0.32rem 0.62rem;
+  color: var(--ctp-teal);
+  border-color: rgba(148, 226, 213, 0.34);
+}
+.remote-qr-body {
+  display: grid;
+  gap: 0.75rem;
+  min-width: 0;
+}
+.remote-qr-loading {
+  display: flex;
+  align-items: center;
+  gap: 0.9rem;
+  padding: 1rem;
+  border: 1px solid rgba(148, 226, 213, 0.26);
+  border-radius: 0.9rem;
+  background: rgba(var(--ctp-crust-rgb), 0.74);
+  box-shadow: inset 0 1px 0 rgba(255,255,255,0.04), 0 0 1rem rgba(148, 226, 213, 0.08);
+}
+.remote-qr-spinner {
+  flex: 0 0 auto;
+  width: 2.25rem;
+  height: 2.25rem;
+  border: 0.22rem solid rgba(148, 226, 213, 0.18);
+  border-top-color: var(--ctp-teal);
+  border-radius: 999px;
+  animation: remote-qr-spinner-spin 900ms linear infinite;
+}
+.remote-qr-loading-copy {
+  display: grid;
+  gap: 0.26rem;
+  min-width: 0;
+  line-height: 1.45;
+}
+.remote-qr-loading-copy strong {
+  color: var(--ctp-text);
+  font-size: 0.95rem;
+}
+.remote-qr-loading-copy span {
+  font-size: 0.78rem;
+  font-weight: 700;
+}
+@keyframes remote-qr-spinner-spin {
+  to { transform: rotate(360deg); }
+}
+.remote-qr-card {
+  display: flex;
+  justify-content: center;
+  align-items: center;
+  max-width: 100%;
+  padding: 0.8rem;
+  overflow: auto;
+  border: 1px solid rgba(148, 226, 213, 0.22);
+  border-radius: 0.9rem;
+  background: rgba(var(--ctp-crust-rgb), 0.74);
+  box-shadow: inset 0 1px 0 rgba(255,255,255,0.04), 0 0 1rem rgba(148, 226, 213, 0.08);
+}
+.remote-qr-svg {
+  display: block;
+  width: min(100%, 15.5rem);
+  height: auto;
+  aspect-ratio: 1 / 1;
+  overflow: visible;
+  border-radius: 0.12rem;
+  background: #cdd6f4;
+}
+.remote-qr-svg-bg { fill: #cdd6f4; }
+.remote-qr-svg-dark { fill: #1e2030; }
+.remote-qr-code {
+  min-width: max-content;
+  margin: 0;
+  color: var(--ctp-text);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  font-size: clamp(0.38rem, 1.25vw, 0.72rem);
+  font-weight: 900;
+  line-height: 1;
+  letter-spacing: 0;
+  text-align: center;
+  white-space: pre;
+}
+.remote-qr-details {
+  display: grid;
+  gap: 0.42rem;
+}
+.remote-qr-url-row {
+  display: grid;
+  grid-template-columns: 3rem minmax(0, 1fr);
+  gap: 0.5rem;
+  align-items: start;
+  padding: 0.58rem 0.64rem;
+  border: 1px solid rgba(180, 190, 254, 0.16);
+  border-radius: 0.72rem;
+  background: rgba(var(--ctp-surface-rgb), 0.34);
+}
+.remote-qr-url-label {
+  color: rgba(var(--ctp-subtext-rgb), 0.72);
+  font-size: 0.68rem;
+  font-weight: 900;
+  letter-spacing: 0.08em;
+  text-transform: uppercase;
+}
+.remote-qr-url {
+  min-width: 0;
+  color: var(--ctp-teal);
+  font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", monospace;
+  font-size: 0.8rem;
+  font-weight: 800;
+  overflow-wrap: anywhere;
+  text-decoration: none;
+}
+.remote-qr-url:hover,
+.remote-qr-url:focus-visible {
+  color: var(--ctp-sky);
+  text-decoration: underline;
+}
+.remote-qr-note {
+  margin: 0;
+  color: rgba(var(--ctp-subtext-rgb), 0.74);
+  font-size: 0.78rem;
+  font-weight: 700;
+  line-height: 1.45;
+}
 .extension-dialog.stats-overlay-dialog {
   width: min(92rem, calc(100vw - 1.5rem));
   height: min(54rem, calc(var(--visual-viewport-height, 100dvh) - 1.5rem));
@@ -7416,6 +7571,12 @@ button.composer-skill-tag:focus-visible {
     background: linear-gradient(180deg, transparent, rgba(var(--ctp-crust-rgb), 0.96) 35%);
   }
   .extension-dialog menu button { flex: 1 1 9rem; }
+  .remote-qr-header {
+    flex-direction: column;
+    gap: 0.6rem;
+  }
+  .remote-qr-close-button { width: 100%; }
+  .remote-qr-code { font-size: clamp(0.34rem, 1.55vw, 0.62rem); }
   .extension-dialog.git-changes-dialog {
     inset: 0;
     margin: auto;

package/tests/http-endpoints-harness.test.mjs

@@ -407,6 +407,13 @@ try {
   assert.equal(traversalDelete.status, 403, "session delete outside the session dir must return 403");
   assert.match(String(traversalDelete.body?.error || ""), /session directory/i);
 
+  const networkQr = await request("127.0.0.1", "/api/network/qr");
+  assert.equal(networkQr.status, 200, "localhost can generate a /remote QR payload");
+  assert.equal(networkQr.body?.ok, true);
+  assert.match(String(networkQr.body?.data?.url || ""), /^http:\/\//, "remote QR payload should include a display URL");
+  assert.ok(Array.isArray(networkQr.body?.data?.qrLines), "remote QR payload should include terminal QR lines");
+  assert.equal(networkQr.body?.data?.network?.open, true, "remote QR payload should describe current network state");
+
   const initialAuth = await request("127.0.0.1", "/api/remote-auth");
   assert.equal(initialAuth.status, 200);
   assert.equal(initialAuth.body?.data?.auth?.enabled, false, "remote PIN auth should be off by default");
@@ -432,6 +439,9 @@ try {
     const remoteClose = await request(lan, "/api/network/close", { method: "POST" });
     assert.equal(remoteClose.status, 403, "network close must be localhost-only");
 
+    const remoteQr = await request(lan, "/api/network/qr");
+    assert.equal(remoteQr.status, 403, "remote QR generation must be localhost-only because it can embed the PIN");
+
     const enableAuth = await request("127.0.0.1", "/api/remote-auth/settings", { method: "POST", body: { enabled: true } });
     assert.equal(enableAuth.status, 200, "localhost can enable remote PIN auth");
     const pin = enableAuth.body?.data?.auth?.pin;

package/tests/mobile-static.test.mjs

@@ -68,6 +68,7 @@ assert.match(html, /id="terminalTabsLayoutSelect"[\s\S]*<option value="left">Lef
 assert.match(html, /id="terminalTabsLayoutStatus"/, "terminal-tabs layout selector should expose status text");
 assert.match(html, /id="nativeCommandDialog"/, "native slash selector UI should have a dedicated dialog");
 assert.match(html, /id="nativeCommandSearch"[^>]*type="search"/, "native slash selector dialog should expose a filter box");
+assert.match(html, /id="remoteQrDialog"[\s\S]*id="remoteQrBody"[\s\S]*id="remoteQrCopyButton"/, "remote WebUI should expose a dedicated QR popup dialog");
 assert.match(html, /id="commandPaletteCloseButton"[^>]*aria-label="Close command palette"[^>]*>Close<\/button>/, "command palette should expose a visible accessible close button");
 assert.match(html, /id="pathPickerCreateNameInput"[^>]*placeholder="New directory name"/, "cwd picker should expose a new-directory name input");
 assert.match(html, /id="pathPickerCreateButton"[^>]*>Create directory<\/button>/, "cwd picker should expose a create-directory action");
@@ -207,9 +208,14 @@ assert.match(css, /\.composer-busy-mode-menu \{[\s\S]*?bottom:\s*calc\(100% \+ 0
 assert.match(css, /\.sticky-user-prompt-button \{[\s\S]*?grid-template-columns:\s*auto minmax\(0, 1fr\) auto/, "last-user-prompt jump control should render as a fixed transcript header");
 assert.match(css, /@media \(max-width: 720px\), \(max-device-width: 720px\), \(pointer: coarse\) and \(hover: none\)[\s\S]*?\.sticky-user-prompt-button \{\n\s+grid-template-columns:\s*minmax\(0, 1fr\) auto;\n\s+min-height:\s*36px;[\s\S]*?\.sticky-user-prompt-text \{[\s\S]*?font-size:\s*0\.72rem/, "mobile last-user-prompt card should use compact height and text");
 assert.match(css, /\.message\.extension,[\s\S]*?\.message\.native/, "extension and native command output should have visible transcript styling");
-assert.match(app, /function mirrorRemoteWebuiWidgetToTranscript\(widgetKey, lines = \[\], request = \{\}\)[\s\S]*?widgetKey !== "pi-remote-webui"[\s\S]*?addTransientMessage\(\{ role: "extension", title: "\/remote"/, "remote WebUI QR widget events should mirror into the active tab transcript");
-assert.match(app, /if \(widgetKey === "pi-remote-webui"\) \{[\s\S]*?widgets\.delete\(widgetKey\);[\s\S]*?mirrorRemoteWebuiWidgetToTranscript/, "remote WebUI QR widget events should not render a Web UI overlay widget");
-assert.doesNotMatch(app, /function renderRemoteWebuiWidget/, "remote WebUI QR should only render in the transcript");
+assert.match(app, /function remoteWebuiQrSvg\(qrLines = \[\]\)[\s\S]*?viewBox[\s\S]*?shape-rendering[\s\S]*?crispEdges/, "remote WebUI QR popup should render terminal QR output as square SVG modules");
+assert.match(app, /function showRemoteWebuiQrLoadingPopup\(message = "Opening Remote WebUI QR…"\)[\s\S]*?remote-qr-loading[\s\S]*?showModal\(\)/, "remote WebUI QR popup should show a loading state while QR generation is pending");
+assert.match(app, /function handleRemoteWebuiStatus\(statusText\)[\s\S]*?opening remote webui[\s\S]*?refreshing remote qr[\s\S]*?enabling remote pin auth[\s\S]*?showRemoteWebuiQrLoadingPopup/, "remote WebUI status updates should open the QR loading popup before widget lines arrive");
+assert.match(app, /case "confirm":[\s\S]*?if \(isRemoteWebuiQrPopupLoading\(\)\) closeRemoteWebuiQrPopup\(\)/, "blocking extension dialogs should close the QR loading popup before opening");
+assert.match(app, /function showRemoteWebuiQrPopup\(widgetKey, lines = \[\], request = \{\}\)[\s\S]*?widgetKey !== "pi-remote-webui"[\s\S]*?openRemoteWebuiQrPopup\(lines\)/, "remote WebUI QR widget events should open the QR popup");
+assert.match(app, /function mirrorRemoteWebuiWidgetToTranscript\(widgetKey, lines = \[\], request = \{\}\)[\s\S]*?widgetKey !== "pi-remote-webui"[\s\S]*?addTransientMessage\(\{ role: "extension", title: "\/remote"/, "remote WebUI QR widget events should still mirror into the active tab transcript");
+assert.match(app, /if \(widgetKey === "pi-remote-webui"\) \{[\s\S]*?widgets\.delete\(widgetKey\);[\s\S]*?showRemoteWebuiQrPopup\(widgetKey, request\.widgetLines, request\)/, "remote WebUI QR widget events should not render in the generic widget area");
+assert.doesNotMatch(app, /function renderRemoteWebuiWidget/, "remote WebUI QR should not render through the generic widget renderer");
 assert.match(css, /\.message\.run-indicator-message \{[\s\S]*?border-color/, "active agent runs should render a visible transcript indicator card");
 assert.match(css, /\.message-copy-button \{[\s\S]*?position:\s*absolute/, "transcript messages should expose a top-right copy button");
 assert.match(css, /\.message\.has-copy-action[\s\S]*?padding-right:\s*3\.1rem/, "copy buttons should reserve space in message cards");
@@ -390,6 +396,11 @@ assert.match(css, /\.extension-dialog[\s\S]*?max-height:\s*calc\(var\(--visual-v
 assert.match(css, /\.extension-dialog[\s\S]*?inset:\s*auto 0 0 0/, "mobile dialogs should behave like bottom sheets");
 assert.match(css, /#dialogMessage \{[\s\S]*?white-space:\s*pre-wrap/, "extension dialog messages should preserve multiline prompts");
 assert.match(css, /\.native-command-dialog \{[\s\S]*?width:\s*min\(56rem/, "native slash selector dialog should have roomy desktop layout");
+assert.match(css, /\.extension-dialog\.remote-qr-dialog \{[\s\S]*?width:\s*min\(34rem/, "remote QR popup should have a bounded modal layout");
+assert.match(css, /\.remote-qr-loading \{[\s\S]*?display:\s*flex/, "remote QR popup should style its loading placeholder");
+assert.match(css, /\.remote-qr-spinner \{[\s\S]*?animation:\s*remote-qr-spinner-spin 900ms linear infinite/, "remote QR popup loading state should include a spinner animation");
+assert.match(css, /\.remote-qr-svg \{[\s\S]*?aspect-ratio:\s*1 \/ 1/, "remote QR popup should render QR modules as a square image");
+assert.match(css, /\.remote-qr-code \{[\s\S]*?white-space:\s*pre/, "remote QR popup should preserve terminal QR whitespace as fallback");
 assert.doesNotMatch(css, /--tree-depth/, "native slash selector choices should not indent tree entries by depth");
 assert.match(css, /\.native-selector-index \{[\s\S]*?font-variant-numeric:\s*tabular-nums/, "native tree selector choices should use numeric prefixes");
 assert.match(css, /\.native-selector-badge\.native-selector-badge-pi-native[\s\S]*?color:\s*var\(--ctp-blue\)/, "Tools Setup should distinguish Pi native tools with a Pi Native tag");
@@ -439,6 +450,8 @@ assert.match(app, /initializeCustomBackground\(\)\.catch/, "startup should resto
 assert.match(app, /Restart Web UI to load themes/, "frontend should explain when a stale server cannot serve the themes endpoint");
 assert.match(app, /themeSelect\.addEventListener\("change"/, "side-panel theme selector should switch themes immediately");
 assert.match(app, /open \? "Close for network" : "Open to network"/, "network button should toggle from open to close action");
+assert.match(app, /let networkStatusLoaded = false;/, "Remote WebUI QR auto-popup state should track the first loaded network status");
+assert.match(app, /const hadNetworkStatus = networkStatusLoaded;[\s\S]*if \(!hadNetworkStatus\) \{\n\s+remoteQrAutoPopupShown = true;\n\s+return;\n\s+\}[\s\S]*if \(!wasOpen && !remoteQrAutoPopupShown && isLocalWebuiBrowserOrigin\(\)\)/, "Remote WebUI QR should auto-open only after network access transitions open, not on initial refresh");
 assert.match(app, /remoteAuthToggle: \$\("#remoteAuthToggle"\)/, "Remote WebUI controls should bind the remote PIN auth toggle");
 assert.match(html, /id="networkControlField"[^>]*hidden/, "Remote WebUI browser controls should be hidden until the optional package is loaded and enabled");
 assert.match(app, /remoteWebuiCommand\(enable \? "authOn" : "authOff"/, "remote PIN auth toggle should dispatch through the Remote WebUI package command");