see-your-output

Files (1)

• SKILL.md

SKILL.md (first lines)

# Patching the UI, and seeing what you did

You cannot see the screen, so a UI change is unverifiable by reading code. Saying
"done" after editing `ui/` is a guess. This is how to turn it into evidence — and how
to patch the UI without interrupting the person using it.

## 0. The rule that comes first: a UI patch never stops a run

The UI is a **view of a durable ledger**, not the thing that owns the work. That is the
whole reason a patch can be safe: the transcript lives in the node's database, the
run executes in the node's interpreter, and the window is a renderer that can be
replaced at any moment. So:

- **Patch by deploying files.** The node reads `ui/` per request. Copy the changed
  files into the directory the window is served from (`app.js`, `style.css`,
  `index.html` — whatever changed) and the running window picks them up. CSS is
  swapped in place; JS is deferred until the run in flight finishes, and then
  reloads itself. Both halves already work: do not invent a mechanism.
- **Never restart the node to patch the UI.** A restart kills the interpreter and
  therefore kills whatever run the person is having. That is not a side effect to
  accept; it is the failure this section exists to prevent. It has happened: a node
  was restarted to install a *binary* while somebody was mid-conversation, and their
  run died with the process.
- A restart is only required for a **Rust** change — a new route, a changed host
  function. That is a different kind of work with a different cost, so: prefer a
  path that needs no restart (Lua routes already exist; extend one if it fits),
  and when a restart is genuinely needed, say so and let the human choose the
  moment between runs.

Two consequences worth stating, because both come up:

- **Anything the window holds that the ledger does not is a bug waiting to be a lost
  run.** After a reload the transcript comes back from the ledger, but tokens still
  arriving for a run that started before the reload do not: the node streams to the
  request that opened it. "Repaint and resume" means the window reattaches to the
  run in flight and replays what it missed. Until that exists, a reload during a run
  loses its partial text — so if you must reload *while* a run is in flight, prefer waiting.
- **A patch that only adds a topic or a control changes the UI, not the node.** Ship
  it the same way.

## 1. Find out which UI the window is actually reading

This is the most common way to do everything right and see nothing:

```bash
# what the node was started with, and whether the served bytes are yours
ps -eo pid,args | grep -E "[s]erve --port"          # look for --ui <dir>
curl -s http://127.0.0.1:8799/app.js | grep -c 'the string you just added'
curl -s -m 5 http://127.0.0.1:8799/version           # changes when the files do
```

A node started with `--ui %LOCALAPPDATA%\wasm-agent\ui` serves the **installed** copy,
not your checkout. Editing the repository changes nothing that window reads. Deploy to
the served directory, then confirm with the `grep` above — and read the version to see
that the change is live. If the version does not move, the window will not reload.

## 2. Assert the DOM in a real browser, headlessly

`scripts/test-ui.ps1` is this technique, already written: it copies `ui/` to a temp
directory, stubs the HTTP layer with `ui/test-fixtures.js`, injects a probe that
replays a synthetic run, and asserts structure. Run it before and after a change:

```bash
powershell -NoProfile -ExecutionPolicy Bypass -File scripts/test-ui.ps1
```

It prints one verdict line. Add your claim as a `check(...)` beside the others.
First run the focused disposable-browser probe; only after it passes run the
required UI suite once. Do not launch the broader suite alongside a probe still
known to fail, or repeat read/discovery/graph work that already established the fix.

Rules that save time, all of them learned the hard way:

- **Prove your assertion can fail.** A check that never runs and a check that passes
  look identical. Break it on purpose once (flip the condition), watch the harness
  report `FAIL`, and put it back.
- **Run the probe synchronously.** Headless virtual time does not reliably advance, so
  anything that waits on a timer or a real async callback never completes — an
  `await` on a callback that never fires hangs the *entire* harness and the verdict
  line simply never appears. `tick()` (a resolved promise) drains microtasks; use it.
  Anything needing a real async step (image decoding) cannot be checked here.
- **No escape sequences in the injected script.** One stray `\n` inside a string is a
  syntax error that kills the block silently: the page renders normally and the probe
  never runs. Write it without escapes and check it with `node --check` first.
- **An empty result is not evidence.** If the verdict element is missing, your
  instrument is broken, not the app.
- Fixtures are matched by **path exactly** (`url.includes("me")` also matches
  `node/name`), so add a stub for any new endpoint you read.

## 3. Screenshot it, and look at the image

Inside the disposable Linux coding benchmark image, `wa-ui-observe` serves a
staged copy of `/work/ui`, injects `test-fixtures.js`, and writes `dom.html` and
`screenshot.png` from real headless Chromium. Pass `--probe /path/to/probe.js`
to run a task-specific check; the probe must write a `pre#wa-probe` with
`data-status="pass"` or `data-status="fail"`. The command fails if Chromium or
the probe fails. Use `--out /trace/ui-observation` to retain only the evidence.
`wa-ui-contracts --base HEAD` reports classes, custom elements, and custom
events removed by the patch. Review each reported removal against callers and
CSS; a clean result does not prove behavior. These commands are available to
benchmark agents without revealing the hidden oracle.

**The same command runs on this host, against *your* worktree, and you can read the
picture.** Chrome is installed here, so from your checkout:

```bash
node scripts/agent-benchmark-ui-observe.mjs --out "$TEMP/ui-look"   # ./ui by default
```

It serves a copy of your `ui/` with `test-fixtures.js` injected, never touches the
node or the installed UI directory, and exits non-zero unless the page really
rendered and the probe passed. `--ui <dir>` picks another tree, `--chrome <path>`
another browser, `--require <text>` pins a DOM marker, `--probe <file>` asserts.
**A child agent can see the screenshot**: `read screenshot.png` returns it as visual
input - a blind test (Chrome rendered a random word and number, read back exactly)
confirmed it. So "open the PNG and look" is an instruction that works.

Structure is not appearance: spacing, wrapping, contrast and overflow are only
visible. A screenshot is also the only way to catch that the window is running a

From Magaav/wasm-agent, MIT.

More from Magaav/wasm-agent