@sdelsad/commodity-desk-daily 1.0.18 → 1.13.2

package/build_page.py

@@ -0,0 +1,1237 @@
+#!/usr/bin/env python3
+"""
+Soft Commodity Trading — episode page builder.
+
+Turns an episode's markdown notes into a standalone HTML page: editorial
+layout, working audio player, light/dark toggle, a contents rail, episode
+navigation, the cumulative glossary, and one reveal per quiz answer so Q1
+can be checked without spoiling Q7.
+
+Usage:
+    python3 build_page.py --notes ep03.md --number 3 \
+        --title "Futures Plumbing and the Shape of the Curve" \
+        --dek "One sentence for under the headline." \
+        --audio-url "https://.../ep03.mp3" --duration 620 \
+        --date "Wednesday 12 August 2026" --out ep03.html
+
+The markdown is rendered generically, so the page follows whatever structure
+the notes have. Everything from the "SOLUTIONS" heading up to the next H2 is
+folded, one <details> per answer.
+
+Two files are picked up automatically when they sit in the working directory
+(both optional — the page degrades cleanly without them):
+
+    covered.md    the running episode log, written by publish_episode.py.
+                  Gives the page its previous/next links and its archive.
+    glossary.md   the cumulative glossary, also written at publish time.
+                  Rendered on the page in a collapsed, filterable section.
+
+Override or disable them with --covered / --glossary.
+
+Zero runtime dependencies: standard library only, and the page it writes has
+no CDN, no web font and no external script.
+"""
+import argparse
+import html
+import json
+import os
+import re
+import sys
+
+try:
+    import chart as chartlib
+except ImportError:                                   # chart.py sits next to us
+    sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+    try:
+        import chart as chartlib
+    except ImportError:
+        chartlib = None
+
+CHART_SPECS = []          # every chart the page rendered, in order
+HEADINGS = []             # (level, id, text) for the contents rail
+
+SHOW = "Soft Commodity Trading"
+SLUG = "commodity-desk-daily"          # frozen: npm package, bucket folder, URLs
+BUCKET = "https://storage.googleapis.com/podcast-audio-2647223968"
+FEED_URL = f"{BUCKET}/{SLUG}/feed.xml"
+SITE_URL = f"{BUCKET}/index.html"
+COVER_URL = ("https://cdn.jsdelivr.net/npm/@sdelsad/"
+             "commodity-desk-daily@1.0.15/cover.jpg")
+AUTHOR = "Sébastien Delsad"
+
+
+def page_url(number):
+    return f"{BUCKET}/{SLUG}/ep{number:02d}.html"
+
+
+# ------------------------------------------------------------ markdown ------
+
+def inline(text):
+    """Inline markdown → HTML, on already-escaped text."""
+    text = re.sub(r"`([^`]+)`", r"<code>\1</code>", text)
+    text = re.sub(r"\*\*(.+?)\*\*", r"<strong>\1</strong>", text)
+    text = re.sub(r"(?<![\w*])\*(?!\s)(.+?)(?<!\s)\*(?![\w*])", r"<em>\1</em>", text)
+    text = re.sub(r"(?<![\w_])_(?!\s)(.+?)(?<!\s)_(?![\w_])", r"<em>\1</em>", text)
+    text = re.sub(r"\[(.+?)\]\((.+?)\)", r'<a href="\2">\1</a>', text)
+    return text
+
+
+FENCE = "```"
+
+_SLUGS = {}
+
+
+def slug(text, prefix=""):
+    """A stable, readable id for a heading."""
+    base = re.sub(r"<[^>]+>", "", text)
+    base = html.unescape(base).lower()
+    base = re.sub(r"[^a-z0-9]+", "-", base).strip("-") or "section"
+    base = prefix + base[:48].rstrip("-")
+    n = _SLUGS.get(base, 0) + 1
+    _SLUGS[base] = n
+    return base if n == 1 else f"{base}-{n}"
+
+
+# ------------------------------------------------------------- tables -------
+
+# "$4.77¾ /bu", "−0.6%", "+21½¢", "1,653", "12.5"
+NUMERIC = re.compile(
+    r"^[~≈]?[+\-−±]?\s*[$€£¥]?\s*\d[\d,]*(?:\.\d+)?[¼½¾⅓⅔⅛⅜⅝⅞]?"
+    r"\s*(?:/?\s*[A-Za-z%¢$€£]{1,5})?\s*$")
+SIGNED = re.compile(r"^([+\-−±])\s*(.+)$")
+BLANKS = {"", "—", "–", "-", "n/a", "na"}
+MOVE_HEADS = {"change", "chg", "move", "moves", "δ", "delta", "d/d", "w/w",
+              "m/m", "y/y", "net", "net change", "+/-", "on the day", "session"}
+FLAT_WORDS = ("unchanged", "unch", "flat", "steady", "nil", "level")
+
+
+def _clean(cell):
+    return re.sub(r"<[^>]+>", "", cell).strip()
+
+
+def is_numeric(cell):
+    c = _clean(cell)
+    return bool(c) and c.lower() not in BLANKS and bool(NUMERIC.match(c))
+
+
+def classify_move(txt):
+    """(display text, 'up' | 'down' | 'flat' | None) for one price move.
+
+    The sign is made explicit here rather than left to colour alone, so the
+    table still reads correctly in monochrome, in print and for a reader who
+    cannot distinguish the two hues. build_email.py imports this, so the page
+    and the e-mail never disagree about which way a market went.
+    """
+    txt = (txt or "").strip()
+    low = txt.lower()
+    if not txt or low in BLANKS:
+        return txt, None
+    if any(w in low for w in FLAT_WORDS):
+        return txt, "flat"
+    m = SIGNED.match(txt)
+    if m:
+        sign, rest = m.group(1), m.group(2)
+        if sign == "±":
+            return txt, "flat"
+        if sign in "-−":
+            return "−" + rest, "down"          # hyphen-minus → a real minus
+        return txt, "up"
+    if re.match(r"^[$€£¥]?\s*0(\.0+)?\s*[%¢]?$", txt):
+        return txt, "flat"
+    if NUMERIC.match(txt):
+        return "+" + txt, "up"                 # a rise must never read as a level
+    return txt, None
+
+
+def move_cell(cell_html):
+    """Wrap a move in a span carrying up/down/flat."""
+    txt = _clean(cell_html)
+    shown, direction = classify_move(txt)
+    if direction is None:
+        return cell_html
+    if shown != txt:
+        cell_html = cell_html.replace(txt, shown, 1)
+    return f'<span class="mv {direction}">{cell_html}</span>'
+
+
+def table_html(head, rows):
+    """A table that survives a 390px screen: it scrolls inside its own box,
+    figures are tabular and right-aligned, and moves carry a sign and a hue."""
+    ncol = max([len(head)] + [len(r) for r in rows]) if rows else len(head)
+    numeric, moves = [], []
+    for c in range(ncol):
+        col = [r[c] for r in rows if c < len(r)]
+        filled = [x for x in col if _clean(x).lower() not in BLANKS]
+        title = _clean(head[c]).lower().strip(" .:") if c < len(head) else ""
+        hit = sum(1 for x in filled if is_numeric(x))
+        numeric.append(bool(filled) and hit >= max(1, int(len(filled) * 0.6)))
+        signed = sum(1 for x in filled if SIGNED.match(_clean(x))
+                     or any(w in _clean(x).lower() for w in FLAT_WORDS))
+        moves.append(title in MOVE_HEADS
+                     or (bool(filled) and signed == len(filled)))
+
+    th = []
+    for c, cell in enumerate(head):
+        cls = ' class="num"' if (numeric[c] or moves[c]) else ""
+        th.append(f"<th{cls}>{inline(html.escape(cell))}</th>")
+    body = []
+    for r in rows:
+        tds = []
+        for c, cell in enumerate(r):
+            rendered = inline(html.escape(cell))
+            klass = []
+            if c < ncol and (numeric[c] or moves[c]):
+                klass.append("num")
+            if c < ncol and moves[c]:
+                rendered = move_cell(rendered)
+            cls = f' class="{" ".join(klass)}"' if klass else ""
+            tds.append(f"<td{cls}>{rendered}</td>")
+        body.append("<tr>" + "".join(tds) + "</tr>")
+    return ('<div class="tablewrap" tabindex="0" role="region" '
+            'aria-label="Table, scrolls sideways">'
+            f'<table><thead><tr>{"".join(th)}</tr></thead>'
+            f'<tbody>{"".join(body)}</tbody></table></div>')
+
+
+# ------------------------------------------------------------- render -------
+
+def render(md):
+    """A deliberately small markdown renderer: headings, lists, tables,
+    blockquotes, rules, paragraphs. Enough for the show's notes, with no
+    third-party dependency to install every morning."""
+    out, lines, i = [], md.split("\n"), 0
+    while i < len(lines):
+        raw = lines[i]
+        line = raw.rstrip()
+        stripped = line.strip()
+
+        if not stripped:
+            i += 1
+            continue
+
+        if stripped.startswith(FENCE + "chart"):
+            # a ```chart fenced block: JSON in, an <svg> figure out
+            body, i = [], i + 1
+            while i < len(lines) and not lines[i].strip().startswith(FENCE):
+                body.append(lines[i])
+                i += 1
+            i += 1                                    # skip the closing fence
+            try:
+                spec = json.loads("\n".join(body))
+            except ValueError as exc:
+                out.append(f'<p class="charterr">Chart skipped: {html.escape(str(exc))}</p>')
+                continue
+            CHART_SPECS.append(spec)
+            if chartlib:
+                out.append(chartlib.figure_html(spec))
+            continue
+
+        if stripped.startswith("<"):            # pass through raw HTML
+            out.append(stripped)
+            i += 1
+            continue
+
+        if re.match(r"^(-{3,}|\*{3,})$", stripped):
+            out.append("<hr>")
+            i += 1
+            continue
+
+        m = re.match(r"^(#{1,6})\s+(.*)$", stripped)
+        if m:
+            level = len(m.group(1))
+            text = inline(html.escape(m.group(2)))
+            if level in (2, 3):
+                hid = slug(m.group(2))
+                HEADINGS.append((level, hid, re.sub(r"<[^>]+>", "", text)))
+                anchor = (f'<a class="anchor" href="#{hid}" aria-label="Link to '
+                          f'this section">#</a>')
+                out.append(f'<h{level} id="{hid}">{text}{anchor}</h{level}>')
+            else:
+                out.append(f"<h{level}>{text}</h{level}>")
+            i += 1
+            continue
+
+        if stripped.startswith("|") and i + 1 < len(lines) and \
+                re.match(r"^\|[\s:|-]+\|$", lines[i + 1].strip()):
+            head = [c.strip() for c in stripped.strip("|").split("|")]
+            i += 2
+            rows = []
+            while i < len(lines) and lines[i].strip().startswith("|"):
+                rows.append([c.strip() for c in lines[i].strip().strip("|").split("|")])
+                i += 1
+            out.append(table_html(head, rows))
+            continue
+
+        if re.match(r"^[-*]\s+", stripped):
+            items = []
+            while i < len(lines) and re.match(r"^[-*]\s+", lines[i].strip()):
+                items.append(inline(html.escape(re.sub(r"^[-*]\s+", "", lines[i].strip()))))
+                i += 1
+            out.append("<ul>" + "".join(f"<li>{it}</li>" for it in items) + "</ul>")
+            continue
+
+        if re.match(r"^\d+[.)]\s+", stripped):
+            items = []
+            while i < len(lines) and re.match(r"^\d+[.)]\s+", lines[i].strip()):
+                items.append(inline(html.escape(re.sub(r"^\d+[.)]\s+", "", lines[i].strip()))))
+                i += 1
+            out.append("<ol>" + "".join(f"<li>{it}</li>" for it in items) + "</ol>")
+            continue
+
+        if stripped.startswith(">"):
+            quote = []
+            while i < len(lines) and lines[i].strip().startswith(">"):
+                quote.append(inline(html.escape(lines[i].strip().lstrip("> ").rstrip())))
+                i += 1
+            out.append("<blockquote>" + "<br>".join(quote) + "</blockquote>")
+            continue
+
+        para = []
+        while i < len(lines) and lines[i].strip() and \
+                not re.match(r"^(#{1,6}\s|[-*]\s|\d+[.)]\s|\||>|<|-{3,})", lines[i].strip()):
+            para.append(lines[i].strip())
+            i += 1
+        if para:
+            out.append("<p>" + inline(html.escape(" ".join(para))) + "</p>")
+        else:
+            i += 1
+    return "\n".join(out)
+
+
+# ----------------------------------------------------- quiz and answers -----
+
+# Episodes have used "**Q1.**", "**Q1 — A title.**" and "**S1.**" over the
+# months. Match the family, not one spelling of it.
+END = r"[.)::—–-]"
+QUESTION_MARK = re.compile(rf"<p>(<strong>\s*Q(\d+)\s*(?={END}|\s|</strong>))")
+ANSWER_SPLIT = re.compile(rf"(?=<p><strong>\s*[AS]\d+\s*(?:{END}|</strong>))")
+ANSWER_HEAD = re.compile(
+    rf"^(<p>)<strong>\s*[AS](\d+)\s*{END}?\s*(.*?)</strong>\s*", re.DOTALL)
+
+
+def number_questions(body_html):
+    """Give every quiz question an id, so an answer can link back to it."""
+    return QUESTION_MARK.sub(
+        lambda m: f'<p id="q{m.group(2)}" class="qq">{m.group(1)}', body_html)
+
+
+def split_answer(part):
+    """(number, html) for one answer, with its "A1." marker removed — the
+    reveal button already says which question it belongs to."""
+    m = ANSWER_HEAD.match(part)
+    if not m:
+        return None, part
+    rest = m.group(3).strip()
+    head = m.group(1) + (f"<strong>{rest}</strong> " if rest else "")
+    return m.group(2), head + part[m.end():]
+
+
+def find_section(body_html, word):
+    """Locate an <h2> by its text, and return (start, end_of_heading, end)."""
+    for m in re.finditer(r"<h2\b[^>]*>.*?</h2>", body_html, re.DOTALL):
+        if word.lower() in re.sub(r"<[^>]+>", "", m.group(0)).lower():
+            rest = body_html[m.end():]
+            nxt = re.search(r"<h2\b", rest)
+            end = m.end() + (nxt.start() if nxt else len(rest))
+            return m.start(), m.end(), end
+    return None
+
+
+def fold_solutions(body_html):
+    """Fold the solutions one answer at a time.
+
+    A single <details> for all seven answers means checking Q1 burns Q2 to Q7.
+    Each answer gets its own reveal, and a link back to its question.
+    """
+    found = find_section(body_html, "solutions")
+    if not found:
+        return body_html
+    start, head_end, end = found
+    inner = body_html[head_end:end]
+    inner = re.sub(r"<p>\s*(<br>)?\s*</p>", "", inner)
+
+    parts = ANSWER_SPLIT.split(inner)
+    numbered = [split_answer(p) for p in parts]
+    lead = "".join(p for n, p in numbered if n is None)
+    answers = [(n, p) for n, p in numbered if n is not None]
+    if not answers:
+        folded = ('<details class="soln"><summary>Reveal the solutions</summary>'
+                  f'<div class="solnbody">{inner}</div></details>')
+        return body_html[:head_end] + folded + body_html[end:]
+
+    blocks = [lead] if lead.strip() else []
+    del parts, numbered
+    blocks.append('<p class="secnote">One reveal per question — check your '
+                  'answer to Q1 without spoiling the rest.</p>'
+                  '<div class="solnbar"><button type="button" class="ghost" '
+                  'data-solnall="open">Reveal all</button>'
+                  '<button type="button" class="ghost" data-solnall="close">'
+                  'Hide all</button></div>')
+    for n, part in answers:
+        blocks.append(
+            f'<details class="soln" id="a{n}">'
+            f'<summary><span class="qn">Q{n}</span>'
+            f'<span class="sl">Reveal the answer</span></summary>'
+            f'<div class="solnbody">{part}'
+            f'<p class="backq"><a href="#q{n}">↑ Back to question {n}</a></p>'
+            f"</div></details>")
+    return body_html[:head_end] + "\n".join(blocks) + body_html[end:]
+
+
+def tidy_rules(body_html):
+    """A rule immediately above a section heading double-rules it: the heading
+    already carries one. Drop the rule and keep the break."""
+    return re.sub(r"<hr>\s*(?=<h2\b)", "", body_html)
+
+
+def strip_spoiler_banner(md):
+    """The email needs a scroll warning; the page has a button instead.
+
+    Normalise whatever spoiler heading the notes used into a plain
+    "## Solutions" so the folding step below can find it reliably.
+    """
+    md = re.sub(r"^#{1,6}\s*.*SOLUTIONS.*$", "## Solutions", md,
+                flags=re.MULTILINE | re.IGNORECASE)
+    md = re.sub(r"^\s*(▼|▲).*$", "", md, flags=re.MULTILINE)
+    md = re.sub(r"^\s*(<br\s*/?>\s*)+$", "", md, flags=re.MULTILINE)
+    # the e-mail pads its spoiler gap with &nbsp; lines; on the page they would
+    # print as the literal text "&nbsp;"
+    md = re.sub(r"^\s*(&nbsp;\s*)+$", "", md, flags=re.MULTILINE)
+    md = md.replace("<br><br>", "")
+    return md
+
+
+# ------------------------------------------------- continuity artefacts -----
+
+SEARCH_NEAR = ""          # the --notes path, so siblings can be found
+
+
+def find_file(explicit, *names):
+    """Explicit path wins; otherwise look in the cwd and next to the notes."""
+    if explicit:
+        return explicit if os.path.exists(explicit) else None
+    near = os.path.dirname(os.path.abspath(SEARCH_NEAR)) if SEARCH_NEAR else ""
+    for name in names:
+        for candidate in (name, os.path.join(near, name) if near else ""):
+            if candidate and os.path.exists(candidate):
+                return candidate
+    return None
+
+
+def load_covered(path):
+    """Episode numbers and titles out of covered.md, for navigation."""
+    eps = {}
+    if not path:
+        return eps
+    try:
+        text = open(path, encoding="utf-8").read()
+    except OSError:
+        return eps
+    for line in text.splitlines():
+        m = re.match(r"^-\s+\*\*Ep (\d+)\*\*[^—-]*[—-]\s*\*(.+?)\*", line.strip())
+        if m:
+            eps[int(m.group(1))] = m.group(2).strip()
+    return eps
+
+
+def load_glossary(path):
+    """(term, definition, episode) out of glossary.md."""
+    terms = []
+    if not path:
+        return terms
+    try:
+        text = open(path, encoding="utf-8").read()
+    except OSError:
+        return terms
+    for line in text.splitlines():
+        m = re.match(r"^-\s+\*\*(.+?)\*\*\s+—\s+(.+?)(?:\s+_\(ep (\d+)\)_)?$",
+                     line.strip())
+        if m:
+            terms.append((m.group(1).strip(), m.group(2).strip(), m.group(3) or ""))
+    return terms
+
+
+def glossary_html(terms, number):
+    """The glossary as it stood on the day this episode aired.
+
+    An episode page carries the vocabulary the show had introduced *by then* —
+    episode 1 shows episode 1's terms, episode 5 shows one to five. A page
+    dated Monday listing a word first used on Friday reads as a leak, and it
+    is no help to someone working through the series in order. Chips filter
+    the list down to any single episode.
+    """
+    if not terms:
+        return ""
+    upto = [(t, d, ep) for t, d, ep in terms
+            if not ep or int(ep) <= number]
+    if not upto:
+        return ""
+    rows, counts = [], {}
+    for term, definition, ep in upto:
+        counts[ep] = counts.get(ep, 0) + 1
+        tag = (f'<span class="gep{" now" if ep == str(number) else ""}">ep {ep}</span>'
+               if ep else "")
+        rows.append(f'<div class="gterm" data-ep="{ep}"><dt>{html.escape(term)}</dt>'
+                    f'<dd>{inline(html.escape(definition))} {tag}</dd></div>')
+
+    # episode one has nothing to filter between: "All 37 / Ep 1 37" is noise
+    seen_eps = sorted(int(e) for e in counts if e)
+    chips = []
+    if len(seen_eps) > 1:
+        chips.append(f'<button type="button" class="gchip on" data-gep="all">'
+                     f'All<span class="gn">{len(upto)}</span></button>')
+        for n in seen_eps:
+            chips.append(f'<button type="button" class="gchip" data-gep="{n}">'
+                         f'Ep {n}<span class="gn">{counts[str(n)]}</span></button>')
+
+    hid = slug("Glossary")
+    HEADINGS.append((2, hid, "Glossary"))
+    return ('<section class="glossec">'
+            f'<h2 id="{hid}">Glossary<a class="anchor" href="#{hid}" '
+            f'aria-label="Link to this section">#</a></h2>'
+            '<p class="secnote">Every unit, convention and desk expression the '
+            f'show had introduced by episode {number}. Nothing said in the '
+            'audio should ever be unrecoverable.</p>'
+            f'<details class="gloss"><summary>Open the glossary'
+            f'<span class="sl">{len(upto)} terms</span></summary>'
+            '<div class="glossbody">'
+            '<label class="gsearch"><span class="vh">Search the glossary</span>'
+            '<input type="search" id="gfilter" placeholder="Search terms…" '
+            'autocomplete="off"></label>'
+            + (f'<div class="gchips" role="group" aria-label="Filter by episode">'
+               f'{"".join(chips)}</div>' if chips else "") +
+            f'<dl id="glist">{"".join(rows)}</dl>'
+            '<p class="gnone" hidden>No term matches that.</p>'
+            "</div></details></section>")
+
+
+def epnav_html(eps, number):
+    """Previous / next / archive. Every page was an orphan before this."""
+    prev_n = max([n for n in eps if n < number], default=None)
+    next_n = min([n for n in eps if n > number], default=None)
+    if prev_n is None and number > 1:
+        prev_n = number - 1
+    bits = ['<nav class="epnav" aria-label="Episodes">']
+    if prev_n:
+        title = html.escape(eps.get(prev_n, f"Episode {prev_n}"))
+        bits.append(f'<a class="epprev" href="ep{prev_n:02d}.html">'
+                    f'<span class="dir">← Previous</span>'
+                    f'<span class="ept">{title}</span>'
+                    f'<span class="epn">Episode {prev_n}</span></a>')
+    if next_n:
+        title = html.escape(eps.get(next_n, f"Episode {next_n}"))
+        bits.append(f'<a class="epnext" href="ep{next_n:02d}.html">'
+                    f'<span class="dir">Next →</span>'
+                    f'<span class="ept">{title}</span>'
+                    f'<span class="epn">Episode {next_n}</span></a>')
+    bits.append("</nav>")
+
+    if eps:
+        items = []
+        for n in sorted(eps):
+            here = ' class="here" aria-current="page"' if n == number else ""
+            items.append(f'<li{here}><a href="ep{n:02d}.html">'
+                         f'<b>{n:02d}</b> {html.escape(eps[n])}</a></li>')
+        bits.append('<details class="archive"><summary>Jump to an episode'
+                    f'<span class="sl">{len(eps)} so far</span></summary>'
+                    f'<ol class="arclist">{"".join(items)}</ol></details>')
+    return "\n".join(bits)
+
+
+# --------------------------------------------------------- head metadata ----
+
+MONTHS = {m: i for i, m in enumerate(
+    ["january", "february", "march", "april", "may", "june", "july",
+     "august", "september", "october", "november", "december"], 1)}
+
+
+def iso_date(text):
+    """'Friday 14 August 2026' → '2026-08-14'. Returns '' if unparseable."""
+    if not text:
+        return ""
+    if re.match(r"^\d{4}-\d{2}-\d{2}$", text.strip()):
+        return text.strip()
+    m = re.search(r"(\d{1,2})\s+([A-Za-z]+)\s+(\d{4})", text)
+    if not m:
+        m = re.search(r"([A-Za-z]+)\s+(\d{1,2}),?\s+(\d{4})", text)
+        if not m:
+            return ""
+        day, month, year = m.group(2), m.group(1), m.group(3)
+    else:
+        day, month, year = m.group(1), m.group(2), m.group(3)
+    mo = MONTHS.get(month.lower())
+    if not mo:
+        return ""
+    return f"{int(year):04d}-{mo:02d}-{int(day):02d}"
+
+
+def toc_html():
+    if len(HEADINGS) < 3:
+        return ""
+    items = []
+    for level, hid, text in HEADINGS:
+        cls = "t2" if level == 2 else "t3"
+        items.append(f'<li class="{cls}"><a href="#{hid}">{text}</a></li>')
+    return ('<nav class="toc" id="toc" aria-label="Contents">'
+            '<p class="tochead">Contents</p>'
+            f'<ol>{"".join(items)}</ol></nav>')
+
+
+def jsonld(args, dek, iso, number):
+    duration = f"PT{args.duration // 60}M{args.duration % 60:02d}S"
+    data = {
+        "@context": "https://schema.org",
+        "@type": "PodcastEpisode",
+        "url": page_url(number),
+        "name": f"Ep {number} — {args.title}",
+        "episodeNumber": number,
+        "duration": duration,
+        "description": dek or f"Episode {number} of {SHOW}.",
+        "image": COVER_URL,
+        "inLanguage": "en",
+        "author": {"@type": "Person", "name": AUTHOR},
+        "associatedMedia": {
+            "@type": "MediaObject",
+            "contentUrl": args.audio_url,
+            "encodingFormat": "audio/mpeg",
+        },
+        "partOfSeries": {
+            "@type": "PodcastSeries",
+            "name": SHOW,
+            "url": SITE_URL,
+            "image": COVER_URL,
+            "webFeed": FEED_URL,
+        },
+    }
+    if iso:
+        data["datePublished"] = iso
+    return json.dumps(data, ensure_ascii=False, indent=2)
+
+
+# ------------------------------------------------------------- template -----
+
+CSS = """
+:root{
+  --ink:#16110c; --ink-soft:#4a4238; --line:#e3ddd2; --paper:#faf7f1;
+  --accent:#1d4032; --gold:#a8813c; --spoiler:#8a2f2f;
+  --tint:rgba(128,110,70,.07); --tint-2:rgba(128,110,70,.045);
+  --up:#215c44; --down:#8a2f2f; --shadow:rgba(22,17,12,.14);
+  --sans:ui-sans-serif,system-ui,-apple-system,"Segoe UI",Roboto,sans-serif;
+  --serif:Georgia,"Iowan Old Style","Times New Roman",serif;
+  --col:680px;
+}
+html[data-theme="dark"]{
+  --ink:#ece6dc; --ink-soft:#a49c90; --line:#2f2a24; --paper:#14110e;
+  --accent:#7fae95; --gold:#c9a45c; --spoiler:#d98a8a;
+  --tint:rgba(200,180,130,.06); --tint-2:rgba(200,180,130,.035);
+  --up:#7fae95; --down:#d98a8a; --shadow:rgba(0,0,0,.55);
+  color-scheme:dark;
+}
+*{box-sizing:border-box}
+html{scroll-behavior:smooth;scroll-padding-top:64px}
+html,body{transition:background-color .25s ease,color .25s ease}
+body{margin:0;background:var(--paper);color:var(--ink);
+     font:18px/1.72 var(--serif);-webkit-font-smoothing:antialiased;
+     text-rendering:optimizeLegibility}
+.wrap{max-width:var(--col);margin:0 auto;padding:0 24px 40px}
+.vh{position:absolute;width:1px;height:1px;overflow:hidden;clip:rect(0 0 0 0);
+    white-space:nowrap}
+
+/* ---------- reading progress ---------- */
+#bar{position:fixed;top:0;left:0;height:2px;width:0;z-index:30;
+     background:var(--gold);transition:width .12s linear}
+
+/* ---------- masthead ---------- */
+header{padding:52px 0 30px}
+.masthead{display:flex;justify-content:space-between;align-items:baseline;gap:10px 16px;
+          flex-wrap:wrap;
+          padding-bottom:12px;border-bottom:1px solid var(--ink);
+          font:600 13px/1 var(--sans);letter-spacing:.13em;text-transform:uppercase}
+.masthead a{color:inherit;text-decoration:none}
+.masthead .epno{color:var(--gold);letter-spacing:.1em}
+.mastright{display:flex;align-items:baseline;gap:16px;white-space:nowrap}
+/* the show name is a link too, but it reads as a title — this is the one that
+   looks clickable, at both ends of the page */
+.homelink{color:var(--ink-soft);border-bottom:1px solid var(--line);
+          padding-bottom:2px;transition:color .2s,border-color .2s}
+.homelink:hover{color:var(--accent);border-color:var(--accent)}
+.tohome{margin:0 0 8px;font:14px/1.6 var(--sans)}
+.tohome a{color:var(--ink-soft);text-decoration:none;
+          border-bottom:1px solid var(--line);padding-bottom:2px;
+          transition:color .2s,border-color .2s}
+.tohome a:hover{color:var(--accent);border-color:var(--accent)}
+h1{font-size:clamp(31px,5.6vw,44px);line-height:1.12;margin:26px 0 0;
+   letter-spacing:-.017em;font-weight:400;text-wrap:balance}
+.dek{color:var(--ink-soft);font-size:20px;line-height:1.5;margin:16px 0 0;
+     max-width:34em;text-wrap:pretty}
+.meta{margin-top:22px;font:12.5px/1.6 var(--sans);color:var(--ink-soft);
+      letter-spacing:.05em;text-transform:uppercase}
+.meta b{font-weight:600;color:var(--ink)}
+
+/* ---------- listen ---------- */
+.listen{margin-top:26px;border:1px solid var(--line);border-radius:12px;
+        background:var(--tint-2);padding:16px 18px 14px}
+audio{width:100%;height:38px;display:block}
+.listenrow{display:flex;flex-wrap:wrap;gap:8px 16px;align-items:center;
+           margin-top:12px;font:12.5px/1 var(--sans);color:var(--ink-soft)}
+.listenrow a{color:var(--ink-soft);text-decoration:none;border-bottom:1px solid var(--line)}
+.listenrow a:hover{color:var(--accent);border-color:var(--accent)}
+.rates{display:flex;gap:6px;margin-right:auto}
+.rate{background:none;border:1px solid var(--line);color:var(--ink-soft);
+      border-radius:99px;padding:4px 10px;cursor:pointer;
+      font:600 11.5px/1 var(--sans);letter-spacing:.04em;transition:all .2s}
+.rate:hover{border-color:var(--gold);color:var(--ink)}
+.rate[aria-pressed="true"]{background:var(--ink);color:var(--paper);border-color:var(--ink)}
+
+/* ---------- contents ---------- */
+.toc{margin:34px 0 6px;padding:16px 0 4px;border-top:1px solid var(--line);
+     border-bottom:1px solid var(--line)}
+.tochead{font:600 11px/1 var(--sans);letter-spacing:.18em;text-transform:uppercase;
+         color:var(--gold);margin:0 0 12px}
+.toc ol{list-style:none;margin:0 0 12px;padding:0;
+        font:14.5px/1.5 var(--sans);columns:2;column-gap:26px}
+.toc li{margin:0 0 7px;break-inside:avoid}
+.toc li.t3{padding-left:12px;font-size:13.5px}
+.toc a{color:var(--ink-soft);text-decoration:none;border-bottom:1px solid transparent}
+.toc a:hover{color:var(--ink);border-color:var(--gold)}
+.toc li.on>a{color:var(--ink);font-weight:600}
+
+/* ---------- body ---------- */
+main{padding-top:8px}
+h2{font:400 27px/1.25 var(--serif);color:var(--gold);margin:56px 0 18px;
+   font-variant-caps:all-small-caps;letter-spacing:.045em;
+   padding-bottom:9px;border-bottom:1px solid var(--line)}
+h3{font-size:23px;line-height:1.3;margin:38px 0 10px;letter-spacing:-.012em;
+   font-weight:400}
+h4{font:600 17px/1.4 var(--sans);margin:26px 0 6px;letter-spacing:-.005em}
+p{margin:0 0 18px}
+h2+p,h3+p,h4+p{margin-top:0}
+ul,ol{margin:0 0 18px;padding-left:24px}
+li{margin:0 0 9px}
+li::marker{color:var(--gold)}
+strong{font-weight:700}
+a{color:var(--accent);text-underline-offset:2px;text-decoration-thickness:1px}
+.anchor{float:right;margin-left:12px;color:var(--line);text-decoration:none;
+        font:400 16px/1 var(--sans);opacity:0;transition:opacity .2s}
+h2:hover .anchor,h3:hover .anchor,.anchor:focus{opacity:1;color:var(--gold)}
+.secnote{font:14.5px/1.6 var(--sans);color:var(--ink-soft);margin:-4px 0 18px}
+code{background:var(--tint);padding:1px 5px;border-radius:3px;
+     font:15px/1 ui-monospace,Menlo,Consolas,monospace}
+blockquote{border-left:2px solid var(--gold);margin:26px 0;padding:6px 0 6px 20px;
+           font-style:italic;color:var(--ink-soft);font-size:17.5px}
+blockquote strong{font-style:normal;color:var(--ink);font-weight:600}
+hr{border:none;border-top:1px solid var(--line);margin:40px 0}
+.charterr{color:var(--spoiler);font:14px/1.5 var(--sans)}
+
+/* ---------- tables ---------- */
+.tablewrap{margin:26px 0;overflow-x:auto;overscroll-behavior-x:contain;
+  background:
+    linear-gradient(to right,var(--paper) 34%,rgba(255,255,255,0)) left center,
+    linear-gradient(to left,var(--paper) 34%,rgba(255,255,255,0)) right center,
+    radial-gradient(farthest-side at 0 50%,var(--shadow),rgba(255,255,255,0)) left center,
+    radial-gradient(farthest-side at 100% 50%,var(--shadow),rgba(255,255,255,0)) right center;
+  background-repeat:no-repeat;
+  background-size:44px 100%,44px 100%,13px 100%,13px 100%;
+  background-attachment:local,local,scroll,scroll}
+.tablewrap:focus-visible{outline:2px solid var(--gold);outline-offset:3px}
+table{width:100%;border-collapse:collapse;font:15.5px/1.5 var(--sans);
+      font-variant-numeric:tabular-nums lining-nums}
+th{text-align:left;font-size:11.5px;letter-spacing:.1em;text-transform:uppercase;
+   color:var(--ink-soft);border-bottom:1px solid var(--ink);padding:0 14px 9px 0;
+   font-weight:600;white-space:nowrap}
+td{padding:10px 14px 10px 0;border-bottom:1px solid var(--line);vertical-align:top}
+th:last-child,td:last-child{padding-right:0}
+th.num,td.num{text-align:right;white-space:nowrap}
+tbody tr:last-child td{border-bottom:none}
+tr td:first-child{font-weight:600;padding-right:20px;min-width:9em}
+.mv{font-weight:600;font-variant-numeric:tabular-nums}
+.mv.up{color:var(--up)} .mv.down{color:var(--down)} .mv.flat{color:var(--ink-soft)}
+
+/* ---------- quiz and solutions ---------- */
+.qq{scroll-margin-top:70px}
+.solnbar{display:flex;gap:8px;margin:0 0 16px}
+.ghost{background:none;border:1px solid var(--line);color:var(--ink-soft);
+       border-radius:99px;padding:6px 14px;cursor:pointer;
+       font:600 11.5px/1 var(--sans);letter-spacing:.06em;text-transform:uppercase;
+       transition:all .2s}
+.ghost:hover{border-color:var(--gold);color:var(--ink)}
+details.soln{margin:0 0 10px;scroll-margin-top:70px}
+details.soln>summary{cursor:pointer;list-style:none;display:flex;align-items:center;
+  gap:12px;border:1px solid var(--line);border-left:3px solid var(--spoiler);
+  border-radius:7px;padding:11px 16px;transition:all .2s;background:var(--tint-2)}
+summary::-webkit-details-marker{display:none}
+details.soln>summary:hover{border-color:var(--spoiler);background:var(--tint)}
+.qn{font:700 13px/1 var(--sans);letter-spacing:.08em;color:var(--spoiler);
+    text-transform:uppercase}
+.sl{font:500 12.5px/1 var(--sans);color:var(--ink-soft);letter-spacing:.05em}
+details[open]>summary .sl{opacity:.6}
+.solnbody{border-left:2px solid var(--accent);margin:14px 0 22px 3px;
+          padding:2px 0 2px 20px;font-size:17.5px}
+.backq{font:12.5px/1 var(--sans);margin:0}
+.backq a{color:var(--ink-soft);text-decoration:none}
+.backq a:hover{color:var(--accent)}
+
+/* ---------- glossary ---------- */
+details.gloss>summary,details.archive>summary{cursor:pointer;list-style:none;
+  display:flex;align-items:baseline;justify-content:space-between;gap:14px;
+  border:1px solid var(--line);border-radius:8px;padding:13px 18px;
+  font:600 14px/1 var(--sans);letter-spacing:.03em;transition:all .2s;
+  background:var(--tint-2)}
+details.gloss>summary:hover,details.archive>summary:hover{border-color:var(--gold)}
+.glossbody{padding:22px 2px 6px}
+.gsearch input{width:100%;padding:11px 14px;border:1px solid var(--line);
+  border-radius:8px;background:var(--paper);color:var(--ink);
+  font:15px/1 var(--sans)}
+.gsearch input:focus{outline:none;border-color:var(--gold)}
+.gchips{display:flex;flex-wrap:wrap;gap:7px;margin:14px 0 0}
+.gchip{background:none;border:1px solid var(--line);color:var(--ink-soft);
+  border-radius:99px;padding:6px 12px;cursor:pointer;display:flex;align-items:center;
+  gap:6px;font:600 12px/1 var(--sans);letter-spacing:.04em;transition:all .2s}
+.gchip:hover{border-color:var(--gold);color:var(--ink)}
+.gchip.on{background:var(--ink);color:var(--paper);border-color:var(--ink)}
+.gn{font-weight:400;opacity:.65;font-variant-numeric:tabular-nums}
+dl{margin:20px 0 0}
+.gterm{padding:11px 0;border-top:1px solid var(--line)}
+.gterm dt{font:600 15.5px/1.4 var(--sans)}
+.gterm dd{margin:3px 0 0;font-size:16.5px;color:var(--ink-soft)}
+.gep{font:600 10.5px/1 var(--sans);letter-spacing:.09em;text-transform:uppercase;
+     color:var(--ink-soft);border:1px solid var(--line);border-radius:99px;
+     padding:3px 7px;white-space:nowrap;margin-left:4px}
+.gep.now{color:var(--gold);border-color:var(--gold)}
+.gnone{font:15px/1.5 var(--sans);color:var(--ink-soft);padding:16px 0}
+
+/* ---------- episode navigation ---------- */
+.epnav{display:grid;grid-template-columns:1fr 1fr;gap:14px;margin:56px 0 20px;
+       padding-top:26px;border-top:1px solid var(--ink)}
+.epnav a{display:flex;flex-direction:column;gap:5px;text-decoration:none;
+  border:1px solid var(--line);border-radius:10px;padding:16px 18px;
+  color:var(--ink);transition:all .25s}
+.epnav a:hover{border-color:var(--gold);background:var(--tint-2)}
+.epnav .epnext{text-align:right}
+.epnav .dir{font:600 11px/1 var(--sans);letter-spacing:.14em;text-transform:uppercase;
+            color:var(--gold)}
+.epnav .ept{font:19px/1.3 var(--serif)}
+.epnav .epn{font:12px/1 var(--sans);color:var(--ink-soft);letter-spacing:.05em}
+.epnav a:only-child{grid-column:1/-1;max-width:60%}
+.epnav .epnext:only-child{margin-left:auto}
+details.archive{margin:0 0 12px}
+.arclist{list-style:none;margin:18px 0 6px;padding:0;font:15px/1.5 var(--sans)}
+.arclist li{margin:0;border-top:1px solid var(--line)}
+.arclist a{display:flex;gap:14px;padding:11px 4px;text-decoration:none;
+           color:var(--ink);transition:background .2s}
+.arclist a:hover{background:var(--tint-2)}
+.arclist b{color:var(--gold);font-variant-numeric:tabular-nums;font-weight:600}
+.arclist li.here a{color:var(--ink-soft)}
+.arclist li.here b:after{content:" ·  you are here";font-weight:400;
+  font-size:11px;letter-spacing:.1em;text-transform:uppercase}
+
+/* ---------- theme button + footer ---------- */
+.themebtn{position:fixed;top:14px;right:14px;z-index:20;background:var(--paper);
+  color:var(--ink-soft);border:1px solid var(--line);border-radius:99px;
+  padding:8px 14px;cursor:pointer;font:500 12px/1 var(--sans);letter-spacing:.06em;
+  display:flex;align-items:center;gap:7px;box-shadow:0 1px 4px var(--shadow);
+  transition:all .2s}
+.themebtn:hover{color:var(--ink);border-color:var(--gold)}
+.themebtn svg{width:14px;height:14px;fill:none;stroke:currentColor;stroke-width:1.8;
+              stroke-linecap:round;stroke-linejoin:round}
+html[data-theme="dark"] .themebtn{box-shadow:none}
+.themebtn .moon{display:block} .themebtn .sun{display:none}
+html[data-theme="dark"] .themebtn .moon{display:none}
+html[data-theme="dark"] .themebtn .sun{display:block}
+.themebtn .lbl:after{content:"Dark"}
+html[data-theme="dark"] .themebtn .lbl:after{content:"Light"}
+footer{margin-top:40px;padding:24px 0 70px;border-top:1px solid var(--line);
+       font:14px/1.7 var(--sans);color:var(--ink-soft);
+       display:flex;flex-wrap:wrap;gap:8px 22px;justify-content:space-between}
+footer a{color:var(--ink-soft)}
+footer a:hover{color:var(--accent)}
+footer .sig b{color:var(--ink);font-weight:600}
+
+/* ---------- wide screens: the rail, and the breakout ---------- */
+@media (min-width:1240px){
+  .toc{position:fixed;top:96px;left:max(24px,calc(50% - 596px));width:216px;
+       max-height:74vh;overflow-y:auto;margin:0;padding:0;border:none;
+       border-left:1px solid var(--line);padding-left:18px;z-index:5}
+  .toc ol{columns:1;font-size:14px}
+  .toc li{margin-bottom:9px}
+  /* charts break out of the measure; tables stay aligned with the prose,
+     because a table that starts left of the paragraph above it reads as a
+     layout fault rather than as emphasis */
+  .chartfig{margin-left:-38px;margin-right:-38px;
+            padding-left:26px;padding-right:26px}
+}
+@media (min-width:1240px) and (max-height:620px){ .toc{display:none} }
+
+/* ---------- phones ---------- */
+@media (max-width:640px){
+  body{font-size:17px;line-height:1.68}
+  .wrap{padding:0 18px 32px}
+  header{padding-top:34px}
+  .dek{font-size:18px}
+  h2{font-size:24px;margin-top:44px}
+  h3{font-size:20.5px}
+  /* a phone gets the sections, not every subhead: eleven rows of contents
+     is a screenful of scrolling before the article even starts */
+  .toc li.t3{display:none}
+  .toc ol{columns:2;column-gap:18px;font-size:14px}
+  .themebtn{top:9px;right:9px;padding:7px 11px}
+  table{font-size:14.5px}
+  th{font-size:10.5px;padding-right:12px}
+  td{padding-right:12px}
+  tr td:first-child{min-width:7.5em;padding-right:14px}
+  .epnav{grid-template-columns:1fr}
+  .epnav .epnext{text-align:left}
+  .epnav a:only-child{max-width:none}
+  .solnbody{font-size:17px;padding-left:15px}
+  /* charts earn the full width of a phone */
+  .chartfig{margin-left:-18px;margin-right:-18px;border-radius:0;
+            border-left:none;border-right:none;padding:16px 14px 12px}
+}
+
+/* ---------- print ---------- */
+@page{margin:16mm 14mm}
+@media print{
+  :root{--ink:#000;--ink-soft:#333;--line:#bbb;--paper:#fff;--tint:#f4f2ec;
+        --tint-2:#f8f7f3;--gold:#7a5c24;--accent:#123024;--up:#123024;
+        --down:#7a1f1f;--shadow:transparent}
+  html[data-theme="dark"]{--ink:#000;--ink-soft:#333;--line:#bbb;--paper:#fff;
+        --tint:#f4f2ec;--tint-2:#f8f7f3;--gold:#7a5c24;--accent:#123024}
+  body{font-size:11pt;line-height:1.5;background:#fff}
+  .wrap{max-width:none;padding:0}
+  #bar,.themebtn,.toc,.listen,.solnbar,.gsearch,.epnav,.anchor,.backq,
+  .homelink,.tohome{display:none!important}
+  header{padding-top:0}
+  .masthead{border-color:#000}
+  h1{font-size:23pt;margin-top:14pt}
+  .dek{font-size:12pt}
+  h2{font-size:15pt;margin:22pt 0 8pt;break-after:avoid}
+  h3{font-size:13pt;margin:14pt 0 5pt;break-after:avoid}
+  p,li{orphans:3;widows:3}
+  .tablewrap{overflow:visible;background:none;break-inside:avoid}
+  .chartfig{break-inside:avoid;border-color:#ccc;background:none}
+  details{break-inside:avoid;margin:0}
+  /* the answers print open, labelled by question, without a button */
+  details.soln>summary{display:flex;border:none;background:none;
+    padding:10pt 0 2pt;border-top:1px solid #ddd}
+  summary .sl{display:none}
+  .solnbody{border-color:#999;margin:2pt 0 8pt;padding-left:0}
+  /* the cumulative glossary is a reference, not part of the article:
+     eighty-odd terms would add pages to every printout */
+  .glossec,details.archive{display:none}
+  a{color:#000;text-decoration:none}
+  footer{border-color:#000}
+}
+@media (prefers-reduced-motion:reduce){
+  html{scroll-behavior:auto}
+  *{animation-duration:.001ms!important;transition-duration:.001ms!important}
+}
+"""
+
+JS = """
+(function(){
+  var doc = document.documentElement;
+
+  /* theme */
+  var btn = document.querySelector('.themebtn');
+  if(btn) btn.addEventListener('click', function(){
+    var next = doc.getAttribute('data-theme') === 'dark' ? 'light' : 'dark';
+    doc.setAttribute('data-theme', next);
+    try{ localStorage.setItem('cdd-theme', next); }catch(e){}
+  });
+
+  /* reading progress */
+  var bar = document.getElementById('bar'), ticking = false;
+  function progress(){
+    var h = doc.scrollHeight - innerHeight;
+    bar.style.width = (h > 0 ? Math.min(100, Math.max(0, scrollY / h * 100)) : 0) + '%';
+    ticking = false;
+  }
+  if(bar){
+    addEventListener('scroll', function(){
+      if(!ticking){ ticking = true; requestAnimationFrame(progress); }
+    }, {passive:true});
+    addEventListener('resize', progress, {passive:true});
+    progress();
+  }
+
+  /* contents: mark the section being read */
+  var links = [].slice.call(document.querySelectorAll('.toc a'));
+  if(links.length && 'IntersectionObserver' in window){
+    var map = {};
+    links.forEach(function(a){
+      var el = document.getElementById(decodeURIComponent(a.hash.slice(1)));
+      if(el) map[el.id] = a.parentNode;
+    });
+    var seen = [];
+    var io = new IntersectionObserver(function(entries){
+      entries.forEach(function(en){
+        var id = en.target.id, at = seen.indexOf(id);
+        if(en.isIntersecting){ if(at < 0) seen.push(id); }
+        else if(at >= 0){ seen.splice(at, 1); }
+      });
+      links.forEach(function(a){ a.parentNode.classList.remove('on'); });
+      if(seen.length && map[seen[0]]) map[seen[0]].classList.add('on');
+    }, {rootMargin:'-64px 0px -70% 0px'});
+    Object.keys(map).forEach(function(id){
+      var el = document.getElementById(id); if(el) io.observe(el);
+    });
+  }
+
+  /* playback speed */
+  var audio = document.querySelector('audio');
+  [].forEach.call(document.querySelectorAll('.rate'), function(b){
+    b.addEventListener('click', function(){
+      if(!audio) return;
+      audio.playbackRate = parseFloat(b.dataset.rate);
+      [].forEach.call(document.querySelectorAll('.rate'), function(o){
+        o.setAttribute('aria-pressed', String(o === b));
+      });
+    });
+  });
+
+  /* solutions: reveal all / hide all */
+  [].forEach.call(document.querySelectorAll('[data-solnall]'), function(b){
+    b.addEventListener('click', function(){
+      var open = b.dataset.solnall === 'open';
+      [].forEach.call(document.querySelectorAll('details.soln'), function(d){
+        d.open = open;
+      });
+    });
+  });
+
+  /* an answer linked to directly should already be open */
+  function openTarget(){
+    var id = location.hash.slice(1);
+    if(!id) return;
+    var el = document.getElementById(decodeURIComponent(id));
+    while(el){
+      if(el.tagName === 'DETAILS') el.open = true;
+      el = el.parentElement;
+    }
+  }
+  addEventListener('hashchange', openTarget); openTarget();
+
+  /* glossary: an episode chip and a search box, which compose */
+  var gf = document.getElementById('gfilter'), list = document.getElementById('glist');
+  if(list){
+    var rows = [].slice.call(list.querySelectorAll('.gterm'));
+    var chips = [].slice.call(document.querySelectorAll('.gchip'));
+    var none = document.querySelector('.gnone');
+    var pick = 'all';
+    function apply(){
+      var q = gf ? gf.value.trim().toLowerCase() : '', hits = 0;
+      rows.forEach(function(r){
+        var on = (pick === 'all' || r.dataset.ep === pick) &&
+                 (!q || r.textContent.toLowerCase().indexOf(q) > -1);
+        r.hidden = !on; if(on) hits++;
+      });
+      if(none) none.hidden = hits > 0;
+    }
+    if(gf) gf.addEventListener('input', apply);
+    chips.forEach(function(c){
+      c.addEventListener('click', function(){
+        pick = c.dataset.gep;
+        chips.forEach(function(o){ o.classList.toggle('on', o === c); });
+        apply();
+      });
+    });
+  }
+
+  /* printing: paper has no disclosure triangles */
+  var reopen = [];
+  addEventListener('beforeprint', function(){
+    reopen = [].filter.call(document.querySelectorAll('details'), function(d){
+      return !d.open;
+    });
+    reopen.forEach(function(d){ d.open = true; });
+  });
+  addEventListener('afterprint', function(){
+    reopen.forEach(function(d){ d.open = false; });
+    reopen = [];
+  });
+})();
+"""
+
+HEAD_JS = """
+try{
+  var s = localStorage.getItem('cdd-theme');
+  if(s){ document.documentElement.setAttribute('data-theme', s); }
+  else if(window.matchMedia && window.matchMedia('(prefers-color-scheme: dark)').matches){
+    document.documentElement.setAttribute('data-theme','dark');
+  }
+}catch(e){}
+"""
+
+TEMPLATE = """<!DOCTYPE html>
+<html lang="en" data-theme="light">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Ep {number} — {title} · {show}</title>
+<meta name="description" content="{dek_attr}">
+<meta name="author" content="{author}">
+<link rel="canonical" href="{page}">
+<meta property="og:type" content="article">
+<meta property="og:site_name" content="{show}">
+<meta property="og:title" content="Ep {number} — {title}">
+<meta property="og:description" content="{dek_attr}">
+<meta property="og:url" content="{page}">
+<meta property="og:image" content="{cover}">
+<meta property="og:image:alt" content="{show} cover art">
+<meta property="og:audio" content="{audio}">
+<meta property="og:audio:type" content="audio/mpeg">
+<meta property="article:published_time" content="{iso}">
+<meta name="twitter:card" content="summary_large_image">
+<meta name="twitter:title" content="Ep {number} — {title}">
+<meta name="twitter:description" content="{dek_attr}">
+<meta name="twitter:image" content="{cover}">
+<meta name="theme-color" content="#faf7f1" media="(prefers-color-scheme: light)">
+<meta name="theme-color" content="#14110e" media="(prefers-color-scheme: dark)">
+<link rel="alternate" type="application/rss+xml" title="{show}" href="{feed}">
+<link rel="icon" href="{favicon}">
+<script type="application/ld+json">
+{jsonld}
+</script>
+<style>{css}</style>
+<script>{headjs}</script>
+</head>
+<body>
+<div id="bar" aria-hidden="true"></div>
+<button class="themebtn" type="button" aria-label="Switch colour theme">
+  <svg class="moon" viewBox="0 0 24 24" aria-hidden="true"><path d="M21 12.8A9 9 0 1 1 11.2 3a7 7 0 0 0 9.8 9.8z"/></svg>
+  <svg class="sun" viewBox="0 0 24 24" aria-hidden="true"><circle cx="12" cy="12" r="4.2"/><path d="M12 2v2M12 20v2M4.9 4.9l1.4 1.4M17.7 17.7l1.4 1.4M2 12h2M20 12h2M4.9 19.1l1.4-1.4M17.7 6.3l1.4-1.4"/></svg>
+  <span class="lbl"></span>
+</button>
+<div class="wrap">
+<header>
+  <div class="masthead">
+    <a href="{site}">{show}</a>
+    <span class="mastright">
+      <a class="homelink" href="{site}">All episodes &#8599;</a>
+      <span class="epno">Ep {number:02d}</span>
+    </span>
+  </div>
+  <h1>{title}</h1>
+  {dekblock}
+  <div class="meta">{date}{datesep}<b>{duration}</b></div>
+  <div class="listen">
+    <audio controls preload="none" src="{audio}"></audio>
+    <div class="listenrow">
+      <span class="rates" role="group" aria-label="Playback speed">
+        <button type="button" class="rate" data-rate="1" aria-pressed="true">1×</button>
+        <button type="button" class="rate" data-rate="1.25" aria-pressed="false">1.25×</button>
+        <button type="button" class="rate" data-rate="1.5" aria-pressed="false">1.5×</button>
+      </span>
+      <a href="{audio}" download>Download</a>
+      <a href="{feed}">Subscribe · RSS</a>
+    </div>
+  </div>
+{toc}
+</header>
+<main>
+{body}
+{glossary}
+</main>
+{epnav}
+<p class="tohome"><a href="{site}">&#8592; All episodes on {show}</a></p>
+<footer>
+  <span class="sig"><b>{show}</b> — a daily briefing on physical commodity trading.</span>
+  <span><a href="{site}">The show</a> · <a href="{feed}">RSS</a></span>
+</footer>
+</div>
+<script>{js}</script>
+</body>
+</html>
+"""
+
+FAVICON = ("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' "
+           "viewBox='0 0 64 64'%3E%3Crect width='64' height='64' rx='12' "
+           "fill='%231d4032'/%3E%3Ctext x='32' y='44' font-family='Georgia,serif' "
+           "font-size='34' fill='%23c9a45c' text-anchor='middle'%3ES%3C/text%3E%3C/svg%3E")
+
+
+def main():
+    global SEARCH_NEAR
+    ap = argparse.ArgumentParser()
+    ap.add_argument("--notes", required=True)
+    ap.add_argument("--number", type=int, required=True)
+    ap.add_argument("--title", required=True)
+    ap.add_argument("--dek", default="")
+    ap.add_argument("--audio-url", required=True)
+    ap.add_argument("--duration", type=int, required=True, help="seconds")
+    ap.add_argument("--date", default="")
+    ap.add_argument("--out", required=True)
+    ap.add_argument("--charts-prefix",
+                    help="also write each chart as a PNG for the e-mail, "
+                         "named <prefix>1.png, <prefix>2.png, ...")
+    ap.add_argument("--covered", default="",
+                    help="covered.md, for previous/next links and the archive. "
+                         "Found automatically in the working directory; pass "
+                         "'none' to leave the page without episode navigation.")
+    ap.add_argument("--glossary", default="",
+                    help="glossary.md, rendered on the page in a collapsed "
+                         "section. Found automatically; 'none' to omit it.")
+    args = ap.parse_args()
+
+    SEARCH_NEAR = args.notes
+    md = open(args.notes, encoding="utf-8").read()
+    # Drop the notes' own H1/H2 title block: the page has a proper header.
+    md = re.sub(r"\A\s*#\s+.*?\n(##\s+.*?\n)?", "", md, count=1)
+    md = re.sub(r"^\*A daily 10-minute briefing.*$", "", md, flags=re.MULTILINE)
+    # the notes rule off under their title block; the page's masthead does that
+    md = re.sub(r"\A\s*(-{3,}|\*{3,})\s*$", "", md, count=1, flags=re.MULTILINE)
+    body = tidy_rules(fold_solutions(number_questions(render(strip_spoiler_banner(md)))))
+
+    covered = {} if args.covered == "none" else load_covered(
+        find_file(args.covered, "covered.md"))
+    terms = [] if args.glossary == "none" else load_glossary(
+        find_file(args.glossary, "glossary.md", "glossary_final.md"))
+
+    mins, secs = divmod(args.duration, 60)
+    dek = args.dek.strip()
+    iso = iso_date(args.date)
+    # the glossary adds a heading, so it has to exist before the contents rail
+    glossary_block = glossary_html(terms, args.number)
+    toc_block = toc_html()
+    page = TEMPLATE.format(
+        number=args.number,
+        show=SHOW,
+        title=html.escape(args.title),
+        dek_attr=html.escape(dek or f"Episode {args.number} of {SHOW}.", quote=True),
+        dekblock=f'<p class="dek">{html.escape(dek)}</p>' if dek else "",
+        date=html.escape(args.date),
+        datesep=" · " if args.date else "",
+        duration=f"{mins} min {secs:02d}",
+        audio=html.escape(args.audio_url, quote=True),
+        feed=FEED_URL,
+        site=SITE_URL,
+        page=page_url(args.number),
+        cover=COVER_URL,
+        favicon=FAVICON,
+        author=html.escape(AUTHOR, quote=True),
+        iso=iso,
+        jsonld=jsonld(args, dek, iso, args.number),
+        css=CSS + (chartlib.CHART_CSS if chartlib else ""),
+        js=JS,
+        headjs=HEAD_JS,
+        toc=toc_block,
+        glossary=glossary_block,
+        epnav=epnav_html(covered, args.number),
+        body=body,
+    )
+    with open(args.out, "w", encoding="utf-8") as fh:
+        fh.write(page)
+    print(f"[page] {args.out} | {len(page):,} bytes")
+
+    if CHART_SPECS and args.charts_prefix and chartlib:
+        for n, spec in enumerate(CHART_SPECS, 1):
+            path = f"{args.charts_prefix}{n}.png"
+            if chartlib.to_png(spec, path):
+                print(f"CHART_PNG={path}")
+    elif CHART_SPECS:
+        print(f"[page] {len(CHART_SPECS)} chart(s) rendered inline")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())