@volter-ai-dev/supercode-ui 0.1.35 → 0.1.37

package/README.md

@@ -64,9 +64,9 @@ import { HarnessAdvisory, HarnessSettingsPanel } from '@volter-ai-dev/supercode-
 import { groupConversation } from '@volter-ai-dev/supercode-ui/core';
 ```
 
-The public components are `SupercodeMessenger`, `Conversation`, `TranscriptEntry`,
+The public components are `SupercodeMessenger`, `AgentActivityLauncher`, `Conversation`, `TranscriptEntry`,
 `ActivityGroup`, `RequestCard`, `SessionList`, `SessionRow`, `Composer`, `ContinuationBar`,
-`LoadingStatus`, `TaskPlan`, `SessionDetails`, `HarnessLogo`, `HarnessAdvisory`, and
+`ContextCandidate`, `ContextCandidates`, `LoadingStatus`, `TaskPlan`, `SessionDetails`, `HarnessLogo`, `HarnessAdvisory`, and
 `HarnessSettingsPanel`. 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/icon`, `preact/conversation`, `preact/sessions`,
@@ -75,6 +75,82 @@ the logo does not pull in Markdown, the messenger, or session-list code.
 `harnessLogoDataUrl(id)` gives non-Preact launchers the same self-contained canonical SVG; it
 returns `null` for an unknown harness rather than inventing a fallback identity.
 
+### React and Preact use the same component sources
+
+React applications import the native React build instead of isolating a Preact root or aliasing
+their application runtime:
+
+```tsx
+import { SupercodeMessenger } from '@volter-ai-dev/supercode-ui/react/messenger';
+import type { MessengerComponents } from '@volter-ai-dev/supercode-ui/react';
+import '@volter-ai-dev/supercode-ui/styles.css';
+
+const components: MessengerComponents = { SessionRow: ProductSessionRow };
+return <SupercodeMessenger state={state} adapter={adapter} components={components} />;
+```
+
+The `react`, `react/logo`, `react/icon`, `react/conversation`, `react/sessions`,
+`react/composer`, `react/settings`, and `react/messenger` exports are generated from the exact same
+JSX sources as their `preact/*` counterparts. Consumers install only the renderer they use; both
+are optional peers, and a React host never loads Preact through the React entry points.
+
+### Compact host launcher
+
+Overlay extensions and host applications can use the canonical activity projection without
+recreating Supercode's attention rules:
+
+```tsx
+import { AgentActivityLauncher } from '@volter-ai-dev/supercode-ui/react/activity';
+
+<AgentActivityLauncher state={snapshot} showSummary onOpen={() => openMessenger()} />
+```
+
+`projectAgentActivity()` is also available from the renderer-free `core` entry. It selects the
+highest-priority session (`needs-input` → failure → working → unread), reports one aggregate unread
+count, and exposes the selected opaque session key. The default launcher is themeable and allows
+its badge to overflow without being clipped.
+
+### Host navigation and context
+
+Hosts do not need to fork the messenger to connect their own object model:
+
+```tsx
+<SupercodeMessenger
+  state={state}
+  adapter={{
+    onIntent,
+    confirmIntent: (intent) => showTakeoverConfirmation(intent),
+  }}
+  navigation={{
+    id: selectedObject.revision,
+    view: 'new',
+    harness: 'claude-code',
+    draft: 'Inspect this selection',
+    context: [selectedObject.asTranscriptContext()],
+  }}
+  contextCandidates={visibleObjects.map(asTranscriptContext)}
+  components={{ ContextCandidate: ObjectPreview }}
+  slots={{ beforeSessions: ProjectThreads }}
+/>
+```
+
+`navigation` is an event, not duplicated router state: change its `id` to open a conversation or
+prefill a new one, while `onViewChange` observes user navigation. Context candidates use the exact
+bounded `TranscriptAttachment` envelope sent to the harness; a custom candidate component changes
+presentation without inventing a second context protocol. `beforeSessions` and `afterSessions`
+place host-owned rows inside the same searchable scroller. `confirmIntent` runs before resume,
+join, branch, reduction, or export so a host can explain ownership and destination before action.
+
+Harness inventory also retains normalized auth, runtime, protocol, repair, and action-capability
+evidence. The new-chat view renders unavailable harnesses in a compact `HarnessReadiness` section;
+hosts can replace that component while continuing to consume the same readiness contract.
+
+When a controlled runtime truthfully advertises native steering, the composer sends a plain-text
+message into the active turn and keeps a separate secondary action for queueing a follow-up. With
+attachments—or with a harness that cannot steer—the same input remains queued for the next turn.
+The distinction is capability-gated from the harness adapter through `availableActions.steer`; the
+UI never infers steering support from a generic `send` method.
+
 ## Bind directly to the headless controller
 
 Trusted desktop, editor, and Node hosts can avoid rewriting ordinary snapshot and action glue:
@@ -117,6 +193,9 @@ before counting visible rows, retains native timestamps and typed tool/request l
 the uncapped residue count truthful. Hosts can narrow those limits with `ClientProjectionOptions`
 and can overlay a machine-wide session inventory, pagination state, attention, drafts, attachment
 errors, and owned/attached identities without reimplementing transcript or capability semantics.
+`projectSessionInventory` performs the corresponding title, latest-preview, activity, path, age,
+sorting, and row projection for raw machine-wide descriptors; the trusted host supplies only its
+opaque-key callback and retains the reversible locator map.
 
 ## Modularity contract
 
@@ -140,6 +219,9 @@ errors, and owned/attached identities without reimplementing transcript or capab
 
 `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`.
+An iframe or extension host can pass unknown payloads through `parseSupercodeUiIntent` before using
+`dispatchControllerIntent`; transport-specific operations can be intercepted with `handleIntent`
+while ordinary controller semantics continue through the shared dispatcher.
 The browser cannot supply locators, credentials, policy, environment variables, or arbitrary
 materialization paths. Session keys and target harnesses must be revalidated by the host.
 Harness configuration is similarly narrow: the UI can only submit a choice from the revisioned

package/activity.d.ts

@@ -0,0 +1,2 @@
+export type { AgentActivityLauncherProps, AgentActivityModel } from './index.js';
+export { AgentActivityLauncher } from './index.js';