@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/chat/transcript/transcript-markdown.ts

@@ -0,0 +1,428 @@
+/**
+ * Shared markdown serializer for digichat turn copy + full-thread export (#3465).
+ *
+ * Payload rules: keep fenced code / GFM tables; strip Foundry citation markers;
+ * optional Sources lines from citation cards (title + path only — never vault body,
+ * tool JSON, BYOK keys, or headers). Searching/tool rows and slash notes are omitted
+ * because callers only pass user/assistant text turns.
+ */
+
+import { REDACTED, redactString } from "../../../replay/redact";
+import { stripFoundryCitationMarkers } from "./activity-view";
+import { saveTextFile } from "./save-file";
+
+export type TranscriptSource = {
+  title: string;
+  path: string;
+};
+
+export type TranscriptTurn = {
+  role: "user" | "assistant";
+  content: string;
+  /** Citation cards already shown on that assistant turn (title + path only). */
+  sources?: readonly TranscriptSource[];
+};
+
+export type CopyMarkdownResult = "clipboard" | "download" | "postMessage" | "textarea";
+
+const COPY_POST_MESSAGE_TYPE = "digichat:copy";
+
+/** Single-turn markdown — the string already fed to MiniMarkdown / ChatMarkdown. */
+export function serializeAssistantMarkdown(
+  content: string,
+  sources?: readonly TranscriptSource[],
+): string {
+  const body = stripFoundryCitationMarkers(content).trim();
+  const sourceBlock = formatSources(sources);
+  if (!sourceBlock) return body;
+  return body ? `${body}\n\n${sourceBlock}` : sourceBlock;
+}
+
+/** Full thread: `## You` / `## digichat` per text turn, in order. */
+export function serializeThreadMarkdown(turns: readonly TranscriptTurn[]): string {
+  const blocks: string[] = [];
+  for (const turn of turns) {
+    const heading = turn.role === "user" ? "## You" : "## digichat";
+    const body =
+      turn.role === "assistant"
+        ? serializeAssistantMarkdown(turn.content, turn.sources)
+        : turn.content.trim();
+    if (!body) continue;
+    blocks.push(`${heading}\n\n${body}`);
+  }
+  return blocks.join("\n\n");
+}
+
+function formatSources(sources?: readonly TranscriptSource[]): string {
+  if (!sources?.length) return "";
+  const lines = sources
+    .map((s) => {
+      const title = (s.title || s.path || "").trim();
+      const path = (s.path || "").trim();
+      if (!title && !path) return null;
+      if (path && path !== title) return `- ${title} (${path})`;
+      return `- ${title || path}`;
+    })
+    .filter((line): line is string => Boolean(line));
+  if (!lines.length) return "";
+  return `### Sources\n\n${lines.join("\n")}`;
+}
+
+/** Iframe-safe download — always available when `document` exists. */
+/** Save a text export. See `save-file.ts` for the phone and iframe paths. */
+export function downloadTextFile(filename: string, text: string, mime: string): void {
+  saveTextFile(filename, text, mime);
+}
+
+export function downloadMarkdown(filename: string, text: string): void {
+  downloadTextFile(
+    filename.endsWith(".md") ? filename : `${filename}.md`,
+    redactString(text),
+    "text/markdown;charset=utf-8",
+  );
+}
+
+/** Plain-text export — same serializer output with fence delimiters stripped. */
+export function downloadPlainText(filename: string, markdown: string): void {
+  const name = filename.endsWith(".txt") ? filename : `${filename}.txt`;
+  downloadTextFile(
+    name,
+    markdownToPlainText(redactString(markdown)),
+    "text/plain;charset=utf-8",
+  );
+}
+
+/** Minimal HTML export — pre-wrapped markdown, no renderer dependency. */
+export function downloadHtml(
+  filename: string,
+  markdown: string,
+  title = "digichat transcript",
+): void {
+  const name = filename.endsWith(".html") ? filename : `${filename}.html`;
+  downloadTextFile(
+    name,
+    markdownToHtmlDocument(redactString(markdown), redactString(title)),
+    "text/html;charset=utf-8",
+  );
+}
+
+function tryParentCopyPostMessage(text: string): boolean {
+  if (typeof window === "undefined") return false;
+  try {
+    if (window.parent && window.parent !== window) {
+      window.parent.postMessage({ type: COPY_POST_MESSAGE_TYPE, text }, "*");
+      return true;
+    }
+  } catch {
+    /* cross-origin access or blocked */
+  }
+  return false;
+}
+
+/**
+ * Selectable textarea fallback when clipboard + download both fail.
+ * Appends a temporary field, selects it, and focuses so the user can ⌘C.
+ */
+export function showSelectableTextareaFallback(text: string): void {
+  if (typeof document === "undefined") return;
+  const existing = document.getElementById("dc-copy-fallback");
+  existing?.remove();
+  const ta = document.createElement("textarea");
+  ta.id = "dc-copy-fallback";
+  ta.value = text;
+  ta.setAttribute("aria-label", "Copy markdown");
+  ta.readOnly = true;
+  Object.assign(ta.style, {
+    position: "fixed",
+    left: "0.5rem",
+    right: "0.5rem",
+    bottom: "0.5rem",
+    zIndex: "9999",
+    width: "auto",
+    maxHeight: "40vh",
+    font: "12px/1.4 ui-monospace, monospace",
+    padding: "0.5rem",
+    border: "1px solid currentColor",
+    background: "Canvas",
+    color: "CanvasText",
+  });
+  document.body.appendChild(ta);
+  ta.focus();
+  ta.select();
+}
+
+/**
+ * Copy markdown with embed-safe fallbacks (#3465).
+ *
+ * Order: clipboard → `.md` download → optional parent `digichat:copy` postMessage →
+ * selectable textarea. Never a silent no-op when `document` exists.
+ *
+ * The payload is redacted once, up front: every branch below hands the same
+ * redacted text to the clipboard, the download, the parent frame and the
+ * textarea fallback, so no branch can carry a secret out of the app.
+ */
+export async function copyMarkdownWithFallback(
+  text: string,
+  opts?: { filename?: string },
+): Promise<CopyMarkdownResult> {
+  const filename = opts?.filename ?? "digichat.md";
+  const safe = redactString(text);
+
+  if (typeof navigator !== "undefined" && navigator.clipboard?.writeText) {
+    try {
+      await navigator.clipboard.writeText(safe);
+      return "clipboard";
+    } catch {
+      /* blocked in cross-origin iframes — continue */
+    }
+  }
+
+  if (typeof document !== "undefined") {
+    try {
+      downloadMarkdown(filename, safe);
+      tryParentCopyPostMessage(safe);
+      return "download";
+    } catch {
+      /* fall through */
+    }
+  }
+
+  if (tryParentCopyPostMessage(safe)) {
+    return "postMessage";
+  }
+
+  showSelectableTextareaFallback(safe);
+  return "textarea";
+}
+
+/* ---------------------------------------------------------------------------
+ * Print + mailto + txt/html export (#3510). Reuses the #3465 serializers —
+ * no vault bodies, tool JSON, or BYOK payloads ever enter these strings.
+ * ------------------------------------------------------------------------- */
+
+/** Safe `mailto:` body budget after `encodeURIComponent` (spec: ~1500–2000). */
+export const MAILTO_MAX_ENCODED_LEN = 1800;
+
+/** Appended when the mailto body is cut to fit the URL budget. */
+export const MAILTO_TRUNCATION_NOTE = "…(truncated — download .md for full thread)";
+
+export type TruncateForMailtoResult = { text: string; truncated: boolean };
+
+/**
+ * Move a cut back so it never lands inside a redaction marker.
+ *
+ * The body is redacted before it is cut, so the cut can land inside a
+ * `[redacted]` marker. A marker that the cut splits is dropped whole rather
+ * than shown half-written. A marker that ends before the cut is kept, and a
+ * `[` that is the user's own text is not a marker and is left alone.
+ */
+function cutOutsideMarker(body: string, cut: number): number {
+  for (let len = 1; len < REDACTED.length; len += 1) {
+    const start = cut - len;
+    if (start < 0) break;
+    const before = body.slice(start, cut);
+    const after = body.slice(cut, cut + (REDACTED.length - len));
+    if (before === REDACTED.slice(0, len) && after === REDACTED.slice(len)) return start;
+  }
+  return cut;
+}
+
+/**
+ * Cut `body` so `encodeURIComponent(text)` fits `maxEncoded` chars.
+ * Binary-searches the longest fitting prefix, then appends the truncation
+ * note. Pure — covered by vitest.
+ */
+export function truncateForMailto(
+  body: string,
+  maxEncoded: number = MAILTO_MAX_ENCODED_LEN,
+): TruncateForMailtoResult {
+  if (encodeURIComponent(body).length <= maxEncoded) {
+    return { text: body, truncated: false };
+  }
+  const note = `\n\n${MAILTO_TRUNCATION_NOTE}`;
+  if (encodeURIComponent(note).length >= maxEncoded) {
+    let cut = note;
+    while (cut.length > 1 && encodeURIComponent(`${cut}…`).length >= maxEncoded) {
+      cut = cut.slice(0, -1);
+    }
+    return { text: cut, truncated: true };
+  }
+  let lo = 0;
+  let hi = body.length;
+  while (lo < hi) {
+    const mid = Math.ceil((lo + hi) / 2);
+    const candidate = body.slice(0, mid).trimEnd() + note;
+    if (encodeURIComponent(candidate).length <= maxEncoded) {
+      lo = mid;
+    } else {
+      hi = mid - 1;
+    }
+  }
+  const cut = cutOutsideMarker(body, lo);
+  return { text: `${body.slice(0, cut).trimEnd()}${note}`, truncated: true };
+}
+
+/**
+ * `mailto:` URL with a short subject and a truncation-safe body. No network.
+ *
+ * The body is redacted before the cut: a secret that straddles the URL
+ * budget would otherwise leave its head behind in the body, and the
+ * redaction marker counts toward the budget like any other character.
+ */
+export function buildMailtoUrl(
+  subject: string,
+  body: string,
+  opts?: { maxEncoded?: number },
+): string {
+  const { text } = truncateForMailto(
+    redactString(body),
+    opts?.maxEncoded ?? MAILTO_MAX_ENCODED_LEN,
+  );
+  return `mailto:?subject=${encodeURIComponent(redactString(subject))}&body=${encodeURIComponent(text)}`;
+}
+
+/** Last-assistant mailto — mirrors the per-turn copy payload. */
+export function buildAnswerMailto(markdown: string, opts?: { maxEncoded?: number }): string {
+  return buildMailtoUrl("digichat answer", markdown, opts);
+}
+
+/** Full-thread mailto — mirrors the thread `.md` download payload. */
+export function buildThreadMailto(markdown: string, opts?: { maxEncoded?: number }): string {
+  return buildMailtoUrl("digichat transcript", markdown, opts);
+}
+
+export type MailtoOpenResult = "mailto" | "download";
+
+export type ExportFallbackOpts = {
+  fallbackMarkdown?: string;
+  fallbackFilename?: string;
+  /**
+   * When true (embed / sandboxed iframe), skip mailto/print and download
+   * immediately. Sandboxed embeds often expose `print` and allow `a.click()`
+   * without throwing, so a try/catch-only fallback would silently no-op.
+   */
+  preferDownload?: boolean;
+};
+
+/**
+ * Open a `mailto:` URL; on blocked navigation fall back to a `.md` download
+ * (same spirit as the #3465 clipboard fallback). Never throws when `document`
+ * exists — worst case the caller gets `"download"`.
+ */
+export function openMailtoWithFallback(
+  mailtoUrl: string,
+  opts?: ExportFallbackOpts,
+): MailtoOpenResult {
+  const fallback = () => {
+    if (opts?.fallbackMarkdown !== undefined && typeof document !== "undefined") {
+      try {
+        downloadMarkdown(opts.fallbackFilename ?? "digichat-thread.md", opts.fallbackMarkdown);
+      } catch {
+        /* download also blocked — caller already has the markdown */
+      }
+    }
+  };
+  if (!mailtoUrl.startsWith("mailto:")) {
+    fallback();
+    return "download";
+  }
+  if (opts?.preferDownload || typeof document === "undefined") {
+    fallback();
+    return "download";
+  }
+  try {
+    const a = document.createElement("a");
+    a.href = mailtoUrl;
+    a.rel = "noopener";
+    document.body.appendChild(a);
+    a.click();
+    a.remove();
+    return "mailto";
+  } catch {
+    fallback();
+    return "download";
+  }
+}
+
+export type PrintTranscriptResult = "print" | "download";
+
+/**
+ * `window.print()` for the transcript; when print is unavailable/blocked
+ * (no window, embed sandbox), fall back to a `.md` download so the action
+ * is never a silent no-op.
+ */
+export function printTranscriptWithFallback(opts?: ExportFallbackOpts): PrintTranscriptResult {
+  const fallback = () => {
+    if (opts?.fallbackMarkdown !== undefined && typeof document !== "undefined") {
+      try {
+        downloadMarkdown(opts.fallbackFilename ?? "digichat-thread.md", opts.fallbackMarkdown);
+      } catch {
+        /* ignore — print already failed */
+      }
+    }
+  };
+  if (opts?.preferDownload) {
+    fallback();
+    return "download";
+  }
+  if (typeof window !== "undefined" && typeof window.print === "function") {
+    try {
+      window.print();
+      return "print";
+    } catch {
+      fallback();
+      return "download";
+    }
+  }
+  fallback();
+  return "download";
+}
+
+/**
+ * Lightweight markdown → plain text for `.txt` export. Strips fence
+ * delimiter lines only; prose (including code content) is kept as-is.
+ *
+ * A pure serializer: it does not redact. `downloadPlainText` redacts before
+ * it writes, so a caller that writes the result itself must redact too.
+ */
+export function markdownToPlainText(markdown: string): string {
+  return markdown
+    .split("\n")
+    .filter((line) => !line.trimStart().startsWith("```"))
+    .join("\n")
+    .trim();
+}
+
+function escapeHtml(text: string): string {
+  return text
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+/**
+ * Minimal HTML document for `.html` export — the markdown pre-wrapped in
+ * `<pre>`. Deliberately no GFM renderer dependency.
+ *
+ * A pure serializer: it does not redact. `downloadHtml` redacts before it
+ * writes, so a caller that writes the result itself must redact too.
+ */
+export function markdownToHtmlDocument(markdown: string, title = "digichat transcript"): string {
+  const safeTitle = escapeHtml(title);
+  const safeBody = escapeHtml(markdown);
+  return [
+    "<!doctype html>",
+    '<html lang="en">',
+    "<head>",
+    '<meta charset="utf-8">',
+    `<title>${safeTitle}</title>`,
+    "</head>",
+    "<body>",
+    `<h1>${safeTitle}</h1>`,
+    `<pre>${safeBody}</pre>`,
+    "</body>",
+    "</html>",
+    "",
+  ].join("\n");
+}

package/src/components/chat/transcript/types.ts

@@ -0,0 +1,81 @@
+export type VaultHitSummary = {
+  title: string;
+  path: string;
+  tier?: string;
+  year?: number;
+  snippet?: string;
+  /** Full note body from digivault_get_note — never an invented URL. */
+  body?: string;
+};
+
+/**
+ * Why a `status` row exists, when it is about a tool. Absent means a quiet note
+ * about the turn — "results exist but this detail level withholds them" — and it
+ * is the only reading a status without an outcome may have.
+ *
+ * `query` is absent when the turn never knew one, never `""`. `state`:
+ *   - `failed`     the tool was asked and did not answer
+ *   - `unreadable` the tool answered and this layer cannot read the answer; an
+ *                  honest unknown, and never an empty result
+ */
+export type DigiChatStatusOutcome = {
+  name: string;
+  query?: string;
+  state: "failed" | "unreadable";
+};
+
+export type DigiChatActivity =
+  | { kind: "status"; message: string; outcome?: DigiChatStatusOutcome }
+  | { kind: "tool_call"; name: string; query: string }
+  | {
+      kind: "tool_result";
+      name: string;
+      query: string;
+      hits: VaultHitSummary[];
+      count: number;
+    }
+  | { kind: "reasoning"; text: string }
+  | { kind: "trace"; label: string; done: boolean }
+  | {
+      kind: "brief";
+      themes: { label: string; summary: string }[];
+      questions?: string[];
+    };
+
+export type DigiChatMessage = {
+  role: "user" | "assistant";
+  content: string;
+  activities?: DigiChatActivity[];
+};
+
+/**
+ * Embed/controller adapter shape used by digichat's `useEmbedDigiChat` and
+ * activity projection. digichat 2.0 UI is `CliThread` (assistant-ui); this is
+ * not a mountable session component.
+ */
+export type DigiChatController = {
+  messages: DigiChatMessage[];
+  busy: boolean;
+  error: string | null;
+  quotaPrompt?: boolean;
+  send: (question: string, opts?: { forceTool?: string }) => void | Promise<void>;
+  stop?: () => void;
+  /** Error-row retry only — not last-turn regenerate chrome. */
+  onRetry?: () => void;
+  /**
+   * Re-answer the last user turn (drop trailing assistant, resend transcript).
+   * Omit on Foundry embeds until the turn-mutation API (#3475) — truncate-and-resend
+   * would append a duplicate user item on an append-only conversation.
+   */
+  regenerate?: () => void;
+  /**
+   * Replace the last user turn (and drop any following assistant), then send.
+   * Empty / whitespace-only text is a no-op. Omit on Foundry for the same reason
+   * as `regenerate`.
+   */
+  editLastUser?: (text: string) => void | Promise<void>;
+  reset?: () => void;
+  modelLabel?: string;
+  providerIsSet?: boolean;
+  openSettings?: () => void;
+};

package/src/components/chat/turn-outcome.ts

@@ -0,0 +1,52 @@
+"use client";
+
+import { useAuiState } from "@assistant-ui/react";
+
+/**
+ * How the current assistant turn stands, for the animations that follow it.
+ *
+ * - `running`: the turn is live, or waiting on the visitor (a tool approval).
+ * - `done`: the turn finished.
+ * - `stopped`: the visitor pressed stop, or the stream ended with a tool call
+ *   still open. Nothing more will arrive for it.
+ * - `failed`: the turn ended on an error.
+ *
+ * A stopped or failed turn ends every animation it started: the work-chain
+ * marker, its "Working" title and the open tool rows all show their final
+ * state instead (DIG-4459).
+ */
+export type TurnOutcome = "running" | "done" | "stopped" | "failed";
+
+type StatusLike = { readonly type?: string; readonly reason?: string } | null | undefined;
+
+/**
+ * assistant-ui's message status after the stream ends:
+ * - an error is `incomplete/error`;
+ * - a stop is `incomplete/cancelled`, except while a tool call has no result,
+ *   when it is `requires-action/tool-calls` (getAutoStatus ranks pending tool
+ *   calls above the cancel). Our tools run on the server, so a pending call
+ *   with the thread idle is a call that will never finish.
+ * - `requires-action/interrupt` waits on the visitor and stays live.
+ */
+export function turnOutcome(status: StatusLike, threadRunning: boolean): TurnOutcome {
+  const type = status?.type;
+  if (type === "incomplete") return status?.reason === "error" ? "failed" : "stopped";
+  if (type === "requires-action") {
+    return status?.reason === "tool-calls" && !threadRunning ? "stopped" : "running";
+  }
+  if (type === "running") return "running";
+  return "done";
+}
+
+/** The outcome of the message in scope; `done` outside a message. */
+export function useTurnOutcome(): TurnOutcome {
+  const status = useAuiState((s) => s.optional.message?.status as StatusLike);
+  const threadRunning = useAuiState((s) => s.optional.thread?.isRunning === true);
+  if (status === undefined) return "done";
+  return turnOutcome(status, threadRunning);
+}
+
+/** A turn that ended before it finished: stopped by the visitor or failed. */
+export function turnCutShort(outcome: TurnOutcome): boolean {
+  return outcome === "stopped" || outcome === "failed";
+}

package/src/components/chat/use-warmup-phase.ts

@@ -0,0 +1,18 @@
+"use client";
+
+import { useSyncExternalStore } from "react";
+import {
+  DIGI_CHAT_WARMUP_EVENT,
+  getDigichatWarmupPhase,
+  type DigichatWarmupPhase,
+} from "./boot-signal";
+
+function subscribe(cb: () => void): () => void {
+  window.addEventListener(DIGI_CHAT_WARMUP_EVENT, cb);
+  return () => window.removeEventListener(DIGI_CHAT_WARMUP_EVENT, cb);
+}
+
+/** Current service warm-up phase (see setDigichatWarmupPhase). */
+export function useDigichatWarmupPhase(): DigichatWarmupPhase {
+  return useSyncExternalStore(subscribe, getDigichatWarmupPhase, () => "idle");
+}

package/src/components/chat/work-status-lead.tsx

@@ -0,0 +1,49 @@
+"use client";
+
+import type { ReactNode } from "react";
+import { DotMatrix, type DotMatrixState } from "./DotMatrix";
+
+/**
+ * Marker and label shared by the pre-response loader and the Working / Worked
+ * header. Both rows render this, so the handoff is the label changing in the
+ * same slot beside the same 12px marker.
+ *
+ * `markerLabel` names the marker. Leave it out where the row is a control
+ * named by its visible text (the work chain trigger), so the glyph is
+ * decorative and the name is not read twice (DIG-4669).
+ */
+export function WorkStatusLead({
+  marker,
+  markerLabel,
+  label,
+}: {
+  marker: DotMatrixState;
+  markerLabel?: string;
+  label?: ReactNode;
+}) {
+  const showLabel =
+    label !== null &&
+    label !== undefined &&
+    !(typeof label === "string" && label.trim() === "");
+
+  return (
+    <>
+      <span data-slot="aui_work-status-marker" className="aui-work-status-marker">
+        {markerLabel === undefined ? (
+          <DotMatrix state={marker} decorative className="!size-3 shrink-0" />
+        ) : (
+          <DotMatrix
+            state={marker}
+            label={markerLabel}
+            className="!size-3 shrink-0"
+          />
+        )}
+      </span>
+      {showLabel ? (
+        <span data-slot="aui_work-status-label" className="aui-work-status-label">
+          {label}
+        </span>
+      ) : null}
+    </>
+  );
+}