revision-engine 0.2.2__py3-none-any.whl

revision_engine/markdown_ext.py

@@ -0,0 +1,285 @@
+"""Markdown rendering with the reVision extensions.
+
+Extensions, all plain CommonMark syntax so other renderers degrade gracefully:
+  [phrase](@anchor)        anchor phrase -> <span class="rv-anchor" data-anchor=...>
+  [name](!intrinsic)       vendor link   -> <a class="rv-intrinsic" href=...>
+  `name` (inline code)     auto-linked when the name is in a vendor table, except inside another
+                           link's text (Markdown or raw <a>), where it renders as plain <code>; an
+                           anchor phrase is a <span>, so a span in one still links. Spans whose
+                           name is in no table are recorded on RenderedLesson.unlinked_code
+  ![alt](diagrams/x.dot)   inline pre-rendered SVG in a <figure class="rv-diagram">
+  ```quiz ... ```          page-local knowledge check widget; code spans in its text render as
+                           plain <code>, never vendor-linked; choices are shuffled in the browser
+                           unless a question sets `shuffle: false` (data-fixed-order) or has
+                           two choices; any key outside _QUESTION_KEYS (or _QUIZ_KEYS, at quiz
+                           level) fails the build
+"""
+
+from __future__ import annotations
+
+import html
+import posixpath
+from dataclasses import dataclass, field
+from typing import Callable
+
+import yaml
+from markdown_it import MarkdownIt
+from markdown_it.common.utils import escapeHtml, isLinkClose, isLinkOpen
+from markdown_it.rules_inline import backtick
+from markdown_it.token import Token
+
+from revision_engine.errors import BuildError, Report
+
+
+@dataclass
+class RenderContext:
+    anchors: dict[str, str]
+    diagrams: dict[str, str]
+    lookup: Callable[[str], str | None]
+    report: Report
+    where: str
+    lesson_file: str
+    line_offset: int = 0  # lines preceding the body in lesson.md (front matter), for file-relative error lines
+
+
+@dataclass
+class RenderedLesson:
+    html: str
+    used_anchors: list[str] = field(default_factory=list)
+    used_diagrams: list[str] = field(default_factory=list)
+    quiz_count: int = 0
+    unlinked_code: list[tuple[int, str]] = field(default_factory=list)  # (file line, span text)
+
+
+def _vendor_attrs(url: str) -> dict[str, str]:
+    return {"class": "rv-intrinsic", "href": url, "target": "_blank", "rel": "noopener"}
+
+
+def _line(token: Token, fallback: int, ctx: RenderContext) -> int:
+    body_line = token.map[0] + 1 if token.map else fallback
+    return body_line + ctx.line_offset
+
+
+def _link_text(children: list[Token], start: int) -> str:
+    parts: list[str] = []
+    for tok in children[start + 1 :]:
+        if tok.type == "link_close":
+            break
+        if tok.type in ("text", "code_inline"):
+            parts.append(tok.content)
+    return "".join(parts)
+
+
+def _close(children: list[Token], open_index: int) -> Token:
+    for tok in children[open_index + 1 :]:
+        if tok.type == "link_close":
+            return tok
+    raise AssertionError("link_open without link_close")
+
+
+def _rewrite_links(children: list[Token], line: int, ctx: RenderContext, out: RenderedLesson) -> None:
+    # A code span in another link's text must not render its own vendor <a> (no <a> inside an <a>):
+    # "code" renders it as plain <code>, "text" as its bare escaped text (the link itself became <code>).
+    # Markdown links don't nest. Raw inline <a ...> and </a> are separate html_inline tokens around the
+    # link text; an unclosed <a> runs to the end of the inline block (a browser would carry it further).
+    link_stamp: str | None = None
+    in_raw_a = False
+    for i, tok in enumerate(children):
+        if tok.type == "code_inline":
+            stamp = link_stamp or ("code" if in_raw_a else None)
+            if stamp:
+                tok.meta["rv_in_link"] = stamp
+            continue
+        if tok.type == "html_inline":
+            if isLinkOpen(tok.content):
+                in_raw_a = True
+            elif isLinkClose(tok.content):
+                in_raw_a = False
+            continue
+        if tok.type == "link_close":
+            link_stamp = None
+            continue
+        if tok.type != "link_open":
+            continue
+        link_stamp = "code"
+        href = tok.attrGet("href") or ""
+        if href.startswith("@"):
+            name = href[1:]
+            if name not in ctx.anchors:
+                raise BuildError(f"{ctx.where}:{line}: unknown anchor {name!r}")
+            if ctx.anchors[name] != ctx.lesson_file:
+                raise BuildError(
+                    f"{ctx.where}:{line}: anchor {name!r} resolves in {ctx.anchors[name]!r} "
+                    f"but this lesson shows {ctx.lesson_file!r}"
+                )
+            tok.tag = "span"
+            tok.attrs = {"class": "rv-anchor", "data-anchor": name, "tabindex": "0"}
+            if name not in out.used_anchors:
+                out.used_anchors.append(name)
+            _close(children, i).tag = "span"
+            link_stamp = None  # an anchor phrase is a <span>, so a span in one still links
+        elif href == "!intrinsic":
+            name = _link_text(children, i)
+            url = ctx.lookup(name)
+            if url is None:
+                ctx.report.warn(f"{ctx.where}:{line}: intrinsic {name!r} is not in any vendor table")
+                tok.tag = "code"
+                tok.attrs = {}
+                _close(children, i).tag = "code"
+                link_stamp = "text"
+            else:
+                tok.attrs = _vendor_attrs(url)
+
+
+# Quiz text accepts code spans only: raw HTML, emphasis, links, entities and backslash escapes show
+# as written, and a code span is never a vendor link (an <a> inside a choice's <label> would take
+# the click meant for the radio button).
+_quiz_text = MarkdownIt("zero").enable("backticks").renderInline
+
+# The keys _quiz_html reads; any other key fails the build, so a misspelled or misplaced
+# `shuffle: false` cannot silently leave a question shuffled (#60).
+_QUIZ_KEYS: tuple[str, ...] = ("questions",)
+_QUESTION_KEYS: tuple[str, ...] = ("q", "choices", "answer", "shuffle")
+
+
+def _unknown_keys(mapping: dict, accepted: tuple[str, ...]) -> list:
+    # Source order; keys may be non-strings (YAML 1.1 loads `on:` as True).
+    return [k for k in mapping if k not in accepted]
+
+
+def _unknown_keys_message(what: str, keys: list, accepted: tuple[str, ...]) -> str:
+    noun = "unknown key" if len(keys) == 1 else "unknown keys"
+    return f"{what} has {noun} {', '.join(repr(k) for k in keys)} (accepted: {', '.join(accepted)})"
+
+
+def _quiz_html(source: str, line: int, ctx: RenderContext) -> str:
+    try:
+        data = yaml.safe_load(source) or {}
+    except yaml.YAMLError as e:
+        raise BuildError(f"{ctx.where}:{line}: quiz block is not valid YAML: {e}") from e
+    if isinstance(data, dict):
+        unknown = _unknown_keys(data, _QUIZ_KEYS)
+        if unknown:
+            # #57 adds `shuffle` to _QUIZ_KEYS, which drops this hint; #57 and #66 add their keys there.
+            hint = "; 'shuffle' goes on each question" if "shuffle" in unknown else ""
+            raise BuildError(f"{ctx.where}:{line}: {_unknown_keys_message('quiz block', unknown, _QUIZ_KEYS)}{hint}")
+    questions = data.get("questions") if isinstance(data, dict) else None
+    if not isinstance(questions, list) or not questions:
+        raise BuildError(f"{ctx.where}:{line}: quiz block needs a non-empty 'questions' list")
+    # Browsers otherwise restore checked answers (Firefox after a reload, all three engines after Back; #46); the quiz
+    # forgets by design. Fixed here, not by form.reset() in app.js: restore timing may vary by engine (unmeasured).
+    parts = ['<section class="rv-quiz">', "<h2>Knowledge check</h2>", '<form autocomplete="off">']
+    for qi, q in enumerate(questions):
+        n = qi + 1
+        if isinstance(q, dict):
+            unknown = _unknown_keys(q, _QUESTION_KEYS)
+            if unknown:
+                raise BuildError(f"{ctx.where}:{line}: {_unknown_keys_message(f'quiz question {n}', unknown, _QUESTION_KEYS)}")
+        if not isinstance(q, dict) or not isinstance(q.get("q"), str):
+            raise BuildError(f"{ctx.where}:{line}: quiz question {n} needs a 'q' string")
+        choices = q.get("choices")
+        if not isinstance(choices, list) or len(choices) < 2:
+            raise BuildError(f"{ctx.where}:{line}: quiz question {n} needs at least two choices")
+        answer = q.get("answer")
+        if not isinstance(answer, int) or isinstance(answer, bool) or not 0 <= answer < len(choices):
+            raise BuildError(f"{ctx.where}:{line}: quiz question {n} answer must be an index into choices")
+        shuffle = q.get("shuffle", True)
+        if not isinstance(shuffle, bool):
+            raise BuildError(f"{ctx.where}:{line}: quiz question {n} shuffle must be true or false")
+        # `< 3` mirrors app.js (`labels.length < 3`); test_quiz_two_choice_threshold_matches_app_js pins it.
+        if q.get("shuffle") is True and len(choices) < 3:
+            ctx.report.warn(
+                f"{ctx.where}:{line}: quiz question {n} has two choices, which always keep their order; "
+                "shuffle: true has no effect"
+            )
+        fixed = "" if shuffle else " data-fixed-order"
+        parts.append(f'<fieldset class="rv-q" data-answer="{answer}"{fixed}><legend>{n}. {_quiz_text(q["q"])}</legend>')
+        for ci, choice in enumerate(choices):
+            parts.append(f'<label><input type="radio" name="q{qi}" value="{ci}"> {_quiz_text(str(choice))}</label>')
+        parts.append('<p class="rv-q-feedback" hidden></p></fieldset>')
+    parts += [
+        '<button type="submit">Check answers</button>',
+        '<p class="rv-quiz-score" hidden></p>',
+        "</form>",
+        "</section>",
+    ]
+    return "\n".join(parts) + "\n"
+
+
+def render_markdown(body: str, ctx: RenderContext) -> RenderedLesson:
+    out = RenderedLesson(html="")
+    md = MarkdownIt("commonmark").enable("table")
+
+    # Stamp each code span with its line within the inline block, so the unlinked listing can
+    # report the span's own line (a span can sit several lines into a paragraph, or wrap).
+    def backticks(state, silent) -> bool:
+        pos, count = state.pos, len(state.tokens)
+        ok = backtick(state, silent)
+        if len(state.tokens) > count:  # only a matched span pushes; push flushes pending text first
+            state.tokens[-1].meta["rv_line"] = state.src.count("\n", 0, pos)
+        return ok
+
+    md.inline.ruler.at("backticks", backticks)
+
+    def core_rewrite(state) -> None:
+        for block in state.tokens:
+            if block.type == "inline" and block.children:
+                line = _line(block, 1, ctx)
+                _rewrite_links(block.children, line, ctx, out)
+                # Top level only: alt-text tokens nest in image.children and render as plain text.
+                for child in block.children:
+                    if child.type == "image":
+                        child.map = block.map
+                    elif child.type == "code_inline" and ctx.lookup(child.content) is None:
+                        out.unlinked_code.append((line + child.meta.get("rv_line", 0), child.content))
+
+    md.core.ruler.push("rv_links", core_rewrite)
+
+    # add_render_rule binds each function as a method of the renderer, hence `self` first.
+    default_code_inline = md.renderer.rules.get("code_inline")
+    default_fence = md.renderer.rules.get("fence")
+    default_image = md.renderer.rules.get("image")
+
+    def code_inline(self, tokens, idx, options, env):
+        content = tokens[idx].content
+        in_link = tokens[idx].meta.get("rv_in_link")
+        if in_link == "text":
+            return escapeHtml(content)
+        code = default_code_inline(tokens, idx, options, env)
+        url = None if in_link else ctx.lookup(content)
+        if url is None:
+            return code
+        attrs = "".join(f' {k}="{escapeHtml(v)}"' for k, v in _vendor_attrs(url).items())
+        return f"<a{attrs}>{code}</a>"
+
+    def fence(self, tokens, idx, options, env):
+        tok = tokens[idx]
+        if tok.info.strip() == "quiz":
+            out.quiz_count += 1
+            return _quiz_html(tok.content, _line(tok, 1, ctx), ctx)
+        return default_fence(tokens, idx, options, env)
+
+    def image(self, tokens, idx, options, env):
+        tok = tokens[idx]
+        src = tok.attrGet("src") or ""
+        if src.endswith(".dot"):
+            stem = posixpath.splitext(posixpath.basename(src))[0]
+            line = _line(tok, 1, ctx)
+            if stem not in ctx.diagrams:
+                raise BuildError(f"{ctx.where}:{line}: diagram {stem!r} ({src}) not found")
+            if stem not in out.used_diagrams:
+                out.used_diagrams.append(stem)
+            alt = html.escape(tok.content)
+            return (
+                f'<figure class="rv-diagram" id="diagram-{stem}" data-diagram="{stem}">'
+                f"{ctx.diagrams[stem]}<figcaption>{alt}</figcaption></figure>"
+            )
+        return default_image(tokens, idx, options, env)
+
+    md.add_render_rule("code_inline", code_inline)
+    md.add_render_rule("fence", fence)
+    md.add_render_rule("image", image)
+
+    tokens = md.parse(body)
+    out.html = md.renderer.render(tokens, md.options, {})
+    return out

revision_engine/narration.py

@@ -0,0 +1,276 @@
+"""Narration: authored segments -> synthesized audio + derived cue timings.
+
+Authors write words, never timestamps. `narrate` derives start/end per segment from
+the synthesized audio and records a hash of the words so `build` can detect drift.
+"""
+
+from __future__ import annotations
+
+import difflib
+import hashlib
+import io
+import json
+import os
+import re
+import shutil
+import subprocess
+import wave
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any, Protocol
+
+import yaml
+
+from revision_engine.config import DEFAULT_VOICE, _load_yaml
+from revision_engine.errors import BuildError
+from revision_engine.lesson import load_lesson
+
+DEFAULT_PAUSE = 0.4
+# A bare voice name: <voice>.onnx directly in the voices folder. Use only via VOICE_NAME.fullmatch.
+VOICE_NAME = re.compile(r"[A-Za-z0-9_][A-Za-z0-9_.-]*")
+
+
+@dataclass(frozen=True)
+class Segment:
+    text: str
+    show: tuple[str, ...]
+    diagram: str | None
+    node: str | None
+    pause: float
+
+
+@dataclass(frozen=True)
+class Narration:
+    voice: str | None
+    segments: tuple[Segment, ...]
+
+
+def load_narration(path: Path, where: str) -> Narration:
+    try:
+        data = yaml.safe_load(path.read_text(encoding="utf-8")) or {}
+    except yaml.YAMLError as e:
+        raise BuildError(f"{where}: invalid YAML: {e}") from e
+    if not isinstance(data, dict):
+        raise BuildError(f"{where}: top level must be a mapping")
+    raw = data.get("segments")
+    if not isinstance(raw, list) or not raw:
+        raise BuildError(f"{where}: 'segments' must be a non-empty list")
+    voice = data.get("voice")
+    if voice is not None and not isinstance(voice, str):
+        raise BuildError(f"{where}: 'voice' must be a string")
+    segments: list[Segment] = []
+    for i, s in enumerate(raw, start=1):
+        if not isinstance(s, dict) or not isinstance(s.get("text"), str) or not s["text"].strip():
+            raise BuildError(f"{where}: segment {i} needs a 'text' string")
+        show = s.get("show", [])
+        if isinstance(show, str):
+            show = [show]
+        if not isinstance(show, list) or not all(isinstance(x, str) for x in show):
+            raise BuildError(f"{where}: segment {i}: 'show' must be an anchor name or a list of names")
+        for key in ("diagram", "node"):
+            if key in s and not isinstance(s[key], str):
+                raise BuildError(f"{where}: segment {i}: '{key}' must be a string")
+        pause = s.get("pause", DEFAULT_PAUSE)
+        if isinstance(pause, bool) or not isinstance(pause, (int, float)) or pause < 0:
+            raise BuildError(f"{where}: segment {i}: 'pause' must be a non-negative number of seconds")
+        segments.append(
+            Segment(
+                text=" ".join(s["text"].split()),
+                show=tuple(show),
+                diagram=s.get("diagram"),
+                node=s.get("node"),
+                pause=float(pause),
+            )
+        )
+    return Narration(voice=voice, segments=tuple(segments))
+
+
+def text_hash(n: Narration) -> str:
+    payload = json.dumps([[s.text, s.pause] for s in n.segments], ensure_ascii=False, separators=(",", ":"))
+    return "sha256:" + hashlib.sha256(payload.encode("utf-8")).hexdigest()
+
+
+class Synthesizer(Protocol):
+    def synthesize(self, text: str) -> tuple[int, bytes]:
+        """Return (sample_rate, 16-bit mono little-endian PCM) for one segment."""
+
+
+class SilentSynthesizer:
+    """Deterministic stand-in: silence whose length grows with the text. For tests and fixtures."""
+
+    def __init__(self, rate: int = 8000, seconds_per_char: float = 0.05) -> None:
+        self.rate = rate
+        self.seconds_per_char = seconds_per_char
+
+    def synthesize(self, text: str) -> tuple[int, bytes]:
+        frames = int(round(len(text) * self.seconds_per_char * self.rate))
+        return self.rate, b"\x00\x00" * frames
+
+
+class PiperSynthesizer:
+    """Runs the `piper` command with a voice model file; text on stdin, raw PCM on stdout."""
+
+    def __init__(self, model: Path) -> None:
+        if shutil.which("piper") is None:
+            raise BuildError("piper is not installed or not on PATH (pip install piper-tts)")
+        if not model.is_file():
+            raise BuildError(f"piper voice model not found: {model}")
+        self.model = model
+        self.rate = _piper_sample_rate(model)
+
+    def synthesize(self, text: str) -> tuple[int, bytes]:
+        proc = subprocess.run(
+            ["piper", "--model", str(self.model), "--output-raw"],
+            input=text.encode("utf-8"),
+            capture_output=True,
+            check=False,
+        )
+        if proc.returncode != 0:
+            raise BuildError(f"piper failed: {proc.stderr.decode('utf-8', 'replace').strip()}")
+        return self.rate, proc.stdout
+
+
+def _piper_sample_rate(model: Path) -> int:
+    cfg = model.with_suffix(model.suffix + ".json")
+    if not cfg.is_file():
+        raise BuildError(f"piper voice config not found: {cfg}")
+    data = json.loads(cfg.read_text(encoding="utf-8"))
+    return int(data["audio"]["sample_rate"])
+
+
+def _write_wav(path: Path, rate: int, pcm: bytes) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    buf = io.BytesIO()
+    with wave.open(buf, "wb") as w:
+        w.setnchannels(1)
+        w.setsampwidth(2)
+        w.setframerate(rate)
+        w.writeframes(pcm)
+    path.write_bytes(buf.getvalue())
+
+
+def narrate(lesson_dir: Path, synth: Synthesizer, voice: str, media_name: str = "narration.wav") -> dict:
+    where = f"{lesson_dir.name}/narration.yaml"
+    n = load_narration(lesson_dir / "narration.yaml", where)
+    rate: int | None = None
+    pcm = bytearray()
+    cues_segments: list[dict[str, Any]] = []
+    for seg in n.segments:
+        seg_rate, audio = synth.synthesize(seg.text)
+        if rate is None:
+            rate = seg_rate
+        elif seg_rate != rate:
+            raise BuildError(f"{where}: synthesizer changed sample rate mid-lesson ({rate} -> {seg_rate})")
+        pcm += b"\x00\x00" * int(round(seg.pause * rate))
+        start = len(pcm) / 2 / rate
+        pcm += audio
+        end = len(pcm) / 2 / rate
+        entry: dict[str, Any] = {"start": round(start, 3), "end": round(end, 3), "text": seg.text}
+        if seg.show:
+            entry["show"] = list(seg.show)
+        if seg.diagram:
+            entry["diagram"] = seg.diagram
+        if seg.node:
+            entry["node"] = seg.node
+        cues_segments.append(entry)
+    assert rate is not None
+    _write_wav(lesson_dir / "media" / media_name, rate, bytes(pcm))
+    cues = {
+        "media": f"media/{media_name}",
+        "voice": voice,
+        "text_hash": text_hash(n),
+        "segments": cues_segments,
+    }
+    (lesson_dir / "cues.json").write_text(
+        json.dumps(cues, indent=2, sort_keys=True) + "\n", encoding="utf-8", newline="\n"
+    )
+    return cues
+
+
+def load_cues(path: Path, where: str) -> dict:
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except json.JSONDecodeError as e:
+        raise BuildError(f"{where}: invalid JSON: {e}") from e
+    if not isinstance(data, dict):
+        raise BuildError(f"{where}: top level must be an object")
+    for key in ("media", "text_hash"):
+        if not isinstance(data.get(key), str):
+            raise BuildError(f"{where}: '{key}' must be a string")
+    if not isinstance(data.get("segments"), list):
+        raise BuildError(f"{where}: 'segments' must be a list")
+    for i, s in enumerate(data["segments"], start=1):
+        if not isinstance(s, dict) or not all(isinstance(s.get(k), (int, float)) for k in ("start", "end")):
+            raise BuildError(f"{where}: segment {i} needs numeric 'start' and 'end'")
+        if not isinstance(s.get("text"), str):
+            raise BuildError(f"{where}: segment {i} needs a 'text' string")
+    return data
+
+
+def check_cues(n: Narration, cues: dict, where: str) -> None:
+    if cues.get("text_hash") == text_hash(n):
+        return
+    old = [s["text"] for s in cues.get("segments", [])]
+    new = [s.text for s in n.segments]
+    diff = "\n".join(difflib.unified_diff(old, new, "cues.json", "narration.yaml", lineterm="", n=1))
+    raise BuildError(
+        f"{where}: narration.yaml changed since cues.json was generated; "
+        f"rerun 'rv2 narrate' for this lesson.\n{diff}"
+    )
+
+
+def _project_voice(lesson_dir: Path) -> tuple[str, Path] | None:
+    """The ``narration.voice`` of the first revision.yaml found walking up from the lesson,
+    with the path of that revision.yaml."""
+    resolved = lesson_dir.resolve()
+    for parent in [resolved, *resolved.parents]:
+        cfg = parent / "revision.yaml"
+        if cfg.is_file():
+            data = _load_yaml(cfg)
+            narration = data.get("narration") if isinstance(data, dict) else None
+            voice = narration.get("voice") if isinstance(narration, dict) else None
+            return (voice, cfg) if isinstance(voice, str) else None
+    return None
+
+
+def resolve_voice_model(lesson_dir: Path, cli_voice: str | None, cli_model: Path | None) -> tuple[str, Path]:
+    """Pick the voice name and Piper model for ``rv2 narrate``.
+
+    Name: --voice, then narration.yaml's ``voice``, then the lesson's front matter, then the
+    project's narration.voice, then the default. Model: --model if given, else ``<voice>.onnx``
+    in $RV2_VOICES or ~/piper-voices. The returned name is what cues.json records.
+
+    The name must be a bare voice name — ASCII letters, digits, ``_``, ``-`` and ``.``, not
+    starting with ``-`` or ``.`` (VOICE_NAME); anything else is refused before it is joined into
+    a path.
+    """
+    if cli_model is not None:
+        if not cli_model.is_file():
+            raise BuildError(f"piper voice model not found: {cli_model}")
+        return cli_voice or cli_model.name.removesuffix(".onnx"), cli_model
+    voice, where = cli_voice, "--voice"
+    if voice is None and (lesson_dir / "narration.yaml").is_file():
+        where = f"{lesson_dir.name}/narration.yaml"
+        voice = load_narration(lesson_dir / "narration.yaml", where).voice
+    if voice is None and (lesson_dir / "lesson.md").is_file():
+        where = f"{lesson_dir.name}/lesson.md"
+        voice = load_lesson(lesson_dir / "lesson.md", where).voice
+    if voice is None and (project := _project_voice(lesson_dir)) is not None:
+        voice, cfg = project
+        where = f"{cfg} (narration.voice)"
+    if voice is None:
+        voice, where = DEFAULT_VOICE, "default voice"
+    if not VOICE_NAME.fullmatch(voice):
+        raise BuildError(
+            f"{where}: voice {voice!r} is not a voice name: use only ASCII letters, digits, '_', '-' "
+            "and '.', not starting with '-' or '.'. Put <voice>.onnx directly in $RV2_VOICES (or "
+            "~/piper-voices), or pass --model to use a model file elsewhere"
+        )
+    voices_dir = Path(os.environ.get("RV2_VOICES") or Path.home() / "piper-voices")
+    model = voices_dir / f"{voice}.onnx"
+    if not model.is_file():
+        raise BuildError(
+            f"voice {voice!r}: no model at {model}. Download <voice>.onnx and .onnx.json from "
+            "https://huggingface.co/rhasspy/piper-voices into that folder, or pass --model."
+        )
+    return voice, model

revision_engine/render.py

@@ -0,0 +1,119 @@
+"""Turn per-lesson build products into HTML pages, hashed assets, and site.json."""
+
+from __future__ import annotations
+
+import hashlib
+import json
+from dataclasses import dataclass
+from importlib import resources
+from pathlib import Path
+from typing import Any
+
+from jinja2 import Environment, PackageLoader, select_autoescape
+
+from revision_engine.config import Curriculum, ProjectConfig
+
+Assets = dict[str, str]
+
+_env = Environment(
+    loader=PackageLoader("revision_engine", "templates"),
+    autoescape=select_autoescape(["html", "j2"]),
+    keep_trailing_newline=True,
+)
+
+
+@dataclass(frozen=True)
+class NavLesson:
+    slug: str
+    title: str
+    href: str
+    current: bool
+
+
+@dataclass(frozen=True)
+class NavChapter:
+    slug: str
+    title: str
+    lessons: tuple[NavLesson, ...]
+
+
+@dataclass(frozen=True)
+class Variant:
+    name: str
+    label: str
+    start: int
+
+
+@dataclass(frozen=True)
+class PageModel:
+    site_title: str
+    root: str
+    assets: Assets
+    chapter_title: str
+    lesson_title: str
+    summary: str
+    nav: tuple[NavChapter, ...]
+    prev_href: str | None
+    next_href: str | None
+    file_path: str
+    commit_short: str
+    file_url: str
+    code_html: str
+    variants: tuple[Variant, ...]
+    lesson_html: str
+    media_url: str | None
+    media_kind: str | None
+    cues: list[dict[str, Any]] | None
+    rv_data: dict[str, Any]
+
+
+def _hashed_name(name: str, content: bytes) -> str:
+    stem, ext = name.rsplit(".", 1)
+    return f"{stem}.{hashlib.sha256(content).hexdigest()[:8]}.{ext}"
+
+
+def write_assets(out: Path, token_css: str) -> Assets:
+    assets_dir = out / "assets"
+    assets_dir.mkdir(parents=True, exist_ok=True)
+    static = resources.files("revision_engine").joinpath("static")
+    files = {
+        "styles.css": static.joinpath("styles.css").read_bytes(),
+        "app.js": static.joinpath("app.js").read_bytes(),
+        "tokens.css": token_css.encode("utf-8"),
+    }
+    result: Assets = {}
+    for name, content in files.items():
+        hashed = _hashed_name(name, content)
+        (assets_dir / hashed).write_bytes(content)
+        result[name] = f"assets/{hashed}"
+    return result
+
+
+def json_for_script(data: Any) -> str:
+    """JSON safe to embed inside <script type="application/json">."""
+    return json.dumps(data, sort_keys=True, separators=(",", ":")).replace("</", "<\\/")
+
+
+def render_page(model: PageModel) -> str:
+    template = _env.get_template("lesson.html.j2")
+    return template.render(m=model, rv_data_json=json_for_script(model.rv_data))
+
+
+def render_redirect(target_href: str, title: str) -> str:
+    return _env.get_template("redirect.html.j2").render(target=target_href, title=title)
+
+
+def site_index(cfg: ProjectConfig, curriculum: Curriculum) -> dict:
+    return {
+        "title": cfg.site.title,
+        "chapters": [
+            {
+                "slug": ch.slug,
+                "title": ch.title,
+                "lessons": [
+                    {"slug": le.slug, "title": le.title, "href": f"{ch.slug}/{le.slug}/"} for le in ch.lessons
+                ],
+            }
+            for ch in curriculum.chapters
+        ],
+    }