Produce placeholder images

"""
A placeholder image without a model: an SVG derived from a hash of the identifier.

Rung N0. No file is written and no byte is downloaded: the function returns a
string of markup that a template can inline or a handler can serve.

Two properties carry the whole approach.

It is deterministic. The same identifier always yields exactly the same image,
in Python as in JavaScript, for as long as this code is left unchanged.

Its arithmetic is integer. Hue, chroma and cell positions are computed without
a single division that could round differently from one runtime to another,
which is what lets the Python and the JavaScript version agree character for
character.
"""

import re

# FNV-1a, the same constants as the rest of the catalogue, so that identifiers
# hash identically wherever they are hashed.
FNV_OFFSET = 2166136261
FNV_PRIME = 16777619
MASK32 = 0xFFFFFFFF

# Characters XML 1.0 does not allow anywhere in a document, escaped or not: C0
# controls other than tab and line breaks, lone surrogates, U+FFFE and U+FFFF.
NOT_XML = re.compile("[\x00-\x08\x0b\x0c\x0e-\x1f\ud800-\udfff\ufffe\uffff]")

GRID = 5  # cells per side
COLUMNS = 3  # independent columns; the remaining two mirror them


def stable_hash(text: str) -> int:
    """
    FNV-1a on 32 bits, fed code points rather than UTF-8 bytes: identical to
    the reference on ASCII, different from it on any other character.

    Not the built-in hash: that one is salted per process, so it would give a
    different image every time the server restarted.
    """
    digest = FNV_OFFSET
    for char in text:
        digest = ((digest ^ ord(char)) * FNV_PRIME) & MASK32
    return digest


def _hex_colour(hue: int, saturation: int, lightness: int) -> str:
    """HSL to hexadecimal, in integers only, all three arguments in percent."""
    chroma = (255 * saturation * (100 - abs(2 * lightness - 100))) // 10000
    edge = (chroma * (60 - abs((hue % 120) - 60))) // 60
    floor = (255 * lightness) // 100 - chroma // 2
    wheel = ((chroma, edge, 0), (edge, chroma, 0), (0, chroma, edge),
             (0, edge, chroma), (edge, 0, chroma), (chroma, 0, edge))
    red, green, blue = wheel[(hue // 60) % 6]
    return "#%02x%02x%02x" % (red + floor, green + floor, blue + floor)


def _escape(text: str) -> str:
    """
    The identifier ends up inside an attribute, so it is markup until escaped.

    Escaping is not enough: a control character pasted from a spreadsheet has
    no escaped form in XML 1.0 and would make the whole SVG unreadable, so it
    is dropped. The ampersand goes first, or it would escape the escapes.
    """
    text = NOT_XML.sub("", text)
    text = text.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;")
    return text.replace('"', "&quot;")


def placeholder_svg(identifier: str, size: int = 240) -> str:
    """
    Build a symmetric two-tone figure on a tinted ground.

    The high bits of the hash choose the hue, the low ones switch cells on and
    off. Mirroring the left columns onto the right ones costs one line and is
    what makes the result read as a mark rather than as noise.
    """
    digest = stable_hash(identifier)
    hue = (digest >> 16) % 360
    cell = size // GRID
    margin = (size - cell * GRID) // 2

    parts = [
        f'<svg xmlns="http://www.w3.org/2000/svg" width="{size}" height="{size}"'
        f' viewBox="0 0 {size} {size}" role="img" aria-label="{_escape(identifier)}">',
        f'<rect width="{size}" height="{size}" fill="{_hex_colour(hue, 45, 90)}"/>',
    ]
    ink = _hex_colour(hue, 55, 42)
    for row in range(GRID):
        for column in range(GRID):
            mirrored = min(column, GRID - 1 - column)
            if not (digest >> (row * COLUMNS + mirrored)) & 1:
                continue
            x = margin + column * cell
            y = margin + row * cell
            parts.append(
                f'<rect x="{x}" y="{y}" width="{cell}" height="{cell}" fill="{ink}"/>'
            )
    parts.append("</svg>")
    return "".join(parts)

/**
 * A placeholder image without a model: an SVG derived from a hash of the identifier.
 *
 * Rung N0. No file is written and no byte is downloaded: the function returns
 * a string of markup that a template can inline or a handler can serve.
 *
 * Two properties carry the whole approach.
 *
 * It is deterministic. The same identifier always yields exactly the same
 * image, in JavaScript as in Python, for as long as this code is left unchanged.
 *
 * Its arithmetic is integer. Hue, chroma and cell positions are computed
 * without a single division that could round differently from one runtime to
 * another, which is what lets the JavaScript and the Python version agree
 * character for character.
 */

// FNV-1a, the same constants as the rest of the catalogue, so that identifiers
// hash identically wherever they are hashed.
const FNV_OFFSET = 2166136261;
const FNV_PRIME = 16777619;

// Characters XML 1.0 does not allow anywhere in a document, escaped or not: C0
// controls other than tab and line breaks, lone surrogates, U+FFFE and U+FFFF.
const NOT_XML = /[\u0000-\u0008\u000b\u000c\u000e-\u001f\ud800-\udfff\ufffe\uffff]/gu;

const GRID = 5; // cells per side
const COLUMNS = 3; // independent columns; the remaining two mirror them

/**
 * FNV-1a on 32 bits, fed code points rather than UTF-8 bytes: identical to
 * the reference on ASCII, different from it on any other character.
 *
 * Math.imul is what keeps it exact: a plain multiplication on numbers this
 * large loses precision past 2^53 and would silently drift away from the
 * integers Python computes.
 */
export function stableHash(text) {
  let digest = FNV_OFFSET;
  for (const char of text) {
    digest = Math.imul(digest ^ char.codePointAt(0), FNV_PRIME) >>> 0;
  }
  return digest;
}

/** HSL to hexadecimal, in integers only, all three arguments in percent. */
function hexColour(hue, saturation, lightness) {
  const chroma = Math.floor((255 * saturation * (100 - Math.abs(2 * lightness - 100))) / 10000);
  const edge = Math.floor((chroma * (60 - Math.abs((hue % 120) - 60))) / 60);
  const floor = Math.floor((255 * lightness) / 100) - Math.floor(chroma / 2);
  const wheel = [[chroma, edge, 0], [edge, chroma, 0], [0, chroma, edge],
    [0, edge, chroma], [edge, 0, chroma], [chroma, 0, edge]];
  const channels = wheel[Math.floor(hue / 60) % 6];
  return `#${channels.map((v) => (v + floor).toString(16).padStart(2, '0')).join('')}`;
}

/**
 * The identifier ends up inside an attribute, so it is markup until escaped.
 *
 * Escaping is not enough: a control character pasted from a spreadsheet has
 * no escaped form in XML 1.0 and would make the whole SVG unreadable, so it
 * is dropped. The ampersand goes first, or it would escape the escapes.
 */
function escape(text) {
  return text.replace(NOT_XML, '').replaceAll('&', '&amp;').replaceAll('<', '&lt;')
    .replaceAll('>', '&gt;').replaceAll('"', '&quot;');
}

/**
 * Build a symmetric two-tone figure on a tinted ground.
 *
 * The high bits of the hash choose the hue, the low ones switch cells on and
 * off. Mirroring the left columns onto the right ones costs one line and is
 * what makes the result read as a mark rather than as noise.
 */
export function placeholderSvg(identifier, size = 240) {
  const digest = stableHash(identifier);
  const hue = (digest >>> 16) % 360;
  const cell = Math.floor(size / GRID);
  const margin = Math.floor((size - cell * GRID) / 2);

  const parts = [
    `<svg xmlns="http://www.w3.org/2000/svg" width="${size}" height="${size}"` +
      ` viewBox="0 0 ${size} ${size}" role="img" aria-label="${escape(identifier)}">`,
    `<rect width="${size}" height="${size}" fill="${hexColour(hue, 45, 90)}"/>`,
  ];
  const ink = hexColour(hue, 55, 42);
  for (let row = 0; row < GRID; row += 1) {
    for (let column = 0; column < GRID; column += 1) {
      const mirrored = Math.min(column, GRID - 1 - column);
      if (!((digest >>> (row * COLUMNS + mirrored)) & 1)) continue;
      const x = margin + column * cell;
      const y = margin + row * cell;
      parts.push(`<rect x="${x}" y="${y}" width="${cell}" height="${cell}" fill="${ink}"/>`);
    }
  }
  parts.push('</svg>');
  return parts.join('');
}