llm action-selection backend (#68)

* feat(spec): add llm() action-backend marker

* feat(spec): make llm marker inert on the JS picker

* feat(spec): expose __sanderlingSampleInput__ corpus draw

* feat(openrouter): minimal chat-completions client

* test(openrouter): cover request shape, parse, and errors

* feat(verifier): thread screenshot + capture corpus sampler

* feat(verifier): LLM accessors — candidates, config, sampler

* test(verifier): cover AllCandidates, LLMConfig, SampleInput

* feat(trace): record action Source and LLMReasoning

* feat(runner): thread step screenshot into PushSnapshot

* feat(runner): llmSource selects actions via OpenRouter

* feat(runner): wire llmSource selection and trace stamping

* test(runner): cover llmSource selection, mapping, downscale

* docs(folio): add llm action-backend example spec

* docs(folio): document the LLM action backend run

* feat(llmclient): support OPENAI_API_KEY, openrouter wins

* refactor(runner): rename openrouter package to llmclient

* docs: both api keys, example model gpt-5.4-nano

* docs: add pr style rules to claude.md

* fix(runner): explain action kinds in llm prompt to stop swipe loops

* feat(trace): record llm ranked list and chosen rank

* feat(runner): stamp llm ranked list and chosen rank on trace

* fix(runner): tap by selector to survive layout shift after observe

* revert(runner): drop selector-first tap; broke path/testTag selectors

* feat(spec): llm() accepts optional instructions

* feat(verifier): read llm instructions off config

* feat(runner): append spec instructions to llm system prompt

* docs(folio): describe app in llm spec instructions

* feat(bundler): map generator export to globalThis.generator

* feat(verifier): read llm config off globalThis.generator

* feat(runner): gate llm source on --generator flag

* feat(cmd): add --generator llm|seeded flag

* test: cover --generator flag parsing and pickSources gating

* feat(verifier): enumerate llm candidates by walking actionsRoot

collect-walk the weighted action tree: recurse weighted branches
accumulating selection probability, call authored leaves once for
concrete actions, enumerate builtins per element. label controls by
visible text (borrowing descendant text), fold gestures into directional
scrolls over scrollable containers, drop disabled, dedup descriptions.

* test(verifier): cover candidate enumeration walk

* feat(verifier): add SetupAction to walk setup without the seeded root

* test(verifier): cover SetupAction setup-only precedence

* refactor(llmclient): make JSONSchema.Schema raw json for pinned field order

* feat(trace): record llm choice number and chosen_action echo

* feat(runner): llm picks one number from weighted candidates

drop the seeded-root call for a setup-only precedence path, render a
numbered weighted candidate list, pin a reasoning-first choice schema,
strict-skip when chosen_action does not echo the numbered entry, and let
the model supply typed values (corpus fallback when empty).

* test(runner): cover choice schema, strict-skip, and setup precedence

* refactor(verifier): drop the superseded AllCandidates enumeration

* feat(folio): drive spec.ts under --generator llm; drop spec-llm.ts

* fix(verifier): label editable fields by hint, not the typed value

an editable field's own text is its transient content; prefer the hint
so the field is named by purpose and the label stays stable.

* test(runner): cover weight-suffixed echo and stripWeightSuffix

* fix(runner): accept chosen_action echo that carries the weight suffix

real runs showed the model copies the whole numbered line including the
trailing (w34) weight annotation, so strict-skip rejected ~91% of picks
and the llm was paralyzed. strip the weight suffix before comparing. also
nudge the prompt to stress-test repeated submissions (idempotency).

* fix(verifier): skip llm enumeration on cross-fade frames

a navhost mid-transition carries >1 route *Screen in a collapsed
coordinate space; acting on it taps garbage (soft keyboard). real runs
showed the llm acting on 44% of steps being such frames. skip them so the
llm re-observes a settled frame next step.

* feat(folio): show current balance on the add-transaction screen

renders the account's balance (testTag TxnCurrentBalance) below the
account name, above the credit/debit toggle, so before/after screenshots
carry comparison data.

* fix(replay): derive device space from screen extent, not first node

the first positive-bounds element is often a short status-bar node
(320x24 on android); using it gave a 320/24 aspect ratio that squashed
the screenshot overlay into a grey horizontal band. use the max extent
across elements (like the runner's screenBounds) instead.

* fix(folio): show balance as a compact one-line label

per review: one line, account-name-sized, e.g. "Balance: $0.00"
instead of a large balance card.

* fix(folio): move balance into the header, one compact line under the account name

* fix(replay): attribute deferred violations to the causing step, not detection

* fix(replay): show a step's own violations in both panels, no next-step bleed

* refactor(hierarchy): one Tree.Transitional, drop the duplicated cross-fade check

* chore: ignore .playwright-mcp scratch output

* docs: document the llm generator and --generator flag

* docs(spec): correct the llm() comment; config reads off globalThis.generator

* docs: add pr description rules

internal/verifier/worker.go

@@ -28,6 +28,17 @@ type Verifier struct {
 	// the shared picker (pick.ts) over the shared Pcg.
 	nextActionFn goja.Callable
 
+	// setupActionFn is the bundle-installed __sanderlingSetupAction__, which
+	// walks ONLY the setup generator. The LLM action generator runs it for setup
+	// precedence (e.g. login) without triggering the seeded action root.
+	setupActionFn goja.Callable
+
+	// sampleInputFn is the bundle-installed __sanderlingSampleInput__, which
+	// draws one value from the shared INPUT_CORPUS. The LLM action backend uses
+	// it to fill InputText values, reusing the exact corpus draw rather than
+	// reimplementing the corpus on the Go side.
+	sampleInputFn goja.Callable
+
 	evaluators map[string]*ltl.Evaluator
 
 	priorVerdicts map[string]ltl.Verdict
@@ -35,6 +46,7 @@ type Verifier struct {
 	witnesses     map[string]Witness
 
 	lastTree       *hierarchy.Tree
+	lastScreenshot []byte
 	scopeCache     map[*hierarchy.Element]bool
 	scopeCacheTree *hierarchy.Tree
 	lastAction     *Action
@@ -151,6 +163,20 @@ func (v *Verifier) Load(source string) error {
 			v.nextActionFn = callable
 		}
 	}
+	if fn := v.runtime.GlobalObject().Get("__sanderlingSetupAction__"); fn != nil {
+		if callable, ok := goja.AssertFunction(fn); ok {
+			v.setupActionFn = callable
+		}
+	}
+
+	// __sanderlingSampleInput__ draws an InputText value from the shared corpus.
+	// The LLM action backend uses it; a raw-JS fixture without the runtime entry
+	// leaves it nil and SampleInput reports an error.
+	if fn := v.runtime.GlobalObject().Get("__sanderlingSampleInput__"); fn != nil {
+		if callable, ok := goja.AssertFunction(fn); ok {
+			v.sampleInputFn = callable
+		}
+	}
 
 	return nil
 }
@@ -258,6 +284,7 @@ func (v *Verifier) buildFormulaNode(index int) (ltl.Formula, error) {
 // allowed and yields an empty ax scope.
 func (v *Verifier) PushSnapshot(input SnapshotInput) error {
 	v.lastTree = input.Tree
+	v.lastScreenshot = input.ScreenshotPNG
 	v.scopeCache = nil
 	v.lastAction = input.LastAction
 	v.lastLogs = input.Logs
@@ -386,9 +413,13 @@ func (v *Verifier) OverrideExtractorValues(overrides map[int]json.RawMessage) (s
 // other than Snapshots are optional; callers that only have snapshots can
 // populate Snapshots alone and leave the rest zero.
 type SnapshotInput struct {
-	Snapshots  Snapshots
-	Tree       *hierarchy.Tree
-	LastAction *Action
+	Snapshots Snapshots
+	Tree      *hierarchy.Tree
+	// ScreenshotPNG is the step's screenshot, captured alongside Tree. The LLM
+	// action backend reads it via Screenshot() to select a candidate; other
+	// callers may leave it nil.
+	ScreenshotPNG []byte
+	LastAction    *Action
 	StepTime   time.Time
 	// StepIndex is the runner's step number for this snapshot. Evaluators label
 	// observations with it so violation witnesses carry runner step numbers even
@@ -575,6 +606,28 @@ func (v *Verifier) NextAction() (Action, error) {
 	return DecodeAction(raw)
 }
 
+// SetupAction walks ONLY the setup generator (globalThis.setup), returning its
+// action or ErrNoAction. The LLM action generator runs this for setup
+// precedence (e.g. login) without triggering the seeded action root, which it
+// replaces entirely. Mirrors NextAction's decode.
+func (v *Verifier) SetupAction() (Action, error) {
+	if v.setupActionFn == nil {
+		return Action{}, ErrNoAction
+	}
+	value, err := v.setupActionFn(goja.Undefined())
+	if err != nil {
+		return Action{}, fmt.Errorf("setup action: %w", err)
+	}
+	if value == nil || goja.IsNull(value) || goja.IsUndefined(value) {
+		return Action{}, ErrNoAction
+	}
+	raw, err := json.Marshal(value.Export())
+	if err != nil {
+		return Action{}, fmt.Errorf("marshal action: %w", err)
+	}
+	return DecodeAction(raw)
+}
+
 var ErrNoAction = errors.New("verifier: no action available")
 
 func (v *Verifier) formulaThunk(index int) func() (bool, error) {