@sarchauhan/chat 0.0.0-stage → 0.0.1

package/README.md

@@ -1,3 +1,131 @@
-# Temporary Holding Version
+# @sarchauhan/chat
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An embeddable React chat package with streaming messages, themes, tool views, and interactive widgets. Bring any backend through `ChatAdapter`; Next.js is only used by the example apps.
+
+## Install
+
+```sh
+npm install @sarchauhan/chat
+```
+
+React and React DOM (version 18 or later) are peer dependencies and must be installed in your application. The package also depends on the published `@sarchauhan/adapter` and `@sarchauhan/protocol` packages; npm installs these automatically.
+
+## Quick start
+
+Create a `ChatAdapter` for your backend, then mount the component and import its stylesheet once:
+
+```tsx
+import { Chat } from "@sarchauhan/chat";
+import type { ChatAdapter } from "@sarchauhan/adapter";
+import "@sarchauhan/chat/styles.css";
+
+const adapter: ChatAdapter = {
+  async *sendMessage() {
+    yield { id: "reply-1", role: "assistant", parts: [{ type: "text", text: "Hello!" }] };
+  },
+};
+
+export function App() {
+  return <Chat adapter={adapter} />;
+}
+```
+
+See the sections below for built-in widgets, adapter payloads, and artifact/subagent rendering.
+
+```tsx
+import { Chat } from "@sarchauhan/chat";
+import "@sarchauhan/chat/styles.css";
+
+<Chat adapter={adapter} />;
+```
+
+## Prebuilt components
+
+```tsx
+import { ReadFileWidget, PatchWidget, SearchWidget, QuestionWidget } from "@sarchauhan/chat/widgets";
+
+<div className="chat-root" data-theme="light">
+  <ReadFileWidget path="src/config.ts" content="export const retries = 3;" startLine={12} />
+  <PatchWidget path="src/config.ts" before="const retries = 1;\n" after="const retries = 3;\n" />
+  <SearchWidget query="retries" results={[{ path: "src/config.ts", line: 12, text: "export const retries = 3;" }]} />
+  <QuestionWidget
+    prompt="How should messages load?"
+    options={[{ label: "Stream", value: "stream", description: "Render responses as they arrive.", recommended: true }, "Wait for completion"]}
+    allowCustom
+    onSubmit={async ({ values, text }) => { await submitAnswer({ values, text }); }}
+  />
+</div>;
+```
+
+Import `styles.css` once. Standalone components inherit theme tokens from `.chat-root`. Read and patch views collapse when complete; running/error/approval views open automatically. Previews are bounded, with controls to show more. Diff colors indicate additions/deletions; everything else uses the existing neutral theme. Question supports radio/checkbox choices, descriptions, recommended choices, free text, explicit confirmation, disabled/submitted states, and retry after failed submission.
+
+## Computed tool views
+
+`Chat` includes `read-file`, `patch`, `search`, and `question` in its default widget registry. Backends can send them with `createWidgetData(name, props, { id, interactive })` from `@sarchauhan/protocol`.
+
+Known tool parts are also mapped automatically:
+
+| View | Tool names | Recognized payload |
+| --- | --- | --- |
+| Read file | `read`, `read_file`, `readFile`, `read-file` | Input `path`/`file`/`filename`/`file_path`; output string or `content`/`text`; optional `startLine`/`start_line`/`offset` |
+| Patch | `patch`, `apply_patch`, `edit`, `edit_file` | Unified/apply-patch text in `diff`/`patch`, or `before`/`after`, `old_string`/`new_string`, `oldText`/`newText` |
+| Search | `search`, `grep`, `file_search`, `web_search` | `query`/`pattern`/`search`; output array or `results`/`matches`; result path/file/url, optional line, text/snippet/content, title |
+| Question | `question`, `ask_question` | Input `prompt`/`question`, `options`, optional `description`, `multiple`, `allowCustom` |
+
+Unsupported payloads retain the generic tool view. Tool state/error are preserved, and completed question tools cannot be submitted again. A custom registry entry for the original tool name takes precedence; custom entries for canonical widget names override builtins too.
+
+Question responses through `Chat` become user messages containing selected labels and custom text. For structured responses with widget IDs, use `WidgetProvider` and its `respondToWidget` callback with `MessageContent`/`WidgetRenderer`. Standalone `QuestionWidget` returns `{ values: string[], text?: string }` directly.
+
+Public helpers: `computeToolWidget`, `computeToolState`, `computeDiff`, `computeTextDiff`, `normalizeSearchResults`, and `safeResultUrl`. Computed text diffs use one replacement hunk with three context lines; they preserve unchanged edges and final-newline markers. Supplied unified diffs retain their original hunks and file headers.
+
+## Distribution
+
+`npm run build` emits ESM, CommonJS, TypeScript declarations, source maps, and CSS assets. Both JS entry points preserve `"use client"` for React Server Component consumers. React/React DOM are peers; the package does not depend on Next.js or the AI SDK.
+
+## Created files and images
+
+Existing protocol `file` parts now render as artifact cards with image thumbnails, preview, open, and download actions. No changes to existing file event producers are needed.
+
+Use `ArtifactWidget` for one file and `ArtifactsWidget` for a list. Text previews are escaped text; HTML and SVG are never embedded as active documents. Relative/signed download URLs remain owned by the backend. Raster images, HTTP(S), and blob URLs are supported; unsafe executable URLs are rejected. Browser cross-origin download behavior depends on the backend's Content-Disposition header.
+
+For creation states and metadata, use the additive data envelope:
+
+```ts
+import { createArtifactData } from "@sarchauhan/protocol";
+writer.write(createArtifactData({
+  id: "report-1", filename: "report.md", mediaType: "text/markdown",
+  status: "creating",
+}));
+// Later: same ID, complete snapshot replaces the card in place.
+writer.write(createArtifactData({
+  id: "report-1", filename: "report.md", mediaType: "text/markdown",
+  status: "ready", url: "/files/report.md",
+  content: "# Results\n\nThe adapter is ready.", sizeBytes: 1204,
+}));
+```
+
+Tool outputs with an explicit `{ artifact }` or `{ artifacts: [...] }` envelope also compute these views for otherwise unrecognized tool names. Local filesystem paths are not assumed to be browser-downloadable URLs. The widget registry includes `artifact` and `artifacts`.
+
+## Integrated subagents
+
+A subagent appears as a compact activity card in the parent conversation. Its inspection view uses the same accessible dialog on every screen: a centered modal above 640px and a bottom sheet at or below 640px. It supports Escape/backdrop dismissal, focus containment/restoration, reduced motion, safe-area padding, a scrolling activity transcript, nested tool views, and created artifacts. Portal content inherits the host theme and custom chat tokens.
+
+```ts
+import { createSubagentData } from "@sarchauhan/protocol";
+writer.write(createSubagentData({
+  id: "session-1:research-1", parentId: "session-1:main",
+  title: "Research agent", task: "Compare the storage options",
+  state: "running", progress: 0.6,
+  messages: [{
+    id: "reply-1", role: "assistant",
+    parts: [{ type: "text", text: "Checking the adapter contract." }],
+  }],
+}));
+// Another full snapshot with the same ID updates the existing card/dialog.
+```
+
+`AgentSubagent` is independent of any harness. Map backend states into `queued`, `running`, `completed`, `failed`, or `cancelled`. IDs identify runs, not just agent names; namespace them across sessions/harnesses. `parentId` is optional correlation metadata. Progress is an optional fraction, not a fabricated estimate. Messages and artifacts are optional; include only the activity intended for users. System messages are excluded from the inspection transcript.
+
+The event remains an existing `AgentDataEvent` (`data-subagent`); no new top-level event/part union or transport is introduced. Only `data-subagent` and `data-artifact` events with IDs replace previous snapshots within a message. Other data events retain append semantics. Each snapshot is complete: omitted fields are cleared rather than implicitly merged. Producers own event ordering and persistence; use one parent message per run or replace the prior parent message snapshot when continuing across turns. A harness that does not provide activity still produces a useful status/task card.
+
+Use `SubagentWidget` directly for custom layouts, or let `Chat`/`MessageContent` render `data-subagent` through the builtin registry. Multiple run IDs render separate cards. Inspection nesting is bounded to three levels while keeping deeper status cards visible.

package/dist/blocks.css

@@ -0,0 +1,291 @@
+@keyframes agent-tool-spin {
+  to {
+    transform: rotate(360deg);
+  }
+}
+
+.agent-tool,
+.agent-data {
+  margin: 0;
+  color: inherit;
+}
+
+.agent-tool > summary,
+.agent-data > summary {
+  display: flex;
+  align-items: center;
+  gap: var(--chat-space-2);
+  padding: var(--chat-space-1_5) 0;
+  cursor: pointer;
+  list-style: none;
+  font-size: var(--chat-fs-14);
+  line-height: var(--chat-leading-snug);
+  font-weight: var(--chat-weight-regular);
+  letter-spacing: var(--chat-tracking-normal);
+  opacity: 0.76;
+  transition:
+    color var(--chat-transition),
+    opacity var(--chat-transition);
+}
+
+.agent-tool > summary:hover {
+  color: var(--chat-fg);
+  opacity: 1;
+}
+
+.agent-tool > summary::-webkit-details-marker,
+.agent-data > summary::-webkit-details-marker {
+  display: none;
+}
+
+.agent-tool-dot {
+  display: inline-flex;
+  align-items: center;
+  justify-content: center;
+  width: 1rem;
+  height: 1rem;
+  flex: 0 0 auto;
+  color: var(--chat-fg-muted);
+  /* Restrain success-check so a 10px glyph does not bob 40px */
+  --check-y-amount: 3px;
+  --check-blur-from: 2px;
+  --check-rotate-from: 24deg;
+  --check-opacity-dur: 280ms;
+  --check-rotate-dur: 280ms;
+  --check-bob-dur: 240ms;
+  --check-blur-dur: 240ms;
+  --check-path-dur: 280ms;
+  --check-path-delay: 40ms;
+}
+
+.agent-tool-dot .t-icon-swap {
+  width: 1rem;
+  height: 1rem;
+  place-items: center;
+}
+
+.agent-tool-dot .t-success-check {
+  display: inline-flex;
+  line-height: 0;
+}
+
+.agent-tool-chevron {
+  width: 0.9rem;
+  height: 0.9rem;
+  flex: 0 0 auto;
+  opacity: 0.58;
+  transition: transform var(--chat-transition);
+}
+
+.agent-tool[open] .agent-tool-chevron {
+  transform: rotate(180deg);
+}
+
+.agent-tool-pending .agent-tool-dot {
+  color: color-mix(in oklab, var(--chat-warning) 70%, currentColor);
+}
+
+.agent-tool-complete .agent-tool-dot {
+  color: var(--chat-fg-muted);
+}
+
+.agent-tool-spinner {
+  width: 0.62rem;
+  height: 0.62rem;
+  border: 1.5px solid currentColor;
+  border-top-color: transparent;
+  border-radius: 999px;
+  animation: agent-tool-spin 0.8s linear infinite;
+  opacity: 0.9;
+}
+
+.agent-event-marker {
+  width: 0.42rem;
+  height: 0.42rem;
+  flex: 0 0 auto;
+  border-radius: 999px;
+  background: currentColor;
+  opacity: 0.4;
+}
+
+.agent-event .agent-tool-body {
+  padding-top: 0.35rem;
+}
+
+.agent-data > summary::before {
+  content: "";
+  width: 0.42rem;
+  height: 0.42rem;
+  flex: 0 0 auto;
+  border-radius: 999px;
+  background: currentColor;
+  opacity: 0.3;
+  transition:
+    opacity var(--chat-transition),
+    transform var(--chat-transition);
+}
+
+.agent-data[open] > summary::before {
+  opacity: 0.62;
+  transform: scale(0.72);
+}
+
+.agent-tool-name {
+  min-width: 0;
+  overflow: hidden;
+  color: inherit;
+  font-family: var(--chat-font-sans);
+  font-size: var(--chat-text);
+  font-weight: var(--chat-weight-medium);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-tool-chip {
+  min-width: 0;
+  max-width: min(100%, 22rem);
+  overflow: hidden;
+  color: var(--chat-fg-muted);
+  font-family: var(--chat-font-mono);
+  font-size: var(--chat-text-sm);
+  line-height: var(--chat-leading-snug);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-tool-state {
+  margin-left: auto;
+  color: var(--chat-fg-muted);
+  font-size: var(--chat-text-sm);
+  font-weight: var(--chat-weight-medium);
+  white-space: nowrap;
+}
+
+.agent-tool-pending .agent-tool-state {
+  color: color-mix(in oklab, var(--chat-warning) 62%, currentColor);
+}
+
+.agent-tool-complete .agent-tool-state {
+  color: var(--chat-fg-subtle);
+}
+
+.agent-tool-error .agent-tool-dot,
+.agent-tool-error .agent-tool-state {
+  color: color-mix(in oklab, var(--chat-danger) 64%, currentColor);
+}
+
+.agent-tool-error .agent-tool-state {
+  opacity: 0.88;
+}
+
+.agent-tool-body,
+.agent-data > pre {
+  margin-left: 1.25rem;
+  padding: var(--chat-space-2) 0 0;
+}
+
+.agent-tool-section + .agent-tool-section {
+  margin-top: var(--chat-space-3_5);
+}
+
+.agent-tool-section-label {
+  margin-bottom: var(--chat-space-1);
+  color: var(--chat-fg-muted);
+  font-size: var(--chat-text-xs);
+  font-weight: var(--chat-weight-medium);
+}
+
+.agent-tool-code {
+  margin: 0;
+  overflow-x: auto;
+  padding: 0;
+  color: inherit;
+  font-family: var(--chat-font-mono);
+  font-size: var(--chat-fs-12);
+  line-height: var(--chat-leading-normal);
+  opacity: 0.72;
+  white-space: pre-wrap;
+  word-break: break-word;
+}
+
+.agent-tool-error {
+  color: color-mix(in oklab, var(--chat-danger) 72%, currentColor);
+  opacity: 0.92;
+}
+
+.agent-source,
+.agent-file,
+.agent-reference {
+  display: inline-flex;
+  flex-direction: column;
+  gap: var(--chat-space-05);
+  max-width: min(100%, 32rem);
+  padding: var(--chat-space-05) 0;
+  color: inherit;
+  text-decoration: none;
+}
+
+.agent-source:hover,
+.agent-file:hover {
+  color: var(--chat-fg);
+}
+
+.agent-source-label {
+  color: var(--chat-fg-subtle);
+  font-size: var(--chat-text-xs);
+  font-weight: var(--chat-weight-medium);
+}
+
+.agent-source-title {
+  overflow: hidden;
+  color: inherit;
+  font-size: var(--chat-text-sm);
+  font-weight: var(--chat-weight-medium);
+  line-height: var(--chat-leading-normal);
+  text-overflow: ellipsis;
+  white-space: nowrap;
+}
+
+.agent-source-meta {
+  color: inherit;
+  font-size: var(--chat-caption-size);
+  opacity: 0.46;
+}
+
+.agent-file-image {
+  display: block;
+  overflow: hidden;
+  padding: 0;
+  background: transparent;
+}
+
+.agent-file-image img {
+  display: block;
+  width: 100%;
+  height: auto;
+  opacity: 0.92;
+}
+
+.agent-file-image figcaption {
+  padding: var(--chat-space-2) 0 0;
+  color: inherit;
+  font-size: var(--chat-caption-size);
+  opacity: 0.46;
+}
+
+.agent-reference {
+  display: flex;
+  max-width: 100%;
+  padding: var(--chat-space-05) 0;
+}
+
+.agent-reference + .agent-reference {
+  margin-top: var(--chat-space-2);
+}
+
+.agent-reference-body {
+  color: inherit;
+  font-size: var(--chat-fs-14);
+  line-height: var(--chat-leading-normal);
+  opacity: 0.72;
+}