Reference¶

Every public Story symbol, one table per namespace, with its signature and a one-line description. Search this page when you know a symbol's name; the topical pages, Registration, Scripts, Runtime and MCP surface, explain how the pieces fit.

re-frame.story carries every surface an author or host calls. The sub-namespaces after it are public, but the shell, its bootstrap or the Xray bridge calls them, not a stories namespace. What is not here lists the internals this page leaves out.

`re-frame.story`¶

The canonical facade. Every user-callable surface lives here.

Registration — macros¶

Symbol	Signature	Intuition
`reg-story`	`(reg-story id metadata)`	Register a story (a cluster of variants).
`reg-variant`	`(reg-variant id metadata)`	Register one variant — view, `:args`, `:setup` events, decorators, `:script`.
`reg-workspace`	`(reg-workspace id metadata)`	Register a workspace — a curated grid of variants.
`reg-decorator`	`(reg-decorator id metadata)`	Register a decorator. Three kinds: `:hiccup` / `:frame-setup` / `:fx-override`.
`reg-story-panel`	`(reg-story-panel id metadata)`	Register a custom panel in the Story chrome. Five placement slots.
`reg-tag`	`(reg-tag id metadata)`	Register a tag. The seven canonical tags and the five `:state/*` tags auto-install.
`reg-mode`	`(reg-mode id metadata)`	Register a mode — a saved tuple of args the chrome toggles into.
`reg-fragment`	`(reg-fragment id metadata)`	Register a fragment — reusable setup, script and world context for `:compose`.
`reg-check`	`(reg-check id metadata)`	Register a check — a named pack of assertions, inherited through `:extends`.

Registration — `*`-suffix runtime helpers¶

Symbol	Signature	Intuition
`reg-story*`	`(reg-story* id body)`	Programmatic story registration.
`reg-variant*`	`(reg-variant* id body)`	Programmatic variant registration. The MCP write surface's `register-variant` tool routes here.
`reg-workspace*`	`(reg-workspace* id body)`	Programmatic workspace registration.
`reg-mode*`	`(reg-mode* id body)`	Programmatic mode registration.
`reg-story-panel*`	`(reg-story-panel* id body)`	Programmatic panel registration.
`reg-decorator*`	`(reg-decorator* id body)`	Programmatic decorator registration.
`reg-tag*`	`(reg-tag* id body)`	Programmatic tag registration.
`reg-fragment*`	`(reg-fragment* id body)`	Programmatic fragment registration.
`reg-check*`	`(reg-check* id body)`	Programmatic check registration.
`valid-variant-id?`	`(valid-variant-id? decomposed-id)` → bool	Whether a decomposed variant id matches the variant id shape, before a keyword is interned.
`unregister!`	`(unregister! kind id)`	Remove a single id under `kind`.
`clear-kind!`	`(clear-kind! kind)`	Remove every registration of `kind`.
`clear-all!`	`(clear-all!)`	Reset every Story registration. Resets the auto-install gate.
`install-canonical-vocabulary!`	`(install-canonical-vocabulary!)`	Idempotent explicit boot, for hosts that want one; the first `reg-*` call installs the vocabulary anyway.

Global args + decorators¶

Symbol	Signature	Intuition
`configure!`	`(configure! opts)` → nil	Top-level config. Map keyed under the closed `:rf.story/*` set (incl. `:rf.story/egress-profile`, the on-box dev-UI egress boundary).
`reg-global-decorator`	`(reg-global-decorator id body)` / `(reg-global-decorator id body ref-args)`	Register a decorator AND opt it into the global stack in one call.
`clear-global-decorator`	`(clear-global-decorator id)`	Remove `id` from the global-decorators vector.
`global-decorators`	`(global-decorators)` → vec	Current ordered vector of global-decorator references.

Built-in decorator `*-id` Vars¶

Symbol	Intuition
`force-fx-stub-id`	Universal fx-mocking primitive — HTTP, websockets, analytics, storage, navigation.
`layout-debug-measure-id`	Storybook-style layout measure overlay.
`layout-debug-outline-id`	Pesticide-style coloured outlines.
`layout-debug-pseudo-id`	Pseudo-state forcing (`:hover` / `:focus` / `:active` / `:visited`).

Execution verbs¶

Symbol	Signature	Intuition
`run`	`(run target)` / `(run target opts)` → promise	Run a registered variant or an inline plan; resolves with the unified run result and never rejects.
`is`	`(is target)` / `(is target opts)` → result (JVM) / promise (CLJS)	Run and report per assertion to `clojure.test` / `cljs.test`.
`report-result!`	`(report-result! result)` → result	Report an already-resolved run result as `is` does.
`explain`	`(explain target)` / `(explain target opts)` → map	How the plan was assembled, without running it. Throws when it cannot compile.
`variant-plan`	`(variant-plan target)` / `(variant-plan target opts)` → plan	The compiled plan `run` executes.
`render-variant`	`(render-variant target)` / `(render-variant target opts)` → map	Render the view from its plan without running the script.

Run results¶

Symbol	Signature	Intuition
`result-status`	`(result-status result)` → keyword	The verdict: `:pass`, `:fail`, `:cannot-run` or `:error`.
`result-passed?`	`(result-passed? result)` → bool	True iff the verdict is `:pass`.
`valid-run-result?`	`(valid-run-result? result)` → bool	Whether a map conforms to `run-result-schema`.
`explain-run-result`	`(explain-run-result result)` → explanation	The Malli explanation of why a map does not conform.
`run-result-schema`	Var	The Malli schema of the unified run result.
`run-result`	`(run-result parts)` → result	Assemble a run result from its parts; the runner's own constructor.
`assertion-record`	`(assertion-record raw)` → map	Normalize one raw assertion record.
`assertion-records`	`(assertion-records raw-assertions)` → vec	Normalize a vector of them.
`aggregate-verdict`	`(aggregate-verdict records unmet)` → keyword	The verdict over records and `:cannot-run` refusals: `:error` over `:fail` over `:cannot-run` over `:pass`.
`result->reports`	`(result->reports result)` → vec	The `clojure.test` report maps `is` fires for a result.

Evidence and hashing¶

Symbol	Signature	Intuition
`project-evidence`	`(project-evidence epoch-tape)` / `(project-evidence epoch-tape opts)` → map	Project a retained epoch tape into the run result's evidence slots.
`tape-shows-failure?`	`(tape-shows-failure? epoch-tape)` / `(tape-shows-failure? epoch-tape consumed-selectors)` → bool	Whether the tape carries failure evidence: a schema violation, a halted epoch or an error effect.
`narrative-beats`	`(narrative-beats narrative)` → vec	Flatten a run's two-level narrative into its beats.
`beat-count`	`(beat-count narrative)` → int	The number of beats.
`beat-at`	`(beat-at narrative idx)` → map	The beat at a 0-based index.
`beat-epoch-ids`	`(beat-epoch-ids narrative)` → vec	The beats' epoch ids, in order.
`canonicalize`	`(canonicalize x)` → value	Strip per-run noise, such as frame ids, timestamps and trace ids, for comparison and hashing.
`canonical-hash`	`(canonical-hash x)` → string	An 8-hex-digit hash of the canonicalized value.
`content-hash`	`(content-hash x)` → string	An 8-hex-digit hash of the exact value.
`plan-hash`	`(plan-hash plan)` → string	The `:plan-hash` of a compiled plan.
`run-hash`	`(run-hash result)` → string	The `:run-hash` of a run result.

Testing primitives¶

Symbol	Signature	Intuition
`make-run-artifact`	`(make-run-artifact parts)` → artifact	Build a `:rf.test/run-artifact` from an event program, or from `:setup` and `:script`.
`run-artifact?`	`(run-artifact? x)` → bool	Whether `x` is a run artifact.
`replay-run-artifact`	`(replay-run-artifact art)` / `(replay-run-artifact art opts)` → result	Replay an artifact into a fresh frame and return its run result.
`assert-deterministic`	`(assert-deterministic artifact-or-program)` / `(assert-deterministic artifact-or-program opts)` → map	Replay into several fresh frames (2 by default) and compare; `:deterministic`, `:non-deterministic` with the first divergence, or `:cannot-run` for a program carrying `[:wait ms]`.
`materialize-variant-plan`	`(materialize-variant-plan artifact)` / `(materialize-variant-plan artifact opts)` → plan	The variant plan a promotion would produce, without registering it.
`promote-run-artifact!`	`(promote-run-artifact! artifact opts)` → variant-id	Register an artifact as a named variant; `opts` must carry `:variant/id`.
`check-property!`	`(check-property! gen-fn opts)` → map	Run a property over generated event programs; on failure, returns the shrunk, seed-bearing artifact.
`sweep-faults!`	`(sweep-faults! base-program fault-lattice opts)` → map	Replay one program across effect-fault cells and collect an artifact per cell.
`diff-run-artifacts`	`(diff-run-artifacts baseline current)` / `(diff-run-artifacts baseline current opts)` → map	A semantic diff of two runs or artifacts, with the per-run noise stripped.
`capture-golden`	`(capture-golden target)` / `(capture-golden target opts)` → golden	Freeze a run's canonicalized behaviour as a golden slice.
`golden-match?`	`(golden-match? golden run)` / `(golden-match? golden run opts)` → bool	Whether a later run matches the golden slice.
`compare-golden`	`(compare-golden golden run)` / `(compare-golden golden run opts)` → map	The same comparison, as a readable report with a diff on mismatch.

Programmatic runtime¶

Symbol	Signature	Intuition
`run-variant`	`(run-variant variant-id)` / `(run-variant variant-id opts)` → promise	Allocate the variant's frame, run the lifecycle, and resolve with the unified run result. The frame stays allocated.
`reset-variant`	`(reset-variant variant-id)` / `(reset-variant variant-id opts)` → promise	Tear the frame down and run the variant again from its declared start.
`watch-variant`	`(watch-variant variant-id callback)` → unsubscribe-fn	Call `callback` with `{:frame-id :from :to :event}` on every lifecycle transition.
`destroy-variant!`	`(destroy-variant! variant-id)`	Tear down the variant's frame. Symmetric with allocation.
`lifecycle-state`	`(lifecycle-state variant-id)` → keyword	Current lifecycle-machine state: `:pre-mount`, `:mounting`, `:loading`, `:ready` or `:error`.
`variant-frames`	`(variant-frames)` → set	Set of variant-ids currently allocated as frames.
`variant-frame?`	`(variant-frame? frame-id)` → bool	Predicate.
`resolve-args`	`(resolve-args variant-id)` / `(resolve-args variant-id opts)` → map	The effective args map (five-layer precedence).
`resolve-decorators`	`(resolve-decorators variant-id)` / `(resolve-decorators variant-id opts)` → map	The resolved decorator stack classified by kind, with `:errors` and `:fingerprints`.
`variants-of`	`(variants-of story-id)` → set	Variant ids whose namespaced id-prefix matches `story-id`.
`variants-by-story`	`(variants-by-story)` → map	Map from parent-story-id to the set of its variant ids.
`variants-with-tags`	`(variants-with-tags tag-set)` → set	Variant ids whose effective tags intersect `tag-set`.
`variant->edn`	`(variant->edn variant-id)` → map	Variant body as serialisable EDN.
`workspace->edn`	`(workspace->edn workspace-id)` → map	Workspace body as serialisable EDN.
`snapshot-identity`	`(snapshot-identity variant-id)` / `(snapshot-identity variant-id opts)` → map	`{:variant-id ... :active-modes [...] :substrate ... :content-hash "<8 hex>"}`. Variant identity for visual-regression keying.
`variant-share-url`	`(variant-share-url variant-id)` / `(variant-share-url variant-id opts)` / `(variant-share-url variant-id base-url opts)` → string	Sharable URL — encodes active modes, cell-overrides and substrate. Without `base-url`, the query string alone.
`static-mode?`	`(static-mode?)` → bool	True iff Story is running in static-export mode.

Registry queries¶

Symbol	Signature	Intuition
`registrations`	`(registrations kind)` → map	All registrations for `kind`, id to body.
`handler-meta`	`(handler-meta kind id)` → any	Registered body for `id`.
`ids`	`(ids kind)` → set	All registered ids of `kind`.
`registered?`	`(registered? kind id)` → bool	Predicate.
`all-kinds-with-counts`	`(all-kinds-with-counts)` → map	Map from each kind → registration count.
`list-tags`	`(list-tags)` → set	All registered tag ids.
`list-modes`	`(list-modes)` → set	All registered mode ids.
`canonical-tags`	Var (set)	The seven canonical tags.
`canonical-axes`	Var (map)	The five canonical tag axes, `:status`, `:role`, `:state`, `:team` and `:feature`, each with `:user-extensible?` and, for the first three, `:values`.
`canonical-status-values`	Var (set)	`#{:alpha :beta :stable :deprecated}`.
`canonical-role-values`	Var (set)	`#{:design :dev :product}`.
`canonical-state-values`	Var (set)	State-axis values: `#{:empty :small :medium :large :special}`.
`canonical-state-tags`	Var (set)	The five `:state/*` tags registered at boot.
`tags-by-axis`	`(tags-by-axis axis)` → set	Registered tag ids whose `:axis` is `axis`.
`tags-without-axis`	`(tags-without-axis)` → set	Registered tag ids that declare no `:axis`.
`tags-default-excluded`	`(tags-default-excluded)` → set	Registered tag ids whose body sets `:default-filter :exclude`.
`tag->axis-index`	`(tag->axis-index)` → map	Map from tag-id → axis.
`registered-substrates`	`(registered-substrates)` → set	Registered substrate ids (CLJS-only).

Assertions¶

Symbol	Signature	Intuition
`read-assertions`	`(read-assertions variant-id)` → vec	Current `:rf.story/assertions` vector.
`assertions-passing?`	`(assertions-passing? result-or-assertions)` → bool	For a run result, whether its verdict is `:pass`; for an assertions vector, whether every record passed.
`canonical-assertion-ids`	`(canonical-assertion-ids)` → set	The eight canonical `:rf.assert/*` ids: the seven assertion events plus `:rf.assert/schema-error`.
`known-assertion-ids`	`(known-assertion-ids)` → set	Every assertion id a plan accepts, including the DOM, browser and causal ids.

Recorder¶

Symbol	Signature	Intuition
`start-recording!`	`(start-recording! variant-id)` → map	Begin capturing canvas-dispatched events; returns the recorder state.
`stop-recording!`	`(stop-recording!)` → map	Stop; returns the recorder state, with the captured `:events`.
`clear-recording!`	`(clear-recording!)` → map	Drop the buffer + return to idle; returns the idle state.
`recording?`	`(recording?)` → bool	Predicate.
`recorder-state`	`(recorder-state)` → map	Read-only view of recorder state.
`gen-play-snippet`	`(gen-play-snippet events opts)` → string	Render captured events as a `(reg-variant ...)` EDN snippet.
`recording->script-body`	`(recording->script-body events)` / `(recording->script-body events opts)` → map	Translate a recording into a `:script` body map.

Privacy — variant-body classification¶

Durable app-db classification is declared on the variant body and lowered into the frame's elision registry as commit-plane classification effects, not via a post-creation mutation surface. A variant declares its sensitive / large paths on its body:

Variant slot	Shape	Intuition
`:sensitive`	`{:app-db [[path...] ...]}`	Sensitive app-db paths — lowered as commit-plane `:sensitive` effects right after frame creation; redact to `:rf/redacted` at every Story observation surface.
`:large`	`{:app-db [[path...] ...]}`	Large app-db paths — lowered as commit-plane `:large` effects; elide to `:rf/large {…}`.

Story does not publish add-marks / set-marks — classification is declared on the variant body and lowered through commit-plane effects.

Substrate registration¶

Symbol	Signature	Intuition
`register-substrate!`	`(register-substrate! substrate-id render-fn)`	Register a substrate render fn (CLJS-only).

Shell lifecycle (CLJS-only)¶

Symbol	Signature	Intuition
`mount-shell!`	`(mount-shell! dom-node)` → handle / nil	Mount the Story shell and return its handle. Production short-circuits before any DOM call.
`unmount-shell!`	`(unmount-shell!)` / `(unmount-shell! handle)`	Unmount the shell. Idempotent.
`active-shell`	`(active-shell)` → map / nil	Inspectable handle on the active shell.

`re-frame.story.recorder.play-export`¶

The rich DOM-capture-aware recorder translator. Sub-namespace require — the facade exposes only the simpler gen-play-snippet projection.

Symbol	Signature	Intuition
`recording->script-body`	`(recording->script-body events)` / `(recording->script-body events opts)` → map	Translate captured events or `:entries` into a normalised `:script` body map. `opts` takes `:name`, `:auto-run?`, `:auto-assert?` with `:final-db`, `:seed-db` and `:max-auto-assertions`, `:wait-threshold-ms` and `:cofx`.
`render-script-body`	`(render-script-body body)` → string	Render the `:script` body map to EDN.
`render-variant-form`	`(render-variant-form body {:keys [variant-id alias extends]})` → string	Render a full `(reg-variant ...)` form around a `:script` body to EDN.

`re-frame.story.ui.xray-embed`¶

The Xray-RHS embed component. Reach here from the embed component or the Xray preset, rarely from app code.

Symbol	Kind	Audience	Intuition
`xray-embed-panel`	Reagent component	`user-app` (rare) / `chrome-shell`	The RHS Xray-host Reagent component. Renders the chip-row picker plus the Xray panel-host `<div>`. Shows a "Select a variant to inspect via Xray." placeholder when no variant is focused; there is no absent-Xray state, since `day8/re-frame2-xray` is a declared Story dependency.
`mount-fn-for`	Pure dispatch fn	`chrome-shell`	`(mount-fn-for panel-id)` returns the Xray `mount-<panel>!` fn for `panel-id` (one of the chip panels `:epoch` / `:app-db` / `:views` / `:trace` / `:machines` / `:routing`, or `:event-spine`, the recent-events strip above them), or nil for an unknown id. Compile-time symbol resolution.
`popout-full-shell!`	User-callable lifecycle	`user-app`	Pop out the full Xray 4-layer shell into a second window. Xray is a declared Story dependency, so the popout symbol is always on the classpath; the only gate is Story's own elision posture.

`re-frame.story.xray-preset`¶

The chrome / Xray bridge.

Symbol	Kind	Audience	Intuition
`wire-cross-host!`	Internal bridge	`chrome-shell`	Bridges-only host-wiring helper called by the shell on every variant selection. Threads through Xray's host-installation hooks (project-root, keybinding) but does NOT mount Xray.
`propagate-project-root!`	Internal bridge	`chrome-shell`	Bridges Story's `:rf.story/project-root` from `configure!` into Xray's `:rf.xray/project-root` slot so Xray-as-RHS source-coord chips share the same on-disk root.

`re-frame.story.theme.*`¶

The design-token namespaces. Public for third-party Story-panel authors; chrome consumes tokens, not raw literals. Panel authors will find the per-namespace contracts in 016-Design-Tokens.md.

Namespace	Surface	Purpose
`re-frame.story.theme.typography`	`sans-stack`, `mono-stack`, `display-stack`, `type-scale`, `weights`, `inject-font-faces!`	IBM Plex Sans + Mono stacks. Inject `local()`-only `@font-face` rules at shell mount.
`re-frame.story.theme.colors`	`tokens`	Semantic colour map (`:bg-1` / `:text-primary` / `:accent-amber` / `:danger` / `:tag-*-bg` / ...).
`re-frame.story.theme.motion`	`timing`, `easing`, `transitions`	Duration / easing maps + pre-composed transitions. Honours `prefers-reduced-motion`.
`re-frame.story.theme.depth`	`shadows`	Elevation shadow scale (`:elev-1` / `:elev-2` / ...).
`re-frame.story.theme.glyphs`	`story-glyph`, `variant-glyph`, `workspace-glyph`, `chevron-right`, `external-link`	Inline-SVG glyph fns. Draws via `currentColor`.

Token contract¶

No raw font-family at call sites. Chrome consumes sans-stack / mono-stack / display-stack; raw font-family literals are banned.
No raw hex literals at call sites. Chrome consumes (:token-name colors/tokens); raw #xxxxxx literals are banned.
No raw transition literals at call sites. Chrome consumes (:row motion/transitions); raw transition strings are banned.
prefers-reduced-motion: reduce is honoured. Chrome motion falls back to static states behind the user-agent media query.

`re-frame.story.ui.keybindings`¶

The chrome's keybinding registry + installer pair.

Symbol	Kind	Audience	Intuition
`bindings`	Pure data table	`pure-data-for-help`	Canonical `{key → handler}` table for the chrome-visibility hotkeys (`f` / `s` / `a` / `t`).
`shortcut-keys`	Pure data → data	`pure-data-for-help`	The sorted list of bound keys. Consumed by the first-visit help overlay.
`install!`	Installer	`chrome-shell`	Install the single `window#keydown` capture-phase listener. Idempotent.
`remove!`	Installer	`chrome-shell`	Symmetric teardown.

Coeffects registered by Story¶

Declared under :rf.cofx/requires; the same two ids are registered as subscriptions.

Cofx id	Shape	Notes
`:story/active-modes`	`[<mode-id> ...]`	Chrome-toolbar's active mode-set.
`:story/active-args`	`{<arg-key> <value>}`	Deep-merge of all active modes' `:args`.

Canonical assertion events¶

The seven :rf.assert/* events the auto-install registers at first reg-*. The eighth canonical id, :rf.assert/schema-error, is evaluated against the epoch tape rather than dispatched (Scripts).

Event id	Payload	Semantics
`:rf.assert/path-equals`	`[path expected]`	`(= (get-in @app-db path) expected)`
`:rf.assert/path-matches`	`[path malli-schema]`	`(m/validate schema (get-in @app-db path))`
`:rf.assert/sub-equals`	`[sub-vec expected]`	`(= @(subscribe sub-vec) expected)`
`:rf.assert/dispatched?`	`[event-vec]` / `[event-id]` / `[pred]`	Was a matching event dispatched during the run, in setup or script?
`:rf.assert/state-is`	`[machine-id state]`	Active state of `reg-machine` machine-id is state.
`:rf.assert/no-warnings`	`[]`	No warning-severity trace event (`:op-type :warning`) captured during play — any operation namespace, not only `:rf.warning/*`.
`:rf.assert/effect-emitted`	`[fx-id]` / `[fx-id pred]`	Did the variant's drain emit fx-id? Optional unary `pred` over the fx-id keyword.

What this reference deliberately omits¶

Several surfaces are publicly visible in the CLJS source but explicitly not part of the contract. They're documented in the developer-internal spec for Story's maintainers; this reference omits them.

re-frame.story.ui.url-state engine. url-from-state, params-from-state, embed-flag-from-current-url, hydrate-embed-flag! — chrome-internal URL surfaces. The facade exposes variant-share-url; the other two URL surfaces (address-bar URL, embed flag) live in this sub-ns and are consumed by the shell's bootstrap.
Story's late-bind shims. re-frame.story.late-bind — the indirection that breaks circular requires between the registrar (consumer) and the canonical installer (producer).
Panel-mount aggregators. Story's shell calls mount-<panel>! aggregators internally; they're not part of the host-facing embed contract.
re-frame.story.config atom handles. Every state setter writes to a defonce atom; the atoms are reachable from CLJS-default-public visibility. The setters in configure! are the canonical write path.

A symbol these pages do not list is internal, and a later release may rename it or make it private. Use the documented surfaces instead.