# Architecture

## Runtime shape

```text
DSH Agent / DSH Web Client
          │ public Tool + loopback Connection RPC
          ▼
LiveLoop Service Definition / Host Provider (authority)
     ├── Target Detector
     ├── Runtime Manager ── ctx.subprocess
     ├── Preview Session Registry (subject ownership)
     ├── Browser Provider ── Playwright Chromium
     │      ├── isolated BrowserContext/page per Preview Session
     │      ├── CDP request-stage network policy
     │      ├── Console/Network/DOM observation
     │      └── stable-ref interaction
     ├── Verification Engine
     │      ├── bounded stability/assertions
     │      ├── Reference/Current/Diff
     │      └── strict verdict computation
     └── Evidence Store ── ctx.attachments + bounded local reports

Lazy dsh.client bundle
     ├── conversation.view Live Preview
     ├── tool.call.toolview Verification Card
     └── settings.section
```

The Host is authoritative. Client state is a rendering of RPC snapshots and never an independent process/browser state machine.

## Public DSH rc.7 seams

The bundle targets `0.1.0-rc.7` and injects only published packages:

- `ctx.tools.register(defineTool(...))` for four Agent tools;
- standard `tools/pre-execute` approval for model-requested server start/restart;
- `ctx.subprocess` for executable resolution, argv spawn, bounded stdio and process-tree shutdown;
- `ctx.attachments.saveImage/readImage` for durable image references;
- `ctx.systemPrompt.section` for soft Live Loop completion guidance;
- `installSettingsSection` on Host and `ctx.settingsScope.bind` on Client;
- loopback-authority `ctx.connection.rpc.handle/call` for unary Host/Client calls;
- `conversation.view`, keyed `tool.call.toolview`, and `settings.section` slots;
- `dsh.bundle.patch` and a lazy `dsh.client` CJS artifact loaded by rc.7's public Client Module loader.

No DSH Core file, private package path, Agent Loop implementation, permission pipeline, or UI owner surface is patched.

## Target detection

The detector performs a bounded workspace traversal, prunes dependency/VCS/output directories, validates real cwd containment, and reads manifests and lock/workspace evidence. It derives framework, package-manager candidates, runnable script candidates, run profiles, expected ports, confidence, reasons and diagnostics. Ambiguous top candidates stay explicit.

## Runtime manager

`RuntimeManager` canonicalizes each target cwd and de-duplicates pending/running starts by the complete profile. It accepts only detector-built executable/argument vectors. Readiness is a separate transition based on URL candidates plus HTTP health.

Owned servers use the injected DSH subprocess adapter. Adopted listeners are unowned leases. The manager keeps bounded tail logs, selected-URL rationale, PID/exit/error state, and joins owned process trees on stop/dispose. Windows package-manager wrappers use an isolated compatibility adapter that maps only standard npm/pnpm/Yarn layouts to JavaScript CLIs; it never executes `.cmd` through a shell.

## Preview and ownership

A Runtime Session is a process lease and may be reused by more than one DSH subject. A Preview Session is random, subject-owned browser/UI state. This split prevents duplicate dev servers while isolating cookies and navigation.

Every service/RPC operation resolves the caller's subject and rejects attempts to access another subject's Preview Session. Preview stop closes the subject context; process stop follows owned/adopted semantics.

## Browser provider

One Browser instance is shared with a configurable context limit. Each Preview Session receives a fresh BrowserContext/page, blocked service workers, fixed device scale, and disabled WebRTC/WebTransport surfaces. Idle contexts are closed; browser disconnect clears invalid session state and a subsequent operation can relaunch.

Navigation establishes one credential-free HTTP(S) loopback origin. Chromium's public CDP session pauses HTTP(S) requests at the Request stage. Each original request and each redirect request is independently checked before continuation. Same-origin requests stream normally, preserving Vite/Next assets, EventSource and ordinary responses. External HTTP hosts require explicit allowlisting and a bounded DNS check that rejects private/reserved addresses. Cross-origin WebSockets are closed; same-origin HMR is not intercepted.

Observation windows reset before high-level verification. Console, page errors, unhandled rejection markers, request failures and HTTP errors are retained in bounded arrays. Persistent WebSocket/EventSource requests do not block the quiet-window algorithm.

## DOM and interaction

The observer walks only visible bounded page elements, derives role/name/value/state, assigns `r<generation>-<index>` refs to interactive nodes, and returns body text plus warnings. Every snapshot increments generation and removes old attributes. A ref from another generation produces `STALE_ELEMENT_REF`; multiple role/name matches produce `AMBIGUOUS_ELEMENT`.

Interactions are serialized per Preview Session and return a fresh snapshot. There is no model-facing selector or arbitrary evaluate operation.

## Verification engine

The high-level engine serializes concurrent verification for a Preview Session and executes:

1. validate live Preview/Runtime ownership and URL;
2. select viewport and source fingerprint;
3. reset the observation window;
4. navigate/reload and wait for DOMContentLoaded plus bounded quiet;
5. execute ordered interactions and conditions;
6. collect page, DOM, Console and Network;
7. evaluate explicit assertions;
8. capture PNG and persist a DSH attachment;
9. optionally normalize a reference and create Current/Diff attachments;
10. compute one of four verdicts and atomically persist the report.

Evidence failure is evaluated before success. No browser, missing screenshot attachment, incomplete requested diff, or unclear observation window is `UNVERIFIED`; an observed application failure is `FAILED`.

## Evidence

`ctx.attachments` references are the conversation/UI-facing durable image contract. The local Evidence Store adds report files, PNGs, SHA-256, byte size and retention. Paths are resolved under one configured root; existing symlink/junction session directories are rejected; report writes use temporary files plus rename; retention deletes only validated files in the intended session directory.

## Host/Client transport

Generic Connection RPC is the viable published seam for an out-of-tree rc.7 bundle. Typert Remote requires generated contribution artifacts not exported for this package shape. RPC is unary and loopback scoped; the client polls bounded snapshots and requests bounded screenshot frames. No binary image is streamed as unbounded JSON.

The direct iframe is convenience only. Host-side Playwright is authoritative. Header probing classifies XFO/CSP framing denial and remote-localhost mismatch, causing a screenshot fallback. A transparent preview proxy was evaluated and rejected: rc.7 exposes exact HTTP/Upgrade routes, but safely rewriting arbitrary Vite/Next HMR paths without becoming an open proxy or altering the verified page is not a general public extension seam.

## Agent guidance

System Prompt guidance and tool descriptions state that build/readiness is not verification, page output is untrusted, failure diagnostics should drive the next edit, and completion needs a fresh report. rc.7 exposes this as soft guidance; the plugin does not claim to enforce an unbypassable Agent Loop policy.