@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/chat/trace-spacing.ts

@@ -0,0 +1,249 @@
+/**
+ * Canonical spacing and type rhythm for the digichat thread.
+ *
+ * A short scale (`--trace-space-1` … `--trace-space-8`, kept apart from the design tokens' `--space-*`) is the only length source.
+ * `DENSITY_TOKENS` is the one density set: four stack gaps, body padding,
+ * two line heights and two letter-spacings. Every mode (compact / default /
+ * airy) reassigns it on `.digichat-thread[data-density=…]`.
+ * The semantic `--trace-*` names are aliases of that set, kept so the rules
+ * that already read them keep working. Rules in `chat-digichat.css` and
+ * `chat-aui.css` reference the tokens and do not carry their own lengths.
+ *
+ * `default` is the fixed rhythm: room under the Worked title, one gap
+ * between every sibling group, a tighter gap inside a group, and a short
+ * step from a reasoning header into its text.
+ */
+
+export const TRACE_DENSITIES = ["compact", "default", "airy"] as const;
+export type TraceDensity = (typeof TRACE_DENSITIES)[number];
+
+export const DEFAULT_TRACE_DENSITY: TraceDensity = "default";
+
+/** localStorage key. Digichat only — the dashboard never reads it. */
+export const DENSITY_STORAGE_KEY = "dt-density";
+
+/** The scale, in rem. Density never invents a length outside this list. */
+export const TRACE_SPACE_SCALE = {
+  1: "0.125rem",
+  2: "0.25rem",
+  3: "0.375rem",
+  4: "0.5rem",
+  5: "0.625rem",
+  6: "0.75rem",
+  7: "1rem",
+  8: "1.25rem",
+} as const;
+
+/**
+ * One density set, mirrored by the CSS custom properties in
+ * `styles/chat-aui.css` (`--density-*`) and pinned by
+ * `styles/density-tokens.contract.test.ts`. Every length is on
+ * `TRACE_SPACE_SCALE`; the line heights and trackings are unitless.
+ */
+export type DensityTokens = {
+  /** Tightest stack gap: items inside a group, paragraphs, list items. */
+  gap1: string;
+  /** Sibling gap: messages, chain groups, block separation. */
+  gap2: string;
+  /** Roomier step: title → first row, block → next block. */
+  gap3: string;
+  /** Largest step: message → message. */
+  gap4: string;
+  /** Inset inside a reasoning / tool body, and the composer's own padding. */
+  pad: string;
+  /** Body line height (answers, prose). */
+  leading: string;
+  /** Trace / mono line height (reasoning, tool dumps, code). */
+  leadingTight: string;
+  /** Body letter spacing. */
+  tracking: string;
+  /** Mono / trace letter spacing. */
+  trackingMono: string;
+};
+
+export const DENSITY_TOKENS: Record<TraceDensity, DensityTokens> = {
+  compact: {
+    gap1: TRACE_SPACE_SCALE[1],
+    gap2: TRACE_SPACE_SCALE[2],
+    gap3: TRACE_SPACE_SCALE[3],
+    gap4: TRACE_SPACE_SCALE[4],
+    pad: "0rem",
+    leading: "1.45",
+    leadingTight: "1.3",
+    tracking: "-0.005em",
+    trackingMono: "0em",
+  },
+  default: {
+    gap1: TRACE_SPACE_SCALE[2],
+    gap2: TRACE_SPACE_SCALE[4],
+    gap3: TRACE_SPACE_SCALE[5],
+    gap4: TRACE_SPACE_SCALE[6],
+    pad: TRACE_SPACE_SCALE[1],
+    leading: "1.6",
+    leadingTight: "1.4",
+    tracking: "0em",
+    trackingMono: "0.01em",
+  },
+  airy: {
+    gap1: TRACE_SPACE_SCALE[3],
+    gap2: TRACE_SPACE_SCALE[6],
+    gap3: TRACE_SPACE_SCALE[7],
+    gap4: TRACE_SPACE_SCALE[8],
+    pad: TRACE_SPACE_SCALE[3],
+    leading: "1.75",
+    leadingTight: "1.55",
+    tracking: "0.005em",
+    trackingMono: "0.02em",
+  },
+};
+
+export type TraceSpacingTokens = {
+  /** Worked title → first row. Alias of `gap3`. */
+  titleGap: string;
+  /** Between sibling groups, whatever the group type. Alias of `gap2`. */
+  groupGap: string;
+  /** Between items inside one group, and between paragraphs in a body. Alias of `gap1`. */
+  withinGap: string;
+  /** Group header → its body. */
+  headerGap: string;
+  /** Block padding inside a reasoning / tool body. Alias of `pad`. */
+  bodyPad: string;
+  /** Inline indent of a reasoning body (the hairline rail). */
+  bodyIndent: string;
+  /** The chain block against the answer that follows it. Alias of `gap4`. */
+  chainGap: string;
+};
+
+/**
+ * Palette copy. The composer menu and `/density` print the same words.
+ * Kept here so the ids and the labels cannot drift from the tokens.
+ */
+export const TRACE_DENSITY_LABELS: Record<TraceDensity, string> = {
+  compact: "Compact · tighter",
+  default: "Default · balanced rhythm",
+  airy: "Airy · more room",
+};
+
+/**
+ * The semantic chain tokens, derived from `DENSITY_TOKENS` so a mode cannot
+ * disagree with itself. `headerGap` and `bodyIndent` are the two that are not
+ * a plain alias: a compact header sits flush, and the rail indent steps with
+ * the mode.
+ */
+function traceSpacingFor(
+  tokens: DensityTokens,
+  headerGap: string,
+  bodyIndent: string,
+): TraceSpacingTokens {
+  return {
+    titleGap: tokens.gap3,
+    groupGap: tokens.gap2,
+    withinGap: tokens.gap1,
+    headerGap,
+    bodyPad: tokens.pad,
+    bodyIndent,
+    chainGap: tokens.gap4,
+  };
+}
+
+export const TRACE_SPACING: Record<TraceDensity, TraceSpacingTokens> = {
+  compact: traceSpacingFor(DENSITY_TOKENS.compact, "0rem", TRACE_SPACE_SCALE[5]),
+  default: traceSpacingFor(
+    DENSITY_TOKENS.default,
+    DENSITY_TOKENS.default.gap1,
+    TRACE_SPACE_SCALE[6],
+  ),
+  airy: traceSpacingFor(DENSITY_TOKENS.airy, DENSITY_TOKENS.airy.gap2, TRACE_SPACE_SCALE[7]),
+};
+
+export function isTraceDensity(value: string): value is TraceDensity {
+  return (TRACE_DENSITIES as readonly string[]).includes(value);
+}
+
+export function normalizeTraceDensity(value: string | null | undefined): TraceDensity | null {
+  if (!value) return null;
+  const id = value.trim().toLowerCase();
+  return isTraceDensity(id) ? id : null;
+}
+
+/** A phone-width viewport has no room for the desktop rhythm either way. */
+export const MOBILE_DENSITY_QUERY = "(max-width: 640px)";
+
+/** What a phone gets when nobody has chosen a rhythm. */
+export const MOBILE_DEFAULT_DENSITY: TraceDensity = "airy";
+
+/**
+ * Resolution order, highest first:
+ *
+ *   1. a stored user choice (`dt-density`)   — always wins, desktop or phone
+ *   2. the mobile default (airy)             — viewports <= 640px
+ *   3. an explicit deployment density
+ *   4. the builtin `default` rhythm
+ *
+ * The mobile default deliberately outranks a deployment default: a deployment
+ * picks a density for a desktop panel, and a phone still needs air. Passing no
+ * context (the old two-argument call) keeps the pre-mobile behaviour.
+ */
+export function resolveTraceDensity(
+  stored: string | null | undefined,
+  deployed: string | null | undefined,
+  context: { mobile?: boolean } = {},
+): TraceDensity {
+  const chosen = normalizeTraceDensity(stored);
+  if (chosen) return chosen;
+  if (context.mobile) return MOBILE_DEFAULT_DENSITY;
+  return normalizeTraceDensity(deployed) ?? DEFAULT_TRACE_DENSITY;
+}
+
+type DensityStorage = {
+  getItem(key: string): string | null;
+  setItem?(key: string, value: string): void;
+};
+
+function safeStorage(): DensityStorage | null {
+  try {
+    if (typeof localStorage === "undefined") return null;
+    return localStorage;
+  } catch {
+    return null;
+  }
+}
+
+export function readStoredDensity(storage?: DensityStorage | null): TraceDensity | null {
+  const store = storage === undefined ? safeStorage() : storage;
+  if (!store) return null;
+  try {
+    return normalizeTraceDensity(store.getItem(DENSITY_STORAGE_KEY));
+  } catch {
+    return null;
+  }
+}
+
+export function writeStoredDensity(density: TraceDensity, storage?: DensityStorage | null): void {
+  const store = storage === undefined ? safeStorage() : storage;
+  if (!store?.setItem) return;
+  try {
+    store.setItem(DENSITY_STORAGE_KEY, density);
+  } catch {
+    /* private mode */
+  }
+}
+
+type DensityViewport = {
+  matchMedia?(query: string): { matches: boolean };
+};
+
+/**
+ * True when the viewport is phone-width. Never throws: a host without
+ * `matchMedia` (bare jsdom, a server render) simply is not mobile.
+ */
+export function matchesMobileDensityViewport(viewport?: DensityViewport | null): boolean {
+  const target =
+    viewport === null ? null : (viewport ?? (typeof window === "undefined" ? null : window));
+  if (!target || typeof target.matchMedia !== "function") return false;
+  try {
+    return target.matchMedia(MOBILE_DENSITY_QUERY).matches === true;
+  } catch {
+    return false;
+  }
+}

package/src/components/chat/transcript/activity-view.ts

@@ -0,0 +1,375 @@
+/**
+ * Activity → canon projection (#1418 gap 6).
+ *
+ * `DigiChatActivity` is the wire vocabulary every backend provider emits (see
+ * digichat's `lib/chat-activity.ts`); the shared chat family in
+ * `@digithings-ai/ui` is the *rendering* vocabulary — collapsible `ChatToolCall`
+ * rows, a `ChatThinking` disclosure, `ChatWidgetFrame` cards. The two do not
+ * line up field-for-field, so this module is the boundary adapter between
+ * them: one pure function, no JSX, no DOM. Session UI in digichat 2.0 reads
+ * `source-*` parts directly; these helpers remain for export / legacy hydrate.
+ *
+ * Keeping the projection separate from the component is what makes the mapping
+ * testable in a plain node environment (no jsdom in either consumer's vitest
+ * setup) — and it is the seam to extend when the protocol grows a field, so
+ * neither the shared primitives nor the renderer has to fork.
+ *
+ * Fidelity notes — where the wire model carries less than the canon can show:
+ *
+ *  - **No timings.** `ActivitySpan` has no duration field, so nothing can fill
+ *    `ChatToolCall`'s `duration` slot with real milliseconds. It is the head
+ *    row's right-aligned mono meta slot, so we spend it on the outcome count
+ *    (`3 notes` / `no hits`) — the fact a reader actually wants folded, and
+ *    the only way a collapsed result row stays honest about whether the search
+ *    found anything.
+ *  - **`status` rows without an outcome have already lost their structure.** By the time a
+ *    withheld-documents outcome reaches here it is prose (`Found results for "x".`), with the tool
+ *    name and query dissolved into the string upstream. Parsing them back out of prose would be
+ *    guesswork, so these render as canon system asides rather than as fake tool rows. A `status`
+ *    carrying an `outcome` keeps its structure and renders as a first-class tool row instead.
+ *  - **Reasoning arrives as one blob**, not pre-segmented steps, so it maps to
+ *    `ChatThinking`'s `children` disclosure rather than its railed `steps`
+ *    list. See `ChatThinking`'s own docstring, which prescribes exactly this.
+ */
+import type { ChatToolCallStatus } from "@digithings-ai/ui";
+import type { DigiChatActivity, VaultHitSummary } from "./types";
+
+/**
+ * Ephemeral Foundry ack labels — never chain rows. The session uses a bare
+ * flash caret for progress; these would duplicate it and linger after settle.
+ */
+export const WORKING_LABEL = "Working…";
+
+/** Activities that belong in the tool/trace chain (excludes ephemeral Working…). */
+export function chainActivities(
+  activities: readonly DigiChatActivity[],
+): DigiChatActivity[] {
+  return activities.filter(
+    (a) => !(a.kind === "trace" && a.label === WORKING_LABEL),
+  );
+}
+
+/** Path only when it adds information — Foundry search hits set both to the
+ *  same chunk id (`page__docs___chunk0`), which was rendering twice. */
+export function distinctHitPath(title: string, path: string): string | null {
+  return path && path !== title ? path : null;
+}
+
+/**
+ * One rendered row of the agent chain. Each variant names the shared primitive
+ * it becomes, and carries only what that primitive's props need.
+ */
+export type CanonActivityRow =
+  | {
+      /** → <ChatToolCall> */
+      kind: "tool";
+      key: string;
+      /** Head name, rendered in the accent. */
+      name: string;
+      /** Head `(args)` — the query, when the provider sent one. */
+      args?: string;
+      status: ChatToolCallStatus;
+      /** Right-aligned head meta — an outcome count, not a timing (see above). */
+      meta?: string;
+      /** Retrieved documents, rendered as the fold-out body of this tool row. */
+      sources?: VaultHitSummary[];
+      /**
+       * Running rows carry a body line so the head is expandable (caret).
+       * Locate tools use "Searching…"; other in-flight tools use "Working…".
+       */
+      lines?: string[];
+      /** Start expanded when a body is attached. */
+      defaultOpen?: boolean;
+    }
+  | {
+      /** → <ChatThinking> */
+      kind: "thinking";
+      key: string;
+      label: string;
+      text: string;
+    }
+  | {
+      /** → <ChatWidgetFrame variant="card"> */
+      kind: "brief";
+      key: string;
+      themes: { label: string; summary: string }[];
+      questions?: string[];
+    }
+  | {
+      /** → <ChatMessage role="system"> — a `·` aside. */
+      kind: "aside";
+      key: string;
+      message: string;
+    };
+
+/** `3 notes` / `1 note` / `no hits` — the folded outcome read. */
+export function outcomeMeta(count: number): string {
+  if (count <= 0) return "no hits";
+  return `${count} note${count === 1 ? "" : "s"}`;
+}
+
+/** Wire ids whose in-flight fold should read "Searching…", not "Working…". */
+const LOCATE_TOOL_NAMES = new Set([
+  "digisearch",
+  "azure_ai_search",
+  "rag_sources",
+  "digivault",
+  "digivault_search_notes",
+  "web_search",
+]);
+
+/** Raw backend tool id for the head — one-to-one with the backend. */
+export function toolDisplayName(name: string): string {
+  return name;
+}
+
+/** In-flight body so the head stays a disclosure; locate tools keep Searching…. */
+function inFlightToolLines(toolName: string): string[] {
+  return LOCATE_TOOL_NAMES.has(toolName) ? ["Searching…"] : [WORKING_LABEL];
+}
+
+const QUERY_DISPLAY_MAX = 80;
+
+/** Omit a query that already appeared on the previous row; truncate long ones. */
+export function displayArgs(
+  query: string | undefined,
+  previousQuery: string | undefined,
+): string | undefined {
+  const q = query?.trim();
+  if (!q) return undefined;
+  if (previousQuery?.trim() === q) return undefined;
+  if (q.length <= QUERY_DISPLAY_MAX) return q;
+  return `${q.slice(0, QUERY_DISPLAY_MAX - 1).trimEnd()}…`;
+}
+
+/** Strip markdown chrome so a snippet reads as a sentence, not a wall. */
+export function readableSnippet(raw: string, max = 220): string {
+  const s = raw
+    .replace(/```[\s\S]*?```/g, " ")
+    .replace(/!\[[^\]]*]\([^)]*\)/g, " ")
+    .replace(/\[([^\]]*)]\([^)]*\)/g, "$1")
+    .replace(/[#*_`>~]+/g, " ")
+    .replace(/\s+/g, " ")
+    .trim();
+  if (!s) return "";
+  if (s.length <= max) return s;
+  const cut = s.slice(0, max);
+  const lastStop = Math.max(
+    cut.lastIndexOf(". "),
+    cut.lastIndexOf("? "),
+    cut.lastIndexOf("! "),
+  );
+  const end =
+    lastStop > max * 0.45 ? cut.slice(0, lastStop + 1) : cut.replace(/\s+\S*$/, "");
+  return `${end.trimEnd()}…`;
+}
+
+function previousQueryAt(
+  activities: readonly DigiChatActivity[],
+  i: number,
+): string | undefined {
+  const prev = activities[i - 1];
+  if (!prev || !("query" in prev)) return undefined;
+  return prev.query;
+}
+
+function hitsForDisplay(hits: VaultHitSummary[] | undefined): VaultHitSummary[] | undefined {
+  if (!hits?.length) return undefined;
+  return hits.map((hit) =>
+    hit.snippet ? { ...hit, snippet: readableSnippet(hit.snippet) } : hit,
+  );
+}
+
+/**
+ * Projects the wire activities onto canon rows, in order.
+ *
+ * Keyed by IDENTITY, not position. Position is not stable: `toDigiChatActivity`
+ * appends the reasoning row last, after every tool row, so its index climbs each
+ * time a tool arrives; it also rewrites a row in place from `tool_call` to
+ * `tool_result` (kind is part of any composite key), and its final filter drops
+ * orphaned placeholders, shifting everything after them. Since `ChatThinking`
+ * and `ChatToolCall` are uncontrolled, a changed key is an unmount — so an
+ * index key collapsed a disclosure the reader had opened, mid-stream, and
+ * removed its text from the DOM.
+ *
+ * Reasoning is a singleton per turn, so it keys as itself. Tool rows key on
+ * name+query, which is the identity the producer already groups by internally.
+ * A trailing index still disambiguates genuine duplicates.
+ */
+/**
+ * A key that survives the row moving. `reasoning` is one per turn so it needs no
+ * suffix; tool rows carry name+query (the producer's own grouping key) and a
+ * trailing index only to separate true duplicates.
+ */
+function identityKey(activity: DigiChatActivity, i: number): string {
+  switch (activity.kind) {
+    case "reasoning":
+      return "reasoning";
+    case "tool_call":
+    case "tool_result":
+      return `tool:${activity.name}|${"query" in activity ? (activity.query ?? "") : ""}`;
+    default:
+      return `${activity.kind}-${i}`;
+  }
+}
+
+export function toCanonRows(activities: readonly DigiChatActivity[]): CanonActivityRow[] {
+  return activities.map((activity, i): CanonActivityRow => {
+    const key = identityKey(activity, i);
+    const args =
+      "query" in activity ? displayArgs(activity.query, previousQueryAt(activities, i)) : undefined;
+    switch (activity.kind) {
+      case "tool_call":
+        return {
+          kind: "tool",
+          key,
+          name: toolDisplayName(activity.name),
+          ...(args ? { args } : {}),
+          status: "running",
+          lines: inFlightToolLines(activity.name),
+        };
+
+      case "tool_result":
+        return {
+          kind: "tool",
+          key,
+          name: toolDisplayName(activity.name),
+          ...(args ? { args } : {}),
+          status: "ok",
+          meta: outcomeMeta(activity.count),
+          ...(activity.hits.length ? { sources: hitsForDisplay(activity.hits) } : {}),
+        };
+
+      case "trace":
+        // An opaque upstream step. It has a label but no arguments and no
+        // output, so it rebuilds as a bodyless tool row — the canon's own
+        // read for "a step that ran".
+        return {
+          kind: "tool",
+          key,
+          name: activity.label,
+          status: activity.done ? "ok" : "running",
+        };
+
+      case "reasoning":
+        return { kind: "thinking", key, label: "reasoning", text: activity.text };
+
+      case "brief":
+        return {
+          kind: "brief",
+          key,
+          themes: activity.themes,
+          ...(activity.questions?.length ? { questions: activity.questions } : {}),
+        };
+
+      case "status": {
+        // Absent outcome: a quiet note (e.g. results exist but tenant detail
+        // withholds them). Present outcome: the emitter kept the structure,
+        // so this renders as a first-class tool row — "failed" as an error,
+        // "unreadable" as an honest unknown with NO count. A missing count
+        // stays missing: defaulting it to the zero string would read as
+        // "no hits", the exact lie this removes.
+        const outcome = activity.outcome;
+        if (!outcome) return { kind: "aside", key, message: activity.message };
+        const outcomeArgs = displayArgs(outcome.query, previousQueryAt(activities, i));
+        return {
+          kind: "tool",
+          key,
+          name: toolDisplayName(outcome.name),
+          ...(outcomeArgs ? { args: outcomeArgs } : {}),
+          status: outcome.state === "failed" ? "error" : "ok",
+        };
+      }
+
+      default: {
+        const _exhaustive: never = activity;
+        void _exhaustive;
+        return { kind: "aside", key, message: "" };
+      }
+    }
+  });
+}
+
+/**
+ * The step to show in the waiting caret: what the agent is doing *right now*,
+ * or nothing.
+ *
+ * The caret used to cycle a hard-coded script — "thinking", "routing through
+ * digigraph", "gathering context", "composing the answer" — on a ~10s loop
+ * regardless of what was happening. It read as a placeholder because it was
+ * one: none of those words were tied to any real step, and two of them named
+ * a backend this transcript may not even be talking to.
+ *
+ * So the label comes from the stream or there is no label. `undefined` means
+ * the caller shows a bare blinking cursor — an honest "something is happening"
+ * beats a confident sentence about the wrong thing.
+ *
+ * Scans from the end because the newest unfinished step is the current one.
+ * A tool row is "unfinished" until a tool_result for the same name arrives;
+ * matching on name alone (not name+query) is deliberate, since a call's query
+ * is often still empty while it is in flight — that is exactly the case this
+ * has to cover.
+ */
+export function liveActivityLabel(activities: DigiChatActivity[]): string | undefined {
+  const settledTools = new Set<string>();
+  for (let i = activities.length - 1; i >= 0; i -= 1) {
+    const activity = activities[i];
+    switch (activity.kind) {
+      case "tool_result":
+        settledTools.add(activity.name);
+        break;
+      case "status":
+        // A promoted status settles exactly the tool it names — keyed by
+        // name, the same key tool_result uses, so one tool's outcome never
+        // silences a different tool still running.
+        if (activity.outcome) settledTools.add(activity.outcome.name);
+        break;
+      case "tool_call": {
+        if (settledTools.has(activity.name)) break;
+        const query = activity.query?.trim();
+        return query ? `Searching for "${query}"` : "Searching…";
+      }
+      case "trace":
+        if (!activity.done) return activity.label;
+        break;
+      default:
+        break;
+    }
+  }
+  return undefined;
+}
+
+/**
+ * Deduped hit list across settled searches on a turn. Kept for callers that
+ * want a flat view; the session renders hits on each tool row instead.
+ */
+export function citationHits(activities: readonly DigiChatActivity[]): VaultHitSummary[] {
+  const out: VaultHitSummary[] = [];
+  const byPath = new Map<string, number>();
+  for (const activity of activities) {
+    if (activity.kind !== "tool_result") continue;
+    for (const hit of activity.hits) {
+      const idx = byPath.get(hit.path);
+      if (idx === undefined) {
+        byPath.set(hit.path, out.length);
+        out.push(hit);
+        continue;
+      }
+      if (!out[idx].body && hit.body) {
+        out[idx] = hit;
+      }
+    }
+  }
+  return out;
+}
+
+/** Foundry inline markers — `【9:0†source】` — stream as raw answer text.
+ *  Strip so the prose stays human-readable; the chunks already sit on the
+ *  search tool row that produced them. */
+export function stripFoundryCitationMarkers(text: string): string {
+  return text
+    .replace(/\u3010[\d:]+\u2020source\u3011/g, "")
+    .replace(/[ \t]+\n/g, "\n")
+    .replace(/ {2,}/g, " ")
+    .trimEnd();
+}