# StatifierUI v0.11.0 - Table of Contents

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

## Pages

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

- How-to guides
  - [How to embed the ops view in a host LiveView](ops-embedding.md)
  - [How to observe an execution from a LiveView host](observe-an-execution.md)

- Reference
  - [The statifier-ui trace wire format](wire-format.md)

- Explanation
  - [Architecture](architecture.md)
  - [Per-fragment fixture bundles](fixture-bundles.md)
  - [Telemetry and the OTel bridge half](telemetry.md)
  - [Why the viewer speaks a wire format and not the engine](why-a-wire-format.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.Diff](StatifierUI.DatamodelExplorer.Diff.md): What the datamodel gained, lost, or changed between two points in one run
(`sui-2uz`) - the reading that makes stepping through a persisted trace
worth doing, rather than watching a table of current values redraw.
- [StatifierUI.DatamodelExplorer.Diff.Markdown](StatifierUI.DatamodelExplorer.Diff.Markdown.md): Renders a `StatifierUI.DatamodelExplorer.Diff` change list as Markdown a
host hands to `Kino.Markdown.new/1` (`sui-2uz`).
- [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.DeepLink](StatifierUI.EventLog.DeepLink.md): The rendering seam for ADR-0013 correlation: from a macrostep in an
`StatifierUI.EventLog.t()` to a link into the host's APM backend.
- [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.Expression](StatifierUI.Expression.md): The completion source behind the expression-editing component: predicator's
own grammar vocabulary, plus the datamodel paths a host declares.
- [StatifierUI.Fixtures](StatifierUI.Fixtures.md): Example data a host supplies for a chart: named scenario datamodels, example
event payloads, and named datasets for evaluating expressions (ADR-0003,
ADR-0006).
- [StatifierUI.Fixtures.Bundle](StatifierUI.Fixtures.Bundle.md): A fixture bundle that travels with one reusable chart fragment rather than
with a whole chart: the ADR-0003/ADR-0006 bundle plus the fragment's name
and a record of where it was loaded from.
- [StatifierUI.Fixtures.Bundle.Markdown](StatifierUI.Fixtures.Bundle.Markdown.md): Renders one `StatifierUI.Fixtures.Bundle` as the per-fragment "test this
step" panel: what the fragment's expressions evaluate to under each of its
datasets, and whether each expectation it states still holds.
- [StatifierUI.Fixtures.Expectations](StatifierUI.Fixtures.Expectations.md): Runs every `expect` entry a fixture bundle states, evaluates it against its
named dataset, and reports whether the stated value held (ADR-0006). This
is the executable side of the fixture contract: `StatifierUI.Fixtures.Lint`
answers "is this bundle well-formed", this module answers "did every stated
expectation come true".
- [StatifierUI.Fixtures.Lint](StatifierUI.Fixtures.Lint.md): ADR-0006's two lint findings for a fixture bundle: an expression whose
source text matches no compiled guard, and an `expect` key naming no
dataset. Both are warnings, never errors - this module has no
`{:error, _}` return path anywhere in its public API.
- [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.TraceStepper](StatifierUI.Kino.TraceStepper.md): The persisted inspector's render loop (`sui-2uz`): a `GenServer` holding
one immutable message list and the point in it the panes are showing.
- [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.Live](StatifierUI.Live.md): Read-only LiveView components for a host application's ops views: the
current-state diagram and the run-history event log, side by side over
one trace stream in wire format v1 (`docs/wire-format.md`), live or
persisted.
- [StatifierUI.Live.ExpressionInput](StatifierUI.Live.ExpressionInput.md): An expression field with completion: predicator's grammar and the host's
declared datamodel paths, offered at the caret.
- [StatifierUI.Live.State](StatifierUI.Live.State.md): The read model a host LiveView keeps in its socket: a compiled
`Statifier.Machine`, the wire-format v1 messages seen so far, and which
point in the run the panes are showing.
- [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.Capture](StatifierUI.Trace.Capture.md): Record a trace off a live `Statifier.Session`, save it, load it back -
one call each.
- [StatifierUI.Trace.DeepLink](StatifierUI.Trace.DeepLink.md): Builds a URL into a host's APM backend from the wire format's `otel`
correlation key (ADR-0013), so a rendered step can be followed to the
trace that covers it.
- [StatifierUI.Trace.Diagnostic](StatifierUI.Trace.Diagnostic.md): The wire `error` object: what `docs/wire-format.md` documents as an event
object's `error` key.
- [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.Otel](StatifierUI.Trace.Otel.md): The producer half of ADR-0013: stamping a message's `otel` correlation key
from a resolver the host supplies.
- [StatifierUI.Trace.Projection](StatifierUI.Trace.Projection.md): ADR-0012's producer-side projection: the transform that replaces values in
a closed set of value positions with the reserved `{"$redacted": true}`
sentinel while leaving every identity, counter, ordering, and structural
field untouched.
- [StatifierUI.Trace.Projection.Profile](StatifierUI.Trace.Projection.Profile.md): A named projection profile: the two allowlists plus `allow_source`.
- [StatifierUI.Trace.Replay](StatifierUI.Trace.Replay.md): The offline producer of the v1 trace wire format (ADR-0017): a pure
function that turns a persisted session event log into the same
`StatifierUI.Trace.Message` stream `StatifierUI.Trace.Subscriber`
produces from a live session - with no `Statifier.Session`, no process,
and no clock.
- [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.TruthTable](StatifierUI.TruthTable.md): Evaluates a fixture bundle's expressions across its datasets and returns the
result matrix ADR-0006 named: "one expression evaluated across all datasets,
rendered as a result matrix".
- [StatifierUI.TruthTable.Markdown](StatifierUI.TruthTable.Markdown.md): Renders a `StatifierUI.TruthTable.t()` as Markdown a host hands to
`Kino.Markdown.new/1`.
- [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).

- Exceptions
  - [StatifierUI.Fixtures.ExpectationError](StatifierUI.Fixtures.ExpectationError.md): Raised by `StatifierUI.Fixtures.Expectations.check!/2` when one or more
stated `expect` entries did not hold.