@unotest/web 0.29.0 → 0.31.0

package/.claude/skills/write-e2e-test/SKILL.md

@@ -87,6 +87,15 @@ APP_BASE_URL) — same idea as run_test's per-call `env`.
 `explore_start` opens the browser itself. Do NOT call `new_context`
 first — it's for RESETTING the browser (Phase 5), not for starting.
 
+**Variables in steps.** In a value field (`fill` value, `press` key,
+`select_option` value, `goto` url) the bare NAME of a `.env`/`.secrets`
+variable is a reference: `value: "PASSWORD"` types the secret live and
+the saved test says `fill(loc, PASSWORD)`. In a locator's text or an
+assertion's text a bare NAME is the literal it looks like — to reference
+a variable there write `{{NAME}}` (`text: "{{GREETING}}"`); the reply
+warns when a literal equals a variable's name. Never type a secret's
+VALUE: it is recorded as the name anyway, and the reply says so.
+
 ### Phase 2 — first recorded step: navigate
 
 ```
@@ -418,7 +427,23 @@ Assertions:
 
 State reads:
 - `getTitle()`, `getUrl()`, `getAttribute(loc, name)`, `getInnerText(loc)`,
-  `getInputValue(loc)`.
+  `getInputValue(loc)`, `count(loc)`; `textContains(haystack, needle)`
+  for a substring probe on a string you already hold
+  (`assertTrue(textContains(out.stdout, 'ready'))`).
+- A `textarea` / `input` VALUE is not page text: `waitForText` and
+  `assertText` never see it. Check it with `assertValue(loc, expected)`
+  — it polls until the timeout (5 s by default, `{timeout}` to raise
+  it), so a value that fills in late is fine. For a substring of the
+  value there is no polling assert: read it in a loop —
+  `for (i = 0; i < 20; i = i + 1) { if (textContains(getInputValue(loc), 'x')) { break; } pause(200); // lint-ok: polling a textarea value }`
+  — then assert.
+- Only the vocabulary above is expression language. `!` is rejected by
+  the parser (`unotest-web lint`: `parse error — Invalid token`);
+  `JSON.stringify` / `Date.now()` / `indexOf` and other JS globals and
+  string methods are rejected by the validator with the replacement
+  named (`use json(value)`, `use nowMs()`, `use textContains(haystack,
+  needle)`). Express the check as an assertion or a locator
+  (`assertHidden`, `assertCount`, `.filter({hasText})`, `textContains`).
 
 Sandbox primitives:
 - `shell("cmd", "arg", …, options?)` — `execFile` style, no shell interpretation. Non-zero exit fails the step; pass `{allowNonZero: true}` to inspect `res.code` yourself. Wall-clock budget `{timeoutMs}` (default 120s).
@@ -433,8 +458,17 @@ Sandbox primitives:
   JSON — there is no key-name magic.
 
 Escape hatch:
-- `evaluate(\`js body\`, …args)` — raw backticks, no `${}`. Linter
+- `evaluate(\`js body\`, arg?)` — raw backticks, no `${}`. Linter
   warns `lint:evaluate-discouraged`. Use only when nothing above fits.
+  The body gets at most ONE argument — extra arguments reach it like
+  this: none → nothing, exactly one → the value itself, **with two or
+  more extra arguments the body receives ONE array** — destructure it:
+  `evaluate('function(n){ return n * 2 }', 21)` and
+  `evaluate('([a, b]) => a + b', a, b)`. The linter's warning says so
+  when it sees two or more.
+- Native dialogs (`confirm()` / `alert()` / `prompt()`) are accepted by
+  the runner itself (`dialogPolicy: "accept"` by default) — a "Remove"
+  that asks first needs no special step.
 
 Time helpers: `nowMs()`, `today()`, `daysFromNow(n)`. Marker helper: `randomWord(len)` — random lowercase letters, digit-free. Debug helper: `json(value)` — serialize any value for an assert message: `assertTrue(res.status == 202, json(res.body))`.
 
@@ -570,11 +604,23 @@ the old browser context, then `run_test` again.
 | `wait_for_url`     | `value` (the pattern)                   | `options`            |
 | `enter_frame`      | `locator`                               |                      |
 | `exit_frame`       |                                         |                      |
+| `screenshot`       |                                         | `name`, `fullPage`, `locator`, `outline`, `evidenceOnly` |
 
 When recording (`explorationId` present): `description` + `section`
 are required. Ad-hoc (no `explorationId`): no description/section,
 no recording.
 
+`screenshot` is the **evidence** step: it files a PNG under the session
+(`.unotest/explorations/<explorationId>/screenshots/<NNN>-<name>.png`,
+`adhoc/` without a session), replies with `{path, width, height}` and
+the image itself, and becomes `screenshot(name)` in the saved test.
+`name` defaults to the section slug; `locator` captures one element
+(the saved test degrades that to a page capture); `outline: true` adds
+the page outline to the reply; `evidenceOnly: true` keeps the file but
+records no step. `explore_stop` lists every file in `artifacts`. Take
+one wherever a human would want to check a green run after the fact —
+do not write throwaway scenarios just to get a picture.
+
 ## Failure modes you will hit
 
 - **`StaleRefError`** — ref no longer in the DOM. Re-`get_page_snapshot`
@@ -635,6 +681,11 @@ Every locator must resolve to exactly one element. When you see
   multi-matches.** Element order is brittle. Use `.filter({hasText:
   '…'})` or `.filter({has: someLocator})`. Linter flags index-based
   picking as `lint:disambig-by-index`.
+- **Don't assert "the first row of the list / audit".** On a shared
+  stand another run (or a person) writes rows between your steps. Give
+  your own data a unique marker (`randomWord()` in a name or note),
+  find your row by it (`.filter({hasText: marker})`), and remove what
+  you created at the end of the scenario.
 - **Don't reach for `locator(...)` with `>` combinators, hashed class
   names, or `xpath=…`.** Stop and ask the user whether the app should
   expose a `data-testid` or accessible name.

package/.claude/skills/write-e2e-test-ground/SKILL.md

@@ -112,6 +112,15 @@ APP_BASE_URL) — same idea as run_test's per-call `env`.
 `explore_start` opens the browser itself. Do NOT call `new_context`
 first — it's for RESETTING the browser (Phase 5), not for starting.
 
+**Variables in steps.** In a value field (`fill` value, `press` key,
+`select_option` value, `goto` url) the bare NAME of a `.env`/`.secrets`
+variable is a reference: `value: "PASSWORD"` types the secret live and
+the saved test says `fill(loc, PASSWORD)`. In a locator's text or an
+assertion's text a bare NAME is the literal it looks like — to reference
+a variable there write `{{NAME}}` (`text: "{{GREETING}}"`); the reply
+warns when a literal equals a variable's name. Never type a secret's
+VALUE: it is recorded as the name anyway, and the reply says so.
+
 ### Phase 2 — record the known steps as ONE batch
 
 **Batch-first default.** When the task brief already spells out the
@@ -549,7 +558,23 @@ Assertions:
 
 State reads:
 - `getTitle()`, `getUrl()`, `getAttribute(loc, name)`, `getInnerText(loc)`,
-  `getInputValue(loc)`.
+  `getInputValue(loc)`, `count(loc)`; `textContains(haystack, needle)`
+  for a substring probe on a string you already hold
+  (`assertTrue(textContains(out.stdout, 'ready'))`).
+- A `textarea` / `input` VALUE is not page text: `waitForText` and
+  `assertText` never see it. Check it with `assertValue(loc, expected)`
+  — it polls until the timeout (5 s by default, `{timeout}` to raise
+  it), so a value that fills in late is fine. For a substring of the
+  value there is no polling assert: read it in a loop —
+  `for (i = 0; i < 20; i = i + 1) { if (textContains(getInputValue(loc), 'x')) { break; } pause(200); // lint-ok: polling a textarea value }`
+  — then assert.
+- Only the vocabulary above is expression language. `!` is rejected by
+  the parser (`unotest-web lint`: `parse error — Invalid token`);
+  `JSON.stringify` / `Date.now()` / `indexOf` and other JS globals and
+  string methods are rejected by the validator with the replacement
+  named (`use json(value)`, `use nowMs()`, `use textContains(haystack,
+  needle)`). Express the check as an assertion or a locator
+  (`assertHidden`, `assertCount`, `.filter({hasText})`, `textContains`).
 
 Sandbox primitives:
 - `shell("cmd", "arg", …, options?)` — `execFile` style, no shell interpretation. Non-zero exit fails the step; pass `{allowNonZero: true}` to inspect `res.code` yourself. Wall-clock budget `{timeoutMs}` (default 120s).
@@ -564,8 +589,17 @@ Sandbox primitives:
   JSON — there is no key-name magic.
 
 Escape hatch:
-- `evaluate(\`js body\`, …args)` — raw backticks, no `${}`. Linter
+- `evaluate(\`js body\`, arg?)` — raw backticks, no `${}`. Linter
   warns `lint:evaluate-discouraged`. Use only when nothing above fits.
+  The body gets at most ONE argument — extra arguments reach it like
+  this: none → nothing, exactly one → the value itself, **with two or
+  more extra arguments the body receives ONE array** — destructure it:
+  `evaluate('function(n){ return n * 2 }', 21)` and
+  `evaluate('([a, b]) => a + b', a, b)`. The linter's warning says so
+  when it sees two or more.
+- Native dialogs (`confirm()` / `alert()` / `prompt()`) are accepted by
+  the runner itself (`dialogPolicy: "accept"` by default) — a "Remove"
+  that asks first needs no special step.
 
 Time helpers: `nowMs()`, `today()`, `daysFromNow(n)`. Marker helper: `randomWord(len)` — random lowercase letters, digit-free. Debug helper: `json(value)` — serialize any value for an assert message: `assertTrue(res.status == 202, json(res.body))`.
 
@@ -701,16 +735,31 @@ the old browser context, then `run_test` again.
 | `wait_for_url`     | `value` (the pattern)                   | `options`            |
 | `enter_frame`      | `locator`                               |                      |
 | `exit_frame`       |                                         |                      |
+| `screenshot`       |                                         | `name`, `fullPage`, `locator`, `outline`, `evidenceOnly` |
 
 When recording (`explorationId` present): `description` + `section`
 are required. Ad-hoc (no `explorationId`): no description/section,
 no recording.
 
+`screenshot` is the **evidence** step: it files a PNG under the session
+(`.unotest/explorations/<explorationId>/screenshots/<NNN>-<name>.png`,
+`adhoc/` without a session), replies with `{path, width, height}` and
+the image itself, and becomes `screenshot(name)` in the saved test.
+`name` defaults to the section slug; `locator` captures one element
+(the saved test degrades that to a page capture); `outline: true` adds
+the page outline to the reply; `evidenceOnly: true` keeps the file but
+records no step. `explore_stop` lists every file in `artifacts`. Take
+one wherever a human would want to check a green run after the fact —
+do not write throwaway scenarios just to get a picture.
+
 ## Failure modes you will hit
 
 - **`StaleRefError`** — a ref from an earlier lookup is no longer in
   the DOM. Intent locators don't go stale (grounded per call) — retry
   with the intent step, or re-ground via `ground_element`.
+- **Grounder unavailable** — `explore_start` or the first intent step
+  says so; intent locators are off for the session. Use
+  `find_element({role, name, near?})` and its ref instead.
 - **`RefResolveError`** — element has no stable identifier (testId /
   role+name / aria-label / placeholder / alt / title / text / href /
   stable id / name attribute). Best fix: ask the app team to add
@@ -769,6 +818,11 @@ Every locator must resolve to exactly one element. When you see
   multi-matches.** Element order is brittle. Use `.filter({hasText:
   '…'})` or `.filter({has: someLocator})`. Linter flags index-based
   picking as `lint:disambig-by-index`.
+- **Don't assert "the first row of the list / audit".** On a shared
+  stand another run (or a person) writes rows between your steps. Give
+  your own data a unique marker (`randomWord()` in a name or note),
+  find your row by it (`.filter({hasText: marker})`), and remove what
+  you created at the end of the scenario.
 - **Don't reach for `locator(...)` with `>` combinators, hashed class
   names, or `xpath=…`.** Stop and ask the user whether the app should
   expose a `data-testid` or accessible name.

package/CHANGELOG.md

@@ -1,5 +1,401 @@
 # Changelog
 
+## [0.31.0] - 2026-09-04
+
+### Minor Changes
+
+- b8e105b: New DSL function `note(label, value)`: attach a labelled value to the
+  current step — the question a data-driven case asked, the answer it got
+  — kept in the run journal and shown in the viewer under the step, during
+  and after the run. Any value: a string as it is, anything else as JSON;
+  cut at 4 KB (marked `truncated`), secrets masked. `log(...)` now also
+  lands in the journal under the step that wrote it (the stdout line
+  stays), and `assertJudge` verdicts carry the position of their statement,
+  so the viewer can show a verdict under its step and the whole verdict on
+  a failed step's error card. Each of these events records the DSL call's
+  `file` / `line` / `col` and the nearest entry-file statement
+  (`entryLine` / `entryCol`) — a note from inside a helper is attributed to
+  the entry step that called the helper. Without a run journal
+  (exploration, an ad-hoc runtime) `note` goes to the logger; nothing
+  fails.
+- 56784b3: `ExecutionWalker.run` takes a trailing `entryArgs` list and binds it by
+  position onto the entry function's parameters (missing ones `null`) in
+  the root scope before the body runs — what `explore_run_flow` needs to
+  replay a parameterised `flow_*` helper live.
+- 56784b3: `explore_run_flow` replays parameterised flows: pass `args` (positional
+  JSON values, `"{{NAME}}"` for a variable) and the helper's parameters are
+  bound for the live replay — `flow_login(username, password)` no longer
+  fails with `Variable "username" is not defined`. `explore_start` lists
+  each flow's `params`; a wrong argument count is refused with the
+  signature. The recording keeps variable NAMES, so the saved test reads
+  `flow_login(LOGIN, PASSWORD);` — `flow_call` is now a regular action
+  plugin rendering the call with its arguments.
+- 307582f: New `explore_step` action `screenshot` — the evidence step of an
+  exploration. It files a PNG under the session
+  (`.unotest/explorations/<explorationId>/screenshots/<NNN>-<name>.png`,
+  `adhoc/` without a session), replies with the absolute `path`, `width`
+  and `height`, and returns the image itself as an MCP image block (a JPEG
+  copy when the PNG is over 1 MiB; path only when both are). `name`
+  defaults to the section slug, `fullPage` captures the whole page,
+  `locator` captures one element, `outline: true` adds the page outline
+  to the reply, `evidenceOnly: true` keeps the file but records no step.
+  A recorded screenshot becomes `screenshot(name)` in the saved test; an
+  element capture degrades to a page capture with a comment and a
+  non-blocking `DEGRADED_STEP` warning. `explore_stop` now lists the
+  session's files in `artifacts`. Driver: `DriverPage.screenshotElement`.
+- 6b61884: New linter rule `lint:external-variable-undeclared` (default `error`): a
+  bare `UPPER_SNAKE` identifier that no layer file declares — `unotest/.env`,
+  `unotest/.secrets`, or the `.env.<name>` / `.secrets.<name>` overlay of
+  the environment `lint --env <name>` / `UNOTEST_ENV` selects — is reported
+  with the files searched, instead of failing at that statement at run time
+  after the browser is up. A name bound in the file (assigned, a parameter,
+  a loop counter) is never flagged. The shell is not a declaration: a value
+  CI exports still needs its name in `unotest/.env` (`NAME=` with no value
+  declares it; the shell's value wins at run time, as before). As an error
+  it is not silenced by `// lint-ok:`; downgrade it in `linter.rules` if a
+  project needs that.
+
+  `run_test` (MCP) and `e2e` run the same check before the browser starts,
+  against what the run will actually resolve — files and the ambient shell
+  — so a suite that lives on a shell variable keeps running; a name that
+  would have failed in the scenario anyway now fails up front (`run_test`
+  answers `lint_failed`; `e2e` prints it and proceeds, like every pre-run
+  diagnostic).
+
+  The linter also descends into operator, array and property-access
+  operands now, so a regex or `{{mustache}}` literal inside `a + b` is
+  diagnosed the same as one on its own.
+
+- eddb1db: New linter rule `lint:one-test-per-file`: a second (third, …) top-level
+  `function test_*` in one scenario file is reported at its declaration.
+  A file is the unit a collection runs and the viewer shows — the Steps
+  tree projects a run onto the first `test_*`, so the others executed with
+  nowhere to be seen. Fold the cases into one test with tagged steps
+  (`step("…", {tag: id}, () => { … })`, `step.soft` when a case must not
+  stop the run) or move shared journeys into `flow_*` helpers under
+  `unotest/e2e/_helpers/`; `flow_*` functions in a scenario file are not
+  counted.
+
+  **Migration window:** the rule is a **warning** in 0.31 — visible in
+  `lint`, the editor and `run_test`'s warnings, silenced per line with
+  `// lint-ok: <reason>`, never blocking. A later minor release flips the
+  default to `error` (which the pre-run gate of `run_test` refuses); split
+  files that hold several `test_*` before then.
+
+- b0a00cb: New DSL function `readJsonLine(path, filter) → object`: read a JSONL file
+  that already exists and return the first line matching the key filter —
+  no polling. `waitForJsonLine` was the only structured input into a
+  scenario, and for a fixture or a finished export its 20s timeout only
+  masked a wrong path. `readJsonLine` takes the same filter (strict equality
+  per key, dot paths for nesting, unparsable lines skipped) and fails at
+  once: `file not found: <path>` when the file is missing, `no line matches
+{…} in <path>` with parse stats and the closest line when nothing matches.
+  Data-driven tests read their cases with it and name evidence after them
+  (`screenshot(q.id)`).
+- 100ab9d: Data-driven steps: `step("label", {tag: q.id}, () => { … })` names the
+  case an iteration is on, and `step.soft("label", [{tag}], () => { … })`
+  records a failure inside instead of stopping the run — the rest of that
+  body is skipped, the next case runs, and the test still ends **failed**
+  with every soft failure listed (`3 soft step(s) failed: Question [q17]:
+…`, one line per case in the CLI output; `run_test` answers
+  `next.softFailures`; `inspect_runtime`'s `lastFailure` carries `stepTag`
+  and `soft`). The failure bundle shows the page at the moment of the
+  **first** soft failure, with `soft: true` and `stepTag` in
+  `failure.json`; later soft failures live in the journal. `step.soft` is
+  allowed inside `test_*` only; nesting is free, and the outer step is a
+  group, not an assertion — a soft failure inside does not change its
+  outcome. The run journal gains `step-block:started` / `step-block:finished`
+  envelopes per block (label, tag, soft, outcome, whole-block duration).
+  Editor typings declare the new forms.
+- ad7c918: The run journal records every loop pass (`loop:iteration`, with the loop
+  statement's position and the pass index), which the viewer's new Trace
+  view uses to show a loop as one group per iteration. Also: when an error
+  unwinds through enclosing statements, `lastFailure` (the failure bundle's
+  position, `inspect_runtime`, the CLI's `in step "…" [tag]` line) now
+  names the innermost statement that raised it — the assert inside the
+  tagged step — instead of the outermost loop that re-threw it.
+
+### Patch Changes
+
+- 9ae6d59: A bundle no longer declares the runner's own `UNOTEST_*` settings
+  (`UNOTEST_HEADED`, `UNOTEST_LOG_LEVEL`, …) from the suite's `.env`, so a box
+  stops warning on every push that an environment "neither sets nor holds"
+  names `env push` never sends. Both sides now share one rule
+  (`isRunnerSetting` in `@unotest/protocol`): those variables configure the
+  machine a run happens on, not the suite. A per-suite value such as the
+  navigation timeout travels with the bundle through `unotest.config.mjs`
+  (`defaultNavigationTimeoutMs`), not through `.env`.
+- 917380d: `unotest.config.*` is merged with the defaults recursively. A partially
+  written section — `linter: { rules: { 'lint:deep-css': 'off' } }`,
+  `failureBundle: { tier3: { video: true } }`, `viewport: { width: 1920 }`
+  — now keeps the rest of that section's defaults instead of failing with
+  "config validation failed" (nested sections require all of their fields
+  at validation time, so a top-level replace made every partial section
+  invalid). Arrays and scalars still replace as a whole: `browsers:
+['firefox']` means firefox only. The setup manual's example config,
+  which was exactly such a partial `linter`, loads as written; its
+  `timeouts` block — never a config field — is corrected to
+  `defaultTimeoutMs` / `defaultNavigationTimeoutMs`.
+- e048334: The viewer's editor flags an undeclared external variable
+  (`lint:external-variable-undeclared`), the way `unotest-web lint` and the
+  pre-run lint already do: a bare `UPPER_SNAKE` identifier that no
+  `unotest/.env` / `.secrets` file of the active environment declares is an
+  error in the editor, naming the files searched. Protocol:
+  `DslValidateContext` gains `externalNames` / `externalSources`; the
+  viewer supplies them from the active target + environment's layer files
+  (the same files the variables panel shows) and `@unotest/web`'s language
+  service turns them into the linter's lookup.
+- dcf4c9e: Viewer editor: lint markers appear as soon as a file opens (or the page
+  reloads), not only after the first keystroke — the editor validates the
+  source it mounted with instead of waiting for a change event that a
+  reopened tab never fires.
+- 6646584: Docs: `hover` now lists its options (`force`, `position`, `timeout`) in
+  the DSL reference, the editor signature and the generated typings — it
+  used to read as if it took none, while `position` is exactly what a
+  hover-revealed menu at one edge of a tall element needs. The agent
+  integration guide gains "Watching a collection run": the collection's
+  `steps.jsonl` journal (path, the four `collection-run:*` events, how to
+  tail it) as the progress source for a run started in the background,
+  where the CLI's per-scenario lines only arrive when the process ends.
+- 630d6ce: `unotest-web lint` now receives its arguments: the bin dispatcher forwarded
+  only the command name, so `lint --env <name>` linted the base environment
+  and an explicit file argument was ignored (every file was linted instead).
+  `UNOTEST_ENV=<name>` worked all along, which is why the gap went unnoticed.
+- f3bd3cc: `lint` works on a project that has not migrated to the 0.28 layout yet.
+  A `unotest.config.*` still at the project root used to stop `lint` with
+  the same refusal `e2e` gives — right for a command that would RUN on
+  defaults, wrong for one that only grades: nobody lints a suite during
+  the very migration that touches every file. `lint` now builds its
+  context on the default settings (rule severities, helpers dir), reads
+  `unotest/.env`, `.secrets` and `_helpers/` as usual, and reports the
+  layout once as the new `lint:legacy-layout` warning (default `warn`,
+  configurable like any rule) with the migration on one line. The exit
+  code is unaffected by it. `e2e`, `collection` and `bundle push` refuse
+  exactly as before.
+- 224d016: The MCP server says when it is running a stale build. `run_test`'s
+  pre-spawn lint, flow discovery (`explore_start`), `explore_run_flow`,
+  `generate_dsl_from_exploration` and `save_exploration_as_test` parse and
+  render DSL in the server's own process, on the modules it loaded at
+  start — after a rebuild a new DSL feature came back as a false parse
+  error until the server was restarted, while the runner child was already
+  on the new build. Those replies now carry `serverStale: true` and a
+  `serverStaleWarning` ("restart the MCP server") once the code on disk is
+  newer than the server's start; nothing changes while it is fresh.
+- 02757c3: `serverStale` now also rides on `explore_step` / `explore_steps` (locator
+  resolution and recording run in the server's process), `find_element`
+  and `ground_element` replies — the same flag `run_test` and the
+  exploration tools already carry once the build on disk is newer than the
+  running MCP server.
+- dcf4c9e: `goto` with a relative path resolves against the runtime's own base URL
+  instead of the browser context's. In a CLI run the two coincide; in an
+  exploration recording against an `env` override, `explore_run_flow`
+  replayed `goto('/_guard/')` on the MCP session's shared context — created
+  with the server's base — and landed on the wrong host. The replay now
+  follows the session's `baseUrl` (and its variables, as before).
+- f3bd3cc: `screenshot(name)` accepts any string value, not only a literal. The
+  runtime always slugified whatever it received, but the validator (and
+  therefore `lint` and `run_test`) rejected `screenshot(q.id)` and
+  `screenshot(textJoin(['q-', id]))` — a data-driven test had to name every
+  capture the same. The `name` slot is now string-like, as in `fill`; a
+  non-string argument is still an `arg-kind` error.
+- dcf4c9e: A section label reopened after another section is called out instead of
+  silently splitting a step: `explore_step` / `explore_steps` reply with
+  `sectionHint` the moment it happens, and the generated draft carries a
+  non-blocking `SPLIT_SECTION` warning naming the reopened entries. The
+  recorded order of actions is never changed; `autoRun` and `save` are not
+  held back by it.
+- 9ae6d59: A scenario that finished in the same instant the viewer looked at it is no
+  longer recorded as `interrupted` with a finish an hour before its start.
+  The runner ends a run by appending `run:finished` and then backdating the
+  heartbeat; the viewer read those two files in the opposite order, so a
+  steps snapshot taken a few milliseconds early could meet the backdated
+  heartbeat, and the provisional verdict stuck in the run index while the
+  collection reported the scenario passed. The heartbeat is read first now.
+  A viewer restart (which rebuilds the index from disk) already corrected
+  such records; runs indexed live are right the first time.
+- 13a2d51: Viewer, Home tab: the tile of a scenario that is running now breathes
+  through colour and shadow only — the scale pulse is gone. It moved the
+  tile's box every frame, so an automation driver never saw the tile as
+  stable and a click on it waited out its timeout. A tile that never ran
+  no longer carries `data-age="fresh"`: it has no age, so the attribute is
+  absent.
+- 91fb562: Viewer, Home tab: clicking a scenario tile opens the scenario's LAST RUN —
+  the run whose verdict the tile's colour is showing — instead of the test
+  file. A tile that has never run still opens the test (there is no run to
+  open), and so does every tile in schedule mode, where the schedule is
+  edited from the test. The legend now reads "hover for history · click to
+  open the last run".
+- dcf4c9e: Viewer, Home tab: the tile field no longer refits itself in a loop. The
+  header and legend take the grid's width; when the legend wrapped at one
+  width and not at the next, the field's height changed, the fit followed,
+  the width changed back — at 60 fps every tile's box moved every frame,
+  and an automation click on ANY tile ("element is not stable") waited out
+  its timeout unless forced. Header and legend now never wrap (they grow
+  past the grid instead), so the fit converges and tiles stay put. A run
+  opened from a tile is titled by its scenario, like one opened from the
+  Runs tree, instead of by its run id.
+- dcf4c9e: Recording no longer bakes relative time or counters into a locator. An
+  accessible name such as `Run smoke — passed, 7m ago`, `just now`,
+  `yesterday`, `5 passed`, `7 runs` or a trailing badge (`Inbox · 3`,
+  `Errors: 12`) now counts as volatile: the recorder emits the stable prefix
+  (`{name: "Run smoke — passed", exact: true}`, then `/^Run smoke — passed\b/`)
+  instead of the literal, and the draft carries the `DYNAMIC_TEXT` warning
+  with that prefix. Bare numbers elsewhere stay stable (`Page 2`, `Q4 2026`,
+  `v2`, `2FA`).
+- Updated dependencies [b8e105b]
+- Updated dependencies [b8e105b]
+- Updated dependencies [b8e105b]
+- Updated dependencies [9ae6d59]
+- Updated dependencies [56784b3]
+- Updated dependencies [e048334]
+- Updated dependencies [dcf4c9e]
+- Updated dependencies [100ab9d]
+- Updated dependencies [100ab9d]
+- Updated dependencies [100ab9d]
+- Updated dependencies [100ab9d]
+- Updated dependencies [ad7c918]
+- Updated dependencies [ad7c918]
+- Updated dependencies [ad7c918]
+- Updated dependencies [9ae6d59]
+- Updated dependencies [13a2d51]
+- Updated dependencies [91fb562]
+- Updated dependencies [dcf4c9e]
+  - @unotest/core@0.31.0
+  - @unotest/protocol@0.31.0
+  - @unotest/viewer@0.31.0
+  - @unotest/dsl@0.31.0
+  - @unotest/grounder-client@0.31.0
+
+## [0.30.0] - 2026-09-03
+
+### Minor Changes
+
+- 23de03c: On a hosted viewer (a box), the project and environment you are looking at
+  are now named and switched in the viewer's own tree header, in place of
+  the checkout directory it used to show there (`current`, which told
+  nobody anything). Previously the only way to another environment was
+  logging out and using the picker page. The chevrons appear on hover, like
+  the refresh button beside them, and only when something fronts the viewer
+  and offers it a list; a plain local viewer keeps the folder name it
+  always showed. Because
+  each environment on a box is its own viewer process, picking one is a full
+  page load into that viewer, and the menu shows which test bundle each
+  environment is running. The status bar's `.env.<name>` overlay switcher is
+  now labelled "env overlay", so the two senses of "environment" no longer
+  share a name. `@unotest/viewer/session` carries the two URLs this needs
+  (`environmentsUrl`, `switchEnvUrl`) and the `ViewerEnvOption` type, both
+  optional — a proxy that does not offer them gets the old behaviour.
+
+### Patch Changes
+
+- A run started in the first moments after the viewer boots is now discovered: the run watcher finishes its initial scan of the day directory before reporting itself started, instead of filing such a run as history.
+- 3f5cab7: `bundle push` and `env push` no longer send you to "the box's
+  admin page" for a project token — there is no such page; tokens are
+  issued per project by the box's operator, and the refusal hints and the
+  missing-token message now say so.
+- 3f5cab7: The vocabulary's description of `evaluate` now says how extra
+  arguments reach the body — none → nothing, exactly one → the value
+  itself, two or more → one array — matching the runtime, the linter's
+  hint and the authoring skill; it used to read as if they were positional
+  (`evaluate(js, ...args)`), and so did the generated DSL typings.
+- 3f5cab7: A scenario that answers a native `confirm()` — a "Remove" button that
+  asks first, say — no longer fails when `run_test` auto-attaches the MCP
+  session to the run's browser, or after `attach_debug_session`. The
+  attaching client now applies the same dialog policy the run does
+  (`dialogPolicy`, accept by default) to the page it watches; before, it
+  listened for no dialogs at all, and Playwright dismisses every dialog on
+  behalf of a client that has no listener — so the second pair of eyes was
+  answering "no" before the run's own accept could land. The same scenario
+  passed with an exploration session open only because that session
+  happened to keep the run's browser to itself. Under `manual` the attached
+  client leaves the dialog to whoever handles it instead of dismissing it.
+- 9f2e244: On a box, an administrator can now see a secret's value from the guard's
+  values page — the eye reveals it in the row, the copy button puts it on
+  the clipboard without showing it — and every look is a `secret.revealed`
+  entry in the box's audit trail, naming who, which secret and whether it
+  was shown or copied. The page is one table now (target, variables,
+  secrets), edited in place, with a JSON view that changes the whole
+  environment at once; a secret left as `"••••"` there is kept as it is.
+  The token door `env push` / `env set` talk to is unchanged: secrets stay
+  write-only on the wire.
+
+  `@unotest/protocol` carries the contract: `boxEnvSecretRevealPath` /
+  `boxEnvSecretsRevealPath` with their response parsers, the session-door
+  batch `BoxEnvValuesReplaceRequest` (`null` for a secret means "keep") and
+  `parseBoxEnvValuesReplaceRequest`, and the refusal code `unknown-secret`
+  for a reveal or a keep that names a secret the environment does not
+  hold. `isEnvVarName` now refuses `__proto__`: it is spelled like a
+  variable, but a plain object cannot hold it and the value was silently
+  lost. The CLI explains an `unknown-secret` refusal.
+
+- 3f5cab7: `evaluate(js, …args)` has always handed the body its extra arguments in
+  one of three shapes — none, the single value, or ONE array for two or
+  more — while the authoring skill described them as positional. The
+  skill now states the rule with both spellings
+  (`evaluate('function(n){…}', 21)` / `evaluate('([a, b]) => …', a, b)`),
+  and the `lint:evaluate-discouraged` warning adds the same hint when it
+  sees two or more extra arguments; the runtime is unchanged. The skill
+  also gains the getters it left out (`count`, `getInputValue`,
+  `textContains`), the note that `waitForText` never sees a textarea's
+  value, the parser's refusal of `!` / `indexOf` / string methods, the
+  shared-stand rule against "the first row" (mark your own data, filter
+  by it, clean up), that native dialogs are accepted by the runner, and
+  what to do when the grounder is unavailable.
+- 3f5cab7: While recording with `explore_step` / `explore_steps`, the bare NAME of a
+  scenario variable is substituted only where the step types a value into
+  the page — `fill`'s value, `press`'s key, `select_option`'s value,
+  `goto`'s url. In a locator's text or an assertion's expected text a bare
+  name is now the literal it looks like: `assertText(el, "BOX_LAB_PASSWORD")`
+  expects those letters, where before the live step silently waited for
+  the secret's value and the saved test said something else. To reference
+  a variable in a matcher, write `{{NAME}}`; the reply warns when a literal
+  happens to equal a variable's name. And a secret's value typed into a
+  value field is recorded as the secret's name (the reply says which), so
+  the value never lands in the test file.
+- 3f5cab7: `run_test` no longer reports `spawn_failed` about a runner that is still
+  starting. Two runs launched together on a busy box took longer than the
+  fixed 10-second wait to write their first `runtime.json`, and the second
+  was declared dead while it was booting a browser. The wait now lasts as
+  long as the runner child is alive (up to 60 seconds), ends early when the
+  child joins the run queue, and — when the child really dies — says so with
+  its exit code and the last lines of its stderr, which the runner now
+  writes to `spawn.stderr.log` in its run directory.
+
+  `explore_start` now reports whether the grounder is usable for the
+  session: `grounder: {available: true}`, or `{available: false, reason,
+hint}` when grounding is off, the backend is unreachable, or a required
+  model is not pulled (`"embeddinggemma" is not available there — pull it:
+\`ollama pull embeddinggemma\``). An intent step in such a session fails
+  with the same words, not with the backend's raw error; the probe is one
+  short request per session.
+
+  Secret masking no longer rewrites the runner's own identifiers in
+  `runtime.json`: with `LOGIN=admin`, the scenario path `guard-admin.js`,
+  the test function `test_guard_admin` and the run id kept their names in
+  `inspect_runtime` replies instead of turning into `guard-‹secret:LOGIN›.js`.
+  Masking by value is unchanged everywhere else; the run id, scenario
+  path, test function and call-stack names are an explicit exception.
+
+- 3f5cab7: `save_exploration_as_test` (and `generate_dsl_from_exploration`) now
+  write scoped locators — a `getByRole` / `getByText` / `locator(css)` step
+  under a parent, such as the "Reveal" button inside one table row — as
+  the chain the DSL already runs:
+  `locator('tr[data-row="A"]').getByRole('button', {name: 'Reveal', exact: true})`.
+  Before, any recorded step whose locator went below its root was skipped
+  with `NO_DSL_PRIMITIVE`, and the save was refused, although the step
+  had executed and the hand-written form worked. Every locator is now
+  rendered in the same method-chain spelling — narrowing steps too
+  (`getByRole('row').filter({hasText: 'Alice'}).first()` instead of
+  `first(filter(getByRole('row'), {hasText: 'Alice'}))`); both spellings
+  remain valid input, the runtime is unchanged.
+- Updated dependencies [23de03c]
+- Updated dependencies [9f2e244]
+  - @unotest/viewer@0.30.0
+  - @unotest/protocol@0.30.0
+  - @unotest/core@0.30.0
+  - @unotest/dsl@0.30.0
+  - @unotest/grounder-client@0.30.0
+
 ## [0.29.0] - 2026-09-02
 
 ### Minor Changes

package/bin/unotest-web.js

@@ -75,7 +75,9 @@ function dispatch(sub) {
         forwardArgs: args.slice(1),
       };
     case "lint":
-      return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: ["lint"] };
+      // Forwarded whole, like e2e: `--env <name>` and explicit file
+      // arguments belong to the command, not to the dispatcher.
+      return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: args };
     case "viewer":
       return { dist: "dist/runner/cli.js", src: "src/runner/cli.ts", forwardArgs: ["viewer"] };
     case "prepare-fix":