Scenes & structure

#The scene

The scene is the unit of the document: a body of narrative and a detail that declares the board. A document is a sequence of scenes, and the reader moves through them in order. The scene's own attributes govern its animation timeline — duration (its implicit attribute, auto by default), autoplay, and loop.

scene{
    # A heading
    Narrative prose, read top to bottom.
}[
    canvas.graph{
        curve(expression: sin(x))
    }
]

#Narrative and board

The body { } holds what is read: paragraphs, headings, lists, equations, callouts, dividers, references. The detail [ ] holds what is shown: canvas panes (canvas.graph, canvas.code) and supporting board content such as table and image. The two halves are choreographed together: as the narrative advances, the board answers.

#Steps

A step — written as === on its own line in the narrative — carves the scene's timeline into steps. Everything animated anchors to those steps: a cue's in: 2 fires at step two, a keyframe's at: 2 starts its move there. Steps are how the prose and the board stay in lockstep: the reader reaching a point in the text is what advances the canvas.

scene{
    First the data alone.
    ===
    Then the fitted line.
}[
    canvas.graph{
        scatter(points: (1, 2.0), (2, 2.4), (3, 3.1))
        cue{
            fit(model: polynomial; degree: 1)
        }(
            in: 1
        )
    }
]

#Panes and splits

A detail may declare two canvas panes; the scene's direction attribute arranges them — horizontal side by side, vertical stacked — and ratio gives the first pane's share over the second's, written as a fraction like 3/2.

scene{
    A graph beside its code.
}[
    canvas.graph#g{
        curve(expression: x^2)
    }
    canvas.code{
        lines{
            y = x ** 2
        }
    }(
        language: python
    )
](
    direction: horizontal
    ratio: 3/2
)

#Continuing a pane

A pane carries an id on its node — canvas.graph#projectile{...} — and a later scene's pane can point back at it with continue: #projectile. What continues is the session state: reader-manipulated parameters, the fit degree they chose, the view they zoomed to. The authored content is the new pane's own — continue: hands off state, never markup.