@compn3rd/pi-web-code-review 0.0.0-stage → 0.1.2

package/dist/protocol.js

@@ -0,0 +1,46 @@
+export function isRevision(value) {
+    return typeof value === "string" && /^[a-z0-9_][a-z0-9_./~^@{}-]{0,255}$/iu.test(value) && !value.includes("..");
+}
+export function isCommitId(value) {
+    return typeof value === "string" && /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/u.test(value);
+}
+export function isComparison(value) {
+    return record(value) && isRevision(value["baseRef"]) && isRevision(value["headRef"])
+        && (value["mode"] === "merge-base" || value["mode"] === "direct")
+        && isCommitId(value["base"]) && isCommitId(value["head"]);
+}
+export function parseComparison(value) {
+    if (!isComparison(value))
+        throw new Error("Invalid Git comparison");
+    return value;
+}
+export function comparisonKey(comparison) {
+    return comparison === undefined ? "" : JSON.stringify([comparison.baseRef, comparison.headRef, comparison.mode, comparison.base, comparison.head]);
+}
+export const MAX_TEXT_LENGTH = 200_000;
+export const MAX_FILES = 2_000;
+export function isGitSource(value) {
+    return value === "git-staged" || value === "git-unstaged" || value === "git-compare";
+}
+/** Relative, unambiguous paths. Git callers must also disable pathspec magic with --literal-pathspecs. */
+export function isWorkspacePath(value) {
+    return typeof value === "string" && value.length > 0 && value.length <= 4096
+        && !/^[a-z]:/iu.test(value) && !value.startsWith("/") && !value.includes("\\")
+        // eslint-disable-next-line no-control-regex -- Never pass controls to Git or persist ambiguous labels.
+        && !/[\u0000-\u001f\u007f]/u.test(value)
+        && value.split("/").every((part) => part !== "" && part !== "." && part !== "..");
+}
+export function record(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+export function parsePaths(value) {
+    if (!Array.isArray(value) || value.length > MAX_FILES || !value.every(isWorkspacePath)) {
+        throw new Error("Invalid or oversized Git file list");
+    }
+    return value;
+}
+export function parseDiff(value) {
+    if (typeof value !== "string" || value.length > MAX_TEXT_LENGTH)
+        throw new Error("Invalid or oversized Git diff");
+    return value;
+}

package/dist/server.js

@@ -0,0 +1,75 @@
+import { isCommitId, isGitSource, isRevision, isWorkspacePath, MAX_FILES, MAX_TEXT_LENGTH, parseComparison, record } from "./protocol.js";
+// Do not inherit the repository/index of the process hosting the daemon.
+const gitEnvironment = [
+    "GIT_ALTERNATE_OBJECT_DIRECTORIES", "GIT_COMMON_DIR", "GIT_DIR", "GIT_INDEX_FILE",
+    "GIT_OBJECT_DIRECTORY", "GIT_PREFIX", "GIT_QUARANTINE_PATH", "GIT_WORK_TREE",
+];
+export async function requestGit(execFile, request) {
+    const { input, operation, workspace, signal } = request;
+    if (!record(input) || !isGitSource(input["source"]))
+        throw new Error("Invalid Git review source");
+    if (operation !== "changes" && operation !== "diff" && operation !== "compare")
+        throw new Error("Unknown review operation");
+    const run = async (args) => {
+        const result = await execFile({ file: "git", args: ["--literal-pathspecs", "-C", workspace.path, ...args], cwd: workspace.path, env: { GIT_OPTIONAL_LOCKS: "0" }, unsetEnv: gitEnvironment, signal, timeoutMs: 10_000 });
+        if (result.exitCode !== 0 || result.signal !== null)
+            throw new Error(`Git review failed: ${result.stderr.trim() || `exit ${String(result.exitCode)}`}`);
+        if (result.stdoutTruncated || result.stderrTruncated)
+            throw new Error("Git output exceeds the host limit; narrow the review");
+        return result.stdout;
+    };
+    if (operation === "compare") {
+        if (input["source"] !== "git-compare" || !isRevision(input["baseRef"]) || !isRevision(input["headRef"])
+            || (input["mode"] !== "merge-base" && input["mode"] !== "direct"))
+            throw new Error("Invalid comparison revisions or mode");
+        const baseRef = input["baseRef"];
+        const headRef = input["headRef"];
+        const mode = input["mode"];
+        const resolve = async (ref) => {
+            const commit = (await run(["rev-parse", "--verify", "--end-of-options", `${ref}^{commit}`])).trim();
+            if (!isCommitId(commit))
+                throw new Error("Git returned an invalid commit ID");
+            return commit;
+        };
+        const baseTip = await resolve(baseRef);
+        const head = await resolve(headRef);
+        const base = mode === "direct" ? baseTip : (await run(["merge-base", baseTip, head])).trim();
+        if (!isCommitId(base))
+            throw new Error("Git returned an invalid merge base");
+        return { baseRef, headRef, mode, base, head };
+    }
+    const comparison = input["source"] === "git-compare" ? parseComparison(input["comparison"]) : undefined;
+    const path = input["path"];
+    if (operation === "diff" && !isWorkspacePath(path))
+        throw new Error("Invalid workspace-relative review path");
+    const args = ["diff", "--no-ext-diff", "--no-textconv", "--no-renames", "--no-color", "--submodule=short", "--relative"];
+    if (input["source"] === "git-staged")
+        args.push("--cached");
+    if (operation === "changes")
+        args.push("--name-only", "-z");
+    else
+        args.push("--unified=3");
+    if (comparison !== undefined)
+        args.push(comparison.base, comparison.head);
+    args.push("--");
+    if (operation === "diff" && typeof path === "string")
+        args.push(path);
+    const output = await run(args);
+    if (operation === "changes") {
+        const paths = output.split("\0").filter((entry) => entry !== "");
+        if (paths.length > MAX_FILES)
+            throw new Error("Too many changed files; narrow the review");
+        if (!paths.every(isWorkspacePath))
+            throw new Error("Git returned a filename this review plugin cannot safely address");
+        return paths;
+    }
+    if (output.length > MAX_TEXT_LENGTH)
+        throw new Error("Diff is too large to review inline");
+    return output;
+}
+const plugin = {
+    apiVersion: 3,
+    name: "Code Review",
+    activate: ({ execFile }) => ({ peer: { request: (request) => requestGit(execFile, request) } }),
+};
+export default plugin;

package/docs/compatibility.md

@@ -0,0 +1,59 @@
+# Latest-release compatibility check
+
+## Target
+
+Checked npm's latest published `@jmfederico/pi-web`: **1.202610.3**, source revision `29f0ace6d955a458a947bb0f03673fa069afb8da`.
+
+References:
+
+- [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`.
+
+## 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.
+
+## UI patch 0.1.2
+
+The redesigned panel uses the same host APIs, storage format, and server operations as 0.1.1. Standalone Edge screenshots show the old and new components with identical sample content ([before](screenshots/review-before.png), [after](screenshots/review-after.png)). Browser rendering was checked separately from the DOM tests; this does not establish live-host behavior or narrow-panel acceptance.
+
+## Validation
+
+After `npm ci --ignore-scripts`:
+
+| Check | Result |
+| --- | --- |
+| `npm run typecheck` | Passed |
+| `npm run lint` | Passed |
+| `npm test` | Passed: 6 files, 84 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 |
+
+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.
+
+### Lint cleanup
+
+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`.
+
+## Remaining release work
+
+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.2` patch release as `@compn3rd/pi-web-code-review`. The remaining validation is follow-up work; discovered defects will be addressed in patch 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.

package/docs/composer-design.md

@@ -0,0 +1,54 @@
+# Composer-chip design and release gate
+
+## Target and status
+
+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 84 tests, builds, and unpacked/packed artifact smoke checks pass. Full automated verification passes. See [compatibility results](compatibility.md).
+
+The `0.1.2` 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.
+
+Reference: [upstream composer documentation](https://github.com/jmfederico/pi-web/blob/830dc179/docs/plugins.md#attach-text-context-to-a-message).
+
+## Ownership
+
+- **ReviewStore** owns durable comments in browser IndexedDB transactions (with one-time, backup-retaining localStorage migration), keyed by machine/project/workspace. A comment is not deleted merely because it was attached to a conversation.
+- **ReviewChips** owns staging and callback bookkeeping for the plugin activation, independent of whether the Review panel is mounted. It retains the exact conversation-bound prompt facade used for each attachment, never a live-selection redirect.
+- **PI WEB** owns composer chips, send admission, failed-send retention, and callbacks. Staging happens only from the user's **Attach review to composer** action, never from render.
+- **ReviewPanel** owns file loading and unsaved edits. It delegates composer lifecycle decisions instead of reaching into the host DOM or sending messages itself.
+
+## One snapshot per workspace/conversation
+
+Attach creates one labeled `Review (N)` chip containing the sorted Markdown for all saved comments in the workspace. The plugin-local chip id is stable for that workspace; the host additionally scopes it by plugin, machine, and conversation. Reattaching replaces the same chip rather than adding duplicates. Individual comments remain editable/removable in the Review panel.
+
+A ready, unarchived conversation in the panel's workspace is required. The facade is already bound to that conversation: no navigation, selection-service shim, cursor manipulation, or clipboard fallback is needed. Hosts without `setChip`/`removeChip` produce an explicit unsupported-host error rather than reverting to the interim insertion implementation.
+
+## Lifecycle
+
+| Event | Intended behavior |
+| --- | --- |
+| Attach | Read current saved comments; stage a detached snapshot; retain durable data. |
+| Panel closes or selection changes | Host retains the chip in its original conversation; the activation retains its callback. |
+| User removes the composer chip | Detach only; keep saved comments for editing or reattachment. |
+| Send fails or is queued only locally | No submitted callback; chip and saved comments remain available. |
+| Server accepts the prompt | `onRemove("submitted")` clears only comments whose stored fields still equal the submitted snapshot. Later edits and new comments survive. |
+| A chip is replaced while Send is in flight | An older callback must not retire the replacement or clear the saved feedback for that newer attachment. |
+| Save or remove a comment in the Review panel | Withdraw this workspace's staged copies before mutation. Attach the updated review explicitly. If withdrawal fails, block the mutation and show the error. |
+| Another tab changes saved review data | Withdraw this activation's copies, even while the panel is closed, and ask for reattachment. A request already in flight may still be accepted; its callback compares against current storage. |
+| Clearing submitted data fails | Preserve saved data, report the problem in the panel, and throw for the host's attributed callback logging. The user checks the conversation before reattaching. |
+| Browser reload | Host chips are gone; saved comments remain. Open the target conversation and attach again with a fresh facade/callback. |
+| Plugin disposal | Close the notification channel/database and attempt silent chip withdrawal; suppress obsolete asynchronous UI work. Already-started durable writes may complete. |
+
+Acceptance means prompt admission by the server, not that the assistant completed its response. There is no automatic resend or inference from the disappearance of prompt text. A submitted callback always uses its captured workspace and snapshot, even after navigation. Attachments in different conversations are independent snapshots; intentionally attaching to multiple conversations can send the feedback more than once.
+
+## Release gate
+
+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.
+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.
+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.2` as `@compn3rd/pi-web-code-review`, with PI WEB `>=1.202610.3` 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

@@ -0,0 +1,30 @@
+# Developing the standalone plugin
+
+All package source, tests, and configuration live at this repository's root. The package is independent of PI WEB's bundled plugins, test command, and npm release; no PI WEB source checkout is required.
+
+This repository starts from the plugin snapshot in [CompN3rd/pi-web at `d0c7a212`](https://github.com/CompN3rd/pi-web/tree/d0c7a212/plugins/code-review). Earlier development history remains there; PI WEB host code is not included here.
+
+## 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 84 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 `0.1.2` 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:
+
+```sh
+npm ci --ignore-scripts
+npm run verify
+npm pack --dry-run
+```
+
+`verify` runs strict typechecking, typed ESLint, Vitest, the standalone build, and browser/server artifact smoke checks. `npm run check:artifacts` consumes already-built output without rebuilding; `node scripts/check-artifacts.mjs /path/to/extracted/package` checks a packed copy using this checkout's DOM harness.
+
+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.
+
+## 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.
+- The backend accepts only read-only `compare`, `changes`, and `diff` operations, runs argv-based Git through the host's bounded executor with the request signal, and uses the host-resolved workspace. Literal pathspecs, disabled external diff/textconv drivers, forced short submodule diffs, and output/path bounds keep this surface narrow.
+- 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.2` 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

@@ -0,0 +1,96 @@
+# Code Review workflow
+
+Version **0.1.2** 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.
+
+## Install the standalone package
+
+Install `npm:@compn3rd/pi-web-code-review` through **Settings → Pi packages** on the target machine. If migrating from the unscoped package, disable/remove that plugin first; do not enable both copies. The plugin ID and storage keys are unchanged. Enable the scoped plugin and restart safely as described below. To build and install locally:
+
+Build from this repository's root:
+
+```sh
+npm ci --ignore-scripts
+npm run build
+```
+
+`--ignore-scripts` avoids native installation scripts from the development-only PI WEB dependency. This plugin's build does not use those native modules. The browser's Lit and Markdown dependencies are bundled; the server entry uses only the host-provided Git runner. Installed users need the built package, not its development dependencies.
+
+Link this directory into the target machine's plugin directory. On Linux/macOS, while still at the repository root:
+
+```sh
+mkdir -p "${PI_WEB_DATA_DIR:-$HOME/.pi-web}/plugins"
+ln -s "$PWD" "${PI_WEB_DATA_DIR:-$HOME/.pi-web}/plugins/code-review"
+```
+
+On Windows, run PowerShell from the built plugin directory:
+
+```powershell
+$data = if ($env:PI_WEB_DATA_DIR) { $env:PI_WEB_DATA_DIR } else { Join-Path $env:USERPROFILE '.pi-web' }
+New-Item -ItemType Directory -Force (Join-Path $data 'plugins')
+New-Item -ItemType Junction -Path (Join-Path $data 'plugins/code-review') -Target (Get-Location).Path
+```
+
+Alternatively, copy the package's `package.json`, `dist`, `LICENSE`, `README.md`, and `docs` into that directory. For distribution, `npm pack` creates a self-contained tarball; extract it as the plugin directory, retaining `package.json` at its root. Do not copy `node_modules`.
+
+Enable **Code Review** in **Settings → PI WEB plugins**. Because the package includes a server entry, **manually restart the target session daemon when safe**, then reload the browser. Restarting interrupts active sessions and terminals; do it from outside the sessions that daemon hosts. The plugin does not restart anything itself. Browser reload or Pi's `/reload` alone is insufficient after installing or updating this paired package.
+
+For remote workspaces, install and enable the package on each target machine. Git runs on the panel's machine, never on the gateway as a fallback. Files and package-peer requests use the host's scoped helpers, including nested deployments.
+
+## 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 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, 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.
+
+Comments render safe Markdown: raw HTML is displayed as text, images do not load, and links are limited to HTTP/HTTPS. Binary, truncated, very large sources (over 200,000 characters or 5,000 lines), and directories/change lists with over 2,000 entries are rejected rather than displaying incomplete selectable coordinates. Git must be installed. Git views show tracked changes; inspect untracked files in Files. Submodules are shown as Git's gitlink diff, not recursively expanded into another repository's file changes.
+
+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.
+
+### Review accumulated branch or commit changes
+
+Select **Compare revisions**, enter **Base revision** and **Target revision**, then choose a comparison mode and click **Compare**:
+
+| Goal | Base | Target | Mode |
+| --- | --- | --- | --- |
+| Current branch's work since diverging from main | `main` (or `origin/main`) | `HEAD` | Branch changes since merge base (`A...B`) |
+| Another branch's accumulated work | `main` | `feature/my-branch` | Branch changes since merge base (`A...B`) |
+| Last three commits together | `HEAD~3` | `HEAD` | Between revisions (`A..B`) |
+| Changes since a particular commit or tag | Commit ID or tag | `HEAD` | Between revisions (`A..B`) |
+
+Merge-base mode compares the common ancestor of base and target with the target, excluding changes made only on main after divergence. Between-revisions mode compares the two commit trees directly. A `main` branch is not assumed to exist: enter `master`, a remote-tracking branch, or another available revision as needed. Refs must exist locally; this feature does not fetch, checkout, stage, or modify Git data. Revisions are single branch/tag/commit expressions (including `HEAD~3` or `HEAD^`), not combined `A..B` strings, paths, or Git options.
+
+Only **committed** changes appear. Dirty index/worktree and untracked changes remain available in the other source modes. Click a changed file to review its complete accumulated diff, then comment as usual.
+
+The list and all opened files use the same resolved commit IDs, even if a branch moves meanwhile. **Compare** or **Refresh** resolves the inputs again and resets the file selection; choose a file in the new list. Saved comments retain the original endpoints, comparison mode, and snapshot hash. **Edit comment** reopens those frozen endpoints, not today's branch tips. A different comparison never silently re-anchors an existing comment, even if its text diff is identical. Feedback Markdown includes the revision labels and abbreviated commit IDs.
+
+### Storage upgrade and recovery
+
+Reload **all old plugin tabs before using the upgraded plugin**. Comparison comments introduce a new source type; older plugin versions cannot read a workspace record containing them and report unrecognized storage without overwriting it. Upgrade all tabs before saving comparison comments; copy/export feedback before downgrading. On first access to each workspace, the plugin imports its previous `pi-web-code-review:v1:` localStorage record into IndexedDB in one transaction. The record itself marks migration complete, including when its comment list is empty after removal or acknowledgement. Existing IndexedDB data always wins. Legacy localStorage is retained unchanged as a backup, not an active store after migration. Old plugin tabs still write only localStorage; their later edits cannot safely be merged automatically and will not appear in the upgraded plugin. Copy any such feedback before reloading those tabs.
+
+If migration is corrupt, blocked, or fails, the panel reports it and retains the original data for recovery; it does not substitute an empty successful save. Close older tabs if an upgrade is blocked, then reopen Review to retry. Browser storage clearing deletes active comments and may also delete the backup; clearing only IndexedDB can reimport the retained legacy snapshot. Export/copy needed feedback before clearing storage.
+
+Cross-tab chip withdrawal and live badges use BroadcastChannel notifications after durable commits. A notification failure cannot undo a saved comment. If the browser blocks BroadcastChannel, transaction safety remains, but other tabs may display stale feedback/chips until refreshed; reattach a fresh snapshot before sending.
+
+Switching away from the tab preserves the current editor within this activation. Switching workspace, reloading the browser, or disabling the plugin discards **unsaved** edits. Save before doing so.
+
+Refreshing or host file invalidation reloads the current snapshot (in comparison mode, it re-resolves the revision inputs and resets the file selection). A changed file does not silently delete feedback: saved comments remain in the list, are flagged as stale when that source is viewed, and are not attached to its new lines. Copy any unfinished text before cancelling a stale edit. Create a new comment against the current snapshot instead of automatically moving an old anchor. Sources you have not reopened have not been checked for staleness; verify coordinates before handing off.
+
+## Attach feedback to the composer
+
+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.
+
+Saving edits or removing comments withdraws this workspace's staged feedback; attach again when ready. Changes from another browser tab also withdraw this activation's copies. If withdrawal fails, remove the stale chip manually before sending. If clearing submitted comments fails, inspect the accepted conversation before reattaching to avoid duplicate feedback. This acceptance warning remains visible alongside later action or storage errors until you explicitly dismiss it, including after switching workspaces or reopening Review within the same activation.
+
+Chips survive closing the panel or navigating away, but not reloading the page. Saved comments survive reloads; open the intended conversation and attach again. Different conversations can hold independent snapshots, so attach to multiple conversations only if you intend to send the feedback more than once.
+
+## Differences from the former core UI
+
+This is an independent Review tab, not an extension of the bundled Files/Git tabs: main does not expose inline decoration hooks for those panels. Composer integration uses main's public chip API, including removal and server-accepted callbacks. There are no private DOM hooks, private HTTP routes, host-owned review services, or patches to PromptEditor.
+
+Feedback is workspace-scoped rather than session-scoped, so it can be authored before choosing a session and requires no temporary-session migration hooks. The old branch's `pi-web:review-comments:` session stores are not automatically imported or deleted; copy any remaining feedback from the old UI before switching installations.
+
+Comment ownership stays in the plugin; the host owns only the staged composer snapshot and its send lifecycle.

package/package.json

@@ -1,6 +1,60 @@
-{
-  "name": "@compn3rd/pi-web-code-review",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+{
+  "name": "@compn3rd/pi-web-code-review",
+  "version": "0.1.2",
+  "publishConfig": {
+    "access": "public"
+  },
+  "description": "Workspace file and Git review comments for PI WEB, without host modifications.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/CompN3rd/pi-web-code-review.git"
+  },
+  "type": "module",
+  "license": "MIT",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "docs",
+    "LICENSE"
+  ],
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint src test",
+    "build": "npm run typecheck && vite build && tsc -p tsconfig.server.json",
+    "check:artifacts": "node scripts/check-artifacts.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",
+    "@noble/hashes": "^2.4.0",
+    "@types/node": "^24.13.3",
+    "eslint": "^10.6.0",
+    "fake-indexeddb": "^6.2.4",
+    "globals": "^17.7.0",
+    "happy-dom": "^20.11.1",
+    "lit": "^3.3.3",
+    "marked": "^18.0.6",
+    "typescript": "^6.0.3",
+    "typescript-eslint": "^8.63.0",
+    "vite": "^8.1.4",
+    "vitest": "^4.1.10"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "piWeb": {
+    "plugins": [
+      {
+        "id": "code-review",
+        "browserRoot": "dist/browser",
+        "module": "dist/browser/index.js",
+        "serverModule": "dist/server.js",
+        "machineSpecific": true
+      }
+    ]
+  }
+}