Chapters

use chapters admits one define chapters block: a row per chapter, each with a name for code, a title for the reader, an optional description, and the moment it begins. Chapters are declared, not scripted — a chapter ends when the next begins, and there is no end chapter.

story
  title: The Secret Letter
  authors:
    You
  id: secret-letter
  use chapters

define chapters
  market - Chapter I - Grubber's Market
    begins when the game starts
  commerce - Chapter II - Commerce Street
    A wider street, and the mercenaries know your face now.
    begins when the player visits Commerce Street for the first time
end chapters

The name is one kebab word — what conditions say, never printed. The title is raw prose to the end of the line: a numeral or a colon in it means nothing to the grammar, so number your chapters however you like, or not at all. The optional description is an indented paragraph in the shape every other block's prose takes. begins when is required and comes last in the row. Rows are in reading order and that order is the chapters' order; a repeated name, a second block, or the block without use chapters is a compile error.

When a chapter begins

begins when names a moment, never a standing condition, and the moments are ones the language already has:

• the game starts — the first turn is about to begin. A story that says use chapters must open exactly one chapter here, and it must be the first row; an un-chaptered opening is spelled as a chapter (a prologue is just a row).
• the player visits <room> for the first time — the role-holder's first arrival in that room, whoever holds the role, by walking or by an authorial move.
• <timer> expires — a timer, named by its possessive from the story level (the bell expires, the player's waiting expires).
• <entity> becomes <state> or the story becomes <state> — a declared state being reached, as a define sequence step anchors.

A trigger firing while that chapter or a later one is already running changes nothing: the runtime raises runtime.chapter-stale naming the row, a diagnostic rather than a crash.

What the reader sees

A chapter beginning is a packet on the story.chapter channel — name, title, description, ordinal — emitted on the turn the trigger fires, before that turn's prose, so the title reads as a heading over what follows: the opening chapter sits between the banner and the first room, and a chapter that begins on an arrival sits above that arrival's room description. The same holds for a timer or a state change — the card opens the turn's output, whatever began the chapter. The browser client renders a title card; how it looks is the client's. The current chapter is ordinary world state, so save, restore, and undo carry it with no special handling.

Reading the chapter

A chapter scopes nothing and gates nothing by itself, but it is readable. during <name> is true while that chapter is current, and it stands on a head directly, beside while, wherever a line takes while <condition>:

create the grocer
  a person
  in the Grocery Stall

  on the player talking during commerce
    refuse no-time-to-chat
  end on

  phrase detail during market:
    The stallkeeper looks nervous and irritable.

  on every turn while hunted and during market
    phrase footsteps-behind
  end on

A head takes one of while <condition> or during <name>; both on one head is a parse error. before <name> and after <name> — the chapter has not begun, or is over — are condition atoms only (while before commerce), since after is already a clause head. The opening chapter is current before the first turn, so during <opener> holds while turn one renders.