render.mjs

// Phase 3 of tbdocs: render each page's markdown / HTML body to an HTML
// fragment stored on page.renderedContent. See builder/PLAN-3.md for the
// full spec.
//
// What this phase does NOT do (per PLAN-3 §3):
//   - wrap in <html> / layout / sidebar / footer / scripts (Phase 4)
//   - inject <a class="anchor-heading"> next to <hN id> (Phase 4 -- has
//     to see auto-generated heading IDs)
//   - compress whitespace (Phase 4)
//   - generate the per-page nav-activation <style> block (Phase 4)
//   - concatenate chapter bodies for the PDF book (Phase 8)

import MarkdownIt from "markdown-it";
import attrs from "markdown-it-attrs";
import deflist from "markdown-it-deflist";
import footnote from "markdown-it-footnote";

import { blockRegions, maskCode } from "../lib/markdown.mjs";
import { initHighlighter } from "./highlight.mjs";
import { countPlugin, expandDownloadPlaceholders, findSurvivingPlaceholder } from "./counts.mjs";
import { replaceOutsideCode } from "./code-guard.mjs";
import { splitFragment } from "./url.mjs";
import { escapeMarkup, escapeMarkupAndQuotes, escapeRegExp } from "./escape.mjs";
import { inlineDiagram } from "./inline-diagram.mjs";
import { checkCalloutLabel, parseCalloutLabel } from "../lib/callout-labels.mjs";
import {
  isLightPicture,
  isPictureSvg,
  lightDimension,
  lightSiblingOf,
  PIC_DARK,
  PIC_LIGHT,
  svgOf,
} from "./theme-pictures.mjs";

export async function renderPhase(pages, site, staticFiles = []) {
  // Allow the orchestrator to pre-build the markdown-it instance (so
  // Phase 2's seo.mjs can share the same renderer). Idempotent: if
  // site.markdown is already set, use it; otherwise build it here.
  let md = site.markdown;
  if (!md) {
    const highlighter = await initHighlighter();
    const linkTables = buildLinkTables(pages);
    const baseurl = String(site.config.baseurl || "");
    const staticFileSet = new Set(staticFiles.map((s) => s.srcRel));
    md = createMarkdownIt({ highlighter, linkTables, baseurl, staticFiles: staticFileSet });
    site.markdown = md;
  }

  await Promise.all(
    pages.map(async (page) => {
      page.renderedContent = renderPage(page, md);
      // A count placeholder that reached the output is the failure the feature
      // exists to prevent, arriving by a new route. Source validation cannot see
      // this case -- a placeholder inside a raw HTML block has a perfectly good
      // name, so it passes there, and markdown-it keeps an html_block as one
      // opaque token the substitution rule never enters. One string scan per
      // page, and it catches every cause rather than the ones anticipated.
      const survivor = findSurvivingPlaceholder(page.renderedContent);
      if (survivor) {
        throw new Error(
          `${page.srcRel}: ${survivor} survived rendering.\n` +
            "  The name is known, so this is a placement markdown-it cannot reach --\n" +
            "  a raw HTML block is the usual one. Put it in prose, or write the\n" +
            "  number by hand and say in the page why it is not derived.",
        );
      }
    }),
  );
}

function renderPage(page, md) {
  if (page.ext === ".html") {
    // 404.html passes through Phase 4's default-layout wrap; book.html is
    // consumed by Phase 8. Either way, no markdown rendering happens here.
    return page.rawContent;
  }
  let source;
  try {
    source = applyPreRenderRewrites(page.rawContent, md, {
      packageVersion: page.packageVersion ?? "",
      permalink: page.permalink,
    });
  } catch (e) {
    throw new Error(`${page.srcRel}: ${e.message}`);
  }
  const env = { page };
  const html = md.render(source, env);
  // Lifted off the headings by searchIndexMarksPlugin; search.mjs reads
  // them when it splits this page into entries.
  if (env.searchIndexMarks) page.searchIndexMarks = env.searchIndexMarks;
  return applyPostRenderRewrites(html);
}

// The rewrites over a page's whole rendered HTML, exactly as renderPage
// applies them. Exported so scripts/check_code_regions.mjs gates the real
// chain. Each goes through replaceOutsideCode. Code the renderer produced
// cannot match their patterns, since its `<` is escaped; a `<pre>` or
// `<code>` written as raw HTML reaches them as written, and whitespace
// inside one is content.
export function applyPostRenderRewrites(html) {
  return padEmptyCells(normaliseVoidTags(html));
}

// markdown-it leaves an empty `<td>` / `<th>` cell collapsed (`<td></td>`);
// kramdown emits a nbsp in it, and so does this. A regular space would look
// the same, but Phase 4's compress would collapse it differently.
function padEmptyCells(html) {
  return replaceOutsideCode(html, /<(t[dh])([^>]*)><\/\1>/g, (_, tag, attrs) => `<${tag}${attrs}>\u{a0}</${tag}>`);
}

// The whole pre-render rewrite chain, exactly as renderPage applies it.
// Exported so scripts/check_code_regions.mjs can gate the real thing rather
// than a reconstruction of it -- in particular so that removing the mask from
// one of these rewrites is caught, which a gate that only exercised the mask
// would miss.
//
// `md` is the site's markdown-it instance, and it decides what the mask hides:
// the definition-list plugin, for one, makes a fence after `: ` that a bare
// parser reads as a paragraph. Without it the mask would silently differ from
// the build's, so a call without one throws.
//
// `options.packageVersion` is the version the page's package section
// documents, which a callout label's package version must be. `options.permalink`
// is the page's URL, which the links in {{tbdocs:packageTestRows}} are relative to.
export function applyPreRenderRewrites(rawContent, md, options = {}) {
  if (!md) throw new TypeError("applyPreRenderRewrites: pass the site's markdown-it instance");
  // CommonMark normalises CRLF/CR to LF before block parsing. The rewrites
  // below all rely on LF-only input -- do the normalisation up front so they
  // see consistent line shapes.
  const source = rawContent.replace(/\r\n?/g, "\n");

  // These four are kramdown-parity fixes over raw source, so none of them
  // knows what is code. On a site whose subject matter IS code that is a
  // standing hazard, and it was demonstrated for each: `Items[1](a, b)` became
  // `Items[1](a,%20b)`, `' *** banner ***` became `' **_ banner _**`, and a
  // YAML sample ending in `---` had that line DELETED and the entry above it
  // promoted to a heading. Mask the code regions, rewrite, then restore.
  //
  // The mask hides every fence the parser finds, blockquote and list prefixes
  // included, and every code span. It does not hide indented code blocks,
  // which the chain has never masked; check_code_regions.mjs compares them
  // all the same. Each masked fence becomes one line starting with a backtick,
  // so absorbTrailingHtmlComments, which will not join a comment to a line that
  // starts with one, never joins a comment to a fence.
  const code = maskCode(source, { md });
  let work = code.masked;
  // The download placeholders expand first, so the rewrites below see the page as it will be
  // read. They are in prose or in a raw HTML block, where the inline substitution (counts.mjs)
  // cannot reach them; a placeholder in code is masked and stays as written.
  if (md.downloads) work = expandDownloadPlaceholders(work, md.downloads, options.permalink);
  work = rewriteTripleAsteriskEmphasis(work);
  work = encodeSpacesInMediaUrls(work);
  work = rewriteListItemSetextHeadings(work);
  work = absorbTrailingHtmlComments(work);

  // rewriteAdmonitions runs OUTSIDE the mask, and must: it finds an
  // admonition's lines by their `> ` markers and strips them, and a masked
  // fence inside an admonition has taken its markers with it into the stash.
  // It asks lib/markdown where the code is itself, with the same parser.
  return rewriteAdmonitions(code.restore(work), md, options);
}

// kramdown accepts unescaped spaces inside `![alt](url)` and `[text](url)`
// URLs; CommonMark / markdown-it does NOT and leaves the source text
// unparsed. URL-encode spaces inside image and link URL components so
// markdown-it can parse them the way kramdown would.
//
// Only the simple case is handled: a URL that's a plain file path with
// spaces and NO embedded quotes or parens. Anything trickier (titles,
// nested parens) gets left alone -- the regex is too coarse to safely
// rewrite those.
const MEDIA_URL_SPACES_RE = /(!?\[(?:[^\]\n]*)\])\(([^)"'\n]+)\)/g;
function encodeSpacesInMediaUrls(src) {
  return src.replace(MEDIA_URL_SPACES_RE, (whole, prefix, url) => {
    if (!/ /.test(url)) return whole;
    return `${prefix}(${url.replace(/ /g, "%20")})`;
  });
}

// kramdown emits `***text***` as `<strong><em>text</em></strong>`;
// markdown-it emits the same source as `<em><strong>text</strong></em>`.
// Pre-rewriting the source to `**_text_**` makes both renderers emit
// the strong-outside form. Leave existing `**_..._**` and `_**...**_`
// patterns alone so their em/strong order matches the source intent.
const TRIPLE_STAR_RE = /\*\*\*([^*\n][^*\n]*?)\*\*\*/g;
function rewriteTripleAsteriskEmphasis(src) {
  return src.replace(TRIPLE_STAR_RE, "**_$1_**");
}

// kramdown attaches a standalone HTML-comment line to the preceding
// paragraph (the comment line ends up inside the paragraph's AST). In
// CommonMark / markdown-it, a comment that occupies a whole line is
// detected as a block-level HTML element and the preceding paragraph is
// closed before it. Pre-rewrite the source so a comment line that
// immediately follows a non-blank "regular text" line and is itself
// followed by a blank line is JOINED to the preceding line. markdown-it
// then treats the `<!-- ... -->` as inline raw HTML inside the same
// paragraph, matching kramdown.
//
// Conservative: skip if the previous line is a fence, heading, list
// marker, blockquote marker, or HTML-block opener -- those don't form
// the kind of paragraph kramdown would absorb the comment into.
const HTML_COMMENT_LINE_RE = /^[ \t]*<!--[^\n]*-->[ \t]*$/;
const PARAGRAPH_CONTINUATION_RE = /^[ \t]*[^\s#>*+\-`~|<\[].*$/;
function absorbTrailingHtmlComments(src) {
  const lines = src.split("\n");
  const out = [];
  for (let i = 0; i < lines.length; i++) {
    const line = lines[i];
    if (
      i > 0 &&
      HTML_COMMENT_LINE_RE.test(line) &&
      PARAGRAPH_CONTINUATION_RE.test(lines[i - 1]) &&
      (i + 1 >= lines.length || lines[i + 1].trim() === "")
    ) {
      // Append to the previous emitted line with a single space.
      out[out.length - 1] = `${out[out.length - 1]} ${line.trim()}`;
    } else {
      out.push(line);
    }
  }
  return out.join("\n");
}

// kramdown quirk: when `---` appears on a line directly after a list item,
// it treats the previous list item's content as a setext H2 INSIDE the
// <li>, and the `---` does NOT terminate the list. markdown-it instead
// reads `---` as <hr> after the list. Rewrite the source to make the
// promoted item explicit: `- text\n---\n` becomes `- ## text\n` so
// markdown-it emits an <li><h2>text</h2></li> at that position.
const LIST_ITEM_SETEXT_RE = /^([ \t]*[*+\-][ \t]+)([^\n]*?)\n[ \t]*---[ \t]*$/gm;
function rewriteListItemSetextHeadings(src) {
  return src.replace(LIST_ITEM_SETEXT_RE, (_, marker, text) => `${marker}## ${text}`);
}

// markdown-it inline newline rule, modified to keep all-but-the-final-
// two trailing spaces in the pending text. Matches kramdown's behaviour
// (the line-break regex `(  )(?=\n)` consumes exactly the final two
// spaces). Otherwise identical to the upstream rule.
function kramdownHardBreakNewline(state, silent) {
  let pos = state.pos;
  if (state.src.charCodeAt(pos) !== 0x0a) return false;

  const pmax = state.pending.length - 1;
  const max = state.posMax;

  if (!silent) {
    if (pmax >= 0 && state.pending.charCodeAt(pmax) === 0x20) {
      if (pmax >= 1 && state.pending.charCodeAt(pmax - 1) === 0x20) {
        // Two-or-more trailing spaces -> hardbreak. Strip only the final
        // two; preserve any additional trailing spaces in the text.
        state.pending = state.pending.slice(0, pmax - 1);
        state.push("hardbreak", "br", 0);
      } else {
        state.pending = state.pending.slice(0, -1);
        state.push("softbreak", "br", 0);
      }
    } else {
      state.push("softbreak", "br", 0);
    }
  }

  pos++;
  while (pos < max && state.src.charCodeAt(pos) === 0x20) pos++;
  while (pos < max && state.src.charCodeAt(pos) === 0x09) pos++;
  state.pos = pos;
  return true;
}

// kramdown normalises HTML void elements to the XHTML self-closing form
// (`<br />`, `<hr />`, `<img ... />`) regardless of the input shape.
// markdown-it with `xhtmlOut: true` emits the same form for tokens it
// generates, but raw block / inline HTML (like author-written `<br>`)
// passes through verbatim. Rewrite those to match.
//
// The attributes are one flat `[^>]*`, and the trailing `/` is removed
// afterwards rather than described in the pattern. That is deliberate:
// spelling the attribute list out as
// `(?:\s+[^>/]+(?:="[^"]*"|='[^']*')?)*` is wrong, because `[^>/]` matches
// a space and so does `\s`, which makes it the classic `(a+)+`: one run of
// attribute text can be partitioned in exponentially many ways, and every
// partition gets tried when the match fails -- which it does on any `/`
// the quoted-value alternative does not cover, such as `Line/Column` in
// alt text. Such a page hangs a render worker outright: its chunk stays
// CLAIMED, the renderJoin and flushJoin barriers behind it never reach a
// dep count of zero, and the build prints its last line and sits there
// forever.
//
// Narrowing the class to `[^\s>/]+` fixed those two strings and did not
// fix the regex: `[^\s>/]` still matches `=`, `"` and `'`, so an
// attribute could be consumed either by the name class or by the
// quoted-value alternative, and that binary choice per attribute is the
// same 2^n one level down. scripts/check_regex_safety.mjs caught it with
// the witness `<BR\tG=` + `""\t"=''\t=='/">'\tG=` -- 186 characters took
// 97 ms and it grew from there.
//
// So do not reintroduce a per-attribute sub-pattern. Matching to the
// first `>` cannot be ambiguous, because `[^>]*` and the `>` that
// follows it share no character. Verified against every void tag in the
// built site -- 4,137 distinct tags, byte-identical output -- and
// recheck's own worst witness now runs in under a millisecond at 288,006
// characters.
const VOID_TAGS_RE = /<(br|hr|img|input|link|meta|area|base|col|embed|source|track|wbr)\b([^>]*)>/gi;

// Drop an existing self-closing slash and the whitespace around it, so
// the emitted tag ends in exactly one ` />`. Three anchored one-liners
// rather than one combined pattern: each is separately trivial to read
// and none of them can backtrack.
function stripSelfClose(attrs) {
  return attrs.replace(/\s+$/, "").replace(/\/$/, "").replace(/\s+$/, "");
}

function normaliseVoidTags(html) {
  return replaceOutsideCode(html, VOID_TAGS_RE, (_, tag, attrs) => `<${tag.toLowerCase()}${stripSelfClose(attrs)} />`);
}

// ---------- markdown-it configuration ---------------------------------------

export { initHighlighter };

export function createMarkdownIt(ctx) {
  const md = new MarkdownIt({
    // kramdown parse_block_html + parse_span_html; recursion handled by
    // blockHtmlRecursionPlugin (PLAN-3 §5.12).
    html: true,
    // kramdown emits self-closing <br /> / <hr /> (XHTML form); CommonMark
    // default is HTML5 <br>. Match kramdown.
    xhtmlOut: true,
    // kramdown hard_wrap is OFF on this site -- single newlines are not
    // <br>. Two-space line breaks still produce <br> via CommonMark.
    breaks: false,
    // Site content uses explicit [text](url) form; no bare URLs in body
    // prose. Off matches current rendered output.
    linkify: false,
    // -- -> en-dash, --- -> em-dash, ASCII quotes -> curly. Matches
    // kramdown smart_quotes; see PLAN-3 §5.9 for divergences.
    typographer: true,
    quotes: "“”‘’",
    highlight: ctx.highlighter ? (code, lang) => ctx.highlighter.render(code, lang) : undefined,
  });

  // `hidden` as a whitespace-separated token anywhere after the language.
  // Matched against the raw info string rather than parsed with
  // scripts/lib/tb-fences.mjs's parseInfo: builder/ must not depend on
  // scripts/, and this is the one token of that markup the renderer cares
  // about. The word has to stand alone, or a language called `hidden-x` or a
  // key like `id=hidden` would suppress a fence the author meant to publish.
  const HIDDEN_FENCE_RE = /^\S+(?:\s+\S+)*?\s+hidden(?:\s|$)/;

  // Override the fence renderer so our highlight callback's wrapper HTML
  // (which starts with <div, not <pre>) is used verbatim. Without this,
  // markdown-it's default fence rule wraps it in another <pre><code>.
  //
  // When the fence is nested (inside a list item, admonition, or other
  // block container), kramdown inserts a newline between the inner
  // `</div>` and the outer `</div>` of the wrapper as part of its
  // indented-block pretty-printing -- the html-compress pass then
  // renders that as a single space. Mirror by splicing a `\n` between
  // the close tags when level > 0.
  md.renderer.rules.fence = (tokens, idx, options) => {
    const tok = tokens[idx];
    const lang = tok.info ? tok.info.trim().split(/\s+/)[0] : "";
    // A fence marked `hidden` is context for the compile gate, not content:
    // scripts/check_examples.mjs builds it with the page's other samples so
    // that the declarations a sample assumes can live beside it rather than in
    // a shared template, and the reader never sees it. Emitting nothing here
    // keeps it out of the HTML, and therefore out of the search index, the
    // offline mirror and the PDF book, all of which read the rendered string.
    if (HIDDEN_FENCE_RE.test(tok.info ?? "")) return "";
    const html = options.highlight(tok.content, lang);
    if (tok.level > 0 || tok.meta?.nestedInBlock) {
      return html.replace(/<\/div><\/div>$/, "</div>\n</div>") + "\n";
    }
    return html + "\n";
  };

  // Indented (4-space) code blocks have no language info. kramdown wraps
  // them in the same Rouge wrapper shape used for fences with a
  // `language-plaintext` class. markdown-it's default emits a bare
  // `<pre><code>` -- override to match.
  md.renderer.rules.code_block = (tokens, idx, _opts, _env, _slf) => {
    const tok = tokens[idx];
    const body = escapeMarkup(tok.content);
    return `<div class="language-plaintext highlighter-rouge"><div class="highlight" tabindex="0"><pre class="highlight"><code>${body}</code></pre></div></div>\n`;
  };

  // kramdown/just-the-docs tag inline `code` spans with the Rouge wrapper
  // class so the same CSS rules style both block-level highlights and
  // inline ones. Match that, and escape only `& < >` (matching kramdown's
  // code-span escape) -- leaving `"` and `'` literal so embedded HTML
  // attribute syntax stays readable.
  md.renderer.rules.code_inline = (tokens, idx, _opts, _env, slf) => {
    const tok = tokens[idx];
    return `<code class="language-plaintext highlighter-rouge"${slf.renderAttrs(tok)}>${escapeMarkup(tok.content)}</code>`;
  };

  // just-the-docs wraps every <table> in <div class="table-wrapper"> via
  // its `_includes/table_wrappers.html` Liquid pass. Mirror that here so
  // CSS rules keyed on `.table-wrapper > table` keep working. Use the
  // default renderToken first so markdown-it's per-token block-prefix
  // whitespace handling still produces the leading newline when the
  // table sits at the start of a list-item / dd / blockquote child.
  //
  // tabindex="0" for the same reason highlight.mjs puts it on div.highlight
  // (PLAN-a11y.md 1.9): the wrapper is `overflow-x: auto` (JTD
  // tables.scss:11), and a scroll container a keyboard user cannot focus
  // cannot be scrolled without a pointer. Unconditional, as on code blocks --
  // whether a given table overflows depends on the viewport, so there is no
  // render-time answer. custom.scss gives the focus a visible ring.
  md.renderer.rules.table_open = (tokens, idx, opts, _env, slf) =>
    slf.renderToken(tokens, idx, opts).replace(/<table>/, `<div class="table-wrapper" tabindex="0"><table>`);
  md.renderer.rules.table_close = (tokens, idx, opts, _env, slf) =>
    `</table></div>` + slf.renderToken(tokens, idx, opts).replace(/<\/table>/, "");

  // kramdown emits `style="text-align: left"` with a space after the
  // colon; markdown-it emits the compact form. Override the th/td
  // renderers to widen the gap.
  const styleSpace = (_defaultRule) => (tokens, idx, opts, _env, slf) => {
    const tok = tokens[idx];
    const styleIdx = tok.attrIndex("style");
    if (styleIdx >= 0) {
      tok.attrs[styleIdx][1] = tok.attrs[styleIdx][1].replace(/:/g, ": ");
    }
    return slf.renderToken(tokens, idx, opts);
  };
  md.renderer.rules.th_open = ((_defaultRule) => (tokens, idx, opts, _env, slf) => {
    const tok = tokens[idx];
    const styleIdx = tok.attrIndex("style");
    if (styleIdx >= 0) {
      tok.attrs[styleIdx][1] = tok.attrs[styleIdx][1].replace(/:/g, ": ");
    }
    tok.attrSet("scope", "col");
    return slf.renderToken(tokens, idx, opts);
  })();
  md.renderer.rules.td_open = styleSpace();

  // kramdown renders ordered lists with no `start` attribute even when
  // the source numbers don't begin at 1 (it ignores the source
  // numbering entirely). markdown-it preserves it; strip to match.
  md.renderer.rules.ordered_list_open = (tokens, idx, _opts, _env, slf) => {
    const tok = tokens[idx];
    const startIdx = tok.attrIndex("start");
    if (startIdx >= 0) tok.attrs.splice(startIdx, 1);
    return slf.renderToken(tokens, idx, slf.options);
  };

  // Override the inline newline rule to match kramdown's hard-break
  // semantics. kramdown's regex `(  )(?=\n)` consumes EXACTLY the two
  // spaces immediately before the newline -- any additional trailing
  // spaces are preserved in the text. markdown-it's default rule strips
  // ALL trailing spaces before emitting the hardbreak. For 2-space hard
  // breaks (the common case) both behaviours are identical; the
  // divergence shows up with 3+ trailing spaces, where Jekyll renders
  // `text <br />` (one trailing space) and we render `text<br />`.
  md.inline.ruler.at("newline", kramdownHardBreakNewline);

  // kramdown's `{: ... }` attribute syntax. Default plugin delimiters
  // are `{` / `}`; we override both to require the colon.
  md.use(attrs, {
    leftDelimiter: "{:",
    rightDelimiter: "}",
  });
  md.use(standaloneIalForwardPlugin);
  md.use(tightLooseListPlugin);
  md.use(deflist);
  md.use(looseDeflistPlugin);
  md.use(footnote);
  configureFootnotes(md);
  md.use(headerIdPlugin);
  md.use(searchIndexMarksPlugin);
  md.use(headingLevelNormalizePlugin);
  md.use(tocPlugin);
  md.use(relativeLinksPlugin, ctx);
  md.use(themePairPlugin, ctx);
  md.use(blockHtmlRecursionPlugin);
  md.use(kramdownDashesPlugin);
  md.use(kramdownEllipsisPlugin);
  md.use(flattenAdjacentStrongPlugin);
  md.use(figurePlugin, ctx);
  md.use(videoLinkPlugin, ctx);
  md.use(remoteImagePlugin, ctx);
  md.use(stripHtmlCommentsPlugin);
  // Substitutes {{tbdocs:<name>}} in prose. Registered last so it runs after
  // `replacements` has done the dash and quote transforms -- see counts.mjs
  // for why the layer matters and what it deliberately cannot reach.
  md.use(countPlugin, ctx);
  // What the pre-render rewrites expand {{tbdocs:size:...}} and {{tbdocs:packageTestRows}}
  // from (counts.mjs); none in a caller that has no downloads, which leaves them unexpanded.
  md.downloads = ctx.downloads ?? null;

  return md;
}

// Author comments (`<!-- ... -->`: SHOT markers, test-region markers, notes)
// are not for the reader, so no page carries one. Only the parser's html_block
// and html_inline tokens are touched: a comment shown in a fence or in a code
// span is text there, escaped by its own renderer, and never reaches this rule.
// It runs after tightLooseListPlugin, which reads a comment block as a block
// of its own, so a list's looseness is decided with the comment still there.
//
// A raw HTML block holding a script, style or textarea element is left alone,
// since a `<!--` inside one is not a comment to the browser.
const RAW_TEXT_ELEMENT_RE = /<(?:script|style|textarea)[\s>]/i;

// `html` without its comments. A comment alone on its line takes the whole
// line with it; one at the end of a line takes the blanks before it. An
// unterminated `<!--` is not a comment and stays.
function withoutHtmlComments(html) {
  let out = "";
  let pos = 0;
  for (;;) {
    const start = html.indexOf("<!--", pos);
    if (start < 0) break;
    const close = html.indexOf("-->", start + 4);
    if (close < 0) break;
    out += html.slice(pos, start);
    let end = close + 3;
    const lineStart = out.lastIndexOf("\n") + 1;
    const newline = html.indexOf("\n", end);
    const restOfLine = html.slice(end, newline < 0 ? html.length : newline);
    const atLineStart = out.slice(lineStart).trim() === "";
    if (restOfLine.trim() === "") {
      if (atLineStart) {
        out = out.slice(0, lineStart);
        end = newline < 0 ? html.length : newline + 1;
      } else {
        out = out.replace(/[ \t]+$/, "");
        end = newline < 0 ? html.length : newline;
      }
    } else if (atLineStart) {
      end += restOfLine.length - restOfLine.trimStart().length;
    }
    pos = end;
  }
  return out + html.slice(pos);
}

const isComment = (c) => c.type === "html_inline" && c.content.startsWith("<!--");

// An inline token's children without its comments. Of the blanks around a removed
// comment one is kept between two texts, none at either end of the paragraph.
function withoutCommentChildren(children) {
  const out = [];
  for (let i = 0; i < children.length; i++) {
    const c = children[i];
    if (!isComment(c)) {
      out.push(c);
      continue;
    }
    const prev = out[out.length - 1];
    const next = children[i + 1];
    const prevText = prev?.type === "text";
    const nextText = next?.type === "text" && !isComment(next);
    if (prevText && (!next || (nextText && /^[ \t]/.test(next.content))))
      prev.content = prev.content.replace(/[ \t]+$/, "");
    else if (!prev && nextText) next.content = next.content.replace(/^[ \t]+/, "");
  }
  return out.filter((c) => c.type !== "text" || c.content !== "");
}

function stripHtmlCommentsPlugin(md) {
  md.core.ruler.push("strip-html-comments", (state) => {
    const kept = [];
    for (const t of state.tokens) {
      if (t.type === "html_block") {
        if (!t.content.includes("<!--") || RAW_TEXT_ELEMENT_RE.test(t.content)) {
          kept.push(t);
          continue;
        }
        t.content = withoutHtmlComments(t.content);
        if (t.content.trim() === "") continue;
      } else if (
        t.type === "inline" &&
        t.children?.some((c) => c.type === "html_inline" && c.content.startsWith("<!--"))
      ) {
        t.children = withoutCommentChildren(t.children);
      }
      kept.push(t);
    }
    state.tokens = kept;
  });
}

// kramdown pairs adjacent `**` markers left-to-right (1st with 2nd,
// 3rd with 4th, ...). markdown-it follows CommonMark's emphasis rule,
// which prefers nesting when intermediate `**` markers can both open
// and close (e.g. `**X"**Y**"Z**` -> outer strong wrapping an inner
// strong). Detect the depth-2 nested-strong-with-text shape and
// flatten it back to two sibling strongs with the inner content as
// plain text between them.
function flattenAdjacentStrongPlugin(md) {
  md.core.ruler.after("inline", "flatten-adjacent-strong", (state) => {
    walkInlineChildren(state.tokens, (children) => {
      let i = 0;
      while (i < children.length) {
        // Pattern (level L):
        //   [i  ] strong_open  (level L)
        //   [i+1] text          (level L+1)   -- non-empty, "outer-left"
        //   [i+2] strong_open  (level L+1)
        //   [i+3] text          (level L+2)   -- "inner"
        //   [i+4] strong_close (level L+1)
        //   [i+5] text          (level L+1)   -- non-empty, "outer-right"
        //   [i+6] strong_close (level L)
        const t0 = children[i];
        if (
          t0 &&
          t0.type === "strong_open" &&
          children[i + 1]?.type === "text" &&
          children[i + 2]?.type === "strong_open" &&
          children[i + 3]?.type === "text" &&
          children[i + 4]?.type === "strong_close" &&
          children[i + 5]?.type === "text" &&
          children[i + 6]?.type === "strong_close" &&
          children[i + 2].markup === t0.markup &&
          children[i + 4].markup === t0.markup &&
          children[i + 6].markup === t0.markup
        ) {
          // Repair the nesting:
          //   inner strong_open  -> outer strong_close
          //   inner strong_close -> outer strong_open
          // Level of each remaining content drops by one (was inside
          // the outer-then-inner stack, now only one deep at most).
          const innerOpen = children[i + 2];
          const innerClose = children[i + 4];
          const baseLevel = t0.level;
          innerOpen.type = "strong_close";
          innerOpen.tag = "strong";
          innerOpen.nesting = -1;
          innerOpen.level = baseLevel;
          innerClose.type = "strong_open";
          innerClose.tag = "strong";
          innerClose.nesting = 1;
          innerClose.level = baseLevel;
          // Plain-text middle is now at level baseLevel.
          children[i + 3].level = baseLevel;
          // Outer-left / outer-right texts retain their levels (still
          // inside a strong each).
          // No re-numbering of subsequent tokens needed -- levels are
          // only used by the renderer for indentation and our other
          // post-passes; the outer strong_close at i+6 is already at
          // baseLevel.
          i += 7;
          continue;
        }
        i++;
      }
    });
  });
}

// markdown-it's `replacements` core rule collapses every run of 2+ dots
// (`.{2,}`) to a single ellipsis `…`. kramdown is stricter: it converts
// exactly THREE consecutive dots to `…` and leaves any extra dots as
// plain dots. The two behaviours diverge on `....`, `.....`, etc.:
// kramdown writes `….`, `…..`, ...; markdown-it writes `…` for any run of
// two or more dots. Keep the dots past the third: before `replacements`,
// each of them becomes HELD_DOT, which the `.{2,}` rule does not match, so
// the run's first three collapse to `…`; straight after it, HELD_DOT turns
// back into a dot. The run is counted in the text token that holds it, so
// code spans, links and the other typographic rules cannot put it out of
// step. A run after `?` or `!` is left alone: markdown-it writes `?..`
// there, and so does this.
const HELD_DOT = "\u{E000}";
const LONG_DOT_RUN_RE = /(?<![?!.])\.{4,}/g;

function kramdownEllipsisPlugin(md) {
  // Only the tokens the first rule changed are restored, so a HELD_DOT
  // written in a page stays as written.
  const held = new WeakSet();
  md.core.ruler.before("replacements", "kramdown-ellipsis-hold", (state) => {
    for (const blk of state.tokens) {
      if (blk.type !== "inline" || !blk.children) continue;
      for (const t of blk.children) {
        if (t.type !== "text" || !t.content.includes("....") || t.content.includes(HELD_DOT)) continue;
        t.content = t.content.replace(LONG_DOT_RUN_RE, (run) => "..." + HELD_DOT.repeat(run.length - 3));
        held.add(t);
      }
    }
  });
  md.core.ruler.after("replacements", "kramdown-ellipsis", (state) => {
    for (const blk of state.tokens) {
      if (blk.type !== "inline" || !blk.children) continue;
      for (const t of blk.children) {
        if (held.has(t)) t.content = t.content.replaceAll(HELD_DOT, ".");
      }
    }
  });
}

// ---------- kramdown-style smart dashes -------------------------------------
//
// markdown-it's typographer converts `--` -> en-dash only when neither
// side is whitespace ("word--word"). kramdown converts unconditionally:
// `word-- word` -> `word– word`. Run a small pass over inline text
// tokens after markdown-it's typographer has finished, replacing the
// remaining `---` with em-dash and `--` with en-dash. text tokens
// inside code spans and code blocks are separate token types
// (code_inline / code_block / fence), so they're untouched.

function kramdownDashesPlugin(md) {
  md.core.ruler.after("replacements", "kramdown-dashes", (state) => {
    walkTokens(state.tokens, (t) => {
      if (t.type !== "text") return;
      if (t.content.includes("--")) {
        t.content = t.content.replace(/---/g, "—").replace(/--/g, "–");
      }
      // kramdown's smart_quotes also converts `<<` and `>>` to
      // left/right guillemets (« / »). markdown-it's typographer
      // doesn't, so do it here. Same `text`-token-only restriction
      // keeps code spans and code blocks untouched.
      if (t.content.includes("<<")) t.content = t.content.replace(/<<(?!=)/g, "«").replace(/<<=/g, "«=");
      if (t.content.includes(">>")) t.content = t.content.replace(/>>(?!=)/g, "»").replace(/>>=/g, "»=");
    });
  });

  // kramdown converts a straight ASCII `'` to a right-curly `’` whenever
  // it follows non-whitespace and precedes a word character -- so
  // `C/C++'s typedef` becomes `C/C++’s typedef`. markdown-it's
  // smartquotes rule is stricter (requires word-char on both sides), so
  // possessive apostrophes after punctuation stay straight. Run a
  // post-smartquotes sweep on text tokens to fix the gap.
  md.core.ruler.after("smartquotes", "kramdown-possessive", (state) => {
    walkTokens(state.tokens, (t) => {
      if (t.type !== "text") return;
      if (!t.content.includes("'")) return;
      t.content = t.content.replace(/(\S)'(?=\w)/g, "$1’");
    });
  });

  // Kramdown's smart_quotes parser operates on the raw source string,
  // so quotes adjacent to emphasis markers (`**"foo"**`) end up curled
  // via rules that markdown-it's typographer (which operates on parsed
  // text tokens, blind to siblings) can't reach. The result: Jekyll
  // renders `<strong>"foo"</strong>` while we emit `<strong>&quot;foo&quot;</strong>`.
  //
  // Translate kramdown's two relevant patterns into token-stream rules:
  //
  // * Text ending with `"` / `'` followed by strong_close or em_close
  //   (`**...X"**`). Source scanner is positioned at X (the char before
  //   the quote, in the same text); rule 6 `(SQ_CLOSE)(quote)` fires
  //   when X is in SQ_CLOSE = `[^ \\\t\r\n\[{(-]`, otherwise rule 9
  //   catchall renders it as the opening curly form. Mirror: rdquo /
  //   rsquo if X is a "closing-friendly" char, ldquo / lsquo otherwise.
  //
  // * Text starting with `"` / `'` preceded by strong_open or em_open
  //   (`**"X...**`). Source scanner is positioned at the quote (the
  //   `**` was already consumed). Rules in order:
  //     - rule 1 (rquote1, SQ_PUNCT lookahead) -> rdquo if next char
  //       in same text is one of [!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~].
  //     - rule 7 (rquote1, \s|s\b|$ lookahead) -> rdquo if next char
  //       is whitespace, `s` at word boundary, or end of content.
  //     - else falls through to rule 9 catchall -> ldquo.
  md.core.ruler.after("smartquotes", "kramdown-quote-near-emphasis", (state) => {
    walkInlineChildren(state.tokens, (children) => {
      for (let i = 0; i < children.length; i++) {
        const t = children[i];
        if (t.type !== "text" || !t.content) continue;
        const last = t.content[t.content.length - 1];
        if ((last === '"' || last === "'") && isEmphasisClose(children[i + 1])) {
          // Char before the quote, in the same text token.
          const charBefore = t.content.length >= 2 ? t.content[t.content.length - 2] : "";
          const closing = !SQ_CLOSE_EXCLUDED.has(charBefore) && charBefore !== "";
          if (closing) {
            t.content = t.content.slice(0, -1) + (last === '"' ? "”" : "’");
          } else {
            t.content = t.content.slice(0, -1) + (last === '"' ? "“" : "‘");
          }
        }
        const first = t.content[0];
        if ((first === '"' || first === "'") && isEmphasisOpen(children[i - 1])) {
          const charAfter = t.content.length >= 2 ? t.content[1] : "";
          let closing = false;
          if (charAfter === "")
            closing = true; // rule 7 EOL branch
          else if (SQ_PUNCT_RE.test(charAfter))
            closing = true; // rule 1
          else if (/\s/.test(charAfter)) closing = true; // rule 7 \s branch
          if (closing) {
            t.content = (first === '"' ? "”" : "’") + t.content.slice(1);
          } else {
            t.content = (first === '"' ? "“" : "‘") + t.content.slice(1);
          }
        }
        // Text starting with a quote whose previous sibling is an
        // emphasis CLOSE (e.g. `*foo*'th` or `**foo**'s`). markdown-it
        // already curls this as `’` / `”` (closing). kramdown's
        // scanner at this position runs the same rule cascade as text
        // after emphasis_open above:
        //   - rule 1 (next char SQ_PUNCT)              -> closing
        //   - rule 7 EOL / `\s` / `s\b` lookahead      -> closing
        //   - else (word char follows, not `s\b`)      -> rule 9 -> opening
        // The `s\b` branch of rule 7 fires for the apostrophe-s
        // possessive (`*foo*'s`), keeping it closing. Other word
        // characters fall through to rule 9 and flip to opening.
        if ((first === "’" || first === "”") && isEmphasisClose(children[i - 1])) {
          const charAfter = t.content.length >= 2 ? t.content[1] : "";
          const charAfter2 = t.content.length >= 3 ? t.content[2] : "";
          let closing = false;
          if (charAfter === "") closing = true;
          else if (SQ_PUNCT_RE.test(charAfter)) closing = true;
          else if (/\s/.test(charAfter)) closing = true;
          else if (first === "’" && charAfter === "s" && !/\w/.test(charAfter2)) closing = true;
          if (!closing) {
            t.content = (first === "’" ? "‘" : "“") + t.content.slice(1);
          }
        }
      }
    });
  });
}

// kramdown's SQ_CLOSE = `[^ \\\t\r\n\[{(-]`: characters that, when they
// appear just before a quote, mark that quote as "closing" via rule 6.
// Encode the EXCLUDED set so a positive lookup gives us the inverse.
const SQ_CLOSE_EXCLUDED = new Set([" ", "\\", "\t", "\r", "\n", "[", "{", "(", "-"]);

// kramdown's SQ_PUNCT character class.
const SQ_PUNCT_RE = /[!"#$%&'()*+,\-./:;<=>?@[\\\]^_`{|}~]/;

// Apply kramdown-style smart-quote conversion to a raw HTML body --
// used for content inside `<summary markdown=span>...</summary>` and
// similar inline elements where kramdown's HTML parser descends and
// applies inline conversions. Implements the same SQ_RULES cascade
// (rules 1, 6, 7, 9) on the raw text outside of nested tags:
//   - `<context-char>"`  -> rdquo   (rule 6: SQ_CLOSE before quote)
//   - `"<word-like>`     -> rdquo via rule 7 (s\b) or fall to ldquo
// Conservative scan -- only converts straight `'` / `"` that look like
// English text quotes; leaves HTML attribute quotes alone by skipping
// content inside `<...>` brackets.
function applyKramdownSmartQuotes(body) {
  if (!/['"]/.test(body)) return body;
  // Walk char-by-char, skipping anything between `<` and `>` (inline
  // tags) and any HTML entity. Track "previous visible char" so we can
  // decide whether each `'` / `"` is opening or closing.
  let out = "";
  let i = 0;
  let prev = ""; // last non-tag char emitted (or "" at start)
  while (i < body.length) {
    const ch = body[i];
    if (ch === "<") {
      const end = body.indexOf(">", i);
      if (end < 0) {
        out += body.slice(i);
        break;
      }
      out += body.slice(i, end + 1);
      i = end + 1;
      prev = ">";
      continue;
    }
    if (ch === "'" || ch === '"') {
      const next = body[i + 1] || "";
      const isDouble = ch === '"';
      // Rule 1 (kramdown SQ rule 126): quote followed by SQ_PUNCT -> rquote.
      // Rule 7 (rule 139): quote followed by whitespace / `s\b` / EOL -> rquote.
      // Rule 6 (rule 137): SQ_CLOSE before quote -> rquote.
      // Default fall-through: ldquo.
      const closingByPunct = SQ_PUNCT_RE.test(next);
      const closingByWS = /\s/.test(next) || next === "";
      const closingByS = !isDouble && next === "s" && !/\w/.test(body[i + 2] || "");
      const closingByPrev = prev !== "" && !SQ_CLOSE_EXCLUDED.has(prev);
      const closing = closingByPunct || closingByWS || closingByS || closingByPrev;
      out += closing ? (isDouble ? "”" : "’") : isDouble ? "“" : "‘";
      prev = ch;
      i++;
      continue;
    }
    out += ch;
    prev = ch;
    i++;
  }
  return out;
}

function isEmphasisOpen(tok) {
  return tok && (tok.type === "strong_open" || tok.type === "em_open");
}
function isEmphasisClose(tok) {
  // Treat `code_inline` like an emphasis_close for smart-quote purposes:
  // kramdown's source-position scanner sees `\`...\`'word` the same as
  // `*...*'word` -- the backtick is consumed first, scanner lands AT
  // the quote, and the same rule cascade fires.
  return tok && (tok.type === "strong_close" || tok.type === "em_close" || tok.type === "code_inline");
}

// Walk inline-token children arrays so a visitor can examine adjacent
// siblings. The plain walkTokens helper recurses but only sees one token
// at a time -- this variant invokes the visitor once per inline token's
// children array (the level at which siblings live).
function walkInlineChildren(tokens, visit) {
  for (const t of tokens) {
    if (t.type === "inline" && Array.isArray(t.children)) {
      visit(t.children);
    }
  }
}

// ---------- standalone IAL forward attachment -------------------------------
//
// kramdown rule: a standalone block IAL (an IAL that takes up an entire
// paragraph) attaches to the FOLLOWING block, not the preceding one.
// markdown-it-attrs attaches them to the paragraph itself, leaving the
// paragraph's inline children empty. Detect that, move the attrs to the
// next block-level token, and splice out the now-empty paragraph triplet.

function standaloneIalForwardPlugin(md) {
  // kramdown's standalone-IAL attachment is direction-sensitive:
  //   - IAL adjacent to the previous block (no blank line between)
  //     attaches BACKWARD to that block.
  //   - IAL separated by a blank line attaches FORWARD to the next
  //     block.
  // markdown-it-attrs always parses the IAL as its own paragraph and
  // sets the attrs on it -- losing both behaviours. Detect the
  // standalone shape (paragraph whose inline content was entirely
  // consumed as attrs) and re-target the attrs onto the right
  // neighbour using token.map to look up the source-line gap.
  md.core.ruler.after("curly_attributes", "standalone-ial-attach", (state) => {
    const toks = state.tokens;
    // Lines previously occupied by a now-removed standalone IAL --
    // counts as "non-blank" when checking adjacency for a following
    // IAL (so multiple consecutive IALs all attach to the same
    // preceding block, as kramdown does).
    const consumedLines = new Set();
    for (let i = 0; i < toks.length; i++) {
      const open = toks[i];
      if (open.type !== "paragraph_open") continue;
      if (!open.attrs || open.attrs.length === 0) continue;
      const inline = toks[i + 1];
      if (inline?.type !== "inline") continue;
      const hasVisibleContent = (inline.children || []).some((c) => c.type !== "text" || c.content !== "");
      if (hasVisibleContent) continue;
      const close = toks[i + 2];
      if (close?.type !== "paragraph_close") continue;

      const prev = toks[i - 1];
      const next = toks[i + 3];

      let target = null;
      if (prev && isHeadingOrParagraphClose(prev)) {
        const prevOpen = findBlockOpenFor(toks, i - 1);
        if (prevOpen && ialAdjacentToPrev(prevOpen, open, consumedLines)) {
          target = prevOpen;
        }
      }
      if (!target && next) target = next;

      if (!target) continue;
      // markdown-it-attrs collapses consecutive standalone IALs into the
      // attrs of the first paragraph but emits them in REVERSE source
      // order. Detect the multi-line IAL paragraph (map spans 2+ lines)
      // and reverse to match kramdown's source-order output.
      const attrsList = open.map && open.map[1] - open.map[0] > 1 ? [...open.attrs].reverse() : open.attrs;
      mergeAttrs(target, attrsList);
      // Record the IAL's source line range so a following IAL one
      // line away still counts as adjacent to the heading.
      if (open.map) {
        for (let ln = open.map[0]; ln < open.map[1]; ln++) consumedLines.add(ln);
      }
      toks.splice(i, 3);
      i--;
    }
  });
}

// True when the IAL paragraph's first source line is the line right
// after the previous block's last source line (no blank line gap).
// Consumed lines (occupied by removed earlier IALs) count as belonging
// to the previous block so that consecutive `{: ... }` IALs all attach
// to the same heading.
function ialAdjacentToPrev(prevOpen, ialOpen, consumedLines) {
  if (!prevOpen.map || !ialOpen.map) return false;
  let line = prevOpen.map[1];
  while (line < ialOpen.map[0]) {
    if (!consumedLines.has(line)) return false;
    line++;
  }
  return true;
}

function isHeadingOrParagraphClose(t) {
  return t.type === "heading_close" || t.type === "paragraph_close";
}

// Walk back from a close token to its matching open token at the same
// nesting level. Tag matches (h1 close -> h1 open, p close -> p open).
function findBlockOpenFor(toks, closeIdx) {
  const close = toks[closeIdx];
  const openType = close.type.replace("_close", "_open");
  let depth = 0;
  for (let k = closeIdx; k >= 0; k--) {
    const t = toks[k];
    if (t.type === close.type && t.tag === close.tag) depth++;
    else if (t.type === openType && t.tag === close.tag) {
      depth--;
      if (depth === 0) return t;
    }
  }
  return null;
}

// ---------- loose-deflist <p> rewrap ----------------------------------------
//
// markdown-it-deflist emits paragraph_open / paragraph_close around every
// <dd> body but marks them `hidden=true` when the list parses as "tight".
// kramdown's rule is per-item: a definition that's separated from its
// term by a blank line wraps in <p>. Detect that gap by comparing the dt
// term's end line to the inner paragraph_open's start line and unhide
// the wrapper pair when the gap is >1.

// ---------- list-item paragraph unwrap (kramdown tightness) -----------------
//
// markdown-it determines tightness at the LIST level: any blank line
// between top-level items makes the entire list loose, which adds
// `<p>...</p>` around every item's inline content. kramdown's rule is
// per-item: an item gets `<p>` wrap only when it actually contains
// multiple paragraph blocks (e.g. inline + blank + more inline). An
// item that's just "inline + nested list" stays unwrapped.
//
// We post-process after block parsing: for each list_item_open, count
// the top-level paragraph_open tokens. If there's exactly one (the
// initial inline content), hide its paragraph_open / paragraph_close
// to match kramdown's tight emit.

function tightLooseListPlugin(md) {
  md.core.ruler.after("block", "tight-loose-list", (state) => {
    const srcLines = state.src.split("\n");
    const toks = state.tokens;
    // Records per-item tightness decisions so the post-pass can apply
    // kramdown's "last item is loose unless an earlier sibling is
    // tight" rule (see kramdown/parser/kramdown/list.rb#132-139).
    // Keyed by list_item_open token index; value = { wouldBeTight,
    // listListOpenIdx, paraOpenIdx, paraCloseIdx }.
    const decisions = new Map();
    // Map of list_open index -> array of contained item indices.
    const listItems = new Map();

    for (let i = 0; i < toks.length; i++) {
      if (toks[i].type !== "list_item_open") continue;
      const itemLevel = toks[i].level;
      const itemMap = toks[i].map;
      let firstParaOpenIdx = -1;
      let extraParagraphs = false;
      let nextBlockAfterParaMap = null;
      let close = -1;
      for (let j = i + 1; j < toks.length; j++) {
        const t = toks[j];
        if (t.level === itemLevel && t.type === "list_item_close") {
          close = j;
          break;
        }
        if (t.type === "paragraph_open" && t.level === itemLevel + 1) {
          if (firstParaOpenIdx < 0) firstParaOpenIdx = j;
          else extraParagraphs = true;
        }
        // First level-+1 block AFTER the first paragraph (nested list,
        // code block, etc.). Captures the start line so we can tell
        // whether the paragraph and that block are blank-separated.
        if (
          firstParaOpenIdx >= 0 &&
          nextBlockAfterParaMap === null &&
          t.level === itemLevel + 1 &&
          j > firstParaOpenIdx &&
          t.type !== "inline" &&
          t.type !== "paragraph_close" &&
          t.type !== "paragraph_open"
        ) {
          nextBlockAfterParaMap = t.map;
        }
      }
      if (close < 0 || firstParaOpenIdx < 0 || extraParagraphs) continue;
      const pOpen = toks[firstParaOpenIdx];
      const hasNested = nextBlockAfterParaMap !== null;
      const internalBlank = paragraphHasTrailingBlank(srcLines, pOpen.map, nextBlockAfterParaMap);
      const siblingBlank = !hasNested && hasSiblingBlank(srcLines, toks, i, close, itemMap);
      // Find the enclosing list_open by walking back to a token of
      // level itemLevel - 1 with type list_open / bullet_list_open /
      // ordered_list_open.
      let listOpenIdx = -1;
      for (let k = i - 1; k >= 0; k--) {
        const t = toks[k];
        if (t.level === itemLevel - 1 && (t.type === "bullet_list_open" || t.type === "ordered_list_open")) {
          listOpenIdx = k;
          break;
        }
      }
      if (!listItems.has(listOpenIdx)) listItems.set(listOpenIdx, []);
      listItems.get(listOpenIdx).push(i);
      // Find this item's paragraph_close.
      let paraCloseIdx = -1;
      for (let j = firstParaOpenIdx + 1; j < close; j++) {
        if (toks[j].type === "paragraph_close" && toks[j].level === pOpen.level) {
          paraCloseIdx = j;
          break;
        }
      }
      const wouldBeTight = !internalBlank && !siblingBlank && paraCloseIdx >= 0;
      decisions.set(i, { wouldBeTight, paraOpenIdx: firstParaOpenIdx, paraCloseIdx, listOpenIdx });
    }

    // Apply kramdown's last-item rule: if the LAST item in a list would
    // be tight, but NO earlier item is tight, leave it loose. This
    // matches the condition 3 third sub-branch in kramdown's source:
    // tight only if some earlier sibling has already been marked
    // transparent (or has a non-paragraph first child).
    for (const [, items] of listItems) {
      if (items.length < 2) continue;
      const lastIdx = items[items.length - 1];
      const lastDecision = decisions.get(lastIdx);
      if (!lastDecision || !lastDecision.wouldBeTight) continue;
      let anyEarlierTight = false;
      for (let k = 0; k < items.length - 1; k++) {
        const d = decisions.get(items[k]);
        if (d && d.wouldBeTight) {
          anyEarlierTight = true;
          break;
        }
      }
      if (!anyEarlierTight) {
        lastDecision.wouldBeTight = false;
      }
    }

    // Apply decisions: hide the paragraph open/close for tight items.
    for (const d of decisions.values()) {
      if (d.wouldBeTight) {
        toks[d.paraOpenIdx].hidden = true;
        toks[d.paraCloseIdx].hidden = true;
      }
    }
  });
}

function paragraphHasTrailingBlank(srcLines, paraMap, nextBlockMap) {
  // Returns true only when there's a following block within the item
  // AND a blank line separates the paragraph from it. The trailing
  // blank line that just marks the item's end (no following sibling
  // block inside the item) is the LIST's separator, not internal.
  if (!paraMap || !nextBlockMap) return false;
  if (nextBlockMap[0] <= paraMap[1]) return false;
  return (srcLines[paraMap[1]] ?? "").trim() === "";
}

function hasSiblingBlank(srcLines, toks, openIdx, closeIdx, itemMap) {
  if (!itemMap) return false;
  const lastIdx = itemMap[1] - 1;
  if (
    lastIdx >= itemMap[0] &&
    (srcLines[lastIdx] ?? "").trim() === "" &&
    toks[closeIdx + 1]?.type === "list_item_open"
  ) {
    return true;
  }
  const prevClose = toks[openIdx - 1];
  if (prevClose?.type === "list_item_close" && prevClose.level === toks[openIdx].level) {
    let depth = 0;
    for (let k = openIdx - 1; k >= 0; k--) {
      const t = toks[k];
      if (t.type === "list_item_close" && t.level === toks[openIdx].level) depth++;
      else if (t.type === "list_item_open" && t.level === toks[openIdx].level) {
        depth--;
        if (depth === 0) {
          const prevMap = t.map;
          if (prevMap) {
            const prevLast = prevMap[1] - 1;
            if (prevLast >= prevMap[0] && (srcLines[prevLast] ?? "").trim() === "") {
              return true;
            }
          }
          break;
        }
      }
    }
  }
  return false;
}

function looseDeflistPlugin(md) {
  // Per-dd looseness, equivalent to the per-item rule we apply on
  // bullet/ordered lists:
  //   - The first <p> inside a <dd> is wrapped IFF the source has a
  //     blank line between the term and the definition (loose form).
  //   - Otherwise the <p> is suppressed.
  // markdown-it-deflist tracks looseness at the LIST level, so any
  // multi-block <dd> in the list flips every other <dd>'s paragraph
  // to visible. Override both directions: hide when tight, unhide
  // when loose.
  md.core.ruler.after("block", "deflist-tightness", (state) => {
    const toks = state.tokens;
    let dtEndLine = -1;
    for (let i = 0; i < toks.length; i++) {
      const t = toks[i];
      if (t.type === "dt_open") {
        dtEndLine = -1;
      } else if (t.type === "dt_close") {
        const inline = toks[i - 1];
        dtEndLine = inline?.map?.[1] ?? -1;
      } else if (t.type === "dd_open") {
        const inner = toks[i + 1];
        if (inner?.type !== "paragraph_open") continue;
        const ddLevel = t.level;
        let ddClose = -1;
        let nextBlockAfterParaMap = null;
        for (let j = i + 1; j < toks.length; j++) {
          const u = toks[j];
          if (u.level === ddLevel && u.type === "dd_close") {
            ddClose = j;
            break;
          }
          if (
            j > i + 1 &&
            u.level === ddLevel + 1 &&
            u.type !== "paragraph_close" &&
            u.type !== "inline" &&
            u.type !== "paragraph_open" &&
            nextBlockAfterParaMap === null
          ) {
            nextBlockAfterParaMap = u.map;
          }
        }
        if (ddClose < 0) continue;
        // kramdown's deflist looseness, observed empirically: ONLY the
        // dt -> dd blank line counts. An internal blank between the
        // definition's first paragraph and a nested list inside the
        // same dd does NOT make the dd loose (unlike bullet/ordered
        // list items, where it does). Keep the rule narrow.
        const wantsLoose = dtEndLine >= 0 && inner.map && inner.map[0] > dtEndLine + 1;
        if (inner.hidden === !wantsLoose) continue;
        inner.hidden = !wantsLoose;
        for (let j = i + 2; j < ddClose; j++) {
          if (toks[j].type === "paragraph_close" && toks[j].level === inner.level) {
            toks[j].hidden = inner.hidden;
            break;
          }
        }
      }
    }
  });
}

function mergeAttrs(token, addAttrs) {
  for (const [key, value] of addAttrs) {
    if (key === "class") {
      const cur = token.attrGet("class");
      token.attrSet("class", cur ? `${cur} ${value}` : value);
    } else {
      token.attrSet(key, value);
    }
  }
}

// ---------- §5.5 footnote rendering overrides -------------------------------
//
// markdown-it-footnote emits `fnref-N` (hyphen) + `footnote-backref` /
// `<section class="footnotes">` shapes. kramdown emits `fnref:N` (colon) +
// `reversefootnote` / `<div class="footnotes">`. Five render-rule
// overrides line up with the kramdown shapes verified against
// docs/_site/Features/index.html.

function configureFootnotes(md) {
  md.renderer.rules.footnote_ref = (tokens, idx) => {
    const id = tokens[idx].meta.id;
    const n = id + 1;
    return `<sup id="fnref:${n}"><a href="#fn:${n}" class="footnote" rel="footnote" role="doc-noteref">${n}</a></sup>`;
  };

  md.renderer.rules.footnote_anchor = (tokens, idx) => {
    const id = tokens[idx].meta.id;
    const n = id + 1;
    // Leading U+00A0 (nbsp) matches kramdown's footnote_anchor output --
    // kramdown emits a nbsp before the backref so the arrow doesn't
    // line-wrap away from the footnote text.
    return ` <a href="#fnref:${n}" class="reversefootnote" role="doc-backlink">&#8617;</a>`;
  };

  md.renderer.rules.footnote_open = (tokens, idx) => {
    const id = tokens[idx].meta.id;
    const n = id + 1;
    return `<li id="fn:${n}">\n`;
  };

  md.renderer.rules.footnote_block_open = () => `<div class="footnotes" role="doc-endnotes">\n<ol>\n`;

  md.renderer.rules.footnote_block_close = () => `</ol>\n</div>\n`;
}

// ---------- §5.6 header-id plugin -------------------------------------------
//
// Auto-assign kramdown-style id="..." on every heading that doesn't carry
// an explicit `{: #foo }`. Slug algorithm: lowercase, runs of non-alnum
// collapse to `-`, strip leading/trailing `-`, "section" fallback for
// empty, suffix duplicates with `-1`, `-2`, ...

// ---------- heading-level normalization (a11y: WCAG heading-order) ----------
//
// House style writes a chapter as `# X` and its sections as `### Y`, skipping
// `##` on purpose: it keeps GitHub's own rendering of the raw markdown at a
// modest heading size, without pushing any styling into the source. On the
// built site that skip is a heading-order defect -- a section sits two levels
// below its chapter with no h2 between (WCAG 1.3.1, best practice).
//
// The house style is deprecated -- new content uses `##` for sections (see the
// page template in WIP.Authoring.md). This rule is a migration bridge: it
// repairs the legacy pages at build time so they are not all edited at once
// (diff churn), and it self-retires per page as each is rewritten to use
// `##` (a page with a real h2 no longer matches the trigger). Fixing it here
// also keeps the
// markdown untouched and GitHub keeps its `###`. Deliberately narrow, per the maintainer's rule: fire ONLY on a page
// that uses h1 and h3 but no h2 -- the unambiguous house-style shape. A page
// that already uses h2 is left exactly as authored (its levels are the
// author's own structure, not the workaround). A raw HTML `<h2>` counts as an
// h2 for that check too, even though it never produces a heading_open token --
// otherwise a page mixing a hand-written `<h2>` with markdown `###` sections
// would get its h3s promoted right over the author's own structure.
//
// Each heading is renumbered against a stack of its still-open ancestors --
// the same shape a document outline builds -- rather than shifted by a fixed
// amount. Walking the headings in order: pop any stack entry whose raw level
// is >= this heading's (it is a sibling or a finished deeper section, not an
// ancestor), then this heading's normalized level is one below whatever
// ancestor is left on top (or h1 if the stack is now empty), and it is
// pushed in turn. That closes the h1->h3 gap (h3 becomes h2) and moves any
// directly nested tail down with it (h4->h3, ...), which is what "raise h3
// to h2" means in the common case. It also keeps two headings written at the
// same raw level as SIBLINGS even when only one of them contains a deeper
// run -- Reference/Core/Open has two `###` sections around a run of six
// `####` subsections, and both `###`s must land on h2, not h2 then h3 for
// the second one just because the stack was deeper when it was reached. A
// fixed -1 offset would get that page right too (nothing in it is more than
// one level deeper than its own section), but it only closes the FIRST gap
// it meets: a page with a second, independent skip further down (h3
// straight to h5, no h4) would come out h1/h2/h4 -- the skip reappears one
// level over and no longer matches anything in the source, so it would go
// unnoticed. The stack closes every gap in one pass; a heading returning to
// a shallower level is left alone, since going shallower is never a skip.
// Runs before header-id and toc so heading ids and the in-page table of
// contents are built from the final levels. Multiple h1 "chapters" on one
// page are intentional and preserved.
const RAW_H2_BLOCK_RE = /<h2[\s>]/i;

function headingLevelNormalizePlugin(md) {
  md.core.ruler.before("header-id", "heading-normalize-levels", (state) => {
    const toks = state.tokens;
    const present = new Set();
    for (const t of toks) {
      if (t.type === "heading_open") present.add(Number(t.tag.slice(1)));
      else if (t.type === "html_block" && RAW_H2_BLOCK_RE.test(t.content)) present.add(2);
    }
    if (!(present.has(1) && present.has(3) && !present.has(2))) return;

    const stack = []; // {raw, normalized} chain of still-open ancestor headings
    let openNormalized = null; // level assigned to the open heading_open, reused by its heading_close
    for (const t of toks) {
      let level;
      if (t.type === "heading_open") {
        level = Number(t.tag.slice(1));
        while (stack.length && stack[stack.length - 1].raw >= level) stack.pop();
        const parent = stack.length ? stack[stack.length - 1].normalized : 0;
        openNormalized = parent + 1;
        stack.push({ raw: level, normalized: openNormalized });
      } else if (t.type === "heading_close" && openNormalized !== null) {
        level = Number(t.tag.slice(1));
      } else {
        continue;
      }
      if (openNormalized === level) continue;
      t.tag = `h${openNormalized}`;
      if (t.markup) t.markup = "#".repeat(openNormalized);
    }
  });
}

function headerIdPlugin(md) {
  md.core.ruler.push("header-id", (state) => {
    const used = new Map();
    let openHeading = null;
    for (const t of state.tokens) {
      if (t.type === "heading_open") {
        openHeading = t;
      } else if (t.type === "heading_close") {
        openHeading = null;
      } else if (openHeading && t.type === "inline") {
        if (openHeading.attrGet("id")) continue;
        const text = headingText(t.children);
        const base = kramdownSlug(text);
        openHeading.attrSet("id", uniqueSlug(base, used));
      }
    }
  });
}

// Hand-marked search index entries (WIP.Search.md, "Hand-marked index
// entries"). A heading's `{: index="..." }` names the terms
// a reader looks up to find that section, as a book's index would, and
// `{: index_also="..." }` the terms it is a strong second answer for. Both
// are lifted off the heading here, once header-id has given it its id, into
// env.searchIndexMarks as `{ id, index, index_also }` with the raw
// attribute values, so they never reach the HTML. search.mjs parses the
// values and attaches them to the entry holding that heading. On any other
// element the attribute would be published and do nothing, so it fails the
// build instead.
const SEARCH_INDEX_ATTRS = ["index", "index_also"];

function searchIndexMarksPlugin(md) {
  md.core.ruler.after("header-id", "search-index-marks", (state) => {
    const misplaced = (t) => {
      const name = SEARCH_INDEX_ATTRS.find((a) => t.attrGet(a) !== null);
      if (!name) return;
      throw new Error(
        `${state.env?.page?.srcRel ?? "(unknown page)"}: \`{: ${name}="..." }\` on ` +
          `${t.tag ? `<${t.tag}>` : t.type}; only a heading can carry a search index entry. ` +
          "For the whole page, use `index:` in the front matter.",
      );
    };
    for (const t of state.tokens) {
      if (t.type === "heading_open") {
        const mark = { id: t.attrGet("id") };
        let found = false;
        for (const a of SEARCH_INDEX_ATTRS) {
          const v = t.attrGet(a);
          if (v === null) continue;
          mark[a] = v;
          found = true;
          t.attrs.splice(t.attrIndex(a), 1);
        }
        if (found) (state.env.searchIndexMarks ??= []).push(mark);
      } else if (t.attrs) {
        misplaced(t);
      }
      for (const c of t.children ?? []) if (c.attrs) misplaced(c);
    }
  });
}

function headingText(children) {
  // Concatenate the visible text content from inline tokens. Skip markup
  // wrappers (em, strong, link openers) and pick up text + code spans --
  // matches kramdown's `output_text(heading)`.
  let out = "";
  for (const c of children) {
    if (c.type === "text" || c.type === "code_inline") out += c.content;
  }
  return out;
}

// kramdown-parser-gfm's generate_gfm_header_id algorithm:
//   1. lowercase
//   2. drop every char that's NOT a Unicode word char (\p{L} / \p{N} /
//      \p{M} / \p{Pc}), a hyphen, or a space
//   3. replace each space with `-`
// Notably this does NOT collapse runs of `-` and does NOT strip
// leading/trailing `-`. Emoji and punctuation drop out; the surrounding
// spaces still become hyphens, which is why headings like "🎮 X" emit
// id="-x" (leading dash).
function kramdownSlug(text) {
  const lower = text.toLowerCase();
  const filtered = [...lower].filter((c) => GFM_HEADER_CHAR_RE.test(c)).join("");
  return filtered.replaceAll(" ", "-") || "section";
}

const GFM_HEADER_CHAR_RE = /[\p{L}\p{N}\p{M}\p{Pc}\- ]/u;

function uniqueSlug(base, used) {
  const count = used.get(base) ?? 0;
  used.set(base, count + 1);
  return count === 0 ? base : `${base}-${count}`;
}

// ---------- §5.8 TOC plugin -------------------------------------------------
//
// Kramdown's `* TOC\n{:toc}` pattern. Scans for the marker bullet-list,
// collects every h2..h6 heading_open after it, emits a nested <ul
// id="markdown-toc"> with one item per heading. markdown-it-attrs sees
// `{:toc}` first and stores `toc` on the next paragraph's token; we
// detect that flag.

function tocPlugin(md) {
  md.core.ruler.after("header-id", "toc", (state) => {
    const toks = state.tokens;
    // Collect all qualifying headings up front; kramdown's TOC includes
    // every page heading regardless of position relative to the
    // `{:toc}` marker.
    const headings = collectHeadings(toks, 0);
    for (let i = 0; i < toks.length; i++) {
      const markerEnd = matchTocMarker(toks, i);
      if (markerEnd < 0) continue;
      const html = renderTocList(headings);
      const tocTok = new state.Token("html_block", "", 0);
      tocTok.content = html;
      toks.splice(i, markerEnd - i, tocTok);
    }
  });
}

// A TOC marker is the kramdown `* TOC\n{:toc}` pattern: a single-item
// bullet list whose item is "TOC", followed by a `{:toc}` IAL that
// markdown-it-attrs has applied as an attribute on the bullet list.
// We treat any bullet_list_open with a `toc` attribute as the marker.
// standaloneIalForwardPlugin never moves it: it moves only an IAL left
// as a paragraph of its own, and this one is on the list.
function matchTocMarker(toks, i) {
  const open = toks[i];
  if (open?.type !== "bullet_list_open") return -1;
  if (!open.attrs) return -1;
  if (!open.attrs.some(([k]) => k === "toc")) return -1;

  // The TOC marker consists of bullet_list_open, list_item_open,
  // paragraph_open, inline ("TOC"), paragraph_close, list_item_close,
  // bullet_list_close -- seven tokens total.
  if (toks[i + 1]?.type !== "list_item_open") return -1;
  if (toks[i + 6]?.type !== "bullet_list_close") return -1;
  return i + 7;
}

function collectHeadings(toks, from) {
  const out = [];
  for (let i = from; i < toks.length; i++) {
    const t = toks[i];
    if (t.type !== "heading_open") continue;
    const level = Number(t.tag.slice(1));
    if (level < 2 || level > 6) continue;
    const inline = toks[i + 1];
    if (inline?.type !== "inline") continue;
    const id = t.attrGet("id");
    if (!id) continue;
    // kramdown's TOC builder filters headings whose IAL set `no_toc` on
    // them. Match that.
    const cls = t.attrGet("class") ?? "";
    if (cls.split(/\s+/).includes("no_toc")) continue;
    out.push({ level, id, html: headingTocHtml(inline.children) });
  }
  return out;
}

// kramdown's TOC keeps inline `<code>` (and other inline markup) inside
// each `<li>` link's text. Mirror that by rendering a minimal subset of
// inline tokens to HTML: text, code spans, and emphasis/strong wrappers.
// Other tokens (links, images, html_inline) fall back to their visible
// text content -- kramdown drops them too. Text and code spans are escaped
// alike: the entry is element content, where a quote needs no escaping.
function headingTocHtml(children) {
  let out = "";
  for (const c of children) {
    if (c.type === "text") out += escapeMarkup(c.content);
    else if (c.type === "code_inline") {
      out += `<code class="language-plaintext highlighter-rouge">${escapeMarkup(c.content)}</code>`;
    } else if (c.type === "strong_open") out += "<strong>";
    else if (c.type === "strong_close") out += "</strong>";
    else if (c.type === "em_open") out += "<em>";
    else if (c.type === "em_close") out += "</em>";
    else if (c.type === "softbreak" || c.type === "hardbreak") out += " ";
  }
  return out;
}

function renderTocList(headings) {
  if (headings.length === 0) return `<ul id="markdown-toc"></ul>`;
  // Build a tree of TocNode from the flat heading list, then render with
  // kramdown's indentation: each <li> on its own line, leaf items
  // collapsed to one line, parent items split open-tag, nested <ul>,
  // close-tag across three lines.
  const root = { children: [] };
  const stack = [{ level: 1, node: root }];
  for (const h of headings) {
    while (stack.length > 1 && stack[stack.length - 1].level >= h.level) {
      stack.pop();
    }
    const node = { ...h, children: [] };
    stack[stack.length - 1].node.children.push(node);
    stack.push({ level: h.level, node });
  }
  const out = [`<ul id="markdown-toc">`];
  renderTocItems(root.children, "  ", out);
  out.push(`\n</ul>\n`);
  return out.join("");
}

function renderTocItems(items, indent, out) {
  for (const item of items) {
    const link = `<a href="#${item.id}" id="markdown-toc-${item.id}">${item.html}</a>`;
    if (item.children.length === 0) {
      out.push(`\n${indent}<li>${link}</li>`);
    } else {
      out.push(`\n${indent}<li>${link} <ul>`);
      renderTocItems(item.children, indent + "  ", out);
      out.push(`\n${indent}</ul>\n${indent}</li>`);
    }
  }
}

// ---------- §5.3 relative-links plugin --------------------------------------

export function buildLinkTables(pages) {
  const byPath = new Map();
  const byUrl = new Map();
  const byRedirect = new Map();

  for (const p of pages) {
    putOnce(byPath, p.srcRel, p);

    const url = p.permalink.replace(/^\//, "");
    if (url !== "") {
      putOnce(byUrl, url, p);
      if (url.endsWith("/")) putOnce(byUrl, url.replace(/\/$/, ""), p);
    }

    const redirects = [].concat(p.frontmatter.redirect_from ?? []);
    for (const r of redirects) {
      const key = String(r).replace(/^\//, "").replace(/\/$/, "");
      if (key) putOnce(byRedirect, key, p);
    }
  }

  return { byPath, byUrl, byRedirect };
}

// Serialize linkTables for cross-thread transfer. resolveLink() only reads
// .permalink from each page, so shipping [key, permalink] pairs is sufficient.
// Workers reconstruct minimal { permalink } stubs via reconstructLinkTables.
export function serializeLinkTables(lt) {
  const pairs = (m) => [...m.entries()].map(([k, p]) => [k, p.permalink]);
  return { byPath: pairs(lt.byPath), byUrl: pairs(lt.byUrl), byRedirect: pairs(lt.byRedirect) };
}

function putOnce(map, key, value) {
  if (!map.has(key)) map.set(key, value);
}

function resolveLink(href, tables, baseurl) {
  let path;
  try {
    path = decodeURIComponent(href);
  } catch {
    path = href;
  }
  const trimmed = path.replace(/\/$/, "");
  const target = tables.byPath.get(path) ?? tables.byUrl.get(trimmed) ?? tables.byRedirect.get(trimmed);
  return target ? `${baseurl}${target.permalink}` : null;
}

function relativeLinksPlugin(md, ctx) {
  md.core.ruler.push("relative-links", (state) => {
    const fromPage = state.env?.page;
    if (!fromPage) return;
    walkTokens(state.tokens, (token) => {
      let attrName;
      if (token.type === "link_open") attrName = "href";
      else if (token.type === "image") attrName = "src";
      else return;

      const idx = token.attrIndex(attrName);
      if (idx < 0) return;
      const value = token.attrs[idx][1];
      if (/^([a-z][a-z0-9+.\-]*:|#|\/\/)/i.test(value)) return;

      const [pathPart, fragPart] = splitFragment(value);
      let resolved;
      if (value.startsWith("/")) {
        // Root-absolute (`/tB/Packages/VB/Label`). jekyll-relative-links
        // still resolves these against the page tables, picking up the
        // canonical permalink form (with trailing slash for folder-
        // style index pages). Strip leading slash and look up directly.
        resolved = pathPart.replace(/^\//, "");
      } else {
        const fromDir = fromPage.srcRel.replace(/[^/]+$/, "");
        resolved = resolveBelowRoot(fromDir, pathPart);
        if (resolved === null) return;
      }
      const newValue = resolveAsset(resolved, ctx) ?? resolveLink(resolved, ctx.linkTables, ctx.baseurl);
      if (newValue) {
        token.attrs[idx][1] = fragPart ? `${newValue}#${fragPart}` : newValue;
      }
    });
  });
}

// Static assets aren't in the page-permalink tables; resolve them as
// root-absolute paths so <img src="Images/x.svg"> becomes
// <img src="/Tutorials/CEF/Images/x.svg"> the way jekyll-relative-links
// rewrites them.
function resolveAsset(resolved, ctx) {
  if (!ctx.staticFiles) return null;
  // The relative-link plugin may receive a URL-encoded `resolved` (e.g.
  // when encodeSpacesInMediaUrls() rewrote `path with space` to
  // `path%20with%20space`). The staticFiles set keys on the unencoded
  // POSIX path Phase 1 stashed; decode before lookup.
  let key = resolved;
  try {
    key = decodeURIComponent(resolved);
  } catch {}
  if (ctx.staticFiles.has(key)) {
    return `${ctx.baseurl}/${resolved}`;
  }
  return null;
}

// Mirrors jekyll-relative-links's File.expand_path-based resolution: a
// link whose `..` segments would escape the docs/ root (the Jekyll
// source directory) is left unrewritten by the upstream gem because the
// computed absolute path falls outside Dir.pwd. Return null for those
// to match that behaviour.
function resolveBelowRoot(fromDir, pathPart) {
  const parts = (fromDir + pathPart).split("/");
  const out = [];
  for (const part of parts) {
    if (part === "" || part === ".") continue;
    if (part === "..") {
      if (out.length === 0) return null;
      out.pop();
      continue;
    }
    out.push(part);
  }
  return out.join("/");
}

function walkTokens(tokens, fn) {
  for (const t of tokens) {
    fn(t);
    if (t.children) walkTokens(t.children, fn);
  }
}

// ---------- pictures in two themes (theme-pictures.mjs) ---------------------
//
// An image whose file has a light sibling among the static files (`X.png` and `X.light.png`)
// becomes two images, the light one first, with the same alt text and attributes, each with
// its theme's class and `loading="lazy"`; the light one's width and height are the page's
// scaled by the two files' pixel sizes (`ctx.pictureSizes`, pairSizes in theme-pictures.mjs),
// since the Light theme lays the IDE out a few pixels differently. The stylesheet hides the one for the other theme,
// and a lazy image that is not displayed is never fetched. A link to such a picture (the
// feature map's "Full size") becomes two links the same way, so that it opens the picture
// the reader sees. The sibling is looked up in the static-file list the build already has,
// never on disk. Runs after relativeLinksPlugin, so a static file's src is root-absolute.
//
// A page never names a light picture itself: one that does, in markdown or raw HTML, fails
// the build, since a light picture shown in both themes is the mistake this exists to stop.
// The book keeps the light picture alone (book.mjs, lightOnly).
//
// Each of the two is then shown as its SVG (X.svg, X.light.svg; theme-pictures.mjs) when
// that is among the static files, an image and a link to the picture alike, unless the
// attribute block names `png` -- `![alt](X.png){:width="190" height="337" png}` -- which
// keeps the PNGs and is removed from the output. A picture with no light sibling gets its
// SVG all the same. The light one's sizes still come from the PNG pair.
const RAW_LIGHT_REF_RE = /\b(?:src|href)\s*=\s*["']?[^"'\s>]*\.light\.(?:png|svg)(?:[?#][^"'\s>]*)?(?:["'\s>]|$)/i;

function themePairPlugin(md, ctx) {
  const urlPath = (value) => {
    const p = value.split(/[?#]/, 1)[0];
    try {
      return decodeURIComponent(p);
    } catch {
      return p;
    }
  };
  const prefix = `${ctx.baseurl || ""}/`;
  md.core.ruler.push("theme-pairs", (state) => {
    const where = state.env?.page?.srcRel ?? "a page";
    const refuse = (what) => {
      throw new Error(
        `${where}: ${what} names a light picture directly. Name the dark one, X.png: ` +
          "the build shows X.light.png beside it in the light theme",
      );
    };
    const checkRaw = (html) => {
      const m = RAW_LIGHT_REF_RE.exec(html);
      if (m) refuse(`raw HTML ${m[0].trim()}`);
    };
    const clone = (t) => {
      const c = new state.Token(t.type, t.tag, t.nesting);
      Object.assign(c, t);
      c.attrs = t.attrs ? t.attrs.map((a) => [...a]) : null;
      c.meta = t.meta ? { ...t.meta } : null;
      return c;
    };
    const mark = (t, name) => {
      setClass(t, name);
      if (t.type === "image") t.attrSet("loading", "lazy");
      t.meta = { ...(t.meta || {}), themePaired: true };
    };
    for (const block of state.tokens) {
      if (block.type === "html_block") checkRaw(block.content);
      if (block.type !== "inline" || !block.children) continue;
      const kids = block.children;
      for (let i = 0; i < kids.length; i++) {
        const t = kids[i];
        if (t.type === "html_inline") checkRaw(t.content);
        const attr = t.type === "image" ? "src" : t.type === "link_open" ? "href" : null;
        if (!attr || t.meta?.themePaired) continue;
        const keepPng = t.attrGet("png") !== null;
        if (keepPng) t.attrs = t.attrs.filter(([name]) => name !== "png");
        const value = t.attrGet(attr);
        if (!value) continue;
        const target = urlPath(value);
        if (isLightPicture(target)) refuse(`the ${t.type === "image" ? "image" : "link"} ${value}`);
        if (!ctx.staticFiles || !target.startsWith(prefix)) continue;
        const rel = target.slice(prefix.length);
        // `v`, a URL naming the picture `pngRel`, as the URL of its SVG when there is one.
        const asSvg = (v, pngRel) =>
          !keepPng && ctx.staticFiles.has(svgOf(pngRel) ?? "") ? v.replace(/\.png(?=[?#]|$)/, ".svg") : v;
        const light = lightSiblingOf(rel);
        if (!light || !ctx.staticFiles.has(light)) {
          t.attrSet(attr, asSvg(value, rel));
          continue;
        }
        const lightValue = asSvg(value.replace(/\.png(?=[?#]|$)/, ".light.png"), light);
        const darkValue = asSvg(value, rel);
        if (t.type === "image") {
          const copy = clone(t);
          copy.attrSet("src", lightValue);
          t.attrSet("src", darkValue);
          const size = ctx.pictureSizes?.[light];
          if (size) {
            for (const [attr, i] of [
              ["width", 0],
              ["height", 1],
            ]) {
              const v = copy.attrGet(attr);
              if (v !== null) copy.attrSet(attr, lightDimension(v, size[i], size[i + 2]));
            }
          }
          mark(copy, PIC_LIGHT);
          mark(t, PIC_DARK);
          kids.splice(i, 0, copy);
          i++;
          continue;
        }
        const close = findLinkClose(kids, i);
        if (close < 0) continue;
        // The light link's contents are walked next (an image in it is paired in turn);
        // both link_open tokens are marked, so neither is taken for a link to pair again.
        const copies = kids.slice(i, close + 1).map(clone);
        copies[0].attrSet("href", lightValue);
        t.attrSet("href", darkValue);
        mark(copies[0], PIC_LIGHT);
        mark(t, PIC_DARK);
        kids.splice(i, 0, ...copies);
      }
    }
  });
}

// ---------- §5.2 GFM admonitions (pre-render text rewrite) ------------------
//
// Octicon SVG strings ported from the Ruby Octicons gem (v19.21.2) --
// the same source jekyll-gfm-admonitions calls into via
// `Octicons::Octicon.new(name).to_svg`. Two cosmetic differences from
// the gem's raw output are needed for byte parity with Jekyll's final
// HTML:
//
//   1. The gem emits `<path d="..."/>` (self-closing). Kramdown's HTML
//      parser normalises self-closing tags on non-void elements to
//      `<tag>...</tag>` -- so the path lands in the rendered HTML as
//      `<path d="..."></path>`. We pre-write the explicit-close form.
//   2. Attribute order: class, viewBox, version, width, height,
//      aria-hidden -- the order the gem's `to_svg` walks `@options`.

const ICON_INFO =
  '<svg class="octicon octicon-info" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M0 8a8 8 0 1 1 16 0A8 8 0 0 1 0 8Zm8-6.5a6.5 6.5 0 1 0 0 13 6.5 6.5 0 0 0 0-13ZM6.5 7.75A.75.75 0 0 1 7.25 7h1a.75.75 0 0 1 .75.75v2.75h.25a.75.75 0 0 1 0 1.5h-2a.75.75 0 0 1 0-1.5h.25v-2h-.25a.75.75 0 0 1-.75-.75ZM8 6a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>';
const ICON_LIGHT_BULB =
  '<svg class="octicon octicon-light-bulb" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M8 1.5c-2.363 0-4 1.69-4 3.75 0 .984.424 1.625.984 2.304l.214.253c.223.264.47.556.673.848.284.411.537.896.621 1.49a.75.75 0 0 1-1.484.211c-.04-.282-.163-.547-.37-.847a8.456 8.456 0 0 0-.542-.68c-.084-.1-.173-.205-.268-.32C3.201 7.75 2.5 6.766 2.5 5.25 2.5 2.31 4.863 0 8 0s5.5 2.31 5.5 5.25c0 1.516-.701 2.5-1.328 3.259-.095.115-.184.22-.268.319-.207.245-.383.453-.541.681-.208.3-.33.565-.37.847a.751.751 0 0 1-1.485-.212c.084-.593.337-1.078.621-1.489.203-.292.45-.584.673-.848.075-.088.147-.173.213-.253.561-.679.985-1.32.985-2.304 0-2.06-1.637-3.75-4-3.75ZM5.75 12h4.5a.75.75 0 0 1 0 1.5h-4.5a.75.75 0 0 1 0-1.5ZM6 15.25a.75.75 0 0 1 .75-.75h2.5a.75.75 0 0 1 0 1.5h-2.5a.75.75 0 0 1-.75-.75Z"></path></svg>';
const ICON_REPORT =
  '<svg class="octicon octicon-report" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M0 1.75C0 .784.784 0 1.75 0h12.5C15.216 0 16 .784 16 1.75v9.5A1.75 1.75 0 0 1 14.25 13H8.06l-2.573 2.573A1.458 1.458 0 0 1 3 14.543V13H1.75A1.75 1.75 0 0 1 0 11.25Zm1.75-.25a.25.25 0 0 0-.25.25v9.5c0 .138.112.25.25.25h2a.75.75 0 0 1 .75.75v2.19l2.72-2.72a.749.749 0 0 1 .53-.22h6.5a.25.25 0 0 0 .25-.25v-9.5a.25.25 0 0 0-.25-.25Zm7 2.25v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 9a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>';
const ICON_ALERT =
  '<svg class="octicon octicon-alert" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M6.457 1.047c.659-1.234 2.427-1.234 3.086 0l6.082 11.378A1.75 1.75 0 0 1 14.082 15H1.918a1.75 1.75 0 0 1-1.543-2.575Zm1.763.707a.25.25 0 0 0-.44 0L1.698 13.132a.25.25 0 0 0 .22.368h12.164a.25.25 0 0 0 .22-.368Zm.53 3.996v2.5a.75.75 0 0 1-1.5 0v-2.5a.75.75 0 0 1 1.5 0ZM9 11a1 1 0 1 1-2 0 1 1 0 0 1 2 0Z"></path></svg>';
const ICON_STOP =
  '<svg class="octicon octicon-stop" viewBox="0 0 16 16" version="1.1" width="16" height="16" aria-hidden="true"><path d="M4.47.22A.749.749 0 0 1 5 0h6c.199 0 .389.079.53.22l4.25 4.25c.141.14.22.331.22.53v6a.749.749 0 0 1-.22.53l-4.25 4.25A.749.749 0 0 1 11 16H5a.749.749 0 0 1-.53-.22L.22 11.53A.749.749 0 0 1 0 11V5c0-.199.079-.389.22-.53Zm.84 1.28L1.5 5.31v5.38l3.81 3.81h5.38l3.81-3.81V5.31L10.69 1.5ZM8 4a.75.75 0 0 1 .75.75v3.5a.75.75 0 0 1-1.5 0v-3.5A.75.75 0 0 1 8 4Zm0 8a1 1 0 1 1 0-2 1 1 0 0 1 0 2Z"></path></svg>';

const ADMONITION_TYPES = {
  note: { title: "Note", icon: ICON_INFO, role: "note" },
  tip: { title: "Tip", icon: ICON_LIGHT_BULB, role: "note" },
  important: { title: "Important", icon: ICON_REPORT, role: "note" },
  warning: { title: "Warning", icon: ICON_ALERT, role: "alert" },
  caution: { title: "Caution", icon: ICON_STOP, role: "alert" },
};

// Matches an admonition fence with optional leading indent. Indented
// admonitions inside a list item or blockquote share the parent's
// indentation; the gem's regex captures that into \1 and uses it as a
// per-line anchor on the body lines.
// The rest of the `[!TYPE]` line is the callout's label (lib/callout-labels.mjs).
const ADMONITION_RE =
  /(^|\n)([ \t]*)>[ \t]*\[!(NOTE|TIP|IMPORTANT|WARNING|CAUTION)\]([^\n]*)\n((?:\2[ \t]*>[ \t]*[^\n]*(?:\n|$))(?:(?![ \t]*>[ \t]*\[!)\2[ \t]*>[ \t]*[^\n]*(?:\n|$))*)?/g;
// An admonition written inside a code region is a sample of the syntax, and is
// left as it is. This rewrite runs outside the mask, so it asks lib/markdown
// where the regions are, with the site's parser for the reason
// applyPreRenderRewrites gives. It is the `[!TYPE]` line that decides: a fence
// INSIDE an admonition is a region too, and the rewrite must still strip its
// `> ` markers with the rest of the body.
//
// It does not find fences with a line scan of its own: such a scan can pair a
// fence with a marker in the middle of a line, or see backtick fences only, so
// a tilde fence holding a ``` line swallows the prose after it, and either
// leaves admonitions as the literal text "[!NOTE]". WIP.Build.md tells both.
// A private scan can also disagree with the parser without anyone noticing;
// check_code_regions.mjs probes each shape through the whole chain.
//
// A label that does not parse, or names a package version other than the one
// the page's section documents (`packageVersion`), throws: the build stops and
// names the callout. So does a callout with no label in such a section.
// `packageVersion` is "" for a page in no package section;
// left out, as the code-region gate's sweep leaves it, versions go unchecked.
export function rewriteAdmonitions(src, md, { packageVersion } = {}) {
  if (!md) throw new TypeError("rewriteAdmonitions: pass the site's markdown-it instance");
  // CommonMark's normalisation pass converts CRLF/CR to LF before block
  // parsing. We do it up-front so our regexes operate on LF-only input.
  src = src.replace(/\r\n?/g, "\n");

  const inCode = [];
  for (const r of blockRegions(src, { md })) for (let i = r.start; i < r.end; i++) inCode[i] = true;
  // The matches arrive in order, so the line count only moves forward.
  let line = 0;
  let counted = 0;

  return src.replace(ADMONITION_RE, (match, leading, indent, typeRaw, labelRaw, bodyRaw, offset) => {
    const at = offset + leading.length;
    for (; counted < at; counted++) if (src.charCodeAt(counted) === 10) line++;
    if (inCode[line]) return match;

    const type = typeRaw.toLowerCase();
    const meta = ADMONITION_TYPES[type];
    const label = parseCalloutLabel(labelRaw);
    const problem =
      label.error ?? (packageVersion === undefined ? undefined : checkCalloutLabel(label.items, packageVersion));
    if (problem) {
      const opening = (bodyRaw ?? "")
        .split("\n")[0]
        .replace(/^[ \t]*>[ \t]?/, "")
        .slice(0, 60);
      throw new Error(`callout "[!${typeRaw}]${labelRaw}" (${opening}...): ${problem}`);
    }
    // One tag per item, a space between them so that the title reads as words
    // to a screen reader; the title is a flex box, which does not draw it.
    // `timeless` is for the tooling only and draws nothing.
    const tags = label.items
      .filter((i) => i.kind !== "timeless")
      .map((i) => ` <span class="markdown-alert-label">${escapeMarkup(i.text)}</span>`)
      .join("");
    // The body lines all share the same leading indent; strip it plus the
    // `>` marker and AT MOST ONE following space, which is what blockquote
    // unwrapping means.
    //
    // The gem's `gsub(/^#{indent}\s*>\s*/, "")` has a trailing `\s*` that is
    // greedy over `\s`, which includes newlines -- so mirrored literally it
    // also eats the body's own indentation and swallows blank lines.
    // A fence inside an admonition is stripped with the rest of the body, so
    // this runs over real code samples: a literal mirror leaves If/ElseIf/Else
    // bodies flush left and loses blank lines between examples.
    const stripRe = indent ? new RegExp(`^${escapeRegExp(indent)}[ \\t]*>[ \\t]?`, "gm") : /^[ \t]*>[ \t]?/gm;
    const body = (bodyRaw ?? "").replace(stripRe, "").trimEnd();

    // The gem emits the replacement <div> at column 0 regardless of how
    // far the source admonition was indented -- so an admonition inside
    // a list item BREAKS the list (the HTML block at column 0 closes
    // any open list/blockquote context). Mirror that. Body wrapped in
    // blank lines so the inner kramdown-style block descent (via
    // blockHtmlRecursionPlugin) parses it as an independent block.
    // The trailing blank line ensures any following text is parsed as
    // a separate markdown block rather than absorbed into the html_block.
    return `${leading}<div class="markdown-alert markdown-alert-${type}" role="${meta.role}" markdown="1">\n<p class="markdown-alert-title">${meta.icon} ${meta.title}${tags}</p>\n\n${body}\n</div>\n\n`;
  });
}

// ---------- markdown="1" attribute strip -----------------------------------
//
// With `html: true`, markdown-it already parses blank-line-separated
// content inside HTML wrappers as markdown -- which is what kramdown
// does when the wrapper has `markdown="1"`. Our admonition rewrite
// produces wrappers that are always blank-line-separated from their
// body, so no explicit recursive re-parse is required. All we need to
// do is strip the `markdown="1"` attribute kramdown would strip itself
// once it had recursed.

function blockHtmlRecursionPlugin(md) {
  md.core.ruler.push("strip-markdown-attr", (state) => {
    for (const t of state.tokens) {
      if (t.type !== "html_block") continue;
      // kramdown treats `markdown=X` (X in {1, span, block}) as a
      // parser directive on the enclosing element and strips the
      // attribute from output. Match the same three forms with
      // optional quoting.
      //
      // For `markdown=span` specifically, kramdown also descends INTO
      // the element's body and applies inline-level conversions
      // (smart-quotes, dashes). Mirror by running a smart-quote pass
      // over the body BEFORE we strip the attribute.
      t.content = t.content.replace(
        /(<([a-zA-Z][\w-]*)\b[^>]*?)\s+markdown=(?:"span"|'span'|span)([^>]*>)([\s\S]*?)(<\/\2\s*>)/g,
        (_, openHead, _tag, openTail, body, closing) => {
          return `${openHead}${openTail}${applyKramdownSmartQuotes(body)}${closing}`;
        },
      );
      t.content = t.content.replace(
        /\s+markdown=(?:"(?:1|span|block)"|'(?:1|span|block)'|(?:1|span|block))(?=[\s/>])/g,
        "",
      );
    }
  });

  // Detect fences that live between admonition-opening and -closing
  // html_blocks. markdown-it splits those out as level-0 siblings
  // (blank lines around the fence break the html_block), but kramdown
  // treats them as nested-inside-the-div blocks and adds the same
  // inter-`</div>` newline it adds for list-item-nested fences.
  // Tag those fences with a meta flag so the fence renderer can mirror.
  md.core.ruler.push("tag-admonition-fences", (state) => {
    const toks = state.tokens;
    let inAdmonition = false;
    for (const t of toks) {
      if (t.type === "html_block") {
        if (/<div\s+class="markdown-alert/.test(t.content)) inAdmonition = true;
        else if (/^<\/div>/.test(t.content.trim())) inAdmonition = false;
      } else if (t.type === "fence" && inAdmonition) {
        t.meta = { ...(t.meta || {}), nestedInBlock: true };
      }
    }
  });

  // kramdown wraps a standalone inline HTML element (e.g. <br />,
  // <img ...>) in a <p> -- which markdown-it doesn't, because it
  // detects them as block HTML and passes them through verbatim.
  // Detect that shape (an html_block whose entire content is an inline
  // tag), and wrap its content in <p>...</p>.
  md.core.ruler.push("wrap-standalone-inline-html", (state) => {
    for (const t of state.tokens) {
      if (t.type !== "html_block") continue;
      const trimmed = t.content.trim();
      if (STANDALONE_INLINE_HTML_RE.test(trimmed)) {
        t.content = `<p>${trimmed}</p>\n`;
      }
    }
  });

  // kramdown parses raw HTML and re-emits it through a normaliser that
  // (a) expands bareword attributes to `attr=""` form (parser at
  // kramdown/parser/html.rb#parse_html_attributes maps missing values
  // to ""; converter at kramdown/utils/html.rb#html_attributes emits
  // ` attr="value"`), and (b) for HTML elements whose body is empty or
  // whitespace-only, emits `<tag></tag>` with no inner whitespace
  // (converter at kramdown/converter/html.rb#convert_html_element).
  // markdown-it instead passes block HTML through verbatim, so the
  // bareword attrs and inter-tag whitespace survive. Apply the same
  // normalisation here so HTML5-bare `<iframe ... allowfullscreen>\n
  // </iframe>` renders the same as kramdown's parsed form.
  md.core.ruler.push("normalise-block-html", (state) => {
    for (const t of state.tokens) {
      if (t.type !== "html_block") continue;
      t.content = normaliseBlockHtml(t.content);
    }
  });
}

// Subset of HTML5 boolean attributes that appear in the corpus. Keep this
// list small -- bareword expansion is a syntactic kramdown quirk, not a
// validation step, and over-broad matching would rewrite arbitrary
// author-written HTML.
// biome-ignore format: a table, one entry per line
const HTML_BOOL_ATTRS = new Set([
  "allowfullscreen", "async", "autofocus", "autoplay", "checked",
  "controls", "default", "defer", "disabled", "formnovalidate", "hidden",
  "inert", "ismap", "itemscope", "loop", "multiple", "muted", "nomodule",
  "novalidate", "open", "playsinline", "readonly", "required", "reversed",
  "selected",
]);

// Match a start tag: `<tag attrs...>`. Captures tag name and the full
// attribute span (between tag name and the closing `>`).
const START_TAG_RE = /<([a-zA-Z][a-zA-Z0-9]*)((?:\s+[^>]*)?)>/g;

// Match a single attribute inside the attribute span. Order: name,
// optional `=value` (with quoted or unquoted value).
const ATTR_RE = /([a-zA-Z_][a-zA-Z0-9_:.-]*)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;

function expandBoolAttrs(attrSpan) {
  return attrSpan.replace(ATTR_RE, (whole, name, dq, sq, uq) => {
    if (dq !== undefined || sq !== undefined || uq !== undefined) return whole;
    if (HTML_BOOL_ATTRS.has(name.toLowerCase())) return `${name}=""`;
    return whole;
  });
}

// HTML elements whose whitespace-only body kramdown collapses to
// `<tag></tag>` with no inner whitespace or newline. Drawn from
// kramdown's HTML_CONTENT_MODEL_BLOCK list (most relevant: iframe,
// details, summary, video, audio).
const WS_COLLAPSE_TAGS_RE =
  /<(iframe|details|summary|video|audio|object|figure|figcaption|aside|section|nav|header|footer|article|main|form|fieldset)(\s[^>]*)?>\s+<\/\1>/gi;

function normaliseBlockHtml(content) {
  let out = content.replace(START_TAG_RE, (whole, tag, attrSpan) => {
    if (!attrSpan) return whole;
    const expanded = expandBoolAttrs(attrSpan);
    return `<${tag}${expanded}>`;
  });
  out = out.replace(WS_COLLAPSE_TAGS_RE, (_, tag, attrs) => `<${tag}${attrs || ""}></${tag}>`);
  return out;
}

// Match an html_block whose content is one or more self-closing inline
// tags (separated by whitespace): <br>, <br/>, <br />, <hr ...>,
// <img ...>. kramdown wraps any such sequence in a single <p>.
//
// No `\/?` before the `>`, deliberately. `/` is already inside `[^>]`,
// so `[^>]*\/?` matches exactly the same language as `[^>]*` -- but it
// matches it two ways per tag, once with the slash inside the class and
// once with it in the optional. Under `(?:...)+` that is 2^n partitions
// of an n-tag block, all of which get tried when the anchored `$`
// fails. Measured at ~4x per two added tags: 22 tags took 106 ms, and
// the curve does not flatten. An html_block of `<br />` lines ending in
// anything that is not another such tag is enough to reach it.
const STANDALONE_INLINE_HTML_RE = /^(?:<(br|hr|img)\b[^>]*>\s*)+$/i;

// ---------- SVG inline plugin -----------------------------------------------

// Video links: `[Title](https://www.youtube.com/watch?v=<id>){: .video }`
// becomes a locally stored poster frame that links out to the video page.
//
// The embed this replaces (a YouTube <iframe>) loaded Google's player on
// page view, contacting Google and setting third-party cookies before the
// reader had done anything. A thumbnail plus a plain link contacts nobody
// until the reader chooses to click.
//
// The thumbnail path is emitted root-absolute rather than page-relative,
// because the PDF book flattens every page into one document -- a
// page-relative src resolves against the book root there and the render
// aborts with `pdf: missing image`.
//
// vendor-assets.mjs guarantees the file exists before render (or fails
// the build), so a miss here means the link is marked `.video` but does
// not point at YouTube. That is an authoring mistake, not a fetch
// failure: warn and leave the plain link alone.
const VIDEO_URL_RE = /^https?:\/\/(?:www\.)?(?:youtube\.com\/watch\?v=|youtu\.be\/)([A-Za-z0-9_-]{6,})/;

function videoLinkPlugin(md, ctx) {
  // One core rule rather than renderer overrides: the link text has to be
  // read BEFORE it is removed, and doing both in a single token-stream
  // pass keeps that ordering obvious. The anchor ends up containing the
  // poster frame and nothing else, so the image's alt carries the
  // accessible name.
  md.core.ruler.push("video_link", (state) => {
    for (const blockToken of state.tokens) {
      if (blockToken.type !== "inline" || !blockToken.children) continue;
      const kids = blockToken.children;

      for (let i = 0; i < kids.length; i++) {
        const open = kids[i];
        if (open.type !== "link_open" || !hasClass(open, "video")) continue;

        const closeIdx = findLinkClose(kids, i);
        if (closeIdx < 0) continue;

        const hrefIdx = open.attrIndex("href");
        const href = hrefIdx >= 0 ? open.attrs[hrefIdx][1] : "";
        const m = VIDEO_URL_RE.exec(href);
        if (!m) {
          console.warn(`render: link marked {: .video } does not point at a YouTube video: ${href}`);
          continue;
        }

        const thumb = ctx.vendoredVideos?.get(m[1]);
        if (!thumb) {
          // vendor-assets guarantees the file exists before render, so
          // this means the marker was added without a build in between.
          console.warn(`render: no vendored thumbnail for video ${m[1]}`);
          continue;
        }

        const alt = kids
          .slice(i + 1, closeIdx)
          .filter((t) => t.type === "text" || t.type === "code_inline")
          .map((t) => t.content)
          .join("")
          .trim();

        // The anchor leaves the site, and its whole content is the
        // poster frame, so the alt is the only thing telling a screen
        // reader where the link goes.
        const label = alt ? `${alt} (watch on YouTube)` : "Watch on YouTube";
        const img = new state.Token("html_inline", "", 0);
        // No loading="lazy": the forked paged.js raises on an image that
        // has not finished loading when the page-breaking pass runs, so a
        // deferred image would abort the PDF book if the Videos pages ever
        // join it. Matches every other image on the site.
        img.content = `<img src="${escapeMarkupAndQuotes(thumb)}" alt="${escapeMarkupAndQuotes(label)}" />`;

        // `.video` is the marker that selected this link, not a styling
        // hook -- nothing in the stylesheets matches it -- so it is
        // consumed rather than emitted. Any OTHER class the author wrote
        // in the same IAL survives, which is the whole point of merging
        // below instead of replacing.
        removeClass(open, "video");
        setClass(open, "video-link");
        kids.splice(i + 1, closeIdx - i - 1, img);
        i += 2; // past the injected image and its link_close
      }
    }
  });
}

function findLinkClose(kids, openIdx) {
  let depth = 0;
  for (let i = openIdx + 1; i < kids.length; i++) {
    if (kids[i].type === "link_open") depth++;
    else if (kids[i].type === "link_close") {
      if (depth === 0) return i;
      depth--;
    }
  }
  return -1;
}

function hasClass(token, name) {
  const i = token.attrIndex("class");
  if (i < 0) return false;
  return String(token.attrs[i][1]).split(/\s+/).includes(name);
}

function setClass(token, name) {
  // Merge into whatever classes the IAL already put on the token --
  // replacing the attribute outright dropped every sibling class from the
  // same `{: .video .float-right }` shorthand, silently.
  const i = token.attrIndex("class");
  if (i < 0) {
    token.attrPush(["class", name]);
    return;
  }
  if (!hasClass(token, name)) token.attrs[i][1] = `${token.attrs[i][1]} ${name}`;
}

// Drop one class, leaving the rest. Used for a marker class that selected
// the token and has no business in the output.
function removeClass(token, name) {
  const i = token.attrIndex("class");
  if (i < 0) return;
  const kept = String(token.attrs[i][1])
    .split(/\s+/)
    .filter((c) => c && c !== name);
  if (kept.length) token.attrs[i][1] = kept.join(" ");
  else token.attrs.splice(i, 1);
}

// Rewrites a GitHub user-attachment <img src> to the copy vendor-assets
// downloaded into the source tree. No marker is needed: an image pointing
// at a user-attachment URL should always be served locally. Leaving it
// remote would cost a redirect-plus-S3 round trip on every page view,
// break the offline mirror, and abort the PDF book render -- the forked
// paged.js raises on an image that has not finished loading.
const GH_ATTACH_SRC_RE = /^https:\/\/github\.com\/user-attachments\/assets\/([0-9a-fA-F-]{36})/;

// Shared between the markdown `![]()` path below and the raw-HTML path:
// given a src/href string, returns the local vendored path if it's a GH
// attachment URL vendor-assets already downloaded, or null if it's some
// other URL (silently) or a GH attachment URL with no vendored copy yet
// (warn -- vendor-assets should have run before render).
function resolveVendoredAttachment(url, ctx) {
  const m = GH_ATTACH_SRC_RE.exec(url);
  if (!m) return null;
  const local = ctx.vendoredImages?.get(m[1].toLowerCase());
  if (!local) console.warn(`render: no vendored copy for attachment ${m[1]}`);
  return local || null;
}

// vendor-assets.mjs's own scan for what to download matches "markdown
// image syntax or a raw <img src>" (its GH_ATTACH_RE comment says so
// explicitly), so a hand-written <img> tag gets the file downloaded to
// disk exactly like a markdown image does. Only the renderer rule below
// rewrote the reference, though -- a raw <img> pointing at a
// user-attachment URL got vendored to disk and then still failed
// --check-remote-assets, with nothing in the failure saying the tag
// syntax was the reason. A raw <img> reaches the token stream as either
// a standalone html_block (see wrap-standalone-inline-html above, which
// may have already wrapped it in <p>...</p> by the time this runs -- the
// regex below doesn't care) or an html_inline child mixed into a
// sentence; rewrite both the same way the markdown path does.
const RAW_IMG_SRC_RE = /(<img\b[^>]*\bsrc\s*=\s*)(["'])(.*?)\2/gi;

function rewriteRawImgSrc(content, ctx) {
  return content.replace(RAW_IMG_SRC_RE, (whole, head, quote, url) => {
    const local = resolveVendoredAttachment(url, ctx);
    return local ? `${head}${quote}${local}${quote}` : whole;
  });
}

function remoteImagePlugin(md, ctx) {
  const orig = md.renderer.rules.image;

  md.renderer.rules.image = (tokens, idx, options, env, self) => {
    const token = tokens[idx];
    const srcIdx = token.attrIndex("src");
    if (srcIdx >= 0) {
      const local = resolveVendoredAttachment(token.attrs[srcIdx][1], ctx);
      if (local) token.attrs[srcIdx][1] = local;
    }
    if (orig) return orig(tokens, idx, options, env, self);
    return self.renderToken(tokens, idx, options);
  };

  md.core.ruler.push("remote-image-raw-html", (state) => {
    for (const t of state.tokens) {
      if (t.type === "html_block") {
        t.content = rewriteRawImgSrc(t.content, ctx);
      } else if (t.type === "inline" && t.children) {
        for (const c of t.children) {
          if (c.type === "html_inline") c.content = rewriteRawImgSrc(c.content, ctx);
        }
      }
    }
  });
}

// Figures. An image that is its paragraph's only content -- a diagram, a picture in two
// themes (the pair themePairPlugin wrote), or any other image -- is written as a figure: a
// wrapper holding a controls bar and the image, which docs/assets/js/figure.js runs. The
// bar has a group per format, each with Download and Copy, and Zoom; the stylesheet puts it
// above the figure, or beside it where the window leaves a margin for it.
//
// A diagram (a site .svg that is no picture's SVG) is inlined: its SVG text goes into the
// wrapper, so it draws in the page's own fonts and its labels take the theme's colour. Any
// other image stays an <img>, and figure.js reads what to download or copy from the one
// the reader sees.
//
// The wrapper is a <div>, and a lone `![alt](x.svg)` is a paragraph, so without hiding the
// paragraph tokens the output is `<p><div …></div></p>` -- invalid, because <p> takes
// phrasing content only. A browser repairs it by closing the paragraph early and leaving a
// stray empty <p> behind, which is why it went unnoticed. Only a paragraph whose ENTIRE
// content is the image (or the pair) qualifies: `See this: ![d](x.svg)` keeps its <p>, and
// its image stays a plain <img>.
//
// Which it is, is decided on the token stream; what the bar holds is decided when the
// figure_open token renders, from the image's src as remoteImagePlugin will write it (that
// plugin rewrites a vendored attachment's URL only when the image itself renders, after
// this).
const RASTER_FORMATS = { png: "PNG", jpg: "JPEG", jpeg: "JPEG", gif: "GIF", webp: "WebP" };

function figurePlugin(md, ctx) {
  const orig = md.renderer.rules.image;
  const prefix = `${ctx.baseurl || ""}/`;

  // The site-relative path of the SVG to inline for this image, or null: only a site .svg
  // that is no picture's SVG (a picture's SVG has its PNG beside it) and whose text the
  // build has.
  function inlinableSvgRel(token) {
    const src = token.attrGet("src");
    if (!src || !src.endsWith(".svg") || !src.startsWith(prefix)) return null;
    const srcRel = src.slice(prefix.length);
    if (ctx.staticFiles && isPictureSvg(srcRel, ctx.staticFiles)) return null;
    return ctx.svgContents?.get(srcRel) ? srcRel : null;
  }

  // One image, or the two of a picture pair, and nothing else.
  const isFigure = (kids) =>
    kids.length === 1
      ? kids[0].type === "image"
      : kids.length === 2 && kids.every((k) => k.type === "image" && k.meta?.themePaired);

  md.core.ruler.push("figures", (state) => {
    const toks = state.tokens;
    for (let i = 0; i + 2 < toks.length; i++) {
      if (toks[i].type !== "paragraph_open") continue;
      if (toks[i + 1].type !== "inline" || toks[i + 2].type !== "paragraph_close") continue;
      const kids = toks[i + 1].children;
      if (!kids || !isFigure(kids)) continue;
      toks[i].hidden = true;
      toks[i + 2].hidden = true;
      const open = new state.Token("figure_open", "div", 1);
      open.meta = { images: kids.slice() };
      if (kids.length === 1 && inlinableSvgRel(kids[0])) kids[0].meta = { ...(kids[0].meta || {}), figureInline: true };
      kids.unshift(open);
      kids.push(new state.Token("figure_close", "div", -1));
    }
  });

  md.renderer.rules.figure_open = (tokens, idx, options, env, self) => {
    const images = tokens[idx].meta.images;
    if (env?.page) env.page.hasFigure = true;
    const first = images[0];
    if (first.meta?.figureInline) {
      const srcRel = inlinableSvgRel(first);
      const alt = self.renderInlineAsText(first.children, options, env);
      const stem = srcRel
        .split("/")
        .pop()
        .replace(/\.svg$/, "");
      return diagramFigureOpen(ctx.svgContents.get(srcRel), alt, stem, srcRel);
    }
    // The dark picture of a pair is the last; any image of the pair names the same formats,
    // and the page's width and height are the dark one's.
    const dark = images[images.length - 1];
    const src = dark.attrGet("src") ?? "";
    return pictureFigureOpen(resolveVendoredAttachment(src, ctx) ?? src, dark.attrGet("width"), dark.attrGet("height"));
  };
  md.renderer.rules.figure_close = () => `</div></div>`;

  md.renderer.rules.image = (tokens, idx, options, env, self) => {
    // A diagram's SVG was written by figure_open.
    if (tokens[idx].meta?.figureInline) return "";
    if (orig) return orig(tokens, idx, options, env, self);
    const token = tokens[idx];
    token.attrs[token.attrIndex("alt")][1] = self.renderInlineAsText(token.children, options, env);
    return self.renderToken(tokens, idx, options);
  };
}

// A glyph of the figure sprite (template.mjs, FIGURE_SPRITE), by its name.
const figureGlyph = (name, cls = "") =>
  `<svg${cls ? ` class="${cls}"` : ""} aria-hidden="true" focusable="false"><use href="#fig-${name}"></use></svg>`;

// One button of a figure's controls bar: an icon, named by its aria-label and, for a
// pointer, by its tooltip.
const figureButton = (action, label, glyph, attrs = "") =>
  `<button type="button" class="btn-reset" data-action="${action}"${attrs} aria-label="${label}" title="${label}">` +
  figureGlyph(glyph) +
  `</button>`;

// A group of the bar, led by the sign of its format (`vector`, `raster`), or by nothing for
// Zoom. The sign is a label, hidden from assistive technology: each button's own label
// already names its format. `data-format` is what figure.js hides a group by.
const figureGroup = (format, buttons) =>
  `<span class="fig-group"${format ? ` data-format="${format}"` : ""}>` +
  (format ? figureGlyph(format, "fig-format") : "") +
  buttons.join("") +
  `</span>`;

const zoomGroup = () => figureGroup(null, [figureButton("zoom", "Zoom", "zoom")]);

// Whether a figure is tall enough to have its bar stood on end beside it, in the margin
// (custom.scss, `.fig-wrap[data-tall]`): at least as tall as that bar, as the page shows it
// in the 736px content column a window that wide has. A shorter figure would leave the
// paragraph after it pushed down by the bar's height, so its bar lies flat, beside it or
// above it. Decided here, from sizes the page already states, so that nothing moves once
// the page has loaded; a figure whose size is not known is taken as short.
//
// The bar's height follows from custom.scss: a group is 2px of padding at each end, its
// format sign (18px and 8px of margin), and 28px buttons 1px apart; groups are 6px apart.
const FIGURE_COLUMN = 736;
const barHeight = (groups) =>
  groups.reduce((sum, g) => sum + 4 + (g.sign ? 26 : 0) + 28 * g.buttons + (g.buttons - 1 + (g.sign ? 1 : 0)), 0) +
  6 * (groups.length - 1);

function tallAttr(width, height, groups) {
  const w = Number(width);
  const h = Number(height);
  if (!(w > 0 && h > 0)) return "";
  return h * Math.min(1, FIGURE_COLUMN / w) >= barHeight(groups) ? " data-tall" : "";
}

// Whether a diagram's figure is tall (tallAttr), by its SVG. A diagram's bar has both
// format groups and Zoom. Exported for the Gantt chart, whose SVG replaces a placeholder
// only after the page is written (tbdocs.mjs, injectGanttChart).
export function diagramIsTall(svgContent) {
  const groups = [
    { sign: true, buttons: 2 },
    { sign: true, buttons: 2 },
    { sign: false, buttons: 1 },
  ];
  return tallAttr(...svgPixelSize(svgContent), groups) !== "";
}

// A diagram's size, from its root <svg>'s width and height: Graphviz writes them in pt.
function svgPixelSize(svgContent) {
  const root = /<svg\b[^>]*>/.exec(svgContent)?.[0] ?? "";
  const px = (name) => {
    const m = new RegExp(String.raw`\s${name}="([\d.]+)(pt|px)?"`).exec(root);
    return m ? Number(m[1]) * (m[2] === "pt" ? 4 / 3 : 1) : 0;
  };
  return [px("width"), px("height")];
}

// The opening of a diagram's figure, its SVG included.
function diagramFigureOpen(svgContent, alt, stem, srcRel) {
  const esc = escapeMarkupAndQuotes;

  // `role="img"` with an empty `aria-label` is worse than no role at all: it
  // tells a screen reader there is an image here and then refuses to say what
  // it is, which axe reports as role-img-alt (serious).  An `<img alt="">`
  // would pass as decorative; an explicit role cannot.  A diagram is never
  // decorative anyway, so an empty alt here is an authoring error -- say so,
  // and drop the role rather than ship the broken form.
  const labelled = alt.trim() !== "";
  if (!labelled) {
    console.warn(
      `render: ${srcRel} is embedded with no alt text -- the diagram will have ` +
        `no accessible name. Add one: ![describe the diagram](...)`,
    );
  }
  // A diagram whose boxes link somewhere (Graphviz's URL attribute) is a group of links,
  // not an image: role="img" would make its links presentational, which axe reports as
  // nested-interactive. inline-diagram.mjs says what else changes.
  const { svg, linked } = inlineDiagram(svgContent);
  svgContent = svg;
  const imgRole = labelled ? ` role="${linked ? "group" : "img"}" aria-label="${esc(alt)}"` : "";
  const name = ` data-filename="${esc(stem)}"`;
  const tall = diagramIsTall(svgContent) ? " data-tall" : "";

  return (
    `<div class="fig-wrap" data-kind="diagram"${tall}>` +
    `<div class="fig-controls">` +
    figureGroup("vector", [
      figureButton("download-svg", "Download SVG", "download", name),
      figureButton("copy-svg", "Copy SVG", "copy"),
    ]) +
    figureGroup("raster", [
      figureButton("download-png", "Download PNG", "download", name),
      figureButton("copy-png", "Copy PNG", "copy", name),
    ]) +
    zoomGroup() +
    `</div>` +
    `<div class="fig-container" data-svg-src="${esc(srcRel)}"${imgRole}>` +
    svgContent
  );
}

// The opening of a picture's or an image's figure. A picture drawn as SVG offers both
// formats, its PNG being beside it; a raster image offers its own format, copied as PNG,
// the one image format a clipboard takes. An image of any other kind gets Zoom alone.
function pictureFigureOpen(src, width, height) {
  const ext = /\.([a-z0-9]+)(?:[?#]|$)/i.exec(src)?.[1]?.toLowerCase() ?? "";
  const raster = ext === "svg" ? "PNG" : RASTER_FORMATS[ext];
  const groups = [];
  const shape = [{ sign: false, buttons: 1 }];
  if (raster) shape.unshift({ sign: true, buttons: 2 });
  if (ext === "svg") shape.unshift({ sign: true, buttons: 2 });
  if (ext === "svg") {
    groups.push(
      figureGroup("vector", [
        figureButton("download-svg", "Download SVG", "download"),
        figureButton("copy-svg", "Copy SVG", "copy"),
      ]),
    );
  }
  if (raster) {
    groups.push(
      figureGroup("raster", [
        figureButton("download-png", `Download ${raster}`, "download"),
        figureButton("copy-png", raster === "PNG" ? "Copy PNG" : "Copy as PNG", "copy"),
      ]),
    );
  }
  groups.push(zoomGroup());
  return (
    `<div class="fig-wrap" data-kind="picture"${tallAttr(width, height, shape)}>` +
    `<div class="fig-controls">` +
    groups.join("") +
    `</div>` +
    `<div class="fig-container">`
  );
}