@aceshooting/lyra-ui 3.7.0 → 3.8.0

package/dist/components/markdown/markdown.class.js

@@ -8,7 +8,16 @@ import { html } from 'lit';
 import { property, state } from 'lit/decorators.js';
 import { unsafeHTML } from 'lit/directives/unsafe-html.js';
 import { LyraElement } from '../../internal/lyra-element.js';
+import { srOnly } from '../../internal/a11y.js';
+import { prefersReducedMotion } from '../../internal/motion.js';
+import { Slugger } from '../../internal/slugger.js';
+import { DocumentAnchorTarget } from '../../internal/anchor-target.js';
+import { scopeFromElement, resolveTextQuote, buildQuoteAnchor } from '../../internal/text-quote.js';
+import { acquireHighlightHandle, supportsCustomHighlights } from '../../internal/text-highlights.js';
+import { finiteInteger } from '../../internal/numbers.js';
 import { loadMarkdownDeps, getMarkdownDepsIfLoaded } from './markdown-loader.js';
+import { loadShikiHighlighter, loadShikiLanguage, loadShikiHighlighterCore, normalizeShikiLanguage, SHIKI_THEMES, } from '../code-block/code-loader.js';
+import { getKatex } from './katex-loader.js';
 import { styles } from './markdown.styles.js';
 const HTML_ESCAPES = {
     '&': '&',
@@ -39,6 +48,108 @@ function cleanHref(href) {
         return null;
     }
 }
+/** Every `LyraHighlightTone`, used to always call `HighlightHandle.setRanges()` once per tone on
+ *  every repaint (with an empty array for an unused tone) -- `setRanges()` replaces a tone's ranges
+ *  wholesale per call, so a tone this pass has nothing for still needs an explicit empty call to
+ *  clear whatever it painted last pass. */
+const HIGHLIGHT_TONES = ['accent', 'success', 'warning', 'danger', 'neutral'];
+/** Upper bound on `highlightCache` entries per instance. Each entry holds a fully-highlighted
+ *  HTML string (potentially large for a long code block), and the cache is content-addressed --
+ *  on a long-lived instance whose `content` keeps changing (a chat transcript, live docs), an
+ *  unbounded map would retain the highlighted HTML of every code block ever rendered. 100 far
+ *  exceeds the fenced-block count of any one document, so eviction only trims blocks that
+ *  scrolled out of the content long ago. */
+const HIGHLIGHT_CACHE_MAX = 100;
+// -- math (KaTeX) -----------------------------------------------------------------------------
+/** Resolved once per page and reused by every `<lyra-markdown>` instance, mirroring
+ *  `markdown-loader.ts`'s own "warm cache" shape: `undefined` means no load has been kicked off
+ *  yet, `null` a load finished but the peer isn't installed, and it's set to `null` synchronously
+ *  the instant a load starts as an in-flight marker so a second concurrent instance never kicks off
+ *  a duplicate `getKatex()` call. */
+let resolvedKatex;
+/** Whether `getKatex()` has already been kicked off, module-wide -- kept separate from
+ *  `resolvedKatex` so "a load is in flight" and "a load finished and the peer is confirmed
+ *  missing" stay distinguishable (both would otherwise collapse to the same falsy `null`). */
+let katexLoadStarted = false;
+/** Test-only override bypassing the real dynamic `import('katex')` and the module cache above
+ *  entirely -- `undefined` (the default) defers to `resolvedKatex`. */
+let katexOverride;
+/** @internal Test-only seam: forces `math` rendering to behave as if `katex` resolved to `katex`
+ *  (or, with `null`, as if the optional peer failed to load). Pass `undefined` to restore the real
+ *  `getKatex()`-driven behavior. */
+export function __setKatexForTesting(katex) {
+    katexOverride = katex;
+}
+function getKatexIfLoaded() {
+    return katexOverride !== undefined ? katexOverride : (resolvedKatex ?? null);
+}
+/** Whether the `katex` load has definitively finished with no peer available -- distinct from
+ *  `getKatexIfLoaded()` returning falsy, which also covers a load that's merely still in flight
+ *  (the state a math token's render-time literal fallback uses regardless of which case it is).
+ *  Used only to decide whether a literal fallback should also report `lyra-render-error`. */
+function isKatexConfirmedMissing() {
+    return (katexOverride !== undefined ? katexOverride : resolvedKatex) === null;
+}
+const MATH_BLOCK_RE = /^\$\$([^\n]+?)\$\$/;
+const MATH_INLINE_RE = /^\$((?:\\\$|[^$\s])(?:\\\$|[^$])*?)\$(?!\$)/;
+/** A marked inline-level extension recognizing `$...$` and `$$...$$` TeX. Tokenizing is
+ *  synchronous (matching marked's own parse pass); actual KaTeX rendering happens in `renderMath`
+ *  against whatever `getKatexIfLoaded()` already has resolved -- mirroring this component's
+ *  existing two-phase pattern for fenced-code highlighting (`code()` returns a plain placeholder
+ *  first; the real highlighted markup arrives one render later once shiki resolves). `renderer` is
+ *  bundled directly into this same extension object (not marked's separate top-level `.use({
+ *  renderer })` override hook -- that hook only recognizes the *built-in* renderer method names;
+ *  a custom token type introduced via `.use({ extensions })` supplies its own renderer the same way). */
+function mathExtension(renderMath) {
+    return {
+        name: 'math',
+        level: 'inline',
+        start(src) {
+            const index = src.indexOf('$');
+            return index === -1 ? undefined : index;
+        },
+        tokenizer(src) {
+            const block = MATH_BLOCK_RE.exec(src);
+            if (block)
+                return { type: 'math', raw: block[0], tex: block[1].trim(), display: true };
+            const inline = MATH_INLINE_RE.exec(src);
+            if (inline)
+                return { type: 'math', raw: inline[0], tex: inline[1].replace(/\\\$/g, '$').trim(), display: false };
+            return undefined;
+        },
+        renderer(token) {
+            return renderMath(token);
+        },
+    };
+}
+/**
+ * Rewrites shiki's generated `<pre>`/`<code>` hast nodes so the highlighted output keeps
+ * `<lyra-markdown>`'s own `part="code-block"` hook and a `language-${lang}` class on `<code>` --
+ * matching today's plain-render output shape exactly, so existing consumer CSS targeting either
+ * keeps working whether or not a given block ended up highlighted. A separate, purpose-built
+ * function from `code-block.class.ts`'s own (private, non-exported) `partTransformer` -- that one
+ * targets `<lyra-code-block>`'s own `part="pre"`/`part="code"`/line-numbers contract, which doesn't
+ * apply here.
+ */
+function markdownCodeTransformer(lang) {
+    return {
+        name: 'lyra-markdown-code-block',
+        pre(node) {
+            node.properties.part = ['code-block'];
+            delete node.properties.tabindex;
+        },
+        code(node) {
+            const classes = Array.isArray(node.properties.class)
+                ? node.properties.class
+                : node.properties.class
+                    ? [node.properties.class]
+                    : [];
+            node.properties.class = [...classes, `language-${lang}`];
+        },
+    };
+}
+class LyraMarkdownBase extends LyraElement {
+}
 /**
  * `<lyra-markdown>` — sanitized Markdown-to-HTML rendering (GFM tables,
  * fenced code blocks, links, blockquotes) built on the optional peer
@@ -74,13 +185,44 @@ function cleanHref(href) {
  * directly into the produced HTML — a single pass, not a second DOM walk
  * after insertion.
  *
+ * Fenced code blocks are syntax-highlighted via the same optional `shiki` peer `<lyra-code-block>`
+ * uses (`highlightCode`, default `true` — a pure upgrade gated by whether `shiki` is installed at
+ * all, not a separate opt-in). `languages`/`languagesOnly` mirror `<lyra-code-block>`'s own
+ * fine-grained bundle-size controls. The very first render of any content is always plain
+ * (identical to today's output); highlighting arrives as an asynchronous upgrade one render later,
+ * once shiki resolves. No highlighting is attempted while `streaming` is `true` — it applies once a
+ * stream settles, so there is no added per-chunk cost while content is still arriving.
+ *
+ * When `heading-anchors` is set, every rendered heading's slug (computed via the shared
+ * GitHub-slugger-style `Slugger`) is stamped as its `id`; `getHeadingTree()` computes that same
+ * outline on every parse regardless of `heading-anchors`, so a host can build a table of contents
+ * even while ids aren't in the DOM yet. `scrollToAnchor()` (from the adopted `DocumentAnchorTarget`
+ * mixin) resolves `fragment` anchors against that outline and `text-quote` anchors via
+ * `internal/text-quote.ts`'s shared scope/resolve helpers; `highlights` re-resolve by quote after
+ * every render (never by node identity), so a highlight painted before a `streaming` update
+ * finishes still finds its quote once the matching text arrives. Highlight painting uses
+ * `internal/text-highlights.ts`'s `acquireHighlightHandle()` -- the CSS Custom Highlight API where
+ * the browser supports it (no DOM mutation at all), a `<mark>`-wrap fallback otherwise.
+ *
+ * `math` renders `$...$`/`$$...$$` TeX as MathML via the optional `katex` peer's
+ * `renderToString(tex, { output: 'mathml' })` -- MathML Core renders natively and accessibly in
+ * evergreen browsers with no extra stylesheet or webfont needing to cross the shadow boundary. A
+ * missing `katex` peer renders the literal, unparsed TeX source (delimiters included) and fires one
+ * `lyra-render-error`.
+ *
  * @customElement lyra-markdown
  * @event lyra-link-click - Fired (and the click prevented) when a rendered
  *   link's `href` starts with `internal-link-prefix`. `detail: { href:
  *   string, internal: true }`. Ordinary external links navigate normally
  *   (in `link-target`) and never fire this event.
  * @event lyra-render-error - Fired whenever rendering falls back to plain
- *   text. `detail: { error: unknown }`.
+ *   text, or `math` is set but the `katex` peer isn't installed. `detail: { error: unknown }`.
+ * @event lyra-highlight-activate - A painted `text-quote` highlight was clicked. `detail: { id }`.
+ * @event lyra-text-select - Fired on selection end inside the rendered content. `detail: { text,
+ *   anchor, rects }`; `anchor` is a `text-quote` `LyraAnchor` scoped to the rendered content, or
+ *   `null` if the selection couldn't be anchored.
+ * @event lyra-anchor-result - Fired after an `anchor` property assignment or a `scrollToAnchor()`
+ *   call is applied. `detail: { found }`.
  * @csspart content - The wrapper around the rendered (or plain-text
  *   fallback) output.
  * @csspart heading - Every rendered `<h1>`–`<h6>` (shifted by
@@ -93,8 +235,9 @@ function cleanHref(href) {
  * @csspart table - Every rendered `<table>`.
  * @csspart blockquote - Every rendered `<blockquote>`.
  * @csspart img - Every rendered `<img>`.
+ * @csspart math - A rendered inline or block math span (`data-display="inline"|"block"`).
  */
-export class LyraMarkdown extends LyraElement {
+export class LyraMarkdown extends DocumentAnchorTarget(LyraMarkdownBase) {
     constructor() {
         super(...arguments);
         /** The Markdown source to render. */
@@ -152,15 +295,80 @@ export class LyraMarkdown extends LyraElement {
          *  is not final. Set it back to `false` with the final content update.
          *  Reflects so a consumer can also target `lyra-markdown[streaming]`. */
         this.streaming = false;
+        /** Syntax-highlights fenced code blocks via the same optional `shiki` peer `<lyra-code-block>`
+         *  uses. `true` (the default) upgrades every fenced block from plain `<pre><code>` once the peer
+         *  is available -- a pure upgrade, not a behavior change gated on opt-in, since it's itself gated
+         *  transparently by whether `shiki` is installed at all (an app that never installs it sees
+         *  byte-identical output to today). Set `false` to keep plain output even when `shiki` is
+         *  installed. No effect while `streaming` is `true` -- see that property's own doc. */
+        this.highlightCode = true;
+        /** Same purpose as `<lyra-code-block>`'s own `languagesOnly` -- skips the default full-bundle
+         *  loader entirely, so a fenced block whose language isn't in `languages` falls back to plain
+         *  unhighlighted text rather than reaching for the full bundle. No effect unless `languages` is
+         *  also set. */
+        this.languagesOnly = false;
+        /** Stamps a computed slug as `id` on every rendered heading. `getHeadingTree()` computes the
+         *  same slugs regardless of this property -- it only controls whether the `id` attribute is
+         *  emitted into the rendered DOM. `false` (the default) preserves today's exact output.
+         *
+         *  When `sanitize` is also on (the default), a slug whose *value* collides with a real
+         *  `document` property name (e.g. a heading literally titled "Title", "Location", or "Forms"
+         *  slugs to `title`/`location`/`forms`) has its `id` silently stripped by DOMPurify's DOM-
+         *  clobbering protection (`SANITIZE_DOM`) -- `getHeadingTree()` still reports that heading's slug
+         *  either way, but `scrollToAnchor({ kind: 'fragment', id })` still resolves it correctly even
+         *  without a DOM `id` present, via its own position-based fallback lookup. */
+        this.headingAnchors = false;
+        /** Renders `$...$`/`$$...$$` TeX via the optional `katex` peer, as MathML. `false` (the
+         *  default) renders `$...$` literally, unparsed -- today's exact output. */
+        this.math = false;
+        /** Anchor kinds this component resolves via `scrollToAnchor()`. Readonly. */
+        this.anchorKinds = ['fragment', 'text-quote'];
         // `null` covers both "the optional peers are still loading" and "a render
         // attempt just fell back after a failure" — the two states intentionally
         // look identical (plain text, see render()) since a consumer distinguishes
         // them via `lyra-render-error`, not a visual difference.
         this.renderedHtml = null;
+        /** Document-ordered heading outline computed on every parse (see `getHeadingTree()`), regardless
+         *  of `headingAnchors`. */
+        this.headingTree = [];
+        /** The most recently resolved `text-quote` highlight ranges, kept for `onContentClick()`'s
+         *  coordinate hit-test -- the CSS Custom Highlight API paints ranges without creating any DOM
+         *  element to attach a click listener to, so activation is resolved by comparing the click point
+         *  against each range's own `getClientRects()` instead, uniformly across both paint paths. */
+        this.resolvedHighlightRanges = [];
+        /** Guards `lyra-render-error` so a permanently-missing `katex` peer reports once per instance,
+         *  not on every subsequent re-render while `math` stays on. Reset whenever `math` toggles. */
+        this.mathFailureReported = false;
+        /** `(lang, code)` -> already-highlighted HTML, content-addressed (see `PendingHighlight`'s doc).
+         *  Persists across renders of this instance; populated asynchronously by `highlightPending()`.
+         *  Never consulted while `streaming` is `true` or `highlightCode` is `false` -- both gates live
+         *  in the `code()` renderer inside `parseMarkdown()`. Bounded to {@link HIGHLIGHT_CACHE_MAX}
+         *  entries, least-recently-used first out, via `getCachedHighlight()`/`setCachedHighlight()` --
+         *  always go through those instead of the map directly so hits refresh recency. */
+        this.highlightCache = new Map();
+        /** Bumped on every `highlightPending()` call, including ones that end up not actually loading
+         *  anything -- guards against a newer `content`/`streaming` change superseding an older in-flight
+         *  highlight, exactly mirroring `<lyra-code-block>`'s own `highlightToken` field for the identical
+         *  race (an async grammar load resolving after a newer call already produced correct output). */
+        this.highlightToken = 0;
+        /** Keys from `PendingHighlight` that failed to highlight -- peer missing, language unrecognized,
+         *  or tokenization threw. Once a key lands here, `code()` stops re-discovering it as pending on
+         *  every future render. Without this, a permanently-unhighlightable block (e.g. an unrecognized
+         *  language) would never get cached, so every `renderMarkdown()` pass -- including the one
+         *  `highlightPending()` itself triggers on completion -- would rediscover it as pending and retry
+         *  it again, forever. Mirrors `code-loader.ts`'s own `unsupportedLanguages` Set, which exists for
+         *  the identical reason one level down (a single unrecognized `language` value on
+         *  `<lyra-code-block>`). */
+        this.failedHighlightKeys = new Set();
         // A single delegated listener on the content wrapper (not one per <a>) —
         // the rendered markup is fully replaced on every content change, so a
         // per-anchor listener would need re-attaching on every render anyway.
         this.onContentClick = (e) => {
+            const highlightId = this.hitTestHighlightAt(e.clientX, e.clientY);
+            if (highlightId) {
+                this.emit('lyra-highlight-activate', { id: highlightId });
+                return;
+            }
             const prefix = this.internalLinkPrefix;
             if (!prefix)
                 return;
@@ -178,7 +386,28 @@ export class LyraMarkdown extends LyraElement {
             this.emit('lyra-link-click', { href, internal: true });
         };
     }
-    static { this.styles = [LyraElement.styles, styles]; }
+    static { this.styles = [LyraElement.styles, styles, srOnly]; }
+    /** LRU read: a hit is re-inserted so Map iteration order (insertion order) keeps the first key
+     *  the least recently used one -- the entry `setCachedHighlight()` evicts when full. */
+    getCachedHighlight(key) {
+        const cached = this.highlightCache.get(key);
+        if (cached !== undefined) {
+            this.highlightCache.delete(key);
+            this.highlightCache.set(key, cached);
+        }
+        return cached;
+    }
+    setCachedHighlight(key, html) {
+        if (this.highlightCache.has(key)) {
+            this.highlightCache.delete(key);
+        }
+        else if (this.highlightCache.size >= HIGHLIGHT_CACHE_MAX) {
+            const oldest = this.highlightCache.keys().next().value;
+            if (oldest !== undefined)
+                this.highlightCache.delete(oldest);
+        }
+        this.highlightCache.set(key, html);
+    }
     connectedCallback() {
         super.connectedCallback();
         if (this.eagerLoad) {
@@ -208,11 +437,31 @@ export class LyraMarkdown extends LyraElement {
             this.renderMarkdown();
         });
     }
+    disconnectedCallback() {
+        super.disconnectedCallback(); // reaches DocumentAnchorTarget's own cleanup (anchor retry, selection binding)
+        this.highlightHandle?.release();
+        this.highlightHandle = undefined;
+    }
+    /** Binds selection -> `lyra-text-select` once, on the stable `[part="content"]` wrapper --
+     *  re-renders only replace that wrapper's children via `unsafeHTML`, never the wrapper itself.
+     *  `bindTextSelection` is `protected` on the mixin's own narrowed return type (deliberately not
+     *  part of `LyraAnchorTarget`'s public surface -- see `anchor-target.ts`'s class doc), so it's
+     *  reached the same way that module's own tests do: through a cast, without declaring a no-op
+     *  passthrough override just to satisfy the type checker. */
+    firstUpdated() {
+        const contentRoot = this.renderRoot.querySelector('[part="content"]');
+        if (!contentRoot)
+            return;
+        this.bindTextSelection(contentRoot);
+    }
     // Runs before render (not updated()) so mutating the `renderedHtml` state
     // property below is absorbed into the *same* update cycle instead of
     // scheduling a second one -- Lit's documented pattern for deriving one
     // reactive property from a change to others.
     willUpdate(changed) {
+        super.willUpdate(changed); // reaches DocumentAnchorTarget's own willUpdate (declarative `anchor`)
+        if (changed.has('math'))
+            this.mathFailureReported = false;
         if (!this.deps) {
             // Still loading the optional peers — the connectedCallback promise
             // above calls renderMarkdown() itself once they resolve, using
@@ -224,17 +473,24 @@ export class LyraMarkdown extends LyraElement {
             changed.has('gfm') ||
             changed.has('linkTarget') ||
             changed.has('headingOffset') ||
-            changed.has('escapeHtml')) {
+            changed.has('escapeHtml') ||
+            changed.has('streaming') ||
+            changed.has('headingAnchors') ||
+            changed.has('math')) {
             this.renderMarkdown();
         }
     }
-    updated() {
+    updated(changed) {
+        super.updated(changed);
         if (this.deps && !this.streaming) {
             this.removeAttribute('aria-busy');
         }
         else {
             this.setAttribute('aria-busy', 'true');
         }
+        if (changed.has('renderedHtml') || changed.has('highlights') || changed.has('activeHighlightId')) {
+            this.repaintHighlights();
+        }
     }
     renderMarkdown() {
         const deps = this.deps;
@@ -245,18 +501,33 @@ export class LyraMarkdown extends LyraElement {
             this.applyFallback(new Error('<lyra-markdown> could not render: the "marked" peer dependency failed to load.'));
             return;
         }
+        const pendingKeys = [];
+        const headingTree = [];
         let rawHtml;
+        let hadMathFallback;
         try {
-            rawHtml = this.parseMarkdown(deps.marked);
+            const parsed = this.parseMarkdown(deps.marked, pendingKeys, headingTree);
+            rawHtml = parsed.html;
+            hadMathFallback = parsed.hadMathFallback;
         }
         catch (error) {
             this.applyFallback(error);
             return;
         }
+        this.headingTree = headingTree;
+        this.maybeLoadKatex();
+        // A math token rendering its literal fallback only means the `katex` peer is *confirmed*
+        // missing once loading has actually settled -- otherwise this is just the same one-microtask
+        // "still loading" window every other optional peer here has, and reporting it as an error
+        // would be a false positive.
+        const mathFailed = hadMathFallback && isKatexConfirmedMissing();
         if (!this.sanitize) {
             // Consumer explicitly opted out of sanitization — dompurify's
             // presence or absence is irrelevant to this path.
             this.renderedHtml = rawHtml;
+            if (mathFailed)
+                this.reportMathFailure();
+            this.maybeHighlightPending(pendingKeys);
             return;
         }
         if (!deps.DOMPurify) {
@@ -271,26 +542,173 @@ export class LyraMarkdown extends LyraElement {
         // `part`/`rel`/`class`, which already are) — without ADD_ATTR here,
         // every rendered link's target="..." would be silently stripped even
         // though the anchor itself survives sanitization.
-        this.renderedHtml = deps.DOMPurify.sanitize(rawHtml, { ADD_ATTR: ['target'] });
+        // 'style' joins 'target' in the added-attribute allowlist -- shiki's per-token output carries
+        // inline style="color:..." (theme colors), which isn't in DOMPurify's default attribute
+        // allowlist any more than 'target' was.
+        // `semantics`/`annotation` join the allowlist only when `math` is on -- the only KaTeX MathML
+        // output elements outside DOMPurify's default allowlist. `annotation-xml` is deliberately never
+        // added -- KaTeX's own MathML output never emits it, and DOMPurify's default allowlist already
+        // treats it as a namespace-switching element worth keeping stripped.
+        this.renderedHtml = deps.DOMPurify.sanitize(rawHtml, {
+            ADD_ATTR: ['target', 'style'],
+            ...(this.math ? { ADD_TAGS: ['semantics', 'annotation'] } : {}),
+        });
+        if (mathFailed)
+            this.reportMathFailure();
+        this.maybeHighlightPending(pendingKeys);
     }
     applyFallback(error) {
         this.renderedHtml = null;
         this.emit('lyra-render-error', { error });
     }
-    parseMarkdown(marked) {
+    /** Kicks off the shared `katex` load the first time `math` needs it and no attempt is already
+     *  in flight (module-scoped, so every `<lyra-markdown>` instance on the page shares one load --
+     *  mirrors `markdown-loader.ts`'s own warm-cache shape). Skipped entirely under
+     *  `__setKatexForTesting()` -- that seam controls math-rendering behavior directly and must never
+     *  race a real, unmocked `import('katex')` settling underneath it. */
+    maybeLoadKatex() {
+        if (!this.math || katexLoadStarted || katexOverride !== undefined)
+            return;
+        katexLoadStarted = true;
+        void getKatex().then((katex) => {
+            resolvedKatex = katex;
+            if (!this.isConnected)
+                return;
+            this.renderMarkdown();
+        });
+    }
+    /** Fires `lyra-render-error` once per instance for a permanently-missing `katex` peer. Called
+     *  only once `renderMarkdown()` has confirmed the peer is actually missing (`katexOverride` or
+     *  the resolved module is `null`) -- a math token rendering its literal fallback while the load
+     *  is merely still in flight (the same one-microtask transient window every other optional peer
+     *  in this component has) never reports an error on its own. */
+    reportMathFailure() {
+        if (this.mathFailureReported)
+            return;
+        this.mathFailureReported = true;
+        this.emit('lyra-render-error', {
+            error: new Error('<lyra-markdown> needs the optional peer dependency `katex` to render math (the `math` property is set) — install it with `pnpm add katex`.'),
+        });
+    }
+    /** Kicks off async highlighting for `pendingKeys` (see `highlightPending()`) unless there's
+     *  nothing to do, `highlightCode` is off, or `streaming` is on -- called from both of
+     *  `renderMarkdown()`'s exit points (the `sanitize=false` early return and the normal sanitized
+     *  path), since highlighting is independent of that decision. */
+    maybeHighlightPending(pendingKeys) {
+        if (pendingKeys.length === 0 || !this.highlightCode || this.streaming)
+            return;
+        void this.highlightPending(pendingKeys);
+    }
+    /** Loads whatever shiki grammars `pendingKeys` need, tokenizes each pending block concurrently,
+     *  populates `highlightCache` with the results, then triggers one more `renderMarkdown()` pass so
+     *  the newly-cached entries actually reach the screen. A pending key whose language fails to load
+     *  is recorded in `failedHighlightKeys` (per `loadShikiLanguage()`'s existing "unrecognized
+     *  grammar" contract -- resolves `false`, never throws) -- it stays uncached, so `code()` keeps
+     *  emitting its plain fallback for it on every future render, and `code()` also stops
+     *  re-discovering it as pending (see `failedHighlightKeys`'s own doc for why that matters: without
+     *  it, the `renderMarkdown()` call at the end of this method would rediscover the same
+     *  permanently-uncacheable key as pending on every pass, forever). Does not block or delay any
+     *  other pending key -- each is tried independently via `Promise.all`. */
+    async highlightPending(pendingKeys) {
+        const token = ++this.highlightToken;
+        const languages = this.languages;
+        const tokenizeOne = async (pending) => {
+            const normalizedLang = normalizeShikiLanguage(pending.lang);
+            let hl;
+            if (languages && (languages[normalizedLang] ?? languages[pending.lang])) {
+                hl = await loadShikiHighlighterCore(languages);
+            }
+            else if (this.languagesOnly) {
+                // languagesOnly skips the default full-bundle loader entirely (mirrors <lyra-code-block>) --
+                // permanent for this key: failedHighlightKeys is never cleared, and languages/languagesOnly
+                // aren't in willUpdate()'s trigger list, so changing either doesn't retry it on its own.
+                this.failedHighlightKeys.add(pending.key);
+                return;
+            }
+            else {
+                const base = await loadShikiHighlighter();
+                if (!base) {
+                    // The shiki peer itself isn't installed -- permanent for every key using this default
+                    // (non-languages) path until the page reloads.
+                    this.failedHighlightKeys.add(pending.key);
+                    return;
+                }
+                const ok = await loadShikiLanguage(base, pending.lang);
+                hl = ok ? base : null;
+            }
+            if (!hl) {
+                this.failedHighlightKeys.add(pending.key);
+                return;
+            }
+            try {
+                const html = hl.codeToHtml(pending.code, {
+                    lang: normalizedLang,
+                    themes: SHIKI_THEMES,
+                    transformers: [markdownCodeTransformer(pending.lang)],
+                });
+                this.setCachedHighlight(pending.key, `${html}\n`);
+            }
+            catch {
+                this.failedHighlightKeys.add(pending.key);
+                // Tokenization failed for a reason other than an unrecognized grammar (already handled by
+                // loadShikiLanguage()'s own return value above) -- leave this key uncached, same effect as
+                // an unrecognized language: permanent plain fallback for this specific block.
+            }
+        };
+        await Promise.all(pendingKeys.map(tokenizeOne));
+        if (token !== this.highlightToken || !this.isConnected)
+            return;
+        this.renderMarkdown();
+    }
+    parseMarkdown(marked, pendingKeys, headingTreeOut) {
         // Falsy (`null` or `''`) means the consumer explicitly opted out of
         // target="..."/rel="..." on rendered links -- see the linkTarget doc.
         // The default '_blank' is already truthy, so this preserves today's
         // exact output when the property is left unset.
         const linkTarget = this.linkTarget;
-        const headingOffset = this.headingOffset;
+        // A raw NaN (e.g. an invalid `heading-offset` attribute) would otherwise flow straight into
+        // `token.depth + headingOffset` below, producing a NaN heading depth and an invalid `<hNaN>`
+        // tag -- finiteInteger() normalizes it back to the documented `0` (additive-only) default.
+        const headingOffset = finiteInteger(this.headingOffset, 0);
         // Captured as a local distinct from the free function `escapeHtml` above
         // (imported/defined at the top of this file) to avoid shadowing/
         // ambiguity inside the renderer closure below, matching how
         // `linkTarget`/`headingOffset` are already captured as locals for the
         // same reason.
         const escapeHtmlOption = this.escapeHtml;
+        const highlightCodeOption = this.highlightCode && !this.streaming;
+        // Bound method reference (not the raw map): reads must go through the LRU accessor so a hit
+        // refreshes its recency. The renderer methods below run with marked's own `this`.
+        const getCachedHighlight = (key) => this.getCachedHighlight(key);
+        const failedHighlightKeys = this.failedHighlightKeys;
+        const headingAnchorsOption = this.headingAnchors;
+        const slugger = new Slugger();
+        const mathOption = this.math;
+        const cachedKatex = mathOption ? getKatexIfLoaded() : null;
+        let hadMathFallback = false;
         const instance = new marked.Marked();
+        if (mathOption) {
+            instance.use({
+                extensions: [
+                    mathExtension((token) => {
+                        if (!cachedKatex) {
+                            hadMathFallback = true;
+                            return escapeHtml(token.display ? `$$${token.tex}$$` : `$${token.tex}$`);
+                        }
+                        try {
+                            const mathml = cachedKatex.renderToString(token.tex, { output: 'mathml', throwOnError: false });
+                            return `<span part="math" data-display="${token.display ? 'block' : 'inline'}">${mathml}</span>`;
+                        }
+                        catch {
+                            // throwOnError: false already handles a malformed-TeX render internally (KaTeX's own
+                            // inline error form); this catch only guards against an unexpected non-KaTeX failure,
+                            // e.g. a broken/incompatible peer version -- same literal fallback, no event fired.
+                            return escapeHtml(token.display ? `$$${token.tex}$$` : `$${token.tex}$`);
+                        }
+                    }),
+                ],
+            });
+        }
         // A fresh renderer per parse (rather than a shared/cached one) so it
         // always closes over the *current* `linkTarget`/`headingOffset` — these
         // properties can change between renders, and marked's `.use()` otherwise
@@ -304,7 +722,13 @@ export class LyraMarkdown extends LyraElement {
                     // since headingOffset is meant to be additive-only (0 is the only
                     // documented non-positive value).
                     const depth = Math.min(6, Math.max(1, token.depth + headingOffset));
-                    return `<h${depth} part="heading">${this.parser.parseInline(token.tokens)}</h${depth}>\n`;
+                    // Rendered through the plain textRenderer so markup never leaks into the slug -- an
+                    // inline <code>/<em> inside a heading collapses to plain text for slugging purposes.
+                    const label = this.parser.parseInline(token.tokens, this.parser.textRenderer);
+                    const slug = slugger.slug(label);
+                    headingTreeOut.push({ id: slug, label, level: depth });
+                    const idAttr = headingAnchorsOption && slug ? ` id="${escapeHtml(slug)}"` : '';
+                    return `<h${depth} part="heading"${idAttr}>${this.parser.parseInline(token.tokens)}</h${depth}>\n`;
                 },
                 paragraph(token) {
                     return `<p part="paragraph">${this.parser.parseInline(token.tokens)}</p>\n`;
@@ -323,6 +747,14 @@ export class LyraMarkdown extends LyraElement {
                     const lang = (token.lang ?? '').trim().split(/\s+/)[0] ?? '';
                     const body = `${token.text.replace(/\n$/, '')}\n`;
                     const text = token.escaped ? body : escapeHtml(body);
+                    if (highlightCodeOption && lang) {
+                        const key = `${lang}\n${body}`;
+                        const cached = getCachedHighlight(key);
+                        if (cached !== undefined)
+                            return cached;
+                        if (!failedHighlightKeys.has(key))
+                            pendingKeys.push({ key, lang, code: body });
+                    }
                     const cls = lang ? ` class="language-${escapeHtml(lang)}"` : '';
                     return `<pre part="code-block"><code${cls}>${text}</code></pre>\n`;
                 },
@@ -386,7 +818,132 @@ export class LyraMarkdown extends LyraElement {
                 },
             },
         });
-        return instance.parse(this.content, { gfm: this.gfm, async: false });
+        return { html: instance.parse(this.content, { gfm: this.gfm, async: false }), hadMathFallback };
+    }
+    /** A document-ordered, flattened heading outline -- computed on every parse regardless of
+     *  `headingAnchors` (see that property's own doc). A caller building a table of contents can rely
+     *  on this even while `heading-anchors` is off. */
+    getHeadingTree() {
+        return [...this.headingTree];
+    }
+    contentRoot() {
+        return this.renderRoot.querySelector('[part="content"]');
+    }
+    // -- anchor-target: applyAnchor per kind -----------------------------------------------------
+    async applyAnchor(anchor) {
+        const root = this.contentRoot();
+        if (!root)
+            return false;
+        switch (anchor.kind) {
+            case 'fragment':
+                return this.applyFragmentAnchor(root, anchor);
+            case 'text-quote':
+                return this.applyTextQuoteAnchor(root, anchor);
+            default:
+                return false;
+        }
+    }
+    applyFragmentAnchor(root, anchor) {
+        if (!anchor.id)
+            return false;
+        const known = this.headingTree.some((h) => h.id === anchor.id);
+        if (!known)
+            return false;
+        const el = root.querySelector(`#${CSS.escape(anchor.id)}`) ?? this.findHeadingByComputedId(root, anchor.id);
+        if (!el)
+            return false;
+        el.scrollIntoView({ behavior: prefersReducedMotion() ? 'auto' : 'smooth', block: 'start' });
+        return true;
+    }
+    /** `headingAnchors` may be off, so a target heading might carry no `id` attribute in the DOM --
+     *  re-derives the same slug order `getHeadingTree()` was built in and matches by position
+     *  instead of by attribute. */
+    findHeadingByComputedId(root, id) {
+        const index = this.headingTree.findIndex((h) => h.id === id);
+        if (index < 0)
+            return null;
+        const headings = root.querySelectorAll('h1, h2, h3, h4, h5, h6');
+        return headings[index] ?? null;
+    }
+    applyTextQuoteAnchor(root, anchor) {
+        const range = resolveTextQuote(scopeFromElement(root), anchor);
+        if (!range)
+            return false;
+        const target = range.startContainer.nodeType === Node.ELEMENT_NODE ? range.startContainer : range.startContainer.parentElement;
+        (target ?? root).scrollIntoView({ behavior: prefersReducedMotion() ? 'auto' : 'smooth', block: 'center' });
+        return true;
+    }
+    /** Overrides `DocumentAnchorTarget`'s default (whole render-root) selection scope, matching
+     *  `heading`'s slug computation and `applyTextQuoteAnchor()` above: only `[part="content"]` is a
+     *  meaningful text-quote scope, so a selection that somehow reaches outside it (there is no other
+     *  text in this component's shadow tree today, but the live region could grow one) never leaks
+     *  into a captured anchor. */
+    computeSelectionAnchor(range) {
+        const root = this.contentRoot();
+        if (!root)
+            return null;
+        return buildQuoteAnchor(range, scopeFromElement(root));
+    }
+    // -- highlight painting ------------------------------------------------------------------------
+    ensureHighlightHandle() {
+        if (!this.highlightHandle)
+            this.highlightHandle = acquireHighlightHandle(this, this.ownerDocument);
+        return this.highlightHandle;
+    }
+    /** Re-resolves every `text-quote` highlight against the current rendered content and repaints
+     *  via `acquireHighlightHandle()` -- resolution is always by quote text, never by node identity,
+     *  so a highlight set before its quote exists in `content` yet (e.g. mid-`streaming`) simply
+     *  paints nothing until a later render's text actually contains it. `fragment` highlights aren't
+     *  painted (there is no literal span of text to wrap/underline for a whole section). */
+    repaintHighlights() {
+        this.resolvedHighlightRanges = [];
+        const root = this.contentRoot();
+        if (!root)
+            return;
+        const handle = this.ensureHighlightHandle();
+        const scope = scopeFromElement(root);
+        const rangesByTone = new Map(HIGHLIGHT_TONES.map((tone) => [tone, []]));
+        let activeRange = null;
+        for (const highlight of this.highlights) {
+            if (highlight.anchor.kind !== 'text-quote')
+                continue;
+            const range = resolveTextQuote(scope, highlight.anchor);
+            if (!range)
+                continue;
+            rangesByTone.get(highlight.tone ?? 'accent').push(range);
+            this.resolvedHighlightRanges.push({ id: highlight.id, range });
+            if (highlight.id === this.activeHighlightId)
+                activeRange = range;
+        }
+        for (const [tone, ranges] of rangesByTone)
+            handle.setRanges(tone, ranges);
+        handle.setActive(activeRange);
+        if (!supportsCustomHighlights()) {
+            // The `<mark>`-wrap fallback creates real elements but carries no `part` of its own (the
+            // module is shared by every adopting viewer, so it can't know this component's part naming)
+            // -- stamped here so a consumer can still target `::part(highlight)` in browsers lacking the
+            // CSS Custom Highlight API. Nothing to stamp on the API path: no DOM element is created there.
+            for (const mark of root.querySelectorAll('mark[data-lyra-highlight-tone]')) {
+                if (!mark.hasAttribute('part'))
+                    mark.setAttribute('part', 'highlight');
+            }
+        }
+    }
+    /** Hit-tests a click point against every currently-resolved highlight's `getClientRects()`,
+     *  topmost (last-resolved) first. The CSS Custom Highlight API paints ranges without creating any
+     *  DOM element to attach a click listener to, so this is the only activation path that works
+     *  identically on both paint paths -- mirrors `<lyra-pdf-viewer>`'s own coordinate-based
+     *  `onPageClick()` hit-test for the same reason (its own painted highlights sit under a text
+     *  layer that intercepts most pointer events). */
+    hitTestHighlightAt(x, y) {
+        for (let i = this.resolvedHighlightRanges.length - 1; i >= 0; i--) {
+            const { id, range } = this.resolvedHighlightRanges[i];
+            for (const rect of range.getClientRects()) {
+                if (x >= rect.left && x <= rect.right && y >= rect.top && y <= rect.bottom)
+                    return id;
+            }
+        }
+        return null;
     }
     render() {
         const isFallback = this.renderedHtml === null;
@@ -394,6 +951,7 @@ export class LyraMarkdown extends LyraElement {
       <div part="content" ?data-fallback=${isFallback} @click=${this.onContentClick}>
         ${isFallback ? this.content : unsafeHTML(this.renderedHtml)}
       </div>
+      ${this.renderAnchorLiveRegion()}
     `;
     }
 }
@@ -424,6 +982,21 @@ __decorate([
 __decorate([
     property({ type: Boolean, reflect: true })
 ], LyraMarkdown.prototype, "streaming", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'highlight-code' })
+], LyraMarkdown.prototype, "highlightCode", void 0);
+__decorate([
+    property({ attribute: false })
+], LyraMarkdown.prototype, "languages", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'languages-only' })
+], LyraMarkdown.prototype, "languagesOnly", void 0);
+__decorate([
+    property({ type: Boolean, attribute: 'heading-anchors' })
+], LyraMarkdown.prototype, "headingAnchors", void 0);
+__decorate([
+    property({ type: Boolean })
+], LyraMarkdown.prototype, "math", void 0);
 __decorate([
     state()
 ], LyraMarkdown.prototype, "renderedHtml", void 0);