@opengeni/react 0.13.0 → 0.20.0

package/README.md

@@ -4,16 +4,17 @@ React hooks and styled components for OpenGeni, built on
 [`@opengeni/sdk`](../sdk): live session streaming, a chat composer, a message
 timeline that renders streaming deltas / tool calls / spawned-worker status,
 session status badges, and fleet tiles for workspace overviews. Two opt-in
-surfaces layer on top: a **sandbox-surfacing** workbench (files, terminal, diff,
+surfaces layer on top: a **sandbox workspace** workbench (files, terminal, diff,
 and an optional desktop stream) and, at the
 [`@opengeni/react/machines`](#connected-machines-opengenireactmachines) subpath,
 the **Connected Machines** dashboard + enrollment flow.
 
 The default root import (`@opengeni/react`) is the clean sandbox-agnostic
-surface — the chat/timeline hooks and components plus the sandbox-surfacing
-suite. Connected-Machine UI lives under the `@opengeni/react/machines` subpath so
-consumers that never surface machines don't pull it in. (The root barrel still
-re-exports the machines island for back-compat, deprecated per #144.)
+surface — the chat/timeline hooks and components plus the sandbox workspace
+suite. Advanced chat-composer composition lives under
+`@opengeni/react/composer`; Connected-Machine UI lives under
+`@opengeni/react/machines`. (The root barrel still re-exports the machines
+island for back-compat, deprecated per #144.)
 
 Design-system-first: every visual decision routes through CSS-variable tokens
 (`styles/tokens.css`) — color, typography, radius, shadow, motion. Dark mode is
@@ -24,6 +25,27 @@ animation. Override the tokens to rebrand everything.
 
 ## Install & styles
 
+Hosts that render their own UI should import the session-only surface:
+
+```tsx
+import {
+  useComposer,
+  useSessionControl,
+  useSessionEvents,
+  useTurnQueue,
+} from "@opengeni/react/session";
+```
+
+That subpath contains session hooks, approval helpers, and the pure timeline
+projection only. It does not load the styled composer, timeline, workbench,
+CSS, or their optional editor/terminal peers. Pass `{ client, workspaceId }` to
+each hook when the host intentionally does not mount `OpenGeniProvider`. The
+exported `SessionClientLike` is deliberately narrow: a tenant-safe proxy needs
+only session events, composer draft/send, queue, pause/resume, and approval
+operations. Workspace-level Resume is an optional authority.
+
+The styled root surface uses Tailwind v4 and the package CSS entries:
+
 The package ships TypeScript source plus two CSS entries. In your Tailwind v4
 entry CSS:
 
@@ -45,16 +67,19 @@ import {
   ChatComposer,
   MessageTimeline,
   OpenGeniProvider,
+  QueueSurface,
   SessionStatus,
   useComposer,
   useSessionEvents,
+  useTurnQueue,
 } from "@opengeni/react";
 
 const client = new OpenGeniClient({ baseUrl: "/api/opengeni" }); // proxy through your API
 
 function OpsChannel({ sessionId }: { sessionId: string }) {
   const { timeline, sessionStatus, hasOlder, loadingOlder, loadOlder } = useSessionEvents(sessionId);
-  const composer = useComposer(sessionId);
+  const queue = useTurnQueue(sessionId);
+  const composer = useComposer(sessionId, { effectiveControl: queue.effectiveControl });
   return (
     <div className="flex h-full flex-col">
       {sessionStatus ? <SessionStatus status={sessionStatus} /> : null}
@@ -66,7 +91,8 @@ function OpsChannel({ sessionId }: { sessionId: string }) {
         onLoadOlder={() => void loadOlder()}
         className="min-h-0 flex-1"
       />
-      <ChatComposer composer={composer} status={sessionStatus} />
+      <QueueSurface queue={queue} composer={composer} />
+      <ChatComposer composer={composer} effectiveControl={queue.effectiveControl} />
     </div>
   );
 }
@@ -80,6 +106,82 @@ export function App() {
 }
 ```
 
+## Composer customization (`@opengeni/react/composer`)
+
+Use `ChatComposer` for the standard layout and its `controlsStart`, `header`,
+and `messages` props for small additions. For a different layout, import the
+headless controller and compound primitives as a namespace. The controller is
+the one behavior path for keyboard routing, guarded queue/steer submission,
+attachments, commands, pause/resume, focus, confirmations, and feedback.
+
+```tsx
+import * as Composer from "@opengeni/react/composer";
+
+function InsertTranscript() {
+  const composer = Composer.useChatComposer();
+  return (
+    <button
+      type="button"
+      onClick={() => {
+        const separator = composer.value.trim().length > 0 ? " " : "";
+        composer.setValue(`${composer.value}${separator}Transcribed text`);
+        composer.focusInput();
+      }}
+    >
+      Insert transcript
+    </button>
+  );
+}
+
+function CustomComposer({ sessionComposer, attachments, effectiveControl }) {
+  const controller = Composer.useChatComposerController({
+    delivery: sessionComposer,
+    draft: sessionComposer,
+    control: sessionComposer,
+    attachments,
+    effectiveControl,
+  });
+
+  return (
+    <Composer.Root controller={controller}>
+      <Composer.Frame>
+        <Composer.CommandPalette />
+        <Composer.Surface>
+          <Composer.PausedState />
+          <Composer.RestoredResources />
+          <Composer.Attachments />
+          <Composer.Input />
+          {controller.confirmState ? (
+            <Composer.Confirmation />
+          ) : (
+            <Composer.Footer>
+              <Composer.Controls>
+                <Composer.AttachButton />
+                <InsertTranscript />
+              </Composer.Controls>
+              <Composer.Actions>
+                <Composer.PauseButton />
+                <Composer.SendButton />
+              </Composer.Actions>
+            </Composer.Footer>
+          )}
+        </Composer.Surface>
+      </Composer.Frame>
+      <Composer.Help />
+      <Composer.Status />
+    </Composer.Root>
+  );
+}
+```
+
+For a pre-session or otherwise limited composer, pass only `delivery`; `draft`
+and `control` are optional capabilities rather than no-op requirements. Custom
+controls should call `controller.submit("queue" | "steer")` (or read it through
+`useChatComposer`) instead of calling a delivery adapter directly, so upload,
+disabled, in-flight, and slash-command guards stay intact. Accessory-local UI
+state remains application-owned; durable draft and session state remain in
+`useComposer`.
+
 ## Hooks
 
 - `useSessionEvents(sessionId)` — loads a compact, bounded tail window by
@@ -90,27 +192,30 @@ export function App() {
   older-history controls (`hasOlder`, `loadingOlder`, `loadOlder`). Pass
   `replay: "full"` to opt back into full replay; a nonzero `after` keeps the
   previous resume semantics.
-- `useComposer(sessionId, { sendExtras, defaultMode })` — draft/send/interrupt
-  state plus the compose-time **queue-vs-steer** choice (`mode`/`setMode`,
-  default `"queue"`): queue stacks the message behind the running turn, steer
-  interrupts and injects it now. Drafts survive failed sends; each draft
-  reuses one `clientEventId` across retries so the server dedupes.
+- `useComposer(sessionId, { sendExtras, effectiveControl })` — revisioned private
+  draft, Send, Steer, and workstream Pause/Resume state. `send()` appends in
+  visible queue order; `steer()` supersedes the current direction. Drafts
+  autosave with optimistic concurrency, survive failed sends, and reuse one
+  `clientEventId` across retries so the server dedupes.
   `sendExtras` (object or function evaluated at send time) merges
   resources/tools/model/reasoningEffort into every message. All human input is
   plain chat text by design; approvals flow as control events
   (`useSessionControl`), not bespoke widgets.
-- `useTurnQueue(sessionId, { events })` — the live turn queue: `queue` (queued
-  turns in execution order), `activeTurn`, and optimistic `editTurn` /
-  `reorderTurns` / `removeTurn` that reconcile with the server (failed
-  mutations roll back via refetch). Live-updates on `turn.*` events — pass the
+- `useTurnQueue(sessionId, { events })` — the one server-authoritative human
+  prompt queue with `moveTurn`, crash-safe `editTurn`, identity-preserving
+  `steerTurn`, and `removeTurn`. Mutations carry observed revisions and conflicts
+  refetch server truth. Live-updates on `turn.*` and `session.queue.*` events — pass the
   `events` log from `useSessionEvents` to reuse its stream, or let it tail the
-  session itself.
+  session itself. Providerless self-streams reconcile authoritative queue/draft
+  state after the SSE connection opens, closing the initial-read handoff race.
 - `useGoal(sessionId, { events })` — goal state + autonomy counters
   (`autoContinuations`, `noProgressStreak`) with `pause(rationale?)` /
   `resume()`. Goal-less sessions yield `goal: null`. Live-updates on `goal.*`
   events.
-- `useSessionControl(sessionId)` — `interrupt(reason?)` and
-  `approve`/`reject(approvalId, message?)` for `requires_action` approvals.
+- `useSessionControl(sessionId)` — durable `pause(reason?)` / `resume(reason?)`
+  workstream controls and `approve`/`reject(approvalId, message?)` for
+  `requires_action` approvals. Pause is recursive control state, not lifecycle
+  status or queue work; Resume creates no message.
 - `useSession(sessionId)` — fetch one session (optional polling) with
   `updateTitle(title)` (rename) and live title-patching on `session.title_set`.
 - `useFileAttachments()` — the composer's attach flow: stages files, drives the
@@ -159,11 +264,12 @@ intentional changes should regenerate those snapshots and review the diff.
 
 ## Components
 
-- `ChatComposer` — auto-growing textarea, Enter-to-send (IME-safe), stop
-  control while a turn runs, inline error recovery. Slots for app chrome:
+- `ChatComposer` — auto-growing textarea, Enter-to-send (IME-safe), pause/resume
+  controls, inline error recovery. Slots for app chrome:
   `controlsStart` (footer controls like model pickers / attach buttons),
   `header` (e.g. attachment chips above the field), and `onPaste`
-  (paste-image-to-attach).
+  (paste-image-to-attach). Its advanced controller and compound primitives are
+  exported from `@opengeni/react/composer`.
 - `MessageTimeline` — the session timeline with stick-to-bottom scrolling, a
   "jump to latest" affordance, streaming caret, collapsible activity clusters,
   and worker cards (wire `onOpenSession` to drill into a worker). Pass
@@ -247,7 +353,7 @@ end-to-end embedder story (create-on-machine, discover, swap, enroll, revoke).
 
 ## Optional peer dependencies
 
-The chat/timeline surface has none. The sandbox-surfacing and diff surfaces pull
+The chat/timeline surface has none. The sandbox workspace and diff surfaces pull
 their heavy libraries from **optional** `peerDependencies`, so you install only
 what the surfaces you mount need: