jupyterlab_markdown_syntax_rendering_fix 0.6.9 → 1.0.2

package/README.md

@@ -8,23 +8,38 @@
 [![Brought To You By KOLOMOLO](https://img.shields.io/badge/Brought%20To%20You%20By-KOLOMOLO-00ffff?style=flat)](https://kolomolo.com)
 [![Donate PayPal](https://img.shields.io/badge/Donate-PayPal-blue?style=flat)](https://www.paypal.com/donate/?hosted_button_id=B4KPBJDLLXTSA)
 
-Fenced code blocks in rendered Markdown sometimes appear plain and uncoloured - the highlighting silently fails when a CodeMirror language chunk loads late or the language registry is not yet ready, and JupyterLab falls back to plain text. This extension restores the highlighting that was lost to that race.
+JupyterLab 4.x extension that restores syntax-highlight colours in rendered Markdown fenced code blocks when no CodeMirror editor is open.
 
-## Features
+> [!WARNING]
+> This extension is a temporary fix for a JupyterLab 4.x behaviour where rendered Markdown code highlighting depends on a CodeMirror editor having been opened. Once JupyterLab core mounts the highlight style for the Markdown renderer independently, this extension will be obsolete and should not be installed.
 
-- **Recovers lost highlighting** - re-applies syntax highlighting to fenced code blocks that rendered plain because the async highlighter missed the cache
-- **Language agnostic** - works for any fenced language (bash, python, json, ...), independent of mermaid
-- **Targets the cold-load race** - handles the case where a language chunk imports late or the registry is wired after an early render
-- **Frontend only** - pure TypeScript labextension, no server component
+## The Problem
 
-## How it works
+Fenced code blocks in rendered Markdown (the Markdown Preview, README files, `.md` documents) appear in a single flat colour instead of syntax-highlighted, even though the highlighter clearly ran.
 
-JupyterLab highlights fenced code in rendered Markdown with an async pass that fills a cache and a synchronous renderer that reads it. When the async highlight throws - a CodeMirror language-chunk import that rejects, or a registry that is not yet wired when an early render fires - the cache misses and the renderer emits a plain `<pre><code>`. This extension watches the application shell for those plain blocks and re-runs the highlight once the language is available.
+**Symptoms**:
 
-- **Detect** - a `MutationObserver` flags any rendered `pre > code` that has a `language-*` class and text but no token `<span>` children
-- **Recover** - re-runs the highlight through `IEditorLanguageRegistry` and swaps in the token spans, only when the highlighted text matches the source exactly so it never truncates content
-- **Resilient** - retries a thrown highlight a few times with backoff while the language chunk finishes loading, then gives up cleanly and leaves the original plain text untouched
-- **Unobtrusive** - each block is handled at most once, and editor and overlay churn is skipped to keep the observer cheap
+- bash, python, json and other fenced blocks render in one uniform grey, not coloured tokens
+- Opening the same file in the editor, then returning to the preview, makes the colours appear - and they stay for the rest of the session
+- Affects any rendered Markdown when the session has not yet opened a CodeMirror editor (notebook cell, file editor, console)
+
+**Root cause - the highlight StyleModule is never mounted**:
+
+- JupyterLab's Markdown renderer highlights code through `@jupyterlab/codemirror`, producing token `<span>`s with CodeMirror's generated highlight classes (e.g. `ͼs`, `ͼ11`)
+- Those class names are emitted by a CodeMirror `StyleModule`, and the CSS that gives them colour is mounted only when an `EditorView` is instantiated (via `syntaxHighlighting(jupyterHighlightStyle)`)
+- With only Markdown previews open, no `EditorView` exists, so the StyleModule is never mounted - the spans carry the right classes but no colour rule, and inherit the plain code text colour
+- Opening any editor mounts the StyleModule document-wide, which is why the workaround of opening the file in the editor fixes the preview
+
+## The Fix
+
+The extension mounts the highlight StyleModule's CSS once at startup, achieving the same effect as opening an editor - without one.
+
+**How it works**:
+
+- On activation, reads the rules from `jupyterHighlightStyle.module` (the same StyleModule the Markdown renderer's spans reference) via `getRules()`
+- Injects them into a single `<style>` element in the document head, so every rendered Markdown code block is coloured immediately
+- Colours are expressed as `--jp-mirror-editor-*-color` CSS variables, so they resolve through whatever theme is active and update on theme change
+- Injection is idempotent (fixed element id) and frontend-only - no server component, no per-render DOM observer
 
 ## Requirements
 
@@ -45,3 +60,65 @@ To remove the extension, execute:
 ```bash
 pip uninstall jupyterlab_markdown_syntax_rendering_fix
 ```
+
+## Contributing
+
+### Development install
+
+Note: You will need NodeJS to build the extension package.
+
+The `jlpm` command is JupyterLab's pinned version of [yarn](https://yarnpkg.com/) that is installed with JupyterLab. You may use `yarn` or `npm` in lieu of `jlpm` below.
+
+```bash
+# Clone the repo to your local environment
+# Change directory to the jupyterlab_markdown_syntax_rendering_fix directory
+
+# Set up a virtual environment and install package in development mode
+python -m venv .venv
+source .venv/bin/activate
+pip install --editable "."
+
+# Link your development version of the extension with JupyterLab
+jupyter labextension develop . --overwrite
+
+# Rebuild extension TypeScript source after making changes
+# IMPORTANT: Unlike the steps above which are performed only once, do this step
+# every time you make a change.
+jlpm build
+```
+
+You can watch the source directory and run JupyterLab at the same time in different terminals to watch for changes in the extension's source and automatically rebuild the extension.
+
+```bash
+# Watch the source directory in one terminal, automatically rebuilding when needed
+jlpm watch
+# Run JupyterLab in another terminal
+jupyter lab
+```
+
+### Development uninstall
+
+```bash
+pip uninstall jupyterlab_markdown_syntax_rendering_fix
+```
+
+In development mode, you will also need to remove the symlink created by `jupyter labextension develop` command. To find its location, you can run `jupyter labextension list` to figure out where the `labextensions` folder is located. Then you can remove the symlink named `jupyterlab_markdown_syntax_rendering_fix` within that folder.
+
+### Testing the extension
+
+#### Frontend tests
+
+This extension is using [Jest](https://jestjs.io/) for JavaScript code testing.
+
+To execute them, execute:
+
+```sh
+jlpm
+jlpm test
+```
+
+#### Integration tests
+
+This extension uses [Playwright](https://playwright.dev/docs/intro) for the integration tests (aka user level tests). More precisely, the JupyterLab helper [Galata](https://github.com/jupyterlab/jupyterlab/tree/master/galata) is used to handle testing the extension in JupyterLab.
+
+More information are provided within the [ui-tests](./ui-tests/README.md) README.

package/lib/highlight.d.ts

@@ -1,35 +1,23 @@
 /**
- * Pure DOM helpers for detecting fenced code blocks that rendered without
- * syntax highlighting. Kept free of JupyterLab imports so they can be unit
- * tested directly.
+ * Restore syntax highlighting in rendered Markdown code blocks.
+ *
+ * Kept free of JupyterLab imports so it can be unit tested directly.
  */
+/** Id of the injected highlight-style element, used to keep injection idempotent. */
+export declare const HIGHLIGHT_STYLE_ID = "jupyterlab-markdown-syntax-rendering-fix-highlight";
 /**
- * Attribute marking a code block this extension has already handled, so the
- * MutationObserver never re-processes the same block.
+ * Inject the CodeMirror highlight StyleModule's CSS into `doc` so rendered
+ * Markdown token spans are coloured.
+ *
+ * Rendered code blocks already carry the generated highlight classes (e.g.
+ * `ͼs`), but the StyleModule that gives those classes their colours is only
+ * mounted when a CodeMirror `EditorView` is instantiated. With only Markdown
+ * previews open, no editor exists, so the spans inherit the plain code colour
+ * and look unhighlighted. Mounting the rules once - the same effect as opening
+ * the editor - colours every preview. Colours resolve through
+ * `--jp-mirror-editor-*-color` CSS variables, so they track the active theme.
+ *
+ * Idempotent: a fixed element id means repeated calls are a no-op, and an empty
+ * rule string is ignored.
  */
-export declare const PROCESSED_ATTR = "data-msrf";
-/**
- * Fenced languages rendered by their own renderer (e.g. mermaid -> SVG). They
- * are never plain `pre > code` highlight candidates, so leave them untouched.
- */
-export declare const SKIP_LANGUAGES: Set<string>;
-/**
- * Extract the CodeMirror language name from a `language-<name>` class token.
- * Returns null when no such class is present.
- */
-export declare function languageFromClass(className: string): string | null;
-/**
- * A rendered fenced code block has lost its syntax highlighting when it carries
- * a `language-*` class and non-empty text, yet has no child elements - the
- * async highlighter threw and the markdown renderer fell back to a plain
- * `<pre><code>` (cache miss). A correctly highlighted block holds token
- * `<span>` children, so `childElementCount > 0`.
- */
-export declare function needsHighlight(code: HTMLElement): boolean;
-/**
- * Collect the plain `pre > code.language-*` blocks at or under `root` that need
- * their highlighting recovered. `root` itself is considered, since
- * `querySelectorAll` only matches descendants and an observer may hand us the
- * `<code>` element directly.
- */
-export declare function collectPlainBlocks(root: ParentNode): HTMLElement[];
+export declare function injectHighlightRules(rules: string, doc?: Document): void;

package/lib/highlight.js

@@ -1,62 +1,32 @@
 /**
- * Pure DOM helpers for detecting fenced code blocks that rendered without
- * syntax highlighting. Kept free of JupyterLab imports so they can be unit
- * tested directly.
+ * Restore syntax highlighting in rendered Markdown code blocks.
+ *
+ * Kept free of JupyterLab imports so it can be unit tested directly.
  */
+/** Id of the injected highlight-style element, used to keep injection idempotent. */
+export const HIGHLIGHT_STYLE_ID = 'jupyterlab-markdown-syntax-rendering-fix-highlight';
 /**
- * Attribute marking a code block this extension has already handled, so the
- * MutationObserver never re-processes the same block.
+ * Inject the CodeMirror highlight StyleModule's CSS into `doc` so rendered
+ * Markdown token spans are coloured.
+ *
+ * Rendered code blocks already carry the generated highlight classes (e.g.
+ * `ͼs`), but the StyleModule that gives those classes their colours is only
+ * mounted when a CodeMirror `EditorView` is instantiated. With only Markdown
+ * previews open, no editor exists, so the spans inherit the plain code colour
+ * and look unhighlighted. Mounting the rules once - the same effect as opening
+ * the editor - colours every preview. Colours resolve through
+ * `--jp-mirror-editor-*-color` CSS variables, so they track the active theme.
+ *
+ * Idempotent: a fixed element id means repeated calls are a no-op, and an empty
+ * rule string is ignored.
  */
-export const PROCESSED_ATTR = 'data-msrf';
-/**
- * Fenced languages rendered by their own renderer (e.g. mermaid -> SVG). They
- * are never plain `pre > code` highlight candidates, so leave them untouched.
- */
-export const SKIP_LANGUAGES = new Set(['mermaid']);
-/**
- * Extract the CodeMirror language name from a `language-<name>` class token.
- * Returns null when no such class is present.
- */
-export function languageFromClass(className) {
-    const match = /(?:^|\s)language-([\w+#-]+)/.exec(className);
-    return match ? match[1] : null;
-}
-/**
- * A rendered fenced code block has lost its syntax highlighting when it carries
- * a `language-*` class and non-empty text, yet has no child elements - the
- * async highlighter threw and the markdown renderer fell back to a plain
- * `<pre><code>` (cache miss). A correctly highlighted block holds token
- * `<span>` children, so `childElementCount > 0`.
- */
-export function needsHighlight(code) {
+export function injectHighlightRules(rules, doc = document) {
     var _a;
-    if (code.hasAttribute(PROCESSED_ATTR) || code.childElementCount > 0) {
-        return false;
-    }
-    const language = languageFromClass(code.className);
-    if (!language || SKIP_LANGUAGES.has(language)) {
-        return false;
-    }
-    return ((_a = code.textContent) !== null && _a !== void 0 ? _a : '').trim().length > 0;
-}
-/** CSS selector for a fenced code block carrying a language hint. */
-const CODE_SELECTOR = 'pre > code[class*="language-"]';
-/**
- * Collect the plain `pre > code.language-*` blocks at or under `root` that need
- * their highlighting recovered. `root` itself is considered, since
- * `querySelectorAll` only matches descendants and an observer may hand us the
- * `<code>` element directly.
- */
-export function collectPlainBlocks(root) {
-    const blocks = [];
-    const consider = (code) => {
-        if (needsHighlight(code)) {
-            blocks.push(code);
-        }
-    };
-    if (root instanceof HTMLElement && root.matches(CODE_SELECTOR)) {
-        consider(root);
+    if (!rules || doc.getElementById(HIGHLIGHT_STYLE_ID)) {
+        return;
     }
-    root.querySelectorAll(CODE_SELECTOR).forEach(consider);
-    return blocks;
+    const style = doc.createElement('style');
+    style.id = HIGHLIGHT_STYLE_ID;
+    style.textContent = rules;
+    ((_a = doc.head) !== null && _a !== void 0 ? _a : doc.documentElement).appendChild(style);
 }

package/lib/index.js

@@ -1,146 +1,23 @@
-import { IEditorLanguageRegistry } from '@jupyterlab/codemirror';
-import { PROCESSED_ATTR, collectPlainBlocks, languageFromClass } from './highlight';
-/** How many times to attempt recovery (only a thrown highlight is retried). */
-const MAX_ATTEMPTS = 4;
-/** Base retry delay; backs off 750/1500/3000ms (~5s total) so a slow chunk import can settle. */
-const BASE_RETRY_DELAY_MS = 750;
-/** Blocks currently being recovered, to dedupe concurrent observer callbacks. */
-const inFlight = new WeakSet();
-const delay = (ms) => new Promise(resolve => {
-    window.setTimeout(resolve, ms);
-});
-/**
- * Recover highlighting on a single plain block, and mark it with a terminal
- * `data-msrf` state so it is processed at most once:
- *
- * - `1`       success - token spans written
- * - `plain`   highlight ran cleanly but produced no tokens (span-less content) -
- *             not a failure, the original plain text is left untouched
- * - `skipped` the language is unsupported (`findBest` miss) - deterministic, so
- *             no retry and no warning
- * - `failed`  the highlight threw on every attempt - left as plain text, no
- *             regression vs without this extension
- *
- * Only a thrown highlight is retried, since that is the one transient case (a
- * cold/flaky CodeMirror language-chunk import). Retrying is effective, not
- * theatre: `highlight()` awaits `getLanguage()` internally, which caches the
- * loaded support on the spec only on success (`spec.support = await spec.load()`)
- * - a rejected load throws and leaves `spec.support` unset, and webpack resets a
- * failed chunk load, so each attempt genuinely re-runs the dynamic import.
- * Retries back off over ~5s; a chunk that never loads within that window stays
- * plain until the block is re-rendered (reload / reopen). Concurrent callbacks
- * are deduped via `inFlight`.
- */
-async function rehighlight(code, languages) {
-    var _a;
-    const language = languageFromClass(code.className);
-    if (!language || inFlight.has(code) || code.hasAttribute(PROCESSED_ATTR)) {
-        return;
-    }
-    const text = (_a = code.textContent) !== null && _a !== void 0 ? _a : '';
-    inFlight.add(code);
-    try {
-        for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-            const spec = languages.findBest(language);
-            if (!spec) {
-                // Unsupported language - a synchronous registry miss is deterministic,
-                // so retrying cannot help. Leave it plain, no warning.
-                code.setAttribute(PROCESSED_ATTR, 'skipped');
-                return;
-            }
-            const host = document.createElement('div');
-            try {
-                await languages.highlight(text, spec, host);
-            }
-            catch (_b) {
-                // The one retryable case: a transient chunk-load flake.
-                if (attempt < MAX_ATTEMPTS) {
-                    await delay(BASE_RETRY_DELAY_MS * 2 ** (attempt - 1));
-                    // The host may have been re-rendered during the back-off; a fresh node
-                    // is handled independently, so stop working this detached one.
-                    if (!code.isConnected) {
-                        return;
-                    }
-                    continue;
-                }
-                code.setAttribute(PROCESSED_ATTR, 'failed');
-                console.warn(`[jupyterlab_markdown_syntax_rendering_fix] gave up re-highlighting ${language} after ${MAX_ATTEMPTS} attempts`);
-                return;
-            }
-            // The node may have been re-rendered during the await; a fresh node is
-            // handled independently, so don't write to a detached one.
-            if (!code.isConnected) {
-                return;
-            }
-            // Highlight ran without throwing. Commit the swap only when the rendered
-            // text round-trips exactly - never replace the block with a truncated or
-            // divergent fragment (worse than leaving it plain). An empty result is
-            // deterministic for the content (a parser that failed to load throws
-            // rather than resolving empty), so it is terminal, not retried.
-            if (host.childElementCount > 0 && host.textContent === text) {
-                // Set the marker in the same synchronous frame as the write so the
-                // observer's async callback sees data-msrf and skips the spans we add.
-                code.setAttribute(PROCESSED_ATTR, '1');
-                code.replaceChildren(...Array.from(host.childNodes));
-            }
-            else {
-                if (host.childElementCount > 0) {
-                    // Spans were produced but the text did not round-trip - surface this
-                    // rare case rather than silently suppressing a possibly-correct render.
-                    console.warn(`[jupyterlab_markdown_syntax_rendering_fix] skipped re-highlight of ${language}: highlighted text did not match source`);
-                }
-                code.setAttribute(PROCESSED_ATTR, 'plain');
-            }
-            return;
-        }
-    }
-    finally {
-        inFlight.delete(code);
-    }
-}
+import { jupyterHighlightStyle } from '@jupyterlab/codemirror';
+import { injectHighlightRules } from './highlight';
 /**
  * Initialization data for the jupyterlab_markdown_syntax_rendering_fix extension.
  */
 const plugin = {
     id: 'jupyterlab_markdown_syntax_rendering_fix:plugin',
-    description: 'Jupyterlab extension to fix a common issue with Markdown renderer where some race condition causes for the fenced code block to not have proper syntax highlighting',
+    description: 'Restore syntax highlighting in rendered Markdown code blocks by mounting the CodeMirror highlight StyleModule at startup, so token colours apply even when no editor is open.',
     autoStart: true,
-    requires: [IEditorLanguageRegistry],
-    activate: (app, languages) => {
+    activate: () => {
+        var _a, _b;
         console.log('JupyterLab extension jupyterlab_markdown_syntax_rendering_fix is activated!');
-        const scan = (root) => {
-            for (const code of collectPlainBlocks(root)) {
-                rehighlight(code, languages).catch(error => {
-                    console.warn('[jupyterlab_markdown_syntax_rendering_fix] unexpected error while re-highlighting', error);
-                });
-            }
-        };
-        const observer = new MutationObserver(mutations => {
-            for (const mutation of mutations) {
-                mutation.addedNodes.forEach(node => {
-                    if (node.nodeType !== Node.ELEMENT_NODE) {
-                        return;
-                    }
-                    const element = node;
-                    // Skip pure observer churn: CodeMirror editors mutate on every
-                    // keystroke and never hold rendered markdown, and the token spans this
-                    // extension itself writes land under an already-processed code block.
-                    if (element.closest('.cm-editor, code[data-msrf]')) {
-                        return;
-                    }
-                    scan(element);
-                });
-            }
-        });
-        // Observe the application shell rather than document.body: rendered markdown
-        // lives in the shell (notebook cells, markdown preview). Markdown rendered in
-        // body-level overlays (completer / hover docstrings) is intentionally not
-        // covered - a deliberate tradeoff to avoid observing the high-churn overlay
-        // layer; such code blocks recover on the next in-shell render or a reload.
-        const root = app.shell.node;
-        observer.observe(root, { childList: true, subtree: true });
-        // Recover any markdown already rendered before this extension activated.
-        scan(root);
+        // Rendered Markdown code blocks receive CodeMirror highlight token classes
+        // (e.g. ͼs), but the StyleModule that gives those classes their colours is
+        // only mounted when a CodeMirror EditorView is instantiated. With only
+        // Markdown previews open, no editor exists, so the spans inherit the plain
+        // code colour and look unhighlighted. Mounting the rules once - the same
+        // effect as opening the editor - colours every preview, and the colours
+        // track the active theme through --jp-mirror-editor-*-color variables.
+        injectHighlightRules((_b = (_a = jupyterHighlightStyle.module) === null || _a === void 0 ? void 0 : _a.getRules()) !== null && _b !== void 0 ? _b : '');
     }
 };
 export default plugin;

package/package.json

@@ -1,7 +1,7 @@
 {
     "name": "jupyterlab_markdown_syntax_rendering_fix",
-    "version": "0.6.9",
-    "description": "Jupyterlab extension to fix a common issue with Markdown renderer where some race condition causes for the fenced code block to not have proper syntax highlighting",
+    "version": "1.0.2",
+    "description": "JupyterLab extension that restores syntax-highlight colours in rendered Markdown fenced code blocks by mounting the CodeMirror highlight StyleModule, so token colours apply even when no editor is open",
     "keywords": [
         "jupyter",
         "jupyterlab",

package/src/__tests__/jupyterlab_markdown_syntax_rendering_fix.spec.ts

@@ -1,100 +1,29 @@
-import {
-  PROCESSED_ATTR,
-  collectPlainBlocks,
-  languageFromClass,
-  needsHighlight
-} from '../highlight';
+import { HIGHLIGHT_STYLE_ID, injectHighlightRules } from '../highlight';
 
-/** Build a `pre > code` block with the given class and inner HTML. */
-function block(className: string, inner: string): HTMLElement {
-  const pre = document.createElement('pre');
-  const code = document.createElement('code');
-  code.className = className;
-  code.innerHTML = inner;
-  pre.appendChild(code);
-  return code;
-}
-
-describe('languageFromClass', () => {
-  it('extracts the language from a language-* class', () => {
-    expect(languageFromClass('language-bash')).toBe('bash');
-  });
-
-  it('finds the token among other classes', () => {
-    expect(languageFromClass('hljs language-python foo')).toBe('python');
+describe('injectHighlightRules', () => {
+  afterEach(() => {
+    document.getElementById(HIGHLIGHT_STYLE_ID)?.remove();
   });
 
-  it('keeps symbol-bearing language names', () => {
-    expect(languageFromClass('language-c++')).toBe('c++');
-    expect(languageFromClass('language-c#')).toBe('c#');
+  it('appends a style element carrying the rules', () => {
+    injectHighlightRules('.ͼs{color:red}');
+    const style = document.getElementById(HIGHLIGHT_STYLE_ID);
+    expect(style).not.toBeNull();
+    expect(style!.tagName).toBe('STYLE');
+    expect(style!.textContent).toBe('.ͼs{color:red}');
   });
 
-  it('returns null without a language class', () => {
-    expect(languageFromClass('hljs')).toBeNull();
-    expect(languageFromClass('')).toBeNull();
-  });
-});
-
-describe('needsHighlight', () => {
-  it('flags a plain block with a language and text', () => {
-    expect(needsHighlight(block('language-bash', 'pip install x'))).toBe(true);
-  });
-
-  it('ignores a block that already has token spans', () => {
-    expect(
-      needsHighlight(block('language-bash', '<span class="tok">pip</span>'))
-    ).toBe(false);
-  });
-
-  it('ignores an already-processed block', () => {
-    const code = block('language-bash', 'pip install x');
-    code.setAttribute(PROCESSED_ATTR, '1');
-    expect(needsHighlight(code)).toBe(false);
-  });
-
-  it('ignores blocks without a language class', () => {
-    expect(needsHighlight(block('', 'plain text'))).toBe(false);
-  });
-
-  it('ignores empty or whitespace-only blocks', () => {
-    expect(needsHighlight(block('language-bash', '   '))).toBe(false);
-  });
-
-  it('skips languages owned by other renderers (mermaid)', () => {
-    expect(needsHighlight(block('language-mermaid', 'graph TD; A-->B'))).toBe(
-      false
-    );
-  });
-});
-
-describe('collectPlainBlocks', () => {
-  it('returns only the plain language blocks under a root', () => {
-    const root = document.createElement('div');
-    root.appendChild(block('language-bash', 'echo hi').parentElement!);
-    root.appendChild(
-      block('language-python', '<span class="tok">import os</span>')
-        .parentElement!
-    );
-    root.appendChild(block('language-json', '{"a": 1}').parentElement!);
-    root.appendChild(
-      block('language-mermaid', 'graph TD; A-->B').parentElement!
+  it('is idempotent - a second call does not add another element', () => {
+    injectHighlightRules('.ͼs{color:red}');
+    injectHighlightRules('.ͼs{color:blue}');
+    expect(document.querySelectorAll(`#${HIGHLIGHT_STYLE_ID}`)).toHaveLength(1);
+    expect(document.getElementById(HIGHLIGHT_STYLE_ID)!.textContent).toBe(
+      '.ͼs{color:red}'
     );
-
-    const found = collectPlainBlocks(root);
-    const langs = found.map(c => languageFromClass(c.className));
-    expect(langs).toEqual(['bash', 'json']);
   });
 
-  it('matches a bare code element passed as the root', () => {
-    const code = block('language-bash', 'echo hi');
-    expect(collectPlainBlocks(code)).toEqual([code]);
-  });
-
-  it('returns an empty list when everything is already highlighted', () => {
-    const root = document.createElement('div');
-    root.appendChild(
-      block('language-bash', '<span class="tok">echo</span>').parentElement!
-    );
-    expect(collectPlainBlocks(root)).toHaveLength(0);
+  it('ignores an empty rule string', () => {
+    injectHighlightRules('');
+    expect(document.getElementById(HIGHLIGHT_STYLE_ID)).toBeNull();
   });
 });

package/src/highlight.ts

@@ -1,67 +1,37 @@
 /**
- * Pure DOM helpers for detecting fenced code blocks that rendered without
- * syntax highlighting. Kept free of JupyterLab imports so they can be unit
- * tested directly.
+ * Restore syntax highlighting in rendered Markdown code blocks.
+ *
+ * Kept free of JupyterLab imports so it can be unit tested directly.
  */
 
-/**
- * Attribute marking a code block this extension has already handled, so the
- * MutationObserver never re-processes the same block.
- */
-export const PROCESSED_ATTR = 'data-msrf';
-
-/**
- * Fenced languages rendered by their own renderer (e.g. mermaid -> SVG). They
- * are never plain `pre > code` highlight candidates, so leave them untouched.
- */
-export const SKIP_LANGUAGES = new Set(['mermaid']);
-
-/**
- * Extract the CodeMirror language name from a `language-<name>` class token.
- * Returns null when no such class is present.
- */
-export function languageFromClass(className: string): string | null {
-  const match = /(?:^|\s)language-([\w+#-]+)/.exec(className);
-  return match ? match[1] : null;
-}
-
-/**
- * A rendered fenced code block has lost its syntax highlighting when it carries
- * a `language-*` class and non-empty text, yet has no child elements - the
- * async highlighter threw and the markdown renderer fell back to a plain
- * `<pre><code>` (cache miss). A correctly highlighted block holds token
- * `<span>` children, so `childElementCount > 0`.
- */
-export function needsHighlight(code: HTMLElement): boolean {
-  if (code.hasAttribute(PROCESSED_ATTR) || code.childElementCount > 0) {
-    return false;
-  }
-  const language = languageFromClass(code.className);
-  if (!language || SKIP_LANGUAGES.has(language)) {
-    return false;
-  }
-  return (code.textContent ?? '').trim().length > 0;
-}
-
-/** CSS selector for a fenced code block carrying a language hint. */
-const CODE_SELECTOR = 'pre > code[class*="language-"]';
+/** Id of the injected highlight-style element, used to keep injection idempotent. */
+export const HIGHLIGHT_STYLE_ID =
+  'jupyterlab-markdown-syntax-rendering-fix-highlight';
 
 /**
- * Collect the plain `pre > code.language-*` blocks at or under `root` that need
- * their highlighting recovered. `root` itself is considered, since
- * `querySelectorAll` only matches descendants and an observer may hand us the
- * `<code>` element directly.
+ * Inject the CodeMirror highlight StyleModule's CSS into `doc` so rendered
+ * Markdown token spans are coloured.
+ *
+ * Rendered code blocks already carry the generated highlight classes (e.g.
+ * `ͼs`), but the StyleModule that gives those classes their colours is only
+ * mounted when a CodeMirror `EditorView` is instantiated. With only Markdown
+ * previews open, no editor exists, so the spans inherit the plain code colour
+ * and look unhighlighted. Mounting the rules once - the same effect as opening
+ * the editor - colours every preview. Colours resolve through
+ * `--jp-mirror-editor-*-color` CSS variables, so they track the active theme.
+ *
+ * Idempotent: a fixed element id means repeated calls are a no-op, and an empty
+ * rule string is ignored.
  */
-export function collectPlainBlocks(root: ParentNode): HTMLElement[] {
-  const blocks: HTMLElement[] = [];
-  const consider = (code: HTMLElement): void => {
-    if (needsHighlight(code)) {
-      blocks.push(code);
-    }
-  };
-  if (root instanceof HTMLElement && root.matches(CODE_SELECTOR)) {
-    consider(root);
+export function injectHighlightRules(
+  rules: string,
+  doc: Document = document
+): void {
+  if (!rules || doc.getElementById(HIGHLIGHT_STYLE_ID)) {
+    return;
   }
-  root.querySelectorAll<HTMLElement>(CODE_SELECTOR).forEach(consider);
-  return blocks;
+  const style = doc.createElement('style');
+  style.id = HIGHLIGHT_STYLE_ID;
+  style.textContent = rules;
+  (doc.head ?? doc.documentElement).appendChild(style);
 }

package/src/index.ts

@@ -1,120 +1,6 @@
-import {
-  JupyterFrontEnd,
-  JupyterFrontEndPlugin
-} from '@jupyterlab/application';
-import { IEditorLanguageRegistry } from '@jupyterlab/codemirror';
-import {
-  PROCESSED_ATTR,
-  collectPlainBlocks,
-  languageFromClass
-} from './highlight';
-
-/** How many times to attempt recovery (only a thrown highlight is retried). */
-const MAX_ATTEMPTS = 4;
-
-/** Base retry delay; backs off 750/1500/3000ms (~5s total) so a slow chunk import can settle. */
-const BASE_RETRY_DELAY_MS = 750;
-
-/** Blocks currently being recovered, to dedupe concurrent observer callbacks. */
-const inFlight = new WeakSet<HTMLElement>();
-
-const delay = (ms: number): Promise<void> =>
-  new Promise(resolve => {
-    window.setTimeout(resolve, ms);
-  });
-
-/**
- * Recover highlighting on a single plain block, and mark it with a terminal
- * `data-msrf` state so it is processed at most once:
- *
- * - `1`       success - token spans written
- * - `plain`   highlight ran cleanly but produced no tokens (span-less content) -
- *             not a failure, the original plain text is left untouched
- * - `skipped` the language is unsupported (`findBest` miss) - deterministic, so
- *             no retry and no warning
- * - `failed`  the highlight threw on every attempt - left as plain text, no
- *             regression vs without this extension
- *
- * Only a thrown highlight is retried, since that is the one transient case (a
- * cold/flaky CodeMirror language-chunk import). Retrying is effective, not
- * theatre: `highlight()` awaits `getLanguage()` internally, which caches the
- * loaded support on the spec only on success (`spec.support = await spec.load()`)
- * - a rejected load throws and leaves `spec.support` unset, and webpack resets a
- * failed chunk load, so each attempt genuinely re-runs the dynamic import.
- * Retries back off over ~5s; a chunk that never loads within that window stays
- * plain until the block is re-rendered (reload / reopen). Concurrent callbacks
- * are deduped via `inFlight`.
- */
-async function rehighlight(
-  code: HTMLElement,
-  languages: IEditorLanguageRegistry
-): Promise<void> {
-  const language = languageFromClass(code.className);
-  if (!language || inFlight.has(code) || code.hasAttribute(PROCESSED_ATTR)) {
-    return;
-  }
-  const text = code.textContent ?? '';
-  inFlight.add(code);
-  try {
-    for (let attempt = 1; attempt <= MAX_ATTEMPTS; attempt++) {
-      const spec = languages.findBest(language);
-      if (!spec) {
-        // Unsupported language - a synchronous registry miss is deterministic,
-        // so retrying cannot help. Leave it plain, no warning.
-        code.setAttribute(PROCESSED_ATTR, 'skipped');
-        return;
-      }
-      const host = document.createElement('div');
-      try {
-        await languages.highlight(text, spec, host);
-      } catch {
-        // The one retryable case: a transient chunk-load flake.
-        if (attempt < MAX_ATTEMPTS) {
-          await delay(BASE_RETRY_DELAY_MS * 2 ** (attempt - 1));
-          // The host may have been re-rendered during the back-off; a fresh node
-          // is handled independently, so stop working this detached one.
-          if (!code.isConnected) {
-            return;
-          }
-          continue;
-        }
-        code.setAttribute(PROCESSED_ATTR, 'failed');
-        console.warn(
-          `[jupyterlab_markdown_syntax_rendering_fix] gave up re-highlighting ${language} after ${MAX_ATTEMPTS} attempts`
-        );
-        return;
-      }
-      // The node may have been re-rendered during the await; a fresh node is
-      // handled independently, so don't write to a detached one.
-      if (!code.isConnected) {
-        return;
-      }
-      // Highlight ran without throwing. Commit the swap only when the rendered
-      // text round-trips exactly - never replace the block with a truncated or
-      // divergent fragment (worse than leaving it plain). An empty result is
-      // deterministic for the content (a parser that failed to load throws
-      // rather than resolving empty), so it is terminal, not retried.
-      if (host.childElementCount > 0 && host.textContent === text) {
-        // Set the marker in the same synchronous frame as the write so the
-        // observer's async callback sees data-msrf and skips the spans we add.
-        code.setAttribute(PROCESSED_ATTR, '1');
-        code.replaceChildren(...Array.from(host.childNodes));
-      } else {
-        if (host.childElementCount > 0) {
-          // Spans were produced but the text did not round-trip - surface this
-          // rare case rather than silently suppressing a possibly-correct render.
-          console.warn(
-            `[jupyterlab_markdown_syntax_rendering_fix] skipped re-highlight of ${language}: highlighted text did not match source`
-          );
-        }
-        code.setAttribute(PROCESSED_ATTR, 'plain');
-      }
-      return;
-    }
-  } finally {
-    inFlight.delete(code);
-  }
-}
+import { JupyterFrontEndPlugin } from '@jupyterlab/application';
+import { jupyterHighlightStyle } from '@jupyterlab/codemirror';
+import { injectHighlightRules } from './highlight';
 
 /**
  * Initialization data for the jupyterlab_markdown_syntax_rendering_fix extension.
@@ -122,53 +8,21 @@ async function rehighlight(
 const plugin: JupyterFrontEndPlugin<void> = {
   id: 'jupyterlab_markdown_syntax_rendering_fix:plugin',
   description:
-    'Jupyterlab extension to fix a common issue with Markdown renderer where some race condition causes for the fenced code block to not have proper syntax highlighting',
+    'Restore syntax highlighting in rendered Markdown code blocks by mounting the CodeMirror highlight StyleModule at startup, so token colours apply even when no editor is open.',
   autoStart: true,
-  requires: [IEditorLanguageRegistry],
-  activate: (app: JupyterFrontEnd, languages: IEditorLanguageRegistry) => {
+  activate: (): void => {
     console.log(
       'JupyterLab extension jupyterlab_markdown_syntax_rendering_fix is activated!'
     );
 
-    const scan = (root: ParentNode): void => {
-      for (const code of collectPlainBlocks(root)) {
-        rehighlight(code, languages).catch(error => {
-          console.warn(
-            '[jupyterlab_markdown_syntax_rendering_fix] unexpected error while re-highlighting',
-            error
-          );
-        });
-      }
-    };
-
-    const observer = new MutationObserver(mutations => {
-      for (const mutation of mutations) {
-        mutation.addedNodes.forEach(node => {
-          if (node.nodeType !== Node.ELEMENT_NODE) {
-            return;
-          }
-          const element = node as HTMLElement;
-          // Skip pure observer churn: CodeMirror editors mutate on every
-          // keystroke and never hold rendered markdown, and the token spans this
-          // extension itself writes land under an already-processed code block.
-          if (element.closest('.cm-editor, code[data-msrf]')) {
-            return;
-          }
-          scan(element);
-        });
-      }
-    });
-
-    // Observe the application shell rather than document.body: rendered markdown
-    // lives in the shell (notebook cells, markdown preview). Markdown rendered in
-    // body-level overlays (completer / hover docstrings) is intentionally not
-    // covered - a deliberate tradeoff to avoid observing the high-churn overlay
-    // layer; such code blocks recover on the next in-shell render or a reload.
-    const root = app.shell.node;
-    observer.observe(root, { childList: true, subtree: true });
-
-    // Recover any markdown already rendered before this extension activated.
-    scan(root);
+    // Rendered Markdown code blocks receive CodeMirror highlight token classes
+    // (e.g. ͼs), but the StyleModule that gives those classes their colours is
+    // only mounted when a CodeMirror EditorView is instantiated. With only
+    // Markdown previews open, no editor exists, so the spans inherit the plain
+    // code colour and look unhighlighted. Mounting the rules once - the same
+    // effect as opening the editor - colours every preview, and the colours
+    // track the active theme through --jp-mirror-editor-*-color variables.
+    injectHighlightRules(jupyterHighlightStyle.module?.getRules() ?? '');
   }
 };