feat: standardize theme toggle and README education structure

Author: systemslibrarian

README.md

@@ -4,74 +4,44 @@
 
 **[Live Demo](https://systemslibrarian.github.io/crypto-lab-format-ward/)**
 
-## Overview
+## 1. What It Is
 
-Format Ward is a browser-based crypto lab demo for format-preserving encryption (FPE) using FF1 and FF3-1 from NIST SP 800-38G.
+Format Ward is a browser demo of format-preserving encryption using FF1 and FF3-1 with WebCrypto AES-CBC rounds in a Feistel construction. It solves the problem of protecting sensitive fields while keeping the original character set and field shape, so existing schema constraints continue to work. In this codebase, encryption and decryption are shown for PAN, SSN/phone/ZIP-style formats, and custom alphabets. This is a symmetric-key model: the same secret key material is required for both encryption and decryption.
 
-The demo shows how sensitive values (credit cards, SSNs, phone numbers, ZIP codes, and custom-alphabet strings) can be encrypted while preserving original format constraints so legacy schema assumptions do not break.
+## 2. When to Use It
 
-Primary standards references:
+- Legacy databases with strict field validation: FF1/FF3-1 let you encrypt values while preserving the original format, so downstream validators and fixed-width schemas continue to accept the data.
+- PAN tokenization workflows: preserving decimal length and structure helps payment pipelines that cannot immediately migrate away from format-bound interfaces.
+- Masked analytics for structured identifiers: FF1 can protect only the digit positions in SSN/phone-style strings while keeping separators in place for operational readability.
+- Cross-system data sharing where format compatibility is mandatory: custom-alphabet FF1 keeps agreed symbol sets and length invariant across parties.
+- Do not use this when you need authenticated encryption by itself: FF1/FF3-1 preserve format but do not replace integrity/authenticity controls at the protocol layer.
 
-- NIST SP 800-38G: https://csrc.nist.gov/pubs/sp/800/38/g/final
-- NIST SP 800-38G Rev.1 (FF3-1): https://csrc.nist.gov/pubs/sp/800/38/g/r1/final
+## 3. Live Demo
 
-## What You Can Explore
+Live GitHub Pages demo: https://systemslibrarian.github.io/crypto-lab-format-ward/
 
-1. Credit Card Tokenization panel
-2. SSN / Phone / Postal format masking panel
-3. FF1 vs FF3-1 side-by-side timing and output comparison
-4. Custom alphabet FF1 encryption and decryption
+The demo supports both encrypt and decrypt flows in each panel and displays round-trip results so you can verify reversibility. You can run FF1 and FF3-1 side-by-side, compare output and timing, and inspect Luhn validity behavior on ciphertext for PAN examples. Exposed controls include plaintext/format selectors, AES-256 key generation, FF1 tweak input, FF3-1 tweak input (14 hex chars), and custom alphabet selection.
 
-## Primitives Used
+## 4. What Can Go Wrong
 
-- FF1 (NIST SP 800-38G)
-- FF3-1 (NIST SP 800-38G Rev.1)
-- AES via WebCrypto (`AES-CBC`) as the underlying block primitive
-- Feistel round structure per standard mode definitions
+- FF3-1 margin assumptions: FF3-1 has published differential-cryptanalysis results relative to FF1, which is why this demo marks FF1 as the preferred default for new systems.
+- Wrong tweak size for FF3-1: FF3-1 requires exactly a 56-bit tweak (14 hex chars), and using the wrong length breaks interoperability and security assumptions.
+- Small-domain misuse: very small message spaces reduce effective security for format-preserving schemes because exhaustive or statistical attacks become more practical.
+- Deterministic reuse patterns: reusing the same key/tweak configuration on repeated structured fields can leak equality patterns even though plaintext is hidden.
+- Alphabet/radix mismatch bugs: if application characters and radix mapping are inconsistent, encryption can fail or silently produce invalid domain behavior for downstream systems.
 
-## Running Locally
+## 5. Real-World Usage
 
-```bash
-npm install
-npm run dev
-```
-
-Build and preview:
-
-```bash
-npm run build
-npm run preview
-```
-
-## GitHub Pages
-
-The Vite base path is resolved automatically during GitHub Actions builds from `GITHUB_REPOSITORY`, so project-page deploys keep working after forks or repository renames.
-
-If you need to override it manually, set `PAGES_BASE_PATH` before building.
-
-Run vector checks:
-
-```bash
-npm run test
-```
-
-## Security Notes
-
-- FF1 is the preferred choice for new deployments in this demo.
-- FF3-1 has known differential-attack literature and reduced margin compared to FF1.
-- The FF3/FF3-1 line of analysis was highlighted by Durak & Vaudenay (2017); this demo surfaces that caveat directly in UI and documentation.
-- Always treat demo code as educational and validate operational choices against your threat model and compliance requirements.
-
-## Why This Matters
-
-Many production systems cannot change field lengths or character constraints without expensive schema and integration rewrites.
-
-FPE allows encryption while preserving the visible format shape, which is useful for tokenization, safe analytics, and controlled data sharing in constrained legacy environments.
+- NIST SP 800-38G and SP 800-38G Rev.1: these standards define FF1 and FF3-1 and are the baseline references used by compliant implementations.
+- PCI-oriented tokenization deployments: payment environments commonly use NIST FPE modes (especially FF1) to protect PAN data without breaking numeric format constraints.
+- OpenText Voltage SecureData: this enterprise data-protection platform documents format-preserving encryption deployments for structured fields.
+- Protegrity data protection platforms: Protegrity materials describe FPE usage for structured-data tokenization in regulated environments.
+- Application security toolkits such as Bouncy Castle: widely used libraries include FF1/FF3-1 primitives that are integrated into production JVM systems handling structured identifiers.
 
 ## Related Demos
 
 - crypto-compare (Format-Preserving Encryption category): https://github.com/systemslibrarian/crypto-compare
 - crypto-lab landing page: https://github.com/systemslibrarian/crypto-lab
 - crypto-lab-iron-letter: https://github.com/systemslibrarian/crypto-lab-iron-letter
 
-So whether you eat or drink or whatever you do, do it all for the glory of God. — 1 Corinthians 10:31
+> *"So whether you eat or drink or whatever you do, do it all for the glory of God." — 1 Corinthians 10:31*

index.html

@@ -1,16 +1,21 @@
 <!doctype html>
 <html lang="en">
   <head>
+    <script>
+      (function () {
+        const saved = localStorage.getItem('theme');
+        document.documentElement.setAttribute('data-theme', saved ?? 'dark');
+      })();
+    </script>
     <meta charset="UTF-8" />
     <meta name="viewport" content="width=device-width, initial-scale=1.0, viewport-fit=cover" />
     <meta name="description" content="Format Ward — Interactive browser demo of Format-Preserving Encryption (FF1 and FF3-1) over real WebCrypto AES rounds, per NIST SP 800-38G." />
-    <meta name="theme-color" content="#0a1216" media="(prefers-color-scheme: dark)" />
-    <meta name="theme-color" content="#f8fbff" media="(prefers-color-scheme: light)" />
+    <meta name="theme-color" content="#0a1216" />
     <title>Format Ward | crypto-lab-format-ward</title>
     <link rel="stylesheet" href="./styles/main.css" />
   </head>
   <body>
     <div id="app"></div>
-    <script type="module" src="./src/ui.ts"></script>
+    <script type="module" src="./src/main.ts"></script>
   </body>
 </html>

src/main.ts

@@ -1,2 +1,28 @@
-// Entry placeholder kept to match repo structure.
-export {};
+import { initUI } from "./ui";
+
+function installThemeToggle(): void {
+	const root = document.documentElement;
+	const button = document.getElementById("theme-toggle") as HTMLButtonElement | null;
+	if (!button) {
+		return;
+	}
+
+	const syncThemeButton = (): void => {
+		const isDark = root.getAttribute("data-theme") !== "light";
+		button.textContent = isDark ? "🌙" : "☀️";
+		button.setAttribute("aria-label", isDark ? "Switch to light mode" : "Switch to dark mode");
+	};
+
+	syncThemeButton();
+
+	button.addEventListener("click", () => {
+		const current = root.getAttribute("data-theme") === "light" ? "light" : "dark";
+		const next = current === "dark" ? "light" : "dark";
+		root.setAttribute("data-theme", next);
+		localStorage.setItem("theme", next);
+		syncThemeButton();
+	});
+}
+
+initUI();
+installThemeToggle();

src/ui.ts

@@ -30,7 +30,6 @@ function setText(id: string, text: string): void {
     el.textContent = text;
   }
 }
-
 function getInputValue(id: string): string {
   const el = document.getElementById(id) as HTMLInputElement | null;
   if (!el) {
@@ -120,35 +119,6 @@ async function runVectorSmokeCheck(): Promise<void> {
   }
 }
 
-function installThemeToggle(): void {
-  const button = document.getElementById("theme-toggle") as HTMLButtonElement | null;
-  const root = document.documentElement;
-
-  const saved = localStorage.getItem("format-ward-theme");
-  if (saved === "light" || saved === "dark") {
-    root.dataset.theme = saved;
-  } else {
-    root.dataset.theme = "dark";
-  }
-
-  const syncLabel = (): void => {
-    const isDark = root.dataset.theme !== "light";
-    if (button) {
-      button.textContent = isDark ? "🌙" : "☀️";
-      button.setAttribute("aria-label", isDark ? "Switch to light mode" : "Switch to dark mode");
-    }
-  };
-
-  syncLabel();
-
-  button?.addEventListener("click", () => {
-    const next = root.dataset.theme === "light" ? "dark" : "light";
-    root.dataset.theme = next;
-    localStorage.setItem("format-ward-theme", next);
-    syncLabel();
-  });
-}
-
 function wireKeyGenerators(): void {
   const pairs: Array<{ buttonId: string; inputId: string }> = [
     { buttonId: "cc-key-gen", inputId: "cc-key" },
@@ -306,7 +276,7 @@ function template(): string {
       <header class="hero" role="banner">
         <div class="chip-row" role="list" aria-label="Category and controls">
           <span class="chip category" role="listitem">Format-Preserving Encryption</span>
-          <button id="theme-toggle" class="theme-toggle" type="button" aria-label="Switch color theme"></button>
+          <button id="theme-toggle" class="theme-toggle" type="button" aria-label="Switch to light mode"></button>
         </div>
         <h1>Format Ward</h1>
         <p class="subtitle">Interactive FF1 and FF3-1 demo over real WebCrypto AES rounds from NIST SP 800-38G.</p>
@@ -494,13 +464,10 @@ export function initUI(): void {
   }
 
   app.innerHTML = template();
-  installThemeToggle();
   wireKeyGenerators();
   wirePanel1();
   wirePanel2();
   wirePanel3();
   wirePanel4();
   runVectorSmokeCheck();
 }
-
-initUI();

styles/main.css

@@ -38,24 +38,6 @@
   --focus-ring: var(--accent-2);
 }
 
-/* Respect system-level preference when no JS theme is stored */
-@media (prefers-color-scheme: light) {
-  :root:not([data-theme]) {
-    --bg: #f8fbff;
-    --bg-soft: #e6f0fa;
-    --surface: #ffffff;
-    --surface-2: #f0f6fd;
-    --text: #10222d;
-    --muted: #4e6370;
-    --accent: #ef6f00;
-    --accent-2: #0f9b8e;
-    --danger: #b13030;
-    --border: #c6d8e7;
-    --shadow: rgba(20, 30, 40, 0.12);
-    --focus-ring: var(--accent-2);
-  }
-}
-
 /* ── Reset ── */
 *,
 *::before,