We are building a web UI and web-renderer system for AppWeaver. Current goal

Reusable local date/time display: timestamp elements accept timestampMs (epoch milliseconds) and an optional label prefix. The client formats them in the browser's locale/timezone, including the timezone abbreviation, with an ISO datetime/tooltip for the exact instant. Standard text size/tone/style props apply.

textField supports inputType: "datetime-local" for a native date/time picker. Supply a timezone-qualified ISO datetime in value to display that instant in the browser's timezone. On form submission, nonempty date/time fields are converted from browser-local time to UTC ISO strings before merging into action arguments/options. Date-only and time-only fields keep their existing string semantics. The picker supports second precision.

select supports choiceSource: "nostrAccounts" with formFieldName to submit a public key from the current browser Nostr account or a named saved bunker connection. Choices are resolved client-side from the shadow-root account context and authenticated bunker-connections API, using data.userPubkey (not the remote signer server key). Choices load automatically on mount with loading/error feedback; it does not invoke signing, switch the authenticated account, or send credentials through form submission. With no connected account it explains how to connect; plugins may offer a separate manual textField fallback. Static select behavior is unchanged when choiceSource is omitted.

Static select elements may also supply a command action to run immediately on selection, without a containing form or submit button. formFieldName identifies the selected scalar argument; include that name in formOptionFieldNames to put it in command options instead. The selected value replaces that one action field, preserving other arguments/options and normal root replacement. Without action, selects retain their ordinary form-input behavior. ariaLabel labels the native input.

Generic command forms render boolean options as checkboxes, using their web default or false. A single named boolean checkbox in a command form submits its checked state as a boolean, including false; repeated-name checkbox groups keep their value-array behavior. Optional false flags are omitted from the built-in text invocation bridge.

Persistent command forms keep their field values on submission, including while a request is pending or fails. Automatic hide/reset is limited to forms with both a revealId and hiddenUntilRevealed: true that are currently revealed. Editor Save actions rely on the returned root to supply saved values or a retained error draft. Plugins should parse web PluginInvocationContext.jsonPayload as structured arguments/ options; the display-oriented CLI bridge does not preserve scalar whitespace boundaries.

Generic details and summary tags render native HTML disclosures, collapsed initially. Put a summary element first in a details element's children, followed by the expandable content. Native keyboard interaction applies; scoped stylesheets can style the heading and body without introducing custom actions.

treeItem.expandOnceKey requests additive expansion once per item/key within a widget's saved tree state. Mark ancestors too when a nested item must become visible. Repeated renders/polls preserve subsequent manual collapses; a new context key expands again. Unrelated expansion states are preserved, with no focus/scroll or collapse-all behavior. Lazy branches invoke their existing load action on that first expansion when needed.

Keyed tree reordering

A tree can opt into props.reorder: { action, field, target }, where action is a command and target is arguments or options. Only direct treeItem children with a nonempty props.reorderKey participate. Unkeyed rows, diagnostics and descendants remain outside the movable set. Keys must be unique. This is sibling ordering, not reparenting or cross-tree dragging.

Keyed items render a small pointer-drag handle. The drop marker indicates before/after the target summary. Only a completed changed move invokes one command, replacing action[target][field] with the full ordered key array and preserving the caller's other arguments/options. No command runs during pointer movement. Escape, pointer cancellation, window blur, root updates and unmount cancel the gesture and remove listeners/markers. Reordering is blocked while busy or filtered; unknown/cross-tree targets are ignored. Ordinary unconfigured trees retain their existing behavior.

The command owner must validate membership and include/check a revision or snapshot to reject stale actions; the renderer does not persist order or infer domain policies. There are no built-in keyboard movement shortcuts. Descendants and unkeyed rows within an opted-in tree reserve a fixed-width, noninteractive handle gutter matching the drag handle. This keeps hierarchical indentation visible when only the root rows are movable. Nested trees establish their own gutter setting.

The generic browser nostr.signEvent client action accepts signingMode: "immediate" for current-time signing with an onSuccessCommand handoff. Its default remains "scheduled", preserving the date/runAt requirements of scheduling flows. Immediate signing forwards the signed event but does not inject a scheduled runAt argument or publish it. It also accepts optional allowedPubkeys to restrict the standard signer picker to the intended account(s); a returned signature from another author is rejected before the onSuccessCommand handoff. Omit it to keep unrestricted signing.

Backend/web

Background command outcomes and diagnostics

WebNodeRoot.meta.outcome optionally supplies { state: "success" | "warning" | "error", message: string }. Background actions apply this outcome to their clientStatus.statusTargetId; a normal command completion cannot overwrite an explicit outcome with the action's default success message. Outcomes remain request-scoped even when the user switches sessions during a running command.

Handlers can stream transient status via sendReply(encodeCommandStatus(update)) using the shared command status contract. Updates carry the target id, state, message, diagnostic output and nullable progress. commandStatus renders an indeterminate bar for pending work without a numeric fraction, and an expandable diagnostic history for output. Terminal streamed statuses are also preserved on command completion. These transport updates are not persisted as timeline events. Keep credentials and private request content out of diagnostic messages.

Bot restart notifications

After /bot restart successfully requests a watch restart, the backend broadcasts process_restart to every authenticated, non-demo WebSocket connection. Each tab/PWA window shows the existing process-restart client view in its own active timeline and immediately treats connection loss as an expected restart. The initiating window's command result uses the same process instance and request timestamp, so it replaces the live notice rather than creating a second card. Timeline catch-up also deduplicates notices against persisted command results. Observer notices are local UI entries; they do not write restart commands into other sessions' stored history.

The existing authenticated process-instance handshake changes the cards to “Restarted” after reconnection to a new bot process. Real connection errors still appear when no restart is expected or the expected-restart window expires. This notification covers /bot restart from web, DM, and local command transports; unexpected process exits and externally written restart signals do not announce a restart through this command notification path.

Universal search and resource views

The authenticated header search uses the shared universal-search contracts and coordinator. Each source returns plain JSON, rendered by core into a tree with collapsible source treeItem branches and leaf treeItem results. Selecting a result invokes the addressed resource-view:v1.open provider through the existing capability modal; plugins retain ownership of the resulting WebNodeRoot.

run_capability accepts resultFormat: "json" for generic raw capability output (capability_result), or "web" (default) for contract-defined webResult rendering. The original fuzzy-file-search operation retains its raw-result compatibility. Authenticated core consumers use a reserved consumerAlias of core:<component>; other aliases resolve to installed plugins. These identify callers for registry routing/logging, not a plugin sandbox. Source discovery and search don't record timeline history. Encoded #/resource/v1/... links open after authentication. Markdown file previews and chat markdown render [label](url) and autolinks as real <a href> tags: http(s)/mailto open in a new tab, workspace-relative paths and @folder/file.md mentions use File resource-view:v1 hashes, and #heading jumps to the matching ATX heading. The markdown source delimiters are dropped; only the label is shown.

Backend interfaces

On viewports narrower than 900px, header app icons occupy a native horizontally scrollable single-row strip. Swipe left/right to reach overflow icons; tapping still opens the app. The logo, layout control, and account menu remain outside the strip. Icon images disable native image dragging, and the strip contains horizontal overscroll while permitting pinch zoom. Desktop header placement is preserved via a display: contents wrapper.

  1. Inspect the todo plugin structure, especially:
    • plugins/todo/commands/list/*
    • existing handler/representation/text rendering
  2. Add a custom renderers/web.ts for todo list
  3. Keep the current web shell architecture, but teach it to recognize/render the todo list result specially
  4. Reuse existing command execution for actions when possible
    • for example, a click in the web renderer can call the existing /api/commands/... endpoint with the right command/subcommand/payload
  5. After an action succeeds, refresh the todo list web view by re-running list with the same filters/options
  6. Do not try to solve every renderer/dispatcher abstraction globally unless needed for this slice
  7. Prefer one focused working example over a generalized framework that is not yet exercised Suggested approach

Widget-wide tree controls

The card-header Collapse all and Expand all controls apply to every treeItem in that WebNodeRoot, including independent sibling trees and nested trees inside layout containers. Each top-level tree registers its toolbar with a stable component token; removing one registration does not clear the others. Tree-specific filter/actions remain attached to their registered toolbar.

Bulk controls record expansion state for all supplied item IDs, including descendants whose components are unmounted under collapsed parents. Existing item IDs retain their state through root refreshes and within the existing stateScopeId cache. New items use the widget's latest bulk preference while that widget is mounted. Individual reopening overrides the saved state, so refreshing does not repeatedly force manually reopened items closed. These controls do not fetch unloaded lazy branches or change archive selection. Inline tree toolbars remain tree-local, and text filtering retains its match-reveal behavior.

When a treeItem sets props.focused: true, its enclosing tree collapses all non-ancestor treeItems, expands the focused treeItem and its ancestor branches (and activates the enclosing tabPanel if inside tabs), scrolls the item's summary into view below any sticky timeline card header, and plays the focus flash animation.

Command-backed downloads

The generic web.downloadCommand client action downloads a text file generated by any command. Its payload contains command, subcommand, arguments, and options. It runs one authenticated JSON command with timeline recording disabled, without replacing the current root or opening a modal. The source widget is busy during generation; failures are shown as system messages rather than downloaded as files.

The target command must return a JSON-encoded string matching WebCommandDownloadSchema in src/web/ui-schema.ts:

{"filename":"report.txt","mimeType":"text/plain;charset=utf-8","content":"Report contents\n"}

The browser validates the envelope, creates a UTF-8 Blob and a temporary download anchor, then removes the anchor and revokes its object URL. No server-side temporary file or plugin-specific browser branch is needed. File content is generated only when clicked, not embedded in every rendered view. Implementations live in web/src/utils/download.ts and the generic client-action dispatcher.

Scoped styles (Shadow DOM)

Command web UIs (WebNodeRoot, kind: 'ui') render inside a Shadow DOM island on the web client. Shared primitives (.web-node, .web-button, tree, overflow menu, tone utilities, etc.) come from a base stylesheet injected automatically; optional stylesheets on the root payload add presentation-only CSS scoped to that render.

Plugin / handler guardrails:

Schema: WebStyleSheet in src/web/ui-schema.ts ({ id, cssText }); optional stylesheets array on WebRenderResultSchema / WebNodeRoot.

Opt-in live refresh

WebNodeRoot.autoRefreshMs (2,000–60,000 ms) opts a render into polling its own meta command. Use it only on read-only view commands, never a command that starts execution. The Shadow DOM host skips polling while hidden/unmounted, busy, or while an input/textarea/select/contenteditable is focused. Requests do not overlap, create timeline entries, or show a pending overlay. Responses use normal root reconciliation and stale-response handling; polling is disposed when the render changes or unmounts. Include a manual Refresh action for recovery after connection errors.

Shadow mount overflow: optional shadowMountOverflow on WebNodeRoot ('hidden' | 'scroll-y'). Omitted or 'scroll-y' lets the inner Solid mount scroll when content is taller than the host (typical timeline cards). Use 'hidden' when your tree defines its own scroll regions (for example a fixed chrome row plus an overflow: auto panel inside stylesheets). The file tree web renderer sets 'hidden' so only .web-file-tree-block scrolls in the modal.

Stable identity and pending UI

Refreshed WebNodeRoot payloads are authoritative complete trees. The client reconciles compatible element nodes so stateful components can keep local UI state while server-rendered props, children, metadata, and stylesheets update.

Command actions may choose pending presentation:

An explicit surface: 'timeline' action renders its result in the main timeline, even when the target command has widget/dock metadata. It does not replace the origin widget or modal root. Actions without a surface can update their origin in place via onReplaceRoot.

pendingUi: {
  presentation: 'entity',
  label: 'Updating...',
}