reifyui 0.3.0 → 0.4.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/README.md CHANGED
@@ -14,7 +14,7 @@ _Reify_ — to make the abstract concrete. ReifyUI reifies an agent's intent int
14
14
  npm install reifyui
15
15
  ```
16
16
 
17
- > **Status: v0.2, early.** ReifyUI is an open foundation, not a finished platform. This first
17
+ > **Status: v0.4, early.** ReifyUI is an open foundation, not a finished platform. This first
18
18
  > release line ships the rendering-and-interaction core described under **Today** below. The larger
19
19
  > vision — a component registry, agent-driven composition, and protocol interop — is on the
20
20
  > **Roadmap**, stated plainly so you can tell what runs now from what's coming. We don't ship
@@ -55,7 +55,7 @@ A production-grade surface for rendering and interacting with a live agent turn:
55
55
  | **Rich blocks** | `CodeBlock` (highlight.js + mermaid + charts), `useResizablePane`, `PaneResizer` |
56
56
  | **Task list** | `TaskList`, `taskStatusGroup` — the master list beside a conversation: live status, filtering, cursor pagination. Transport-agnostic: you supply `fetchPage(cursor)` |
57
57
  | **Dialogs** | `DialogHost`, `useDialog` — awaited in-app `alert` / `confirm` / `prompt`, so a destructive tool call or a "name this" step never falls back to a browser popup |
58
- | **Slides** | a slide renderer/editor + `reifyui/styles/slides.css` |
58
+ | **Slides** (`reifyui/slides`) | `SlideView`, `SlideStage`, `EditorCanvas`, `Presentation`, `ElementView`, `themeVars` — render a JSON deck, edit it by direct manipulation, present it |
59
59
  | **Spreadsheet** | `SheetGrid`, `sheetToDelimited`, `sheetToAoA` — an AI-editable grid |
60
60
  | **Icons / tool meta** | `Ic*` icon set, `toolMeta`, `humanize`, `summarizeSteps` |
61
61
  | **Auth (optional)** | `configureAuth`, `login`, `AuthForm`, `GoogleButton` — a thin JWT client for products with a `/v1/auth`-style backend; wired to nothing by default |
@@ -88,29 +88,43 @@ Render a live agent turn from a Server-Sent-Events response:
88
88
 
89
89
  ```jsx
90
90
  import { useState } from 'react';
91
- import { ChatMessages, Composer, createConversationStore, pumpResponsesStream } from 'reifyui';
91
+ import { ChatMessages, Composer, pumpResponsesStream } from 'reifyui';
92
92
  import 'reifyui/styles/chat.css';
93
93
  import 'reifyui/styles/themes/light.css'; // or themes/dark.css
94
94
 
95
- const store = createConversationStore();
96
-
95
+ // You own the conversation array. ReifyUI renders it — text, reasoning, and a collapsible
96
+ // tool-step timeline — and never decides how you fetch or where your state lives.
97
97
  export function Chat({ endpoint }) {
98
- const [, force] = useState(0);
99
- store.subscribe(() => force((n) => n + 1));
98
+ const [messages, setMessages] = useState([]);
99
+ const [busy, setBusy] = useState(false);
100
+
101
+ const amendLast = (patch) =>
102
+ setMessages((m) => m.map((x, i) => (i === m.length - 1 ? { ...x, ...patch(x) } : x)));
100
103
 
101
104
  async function send(text) {
105
+ setMessages((m) => [...m, { role: 'user', text }, { role: 'assistant', text: '', steps: [] }]);
106
+ setBusy(true);
102
107
  const res = await fetch(endpoint, {
103
108
  method: 'POST',
104
109
  headers: { 'content-type': 'application/json' },
105
110
  body: JSON.stringify({ input: text, stream: true }),
106
111
  });
107
- await pumpResponsesStream({ response: res, store });
112
+ await pumpResponsesStream(res.body, {
113
+ onTextDelta: (d) => amendLast((x) => ({ text: x.text + d })),
114
+ onReasoningDelta: (d) => amendLast((x) => ({ reasoning: (x.reasoning || '') + d })),
115
+ onToolCall: (name, args, callId) =>
116
+ amendLast((x) => ({ steps: [...x.steps, { name, args, callId }] })),
117
+ onToolResult: (callId, output) =>
118
+ amendLast((x) => ({ steps: x.steps.map((s) => (s.callId === callId ? { ...s, output } : s)) })),
119
+ onDone: () => setBusy(false),
120
+ onError: () => setBusy(false),
121
+ });
108
122
  }
109
123
 
110
124
  return (
111
125
  <>
112
- <ChatMessages store={store} />
113
- <Composer onSend={send} placeholder="Ask anything…" />
126
+ <ChatMessages messages={messages} workingLabel={busy ? 'Working…' : undefined} />
127
+ <Composer onSend={send} disabled={busy} />
114
128
  </>
115
129
  );
116
130
  }
@@ -137,6 +151,41 @@ import 'reifyui/styles/dialog.css'; // alert / confirm / prompt dialogs
137
151
  Themes are CSS-variable files — load one, or switch at runtime by toggling which you apply. Override
138
152
  the variables to match your design system.
139
153
 
154
+ ## Slides
155
+
156
+ A deck is JSON — a fixed 1920×1080 stage, and elements with absolute frames and stable ids. That
157
+ makes it something an agent can author and patch precisely, and something you can render, edit and
158
+ present from the same components.
159
+
160
+ Imported from **`reifyui/slides`**, not the root: chart, diagram and code elements lazy-load
161
+ echarts, mermaid and highlight.js, and a root re-export would put all three in the dependency graph
162
+ of every app that imports a `Button`.
163
+
164
+ ```jsx
165
+ import { SlideView, EditorCanvas, Presentation } from 'reifyui/slides';
166
+ import 'reifyui/styles/slides.css';
167
+
168
+ // Read-only: thumbnails, previews, print pages.
169
+ <SlideView slide={deck.slides[0]} theme={deck.theme} bare />
170
+
171
+ // Editable: drag to move, corner handles to resize, double-click to edit text,
172
+ // Delete to remove, arrows to nudge. The canvas never mutates the deck — you do.
173
+ <EditorCanvas
174
+ slide={deck.slides[i]}
175
+ theme={deck.theme}
176
+ selectedId={selected}
177
+ onSelect={setSelected}
178
+ onPatchElement={(id, patch) => setDeck((d) => patchElement(d, i, id, patch))}
179
+ onDeleteElement={(id) => setDeck((d) => removeElement(d, i, id))}
180
+ readOnly={agentIsWriting}
181
+ />
182
+ ```
183
+
184
+ Because every commit leaves as a typed patch, undo, autosave and collaboration stay where they
185
+ belong — with the host. Pass `peers` to draw other people's selections and live drags, and
186
+ `onDragState` to broadcast your own. `resolveSrc` rewrites element `src` values on the way out, so
187
+ workspace-relative image paths can point at your own file API.
188
+
140
189
  ## Optional: auth client
141
190
 
142
191
  ReifyUI includes a small, framework-agnostic auth client for products whose backend exposes a JSON
package/dist/index.d.ts CHANGED
@@ -8,38 +8,91 @@ import type { ComponentType, ReactNode } from 'react';
8
8
 
9
9
  // ── streaming ──────────────────────────────────────────────────────────────
10
10
  export interface SSEEvent { type: string; [k: string]: unknown; }
11
+
12
+ /** Semantic callbacks over the Responses SSE shape. All optional — handle only what you render. */
13
+ export interface ResponseHandlers {
14
+ /** The response id, as soon as response.created arrives. */
15
+ onCreated?(responseId: string): void;
16
+ /** The server-side session id, for continuing this conversation on the next turn. */
17
+ onSession?(sessionId: string): void;
18
+ onReasoningDelta?(text: string): void;
19
+ onTextDelta?(text: string): void;
20
+ onToolCall?(name: string, args: string, callId: string): void;
21
+ onToolResult?(callId: string, output: string): void;
22
+ onFile?(file: { container_id: string; file_id: string; filename: string }): void;
23
+ /** Terminal event. `status` distinguishes completed / incomplete / failed (incl. cancels). */
24
+ onDone?(status: string, response: unknown): void;
25
+ onError?(message: string): void;
26
+ }
27
+
28
+ export interface ResponsesDispatcher {
29
+ responseId: string | null;
30
+ dispatch(event: SSEEvent): void;
31
+ }
32
+ /** Event-shape decoding only — pair with readSSEStream when you own the read loop. */
33
+ export function createResponsesDispatcher(handlers: ResponseHandlers): ResponsesDispatcher;
34
+
35
+ /** Frame an SSE byte stream. Takes the response BODY, and hands back each frame's raw `data:`
36
+ * payload as a STRING — parsing is the caller's (see pumpResponsesStream for the parsed form). */
11
37
  export function readSSEStream(
12
- response: Response,
13
- onEvent: (event: SSEEvent) => void,
38
+ body: ReadableStream<Uint8Array>,
39
+ onData: (data: string) => void,
14
40
  ): Promise<void>;
15
- export function createResponsesDispatcher(handlers: Record<string, (event: SSEEvent) => void>):
16
- (event: SSEEvent) => void;
17
- export function pumpResponsesStream(args: {
18
- response: Response;
19
- onEvent?: (event: SSEEvent) => void;
20
- [k: string]: unknown;
21
- }): Promise<unknown>;
41
+
42
+ /** Read + decode in one call. Resolves to the response id. */
43
+ export function pumpResponsesStream(
44
+ body: ReadableStream<Uint8Array>,
45
+ handlers: ResponseHandlers,
46
+ ): Promise<string | null>;
22
47
 
23
48
  // ── block state machine ─────────────────────────────────────────────────────
24
- export type Block = Record<string, unknown>;
25
- export function withText(blocks: Block[], text: string): Block[];
26
- export function withReasoning(blocks: Block[], text: string): Block[];
27
- export function withStep(blocks: Block[], step: Record<string, unknown>): Block[];
28
- export function withResult(blocks: Block[], result: Record<string, unknown>): Block[];
29
- export function asstText(blocks: Block[]): string;
49
+ // An assistant turn is an ORDERED list of blocks appended as events arrive, so tool activity
50
+ // interleaves with prose in real time instead of every tool being hoisted above the text.
51
+ export interface ToolStep {
52
+ name: string;
53
+ args?: string;
54
+ result?: unknown;
55
+ callId?: string;
56
+ [k: string]: unknown;
57
+ }
58
+ export type Block =
59
+ | { kind: 'text'; text: string }
60
+ | { kind: 'tools'; reasoning: string; steps: ToolStep[] };
61
+
62
+ // The transforms are generic over the caller's block type: they only ever read `kind` (and, in
63
+ // withResult, a step's `callId`/`result`), and otherwise pass values through untouched. An app
64
+ // with a stricter Block/ToolStep of its own keeps it, rather than having every result widened to
65
+ // this module's shape. Block above is the DEFAULT for apps that don't declare their own.
66
+ /** Append prose, merging into a trailing text block. */
67
+ export function withText<B = Block>(blocks: B[], delta: string): B[];
68
+ /** Append reasoning, merging into a trailing tools block. */
69
+ export function withReasoning<B = Block>(blocks: B[], delta: string): B[];
70
+ /** Append a tool step, merging into a trailing tools block. */
71
+ export function withStep<B = Block, S = ToolStep>(blocks: B[], step: S): B[];
72
+ /** Attach a result to the pending step with this call id. */
73
+ export function withResult<B = Block>(blocks: B[], callId: string, output: unknown): B[];
74
+ /** All prose of an assistant MESSAGE joined — takes the message, not its blocks. */
75
+ export function asstText(message: { blocks: readonly unknown[] }): string;
30
76
 
31
77
  // ── conversation store ──────────────────────────────────────────────────────
78
+ // A tiny keyed store with a React binding: `use(key)` subscribes, `get`/`set` read and write
79
+ // outside render. Values are whatever the caller puts in, so they stay generic per key.
32
80
  export interface ConversationStore {
33
- getState: () => unknown;
34
- setState: (next: unknown) => void;
35
- subscribe: (listener: () => void) => () => void;
36
- [k: string]: unknown;
81
+ get<T = unknown>(key: string): T;
82
+ /** Shallow-merges a partial into the key's current state (or the partial a function returns). */
83
+ set<T = unknown>(key: string, patch: Partial<T> | ((prev: T) => Partial<T>)): void;
84
+ seed(key: string, value: unknown): void;
85
+ updateLastAssistant(key: string, update: (msg: unknown) => unknown): void;
86
+ use<T = unknown>(key: string): T;
37
87
  }
38
- export function createConversationStore(initial?: unknown): ConversationStore;
88
+ /** `makeInitial(key)` supplies the starting value the first time a key is read. */
89
+ export function createConversationStore(
90
+ makeInitial?: (key: string) => unknown,
91
+ ): ConversationStore;
39
92
 
40
93
  // ── icons ───────────────────────────────────────────────────────────────────
41
94
  export const Svg: ComponentType<{ s?: number; children?: ReactNode }>;
42
- export const Chevron: ComponentType<{ open?: boolean }>;
95
+ export const Chevron: ComponentType<{ dir?: 'left' | 'right' | 'down'; size?: number }>;
43
96
  export const IcTool: ComponentType;
44
97
  export const IcPlug: ComponentType;
45
98
  export const IcSkill: ComponentType;
@@ -65,7 +118,25 @@ export function summarizeSteps(steps: unknown[]): string;
65
118
  // ── components (permissive props: see README for slot contracts) ─────────────
66
119
  export const ToolGroup: ComponentType<Record<string, unknown>>;
67
120
  export const ToolRow: ComponentType<Record<string, unknown>>;
68
- export const ChatMessages: ComponentType<Record<string, unknown>>;
121
+ /** The message list. `messages` is the conversation you own — this renders it and its tool
122
+ * timeline; every render slot is optional. */
123
+ // Generic over YOUR message type: the renderer never inspects a message beyond `role` and its
124
+ // blocks, so the slots hand back whatever shape you passed in rather than widening it.
125
+ export interface ChatMessagesProps<M = any> {
126
+ messages: M[];
127
+ renderMarkdown?: (text: string) => ReactNode;
128
+ renderMessage?(message: M, index: number): ReactNode;
129
+ renderStep?(step: ToolStep, index: number): ReactNode;
130
+ userExtras?(message: M, index: number): ReactNode;
131
+ /** Rendered on the live "working" row — a node, not a slot function. */
132
+ workingExtra?: ReactNode;
133
+ assistantFooter?(message: M, index: number): ReactNode;
134
+ statusLabels?: Record<string, string>;
135
+ workingLabel?: string;
136
+ toolLabels?: Record<string, string>;
137
+ [k: string]: unknown;
138
+ }
139
+ export const ChatMessages: <M = unknown>(props: ChatMessagesProps<M>) => ReactNode;
69
140
  export const ChatMessagesSkeleton: ComponentType<Record<string, unknown>>;
70
141
  export const UserTurn: ComponentType<Record<string, unknown>>;
71
142
  export const AssistantTurn: ComponentType<Record<string, unknown>>;