@digithings-ai/ui 0.0.0-stage → 0.1.0

package/src/components/chat/stock/skin-slash-palette.tsx

@@ -0,0 +1,393 @@
+"use client";
+
+import { useCallback, useEffect, useMemo, useRef } from "react";
+import {
+  unstable_useMentionAdapter,
+  unstable_useSlashCommandAdapter,
+  useAui,
+  useAuiState,
+} from "@assistant-ui/react";
+import {
+  copyMarkdownWithFallback,
+  serializeAssistantMarkdown,
+  serializeThreadMarkdown,
+  transcriptTurns,
+  type ChatExportFormat,
+} from "../transcript";
+import type {
+  ThreadMentionTrigger,
+  ThreadSlashTrigger,
+} from "../gallery-thread/thread.aui";
+import { useStockSendGate } from "./stock-send-gate";
+import {
+  useEmbedChatPrefsOptional,
+  type EmbedChatPrefsApi,
+} from "./embed-chat-prefs";
+import { exportConversation } from "../../../replay/chat-export-run";
+import { applyExportSlash } from "../../../replay/export-format";
+import { useChatExportStrings } from "./message-export-menu";
+
+/**
+ * Product slash-command wiring injected by the host (WS4). Structural mirror
+ * of the app's product-slash-commands + pending-headers signatures, so the
+ * real app functions assign directly. The skin never imports app code.
+ *
+ * - `SkinSlashCommand` mirrors assistant-ui's `Unstable_SlashCommand`
+ *   (`{ readonly id; label?; description?; icon?; execute: () => void }`).
+ * - `SkinSlashExtraDef` mirrors the app's `SlashDef` minus `category`
+ *   (optional-only there, so assignment holds both directions; runtime
+ *   values are real app defs, and the skin never reads the extra fields).
+ * - `SkinSlashAction` mirrors the app's `SlashSubmitAction` (`pass`, not `none`).
+ */
+export type SkinSlashCommand = {
+  readonly id: string;
+  readonly label?: string | undefined;
+  readonly description?: string | undefined;
+  readonly icon?: string | undefined;
+  readonly execute: () => void;
+};
+
+export type SkinSlashExtraDef = {
+  id: string;
+  names: readonly string[];
+  needsArg: boolean;
+  hint: string;
+  forceTool?: string;
+  choiceOptions?: readonly { value: string; label: string }[];
+  kind?: "toggle" | "action" | "tool" | "client";
+};
+
+export type SkinSlashAction =
+  | { kind: "pass" }
+  | { kind: "block" }
+  | { kind: "force"; forceTool: string; text: string }
+  | { kind: "force-web"; text: string }
+  | { kind: "pane"; command: SkinSlashExtraDef; arg: string }
+  | { kind: "run"; command: SkinSlashExtraDef; arg: string };
+
+export type SkinPaletteKind = "closed" | "commands" | "pane";
+
+export type SkinPaletteFrame = {
+  kind: SkinPaletteKind;
+  filter?: string;
+  menu?: string;
+};
+
+export type SkinPaletteApply = {
+  kind: SkinPaletteKind;
+  menu: "close" | "keep" | string;
+  filter: string;
+};
+
+/**
+ * Structural mirror of the app's `SlashAdapterLike`
+ * (`apps/digichat/src/lib/product-slash-commands.ts`). Identical shape keeps
+ * the app's generic `prefixSlashAdapter` assignable to the prop below (WS4):
+ * a constrained generic is only assignable to the same constraint.
+ */
+export type SkinSlashAdapterLike = {
+  search?: (query: string) => readonly { id: string; label?: string }[];
+  categories?: () => readonly { id: string; label: string }[];
+  categoryItems?: (categoryId: string) => readonly unknown[];
+};
+
+export type DigichatSkinSlash = {
+  buildCommands: (prefs: EmbedChatPrefsApi) => SkinSlashCommand[];
+  extraDefs: (prefs: EmbedChatPrefsApi) => SkinSlashExtraDef[];
+  prefixAdapter: <T extends SkinSlashAdapterLike>(inner: T) => T;
+  shouldDraft: (id: string, extra: readonly SkinSlashExtraDef[]) => boolean;
+  submitAction: (
+    text: string,
+    extra?: readonly SkinSlashExtraDef[],
+  ) => SkinSlashAction;
+  executeDef: (
+    def: SkinSlashExtraDef,
+    arg: string,
+    prefs: EmbedChatPrefsApi,
+  ) => void;
+  executeFromComposer: (
+    id: "lang" | "effort" | "byok" | "mcp" | "tools",
+    composerText: string,
+    prefs: EmbedChatPrefsApi,
+    extra?: readonly SkinSlashExtraDef[],
+  ) => void;
+  /** Composer text → the one open surface. */
+  frame: (text: string) => SkinPaletteFrame;
+  /** Previous surface plus the next frame. A button-opened menu can stay. */
+  applyFrame: (prev: SkinPaletteKind, frame: SkinPaletteFrame) => SkinPaletteApply;
+  /** Draft written when a pane command is chosen (`/language `), or null. */
+  paneDraft: (id: string) => string | null;
+  armForceTool: (
+    sessionKey: string,
+    forceTool: string,
+    onHold: () => void,
+  ) => void;
+  setForceTool: (sessionKey: string, forceTool?: string) => void;
+  setWebSearchForce: (sessionKey: string, value: boolean) => void;
+};
+
+/** The product `/` palette, independent of the skin that renders it. */
+export type SkinSlashPalette = {
+  /** True when the host passed slash wiring and mounted the prefs host. */
+  enabled: boolean;
+  /** `/` trigger for a composer popover; undefined when disabled. */
+  slash: ThreadSlashTrigger | undefined;
+  /** `@` tool trigger; undefined when disabled or the catalog is empty. */
+  mention: ThreadMentionTrigger | undefined;
+  /**
+   * Runs the slash submit action for the composer text. Returns true when the
+   * palette consumed the submit (block, pane, force, run); the caller must
+   * then not send. False means a plain message: the skin sends as usual.
+   */
+  handleSubmit: (event: { preventDefault(): void }) => boolean;
+};
+
+export type SkinSlashPaletteOptions = {
+  slash?: DigichatSkinSlash | undefined;
+  /** Rebuilds the rows when the private session flips (`/private` value). */
+  privateMode?: boolean | undefined;
+};
+
+/**
+ * Product slash-command palette logic shared by every skin. The digichat skin
+ * hands the result to its own composer; every other skin gets it through
+ * `SkinPaletteBridge`. Moved verbatim from the digichat skin.
+ */
+export function useSkinSlashPalette({
+  slash: slashWiring,
+  privateMode,
+}: SkinSlashPaletteOptions): SkinSlashPalette {
+  const gate = useStockSendGate();
+  const prefs = useEmbedChatPrefsOptional();
+  const aui = useAui();
+  const composerText = useAuiState((s) => s.composer.text);
+  const palettePrev = useRef<SkinPaletteKind>("closed");
+  const slashPrefs = useMemo(() => {
+    if (!prefs) return null;
+    return {
+      ...prefs,
+      newThread: () => {
+        prefs.newThread();
+        aui.threads.switchToNewThread();
+      },
+    };
+  }, [prefs, aui]);
+  const enableSlash = Boolean(slashPrefs) && Boolean(slashWiring);
+  useEffect(() => {
+    if (!enableSlash || !slashPrefs?.syncPalette || !slashWiring) return;
+    const next = slashWiring.applyFrame(palettePrev.current, slashWiring.frame(composerText));
+    palettePrev.current = next.kind;
+    slashPrefs.syncPalette(next);
+  }, [composerText, enableSlash, slashPrefs, slashWiring]);
+  useEffect(() => {
+    if (!slashPrefs?.bindComposerDraft) return;
+    slashPrefs.bindComposerDraft((text) => {
+      aui.composer.setText(text);
+    });
+  }, [slashPrefs, aui]);
+  const extra = useMemo(
+    () =>
+      slashPrefs && slashWiring ? slashWiring.extraDefs(slashPrefs) : [],
+    [slashPrefs, slashWiring],
+  );
+
+  const exportStrings = useChatExportStrings();
+  const copyExport = useMemo(
+    () => ({
+      copy: () => {
+        const turns = transcriptTurns(aui.thread().getState().messages);
+        const last = [...turns].reverse().find((t) => t.role === "assistant");
+        if (!last) return;
+        void copyMarkdownWithFallback(serializeAssistantMarkdown(last.content, last.sources));
+      },
+      /** The whole conversation, from the chat menu or a typed `/export md|html`. */
+      exportConversation: (format: ChatExportFormat) => {
+        if (privateMode) return;
+        void exportConversation({
+          format,
+          privateMode,
+          messages: aui.thread().getState().messages,
+          strings: exportStrings,
+        });
+      },
+    }),
+    [aui, exportStrings, privateMode],
+  );
+  // The settings menu and the `/export` pane live outside the runtime; they
+  // reach the thread through the prefs host.
+  useEffect(() => {
+    if (!slashPrefs?.bindThreadExport) return;
+    slashPrefs.bindThreadExport(copyExport.exportConversation);
+  }, [slashPrefs, copyExport]);
+
+  const commands = useMemo(() => {
+    if (!enableSlash || !slashPrefs || !slashWiring) return [];
+    return slashWiring.buildCommands(slashPrefs).map((c) => {
+      if (c.id === "copy") return { ...c, execute: copyExport.copy };
+      if (c.id === "compact") {
+        return {
+          ...c,
+          execute: () => {
+            const md = serializeThreadMarkdown(transcriptTurns(aui.thread().getState().messages));
+            slashPrefs.reset();
+            slashPrefs.newThread();
+            if (!md.trim()) return;
+            queueMicrotask(() => {
+              aui.composer.setText(
+                `Summarize this conversation so we can continue with a smaller context.\n\n${md}`,
+              );
+              aui.composer.send();
+            });
+          },
+        };
+      }
+      const draft = slashWiring.paneDraft(c.id);
+      if (draft) {
+        return {
+          ...c,
+          execute: () => {
+            queueMicrotask(() => aui.composer.setText(draft));
+          },
+        };
+      }
+      if (slashWiring.shouldDraft(c.id, extra)) {
+        const inserted = `${c.label?.startsWith("/") ? c.label : `/${c.id}`} `;
+        return {
+          ...c,
+          execute: () => {
+            queueMicrotask(() => aui.composer.setText(inserted));
+          },
+        };
+      }
+      return c;
+    });
+    // `privateMode` is read inside `buildCommands` (the `/private` row's
+    // value) from a store, not from an argument: listing it here rebuilds the
+    // rows when it flips, so the palette shows the current value.
+    // eslint-disable-next-line react-hooks/exhaustive-deps
+  }, [enableSlash, slashPrefs, slashWiring, copyExport, aui, extra, privateMode]);
+
+  const slash = unstable_useSlashCommandAdapter({
+    commands,
+    removeOnExecute: true,
+  });
+  const slashTrigger = useMemo((): ThreadSlashTrigger => {
+    return {
+      adapter: slashWiring?.prefixAdapter(slash.adapter) ?? slash.adapter,
+      action: slash.action,
+      matcher: (text, _triggerChar, cursorPosition) => {
+        if (!slashWiring || cursorPosition <= 0) return null;
+        const frame = slashWiring.frame(text);
+        if (frame.kind !== "commands") return null;
+        return { query: frame.filter ?? "", offset: 0, endOffset: cursorPosition };
+      },
+    };
+  }, [slash, slashWiring]);
+
+  const mentionItems = useMemo(
+    () =>
+      (slashPrefs?.catalogTools ?? [])
+        .filter((t) => t.id !== "web_search" || Boolean(slashPrefs?.tenantAllowsWeb))
+        .map((t) => ({
+          id: t.id,
+          type: "tool",
+          label: t.label?.trim() || t.id,
+          description: `Use ${t.label?.trim() || t.id}`,
+        })),
+    [slashPrefs],
+  );
+  const mention = unstable_useMentionAdapter({
+    items: mentionItems,
+  });
+  const mentionTrigger = useMemo(
+    () =>
+      mentionItems.length
+        ? {
+            adapter: mention.adapter,
+            directive: mention.directive,
+          }
+        : undefined,
+    [mention, mentionItems.length],
+  );
+
+  const handleSubmit = useCallback(
+    (event: { preventDefault(): void }): boolean => {
+      if (slashPrefs && slashWiring) {
+        const text = aui.composer.getState().text;
+        const action = slashWiring.submitAction(text, extra);
+        if (action.kind === "block" || action.kind === "pane") {
+          event.preventDefault();
+          return true;
+        }
+        if (action.kind === "force") {
+          event.preventDefault();
+          if (gate?.shouldHold(action.text)) {
+            aui.composer.setText("");
+            void aui.composer.clearAttachments();
+            slashWiring.armForceTool(slashPrefs.sessionKey, action.forceTool, () => {
+              gate.onHold(action.text);
+            });
+            return true;
+          }
+          slashWiring.setForceTool(slashPrefs.sessionKey, action.forceTool);
+          aui.composer.setText(action.text);
+          gate?.onAllowSend?.();
+          aui.composer.send();
+          return true;
+        }
+        if (action.kind === "force-web") {
+          event.preventDefault();
+          // Tenant-gated arm (#3871): a deny tenant typing
+          // /websearch must not set the pending flag — same tenantAllowsWeb
+          // signal as the mention filter above. The BFF deny stays as backstop.
+          if (slashPrefs.tenantAllowsWeb) {
+            slashWiring.setWebSearchForce(slashPrefs.sessionKey, true);
+          }
+          if (gate?.shouldHold(action.text)) {
+            aui.composer.setText("");
+            void aui.composer.clearAttachments();
+            gate.onHold(action.text);
+            return true;
+          }
+          aui.composer.setText(action.text);
+          gate?.onAllowSend?.();
+          aui.composer.send();
+          return true;
+        }
+        if (action.kind === "run") {
+          event.preventDefault();
+          if (action.command.id === "copy") copyExport.copy();
+          else if (action.command.id === "export") {
+            applyExportSlash(action.arg, document, {
+              html: () => copyExport.exportConversation("html"),
+              markdown: () => copyExport.exportConversation("md"),
+            });
+          }
+          else if (action.command.id === "compact") {
+            // Palette compact serializes the thread and queues a summary.
+            // executeDef only resets prefs and opens an empty thread.
+            const compact = commands.find((command) => command.id === "compact");
+            if (compact) compact.execute();
+            else slashWiring.executeDef(action.command, action.arg, slashPrefs);
+          } else slashWiring.executeDef(action.command, action.arg, slashPrefs);
+          aui.composer.setText("");
+          return true;
+        }
+      }
+      return false;
+    },
+    [slashPrefs, slashWiring, aui, gate, copyExport, extra, commands],
+  );
+
+  return useMemo(
+    () => ({
+      enabled: enableSlash,
+      slash: enableSlash ? slashTrigger : undefined,
+      mention: enableSlash ? mentionTrigger : undefined,
+      handleSubmit,
+    }),
+    [enableSlash, slashTrigger, mentionTrigger, handleSubmit],
+  );
+}
+
+

package/src/components/chat/stock/skin-types.ts

@@ -0,0 +1,217 @@
+/**
+ * Shared skin/chrome value types for the package thread + skins.
+ *
+ * These are structural twins of the app's deploy-config literals
+ * (`ChromeModeSchema`, `PageContextModeSchema`, `UserAlignSchema` in
+ * `apps/digichat/src/lib/deploy-config/schema.ts`, `ChainDisclosureMode` in
+ * `apps/digichat/src/lib/view-modes.ts`). The app schema stays the single
+ * source of truth for config validation; this module keeps the presentation
+ * layer free of app imports (WS4).
+ */
+
+export type ChromeMode = "app" | "embed" | "modal" | "sidebar";
+
+export type PageContextMode = "off" | "silent" | "visible";
+
+export type UserAlign = "right" | "left";
+
+export type ChainDisclosureMode =
+  | "off"
+  | "collapsed"
+  | "balanced"
+  | "expanded";
+
+/**
+ * How much of the agent's work (reasoning + tool calls) a client wants its
+ * users to see. Structural twin of the app's `workVisibility` literal in
+ * `apps/digichat/src/lib/deploy-config/schema.ts`.
+ *
+ * - `quiet` — the chain is there, folded, and its header reads as a status
+ *   line ("Working — digisearch", "Used 3 tools"); the rows stay closed.
+ * - `balanced` — the chain is expanded while it runs, so the arguments and
+ *   the reasoning are visible, and collapses when it finishes.
+ * - `verbose` — the chain stays expanded; everything is readable.
+ *
+ * There is no `hidden` level any more: a client that wants the least reads
+ * the live status line and nothing else, which is `quiet`. Old values fold
+ * forward — see `LEGACY_VIEW_MODE_ALIASES` and `workVisibilityForView`.
+ */
+export type WorkVisibility = "quiet" | "balanced" | "verbose";
+
+/** What the disclosure policy resolves to for the thread components. */
+export type WorkDisclosure = {
+  /**
+   * A single summary line replaces the chain. The hidden level is gone, so
+   * this is always false now; it stays on the type while the thread renderer
+   * still holds the branch that reads it.
+   *
+   * @deprecated the chain folds to its titles instead (`quiet`).
+   */
+  summaryOnly: boolean;
+  /** The rows expand while their work streams. */
+  openWhileRunning: boolean;
+  /** The rows stay open once the work has finished. */
+  openAtRest: boolean;
+  /** Per-tool detail (arguments, results) is rendered. */
+  showDetails: boolean;
+  /**
+   * The chain folds as soon as the answer starts streaming, rather than
+   * waiting for the turn to end. The quiet level: the titles are there while
+   * the agent works, then they get out of the way of the answer.
+   */
+  foldOnAnswer: boolean;
+};
+
+/**
+ * The client-facing view level becomes the work visibility the thread uses.
+ * The retired `hidden` level means "the titles only, folded" now, so a host
+ * bundle still carrying it folds forward to `quiet`.
+ */
+export function workVisibilityForView(
+  view: ViewMode | undefined,
+): WorkVisibility {
+  switch (view) {
+    case "quiet":
+      return "quiet";
+    case "verbose":
+      return "verbose";
+    // Includes `balanced` and a host bundle that has not been rebuilt yet.
+    default:
+      return (view as string | undefined) === "hidden" ? "quiet" : "balanced";
+  }
+}
+
+/** The one place the visibility level becomes behaviour. */
+export function resolveWorkDisclosure(
+  visibility: WorkVisibility | undefined,
+): WorkDisclosure {
+  switch (visibility) {
+    // The titles only: the chain and its rows are there, folded. The folded
+    // header is the status line, so this is also the level that used to be
+    // called `hidden`.
+    case "quiet":
+      return {
+        summaryOnly: false,
+        openWhileRunning: false,
+        openAtRest: false,
+        showDetails: false,
+        foldOnAnswer: true,
+      };
+    // Open while the work streams, folded when the turn ends.
+    case "balanced":
+      return {
+        summaryOnly: false,
+        openWhileRunning: true,
+        openAtRest: false,
+        showDetails: true,
+        foldOnAnswer: false,
+      };
+    // Nothing ever folds: everything stays open and can be closed by hand.
+    case "verbose":
+      return {
+        summaryOnly: false,
+        openWhileRunning: true,
+        openAtRest: true,
+        showDetails: true,
+        foldOnAnswer: false,
+      };
+    default:
+      return {
+        summaryOnly: false,
+        openWhileRunning: true,
+        openAtRest: false,
+        showDetails: true,
+        foldOnAnswer: false,
+      };
+  }
+}
+
+/**
+ * Prefs value literals (WS4). Structural twins of `ViewMode` /
+ * `ThinkingMode` (`VIEW_MODES`, `THINKING_MODES` in
+ * `apps/digichat/src/lib/view-modes.ts`, defaults `"balanced"` / `"auto"`).
+ */
+export type ViewMode = "quiet" | "balanced" | "verbose";
+
+/**
+ * Retired view ids still found in saved prefs. `hidden` was the level that
+ * folded the trace to a single line — the chain folds to its titles and shows
+ * the same status line now, so it means `quiet`. `compact` was the
+ * closed-summary level (also now `quiet`); `detailed` was the fully-open one
+ * (now `verbose`). The app's `view-modes.ts` holds the twin of this map.
+ */
+export const LEGACY_VIEW_MODE_ALIASES = {
+  hidden: "quiet",
+  compact: "quiet",
+  detailed: "verbose",
+} as const;
+
+/** A current view id, a retired one folded forward, or the default. */
+export function normalizeViewPref(value: unknown): ViewMode {
+  if (value === "quiet" || value === "balanced" || value === "verbose") {
+    return value;
+  }
+  if (value === "hidden" || value === "compact") return "quiet";
+  if (value === "detailed") return "verbose";
+  return "balanced";
+}
+
+export type ThinkingMode = "auto" | "collapsed" | "open";
+
+/**
+ * Session MCP server config (WS4). Structural twin of `SessionMcpConfig` in
+ * `apps/digichat/src/components/stock/embed-mcp-flow.ts` (`auth` /
+ * `source` literals mirror `McpAuthKind` / `McpSource`). The app type stays
+ * the source of truth for BFF validation; identical shape keeps host values
+ * assignable across the boundary.
+ */
+export type SkinMcpServerConfig = {
+  id: string;
+  label: string;
+  url: string;
+  auth: "none" | "bearer" | "oauth";
+  token: string;
+  extra: Record<string, string>;
+  source: "operator" | "session";
+};
+
+/**
+ * Composer menu pane ids (WS4). Structural twin of `ComposerMenuKind` in
+ * `apps/digichat/src/components/stock/embed-composer-menu.tsx`.
+ */
+export type StockComposerMenuKind =
+  | "settings"
+  | "models"
+  | "mcp"
+  | "tools"
+  | "language"
+  | "effort"
+  | "search-engine"
+  | "view"
+  | "density"
+  | "theme"
+  | "thinking"
+  | "provider"
+  | "help"
+  | "export";
+
+const STOCK_COMPOSER_MENU_KINDS: readonly StockComposerMenuKind[] = [
+  "settings",
+  "models",
+  "mcp",
+  "tools",
+  "language",
+  "effort",
+  "search-engine",
+  "view",
+  "density",
+  "theme",
+  "thinking",
+  "provider",
+  "help",
+  "export",
+];
+
+export function isStockComposerMenuKind(value: string): value is StockComposerMenuKind {
+  return (STOCK_COMPOSER_MENU_KINDS as readonly string[]).includes(value);
+}