Step 2 rebuild — Skeleton sections

What's shipped vs pending in this plan.

The roadmap's Phase 3 lists trackers (3.2), zones (3.3), and win conditions (3.1) as separate steps. They are — but they share UI surface (Step 2), share a client-side architecture (the live schema store), and share a migration concern (legacy game_parts / game_meta['life_points'] reads). Building them one at a time without a unified plan means redoing the foundation three times.

This plan separates foundation (must ship first, locks the architecture) from sections (can ship in any order once the foundation is in place). The foundation is small and contained; the sections are the real feature work.

Three architectural commitments

1. One client-side store (window.gameSchema) holds the live shape. Sections render from it; saves write to it; cross-section dropdowns read from it.
2. Auto-save per section (debounced) replaces the "Save & Continue" button as the persistence mechanism. Continue becomes a navigation button only.
3. Live validation, non-blocking. Broken cross-references (a win condition naming a deleted tracker) get red badges; user can keep editing. The "schema OK" status pill at the bottom of the page is the new "you're ready" signal.

Visual layout of the rebuilt Step 2

Goal

Lock the architecture before any section work. Without this, every section reinvents save / load / cross-reference / validation.

Estimate

~3–5 days, focused.

Deliverable

Step 2 page renders with empty sections; the store + autosave + validator + migration all work end-to-end against a stub section.

Foundation steps

• F.0a — Client-side schema store + autosave helper shipped

  What: A small JS module (js/step2-schema-store.js) that holds the live gameSchema object, exposes saveSection(name, data) with debounced AJAX, and emits change events for reactive dropdowns.
  API:

  • SchemaStore.init(initialSchema)
  • SchemaStore.get() — returns the live shape
  • SchemaStore.update(section, data) — updates + triggers save
  • SchemaStore.on(section, callback) — subscribe to changes
  • SchemaStore.findReferencesTo(type, id) — returns sites referencing a given id

  Files: js/step2-schema-store.js (new), ajax-step2-save.php (new endpoint that accepts {section, data}, persists to game_meta).
  Acceptance: with a stub section that writes {foo:"bar"}, hitting save in the browser persists to the DB; reload shows the value back; the store fires change events to subscribed dropdowns.
• F.0b — Step 2 page restructure (skeleton + collapsibles) shipped

  What: Replace the existing Step 2 layout with the four-section Skeleton hub above the existing Card Types / Families. Each section is a collapsible <details> block with a stub body initially. Auto-save indicator + status pill at the bottom.
  Files: index-step2.php (substantial rewrite of the form section, leaving Card Types / Families untouched).
  Approach: keep all existing PHP state-loading logic intact; rebuild only the form HTML for the new sections. Old sections stay where they are.
  Acceptance: page loads with four empty Skeleton sections + the existing Card Types / Families; existing data renders unchanged; the four stub sections are wired up to the store from F.0a.
• F.0c — Schema validator + reference finder shipped

  What: Two pieces, both in the same JS module:

  • SchemaValidator.validate(schema) — returns a list of {section, severity, message} issues. Severities: error (red badge) | warning (yellow). Non-blocking.
  • SchemaStore.findReferencesTo(type, id) — walks the schema and returns places that reference a given tracker / zone / etc id. Used by delete confirmations.

  Files: js/step2-schema-validator.js (new).
  Acceptance: after each save, validator runs and section badges update; deleting a referenced tracker shows a confirmation modal listing the referencing sites.
• F.0d — Legacy data migration on read dropped

  What: When the page loads and game_meta['trackers'] is missing, build it on the fly from existing game_parts(part_type='resource') rows plus game_meta['life_points']. Same pattern for zones (legacy game_meta['game_zones'] blob → structured shape).
  Files: a helper php-includes/inc-step2-migrate.php with two functions: migrateLegacyTrackers($conn, $gameId): array and migrateLegacyZones($conn, $gameId): array.
  Approach: read-only migration. Don't write the new shape until the user actually saves a section through the new UI. That way existing games keep their legacy storage until they're touched, and we have a clear "user has migrated" signal.
  Acceptance: a game created in the old UI loads correctly in the new UI with its resources / life / zones visible as trackers / zones; no DB writes happen on page load.

Once the foundation is shipped, the four Skeleton sections can be built independently. Each replaces a stub from F.0b with a real recipe-based form. They don't depend on each other for implementation — only at runtime through live cross-references, which the store handles.

Suggested order is by user value: trackers first (replaces a real bug today — Resources + Life duality), zones second (same recipe pattern, validates it generalises), effects third (small multi-select, no real complexity), win conditions last (depends on the JSON Logic evaluator from Roadmap step 3.1a, which can be built in parallel).

Section build steps

• S.1 — Trackers section (Roadmap 3.2) shipped

  Read this first: Appendix B — Trackers (especially B.6 for UI / recipes).
  What: Replace the stub Trackers section with: list view (rows showing icon + label + type/role badges + scope + edit/delete) + "+ Add tracker" button opening the recipe picker.
  Recipes to ship: the seven from B.6 (life_points, generic_resource, victory_points, action_points, player_status, achievement_set, shared_threat) plus a "Custom" option for the full form.
  v1 scope: the four types (counter / boolean / enum / set) and six roles. Defer derived trackers and per-card counters to v1.5 (Roadmap parking).
  Acceptance: user can add a tracker via a recipe in 3 clicks, see it in the list, edit it inline, delete it (with reference-finder warning if it's referenced elsewhere). Saved to game_meta['trackers'] via the store.
• S.2 — Zones section (Roadmap 3.3) shipped

  Read this first: Appendix C — Zones (especially C.5 for UI / recipes).
  What: Same pattern as trackers: list + recipe picker + form. The 10 recipes from C.5 (personal_deck, hand, in_play, discard, shared_market, shared_deck, shared_pool, current_trick, won_tricks, tableau).
  v1 scope: the four scopes / five visibilities / five orderings, the three auto_refill.when_empty policies. Defer multi-zone selectors, hand-passing, per-card ownership / visibility in shared zones (all C.6 stretches) to v1.5.
  Acceptance: user can add a zone via a recipe in 3 clicks. Saved to game_meta['game_zones'] in the new structured shape (legacy reads still work via F.0d migration).
• S.3 — Effects vocabulary section shipped

  What: Multi-select checklist of effects from assets/data/effects.json, grouped by mechanic family (deal_damage, gain_resource, draw_cards, etc). Each effect's checkbox is enabled only if the game has the trackers / zones it requires. Greyed-out effects show a tooltip explaining why ("requires a tracker with role: life").
  Files: renders from $_game_defaults['effects']; saves to game_meta['enabled_effects'] as an array of effect_key values.
  Smart filtering: a small inference step that reads each effect's params and checks: do we have a tracker with the right role? a zone of the right scope? Disable the checkbox if not.
  Acceptance: user can toggle effects on / off; disabled effects show why; the AI card-generation prompt later reads only the enabled set.
• S.4 — Win Conditions section (Roadmap 3.1) shipped

  Prerequisite: Roadmap step 3.1a (the JSON Logic evaluator, inc-game-expressions.php) is already shipped. Can be built in parallel with foundation.
  Read this first: Appendix A — Win conditions (A.0 architectural principle, A.5 recipes, A.7 worked examples).
  What: Reads win_shape from Step 1, renders the shape-specific recipe form. Form dropdowns (tracker pickers, zone pickers) read live from the store — adding a tracker upstream immediately makes it selectable here.
  v1 recipes: the six from A.9 v1 (combat, race_to_n, most_at_end, multi_source_score, weighted_score, last_standing). Defer cooperative / boss / team / hidden to later.
  Output: JSON Logic stored in game_meta['ending'] per A.1 schema.
  Natural-language preview: the form shows what the structured ending says in human terms ("Game ends when any player's Authority reaches 0. That player loses.") so the designer can sanity-check without reading JSON.
  Acceptance: picking a recipe and filling its form generates a valid JSON Logic expression that the evaluator from 3.1a returns the expected boolean for, against a stub Game state.

• P.1 — Add win_shape dropdown to Step 1 briefing dropped

  What: A single dropdown on the Step 1 form: "What kind of victory?" with the six recipe ids as options (combat, race_to_n, most_at_end, multi_source_score, weighted_score, last_standing). Free-text game_goal stays as the human-readable label alongside.
  Files: index.php (form), ajax-steps.php (save handler), game_meta['game_briefing'] shape.
  Why: Step 2's Win Conditions section (S.4) reads win_shape to know which recipe form to render.
  Acceptance: the dropdown saves; Step 2's Win Conditions section reads it correctly.
  When to ship: any time before S.4. Could land in the same PR as F.0b or as its own tiny PR.

The Step 2 rebuild is complete when:

1. A user can land on Step 2 with a fresh game and author trackers, zones, win conditions, and effects via recipe-based forms, in any order they choose.
2. Existing games (legacy storage) load correctly without manual migration.
3. The schema validator runs after each save; broken cross-references show inline; the bottom-of-page status pill reflects "schema valid" or "N issues".
4. Card Types and Families still work as before, visually separated from the new Skeleton block.
5. The simulator (when it exists, Roadmap 3.8+) can read game_meta['trackers'], ['game_zones'], ['ending'], ['enabled_effects'] and build a runnable Game state from them.

This plan is the implementation detail behind several Roadmap entries. The roadmap stays high-level; this plan is where the substeps live.

The foundation work doesn't appear in the roadmap because it's architecture-not-feature. If you want it visible in the roadmap, add a 3.0 step ("Step 2 architecture: live schema store + autosave + validator") that links here.