Skip to main content

0017: Separate Native Visual Review Surfaces

Status: Historical surface taxonomy; consumer separation retained; prescribed Almanac adoption and shared-surface guidance superseded by ADR 0027

Terminology and detached-export consequences are superseded by ADR 0025. ADR 0027 keeps the consumer-completeness lesson but does not require any of the surfaces below or a common implementation between them.

Context​

The first STAGE visual-rehearsal implementation treated screenshots, videos, and a detached contact sheet as the review product. It reproduced less of the game than the engine already knew, encouraged placeholder subjects, and made ordinary visual iteration leave the authoring environment. Moving the loop into The Circussy One as a runtime Visual Almanac corrected that inversion.

The correction exposed a second risk: an engine-native developer browser, an automation driver, a visual-regression suite, a player-facing codex, and an evidence export all touch similar content but serve different users and carry different lifecycle, failure, performance, and shipping requirements. Treating them as one feature makes each surface harder to use and easier to overclaim.

Established engine and UI workflows already separate these concerns. Native editor or runtime scenes present real content; automation frameworks drive and observe controlled states; screenshot tools compare reviewed references; and shipping galleries remain product features. STAGE should connect these capabilities without collapsing them.

Decision​

STAGE distinguishes five related responsibility contracts:

  1. Developer inspection mode - the gated responsibility for interactively resolving, staging, playing, tuning, and inspecting real game content. It exposes invalid content and keeps presentation human-editable. Prefer to host it inside a product-native Gallery when that Gallery has player value.
  2. Native Review Driver - an optional callable operation layer that can select a Scenario, open it, seek or play supported states, read provenance, reset, and tear down. It establishes operability, not visual quality.
  3. Visual Regression Capture - an optional controlled comparison layer for stable coordinates, reference images, tolerances, platforms, and objective differences. A human reviews reference creation and intentional updates.
  4. Player Codex or Gallery - an optional shipping product surface with its own unlock, localization, accessibility, performance, save-data, and content presentation requirements. It does not prove developer inspection capability.
  5. Evidence Export - an optional durable or portable projection used only when review must persist, leave the engine, support CI, or form an auditable record.

These are not requirements for five scenes, screens, binaries, or codebases. One in-game gallery may intentionally host player presentation and a gated developer-review mode over the same subject resolver, Native Stage, camera, and playback implementation. A direct game route may also remain the complete review surface without any Almanac UI. Prefer shared implementation when it removes duplicate representations and keeps the production composition intact.

The contracts must still not silently share audience-specific lifecycle or authority. In particular:

  • player mode may hide unsupported or invalid content; developer inspection mode must surface it;
  • an automation driver may report state and readiness without seeing pixels;
  • a regression comparison may identify change without deciding whether the change is good;
  • an Evidence Export may navigate accepted engine output but must not become the ordinary authoring loop; and
  • no project is required to build all five surfaces.

When a persistent Almanac is justified, its adoption order is: useful human Almanac, safe reset and teardown, optional driver, optional regression capture, and optional export. ADR 0018 later made existing engine previews and direct game routes the earlier default for one-off review. A player Codex is scheduled by product need rather than by development-tool maturity.

No separate visual schema is required. The ordinary project map and operating docs separate human and agent entry points, operations, observation channels, lifecycle, and optional export. ADR 0026 retired the earlier duplicate capability declaration.

Consequences​

  • STAGE's daily visual workflow remains inside the engine and the real project.
  • Projects can reuse a shipping codex without forcing development controls into the player build, or reuse an Almanac foundation without shipping it.
  • Agents gain a stable operation surface only when a Native Review Driver exists; UI discoverability alone remains insufficient.
  • Screenshot comparison becomes an optional regression concern rather than the definition of Visual Rehearsal.
  • Contact sheets remain useful navigation artifacts for remote or durable evidence, but are never the canonical review product.
  • A single product-native implementation can satisfy several contracts when its modes, permissions, failure visibility, persistence, and claims remain explicit; separation is conceptual, not a mandate for duplicate tooling.
Last updated on