repositories / pi-ext

pi-ext

bugabingas pi extensions

owned by bugabinga

Format ui phase plans

30c3d2cbc6af9a7b3a1b45a9a29a136b2268de8a

Oliver Krylow <o.krylow@isp-insoft.de> ·

unsigned

Browse filesCompare with HEAD

Changed files (6)

docs/super/plans/2026-07-01-ui-extension-phase-2-rpc-session-stream.md

Modified
1 -# UI Extension Phase 2 Implementation Plan
3 -> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 -**Goal:** Make `/ui` a minimal browser Pi frontend backed by a seeded active-branch RPC subprocess.
7 -**Architecture:** Keep Phase 1 server/runtime as owner. Add active-branch session seeding, a Pi RPC child-process bridge, a small event protocol, WebSocket fanout, and a no-framework browser shell that renders snapshots plus ordered events.
9 -**Tech Stack:** Node `child_process`, `fs`, `readline`, `crypto`; Pi `SessionManager`; browser WebSocket, Web Components, CSS; Vitest harness tests.
11 -**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 -**Phase:** Phase 2: Active-Branch RPC Session and Basic Web Stream
15 ----
17 -## Scope
19 -Included:
21 -- Seed a persistent web session from `ctx.sessionManager.createBranchedSession(ctx.sessionManager.getLeafId())`.
22 -- Spawn `pi --mode rpc --session <seeded-session>` with normal extensions/skills/settings.
23 -- Parse LF-delimited JSONL from RPC stdout and keep stderr diagnostics separate.
24 -- Add RPC request queue with ids, timeout, startup, death, and slow-start states.
25 -- Add `/api/snapshot`, `/ws`, event replay buffer, monotonic event ids, and JSON protocol types.
26 -- Replace Phase 1 shell page with a basic stream-first browser app and composer.
27 -- Send browser prompts through RPC and render user/assistant/tool/error stream items.
29 -Excluded:
31 -- Full slash-command parity.
32 -- Rich syntax/autocomplete.
33 -- Visual widgets.
34 -- Telemetry.
35 -- Nugu polish beyond readable brutal defaults.
37 -## Files
39 -Create:
41 -- `extensions/ui/session-seed.ts` — active-branch seed path and warnings.
42 -- `extensions/ui/rpc.ts` — child process, JSONL parser, request queue, lifecycle.
43 -- `extensions/ui/protocol.ts` — event/snapshot/request types.
44 -- `extensions/ui/events.ts` — monotonic event store and replay.
45 -- `extensions/ui/web/app.html.ts` — HTML shell.
46 -- `extensions/ui/web/app.css.ts` — minimal stream-first CSS.
47 -- `extensions/ui/web/app.js.ts` — browser app source emitted by server.
48 -- `extensions/ui/__tests__/session-seed.test.ts`.
49 -- `extensions/ui/__tests__/rpc.test.ts`.
50 -- `extensions/ui/__tests__/events.test.ts`.
51 -- `extensions/ui/__tests__/web-smoke.test.ts`.
53 -Modify:
55 -- `extensions/ui/runtime.ts` — own seed, RPC, event store.
56 -- `extensions/ui/server.ts` — add snapshot, app assets, WebSocket upgrade.
57 -- `extensions/ui/index.ts` — pass command context into runtime start.
58 -- `extensions/ui/terminal-widget.ts` — show RPC startup/connected/dead states.
59 -- `extensions/ui/package.json` — add `ws` and `@types/ws` if native upgrade handling is not enough.
61 -## Tasks
63 -### Task 1: Event protocol and store
65 -- [x] Write `events.test.ts` for monotonic ids, bounded replay, and snapshot shape.
66 -- [x] Implement `protocol.ts` and `events.ts` with `UiEvent`, `UiSnapshot`, `EventStore.append`, `EventStore.snapshot`, and `EventStore.replayAfter`.
67 -- [x] Run `npx vitest run extensions/ui/__tests__/events.test.ts`; expect PASS.
68 -- [x] Commit `Add ui event protocol`.
70 -### Task 2: Active-branch session seed
72 -- [x] Write `session-seed.test.ts` using a fake session manager with `getLeafId()` and `createBranchedSession()`.
73 -- [x] Implement `session-seed.ts` so the default path calls `createBranchedSession(getLeafId())` and returns `{ path, warning: undefined }`.
74 -- [x] Add fallback warning only when whole-tree `forkFrom` is explicitly used by option.
75 -- [x] Run `npx vitest run extensions/ui/__tests__/session-seed.test.ts`; expect PASS.
76 -- [x] Commit `Add ui active branch session seed`.
78 -### Task 3: RPC bridge
80 -- [x] Write `rpc.test.ts` for JSONL parsing, request id matching, stderr capture, timeout, process exit event, and slow-start event.
81 -- [x] Implement `rpc.ts` with `startRpc`, `sendRpc`, `closeRpc`, `parseJsonLines`, and typed lifecycle callbacks.
82 -- [x] Make subprocess command resolve to `pi.cmd` on win32 and `pi` elsewhere unless `PI_UI_RPC_BIN` overrides it for tests.
83 -- [x] Run `npx vitest run extensions/ui/__tests__/rpc.test.ts`; expect PASS.
84 -- [x] Commit `Add ui rpc bridge`.
86 -### Task 4: Server snapshot and WebSocket stream
88 -- [x] Write server tests for authenticated `/api/snapshot`, authenticated WebSocket connect, replay after event id, and 401 on missing token.
89 -- [x] Implement `server.ts` upgrade handling and snapshot route.
90 -- [x] Add heartbeat ping/pong and disconnect cleanup.
91 -- [x] Run `npx vitest run extensions/ui/__tests__/server.test.ts`; expect PASS.
92 -- [x] Commit `Add ui browser event transport`.
94 -### Task 5: Browser shell and composer
96 -- [x] Add `web-smoke.test.ts` that fetches the shell and verifies it contains module script, stream root, composer, and status strip.
97 -- [x] Implement `web/app.html.ts`, `web/app.css.ts`, and `web/app.js.ts`.
98 -- [x] Browser JS must fetch snapshot first, then connect WebSocket, then render replayed stream items in id order.
99 -- [x] Composer submit sends `{ type: "prompt", text }` to server, disables during in-flight RPC, and appends visible pending state.
100 -- [x] Run `npx vitest run extensions/ui/__tests__/web-smoke.test.ts`; expect PASS.
101 -- [x] Commit `Add ui basic browser shell`.
103 -### Task 6: Runtime integration
105 -- [x] Extend runtime tests to start with fake seed and fake RPC bridge.
106 -- [x] Modify `runtime.ts` to create event store, seed session, start RPC, publish startup state, and expose snapshot/transport dependencies to server.
107 -- [x] Modify `index.ts` so `/ui` passes `ctx` into runtime start.
108 -- [x] Modify terminal widget to show web URL, RPC state, seeded session path basename, and last lifecycle error.
109 -- [x] Run all UI tests: `npx vitest run extensions/ui/__tests__/*.test.ts`; expect PASS.
110 -- [x] Commit `Wire ui rpc runtime`.
112 -### Task 7: Verification
114 -- [x] Run actual static check: `node --input-type=module -e "import {checkStatic, extDirs} from './scripts/extensions.mjs'; process.exit(checkStatic(extDirs(['ui'])));"`.
115 -- [x] Run `mise run install` and `mise run check -- ui`.
116 -- [x] On win32, run the manual smoke with zellij instead of tmux: create a zellij background session, launch `pi -e extensions/ui/index.ts`, send `/ui`, open the browser URL, send one browser prompt, then `/ui off`.
117 -- [x] On non-win32, tmux remains acceptable for manual smoke.
118 -- [x] Commit any verification fixes as `Verify ui phase 2 rpc stream`.
120 -## Done criteria
122 -- Browser page renders seeded session snapshot and live ordered RPC events.
123 -- Browser prompt submission reaches the RPC Pi session.
124 -- RPC slow startup/death are visible in browser and terminal widget.
125 -- Token auth protects snapshot and WebSocket.
126 -- UI tests, static check, `mise run install`, and `mise run check -- ui` pass.
127 -- Win32 manual terminal smoke uses zellij, not tmux.
1 +# UI Extension Phase 2 Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Make `/ui` a minimal browser Pi frontend backed by a seeded active-branch RPC subprocess.
7 +**Architecture:** Keep Phase 1 server/runtime as owner. Add active-branch session seeding, a Pi RPC child-process bridge, a small event protocol, WebSocket fanout, and a no-framework browser shell that renders snapshots plus ordered events.
9 +**Tech Stack:** Node `child_process`, `fs`, `readline`, `crypto`; Pi `SessionManager`; browser WebSocket, Web Components, CSS; Vitest harness tests.
11 +**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 +**Phase:** Phase 2: Active-Branch RPC Session and Basic Web Stream
15 +---
17 +## Scope
19 +Included:
21 +- Seed a persistent web session from `ctx.sessionManager.createBranchedSession(ctx.sessionManager.getLeafId())`.
22 +- Spawn `pi --mode rpc --session <seeded-session>` with normal extensions/skills/settings.
23 +- Parse LF-delimited JSONL from RPC stdout and keep stderr diagnostics separate.
24 +- Add RPC request queue with ids, timeout, startup, death, and slow-start states.
25 +- Add `/api/snapshot`, `/ws`, event replay buffer, monotonic event ids, and JSON protocol types.
26 +- Replace Phase 1 shell page with a basic stream-first browser app and composer.
27 +- Send browser prompts through RPC and render user/assistant/tool/error stream items.
29 +Excluded:
31 +- Full slash-command parity.
32 +- Rich syntax/autocomplete.
33 +- Visual widgets.
34 +- Telemetry.
35 +- Nugu polish beyond readable brutal defaults.
37 +## Files
39 +Create:
41 +- `extensions/ui/session-seed.ts` — active-branch seed path and warnings.
42 +- `extensions/ui/rpc.ts` — child process, JSONL parser, request queue, lifecycle.
43 +- `extensions/ui/protocol.ts` — event/snapshot/request types.
44 +- `extensions/ui/events.ts` — monotonic event store and replay.
45 +- `extensions/ui/web/app.html.ts` — HTML shell.
46 +- `extensions/ui/web/app.css.ts` — minimal stream-first CSS.
47 +- `extensions/ui/web/app.js.ts` — browser app source emitted by server.
48 +- `extensions/ui/__tests__/session-seed.test.ts`.
49 +- `extensions/ui/__tests__/rpc.test.ts`.
50 +- `extensions/ui/__tests__/events.test.ts`.
51 +- `extensions/ui/__tests__/web-smoke.test.ts`.
53 +Modify:
55 +- `extensions/ui/runtime.ts` — own seed, RPC, event store.
56 +- `extensions/ui/server.ts` — add snapshot, app assets, WebSocket upgrade.
57 +- `extensions/ui/index.ts` — pass command context into runtime start.
58 +- `extensions/ui/terminal-widget.ts` — show RPC startup/connected/dead states.
59 +- `extensions/ui/package.json` — add `ws` and `@types/ws` if native upgrade handling is not enough.
61 +## Tasks
63 +### Task 1: Event protocol and store
65 +- [x] Write `events.test.ts` for monotonic ids, bounded replay, and snapshot shape.
66 +- [x] Implement `protocol.ts` and `events.ts` with `UiEvent`, `UiSnapshot`, `EventStore.append`, `EventStore.snapshot`, and `EventStore.replayAfter`.
67 +- [x] Run `npx vitest run extensions/ui/__tests__/events.test.ts`; expect PASS.
68 +- [x] Commit `Add ui event protocol`.
70 +### Task 2: Active-branch session seed
72 +- [x] Write `session-seed.test.ts` using a fake session manager with `getLeafId()` and `createBranchedSession()`.
73 +- [x] Implement `session-seed.ts` so the default path calls `createBranchedSession(getLeafId())` and returns `{ path, warning: undefined }`.
74 +- [x] Add fallback warning only when whole-tree `forkFrom` is explicitly used by option.
75 +- [x] Run `npx vitest run extensions/ui/__tests__/session-seed.test.ts`; expect PASS.
76 +- [x] Commit `Add ui active branch session seed`.
78 +### Task 3: RPC bridge
80 +- [x] Write `rpc.test.ts` for JSONL parsing, request id matching, stderr capture, timeout, process exit event, and slow-start event.
81 +- [x] Implement `rpc.ts` with `startRpc`, `sendRpc`, `closeRpc`, `parseJsonLines`, and typed lifecycle callbacks.
82 +- [x] Make subprocess command resolve to `pi.cmd` on win32 and `pi` elsewhere unless `PI_UI_RPC_BIN` overrides it for tests.
83 +- [x] Run `npx vitest run extensions/ui/__tests__/rpc.test.ts`; expect PASS.
84 +- [x] Commit `Add ui rpc bridge`.
86 +### Task 4: Server snapshot and WebSocket stream
88 +- [x] Write server tests for authenticated `/api/snapshot`, authenticated WebSocket connect, replay after event id, and 401 on missing token.
89 +- [x] Implement `server.ts` upgrade handling and snapshot route.
90 +- [x] Add heartbeat ping/pong and disconnect cleanup.
91 +- [x] Run `npx vitest run extensions/ui/__tests__/server.test.ts`; expect PASS.
92 +- [x] Commit `Add ui browser event transport`.
94 +### Task 5: Browser shell and composer
96 +- [x] Add `web-smoke.test.ts` that fetches the shell and verifies it contains module script, stream root, composer, and status strip.
97 +- [x] Implement `web/app.html.ts`, `web/app.css.ts`, and `web/app.js.ts`.
98 +- [x] Browser JS must fetch snapshot first, then connect WebSocket, then render replayed stream items in id order.
99 +- [x] Composer submit sends `{ type: "prompt", text }` to server, disables during in-flight RPC, and appends visible pending state.
100 +- [x] Run `npx vitest run extensions/ui/__tests__/web-smoke.test.ts`; expect PASS.
101 +- [x] Commit `Add ui basic browser shell`.
103 +### Task 6: Runtime integration
105 +- [x] Extend runtime tests to start with fake seed and fake RPC bridge.
106 +- [x] Modify `runtime.ts` to create event store, seed session, start RPC, publish startup state, and expose snapshot/transport dependencies to server.
107 +- [x] Modify `index.ts` so `/ui` passes `ctx` into runtime start.
108 +- [x] Modify terminal widget to show web URL, RPC state, seeded session path basename, and last lifecycle error.
109 +- [x] Run all UI tests: `npx vitest run extensions/ui/__tests__/*.test.ts`; expect PASS.
110 +- [x] Commit `Wire ui rpc runtime`.
112 +### Task 7: Verification
114 +- [x] Run actual static check: `node --input-type=module -e "import {checkStatic, extDirs} from './scripts/extensions.mjs'; process.exit(checkStatic(extDirs(['ui'])));"`.
115 +- [x] Run `mise run install` and `mise run check -- ui`.
116 +- [x] On win32, run the manual smoke with zellij instead of tmux: create a zellij background session, launch `pi -e extensions/ui/index.ts`, send `/ui`, open the browser URL, send one browser prompt, then `/ui off`.
117 +- [x] On non-win32, tmux remains acceptable for manual smoke.
118 +- [x] Commit any verification fixes as `Verify ui phase 2 rpc stream`.
120 +## Done criteria
122 +- Browser page renders seeded session snapshot and live ordered RPC events.
123 +- Browser prompt submission reaches the RPC Pi session.
124 +- RPC slow startup/death are visible in browser and terminal widget.
125 +- Token auth protects snapshot and WebSocket.
126 +- UI tests, static check, `mise run install`, and `mise run check -- ui` pass.
127 +- Win32 manual terminal smoke uses zellij, not tmux.

docs/super/plans/2026-07-01-ui-extension-phase-3-pi-syntax-controls.md

Modified
1 -# UI Extension Phase 3 Implementation Plan
3 -> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 -**Goal:** Bring browser composer behavior close to normal Pi interaction: slash commands, references, keybindings, model/thinking controls, and extension UI requests.
7 -**Architecture:** Build on the Phase 2 RPC transport. Add browser-side parsing for Pi syntax, RPC command adapters, and a small UI-request protocol for select/confirm/input/editor/notify/status/title/widget/editor-text interactions.
9 -**Tech Stack:** Browser Web Components, WebSocket RPC events, Pi RPC commands, Vitest browser/parser tests.
11 -**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 -**Phase:** Phase 3: Pi Syntax, Commands, Keybindings, and Extension UI
15 ----
17 -## Scope
19 -Included:
21 -- Slash command autocomplete and execution.
22 -- `/skill:*` and prompt-template entries from RPC command state.
23 -- `@` reference parsing and visible unsupported attachment errors when Phase 3 cannot attach yet.
24 -- `!` and `!!` mapping to RPC `bash` with correct `excludeFromContext`.
25 -- Enter, Shift+Enter, Esc, Ctrl+O, Ctrl+P controls.
26 -- Model/thinking controls through RPC where available.
27 -- Extension UI request/response rendering for select, confirm, input, editor, notify, status, title, widget, editor text.
29 -Excluded:
31 -- Trusted full-JS visual widgets.
32 -- Telemetry digest.
33 -- Pierre/Shiki polish.
35 -## Files
37 -Create:
39 -- `extensions/ui/composer.ts` — shared parser for slash/ref/bash forms.
40 -- `extensions/ui/command-adapter.ts` — server-side RPC command helpers.
41 -- `extensions/ui/extension-ui.ts` — request/response event model.
42 -- `extensions/ui/web/components/composer.js.ts`.
43 -- `extensions/ui/web/components/dialogs.js.ts`.
44 -- `extensions/ui/__tests__/composer.test.ts`.
45 -- `extensions/ui/__tests__/command-adapter.test.ts`.
46 -- `extensions/ui/__tests__/extension-ui.test.ts`.
48 -Modify:
50 -- `extensions/ui/protocol.ts`.
51 -- `extensions/ui/rpc.ts`.
52 -- `extensions/ui/server.ts`.
53 -- `extensions/ui/web/app.js.ts`.
54 -- `extensions/ui/web/app.css.ts`.
56 -## Tasks
58 -### Task 1: Composer parser
60 -- [x] Write parser tests for plain prompts, `/command args`, `/skill:name`, `@path`, `!cmd`, and `!!cmd`.
61 -- [x] Implement `composer.ts` with `parseComposerInput(text)` returning `{ kind, command, args, refs, excludeFromContext }`.
62 -- [x] Run `npx vitest run extensions/ui/__tests__/composer.test.ts`; expect PASS.
63 -- [x] Commit `Add ui composer parser`.
65 -### Task 2: RPC command adapters
67 -- [x] Write adapter tests using fake RPC send calls for slash commands, model cycle, thinking cycle, compact, and bash.
68 -- [x] Implement `command-adapter.ts` with explicit functions: `sendPrompt`, `runSlashCommand`, `runBash`, `cycleModel`, `cycleThinking`, `abortCurrent`.
69 -- [x] Ensure `!!` calls RPC `bash` with `excludeFromContext: true`.
70 -- [x] Run adapter tests; expect PASS.
71 -- [x] Commit `Add ui rpc command adapters`.
73 -### Task 3: Browser autocomplete
75 -- [x] Add web tests for slash menu filtering and keyboard selection.
76 -- [x] Implement composer component with slash menu from snapshot commands and skills.
77 -- [x] Keep desktop minimal; show mobile tap targets only under phone-width CSS.
78 -- [x] Run web smoke tests; expect PASS.
79 -- [x] Commit `Add ui slash autocomplete`.
81 -### Task 4: Keybindings
83 -- [x] Add tests for Enter submit, Shift+Enter newline, Esc abort, Ctrl+O expand toggle, Ctrl+P model cycle.
84 -- [x] Implement keybinding dispatch in `composer.js.ts` and server RPC routes.
85 -- [x] Render immediate local state for abort/model/thinking actions before RPC response when safe.
86 -- [x] Run UI tests; expect PASS.
87 -- [x] Commit `Add ui browser keybindings`.
89 -### Task 5: Extension UI protocol
91 -- [x] Write tests for select/confirm/input/editor requests and responses.
92 -- [x] Implement `extension-ui.ts` and protocol events `ui_request`, `ui_response`, `ui_notify`, `ui_status`, `ui_title`, `ui_widget`, `ui_editor_text`.
93 -- [x] Wire RPC stderr/stdout UI request messages into event store.
94 -- [x] Render dialogs in browser and send response ids back through RPC.
95 -- [x] Run extension UI tests; expect PASS.
96 -- [x] Commit `Add ui extension request protocol`.
98 -### Task 6: Integration verification
100 -- [x] Run `npx vitest run extensions/ui/__tests__/*.test.ts`.
101 -- [x] Run actual static check for `ui`.
102 -- [x] Run `mise run install` and `mise run check -- ui`.
103 -- [x] On win32, run zellij manual smoke for `/`, `/skill:`, `!`, `!!`, Esc, Ctrl+O, Ctrl+P.
104 -- [x] Commit fixes as `Verify ui phase 3 syntax controls`.
106 -## Done criteria
108 -- Browser composer supports core Pi text syntax and keybindings.
109 -- Extension UI requests render and respond through the browser.
110 -- Unsupported terminal-only semantics show explicit stream errors, not silent failure.
111 -- Tests and mise checks pass.
1 +# UI Extension Phase 3 Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Bring browser composer behavior close to normal Pi interaction: slash commands, references, keybindings, model/thinking controls, and extension UI requests.
7 +**Architecture:** Build on the Phase 2 RPC transport. Add browser-side parsing for Pi syntax, RPC command adapters, and a small UI-request protocol for select/confirm/input/editor/notify/status/title/widget/editor-text interactions.
9 +**Tech Stack:** Browser Web Components, WebSocket RPC events, Pi RPC commands, Vitest browser/parser tests.
11 +**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 +**Phase:** Phase 3: Pi Syntax, Commands, Keybindings, and Extension UI
15 +---
17 +## Scope
19 +Included:
21 +- Slash command autocomplete and execution.
22 +- `/skill:*` and prompt-template entries from RPC command state.
23 +- `@` reference parsing and visible unsupported attachment errors when Phase 3 cannot attach yet.
24 +- `!` and `!!` mapping to RPC `bash` with correct `excludeFromContext`.
25 +- Enter, Shift+Enter, Esc, Ctrl+O, Ctrl+P controls.
26 +- Model/thinking controls through RPC where available.
27 +- Extension UI request/response rendering for select, confirm, input, editor, notify, status, title, widget, editor text.
29 +Excluded:
31 +- Trusted full-JS visual widgets.
32 +- Telemetry digest.
33 +- Pierre/Shiki polish.
35 +## Files
37 +Create:
39 +- `extensions/ui/composer.ts` — shared parser for slash/ref/bash forms.
40 +- `extensions/ui/command-adapter.ts` — server-side RPC command helpers.
41 +- `extensions/ui/extension-ui.ts` — request/response event model.
42 +- `extensions/ui/web/components/composer.js.ts`.
43 +- `extensions/ui/web/components/dialogs.js.ts`.
44 +- `extensions/ui/__tests__/composer.test.ts`.
45 +- `extensions/ui/__tests__/command-adapter.test.ts`.
46 +- `extensions/ui/__tests__/extension-ui.test.ts`.
48 +Modify:
50 +- `extensions/ui/protocol.ts`.
51 +- `extensions/ui/rpc.ts`.
52 +- `extensions/ui/server.ts`.
53 +- `extensions/ui/web/app.js.ts`.
54 +- `extensions/ui/web/app.css.ts`.
56 +## Tasks
58 +### Task 1: Composer parser
60 +- [x] Write parser tests for plain prompts, `/command args`, `/skill:name`, `@path`, `!cmd`, and `!!cmd`.
61 +- [x] Implement `composer.ts` with `parseComposerInput(text)` returning `{ kind, command, args, refs, excludeFromContext }`.
62 +- [x] Run `npx vitest run extensions/ui/__tests__/composer.test.ts`; expect PASS.
63 +- [x] Commit `Add ui composer parser`.
65 +### Task 2: RPC command adapters
67 +- [x] Write adapter tests using fake RPC send calls for slash commands, model cycle, thinking cycle, compact, and bash.
68 +- [x] Implement `command-adapter.ts` with explicit functions: `sendPrompt`, `runSlashCommand`, `runBash`, `cycleModel`, `cycleThinking`, `abortCurrent`.
69 +- [x] Ensure `!!` calls RPC `bash` with `excludeFromContext: true`.
70 +- [x] Run adapter tests; expect PASS.
71 +- [x] Commit `Add ui rpc command adapters`.
73 +### Task 3: Browser autocomplete
75 +- [x] Add web tests for slash menu filtering and keyboard selection.
76 +- [x] Implement composer component with slash menu from snapshot commands and skills.
77 +- [x] Keep desktop minimal; show mobile tap targets only under phone-width CSS.
78 +- [x] Run web smoke tests; expect PASS.
79 +- [x] Commit `Add ui slash autocomplete`.
81 +### Task 4: Keybindings
83 +- [x] Add tests for Enter submit, Shift+Enter newline, Esc abort, Ctrl+O expand toggle, Ctrl+P model cycle.
84 +- [x] Implement keybinding dispatch in `composer.js.ts` and server RPC routes.
85 +- [x] Render immediate local state for abort/model/thinking actions before RPC response when safe.
86 +- [x] Run UI tests; expect PASS.
87 +- [x] Commit `Add ui browser keybindings`.
89 +### Task 5: Extension UI protocol
91 +- [x] Write tests for select/confirm/input/editor requests and responses.
92 +- [x] Implement `extension-ui.ts` and protocol events `ui_request`, `ui_response`, `ui_notify`, `ui_status`, `ui_title`, `ui_widget`, `ui_editor_text`.
93 +- [x] Wire RPC stderr/stdout UI request messages into event store.
94 +- [x] Render dialogs in browser and send response ids back through RPC.
95 +- [x] Run extension UI tests; expect PASS.
96 +- [x] Commit `Add ui extension request protocol`.
98 +### Task 6: Integration verification
100 +- [x] Run `npx vitest run extensions/ui/__tests__/*.test.ts`.
101 +- [x] Run actual static check for `ui`.
102 +- [x] Run `mise run install` and `mise run check -- ui`.
103 +- [x] On win32, run zellij manual smoke for `/`, `/skill:`, `!`, `!!`, Esc, Ctrl+O, Ctrl+P.
104 +- [x] Commit fixes as `Verify ui phase 3 syntax controls`.
106 +## Done criteria
108 +- Browser composer supports core Pi text syntax and keybindings.
109 +- Extension UI requests render and respond through the browser.
110 +- Unsupported terminal-only semantics show explicit stream errors, not silent failure.
111 +- Tests and mise checks pass.

docs/super/plans/2026-07-01-ui-extension-phase-4-trusted-visual-widgets.md

Modified
1 -# UI Extension Phase 4 Implementation Plan
3 -> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 -**Goal:** Let agents render trusted full-JS visual widgets in the browser stream with `window.pi` action bridges and visible attribution.
7 -**Architecture:** Register UI visual tools in the web RPC session. Store widget lifecycle events in the existing event stream. Mount widget documents in bounded `iframe srcdoc` containers, expose `window.pi` in the parent bridge, and audit every widget-originated action.
9 -**Tech Stack:** Pi extension tools, browser iframe `srcdoc`, postMessage, Web Components, Vitest, Playwright Chrome/Firefox probes.
11 -**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 -**Phase:** Phase 4: Trusted Visual Widgets and `window.pi`
15 ----
17 -## Scope
19 -Included:
21 -- Visual tools: card, table, diagram, form, mockup/prototype, raw HTML/CSS/JS, update/patch, wait-for-action.
22 -- Stable widget ids and lifecycle events.
23 -- Bounded iframe layout with height negotiation and overflow containment.
24 -- Parent-provided `window.pi` methods for action/result, prompt/steer/follow-up, state, events, update, local notify, and attachment request.
25 -- Visible attribution before widget-originated prompts/actions reach the agent/session.
26 -- Audit details in expanded stream metadata.
28 -Excluded:
30 -- Telemetry digest beyond widget action events.
31 -- Rendering polish and virtualization.
32 -- Any sandbox or permission wall.
34 -## Files
36 -Create:
38 -- `extensions/ui/visual-tools.ts`.
39 -- `extensions/ui/widget-state.ts`.
40 -- `extensions/ui/web/components/visual-block.js.ts`.
41 -- `extensions/ui/web/components/widget-bridge.js.ts`.
42 -- `extensions/ui/__tests__/visual-tools.test.ts`.
43 -- `extensions/ui/__tests__/widget-state.test.ts`.
44 -- `extensions/ui/__tests__/widget-layout.test.ts`.
45 -- `extensions/ui/__tests__/widget-bridge.test.ts`.
47 -Modify:
49 -- `extensions/ui/index.ts`.
50 -- `extensions/ui/protocol.ts`.
51 -- `extensions/ui/server.ts`.
52 -- `extensions/ui/web/app.js.ts`.
53 -- `extensions/ui/web/app.css.ts`.
54 -- `extensions/ui/errors.ts`.
56 -## Tasks
58 -### Task 1: Widget protocol and state
60 -- [x] Write tests for stable ids, mount/update/action/error lifecycle, and audit records.
61 -- [x] Implement `widget-state.ts` and protocol event types.
62 -- [x] Ensure every widget action has `widgetId`, `toolCallId`, `actionId`, visible label, and timestamp.
63 -- [x] Run widget state tests; expect PASS.
64 -- [x] Commit `Add ui widget lifecycle state`.
66 -### Task 2: Visual tools
68 -- [x] Write tests for each visual tool returning fallback text and appending widget events.
69 -- [x] Implement `visual-tools.ts` with no sibling extension imports.
70 -- [x] Register tools from `index.ts` only for the UI RPC session where tool registration is safe.
71 -- [x] Run visual tool tests; expect PASS.
72 -- [x] Commit `Add ui visual tools`.
74 -### Task 3: Iframe bridge
76 -- [x] Write bridge tests for `window.pi.action`, `window.pi.prompt`, `window.pi.notify`, and error reporting.
77 -- [x] Implement bounded `iframe srcdoc` bridge with parent postMessage routing.
78 -- [x] Reject silent prompts: widget-originated prompt must first append attribution event.
79 -- [x] Run bridge tests; expect PASS.
80 -- [x] Commit `Add ui widget bridge`.
82 -### Task 4: Layout probes
84 -- [x] Add Playwright tests for Chrome and Firefox iframe bridge access.
85 -- [x] Add mobile-width bounded-layout test with intentionally over-wide/tall content.
86 -- [x] Use installed Playwright Firefox; do not skip Firefox silently.
87 -- [x] Run layout tests; expect PASS.
88 -- [x] Commit `Add ui widget browser layout tests`.
90 -### Task 5: Stream rendering
92 -- [x] Render visual blocks in main stream with title, fallback, lifecycle state, expand/collapse, ids, and audit details.
93 -- [x] Show widget JS errors as stream errors with human action and agent fix hint.
94 -- [x] Add tests for fallback and error rendering.
95 -- [x] Run UI tests; expect PASS.
96 -- [x] Commit `Render ui visual widgets`.
98 -### Task 6: Verification
100 -- [x] Run all UI tests plus Chrome/Firefox widget probes.
101 -- [x] Run static check and `mise run check -- ui`.
102 -- [x] On win32, run zellij smoke asking the agent for card/form/raw widget and click a widget action.
103 -- [x] Commit fixes as `Verify ui phase 4 widgets`.
105 -## Done criteria
107 -- Agents can create trusted full-JS widgets in stream.
108 -- `window.pi` actions work and are visibly attributed.
109 -- Layout is bounded in Chrome and Firefox on desktop and phone widths.
110 -- Tests and mise checks pass.
1 +# UI Extension Phase 4 Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Let agents render trusted full-JS visual widgets in the browser stream with `window.pi` action bridges and visible attribution.
7 +**Architecture:** Register UI visual tools in the web RPC session. Store widget lifecycle events in the existing event stream. Mount widget documents in bounded `iframe srcdoc` containers, expose `window.pi` in the parent bridge, and audit every widget-originated action.
9 +**Tech Stack:** Pi extension tools, browser iframe `srcdoc`, postMessage, Web Components, Vitest, Playwright Chrome/Firefox probes.
11 +**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 +**Phase:** Phase 4: Trusted Visual Widgets and `window.pi`
15 +---
17 +## Scope
19 +Included:
21 +- Visual tools: card, table, diagram, form, mockup/prototype, raw HTML/CSS/JS, update/patch, wait-for-action.
22 +- Stable widget ids and lifecycle events.
23 +- Bounded iframe layout with height negotiation and overflow containment.
24 +- Parent-provided `window.pi` methods for action/result, prompt/steer/follow-up, state, events, update, local notify, and attachment request.
25 +- Visible attribution before widget-originated prompts/actions reach the agent/session.
26 +- Audit details in expanded stream metadata.
28 +Excluded:
30 +- Telemetry digest beyond widget action events.
31 +- Rendering polish and virtualization.
32 +- Any sandbox or permission wall.
34 +## Files
36 +Create:
38 +- `extensions/ui/visual-tools.ts`.
39 +- `extensions/ui/widget-state.ts`.
40 +- `extensions/ui/web/components/visual-block.js.ts`.
41 +- `extensions/ui/web/components/widget-bridge.js.ts`.
42 +- `extensions/ui/__tests__/visual-tools.test.ts`.
43 +- `extensions/ui/__tests__/widget-state.test.ts`.
44 +- `extensions/ui/__tests__/widget-layout.test.ts`.
45 +- `extensions/ui/__tests__/widget-bridge.test.ts`.
47 +Modify:
49 +- `extensions/ui/index.ts`.
50 +- `extensions/ui/protocol.ts`.
51 +- `extensions/ui/server.ts`.
52 +- `extensions/ui/web/app.js.ts`.
53 +- `extensions/ui/web/app.css.ts`.
54 +- `extensions/ui/errors.ts`.
56 +## Tasks
58 +### Task 1: Widget protocol and state
60 +- [x] Write tests for stable ids, mount/update/action/error lifecycle, and audit records.
61 +- [x] Implement `widget-state.ts` and protocol event types.
62 +- [x] Ensure every widget action has `widgetId`, `toolCallId`, `actionId`, visible label, and timestamp.
63 +- [x] Run widget state tests; expect PASS.
64 +- [x] Commit `Add ui widget lifecycle state`.
66 +### Task 2: Visual tools
68 +- [x] Write tests for each visual tool returning fallback text and appending widget events.
69 +- [x] Implement `visual-tools.ts` with no sibling extension imports.
70 +- [x] Register tools from `index.ts` only for the UI RPC session where tool registration is safe.
71 +- [x] Run visual tool tests; expect PASS.
72 +- [x] Commit `Add ui visual tools`.
74 +### Task 3: Iframe bridge
76 +- [x] Write bridge tests for `window.pi.action`, `window.pi.prompt`, `window.pi.notify`, and error reporting.
77 +- [x] Implement bounded `iframe srcdoc` bridge with parent postMessage routing.
78 +- [x] Reject silent prompts: widget-originated prompt must first append attribution event.
79 +- [x] Run bridge tests; expect PASS.
80 +- [x] Commit `Add ui widget bridge`.
82 +### Task 4: Layout probes
84 +- [x] Add Playwright tests for Chrome and Firefox iframe bridge access.
85 +- [x] Add mobile-width bounded-layout test with intentionally over-wide/tall content.
86 +- [x] Use installed Playwright Firefox; do not skip Firefox silently.
87 +- [x] Run layout tests; expect PASS.
88 +- [x] Commit `Add ui widget browser layout tests`.
90 +### Task 5: Stream rendering
92 +- [x] Render visual blocks in main stream with title, fallback, lifecycle state, expand/collapse, ids, and audit details.
93 +- [x] Show widget JS errors as stream errors with human action and agent fix hint.
94 +- [x] Add tests for fallback and error rendering.
95 +- [x] Run UI tests; expect PASS.
96 +- [x] Commit `Render ui visual widgets`.
98 +### Task 6: Verification
100 +- [x] Run all UI tests plus Chrome/Firefox widget probes.
101 +- [x] Run static check and `mise run check -- ui`.
102 +- [x] On win32, run zellij smoke asking the agent for card/form/raw widget and click a widget action.
103 +- [x] Commit fixes as `Verify ui phase 4 widgets`.
105 +## Done criteria
107 +- Agents can create trusted full-JS widgets in stream.
108 +- `window.pi` actions work and are visibly attributed.
109 +- Layout is bounded in Chrome and Firefox on desktop and phone widths.
110 +- Tests and mise checks pass.

docs/super/plans/2026-07-01-ui-extension-phase-5-telemetry-lifecycle.md

Modified
1 -# UI Extension Phase 5 Implementation Plan
3 -> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 -**Goal:** Summarize browser behavior for the next prompt and show actionable browser lifecycle errors.
7 -**Architecture:** Track raw browser interactions locally, aggregate them in a worker into a capped digest, and attach the digest exactly once to the next user prompt. Treat lifecycle changes as stream events so both human and agent can see disconnects, stale clients, and telemetry failures.
9 -**Tech Stack:** Browser Worker, WebSocket heartbeat, Page Visibility API, `pagehide`, local redaction helpers, Vitest browser tests.
11 -**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 -**Phase:** Phase 5: Telemetry Digest and Browser Lifecycle Errors
15 ----
17 -## Scope
19 -Included:
21 -- Track scroll dwell, clicks/taps, focus/blur, inactive time, viewport/device class, selected text, widget actions, form abandon/submit, and visible errors.
22 -- Redact selected/input text before digest generation.
23 -- Show inspectable “digest will be sent” indicator when non-empty.
24 -- Attach digest once to the next accepted prompt, then clear.
25 -- Detect visibility changes, pagehide, heartbeat loss, WebSocket close, stale clients, and likely browser crash/disconnect.
26 -- Render lifecycle errors with human action, agent hint, retryability, and related ids.
28 -Excluded:
30 -- Raw analytics persistence.
31 -- Multi-tab SharedWorker optimization.
32 -- Rendering polish.
34 -## Files
36 -Create:
38 -- `extensions/ui/telemetry.ts`.
39 -- `extensions/ui/lifecycle.ts`.
40 -- `extensions/ui/web/worker.js.ts`.
41 -- `extensions/ui/web/components/digest-indicator.js.ts`.
42 -- `extensions/ui/__tests__/telemetry.test.ts`.
43 -- `extensions/ui/__tests__/lifecycle.test.ts`.
45 -Modify:
47 -- `extensions/ui/protocol.ts`.
48 -- `extensions/ui/server.ts`.
49 -- `extensions/ui/command-adapter.ts`.
50 -- `extensions/ui/web/app.js.ts`.
51 -- `extensions/ui/web/app.css.ts`.
53 -## Tasks
55 -### Task 1: Telemetry aggregation
57 -- [x] Write tests for scroll/click/focus/pagehide/widget/form events, caps, and digest text.
58 -- [x] Implement `telemetry.ts` with `TelemetryAggregator.add`, `digest`, `clear`, and redaction helpers.
59 -- [x] Ensure raw values never cross into prompt context.
60 -- [x] Run telemetry tests; expect PASS.
61 -- [x] Commit `Add ui telemetry aggregator`.
63 -### Task 2: Browser worker tracking
65 -- [x] Write worker tests for batching and redaction messages.
66 -- [x] Implement `web/worker.js.ts` to batch raw events off the hot path.
67 -- [x] Wire `app.js.ts` event listeners for scroll, click, selection, focus, blur, pagehide, and widget actions.
68 -- [x] Run worker/web tests; expect PASS.
69 -- [x] Commit `Add ui browser telemetry worker`.
71 -### Task 3: Digest prompt attachment
73 -- [x] Write adapter tests proving digest attaches once to next prompt and then clears.
74 -- [x] Modify prompt send path to prepend or attach the digest in a deterministic bounded block.
75 -- [x] Render digest indicator near composer with inspectable details.
76 -- [x] Run prompt/digest tests; expect PASS.
77 -- [x] Commit `Attach ui telemetry digest once`.
79 -### Task 4: Lifecycle detection
81 -- [x] Write lifecycle tests for heartbeat timeout, WebSocket close, pagehide, stale client, and browser reconnect.
82 -- [x] Implement `lifecycle.ts` and server heartbeat state.
83 -- [x] Emit lifecycle stream events with action, agent hint, retryability, client id, and timestamps.
84 -- [x] Run lifecycle tests; expect PASS.
85 -- [x] Commit `Add ui browser lifecycle events`.
87 -### Task 5: Verification
89 -- [x] Run all UI tests.
90 -- [x] Run static check and `mise run check -- ui`.
91 -- [x] On win32, use zellij smoke to scroll/click/select/background/return/send next prompt and verify digest appears once.
92 -- [x] Commit fixes as `Verify ui phase 5 telemetry lifecycle`.
94 -## Done criteria
96 -- Digest is capped, inspectable, redacted, prompt-gated, and sent once.
97 -- Browser lifecycle errors are visible and actionable.
98 -- Telemetry failure does not break prompt submission.
99 -- Tests and mise checks pass.
1 +# UI Extension Phase 5 Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Summarize browser behavior for the next prompt and show actionable browser lifecycle errors.
7 +**Architecture:** Track raw browser interactions locally, aggregate them in a worker into a capped digest, and attach the digest exactly once to the next user prompt. Treat lifecycle changes as stream events so both human and agent can see disconnects, stale clients, and telemetry failures.
9 +**Tech Stack:** Browser Worker, WebSocket heartbeat, Page Visibility API, `pagehide`, local redaction helpers, Vitest browser tests.
11 +**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 +**Phase:** Phase 5: Telemetry Digest and Browser Lifecycle Errors
15 +---
17 +## Scope
19 +Included:
21 +- Track scroll dwell, clicks/taps, focus/blur, inactive time, viewport/device class, selected text, widget actions, form abandon/submit, and visible errors.
22 +- Redact selected/input text before digest generation.
23 +- Show inspectable “digest will be sent” indicator when non-empty.
24 +- Attach digest once to the next accepted prompt, then clear.
25 +- Detect visibility changes, pagehide, heartbeat loss, WebSocket close, stale clients, and likely browser crash/disconnect.
26 +- Render lifecycle errors with human action, agent hint, retryability, and related ids.
28 +Excluded:
30 +- Raw analytics persistence.
31 +- Multi-tab SharedWorker optimization.
32 +- Rendering polish.
34 +## Files
36 +Create:
38 +- `extensions/ui/telemetry.ts`.
39 +- `extensions/ui/lifecycle.ts`.
40 +- `extensions/ui/web/worker.js.ts`.
41 +- `extensions/ui/web/components/digest-indicator.js.ts`.
42 +- `extensions/ui/__tests__/telemetry.test.ts`.
43 +- `extensions/ui/__tests__/lifecycle.test.ts`.
45 +Modify:
47 +- `extensions/ui/protocol.ts`.
48 +- `extensions/ui/server.ts`.
49 +- `extensions/ui/command-adapter.ts`.
50 +- `extensions/ui/web/app.js.ts`.
51 +- `extensions/ui/web/app.css.ts`.
53 +## Tasks
55 +### Task 1: Telemetry aggregation
57 +- [x] Write tests for scroll/click/focus/pagehide/widget/form events, caps, and digest text.
58 +- [x] Implement `telemetry.ts` with `TelemetryAggregator.add`, `digest`, `clear`, and redaction helpers.
59 +- [x] Ensure raw values never cross into prompt context.
60 +- [x] Run telemetry tests; expect PASS.
61 +- [x] Commit `Add ui telemetry aggregator`.
63 +### Task 2: Browser worker tracking
65 +- [x] Write worker tests for batching and redaction messages.
66 +- [x] Implement `web/worker.js.ts` to batch raw events off the hot path.
67 +- [x] Wire `app.js.ts` event listeners for scroll, click, selection, focus, blur, pagehide, and widget actions.
68 +- [x] Run worker/web tests; expect PASS.
69 +- [x] Commit `Add ui browser telemetry worker`.
71 +### Task 3: Digest prompt attachment
73 +- [x] Write adapter tests proving digest attaches once to next prompt and then clears.
74 +- [x] Modify prompt send path to prepend or attach the digest in a deterministic bounded block.
75 +- [x] Render digest indicator near composer with inspectable details.
76 +- [x] Run prompt/digest tests; expect PASS.
77 +- [x] Commit `Attach ui telemetry digest once`.
79 +### Task 4: Lifecycle detection
81 +- [x] Write lifecycle tests for heartbeat timeout, WebSocket close, pagehide, stale client, and browser reconnect.
82 +- [x] Implement `lifecycle.ts` and server heartbeat state.
83 +- [x] Emit lifecycle stream events with action, agent hint, retryability, client id, and timestamps.
84 +- [x] Run lifecycle tests; expect PASS.
85 +- [x] Commit `Add ui browser lifecycle events`.
87 +### Task 5: Verification
89 +- [x] Run all UI tests.
90 +- [x] Run static check and `mise run check -- ui`.
91 +- [x] On win32, use zellij smoke to scroll/click/select/background/return/send next prompt and verify digest appears once.
92 +- [x] Commit fixes as `Verify ui phase 5 telemetry lifecycle`.
94 +## Done criteria
96 +- Digest is capped, inspectable, redacted, prompt-gated, and sent once.
97 +- Browser lifecycle errors are visible and actionable.
98 +- Telemetry failure does not break prompt submission.
99 +- Tests and mise checks pass.

docs/super/plans/2026-07-01-ui-extension-phase-6-nugu-polish-performance.md

Modified
1 -# UI Extension Phase 6 Implementation Plan
3 -> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 -**Goal:** Apply the accepted Nugu brutal/minimal visual direction and make long streams, diffs, code, and widgets stay fast.
7 -**Architecture:** Keep behavior unchanged. Add semantic CSS variables, lazy rendering upgrades, diff/highlight modules loaded on demand, stream batching, and virtualization thresholds behind the existing event protocol.
9 -**Tech Stack:** Nugu CSS variables, `prefers-color-scheme`, Pierre diffs, Shiki lazy import, Web Components, `content-visibility`, `requestAnimationFrame`, `MessageChannel`.
11 -**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 -**Phase:** Phase 6: Nugu Polish, Diffs, Highlighting, and Performance
15 ----
17 -## Scope
19 -Included:
21 -- Nugu semantic dark/light variables.
22 -- Stream-first layout: no sidebar by default, dominant `YOU` anchors, tiny top/status strips, brutal styling.
23 -- Pierre diff rendering with summary, expanded file view, anchors, copied hunks, and annotations.
24 -- Shiki lazy/cached highlighting with immediate plaintext fallback.
25 -- Long output truncation/expansion.
26 -- Virtualization threshold, content visibility, rAF batching, and worker parsing.
27 -- Responsive stream/widget containment on desktop and phone.
29 -Excluded:
31 -- New semantics or transport features.
32 -- SharedWorker multi-tab optimization unless measured pain proves it necessary.
34 -## Files
36 -Create:
38 -- `extensions/ui/web/theme.css.ts`.
39 -- `extensions/ui/web/components/code-block.js.ts`.
40 -- `extensions/ui/web/components/diff-view.js.ts`.
41 -- `extensions/ui/web/components/long-output.js.ts`.
42 -- `extensions/ui/web/components/virtual-stream.js.ts`.
43 -- `extensions/ui/__tests__/theme.test.ts`.
44 -- `extensions/ui/__tests__/rendering.test.ts`.
45 -- `extensions/ui/__tests__/performance.test.ts`.
47 -Modify:
49 -- `extensions/ui/package.json` and `package-lock.json` — add Pierre/Shiki deps.
50 -- `extensions/ui/web/app.css.ts`.
51 -- `extensions/ui/web/app.js.ts`.
52 -- `extensions/ui/web/worker.js.ts`.
53 -- `extensions/ui/README.md`.
55 -## Tasks
57 -### Task 1: Dependencies through mise/npm workspace
59 -- [x] Add Pierre and Shiki dependencies to `extensions/ui/package.json`.
60 -- [x] Run `npm install` to update `package-lock.json`.
61 -- [x] Run `mise run install` to verify `npm ci` installs them.
62 -- [x] Commit `Add ui rendering dependencies`.
64 -### Task 2: Nugu theme and layout
66 -- [x] Write theme tests for emitted semantic variables and dark/light media query.
67 -- [x] Implement `theme.css.ts` and update `app.css.ts`.
68 -- [x] Verify stream layout has no default sidebar and keeps top/status strips tiny.
69 -- [x] Run theme tests; expect PASS.
70 -- [x] Commit `Apply ui Nugu theme`.
72 -### Task 3: Code and diff rendering
74 -- [x] Write rendering tests for plaintext-first code, lazy Shiki upgrade, and Pierre diff summary/expanded view.
75 -- [x] Implement `code-block.js.ts` and `diff-view.js.ts`.
76 -- [x] Lazy-load Shiki only after initial plaintext is visible.
77 -- [x] Run rendering tests; expect PASS.
78 -- [x] Commit `Add ui code and diff rendering`.
80 -### Task 4: Long output and virtualization
82 -- [x] Write tests for truncation, expansion persistence, selected item preservation, and virtualized stream order.
83 -- [x] Implement `long-output.js.ts` and `virtual-stream.js.ts`.
84 -- [x] Use `content-visibility` and rAF/MessageChannel batching.
85 -- [x] Run performance tests; expect PASS.
86 -- [x] Commit `Add ui stream performance guards`.
88 -### Task 5: Visual verification
90 -- [x] Run all UI tests.
91 -- [x] Run static check and `mise run check -- ui`.
92 -- [x] On win32, run zellij smoke for dark/light desktop, phone width, long output, code, diff, and widgets.
93 -- [x] Commit fixes as `Verify ui phase 6 polish performance`.
95 -## Done criteria
97 -- Accepted Nugu direction is visible in dark and light mode.
98 -- Long streams remain responsive.
99 -- Code and diffs show plaintext immediately and upgrade lazily.
100 -- Tests and mise checks pass.
1 +# UI Extension Phase 6 Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Apply the accepted Nugu brutal/minimal visual direction and make long streams, diffs, code, and widgets stay fast.
7 +**Architecture:** Keep behavior unchanged. Add semantic CSS variables, lazy rendering upgrades, diff/highlight modules loaded on demand, stream batching, and virtualization thresholds behind the existing event protocol.
9 +**Tech Stack:** Nugu CSS variables, `prefers-color-scheme`, Pierre diffs, Shiki lazy import, Web Components, `content-visibility`, `requestAnimationFrame`, `MessageChannel`.
11 +**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 +**Phase:** Phase 6: Nugu Polish, Diffs, Highlighting, and Performance
15 +---
17 +## Scope
19 +Included:
21 +- Nugu semantic dark/light variables.
22 +- Stream-first layout: no sidebar by default, dominant `YOU` anchors, tiny top/status strips, brutal styling.
23 +- Pierre diff rendering with summary, expanded file view, anchors, copied hunks, and annotations.
24 +- Shiki lazy/cached highlighting with immediate plaintext fallback.
25 +- Long output truncation/expansion.
26 +- Virtualization threshold, content visibility, rAF batching, and worker parsing.
27 +- Responsive stream/widget containment on desktop and phone.
29 +Excluded:
31 +- New semantics or transport features.
32 +- SharedWorker multi-tab optimization unless measured pain proves it necessary.
34 +## Files
36 +Create:
38 +- `extensions/ui/web/theme.css.ts`.
39 +- `extensions/ui/web/components/code-block.js.ts`.
40 +- `extensions/ui/web/components/diff-view.js.ts`.
41 +- `extensions/ui/web/components/long-output.js.ts`.
42 +- `extensions/ui/web/components/virtual-stream.js.ts`.
43 +- `extensions/ui/__tests__/theme.test.ts`.
44 +- `extensions/ui/__tests__/rendering.test.ts`.
45 +- `extensions/ui/__tests__/performance.test.ts`.
47 +Modify:
49 +- `extensions/ui/package.json` and `package-lock.json` — add Pierre/Shiki deps.
50 +- `extensions/ui/web/app.css.ts`.
51 +- `extensions/ui/web/app.js.ts`.
52 +- `extensions/ui/web/worker.js.ts`.
53 +- `extensions/ui/README.md`.
55 +## Tasks
57 +### Task 1: Dependencies through mise/npm workspace
59 +- [x] Add Pierre and Shiki dependencies to `extensions/ui/package.json`.
60 +- [x] Run `npm install` to update `package-lock.json`.
61 +- [x] Run `mise run install` to verify `npm ci` installs them.
62 +- [x] Commit `Add ui rendering dependencies`.
64 +### Task 2: Nugu theme and layout
66 +- [x] Write theme tests for emitted semantic variables and dark/light media query.
67 +- [x] Implement `theme.css.ts` and update `app.css.ts`.
68 +- [x] Verify stream layout has no default sidebar and keeps top/status strips tiny.
69 +- [x] Run theme tests; expect PASS.
70 +- [x] Commit `Apply ui Nugu theme`.
72 +### Task 3: Code and diff rendering
74 +- [x] Write rendering tests for plaintext-first code, lazy Shiki upgrade, and Pierre diff summary/expanded view.
75 +- [x] Implement `code-block.js.ts` and `diff-view.js.ts`.
76 +- [x] Lazy-load Shiki only after initial plaintext is visible.
77 +- [x] Run rendering tests; expect PASS.
78 +- [x] Commit `Add ui code and diff rendering`.
80 +### Task 4: Long output and virtualization
82 +- [x] Write tests for truncation, expansion persistence, selected item preservation, and virtualized stream order.
83 +- [x] Implement `long-output.js.ts` and `virtual-stream.js.ts`.
84 +- [x] Use `content-visibility` and rAF/MessageChannel batching.
85 +- [x] Run performance tests; expect PASS.
86 +- [x] Commit `Add ui stream performance guards`.
88 +### Task 5: Visual verification
90 +- [x] Run all UI tests.
91 +- [x] Run static check and `mise run check -- ui`.
92 +- [x] On win32, run zellij smoke for dark/light desktop, phone width, long output, code, diff, and widgets.
93 +- [x] Commit fixes as `Verify ui phase 6 polish performance`.
95 +## Done criteria
97 +- Accepted Nugu direction is visible in dark and light mode.
98 +- Long streams remain responsive.
99 +- Code and diffs show plaintext immediately and upgrade lazily.
100 +- Tests and mise checks pass.

docs/super/plans/2026-07-01-ui-extension-phase-7-hardening-e2e-playbook.md

Modified
1 -# UI Extension Phase 7 Implementation Plan
3 -> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 -**Goal:** Harden `/ui` for release with packaging, docs, E2E coverage, and a reproducible manual playbook.
7 -**Architecture:** Freeze feature scope, strengthen tests around complete flows, document limitations, and make manual/browser verification explicit. Use zellij instead of tmux on win32; use tmux only on non-win32 systems where available.
9 -**Tech Stack:** Pi extension static checks, Vitest, Playwright Chrome/Firefox, zellij on win32, tmux on non-win32, mise tasks.
11 -**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 -**Phase:** Phase 7: Package Hardening, E2E, Manual Playbook
15 ----
17 -## Scope
19 -Included:
21 -- Finalize package metadata, README, dependencies, and no sibling-extension imports.
22 -- Complete unit, harness, browser component, fake-RPC E2E, and real-RPC smoke tiers.
23 -- Harden cleanup for subprocess, server, sockets, timers, widgets, terminal restore, and browser clients.
24 -- Add manual playbook with zellij on win32 and tmux on non-win32.
25 -- Document trusted full JS, LAN HTTP token model, terminal minimization limits, RPC unsupported semantics, and troubleshooting.
27 -Excluded:
29 -- New UI features.
30 -- Automatic RPC restart.
31 -- Old-browser support.
33 -## Files
35 -Create:
37 -- `extensions/ui/playwright.config.ts`.
38 -- `extensions/ui/__e2e__/fake-rpc.spec.ts`.
39 -- `extensions/ui/__e2e__/real-rpc-smoke.spec.ts`.
40 -- `extensions/ui/docs/manual-playbook.md`.
41 -- `extensions/ui/scripts/zellij-smoke.mjs`.
42 -- `extensions/ui/scripts/tmux-smoke.mjs`.
43 -- `extensions/ui/__tests__/cleanup.test.ts`.
45 -Modify:
47 -- `extensions/ui/package.json`.
48 -- `extensions/ui/README.md`.
49 -- `mise.toml` — only if a repo task is needed for UI E2E; otherwise keep using existing root tasks.
50 -- `docs/super/specs/2026-07-01-ui-extension-design.md` only for discovered corrections.
52 -## Tasks
54 -### Task 1: Cleanup hardening
56 -- [x] Write cleanup tests for `/ui off`, Esc, session shutdown, RPC death, socket close, and repeated stop.
57 -- [x] Fix runtime cleanup until all resources are idempotently closed.
58 -- [x] Run cleanup and all UI tests; expect PASS.
59 -- [x] Commit `Harden ui cleanup`.
61 -### Task 2: E2E fake-RPC tier
63 -- [x] Add Playwright config and fake-RPC E2E fixture.
64 -- [x] Test auth shell, snapshot, stream render, composer submit, tool lifecycle, widget render, telemetry digest, and shutdown.
65 -- [x] Add package script `test:e2e` for UI workspace.
66 -- [x] Run `npm --workspace extensions/ui run test:e2e`; expect PASS.
67 -- [x] Commit `Add ui fake rpc e2e`.
69 -### Task 3: Real-RPC smoke tier
71 -- [x] Add real-RPC smoke with long startup budget and explicit skip only when `pi` is unavailable.
72 -- [x] Verify active-branch seeded history, one browser prompt, command state, and shutdown.
73 -- [x] Keep the test small and non-flaky; fake-RPC remains the broad E2E tier.
74 -- [x] Run real smoke locally; expect PASS or documented environment skip.
75 -- [x] Commit `Add ui real rpc smoke`.
77 -### Task 4: Manual playbook scripts
79 -- [x] Implement `scripts/zellij-smoke.mjs` for win32: create zellij background session, launch Pi, send `/ui`, dump screen, extract URL, open browser, test 401, run `/ui off`, and leave attach/kill commands.
80 -- [x] Implement `scripts/tmux-smoke.mjs` for non-win32 with the same checkpoints.
81 -- [x] Ensure win32 path never invokes tmux.
82 -- [x] Add `docs/manual-playbook.md` with exact zellij/tmux commands and evidence checkpoints.
83 -- [x] Commit `Add ui manual smoke playbook`.
85 -### Task 5: Documentation and package review
87 -- [x] Update `extensions/ui/README.md` with commands, security/trust model, LAN token, zellij-on-win32 playbook, troubleshooting, and known limitations.
88 -- [x] Verify package metadata has no version, `private:true`, `main:index.ts`, MIT, peer deps, and required harness dev dep.
89 -- [x] Run `mise run readme -- ui` only if the generated style preserves required manual details; otherwise update manually.
90 -- [x] Commit `Document ui extension`.
92 -### Task 6: Release gate verification
94 -- [x] Run `npx vitest run extensions/ui/__tests__/*.test.ts`.
95 -- [x] Run UI E2E.
96 -- [x] Run actual static check for `ui`.
97 -- [x] Run `mise run install`, `mise run check -- ui`, and then `mise run ci` if unrelated dirty work does not make CI meaningless.
98 -- [x] Run win32 zellij manual smoke on this host.
99 -- [x] Commit fixes as `Verify ui release hardening`.
101 -## Done criteria
103 -- Full UI feature set is tested at unit/harness/browser/E2E levels.
104 -- Manual playbook is executable and uses zellij on win32.
105 -- README documents commands, trust, LAN HTTP, limitations, and troubleshooting.
106 -- Static check, mise install/check, and relevant test suites pass.
1 +# UI Extension Phase 7 Implementation Plan
3 +> **For agentic workers:** REQUIRED SUB-SKILL: Use /skill:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
5 +**Goal:** Harden `/ui` for release with packaging, docs, E2E coverage, and a reproducible manual playbook.
7 +**Architecture:** Freeze feature scope, strengthen tests around complete flows, document limitations, and make manual/browser verification explicit. Use zellij instead of tmux on win32; use tmux only on non-win32 systems where available.
9 +**Tech Stack:** Pi extension static checks, Vitest, Playwright Chrome/Firefox, zellij on win32, tmux on non-win32, mise tasks.
11 +**Roadmap:** `docs/super/roadmaps/2026-07-01-ui-extension-roadmap.md`
13 +**Phase:** Phase 7: Package Hardening, E2E, Manual Playbook
15 +---
17 +## Scope
19 +Included:
21 +- Finalize package metadata, README, dependencies, and no sibling-extension imports.
22 +- Complete unit, harness, browser component, fake-RPC E2E, and real-RPC smoke tiers.
23 +- Harden cleanup for subprocess, server, sockets, timers, widgets, terminal restore, and browser clients.
24 +- Add manual playbook with zellij on win32 and tmux on non-win32.
25 +- Document trusted full JS, LAN HTTP token model, terminal minimization limits, RPC unsupported semantics, and troubleshooting.
27 +Excluded:
29 +- New UI features.
30 +- Automatic RPC restart.
31 +- Old-browser support.
33 +## Files
35 +Create:
37 +- `extensions/ui/playwright.config.ts`.
38 +- `extensions/ui/__e2e__/fake-rpc.spec.ts`.
39 +- `extensions/ui/__e2e__/real-rpc-smoke.spec.ts`.
40 +- `extensions/ui/docs/manual-playbook.md`.
41 +- `extensions/ui/scripts/zellij-smoke.mjs`.
42 +- `extensions/ui/scripts/tmux-smoke.mjs`.
43 +- `extensions/ui/__tests__/cleanup.test.ts`.
45 +Modify:
47 +- `extensions/ui/package.json`.
48 +- `extensions/ui/README.md`.
49 +- `mise.toml` — only if a repo task is needed for UI E2E; otherwise keep using existing root tasks.
50 +- `docs/super/specs/2026-07-01-ui-extension-design.md` only for discovered corrections.
52 +## Tasks
54 +### Task 1: Cleanup hardening
56 +- [x] Write cleanup tests for `/ui off`, Esc, session shutdown, RPC death, socket close, and repeated stop.
57 +- [x] Fix runtime cleanup until all resources are idempotently closed.
58 +- [x] Run cleanup and all UI tests; expect PASS.
59 +- [x] Commit `Harden ui cleanup`.
61 +### Task 2: E2E fake-RPC tier
63 +- [x] Add Playwright config and fake-RPC E2E fixture.
64 +- [x] Test auth shell, snapshot, stream render, composer submit, tool lifecycle, widget render, telemetry digest, and shutdown.
65 +- [x] Add package script `test:e2e` for UI workspace.
66 +- [x] Run `npm --workspace extensions/ui run test:e2e`; expect PASS.
67 +- [x] Commit `Add ui fake rpc e2e`.
69 +### Task 3: Real-RPC smoke tier
71 +- [x] Add real-RPC smoke with long startup budget and explicit skip only when `pi` is unavailable.
72 +- [x] Verify active-branch seeded history, one browser prompt, command state, and shutdown.
73 +- [x] Keep the test small and non-flaky; fake-RPC remains the broad E2E tier.
74 +- [x] Run real smoke locally; expect PASS or documented environment skip.
75 +- [x] Commit `Add ui real rpc smoke`.
77 +### Task 4: Manual playbook scripts
79 +- [x] Implement `scripts/zellij-smoke.mjs` for win32: create zellij background session, launch Pi, send `/ui`, dump screen, extract URL, open browser, test 401, run `/ui off`, and leave attach/kill commands.
80 +- [x] Implement `scripts/tmux-smoke.mjs` for non-win32 with the same checkpoints.
81 +- [x] Ensure win32 path never invokes tmux.
82 +- [x] Add `docs/manual-playbook.md` with exact zellij/tmux commands and evidence checkpoints.
83 +- [x] Commit `Add ui manual smoke playbook`.
85 +### Task 5: Documentation and package review
87 +- [x] Update `extensions/ui/README.md` with commands, security/trust model, LAN token, zellij-on-win32 playbook, troubleshooting, and known limitations.
88 +- [x] Verify package metadata has no version, `private:true`, `main:index.ts`, MIT, peer deps, and required harness dev dep.
89 +- [x] Run `mise run readme -- ui` only if the generated style preserves required manual details; otherwise update manually.
90 +- [x] Commit `Document ui extension`.
92 +### Task 6: Release gate verification
94 +- [x] Run `npx vitest run extensions/ui/__tests__/*.test.ts`.
95 +- [x] Run UI E2E.
96 +- [x] Run actual static check for `ui`.
97 +- [x] Run `mise run install`, `mise run check -- ui`, and then `mise run ci` if unrelated dirty work does not make CI meaningless.
98 +- [x] Run win32 zellij manual smoke on this host.
99 +- [x] Commit fixes as `Verify ui release hardening`.
101 +## Done criteria
103 +- Full UI feature set is tested at unit/harness/browser/E2E levels.
104 +- Manual playbook is executable and uses zellij on win32.
105 +- README documents commands, trust, LAN HTTP, limitations, and troubleshooting.
106 +- Static check, mise install/check, and relevant test suites pass.
108 108 ## Execution note