Skip to main content
A project’s renderers are React components, written in TypeScript in the project’s renderer package, 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.
An 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’s InvocationPanel 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. invocations holds one Spawn per 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) from fxtr-view-kit joins 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, and scalarValue(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 with rowsOf(array), whose keys 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’s InvocationRecord: its state and error, and its inputs, 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.
Load the outputs in two stages: the spawns’ output arrays with one 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
Register it with 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
The value changes as new previews arrive without remounting the component, so its state survives. A renderer that throws on a preview falls back to the data tree, with its error above it. A running step’s row in a run’s table shows the preview in one line, where a finished row shows its result’s 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”. 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 with useLink. 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
Register a declared view with 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:
The viewer opens the detail beside the view, hands it the invocations its params pick out (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 (an EntityPanel 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:
A link with params opens the entity alone, and stays on it: the params are about that one entity, so it doesn’t follow the view it was opened from as a link with 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’s storage 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:
Stored values are trusted as the initial value’s type unless you pass a type guard, 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:
This runs the package’s build and, if the result checks out, replaces the bundle in 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" in pyproject.toml.
  • views/vendor/fxtr/, the fxtr TypeScript packages: uv run fxtr views vendor copies them from the installed fxtr. They are TypeScript source; inside views/, their own imports (React, jotai, one another) resolve to views/node_modules.
  • views/package.json, linking the fxtr packages from that copy ("fxtr-view": "link:./vendor/fxtr/packages/fxtr-view", and likewise fxtr-view-kit, fxtr-view-bundle for the build, and fxtr-view-behaviors if 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/node are its development dependencies. fxtr views vendor names any registry package a linked fxtr package needs that package.json lacks (fxtr-view-shell-util needs @ipld/dag-cbor and multiformats).
  • views/pnpm-workspace.yaml, with packages: ["."] and onlyBuiltDependencies: [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 a ViewBundle.
  • views/tsconfig.json, extending ./vendor/fxtr/tsconfig.base.json, which also declares CSS Modules.
  • node_modules/ and dist/ in the project’s .gitignore.
Then install its dependencies and commit the lockfile, as for a package fxtr new wrote.

Testing renderers

If you test renderers with Vitest, set resolve.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.