views/, and built into a view bundle that the viewer loads.
Visualization and custom renderers explains
how they fit into the viewer, with a small example, and
Designing views covers how a view should look and behave. This page
is the reference for the API they use, fxtr-view, the contract with the viewer, and
fxtr-view-kit, the building blocks, and for the package that builds them.
Registering renderers
renderer(slot, subject, id, Component) from fxtr-view registers a component for a slot and a
subject. The project’s bundle, views/src/bundle.ts, exports its registrations as its default
ViewBundle:
views/src/bundle.ts
The prop types are
EntityPanelProps, EntityViewProps (the id alone), and
InvocationPanelProps. Give each renderer an ID prefixed with your project’s name. Two renderers
for the same slot and subject with the same ID, including a clash with one of the viewer’s own,
keep the whole bundle from loading. Several renderers with different IDs may target the same slot
and subject, and the viewer offers a switcher between them.
Registrations belong in the bundle: a project never changes the viewer itself, its dependencies,
or its registry.
Loading data
unwrap(useEntity(id)) loads an entity’s data, suspending until it arrives, so the component can
assume it is there and leave the loading state to the viewer. The data is the entity’s stored
form: a map of its fields, in which references to other entities arrive as EntityIDs.
A view over many entities, such as a step’s outputs, loads them with the kit’s LoadEach, which
starts every load at once and hands its body the values loaded so far, by idKey(id), with how
many are still pending, so the view fills in as its data arrives. parse turns each entity’s
data into the value the body receives, and must be the same function on every render (defined
outside the component, or memoized). Never call useEntity in a loop.
InvocationPanel is handed every invocation the viewer’s selection picks out (its
invocations prop, each with its key in the run and its output array;
Step panels says what each holds). It must be useful as soon as it is opened,
however many it is handed: a step or child workflow mapped over a dim hands its view every
invocation. Show one in full, and several in a view of their own (an aggregate, or a row or card
each that links to that one alone), never a note asking the reader to select one. A root
workflow’s panel is always given its one invocation.
useInvocation(spawn.ref) loads an invocation’s record, which has the function’s name, its
state and error, its inputs by argument name, and its output, each an array entity’s ID to
load in turn (output is null until there is one). The kit’s invocationInput(invocation, name)
reads a named input, and InvocationOutcome shows a run that has no output yet. Where the view of
several invocations is just the view of each in turn, the kit’s eachInvocation(View) shows a
collapsible section per invocation, each loading its own record when opened and passing it to
View as invocation. (The kit’s singleInvocation(View), which shows a view of one record and
otherwise asks for one invocation to be selected, is deprecated.)
Step panels
A step’sInvocationPanel is its default view: the viewer draws it in the step’s pane, which a
reader opens from the step’s card in the job’s trace. What it is given:
- Spawns, not records.
invocationsholds oneSpawnper invocation the selection picks out: every invocation of the step, or fewer when the reader slices the level’s dims (slice dims). Handle any count. One spawn gets the entity it returned in full, through that entity’s own panel; several get a view of them all (a table, a grid, a chart) whose cells link to the entity behind each. - A key of the mapped and replica dims only, by name:
spawn.key.model,spawn.key.sample.spawnKeyLabel(spawn)fromfxtr-view-kitjoins them into a label. - An output array, null until the invocation has finished. A step returning one entity
returns an array of one row with an empty key:
scalarEntityId(array)reads the reference, andscalarValue(array)reads a struct result. A step with output dims of its own (-> Annotated[Array[Hit], "[rank: int]"]) returns those dims as the array’s rows: read them withrowsOf(array), whosekeys hold the output dims. So a spawn is keyed by the dims the step is mapped over, and its output holds the dims the step introduces. - Inputs on the record.
useInvocation(spawn.ref)loads the spawn’sInvocationRecord: itsstateanderror, and itsinputs, array IDs by argument name (invocationInput(record, "scores")from the kit). A dim the step takes whole (a core dim of an argument, such as the[doc]a ranking step reduces) is in neither the key nor the output; show it from the input. A hook is called a fixed number of times per component, so a view over many spawns’ records loads each in a component of its own, which fills in when its record arrives.
LoadEach, then the entities
they reference with another. A running step’s spawns gain outputs as its invocations finish, and
LoadEach follows them, so the panel fills in while the step runs; say how many have no result
yet. A step mapped over [model, prompt] that returns a Verdict entity:
views/src/judge.tsx
renderer(InvocationPanel, "my_experiment.judge", "my-project.JudgePanel", JudgePanel). eachInvocation suits a view of one invocation’s record repeated per invocation; a
panel that shows many spawns together, like this one, reads them directly.
Live previews
While a step runs, the viewer shows its latest preview in place of its output, and after it fails, the last one under the error. A preview is not a stored entity, so its renderer is handed the value itself,value, instead of an ID; the viewer dispatches on the value’s type tag as
for an entity. A type with no PartialEntityPanel renderer of its own shows the same data tree as a
finished entity’s raw view, with the fields not yet known as null.
Registering a PartialEntityPanel renderer for a type is how a renderer opts in to showing its
values as they stream. partial is true while the value is still being produced: then any field may
be null whatever its type says, a list may be shorter than it will be, and nested
partial values are already unwrapped into
the records they will become. A renderer reading a field unconditionally must treat null as “not
yet”. isPartial(part) from fxtr-view says which parts are still being produced, for one that
shows a part in progress differently (the reply being written, not one just finished); read it on
the value as handed over, since a copy of a part is not marked. live says whether the step is still
running: it is false for the last preview of a step that failed or stopped, whose partial value
will never be finished, so the renderer should not show it as in progress. Share the component with
the type’s EntityPanel renderer, so a value looks the same streaming as finished:
views/src/report.tsx
EntityInlineLink. A PartialEntityInline renderer, given the same props without
storage, says how far the value has got (behaviors’ rollout reads “turn 6 · streaming…”); like an
inline link, it must be static phrasing content. A type with none shows its type name and
“partial”.
Links
Anything that stands for an entity should lead to it. In text and tables,EntityLink({ id }) is
the viewer’s own link: a chip that opens the entity in a pane and shows its preview on hover. A
chart’s mark can’t be a chip, so it uses useEntityLinks(), whose open(id) does what pressing
the entity’s link does, and whose isOpen(id) says whether a pane shows the entity.
Designing views shows how marks use them.
Linking to detail views
A view that opens a detail of something picked in it (a chart’s point, a table’s row) declares the detail as a view of its own, which reads the params the pick adds, and links to it withuseLink. Declare views apart from their components, with declareView(slot, subject, id, options), in a module that imports no components, so views can link to each other without
import cycles:
views/src/views.ts
renderer(SCORES, ScoresPanel) and renderer(FIT, FitPanel). In
ScoresPanel, each mark links to the detail with the row’s keys and the params the detail reads,
by name, and spreads the link’s props onto the element:
target_model, a dim of the step) and the params it declares (proposition; a link that leaves
one out is a type error), and keeps it following the view. Type the detail’s component with
ViewProps<typeof FIT>: its params then binds each declared param (params.proposition), so
the view only checks the values (a string, one of a few names). A param’s value is any JSON (a
string, a number, a list, an object), and nothing checks it before the view gets it, so the view
narrows it itself. useLink returns null where the
viewer cannot open a view from here; the view then shows the detail in place.
Declare a detail within the view that links to it when only that view does: its ID is named
below that view’s (my-project.Scores/fit), and its pane closes when the view before it changes
to another. Declare a detail that several views link to on its own, and link to it from each.
A link can also name a location, relative to the view’s own or absolute, opened in that
location’s default view or a declared one: useLink({ to: "../sibling_step" }, keys),
useLink({ view: REPLIES, to: "/respond" }, keys). A location is a step path from the run’s root
workflow (/score, or /round/judge for a step inside a workflow step), then a field path into
each invocation’s record: .output.call for a field of the step’s output, .inputs.prompt for an
input. From a view of a step, .output… is below it and ../step is a sibling.
An EntityLink to an entity inside what the view was handed says where the entity sits, with
at: <EntityLink id={call} at={{ keys: spawn.key, path: ["call"] }} /> for the call field of
one invocation’s output, or at={{ path: ["messages", 2] }} in an entity’s view. The pane it opens
follows the view as the view moves. For an entity better shown somewhere else (a step’s input,
another step’s output), name the location instead, with to (and view, for a declared view) and
the params it is opened at: <EntityLink id={id} to=".inputs.prompt" params={spawn.key} />. A
link takes one or the other; with neither, it opens the entity alone.
Params of an entity’s views
An entity’s view (anEntityPanel renderer) can read params too, declared the same way:
declareView(EntityPanel, "my_project.Transcript", "my-project.Transcript", { params: ["selector"] }).
They are optional, since the viewer also opens the entity from links that bind none: the
component’s params.selector may be absent. The main use is a selector, a value telling the
view which part of the entity to point out (a message to mark, a span to highlight), much like a
text fragment in a URL. fxtr gives selectors no meaning or shape of their own: a selector is a
param whose value the view decides, usually stored in a field of another entity (a judgment’s
citation, beside the reference to the transcript it cites). A link carries it as params:
at does, and the panes
opened from it don’t inherit them. The pane keeps every param the link passed and hands each of
the entity’s views the ones it declares, whichever is shown, so two views of a type that read the
same param should agree on its shape. A pane’s head shows a short param’s value (a dim’s key, say)
and a longer one’s name alone, and on an entity’s pane a × to clear it. Nothing checks that the
shape the producing step stores matches what the view reads: keep them the same, and have the view
ignore a value it can’t use.
A view of the whole run (a chart across several steps) is a view of the root workflow. A detail
that several views link to and that belongs to no one step can be a page:
declarePage(name, { params }) declares it and page(decl, Component) registers it. A page’s
component is handed the run (run, the root workflow’s invocation), its params, and storage
(PagePanelProps). A page opens only from links to it.
Panel state
A panel’sstorage prop is a JSON value the viewer keeps for the panel while it is open. Keep
what a reader chose in it (a tab, an order, a pick, a filter) with the kit’s
useStoredState(storage, key, initial, isValid?), which works like useState over one key of
it, so the choice survives the view remounting:
isValid, to
reject an obsolete choice or state from another version of the view; a rejected value reads as
the initial one. The initial value and the guard are captured once for each storage and key.
Keep hover and focus in useState. State a component keeps in
useState starts over when a rebuild replaces the renderers; state in storage stays.
Styles
Style a renderer with CSS Modules (*.module.css) beside the components that use them, and with
the kit’s layout classes, over the viewer’s design tokens, so the view follows the viewer’s
light and dark themes. A state or variant is a data-* attribute ([data-state="failed"]), not a
class name built from a value. Designing views lists the tokens and
what each is for.
The kit
fxtr-view is shared with the viewer, which hands its own copy to the bundle; fxtr-view-kit is
bundled with the project. Both are TypeScript source installed in the renderer package’s
node_modules/: read node_modules/fxtr-view-kit/src/ (or fxtr-view/src/) for a signature
this page leaves out, and run pnpm typecheck in views/ (or uv run fxtr views build) to check
every use against them.
From fxtr-view:
From
fxtr-view-kit:
The
fxtr-view-behaviors package has views of behaviors conversation records, for a
project that stores them.
The renderer package
fxtr new writes the renderer package, views/, with an empty bundle. --example fills the
bundle with a panel and an inline link for the example’s greeting, and a results overview of its
workflow with a chart, views/src/overview.tsx. Install
its dependencies once, and commit the views/pnpm-lock.yaml it writes with your project:
Building and reloading
uv run fxtr view builds the package into its view bundle when it starts if the bundle is missing
or stale, and again whenever you save a change to it while it runs. The open viewer then switches
to the new renderers in place, without a reload, keeping the job, level, and panes you have open,
and what each panel keeps in its storage (Panel state).
To build without the viewer:
views/dist/.
A failed build keeps the previous bundle and prints why it failed. Builds use the node on your
PATH, which must be Node 22 or later; fxtr refuses an older one and says how to fix it.
The bundle is an ES module holding the renderers, an optional stylesheet, and a manifest naming
both and recording the version of the view API they were built against. The viewer loads it when
its page loads, checks that version against its own, and adds the bundle’s renderers after its
defaults. React, jotai, and fxtr-view are not bundled in: the viewer hands its own copies to the
bundle, so renderers share the viewer’s hook state and context. Everything else the renderers
import, the kit, a chart library, your own components, is bundled in.
The fxtr packages the renderers import are not on npm. The project carries its own copy in
views/vendor/fxtr/, committed with the project. After upgrading fxtr, refresh the copy and
reinstall before building:
When the bundle doesn’t load
If a renderer build fails, including at startup,fxtr view keeps serving the last valid bundle,
or uses the default renderers when none exists. The side rail and terminal show the error and
the end of the build’s output. Fix the source and save it to trigger another build; the viewer
updates without a restart.
If a bundle fails to load in the browser, the viewer keeps the renderers it already loaded, or
uses its defaults when none were loaded, and the side rail says why.
If fxtr says the bundle was built at another view API version, the renderers were built against
another fxtr’s packages, usually a views/vendor/fxtr/ copy from before you upgraded fxtr. A
release that changes the view API incompatibly bumps that version, and the viewer then refuses
bundles built at the old one. Refresh the copy, reinstall, and rebuild, as above, and fix any
renderer code that used an API the new fxtr-view no longer has.
Adding a package to a project
To add a renderer package to a project without one, write these parts:[tool.fxtr.views] package = "views"inpyproject.toml.views/vendor/fxtr/, the fxtr TypeScript packages:uv run fxtr views vendorcopies them from the installed fxtr. They are TypeScript source; insideviews/, their own imports (React, jotai, one another) resolve toviews/node_modules.views/package.json, linking the fxtr packages from that copy ("fxtr-view": "link:./vendor/fxtr/packages/fxtr-view", and likewisefxtr-view-kit,fxtr-view-bundlefor the build, andfxtr-view-behaviorsif you use it). Its build script is"build": "vite build --configLoader runner", whose flag lets the shared build preset’s TypeScript load; keep it when editing the script. React, jotai, TypeScript, Vite, and@types/nodeare its development dependencies.fxtr views vendornames any registry package a linked fxtr package needs thatpackage.jsonlacks (fxtr-view-shell-utilneeds@ipld/dag-cborandmultiformats).views/pnpm-workspace.yaml, withpackages: ["."]andonlyBuiltDependencies: [esbuild], which gives the package its own installation and lockfile even inside another workspace, and allows esbuild’s install script.views/vite.config.ts, the build, which is always the shared preset’s:export default defineViewBundleConfig({ entry: "src/bundle.ts" }).views/src/bundle.ts, the entry, whose default export is aViewBundle.views/tsconfig.json, extending./vendor/fxtr/tsconfig.base.json, which also declares CSS Modules.node_modules/anddist/in the project’s.gitignore.
fxtr new wrote.
Testing renderers
If you test renderers with Vitest, setresolve.dedupe to
["react", "react-dom", "jotai", "fxtr-view"] in vitest.config.ts, so the linked fxtr packages
use the test environment’s React and context instances.