@guuey/chat 0.4.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Loqu, Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,137 @@
+# @guuey/chat
+
+The default end-user transcript UI for [guuey](https://guuey.com) agents —
+the presentation layer that makes a long, tool-heavy agent turn _readable_:
+tool calls collapse into calm one-liners, generative-UI views mount inline,
+cold starts and failures are designed states instead of blank screens, and
+every unknown block renders as a labeled row (never blank, never raw JSON).
+
+```bash
+npm install @guuey/chat
+```
+
+## The React kit (`@guuey/chat/react`)
+
+The fastest path on the web — the component kit over the live assembler,
+with the default stylesheet:
+
+```tsx
+import { useAgentInvoke, createWebAdapters } from "@guuey/agent-client/react";
+import { calmPolicy } from "@guuey/chat";
+import { Transcript, useTranscript, useTranscriptInputs } from "@guuey/chat/react";
+import "@guuey/chat/styles.css";
+
+function Chat({ endpointUrl }: { endpointUrl: string }) {
+  const invoke = useAgentInvoke({ endpointUrl, appId: "my-app", adapters: createWebAdapters() });
+  const { inputs } = useTranscriptInputs(invoke);
+  const { plan, toggle, onViewPhase, resolvedMounts } = useTranscript({
+    inputs,
+    policy: calmPolicy(),
+  });
+  return (
+    <Transcript
+      plan={plan}
+      onToggle={toggle}
+      onViewPhase={onViewPhase}
+      resolvedMounts={resolvedMounts}
+    />
+  );
+}
+```
+
+What the kit owns (so you don't): stick-to-bottom scroll with a
+jump-to-latest release, windowed rendering for long transcripts,
+`aria-live`/keyboard/focus accessibility, sanitized markdown (typed AST —
+raw HTML is unrepresentable, links are scheme-allowlisted), generative-UI
+views mounting through `@guuey/mcp-apps-host`'s sandboxed host, and theming
+from the `GuueyChatTheme` token schema (`--guuey-chat-*` custom properties;
+`GUUEY_CHAT_THEME` ships beside the neutral default).
+
+Override one row without forfeiting the rest:
+
+```tsx
+<Transcript plan={plan} components={{ tool: MyToolChip }} … />
+```
+
+Server-side (no hook, no DOM): assemble inputs from a persisted thread read
+with `transcriptInputsFromHistory` and plan/render anywhere Node runs.
+
+## The headless view-model (the root subpath)
+
+The **headless** half — a pure function from agent state to an ordered
+display plan. The root subpath stays React-free forever (the
+batteries-included `<GuueyChat>` surface arrives in the next wave).
+
+```ts
+import { planTranscript, calmPolicy } from "@guuey/chat";
+
+const plan = planTranscript(
+  {
+    result: reduceResult, // the @silverprotocol/core Reducer's fold (or null)
+    assistantText, // the in-flight turn's cumulative text
+    status, // ready | connecting | thinking | using-tool | responding
+    statusElapsedMs, // you supply elapsed time — the function has no clock
+    activeTool,
+    error: null,
+    prompts: [],
+    messages, // the settled conversation, both roles
+  },
+  calmPolicy()
+);
+
+for (const item of plan.items) {
+  // item.kind: "user" | "text" | "tool" | "tool-group" | "view" | "media"
+  //          | "code" | "citations" | "prompt" | "error" | "reasoning"
+  //          | "data-result" | "history-boundary" | "compaction" | "unknown"
+}
+plan.status; // the derived status line ("Starting your agent…") or null
+```
+
+Determinism contract: same inputs + policy + overrides ⇒ a deeply equal
+plan, with **stable item keys** across streaming updates (a tool's key
+survives from `running` to `done`), so renderer state and DOM identity hold.
+
+## Presets
+
+`calmPolicy()` is the end-user default: tool runs group into "Ran N tools ▸",
+reasoning collapses to a line, results are scroll-capped. `debugPolicy()` is
+the builder surface: every tool its own row, args and results expanded, wire
+codes verbatim, raw payloads on unknown content.
+
+Both are complete policy bundles — override any knob or any user-facing
+string (`ChatStrings`, the i18n seam) without forfeiting the rest:
+
+```ts
+calmPolicy({ toolGroup: { threshold: 3 }, strings: { thinking: "Pondering…" } });
+```
+
+## Theme
+
+`GuueyChatTheme` is a serializable token schema (zod) — the same object a
+builder configures on platform.guuey.com. Parsing is lenient and resolution
+falls back **per token** to the default theme, so a partial or old-schema
+theme can never produce an unreadable surface:
+
+```ts
+import { resolveTheme, GUUEY_CHAT_THEME } from "@guuey/chat";
+const theme = resolveTheme(appConfiguredTheme); // never throws
+```
+
+Two constants ship: the brand-neutral default and `GUUEY_CHAT_THEME` (the
+guuey identity — portal's default look).
+
+## The fixture corpus
+
+`src/corpus/` holds the recorded-transcript corpus that DEFINES "comfortably
+readable" — forty-tool turns, mid-stream failures, cold starts, dead view
+locators, unknown-block storms. The standing rule: a new weird transcript
+found in production becomes a fixture before its fix lands. The corpus only
+grows.
+
+## Part of the guuey SDK cohort
+
+Consumes [`@guuey/agent-client`](https://www.npmjs.com/package/@guuey/agent-client)
+(the invoke stream + fold) and
+[`@guuey/mcp-apps-host`](https://www.npmjs.com/package/@guuey/mcp-apps-host)
+(the MCP-Apps host role that mounts generative views). Issues:
+[withguuey/guuey-sdks](https://github.com/withguuey/guuey-sdks/issues).

package/dist/history-inputs.d.ts

@@ -0,0 +1,24 @@
+/**
+ * The HISTORY input assembler (spec §7 "Input assembly") — persisted thread
+ * read → `TranscriptInputs`, no hook, no DOM, no React: the seam that makes
+ * server-side transcript rendering real. Give it what the read plane
+ * returned (an agent-client `HistoryLoadResult`, or `null` while the read is
+ * in flight) and plan the result with `planTranscript` anywhere Node runs.
+ *
+ * The LIVE twin (`useTranscriptInputs`, `@guuey/chat/react`) assembles the
+ * same shape from `useAgentInvoke`'s state; the two produce byte-identical
+ * inputs for the same settled conversation — that identity is what lets a
+ * server-rendered transcript hydrate under the live one without a repaint.
+ */
+import type { HistoryLoadResult } from "@guuey/agent-client";
+import type { TranscriptInputs } from "./types.js";
+/**
+ * Assemble transcript inputs from a history read.
+ *
+ *  - `null` (read still in flight) → the R13 `loading` skeleton state;
+ *  - `{ gone: true }` → the R13 `thread-gone` labeled empty state;
+ *  - a transcript → the settled conversation, with any persisted cards
+ *    riding the R13 → R6 remount path.
+ */
+export declare function transcriptInputsFromHistory(load: HistoryLoadResult | null): TranscriptInputs;
+//# sourceMappingURL=history-inputs.d.ts.map

package/dist/history-inputs.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"history-inputs.d.ts","sourceRoot":"","sources":["../src/history-inputs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAC7D,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,YAAY,CAAC;AAgBnD;;;;;;;GAOG;AACH,wBAAgB,2BAA2B,CAAC,IAAI,EAAE,iBAAiB,GAAG,IAAI,GAAG,gBAAgB,CAU5F"}

package/dist/history-inputs.js

@@ -0,0 +1,34 @@
+/** The settled-idle baseline every assembled input starts from. */
+function idleInputs() {
+    return {
+        result: null,
+        assistantText: "",
+        status: "ready",
+        statusElapsedMs: 0,
+        activeTool: null,
+        error: null,
+        prompts: [],
+        messages: [],
+    };
+}
+/**
+ * Assemble transcript inputs from a history read.
+ *
+ *  - `null` (read still in flight) → the R13 `loading` skeleton state;
+ *  - `{ gone: true }` → the R13 `thread-gone` labeled empty state;
+ *  - a transcript → the settled conversation, with any persisted cards
+ *    riding the R13 → R6 remount path.
+ */
+export function transcriptInputsFromHistory(load) {
+    const base = idleInputs();
+    if (load === null)
+        return { ...base, historyState: "loading" };
+    if ("gone" in load)
+        return { ...base, historyState: "gone" };
+    return {
+        ...base,
+        historyState: "loaded",
+        messages: load.messages,
+        ...(load.cards && load.cards.length > 0 ? { historyCards: load.cards } : {}),
+    };
+}

package/dist/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * `@guuey/chat` — the default end-user transcript UI for guuey agents.
+ *
+ * Wave 3a (guuey#135): the HEADLESS half — `planTranscript` (the pure
+ * view-model over the AgJSON fold + the invoke status surface), the
+ * `calm`/`debug` policy presets, the `GuueyChatTheme` platform-data token
+ * schema, and the `ChatStrings` i18n seam. Zero DOM, zero React.
+ *
+ * Wave 3b adds `./react` (the component kit + `<GuueyChat>` arrives in 3c);
+ * this root subpath stays React-free forever — server-side transcript
+ * rendering, tests, and RN bundlers consume the view-model directly.
+ */
+export { planTranscript, } from "./plan.js";
+export { calmPolicy, debugPolicy, type TranscriptPolicy, } from "./policy.js";
+export { defaultChatStrings, humanizeToolName, type ChatStrings, } from "./strings.js";
+export { transcriptInputsFromHistory } from "./history-inputs.js";
+export { DEFAULT_CHAT_THEME, GUUEY_CHAT_THEME, GuueyChatPalette, GuueyChatTheme, resolveTheme, } from "./theme.js";
+export type { CitationsItem, CodeItem, CompactionItem, DataResultItem, DisplayItem, ErrorItem, HistoryBoundaryItem, ItemKey, MediaItem, PromptItem, PromptItemInput, ReasoningItem, StatusLineItem, TextItem, ToolGroupItem, ToolItem, TranscriptInputs, TranscriptMessage, TranscriptOverrides, TranscriptPlan, UnknownItem, UserMessageItem, ViewMountItem, } from "./types.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AACH,OAAO,EACL,cAAc,GACf,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,UAAU,EACV,WAAW,EACX,KAAK,gBAAgB,GACtB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,KAAK,WAAW,GACjB,MAAM,cAAc,CAAC;AACtB,OAAO,EAAE,2BAA2B,EAAE,MAAM,qBAAqB,CAAC;AAClE,OAAO,EACL,kBAAkB,EAClB,gBAAgB,EAChB,gBAAgB,EAChB,cAAc,EACd,YAAY,GACb,MAAM,YAAY,CAAC;AACpB,YAAY,EACV,aAAa,EACb,QAAQ,EACR,cAAc,EACd,cAAc,EACd,WAAW,EACX,SAAS,EACT,mBAAmB,EACnB,OAAO,EACP,SAAS,EACT,UAAU,EACV,eAAe,EACf,aAAa,EACb,cAAc,EACd,QAAQ,EACR,aAAa,EACb,QAAQ,EACR,gBAAgB,EAChB,iBAAiB,EACjB,mBAAmB,EACnB,cAAc,EACd,WAAW,EACX,eAAe,EACf,aAAa,GACd,MAAM,YAAY,CAAC"}

package/dist/index.js

@@ -0,0 +1,17 @@
+/**
+ * `@guuey/chat` — the default end-user transcript UI for guuey agents.
+ *
+ * Wave 3a (guuey#135): the HEADLESS half — `planTranscript` (the pure
+ * view-model over the AgJSON fold + the invoke status surface), the
+ * `calm`/`debug` policy presets, the `GuueyChatTheme` platform-data token
+ * schema, and the `ChatStrings` i18n seam. Zero DOM, zero React.
+ *
+ * Wave 3b adds `./react` (the component kit + `<GuueyChat>` arrives in 3c);
+ * this root subpath stays React-free forever — server-side transcript
+ * rendering, tests, and RN bundlers consume the view-model directly.
+ */
+export { planTranscript, } from "./plan.js";
+export { calmPolicy, debugPolicy, } from "./policy.js";
+export { defaultChatStrings, humanizeToolName, } from "./strings.js";
+export { transcriptInputsFromHistory } from "./history-inputs.js";
+export { DEFAULT_CHAT_THEME, GUUEY_CHAT_THEME, GuueyChatPalette, GuueyChatTheme, resolveTheme, } from "./theme.js";

package/dist/plan.d.ts

@@ -0,0 +1,5 @@
+import type { TranscriptPolicy } from "./policy.js";
+import type { TranscriptInputs, TranscriptOverrides, TranscriptPlan } from "./types.js";
+/** The one pure function (spec §7). */
+export declare function planTranscript(inputs: TranscriptInputs, policy: TranscriptPolicy, overrides?: TranscriptOverrides): TranscriptPlan;
+//# sourceMappingURL=plan.d.ts.map

package/dist/plan.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plan.d.ts","sourceRoot":"","sources":["../src/plan.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AACpD,OAAO,KAAK,EAQV,gBAAgB,EAChB,mBAAmB,EACnB,cAAc,EAGf,MAAM,YAAY,CAAC;AAoiBpB,uCAAuC;AACvC,wBAAgB,cAAc,CAC5B,MAAM,EAAE,gBAAgB,EACxB,MAAM,EAAE,gBAAgB,EACxB,SAAS,GAAE,mBAAwB,GAClC,cAAc,CA4IhB"}