@plannotator/ui 0.32.0 → 0.34.0

package/utils/math-default-loader.ts

@@ -0,0 +1,24 @@
+/**
+ * The default math renderer loader: KaTeX's JS only, fetched lazily.
+ *
+ * This module is the ONLY place in `@plannotator/ui` that names `katex` at
+ * runtime (`./math-eager` names it too, but a host chooses to import that).
+ * `./math` calls `loadDefaultMathRenderer` only when no host loader is
+ * registered (`setMathRendererLoader` / `configurePlannotatorUI({
+ * mathRendererLoader })`), so a host that registers one never runs the
+ * `import('katex')` below and never requests the chunk it produces.
+ *
+ * Keeping the import in its own module is what lets a bundler drop the chunk
+ * entirely: chunk emission is static, so a host that registers a loader and
+ * wants no KaTeX chunk from the package at all points this module at a stub
+ * (see HANDOFF.md "Lazy renderers and eager entries", the alias recipe). The
+ * stylesheet is deliberately NOT imported here; CSS loading stays the host's
+ * job (HANDOFF.md "Math rendering"), and a host that already serves
+ * `katex.min.css` would otherwise load it twice.
+ */
+
+import type { MathRenderer } from './math';
+
+export function loadDefaultMathRenderer(): Promise<MathRenderer> {
+  return import('katex').then((m) => m.default);
+}

package/utils/math.ts

@@ -11,12 +11,16 @@
  * call `loadMathRenderer()`, and re-render typeset once it resolves.
  *
  * This module deliberately has NO runtime import of `katex`: the only place
- * the dependency is named is the default loader's `import('katex')`, which a
- * chunking bundler turns into a lazy chunk and Plannotator's single-file
- * builds inline (the eager entry keeps it in the entry either way).
+ * the dependency is named is `./math-default-loader`'s `import('katex')`,
+ * which a chunking bundler turns into a lazy chunk and Plannotator's
+ * single-file builds inline (the eager entry keeps it in the entry either
+ * way). That default is called only while no host loader is registered, and
+ * it lives in its own module so a host that registers a loader can alias it
+ * away and drop the chunk (see HANDOFF.md "Lazy renderers and eager entries").
  */
 
 import type { KatexOptions } from 'katex';
+import { loadDefaultMathRenderer } from './math-default-loader';
 
 /** The subset of KaTeX's API the renderer needs. `katex` itself satisfies it. */
 export interface MathRenderer {
@@ -25,13 +29,6 @@ export interface MathRenderer {
 
 export type MathRendererLoader = () => Promise<MathRenderer>;
 
-/**
- * Default loader: KaTeX's JS only. The stylesheet is deliberately NOT imported
- * here; CSS loading stays the host's job (see HANDOFF.md "Math rendering"),
- * and a host that already serves `katex.min.css` would otherwise load it twice.
- */
-const defaultMathRendererLoader: MathRendererLoader = () => import('katex').then((m) => m.default);
-
 /**
  * Who filled the slot: the eager entry (`./math-eager`), the lazy loader, or a
  * host calling `setMathRenderer` directly. Diagnostic for a host chasing a TeX
@@ -43,8 +40,20 @@ export type MathRendererSource = 'plannotator-math-eager' | 'loader' | 'host';
 
 let renderer: MathRenderer | null = null;
 let rendererSource: MathRendererSource | null = null;
-let loader: MathRendererLoader = defaultMathRendererLoader;
+/**
+ * The host loader, or `null` while none is registered. `null` is the only
+ * state in which `loadMathRenderer()` reaches `loadDefaultMathRenderer` and
+ * its `import('katex')`; a registered loader is never backfilled by the
+ * default, not even after it rejects.
+ */
+let loader: MathRendererLoader | null = null;
 let pending: Promise<MathRenderer> | null = null;
+/**
+ * Bumped by `resetMathRenderer()`. A load in flight across a reset must not
+ * fill the slot when it lands: the reset promised an empty slot, and the next
+ * `loadMathRenderer()` re-invokes the registered loader instead.
+ */
+let resetEpoch = 0;
 const listeners = new Set<() => void>();
 
 function notify(): void {
@@ -81,14 +90,22 @@ export function subscribeMathRenderer(listener: () => void): () => void {
  * Swap the loader `loadMathRenderer()` uses. Host seam
  * (`configurePlannotatorUI({ mathRendererLoader })`): a host may return a
  * module that imports katex AND its stylesheet in one chunk. A load already in
- * flight keeps going; the new loader is used from the next `loadMathRenderer()`
- * call that finds the slot empty.
+ * flight keeps going and still fills the slot when it lands (the component
+ * that started it is waiting on that result and would otherwise never
+ * typeset); the new loader is used from the next `loadMathRenderer()` call
+ * that finds the slot empty. Passing `null` unregisters the host loader and
+ * restores the package default.
  */
-export function setMathRendererLoader(next: MathRendererLoader): void {
+export function setMathRendererLoader(next: MathRendererLoader | null): void {
   loader = next;
   pending = null;
 }
 
+/** The registered host loader, or `null` while the package default applies. */
+export function getMathRendererLoader(): MathRendererLoader | null {
+  return loader;
+}
+
 /**
  * Load and register the renderer. Idempotent: a filled slot resolves at once,
  * a load in flight is shared, and a rejected load is dropped so the next call
@@ -97,9 +114,12 @@ export function setMathRendererLoader(next: MathRendererLoader): void {
 export function loadMathRenderer(): Promise<MathRenderer> {
   if (renderer) return Promise.resolve(renderer);
   if (!pending) {
-    const attempt = loader().then(
+    const epoch = resetEpoch;
+    const attempt = (loader ? loader() : loadDefaultMathRenderer()).then(
       (loaded) => {
-        setMathRenderer(loaded, 'loader');
+        // A reset since this load started wants the slot empty: hand the
+        // result to the caller that awaited it, but do not register it.
+        if (epoch === resetEpoch) setMathRenderer(loaded, 'loader');
         return loaded;
       },
       (err: unknown) => {
@@ -112,12 +132,19 @@ export function loadMathRenderer(): Promise<MathRenderer> {
   return pending;
 }
 
-/** Test hook: clear the slot, the loader override and any pending load. */
+/**
+ * Test hook: empty the slot (renderer and source) and forget any load in
+ * flight, so the next `loadMathRenderer()` invokes the loader afresh and a
+ * stale in-flight result cannot fill the slot after the reset. The registered
+ * loader is KEPT: resetting the renderer is not unregistering the host seam
+ * (a host's `configurePlannotatorUI` runs once, before any reset a test issues
+ * later). To drop the loader too, call `setMathRendererLoader(null)`.
+ */
 export function resetMathRenderer(): void {
   renderer = null;
   rendererSource = null;
-  loader = defaultMathRendererLoader;
   pending = null;
+  resetEpoch += 1;
   notify();
 }
 

package/utils/mermaid-math-slot.ts

@@ -0,0 +1,56 @@
+/**
+ * Mermaid's KaTeX, served from the math renderer slot.
+ *
+ * Mermaid renders `$$...$$` labels through its own `import("katex")`
+ * (`renderKatexUnsanitized` in the runtime; there is no config flag and no
+ * hook for it, and chunk emission is static), so a host that registers a
+ * `mathRendererLoader` and aliases `./math-default-loader` away still gets a
+ * shared `katex-*.js` chunk out of the Mermaid runtime, and a math document
+ * fetches two files: the host's loader chunk plus that shared chunk.
+ *
+ * This module is the alias target that removes it. A host redirects the
+ * `katex` specifier, for importers inside the `mermaid` package ONLY, to
+ * `@plannotator/ui/utils/mermaid-math-slot` (HANDOFF.md "Lazy renderers and
+ * eager entries", item 2). Its default export has the one method Mermaid
+ * calls, `renderToString`, and delegates to whatever renderer fills the slot
+ * in `./math`: the host's loader result, or the eager KaTeX registration.
+ * Mermaid's own options (`throwOnError: true`, `displayMode: true`, the
+ * MathML `output` mode) are passed through untouched, so a KaTeX renderer
+ * produces exactly the markup Mermaid produced from its direct import.
+ *
+ * The slot must be filled by the time Mermaid asks: `MermaidBlock` awaits
+ * `loadMathRenderer()` before rendering a diagram whose source carries a
+ * `$$` label (`hasMermaidMath`), which is a no-op resolve on a filled slot
+ * and the host's loader otherwise. An empty slot here means that load
+ * failed, and the error below surfaces in the block's error panel with the
+ * source, instead of a silently unlabeled node.
+ *
+ * Nothing imports this module by default: Plannotator never aliases, so its
+ * Mermaid keeps its direct KaTeX (inlined by the single-file builds), and
+ * this file must never import `katex` itself, or the redirect would re-create
+ * the chunk it exists to remove (`tests/entry-assets.test.ts` pins that).
+ */
+
+import { getMathRenderer, type MathRenderer } from './math';
+
+/** Mermaid's own test for a math label (`katexRegex` in the runtime). */
+const MERMAID_MATH_REGEX = /\$\$(.*)\$\$/;
+
+/** True when a diagram source carries at least one `$$...$$` label. */
+export function hasMermaidMath(source: string): boolean {
+  return MERMAID_MATH_REGEX.test(source);
+}
+
+/** Thrown when Mermaid asks for KaTeX while the math slot is still empty. */
+export const MERMAID_MATH_SLOT_EMPTY_MESSAGE =
+  'Math label: no math renderer is registered (the mathRendererLoader did not resolve before the diagram rendered)';
+
+const slotRenderer: MathRenderer = {
+  renderToString(tex, options) {
+    const renderer = getMathRenderer();
+    if (!renderer) throw new Error(MERMAID_MATH_SLOT_EMPTY_MESSAGE);
+    return renderer.renderToString(tex, options);
+  },
+};
+
+export default slotRenderer;