clone

a browser grid puzzle game where you push words around to rewrite the rules of each level

main
miau-is-true / openspec / changes / archive / 2026-09-24-add-world-index-navigation / proposal.md
proposal.md 4.2K source

Why

The accepted D20 design makes each registered pack a walkable world, but the current INDEX model still treats bundled packs as one core sheet and has no world identity or world-to-world navigation contract. That leaves registration order, chapter progress, boundary movement, and imported pack metadata to incidental catalog behavior.

The short-term goal is a stable world model and navigation seam that the renderer can consume. It keeps the accepted world card and header treatment explicit while leaving their final visual implementation to a follow-up design review.

What Changes

  • Give every registered pack one world identity and an ordered chapter range of INDEX sheets. A world with more than fifteen proofs continues onto additional sheets belonging to that same world; worlds never share a sheet.
  • Preserve deterministic registration order: core first, then bundled packs in registration order, then imported packs in install order. Remove the current special case that groups bundled packs under core.
  • Define world-aware INDEX navigation: Q/E (gamepad LB/RB and the touch equivalent) switch worlds, and walking off a world's terminal path enters the adjacent world's opener. Boundary movement is clamped at the first and last world.
  • Define per-world progress and active-world identity so completion counts and unlock sequencing do not leak between chapters.
  • Validate optional manifest.world metadata (glyph, tagline, and the allowed property-color accent) as a nonblocking W11 authoring note. An invalid identity falls back to the first palette glyph, no tagline, and the default foreground path while gameplay-field validation remains atomic. Expose normalized metadata to INDEX, Workshop, and future world cards.
  • Record the accepted world header and first-entry card contract as a presentation seam: header data includes world number, name, per-world completion, and world strip state; first entry and Workshop PLAY can request a world card. Pixel layout, animation timing, and final copy fitting remain follow-up presentation work.
  • Clarify that the D20 Worlds section supersedes the earlier INDEX paragraph that says built-ins share sheet 1. The rule is now one sheet range per pack, including built-in packs.

Capabilities

New Capabilities

  • world-index-navigation: world identity, pack-owned INDEX sheet ranges, deterministic world order, chapter navigation, progress scoping, and the presentation data seam for D20.

Modified Capabilities

  • level-packs: validated world identity and registration order become part of the pack handoff contract.
  • game-presentation: INDEX consumes a world-aware layout and exposes world switching and first-entry card requests without changing simulation state.

Dependencies

  • add-world-authoring-workflow supplies the reviewed bundled-pack handoff, stable pack IDs, registration order, and solver evidence.
  • fix-rule-precedence-and-reading remains an engine/content prerequisite for world packs, but this change does not alter rule evaluation.
  • The existing catalog and progress stores remain the persistence boundary; this change adds world/chapter keys without changing solved proof IDs.

Impact

  • Affected data model: catalog pack records, normalized manifests, INDEX layout, navigator state, and world-scoped progress queries.
  • Gameplay fields continue to use the existing atomic pack validation path; optional world presentation metadata does not weaken those checks.
  • Affected input paths: keyboard, gamepad, touch, and path-edge traversal.
  • Affected presentation contract: world header/card request data and world strip state. The follow-up implementation must preserve fixed integer board geometry and existing hit targets.
  • No new rule vocabulary, movement semantics, solver behavior, or CommonJS execution API is introduced.

Deliberately Deferred

  • The exact canvas composition, font fitting, iris timing, and copy for the world card/header are left for a separate designer-reviewed implementation change. This proposal defines the data and transition seam they consume.
  • World-specific custom map layouts remain an authoring extension after the default auto layout is correct.