@volter-ai-dev/supercode-ui 0.1.69 → 0.1.71

package/README.md

@@ -1,5 +1,12 @@
 # `@volter-ai-dev/supercode-ui`
 
+Repository reference: [UI inventory](../../docs/reference/ui.md) ·
+[feature inventory](../../docs/reference/features.md) ·
+[ideal Storybook first](../../docs/contributing/ui-development.md).
+These repository guides describe current coverage and proposed components; the API below
+describes this package. Workflow and orchestration currently have session-level provenance,
+but no dedicated board, job, run, or routing components.
+
 `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.
@@ -9,6 +16,34 @@ The package does not inject iframes, open sockets, read native session files, pe
 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.
 
+## Compose a host layout with shared behavior
+
+`MessengerProvider` owns shared navigation and conversation state. Put
+`MessengerSessions` in a persistent sidebar and `MessengerContent` beside it; the
+content retains the complete messenger's actions, receipts, recovery, settings,
+and child-session inspector. `useMessenger()` exposes navigation to host controls.
+
+```jsx
+<MessengerProvider state={state} adapter={adapter} initialView="new">
+  <aside className="scui-root"><MessengerSessions /></aside>
+  <section className="scui-root">
+    <MessengerContent showBack={false} starter={{
+      variant: 'starter', environmentLabel: 'This workspace',
+      suggestions: ['Explain this workspace', 'Fix the failing test'],
+      initialDraft: storedNewDraft, onDraftChange: saveNewDraft,
+    }} />
+  </section>
+</MessengerProvider>
+```
+
+Import these from `/preact` or `/react` (or their `/messenger` subpath).
+The host supplies layout sizing. The optional centered starter uses the same
+harness readiness, attachments, execution modes, and submission logic as the
+complete messenger. Its persisted draft is separate from `state.savedDraft`,
+which belongs to the attached conversation. An asynchronous start must settle
+successfully before the starter clears its draft; merely becoming busy or
+allocating a new runtime is insufficient.
+
 ## Storybook is the component contract
 
 The package's complete development, documentation, and acceptance surface lives in Storybook:
@@ -23,7 +58,8 @@ Stories import the same built public artifacts that consumers install. They cove
 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.
+dark consumer themes. The static build is available through `build:storybook`; see the
+[validation guide](../../docs/contributing/validation.md) for current automation.
 
 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.