Overview

Macaron Artifacts keeps the browser experience independent from the coding harness. The root package starts one local Node server and serves one prebuilt React application. Each conversation selects Claude Code, Codex, OpenCode, pi, Hermes, or OpenClaw through the same session and streaming contract.

Repository shape

• artifacts/src/server owns sessions, turns, Profiles, pairing, artifacts, and native harness lifecycles.
• artifacts/src/web contains the shared conversation UI, Canvas panel, Profile manager, and theme system.
• artifacts/src/shared defines the session, Profile, harness, and AI SDK UI-message types shared by both sides.
• artifacts/skills/ui4a/SKILL.md is generated from the runtime manifest and gives models the exact UI4A contract.
• bin/macaron-artifacts.mjs starts the bundled server and is the only published launcher.

A turn from browser to harness

1. The browser creates or selects a session with a workspace, harness, Profile, and optional model override.
2. ActiveConversation captures the resolved configuration for that turn and asks the selected HarnessAdapter to start native work.
3. Native events are normalized into AI SDK UI-message chunks while preserving each harness's event boundaries.
4. The browser's per-session Chat instance renders text, reasoning, tools, approvals, and completion state.
5. Title and follow-up enrichment runs separately on a disposable native branch and never changes the durable conversation.

There is no harness-specific SPA, launcher, message store, or Canvas implementation. Adding a harness means implementing HarnessAdapter, declaring capabilities, and registering it in artifacts/src/server/harnesses/index.ts.

Current harnesses

Read Server for lifecycle details and Packaging for the distribution boundary.