# Flow Debugger — method pane takes structured parameters (Gitea #37)

**Date:** 2026-09-10 · **Status:** approved (issue-authored spec) · **Issue:** #37

## Problem

The Flow Debugger's *Run inbound API method* pane rendered one single-line text box per
top-level schema field and coerced the text by declared type. For `object` / `array` fields it
tried `JsonNode.Parse` on the raw text and, on failure, **sent the text as a string**; an empty
box was silently omitted. A required array-of-object parameter (MesMoveOut `WorkOrders`,
`[{WorkOrderNumber, PartNumber}]`) could not be entered from the page at all — the QA run
reached the site with `"WorkOrders":[]` and the receiver rejected it with a misleading error.
The same payload ran fine through `flow-debug run-method --params`, so only the UI input
surface was at fault. The *Run site script* pane on the same page already uses the shared
`ParameterValueForm` (typed inputs, nested groups, add/remove list editors, `$ref:lib:`
resolution, inline validation, Monaco escape hatch for unresolved shapes).

## Design

1. **The method pane renders `ParameterValueForm`** driven by the method's
   `ParameterDefinitions`, keyed on the method id so a change of method remounts the form (the
   same reason the script pane keys on the script's canonical name). The page holds a
   `_methodParams` value tree + `_methodParamsValid`; `BuildParameters()` serializes the tree
   as-is, exactly like `BuildScriptParameters()`. The flat `_inputs` / `Coerce()` / `SetInput`
   path is deleted — a failed parse can no longer be sent as a string, and there is no
   type-specific coercion left on the page.
2. **Whole-payload raw-JSON escape hatch.** The Inputs card gains a *Form | Raw JSON* toggle.
   Raw mode is a Monaco `json` editor given the method's root schema (the form's
   `ToJsonSchema` made `internal static`) so completion and hover work. Every edit parses the
   text and validates it with `InboundApiSchema.Validate` against the resolved root schema
   (`ParseWithRefs` + `ISchemaLibraryQueryService`, the same resolution the form does); errors
   render inline under the editor. Switching Form → Raw seeds the editor from the current value
   tree (indented); Raw → Form loads the last *valid* tree into the form. The value tree is the
   single source of truth in both modes.
3. **Run gating.** `CanRun` for the method entry is `method chosen && (no parameters ||
   params valid)`, mirroring `_scriptParamsValid`. A required field left empty disables Run
   (the form reports validity on mount, so this holds before the first keystroke).
4. **Persistence.** The per-method `localStorage` entry (`flowDebugger.inputs.<id>`) now stores
   the value tree as JSON. On restore the tree is converted back (the form's
   `JsonElementToObject` made `internal static`) and validated against the schema; an invalid
   tree is discarded. That also retires the old flat `Dictionary<string,string>` entries without
   a version flag: legacy strings that still validate (string fields) are kept, anything else is
   dropped.
5. **Not changed:** the runner (`FlowDebugRunMethodCommand`), the CLI, prediction, Replay, the
   script pane. No wire, proto or schema change.

## Tests

- bUnit (`FlowDebuggerPageTests`): an array-of-object field (the `WorkOrders` shape)
  round-trips from the list item editors to the `RunMethodAsync` payload; invalid raw JSON
  blocks Run and shows the error; valid raw JSON sends exactly that payload; a required scalar
  left empty disables Run until filled; switching methods resets the form and its validity.
- Playwright `FlowDebuggerTests`: the smoke selector moves from `flow-input-Text` to the
  form's `#param-Text`.

## Docs

`Component-CentralUI.md` (Flow Debugger entry points), CLAUDE.md Flow Debugger bullet, this
design doc.