Showcases

A showcase is a curated presentation of a game: a player-facing description plus a short, ordered carousel of media. Three showcases exist, and they share one on-disk format:

• The run showcase is the model’s own presentation of the game it built. The model writes it into its repository during the run, and record assembly captures it onto the run record.
• The case showcase is the authored presentation of a test-case variant, committed with the version and captured from the reference implementation.
• The suite showcase is the authored presentation of a test suite, declared as the showcase/ directory of the suite’s version folder and captured from the suite’s reference implementations.

The showcase directory

Each showcase is a directory holding exactly three things, with no subdirectories:

• showcase.md, the description: player-facing markdown in the style of a store page. It may reference images in the same directory by bare relative path (![Title](title.png)).
• showcase.toml, the carousel: repeated [[media]] tables, each naming a file in the directory itself and a short caption name. Table order is carousel order. Unknown keys are tolerated.
• The media files themselves, beside those two.

A media file’s kind is inferred from its extension, by the same rule as a declared proof:

Extension	Kind
.png	image
.json.gz	replay: a gzipped engine draw-command recording
.webm	video

Replays are the preferred moving footage. The engine records them itself through its recording bracket, and they are far smaller than video. Video is supported through the whole pipeline but discouraged.

Shared bounds apply to every showcase: the description is capped at 64 KiB, the carousel at 10 entries, and each media file at 25 MiB.

The run showcase

The model writes a showcase/ directory at the root of its repository. It is instructed through the case’s prompt and specs rather than declared by any manifest key, so it is a convention over the produced tree and the same capture applies to every test type that asks for one. A run whose tree holds no readable showcase has none.

Capture

At record-assembly time the showcase is read from the produced tree’s showcase/ directory and written onto the record: the description text and the ordered media entries, each with its file name, caption, and kind.

The showcase is model-written, so capture degrades leniently:

• A description over the cap is truncated on a character boundary with a truncation marker.
• Carousel entries beyond the cap are dropped with a warning.
• A media entry whose file is missing, or over the file cap, is dropped with a warning.
• A showcase that cannot be parsed records no showcase, with a warning.

A showcase problem never fails a run and never degrades its status.

Serving and publishing

The showcase’s bytes travel the same path as the run’s proof, asset, and validation media:

• The driver uploads the run tree, implementation/showcase/ included, to the artifacts service when the run finishes. The whole directory travels rather than the carousel alone, because an image the description references must be served per run even when the carousel does not list it.
• The artifacts service serves each file of it except showcase.toml at GET /runs/{id}/showcase/{file}.
• At publish, the backend has the artifacts service copy the run’s publishable media to the public bucket, where each showcase file lands under media/runs/<run-id>/showcase/<file>, and the public snapshot names the set on the per-run document as showcaseMedia. The set is derived from the record itself: the carousel entries plus the image references extracted from the description.

The console and the public gallery present a run’s showcase when the record carries one, with the description’s image references resolved to the served files.

The case showcase

A test-case variant declares its showcase with one manifest key, a directory relative to the version folder:

variants/base.toml

showcase = "showcase/base"

The directory takes the shared format above. Its media is captured from the variant’s reference implementation, so like the reference implementation it is authored answer-key material: it is never seeded into a run, and resolving it costs a run nothing. A variant that omits the key has no showcase.

The media presents the case rather than proving properties of it. The leading entry shows sustained, real play, with the case’s mechanics arising inside that play, and stills follow the play. What the media must show and how to capture it are stated in Authoring a Case Showcase.

Validation

The case showcase is authored and committed rather than model-written, so every problem hard-fails version resolution instead of degrading. Resolution requires:

• showcase.md present, non-empty, and within the description cap.
• showcase.toml parseable, with 1–10 [[media]] entries.
• Every entry’s file a plain file name: no path separators and no ...
• Every named file present in the directory, within the file cap, and of a recognized media kind.

Flow

The showcase travels the definition pipeline the way specs do:

• Ingest inlines the description into the stored manifest and records each media entry with the store-relative key its bytes live at inside the copied version tree.
• The backend serves each media file at GET /test-cases/{slug}/versions/{version}/showcase/{variant}/{file}. Only a file the variant’s stored carousel lists resolves, and showcase.toml is never served.
• The resolved version carries each variant’s showcase, meaning the description plus the carousel, and the catalog listing carries each case’s showcase preview: the latest visible version’s first variant, in manifest order, that declares one. See the backend API.
• The public snapshot publishes the showcase of every non-experimental version of each case with a published run, whichever version that run built, because a showcase presents the case rather than a run. Each media file is content-addressed under media/cases/<slug>/<version>/showcase/<variant>/<digest>-<file>, listed in the snapshot’s case-showcases.json, and also named on the case document’s variant for a version the snapshot publishes a case document for. A .webm clip is transcoded to .mp4 for universal playback, with the entry’s file kept as authored, exactly as run media is.
• The public site lists a case once any run of it is published, and previews it with the showcase of its newest version that has one, read from case-showcases.json.