We are building a web UI and web-renderer system for AppWeaver. Current goal
- Support rich web renderers for commands/subcommands, starting with a custom web renderer for
todo list. - Keep the existing text command flow working.
- Reuse existing command handlers/business logic where possible.
- Allow web UI actions to map into normal command invocations first, instead of overengineering adapters. What already exists
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
- Local web server exists in
src/web/server.ts,src/web/routes.ts,src/web/command-catalog.ts,src/web/execute.ts,src/web/chat.ts. - Web API supports:
GET /api/healthGET /api/commandsGET /api/commands/:namePOST /api/commands/:command/:subcommandPOST /api/chat
- Plugin commands are included in web command discovery if the plugin exposes
commandDefinition. - Plugin commandDefinition can now be either:
- a concrete
CommandDefinition - or a function
(prefix, alias) => CommandDefinition
- a concrete
src/commands/help/handlers.tswas updated to resolve plugin command definitions correctly. Frontend/web
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.
- Solid + Vite app exists under
web/ - Main files:
web/src/App.tsxweb/src/components/TimelineView.tsxweb/src/components/CommandPalette.tsxweb/src/components/Composer.tsxweb/src/types.tsweb/src/utils.ts
- Current UI supports:
- timeline/chat shell
- bottom composer
/command popup- command and subcommand filtering
- auto-focus behaviors
- command execution through HTTP
- chat through
/api/chat
- The popup path parser supports command/subcommand-ish input such as
todo list, and special treatment for/help. Command helper work already done src/system/command-helpers.tsnow exists with:createCommand(...)createSubcommand(...)
- It uses the shared representation base from:
src/system/representation.ts
- Helper-based subcommands currently include:
definitionrepresentationhandlerrenderers- optional
adapter
- Important: adapters are optional by design. Do not force adapters everywhere.
- The current practical rule is:
- prefer transforming web actions into normal command invocations first
- only add adapters if a command truly needs one later Important architectural decisions already made
- We want renderer targets to be:
textwebnotcli
- We are leaning toward adding
webtoMessageSourceand eventually removingpluginfromsrc/messaging.ts, but that has NOT been fully implemented yet. - Long-term renderer selection should likely be global/shared, not per-plugin hacked in adapters.
- But we have NOT yet implemented a full target-aware renderer dispatcher.
- For now, web still mostly executes commands through existing command-text paths or reconstructed command payloads. What we want next Primary next goal
- Build a real custom web renderer for
todo list. What “todo list web renderer” should mean - A dedicated web view for the
todo listsubcommand, not just plain text in a card. - It should render the todo tree/list in structured HTML/UI.
- Desired interactions we discussed:
- click checkbox to mark item
in_progress - double click to mark item
done - click
[x]to delete - edit item text
- insert new item
- move/reorder item, maybe change parent
- maybe save-all mode, maybe immediate execution mode
- click checkbox to mark item
- However, we decided NOT to overbuild a generic action-adapter system yet.
- First preference:
- map web UI actions back into normal command invocations where possible, such as:
/todo update .../todo done .../todo delete .../todo add .../todo move ...
- after each action, refresh the rendered list by re-running the list command or equivalent
- map web UI actions back into normal command invocations where possible, such as:
- Only add custom web-only action plumbing if command-shaped mapping becomes clearly awkward. What is still missing
- No real renderer selection system yet (
textvsweb). - No standard place yet where command handlers return
representation + renderersand dispatch chooses target. - No actual custom web renderer has been wired into command dispatch yet.
todo listcurrently still goes through the generic command form/result system.MessageSource.weband target-aware rendering are still conceptual, not finished infra.- No websocket live event system yet; current web messaging uses HTTP.
Practical next step
Implement the smallest clean vertical slice for
todo listcustom web rendering, without overhauling the whole architecture. Recommended scope for the next step
- Inspect the todo plugin structure, especially:
plugins/todo/commands/list/*- existing handler/representation/text rendering
- Add a custom
renderers/web.tsfortodo list - Keep the current web shell architecture, but teach it to recognize/render the
todo listresult specially - 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
- for example, a click in the web renderer can call the existing
- After an action succeeds, refresh the
todo listweb view by re-running list with the same filters/options - Do not try to solve every renderer/dispatcher abstraction globally unless needed for this slice
- Prefer one focused working example over a generalized framework that is not yet exercised Suggested approach
- Start by inspecting:
plugins/todo/commands/list/handler.tsplugins/todo/commands/list/representation.tsplugins/todo/commands/list/renderers/text.tsor equivalent existing text renderer
- If there is no suitable representation for web, extend or improve the
todo listrepresentation so it contains enough structured data for a web view. - Then create a web renderer for that representation.
- Wire the frontend so when a
todo listresult is returned, it renders a structured todo view instead of plain text. - Keep fallback to plain text if web rendering is unavailable. Important constraints
- Do not force adapters everywhere.
- Do not require every command to have a web renderer yet.
- Do not break existing text/CLI behavior.
- Keep the new helper system optional.
- Prefer incremental integration over large-scale refactors. Useful context on code quality
src/web/*backend code is currently cleaner and more structured than the frontend was.web/src/App.tsxwas recently split into components and is now more manageable.- The next good cleanup after the todo renderer may be:
- further splitting timeline card components
- introducing a global renderer-selection helper
- But do not do those first unless needed to make
todo listwork well. Deliverable for this session - A working first custom web renderer path for
todo list - Enough backend/frontend wiring so the web UI can show a structured todo list and trigger at least one or two meaningful actions through the existing command execution path
- A short explanation of the architecture chosen and what should come next after this slice My practical recommendation:
- yes, start the new session with exactly this
- the next logical step is not a full renderer framework
- it is one real todo list web renderer slice that proves the model
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:
stylesheetsare presentation-only. Do not rely on global app classes fromweb/src/styles.css; only:roottheme variables (for examplevar(--color-accent)) are guaranteed to inherit into the shadow tree.- Prefer stable string
idvalues per logical sheet (for examplefile-plugin-tree); the client dedupes byidand replacescssTextwhen the sameidappears again on an updated root. - Avoid
@importand remote fonts in v1 payloads; keep CSS self-contained and small.
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.
- Put
renderKeyon repeated or stateful element nodes. It must be stable across equivalent refreshes, unique among siblings, independent of sorting/counts, and never reused for another element tag. - Include branch context when one entity appears in several places, for example
topic:nostr:event:<id>andmood:focused:event:<id>.renderKeyidentifies one rendered instance. - Put
entityKeyin element props when several render instances represent one logical entity, for examplenostr-event:<id>. Duplicate entity keys are intentional and are not reconciliation keys. - Unkeyed legacy nodes continue to reconcile positionally. Reordered stateful collections should always provide keys.
- The client uses a focused recursive WebNode reconciler rather than Solid's stock keyed array reconciler because WebNode arrays may mix keyed elements, unkeyed elements, and text nodes.
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...',
}
- Omitted or
widgetkeeps the widget-wide Working overlay. entityuses the nearest ancestorentityKey, marks every mounted copy in the same widget source pending, and falls back to widget pending when no entity is available.noneruns without a pending overlay.- Keep the action's refresh command server-authoritative. Entity pending remains active through refresh settlement, and late older refresh roots are ignored.