The user watches the widget live — stream content fast, one section per tool call.
Quick start
CODEBLOCK0
1. Open
CODEBLOCK1
Send links.feishu_sidebar or links.browser to user. NEVER send control_url/control_token.
2. Skeleton + push
CODEBLOCK2
3a. Append section via full HTML (classic)
CODEBLOCK3
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.
CODEBLOCK4
Patch operations:
Op
What it does
Requires
INLINECODE8
Insert html as last child of INLINECODE10
INLINECODE11
INLINECODE12
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:
1. 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 INLINECODE31
Then INLINECODE32
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:
CODEBLOCK5
4. Finalize
CODEBLOCK6
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
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
- Added support and documentation for fast incremental widget updates using the new `update --patch` CLI flag.
- Described available patch operations (e.g., append, prepend, replace, innerHTML, text, remove).
- Clarified when to use patch vs. full HTML updates and how to ensure the finalized artifact is complete.
- Updated CLI reference to include `--patch`.
- Provided a best-practice section for designing skeletons with target IDs for patching.
