@compn3rd/pi-web-code-review 0.1.1 → 0.2.0

package/docs/compatibility.md

@@ -1,55 +1,43 @@
-# Latest-release compatibility check
+# Release compatibility and validation
 
-## Target
+## 0.2.0 target
 
-Checked npm's latest published `@jmfederico/pi-web`: **1.202610.3**, source revision `29f0ace6d955a458a947bb0f03673fa069afb8da`.
+Checked published **`@jmfederico/pi-web@1.202610.6`**, including its packaged `docs/plugins.md` and public browser/server declarations. The supported host minimum is now **1.202610.6**. The lockfile records the concrete development dependency. Compatibility with future releases is not implied by these checks.
 
-References:
+## Integration
 
-- [Release changelog](https://github.com/jmfederico/pi-web/blob/29f0ace6d955a458a947bb0f03673fa069afb8da/CHANGELOG.md)
-- [Version-matched plugin guide](https://github.com/jmfederico/pi-web/blob/29f0ace6d955a458a947bb0f03673fa069afb8da/docs/plugins.md)
-- Public browser/server declarations in the installed npm package, resolved through `@jmfederico/pi-web/plugin-api` and `@jmfederico/pi-web/server-plugin-api`.
+- Browser entrypoint migrated from API **v4 to v5**.
+- Declares the public **`pi-web/stylesheet-integration` v1** capability, resolves it in `start`, and installs one Lit controller per panel with `{ sharedUi: true }`. The host owns stylesheet adoption and cleanup on disconnect/reconnect. Missing or malformed capability values fail explicitly.
+- Uses shared `ui-button`, `ui-select`, `ui-toolbar` and `ui-file-row` patterns with component-owned responsive CSS and inherited `--pi-*` colour/font tokens. No private host imports, global CSS patches or stylesheet-text capability are used. Styling remains experimental upstream and must be rechecked on upgrades.
+- Server entry remains API **v3**, which `1.202610.6` still supports (with an upstream deprecation diagnostic). Its workspace-scoped, read-only Git operations are unchanged. There is no need to accept new machine/project scopes for this UI release.
+- Composer-chip ownership, acceptance callbacks, storage transactions, comparison endpoints, plugin ID and comment schema are unchanged. There is no comment-data migration for 0.2.0.
+- Layout/wrapping preferences use a separate browser-local key, `pi-web-code-review:preferences:v1`. Corrupt or unavailable preferences fall back safely. Write failures report that the choice applies to the current panel only; they do not block comment storage.
+- UI controls are implemented by this plugin. Shared styles do not supply event handling, selection or ARIA semantics. Native modal dialogs supply modal background exclusion and Escape handling.
 
-## Integration findings
-
-No production API migration was required for this release:
-
-- Composer chips shipped in **1.202610.2**. `PluginPromptChip`, optional `setChip`/`removeChip`, silent programmatic withdrawal, and `onRemove("user" | "submitted")` match the plugin's implementation. Submission means server acceptance, not agent completion; failed sends retain chips.
-- Browser API **v4** and server API **v3** are unchanged. Workspace file helpers, invalidation, package peers, and bounded `execFile` with `unsetEnv` and operation signals remain supported.
-- Removed panel aliases do not affect this plugin: it declares no `routeAliases`/`navigationAliases` and opens its panel with the runtime-qualified contribution ID.
-- Full, case-sensitive session IDs are now required. The plugin already uses the full `selectedSession.id`; it does not generate abbreviated session links.
-- New selection subscriptions, application panels, metadata, and message actions are optional additions, not required adaptations for the existing Review panel.
-- PI WEB's newer Pi SDK dependencies do not require a companion-extension migration here: this plugin uses no Pi SDK imports or companion extension.
-- The standalone browser/server manifest follows the published example, keeping server code outside `browserRoot`. Node's declared minimum remains `>=22.19.0`.
-
-The supported dependency range is `>=1.202610.3`; the lockfile records a concrete resolved version. Compatibility was checked against `1.202610.3`, not every later version. One test access was made null-safe because panel `state` is optional in the public contract. No production API migration was needed. The subsequent `0.1.1` patch adds the Review icon, lint cleanup, and branch/commit comparisons described in the [changelog](../CHANGELOG.md). Revision comparison uses only the existing scoped package-peer API and read-only Git runner; no additional host API is required.
-
-## Validation
-
-After `npm ci --ignore-scripts`:
+## Automated results
 
 | Check | Result |
 | --- | --- |
-| `npm run typecheck` | Passed |
-| `npm run lint` | Passed |
-| `npm test` | Passed: 6 files, 82 tests |
-| `npm run build` | Passed |
-| `npm run check:artifacts` | Passed |
-| `npm pack` and smoke check of extracted package | Passed |
-| `npm run verify` | Passed |
-| Live-host send/acceptance, remote machines, real browser storage failures | Not exercised |
+| Typecheck and typed ESLint | Passed |
+| Unit/DOM/real-Git tests | Passed: 7 files, 99 tests |
+| Browser/server build | Passed |
+| Unpacked artifact smoke | Passed |
+| Actual `npm pack` and extracted-package smoke | Passed |
+| Production-bundle Chromium acceptance | Passed |
+| Dependency audit | 0 known vulnerabilities |
+
+Browser checks exercise dark/light palettes at desktop width; 360/390/430px viewports with both layouts and wrapping on/off; absence of page-level horizontal overflow; draft retention through layout changes; preference persistence (DOM tests); file/notes/settings dialogs; keyboard exclusion of inert background controls; numeric range editing; mocked chip attachment without clearing the draft; stale-draft save prevention after source changes; and stylesheet-controller connection/disconnection. The browser harness consumes the built `dist/browser/index.js` artifact, not the visual prototype.
 
-The artifact harness activates the built browser/server entries with mocked host contexts and a DOM/IndexedDB harness. Passing it does not establish live host registration or end-to-end send behavior.
+The artifact harness uses mocked host contexts and DOM/IndexedDB adapters. The Chromium harness uses native browser storage and the production plugin with a sample backend and a mock stylesheet capability; it does not reproduce the running host's shared CSS bundle. Screenshots under `docs/screenshots/0.2.0/` document those limits.
 
-### Lint cleanup
+## Follow-up acceptance
 
-All 38 original lint findings are resolved. Async disposal and callback-mutated ownership checks are preserved through live-state reads. Storage rejects with Error instances (retaining non-Error exceptions as causes), and tests use runtime-checked panel fixtures, real event/request objects, and explicit mock spies. The deliberately unbound IndexedDB method has a local lint exemption because its receiver is explicitly supplied with `.call`.
+- Live-host registration and shared stylesheet/theme adoption, including theme changes and narrow desktop panels.
+- Real iOS/Android keyboards, viewport changes, touch selection and assistive technology.
+- Successful/failed/chips-only sends, steer/follow-up, in-flight replacement, two-tab acknowledgements, real storage failures and remote-machine scoping. The automated ownership/storage regressions pass, but do not establish live end-to-end acceptance.
 
-## Remaining release work
+See the [composer checklist](composer-design.md#release-gate). These live checks remain follow-up work under the existing publication policy. No live plugin installation, daemon restart or host modification was performed to produce this release.
 
-1. Automated verification and packed smoke checks pass after lint cleanup; storage/ownership guards remain in place.
-2. Validate comparison controls and saved comparison comments on a live host, including moving branches and upgrading all older tabs. Complete the separate live-host checklist in [the release gate](composer-design.md#release-gate), especially successful/failed/chips-only sends, steer/follow-up, replacement during Send, selection changes, two-tab acknowledgements, and remote scoping. The newest host also adds pending-message controls; confirm locally queued messages do not clear saved feedback before server admission.
-3. The declared host range is `>=1.202610.3`. Only `1.202610.3` was checked here; later versions are allowed but have not been independently verified.
-4. Publication is enabled for the `0.1.1` patch release as `@compn3rd/pi-web-code-review`. The remaining validation is follow-up work; discovered defects will be addressed in patch releases.
+## Earlier releases
 
-Automated verification did not install the plugin into a live PI WEB instance or restart a daemon. Live-host testing remains separate from package publication.
+Versions 0.1.1 and 0.1.2 were checked against PI WEB `1.202610.3`, browser API v4 and server API v3. The 0.1.2 inline-editor redesign passed 84 tests. Historical [before](screenshots/review-before.png) and [after](screenshots/review-after.png) captures are standalone previews, not live-host screenshots.

package/docs/composer-design.md

@@ -4,9 +4,9 @@
 
 Target the public API on `jmfederico/pi-web` main at `830dc179`, including composer chips introduced in `02d24ec6`. The source imports `PluginPromptChip` directly from `@jmfederico/pi-web/plugin-api`; it does not recreate the missing API through a local shim or access private host code.
 
-The development dependency accepts PI WEB `>=1.202610.3`; compatibility was checked against published `1.202610.3`. Composer chips shipped in `1.202610.2`; the `1.202610.3` public declarations match this design. No speculative version, Git dependency, or local shim is used. Typechecking, all 82 tests, builds, and unpacked/packed artifact smoke checks pass. Full automated verification passes. See [compatibility results](compatibility.md).
+The development dependency accepts PI WEB `>=1.202610.6`; compatibility was checked against published `1.202610.6`. Composer chips shipped in `1.202610.2`; the `1.202610.3` public declarations match this design. No speculative version, Git dependency, or local shim is used. Typechecking, all 99 tests, builds, and unpacked/packed artifact smoke checks pass. Full automated verification passes. See [compatibility results](compatibility.md).
 
-The `0.1.1` patch release is enabled for publication. Live-host checks remain follow-up work rather than publication gates. Live-host runtime testing and installation are still deferred; the checks above validate declarations and standalone artifacts, not end-to-end send admission in a running host.
+The `0.2.0` release is enabled for publication. Live-host checks remain follow-up work rather than publication gates. Live-host runtime testing and installation are still deferred; the checks above validate declarations and standalone artifacts, not end-to-end send admission in a running host.
 
 Reference: [upstream composer documentation](https://github.com/jmfederico/pi-web/blob/830dc179/docs/plugins.md#attach-text-context-to-a-message).
 
@@ -45,10 +45,10 @@ Acceptance means prompt admission by the server, not that the assistant complete
 
 Current progress against published PI WEB `1.202610.3`:
 
-1. Confirm its public declarations include `PluginPromptChip` and the documented `setChip`/`removeChip` lifecycle. Declare the supported minimum as `>=1.202610.3` and retain a concrete resolved version in the lockfile.
+1. Confirm its public declarations include `PluginPromptChip` and the documented `setChip`/`removeChip` lifecycle. Declare the supported minimum as `>=1.202610.6` and retain a concrete resolved version in the lockfile.
 2. Re-read the published contract and reconcile any differences from the recorded main revision. Do not assume main's design is frozen.
-3. Run `npm run verify` at the package root, followed by an actual packed-package smoke check. All 82 unit/DOM cases have passed, as have unpacked and packed artifact smoke checks. All 38 lint findings have been resolved and full `verify` now passes. The dev-only `fake-indexeddb` factory exercises the actual adapter on two connections, transaction aborts, migration precedence/empty markers, and open retry/late-success cleanup. Dependencies were installed with `--ignore-scripts`; no host installation or daemon restart was performed.
+3. Run `npm run verify` at the package root, followed by an actual packed-package smoke check. All 99 unit/DOM cases have passed, as have unpacked and packed artifact smoke checks. All 38 lint findings have been resolved and full `verify` now passes. The dev-only `fake-indexeddb` factory exercises the actual adapter on two connections, transaction aborts, migration precedence/empty markers, and open retry/late-success cleanup. Dependencies were installed with `--ignore-scripts`; no host installation or daemon restart was performed.
 4. In a separate test installation, exercise successful and failed sends, chips-only messages, steer/follow-up, selection changes, repeat attachment during an in-flight send, local edits/deletes, simultaneous two-tab saves/acknowledgements, failed/blocked/corrupt migration, retained legacy backups, persistent storage/acknowledgement warnings across remounts, async navigation/disposal, LAN HTTP without Web Locks, BroadcastChannel failure, Git with `diff.submodule=diff`, reload/restaging, disabled-plugin cleanup, and remote-machine scoping. Confirm the server-accepted callback clears only the correct saved feedback. Do not restart the developer's active session daemon as part of this check.
-5. Publication is enabled for version `0.1.1` as `@compn3rd/pi-web-code-review`, with PI WEB `>=1.202610.3` supported. Keep outstanding validation documented and address discovered defects in patch releases.
+5. Publication is enabled for version `0.2.0` as `@compn3rd/pi-web-code-review`, with PI WEB `>=1.202610.6` supported. Keep outstanding validation documented and address discovered defects in patch releases.
 
 There is no scheduled release watcher or automatic installation/restart associated with this gate.

package/docs/development.md

@@ -6,9 +6,9 @@ This repository starts from the plugin snapshot in [CompN3rd/pi-web at `d0c7a212
 
 ## Verification status
 
-The development dependency accepts PI WEB `>=1.202610.3`, which includes the public composer-chip API. The lockfile records the concrete version used for reproducible development. There are no local replacement declarations. Typechecking, all 82 tests, the build, and unpacked/packed artifact smoke checks pass. Full `verify` passes; live-host testing is still pending. See [compatibility results](compatibility.md).
+The development dependency targets PI WEB `^1.202610.6`, with a concrete lockfile resolution. The browser entry uses API v5 and public stylesheet-integration v1; the unchanged server entry uses supported API v3. There are no local replacement declarations. Typechecking, all 99 tests, the build, and unpacked/packed artifact smoke checks pass. Full `verify` and standalone production-browser checks pass; live-host testing is still pending. See [compatibility results](compatibility.md).
 
-The `0.1.1` patch release is enabled for publication with live-host testing tracked as follow-up work in the [validation checklist](composer-design.md#release-gate). Reproduce validation with:
+The `0.2.0` release is enabled for publication with live-host testing tracked as follow-up work in the [validation checklist](composer-design.md#release-gate). Reproduce validation with:
 
 ```sh
 npm ci --ignore-scripts
@@ -20,6 +20,17 @@ npm pack --dry-run
 
 Prepared cases cover actual adapter serialization on two IndexedDB connections, aborted-write durability, one-time migration and empty migration markers, legacy-backup retention, corrupt/failed migration, failed-open retry and late blocked-open cleanup, captured chip ownership, stale async reads, disposal, user removal versus server acceptance, replacement during Send, unchanged-snapshot deletion, cross-tab withdrawal/badge refresh, persistent storage/acknowledgement warnings across remounts, and Git's `--submodule=short` override. `fake-indexeddb` is dev-only and injected through the native `IDBFactory` boundary; DOM tests retain the per-file happy-dom harness. These tests and the existing source-coordinate, Markdown, Git, and storage cases have passed against the released declarations. Mock/DOM coverage does not replace live-host acceptance testing.
 
+## Production browser checks
+
+Install Playwright in a separate tools directory (or supply an existing installation), ensure its Chromium browser is available, then run:
+
+```sh
+npm run build
+npm run check:browser -- /absolute/path/to/playwright/index.mjs
+```
+
+This starts a temporary localhost Vite server, loads the built plugin with native browser storage and sample host/backend adapters, checks the responsive interactions, captures `docs/screenshots/0.2.0/`, then closes browser and server. It never starts PI WEB or restarts its daemon. The host stylesheet capability is mocked; test shared CSS and real mobile keyboards separately. The earlier `docs/redesign/` study is historical and excluded from npm; the production harness under `scripts/browser/` is the acceptance source.
+
 ## Boundaries
 
 - The frontend stores workspace-scoped comments and delegates staging/acknowledgement to `ReviewChips`. Only public `prompt.setChip`/`prompt.removeChip` methods are used for handoff; prompt insertion and the provisional selection-service shim have been removed.
@@ -27,4 +38,4 @@ Prepared cases cover actual adapter serialization on two IndexedDB connections,
 - The Markdown renderer is adapted from PI WEB's MIT-licensed Captain's Log example. It renders known lexer tokens through Lit text bindings, not unsafe HTML.
 - Browser dependencies are bundled under `dist/browser`; server JavaScript remains outside that public directory. The whole plugin can be built separately from the host after the dependency gate is satisfied.
 
-Version `0.1.1` is packaged for public npm distribution as `@compn3rd/pi-web-code-review`. Release publication is separate from host installation and activation. Do not publish the PI WEB host to ship this plugin.
+Version `0.2.0` is packaged for public npm distribution as `@compn3rd/pi-web-code-review`. Release publication is separate from host installation and activation. Do not publish the PI WEB host to ship this plugin.

package/docs/usage.md

@@ -1,6 +1,6 @@
 # Code Review workflow
 
-Version **0.1.1** requires **PI WEB >=1.202610.3**. Automated tests, builds, and artifact smoke checks passed against `1.202610.3`; live-host testing remains outstanding. See [compatibility results](compatibility.md) for the validation limits.
+Version **0.2.0** requires **PI WEB >=1.202610.6**. Automated tests, builds, artifact smoke checks and production-bundle Chromium checks passed against `1.202610.6`; live-host testing remains outstanding. See [compatibility results](compatibility.md) for the validation limits.
 
 ## Install the standalone package
 
@@ -39,8 +39,8 @@ For remote workspaces, install and enable the package on each target machine. Gi
 ## Review files and changes
 
 1. Select a workspace and open the **Review** tab (or **Open Code Review** in the action palette).
-2. Choose **Files**, **Git unstaged**, **Git staged**, or **Compare revisions**. Files includes untracked files. Browse directories or enter a workspace-relative file path. For committed work across multiple commits, use the comparison controls below.
-3. Click a line number. Shift-click extends its range on the same side; on touch screens, edit **Start line** and **End line** instead. Deleted diff lines use old-side coordinates; context and additions use new-side coordinates. Ranges cannot span omitted diff context.
+2. Choose **Files**, **Unstaged**, **Staged**, or **Compare**. Files includes untracked files. Browse directories or expand **Open a file by path** to enter a workspace-relative file path. For committed work across multiple commits, use the comparison controls below.
+3. Click a line number to open and focus the comment editor directly below it inside the viewer. Shift-click extends its range on the same side; on touch screens, expand **Line range** and edit **Start line** and **End line** instead. Deleted diff lines use old-side coordinates; context and additions use new-side coordinates. Ranges cannot span omitted diff context.
 4. Enter Markdown and choose **Save comment**. Ctrl/Cmd+Enter also saves; ordinary Enter inserts a newline.
 5. Review the saved list. **Edit comment** reloads its source before allowing a save; **Remove comment** deletes that comment.
 
@@ -48,9 +48,19 @@ Comments render safe Markdown: raw HTML is displayed as text, images do not load
 
 Saved comments are local to this browser origin, keyed by machine, project, and workspace. They survive reloads and session changes; they are not synchronized across browsers or machines. IndexedDB transactions serialize concurrent saves and acknowledgements across tabs, so independent comments are not lost through competing read/modify/write operations. IndexedDB does not require HTTPS or Web Locks; LAN HTTP remains supported where the browser permits origin storage. Storage errors are shown and an unsuccessful save leaves the editor text available. Corrupt or unrecognized storage is not overwritten automatically. Feedback warnings remain separate from source-loading errors, survive panel/workspace remounts within the activation, and stay visible until explicitly dismissed.
 
+### Layout and phone controls
+
+Choose **Review settings** in the panel header. **Workbench** shows files, code and saved notes in columns on wide panels (notes move below at intermediate widths). **Focus** hides the persistent file list, keeps feedback inline and collapses the saved-review summary. Switching layouts preserves the current file, range, draft and code-view DOM; normal responsive reflow can adjust scroll geometry.
+
+On panels at most 640px wide, use **Files** (Workbench) or the current filename (Focus) to open a file sheet. **Notes** opens all saved feedback. Choose a file to close the sheet; opening a directory keeps it open for browsing. Close sheets with the close button or Escape. Desktop previous/next controls navigate the current file list.
+
+**Wrap code** is enabled by default. Turning it off scrolls long source lines inside the code viewer; comments and the draft remain constrained to the viewer width. Wrapping does not change original line coordinates. Layout and wrapping choices are stored per browser origin, shared across workspaces on subsequent panel creation; existing tabs do not live-sync these preferences. A failed settings write is reported without affecting saved comments.
+
+Settings are in the Review panel, not the host-wide settings screen. Unsaved drafts still need to be saved before reloading or switching workspaces. Neither applying settings nor attaching a review sends a message.
+
 ### Review accumulated branch or commit changes
 
-Select **Compare revisions**, enter **Base revision** and **Target revision**, then choose a comparison mode and click **Compare**:
+Select **Compare**, enter **Base revision** and **Target revision**, then choose a comparison mode and click **Compare**:
 
 | Goal | Base | Target | Mode |
 | --- | --- | --- | --- |
@@ -79,7 +89,7 @@ Refreshing or host file invalidation reloads the current snapshot (in comparison
 
 ## Attach feedback to the composer
 
-Choose a ready, unarchived conversation in this workspace, then select **Attach review to composer**. One removable **Review (N)** chip contains a snapshot of all saved comments. Repeating the action replaces that conversation's review chip, not the text at its cursor. You can inspect the payload under **Feedback Markdown**.
+Choose a ready, unarchived conversation in this workspace, then select **Attach review to composer** in the panel header. The header shows saved-comment and unsaved-draft counts; save your draft first if you want it included. One removable **Review (N)** chip contains a snapshot of all saved comments. Repeating the action replaces that conversation's review chip, not the text at its cursor. You can inspect the payload under **Feedback Markdown**.
 
 Send the chip with a message or by itself. Failed sends keep it and the saved comments for retry. Server acceptance clears only unchanged comments from the submitted snapshot; later edits and new comments survive. Acceptance does not mean the assistant has finished answering. Removing the composer chip only detaches it—saved comments remain available.
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@compn3rd/pi-web-code-review",
-  "version": "0.1.1",
+  "version": "0.2.0",
   "publishConfig": {
     "access": "public"
   },
@@ -15,7 +15,8 @@
     "dist",
     "README.md",
     "CHANGELOG.md",
-    "docs",
+    "docs/*.md",
+    "docs/screenshots",
     "LICENSE"
   ],
   "scripts": {
@@ -24,12 +25,13 @@
     "lint": "eslint src test",
     "build": "npm run typecheck && vite build && tsc -p tsconfig.server.json",
     "check:artifacts": "node scripts/check-artifacts.mjs",
+    "check:browser": "node scripts/check-browser.mjs",
     "verify": "npm run typecheck && npm run lint && npm test && npm run build && npm run check:artifacts",
     "prepack": "npm run build"
   },
   "devDependencies": {
     "@eslint/js": "^10.0.1",
-    "@jmfederico/pi-web": ">=1.202610.3",
+    "@jmfederico/pi-web": "^1.202610.6",
     "@noble/hashes": "^2.4.0",
     "@types/node": "^24.13.3",
     "eslint": "^10.6.0",
@@ -40,8 +42,8 @@
     "marked": "^18.0.6",
     "typescript": "^6.0.3",
     "typescript-eslint": "^8.63.0",
-    "vite": "^8.1.4",
-    "vitest": "^4.1.10"
+    "vite": "^8.3.5",
+    "vitest": "^4.1.12"
   },
   "engines": {
     "node": ">=22.19.0"