════════════════════════════════════════════════════════════════════════
  BUILD NARRATIVE
  Gnomad Webcanvas · docs/BUILD.md
════════════════════════════════════════════════════════════════════════

BUILD NARRATIVE — GNOMAD WEBCANVAS
==================================

Version: 0.1.0-beta.2  
Last updated: June 2026

────────────────────────────────────────

VISION
------

Deliver a zero-backend live code playground that feels native on desktop and works instantly in the browser — Monaco editing, real-time preview, one-click export, and shareable URLs.

────────────────────────────────────────

PHASE 1 — WEB MVP ✓
-------------------

Goal: Prove the editor + preview loop in pure React.

  Deliverable                             |  Status
  Three-pane Monaco layout (HTML/CSS/JS)  |  ✓     
  Live iframe preview with debounce       |  ✓     
  Resizable panels (vertical/horizontal)  |  ✓     
  Zustand state management                |  ✓     
  localStorage project persistence        |  ✓     
  CDN library registry                    |  ✓     
  Starter templates                       |  ✓     
  ZIP export (JSZip)                      |  ✓     

Outcome: Usable web playground at npm run dev.

────────────────────────────────────────

PHASE 2 — PREVIEW POLISH ✓
--------------------------

Goal: Production-quality preview and designer tooling.

  Deliverable                                         |  Status
  Viewport presets (mobile/tablet/desktop)            |  ✓     
  Preview pause + force refresh                       |  ✓     
  Preview fullscreen mode                             |  ✓     
  Console panel (iframe postMessage)                  |  ✓     
  Preview background modes (white/dark/checkerboard)  |  ✓     
  Font pairings + Google Fonts injection              |  ✓     
  Floating tools (color picker, CSS generator)        |  ✓     
  URL hash sharing (lz-string)                        |  ✓     
  Keyboard shortcuts + modal                          |  ✓     

Outcome: Feature-complete editor experience for demos and daily use.

────────────────────────────────────────

PHASE 3 — TAURI DESKTOP ✓
-------------------------

Goal: Native Open/Save without changing the React codebase.

  Deliverable                       |  Status
  Tauri 2 scaffold                  |  ✓     
  Platform bridge (web vs desktop)  |  ✓     
  Native open/save dialogs          |  ✓     
  Single-file HTML assemble/parse   |  ✓     
  Window title + dirty indicator    |  ✓     
  Tauri capabilities (fs, dialog)   |  ✓     
  GitHub Actions release workflow   |  ✓     

Outcome: Same UI in browser and desktop; desktop adds file I/O.

────────────────────────────────────────

PHASE 4 — DOCUMENTATION & RELEASE READINESS ✓
---------------------------------------------

Goal: Portfolio-grade docs matching Gnomad Desktop Assistant standards.

  Deliverable                           |  Status
  README overhaul                       |  ✓     
  docs/ suite (MD + HTML + TXT)         |  ✓     
  User guide, tech stack, architecture  |  ✓     
  QA checklist, release runbook         |  ✓     
  CHANGELOG, HUMAN.md                   |  ✓     

────────────────────────────────────────

PHASE 5 — QUALITY HARDENING ✓
-----------------------------

Goal: Address review feedback — tests, robust parsing, accessibility themes.

  Deliverable                      |  Status
  Vitest unit tests (19)           |  ✓     
  DOMParser-based parseHtmlFile    |  ✓     
  Shell UI themes (dark/light/hc)  |  ✓     
  Persisted theme preference       |  ✓     

────────────────────────────────────────

PHASE 6 — V1.0 (PLANNED)
------------------------

  Item                         |  Priority
  Playwright E2E smoke tests   |  P0      
  Auto-updater (Tauri plugin)  |  P1      
  macOS notarization in CI     |  P1      
  Multi-file project folders   |  P2      
  GitHub Pages demo deploy     |  P2      

See ROADMAP.md for full timeline.

────────────────────────────────────────

TECHNICAL DECISIONS
-------------------

  Decision                     |  Rationale                                  
  Zustand over Redux           |  Minimal boilerplate for editor state       
  iframe srcDoc over eval      |  Sandboxed user JS; no DOM pollution        
  Platform bridge pattern      |  Single React bundle for web + desktop      
  Single HTML file on desktop  |  Simplest Open/Save UX for v0.1             
  DOMParser for file open      |  Robust HTML parsing vs regex               
  lz-string URL sharing        |  No server; instant share in browser mode   
  Thin Rust backend            |  File I/O via plugins; defer custom commands

────────────────────────────────────────

BUILD COMMANDS REFERENCE
------------------------

  [bash]
    npm run dev          # Web dev server
    npm run tauri:dev    # Desktop dev (Vite + Tauri)
    npm run build        # Production frontend
    npm run tauri:build  # Desktop installer
    npm run lint         # ESLint
    npm run test         # Vitest unit tests
    npm run docs:export  # Regenerate HTML/TXT docs

Per-OS details: BUILD_PLATFORMS.md

────────────────────────────────────────

Built with ❤️ by Gnomad Studio 🦙

════════════════════════════════════════════════════════════════════════
Built with ❤️ by Gnomad Studio 🦙
https://gnomadstudio.org
════════════════════════════════════════════════════════════════════════