# Confidence Fact Vault A single-page evidence ledger for storing claims, context, and 0–100 confidence scores ranked from most to least certain. ## Masterplan - Help researchers, students, analysts, and curious individuals track claims whose certainty may change over time. - Make confidence explicit with an integer score, visible tier label, and highest-confidence-first ranking. - Keep the workflow intentionally focused: add a fact, review ranked entries, delete entries, and change theme. - Persist facts and the user’s theme preference directly in the injected GenMB key-value store; there is no custom backend or database schema. - Seed an empty vault with three sample facts so first-time users immediately understand the product. ## Tech Stack & Architecture - **React 19 + TypeScript**, built with **Vite**. - **React Router** with `HashRouter`; the only route is `#/`. - **Tailwind CSS v4** through `@tailwindcss/vite`, with semantic CSS-variable color tokens in `src/styles/main.css`. - **Lucide React** for all icons. - **GenMB KV SDK** injected by `index.html` as `window.genmb.kv`. - **No API routes or conventional backend.** Client code calls the injected KV SDK directly. Application composition: 1. `src/main.tsx` mounts the app in `StrictMode`, wraps it in `HashRouter` and `ToastProvider`, and imports global CSS. 2. `src/App.tsx` maps `/` to `src/pages/FactsPage.tsx`. 3. `FactsPage.tsx` owns persistence calls, local state, sorting, loading/error handling, statistics, and theme application. 4. `FactForm.tsx`, `FactList.tsx`, and supporting components remain presentational and communicate through props/callbacks. 5. `src/lib/facts.ts` defines persisted models, storage keys, and starter data. State management is local React state only: - `facts`, loading/error status, deletion state, and theme state live in `FactsPage`. - Toast state lives in `ToastProvider` context. - Form field state and validation state live inside `FactForm`. - Do not introduce a global store unless cross-page state is actually added. ### Persistence Surface The GenMB SDK interface is declared in `src/types/genmb.d.ts`: - `window.genmb.kv.get(key)` → `Promise` - `window.genmb.kv.set(key, value)` → `Promise` - `window.genmb.kv.delete(key)` → `Promise<{ deleted: boolean }>` - `window.genmb.kv.list(prefix)` → `Promise<{ data, total }>` - `window.genmb.kv.increment(key, by?)` → `Promise` Persisted keys: - `fact:{uuid}` — one `Fact` record per key. - `fact:count` — incremented on fact creation only. It is not used by the UI and is intentionally **not decremented** when deleting. - `fact-confidence:settings` — `AppSettings`, currently storing only `theme`. Important: `FACTS_PREFIX` is `fact:`, so a `list('fact:')` call also includes `fact:count`. `FactsPage` filters list values through `isFact()` before rendering; preserve this guard if adding metadata keys under the same prefix. ## File Structure ```text index.html Vite shell, page metadata, and injected GenMB KV SDK. package.json Runtime dependencies and Vite scripts. vite.config.ts Enables React and Tailwind CSS Vite plugins. src/ ├── main.tsx Mounts StrictMode, HashRouter, ToastProvider, and App. ├── App.tsx Defines the sole / route. ├── pages/ │ └── FactsPage.tsx Main controller: KV CRUD, seeding, sorting, stats, theme logic. ├── components/ │ ├── Button.tsx Shared button variants, sizing, loading state, and focus styles. │ ├── EmptyState.tsx Empty vault CTA shown when no facts remain. │ ├── FactForm.tsx Inline fact creation form and client-side validation. │ ├── FactList.tsx Ranked fact card grid, confidence badge, and delete actions. │ ├── FetchError.tsx Load-failure screen with retry action. │ ├── ThemeToggle.tsx Light/dark mode toggle button. │ └── ToastProvider.tsx Toast context, stack rendering, and manual dismissal. ├── lib/ │ ├── facts.ts Fact/AppSettings types, KV key constants, and sample facts. │ └── utils.ts Tailwind class merger and safe error-message helper. ├── styles/ │ └── main.css Tailwind import, semantic palette, dark theme, global animation. └── types/ └── genmb.d.ts Type declarations for window.genmb.kv. ``` ## Key Features ### Fact records `src/lib/facts.ts` defines: ```ts type Fact = { id: string title: string description: string confidence: number createdAt: number } ``` Requirements: - Title is required, trimmed, and limited to **120 characters**. - Description is required, trimmed, and limited to **1000 characters**. - Confidence is an integer selected with a range input from **0 through 100**, defaulting to `75`. - New records use `crypto.randomUUID()` and `Date.now()`. - A successful save writes `fact:{id}`, increments `fact:count`, updates local state, and shows a success toast. - Save failures must remain visible in the form and also show an error toast. ### Confidence ranking and tiers `sortFacts()` in `src/pages/FactsPage.tsx` sorts: 1. Descending `confidence` 2. Descending `createdAt` for equal scores `ConfidenceBadge` in `src/components/FactList.tsx` labels facts as: - **High confidence:** `90–100` - **Moderate confidence:** `70–89` - **Low confidence:** `0–69` Do not change these thresholds without updating both product copy and badge behavior. ### Initial data seeding When `loadFacts()` finds no valid persisted `Fact` records, it writes the three `sampleFacts` from `src/lib/facts.ts` to KV and displays them. This happens whenever the vault is empty, including after deleting every fact. Therefore, deleting all facts and then reloading the page restores sample facts. This is current product behavior, not a storage bug. ### Deletion - Each fact card has an icon-only delete action. - Only one deletion can run at once via `deletingId`. - The UI updates only after `kv.delete()` returns `{ deleted: true }`. - There is no confirmation dialog and no undo. - Deletion does not modify `fact:count`. ### Theme preference - `ThemeToggle.tsx` switches between light and dark modes. - `FactsPage.tsx` persists `{ theme }` under `fact-confidence:settings`. - `applyTheme()` toggles the `.dark` class on `` and sets `document.documentElement.style.colorScheme`. - Default theme is light when no stored preference exists. - Do not rely on OS color preference: this app uses only its saved explicit mode. ### Feedback and resilience - Loading facts renders skeleton cards. - Failed loads render `FetchError` and disable fact creation until retry succeeds. - Toasts support success, error, and info variants; there is no automatic timeout, so users dismiss them manually. - Use `getErrorMessage()` for caught unknown errors rather than exposing raw non-`Error` values. ## Design Guidelines - Visual language: calm, trustworthy, ledger-like interface using rounded cards, restrained borders, soft shadows, and blue confidence accents. - Font stack: `Inter`, then system sans-serif fallbacks, declared in `src/styles/main.css`. - Light mode uses an off-white blue-gray background, white cards, and blue primary actions. - Dark mode uses deep navy surfaces with lighter blue primary accents. - Semantic Tailwind tokens (`bg-background`, `text-muted-foreground`, `bg-card`, `text-primary`, etc.) must be used instead of hard-coded colors. - Green (`success`) is reserved for high-confidence badges and successful feedback; red (`destructive`) is reserved for failures and deletion affordances. - Main content is constrained to `max-w-6xl`. - Fact cards display in one column on small screens and two columns from the `md` breakpoint upward. - The add form uses a two-column layout from `md` upward; it stays vertically stacked on mobile. - Preserve keyboard/focus behavior from `Button.tsx`, labels for all form controls, and descriptive `aria-label`s on icon-only buttons. - Respect reduced-motion preferences; animation classes already disable under `prefers-reduced-motion`. ## App Flow 1. User opens `#/`. 2. `FactsPage` concurrently loads persisted facts and saved theme settings. 3. If no valid facts exist, sample facts are seeded and displayed. 4. Facts are shown in descending confidence order with vault statistics. 5. User enters a title, description, and confidence score in the inline form, then saves. 6. The new fact persists, immediately enters the sorted local list, and triggers a toast. 7. User may delete an entry; the card disappears only after storage confirms deletion. 8. User may toggle light/dark mode; the UI changes only after the preference is persisted. Key edge cases: - A failed fact-list request shows the retry screen and prevents new saves. - Invalid KV values are ignored by `isFact()` rather than rendered. - Equal confidence scores are ordered newest first. - If theme persistence fails, the current theme remains unchanged and an error toast appears. - The title in `index.html` and runtime `document.title` is currently **“Fact Confidence Tracker”**, while the product name is Confidence Fact Vault; keep them synchronized if renamed. ## Conventions - Use PascalCase for React components and component files: `FactList.tsx`, `ThemeToggle.tsx`. - Use camelCase for functions, variables, props, and state: `loadFacts`, `deletingId`. - Keep persisted TypeScript models and storage-key constants in `src/lib/facts.ts`. - Use `type` imports where appropriate, as existing files do. - Use `cn()` from `src/lib/utils.ts` to compose conditional Tailwind class names. - Use the shared `Button` component rather than raw `