@campfire-interactive/ai-chat 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,76 @@
-# Temporary Holding Version
-
-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.
+# `@campfire-interactive/ai-chat`
+
+> **Private and unvetted until the pm exercise.** Do not adopt it in an app yet;
+> see [CLAUDE.md](./CLAUDE.md).
+
+The platform AI chat: an icon in the header opens a docked panel beside the
+page. The chat knows which page is open, offers chips that fit it, answers with
+typed blocks (prose, tables, charts, KPI tiles, links, buttons, questions,
+citations), and proposes small changes as cards the user confirms. It talks to
+the hub's `/api/v1/assistant/*` API directly with the user's token.
+
+A live playground with a scripted hub is the showcase's **AI chat** page
+(`npm run showcase`, then `#ai-chat`).
+
+## Entries
+
+| Entry | What it holds |
+|---|---|
+| `.` | The wire-contract types and `createAssistantClient` (`chatStream`, `confirmWrite`, `listActions`). No UI. |
+| `/host` | `AiChatProvider`, `AiChatSurface`, `AiChatButton`, `useAiChat`. |
+
+Peers: `react` / `react-dom` 18 or 19, `lucide-react` (>= 0.460), `recharts`
+2.15+ or 3. **No CSS import:** the stylesheet (`cfi-ac-*`, in
+`@layer components`) is injected by the bundle. Charts load lazily.
+
+## Wiring a host (pm)
+
+```tsx
+import { AiChatProvider, AiChatSurface, AiChatButton } from '@campfire-interactive/ai-chat/host';
+
+// App.tsx: above <Routes>, beside <PmHelp>.
+<AiChatProvider
+  app="pm"
+  hubUrl={aiEnabled ? runtime.aiHubBaseUrl : undefined}   // undefined = chat off
+  getToken={getAccessToken}
+  uploadFile={uploadToDms}                                 // pm's dms-client upload, as WorkAttachments does; returns { documentId }
+  pageContext={usePmPageContext()}                        // rebuilt on every navigation
+  starters={PM_STARTERS}                                   // { 'program.risks': ['Which risks are overdue?'], … }
+  navigate={(link) => (link.app === 'pm' ? navigate(link.path) : (window.location.href = getAppUrl(link.app) + link.path))}
+>
+  <Routes>…</Routes>
+</AiChatProvider>
+
+// AppShell.tsx
+<ShellHeader rightActions={<AiChatButton />} … />
+<div className="flex flex-1 overflow-hidden">
+  <SideNav … />
+  <main className="min-w-0 flex-1 overflow-auto">…</main>
+  <CampfireHelpSurfaces />
+  <AiChatSurface />
+</div>
+```
+
+`AiChatButton` and `AiChatSurface` render nothing when the provider has no
+`hubUrl`, so a host gates only the provider.
+
+## Behavior worth knowing
+
+- **Session.** The thread lives in React state; navigation and closing the panel
+  keep it. A reload ends it. "Start over" clears the thread, the dropped files
+  and the session id.
+- **History.** Each request sends the last 8 turns as text. Blocks are reduced
+  to one-line traces; a confirmed write appends
+  `Confirmed: <summary> (succeeded|failed)` to that answer.
+- **Starters** are keyed by `pageContext.page` (`'*'` is the fallback).
+  `{placeholders}` fill from the page's entities by `type`, then from `filters`,
+  then `{title}`. A fully filled chip sends; otherwise it loads into the composer.
+  They show in the empty state, and again above the composer once the page
+  differs from where the last question was asked.
+- **Files** are kept in memory under a `fileRef` and offered on every request
+  until attached. `uploadFile` runs only when the user confirms an attach card,
+  immediately before `confirmWrite({ token, documentId })`.
+- **Writes.** Cancel, or any new message, discards every pending write. Nothing
+  is stored, so nothing needs cleaning up.
+- **Panel open state and width** (360 to 900 px) are remembered per browser in
+  `localStorage` under `cfi.ai-chat.<app>.*`.

package/dist/ChartBlock-HDE237VG.js

@@ -0,0 +1,210 @@
+import {
+  formatTick,
+  formatValue
+} from "./chunk-2MWBMQMX.js";
+
+// src/blocks/ChartBlock.tsx
+import {
+  Area,
+  AreaChart,
+  Bar,
+  BarChart,
+  CartesianGrid,
+  Cell,
+  Legend,
+  Line,
+  LineChart,
+  ReferenceLine,
+  ResponsiveContainer,
+  Scatter,
+  ScatterChart,
+  Tooltip,
+  XAxis,
+  YAxis
+} from "recharts";
+import { jsx, jsxs } from "react/jsx-runtime";
+var palette = (i) => `var(--cfi-chart-${i % 8 + 1})`;
+var HEIGHT = 260;
+var LONG_LABEL = 10;
+var LABEL_MAX = 24;
+var shorten = (v) => {
+  const text = String(v ?? "");
+  return text.length > LABEL_MAX ? `${text.slice(0, LABEL_MAX - 1)}\u2026` : text;
+};
+var axisProps = {
+  tick: { fontSize: 11, fill: "var(--cfi-chart-label, #6b7280)" },
+  stroke: "var(--cfi-chart-axis, #d1d5db)"
+};
+var tooltipStyle = {
+  contentStyle: {
+    background: "var(--cfi-surface-raised, #fff)",
+    border: "1px solid var(--cfi-border, #e5e7eb)",
+    borderRadius: "var(--cfi-radius-md, 6px)",
+    fontSize: 12,
+    color: "var(--cfi-content, #111827)"
+  }
+};
+function ChartBlock({ block }) {
+  const fmt = (v) => formatValue(typeof v === "number" || typeof v === "string" ? v : null, block.valueFormat ?? "number");
+  const tick = (v) => formatTick(v, block.valueFormat);
+  const showLegend = block.series.length > 1;
+  const color = (i) => showLegend ? palette(i) : "var(--cfi-ac-action)";
+  const sideways = block.chartType === "bar" && block.data.some((row) => String(row[block.xKey] ?? "").length > LONG_LABEL);
+  const chartHeight = sideways ? Math.max(140, block.data.length * 36 + 56) : HEIGHT;
+  const allowDecimals = block.data.some((row) => block.series.some((s) => {
+    const v = row[s.key];
+    return typeof v === "number" && !Number.isInteger(v);
+  }));
+  const top = Math.max(0, ...block.data.flatMap((row) => block.series.map((s) => Number(row[s.key]) || 0)));
+  const tickCount = allowDecimals ? void 0 : Math.max(2, Math.min(5, Math.ceil(top) + 1));
+  const grid = /* @__PURE__ */ jsx(CartesianGrid, { strokeDasharray: "3 3", stroke: "var(--cfi-chart-grid, #e5e7eb)", vertical: false });
+  const crowded = block.data.length > 4;
+  const x = /* @__PURE__ */ jsx(
+    XAxis,
+    {
+      dataKey: block.xKey,
+      ...axisProps,
+      interval: 0,
+      angle: crowded ? -30 : 0,
+      textAnchor: crowded ? "end" : "middle",
+      height: crowded ? 64 : 32,
+      label: block.xLabel ? { value: block.xLabel, position: "insideBottom", offset: 0, fontSize: 11 } : void 0
+    }
+  );
+  const y = /* @__PURE__ */ jsx(
+    YAxis,
+    {
+      ...axisProps,
+      width: 56,
+      tickFormatter: tick,
+      allowDecimals,
+      tickCount,
+      label: block.yLabel ? { value: block.yLabel, angle: -90, position: "insideLeft", fontSize: 11 } : void 0
+    }
+  );
+  const tooltip = /* @__PURE__ */ jsx(Tooltip, { ...tooltipStyle, formatter: (v) => fmt(v) });
+  let chart;
+  switch (block.chartType) {
+    case "line":
+      chart = /* @__PURE__ */ jsxs(LineChart, { accessibilityLayer: false, data: block.data, margin: { top: 8, right: 12, bottom: 8, left: 0 }, children: [
+        grid,
+        x,
+        y,
+        tooltip,
+        showLegend && /* @__PURE__ */ jsx(Legend, { verticalAlign: "top", wrapperStyle: { fontSize: 12, paddingBottom: 4 } }),
+        block.series.map((s, i) => /* @__PURE__ */ jsx(Line, { type: "monotone", dataKey: s.key, name: s.label, stroke: color(i), strokeWidth: 2, dot: false, connectNulls: true }, s.key))
+      ] });
+      break;
+    case "area":
+      chart = /* @__PURE__ */ jsxs(AreaChart, { accessibilityLayer: false, data: block.data, margin: { top: 8, right: 12, bottom: 8, left: 0 }, children: [
+        grid,
+        x,
+        y,
+        tooltip,
+        showLegend && /* @__PURE__ */ jsx(Legend, { verticalAlign: "top", wrapperStyle: { fontSize: 12, paddingBottom: 4 } }),
+        block.series.map((s, i) => /* @__PURE__ */ jsx(Area, { type: "monotone", dataKey: s.key, name: s.label, stroke: color(i), fill: color(i), fillOpacity: 0.18, strokeWidth: 2, connectNulls: true }, s.key))
+      ] });
+      break;
+    case "scatter":
+      chart = /* @__PURE__ */ jsxs(ScatterChart, { accessibilityLayer: false, margin: { top: 8, right: 12, bottom: 8, left: 0 }, children: [
+        grid,
+        /* @__PURE__ */ jsx(XAxis, { type: "number", dataKey: block.xKey, name: block.xLabel ?? block.xKey, ...axisProps, tickFormatter: (v) => formatTick(v, void 0) }),
+        /* @__PURE__ */ jsx(YAxis, { type: "number", ...axisProps, width: 56, tickFormatter: tick }),
+        tooltip,
+        showLegend && /* @__PURE__ */ jsx(Legend, { verticalAlign: "top", wrapperStyle: { fontSize: 12, paddingBottom: 4 } }),
+        block.series.map((s, i) => /* @__PURE__ */ jsx(
+          Scatter,
+          {
+            name: s.label,
+            data: block.data.map((row) => ({ [block.xKey]: row[block.xKey], y: row[s.key] })),
+            dataKey: "y",
+            fill: color(i)
+          },
+          s.key
+        ))
+      ] });
+      break;
+    case "waterfall": {
+      const key = block.series[0]?.key;
+      let running = 0;
+      const shaped = block.data.map((row, i) => {
+        const value = Number(row[key ?? ""] ?? 0) || 0;
+        const isTotal = i === block.data.length - 1;
+        const base = isTotal ? Math.min(0, value) : Math.min(running, running + value);
+        if (!isTotal) running += value;
+        return {
+          [block.xKey]: row[block.xKey],
+          base,
+          bar: Math.abs(value),
+          raw: value,
+          fill: isTotal ? color(0) : value >= 0 ? "var(--cfi-color-success, #10b981)" : "var(--cfi-color-error, #ef4444)"
+        };
+      });
+      chart = /* @__PURE__ */ jsxs(BarChart, { accessibilityLayer: false, data: shaped, margin: { top: 8, right: 12, bottom: 8, left: 0 }, children: [
+        grid,
+        x,
+        y,
+        /* @__PURE__ */ jsx(
+          Tooltip,
+          {
+            ...tooltipStyle,
+            formatter: ((_v, name, item) => name === "base" ? [null, null] : [fmt(item?.payload?.raw ?? 0), block.series[0]?.label ?? ""])
+          }
+        ),
+        /* @__PURE__ */ jsx(ReferenceLine, { y: 0, stroke: "var(--cfi-chart-axis, #d1d5db)" }),
+        /* @__PURE__ */ jsx(Bar, { dataKey: "base", stackId: "w", fill: "transparent", isAnimationActive: false }),
+        /* @__PURE__ */ jsx(Bar, { dataKey: "bar", stackId: "w", radius: [3, 3, 0, 0], children: shaped.map((entry, i) => /* @__PURE__ */ jsx(Cell, { fill: entry.fill }, i)) })
+      ] });
+      break;
+    }
+    case "bar":
+    default:
+      if (sideways) {
+        chart = /* @__PURE__ */ jsxs(BarChart, { accessibilityLayer: false, data: block.data, layout: "vertical", margin: { top: 8, right: 16, bottom: 8, left: 0 }, children: [
+          /* @__PURE__ */ jsx(CartesianGrid, { strokeDasharray: "3 3", stroke: "var(--cfi-chart-grid, #e5e7eb)", horizontal: false }),
+          /* @__PURE__ */ jsx(
+            XAxis,
+            {
+              type: "number",
+              ...axisProps,
+              tickFormatter: tick,
+              allowDecimals,
+              tickCount,
+              label: block.yLabel ? { value: block.yLabel, position: "insideBottom", offset: -4, fontSize: 11 } : void 0
+            }
+          ),
+          /* @__PURE__ */ jsx(YAxis, { type: "category", dataKey: block.xKey, ...axisProps, width: 150, interval: 0, tickFormatter: shorten }),
+          tooltip,
+          showLegend && /* @__PURE__ */ jsx(Legend, { verticalAlign: "top", wrapperStyle: { fontSize: 12, paddingBottom: 4 } }),
+          block.series.map((s, i) => /* @__PURE__ */ jsx(Bar, { dataKey: s.key, name: s.label, fill: color(i), radius: [0, 3, 3, 0], maxBarSize: 28 }, s.key))
+        ] });
+        break;
+      }
+      chart = /* @__PURE__ */ jsxs(BarChart, { accessibilityLayer: false, data: block.data, margin: { top: 8, right: 12, bottom: 8, left: 0 }, children: [
+        grid,
+        x,
+        y,
+        tooltip,
+        showLegend && /* @__PURE__ */ jsx(Legend, { verticalAlign: "top", wrapperStyle: { fontSize: 12, paddingBottom: 4 } }),
+        block.series.map((s, i) => /* @__PURE__ */ jsx(Bar, { dataKey: s.key, name: s.label, fill: color(i), radius: [3, 3, 0, 0] }, s.key))
+      ] });
+  }
+  return /* @__PURE__ */ jsxs("figure", { className: "cfi-ac-block cfi-ac-chart", children: [
+    block.title && /* @__PURE__ */ jsx("figcaption", { className: "cfi-ac-block__title", children: block.title }),
+    /* @__PURE__ */ jsxs("table", { className: "cfi-ac-sr-only", children: [
+      /* @__PURE__ */ jsx("caption", { children: block.title ?? "Chart data" }),
+      /* @__PURE__ */ jsx("thead", { children: /* @__PURE__ */ jsxs("tr", { children: [
+        /* @__PURE__ */ jsx("th", { scope: "col", children: block.xLabel ?? block.xKey }),
+        block.series.map((s) => /* @__PURE__ */ jsx("th", { scope: "col", children: s.label }, s.key))
+      ] }) }),
+      /* @__PURE__ */ jsx("tbody", { children: block.data.map((row, i) => /* @__PURE__ */ jsxs("tr", { children: [
+        /* @__PURE__ */ jsx("th", { scope: "row", children: String(row[block.xKey] ?? "") }),
+        block.series.map((s) => /* @__PURE__ */ jsx("td", { children: fmt(row[s.key]) }, s.key))
+      ] }, i)) })
+    ] }),
+    /* @__PURE__ */ jsx("div", { className: "cfi-ac-chart__frame", style: { height: chartHeight }, "aria-hidden": true, children: /* @__PURE__ */ jsx(ResponsiveContainer, { width: "100%", height: "100%", children: chart }) })
+  ] });
+}
+export {
+  ChartBlock as default
+};

package/dist/chunk-2MWBMQMX.js

@@ -0,0 +1,91 @@
+// src/blocks/format.ts
+function formatValue(value, type, currency = "USD") {
+  if (value === null || value === void 0 || value === "") return "\u2014";
+  if (typeof value === "boolean") return value ? "Yes" : "No";
+  switch (type) {
+    case "number":
+      return typeof value === "number" ? value.toLocaleString(void 0, { maximumFractionDigits: 2 }) : String(value);
+    case "money":
+      if (typeof value !== "number") return String(value);
+      try {
+        return value.toLocaleString(void 0, {
+          style: "currency",
+          currency,
+          minimumFractionDigits: 2,
+          maximumFractionDigits: 4
+        });
+      } catch {
+        return value.toLocaleString(void 0, { minimumFractionDigits: 2, maximumFractionDigits: 4 });
+      }
+    case "percent":
+      return typeof value === "number" ? `${value.toLocaleString(void 0, { maximumFractionDigits: 1 })}%` : String(value);
+    case "date":
+      return formatDate(String(value));
+    default:
+      return String(value);
+  }
+}
+var DATE_ONLY = /^(\d{4})-(\d{2})-(\d{2})$/;
+function formatDate(value) {
+  const m = DATE_ONLY.exec(value);
+  const date = m ? new Date(Number(m[1]), Number(m[2]) - 1, Number(m[3])) : new Date(value);
+  if (Number.isNaN(date.getTime())) return value;
+  return date.toLocaleDateString(void 0, { year: "numeric", month: "short", day: "numeric" });
+}
+function formatTick(value, format, currency = "USD") {
+  if (typeof value !== "number") return String(value ?? "");
+  const compact = value.toLocaleString(void 0, { notation: "compact", maximumFractionDigits: 1 });
+  if (format === "percent") return `${compact}%`;
+  if (format === "money") {
+    try {
+      return value.toLocaleString(void 0, { style: "currency", currency, notation: "compact", maximumFractionDigits: 1 });
+    } catch {
+      return compact;
+    }
+  }
+  return compact;
+}
+function compareCells(a, b, type) {
+  const blankA = a === null || a === void 0 || a === "";
+  const blankB = b === null || b === void 0 || b === "";
+  if (blankA || blankB) return blankA === blankB ? 0 : blankA ? 1 : -1;
+  if (typeof a === "number" && typeof b === "number") return a - b;
+  if (type === "date") {
+    const ta = Date.parse(String(a));
+    const tb = Date.parse(String(b));
+    if (!Number.isNaN(ta) && !Number.isNaN(tb)) return ta - tb;
+  }
+  return String(a).localeCompare(String(b), void 0, { numeric: true, sensitivity: "base" });
+}
+function safeUrl(url) {
+  const trimmed = url.trim();
+  if (trimmed.startsWith("/") || trimmed.startsWith("#")) return trimmed;
+  try {
+    const parsed = new URL(trimmed);
+    return parsed.protocol === "https:" || parsed.protocol === "http:" ? trimmed : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function statusLabel(value) {
+  const text = String(value ?? "");
+  if (!/^[a-z0-9]+([_-][a-z0-9]+)*$/.test(text)) return text;
+  const words = text.replace(/[_-]+/g, " ");
+  return words.charAt(0).toUpperCase() + words.slice(1);
+}
+function statusTone(value) {
+  const v = String(value ?? "").toLowerCase();
+  if (/(done|complete|closed|approved|on track|green|passed|resolved)/.test(v)) return "good";
+  if (/(overdue|blocked|late|red|failed|rejected|critical|off track)/.test(v)) return "bad";
+  if (/(at risk|amber|yellow|pending|waiting|in review|warning)/.test(v)) return "warn";
+  return "neutral";
+}
+
+export {
+  formatValue,
+  formatTick,
+  compareCells,
+  safeUrl,
+  statusLabel,
+  statusTone
+};

package/dist/chunk-IDPIG6KY.js

@@ -0,0 +1,133 @@
+// src/client/sse.ts
+var EVENT_TYPES = /* @__PURE__ */ new Set(["text", "step", "block", "write_pending", "done", "error"]);
+var SseParser = class {
+  constructor() {
+    this.buffer = "";
+    this.decoder = new TextDecoder();
+  }
+  /** Feed a chunk; returns every event completed by it. */
+  push(chunk) {
+    this.buffer += typeof chunk === "string" ? chunk : this.decoder.decode(chunk, { stream: true });
+    const events = [];
+    let newline = this.buffer.search(/\r\n|\n|\r/);
+    while (newline !== -1) {
+      if (this.buffer[newline] === "\r" && newline === this.buffer.length - 1) break;
+      const line = this.buffer.slice(0, newline);
+      const width = this.buffer.startsWith("\r\n", newline) ? 2 : 1;
+      this.buffer = this.buffer.slice(newline + width);
+      const event = parseLine(line);
+      if (event) events.push(event);
+      newline = this.buffer.search(/\r\n|\n|\r/);
+    }
+    return events;
+  }
+  /** The stream ended: parse whatever is left as a last line. */
+  flush() {
+    const rest = this.buffer + this.decoder.decode();
+    this.buffer = "";
+    const event = parseLine(rest.replace(/\r$/, ""));
+    return event ? [event] : [];
+  }
+};
+function parseLine(line) {
+  if (!line.startsWith("data:")) return null;
+  const payload = line.slice(5).replace(/^ /, "");
+  if (!payload) return null;
+  try {
+    const value = JSON.parse(payload);
+    if (value && typeof value === "object" && typeof value.type === "string" && EVENT_TYPES.has(value.type)) {
+      return value;
+    }
+  } catch {
+  }
+  return null;
+}
+async function* readEvents(body) {
+  const parser = new SseParser();
+  const reader = body.getReader();
+  let finished = false;
+  try {
+    for (; ; ) {
+      const { done, value } = await reader.read();
+      if (done) break;
+      for (const event of parser.push(value)) yield event;
+    }
+    finished = true;
+    for (const event of parser.flush()) yield event;
+  } finally {
+    if (!finished) await reader.cancel().catch(() => void 0);
+    reader.releaseLock();
+  }
+}
+
+// src/client/client.ts
+var AssistantHttpError = class extends Error {
+  constructor(status, message) {
+    super(message);
+    this.status = status;
+    this.name = "AssistantHttpError";
+  }
+};
+function createAssistantClient({ hubUrl, getToken, fetch: fetchImpl }) {
+  const base = `${hubUrl.replace(/\/+$/, "")}/api/v1/assistant`;
+  const doFetch = (input, init) => (fetchImpl ?? globalThis.fetch)(input, init);
+  const headers = async (extra) => {
+    const token = await getToken();
+    return { ...token ? { Authorization: `Bearer ${token}` } : {}, ...extra };
+  };
+  const json = async (res) => {
+    if (!res.ok) throw await httpError(res);
+    return await res.json();
+  };
+  return {
+    async *chatStream(req, opts) {
+      const res = await doFetch(`${base}/chat/stream`, {
+        method: "POST",
+        headers: await headers({ "Content-Type": "application/json", Accept: "text/event-stream" }),
+        body: JSON.stringify(req),
+        signal: opts?.signal
+      });
+      if (!res.ok) throw await httpError(res);
+      if (!res.body) throw new AssistantHttpError(res.status, "The answer arrived empty.");
+      yield* readEvents(res.body);
+    },
+    async confirmWrite(req) {
+      const res = await doFetch(`${base}/writes/confirm`, {
+        method: "POST",
+        headers: await headers({ "Content-Type": "application/json" }),
+        body: JSON.stringify(req)
+      });
+      return json(res);
+    },
+    async listActions(query) {
+      const params = new URLSearchParams();
+      if (query.sessionId) params.set("session_id", query.sessionId);
+      if (query.entityId) params.set("entity_id", query.entityId);
+      if (query.userId) params.set("user_id", query.userId);
+      if (query.limit != null) params.set("limit", String(query.limit));
+      const qs = params.toString();
+      const res = await doFetch(`${base}/actions${qs ? `?${qs}` : ""}`, { headers: await headers() });
+      return json(res);
+    }
+  };
+}
+async function httpError(res) {
+  let message = "";
+  try {
+    const body = await res.json();
+    const candidate = body.message ?? body.detail ?? body.error;
+    if (typeof candidate === "string") message = candidate;
+  } catch {
+  }
+  if (!message) {
+    message = res.status === 401 || res.status === 403 ? "AI chat is not available for your account." : "AI chat could not answer right now. Try again in a moment.";
+  }
+  return new AssistantHttpError(res.status, message);
+}
+
+export {
+  SseParser,
+  readEvents,
+  AssistantHttpError,
+  createAssistantClient
+};