@mui/internal-docs-infra 0.11.1-canary.9 → 0.11.1

package/cli/loadNextConfig.d.mts

@@ -10,6 +10,14 @@ export interface DemoClientRequirement {
   /** Import specifier passed verbatim into the generated `client.ts`. */
   requireClient: string;
 }
+export interface DemoPageRequirement {
+  /**
+   * Either a Turbopack-style glob pattern (e.g. `./app/**\/demos/*\/index.ts`)
+   * or a webpack-style RegExp used as the rule's `test`. Globs are extracted
+   * from `turbopack.rules`; RegExps are extracted from `webpack` rules.
+   */
+  pattern: string | RegExp;
+}
 export type ExtractedNextConfigOptions = {
   ordering?: OrderingConfig;
   descriptionReplacements?: DescriptionReplacement[];
@@ -17,5 +25,22 @@ export type ExtractedNextConfigOptions = {
   socketDir?: string;
   /** Demo index patterns that opted into automatic `client.ts` generation. */
   demoClientRequirements?: DemoClientRequirement[];
+  /** Demo index patterns that opted into automatic `page.tsx` generation. */
+  demoPageRequirements?: DemoPageRequirement[];
 };
+/**
+ * Walks Turbopack rules to collect demo patterns that opted into automatic
+ * `page.tsx` generation via the `requirePage` option.
+ *
+ * Exported for tests.
+ */
+export declare function extractDemoPageRequirementsFromTurbopack(config: any): DemoPageRequirement[];
+/**
+ * Walks webpack rules to collect demo `test` regexes that opted into automatic
+ * `page.tsx` generation via the `requirePage` option. Mirrors the Turbopack
+ * extractor but uses the rule's RegExp `test` as the pattern.
+ *
+ * Exported for tests.
+ */
+export declare function extractDemoPageRequirementsFromWebpackResult(result: any): DemoPageRequirement[];
 export declare function extractDocsInfraOptionsFromNextConfig(dir: string): Promise<ExtractedNextConfigOptions>;

package/cli/loadNextConfig.mjs

@@ -227,6 +227,61 @@ function extractDemoClientRequirementsFromWebpackResult(result) {
   }
   return requirements;
 }
+
+/**
+ * Walks Turbopack rules to collect demo patterns that opted into automatic
+ * `page.tsx` generation via the `requirePage` option.
+ *
+ * Exported for tests.
+ */
+export function extractDemoPageRequirementsFromTurbopack(config) {
+  const rules = config?.turbopack?.rules;
+  if (!rules || typeof rules !== 'object') {
+    return [];
+  }
+  const requirements = [];
+  for (const [pattern, rule] of Object.entries(rules)) {
+    const loaders = rule?.loaders;
+    if (!Array.isArray(loaders)) {
+      continue;
+    }
+    for (const loader of loaders) {
+      if (loader?.loader === CODE_HIGHLIGHTER_LOADER && loader?.options?.requirePage === true) {
+        requirements.push({
+          pattern
+        });
+        break;
+      }
+    }
+  }
+  return requirements;
+}
+
+/**
+ * Walks webpack rules to collect demo `test` regexes that opted into automatic
+ * `page.tsx` generation via the `requirePage` option. Mirrors the Turbopack
+ * extractor but uses the rule's RegExp `test` as the pattern.
+ *
+ * Exported for tests.
+ */
+export function extractDemoPageRequirementsFromWebpackResult(result) {
+  const requirements = [];
+  for (const rule of result?.module?.rules ?? []) {
+    if (!(rule?.test instanceof RegExp)) {
+      continue;
+    }
+    const useEntries = Array.isArray(rule.use) ? rule.use : [];
+    for (const loader of useEntries) {
+      if (loader?.loader === CODE_HIGHLIGHTER_LOADER && loader?.options?.requirePage === true) {
+        requirements.push({
+          pattern: rule.test
+        });
+        break;
+      }
+    }
+  }
+  return requirements;
+}
 export async function extractDocsInfraOptionsFromNextConfig(dir) {
   const configPath = await findNextConfig(dir);
   if (!configPath) {
@@ -260,12 +315,16 @@ export async function extractDocsInfraOptionsFromNextConfig(dir) {
   const turbopackDemoClientRequirements = extractDemoClientRequirementsFromTurbopack(config);
   const webpackDemoClientRequirements = webpackResult ? extractDemoClientRequirementsFromWebpackResult(webpackResult) : [];
   const demoClientRequirements = [...new Map([...turbopackDemoClientRequirements, ...webpackDemoClientRequirements].map(requirement => [`${typeof requirement.pattern === 'string' ? requirement.pattern : requirement.pattern.toString()}::${requirement.requireClient}`, requirement])).values()];
+  const turbopackDemoPageRequirements = extractDemoPageRequirementsFromTurbopack(config);
+  const webpackDemoPageRequirements = webpackResult ? extractDemoPageRequirementsFromWebpackResult(webpackResult) : [];
+  const demoPageRequirements = [...new Map([...turbopackDemoPageRequirements, ...webpackDemoPageRequirements].map(requirement => [typeof requirement.pattern === 'string' ? requirement.pattern : requirement.pattern.toString(), requirement])).values()];
   return {
     ordering: turbopack.ordering ?? webpack.ordering,
     descriptionReplacements: turbopack.descriptionReplacements ?? webpack.descriptionReplacements,
     useVisibleDescription: turbopack.useVisibleDescription ?? webpack.useVisibleDescription,
     socketDir: turbopack.socketDir ?? webpack.socketDir,
-    demoClientRequirements: demoClientRequirements.length > 0 ? demoClientRequirements : undefined
+    demoClientRequirements: demoClientRequirements.length > 0 ? demoClientRequirements : undefined,
+    demoPageRequirements: demoPageRequirements.length > 0 ? demoPageRequirements : undefined
   };
 }
 async function findNextConfig(dir) {

package/cli/runBrowser.mjs

@@ -104,7 +104,7 @@ async function handler(argv) {
       const xauthority = process.env.XAUTHORITY || `${process.env.HOME}/.Xauthority`;
       containerArgs.push('-e', 'XAUTHORITY=/tmp/.Xauthority', '-v', `${xauthority}:/tmp/.Xauthority:ro`);
     }
-    containerArgs.push(image, 'npx', '--yes', 'playwright', 'run-server', '--port', String(port), '--host', '0.0.0.0');
+    containerArgs.push(image, 'npx', '--yes', `playwright@${argv['playwright-version']}`, 'run-server', '--port', String(port), '--host', '0.0.0.0');
     console.log(`Starting Playwright server on port ${port}…`);
     await engine(...containerArgs);
 

package/cli/runValidate.mjs

@@ -12,6 +12,7 @@ import { createPerformanceLogger, logPerformance, nameMark, performanceMeasure }
 import { terminateWorkerManager } from "../pipeline/loadServerTypesMeta/workerManager.mjs";
 import { extractDocsInfraOptionsFromNextConfig } from "./loadNextConfig.mjs";
 import { ensureDemoClients } from "./ensureDemoClients.mjs";
+import { ensureDemoPages } from "./ensureDemoPages.mjs";
 const completeMessage = message => `✓ ${chalk.green(message)}`;
 const functionName = 'Run Validate';
 
@@ -88,7 +89,8 @@ const runValidate = {
       descriptionReplacements,
       useVisibleDescription = false,
       socketDir: configSocketDir,
-      demoClientRequirements = []
+      demoClientRequirements = [],
+      demoPageRequirements = []
     } = await extractDocsInfraOptionsFromNextConfig(cwd);
     const socketDir = configSocketDir ? path.resolve(cwd, configSocketDir) : undefined;
 
@@ -181,7 +183,9 @@ const runValidate = {
     let indexesMark = currentMark;
     let typesMark = currentMark;
     let clientsMark = currentMark;
+    let pagesMark = currentMark;
     let ranClients = false;
+    let ranPages = false;
     try {
       // === Validate page.mdx index files ===
       if (runIndexes) {
@@ -363,6 +367,37 @@ const runValidate = {
         }, [functionName], true);
         currentMark = clientsMark;
       }
+
+      // === Ensure demo page.tsx files for patterns that opted in ===
+      if (runIndexes && demoPageRequirements.length > 0) {
+        ranPages = true;
+        const demoPageResult = await ensureDemoPages({
+          baseDir: cwd,
+          requirements: demoPageRequirements
+        });
+        const patternCount = demoPageRequirements.length;
+        console.log(chalk.cyan(`\nEnsured demo page.tsx wiring for ${demoPageResult.demoCount} demo${demoPageResult.demoCount === 1 ? '' : 's'} across ${patternCount} pattern${patternCount === 1 ? '' : 's'}`));
+        for (const {
+          filePath,
+          message
+        } of demoPageResult.errors) {
+          console.error(chalk.red(`  ✗ ${filePath}: ${message}`));
+          hasErrors = true;
+        }
+        if (demoPageResult.updatedFiles.length > 0) {
+          console.log(chalk.yellow('\nCreated demo page files:'));
+          for (const relativePath of demoPageResult.updatedFiles) {
+            console.log(chalk.gray(`  ${relativePath}`));
+            updatedFilePaths.push(relativePath);
+          }
+          totalUpdatedFiles += demoPageResult.updatedFiles.length;
+        }
+        pagesMark = performanceMeasure(currentMark, {
+          mark: 'Validated Demo Pages',
+          measure: 'Validating Demo Pages'
+        }, [functionName], true);
+        currentMark = pagesMark;
+      }
     } finally {
       // Terminate worker pool
       await Promise.all(workers.map(w => w.terminate()));
@@ -401,6 +436,14 @@ const runValidate = {
       const clientsDuration = performance.measure(nameMark(functionName, 'Demo Clients Duration', []), typesMark, clientsMark).duration / 1000;
       timingParts.push(`clients: ${clientsDuration.toFixed(2)}s`);
     }
+    if (ranPages) {
+      // Pages run after clients, but clients are optional (requireDemoPage and
+      // requireDemoClient are independent). When clients didn't run, clientsMark
+      // is still the start mark, so measure from typesMark instead — mirroring how
+      // the types breakdown falls back to startMark when indexes didn't run.
+      const pagesDuration = performance.measure(nameMark(functionName, 'Demo Pages Duration', []), ranClients ? clientsMark : typesMark, pagesMark).duration / 1000;
+      timingParts.push(`pages: ${pagesDuration.toFixed(2)}s`);
+    }
     const timingBreakdown = timingParts.length > 0 ? ` [${timingParts.join(', ')}]` : '';
     console.log(completeMessage(`${totalUpdatedFiles} files updated in ${totalDuration.toFixed(2)}s${timingBreakdown}`));
     if (hasErrors) {

package/package.json

@@ -1,9 +1,10 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.11.1-canary.9",
+  "version": "0.11.1",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
+  "sideEffects": false,
   "keywords": [
     "react",
     "react-component",
@@ -22,7 +23,6 @@
   "homepage": "https://github.com/mui/mui-public/tree/master/packages/docs-infra",
   "dependencies": {
     "@babel/runtime": "^7.29.2",
-    "@babel/standalone": "^7.29.4",
     "@orama/orama": "^3.1.18",
     "@orama/plugin-qps": "^3.1.18",
     "@orama/stemmers": "^3.1.18",
@@ -46,6 +46,7 @@
     "remark-parse": "^11.0.0",
     "remark-stringify": "^11.0.0",
     "remark-typography": "^0.7.3",
+    "sucrase": "^3.35.1",
     "typescript-api-extractor": "1.0.0-beta.3",
     "uint8-to-base64": "^0.2.1",
     "unified": "^11.0.5",
@@ -83,6 +84,16 @@
   "type": "commonjs",
   "exports": {
     "./package.json": "./package.json",
+    "./abstractCreateStream": {
+      "import": {
+        "types": "./abstractCreateStream/index.d.mts",
+        "default": "./abstractCreateStream/index.mjs"
+      },
+      "default": {
+        "types": "./abstractCreateStream/index.d.mts",
+        "default": "./abstractCreateStream/index.mjs"
+      }
+    },
     "./abstractCreateDemo": {
       "import": {
         "types": "./abstractCreateDemo/index.d.mts",
@@ -113,6 +124,26 @@
         "default": "./abstractCreateTypes/index.mjs"
       }
     },
+    "./cli": {
+      "import": {
+        "types": "./cli/index.d.mts",
+        "default": "./cli/index.mjs"
+      },
+      "default": {
+        "types": "./cli/index.d.mts",
+        "default": "./cli/index.mjs"
+      }
+    },
+    "./ChunkProvider": {
+      "import": {
+        "types": "./ChunkProvider/index.d.mts",
+        "default": "./ChunkProvider/index.mjs"
+      },
+      "default": {
+        "types": "./ChunkProvider/index.d.mts",
+        "default": "./ChunkProvider/index.mjs"
+      }
+    },
     "./CodeControllerContext": {
       "import": {
         "types": "./CodeControllerContext/index.d.mts",
@@ -173,6 +204,26 @@
         "default": "./CodeProvider/index.mjs"
       }
     },
+    "./CoordinatedLazy": {
+      "import": {
+        "types": "./CoordinatedLazy/index.d.mts",
+        "default": "./CoordinatedLazy/index.mjs"
+      },
+      "default": {
+        "types": "./CoordinatedLazy/index.d.mts",
+        "default": "./CoordinatedLazy/index.mjs"
+      }
+    },
+    "./CoordinatedLazy/types": {
+      "import": {
+        "types": "./CoordinatedLazy/types.d.mts",
+        "default": "./CoordinatedLazy/types.mjs"
+      },
+      "default": {
+        "types": "./CoordinatedLazy/types.d.mts",
+        "default": "./CoordinatedLazy/types.mjs"
+      }
+    },
     "./createDemoData": {
       "import": {
         "types": "./createDemoData/index.d.mts",
@@ -213,6 +264,26 @@
         "default": "./createSitemap/types.mjs"
       }
     },
+    "./useStream": {
+      "import": {
+        "types": "./useStream/index.d.mts",
+        "default": "./useStream/index.mjs"
+      },
+      "default": {
+        "types": "./useStream/index.d.mts",
+        "default": "./useStream/index.mjs"
+      }
+    },
+    "./useStream/types": {
+      "import": {
+        "types": "./useStream/types.d.mts",
+        "default": "./useStream/types.mjs"
+      },
+      "default": {
+        "types": "./useStream/types.d.mts",
+        "default": "./useStream/types.mjs"
+      }
+    },
     "./useCode": {
       "import": {
         "types": "./useCode/index.d.mts",
@@ -233,6 +304,16 @@
         "default": "./useCodeWindow/index.mjs"
       }
     },
+    "./useCoordinated": {
+      "import": {
+        "types": "./useCoordinated/index.d.mts",
+        "default": "./useCoordinated/index.mjs"
+      },
+      "default": {
+        "types": "./useCoordinated/index.d.mts",
+        "default": "./useCoordinated/index.mjs"
+      }
+    },
     "./useCopier": {
       "import": {
         "types": "./useCopier/index.d.mts",
@@ -686,6 +767,5 @@
   },
   "bin": {
     "docs-infra": "./cli/index.mjs"
-  },
-  "gitSha": "ec55950e5d74caba22afb552b951704f6c5761b8"
+  }
 }

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasis.mjs

@@ -1354,6 +1354,34 @@ export function createEnhanceCodeEmphasis(options = {}) {
       }
     }
 
+    // Helper: record the focused-window size (lines visible when collapsed)
+    // alongside `totalLines`. Mirrors the visibility rule in `<Pre>` /
+    // `hasCollapseInFocus`: frame types `'highlighted' | 'focus' |
+    // 'padding-top' | 'padding-bottom'` make up the focused window.
+    //
+    // When `oversizedFocus: 'hide'` suppressed the focus window, no focused
+    // frames exist (`focusedLines === 0`) yet there is hidden content to
+    // expand into. Force `collapsible` so the block collapses to nothing
+    // rather than reading as a non-collapsible (always-expanded) block.
+    function recordFocusedLines(frameRanges) {
+      let focusedLines = 0;
+      for (const range of frameRanges) {
+        if (range.type === 'highlighted' || range.type === 'focus' || range.type === 'padding-top' || range.type === 'padding-bottom') {
+          focusedLines += range.endLine - range.startLine + 1;
+        }
+      }
+      root.data = {
+        ...root.data,
+        focusedLines
+      };
+      if (options.oversizedFocus === 'hide' && focusedLines === 0 && frameRanges.length > 0) {
+        root.data = {
+          ...root.data,
+          collapsible: true
+        };
+      }
+    }
+
     // Step 1: Parse directives from comments (no tree traversal)
     const directives = comments && Object.keys(comments).length > 0 ? parseEmphasisDirectives(comments) : [];
     const effectiveOptions = options;
@@ -1371,6 +1399,7 @@ export function createEnhanceCodeEmphasis(options = {}) {
       const frameRanges = calculateFrameRanges(new Map(), totalLines, effectiveOptions, normalFrameMaxSize);
       restructureFrames(root, frameRanges, new Map());
       markCollapsible(frameRanges);
+      recordFocusedLines(frameRanges);
       return root;
     }
 
@@ -1403,6 +1432,7 @@ export function createEnhanceCodeEmphasis(options = {}) {
     // Step 7: Restructure frames (flat iteration, not deep recursive traversal)
     restructureFrames(root, frameRanges, regionIndentLevels);
     markCollapsible(frameRanges);
+    recordFocusedLines(frameRanges);
 
     // Step 8: Reconcile line-level data-hl with frame types and promote descriptions
     reconcileLineAndFrameEmphasis(root, emphasizedLines);

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasisLazy.d.mts

@@ -0,0 +1,17 @@
+import type { SourceEnhancer } from "../../CodeHighlighter/types.mjs";
+/**
+ * Warms the emphasis-enhancer chunk so the next enhancement runs synchronously
+ * (no flash during live-edit re-enhancement). Optional — the wrapper loads on
+ * first use anyway; this is a head start, e.g. when a block becomes editable.
+ */
+export declare function preloadCodeEmphasis(): Promise<void>;
+/** Clears the module cache. Intended for tests exercising the cold path. */
+export declare function resetCodeEmphasisCache(): void;
+/**
+ * Defers the `enhanceCodeEmphasis` chunk until a block actually enhances
+ * (client highlight or live edit). Runs synchronously once the chunk is warm so
+ * live-edit re-enhancement does not flash; returns a promise on the first cold
+ * call (the existing async-enhancer path handles it). Carries the same
+ * `enhancerName` so precomputed HAST skips it without loading anything.
+ */
+export declare const enhanceCodeEmphasisLazy: SourceEnhancer;

package/pipeline/enhanceCodeEmphasis/enhanceCodeEmphasisLazy.mjs

@@ -0,0 +1,52 @@
+// Lazy form of `enhanceCodeEmphasis`. The real enhancer is ~13 KB gzip (frame
+// range / indent logic); this wrapper keeps it out of the initial bundle and
+// dynamic-imports it only when a block actually enhances client-side. A
+// precomputed block's HAST already carries the emphasis (recorded under the
+// same `enhancerName`), so `shouldSkipEnhancer` skips this wrapper without ever
+// importing the chunk. `CodeProviderLazy` uses this; the eager `CodeProvider`
+// uses the bundled `enhanceCodeEmphasis` directly so its zero-fetch invariant
+// holds.
+//
+// Must stay light: only types are statically imported; the heavy module is
+// reached exclusively through the dynamic `import()` below.
+
+// Stable name — MUST match `enhanceCodeEmphasis.enhancerName` so a precomputed
+// HAST that recorded the eager enhancer is correctly skipped by this wrapper
+// (and vice versa). Hardcoded rather than imported to avoid pulling the chunk.
+const ENHANCE_CODE_EMPHASIS_NAME = 'enhanceCodeEmphasis';
+let cached;
+async function load() {
+  if (!cached) {
+    cached = (await import("./enhanceCodeEmphasis.mjs")).enhanceCodeEmphasis;
+  }
+  return cached;
+}
+
+/**
+ * Warms the emphasis-enhancer chunk so the next enhancement runs synchronously
+ * (no flash during live-edit re-enhancement). Optional — the wrapper loads on
+ * first use anyway; this is a head start, e.g. when a block becomes editable.
+ */
+export async function preloadCodeEmphasis() {
+  await load();
+}
+
+/** Clears the module cache. Intended for tests exercising the cold path. */
+export function resetCodeEmphasisCache() {
+  cached = undefined;
+}
+
+/**
+ * Defers the `enhanceCodeEmphasis` chunk until a block actually enhances
+ * (client highlight or live edit). Runs synchronously once the chunk is warm so
+ * live-edit re-enhancement does not flash; returns a promise on the first cold
+ * call (the existing async-enhancer path handles it). Carries the same
+ * `enhancerName` so precomputed HAST skips it without loading anything.
+ */
+export const enhanceCodeEmphasisLazy = (root, comments, fileName) => {
+  if (cached) {
+    return cached(root, comments, fileName);
+  }
+  return load().then(enhance => enhance(root, comments, fileName));
+};
+enhanceCodeEmphasisLazy.enhancerName = ENHANCE_CODE_EMPHASIS_NAME;

package/pipeline/hastUtils/frameFallbackFromSpans.d.mts

@@ -0,0 +1,18 @@
+import type { ElementContent } from 'hast';
+/**
+ * Derive the lightweight per-frame fallback nodes from a frame's child spans.
+ *
+ * Runs {@link stripHighlightingSpans} over the frame's children — unwrapping
+ * syntax-highlight spans while preserving `.collapse` placeholders and merging
+ * adjacent text — and returns the resulting nodes. This is the canonical way to
+ * produce a frame's `data.fallback` from its live hast: a frame with no collapse
+ * collapses to a single text node (matching `addLineGutters`), while a collapsed
+ * frame keeps its placeholder so the fallback render's height stays in sync with
+ * the highlighted render.
+ *
+ * Shared by the renderer (`Pre`, which derives this lazily for an
+ * un-highlighted frame) and `applyCodeTransform` (which regenerates it for a
+ * frame a transform rewrote), so the precomputed and lazy fallbacks are
+ * byte-identical.
+ */
+export declare function frameFallbackFromSpans(spans: ElementContent[]): ElementContent[];

package/pipeline/hastUtils/frameFallbackFromSpans.mjs

@@ -0,0 +1,24 @@
+import { stripHighlightingSpans } from "./stripHighlightingSpans.mjs";
+
+/**
+ * Derive the lightweight per-frame fallback nodes from a frame's child spans.
+ *
+ * Runs {@link stripHighlightingSpans} over the frame's children — unwrapping
+ * syntax-highlight spans while preserving `.collapse` placeholders and merging
+ * adjacent text — and returns the resulting nodes. This is the canonical way to
+ * produce a frame's `data.fallback` from its live hast: a frame with no collapse
+ * collapses to a single text node (matching `addLineGutters`), while a collapsed
+ * frame keeps its placeholder so the fallback render's height stays in sync with
+ * the highlighted render.
+ *
+ * Shared by the renderer (`Pre`, which derives this lazily for an
+ * un-highlighted frame) and `applyCodeTransform` (which regenerates it for a
+ * frame a transform rewrote), so the precomputed and lazy fallbacks are
+ * byte-identical.
+ */
+export function frameFallbackFromSpans(spans) {
+  return stripHighlightingSpans({
+    type: 'root',
+    children: spans
+  }).children;
+}

package/pipeline/hastUtils/hast.d.mts

@@ -0,0 +1,27 @@
+// Module augmentation for the `hast` type definitions. Lets us attach
+// strongly-typed metadata to nodes via the user-extensible `Data` interfaces
+// (see https://github.com/syntax-tree/hast#types) without scattering `as any`
+// casts at every read/write site.
+
+import type { ElementContent } from 'hast';
+declare module 'hast' {
+  interface ElementData {
+    /**
+     * Precomputed lightweight hast used as the pre-hydration / SSR fallback
+     * for this element. Set by `addLineGutters` on each frame span (single
+     * `{ type: 'text' }` node carrying the frame's raw source text) so the
+     * renderer can skip running `stripHighlightingSpans` per frame.
+     */
+    fallback?: ElementContent[];
+  }
+  interface RootData {
+    /** Total number of lines in the source represented by this tree. */
+    totalLines?: number;
+    /** Lines-per-frame size used when splitting the tree into frame spans. */
+    frameSize?: number;
+  }
+}
+
+// Required to make this file a module so the `declare module` augmentation
+// is picked up. The empty export keeps the runtime emit shape unchanged.
+export {};

package/pipeline/hastUtils/hastCompression.d.mts

@@ -1,3 +1,5 @@
 export { HAST_DICTIONARY, MAX_DICTIONARY_SIZE, CHECKSUM_BYTES, buildDictionary, computeDictionaryChecksum, HastDictionaryMismatchError } from "./hastDictionary.mjs";
 export { compressHast, compressHastAsync } from "./hastCompress.mjs";
-export { decompressHast, decompressHastAsync } from "./hastDecompress.mjs";
+export { decompressHast, decompressHastAsync } from "./hastDecompress.mjs";
+export { compressHast as compressString, compressHastAsync as compressStringAsync } from "./hastCompress.mjs";
+export { decompressHast as decompressString, decompressHastAsync as decompressStringAsync } from "./hastDecompress.mjs";

package/pipeline/hastUtils/hastCompression.mjs

@@ -1,3 +1,11 @@
 export { HAST_DICTIONARY, MAX_DICTIONARY_SIZE, CHECKSUM_BYTES, buildDictionary, computeDictionaryChecksum, HastDictionaryMismatchError } from "./hastDictionary.mjs";
 export { compressHast, compressHastAsync } from "./hastCompress.mjs";
-export { decompressHast, decompressHastAsync } from "./hastDecompress.mjs";
+export { decompressHast, decompressHastAsync } from "./hastDecompress.mjs";
+
+// `compressHast` / `decompressHast` are string-in/string-out DEFLATE with an
+// optional preset dictionary — generic beyond HAST. These aliases name that
+// generic use (e.g. the Coordinated Streaming pattern passing a compressed
+// payload from a fallback to the full content, decoded against a hoisted
+// dictionary).
+export { compressHast as compressString, compressHastAsync as compressStringAsync } from "./hastCompress.mjs";
+export { decompressHast as decompressString, decompressHastAsync as decompressStringAsync } from "./hastDecompress.mjs";

package/pipeline/hastUtils/hastDecompress.mjs

@@ -19,13 +19,19 @@ export function decompressHast(base64, textContent) {
   const dictionary = buildDictionary(textContent);
   if (textContent != null) {
     verifyChecksum(raw, dictionary);
-    return strFromU8(inflateSync(raw.subarray(CHECKSUM_BYTES), {
+  }
+  try {
+    const deflated = textContent != null ? raw.subarray(CHECKSUM_BYTES) : raw;
+    return strFromU8(inflateSync(deflated, {
       dictionary
     }));
+  } catch (error) {
+    // A raw inflate failure (e.g. fflate's "unexpected EOF") is almost always a
+    // payload that was compressed with a fallback dictionary being decoded
+    // without one — the checksum prefix is then read as deflate data. Surface
+    // that cause instead of the cryptic `{code:0}` the raw error stringifies to.
+    throw new Error(`Failed to decompress payload${textContent == null ? ' — if it was compressed with a fallback dictionary, that dictionary must be provided' : ''}: ${error instanceof Error ? error.message : String(error)}`);
   }
-  return strFromU8(inflateSync(raw, {
-    dictionary
-  }));
 }
 
 /**

package/pipeline/hastUtils/hastDictionary.mjs

@@ -24,6 +24,15 @@ export const CHECKSUM_BYTES = 4;
  * small — currently ~3 KB uncompressed.
  */
 export const HAST_DICTIONARY = strToU8([
+// ── New entries go HERE, at the START (prepend only) ──
+// DEFLATE back-references reach into the dictionary from its END, so a payload
+// compressed with an earlier version of this dictionary only decodes correctly
+// if the existing tail stays byte-identical. Prepending preserves that tail;
+// appending or inserting in the middle silently corrupts older payloads (the
+// text path also catches this loudly via the dictionary checksum). Always add
+// new strings to the top of this list — never the middle or end. See the
+// `dictionary mutation tolerance` tests in `hastCompression.test.ts`.
+'collapseToEmpty', 'showCollapsedFocus', 'initialExpanded', 'initialCollapsed',
 // JSON structural patterns (most frequent first)
 '{"type":"element","tagName":"span","properties":{"className":["frame"],"dataFrameType":"', '{"type":"element","tagName":"span","properties":{"className":["line"],"dataLn":', '{"type":"element","tagName":"span","properties":{"className":["', '{"type":"element","tagName":"a","properties":{"href":"', '{"type":"text","value":"', '"children":[', '"properties":{}', '"tagName":"code"', '"tagName":"pre"', '"type":"root"', '"type":"element"', '"type":"text"',
 // Starry Night / Pretty Lights class names (full set)

package/pipeline/hastUtils/hastUtils.d.mts

@@ -1,19 +1,20 @@
 import type * as React from 'react';
 import type { Nodes as HastNodes } from 'hast';
 import type { Components } from 'hast-util-to-jsx-runtime';
+import { type FallbackNode } from "./fallbackFormat.mjs";
 export declare function hastToJsx(hast: HastNodes, components?: Partial<Components>): React.ReactNode;
 export declare function hastOrJsonToJsx(hastOrJson: HastNodes | {
   hastJson: string;
 } | {
   hastCompressed: string;
-}, components?: Partial<Components>): React.ReactNode;
+}, components?: Partial<Components>, fallback?: FallbackNode[]): React.ReactNode;
 export declare function stringOrHastToString(source: string | HastNodes | {
   hastJson: string;
 } | {
   hastCompressed: string;
-}): string;
+}, fallback?: FallbackNode[]): string;
 export declare function stringOrHastToJsx(source: string | HastNodes | {
   hastJson: string;
 } | {
   hastCompressed: string;
-}, highlighted?: boolean, components?: Partial<Components>): React.ReactNode;
+}, highlighted?: boolean, components?: Partial<Components>, fallback?: FallbackNode[]): React.ReactNode;