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

3a. Append section via full HTML (classic)

python3 - /tmp/w-{wid}.html \x3C\x3C 'PYEOF'
import sys
f = sys.argv[1]
html = open(f).read()
section = """\x3Cdiv style="background:#2a2a2a;padding:16px;border-radius:8px;margin-bottom:12px;">
  \x3Ch3 style="margin:0 0 8px;color:#fff;font-size:16px;font-weight:500;">Section title\x3C/h3>
  \x3Cp style="margin:0;color:#999;font-size:14px;">Content — $100 safe, no escaping needed\x3C/p>
\x3C/div>
\x3C!-- NEXT -->"""
html = html.replace('\x3C!-- 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":"\x3Ctr>\x3Ctd>New item\x3C/td>\x3Ctd>$100\x3C/td>\x3C/tr>"},
  {"op":"text","selector":"#count","text":"42"},
  {"op":"innerHTML","selector":"#status","html":"\x3Cstrong style=\"color:#4ade80\">Done\x3C/strong>"}
]'

Patch operations:

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:

1. Push skeleton via full update --html (keep the temp file)
2. Stream data via --patch for live viewer speed
3. In parallel, keep appending to /tmp/w-{wid}.html locally
4. Before finalize, do one last cat /tmp/w-{wid}.html | duoduo-widget update --wid ...
5. 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:

\x3Ctbody id="rows">\x3C/tbody>
\x3C!-- append rows here -->
\x3Cspan id="count">0\x3C/span>
\x3C!-- update text here -->
\x3Cdiv id="status">Loading...\x3C/div>
\x3C!-- update status here -->

4. Finalize

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

Rules

1. Copy from references/html_patterns.md — read it first, pick a section template, change only the data values. Never design HTML from scratch
2. One section per Bash call — heredoc + cat pipe in a single command
3. Push after every section — never batch
4. Never build full HTML in context — the temp file accumulates; context only sees the section
5. Never read the temp file back — it only flows through the pipe
6. 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: \x3Cbutton 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\x3C/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

State machine

draft → finalized → awaiting_input → submitted (terminal)

Finalized artifacts are permanent. Fork: open --fork \x3Cwidget_id>.

Environment

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