Macaron Artifacts
Architecture

Web

The shared React application for conversations, Profiles, Canvas, approvals, and themes.

The WebUI is a single Vite-built React application under artifacts/src/web. It does not select a different SPA for each harness: the active conversation tells the server which HarnessAdapter to use, while the browser keeps one consistent interaction model.

Main surfaces

  • App.tsx composes the sidebar, top bar, conversation, composer, Profile manager, and responsive Canvas split view.
  • src/web/chat keeps a stable AI SDK Chat instance per session, queues messages for the owning session, and reconnects to active turns.
  • ArtifactPanel discovers .artifacts/canvases/*.ui4a.tsx, shows source while it streams, and mounts the live Canvas when the module is ready.
  • src/web/components/profiles edits harness-specific Profiles with Headless UI controls and applies changes from the next turn.
  • src/web/theme maps Shiki workbench roles to semantic CSS variables shared by the host and generated UI.

Rendering and accessibility

Host controls use native HTML plus Headless UI where behavior is stateful: dialogs, tabs, selects, disclosures, and menus retain keyboard navigation and focus management. UnoCSS presetWind4 supplies the shared reset and utilities. Generated surfaces use a scoped Wind4 runtime so they cannot replace the host reset.

The layout preserves background turns when the selected conversation changes. Mobile viewports collapse Canvas into a drawer, and the split separator exposes its current value to assistive technology. Focus indicators come from the theme's focus token rather than from repeated container borders.

Reasoning is visible by default. Summary updates show the latest entry while keeping earlier entries available; full reasoning uses a height-limited scrolling region with fading edges. Scrolling up pauses automatic following. The UI preserves independent AI SDK reasoning parts and their tool/text boundaries instead of joining them into one monologue. Streaming motion and automatic following stop when the turn ends or is interrupted.

Themes

The picker stores a paired light/dark family. Appearance (auto, light, or dark) remains independent from family selection, and only the variant matching the current appearance is loaded. Theme roles include editor, sidebar, title bar, menu, widget, input, dropdown, selection, focus, and optional borders; missing roles fall back to composited semantic values instead of painting every surface with a border.

On this page