Introducing a new way to review your PRs.

Read the announcement

affaan-m / ecc

The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.

View on GitHub

30 documents · Updated Nov 20, 2026

docs / ui-canvas-workspace

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

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

TriggerConsequenceGuard
The agent rewrites an element so a positional selector no longer identifies one targetThe submitted batch becomes unresolved and Apply or Finish is blockedReplay requires a unique target and the original source revision for positional selectors
The browser submits malformed or oversized HTML or edit dataThe feedback is rejected and no export is queuedThe server normalizes allow-listed fields and enforces size and range limits
A delivery response is lost after the server accepts itA retry could duplicate feedback or replace the wrong exportThe browser stores an immutable snapshot and the server checks the delivery token fingerprint
The agent saves a file without incorporating an Apply batchThe browser keeps the batch pending instead of hiding itAcknowledgment requires a matching batch ID or exact exported snapshot
The user ends a session without savingThe agent must not reopen the review without permissionUser-ended sessions refuse a plain reopen and report the end state

Key files

FileWhy to read it
commands/ui-canvas.mdDefines the agent-facing command flow and handoff behavior
scripts/ui-canvas.jsShows how the command selects UI mode and guides the agent after feedback
scripts/…/ui.jsExplains the browser shell, viewport controls, conversation, and delivery actions
scripts/…/editor.jsDefines the in-frame editing model, edit records, replay, and export snapshot
scripts/…/inspector.jsDefines the selection inspector and its property groups
scripts/…/fields.jsDefines accepted and normalized field values
scripts/…/feedback.jsDefines feedback, edit, viewport, and export contracts
scripts/…/delivery.jsDefines retry-safe browser delivery state
scripts/…/server-routes.jsConnects UI assets and exports to the shared server
scripts/…/server.jsShows the shared session transport, presence, reload, and API lifecycle
scripts/…/sessions.jsShows durable session state, queue delivery, and batch acknowledgment