htmlboard 0.4.0 → 0.5.0

package/src/client/check.js

@@ -0,0 +1,349 @@
+// Checking the designs (`htmlboard check`). Each design loads afresh, out of sight, in a frame of its
+// size, so the check sees the files as they are now, whatever the canvas shows (a filter, a reload
+// on its way). Once its page settles, the check reads what went wrong:
+//
+//   - what the probe noted while the page built (probe.js, which the server puts in framed pages):
+//     script errors, console.error, files that didn't load;
+//   - files the page asked for that aren't there (a stylesheet's fonts and images too);
+//   - components that weren't built, fonts that didn't load, a page that shows nothing;
+//   - layout: content cut at the frame's right edge, or below a frame of fixed height; text cut off
+//     by a box that hides what overflows it; text spilling out of its box.
+//
+// What a design means to do is left alone: text that ends in an ellipsis or is clamped, boxes that
+// scroll, content hidden or moved off the page on purpose.
+
+const AT_ONCE = 4; // designs loading at the same time
+const LOAD_MS = 10000; // a page that hasn't loaded by then is checked as it is, and said so
+const QUIET_MS = 300; // a page whose content hasn't changed for this long has settled…
+const SETTLE_MS = 3000; // …or this long after it loaded, if it keeps changing
+const MOST = 5; // boxes listed for a layout problem; the rest are counted
+
+const MEDIA = 'img, svg, video, canvas, picture, iframe, embed, object, input, select, textarea, button';
+const NOT_TEXT = new Set(['script', 'style', 'noscript', 'template', 'textarea', 'option', 'title']);
+const CLIPS = new Set(['hidden', 'clip']);
+const SCROLLS = new Set(['auto', 'scroll']);
+
+const wait = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+
+/**
+ * Check designs, each `{ file, title, width, height, frameHeight }` (height: the design's own, 0 when
+ * it grows with its page; frameHeight: its frame's), and say what went wrong in each.
+ */
+export async function checkDesigns(designs) {
+  const box = document.createElement('div');
+  box.setAttribute('aria-hidden', 'true');
+  box.style.cssText = 'position: fixed; left: 0; top: 0; width: 0; height: 0; overflow: hidden; visibility: hidden; pointer-events: none;';
+  document.body.append(box);
+  const results = [];
+  let next = 0;
+  const worker = async () => {
+    while (next < designs.length) {
+      const index = next++;
+      results[index] = await checkDesign(designs[index], box);
+    }
+  };
+  try {
+    await Promise.all(Array.from({ length: Math.min(AT_ONCE, designs.length) }, worker));
+  } finally {
+    box.remove();
+  }
+  await findMissing(results);
+  return results.map(({ resources, ...result }) => result);
+}
+
+async function checkDesign(design, box) {
+  const result = {
+    file: design.file, title: design.title, width: design.width, height: design.height || null,
+    problems: [], resources: new Map(),
+  };
+  const frame = document.createElement('iframe');
+  frame.name = 'htmlboard-check'; // the probe listens in these frames only
+  frame.setAttribute('scrolling', 'no');
+  frame.style.cssText = `position: absolute; left: 0; top: 0; border: 0; width: ${design.width}px; height: ${design.frameHeight}px;`;
+  const loaded = new Promise((resolve) => frame.addEventListener('load', () => resolve(true), { once: true }));
+  frame.src = encodeURI(`/${design.file}`);
+  box.append(frame);
+  try {
+    const finished = await Promise.race([loaded, wait(LOAD_MS).then(() => false)]);
+    const doc = frame.contentDocument;
+    if (!doc?.body) {
+      result.problems.push({ level: 'error', kind: 'blank' });
+      return result;
+    }
+    if (finished) await settle(doc);
+    else result.problems.push({ level: 'error', kind: 'timeout', seconds: LOAD_MS / 1000 });
+    inspect(frame.contentWindow, doc, design, result);
+  } catch (error) {
+    result.problems.push({ level: 'error', kind: 'check', message: String(error?.message || error) });
+  } finally {
+    frame.remove();
+  }
+  return result;
+}
+
+// Fonts in, components built, scripts done changing the page: quiet for QUIET_MS, or SETTLE_MS
+async function settle(doc) {
+  const start = performance.now();
+  await Promise.race([doc.fonts?.ready, wait(SETTLE_MS)]);
+  await new Promise((resolve) => {
+    let quiet = 0;
+    let cap = 0;
+    const observer = new doc.defaultView.MutationObserver(() => {
+      clearTimeout(quiet);
+      quiet = setTimeout(done, QUIET_MS);
+    });
+    function done() {
+      observer.disconnect();
+      clearTimeout(quiet);
+      clearTimeout(cap);
+      resolve();
+    }
+    observer.observe(doc.documentElement, { childList: true, subtree: true, characterData: true });
+    quiet = setTimeout(done, QUIET_MS);
+    cap = setTimeout(done, Math.max(QUIET_MS, SETTLE_MS - (performance.now() - start)));
+  });
+  await Promise.race([doc.fonts?.ready, wait(SETTLE_MS)]); // the fonts the new content asked for
+}
+
+/** A same-origin URL as its path from the server's root (`{ path: "/01-screens/app.js" }`), any other as it is */
+function where(url) {
+  try {
+    const parsed = new URL(url, location.href);
+    return parsed.origin === location.origin ? { path: decodeURIComponent(parsed.pathname) } : { url: parsed.href };
+  } catch {
+    return { url: String(url) };
+  }
+}
+
+// The same problem again and again (an error in a loop) is listed once, with how many times
+function addCounted(problems, problem) {
+  const key = JSON.stringify(problem);
+  const same = problems.find((other) => other.key === key);
+  if (same) same.count = (same.count || 1) + 1;
+  else problems.push(Object.defineProperty({ ...problem }, 'key', { value: key }));
+}
+
+function inspect(win, doc, design, { problems, resources }) {
+  const body = doc.body;
+  const cache = (measure) => {
+    const known = new Map();
+    return (el) => {
+      if (!known.has(el)) known.set(el, measure(el));
+      return known.get(el);
+    };
+  };
+  const style = cache((el) => win.getComputedStyle(el));
+  const rect = cache((el) => el.getBoundingClientRect());
+  const hidden = cache((el) => {
+    const own = style(el);
+    return own.visibility !== 'visible' || own.opacity === '0'
+      || Boolean(el.parentElement && el.parentElement !== doc.documentElement && hidden(el.parentElement));
+  });
+  // A box that hides or scrolls what overflows it
+  const keeps = (el) => style(el).overflowX !== 'visible' || style(el).overflowY !== 'visible';
+
+  // What the probe noted while the page built
+  const loads = new Set();
+  for (const note of win.__htmlboard?.problems ?? []) {
+    if (note.kind === 'script') {
+      const source = note.source ? { source: where(note.source).path ?? note.source, line: note.line } : {};
+      addCounted(problems, { level: 'error', kind: 'script', message: note.message, ...source });
+    } else if (note.kind === 'console') {
+      addCounted(problems, { level: 'error', kind: 'console', message: note.message });
+    } else if (note.kind === 'load') {
+      loads.add(note.url);
+      addCounted(problems, { level: 'error', kind: 'load', tag: note.tag, ...(note.url ? where(note.url) : {}) });
+    }
+  }
+
+  // Images that didn't load, if the probe didn't hear of them
+  for (const img of doc.images) {
+    const src = img.currentSrc || img.src;
+    if (img.complete && !img.naturalWidth && src && !loads.has(src)) {
+      loads.add(src);
+      addCounted(problems, { level: 'error', kind: 'load', tag: 'img', ...where(src) });
+    }
+  }
+
+  // Elements of tags nobody defined: components with no file, or a page that doesn't load components.js
+  const tags = new Set([...doc.querySelectorAll(':not(:defined)')].map((el) => el.localName).filter((name) => name.includes('-')));
+  if (tags.size) {
+    const loader = [...doc.querySelectorAll('script[src]')]
+      .find((script) => /(^|\/)components\.js$/.test(new URL(script.src, doc.baseURI).pathname));
+    for (const tag of tags) {
+      problems.push(loader
+        ? { level: 'error', kind: 'component', tag, ...where(new URL(`components/${tag}.html`, loader.src)) }
+        : { level: 'error', kind: 'component', tag, loader: false });
+    }
+  }
+
+  // Fonts the page uses that didn't load
+  const families = new Set();
+  for (const face of doc.fonts ?? []) if (face.status === 'error') families.add(face.family.replace(/^(["'])(.*)\1$/, '$2'));
+  for (const family of families) problems.push({ level: 'error', kind: 'font', family });
+
+  // Every file the page asked this server for (its stylesheets' fonts and images, its fetches too):
+  // which ones aren't there is asked once all the designs are checked
+  for (const entry of win.performance.getEntriesByType('resource')) {
+    const { path } = where(entry.name);
+    if (path && !path.startsWith('/__explorer/') && !path.startsWith('/api/')) resources.set(path, entry.responseStatus || 0);
+  }
+
+  if (!body.innerText.trim() && ![...body.querySelectorAll('*')].some((el) => !hidden(el) && rect(el).width > 0 && rect(el).height > 0)) {
+    problems.push({ level: 'error', kind: 'blank' });
+    return;
+  }
+
+  // Content cut at the right edge: the outermost boxes that cross it (or, in the page's flow, start
+  // past it) with something to see in them. A box that hides or scrolls its overflow keeps it inside.
+  const width = win.innerWidth;
+  const beyond = [];
+  const hasContent = (el) => el.matches(MEDIA) || Boolean(el.querySelector(MEDIA)) || Boolean(el.innerText?.trim());
+  const visit = (el) => {
+    for (const child of el.children) {
+      const s = style(child);
+      if (NOT_TEXT.has(child.localName) || s.display === 'none' || s.position === 'fixed') continue;
+      const r = rect(child);
+      const crosses = r.left < width - 1 && r.right > width + 1;
+      const past = r.left >= width && s.position === 'static' && s.transform === 'none';
+      if ((crosses || past) && r.width > 0 && r.height > 0 && !hidden(child) && hasContent(child)) {
+        beyond.push({ selector: describe(child), right: Math.round(r.right) });
+      } else if (s.overflowX === 'visible') {
+        visit(child);
+      }
+    }
+  };
+  if (rect(body).right > width + 1 && hasContent(body)) beyond.push({ selector: 'body', right: Math.round(rect(body).right) });
+  else visit(body);
+  if (beyond.length) {
+    problems.push({ level: 'layout', kind: 'beyond', frame: width, elements: beyond.slice(0, MOST), ...(beyond.length > MOST ? { more: beyond.length - MOST } : {}) });
+  }
+
+  // Text: cut off by a box that hides what overflows it, or spilling out of its box. Each text is
+  // measured against the boxes around it, from the nearest, up to the first it doesn't fit in (or one
+  // that keeps its overflow inside: past it, nothing can cut it).
+  const cut = new Map(); // box → { overflow, text, count }
+  const spilled = new Map();
+  const note = (map, box, node, detail) => {
+    if (map.has(box)) map.get(box).count++;
+    else map.set(box, { ...detail, text: snippet(node.data), count: 1 });
+  };
+  let bottom = 0; // where the content that no box keeps inside ends
+  const walker = doc.createTreeWalker(body, NodeFilter.SHOW_TEXT);
+  const range = doc.createRange();
+  for (let node = walker.nextNode(); node; node = walker.nextNode()) {
+    const parent = node.parentElement;
+    if (!node.data.trim() || !parent || NOT_TEXT.has(parent.localName) || hidden(parent)) continue;
+    range.selectNodeContents(node);
+    const lines = [...range.getClientRects()].filter((r) => r.width > 0 && r.height > 0);
+    if (!lines.length) continue;
+    const text = {
+      left: Math.min(...lines.map((r) => r.left)),
+      right: Math.max(...lines.map((r) => r.right)),
+      top: Math.min(...lines.map((r) => r.top)),
+      bottom: Math.max(...lines.map((r) => r.bottom)),
+    };
+    // A line's box is taller than its line when the line height is small: that much isn't overflow
+    const slack = parseFloat(style(parent).fontSize) * 0.35 + 1 || 6;
+    let kept = false;
+    for (let el = parent; el && el !== body; el = el.parentElement) {
+      const s = style(el);
+      if (s.display === 'inline' || s.display === 'contents') continue;
+      const r = rect(el);
+      const overX = text.left < r.left - 1 || text.right > r.right + 1;
+      const overY = text.top < r.top - slack || text.bottom > r.bottom + slack;
+      if (!overX && !overY) {
+        if (keeps(el)) {
+          kept = true;
+          break;
+        }
+        continue;
+      }
+      kept = true;
+      const cuts = (overX && CLIPS.has(s.overflowX)) || (overY && CLIPS.has(s.overflowY));
+      const scrolls = (overX && SCROLLS.has(s.overflowX)) || (overY && SCROLLS.has(s.overflowY));
+      const meant = s.textOverflow === 'ellipsis' || (s.webkitLineClamp && s.webkitLineClamp !== 'none') || r.width <= 2 || r.height <= 2;
+      if (meant) break;
+      if (cuts) note(cut, el, node, { overflow: overX && CLIPS.has(s.overflowX) ? s.overflowX : s.overflowY });
+      else if (!scrolls) note(spilled, el, node, {});
+      break;
+    }
+    if (!kept) bottom = Math.max(bottom, text.bottom);
+  }
+  for (const media of body.querySelectorAll(MEDIA)) {
+    const r = rect(media);
+    if (r.width > 0 && r.height > 0 && !hidden(media) && ![...ancestors(media, body)].some(keeps)) bottom = Math.max(bottom, r.bottom);
+  }
+  for (const [map, kind] of [[cut, 'cut'], [spilled, 'spill']]) {
+    for (const [box, { count, ...detail }] of [...map].slice(0, MOST)) {
+      problems.push({ level: 'layout', kind, selector: describe(box), ...detail, ...(count > 1 ? { count } : {}) });
+    }
+    if (map.size > MOST) problems.push({ level: 'layout', kind, more: map.size - MOST });
+  }
+
+  // A frame of fixed height cuts what goes past it (fine for a screen that scrolls, not for a flyer)
+  if (design.height && bottom > win.innerHeight + 1) {
+    problems.push({ level: 'note', kind: 'below', bottom: Math.round(bottom), frame: win.innerHeight });
+  }
+}
+
+function snippet(text) {
+  const flat = text.replace(/\s+/g, ' ').trim();
+  return flat.length > 40 ? `${flat.slice(0, 39)}…` : flat;
+}
+
+function* ancestors(el, until) {
+  for (let node = el.parentElement; node && node !== until; node = node.parentElement) yield node;
+}
+
+/**
+ * How to find an element: its tag (but div and span) with its id or first classes, after the
+ * element around it that has one when it has neither; and, inside a component, the component first.
+ */
+function describe(el) {
+  const own = (node) => {
+    if (node.localName.includes('-')) return `<${node.localName}>`;
+    const tag = node.localName === 'div' || node.localName === 'span' ? '' : node.localName;
+    if (node.id) return `${tag}#${node.id}`;
+    const classes = [...node.classList].slice(0, 2);
+    return classes.length ? `${tag}.${classes.join('.')}` : node.localName;
+  };
+  let text = own(el);
+  if (!el.id && !el.classList.length && !el.localName.includes('-')) {
+    const named = el.parentElement?.closest('[id], [class]');
+    if (named && named !== el.ownerDocument.body) text = `${own(named)} ${text}`;
+  }
+  const component = [...ancestors(el)].find((node) => node.localName.includes('-'));
+  if (component && !text.startsWith('<')) text = `<${component.localName}> ${text}`;
+  return text;
+}
+
+// Same-origin files the pages asked for that the server doesn't have, components' files among them.
+// Each file is asked about once, however many designs use it.
+async function findMissing(results) {
+  const status = new Map(); // path → HTTP status (0: not known yet)
+  for (const { resources, problems } of results) {
+    for (const [file, code] of resources) if (code || !status.has(file)) status.set(file, code);
+    for (const problem of problems) if (problem.path && !status.has(problem.path)) status.set(problem.path, 0);
+  }
+  await Promise.all([...status].filter(([, code]) => !code).map(async ([file]) => {
+    try {
+      status.set(file, (await fetch(encodeURI(file), { method: 'HEAD', cache: 'no-store' })).status);
+    } catch {
+      // Can't tell
+    }
+  }));
+  const missing = (file) => status.get(file) === 404;
+  for (const { resources, problems } of results) {
+    const named = new Set();
+    for (const problem of problems) {
+      if (!problem.path) continue;
+      named.add(problem.path);
+      if (problem.kind === 'component') problem.found = !missing(problem.path);
+      else if (problem.kind === 'load' && missing(problem.path)) problem.kind = 'missing';
+    }
+    for (const [file] of resources) {
+      if (missing(file) && !named.has(file)) problems.push({ level: 'error', kind: 'missing', path: file });
+    }
+  }
+}

package/src/client/explorer.js

@@ -4,7 +4,9 @@
 // so they stay sharp and readable at any zoom. The server lists the designs at /api/designs and
 // pushes saved files at /api/events.
 
-const FRAME_GAP = 120;     // canvas px between the designs of a section
+import { checkDesigns } from './check.js';
+
+const FRAME_GAP = 120;    // canvas px between the designs of a section
 const SECTION_GAP = 560;   // canvas px between sections
 const MIN_ZOOM = 0.02;
 const MAX_ZOOM = 8;
@@ -19,6 +21,7 @@ const DRAG_SLOP = 4;       // screen px a press can move and still be a click
 const DOUBLE_MS = 350;
 const CHANGE_MS = 60;      // saved files arriving this close together are applied at once
 const DEFAULT_SIZE = [1200, 800]; // a design whose entry gives no size; without a height it grows with its page
+const FIT_HEIGHT = 100;    // a frame that fits its page however short (a component's) starts this tall
 
 const $ = (id) => document.getElementById(id);
 const els = {
@@ -141,7 +144,8 @@ function makeDesign(board, section) {
     path: `/${file.split('?')[0]}`,
     title: board.title || file,
     w: Number(board.width) || DEFAULT_SIZE[0],
-    h: Number(board.height) || DEFAULT_SIZE[1],
+    // A page is never shorter than its frame, so a frame grows to its page but can't shrink to it
+    h: Number(board.height) || (board.fit ? FIT_HEIGHT : DEFAULT_SIZE[1]),
     autoHeight: !Number(board.height),
     x: 0,
     y: 0,
@@ -185,6 +189,15 @@ function onLoad(design) {
   if (!doc || !design.autoHeight) return;
   growToPage(design);
   doc.fonts?.ready.then(() => growToPage(design));
+  // Pages go on building themselves after they load (components, scripts): measured again when
+  // they change. Not when the frame grows: a page always a bit taller than its frame would grow forever.
+  let timer = 0;
+  new design.iframe.contentWindow.MutationObserver(() => {
+    clearTimeout(timer);
+    timer = setTimeout(() => {
+      if (design.autoHeight && design.iframe.contentDocument === doc) growToPage(design);
+    }, 50);
+  }).observe(doc.documentElement, { childList: true, subtree: true });
 }
 
 // A design without a height takes its page's.
@@ -753,6 +766,13 @@ function connect() {
       // Not ours.
     }
   });
+  source.addEventListener('check', (event) => {
+    try {
+      takeCheck(JSON.parse(event.data));
+    } catch {
+      // Not ours.
+    }
+  });
   // EventSource keeps trying to reconnect by itself.
   source.addEventListener('error', () => {
     lost = true;
@@ -760,6 +780,52 @@ function connect() {
   });
 }
 
+// ---------------------------------------------------------------- checking (htmlboard check)
+
+let checking = Promise.resolve();
+
+// The server asks every open canvas: the first to claim a check does it, after the ones it's doing.
+async function takeCheck(request) {
+  let claimed = false;
+  try {
+    claimed = (await fetch(`/api/check/${request.id}/claim`, { method: 'POST' })).ok;
+  } catch {
+    // The server is gone
+  }
+  if (claimed) checking = checking.then(() => runCheck(request));
+}
+
+async function runCheck({ id, designs: boards }) {
+  const designs = boards.map((board) => {
+    const shown = state.designs.find((d) => d.file === board.file);
+    const height = Number(board.height) || 0;
+    return {
+      file: board.file,
+      title: board.title || board.file,
+      width: Number(board.width) || DEFAULT_SIZE[0],
+      height,
+      // Without a height, the frame is as tall as the canvas has it (as tall as its page)
+      frameHeight: height || (shown?.autoHeight ? shown.h : board.fit ? FIT_HEIGHT : DEFAULT_SIZE[1]),
+    };
+  });
+  const what = designs.length === 1 ? designs[0].title : `${designs.length} designs`;
+  toast(`Checking ${what}…`);
+  let report;
+  try {
+    report = { designs: await checkDesigns(designs) };
+  } catch (err) {
+    report = { error: String(err?.message || err) };
+  }
+  try {
+    await fetch(`/api/check/${id}`, { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(report) });
+  } catch {
+    return;
+  }
+  const failing = (report.designs || []).filter((d) => d.problems.some((p) => p.level !== 'note')).length;
+  const verdict = !failing ? 'no problems' : designs.length === 1 ? 'problems found' : `${failing} with problems`;
+  toast(report.error ? `Couldn't check ${what}: ${report.error}` : `Checked ${what}: ${verdict}`);
+}
+
 function setLive(on) {
   els.live.hidden = false;
   els.live.classList.toggle('is-off', !on);

package/src/client/probe.js

@@ -0,0 +1,41 @@
+// probe.js: notes what goes wrong while a design's page builds (script errors, console.error, files
+// that don't load), for `htmlboard check`. The server puts it first in the <head> of the pages shown
+// in frames, so it hears everything from the start. It only listens in the frames the check loads
+// (named htmlboard-check): the canvas's own frames, and a page opened on its own, are left as they are.
+(() => {
+  if (window.name !== 'htmlboard-check') return;
+  const MOST = 100;
+  const problems = [];
+  const note = (problem) => {
+    if (problems.length < MOST) problems.push(problem);
+  };
+  const describe = (value) => {
+    if (value instanceof Error) return `${value.name}: ${value.message}`;
+    if (typeof value === 'string') return value;
+    try {
+      return JSON.stringify(value) ?? String(value);
+    } catch {
+      return String(value);
+    }
+  };
+  // Capturing: an element's failed load (an <img>, a <script>, a <link>) doesn't bubble
+  addEventListener('error', (event) => {
+    const { target } = event;
+    if (target instanceof Element) {
+      const url = [target.currentSrc, target.src, target.href, target.href?.baseVal].find((value) => typeof value === 'string');
+      note({ kind: 'load', tag: target.localName, url: url || '' });
+    } else {
+      const message = event.message || describe(event.error);
+      note({ kind: 'script', message: message.replace(/^Uncaught /, ''), source: event.filename || '', line: event.lineno || 0 });
+    }
+  }, true);
+  addEventListener('unhandledrejection', (event) => {
+    note({ kind: 'script', message: `(in a promise) ${describe(event.reason)}`, source: '', line: 0 });
+  });
+  const error = console.error;
+  console.error = function (...args) {
+    note({ kind: 'console', message: args.map(describe).join(' ') });
+    return error.apply(this, args);
+  };
+  Object.defineProperty(window, '__htmlboard', { value: Object.freeze({ problems }) });
+})();

package/src/components.js

@@ -0,0 +1,95 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+// Components: every file in a designs folder's components/ is a custom element named after it
+// (components/tx-item.html is <tx-item>), built in the page by components.js, the script beside
+// the folder that designs load like they link styles.css. A component file is a piece of HTML that
+// starts with a comment showing how to use it; that example is also its preview on the canvas.
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+
+/** The folder of components, at the top of the designs folder */
+export const COMPONENTS_FOLDER = 'components';
+/** The script that turns them into custom elements, beside the folder */
+export const COMPONENTS_SCRIPT = 'components.js';
+/** The script as htmlboard ships it */
+export const COMPONENTS_SCRIPT_SOURCE = path.join(__dirname, 'templates', COMPONENTS_SCRIPT);
+/** A component's preview on the canvas is this wide, unless its file says otherwise */
+export const PREVIEW_WIDTH = 480;
+
+const RESERVED = new Set(['annotation-xml', 'color-profile', 'font-face', 'font-face-src', 'font-face-uri',
+  'font-face-format', 'font-face-name', 'missing-glyph']);
+
+/** A name a custom element can have: lowercase, starting with a letter, with a hyphen */
+export function isTagName(name) {
+  return /^[a-z][-.0-9_a-z·À-\u{EFFFF}]*$/u.test(name) && name.includes('-') && !RESERVED.has(name);
+}
+
+/** A whole page (<!DOCTYPE html> or <html> first), not a piece of one: a design, even in components/ */
+export function isPage(html) {
+  return /^\s*(?:<!--[\s\S]*?-->\s*)*(?:<!doctype\s+html|<html[\s>])/i.test(html);
+}
+
+/** How a component is used: the comment its file starts with, else the bare element */
+export function componentExample(html, tag) {
+  const comment = html.match(/^\s*<!--([\s\S]*?)-->/);
+  return comment?.[1].trim() || `<${tag}></${tag}>`;
+}
+
+/**
+ * The page that shows a component on the canvas (components/<tag>.html?preview): its example, with
+ * the stylesheets at the top of the designs folder and components.js. Null for any other file.
+ */
+export function componentPreview(designsDir, file) {
+  if (path.dirname(file) !== path.join(designsDir, COMPONENTS_FOLDER) || !/\.html$/.test(file)) return null;
+  const tag = path.basename(file, '.html');
+  if (!isTagName(tag)) return null;
+  let html;
+  try {
+    html = fs.readFileSync(file, 'utf8');
+  } catch {
+    return null;
+  }
+  if (isPage(html)) return null;
+  const stylesheets = fs.readdirSync(designsDir, { withFileTypes: true })
+    .filter((entry) => entry.isFile() && /\.css$/i.test(entry.name))
+    .map((entry) => entry.name)
+    .sort();
+  return `<!DOCTYPE html>
+<html lang="en">
+<head>
+  <meta charset="UTF-8">
+  <title>&lt;${tag}&gt;</title>
+${stylesheets.map((name) => `  <link rel="stylesheet" href="../${encodeURI(name)}">\n`).join('')}  <script type="module" src="../${COMPONENTS_SCRIPT}"></script>
+  <style>body { display: grid; gap: 16px; margin: 0; padding: 24px; }</style>
+</head>
+<body>
+${componentExample(html, tag)}
+</body>
+</html>
+`;
+}
+
+/**
+ * Add components.js (and the components/ folder) to a designs folder. A components.js that differs
+ * from htmlboard's (an older one, or one edited by hand) is kept unless `force` is set.
+ *
+ * @param {object} [options]
+ * @param {string} [options.dir=process.cwd()] The designs folder
+ * @param {boolean} [options.force=false] Replace a components.js that differs
+ * @returns {{path: string, status: 'installed'|'updated'|'unchanged'|'skipped'}}
+ */
+export function installComponents({ dir = process.cwd(), force = false } = {}) {
+  const designsDir = path.resolve(dir);
+  const dest = path.join(designsDir, COMPONENTS_SCRIPT);
+  const script = fs.readFileSync(COMPONENTS_SCRIPT_SOURCE);
+  let status = 'installed';
+  if (fs.existsSync(dest)) {
+    if (fs.readFileSync(dest).equals(script)) status = 'unchanged';
+    else status = force ? 'updated' : 'skipped';
+  }
+  fs.mkdirSync(path.join(designsDir, COMPONENTS_FOLDER), { recursive: true });
+  if (status === 'installed' || status === 'updated') fs.writeFileSync(dest, script);
+  return { path: dest, status };
+}