htmlboard 0.5.0 → 0.7.0

package/src/client/index.html

@@ -29,9 +29,28 @@
         <kbd aria-hidden="true">/</kbd>
       </div>
       <div class="filters" id="filters" role="group" aria-label="Show" hidden></div>
+      <div class="sections-bar" id="sections-bar" hidden>
+        <span class="sections-label">Sections</span>
+        <div class="sections-tools" role="group" aria-label="All sections">
+          <button class="mini" type="button" id="expand-all" title="Expand all" aria-label="Expand all sections">
+            <svg viewBox="0 0 24 24" aria-hidden="true"><path d="m7 15 5 5 5-5M7 9l5-5 5 5"/></svg>
+          </button>
+          <button class="mini" type="button" id="collapse-all" title="Collapse all" aria-label="Collapse all sections">
+            <svg viewBox="0 0 24 24" aria-hidden="true"><path d="m7 20 5-5 5 5M7 4l5 5 5-5"/></svg>
+          </button>
+          <span class="mini-gap" aria-hidden="true"></span>
+          <button class="mini" type="button" id="show-all" title="Show all on the canvas" aria-label="Show all sections">
+            <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M2.06 12.35a1 1 0 0 1 0-.7 10.75 10.75 0 0 1 19.88 0 1 1 0 0 1 0 .7 10.75 10.75 0 0 1-19.88 0"/><circle cx="12" cy="12" r="3"/></svg>
+          </button>
+          <button class="mini" type="button" id="hide-all" title="Hide all from the canvas" aria-label="Hide all sections">
+            <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M10.73 5.08a10.74 10.74 0 0 1 11.2 6.57 1 1 0 0 1 0 .7 10.75 10.75 0 0 1-1.44 2.49M14.08 14.16a3 3 0 0 1-4.24-4.24M17.48 17.5a10.75 10.75 0 0 1-15.42-5.15 1 1 0 0 1 0-.7 10.75 10.75 0 0 1 4.45-5.14M2 2l20 20"/></svg>
+          </button>
+        </div>
+      </div>
       <p class="no-match" id="no-match" hidden>No design matches the search.</p>
       <nav class="list" id="list" aria-label="Designs by section"></nav>
       <p class="sidebar-hint">Drag or scroll to move, <kbd>Ctrl</kbd> + scroll or pinch to zoom, double-click a design to fit it. <kbd>?</kbd> lists the shortcuts.</p>
+
     </aside>
 
     <main class="viewport" id="viewport" aria-label="Canvas">
@@ -41,6 +60,14 @@
         <div class="outline outline--selected" id="selection" hidden></div>
         <div class="size" id="size" hidden></div>
       </div>
+      <div class="actions" id="actions" role="toolbar" aria-label="Design" hidden>
+        <button class="mini" type="button" id="copy-image" title="Copy as an image (C)" aria-label="Copy as an image">
+          <svg viewBox="0 0 24 24" aria-hidden="true"><rect width="14" height="14" x="8" y="8" rx="2"/><path d="M4 16c-1.1 0-2-.9-2-2V4c0-1.1.9-2 2-2h10c1.1 0 2 .9 2 2"/></svg>
+        </button>
+        <button class="mini" type="button" id="save-image" title="Save as an image (S); Shift + click: choose the folder" aria-label="Save as an image">
+          <svg viewBox="0 0 24 24" aria-hidden="true"><path d="M21 15v4a2 2 0 0 1-2 2H5a2 2 0 0 1-2-2v-4M7 10l5 5 5-5M12 15V3"/></svg>
+        </button>
+      </div>
 
       <div class="toolbar" role="toolbar" aria-label="Canvas">
         <button class="tool" type="button" id="toggle-list" title="Show or hide the list (\)" aria-label="Show or hide the list" aria-pressed="true">
@@ -83,6 +110,7 @@
           <div><dt><kbd>Shift</kbd> + <kbd>2</kbd>, double-click</dt><dd>Fit the design</dd></div>
           <div><dt><kbd>←</kbd> <kbd>→</kbd></dt><dd>Previous, next design</dd></div>
           <div><dt><kbd>Enter</kbd></dt><dd>Open the design on its own</dd></div>
+          <div><dt><kbd>C</kbd> <kbd>S</kbd></dt><dd>Copy, save the design as an image</dd></div>
           <div><dt><kbd>/</kbd></dt><dd>Search</dd></div>
           <div><dt><kbd>1</kbd> – <kbd>4</kbd></dt><dd>All, mobile, tablet, desktop</dd></div>
           <div><dt><kbd>R</kbd></dt><dd>Reload the designs</dd></div>
@@ -91,6 +119,11 @@
         </dl>
       </section>
 
+      <div class="empty" id="empty" hidden>
+        <p id="empty-text">All sections are hidden.</p>
+        <button class="empty-show" type="button" id="empty-show">Show all</button>
+      </div>
+
       <div class="toast" id="toast" role="status" aria-live="polite"></div>
       <div class="notice" id="notice" hidden>
         <img class="notice-mark" src="/__explorer/mark.svg" alt="" height="72">

package/src/client/picture.js

@@ -0,0 +1,281 @@
+// A design as an image, to copy or save it. The browser draws it from the page as its frame has it:
+// the page's HTML and CSS go into an SVG <foreignObject>, with the files they use (stylesheets, fonts,
+// images) inlined, since an image can't load anything. Scripts don't run in an image, so it shows the
+// page as built when it was taken.
+//
+// What it can't show: images from another site that doesn't allow reading them (CORS), pages inside
+// the page (iframes), shadow DOM. A video shows the frame it is at, or its poster.
+
+const MAX_SIDE = 16384; // px: the longest side browsers draw a canvas at
+const MAX_AREA = 64e6; // px: about 256 MB of pixels
+const LOAD_MS = 10000;
+const TRANSPARENT = 'data:image/gif;base64,R0lGODlhAQABAIAAAAAAAP///yH5BAEAAAAALAAAAAABAAEAAAIBRAA7';
+const URL_RE = /url\(\s*(['"]?)(.*?)\1\s*\)/gi;
+const IMPORT_RULE = 3;
+const FONT_FACE_RULE = 5;
+const LEFT_OUT = new Set(['script', 'noscript', 'style', 'link', 'source', 'track']);
+
+/**
+ * The page in `iframe` drawn on a canvas, `width` × `height` CSS px at `scale` device px per CSS px
+ * (less when that would make a canvas too big to draw).
+ */
+export async function drawDesign(iframe, { width, height, scale = 1 }) {
+  const doc = await loaded(iframe);
+  const win = iframe.contentWindow;
+  await doc.fonts?.ready;
+  const files = reader(win);
+  const [css, root] = await Promise.all([styles(doc, files), copyPage(doc, files)]);
+  const style = doc.createElement('style');
+  style.textContent = css;
+  (root.querySelector('head') || root).append(style);
+  const markup = new XMLSerializer().serializeToString(root);
+  const svg = `<svg xmlns="http://www.w3.org/2000/svg" width="${width}" height="${height}">`
+    + `<foreignObject x="0" y="0" width="${width}" height="${height}">${markup}</foreignObject></svg>`;
+  const image = new Image();
+  // A data: URL, not a blob: one, which would keep the canvas from being read (Chromium)
+  image.src = `data:image/svg+xml;charset=utf-8,${encodeURIComponent(svg)}`;
+  try {
+    await image.decode();
+  } catch {
+    throw new Error('the browser couldn’t draw this page');
+  }
+  scale = Math.min(scale, MAX_SIDE / width, MAX_SIDE / height, Math.sqrt(MAX_AREA / (width * height)));
+  const canvas = document.createElement('canvas');
+  canvas.width = Math.max(1, Math.round(width * scale));
+  canvas.height = Math.max(1, Math.round(height * scale));
+  const context = canvas.getContext('2d');
+  // The page's background fills the frame in a browser; in an image it would cover only its box.
+  context.fillStyle = backdrop(doc, win);
+  context.fillRect(0, 0, canvas.width, canvas.height);
+  context.drawImage(image, 0, 0, canvas.width, canvas.height);
+  return canvas;
+}
+
+/** The frame's page once it has loaded (a frame reloading after a save is waited for) */
+function loaded(iframe) {
+  const ready = () => {
+    const doc = iframe.contentDocument;
+    return doc && doc.readyState === 'complete' && doc.URL !== 'about:blank' ? doc : null;
+  };
+  if (ready()) return Promise.resolve(ready());
+  return new Promise((resolve, reject) => {
+    const done = () => {
+      clearTimeout(timer);
+      iframe.removeEventListener('load', done);
+      if (ready()) resolve(ready());
+      else reject(new Error('the page didn’t load'));
+    };
+    const timer = setTimeout(done, LOAD_MS);
+    iframe.addEventListener('load', done);
+  });
+}
+
+// ---------------------------------------------------------------- the files the page uses
+
+// Reads the files the page uses as data: URLs, each once. `used` holds the files the page loaded, to
+// leave out the fonts it never needed (another alphabet's part of a font); null when it can't tell.
+function reader(win) {
+  let used = null;
+  try {
+    const entries = win.performance.getEntriesByType('resource');
+    if (entries.length < 250) used = new Set(entries.map((entry) => entry.name)); // browsers stop listing at 250
+  } catch {
+    // Can't tell
+  }
+  const read = new Map();
+  return {
+    used,
+    // '' when it can't be read: missing, or another site's that doesn't allow it
+    dataUrl(url) {
+      if (!read.has(url)) {
+        read.set(url, fetch(url)
+          .then((res) => (res.ok ? res.blob() : null))
+          .then((blob) => (blob ? asDataUrl(blob) : ''))
+          .catch(() => ''));
+      }
+      return read.get(url);
+    },
+  };
+}
+
+function asDataUrl(blob) {
+  return new Promise((resolve) => {
+    const fileReader = new FileReader();
+    fileReader.onload = () => resolve(String(fileReader.result));
+    fileReader.onerror = () => resolve('');
+    fileReader.readAsDataURL(blob);
+  });
+}
+
+function absolute(url, base) {
+  try {
+    return new URL(url, base).href;
+  } catch {
+    return null;
+  }
+}
+
+/** CSS with every url(…) in it as a data: URL (an empty one for a file it can't read) */
+async function inlineUrls(css, base, files) {
+  const urls = new Map();
+  for (const [, , raw] of css.matchAll(URL_RE)) {
+    const url = raw.trim();
+    if (!url || urls.has(url) || /^(data:|#|about:)/i.test(url)) continue;
+    const full = absolute(url, base);
+    if (full) urls.set(url, files.dataUrl(full));
+  }
+  if (!urls.size) return css;
+  const data = new Map();
+  for (const [url, reading] of urls) data.set(url, await reading);
+  return css.replace(URL_RE, (whole, quote, raw) => {
+    const value = data.get(raw.trim());
+    return value === undefined ? whole : `url("${value || 'data:,'}")`;
+  });
+}
+
+// ---------------------------------------------------------------- the page's CSS
+
+/** All the CSS the page has, in its order, with the files it uses inlined */
+async function styles(doc, files) {
+  const parts = [];
+  for (const sheet of doc.styleSheets) if (!sheet.disabled) parts.push(await sheetCss(sheet, doc.baseURI, files));
+  for (const sheet of doc.adoptedStyleSheets || []) parts.push(await rulesCss(sheet.cssRules, doc.baseURI, files));
+  return parts.join('\n');
+}
+
+async function sheetCss(sheet, base, files, media = sheet.media?.mediaText) {
+  const href = sheet.href || base;
+  let css;
+  try {
+    css = await rulesCss(sheet.cssRules, href, files);
+  } catch {
+    // Another site's stylesheet, which the page can use but not read: fetched again, as most allow
+    // (font services and CDNs do).
+    css = sheet.href ? await fetch(sheet.href).then((res) => (res.ok ? res.text() : '')).catch(() => '') : '';
+    css = await inlineUrls(css, href, files);
+  }
+  return media && media !== 'all' ? `@media ${media} {\n${css}\n}` : css;
+}
+
+async function rulesCss(rules, base, files) {
+  const parts = [];
+  for (const rule of rules) {
+    if (rule.type === IMPORT_RULE) {
+      let css = rule.styleSheet ? await sheetCss(rule.styleSheet, base, files, rule.media?.mediaText) : '';
+      if (rule.supportsText) css = `@supports ${rule.supportsText} {\n${css}\n}`;
+      if (rule.layerName != null) css = `@layer${rule.layerName ? ` ${rule.layerName}` : ''} {\n${css}\n}`;
+      parts.push(css);
+    } else if (rule.type !== FONT_FACE_RULE || !unusedFont(rule, base, files.used)) {
+      parts.push(rule.cssText);
+    }
+  }
+  return inlineUrls(parts.join('\n'), base, files);
+}
+
+// A font face whose files the page never loaded
+function unusedFont(rule, base, used) {
+  if (!used) return false;
+  const urls = [...rule.cssText.matchAll(URL_RE)].map((match) => match[2].trim()).filter((url) => !/^data:/i.test(url));
+  return urls.length > 0 && !urls.some((url) => used.has(absolute(url, base)));
+}
+
+// ---------------------------------------------------------------- the page's HTML
+
+/**
+ * A copy of the page as it is now: without scripts and stylesheets (their CSS comes whole), with what
+ * the page's elements hold but their markup doesn't say (the image each <img> chose, form values, a
+ * canvas's drawing) and its files inlined.
+ */
+async function copyPage(doc, files) {
+  const root = doc.documentElement;
+  const copy = root.cloneNode(true);
+  const live = [root, ...root.querySelectorAll('*')];
+  const copies = [copy, ...copy.querySelectorAll('*')]; // the same elements, in the same order
+  const waits = [];
+  live.forEach((el, i) => {
+    const out = copies[i];
+    const tag = el.localName;
+    if (LEFT_OUT.has(tag)) {
+      out.remove();
+      return;
+    }
+    if (tag === 'img') {
+      const src = el.currentSrc || el.src;
+      for (const attribute of ['srcset', 'sizes', 'loading']) out.removeAttribute(attribute);
+      if (src) waits.push(files.dataUrl(src).then((data) => out.setAttribute('src', data || TRANSPARENT)));
+    } else if (tag === 'image' && (el.getAttribute('href') || el.getAttribute('xlink:href'))) {
+      const full = absolute(el.getAttribute('href') || el.getAttribute('xlink:href'), doc.baseURI);
+      if (full) {
+        waits.push(files.dataUrl(full).then((data) => {
+          out.removeAttribute('xlink:href');
+          out.setAttribute('href', data || TRANSPARENT);
+        }));
+      }
+    } else if (tag === 'canvas') {
+      // Without scripts (as in an image), a canvas shows what it holds instead of its drawing
+      asImage(el, out, canvasData(el));
+    } else if (tag === 'video') {
+      const frame = videoFrame(el);
+      waits.push((frame || !el.poster ? Promise.resolve(frame) : files.dataUrl(el.poster)).then((data) => asImage(el, out, data, 'contain')));
+    } else if (tag === 'iframe' || tag === 'frame' || tag === 'embed' || tag === 'object') {
+      for (const attribute of ['src', 'srcdoc', 'data']) out.removeAttribute(attribute);
+    } else if (tag === 'input') {
+      if (el.type === 'checkbox' || el.type === 'radio') out.toggleAttribute('checked', el.checked);
+      else if (el.type !== 'file') out.setAttribute('value', el.value);
+    } else if (tag === 'textarea') {
+      out.textContent = el.value;
+    } else if (tag === 'option') {
+      out.toggleAttribute('selected', el.selected);
+    }
+    const style = out.getAttribute('style');
+    if (style && /url\(/i.test(style)) waits.push(inlineUrls(style, doc.baseURI, files).then((css) => out.setAttribute('style', css)));
+  });
+  await Promise.all(waits);
+  return copy;
+}
+
+// An <img> of what a canvas or a video shows, in its place: its attributes (for the page's CSS) and
+// the size the page gave it.
+function asImage(el, out, data, fit = 'fill') {
+  const img = el.ownerDocument.createElement('img');
+  for (const { name, value } of out.attributes) {
+    if (!['src', 'poster', 'autoplay', 'controls', 'width', 'height'].includes(name)) img.setAttribute(name, value);
+  }
+  const style = el.ownerDocument.defaultView.getComputedStyle(el);
+  img.style.width = style.width;
+  img.style.height = style.height;
+  img.style.objectFit = fit;
+  img.src = data || TRANSPARENT;
+  out.replaceWith(img);
+}
+
+function canvasData(canvas) {
+  try {
+    return canvas.toDataURL();
+  } catch {
+    return 'data:,'; // drawn from another site: unreadable
+  }
+}
+
+function videoFrame(video) {
+  try {
+    if (video.readyState < 2 || !video.videoWidth) return '';
+    const canvas = document.createElement('canvas');
+    canvas.width = video.videoWidth;
+    canvas.height = video.videoHeight;
+    canvas.getContext('2d').drawImage(video, 0, 0);
+    return canvas.toDataURL('image/jpeg', 0.9);
+  } catch {
+    return '';
+  }
+}
+
+/** The colour that fills the page behind its content: the root's background, or the body's, or white */
+function backdrop(doc, win) {
+  for (const el of [doc.documentElement, doc.body]) {
+    if (!el) continue;
+    const color = win.getComputedStyle(el).backgroundColor;
+    if (color && !/^transparent$|,\s*0\)$|\/\s*0\)$/.test(color)) return color;
+  }
+  return '#FFFFFF';
+}

package/src/designs.js

@@ -120,12 +120,36 @@ function parseSettings(content) {
   return settings;
 }
 
-/** <meta name="htmlboard:variant" content="?tema=escuro · escuro">: the query, then a label */
+// A variant's own setting, as the htmlboard tag says it: width=390, height=844, category=mobile
+const VARIANT_SETTING = /^(width|height|category)=[^,;\s]+[,;]?$/i;
+const LABEL_START = /^[·|:,\-–—]+\s*/;
+
+/**
+ * <meta name="htmlboard:variant" content="?tema=escuro · escuro">: the file once more, with a
+ * query string, a size (width=390, height=844) or both, then a label. A query may leave out its "?".
+ */
 function parseVariant(content) {
-  const [, first, rest] = content.match(/^(\S+)\s*(.*)$/s);
-  const query = first.startsWith('?') ? first : `?${first}`;
-  if (query === '?') return null;
-  return { query, label: rest.replace(/^[·|:,\-–—]+\s*/, '').trim() };
+  const tokens = content.trim().split(/\s+/);
+  let query = '';
+  const settings = [];
+  let i = 0;
+  for (; i < tokens.length; i++) {
+    const token = tokens[i];
+    if (VARIANT_SETTING.test(token)) settings.push(token.replace(/[,;]$/, ''));
+    else if (token.startsWith('?') && !query) query = token;
+    else if (i === 0 && !LABEL_START.test(token)) query = `?${token}`;
+    else break;
+  }
+  if (query === '?') query = '';
+  const { width, height, category } = parseSettings(settings.join(','));
+  if (!query && !width && !height) return null;
+  return { query, label: tokens.slice(i).join(' ').replace(LABEL_START, '').trim(), ...compact({ width, height, category }) };
+}
+
+/** A variant as its tag's content says it: "?theme=dark width=390, height=844 · dark mobile" */
+export function formatVariant({ query = '', label = '', width, height, category }) {
+  const size = [width && `width=${width}`, height && `height=${height}`, category && `category=${category}`].filter(Boolean).join(', ');
+  return [query, size].filter(Boolean).join(' ') + (label ? ` · ${label}` : '');
 }
 
 /** What an HTML file says about itself, from its <head> (see the top of this file) */
@@ -196,12 +220,24 @@ function fileDesign(file, folder, meta) {
   });
 }
 
-function variantDesign(base, { query, label }) {
+// A variant of a file's design: another query string (a state the page builds from its URL), another
+// size (the same page at a phone's width), or both. Without a height of its own, a variant that
+// changes the width grows with its page. One that only changes the size loads the same URL as its
+// file, so its id comes from its label.
+function variantDesign(base, { query = '', label, width, height, category }) {
+  const sized = Boolean(width || height);
+  const size = sized ? { width: width ?? base.width, height: height ?? (width ? undefined : base.height) } : {};
+  const sizeName = sized ? `${size.width}${size.height ? ` × ${size.height}` : ''}` : '';
+  const name = label || [query.slice(1), sizeName].filter(Boolean).join(' · ');
   return compact({
     ...base,
-    key: base.file + query,
+    ...size,
+    key: base.file + query + (sized ? `@${size.width}x${size.height ?? ''}` : ''),
     file: base.file + query,
-    title: `${base.baseTitle} · ${label || query.slice(1)}`,
+    title: `${base.baseTitle} · ${name}`,
+    // A new size is a new device: its category comes from its size, unless it says one
+    category: sized ? category : category ?? base.category,
+    id: sized ? `${designId(base.file + query)}-${slugify(name)}` : undefined,
     variantOf: base.file
   });
 }

package/src/migrate.js

@@ -1,7 +1,7 @@
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { loadDesignsManifest, parseDesignMeta, stripPrefix } from './designs.js';
+import { loadDesignsManifest, parseDesignMeta, stripPrefix, formatVariant } from './designs.js';
 
 // `htmlboard migrate`: moves what a designs.json says about each design into the design's own file
 // (its size, category, label, variants and description) and leaves designs.json with what only it
@@ -110,7 +110,7 @@ export function planMigration(designsDir) {
       }
       for (const key of ['description', 'tags', 'id']) if (item.entry[key] !== undefined) item.keep[key] = item.entry[key];
     }
-    for (const v of declared) lines.push(`<meta name="htmlboard:variant" content="${escapeAttr(v.query + (v.label ? SEP + v.label : ''))}">`);
+    for (const v of declared) lines.push(`<meta name="htmlboard:variant" content="${escapeAttr(formatVariant(v))}">`);
 
     const next = rewriteHead(html, lines);
     if (next !== html) files.push({ file: base, lines, html: next });

package/src/server.js

@@ -224,7 +224,7 @@ export function createServer(options = {}) {
     const wanted = only.map((item) => item.replace(/\\/g, '/').replace(/^\.?\/+|\/+$/g, ''));
     const designs = loadDesignsManifest(targetDir, rootDir).sections
       .flatMap((section) => section.artboards)
-      .map(({ file, title, width, height, fit }) => ({ file, title, width, height, fit }))
+      .map(({ id, file, title, width, height, fit }) => ({ id, file, title, width, height, fit }))
       .filter(({ file }) => {
         const own = (designsPath ? file.slice(designsPath.length + 1) : file).split('?')[0];
         return !wanted.length || wanted.some((item) => !item || own === item || own.startsWith(`${item}/`));

package/src/skills.js

@@ -21,7 +21,8 @@ export const SKILL_TARGETS = {
 function bundledSkills() {
   return fs.readdirSync(SKILLS_DIR, { withFileTypes: true })
     .filter((entry) => entry.isDirectory() && fs.existsSync(path.join(SKILLS_DIR, entry.name, 'SKILL.md')))
-    .map((entry) => entry.name);
+    .map((entry) => entry.name)
+    .sort();
 }
 
 function resolveTargets(agent = 'all') {