@docpensieve/core 0.1.5 → 0.2.0

package/src/generator.js

@@ -4,11 +4,12 @@
  * @module @docpensieve/core/generator
  */
 
-import { copyFile, mkdir, readFile, readdir, writeFile } from 'node:fs/promises';
+import { copyFile, mkdir, readFile, readdir, rm, writeFile } from 'node:fs/promises';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
 
 import {
+  ConfigError,
   DOC_EXTENSIONS,
   assetPathToSlug,
   dirPathToSlug,
@@ -22,7 +23,10 @@ import Handlebars from 'handlebars';
 import { Compiler } from './compiler.js';
 import { resolveVersion } from './config.js';
 import { DocLoader } from './loader.js';
-import { buildSidebar, collectSectionTitles } from './sidebar.js';
+import { buildFeed, buildRobots, buildSitemap } from './discovery.js';
+import { minifyCss } from './minify-css.js';
+import { SEARCH_SLUG, htmlToText, searchPageContent } from './search-index.js';
+import { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
 import { StructuredDataBuilder } from './structured-data.js';
 
 /** Template folder, resolved from this module rather than from the cwd. */
@@ -31,6 +35,15 @@ const TEMPLATE_DIR = path.join(path.dirname(fileURLToPath(import.meta.url)), '..
 /** Path of the stylesheet written into every version. */
 const STYLESHEET = 'assets/docpensieve.css';
 
+/** Index of a version, which the search page reads. */
+const SEARCH_INDEX = 'assets/search-index.json';
+
+/** Script of the search page, the only one a site loads. */
+const SEARCH_SCRIPT = 'assets/search.js';
+
+/** Source of that script, shipped with this package. */
+const CLIENT_SEARCH = fileURLToPath(new URL('../client/search.js', import.meta.url));
+
 /**
  * Where each project image is written in a version, before its extension.
  * @type {Record<'logo' | 'favicon' | 'socialImage', string>}
@@ -162,7 +175,8 @@ export class SiteGenerator {
    *
    * @param {string} versionSlug Slug of the version to generate.
    * @param {string} outDir Output folder of that version.
-   * @returns {Promise<{ pages: number, outDir: string }>}
+   * @returns {Promise<{ pages: number, outDir: string, published: import('./discovery.js').PublishedPage[] }>}
+   *   `published` lists the pages as the site serves them, for the sitemap and the feed.
    * @throws {GeneratorError} Write failure.
    */
   async buildVersion(versionSlug, outDir) {
@@ -170,6 +184,19 @@ export class SiteGenerator {
     const rootDir = this.config.rootDir ?? process.cwd();
     const target = path.resolve(rootDir, outDir);
 
+    // A page removed from the sources must not stay online: the version's
+    // folder is emptied before it is written — once it is certain to hold
+    // nothing but what a build wrote there.
+    this.#guardOutput(target);
+    try {
+      await rm(target, { recursive: true, force: true });
+    } catch (cause) {
+      throw new GeneratorError(`Could not empty the output folder "${target}".`, {
+        cause,
+        hint: 'Check that the path is a folder, and that nothing holds it open.',
+      });
+    }
+
     const sourceDir = path.resolve(rootDir, version.folder);
     const docs = await this.loader.load(sourceDir);
 
@@ -188,7 +215,12 @@ export class SiteGenerator {
     const current = this.config.versions.find((candidate) => candidate.current);
     const notice = versionNotice(version, current, this.config.baseUrl);
 
-    const sidebar = buildSidebar(docs, pageUrl, { brand: this.config.projectName });
+    // 'auto' follows the file tree; otherwise each version describes its menu
+    // in a file of its own, since each has its own pages.
+    const sidebar =
+      this.config.sidebar && this.config.sidebar !== 'auto'
+        ? await this.#describedSidebar(sourceDir, docs, pageUrl, version.folder)
+        : buildSidebar(docs, pageUrl, { brand: this.config.projectName });
     const breadcrumbTitles = collectSectionTitles(docs);
     const layout = await this.#loadLayout();
     const classes = this.#classes();
@@ -209,7 +241,46 @@ export class SiteGenerator {
 
     // The project's images go into every version: each one stands on its
     // own, down to the orphan branch it is published on.
-    const images = await this.#copyImages(target, versionBase, written);
+    const images = await this.#copyImages(target, versionBase, written, version);
+
+    // What every page of the version shares, the search page included.
+    const searchUrl = this.config.search !== false ? joinUrl(versionBase, SEARCH_SLUG) : '';
+    const shell = {
+      lang: this.config.lang ?? 'en',
+      // A fixed scheme is a class on <html>, which the skins and the dark
+      // variant of the utilities both obey.
+      darkModeClass: ['dark', 'light'].includes(this.config.theme?.darkMode ?? '')
+        ? this.config.theme.darkMode
+        : null,
+      projectName: this.config.projectName,
+      versionName: version.name,
+      homeUrl: versionBase,
+      cssHref: joinUrl(versionBase, path.dirname(STYLESHEET)) + path.basename(STYLESHEET),
+      feedUrl: this.#feedUrl(),
+      logoUrl: images.logo ?? '',
+      favicon: images.favicon
+        ? { href: images.favicon, type: FAVICON_TYPES[path.extname(images.favicon).toLowerCase()] }
+        : null,
+      // Social networks only read an absolute address: normalisation
+      // refuses a preview image without siteUrl.
+      socialImage:
+        images.socialImage && this.config.siteUrl
+          ? new URL(images.socialImage, this.config.siteUrl).href
+          : '',
+      searchUrl,
+      // The light / dark switch: a button, and the few lines of script it needs.
+      schemeToggle: this.config.theme?.toggle !== false,
+      cls: classes,
+      versions: this.#versionLinks(version.slug),
+      // A switcher offering a single choice is not a switcher.
+      showVersions: this.config.versions.length > 1,
+      // The back-to-top button is page furniture, not content: writing it in
+      // every file would repeat it everywhere, and forget it somewhere.
+      scrollToTop: this.config.scrollToTop !== false,
+      notice,
+    };
+    /** @type {{ title: string, url: string, description: string, text: string }[]} */
+    const entries = [];
 
     for (const doc of docs) {
       const url = pageUrl(doc);
@@ -229,6 +300,7 @@ export class SiteGenerator {
         url,
         dirUrl,
         basePath: versionBase,
+        sourceDir,
       });
 
       const jsonld = new StructuredDataBuilder(doc.frontmatter, url, this.config, {
@@ -242,39 +314,20 @@ export class SiteGenerator {
       // landmarks within a document, not in an entrance hall.
       const wide = pageLayout(doc) === 'home';
 
+      entries.push({
+        title: String(doc.frontmatter.title ?? this.config.projectName),
+        url,
+        description: String(doc.frontmatter.description ?? ''),
+        text: htmlToText(html),
+      });
+
       const page = layout({
-        lang: this.config.lang ?? 'en',
-        darkModeClass: null,
+        ...shell,
         title: documentTitle(doc.frontmatter.title, this.config.projectName),
         description: doc.frontmatter.description ?? '',
         canonical: this.config.siteUrl ? new URL(url, this.config.siteUrl).href : '',
-        projectName: this.config.projectName,
-        versionName: version.name,
-        homeUrl: versionBase,
         currentUrl: url,
-        cssHref: joinUrl(versionBase, path.dirname(STYLESHEET)) + path.basename(STYLESHEET),
-        logoUrl: images.logo ?? '',
-        favicon: images.favicon
-          ? {
-              href: images.favicon,
-              type: FAVICON_TYPES[path.extname(images.favicon).toLowerCase()],
-            }
-          : null,
-        // Social networks only read an absolute address: normalisation
-        // refuses a preview image without siteUrl.
-        socialImage:
-          images.socialImage && this.config.siteUrl
-            ? new URL(images.socialImage, this.config.siteUrl).href
-            : '',
-        cls: classes,
-        versions: this.#versionLinks(version.slug),
-        // A switcher offering a single choice is not a switcher.
-        showVersions: this.config.versions.length > 1,
         wide,
-        // The back-to-top button is page furniture, not content: writing it in
-        // every file would repeat it everywhere, and forget it somewhere.
-        scrollToTop: this.config.scrollToTop !== false,
-        notice,
         // A version in preparation must not compete with the current one:
         // same content, two addresses, and the wrong one comes up. "follow"
         // still lets its links be followed.
@@ -295,13 +348,199 @@ export class SiteGenerator {
       await this.#write(destination, page);
     }
 
+    // The search page and the index it reads, built with the site: content
+    // pages load no script, and this page is useful before its own runs.
+    if (searchUrl) {
+      const destination = path.join(target, SEARCH_SLUG, 'index.html');
+      const taken = written.get(destination);
+      if (taken !== undefined) {
+        throw new GeneratorError(`"${taken}" takes the place of the search page, ${searchUrl}.`, {
+          hint: 'Rename that page, or set search: false in the configuration.',
+        });
+      }
+
+      /** @param {string} file */
+      const assetUrl = (file) =>
+        joinUrl(versionBase, path.posix.dirname(file)) + path.posix.basename(file);
+      const indexFile = path.join(target, ...SEARCH_INDEX.split('/'));
+      const scriptFile = path.join(target, ...SEARCH_SCRIPT.split('/'));
+      await this.#write(indexFile, JSON.stringify(entries));
+      await mkdir(path.dirname(scriptFile), { recursive: true });
+      await copyFile(CLIENT_SEARCH, scriptFile);
+
+      const page = layout({
+        ...shell,
+        title: documentTitle('Search', this.config.projectName),
+        description: `Search the pages of ${this.config.projectName} ${version.name}.`,
+        canonical: '',
+        currentUrl: searchUrl,
+        wide: false,
+        // A list of every page, and a script: nothing a search engine should
+        // offer as a result.
+        noindex: true,
+        sidebar,
+        toc: [],
+        preloads: [],
+        scripts: [assetUrl(SEARCH_SCRIPT)],
+        content: searchPageContent(entries, assetUrl(SEARCH_INDEX)),
+        jsonld: '',
+      });
+      for (const [, value] of page.matchAll(CLASS_ATTRIBUTE)) {
+        for (const token of value.split(/\s+/)) if (token) candidates.add(token);
+      }
+      await this.#write(destination, page);
+      for (const file of [destination, indexFile, scriptFile]) written.set(file, 'the search page');
+    }
+
     await this.#copyAssets(sourceDir, target, '', written);
 
     // The stylesheet is compiled last: it needs the classes above.
     const { css } = await this.deps.theme.compile({ candidates: [...candidates] });
-    await this.#write(path.join(target, ...STYLESHEET.split('/')), css);
+    // Comments and indentation make the stylesheet readable, and heavier on
+    // every page: the reader receives it minified.
+    await this.#write(path.join(target, ...STYLESHEET.split('/')), minifyCss(css));
+
+    return {
+      pages: docs.length,
+      outDir: target,
+      published: docs.map((doc) => ({ url: pageUrl(doc), frontmatter: doc.frontmatter })),
+    };
+  }
+
+  /**
+   * Reads the sidebar description of a version.
+   *
+   * @param {string} sourceDir Source folder of the version.
+   * @param {import('./loader.js').Doc[]} docs Documents of the version.
+   * @param {(doc: import('./loader.js').Doc) => string} pageUrl
+   * @param {string} folder The version's folder, as the configuration names it.
+   * @returns {Promise<import('./sidebar.js').SidebarNode[]>}
+   * @throws {ConfigError} When the file is missing, is not JSON, or describes
+   *   the menu wrongly.
+   */
+  async #describedSidebar(sourceDir, docs, pageUrl, folder) {
+    const name = this.config.sidebar;
+    const source = `${folder}/${name}`;
+
+    let text;
+    try {
+      text = await readFile(path.join(sourceDir, ...name.split('/')), 'utf8');
+    } catch (cause) {
+      throw new ConfigError(`No sidebar description at ${source}.`, {
+        cause,
+        hint: `Each version describes its own menu, since each has its own pages: create ${source}, or set sidebar: 'auto'.`,
+      });
+    }
+
+    let description;
+    try {
+      description = JSON.parse(text);
+    } catch (cause) {
+      throw new ConfigError(
+        `${source} is not valid JSON: ${/** @type {Error} */ (cause).message}`,
+        {
+          cause,
+          hint: 'JSON accepts neither comments nor a comma after the last entry.',
+        },
+      );
+    }
+
+    return buildSidebarFromDescription(description, docs, pageUrl, { source });
+  }
+
+  /**
+   * Refuses an output folder the build could not empty without harm: the
+   * project itself, a folder above it, or one that holds a version's pages —
+   * or lies inside them. Checked before anything is deleted.
+   *
+   * @param {string} folder Absolute path.
+   * @throws {GeneratorError}
+   */
+  #guardOutput(folder) {
+    const rootDir = path.resolve(this.config.rootDir ?? process.cwd());
+    /** @param {string} child @param {string} parent */
+    const within = (child, parent) => {
+      const relative = path.relative(parent, child);
+      return relative === '' || (!relative.startsWith('..') && !path.isAbsolute(relative));
+    };
+
+    if (within(rootDir, folder)) {
+      throw new GeneratorError(`The output folder "${folder}" holds the project itself.`, {
+        hint: 'Point outDir to a folder of its own, such as "dist": the build empties the folders it writes there.',
+      });
+    }
+    for (const version of this.config.versions) {
+      const sources = path.resolve(rootDir, version.folder);
+      if (within(sources, folder) || within(folder, sources)) {
+        throw new GeneratorError(
+          `The output folder "${folder}" overlaps the pages of version "${version.slug}".`,
+          {
+            hint: 'Keep outDir apart from the documentation folders: the build empties what it writes.',
+          },
+        );
+      }
+    }
+  }
+
+  /**
+   * Absolute address of the RSS feed, or `''` when none is written.
+   *
+   * Known before any page is rendered: every page announces the feed in its
+   * head, whereas the feed itself is written once every version is built.
+   *
+   * @returns {string}
+   */
+  #feedUrl() {
+    if (!this.config.feed || !this.config.siteUrl) return '';
+    return new URL(`${this.config.baseUrl}feed.xml`, this.config.siteUrl).href;
+  }
 
-    return { pages: docs.length, outDir: target };
+  /**
+   * Writes what search engines and feed readers read, at the root of the
+   * site: `sitemap.xml`, `robots.txt` and the RSS feed.
+   *
+   * @param {string} target Output folder.
+   * @param {Map<string, import('./discovery.js').PublishedPage[]>} published
+   *   Pages of each version, by slug.
+   */
+  async #writeDiscovery(target, published) {
+    // Written anew every time: a sitemap or a feed turned off since the last
+    // build must not linger at the root of the site.
+    for (const file of ['sitemap.xml', 'robots.txt', 'feed.xml']) {
+      await rm(path.join(target, file), { force: true });
+    }
+
+    const { siteUrl, baseUrl } = this.config;
+    if (!siteUrl) return;
+
+    if (this.config.sitemap !== false) {
+      // A version in preparation is kept out of search engines: its pages
+      // carry noindex, and listing them would contradict it.
+      const pages = this.config.versions
+        .filter((version) => !version.prerelease)
+        .flatMap((version) => published.get(version.slug) ?? []);
+      await this.#write(path.join(target, 'sitemap.xml'), buildSitemap(pages, siteUrl));
+
+      // Crawlers only read robots.txt at the root of a domain: under a
+      // sub-path, the file would be written for nobody.
+      if (baseUrl === '/') {
+        const sitemapUrl = new URL('/sitemap.xml', siteUrl).href;
+        await this.#write(path.join(target, 'robots.txt'), buildRobots(sitemapUrl));
+      }
+    }
+
+    const feedUrl = this.#feedUrl();
+    if (feedUrl) {
+      const current = resolveVersion(this.config);
+      const feed = buildFeed(published.get(current.slug) ?? [], {
+        projectName: this.config.projectName,
+        siteUrl,
+        homeUrl: new URL(joinUrl(baseUrl, 'versions', current.slug), siteUrl).href,
+        feedUrl,
+        lang: this.config.lang,
+      });
+      await this.#write(path.join(target, 'feed.xml'), feed);
+    }
   }
 
   /**
@@ -310,17 +549,19 @@ export class SiteGenerator {
    * @param {string} target Output folder of the version.
    * @param {string} versionBase URL of the version.
    * @param {Map<string, string>} written Files already written, for collisions.
+   * @param {import('./config.js').Version} version The version being built.
    * @returns {Promise<Partial<Record<keyof typeof IMAGE_FILES, string>>>} URL
    *   of each declared image.
    * @throws {GeneratorError} When a declared image does not exist.
    */
-  async #copyImages(target, versionBase, written) {
+  async #copyImages(target, versionBase, written, version) {
     const rootDir = this.config.rootDir ?? process.cwd();
     /** @type {Partial<Record<keyof typeof IMAGE_FILES, string>>} */
     const urls = {};
 
     for (const field of /** @type {(keyof typeof IMAGE_FILES)[]} */ (Object.keys(IMAGE_FILES))) {
-      const declared = this.config[field];
+      // A version's own logo or favicon replaces the project's.
+      const declared = (field !== 'socialImage' && version[field]) || this.config[field];
       if (!declared) continue;
 
       const file = `${IMAGE_FILES[field]}${path.extname(declared).toLowerCase()}`;
@@ -359,18 +600,39 @@ export class SiteGenerator {
   async buildAll() {
     const rootDir = this.config.rootDir ?? process.cwd();
     const target = path.resolve(rootDir, this.config.outDir);
+    this.#guardOutput(target);
+
+    // The folder of a version no longer declared would stay online, unlisted
+    // but reachable. Everything else in the output folder is left alone.
+    const declared = new Set(this.config.versions.map((version) => version.slug));
+    /** @type {import('node:fs').Dirent[]} */
+    let existing;
+    try {
+      existing = await readdir(path.join(target, 'versions'), { withFileTypes: true });
+    } catch {
+      existing = [];
+    }
+    for (const entry of existing) {
+      if (entry.isDirectory() && !declared.has(entry.name)) {
+        await rm(path.join(target, 'versions', entry.name), { recursive: true, force: true });
+      }
+    }
 
     let pages = 0;
+    /** @type {Map<string, import('./discovery.js').PublishedPage[]>} */
+    const published = new Map();
     for (const version of this.config.versions) {
       const result = await this.buildVersion(
         version.slug,
         path.join(target, 'versions', version.slug),
       );
       pages += result.pages;
+      published.set(version.slug, result.published);
     }
 
     await this.#writeManifest(target);
     await this.#writeRootRedirect(target);
+    await this.#writeDiscovery(target, published);
 
     return { versions: this.config.versions.length, pages, outDir: target };
   }
@@ -498,6 +760,8 @@ export class SiteGenerator {
         });
       }
 
+      // The sidebar description is read by the build, not published.
+      if (this.config.sidebar !== 'auto' && readable === this.config.sidebar) continue;
       if (DOC_EXTENSIONS.includes(path.extname(entry.name).toLowerCase())) continue;
 
       const destination = path.join(target, ...assetPathToSlug(next).split('/'));

package/src/image-size.js

@@ -0,0 +1,128 @@
+/**
+ * Dimensions of an image, read from the first bytes of its file.
+ *
+ * The build writes them on every image of a page: the browser then keeps the
+ * room before the image arrives, instead of shifting the text when it does.
+ * Only the header of each format is read — no decoding, no dependency.
+ *
+ * @module @docpensieve/core/image-size
+ */
+
+/**
+ * @typedef {{ width: number, height: number }} ImageSize
+ */
+
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function png(bytes) {
+  // Signature, then the IHDR chunk: width and height, big-endian.
+  if (bytes.length < 24 || bytes.readUInt32BE(0) !== 0x89504e47) return null;
+  return { width: bytes.readUInt32BE(16), height: bytes.readUInt32BE(20) };
+}
+
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function gif(bytes) {
+  if (bytes.length < 10 || bytes.toString('ascii', 0, 3) !== 'GIF') return null;
+  return { width: bytes.readUInt16LE(6), height: bytes.readUInt16LE(8) };
+}
+
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function jpeg(bytes) {
+  if (bytes.length < 4 || bytes[0] !== 0xff || bytes[1] !== 0xd8) return null;
+  // Walk the segments up to the frame header (SOF), which holds the size.
+  let offset = 2;
+  while (offset + 9 < bytes.length) {
+    if (bytes[offset] !== 0xff) return null;
+    const marker = bytes[offset + 1];
+    const isFrame = marker >= 0xc0 && marker <= 0xcf && ![0xc4, 0xc8, 0xcc].includes(marker);
+    if (isFrame) {
+      return { height: bytes.readUInt16BE(offset + 5), width: bytes.readUInt16BE(offset + 7) };
+    }
+    offset += 2 + bytes.readUInt16BE(offset + 2);
+  }
+  return null;
+}
+
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function webp(bytes) {
+  if (bytes.length < 30 || bytes.toString('ascii', 0, 4) !== 'RIFF') return null;
+  if (bytes.toString('ascii', 8, 12) !== 'WEBP') return null;
+  const chunk = bytes.toString('ascii', 12, 16);
+  if (chunk === 'VP8 ') {
+    return { width: bytes.readUInt16LE(26) & 0x3fff, height: bytes.readUInt16LE(28) & 0x3fff };
+  }
+  if (chunk === 'VP8L') {
+    const bits = bytes.readUInt32LE(21);
+    return { width: (bits & 0x3fff) + 1, height: ((bits >> 14) & 0x3fff) + 1 };
+  }
+  if (chunk === 'VP8X') {
+    return { width: bytes.readUIntLE(24, 3) + 1, height: bytes.readUIntLE(27, 3) + 1 };
+  }
+  return null;
+}
+
+/**
+ * @param {Buffer} bytes
+ * @returns {ImageSize | null}
+ */
+function svg(bytes) {
+  const text = bytes.toString('utf8', 0, Math.min(bytes.length, 4096));
+  const tag = /<svg\b[^>]*>/i.exec(text)?.[0];
+  if (!tag) return null;
+  /** @param {string} name */
+  const attribute = (name) => new RegExp(`\\b${name}\\s*=\\s*["']([^"']+)["']`, 'i').exec(tag)?.[1];
+
+  // Width and height in pixels, or failing that the proportions of the viewBox.
+  const width = Number.parseFloat(attribute('width') ?? '');
+  const height = Number.parseFloat(attribute('height') ?? '');
+  const inPixels = (/** @type {string | undefined} */ value) =>
+    !value || /^[\d.]+(px)?$/.test(value.trim());
+  if (width > 0 && height > 0 && inPixels(attribute('width')) && inPixels(attribute('height'))) {
+    return { width: Math.round(width), height: Math.round(height) };
+  }
+  const box = (attribute('viewBox') ?? '')
+    .trim()
+    .split(/[\s,]+/)
+    .map(Number);
+  if (box.length === 4 && box[2] > 0 && box[3] > 0) {
+    return { width: Math.round(box[2]), height: Math.round(box[3]) };
+  }
+  return null;
+}
+
+/**
+ * Reads the dimensions of an image from its content.
+ *
+ * @param {Buffer} bytes Content of the file — its first kilobytes are enough.
+ * @param {string} extension Extension of the file, dot included.
+ * @returns {ImageSize | null} `null` for an unknown or damaged format: the
+ *   image is then written without dimensions, as before.
+ */
+export function imageSize(bytes, extension) {
+  switch (extension.toLowerCase()) {
+    case '.png':
+      return png(bytes);
+    case '.jpg':
+    case '.jpeg':
+      return jpeg(bytes);
+    case '.gif':
+      return gif(bytes);
+    case '.webp':
+      return webp(bytes);
+    case '.svg':
+      return svg(bytes);
+    default:
+      return null;
+  }
+}

package/src/index.js

@@ -32,4 +32,5 @@ export { DocLoader } from './loader.js';
 export { Compiler } from './compiler.js';
 export { StructuredDataBuilder } from './structured-data.js';
 export { SiteGenerator } from './generator.js';
-export { buildSidebar, collectSectionTitles } from './sidebar.js';
+export { buildSidebar, buildSidebarFromDescription, collectSectionTitles } from './sidebar.js';
+export { buildFeed, buildRobots, buildSitemap } from './discovery.js';

package/src/minify-css.js

@@ -0,0 +1,70 @@
+/**
+ * Minification of the produced stylesheet.
+ *
+ * Deliberately cautious: comments go, and so does the whitespace that nothing
+ * reads — indentation, line breaks, the space around `{`, `}` and `;`. Every
+ * other space stays one space, since some carry meaning (`.a :hover` is not
+ * `.a:hover`), and the content of a string is never touched. That keeps most
+ * of the gain of a real minifier without its risk of changing what a rule
+ * means.
+ *
+ * @module @docpensieve/core/minify-css
+ */
+
+/** Characters around which no space is ever needed. */
+const TIGHT = new Set(['{', '}', ';']);
+
+/**
+ * @param {string} css
+ * @returns {string} The same rules, lighter.
+ */
+export function minifyCss(css) {
+  let out = '';
+  let space = false;
+  let i = 0;
+
+  while (i < css.length) {
+    const char = css[i];
+
+    // A string is copied as is, escapes included.
+    if (char === '"' || char === "'") {
+      let end = i + 1;
+      while (end < css.length && css[end] !== char) end += css[end] === '\\' ? 2 : 1;
+      if (space && out && !TIGHT.has(out[out.length - 1])) out += ' ';
+      space = false;
+      out += css.slice(i, end + 1);
+      i = end + 1;
+      continue;
+    }
+
+    // A comment weighs its length and says nothing to the browser.
+    if (char === '/' && css[i + 1] === '*') {
+      const end = css.indexOf('*/', i + 2);
+      i = end < 0 ? css.length : end + 2;
+      space = true;
+      continue;
+    }
+
+    if (char === ' ' || char === '\n' || char === '\r' || char === '\t' || char === '\f') {
+      space = true;
+      i += 1;
+      continue;
+    }
+
+    if (TIGHT.has(char)) {
+      // The last declaration of a block needs no semicolon.
+      if (char === '}' && out.endsWith(';')) out = out.slice(0, -1);
+      out += char;
+      space = false;
+      i += 1;
+      continue;
+    }
+
+    if (space && out && !TIGHT.has(out[out.length - 1])) out += ' ';
+    space = false;
+    out += char;
+    i += 1;
+  }
+
+  return out;
+}