kandev/docs/specs/tasks/requirements/web-preview-feedback.md

status, system, created, owners

status	system	created	owners
active	tasks	2026-09-15	kandev

Web Preview Feedback Requirements

Overview

Kandev shall let a user review an interactive page in either the Browser panel or an inline HTML-file preview, capture the relevant rendered content, attach a comment, and deliberately send the accumulated feedback to an Agent session. The pending feedback belongs to the task so navigation, panel closure, session selection, browser reloads, and backend restarts cannot silently discard it.

The task system owns persistence and delivery because feedback is withheld until a task message is accepted. The UI system owns capture and responsive presentation. Existing session preview routing, trusted HTML execution, chat attachments, and direct or queued message admission remain adjacent contracts.

Terminology

• Preview feedback: A saved, unsent user comment plus a text, element, or screenshot capture from a rendered page.
• Preview source: The Browser-panel page or published HTML-file preview where a capture was made.
• Page identity: Stable source metadata plus the navigated route at capture time. It identifies context without making the ephemeral proxy URL durable.
• Capture draft: A selection and comment that have not yet been accepted into the pending task collection.
• Pending collection: The authoritative set of preview feedback that has been saved but not accepted as a direct or queued message.
• Accepted delivery: A direct user message durably persisted for dispatch, or a queued prompt durably admitted for the selected session.

Requirements

REQ-TASKS-WEB-PREVIEW-FEEDBACK-001: Preserve one task-owned pending collection

Intent: Keep unsent page-review feedback available until the user either deletes it or deliberately sends it.

User story: As a user reviewing a multi-page interface, I want my saved feedback to survive navigation and workspace changes, so that I can finish the review before contacting the agent.

Acceptance criteria

• AC-TASKS-WEB-PREVIEW-FEEDBACK-001.1: After an authorized user saves preview feedback, Kandev shall show the same pending item in every Browser, HTML-preview, and task-composer view for that task.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-001.2: Navigating within or between preview pages, closing or reopening a preview, switching or deleting sessions, and changing the task's primary session shall not hide, move, duplicate, or delete pending feedback.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-001.3: After reconnect, browser reload, backend restart, or opening the task from another authorized browser, Kandev shall restore the pending collection and its screenshot images from backend state.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-001.4: A user shall be able to inspect, edit the comment on, and delete any pending item without an available Agent session. Deleting screenshot feedback shall also delete its unsent stored image.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-001.5: Concurrent clients shall converge on an authoritative ordered snapshot. A stale edit, delete, or send shall fail without overwriting newer feedback and shall make the current collection available for recovery.

REQ-TASKS-WEB-PREVIEW-FEEDBACK-002: Capture rendered page context

Intent: Give the agent the exact visible context behind a review comment without forcing the user to translate the page into prose.

User story: As a user reviewing an interface, I want to point at text, elements, or a page region, so that my feedback identifies what should change.

Acceptance criteria

• AC-TASKS-WEB-PREVIEW-FEEDBACK-002.1: The Browser panel and an inline .html or .htm preview shall expose the same three capture modes whenever their content is available through Kandev's session preview proxy: selected text, DOM element, and screenshot region.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-002.2: A text capture shall retain and deliver the exact selected text, its rendered containing-element snapshot, DOM range endpoints, stable selectors when derivable, selection rectangles, document scroll and viewport dimensions, and page identity. This captured runtime context shall remain available when the text was generated by script or can no longer be found on the live page. An element capture shall retain a bounded HTML snippet, semantic element metadata, a stable selector when one can be derived, its rendered rectangle and viewport context, and page identity.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-002.3: A screenshot-region capture shall create a real PNG image of the user-selected rendered region, show that image for review before saving, and retain its page identity and capture bounds. Kandev shall report capture failure instead of saving a feedback item without its image.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-002.4: Every saved capture shall require a non-blank user comment. Cancelling a capture or a failed save shall not add a pending item; a failed save shall preserve the capture draft for retry.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-002.5: After navigation, feedback from prior pages shall remain in the pending collection. Returning to a matching page shall restore resolvable text or element markers without changing or deleting captures whose DOM anchors no longer resolve.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-002.6: Captured page content shall be shown and delivered as quoted user context. Kandev shall not execute captured HTML in its own chrome or treat page text as system instructions.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-002.7: While element capture is active, Kandev shall visually outline the current candidate before selection and show a concise element label such as tag, ID, or class. Pointer hover, keyboard focus, and an active touch press shall update the same candidate hint. The hint shall disappear on cancel, completion, navigation, or mode exit.

REQ-TASKS-WEB-PREVIEW-FEEDBACK-003: Deliver feedback through ordinary chat Send

Intent: Keep review comments private until one familiar, explicit action chooses the receiving Agent session.

User story: As a user, I want pending preview feedback to join my next chat message only when I press Send, so that I can review several pages before the agent sees anything.

Acceptance criteria

• AC-TASKS-WEB-PREVIEW-FEEDBACK-003.1: Every composer for the task shall show one pending-context item with the current preview-feedback count. The item shall open the shared collection and shall not expose feedback to the Agent merely because it is visible in the composer.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-003.2: Ordinary chat Send shall snapshot the visible pending item identifiers and versions and address them to the session whose composer the user submitted. Typed text and other supported context or attachments may accompany the feedback; typed text may be empty when at least one preview-feedback item is selected.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-003.3: A promptable session shall receive a direct message. A busy session shall receive the same content through its existing durable queue path. Preview feedback shall not introduce an independent Run, broadcast, or auto-send action.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-003.4: Text and element feedback shall be expanded into visible, bounded Markdown. Screenshot feedback shall include its comment and page context in that Markdown and its PNG as an actual image attachment available to the receiving agent and transcript.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-003.5: Accepted direct or queued delivery shall consume exactly the submitted feedback versions task-wide in the same durable operation that accepts the prompt and claims screenshot attachments. A validation, capacity, authorization, routing, attachment, or version failure shall preserve every submitted item and the composer draft for retry.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-003.6: A lost response or repeated submit with the same caller identity shall reconcile to the original accepted message or queue entry without delivering the feedback twice. Feedback added or edited after the user's Send snapshot shall remain pending.

REQ-TASKS-WEB-PREVIEW-FEEDBACK-004: Provide responsive and accessible review controls

Intent: Make page review usable with keyboard, mouse, and touch without turning the phone preview into a compressed desktop toolbar.

User story: As a desktop or phone user, I want capture and review controls that fit my input method and viewport, so that I can complete the same feedback workflow on either device.

Acceptance criteria

• AC-TASKS-WEB-PREVIEW-FEEDBACK-004.1: Desktop shall expose capture modes and the pending count in Kandev-owned preview chrome. Keyboard users shall be able to enter and exit each mode, save or cancel a draft, inspect the pending list, and return focus to the invoking control.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-004.2: Phone and coarse-pointer surfaces shall use a bottom Drawer for mode selection, draft editing, and the pending list. Actions shall have a minimum 44-pixel touch dimension, respect safe areas, keep one scroll owner, and avoid document-level horizontal overflow.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-004.3: Active touch-region capture may temporarily own drag gestures inside the preview, but cancelling or completing capture shall restore ordinary page scrolling and navigation.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-004.4: Selection, saving, upload, conflict, and delivery failures shall have localized visible status text. Capture markers, modes, and counts shall not rely on color or hover alone.
• AC-TASKS-WEB-PREVIEW-FEEDBACK-004.5: Browser-panel pages served by local development servers, including ports published from Docker-backed task sessions, and native HTML-file previews shall retain their current navigation, script execution, and source-return behavior while feedback controls are inactive.

Out of scope

• Mapping rendered DOM nodes or screenshot pixels to source-file line numbers.
• Annotating arbitrary internet pages or file:// URLs outside Kandev's session-authorized preview proxy.
• Recording video, full-page stitched captures, console logs, network traces, accessibility-tree snapshots, or browser developer-tools editing.
• Sending feedback to multiple sessions, adding a per-item Run action, or exposing unsent feedback as ambient Agent context.
• Pixel-identical capture of cross-origin media that the browser cannot read.
• Preserving ephemeral preview URLs or HTML preview execution state after the owning task runtime stops.