tangl.story.episode

Traversable node and edge types that define the story cursor vocabulary.

Related design docs

Related notes

Episode nodes

class Block[source]

Primary interactive cursor node in a runtime story graph.

Why

Blocks are the units a player or consumer actually visits. They hold the authored narrative content together with local action, role, setting, and media declarations that journaling and provisioning consume.

Key Features

  • Carries authored prose in content.

  • Stores local action, continue, and redirect declarations that later materialize into traversable edges.

  • Declares local roles, settings, and media used by namespace and render handlers.

API

  • content stores authored narrative text.

  • actions, continues, and redirects hold authored navigation declarations.

  • roles, settings, and media hold local provider and presentation declarations.

class Scene[source]

Container node that groups blocks into a traversable narrative segment.

Why

Scenes provide the structural scope that blocks, roles, and settings hang from. They also maintain source and sink pointers so container traversal is deterministic once children are materialized.

Key Features

  • Groups blocks into a shared traversal and namespace scope.

  • Carries scene-level role and setting declarations.

  • Owns source/sink cursor pointers used by container traversal.

API

  • title stores the authored scene heading.

  • roles and settings hold scene-scope provider declarations.

  • finalize_container_contract() derives missing source/sink ids from current child order.

class Action[source]

Traversable choice edge connecting story blocks.

Why

Action carries both user-facing choice text and authored successor semantics, allowing the compiler and materializer to preserve the narrative meaning of redirects, continuations, and interactive choices.