lecodes-design 0.1.0

package/dist/server.js

@@ -0,0 +1,863 @@
+// src/server/index.ts
+import { createServer } from "node:http";
+import { existsSync as existsSync4, readFileSync as readFileSync4, statSync, watch } from "node:fs";
+import { extname, join as join3, normalize, resolve as resolve3, sep as sep3, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/server/designState.ts
+import { existsSync, readFileSync, readdirSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+var DEFAULT_SCREEN_SIZE = [390, 844];
+var GRID_GAP = 160;
+var GRID_ROWS = 2;
+var readMeta = (designDir, warnings) => {
+  const path = join(designDir, "meta.json");
+  if (!existsSync(path))
+    return {};
+  try {
+    return JSON.parse(readFileSync(path, "utf8"));
+  } catch (e) {
+    warnings.push(`meta.json is not valid JSON (${e instanceof Error ? e.message : String(e)}) — positions/edges ignored.`);
+    return {};
+  }
+};
+var listScreenFiles = (designDir) => {
+  const dir = join(designDir, "screens");
+  if (!existsSync(dir))
+    return [];
+  const out = [];
+  for (const entry of readdirSync(dir, { withFileTypes: true })) {
+    if (!entry.isFile() || !entry.name.endsWith(".ts") || entry.name.startsWith("."))
+      continue;
+    out.push({ id: entry.name.slice(0, -3), file: `screens/${entry.name}` });
+  }
+  out.sort((a, b) => a.id.localeCompare(b.id));
+  return out;
+};
+var readMetaFile = (designDir) => {
+  const path = join(designDir, "meta.json");
+  if (!existsSync(path))
+    return {};
+  return JSON.parse(readFileSync(path, "utf8"));
+};
+var writeMetaFile = (designDir, meta) => {
+  writeFileSync(join(designDir, "meta.json"), JSON.stringify(meta, null, 2) + `
+`);
+};
+var writeScreenMeta = (designDir, id, patch) => {
+  const meta = readMetaFile(designDir);
+  meta.screens ??= {};
+  const entry = { ...meta.screens[id] };
+  if (patch.pos)
+    entry.pos = [Math.round(patch.pos[0]), Math.round(patch.pos[1])];
+  if (patch.desc !== undefined) {
+    if (patch.desc.trim() === "")
+      delete entry.desc;
+    else
+      entry.desc = patch.desc.trim();
+  }
+  meta.screens[id] = entry;
+  writeMetaFile(designDir, meta);
+};
+var addEdge = (designDir, edge) => {
+  const meta = readMetaFile(designDir);
+  meta.edges ??= [];
+  const clean = { from: edge.from, to: edge.to };
+  if (edge.label?.trim())
+    clean.label = edge.label.trim();
+  if (edge.activator?.trim())
+    clean.activator = edge.activator.trim();
+  meta.edges.push(clean);
+  writeMetaFile(designDir, meta);
+  return meta.edges.length - 1;
+};
+var updateEdge = (designDir, index, patch) => {
+  const meta = readMetaFile(designDir);
+  const edge = meta.edges?.[index];
+  if (!edge)
+    throw new Error(`No edge at index ${index}.`);
+  for (const key of ["label", "activator"]) {
+    const value = patch[key];
+    if (value === undefined)
+      continue;
+    if (value.trim() === "")
+      delete edge[key];
+    else
+      edge[key] = value.trim();
+  }
+  writeMetaFile(designDir, meta);
+};
+var removeEdge = (designDir, index) => {
+  const meta = readMetaFile(designDir);
+  if (!meta.edges?.[index])
+    throw new Error(`No edge at index ${index}.`);
+  meta.edges.splice(index, 1);
+  writeMetaFile(designDir, meta);
+};
+var readDesignState = (designDir) => {
+  const warnings = [];
+  const meta = readMeta(designDir, warnings);
+  const files = listScreenFiles(designDir);
+  const placed = files.filter((f) => meta.screens?.[f.id]?.pos);
+  let autoX = 0;
+  for (const f of placed) {
+    const m = meta.screens[f.id];
+    autoX = Math.max(autoX, m.pos[0] + (m.size?.[0] ?? DEFAULT_SCREEN_SIZE[0]) + GRID_GAP);
+  }
+  let autoIndex = 0;
+  const screens = files.map((f) => {
+    const m = meta.screens?.[f.id] ?? {};
+    const size = m.size ?? DEFAULT_SCREEN_SIZE;
+    let pos = m.pos;
+    if (!pos) {
+      const col = Math.floor(autoIndex / GRID_ROWS);
+      const row = autoIndex % GRID_ROWS;
+      pos = [autoX + col * (DEFAULT_SCREEN_SIZE[0] + GRID_GAP), row * (DEFAULT_SCREEN_SIZE[1] + GRID_GAP)];
+      autoIndex++;
+    }
+    return { id: f.id, file: f.file, desc: m.desc, pos, size };
+  });
+  const ids = new Set(screens.map((s) => s.id));
+  for (const id of Object.keys(meta.screens ?? {})) {
+    if (!ids.has(id))
+      warnings.push(`meta.json describes screen "${id}" but screens/${id}.ts does not exist.`);
+  }
+  const edges = [];
+  for (const [index, e] of (meta.edges ?? []).entries()) {
+    if (!ids.has(e.from) || !ids.has(e.to)) {
+      warnings.push(`Edge ${e.from} → ${e.to} references a missing screen — skipped.`);
+      continue;
+    }
+    edges.push({ ...e, index });
+  }
+  return { screens, edges, warnings };
+};
+
+// src/server/textEdit.ts
+import { readFileSync as readFileSync2, writeFileSync as writeFileSync2, existsSync as existsSync2 } from "node:fs";
+import { resolve, sep, relative } from "node:path";
+var CALL_SCAN_LIMIT = 8000;
+var FALLBACK_WINDOW = 400;
+var decodeEscape = (src, i) => {
+  const c = src[i];
+  switch (c) {
+    case "n":
+      return [`
+`, i + 1];
+    case "t":
+      return ["\t", i + 1];
+    case "r":
+      return ["\r", i + 1];
+    case "b":
+      return ["\b", i + 1];
+    case "f":
+      return ["\f", i + 1];
+    case "v":
+      return ["\v", i + 1];
+    case "0":
+      return ["\x00", i + 1];
+    case "x": {
+      const hex = src.slice(i + 1, i + 3);
+      return /^[0-9a-fA-F]{2}$/.test(hex) ? [String.fromCharCode(parseInt(hex, 16)), i + 3] : [c ?? "", i + 1];
+    }
+    case "u": {
+      if (src[i + 1] === "{") {
+        const close = src.indexOf("}", i + 2);
+        const hex2 = close > 0 ? src.slice(i + 2, close) : "";
+        if (/^[0-9a-fA-F]{1,6}$/.test(hex2))
+          return [String.fromCodePoint(parseInt(hex2, 16)), close + 1];
+        return [c ?? "", i + 1];
+      }
+      const hex = src.slice(i + 1, i + 5);
+      return /^[0-9a-fA-F]{4}$/.test(hex) ? [String.fromCharCode(parseInt(hex, 16)), i + 5] : [c ?? "", i + 1];
+    }
+    case `
+`:
+      return ["", i + 1];
+    default:
+      return [c ?? "", i + 1];
+  }
+};
+var parseStringLiteral = (src, start) => {
+  const quote = src[start];
+  if (quote !== '"' && quote !== "'" && quote !== "`")
+    return null;
+  let value = "";
+  let i = start + 1;
+  while (i < src.length) {
+    const c = src[i];
+    if (c === "\\") {
+      const [text, next] = decodeEscape(src, i + 1);
+      value += text;
+      i = next;
+      continue;
+    }
+    if (c === quote)
+      return { start, end: i + 1, value, quote };
+    if (quote !== "`" && (c === `
+` || c === "\r"))
+      return null;
+    if (quote === "`" && c === "$" && src[i + 1] === "{")
+      return null;
+    value += c;
+    i++;
+  }
+  return null;
+};
+var encodeStringLiteral = (text, quote) => {
+  let out = quote;
+  for (const c of text) {
+    if (c === "\\")
+      out += "\\\\";
+    else if (c === quote)
+      out += "\\" + c;
+    else if (quote === "`" && c === "$")
+      out += "\\$";
+    else if (c === `
+`)
+      out += quote === "`" ? `
+` : "\\n";
+    else if (c === "\r")
+      out += "\\r";
+    else if (c === "\t")
+      out += quote === "`" ? "\t" : "\\t";
+    else
+      out += c;
+  }
+  return out + quote;
+};
+var offsetOf = (src, line, column) => {
+  let offset = 0;
+  for (let l = 1;l < line; l++) {
+    const nl = src.indexOf(`
+`, offset);
+    if (nl === -1)
+      return -1;
+    offset = nl + 1;
+  }
+  const end = src.indexOf(`
+`, offset);
+  const lineLength = (end === -1 ? src.length : end) - offset;
+  return column <= lineLength ? offset + column : -1;
+};
+var directCallStringArgs = (src, from) => {
+  let open = -1;
+  for (let i2 = from;i2 < Math.min(src.length, from + 120); i2++) {
+    const c = src[i2];
+    if (c === "(") {
+      open = i2;
+      break;
+    }
+    if (c === ")" || c === ";" || c === "}")
+      break;
+  }
+  if (open === -1)
+    return [];
+  const out = [];
+  let paren = 1, brace = 0, bracket = 0;
+  let i = open + 1;
+  const limit = Math.min(src.length, open + CALL_SCAN_LIMIT);
+  while (i < limit && paren > 0) {
+    const c = src[i];
+    if (c === '"' || c === "'" || c === "`") {
+      const lit = parseStringLiteral(src, i);
+      if (!lit)
+        return [];
+      if (paren === 1 && brace === 0 && bracket === 0)
+        out.push(lit);
+      i = lit.end;
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "/") {
+      const nl = src.indexOf(`
+`, i);
+      i = nl === -1 ? limit : nl + 1;
+      continue;
+    }
+    if (c === "/" && src[i + 1] === "*") {
+      const close = src.indexOf("*/", i + 2);
+      i = close === -1 ? limit : close + 2;
+      continue;
+    }
+    if (c === "(")
+      paren++;
+    else if (c === ")")
+      paren--;
+    else if (c === "{")
+      brace++;
+    else if (c === "}")
+      brace = Math.max(0, brace - 1);
+    else if (c === "[")
+      bracket++;
+    else if (c === "]")
+      bracket = Math.max(0, bracket - 1);
+    i++;
+  }
+  return paren === 0 ? out : [];
+};
+var literalsInWindow = (src, from, window) => {
+  const out = [];
+  const limit = Math.min(src.length, from + window);
+  let i = from;
+  while (i < limit) {
+    const c = src[i];
+    if (c === '"' || c === "'" || c === "`") {
+      const lit = parseStringLiteral(src, i);
+      if (lit) {
+        out.push(lit);
+        i = lit.end;
+        continue;
+      }
+    }
+    i++;
+  }
+  return out;
+};
+var editTextAtSite = (options) => {
+  const { root, designDir, frames, oldText, newText } = options;
+  if (!oldText)
+    return { ok: false, reason: "Empty text can't be located safely — edit the code directly." };
+  if (oldText === newText)
+    return { ok: true, file: "" };
+  let sawDynamic = false;
+  for (const frame of frames) {
+    const rel = frame.source.replace(/^[/\\]+/, "");
+    const abs = resolve(root, rel);
+    if (!abs.startsWith(resolve(designDir) + sep))
+      continue;
+    if (!existsSync2(abs))
+      continue;
+    const src = readFileSync2(abs, "utf8");
+    const offset = offsetOf(src, frame.line, frame.column);
+    if (offset < 0)
+      continue;
+    let matches = directCallStringArgs(src, offset).filter((l) => l.value === oldText);
+    if (matches.length === 0) {
+      const near = literalsInWindow(src, offset, FALLBACK_WINDOW).filter((l) => l.value === oldText);
+      if (near.length === 1)
+        matches = near;
+      else if (near.length === 0 && directCallStringArgs(src, offset).length > 0)
+        sawDynamic = true;
+    } else if (matches.length > 1) {
+      return { ok: false, reason: "Ambiguous — the same text appears more than once at this call site." };
+    }
+    const hit = matches[0];
+    if (!hit)
+      continue;
+    const next = src.slice(0, hit.start) + encodeStringLiteral(newText, hit.quote) + src.slice(hit.end);
+    writeFileSync2(abs, next);
+    return { ok: true, file: relative(root, abs).replace(/\\/g, "/") };
+  }
+  return {
+    ok: false,
+    reason: sawDynamic ? "This text is computed at runtime — edit it in the code." : "Couldn't locate the text in the source — edit it in the code."
+  };
+};
+
+// src/server/imageEdit.ts
+import { existsSync as existsSync3, mkdirSync, readdirSync as readdirSync2, readFileSync as readFileSync3, writeFileSync as writeFileSync3 } from "node:fs";
+import { join as join2, posix, relative as relative2, resolve as resolve2, sep as sep2 } from "node:path";
+var WINDOW = 800;
+var keyOf = (root, abs) => "/" + relative2(root, abs).replace(/\\/g, "/");
+var offsetOf2 = (src, line, column) => {
+  let offset = 0;
+  for (let l = 1;l < line; l++) {
+    const nl = src.indexOf(`
+`, offset);
+    if (nl === -1)
+      return -1;
+    offset = nl + 1;
+  }
+  const end = src.indexOf(`
+`, offset);
+  const lineLength = (end === -1 ? src.length : end) - offset;
+  return offset + Math.min(column, lineLength);
+};
+var findAssetCalls = (src, from, window) => {
+  const out = [];
+  const limit = Math.min(src.length, from + window);
+  let i = from;
+  while (i < limit) {
+    const at = src.indexOf("asset", i);
+    if (at === -1 || at >= limit)
+      break;
+    i = at + 5;
+    if (at > 0 && /[\w$.]/.test(src[at - 1]))
+      continue;
+    let j = at + 5;
+    while (j < src.length && /\s/.test(src[j]))
+      j++;
+    if (src[j] !== "(")
+      continue;
+    j++;
+    while (j < src.length && /\s/.test(src[j]))
+      j++;
+    const literal = parseStringLiteral(src, j);
+    if (!literal)
+      continue;
+    let k = literal.end;
+    while (k < src.length && /\s/.test(src[k]))
+      k++;
+    if (src[k] !== ")")
+      continue;
+    out.push({ literal });
+  }
+  return out;
+};
+var findImportRefs = (src) => {
+  const out = [];
+  const importRe = /\bimport\b/g;
+  let m;
+  while (m = importRe.exec(src)) {
+    if (m.index > 0 && /[\w$.]/.test(src[m.index - 1]))
+      continue;
+    let i = m.index + 6;
+    while (i < src.length && /\s/.test(src[i]))
+      i++;
+    if (src[i] === "(" || src[i] === ".")
+      continue;
+    if (src[i] !== '"' && src[i] !== "'") {
+      const fromRe = /\bfrom\s*(?=["'])/g;
+      fromRe.lastIndex = i;
+      const f = fromRe.exec(src);
+      if (!f || f.index - m.index > 600)
+        continue;
+      i = f.index + f[0].length;
+    }
+    const literal = parseStringLiteral(src, i);
+    if (literal)
+      out.push(literal);
+  }
+  return out;
+};
+var assetRefsIn = (src, fileKey, oldKey) => {
+  const out = [];
+  for (const call of findAssetCalls(src, 0, src.length)) {
+    if (resolveAssetArg(fileKey, call.literal.value) === oldKey)
+      out.push({ literal: call.literal, kind: "asset" });
+  }
+  for (const literal of findImportRefs(src)) {
+    if (resolveAssetArg(fileKey, literal.value) === oldKey)
+      out.push({ literal, kind: "import" });
+  }
+  return out;
+};
+var findLiteralsEqual = (src, from, to, value) => {
+  const out = [];
+  const limit = Math.min(src.length, to);
+  let i = from;
+  while (i < limit) {
+    const c = src[i];
+    if (c === '"' || c === "'" || c === "`") {
+      const literal = parseStringLiteral(src, i);
+      if (literal) {
+        if (literal.value === value)
+          out.push(literal);
+        i = literal.end;
+        continue;
+      }
+    }
+    i++;
+  }
+  return out;
+};
+var tsFilesUnder = (dir) => {
+  const out = [];
+  for (const entry of readdirSync2(dir, { withFileTypes: true })) {
+    if (entry.name.startsWith(".") || entry.name === "node_modules")
+      continue;
+    const abs = join2(dir, entry.name);
+    if (entry.isDirectory())
+      out.push(...tsFilesUnder(abs));
+    else if (/\.tsx?$/.test(entry.name))
+      out.push(abs);
+  }
+  return out;
+};
+var resolveAssetArg = (fileKey, arg) => {
+  if (arg.startsWith("/"))
+    return posix.normalize(arg);
+  if (arg.startsWith("."))
+    return posix.normalize(posix.join(posix.dirname(fileKey), arg));
+  return null;
+};
+var relativeAssetArg = (fileKey, assetKey) => {
+  const rel = posix.relative(posix.dirname(fileKey), assetKey);
+  return rel.startsWith(".") ? rel : `./${rel}`;
+};
+var sanitizeName = (name) => {
+  const base = name.replace(/^.*[/\\]/, "").replace(/[^\w.\- ]+/g, "-").replace(/\s+/g, "-");
+  return base && base !== "." && base !== ".." ? base : "image";
+};
+var saveAsset = (designDir, name, data) => {
+  const dir = join2(designDir, "assets");
+  mkdirSync(dir, { recursive: true });
+  const safe = sanitizeName(name);
+  const dot = safe.lastIndexOf(".");
+  const stem = dot > 0 ? safe.slice(0, dot) : safe;
+  const ext = dot > 0 ? safe.slice(dot) : "";
+  for (let n = 0;n < 1000; n++) {
+    const candidate = join2(dir, n === 0 ? safe : `${stem}-${n}${ext}`);
+    if (!existsSync3(candidate)) {
+      writeFileSync3(candidate, data);
+      return candidate;
+    }
+    if (data.equals(readFileSync3(candidate)))
+      return candidate;
+  }
+  throw new Error("Couldn't find a free asset filename.");
+};
+var locate = (root, designDir, frames, oldSrc) => {
+  const oldKey = oldSrc.startsWith("/project/") ? posix.normalize(decodeURI(oldSrc.slice("/project".length))) : null;
+  const frameFiles = new Set;
+  for (const frame of frames) {
+    const rel = frame.source.replace(/^[/\\]+/, "");
+    const abs = resolve2(root, rel);
+    if (!abs.startsWith(resolve2(designDir) + sep2))
+      continue;
+    if (!existsSync3(abs))
+      continue;
+    if (frameFiles.has(abs))
+      continue;
+    frameFiles.add(abs);
+    const src = readFileSync3(abs, "utf8");
+    const offset = offsetOf2(src, frame.line, frame.column);
+    if (offset < 0)
+      continue;
+    const fileKey = keyOf(root, abs);
+    if (oldKey) {
+      const near = findAssetCalls(src, offset, WINDOW).filter((c) => resolveAssetArg(fileKey, c.literal.value) === oldKey);
+      if (near.length === 1)
+        return { abs, fileKey, src, literal: near[0].literal, kind: "asset" };
+      if (near.length > 1)
+        return { reason: "Ambiguous — several asset() calls here point at the same file." };
+      const inFile = assetRefsIn(src, fileKey, oldKey);
+      if (inFile.length === 1)
+        return { abs, fileKey, src, literal: inFile[0].literal, kind: inFile[0].kind };
+      if (inFile.length > 1)
+        return { reason: "Ambiguous — this file references the same image more than once." };
+    } else {
+      const near = findLiteralsEqual(src, offset, offset + WINDOW, oldSrc);
+      if (near.length === 1)
+        return { abs, fileKey, src, literal: near[0], kind: "url" };
+      if (near.length > 1)
+        return { reason: "Ambiguous — the same source URL appears more than once here." };
+      const inFile = findLiteralsEqual(src, 0, src.length, oldSrc);
+      if (inFile.length === 1)
+        return { abs, fileKey, src, literal: inFile[0], kind: "url" };
+      if (inFile.length > 1)
+        return { reason: "Ambiguous — the same source URL appears more than once in this file." };
+    }
+  }
+  if (oldKey) {
+    const hits = [];
+    for (const abs of tsFilesUnder(designDir)) {
+      if (frameFiles.has(abs))
+        continue;
+      const src = readFileSync3(abs, "utf8");
+      const fileKey = keyOf(root, abs);
+      for (const ref of assetRefsIn(src, fileKey, oldKey)) {
+        hits.push({ abs, fileKey, src, literal: ref.literal, kind: ref.kind });
+        if (hits.length > 1)
+          return { reason: "Ambiguous — several places in the design folder reference this image." };
+      }
+    }
+    if (hits.length === 1)
+      return hits[0];
+  }
+  return { reason: "This image's source is computed at runtime — edit it in the code." };
+};
+var replaceImageAtSite = (options) => {
+  const { root, designDir, frames, oldSrc, name, data } = options;
+  if (!oldSrc)
+    return { ok: false, reason: "This image has no file source — edit the code directly." };
+  const target = locate(root, designDir, frames, oldSrc);
+  if (!("abs" in target))
+    return { ok: false, reason: target.reason };
+  const savedAbs = saveAsset(designDir, name, data);
+  const assetKey = keyOf(root, savedAbs);
+  const arg = relativeAssetArg(target.fileKey, assetKey);
+  const replacement = target.kind === "url" ? `asset(${encodeStringLiteral(arg, '"')})` : encodeStringLiteral(arg, target.literal.quote);
+  const next = target.src.slice(0, target.literal.start) + replacement + target.src.slice(target.literal.end);
+  writeFileSync3(target.abs, next);
+  return {
+    ok: true,
+    file: relative2(root, target.abs).replace(/\\/g, "/"),
+    path: assetKey,
+    src: "/project" + encodeURI(assetKey)
+  };
+};
+
+// src/server/index.ts
+var MIME = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".avif": "image/avif",
+  ".ico": "image/x-icon",
+  ".wasm": "application/wasm",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+  ".otf": "font/otf",
+  ".mp3": "audio/mpeg",
+  ".mp4": "video/mp4",
+  ".txt": "text/plain; charset=utf-8"
+};
+var sendJson = (res, status, value) => {
+  res.writeHead(status, { "content-type": "application/json; charset=utf-8", "cache-control": "no-store" });
+  res.end(JSON.stringify(value));
+};
+var sendFile = (res, baseDir, relPath) => {
+  const abs = resolve3(baseDir, "." + sep3 + normalize(relPath).replace(/^([/\\])+/, ""));
+  if (!abs.startsWith(resolve3(baseDir) + sep3) && abs !== resolve3(baseDir))
+    return false;
+  if (!existsSync4(abs) || !statSync(abs).isFile())
+    return false;
+  res.writeHead(200, {
+    "content-type": MIME[extname(abs).toLowerCase()] ?? "application/octet-stream",
+    "cache-control": "no-store"
+  });
+  res.end(readFileSync4(abs));
+  return true;
+};
+var startDesignServer = async (options) => {
+  const { root, designDir, compileScreen } = options;
+  const port = options.port ?? 4477;
+  const log = options.log ?? (() => {});
+  const appDir = options.appDir ?? join3(dirname(fileURLToPath(import.meta.url)), "app");
+  const cache = new Map;
+  const getCompiled = (id) => {
+    let entry = cache.get(id);
+    if (!entry) {
+      entry = compileScreen(id);
+      entry.catch(() => cache.delete(id));
+      cache.set(id, entry);
+    }
+    return entry;
+  };
+  const clients = new Set;
+  const broadcast = (event) => {
+    const payload = `data: ${JSON.stringify(event)}
+
+`;
+    for (const res of clients)
+      res.write(payload);
+  };
+  let pendingScreens = new Set;
+  let pendingAll = false;
+  let pendingMeta = false;
+  let timer = null;
+  const flush = () => {
+    timer = null;
+    const event = { screens: pendingAll ? null : [...pendingScreens], meta: pendingMeta };
+    if (pendingAll)
+      cache.clear();
+    else
+      for (const id of pendingScreens)
+        cache.delete(id);
+    pendingScreens = new Set;
+    pendingAll = false;
+    pendingMeta = false;
+    log(`change → reload ${event.screens === null ? "all screens" : event.screens.join(", ") || "(meta only)"}`);
+    broadcast(event);
+  };
+  const onFsEvent = (file) => {
+    const key = (file ?? "").replace(/\\/g, "/");
+    const match = /^screens\/([^/]+)\.ts$/.exec(key);
+    if (match)
+      pendingScreens.add(match[1]);
+    else if (key === "meta.json")
+      pendingMeta = true;
+    else
+      pendingAll = true;
+    if (timer)
+      clearTimeout(timer);
+    timer = setTimeout(flush, 120);
+  };
+  let watcher = null;
+  try {
+    watcher = watch(designDir, { recursive: true }, (_type, file) => onFsEvent(file));
+  } catch {
+    log("fs.watch(recursive) unavailable — hot reload disabled (refresh the browser manually).");
+  }
+  const server = createServer(async (req, res) => {
+    const url = new URL(req.url ?? "/", "http://localhost");
+    const path = decodeURIComponent(url.pathname);
+    try {
+      if (path === "/api/state") {
+        const state = readDesignState(designDir);
+        return sendJson(res, 200, { name: options.name ?? "LeCodes Design", ...state });
+      }
+      const readBody = () => new Promise((resolveBody, rejectBody) => {
+        let data = "";
+        req.on("data", (chunk) => {
+          data += chunk;
+        });
+        req.on("end", () => {
+          try {
+            resolveBody(JSON.parse(data || "{}"));
+          } catch (e) {
+            rejectBody(e);
+          }
+        });
+        req.on("error", rejectBody);
+      });
+      const metaMatch = /^\/api\/screen\/([\w][\w.-]*)\/meta$/.exec(path);
+      if (metaMatch && req.method === "POST") {
+        const body = await readBody();
+        const pos = body.pos;
+        if (pos !== undefined && (!Array.isArray(pos) || pos.length !== 2 || !pos.every((n) => Number.isFinite(n)))) {
+          return sendJson(res, 400, { error: "pos must be [x, y]." });
+        }
+        if (body.desc !== undefined && typeof body.desc !== "string") {
+          return sendJson(res, 400, { error: "desc must be a string." });
+        }
+        writeScreenMeta(designDir, metaMatch[1], { pos, desc: body.desc });
+        return sendJson(res, 200, { ok: true });
+      }
+      if (path === "/api/edges" && req.method === "POST") {
+        const body = await readBody();
+        const ids = new Set(listScreenFiles(designDir).map((s) => s.id));
+        if (typeof body.from !== "string" || typeof body.to !== "string" || !ids.has(body.from) || !ids.has(body.to)) {
+          return sendJson(res, 400, { error: "from/to must name existing screens." });
+        }
+        const index = addEdge(designDir, {
+          from: body.from,
+          to: body.to,
+          label: typeof body.label === "string" ? body.label : undefined,
+          activator: typeof body.activator === "string" ? body.activator : undefined
+        });
+        return sendJson(res, 200, { index });
+      }
+      const edgeMatch = /^\/api\/edges\/(\d+)$/.exec(path);
+      if (edgeMatch && (req.method === "PUT" || req.method === "DELETE")) {
+        const index = Number(edgeMatch[1]);
+        try {
+          if (req.method === "DELETE") {
+            removeEdge(designDir, index);
+          } else {
+            const body = await readBody();
+            updateEdge(designDir, index, {
+              label: typeof body.label === "string" ? body.label : undefined,
+              activator: typeof body.activator === "string" ? body.activator : undefined
+            });
+          }
+          return sendJson(res, 200, { ok: true });
+        } catch (e) {
+          return sendJson(res, 404, { error: e instanceof Error ? e.message : String(e) });
+        }
+      }
+      const textMatch = /^\/api\/screen\/([\w][\w.-]*)\/text$/.exec(path);
+      if (textMatch && req.method === "POST") {
+        const body = await readBody();
+        const frames = Array.isArray(body.frames) ? body.frames.filter((f) => !!f && typeof f.source === "string" && Number.isInteger(f.line) && Number.isInteger(f.column)) : [];
+        if (frames.length === 0 || typeof body.oldText !== "string" || typeof body.newText !== "string") {
+          return sendJson(res, 400, { error: "frames + oldText + newText required." });
+        }
+        const result = editTextAtSite({ root, designDir, frames, oldText: body.oldText, newText: body.newText });
+        if (result.ok && result.file)
+          log(`text edit → ${result.file}`);
+        return sendJson(res, 200, result);
+      }
+      const imageMatch = /^\/api\/screen\/([\w][\w.-]*)\/image$/.exec(path);
+      if (imageMatch && req.method === "POST") {
+        const body = await readBody();
+        const frames = Array.isArray(body.frames) ? body.frames.filter((f) => !!f && typeof f.source === "string" && Number.isInteger(f.line) && Number.isInteger(f.column)) : [];
+        if (frames.length === 0 || typeof body.oldSrc !== "string" || typeof body.name !== "string" || typeof body.data !== "string") {
+          return sendJson(res, 400, { error: "frames + oldSrc + name + data (base64) required." });
+        }
+        const data = Buffer.from(body.data, "base64");
+        if (data.length === 0)
+          return sendJson(res, 400, { error: "Empty image data." });
+        if (data.length > 24 * 1024 * 1024)
+          return sendJson(res, 400, { error: "Image too large (24MB max)." });
+        const result = replaceImageAtSite({ root, designDir, frames, oldSrc: body.oldSrc, name: body.name, data });
+        if (result.ok)
+          log(`image → ${result.path} (${result.file})`);
+        return sendJson(res, 200, result);
+      }
+      const screenMatch = /^\/api\/screen\/([\w][\w.-]*)$/.exec(path);
+      if (screenMatch) {
+        const id = screenMatch[1];
+        if (!listScreenFiles(designDir).some((s) => s.id === id)) {
+          return sendJson(res, 404, { error: `No screen "${id}" (screens/${id}.ts not found).` });
+        }
+        try {
+          const compiled = await getCompiled(id);
+          return sendJson(res, 200, compiled);
+        } catch (e) {
+          return sendJson(res, 200, { js: null, warnings: [], error: e instanceof Error ? e.message : String(e) });
+        }
+      }
+      if (path === "/events") {
+        res.writeHead(200, {
+          "content-type": "text/event-stream",
+          "cache-control": "no-store",
+          connection: "keep-alive"
+        });
+        res.write(`retry: 1000
+
+`);
+        clients.add(res);
+        const ping = setInterval(() => res.write(`: ping
+
+`), 30000);
+        req.on("close", () => {
+          clients.delete(res);
+          clearInterval(ping);
+        });
+        return;
+      }
+      if (path.startsWith("/project/")) {
+        if (sendFile(res, root, path.slice("/project/".length)))
+          return;
+        res.writeHead(404);
+        res.end("Not found");
+        return;
+      }
+      if (path !== "/" && sendFile(res, appDir, path))
+        return;
+      if (!sendFile(res, appDir, "index.html")) {
+        res.writeHead(503, { "content-type": "text/plain" });
+        res.end("The design board app is not built (missing dist/app). Reinstall lecodes-design or run its build.");
+      }
+    } catch (e) {
+      sendJson(res, 500, { error: e instanceof Error ? e.message : String(e) });
+    }
+  });
+  await new Promise((resolvePromise, reject) => {
+    server.once("error", reject);
+    server.listen(port, "127.0.0.1", () => resolvePromise());
+  });
+  return {
+    port,
+    url: `http://localhost:${port}`,
+    close: () => {
+      watcher?.close();
+      for (const res of clients)
+        res.end();
+      clients.clear();
+      server.close();
+    }
+  };
+};
+export {
+  writeScreenMeta,
+  updateEdge,
+  startDesignServer,
+  replaceImageAtSite,
+  removeEdge,
+  readDesignState,
+  listScreenFiles,
+  editTextAtSite,
+  addEdge
+};