@elizaos/app-core 2.0.0-alpha.67 → 2.0.0-alpha.69

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elizaos/app-core",
-  "version": "2.0.0-alpha.67",
+  "version": "2.0.0-alpha.69",
   "description": "Shared application core for Milady shells and white-label apps.",
   "type": "module",
   "license": "MIT",
@@ -68,8 +68,8 @@
     "@capacitor/haptics": "8.0.0",
     "@capacitor/keyboard": "8.0.0",
     "@capacitor/preferences": "^8.0.1",
-    "@elizaos/autonomous": "2.0.0-alpha.67",
-    "@elizaos/ui": "2.0.0-alpha.67",
+    "@elizaos/autonomous": "2.0.0-alpha.69",
+    "@elizaos/ui": "2.0.0-alpha.69",
     "@sparkjsdev/spark": "^0.1.10",
     "lucide-react": "^0.575.0",
     "three": "^0.182.0",
@@ -87,5 +87,5 @@
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },
-  "gitHead": "197684308ba4462a195efc7d60b2193c9943a9ea"
+  "gitHead": "774937c9cbefd3d95fc181ca40295bb4fd5a7d3b"
 }

package/src/actions/character.ts

@@ -6,6 +6,10 @@
 
 import type { CharacterData, ElizaClient } from "../api/client";
 
+type MessageExampleGroup = {
+  examples: Array<{ name: string; content: { text: string } }>;
+};
+
 export interface CharacterActionContext {
   client: ElizaClient;
   setCharacterData: (data: CharacterData | null) => void;
@@ -51,6 +55,165 @@ export async function loadCharacter(
   ctx.setCharacterLoading(false);
 }
 
+function extractLikelyJson(input: string): string {
+  const trimmed = input.trim();
+  if (!trimmed) return trimmed;
+
+  const withoutFences = trimmed
+    .replace(/^```(?:json)?\s*/i, "")
+    .replace(/\s*```$/i, "")
+    .trim();
+  if (withoutFences.startsWith("{") || withoutFences.startsWith("[")) {
+    return withoutFences;
+  }
+
+  const firstBracket = withoutFences.indexOf("[");
+  const firstBrace = withoutFences.indexOf("{");
+  const starts = [firstBracket, firstBrace].filter((index) => index >= 0);
+  if (starts.length === 0) return withoutFences;
+
+  const start = Math.min(...starts);
+  const opener = withoutFences[start];
+  const closer = opener === "[" ? "]" : "}";
+  const end = withoutFences.lastIndexOf(closer);
+  if (end <= start) return withoutFences;
+
+  return withoutFences.slice(start, end + 1);
+}
+
+function normalizeSpeakerName(
+  rawName: unknown,
+  fallbackAgentName: string,
+  options: { fallbackMissingSpeaker?: boolean } = {},
+): string {
+  const fallbackMissingSpeaker = options.fallbackMissingSpeaker ?? true;
+  if (typeof rawName === "string" && rawName.trim()) {
+    const trimmed = rawName.trim();
+    const normalized = trimmed.toLowerCase();
+    if (
+      normalized === "assistant" ||
+      normalized === "agent" ||
+      normalized === "ai" ||
+      normalized === "model" ||
+      normalized === "{{agentname}}"
+    ) {
+      return fallbackAgentName;
+    }
+    if (
+      normalized === "user" ||
+      normalized === "human" ||
+      normalized === "{{user}}" ||
+      normalized === "customer"
+    ) {
+      return "{{user1}}";
+    }
+    return trimmed;
+  }
+  return fallbackMissingSpeaker ? fallbackAgentName : "";
+}
+
+function normalizeMessageText(raw: unknown): string {
+  if (typeof raw === "string") return raw.trim();
+  return "";
+}
+
+function normalizeConversation(
+  conversation: unknown,
+  fallbackAgentName: string,
+  options: { fallbackMissingSpeaker?: boolean } = {},
+): MessageExampleGroup | null {
+  const rawExamples = Array.isArray(conversation)
+    ? conversation
+    : conversation &&
+        typeof conversation === "object" &&
+        Array.isArray(
+          (conversation as { examples?: unknown[] }).examples,
+        )
+      ? (conversation as { examples: unknown[] }).examples
+      : null;
+
+  if (!rawExamples) return null;
+
+  const examples = rawExamples
+    .map((message) => {
+      const record =
+        message && typeof message === "object"
+          ? (message as Record<string, unknown>)
+          : null;
+      if (!record) return null;
+
+      const content =
+        record.content && typeof record.content === "object"
+          ? (record.content as Record<string, unknown>)
+          : null;
+      const text = normalizeMessageText(
+        content?.text ?? record.text ?? record.message ?? record.content,
+      );
+      if (!text) return null;
+
+      return {
+        name: normalizeSpeakerName(
+          record.name ?? record.user ?? record.speaker ?? record.role,
+          fallbackAgentName,
+          options,
+        ),
+        content: { text },
+      };
+    })
+    .filter(
+      (
+        message,
+      ): message is { name: string; content: { text: string } } =>
+        Boolean(message?.name && message.content.text),
+    );
+
+  if (examples.length === 0) return null;
+  return { examples };
+}
+
+export function normalizeGeneratedMessageExamples(
+  input: unknown,
+  fallbackAgentName = "Agent",
+  options: { fallbackMissingSpeaker?: boolean } = {},
+): MessageExampleGroup[] {
+  let parsed = input;
+
+  if (typeof input === "string") {
+    const candidate = extractLikelyJson(input);
+    try {
+      parsed = JSON.parse(candidate);
+    } catch {
+      return [];
+    }
+  }
+
+  const source =
+    parsed &&
+    typeof parsed === "object" &&
+    Array.isArray(
+      (parsed as { messageExamples?: unknown[] }).messageExamples,
+    )
+      ? (parsed as { messageExamples: unknown[] }).messageExamples
+      : parsed;
+
+  if (!Array.isArray(source)) return [];
+
+  const groups =
+    source.length > 0 &&
+    source.every(
+      (entry) =>
+        entry && typeof entry === "object" && Array.isArray((entry as { examples?: unknown[] }).examples),
+    )
+      ? source
+      : source.every((entry) => Array.isArray(entry))
+        ? source
+        : [source];
+
+  return groups
+    .map((group) => normalizeConversation(group, fallbackAgentName, options))
+    .filter((group): group is MessageExampleGroup => Boolean(group));
+}
+
 export function prepareDraftForSave(
   draft: CharacterData,
 ): Record<string, unknown> {
@@ -91,24 +254,43 @@ export function prepareDraftForSave(
   );
   if (postExamples.length > 0) result.postExamples = postExamples;
 
-  if (
-    Array.isArray(draft.messageExamples) &&
-    draft.messageExamples.length > 0
-  ) {
+  if (draft.messageExamples != null) {
     // Strip extra fields from content (schema is .strict() — only text + actions allowed)
-    const cleaned = draft.messageExamples
-      .map((group) => ({
-        examples: (group.examples ?? [])
-          .filter((msg) => msg.name?.trim() && msg.content?.text?.trim())
-          .map((msg) => ({
-            name: msg.name,
+    const cleaned = normalizeGeneratedMessageExamples(
+      draft.messageExamples,
+      draft.name?.trim() || "Agent",
+      { fallbackMissingSpeaker: false },
+    ).map((group, groupIndex) => ({
+      examples: group.examples
+        .map((msg) => {
+          const originalGroup =
+            Array.isArray(draft.messageExamples) &&
+            draft.messageExamples[groupIndex] &&
+            typeof draft.messageExamples[groupIndex] === "object"
+              ? (draft.messageExamples[groupIndex] as {
+                  examples?: Array<{
+                    name?: string;
+                    content?: { text?: string; actions?: string[] };
+                  }>;
+                })
+              : null;
+          const originalMessage = originalGroup?.examples?.find(
+            (candidate) =>
+              candidate?.name?.trim() === msg.name &&
+              candidate?.content?.text?.trim() === msg.content.text,
+          );
+          return {
+            name: msg.name.trim(),
             content: {
-              text: msg.content.text,
-              ...(msg.content.actions ? { actions: msg.content.actions } : {}),
+              text: msg.content.text.trim(),
+              ...(originalMessage?.content?.actions
+                ? { actions: originalMessage.content.actions }
+                : {}),
             },
-          })),
-      }))
-      .filter((group) => group.examples.length > 0);
+          };
+        })
+        .filter((msg) => msg.name && msg.content.text),
+    }));
     if (cleaned.length > 0) result.messageExamples = cleaned;
   }
 

package/src/components/CharacterView.tsx

@@ -13,11 +13,12 @@ import {
   dispatchWindowEvent,
   VOICE_CONFIG_UPDATED_EVENT,
 } from "@elizaos/app-core/events";
+import { COMPANION_ENABLED } from "@elizaos/app-core/navigation";
+import { normalizeGeneratedMessageExamples } from "../actions/character";
 import { useApp } from "@elizaos/app-core/state";
 import {
   CharacterRoster,
   type CharacterRosterEntry,
-  CHARACTER_PRESET_META,
   resolveRosterEntries,
 } from "./CharacterRoster";
 import {
@@ -389,7 +390,7 @@ export function CharacterView({
   }, [onboardingOptions?.styles]);
 
   const characterRoster = resolveRosterEntries(rosterStyles);
-  const visibleCharacterRoster = characterRoster.slice(0, 4);
+  const visibleCharacterRoster = characterRoster;
   const currentCharacter = hasCharacterContent(characterDraft)
     ? characterDraft
     : characterData;
@@ -533,12 +534,12 @@ export function CharacterView({
     dispatchWindowEvent(VOICE_CONFIG_UPDATED_EVENT, normalizedVoiceConfig);
   }, [voiceConfig]);
 
-  const d = characterDraft;
+  const d = characterDraft ?? ({} as Record<string, unknown>);
   const bioText =
     typeof d.bio === "string"
       ? d.bio
       : Array.isArray(d.bio)
-        ? d.bio.join("\n")
+        ? (d.bio as string[]).join("\n")
         : "";
 
   const getCharContext = useCallback(
@@ -598,23 +599,18 @@ export function CharacterView({
             /* raw text fallback */
           }
         } else if (field === "chatExamples") {
-          try {
-            const parsed = JSON.parse(generated);
-            if (Array.isArray(parsed)) {
-              const formatted = parsed.map(
-                (
-                  convo: Array<{ user: string; content: { text: string } }>,
-                ) => ({
-                  examples: convo.map((msg) => ({
-                    name: msg.user,
-                    content: { text: msg.content.text },
-                  })),
-                }),
-              );
-              handleFieldEdit("messageExamples", formatted);
-            }
-          } catch {
-            /* raw text fallback */
+          const formatted = normalizeGeneratedMessageExamples(
+            generated,
+            d.name?.trim() || "Agent",
+          );
+          if (formatted.length > 0) {
+            setState("characterSaveError", null);
+            handleFieldEdit("messageExamples", formatted);
+          } else {
+            setState(
+              "characterSaveError",
+              "Generated chat examples could not be parsed. Try again.",
+            );
           }
         } else if (field === "postExamples") {
           try {
@@ -633,8 +629,15 @@ export function CharacterView({
             /* raw text fallback */
           }
         }
-      } catch {
-        /* generation failed */
+      } catch (err) {
+        if (field === "chatExamples") {
+          setState(
+            "characterSaveError",
+            err instanceof Error
+              ? `Failed to generate chat examples: ${err.message}`
+              : "Failed to generate chat examples.",
+          );
+        }
       }
       setGenerating(null);
     },
@@ -644,6 +647,7 @@ export function CharacterView({
       handleFieldEdit,
       handleStyleEdit,
       handleCharacterArrayInput,
+      setState,
     ],
   );
 
@@ -802,19 +806,44 @@ export function CharacterView({
   ]);
 
   const handleSaveAll = useCallback(async () => {
-    setVoiceSaving(true);
+    const trimmedName =
+      typeof characterDraft?.name === "string" ? characterDraft.name.trim() : "";
+    if (!trimmedName) {
+      setVoiceSaveError(null);
+      setState("characterSaveSuccess", null);
+      setState("characterSaveError", "Character name is required before saving.");
+      return;
+    }
+
     setVoiceSaveError(null);
+    try {
+      await handleSaveCharacter();
+    } catch {
+      return;
+    }
+
+    setVoiceSaving(true);
+    let voiceSaveFailed = false;
     try {
       await persistVoiceConfig();
     } catch (err) {
+      voiceSaveFailed = true;
       setVoiceSaveError(
         err instanceof Error ? err.message : "Failed to save voice settings.",
       );
     } finally {
       setVoiceSaving(false);
     }
-    await handleSaveCharacter();
-  }, [handleSaveCharacter, persistVoiceConfig]);
+    if (!voiceSaveFailed) {
+      setTab(COMPANION_ENABLED ? "companion" : "chat");
+    }
+  }, [
+    characterDraft?.name,
+    handleSaveCharacter,
+    persistVoiceConfig,
+    setState,
+    setTab,
+  ]);
 
   /* ── Helpers ────────────────────────────────────────────────────── */
   const cardCls = sceneOverlay
@@ -839,8 +868,8 @@ export function CharacterView({
   const notebookShellCls =
     "relative isolate flex h-[34.75rem] w-full max-w-[29rem] overflow-visible";
   const notebookFrameCls = sceneOverlay
-    ? "relative flex h-full w-full overflow-hidden rounded-[1.75rem] border border-[#2f261b]/20 bg-[#f8f0df]/70 shadow-[0_24px_60px_rgba(0,0,0,0.34),inset_0_1px_0_rgba(255,255,255,0.5)]"
-    : "relative flex h-full w-full overflow-hidden rounded-[1.75rem] border border-[#2f261b]/14 bg-[#f8f0df] shadow-[0_26px_60px_rgba(36,28,18,0.2),inset_0_1px_0_rgba(255,255,255,0.58)]";
+    ? "relative flex h-full w-full overflow-hidden rounded-[1.75rem] border border-[#2f261b]/20 bg-[#f8f0df]/70 dark:border-white/10 dark:bg-[#1c1c1e]/90 shadow-[0_24px_60px_rgba(0,0,0,0.34),inset_0_1px_0_rgba(255,255,255,0.5)]"
+    : "relative flex h-full w-full overflow-hidden rounded-[1.75rem] border border-[#2f261b]/14 bg-[#f8f0df] dark:border-white/10 dark:bg-[#1c1c1e] shadow-[0_26px_60px_rgba(36,28,18,0.2),inset_0_1px_0_rgba(255,255,255,0.58)]";
 
   const handleCustomVrmUpload = useCallback(
     (file: File) => {
@@ -872,7 +901,11 @@ export function CharacterView({
     PREMADE_VOICES.find((preset) => preset.id === selectedVoicePresetId) ??
     null;
   const voiceSelectValue = selectedVoicePresetId ?? null;
-  const combinedSaveError = voiceSaveError ?? characterSaveError;
+  const combinedSaveError = characterSaveError;
+  const saveAdvisory =
+    characterSaveSuccess && voiceSaveError
+      ? `Character saved. Voice settings still need attention: ${voiceSaveError}`
+      : null;
   const customizationActionLabel = customOverridesEnabled
     ? t("characterview.backToCharacterSelect")
     : t("characterview.customize");
@@ -995,16 +1028,16 @@ export function CharacterView({
             className={notebookShellCls}
             data-testid="character-notebook"
           >
-            <div className="pointer-events-none absolute inset-x-5 bottom-[-1.2rem] top-6 rounded-[1.9rem] bg-[linear-gradient(180deg,rgba(35,27,18,0.12)_0%,rgba(16,12,9,0.32)_100%)] blur-xl" />
-            <div className="pointer-events-none absolute inset-[0.35rem] translate-x-2 translate-y-2 rounded-[1.9rem] border border-[#d7c5a4]/50 bg-[linear-gradient(180deg,rgba(251,246,235,0.86)_0%,rgba(236,224,198,0.7)_100%)] shadow-[0_12px_26px_rgba(62,44,21,0.12)]" />
+            <div className="pointer-events-none absolute inset-x-5 bottom-[-1.2rem] top-6 rounded-[1.9rem] bg-[linear-gradient(180deg,rgba(35,27,18,0.12)_0%,rgba(16,12,9,0.32)_100%)] dark:bg-[linear-gradient(180deg,rgba(0,0,0,0.3)_0%,rgba(0,0,0,0.5)_100%)] blur-xl" />
+            <div className="pointer-events-none absolute inset-[0.35rem] translate-x-2 translate-y-2 rounded-[1.9rem] border border-[#d7c5a4]/50 bg-[linear-gradient(180deg,rgba(251,246,235,0.86)_0%,rgba(236,224,198,0.7)_100%)] dark:border-white/10 dark:bg-[linear-gradient(180deg,rgba(38,38,40,0.9)_0%,rgba(28,28,30,0.8)_100%)] shadow-[0_12px_26px_rgba(62,44,21,0.12)]" />
             <div className="pointer-events-none absolute bottom-[-0.95rem] left-8 h-14 w-4 rounded-b-sm bg-[linear-gradient(180deg,#ddb45e_0%,#be8530_100%)] [clip-path:polygon(0_0,100%_0,100%_78%,50%_100%,0_78%)] shadow-[0_10px_20px_rgba(141,97,34,0.28)]" />
             <div className={notebookFrameCls}>
-              <div className="pointer-events-none absolute left-4 top-4 h-2 w-2 rounded-full border border-[#d8c295]/70 bg-[#fff9eb]/85 shadow-[0_0_0_2px_rgba(150,116,61,0.08)]" />
-              <div className="pointer-events-none absolute bottom-4 left-4 h-2 w-2 rounded-full border border-[#d8c295]/70 bg-[#fff9eb]/85 shadow-[0_0_0_2px_rgba(150,116,61,0.08)]" />
+              <div className="pointer-events-none absolute left-4 top-4 h-2 w-2 rounded-full border border-[#d8c295]/70 bg-[#fff9eb]/85 shadow-[0_0_0_2px_rgba(150,116,61,0.08)] dark:border-white/20 dark:bg-white/10 dark:shadow-[0_0_0_2px_rgba(255,255,255,0.05)]" />
+              <div className="pointer-events-none absolute bottom-4 left-4 h-2 w-2 rounded-full border border-[#d8c295]/70 bg-[#fff9eb]/85 shadow-[0_0_0_2px_rgba(150,116,61,0.08)] dark:border-white/20 dark:bg-white/10 dark:shadow-[0_0_0_2px_rgba(255,255,255,0.05)]" />
               <div className="pointer-events-none absolute right-4 top-4 h-2 w-2 rounded-full border border-white/10 bg-white/10 shadow-[0_0_0_2px_rgba(255,255,255,0.03)]" />
               <div className="pointer-events-none absolute bottom-4 right-4 h-2 w-2 rounded-full border border-white/10 bg-white/10 shadow-[0_0_0_2px_rgba(255,255,255,0.03)]" />
-              <div className="pointer-events-none absolute inset-x-0 bottom-0 h-14 bg-[linear-gradient(180deg,rgba(0,0,0,0)_0%,rgba(104,77,39,0.07)_100%)]" />
-              <div className="pointer-events-none absolute bottom-3 right-[4.95rem] top-3 w-[0.7rem] rounded-full bg-[linear-gradient(90deg,rgba(116,92,55,0.16)_0%,rgba(255,255,255,0.5)_45%,rgba(112,88,52,0.2)_100%)] shadow-[inset_0_0_7px_rgba(89,67,37,0.16),0_0_18px_rgba(255,246,220,0.16)]" />
+              <div className="pointer-events-none absolute inset-x-0 bottom-0 h-14 bg-[linear-gradient(180deg,rgba(0,0,0,0)_0%,rgba(104,77,39,0.07)_100%)] dark:bg-[linear-gradient(180deg,rgba(0,0,0,0)_0%,rgba(0,0,0,0.15)_100%)]" />
+              <div className="pointer-events-none absolute bottom-3 right-[4.95rem] top-3 w-[0.7rem] rounded-full bg-[linear-gradient(90deg,rgba(116,92,55,0.16)_0%,rgba(255,255,255,0.5)_45%,rgba(112,88,52,0.2)_100%)] shadow-[inset_0_0_7px_rgba(89,67,37,0.16),0_0_18px_rgba(255,246,220,0.16)] dark:bg-[linear-gradient(90deg,rgba(255,255,255,0.05)_0%,rgba(255,255,255,0.15)_45%,rgba(255,255,255,0.05)_100%)] dark:shadow-[inset_0_0_7px_rgba(0,0,0,0.3),0_0_18px_rgba(255,255,255,0.05)]" />
               {/* ── Book page (left) ── */}
               <div
                 className={`${bookPageCls} flex flex-1 flex-col rounded-l-[1.75rem] border-r border-[#cdbb98]/60 text-[#1e2329] dark:border-white/[0.08] dark:text-[hsl(40,10%,84%)]`}
@@ -1411,13 +1444,18 @@ export function CharacterView({
       )}
 
       <div className={`${sectionCls} relative z-10 ${sceneOverlay ? "character-action-bar" : ""}`}>
-        {(characterSaveSuccess || combinedSaveError) && (
+        {(characterSaveSuccess || combinedSaveError || saveAdvisory) && (
           <div className="mb-3 flex flex-wrap items-center justify-center gap-2">
             {characterSaveSuccess && (
               <span className="rounded-lg border border-green-400/20 bg-green-400/10 px-3 py-1.5 text-xs font-bold text-green-400">
                 {characterSaveSuccess}
               </span>
             )}
+            {saveAdvisory && (
+              <span className="rounded-lg border border-amber-400/20 bg-amber-400/10 px-3 py-1.5 text-xs font-medium text-amber-300">
+                {saveAdvisory}
+              </span>
+            )}
             {combinedSaveError && (
               <span className="rounded-lg border border-danger/20 bg-danger/10 px-3 py-1.5 text-xs font-medium text-danger">
                 {combinedSaveError}
@@ -1426,8 +1464,8 @@ export function CharacterView({
           </div>
         )}
 
-        <div className="relative flex flex-col gap-3 md:min-h-10 md:flex-row md:items-center md:justify-between">
-          <div className="flex items-center justify-center md:justify-start">
+        <div className="flex min-h-10 flex-row items-center justify-between gap-2">
+          <div className="flex items-center justify-start">
             <div
               className="flex min-w-0 items-center gap-2"
               data-testid="character-voice-picker"
@@ -1466,7 +1504,7 @@ export function CharacterView({
                 }}
                 placeholder={t("characterview.selectAVoice")}
                 menuPlacement="top"
-                className="w-[11rem] max-w-[58vw]"
+                className="min-w-0 w-[7rem] sm:w-[11rem]"
                 triggerClassName="h-8 rounded-full border-border/50 bg-bg/65 px-4 py-0 text-[11px] shadow-inner backdrop-blur-sm"
                 menuClassName="border-border/60 bg-bg/92 shadow-2xl backdrop-blur-md"
               />
@@ -1495,25 +1533,32 @@ export function CharacterView({
             </div>
           </div>
 
-          <div className="flex items-center justify-center md:absolute md:left-1/2 md:top-1/2 md:z-10 md:-translate-x-1/2 md:-translate-y-1/2">
+          <div className="flex items-center">
             <Button
               size="lg"
-              className="rounded-xl px-8 text-[13px] font-bold tracking-wider shadow-[0_0_15px_color-mix(in_srgb,var(--accent)_20%,transparent)] transition-all hover:shadow-[0_0_20px_color-mix(in_srgb,var(--accent)_40%,transparent)]"
+              className="ce-save-btn"
               disabled={characterSaving || voiceSaving}
               onClick={() => void handleSaveAll()}
             >
-              {characterSaving || voiceSaving ? "saving..." : "Save Character"}
+              {characterSaving || voiceSaving ? (
+                "saving..."
+              ) : (
+                <>
+                  <span className="hidden sm:inline">Save Character</span>
+                  <span className="sm:hidden">Save</span>
+                </>
+              )}
             </Button>
           </div>
 
-          <div className="flex items-center justify-center md:justify-end">
+          <div className="flex items-center justify-end">
             <Button
               type="button"
               variant={customOverridesEnabled ? "outline" : "default"}
               size="sm"
-              className={`h-10 rounded-xl px-4 text-sm font-semibold ${customOverridesEnabled
+              className={`ce-customize-btn ${customOverridesEnabled
                 ? "border-border/40 bg-bg/40 text-txt"
-                : "shadow-[0_0_18px_color-mix(in_srgb,var(--accent)_18%,transparent)]"
+                : ""
                 }`}
               onClick={() =>
                 handleCustomOverridesChange(!customOverridesEnabled)

package/src/components/FlaminaGuide.test.tsx

@@ -0,0 +1,61 @@
+// @vitest-environment jsdom
+import React from "react";
+import TestRenderer from "react-test-renderer";
+import { describe, expect, it } from "vitest";
+import { FlaminaGuideCard } from "./FlaminaGuide";
+
+function textOf(node: TestRenderer.ReactTestInstance): string {
+  return node.children
+    .map((child) => (typeof child === "string" ? child : textOf(child)))
+    .join("");
+}
+
+describe("FlaminaGuideCard", () => {
+  it("explains provider impact on character behavior", () => {
+    const tree = TestRenderer.create(
+      React.createElement(FlaminaGuideCard, { topic: "provider" }),
+    );
+
+    const renderedText = textOf(tree.root);
+
+    expect(renderedText).toContain("reasons");
+    expect(renderedText).toContain("latency");
+    expect(renderedText).toContain("output quality");
+  });
+
+  it("explains rpc impact on external capabilities", () => {
+    const tree = TestRenderer.create(
+      React.createElement(FlaminaGuideCard, { topic: "rpc" }),
+    );
+
+    const renderedText = textOf(tree.root);
+
+    expect(renderedText).toContain("wallets");
+    expect(renderedText).toContain("chains");
+    expect(renderedText).toContain("external execution");
+  });
+
+  it("explains permissions impact on local access", () => {
+    const tree = TestRenderer.create(
+      React.createElement(FlaminaGuideCard, { topic: "permissions" }),
+    );
+
+    const renderedText = textOf(tree.root);
+
+    expect(renderedText).toContain("see");
+    expect(renderedText).toContain("control");
+    expect(renderedText).toContain("locally");
+  });
+
+  it("explains voice impact on presentation", () => {
+    const tree = TestRenderer.create(
+      React.createElement(FlaminaGuideCard, { topic: "voice" }),
+    );
+
+    const renderedText = textOf(tree.root);
+
+    expect(renderedText).toContain("sounds");
+    expect(renderedText).toContain("spoken interactions");
+    expect(renderedText).toContain("saved");
+  });
+});