feat(ui-tui): widget-app SDK — apps as state+reducer+render, with three reference apps

[OutThisLife]

Summary

Stacked on #20379. Turns the layout/theme engine into an authorable surface — the TUI counterpart of the desktop component model. A widget app is state + init(arg) + reduce(input) + render(ctx), registered by id, launched from a slash command. Three reference apps ship with it: the ported /grid-test and /dialog-test demos, plus a new /weather app that proves the async-data contract.

The SDK (ui-tui/src/sdk/)

• types.ts — the WidgetApp<S> contract: id + help (surfaced in / completions), mode (modal owns input and blocks the composer; ambient captures nothing, never blocks, toggles closed on relaunch) + zone placement — dock rows (dock-top/dock-bottom, right-aligned card rows in the chrome) and side RAILS (top-right/bottom-right/top-left/bottom-left: reserved columns beside the transcript that text REFLOWS around; apps declare width, same-corner cards stack, crash-isolated by a per-widget error boundary), init (slash tail → state; null ⇒ launcher prints usage), reduce (next state / same reference to swallow / null to close), render (composes SDK primitives at viewport level).
• registry.ts — the registry IS the catalog: defineWidgetApp registers at module load (last-writer-wins so user apps can shadow built-ins); slash commands are GENERATED from listWidgetApps() and / completions merge each app's help client-side — adding an app is one defineWidgetApp call, no command/completion lists to touch on either side.
• host.tsx — the ONLY core coupling, five functions: launchWidget(id, arg) (slash), openWidget(app, state) (typed programmatic launch — apps stack each other), updateWidget(app, fn) (async delivery: patches state only while the app is still active, so a late fetch can never resurrect a closed app), dispatchWidgetInput (input pipeline), ActiveWidgetSlot (modal render slot) + AmbientDock (right-aligned flow dock above the bottom status rule — never floats over the transcript). The active app lives in the overlay store's generic widget slot and blocks the composer like any overlay.
• index.ts — the one import an author needs: app contract + host, layout engine (resolveGridTracks/layoutWidgetGrid/layoutGridAreas + WidgetGrid/GridAreas), Overlay/Dialog, chrome primitives (chipRowProps, listRowStyle, scrollbarColors, useMenu, MenuRow, OverlayHint, …), color math (mix, liftForContrast, …).

Reference apps (sdk/apps/)

App	Demonstrates
grid-test	stateful reducer (~140 lines of keybindings moved out of useInputHandlers), app stacking via openWidget (d opens the dialog app)
dialog-test	zoned Overlay + Dialog + backdrop, minimal close-only reducer
weather	async data + ambient mode: init fires the fetch, results land via updateWidget; docks as a glanceable card (composer stays live, /weather toggles it away); table-driven WWO-code → ASCII-art buckets; every tint is a theme family tone (sun = primary, rain = shell blue, thunder = warn)
ticker	animated ambient: fake 1-pip chart, random-walk price + live block sparkline at 250ms (streams-demo style — the component owns the animation, app state is just the symbol), direction-colored via theme ok/error

Core shrinkage

interfaces.ts drops DialogState/GridTestState; overlayStore's two demo slices collapse into widget; appOverlays/appLayout lose bespoke demo branches; the slash commands are three-line launchers through one widgetCommand helper.

Self-authoring (Hermes makes its own widgets)

The Python-plugin contract, mirrored: drop <name>.mjs into $HERMES_HOME/tui-widgets/ default-exporting register(sdk) — the SDK object is passed IN (user files have no import path to the bundle: defineWidgetApp, updateWidget, React, h, Box/Text/Dialog/Overlay/WidgetGrid/GridAreas). Loaded at boot + /widgets-reload (cache-busted, last-writer-wins, errors log-and-skip). A registry-first dispatch fallback means late-registered widgets get their slash command with zero static wiring. The tui-widgets skill (skills/productivity/tui-widgets/) teaches the agent the contract, with a working /clock template.

Reviewer guide

Read sdk/types.ts (contract) → sdk/host.tsx (five integration points) → sdk/apps/weather.tsx (canonical data-backed consumer). The core diff is almost entirely deletions.

Demo commands

Command	Shows
/grid-test (4x3, 6 4, streams)	arrows/hjkl move, a areas, s streams, g/p gap/padding, n nest, + - ] [ resize, z/Enter zoom, d stacks the dialog app, r reset, Esc/q close
/dialog-test [zone]	zoned viewport overlay with backdrop scrim
/weather [location]	docked ambient card: live wttr.in conditions + themed ASCII art, composer stays usable; /weather again dismisses (blank location = IP geolocation)
/ticker [symbol]	docked animated sparkline ticker; stack it next to /weather to see the multi-widget dock
/widgets-reload	rescan $HERMES_HOME/tui-widgets/ — try it with the skill's clock.mjs template, then /clock Asia/Tokyo

Test plan

• 6 host-contract tests: lifecycle, refusal→usage, unknown id, app stacking, typed openWidget, $isBlocked
• Loader e2e: temp-dir .mjs → load → registered + launchable, broken files reported not fatal
• 4 async-contract tests: loading→ready via updateWidget, late-resolution guard (toggle-close mid-flight), error phase, keymap (fetch mocked — no live network)
• Slash + grid component tests updated to the widget slot
• 1253 vitest, typecheck, lint, build green

Follow-up (not this PR)

External authorship: data-driven widget manifests over the gateway for Python plugins, and/or publishing @hermes/ink + the SDK as a package. The SDK stays internal until the contract has soaked.

[github-actions]

૮ >ﻌ< ა ci review

_{running on 2ed61d4}

CI timings

CI timings · View job

Wall time 7m48s vs 10m10s (-23.3%). 8 job(s) slower, 10 faster, 3 unchanged.

• Build&Test Docker image / build (arm64, ubuntu-24.04-arm, linux/arm64, type=gha,scope=docker-arm64, type=gha,mode=max,scope...: -120.0s
• Build&Test Docker image / build (amd64, ubuntu-latest, linux/amd64, type=gha,scope=docker-amd64, type=gha,mode=max,scope=do...: -108.0s
• Docs Site / docs-site-checks: -78.0s
• Python tests / Run tests slice 5/8: -76.0s
• Python tests / Run tests slice 4/8: -33.0s