@gavin-hu/my-pi-agent 0.18.0 → 0.19.0

package/extensions/file-browse/README.md

@@ -1,506 +0,0 @@
-# file-browse — view the working directory in a browser
-
-`/browse` starts a **read-only** HTTP server rooted at the effective working
-directory, opens the default browser at it, and prints the URL. The page is a
-two-pane file browser: a collapsible path tree on the left, directory listings
-and file views on the right, with image thumbnails, rendered Markdown,
-highlighted code, per-language icons, a fuzzy quick-open palette, and a
-read-only git diff view. It is
-bound to `127.0.0.1`
-and ships no dependencies — `node:http` plus one small vanilla script.
-
-<img src="../../assets/file-browse.png" alt="The loopback file browser, showing the path filter, the file tree, and a rendered Markdown preview" width="100%">
-
-```bash
-pi --extension ./extensions/file-browse   # load just this extension
-pi -e .                                    # load the whole @gavin-hu/my-pi-agent package
-```
-
-## What it does
-
-- **One-command browsing.** `/browse` starts the server, prints the URL, and
-  opens the browser (unless `autoOpen: false`).
-- **Two-pane UI.** A server-rendered tree, directory listings, and file pages,
-  progressively enhanced by one first-party script (filter, lazy tree
-  expansion, thumbnail fallback). A folder folds from its twisty, and a
-  `fold all` / `expand all` button beside the filter folds the whole tree at
-  once. The tree scrolls in
-  its own pane with quick open and the filter pinned above it; below 860px it
-  collapses into a `Files` disclosure above the listing. A hairline progress bar
-  tracks whichever column is scrolling (the card body for a file or diff, the
-  main column otherwise), and the served folder names the root page.
-- **Rich previews.** Text, rendered Markdown, images (thumbnails), and
-  binary/over-size download cards, with per-language icons.
-- **First-party syntax highlighting.** Code files render with keywords,
-  strings, numbers, and comments colored, in the dark and light palettes:
-  JavaScript/TypeScript (`js`, `mjs`, `cjs`, `jsx`, `ts`, `mts`, `cts`, `tsx`),
-  JSON, CSS (`css`, `scss`, `sass`, `less`), HTML/XML and template components
-  (`html`, `htm`, `xml`, `vue`, `svelte`), shell (`sh`, `bash`, `zsh`),
-  Python (`py`, `pyw`, `pyi`), Java, YAML (`yaml`, `yml`), and SQL. Other text
-  types stay plain.
-- **Rendered Markdown.** `.md`/`.markdown` files render as headings, lists,
-  tables, code, inline and reference links, bare-URL autolinks, and images, with
-  a one-click **raw** view (`?raw=1`). The page fills the card, so the scroll
-  bar sits at the card edge; headings, prose, and images keep a centred reading
-  measure of at most 1012px. Code blocks stay
-  inside that column; tables start at it and take the free gutter to its right,
-  and a table wider than the pane scrolls, its right edge fading until the last
-  column is reached. A task list's checkbox is drawn by the page, so a done
-  item carries the success colour in both themes. Tables size their columns to
-  the content, and named and numeric character references are decoded. A
-  README's raw HTML is re-emitted through an allowlist (`<details>`,
-  `<summary>`, tables, `<kbd>`, images), so it renders without becoming an
-  injection path. Fenced code blocks are syntax-highlighted when the fence
-  names a supported language. Headings get stable anchor ids, so in-document
-  `#anchor` links work. Raw HTML in the source is escaped, never executed, and
-  external images are shown as links rather than fetched.
-- **Sortable listings.** The Name / Size / Modified headers sort the current
-  directory, directories first, and the choice is remembered per browser.
-- **Copy and wrap.** Copy a file's root-relative path or its contents, copy a
-  `path:12-30` reference for the lines you selected, and toggle line wrapping for
-  text and raw views.
-- **Theme toggle.** A header button switches between the dark and light
-  palettes and remembers the choice per browser; until it is used, the palette
-  follows the system `prefers-color-scheme`.
-- **Quick open.** `/` (or `Ctrl/Cmd+K`, or the sidebar button) opens a fuzzy
-  path finder over a capped index of the tree, with keyboard navigation and a
-  highlighted match; Enter opens the file.
-- **Keyboard.** `/` or `Ctrl/Cmd+K` opens quick open, `-` folds or expands
-  every folder in the tree, `u` toggles line wrapping, `r` switches rendered and
-  raw Markdown, `y` copies a reference to the selected lines, `n`/`p` step
-  between a diff's hunks, and `?` opens a shortcut
-  sheet. A diff's hunk headers pin to the top of the code viewport while its
-  body scrolls.
-- **Read-only and loopback-scoped.** No editing, no writing, no LAN exposure.
-- **Git context.** A read-only header chip shows the checked-out branch (or
-  detached head) and reflows on narrow screens. Uncommitted changes are stated
-  once, by the changes chip below; turn the diff view off (`gitDiff: false`) and
-  the header reports no changes at all.
-- **Git diff view.** A `● N changes +A −D` chip links to `/diff`, a change
-  overview with `git diff --stat` and a per-file status table, and `/diff/<rel>`
-  renders one file's unified diff, whose head carries its own `+A −D` and hunk
-  count. Changed lines are syntax-highlighted with the
-  file's language, and dirty files and their directories carry a marker in the
-  listing and the tree. The scope is switchable between `head` / `staged` /
-  `worktree`; untracked files show as all-add, an unborn `HEAD` falls back to the
-  index, and a non-repository is a plain empty state. Read-only, capped, and
-  rendered with the shared diff colors.
-- **Live status.** A page left open keeps up with the session: a `◉ live`
-  chip beside `read-only` says whether status is flowing (green), still
-  connecting (accent), stalled (amber, after three missed frames), or offline
-  (red); the branch chip, the `● N changes +A −D` chip, and the change markers in
-  the tree and the listing update in place; and the footer line reports `up 2m
-  14s · 37 requests`. The chip names its state and never counts, and a frame
-  whose change set did not move repaints nothing at all. One Server-Sent Events
-  stream per page carries it, on the same loopback server, so nothing extra is
-  opened and nothing is written; that stream is also how the server notices the
-  last page closing its window, after which it stops listening. A page that lists
-  a folder also checks that folder, and offers a `⟳ reload` control when a file
-  has appeared or gone on disk since it drew its rows.
-- **No dependencies.** `node:http` plus the inline sprite, CSS, and client
-  script.
-
-## Commands
-
-```bash
-/browse            start at the working directory, open the browser, print the URL
-/browse <path>     start with a subdirectory of the working directory as the root
-/browse status     print the root and URL, or "not running"
-/browse stop       stop the server
-```
-
-- The root is the effective cwd, so an active `worktree` session serves the
-  worktree. `<path>` must resolve inside it.
-- The port is fixed for the session: the first `/browse` picks a random port
-  in `4780`–`5779` and every later `/browse` in that session reuses it, so the
-  URL stays stable across roots and restarts. Set `"port"` to pin an explicit
-  port; a busy port is reported, not silently changed.
-- Starting while already running with the same root reprints the URL without
-  restarting; a different root (or a changed pinned port) restarts the server.
-- The server is closed when its last page has been gone for ten seconds, so
-  closing the browser window ends the session's browse server and `/browse`
-  starts it again on the same port. A reload or a new tab inside that grace keeps
-  it. `session_shutdown` closes it too, and `/browse stop` closes it at once.
-
-### Status
-
-While a server is running, the extension publishes a two-tone `◉ <port>` chip
-(a green circle-dot and a blue port) under the shared `browse` status key. The
-[`bytefly`](../bytefly/) extension routes it to line 1's right zone
-beside `⎇ branch` and `⑂ worktree`; it
-is cleared on stop and on `session_shutdown`. The chip is session-local: it
-reflects only this session's server, with no cross-session sharing.
-
-The page has its own live status, which is what a left-open tab reads. The
-header chip starts hidden and is painted by the client from `/events`: `◉ live`
-in the success colour while frames arrive, `◉ connecting` before the first
-one, `◉ stale` in the warning colour when three intervals pass without a frame
-on an open connection, and `◉ offline` in the danger colour once the stream
-errors. The chip names its state rather than counting, so it is repainted only
-when that state changes. The same frame carries the branch (or detached head), the
-uncommitted-change totals and paths, the server's uptime, and the requests it
-has answered, so the branch chip, the changes chip, the markers, and the footer
-line are painted from one snapshot rather than four requests. Each change set
-also carries a short revision, and a frame whose revision the page already
-painted does no work at all — so an idle tree costs no DOM, however many rows the
-page drew. Losing the stream leaves everything the page last showed in place: it
-is read-only, so a stale label is never a stale action. `"live": false` turns the
-whole surface off — no chip, no stream, no `/events` route — and so does
-JavaScript off.
-
-A page that lists a folder carries the revision of the names it drew, and asks
-`/api/dir-rev` for the folder's current one on the frame cadence — one directory
-read every five seconds by default, skipped while the tab is hidden and stopped
-for good once it has an answer. A difference reveals `⟳ reload` beside the live
-chip, which reloads the page; the rows themselves are never touched, because a
-page that could grow a row is a page that writes. A folder whose listing was
-truncated, and a file, `/diff`, or error page, has nothing to compare and shows
-no control. At most eight pages may hold the stream at once: a ninth is refused
-and its chip reads `offline`, which keeps one local page from pinning the server
-— and the git read behind each frame — alive.
-
-The stream is also how the server knows a page is still there: when the last one
-leaves, the port is released after ten seconds and the chip is cleared, because
-nothing is left to serve. That is why a page with JavaScript off — or with live
-status off — never counts as a reader, and the server then waits for
-`/browse stop` or the end of the session.
-
-### The page
-
-The page is keyboard-first, and the tree is one tab stop rather than two per
-folder:
-
-| Key | What it does in the tree |
-|---|---|
-| `↑` / `↓` | Move between the rows on screen |
-| `→` | Open a folder (reading its children first if needed), or enter it |
-| `←` | Close the folder, or step out to its parent |
-| `Space` | Open or close the focused folder |
-| `Enter` | Follow the focused row's link |
-| `Home` / `End` | First or last row on screen |
-
-The folder's own link carries `aria-expanded`, so a screen reader hears its
-state once; the twisty beside it is a pointer control kept out of the tab order.
-A mouse click moves the tab stop to that row, so `Tab` comes back to where you
-were. Elsewhere the page keeps its own keys: `/` or `Ctrl`/`Cmd`+`K` for quick
-open, `-` to fold, `u` to wrap, `r` for raw Markdown, `n`/`p` between diff hunks,
-and `?` for the sheet, whose dialog now traps `Tab` and returns focus to its
-button.
-
-Printing is supported: the paper gets the light palette whatever the screen is
-showing, the chrome and the tree are dropped, and a file or diff prints whole
-instead of inside its scroll box.
-
-## Routes
-
-| Route | Result |
-|---|---|
-| `/`, `/browse[/<rel>]` | tree + directory listing |
-| `/view/<rel>` | tree + file page (text, Markdown, image, binary, or over-size) |
-| `/view/<rel>?raw=1` | raw Markdown/text source instead of the rendered view |
-| `/raw/<rel>` | raw bytes, streamed; downloads and image sources |
-| `/diff[?mode=head\|staged\|worktree]` | changed-file overview with `--stat` |
-| `/diff/<rel>[?mode=…]` | one file's unified diff |
-| `/api/tree?path=<rel>` | JSON children for lazy tree expansion |
-| `/api/files?q=<query>` | JSON fuzzy path matches for the quick-open palette |
-| `/events` | Server-Sent Events stream of `status` frames for the open page |
-| `/app.js` | the first-party client script |
-| `/theme.js` | the pre-paint theme bootstrap |
-| `/favicon.ico` | `204` (the icon is a data URI) |
-
-## Configuration
-
-The `file-browse` section of the shared `bytefly.json`, merged from the global
-document and the project document (project wins):
-
-```jsonc
-// bytefly.json → "file-browse"
-{
-  "port": 0,                 // 0 = one random port fixed for the session
-  "autoOpen": true,          // open the browser on start; false for headless
-  "maxFileBytes": 1048576,   // larger files show a download card only
-  "maxThumbBytes": 5242880,  // larger images get an icon, not a thumbnail
-  "maxTextLines": 5000,      // rendered lines before truncation
-  "maxDirEntries": 2000,     // listed entries before truncation
-  "thumbnails": true,
-  "markdown": true,          // render Markdown files as formatted HTML
-  "markdownHtml": true,      // re-emit sanitized raw HTML in rendered Markdown
-  "maxIndexEntries": 20000,  // files collected for quick open before truncation
-  "gitDiff": true,           // offer the read-only diff view
-  "diffContext": 3,          // unified diff context lines
-  "maxDiffLines": 4000,      // diff lines rendered before truncation
-  "live": true,              // stream live status to open pages
-  "liveIntervalMs": 5000     // ms between status frames while a page is connected
-}
-```
-
-## Security
-
-- **Loopback only.** Binds `127.0.0.1`; no auth and no LAN exposure.
-- **Method and Host.** Only `GET`/`HEAD` are served (else `405`); a `Host`
-  header that is not `127.0.0.1[:port]`, `localhost[:port]`, or `[::1][:port]`
-  is rejected (else `403`, DNS-rebinding defense), and no CORS headers are sent.
-- **Path guard.** Every path is decoded once, NUL and absolute paths are
-  rejected, the path is resolved under the root, and the target (or nearest
-  existing ancestor) is `realpath`-checked for containment. This blocks `../`,
-  encoded traversal, and symlink escapes. Symlinks are listed but only followed
-  when their real path stays inside the root.
-- **CSP.** Pages allow only same-origin scripts and inline styles, and refuse to
-  be framed (`frame-ancestors 'none'`, `X-Frame-Options: DENY`), so a local page
-  cannot clickjack the controls or re-point relative URLs through an injected
-  `<base>`; the policy comes from `lib/http/headers.ts`, shared with `plan`, so
-  the two surfaces cannot drift. `/raw` uses
-  `default-src 'none'; script-src 'none'; sandbox` plus `nosniff`, so a served
-  SVG/HTML file cannot execute.
-- **Markdown safety.** Rendered Markdown is escape-first, and raw HTML passes an
-  allowlist (`raw-html.ts`): only known elements and attributes are re-emitted,
-  rebuilt from the parsed names rather than copied, so `script`, `style`,
-  `iframe`, `svg`, event handlers, `style=` and `class=` never reach the page.
-  Link schemes are allowlisted (`javascript:`/`data:` dropped), an external
-  image renders as a link instead of loading, and open elements are balanced at
-  the end of the document so an unclosed `<div>` cannot swallow the page chrome.
-  A suppressed element (`script`, `style`, `svg`, …) is dropped with its body;
-  any other unknown tag is escaped and stays visible. `markdownHtml: false`
-  restores escape-only rendering. The page CSP keeps the rest inert.
-- **Highlighting safety.** The highlighter escapes every literal before it
-  wraps it in a token span, so a code file's content cannot inject markup or
-  attributes; only the fixed `tok-*` class names reach the page.
-- **Event stream.** `/events` is a `GET` on the same loopback server, behind
-  the same method and `Host` checks, and it only reads: the frame is the branch,
-  the change paths and their revision, an uptime, and a request count, all of
-  which the page it feeds already renders. It carries no page policy
-  (`text/event-stream` is not a document), sends `Cache-Control: no-store`, and
-  cannot be cached or replayed. A tick runs only while a page is attached, and
-  the timer is `unref`ed, so an idle server does no work and a forgotten tab
-  cannot hold the process open. At most eight pages may attach; a ninth is
-  answered `204`, the one status an event source never reconnects after.
-- **Directory check.** `/api/dir-rev` answers one folder's listing revision, so
-  the page can tell whether its rows are stale. It goes through the same path
-  guard as every other route and reads one directory; its answer is a hash of the
-  names, not the names themselves, so it discloses nothing the page above it does
-  not already show.
-- **Caps.** `maxFileBytes` (inline rendering), `maxTextLines` (rendered lines),
-  `maxThumbBytes` (thumbnails), and `maxDirEntries` (listings) bound every read.
-- **Git reads.** The header chip and the diff view run read-only git
-  (`rev-parse`, `status --porcelain=v1 -z`, `diff --stat`, `diff -U<n>`) with a
-  timeout and a short cache; any failure simply omits the chip or the diff. A
-  per-file diff sets `GIT_LITERAL_PATHSPECS=1`, so a filename containing glob
-  characters is matched literally.
-- **Read-only.** Nothing is ever written.
-
-## Limitations
-
-- Syntax highlighting covers the built-in language set below; any other text
-  type renders exactly as before. State that the tokenizer does not carry
-  across lines (shell heredocs, interpolation inside a template literal) is
-  approximated rather than parsed.
-- Live status updates what the page already contains: the header chips, the
-  markers on the rows it rendered, and the footer line. A file that appears on
-  disk does not join the listing by itself — the page offers `⟳ reload` instead —
-  and the check covers the folder the page lists, by name, not the folders inside
-  it, a listed file's contents, the `/diff` table, or a file page's `changes`
-  action, which stay page-load snapshots. The branch chip is only patched when
-  the page was served inside a repository.
-- `/browse` has no auth; a malicious local page could probe the port. The `Host`
-  allowlist and the absence of CORS headers mitigate reads, and the server is
-  read-only.
-- Serving the root exposes whatever is on disk to the local user who started it;
-  this is intentional and scoped to loopback.
-
-## Non-goals
-
-- No editing or writing from the browser.
-- No third-party assets: the Markdown renderer, its raw-HTML sanitizer, and the
-  syntax highlighter are first-party, so raw HTML in a Markdown file is
-  allowlisted and never executed.
-- No auth and no LAN exposure: loopback only.
-- Not a general static-file server: the root is confined to the effective cwd.
-
-## Pi integration
-
-| Integration point | How |
-|---|---|
-| Command | `/browse` registers a single command from the factory; no tools are exposed. |
-| State | The running server, its root, and the session port live in a module-local closure; nothing is persisted and no session entries are written. |
-| Lifecycle | The factory opens no socket; the server is created on `/browse` and closed idempotently by `/browse stop`, by `session_shutdown`, and once its last page has been gone for the idle grace, which also ends every attached status stream. |
-
-## Design notes
-
-- **Lifecycle.** `/browse` resolves `resolveEffectiveCwd(ctx.cwd)`, loads config,
-  selects the port, parses args, and `await createFileServer(...)`: `realpath`
-  the root, bind `127.0.0.1`, await `listening`, return `{ url, port, root,
-  close }`. The port is chosen once for the session: a pinned config `port`
-  wins, otherwise a random port is drawn and cached after the first successful
-  bind, so later starts reuse it (a conflict is reported and the next `/browse`
-  rolls another). `/browse stop` and `session_shutdown` await the idempotent
-  `close()`; `session_shutdown` also clears the cached port. The page is the
-  server's only reader, so the channel reports the last page's departure after
-  `IDLE_STOP_MS` and the command closes the server and clears the chip — the
-  cached port survives, so the next `/browse` binds the same one.
-- **Pure routing.** `handleRequest(context, method, rawUrl, headers)` validates
-  method and `Host`, parses the URL, matches a route, and runs every path
-  through `paths.ts`. It returns a plain `ServeResponse`, so routing is tested
-  without a socket; `server.ts` is the only part that binds a port.
-- **One snapshot, one frame.** The status source is shared by every attached
-  page, so a tick costs one `git status`, one `git diff --stat`, and one
-  serialization however many tabs are open. The frame carries a revision of the
-  change set, and the client compares it before painting, which is why an idle
-  page does no DOM work. The cadence is what bounds those reads, so the default
-  is five seconds rather than matching the providers' two-second render cache.
-- **A poll, not a watcher.** The folder check is one request from the page to
-  `/api/dir-rev`, not an `fs.watch`: recursive watching is the one part of
-  `node:fs` whose availability and event semantics differ per platform, and it
-  would add a long-lived resource to start and release around `close()`. The
-  check compares names, so it is a directory read rather than a stat pass, and it
-  stops at the first difference because the control, not the checker, is the fix.
-- **Progressive UI.** The page is server-rendered HTML with an inline style
-  block and inline SVG icons. `client.ts` enhances it: the filter hides
-  non-matching rows while keeping ancestors, disclosure triangles lazily
-  `fetch("/api/tree")`, broken thumbnails fall back to the category icon, the
-  listing headers sort in place, the wrap toggle is remembered, and the copy
-  buttons use the clipboard. On wide screens the tree is its own scroll pane
-  under the pinned filter and quick-open trigger; the sidebar is a `<details>`
-  whose content wrapper has no definite height, so the panel fills it
-  absolutely and the tree flexes inside. Without JS the page still browses and
-  renders Markdown, and the JS-only controls (filter, disclosure, actions, quick
-  open) are hidden; the sort buttons lose their pointer so they do not look
-  live. The palette is the shared Bytefly web theme (`lib/web/tokens.ts`),
-  derived from the `bytefly-dark`/`bytefly-light` terminal themes; it follows
-  `prefers-color-scheme` until an explicit choice sets `data-theme` on the root:
-  `/theme.js` applies the saved choice in the head before first paint, and the
-  header toggle flips and stores it (`pi-web-theme` in `localStorage`, the key
-  shared with plan's review page).
-- **Markdown rendering.** `markdown.ts` is a first-party, escape-first renderer
-  for the constructs that show up in repository READMEs. It emits only a known
-  tag set, escapes every literal character, allowlists URL schemes (dropping
-  `javascript:`/`data:`), rewrites local links and images to `/view`/`/raw`, and
-  renders an external image as a link instead of loading it (the page CSP is
-  `img-src 'self' data:`). Link reference definitions (`[id]: url`), including
-  the full `[text][id]`, collapsed `[text][]`, and shortcut `[text]` forms, and
-  numeric and common named character references are resolved. The Rendered/Raw
-  switch is a server-side `?raw=1`
-  link, so it works without JavaScript. Headings are demoted one level so the
-  card title stays the page's only `h1`, and each gets a slug `id` (unique in
-  the document). Set `markdown: false` to fall back to the plain-text view. A
-  fenced code block
-  whose info string names a supported
-  language is highlighted through `lib/highlight.ts` (either an extension or a
-  long-form alias, `fenceLanguage`); an absent or unknown language stays plain.
-- **Raw HTML.** A line that starts with an allowed block tag (`<details>`,
-  `<table>`, `<div>`, `<pre>`, …), a comment, or a closing tag opens an HTML
-  block that runs to the next blank line; text inside it stays text, and a
-  suppressed tag (`<script>`, `<style>`, `<svg>`) drops its body through the
-  matching close tag. `raw-html.ts` re-emits only allowlisted elements and
-  attributes: `a`/`img` go through the same `/view`/`/raw` resolution as
-  Markdown, an external image becomes a link, and `class`/`style`/handlers are
-  dropped. Phrasing tags are also accepted inside a line, while a block tag
-  mid-paragraph stays escaped. Open elements are balanced across blocks, which
-  is how a `<details>` can wrap Markdown paragraphs, and `markdownHtml: false`
-  turns the whole path off.
-- **Syntax highlighting.** `lib/highlight.ts` is a first-party, escape-first
-  tokenizer for the file types that dominate a repository: JavaScript and
-  TypeScript, JSON, CSS (incl. SCSS/Sass/Less), HTML/XML and template
-  components, shell, Python, Java, YAML, and SQL. `detectLanguage` maps a
-  filename to a tokenizer and an unmapped type stays plain. `highlightLines`
-  walks the whole file, so block comments, template literals, open HTML tags,
-  CSS brace depth, and Python triple-quoted strings carry across lines; every
-  literal is escaped with the same `escapeHtml` the plain view uses, and a
-  line's markup is only the fixed `tok-*` classes the stylesheet colors. It
-  backs both the plain text view and fenced code blocks in the rendered
-  Markdown view.
-- **Quick open.** `/api/files` ranks the cached index with `fuzzy.ts` and
-  returns the matched character positions; the client fetches on an 80 ms
-  debounce and builds rows with `textContent`, so a file name cannot inject
-  markup. The index skips `.git`, `node_modules`, and symlinks, is capped by
-  `maxIndexEntries`, and is cached per server for 10 s by `createFileIndex`. The
-  palette is a `dialog`/`combobox`/`listbox` with `aria-activedescendant` and
-  `Esc` / arrow / `Enter` handling.
-- **Diff view.** `git.ts` extends the read-only provider set with a TTL-cached
-  `git status --porcelain=v1 -z` and a per-mode `git diff`; `diff.ts` parses the
-  unified diff and the porcelain records into plain view models, so `router.ts`
-  and `html.ts` stay pure. `head` compares against `HEAD` (falling back to
-  `--cached` before the first commit), `staged` against the index, and
-  `worktree` against the index from the other side. An untracked file renders as
-  all-add through `readFileView`, so binary and over-size handling is shared
-  with the file view. `git diff --stat` supplies the chip totals and
-  `changeDirs` derives the directory markers; the changed lines are highlighted
-  per hunk by rebuilding the old and new sides for `lib/highlight`.
-- **Live status.** `live.ts` builds one snapshot per tick — the git status,
-  the `head` change index, the server's uptime, and its request count — and
-  `frameOf` serializes it as one `status` event. `createLiveChannel` holds the
-  attached pages and starts the ticker on the first attach, so an idle server
-  does no work; it shares a single in-flight snapshot between pages, drops a
-  page whose write fails, and stops on the last detach and on `close()`, which
-  `server.ts` calls before closing the socket. The last detach also arms one
-  idle-stop timer — a reload re-attaches and cancels it — and `server.ts` turns
-  that into the extension's `close()` and a cleared chip. Both providers are already
-  TTL-cached, so a tick re-reads at most one `git status`, and every read
-  failure degrades to `null` rather than a failed frame. The event-stream
-  headers and the `retry:` preamble live in `lib/http` with the rest of the
-  loopback policy, shared with plan's review page. The client half is
-  `live-client.ts`: one `EventSource`, one snapshot paint (`textContent` only,
-  never markup), one staleness timeout armed per frame, and a `pagehide` cleanup.
-- **Streaming responses.** The server streams `filePath` responses and
-  suppresses bodies for `HEAD`, so large `/raw` files are not buffered.
-- **Root confinement over feature breadth.** The root is deliberately confined
-  to the effective cwd rather than serving an arbitrary directory, so a
-  worktree session serves the worktree and nothing above it.
-
-## Files
-
-| File | Purpose |
-|---|---|
-| `index.ts` | `/browse` command, running-server closure, shutdown cleanup |
-| `config.ts` | Config defaults, validation, global/project merge |
-| `paths.ts` | Decode/encode, resolve, and `realpath`-containment guard |
-| [`../../lib/escape.ts`](../../lib/escape.ts) | `escapeHtml`, the shared HTML escaping used by every renderer |
-| [`../../lib/highlight.ts`](../../lib/highlight.ts) | First-party escape-first syntax tokenizer for the code view (shared with `plan`) |
-| [`../../lib/web/index.ts`](../../lib/web/index.ts) | The shared Bytefly web brand system: tokens, base, components, layout, runtime, and markup |
-| `files.ts` | Classification (incl. Markdown), text reads, and one page-level walk (`directoryView`) that returns a directory's listing and its sidebar tree |
-| `diff.ts` | Pure unified-diff and porcelain-status parsing for the diff view |
-| `fuzzy.ts` | Fuzzy path matching and ranking for the quick-open palette |
-| `markdown.ts` | First-party escape-first Markdown-to-HTML renderer (fenced code highlighted; raw HTML through `raw-html.ts`) |
-| `raw-html.ts` | Allowlisted raw-HTML sanitizer: element/attribute policy, suppressed bodies, and cross-block balancing |
-| `urls.ts` | Shared link/image URL policy: scheme allowlist and `/view`/`/raw` rewriting |
-| `git.ts` | Read-only branch/dirty provider for the header chip |
-| `icons.ts` | Inline SVG sprite and the per-language mapping |
-| `client.ts` | The `/app.js` source: sort, wrap, copy, hunk navigation, reading progress, and the page keymap |
-| `tree.ts` | The sidebar block: path filter, fold-all, lazy tree loading, and the tree's keyboard model (interpolated into `client.ts`) |
-| `palette.ts` | The quick-open palette: fuzzy search, the combobox wiring, and the `window.bfPalette` contract (interpolated into `client.ts`) |
-| `live-client.ts` | The client's live status block: the event stream, the chips, the markers, and the footer line (interpolated into `client.ts`) |
-| `live.ts` | The live status snapshot, its frame, and the fan-out channel that ticks it |
-| `styles.ts` | The page-only `browse-*` stylesheet (the `bf-*` kit comes from `lib/web`) |
-| `html.ts` | Page renderers: the shared shell, the two-pane layout, the listing, the cards, and the diff body |
-| `router.ts` | Pure request handler: routes, the `/raw` sandbox policy, and the error page |
-| `server.ts` | `node:http` server: this extension's handler over the shared bind, writer, and close |
-| [`../../lib/http/index.ts`](../../lib/http/index.ts) | Loopback HTTP layer shared with `plan`: page/script/JSON/event-stream headers, `ServeResponse`, the request-envelope helpers, bind/respond/close, and `openEventStream` |
-| [`../../lib/browser.ts`](../../lib/browser.ts) | Cross-platform browser opener (shared with `plan`) |
-
-## Testing
-
-`extensions/file-browse/` covers the path guard (traversal, encoded, NUL, malformed,
-absolute, symlink escape and in-root symlink), file classification/listings/
-reads/tree and the quick-open file index, the fuzzy matcher, the syntax
-highlighter (language detection, fence aliases, token classes, cross-line
-state, and escaping), the Markdown renderer (blocks, inline, fenced-code
-highlighting, safety, raw HTML, and path resolution), the raw-HTML sanitizer
-(allowlist, suppressed bodies, attribute policy, balancing, and a seeded
-invariant test over fragment soup),
-the icon mapping and sprite, HTML escaping/encoding/rendering, the client script
-and its serving, the platform browser commands with an injected spawn, the router
-(routes, `/api/tree`, `/api/files`, `?raw=1`, status codes, `Host`, `HEAD`, `/raw`
-headers, and the `/diff` view routes and mode validation)
-without a socket, a real `127.0.0.1:0` server, the session-port lifecycle (fixed
-on first start, reused, and re-rolled after a conflict), the git status provider
-(branch, dirty, detached, non-repo, failure, and TTL cache), the git diff parser
-and provider (line kinds, line numbers, status and rename parsing, mode
-filtering, untracked all-add, unborn-HEAD fallback, literal pathspec, and TTL
-cache), the diff renderers (highlighted changed lines, marker sets, and chip
-totals), the live status feed (snapshot fields, degraded providers, the frame,
-and the channel's ticker driven by an injected timer, plus the idle stop armed on
-the last detach and cancelled by the next page or by `close()`), the `/events`
-route and
-its 404 when the channel is off, a real socket that reads a page's first frame
-and the ticker's next one and sees the stream end when the server closes, the
-live chrome a page renders when on and not when off, and the command
-lifecycle with injected seams.

package/extensions/file-browse/server.ts

@@ -1,141 +0,0 @@
-/**
- * The HTTP server for the browse extension.
- *
- * Wraps `node:http` around the pure `handleRequest`: it resolves the root once,
- * binds `127.0.0.1`, streams `/raw` responses from disk, feeds the live status
- * channel, and exposes an idempotent `close()`. The request handler is injectable
- * so tests can avoid a socket when they only need routing.
- *
- * The bind, the response writer, the event-stream head, and the close come from
- * `lib/http`, which `plan` shares; what stays here is this server's own request
- * handler, its request count, and the catch that turns a thrown handler into a
- * plain-text 500.
- */
-
-import { realpathSync } from "node:fs";
-import { createServer } from "node:http";
-import {
-	bindLoopback,
-	createCloser,
-	openEventStream,
-	respond,
-	textResponse,
-	type ServeResponse,
-} from "../../lib/http/index.ts";
-import { IDLE_STOP_MS, type ServeConfig } from "./config.ts";
-import { createFileIndex } from "./files.ts";
-import type { GitDiffProvider, GitStatusProvider } from "./git.ts";
-import { createLiveChannel, createLiveStatus } from "./live.ts";
-import { handleRequest, type ServeContext } from "./router.ts";
-
-export interface FileServer {
-	/** Origin URL, e.g. `http://127.0.0.1:49152/`. */
-	url: string;
-	/** The bound port. */
-	port: number;
-	/** Resolved absolute root that is actually served. */
-	root: string;
-	/** Stop listening. Safe to call more than once or before `listen` settles. */
-	close(): Promise<void>;
-}
-
-export interface FileServerOptions {
-	root: string;
-	config: ServeConfig;
-	/** Read-only git context for the page header; omitted when unavailable. */
-	git?: GitStatusProvider;
-	/** Read-only diff provider for the change and diff views; omitted when unavailable. */
-	diff?: GitDiffProvider;
-	/** Called once the last page has been gone for `idleStopMs`; omitted, the server waits for `close()`. */
-	onIdle?: () => void;
-	/** Grace before `onIdle`, in ms; defaults to `IDLE_STOP_MS`. */
-	idleStopMs?: number;
-	/** Override the request handler (tests). */
-	handler?: typeof handleRequest;
-}
-
-/** Start a read-only server rooted at `options.root` on 127.0.0.1. */
-export async function createFileServer(options: FileServerOptions): Promise<FileServer> {
-	const root = realpathSync.native(options.root);
-	const { config } = options;
-	// The status feed's two server-owned facts: how long it has been up, and how
-	// many requests it has answered. Both are read per frame, never cached.
-	let requests = 0;
-	const status = config.live
-		? createLiveStatus({
-				git: options.git,
-				diff: config.gitDiff ? options.diff : undefined,
-				startedAt: Date.now(),
-				requests: () => requests,
-			})
-		: undefined;
-	const live = status
-		? createLiveChannel({
-				status,
-				intervalMs: config.liveIntervalMs,
-				idleMs: options.idleStopMs ?? IDLE_STOP_MS,
-				onIdle: options.onIdle,
-			})
-		: undefined;
-	const context: ServeContext = {
-		root,
-		config,
-		git: options.git,
-		diff: options.diff,
-		index: createFileIndex(root, config.maxIndexEntries),
-		live: status,
-	};
-	const handler = options.handler ?? handleRequest;
-
-	const server = createServer((request, response) => {
-		requests += 1;
-		const answer = async (): Promise<ServeResponse> => {
-			try {
-				return await handler(context, request.method ?? "GET", request.url ?? "/", request.headers);
-			} catch {
-				return textResponse(500, "Internal error");
-			}
-		};
-		void answer().then((result) => {
-			// A HEAD of the stream is answered as a plain response: there is no body to
-			// hold open, and the client would otherwise wait on frames it asked not to get.
-			if (!result.stream || !live || (request.method ?? "GET").toUpperCase() === "HEAD") {
-				respond(request, response, result);
-				return;
-			}
-			// Checked before the head is written: a refusal must not leave a stream the
-			// client would wait on. `204` is the one status an event source does not
-			// reconnect after, so a page beyond the cap goes quiet instead of retrying.
-			if (live.atCapacity()) {
-				respond(request, response, { status: 204, headers: { "Cache-Control": "no-store" }, body: "" });
-				return;
-			}
-			openEventStream(response, result);
-			const detach = live.attach({
-				write: (frame) => {
-					response.write(frame);
-				},
-				end: () => {
-					if (!response.writableEnded) response.end();
-				},
-			});
-			request.on("close", () => {
-				detach();
-				if (!response.writableEnded) response.end();
-			});
-		});
-	});
-
-	const port = await bindLoopback(server, config.port);
-	const closeServer = createCloser(server);
-	return {
-		url: `http://127.0.0.1:${port}/`,
-		port,
-		root,
-		close: async () => {
-			// End the streams first, so a connected page does not hold the close open.
-			live?.close();
-			await closeServer();
-		},
-	};
-}