Spectra

Spectra: typed Prism presentations lowered to deterministic Typst.

A deck is an ordinary immutable value: metadata, a theme, and a list of slides whose bodies are Pict layout values. Everything else is a projection of that value, so building one is just building data:

fn main() =
  let d = make_deck(
      metadata("Prism in Six Slides", "sdiehl"),
      prism_theme,
      [titled_slide("Hello", item("A deck is a value."))],
    )
  match d.slides of
    Cons(s, Nil) =>
      match s.title of
        Some(t) => println(t)
        None => ()
    _ => ()

Hello

The effectful deck/slide/pict builders elaborate to this same pure representation; render_typst lowers a deck to a Typst document, and the standalone spectra executable (see SpectraCli) drives the pipeline through to a PDF. Slides can quote their own source through reflect fn, which is what makes a deck that explains its own code an ordinary program.

Types

Metadata

type Metadata = Metadata {
  title: String,
  author: String,
  subject: String
} deriving (Eq, Show)

A deck’s document metadata.

Slide

type Slide = Slide {
  title: Option(String),
  body: Pict,
  notes: List(String)
} deriving (Eq, Show)

One slide: an optional title, a body picture, and presenter notes.

Deck

type Deck = Deck {
  metadata: Metadata,
  theme: Theme,
  slides: List(Slide)
} deriving (Eq, Show)

A whole presentation: metadata, theme, and slides in order.

Effects

SlideBuilder

effect SlideBuilder
  place(Pict) : Unit
  reveal(Unit) : Unit

DeckBuilder

effect DeckBuilder
  add_slide(Slide) : Unit

The deck authoring surface: emit a finished slide.

Functions and Values

text

text : (String) -> Layout.Pict

rich_text

rich_text : (List(Layout.Inline)) -> Layout.Pict

Rich inline text in the theme foreground.

para

para : (List(Layout.Inline)) -> Layout.Pict

A paragraph-sized inline sequence.

plain

plain : (String) -> Layout.Inline

Literal characters, escaped by the backend.

emphasis

emphasis : (List(Layout.Inline)) -> Layout.Inline

An emphasized inline span.

strong

strong : (List(Layout.Inline)) -> Layout.Inline

A strongly emphasized inline span.

link

link : (String, List(Layout.Inline)) -> Layout.Inline

An inline span linking to url.

colored

colored : (String, List(Layout.Inline)) -> Layout.Inline

An inline span in the theme color role name.

item_text

item_text : (List(Layout.Inline)) -> Layout.Pict

A bullet item rendered as an accent arrow and rich inline text.

item

item : (String) -> Layout.Pict

A plain bullet item.

row

row : (Int, List(Layout.Pict)) -> Layout.Pict

Children laid out left to right, gap points apart.

column

column : (Int, List(Layout.Pict)) -> Layout.Pict

Children laid out top to bottom, gap points apart, left aligned.

centered

centered : (Int, List(Layout.Pict)) -> Layout.Pict

Children laid out top to bottom, gap points apart, centered.

overlay

overlay : (List(Layout.Pict)) -> Layout.Pict

Children stacked on one another, first at the back.

inset

inset : (Int, Layout.Pict) -> Layout.Pict

A child padded by all points on every side.

raw_typst

raw_typst : (String) -> Layout.Pict

Typst source admitted verbatim, escaping nothing.

code_block

code_block : (String, String) -> Layout.Pict

A highlighted code block in language.

prism_code

prism_code : (String) -> Layout.Pict

A highlighted block of Prism source.

inline_code

inline_code : (String) -> Layout.Inline

An inline code span in the theme code face.

doctest

doctest : (String) -> Layout.Pict

Every example a reflected declaration’s docstring fences, each over the output the doctest runner proves it prints.

definition

definition : (String) -> Layout.Pict

A reflected declaration with its comment block removed.

read_doc

read_doc : (String) -> Example.Doc

Take a reflected declaration apart into prose, examples, and the declaration itself.

examples_of

examples_of : (String) -> List(Example.Example)

The examples a reflected declaration’s docstring fences.

example_pict

example_pict : (Example.Example) -> Layout.Pict

One example as its source over the output it prints.

prism_theme

prism_theme : Theme.Theme

The default theme: a purple accent on warm near-white.

paper_theme

paper_theme : Theme.Theme

A print theme with a slightly darker accent.

prism_dark_theme

prism_dark_theme : Theme.Theme

The dark palette, for code-heavy talks.

max_stage

max_stage : (Layout.Pict) -> Int

The highest reveal stage any fragment in a picture is attached to.

pict_assets

pict_assets : (Layout.Pict) -> List(String)

Every asset path a picture refers to.

render_pict

render_pict : (Layout.Pict, Int, Theme.Theme) -> String

The Typst source for a picture at one reveal stage under a theme.

render_slide_page

render_slide_page : (Option(String), Layout.Pict, Int, Theme.Theme) -> String

The Typst source for one slide page at one reveal stage.

typst_prelude

typst_prelude : (Theme.Theme) -> String

The Typst preamble a theme’s page and text settings compile to.

metadata

metadata : (String, String) -> Metadata

Deck metadata from a title and an author, leaving the subject empty.

make_deck

make_deck : (Metadata, Theme.Theme, List(Slide)) -> Deck

A deck from its metadata, its theme, and its slides.

title_slide

title_slide : (String, String) -> Slide

A cover slide: a large accented title over a muted subtitle, centered.

titled_slide

titled_slide : (String, Layout.Pict) -> Slide

A slide with a title and a body picture.

pict

pict : (Layout.Pict) -> Unit ! {SlideBuilder}

Place a picture into the slide being built.

reveal_next

reveal_next : () -> Unit ! {SlideBuilder}

Advance the reveal stage, so what follows appears on a later page.

slide

slide : (String, () -> Unit ! {SlideBuilder}) -> Unit ! {DeckBuilder}

Emit a built slide into the surrounding deck builder.

cover

cover : (String, String) -> Unit ! {DeckBuilder}

Emit a cover slide into the surrounding deck builder.

deck

deck : (Metadata, Theme.Theme, () -> Unit ! {DeckBuilder}) -> Deck

Run the effectful authoring surface into the same pure Deck used by the data-first API.

render_typst

render_typst : (Deck) -> Backend.TypstDocument

Pure, deterministic Typst lowering. Logical slides with reveals expand to one physical PDF page per stage.

envelope

envelope : (Deck) -> String

The exact one-line envelope consumed by the spectra host frontend.

emit_deck

emit_deck : (Deck) -> Unit ! {IO}

Emit exactly one framed envelope. The host rejects any extra output, so a stray debug print can never be interpreted as Typst source.