@hienlh/ppm 0.23.10 → 0.23.12

package/docs/architecture/android-emulator-plan-260920.md

@@ -0,0 +1,376 @@
+# Plan: Android Emulator trong PPM
+
+Ngày: 2026-09-20. Trạng thái: **đề xuất triển khai, chưa viết tính năng**.
+Đối chiếu repository tại `641da958`; nghiên cứu tài liệu và mã nguồn upstream ngày 2026-09-20.
+
+## 1. Kết quả cần đạt
+
+Người dùng mở **Android** trong PPM, chọn máy ảo, bấm Start/Open và thao tác trực tiếp: chạm, vuốt, giữ, gõ chữ, Home/Back/Recent, xoay màn hình. Mỗi máy có tab riêng; desktop có thể pop-out/PiP theo cơ chế sẵn có, điện thoại dùng giao diện cảm ứng. Emulator chạy trên máy host cài PPM; trình duyệt chỉ hiển thị và gửi thao tác.
+
+Phạm vi mặc định: Android Emulator chính thức/AVD trên cùng host PPM; Linux trước để xác minh, Windows và macOS là các nền tảng phải kiểm chứng trước khi công bố hỗ trợ. Hai máy ảo độc lập là bài kiểm tra thiết kế; mặc định giới hạn một máy do PPM khởi động đồng thời để tránh chiếm tài nguyên host. Có thể tăng giới hạn sau kiểm tra RAM/CPU.
+
+Không yêu cầu Android Studio đang mở. SDK, system image và AVD có thể dùng chung với Studio. Không cam kết toàn bộ tính năng của Studio: debugger, profiler, Gradle integration, camera/AR/XR và device farm nằm ngoài bản đầu. Điện thoại USB/Wi-Fi là giai đoạn mở rộng, chưa phải yêu cầu đã chốt.
+
+## 2. Android Studio thực sự làm gì
+
+| Bằng chứng upstream | Bài học áp dụng cho PPM |
+|---|---|
+| `EmulatorController.kt` kết nối localhost gRPC, gắn credentials, quản lý trạng thái và gọi các dịch vụ emulator | Backend PPM giữ kết nối native và thông tin xác thực; browser dùng API PPM. [S1] |
+| `EmulatorView.kt` yêu cầu `streamScreenshot` ở định dạng `RGB888`, kích thước theo vùng hiển thị; hủy feed cũ khi thay đổi | Lấy màn hình trực tiếp từ emulator, scale theo viewport; không chụp cửa sổ desktop. [S2] |
+| View chuyển chuột/phím/touch thành sự kiện emulator | Viết bộ chuyển input Android riêng; không dùng bộ inject input vào OS của Remote Desktop. [S2] |
+| `emulator_controller.proto` có screenshot, input, clipboard, VM state, rotation/display metadata và timestamp | Có cơ sở xây tab tương tác; phải pin schema và probe năng lực từng phiên bản. [S3] |
+| Device Manager quản lý AVD, cấu hình phần cứng và system image | Tách **danh sách máy/config** khỏi **phiên đang chạy/viewer**. [S4] |
+| Tài liệu CLI minh họa Studio dùng `-qt-hide-window`, `-grpc-use-token`, `-idle-grpc-timeout` | Flags phụ thuộc phiên bản; kiểm tra `-help` trên binary thật, không copy cứng hoặc nhầm “ẩn cửa sổ” với “headless”. [S5] |
+
+Đính chính đề xuất ban đầu: **chưa có căn cứ nói Android Studio dùng scrcpy cho embedded emulator**. Nguồn đã đọc cho thấy gRPC + screenshot feed. Scrcpy là một phương án của PPM, không phải mô tả kiến trúc Studio.
+
+Phần khác biệt cần tự thiết kế: Studio và emulator ở cùng máy; PPM có browser qua LAN/tunnel. Một frame RGB 720×1280 cần 2,764,800 byte; 30 fps xấp xỉ 83 MB/s trước overhead. Không chuyển raw RGB qua Internet. Con số là phép tính dung lượng, không phải benchmark.
+
+Google cũng có demo browser dùng gateway nối gRPC `rtc2` và WebRTC. Đây là hướng tham khảo riêng cho web, không đồng nghĩa embedded Studio dùng WebRTC. Proto `rtc_service_v2.proto` trên SDK máy này ghi rõ API experimental. [S6]
+
+## 3. Bằng chứng tại máy và repository
+
+Kiểm tra read-only, chưa boot/stop AVD và chưa thử phiên streaming:
+
+- Emulator: `/home/thawngho/Android/Sdk/emulator/emulator`, phiên bản **36.5.10.0**, build **15081367**.
+- `-list-avds`: **Pixel_9**, **Pixel_Tablet**.
+- `-accel-check`: **KVM installed and usable**; chưa xác minh GPU rendering hoặc tốc độ boot.
+- ADB trên PATH: `/usr/bin/adb`, **1.0.41**, package **37.0.0-android-tools**. Khi triển khai cần chọn một ADB nhất quán với SDK; không thay server ADB đang chạy chỉ vì phát hiện khác phiên bản.
+- SDK có `emulator_controller.proto`, `rtc_service.proto`, `rtc_service_v2.proto`, snapshot/UI protos. Có file không chứng minh RPC hoạt động trên binary: phase 0 phải gọi thử.
+- PPM có Hono/Bun WS, ffmpeg, WebCodecs viewer, tab pool và pop-out. Remote Desktop session hiện thu hồi **mọi** session khác khi mở phiên mới; không thể dùng nguyên manager này cho Android.
+- TabPool giữ tab ẩn mounted. Phải ngừng feed/release input theo visibility thực tế, không chỉ cleanup khi unmount.
+- Decoder Remote Desktop đang tạo timestamp theo 30 fps; chưa phải pipeline đồng bộ audio/video.
+- `.claude/workflows/*`, `.ck.json` và biến `CK_PLAN_DATE_FORMAT` không có trong checkout này. Plan dùng `YYMMDD` theo tên tài liệu hiện có; áp dụng `CLAUDE.md`, roadmap, code/design standards đã có.
+
+## 4. Quyết định kiến trúc / ADR đề xuất
+
+### ADR-A: Backend native gRPC cho emulator
+
+**Ưu tiên:** Bun service gọi emulator gRPC; ADB dùng discovery/boot readiness, cài APK và logcat. SDK command-line tools quản lý AVD khi tới giai đoạn quản lý máy.
+
+> **Đính chính sau Phase 3 (2026-09-21, đo thật):** logcat **không** đi qua `adb logcat` như câu
+> trên viết, mà qua gRPC `streamLogcat` — dùng lại đúng channel đã xác thực, không thêm tiến
+> trình con mỗi máy, và có sẵn cả khi adb serial còn `null` lúc máy đang boot. Theo chính comment
+> trong proto, `streamLogcat` chạy `logcat` trong guest qua `AdbShellStream`, nên dữ liệu là một.
+> Cái mất là không đẩy được filter xuống thiết bị. **Cài APK thì vẫn đi adb** đúng như trên, vì
+> `EmulatorController` không có RPC install nào. Hai phép đo đi kèm, cả hai đều trái với thứ đọc
+> proto ra: `LogMessage.sort = Parsed` **không được cài đặt** và hỏng bằng cách gửi stream rỗng
+> (334 message trống trong 8 s, không lỗi), còn unary `getLogcat` trả `12 UNIMPLEMENTED`. Xem
+> `android-emulator-phase3-report-260921.md` §2.
+
+Lý do: phù hợp emulator-first và học đúng ranh giới từ Studio; không cần cài server vào Android guest cho đường chính. Rủi ro: schema/auth/discovery thay đổi; thư viện gRPC Node không mặc nhiên tương thích Bun/binary compiled. Thử `@grpc/grpc-js` với protobuf client được generate/pin trước; chỉ thêm dependency sau spike. Không tự viết lại HTTP/2/gRPC, không đổi backend sang Go hay thêm Python service mặc định. [S9]
+
+Chỉ chọn subset RPC cần dùng nhưng giữ nguồn/schema, revision và license. Không tải proto tùy ý từ mạng lúc chạy.
+
+**Cấm `protoLoader.loadSync()`.** Nó đọc file `.proto` từ đĩa lúc chạy, và trong binary
+`bun build --compile` đường dẫn trỏ vào `/$bunfs/root/` nên ném `ENOENT` — đo được ở Phase 0, đúng
+bài học "compiled PPM không với tới node_modules của chính nó" trong CLAUDE.md. Đường duy nhất là
+`protoLoader.fromJSON()` với descriptor JSON sinh lúc build và `import` vào module để bundler nhúng.
+Đã chứng minh: binary chạy từ thư mục ngoài checkout trả `getStatus` trong 17.5 ms và pass toàn bộ
+bài cancellation/deadline/cleanup y hệt bản chạy từ source. Tạo compatibility record gồm emulator version, auth mode, RPC capabilities và lỗi có hướng xử lý.
+
+### ADR-B: Media qua WebSocket cùng origin là đường cơ sở
+
+| Phương án | Ưu điểm | Chi phí / kết luận |
+|---|---|---|
+| gRPC RGB → ffmpeg H.264 → WSS → WebCodecs | Input/lifecycle giống Studio; đi cùng đường truy cập PPM | Encode thêm trên host, copy frame, xử lý resize; **phương án ưu tiên cần benchmark** |
+| Native emulator WebRTC + signaling qua PPM | Browser media stack, có khả năng giảm encode trung gian | API experimental; ICE/TURN, NAT và chính sách thu hồi phiên cần kiểm chứng; để mở rộng sau |
+| Scrcpy server → H.264 qua ADB → WSS | Luồng nén từ guest, dùng được cho máy thật | Client/server phải khớp phiên bản, deploy artifact vào guest; **contingency nếu gRPC media không đạt** [S7] |
+| gRPC PNG → WSS → canvas | Dễ xác minh correctness, không phụ thuộc VideoDecoder | Băng thông/CPU lớn; chế độ tương thích giới hạn kích thước và fps, không dùng làm chuẩn hiệu năng |
+| **gRPC MMAP side channel → ffmpeg → WSS** | Pixel không đi qua grpc-js chút nào; gRPC chỉ mang `seq`/`timestampUs` | `ImageTransport.MMAP` (`emulator_controller.proto` field 6): client sở hữu handle shm/mmap. Đo được 318/318 frame có pixel thật, **0 byte** qua gRPC. Proto tự cảnh báo *"the mmap can result in tearing"*. **Để dành**, chưa cần ở v1 |
+
+**Quyết định (Phase 0, 2026-09-21): giữ option 1 làm đường chính.** Đo trên host Linux, emulator
+36.5.10, Bun 1.3.11, `@grpc/grpc-js` 1.14.0, với chuyển động liên tục thật: RGB888 720×1600 đạt
+**39.9 fps / 131.9 MiB/s**, full-res 1080×2400 đạt **40.0 fps / 297.4 MiB/s**, **không rớt frame nào**
+(seq liên tục). Pipeline đầy đủ ra **360/360 frame** decode được ở **3.90 Mbit/s**. `h264_vaapi` tốn
+**0.33 core** so với 64–80% của libx264. Ngưỡng 83 MB/s mà plan lo không phải là ngưỡng. Không
+chuyển sang scrcpy. Chi tiết: `docs/architecture/android-emulator-phase0-report-260921.md`.
+
+Ba chi tiết schema phải tôn trọng khi hiện thực hoá — cả ba đều đã được **đo lại ở Phase 2**, và
+hai trong số đó hoá ra đoạn văn cũ ở đây ghi sai:
+
+1. `ImageFormat.width/height` là **hộp bao giữ tỉ lệ**, không phải kích thước ra lệnh (proto:
+   *"will never exceed the given width, but can be less"*). Phải xin hộp **vuông** để trần áp lên
+   cạnh dài, và đọc kích thước thật từ `format.width/height` của chính frame — đó là trường
+   output, và cũng là thứ khiến việc xoay màn hình chạy đúng mà không phải đoán.
+2. ~~Thứ tự pixel là bottom-up nên phải có `vflip`~~ — **sai**. Câu đó chép từ comment trong
+   proto. So từng hàng với `adb exec-out screencap` trên emulator 36.5.10: khớp ở mức chênh lệch
+   **1.21**/pixel khi căn thẳng và **37.15** khi lật. Buffer là **top-down**; thêm `vflip` làm mọi
+   màn hình lộn ngược mà không báo lỗi.
+3. Sau khi một `streamScreenshot` bị cancel, mọi stream mở sau đó trả **đúng 1 frame** rồi im, kể
+   cả trên channel mới. Nên đổi mức chất lượng **không được** mở lại stream: mở đúng một stream ở
+   trần rung cao nhất cho cả phiên, đổi rung bằng `scale` trong ffmpeg.
+
+Và một chi tiết input: `Touch.x/y` luôn là **pixel panel gốc chưa xoay**, không đổi theo hướng màn
+hình (đo bằng `getevent`), nên toạ độ trên frame đã xoay phải được xoay ngược lại trước khi gửi.
+
+Chỉ productize một đường chính; không xây đồng thời ba backend. Nếu raw→H.264 không đạt ngân sách, ghi ADR cập nhật rồi chuyển sang scrcpy cho video/control thay vì kết hợp input của backend này với geometry backend khác chưa được kiểm chứng.
+
+WebSocket được Cloudflare hỗ trợ; cần heartbeat và reconnect vì kết nối có thể bị ngắt. WebRTC media đi qua tuyến ICE riêng; việc trang PPM mở được qua tunnel không chứng minh media WebRTC tới được. Không mặc định yêu cầu người dùng dựng TURN. [S6, S10]
+
+### ADR-C: Module nội bộ độc lập, lazy-load
+
+Đặt backend trong `src/services/android/`, UI trong `src/web/components/android/`. Dùng route/tab riêng; chỉ trích xuất tiện ích codec thực sự dùng chung. Runtime registry theo device, không tạo framework plugin mới.
+
+Đây là bước thực dụng theo hiện trạng: extension RPC/webview hiện chưa có media/control capability đã được chứng minh. Giữ API service có ranh giới rõ để có thể chuyển thành plugin khi nền tảng hỗ trợ. Không nới quyền spawn toàn cục của extension chỉ để gọi emulator.
+
+### ADR-D: Vòng đời emulator tách khỏi viewer
+
+Đóng tab/refresh/mất mạng không stop emulator. Stop là hành động riêng, chỉ áp dụng máy PPM sở hữu; máy attach từ Studio mặc định chỉ Disconnect. Không kill ADB server, không kill theo tên process.
+
+## 5. Luồng và hợp đồng nội bộ
+
+```mermaid
+flowchart LR
+  B[Android tab trong browser] <-->|HTTPS: máy và tác vụ| H[PPM Hono API]
+  B <-->|WSS: input, trạng thái, video nén| W[Android session manager]
+  H --> D[Device registry và lifecycle]
+  D --> T[SDK tools và ADB]
+  W -->|input và trạng thái| G[gRPC adapter localhost]
+  G <--> E[Android Emulator]
+  G -->|RGB frames nội bộ host| F[ffmpeg encoder]
+  F -->|H.264 access units| W
+  T --> E
+```
+
+Đồ thị là phương án ADR-B ưu tiên; thay media adapter nếu phase 0 chọn khác.
+
+**Identity:** `avdId` dựa trên canonical AVD config path + SDK context; ID opaque cấp bởi server. `deviceId` chỉ runtime instance, đi cùng `generation`, ADB serial, PID/start identity và gRPC endpoint. Không dùng ADB serial làm ID tab bền vững. Restart máy làm runtime identity thay đổi nhưng vẫn mở lại đúng AVD.
+
+**State máy:** `stopped → starting → booting → ready → stopping → stopped`; lỗi boot thành `error`, ADB offline hiện riêng. **State viewer:** `disconnected → connecting → viewing/controlling → paused/reconnecting/error`. Khả năng video sẵn sàng có thể trước Android boot-complete; install APK chỉ khi guest ready.
+
+**Discovery:** SDK path do người dùng chọn → env Android SDK phù hợp → vị trí chuẩn OS/PATH. Tôn trọng AVD home overrides — nhưng **`ANDROID_AVD_HOME` thay thế chứ không cộng dồn**: set nó thì AVD của người dùng biến mất khỏi `-list-avds`, nên PPM không được set biến này toàn cục (đo ở Phase 0). Và **không bao giờ truyền `-grpc <port>`**: `emulator -help` ghi `-grpc-use-jwt ... (default, disable with -grpc flag)`, nên ghim port cố định chính là tự hạ kênh điều khiển xuống không xác thực — luôn discovery. Thực tế gRPC đã bật sẵn không cần cờ nào (`Started GRPC server at 127.0.0.1:8554, security: Local, auth: +token`), và emulator tự cảnh báo *"Basic token auth should only be used by android-studio"*, nên PPM đi đường JWT. Đọc discovery files của emulator user hiện tại với giới hạn kích thước; xác minh PID/process identity, AVD và endpoint loopback trước sử dụng. Không giả định mọi OS/version dùng một đường dẫn `avd/running`. Credentials chỉ nằm backend. Hỗ trợ token/JWT theo phiên bản đã test, báo unsupported nếu chưa có; không hạ xuống unauthenticated khi thất bại. [S8]
+
+**Lifecycle:** mutex theo AVD + start idempotency; refresh/chạm Start hai lần không spawn hai process. Dùng argv, deadline boot có cấu hình, log ring buffer, cancellation. Timeout cho lựa chọn Retry/Stop rõ ràng; chỉ xử lý process được task đó tạo. Kiểm tra AVD đang được Studio dùng, không xóa lock file để cưỡng ép chạy.
+
+**PPM restart:** không tự boot máy theo restored tab. Runtime registry được dựng lại từ discovery + ownership record tối thiểu; kiểm tra PID start identity để tránh PID reuse. Encoder/viewer session kết thúc, emulator do PPM tạo được giữ chạy và nhận lại nếu runtime/process ownership còn hợp lệ. Phase 0 phải thử thực tế hành vi process group/service shutdown trên từng OS; khi chưa xác minh thì không quảng cáo giữ máy xuyên restart.
+
+**Session:** một controller lease trên mỗi runtime device; client thứ hai bị báo đang sử dụng, có hành động Take control rõ ràng. V1 chưa cần nhiều viewer thụ động. Hai device có hai session độc lập; tuyệt đối không ngắt Remote Desktop hay máy khác. Lease đề xuất heartbeat 5 giây, expire 15 giây; server hết lease phải giải phóng input. Reconnect lấy nonce mới và không replay thao tác cũ. Server cấp capability reconnect ngắn hạn, chỉ giữ trong memory của browser, bind session/device/token generation; reconnect hợp lệ thay socket cũ nguyên tử, không đợi lease hết hạn. Take control tăng generation, hủy cả pending auth/reconnect của controller cũ. Refresh mất capability thì chờ lease hoặc Take control chủ động; mục tiêu reconnect 5 giây chỉ áp dụng kết nối còn capability hợp lệ.
+
+**API dự kiến (tên có thể điều chỉnh theo convention repository):**
+
+| Endpoint | Contract chính |
+|---|---|
+| `GET /api/android/capabilities` | SDK/tool versions, host accel, streaming/backend readiness, lý do thiếu |
+| `GET /api/android/devices` | AVD + runtime instance, state, ownership và capabilities; không token/đường dẫn nhạy cảm |
+| `POST /api/android/avds/:avdId/start` | Validated launch profile, idempotency key → operation ID |
+| `GET /api/android/operations/:id` | Pending/progress/result/error; client reconnect không khởi động lại operation |
+| `POST /api/android/devices/:deviceId/stop` | Check generation và ownership, graceful stop → operation ID |
+| `POST /api/android/devices/:deviceId/sessions` | Viewport/codec capabilities → session ID + nonce ngắn hạn |
+| `WS /ws/android` | Auth đầu tiên, device/session binding; JSON control + binary video |
+| `DELETE /api/android/sessions/:id` | Đóng viewer/idempotent, không stop máy |
+| Phase 3: install/screenshot/logcat | API typed riêng, không mở generic shell/RPC proxy |
+| Phase 4: AVD create/delete/wipe | Thao tác riêng, xác nhận target và hậu quả |
+
+HTTP dùng `ok/err` hiện có. Các thao tác lâu trả operation ID, không giữ HTTP request chờ boot nhiều phút. Discovery khi Android UI hoạt động có interval/backoff giới hạn; feature chưa dùng không spawn/poll liên tục.
+
+**WS envelope phiên bản 1:** auth, ready, geometry, input, input-reset, quality, visibility, heartbeat, error; metadata gồm session generation và geometry generation. Binary video có version, generation, sequence, timestamp/PTS, config/keyframe flag, kích thước payload. Final layout ghi trong `src/shared/android-protocol.ts` và test với fixture trước khi viết UI. Không gửi base64 video trong JSON.
+
+**Media:** một encoder mỗi active device; RGB chỉ trong host. Giới hạn frame dimensions, message size và pending buffers. Không block Bun loop bằng encode sync. Trước encode chỉ giữ latest frame; ffmpeg rawvideo stdin không có frame header nên một khi bắt đầu write phải hoàn tất frame đó, kể cả partial write/backpressure. Chỉ drop nguyên frame chưa bắt đầu; validate stride, pixel layout và kích thước. Sau encode không drop delta tùy ý rồi tiếp tục decode: bỏ đến keyframe hợp lệ hoặc restart/request keyframe. Resize/rotation bắt đầu generation mới, gửi codec config + keyframe, bỏ late frames từ generation cũ. Duy trì timestamp monotonic từ pipeline; chưa thêm audio ở v1.
+
+## 6. UX và input
+
+**Device Manager:** danh sách AVD: tên, loại phone/tablet, API/ABI, trạng thái, Start/Open/Disconnect/Stop theo ownership. Empty state phân biệt chưa có SDK, thiếu emulator/system image, chưa có AVD, acceleration không dùng được. Không spinner vô thời hạn.
+
+**Viewer:** toolbar Home, Back, Recent, Rotate, Volume, Power, Fit/100%, Disconnect; hiển thị trạng thái kết nối và lựa chọn chất lượng. Stop nằm trong menu riêng. Action chưa được backend hỗ trợ có lý do rõ ràng. Phase 3 thêm Screenshot, Install APK và Logcat ở panel phụ.
+
+**Mobile:** viewport giữ đúng aspect ratio; nút điều khiển chính ở dưới, target ≥44×44; menu/dialog dùng bottom sheet. Có nút Keyboard và vùng nhập text dùng IME. Pinch trên màn hình Android gửi multi-touch khi bật chế độ tương tác; zoom viewer có chế độ riêng để hai hành vi không xung đột.
+
+**Input correctness:**
+
+- Pointer capture, ID ổn định cho nhiều ngón; down/move/up/cancel; long press và drag dựa trên thời gian thực, không lặp `adb shell input` mỗi frame.
+- Ánh xạ CSS bounds/letterboxing → frame hiển thị → native display coordinates. Xét DPR, rotation, resize, display metadata. Reject input theo geometry cũ; cancel gesture khi geometry đổi.
+- Pointer cancel, blur, tab hidden, mất controller, disconnect đều release keys/touches. Timeout server là lớp dự phòng cho browser mất mạng không gửi được release.
+- Phân biệt physical key với text/IME (`beforeinput`, composition). **Phase 0 đo được: `sendKey.text` chỉ mang ASCII in được [32-127).** `"café"` tới nơi thành `"caf"`, còn tiếng Việt, emoji và CJK mất sạch — không lỗi, chỉ cắt cụt âm thầm. `setClipboard` giữ nguyên `"Tiếng Việt 😀"` (xác minh cả round-trip lẫn nhìn trong guest). Nên **mọi ký tự ngoài ASCII phải đi đường clipboard**, không phải `text`; đó là ràng buộc thiết kế của IME mobile ở phase 2, không phải chi tiết tối ưu.
+- Clipboard là thao tác copy/paste chủ động giữa browser và guest, không bật đồng bộ clipboard OS host mặc định. Giữ nguyên giới hạn quyền clipboard của browser.
+- Không chiếm shortcut PPM khi canvas không focus. PiP dùng đúng ownerDocument/window, không gắn listener cứng vào document chính.
+
+`VideoDecoder` phụ thuộc secure context và codec thực tế. Probe `isConfigSupported`; HTTPS/localhost dùng H.264 khi có. Browser không hỗ trợ hoặc LAN HTTP có chế độ PNG tốc độ thấp, ghi nhãn chất lượng rõ ràng; nếu không đạt mức dùng được thì báo hướng mở HTTPS/trình duyệt hỗ trợ, không để màn hình đen. Backend được chọn phải chứng minh được screenshot fallback: gRPC dùng PNG, nếu chọn scrcpy thì thử ADB screenshot có giới hạn tần suất/độ phân giải; không giữ thêm toàn bộ gRPC stack chỉ để fallback. [S11]
+
+## 7. Bảo vệ phiên và dữ liệu
+
+Đây là yêu cầu chức năng của kênh điều khiển host/device, không phải bổ sung hệ thống phân quyền nhiều người dùng.
+
+- Bắt buộc PPM auth enabled; validate Origin đầy đủ ở upgrade và tạo phiên, có allowlist dev proxy cụ thể. Không copy kiểm tra chỉ hostname của Remote Desktop như bảo đảm same-origin chung. **Phase 0 xác nhận câu trên đúng:** `assertSessionAllowed` trong `src/server/routes/remote-desktop.ts:28-46` so sánh **hostname, bỏ qua port**, có chủ ý và có comment — dev proxy của Vite ghi đè `Host` mà không thêm `X-Forwarded-Host`, nên so cả `host:port` sẽ chặn mọi phiên dev. Android dùng lại đúng khuôn đó, nhưng phải nhớ nó **không** phải bảo đảm same-origin đầy đủ: một trang khác **port** trên cùng hostname vẫn qua được.
+- Nonce single-use TTL đề xuất 30 giây, bind auth context, device/generation, session và quyền control. Chưa auth không tạo encoder/gRPC session; auth timeout đề xuất 5 giây. PPM hiện dùng bearer token chung, không giả định đã có user/session identity phía server: logout browser phải gửi close/release, server có lease expiry dự phòng; token đổi/auth tắt thu hồi toàn bộ Android sessions.
+- RPC chỉ gọi endpoint loopback server đã discovery; browser không nhập URL gRPC hay command tùy ý. Không public ADB/gRPC/TURN credentials qua API/logs.
+- Bound control message size, input rate, video/encoder allocation và concurrent operations. Không nuốt key-up/cancel vì rate limiting; quá tải thì reset input.
+- Cài APK nhận upload ID hoặc file qua existing path guards; xác thực đích, quota, deadline, cleanup temp qua `getPpmDir()`. Không cho upload chọn đường ghi tự do. Không tự uninstall app khi install lỗi chữ ký.
+- Log chỉ metadata/errors, phiên bản, latency/bytes/drop counts; không lưu màn hình, clipboard hay text gõ mặc định.
+- AVD/SDK người dùng hiện có giữ vị trí native Android; dữ liệu quản lý/cache riêng PPM qua `getPpmDir()`. Tests dùng SDK/AVD home giả và `PPM_HOME` tạm.
+
+## 8. Bản đồ thay đổi code
+
+Tất cả đường dẫn Android dưới đây là **dự kiến tạo**, chưa tồn tại.
+
+| Phần | Điểm tích hợp |
+|---|---|
+| Backend Android | `src/services/android/`: sdk-discovery, device-registry, emulator-launcher, grpc-client/auth, session-manager, input, video-pipeline, operations |
+| Schema/protocol | `src/shared/android-protocol.ts`, generated/pinned protobuf dưới module Android; build-time generate, runtime không cần protoc |
+| HTTP/WS | `src/server/routes/android.ts`, `src/server/ws/android.ts`; đăng ký Hono/upgrade/dispatch trong `src/server/index.ts` |
+| UI | `src/web/components/android/`: manager, tab, viewport, toolbar, input hooks, setup; lazy-loaded |
+| Tab registry | `src/web/stores/tab-store.ts`, `panel-utils.ts`, `components/layout/tab-pool.tsx`, `tab-content.tsx` |
+| Pop-out/icon/navigation | `window-panel-persistence.ts`, `lib/tab-type-icons.ts`, nav rail/mobile drawer/command palette; dùng `tab-host` sẵn có |
+| Settings | `settings-categories.ts`, `settings-section-content.tsx`, settings routes, `src/types/config.ts`, config service |
+| Codec reuse | Remote Desktop H.264 decoder/SPS/NAL helpers: trích xuất phần thuần dùng chung nếu cần, giữ regression tests đường cũ |
+| Packaging | `package.json`, `.npmignore`, build/release pipeline, third-party notices; kiểm tra npm và compiled binary |
+
+SDK path/default launch limits là host config trong KV hiện có; fit/quality là preference từng browser. Chưa cần migration DB mới hoặc ấn định migration number. Chỉ lưu ownership metadata tối thiểu nếu restart reconciliation thực sự cần; không lưu secret hoặc process handle trong workspace JSON.
+
+## 9. Các giai đoạn và điều kiện hoàn thành
+
+### Phase 0 — Chứng minh protocol, runtime và media
+
+- Tạo spike riêng, scratch PPM_HOME và test AVD do task tạo; không sửa Pixel_9/Pixel_Tablet của người dùng để test destructive flows.
+- Pin emulator/proto/dependency versions; đọc help thực tế, kiểm chứng discovery/token hoặc JWT, `getStatus`, screenshot, touch/key/text, rotation. So sánh tọa độ bằng test app có điểm chạm hiển thị.
+- Chạy gRPC dưới Bun source **và compiled PPM**, working directory ngoài checkout; chứng minh cancellation/deadline/resource cleanup.
+- Đo gRPC RGB→ffmpeg→H.264→browser; PNG làm correctness baseline. Có fixture stdin slow-consumer/partial writes để xác minh frame boundary. Nếu không đạt, benchmark scrcpy candidate và screenshot fallback tương ứng; native WebRTC chỉ spike phụ khi có lý do, không làm dependency để hoàn thành v1.
+- Đo trên LAN và PPM tunnel: fps khi có chuyển động, bitrate, click-to-visible p50/p95, CPU/RSS của PPM + encoder riêng và emulator riêng, ảnh hưởng chat/terminal, rotation, hide/resume.
+- Output: report versions/commands/numbers, quyết định media, giới hạn browser/OS, schema/auth compatibility. **Gate:** boot/stream/control/cleanup thật và ngân sách sơ bộ đạt; chưa đạt thì sửa ADR trước phase 1.
+
+### Phase 1 — SDK discovery và vòng đời máy
+
+- Capabilities/setup diagnostics; list AVD/runtime, Start/Open/Stop có ownership, trạng thái và operation progress.
+- Registry identity, per-AVD mutex, timeouts, stderr bounded, port/discovery races và restart reconcile.
+- Gate: start đúng một máy, không double spawn; attach máy ngoài không nhận quyền stop; lỗi SDK/KVM/boot actionable; không tác động ADB/AVD khác.
+
+### Phase 2 — Tab hiển thị và điều khiển hoàn chỉnh
+
+- Dedicated route/WS auth + lease, media adapter đã chọn, viewport và Android input.
+- Toolbar cơ bản, Unicode/IME, multi-touch, rotation, quality, pause/resume, disconnect/reconnect.
+- Tích hợp tab, pop-out/PiP và mobile; fallback browser; không bật emulator khi restore workspace.
+- Gate: nghiệm thu tình huống 1–9 và 11 bên dưới trên served build. Đây là bản đầu có thể dùng để thao tác máy ảo hằng ngày; tình huống 10 thuộc phase 3, tình huống 12 thuộc phase 4.
+
+> **Đính chính sau khi người dùng thử thật (đo 2026-09-21).**
+> Ba lỗi, cả ba **không sinh ra một dòng lỗi nào** ở bất kỳ tầng nào:
+> 1. **Ảnh cuộn/méo từ khung thứ hai trở đi.** `FileSink.write()` của Bun nhận trọn chunk và trả
+>    về một con số **không phải** "đã ghi bao nhiêu byte của chunk này". Vòng `off += n` vì thế
+>    gửi lại phần đuôi nhiều lần: đo bằng `cat`, một khung 4.924.800 byte tới nơi thành
+>    **28.043.840 byte (5,7×)**. Luồng rawvideo vào ffmpeg lệch vĩnh viễn — khung **đầu** vẫn
+>    đúng, mọi khung sau bị vẽ cuộn. Ghi **một lần** rồi `flush()`. Test phải đo **byte tới nơi**,
+>    không đếm khung: mọi bộ đếm trong pipeline đều báo đúng trong khi ffmpeg nhận gấp 5,7 lần.
+> 2. **Màn hình đứng yên thì không có video.** `streamScreenshot` là *change-driven*: đo được
+>    **2 khung trong 15 giây** trên một máy nằm ở launcher. Chỉ nạp ffmpeg khi có khung mới nghĩa
+>    là luồng H.264 im hẳn, và người vào xem lúc đó kẹt ở "Waiting for the first frame…" cho tới
+>    khi có gì đó động đậy trong guest. Phải **nạp lại khung cuối theo nhịp fps** của rung. E2E cũ
+>    không thấy vì nó chạy kèm một vòng swipe liên tục.
+>    Nhưng nhịp đầy đủ không miễn phí: đo trên máy đứng im, một viewer giữ ffmpeg ở **55% một
+>    core** — mỗi khung rgb24 đều bị scale và hwupload lại dù không một pixel nào đổi. Lùi về 10
+>    fps sau 1 giây không đổi thì còn **11,7 khung/s vào ffmpeg, 23% một core**, trong khi client
+>    vẫn nhận **24,9 access unit/s**: demuxer rawvideo khai 25 fps nên CFR mặc định của ffmpeg
+>    nhân bản khung để bù lại, mà khung nhân bản gần như không tốn gì — phần đắt nằm ở mỗi khung
+>    *đầu vào*. Hệ quả cần biết: **tốc độ trên dây luôn là 25 fps**, không phải `fps` của rung
+>    (24/30/30), và `-g = fps/2` vì thế là GOP 0,6 s chứ không phải 0,5 s. Chưa sửa — muốn đúng
+>    thì phải đặt `-framerate` cho input, và đó là thay đổi ngoài phạm vi ba lỗi này.
+> 3. **`avd.id` mới là danh tính, không phải `avd.name`.** File discovery có cả hai, và với mọi AVD
+>    tạo bằng Android Studio chúng khác nhau: `avd.id=Pixel_9` cạnh `avd.name=Pixel 9`. Khớp theo
+>    tên hiển thị thì emulator đang chạy không khớp được dòng AVD của chính nó — danh sách hiện
+>    máy là "stopped" *và* mọc thêm một dòng `external:` không có geometry. Không thấy suốt 4 phase
+>    vì mọi AVD dùng để test đều tên một từ, nơi hai trường trùng nhau.
+
+### Phase 3 — Công cụ làm việc với app
+
+- Install APK bằng picker/upload và chọn file project; progress/cancel, lỗi ABI/minSdk/chữ ký, split APK chỉ nếu có workflow rõ ràng.
+- Screenshot tải về; clipboard chủ động; Logcat theo device với filter, pause/clear-view và ring buffer, không ghi vô hạn vào DB.
+- Gate: install đúng target khi có hai máy; hủy upload không để temp; logs hidden ngừng subscription; không log nội dung input/clipboard.
+
+### Phase 4 — Device Manager đầy đủ hơn
+
+- Tạo AVD từ system image đã cài, chọn phone/tablet profile, ABI theo host, RAM/storage hợp lý. Các API typed bọc SDK tools, không nối chuỗi shell.
+- **Bắt buộc ghi `hw.keyboard=yes` vào `config.ini`.** `avdmanager` mặc định `no` (Studio thì `yes`), và khi tắt thì touch gRPC vẫn chạy hoàn hảo trong khi `sendKey` trả `OK` và **không một ký tự nào tới guest** — không lỗi, không log. Đã loại trừ allowlist và `-no-window` bằng thực nghiệm ở Phase 0.
+- Cold boot, quick-boot policy; quản lý snapshot là task riêng, serialize với start/stop. Wipe/Delete có xác nhận tên máy và hậu quả, chỉ khi stopped.
+- Có thể cài system image qua UI sau khi hiển thị dung lượng, license và tiến trình; không tự chấp nhận SDK license hay tải nhiều GB khi mở tab. SDK tools có `sdkmanager`/`avdmanager`; tài liệu mới cũng giới thiệu Android CLI, nên probe tool có sẵn và pin đường được test. [S4, S5, S12, S13]
+- Gate: tạo→boot→stop→mở lại giữ dữ liệu; wipe/delete chỉ trúng AVD đã chọn; không sửa AVD Studio đang chạy. Không cần build lại toàn bộ SDK Manager của Studio.
+
+> **Đính chính sau Phase 4 (đo 2026-09-21, xem `android-emulator-phase4-report-260921.md`).**
+> Ba điều plan không nói, và cả ba đều hỏng **im lặng**:
+> 1. `ANDROID_AVD_HOME` phải trỏ vào một thư mục **có thật**. Trỏ vào thư mục không tồn tại thì
+>    `avdmanager` không báo lỗi — nó quay về `~/.android/avd`, tức thư mục AVD **thật của người
+>    dùng**, và ghi AVD vào đó. Giống hệt trường hợp không set biến này cho tiến trình con.
+>    `createAvd` phải `mkdir -p` avdHome trước, và vẫn kiểm tra `config.ini` có hiện ra đúng chỗ.
+> 2. **Wipe không được xoá `userdata.img`.** `emulator -help-disk-images` xếp nó vào nhóm ảnh
+>    *khởi tạo* cùng `system.img`, và định nghĩa `-wipe-data` là *copy nội dung của userdata.img
+>    vào userdata-qemu.img* — xoá nó là xoá bản gốc mà wipe cần để khôi phục.
+> 3. `hardware-qemu.ini.lock` chứa pid **kết thúc bằng byte NUL** (`519772\0`). `trim()` không bỏ
+>    NUL, nên `Number()` ra `NaN` và mọi emulator đang chạy đều bị đọc là "không khoá" — dòng cảnh
+>    báo "đang mở trong Android Studio" chưa từng hiện kể từ Phase 1. Lấy cụm số đầu file.
+
+### Phase 5 — Đóng gói, ổn định và phát hành
+
+- Test source/npm/compiled ở Linux, Windows, macOS; đường dẫn có khoảng trắng/Unicode, PATH của service khác terminal, không có Android Studio, thiếu ffmpeg/tool.
+- Test thực trên mobile Safari/Chrome và desktop Chromium/Firefox theo capabilities, cả mạng cục bộ/tunnel.
+- Documentation setup/troubleshoot/compatibility, license notices; feature flag opt-in, lazy load; tắt flag phải cleanup session/encoder nhưng không wipe/stop emulator ngoài ý muốn.
+- Gate: artifacts được serve đúng build, regression Remote Desktop/chat/terminal pass; rollback chỉ tắt tính năng, không thay schema hoặc AVD data.
+
+Thứ tự: **0 → 1 → 2 → 3 → 4 → 5**. Việc kiểm tra packaging/mobile/security diễn ra từ phase 0–2, không để cuối mới phát hiện. Có thể release preview sau phase 2 nếu ghi rõ chưa có AVD CRUD/công cụ phase 3–4. Chưa gắn số version hay lịch ngày trước khi có benchmark và test trên OS đích.
+
+## 10. Ngân sách hiệu năng và cách đo
+
+Đây là **mục tiêu nghiệm thu đề xuất**, chưa phải số đo đã đạt:
+
+| Chỉ số | Mục tiêu ban đầu |
+|---|---|
+| Chất lượng chuẩn | 720p-equivalent, 30 fps khi màn hình chuyển động; bitrate mục tiêu 2–6 Mbps |
+| LAN input-to-visible | p95 ≤150 ms trên host/reference client đủ tài nguyên |
+| Tunnel input-to-visible | p95 ≤300 ms với RTT ≤100 ms, downstream ≥10 Mbps; báo điều kiện mạng khi đo |
+| Thời gian first frame | ≤3 giây từ khi emulator đã sẵn sàng, không gồm cold boot |
+| Encoder backlog | ≤2 raw frames; encode/decode/network queues đều có hard cap |
+| PPM + encoder overhead | Mục tiêu ≤1 CPU core bình quân, ≤250 MiB RSS tăng thêm/device ở profile chuẩn; không tính emulator |
+| Idle/ẩn | Dừng feed/encoder sau grace ≤5 giây khi không còn viewer; emulator vẫn chạy |
+| Reconnect | ≤5 giây sau mạng phục hồi trong test, nonce mới/keyframe mới, không input cũ |
+| Soak | 60 phút có rotate/reconnect; không tăng RAM đều, không rò encoder/gRPC/touch |
+
+Đo click-to-visible bằng test app đổi màu khi nhận touch, quay/timestamp trên cùng browser clock; không trừ trực tiếp clock host và client chưa đồng bộ. Ghi cấu hình host/GPU/guest/browser và thông số mạng. Nếu ngân sách không đạt thì hạ profile hoặc đổi media theo ADR; không gọi số mục tiêu là benchmark.
+
+## 11. Ma trận kiểm thử và Definition of Done
+
+Unit/contract: parser SDK/discovery và stale PID, identity, argv/path validation, protocol packet bounds, codec generation, geometry tại 0/90/180/270°, DPR/letterbox, pointer/key cancellation, IME composition, lease expiry/nonce replay.
+
+Integration: fake SDK processes + gRPC fixture có auth, timeout và disconnect; HTTP/WS thực qua route registration; lỗi giữa lúc auth/start/rotate, start hai lần, logout, đổi token, stop nhầm generation, thiếu quyền host. Hai thiết bị chạy đồng thời không tranh session; feature không ảnh hưởng Remote Desktop.
+
+E2E bắt buộc với emulator thật và **bundle đã build/serve trên instance riêng**:
+
+1. SDK có sẵn → list AVD → Start → boot progress → Open có hình.
+2. Tap/long press/swipe/drag; hai ngón pinch; Home/Back/Recent/Power/Volume hoạt động.
+3. Gõ `Tiếng Việt`, emoji **qua đường clipboard** (Phase 0 chứng minh `sendKey.text` không mang được); ASCII qua `key`; Enter/Backspace; bàn phím mobile không gõ đôi/mất composition.
+4. Rotate liên tục trong khi kéo, resize/fit/100%; chạm vẫn đúng vị trí, không stuck touch.
+5. Chuyển tab ẩn/hiện, pop-out/PiP/return; không double stream hoặc mất ownership.
+6. Mất mạng 30 giây rồi reconnect; input được release, không replay click; máy vẫn chạy.
+7. Client thứ hai nhận thông báo đang dùng; Take control thu hồi client cũ và input cũ.
+8. Hai AVD khác nhau và Remote Desktop không đá nhau; vượt limit có lỗi rõ ràng.
+9. Refresh/restore workspace không boot hoặc tự giành control; emulator đã chạy có thể reconnect.
+10. Install APK đúng máy; screenshot đúng khung Android; Logcat có cap/cleanup.
+11. Stop máy PPM sở hữu; máy Studio chỉ Disconnect; stale PID/AVD lock không gây kill sai.
+12. Wipe/Delete task-test AVD có xác nhận và đúng target; Cold boot/Quick boot không mất dữ liệu ngoài hành động wipe.
+
+Release checklist: cold browser origin tránh cache cũ; kiểm tra hash/timestamp served bundle; full asset pipeline gồm Monaco/precompress; isolated `PPM_HOME` và port đã kiểm tra không trùng. Không stop `ppm.service` từ session này để build. Nếu suite tổng treo theo baseline đã biết, báo rõ và chạy từng file liên quan, không tuyên bố full suite pass.
+
+## 12. Những việc cần chốt bằng thử nghiệm
+
+- Bun gRPC + compiled binary có hoạt động ổn với auth/stream cancellation không?
+- RGB→H.264 có đạt ngân sách trên Linux/Windows/macOS, hay nên chọn scrcpy media?
+- Phiên bản emulator tối thiểu, flags headless/hidden, discovery layout và auth modes nào được hỗ trợ chính thức?
+- Unicode/text injection thực tế của gRPC trên các guest image; cơ chế nào cần cho mobile IME?
+- Process lifecycle qua PPM restart/service shutdown ở từng OS giữ emulator như thiết kế được không?
+- Chọn máy Windows/macOS và thiết bị browser thật để chạy ma trận; máy hiện tại chỉ chứng minh prerequisites Linux.
+
+Các câu hỏi này không chặn việc lập plan. Chúng là deliverable của spike/validation; không âm thầm coi giả định là chức năng đã có.
+
+## Nguồn tham khảo
+
+- **S1 — Studio controller (pinned revision):** https://android.googlesource.com/platform/tools/adt/idea/+/2aa920453118ffa8cd6b2996ca95e4e7187d01c2/streaming/src/com/android/tools/idea/streaming/emulator/EmulatorController.kt
+- **S2 — Studio view (cùng revision; đọc raw Gitiles):** https://android.googlesource.com/platform/tools/adt/idea/+/2aa920453118ffa8cd6b2996ca95e4e7187d01c2/streaming/src/com/android/tools/idea/streaming/emulator/EmulatorView.kt
+- **S3 — Emulator controller schema:** https://android.googlesource.com/platform/tools/base/+/refs/heads/mirror-goog-studio-main/emulator/proto/emulator_controller.proto ; đối chiếu file SDK cục bộ 36.5.10 ở `emulator/lib/emulator_controller.proto`.
+- **S4 — Device Manager / AVD:** https://developer.android.com/studio/run/managing-avds
+- **S5 — Emulator CLI:** https://developer.android.com/studio/run/emulator-commandline
+- **S6 — Google browser/WebRTC demo:** https://github.com/google/android-emulator-container-scripts/blob/master/gateway/DEMO.md ; đối chiếu `emulator/lib/rtc_service_v2.proto` cục bộ, có cảnh báo experimental.
+- **S7 — Scrcpy architecture/protocol:** https://github.com/Genymobile/scrcpy/blob/master/doc/develop.md
+- **S8 — Emulator gRPC/authentication:** https://android.googlesource.com/platform/external/qemu/+/686efa16baf59d776cadc3f975d12570fe44bbb9/android/android-grpc/docs/
+- **S9 — gRPC Node API (không phải chứng nhận Bun compatibility):** https://grpc.io/docs/languages/node/basics/
+- **S10 — Cloudflare WebSocket support:** https://developers.cloudflare.com/network/websockets/
+- **S11 — Browser VideoDecoder:** https://developer.mozilla.org/en-US/docs/Web/API/VideoDecoder
+- **S12 — sdkmanager:** https://developer.android.com/tools/sdkmanager
+- **S13 — avdmanager:** https://developer.android.com/tools/avdmanager
+- **S14 — Host acceleration:** https://developer.android.com/studio/run/emulator-acceleration
+
+Nguồn branch/master là tài liệu động, chỉ dùng để nghiên cứu. Khi triển khai phải pin revision/hash dependency và giữ notices tương ứng. Kế hoạch không sao chép nguyên implementation Studio và không bundle SDK/system images vào PPM.

package/docs/architecture/data-and-storage.md

@@ -19,7 +19,7 @@ the loop seeded from the bus (windowed + rolling summary).
 | **TagService** | Session tagging CRUD, bulk operations, tag-session enrichment | seedDefaultTags, getTagsByProject, createTag, updateTag, deleteTag, setSessionTag, bulkSetSessionTag, getSessionTags, getTagSessionCounts |
 | **DraftService** | Chat draft auto-save per session, 50KB cap | get, upsert, delete, deleteOrphaned |
 | **FileFilterService** | Glob pattern matching + precedence-enforced filtering (hardcoded ⊂ global ⊂ project) | mergeFilters, isPathIgnored, matchesPattern |
-| **SystemMetricsService** (`src/services/system-metrics/`) | Whole-machine Task Manager backend: CPU per core + RAM via `node:os`, disk/net/GPU + all processes via per-OS collectors (Linux `/proc`, macOS `ps`, Windows one long-lived PowerShell REPL child, `Win32_Process` + `PerfRawData` per 2 s tick), delta-based CPU%, grouping by app root, aggregate-only 30-min history. Two SSE tiers on `/api/system/resources/stream`: `light` (status bar, no children spawned) and `full` (`?processes=1`, demand-gated collectors, 60 s teardown). Subscriber lease (sid + 10 s ping, 30 s expiry) because Cloudflare tunnel never propagates client disconnects. Guarded `POST /resources/kill`: protected set (PPM server/supervisor/edge/cloudflared, OS-critical names), ancestor/tree-intersection rule, `startedAt` identity re-query → 409, JSON + `X-PPM-Request` header. | subscribe, unsubscribe, ping, getLatest, kill, reapExpired |
+| **SystemMetricsService** (`src/services/system-metrics/`) | Whole-machine Task Manager backend: CPU per core + RAM (`/proc` on Linux, `host_statistics64` on macOS, `node:os` elsewhere), disk/net/GPU + all processes via per-OS collectors (Linux `/proc`/`/sys`; macOS the kernel over `bun:ffi` — `host_statistics64`, `proc_pid_rusage`, SMC, IOReport, CoreWLAN — plus `ps` and one memoised `ioreg`/`netstat`/`ifconfig` read per tick; Windows one long-lived PowerShell REPL child, `Win32_Process` + `PerfRawData` per 2 s tick), delta-based CPU%, grouping by app root, aggregate-only 30-min history. Two SSE tiers on `/api/system/resources/stream`: `light` (status bar, no children spawned) and `full` (`?processes=1`, demand-gated collectors, 60 s teardown). Subscriber lease (sid + 10 s ping, 30 s expiry) because Cloudflare tunnel never propagates client disconnects. Guarded `POST /resources/kill`: protected set (PPM server/supervisor/edge/cloudflared, OS-critical names), ancestor/tree-intersection rule, `startedAt` identity re-query → 409, JSON + `X-PPM-Request` header. | subscribe, unsubscribe, ping, getLatest, kill, reapExpired |
 
 **Key Files:** `src/services/*.service.ts`, `src/services/tag.service.ts`, `src/services/ppmbot/*.ts`, `src/services/bash-output-spy.ts`, `src/services/system-metrics/system-metrics.service.ts`, `src/services/system-metrics/kill-guard.ts`, `src/services/system-metrics/powershell-session.ts`, `src/services/redact-secrets.ts`, `src/services/file-filter.service.ts`, `src/cli/commands/bot-cmd.ts`
 

package/docs/architecture/plugins-and-tracing.md

@@ -4,8 +4,9 @@ Two rules adopted on 2026-09-11, borrowed from DeepSeek Harness: **Everything is
 run is traceable.** PPM is a platform that embeds things around an AI agent — the IDE is one of
 those things, not the product.
 
-**Status: design only. Nothing in this document is built.** Current priority is finishing the
-features already in flight; this exists so the work starts from a decision instead of a guess.
+**Status (2026-09-25): Rule 1's trace is built** — `src/services/session-trace/` and
+`src/web/lib/trace-client.ts`; where the build departs from the design is listed under *As built*.
+**Rule 2 is still design only**; it exists so that work starts from a decision instead of a guess.
 
 Rewriting the backend in Go was considered and rejected on the same day — see `docs/lessons-learned.md`.
 
@@ -160,11 +161,12 @@ real question too, and it keeps one `seq` space per key.
 "All of the browser's logs" is read as: `console.error` and `console.warn` are sent; `console.log`
 and `info` go into a **50-entry ring buffer** that rides along as breadcrumbs on the next error. That
 is what a failure needs — the lines just before it — without paying for logging while nothing is
-wrong.
+wrong. (Reversed when built: every level is sent — see *As built*.)
 
 Ingest is one route — `POST /api/trace` — taking a small batch. It sits behind `authMiddleware` like
-the rest of `/api/*` (`index.ts:177`), so an error raised while logged out is lost; accepted. Three
-things it needs, none optional:
+the rest of `/api/*` (`index.ts:177`), so an error raised while logged out is lost; accepted. (As
+built, the client holds such rows until a sign-in — see *As built*.) Three things it needs, none
+optional:
 
 - **A cap and a schema check.** Batch ≤ 50, payload ≤ 16 KB each; treat the body as hostile and drop
   what does not fit.
@@ -178,8 +180,9 @@ Client side, `root-error-boundary.tsx:87` and `chunk-recovery.ts` already know s
 `main.tsx`** so it lives in the boot shell — in a lazy chunk it could not report the one failure that
 matters most, a missing chunk. The case where the entry never runs at all (`__ppmEntryRan` false)
 gets a bundle-free beacon in `index.html`'s inline watchdog, reading the Bearer token from
-`localStorage["ppm-auth-token"]`. Buffer locally and flush with `sendBeacon`/`keepalive` on
-`pagehide`, because the common case for a fatal client error is that the network is also what broke.
+`localStorage["ppm-auth-token"]`. Buffer locally and flush with `keepalive` on `pagehide`, because
+the common case for a fatal client error is that the network is also what broke. (Not `sendBeacon`:
+it cannot carry the `Authorization` header.)
 
 ### Retention
 
@@ -194,6 +197,44 @@ sessions that predate the log or were created outside PPM. That is the point whe
 tax gets repaid: cross-provider history stops depending on `getFullMessages` being implemented
 (only Claude implements it today, so the search index is better for one provider than the others).
 
+### As built (2026-09-25)
+
+What differs from the design above, and why:
+
+- **Every console level is sent**, at the user's request: batched (errors within 1 s, the rest
+  within 5 s), capped at 300 entries a minute per tab, then one `console_dropped{count}`. Each
+  error-level entry still carries the 50 lines before it as breadcrumbs.
+- **Logged out is held, not lost.** A 401 leaves the queue in place and nothing is sent again until
+  the stored token changes — a storage read every 5 s, no request — so a fresh device's login screen
+  is not the one page that cannot be debugged. Rows still only reach the server authenticated. The
+  watchdog beacon cannot do this: when the entry never ran there is no code left to retry with.
+- **`trace_aliases`** maps an id a provider migrated to (`session_migrated`) back to the trace the
+  run started under, so a follow-up, an abort or a browser row filed under the new id joins it.
+- **`context_added`** records the shared provider context PPM prefixes to a message (or hands to a
+  provider that places it), in full — at most 12 000 characters, and only when it changed. Found in
+  verification: a mock asked approval for `rm -rf` because the word "remove" was in
+  `~/.claude/CLAUDE.md`, text the trace had not recorded. Design instructions are not recorded; they
+  are rebuilt from the stored slug.
+- **A bare system signal is counted on the block it arrives in.** The Claude SDK sends a data-less
+  `system/thinking_tokens` between every two thinking deltas; treated as events, they split each
+  thinking block into a row per delta — 84 of one real turn's 92 rows. Inside a text or thinking
+  block such a signal now becomes `signals: {thinking_tokens: N}` on the block's row; outside one it
+  is still a row of its own.
+- **`run_closed` only for an unanswered turn.** Every caller but the WebSocket stops reading at
+  `done`, so that is how a run normally ends and it gets no row. `consumer_closed` and `no_done` are
+  written only when a turn, or a follow-up queued behind it, never got its `done`.
+- **The API proxy** (`proxy-agent-turn.ts`) does not go through `ChatService`, so its stream is
+  wrapped in `traceStream` with origin `proxy`.
+- **Reading without sqlite:** `GET /api/trace/sessions/:id` returns a session's merged timeline —
+  its rows plus every browser row whose `ref_id` is one of its ids.
+- **Measured:** 50 mock turns against a clean HEAD and the traced build, alternating: `/api/health`
+  p50 0.85–0.94 ms and p99 4.4–5.0 ms on both, no event-loop stall on either. A synthetic heavy
+  stream (76 010 events → 6 040 rows) cost 49.7 ms in all, 0.57 µs per event; the worst single call
+  was the end-of-turn write at 3.75 ms.
+- **Not in the trace yet:** events of nested subagents (never streamed — see `CLAUDE.md`) and
+  background `bash_output`. The older `session_logs` / `logSessionEvent` still exists and could be
+  retired in favour of this log.
+
 ---
 
 ## Rule 2 — Everything is a plugin

package/docs/architecture/workspace-and-ui.md

@@ -263,20 +263,25 @@ A link may name one place in the file — `app.ts:120`, `app.ts:120-140`, `app.t
 
 ## Design mode
 
-A **Design tab** puts a design chat beside a live, sandboxed canvas of what the agent builds: a page or a slide deck (`kind` `page` or `slides`), made of plain HTML/CSS files the user can export or hand off to real code. It opens from the sidebar's Designs section, the palette's "New Design…" (the dialog is hosted by `command-palette-design-commands.tsx`, since the palette is mounted on every layout) or the deep link `/project/<p>/design/<slug>`. The layout follows the tab's own width, not the viewport (`lib/design/design-layout-mode.ts`): a draggable chat/canvas split at 940px and up, one pane below 860px (the previous layout holds in between, so dragging a panel divider does not flicker), switched by a Canvas | Chat toggle in the toolbar. The toolbar's Layout menu pins Auto / Split / Canvas only / Chat only per device (`design-view-prefs.ts`), and Expand canvas lifts the canvas over the whole window (Esc or Exit full view to leave). Below `md` it is always one pane with a Canvas / Chat / More bar in the thumb zone. Every one of these is the same tree (`design-split-layout.tsx`) restyled by CSS, because moving the iframe reloads the design and unmounting the chat drops its socket; the one reload left is PPM's shell moving the whole tab into its mobile slot when the viewport crosses `md`. UI in `src/web/components/design/`, one tab per design, never popped out (`NON_POPPABLE_TAB_TYPES`: the bridge accepts messages only from an iframe whose parent is the main window).
+A **Design tab** puts a design chat beside a live, sandboxed canvas of what the agent builds: a page or a slide deck (`kind` `page` or `slides`), made of plain HTML/CSS files the user can export or build in real code from a new chat. It opens from the sidebar's Designs section, the palette's "New Design…" (the dialog is hosted by `command-palette-design-commands.tsx`, since the palette is mounted on every layout) or the deep link `/project/<p>/design/<slug>`. The layout follows the tab's own width, not the viewport (`lib/design/design-layout-mode.ts`): a draggable chat/canvas split at 940px and up, one pane below 860px (the previous layout holds in between, so dragging a panel divider does not flicker), switched by a Canvas | Chat toggle in the toolbar. The toolbar's Layout menu pins Auto / Split / Canvas only / Chat only per device (`design-view-prefs.ts`), and Expand canvas lifts the canvas over the whole window (Esc or Exit full view to leave). Below `md` it is always one pane with a Canvas / Chat / More bar in the thumb zone. Every one of these is the same tree (`design-split-layout.tsx`) restyled by CSS, because moving the iframe reloads the design and unmounting the chat drops its socket; the one reload left is PPM's shell moving the whole tab into its mobile slot when the viewport crosses `md`. UI in `src/web/components/design/`, one tab per design, never popped out (`NON_POPPABLE_TAB_TYPES`: the bridge accepts messages only from an iframe whose parent is the main window).
 
 **Storage** (`src/services/design/`, REST under `/api/project/:name/designs`, `src/server/routes/designs.ts` plus one sub-router per feature):
 - `designs/<slug>/` is the design: `index.html` (the entry), `design.json` (`title`, `kind`, `entry`, timestamps and the agent's `tweaks[]`; unknown fields are carried through) and whatever else the agent writes.
-- `designs/DESIGN.md` and `designs/tokens.css` are the project's design system, shared by every design (a page links `../tokens.css`).
+- `designs/DESIGN.md` and `designs/tokens.css` are the *default app's* design system (every project has one, implicitly, at the project root) shared by every design that belongs to it — a page links `../tokens.css` and `../systems/default/kit/app.css`. `DESIGN.md`'s `## Screens and components` section maps each screen to the source files that build it, so a design session can read them and reproduce a screen faithfully.
+- **Declared apps** (`design-systems.service.ts`, `design-systems-paths.ts`, REST `/api/project/:name/designs/systems`, mounted before `/:slug` since `systems` is a reserved slug): a monorepo or a container folder (Nxsys's `payroll-fe`, `umbrella-fe`…) can have more than one UI app, each with its own design system. An app is `designs/systems/<id>/system.json` (`label`, `root` relative to the project, `platform: "web" | "mobile"`, server-recorded `builtFrom`); its `DESIGN.md`/`tokens.css`/`kit/` live in that same folder — except `default`, whose files stay at the legacy `designs/` root and are never moved. Settings → Design's "Apps in this project" (`design-apps-settings-section.tsx`) declares, edits and removes them (no auto-detection); a design's `design.json` carries `system: "<id>"` (absent = `default`).
+- **Showcase and automatic setup.** Each app has a showcase design at the fixed slug `system-<id>` (manifest `showcaseFor`), listed in the sidebar's own "Design systems" group (`design-systems-sidebar-group.tsx`) instead of the ordinary Designs list. Most users do not know what a design system is, so nothing asks them: the first design turn of any kind for an app whose `DESIGN.md` does not exist yet carries an extra instructions block (`design-instructions-auto-setup-block.ts`, embedding `buildDesignSystemInitPrompt`'s own text so the two cannot drift) that tells the agent to notify the user in one line, set the system up itself — `designs/systems/<id>/` and the showcase's `designs/system-<id>/index.html` are explicitly writable for that one turn, the only exception to "Where to work" — then build what was actually asked for. `chatService.resolveDesignOptions` gets the showcase design's own folder and manifest ready first (`ensureShowcaseDesign`), so the agent only ever has to write its `index.html`. The canvas More menu's "Set up design system" still gets or creates that showcase and auto-sends the brief as an ordinary chat message, for a manual re-run (the stale "Refresh" flow); a tab that has not mounted its composer yet is retried for up to 2 s before falling back to a plain prefill. `builtFrom` (`git rev-parse HEAD` of the app's root) is recorded server-side, via the same debounced hook as the turn snapshot (`design-turn-snapshot.ts` → `recordBuiltFromAfterDesignTurn`): unconditionally after a showcase session's turn (what the manual re-run relies on to clear "may be outdated"), or, for an ordinary design, only the one turn that leaves `DESIGN.md` in place while `builtFrom` was still absent — never on a later, unrelated edit.
+- **Stale reminder** (`design-systems-stale.ts`, cached per (root, HEAD)): comparing `builtFrom.commit..HEAD` restricted to the app root, a theme/style-config file changed (`tailwind.config.*`, `postcss.config.*`, anything named or pathed like theme/tokens/variables, a `styles/`/`theme/` `.scss`/`.less` partial) or at least 20 changed UI files makes it stale ("may be outdated (N UI files changed)"); no repo, no `builtFrom`, or a timed-out `git diff` is "unknown", shown as "built <date>", never as stale.
 - `designs/<slug>/.design/` is the canvas's own data and is never part of the design: its `.gitignore` is `*`, the file watcher skips it (`file-watcher/ignore-rules.ts`), the preview route never serves it. `history/<id>/{meta.json,files/}` holds snapshots (`turn`, `pre-restore`, `before-edit`, `manual`; 100 protected + 30 `before-edit` kept, tree-hash dedupe, a design over 50 MB or 5000 files is skipped), `comments.json` the pinned comments. Because nothing there is watched, History and Comments refresh on `design:history_changed` / `design:comments_changed` from `/ws/global` (`design-events.ts`).
 - Restore snapshots the current state first and swaps through a journal (`design-restore-journal.ts`), so a crash mid-restore is finished from the staged copy on the next access rather than leaving half a design.
 - Every tree operation goes through `design-safe-walk.ts` (no symlinks, no FIFOs, no credential paths, depth and size caps).
 
 **The design session** is an ordinary chat session whose `session_metadata.design_slug` is fixed at creation (`POST /chat/sessions` with `designSlug`, accepted only on a provider with `supportsDesignInstructions` — Claude and Codex). `chatService.prepareSendOptions` rebuilds the instruction block from the stored slug on every turn, whoever sends it (WebSocket, `ppm chat send`, scheduler, bots): Claude gets it appended to the `claude_code` preset, Codex as `developerInstructions` (`design-instructions.ts`). The permission mode defaults exactly as for a new chat (the provider's configured default, normally `bypassPermissions`), because a design agent reads and searches the project constantly and a stricter default asked on every file. A user who picks `acceptEdits` for a design session gets the tighter design policy: project file reads and writes are approved, shell and every other tool ask (`design-tool-policy.ts` for Claude, `workspace-write` + `untrusted` for Codex). Every `done`, and every terminal background task, schedules a `turn` snapshot 2 s later (`design-turn-snapshot.ts`). The tab keeps the session in design mode: a fork is swapped in place, `/clear` starts the next session in the same tab, the embedded history lists only this design's sessions, and opening a design session from anywhere focuses its design tab (`openSessionInItsTab`, `tabSessionId()` in `src/web/lib/tab-session-id.ts`).
 
+**The user's design instructions** (Settings → Design, `design-settings-section.tsx`; `GET/PUT /api/settings/design`, `src/server/routes/design-settings.ts`) are one global text (config row `design.instructions`, 8 KB UTF-8 cap, `design-settings.service.ts`). `design-user-section.ts` appends them after PPM's block, quoted in a `<user_design_instructions>` block under a statement that PPM's rules win. `/name` and `$name` mentions (`src/shared/design-skill-mentions.ts`) are resolved per session against the skills that provider can load (`design-skill-sources.ts`: Claude's slash discovery for the project narrowed to `.claude`, `CLAUDE_CONFIG_DIR` and plugins, since the Skill tool cannot run a `.codex`/`.ppm` skill the composer also lists; Codex's `skills/list` for the session's cwd and account): Claude is told to invoke the canonical name with the Skill tool, Codex to use `$name` (Codex's own mention syntax, the same rewrite `provider-skill-sigil.ts` does in chat). A name found nowhere is "not a skill, read it as text", any mention adds the ask-before-installing rule, and an unreadable list (an empty codex answer counts) marks the names unchecked; listing has a 5 s timeout and a 60 s back-off after a failure so a broken codex cannot spawn an app-server per turn. The editor reuses the composer's `SlashCommandPicker` and `slash-trigger.ts`. When nothing named resolves and no `ui-ux-pro-max` is installed, the pane (and a hint in New Design) shows the upstream install commands (`design-skill-suggestion.ts`); PPM never installs a skill. Claude snapshots its system prompt at a session's first request and Codex reads developer instructions on connect, so a change reaches new design chats; the section is cached per session and text. e2e `tests/e2e/design-settings-e2e.mjs`.
+
 **The canvas** (`src/server/routes/design-preview.ts`):
 - `POST /api/design-preview` (authenticated) mints a token for one design and one purpose. A canvas token lives 30 min idle and 8 h at most, and is extended only by authenticated refreshes; within the last hour a refresh rotates it. Print and standalone tokens last 10 min and cannot be refreshed. Unauthenticated content reads never extend a token (`design-preview-tokens.ts`).
-- `/api/design-preview/content/<token>/<slug>/…` is mounted before auth and serves `designs/<slug>/**` plus the `../tokens.css` alias, nothing else. ACAO is `null`, which answers the sandboxed document's `Origin: null` and nobody else.
+- `/api/design-preview/content/<token>/<slug>/…` is mounted before auth and serves `designs/<slug>/**` plus two read-only aliases, `../tokens.css` and `../systems/<id>/**` (an app's folder; `default` remaps to the legacy `designs/` root), nothing else (`preview/design-preview-scope.ts`). ACAO is `null`, which answers the sandboxed document's `Origin: null` and nobody else.
 - `buildDesignCsp` (`preview/design-csp.ts`): `sandbox allow-scripts` (with `allow-modals` for the print view only), inline scripts and `'unsafe-eval'`, the CDN hosts in `src/shared/design-cdn-hosts.ts` for scripts, styles, fonts and images, and `connect-src` limited to the design's own files. Accepted residuals: jsdelivr and unpkg execute any npm/GitHub code, and a design script can still navigate its own frame; there is no shell `frame-src`, so the bridge's link guard and the 3 s liveness check are what catch it.
 - The HTML is instrumented with parse5 (`preview/html-instrument.ts`): every source element gets `data-ppm-id`, its start-tag offset in the BOM-less text, valid only for that file's `gen` (16 hex chars of SHA-256; linked stylesheets report theirs in `cssGens`). The bridge script is the first thing in `<head>`.
 - A dead token serves the expired page (`preview/expired-page.ts`), which posts `expired`; the canvas re-mints and reloads.
@@ -289,24 +294,29 @@ A **Design tab** puts a design chat beside a live, sandboxed canvas of what the
 
 **Write-backs:**
 - *Comments.* An anchor is `ppmId` + tag + text quote with prefix/suffix + a CSS path. It is re-resolved on every `ready` (same tag only, 0.55 similarity threshold, orphaned rather than guessed) and re-checked against the source by the server. The element context in a prompt is a snippet the server slices from the source (`design-comment-element-context.ts`), fenced as untrusted (`design-comments-prompt.ts`). "Send to AI" shows the whole message first and only fills the design chat's composer.
-- *Tweaks.* `design.json` declares controls bound to CSS custom properties. Moving one restyles the frame live; Apply patches the last winning declaration in the design's own `:root` or appends a `:root` block (`source/tweak-patch-plan.ts`). A value in `../tokens.css`, inside an at-rule or behind `!important` is refused, and values pass an allowlist, not a denylist.
+- *Tweaks.* `design.json` declares controls bound to CSS custom properties. Moving one restyles the frame live; Apply patches the last winning declaration in the design's own `:root` or appends a `:root` block (`source/tweak-patch-plan.ts`). A value set last in `../tokens.css` or `../systems/<id>/**` (both read-only), inside an at-rule or behind `!important` is refused, and values pass an allowlist, not a denylist.
 - *Move and resize.* The frame's `transform-commit` is a proposal. The parent writes it only with Move on, the chat idle, its own target, the current `ready` gen and `navigator.userActivation.isActive` (`src/web/lib/design/design-transform-proposal.ts`). The server re-checks the gen (409 `stale`) and the tag at the offset (409 `element-moved`), rate-limits (1 per 500 ms, 30 per minute), snapshots `before-edit` and writes only `translate`/`width`/`height` px into that element's `style` attribute.
 - *Undo* reverses the exact spans a canvas write replaced, with 32 characters of context on each side, so later AI edits elsewhere survive. The journal is in memory (50 writes per design, lost on restart); `cannot-undo` points to History (`design-edit-undo-journal.ts`).
 
+**Asking first, and variants.** The instructions tell the agent to ask at most 3 short questions, in one go, before the first build when the request leaves purpose, audience, content, style, page vs deck or the number of variants open (Claude with `AskUserQuestion`, Codex in a plain message), and never for edits or when told to just build. A design holds up to 5 variants: `index.html` is variant 1, `variant-2.html`… sit beside it, and `design.json` lists them as `variants: [{ file, label }]`.
+- `src/shared/design-variants.ts` parses that list tolerantly (flat `*.html` names only, deduped case-insensitively, entry forced first, capped at 5, labels 40 chars); `design-variants-resolve.ts` also drops files that do not exist yet. The summary carries `variants` and `variantWarnings` (shown in the canvas issues badge). A top-level page other than the entry appearing refetches the summary (`mayChangeVariants`), since an agent writes the manifest before the pages.
+- The switcher (`variants/`) is a toolbar menu on desktop and a More-sheet section on phones, shown from 2 variants; the choice is per design per device (`design-view-prefs.ts`) and falls back to the entry when the file leaves the list. Switching re-points the canvas through the token *refresh* (`retarget` in `use-design-preview-url.ts`), which keeps the token; `POST /api/design-preview` takes `entry`, which must be a listed variant. Comments, tweaks, move/resize and checks already key on the `ready` file; the print/standalone views, the single-HTML export and the "Build in new chat" brief use the variant on screen (the ZIP is the whole folder), and the automatic check says how many variants went unchecked.
+- Keeping or dropping a variant is done by the agent in the design chat, not from the canvas (there is no "Use this variant" button): the instructions tell it to make the kept file `index.html`, delete the dropped ones and update `variants` in `design.json` (or leave the field out for a single variant). The turn snapshot already covers what it deletes, so it is recoverable from Version history.
+
 **Exports** (`src/server/routes/design-export.ts`, `src/services/design/export/`, client `src/web/components/design/export/`):
-- ZIP: the design folder plus `DESIGN.md`/`tokens.css`, no dotfiles or `.design/`, capped at 5000 files / 512 MB.
-- Standalone HTML: local CSS, images, fonts and scripts inlined as data URLs within per-asset and total budgets. Whatever stays linked is listed (`X-PPM-Export-Warning-List`).
+- ZIP: the design folder plus `DESIGN.md`/`tokens.css`, and each app the design's own files reference via `../systems/<id>/` (re-rooted to `systems/<id>/**` in the zip; for `default` that means copying its legacy root files under `systems/default/`, since a static zip has no server-side alias to remap them), no dotfiles, `.design/` or `system.json`, capped at 5000 files / 512 MB.
+- Standalone HTML: local CSS, images, fonts and scripts inlined as data URLs within per-asset and total budgets, `../systems/<id>/**` assets included the same way as `../tokens.css`. Whatever stays linked is listed (`X-PPM-Export-Warning-List`).
 - PDF: the print view is a print-purpose token with `@page` rules and one page per `section.slide`, opened by a real `rel="noopener noreferrer"` link. Fidelity is the browser's own print engine.
 - PPTX: the bridge measures the laid-out slides (`bridge-extract-slides.ts`), `pptx-slide-mapper.ts` turns them into native text boxes, shapes and images, and `pptxgenjs` runs in a lazy chunk (`pptx-export.ts`). Gradients and shadows are approximated and images the canvas cannot read are skipped; each one is listed after the save, with the fonts PowerPoint needs.
 - Every download Blob is `application/octet-stream` (`design-export-client.ts`).
-- *Hand off to code* opens a new, ordinary chat with an editable brief (`design-handoff-prompt.ts`) that treats everything under `designs/` as untrusted reference material.
+- *Build in new chat* (a toolbar bar button, replacing "Hand off to code") opens a new, ordinary chat with an editable brief (`design-handoff-prompt.ts`, treats everything under `designs/` as untrusted reference material) and a screenshot of the variant on screen attached as an image — the same self-check screenshot `design_check` uses (`runCanvasCheck`), fed into the new tab's composer through its own drop path (`pendingAttachmentDataUrl` tab metadata → `externalFiles`). A capture failure still opens the chat, just without the image, and says so in a toast. Export stays for building on another machine.
 
 **Canvas self-check.** The agent runs on the server and never sees the canvas, so the frame measures itself (`bridge-layout-grid.ts`, `bridge-layout-boxes.ts`): grid items auto-placed into implicit tracks (found with an absolutely positioned `1 / -1` probe, whose box is the explicit grid), sideways page overflow, elements running off the viewport, text cut off by an `overflow: hidden` ancestor, content squeezed under 4 px, and overlapping in-flow siblings; the parent adds the runtime issues it collected and the device frame. At most 30 findings of 300 characters, validated again by the parent and the server (`src/shared/design-canvas-check.ts`) and fenced as untrusted when an agent reads them.
 - *`design_check` tool.* `/api/design-mcp` is a minimal MCP Streamable HTTP endpoint (JSON responses only) mounted before auth and authorized by a per-session capability token (`design/mcp/`, in memory, stored by SHA-256, bound to session + project + slug, revoked with the session). `chatService` adds it to a design session's options with a URL on the port the server actually bound (`server-listen-address.ts`). Claude gets it as an `http` MCP server with the token in `Authorization` and the tool pre-approved; Codex gets a `mcp_servers.ppm_design` config override on `thread/start`/`thread/resume` with `bearer_token_env_var`, so the token lives only in that app-server's environment. A call emits `design:check_request` on `/ws/global`; the first open canvas POSTs `/designs/:slug/check/:requestId` (authenticated, 768 KB cap) and the tool returns the text plus a JPEG screenshot (≤ 1280 px, ≤ 400 KB) drawn in the frame by `modern-screenshot`, whose source the parent sends in the lazy chunk it lives in. No canvas open means an error after 20 s.
 - *After each turn* (`use-design-auto-check.ts`): when the canvas reloaded during the turn or within 8 s of its end, it is measured once quiet for 700 ms; findings go into the issues badge and, at most twice per user message, back to the agent as a `[Canvas check]` message — sent only into an empty, idle composer, otherwise added as a chip.
 - Real-browser check of the grid rule and the screenshot: `node tests/e2e/design-canvas-check-e2e.mjs` (no PPM server; needs Playwright and Chrome).
 
-End to end: `tests/e2e/design-mode-e2e.mjs` (1366 px and 390 px, isolated server, scripted providers).
+End to end: `tests/e2e/design-mode-e2e.mjs` (1366 px and 390 px, isolated server, scripted providers; `PPM_DESIGN_E2E_ONLY=variants` runs the named steps only), including declaring an app, the New Design dialog's app picker (no setup step in it any more), a design's own first turn auto-setting its app's system up and building on it in the same turn, its showcase and stale reminder (`fixtures/design-mode-steps-systems.mjs`); Settings → Design itself is `tests/e2e/design-settings-e2e.mjs`.
 
 ## Terminal Flow