@noy4/docserve 0.1.0

package/bin.mjs

@@ -0,0 +1,217 @@
+#!/usr/bin/env node
+// docserve — serve a folder of HTML as a card gallery with live reload.
+//
+//   docserve [dir] [command] [options]
+//
+// Flow:
+//   parse args ──▶ stop / status ──▶ state.json
+//   └─ start
+//      ├─ single-instance check (readLiveState)
+//      ├─ --background ──▶ spawn detached ──▶ wait for state.json
+//      └─ foreground ──▶ runServer() (writes state.json on bind)
+import fs from "node:fs"
+import path from "node:path"
+import { exec, spawn } from "node:child_process"
+import { fileURLToPath } from "node:url"
+import { parseArgs } from "node:util"
+import { runServer } from "./server/index.mjs"
+import { clearState, readLiveState } from "./server/state.mjs"
+
+const pkg = JSON.parse(fs.readFileSync(new URL("./package.json", import.meta.url), "utf8"))
+const VERSION = pkg.version
+const DEFAULT_PORT = 4242
+const SUBCOMMANDS = ["stop", "status"]
+
+const HELP = `
+docserve v${VERSION} — serve a folder of HTML as a card gallery with live reload.
+
+Usage:
+  docserve [dir] [command] [options]
+
+Arguments:
+  dir                Folder of HTML files to serve (default: current directory)
+
+Commands:
+  stop               Stop the running docserve server
+  status             Show whether a server is running (exit 1 if none)
+
+Options:
+  --open             Open the gallery in the browser once the port is bound
+  --port <number>    Port to bind (default: ${DEFAULT_PORT}); falls back +1 up to 20 tries
+  --background       Start detached; the bound port and pid land in state.json
+  -h, --help         Show this help
+  -v, --version      Show version
+`
+
+async function main() {
+  const args = parseCliArgs()
+  if (args.command === "stop") return stopServer()
+  if (args.command === "status") return showStatus()
+  return startServer(args)
+}
+
+function parseCliArgs() {
+  let parsed
+  try {
+    parsed = parseArgs({
+      allowPositionals: true,
+      options: {
+        open: { type: "boolean" },
+        port: { type: "string" },
+        background: { type: "boolean" },
+        help: { type: "boolean", short: "h" },
+        version: { type: "boolean", short: "v" },
+      },
+    })
+  } catch (err) {
+    console.error(`[docserve] ${err.message}`)
+    console.error(HELP)
+    process.exit(1)
+  }
+  if (parsed.values.help) {
+    console.log(HELP)
+    process.exit(0)
+  }
+  if (parsed.values.version) {
+    console.log(VERSION)
+    process.exit(0)
+  }
+
+  let dir = null
+  let command = null
+  for (const positional of parsed.positionals) {
+    if (dir === null && command === null && SUBCOMMANDS.includes(positional)) {
+      command = positional
+      continue
+    }
+    if (dir === null) {
+      dir = positional
+      continue
+    }
+    if (command === null && SUBCOMMANDS.includes(positional)) {
+      command = positional
+      continue
+    }
+    console.error(`[docserve] Unexpected argument "${positional}".`)
+    process.exit(1)
+  }
+
+  let port = DEFAULT_PORT
+  if (parsed.values.port !== undefined) {
+    port = Number(parsed.values.port)
+    if (!Number.isInteger(port) || port < 1 || port > 65535) {
+      console.error(`[docserve] --port expects an integer between 1 and 65535, got "${parsed.values.port}"`)
+      process.exit(1)
+    }
+  }
+
+  return {
+    dir,
+    command,
+    port,
+    open: parsed.values.open ?? false,
+    background: parsed.values.background ?? false,
+  }
+}
+
+function stopServer() {
+  const state = readLiveState() // stale state (dead pid) is removed silently
+  if (!state) {
+    console.log("docserve is not running.")
+    return
+  }
+  try {
+    process.kill(state.pid, "SIGTERM")
+  } catch {}
+  clearState()
+  console.log(`Stopped docserve (${state.url})`)
+}
+
+function showStatus() {
+  const state = readLiveState()
+  if (!state) {
+    console.error("docserve is not running.")
+    process.exit(1)
+  }
+  console.log(state.url)
+  console.log(`docs : ${state.docsDir}`)
+}
+
+async function startServer(args) {
+  const docsDir = path.resolve(args.dir ?? ".")
+  if (!isDirectory(docsDir)) {
+    console.error(`[docserve] Directory not found: ${docsDir}`)
+    process.exit(1)
+  }
+
+  // Single instance: same docsDir just opens its URL; a different docsDir
+  // requires docserve stop first.
+  const running = readLiveState()
+  if (running) {
+    if (running.docsDir === docsDir) {
+      if (args.open) openBrowser(running.url)
+      console.log(`docserve is already serving this folder: ${running.url}`)
+      return
+    }
+    console.error([
+      "[docserve] A server is already running for a different folder.",
+      `  url  : ${running.url}`,
+      `  docs : ${running.docsDir}`,
+      "Stop it first: docserve stop",
+    ].join("\n"))
+    process.exit(1)
+  }
+
+  if (args.background) return startBackground(args, docsDir)
+
+  console.log(`docserve v${pkg.version}`)
+  console.log(`docs : ${docsDir}`)
+  await runServer({ docsDir, port: args.port, open: args.open })
+}
+
+async function startBackground(args, docsDir) {
+  const entry = fileURLToPath(import.meta.url)
+  const childArgs = [entry, docsDir]
+  if (args.open) childArgs.push("--open")
+  if (args.port !== DEFAULT_PORT) childArgs.push("--port", String(args.port))
+  const child = spawn(process.execPath, childArgs, { detached: true, stdio: "ignore" })
+  child.unref()
+
+  const state = await waitForState()
+  if (!state) {
+    console.error("[docserve] Server did not report startup (no state file). Try running in the foreground.")
+    process.exit(1)
+  }
+  console.log("docserve started in the background")
+  console.log(`  pid  : ${state.pid}`)
+  console.log(`  url  : ${state.url}`)
+  console.log(`  docs : ${state.docsDir}`)
+  console.log("  stop : docserve stop")
+}
+
+async function waitForState({ timeoutMs = 10000, intervalMs = 200 } = {}) {
+  const deadline = Date.now() + timeoutMs
+  while (Date.now() < deadline) {
+    const state = readLiveState()
+    if (state) return state
+    await new Promise((resolve) => setTimeout(resolve, intervalMs))
+  }
+  return null
+}
+
+function openBrowser(url) {
+  if (process.platform === "darwin") exec(`open ${url}`)
+}
+
+function isDirectory(path) {
+  try {
+    return fs.statSync(path).isDirectory()
+  } catch {
+    return false
+  }
+}
+
+main().catch((err) => {
+  console.error(err?.message ?? err)
+  process.exit(1)
+})

package/index.html

@@ -0,0 +1,343 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1.0">
+<title>docserve</title>
+<link rel="icon" href="data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%236c8cff' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'%3E%3Cpath d='M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z'/%3E%3Cpath d='M14 2v6h6'/%3E%3Cpath d='M8 13h8M8 17h5'/%3E%3C/svg%3E">
+<style>
+  :root {
+    --bg: #0f1117;
+    --card: #1a1d27;
+    --border: #2a2e3d;
+    --text: #e6e8ee;
+    --muted: #9aa0b0;
+    --accent: #6c8cff;
+    --green: #4ade80;
+    --btn-bg: rgba(15, 17, 23, 0.82);
+  }
+  @media (prefers-color-scheme: light) {
+    :root {
+      --bg: #f8fafc;
+      --card: #ffffff;
+      --border: #e2e8f0;
+      --text: #334155;
+      --muted: #64748b;
+      --accent: #2563eb;
+      --green: #16a34a;
+      --btn-bg: rgba(255, 255, 255, 0.85);
+  }
+  }
+
+  * { box-sizing: border-box; margin: 0; padding: 0; }
+
+  body {
+    background: var(--bg);
+    color: var(--text);
+    font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", "Hiragino Sans", "Noto Sans JP", sans-serif;
+    padding: 40px 24px;
+  }
+
+  h1 {
+    display: flex;
+    align-items: center;
+    gap: 10px;
+    font-size: 1.6rem;
+    margin-bottom: 8px;
+  }
+  h1 svg { width: 26px; height: 26px; color: var(--accent); flex-shrink: 0; }
+  .sub { color: var(--muted); margin-bottom: 32px; font-size: 0.9rem; }
+  .sub b { color: var(--green); }
+
+  .sub code {
+    font-family: ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, "Liberation Mono", "Courier New", monospace;
+    font-size: 0.78rem;
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 6px;
+    padding: 2px 8px;
+    word-break: break-all;
+  }
+
+  .grid {
+    display: grid;
+    grid-template-columns: repeat(auto-fill, minmax(240px, 1fr));
+    gap: 16px;
+  }
+
+  .card {
+    display: flex;
+    flex-direction: column;
+    overflow: hidden;
+    background: var(--card);
+    border: 1px solid var(--border);
+    border-radius: 12px;
+    color: inherit;
+    text-decoration: none;
+    transition: transform 0.15s ease, border-color 0.15s ease;
+  }
+
+  .card:hover { border-color: var(--accent); }
+
+  .preview {
+    position: relative;
+    height: 160px;
+    overflow: hidden;
+    background: #fff;
+  }
+
+  .preview iframe {
+    border: 0;
+    transform-origin: top left;
+    pointer-events: none;
+  }
+
+  .preview::after {
+    content: "";
+    position: absolute;
+    inset: 0;
+  }
+
+  .copy-btn {
+    position: absolute;
+    top: 8px;
+    right: 8px;
+    z-index: 1;
+    display: grid;
+    place-items: center;
+    width: 26px;
+    height: 26px;
+    padding: 0;
+    border: 1px solid var(--border);
+    border-radius: 7px;
+    background: var(--btn-bg);
+    color: var(--text);
+    cursor: pointer;
+    opacity: 0;
+    transition: opacity 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+  }
+
+  .copy-btn svg { width: 13px; height: 13px; }
+  .copy-btn .ic-check { display: none; }
+  .card:hover .copy-btn { opacity: 1; }
+  .copy-btn:hover { border-color: var(--accent); color: var(--accent); }
+  .copy-btn.copied { color: var(--green); border-color: var(--green); }
+  .copy-btn.copied .ic-copy { display: none; }
+  .copy-btn.copied .ic-check { display: block; }
+
+  @media (hover: none) {
+    .copy-btn { opacity: 0.7; }
+  }
+
+  .meta {
+    display: flex;
+    flex: 1;
+    flex-direction: column;
+    justify-content: space-between;
+    gap: 6px;
+    padding: 10px 12px;
+    border-top: 1px solid var(--border);
+  }
+
+  .meta .title { font-size: 0.85rem; font-weight: 600; line-height: 1.4; }
+  .date { font-size: 0.7rem; color: var(--muted); }
+
+  .empty {
+    max-width: 480px;
+    margin: 48px auto;
+    padding: 32px 24px;
+    border: 1px dashed var(--border);
+    border-radius: 12px;
+    color: var(--muted);
+    text-align: center;
+  }
+
+  .empty b { color: var(--text); }
+</style>
+</head>
+
+<body>
+  <h1>
+    <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M14 2H6a2 2 0 0 0-2 2v16a2 2 0 0 0 2 2h12a2 2 0 0 0 2-2V8z"/><path d="M14 2v6h6"/><path d="M8 13h8M8 17h5"/></svg>
+    docserve
+  </h1>
+  <p class="sub">
+    <code id="docs-dir">__DOCSERVE_DIR__</code> - <b id="total">0</b> files
+  </p>
+
+  <div class="grid" id="grid" hidden></div>
+
+  <div class="empty" id="empty" hidden>
+    <b>No HTML files found</b>
+    <p>Place .html files in <code id="empty-dir"></code> and they will appear here automatically</p>
+  </div>
+
+<script type="module">
+  const VIEWPORT_W = 960
+  const VIEWPORT_H = 900
+
+  function el(tag, props = {}, children = []) {
+    const node = document.createElement(tag)
+    for (const [key, value] of Object.entries(props)) {
+      if (value == null || value === false) continue
+      if (key === "class") node.className = value
+      else if (key === "text") node.textContent = value
+      else if (key === "html") node.innerHTML = value
+      else if (key === "style" && typeof value === "object") Object.assign(node.style, value)
+      else if (key.startsWith("on") && typeof value === "function") node.addEventListener(key.slice(2).toLowerCase(), value)
+      else node.setAttribute(key, value === true ? "" : String(value))
+    }
+    for (const child of Array.isArray(children) ? children : [children]) {
+      if (child == null || child === false) continue
+      node.append(child)
+    }
+    return node
+  }
+
+  function icon(paths, { width = 2, class: name = "" } = {}) {
+    return `<svg${name ? ` class="${name}"` : ""} viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="${width}" stroke-linecap="round" stroke-linejoin="round">${paths}</svg>`
+  }
+
+  const COPY_SVG = icon('<rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/>', { class: "ic-copy" })
+  const CHECK_SVG = icon('<polyline points="20 6 9 17 4 12"/>', { class: "ic-check", width: 2.5 })
+
+  class PreviewLoader {
+    queue = []
+    active = 0
+    max = 3
+    observer
+
+    constructor({ max = 3, rootMargin = "400px" } = {}) {
+      this.max = max
+      this.observer = new IntersectionObserver((entries) => {
+        for (const entry of entries) {
+          if (!entry.isIntersecting) continue
+          this.observer.unobserve(entry.target)
+          const preview = entry.target
+          const iframe = preview.querySelector("iframe")
+          const src = iframe?.dataset.src
+          if (iframe && src) this.enqueue(iframe, src)
+        }
+      }, { rootMargin })
+    }
+
+    watch(preview) {
+      this.observer.observe(preview)
+    }
+
+    enqueue(iframe, src) {
+      this.queue.push({ iframe, src })
+      this.pump()
+    }
+
+    pump() {
+      while (this.active < this.max && this.queue.length) {
+        const item = this.queue.shift()
+        if (!item) return
+        this.active++
+        item.iframe.addEventListener(
+          "load",
+          () => {
+            this.active--
+            this.pump()
+          },
+          { once: true },
+        )
+        item.iframe.src = item.src
+      }
+    }
+  }
+
+  const previews = new PreviewLoader()
+
+  function fitPreviews() {
+    for (const el of document.querySelectorAll(".preview")) {
+      const iframe = el.querySelector("iframe")
+      if (!iframe) continue
+      iframe.style.width = `${VIEWPORT_W}px`
+      iframe.style.height = `${VIEWPORT_H}px`
+      iframe.style.transform = `scale(${el.clientWidth / VIEWPORT_W})`
+    }
+  }
+
+  function displayDate(value) {
+    const date = new Date(typeof value === "number" ? value * 1000 : value)
+    if (Number.isNaN(date.getTime())) return ""
+    return `${date.getFullYear()}/${String(date.getMonth() + 1).padStart(2, "0")}/${String(date.getDate()).padStart(2, "0")}`
+  }
+
+  function card(file) {
+    return el("a", { class: "card", href: file.url, target: "_blank", rel: "noopener" }, [
+      el("div", { class: "preview" }, [
+        el("iframe", { tabindex: -1, title: file.title ?? "", "data-src": file.url }),
+        el("button", {
+          type: "button",
+          class: "copy-btn",
+          title: file.path,
+          "aria-label": "Copy file path",
+          html: COPY_SVG + CHECK_SVG,
+          onclick: async (e) => {
+            const btn = e.currentTarget
+            e.preventDefault()
+            e.stopPropagation()
+            try {
+              await navigator.clipboard.writeText(btn.title)
+              btn.classList.add("copied")
+              setTimeout(() => btn.classList.remove("copied"), 1200)
+            } catch {}
+          },
+        }),
+      ]),
+      el("div", { class: "meta" }, [
+        el("div", { class: "title", text: file.title }),
+        el("div", { class: "date", text: displayDate(file.created) }),
+      ]),
+    ])
+  }
+
+  async function load() {
+    const docsDir = document.getElementById("docs-dir").textContent
+    document.getElementById("empty-dir").textContent = docsDir
+
+    let files = []
+    try {
+      const res = await fetch("/api/files")
+      files = await res.json()
+    } catch {}
+    if (!Array.isArray(files)) files = []
+
+    document.getElementById("total").textContent = String(files.length)
+    if (files.length === 0) {
+      document.getElementById("empty").hidden = false
+      return
+    }
+
+    const grid = document.getElementById("grid")
+    for (const f of files) grid.appendChild(card(f))
+    grid.hidden = false
+
+    for (const preview of grid.querySelectorAll(".preview")) {
+      previews.watch(preview)
+    }
+    fitPreviews()
+    new ResizeObserver(fitPreviews).observe(grid)
+  }
+
+  function connectLiveReload() {
+    // Reload when the set of files changes; a dropped socket recovers after restart.
+    const ws = new WebSocket(`${location.protocol === "https:" ? "wss:" : "ws:"}//${location.host}/__reload`)
+    ws.addEventListener("message", (e) => {
+      let change
+      try { change = JSON.parse(e.data) } catch { return }
+      if (change?.type === "change" && change.contentSetChanged) location.reload()
+    })
+    ws.addEventListener("close", () => setTimeout(() => location.reload(), 1000))
+  }
+
+  window.addEventListener("resize", fitPreviews)
+  document.fonts?.ready.then(fitPreviews)
+  load()
+  connectLiveReload()
+</script>
+</body>
+</html>

package/package.json

@@ -0,0 +1,37 @@
+{
+  "name": "@noy4/docserve",
+  "version": "0.1.0",
+  "description": "Serves a folder of HTML as a card gallery with live reload.",
+  "type": "module",
+  "bin": {
+    "docserve": "./bin.mjs"
+  },
+  "scripts": {
+    "test": "node --test"
+  },
+  "files": [
+    "bin.mjs",
+    "index.html",
+    "server/"
+  ],
+  "engines": {
+    "node": ">=22.12.0"
+  },
+  "keywords": [
+    "static-server",
+    "live-reload",
+    "gallery",
+    "html"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/noy4/docserve.git"
+  },
+  "homepage": "https://github.com/noy4/docserve#readme",
+  "bugs": "https://github.com/noy4/docserve/issues",
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  }
+}

package/server/files.mjs

@@ -0,0 +1,189 @@
+// File metadata for /api/files: recursive *.html listing (excluding index.html),
+// <title> / <meta name="created_at"> extraction, and git date maps cached per
+// repo root.
+//
+// Created-date priority: meta created_at > oldest git add commit > birthtime.
+import { open, readdir, stat } from "node:fs/promises"
+import { realpathSync } from "node:fs"
+import { basename, isAbsolute, join, relative, sep } from "node:path"
+import { execFile } from "node:child_process"
+import { promisify } from "node:util"
+
+const run = promisify(execFile)
+
+// Walk docsDir recursively and collect .html files; any index.html is excluded
+// from the gallery.
+export async function listHtmlFiles(docsDir, out = []) {
+  let entries
+  try {
+    entries = await readdir(docsDir, { withFileTypes: true })
+  } catch {
+    return out
+  }
+  for (const entry of entries) {
+    const full = join(docsDir, entry.name)
+    if (entry.isDirectory()) {
+      await listHtmlFiles(full, out)
+    } else if (entry.name.endsWith(".html") && entry.name !== "index.html") {
+      out.push(full)
+    }
+  }
+  return out
+}
+
+// /api/files payload, sorted by created desc with title/path tiebreaks.
+export async function apiFiles(docsDir) {
+  const paths = await listHtmlFiles(docsDir)
+  const { created, modified } = await gitDateMaps(docsDir)
+  const files = []
+  for (const full of paths) {
+    let st
+    try {
+      st = await stat(full)
+    } catch {
+      continue // deleted between listing and stat
+    }
+    const { title, date } = await metaOf(full, st.mtimeMs)
+    let key
+    try {
+      key = realpathSync(full)
+    } catch {
+      continue
+    }
+    const rel = normalizedRelative(docsDir, full)
+    files.push({
+      title: title ?? basename(full),
+      url: `/${rel}`,
+      path: full,
+      created: date ?? created.get(key) ?? Math.floor(st.birthtimeMs / 1000),
+      modified: modified.get(key) ?? Math.floor(st.mtimeMs / 1000),
+    })
+  }
+  files.sort((a, b) => b.created - a.created || a.title.localeCompare(b.title, "ja") || a.url.localeCompare(b.url))
+  return files
+}
+
+// <title> + <meta name="created_at"> extracted from the head of a report; cached by
+// path + mtime so repeated /api/files calls only re-read files that changed.
+const metaCache = new Map() // "path:mtimeMs" -> { title, created }
+
+async function metaOf(full, mtimeMs) {
+  const key = `${full}:${mtimeMs}`
+  const cached = metaCache.get(key)
+  if (cached !== undefined) return cached
+  const meta = await extractMeta(full)
+  metaCache.set(key, meta)
+  return meta
+}
+
+async function extractMeta(full) {
+  const findTitle = (text) => text.match(/<title>([^<]*)<\/title>/)?.[1]?.trim() ?? null
+  const findDate = (text) => {
+    for (const tag of text.match(/<meta\b[^>]*>/gi) ?? []) {
+      if (!/\bname\s*=\s*["']created_at["']/i.test(tag)) continue
+      const d = new Date(tag.match(/\bcontent\s*=\s*["']([^"']*)["']/i)?.[1]?.trim() ?? "")
+      if (!isNaN(d.getTime())) return Math.floor(d.getTime() / 1000)
+    }
+    return null
+  }
+  try {
+    const handle = await open(full, "r")
+    try {
+      const read = async (len, pos) => {
+        const { buffer, bytesRead } = await handle.read(Buffer.alloc(len), 0, len, pos)
+        return buffer.toString("utf8", 0, bytesRead)
+      }
+      // Titles and meta tags live in <head>; read only the first 4 KB.
+      const head = await read(4096, 0)
+      let meta = { title: findTitle(head), date: findDate(head) }
+      if (meta.title === null || meta.date === null) {
+        // Fallback for documents with a long preamble (inline favicon etc.)
+        const text = await read(1 << 20, 0)
+        meta = {
+          title: meta.title ?? findTitle(text),
+          date: meta.date ?? findDate(text),
+        }
+      }
+      return meta
+    } finally {
+      await handle.close()
+    }
+  } catch {
+    return { title: null, date: null }
+  }
+}
+
+// Resolve created/modified dates from git history, keyed by absolute path.
+// A single full-repo scan with cwd set to the docs dir, cached per repo root in
+// module scope. git log outputs newest first: overwriting keeps the oldest add
+// (= creation date) and the newest touch (= modified date).
+const gitMapsCache = new Map() // repo root (or docsDir when not a repo) -> { created, modified }
+
+async function gitDateMaps(docsDir) {
+  const cwd = realpath(docsDir)
+  const top = (await git(["rev-parse", "--show-toplevel"], cwd)).trim()
+  const root = top ? realpath(top) : null
+  const cacheKey = root ?? cwd
+  let maps = gitMapsCache.get(cacheKey)
+  if (maps) return maps
+
+  maps = { created: new Map(), modified: new Map() }
+  if (root) {
+    try {
+      const [first, last] = await Promise.all([
+        git(["log", "--diff-filter=A", "--name-only", "--format=c:%at"], cwd),
+        git(["log", "--name-only", "--format=m:%at"], cwd),
+      ])
+      let ts
+      for (const line of first.split("\n")) {
+        if (line.startsWith("c:")) {
+          ts = parseInt(line.slice(2), 10)
+        } else if (line && ts !== undefined) {
+          maps.created.set(join(root, line), ts) // oldest add wins
+        }
+      }
+      ts = undefined
+      for (const line of last.split("\n")) {
+        if (line.startsWith("m:")) {
+          ts = parseInt(line.slice(2), 10)
+        } else if (line && ts !== undefined) {
+          maps.modified.set(join(root, line), ts) // newest touch wins
+        }
+      }
+    } catch {
+      // unreadable history → fall back to fs dates
+    }
+  }
+  gitMapsCache.set(cacheKey, maps)
+  return maps
+}
+
+async function git(args, cwd) {
+  try {
+    const { stdout } = await run("git", args, { cwd, timeout: 10000, maxBuffer: 64 * 1024 * 1024 })
+    return stdout
+  } catch {
+    return ""
+  }
+}
+
+// On macOS /var is a symlink to /private/var; canonicalize to real paths so
+// lookups match git output.
+function realpath(p) {
+  try {
+    return realpathSync(p)
+  } catch {
+    return p
+  }
+}
+
+// --- Path utilities (shared by the HTTP handler and the watcher) ---
+
+export function isWithin(base, path) {
+  const rel = relative(base, path)
+  return rel === "" || (rel !== ".." && !rel.startsWith(`..${sep}`) && !isAbsolute(rel))
+}
+
+export function normalizedRelative(base, path) {
+  return relative(base, path).split(sep).join("/")
+}

package/server/index.mjs

@@ -0,0 +1,168 @@
+// docserve server core: HTTP layer + server lifecycle.
+//
+// ┌────────────────────────────────────────────────────────┐
+// │ runServer()                                            │
+// │ ├─ createServer ──▶ handler()                          │ # HTTP
+// │ │   ├─ /api/files ──▶ apiFiles()                       │
+// │ │   ├─ /, /index.html ──▶ gallery template             │
+// │ │   └─ other paths ──▶ raw files ──▶ injectIntoHtml()  │
+// │ ├─ WebSocketServer("/__reload") ◀─ UpdateListener      │
+// │ └─ listen ──▶ listener.start() + writeState()          │
+// └────────────────────────────────────────────────────────┘
+import { createServer } from "node:http"
+import { readFile } from "node:fs/promises"
+import { extname, resolve } from "node:path"
+import { exec } from "node:child_process"
+import { clearState, writeState } from "./state.mjs"
+import { apiFiles, isWithin, normalizedRelative } from "./files.mjs"
+import { injectIntoHtml, WS_PATH } from "./inject.mjs"
+import { WebSocketServer } from "./websocket.mjs"
+import { UpdateListener } from "./watch.mjs"
+
+const MAX_PORT_TRIES = 20 // on conflict, try the next port up to 20 times
+const INDEX_TEMPLATE = resolve(import.meta.dirname, "..", "index.html")
+
+const MIME = {
+  ".html": "text/html",
+  ".htm": "text/html",
+  ".js": "text/javascript",
+  ".mjs": "text/javascript",
+  ".css": "text/css",
+  ".json": "application/json",
+  ".txt": "text/plain",
+  ".md": "text/markdown",
+  ".xml": "application/xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".svg": "image/svg+xml",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".pdf": "application/pdf",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".mp4": "video/mp4",
+  ".webm": "video/webm",
+}
+
+export async function runServer({ docsDir, port: initialPort, open = false }) {
+  const wss = new WebSocketServer({ path: WS_PATH })
+  const updateListener = new UpdateListener({ wss, docsDir })
+  let port = initialPort // actually bound port (may fall back +1 on conflict)
+
+  const cleanup = () => {
+    updateListener.close()
+    clearState()
+  }
+  process.on("SIGINT", () => { cleanup(); process.exit(0) })
+  process.on("SIGTERM", () => { cleanup(); process.exit(0) })
+
+  const server = createServer(createNodeServerAdapter(createHandler({ docsDir })))
+  wss.attach(server)
+  server.on("error", (err) => {
+    if (err.code === "EADDRINUSE" && port < initialPort + MAX_PORT_TRIES) {
+      port += 1
+      server.listen(port, "127.0.0.1")
+    } else {
+      console.error(err)
+      process.exit(1)
+    }
+  })
+  server.listen(port, "127.0.0.1", async () => {
+    await updateListener.start()
+    const state = { pid: process.pid, port, url: `http://localhost:${port}/`, docsDir }
+    writeState(state)
+    console.log(state.url)
+    if (open && process.platform === "darwin") exec(`open ${state.url}`)
+  })
+  return { server, wss, updateListener }
+}
+
+// --- Node server adapter ---
+
+function createNodeServerAdapter(handler) {
+  return async (req, res) => {
+    try {
+      const response = await handler(toWebRequest(req))
+      res.writeHead(response.status, Object.fromEntries(response.headers))
+      res.end(Buffer.from(await response.arrayBuffer()))
+    } catch (err) {
+      console.error(err)
+      res.writeHead(500, { "content-type": "text/plain" })
+      res.end("Internal Server Error")
+    }
+  }
+}
+
+function toWebRequest(req) {
+  const host = req.headers.host || "localhost"
+  return new Request(`http://${host}${req.url}`, { method: req.method, headers: req.headers })
+}
+
+// --- HTTP handler ---
+
+function createHandler({ docsDir }) {
+  return async function handler(request) {
+    const url = new URL(request.url)
+
+    if (url.pathname === "/api/files") {
+      try {
+        return Response.json(await apiFiles(docsDir))
+      } catch (err) {
+        console.error(err)
+        return Response.json([])
+      }
+    }
+
+    let pathname
+    try {
+      pathname = decodeURIComponent(url.pathname)
+    } catch {
+      return new Response("Bad Request", { status: 400 })
+    }
+
+    if (pathname === "/" || pathname === "/index.html") {
+      return galleryResponse(docsDir)
+    }
+
+    if (pathname.includes("\0")) {
+      return new Response("Bad Request", { status: 400 })
+    }
+
+    const path = resolve(docsDir, pathname.slice(1))
+    if (!isWithin(docsDir, path)) {
+      return new Response("Forbidden", { status: 403 })
+    }
+
+    try {
+      const body = await readFile(path)
+      const type = MIME[extname(path).toLowerCase()] || "application/octet-stream"
+      // Inject the reload client + copy path button into docsDir pages only;
+      // the gallery template ships its own client.
+      if (type === "text/html") {
+        const html = injectIntoHtml(body.toString(), normalizedRelative(docsDir, path), path)
+        return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } })
+      }
+      return new Response(body, { headers: { "content-type": type } })
+    } catch {
+      return new Response("Not Found", { status: 404 })
+    }
+  }
+}
+
+// The gallery is an embedded template served at / and /index.html; docsDir's own
+// index.html is shadowed by it. __DOCSERVE_DIR__ is substituted for display.
+async function galleryResponse(docsDir) {
+  try {
+    let html = await readFile(INDEX_TEMPLATE, "utf8")
+    html = html.replaceAll("__DOCSERVE_DIR__", escapeHtml(docsDir))
+    return new Response(html, { headers: { "content-type": "text/html; charset=utf-8" } })
+  } catch {
+    return new Response("Gallery template missing", { status: 500 })
+  }
+}
+
+function escapeHtml(s) {
+  return s.replaceAll("&", "&amp;").replaceAll("<", "&lt;").replaceAll(">", "&gt;")
+}

package/server/inject.mjs

@@ -0,0 +1,100 @@
+// Injection: every text/html response served from docsDir gets one client script
+// before the last </body> (appended at the end if the tag is missing). The script
+// exits immediately inside iframes, so previews get neither part; the gallery
+// template ships its own client.
+
+export const WS_PATH = "/__reload"
+
+export function injectIntoHtml(html, pageId, absPath) {
+  const idx = html.toLowerCase().lastIndexOf("</body>")
+  if (idx === -1) return html + clientJs(pageId, absPath)
+  return html.slice(0, idx) + clientJs(pageId, absPath) + html.slice(idx)
+}
+
+function clientJs(pageId, absPath) {
+  return `<script>
+(() => {
+  // iframes: no reload loop from dropped sockets, no copy button
+  if (window.self !== window.top) return
+  const pageId = ${JSON.stringify(pageId).replaceAll("<", "\\u003c")}
+  const proto = location.protocol === "https:" ? "wss:" : "ws:"
+  const ws = new WebSocket(proto + "//" + location.host + "${WS_PATH}")
+  ws.addEventListener("message", (e) => {
+    let change
+    try { change = JSON.parse(e.data) } catch { return }
+    if (change?.type === "change" && Array.isArray(change.pages) && change.pages.includes(pageId)) {
+      location.reload()
+    }
+  })
+  ws.addEventListener("close", () => setTimeout(() => location.reload(), 1000))
+
+  const absPath = ${JSON.stringify(absPath).replaceAll("<", "\\u003c")}
+  const style = document.createElement("style")
+  style.textContent = \`#docserve-copy {
+  position: fixed;
+  top: 12px;
+  right: 12px;
+  z-index: 2147483647;
+  display: inline-flex;
+  align-items: center;
+  gap: 6px;
+  height: 28px;
+  padding: 0 10px 0 9px;
+  border: 1px solid rgba(127, 127, 138, 0.35);
+  border-radius: 8px;
+  background: rgba(127, 127, 138, 0.14);
+  color: inherit;
+  cursor: pointer;
+  opacity: 0.55;
+  transition: opacity 0.15s ease, color 0.15s ease, border-color 0.15s ease;
+}
+#docserve-copy svg {
+  width: 14px;
+  height: 14px;
+  pointer-events: none;
+}
+#docserve-copy .label {
+  font: 500 11.5px/1 -apple-system, BlinkMacSystemFont, "Segoe UI", "Hiragino Sans", sans-serif;
+  letter-spacing: 0.01em;
+  white-space: nowrap;
+}
+#docserve-copy:hover {
+  opacity: 1;
+  border-color: #6c8cff;
+  color: #6c8cff;
+}
+#docserve-copy.copied {
+  opacity: 1;
+  color: #4ade80;
+  border-color: #4ade80;
+}
+@media (prefers-color-scheme: light) {
+  #docserve-copy:hover { border-color: #2563eb; color: #2563eb; }
+  #docserve-copy.copied { color: #16a34a; border-color: #16a34a; }
+}
+#docserve-copy .ic-check { display: none; }
+#docserve-copy.copied .ic-copy { display: none; }
+#docserve-copy.copied .ic-check { display: block; }\`
+  const COPY = '<svg class="ic-copy" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"><rect x="9" y="9" width="13" height="13" rx="2" ry="2"/><path d="M5 15H4a2 2 0 0 1-2-2V4a2 2 0 0 1 2-2h9a2 2 0 0 1 2 2v1"/></svg>'
+  const CHECK = '<svg class="ic-check" width="14" height="14" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2.5" stroke-linecap="round" stroke-linejoin="round"><polyline points="20 6 9 17 4 12"/></svg>'
+  const btn = document.createElement("button")
+  btn.id = "docserve-copy"
+  btn.type = "button"
+  btn.title = absPath
+  btn.innerHTML = COPY + CHECK + '<span class="label">Copy file path</span>'
+  btn.addEventListener("click", async () => {
+    try {
+      await navigator.clipboard.writeText(absPath)
+      btn.classList.add("copied")
+      btn.querySelector(".label").textContent = "Copied"
+      setTimeout(() => {
+        btn.classList.remove("copied")
+        btn.querySelector(".label").textContent = "Copy file path"
+      }, 1200)
+    } catch {}
+  })
+  document.head.appendChild(style)
+  document.body.appendChild(btn)
+})()
+</script>`
+}

package/server/state.mjs

@@ -0,0 +1,61 @@
+// state.json read/write + pid liveness.
+//
+// The server writes ~/.cache/docserve/state.json once the port is bound and
+// removes it on clean shutdown. Readers verify the PID is alive and treat
+// dead-PID state as stale (removed in place).
+import fs from "node:fs"
+import os from "node:os"
+import path from "node:path"
+
+// DOCSERVE_STATE overrides the state file path (test isolation).
+export function statePath() {
+  return process.env.DOCSERVE_STATE || path.join(os.homedir(), ".cache", "docserve", "state.json")
+}
+
+export function readState() {
+  try {
+    const state = JSON.parse(fs.readFileSync(statePath(), "utf8"))
+    if (
+      typeof state?.pid === "number" &&
+      typeof state?.port === "number" &&
+      typeof state?.url === "string" &&
+      typeof state?.docsDir === "string"
+    ) {
+      return state
+    }
+    return null
+  } catch {
+    return null
+  }
+}
+
+export function writeState(state) {
+  fs.mkdirSync(path.dirname(statePath()), { recursive: true })
+  fs.writeFileSync(statePath(), JSON.stringify(state, null, 2) + "\n")
+}
+
+export function clearState() {
+  try {
+    fs.rmSync(statePath(), { force: true })
+  } catch {}
+}
+
+export function isProcessAlive(pid) {
+  try {
+    process.kill(pid, 0)
+    return true
+  } catch {
+    return false
+  }
+}
+
+// Read the state and drop stale entries (dead pid) in place.
+export function readLiveState() {
+  const state = readState()
+  if (!state) return null
+  if (!isProcessAlive(state.pid)) {
+    clearState()
+    return null
+  }
+  return state
+}

package/server/watch.mjs

@@ -0,0 +1,86 @@
+// UpdateListener: watch docsDir recursively for *.html changes and broadcast
+// debounced batches over the reload socket.
+//
+// The gallery list is every *.html except any index.html; files outside that
+// set never flip contentSetChanged.
+import { existsSync, watch } from "node:fs"
+import { basename, resolve } from "node:path"
+import { isWithin, listHtmlFiles, normalizedRelative } from "./files.mjs"
+
+const DEBOUNCE_MS = 50 // like livePreview.previewDebounceDelay
+
+export class UpdateListener {
+  constructor(options = {}) {
+    this.wss = options.wss
+    this.docsDir = options.docsDir
+    this.debounceMs = options.debounceMs ?? DEBOUNCE_MS
+    this.knownFiles = new Set()
+    this.broadcastQueue = Promise.resolve()
+    this.watchers = []
+
+    this.queueBroadcast = debounceBatch((touched) => {
+      this.broadcastQueue = this.broadcastQueue
+        .then(() => this.broadcastChanges(touched))
+        .catch((error) => console.error(error))
+    }, this.debounceMs)
+  }
+
+  async start() {
+    try {
+      this.knownFiles = new Set(
+        (await listHtmlFiles(this.docsDir)).map((p) => normalizedRelative(this.docsDir, p)),
+      )
+    } catch {
+      this.knownFiles = new Set()
+    }
+
+    this.watchers.push(
+      watch(this.docsDir, { recursive: true }, (event, filename) => {
+        if (!filename?.endsWith(".html")) return
+        const full = resolve(this.docsDir, filename)
+        if (!isWithin(this.docsDir, full)) return
+        this.queueBroadcast(normalizedRelative(this.docsDir, full))
+      }).on("error", () => {}),
+    )
+  }
+
+  async broadcastChanges(touched) {
+    let contentSetChanged = false
+
+    for (const rel of touched) {
+      if (basename(rel) === "index.html") continue // never a gallery card
+      const full = resolve(this.docsDir, rel)
+      const exists = existsSync(full)
+      const wasKnown = this.knownFiles.has(rel)
+
+      if (exists && !wasKnown) {
+        this.knownFiles.add(rel)
+        contentSetChanged = true
+      } else if (!exists && wasKnown) {
+        this.knownFiles.delete(rel)
+        contentSetChanged = true
+      }
+    }
+
+    this.wss.broadcast({ type: "change", pages: touched, contentSetChanged })
+  }
+
+  close() {
+    this.watchers.forEach((w) => w.close())
+  }
+}
+
+// Accumulate items during the debounce window and deliver them as one batch.
+function debounceBatch(fn, ms) {
+  let timer = null
+  const pending = new Set()
+  return (item) => {
+    pending.add(item)
+    clearTimeout(timer)
+    timer = setTimeout(() => {
+      const items = [...pending]
+      pending.clear()
+      fn(items)
+    }, ms)
+  }
+}

package/server/websocket.mjs

@@ -0,0 +1,81 @@
+// Minimal WebSocket server (RFC 6455 subset: handshake + text frames + ping/pong,
+// zero deps). Broadcast payloads are JSON-encoded text frames.
+import { createHash } from "node:crypto"
+
+export class WebSocketServer {
+  constructor(options = {}) {
+    this.path = options.path
+    this.clients = new Set()
+    if (options.server) {
+      this.attach(options.server)
+    }
+  }
+
+  attach(server) {
+    server.on("upgrade", (req, socket) => this.handleUpgrade(req, socket))
+  }
+
+  handleUpgrade(req, socket) {
+    const url = new URL(req.url, "http://localhost")
+    if (this.path && url.pathname !== this.path) {
+      socket.destroy()
+      return
+    }
+    const key = req.headers["sec-websocket-key"]
+    if (!key) {
+      socket.destroy()
+      return
+    }
+    socket.write(
+      "HTTP/1.1 101 Switching Protocols\r\n" +
+      "Upgrade: websocket\r\n" +
+      "Connection: Upgrade\r\n" +
+      `Sec-WebSocket-Accept: ${acceptKey(key)}\r\n\r\n`,
+    )
+    socket.setNoDelay(true)
+    this.clients.add(socket)
+    socket.on("close", () => this.clients.delete(socket))
+    socket.on("error", () => this.clients.delete(socket))
+    // Answer pings to keep the connection alive
+    socket.on("data", (buf) => {
+      if (buf.length > 0 && (buf[0] & 0x0f) === 0x9) {
+        socket.write(Buffer.from([0x8a, 0x00])) // pong
+      }
+    })
+  }
+
+  broadcast(payload) {
+    const frame = encodeFrame(typeof payload === "string" ? payload : JSON.stringify(payload))
+    for (const socket of this.clients) {
+      try {
+        socket.write(frame)
+      } catch {
+        this.clients.delete(socket)
+      }
+    }
+  }
+}
+
+function acceptKey(key) {
+  return createHash("sha1").update(key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11").digest("base64")
+}
+
+function encodeFrame(text) {
+  const payload = Buffer.from(text)
+  const len = payload.length
+  let header
+  if (len < 126) {
+    header = Buffer.from([0x81, len])
+  } else if (len < 65536) {
+    header = Buffer.alloc(4)
+    header[0] = 0x81
+    header[1] = 126
+    header.writeUInt16BE(len, 2)
+  } else {
+    header = Buffer.alloc(10)
+    header[0] = 0x81
+    header[1] = 127
+    header.writeBigUInt64BE(BigInt(len), 2)
+  }
+  return Buffer.concat([header, payload])
+}