@kpritam/grimoire-output-docusaurus 0.1.8

package/templates/spellbook/src/components/SpellbookChat/ChatEngine.ts

@@ -0,0 +1,79 @@
+/**
+ * Shared contract between the text-chat panel and the voice-mode wrapper —
+ * both are React-rendered, in-browser, BYOK. `useChatEngine()` (in this
+ * folder) provides the canonical implementation.
+ */
+
+import type { Citation } from "./types";
+
+export type EngineLoadingState =
+  | "idle"
+  | "loading-bundle"
+  | "loading-model"
+  | "ready"
+  | "missing-key"
+  | "error";
+
+export interface StreamChunkEvent {
+  readonly text: string;
+}
+
+/**
+ * Why the stream ended. Surfaced on `AskResult` so the UI can distinguish
+ * "the model said its piece" from "we ran out of tokens" or "the request
+ * was cut off mid-flight". Maps 1:1 onto the AI SDK `finishReason` plus
+ * an explicit `"abort"` for client-side cancellation.
+ */
+export type AskFinishReason =
+  | "stop"
+  | "length"
+  | "tool-call"
+  | "error"
+  | "abort";
+
+/**
+ * One turn of the conversation as it should be replayed to the model on
+ * the next call. The current pending question is NOT part of this — it's
+ * passed separately to `ask`. This shape mirrors `ChatTurn` in the
+ * provider-stream contract so the engine can hand it through verbatim.
+ */
+export interface AskHistoryEntry {
+  readonly role: "user" | "assistant";
+  readonly content: string;
+}
+
+export interface AskResult {
+  readonly answer: string;
+  readonly citations: readonly Citation[];
+  readonly inputTokensApprox: number;
+  readonly outputTokensApprox: number;
+  readonly durationMs: number;
+  /** Why the stream stopped. Defaults to `"stop"` for clean completions. */
+  readonly finishReason: AskFinishReason;
+}
+
+export interface AskOptions {
+  readonly onToken?: (event: StreamChunkEvent) => void;
+  readonly signal?: AbortSignal;
+  /**
+   * Prior turns of the conversation, oldest first. Excludes the current
+   * pending `question`. The engine forwards this to the provider so the
+   * model can see context like "the second one" or "what about that file?".
+   */
+  readonly history?: readonly AskHistoryEntry[];
+}
+
+export interface ChatEngine {
+  readonly state: EngineLoadingState;
+  readonly statusMessage: string;
+  readonly error?: string;
+  readonly chunkCount: number;
+  readonly repo?: string;
+  readonly hasApiKey: boolean;
+  /** Streams tokens via `opts.onToken`. Rejects if not ready or call fails. */
+  readonly ask: (question: string, opts?: AskOptions) => Promise<AskResult>;
+  /** Idempotent lazy-load of bundle + model. */
+  readonly preload: () => void;
+}
+
+export type UseChatEngine = () => ChatEngine;

package/templates/spellbook/src/components/SpellbookChat/ChatErrorBoundary.tsx

@@ -0,0 +1,65 @@
+import { Component, type ErrorInfo, type ReactNode } from "react";
+
+import styles from "./styles.module.css";
+
+interface ChatErrorBoundaryProps {
+  readonly children: ReactNode;
+}
+
+interface ChatErrorBoundaryState {
+  readonly error: Error | null;
+}
+
+/**
+ * Isolates chat crashes so they don't take down the surrounding Docusaurus
+ * page. Renders a small recoverable error card inside the panel instead
+ * of letting React unwind to the outer ErrorBoundary.
+ *
+ * In dev we log the full error + stack to the console for debugging.
+ */
+export default class ChatErrorBoundary extends Component<
+  ChatErrorBoundaryProps,
+  ChatErrorBoundaryState
+> {
+  state: ChatErrorBoundaryState = { error: null };
+
+  static getDerivedStateFromError(error: Error): ChatErrorBoundaryState {
+    return { error };
+  }
+
+  componentDidCatch(error: Error, info: ErrorInfo): void {
+    if (typeof console !== "undefined") {
+      console.error("[chat] Panel crashed:", error, info.componentStack);
+    }
+  }
+
+  private reset = (): void => {
+    this.setState({ error: null });
+  };
+
+  render(): ReactNode {
+    if (!this.state.error) {
+      return this.props.children;
+    }
+    const message =
+      this.state.error.message || "Unknown error in the chat.";
+    return (
+      <div className={styles.errorBanner} role="alert">
+        <div>
+          <strong>The assistant stumbled.</strong>
+          <br />
+          {message}
+        </div>
+        <div className={styles.errorActions}>
+          <button
+            type="button"
+            className={styles.buttonPrimary}
+            onClick={this.reset}
+          >
+            Try again
+          </button>
+        </div>
+      </div>
+    );
+  }
+}

package/templates/spellbook/src/components/SpellbookChat/Markdown.tsx

@@ -0,0 +1,259 @@
+import { useCallback, useState, type ReactNode } from "react";
+import rehypeHighlight from "rehype-highlight";
+import remarkGfm from "remark-gfm";
+import { Streamdown, type Components } from "streamdown";
+
+import styles from "./markdown.module.css";
+
+interface MarkdownProps {
+  readonly source: string;
+  /**
+   * `true` while tokens are still arriving from the model. Streamdown uses
+   * this to enable incomplete-block parsing (so a half-emitted code fence
+   * doesn't render as broken markdown) and shows a subtle caret at the
+   * streaming edge. Cheap to leave `false` once the assistant finishes —
+   * the rendered output is identical once the markdown is complete.
+   */
+  readonly streaming?: boolean;
+}
+
+interface CodeBlockProps {
+  readonly className?: string;
+  readonly children: ReactNode;
+}
+
+/**
+ * Standalone fenced code block with language tag + copy-to-clipboard button.
+ * Styling lives in `markdown.module.css`; theming overrides live alongside.
+ */
+function CodeBlock(props: CodeBlockProps): ReactNode {
+  const { className = "", children } = props;
+  const langMatch = /language-(\w+)/.exec(className);
+  const language = langMatch?.[1] ?? "";
+  const [copied, setCopied] = useState(false);
+
+  const onCopy = useCallback(() => {
+    const text = extractText(children);
+    if (!text) {
+      return;
+    }
+    navigator.clipboard
+      ?.writeText(text)
+      .then(() => {
+        setCopied(true);
+        window.setTimeout(() => setCopied(false), 1400);
+      })
+      .catch(() => {
+        // ignore — likely insecure context
+      });
+  }, [children]);
+
+  return (
+    <div className={styles.codeBlock}>
+      <div className={styles.codeBlockHeader}>
+        <span className={styles.codeBlockLang}>{language || "code"}</span>
+        <button
+          type="button"
+          className={styles.codeCopyButton}
+          onClick={onCopy}
+          aria-label="Copy code"
+        >
+          {copied ? "Copied" : "Copy"}
+        </button>
+      </div>
+      <pre className={styles.codeBlockPre}>
+        <code className={`${className} ${styles.codeBlockCode}`}>
+          {children}
+        </code>
+      </pre>
+    </div>
+  );
+}
+
+function extractText(node: ReactNode): string {
+  if (typeof node === "string") {
+    return node;
+  }
+  if (typeof node === "number") {
+    return String(node);
+  }
+  if (Array.isArray(node)) {
+    return node.map(extractText).join("");
+  }
+  if (
+    node &&
+    typeof node === "object" &&
+    "props" in node &&
+    (node as { props?: { children?: ReactNode } }).props
+  ) {
+    return extractText(
+      (node as { props: { children?: ReactNode } }).props.children,
+    );
+  }
+  return "";
+}
+
+const componentMap: Components = {
+  code(props) {
+    const { className, children } = props as {
+      className?: string;
+      children?: ReactNode;
+    };
+    const isInline = !/language-/.test(className ?? "");
+    if (isInline) {
+      return <code className={styles.inlineCode}>{children}</code>;
+    }
+    return <CodeBlock className={className}>{children}</CodeBlock>;
+  },
+  pre(props) {
+    return <>{(props as { children?: ReactNode }).children}</>;
+  },
+  a(props) {
+    const { href = "", children, ...rest } = props as {
+      href?: string;
+      children?: ReactNode;
+    } & Record<string, unknown>;
+    // Defense-in-depth: answers are markdown from a third-party LLM and
+    // must never execute as JavaScript. Allow only http(s), anchors, and
+    // relative paths; anything else (javascript:, data:, vbscript:, etc.)
+    // is stripped to a non-link span.
+    const safeHref = (() => {
+      const t = href.trim();
+      if (t === "") return undefined;
+      if (t.startsWith("#") || t.startsWith("/") || t.startsWith("./")) {
+        return t;
+      }
+      if (/^https?:\/\//i.test(t)) {
+        return t;
+      }
+      return undefined;
+    })();
+    if (!safeHref) {
+      return <span className={styles.link}>{children}</span>;
+    }
+    const external = /^https?:\/\//i.test(safeHref);
+    return (
+      <a
+        {...(rest as Record<string, unknown>)}
+        href={safeHref}
+        className={styles.link}
+        target={external ? "_blank" : undefined}
+        rel={external ? "noreferrer noopener" : undefined}
+      >
+        {children}
+      </a>
+    );
+  },
+  table(props) {
+    return (
+      <div className={styles.tableWrap}>
+        <table className={styles.table}>
+          {(props as { children?: ReactNode }).children}
+        </table>
+      </div>
+    );
+  },
+  blockquote(props) {
+    return (
+      <blockquote className={styles.blockquote}>
+        {(props as { children?: ReactNode }).children}
+      </blockquote>
+    );
+  },
+  ul(props) {
+    return (
+      <ul className={styles.list}>
+        {(props as { children?: ReactNode }).children}
+      </ul>
+    );
+  },
+  ol(props) {
+    return (
+      <ol className={styles.list}>
+        {(props as { children?: ReactNode }).children}
+      </ol>
+    );
+  },
+  li(props) {
+    return (
+      <li className={styles.listItem}>
+        {(props as { children?: ReactNode }).children}
+      </li>
+    );
+  },
+  h1(props) {
+    return (
+      <h3 className={styles.heading}>
+        {(props as { children?: ReactNode }).children}
+      </h3>
+    );
+  },
+  h2(props) {
+    return (
+      <h3 className={styles.heading}>
+        {(props as { children?: ReactNode }).children}
+      </h3>
+    );
+  },
+  h3(props) {
+    return (
+      <h4 className={styles.subheading}>
+        {(props as { children?: ReactNode }).children}
+      </h4>
+    );
+  },
+  h4(props) {
+    return (
+      <h4 className={styles.subheading}>
+        {(props as { children?: ReactNode }).children}
+      </h4>
+    );
+  },
+  hr() {
+    return <hr className={styles.rule} />;
+  },
+  p(props) {
+    return (
+      <p className={styles.paragraph}>
+        {(props as { children?: ReactNode }).children}
+      </p>
+    );
+  },
+};
+
+/**
+ * Streaming-aware markdown renderer.
+ *
+ * Built on Vercel's `streamdown`, which handles **incomplete markdown blocks**
+ * gracefully (so a half-emitted code fence won't render as broken HTML
+ * mid-stream) and ships `rehype-harden` for safer rendering of LLM output.
+ * We override the default elements via `components` to keep the chat panel's
+ * visual style consistent with the rest of the docs.
+ *
+ * `streaming={true}` enables the unterminated-block handling and the
+ * subtle caret indicator at the live edge. Pass `false` for finalised
+ * messages — the output is identical, just without the streaming hints.
+ */
+export default function Markdown({
+  source,
+  streaming = false,
+}: MarkdownProps): ReactNode {
+  if (!source) {
+    return null;
+  }
+  return (
+    <div className={styles.root}>
+      <Streamdown
+        mode={streaming ? "streaming" : "static"}
+        parseIncompleteMarkdown={streaming}
+        remarkPlugins={[remarkGfm]}
+        rehypePlugins={[
+          [rehypeHighlight, { detect: true, ignoreMissing: true }],
+        ]}
+        components={componentMap}
+      >
+        {source}
+      </Streamdown>
+    </div>
+  );
+}

package/templates/spellbook/src/components/SpellbookChat/README.md

@@ -0,0 +1,111 @@
+# Chat — in-browser RAG over the documentation
+
+A static-site chat panel that runs **entirely in the user's browser**:
+
+- no backend, no edge function, no infra cost to the project owner
+- **BYOK** — users bring their own API keys for cloud models; keys live in
+  tab memory only (cleared on refresh, never written to disk)
+- optional **fully local** inference with **WebLLM** (WebGPU, no keys)
+- private by default — cloud calls go straight from the user's browser to
+  the provider they chose
+
+## Architecture
+
+```
+┌──────────────────────────────────────────────────────────────────────┐
+│  Build time — packages/core/IndexBuilder                             │
+│    • walks tome/**/*.md, chunks by heading + ~512 tokens             │
+│    • embeds chunks with @huggingface/transformers (onnx-community MiniLM-L6-v2, 384-dim) │
+│    • writes the static bundle under                                  │
+│        tome/site/static/grimoire-index/                              │
+│          chunks.json     (array<ChunkRecord>)                        │
+│          vectors.bin     (Float32Array, packed little-endian)        │
+│          manifest.json   (BundleManifest — also carries siteName,    │
+│                          siteTagline, repo so the chat persona is    │
+│                          project-aware)                              │
+└──────────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────────┐
+│  Browser runtime — SpellbookChat panel + ChatEngine                  │
+│    1. User picks a provider + model in Settings                      │
+│         • Provider id, model, base URL → localStorage                │
+│         • API key → secretStore.ts (memory only; never on disk)      │
+│    2. lazy-load chunks.json + vectors.bin + embedding model (WASM)   │
+│    3. Optional: WebLLM preloads model weights (IndexedDB cache)      │
+│    4. on each question: embed query locally → top-k chunks →         │
+│       stream completion via the active StreamProvider                │
+└──────────────────────────────────────────────────────────────────────┘
+
+┌──────────────────────────────────────────────────────────────────────┐
+│  Voice mode — VoiceMode wrapper                                      │
+│    • mic button → unified STT (Web Speech API, Whisper fallback)     │
+│    • call ChatEngine.ask(text, { signal, onToken })                  │
+│    • each sentence is streamed through SpeechSynthesis as it arrives │
+│    • cancel() via ref kills the ask + TTS together; the panel calls  │
+│      it on Close, Clear, and mode-switch to Type                     │
+└──────────────────────────────────────────────────────────────────────┘
+```
+
+## LLM providers (`streamProviders/`)
+
+All implement the shared `StreamProvider` contract (`streamProviders/types.ts`).
+
+| Provider | How it runs | What the user configures |
+| --- | --- | --- |
+| **Anthropic** | Browser → Anthropic API (CORS header set) | API key; model from built-in list |
+| **OpenAI** | Browser → OpenAI API | API key; model from built-in list |
+| **Google Gemini** | Browser → Generative Language API | API key; model from built-in list |
+| **Ollama / OpenAI-compatible** | Browser → user's server (e.g. `http://localhost:11434/v1`) | Base URL (optional); model name (presets + **custom**). Requires CORS on the server (e.g. `OLLAMA_ORIGINS`). |
+| **WebLLM** | Model runs in the tab (WebGPU); weights cached locally | Model choice only. Needs a **WebGPU**-capable browser. SSR builds alias `@mlc-ai/web-llm` to a stub so Docusaurus can prerender. |
+
+## Storage layout
+
+| What | Where | Why |
+| --- | --- | --- |
+| Active provider id | `localStorage["grimoire.chat.provider"]` | Non-secret preference |
+| Model / baseUrl per provider | `localStorage["grimoire.chat.<id>.{model,baseUrl}"]` | Non-secret preferences |
+| **API key** | in-memory (`secretStore.ts`) | Cleared on tab refresh — no plaintext secret on disk |
+
+On first load `secretStore.purgeLegacyKeyStorage()` deletes any plaintext
+API keys a previous build persisted, so returning users don't carry
+credentials forward on disk.
+
+## Files in this directory
+
+| File | Purpose |
+| --- | --- |
+| `types.ts` | Bundle schema (`ChunkRecord`, `BundleManifest`, `RetrievedChunk`) |
+| `ChatEngine.ts` | Engine interface shared by panel + voice mode |
+| `streamProviders/*.ts` | Per-provider streaming (Vercel AI SDK + WebLLM) |
+| `index.tsx` | Main chat panel React component |
+| `useChatEngine.ts` | React hook that implements the engine |
+| `systemPrompt.ts` | Project-aware persona + grounded RAG prompt |
+| `secretStore.ts` | In-memory API key store (no persistence) |
+| `useEmbeddings.ts` | Loads + runs the in-browser embedding model |
+| `useRetrieval.ts` | Cosine-sim against shipped vectors |
+| `SettingsPanel.tsx` | Provider + model + key settings |
+| `VoiceMode.tsx` | Mic button + STT/TTS wrapper with imperative cancel |
+| `useSpeechRecognition.ts` | Web Speech API STT hook |
+| `useSpeechSynthesis.ts` | Web Speech API TTS hook (cancels on unmount) |
+| `useUnifiedSTT.ts` | Unified native + Whisper-fallback STT |
+| `useWhisperSTT.ts` | In-browser Whisper STT hook |
+| `voiceDebug.ts` | Opt-in voice pipeline logger (silent by default) |
+| `styles.module.css` | Panel styles |
+| `voiceStyles.module.css` | Voice-mode styles |
+| `webllm-ssr-stub.ts` | SSR stub for `@mlc-ai/web-llm` |
+| `transformers-ssr-stub.ts` | SSR stub for `@huggingface/transformers` |
+
+`types.ts` and `ChatEngine.ts` are the only cross-cutting contracts.
+
+## Debug logging
+
+The voice pipeline is chatty during development. To enable transcript-level
+traces in production:
+
+```js
+localStorage.setItem("grimoire.chat.debug", "1");
+location.reload();
+```
+
+The flag is read once on module load. Logs include a truncated transcript
+preview (first 80 chars) but never the raw API key or full answer.