add demo feature

Author: AmyJeanes

Keypad.Flasher.Client/src/ch55xbl.css

@@ -79,6 +79,17 @@
     border-color: var(--accent);
 }
 
+.btn-demo {
+    background: var(--button-bg);
+    border-color: var(--button-border);
+    color: var(--button-text);
+    box-shadow: var(--button-shadow);
+}
+
+.btn-demo:hover:not(:disabled) {
+    box-shadow: var(--button-shadow-strong);
+}
+
 .panel {
     padding: 16px;
     border-radius: 16px;
@@ -244,6 +255,12 @@
     color: var(--pill-warn-text);
 }
 
+.pill-demo {
+    background: #9a3412;
+    color: #fff7ed;
+    border: 1px solid #ea580c;
+}
+
 .detected-name {
     font-size: 18px;
     font-weight: 600;

Keypad.Flasher.Client/src/ch55xbl.tsx

@@ -2,7 +2,9 @@
 import { useCallback, useRef, useState, useEffect, useLayoutEffect } from "react";
 import {
   CH55xBootloader,
+  FakeBootloader,
   parseIntelHexBrowser,
+  type BootloaderClient,
   type ConnectedInfo,
   type Progress,
   readFileAsText,
@@ -338,6 +340,7 @@ export default function CH55xBootloaderMinimal() {
   const [status, setStatus] = useState<Status>({ state: "idle" });
   const [connectedInfo, setConnectedInfo] = useState<ConnectedInfo | null>(null);
   const [progress, setProgress] = useState<Progress>({ phase: "", current: 0, total: 0 });
+  const [demoMode, setDemoMode] = useState<boolean>(false);
   const [devMode, setDevMode] = useState<boolean>(false);
   const [debugFirmware, setDebugFirmware] = useState<boolean>(false);
   const [selectedProfile, setSelectedProfile] = useState<KnownDeviceProfile | null>(null);
@@ -361,7 +364,7 @@ export default function CH55xBootloaderMinimal() {
 
   const fileInputRef = useRef<HTMLInputElement | null>(null);
   const hiddenKeyInputRef = useRef<HTMLInputElement | null>(null);
-  const clientRef = useRef<CH55xBootloader | null>(null);
+  const clientRef = useRef<BootloaderClient | null>(null);
   const lastBootloaderIdRef = useRef<number[] | null>(null);
   const highlightTimerRef = useRef<number | null>(null);
   const removeTimerRef = useRef<Map<string, number>>(new Map());
@@ -433,6 +436,57 @@ export default function CH55xBootloaderMinimal() {
     setCurrentBindings(nextBindings);
   }, []);
 
+  const applyConnectedDevice = useCallback((info: ConnectedInfo, options: { source: "real" | "demo"; persistLastId: boolean }) => {
+    const previousId = lastBootloaderIdRef.current;
+    const sameDevice = sameBootloaderId(previousId, info.id);
+
+    if (options.persistLastId) {
+      lastBootloaderIdRef.current = info.id;
+    }
+
+    setConnectedInfo(info);
+    const profile = findProfileForBootloaderId(info.id);
+    setSelectedProfile(profile);
+
+    if (options.persistLastId) {
+      setRememberedBootloaderId(info.id);
+      saveLastBootloaderId(info.id);
+    }
+
+    const stored = loadStoredConfig(info.id);
+    if (!sameDevice || !selectedLayout) {
+      const nextLayout = stored?.layout ?? (profile?.layout ? cloneLayout(profile.layout) : null);
+      setSelectedLayout(nextLayout);
+    }
+
+    const nextBindings = stored?.bindings ?? profile?.defaultBindings ?? null;
+    if (!sameDevice || !currentBindings) {
+      setCurrentBindings(nextBindings);
+    }
+
+    const detail = profile
+      ? `${options.source === "demo" ? "Demo: " : ""}${profile.name}`
+      : (options.source === "demo" ? "Demo device" : undefined);
+    setStatus(profile ? { state: "connectedKnown", detail } : { state: "connectedUnknown", detail });
+  }, [currentBindings, selectedLayout]);
+
+  const restoreSavedConfig = useCallback(() => {
+    const id = rememberedBootloaderId ?? lastBootloaderIdRef.current;
+    if (!id) {
+      setSelectedProfile(null);
+      setSelectedLayout(null);
+      setCurrentBindings(null);
+      return;
+    }
+    const profile = findProfileForBootloaderId(id);
+    setSelectedProfile(profile);
+    const stored = loadStoredConfig(id);
+    const nextLayout = stored?.layout ?? (profile?.layout ? cloneLayout(profile.layout) : null);
+    const nextBindings = stored?.bindings ?? profile?.defaultBindings ?? null;
+    setSelectedLayout(nextLayout);
+    setCurrentBindings(nextBindings);
+  }, [rememberedBootloaderId]);
+
   const disconnectClient = useCallback(async (nextStatus?: Status, reboot?: boolean) => {
     const client = clientRef.current;
     if (client) {
@@ -442,10 +496,12 @@ export default function CH55xBootloaderMinimal() {
       await client.disconnect().catch(() => {});
     }
     clientRef.current = null;
+    setDemoMode(false);
     setConnectedInfo(null);
     setProgress({ phase: "", current: 0, total: 0 });
+    restoreSavedConfig();
     if (nextStatus) setStatus(nextStatus);
-  }, []);
+  }, [restoreSavedConfig]);
 
   const handlePassiveDisconnect = useCallback(async (detail?: string) => {
     await disconnectClient({ state: "deviceLost", detail: detail ?? "Device disconnected. Reconnect to continue." });
@@ -480,43 +536,52 @@ export default function CH55xBootloaderMinimal() {
     };
   }, [capturingStepIndex]);
 
+  const handleDemoToggle = useCallback(async () => {
+    if (demoMode) {
+      await disconnectClient({ state: "idle" });
+      return;
+    }
+
+    try {
+      setStatus({ state: "requesting", detail: "Starting demo…" });
+      if (clientRef.current) {
+        await clientRef.current.disconnect().catch(() => {});
+      }
+      const client = new FakeBootloader();
+      clientRef.current = client;
+      const info = await client.connect();
+      setDemoMode(true);
+      applyConnectedDevice(info, { source: "demo", persistLastId: false });
+    } catch (err) {
+      clientRef.current = null;
+      setDemoMode(false);
+      setStatus({ state: "error", detail: String((err as Error).message ?? "Failed to start demo mode.") });
+    }
+  }, [demoMode, disconnectClient, applyConnectedDevice]);
+
   const handleConnect = useCallback(async () => {
     if (!webUsbAvailable) {
       setStatus({ state: "error", detail: "WebUSB not available in this browser." });
       return;
     }
     try {
       setStatus({ state: "requesting" });
-      const client = clientRef.current ?? new CH55xBootloader();
+      if (demoMode && clientRef.current) {
+        await clientRef.current.disconnect().catch(() => {});
+      }
+
+      const existing = clientRef.current;
+      const client = existing instanceof CH55xBootloader ? existing : new CH55xBootloader();
       clientRef.current = client;
+
+      setDemoMode(false);
       const info = await client.connect();
-      const previousId = lastBootloaderIdRef.current;
-      const sameDevice = sameBootloaderId(previousId, info.id);
-      lastBootloaderIdRef.current = info.id;
-      setConnectedInfo(info);
-      const profile = findProfileForBootloaderId(info.id);
-      setRememberedBootloaderId(info.id);
-      saveLastBootloaderId(info.id);
-      setSelectedProfile(profile);
-      const stored = loadStoredConfig(info.id);
-      if (!sameDevice || !selectedLayout) {
-        const nextLayout = stored?.layout ?? (profile?.layout ? cloneLayout(profile.layout) : null);
-        setSelectedLayout(nextLayout);
-      }
-      const nextBindings = stored?.bindings ?? profile?.defaultBindings ?? null;
-      if (!sameDevice || !currentBindings) {
-        setCurrentBindings(nextBindings);
-      }
-      if (profile) {
-        setStatus({ state: "connectedKnown", detail: profile.name });
-      } else {
-        setStatus({ state: "connectedUnknown" });
-      }
+      applyConnectedDevice(info, { source: "real", persistLastId: true });
     } catch (e) {
       const msg = normalizeUsbErrorMessage(String((e as Error).message ?? e));
       setStatus({ state: "error", detail: msg });
     }
-  }, [webUsbAvailable, selectedLayout, currentBindings]);
+  }, [webUsbAvailable, demoMode, applyConnectedDevice]);
 
   const handleDisconnect = useCallback(async () => {
     await disconnectClient({ state: "idle" }, true);
@@ -542,10 +607,12 @@ export default function CH55xBootloaderMinimal() {
   }, [disconnectClient]);
 
   useEffect(() => {
-    const targetId = connectedInfo?.id ?? rememberedBootloaderId;
+    if (demoMode) return;
+    if (connectedInfo) return; // avoid overwriting saved presets while live-connected
+    const targetId = rememberedBootloaderId;
     if (!targetId) return;
     saveStoredConfig(targetId, { bindings: currentBindings, layout: selectedLayout });
-  }, [connectedInfo, rememberedBootloaderId, currentBindings, selectedLayout]);
+  }, [connectedInfo, rememberedBootloaderId, currentBindings, selectedLayout, demoMode]);
 
   useEffect(() => {
     if (!webUsbAvailable || typeof navigator === "undefined" || !navigator.usb) return;
@@ -563,6 +630,7 @@ export default function CH55xBootloaderMinimal() {
   }, [webUsbAvailable, handlePassiveDisconnect]);
 
   useEffect(() => {
+    if (demoMode) return;
     if (!connectedInfo || !clientRef.current) return;
     if (status.state === "flashing" || status.state === "compiling" || status.state === "requesting") return;
     let cancelled = false;
@@ -579,7 +647,7 @@ export default function CH55xBootloaderMinimal() {
       cancelled = true;
       window.clearInterval(intervalId);
     };
-  }, [connectedInfo, status.state, handlePassiveDisconnect]);
+  }, [connectedInfo, status.state, handlePassiveDisconnect, demoMode]);
 
   const handlePickFile = useCallback(() => {
     if (!clientRef.current) {
@@ -1307,6 +1375,16 @@ export default function CH55xBootloaderMinimal() {
 
         <div className="actions">
           <button onClick={handleConnect} className="btn">Connect</button>
+          {!demoMode && (
+            <button
+              onClick={handleDemoToggle}
+              className="btn btn-demo"
+              disabled={Boolean(connectedInfo)}
+              title="Start demo mode to explore the UI without connecting a real device."
+            >
+              Start Demo
+            </button>
+          )}
           {connectedInfo && (
             <button onClick={handleDisconnect} className="btn">Disconnect</button>
           )}
@@ -1355,6 +1433,7 @@ export default function CH55xBootloaderMinimal() {
             <div className="detected-card">
               <div className="detected-header">
                 <span className="pill">Detected device</span>
+                {demoMode && <span className="pill pill-demo">Demo</span>}
                 {!selectedProfile && <span className="pill pill-warn">Unknown</span>}
               </div>
               <div className="detected-name">{selectedProfile?.name ?? "Unknown device"}</div>

Keypad.Flasher.Client/src/lib/ch55x-bootloader.ts

@@ -16,6 +16,15 @@ export type ConnectedInfo = { version: string; id: number[]; deviceIdHex: string
 export type Progress = { phase: "" | "Writing" | "Verifying"; current: number; total: number };
 export type ProgressCb = (p: Progress) => void;
 
+export interface BootloaderClient {
+  connect(): Promise<ConnectedInfo>;
+  disconnect(): Promise<void>;
+  flashBinary(hexBytes: Uint8Array, onProgress?: ProgressCb): Promise<void>;
+  getConnectedDevice(): USBDevice | null;
+  ping(): Promise<void>;
+  runApplication(): Promise<void>;
+}
+
 // ===== Constants =====
 const VENDOR_ID = 0x4348;
 const PRODUCT_ID = 0x55e0;
@@ -155,7 +164,7 @@ export function parseIntelHexBrowser(data: string, bufferSize: number): {
 }
 
 // ===== Core class =====
-export class CH55xBootloader {
+export class CH55xBootloader implements BootloaderClient {
   public uploadReady = false;
   public bootloaderDeviceID: number | null = null;
   private device: USBDevice | null = null;
@@ -392,6 +401,68 @@ export class CH55xBootloader {
   }
 }
 
+// ===== Demo/fake bootloader for UI previews =====
+const DEMO_BOOTLOADER_ID = [126, 80, 44, 189];
+const DEMO_DEVICE_ID_HEX = "0xd3f0";
+const DEMO_VERSION = "9.9.9";
+const DEMO_STEPS = 120;
+const DEMO_STEP_DELAY_MS = 3;
+
+export class FakeBootloader implements BootloaderClient {
+  private connected = false;
+  private readonly bootloaderId: number[];
+  private readonly stepDelayMs: number;
+
+  constructor(opts: { bootloaderId?: number[]; stepDelayMs?: number } = {}) {
+    this.bootloaderId = opts.bootloaderId ?? DEMO_BOOTLOADER_ID;
+    this.stepDelayMs = opts.stepDelayMs ?? DEMO_STEP_DELAY_MS;
+  }
+
+  private ensureConnected() {
+    if (!this.connected) throw new Error("Demo bootloader not connected.");
+  }
+
+  async connect(): Promise<ConnectedInfo> {
+    this.connected = true;
+    return { version: DEMO_VERSION, id: [...this.bootloaderId], deviceIdHex: DEMO_DEVICE_ID_HEX };
+  }
+
+  async disconnect(): Promise<void> {
+    this.connected = false;
+  }
+
+  getConnectedDevice(): USBDevice | null {
+    return null;
+  }
+
+  async ping(): Promise<void> {
+    this.ensureConnected();
+  }
+
+  async runApplication(): Promise<void> {
+    this.connected = false;
+  }
+
+  async flashBinary(_hexBytes: Uint8Array, onProgress?: ProgressCb): Promise<void> {
+    this.ensureConnected();
+
+    const writeTotal = DEMO_STEPS;
+    onProgress?.({ phase: "Writing", current: 0, total: writeTotal });
+    for (let i = 0; i < writeTotal; i += 1) {
+      await new Promise((resolve) => window.setTimeout(resolve, this.stepDelayMs));
+      onProgress?.({ phase: "Writing", current: i + 1, total: writeTotal });
+    }
+
+    onProgress?.({ phase: "Verifying", current: 0, total: writeTotal });
+    for (let i = 0; i < writeTotal; i += 1) {
+      await new Promise((resolve) => window.setTimeout(resolve, this.stepDelayMs));
+      onProgress?.({ phase: "Verifying", current: i + 1, total: writeTotal });
+    }
+
+    onProgress?.({ phase: "", current: 0, total: 0 });
+  }
+}
+
 // ===== Small utils for consumers =====
 export async function readFileAsText(file: File): Promise<string> {
   return new Promise((resolve, reject) => {