@mui/internal-docs-infra 0.11.1-canary.15 → 0.11.1-canary.17

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mui/internal-docs-infra",
-  "version": "0.11.1-canary.15",
+  "version": "0.11.1-canary.17",
   "author": "MUI Team",
   "description": "MUI Infra - internal documentation creation tools.",
   "license": "MIT",
@@ -768,5 +768,5 @@
   "bin": {
     "docs-infra": "./cli/index.mjs"
   },
-  "gitSha": "6ad5e4fa528c6617251224a57814890fdf1c4389"
+  "gitSha": "5f0871264ec4d7c78d5fd7e62888de0f7bf61cda"
 }

package/pipeline/parseSource/extendSyntaxTokens.mjs

@@ -140,6 +140,334 @@ function enhanceStringSpan(element) {
   }
 }
 
+/**
+ * Tests whether a `pl-k` token's text consists entirely of symbol characters
+ * (no letters, digits, or underscore). Used to distinguish symbolic operators
+ * (`=`, `=>`, `&&`, `...`) from word keywords (`const`, `if`, `function`).
+ */
+function isSymbolicPunctuation(text) {
+  if (text.length === 0) {
+    return false;
+  }
+  for (let i = 0; i < text.length; i += 1) {
+    const code = text.charCodeAt(i);
+    // 0-9
+    if (code >= 48 && code <= 57) {
+      return false;
+    }
+    // A-Z
+    if (code >= 65 && code <= 90) {
+      return false;
+    }
+    // a-z
+    if (code >= 97 && code <= 122) {
+      return false;
+    }
+    // _
+    if (code === 95) {
+      return false;
+    }
+  }
+  return true;
+}
+
+/**
+ * Splits a text value into nodes, wrapping bare identifier object-literal keys
+ * (e.g. `height` in `{ height: 400 }`) in a `<span>` carrying `di-op` plus, when
+ * `inJsx` is true, also `di-jv`. Returns `null` if no key pattern is found,
+ * leaving the original text node untouched.
+ *
+ * A key is detected as `[A-Za-z_$][\w$]*` immediately preceded by `{` or `,`
+ * (with optional whitespace) and followed by optional whitespace, then a single
+ * `:` not part of `::`. The leading-context check avoids tagging ternary/label
+ * patterns; the trailing check avoids `::` (TypeScript namespace, pseudo-elements).
+ */
+function splitObjectKeys(value, inJsx) {
+  const nodes = [];
+  let lastEnd = 0;
+  let i = 0;
+  while (i < value.length) {
+    const code = value.charCodeAt(i);
+    const isIdentStart = code >= 65 && code <= 90 || code >= 97 && code <= 122 || code === 95 || code === 36;
+    if (!isIdentStart) {
+      i += 1;
+      continue;
+    }
+
+    // Find preceding non-whitespace character; must be `{` or `,` (object key context)
+    let prev = i - 1;
+    while (prev >= 0) {
+      const pc = value.charCodeAt(prev);
+      if (pc !== 32 && pc !== 9 && pc !== 10 && pc !== 13) {
+        break;
+      }
+      prev -= 1;
+    }
+    if (prev < 0) {
+      i += 1;
+      continue;
+    }
+    const prevCode = value.charCodeAt(prev);
+    if (prevCode !== 123 /* { */ && prevCode !== 44 /* , */) {
+      i += 1;
+      continue;
+    }
+
+    // Consume identifier chars
+    let end = i + 1;
+    while (end < value.length) {
+      const ec = value.charCodeAt(end);
+      const isIdentPart = ec >= 48 && ec <= 57 || ec >= 65 && ec <= 90 || ec >= 97 && ec <= 122 || ec === 95 || ec === 36;
+      if (!isIdentPart) {
+        break;
+      }
+      end += 1;
+    }
+
+    // Skip whitespace, expect a single `:` (not `::`)
+    let after = end;
+    while (after < value.length) {
+      const ac = value.charCodeAt(after);
+      if (ac !== 32 && ac !== 9 && ac !== 10 && ac !== 13) {
+        break;
+      }
+      after += 1;
+    }
+    if (after >= value.length || value.charCodeAt(after) !== 58 /* : */) {
+      i = end;
+      continue;
+    }
+    if (after + 1 < value.length && value.charCodeAt(after + 1) === 58) {
+      i = end;
+      continue;
+    }
+    if (i > lastEnd) {
+      nodes.push({
+        type: 'text',
+        value: value.slice(lastEnd, i)
+      });
+    }
+    const className = inJsx ? ['di-op', 'di-jv'] : ['di-op'];
+    nodes.push({
+      type: 'element',
+      tagName: 'span',
+      properties: {
+        className
+      },
+      children: [{
+        type: 'text',
+        value: value.slice(i, end)
+      }]
+    });
+    lastEnd = end;
+    i = end;
+  }
+  if (nodes.length === 0) {
+    return null;
+  }
+  if (lastEnd < value.length) {
+    nodes.push({
+      type: 'text',
+      value: value.slice(lastEnd)
+    });
+  }
+  return nodes;
+}
+
+/**
+ * Tests whether a string starts with optional whitespace followed by `:`.
+ * Used to detect that a `pl-s` span sits in object property-key position.
+ */
+function startsWithColon(text) {
+  for (let i = 0; i < text.length; i += 1) {
+    const ch = text.charCodeAt(i);
+    if (ch === 58) {
+      return true;
+    }
+    // space, tab, newline, carriage return
+    if (ch !== 32 && ch !== 9 && ch !== 10 && ch !== 13) {
+      return false;
+    }
+  }
+  return false;
+}
+
+/**
+ * Frame in the template-literal interpolation stack. A `string` frame means we
+ * are inside template-string content; an `expr` frame means we are inside a
+ * `${ ... }` interpolation expression, tracking `{`/`}` nesting via `braceDepth`
+ * so the matching close brace can be found across object literals and lines.
+ */
+
+/** Creates an empty `di-te` interpolation-region span. */
+function createInterpolationRegion() {
+  return {
+    type: 'element',
+    tagName: 'span',
+    properties: {
+      className: ['di-te']
+    },
+    children: []
+  };
+}
+
+/** Creates a `di-td` delimiter span wrapping the given `${` or `}` glyph. */
+function createInterpolationDelimiter(value) {
+  return {
+    type: 'element',
+    tagName: 'span',
+    properties: {
+      className: ['di-td']
+    },
+    children: [{
+      type: 'text',
+      value
+    }]
+  };
+}
+
+/** True when a node is a `pl-pds` span whose text is a backtick. */
+function isBacktickDelimiter(node) {
+  return !!node && node.type === 'element' && node.tagName === 'span' && getFirstClass(node) === 'pl-pds' && getShallowTextContent(node) === '`';
+}
+function pushText(target, value) {
+  target.push({
+    type: 'text',
+    value
+  });
+}
+
+/**
+ * Scans one text node of a template literal, splitting it around interpolation
+ * boundaries. In `string` mode it looks for `${` (opening a `di-te` region with a
+ * `di-td` delimiter); in `expr` mode it counts `{`/`}` to find the matching close
+ * (emitting the closing `di-td`). Mutates `stack` and `targets` in place as it
+ * crosses boundaries, appending nodes to the innermost current target.
+ */
+function processTemplateText(value, stack, targets) {
+  let i = 0;
+  let segStart = 0;
+  while (i < value.length) {
+    const top = stack[stack.length - 1];
+    const target = targets[targets.length - 1];
+    if (top.mode === 'string') {
+      const open = value.indexOf('${', i);
+      if (open === -1) {
+        break;
+      }
+      if (open > segStart) {
+        pushText(target, value.slice(segStart, open));
+      }
+      const region = createInterpolationRegion();
+      target.push(region);
+      region.children.push(createInterpolationDelimiter('${'));
+      stack.push({
+        mode: 'expr',
+        braceDepth: 1
+      });
+      targets.push(region.children);
+      i = open + 2;
+      segStart = i;
+    } else {
+      const code = value.charCodeAt(i);
+      if (code === 123 /* { */) {
+        top.braceDepth += 1;
+        i += 1;
+      } else if (code === 125 /* } */) {
+        top.braceDepth -= 1;
+        if (top.braceDepth === 0) {
+          if (i > segStart) {
+            pushText(target, value.slice(segStart, i));
+          }
+          target.push(createInterpolationDelimiter('}'));
+          stack.pop();
+          targets.pop();
+          i += 1;
+          segStart = i;
+        } else {
+          i += 1;
+        }
+      } else {
+        i += 1;
+      }
+    }
+  }
+  if (segStart < value.length) {
+    pushText(targets[targets.length - 1], value.slice(segStart));
+  }
+}
+
+/**
+ * Restructures one `pl-s` template-literal line, wrapping each `${ ... }`
+ * interpolation slice on the line in a `di-te` region with `di-td` delimiters.
+ *
+ * `entryStack` carries the interpolation state from previous lines (a single
+ * `string` frame for the opening line). `isOpener` is true for the line that
+ * holds the opening backtick. Because starry-night emits one `pl-s` span per line
+ * and the line gutter splits on top-level newlines, a region can never cross a
+ * line boundary — each line's slice is wrapped on its own, so a continuation
+ * line opens a fresh `di-te` with no leading `${`. Returns the stack to carry to
+ * the next line, or `null` once the closing backtick is consumed (run complete).
+ */
+function restructureTemplateLine(pls, entryStack, isOpener) {
+  const source = pls.children;
+  const out = [];
+  const stack = entryStack.map(frame => ({
+    ...frame
+  }));
+
+  // Rebuild the physical target chain for the carried stack: each open `expr`
+  // frame gets a fresh `di-te` region on this line; nested `string` frames share
+  // their parent expression's region as the target.
+  const targets = [out];
+  for (let depth = 1; depth < stack.length; depth += 1) {
+    if (stack[depth].mode === 'expr') {
+      const region = createInterpolationRegion();
+      targets[depth - 1].push(region);
+      targets.push(region.children);
+    } else {
+      targets.push(targets[depth - 1]);
+    }
+  }
+  let runEnded = false;
+  let index = 0;
+  if (isOpener) {
+    out.push(source[0]);
+    index = 1;
+  }
+  for (; index < source.length; index += 1) {
+    const node = source[index];
+    const target = targets[targets.length - 1];
+    if (node.type === 'text') {
+      processTemplateText(node.value, stack, targets);
+      continue;
+    }
+    if (isBacktickDelimiter(node)) {
+      if (stack[stack.length - 1].mode === 'expr') {
+        // A nested template literal opens inside the interpolation expression.
+        target.push(node);
+        stack.push({
+          mode: 'string'
+        });
+        targets.push(target);
+      } else if (stack.length === 1) {
+        // The outer template's closing backtick — the run is complete.
+        out.push(node);
+        runEnded = true;
+      } else {
+        // A nested template literal's closing backtick.
+        target.push(node);
+        stack.pop();
+        targets.pop();
+      }
+      continue;
+    }
+    target.push(node);
+  }
+  pls.children = out;
+  return runEnded ? null : stack;
+}
+
 /**
  * Single-pass enhancement of a HAST children array. Processes each child exactly
  * once, applying all per-element and sibling-context enhancements in one iteration.
@@ -148,6 +476,7 @@ function enhanceStringSpan(element) {
  * Per-element enhancements (applied to individual spans):
  * - `pl-c1` → `di-num`, `di-bool`, `di-n`, `di-this`, `di-bt` via enhanceConstantSpan
  * - `pl-s` → `di-n` for empty strings via enhanceStringSpan
+ * - `pl-k` symbolic operators (`=`, `=>`, `&&`, `...`) → `di-pu`
  *
  * Sibling-context enhancements (depend on neighbor nodes or positional state):
  * - CSS `&` nesting selector → wraps in `pl-ent` span
@@ -155,6 +484,9 @@ function enhanceStringSpan(element) {
  * - CSS `property: value` → `di-cp` / `di-cv` based on colon position
  * - HTML/JSX `<tag attr=value>` → `di-ak`, `di-ae`, `di-av`
  * - JSX `<Component>` → `di-jsx` on component name spans
+ * - JSX `{expression}` → `di-jv` on `pl-smi`/`pl-v` identifier spans inside braces
+ * - JS `'key':` object property string → `di-ps` on `pl-s` spans
+ * - JS template literals → `di-te` region / `di-td` delimiters around `${ ... }`
  */
 function enhanceChildren(children, isCss, isHtmlJsx, isJs, isTs, isJsx) {
   // CSS declaration state: tracks position relative to { } : ; [ ]
@@ -165,9 +497,17 @@ function enhanceChildren(children, isCss, isHtmlJsx, isJs, isTs, isJsx) {
   // HTML/JSX tag state: whether we're between < and >
   let htmlInsideTag = false;
 
+  // JSX expression depth: how many `pl-pse` `{` braces are currently open.
+  // Identifiers (`pl-smi`, `pl-v`) inside an expression are tagged as JSX variables.
+  let jsxExpressionDepth = 0;
+
   // Whether a span appeared between the last text node and the current position.
   // Used to detect attribute context for = wrapping (replaces backward scanning).
   let hasSpanSinceLastText = false;
+
+  // Template-literal interpolation state, carried across the per-line `pl-s` spans
+  // of one multi-line literal. `null` when not inside a template-literal run.
+  let templateRun = null;
   for (let index = 0; index < children.length; index += 1) {
     const child = children[index];
 
@@ -238,56 +578,91 @@ function enhanceChildren(children, isCss, isHtmlJsx, isJs, isTs, isJsx) {
         }
       }
 
-      // HTML/JSX: track < > tag boundaries and wrap bare = in attribute context
+      // HTML/JSX: track < > tag boundaries and wrap bare = in attribute context.
+      // A trailing `<` (next sibling = element) only enters tag mode when the next
+      // element looks like a JSX tag — `pl-ent` (HTML element) or `pl-c1` whose text
+      // isn't a TS built-in primitive. This avoids treating TS generics like
+      // `useState<number | null>` or `<T = string>` as JSX tags.
       if (isHtmlJsx) {
         for (let ci = 0; ci < value.length; ci += 1) {
           if (value[ci] === '<') {
-            htmlInsideTag = true;
+            if (ci === value.length - 1) {
+              const nextChild = children[index + 1];
+              if (isJsx && nextChild && nextChild.type === 'element' && nextChild.tagName === 'span') {
+                const nextClass = getFirstClass(nextChild);
+                if (nextClass === 'pl-ent') {
+                  htmlInsideTag = true;
+                } else if (nextClass === 'pl-c1') {
+                  const nextText = getShallowTextContent(nextChild);
+                  if (nextText && !BUILT_IN_TYPES.has(nextText)) {
+                    htmlInsideTag = true;
+                  }
+                }
+              } else {
+                htmlInsideTag = true;
+              }
+            } else {
+              htmlInsideTag = true;
+            }
           } else if (value[ci] === '>') {
             htmlInsideTag = false;
           }
         }
-        if (htmlInsideTag && savedSpanFlag) {
-          const equalsIndex = value.indexOf('=');
-          if (equalsIndex !== -1) {
-            // Tag the following pl-s span as attribute value
-            const nextChild = children[index + 1];
-            if (nextChild && nextChild.type === 'element' && nextChild.tagName === 'span' && getFirstClass(nextChild) === 'pl-s') {
-              addClass(nextChild, 'di-av');
-            }
+      }
 
-            // Split text around = and wrap in di-ae span
-            const before = value.slice(0, equalsIndex);
-            const after = value.slice(equalsIndex + 1);
-            const equalsSpan = {
-              type: 'element',
-              tagName: 'span',
-              properties: {
-                className: ['di-ae']
-              },
-              children: [{
-                type: 'text',
-                value: '='
-              }]
-            };
-            const newNodes = [];
-            if (before) {
-              newNodes.push({
-                type: 'text',
-                value: before
-              });
-            }
-            newNodes.push(equalsSpan);
-            if (after) {
-              newNodes.push({
-                type: 'text',
-                value: after
-              });
-            }
-            children.splice(index, 1, ...newNodes);
-            index += newNodes.length - 1;
-            hasSpanSinceLastText = newNodes[newNodes.length - 1].type === 'element';
+      // Bare object-literal keys (e.g. `height` in `{ height: 400 }`) become di-op spans.
+      // Inside a JSX attribute expression they also receive di-jv. Done before the `=` split
+      // below, which only fires in attribute context (htmlInsideTag) — the two paths don't conflict.
+      // Children expressions (e.g. `<Comp>{children}</Comp>`) are excluded by the htmlInsideTag check.
+      if (isJs) {
+        const split = splitObjectKeys(value, isJsx && jsxExpressionDepth > 0 && htmlInsideTag);
+        if (split) {
+          children.splice(index, 1, ...split);
+          index += split.length - 1;
+          hasSpanSinceLastText = split[split.length - 1].type === 'element';
+          continue;
+        }
+      }
+      if (isHtmlJsx && htmlInsideTag && savedSpanFlag) {
+        const equalsIndex = value.indexOf('=');
+        if (equalsIndex !== -1) {
+          // Tag the following pl-s span as attribute value
+          const nextChild = children[index + 1];
+          if (nextChild && nextChild.type === 'element' && nextChild.tagName === 'span' && getFirstClass(nextChild) === 'pl-s') {
+            addClass(nextChild, 'di-av');
+          }
+
+          // Split text around = and wrap in di-ae span
+          const before = value.slice(0, equalsIndex);
+          const after = value.slice(equalsIndex + 1);
+          const equalsSpan = {
+            type: 'element',
+            tagName: 'span',
+            properties: {
+              className: ['di-ae']
+            },
+            children: [{
+              type: 'text',
+              value: '='
+            }]
+          };
+          const newNodes = [];
+          if (before) {
+            newNodes.push({
+              type: 'text',
+              value: before
+            });
+          }
+          newNodes.push(equalsSpan);
+          if (after) {
+            newNodes.push({
+              type: 'text',
+              value: after
+            });
           }
+          children.splice(index, 1, ...newNodes);
+          index += newNodes.length - 1;
+          hasSpanSinceLastText = newNodes[newNodes.length - 1].type === 'element';
         }
       }
       continue;
@@ -298,6 +673,34 @@ function enhanceChildren(children, isCss, isHtmlJsx, isJs, isTs, isJsx) {
       continue;
     }
 
+    // ── Template-literal interpolation (JS family) ──
+    // starry-night tokenizes a backtick string as a `pl-s` span (one per line for
+    // multi-line literals). Wrap each `${ ... }` slice in a `di-te` region with
+    // `di-td` delimiters so the interpolated expression resets from the string
+    // color. `templateRun` carries the brace/nesting state across the per-line
+    // `pl-s` spans; a run starts on the line whose first child is the opening
+    // backtick. Handled here, before the generic recursion, so the expression
+    // tokens are enhanced inside their regions and the outer `pl-s` is skipped.
+    if (isJs && child.tagName === 'span' && getFirstClass(child) === 'pl-s') {
+      const opensRun = templateRun === null && isBacktickDelimiter(child.children[0]);
+      if (templateRun !== null || opensRun) {
+        templateRun = restructureTemplateLine(child, templateRun ?? [{
+          mode: 'string'
+        }], opensRun);
+        // Empty backtick literals (`` `` ``) keep their nullish (`di-n`) classification.
+        enhanceStringSpan(child);
+        // Enhance the interpolated expressions (e.g. `di-num` on `${42}`) within
+        // each region; nested regions are reached by the recursion.
+        for (const region of child.children) {
+          if (region.type === 'element' && getFirstClass(region) === 'di-te') {
+            enhanceChildren(region.children, isCss, isHtmlJsx, isJs, isTs, isJsx);
+          }
+        }
+        hasSpanSinceLastText = true;
+        continue;
+      }
+    }
+
     // Recurse into nested elements (frames, lines, nested spans)
     if (child.children.length > 0) {
       enhanceChildren(child.children, isCss, isHtmlJsx, isJs, isTs, isJsx);
@@ -314,6 +717,56 @@ function enhanceChildren(children, isCss, isHtmlJsx, isJs, isTs, isJsx) {
       enhanceConstantSpan(child, isJs, isTs);
     } else if (firstClass === 'pl-s') {
       enhanceStringSpan(child);
+    } else if (firstClass === 'pl-k') {
+      const text = getShallowTextContent(child);
+      if (text && isSymbolicPunctuation(text)) {
+        addClass(child, 'di-pu');
+      }
+    }
+
+    // ── JSX expression brace tracking ──
+    if (isJsx && firstClass === 'pl-pse') {
+      const text = getShallowTextContent(child);
+      if (text === '{') {
+        jsxExpressionDepth += 1;
+      } else if (text === '}' && jsxExpressionDepth > 0) {
+        jsxExpressionDepth -= 1;
+      }
+    }
+
+    // ── JSX variable: identifier-like spans inside an attribute expression ──
+    // - `pl-smi` plain identifier (e.g. `row` in `{row.name}`)
+    // - `pl-v` parameter / variable (e.g. arrow function params)
+    // - `pl-c1` after a `.` text node — member-access property (e.g. `name` in `{row.name}`).
+    //   Skips numbers/booleans/nullish (which `enhanceConstantSpan` has already classified)
+    //   and JSX components (handled below by the `<`/`</` detection).
+    //
+    // Restricted to attribute context (`htmlInsideTag`) so children expressions like
+    // `<Comp>{children}</Comp>` are not tagged.
+    if (isJsx && jsxExpressionDepth > 0 && htmlInsideTag) {
+      if (firstClass === 'pl-smi' || firstClass === 'pl-v') {
+        addClass(child, 'di-jv');
+      } else if (firstClass === 'pl-c1' && index > 0) {
+        const prev = children[index - 1];
+        if (prev.type === 'text' && prev.value.endsWith('.')) {
+          addClass(child, 'di-jv');
+        }
+      }
+    }
+
+    // ── JS object property string: pl-s followed by text starting with `:` ──
+    // String keys (e.g. `'aria-label': value`) get the dedicated `di-op` class plus
+    // `di-ps` for the string-shape detail. Inside JSX expressions, also add `di-jv`
+    // so themes that style JSX variables can include string keys.
+    if (isJs && firstClass === 'pl-s') {
+      const next = children[index + 1];
+      if (next && next.type === 'text' && startsWithColon(next.value)) {
+        addClass(child, 'di-op');
+        addClass(child, 'di-ps');
+        if (isJsx && jsxExpressionDepth > 0 && htmlInsideTag) {
+          addClass(child, 'di-jv');
+        }
+      }
     }
 
     // ── CSS-specific enhancements ──
@@ -353,10 +806,15 @@ function enhanceChildren(children, isCss, isHtmlJsx, isJs, isTs, isJsx) {
     if (isJsx && index > 0) {
       const prev = children[index - 1];
 
-      // Opening/closing: text ending in < or </ followed by pl-c1
+      // Opening/closing: text ending in < or </ followed by pl-c1.
+      // Skip TS built-in types (e.g. `number` in `useState<number>`) so generic
+      // type arguments aren't mistaken for JSX components.
       if (firstClass === 'pl-c1' && prev.type === 'text') {
         if (prev.value.endsWith('<') || prev.value.endsWith('</')) {
-          addClass(child, 'di-jsx');
+          const text = getShallowTextContent(child);
+          if (!text || !BUILT_IN_TYPES.has(text)) {
+            addClass(child, 'di-jsx');
+          }
         }
       }
 

package/pipeline/transformHtmlCodeInline/removeSuffixFromHighlightedNodes.d.mts

@@ -0,0 +1,12 @@
+import type { ElementContent } from 'hast';
+/**
+ * Removes a suffix from the end of highlighted HAST nodes.
+ *
+ * Mirror of `removePrefixFromHighlightedNodes`: used to strip temporary
+ * trailing characters that were appended to the source before highlighting
+ * (e.g., closing `)` for object-literal wrapping).
+ *
+ * @param children - The array of HAST nodes to modify
+ * @param suffixLength - The number of characters to remove from the end
+ */
+export declare function removeSuffixFromHighlightedNodes(children: ElementContent[], suffixLength: number): void;

package/pipeline/transformHtmlCodeInline/removeSuffixFromHighlightedNodes.mjs

@@ -0,0 +1,52 @@
+/**
+ * Removes a suffix from the end of highlighted HAST nodes.
+ *
+ * Mirror of `removePrefixFromHighlightedNodes`: used to strip temporary
+ * trailing characters that were appended to the source before highlighting
+ * (e.g., closing `)` for object-literal wrapping).
+ *
+ * @param children - The array of HAST nodes to modify
+ * @param suffixLength - The number of characters to remove from the end
+ */
+export function removeSuffixFromHighlightedNodes(children, suffixLength) {
+  let removedLength = 0;
+  while (removedLength < suffixLength && children.length > 0) {
+    const lastChild = children[children.length - 1];
+    if (lastChild.type === 'text') {
+      const textLength = lastChild.value.length;
+      if (removedLength + textLength <= suffixLength) {
+        children.pop();
+        removedLength += textLength;
+      } else {
+        const charsToRemove = suffixLength - removedLength;
+        lastChild.value = lastChild.value.slice(0, textLength - charsToRemove);
+        removedLength = suffixLength;
+      }
+    } else if (lastChild.type === 'element') {
+      const element = lastChild;
+      if (element.children && element.children.length > 0) {
+        const lastElementChild = element.children[element.children.length - 1];
+        if (lastElementChild.type === 'text') {
+          const textLength = lastElementChild.value.length;
+          if (removedLength + textLength <= suffixLength) {
+            element.children.pop();
+            removedLength += textLength;
+            if (element.children.length === 0) {
+              children.pop();
+            }
+          } else {
+            const charsToRemove = suffixLength - removedLength;
+            lastElementChild.value = lastElementChild.value.slice(0, textLength - charsToRemove);
+            removedLength = suffixLength;
+          }
+        } else {
+          break;
+        }
+      } else {
+        children.pop();
+      }
+    } else {
+      break;
+    }
+  }
+}

package/pipeline/transformHtmlCodeInline/transformHtmlCodeInline.mjs

@@ -3,8 +3,10 @@ import { visit } from 'unist-util-visit';
 import { grammars } from "../parseSource/grammars.mjs";
 import { extensionMap } from "../parseSource/grammarMaps.mjs";
 import { extendSyntaxTokens } from "../parseSource/extendSyntaxTokens.mjs";
+import { getLanguageCapabilitiesFromScope } from "../parseSource/languageCapabilities.mjs";
 import { getHastTextContent } from "../hastUtils/index.mjs";
 import { removePrefixFromHighlightedNodes } from "./removePrefixFromHighlightedNodes.mjs";
+import { removeSuffixFromHighlightedNodes } from "./removeSuffixFromHighlightedNodes.mjs";
 const STARRY_NIGHT_KEY = '__docs_infra_starry_night_instance__';
 
 /**
@@ -67,7 +69,14 @@ export default function transformHtmlCodeInline(options = {}) {
       const highlightingPrefix = typeof node.properties?.dataHighlightingPrefix === 'string' ? node.properties.dataHighlightingPrefix : undefined;
 
       // Temporarily prepend the prefix for proper syntax highlighting
-      const sourceToHighlight = highlightingPrefix ? `${highlightingPrefix}${source}` : source;
+      let sourceToHighlight = highlightingPrefix ? `${highlightingPrefix}${source}` : source;
+
+      // Inline JS-family snippets that look like a bare object literal (e.g. `{ height: 400 }`)
+      // are tokenized by starry-night as a block statement with labeled statements, which makes
+      // the keys appear as `pl-en` (entity name) tokens rather than property names. Wrap them
+      // in `(...)` so the snippet parses as an expression and `extendSyntaxTokens` can split
+      // out the keys via `splitObjectKeys`. The wrapping characters are stripped after highlighting.
+      let objectWrap = false;
 
       // Determine language from className (e.g., 'language-ts')
       const className = node.properties?.className;
@@ -103,6 +112,14 @@ export default function transformHtmlCodeInline(options = {}) {
       if (!fileType || !extensionMap[fileType]) {
         return;
       }
+      const grammarScope = extensionMap[fileType];
+      if (!highlightingPrefix && getLanguageCapabilitiesFromScope(grammarScope).semantics === 'js') {
+        const trimmed = sourceToHighlight.trim();
+        if (trimmed.length >= 2 && trimmed.startsWith('{') && trimmed.endsWith('}')) {
+          sourceToHighlight = `(${sourceToHighlight})`;
+          objectWrap = true;
+        }
+      }
 
       // Apply syntax highlighting
       const highlighted = starryNight.highlight(sourceToHighlight, extensionMap[fileType]);
@@ -116,6 +133,10 @@ export default function transformHtmlCodeInline(options = {}) {
         if (highlightingPrefix && node.children.length > 0) {
           removePrefixFromHighlightedNodes(node.children, highlightingPrefix.length);
         }
+        if (objectWrap && node.children.length > 0) {
+          removePrefixFromHighlightedNodes(node.children, 1);
+          removeSuffixFromHighlightedNodes(node.children, 1);
+        }
       }
 
       // Mark this code element as inline highlighted (only for inline code, not pre>code)

package/useCode/EditableEngine.mjs

@@ -1146,12 +1146,19 @@ export const createEditableEngine = ctx => {
           state.repeatFlushId = null;
           // The user may have moved focus or cleared the selection in the
           // 100ms since the last repeat keydown (e.g. clicked elsewhere,
-          // unmounted, blurred). The debounced flush is best-effort; if
-          // there's no live selection inside the editable any more, skip
-          // — the next real event will pick up state. Without this guard
-          // `getPosition` throws from a stray timer after teardown.
+          // unmounted, blurred). The debounced flush is best-effort; if the
+          // engine is gone or there's no live selection inside the editable
+          // any more, skip — the next real event will pick up state.
+          //
+          // Bail out before touching `window`: a stray timer can fire after
+          // teardown, and in a test environment the `window` global may already
+          // be removed, so `window.getSelection()` would throw a `ReferenceError`
+          // (an unhandled rejection that can mask real failures).
+          if (state.disconnected || typeof window === 'undefined') {
+            return;
+          }
           const selection = window.getSelection();
-          if (state.disconnected || !selection || selection.rangeCount === 0 || !element.contains(selection.getRangeAt(0).startContainer)) {
+          if (!selection || selection.rangeCount === 0 || !element.contains(selection.getRangeAt(0).startContainer)) {
             return;
           }
           flushChanges();

package/useCodeWindow/useCodeWindow.d.mts

@@ -48,6 +48,14 @@ export type UseCodeWindowResult<ToggleElement extends HTMLElement = HTMLElement,
    * so the anchor stays put against the panel's own scroll rather than the
    * page. When left unattached, the page is compensated — the right default
    * for code that grows the document flow. Forwarded from `useScrollAnchor`.
+   *
+   * When attached, this element is also treated as the horizontal scroll
+   * owner: the scrollbar-gutter swap (`data-scrollbar-gutter`) and the
+   * collapse scroll-back run on it instead of the inner `<pre>`. Use this when
+   * the window owns both scroll axes so the horizontal scrollbar sits at the
+   * window's edge (in view) rather than at the bottom of the inner `<pre>`,
+   * which can extend past the window's height and scroll out of view. Your
+   * gutter CSS must then key off this element's attribute.
    */
   scrollContainerRef: React.RefObject<ScrollElement | null>;
   /**

package/useCodeWindow/useCodeWindow.mjs

@@ -53,33 +53,38 @@ function cancelScheduled(handle) {
  * Smoothly slides the `<code>` element back to the left edge over `duration`
  * ms using an ease-out cubic via the Web Animations API.
  *
- * Used during collapse instead of tweening `pre.scrollLeft` because the
- * scrollbar-gutter animation forces `overflow-x: hidden` on the pre, which
+ * `scrollEl` is whichever element owns the horizontal scroll — the inner
+ * `<pre>` by default, or an attached scroll container (see `scrollContainerRef`)
+ * when the code block is rendered inside a fixed-size window. `code` is this
+ * code window's own `<code>` (scoped to its container by the caller) so a shared
+ * scroll container holding several blocks animates the right one.
+ *
+ * Used during collapse instead of tweening `scrollEl.scrollLeft` because the
+ * scrollbar-gutter animation forces `overflow-x: hidden` on `scrollEl`, which
  * snaps `scrollLeft` to 0 instantly. Animating a transform on the inner
  * `code` element produces the same visual effect, isn't reset by the overflow
- * change, and is naturally clipped by the pre's hidden overflow.
+ * change, and is naturally clipped by the scroll element's hidden overflow.
  *
  * Honors `prefers-reduced-motion` by snapping immediately.
  */
-function smoothCollapseScrollLeft(pre, duration) {
-  const startLeft = pre.scrollLeft;
+function smoothCollapseScrollLeft(scrollEl, code, duration) {
+  const startLeft = scrollEl.scrollLeft;
   if (startLeft <= 0) {
     return null;
   }
-  const code = pre.querySelector('code');
-  if (!code || typeof code.animate !== 'function') {
-    return null;
-  }
 
   // Cancel any leftover scroll-back animation from a previous toggle so we
   // don't end up with two transforms competing on the same element.
-  scrollbackAnimations.get(pre)?.cancel();
-  scrollbackAnimations.delete(pre);
+  scrollbackAnimations.get(scrollEl)?.cancel();
+  scrollbackAnimations.delete(scrollEl);
 
-  // Reset the actual scroll position now; the WAAPI animation visually
-  // compensates by translating the element from `-startLeft` back to `0`.
-  pre.scrollLeft = 0;
-  if (prefersReducedMotion() || duration <= 0) {
+  // Snap the actual scroll position back to the left edge now. When we can
+  // animate, the WAAPI transform below visually compensates by translating the
+  // element from `-startLeft` back to `0`; otherwise (no WAAPI, no `code`,
+  // reduced motion, or zero duration) this stands as an instant snap — still
+  // the correct collapsed end state.
+  scrollEl.scrollLeft = 0;
+  if (!code || typeof code.animate !== 'function' || prefersReducedMotion() || duration <= 0) {
     return null;
   }
   const anim = code.animate([{
@@ -91,10 +96,10 @@ function smoothCollapseScrollLeft(pre, duration) {
     easing: 'cubic-bezier(0, 0, 0.2, 1)',
     fill: 'none'
   });
-  scrollbackAnimations.set(pre, anim);
+  scrollbackAnimations.set(scrollEl, anim);
   const onSettle = () => {
-    if (scrollbackAnimations.get(pre) === anim) {
-      scrollbackAnimations.delete(pre);
+    if (scrollbackAnimations.get(scrollEl) === anim) {
+      scrollbackAnimations.delete(scrollEl);
     }
   };
   anim.finished.then(onSettle, onSettle);
@@ -106,74 +111,76 @@ function isElementInViewport(element) {
 }
 
 /**
- * Measures the horizontal scrollbar height of a `<pre>` element by
+ * Measures the horizontal scrollbar height of the scroll element by
  * temporarily forcing `overflow-x: scroll`.
  */
-function measureScrollbarHeight(pre) {
-  const prevOverflow = pre.style.overflowX;
-  pre.style.overflowX = 'scroll';
-  const scrollbarHeight = pre.offsetHeight - pre.clientHeight;
-  pre.style.overflowX = prevOverflow;
+function measureScrollbarHeight(scrollEl) {
+  const prevOverflow = scrollEl.style.overflowX;
+  scrollEl.style.overflowX = 'scroll';
+  const scrollbarHeight = scrollEl.offsetHeight - scrollEl.clientHeight;
+  scrollEl.style.overflowX = prevOverflow;
   return scrollbarHeight;
 }
-function clearGutterState(pre) {
-  cancelScheduled(gutterCleanupTimers.get(pre));
-  gutterCleanupTimers.delete(pre);
-  const flipTimer = gutterFlipTimers.get(pre);
+function clearGutterState(scrollEl) {
+  cancelScheduled(gutterCleanupTimers.get(scrollEl));
+  gutterCleanupTimers.delete(scrollEl);
+  const flipTimer = gutterFlipTimers.get(scrollEl);
   if (flipTimer !== undefined) {
     clearTimeout(flipTimer);
-    gutterFlipTimers.delete(pre);
+    gutterFlipTimers.delete(scrollEl);
   }
-  pre.removeAttribute(GUTTER_STATE_ATTRIBUTE);
+  scrollEl.removeAttribute(GUTTER_STATE_ATTRIBUTE);
 }
-function cancelAllForPre(pre) {
-  scrollbackAnimations.get(pre)?.cancel();
-  scrollbackAnimations.delete(pre);
-  clearGutterState(pre);
+function cancelAllForScrollEl(scrollEl) {
+  scrollbackAnimations.get(scrollEl)?.cancel();
+  scrollbackAnimations.delete(scrollEl);
+  clearGutterState(scrollEl);
 }
 
 /**
  * Drives a from→to transition on the `data-scrollbar-gutter` attribute of
- * `pre`, which the consumer's CSS hooks into to animate the swap between
- * a real scrollbar and equivalent padding-bottom.
+ * the scroll element, which the consumer's CSS hooks into to animate the swap
+ * between a real scrollbar and equivalent padding-bottom.
+ *
+ * `scrollEl` is whichever element owns the horizontal scroll — the inner
+ * `<pre>` by default, or the attached `scrollContainerRef` when the code block
+ * is rendered inside a fixed-size window. `code` is this code window's own
+ * `<code>` (scoped to its container by the caller).
  *
  * Skips the animation when content doesn't overflow (no scrollbar exists)
  * or when the browser uses overlay scrollbars (zero height).
  */
-function animateScrollbarGutter(pre, from, to, durationMs) {
-  const scrollbarHeight = measureScrollbarHeight(pre);
+function animateScrollbarGutter(scrollEl, code, from, to, durationMs) {
+  const scrollbarHeight = measureScrollbarHeight(scrollEl);
   if (scrollbarHeight === 0) {
     return; // Overlay scrollbars, nothing to do
   }
 
-  // For expand, check the inner code's scrollWidth (since `min-width:
-  // fit-content` reflects hidden frames). For collapse, the pre's own
-  // scrollWidth is enough.
-  if (from === 'expand-from') {
-    const code = pre.querySelector('code');
-    if (code && code.scrollWidth <= pre.clientWidth) {
-      return;
-    }
-  } else if (pre.scrollWidth <= pre.clientWidth) {
+  // Decide from this code window's own `<code>`, not from `scrollEl` — the
+  // scroll owner may be a shared container wrapping other content. `code`'s
+  // `scrollWidth` reflects hidden frames (via `min-width: fit-content`), so it
+  // predicts the post-expand width and still reflects the wide source during
+  // collapse; compare it against the scroll owner's visible width.
+  if (!code || code.scrollWidth <= scrollEl.clientWidth) {
     return;
   }
-  clearGutterState(pre);
-  pre.setAttribute(GUTTER_STATE_ATTRIBUTE, from);
+  clearGutterState(scrollEl);
+  scrollEl.setAttribute(GUTTER_STATE_ATTRIBUTE, from);
 
   // Move into the transition state on the next macrotask. Tracked so the
   // flip can be cancelled if the component unmounts before it fires.
   const flipTimer = setTimeout(() => {
-    gutterFlipTimers.delete(pre);
-    pre.setAttribute(GUTTER_STATE_ATTRIBUTE, to);
+    gutterFlipTimers.delete(scrollEl);
+    scrollEl.setAttribute(GUTTER_STATE_ATTRIBUTE, to);
   }, 0);
-  gutterFlipTimers.set(pre, flipTimer);
+  gutterFlipTimers.set(scrollEl, flipTimer);
 
   // Schedule cleanup on the animation timeline so DevTools throttling
   // scales it together with the CSS transition.
-  const cleanup = scheduleOnAnimationTimeline(pre, durationMs + 30, () => {
-    clearGutterState(pre);
+  const cleanup = scheduleOnAnimationTimeline(scrollEl, durationMs + 30, () => {
+    clearGutterState(scrollEl);
   });
-  gutterCleanupTimers.set(pre, cleanup);
+  gutterCleanupTimers.set(scrollEl, cleanup);
 }
 const DEFAULT_ANCHOR_SELECTOR = '[data-frame-type="highlighted"], [data-frame-type="focus"]';
 const DEFAULT_COLLAPSIBLE_SELECTOR = '[data-collapsible]';
@@ -218,7 +225,7 @@ export function useCodeWindow(options = {}) {
     collapsibleProbeSelector = DEFAULT_COLLAPSIBLE_SELECTOR
   } = options;
   const toggleRef = React.useRef(null);
-  const lastPreRef = React.useRef(null);
+  const lastScrollElRef = React.useRef(null);
   const {
     containerRef,
     scrollContainerRef,
@@ -226,10 +233,10 @@ export function useCodeWindow(options = {}) {
   } = useScrollAnchor();
   React.useEffect(() => {
     return () => {
-      const pre = lastPreRef.current;
-      if (pre) {
-        cancelAllForPre(pre);
-        lastPreRef.current = null;
+      const scrollEl = lastScrollElRef.current;
+      if (scrollEl) {
+        cancelAllForScrollEl(scrollEl);
+        lastScrollElRef.current = null;
       }
     };
   }, []);
@@ -247,32 +254,42 @@ export function useCodeWindow(options = {}) {
     if (!anchor) {
       return;
     }
-    const pre = container.querySelector('pre');
-    if (pre) {
-      lastPreRef.current = pre;
+
+    // The element whose horizontal scrollbar we smooth: the attached scroll
+    // container when one is provided (the code block lives inside a
+    // fixed-size window that owns both scroll axes), otherwise the inner
+    // `<pre>`, which scrolls horizontally on its own.
+    const scrollEl = scrollContainerRef.current ?? container.querySelector('pre');
+    // Scope content lookups to *this* code window's `container`, never to
+    // `scrollEl`: an attached scroll container may wrap several code blocks or
+    // unrelated content, so `scrollEl.querySelector('code')` could match the
+    // wrong block. The overflow decision and scroll-back both use this code.
+    const code = container.querySelector('code');
+    if (scrollEl) {
+      lastScrollElRef.current = scrollEl;
       if (direction === 'collapse') {
         // Smoothly return horizontal scroll to the left edge. We animate
         // via a transform on the inner `code` element rather than
-        // tweening `pre.scrollLeft`, because the gutter animation below
+        // tweening `scrollEl.scrollLeft`, because the gutter animation below
         // sets `overflow-x: hidden` which would snap `scrollLeft` to 0
         // instantly. Both animations start in the same frame: the
         // scroll-back resets `scrollLeft` to 0 up front, so the gutter
         // swap's `overflow-x` change has nothing left to snap.
-        smoothCollapseScrollLeft(pre, scrollBackDuration);
-        animateScrollbarGutter(pre, 'collapse-from', 'collapse-to', collapseDuration);
+        smoothCollapseScrollLeft(scrollEl, code, scrollBackDuration);
+        animateScrollbarGutter(scrollEl, code, 'collapse-from', 'collapse-to', collapseDuration);
       }
       if (direction === 'expand') {
         // Cancel any in-flight collapse scroll-back so its leftover
         // transform can't drift the code horizontally during expand.
-        scrollbackAnimations.get(pre)?.cancel();
-        scrollbackAnimations.delete(pre);
-        if (collapsibleProbeSelector && pre.querySelector(collapsibleProbeSelector)) {
-          animateScrollbarGutter(pre, 'expand-from', 'expand-to', expandDuration);
+        scrollbackAnimations.get(scrollEl)?.cancel();
+        scrollbackAnimations.delete(scrollEl);
+        if (collapsibleProbeSelector && container.querySelector(collapsibleProbeSelector)) {
+          animateScrollbarGutter(scrollEl, code, 'expand-from', 'expand-to', expandDuration);
         }
       }
     }
     rawAnchorScroll(anchor, direction === 'collapse' ? collapseDuration : expandDuration);
-  }, [containerRef, rawAnchorScroll, anchorSelector, collapsibleProbeSelector, collapseDuration, expandDuration, scrollBackDuration]);
+  }, [containerRef, scrollContainerRef, rawAnchorScroll, anchorSelector, collapsibleProbeSelector, collapseDuration, expandDuration, scrollBackDuration]);
   return {
     containerRef,
     scrollContainerRef,

package/useScrollAnchor/useScrollAnchor.mjs

@@ -42,10 +42,16 @@ export function useScrollAnchor() {
     activeSessionCleanupRef.current = null;
 
     // Snapshot the scroll target at session start so a later ref change
-    // doesn't redirect compensation mid-flight.
-    const scrollTarget = scrollContainerRef.current ?? window;
+    // doesn't redirect compensation mid-flight. `scrollElement` is the attached
+    // container (if any); `scrollTarget` is what receives the user-interaction
+    // listeners (the container or the window).
+    const scrollElement = scrollContainerRef.current;
+    const scrollTarget = scrollElement ?? window;
     const interactionTarget = scrollTarget;
-    const initialTop = anchor.getBoundingClientRect().top;
+
+    // Mutable so it can be re-baselined when an attached container can't yet
+    // absorb a delta (see below).
+    let initialTop = anchor.getBoundingClientRect().top;
     let active = true;
     let cleanupTimer;
 
@@ -58,8 +64,25 @@ export function useScrollAnchor() {
         return;
       }
       const delta = anchor.getBoundingClientRect().top - initialTop;
-      if (Math.abs(delta) > 0.5) {
-        scrollTarget.scrollBy(0, delta);
+      if (Math.abs(delta) <= 0.5) {
+        return;
+      }
+      if (!scrollElement) {
+        window.scrollBy(0, delta);
+        return;
+      }
+      const before = scrollElement.scrollTop;
+      scrollElement.scrollBy(0, delta);
+      const remainder = delta - (scrollElement.scrollTop - before);
+      if (Math.abs(remainder) > 0.5) {
+        // The container couldn't absorb this part — it isn't scrollable yet
+        // (its content hasn't exceeded its `max-height`). Re-baseline instead
+        // of forcing the difference elsewhere: scrolling the page would shift
+        // the surrounding layout, and carrying the delta forward would snap the
+        // anchor back the instant the container becomes scrollable. Accepting
+        // the small drift now keeps the surrounding layout still and lets the
+        // container hold the anchor smoothly from here on.
+        initialTop += remainder;
       }
     });
     function cleanup() {