🚀 Quick Start

🌳 Knowledge Tree v0.3.0

💡 AI-powered interactive D3 topic visualizer (Production-Ready)

🛠️ Stack: Vanilla JS (ESM), D3.js v7, Python dev server (server.py) with LLM proxy, html2canvas, jsPDF, Groq / OpenRouter. No build step.

---

📂 Layout:

• index.html — Entry point & CSP
• start.command — Quick launch script
• server.py — Python dev server & LLM proxy (port 51808)
• src/scripts/: main.js (Init/Nav), tree.js (D3), ui.js (Panels), api.js (LLM), settings.js (LocalStorage), debugLog.js (Logs), utils.js (Helpers)
• src/styles/: main.css (Core), themes.css (Themes), components.css (UI styles)

---

🚀 Quick Start:

1. Copy .env.example to .env in the root: cp .env.example .env
2. Set API keys (API_KEY_GROQ, API_KEY_OPENROUTER) in .env.
3. Start the dev server: python3 server.py (or double-click ./start.command on macOS).
4. Visit http://localhost:51808.

---

✅ Features:

• 🌳 D3 Tree: Interactive zoom/pan, folding memory, and NaN/Infinity bounds safety.
• 💬 AI Panels: Preset generations (Creative/Balanced/Precise/Factual), LLM metrics, and redacted observability logs.
• 💾 State & I/O: LocalStorage config, drag-and-drop JSON import (merge/replace), and PNG/PDF/JSON/MD exports.
• ⌨️ UX & Accessibility: Undo/Redo (⌘Z/⌘⇧Z), keyboard nav, DOM-safe escaping, event listeners (no inline onclick), and dark mode.
• ♿ A11y & Focus: Unified focus-trap model (Escape closes, loops focus, restores on close) for Node, Confirm, Debug, and Import panels. Normalised WCAG 2.2 SC 2.5.8 compliant target sizes (24x24px with spacing, 44x44px for coarse pointers).
• 🏎️ Perf-UX: Reduced-motion fallback animation support; prevented transform shifts on mobile debug drawer; skeleton loader states during async AI generation.

🚨 Security:

• 🔒 DOM Safety: DOM API + escapeText() formatting only. No inline handlers.
• 🛡️ CSP: Requires unsafe-eval (D3) & unsafe-inline (Google Fonts).
• 🗃️ Secrets Protection: Keys live only in .env (never committed or exposed).

🎯 Done:

• P1: Focus-trap architecture for modals/drawers (Node, Confirm, Debug, Import) 🧯
• P2: Export menu keyboard navigation and ARIA semantics 📄
• P3: Collapsible settings intent groups and Reset-to-Defaults ⚙️
• P4: Screen-reader helpers, contrast checks, and tab-order validation ♿
• P5: Skeleton states and redraw optimization for frequent debug updates 🏎️

🔮 Roadmap:

• 🧪 Unit tests for API/settings modules.
• 🔍 Real-time node search and filter panel.
• ⚡ Virtualized D3 tree layout for massive datasets.
• 📦 Offline PWA support with local cache.

---

⌨️ Shortcuts:

Scope	Key	Action
Global	⌘Z / ⌘⇧Z (or ⌘Y)	Undo / Redo
	⌘E / ⌘O	Export / Import dialog
	⌘, / Esc	Settings panel / Close panels
Node	↑ / ↓	Navigate tree levels
	← / →	Navigate siblings
	Tab / ⇧Tab	Go to first child / Go to parent
	Enter / ⇧Enter	Fold/unfold (or extend) / Force extend
	Space / ⌘N	Open node panel / Extend children
	⌘H / ⌘I / ⌘⌫	Toggle visibility / Generate insights / Delete

---

⚙️ Config Notes:

• 🔑 API keys live in .env at the project root (API_KEY_GROQ, API_KEY_OPENROUTER). The retired config.js is deprecated and moved to obsolete/.
• 🌐 The Python server (server.py) defaults to port 51808 to proxy LLM requests and load ES modules.
• 💾 Settings persist in localStorage with XOR validation and range clamping.
• 📊 Debug logs are written to the server’s filesystem under logs/debug-{today}.jsonl.

---

🌐 Hosting & DNS:

• App URL: https://tree.loca.zone (reverse proxies to loopback port 51808)
• Wiki URL: https://wiki.tree.loca.zone (static Quartz site)
• Direct diagnostic URL: http://routa.loca.zone:51808/ (Knowledge Tree listener, not a separate Routa app)
• Reverse Proxy (Nginx):

  server_name tree.loca.zone;
  location / {
      proxy_pass http://127.0.0.1:51808;
  }

• Smoke Checks:

  curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:51808/
  curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:51808/api/config
  curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:51808/src/scripts/main.js

  (Expect 200 on all checks)

---