@kpritam/grimoire-output-docusaurus 0.1.8

package/templates/spellbook/src/components/SpellbookChat/markdown.module.css

@@ -0,0 +1,343 @@
+/* Markdown rendering for SpellbookChat assistant messages.
+   Theming follows the grimoire dark palette (violet + candlelight gold). */
+
+.root {
+  display: flex;
+  flex-direction: column;
+  gap: 0.6em;
+  font-family: var(--grim-font-chat);
+  font-size: 0.92rem;
+  line-height: 1.6;
+  color: var(--grim-text);
+  word-break: break-word;
+}
+
+.root > *:first-child {
+  margin-top: 0;
+}
+
+.root > *:last-child {
+  margin-bottom: 0;
+}
+
+.paragraph {
+  margin: 0;
+}
+
+.heading {
+  margin: 0.4em 0 0.1em;
+  font-family: var(--grim-font-display);
+  font-weight: 600;
+  font-size: 1.05rem;
+  letter-spacing: 0;
+  color: var(--grim-text);
+}
+
+.subheading {
+  margin: 0.4em 0 0.1em;
+  font-family: var(--grim-font-display);
+  font-weight: 600;
+  font-size: 0.98rem;
+  color: var(--grim-text);
+}
+
+.list {
+  margin: 0;
+  padding-left: 1.25rem;
+  display: flex;
+  flex-direction: column;
+  gap: 0.2em;
+}
+
+.listItem {
+  padding-left: 0.1rem;
+}
+
+.listItem::marker {
+  color: var(--grim-violet);
+}
+
+.link {
+  color: var(--grim-gold);
+  text-decoration: underline;
+  text-decoration-color: oklch(0.74 0.15 70 / 0.45);
+  text-underline-offset: 2px;
+  transition: text-decoration-color 120ms ease;
+}
+
+.link:hover {
+  text-decoration-color: var(--grim-gold);
+}
+
+.blockquote {
+  margin: 0;
+  padding: 0.4em 0.9em;
+  border-left: 2px solid var(--grim-violet);
+  background: oklch(0.18 0.04 285 / 0.6);
+  border-radius: 0 var(--grim-radius-sm) var(--grim-radius-sm) 0;
+  color: var(--grim-text-muted);
+  font-style: italic;
+}
+
+.rule {
+  border: none;
+  border-top: 1px solid var(--grim-rule);
+  margin: 0.6em 0;
+}
+
+.tableWrap {
+  width: 100%;
+  overflow-x: auto;
+  border-radius: var(--grim-radius-sm);
+  border: 1px solid var(--grim-rule);
+}
+
+.table {
+  width: 100%;
+  border-collapse: collapse;
+  font-size: 0.85rem;
+}
+
+.table th,
+.table td {
+  padding: 0.4em 0.7em;
+  text-align: left;
+  border-bottom: 1px solid var(--grim-rule);
+}
+
+.table th {
+  background: var(--grim-surface);
+  font-weight: 600;
+  color: var(--grim-text);
+  letter-spacing: 0.02em;
+}
+
+.table tr:last-child td {
+  border-bottom: none;
+}
+
+/* ---------- Inline code ---------- */
+
+.inlineCode {
+  font-family: var(--grim-font-mono);
+  font-size: 0.85em;
+  padding: 0.06em 0.4em;
+  border-radius: 4px;
+  background: oklch(0.22 0.03 285 / 0.85);
+  border: 1px solid var(--grim-rule);
+  color: var(--grim-gold);
+}
+
+/* ---------- Fenced code blocks ---------- */
+
+.codeBlock {
+  margin: 0.1em 0;
+  border-radius: var(--grim-radius-md);
+  border: 1px solid var(--grim-rule);
+  background: oklch(0.12 0.025 282);
+  overflow: hidden;
+}
+
+.codeBlockHeader {
+  display: flex;
+  align-items: center;
+  justify-content: space-between;
+  padding: 0.35em 0.7em;
+  background: oklch(0.16 0.028 282);
+  border-bottom: 1px solid var(--grim-rule);
+  font-family: var(--grim-font-ui);
+  font-size: 0.7rem;
+}
+
+.codeBlockLang {
+  text-transform: uppercase;
+  letter-spacing: 0.08em;
+  color: var(--grim-text-subtle);
+}
+
+.codeCopyButton {
+  appearance: none;
+  border: none;
+  background: transparent;
+  color: var(--grim-text-muted);
+  font-family: var(--grim-font-ui);
+  font-size: 0.7rem;
+  letter-spacing: 0.04em;
+  cursor: pointer;
+  padding: 0.15em 0.5em;
+  border-radius: 4px;
+  transition: color 120ms ease, background 120ms ease;
+}
+
+.codeCopyButton:hover {
+  color: var(--grim-gold);
+  background: oklch(0.22 0.03 285);
+}
+
+.codeBlockPre {
+  margin: 0;
+  padding: 0.75em 0.9em;
+  overflow-x: auto;
+  font-family: var(--grim-font-mono);
+  font-size: 0.82rem;
+  line-height: 1.55;
+  background: transparent;
+}
+
+.codeBlockCode {
+  background: transparent !important;
+  padding: 0 !important;
+  border-radius: 0 !important;
+  border: none !important;
+  color: var(--grim-text);
+  font-family: inherit;
+  font-size: inherit;
+  white-space: pre;
+}
+
+/* ---------- highlight.js dark theme overrides ---------- */
+/* Scoped via :global so highlight.js's emitted classes apply only inside .root */
+
+.root :global(.hljs) {
+  color: var(--grim-text);
+  background: transparent;
+}
+
+.root :global(.hljs-comment),
+.root :global(.hljs-quote) {
+  color: oklch(0.55 0.025 285);
+  font-style: italic;
+}
+
+.root :global(.hljs-keyword),
+.root :global(.hljs-selector-tag),
+.root :global(.hljs-tag) {
+  color: oklch(0.78 0.16 300);
+}
+
+.root :global(.hljs-string),
+.root :global(.hljs-attr),
+.root :global(.hljs-meta-string) {
+  color: oklch(0.85 0.13 78);
+}
+
+.root :global(.hljs-number),
+.root :global(.hljs-literal),
+.root :global(.hljs-built_in),
+.root :global(.hljs-type) {
+  color: oklch(0.82 0.16 200);
+}
+
+.root :global(.hljs-title),
+.root :global(.hljs-name),
+.root :global(.hljs-section) {
+  color: oklch(0.88 0.12 100);
+}
+
+.root :global(.hljs-variable),
+.root :global(.hljs-template-variable),
+.root :global(.hljs-property) {
+  color: oklch(0.92 0.04 290);
+}
+
+.root :global(.hljs-symbol),
+.root :global(.hljs-bullet),
+.root :global(.hljs-link) {
+  color: var(--grim-violet);
+}
+
+.root :global(.hljs-deletion) {
+  color: oklch(0.7 0.16 28);
+}
+
+.root :global(.hljs-addition) {
+  color: oklch(0.78 0.18 145);
+}
+
+.root :global(.hljs-emphasis) {
+  font-style: italic;
+}
+
+.root :global(.hljs-strong) {
+  font-weight: 600;
+}
+
+/* =============================================================
+   LIGHT THEME OVERRIDES — surfaces and syntax colours above are
+   dark-palette only; correct them here.
+   ============================================================= */
+
+:global([data-theme="light"]) .link {
+  text-decoration-color: color-mix(in oklch, var(--grim-gold) 45%, transparent);
+}
+
+:global([data-theme="light"]) .listItem::marker {
+  color: var(--grim-violet-deep);
+}
+
+:global([data-theme="light"]) .blockquote {
+  background: color-mix(in oklch, var(--grim-violet) 8%, var(--grim-surface));
+}
+
+:global([data-theme="light"]) .inlineCode {
+  background: var(--grim-code-bg);
+  color: var(--grim-violet-deep);
+  border-color: color-mix(in oklch, var(--grim-violet) 20%, var(--grim-rule));
+}
+
+:global([data-theme="light"]) .codeBlock {
+  background: var(--grim-code-bg);
+}
+
+:global([data-theme="light"]) .codeBlockHeader {
+  background: var(--grim-surface-2);
+}
+
+:global([data-theme="light"]) .codeCopyButton:hover {
+  background: var(--grim-surface-3);
+}
+
+/* Light theme: remap hljs syntax colours for a light code background */
+:global([data-theme="light"]) .root :global(.hljs-comment),
+:global([data-theme="light"]) .root :global(.hljs-quote) {
+  color: oklch(0.56 0.03 285);
+}
+
+:global([data-theme="light"]) .root :global(.hljs-keyword),
+:global([data-theme="light"]) .root :global(.hljs-selector-tag),
+:global([data-theme="light"]) .root :global(.hljs-tag) {
+  color: oklch(0.45 0.22 298);
+}
+
+:global([data-theme="light"]) .root :global(.hljs-string),
+:global([data-theme="light"]) .root :global(.hljs-attr),
+:global([data-theme="light"]) .root :global(.hljs-meta-string) {
+  color: oklch(0.5 0.15 58);
+}
+
+:global([data-theme="light"]) .root :global(.hljs-number),
+:global([data-theme="light"]) .root :global(.hljs-literal),
+:global([data-theme="light"]) .root :global(.hljs-built_in),
+:global([data-theme="light"]) .root :global(.hljs-type) {
+  color: oklch(0.48 0.18 210);
+}
+
+:global([data-theme="light"]) .root :global(.hljs-title),
+:global([data-theme="light"]) .root :global(.hljs-name),
+:global([data-theme="light"]) .root :global(.hljs-section) {
+  color: oklch(0.48 0.15 88);
+}
+
+:global([data-theme="light"]) .root :global(.hljs-variable),
+:global([data-theme="light"]) .root :global(.hljs-template-variable),
+:global([data-theme="light"]) .root :global(.hljs-property) {
+  color: oklch(0.4 0.03 285);
+}
+
+:global([data-theme="light"]) .root :global(.hljs-deletion) {
+  color: oklch(0.48 0.2 25);
+}
+
+:global([data-theme="light"]) .root :global(.hljs-addition) {
+  color: oklch(0.44 0.2 148);
+}

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

@@ -0,0 +1,106 @@
+/**
+ * In-memory store for chat API keys.
+ *
+ * Keys live ONLY in the running tab's memory — never in localStorage,
+ * sessionStorage, IndexedDB, cookies, or any other persistent surface.
+ * Refreshing the page, opening a new tab, or closing the browser drops
+ * every key. This is a deliberate security trade-off: users pay a one-time
+ * re-entry cost per session for a drastically smaller attack surface
+ * (no XSS-readable keys, no extensions that snoop storage, no keys left
+ * behind on a shared device).
+ *
+ * Everything non-secret (active provider id, chosen model, base URL) still
+ * lives in localStorage — those are low-risk preferences, not credentials.
+ *
+ * Subscribers can listen to `onChange(id)` to re-run `validateConfig`
+ * whenever the user types or clears a key.
+ */
+
+import type { ProviderId } from "./streamProviders/types";
+
+type Listener = (id: ProviderId) => void;
+
+const secrets = new Map<ProviderId, string>();
+const listeners = new Set<Listener>();
+
+/**
+ * Read the secret for a provider. Returns `undefined` when the user hasn't
+ * entered one yet or after they clear it.
+ */
+export function getSecret(id: ProviderId): string | undefined {
+  const v = secrets.get(id);
+  return v && v.length > 0 ? v : undefined;
+}
+
+/**
+ * Store a secret in memory. Empty/whitespace values clear the secret
+ * (equivalent to `clearSecret(id)`).
+ */
+export function setSecret(id: ProviderId, value: string): void {
+  const trimmed = value.trim();
+  if (trimmed.length === 0) {
+    if (!secrets.has(id)) return;
+    secrets.delete(id);
+  } else {
+    if (secrets.get(id) === trimmed) return;
+    secrets.set(id, trimmed);
+  }
+  for (const fn of listeners) {
+    try {
+      fn(id);
+    } catch {
+      // Listener failures must not prevent other listeners firing or the
+      // secret from being updated; subsequent calls will re-notify.
+    }
+  }
+}
+
+export function clearSecret(id: ProviderId): void {
+  setSecret(id, "");
+}
+
+export function hasSecret(id: ProviderId): boolean {
+  return getSecret(id) !== undefined;
+}
+
+export function onSecretChange(fn: Listener): () => void {
+  listeners.add(fn);
+  return () => {
+    listeners.delete(fn);
+  };
+}
+
+/**
+ * Migration helper: wipes any legacy API keys from localStorage that a
+ * previous version of the chat had persisted, so returning users don't
+ * carry plaintext credentials around on disk. Runs exactly once per tab
+ * (guarded by `migrated`).
+ *
+ * Call this from the chat bootstrap (useChatEngine) — it's a one-shot
+ * side-effect, not something to call on every render.
+ */
+let migrated = false;
+export function purgeLegacyKeyStorage(): void {
+  if (migrated) return;
+  migrated = true;
+  if (typeof localStorage === "undefined") return;
+  // Any key whose last segment is `apiKey`, plus the pre-generic
+  // namespace Grimoire used during early previews. The list is explicit
+  // rather than a regex so we never accidentally delete user preferences.
+  const doomed = [
+    "grimoire.spellbook.anthropic-key",
+    "grimoire.spellbook.anthropic.apiKey",
+    "grimoire.spellbook.openai.apiKey",
+    "grimoire.spellbook.google.apiKey",
+    "grimoire.chat.anthropic.apiKey",
+    "grimoire.chat.openai.apiKey",
+    "grimoire.chat.google.apiKey",
+  ];
+  for (const key of doomed) {
+    try {
+      localStorage.removeItem(key);
+    } catch {
+      // Private browsing / storage quota — silently skip.
+    }
+  }
+}

package/templates/spellbook/src/components/SpellbookChat/streamProviders/anthropic.ts

@@ -0,0 +1,36 @@
+import { createAnthropic } from "@ai-sdk/anthropic";
+
+import { createCloudProvider } from "./createCloudProvider";
+
+export const anthropicProvider = createCloudProvider({
+  id: "anthropic",
+  displayName: "Anthropic Claude",
+  tagline: "Cloud · BYOK · Claude 4.5–4.7 family",
+  models: [
+    { id: "claude-sonnet-4-6", label: "Claude Sonnet 4.6", note: "balanced" },
+    { id: "claude-opus-4-7", label: "Claude Opus 4.7", note: "smart" },
+    { id: "claude-haiku-4-5", label: "Claude Haiku 4.5", note: "fast" },
+    { id: "claude-sonnet-4-5-20250929", label: "Claude Sonnet 4.5" },
+    { id: "claude-opus-4-6", label: "Claude Opus 4.6" },
+    { id: "claude-3-5-haiku-latest", label: "Claude 3.5 Haiku", note: "legacy" },
+  ],
+  configFields: [
+    {
+      key: "apiKey",
+      label: "Anthropic API key",
+      placeholder: "sk-ant-…",
+      helpText:
+        "Get one at console.anthropic.com. Kept in this tab's memory only (cleared on refresh). Calls go directly from your browser to Anthropic (CORS header enabled).",
+      required: true,
+      secret: true,
+    },
+  ],
+  validateConfig: (cfg) => (!cfg.apiKey?.trim() ? "API key required" : null),
+  resolveModel: (cfg) => {
+    const client = createAnthropic({
+      apiKey: cfg.apiKey!,
+      headers: { "anthropic-dangerous-direct-browser-access": "true" },
+    });
+    return client(cfg.model);
+  },
+});

package/templates/spellbook/src/components/SpellbookChat/streamProviders/createCloudProvider.ts

@@ -0,0 +1,112 @@
+import { type LanguageModel, streamText } from "ai";
+
+import { mapFinishReason } from "./mapFinishReason";
+import type {
+  ConfigField,
+  ModelOption,
+  PreloadProgress,
+  ProviderConfig,
+  ProviderId,
+  StreamEvent,
+  StreamProvider,
+  StreamRequest,
+} from "./types";
+
+/**
+ * How many times the AI SDK should retry a failed network call before
+ * giving up. Cloud LLM endpoints are flaky enough — especially during
+ * model rollouts — that bumping this from the SDK default of 2 to 3 has
+ * a measurable user-experience impact and costs nothing on the happy
+ * path. The signal still aborts the whole pipeline including retries.
+ */
+const STREAM_MAX_RETRIES = 3;
+
+export interface CloudProviderSpec {
+  readonly id: ProviderId;
+  readonly displayName: string;
+  readonly tagline: string;
+  readonly models: readonly ModelOption[];
+  readonly configFields: readonly ConfigField[];
+  readonly validateConfig: (cfg: ProviderConfig) => string | null;
+  /**
+   * Build a `LanguageModel` for the given config. Provider-specific (creates
+   * the SDK client, applies headers, picks `chat` vs `chatModel`).
+   */
+  readonly resolveModel: (cfg: ProviderConfig) => LanguageModel;
+  /** Optional warm-up. Cloud providers usually leave this undefined. */
+  readonly preload?: (
+    config: ProviderConfig,
+    onProgress?: (info: PreloadProgress) => void,
+  ) => Promise<void>;
+}
+
+/**
+ * Single source of truth for the streaming loop every cloud provider runs:
+ *   1. Build a `LanguageModel` via the spec's `resolveModel`.
+ *   2. Hand it to the AI SDK's `streamText` with our shared retry, abort
+ *      and decoding settings.
+ *   3. Forward `text-delta` events as they arrive, then a `finish` with
+ *      mapped reason + token usage.
+ *
+ * Adding a new cloud provider is now a ~15-line metadata block instead of
+ * 70 lines of nearly-identical glue. Provider-specific quirks
+ * (`anthropic-dangerous-direct-browser-access`, OpenAI-compatible base URL,
+ * etc.) live entirely inside `resolveModel`.
+ */
+export function createCloudProvider(spec: CloudProviderSpec): StreamProvider {
+  return {
+    id: spec.id,
+    displayName: spec.displayName,
+    tagline: spec.tagline,
+    models: spec.models,
+    configFields: spec.configFields,
+    validateConfig: spec.validateConfig,
+    preload: spec.preload,
+    async *stream(
+      req: StreamRequest,
+      cfg: ProviderConfig,
+    ): AsyncIterable<StreamEvent> {
+      const model = spec.resolveModel(cfg);
+
+      const result = streamText({
+        model,
+        system: req.system,
+        messages: req.messages.map((m) => ({
+          role: m.role,
+          content: m.content,
+        })),
+        maxOutputTokens: req.maxTokens ?? 1024,
+        temperature: req.temperature ?? 0.4,
+        abortSignal: req.signal,
+        maxRetries: STREAM_MAX_RETRIES,
+      });
+
+      try {
+        for await (const delta of result.textStream) {
+          yield { type: "text-delta", text: delta };
+        }
+      } catch (err) {
+        // The async iterator can throw if the underlying fetch was aborted
+        // mid-flight. Surface that as a clean abort finish so the engine
+        // doesn't bubble an `AbortError` past `useChatEngine`.
+        if (
+          req.signal?.aborted ||
+          (err as Error)?.name === "AbortError"
+        ) {
+          yield { type: "finish", finishReason: "abort" };
+          return;
+        }
+        throw err;
+      }
+
+      const finishReasonRaw = await result.finishReason;
+      const usage = await result.usage;
+      yield {
+        type: "finish",
+        finishReason: mapFinishReason(finishReasonRaw),
+        inputTokens: usage?.inputTokens,
+        outputTokens: usage?.outputTokens,
+      };
+    },
+  };
+}

package/templates/spellbook/src/components/SpellbookChat/streamProviders/google.ts

@@ -0,0 +1,33 @@
+import { createGoogleGenerativeAI } from "@ai-sdk/google";
+
+import { createCloudProvider } from "./createCloudProvider";
+
+export const googleProvider = createCloudProvider({
+  id: "google",
+  displayName: "Google Gemini",
+  tagline: "Cloud · BYOK · Gemini 3 & 2.5",
+  models: [
+    { id: "gemini-3.1-pro-preview", label: "Gemini 3.1 Pro", note: "preview" },
+    { id: "gemini-3-flash-preview", label: "Gemini 3 Flash", note: "preview" },
+    { id: "gemini-2.5-pro", label: "Gemini 2.5 Pro", note: "smart" },
+    { id: "gemini-2.5-flash", label: "Gemini 2.5 Flash", note: "fast" },
+    { id: "gemini-2.5-flash-lite", label: "Gemini 2.5 Flash-Lite", note: "budget" },
+    { id: "gemini-2.0-flash", label: "Gemini 2.0 Flash", note: "deprecated" },
+  ],
+  configFields: [
+    {
+      key: "apiKey",
+      label: "Google AI API key",
+      placeholder: "AI…",
+      helpText:
+        "Create a key in Google AI Studio (aistudio.google.com). Kept in this tab's memory only (cleared on refresh).",
+      required: true,
+      secret: true,
+    },
+  ],
+  validateConfig: (cfg) => (!cfg.apiKey?.trim() ? "API key required" : null),
+  resolveModel: (cfg) => {
+    const google = createGoogleGenerativeAI({ apiKey: cfg.apiKey! });
+    return google.chat(cfg.model);
+  },
+});

package/templates/spellbook/src/components/SpellbookChat/streamProviders/index.ts

@@ -0,0 +1,32 @@
+import type {
+  PreloadProgress,
+  ProviderConfig,
+  ProviderId,
+  ProviderRegistry,
+  StreamEvent,
+  StreamProvider,
+  StreamRequest,
+} from "./types";
+
+export const PROVIDERS: ProviderRegistry = {
+  anthropic: () => import("./anthropic").then((m) => m.anthropicProvider),
+  openai: () => import("./openai").then((m) => m.openaiProvider),
+  "openai-realtime": () =>
+    import("./openaiRealtime").then((m) => m.openaiRealtimeProvider),
+  google: () => import("./google").then((m) => m.googleProvider),
+  ollama: () => import("./ollama").then((m) => m.ollamaProvider),
+  webllm: () => import("./webllm").then((m) => m.webllmProvider),
+};
+
+export async function loadProvider(id: ProviderId): Promise<StreamProvider> {
+  return PROVIDERS[id]();
+}
+
+export type {
+  PreloadProgress,
+  ProviderConfig,
+  ProviderId,
+  StreamEvent,
+  StreamProvider,
+  StreamRequest,
+};

package/templates/spellbook/src/components/SpellbookChat/streamProviders/mapFinishReason.ts

@@ -0,0 +1,23 @@
+import type { StreamEvent } from "./types";
+
+/**
+ * Normalize the `ai` SDK's free-form `finishReason` string into the closed
+ * union our `StreamProvider` contract emits. Shared by every cloud provider
+ * (`anthropic`, `openai`, `google`, `ollama`) so the mapping is defined once.
+ *
+ * Unknown / undefined reasons fall through to `"stop"` since callers treat
+ * that as the "completed normally" baseline.
+ */
+export type FinishReason = Extract<StreamEvent, { type: "finish" }>["finishReason"];
+
+export function mapFinishReason(r: string | undefined): FinishReason {
+  if (r === "length") return "length";
+  if (r === "error" || r === "content-filter") return "error";
+  if (r === "tool-calls") return "tool-call";
+  // The AI SDK currently emits `"unknown"` after an aborted stream. We can't
+  // distinguish that from a malformed response, but in practice the engine
+  // already detects abort via `signal.aborted` before reading the finish
+  // event so this branch is informational only.
+  if (r === "abort") return "abort";
+  return "stop";
+}