@mui/internal-docs-infra 0.12.1-canary.2 → 0.12.1-canary.21

package/pipeline/transformMarkdownCode/transformMarkdownCode.mjs

@@ -281,12 +281,16 @@ export const transformMarkdownCode = (options = {}) => {
                 tagName: 'code',
                 data: {
                   hName: 'code',
-                  hProperties: codeHProperties
+                  hProperties: codeHProperties,
+                  // Pass the source as raw hast via `hChildren` so remark-rehype
+                  // skips its mdast `text` handler, which line-trims (and would
+                  // strip the per-line indentation) on the way to hast.
+                  hChildren: [{
+                    type: 'text',
+                    value: codeNode.value
+                  }]
                 },
-                children: [{
-                  type: 'text',
-                  value: codeNode.value
-                }]
+                children: []
               }]
             };
             const outputElement = {
@@ -607,12 +611,15 @@ export const transformMarkdownCode = (options = {}) => {
                           data: {
                             hName: 'code',
                             hProperties: codeHProperties,
-                            meta: `variant=${block.variant}${Object.entries(block.props).map(([key, value]) => ` ${key}=${value}`).join('')}`
+                            meta: `variant=${block.variant}${Object.entries(block.props).map(([key, value]) => ` ${key}=${value}`).join('')}`,
+                            // Raw hast `hChildren` to keep per-line indentation;
+                            // see the filename branch above.
+                            hChildren: [{
+                              type: 'text',
+                              value: block.node.value
+                            }]
                           },
-                          children: [{
-                            type: 'text',
-                            value: block.node.value
-                          }]
+                          children: []
                         }]
                       }]
                     }]
@@ -745,12 +752,15 @@ export const transformMarkdownCode = (options = {}) => {
                     data: {
                       hName: 'code',
                       hProperties: codeHProperties,
-                      meta: `variant=${block.variant}${Object.entries(block.props).map(([key, value]) => ` ${key}=${value}`).join('')}`
+                      meta: `variant=${block.variant}${Object.entries(block.props).map(([key, value]) => ` ${key}=${value}`).join('')}`,
+                      // Raw hast `hChildren` to keep per-line indentation;
+                      // see the filename branch above.
+                      hChildren: [{
+                        type: 'text',
+                        value: block.node.value
+                      }]
                     },
-                    children: [{
-                      type: 'text',
-                      value: block.node.value
-                    }]
+                    children: []
                   }]
                 }]
               }]

package/pipeline/transformMarkdownMetadata/transformMarkdownMetadata.mjs

@@ -834,6 +834,9 @@ export const transformMarkdownMetadata = (options = {}) => {
             if (options.extractToIndex.indexWrapperComponent) {
               updateOptions.indexWrapperComponent = options.extractToIndex.indexWrapperComponent;
             }
+            if (options.extractToIndex.cacheDir) {
+              updateOptions.cacheDir = options.extractToIndex.cacheDir;
+            }
           }
           await syncPageIndex(updateOptions);
         } catch (error) {

package/pipeline/transformMarkdownMetadata/types.d.mts

@@ -1,5 +1,5 @@
 import type { PhrasingContent } from 'mdast';
-import { type Audience } from "../../createSitemap/types.mjs";
+import type { Audience } from "../../createSitemap/types.mjs";
 /**
  * Base options for syncing page indexes.
  * Shared between extractToIndex (markdown metadata) and updateParentIndex (types).
@@ -28,6 +28,13 @@ export type SyncPageIndexBaseOptions = {
    * @default false
    */
   errorIfOutOfDate?: boolean;
+  /**
+   * Directory for the sha256-validated JSON cache of page indexes. When set, each
+   * index written is also cached at `{cacheDir}/pages-index/{route}.json`, leaving it
+   * warm for the next cold `loadServerPageIndex` read.
+   * @default undefined (disabled)
+   */
+  cacheDir?: string;
 };
 /**
  * Plugin options for transformMarkdownMetadata

package/useCode/EditableEngine.d.mts

@@ -1,4 +1,4 @@
-import { type Position } from "./useEditableUtils.mjs";
+import type { Position } from "./useEditableUtils.mjs";
 import type { EditingEngineLoader } from "./editingEngineCache.mjs";
 type History = [Position, string];
 export interface State {

package/useCode/Pre.d.mts

@@ -2,7 +2,7 @@ import * as React from 'react';
 import type { SetSource } from "./useSourceEditing.mjs";
 import type { VariantSource } from "../CodeHighlighter/types.mjs";
 import type { FallbackNode } from "../CodeHighlighter/fallbackFormat.mjs";
-import { type SourceLineCounts } from "./sourceLineCounts.mjs";
+import type { SourceLineCounts } from "./sourceLineCounts.mjs";
 export declare function Pre({
   children,
   className,
@@ -22,7 +22,8 @@ export declare function Pre({
   onTransitionReady,
   swapTarget,
   editActivation,
-  onActivate
+  onActivate,
+  editable
 }: {
   children: VariantSource;
   className?: string;
@@ -160,4 +161,10 @@ export declare function Pre({
    * the live-editing engine, grammars, and worker at the activation moment.
    */
   onActivate?: () => void;
+  /**
+   * Whether edit mode is on. When `false` the block stays read-only — `useEditable` is
+   * never enabled, so there's no `contentEditable`, no engine load, and no `onActivate`.
+   * Defaults to `true`; the host drives it from the `editable` toggle `useCode` returns.
+   */
+  editable?: boolean;
 }): React.ReactNode;

package/useCode/Pre.mjs

@@ -240,7 +240,8 @@ export function Pre({
   onTransitionReady,
   swapTarget,
   editActivation,
-  onActivate
+  onActivate,
+  editable = true
 }) {
   // Defer the decompressing `decodeHastSource` to a post-paint render ONLY when the
   // first-paint `.fallback` is ALREADY highlighted — i.e. the promoted highlighted-visible
@@ -419,7 +420,7 @@ export function Pre({
   const collapsedBounds = React.useMemo(() => expanded ? undefined : computeCollapsedBounds(hast, indentation, collapseToEmpty), [hast, expanded, collapseToEmpty]);
   useEditable(preRef, onEditableChange, {
     indentation,
-    disabled: !setSource || !editableReady,
+    disabled: !setSource || !editableReady || !editable,
     minColumn: collapsedBounds?.minColumn,
     minRow: collapsedBounds?.minRow,
     maxRow: collapsedBounds?.maxRow,
@@ -874,7 +875,7 @@ export function Pre({
   // Collapse-to-empty empties the collapsed window, so the focused-line count is 0
   // regardless of the precomputed value.
   const sourceFocusedLines = collapseToEmpty ? 0 : rawFocusedLines;
-  const isEditable = Boolean(setSource);
+  const isEditable = Boolean(setSource) && editable;
 
   // Focus-trap state for editable code blocks. When the user tabs into the
   // wrapper (keyboard-only, gated by `:focus-visible`), an overlay prompts

package/useCode/TransformEngine.d.mts

@@ -1,4 +1,4 @@
-import { type TransformRuntimeDeps } from "../pipeline/loadIsomorphicCodeVariant/applyCodeTransformWithComments.mjs";
+import type { TransformRuntimeDeps } from "../pipeline/loadIsomorphicCodeVariant/applyCodeTransformWithComments.mjs";
 import type { VariantSource, VariantCode, Transforms, SourceComments, Fallbacks } from "../CodeHighlighter/types.mjs";
 import type { FallbackNode } from "../CodeHighlighter/fallbackFormat.mjs";
 import type { TransformedFiles } from "./useCodeUtils.mjs";

package/useCode/useCode.d.mts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import type { ContentProps, SourceEnhancers } from "../CodeHighlighter/types.mjs";
-import { type UseCopierOpts } from "../useCopier/index.mjs";
+import type { UseCopierOpts } from "../useCopier/index.mjs";
 export type UseCodeOpts = {
   preClassName?: string;
   copy?: UseCopierOpts;
@@ -203,6 +203,22 @@ export interface UseCodeResult<T extends {} = {}> {
    * stays anchored to the demo the user interacted with.
    */
   pendingTransform: string | null | undefined;
+  /**
+   * Whether edit mode is currently on. `true` by default; starts `false` when the block
+   * opts in via `initialDisabled` — per demo through the `createDemo` `meta`, or across a
+   * factory's demos through `createDemoFactory`. While `false` the block renders
+   * read-only and the live-editing engine is not even warmed; flip it with
+   * {@link setEditable}. Independent of `editActivation`, which governs *when* the engine
+   * loads once editing is on, and of `disabled`, which turns editing off permanently.
+   */
+  editable: boolean;
+  /**
+   * Turns edit mode on or off. `undefined` when the block can't be edited at all — no
+   * `CodeControllerContext` with `setCode` in scope, or editing is hard-`disabled` — so
+   * a toggle button can render only when this is defined. Toggling off keeps the
+   * reader's edits (use {@link reset} to discard them).
+   */
+  setEditable?: (editable: boolean) => void;
   /**
    * Replace the source of the currently selected file (or `fileName` when
    * provided) in the controlled code. Internal hooks may pass additional

package/useCode/useCode.mjs

@@ -149,10 +149,12 @@ export function useCode(contentProps, opts) {
   // disagree.
   const collapseToEmpty = contentProps.collapseToEmpty === true;
   const initialExpanded = contentProps.initialExpanded === true;
+  const initialDisabled = contentProps.initialDisabled === true;
 
   // Sub-hook: UI State Management (needs slug to check for relevant hash)
   const uiState = useUIState({
     initialExpanded,
+    initialDisabled,
     mainSlug: userProps.slug
   });
 
@@ -347,6 +349,7 @@ export function useCode(contentProps, opts) {
     setSource: sourceEditing.setSource,
     editActivation: context?.editActivation,
     onActivate: context?.onEditingActivated,
+    editable: uiState.editable,
     effectiveCode,
     fileHashMode,
     saveHashVariantToLocalStorage,
@@ -377,6 +380,22 @@ export function useCode(contentProps, opts) {
     title: userProps.name,
     copyOpts
   });
+
+  // Editing can be toggled only where it's possible at all: a controller with `setCode`
+  // is in scope and the block isn't hard-`disabled`. Otherwise `setEditable` is omitted,
+  // so a host renders no toggle.
+  const canToggleEditing = Boolean(controllerContext?.setCode) && !disabled;
+
+  // Discard live edits when the reader switches language.
+  const rawSelectTransform = transformManagement.selectTransform;
+  const resetSource = sourceEditing.reset;
+  const hasControlledEdits = Boolean(controllerContext?.code);
+  const selectTransform = React.useCallback(transformName => {
+    if (hasControlledEdits) {
+      resetSource?.();
+    }
+    rawSelectTransform(transformName);
+  }, [hasControlledEdits, resetSource, rawSelectTransform]);
   return {
     variants: variantSelection.variantKeys,
     selectedVariant: variantSelection.selectedVariantKey,
@@ -396,8 +415,10 @@ export function useCode(contentProps, opts) {
     copyMarkdown: copyFunctionality.copyMarkdown,
     availableTransforms: transformManagement.availableTransforms,
     selectedTransform: transformManagement.selectedTransform,
-    selectTransform: transformManagement.selectTransform,
+    selectTransform,
     pendingTransform: transformManagement.pendingTransform,
+    editable: uiState.editable,
+    setEditable: canToggleEditing ? uiState.setEditable : undefined,
     setSource: sourceEditing.setSource,
     reset: sourceEditing.reset,
     refresh: context?.refresh,

package/useCode/useCopyFunctionality.d.mts

@@ -1,8 +1,8 @@
 import * as React from 'react';
-import { type UseCopierOpts } from "../useCopier/index.mjs";
+import type { UseCopierOpts } from "../useCopier/index.mjs";
 import type { Fallbacks, VariantCode, VariantSource } from "../CodeHighlighter/types.mjs";
 import type { FallbackNode } from "../CodeHighlighter/fallbackFormat.mjs";
-import { type MarkdownFile } from "./generateVariantMarkdown.mjs";
+import type { MarkdownFile } from "./generateVariantMarkdown.mjs";
 import type { TransformedFiles } from "./useCodeUtils.mjs";
 interface UseCopyFunctionalityProps {
   selectedFile: VariantSource | null;

package/useCode/useEditable.browser.mjs

@@ -2,7 +2,6 @@ import { describe, it, expect, vi, afterEach, beforeAll } from 'vitest';
 import { renderHook, act } from '@testing-library/react';
 import { userEvent } from 'vitest/browser';
 import { useEditable, preloadEditableEngine } from "./useEditable.mjs";
-
 // `useEditable` loads its heavy runtime (the `EditableEngine` chunk) on demand
 // and only applies `contentEditable` once it resolves. Warm that load once so
 // the synchronous assertions below see `contentEditable` applied within `act`,

package/useCode/useFileNavigation.d.mts

@@ -30,6 +30,8 @@ interface UseFileNavigationProps {
   editActivation?: 'eager' | 'interaction';
   /** Forwarded to `<Pre>` / `useEditable`: fired once when the block engages for editing. */
   onActivate?: () => void;
+  /** Forwarded to `<Pre>`: whether edit mode is on. When `false` the block stays read-only. */
+  editable?: boolean;
   effectiveCode?: Code;
   selectVariant?: React.Dispatch<React.SetStateAction<string>>;
   fileHashMode?: 'remove-hash' | 'remove-filename';
@@ -153,6 +155,7 @@ export declare function useFileNavigation({
   setSource,
   editActivation,
   onActivate,
+  editable,
   effectiveCode,
   selectVariant,
   fileHashMode,

package/useCode/useFileNavigation.mjs

@@ -70,6 +70,7 @@ export function useFileNavigation({
   setSource,
   editActivation,
   onActivate,
+  editable,
   effectiveCode,
   selectVariant,
   fileHashMode = 'remove-hash',
@@ -542,6 +543,7 @@ export function useFileNavigation({
         setSource: setSource,
         editActivation: editActivation,
         onActivate: onActivate,
+        editable: editable,
         shouldHighlight: shouldHighlight,
         fallback: selectedFileFallback,
         fallbackLineCounts: selectedFileLineCounts,
@@ -555,7 +557,7 @@ export function useFileNavigation({
       }, getPreRenderKey(fileSlug, enhancementPhase));
     }
     return null;
-  }, [selectedVariant, shouldHighlight, preClassName, setSource, editActivation, onActivate, enhancedSource, isEnhancing, mainSlug, selectedFile, selectedVariantKey, sourceEnhancers, selectedFileNameInternal, selectedFileFallback, selectedFileLineCounts, expanded, collapseToEmpty, expand, transforming, onPreTransitionReady, variantBridgeLineMode, resolveSwapTarget]);
+  }, [selectedVariant, shouldHighlight, preClassName, setSource, editActivation, onActivate, editable, enhancedSource, isEnhancing, mainSlug, selectedFile, selectedVariantKey, sourceEnhancers, selectedFileNameInternal, selectedFileFallback, selectedFileLineCounts, expanded, collapseToEmpty, expand, transforming, onPreTransitionReady, variantBridgeLineMode, resolveSwapTarget]);
   const selectedFileLines = React.useMemo(() => {
     if (selectedFile == null) {
       return 0;

package/useCode/useSourceEditing.mjs

@@ -3,6 +3,7 @@ import * as React from 'react';
 // (via `useCopyFunctionality`/`Pre`). Passing it into the lazy editing engine
 // keeps that engine chunk from statically pulling it (and `hastDecompress`).
 import { stringOrHastToString } from "../pipeline/hastUtils/index.mjs";
+import { preParsedCacheKey } from "../CodeHighlighter/parseControlledCode.mjs";
 import { useCodeContext } from "../CodeProvider/CodeContext.mjs";
 import { peekEditingEngine, loadEditingEngine, preloadEditingEngine, resetEditingEngineCache } from "./editingEngineCache.mjs";
 // The edit-time runtime (`analyzeSource`/`shiftComments`/`toControlledCode`) lives
@@ -50,11 +51,11 @@ export function useSourceEditing({
     editingEngineLoader
   } = useCodeContext();
 
-  // Monotonic token bumped by every `setSource`/`reset`. A cold first edit
-  // defers its commit into a microtask; if a later edit or a `reset` happens
-  // before the engine resolves, the stale deferred commit must NOT run (it would
-  // re-apply a superseded edit and, after a reset, reverse it). The deferred
-  // callback captures the token at schedule time and bails if it changed.
+  // Monotonic token bumped by every `setSource`/`reset`. A cold first edit defers
+  // its commit until the engine chunk resolves; if a later edit or a `reset`
+  // happens before then, the stale deferred commit must NOT run (it would re-apply
+  // a superseded edit and, after a reset, reverse it). The deferred callback
+  // captures the token at schedule time and bails if it changed.
   const editTokenRef = React.useRef(0);
   const setSource = React.useCallback((source, fileName, position, preParsed) => {
     if (!contextSetCode) {
@@ -76,13 +77,13 @@ export function useSourceEditing({
     const resolvedFileName = fileName ?? selectedVariant?.fileName;
     const preParsedCache = context?.preParsedCache;
     if (preParsed !== undefined && preParsedCache && resolvedFileName) {
-      preParsedCache.set(resolvedFileName, {
+      preParsedCache.set(preParsedCacheKey(selectedVariantKey, resolvedFileName), {
         source,
         hast: preParsed
       });
     }
     const applyUpdate = engine => {
-      contextSetCode(currentCode => {
+      const applyEdit = currentCode => {
         const newCode = currentCode ? {
           ...currentCode
         } : engine.toControlledCode(effectiveCode, selectedVariantKey, context?.fallbacks, stringOrHastToString);
@@ -175,8 +176,37 @@ export function useSourceEditing({
             }
           };
         }
+        const editedVariant = newCode[selectedVariantKey];
+        if (editedVariant) {
+          if (!currentCode) {
+            // FIRST edit (precomputed → controlled): carry the pre-edit build
+            // inputs so the runner renders the ORIGINAL as a baseline before this
+            // (possibly broken) edit, then swaps to it (see `useVariantBuilds`).
+            newCode[selectedVariantKey] = {
+              ...editedVariant,
+              original: {
+                source: variant.source,
+                extraFiles: variant.extraFiles
+              }
+            };
+          } else if (editedVariant.original) {
+            // Subsequent edit: the baseline already rendered — drop `original` so
+            // it doesn't linger in (and bloat) the controlled state.
+            const stripped = {
+              ...editedVariant
+            };
+            delete stripped.original;
+            newCode[selectedVariantKey] = stripped;
+          }
+        }
         return newCode;
-      });
+      };
+
+      // A SINGLE update carries the edited code to the controller — which the
+      // editor reflects immediately (no seed/handoff dance). On the FIRST edit
+      // `applyEdit` tags it with `.original`, so the runner renders the original
+      // as a baseline before swapping to this edit (see `useVariantBuilds`).
+      contextSetCode(applyEdit);
     };
 
     // Apply synchronously from the warm cache (the common case — the warm
@@ -211,8 +241,13 @@ export function useSourceEditing({
     }
     // Supersede any pending cold edit so it can't re-apply after this reset.
     editTokenRef.current += 1;
-    contextSetCode(undefined);
-  }, [contextSetCode]);
+    // Evict any pre-parsed HAST so the original re-parses fresh on the next render
+    // (matches `refresh()`); a stale entry keyed by (variant, fileName) would otherwise
+    // survive the reset and the source viewer could reuse it for the rebuilt original.
+    context?.preParsedCache?.clear();
+    // Back to an empty controlled state, so the next edit re-tags `.original`.
+    contextSetCode(null);
+  }, [contextSetCode, context?.preParsedCache]);
   const isEditable = !disabled && Boolean(contextSetCode) && Boolean(selectedVariant);
   const canReset = !disabled && Boolean(contextSetCode);
   return {

package/useCode/useSourceEnhancing.mjs

@@ -4,6 +4,13 @@ import * as React from 'react';
 import { decodeHastSource } from "../pipeline/loadIsomorphicCodeVariant/decodeHastSource.mjs";
 import { recordEnhancerApplied, shouldSkipEnhancer } from "../pipeline/loadIsomorphicCodeVariant/runSourceEnhancers.mjs";
 
+// Safety-net deadline (ms) for the async enhancer pass. A client-side enhancer that
+// REJECTS or HANGS would otherwise leave `asyncWork` non-null forever — keeping
+// `isEnhancing` true and locking the consumer (`<Pre>` via `useFileNavigation`) at its
+// un-enhanced 'base' phase until a full page reload. On failure/timeout we settle to the
+// already sync-enhanced result so the phase advances.
+const ENHANCER_TIMEOUT_MS = 10_000;
+
 /**
  * Resolves a `VariantSource` to a HAST root that is safe to mutate.
  *
@@ -194,22 +201,47 @@ export function useSourceEnhancing({
     const enhancers = sourceEnhancers;
     const name = fileName || 'unknown';
     let cancelled = false;
-    async function continueEnhancing() {
-      const asyncResult = await firstAsyncPromise;
-      if (cancelled) {
-        return;
-      }
-      const final = await applyEnhancersFrom(asyncResult, comments, name, enhancers, asyncStartIndex + 1);
+
+    // Clear `asyncWork` (keeping whatever enhanced source we already have) so
+    // `isEnhancing` drops and the consumer's phase advances. Used by the failure and
+    // timeout paths below — without it a rejected/hung enhancer wedges 'base' forever.
+    const settleWithCurrent = () => {
       if (!cancelled) {
-        setState({
-          enhancedSource: final,
+        setState(previous => ({
+          enhancedSource: previous.enhancedSource,
           asyncWork: null
-        });
+        }));
+      }
+    };
+
+    // Safety net for a hung enhancer (a promise that never settles): force-settle after
+    // the deadline so the un-enhanced phase isn't locked until a reload.
+    const timer = setTimeout(settleWithCurrent, ENHANCER_TIMEOUT_MS);
+    async function continueEnhancing() {
+      try {
+        const asyncResult = await firstAsyncPromise;
+        if (cancelled) {
+          return;
+        }
+        const final = await applyEnhancersFrom(asyncResult, comments, name, enhancers, asyncStartIndex + 1);
+        if (!cancelled) {
+          setState({
+            enhancedSource: final,
+            asyncWork: null
+          });
+        }
+      } catch (error) {
+        // A rejected async enhancer must not strand `asyncWork` non-null forever.
+        console.error('Async source enhancer failed; settling with the current result.', error);
+        settleWithCurrent();
+      } finally {
+        clearTimeout(timer);
       }
     }
     continueEnhancing();
     return () => {
       cancelled = true;
+      clearTimeout(timer);
     };
   }, [state.asyncWork, sourceEnhancers, fileName, comments]);
   return {

package/useCode/useTransformManagement.d.mts

@@ -1,8 +1,8 @@
 import type { Code, VariantCode } from "../CodeHighlighter/types.mjs";
 import type { CreateTransformedFiles } from "./TransformEngine.mjs";
 import { preloadTransformEngine, resetTransformEngineCache } from "./transformEngineCache.mjs";
-import { type CodeHighlighterContextType } from "../CodeHighlighter/CodeHighlighterContext.mjs";
-import { type TransitionPhase } from "./useTransitionPhase.mjs";
+import type { CodeHighlighterContextType } from "../CodeHighlighter/CodeHighlighterContext.mjs";
+import type { TransitionPhase } from "./useTransitionPhase.mjs";
 export { preloadTransformEngine, resetTransformEngineCache };
 interface UseTransformManagementProps {
   context?: CodeHighlighterContextType;

package/useCode/useTransformManagement.mjs

@@ -13,7 +13,6 @@ import { usePreference } from "../usePreference/index.mjs";
 import { useCoordinated } from "../useCoordinated/index.mjs";
 import { useHighlightGate } from "./useHighlightGate.mjs";
 import { useTransitionPhase } from "./useTransitionPhase.mjs";
-
 // Stable identity for the hast helpers handed to the transform engine; both are
 // module-level functions, so this never needs to change.
 const transformRuntimeDeps = {
@@ -123,7 +122,19 @@ export function useTransformManagement({
   // here, otherwise rename-only entries would be dropped from
   // resolution and the storage key would shift whenever a transform's
   // visibility changed between sibling demos.
-  const applicableTransforms = React.useMemo(() => getApplicableTransforms(effectiveCode, selectedVariantKey), [effectiveCode, selectedVariantKey]);
+  const contextAvailableTransforms = context?.availableTransforms;
+  // What the CURRENT (possibly edited) code can actually apply. Empty while
+  // live-editing, since controlled code carries no transform manifest.
+  const applicableFromCode = React.useMemo(() => getApplicableTransforms(effectiveCode, selectedVariantKey), [effectiveCode, selectedVariantKey]);
+  const applicableTransforms = React.useMemo(() => {
+    // Fall back to the controller's visible list while editing so a language
+    // switch still validates — it discards the edit and re-applies to the
+    // pristine build-time source (see `useCode.selectTransform`).
+    if (applicableFromCode.length === 0 && contextAvailableTransforms?.length) {
+      return contextAvailableTransforms;
+    }
+    return applicableFromCode;
+  }, [applicableFromCode, contextAvailableTransforms]);
 
   // Coordinator key. Demos sharing the same applicable transform set
   // belong to the same coordination group: a user click in one demo
@@ -510,6 +521,11 @@ export function useTransformManagement({
   // `onCommit` when its `(variant, transform)` keys match the values
   // about to be rendered.
   const transformedFiles = React.useMemo(() => {
+    // While live-editing, `selectedTransform` may still be e.g. `js`, so
+    // return `undefined` to render the edited source as-is (see `useFileNavigation`).
+    if (delayedAppliedTransform && !applicableFromCode.includes(delayedAppliedTransform)) {
+      return undefined;
+    }
     if (precomputed && precomputed.variant === selectedVariant && precomputed.transform === delayedAppliedTransform) {
       return precomputed.result;
     }
@@ -522,7 +538,7 @@ export function useTransformManagement({
       return undefined;
     }
     return transformEngine(selectedVariant, delayedAppliedTransform, transformRuntimeDeps, context?.fallbacks);
-  }, [precomputed, selectedVariant, delayedAppliedTransform, context?.fallbacks, transformEngine]);
+  }, [precomputed, selectedVariant, delayedAppliedTransform, applicableFromCode, context?.fallbacks, transformEngine]);
   const result = {
     availableTransforms,
     selectedTransform,

package/useCode/useUIState.d.mts

@@ -1,12 +1,15 @@
 import * as React from 'react';
 interface UseUIStateProps {
   initialExpanded?: boolean;
+  initialDisabled?: boolean;
   mainSlug?: string;
 }
 export interface UseUIStateResult {
   expanded: boolean;
   expand: () => void;
   setExpanded: React.Dispatch<React.SetStateAction<boolean>>;
+  editable: boolean;
+  setEditable: React.Dispatch<React.SetStateAction<boolean>>;
 }
 /**
  * Hook for managing UI state like expansion and focus
@@ -14,6 +17,7 @@ export interface UseUIStateResult {
  */
 export declare function useUIState({
   initialExpanded,
+  initialDisabled,
   mainSlug
 }: UseUIStateProps): UseUIStateResult;
 export {};

package/useCode/useUIState.mjs

@@ -7,6 +7,7 @@ import { isHashRelevantToDemo } from "./useFileNavigation.mjs";
  */
 export function useUIState({
   initialExpanded = false,
+  initialDisabled = false,
   mainSlug
 }) {
   const [hash] = useUrlHashState();
@@ -14,6 +15,10 @@ export function useUIState({
   const [expanded, setExpanded] = React.useState(initialExpanded || hasRelevantHash);
   const expand = React.useCallback(() => setExpanded(true), []);
 
+  // Edit-mode toggle. Starts on unless the block opted into `initialDisabled`; the host
+  // exposes `setEditable` (gated on a controller) so a reader can flip read-only ↔ edit.
+  const [editable, setEditable] = React.useState(!initialDisabled);
+
   // Auto-expand if hash becomes relevant. This is a one-way OR-latch: it ratchets
   // `expanded` to true but never collapses, so adjusting state during render is safe
   // (the branch is skipped once `expanded` is true, avoiding an extra render).
@@ -23,6 +28,8 @@ export function useUIState({
   return {
     expanded,
     expand,
-    setExpanded
+    setExpanded,
+    editable,
+    setEditable
   };
 }

package/useCode/useVariantSelection.d.mts

@@ -1,6 +1,6 @@
 import * as React from 'react';
 import type { Code, VariantCode } from "../CodeHighlighter/types.mjs";
-import { type TransitionPhase } from "./useTransitionPhase.mjs";
+import type { TransitionPhase } from "./useTransitionPhase.mjs";
 interface UseVariantSelectionProps {
   effectiveCode: Code;
   initialVariant?: string;

package/useCoordinated/useCoordinated.d.mts

@@ -1,5 +1,5 @@
 import * as React from 'react';
-import { type ChannelKey, type PeerId } from "./coordinatePreference.mjs";
+import type { ChannelKey, PeerId } from "./coordinatePreference.mjs";
 /**
  * Options for {@link useCoordinated}. See `coordinatePreference` for
  * the underlying semantics; only React-specific behaviors are

package/useCoordinated/useCoordinatedLocalStorage.d.mts

@@ -1,5 +1,5 @@
 import type * as React from 'react';
-import { type UseCoordinatedExtras, type UseCoordinatedOptions } from "./useCoordinated.mjs";
+import type { UseCoordinatedExtras, UseCoordinatedOptions } from "./useCoordinated.mjs";
 /**
  * `useLocalStorageState` + coordination in one call. Cross-tab sync
  * happens via the underlying storage events; the coordinator handles

package/useCoordinated/useCoordinatedLocalStorage.mjs

@@ -2,7 +2,6 @@
 
 import useLocalStorageState from "../useLocalStorageState/index.mjs";
 import { useCoordinated } from "./useCoordinated.mjs";
-
 /**
  * `useLocalStorageState` + coordination in one call. Cross-tab sync
  * happens via the underlying storage events; the coordinator handles

package/useCoordinated/useCoordinatedPreference.d.mts

@@ -1,5 +1,5 @@
 import type * as React from 'react';
-import { type UseCoordinatedExtras, type UseCoordinatedOptions } from "./useCoordinated.mjs";
+import type { UseCoordinatedExtras, UseCoordinatedOptions } from "./useCoordinated.mjs";
 /**
  * `usePreference` + {@link useCoordinated} in one call.
  *