308aada5f9
Co-authored-by: Carlos Florencio <carlosmflorencio@gmail.com>
333 lines
18 KiB
Markdown
333 lines
18 KiB
Markdown
---
|
||
status: done
|
||
created: 2026-09-15
|
||
requirements:
|
||
- REQ-TASKS-WEB-PREVIEW-FEEDBACK-001
|
||
- REQ-TASKS-WEB-PREVIEW-FEEDBACK-002
|
||
- REQ-TASKS-WEB-PREVIEW-FEEDBACK-003
|
||
- REQ-TASKS-WEB-PREVIEW-FEEDBACK-004
|
||
system_design:
|
||
- ../../specs/tasks/system-design/web-preview-feedback.md
|
||
legacy_specs:
|
||
- ../../specs/ui/requirements/browser-inspect-annotations-save.md
|
||
---
|
||
|
||
# Implementation Plan: Interactive Web Preview Feedback
|
||
|
||
## Overview
|
||
|
||
Replace Browser-panel-local annotations with a task-owned review workflow that
|
||
works in both the Browser panel and native HTML-file preview. Users capture text,
|
||
DOM elements, or screenshot regions across navigable pages, add required
|
||
comments, and review one durable pending collection. The ordinary composer Send
|
||
action delivers the current versioned snapshot to the selected Agent session,
|
||
using direct delivery or the existing queue, and consumes it only after durable
|
||
acceptance.
|
||
|
||
Implementation follows Red-Green-Refactor inside every work order. The package
|
||
first establishes persistence and synchronization, then atomic chat delivery,
|
||
shared text and element capture, screenshot capture and attachment ownership,
|
||
and final public guidance plus browser proof.
|
||
|
||
## Scope
|
||
|
||
### In scope
|
||
|
||
- A revisioned task-owned preview-feedback collection on SQLite and PostgreSQL.
|
||
- Authorized WebSocket CRUD and full-snapshot synchronization.
|
||
- Durable screenshot storage through the existing attachment service.
|
||
- Exact-reference direct and queued delivery with server-owned formatting and
|
||
atomic feedback consumption.
|
||
- One composer context item shared by every session in the task.
|
||
- Text, element, and screenshot-region capture in Browser and native HTML-file
|
||
preview surfaces.
|
||
- Cross-page pending review and best-effort marker restoration.
|
||
- Desktop Popover/panel controls and a phone Drawer with touch capture.
|
||
- Localization in all shipped catalogs, public documentation, and focused unit,
|
||
integration, desktop, mobile, and Docker-backed E2E tests.
|
||
- Final repository formatting, typecheck, test, and lint requested for the
|
||
implementation phase.
|
||
|
||
### Out of scope
|
||
|
||
- Source-line mapping, full browser developer tools, video, full-page stitched
|
||
screenshots, console or network capture, and arbitrary `file://` pages.
|
||
- A separate untrusted-content origin or a change to the trusted HTML-preview
|
||
execution model.
|
||
- Per-item Run, multi-session broadcast, automatic sending, or task-wide
|
||
conversion of other comment sources.
|
||
- Pixel-identical capture of unreadable cross-origin media.
|
||
|
||
## Technical approach
|
||
|
||
### Task collection
|
||
|
||
Add `task_preview_feedback_collections` and `task_preview_feedback` with
|
||
task-cascade ownership, monotonic collection revisions, optimistic row versions,
|
||
stable order, kind-specific payload validation, and bounded snapshots. Screenshot
|
||
rows reference uniquely claimed PNG attachments; staged upload, task feedback,
|
||
message, and queue claims use one attachment lifecycle.
|
||
|
||
Authorized WebSocket actions return complete replacement snapshots and publish
|
||
`task.preview_feedback.changed`. A dedicated frontend slice keeps one snapshot
|
||
per task and does not use the session comment store or browser storage.
|
||
|
||
### Message admission
|
||
|
||
Extend the plan-comment admission envelope with `preview_feedback_refs`. The
|
||
backend resolves exact task-owned versions and creates a visible
|
||
`### Web Preview Feedback` prompt block. Screenshot comments include their page
|
||
context and PNG attachment. The final direct or queued repository transaction
|
||
claims all attachments, persists delivery, conditionally removes referenced
|
||
feedback, and increments collection revisions. Rejection and conflicts leave
|
||
the pending set and composer untouched.
|
||
|
||
### Shared preview capture
|
||
|
||
Refactor the injected inspector into a versioned selection bridge. It reports
|
||
bounded text, element, page, and region metadata to the parent window and accepts
|
||
marker projections for the current route. `BrowserPanel` uses the existing
|
||
localhost proxy rewrite. `HtmlPreviewContent` recognizes its already-proxied URL
|
||
as inspector-capable without routing it a second time.
|
||
|
||
Kandev-owned chrome provides capture modes, localized comment editing, upload
|
||
state, pending review, and errors. The parent validates iframe events by source
|
||
and schema. Element HTML renders only as escaped code.
|
||
|
||
### Screenshot regions
|
||
|
||
Add `html2canvas` to the web application and rasterize the selected rectangle
|
||
from the same-origin proxied iframe document. Downscale output above the pixel
|
||
bound, encode PNG, and require confirmation through a thumbnail before upload.
|
||
Save uploads the image, then atomically creates the feedback claim. Capture or
|
||
save failure keeps the local draft and creates no incomplete row.
|
||
|
||
### Responsive composition
|
||
|
||
Desktop uses one **Annotate** control in preview chrome, an anchored capture
|
||
draft Popover, and a pending panel grouped by page. Phone uses one touch-sized
|
||
header action and a bottom Drawer for modes, draft editing, and the list.
|
||
Screenshot drag mode temporarily owns iframe gestures; every other state keeps
|
||
ordinary page navigation and scrolling.
|
||
|
||
## ASCII UI preview
|
||
|
||
The control hierarchy, one task-wide pending count, required comment, ordinary
|
||
composer Send, and phone Drawer are requirements. Exact spacing, icons, colors,
|
||
and row truncation are illustrative and must use existing Kandev tokens and
|
||
localized copy.
|
||
|
||
### UI-01: Desktop preview annotation
|
||
|
||
Entry point: Browser panel or rendered HTML-file preview. The toolbar is fixed;
|
||
the page owns iframe scrolling. Covers `AC-TASKS-WEB-PREVIEW-FEEDBACK-002.1`
|
||
through `.5`, `.7`, and `AC-TASKS-WEB-PREVIEW-FEEDBACK-004.1`.
|
||
|
||
```text
|
||
┌ Browser / index.html ───────────────────────────────────────────────────────┐
|
||
│ [ local page or file ] [Refresh] [Annotate (3) ▾] │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ interactive page (scrolls) │
|
||
│ │
|
||
│ ┌──── button#save.primary ──────────┐ ② │
|
||
│ │ Save │ │
|
||
│ └───────────────────────────────────┘ │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ Pending feedback (3) [Clear all] │
|
||
│ /products ① Text: “Choose a plan” “Increase contrast” [Edit] │
|
||
│ /products ② <button.checkout> “Align with price” [Edit] │
|
||
│ /account ③ Screenshot 820 × 360 “Form clips here” [Edit] │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
|
||
Annotate menu Capture draft Popover
|
||
┌─────────────────────┐ ┌────────────────────────────────────┐
|
||
│ Select text │ │ Element: <button.checkout> │
|
||
│ Select element │ │ Comment * │
|
||
│ Screenshot region │ │ [ Align with price... ] │
|
||
│ Review 3 pending │ │ [Cancel] [Add] │
|
||
└─────────────────────┘ └────────────────────────────────────┘
|
||
```
|
||
|
||
### UI-02: Phone preview annotation
|
||
|
||
Entry point: focused Browser or HTML-file preview. The preview is full height;
|
||
the Drawer has one internal scroll owner and safe-area clearance. Covers
|
||
`AC-TASKS-WEB-PREVIEW-FEEDBACK-004.2` through `.5`.
|
||
|
||
```text
|
||
┌ index.html ──────────────────────────┐
|
||
│ [Show code] [Annotate 3]│ fixed, 44 px actions
|
||
├──────────────────────────────────────┤
|
||
│ │
|
||
│ interactive page (scrolls) │
|
||
│ │
|
||
│ Screenshot region: drag to capture │ capture mode only
|
||
│ [Cancel]│
|
||
└──────────────────────────────────────┘
|
||
|
||
┌ Annotation Drawer ───────────────────┐
|
||
│ ━ │
|
||
│ Add feedback │
|
||
│ [Text] [Element] [Screenshot region] │
|
||
│ │
|
||
│ Pending feedback (3) │
|
||
│ /products · Text [Edit] │
|
||
│ /products · Element [Edit] │
|
||
│ /account · Screenshot [Edit] │
|
||
│ │
|
||
│ one scroll area │
|
||
└──────────────────────────────────────┘
|
||
```
|
||
|
||
### UI-03: Ordinary composer delivery
|
||
|
||
Entry point: any task session composer. Covers
|
||
`AC-TASKS-WEB-PREVIEW-FEEDBACK-003.1` through `.6`.
|
||
|
||
```text
|
||
┌ Context ────────────────────────────────────────────────────────────────────┐
|
||
│ [Preview feedback · 3] [Plan comments · 1] │
|
||
├─────────────────────────────────────────────────────────────────────────────┤
|
||
│ Add an optional message... [Send] │
|
||
└─────────────────────────────────────────────────────────────────────────────┘
|
||
```
|
||
|
||
### UI-04: Screenshot draft and recoverable failure
|
||
|
||
Entry point: after selecting a region. Covers
|
||
`AC-TASKS-WEB-PREVIEW-FEEDBACK-002.3`, `.4`, and
|
||
`AC-TASKS-WEB-PREVIEW-FEEDBACK-004.4`.
|
||
|
||
```text
|
||
┌ Screenshot feedback ───────────────────────────┐
|
||
│ ┌────────────────────────────────────────────┐ │
|
||
│ │ captured region thumbnail │ │
|
||
│ └────────────────────────────────────────────┘ │
|
||
│ 820 × 360 · PNG │
|
||
│ Comment * │
|
||
│ [ Form clips below the submit button... ] │
|
||
│ Could not upload the image. Try again. │ visible when failed
|
||
│ [Cancel] [Retry / Add] │
|
||
└────────────────────────────────────────────────┘
|
||
```
|
||
|
||
## Acceptance evidence
|
||
|
||
| Acceptance criteria | Evidence owner |
|
||
| --- | --- |
|
||
| `AC-TASKS-WEB-PREVIEW-FEEDBACK-001.1` through `.5` | Task 01 repository, service, WebSocket, frontend snapshot, reconnect, and conflict tests |
|
||
| `AC-TASKS-WEB-PREVIEW-FEEDBACK-003.1` through `.6` | Task 02 direct-message, queue, formatting, attachment, replay, and composer tests |
|
||
| `AC-TASKS-WEB-PREVIEW-FEEDBACK-002.1`, `.2`, `.4` through `.7` | Task 03 bridge, Browser/HTML preview, candidate hint, marker, panel, desktop, and phone component tests |
|
||
| `AC-TASKS-WEB-PREVIEW-FEEDBACK-002.3` | Task 04 rasterization, preview, upload, PNG validation, and attachment-lifecycle tests |
|
||
| `AC-TASKS-WEB-PREVIEW-FEEDBACK-004.1` through `.5` | Tasks 03 and 05 accessibility, mobile, desktop, and Docker-backed E2E |
|
||
| All criteria | Task 05 public guidance, focused E2E, and requested repository checks |
|
||
|
||
## Work orders
|
||
|
||
- [x] [Task 01: Persist and synchronize preview feedback](task-01-persist-and-sync-feedback.md)
|
||
- [x] [Task 02: Deliver preview feedback through chat](task-02-deliver-feedback-through-chat.md)
|
||
- [x] [Task 03: Capture text and elements across previews](task-03-capture-text-and-elements.md)
|
||
- [x] [Task 04: Capture screenshot regions as attachments](task-04-capture-screenshot-regions.md)
|
||
- [x] [Task 05: Document and prove the complete workflow](task-05-docs-e2e-and-verification.md)
|
||
|
||
## Dependency order
|
||
|
||
```text
|
||
Task 01 durable collection and synchronization
|
||
|
|
||
v
|
||
Task 02 exact direct and queued delivery
|
||
|
|
||
v
|
||
Task 03 Browser and HTML text/element capture
|
||
|
|
||
v
|
||
Task 04 screenshot capture and attachment ownership
|
||
|
|
||
v
|
||
Task 05 public docs, desktop/mobile/container E2E, final checks
|
||
```
|
||
|
||
The collection exists before message admission references it. Message admission
|
||
is complete before UI capture can create user-visible pending data. Screenshot
|
||
work follows the shared capture workflow and reuses the already-tested delivery
|
||
and task-attachment boundaries. Final E2E and documentation describe only the
|
||
settled end-to-end behavior.
|
||
|
||
## Verification strategy
|
||
|
||
- Every work order starts with focused failing tests, records the expected RED
|
||
result, implements the minimum behavior, reruns GREEN, then refactors with the
|
||
same focused tests green.
|
||
- Backend repository and service tests run with `-race` and cover both SQLite
|
||
and the environment-gated PostgreSQL paths already used by adjacent plan
|
||
comment and attachment tests.
|
||
- Frontend Vitest covers pure bridge/raster helpers, task state, message
|
||
submission, and responsive components. Typecheck, ESLint, and i18n checks run
|
||
after the affected vertical slice.
|
||
- Managed Playwright runs rebuild backend and web artifacts, then cover desktop,
|
||
mobile, and the Docker-backed executor path with one worker per project.
|
||
- The final work order runs `make fmt` first, followed by
|
||
`make typecheck test lint`, exactly as requested. A conventional commit is
|
||
created only after all checks pass and work-order results are recorded.
|
||
|
||
## Risks
|
||
|
||
- `html2canvas` cannot reproduce every CSS feature or unreadable cross-origin
|
||
resource. Mandatory thumbnail review makes the resulting PNG explicit before
|
||
persistence; failed rendering never produces a partial pending row.
|
||
- Preview content runs under the existing trusted same-origin model. Bridge
|
||
source/schema validation and server authorization must prevent that content
|
||
from choosing task or attachment ownership.
|
||
- Combining ordinary files and screenshots can cross the existing ten-file or
|
||
100 MiB message limits. Admission must reject atomically and the composer must
|
||
explain which limit was crossed.
|
||
- Exact feedback consumption touches both direct and queued repositories.
|
||
Reusing the established plan-comment lease and replay boundary is required to
|
||
avoid a second, weaker delivery implementation.
|
||
- Touch region capture competes with page scroll. Only the explicit screenshot
|
||
mode may suppress iframe drag gestures, and cleanup must run on completion,
|
||
cancel, navigation, or unmount.
|
||
- Full-snapshot events can grow with HTML excerpts. Shared count and aggregate
|
||
byte limits must be enforced before persistence in every database dialect.
|
||
|
||
## Completion gate
|
||
|
||
The implementation is complete when all five work orders are `done`, their
|
||
focused checks and the final requested repository checks pass, public docs
|
||
describe the shipped workflow and limits, generated dependency licenses are
|
||
current, and the verified changes have a Conventional Commit. The user can then
|
||
move the task to Test.
|
||
|
||
## Verification results
|
||
|
||
### Review follow-up (2026-09-16)
|
||
|
||
The [review-fix package](../web-preview-feedback-review-fixes/plan.md) owns
|
||
three open corrections: queue replay, screenshot draft comments, and independent
|
||
collection access. It reuses this package's requirements and system design.
|
||
Tasks 02, 03, 04, and 05 intersect those corrections. Their results here remain
|
||
historical contributor evidence, not evidence that the new regressions pass.
|
||
The follow-up package owns its pending statuses and new command results.
|
||
Its scope does not include a commit, push, or whole-PR merge clearance.
|
||
|
||
### Original implementation results
|
||
|
||
- Desktop Chromium, mobile Chrome, and Docker-backed Playwright scenarios each
|
||
pass against rebuilt production artifacts. They cover multi-route durable
|
||
review, exact generated-text position evidence, candidate highlighting,
|
||
touch region capture, panel reopening, direct delivery, queued delivery, and
|
||
real screenshot attachments.
|
||
- The full web suite passes 2,095 files and 18,041 tests, with 4 intentional
|
||
skips. Focused frontend suites pass 88 preview, composer, API, store, bridge,
|
||
screenshot, and WebSocket tests.
|
||
- Preview-feedback repository, service, handler, queue, and attachment tests
|
||
pass. The full backend run passes every package except the unchanged
|
||
real-process probe integration in the elevated test namespace, where host
|
||
PIDs are combined with container `/proc/uptime`; that package passes 20
|
||
consecutive runs in the normal namespace.
|
||
- Host and Linux backend artifacts, the E2E web bundle, public-doc validators,
|
||
spec validators, CLI tests, formatting, typecheck, and lint pass. Script
|
||
Git fixtures use repository-local empty hook paths so machine-wide hooks do
|
||
not affect their synthetic commits.
|