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

package/useCode/TransformEngine.mjs

@@ -0,0 +1,208 @@
+// The transform-application runtime, split out of `useCodeUtils` so the heavy
+// `applyCodeTransform` path (which statically pulls `jsondiffpatch`) loads only
+// when a block actually applies a transform. `useTransformManagement` reaches it
+// through the `transformEngineLoader` accessor on `CodeContext` (the eager
+// `CodeProvider` bundles it; `CodeProviderLazy` dynamic-imports it), with a
+// built-in fallback so transforms still work without a provider. The pure,
+// manifest-only transform helpers stay in `useCodeUtils` so read-only / no-transform
+// blocks never pull this chunk.
+
+// Import the transform core (which takes its hast helpers injected) rather than
+// the `applyCodeTransform` wrapper that binds them, so this dynamic engine chunk
+// never statically pulls `decodeHastSource` / `frameFallbackFromSpans` (and
+// their `hastDecompress` dependency). The helpers are threaded in from the
+// always-loaded `useCode` shell, which already has them, so they stay counted
+// there instead of being hoisted into their own chunks.
+import { applyCodeTransformWithComments } from "../pipeline/loadIsomorphicCodeVariant/applyCodeTransformWithComments.mjs";
+
+/**
+ * Function signature of {@link createTransformedFiles}. Used by the
+ * `transformEngineLoader` accessor and `useTransformManagement` so they can
+ * reference the engine without statically importing this (heavy) module.
+ *
+ * `deps` (the decoder + frame-fallback helper) is injected by the caller (the
+ * `useCode` shell already loads them) so this engine chunk doesn't statically
+ * depend on them.
+ */
+
+/**
+ * Pure helper function to apply transform to a source file.
+ *
+ * @param source - The source code to transform
+ * @param fileName - The filename for the source
+ * @param transforms - Available transforms for this source
+ * @param selectedTransform - The transform to apply
+ * @param comments - Optional 1-indexed comment map for the source. Returned
+ *   shifted onto the transformed source's line numbering.
+ * @returns Object with transformed source, name, and shifted comments
+ */
+export function applyTransformToSource(source, fileName, transforms, selectedTransform, deps, comments, fallback) {
+  if (!transforms?.[selectedTransform]) {
+    return {
+      transformedSource: source,
+      transformedName: fileName,
+      transformedComments: comments
+    };
+  }
+  try {
+    const transformData = transforms[selectedTransform];
+
+    // Apply transform — `applyCodeTransform` will look up the delta inside
+    // `source.data.transforms` if `transformData.delta` is absent (manifest
+    // mode after embedding).
+    const result = applyCodeTransformWithComments(source, transforms, selectedTransform, deps, comments, fallback);
+    const transformedName = transformData.fileName || fileName;
+    return {
+      transformedSource: result.source,
+      transformedName,
+      transformedComments: result.comments
+    };
+  } catch (error) {
+    console.error(`Transform failed for ${fileName}:`, error);
+    return {
+      transformedSource: source,
+      transformedName: fileName,
+      transformedComments: comments
+    };
+  }
+}
+
+/**
+ * Pure function to create transformed files from a variant and selected transform.
+ *
+ * @param selectedVariant - The currently selected variant
+ * @param selectedTransform - The transform to apply
+ * @returns Object with transformed files and filename mapping, or undefined if no transform
+ */
+export function createTransformedFiles(selectedVariant, selectedTransform,
+// Hast helpers injected by the caller (the `useCode` shell), so this engine
+// chunk never statically imports them. See the module comment.
+deps,
+// Per-file DEFLATE dictionaries hoisted from a `ContentLoading` component.
+// A file's fallback may live here (hoisted) instead of on the variant
+// (stripped) — applying a transform must decode `hastCompressed`, so resolve
+// from both, preferring the hoisted copy.
+fallbacks) {
+  // Only create transformed files when there's actually a transform selected
+  if (!selectedVariant || !selectedTransform) {
+    return undefined;
+  }
+  const files = [];
+  const filenameMap = {};
+
+  // First, check if any file has a transform manifest entry for the selected
+  // transform. A manifest entry may carry a real embedded delta (`hasDelta: true`)
+  // or be rename-only (`hasDelta: false`) — both cases are "meaningful" here
+  // because either the source changes or the filename does.
+  const variantTransforms = 'transforms' in selectedVariant ? selectedVariant.transforms : undefined;
+  let hasAnyMeaningfulTransform = false;
+
+  // Check main file for the transform key
+  if (selectedVariant.fileName && variantTransforms?.[selectedTransform]) {
+    hasAnyMeaningfulTransform = true;
+  }
+
+  // Check extraFiles for the transform key
+  if (!hasAnyMeaningfulTransform && selectedVariant.extraFiles) {
+    Object.values(selectedVariant.extraFiles).forEach(fileData => {
+      if (fileData && typeof fileData === 'object' && 'transforms' in fileData && fileData.transforms?.[selectedTransform]) {
+        hasAnyMeaningfulTransform = true;
+      }
+    });
+  }
+
+  // If no file has a meaningful transform, return empty result
+  if (!hasAnyMeaningfulTransform) {
+    return {
+      files: [],
+      filenameMap: {}
+    };
+  }
+
+  // Process main file if we have a fileName and source
+  if (selectedVariant.fileName && selectedVariant.source) {
+    const {
+      transformedSource: mainSource,
+      transformedName: mainName,
+      transformedComments: mainComments
+    } = applyTransformToSource(selectedVariant.source, selectedVariant.fileName, variantTransforms, selectedTransform, deps, selectedVariant.comments, (selectedVariant.fileName ? fallbacks?.[selectedVariant.fileName] : undefined) ?? selectedVariant.fallback);
+    const fileName = selectedVariant.fileName;
+    filenameMap[fileName] = mainName;
+    files.push({
+      name: mainName,
+      originalName: fileName,
+      source: mainSource,
+      ...(mainComments && {
+        comments: mainComments
+      })
+    });
+  }
+
+  // Process extra files
+  if (selectedVariant.extraFiles) {
+    Object.entries(selectedVariant.extraFiles).forEach(([extraFileName, fileData]) => {
+      let source;
+      let transforms;
+      let fileComments;
+
+      // Handle different extraFile structures
+      if (typeof fileData === 'string') {
+        source = fileData;
+        transforms = undefined; // Don't inherit variant transforms for simple string files
+      } else if (fileData && typeof fileData === 'object' && 'source' in fileData) {
+        source = fileData.source;
+        transforms = fileData.transforms; // Only use explicit transforms for this file
+        fileComments = fileData.comments;
+      } else {
+        return; // Skip invalid entries
+      }
+
+      // Skip if source is undefined
+      if (!source) {
+        return;
+      }
+
+      // Apply transforms if available, otherwise use original source
+      let transformedSource = source;
+      let transformedName = extraFileName;
+      let transformedComments = fileComments;
+      if (transforms?.[selectedTransform]) {
+        try {
+          const transformData = transforms[selectedTransform];
+          // The presence of an entry in the (manifest or legacy) transforms
+          // record is enough — `applyCodeTransform` will look up the delta
+          // inside `source.data.transforms` if it isn't on the entry.
+          const result = applyCodeTransformWithComments(source, transforms, selectedTransform, deps, fileComments, fallbacks?.[extraFileName] ?? (typeof fileData === 'object' ? fileData.fallback : undefined));
+          transformedSource = result.source;
+          transformedComments = result.comments;
+          transformedName = transformData.fileName || extraFileName;
+        } catch (error) {
+          console.error(`Transform failed for ${extraFileName}:`, error);
+          // Continue with original source if transform fails
+        }
+      }
+
+      // Only update filenameMap and add to files if this doesn't conflict with existing files
+      // If a file already exists with the target name, skip this transformation to preserve original files
+      const existingFile = files.find(f => f.name === transformedName);
+      if (!existingFile) {
+        filenameMap[extraFileName] = transformedName;
+        files.push({
+          name: transformedName,
+          originalName: extraFileName,
+          source: transformedSource,
+          ...(transformedComments && {
+            comments: transformedComments
+          })
+        });
+      } else {
+        // If there's a conflict, skip this file with a warning
+        console.warn(`Transform conflict: ${extraFileName} would transform to ${transformedName} but that name is already taken. Skipping this file.`);
+      }
+    });
+  }
+  return {
+    files,
+    filenameMap
+  };
+}

package/useCode/editingEngineCache.d.mts

@@ -0,0 +1,29 @@
+import type * as EditingEngine from "./EditingEngine.mjs";
+/** The resolved editing-engine module: `createEditableEngine` + source-editing fns. */
+export type EditingEngineModule = typeof EditingEngine;
+/**
+ * Resolves the live-editing engine module. `CodeProvider` supplies one via
+ * context (eager → bundled, resolves instantly; lazy → dynamic `import()`);
+ * `useEditable` / `useSourceEditing` also have the built-in default below so
+ * editing works without a provider.
+ */
+export type EditingEngineLoader = () => Promise<EditingEngineModule>;
+/** Built-in loader, used when no provider supplies an `editingEngineLoader`. */
+export declare const defaultEditingEngineLoader: EditingEngineLoader;
+/** Synchronously reads the cached module, or `undefined` if not yet resolved. */
+export declare function peekEditingEngine(): EditingEngineModule | undefined;
+/**
+ * Resolves the editing-engine module (from the warm cache, else via the loader)
+ * and caches it. Returns the cached value synchronously when warm. Rejects if
+ * the load fails; callers decide whether to surface or swallow that.
+ */
+export declare function loadEditingEngine(loader?: EditingEngineLoader): EditingEngineModule | Promise<EditingEngineModule>;
+/**
+ * Eagerly resolves and caches the editing-engine module so the next editable
+ * block attaches (and the first edit commits) synchronously instead of after a
+ * load round-trip. Fire-and-forget — fails open. Pass the provider's
+ * `editingEngineLoader` to share its page-wide deduplication.
+ */
+export declare function preloadEditingEngine(loader?: EditingEngineLoader): Promise<void>;
+/** Clears the cache so the next resolve loads from scratch. For tests. */
+export declare function resetEditingEngineCache(): void;

package/useCode/editingEngineCache.mjs

@@ -0,0 +1,68 @@
+/** The resolved editing-engine module: `createEditableEngine` + source-editing fns. */
+
+/**
+ * Resolves the live-editing engine module. `CodeProvider` supplies one via
+ * context (eager → bundled, resolves instantly; lazy → dynamic `import()`);
+ * `useEditable` / `useSourceEditing` also have the built-in default below so
+ * editing works without a provider.
+ */
+
+// Set DEBUG=true to log editing-engine load failures (e.g. a chunk-load error
+// after a rotated deploy). Off by default — a failed load fails open (the block
+// stays read-only / the edit no-ops) per convention 9.3.
+const DEBUG = false;
+
+// Module-level cache of the resolved editing-engine module, shared by
+// `useEditable` (reads `createEditableEngine`) and `useSourceEditing` (reads the
+// source-editing fns). Because both gate on the same "is-editable" signal and
+// load the SAME chunk, the first editable block resolves it once and every
+// reader after that — including the first keystroke's source-editing call — sees
+// it warm and runs synchronously.
+let cached;
+
+/** Built-in loader, used when no provider supplies an `editingEngineLoader`. */
+export const defaultEditingEngineLoader = () => import("./EditingEngine.mjs");
+
+/** Synchronously reads the cached module, or `undefined` if not yet resolved. */
+export function peekEditingEngine() {
+  return cached;
+}
+
+/**
+ * Resolves the editing-engine module (from the warm cache, else via the loader)
+ * and caches it. Returns the cached value synchronously when warm. Rejects if
+ * the load fails; callers decide whether to surface or swallow that.
+ */
+export function loadEditingEngine(loader) {
+  if (cached) {
+    return cached;
+  }
+  return (loader ?? defaultEditingEngineLoader)().then(mod => {
+    cached = mod;
+    return mod;
+  });
+}
+
+/**
+ * Eagerly resolves and caches the editing-engine module so the next editable
+ * block attaches (and the first edit commits) synchronously instead of after a
+ * load round-trip. Fire-and-forget — fails open. Pass the provider's
+ * `editingEngineLoader` to share its page-wide deduplication.
+ */
+export async function preloadEditingEngine(loader) {
+  if (cached) {
+    return;
+  }
+  try {
+    await loadEditingEngine(loader);
+  } catch (error) {
+    if (DEBUG) {
+      console.error('[docs-infra] editing engine failed to preload', error);
+    }
+  }
+}
+
+/** Clears the cache so the next resolve loads from scratch. For tests. */
+export function resetEditingEngineCache() {
+  cached = undefined;
+}

package/useCode/sourceLineCounts.d.mts

@@ -0,0 +1,80 @@
+import type { VariantSource, VariantCode, Code } from "../CodeHighlighter/types.mjs";
+import type { FallbackNode } from "../CodeHighlighter/fallbackFormat.mjs";
+export interface SourceLineCounts {
+  totalLines: number;
+  focusedLines: number;
+  collapsible: boolean;
+}
+/**
+ * Extract `{ totalLines, focusedLines }` from any `VariantSource`
+ * shape. Reads precomputed metadata when available (`HastRoot.data`)
+ * and falls back to counting lines for plain string sources. For
+ * string sources, `focusedLines === totalLines` because the
+ * `@focus` enhancer never ran. Results are cached by source identity
+ * for object payloads so subsequent calls are O(1).
+ *
+ * Returns zeroes when the source is missing or malformed.
+ */
+export declare function getSourceLineCounts(source: VariantSource | undefined, fallback?: FallbackNode[]): SourceLineCounts;
+export declare function getVariantFileLineCounts(variant: VariantCode, fileName: string): SourceLineCounts | null;
+/**
+ * Determines whether switching from `fromVariantKey` to `toVariantKey`
+ * would visibly shift layout. The `mode` mirrors the transform
+ * classifier and is configured via `useCode`'s `variantLayoutShift`
+ * option:
+ *
+ *   - `'all'` — sums `totalLines` across every file (main +
+ *     `extraFiles`) in both variants. Layout shift when the totals
+ *     differ. Useful when the rendering surface displays the full
+ *     variant simultaneously.
+ *   - `'selected'` (default) — compares `totalLines` for the
+ *     currently-selected file (`selectedFileName`, falling back to
+ *     the source variant's main file) between the two variants.
+ *     Layout shift when the line counts differ.
+ *   - `'focus'` — like `'selected'` but consults `focusedLines`
+ *     (the size of the visible window when the surrounding code
+ *     block is collapsed) while `expanded === false`. Reverts to
+ *     `'selected'`-style behavior when expanded. Recommended for
+ *     demos that use `@focus`/`@padding` to collapse to a region.
+ *
+ * Returns `true` (layout shift) when:
+ *   - either variant is missing,
+ *   - the selected file is missing from either variant (the file
+ *     list itself changes),
+ *   - the relevant line count differs between the two variants.
+ *
+ * Returns `false` for same-variant swaps and when the line counts
+ * match.
+ */
+export declare function variantHasLayoutShift(effectiveCode: Code, fromVariantKey: string | null, toVariantKey: string | null, opts?: {
+  mode?: 'all' | 'selected' | 'focus';
+  selectedFileName?: string | undefined;
+  expanded?: boolean;
+}): boolean;
+/**
+ * Description of a pair of variants whose same-named file has a
+ * different `focusedLines` count. Returned by
+ * `findVariantFocusedLinesMismatches` so callers can produce
+ * actionable error messages without re-walking the variant tree.
+ */
+export interface VariantFocusedLinesMismatch {
+  fileName: string;
+  variantA: string;
+  variantB: string;
+  focusedLinesA: number;
+  focusedLinesB: number;
+}
+/**
+ * Walk every variant on `effectiveCode` and collect files that share
+ * a name across variants but disagree on `focusedLines`. Used by
+ * `useCode`'s `strictMatchingVariantFocusedLines` option to throw
+ * with a pointer to the offending variants/file so the demo author
+ * can align the `@focus` / `@padding` markers across language
+ * variants and avoid coordinated barriers while collapsed.
+ *
+ * The first variant to declare a given file name is treated as the
+ * baseline; every subsequent variant that disagrees produces a
+ * mismatch entry paired with the baseline. Returns an empty array
+ * when every shared file agrees.
+ */
+export declare function findVariantFocusedLinesMismatches(effectiveCode: Code): VariantFocusedLinesMismatch[];

package/useCode/sourceLineCounts.mjs

@@ -0,0 +1,284 @@
+import { decodeHastSource } from "../pipeline/loadIsomorphicCodeVariant/decodeHastSource.mjs";
+const ZERO_LINE_COUNTS = {
+  totalLines: 0,
+  focusedLines: 0,
+  collapsible: false
+};
+function normalizeLineCounts(totalRaw, focusedRaw, collapsibleRaw) {
+  const totalNum = totalRaw == null ? NaN : Number(totalRaw);
+  const totalLines = Number.isFinite(totalNum) && totalNum >= 0 ? totalNum : 0;
+  const focusedNum = focusedRaw == null ? NaN : Number(focusedRaw);
+  const focusedLines = Number.isFinite(focusedNum) && focusedNum >= 0 ? focusedNum : totalLines;
+  return {
+    totalLines,
+    focusedLines,
+    collapsible: collapsibleRaw === true
+  };
+}
+function readStoredLineCounts(file) {
+  if (file.totalLines === undefined) {
+    return null;
+  }
+  return normalizeLineCounts(file.totalLines, file.focusedLines, file.collapsible);
+}
+
+/**
+ * Cache of `{ totalLines, focusedLines }` keyed on the raw source
+ * payload. Variant sources are typically stable references across
+ * re-renders (they live on the precomputed manifest) so caching by
+ * identity is safe and avoids re-parsing compressed hast on every
+ * layout-shift classification.
+ */
+const sourceLineCountsCache = new WeakMap();
+function readHastLineCounts(root) {
+  if (!root || !root.data) {
+    return ZERO_LINE_COUNTS;
+  }
+  const totalRaw = root.data.totalLines;
+  const focusedRaw = root.data.focusedLines;
+  const collapsibleRaw = root.data.collapsible;
+  return normalizeLineCounts(totalRaw, focusedRaw, collapsibleRaw);
+}
+
+/**
+ * Extract `{ totalLines, focusedLines }` from any `VariantSource`
+ * shape. Reads precomputed metadata when available (`HastRoot.data`)
+ * and falls back to counting lines for plain string sources. For
+ * string sources, `focusedLines === totalLines` because the
+ * `@focus` enhancer never ran. Results are cached by source identity
+ * for object payloads so subsequent calls are O(1).
+ *
+ * Returns zeroes when the source is missing or malformed.
+ */
+export function getSourceLineCounts(source, fallback) {
+  if (source == null) {
+    return ZERO_LINE_COUNTS;
+  }
+  if (typeof source === 'string') {
+    const total = source.length === 0 ? 0 : source.split('\n').length;
+    return {
+      totalLines: total,
+      focusedLines: total,
+      collapsible: false
+    };
+  }
+  const cached = sourceLineCountsCache.get(source);
+  if (cached) {
+    return cached;
+  }
+  let counts;
+  if (typeof source === 'object' && ('hastJson' in source || 'hastCompressed' in source)) {
+    counts = readHastLineCounts(decodeHastSource(source, fallback) ?? undefined);
+  } else {
+    counts = readHastLineCounts(source);
+  }
+  sourceLineCountsCache.set(source, counts);
+  return counts;
+}
+const variantTotalLinesCache = new WeakMap();
+
+/**
+ * Sum `totalLines` across every file in a variant (main file +
+ * `extraFiles`). Used by `variantHasLayoutShift` in `'all'` mode to
+ * decide whether the aggregate height changes when switching
+ * variants. Memoized per variant identity.
+ */
+function sumVariantTotalLines(variant) {
+  const cached = variantTotalLinesCache.get(variant);
+  if (cached !== undefined) {
+    return cached;
+  }
+  let sum = variant.fileName ? getVariantFileLineCounts(variant, variant.fileName)?.totalLines ?? 0 : getSourceLineCounts(variant.source, variant.fallback).totalLines;
+  if (variant.extraFiles) {
+    for (const [fileName, file] of Object.entries(variant.extraFiles)) {
+      if (file == null) {
+        continue;
+      }
+      sum += getVariantFileLineCounts(variant, fileName)?.totalLines ?? 0;
+    }
+  }
+  variantTotalLinesCache.set(variant, sum);
+  return sum;
+}
+export function getVariantFileLineCounts(variant, fileName) {
+  if ('fileName' in variant && variant.fileName === fileName) {
+    if (variant.source === undefined) {
+      return null;
+    }
+    const stored = readStoredLineCounts(variant);
+    if (stored) {
+      return stored;
+    }
+    return getSourceLineCounts(variant.source, variant.fallback);
+  }
+  const extra = variant.extraFiles?.[fileName];
+  if (extra === undefined) {
+    return null;
+  }
+  if (typeof extra === 'string') {
+    const total = extra.length === 0 ? 0 : extra.split('\n').length;
+    return {
+      totalLines: total,
+      focusedLines: total,
+      collapsible: false
+    };
+  }
+  if (extra.source !== undefined) {
+    const stored = readStoredLineCounts(extra);
+    if (stored) {
+      return stored;
+    }
+    return getSourceLineCounts(extra.source, extra.fallback);
+  }
+  return null;
+}
+function getVariantCode(effectiveCode, variantKey) {
+  const variant = effectiveCode[variantKey];
+  if (!variant || typeof variant !== 'object' || !('source' in variant)) {
+    return null;
+  }
+  return variant;
+}
+
+/**
+ * Determines whether switching from `fromVariantKey` to `toVariantKey`
+ * would visibly shift layout. The `mode` mirrors the transform
+ * classifier and is configured via `useCode`'s `variantLayoutShift`
+ * option:
+ *
+ *   - `'all'` — sums `totalLines` across every file (main +
+ *     `extraFiles`) in both variants. Layout shift when the totals
+ *     differ. Useful when the rendering surface displays the full
+ *     variant simultaneously.
+ *   - `'selected'` (default) — compares `totalLines` for the
+ *     currently-selected file (`selectedFileName`, falling back to
+ *     the source variant's main file) between the two variants.
+ *     Layout shift when the line counts differ.
+ *   - `'focus'` — like `'selected'` but consults `focusedLines`
+ *     (the size of the visible window when the surrounding code
+ *     block is collapsed) while `expanded === false`. Reverts to
+ *     `'selected'`-style behavior when expanded. Recommended for
+ *     demos that use `@focus`/`@padding` to collapse to a region.
+ *
+ * Returns `true` (layout shift) when:
+ *   - either variant is missing,
+ *   - the selected file is missing from either variant (the file
+ *     list itself changes),
+ *   - the relevant line count differs between the two variants.
+ *
+ * Returns `false` for same-variant swaps and when the line counts
+ * match.
+ */
+export function variantHasLayoutShift(effectiveCode, fromVariantKey, toVariantKey, opts) {
+  if (!fromVariantKey || !toVariantKey || fromVariantKey === toVariantKey) {
+    return false;
+  }
+  const fromVariant = getVariantCode(effectiveCode, fromVariantKey);
+  const toVariant = getVariantCode(effectiveCode, toVariantKey);
+  if (!fromVariant || !toVariant) {
+    return false;
+  }
+  const mode = opts?.mode ?? 'selected';
+  const expanded = opts?.expanded ?? false;
+  if (mode === 'all') {
+    return sumVariantTotalLines(fromVariant) !== sumVariantTotalLines(toVariant);
+  }
+
+  // `'selected'` / `'focus'` default to the from-variant's main file
+  // when no selection is supplied — mirrors the runtime's "render the
+  // main file by default" behavior.
+  let fileName = opts?.selectedFileName;
+  if (fileName === undefined && 'fileName' in fromVariant) {
+    fileName = fromVariant.fileName;
+  }
+  // No resolvable file name (e.g. an inline-only variant without
+  // `fileName`): fall back to the aggregate `totalLines` comparison
+  // used by `'all'` mode so wildly different variants still register
+  // as layout-shifting instead of silently returning `false`.
+  if (!fileName) {
+    return sumVariantTotalLines(fromVariant) !== sumVariantTotalLines(toVariant);
+  }
+  const fromCounts = getVariantFileLineCounts(fromVariant, fileName);
+  const toCounts = getVariantFileLineCounts(toVariant, fileName);
+  // File missing on either side means the file list itself changes,
+  // which is inherently layout-shifting.
+  if (!fromCounts || !toCounts) {
+    return true;
+  }
+  if (mode === 'focus' && !expanded) {
+    return fromCounts.focusedLines !== toCounts.focusedLines;
+  }
+  return fromCounts.totalLines !== toCounts.totalLines;
+}
+
+/**
+ * Description of a pair of variants whose same-named file has a
+ * different `focusedLines` count. Returned by
+ * `findVariantFocusedLinesMismatches` so callers can produce
+ * actionable error messages without re-walking the variant tree.
+ */
+
+/**
+ * Walk every variant on `effectiveCode` and collect files that share
+ * a name across variants but disagree on `focusedLines`. Used by
+ * `useCode`'s `strictMatchingVariantFocusedLines` option to throw
+ * with a pointer to the offending variants/file so the demo author
+ * can align the `@focus` / `@padding` markers across language
+ * variants and avoid coordinated barriers while collapsed.
+ *
+ * The first variant to declare a given file name is treated as the
+ * baseline; every subsequent variant that disagrees produces a
+ * mismatch entry paired with the baseline. Returns an empty array
+ * when every shared file agrees.
+ */
+export function findVariantFocusedLinesMismatches(effectiveCode) {
+  const baseline = new Map();
+  const mismatches = [];
+  const recordFile = (variantName, fileName, focusedLines) => {
+    const existing = baseline.get(fileName);
+    if (!existing) {
+      baseline.set(fileName, {
+        variantName,
+        focusedLines
+      });
+      return;
+    }
+    if (existing.focusedLines !== focusedLines) {
+      mismatches.push({
+        fileName,
+        variantA: existing.variantName,
+        variantB: variantName,
+        focusedLinesA: existing.focusedLines,
+        focusedLinesB: focusedLines
+      });
+    }
+  };
+  for (const [variantName, variant] of Object.entries(effectiveCode)) {
+    if (!variant || typeof variant !== 'object' || !('source' in variant)) {
+      continue;
+    }
+    if ('fileName' in variant && variant.fileName && variant.source !== undefined) {
+      const {
+        focusedLines
+      } = getVariantFileLineCounts(variant, variant.fileName) ?? getSourceLineCounts(variant.source, variant.fallback);
+      recordFile(variantName, variant.fileName, focusedLines);
+    }
+    if ('extraFiles' in variant && variant.extraFiles) {
+      for (const [fileName, file] of Object.entries(variant.extraFiles)) {
+        if (file == null) {
+          continue;
+        }
+        if (typeof file === 'string') {
+          const total = file.length === 0 ? 0 : file.split('\n').length;
+          recordFile(variantName, fileName, total);
+        } else if (file.source !== undefined) {
+          const {
+            focusedLines
+          } = getVariantFileLineCounts(variant, fileName) ?? getSourceLineCounts(file.source, file.fallback);
+          recordFile(variantName, fileName, focusedLines);
+        }
+      }
+    }
+  }
+  return mismatches;
+}

package/useCode/subscribeToggleNudge.d.mts

@@ -0,0 +1,3 @@
+type ToggleNudge = () => void;
+export declare function subscribeToggleNudge(preNode: HTMLElement, nudge: ToggleNudge): () => void;
+export {};