Fused Widgets

Widgets — getting a rendered result back

Part of the Fused skill set — don't work from it alone. Fused is workspace ⊃ project ⊃ UDF. Before acting, also load fused-projects for the end-to-end model (creating, running, opening, and deploying a project's widget). For a question/approval/plan UI load fused-feedback. See fused-guide for the full set — this skill assumes that context.

In most Fused flows the thing a human wants back is a widget (an interactive dashboard), not a raw value. A widget is a JSON config; running it yields resolved rows that a renderer turns into a visual. This skill covers authoring widgets and getting them in front of a human.

There are NO MCP widget tools. Agents author widget files; humans view them through the CLI (fused widget open / the parley). The separate flow UI (fusedio/flow — started with the flow CLI, or npx @fusedio/flow once published) can also render them, but driving flow is out of scope for this skill; everything below is the fused CLI, never MCP. (See fused-projects for where this sits in the project lifecycle, and fused-cli for the full widget command flag tables.)

What a widget is

A widget is a single JSON document — a tree of nodes, each { "type": "<component>", "props": { … }, "children": [ … ] }. It lives in one of two places in a project — and the two render on different surfaces, so the choice matters:

• widgets/<stem>.json — a saved project dashboard, addressed by its stem (fused widget open <stem> --project <p>). This is also the form the separate flow UI live-renders on its project surface (out of scope here). Use this form when the human will browse the dashboard.
• scripts/<name>/main.json — a json-kind UDF: a first-class, deployable entrypoint (deploys to a stable widget URL). Preview it rendered with fused widget open scripts/<name>/main.json (the file render path) or by deploying it. In the flow UI it appears as source ("View source ↗"), not a live render.

The config is identical either way (same {{ref}}/$param grammar), so this is purely where the file lives. The default for "show the human a dashboard" is widgets/<stem>.json. If you also need a shareable URL, keep the deployable copy at scripts/<name>/main.json as well.

Always pair a widget with a spec. For every widgets/<stem>.json you save, write a widgets/<stem>.spec.md contract sidecar next to it — purpose, the {{udf}} data it binds, and the components + their SQL — the SAME spec↔file pairing a UDF has (scripts/<stem>/spec.md). The app renders it in the widget's Preview ⇄ Spec toggle, and data-qa verifies the widget against it; a widget without its spec.md is incomplete.

The renderable component set is fixed and comes from a single generated source of truth (widgets/components.json); a type outside it is a hard error. The current components:

Input components carry a param prop and a defaultValue; they seed the param store on first paint and re-resolve dependent queries when the human changes them.

Use this catalog — not the external Fused-branded skills. Author widgets ONLY against this catalog (the agent_core widget set). Do not use any external Fused-branded skill (fused:*, e.g. fused:json-ui-schemas, fused:canvas-toml) or the hosted Fused product's JSON-UI schema — those target a different product and carry components this catalog does not support, and an unsupported type is a hard render error. The live, authoritative list for the project you're in is the widget_components array in get_project_context ([{type, hasChildren, isInput}, …]) — orient on it.

Component reference (key props — style applies to all, omit unless overriding)

Charts read fixed result columns (alias your SELECT to them), not props:

Always title chart axes. Set xAxisLabel/yAxisLabel on the cartesian charts above (and xLabel/yLabel on scatter-chart) so each axis names what it shows — an unlabeled axis is an incomplete chart. These are axis titles, separate from the per-tick labels.

Display / data:

Maps render in the native renderer only. map, map-bounds, and fused-map need heavy WebGL deps + external tiles the self-contained deployed bundle does not ship, so the deployed build aliases the map modules to a placeholder — they render only in the native renderer (fused widget open / the parley / the flow UI), not on a deployed URL.

Inputs (write param; all take param, label, defaultValue):

Prose vs raw HTML vs scalar: use text for a single value (a label, a count), markdown for prose / reports / notes (headings, lists, tables, code — GitHub flavored), and html only when you need raw HTML. Use diff to show the change between two texts — pass before + after (the line diff is computed for you) or a precomputed unified-diff string in diff; built for reviewing markdown spec changes. Lean on the built-in defaults — omit style unless you need a deliberate override (one consistent default look across every surface).

Don't inline a large dataset into an html value — keep large data outside the widget, where the project stores its data, and load it at runtime. Concretely: store the data as a file in assets/, add a backing UDF in scripts/ that reads it with openfused.asset_path(...), and bind the widget to it via {{udf_name}} in a sql prop. A widget config over 512 KB is rejected at save and resolve time (ConfigTooLargeError) — an inlined dataset also rides in every resolve request, which the app server caps at 1 MB.

checkbox-group is the multi-select reply channel — the array twin of dropdown. It is the input to reach for when an ask allows more than one answer (an ask_user widget whose question allows more than one choice). It writes the chosen option values to its param as a string[]. Because the param holds an array, it (like sql-table's selectionParam and video-review) must never be referenced in SQL — $param is text substitution and only scalars are SQL-safe. Use a dropdown for single-select.

The core pattern: a py UDF computes, a json widget visualizes

This is the shape of almost every project. A py UDF returns a DataFrame; a json widget binds to it in a DuckDB SQL string via the {{ref}} grammar.

scripts/sales/main.py — the data UDF:

import fused

@fused.udf
def main(region: str = "all"):
    import pandas as pd
    df = pd.read_parquet("s3://my-bucket/sales.parquet")
    if region != "all":
        df = df[df["region"] == region]
    return df[["month", "region", "revenue"]]

widgets/sales-board.json — the saved dashboard that renders it (use scripts/sales-board/main.json instead if this widget is a deployable entrypoint):

{
  "type": "div",
  "props": { "style": "display: grid; gap: 16px; padding: 16px" },
  "children": [
    { "type": "text", "props": { "value": "Revenue across regions", "variant": "h3" } },
    { "type": "dropdown", "props": {
        "param": "region", "label": "Region",
        "options": [{"value": "all", "label": "All"}, {"value": "emea", "label": "EMEA"}],
        "defaultValue": "all" } },
    { "type": "slider", "props": {
        "param": "min_revenue", "label": "Min revenue",
        "min": 0, "max": 500, "defaultValue": 0 } },
    { "type": "metric", "props": {
        "label": "Total revenue", "format": "currency", "prefix": "$",
        "sql": "select sum(revenue) as value from {{sales?region=$region}}" } },
    { "type": "bar-chart", "props": {
        "sql": "select month, sum(revenue) as revenue from {{sales?region=$region}} where revenue >= $min_revenue group by month order by month" } },
    { "type": "sql-table", "props": {
        "title": "Raw rows",
        "sql": "select month, region, revenue from {{sales?region=$region}} where revenue >= $min_revenue order by month limit 50" } }
  ]
}

The dropdown/slider write $region/$min_revenue; the metric, bar-chart, and sql-table read them and re-resolve when they change.

Reading a bundled project asset (a file under the project's assets/): use openfused.asset_path(...), never a relative ./assets/..., a __file__-relative path, or a hard-coded absolute path. A UDF runs in a throwaway sandbox cwd, so only a project-root-anchored path resolves — and the widget render path is exactly where the relative forms silently break (blank dashboard / FileNotFoundError):

import openfused
df = pd.read_parquet(openfused.asset_path("data.parquet"))   # robust, one-shot

Geo data → always a map. When the data has a geographic dimension (lat/lon, geometry, or geocodable place/address columns), include a fused-map in the dashboard by default — unless the user explicitly says not to. A map is the default for geo data, not an optional extra.

The {{ref}} / $param grammar (essentials)

• {{sales}} — the whole result of the sales UDF, default params.
• {{sales?region=$region}} — pass kwarg region bound to the param $region.
• {{sales?region=emea&limit=50}} — bare literals (string emea, number 50); single-quote a value that must stay a string or contain & = whitespace: {{sales?region='emea, west'}}.
• name may contain - ({{my-udf}}). Two refs with identical name+args share one UDF run / one DuckDB view; distinct args run the UDF again.
• Cross-project ({{_core.proj.udf}}) — a bare {{udf}} resolves in the current project; a three-segment ref reuses a UDF from the built-in _core workspace, e.g. {{_core.task-management.create}} (read path) or a button executor firing the same name (write path). Only the allowlisted _core workspace is reachable (any other first segment → unknown endpoint); its source is the packaged core_source_dir() but it RUNS under the consuming project's venv, so keep shared UDFs dependency-light. _core refs resolve on every local surface — they all route through fused dev serve, whose directory-addressed modes (?dir=/?projectDir=, used by widget open / parley) inject the built-in _core shared root by default — so a standalone widget (e.g. the task-board's mutateBackend: "core") can drive the built-in _core UDFs; only the deployed-serve bundle can't. App-parity note: this is an extension specific to this platform (agent_core) — a cross-project ref won't resolve if pasted into the external Fused app.
• $name is an inline text substitution (not a DuckDB bind param), so it works anywhere — including inside '…' and "…". Grammar: $[A-Za-z_]\w*. Substitution is context-aware (quotes are doubled; comments/dollar-quoted bodies are left verbatim). This matches the Fused app byte-for-byte, so a config authored here pastes into the app and behaves identically.

The {{ref}} / $param grammar above is the full contract.

Archived widgets (soft-deleted, reachable by link). When a human archives a widget in the app it moves to archive/widgets/<stem>.json and is read-only — gone from the canvas, the Widget tab, and get_project_context, but still loadable through a task deep-link. A bare {{udf}} resolves from the live scripts/ dir; if that UDF was also archived, the resolver falls back to archive/scripts/<udf>/ so a fully-archived widget + UDF pair still resolves its data when opened via the link. The fallback fires only for the exact ref the widget names — archived UDFs are never enumerated, so they stay out of every catalog. You don't author or restore archived widgets from here (that's an app + human action); just know an archived widget you reach by link still renders.

Core UDFs → custom views (no project setup)

The built-in _core workspace ships ready-to-use UDFs that any ad-hoc widget can read or act on directly via a {{_core.<project>.<udf>}} ref (read) or a button executor firing the same name (write). This is how a user gets a custom view of Fused's own state — a bespoke task board, an inbox triage panel, a run monitor — without authoring any backing UDF: bind a chart/table straight to a core UDF. No setup, no env, no uv add for the core source itself — the directory-addressed surfaces (widget open, parley, fused dev serve) inject the _core root automatically.

The shipped _core projects and their UDFs:

Example — a custom open-tasks board bound directly to the core task store:

{ "type": "sql-table", "props": {
    "title": "Open tasks",
    "sql": "select title, assignee, status from {{_core.task-management.read}} where status != 'completed' order by updatedAt desc" } }

A write needs a button whose executor fires the qualified name, e.g. "executor": "_core.task-management.update_status?id=$selectedId&status='completed'". Same rules as any {{ref}}: the UDF runs under the consuming widget's venv, so core UDFs are kept dependency-light. Only the deployed-serve bundle can't reach _core; every local surface can.

How "running" a widget works

A widget does not return a result value the way a py UDF does. Instead, each data-bound node's sql is scanned → planned → resolved into rows:

1. Plan — scan each props.sql, stamp a stable queryId, harvest input defaults, build the param → [queryId] dependency map.
2. Resolve sources — map each {{name}} to a UDF source on disk (scripts/<name>/main.py).
3. Resolve — build a self-contained resolver program (DuckDB runtime + the per-query SQL + the resolved UDF sources) and run it through ComputeBackend.execute — the same backend and content-addressed cache as execute_code. In the sandbox: run each {{ref}} fresh → register a DuckDB view → rewrite the SQL to those views → substitute $param → execute → encode rows. Returns { "data": {queryId: {columns, rows}}, "errors": {…} }.

List/dict-valued UDF columns. When a py UDF returns a DataFrame with columns that contain Python lists or dicts (e.g. blockedBy: [] in task records), the resolver JSON-encodes those cells before registering the DuckDB view (so DuckDB can accept them as strings), then decodes them back to arrays/objects in the output rows. This is transparent — the renderer receives the original list/dict values, not strings.

Consequence for the local backend: because resolution runs through the project's compute backend, the project venv must contain duckdb (plus pandas/pyarrow, provided automatically) and any libraries the referenced py UDFs import. Add them and sync before previewing:

cd ~/.openfused/workspaces/default/<project>
uv add duckdb pandas        # + whatever the py UDFs import
uv sync

A missing/incomplete .venv surfaces a guided error telling you to run uv sync. (project new does not create .venv.) Best practice: seed the venv right after project new, not when the first resolve fails — see fused-projects Step 2.

Live dashboards: refreshInterval (client-side polling)

A data-bound node can poll on its own — set props.refreshInterval to an interval in milliseconds and the renderer re-resolves that source on a timer (a map/fused-map node also accepts a per-layer refreshInterval under each layer). Use it for live dashboards (a metric or chart that should track changing UDF output without a human interaction).

{ "type": "metric", "props": {
    "label": "Active runs", "refreshInterval": 5000,
    "sql": "select count(*) as value from {{_core.run-management.read}} where status = 'started'" } }

• Floor is 1000 ms. Sub-floor values are clamped up to 1000 ms; a non-positive / non-finite / non-number value is rejected (no timer scheduled).
• It's purely client-side — timers live in the renderer (the widget-host viewer, the flow UI, and the deployed static bundle). The Python server, planner, and resolver are unchanged: a tick is just an ordinary resolve POST for that source's query, the same path a $param change takes. Because of that it's deduped by the cache — a tick landing inside the source's cache_max_age window returns the stored entry with no recompute, so pair a short interval with a short cache age (or 0s) if you actually want fresh data each tick.
• verify never ticks (it's one-shot), so a refreshInterval has no effect on a headless check — confirm live-refresh behavior on the real renderer.

Triggering a UDF on a button press (act, not just read)

The flow above is read — data flows UDF → rows → widget. A button can also act: run a UDF on press via its executor prop.

{ "type": "button", "props": {
    "label": "Promote",
    "executor": "promote-udf?id=$selectedId&channel='release'"
} }

• executor is a brace-less {{ref}} body — the SAME grammar as SQL: a UDF name, optional ?k=v&k2=$param args, $param bound against the live params at click time (single-quote literals as in SQL). Authoring it is just the {{ref}} grammar above minus the braces. The UDF name is its project slug (kebab-case, e.g. promote-udf), the same name a {{ref}} reads it under — or a qualified _core.task-management.create to fire a built-in _core UDF (same cross-project rule as reads).
• The press fires the UDF once (it is event-triggered, not reactive like a $param change). The button shows a running state and disables mid-flight; an error surfaces on hover. The UDF is invoked directly (the args become typed kwargs — no SQL is synthesized), and its raw return value comes back as data in the {data, error} envelope: a DataFrame/Arrow table as records, a dict/list/scalar verbatim.
• It runs through the same compute backend as reads — so the project venv needs the UDF's imports, same as the read path. Caching is forced off (a write must re-run every press).
• Surface scope: works where there is a local host (widget open, the parley, the flow UI). On the deployed-serve bundle / MCP-Apps sandbox there is no executor, so an executor press is a visible no-op (the button still renders). Pair executor with action on the same button to ALSO report a feedback event.
• v1 is fire-and-forget: the button does not yet auto-refresh dependent queries from the UDF's result. To reflect a write, have the UDF mutate state a read {{ref}} re-reads, and re-resolve (e.g. bump a $param the read depends on).

Self-verify a widget resolves (headless)

Confirm a widget resolves to data with fused widget verify — the fast headless check (no GUI in the loop). Run it alongside open, not as a serial gate in front of it (see Optimistic open + background verify): it resolves the widget in one shot, prints the data envelope to stdout, and exits — spawning and reaping nothing (no daemon, no port, no token, no browser). It reuses the same resolution path as the render surfaces in-process, so a clean verify faithfully predicts what open would render. It is the headless counterpart of open/push/watch and replaces the old hand-driven fused dev serve dance (spawn → read handshake → POST /api/exec/widget → parse → kill).

# a .json config file, pinned to its project (the usual real-widget case)
fused widget verify scripts/<widget>/main.json \
  --project-dir ~/.openfused/workspaces/default/<project>

# a saved widgets/<stem>.json owned by a project
fused widget verify <stem> --project <project>

# inline / from stdin; bind $param values; force a fresh run (or pin a max age)
cat main.json | fused widget verify --config -
fused widget verify <stem> --project <project> --params '{"region":"emea"}' --cache-refresh
fused widget verify <stem> --project <project> --cache-max-age 0s

The response is {"data": {queryId: {columns, rows}}, "errors": {…}, "depMap": {…}, "config": {…}, "warnings": […]}. Success = errors is empty and data has rows. A per-query failure (bad SQL, a UDF error, a missing {{ref}} source, a missing $param) lands under errors[queryId] and never blanks the rest — read it to fix the SQL or the referenced UDF; the command still exits 0 because per-query failures are in-band. A source that returns [] (zero rows) is a success, not an error: it's an empty result and the widget renders empty — a clean empty widget, not an in-card error. Only a hard failure (bad input, unknown/unresolvable widget, resolver crash) prints no stdout JSON, a message on stderr, and exits non-zero. Resolution runs through the project's compute backend, so the project venv needs duckdb + the py UDFs' deps (see above). Full flags + the exit-code table: fused-cli (widget section).

The warnings array is a best-effort advisory — [{"type","props":[…]}, …], empty [] when clean — flagging config props the server's catalog doesn't recognize (a typo'd or unsupported prop name). It is strictly additive and never changes the exit code (a warning is not an error), and because it comes from the shared resolve path the interactive surfaces (open/push/watch) carry it too. See the caveat below for what it does and doesn't catch.

Pick the right addressing mode

verify resolves {{ref}} sources in one of two modes, chosen by the flag you pass. Picking the wrong one is the most common failure here — and it surfaces as a misleading unknown endpoint error, not as "wrong mode", so know the rule up front:

unknown endpoint ⇒ wrong mode (90% of the time). If a {{ref}} resolves to unknown endpoint, you almost certainly ran a bare .json (widget-dir mode) against a UDF that folder can't see. Add --project-dir <project root> (or --project <name> for a stem) before suspecting the SQL or the UDF itself. Being inside the project tree is not enough — the mode is set by the flag, not by cwd. The reverse — a truly missing/misnamed {{ref}} — also reads unknown endpoint, so confirm the mode first, then the name.

⚠ What this proves — and what it does NOT. A clean verify proves the widget's SQL resolves to data, and its warnings array now catches props the server catalog doesn't recognize (a typo'd or unsupported prop name). But it still does not prove the renderer will honor a prop it does recognize — verify returns raw rows and never renders. The gap it can't see is version skew: a prop the server catalog knows but a stale/old @fusedio/flow bundle doesn't (e.g. idColumn/parentColumn row-grouping added after that bundle) resolves clean, warns nothing, and still draws wrong. So when you add a newer config prop, don't trust the headless pass alone: confirm the prop is actually applied on the real renderer (the widget-host viewer via fused widget open, the flow UI, or the deployed widget URL) and check the renderer version supports it. The headless check is a data + catalog gate, not a render gate.

⚠ Build-freshness: verify sees source, open serves a compiled bundle. verify resolves in-process against the source on disk, but open serves the compiled widget-host bundle (widget-host/dist). If that bundle is stale — older than its src/ — open can render old/wrong behavior while verify stays green, and you'll burn a whole session debugging config that is already correct. So when open misbehaves but verify is clean, suspect the running artifact before your config: confirm the bundle is newer than its source (and actually contains the symbol you're testing), rebuild (pnpm build in widget-host), and re-open — before re-editing the widget. Attribute a render bug to source only once you've confirmed the artifact you're running is fresh. This is the general rule for any compiled surface: verify the thing you're actually running, not the thing you're reading.

Getting a widget in front of a human — decision tree

CLI / standalone agent: open the widget yourself — do not tell the human to open it. Once you have authored (and headlessly self-verified) the widget file, you run the surface command — fused widget open <file> for a one-shot, or push it into the parley for a standing loop. widget open launches/reuses the app server, opens the browser, and blocks until the human responds, handing you their reply. Never end your turn with "open the file in the flow UI to see it" — that strands the human; drive the surface and bring back the result.

⚠ Agents spawned by the flow app (architect / data-analyst / QA worker runs) MUST NOT run fused widget open / widget push / the parley. Those surfaces wait on a human at a keyboard and would hang the run (or collide with the already-running UI). In that context the widget flow is different: a data-analyst just writes widgets/<stem>.json and the flow UI live-renders it natively — no command to run; feedback is asked via the teamwork MCP (ask_user — the single human-ask tool), and data-qa self-checks a widget headless via POST /api/exec/widget. The "run widget open yourself" rule is for an agent driving Fused from the CLI, not for an in-app worker.

All four surfaces render the same config through the same resolver. Pick by the interaction you need:

• Finding the target (don't ls the workspace). When the human just names a widget and/or project ("open the session_cost widget of cc-open"), resolve it with the CLI, not by listing directories:
  • fused project list → JSON array of every project (name, path, exists). Skip it when the human already named the project.
  • fused project show <project> → includes a "widgets": [...] array of the project's saved-widget stems (the widgets/<stem>.json you'd pass to open), plus its references and components. One call confirms the project and lists its widgets — replacing a ls ~/.openfused/workspaces/… + ls widgets/ walk with one structured command. When the human named both the project and an obvious widget, skip discovery entirely and go straight to fused widget open <stem> --project <project>.
• widget open <target>: <target> is a .json path or a saved-widget stem. It launches/reuses the app server, opens the browser, and blocks. --no-open still blocks (prints the URL). This is the canonical "ask the human" path for an agent. The block is time-bounded: --timeout seconds (default 600 = 10 min), after which it prints {"action":"timeout"} and exits 3; --timeout 0 waits forever (see Long-running / standing widgets).
  • -c/--config TEXT (or --config - for stdin): pass the widget config inline instead of a <target> — one call instead of Write a .json then open it. Mutually exclusive with <target>. Best for one-shot asks (approvals, questions) that settle and exit; the config is not editable (no durable file), so for an edit-and-refresh loop keep authoring a named .json and open its path. widget push -c/--config is the parley counterpart (no temp file; --source PATH sets the edit anchor).
  • --project-dir PATH (.json/--config targets only; on both widget open and widget push): pins fused dev serve's ?projectDir= mode to a project directory so UDFs in scripts/ and the project .venv are available. Pass this for almost any real project widget — one that references a UDF elsewhere in scripts/ or a {{_core.*}} ref. Omitting it leaves the surface in widget-dir (?dir=) mode, which sees only the .py files sitting next to the widget file; a {{ref}} to anything else then fails (often a misleading unknown endpoint/ValueError). Being inside the project tree is not enough — the mode is set by this flag, not by file location (see Pick the right addressing mode). Mutually exclusive with --project. On push, it is the entry point to feedback mode: a .json path pushed --project-dir resolves against the project and stays file-backed, so the parley comment loop works on a scripts/-backed widget — the only push form that is both project-addressed and editable (a {project, stem} push resolves but is not editable). See fused-feedback → CLI-native comment feedback.
• parley (widget push/watch/parley/agent) is the standing agent↔human channel — successive views land on one persistent page and the human's events stream back as NDJSON. Use it for iterative refinement. Details
  • flags: fused-cli (widget section).
• The flow UI (separate tool, out of scope) renders saved dashboards (widgets/<stem>.json) natively, with data resolved through fused dev serve. A json UDF (scripts/<name>/main.json) is not live-rendered there — it appears as source/spec; preview a json UDF with widget open (above) or deploy it.
• Deployed json UDFs build a self-contained widget.html bundle + a gated resolver data route → a stable widget URL. This is the one place a renderer bundle (not the app) serves the widget.

Long-running / standing widgets

Yes — a widget can stay up long-term, but widget open is the wrong tool for it. An open session lives only as long as its command runs: the block gives up after --timeout seconds (default 600 = 10 min → {"action":"timeout"}, exit 3), and on any exit (timeout, Ctrl-C, the tab closing) it de-registers the widget — so you cannot "open it and walk away." Pick by what "long-running" means:

• One long-lived ask that just needs more patience — widget open --timeout 0 (wait forever). The block never expires; it returns only when the human acts (or you interrupt). Because it then blocks indefinitely, you MUST drive it from run_in_background and Monitor its stderr for the widget page: URL — never a foreground --timeout 0 you can't get back from (same rule as Optimistic open + background verify).
• A widget that genuinely persists across a long session — the parley (the real long-running surface). Unlike an open session, a pushed parley view persists in the widget-host independently of the short-lived push command: widget push <cfg> posts a view and exits immediately, the view stays on the standing /parley page, and widget watch (its --timeout defaults to 0 = watch forever) streams the human's events as NDJSON. Push successive views onto the same page over time. This is the surface to reach for when the widget must outlive a single blocking call.
  • Consume the event stream with a Monitor, not a plain background task. watch streams forever, so a run_in_background task only notifies you when it exits (it never does) — you'd sit blind while the human comments. Run watch directly as the Monitor command (persistent: true) so each NDJSON line wakes you the instant the human acts. Arm it before the first push. This is the same pattern documented in fused-feedback → React live with a Monitor:

    Monitor(description: "parley human events", persistent: true,
            command: "fused widget watch --from latest")
    

    (The other "Monitor" mentions above are for polling stderr for the open URL — a different job than consuming this event stream.)

Either way, the widget-host itself is a detached background process that outlives the CLI call — it binds a fixed loopback port (default 4410) and a later widget command reuses it — so the host (and any parley view on it) keeps serving between commands. What's transient is the per-open session, not the host.

Optimistic open + background verify

widget open blocks until the human responds, so you cannot both open a widget and do anything else from the same foreground call. Two rules follow — and together they kill the blind-sleep anti-pattern.

Open optimistically; verify in the background — don't gate the human's view on the headless check. verify is a data + catalog gate, not a render gate, and it's fast. Launch open first so the human sees the widget the moment the server is up, and run verify concurrently to catch resolve/catalog problems — then react (push a fix, flag an empty result) if it comes back dirty. Serialising verify → open only adds latency to the human's first paint for a check that rarely fails once the SQL is written.

Poll for readiness — never blind-sleep. Because open blocks, start it with run_in_background and watch its output for the http://… URL instead of guessing with sleep 8; cat log. A fixed sleep is both too slow (you pay the worst case every time) a

…(truncated)