Standout Builder Studio · planning Index / Flow / 05 · Iteration Loop draft Updated 12 Jun 2026

Proposal 05 · Iteration Loop

This proposal covers pipeline step 7 — Iterate. Today build versions exist only as mock rows in builderMockData.ts with no config diff between builds, no validation delta, and no session history per version. A builder who wants to understand what changed between two sandbox runs — or why a validation check that passed in one version now fails — has nowhere to look. This stub captures the problem, sketches one wireframe, and lists the open questions that must be resolved before a full proposal can be written.

1 Choose build path 2 Define the game package 3 Configure mechanics 4 Attach assets & theme 5 Run validation 6 Generate playable sandbox 7 Iterate 8 Promote toward handoff
Draft stub — structure and problem statement only.
Copy the full-depth anatomy of Proposal 01 / Proposal 04 when writing this proposal.

User problem

The versions arrays in apps/web/src/lib/builderMockData.ts represent a build history as an ordered list of version objects with id, number, and createdAt, but each version record carries no config snapshot, no validation run results, and no attached sandbox session identifiers. A builder who runs two sandbox sessions on the same build and gets different outcomes has no in-tool mechanism to trace the difference back to a config change.

The workspace in apps/web/src/components/builder/GameWorkspace.tsx renders version history as a list but provides no comparison mode — the builder cannot select two versions and see a side-by-side diff of their config values or validation outcomes. There is also no concept of a regression: if a validation check that passed in version 3 fails in version 4 due to a config change, the builder must manually reconstruct what changed by inspecting both versions' configs separately, and there is no tooling to surface this automatically.

Proposed UI

The workspace gains a version timeline with per-version status chips (validation result, sandbox run count) and a compare drawer that opens when two versions are selected, showing a config diff and a validation delta side by side.

Iteration Loop — version timeline with per-version chips and compare drawer CONCEPT · proposed
Version history
v0.4.0
Config: winMultiplier.max raised to 6.5
12 Jun 2026 · 3 sandbox sessions
validation ✓
v0.3.2
Config: minBet lowered to $0.10
10 Jun 2026 · 1 sandbox session
validation ✗
v0.3.1
Base defaults — first config snapshot
8 Jun 2026 · 2 sandbox sessions
validation ✓
Compare: v0.3.1 vs v0.3.2 regression detected
Config diff
minBet $0.25 $0.10 ← changed
Validation delta
minBet jurisdiction floor (HK) — min $0.20 required v0.3.1 ✓ v0.3.2 ✗ new failure

State variants

State variants to be designed in the full proposal
  • single-version — only one version exists; timeline shows a single row; compare mode unavailable; no drawer shown.
  • comparing-two — exactly two versions selected; compare drawer opens showing config diff and validation delta side by side; regression chips highlighted if any checks regressed.
  • regression-flagged — the compare drawer identifies at least one validation check that passed in the earlier version and fails in the later version; a prominent amber regression banner surfaces the affected check and the config field most likely responsible.

Affected current files

File Change
apps/web/src/components/builder/GameWorkspace.tsx Add version timeline component with per-version validation chips and sandbox-run counts; add compare mode that enables selection of two versions and renders a config diff and validation delta drawer.
apps/web/src/lib/builderMockData.ts Extend the versions arrays with config snapshots, validation run results, and sandbox session identifiers per version so the timeline and compare drawer have real structured data to display rather than bare metadata rows.

What changes in the build flow

Today step 7 is notional — the versions list exists in mock data but provides no diff or regression signal; after this proposal it becomes an active iteration workspace where a builder can compare any two versions, pinpoint the config change that introduced a validation failure, and make an informed decision about whether to revert, adjust, or accept the change before advancing to step 8.

Open questions

Decisions needed before implementation
  • What counts as a "version"? Every save to the config form could create a version row, or versions could be explicit snapshots triggered by the builder (e.g. clicking "Save as version"). Auto-versioning on every save produces high fidelity but may overwhelm the timeline; explicit snapshotting requires the builder to remember to trigger it. This decision shapes both the data model extension to builderMockData.ts and the UI affordances in the timeline.
  • What is the retention window for version history? Storing config snapshots and sandbox session logs indefinitely for every build is potentially expensive. A policy is needed — e.g. the last N versions, or all versions within the current submission cycle — before the timeline's data model can be finalised.

What to tackle next

Once the open questions above are resolved, the version timeline and compare drawer can be specced in full. The next and final proposal in this reading order is Proposal 06 · Promote / Handoff, which covers pipeline step 8: the promotion stage ladder that takes a build from internal playable through to a certifiable package ready for operator distribution.