stack/packages/webui/README.md

Mosaic Console

Piece 4, #1507. The control board is the first and only WebUI screen.

Run

Start the existing board in one terminal, then the WebUI in another:

node packages/control-board/src/cli.mjs serve
node packages/webui/src/cli.mjs serve

Open http://127.0.0.1:7330/. Optional --port N and --board http://127.0.0.1:7331 select another port or loopback board origin. Port 0 picks a free port. Ctrl-C stops each foreground server. No daemon, installation, account, authentication or deployment is added.

Only HTTP loopback board origins are accepted. The WebUI binds to IPv4 loopback by default, rejects nonlocal Host and cross-origin requests, sends no CORS headers, refuses redirects and accepts only JSON object POST bodies up to 4096 bytes. Do not expose either unauthenticated server through a public proxy.

Use

• Waiting on you uses the board's waitingOnYou flag across all projects.
• Select a project on the left to filter the session table. Counts show visible rows out of the total when Hide offline or Hide seen hides anything.
• Select an agent to open its inspector. Arrow keys move between table agent buttons, Enter opens, and Close or Escape in the inspector returns focus.
• Seen clears the row from Waiting on you until the board detects new activity. The collapsed Seen section keeps those rows available; Unsee returns them.
• Reply appears only where the board's registration permits it. A failure shows the board's stderr and keeps the draft. Transport success is the board's delivered receipt, not proof that the seat processed the message.
• Refresh runs the existing board scan. Automatic refresh uses the board page's ten-second interval; Pause stops it. Failed refreshes keep the last snapshot with a warning. There are no automatic action retries.
• Palette and appearance use the existing brand tokens and persist in this browser when local storage is available. No settings screen is added.

Drafts and receipts stay in page memory, including across refresh, inspector changes and a stale registration. Reloading or closing the page loses them. A pending send stays disabled across refresh; new text typed during a send is not cleared by the earlier send's success. If the proxy loses the response, delivery may be unknown: inspect the seat before sending again.

Data and boundaries

GET /api/board and POST /api/seen and /api/reply proxy only the existing board paths. POST bytes and upstream status/JSON are preserved. GET /api/config returns the configured board URL for the page's error message. No scanner, registration, session reader or transport is implemented here. No control-board, seat, fleet, comms or root package files are changed.

Console's shared CSS, Console CSS, brand.js and local Manrope fonts were copied unchanged from agents/dewey/work/wui/. Font license and source URLs accompany the files under src/public/assets/fonts/. live.css contains the live-page adaptations; original mockups and unrelated pending design work stay untouched. Unsupported mockup fields and controls are listed in docs/plans/DEFERRED.md. The source tree is a project filter; no invented workspace registration tree or mockup session hierarchy is presented as live data.

Verify

node --test packages/webui/tests/
node --test packages/control-board/tests/ packages/seat/tests/ packages/ledger/tests/ packages/mosaic/tests/
WEBUI_EVIDENCE=/tmp/webui-evidence node --test packages/webui/tests/browser.test.mjs

Node's test runner and installed /usr/bin/chromium are required. Set CHROMIUM to another installed Chromium path. No npm download is needed. The copied CDP helper starts a separate temporary browser profile and removes it on exit. Tests use temporary board session/registration files and stub the board's transport. They never send to real seats or read real session logs.

Browser tests exercise the rendered real board fixture, exact counts, project filtering, keyboard return focus, Seen/Unsee, success/failure receipts, draft and caret preservation, pending-send exclusion, storage denial, stale registration, loading/empty/malformed/unreachable states and hostile text. Contrast is measured on 330 rendered samples across ten palettes and three modes. Layouts are checked at 320, 390, 768, 1440 and 2560px. Horizontal scrolling is intentional within the dense table; the page itself must not overflow.

No root CI workflow is configured for this package. These local tests are not a claim of CI, deployment, live-seat delivery or user acceptance.

User test and rollback

Gate E belongs to Jason on Monday 2026-09-14. Use Console to find who is waiting, open a registered repo seat, reply and see its next answer after a scan. Mark a completion Seen and find it again in Seen. Record any reason to open the board's own page or a repo seat terminal in DEFERRED.md. Pass is Jason's end-of-day say-so, not a test result. Keep #1507 open pending that ruling.

Rollback requires only stopping the WebUI and using the unchanged board at 7331. Revert the scoped WebUI commit to remove it; there is no data migration to undo. Seen and reply actions already taken belong to the board and are not rolled back.