lablup / lablup/backend.ai-webui
[pr-devserver-review] Walkthrough 2/4 — review overlay guided mode: marks, navigator, popover, keys, comment export
- Dominant language
- TypeScript
- Stars
- 133
- Forks
- 81
- Avg merge
- 1d 11h
- Merged PRs (30d)
- 344
Description
## Parent
FR-3313. Design: wayfinder map FR-3941, decision FR-3944 (guided mode = the docs PR preview's grammar, ported as design). Prototype to match: branch `proto/FR-3944-guided-mode`, `react/vite-plugins/review-overlay/proto-FR-3944/walkthrough-guided-mode.html`, variant D (live: https://claude.ai/code/artifact/b3d6ebdb-4d5b-425f-a200-f4e80677744f). Builds on FR-A (stop fields, strict resolution, re-arm).
## What to build
When a `#bai=v3` link whose parts are all **stops** is opened, the overlay enters **guided mode** instead of merging into the draft set:
- **Separate read-only set**: the walkthrough set lives beside the reviewer's draft set (own `sessionStorage` key), never merges into it, never leaves through `copy all`; the dock shows the reviewer's own pins as before.
- **Marks, not pins**: each located stop's element gets `data-bai-change` + `data-bai-type` styling — tinted (`added` green / `modified` amber), 1.5 px dashed orange outline at 5 px offset, an orange ordinal badge top-left, `✓ viewed` / `✎ comment` badges top-right, dotted grey once viewed; `role=button` + aria-label. Colours/tokens as in `packages/backend.ai-docs-toolkit/templates/assets/pr-preview.css` (`--bai-add`, `--bai-mod`, `--bai-accent #ff7a00`, `--bai-focus #2563eb`, `--bai-viewed-badge #6b7280`), inside the overlay's Shadow root.
- **Navigator pill** fixed bottom-right: `N pages · M changes │ i / M · k viewed │ ✎ Copy N comments │ ‹ › ☰`; `‹ ›` step in set order and cross pages by SPA navigation (the route watcher re-runs resolution; `location.assign(pinSetUrlAt)` only as fallback); `☰` panel lists stops grouped by page with state badges and "Copy page summary" (`[ ]`/`[x]` checklist).
- **Popover** for the current stop: type chip · kind · `Copy ref` · **Viewed** checkbox · what changed + one-line `old → new` · what to check · code links `https://github.com/lablup/backend.ai-webui/pull//files#diff-R[-R]` (sha256 in pure JS — no `crypto.subtle` on the plain-http gateway, reuse `id.ts`) · comment textarea · footer `#i · page · id` + key hints. A waiting stop shows its `via` as a sentence ("Click “Upload”"); an away stop names the page `›` goes to.
- **Keys** by `e.code`: `n`/`]`, `p`/`[`, `v`, `m`, `c`, `Esc`.
- **Page banner** at the top of the page content: "N changes on this page · k viewed · made for ``", turning into the warning when `/__review/state` (boot record) reports a different head.
- **State** in `localStorage` keyed by `sha`: viewed + comments.
- **Comment export**: `✎ Copy N comments` emits one reviewer-pin **block** per comment in the existing block format (`block.ts`), each with the stop's one-pin `#bai=v3` link and a `re: stop k · ` line; `Copy ref` emits one. Reviewer pins made this way are ordinary `bai-review` blocks the resolver already reads.
- Unit tests for the mode switch, the navigator order across pages, viewed/comment persistence, and the export text; `DEV_ENVIRONMENT.md` gets a "Walkthrough" paragraph; `CONTEXT.md` gets **Walkthrough**, **Mark**, **Navigator**.
## Acceptance criteria
- [ ] Opening a 6-stop link (two stops behind a dialog, two on another page) shows the navigator with `2 pages · 6 changes`, marks only the located stops, and the dialog stops stay "waiting" with their `via` sentence until the dialog opens, then get marks without a reload.
- [ ] `›` from stop 4 (Data) to stop 5 (Session start) navigates without a full reload and marks stop 5 within the ladder.
- [ ] `v` persists across reload; a comment typed in the popover survives reload and `✎ Copy 1 comment` yields a block `review-pins parse --json` reads as one pin with the stop's id in a `re:` line.
- [ ] A reviewer's own draft set is untouched by opening/closing a walkthrough.
- [ ] `bash scripts/verify.sh` passes; token gate: no new findings.
JIRA Issue: FR-3950
Contributor guide
No contributing guide indexed for this repository
Research direction
Start with the guided-mode prototype at react/vite-plugins/review-overlay/proto-FR-3944/walkthrough-guided-mode.html, then inspect the existing block.ts, id.ts, and preview CSS tokens named in the issue. Add unit tests for mode switching, cross-page navigator order, persistence, and export, plus the requested DEV_ENVIRONMENT.md and CONTEXT.md sections. Done means the listed acceptance scenarios pass and bash scripts/verify.sh reports no new findings.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- documentation, frontend
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Clearly specified
- Newbie friendliness
- 35/100