Visual novel — the Experience medium

Status: rough spec (direction). Not an implementation contract; nothing here ships until scheduled.

Who it is built for, since it decides most arguments here: the roleplay-minded reader who would rather decide inside a story than watch one resolve. Every feature below is judged against that — a commitment must feel like a commitment, a POV must genuinely withhold, and a second run must be a different story rather than the same pages again. If a proposal makes the reading smoother but the deciding weaker, it is the wrong trade.

The value proposition, in one line

A better book. Not a longer one, not an AI-written one — a book that keeps the four things the printed page has to fake, and every argument in this folder resolves against them:

Everything downstream — the reference chain for sprite identity, the cliffhanger contract, the reader transport, the exploration budget — exists to buy one of those four and is worth exactly what it buys.

What we are building toward (next roadmap)

The four properties are what the reader gets once. What brings them back is a fifth thing the printed page cannot do: the book remembers you. A second run is a different story because the world kept your first, and because you return knowing what another seat knew. That is the practice record, and the Experience is where it starts — the training world, the first thing sold and the first to prove.

The next roadmap's job for this medium is to produce that one Experience and measure those three things — not to widen the ontology. The target shape of that Experience — a short, original, emotionally true world with a canonical good route, divert and rejoin, and a reading given back afterwards — is the training worlds spec. Every build item in §9 that does not shorten the path to a played, measured Experience is deferred behind ones that do. The reader shell, the commitment contract, the ending card, and Factory coverage are on the path; a second renderer, a richer score, or a new evidence system are not.

Boundaries the framing does not move: no pricing, retention, or demand figure for novels is quoted until one has been observed; the record is evidence of practice inside a declared world, perspective, and interval, never a verdict on the reader (promise); and whether anything practised here transfers outside the fiction is an independent question this medium does not answer.

Experience is the product name for this medium: one of the three ways a Domain is inhabited, alongside Scenario (decided) and World (wandered). Episode remains its unit of delivery and Script its scaffold — Experience names the medium, it does not rename either. See the product model for the three-medium contract.

This specification owns one thing: what a visual-novel delivery of an Episode is, and what it may and may not do. It does not own presentation craft, and it does not introduce a second renderer, score, resolver, or evidence system. Composition, camera, performance, sound, and editorial craft stay with Stageplay and its craft skills (stageplay-production, stageplay-editorial-craft, stageplay-set-craft, sprite-performance-craft, stageplay-audio-effects-craft) — the visual-novel close view is already one of Stageplay's projections, and this spec is the delivery shell around it.

Authority is unchanged and non-negotiable:

Domain defines. Branch preserves. Scenario resolves. Episode embodies. World inherits and lives.
You decide in a Scenario, read an Experience, and wander a World.

The spine

This folder is one specification in seven parts, sequenced the way the pipeline runs. Read them in order; each owns exactly one stage and defers to its neighbours rather than restating them.

canon                scaffold            supply              fork               look              experience
Scene.summary   →    ScriptContent   →   mandate ·       →   the cliffhanger →  sprites ·     →   the reader
+ typed deltas       (a projection)      direction ·         and the choice     plates ·          transport ·
(the truth)                              Reading                                CGs · style       saves · POV

Its supply side beyond the fork — how a timeline is scouted cheaply and earns production at all — is budgeted fate exploration.

Surrounding context: human practice (the two Episode postures), Play vocabulary (Episode · posture · modality · Will), reasoning vocabulary (Mandate — the branch-scoped trajectory of peaks and valleys), Memory Palace (the experiential frame), narrative convention (scene classes and beat mechanisms), World concept contract (what happens to a mature branch).

The subsystems it reads: src/types/domain/stage.ts (ScriptContent → ScriptFrame → ScriptMoment), src/types/domain/branch.ts (Branch, SceneVersionPointers), src/types/domain/futures.ts (Future / FutureRun — the sister continuations and their priorLogit), src/types/domain/scene.ts (WorldExpansion deltas), src/lib/core/io/script-export.ts (the existing export seam).

The claim. A dense causal structure is a bad read as a document and a good read as a passage. A catch-up Episode already turns accepted branch state into an immersive passage; the visual novel is the reader-paced form of that passage — one moment per advance, a stable stage, and a commitment at each fork — plus the traversal affordances that make a branching record explorable rather than exhausting. It is a modality, not a new truth: it changes affordances and pacing, never canonical state.

---

1. What this modality is for

Existing deliveries are timed: a score plays, the audience watches. That is right for a set-piece and wrong for a causally dense passage, where the reader needs to control the clock, re-read the line they skimmed, and stand at a fork long enough to weigh it. The visual-novel grammar solves exactly that, and it is the only popular medium whose entire vocabulary is built for branching.

Two postures, matching human practice exactly:

• Catch-up (read). Accepted branch material, delivered reader-paced. No new Will. The reader may traverse forks that already exist on the branch tree — a commitment here selects which accepted or candidate continuation to read next, and writes nothing.
• Live (direct). At a decision window, the delivery hands off to a bounded Scenario exactly as any live Episode does. The reader's commitment becomes real Will, resolved through the governed path, and the branch preserves the consequence. The visual-novel frame is the roleplay skin over that window — it never resolves anything itself.

Conflating those two is the failure mode this spec exists to prevent: a reader must always know whether the commitment in front of them selects a passage or spends Will.

---

2. The medium, taken seriously

Designing "in the authentic style" means adopting the medium's actual grammar rather than a scrolling transcript with pictures. Each convention below is load-bearing — it solves a problem a naive reader re-encounters — and each maps onto something the record already carries.

Deliberately not taken from the medium: melodramatic register, affection meters, timed choices, and "bad end" framing. The material is a modelled world; the register is documentary (§6).

---

3. The commitment contract

This section decides whether the modality is a real medium here or a slideshow.

Underneath it sits the product's simulation principle: Will is injected from outside the simulation. The engine supplies the world, the memory, the affordances, and the price of a move; the reader supplies the move. Nothing in the reader may commit on their behalf — auto and skip advance presentation, never a fork (§ transport), a resumed save restores a position rather than replaying a decision, and a recommendation is not offered where a commitment is asked for. The value of a route is that a person chose it: the record of a playthrough should be able to say who moved, from what vantage, and knowing what.

A fork is presented as a choice only when the alternatives differ in world state. Concretely: the candidate continuations must differ in their WorldExpansion deltas (threadDeltas / worldDeltas / systemDeltas / ownershipDeltas / …). Two continuations that differ only in prose are versions, not choices; the reader passes straight through and the better-written version is simply the one delivered.

This governs forks, not every interaction. The medium also runs on commitments that branch nothing — a line you choose to say, a small kindness that moves a relationship, a fact you decide to withhold — and whose effect arrives much later, sometimes as the condition that opens a route at all. Those are graded separately as texture and accumulating picks in systems §1: they never take a choice screen, never stop the work, and never claim a consequence no delta recorded — and the strict gate above stays strict precisely because they exist below it.

A presented choice carries:

• Posture, unmistakably. Traversal ("which accepted passage do I read next") or Will ("this issues a move that Scenario resolves"). Different framing, different confirmation weight; never the same affordance.
• A label in the reader's own second person, derived from the Future's name and variable coordination — never a raw id, never a probability as the label.
• What was weighed, on demand. The Future already carries considered (the option space rejected). It belongs behind an affordance, not dumped on the choice screen.
• Divergence after the fact, never before. Priors are real, so they may be shown after commitment. Showing a prior before the choice turns a decision into an instruction and collapses the modality into a recommendation engine. This is a rule, not a preference.
• The consequence, named. After committing, the delivery surfaces which state moved — the thread whose stance shifted, the relationship that changed — as a quiet readout in the instrument register. This is the anti-weightlessness mechanism: the reader watches the world take the delta.

Three further rules:

• No dead options. If a continuation has not been generated (or, in the live posture, is not a legal move), it is not shown. A greyed-out option is a promise the record cannot keep.
• Seat-shaped, or not offered. A choice may only expose what this seat could know. Private beats reach a reader through their own seat or not at all; the glossary, backlog, and flowchart inherit the same boundary. A clearer choice screen is never a reason to leak.
• What would falsify it travels with the route. breaks — the condition under which a direction was wrong — belongs on the ending card (§5), not the choice screen.

---

4. The reading position, and what may write

Route     the ordered commitments taken across the branch tree
 └ Node   one timeline entry on a branch (a scene, or a world build read as an interlude)
    └ Frame    one tableau — ScriptFrame, unchanged
       └ Moment  one line/thought/action/narration — ScriptMoment, the advance unit

• A reading position is (branchId, entryIndex, frameIndex, momentIndex) plus the route that reached it.
• A save is exactly that, and nothing else. Restoring re-resolves all content from the record through the existing branch/version resolution, so a save can never carry stale content or drift from canon.
• Seen-state (moments read, endings reached, assets seen) is a set of ids per domain — the substrate for skip-read, the glossary, and the gallery.

Reading writes nothing to canon. Not seen-flags, not progress, not "last read at". Reading state lives in client/aux state, per-reader and disposable: losing it loses a bookmark, never content. This is the same relationship the browser projection already has with the record (persistence) and the same rule Stageplay already holds — a delivery may select presentation, never mutate authority.

The only path from a reading session into the record is the live posture (§1): a decision window instantiates a bounded Scenario, and the write happens through that governed path with its own provenance — not through the reader's advance click. A prepared continuation is revalidated against accepted branch state before it is delivered; the delivery never assumes an unresolved move succeeded.

---

5. Routes, endings, and replay

• A route is derived, never stored as its own object: the branch tree plus the cursor names it.
• An ending is a route terminal — the last entry of a branch with no accepted continuation. The ending card is not "Ending 3/12 — Good End". It is what the material honestly supports: which threads resolved and how, which stayed open, and (from breaks) what would have invalidated the path just read.
• The flowchart is the medium's best replay affordance and is nearly free here: the branch tree already renders as graph and board projections. The one addition is jump into any node this reader has visited, legal because a cursor is all a position is. Unexplored sister branches show as unexplored edges — the invitation to re-read.
• Skip-to-next-fork makes a second pass bearable: seen moments advance at skip speed and the reading halts at the first fork where a different commitment is available.
• Comparison is the payoff. Two routes over one situation are two compatible renditions of the same record, which is exactly what the debrief in human practice needs: what this reader anticipated, what another seat knew, what the other route cost.

---

6. Presentation, and the register problem

Presentation craft belongs to the Stageplay craft skills; this section fixes only the constraints the modality imposes.

The register is documentary, not melodrama. Meridians is quiet-by-default and instrument-shaped (frontend convention, the frontend-design skill). A visual-novel frame invites theatrics that modelled material cannot carry, and the resolution is to keep the medium's grammar and drop its affect.

• The frame. Full-bleed stage, chrome withdrawn. Interface surfaces persist only where they carry function — textbox, choice screen — never as ornament over the plate.
• The textbox keeps a fixed height so text never reflows the stage, sits in the established rail, and respects real reading time with sound off. Mechanism is styled, not labelled: line reads as speech, thought recessed, narration / environment as unattributed caption, action / reaction / comic as stage lines, memory set back, document as found text. Speaker, title, and body keep distinct hierarchy.
• Staging. ScriptSlot maps to fixed positions; facing mirrors the figure; state drives emphasis — the active speaker lifts, the rest dim. entering / exiting are the only motion that plays on a figure.
• One primary changing channel per beat. Typing, camera, gesture, particles, and an animated instrument must not compete for the same line. Transitions are motivated cuts, not drift: crossfade within a scene, a slower change with a location card between nodes.
• Expression variants. The data models seven figure states while the asset lane generates one portrait per character. Either produce a small set per speaking character (neutral / intent / recoil is enough) or accept the flat figure honestly — a wrong-face figure is worse than a still one.
• Audio. Voice optional and per character, with a stable assignment so a re-read never recasts; ambience per location; no score, no stingers. Voiced dialogue binds to its exact transcript.
• Reading controls. Advance, backlog, auto, skip, skip-to-next-fork, save, load — all reachable by keyboard, all readable at phone scale.

---

7. Preparation and cost

A voiced, illustrated reading is among the most expensive artifacts the instrument can produce. Cost is the binding constraint, not capability, and the controls already exist (unit economics; ceilings enforce against actual trailing spend).

• Preparation is reader- or Director-initiated, never autonomous. Under the spend model explicit user actions fail open and autonomous work fails closed; an autonomous lane that prepares readings can spend a week's ceiling unattended.
• Estimate before spending. Preparation states its cost from the shipped pricer — N missing entity images at the image rate, M characters of dialogue at the voice rate. No new cost machinery, no new lane.
• Assets are per identity lineage, produced once and reused where valid. Factory resolves the route's entity, appearance, expression, place, and moment coverage against approved renditions. Producing per scene multiplies spend by the branching factor for no gain; blindly sharing a post-injury or branch-bound appearance across every route erases history. Reuse requires exact lineage and valid branch/time bounds, not similar labels.
• Voice is opt-in and cached per line version. A re-read must never re-synthesise; editing a line invalidates only that line.
• What preparation adds beyond assets: a label per presented fork, expression variants for speaking characters, and a voice assignment per character. All three are cheap relative to the reading itself.

Which branches are worth preparing at all — and how the exploration that produced them is bounded by a dollar budget rather than a scene count — is owned by budgeted fate exploration. Its finding, in one line: scouting a candidate costs ~2.5% of producing one, and production cost is voice and images, not text.

Preparation freezes a reproducible interpretation package: resolved Script versions, seat projection, active Acting State and Dynamics graph ids at each branch coordinate, and exact Factory asset revisions. Later evidence may produce a better latent model or a repaired sprite set; it prepares a new package rather than silently changing a published passage.

---

8. Leaving the instrument

If a reading is a consumable artifact it must be shareable outside Meridians, and export must go through the existing seam (src/lib/core/io/script-export.ts, alongside the scene/epub/board exporters) rather than a parallel exporter.

• A static bundle — resolved script, images, optional audio, minimal player; a self-contained directory that opens with no runtime. This is the shareable artifact, and it is subject to the existing publish sanitisation: an export carries only what its seat may disclose.
• A Ren'Py project — script files with menu: blocks at the forks and assets placed by convention. Ren'Py is the medium's lingua franca; exporting to it means the artifact outlives us and can be hand-edited by someone who knows the medium.

Exported readings are catch-up only. A live posture cannot leave the governed path, because resolution lives here.

---

9. The honest ledger

The local VN experiment audit 🔒 records a deterministic candidate catch-up bundle with reader-paced advance, backlog, local save/load, auto, seen-only skip, stable frames, digest-pinned assets, and preview-only decisions. It also records repeatable VN-first composition across several fixed-video trials. This is strong integration evidence, but it lives in tmp/sfx-lab, lacks held-out and human audience proof, and does not make the permanent delivery shell shipped. The integration order is owned by the World roadmap.

---

10. Risks, and the test that would falsify this

• Weightless commitments — the standard failure of generated branching. Held off structurally by the delta gate and the consequence readout (§3). If most forks fail the gate, that is not a delivery problem: it is the finding that generation is producing variation without consequence.
• Posture confusion — a reader believing they spent Will when they selected a passage, or the reverse. The most serious risk here, because it corrupts the debrief. Mitigated by §1 and §3, and worth a test.
• A second writer — the subtlest risk: a reading surface that starts persisting progress into canon. Mitigated by §4, which should be enforced by a test rather than by discipline.
• A parallel pipeline — a visual-novel renderer, score, or evidence system growing beside Stageplay's. Mitigated by scope: this spec owns the delivery shell and the commitment contract, nothing else.
• Cost — the highest per-artifact spend in the product, held by §7.
• Tone collapse — the frame pulling modelled material toward melodrama, held by §6.

The falsifiable test. Take one domain with a real branching arc. Have a participant read the outline, then read the same material as a reader-paced delivery, and answer the same questions about the causal structure — which factors move which threads, what would invalidate the current read. If reading it as a passage does not beat reading the outline, this modality is an expensive skin and the spec should be abandoned rather than polished.

---

11. Vocabulary

This spec introduces no new product noun. It is an experience modality of Episode delivery in the existing sense (Play vocabulary), and it reuses:

Deliberately not introduced: "player", "score", "good end", or a second sense of "Scenario" — Scenario is the decision substrate, and a traversal commitment is not one.

---

12. Open questions

1. Who reads it. The Director reading their own branch, a seated participant, or a published audience? Publishing pulls in disclosure, asset rights, and hosting, and substantially changes §8.
2. May a reader traverse uncommitted Future branches? It is the more interesting product and needs an unmistakable "this did not happen" signal held for the whole passage, not a badge at the fork.
3. Where does the live decision window sit visually — inside the textbox grammar, or as a declared transition out to the Scenario surface and back? Both are legal; only one will read as one work.
4. Expression variants — worth the spend? Three per speaking character multiplies image cost; a flat figure is honest but flat. A cost/fidelity call, not a technical one.
5. How much reasoning goes on stage? The causal structure behind a fork can be an explanatory instrument, or entirely off-stage. Too much makes it a dashboard; too little makes the commitment arbitrary.