feat(quoter-bot): make playground previews readable

[thomas-chabert]

What

The quoter-bot playground rendered every amount as a raw integer and drew rates on two unrelated plot styles. This makes it readable, and the audit behind it corrected several descriptions that misstated the runtime.

Readable amounts. One decimals box scales the whole page. A process has a single LOAN_ASSET_ADDRESS and every configured amount is a raw smallest-unit amount of that one asset, so one scale is both sufficient and correct — collateral decimals never apply. Defaults to 6 for USDC, clears to exact raw integers, and every scaled amount keeps its raw value on hover.

Both plots are order books. A vertical rate axis with the bounds labelled above and below, and one row per offer carrying its rate, a depth bar and its size. The ladder reads as price-level depth; bootstrap shows the single offer it publishes, sized against its credit target.

Tiles anchored on the editor vocabulary, each printing the config keys it derives from. Tiles with no keys are fixed runtime behaviour, which makes the distinction visible. Two editor labels contradicted their own help text and were corrected: offerSize was "Pending-offer cap" though it bounds one offer, and acceptanceAssets was "Completion threshold" though it is the shortfall.

Four ladder descriptions were wrong and are now derived from the code:

	Was	Actually
sizeSkewBps	flat outer-vs-inner difference	compounds per step off a 10,000 BPS base
minimumOfferAssets	"small rungs are dropped"	an underfunded side drops its outermost rungs
exposure caps	bound the market	bound the lending side only (aggregateBudget feeds higherBudget)
movementToleranceBps	suppresses republishing	gates recentring; a resize still happens inside it

Each entry reports the reference band it tolerates, swept from the config through the runtime's own generateLadderWithDiagnostics. This answers what a single deterministic preview cannot, since the synthetic reference always lands mid-bounds — for a ladder spanning its full half-range that is the one rate at which no rung pins.

An out-of-range derived reference no longer suppresses the preview. It renders with markers pinned to the axis plus a notice, because on the variable strategy that state is an artefact of the synthetic reference, not an invalid config — exports stayed valid throughout. A shape the shared parser genuinely rejects still cannot be drawn, so its message now restates the runtime's own sideWidth * 2 > range inequality with the operator's numbers.

Config safety

Every change is display-only, with one deliberate exception: autoRefill now defaults to true for new bootstrap entries.

Verified by running this branch and main side by side over the same configs (variable and hardcoded strategies, shared-rung and per-book, with and without a maturity premium):

SAME  exportBootstrapJson          SAME  encodePlaygroundFragment
SAME  BOOTSTRAP_MARKETS            SAME  createPlaygroundShareUrl (with query)
SAME  exportLadderJson             SAME  new code decodes main fragment
SAME  LADDER_MARKETS               SAME  main code decodes new fragment
SAME  parseCollectionsImport ×2    SAME  maturity premium fragment
SAME  validatePlaygroundState      SAME  validateBootstrapCollection
SAME  validateLadderCollection     SAME  createDefaultLadder
DIFFERS createDefaultBootstrap  →  autoRefill false → true (intended)

16/17 identical, fragments compatible in both directions. Structurally, the JSON scanner, import parsing, fragment codec, all four exports and validation have zero changed lines.

Review round

Devin and Codex both reviewed c9abed7; every posted finding was verified against the code and fixed in bf2ff8e and fd6f98f. All 11 threads resolved.

• Reference bands reported sampled edges as exact. A stride above one BPS is reachable once the swept interval passes the sample cap, so a 0–20000 BPS range reported 19999 as its boundary. The sweep now walks outward one BPS from each sampled edge — one stride per side at most, exact at any range.
• A maturity premium made both bands wrong. Bootstrap ignored the premium, ladder pinned maturity at zero, so a band shown as general held only at maturity. Both callouts now say so.
• The ladder notice covered only the reference, leaving a premium-pushed centre visibly pinned with no explanation. It now names every marker the view can clamp.
• A hardcoded target was described as market-following across a band it can never traverse.
• Raw amounts were promised but not delivered outside the ladder table. Bootstrap and ladder plot amounts and rung hover text now carry them; the promise is scoped to plots and tables, since callout prose stays scaled-only.
• acceptanceAssets equal to creditTarget makes the runtime complete immediately and publish nothing, while the tile claimed one offer would fill it.
• autoRefill: false claimed it stops for good, though completion lives in an in-memory set a restart discards.
• Utility isolation: rung rendering helpers moved out of the module holding ErrorBoundary into playground/rung-rendering.utils.tsx.

Config output stayed byte-identical to main throughout, re-verified across the hardcoded strategy, per-book grouping and a zero accepted-credit target. Four new tests cover the copy corrections.

Three further Devin findings are hidden by repository review settings and are not visible through the API — they remain unaddressed and can be seen in Devin Review.

Checks

• tsc --noEmit clean; oxlint 0 warnings / 0 errors across 599 files; oxfmt clean; knip reports no unused playground exports
• vitest run — 2597 passed, 11 skipped. 14 test files fail to collect (unbuilt @repo/contracts in three other bots, plus two fork e2e tests needing a Base RPC); the identical 14 fail on origin/main, diff empty
• check-jsdoc flags 482 items repo-wide, none in playground/
• 73 playground tests, including two new suites for the amount formatter and the reference sweep

Not verified locally

Local Node is 24.5.0 against the pinned ^24.14.1, so installs and runs used --config.engine-strict=false.

playground:smoke:test cannot run on macOS at all — both the wrapper and the smoke script call assertProcessInspection, which refuses on any non-Linux platform ("Definitive descendant cleanup requires Linux /proc process inspection"). CI is therefore the only place it executes, and its first run here caught a stale assertion: the runtime-preview parity scenario expected two preview errors for a runtime-valid collection whose synthetic reference leaves the plotted range, which is exactly the suppression this branch removes. That assertion now requires zero errors, two notices and both plots rendered — the property it was written to protect. Fixed in e5a7601; all checks green.

Two other selectors the suite depends on were updated with the behaviour change: the ladder centre marker label is now Quote, and .ladder-reference-marker is scoped to [data-preview="ladder"] since bootstrap now has one too.

🤖 Generated with Claude Code

[devin-ai-integration]

Devin Review found 4 potential issues.

3 flags not posted on this PR by your GitHub settings — view them in Devin Review. (Configure)

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: c9abed7e23

ℹ️ About Codex in GitHub

Codex has been enabled to automatically review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

When you sign up for Codex through ChatGPT, Codex can also answer questions or update the PR, like "@codex address that feedback".