Proposal: App Shell & Modes¶

Status: Shipped — the skeleton this describes is live · Last updated: 2026-07-20 (status audit)

As-built note (2026-07-20): the shell shipped as scaffolding and was then redesigned — chrome/layout now per floating-glass-shell.md, the mode roster per four-modes.md, routing/front door per brochure-settings-seo.md. This doc remains the record of the original skeleton (Pages deploy, MkDocs, Playwright), not the current chrome.

Summary¶

The shared chrome every mode lives inside: top bar (logo, mode selector, cyphertap login/wallet), theming, routing, mode state, and the deployment/testing skeleton (GitHub Pages, MkDocs, Playwright).

Motivation¶

PlebChat is four mini-apps that share identity, wallet, theming, and navigation. Building the shell first — modeled on SvelteReader's proven layout — lets each mode be developed independently behind a stable frame.

Design¶

Stack: SvelteKit 2 + Svelte 5 runes, Tailwind v4, static adapter (ssr=false, prerendered shell, 404.html SPA fallback), pnpm workspace with the cyphertap submodule. Mirrors vibereader's scaffold, including the inline SvelteKit config in vite.config.ts and the NDK version override.
Modes: src/lib/stores/mode.svelte.ts — AppMode = 'chat' | 'read' | 'search' | 'synthesize' | 'debate'; every mode owns a top-level route (/chat, /read, /search, /synthesize, /debate) and Chat is the default. / is the front door: the whole-site brochure while logged out, an immediate redirect to /chat once logged in. The current mode is derived from the URL (root layout sync effect; / counts as Chat) — no localStorage persistence. ModeSelector.svelte (bits-ui popover in the top bar) switches modes; see proposals/chat-mode.md and proposals/brochure-settings-seo.md.
Theming: semantic shadcn-style tokens in src/theme.css (zinc neutrals, violet primary, dark-first via mode-watcher), mapped to Tailwind utilities with @theme inline in src/app.css. The :root:root specificity trick themes the cyphertap widget with the same palette (see cyphertap docs/THEMING.md). Palette is a placeholder decision — easy to revisit, it's ~40 lines of CSS variables.
Identity/wallet: <Cyphertap relays mints/> in the top bar; defaults in src/lib/relays.ts (our whitelisted test relay + fake testnut mint).
Docs: MkDocs Material built by CI into the same Pages artifact at /docs/ (vibereader pattern).
Testing: Playwright e2e (e2e/), chromium, dev-server based.

Reference material¶

SvelteReader frontend/src/lib/stores/mode.svelte.ts, ModeSelector.svelte, TopBar.svelte, app.css — the shell we modeled.
vibereader — scaffold, CI/Pages/MkDocs workflows, cyphertap theming overrides.
cyphertap docs/CONSUMING.md — submodule pattern, NDK override, styles import.

Open questions¶

Branding/palette: violet-on-zinc is a starting point, not a decision.
~~Custom domain~~: RESOLVED 2026-07-13 — PlebChat owns the domain root. The repo moved to plebeiusgaragicus.github.io (the user Pages site, custom domain plebchat.me) and BASE_PATH was removed everywhere; the app serves at https://plebchat.me/.
~~Mode-aware home~~: RESOLVED 2026-07-13 (issue #1) — deep links preserve modes in the path; the mode-card welcome screen is retired. Amended the same day during phase 3: Chat moved from / to /chat, and / became the front door (brochure logged out, redirect to /chat logged in) so the root stays a pure marketing/SEO surface.