Skip to content

Generative UI API

ui

Generative UI primitives — agents that design their own surface.

The agent emits a typed :class:UIComponentSpec; the frontend resolves a renderer by component_type and hot-loads it. Subsequent state updates flow as :class:UIDeltaEvent records on the same SSE stream.

See :doc:/concepts/generative_ui for the full picture; this module hosts:

  • :class:UIComponentSpec[T] + :class:UIDeltaEvent + :data:UIDeltaOp — the protocol primitives.
  • :class:ComponentRegistry — per-Workbench schema registry.
  • :class:UIEmitter — convenience facade for emitting init/delta/remove events on an :class:EventBus.
  • First-party components organised in three layers:

  • Compositional primitives: :class:PlanComponent, :class:ChartComponent, :class:TableComponent, :class:FormComponent, :class:TakeoverDialogComponent, :class:LayoutComponent, :class:TextComponent, :class:MarkdownComponent, :class:ImageComponent, :class:BadgeComponent, :class:ButtonComponent, :class:InputComponent, :class:StatTileComponent, :class:ChecklistComponent, :class:TimelineComponent, :class:MapComponent, :class:MediaComponent.

  • Declarative grammars: :class:VegaChartComponent, :class:MermaidComponent, :class:LatexComponent, :class:JsonViewerComponent.
  • Sandboxed escape hatch: :class:SandboxedHTMLComponent.

UIDeltaOp module-attribute

UIDeltaOp = Literal['replace', 'merge', 'append', 'remove']

Op set for partial component updates.

  • replace — set value at path to value (RFC 6902 replace).
  • merge — shallow-merge value (a dict) into the dict at path; if value-at-path is not a dict, behaves like replace.
  • append — append value to the list at path. Required for streaming-append components (chart series, table rows).
  • remove — delete the field/element at path. value ignored.

BadgeComponentData

icon class-attribute instance-attribute
icon: str | None = None

lucide-react icon name. The frontend resolves the symbol; if the icon is unknown it falls back to label-only.

ButtonComponentData

event_name class-attribute instance-attribute
event_name: str = 'ui.button.clicked'

The event_type the frontend POSTs back when the button is clicked. The agent subscribes to this via the SSE bus + event-loop integration.

ChartComponentData

config class-attribute instance-attribute
config: dict[str, Any] = Field(default_factory=dict)

Free-form renderer-specific knobs (axis formatters, colour scheme, etc.). Not load-bearing for the protocol.

ChartSeries

One labelled data series. Points are dicts so the renderer can pick out the relevant axes (e.g. {"x": ..., "y": ...}).

ChecklistComponentData

action class-attribute instance-attribute
action: str = 'toggle'

ui.action name the renderer sends when an item is ticked.

FormComponentData

submit_event class-attribute instance-attribute
submit_event: str = 'form.submitted'

The event_type the frontend should emit (back to the agent) on submission. Decoupled from the component_type so multiple forms can share a single rendering path.

FormField

options class-attribute instance-attribute
options: list[str] = Field(default_factory=list)

For select / multiselect — the available choices.

InputComponentData

rows class-attribute instance-attribute
rows: int | None = None

Textarea row count (ignored for other kinds).

accept class-attribute instance-attribute
accept: str | None = None

File mime/extension filter (e.g. "image/*" or ".csv,.tsv").

JsonViewerComponentData

data class-attribute instance-attribute
data: Any = None

Any JSON-serialisable structure (object, array, scalar).

expanded_paths class-attribute instance-attribute
expanded_paths: list[str] = Field(default_factory=list)

Paths to expand by default (e.g. ["", "items.0"]).

LatexComponentData

content instance-attribute
content: str

LaTeX source rendered via KaTeX. Use display=True for block math, False for inline.

LayoutComponentData

gap class-attribute instance-attribute
gap: int = 8

Tailwind spacing unit. 8 ≈ 0.5rem (matches existing Polymath UI).

grid_columns class-attribute instance-attribute
grid_columns: int | None = None

Number of columns for direction="grid" (ignored otherwise).

LessonStepComponentData

media_url class-attribute instance-attribute
media_url: str | None = Field(
    default=None, description="https:// only."
)

Optional picture or clip; https:// only, like media.

voice_hint class-attribute instance-attribute
voice_hint: str | None = Field(
    default=None,
    description="Text a renderer may speak for this step.",
)

Text a renderer may speak for this step.

MarkdownComponentData

content instance-attribute
content: str

GFM markdown — tables, code, links, images. Frontend uses react-markdown + remark-gfm + the existing CodeBlock renderer.

MediaComponentData

poster class-attribute instance-attribute
poster: str | None = None

Preview frame; video only.

MermaidComponentData

diagram instance-attribute
diagram: str

Mermaid source. flowchart / sequence / classDiagram / erDiagram / gantt / mindmap / etc.

PathwayComponentData

action class-attribute instance-attribute
action: str | None = Field(
    default=None,
    description="ui.action name the renderer sends when the pathway is opened.",
)

ui.action name the renderer sends when the pathway is opened.

PlanComponentData

Data payload — list of :class:PlanTask records.

SandboxedHTMLComponentData

html instance-attribute
html: str

Raw HTML / SVG / restricted JS. Rendered in an iframe with sandbox="allow-scripts" and a strict CSP. No parent-document access, no network unless allowed via the iframe csp.

height_px class-attribute instance-attribute
height_px: int = 400

Fixed height in CSS pixels — iframes don't auto-size.

csp_extra class-attribute instance-attribute
csp_extra: str = ''

Additional CSP directives merged onto the default. Empty by default.

StatTileComponentData

trend class-attribute instance-attribute
trend: float | None = None

Signed change versus the previous period.

TableColumn

key instance-attribute
key: str

Row-dict key the renderer reads to populate this column.

TakeoverDialogData

choices class-attribute instance-attribute
choices: list[str] = Field(default_factory=list)

For choice kind — the offered options.

VegaChartComponentData

spec class-attribute instance-attribute
spec: dict[str, Any] = Field(default_factory=dict)

Full Vega-Lite spec (https://vega.github.io/vega-lite/). The frontend imports vega-embed and renders. The agent emits the JSON directly — Vega-Lite syntax is well-documented and the LLM is typically familiar with it.

UIEmitter

UIEmitter(
    bus: EventBus | None = None, *, agent_name: str = "ui"
)

Facade for publishing :class:UIComponentSpec and :class:UIDeltaEvent events on a :class:EventBus.

Source code in orqest/ui/emitter.py
def __init__(
    self,
    bus: EventBus | None = None,
    *,
    agent_name: str = "ui",
) -> None:
    self._bus = bus
    self._agent_name = agent_name
init async
init(
    component: UIComponentSpec[Any],
    *,
    agent_name: str | None = None,
) -> AgentEvent | None

Emit ui.<component_type>.init for a fresh component.

Returns the emitted :class:AgentEvent for the caller to log / record, or None when no bus is configured. Bus failures log at DEBUG and return None.

Source code in orqest/ui/emitter.py
async def init(
    self,
    component: UIComponentSpec[Any],
    *,
    agent_name: str | None = None,
) -> AgentEvent | None:
    """Emit ``ui.<component_type>.init`` for a fresh component.

    Returns the emitted :class:`AgentEvent` for the caller to log /
    record, or ``None`` when no bus is configured. Bus failures
    log at DEBUG and return ``None``.
    """
    event = AgentEvent(
        event_type=ui_init_event_type(component.component_type),
        agent_name=agent_name or self._agent_name,
        data=component.to_event_data(),
    )
    if self._bus is None:
        return event
    try:
        await self._bus.emit(event)
    except Exception as exc:
        logger.debug("UIEmitter.init failed: {e}", e=exc)
        return None
    return event
delta async
delta(
    *,
    component_id: str,
    component_type: str,
    op: UIDeltaOp,
    path: str = "",
    value: Any = None,
    agent_name: str | None = None,
) -> AgentEvent | None

Emit ui.<component_type>.delta with a partial update.

Source code in orqest/ui/emitter.py
async def delta(
    self,
    *,
    component_id: str,
    component_type: str,
    op: UIDeltaOp,
    path: str = "",
    value: Any = None,
    agent_name: str | None = None,
) -> AgentEvent | None:
    """Emit ``ui.<component_type>.delta`` with a partial update."""
    delta = UIDeltaEvent(
        component_id=component_id,
        component_type=component_type,
        op=op,
        path=path,
        value=value,
    )
    event = AgentEvent(
        event_type=ui_delta_event_type(component_type),
        agent_name=agent_name or self._agent_name,
        data=delta.to_event_data(),
    )
    if self._bus is None:
        return event
    try:
        await self._bus.emit(event)
    except Exception as exc:
        logger.debug("UIEmitter.delta failed: {e}", e=exc)
        return None
    return event
remove async
remove(
    *,
    component_id: str,
    component_type: str,
    agent_name: str | None = None,
) -> AgentEvent | None

Emit ui.<component_type>.remove so the frontend unmounts the component.

Source code in orqest/ui/emitter.py
async def remove(
    self,
    *,
    component_id: str,
    component_type: str,
    agent_name: str | None = None,
) -> AgentEvent | None:
    """Emit ``ui.<component_type>.remove`` so the frontend
    unmounts the component."""
    event = AgentEvent(
        event_type=ui_remove_event_type(component_type),
        agent_name=agent_name or self._agent_name,
        data={"component_id": component_id},
    )
    if self._bus is None:
        return event
    try:
        await self._bus.emit(event)
    except Exception as exc:
        logger.debug("UIEmitter.remove failed: {e}", e=exc)
        return None
    return event

ComponentRegistry

ComponentRegistry()

Maps component_type → :class:UIComponentSpec subclass.

Source code in orqest/ui/registry.py
def __init__(self) -> None:
    self._specs: dict[str, type[UIComponentSpec[Any]]] = {}
register
register(
    spec_class: type[UIComponentSpec[Any]],
    *,
    overwrite: bool = False,
) -> None

Register a concrete :class:UIComponentSpec subclass.

Reads the component_type Literal default off spec_class; the discriminator must be set on the class (not the instance). Re-registering the same component_type is a no-op unless overwrite=True (the prior class is logged at WARN).

Source code in orqest/ui/registry.py
def register(
    self,
    spec_class: type[UIComponentSpec[Any]],
    *,
    overwrite: bool = False,
) -> None:
    """Register a concrete :class:`UIComponentSpec` subclass.

    Reads the ``component_type`` Literal default off ``spec_class``;
    the discriminator must be set on the class (not the instance).
    Re-registering the same ``component_type`` is a no-op unless
    ``overwrite=True`` (the prior class is logged at WARN).
    """
    component_type = self._extract_type(spec_class)
    if component_type in self._specs and not overwrite:
        logger.warning(
            "Component {ct} already registered; pass overwrite=True to replace",
            ct=component_type,
        )
        return
    self._specs[component_type] = spec_class
get
get(
    component_type: str,
) -> type[UIComponentSpec[Any]] | None

Return the registered spec class for component_type, or None.

Source code in orqest/ui/registry.py
def get(self, component_type: str) -> type[UIComponentSpec[Any]] | None:
    """Return the registered spec class for ``component_type``, or ``None``."""
    return self._specs.get(component_type)
list_types
list_types() -> list[str]

All registered component types, sorted.

Source code in orqest/ui/registry.py
def list_types(self) -> list[str]:
    """All registered component types, sorted."""
    return sorted(self._specs.keys())
validate_payload
validate_payload(
    component_type: str, payload: dict[str, Any]
) -> UIComponentSpec[Any] | None

Hydrate a raw dict against the registered spec.

Returns None on lookup miss or validation failure (logged at WARN). Best-effort — UI validation should never break agent execution.

Source code in orqest/ui/registry.py
def validate_payload(
    self, component_type: str, payload: dict[str, Any]
) -> UIComponentSpec[Any] | None:
    """Hydrate a raw dict against the registered spec.

    Returns ``None`` on lookup miss or validation failure (logged
    at WARN). Best-effort — UI validation should never break agent
    execution.
    """
    cls = self._specs.get(component_type)
    if cls is None:
        return None
    try:
        return cls.model_validate(payload)
    except Exception as exc:
        logger.warning(
            "Component validation failed for {ct}: {e}", ct=component_type, e=exc,
        )
        return None

UIComponentSpec

Generic init payload for a frontend-renderable component.

Subclasses MUST override component_type with a unique :class:Literal value so the frontend resolver can pick a renderer. The data field carries the typed payload the renderer reads.

The schema is intentionally minimal: every concrete component inherits the same envelope (component_type, component_id, data, metadata, created_at) so the SSE protocol and the frontend resolver can be component-agnostic.

to_event_data
to_event_data() -> dict[str, Any]

Serialize to the dict that lands inside :class:AgentEvent.data.

Source code in orqest/ui/spec.py
def to_event_data(self) -> dict[str, Any]:
    """Serialize to the dict that lands inside :class:`AgentEvent.data`."""
    return self.model_dump(mode="json")

UIDeltaEvent

Targeted partial update to a previously-emitted :class:UIComponentSpec.

path is a dot-path into data (root = empty string). For list operations, integer indices may appear in the path (e.g. "tasks.0.status"). Frontend implementations apply the op against the previously-rendered component identified by component_id. A delta whose component_id is unknown, or whose component_type differs from the rendered component's, means the renderer is out of sync: it must refetch the snapshot rather than guess. :func:orqest.ui.view.apply_deltas raises ValueError in both cases; that is the reference form of this signal.

BindingError

A binding path does not resolve in the given context.

Hints

Presentation hints. Assistants never set colours, fonts or spacing.

ResolvedView

A view rendered against a context.

ViewNode

One node of a view tree.

Unknown keys are rejected (a typo such as props for data fails instead of being dropped).

bindings class-attribute instance-attribute
bindings: dict[str, str] = Field(default_factory=dict)

Top-level data field name -> binding path into the context.

ViewSpec

A named, versioned screen definition.

Unknown keys are rejected. The root must be a layout, node ids must be unique, and a view holds at most :data:MAX_VIEW_NODES nodes nested at most :data:MAX_VIEW_DEPTH deep.

default_registry

default_registry() -> ComponentRegistry

A :class:ComponentRegistry pre-loaded with first-party components.

Three layers of generative-UI primitives ship in core:

  1. Compositional — :class:PlanComponent, :class:ChartComponent, :class:TableComponent, :class:FormComponent, :class:TakeoverDialogComponent, :class:LayoutComponent, :class:TextComponent, :class:MarkdownComponent, :class:ImageComponent, :class:BadgeComponent, :class:ButtonComponent, :class:InputComponent, :class:StatTileComponent, :class:ChecklistComponent, :class:TimelineComponent, :class:MapComponent, :class:MediaComponent, :class:PathwayComponent, :class:LessonStepComponent. The agent composes these to build arbitrary UI.
  2. Declarative grammars — :class:VegaChartComponent, :class:MermaidComponent, :class:LatexComponent, :class:JsonViewerComponent. Thin wrappers around external grammars; the agent emits the spec.
  3. Sandboxed escape hatch — :class:SandboxedHTMLComponent. The agent writes raw HTML/SVG; the frontend confines it in an iframe. The component registers in core unconditionally; consumers gate rendering / emission via their own config flag.
Source code in orqest/ui/registry.py
def default_registry() -> ComponentRegistry:
    """A :class:`ComponentRegistry` pre-loaded with first-party components.

    Three layers of generative-UI primitives ship in core:

    1. **Compositional** — :class:`PlanComponent`, :class:`ChartComponent`,
       :class:`TableComponent`, :class:`FormComponent`,
       :class:`TakeoverDialogComponent`, :class:`LayoutComponent`,
       :class:`TextComponent`, :class:`MarkdownComponent`,
       :class:`ImageComponent`, :class:`BadgeComponent`,
       :class:`ButtonComponent`, :class:`InputComponent`,
       :class:`StatTileComponent`, :class:`ChecklistComponent`,
       :class:`TimelineComponent`, :class:`MapComponent`,
       :class:`MediaComponent`, :class:`PathwayComponent`,
       :class:`LessonStepComponent`. The agent composes these to build
       arbitrary UI.
    2. **Declarative grammars** — :class:`VegaChartComponent`,
       :class:`MermaidComponent`, :class:`LatexComponent`,
       :class:`JsonViewerComponent`. Thin wrappers around external
       grammars; the agent emits the spec.
    3. **Sandboxed escape hatch** — :class:`SandboxedHTMLComponent`. The
       agent writes raw HTML/SVG; the frontend confines it in an iframe.
       The component registers in core unconditionally; consumers gate
       *rendering* / *emission* via their own config flag.
    """
    from orqest.ui.components import (
        BadgeComponent,
        ButtonComponent,
        ChartComponent,
        ChecklistComponent,
        FormComponent,
        ImageComponent,
        InputComponent,
        JsonViewerComponent,
        LatexComponent,
        LayoutComponent,
        LessonStepComponent,
        MapComponent,
        MarkdownComponent,
        MediaComponent,
        MermaidComponent,
        PathwayComponent,
        PlanComponent,
        SandboxedHTMLComponent,
        StatTileComponent,
        TableComponent,
        TakeoverDialogComponent,
        TextComponent,
        TimelineComponent,
        VegaChartComponent,
    )

    reg = ComponentRegistry()
    # Existing first-party components.
    reg.register(PlanComponent)
    reg.register(ChartComponent)
    reg.register(TableComponent)
    reg.register(FormComponent)
    reg.register(TakeoverDialogComponent)
    # Layer 1 — compositional primitives.
    reg.register(LayoutComponent)
    reg.register(TextComponent)
    reg.register(MarkdownComponent)
    reg.register(ImageComponent)
    reg.register(BadgeComponent)
    reg.register(ButtonComponent)
    reg.register(InputComponent)
    reg.register(StatTileComponent)
    reg.register(ChecklistComponent)
    reg.register(TimelineComponent)
    reg.register(MapComponent)
    reg.register(MediaComponent)
    reg.register(PathwayComponent)
    reg.register(LessonStepComponent)
    # Layer 2 — declarative grammars.
    reg.register(VegaChartComponent)
    reg.register(MermaidComponent)
    reg.register(LatexComponent)
    reg.register(JsonViewerComponent)
    # Layer 3 — sandboxed escape hatch (frontend gates rendering).
    reg.register(SandboxedHTMLComponent)
    return reg

apply_deltas

apply_deltas(
    blocks: dict[str, dict[str, Any]],
    deltas: list[UIDeltaEvent],
) -> dict[str, dict[str, Any]]

Reference applier for :func:diff_view output; returns a new block map.

Supports exactly the ops diff_view emits (top-level replace and remove). An unknown op, an unknown component id or a component_type that differs from the block's raises :class:ValueError: the reference form of the renderer's "refetch the snapshot" signal (see :class:orqest.ui.spec.UIDeltaEvent).

Source code in orqest/ui/view.py
def apply_deltas(
    blocks: dict[str, dict[str, Any]], deltas: list[UIDeltaEvent]
) -> dict[str, dict[str, Any]]:
    """Reference applier for :func:`diff_view` output; returns a new block map.

    Supports exactly the ops ``diff_view`` emits (top-level ``replace`` and
    ``remove``). An unknown op, an unknown component id or a
    ``component_type`` that differs from the block's raises
    :class:`ValueError`: the reference form of the renderer's "refetch the
    snapshot" signal (see :class:`orqest.ui.spec.UIDeltaEvent`).
    """
    out = copy.deepcopy(blocks)
    for delta in deltas:
        block = out.get(delta.component_id)
        if block is None:
            raise ValueError(f"unknown component_id {delta.component_id!r}")
        if block["component_type"] != delta.component_type:
            raise ValueError(
                f"component_type mismatch at {delta.component_id!r}:"
                f" block is {block['component_type']!r}, delta says {delta.component_type!r}"
            )
        if delta.op == "replace":
            block["data"][delta.path] = copy.deepcopy(delta.value)
        elif delta.op == "remove":
            block["data"].pop(delta.path, None)
        else:
            raise ValueError(f"unsupported delta op {delta.op!r}")
    return out

diff_view

diff_view(
    old: ResolvedView, new: ResolvedView
) -> list[UIDeltaEvent] | None

Compute top-level-field deltas turning old into new.

Both resolutions must come from the same spec: diff_view ignores child order and hints, so a caller must re-init when the spec changes (as :class:orqest.assistants.live_views.LiveViews does). Returns None when a full re-init is required: the view name or version differs, the block id sets differ, or any block changed component_type (for example a placeholder that became a real block). Otherwise returns one replace per changed or added top-level data key and one remove per dropped key, ordered by block id then key. Metadata is not diffed (hints only change with the spec version).

Source code in orqest/ui/view.py
def diff_view(old: ResolvedView, new: ResolvedView) -> list[UIDeltaEvent] | None:
    """Compute top-level-field deltas turning *old* into *new*.

    Both resolutions must come from the same spec: ``diff_view`` ignores
    child order and hints, so a caller must re-init when the spec changes (as
    :class:`orqest.assistants.live_views.LiveViews` does). Returns ``None``
    when a full re-init is required: the view name or version differs, the
    block id sets differ, or any block changed ``component_type`` (for
    example a placeholder that became a real block). Otherwise returns one
    ``replace`` per changed or added top-level data key and one ``remove`` per
    dropped key, ordered by block id then key. Metadata is not diffed (hints
    only change with the spec version).
    """
    if old.name != new.name or old.version != new.version:
        return None
    if old.blocks.keys() != new.blocks.keys():
        return None
    if any(old.blocks[k]["component_type"] != new.blocks[k]["component_type"] for k in new.blocks):
        return None
    deltas: list[UIDeltaEvent] = []
    for block_id in sorted(new.blocks):
        component_type = new.blocks[block_id]["component_type"]
        old_data = old.blocks[block_id]["data"]
        new_data = new.blocks[block_id]["data"]
        for key in sorted(old_data.keys() | new_data.keys()):
            if key not in new_data:
                deltas.append(
                    UIDeltaEvent(
                        component_id=block_id, component_type=component_type, op="remove", path=key
                    )
                )
            elif key not in old_data or old_data[key] != new_data[key]:
                deltas.append(
                    UIDeltaEvent(
                        component_id=block_id,
                        component_type=component_type,
                        op="replace",
                        path=key,
                        value=copy.deepcopy(new_data[key]),
                    )
                )
    return deltas

fallback_view

fallback_view(name: str) -> ViewSpec

A minimal view that shows the raw state in a JSON viewer.

Source code in orqest/ui/view.py
def fallback_view(name: str) -> ViewSpec:
    """A minimal view that shows the raw ``state`` in a JSON viewer."""
    return ViewSpec(
        name=name,
        root=ViewNode(
            id="root",
            component_type="layout",
            children=[
                ViewNode(
                    id="state",
                    component_type="json_viewer",
                    data={"title": "State"},
                    bindings={"data": "state"},
                )
            ],
        ),
    )

iter_nodes

iter_nodes(node: ViewNode) -> Iterator[ViewNode]

Yield node and every descendant, depth-first in child order.

Source code in orqest/ui/view.py
def iter_nodes(node: ViewNode) -> Iterator[ViewNode]:
    """Yield ``node`` and every descendant, depth-first in child order."""
    yield node
    for child in node.children:
        yield from iter_nodes(child)

node_problems

node_problems(
    spec: ViewSpec,
    registry: ComponentRegistry,
    context: dict[str, Any],
) -> list[tuple[str, str]]

Return (node id, problem) for each problem :func:resolve_view reports.

The same problems as :attr:ResolvedView.problems (rendered nodes only, every cause), each paired with the id of the node it degraded.

Source code in orqest/ui/view.py
def node_problems(
    spec: ViewSpec, registry: ComponentRegistry, context: dict[str, Any]
) -> list[tuple[str, str]]:
    """Return ``(node id, problem)`` for each problem :func:`resolve_view` reports.

    The same problems as :attr:`ResolvedView.problems` (rendered nodes only,
    every cause), each paired with the id of the node it degraded.
    """
    _, problems = _resolve(spec, registry, context)
    return [(node_id, msg) for _, node_id, msg, rendered in problems if rendered]

resolve_path

resolve_path(context: dict[str, Any], path: str) -> Any

Walk dict keys and integer list indices; raise :class:BindingError on a miss.

Source code in orqest/ui/view.py
def resolve_path(context: dict[str, Any], path: str) -> Any:
    """Walk dict keys and integer list indices; raise :class:`BindingError` on a miss."""
    current: Any = context
    for segment in path.split("."):
        if isinstance(current, dict):
            if segment not in current:
                raise BindingError(path)
            current = current[segment]
        elif (
            isinstance(current, list)
            and segment.isascii()
            and segment.isdigit()
            and len(segment) <= _MAX_INDEX_DIGITS
        ):
            idx = int(segment)
            if idx >= len(current):
                raise BindingError(path)
            current = current[idx]
        else:
            raise BindingError(path)
    return current

resolve_view

resolve_view(
    spec: ViewSpec,
    registry: ComponentRegistry,
    context: dict[str, Any],
) -> ResolvedView

Render spec against context. Degraded nodes become placeholders; never raises.

Source code in orqest/ui/view.py
def resolve_view(
    spec: ViewSpec, registry: ComponentRegistry, context: dict[str, Any]
) -> ResolvedView:
    """Render *spec* against *context*. Degraded nodes become placeholders; never raises."""
    return _resolve(spec, registry, context)[0]

unresolved_bindings

unresolved_bindings(
    spec: ViewSpec,
    registry: ComponentRegistry,
    context: dict[str, Any],
) -> list[str]

Return one line per binding that does not resolve in context.

These are warnings, not problems: such nodes render as placeholders until the data exists. Bindings inside a subtree that is not rendered (under a degraded layout) are included.

Source code in orqest/ui/view.py
def unresolved_bindings(
    spec: ViewSpec, registry: ComponentRegistry, context: dict[str, Any]
) -> list[str]:
    """Return one line per binding that does not resolve in *context*.

    These are warnings, not problems: such nodes render as placeholders until
    the data exists. Bindings inside a subtree that is not rendered (under a
    degraded layout) are included.
    """
    _, problems = _resolve(spec, registry, context)
    return [msg for cause, _, msg, _ in problems if cause == "binding"]

validate_view

validate_view(
    spec: ViewSpec,
    registry: ComponentRegistry,
    context: dict[str, Any],
) -> list[str]

Return structural problems only (unknown types, binding keys that are not fields of the block's data model, invalid data).

Bindings that do not resolve in context are not reported: they degrade to placeholders at render time and may resolve later. For such nodes the literal data is still checked (errors on bound fields are ignored), the type is still checked, and children are still visited.

Source code in orqest/ui/view.py
def validate_view(
    spec: ViewSpec, registry: ComponentRegistry, context: dict[str, Any]
) -> list[str]:
    """Return structural problems only (unknown types, binding keys that are not
    fields of the block's data model, invalid data).

    Bindings that do not resolve in *context* are not reported: they degrade
    to placeholders at render time and may resolve later. For such nodes the
    literal data is still checked (errors on bound fields are ignored), the
    type is still checked, and children are still visited.
    """
    _, problems = _resolve(spec, registry, context)
    return [msg for cause, _, msg, _ in problems if cause == "structure"]