Skip to main content

ADR-0009: Live Web-Target Markup (Embedded Browser)

Status​

Proposed / exploring. Captured during ideation on 2026-07-04. Not yet decided; revisit after the core loop (SPEC-0001..0003) is standing.

Context and Problem Statement​

Stet reviews code, but for a web project the thing you actually care about is the running product. When Stet dispatches an agent, the sandbox (ADR-0003) can run the project's dev server; Stet already has a local, addressable web app on hand.

The idea: embed a browser in Stet pointed at that running app, and let the human mark up the live UI as they use it — click through the app, highlight an element, drag a callout, comment "this button is misaligned" or "this flow is confusing" — and have that markup become review feedback that compiles into a brief (ADR-0006) just like code markup does. Feedback moves from the source to the rendered artifact.

This extends the "editorial, multi-modal review" posture (ADR-0002, SPEC-0002) from text/emoji/voice/scribble on code to direct annotation of a live web UI.

Sketch​

  • The container runtime (ADR-0003) exposes the running dev server's port to the host.
  • Stet embeds a WKWebView (or equivalent) bound to that URL as a first-class canvas mode alongside code and Markdown.
  • An annotation layer over the web view captures: element selection (DOM path / bounding box), freeform callouts, comments, emoji verbs (ADR-0005), and ideally a screenshot of the annotated state.
  • Anchors resolve toward source where possible (DOM element → component/file via source maps, framework devtools protocols, or an agent step that maps the selector to the responsible code).
  • On Submit, web-UI annotations join the same Brief as code annotations, so one review can span "the code and how it looks/behaves."

Why it fits​

  • Good, because it makes the product reviewable, not just its source — a strong, demoable differentiator.
  • Good, because it reuses the existing sandbox, verb, and brief machinery rather than inventing a parallel path.
  • Good, because it pairs naturally with agent iteration: mark the live UI, dispatch, reload the same URL, see the fix.

Open questions​

  • Reliable DOM-element → source-file mapping (source maps? framework-specific? agent-inferred?).
  • How to represent a live-UI anchor durably in the Brief (selector + screenshot + route + viewport?).
  • Interaction/session state: how much of the user's click-path to capture as context for the agent.
  • Security of pointing an embedded browser at arbitrary local containers.

Consequences (tentative)​

  • Adds a third canvas mode (web) and an annotation layer over WKWebView.
  • Requires runtime port-exposure plumbing (ADR-0003) and a source-mapping strategy.
  • Expands the Brief/anchor schema (SPEC-0002) to carry live-UI anchors.

More Information​

Sibling idea for native desktop apps: ADR-0010 (screenshot-to-narrative). Shared theme: review the running artifact, not only the source.