@openbooknetwork/kitap 0.0.0-stage → 0.1.0

package/src/pages.mjs

@@ -0,0 +1,271 @@
+// The static HTML of every page in every language, with the head tags search engines and link previews read, and
+// the files crawlers ask for: sitemaps, robots.txt, llms.txt and each story as Markdown.
+// Paths are relative to the folder a page's <base> names. URLs are absolute and come from site.yaml's url.
+
+export const esc = s => String(s ?? '').replace(/[&<>"']/g, c => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c]));
+// JSON inside a <script> element, with < escaped so a "</script>" in the content stays text
+const scriptJson = v => JSON.stringify(v).replace(/</g, '\\u003c');
+const pick = (field, lang, fallback) => field?.[lang] ?? field?.[fallback] ?? '';
+// A line that opens with a number and a full stop is text, as Turkish ordinals are ("21. yüzyılda"), not a list item.
+export const ordinals = md => md.replace(/^(\d+)\. /gm, '$1\\. ');
+// a place the text names, linked to the page's marker by its id: [Gelibolu’ya](@gallipoli)
+export const PLACE = /\[([^\]]+)\]\(@([^)\s]+)\)/g;
+
+// a marker the template must hold. The function form keeps a "$&" in the value literal.
+function fill(html, marker, value) {
+  if (!html.includes(marker)) throw new Error(`template has no ${marker}`);
+  return html.replace(marker, () => value);
+}
+
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ' };
+const plain = html => html.replace(/<[^>]+>/g, '')
+  .replace(/&(#x[0-9a-f]+|#\d+|\w+);/gi, (m, e) => e[0] !== '#' ? ENTITIES[e] ?? m : String.fromCodePoint(e[1].toLowerCase() === 'x' ? parseInt(e.slice(2), 16) : Number(e.slice(1))))
+  .replace(/\s+/g, ' ').trim();
+const firstParagraph = html => plain(html.match(/<p>([\s\S]*?)<\/p>/)?.[1] ?? '');
+
+// A search snippet: the text up to its last sentence end before max characters, else cut at a space with an
+// ellipsis. A sentence end in the first 60 characters is passed over, since it is often an abbreviation such as "c.".
+export function describe(text, max = 160) {
+  if (text.length <= max) return text;
+  const ends = [...text.slice(0, max).matchAll(/[.!?…](?=\s)/g)].map(m => m.index + 1).filter(i => i >= 60);
+  if (ends.length) return text.slice(0, ends.at(-1));
+  const cut = text.lastIndexOf(' ', max - 2);
+  return text.slice(0, cut > 0 ? cut : max - 2).replace(/[\s,;:]+$/, '') + '…';
+}
+
+// og:locale wants language_TERRITORY, and ICU supplies the likely territory: tr gives tr_TR
+const ogLocale = l => { const m = new Intl.Locale(l).maximize(); return m.region ? `${m.language}_${m.region}` : m.language; };
+
+// the <head> tags after the viewport: <base>, title and description always, the rest when the site has a URL
+function head({ base, title, description, lang, site, canonical, alternates = [], type = 'website', image = null, jsonld = null }) {
+  const tags = [`<base href="${base}">`, `<title>${esc(title)}</title>`];
+  if (description) tags.push(`<meta name="description" content="${esc(description)}">`);
+  if (!site.url) return tags.join('\n');
+  tags.push(`<link rel="canonical" href="${esc(canonical)}">`);
+  for (const a of alternates) tags.push(`<link rel="alternate" hreflang="${a.hreflang}" href="${esc(a.href)}">`);
+  const og = { 'og:type': type, 'og:title': title, 'og:description': description, 'og:url': canonical, 'og:site_name': pick(site.title, lang, site.defaultLang), 'og:locale': ogLocale(lang) };
+  for (const [k, v] of Object.entries(og)) if (v) tags.push(`<meta property="${k}" content="${esc(v)}">`);
+  for (const a of alternates) if (a.hreflang !== lang && a.hreflang !== 'x-default') tags.push(`<meta property="og:locale:alternate" content="${ogLocale(a.hreflang)}">`);
+  if (image) tags.push(`<meta property="og:image" content="${esc(image)}">`);
+  tags.push(`<meta name="twitter:card" content="${image ? 'summary_large_image' : 'summary'}">`);
+  if (jsonld) tags.push(`<script type="application/ld+json">${scriptJson(jsonld)}</script>`);
+  return tags.join('\n');
+}
+
+// one link per language version, plus x-default for readers whose language the page lacks
+const alternatesFor = (site, langs, defaultLang, at) => site.url ? [...langs.map(l => ({ hreflang: l, href: site.abs(at(l)) })), { hreflang: 'x-default', href: site.abs(at(defaultLang)) }] : [];
+const urlset = entries => `<?xml version="1.0" encoding="UTF-8"?>
+<urlset xmlns="http://www.sitemaps.org/schemas/sitemap/0.9" xmlns:xhtml="http://www.w3.org/1999/xhtml">
+${entries.map(e => `<url><loc>${esc(e.loc)}</loc>${e.alternates.map(a => `<xhtml:link rel="alternate" hreflang="${a.hreflang}" href="${esc(a.href)}"/>`).join('')}</url>`).join('\n')}
+</urlset>
+`;
+
+// The site as the page builders use it: url ends in a slash, abs() turns a path from the site root into a URL.
+export function siteContext({ url, title, languages, defaultLanguage }) {
+  const base = url ? url.replace(/\/?$/, '/') : null;
+  // abs keeps an absolute URL, such as an image's in the asset store, as it is
+  return { url: base, title, langs: languages, defaultLang: defaultLanguage, abs: p => new URL(p, base).href, root: base ? new URL(base).pathname : '/' };
+}
+
+// Every file of one story folder: the bare and per language overviews, a page per step and language, the story as
+// Markdown per language, and with a site URL its sitemap. bundle is what story.js carries. texts and images are
+// per page id and language: the Markdown source, and the first image the text shows. links holds each image's
+// original and og:image links, absolute or from the site root, and coverImage is the id of the story's cover.
+export function storyFiles({ shell, bundle: B, texts, firstImages, links, coverImage = null, site: siteIn, engine = null, versions }) {
+  const site = { ...siteIn, title: B.site.title }, files = {}, id = B.id, langs = B.languages, def = B.defaultLanguage, pages = B.pages;
+  const homeLang = l => site.langs.includes(l) ? l : site.defaultLang;
+  // the Markdown file sits in the story folder, so a link from the site root goes one folder up
+  const imageUrl = imgId => site.url ? site.abs(links[imgId].original) : /^https?:/.test(links[imgId].original) ? links[imgId].original : `../${links[imgId].original}`;
+  const ogImage = imgId => site.url ? site.abs(links[imgId].og) : null;
+  const cover = coverImage ? ogImage(coverImage) : null;
+  const overviewAt = l => `${id}/${l}/`, stepAt = (l, pid) => `${id}/${l}/${pid}/`;
+
+  const nav = (lang, cur) => {
+    const L = f => pick(f, lang, def);
+    const walk = (nodes, depth) => nodes.map(n => n.type === 'page'
+      ? `<a class="pg" href="${lang}/${pages[n.index].id}/" style="--depth:${depth}"${n.index === cur ? ' aria-current="page"' : ''}><span class="d">${esc(L(pages[n.index].date))}</span>${esc(L(pages[n.index].title))}</a>`
+      : `<details open><summary style="--depth:${depth}">${esc(L(n.title))}</summary>${walk(n.children, depth + 1)}</details>`).join('');
+    return walk(B.tree, 0);
+  };
+  const page = ({ lang, base, route, headHtml, text, cur }) => {
+    const L = f => pick(f, lang, def);
+    let html = fill(shell, '<html lang="en">', `<html lang="${lang}" dir="${B.ui[lang].dir}">`);
+    html = fill(html, '<!--__HEAD__-->', headHtml);
+    html = fill(html, '<a class="back" id="back" href="../"></a>', `<a class="back" id="back" href="../${homeLang(lang)}/">${esc(L(B.site.title))}</a>`);
+    html = fill(html, '<h1 id="title"></h1>', `<h1 id="title">${esc(L(B.title))}</h1>`);
+    html = fill(html, '<nav class="pages" id="nav"></nav>', `<nav class="pages" id="nav">${nav(lang, cur)}</nav>`);
+    html = fill(html, '<div class="text" id="story"></div>', `<div class="text" id="story">${text}</div>`);
+    html = fill(html, 'const ROUTE = null;', `const ROUTE = ${scriptJson(route)};`);
+    html = fill(html, 'src="story.js"', `src="story.js?v=${versions.story}"`);
+    if (engine && html.includes(`src="../${engine}.js"`)) html = fill(html, `src="../${engine}.js"`, `src="../${engine}.js?v=${versions.engine}"`);
+    return fill(html, 'src="../kitap.js"', `src="../kitap.js?v=${versions.app}"`);
+  };
+
+  const overview = (lang, base, bare) => {
+    const L = f => pick(f, lang, def), T = B.ui[lang];
+    const canonical = site.url ? site.abs(overviewAt(lang)) : null;
+    const text = `<div class="date">${esc(L(B.span))}</div><h2>${esc(L(B.title))}</h2>${B.summary ? `<p>${esc(L(B.summary))}</p>` : ''}`
+      + `<p><a class="start" href="${lang}/${pages[0].id}/" data-page="0">${esc(T.start)}</a></p>`;
+    const headHtml = head({ base, title: L(B.title), description: describe(L(B.summary)), lang, site, canonical,
+      alternates: bare ? [] : alternatesFor(site, langs, def, overviewAt), image: cover });
+    return page({ lang, base, route: bare ? null : { lang, page: null }, headHtml, text, cur: -1 });
+  };
+  files['index.html'] = overview(def, './', true);
+  for (const lang of langs) files[`${lang}/index.html`] = overview(lang, '../', false);
+
+  pages.forEach((p, i) => {
+    for (const lang of langs) {
+      const L = f => pick(f, lang, def), T = B.ui[lang];
+      const description = describe(firstParagraph(p.html[lang]));
+      const canonical = site.url ? site.abs(stepAt(lang, p.id)) : null;
+      const image = firstImages[p.id]?.[lang] ? ogImage(firstImages[p.id][lang]) : cover;
+      const sources = p.sources[lang].length ? `<h3>${esc(T.sources)}</h3><ol>${p.sources[lang].map(x => `<li>${esc(x)}</li>`).join('')}</ol>` : '';
+      const step = (j, label) => pages[j] ? `<a href="${lang}/${pages[j].id}/" data-page="${j}">${esc(label)}: ${esc(L(pages[j].title))}</a>` : '<span></span>';
+      const text = `<div class="date">${esc(L(p.date))}</div><h2>${esc(L(p.title))}</h2>${p.html[lang]}${sources}<p class="steps">${step(i - 1, T.prev)}${step(i + 1, T.next)}</p>`;
+      const title = `${L(p.title)} - ${L(B.title)}`;
+      const jsonld = site.url && [
+        { '@context': 'https://schema.org', '@type': 'BreadcrumbList', itemListElement: [
+          [L(B.site.title), site.abs(`${homeLang(lang)}/`)], [L(B.title), site.abs(overviewAt(lang))], [L(p.title), canonical],
+        ].map(([name, item], k) => ({ '@type': 'ListItem', position: k + 1, name, item })) },
+        { '@context': 'https://schema.org', '@type': 'Article', headline: L(p.title), description, inLanguage: lang, url: canonical, mainEntityOfPage: canonical,
+          ...(image ? { image } : {}), isPartOf: { '@type': 'CreativeWork', name: L(B.title), url: site.abs(overviewAt(lang)) },
+          ...(p.sources[lang].length ? { citation: p.sources[lang] } : {}), publisher: { '@type': 'Organization', name: L(B.site.title), url: site.url } },
+      ];
+      const headHtml = head({ base: '../../', title, description, lang, site, canonical, alternates: alternatesFor(site, langs, def, l => stepAt(l, p.id)), type: 'article', image, jsonld });
+      files[`${lang}/${p.id}/index.html`] = page({ lang, base: '../../', route: { lang, page: p.id }, headHtml, text, cur: i });
+    }
+  });
+
+  for (const lang of langs) files[`${lang}.md`] = markdown(B, lang, texts, imageUrl);
+  if (site.url) files['sitemap.xml'] = urlset([
+    ...langs.map(l => ({ loc: site.abs(overviewAt(l)), alternates: alternatesFor(site, langs, def, overviewAt) })),
+    ...pages.flatMap(p => langs.map(l => ({ loc: site.abs(stepAt(l, p.id)), alternates: alternatesFor(site, langs, def, k => stepAt(k, p.id)) }))),
+  ]);
+  return files;
+}
+
+// The story as one Markdown file: title and summary, then the groups as headings and each step with its date,
+// text and sources. An @image line becomes a Markdown image.
+function markdown(B, lang, texts, imageUrl) {
+  const L = f => pick(f, lang, B.defaultLanguage), T = B.ui[lang], out = [`# ${L(B.title)}`, ''];
+  if (B.summary) out.push(L(B.summary), '');
+  const heading = depth => '#'.repeat(Math.min(depth + 2, 6));
+  const walk = (nodes, depth) => {
+    for (const n of nodes) {
+      if (n.type === 'group') { out.push(`${heading(depth)} ${L(n.title)}`, ''); walk(n.children, depth + 1); continue; }
+      const p = B.pages[n.index];
+      const text = ordinals(texts[p.id][lang]).replace(/^@image\s+(\S+)\s*$/gm, (_, imgId) => `![${L(B.images[imgId].caption).replace(/[[\]]/g, '\\$&')}](${imageUrl(imgId)})`)
+        .replace(PLACE, '$1');
+      out.push(`${heading(depth)} ${L(p.title)}`, '', `*${L(p.date)}*`, '', text.trim(), '');
+      if (p.sources[lang].length) out.push(`${T.sources}:`, '', ...p.sources[lang].map(s => `- ${s}`), '');
+    }
+  };
+  walk(B.tree, 0);
+  return out.join('\n');
+}
+
+// The main page per language and bare at the root, the 404 page, and with a site URL the crawl files. data is
+// what the main page script reads as SITE, cards the stories it lists. image is the og:image link of the first cover,
+// absolute or from the site root.
+export function siteFiles({ shell, data: S, image: imageIn = null, site: siteIn, common, themeCss, ui }) {
+  const site = { ...siteIn, title: S.title }, files = {}, langs = S.languages, def = S.defaultLanguage;
+  const storyLang = (s, l) => s.languages.includes(l) ? l : s.defaultLanguage;
+  const homeAt = l => `${l}/`;
+  const image = imageIn && site.url ? site.abs(imageIn) : null;
+
+  const main = (lang, base, bare) => {
+    const L = f => pick(f, lang, def), T = S.ui[lang];
+    const rows = S.stories.map((s, i) => `
+    <li class="row">
+      <button type="button" aria-expanded="false" 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}" hidden>
+        <div>
+          <p>${esc(L(s.summary))}</p>
+          <div class="meta"><span>${s.pages} ${esc(T.pages)}</span><span>${esc(s.languages.map(l => S.ui[l]?.name ?? l).join(', '))}</span></div>
+          <a class="open" href="${esc(s.id)}/${storyLang(s, lang)}/">${esc(T.open)}</a>
+        </div>
+        <div class="cover">${s.cover ? `<img src="${esc(s.cover)}" alt="">` : `<span>${esc(L(s.title))}</span>`}</div>
+      </div>
+    </li>`).join('');
+    let html = fill(shell, '<html lang="en">', `<html lang="${lang}" dir="${T.dir}">`);
+    html = fill(html, '<!--__HEAD__-->', head({ base, title: L(S.title), description: describe(L(S.intro)), lang, site,
+      canonical: site.url ? site.abs(homeAt(lang)) : null, alternates: bare ? [] : alternatesFor(site, langs, def, homeAt), image }));
+    html = fill(html, '<h1 id="title"></h1>', `<h1 id="title">${esc(L(S.title))}</h1>`);
+    html = fill(html, '<p class="intro" id="intro"></p>', `<p class="intro" id="intro">${esc(L(S.intro))}</p>`);
+    html = fill(html, '<ul class="rows" id="rows"></ul>', `<ul class="rows" id="rows">${rows}</ul>`);
+    return fill(html, 'const SITE = null;', `const ROUTE = ${scriptJson(bare ? null : { lang })};\nconst SITE = ${scriptJson(S)};`);
+  };
+  files['index.html'] = main(def, './', true);
+  for (const lang of langs) files[`${lang}/index.html`] = main(lang, '../', false);
+  files['404.html'] = notFound({ S, site, common, themeCss, ui });
+
+  if (site.url) {
+    files['sitemap-main.xml'] = urlset(langs.map(l => ({ loc: site.abs(homeAt(l)), alternates: alternatesFor(site, langs, def, homeAt) })));
+    files['sitemap.xml'] = `<?xml version="1.0" encoding="UTF-8"?>
+<sitemapindex xmlns="http://www.sitemaps.org/schemas/sitemap/0.9">
+${['sitemap-main.xml', ...S.stories.map(s => `${s.id}/sitemap.xml`)].map(f => `<sitemap><loc>${esc(site.abs(f))}</loc></sitemap>`).join('\n')}
+</sitemapindex>
+`;
+    files['robots.txt'] = `User-agent: *\nAllow: /\n\nSitemap: ${site.abs('sitemap.xml')}\n`;
+    const L = f => pick(f, def, def);
+    files['llms.txt'] = [`# ${L(S.title)}`, '', ...(S.intro?.[def] ? [`> ${L(S.intro)}`, ''] : []),
+      'Each story is one Markdown file per language: the title and summary, then every step with its date, text and sources.', '',
+      '## Stories', '',
+      ...S.stories.map(s => {
+        const sl = storyLang(s, def), others = s.languages.filter(l => l !== sl);
+        const also = others.length ? ` Also in ${others.map(l => `[${S.ui[l]?.name ?? l}](${site.abs(`${s.id}/${l}.md`)})`).join(', ')}.` : '';
+        return `- [${pick(s.title, sl, s.defaultLanguage)}](${site.abs(`${s.id}/${sl}.md`)}): ${pick(s.summary, sl, s.defaultLanguage)}${also}`;
+      }), ''].join('\n');
+  }
+  return files;
+}
+
+// GitHub Pages serves 404.html for any unknown path, at any depth, so its links start at the site root. The script
+// reads the story and language from the path and shows the message in that language.
+function notFound({ S, site, common, themeCss, ui }) {
+  const def = S.defaultLanguage;
+  const data = { root: site.root, languages: S.languages, defaultLanguage: def, title: S.title,
+    ui: Object.fromEntries(Object.entries(ui).map(([l, u]) => [l, { not_found: u.not_found, dir: u.dir }])),
+    stories: Object.fromEntries(S.stories.map(s => [s.id, { title: s.title, languages: s.languages, defaultLanguage: s.defaultLanguage }])) };
+  return `<!doctype html>
+<html lang="${def}" dir="${ui[def].dir}">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<meta name="robots" content="noindex">
+<title>${esc(ui[def].not_found)}</title>
+<link rel="stylesheet" href="${site.root}vendor/fonts.css">
+<style>
+${themeCss}
+body{margin:0;background:var(--paper);color:var(--ink);font-family:"Public Sans","Helvetica Neue",Arial,sans-serif;line-height:1.5}
+main{max-width:40rem;margin:0 auto;padding:4rem 1rem}
+h1{font-family:"Fraunces",Georgia,serif;font-size:2rem;margin:0 0 1rem}
+a{color:var(--accent)}
+li{margin-bottom:.5rem}
+</style>
+</head>
+<body>
+<main>
+<h1 id="msg">${esc(ui[def].not_found)}</h1>
+<ul id="links"><li><a href="${esc(site.root)}${def}/">${esc(pick(S.title, def, def))}</a></li></ul>
+</main>
+<script>
+${common}
+const D = ${scriptJson(data)};
+const path = decodeURIComponent(location.pathname), parts = path.slice(path.startsWith(D.root) ? D.root.length : 1).split('/').filter(Boolean);
+const story = D.stories[parts[0]], asked = story ? parts[1] : parts[0];
+const lang = (story ? story.languages : D.languages).includes(asked) ? asked : preferredLang(D.languages, D.defaultLanguage);
+const home = D.languages.includes(lang) ? lang : D.defaultLanguage;
+const L = field => pick(field, lang, D.defaultLanguage);
+document.documentElement.lang = lang; document.documentElement.dir = D.ui[lang].dir;
+document.title = $('msg').textContent = D.ui[lang].not_found;
+$('links').innerHTML = (story ? \`<li><a href="\${esc(D.root + parts[0])}/\${story.languages.includes(lang) ? lang : story.defaultLanguage}/">\${esc(L(story.title))}</a></li>\` : '')
+  + \`<li><a href="\${esc(D.root + home)}/">\${esc(L(D.title))}</a></li>\`;
+</script>
+</body>
+</html>
+`;
+}

package/src/routes.mjs

@@ -0,0 +1,23 @@
+// How the site answers a path, shared by harita dev and the Worker, so a page behaves the same on a laptop and on
+// the site. The module has no Node imports, so the Worker bundles it as it is.
+const TYPES = { '.html': 'text/html; charset=utf-8', '.js': 'text/javascript; charset=utf-8', '.css': 'text/css; charset=utf-8', '.md': 'text/markdown; charset=utf-8',
+  '.txt': 'text/plain; charset=utf-8', '.xml': 'application/xml', '.json': 'application/json', '.svg': 'image/svg+xml', '.png': 'image/png', '.jpg': 'image/jpeg',
+  '.jpeg': 'image/jpeg', '.webp': 'image/webp', '.gif': 'image/gif', '.ico': 'image/x-icon', '.woff2': 'font/woff2', '.pbf': 'application/x-protobuf' };
+export const typeOf = file => TYPES[file.slice(file.lastIndexOf('.')).toLowerCase()] ?? 'application/octet-stream';
+
+const NOT_FOUND = { key: '404.html', status: 404 };
+
+// The answer to a decoded path: { key, status } to serve, or { location } to redirect to with 301. A path ending in /
+// serves its index.html. A path without its slash whose folder has an index.html redirects to the path with the
+// slash, with query kept. A path redirect names redirects to its target. Any other path the site lacks gets 404.html.
+// exists tells whether the site holds a key and redirect gives a path's target or null, and either may be async.
+export async function resolve(path, exists, { redirect = () => null, query = '' } = {}) {
+  const parts = path.split('/');
+  if (parts[0] !== '' || parts.includes('..') || parts.includes('.')) return NOT_FOUND;
+  if (path.endsWith('/')) { const key = path.slice(1) + 'index.html'; return await exists(key) ? { key, status: 200 } : NOT_FOUND; }
+  const key = path.slice(1);
+  if (await exists(key)) return { key, status: 200 };
+  if (await exists(key + '/index.html')) return { location: path + '/' + query };
+  const target = await redirect(path);
+  return target ? { location: target } : NOT_FOUND;
+}

package/src/schema.mjs

@@ -0,0 +1,78 @@
+// Shapes of the book's content files. An engine adds its own fields to Story and Page under one key, its id, through
+// storySchema and pageSchema. Cross references between files are checked in build.mjs.
+import { z } from 'zod';
+export { z };
+
+// A plain string applies to every language; an object holds one string per language code.
+export const Translatable = z.union([z.string(), z.record(z.string().min(2).max(8), z.string())]);
+export const Id = z.string().regex(/^[a-z0-9][a-z0-9-]*$/, 'lowercase letters, digits and dashes only');
+export const Lang = z.string().regex(/^[a-z]{2}(-[A-Za-z]{2,4})?$/, 'a language code like en or pt-BR');
+export const Hex = z.string().regex(/^#[0-9a-fA-F]{6}$/, 'a hex colour like #a06b1f');
+// a year, a year-month, or a full date; YAML hands over a Date for the full form
+export const When = z.union([z.number().int(), z.string(), z.date()]).transform(v => v instanceof Date ? v.toISOString().slice(0, 10) : String(v))
+  .refine(s => /^\d{4}(-\d{2})?(-\d{2})?$/.test(s), 'YYYY, YYYY-MM or YYYY-MM-DD');
+
+// land: up to eight tints an engine may use for areas, neighbours get different ones; without it every area is paper2
+const ThemeTokens = z.object({ paper: Hex, paper2: Hex, sea: Hex, ink: Hex, ink2: Hex, rule: Hex, accent: Hex, panel: Hex, route: Hex, border: Hex, land: z.array(Hex).min(2).max(8).optional() }).strict();
+export const Theme = z.object({ name: Translatable.optional(), light: ThemeTokens, dark: ThemeTokens }).strict();
+export const Themes = z.record(Id, Theme);
+
+export const Site = z.object({
+  title: Translatable.optional(),
+  intro: Translatable.optional(),
+  languages: z.array(Lang).min(1).optional(),
+  default_language: Lang.optional(),
+  stories: z.array(Id).optional(),
+  engine: Id.optional(), // the engine that draws the stories' pictures, resolved from the project's packages or plugins/engines/
+  theme: Id.optional(),
+  themes: Themes.optional(),
+  url: z.string().url().optional(), // where the site is published, for canonical links, sitemaps and llms.txt
+  repository: z.string().url().optional(), // the content repository: a Contribute link on the main page, a source link per story
+  branch: z.string().default('main'),
+  // the object store that holds the images and the engine's objects: url serves them, bucket and endpoint take uploads
+  assets: z.object({ url: z.string().url().refine(u => u.endsWith('/'), 'ends in /'), bucket: z.string().min(1), endpoint: z.string().url() }).strict().optional(),
+  pages: z.object({ bucket: z.string().min(1) }).strict().optional(), // the bucket kitap deploy writes dist/ to, in the account of assets.endpoint
+}).strict();
+
+// The book's fields of story.yaml. storySchema(engine) adds the engine's under its id.
+export const StoryCore = {
+  id: Id,
+  title: Translatable,
+  summary: Translatable.optional(),
+  span: Translatable.optional(),
+  cover: z.string().regex(/^[a-z0-9][a-z0-9-]*$/, 'the id of an image folder the story can show, kitap image <file> <name> --story <story> makes one').optional(), // the card on the main page
+  languages: z.array(Lang).min(1),
+  default_language: Lang.optional(),
+  theme: Id.optional(),
+};
+export const storySchema = engine => z.object({ ...StoryCore, ...(engine ? { [engine.id]: (engine.schemas?.story ?? z.object({}).passthrough()).default({}) } : {}) }).strict();
+
+export const Group = z.object({ title: Translatable.optional() }).strict();
+
+// image.yaml in an image folder, content/shared/images/<id>/ or content/<story>/shared/images/<id>/. source: the page
+// the original came from, such as its Commons file page. url: where the original downloads from. file and sha256: the
+// original's name in the folder and its hash, which name its objects in the asset store.
+export const ImageFolder = z.object({ caption: Translatable, credit: Translatable.optional(), default_language: Lang.default('en'),
+  source: z.string().url().optional(), url: z.string().url().optional(),
+  file: z.string().regex(/^image\.(jpe?g|png|webp|svg|gif)$/, 'image.<ext>, the original in this folder, kitap rehash writes it'),
+  sha256: z.string().regex(/^[0-9a-f]{64}$/, '64 hex digits, kitap rehash writes it') }).strict();
+
+// The book's fields of page.yaml. pageSchema(engine) adds the engine's under its id.
+export const PageCore = {
+  title: Translatable,
+  date: Translatable.optional(), // shown above the title and in the contents, when the subject has dates
+  when: z.union([When, z.object({ from: When, to: When.optional() }).strict()]).optional(),
+  sources: z.array(Translatable).default([]),
+  // a card beside the text drawn by plugins/cards/<kind>.mjs, with its parameters
+  card: z.object({ kind: Id }).passthrough().optional(),
+  images: z.unknown().optional().refine(v => v === undefined, 'images live in image folders, content/<story>/shared/images/<name>-<six hex digits>/, and kitap image <file> <name> makes one'),
+};
+export const pageSchema = engine => z.object({ ...PageCore, ...(engine ? { [engine.id]: (engine.schemas?.page ?? z.object({}).passthrough()).default({}) } : {}) }).strict();
+
+// Parse or throw one error that names the file and every bad field.
+export function check(schema, data, file) {
+  const r = schema.safeParse(data);
+  if (r.success) return r.data;
+  const lines = r.error.issues.map(i => `  ${i.path.length ? i.path.join('.') : '(root)'}: ${i.message}`);
+  throw new Error(`${file}:\n${lines.join('\n')}`);
+}

package/src/store.mjs

@@ -0,0 +1,153 @@
+// The asset store: an S3 bucket that holds the images and the engine's objects under keys the build computes, and per
+// story a hash tree of the keys it needs. Reads go through the store's public URL, uploads through its S3 endpoint.
+import crypto from 'crypto';
+import { AwsClient } from 'aws4fetch';
+
+export const TREE_FORMAT = 1;
+const IMMUTABLE = 'public, max-age=31536000, immutable';
+const hashLines = lines => crypto.createHash('sha256').update(lines.join('\n')).digest('hex');
+
+// A story's hash tree: a directory per image folder with its keys, and a directory per group of the engine's objects
+// with its keys. A directory's hash is the sha256 of its sorted keys, and the root's the sha256 of its sorted
+// "<hash> <directory>" lines. images are { dir, keys } with dir the folder's path in the project, groups is
+// { directory: [keys] }.
+export function storyTree(story, images, groups = {}) {
+  const keysOf = {};
+  for (const { dir, keys } of images) keysOf[dir] = Object.values(keys);
+  for (const [d, keys] of Object.entries(groups)) (keysOf[d] ??= []).push(...keys);
+  const dirs = {};
+  for (const d of Object.keys(keysOf).sort()) { const keys = [...new Set(keysOf[d])].sort(); dirs[d] = { hash: hashLines(keys), keys }; }
+  return { format: TREE_FORMAT, story, root: hashLines(Object.entries(dirs).map(([d, x]) => `${x.hash} ${d}`).sort()), dirs };
+}
+
+// Runs fn over the items, n at a time, and returns its results in order.
+export async function pool(items, n, fn) {
+  const out = new Array(items.length);
+  let next = 0;
+  const worker = async () => { while (next < items.length) { const i = next++; out[i] = await fn(items[i], i); } };
+  await Promise.all(Array.from({ length: Math.min(n, items.length) }, worker));
+  return out;
+}
+
+// A request tried again five times on a network error or a 5xx or 429 answer, waiting twice as long each time, half
+// a minute in all. Returns the last answer, or throws with the status or the error code, such as ETIMEDOUT.
+export async function retry(what, request, { wait = 1000 } = {}) {
+  for (let attempt = 0; ; attempt++) {
+    let res = null, error = null;
+    try { res = await request(); } catch (err) { error = err; }
+    if (res && res.status < 500 && res.status !== 429) return res;
+    if (attempt === 5) throw new Error(`${what}: ${res ? `HTTP ${res.status}` : [error.cause?.code, error.cause?.message || error.message].filter(Boolean).join(' ')}`);
+    await new Promise(r => setTimeout(r, wait * 2 ** attempt));
+  }
+}
+
+// Reads objects through the store's public URL, which needs no credentials. count tells the requests made.
+export function storeReader(url, opts = {}) {
+  const r = {
+    count: 0,
+    // whether the store holds the key: a GET of its first byte, since the store closes the connection after a HEAD
+    async has(key) {
+      r.count++;
+      const res = await retry(url + key, () => fetch(url + key, { headers: { Range: 'bytes=0-0' } }), opts);
+      await res.arrayBuffer();
+      if (res.status === 404 || res.status === 403) return false;
+      if (!res.ok) throw new Error(`${url + key}: HTTP ${res.status}`);
+      return true;
+    },
+    async get(key) {
+      r.count++;
+      const res = await retry(url + key, () => fetch(url + key, { cache: 'no-store' }), opts);
+      if (res.status === 404 || res.status === 403) return null;
+      if (!res.ok) throw new Error(`${url + key}: HTTP ${res.status}`);
+      return Buffer.from(await res.arrayBuffer());
+    },
+    async json(key) { const b = await r.get(key); return b && JSON.parse(b.toString('utf8')); },
+  };
+  return r;
+}
+
+const unescapeXml = s => s.replace(/&(amp|lt|gt|quot|apos|#(\d+));/g, (_, e, n) => n ? String.fromCodePoint(n) : { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'" }[e]);
+
+// Writes, lists and deletes objects through the S3 endpoint with the credentials of AWS_ACCESS_KEY_ID and
+// AWS_SECRET_ACCESS_KEY. command names the command in the error for missing credentials.
+export function storeWriter({ endpoint, bucket }, { command = 'kitap upload', ...opts } = {}) {
+  const { AWS_ACCESS_KEY_ID: accessKeyId, AWS_SECRET_ACCESS_KEY: secretAccessKey } = process.env;
+  if (!accessKeyId || !secretAccessKey) throw new Error(`${command} writes with the S3 credentials of an API token for the bucket: set AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY`);
+  const aws = new AwsClient({ accessKeyId, secretAccessKey, service: 's3', region: 'auto', retries: 0 });
+  const base = `${endpoint.replace(/\/$/, '')}/${bucket}/`;
+  return {
+    // the store checks the bytes against Content-MD5 and refuses a copy damaged on the way
+    async put(key, body, type, cacheControl = IMMUTABLE) {
+      const headers = { 'Content-Type': type, 'Cache-Control': cacheControl, 'Content-MD5': crypto.createHash('md5').update(body).digest('base64') };
+      const res = await retry(`PUT ${key}`, async () => fetch(await aws.sign(base + key, { method: 'PUT', body, headers })), opts);
+      if (!res.ok) throw new Error(`PUT ${key}: HTTP ${res.status} ${(await res.text()).slice(0, 300)}`);
+    },
+    // every key in the bucket with its ETag, the MD5 of an object put in one part, a thousand keys a request
+    async list() {
+      const out = [];
+      let token = null;
+      do {
+        const query = `?list-type=2${token ? `&continuation-token=${encodeURIComponent(token)}` : ''}`;
+        const res = await retry(`list ${bucket}`, async () => fetch(await aws.sign(base + query, { method: 'GET' })), opts);
+        if (!res.ok) throw new Error(`list ${bucket}: HTTP ${res.status} ${(await res.text()).slice(0, 300)}`);
+        const xml = await res.text();
+        for (const [, entry] of xml.matchAll(/<Contents>([\s\S]*?)<\/Contents>/g))
+          out.push({ key: unescapeXml(entry.match(/<Key>([\s\S]*?)<\/Key>/)[1]), etag: unescapeXml(entry.match(/<ETag>([\s\S]*?)<\/ETag>/)[1]).replace(/"/g, '') });
+        token = xml.match(/<NextContinuationToken>([\s\S]*?)<\/NextContinuationToken>/)?.[1];
+        token = token ? unescapeXml(token) : null;
+      } while (token);
+      return out;
+    },
+    async delete(key) {
+      const res = await retry(`DELETE ${key}`, async () => fetch(await aws.sign(base + key, { method: 'DELETE' })), opts);
+      if (!res.ok && res.status !== 404) throw new Error(`DELETE ${key}: HTTP ${res.status} ${(await res.text()).slice(0, 300)}`);
+    },
+  };
+}
+
+// The keys of a tree the store lacks. The meta file of the tree's root means none. Else the tree latest.json names
+// tells the directories that match and the keys uploaded, and the store is asked for each other key. A story without
+// latest.json returns null, or with headAll a request for every key.
+export async function missingKeys(reader, tree, { headAll = false } = {}) {
+  const meta = `meta/${tree.story}/`;
+  if (await reader.get(`${meta}${tree.root}.json`)) return { missing: [], complete: true };
+  const latest = await reader.json(`${meta}latest.json`), stored = latest && await reader.json(`${meta}${latest.root}.json`);
+  if (!stored && !headAll) return { missing: null, complete: false };
+  const known = new Set(), same = new Set();
+  for (const [d, x] of Object.entries(stored?.dirs ?? {})) {
+    for (const k of x.keys) known.add(k);
+    if (tree.dirs[d]?.hash === x.hash) same.add(d);
+  }
+  const ask = [...new Set(Object.entries(tree.dirs).filter(([d]) => !same.has(d)).flatMap(([, x]) => x.keys).filter(k => !known.has(k)))];
+  const found = await pool(ask, 8, k => reader.has(k));
+  return { missing: ask.filter((_, i) => !found[i]), complete: false };
+}
+
+// The keys of a tree that a listing of the bucket lacks, held being the set of keys in the store.
+export function missingIn(held, tree) {
+  const keys = [...new Set(Object.values(tree.dirs).flatMap(x => x.keys))];
+  return { missing: keys.filter(k => !held.has(k)), complete: held.has(`meta/${tree.story}/${tree.root}.json`) };
+}
+
+// The missing objects of a tree in words: the image folders by path, and the engine's objects as the engine describes
+// them, else by count.
+export function describeMissing(tree, missing, describe = null) {
+  const set = new Set(missing);
+  const folders = Object.entries(tree.dirs).filter(([d, x]) => !d.startsWith('objects/') && d.includes('/images/') && x.keys.some(k => set.has(k))).map(([d]) => d);
+  const others = missing.filter(k => !k.startsWith('images/'));
+  const described = others.length ? describe?.(others) ?? `${others.length} object${others.length === 1 ? '' : 's'}` : '';
+  return [folders.length && `the images of ${folders.join(', ')}`, described].filter(Boolean).join(' and ');
+}
+
+// kitap build --strict: every object the trees name is in the store. Throws with the stories that lack some, named by
+// each tree's dir, the story folder.
+export async function checkStore({ url, trees, log = console.log, describe = null, ...opts }) {
+  const reader = storeReader(url, opts), problems = [];
+  for (const tree of trees) {
+    const { missing } = await missingKeys(reader, tree);
+    if (missing === null) problems.push(`${tree.dir}: the store holds no upload of this story, kitap upload --story ${tree.story} puts its objects there`);
+    else if (missing.length) problems.push(`${tree.dir}: the store lacks ${describeMissing(tree, missing, describe)}, kitap upload --story ${tree.story} puts them there`);
+  }
+  if (problems.length) throw new Error(problems.join('\n'));
+  log(`the store holds every object of ${trees.length} stor${trees.length === 1 ? 'y' : 'ies'} (${reader.count} request${reader.count === 1 ? '' : 's'})`);
+}

package/src/themes.yaml

@@ -0,0 +1,27 @@
+# Named colour themes. Each has a light and a dark set of the same tokens.
+# A project adds or overrides themes under `themes:` in site.yaml with the same shape.
+# Names are interface strings: themes.<id> in src/i18n/<lang>.yaml, or i18n/ui/<lang>.yaml in a project.
+# land lists tints for the countries, atlas style; a theme without it paints every country paper2.
+cool:
+  light: { paper: "#f7f7f5", paper2: "#eef0ea", sea: "#d8e0e6", ink: "#1f2328", ink2: "#5b6470", rule: "#c9cfd6", accent: "#c0392b", panel: "#ffffff", route: "#5b6470", border: "#7a848f",
+           land: ["#e6e8d6", "#e2e6ea", "#ece2d6", "#dfe8dc", "#eadfe0", "#e8e4d2"] }
+  dark:  { paper: "#15181c", paper2: "#262b31", sea: "#0f1317", ink: "#e6e8eb", ink2: "#9aa3ad", rule: "#3a414a", accent: "#e8655a", panel: "#1c2026", route: "#9aa3ad", border: "#8a949e",
+           land: ["#2b3128", "#262d36", "#332c27", "#263229", "#312a2e", "#302f26"] }
+mono:
+  light: { paper: "#ffffff", paper2: "#f0f0f0", sea: "#e2e2e2", ink: "#111111", ink2: "#666666", rule: "#d0d0d0", accent: "#c8102e", panel: "#fafafa", route: "#666666", border: "#777777" }
+  dark:  { paper: "#0e0e0e", paper2: "#232323", sea: "#050505", ink: "#f2f2f2", ink2: "#a0a0a0", rule: "#333333", accent: "#ff4d5e", panel: "#161616", route: "#a0a0a0", border: "#8c8c8c" }
+navy:
+  light: { paper: "#0f1a2b", paper2: "#c9bda0", sea: "#0b1422", ink: "#f1e9d6", ink2: "#a9b2c2", rule: "#2c3b55", accent: "#f0a04b", panel: "#162339", route: "#a9b2c2", border: "#5c6a80",
+           land: ["#c9bda0", "#bfc3a0", "#c7b396", "#b8bfa8", "#cbb8a6", "#c2bb9a"] }
+  dark:  { paper: "#0f1a2b", paper2: "#c9bda0", sea: "#0b1422", ink: "#f1e9d6", ink2: "#a9b2c2", rule: "#2c3b55", accent: "#f0a04b", panel: "#162339", route: "#a9b2c2", border: "#5c6a80",
+           land: ["#c9bda0", "#bfc3a0", "#c7b396", "#b8bfa8", "#cbb8a6", "#c2bb9a"] }
+parchment:
+  light: { paper: "#e9ebe6", paper2: "#dfe2da", sea: "#cfd7d3", ink: "#262b28", ink2: "#5c645f", rule: "#b8beb8", accent: "#9c2f2f", panel: "#f1f2ee", route: "#5c645f", border: "#6f7873",
+           land: ["#dde2cf", "#d8e0dc", "#e3dccd", "#d5e0d2", "#e0d8d6", "#dcdccb"] }
+  dark:  { paper: "#22262a", paper2: "#30363b", sea: "#171b1f", ink: "#e3e6e2", ink2: "#a3aaa6", rule: "#454c51", accent: "#d9605e", panel: "#1c2024", route: "#a3aaa6", border: "#8f9893",
+           land: ["#333a2f", "#2e363e", "#3a342d", "#2e3a33", "#383037", "#36362c"] }
+sepia:
+  light: { paper: "#e6e1d2", paper2: "#ddd7c6", sea: "#cfd6d2", ink: "#2a2823", ink2: "#5d5950", rule: "#b9b2a0", accent: "#a3282b", panel: "#efebe0", route: "#5d5950", border: "#6d665a",
+           land: ["#dcd4b8", "#d3d6c2", "#e0d0bd", "#cfd6c4", "#ddd0c8", "#d8d6b9"] }
+  dark:  { paper: "#2a2823", paper2: "#34312a", sea: "#1d2024", ink: "#e7e1d1", ink2: "#aaa392", rule: "#4e4a40", accent: "#d9565a", panel: "#23211c", route: "#aaa392", border: "#9a9283",
+           land: ["#38352a", "#30352e", "#3b322a", "#2e3630", "#38302e", "#353426"] }

package/src/translate.mjs

@@ -0,0 +1,41 @@
+// kitap i18n <lang> [--story id]: builds quietly to collect every string, then writes the <lang>.yaml catalogues of
+// each story, of each image folder and folder of the engine's a story uses, and of the site, keeping the translations there.
+import fs from 'fs';
+import os from 'os';
+import path from 'path';
+import yaml from 'js-yaml';
+import { buildPages, uiCatalogue } from './build.mjs';
+import { flatten, catalogueText } from './i18n.mjs';
+
+export function i18n({ root = process.cwd(), lang, story, log = console.log, engine = null } = {}) {
+  if (!lang) throw new Error('usage: kitap i18n <lang> [--story id]');
+  // one story builds alone into a folder thrown away after, so a half edited story elsewhere does not stop it
+  const out = story && fs.mkdtempSync(path.join(os.tmpdir(), 'kitap-i18n-'));
+  let r;
+  try { r = buildPages({ root, log: () => {}, story, out, localAssets: true, engine }); } finally { if (out) fs.rmSync(out, { recursive: true, force: true }); }
+  const written = [];
+  const write = (file, entries, heading) => {
+    const existing = fs.existsSync(file) ? flatten(yaml.load(fs.readFileSync(file, 'utf8')) ?? {}) : {};
+    const { text, filled, total } = catalogueText(lang, entries, existing, heading);
+    fs.mkdirSync(path.dirname(file), { recursive: true });
+    fs.writeFileSync(file, text);
+    log(`wrote ${path.relative(root, file)}: ${filled} of ${total} strings translated`);
+    written.push(file);
+  };
+  for (const [id, { dir, entries }] of Object.entries(r.i18n.stories)) write(path.join(root, dir, 'i18n', lang + '.yaml'), entries, `${lang} strings for the story "${id}".`);
+  // an image folder's or an engine folder's catalogues sit in its folder, for each language a story using it has
+  for (const [dir, f] of Object.entries(r.i18n.folders)) {
+    if (lang === f.defaultLang || !f.langs.includes(lang)) continue;
+    write(path.join(root, dir, 'i18n', lang + '.yaml'), f.entries, `${lang} strings for the ${f.kind} "${f.id}".`);
+  }
+  if (!story) write(path.join(root, 'i18n', lang + '.yaml'), r.i18n.site, `${lang} strings for the site.`);
+  if (!story && lang !== 'en') {
+    const u = uiCatalogue(root, lang, r.themes, r.engine), file = path.join(root, 'i18n', 'ui', lang + '.yaml');
+    if (u.missing.length || fs.existsSync(file)) {
+      const { text, filled, total } = catalogueText(lang, u.entries, u.existing, `${lang} interface strings: buttons, labels, messages, theme names. Overrides what kitap and the engine ship.`);
+      fs.mkdirSync(path.dirname(file), { recursive: true }); fs.writeFileSync(file, text);
+      log(`wrote ${path.relative(root, file)}: ${filled} of ${total} strings translated`); written.push(file);
+    } else log(`interface: kitap and the engine ship all ${u.entries.length} strings for ${lang}`);
+  }
+  return written;
+}