@volter-ai-dev/supercode-ui 0.1.0

package/README.md

@@ -0,0 +1,116 @@
+# `@volter-ai-dev/supercode-ui`
+
+`supercode-ui` is the composable default interface for Supercode's glue workflows: inspect a
+native coding-agent session, continue it safely, switch harnesses, answer requests, hand it to a
+terminal, and export it back without hiding fidelity or residue.
+
+It is deliberately separate from both the headless `supercode-client` and any embedding shell.
+The package does not inject iframes, open sockets, read native session files, persist credentials,
+or assume Lucarne. A host supplies bounded public state and receives typed intents. This lets a
+browser widget, editor panel, desktop app, or ordinary page share one capability-honest UI.
+
+## Storybook is the component contract
+
+The package's complete development, documentation, and acceptance surface lives in Storybook:
+
+```sh
+npm run storybook --prefix sdk/ui
+npm run build:storybook --prefix sdk/ui
+npm run test:storybook --prefix sdk/ui
+```
+
+Stories import the same built public artifacts that consumers install. They cover every canonical
+harness identity, loading phase, transcript primitive, native request, tool lifecycle, long plan,
+session inventory, composer/continuation state, receipt, narrow messenger layout, and modular
+override seam. Chromium interaction and axe accessibility tests run every story in both light and
+dark consumer themes. The static Storybook build is part of the repository SDK gate.
+
+The older browser fixture remains a low-level embed smoke test; it is not a parallel design system.
+New component behavior and hard-to-reach states belong in Storybook first.
+
+## Use the whole messenger
+
+```js
+import { mountSupercodeMessenger } from '@volter-ai-dev/supercode-ui/embed';
+import '@volter-ai-dev/supercode-ui/styles.css';
+
+const mounted = mountSupercodeMessenger(document.querySelector('#agent'), {
+  state: initialState,
+  onIntent(intent) {
+    host.send(intent);
+  },
+  onClose() {
+    panel.close();
+  },
+});
+
+host.onState((state) => mounted.update(state));
+```
+
+## Take only the parts you need
+
+```js
+import {
+  Conversation,
+  SessionList,
+} from '@volter-ai-dev/supercode-ui/preact';
+import { HarnessLogo } from '@volter-ai-dev/supercode-ui/preact/logo';
+import { groupConversation } from '@volter-ai-dev/supercode-ui/core';
+```
+
+The public components are `SupercodeMessenger`, `Conversation`, `TranscriptEntry`,
+`ActivityGroup`, `RequestCard`, `SessionList`, `SessionRow`, `Composer`, `ContinuationBar`,
+`LoadingStatus`, `TaskPlan`, `SessionDetails`, and `HarnessLogo`. Pure state readers, selectors,
+formatters, and intent constructors live at `supercode-ui/core` and have no DOM or Preact imports.
+For genuine partial delivery, the `preact/logo`, `preact/conversation`, `preact/sessions`,
+`preact/composer`, and `preact/messenger` subpaths are independently tree-shaken artifacts; taking
+the logo does not pull in Markdown, the messenger, or session-list code.
+
+## Bind directly to the headless controller
+
+Trusted desktop, editor, and Node hosts can avoid rewriting ordinary snapshot and action glue:
+
+```js
+import { createControllerBinding } from '@volter-ai-dev/supercode-ui/controller';
+
+const binding = createControllerBinding(controller, {
+  onDraft: saveDraft,
+  onAcknowledge: clearAttention,
+  onArtifact: materializeArtifactInTrustedHost,
+});
+
+binding.subscribe((state) => mounted.update(state));
+mounted.update(binding.getState());
+```
+
+The binding maps only standard controller operations. Host-owned pagination, durable attention,
+drafts, artifact materialization, and future reduction receipts remain explicit callbacks. A
+browser should receive projected state from a trusted host rather than instantiate a local
+controller or gain filesystem authority.
+
+## Modularity contract
+
+- Every component accepts data and callbacks. No component reaches into a global controller.
+- The complete messenger accepts `slots` for high-level replacement and `components` for row-level
+  replacement. Replacements receive the same typed, capability-filtered props as defaults.
+- Stable `scui-*` classes and `data-*` attributes support additive styling; CSS custom properties
+  are the supported theme API.
+- `styles.css` contains both neutral tokens and default component rules. Teams may load it whole,
+  override tokens, or omit it and style the stable markup themselves.
+- Component state is local presentation state only (navigation, disclosure, search, drafts and
+  scroll position). Machine/session truth always arrives through `state`.
+- Unknown harness marks are a contract error. `HarnessLogo` renders nothing and calls
+  `onMissingLogo`; it never invents initials that disguise an unsupported harness.
+- Expensive transcript details are mounted only when disclosed. The host remains responsible for
+  bounding and paging transcript/session state.
+
+## Host boundary
+
+`SupercodeUiState` is a transport-safe view model, not a duplicate controller. A trusted host maps
+`SupercodeController` snapshots and persisted inventory into it, then handles `SupercodeUiIntent`.
+The browser cannot supply locators, credentials, policy, environment variables, or arbitrary
+materialization paths. Session keys and target harnesses must be revalidated by the host.
+
+An embedding product such as Vibewaiting should therefore be small: Lucarne owns its iframe and
+launcher lifecycle, Supercode owns this UI and the controller semantics, and Vibewaiting only
+bridges state/intents plus host-specific theme and persistence policy.