UI canvas workspace
The UI Canvas is a browser workspace for reviewing and shaping a self-contained HTML mockup before an agent builds the approved design into the real component. It joins direct visual edits, viewport checks, inspector controls, and agent chat into one session while keeping the final markup and edit record available for handoff.
Workspace purpose
The workspace lets a person change a component where it is rendered instead of describing every visual change in text. The agent supplies the mockup, the browser records the person's changes, and the final export becomes the visual contract for the production implementation.
The workspace supports two related activities:
- Edit mode changes the mockup through selection, text editing, movement, resizing, removal, and style controls.
- Interact mode sends clicks and other normal interactions to the mockup so the person can check behavior without changing its structure.
The canvas is local and session-based. It is intended for one browser, one agent, and one HTML artifact at a time.
Command and session lifecycle
Command entry
The ecc-ui-canvas command opens or resumes an HTML mockup and then waits for browser feedback. The command is a thin UI-specific layer over the shared Plan Canvas session service; its main difference is that it asks for UI edits and final markup rather than plan annotations. commands/ui-canvas.md describes the agent-facing flow, while scripts/ui-canvas.js selects the UI session mode and viewport options.
When the command starts a session, it can choose a mobile, desktop, or exact-size viewport. The agent normally keeps await running in the background so chat, Apply to file, and Save and Finish can reach the same session without a new browser launch.
References: commands/ui-canvas.md• L7-30 scripts/ui-canvas.js• L24-52 scripts/ui-canvas.js• L56-74
Session server
The shared loopback server is the meeting point for the browser and the agent. It serves the canvas shell, serves the mockup inside a sandboxed frame, watches the artifact for agent writes, stores queued feedback, and exposes a long-poll wait for the agent. Server-sent events keep the browser current with chat, presence, reloads, and acknowledgments.
The session store makes feedback durable across a server restart. A session is tied to the canonical artifact path, and its short key lets the browser and the agent refer to the same work without passing the file path through every browser request.
References: scripts/…/server.js• L237-291 scripts/…/server.js• L394-414 scripts/…/server.js• L672-701 scripts/…/sessions.js• L48-60 scripts/…/sessions.js• L108-182
Browser shell
The shell surrounds the mockup with the controls needed for review. It shows the viewport, edit or interact mode, agent presence, undo and redo, animation pause, reload, the inspector, the edit log, and the conversation panel. The mockup keeps its real CSS pixel size; the shell scales it down only when the stage is too small.
The shell keeps temporary edits and view state in browser session storage. A reload therefore refreshes the artifact without losing the person's unsent work or the current review context.
References: scripts/…/ui.js• L4-15 scripts/…/ui.js• L79-103 scripts/…/ui.js• L122-206 scripts/…/ui.js• L646-753
Editor and inspector model
Mockup editing
The editor runs inside the sandboxed mockup frame and reports changes to the shell through postMessage. It adds a selection overlay without changing the exported design. A person can select an element, edit its text, resize it, reorder it, nudge it, change a supported style, or remove it.
Each action becomes a structured edit tied to a selector and the mockup revision from which the action came. This gives the shell an edit log that can be undone, replayed after an agent reload, shown to the agent, and exported with the final markup.
References: scripts/…/editor.js• L5-16 scripts/…/editor.js• L142-167 scripts/…/editor.js• L298-335 scripts/…/editor.js• L374-430 scripts/…/editor.js• L450-482
Selection and element identity
The selected element is described by its selector, tag, classes, text or asset snippet, size, editability, and breadcrumb path. The selector is the link between what the person sees and what the agent must reproduce in the file.
The editor prefers a unique ID. Otherwise it uses a positional path that is safe only for the source revision that produced it. A replay can proceed only when the selector resolves to exactly one element. This prevents a later file rewrite from silently applying a visual change to the wrong element.
References: scripts/…/editor.js• L123-167 scripts/…/editor.js• L244-265 scripts/…/editor.js• L493-546
Inspector fields
The inspector turns the selected element's computed style into grouped controls. It shows size, fill, text, spacing, border, and effects as applicable to the selected element. Each field can expose a slider, a typed value, a color control, a clear action, or a read-only value when the property is not safe to change there.
The inspector has two value paths. Sliders provide quick visual changes. Typed values provide exact control and pass through the same field rules before they reach the frame. The inspector uses the browser's computed style for display but records only the inline change needed to represent the person's choice.
References: scripts/…/inspector.js• L7-14 scripts/…/inspector.js• L135-195 scripts/…/inspector.js• L198-239 scripts/…/inspector.js• L508-546
Field value model
Field helpers define the accepted value model for numbers, box values, colors, and free CSS text. Numeric values have allowed units and bounds. Ratios accept forms such as 50% and normalize them to a value from zero to one. Box values accept a bounded number of parts, and colors keep an exact RGB value alongside an HSL view for readable editing.
Free CSS values are limited to one safe declaration value. The field rejects declaration breakers, markup, comments, script URLs, and similar text before the browser checks whether the property accepts the value.
References: scripts/…/fields.js• L31-63 scripts/…/fields.js• L65-81 scripts/…/fields.js• L88-120 scripts/…/fields.js• L159-170
Viewport and review modes
Viewport model
The workspace checks the mockup at three kinds of viewport: desktop fills the stage, mobile uses a device-sized frame, and custom uses an exact width and height. A custom viewport can also be rotated. The frame uses CSS pixels, so responsive rules run as they would in a normal browser view.
The selected viewport travels with Apply and Finish. It tells the agent which view informed the exported design, but it does not replace the HTML or the edit record.
References: scripts/…/feedback.js• L22-42 scripts/…/ui.js• L122-166 scripts/…/ui.js• L177-205
Review modes
Edit mode captures selection and design actions. Interact mode turns off the editing overlay and lets component clicks, hovers, and taps reach the mockup. The mode switch gives the reviewer a way to test behavior without confusing a component interaction with a design edit.
The editor can also pause animations and transitions. This makes a moving state stable while the reviewer inspects it, without adding a design change to the edit log.
References: scripts/…/ui.js• L208-226 scripts/…/editor.js• L729-780 scripts/…/ui.js• L353-358
Feedback and delivery lifecycle
Chat feedback
Chat is the lightweight path for a request that still needs the agent to decide how to change the mockup. A message can include the selected element as an anchor and short summaries of unsent edits. These summaries provide context only; the agent must not treat them as edits to apply.
The agent signals that it is thinking or typing, edits the mockup file, and replies in the canvas. The file watcher then reloads the frame, while the shell restores the person's pending edits on top of the new file.
References: scripts/…/ui.js• L360-417 scripts/…/ui.js• L440-463 scripts/ui-canvas.js• L75-103 scripts/…/server.js• L265-290
Apply delivery
Apply to file sends the current hand edits and a clean HTML snapshot to the server. The server writes the snapshot and normalized edit log beside the mockup before it queues feedback for the agent. The agent reads that export, rewrites the self-contained mockup, and acknowledges only the batches it actually incorporated.
Each Apply batch has its own export pair. This keeps an older queued batch pointing to the exact snapshot the reviewer saw, even if a later Apply creates a newer snapshot.
References: scripts/…/ui.js• L479-517 scripts/…/server-routes.js• L73-105 scripts/…/feedback.js• L262-314 scripts/ui-canvas.js• L86-97
Finish handoff
Save and Finish freezes the review, exports the final markup and edit log, and ends the session after the server accepts the delivery. The agent then reads the exported files and ports the approved visual result into the real component with full product behavior. The canvas does not generate framework code or reopen itself after the handoff.
If the browser cannot confirm the delivery, it keeps the exact snapshot in session storage and makes the review read-only until the same delivery is retried. This avoids sending a changed snapshot under the identity of the first attempt.
References: scripts/…/ui.js• L469-535 scripts/…/delivery.js• L6-49 scripts/…/server.js• L572-621 scripts/ui-canvas.js• L79-84
Batch acknowledgment
Delivery means that the server accepted a feedback item. Acknowledgment means that the agent proved the corresponding changes are in the mockup file. The distinction lets the browser keep applied work visible until the agent's rewrite is known to contain it.
The server can acknowledge a named batch through an agent reply or recognize an exact file snapshot by its hash. It can also record older batches represented by that exact snapshot. An unrelated file save does not acknowledge queued UI work.
References: scripts/…/sessions.js• L198-249 scripts/…/server.js• L376-391 scripts/…/server.js• L604-620 scripts/…/server.js• L672-684
Validation contracts
Feedback contract
The server treats browser feedback as untrusted input. It accepts only chat, edits, and finish items. Edit records use an allow-list of text, resize, move, nudge, remove, and style operations. Text, selectors, markup, style values, dimensions, edit counts, and HTML snapshots have size or range limits.
The server stores the HTML snapshot outside the session queue and sends the agent only its path. This keeps the queue small and gives the agent a stable file to inspect while the normalized edit log preserves the review record.
References: scripts/…/feedback.js• L22-42 scripts/…/feedback.js• L106-185 scripts/…/feedback.js• L227-259 scripts/…/server-routes.js• L76-114
Replay contract
Replay restores edits in order after the agent changes the mockup. Submitted batches are atomic: if one target cannot be resolved safely, none of that batch is applied and its edits remain visible as unresolved. Unique IDs and document roots can survive a new revision; positional selectors require the captured source revision.
An unresolved submitted edit blocks another Apply or Finish until the agent resolves the mismatch. Reset removes unsent edits but keeps unresolved submitted changes so the review does not hide a delivery problem.
References: scripts/…/editor.js• L162-167 scripts/…/editor.js• L493-540 scripts/…/ui.js• L300-315 scripts/…/server-routes.js• L31-65
Delivery contract
Apply and Finish first preserve an immutable snapshot in browser session storage. A delivery token binds that snapshot to its kind and content hash. A retry with the same token can return the original receipt, while a changed payload is rejected.
Only accepted edit IDs are retired from the browser's pending log. Later edits remain separate, and an uncertain Finish stays read-only until the server confirms the original handoff.
References: scripts/…/delivery.js• L14-48 scripts/…/ui.js• L495-533 scripts/…/server.js• L576-592 scripts/…/sessions.js• L223-226
Related pages
- Operator control plane and readiness — parent context for operator-facing control and readiness.
- Control plane views and agent proximity — related view and presence concepts.
Change checklist
When these files or sections are changed, remember to consider these:
- Keep the UI command profile, the session mode, and the server's UI route selection aligned.
- Keep edit kinds and field value rules aligned between browser recording, server normalization, export validation, and replay.
- Preserve the distinction between delivered, acknowledged, and unresolved batches when changing reload or feedback behavior.
- Keep export naming, snapshot hashes, delivery receipts, and browser retry state compatible.
- Keep viewport values consistent between command options, session storage, browser controls, and feedback payloads.
Important failure modes
| Trigger | Consequence | Guard |
|---|---|---|
| The agent rewrites an element so a positional selector no longer identifies one target | The submitted batch becomes unresolved and Apply or Finish is blocked | Replay requires a unique target and the original source revision for positional selectors |
| The browser submits malformed or oversized HTML or edit data | The feedback is rejected and no export is queued | The server normalizes allow-listed fields and enforces size and range limits |
| A delivery response is lost after the server accepts it | A retry could duplicate feedback or replace the wrong export | The browser stores an immutable snapshot and the server checks the delivery token fingerprint |
| The agent saves a file without incorporating an Apply batch | The browser keeps the batch pending instead of hiding it | Acknowledgment requires a matching batch ID or exact exported snapshot |
| The user ends a session without saving | The agent must not reopen the review without permission | User-ended sessions refuse a plain reopen and report the end state |
Key files
| File | Why to read it |
|---|---|
| commands/ui-canvas.md | Defines the agent-facing command flow and handoff behavior |
| scripts/ui-canvas.js | Shows how the command selects UI mode and guides the agent after feedback |
| scripts/…/ui.js | Explains the browser shell, viewport controls, conversation, and delivery actions |
| scripts/…/editor.js | Defines the in-frame editing model, edit records, replay, and export snapshot |
| scripts/…/inspector.js | Defines the selection inspector and its property groups |
| scripts/…/fields.js | Defines accepted and normalized field values |
| scripts/…/feedback.js | Defines feedback, edit, viewport, and export contracts |
| scripts/…/delivery.js | Defines retry-safe browser delivery state |
| scripts/…/server-routes.js | Connects UI assets and exports to the shared server |
| scripts/…/server.js | Shows the shared session transport, presence, reload, and API lifecycle |
| scripts/…/sessions.js | Shows durable session state, queue delivery, and batch acknowledgment |