Widget — Durable Interactive Artifacts

The user watches the widget live — stream content fast, one section per tool call.

Quick start

npm install -g @openduo/duoduo-widgets  # if not installed

1. Open

duoduo-widget open --title "Dashboard" --ttl-seconds 300

Send links.feishu_sidebar or links.browser to user. NEVER send control_url/control_token.

2. Skeleton + push

cat > /tmp/w-{wid}.html << 'SKELETON'
<div style="background:#1a1a1a;color:#e0e0e0;padding:20px;font-family:system-ui;min-height:100vh;">
  <h1 style="color:#fff;font-size:28px;font-weight:500;margin:0 0 4px;">Title</h1>
  <p style="color:#999;font-size:14px;margin:0 0 20px;">Subtitle</p>
<!-- NEXT -->
</div>
SKELETON
cat /tmp/w-{wid}.html | duoduo-widget update --wid "wid_..."

3a. Append section via full HTML (classic)

python3 - /tmp/w-{wid}.html << 'PYEOF'
import sys
f = sys.argv[1]
html = open(f).read()
section = """<div style="background:#2a2a2a;padding:16px;border-radius:8px;margin-bottom:12px;">
  <h3 style="margin:0 0 8px;color:#fff;font-size:16px;font-weight:500;">Section title</h3>
  <p style="margin:0;color:#999;font-size:14px;">Content — $100 safe, no escaping needed</p>
</div>
<!-- NEXT -->"""
html = html.replace('<!-- NEXT -->', section)
open(f, 'w').write(html)
PYEOF
cat /tmp/w-{wid}.html | duoduo-widget update --wid "wid_..."

Quoted heredoc 'PYEOF' — write raw HTML, no shell escaping. Only change content inside """...""".

3b. Incremental update via `--patch` (preferred for data-heavy widgets)

After the skeleton is pushed, use --patch to update specific parts of the page without re-sending the entire HTML. This is faster, uses less bandwidth, and avoids morphdom re-rendering.

duoduo-widget update --wid "wid_..." --patch '[
  {"op":"append","selector":"#rows","html":"<tr><td>New item</td><td>$100</td></tr>"},
  {"op":"text","selector":"#count","text":"42"},
  {"op":"innerHTML","selector":"#status","html":"<strong style=\"color:#4ade80\">Done</strong>"}
]'

Patch operations:

Op	What it does	Requires
`append`	Insert `html` as last child of `selector`	`html`
`prepend`	Insert `html` as first child of `selector`	`html`
`replace`	Replace element matching `selector`	`html`
`innerHTML`	Set innerHTML of `selector`	`html`
`text`	Set textContent of `selector`	`text`
`remove`	Remove element matching `selector`	—

When to use patch vs full HTML:

Patch: tables gaining rows, dashboards updating numbers, status text changes, progressive list building
Full HTML: first skeleton push, layout changes, adding new scripts/CDN libraries

Important: Patches update the live viewer instantly but do NOT update the stored HTML on the server. To ensure the finalized artifact includes all changes, use this pattern:

Push skeleton via full update --html (keep the temp file)
Stream data via --patch for live viewer speed
In parallel, keep appending to /tmp/w-{wid}.html locally
Before finalize, do one last cat /tmp/w-{wid}.html | duoduo-widget update --wid ...
Then finalize

Or simply: pass the final complete HTML via duoduo-widget finalize --wid ... --html "..." if available.

Skeleton design for patch: Give target elements id attributes so patches can address them:

<tbody id="rows"></tbody>
<!-- append rows here -->
<span id="count">0</span>
<!-- update text here -->
<div id="status">Loading...</div>
<!-- update status here -->

4. Finalize

duoduo-widget finalize --wid "wid_..."

Rules

Copy from references/html_patterns.md — read it first, pick a section template, change only the data values. Never design HTML from scratch
One section per Bash call — heredoc + cat pipe in a single command
Push after every section — never batch
Never build full HTML in context — the temp file accumulates; context only sees the section
Never read the temp file back — it only flows through the pipe
Act on _hints in update output: no_viewers → send link; ttl_low/ttl_expiring → finalize now; many_updates → wrap up

Interactive widgets

duoduo-widget open --title "Confirm" --ttl-seconds 300 \
  --interaction-mode submit --interaction-prompt "Review and confirm"

Button: <button onclick="window.duoduo.submit('action', {key:'val'})" style="background:#4a9;color:#fff;border:none;padding:10px 24px;border-radius:6px;font-size:14px;cursor:pointer;">Label</button>

Read result: duoduo-widget wait --wid "wid_..." --timeout-seconds 120

HTML rules

Inline styles only. CDN: cdnjs.cloudflare.com, esm.sh, cdn.jsdelivr.net, unpkg.com
Forbidden: fetch(), XMLHttpRequest, WebSocket, eval(), new Function()

Templates — read references/html_patterns.md first. Copy a template, change data values only.

CLI reference

Command	Purpose	Key flags
`open`	Create draft	`--title`, `--ttl-seconds`, `--interaction-mode`, `--interaction-prompt`
`update`	Push HTML or patch	`--wid`, stdin or `--html`, `--patch <json>`, `--text-fallback`
`finalize`	Freeze	`--wid`
`wait`	Block for submit	`--wid`, `--timeout-seconds`
`get`	Poll status	`--wid`

State machine

draft → finalized → awaiting_input → submitted (terminal)

Finalized artifacts are permanent. Fork: open --fork <widget_id>.

Environment

WIDGET_SERVICE_URL env var (default: https://aidgets.dev).

interactive-widget