pi-pocket 0.27.0-beta.4 → 0.27.0-beta.6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -97,33 +97,41 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
97
97
 
98
98
  ### The frame
99
99
 
100
- | Part | What |
101
- | ------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
- | `app` | The whole layout: the sidebar, the conversation, and the panels beside it, in a row |
103
- | `boot` | The screen while the app starts |
104
- | `brand-mark` | The π: on the rail, and on the boot screen |
105
- | `sidebar` | The rail and the session list, on wide screens |
106
- | `drawer` | The rail and the session list sliding in, on narrow screens |
107
- | `rail`, `rail-button` | The column of buttons, and each of them (an extension's too) |
108
- | `session-list`, `session-list-title` | The session list, and its title ("Sessions") |
109
- | `session-search` | The search field |
110
- | `session-filter` | An extension's filter button in the search field (`data-state="on"` while it narrows the list) (since 0.20.0) |
111
- | `session-tabs` | Recent, Folders, Archived |
112
- | `segment-thumb` | What slides under the chosen segment, in the session tabs and other segmented controls. The app sets its place and width (`transform` and `width`, or `height` in a column); leave those to it |
113
- | `session-group`, `session-group-head` | A group of rows (a day, a folder), and its head, which folds it |
114
- | `session-group-name`, `session-group-count` | The head's name, and its count |
115
- | `session-row` | One session's line |
116
- | `session-button` | The row's button: its square, title, and what is on its right |
117
- | `session-mark` | A session's square, in its folder's color, in the shape of its state (the home screen's too) |
118
- | `session-branches` | The lines to a session that another one started |
119
- | `session-chips`, `session-chip` | The chips that extensions put under a row's title, and each of them (since 0.20.0) |
120
- | `home` | The home screen on wide screens |
121
- | `home-facts`, `home-logo`, `home-title`, `home-fact`, `home-colors` | Its summary: the block, the logo, the first line, each fact, the palette's colors (each a `home-color`) |
122
- | `home-actions` | Its buttons |
123
- | `home-recent`, `home-heading`, `home-recent-row`, `home-recent-key` | Jump back in: the list, its heading, each session, and the number that opens it |
124
- | `home-list` | The session list as a phone's home screen |
125
- | `pane` | The conversation's window (or the subagents board, or an extension's page) |
126
- | `topbar`, `topbar-title`, `topbar-sub` | The conversation's title bar, its title, and the line under it (folder, branch) |
100
+ | Part | What |
101
+ | ---------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
102
+ | `app` | The whole layout: the sidebar, the conversation, and the panels beside it, in a row |
103
+ | `boot` | The screen while the app starts |
104
+ | `brand-mark` | The π: on the rail, and on the boot screen |
105
+ | `sidebar` | The rail and the session list, on wide screens |
106
+ | `drawer` | The rail and the session list sliding in, on narrow screens |
107
+ | `rail`, `rail-button` | The column of buttons, and each of them (an extension's too) |
108
+ | `rail-needs` | The warning-colored count on the Sessions button: how many sessions need you (since 0.27.0) |
109
+ | `session-list`, `session-list-title` | The session list, and its title ("Sessions") |
110
+ | `session-search` | The search field |
111
+ | `session-filter` | An extension's filter button in the search field (`data-state="on"` while it narrows the list) (since 0.20.0) |
112
+ | `session-tabs` | Priority, Recent, Folders, and Archived (an icon) |
113
+ | `session-tab`, `session-tab-count` | One tab; and Priority's count of the sessions that need you (since 0.27.0) |
114
+ | `segment-thumb` | What slides under the chosen segment, in the session tabs and other segmented controls. The app sets its place and width (`transform` and `width`, or `height` in a column); leave those to it |
115
+ | `session-group`, `session-group-head` | A group of rows (a day, a folder, a Priority group), and its head, which folds it; Priority's Needs you does not fold, and its head is not a button |
116
+ | `session-group-bar`, `session-group-action` | In Priority, a group's head with its button beside it (Dismiss N failed, Mark all read), and that button (since 0.27.0) |
117
+ | `session-clear`, `session-more` | In Priority, the line "Nothing needs you", and Show N more under Needs you (since 0.27.0) |
118
+ | `session-group-name`, `session-group-count` | The head's name, and its count |
119
+ | `session-row` | One session's line |
120
+ | `session-button` | The row's button: its square, title, and what is on its right |
121
+ | `session-mark` | A session's square, in its folder's color, in the shape of its state (the home screen's too) |
122
+ | `session-limit` | In Priority's Working group, the clock pill with the time a usage limit clears (since 0.27.0) |
123
+ | `session-quick`, `session-review`, `session-dismiss`, `session-read` | In Priority, the button at the right of a row: Review (a call waits), Dismiss (a failure), and Mark read on hover (since 0.27.0) |
124
+ | `session-ask`, `session-ask-command`, `session-ask-reason` | The call open in a row of Needs you, its command, and why the guard asks (since 0.27.0) |
125
+ | `session-deny`, `session-decline`, `session-allow`, `session-ask-open` | That call's buttons (since 0.27.0) |
126
+ | `session-branches` | The lines to a session that another one started |
127
+ | `session-chips`, `session-chip` | The chips that extensions put under a row's title, and each of them (since 0.20.0) |
128
+ | `home` | The home screen on wide screens |
129
+ | `home-facts`, `home-logo`, `home-title`, `home-fact`, `home-colors` | Its summary: the block, the logo, the first line, each fact, the palette's colors (each a `home-color`) |
130
+ | `home-actions` | Its buttons |
131
+ | `home-recent`, `home-heading`, `home-recent-row`, `home-recent-key` | Jump back in: the list, its heading, each session, and the number that opens it |
132
+ | `home-list` | The session list as a phone's home screen |
133
+ | `pane` | The conversation's window (or the subagents board, or an extension's page) |
134
+ | `topbar`, `topbar-title`, `topbar-sub` | The conversation's title bar, its title, and the line under it (folder, branch) |
127
135
 
128
136
  ### The conversation
129
137
 
@@ -200,7 +208,7 @@ Each is a `data-part` attribute. Some elements have two (`data-part="composer-bu
200
208
  | `session-row` | `data-state` | `working`, `waiting` (for you), `limited` (waiting for a provider's limit to clear, since 0.21.0), `failed`, `done` (since you looked), `idle` |
201
209
  | `peek-tile` | `data-state` | The same as `session-row`'s, but without `failed` |
202
210
  | `session-button` | `aria-current` | `page` on the open session's |
203
- | `session-group-head`, `activity-head`, `step-head` | `aria-expanded` | `true` while open |
211
+ | `session-group-head`, `activity-head`, `step-head` | `aria-expanded` | `true` while open; none on Priority's Needs you head, which does not fold |
204
212
  | `activity` | `data-state` | `open` while open |
205
213
  | `tool-call` | `data-state` | `running`, `ok`, `failed`, `waiting` (for approval), `denied`, `stopped` |
206
214
  | `prompt` | `data-from` | `me`, `person` (someone else), `linked` (a linked session), `other` (Pi's schedule, the main agent, a watch or a webhook) |
@@ -237,6 +245,8 @@ A part's `::before` and `::after` are a theme's to use, except these, which the
237
245
  | ---------------------------------------------- | --------------------------------------------------------------------------- |
238
246
  | `session-group-head` | `::after`: its tap area on touch screens |
239
247
  | `session-mark` | `::before`: the square that steps while the session works |
248
+ | `session-review`, `session-dismiss` | `::before`: their tap areas (since 0.27.0) |
249
+ | `session-group-action` | `::before`: its tap area on touch screens (since 0.27.0) |
240
250
  | `timeline` | `::before`: the rule |
241
251
  | `composer-button`, `model-chip`, `send-button` | `::before`: their tap areas on phones; the mic's `::after` while it listens |
242
252
  | `notice` | `::after`: the bar that counts down |
package/docs/features.md CHANGED
@@ -7,7 +7,7 @@ The full tour. For setup, see the [README](../README.md).
7
7
  - **Omarchy colors.** All of Omarchy's themes, from Tokyo Night and Gruvbox to Rosé Pine and the light ones, drawn from each theme's own `colors.toml`, in soft tiles: rounded windows and controls on 1px hairlines, soft shadows only on what floats, Geist for words and JetBrains Mono for code, paths, and numbers, with JetBrains Mono's own italic and the Nerd Fonts icons that prompts and tools print (bundled in `web/fonts/`, with Inter, Fira Code, IBM Plex Mono, and Iosevka for themes to name; `web/fonts/SOURCES.md` says where each came from); light themes too. Menu → **Appearance** (or the **Theme** tile, the launcher, or `/theme gruvbox`) picks one under **Colors**, as well as a theme folder's `colors.toml` (any Omarchy theme folder dropped into `themes/` shows there); the mini-desktop cards in Appearance preview a theme on hover or keyboard focus, and leaving without choosing restores the saved theme. The new look grows as a circle from where you tapped. **Desktop** follows the Omarchy theme of the machine Pi Pocket runs on: change your desktop's theme and the app follows within seconds, optionally with your wallpaper in the gaps.
8
8
  - **Sheets and controls.** Sheets have a 56px title bar on wide screens, a back chevron when opened from another sheet, grouped inset lists, round toggles, and segmented settings. On phones they keep their bottom-sheet grip and drag-to-close gesture. Text sheets have Cancel and the main action together at the bottom; all existing keyboard and back flows stay available. Buttons, fields, and search share the same rounded controls across the app.
9
9
  - **Tiled windows and motion.** On wide screens the sidebar and the session are Hyprland windows, softened: 8px gaps, rounded corners on a hairline, and a soft accent ring on the one under the mouse. Motion uses Omarchy's Hyprland curves: windows pop in at 87%, sheets and popovers rise a little as they fade in, and leave quickly, new messages slide in, and notices count down until they go. While Pi works, the conversation shows what it does; elsewhere a working session's square steps around and a small dot pulses (both hold still with reduced motion). Appearance can turn tiling off (no gaps, square corners, no ring), reduce motion (or follow the system's setting), choose Fluid motion (sheets, menus, the launcher, and notices arrive on a spring and leave quickly, over a frosted scrim; what they hold, and a tool group's first steps, follow a step apart; a message sent lifts off from the message box; each new paragraph of Pi's answer fades in, and its caret breathes; a pressed button springs back; and folding the sidebar morphs the windows into place; Width and tiling change at once, as they are set from a sheet or the launcher, which morphs skip; Auto never picks it), change the conversation's text size (13, 15, 17, or 20, or any size from 10 to 32 px typed in, in half pixels), set the width (Comfortable, which grows with a wide window, Wide, or Full: how much of the window the conversation and the message box take, per browser; phones stay as they are; a reply's code block with long lines grows past the column, centered on it, where plain text and Markdown wrap in the column, and a wide table grows toward the window's edge), set the density (Comfortable, Compact, or Tight: less room between turns, inside message cards and activity groups, between the conversation's lines, in the session list's rows, around the message box and the status line, in sheets and their lists, and in the top bar, while font sizes stay and rows on a touch screen stay a thumb tall), show Pi's thinking while it works, and show the reply speed under the message box.
10
- - **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Recent, Folders, and Archived in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet of its actions; with a mouse, right-click a row for the same actions in a small menu at the pointer (Shift+right-click keeps the browser's own menu, and Ctrl+click on a Mac still selects). They are: open it in a new tab, copy its link or its folder's path, rename it, fork it (a new session with its whole history, through Pi's latest finished reply), start a new session in its folder, share it (an invite to only that session), pin or unpin it, move a pinned one to the top or bottom of the pins, mark it unread or read, extensions' actions, select it, and archive or unarchive it. Pinned sessions keep the order they were pinned in, or moved to. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
10
+ - **The sidebar.** A rail and the session list beside it. The rail holds Pi (which goes to the home screen), Sessions (which folds the sidebar to numbered sessions and unfolds it again, as Ctrl/⌘+B does), the tools (Peek tiles, where the server has them, lit while they are on; Running now, with how many sessions work; the subagents board, with how many subagents work or wait, and a red mark when one waits for you or failed and nobody has dealt with it yet; People; Providers, for the owner; Theme), and you. The list has Priority, Recent, Folders, and Archived (an icon) in a segmented switch; sessions grouped by day or by folder, in groups that fold; and pinned sessions on top (per browser). **Priority** (since 0.27.0) groups sessions by what they ask of you, not by when they ran, and has no Pinned group: pinned sessions go by their state. **Needs you** holds sessions with a call waiting for approval (the longest wait first), then failed runs not seen yet, then sessions with failed subagents nobody dealt with; its tab and the rail's Sessions button carry a warning-colored count of them, and its head offers **Dismiss N failed** when more than one failed. **Ready to read** holds sessions that finished since this browser looked, that are marked unread, or that have new chat (newest first; **Mark all read** in its head, and a button on a row's hover). **Working** holds sessions where Pi or its subagents work, a background command runs, or a request waits for a provider's limit (a clock pill says when it clears). **Quiet** holds the rest, folded at first. Each row is one line. A call's row has a **Review** button, which opens the call in the row (one at a time): the tool and its whole command, why the guard asks, and how long ago, with Deny and Allow. Allow shows only when the command is whole in the row (80 characters, one line), as on a peek tile; otherwise Deny and Open. An extension's question can be declined from its row, or opened to be answered where it waits, a person who may not allow what Pi did for someone else cannot allow it, and only people who can steer answer. After an answer the next call opens by itself with the focus on its Review, and the answered row glows in the group it moves to; an answer cannot be undone, and says so in a notice without Undo. A failed run's row has a ✕ that dismisses it (the run counts as seen, like opening it) and a failed subagent's ✕ deals with it, as the subagents board does; Dismiss and Mark all read say so in a notice that undoes them, except a subagent's dealt-with failure. The open session's row stays in its group while it is open, though opening it reads it, and moves when another session opens. Needs you shows six rows and a **Show N more** button. A search lists the matches, as on the other tabs. The tab a browser starts on is the one it kept (Recent when it kept none). Each session is one line: a square in its folder's color whose shape says where the session is (stepping quadrants while Pi or its subagents work, two bars while a call waits for you, a cross when its run failed, solid when it finished since this browser last had it open or is marked unread, and hollow once read or never run), its title (semibold with new chat, when marked unread, or when open, and the open one on the accent's soft fill), and on the right a small pill with ⑂ and how many subagents work there (or failed with nobody dealing with it yet, in red), who else is there, a pulsing dot while Pi works or a "needs you" pill while a call waits for you, a dot for new chat (or for a session this browser marked unread), and how long ago; its folder and model are in its tooltip. Hover a row to archive, pin, or mark it unread; on a touch screen, hold a finger on it (the row shows the press, and moving the finger scrolls instead) for a sheet of its actions; with a mouse, right-click a row for the same actions in a small menu at the pointer (Shift+right-click keeps the browser's own menu, and Ctrl+click on a Mac still selects). They are: open it in a new tab, copy its link or its folder's path, rename it, fork it (a new session with its whole history, through Pi's latest finished reply), start a new session in its folder, share it (an invite to only that session), pin or unpin it, move a pinned one to the top or bottom of the pins, mark it unread or read, extensions' actions, select it, and archive or unarchive it. Pinned sessions keep the order they were pinned in, or moved to. Marks are per browser, like pins (a session's square counts as read here when this browser opens it, or has it open in sight as its run ends; a failed run's cross stays until its next run starts, and a restart forgets it), and opening the session clears its mark; the session's menu marks the open one unread and goes back to the list. A session that another one started (Agent Teams) shows under it, with a branch line to it, as deep as they go (up to three steps of indent, so a phone's list keeps its room), and the numbers (Alt+1…9, the folded rail) follow the tree; a pinned one stays among the pins, and in Folders one in another folder stays in that folder's group. A session with linked sessions under it has a pill on its right with how many and a chevron: a tap folds them away under it, and again shows them; a fold holds in that browser across reloads, a folded row shows a dot when one under it waits for you or failed, and a search shows every match, folded or not. Someone who cannot see the session that started one sees it as a session of its own. A session moves up the list when it is renamed, gets a message, or Pi starts work there for any other reason (a scheduled message, a subagent's report, a message sent again after a restart), so the one that ran last is on top. Archiving says so in a notice that undoes it. Ctrl/⌘+click selects sessions, Ctrl/⌘+drag selects every row it passes (the list scrolls at its edges), and Shift+click selects a run; on a touch screen, after **Select**, taps select more rows or let them go. A bar under the list archives, unarchives, or pins them, and Esc (or back, after Select) lets go. Archiving does not move a session in the list, so one brought back returns to where it was. Drag its edge to resize the list (to 40% of the screen at most), or fold the sidebar to the rail with numbered sessions, like Waybar's workspaces. A rail with more buttons than room (a short window, many extensions' buttons) scrolls as a whole, and its numbered sessions on their own, up to a third of the window; each fades the edge where more is. On phones the drawer and the list with no session open have the same rail. On wide screens with no session open, the home screen shows a fastfetch-style summary, buttons for a new session, the launcher, and Appearance, and the sessions to jump back into.
11
11
  - **Your own layout.** Appearance → **Top bar buttons**, **Status line items**, **Places**, **Message box buttons**, and **Under Pi's answers** list what shows in each place, the app's own and extensions' alike: a switch shows or hides each one, arrows move it, and **Reset** goes back to the defaults. The menu, More under an answer, Lancet Guard, and the connection's warning always show. Saved in each browser, so a phone and a desktop can differ. Extensions can arrange these too (`pocket.arrange`), and what you choose wins.
12
12
  - **Peek tiles.** Off until you turn them on: the menu's **Peeks** tile, Alt+P, `/peek`, the launcher, or Appearance switches them on or off in one step, and so do the rail's **Peek tiles** button and the tiles button in the top bar, which shows wherever its pane is 480px wide or more (while off, it has a dot when another session waits for you). Then other sessions' live work shows beside the one you are in: one tile per session that is working, waiting for an approval, has subagents at work, finished since this browser last had it open, or is pinned, plus the one you just left. Each is a card with the session's folder square, title, and path, its last three lines (what was asked, what Pi said, its tool calls and how they went, each in two lines at most, with a mark for who or what said it), the subagents at work there, and a footer with its state in words; it changes at most once a second, and only its square moves while the session works. Its subagents at work get a line each: the state square, the name, and what it does this moment (the call it runs, the one it waits to allow, or its words), from its own peek; a tap opens it. Those waiting for an approval come first, and a tile shows three at most (the strip one), so it stays a glance however many work: **N more** opens the subagents board at the first one left out. A subagent's call waiting on its session's tile says which subagent asks, and in the column the footer says when only subagents keep the session working or waiting ("3 subagents working"). Click a tile to open its session; the one you leave takes its place, so the tiles stay put. Allow or deny a waiting call right on its tile, which shows the whole command and why the guard asks; a command that does not show whole offers Open instead of Allow, which goes to the conversation it waits in. The ✓ on a finished one marks it seen. On wide screens the tiles are a column that slides in where People and the Browser panel dock when neither is open, with **▲/▼ N need you** at its edge for waiting tiles out of view; narrower screens (and wide ones with a panel open) get a strip under the top bar that swipes sideways. Only the tiles on screen are live: once scrolling settles, the tab tells the server which, and the rest keep their last lines (their marks stay current from the session list); a tab in the background keeps none live, and with tiles off nothing is sent at all. Peeking is not being there: it does not show you in the session's people.
13
13
  - **Launcher.** Ctrl/⌘+K (on a touch screen, the **Launcher** tile among the places, or the ⌘ button in the session search) opens a rounded search window for sessions, actions, and themes, with fuzzy matching. Search-type pills sit above grouped results with folder-color tiles, action icons, or four-color theme swatches; the selected row has a soft fill. **All**, **Sessions**, **Actions**, and **Themes** select the search type without clearing your words; `>`, `@`, and `#` still work. All starts with six recent sessions; **Show all** searches the whole session list, including archived sessions. Result counts show when a list is capped. Titles and folder or command details highlight matches, and sessions show their current, working, waiting, or archived state in a pill on the right. Arrowing onto colors shows them at once; Enter keeps them, Escape goes back. A theme that changes the look shows once chosen. Arrows, Tab/Shift+Tab, and PageUp/PageDown move the selection; Enter opens it. **Close**, Escape, a tap outside, or Back closes the launcher. Each opening starts with a fresh search and a focused input, even when it reopens during its fade-out. On a phone it is a sheet from the bottom edge, like the app's other sheets: drag it down to close it. On a touch screen it opens without the keyboard, so the results stay in sight; a tap on its search brings the keyboard up.
@@ -69,7 +69,7 @@ The full tour. For setup, see the [README](../README.md).
69
69
  - **Tweaks.** A page can declare knobs (colors, sizes, choices, switches) and the Tweaks tab shows them as controls that change the page live. Values are each person's own, kept for each design. **Keep these** puts them in the message box so that Pi writes them into the design.
70
70
  - **Variations.** Artifacts of one group show as a grid of live thumbnails. **Use this one** puts a message about it in the message box.
71
71
  - **Export and share.** PNG, PDF, PPTX (decks), and an HTML zip, from the menu. The file is written in the session's `exports/` folder and the browser downloads it. **Share a link** is the artifact viewer's Share. There is no Canva export.
72
- - **What Pi does.** Its guide (a prompt section, only while the module is on) gives Pi a page skeleton and craft rules: one HTML artifact for each design, `data-pid` on meaningful elements, a tweaks manifest of 3 to 8 knobs bound to the system's tokens, assets for images and fonts, variations as a group of 2 to 4 artifacts, a link to `ds/tokens.css` when the project has a design system, and a check with `design_preview` before it replies. When the project has a system, the guide carries a summary of it (roles and components first) as untrusted project data. Its tools: `design_preview` renders a version in a private headless Chromium (never the browser people watch) at mobile and desktop sizes, or the sizes asked for, and returns screenshots and a short report (see **Checks**); its options are `checks` (on by default), `tweaks`, `colorScheme`, `page` (another page of the bundle), and `actions` (hover, click, or focus on a selector before the screenshot). `design_export` writes PNG, PDF, PPTX, or an HTML zip, by default as `exports/<id>-v<version>.<ext>`, and refuses a path outside the session's folder; it also takes `tweaks`, a custom `viewport`, and, for a deck's PNG, `slide` (a number, or `"all"` for a zip of every slide). A page's PDF is as wide as its viewport, and PPTX slide images have twice the pixels. `design_system` reads, scans, and changes the project's design system (see **The design system**). The private renderer serves the bundle on a loopback address under a random path and gives Chromium no sign-in; other requests go through `host.fetchPublic`, so a design reaches only public addresses. Renders run 2 at once, and more wait their turn; each has 90 seconds.
72
+ - **What Pi does.** Its guide (a prompt section, only while the module is on) gives Pi an order of work, after Claude Design's (since 0.27.0): one round of questions when the work is new or unclear, then a start from what exists (the design system, the code, the screens) rather than a mock from scratch, a first version early, iterations, a check, and a short reply. A screen that exists is redesigned from itself: Pi reads its code and data first, makes version 1 the screen as it is today (in its place in the app, compared with a screenshot of the real one when it can get one), and then changes it in new versions, within what the code supports; a change that needs new data or server work is marked in the design and named in the reply, and a different direction becomes a new artifact in the same group. The product's own type sizes, spacing, and density win over the guide's craft defaults. It also gives Pi a page skeleton and craft rules: one HTML artifact for each design, `data-pid` on meaningful elements, a tweaks manifest of 3 to 8 knobs bound to the system's tokens, assets for images and fonts, variations as a group of 2 to 4 artifacts, a link to `ds/tokens.css` when the project has a design system, and a check with `design_preview` before it replies. When the project has a system, the guide carries a summary of it (roles and components first) as untrusted project data. Its tools: `design_preview` renders a version in a private headless Chromium (never the browser people watch) at mobile and desktop sizes, or the sizes asked for, and returns screenshots and a short report (see **Checks**); its options are `checks` (on by default), `tweaks`, `colorScheme`, `page` (another page of the bundle), and `actions` (hover, click, or focus on a selector before the screenshot). `design_export` writes PNG, PDF, PPTX, or an HTML zip, by default as `exports/<id>-v<version>.<ext>`, and refuses a path outside the session's folder; it also takes `tweaks`, a custom `viewport`, and, for a deck's PNG, `slide` (a number, or `"all"` for a zip of every slide). A page's PDF is as wide as its viewport, and PPTX slide images have twice the pixels. `design_system` reads, scans, and changes the project's design system (see **The design system**). The private renderer serves the bundle on a loopback address under a random path and gives Chromium no sign-in; other requests go through `host.fetchPublic`, so a design reaches only public addresses. Renders run 2 at once, and more wait their turn; each has 90 seconds.
73
73
  - **The design system.** A project's design system lives in `.pi/design/` in the session's folder: `tokens.json` (W3C Design Tokens, DTCG: groups, `$value`, `$type`, references such as `{color.blue.500}`, tiers for primitives, semantic roles, and component tokens), `tokens.<mode>.json` for each other mode (dark, high contrast, a brand), `components/<slug>.html` (a component specimen with its states), and `guidelines.md`. Pi Pocket checks it (broken or circular references, raw values in semantic roles, declared contrast pairs in every mode) and builds `dist/`: `tokens.css` (`:root`, a `[data-theme]` block for each mode, and a `prefers-color-scheme` block), `tailwind.css` (a Tailwind v4 `@theme`, with utilities such as `bg-surface` and `text-primary`), `tokens.<mode>.resolved.json` (DTCG, one for each mode), `tokens.studio.json` (Tokens Studio), `tokens.resolved.json` (a compact summary), and `components.css`. A design that links `ds/tokens.css`, `ds/tailwind.css`, or `ds/components.css` gets the current files as assets when Pi publishes it, a snapshot kept with that version. Pi's `design_system` tool has the actions `scan` (a structured draft from the project's style files: colors in every CSS syntax, roles, the type, spacing, and radius scales, shadows, motion, and dark mode, from CSS variables, Tailwind, SCSS, theme objects, token files such as Tokens Studio, and WordPress `theme.json`), `init` (from a scan or given tokens; it refuses to replace a system unless asked), `set`, `validate`, `compile`, `component`, `guidelines`, and the 0.26 `read` and `write`. A project with only `.pi/design-system.md` (the 0.26 format) keeps working.
74
74
  - **The System view.** The first row of the design picker (or `/design-open system`, or the launcher's "Open the design system") shows the system: **Colors** (role cards with contrast badges first, a live sample card, and the palette as ramp strips in a folded group), **Type**, **Spacing**, **Radii**, **Shadows** (each with its value), **Motion** (durations and easings that play), **Components** (every state, in a frame that runs nothing and loads nothing), and **Guidelines**. A section's count is its role tokens; the palette and component tokens show their own counts inside it. Modes show one at a time or side by side, and a mode's value says whether it is its own or inherited from the default. People who steer change a color, a size, a time, a weight, a font, an easing, or a shadow's layers in place, or link a token to another; the open design shows each change live when it uses the system's variables. The editor lists every contrast pair of a color (an exempt pair shows as exempt, not as a failure). **Undo** and **Redo** step through the changes, **Discard** gives them up, and **Save** writes the files and the generated CSS with no run of Pi (it refuses a change that the checks refuse, or one made on a system that changed meanwhile). The menu publishes the documentation page as a design, exports the generated files as a zip, and adds or removes a mode. People who only view see everything and change nothing. **Focus mode** hides the conversation for wide work. On a phone, the canvas fits the screen's width, and until a size is chosen it takes the size of its panel. The Design module loads only a small shell at app start; the workspace and the System view load when first opened.
75
75
  - **Checks.** A design's **Check** tab, `design_preview`, and `npm run design:check` (for CI: `src/server/design/check-cli.ts` on an HTML file and a `.pi/design` folder; exit 1 on an error, 2 without Chromium) render the page on the server and judge only what the author's CSS sets, never the browser's defaults. They report values that are not the system's (colors, fonts, and sizes, each with the exact CSS edit and the nearest token of the matching role), contrast (WCAG 2.2 AA, judged only where the background is certain), non-text contrast of focus rings and icon buttons (3:1), tap targets (an error under 24 px, a warning under 44 px), sideways overflow, image alt text, heading order, a missing `lang`, form controls with no label (a placeholder is not a label), links, buttons, and widgets with no accessible name, no `main` landmark, fonts that did not load, a missing viewport tag, missing `data-pid`s, elements with no visible focus style, long motion with no `prefers-reduced-motion` rule, and author-set input text under 16 px on a phone. A check runs in any mode of the system. The tab follows the mode and size on the canvas, puts a pin on each element, and **Send to Pi** puts one message with every finding in the message box. **Fix N exact matches** rewrites literals that equal a token exactly to `var(--token)` and saves a new version with no run of Pi. On a phone, the tab starts as a bar with the counts, so the page keeps most of the screen.
@@ -113,9 +113,9 @@ The full tour. For setup, see the [README](../README.md).
113
113
  - **Drop-in extensions.** Put your own extension module (a `.ts` file that default-exports `(host, web) => Extension`, or a list, or nothing) in `~/.pi-pocket/extensions/`. It shows in the Extensions sheet, stays off until the owner turns it on, can import Pi Pocket's packages (Pi Durable, pi-ai, Pi's MCP client pi-mcp, and the rest) as the built-in modules do, and reloads when edited. One that would take the name of a built-in extension or tool, or of another drop-in's, is not loaded, and the sheet says why: installing it would replace that one.
114
114
  - **Extensions in the app.** A module can add to the app itself, without changes to Pi Pocket's code: routes on the server, commands for the message box, and a browser module with buttons on the rail, pages in the conversation's place (as the subagents board shows), panels beside the conversation (where the Browser and Files panels dock, with a button in the top bar and the places), items in the status line under the message box (with a short form a narrow line takes), sheets, rows in the menu, and launcher actions, which work without asking Pi. A dashboard of a provider's usage, the server's load, or a machine's power and temperature, say: the route asks the service with a key that stays on the server, and the page shows what it says, live with the module's events. It is the owner's alone unless the module opens it to people who can steer, or to everyone who sees every session; someone invited to one session never gets it. A module can also show **public pages** to anyone with one of its links, with no sign-in (`/l/<token>`, since 0.22.0): each link closes at its time (30 days at most) or after the answers it takes, the page runs in a sandbox with no script, so whoever opens it while signed in lends it nothing, and Extensions says which modules have them ([docs/extensions/public-pages.md](extensions/public-pages.md)). Turning the module off takes away what it added, its pages included; an edit swaps the routes, and an edit to the browser module's files has tabs load it again. One that fails tells the owner why in a notice and in the Extensions sheet, and the rest of the app goes on; a tab opened with `?noext=1` loads none of their browser parts (safe mode), to turn off one that breaks the app. [docs/extensions.md](extensions/app.md) says how, with an example: a page with the server's load, memory, and uptime.
115
115
  - **Extension workspace APIs (0.16.0).** A page can save its own durable catalog with request-lifetime document commits, or use a source-bound route to start linked sessions as the person who clicked Run. Current source access, turn, plan, spend, team, and model checks apply; explicit thinking choices are not silently lowered. Human history can open authorized sessions through `pocket.openConversation`. Extensions can read the running server's package version through `host.pocketVersion` or browser `pocket.pocketVersion`, without an updater or restart control; the extension API level remains 1.
116
- - **Extensions hub.** Menu → **Extensions** opens **Discover**, **Installed**, and **Updates** for the owner while the gallery is on. Wide screens show the list and selected entry side by side; phones show one at a time, with Back returning to the filtered list. **Installed** (also tap "guard" in the status line) lists Pi Pocket's extensions with their tools, the routes, commands, and browser module they add to the app, and any load error, in this browser too. The owner can turn Artifacts, Design, Browser, Subagents, Scheduled messages, Done when, Plan mode, Codemode, Memory, PiP, Triggers, Extension gallery, Pi Pocket updates, Agent Teams, Session tags, Lancet Guard, or a drop-in off and on, or reload one; the change applies to every session at once, stays after restarts (`disabledExtensions` and `enabledExtensions` in `~/.pi-pocket/config.json`), and everyone in a session sees who changed what. Turning Lancet Guard off first shows a warning card with **Keep it on** and **Turn off**; only **Turn off** applies the change. This leaves Pi's own setting (`~/.pi/lancet-guard.json`) alone. Under PiP, the owner picks when PiP compacts its context. The system prompt cannot be turned off.
116
+ - **Extensions hub.** Menu → **Extensions** opens **Discover**, **Installed**, and **Updates**, as tabs in the sheet's head, for the owner while the gallery is on. Wide screens show the list and the selected entry side by side; phones show one at a time, with Back returning to the filtered list. The list is in sections: **Extensions** as dense rows divided by hairlines (a small mark, the name and its maker, one line about it, and up to three facts of what it reaches or adds, such as `openrouter.ai`, `a key`, `sees turns`, or `2 tools`), and **Themes** as cards, each a tiny desktop drawn in the theme's own colors with its color dots (since 0.27.0). Filters narrow Discover to **Extensions** or **Themes**, and to those with **Tools for Pi**, a part **In the app**, or ones that **Change Pi** (hooks, prompt sections, wraps). **Installed** (also tap "guard" in the status line, which opens it with **Built in** unfolded) lists your **Extensions** (from the gallery and your own drop-ins) first, each with how it stands now: **On**, **Off**, **Did not load** (with the error under it), **Off in this tab** (its browser part failed here), **Edited since install**, or **Revoked**; then your **Themes** (from the gallery, and your own, marked **Yours**, which open Appearance); then the **Built in** modules, folded under one line that says how many are on, and unfolded by a search or a module that did not load. A module's row shows its tools, the routes, commands, and browser module it adds to the app, and any load error, in this browser too. The owner can turn Artifacts, Design, Browser, Subagents, Scheduled messages, Done when, Plan mode, Codemode, Memory, PiP, Triggers, Extension gallery, Pi Pocket updates, Agent Teams, Session tags, Lancet Guard, or a drop-in off and on, or reload one; the change applies to every session at once, stays after restarts (`disabledExtensions` and `enabledExtensions` in `~/.pi-pocket/config.json`), and everyone in a session sees who changed what. Turning Lancet Guard off first shows a warning card with **Keep it on** and **Turn off**; only **Turn off** applies the change. This leaves Pi's own setting (`~/.pi/lancet-guard.json`) alone. Under PiP, the owner picks when PiP compacts its context. The system prompt cannot be turned off.
117
117
  - **Extension settings.** A module can declare settings (on or off, text, a number, a choice, or a secret such as an API key); the owner changes them in Menu → Extensions under the module, with **Save settings**, and **Default** or **Clear** to put one back. A secret's value never leaves the server: the sheet shows only that it is set. Modules can also listen to what happens in the app (sessions made, renamed, and archived, messages, runs) and offer services to each other; Extensions says which ones offer a service. Since 0.22.0 ([docs/extensions/services-settings.md](extensions/services-settings.md)).
118
- - **Extension gallery.** Menu → Extensions → **Discover** (or **Find extensions** in the launcher) lists drop-ins other people wrote, from a reviewed index ([TannerMidd/pi-pocket-extensions](https://github.com/TannerMidd/pi-pocket-extensions) unless the owner picks another): search them by name, words, and tags; entries for a newer Pi Pocket are hidden. Each row has a quiet **Install**. An entry walks through three steps, each with its buttons: **Install** (it stays off), **Look it over** (**View source**, **Ask Pi to review**), and **Turn it on**, which asks once more, in place, before code runs; what it adds shows in plain words, with technical information folded below. In Installed, a tap on a row opens its settings and details, and turning a drop-in on asks in its row. An entry shows who wrote it, where its code is (a GitHub repository at a pinned commit), its files, and what it declares: its tools (and which only read), hooks, prompt sections, wraps, routes, and browser module, and who can reach them. **Install** downloads its files over https from that commit, checks each against the SHA-256 the index pins (one that differs installs nothing), and puts them in the extensions folder, off, as every drop-in starts. Before turning it on, read its whole source in the gallery, or **Ask Pi to review**: a new session in the extensions folder, in plan mode, where Pi audits what the code reads (`config.json`, sign-ins, other secrets), the addresses it calls, the processes it starts, what its browser module does, and whether it does what it declares. Updates are never automatic: the **Updates** tab lists available updates with a **Review update** button, and the review shows what changes, as a diff of every file and of what it declares, before you apply it. When the index revokes the version you have, the gallery and Extensions say why and offer to turn it off, and a notice says so while it is on. **Uninstall** removes its files (where each came from is kept in `<name>.gallery.json` beside it). **Share…** on one of your own drop-ins in Extensions checks that it stands on its own (its files named after it, importing only Pi Pocket's packages and its own files), drafts its index entry (the description from its doc comment, each file's SHA-256, what it declares while it is on), asks where its files are on GitHub (the repository and commit you put them in, tags, your GitHub name), and, once the entry would pass the index's checks, opens GitHub's page for a pull request to the index with the entry filled in; Pi Pocket itself makes no GitHub calls. [docs/extensions.md](extensions/publishing.md) says how to publish. The owner's alone; turned off in Extensions, it reads nothing. It lists themes too, with a **Theme** tag and filter: **Install** checks a theme's pinned files and its CSS before it goes into `themes/`, and puts it in Appearance's list without applying it; **Update** shows a diff; **Remove** moves it to `themes/.removed/`; **Share…** in Appearance drafts an entry for one of your own themes ([themes.md](extensions/themes.md#themes-in-the-gallery)).
118
+ - **Extension gallery.** Menu → Extensions → **Discover** (or **Find extensions** in the launcher) lists drop-ins other people wrote, from a reviewed index ([TannerMidd/pi-pocket-extensions](https://github.com/TannerMidd/pi-pocket-extensions) unless the owner picks another): search them by name, words, and tags; entries for a newer Pi Pocket are hidden. Each row has a quiet **Install**, which installs it turned off. An entry (since 0.27.0) says **What it can reach** in plain sentences, each marked with where it comes from: **In its code** (from the scan below: "Talks to openrouter.ai", "Uses your openrouter key, from Pi", "Runs git and gh", "Uses files in its data folder"), **Declared** (the hooks it sees with, such as "Sees tool calls, before they run", and changes to Pi's instructions or tools), and **Always** (it runs in the server with your rights, in every session, where Lancet Guard does not see its code), then what the scan found nothing for. The scan reads the code's text, so the code can reach more than it finds: the entry says so, and nothing claims an extension stays inside. When the installed files were edited since install, the entry and the question say that the summary is the pinned version's, not what runs. **What it adds** shows its tools and commands as code, and what it puts in the app; technical information is folded below. **Install and turn on** asks one question over the sheet: what it reaches, with **Cancel**, **Install turned off**, and **Install and turn on** (Cancel has the focus, Escape closes only the question, and the question stays until it is installed and on); **Install turned off** installs it without asking, and an installed one that is off has **Turn on**, which asks the same question. Before turning it on, read its source with **View source**, or install it off and **Ask Pi to review**. A theme's entry shows its picture in its own colors (dark and light side by side when it has both), what it changes from its files (its colors, a layout of its own, its fonts, its images), its palette with the values, and **Use it in this browser** and **Open Appearance** once installed. In **Updates**, a row says what an update adds to what the extension declares ("Declares more: sees tool results; 2 new tools", or "Declares nothing new") before its review; its code's changes are in the review's diff. In Installed, a tap on a row opens its settings and details, and turning a drop-in on asks in its row. An entry shows who wrote it, where its code is (a GitHub repository at a pinned commit), its files, and what it declares: its tools (and which only read), hooks, prompt sections, wraps, routes, and browser module, and who can reach them. **Install** downloads its files over https from that commit, checks each against the SHA-256 the index pins (one that differs installs nothing), and puts them in the extensions folder, off, as every drop-in starts. Before turning it on, read its whole source in the gallery, or **Ask Pi to review**: a new session in the extensions folder, in plan mode, where Pi audits what the code reads (`config.json`, sign-ins, other secrets), the addresses it calls, the processes it starts, what its browser module does, and whether it does what it declares. Updates are never automatic: the **Updates** tab lists available updates with a **Review update** button, and the review shows what changes, as a diff of every file and of what it declares, before you apply it. When the index revokes the version you have, the gallery and Extensions say why and offer to turn it off, and a notice says so while it is on. **Uninstall** removes its files (where each came from is kept in `<name>.gallery.json` beside it). **Share…** on one of your own drop-ins in Extensions checks that it stands on its own (its files named after it, importing only Pi Pocket's packages and its own files), drafts its index entry (the description from its doc comment, each file's SHA-256, what it declares while it is on), asks where its files are on GitHub (the repository and commit you put them in, tags, your GitHub name), and, once the entry would pass the index's checks, opens GitHub's page for a pull request to the index with the entry filled in; Pi Pocket itself makes no GitHub calls. [docs/extensions.md](extensions/publishing.md) says how to publish. The owner's alone; turned off in Extensions, it reads nothing. It lists themes too, with a **Theme** tag and filter: **Install** checks a theme's pinned files and its CSS before it goes into `themes/`, and puts it in Appearance's list without applying it; **Update** shows a diff; **Remove** moves it to `themes/.removed/`; **Share…** in Appearance drafts an entry for one of your own themes ([themes.md](extensions/themes.md#themes-in-the-gallery)). **What an entry reaches.** `GET /api/x/gallery/reach` (the owner's, like the other gallery routes) answers `{ entries: { [name]: … } }` for every entry of the index read now, each with the entry's `pin` so the app matches a result to the exact files it shows, so the app can show what each one can reach before it is installed. An extension gives `{ kind: "extension", commit, scanned: { network, keys, programs, files } }`: short words for the hosts its address literals name (`localhost`, standards' namespaces, `example.*`, and repository pages left out; `addresses it builds at run time` when it calls `fetch(`, `new WebSocket(`, or `http.request` with no host in its code), the keys it reads (`openrouter key from Pi`, an environment variable whose name has `KEY`, `TOKEN`, or `SECRET`, `Pi's auth.json`), the programs it starts (`programs it names at run time` when it imports `child_process` but names none), and the files it writes (`its data folder`, paths under `~/.pi/agent/`, or `your home folder`). The scan is by literal patterns on the code with its comments taken out: it tells what the code says, not what it does. A theme gives `{ kind: "theme", commit, palette: { colors, colorsLight } }` from its `colors.toml` and `colors-light.toml` (`null` for one it lacks). An entry that cannot be read (a download fails, or a file differs from the size or SHA-256 the index pins) gives `{ kind, commit, error }` and fails no other entry. Only the code files (`.ts`, `.js`, `.mjs`, `.cjs`) and the two palette files are read: from the installed copy when the entry is installed at the same commit and each file is as pinned, otherwise downloaded from the pinned commit with the checks every download has. Results are kept in `gallery/reach.json` in the data folder, by entry, commit, and pinned files, so the next answer downloads nothing for them; entries that fail are tried again, and three are read at a time.
119
119
  - **Updates.** Menu → **Update Pi Pocket** (or the launcher) shows the running version, the newest release with its notes, and **Update to … and restart**; a notice says once when a new version is out. The owner's alone. Under the version, the sheet shows the checkout's branch and commit, **installed with npm (global)**, **installed with npm (local)**, or **run with npx**. For npm installs, Pi Pocket asks the npm registry's `latest` tag for the newest published version 2 minutes after the server starts and every 6 hours after, and GitHub for that version's release notes (`PI_POCKET_UPDATES_REPO` names another repository). A git checkout asks GitHub for the newest release (or the repository's version tags, without notes) and downloads its commit into the checkout under a ref of its own, `refs/pocket-update/target`. An update from a git checkout needs a checkout that the server's user can write, run by the launcher (`npm start`), with no changes that are not committed and no commits the release lacks, and a Node.js the release runs on; the sheet says which of these stands in the way, and an ignored file of yours where the release has a file stops it too. It installs the release's packages beside the checkout first (`npm ci` in `.pocket-update/staging/`, only when the lock file names other packages), stops loading edited files, puts the packages in place, moves the branch forward to the release's commit (a detached checkout moves detached), and restarts. **A global npm install** updates from the app too, when the server's user can write the folder that holds the package and the launcher runs the server: Pi Pocket installs the exact published version into a staging folder beside the package, swaps it in place of the running copy, and restarts, with the copy before kept next to it. If the machine stops at the very moment of the swap, `pi-pocket` may not start: `npm install -g pi-pocket` puts it back. A **local** npm install (in a project's `node_modules`) and a copy **run with npx** do not update from the app: the sheet lists what stands in the way, with the server's hint of what to run instead (`npm install pi-pocket@latest` in the project, or `npx pi-pocket@latest`), and the update button stays off. The owner runs the command and restarts. Running work continues through a restart, but a tool call the restart cuts off comes back as interrupted, and the sheet says when Pi works. When the new version does not start, the launcher puts the files before back and starts that (a git checkout puts the commit and packages back; a global npm install swaps the kept copy back, with no network), and the sheet and a notice say what happened; after the next look the sheet offers that version again, for the owner to try again. A release whose notes have a `[!WARNING]` or `[!CAUTION]` alert needs a tick that you read it, and is not undone by itself, since it may change data one way; so does a release whose notes Pi Pocket could not read because GitHub did not answer (the registry or the tag gave the version, with no notes), since they may have such an alert: read them on GitHub. Under Menu → Extensions → Installed → **Pi Pocket updates**: **Look for new versions** (on), **Install new versions by themselves** (off), and **Beta updates** (off). **Beta updates** (since 0.27.0) also offers pre-releases, tagged `vX.Y.Z-beta.N` (GitHub releases marked as pre-release; npm's `beta` dist-tag): a git checkout takes the highest version among GitHub's non-draft releases (or the beta tags, when GitHub does not answer), and an npm install the newer of the `latest` and `beta` dist-tags. A beta is marked **Beta** in the sheet, the menu hint, and the notice, and its caution says that it may have bugs. With the setting off nothing changes: only stable releases are offered, a beta is never offered, and a running beta still gets the next stable release (`0.27.0` is newer than `0.27.0-beta.N`, and `0.27.0-beta.2` is newer than `0.27.0-beta.1`) but never an older one. Turning it off drops a beta found before. An install by itself also takes a beta, when both settings are on. A server from before 0.27.0 needs a restart (menu → Restart server) for the setting to work. An install by itself waits until no session has worked for 10 minutes, and again after its packages install; it never takes a release with a warning or without notes, or one that failed before (did not start, or did not install). A launcher started before this feature restarts but does not go back, and cannot update a global npm install at all (the sheet says so): quit Pi Pocket and start it again once.
120
120
  - **Refresh models.** The owner can tap **Refresh models** in the menu (under App) or the Providers sheet (above Models for subagents), or run **Refresh models** from the Ctrl/⌘+K launcher. The same controls work on phones. Refresh reloads `models.json` and Pi’s sign-ins, and asks configured providers for fresh catalogs. The menu's row says when it is refreshing, and a notice gives the added and removed model counts, without closing the menu; the Providers sheet also shows the errors for individual providers. All connected tabs receive the updated list. Healthy providers finish independently of slow ones; each provider has an eight-second limit. Running sessions keep their chosen models. A local model must be configured in `models.json` or registered by a Pocket-compatible extension: refresh does not load regular Pi CLI extensions or discover arbitrary local servers.
121
121
  - **Uploads.** In normal chat and PiP, attach files with the picker, paste files or images, or drop them into the message box. Files are saved on the server for the conversation you send to and their paths are given to the agent; supported images also go straight to models that accept them.
package/docs/map.md CHANGED
@@ -18,25 +18,25 @@ A module split into parts keeps its name for the part others import, with the re
18
18
 
19
19
  ### The core
20
20
 
21
- | File | Owns |
22
- | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23
- | `main.ts` | The server process: options, the port, signals, then `PocketApp.open` and `createHandler` |
24
- | `app.ts` | `PocketApp`: opening the harness, reading state back at startup (`#recover`), the commit coordinator (`#committed`), connected tabs and their peek tiles, access checks (`canSee`, `requireSteer`, `requireDriver`), the session list (each session's subagents counted by state), every subagent for the subagents board (`subagents`, `setBoard`), `hello`, model list with Pi’s enabledModels scope (`modelList`), extensions on and off Bundle readers for artifacts (`artifactBundle`: the page and its assets by hash, `artifactAsset`: one manifest asset), which callers must check access for. |
25
- | `attribution.ts` | Who Pi works for: who wrote each message to Pi or whose work it is (authors documents, from request ids), who queued each submission; read back at startup |
26
- | `room.ts` | One conversation's live view for its tabs: Pi Durable's view plus `ROOM_DOCS`, sent every 90 ms as changes; its peek tile (`peek`, at most once a second) for the tabs that show it (`PocketApp.setPeeks`) |
27
- | `projection.ts` | Entries as compact JSON for browsers; `usageCost` |
28
- | `timing.ts` | Every model stream timed: when it started, its first token, and its end, stamped on the response for the status line's speed |
29
- | `limits.ts` | Reads a failed model request (error text, status, limit headers) and says whether it is a limit that clears with time, until when, and for whom (the account or one model). Pure functions |
30
- | `limit-gate.ts` | The limit gate around every model stream: a request that hits such a limit waits, one canary goes out, then the rest leave one by one; Stop and Interrupt end a wait; `provider-limits.json`; what the views and the session list show of a wait |
31
- | `cache-keeper.ts` | The prompt cache keeper around every model stream: replays a tool-call request with one output token just before its 5-minute cache expires, when that costs less than a rebill; stops on a real request, run end, error, shutdown, or 30 minutes; warm usage counts in spend |
32
- | `entry-format.ts` | The kinds of Pi Pocket's own entries, and the markers it writes into message text (`[from: …]`, attached files). Stored data and the web app depend on their exact values |
33
- | `fence.ts` | Text from elsewhere between tags as data, for Pi: no closing tag survives inside it |
34
- | `docs.ts` | Every durable document Pi Pocket defines The design workspace's `pocket.design-comments` (comments, tweaks, restores) and the artifact bundle documents (`pocket.artifact-asset`, by content hash). |
35
- | `host.ts`, `reload.ts` | `PocketHost` (what extensions get) and `Approvals`; the extension loader: built-ins in `ORDER`, drop-ins (never with a name Pi Pocket keeps, `BUILT_IN_TOOLS`), live reload |
36
- | `extension-web.ts` | What extension modules add to the app (`web`, their default export's second argument): routes, the browser module and its files' versions, events to it, commands (`BUILT_IN_COMMANDS`), cleanups; who may use each (`mayUse`), `POCKET_API` |
37
- | `lock.ts` | One process per data folder |
38
- | `errors.ts`, `paths.ts` | `HttpError`, `describe`, and input checks; `~` paths |
39
- | `zip.ts` | `zip(entries)`: a ZIP32 archive in memory with CRC32, UTF-8 names, and deflate, with no dependency; Design's PPTX and HTML exports use it |
21
+ | File | Owns |
22
+ | ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
23
+ | `main.ts` | The server process: options, the port, signals, then `PocketApp.open` and `createHandler` |
24
+ | `app.ts` | `PocketApp`: opening the harness, reading state back at startup (`#recover`), the commit coordinator (`#committed`), connected tabs and their peek tiles, access checks (`canSee`, `requireSteer`, `requireDriver`), the session list (each session's subagents counted by state; for Priority, the oldest waiting call and how many wait (`approval`), a failed run's reason (`failure`), and failed subagents nobody dealt with (`failedAgents`)), every subagent for the subagents board (`subagents`, `setBoard`), `hello`, model list with Pi’s enabledModels scope (`modelList`), extensions on and off Bundle readers for artifacts (`artifactBundle`: the page and its assets by hash, `artifactAsset`: one manifest asset), which callers must check access for. |
25
+ | `attribution.ts` | Who Pi works for: who wrote each message to Pi or whose work it is (authors documents, from request ids), who queued each submission; read back at startup |
26
+ | `room.ts` | One conversation's live view for its tabs: Pi Durable's view plus `ROOM_DOCS`, sent every 90 ms as changes; its peek tile (`peek`, at most once a second) for the tabs that show it (`PocketApp.setPeeks`) |
27
+ | `projection.ts` | Entries as compact JSON for browsers; `usageCost` |
28
+ | `timing.ts` | Every model stream timed: when it started, its first token, and its end, stamped on the response for the status line's speed |
29
+ | `limits.ts` | Reads a failed model request (error text, status, limit headers) and says whether it is a limit that clears with time, until when, and for whom (the account or one model). Pure functions |
30
+ | `limit-gate.ts` | The limit gate around every model stream: a request that hits such a limit waits, one canary goes out, then the rest leave one by one; Stop and Interrupt end a wait; `provider-limits.json`; what the views and the session list show of a wait |
31
+ | `cache-keeper.ts` | The prompt cache keeper around every model stream: replays a tool-call request with one output token just before its 5-minute cache expires, when that costs less than a rebill; stops on a real request, run end, error, shutdown, or 30 minutes; warm usage counts in spend |
32
+ | `entry-format.ts` | The kinds of Pi Pocket's own entries, and the markers it writes into message text (`[from: …]`, attached files). Stored data and the web app depend on their exact values |
33
+ | `fence.ts` | Text from elsewhere between tags as data, for Pi: no closing tag survives inside it |
34
+ | `docs.ts` | Every durable document Pi Pocket defines The design workspace's `pocket.design-comments` (comments, tweaks, restores) and the artifact bundle documents (`pocket.artifact-asset`, by content hash). |
35
+ | `host.ts`, `reload.ts` | `PocketHost` (what extensions get) and `Approvals`; the extension loader: built-ins in `ORDER`, drop-ins (never with a name Pi Pocket keeps, `BUILT_IN_TOOLS`), live reload |
36
+ | `extension-web.ts` | What extension modules add to the app (`web`, their default export's second argument): routes, the browser module and its files' versions, events to it, commands (`BUILT_IN_COMMANDS`), cleanups; who may use each (`mayUse`), `POCKET_API` |
37
+ | `lock.ts` | One process per data folder |
38
+ | `errors.ts`, `paths.ts` | `HttpError`, `describe`, and input checks; `~` paths |
39
+ | `zip.ts` | `zip(entries)`: a ZIP32 archive in memory with CRC32, UTF-8 names, and deflate, with no dependency; Design's PPTX and HTML exports use it |
40
40
 
41
41
  `extension-request.ts` owns extension routes' request-lifetime document/context capabilities and fresh person/source authorization. `http/extension-routes.ts` binds named source parameters and supplies human linked-session capabilities. `linked-sessions.ts` keeps the short final-admission lease; its child context watches policy publications and checks current config when Durable enters admission. `models.ts` supplies exact local `host.modelInfo` metadata. `versions.ts` supplies `host.pocketVersion` and `hello.server.pocketVersion`, read by browser `pocket.pocketVersion`; `pocket.openConversation` delegates to normal `store.navigate`.
42
42
 
@@ -171,6 +171,7 @@ The agent's side of Design mode. `extensions/design.ts` installs it (see Extensi
171
171
  | `gallery/files.ts`, `gallery/fetch.ts` | An extension's files in the drop-in folder: names checked, never through a link, a version put in place all or none with an undo journal that `recover` replays before extensions load; reading from other sites, https only, within size and time limits |
172
172
  | `gallery/diff.ts`, `gallery/share.ts` | A file's change as a unified diff, for updates; whether a drop-in stands on its own, and the draft of its entry, for Share |
173
173
  | `gallery/themes.ts` | Themes from the gallery in the data folder's `themes/`: a version written to a hidden folder, checked with `readTheme`, then put in place in one rename; the `.gallery.json` provenance in each; recovery at the start |
174
+ | `gallery/reach.ts` | What an entry can reach, by literal patterns on its code with comments taken out (hosts, keys, programs, files), a theme's palettes, and the results kept in `gallery/reach.json`; behind `GET /api/x/gallery/reach` |
174
175
  | `lancet.ts` | Loads Lancet Guard from Pi's install, and downloads its model on request |
175
176
  | `omarchy.ts` | The Omarchy desktop's current theme and wallpaper, read-only, for Follow desktop (`/api/theme`) |
176
177
  | `themes.ts`, `themes/` | Theme folders (`app.themes`): the built-in ones in `web/themes/` and the owner's in the data folder's `themes/`, read and checked (`themes/format.ts`: `theme.json`, `colors.toml`, limits; `themes/css.ts`: CSS's tokens and the files it loads), each one's last good version, watching, Duplicate, Remove, Edit with Pi |
@@ -214,13 +215,13 @@ Plain ES modules, loaded as they are. `store.js` holds the shared state, and not
214
215
  | `sheets.js` | Which sheet is open, the component that shows it, and the nested-sheet back action supplied to `Sheet` through `SheetBack` |
215
216
  | `sheets/*.js` | One sheet (or a few close ones) each: the model and branch pickers, folder, extensions, providers, people and invites, the file viewer (`FileView`, which the Files tile shows too), find, spend, running now, schedules, webhooks, memory (the lessons Pi keeps, with the menu's hint), worktree, Pi's terminal sessions, appearance, shortcuts, the menu, a session's actions, the extension gallery (`gallery.js`: browsing, an entry, its source, an update, sharing; `galleryAvailable`), with the artifact viewer's **Open in Design** button (`viewers.js`) |
216
217
  | `peeks.js` | Peek tiles: their switches (the top bar's and the rail's), which sessions get one and in what order (working, waiting, with subagents at work, finished, or pinned), the column and the strip, each tile's subagents at work (the first few as rows, the rest counted, opening the board at them) and their own peeks, the watch list |
217
- | `seen.js` | What this browser has seen: when it last looked at each session (`markSeen`), which runs ended since (`finishedUnseen`), and the server's clock (`fromServer`). Peek tiles and the session list's squares read it |
218
+ | `seen.js` | What this browser has seen: when it last looked at each session (`markSeen`), which runs ended since (`finishedUnseen`), and the server's clock (`fromServer`). Peek tiles and the session list's squares read it; the list also puts looks back (`seenSnapshot`, `restoreSeen`) when it undoes marking sessions read |
218
219
  | `clock.js` | The server's clock as a tab knows it, without the DOM: how far it is ahead of this browser's, fitted to what each hello proves, so a hello handled late (a tab woken from the background) moves no time shown |
219
220
  | `chat.js` | People panel: presence roster, take-turns shortcut, chat bubbles, pins, notes; the chat sheet |
220
221
  | `avatar.js` | People's avatars and colors, and folders' colors |
221
222
  | `subagents-board.js` | The subagents board: every subagent in every session (the server's `subagents` events, while it shows), soft state-colored cells and rounded session rows, a sub-tile for each at work saying what it does now, the proportional state bar and filter pills, Needs you, the selected detail card (its peek), the arrows, and the phone's layout |
222
223
  | `extension-ui.js` | Extensions' browser modules: loading them as `hello` lists them (`server.ui`), `pocket` (the app's API for them), and what they add: rail buttons (`ExtensionRailButtons`), menu rows, launcher actions, pages in the conversation's place (`ExtensionPage`, `state.page`), panels beside it (`ExtensionPanel`, `state.extPanel`, with `ExtensionPanelButtons` in the top bar and `extensionPlaces` in the places), status-line items (`extensionStatusItems`, drawn by `composer.js`), sheets (`ExtensionSheet`), and the session list's chips, words, filters, and actions (`sessionChips`, `sessionWords`, `sessionFilters` and `sessionFilterTest`, `sessionActions`, drawn by `sessions.js`, `sheets/session.js`, and `launcher.js`); one that fails, alone, and how their tools' calls show (`pocket.toolCall`, given to `calls.js` and `turns.js`) |
223
- | `sessions.js` | The sidebar: the rail (`RailNav`: the tools, you, and, folded, numbered sessions) and the session list beside it (sidebar, drawer, a phone's home screen), a line per session, with extensions' chips under its title; extensions' filters beside the search; selecting rows and archiving them with undo (`setArchived`), and extensions' actions in the bar for them, and a touch screen's long press on a row, which opens `sheets/session.js`; linked sessions under the one that started them, with branch lines (`session-tree.js`, the tree as data) |
224
+ | `sessions.js` | The sidebar: the rail (`RailNav`: the tools, you, and, folded, numbered sessions) and the session list beside it (sidebar, drawer, a phone's home screen), a line per session, with extensions' chips under its title; extensions' filters beside the search; selecting rows and archiving them with undo (`setArchived`), and extensions' actions in the bar for them, and a touch screen's long press on a row, which opens `sheets/session.js`; linked sessions under the one that started them, with branch lines (`session-tree.js`, the tree as data); and Priority (`priorityGroups`, `slotOf`, `needOf`): sessions by what they ask of you, with a call open in its row (`NeedAsk`), dismissing failures, and marking sessions read, each with an undo where one is possible; the rail's count of sessions that need you (`needsYouCount`) |
224
225
  | `home.js`, `signin.js` | The wide home screen; the sign-in screen |
225
226
  | `notify.js`, `sw.js` | Push, the icon badge, approvals from notifications, shares; the notifications sheet |
226
227
  | `share.js` | Share to Pi |
package/docs/releases.md CHANGED
@@ -4,13 +4,12 @@ Pi Pocket ships a stable release every Friday. Between two Fridays, the next rel
4
4
 
5
5
  ## The week
6
6
 
7
- | When | What happens |
8
- | ----------------------- | ------------------------------------------------------------------------------------------------------- |
9
- | Friday, after a release | The branch of the next release opens: `release/X.Y.0`, from `main`. |
10
- | Saturday to Wednesday | Ready pull requests merge into the release branch. A beta comes out when something worth trying lands. |
11
- | Wednesday, end of day | Code freeze: from now on, only fixes go into the release branch. The last beta comes out. |
12
- | Thursday | The review and live-test rounds run on the release branch, and their fixes go in. |
13
- | Friday | The release pull request merges into `main`. The tag `vX.Y.0` and the GitHub release publish it to npm. |
7
+ | When | What happens |
8
+ | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
9
+ | Friday, after a release | The branch of the next release opens: `release/X.Y.0`, from `main`. |
10
+ | Saturday to Thursday | Ready pull requests merge into the release branch. A beta comes out when something worth trying lands. |
11
+ | Thursday, end of day | Code freeze: from now on, only fixes go into the release branch. The last beta comes out. |
12
+ | Friday | The review and live-test rounds run on the release branch, and their fixes go in. Then the release pull request merges into `main`, and the tag `vX.Y.0` and the GitHub release publish it to npm. |
14
13
 
15
14
  A week with nothing to ship has no release. A change that is not ready by the freeze waits for the next week.
16
15
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "pi-pocket",
3
- "version": "0.27.0-beta.4",
3
+ "version": "0.27.0-beta.6",
4
4
  "description": "A durable, multiplayer, mobile-first web app for Pi agents, built on Pi Durable",
5
5
  "keywords": [
6
6
  "pi",
@@ -44,7 +44,7 @@
44
44
  "start": "node bin/pi-pocket.js",
45
45
  "dev": "node bin/pi-pocket.js --cwd .",
46
46
  "check": "tsc --noEmit -p . && node test/types-file.ts && node docs-site/check-reference.mjs",
47
- "test": "node --test test/*.test.ts",
47
+ "test": "node --test --test-concurrency=4 test/*.test.ts",
48
48
  "design:check": "node src/server/design/check-cli.ts",
49
49
  "site:publish": "gh workflow run pages.yml",
50
50
  "format": "eslint --fix . && prettier --write .",