spb/zyquo-cloud-web Public MIT

1# CLAUDE.md — Zyquo Cloud Web23## Project Identity45**Zyquo Cloud Web** is the **browser edition of Zyquo Cloud**: a legendary, fast, beautiful **React** web app that delivers the same multi-provider AI chat experience as the native macOS **Zyquo Cloud** — but running entirely in the browser, with **no authentication, no accounts, and no backend**. Everything lives on the user's device: the user enters their own provider API keys, which are stored in **`localStorage`**, and their **conversation history is also stored locally** (localStorage / IndexedDB). There is no server, no login, no user database — open the page, add your keys, start chatting.67It fronts **the same 12 providers and the exact same models as native Zyquo Cloud**, with streaming and non-streaming chat, model switching, Markdown + code rendering, and the family's premium design language. Because there is no backend, API calls go **directly from the browser to each provider's API** using the user's keys.89⚠️ **Reality of a keyless, backend-less browser app (design around this honestly):**10- API keys in `localStorage` are **not strongly secure** — any script running on the page (or someone with device access) can read them. Be transparent about this in the UI (a clear one-time notice), keep the app dependency-light and CSP-hardened to reduce XSS risk, and never transmit keys anywhere except directly to the chosen provider. This is a deliberate "bring-your-own-key, local-only" model, not a secure vault.11- **CORS:** some providers' APIs do not allow direct browser (cross-origin) calls. During Phase 0 you MUST determine, per provider, whether direct browser calls work, and document the reality + the optional fallback (a user-supplied proxy URL / the option to run Zyquo Router locally and point the web app at it). Do not pretend all 12 work browser-side without checking.1213**Naming conventions (use consistently everywhere):**14- Display name / product name: `Zyquo Cloud Web`15- App title / PWA name: `Zyquo Cloud`16- Deployment domain: **`www.zyquo.cloud`** (canonical, HTTPS; redirect apex `zyquo.cloud` → `www`)17- Repo module prefix in file headers: `Zyquo Cloud Web`18- Storage key namespace: `zyquo.cloud.web.*` (e.g., `zyquo.cloud.web.keys`, `zyquo.cloud.web.conversations`, `zyquo.cloud.web.settings`)1920---2122## 📋 MANDATORY FILE HEADER — EVERY CODE FILE2324**Every single code file you write** (all `.ts`, `.tsx`, `.js`, `.jsx`, `.css`, config files, `Makefile`, shell/build scripts — anything containing code) **MUST begin with this header comment**, adapted to the file's comment syntax:2526```ts27/*28 *  <FileName>29 *  Zyquo Cloud Web30 *31 *  Author: Simon-Pierre Boucher32 *  Mail: contact@spboucher.ai33 */34```3536For shell scripts / Makefiles / YAML (`#` comments):3738```bash39#40#  <filename>41#  Zyquo Cloud Web42#43#  Author: Simon-Pierre Boucher44#  Mail: contact@spboucher.ai45#46```4748No exceptions. If you ever create or refactor a file and the header is missing, add it. Before declaring the project done, run a sweep over the repository to verify every code file carries the header.4950---5152## 🧭 METHODOLOGY — WORK METHODICALLY, KEEP EVERYTHING COHERENT5354You must execute this project **strictly in phase order (0 → 8)**. Do not jump ahead, do not interleave phases, do not build the full UI before one provider streams a real completion in the browser, and do not write provider code before Phase 0 research + Zyquo Cloud study are complete.5556**Working rules:**57581. **One phase at a time.** At the start of each phase, write a checklist into `docs/PLAN.md`; check items off as you go. At the end of each phase, run a **phase checkpoint**: build (`npm run build`), type-check, lint, fix everything, write a 3–5 line phase summary in `docs/PLAN.md` before moving on.592. **Phase gates:** Phase 0 is complete only when `docs/PROVIDER-REUSE.md` and `docs/CORS-MATRIX.md` are complete. Phase 2 is complete only when a real streaming completion works browser-side against at least one provider. Phase 3 is complete only when local persistence (keys + conversations) round-trips reliably. Phase 4 spec is the contract for all UI in Phase 6. Phase 7 is complete only when the provider matrix is verified with real keys. Phase 8 is complete only when the production build + deployment are done.603. **Single source of truth, everywhere:**61   - Provider/model behavior → ported from the native **Zyquo Cloud** repo (Phase 0.B), adapted to browser `fetch`/streaming; never re-invent request formats. **All Zyquo Cloud models are available.**62   - Colors, fonts, spacing, radii → only from `ZyquoTheme` design tokens (the same family system). Zero raw hex or magic numbers in components.63   - All storage access → only through a `storage/` layer (never call `localStorage` directly from components).64   - All provider networking → only in the `providers/` layer.65   - Naming → per the conventions above.664. **Coherence sweeps:** after Phases 3, 6, and 8 (consistent naming — always `Provider`, `AIModel`, `Conversation`, `Message`; no dead code; headers present; one reusable message/bubble component; folders match Phase 2).675. **Build early, build often.** Keep the type-checker and linter green; never accumulate more than one file of unbuilt changes.686. **Commit discipline:** one logical unit per commit, phase-prefixed. **Never commit any API keys** or `.env` with secrets.697. **Local-only is a hard invariant:** no analytics that capture prompt content, no backend calls except directly to the user's chosen provider (and an optional user-configured proxy). Keys and history never leave the device except as part of a provider request the user initiated.7071---7273## ⚠️ PHASE 0 — MANDATORY RESEARCH + ZYQUO CLOUD STUDY (DO THIS FIRST, BEFORE ANY CODE)7475Two mandatory tracks, two documents. No React until both are done.7677### 0.B — `docs/PROVIDER-REUSE.md` — study the native Zyquo Cloud repo and reuse its providers7879**Before writing provider code, read and study the native Zyquo Cloud repository** (the macOS app already built from its own CLAUDE.md). Locate it on disk (check the user's projects folder; if not found, ask the user for its path). Document and reuse:80811. **Exactly how each provider's API is called** in Zyquo Cloud: base URLs, endpoints, auth headers (`Bearer` vs `x-api-key`, `anthropic-version`, Gemini key param), request/response shapes, the shared OpenAI-compatible client, the native Anthropic (Messages API) and Gemini (`generateContent`) clients, and the SSE streaming formats. The web app must call providers the **same way**, re-implemented with the browser **`fetch` API + `ReadableStream`** for SSE (instead of URLSession).822. **The complete model catalog** (`ModelCatalog` / `docs/PROVIDERS.md`) with capabilities (vision, tools, reasoning, context, max output) and pricing. **Include ALL of these models** in the web app's catalog. Reproduce it as a typed TS catalog.833. **Provider-specific streaming/parse quirks** (Anthropic event blocks, Gemini chunks, DeepSeek/Qwen reasoning fields, Perplexity citations) so the browser streaming layer normalizes them behind one interface.844. The native app's **design tokens and UX** (light-theme flagship, layout, message rendering, model chip) so the web app matches the family look. (The web app re-implements the vault concept as plain localStorage — see the honesty note in Identity — NOT the machine-bound encryption, since a browser has no equivalent; be explicit about this difference.)8586### 0.A — `docs/CORS-MATRIX.md` — browser feasibility per provider (INTENSIVE WEB RESEARCH)8788Because calls go **directly from the browser**, you MUST research and document, per provider, the CURRENT reality:89901. **CORS support:** does the provider's API send `Access-Control-Allow-Origin` allowing direct browser calls? Test/verify from official docs and community reports for each of the 12 providers (OpenAI, Anthropic, xAI, Mistral, Gemini, Qwen/DashScope, DeepSeek, Kimi, Perplexity, Together, DeepInfra, Cerebras). Note that some providers explicitly support browser use (and may need a special header like Anthropic's `anthropic-dangerous-direct-browser-access` — verify current requirement) and some block CORS entirely.912. **Per-provider verdict:** ✅ direct browser call works / ⚠️ works with a specific header or caveat / ❌ blocked by CORS.923. **Fallback design:** for ❌/⚠️ providers, document the **optional user-configurable proxy**: a base-URL override per provider so a user can point at their own CORS proxy **or at a locally running Zyquo Router** (the family's local gateway) which exposes an OpenAI-compatible endpoint. The app ships fully client-side; the proxy is opt-in and user-supplied. Make the UI surface this clearly ("This provider can't be called directly from the browser — set a proxy URL or run Zyquo Router locally").934. **Streaming over fetch:** confirm SSE-over-`fetch` `ReadableStream` parsing works for each shape (OpenAI SSE, Anthropic events, Gemini stream) in the browser, incl. cancellation via `AbortController`.9495---9697## PHASE 1 — Project Setup (React)9899- **Stack:** **React + TypeScript (strict) + Vite**. Styling: Tailwind CSS (or CSS variables + tokens) implementing `ZyquoTheme`. State: lightweight (Zustand or React context + reducers) — no heavy framework. Routing minimal (single-page; optional hash routes for settings). Markdown: a well-maintained renderer (react-markdown + remark/rehype) with a syntax highlighter (Shiki or highlight.js) and copy buttons. No backend, no auth libraries.100- **PWA (recommended):** installable, offline shell (the app UI works offline; only provider calls need network), `manifest.webmanifest`, service worker for the app shell (NOT for caching API responses/keys).101- **Scripts:** `npm run dev`, `build`, `preview`, `lint`, `typecheck`, `check`.102- **Security posture from the start:** strict **Content-Security-Policy** (allow connections only to the known provider API origins + a user-set proxy origin; no inline scripts; no third-party script tags), Subresource Integrity where applicable, and no dependencies that aren't needed (every dependency is XSS surface for stored keys).103- **Deployment target:** static hosting (served as static assets). If deployed under the Zyquo platform, coordinate with the Node+ngrok topology on `m2u64` used by the main site, OR any static host — document in Phase 8.104105---106107## PHASE 2 — Architecture + Browser Provider Layer108109```110src/111├── main.tsx, App.tsx112├── design/            # ZyquoTheme tokens, global styles, theme (light default) + dark toggle113├── types/             # Provider, AIModel, Conversation, Message, Settings…114├── providers/         # PORTED FROM NATIVE ZYQUO CLOUD (browser fetch/stream)115│   ├── types.ts               # ProviderClient interface (send, stream)116│   ├── openaiCompatible.ts    # OpenAI, xAI, Mistral, DashScope, DeepSeek, Kimi, Perplexity, Together, DeepInfra, Cerebras, Gemini-compat117│   ├── anthropic.ts           # native Messages API + browser header118│   ├── gemini.ts              # native generateContent119│   ├── sse.ts                 # fetch + ReadableStream SSE parser, AbortController cancel120│   └── catalog.ts             # ALL models from Zyquo Cloud (typed)121├── storage/           # the ONLY place that touches localStorage/IndexedDB122│   ├── keys.ts                # get/set/remove provider keys (localStorage, namespaced)123│   ├── conversations.ts       # CRUD conversations/messages (IndexedDB for scale, or localStorage)124│   └── settings.ts            # theme, default model, per-provider proxy base URLs125├── state/             # store (Zustand): conversations, activeModel, streaming state, settings126├── features/          # ai orchestration: send message, stream, stop, regenerate, title-gen127├── components/        # UI (see Phase 4)128├── hooks/129└── lib/130```131132- **Streaming with `fetch` + `AbortController`:** parse SSE from a `ReadableStream`; normalize every provider's stream into a common token/tool/usage event; cancel on stop or when the user sends a new message.133- **PHASE GATE:** a real **streaming** completion renders token-by-token in a bare test view against at least one ✅-CORS provider, using a key from `localStorage`.134135---136137## PHASE 3 — LOCAL PERSISTENCE (KEYS + HISTORY, NO BACKEND)138139All state is local. **PHASE GATE:** keys and full conversation history survive a page reload and browser restart, and can be exported/imported.140141### 3.A — Keys (`storage/keys.ts`)142- Store per-provider keys in `localStorage` under `zyquo.cloud.web.keys` (a JSON map). Provide get/set/remove, masked display (last 4 chars), and a per-provider **Test** action.143- Optional light **obfuscation at rest** (e.g., encrypt with a key derived from a user-set passphrase via WebCrypto AES-GCM) offered as an opt-in "lock with passphrase" feature — but be honest in the UI that without a passphrase the keys are stored in plaintext, and even with one, a compromised page can read them once unlocked. Default is plain localStorage with a clear first-run notice; passphrase lock is a bonus.144145### 3.B — Conversations (`storage/conversations.ts`)146- Persist conversations and messages locally. **Prefer IndexedDB** (via a tiny wrapper or `idb`) for capacity and performance with long histories; fall back to localStorage for small data. Namespace `zyquo.cloud.web.conversations`.147- Store: conversation id, title, created/updated, model per conversation, system prompt, params, and the full message list (role, content, images as base64/blob refs, usage, reasoning, citations, timestamps).148- CRUD + search across all conversations; autosave on every change; safe migration/versioning of the stored schema.149150### 3.C — Settings & data portability151- `storage/settings.ts`: theme (light default), default model, per-provider proxy base URLs (from the CORS matrix), UI prefs.152- **Export / Import all data** (keys optional, conversations, settings) as a JSON file — the only "backup" mechanism since there's no cloud. Clearly warn that exported files may contain API keys if the user includes them.153- **Clear data** controls (per-conversation, all conversations, all keys, everything) with confirmation.154155---156157## PHASE 4 — DESIGN SYSTEM & UI (LIGHT THEME FLAGSHIP, RESPONSIVE)158159Match native Zyquo Cloud's look via the family `ZyquoTheme` tokens; **light theme is the default and flagship**, dark is a secondary opt-in toggle. The app is a chat client and must be **responsive / mobile-friendly** (usable on a phone browser).160161### 4.1 — Light theme (family standard)162Reuse Zyquo Cloud's light palette: airy off-white background (`#FAFBFD`), white surfaces, sky-indigo accent (`#4E6AF0`), 0.5pt-equivalent hairlines, ultra-soft shadows on floating elements only, generous body line-height (1.45). Typography/spacing/radii identical to the family. Dark theme derived. **Default = light**, never dark-auto.163164### 4.2 — Layout & screens165- **Shell:** a chat layout with a **sidebar** (conversations: search, new chat, pinned/date groups, rename/delete, model badge) and a **chat area** (header with editable title + centered **model chip** → the full **Model Menu** in 4.2.1; transcript; input bar). Matches native Zyquo Cloud's structure.166167#### 4.2.1 — The Model Menu (a headline surface — make it exceptional)168Clicking the model chip opens a rich, fast **command-palette-style model picker** (⌘/Ctrl+K also opens it):169- **Instant search/filter** by model name, provider, or capability; fuzzy match; keyboard-navigable (arrows + Enter), Esc to close.170- **Grouped by provider** with the provider glyph/logo, collapsible sections; a **Favorites** group pinned at top (star any model); a **Recents** group.171- **Filter chips/toggles:** Vision, Tools/Function-calling, Reasoning, JSON mode, Long-context, Cheapest, Fastest — filter the list live (data from the ported catalog capabilities).172- **Each row shows:** model name, provider, **capability badges** (👁 vision / 🛠 tools / 🧠 reasoning), **context window**, max output, and **price per 1M tokens** (in/out) from the catalog; a subtle "not configured" state if the provider has no key yet (with a quick "Add key" affordance), and a "needs proxy" flag for CORS-blocked providers.173- **Set as default**, **use for this conversation**, or **use for this one message** (regenerate with a different model right from the menu).174- **Compare picker:** a "Compare…" action to select 2–4 models for side-by-side compare mode.175- **Aliases:** user-defined friendly aliases (e.g., `fast`, `smart`) mapping to a chosen model, surfaced at the top.176- Beautiful empty/loading/error states; virtualized list so 100+ models stay instant.177- **Transcript:** user bubbles right (accent-subtle), assistant left on surface; full **Markdown** with tables, blockquotes, and **syntax-highlighted code blocks with copy**; collapsible **reasoning/"thinking"** section for reasoning models; **Perplexity citations** as numbered chips; per-message token/cost (from `usage` + catalog pricing) on hover; message actions (copy, edit & resend, regenerate — optionally with another model, delete).178- **Input bar:** floating card, multiline auto-grow, **image attach/paste** for vision-capable models (base64), attachment thumbnails, params quick-toggle, circular accent **send** (⌘/Ctrl+Enter), **Stop** during streaming.179- **Settings (modal or route):** tabs — **Providers & Keys** (per-provider masked field, Test button + status dot, proxy base URL field for ⚠️/❌ providers, the honesty notice about localStorage), **Models** (full catalog, capability badges, pricing, favorites, default model), **Appearance** (light/dark/system + accent choices + chat font size), **Data** (export/import, clear data), **Advanced** (passphrase lock toggle, streaming toggle, default params).180- **First-run:** a clean, honest welcome — "Your keys and history stay in this browser (localStorage). Add a provider key to begin." + quick model pick. Beautiful, not scary, but transparent.181- **Empty chat state:** centered Zyquo mark, greeting, a few suggested prompts, model chip.182183### 4.3 — Responsive & motion184- **Responsive:** sidebar collapses to a drawer on phones; transcript and input bar adapt full-width; ≥44pt touch targets; code blocks scroll internally; no horizontal overflow; works portrait/landscape. Mobile is a real target.185- **Motion:** smooth streaming (no jitter, blinking caret), 150ms message-in, 80ms hovers, snappy popovers, 60fps; respect `prefers-reduced-motion`.186187### 4.4 — Quality gate188Review every state at phone + desktop widths in light (default) and dark: consistent tokens, no overflow, working drawer nav, streaming, stop, error (bad key → clear message, CORS-blocked → explain proxy/Router), empty/loading, long conversation performance (virtualize the transcript if needed), export/import, passphrase lock/unlock. Confirm **light default**. If it looks templated or breaks on a phone, iterate.189190---191192## PHASE 5 — BRAND ASSETS193194- Favicon set + `manifest.webmanifest` (installable PWA) using the Zyquo mark (chunky charcoal-black Z with electric-blue base) and the Cloud accent; apple-touch-icon; `theme-color` light.195- App wordmark as crisp inline SVG (light/dark); reuse the Zyquo Cloud icon for the PWA/install icon so it matches the native app in the Dock/home screen.196- OG/social meta for the hosted URL (static image, on-brand).197198---199200## PHASE 6 — Features (Parity with native Zyquo Cloud, browser-native)201202### Cool chat features (make this genuinely delightful — go beyond a basic chat box)203- **Rich Model Menu** (Phase 4.2.1): searchable, capability-filtered, priced, favorites/recents, per-message model override, aliases.204- **Branching / regenerate variants:** regenerate a response (same or different model) and keep **multiple variants** you can swipe/tab between; branch a conversation from any message to explore alternatives without losing the original thread.205- **Edit & fork:** edit any earlier user message and re-run from that point (forking the thread); edit assistant messages for note-taking.206- **Streaming niceties:** token-by-token with a blinking caret, live **tokens/sec** and elapsed timer, **Stop** and **Continue** (ask the model to keep going), and **scroll-lock with a "jump to latest" pill**.207- **Multi-model compare mode:** send one prompt to 2–4 models side-by-side in columns, each streaming independently, with per-column copy/regenerate and a quick "promote this answer into the thread" action.208- **Prompt Library & slash commands:** ship ≥40 quality templates; type **`/`** in the input for a slash-command menu (templates, personas, tools like `/summarize`, `/translate`, `/rewrite`, `/explain`); templates support `{{variables}}` with a quick fill form.209- **Personas:** named assistants = system prompt + preferred model + params; switch persona per conversation; ship a few great defaults (Coder, Writer, Analyst, Tutor…).210- **Attachments:** drag/drop or paste **images** (vision models) with thumbnails; attach **text/code/CSV/JSON/MD files** injected as context; paste large text as a collapsible block.211- **Rich rendering:** GitHub-flavored **Markdown**, tables, task lists, footnotes; **syntax-highlighted code** with language label, copy button, and per-block "copy"/"wrap" toggles; **math via KaTeX**; **Mermaid diagram** rendering; collapsible **reasoning/"thinking"** panels; **Perplexity citations** as numbered, clickable chips.212- **Message actions:** copy (as text or Markdown), quote-reply, pin/star a message, add a note, delete, and **read-aloud** (Web Speech API TTS) with voice/speed controls; optional **speech-to-text input** (Web Speech API) for dictation.213- **Conversation tools:** auto-generated titles, **summarize this conversation**, **conversation-level search** and **in-conversation find**, tags/folders, pin, archive, duplicate, and **export a single conversation** to Markdown / JSON / (client-side) PDF; shareable **export link is NOT server-based** — export is a file since there's no backend.214- **Token & cost HUD:** live per-message and per-conversation token counts and **estimated cost** (from catalog pricing), plus a context-window usage bar showing how full the context is, with **auto-trim oldest turns** (keeping system prompt) when near the limit.215- **Parameter controls:** per-conversation temperature, top_p, max tokens, penalties, seed, JSON mode/`response_format`, and **reasoning effort** where supported — the panel only shows params the active model/provider actually supports.216- **Quality-of-life:** command palette (⌘/Ctrl+K) for everything (new chat, switch model, search, jump to conversation, run template); full keyboard shortcuts; **undo** for deletes (soft-delete + toast); autosave everywhere; offline-friendly UI shell (PWA); **retry with backoff** on transient provider errors; graceful, human error toasts (bad key names the provider, CORS-blocked explains the proxy/Router option, rate-limit shows retry).217- **Theming extras:** light default + dark toggle + a few accent choices; adjustable chat font size and message density (comfortable/compact); optional "focus mode" hiding the sidebar.218219### Core parity220- Multi-conversation local history (search, pin, rename, delete, groups) — all in IndexedDB/localStorage221- Streaming + non-streaming chat across **all 12 providers / all Cloud models** (browser fetch), model switch per conversation and per message222- Vision (image attach/paste) for capable models; text-file attach injected into messages223- System prompt per conversation + global default; per-conversation params (only those the provider supports)224- Keys + history in `localStorage`/IndexedDB with optional passphrase lock; full export/import; clear-data controls; per-provider proxy override for CORS-blocked providers (point at a local Zyquo Router)225- PWA installable; **light theme default**; fully responsive (usable on a phone browser)226227---228229## PHASE 7 — VERIFICATION (MANDATORY)230231The user will provide **real API keys** (same providers as Zyquo Cloud). You MUST:2322331. **Provider matrix (browser-side):** for **every provider/model** in the catalog, from an actual browser context, verify: non-streaming completion; **streaming** renders token-by-token; cancellation via Stop works; vision on vision-capable models; reasoning content on reasoning models; Perplexity citations. Record ✅/❌ per provider/model and the **CORS verdict** encountered (direct vs. needs-proxy). Fix everything fixable; for CORS-blocked providers, verify the **proxy/Zyquo Router fallback** path works and is clearly surfaced in the UI.2342. **Persistence:** keys and full history survive reload and browser restart; export→clear→import restores exactly; schema migration works; large-history performance is smooth (virtualization if needed).2353. **Security/privacy sanity:** confirm no key or prompt content is sent anywhere except the chosen provider (or user-set proxy) — inspect network traffic; confirm the CSP blocks unexpected origins; confirm the first-run localStorage notice is present; passphrase lock encrypts/decrypts correctly.2364. **Responsive/cross-browser:** verify on Chrome, Safari, Firefox (desktop) and iOS Safari / Android Chrome (phone): layout, streaming, drawer nav, no overflow; **light theme loads by default**.2375. Never commit or log any key; keys live only in the browser's localStorage during use.238239---240241## PHASE 8 — BUILD & DEPLOYMENT242243No notarization (it's a web app). Phase 8 is a proper **production build + static deployment**:2441. `npm run build` → optimized static bundle (code-split, hashed assets, tree-shaken, minimal JS); zero type/lint errors; PWA assets generated; CSP finalized to the exact set of provider origins (+ a placeholder for the user's proxy origin, handled at runtime).2452. **Deploy as static assets** at **`www.zyquo.cloud`** (HTTPS, apex `zyquo.cloud` → `www` redirect). If served under the Zyquo platform, use the same **Node server on `m2u64` exposed through ngrok** as the main site (bind the `www.zyquo.cloud` custom domain to the tunnel + DNS CNAME), OR any static host (Cloudflare Pages/Vercel/Netlify) as a documented alternative. Set security headers (CSP, HSTS, X-Content-Type-Options, Referrer-Policy) and long-cache for hashed assets.2463. Because it's 100% client-side, it also runs from `file://`-style local hosting or a simple static server — document how a user can self-host it, which pairs naturally with running **Zyquo Router** locally for CORS-blocked providers.2474. Post-deploy: verify HTTPS, PWA install, all provider calls from the deployed origin (CSP must allow them), light-default, and mobile.248249---250251## Engineering Standards252253- TypeScript strict; ESLint + Prettier clean; zero build warnings; minimal, audited dependencies (each is key-theft surface)254- All `localStorage`/IndexedDB access behind `storage/`; all networking behind `providers/`; components stay presentational255- Provider layer faithfully ported from native Zyquo Cloud (all models); SSE via `fetch`+`ReadableStream`+`AbortController`; robust human-readable errors (invalid key names the provider; **CORS-blocked explains the proxy/Router fallback**; rate-limit shows retry)256- Design tokens only — no hardcoded colors/sizes; **light theme default**; responsive/mobile-first friendly257- Strict CSP; never transmit keys/history anywhere but the chosen provider (or user proxy); transparent first-run notice about localStorage258- `README.md` (dev, self-host, "use with Zyquo Router") + `docs/` (PROVIDER-REUSE, CORS-MATRIX, PLAN)259- Commit in logical, phase-prefixed increments; never commit keys/secrets260261## Definition of Done262263- A React web app that reproduces Zyquo Cloud's chat experience in the browser with **no auth, no accounts, no backend**264- API **keys stored in `localStorage`** and **conversation history stored locally** (IndexedDB/localStorage), surviving reloads/restarts, with export/import and clear-data — plus an optional passphrase lock and an honest first-run notice about local storage265- Streaming + non-streaming chat across **all 12 providers / all models from native Zyquo Cloud**, called **directly from the browser**, with per-provider **CORS reality documented** and a **proxy / local Zyquo Router fallback** for blocked providers, verified with real keys (Phase 7 matrix)266- Full chat features: a rich searchable/priced **Model Menu**, per-message model override, **branching/regenerate variants**, edit & fork, **multi-model compare**, **slash commands** + prompt library, personas, Markdown + code + **KaTeX + Mermaid**, reasoning display, citations, vision, **read-aloud / dictation**, token/cost HUD + context bar with auto-trim, and a ⌘K command palette267- Deployed at **`www.zyquo.cloud`** (HTTPS, apex→www); **light theme loads by default**; dark is a secondary toggle; the app is **responsive and usable on phones**; installable PWA268- Strict CSP; keys/history never leave the device except as user-initiated provider requests269- The Zyquo mark/wordmark and Cloud accent applied consistently as crisp SVG270- **Every code file starts with the mandatory Author/Mail header** (verified by a repo-wide sweep)271- `docs/PLAN.md` shows every phase completed; PROVIDER-REUSE and CORS-MATRIX complete and traceable272- Zyquo Cloud Web feels like the legendary, private, local-only browser edition of Zyquo Cloud273