# Multilingual Book Studio An offline-first React PWA for creating, illustrating, organizing, searching, and reading books stored locally, with Kreyòl, French, and English interfaces. ## Masterplan - Preserve the existing Book Studio workflows: library, editor, reader, chapter/image management, story generator, studio assistant, local storage, and PWA installation. - Serve writers who need a private, device-local workspace that remains usable without internet access. - Support exactly three application UI languages: Haitian Creole (`ht`), French (`fr`), and English (`en`). - Keep application language separate from all user-authored content and each book’s `storyLanguage`; never translate existing books automatically. - Search locally saved title, author, description, chapter titles, and chapter content without network access. ## Tech Stack & Architecture - **React 18 + TypeScript + Vite**, initialized in `src/main.tsx`. - **React Router DOM** with `HashRouter`; routes are defined in `src/App.tsx`. Keep hash routing for reliable static-host and offline navigation. - **Tailwind CSS v4** via `@tailwindcss/vite`; global styling and color tokens live in `src/styles/main.css`. - **Lucide React** provides UI icons. - **`clsx` + `tailwind-merge`**, exposed as `cn()` from `src/lib/utils.ts`. ### Providers and state `src/main.tsx` intentionally nests providers as follows: ```tsx ``` - `LanguageProvider` (`src/i18n.tsx`) owns UI language selection and translation lookup. - `ToastProvider` (`src/components/ToastProvider.tsx`) renders transient success, error, and info messages. - `BookStoreProvider` (`src/lib/bookStore.tsx`) is mounted by `src/App.tsx` and owns loaded books, persistence actions, loading status, and storage errors. - Any component using `useBooks()` must remain below `BookStoreProvider`. - Components use local React state for transient editor, dialog, reader, and generation UI state; books remain centralized in the store. ### Persistence - `src/lib/bookStorage.ts` uses IndexedDB database **`offline-book-studio`**: - `books` store: persisted `BookRecord`s. - `settings` store: language and other local settings. - Every stored book has generated lowercase `searchText`, built from title, author, description, chapter titles, and chapter content. - `src/lib/bookStore.tsx` maintains a legacy localStorage mirror under `offline-book-studio:books`; do not clear, reset, or destructively migrate it. - `src/lib/imageStorage.ts` persists uploaded/generated image blobs in a separate IndexedDB database. - Remote KV mirroring in `bookStore.tsx` is opportunistic only. Local IndexedDB remains authoritative. ### Internationalization - `src/i18n.tsx` is the sole UI translation layer. - Dictionaries are bundled locally in: - `src/locales/en.json` - `src/locales/fr.json` - `src/locales/ht.json` - `src/locales/extra.ts` for supplemental keys - Use `useLanguage()` and `t('namespace.key', variables?)` for all user-facing UI strings. - Translation keys are flat dotted keys, e.g. `common.save`, `nav.library`, `book.coverAlt`, `settings.language`. - UI language is persisted synchronously in localStorage as `offline-book-studio:language` to prevent a language flash, then mirrored to IndexedDB settings. - Browser detection supports `ht-*`, `fr-*`, and `en-*`; unsupported browser languages fall back to English. - Never pass book titles, author names, descriptions, chapter text, saved prompts, character details, or notes through `t()`. ### Offline and PWA - `public/manifest.webmanifest` defines the standalone PWA identity, icons, and theme colors. - `public/sw.js` precaches shell files and runtime-caches same-origin scripts, styles, images, fonts, and manifest assets. - `src/main.tsx` registers `/sw.js` and requests persistent browser storage where available. - Do not add an internet dependency to core workflows: loading books, language switching, editing, reading, searching, and local image retrieval must remain offline-capable. ## File Structure ```text functions/ └── generateImage.ts Hosted Gemini image-generation function; existing remote feature. public/ ├── manifest.webmanifest PWA metadata, standalone mode, app name, icons. ├── sw.js Offline shell and same-origin runtime caching. ├── icon.svg Browser/favicon icon. ├── icon-192.svg PWA icon. └── icon-512.svg Maskable PWA icon. src/ ├── main.tsx React bootstrap, router/provider nesting, service-worker registration. ├── App.tsx Route definitions and BookStoreProvider boundary. ├── i18n.tsx Language detection, persistence, dictionaries, useLanguage(). ├── types.ts Shared Book, Chapter, image, language, and toast types. ├── styles/ │ └── main.css Tailwind/global visual tokens and application-wide styles. ├── locales/ │ ├── en.json English UI dictionary. │ ├── fr.json French UI dictionary. │ ├── ht.json Haitian Creole UI dictionary. │ └── extra.ts Supplemental translations merged into dictionaries. ├── components/ │ ├── AppShell.tsx Header, navigation, online state, main outlet. │ ├── BookCover.tsx Cover image/fallback with translated accessibility labels. │ ├── Button.tsx Shared styled button with loading state. │ ├── Dialog.tsx Accessible modal with Escape and focus handling. │ ├── LanguageSelect.tsx Shared application-language select control. │ ├── StoredImage.tsx IndexedDB image loader and missing-image state. │ └── ToastProvider.tsx Toast context and renderer. ├── hooks/ │ └── usePageMeta.ts Updates document title and description per page. ├── lib/ │ ├── bookStorage.ts IndexedDB books/settings and offline search indexing. │ ├── bookStore.tsx Book state, legacy migration/fallback, save/delete actions. │ ├── imageStorage.ts Local blob persistence for chapter images. │ ├── imageGenerator.ts Client integration for existing image generation. │ ├── imagePromptGenerator.ts Existing illustration prompt support. │ ├── storyGenerator.ts Existing story-generation support. │ └── utils.ts cn() class-name utility. └── pages/ ├── LibraryPage.tsx Local library, search, book actions, empty/loading states. ├── BookEditorPage.tsx Create/edit books, chapters, story language, images. ├── ReaderPage.tsx Book reading and chapter navigation. ├── SettingsPage.tsx Visible application language settings. ├── StoryGeneratorPage.tsx Existing story generation workflow. └── StudioAssistantPage.tsx Existing assistant workflow. ``` ## Key Features ### Book library and local search - `LibraryPage.tsx` lists books from `useBooks()`. - Search must remain local and offline. - Search covers: - `Book.title` - `Book.author` - `Book.description` - `Chapter.title` - `Chapter.content` - `bookStorage.ts` creates `searchText` on every save. Do not search translated UI labels or mutate user content. - Search UI text, empty states, and accessibility labels must use translation keys. ### Book creation and editing - `BookEditorPage.tsx` creates and edits `Book` records without changing existing book content. - Books include title, author, description, chapters, timestamps, images, characters, and `storyLanguage`. - `storyLanguage` accepts only `ht`, `fr`, or `en`. - Story Language controls the intended language of future generation workflows; it does not translate existing content. - Existing books without valid image metadata are normalized safely in `normaliseBook()` / `normaliseChapter()`. ### Reader - `ReaderPage.tsx` reads saved books and chapters locally. - Preserve existing reader layout and navigation unless a translated label or accessibility update is required. - Persist last opened book/chapter through `setLastOpened()` in `src/lib/bookStorage.ts`. ### Image functionality - Uploaded and generated images are stored as blobs through `src/lib/imageStorage.ts`. - `StoredImage.tsx` resolves blob URLs at runtime and revokes them on cleanup. - Deleting a book also deletes its locally stored chapter images. - Preserve current image upload, prompt, generation, regeneration, viewing, and removal functionality. ### Existing remote-assisted tools - `functions/generateImage.ts` invokes Gemini image generation through the existing hosted function runtime. - `src/lib/imageGenerator.ts`, `src/lib/imagePromptGenerator.ts`, and `src/lib/storyGenerator.ts` support existing generation workflows. - These features may require connectivity; do not make offline core book workflows depend on them. - Do not add additional AI providers, authentication, payments, cloud sync, or unrelated APIs. ## Design Guidelines - Visual identity uses a calm editorial/studio style with the primary green `#245c4a`. - The PWA shell uses light backgrounds (`#fbfcfa`), bordered cards, muted secondary text, rounded controls, and subtle elevation. - Shared interactive controls should use `Button.tsx` or match its focus, disabled, loading, and minimum-height behavior. - Use Lucide icons with `aria-hidden="true"` when adjacent text identifies the action. - Icon-only controls require translated `aria-label` text. - Maintain keyboard-visible focus rings and dialog focus trapping. - Layout uses responsive Tailwind utilities: - Header navigation labels collapse on small screens. - Main content is constrained to `max-w-7xl`. - Controls retain touch-friendly minimum heights (`min-h-10` / `min-h-11`). - Do not redesign the reader or replace the established UI structure while adding language support. ## App Flow 1. **Launch** - Service worker registers. - `LanguageProvider` immediately restores local language preference or detects browser language. - `BookStoreProvider` loads IndexedDB books, then localStorage fallback, then the starter book only when no stored books exist. 2. **Library** - User opens `/library`, searches locally, opens a book, edits it, or creates a new book. - Search filters saved data only and remains available offline. 3. **Create/edit** - `/new` creates a book; `/edit/:id` modifies an existing one. - User chooses Story Language independently of the interface language. - Saving updates IndexedDB, localStorage mirror, search index, and optional online KV mirror. 4. **Read** - `/reader/:id` opens the reader and supports chapter navigation. - Missing IDs should return users safely to an appropriate existing route rather than rendering unusable content. 5. **Settings** - `/settings` exposes the visible application language selector. - Options must display exactly: **Kreyòl**, **Français**, **English**. - Changing language updates all interface text immediately and persists locally. 6. **Offline behavior** - Navigation, saved books, local images, language preference, reader, editor, and search continue to work offline. - Connectivity-dependent generation features should fail gracefully with translated status/error feedback. ## Conventions - Use TypeScript and functional React components. - Name components in PascalCase; hooks begin with `use`; utility functions use camelCase. - Keep route pages in `src/pages/`, reusable UI in `src/components/`, and persistence/business logic in `src/lib/`. - Use `cn()` from `src/lib/utils.ts` for conditional Tailwind classes. - Use `useLanguage()` in every user-facing component: ```tsx const { t } = useLanguage() ``` - Add translation keys to all three locale resources at the same time. English fallback is a safety net, not permission to leave other locales incomplete. - Keep user content raw: ```tsx

{book.title}

// Correct: never translate saved content. ``` - When adding a page: 1. Create it in `src/pages/`. 2. Add its route in `src/App.tsx`. 3. Add navigation in `src/components/AppShell.tsx` only if it is a primary destination. 4. Add translated page title, labels, errors, placeholders, and accessibility text. 5. Use `usePageMeta()` with translated metadata where applicable. - When changing storage models, preserve backward compatibility in `src/lib/bookStore.tsx` normalization and validation. Never clear IndexedDB or legacy localStorage to migrate data. ## Platform (GenMB) This app is built and hosted on GenMB. **Runtime:** Browser sandbox (iframe) or Cloud Run. No Node.js server — all code runs client-side unless `backend/` exists. **Dependencies:** CDN-only (esm.sh, cdn.tailwindcss.com, unpkg). Use ES module imports with full CDN URLs. No `npm install` at runtime. **Entry point:** `index.html` must include all CDN script tags. Tailwind via CDN with inline config. **Built-in services (relative API paths only, never hardcode domains):** - `/api/ai/completion` — AI proxy | `/api/data/{appId}/*` — PostgreSQL (DataConnect SDK) - `/api/storage/{appId}/*` — File uploads (GCS) | `/api/auth/google/*` — Google OAuth - `/api/contact/submit` — Contact form | SDKs: `window.genmb.db`, `.storage`, `.auth` **File structure:** `index.html` (entry), `src/` (source), `styles/` (CSS), `backend/` (optional FastAPI), `CLAUDE.md` (this file). **Cannot:** Install npm packages at runtime, access filesystem, make direct server-side calls from frontend, modify infra.