@openbooknetwork/kitap 0.0.0-stage → 0.3.0

package/src/image.mjs

@@ -0,0 +1,214 @@
+// Image folders: content/shared/images/<id>/ for every story, content/<story>/shared/images/<id>/ for one. Each holds
+// image.yaml with the caption, the credit, where the original came from, its file name and sha256. The original,
+// image.<ext>, stays on the machine that added it, and the asset store holds it with its WebP sizes.
+import fs from 'fs';
+import path from 'path';
+import crypto from 'crypto';
+import yaml from 'js-yaml';
+import { libraryItems, storyFolders, isImage } from './folders.mjs';
+import { check, ImageFolder } from './schema.mjs';
+
+export const SIZES_VERSION = 1; // part of the keys of the WebP sizes, bumped when the sizes or their encoding change
+export const MAX_BYTES = 20e6;
+const TYPES = { '.jpg': 'image/jpeg', '.jpeg': 'image/jpeg', '.png': 'image/png', '.gif': 'image/gif', '.webp': 'image/webp', '.svg': 'image/svg+xml' };
+export const contentType = ext => TYPES[ext] ?? 'application/octet-stream';
+const FORMAT = { '.jpg': 'jpeg', '.jpeg': 'jpeg', '.png': 'png', '.gif': 'gif', '.webp': 'webp', '.svg': 'svg' };
+
+export const sha256Of = bytes => crypto.createHash('sha256').update(bytes).digest('hex');
+export const sha256 = file => sha256Of(fs.readFileSync(file));
+// The keys of an image's objects in the asset store, from its folder id and the file and sha256 of its image.yaml.
+export const imageKeys = (id, { file, sha256: hash }) => ({
+  original: `images/${hash}/${id}${path.extname(file)}`,
+  large: `images/${hash}/s${SIZES_VERSION}/${id}-1280.webp`,
+  small: `images/${hash}/s${SIZES_VERSION}/${id}-320.webp`,
+});
+
+// The format the bytes hold, by their first bytes, or null.
+function formatOf(b) {
+  if (b[0] === 0xff && b[1] === 0xd8 && b[2] === 0xff) return 'jpeg';
+  if (b.subarray(0, 8).equals(Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]))) return 'png';
+  if (b.toString('latin1', 0, 4) === 'GIF8') return 'gif';
+  if (b.toString('latin1', 0, 4) === 'RIFF' && b.toString('latin1', 8, 12) === 'WEBP') return 'webp';
+  // an XML declaration, comments and a doctype may come before the svg element
+  const head = b.toString('utf8', 0, 65536);
+  if (/^?\s*(<\?xml[^>]*>\s*)?(<!--[\s\S]*?-->\s*|<!DOCTYPE[^[>]*(\[[\s\S]*?\])?\s*>\s*)*<svg[\s>]/i.test(head)) return 'svg';
+  return null;
+}
+
+// true when an EXIF block holds a position: IFD0 points at a GPS IFD with a latitude or a longitude in it
+function exifHasPosition(exif) {
+  const t = exif.toString('latin1', 0, 6) === 'Exif\0\0' ? exif.subarray(6) : exif;
+  if (t.length < 8) return false;
+  const le = t.toString('latin1', 0, 2) === 'II';
+  const u16 = o => le ? t.readUInt16LE(o) : t.readUInt16BE(o), u32 = o => le ? t.readUInt32LE(o) : t.readUInt32BE(o);
+  const tags = ifd => {
+    const found = new Map();
+    if (ifd + 2 > t.length) return found;
+    for (let i = 0, n = u16(ifd); i < n && ifd + 14 + i * 12 <= t.length; i++) found.set(u16(ifd + 2 + i * 12), u32(ifd + 10 + i * 12));
+    return found;
+  };
+  try {
+    const gps = tags(u32(4)).get(0x8825);
+    if (gps == null) return false;
+    const g = tags(gps);
+    return g.has(2) || g.has(4);
+  } catch { return false; } // a block too short for its own offsets holds no position
+}
+
+// What an SVG must not hold: anything that runs code or loads a file when the SVG is opened.
+const SVG_RULES = [
+  [/<script[\s>/]/i, () => 'a script'],
+  [/\s(on[a-z]+)\s*=/i, m => `the event attribute ${m[1]}`],
+  [/\s((?:xlink:)?href|src)\s*=\s*["']\s*(?!#|data:)([^"']*)/i, m => `a reference to ${m[2] || 'another file'}`],
+  [/url\(\s*["']?\s*(?!#|data:)([^)"']*)/i, m => `a reference to ${m[1]}`],
+  [/@import\b/i, () => 'a stylesheet import'],
+  [/<!ENTITY[^>]*\b(SYSTEM|PUBLIC)\b/i, () => 'an outside entity'],
+];
+
+// Refuses an original over 20 MB, one whose bytes are not the format its extension names, one with a position in its
+// EXIF or XMP metadata, and an SVG that holds a script, an event attribute or a reference outside the file.
+export async function checkOriginal(bytes, ext, where) {
+  if (bytes.length > MAX_BYTES) throw new Error(`${where}: ${(bytes.length / 1e6).toFixed(1)} MB, an original is at most ${MAX_BYTES / 1e6} MB, add a smaller copy`);
+  const want = FORMAT[ext.toLowerCase()], got = formatOf(bytes);
+  if (got !== want) throw new Error(`${where}: the file ends in ${ext} and holds ${got ? `${got.toUpperCase()} bytes` : 'bytes of no image format'}, add it with the extension of its format`);
+  if (got === 'svg') {
+    const text = bytes.toString('utf8');
+    for (const [re, what] of SVG_RULES) {
+      const m = text.match(re);
+      if (m) throw new Error(`${where}: the SVG holds ${what(m)}, remove it and add the file again`);
+    }
+    return;
+  }
+  const sharp = (await import('sharp')).default;
+  let meta;
+  try { meta = await sharp(bytes).metadata(); } catch (err) { throw new Error(`${where}: the ${got.toUpperCase()} does not read (${err.message})`); }
+  const xmp = meta.xmp ? meta.xmp.toString('utf8') : '';
+  if ((meta.exif && exifHasPosition(meta.exif)) || /GPS(Latitude|Longitude)/.test(xmp))
+    throw new Error(`${where}: the file holds the place it was taken in its metadata, remove the location and add the file again`);
+}
+
+// a source as a page address, so File%3AA%20b.jpg over http and File:A_b.jpg over https are one source, and
+// object.php?id=101 and ?id=202 are two
+const sameSource = url => { try { const u = new URL(url); return u.host + decodeURIComponent(u.pathname).replace(/ /g, '_') + u.search; } catch { return url; } };
+const readMeta = dir => { try { return yaml.load(fs.readFileSync(path.join(dir, 'image.yaml'), 'utf8')) ?? {}; } catch { return {}; } };
+// a field of image.yaml set in place, so the other lines and their comments stay. A new field goes before the field
+// named by before, else at the end.
+function setField(dir, key, value, before = null) {
+  const file = path.join(dir, 'image.yaml'), text = fs.readFileSync(file, 'utf8'), line = `${key}: ${value}`, at = new RegExp(`^${key}:.*$`, 'm');
+  const next = before && text.match(new RegExp(`^${before}:`, 'm'));
+  fs.writeFileSync(file, at.test(text) ? text.replace(at, line) : next ? text.slice(0, next.index) + line + '\n' + text.slice(next.index) : text.replace(/\n?$/, '\n') + line + '\n');
+}
+const removeField = (dir, key) => { const file = path.join(dir, 'image.yaml'); fs.writeFileSync(file, fs.readFileSync(file, 'utf8').replace(new RegExp(`^${key}:.*\n?`, 'm'), '')); };
+
+// Every image folder the content holds, with its stored fields. file and size describe the original on this machine,
+// and are null where it is elsewhere.
+export function imageIndex({ root = process.cwd() } = {}) {
+  const content = path.join(root, 'content'), index = [];
+  // the image folders of a library, in its groups too
+  const folders = (dir, story) => {
+    for (const [id, d] of libraryItems(dir, isImage, p => path.relative(root, p))) {
+      const m = readMeta(d), files = fs.readdirSync(d).filter(f => /^image\.\w+$/.test(f) && f !== 'image.yaml');
+      const f = files.includes(m.file) ? m.file : files[0], file = f ? path.join(d, f) : null;
+      index.push({ id, story, dir: d, meta: fs.existsSync(path.join(d, 'image.yaml')), file, size: file ? fs.statSync(file).size : null,
+        source: m.source ?? null, url: m.url ?? null, name: m.file ?? null, sha256: m.sha256 ?? null });
+    }
+  };
+  folders(path.join(content, 'shared', 'images'), null);
+  for (const [s, d] of storyFolders(content, p => path.relative(root, p))) folders(path.join(d, 'shared', 'images'), s);
+  return index;
+}
+
+// The image the content already holds for a source or an original: the same source first, then the same bytes, by
+// the sha256 of file or the sha256 given. Returns the index entry with by: 'source' or 'sha256', or null.
+export function findImage(index, { source = null, file = null, sha256: hash = file ? sha256(file) : null } = {}) {
+  if (source) {
+    const want = sameSource(source), hit = index.find(i => i.source && sameSource(i.source) === want);
+    if (hit) return { ...hit, by: 'source' };
+  }
+  if (hash) {
+    // a folder without a sha256 hashes its original, which only happens before kitap rehash
+    const hit = index.find(i => (i.sha256 ?? (i.file ? sha256(i.file) : null)) === hash);
+    if (hit) return { ...hit, by: 'sha256' };
+  }
+  return null;
+}
+
+// The original behind a URL and its extension: the one the path ends in, else the one of the type the server sends.
+export async function downloadOriginal(url) {
+  let res;
+  try { res = await fetch(url); } catch (err) { throw new Error(`${url}: ${err.cause?.message ?? err.message}`); }
+  if (!res.ok) throw new Error(`${url}: HTTP ${res.status}`);
+  if (Number(res.headers.get('content-length')) > MAX_BYTES) throw new Error(`${url}: an original is at most ${MAX_BYTES / 1e6} MB, add a smaller copy`);
+  const bytes = Buffer.from(await res.arrayBuffer()), named = path.extname(decodeURIComponent(new URL(url).pathname)).toLowerCase();
+  const type = (res.headers.get('content-type') ?? '').split(';')[0].trim();
+  const ext = FORMAT[named] ? named : Object.keys(TYPES).find(e => e !== '.jpeg' && TYPES[e] === type);
+  if (!ext) throw new Error(`${url}: an image is a .jpg, .jpeg, .png, .webp, .svg or .gif file, and this one is ${type || 'of no known type'}`);
+  return { bytes, ext };
+}
+
+// kitap image: the folder that holds the same source or bytes, moved to content/shared/images/ when another story owns
+// it, else a new one named <name>-<six random hex digits>, so branches adding images at once never clash. file is a
+// path or a URL to download the original from. Returns the id.
+export async function image({ root = process.cwd(), file, name, caption, credit = null, source = null, story = null, log = console.log } = {}) {
+  if (!file || !name || !caption) throw new Error('usage: kitap image <file or url> <name> --caption <text> [--credit <text>] [--source <url>] [--story <id>]');
+  if (!/^[a-z0-9][a-z0-9-]*$/.test(name)) throw new Error(`"${name}": a name is lowercase letters, digits and dashes, such as hastings-knights`);
+  const url = /^https?:\/\//i.test(file) ? file : null;
+  if (!url && !fs.existsSync(file)) throw new Error(`${file}: no such file`);
+  if (!url && !FORMAT[path.extname(file).toLowerCase()]) throw new Error(`${file}: an image is a .jpg, .jpeg, .png, .webp, .svg or .gif file`);
+  const stories = storyFolders(path.join(root, 'content'), p => path.relative(root, p));
+  if (!stories.size) throw new Error('content/: no story.yaml found, run kitap image from a content project');
+  if (story && !stories.has(story)) throw new Error(`"${story}" is not a story folder under content/`);
+  // the fields as image.yaml will hold them, checked before anything is fetched or written
+  const fields = { caption, ...(credit ? { credit } : {}), ...(source ? { source } : {}), ...(url ? { url } : {}) };
+  check(ImageFolder.partial({ file: true, sha256: true }), fields, '--caption, --credit and --source');
+  const { bytes, ext } = url ? await downloadOriginal(url) : { bytes: fs.readFileSync(file), ext: path.extname(file).toLowerCase() };
+  await checkOriginal(bytes, ext, file);
+  const hash = sha256Of(bytes), rel = p => path.relative(root, p), common = path.join(root, 'content', 'shared', 'images');
+  const index = imageIndex({ root }), hit = findImage(index, { source, sha256: hash });
+  if (hit) {
+    let dir = hit.dir;
+    // a folder of another story moves where both stories see it, and every reference to it keeps working
+    if (hit.story && hit.story !== story) {
+      dir = path.join(common, hit.id);
+      if (fs.existsSync(dir) || index.some(i => i.id === hit.id && i.dir !== hit.dir)) throw new Error(`${rel(hit.dir)} holds this image and another folder is named ${hit.id} too, keep one`);
+      fs.mkdirSync(common, { recursive: true });
+      fs.renameSync(hit.dir, dir);
+      log(`moved ${rel(hit.dir)}/ to ${rel(dir)}/, it holds the same ${hit.by === 'source' ? 'source' : 'file'}`);
+    } else log(`${rel(dir)}/ holds the same ${hit.by === 'source' ? 'source' : 'file'}`);
+    if (source && !hit.source) setField(dir, 'source', source);
+    log(`name it as ${hit.id}`);
+    return hit.id;
+  }
+  const base = story ? path.join(stories.get(story), 'shared', 'images') : common;
+  let id;
+  // a fresh suffix, unused in every library and group
+  do id = `${name}-${crypto.randomBytes(3).toString('hex')}`; while (index.some(i => i.id === id));
+  const dir = path.join(base, id), original = 'image' + ext;
+  fs.mkdirSync(dir, { recursive: true });
+  fs.writeFileSync(path.join(dir, original), bytes);
+  // the caption is in the story's default language, or for a shared image the site's
+  const settingsFile = story ? path.join(stories.get(story), 'story.yaml') : path.join(root, 'site.yaml');
+  const settings = fs.existsSync(settingsFile) ? yaml.load(fs.readFileSync(settingsFile, 'utf8')) ?? {} : {};
+  const lang = settings.default_language ?? settings.languages?.[0] ?? 'en';
+  fs.writeFileSync(path.join(dir, 'image.yaml'), yaml.dump({ ...fields, ...(lang !== 'en' ? { default_language: lang } : {}), file: original, sha256: hash }, { lineWidth: -1 }));
+  log(`wrote ${rel(dir)}/, name it as ${id}`);
+  return id;
+}
+
+// kitap rehash: writes the file and sha256 of every image folder whose original is on this machine into its
+// image.yaml, where they are missing or no longer match. A new sha256 drops url, which downloads the old bytes.
+// Returns the folders it wrote.
+export function rehash({ root = process.cwd(), log = console.log } = {}) {
+  const written = [];
+  for (const i of imageIndex({ root })) {
+    if (!i.meta) { log(`${path.relative(root, i.dir)}: image.yaml is missing`); continue; }
+    if (!i.file) continue;
+    const hash = sha256(i.file), name = path.basename(i.file);
+    if (i.sha256 === hash && i.name === name) continue;
+    if (i.name !== name) setField(i.dir, 'file', name, 'sha256');
+    if (i.sha256 !== hash) { setField(i.dir, 'sha256', hash); if (i.url) removeField(i.dir, 'url'); }
+    written.push(path.relative(root, i.dir));
+  }
+  log(`wrote the file and sha256 of ${written.length} image folder${written.length === 1 ? '' : 's'}`);
+  return written;
+}

package/src/index.html

@@ -0,0 +1,183 @@
+<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<!--__HEAD__-->
+<link rel="stylesheet" href="vendor/fonts.css">
+<style>
+:root{
+  --display:"Fraunces",Georgia,"Times New Roman",serif;
+  --body:"Public Sans","Helvetica Neue",Arial,sans-serif;
+}
+/*__THEMES_CSS__*/
+html{font-size:clamp(14px, 0.4545vw + 7.2px, 19px)}
+*{box-sizing:border-box}
+[hidden]{display:none!important}
+body{margin:0;background:var(--paper);color:var(--ink);font-family:var(--body);font-size:1.07rem;line-height:1.5;padding-inline:1.143rem;padding-block:.857rem}
+.wrap{max-width:68rem;margin:0 auto;display:flex;flex-direction:column;gap:2rem}
+h1,h2{font-family:var(--display);font-weight:500;margin:0;text-wrap:balance}
+header{display:flex;align-items:center;gap:1.143rem;flex-wrap:wrap;border-bottom:1px solid var(--rule);padding-bottom:.714rem}
+header h1{font-size:1.857rem}
+header .controls{margin-inline-start:auto;display:flex;gap:.571rem}
+header a.contribute{color:var(--ink-2);font-size:.929rem;text-decoration:none;border:1px solid var(--rule);border-radius:4px;padding:.357rem .714rem;display:inline-flex;align-items:center}
+header a.contribute:hover{color:var(--ink)}
+header a.contribute:focus-visible{outline:2px solid var(--accent)}
+header .prefs{position:relative}
+#settings-btn{background:var(--panel);color:var(--ink);border:1px solid var(--rule);border-radius:4px;padding:.357rem .714rem;font:inherit;font-size:.929rem;cursor:pointer;display:inline-flex;align-items:center;gap:.357rem}
+#settings-btn svg{width:1rem;height:1rem}
+#settings-btn:focus-visible{outline:2px solid var(--accent)}
+/* the language beside the settings, as on a story page */
+.langpick{display:inline-flex;align-items:center;gap:.143rem;background:var(--panel);color:var(--ink);border:1px solid var(--rule);border-radius:4px;padding-inline-start:.714rem;font-size:.929rem}
+.langpick svg{width:1rem;height:1rem;flex:none}
+.langpick select{background:var(--panel);color:inherit;border:0;border-radius:4px;font:inherit;padding:.357rem .571rem;cursor:pointer}
+.langpick:focus-within{outline:2px solid var(--accent)}
+.langpick select:focus{outline:none}
+/* settings: the same panel as on a story page, the layout and the theme, under its button */
+.settings{position:absolute;top:calc(100% + .429rem);inset-inline-end:0;z-index:8;width:min(24rem,calc(100vw - 2.286rem));display:grid;gap:.857rem;
+  background:var(--panel);border:1px solid var(--rule);border-radius:6px;padding:.857rem;box-shadow:0 4px 16px rgba(0,0,0,.25)}
+.settings .group{display:grid;gap:.357rem}
+.settings .group > span{font-size:.786rem;letter-spacing:.06em;text-transform:uppercase;color:var(--ink-2)}
+.layouts{display:grid;grid-template-columns:repeat(3,minmax(0,1fr));gap:.429rem}
+.layouts button{display:grid;justify-items:center;align-content:start;gap:.286rem;padding:.429rem;font:inherit;font-size:.786rem;line-height:1.25;text-align:center;
+  background:var(--paper);color:var(--ink);border:1px solid var(--rule);border-radius:6px;cursor:pointer}
+.layouts button svg{width:100%;height:auto;max-width:4.6rem}
+.layouts button[aria-checked="true"]{border-color:var(--accent);box-shadow:inset 0 0 0 1px var(--accent)}
+.layouts button:focus-visible{outline:2px solid var(--accent)}
+@media (max-width:900px){ .settings .layout-group{display:none} } /* a phone has one layout */
+select#theme{width:100%;min-height:max(40px,2.857rem);background:var(--paper);color:var(--ink);border:1px solid var(--rule);border-radius:4px;padding:0 .571rem;font:inherit;cursor:pointer}
+select#theme:focus-visible{outline:2px solid var(--accent)}
+.intro{max-width:62ch;color:var(--ink-2);margin:0}
+.listbar{display:flex;justify-content:space-between;align-items:center;gap:.857rem;flex-wrap:wrap}
+.listbar input{flex:1;max-width:24rem;min-height:max(40px,2.857rem);background:var(--panel);color:var(--ink);border:1px solid var(--rule);border-radius:6px;padding:0 .857rem;font:inherit}
+.listbar input::placeholder{color:var(--ink-2)}
+.listbar input:focus-visible{outline:2px solid var(--accent);outline-offset:-1px}
+.rows .empty{padding:1.143rem .571rem;color:var(--ink-2)}
+.listbar button,.toggle-all{background:none;border:1px solid var(--rule);border-radius:4px;color:var(--ink-2);font:inherit;font-size:.857rem;padding:.286rem .714rem;cursor:pointer}
+.listbar button:hover,.toggle-all:hover{color:var(--ink)}
+.listbar button:focus-visible,.toggle-all:focus-visible{outline:2px solid var(--accent)}
+.rows{list-style:none;margin:0;padding:0;border-top:1px solid var(--rule)}
+.row{border-bottom:1px solid var(--rule)}
+.row > button{display:grid;grid-template-columns:auto auto minmax(0,1fr);gap:.286rem 1.143rem;align-items:baseline;width:100%;text-align:start;background:none;border:0;
+  color:var(--ink);font:inherit;padding:1rem .571rem;cursor:pointer}
+.row > button:hover{background:var(--panel)}
+.row > button:focus-visible{outline:2px solid var(--accent);outline-offset:-2px}
+.row .span{grid-column:2;grid-row:1;font-size:.857rem;letter-spacing:.06em;text-transform:uppercase;color:var(--accent);font-variant-numeric:tabular-nums}
+.row h2{grid-column:3;grid-row:1;font-size:1.429rem;line-height:1.2}
+.row .brief{grid-column:2/4;grid-row:2;color:var(--ink-2);font-size:1rem;white-space:nowrap;overflow:hidden;text-overflow:ellipsis;min-width:0}
+.row .chev{grid-column:1;grid-row:1/3;align-self:center;width:0;height:0;border:5px solid transparent;border-inline-start:6px solid var(--ink-2);transition:transform .15s}
+.row > button[aria-expanded="true"] .chev{transform:rotate(90deg)}
+:root[dir="rtl"] .row > button[aria-expanded="true"] .chev{transform:rotate(-90deg)}
+.row > button[aria-expanded="true"] .brief{visibility:hidden}
+.row .detail{display:grid;grid-template-columns:minmax(0,1fr) 300px;gap:1.429rem;padding:0 .571rem 1.286rem}
+.row .detail p{margin:0;max-width:62ch}
+.row .detail .meta{display:flex;gap:.857rem;font-size:.857rem;color:var(--ink-2);margin-top:.857rem}
+.row .detail .open{display:inline-block;margin-top:1rem;background:var(--ink);color:var(--paper);text-decoration:none;padding:.5rem 1rem;border-radius:4px;font-size:1rem}
+.row .detail .open:focus-visible{outline:2px solid var(--accent);outline-offset:2px}
+.row .cover{aspect-ratio:16/10;background:var(--paper-2);border:1px solid var(--rule);display:grid;place-items:center;overflow:hidden}
+.row .cover img{width:100%;height:100%;object-fit:cover;display:block}
+.credit{font-size:.857rem;color:var(--ink-2);border-top:1px solid var(--rule);padding-top:.714rem}
+.credit a{color:inherit}
+.row .cover span{font-family:var(--display);font-size:1.571rem;color:var(--ink-2);padding:.857rem;text-align:center}
+@media (max-width:640px){
+  .row > button{grid-template-columns:auto minmax(0,1fr)}
+  .row .span{grid-column:2;grid-row:1}
+  .row h2{grid-column:2;grid-row:2}
+  .row .brief{grid-column:2;grid-row:3}
+  .row .chev{grid-column:1;grid-row:1/4}
+  .row .detail{grid-template-columns:1fr}
+}
+</style>
+</head>
+<body>
+<div class="wrap">
+  <header>
+    <h1 id="title"></h1>
+    <div class="controls"><a class="contribute" id="contribute" target="_blank" rel="noopener" hidden></a>
+      <label class="langpick" id="langpick"><span id="lang-icon" aria-hidden="true"></span><select id="lang"></select></label>
+      <div class="prefs">
+        <button type="button" id="settings-btn" aria-expanded="false" aria-controls="settings"></button>
+        <div class="settings" id="settings" hidden>
+          <div class="group layout-group"><span id="layout-label"></span><div class="layouts" id="layouts" role="radiogroup"></div></div>
+          <label class="group"><span id="theme-label"></span><select id="theme"></select></label>
+        </div>
+      </div>
+    </div>
+  </header>
+  <p class="intro" id="intro"></p>
+  <div class="listbar"><input type="search" id="search" autocomplete="off" spellcheck="false"><button type="button" id="toggle-all"></button></div>
+  <ul class="rows" id="rows"></ul>
+  <footer class="credit" id="credit"></footer>
+</div>
+<script>
+/*__COMMON__*/
+const SITE = null;
+const S = SITE;
+// the language the URL names, else the reader's
+let lang = ROUTE?.lang ?? preferredLang(S.languages, S.defaultLanguage);
+// a story opens in the main page's language when it has it, else in its own default
+const storyLang = s => s.languages.includes(lang) ? lang : s.defaultLanguage;
+let palette = pref('palette', S.themes.map(t => t.id), S.defaultTheme);
+document.documentElement.dataset.palette = palette;
+const L = field => pick(field, lang, S.defaultLanguage);
+const open = new Set();
+// search: a case insensitive substring of the title in the current language, folded by that language's rules
+let query = '';
+const visible = () => { const q = query.trim().toLocaleLowerCase(lang); return q ? S.stories.filter(s => L(s.title).toLocaleLowerCase(lang).includes(q)) : S.stories; };
+const allOpen = () => visible().every(s => open.has(s.id));
+function render(){
+  document.documentElement.lang = lang; document.documentElement.dir = S.ui[lang].dir;
+  document.title = L(S.title);
+  $('title').textContent = L(S.title);
+  $('intro').textContent = L(S.intro);
+  if (S.repository) { $('contribute').href = S.repository; $('contribute').textContent = S.ui[lang].contribute; $('contribute').hidden = false; }
+  fillSelect($('lang'), S.languages.map(l => ({ value: l, text: S.ui[l].name ?? l })), lang, S.ui[lang].language);
+  $('lang-icon').innerHTML = S.icons.languages; $('langpick').title = S.ui[lang].language; $('langpick').hidden = S.languages.length < 2;
+  fillSelect($('theme'), S.themes.map(t => ({ value: t.id, text: pick(t.name, lang, S.defaultLanguage, t.id) })), palette, S.ui[lang].theme);
+  $('settings-btn').innerHTML = `${S.icons.settings} ${esc(S.ui[lang].settings)}`;
+  $('settings').setAttribute('aria-label', S.ui[lang].settings);
+  $('theme-label').textContent = S.ui[lang].theme;
+  $('layout-label').textContent = S.ui[lang].layout; $('layouts').setAttribute('aria-label', S.ui[lang].layout);
+  $('layouts').innerHTML = layoutButtons(S.ui[lang], pref('layout', LAYOUTS, 'center'));
+  $('search').placeholder = S.ui[lang].search_stories; $('search').setAttribute('aria-label', S.ui[lang].search_stories);
+  $('toggle-all').textContent = toggleLabel(S.ui[lang], allOpen());
+  $('credit').innerHTML = credit(S.ui[lang]);
+  const shown = visible();
+  $('toggle-all').hidden = !shown.length;
+  if (!shown.length) { $('rows').innerHTML = `<li class="empty">${esc(S.ui[lang].no_match.replace('{q}', query.trim()))}</li>`; return; }
+  $('rows').innerHTML = shown.map((s, i) => `
+    <li class="row">
+      <button type="button" aria-expanded="${open.has(s.id)}" aria-controls="d-${i}" data-id="${esc(s.id)}">
+        <span class="span">${esc(L(s.span))}</span><h2>${esc(L(s.title))}</h2><span class="chev"></span>
+        <span class="brief">${esc(L(s.summary))}</span>
+      </button>
+      <div class="detail" id="d-${i}" ${open.has(s.id) ? '' : 'hidden'}>
+        <div>
+          <p>${esc(L(s.summary))}</p>
+          <div class="meta"><span>${s.pages} ${esc(S.ui[lang].pages)}</span><span>${esc(s.languages.map(l => S.ui[l]?.name ?? l).join(', '))}</span></div>
+          <a class="open" href="${storyLink(s.id, storyLang(s))}">${esc(S.ui[lang].open)}</a>
+        </div>
+        <div class="cover">${s.cover ? `<img src="${esc(s.cover)}" alt="">` : `<span>${esc(L(s.title))}</span>`}</div>
+      </div>
+    </li>`).join('');
+}
+$('rows').addEventListener('click', e => {
+  const b = e.target.closest('button[data-id]'); if (!b) return;
+  const id = b.dataset.id; open.has(id) ? open.delete(id) : open.add(id);
+  b.setAttribute('aria-expanded', open.has(id)); $(b.getAttribute('aria-controls')).hidden = !open.has(id);
+  $('toggle-all').textContent = toggleLabel(S.ui[lang], allOpen());
+});
+$('toggle-all').onclick = () => { const all = allOpen(); visible().forEach(s => all ? open.delete(s.id) : open.add(s.id)); render(); };
+$('search').oninput = e => { query = e.target.value; render(); };
+$('search').onkeydown = e => { if (e.key === 'Escape' && query) { e.target.value = query = ''; render(); } };
+$('theme').onchange = e => { palette = e.target.value; applyPalette(palette); };
+const showSettings = open => { $('settings').hidden = !open; $('settings-btn').setAttribute('aria-expanded', open); };
+$('settings-btn').onclick = () => showSettings($('settings').hidden);
+$('layouts').onclick = e => { const b = e.target.closest('button[data-layout]'); if (b) saveLayout(b.dataset.layout); };
+document.addEventListener('click', e => { if (!$('settings').hidden && !e.target.closest('.prefs')) showSettings(false); });
+document.addEventListener('keydown', e => { if (e.key === 'Escape') showSettings(false); });
+$('lang').onchange = e => { lang = e.target.value; savePref('lang', lang); setRoute([lang], false); render(); };
+render(); setRoute([lang], false);
+</script>
+</body>
+</html>

package/src/index.mjs

@@ -0,0 +1,15 @@
+// The package entry. The same commands the CLI offers, as functions, plus the content schemas and what an engine's
+// own commands read.
+export { build, buildPages, checkStory as check, readStory, storyAssets, uiCatalogue } from './build.mjs';
+export { dev } from './dev.mjs';
+export { i18n } from './translate.mjs';
+export { image, imageIndex, findImage, rehash } from './image.mjs';
+export { upload } from './upload.mjs';
+export { deploy } from './deploy.mjs';
+export { resolve } from './routes.mjs';
+export { loadEngine } from './engine.mjs';
+export { translator, loadCatalogues, flatten, unflatten, catalogueText } from './i18n.mjs';
+export { libraryItems, storyFolders } from './folders.mjs';
+export { esc, PLACE, describe } from './pages.mjs';
+export { hash, idOf, listDirs } from './util.mjs';
+export * as schema from './schema.mjs';