Injectable console UI

A worker ships pages, function and trigger-activity renderers, forms, and stylesheets into every console tab at runtime — no console rebuild, no iframe, hot reload. This skill is the delivery contract. Looks, tokens and every number: ade/design-system (link to ade/design-system › Numbers, never restate one). Behavior across widths and forms: ade/design-console-ui.

How it works

A worker registers console:script and console:style triggers whose config.path identifies an asset and whose function_id serves {content} for {path}. The console hashes and serves those bytes, then pushes changes to open tabs. Tabs import() scripts and call their default setup(host); styles load as scoped assets. Re-registering a path hot-reloads it. Registration is deployment; disconnect is teardown.

Project layout

mywork/
  build.rs        # ensure dist assets exist before include_str!
  ui/
    page.tsx      # the script asset — default-exports setup(host)
    styles.css    # the style asset — every rule scoped
    build.mjs     # buildWorkerUi({ scope }) — the shared driver
    package.json  # workspace dependency on @iii-dev/console-ui
    tsconfig.json # extends the shared worker tsconfig
    src/          # page, renderers, config form, widgets
  src/
    ui.rs         # embed and register dist/page.js + dist/styles.css

Both sides of the contract are versioned in this repository; nothing is installed from a registry.

1. Add /ui to the root pnpm-workspace.yaml packages list.
2. ui/package.json (copy state/ui/package.json): private, "type": "module", scripts build: tsc --noEmit && node build.mjs and watch: node build.mjs --watch, "dependencies": { "@iii-dev/console-ui": "workspace:*" }, and @types/react, @types/react-dom, esbuild, lucide-react, react, react-dom, typescript as "catalog:" devDependencies — the workspace catalog: in pnpm-workspace.yaml pins every toolchain version once.
3. ui/tsconfig.json is { "extends": "@iii-dev/console-ui/tsconfig.worker-ui.json", "include": ["page.tsx", "src"] }.
4. ui/build.mjs is the whole driver call: import { buildWorkerUi } from '@iii-dev/console-ui/build-worker-ui', then await buildWorkerUi({ scope: 'mywork' }).
5. A Rust worker adds iii-console-ui = { path = "../crates/console-ui" } to /Cargo.toml.

@iii-dev/console-ui's root is types-only at build time; the console serves its runtime from the running SPA. iii-console-ui registers the content function, the asset triggers, and the development watcher; Node workers implement the wire contract directly. Copy state/build.rs and state/src/ui.rs; rename worker and asset paths and keep their tests.

Authoring workflow

1. Read packages/console-ui/index.d.ts, hooks.d.mts and format.d.mts; never guess a component, hook or prop.
2. Select only the needed slots; model the primary object, navigation, actions, async states, and what must survive navigation or reload.
3. Choose one archetype (below); design wide and narrow flows separately.
4. Build with shared primitives and minimal scoped CSS; build (the driver scopes, checks tokens, lints), register, inspect the manifest, exercise the real console.

Living references

Copy delivery plumbing when it matches; never copy a reference's sidebar count, thresholds, controls, or visual hierarchy without deriving them from the new worker's content. The migration recipe and the order of the remaining workers: docs/plans/2026-09-16-worker-ui-migration.md.

Archetypes

Choose one dominant archetype before writing JSX; mixing them produces a generic dashboard. Shapes, wide/narrow flows and references are in ade/design-console-ui › Archetypes.

• Console catalog — many searchable objects with rich detail.
• Database workbench — several tools on one selected resource.
• Directory editor — searchable documents with drafts or preview.
• State explorer — deep but compact hierarchy.
• Settings flow — one configuration entry, host-owned persistence.
• Terminal/instrument — one live surface with a toolbar and status bar.

1. The script asset (ui/page.tsx)

Ordinary React. react, @iii-dev/console-ui and lucide-react resolve at runtime through the console's import map, so they stay external (the driver does this). Default-export setup(host) and make every registration through host: the loader attributes registrations to the script and disposes them on reload. setup may return a disposer (SetupFn in index.d.ts); the loader runs it and the registrations LIFO.

import { type Host, PageHeader, PageMain, type PageRenderProps, PageShell } from '@iii-dev/console-ui'
import { Boxes } from 'lucide-react'

function MyworkPage({ host, onRequestClose }: PageRenderProps & { host: Host }) {
  return (
    <PageShell className="mywork-ui-shell">
      <PageHeader icon={<Boxes />} title="Mywork" description={host.path} onClose={onRequestClose} />
      <PageMain className="mywork-ui-main">{/* the chosen archetype */}</PageMain>
    </PageShell>
  )
}

export default function setup(host: Host) {
  host.pages.register({
    id: 'mywork-manager',       // alone at #/worker/mywork/mywork-manager
    title: 'Mywork',            // nav label
    configurationId: 'mywork',  // host adds the standard settings action
    render: (props) => <MyworkPage host={host} {...props} />,
  })
}

Imports from the shared package and from lucide-react add zero bundle bytes.

Slots

Every register returns a remover and is disposed automatically on hot reload and worker disconnect. Namespaces marked ? are absent on older consoles: feature-detect them.

PageRenderProps: panelSide ('left' | 'right', only to keep wide side navigation on the outer edge); tabId and paneId? (key persisted UI state and per-instance resources on paneId — the same page can be open in two columns of one tab — falling back to tabId on older consoles); onRequestClose? (wire to PageHeader.onClose); workingDir? (the active conversation's live directory, for filesystem-shaped pages only); panelContext? and conversationId?; setDirty? (report unsaved work) and commands? (palette rows and pane-scoped keys, registered from an effect).

Live data: a page registers its own trigger over host.iii with a handler id like iii::-ui::events:: (the iii:: prefix keeps it out of the trace feed; the binding is GC'd with the tab) — useWorkerLive from @iii-dev/console-ui/hooks wraps fetch + bindings + visible-tab poll. Every injected render is error-bounded: import or setup failures drop the extension's contribution and log to the browser console. Scripts run with full console-origin privileges; the wrapper scopes styles, it is not a sandbox.

Trigger renderers: layered ownership

interface TriggerActivityRenderer {
  id: string
  isMatch(triggerType: string): boolean
  tryRender(activity: TriggerActivityMessage): React.ReactNode | null
  tryRenderDetails?(activity: TriggerActivityMessage): React.ReactNode | null
  tryRenderDisplay?(activity: TriggerActivityMessage): React.ReactNode | null
  redactRaw?(value: unknown): unknown
}

TriggerActivityMessage.kind is registration, fired, or retirement; the model carries triggerType, opaque config, optional label and action, delivery, lifecycle and payload/outcome fields. Match triggerType (many sources share engine::register_trigger), parse config without throwing, return null per slot to fall through. tryRender is the source-specific section inside the generic detail view; tryRenderDetails replaces the whole expanded Terminal tab and must carry the lifecycle and delivery facts the host no longer adds; tryRenderDisplay is the compact timeline content inside the host's disclosure button — non-interactive, one line, truncation-safe; redactRaw is pure, non-mutating, total, cycle-safe, and a throw fails closed. The host owns the click target, expanded state, motion, isolation, per-slot fallback and the Raw JSON tab; a once firing and its automatic retirement are one activity.

For harness registrations, label names the binding and metadata.action describes the future event:

{ "trigger_type": "on-message", "config": { "scope": "explorer" },
  "label": "explorer-messages", "metadata": { "action": "new Explorer message received" } }

Registration and active-binding surfaces show label; show action only when activity.kind === 'fired'. Action affects presentation only.

Shared components, hooks, format, icons

packages/console-ui/index.d.ts is the only list of runtime exports: page chrome, List/ListItem, cards, Panel, Chip/Badge, IconButton, the Table family, line Tabs/SegmentedControl, Select/Selector, inputs, Dialog/ConfirmDialog/DropdownMenu/Tooltip/BottomSheet, status and empty states, Eyebrow, SearchField, Toolbar/StatusBar, MetaRow/ActionLine, Kbd/KeyCombo, LiveRegion, Markdown/JSON/code renderers, the terminal atoms (AnsiText, TerminalStream, TerminalCommandLine), CodeEditor, FileDiff, ImageViewer, ModelPicker, DirectoryPicker, and the settings primitives (SettingsSection/SettingsList/SettingsRow/SettingsField, RawValueInput, SettingsDeck). is the one-line tooltip. Confirmation is useConfirm() (render dialog, await confirm({ … })) or ConfirmDialog — never window.confirm. uiClasses holds the stable class recipes (list*, tree*, card*, panel*, chip, table*, tabs*, field*, settings*, eyebrow, toolbar/toolbarEnd, statusbar, spin, pulse) and tokens the CSS variable inventory. When to use each: ade/design-system › Shared components.

Two subpaths bundle (React-free code the console itself uses):

• @iii-dev/console-ui/hooks — useContainerNarrow({ below? }) (attach ref to the pane root; narrow while the pane is below the shared default from ade/design-system › Numbers or your below; synchronous first measure, resizes observed, zero widths ignored), usePaneState(key, initial) (localStorage-mirrored, best effort), useCopyFlash(text, ms?), useWorkerLive({ iii, triggers, fetch, pollMs?, handlerId }).
• @iii-dev/console-ui/format — formatRelative, formatDuration, formatBytes, errorMessage, errorCode, copyText.

Import these instead of keeping a local copy; the migration plan lists the copies still to be replaced.

Icons are lucide-react, an external shared with the console: import { X } from 'lucide-react'. Never hand-write SVG icons (the lint flags them) and never add another icon dependency. Sizes: ade/design-system › Numbers. Never bundle Monaco, CodeMirror, a diff renderer, or an ANSI parser; use CodeEditor, FileDiff, and the terminal atoms.

2. The style asset (ui/styles.css)

Plain CSS, every top-level rule scoped under the worker's wrapper attribute — the console mounts each render inside

[data-iii-ui="mywork"] .mywork-ui-main {
  min-width: 0;
  min-height: 0;
  overflow: auto;
}
@keyframes mywork-flash { /* keyframe names are global: prefix them */ }

use iii_console_ui::ConsoleUi;

ConsoleUi::new("mywork")
    .script("mywork/page.js", include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/ui/dist/page.js")))
    .style("mywork/styles.css", include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/ui/dist/styles.css")))
    .register(&iii);

pnpm --dir mywork/ui watch                      # terminal 1, repo root
cd mywork && III_MYWORK_UI_WATCH=1 cargo run    # terminal 2