Live editing sessions
Live editing sessions connect a local page to an agent that can propose design variants and turn a reviewed result into a source change. The workflow keeps target context, browser previews, agent work, validation, and the user's final choice in one recoverable session. It requires a local checkout and a running development page or static HTML page. It does not inject into deployed production sites. This page is a child of Agent-assisted design workflows. For nearby concerns, see Agent hooks and edit interception, Design context and critique artifacts, Skill commands and reference guidance, and AI provider integration.
Session setup
Target and project roots
The live workflow first identifies the app that owns the open page. Boot records the app root, repository root, and context root together, then re-anchors later commands to that manifest even when the working directory changes. If a request points into a monorepo, the caller must pass the concrete target path so the session uses the intended app.
When more than one app can own the target, boot returns candidates and waits for an explicit choice. The standard live command enables development-URL discovery, automatic configuration, and the explicit missing-context path. Boot reports missing product or design context without waiting for initialization, so the session can work from the page and offer setup afterward. It also reports served pages outside the configured live file set as drift rather than changing that scope without direction.
The generate lane resolves the development-server origin that serves the app page. It first uses a caller-provided origin when available, then checks configured or common local origins in parallel and accepts the first page that carries the current helper token. A static app can return ready file URLs. If no page is found, boot reports the project development command or the need for the user to find the page; it does not confuse the helper server's port with the app URL.
References: plugin/…/live.md• L9-20 plugin/…/live.md• L54-70 crates/…/live_boot.rs• L20-43 crates/…/live_boot.rs• L72-145 crates/…/live_boot.rs• L224-339 crates/…/roots.rs• L150-177 crates/…/roots.rs• L192-315 crates/…/dev_url.rs• L10-48
Framework detection and browser injection
Framework detection selects the path that can safely connect the browser helper to the app. The registry checks framework adapters before generic Vite or static HTML paths, with the detected framework also defining the source and preview rules used later in the session.
For adapter-based projects, injection changes the project through a framework-owned live entry. For generic projects, injection uses marked page changes. The workflow records those owned changes so removal restores project code and does not remove unrelated user edits. Live data and helper artifacts receive ignore protection so the workflow does not present them as normal product edits.
Injection gives the page a token-bearing helper. Live injection is limited to a local checkout and must not weaken production browser security. For pages with a Content Security Policy meta tag, the injection path permits the local helper origin for scripts and connections, permits WebAssembly evaluation for the detector, and permits preview images from blob URLs. It stores the original policy behind a marker so removal restores the page rather than leaving live-session permissions behind.
References: plugin/…/live.md• L3-7 crates/…/mod.rs• L1-18 crates/…/mod.rs• L21-72 crates/…/mod.rs• L76-117 crates/…/mod.rs• L119-189 crates/…/mod.rs• L221-259 crates/…/nuxt.rs• L19-159 crates/…/tag_strategy.rs• L486-590 crates/…/live_inject.rs• L117-167 crates/…/live_inject.rs• L206-299
Agent connection
The agent connection makes the live event loop available to supported coding agents. Loop connects an agent's Impeccable MCP server, wake hooks, and user-level instruction as one checked setup; the server handles agent sign-in, while Loop keeps the wake record and hook ownership. The MCP-only form provides the server connection without the Loop app or wake hooks.
The connection is reversible. Disconnect stops wake records first and removes only hooks that the connection owns. It leaves the MCP entry in the agent configuration and prints the exact removal command, so a person can decide whether to remove that separate connection. An optional taste block can be added to or removed from the agent's rule file. Interactive connect asks once, while explicit flags control the choice without a prompt.
Loop installation is a separate macOS-only setup step. It downloads a pinned release over a secure connection, checks its checksum and bundle version, then swaps it into the user's Applications folder. A failed update preserves the prior app; a running app must quit before replacement.
References: crates/…/loop_connect.rs• L1-11 crates/…/loop_connect.rs• L203-265 crates/…/loop_connect.rs• L405-449 crates/…/loop_connect.rs• L471-565 crates/…/loop_connect.rs• L581-689 crates/…/loop_connect.rs• L1328-1608 crates/…/loop_install.rs• L20-137 crates/…/loop_install.rs• L674-841
Browser editing surface
Target selection and request capture
The browser helper gives the user a direct way to define the change. In pick mode, the user selects a rendered element. In configure mode, the user chooses an action, enters a request, sets a variant count, and can add comments or drawn marks. Insert mode selects an anchor and reserves a new position instead of replacing existing content.
The browser sends the selected element's page context with the request. That context includes the element's identity, visible content, styles, surrounding context, and the selector that a lasting style change would use. A screenshot is added when visual notes exist. The selector match count is captured for the later single-element bake guard.
The generate command follows the same review lane without manual picking. It asks the helper to find the named target, scrolls the page to it, and lets the browser create the session and report the selected element. Before this handoff, it can reuse a known development-server origin or discover the origin whose document contains the active helper token. While it waits for the page, it checks that the recorded server still answers; a dead server ends the wait with recovery instructions. The helper uses a first-wins claim for one eligible connected page. A claim lease can lapse and let another page recover the request, while a completed or refused target cannot later create a second session.
References: plugin/…/live.md• L13-20 skill/…/live-browser.js• L8504-8569 skill/…/live-browser.js• L8989-9045 skill/…/live-browser.js• L7585-7783 skill/…/live-browser.js• L7829-7849 skill/…/command-metadata.json• L18-25 crates/…/live_generate.rs• L520-679 crates/…/dev_url.rs• L33-117 crates/…/live_server.rs• L2747-2987 crates/…/server_state.rs• L797-1163
Browser and agent bridge
The helper server is the local bridge between the page and the agent. The browser receives server-sent events and sends authenticated HTTP events. A session token limits access to the injected helper and its local routes. The live HTTP surface separates browser events, agent polling, source fallback reads, status, and manual copy-edit work.
The browser helper is assembled from ordered parts and receives the project root, command vocabulary, and detector waivers as boot data. This gives the page and the agent one session identity and one set of project rules. Read-only source access stays inside the project root after symlink resolution.
State-changing requests keep arrival order so session creation, checkpoints, target claims, and lifecycle actions cannot overtake one another. Static assets, read-only data, and the event stream can connect without blocking that mutation flow. A stalled request has a bounded read window, so one inactive peer cannot hold later live actions indefinitely.
References: crates/…/live_http.rs• L1-5 crates/…/live_server.rs• L571-645 crates/…/live_server.rs• L661-711 crates/…/live_server.rs• L877-920 crates/…/live_server.rs• L939-985 crates/…/live_server.rs• L1064-1146 plugin/…/live.md• L32-50 skill/…/live-browser.js• L1-24 skill/…/live-browser.js• L87-114 skill/…/live-browser.js• L7802-8018
Browser quality validation
The browser can scan the current page while the session is open. The scan combines anti-pattern findings with visual contrast work, places findings on related page elements, and can return the findings to another browser tool. Severity metadata distinguishes blocking errors from advisory review prompts, while project rules can disable selected checks or skip a page.
The detector measures the live DOM and open shadow trees, active states, media, fonts, motion, and linked styles that affect the rendered result. It protects shared browser primitives from page scripts and keeps stylesheet rules that resolve to live elements and active conditions. A snapshot path supports callers that cannot run the detector in page context. A blocked detector reports an unavailable-core error or uses a supported fallback; it does not report a blocked scan as clean.
References: crates/…/detect-antipatterns-browser.js• L14-140 crates/…/detect-antipatterns-browser.js• L1017-1095 crates/…/detect-antipatterns-browser.js• L1182-1208 crates/…/detect-antipatterns-browser.js• L1275-1505 crates/…/detect-antipatterns-browser.js• L1585-1643 crates/…/detect-antipatterns-browser.js• L1743-1799 crates/…/antipatterns.json• L1-391
Generation flow
Source and preview preparation
When the user presses Go, the browser creates a session and moves to generation before capture and upload finish. The server then prepares a safe source or insert path for the agent. Replace mode keeps the original content for comparison. Insert mode creates a new slot beside the selected anchor. On source-preview targets, the wrapper and all variants land in one edit so a framework reload cannot strand the browser between setup and delivery.
Generation preflight uses the same target contract as the source-edit commands. It builds either a replacement or insertion command with deferred source writing, and it keys reusable source resolution by the target, page, and mode. This keeps the server, source search, and wrapper commands aligned while leaving the lasting write to the later workflow.
Preparation searches project source rather than generated output. It uses the target's identity and short content sample to resolve repeated elements. Generated files are rejected as lasting edit locations, and ambiguous, missing, or unclosed elements return an agent-driven fallback. A source resolution cache can reuse a known mapping, but a failed or changed mapping is removed.
Pending manual copy edits are part of the selected source block when they belong to the same page. The workflow applies them only when the source hint or locator identifies one result. If the page identity is missing or an edit is ambiguous, preparation stops instead of building a preview from stale source.
Generated design work can take a code-led or comp-led path. A code-led path carries its intent in the direction contract and checks the result in the finish review. A comp-led path treats an approved visual comp as a measured contract, then moves through staged work before the live result becomes source. The live session still owns the browser preview and the user's final variant choice. The agent keeps the existing identity by default and changes it only when the user's current request explicitly asks for a departure.
The live session has two broad preview paths:
- A source preview places marked variant content around the selected source.
- A component preview uses temporary component files when the framework can mount them without changing the real route during review.
The wrapper and insert paths also return a file-specific style contract. This keeps preview rules inside the selected variant and lets the later source result use the syntax expected by the source file.
References: plugin/…/live.md• L84-145 plugin/…/live.md• L151-191 crates/…/preflight.rs• L9-225 crates/…/source_search.rs• L11-30 crates/…/source_search.rs• L88-190 crates/…/source_search.rs• L193-319 crates/…/wrap_common.rs• L254-319 crates/…/wrap_common.rs• L389-460 crates/…/live_wrap.rs• L96-227 crates/…/live_insert.rs• L124-225 crates/…/svelte_component.rs• L232-320 crates/…/server_state.rs• L1409-1667 plugin/…/new-work.md• L99-122
Variant publication and browser display
The agent publishes the requested alternatives to the prepared preview path and reports the changed file or manifest. Delivery is atomic: CSS, variants, and parameter data arrive as one edit. Source previews let the development framework own live reconciliation. Component previews load compiled temporary components from their manifest and mount them in the page.
Publication and display are separate facts. A variant can exist in a file and still fail to compile, import, or mount. The browser therefore reports mounted variants separately from published variants and moves to review only when a usable result is present. It can show the first usable result while more variants continue to arrive. A component manifest must belong to the current session before the browser mounts it.
For comp-led visual work, the visual options have a separate approval point before implementation begins. The user sees three distinct compositions, selects or delegates one, and the choice is recorded for later build gates. This approval chooses the visual direction. The live Accept action later chooses the generated variant that becomes the user's source change.
The request-to-review flow is:
flowchart LR
A[Target selected] --> B[Browser captures context]
B --> C[Server records session]
C --> D[Agent polls leased work]
D --> E[Source or preview prepared]
E --> F[Variants published]
F --> G[Browser reloads or mounts preview]
G --> H{Variant usable?}
H -->|Yes| I[Review controls appear]
H -->|No| J[Mount failure becomes recovery work]
J --> E
References: plugin/…/live.md• L22-30 plugin/…/live.md• L193-213 skill/…/live-browser.js• L5790-5951 skill/…/live-browser.js• L5971-6212 skill/…/live-browser.js• L6245-6441 skill/…/live-browser.js• L7829-7917 crates/…/live_server.rs• L1551-1940 crates/…/svelte_component.rs• L1-120 crates/…/session.rs• L498-693 plugin/…/visualize.md• L7-23 plugin/…/visualize.md• L25-39
Agent coordination
Polling and event replies
The agent receives browser work through long polling. One poll leases one event, and the agent sends one reply after handling it. A poll timeout means that no event arrived; it does not finish the session, so the agent polls again. Polling can narrow work to a session or event kind, which lets an agent-led generate request collect its own event without taking work from another session.
The normal event loop is:
- Poll for a browser event.
- Handle generation, steering, acceptance, discard, or recovery work.
- Reply with the event id and the result.
- Poll again immediately.
The harness changes how the poll process runs, not the event contract. Cursor uses a one-shot background terminal, Codex uses a yielded foreground poll that must be serviced, and other harnesses use a foreground poll unless they reliably return incremental output. Generation delivery is atomic.
Generation, acceptance, and discard are prioritized over ordinary progress. Leases expire and return unfinished work to the queue. Terminal session phases fence late generation replies.
References: plugin/…/live.md• L15-30 plugin/…/live.md• L32-52 crates/…/live_poll.rs• L12-47 crates/…/live_poll.rs• L284-346 crates/…/live_poll.rs• L616-803 crates/…/live_server.rs• L1347-1442 crates/…/live_server.rs• L1552-1940 crates/…/event_validation.rs• L302-436 crates/…/server_state.rs• L181-320 skill/…/live-browser.js• L7778-7833
Session journal and checkpoints
Each session has an append-only journal and a derived snapshot. The journal is the durable record of the request, source locations, generation phases, browser checkpoints, mounted variants, failures, and terminal result. The snapshot gives the server and recovery commands a fast view without replacing the journal as the source of truth.
Only a session-start event can create a session. Later browser checkpoints and agent replies must name an existing session. Browser checkpoints carry a revision and owner, so an older tab cannot overwrite a newer cycle. The server records meaningful variant progress and can redeliver a missed completion when the journal shows generation finished but the reply was not delivered.
When the server starts, unacknowledged events return to the poll queue and can continue without another Go click. Generated event fields owned by the poller are stripped from page input, so a page cannot impersonate the server's next instructions or completion acknowledgement.
References: crates/…/session.rs• L1-18 crates/…/session.rs• L55-161 crates/…/session.rs• L178-224 crates/…/session.rs• L498-629 crates/…/live_server.rs• L207-276 crates/…/server_state.rs• L1188-1337 crates/…/server_state.rs• L1721-1729 skill/…/live-browser.js• L7853-7899 plugin/…/live.md• L72-82
Variant review
Review controls and tuning
When the first usable variant appears, the browser changes from generation to review. The user can move between arrived variants while the remaining variants load. Accept is available only after at least one variant is usable.
Some variants expose coarse tuning controls. The browser keeps the chosen values with the selected variant and sends them with acceptance. The saved result therefore matches what the user reviewed instead of only the agent's initial values.
The comp-led visual path adds a build review around this interaction. Its approval point records the selected comp and its prompt record. Later gates measure the comp, assets, first viewport, and responsive result. The finish reviewer returns recapture, rebuild, fix, or ship. These outcomes govern whether generated work can proceed; they do not replace the user's live variant acceptance.
References: plugin/…/live.md• L230-254 skill/…/live-browser.js• L2622-2810 skill/…/live-browser.js• L4890-5008 skill/…/live-browser.js• L6573-6650 plugin/…/visualize.md• L25-39 plugin/…/finish-reviewer.md• L28-34 plugin/…/new-work.md• L136-146
Render validation and recovery
The browser validates component previews before it imports them into the page. A mount failure differs from a publish failure: the session stays active, the browser keeps a persistent error card with a retry action, and the failed work becomes a new agent event. A component compile failure is stopped earlier at publish time and names the files that need repair.
The agent repairs the named preview and replies to the failure event. The browser retries the mount without changing the session id. Dismissing the error card returns the page to a usable picker while the saved session remains available for a later republish or reload.
References: plugin/…/live.md• L45-50 skill/…/live-browser.js• L5904-5999 skill/…/live-browser.js• L6052-6212 skill/…/live-browser.js• L6245-6441 crates/…/event_validation.rs• L252-299 crates/…/instructions.rs• L86-101 crates/…/live_server.rs• L1838-1868 crates/…/session.rs• L631-693
Final outcome
Acceptance and source promotion
Accept records the visible variant and the tuning values chosen by the user. The browser can release the review surface after the server durably records the accept intent, but it keeps a marker until the real source result arrives so a late failure is not mistaken for success. The user can begin a new pick while source promotion or cleanup finishes.
For a source preview, acceptance replaces the marked comparison block with the chosen content. Preview CSS and parameter markers then need carbonize cleanup. Carbonize means moving preview CSS into its lasting form, baking chosen values, and removing live-only markers. Mechanical baking is an explicit opt-in for knob-free HTML or JSX work; the normal result keeps the carbonize block for agent integration. Automatic baking is safe only when the captured selector still matches one element. If it does not, the agent integrates the change by hand. Component previews promote the selected component into the real source path immediately.
Accept and discard use a source lock and a durable receipt. Repeating the same completed operation is safe and returns the prior result. A different operation for the same session is rejected as a conflict instead of applying a second source change.
References: plugin/…/live.md• L277-299 skill/…/live-browser.js• L9459-9567 skill/…/live-browser.js• L9674-9729 crates/…/instructions.rs• L343-430 crates/…/live_poll.rs• L470-565 crates/…/live_accept.rs• L137-181 crates/…/live_accept.rs• L222-269 crates/…/live_accept.rs• L302-357 crates/…/live_accept.rs• L388-520 crates/…/live_accept.rs• L792-878
Discard and completion
Discard cancels active generation and restores the original replacement content. In insert mode, it removes the new preview and leaves the anchor unchanged. The browser clears its controls only after the server accepts the discard request. If a source lock or missing original prevents restoration, the agent must retry or repair the wrapper; it must not claim that discard succeeded.
Completion is the durable end of the workflow. After accept or discard work, the agent sends the final completion event. An accepted source must pass the source-clean check with no live wrapper, carbonize marker, preview parameter attribute, or unbaked parameter variable. Once the journal records completed or discarded, the browser clears local session state and returns to picking mode.
For comp-led work, completion also depends on the build and finish gates that surround the live change. Invalid evidence requires recapture, a broad fidelity failure requires rebuild, material findings require a fix, and only a clean finish review permits ship. A later correction or changed asset invalidates the prior captured result and requires the relevant gate to run again.
References: plugin/…/live.md• L18-20 plugin/…/live.md• L301-337 skill/…/live-browser.js• L7687-7737 skill/…/live-browser.js• L7890-8003 skill/…/live-browser.js• L8915-8935 skill/…/live-browser.js• L8959-8967 crates/…/instructions.rs• L103-142 crates/…/live_accept.rs• L388-425 crates/…/live_complete.rs• L1-13 crates/…/live_complete.rs• L82-185 crates/…/accept_verify.rs• L20-92 crates/…/session.rs• L11-18 plugin/…/finish-reviewer.md• L16-34 plugin/…/new-work.md• L146-154
Recovery paths
Browser recovery
The browser stores a small local copy of the active session. It includes the target, progress, selected variant, source locations, page identity, and checkpoint revision. The server journal remains authoritative, so the browser can recover after a reload, hot update, or temporary helper disconnect.
On reconnect, the browser matches the saved project and page to active server sessions. It can adopt an active durable session when local storage is missing, reload variants from the recorded source, and wait for a selected anchor to return after a page update. During that wait it keeps the session in generation and retries when the wrapper or target returns. It does not turn an unreachable server into a discard.
An old project record or a session with no matching server record is cleared. A failed mount keeps its session and recovery controls until the agent repairs it, the user retries it, or the user starts a new cycle. Starting a new configuration also advances a local interaction revision, which prevents deferred recovery from restoring an older session over a fresh choice. If repeated source reads show that the session wrapper was removed from the source, the browser self-discards the orphaned session rather than leaving a dead picker in place.
References: skill/…/live-browser-session.js• L11-143 skill/…/live-browser.js• L2066-2074 skill/…/live-browser.js• L5204-5239 skill/…/live-browser.js• L6412-6479 skill/…/live-browser.js• L6481-6756 skill/…/live-browser.js• L9008-9261
Agent recovery
The status command reports the helper, active sessions, pending events, polling state, render failures, and staged copy-edit activity. The resume command turns the durable snapshot into the next safe action. It gives manual Apply work and mount failures priority because ignoring either can lose user edits or leave the page without a usable preview.
If the helper stops, start it again and poll. Startup restores unacknowledged journal events, removes stale temporary component sessions, recovers abandoned manual-apply transactions, and cleans old accept receipts. Temporary component data is removed only when the durable session record proves that the session is no longer active.
For visual builds, recovery also follows the open build gate. An open phase must close before later work starts. A bad or missing capture returns the work to recapture rather than allowing a partial review. A fix or rebuild produces new evidence before the finish result can be trusted.
References: plugin/…/live.md• L72-82 crates/…/live_status.rs• L23-127 crates/…/live_resume.rs• L176-231 crates/…/live_resume.rs• L268-356 crates/…/live_server.rs• L208-278 crates/…/apply.rs• L1228-1327 plugin/…/new-work.md• L105-118 plugin/…/finish-reviewer.md• L16-34
Manual copy edits
Browser copy edits use a separate staged buffer from visual variant sessions. The buffer groups edits by page and element reference. A later removal can supersede a staged text edit while retaining it for Undo, so discard of the removal restores the earlier copy edit.
Apply builds source evidence from the staged entries. It checks a source hint, then searches likely source files for literal text, object keys, element locators, and nearby context. Generated files are excluded from the search. The agent uses that evidence to change true source rather than browser output.
Apply sends bounded batches to the active chat agent, a selected local provider, or a deterministic test provider. Large batches split into ordered chunks. Each chunk must report complete entry ids; an entry with a failed or unreported operation is not treated as applied. Before source changes begin, Apply records affected files and their prior contents in a transaction. Validation checks syntax, data format, live markers, and optional project validation. A failure keeps the transaction available for repair or rollback.
Discarding staged copy edits removes them without writing source. A page-scoped Undo refuses while Apply owns that page's edits. This path is separate from visual variant discard, so one action cannot silently remove the other kind of work.
References: crates/…/buffer.rs• L9-25 crates/…/buffer.rs• L96-186 crates/…/evidence.rs• L189-248 crates/…/evidence.rs• L365-410 crates/…/apply.rs• L749-888 crates/…/apply.rs• L1002-1152 crates/…/apply.rs• L1168-1327 crates/…/apply.rs• L1482-1651 crates/…/copy_edit_agent.rs• L258-350 crates/…/live_server.rs• L1994-2744 crates/…/event_validation.rs• L178-249
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the
liveandgeneratecommand descriptions aligned with target selection, missing-context handling, live-bar behavior, and review behavior. - Keep captured target context, target signatures, selector match counts, source preparation, and the single-element bake guard aligned.
- Keep source search extension rules, generated-file detection, fallback errors, and deferred wrapper or insert writes aligned.
- Keep pending manual-edit page filtering, source hints, locator matching, and ambiguous-edit refusal aligned with source preparation.
- Keep browser event ordering aligned with session creation, checkpoint revisions, event leases, event identity, and terminal fences.
- Keep published variants, compiled variants, mounted variants, and mount failures as separate state when changing progressive delivery or recovery.
- Keep component manifest identity checks, compile rejection, retry behavior, persistent mount-error controls, and orphan handling aligned.
- Keep accept receipts, source locks, accept intent, optimistic browser teardown, late failure handling, carbonize cleanup, and completion verification aligned.
- Keep local session revisions, project identity, page identity, and server journal state aligned during reload and reconnect.
- Keep manual copy-edit staging, source evidence, apply chunks, transaction snapshots, provider routing, validation, repair decisions, and discard locks separate from visual variant sessions.
- Keep the code-led or comp-led choice aligned with the direction contract, comp approval record, build gates, and finish-review outcome.
- Keep the anti-pattern catalog, severity metadata, bundled detector, detector configuration, direct scan behavior, snapshot fallback, page-global isolation, shadow-tree coverage, and active stylesheet coverage aligned so a blocked detector never appears as a clean page.
- Keep helper injection, CSP permissions, ownership markers, and reversible cleanup aligned when changing browser startup or shutdown.
- Keep development-server candidate discovery, helper-token verification, caller-provided origins, and liveness checks aligned when changing the page-opening or browser-wait path.
- Keep Loop agent connection, MCP selection, wake hooks, taste consent, MCP-only setup, and disconnect cleanup aligned when changing the agent setup path.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| Several app roots match the target repository | Boot stops and returns candidates instead of choosing the wrong app | Select the app or pass an explicit target |
| No candidate development server serves the current helper token | Generate cannot identify the page to open | Pass the running origin, set the candidate list for unusual hosts, or start the app server before retrying |
| The recorded development server stops answering while generate waits | The command stops early instead of waiting for a page that cannot load | Restart the same app server, pass its origin again, and rerun the command |
| A page is outside the configured live file set | The page may load without the helper and boot reports drift | Review the drift report and update the live file configuration |
| Production or deployed content is used as a live target | Live injection is unsupported and can require unsafe browser policy changes | Use a local checkout for Live; use detection or the extension for production inspection |
| A page policy blocks the helper origin, WebAssembly evaluation, or local event connection | Injection or detector startup fails | Use the reversible local policy path or the supported snapshot or extension path |
| A target maps only to generated output | Automatic preparation refuses the unsafe edit | Resolve the true source range and use the agent-driven fallback |
| A target locator matches several source elements | Preparation cannot choose a lasting source range | Pass a stronger locator or let the agent inspect the reported candidates |
| Pending manual edits affect the selected block without a page URL or cannot be applied uniquely | Preflight stops instead of mixing stale and current copy | Pass the selected page URL and apply or discard staged edits first |
| A target claim arrives from a non-holder or after the target was resolved | The browser result is rejected and no second session is opened | Keep the target and result tied to the current client and target ids |
| A component manifest belongs to another session | The browser keeps generation active instead of mounting the wrong preview | Republish the manifest for the current session |
| A published component does not compile or mount | Publish is rejected or no usable variant appears | Fix the named preview, reply to the failure event, and retry |
| The detector core is blocked by page content security policy | Direct validation reports an unavailable core instead of findings | Use the supported snapshot or extension path |
| Accept leaves live markers or unbaked parameter values | Completion returns source_dirty and keeps the session unfinished | Finish carbonize cleanup before completion |
| Accept or discard finds a source lock | The source operation is not handled and the session cannot complete | Retry the same idempotent operation; do not hand-edit during the lock |
| Discard cannot find the original replacement content | The operation refuses to write because it could delete the user's element | Restore the original wrapper content by hand, then complete discard |
| The helper stops during generation | The browser disconnects while durable work remains pending | Run status or resume, restart the helper, and poll again |
| A delayed generation reply arrives after accept or discard | A late reply could affect the wrong lifecycle phase | Use event leases and terminal journal fences |
| A manual Apply result has malformed status or incomplete entry ids | Apply rejects the reply and leaves work pending | Return the canonical result shape with complete applied or failed entries |
| A manual Apply validation finds syntax damage or live markers | The transaction needs repair or rollback | Repair the current source or choose rollback; do not claim Apply completed |
| A comp-led session has no approved comp or valid capture | The build gate cannot close or the finish result becomes recapture | Record one approved option and capture the required viewports |
| The selected account service is not an allowed Impeccable account, or a test MCP URL is unusable | Connection stops without writing an MCP entry, so the agent remains unchanged | Unset the account override or use the matching secure account or local test URL |
| Loop finds a different MCP server under the expected name | Agent connection stops without replacing the person's server | Remove or rename the conflicting entry, then connect again |
| Loop hooks or taste files change during a failed connection | A partial connection can leave stale wake behavior or rule text | Use the journaled rollback and run status before retrying |
| Loop is running during an update and does not quit | The old app is not replaced | Quit the exact Loop app process and retry the update |
Key files
| File | Why to read it |
|---|---|
| plugin/…/live.md | Agent contract for boot, page opening, polling, variant delivery, acceptance, discard, completion, and recovery |
| crates/…/live_boot.rs | Boot flow from target resolution through context checks, helper start, injection, drift reporting, and page-first options |
| crates/…/roots.rs | App, repository, and context root selection that anchors later commands |
| crates/…/dev_url.rs | Development-server discovery, helper-token matching, and liveness checks |
| crates/…/live_generate.rs | Agent-led target selection and handoff into the standard generate event |
| crates/…/mod.rs | Framework detection order and adapter versus generic injection paths |
| crates/…/live_inject.rs | Injection, removal, project ignore protection, and artifact healing |
| crates/…/live_server.rs | Browser bridge, ordered request handling, polling, source reads, and reply routing |
| crates/…/server_state.rs | Event leases, target claims, progress checkpoints, and session coordination |
| crates/…/session.rs | Durable phases, checkpoints, render state, and terminal outcomes |
| crates/…/preflight.rs | Shared target contract, deferred source preparation, and fallback behavior |
| crates/…/live_wrap.rs and crates/…/live_insert.rs | Replacement and insertion preview paths |
| crates/…/live_accept.rs and crates/…/accept_verify.rs | Source promotion, receipts, locks, parameter baking, and the source-clean gate |
| crates/…/live_complete.rs | Durable completion after accept or discard |
| crates/…/live_status.rs and crates/…/live_resume.rs | Recovery state and next-action guidance after interruption |
| skill/…/live-browser.js | Browser flow from target selection through generation, review, accept, discard, mount failure, and reconnect |
| skill/…/live-browser-session.js | Browser session persistence, checkpoint revisions, and scroll recovery |
| crates/…/detect-antipatterns-browser.js | Browser quality scan, protected page probe, fallback paths, and explicit detector failure behavior |
| crates/…/loop_connect.rs | Optional Loop connection for agent MCP access, hooks, wake records, taste consent, MCP-only setup, and disconnect |
| crates/…/loop_install.rs | macOS-only verified Loop installation and update lifecycle |