simplex-web 0.2.0__py3-none-any.whl

simplex/render/thumbnail.py

@@ -0,0 +1,374 @@
+"""Per-main-slide JPG thumbnails from the reconciled subsection MP4s.
+
+Default rule: extract the **last frame** of the **second-to-last subsection**
+(``subsections[-2]``). Configurable per main via
+``deck.slides["Main Name"].thumbnail_section_index``. A literal path
+override at ``deck.slides["Main Name"].thumbnail`` (relative to the deck
+directory) wins over the extraction rule.
+
+Content-addressable cache: file name = sha256 of source path + mtime + deck
+slug, so re-rendering a subsection naturally invalidates its thumbnail.
+
+Extraction tries the system ``ffmpeg`` CLI first (fastest), then falls back
+to PyAV -- manim already depends on PyAV for its own concatenation pipeline,
+so this fallback works without any extra system binaries (the typical reason
+real previews showed "no preview yet" on Windows: manim runs via PyAV but
+ffmpeg.exe is not on PATH, so the old code went straight to the placeholder).
+The "no video" fallback ships an inline SVG so the placeholder is always a
+valid image even when neither extractor can run.
+"""
+
+import contextlib
+import hashlib
+import shutil
+import subprocess
+from pathlib import Path
+
+import av
+import av.error
+from PIL import Image
+from PIL.Image import Resampling
+
+from simplex.deck.config import DeckConfig
+from simplex.manifest import DeckManifest, MainSlide, Subsection
+
+DEFAULT_WIDTH = 480
+DEFAULT_SECONDARY_WIDTH = 960
+DEFAULT_GIF_WIDTH = 320
+DEFAULT_GIF_FPS = 6
+DEFAULT_GIF_MAX_FRAMES = 24
+DEFAULT_GIF_COLORS = 64
+PLACEHOLDER_NAME = "_placeholder.svg"
+
+
+def _key(video: Path, slug: str) -> str:
+    stat = video.stat()
+    raw = f"{slug}:{video.as_posix()}:{stat.st_mtime_ns}:{stat.st_size}"
+    return hashlib.sha256(raw.encode()).hexdigest()[:24]
+
+
+def _multi_video_key(videos: tuple[Path, ...], slug: str, suffix: str) -> str:
+    parts = [slug, suffix]
+    for video in videos:
+        stat = video.stat()
+        parts.append(f"{video.as_posix()}:{stat.st_mtime_ns}:{stat.st_size}")
+    return hashlib.sha256("|".join(parts).encode()).hexdigest()[:24]
+
+
+def _extract_frame(
+    video: Path,
+    dest: Path,
+    *,
+    width: int,
+    seek_from_end: bool = True,
+) -> bool:
+    """Extract one frame near the end (or start) of ``video`` to ``dest``.
+
+    Tries ``ffmpeg`` first; falls back to PyAV (bundled with manim) when the
+    CLI is missing. Returns ``True`` on success.
+    """
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    if _try_ffmpeg(video, dest, width=width, seek_from_end=seek_from_end):
+        return True
+    return _try_pyav(video, dest, width=width, seek_from_end=seek_from_end)
+
+
+def _try_ffmpeg(
+    video: Path,
+    dest: Path,
+    *,
+    width: int,
+    seek_from_end: bool,
+) -> bool:
+    """Extract a frame via the ``ffmpeg`` CLI if it's on PATH."""
+    if shutil.which("ffmpeg") is None:
+        return False
+    seek = ["-sseof", "-0.1"] if seek_from_end else ["-ss", "0.1"]
+    args = [
+        "ffmpeg",
+        "-y",
+        "-loglevel",
+        "error",
+        *seek,
+        "-i",
+        str(video),
+        "-vframes",
+        "1",
+        "-vf",
+        f"scale={width}:-2",
+        "-q:v",
+        "2",
+        str(dest),
+    ]
+    with contextlib.suppress(subprocess.SubprocessError, FileNotFoundError):
+        subprocess.run(args, check=True, timeout=30)
+        return dest.exists()
+    return False
+
+
+def _try_pyav(
+    video: Path,
+    dest: Path,
+    *,
+    width: int,
+    seek_from_end: bool,
+) -> bool:
+    """Decode a representative frame with PyAV and save it as JPEG.
+
+    Walks every frame and keeps the last when ``seek_from_end`` is true; for
+    typical slide-length clips (<10 s) that's still fast and avoids the
+    container-specific seek edge cases (no-keyframe, B-frame ordering, etc.)
+    that bite when you try to seek directly to the tail.
+    """
+    try:
+        with av.open(str(video)) as container:
+            stream = container.streams.video[0]
+            stream.thread_type = "AUTO"
+            chosen = None
+            for frame in container.decode(stream):
+                chosen = frame
+                if not seek_from_end:
+                    break
+            if chosen is None:
+                return False
+            image = chosen.to_image()
+    except (av.error.FFmpegError, IndexError, OSError):
+        return False
+    src_w, src_h = image.size
+    if src_w <= 0 or src_h <= 0:
+        return False
+    target_h = max(1, round(src_h * width / src_w))
+    if (src_w, src_h) != (width, target_h):
+        image = image.resize((width, target_h), Resampling.LANCZOS)
+    image.save(str(dest), "JPEG", quality=85, optimize=True)
+    return dest.exists()
+
+
+_PLACEHOLDER_SVG = (
+    '<?xml version="1.0" encoding="UTF-8"?>'
+    '<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 480 270" '
+    'preserveAspectRatio="xMidYMid slice" role="img" '
+    'aria-label="No preview available">'
+    '<rect width="480" height="270" fill="#242424"/>'
+    '<text x="240" y="142" text-anchor="middle" fill="#8a8a8a" '
+    'font-family="system-ui, sans-serif" font-size="18">no preview yet</text>'
+    "</svg>"
+)
+
+
+def _placeholder(dest_dir: Path) -> Path:
+    """Write a 16:9 SVG placeholder once per deck and return its path.
+
+    SVG works without ffmpeg and is a single inline string, so the file is
+    always a valid image regardless of the host's video-tool availability.
+    """
+    placeholder = dest_dir / PLACEHOLDER_NAME
+    if placeholder.exists():
+        return placeholder
+    placeholder.parent.mkdir(parents=True, exist_ok=True)
+    placeholder.write_text(_PLACEHOLDER_SVG, encoding="utf-8")
+    return placeholder
+
+
+def _pick_source(main: MainSlide, override_idx: int) -> Subsection | None:
+    """Pick which subsection's frame to use for `main`'s thumbnail.
+
+    Returns the subsection at ``override_idx`` if it has a usable video,
+    otherwise walks the remaining subsections (last-to-first) so a missing
+    video at ``-1`` (e.g. the trailing skip-animations section Manim emits
+    when ``construct()`` ends without a final ``play()``) doesn't degrade
+    into the placeholder. Returns ``None`` only when the main has no
+    playable video at any index.
+    """
+    subs = main.subsections
+    if not subs:
+        return None
+    try:
+        primary = subs[override_idx]
+    except IndexError:
+        primary = subs[-1]
+    if _has_video(primary):
+        return primary
+    # Fallback: scan from last to first, skipping the primary we already
+    # tried. The last sub usually carries the slide's final visual state
+    # (the most informative thumbnail), so we prefer it over earlier ones.
+    for sub in reversed(subs):
+        if sub is primary:
+            continue
+        if _has_video(sub):
+            return sub
+    return primary
+
+
+def _has_video(sub: Subsection) -> bool:
+    return sub.video is not None and sub.video.exists()
+
+
+def generate(
+    deck: DeckConfig,
+    manifest: DeckManifest,
+    *,
+    site_deck_dir: Path,
+    cache_dir: Path,
+) -> dict[int, Path]:
+    """Generate one JPG per main slide. Returns ``{main.index: rel_path}``."""
+    thumbs_dir = site_deck_dir / "thumbs"
+    cache_root = cache_dir / "thumbnails" / deck.slug
+    thumbs_dir.mkdir(parents=True, exist_ok=True)
+    cache_root.mkdir(parents=True, exist_ok=True)
+    out: dict[int, Path] = {}
+    for main in manifest.main_slides:
+        out[main.index] = _one(main, deck, thumbs_dir, cache_root)
+    return out
+
+
+def generate_carousel_gif(
+    deck: DeckConfig,
+    manifest: DeckManifest,
+    *,
+    site_deck_dir: Path,
+    cache_dir: Path,
+) -> Path | None:
+    """Return a low-quality GIF preview for deck cards, if configured.
+
+    Resolution order:
+    1. ``[web] carousel_gif = "path/to/preview.gif"`` copies the user asset.
+    2. ``[web] carousel_gif_slides = [1, 3]`` samples rendered videos from
+       those 1-based main-slide indexes and writes a small cached GIF.
+    3. No configured preview returns ``None`` so the portal keeps the static
+       thumbnail only.
+    """
+    previews_dir = site_deck_dir / "previews"
+    cache_root = cache_dir / "carousel-gifs" / deck.slug
+    if deck.web.carousel_gif is not None:
+        return _copy_gif_override(deck, previews_dir)
+
+    selected = set(deck.web.carousel_gif_slides)
+    if not selected:
+        return None
+    videos = tuple(
+        sub.video
+        for main in manifest.main_slides
+        if main.index in selected
+        for sub in [_pick_source(main, -1)]
+        if sub is not None and sub.video is not None and sub.video.exists()
+    )
+    if not videos:
+        return None
+
+    previews_dir.mkdir(parents=True, exist_ok=True)
+    cache_root.mkdir(parents=True, exist_ok=True)
+    key = _multi_video_key(videos, deck.slug, ",".join(str(i) for i in sorted(selected)))
+    cached = cache_root / f"{key}.gif"
+    dest = previews_dir / f"{key}.gif"
+    if cached.exists():
+        if not dest.exists():
+            shutil.copy2(cached, dest)
+        return dest.relative_to(site_deck_dir)
+    if _write_preview_gif(videos, dest):
+        shutil.copy2(dest, cached)
+        return dest.relative_to(site_deck_dir)
+    return None
+
+
+def _copy_gif_override(deck: DeckConfig, previews_dir: Path) -> Path | None:
+    rel = deck.web.carousel_gif
+    if rel is None:
+        return None
+    src = deck.path / rel
+    if not src.exists() or src.suffix.lower() != ".gif":
+        return None
+    previews_dir.mkdir(parents=True, exist_ok=True)
+    key = _multi_video_key((src,), deck.slug, "override")
+    target = previews_dir / f"override_{key}.gif"
+    if not target.exists() or target.stat().st_mtime < src.stat().st_mtime:
+        shutil.copy2(src, target)
+    return target.relative_to(previews_dir.parent)
+
+
+def _write_preview_gif(videos: tuple[Path, ...], dest: Path) -> bool:
+    frames: list[Image.Image] = []
+    per_video = max(1, DEFAULT_GIF_MAX_FRAMES // max(1, len(videos)))
+    for video in videos:
+        frames.extend(_sample_gif_frames(video, max_frames=per_video, width=DEFAULT_GIF_WIDTH))
+        if len(frames) >= DEFAULT_GIF_MAX_FRAMES:
+            frames = frames[:DEFAULT_GIF_MAX_FRAMES]
+            break
+    if not frames:
+        return False
+    dest.parent.mkdir(parents=True, exist_ok=True)
+    try:
+        frames[0].save(
+            str(dest),
+            save_all=True,
+            append_images=frames[1:],
+            duration=round(1000 / DEFAULT_GIF_FPS),
+            loop=0,
+            optimize=True,
+        )
+    except OSError:
+        return False
+    return dest.exists()
+
+
+def _sample_gif_frames(video: Path, *, max_frames: int, width: int) -> list[Image.Image]:
+    out: list[Image.Image] = []
+    try:
+        with av.open(str(video)) as container:
+            stream = container.streams.video[0]
+            stream.thread_type = "AUTO"
+            rate = float(stream.average_rate or DEFAULT_GIF_FPS)
+            stride = max(1, round(rate / DEFAULT_GIF_FPS))
+            for i, frame in enumerate(container.decode(stream)):
+                if i % stride != 0:
+                    continue
+                out.append(_gif_frame(frame.to_image(), width=width))
+                if len(out) >= max_frames:
+                    break
+    except (av.error.FFmpegError, IndexError, OSError):
+        return []
+    return out
+
+
+def _gif_frame(image: Image.Image, *, width: int) -> Image.Image:
+    src_w, src_h = image.size
+    if src_w > 0 and src_h > 0 and src_w != width:
+        target_h = max(1, round(src_h * width / src_w))
+        image = image.resize((width, target_h), Resampling.LANCZOS)
+    return image.convert("P", palette=Image.Palette.ADAPTIVE, colors=DEFAULT_GIF_COLORS)
+
+
+def _one(
+    main: MainSlide,
+    deck: DeckConfig,
+    thumbs_dir: Path,
+    cache_root: Path,
+) -> Path:
+    # Literal path override?
+    override = deck.slides.get(main.name)
+    if override is not None and override.thumbnail is not None:
+        src = deck.path / override.thumbnail
+        if src.exists():
+            target = thumbs_dir / f"override_{main.index:04d}{src.suffix}"
+            shutil.copy2(src, target)
+            return target.relative_to(thumbs_dir.parent)
+
+    section_index = override.thumbnail_section_index if override is not None else -2
+    sub = _pick_source(main, section_index)
+    if sub is None or sub.video is None or not sub.video.exists():
+        return _placeholder(thumbs_dir).relative_to(thumbs_dir.parent)
+
+    key = _key(sub.video, deck.slug)
+    cached = cache_root / f"{key}.jpg"
+    dest = thumbs_dir / f"{key}.jpg"
+    if cached.exists():
+        if not dest.exists():
+            shutil.copy2(cached, dest)
+        return dest.relative_to(thumbs_dir.parent)
+    if _extract_frame(sub.video, dest, width=DEFAULT_WIDTH, seek_from_end=True):
+        shutil.copy2(dest, cached)
+        dest_2x = thumbs_dir / f"{key}@2x.jpg"
+        if _extract_frame(sub.video, dest_2x, width=DEFAULT_SECONDARY_WIDTH, seek_from_end=True):
+            shutil.copy2(dest_2x, cache_root / f"{key}@2x.jpg")
+        return dest.relative_to(thumbs_dir.parent)
+    return _placeholder(thumbs_dir).relative_to(thumbs_dir.parent)

simplex/slides/README.md

@@ -0,0 +1,9 @@
+# slides/
+
+Namespace placeholder for `simplex.slides` in this repo.
+
+The slide bases are shipped by `manim-simplex` and merged via PEP 420.
+
+## Don't
+
+- Don't add slide classes here; keep them in manim-simplex.

simplex/slides/components/README.md

@@ -0,0 +1,9 @@
+# slides/components/
+
+Placeholder for slide component helpers.
+
+Any shared components should live in `manim-simplex` alongside the slide bases.
+
+## Don't
+
+- Don't add new component code here.

simplex/theme/README.md

@@ -0,0 +1,9 @@
+# theme/
+
+Namespace placeholder for `simplex.theme` in this repo.
+
+Theme tokens and presets live in `manim-simplex` and are merged via PEP 420.
+
+## Don't
+
+- Don't edit or add theme code here.

simplex/web/README.md

@@ -0,0 +1,33 @@
+# web/
+
+Static-site generator: home carousels, deck pages, viewer bridge, academic
+notes pipeline (markdown + math + citations + Tufte sidenotes).
+
+## Public surface
+
+- `SiteConfig.load()` -- merge committed `site.toml` with env overrides
+  (`SIMPLEX_GA_TAG`, `SIMPLEX_BASE_URL`, `SIMPLEX_BRAND`, `SIMPLEX_PREVIEW`).
+- `notes.render(notes_md_path, slide_count=..., bibliography=...)` --
+  markdown-it + dollarmath + footnotes + `[slide:N]` + `\cite{}` +
+  `\ref{}` -> Tufte-style academic HTML (serif body, Lato headings,
+  right-margin sidenotes, colour-coded theorem callouts, references
+  appendix, auto-fitted display math).
+- `bibliography.Bibliography.load(refs_bib)` -- parse a `.bib`, assign
+  biblatex `alpha` labels (`[DHS11]`-style), render the cited subset.
+- `callouts.transform(html)` -- rewrite `> **Theorem 3.1.** ...`
+  blockquotes as anchored `<aside class="callout callout-theorem"
+  id="theorem-3-1">` blocks; resolve `\ref{}` placeholders to the
+  display label.
+- `builder.build(decks_dir, site_dir, *, render=True, site_cfg=None, only=(), scenes=(), watch=False)`
+  -- discover -> render -> pdf -> reconcile -> thumbnail -> notes ->
+  emit per-deck `slides.html` + page + per-section pages + home.
+
+## Don't
+
+- Don't bundle JS or load CDNs. Tailwind / KaTeX / RevealJS / Lato /
+  Merriweather are vendored under `static/` (see `static/README.md`).
+- Don't hand-edit anything under `site/`. Edit templates / CSS instead.
+- Don't import Jinja templates as Python modules. Loaded via
+  `PackageLoader("simplex.web", "templates")`.
+- Don't write a manual "References" section in `notes.md`. Use
+  `\cite{key}` and ship a `refs.bib`; the renderer appends the list.

simplex/web/__init__.py

@@ -0,0 +1 @@
+"""Static-site generator: notes + builder + templates."""

simplex/web/bibliography.py

@@ -0,0 +1,248 @@
+"""BibTeX -> biblatex-alpha citation keys + HTML bibliography.
+
+`bibtex.py` does the parsing; this module owns the data model and the
+rendered output.
+
+Public surface (see `simplex/web/README.md`):
+
+- `Bibliography.parse(text)` / `.load(path)` -- read a `.bib` file.
+- `Bibliography.get(key)` -- retrieve an entry, raises if missing.
+- `Bibliography.has(key)` -- existence check (used by the citations plugin).
+- `Bibliography.to_html(used)` -- ordered <ol> of the cited entries, in the
+  order they were first referenced. Pass an empty tuple to suppress.
+
+Alpha labels follow `biblatex`'s `alpha` style:
+
+    1 author  -> 3 letters of last name           ("Hou00")
+    2-3       -> 1 letter of each last name       ("KB15", "DHS11")
+    4+        -> 3 letters of first three + "+"   ("ABG+23")
+
+followed by the last two digits of the year (or `??` if unknown).
+"""
+
+import re
+from pathlib import Path
+from typing import Self
+
+from pydantic import BaseModel, ConfigDict
+
+from simplex.web import bibtex
+
+
+class Author(BaseModel):
+    """A single author. `last` is what appears in alpha labels."""
+
+    model_config = ConfigDict(frozen=True)
+
+    last: str
+    first: str = ""
+
+    @classmethod
+    def parse(cls, raw: str) -> Self:
+        """Parse a BibTeX author token (`Last, First` or `First Last`)."""
+        raw = bibtex.unbrace(raw.strip())
+        if "," in raw:
+            last, first = raw.split(",", 1)
+            return cls(last=last.strip(), first=first.strip())
+        parts = raw.split()
+        if len(parts) == 1:
+            return cls(last=parts[0])
+        return cls(last=parts[-1], first=" ".join(parts[:-1]))
+
+    @property
+    def display(self) -> str:
+        """`F. Last`-style initials for the bibliography list."""
+        if not self.first:
+            return self.last
+        initials = " ".join(f"{p[0]}." for p in self.first.split() if p)
+        return f"{initials} {self.last}".strip()
+
+
+class BibEntry(BaseModel):
+    """A single bibliography entry. The field bag stays a plain dict because
+    BibTeX's field set is open."""
+
+    model_config = ConfigDict(frozen=True)
+
+    key: str
+    entry_type: str
+    fields: dict[str, str]
+    authors: tuple[Author, ...]
+    year: int | None
+    alpha_key: str
+
+    @classmethod
+    def make(cls, key: str, entry_type: str, fields: dict[str, str]) -> Self:
+        authors = _parse_authors(fields.get("author") or fields.get("editor") or "")
+        year = _parse_year(fields.get("year", ""))
+        return cls(
+            key=key,
+            entry_type=entry_type.lower(),
+            fields=fields,
+            authors=authors,
+            year=year,
+            alpha_key=_alpha_key(authors, year),
+        )
+
+    def render_html(self) -> str:
+        """Emit one <li> for the bibliography list.
+
+        The alpha-key marker (e.g. `[KB15]`) is rendered as an inline
+        `<span class="bib-marker">`, not a CSS counter, so the printed
+        bullet matches the inline `[KB15]` citation chip.
+        """
+        parts: list[str] = []
+        if self.authors:
+            parts.append(_join_authors(self.authors))
+        if title := self.fields.get("title"):
+            # Wrap titles in quotes (academic convention). Joining with ", "
+            # yields the canonical `Authors, "Title," Venue, Year.` shape.
+            parts.append(f"&ldquo;{_escape_html(bibtex.unbrace(title))}&rdquo;")
+        if venue := self._venue_html():
+            parts.append(venue)
+        if self.year is not None:
+            parts.append(str(self.year))
+        body = ", ".join(parts)
+        if link := self._link_html():
+            body = f"{body} {link}"
+        marker = f'<span class="bib-marker">[{_escape_html(self.alpha_key)}]</span>'
+        return f'<li id="bib-{_escape_html(self.key)}" class="bib-entry">{marker} {body}.</li>'
+
+    def _venue_html(self) -> str:
+        for field in ("journal", "booktitle", "publisher", "school", "institution"):
+            if value := self.fields.get(field):
+                return f"<em>{_escape_html(bibtex.unbrace(value))}</em>"
+        return ""
+
+    def _link_html(self) -> str:
+        for field in ("doi", "url"):
+            value = self.fields.get(field)
+            if not value:
+                continue
+            value = bibtex.unbrace(value)
+            href = value if field == "url" else f"https://doi.org/{value}"
+            return (
+                f'<a class="bib-link" href="{_escape_html(href)}" '
+                f'rel="noopener" target="_blank">[link]</a>'
+            )
+        return ""
+
+
+class Bibliography(BaseModel):
+    """Parsed .bib file. `entries` is keyed by the BibTeX cite key."""
+
+    entries: dict[str, BibEntry]
+
+    @classmethod
+    def parse(cls, text: str) -> Self:
+        """Parse a BibTeX document. Duplicate keys keep the first definition;
+        the citations plugin marks unknown keys as stale."""
+        parsed: dict[str, BibEntry] = {}
+        for key, entry_type, fields in bibtex.parse(text):
+            if key in parsed:
+                continue
+            parsed[key] = BibEntry.make(key, entry_type, fields)
+        return cls(entries=parsed)
+
+    @classmethod
+    def load(cls, path: Path) -> Self:
+        return cls.parse(path.read_text(encoding="utf-8"))
+
+    @classmethod
+    def empty(cls) -> Self:
+        return cls(entries={})
+
+    def has(self, key: str) -> bool:
+        return key in self.entries
+
+    def get(self, key: str) -> BibEntry:
+        return self.entries[key]
+
+    def to_html(self, used: tuple[str, ...]) -> str:
+        """Render an ordered list of the cited entries, in citation order."""
+        seen: set[str] = set()
+        ordered: list[BibEntry] = []
+        for key in used:
+            if key in seen or key not in self.entries:
+                continue
+            seen.add(key)
+            ordered.append(self.entries[key])
+        if not ordered:
+            return ""
+        items = "\n".join(e.render_html() for e in ordered)
+        return (
+            '<section class="bibliography" aria-labelledby="bib-heading">'
+            '<h2 id="bib-heading">References</h2>'
+            f'<ol class="bib-list">\n{items}\n</ol>'
+            "</section>"
+        )
+
+
+# ---------------------------------------------------------------------------
+# Author / alpha-key helpers
+# ---------------------------------------------------------------------------
+
+
+def _parse_authors(raw: str) -> tuple[Author, ...]:
+    if not raw:
+        return ()
+    parts = re.split(r"\s+and\s+", raw, flags=re.IGNORECASE)
+    return tuple(Author.parse(p) for p in parts if p.strip())
+
+
+def _parse_year(raw: str) -> int | None:
+    if not raw:
+        return None
+    match = re.search(r"\d{4}", raw)
+    return int(match.group(0)) if match else None
+
+
+def _alpha_key(authors: tuple[Author, ...], year: int | None) -> str:
+    """biblatex-alpha label. Empty author list -> `Anon` prefix."""
+    suffix = f"{year % 100:02d}" if year is not None else "??"
+    if not authors:
+        return f"Anon{suffix}"
+    initials = [_first_letter(a.last) for a in authors]
+    match len(initials):
+        case 1:
+            prefix = (initials[0] + _initial_pad(authors[0].last))[:3]
+        case 2 | 3:
+            prefix = "".join(initials)
+        case _:
+            prefix = "".join(initials[:3]) + "+"
+    return f"{prefix}{suffix}"
+
+
+def _first_letter(s: str) -> str:
+    for ch in s:
+        if ch.isalpha():
+            return ch.upper()
+    return "?"
+
+
+def _initial_pad(last: str) -> str:
+    """For single-author keys, take chars 2-3 of the last name (lowercased)."""
+    letters = [c for c in last if c.isalpha()]
+    return "".join(letters[1:3]).lower()
+
+
+def _join_authors(authors: tuple[Author, ...]) -> str:
+    """`A. Smith, B. Jones, and C. Lee`."""
+    names = [_escape_html(a.display) for a in authors]
+    match len(names):
+        case 0:
+            return ""
+        case 1:
+            return names[0]
+        case 2:
+            return f"{names[0]} and {names[1]}"
+        case _:
+            head = ", ".join(names[:-1])
+            return f"{head}, and {names[-1]}"
+
+
+_ESCAPE = {"&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;"}
+
+
+def _escape_html(s: str) -> str:
+    return "".join(_ESCAPE.get(c, c) for c in s)