# StatifierUI v0.1.0 - Table of Contents

> UI components for authoring, observing, and debugging statifier statecharts

## Pages

- [StatifierUI](readme.md)
- [Changelog](changelog.md)

- Guides
  - [Architecture](architecture.md)
  - [The statifier-ui trace wire format](wire-format.md)

- Architecture Decision Records
  - [Architecture Decision Records](adr-index.md)
  - [ADR-0001: Record architecture decisions](0001-record-architecture-decisions.md)
  - [ADR-0002: Adopt upstream statifier and predicator decisions by reference](0002-adopt-upstream-decisions-by-reference.md)
  - [ADR-0003: Fixtures as the example-data contract](0003-fixtures-as-the-example-data-contract.md)
  - [ADR-0004: One package with optional integrations](0004-one-package-with-optional-integrations.md)
  - [ADR-0005: Language-neutral trace wire format](0005-language-neutral-trace-wire-format.md)
  - [ADR-0006: Datasets and expression fixtures](0006-datasets-and-expression-fixtures.md)
  - [ADR-0007: Text-first authoring](0007-text-first-authoring.md)
  - [ADR-0008: Client-side elkjs layout rendering plain SVG](0008-client-side-elkjs-layout.md)
  - [ADR-0009: JavaScript ships as source](0009-javascript-ships-as-source.md)
  - [ADR-0010: Cross-repo tracker authority and mirrors](0010-cross-repo-tracker-authority-and-mirrors.md)
  - [ADR-0011: Exit and entry sets are sequences, not sets](0011-exit-and-entry-sets-are-sequences.md)

## Modules

- [StatifierUI](StatifierUI.md): UI components for authoring, observing, inspecting, and debugging
[statifier](https://github.com/riddler/statifier-ex) statecharts.
- [StatifierUI.DatamodelExplorer](StatifierUI.DatamodelExplorer.md): The datamodel explorer pane (`sui-t36.7`): one component, two data
sources. **Authoring mode** (`build_authoring/3`) merges the mode-
independent tiers `StatifierUI.DatamodelExplorer.Scope` builds - document
`<data id>` declarations (tier 1), the SCXML 5.10.1 system variables
(tier 2a), the predicator provider functions in scope (tier 2b) - with
one named fixture scenario (tier 3), the one tier that switches source
between modes (ADR-0003:82-88). **Live mode**'s `build_live/2` is
`sui-t36.7` Phase 3's addition to this same module.
- [StatifierUI.DatamodelExplorer.Entry](StatifierUI.DatamodelExplorer.Entry.md): One node in the datamodel explorer tree (`sui-t36.7`): a `<data>`
declaration, a system variable, a provider function, a fixture scenario
value, or a runtime-only location - the ADR-0003 tiers, plus live mode's
`:runtime` sibling for a location `session.datamodel` never named.
- [StatifierUI.DatamodelExplorer.Markdown](StatifierUI.DatamodelExplorer.Markdown.md): Renders a `StatifierUI.DatamodelExplorer.t()` as Markdown a host hands to
`Kino.Markdown.new/1`, per the `sui-t36.7` plan's Phase 4.
- [StatifierUI.DatamodelExplorer.Scope](StatifierUI.DatamodelExplorer.Scope.md): The three ADR-0003 tiers that do not switch source between authoring and
live mode: document `<data id>` declarations (tier 1), the SCXML 5.10.1
system variables (tier 2a), and the predicator provider functions in
scope (tier 2b). All three come from a compiled `%Statifier.Machine{}`
and two engine constants - no session, no fixtures, no wire messages.
- [StatifierUI.Diagram](StatifierUI.Diagram.md): Renders a compiled `Statifier.Machine` and an active configuration as
Mermaid `stateDiagram-v2` source, for display via `Kino.Mermaid` (or any
other Mermaid consumer - this module is pure and depends on neither Kino
nor LiveView).
- [StatifierUI.EventInjection](StatifierUI.EventInjection.md): The pane model behind the inspector's event-firing form: a palette built
from a fixture bundle's `events` map (`StatifierUI.EventInjection.Palette`),
a `free_form_only?` flag for the degraded mode the bead requires when there
are no fixtures to draw buttons from, and the one send path every submitted
form goes through.
- [StatifierUI.EventInjection.Draft](StatifierUI.EventInjection.Draft.md): Turns a form's two free-form fields - an event name and a payload text -
into a `Statifier.Event.t()`, the ordinary recordable input
(`Statifier.Event.external/2`) rather than a side door.
- [StatifierUI.EventInjection.Entry](StatifierUI.EventInjection.Entry.md): One fixture event, rendered as a palette button: an event name, its sample
payload verbatim, and the ADR-0005 JSON text a form prefills the payload
field with.
- [StatifierUI.EventInjection.Palette](StatifierUI.EventInjection.Palette.md): A fixture bundle's `events` map (ADR-0003), turned into a sorted list of
`StatifierUI.EventInjection.Entry.t()` a form can render as buttons.
- [StatifierUI.EventLog](StatifierUI.EventLog.md): Folds a `[StatifierUI.Trace.Message.t()]` (in any order) into a readable
log keyed by `(macrostep, round)`, per the sui-t36.5 plan.
- [StatifierUI.EventLog.Labels](StatifierUI.EventLog.Labels.md): Turns the wire format's integer indexes into strings a human can read,
using only the `session.start` tables already on the stream
(`lib/statifier_ui/trace/manifest.ex:120-211`).
- [StatifierUI.EventLog.Macrostep](StatifierUI.EventLog.Macrostep.md): One macrostep's worth of an `StatifierUI.EventLog.t()`: its rounds, its
round-less `effect.*` messages, and two summaries derived from its rounds
rather than carried on any single message.
- [StatifierUI.EventLog.Markdown](StatifierUI.EventLog.Markdown.md): Renders a `StatifierUI.EventLog.t()` as Markdown a host hands to
`Kino.Markdown.new/1`, per the sui-t36.5 plan's Phase 3.
- [StatifierUI.EventLog.Round](StatifierUI.EventLog.Round.md): One `(macrostep, round)` bucket of an `StatifierUI.EventLog.t()`.
- [StatifierUI.Fixtures](StatifierUI.Fixtures.md): Example data a host supplies for a chart: named scenario datamodels and
example event payloads (ADR-0003).
- [StatifierUI.Fixtures.Sidecar](StatifierUI.Fixtures.Sidecar.md): Reads a `<chart>.fixtures.json` sidecar (ADR-0003) and produces the same
`StatifierUI.Fixtures` struct the behaviour-based delivery path produces.
- [StatifierUI.Fixtures.Source](StatifierUI.Fixtures.Source.md): Behaviour for a host-application module that supplies fixture data.
- [StatifierUI.Inspector](StatifierUI.Inspector.md): Pure pane assembly for the Livebook inspector: folds a compiled
`Statifier.Machine` and a `StatifierUI.Trace.Subscriber` message list
into the render source each pane displays - Mermaid source for the
configuration diagram, Markdown for the event log and the datamodel
explorer, and a status line from the subscriber's `stats/1` snapshot.
- [StatifierUI.Kino](StatifierUI.Kino.md): The Livebook inspector: `inspect/3` composes the four panes -
configuration diagram, datamodel explorer, event injection, event
log - over one shared `StatifierUI.Trace.Subscriber`, attached with
catch-up (statifier ADR-0049), inside one `Kino.Layout`.
- [StatifierUI.Kino.Updater](StatifierUI.Kino.Updater.md): The inspector's render loop: a `GenServer` registered as the shared
subscriber's listener, re-rendering every frame from the subscriber's
buffer on a coalesced tick (one render at most every 80 ms, however
fast messages arrive). Started via
`Kino.start_child/1` by `StatifierUI.Kino.inspect/3`, and terminated
with the cell - which is what detaches the inspector.

- [StatifierUI.Shape](StatifierUI.Shape.md): Infers a structured shape from a predicator value, and renders that shape
as a display label.
- [StatifierUI.Trace.Buffer](StatifierUI.Trace.Buffer.md): A fixed-capacity, drop-oldest store of `%StatifierUI.Trace.Message{}`
values - the memory-safety mechanism a chatty session needs so a notebook
does not grow without bound (decision 8 of the plan).
- [StatifierUI.Trace.Json](StatifierUI.Trace.Json.md): The canonical JSON encoder that makes ADR-0005's byte-comparable golden
traces real.
- [StatifierUI.Trace.Manifest](StatifierUI.Trace.Manifest.md): Turns a compiled `%Statifier.Machine{}` plus caller-supplied context into
the `session.start` definition message (`docs/wire-format.md`) - the
message that makes every later index (state `index`, `t_index`,
`c_index`, `d_index`) resolvable to a source location without a compiler
on the reading end.
Pure, no process.
- [StatifierUI.Trace.Message](StatifierUI.Trace.Message.md): One message of the trace wire format (`docs/wire-format.md`), held as a
struct in process and rendered to the documented JSON object by `to_map/1`.
- [StatifierUI.Trace.Normalizer](StatifierUI.Trace.Normalizer.md): The pure mapping from `Statifier.Effect.t()` (and the session's own
lifecycle messages) to `StatifierUI.Trace.Message.t()`, matching
`docs/wire-format.md` field for field. No process, no session, no
`%Statifier.Machine{}` - the whole vocabulary is testable from a struct
literal.
- [StatifierUI.Trace.Subscriber](StatifierUI.Trace.Subscriber.md): The only `GenServer` in this bead - it owns attach and detach, `seq`
stamping, the `session.start` manifest emission, session-death handling,
and the bounded buffer, and fans every message out to registered
listeners. Everything else under `lib/statifier_ui/trace/` is a pure
module; this is the process that wires them to a live
`Statifier.Session`.
- [StatifierUI.Value](StatifierUI.Value.md): Codec for ADR-0005's JSON encoding of the value domain predicator's
`Predicator.Types` module defines (its `value/0` type).

