htmlboard 0.1.0 → 0.3.0

package/src/server.js

@@ -3,10 +3,12 @@ import net from 'node:net';
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import { loadDesignsManifest } from './designs.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const __dirname = path.dirname(__filename);
 const CLIENT_DIR = path.join(__dirname, 'client');
+const { version: VERSION } = JSON.parse(fs.readFileSync(path.join(__dirname, '..', 'package.json'), 'utf8'));
 
 // Supported MIME types
 const MIME_TYPES = {
@@ -30,208 +32,93 @@ const MIME_TYPES = {
   '.mp4': 'video/mp4'
 };
 
-const IGNORED_DIRS = new Set([
-  'node_modules',
-  '.git',
-  '.github',
-  'dist',
-  'build',
-  '.vscode',
-  '.idea',
-  '.gemini',
-  '.agents'
-]);
-
-/**
- * Extract <title> content from HTML text if available
- */
-function extractTitleFromHtml(content, fallbackName) {
-  const match = content.match(/<title[^>]*>([^<]+)<\/title>/i);
-  if (match && match[1]?.trim()) {
-    return match[1].trim();
-  }
-  return fallbackName
-    .replace(/\.html$/i, '')
-    .replace(/[-_]/g, ' ')
-    .replace(/\b\w/g, (c) => c.toUpperCase());
-}
-
-/** Default frame size for each category */
-const CATEGORY_SIZES = {
-  mobile: [390, 844],
-  tablet: [768, 1024],
-  components: [720, 600],
-  desktop: [1280, 800],
-  responsive: [1200, 800]
-};
-
-/**
- * Guess an artboard's category from words in its path, then from its width
- */
-export function inferCategory(file, width) {
-  const lower = file.toLowerCase();
-  if (/mobile|phone|iphone/.test(lower)) return 'mobile';
-  if (/tablet|ipad/.test(lower)) return 'tablet';
-  if (/component|\bui\b|atomic/.test(lower)) return 'components';
-  if (/desktop|laptop|screen/.test(lower)) return 'desktop';
-  if (width) {
-    if (width <= 480) return 'mobile';
-    if (width <= 1024) return 'tablet';
-    return 'desktop';
-  }
-  return 'responsive';
-}
-
-function slugify(text) {
-  return String(text).toLowerCase().normalize('NFD').replace(/[\u0300-\u036f]/g, '')
-    .replace(/[^a-z0-9]+/g, '-').replace(/^-+|-+$/g, '');
-}
-
 /** True when target is base itself or inside it */
 function isInside(base, target) {
   const rel = path.relative(base, target);
   return rel === '' || (!rel.startsWith('..') && !path.isAbsolute(rel));
 }
 
+/** Folders the watcher leaves alone: hidden ones (.git, .vscode, …) and dependencies */
+const skipWatching = (name) => name.startsWith('.') || name === 'node_modules';
+
 /**
- * Scan target directory recursively for HTML files to auto-discover
+ * Watch a folder and everything under it, calling onChange(path, isFolder) with the path (relative,
+ * with forward slashes) of every file or folder created, changed or removed.
+ * macOS and Windows watch a whole tree natively. On Linux Node emulates that with one watcher per
+ * file, which loses a file for good once it is saved by replacing it (writing a copy and renaming
+ * it over, as many editors do), so there every folder gets its own watcher instead.
+ * Returns a function that stops watching.
  */
-export function discoverDesigns(baseDir) {
-  const artboards = [];
+export function watchTree(rootDir, onChange) {
+  const relative = (full) => path.relative(rootDir, full).split(path.sep).join('/');
+  const skipped = (rel) => rel.split('/').some(skipWatching);
 
-  function scan(currentDir, relativePath = '') {
-    let entries;
-    try {
-      entries = fs.readdirSync(currentDir, { withFileTypes: true });
-    } catch {
-      return;
-    }
-
-    for (const entry of entries) {
-      if (entry.name.startsWith('.') && entry.name !== '.') continue;
-      if (IGNORED_DIRS.has(entry.name)) continue;
-
-      const fullPath = path.join(currentDir, entry.name);
-      const relPath = relativePath ? path.join(relativePath, entry.name) : entry.name;
+  if (process.platform !== 'linux') {
+    const watcher = fs.watch(rootDir, { recursive: true }, (eventType, filename) => {
+      if (!filename) return;
+      const rel = String(filename).split(path.sep).join('/');
+      if (skipped(rel)) return;
+      let isFolder;
+      try {
+        isFolder = fs.statSync(path.join(rootDir, rel)).isDirectory();
+      } catch {
+        isFolder = path.extname(rel) === ''; // gone: a name without an extension was likely a folder
+      }
+      onChange(rel, isFolder);
+    });
+    return () => watcher.close();
+  }
 
-      if (entry.isDirectory()) {
-        scan(fullPath, relPath);
-      } else if (entry.isFile() && entry.name.toLowerCase().endsWith('.html')) {
-        let title = '';
-        let fileContent = '';
+  const watchers = new Map(); // folder → its watcher
+  const unwatch = (dir) => {
+    for (const [watched, watcher] of watchers) {
+      if (watched === dir || watched.startsWith(dir + path.sep)) {
+        watcher.close();
+        watchers.delete(watched);
+      }
+    }
+  };
+  const watch = (dir) => {
+    if (watchers.has(dir)) return;
+    let watcher;
+    try {
+      watcher = fs.watch(dir, (eventType, name) => {
+        if (!name) return;
+        const full = path.join(dir, String(name));
+        const rel = relative(full);
+        if (!rel || rel.startsWith('..') || skipped(rel)) return;
+        let isDir = false;
         try {
-          fileContent = fs.readFileSync(fullPath, 'utf8');
-          title = extractTitleFromHtml(fileContent, entry.name);
+          isDir = fs.statSync(full).isDirectory();
         } catch {
-          title = entry.name;
+          // Removed
         }
-
-        const category = inferCategory(relPath);
-        const [width, height] = CATEGORY_SIZES[category];
-
-        const sectionName = relativePath ? relativePath.replace(/[\\/]/g, ' / ') : 'Root Designs';
-
-        artboards.push({
-          id: slugify(relPath.replace(/\.html$/i, '')),
-          title,
-          file: relPath.replace(/\\/g, '/'),
-          category,
-          width,
-          height,
-          sectionName,
-          tags: [category]
-        });
-      }
-    }
-  }
-
-  scan(baseDir);
-
-  // Group into sections
-  const sectionsMap = new Map();
-  for (const board of artboards) {
-    const sName = board.sectionName;
-    if (!sectionsMap.has(sName)) {
-      sectionsMap.set(sName, {
-        id: sName.toLowerCase().replace(/[^a-z0-9]+/g, '-'),
-        name: sName,
-        description: `HTML artboards discovered in ${sName}`,
-        artboards: []
+        const wasDir = watchers.has(full);
+        if (isDir) watch(full);
+        else if (wasDir) unwatch(full);
+        onChange(rel, isDir || wasDir);
       });
+    } catch {
+      return; // gone already, or unreadable
+    }
+    watcher.on('error', () => unwatch(dir));
+    watchers.set(dir, watcher);
+    let entries = [];
+    try {
+      entries = fs.readdirSync(dir, { withFileTypes: true });
+    } catch {
+      // Unreadable: its own watcher still reports what happens in it
+    }
+    for (const entry of entries) {
+      if (entry.isDirectory() && !skipWatching(entry.name)) watch(path.join(dir, entry.name));
     }
-    const { sectionName, ...rest } = board;
-    sectionsMap.get(sName).artboards.push(rest);
-  }
-
-  const projectName = path.basename(path.resolve(baseDir)) || 'Design Explorer';
-
-  return {
-    title: projectName,
-    description: 'Auto-discovered HTML artboards in workspace',
-    autoDiscovered: true,
-    sections: Array.from(sectionsMap.values())
   };
-}
 
-/**
- * Fill in what a manifest may leave out, so the explorer always gets
- * `sections[].{id, name, artboards[].{id, title, file, category}}`.
- * Accepts the short form too: `sections[].title` and `sections[].designs[]`
- * with only `{ file, title, width, height }`.
- * `prefix` is prepended to every file (the designs folder relative to the served root).
- */
-export function normalizeManifest(manifest, prefix = '') {
-  const usedIds = new Set();
-  const uniqueId = (wanted) => {
-    let id = wanted || 'artboard';
-    for (let n = 2; usedIds.has(id); n++) id = `${wanted}-${n}`;
-    usedIds.add(id);
-    return id;
+  watch(rootDir);
+  return () => {
+    for (const watcher of watchers.values()) watcher.close();
+    watchers.clear();
   };
-
-  const sections = (Array.isArray(manifest.sections) ? manifest.sections : []).map((section, i) => {
-    const name = section.name ?? section.title ?? `Section ${i + 1}`;
-    const boards = section.artboards ?? section.designs ?? [];
-    return {
-      ...section,
-      id: section.id ?? (slugify(name) || `section-${i + 1}`),
-      name,
-      artboards: boards.filter((board) => board && board.file).map((board) => {
-        const file = prefix ? path.posix.join(prefix, board.file) : board.file;
-        return {
-          ...board,
-          id: uniqueId(board.id ?? slugify(board.file.replace(/\.html?(?=$|\?)/i, ''))),
-          title: board.title ?? board.file,
-          file,
-          category: board.category ?? inferCategory(board.file.split('?')[0], board.width)
-        };
-      })
-    };
-  });
-
-  return { ...manifest, sections };
-}
-
-/**
- * Load designs configuration from designs.json or auto-discover.
- * With `rootDir` (a folder containing baseDir), artboard paths are given relative to it.
- */
-export function loadDesignsManifest(baseDir, rootDir = baseDir) {
-  const prefix = path.relative(rootDir, baseDir).split(path.sep).join('/');
-  const configPath = path.join(baseDir, 'designs.json');
-  if (fs.existsSync(configPath)) {
-    try {
-      const raw = fs.readFileSync(configPath, 'utf8');
-      const data = JSON.parse(raw);
-      return {
-        ...normalizeManifest(data, prefix),
-        autoDiscovered: false
-      };
-    } catch (err) {
-      console.warn(`[htmlboard] Failed parsing designs.json: ${err.message}. Falling back to auto-discovery.`);
-    }
-  }
-  return normalizeManifest(discoverDesigns(baseDir), prefix);
 }
 
 /**
@@ -309,7 +196,7 @@ export function createServer(options = {}) {
     // API: Health status
     if (pathname === '/api/health') {
       res.writeHead(200, { 'Content-Type': 'application/json' });
-      res.end(JSON.stringify({ status: 'ok', dir: targetDir, root: rootDir }));
+      res.end(JSON.stringify({ status: 'ok', version: VERSION, dir: targetDir, root: rootDir }));
       return;
     }
 
@@ -369,37 +256,30 @@ export function createServer(options = {}) {
     }
   }
 
-  // File watcher for live reload with debouncing
+  // Live reload. Saves come in bursts (an editor writing a file several times, an agent saving a
+  // page and its stylesheet together), so changes are collected for 100 ms and then sent once each.
+  const changed = new Map(); // path → is a folder
   let watchDebounceTimer = null;
-  let watcher = null;
+  let stopWatching = null;
 
   try {
-    watcher = fs.watch(rootDir, { recursive: true }, (eventType, filename) => {
-      if (!filename) return;
-      const normalized = filename.replace(/\\/g, '/');
-
-      // Ignore noise: hidden files and folders (.git, .vscode, …), dependencies, editor temp files
-      if (
-        normalized.split('/').some((part) => part.startsWith('.') || part === 'node_modules') ||
-        normalized.endsWith('~') ||
-        normalized.endsWith('.tmp')
-      ) {
-        return;
-      }
-
+    stopWatching = watchTree(rootDir, (file, isFolder) => {
+      if (file.endsWith('~') || file.endsWith('.tmp')) return; // editor scratch files
+      changed.set(file, isFolder);
       clearTimeout(watchDebounceTimer);
       watchDebounceTimer = setTimeout(() => {
-        const isManifest = normalized === manifestFile;
-        const isHtml = normalized.endsWith('.html');
-        const eventData = JSON.stringify({
-          type: isManifest ? 'manifest' : 'file',
-          file: normalized,
-          isHtml,
-          timestamp: Date.now()
-        });
-
-        for (const client of clients) {
-          client.write(`event: change\ndata: ${eventData}\n\n`);
+        const files = [...changed];
+        changed.clear();
+        for (const [file, isFolder] of files) {
+          const eventData = JSON.stringify({
+            type: file === manifestFile ? 'manifest' : isFolder ? 'folder' : 'file',
+            file,
+            isHtml: !isFolder && /\.html?$/i.test(file),
+            timestamp: Date.now()
+          });
+          for (const client of clients) {
+            client.write(`event: change\ndata: ${eventData}\n\n`);
+          }
         }
       }, 100);
     });
@@ -412,7 +292,8 @@ export function createServer(options = {}) {
     targetDir,
     rootDir,
     close: () => {
-      if (watcher) watcher.close();
+      clearTimeout(watchDebounceTimer);
+      if (stopWatching) stopWatching();
       for (const client of clients) {
         client.end();
       }

package/src/templates/{artboards/desktop.html → 01-screens/01-desktop.html}

@@ -4,6 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Desktop Dashboard</title>
+  <meta name="description" content="Main analytics dashboard with sidebar, metric cards, and charts">
+  <meta name="htmlboard" content="width=1280, height=820">
   <style>
     * {
       box-sizing: border-box;

package/src/templates/{artboards/mobile.html → 01-screens/02-mobile.html}

@@ -4,6 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Mobile Feed Screen</title>
+  <meta name="description" content="Smartphone screen with balance card, quick actions, and transaction feed">
+  <meta name="htmlboard" content="width=390, height=844">
   <style>
     * {
       box-sizing: border-box;

package/src/templates/{artboards/components.html → 02-components/01-ui-kit.html}

@@ -4,6 +4,8 @@
   <meta charset="UTF-8">
   <meta name="viewport" content="width=device-width, initial-scale=1.0">
   <title>Component Library Preview</title>
+  <meta name="description" content="Buttons, inputs, badges, cards, and interactive elements">
+  <meta name="htmlboard" content="width=780, height=720, category=components">
   <style>
     * {
       box-sizing: border-box;

package/src/templates/designs.json

@@ -1,50 +0,0 @@
-{
-  "title": "Design Exploration Canvas",
-  "description": "Infinite canvas and artboard explorer for HTML designs and components",
-  "sections": [
-    {
-      "id": "screens",
-      "name": "Screen Layouts",
-      "description": "Full page layouts across mobile and desktop viewports",
-      "artboards": [
-        {
-          "id": "desktop-dashboard",
-          "title": "Desktop Dashboard",
-          "description": "Main analytics dashboard with sidebar, metric cards, and charts",
-          "file": "artboards/desktop.html",
-          "width": 1280,
-          "height": 820,
-          "category": "desktop",
-          "tags": ["desktop", "dashboard", "analytics", "dark-mode"]
-        },
-        {
-          "id": "mobile-app",
-          "title": "Mobile App Feed",
-          "description": "Smartphone screen with balance card, quick actions, and transaction feed",
-          "file": "artboards/mobile.html",
-          "width": 390,
-          "height": 844,
-          "category": "mobile",
-          "tags": ["mobile", "ios", "feed", "finance"]
-        }
-      ]
-    },
-    {
-      "id": "components",
-      "name": "Component Library",
-      "description": "Reusable atomic UI blocks and design system primitives",
-      "artboards": [
-        {
-          "id": "ui-primitives",
-          "title": "UI Component Kit",
-          "description": "Buttons, inputs, badges, cards, and interactive elements",
-          "file": "artboards/components.html",
-          "width": 780,
-          "height": 720,
-          "category": "components",
-          "tags": ["design-system", "buttons", "badges", "inputs"]
-        }
-      ]
-    }
-  ]
-}