# Scene spec

Scope: how the director writes one scene of a product showcase video, and the shape in which the builder reports it back. The director owns every field. The builder fills only what the director leaves blank, and says so in the report.

## Template

```md
## Scene <n>: <name>

Time limit: <seconds> max. Includes the entrance and the exit.
Voiceover: <the line, if any>. It sets the length; it is not rendered.
Surface: <where in the product this happens, and what has already happened there>.

Beats:
1. <what the viewer sees> (<seconds>)
2. <what the viewer sees> (<seconds>)
3. <what the viewer sees> (<seconds>)

In: <rise from wallpaper | match cut from scene <n-1>'s last frame | film open>
Out: <drop or rise out to wallpaper | hold (film end) | none, the next scene match-cuts>
Cursor: <shown | hidden>

Real: <what is the running product, unmodified>
Staged: <seeded history, scripted replies, stand-in records>
Synthetic: <generated data, and its seed>
Composited: <overlays, split screens, effects drawn over or around the product>
```

## Fields

| Field | Who decides | Notes |
| --- | --- | --- |
| Time limit | Director | A hard maximum. Revisions are paid for inside it. |
| Voiceover | Director | Context for pacing only. |
| Surface | Director | The builder proposes one when it is blank; see [choose the surface](showcase-guide.md#choose-the-surface-for-the-story). |
| Beats | Director | Numbered, in viewer terms. Seconds per beat are optional; a given split is binding. |
| In, Out | Director | The builder proposes these from the neighbouring scenes when blank; see [transitions](showcase-guide.md#transitions). |
| Cursor | Builder by default | Hidden when nothing is clicked. |
| Real, Staged, Synthetic, Composited | Builder | Filled in from what was actually built; see [data honesty](showcase-guide.md#data-honesty). |

## Example

A scene from a five-scene product launch film:

```md
## Scene 4: Training table

Time limit: 6s max.
Surface: an agent's training workbench, with five training sets already in the Training tab.

Beats:
1. The window rises; the cursor flips the tabs right to left, landing on Training.
2. The rest of the UI peels away as the camera zooms into the table.
3. New rows append while the table scrolls up out of frame, the newest row held front and centre.
4. The stream stops, one last row pops in, and the table slides up and out.

In: rise from wallpaper.
Out: rise out to wallpaper (the next scene rises in, so the motion carries).
Cursor: shown for the tab flip, drifts away before the peel.

Real: the tab flip and the starting table.
Staged: the appended rows, through a video-only patch (the product has no way to add sets live).
Composited: the peel-away and the zoom.
```

The example illustrates the shape, not a template for content.
