Skip to content

An open source design system that's fully customizable and agent ready

TypeScript

fix(CodeBlock): syntax highlighting missing on scroll + perf improvements (#1221)

Cindy Zhang4756b4119477
diff --git a/apps/sandbox/package.json b/apps/sandbox/package.json
index 99819d3838..0450d61244 100644
--- a/apps/sandbox/package.json
+++ b/apps/sandbox/package.json
@@ -3,6 +3,7 @@
"version": "0.0.1",
"private": true,
"scripts": {
+ "build:deps": "yarn workspace @xds/core build && yarn workspace @xds/theme-default build && yarn workspace @xds/theme-neutral build && yarn workspace @xds/theme-brutalist build && yarn workspace @xds/theme-meta build && yarn workspace @xds/theme-whatsapp build && yarn workspace @xds/theme-daily build",
"predev": "node ../../scripts/sync-templates.js",
"dev": "next dev",
"prebuild": "node ../../scripts/sync-templates.js",
diff --git a/apps/sandbox/src/app/(fullscreen)/pages/codeblock-perf/page.tsx b/apps/sandbox/src/app/(fullscreen)/pages/codeblock-perf/page.tsx
new file mode 100644
index 0000000000..bda7c23d40
--- /dev/null
+++ b/apps/sandbox/src/app/(fullscreen)/pages/codeblock-perf/page.tsx
@@ -0,0 +1,363 @@
+'use client';
+
+import * as React from 'react';
+import {useState, useCallback, useRef, useEffect} from 'react';
+import {XDSCodeBlock} from '@xds/core/CodeBlock';
+import {XDSText, XDSHeading} from '@xds/core/Text';
+import {XDSHStack, XDSVStack} from '@xds/core/Stack';
+import {XDSButton} from '@xds/core/Button';
+import {XDSBadge} from '@xds/core/Badge';
+import {XDSCard} from '@xds/core/Card';
+import {XDSAppShell} from '@xds/core/AppShell';
+import {XDSSection} from '@xds/core/Section';
+import {XDSGrid} from '@xds/core/Grid';
+import {
+ XDSSegmentedControl,
+ XDSSegmentedControlItem,
+} from '@xds/core/SegmentedControl';
+
+// ---------------------------------------------------------------------------
+// Code generation
+// ---------------------------------------------------------------------------
+
+function generateCode(lines: number): string {
+ const parts: string[] = [
+ "import {useState, useEffect, useCallback, useMemo, useRef} from 'react';",
+ "import type {ReactNode, CSSProperties} from 'react';",
+ '',
+ '// Auto-generated stress test code',
+ `// ${lines} lines of TypeScript`,
+ '',
+ ];
+
+ for (let i = 0; i < lines - 6; i++) {
+ const mod = i % 12;
+ switch (mod) {
+ case 0:
+ parts.push(`interface Model${i} {`);
+ break;
+ case 1:
+ parts.push(` id: string;`);
+ break;
+ case 2:
+ parts.push(` value: number;`);
+ break;
+ case 3:
+ parts.push(`}`);
+ break;
+ case 4:
+ parts.push('');
+ break;
+ case 5:
+ parts.push(
+ `async function fetch${i}(url: string): Promise<Model${i - 5}> {`,
+ );
+ break;
+ case 6:
+ parts.push(` const response = await fetch(url);`);
+ break;
+ case 7:
+ parts.push(
+ ` if (!response.ok) throw new Error("HTTP " + response.status);`,
+ );
+ break;
+ case 8:
+ parts.push(` return response.json(); // line ${i}`);
+ break;
+ case 9:
+ parts.push(`}`);
+ break;
+ case 10:
+ parts.push('');
+ break;
+ case 11:
+ parts.push(`// Section ${Math.floor(i / 12) + 1}`);
+ break;
+ }
+ }
+ return parts.join('\n');
+}
+
+// ---------------------------------------------------------------------------
+// Perf measurement
+// ---------------------------------------------------------------------------
+
+interface PerfMetrics {
+ mountMs: number | null;
+ renderCount: number;
+ lastRenderMs: number | null;
+ scrollFps: number | null;
+ scrollFrameDrops: number;
+}
+
+function usePerfMetrics() {
+ const [metrics, setMetrics] = useState<PerfMetrics>({
+ mountMs: null,
+ renderCount: 0,
+ lastRenderMs: null,
+ scrollFps: null,
+ scrollFrameDrops: 0,
+ });
+
+ const mountStart = useRef(performance.now());
+ const renderCount = useRef(0);
+
+ renderCount.current += 1;
+
+ useEffect(() => {
+ const elapsed = performance.now() - mountStart.current;
+ setMetrics({
+ mountMs: elapsed,
+ renderCount: renderCount.current,
+ lastRenderMs: elapsed,
+ scrollFps: null,
+ scrollFrameDrops: 0,
+ });
+ }, []);
+
+ const scrollRef = useRef<HTMLDivElement>(null);
+ const scrollState = useRef({
+ frames: 0,
+ drops: 0,
+ startTime: 0,
+ rafId: 0,
+ measuring: false,
+ lastFrameTime: 0,
+ });
+
+ const runScrollTest = useCallback(() => {
+ const el = scrollRef.current;
+ if (!el) return;
+
+ const scrollContainer =
+ el.querySelector<HTMLElement>('[style*="max-height"]') ??
+ el.querySelector<HTMLElement>('pre');
+ if (!scrollContainer) return;
+
+ scrollContainer.scrollTop = 0;
+ const s = scrollState.current;
+ s.frames = 0;
+ s.drops = 0;
+ s.startTime = performance.now();
+ s.measuring = true;
+ s.lastFrameTime = performance.now();
+
+ function tick() {
+ if (!s.measuring) return;
+ const now = performance.now();
+ s.frames++;
+ if (now - s.lastFrameTime > 20) s.drops++;
+ s.lastFrameTime = now;
+ s.rafId = requestAnimationFrame(tick);
+ }
+ s.rafId = requestAnimationFrame(tick);
+
+ const totalScroll =
+ scrollContainer.scrollHeight - scrollContainer.clientHeight;
+ const duration = 2000;
+ const start = performance.now();
+
+ function step() {
+ const elapsed = performance.now() - start;
+ const progress = Math.min(elapsed / duration, 1);
+ const eased = 1 - Math.pow(1 - progress, 3);
+ scrollContainer!.scrollTop = totalScroll * eased;
+
+ if (progress < 1) {
+ requestAnimationFrame(step);
+ } else {
+ requestAnimationFrame(() => {
+ s.measuring = false;
+ cancelAnimationFrame(s.rafId);
+ const totalElapsed = performance.now() - s.startTime;
+ if (totalElapsed > 0 && s.frames > 0) {
+ const fps = Math.round((s.frames / totalElapsed) * 1000);
+ setMetrics(m => ({
+ ...m,
+ scrollFps: fps,
+ scrollFrameDrops: s.drops,
+ }));
+ }
+ });
+ }
+ }
+ requestAnimationFrame(step);
+ }, []);
+
+ return {metrics, scrollRef, runScrollTest};
+}
+
+// ---------------------------------------------------------------------------
+// Metrics display
+// ---------------------------------------------------------------------------
+
+function metricVariant(
+ value: number | null,
+ thresholds?: {good: number; warn: number},
+): 'green' | 'orange' | 'red' | 'neutral' {
+ if (value == null || !thresholds) return 'neutral';
+ if (value <= thresholds.good) return 'green';
+ if (value <= thresholds.warn) return 'orange';
+ return 'red';
+}
+
+function formatMetric(value: number | null, unit: string): string {
+ if (value == null) return '\u2014';
+ return `${value.toFixed(1)}${unit}`;
+}
+
+function Metric({
+ label,
+ value,
+ unit,
+ thresholds,
+}: {
+ label: string;
+ value: number | null;
+ unit: string;
+ thresholds?: {good: number; warn: number};
+}) {
+ return (
+ <XDSHStack gap={1} vAlign="center">
+ <XDSBadge variant={metricVariant(value, thresholds)} label={label} />
+ <XDSText type="code">{formatMetric(value, unit)}</XDSText>
+ </XDSHStack>
+ );
+}
+
+function MetricsBar({
+ metrics,
+ onScrollTest,
+}: {
+ metrics: PerfMetrics;
+ onScrollTest: () => void;
+}) {
+ return (
+ <XDSHStack gap={3} vAlign="center" wrap="wrap">
+ <Metric
+ label="mount"
+ value={metrics.mountMs}
+ unit="ms"
+ thresholds={{good: 50, warn: 200}}
+ />
+ <Metric
+ label="render"
+ value={metrics.lastRenderMs}
+ unit="ms"
+ thresholds={{good: 16, warn: 50}}
+ />
+ <Metric label="renders" value={metrics.renderCount} unit="" />
+ <Metric
+ label="scroll fps"
+ value={metrics.scrollFps}
+ unit=""
+ thresholds={{good: 120, warn: 55}}
+ />
+ <Metric label="drops" value={metrics.scrollFrameDrops} unit="" />
+ <XDSButton
+ size="sm"
+ variant="secondary"
+ label="Scroll test"
+ onClick={onScrollTest}
+ />
+ </XDSHStack>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Panel (one code block + its metrics)
+// ---------------------------------------------------------------------------
+
+function PerfPanel({
+ mode,
+ label,
+ lineCount,
+ maxHeight,
+}: {
+ mode: 'ranges' | 'spans';
+ label: string;
+ lineCount: number;
+ maxHeight: number;
+}) {
+ const code = React.useMemo(() => generateCode(lineCount), [lineCount]);
+ const {metrics, scrollRef, runScrollTest} = usePerfMetrics();
+
+ return (
+ <XDSVStack gap={3}>
+ <XDSHStack gap={2} vAlign="center">
+ <XDSText type="label">{label}</XDSText>
+ <XDSBadge label={mode} />
+ </XDSHStack>
+ <XDSCard padding={3} variant="muted">
+ <MetricsBar metrics={metrics} onScrollTest={runScrollTest} />
+ </XDSCard>
+ <div ref={scrollRef}>
+ <XDSCodeBlock
+ code={code}
+ language="typescript"
+ title={`${lineCount.toLocaleString()} lines`}
+ hasLineNumbers
+ maxHeight={maxHeight}
+ highlightMode={mode}
+ />
+ </div>
+ </XDSVStack>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Page
+// ---------------------------------------------------------------------------
+
+const LINE_OPTIONS = ['100', '500', '1000', '2000', '5000'];
+
+export default function CodeBlockPerfPage() {
+ const [lineCount, setLineCount] = useState('1000');
+
+ return (
+ <XDSAppShell contentPadding={4} height="fill">
+ <XDSVStack gap={4}>
+ <XDSVStack gap={1}>
+ <XDSHeading level={2}>CodeBlock Performance</XDSHeading>
+ <XDSText type="body" color="secondary">
+ Compare CSS Highlight API (ranges) vs span-based rendering side by
+ side.
+ </XDSText>
+ </XDSVStack>
+
+ <XDSSection variant="wash" padding={3} dividers={['bottom']}>
+ <XDSSegmentedControl
+ label="Line count"
+ value={lineCount}
+ onChange={setLineCount}
+ size="sm">
+ {LINE_OPTIONS.map(n => (
+ <XDSSegmentedControlItem
+ key={n}
+ value={n}
+ label={Number(n).toLocaleString()}
+ />
+ ))}
+ </XDSSegmentedControl>
+ </XDSSection>
+
+ <XDSGrid columns={2} gap={4}>
+ <PerfPanel
+ key={`ranges-${lineCount}`}
+ mode="ranges"
+ label="CSS Highlight API"
+ lineCount={Number(lineCount)}
+ maxHeight={500}
+ />
+ <PerfPanel
+ key={`spans-${lineCount}`}
+ mode="spans"
+ label="Span-based"
+ lineCount={Number(lineCount)}
+ maxHeight={500}
+ />
+ </XDSGrid>
+ </XDSVStack>
+ </XDSAppShell>
+ );
+}
diff --git a/apps/sandbox/src/app/sandboxPages.ts b/apps/sandbox/src/app/sandboxPages.ts
index 219015e72f..d52b6f14c8 100644
--- a/apps/sandbox/src/app/sandboxPages.ts
+++ b/apps/sandbox/src/app/sandboxPages.ts
@@ -120,6 +120,12 @@ export const categories: SandboxCategory[] = [
description:
'CodePen-style playground with code panels and live XDS preview',
},
+ {
+ name: 'CodeBlock Perf',
+ href: '/pages/codeblock-perf/',
+ description:
+ 'Compare highlight modes and scroll performance'
+ },
],
},
];
diff --git a/packages/core/src/CodeBlock/XDSCodeBlock.tsx b/packages/core/src/CodeBlock/XDSCodeBlock.tsx
index f8452de3d8..baeb2454bd 100644
--- a/packages/core/src/CodeBlock/XDSCodeBlock.tsx
+++ b/packages/core/src/CodeBlock/XDSCodeBlock.tsx
@@ -20,6 +20,7 @@ import {
useCallback,
useMemo,
} from 'react';
+import * as React from 'react';
import type {XDSBaseProps} from '../XDSBaseProps';
import * as stylex from '@stylexjs/stylex';
import {
@@ -35,7 +36,8 @@ import {
import {xdsClassName, mergeProps} from '../utils';
import {tokenize, tokenizeAsync, SYNC_TOKENIZE_THRESHOLD} from './tokenizer';
import type {Token} from './tokenizer';
-import {ensureHighlightStyles, TOKEN_TYPES} from './highlightStyles';
+import {ensureHighlightStyles} from './highlightStyles';
+import {applyHighlightRangesChunked} from './highlightRanges';
// ---------------------------------------------------------------------------
// Styles
@@ -109,8 +111,9 @@ const styles = stylex.create({
},
line: {
lineHeight: typeScaleVars['--text-code-leading'],
+ },
+ lineChunk: {
contentVisibility: 'auto',
- containIntrinsicBlockSize: 'auto 1lh',
},
lineHighlighted: {
backgroundColor: colorVars['--color-accent-muted'],
@@ -151,52 +154,110 @@ const styles = stylex.create({
},
});
+// ---------------------------------------------------------------------------
+// Line rendering (shared)
+// ---------------------------------------------------------------------------
+
+const LINE_CHUNK_SIZE = 20;
+const LINE_CHUNK_THRESHOLD = 100;
+
+/**
+ * Memoized line component to avoid re-rendering unchanged lines.
+ */
+const CodeLine = React.memo(function CodeLine({
+ lineIndex,
+ isHighlighted,
+ children,
+}: {
+ lineIndex: number;
+ isHighlighted: boolean;
+ children: React.ReactNode;
+}) {
+ return (
+ <div
+ data-line={lineIndex + 1}
+ {...stylex.props(styles.line, isHighlighted && styles.lineHighlighted)}>
+ {children}
+ </div>
+ );
+});
+
+function renderLines(
+ lines: string[],
+ highlightSet: Set<number> | null,
+ renderLineContent: (line: string, lineIndex: number) => React.ReactNode,
+ chunkSize: number = LINE_CHUNK_SIZE,
+): React.ReactNode {
+ chunkSize = Math.max(1, Math.floor(chunkSize));
+
+ const renderLine = (line: string, i: number) => (
+ <CodeLine
+ key={i}
+ lineIndex={i}
+ isHighlighted={highlightSet?.has(i + 1) ?? false}>
+ {renderLineContent(line, i)}
+ </CodeLine>
+ );
+
+ if (lines.length < LINE_CHUNK_THRESHOLD) {
+ return lines.map(renderLine);
+ }
+
+ const chunks: React.ReactNode[] = [];
+ for (let start = 0; start < lines.length; start += chunkSize) {
+ const end = Math.min(start + chunkSize, lines.length);
+ const chunkLines = lines.slice(start, end);
+ const estimatedHeight = `${chunkLines.length}lh`;
+
+ chunks.push(
+ <div
+ key={start}
+ {...stylex.props(styles.lineChunk)}
+ style={{containIntrinsicBlockSize: `auto ${estimatedHeight}`}}>
+ {chunkLines.map((line, j) => renderLine(line, start + j))}
+ </div>,
+ );
+ }
+ return chunks;
+}
+
// ---------------------------------------------------------------------------
// Props
// ---------------------------------------------------------------------------
export interface XDSCodeBlockProps extends XDSBaseProps<HTMLPreElement> {
- /** Ref forwarded to the root <pre> element */
ref?: React.Ref<HTMLPreElement>;
- /** The code string to display */
code: string;
- /** Language for syntax highlighting. @default "plaintext" */
language?: string;
- /** Filename/label in header bar */
title?: string;
- /**
- * Show the language name in the header bar.
- * @default true
- */
hasLanguageLabel?: boolean;
- /** Show line number gutter. @default false */
hasLineNumbers?: boolean;
- /** 1-indexed lines to highlight. */
highlightLines?: number[];
- /** Show copy-to-clipboard button. @default true */
hasCopyButton?: boolean;
- /** Callback after copy */
onCopy?: () => void;
- /** Wrap long lines vs horizontal scroll. @default false */
isWrapped?: boolean;
- /** Max height before scrolling */
maxHeight?: number | string;
- /** Text size. @default "md" */
size?: 'sm' | 'md';
- /** Custom tokenizer override */
tokenizer?: (
code: string,
language: string,
) => Array<{type: string; start: number; end: number}>;
}
+/**
+ * Internal-only props for testing and performance tuning.
+ * Not part of the public API — used by the sandbox perf page.
+ * @internal
+ */
+interface XDSCodeBlockInternalProps extends XDSCodeBlockProps {
+ /** @internal Force a specific highlighting strategy. */
+ highlightMode?: 'auto' | 'ranges' | 'spans';
+}
+
// ---------------------------------------------------------------------------
// Helpers
// ---------------------------------------------------------------------------
-/**
- * Check if CSS Custom Highlight API is available.
- */
function hasHighlightAPI(): boolean {
return (
typeof CSS !== 'undefined' &&
@@ -205,43 +266,51 @@ function hasHighlightAPI(): boolean {
);
}
-/**
- * Build span-based highlighted line content from tokens.
- *
- * Splits a line into segments: plain text between tokens gets rendered
- * as bare text nodes, tokens get wrapped in <span className="xds-token-{type}">.
- */
+// ---------------------------------------------------------------------------
+// Span-mode code element
+// ---------------------------------------------------------------------------
+
+function findFirstTokenIndex(tokens: Token[], lineStart: number): number {
+ let lo = 0;
+ let hi = tokens.length;
+ while (lo < hi) {
+ const mid = (lo + hi) >>> 1;
+ if (tokens[mid].end <= lineStart) {
+ lo = mid + 1;
+ } else {
+ hi = mid;
+ }
+ }
+ return lo;
+}
+
function buildSpanLine(
lineText: string,
lineStart: number,
tokens: Token[],
+ searchStart: number,
): React.ReactNode {
if (tokens.length === 0) {
return lineText || '\u200b';
}
const lineEnd = lineStart + lineText.length;
-
- // Filter tokens that overlap this line
- const lineTokens = tokens.filter(t => t.start < lineEnd && t.end > lineStart);
-
- if (lineTokens.length === 0) {
- return lineText || '\u200b';
- }
-
const parts: React.ReactNode[] = [];
let cursor = lineStart;
+ let hasTokens = false;
- for (const token of lineTokens) {
+ for (let i = searchStart; i < tokens.length; i++) {
+ const token = tokens[i];
+ if (token.start >= lineEnd) break;
+ if (token.end <= lineStart) continue;
+
+ hasTokens = true;
const tStart = Math.max(token.start, lineStart);
const tEnd = Math.min(token.end, lineEnd);
- // Plain text before this token
if (tStart > cursor) {
parts.push(lineText.slice(cursor - lineStart, tStart - lineStart));
}
-
- // Token span
parts.push(
<span
key={`${tStart}-${token.type}`}
@@ -249,99 +318,53 @@ function buildSpanLine(
{lineText.slice(tStart - lineStart, tEnd - lineStart)}
</span>,
);
-
cursor = tEnd;
}
- // Remaining plain text after last token
- if (cursor < lineEnd) {
- parts.push(lineText.slice(cursor - lineStart));
- }
-
+ if (!hasTokens) return lineText || '\u200b';
+ if (cursor < lineEnd) parts.push(lineText.slice(cursor - lineStart));
return parts.length > 0 ? parts : '\u200b';
}
-// ---------------------------------------------------------------------------
-// Component
-// ---------------------------------------------------------------------------
-
/**
- * A read-only syntax-highlighted code block.
- *
- * Uses the CSS Custom Highlight API for zero-DOM-overhead syntax coloring.
- * Falls back to span-based rendering in browsers without support, or when
- * `highlightMode="spans"` is explicitly set.
- *
- * @example
- * ```
- * <XDSCodeBlock
- * code={`const x = 42;`}
- * language="typescript"
- * hasLineNumbers
- * />
- * ```
+ * Span-mode: tokenizes code and renders lines with <span> tokens.
+ * Only mounts when highlightMode resolves to spans.
*/
-export function XDSCodeBlock({
+function SpanCodeContent({
code,
- language = 'plaintext',
- title,
- hasLanguageLabel = true,
- hasLineNumbers = false,
- highlightLines,
- hasCopyButton = true,
- onCopy,
- isWrapped = false,
- maxHeight,
- size = 'md',
- tokenizer: customTokenizer,
- xstyle,
- className,
- style,
- ref,
- ...props
-}: XDSCodeBlockProps) {
- const codeRef = useRef<HTMLElement>(null);
- const instanceId = useId();
- const [copied, setCopied] = useState(false);
-
- // Auto-detect: use CSS Custom Highlight API when available, fall back to spans
- const useSpans = !hasHighlightAPI();
-
- // For span mode: we need tokens to render. Small code is tokenized sync,
- // large code is tokenized async.
+ language,
+ lines,
+ lineOffsets,
+ highlightSet,
+ isWrapped,
+ sizeStyle,
+ customTokenizer,
+}: {
+ code: string;
+ language: string;
+ lines: string[];
+ lineOffsets: number[];
+ highlightSet: Set<number> | null;
+ isWrapped: boolean;
+ sizeStyle: stylex.StyleXStyles;
+ customTokenizer?: XDSCodeBlockProps['tokenizer'];
+}) {
const [asyncTokens, setAsyncTokens] = useState<Token[] | null>(null);
- const lines = code.split('\n');
- // Remove trailing empty line from code that ends with newline
- if (lines.length > 1 && lines[lines.length - 1] === '') {
- lines.pop();
- }
-
- const highlightSet = highlightLines ? new Set(highlightLines) : null;
-
- const handleCopy = useCallback(() => {
- navigator.clipboard.writeText(code).then(() => {
- setCopied(true);
- onCopy?.();
- setTimeout(() => setCopied(false), 2000);
- });
- }, [code, onCopy]);
+ useLayoutEffect(() => {
+ ensureHighlightStyles();
+ }, []);
- // Compute tokens for span mode
const syncTokens = useMemo(() => {
- if (!useSpans) return null;
if (code.length >= SYNC_TOKENIZE_THRESHOLD) return null;
const tok = customTokenizer ?? tokenize;
return tok(code, language);
- }, [useSpans, code, language, customTokenizer]);
+ }, [code, language, customTokenizer]);
- // Async tokenization for span mode with large code
useEffect(() => {
- if (!useSpans) return;
if (code.length < SYNC_TOKENIZE_THRESHOLD) return;
const abortController = new AbortController();
-
tokenizeAsync(code, language, abortController.signal).then(tokens => {
if (!abortController.signal.aborted) {
setAsyncTokens(tokens);
@@ -352,32 +375,72 @@ export function XDSCodeBlock({
abortController.abort();
setAsyncTokens(null);
};
- }, [useSpans, code, language, customTokenizer]);
+ }, [code, language, customTokenizer]);
const spanTokens = syncTokens ?? asyncTokens ?? [];
- // Apply CSS Custom Highlight API ranges — small code (sync, layout effect)
- useLayoutEffect(() => {
- if (useSpans) return;
- if (code.length >= SYNC_TOKENIZE_THRESHOLD) return;
- if (!hasHighlightAPI()) return;
+ const tokenSearchStarts = useMemo(() => {
+ if (spanTokens.length === 0) return null;
+ const starts = new Array<number>(lines.length);
+ for (let i = 0; i < lines.length; i++) {
+ starts[i] = findFirstTokenIndex(spanTokens, lineOffsets[i]);
+ }
+ return starts;
+ }, [spanTokens, lines.length, lineOffsets]);
- ensureHighlightStyles();
+ function renderLineContent(line: string, lineIndex: number): React.ReactNode {
+ return buildSpanLine(
+ line,
+ lineOffsets[lineIndex],
+ spanTokens,
+ tokenSearchStarts?.[lineIndex] ?? 0,
+ );
+ }
- const codeEl = codeRef.current;
- if (!codeEl) return;
+ return (
+ <code
+ {...stylex.props(
+ styles.code,
+ sizeStyle,
+ isWrapped && styles.codeWrapped,
+ )}>
+ {renderLines(lines, highlightSet, renderLineContent)}
+ </code>
+ );
+}
- const tok = customTokenizer ?? tokenize;
- const tokens = tok(code, language);
- if (tokens.length === 0) return;
+// ---------------------------------------------------------------------------
+// Range-mode code element
+// ---------------------------------------------------------------------------
- return applyHighlightRanges(codeEl, tokens);
- }, [useSpans, code, language, customTokenizer, instanceId]);
+/**
+ * Range-mode: renders plain text lines, applies CSS Custom Highlight API
+ * ranges in a non-blocking effect. Only mounts when highlightMode
+ * resolves to ranges.
+ */
+function RangeCodeContent({
+ code,
+ language,
+ lines,
+ highlightSet,
+ isWrapped,
+ sizeStyle,
+ customTokenizer,
+}: {
+ code: string;
+ language: string;
+ lines: string[];
+ highlightSet: Set<number> | null;
+ isWrapped: boolean;
+ sizeStyle: stylex.StyleXStyles;
+ customTokenizer?: XDSCodeBlockProps['tokenizer'];
+}) {
+ const codeRef = useRef<HTMLElement>(null);
+ const instanceId = useId();
- // Apply CSS Custom Highlight API ranges — large code (async, regular effect)
+ // Apply highlight ranges in a non-blocking effect so the code text
+ // is visible and scrollable immediately. Colors appear a frame later.
useEffect(() => {
- if (useSpans) return;
- if (code.length < SYNC_TOKENIZE_THRESHOLD) return;
if (!hasHighlightAPI()) return;
ensureHighlightStyles();
@@ -385,27 +448,120 @@ export function XDSCodeBlock({
const codeEl = codeRef.current;
if (!codeEl) return;
+ if (code.length < SYNC_TOKENIZE_THRESHOLD) {
+ const tok = customTokenizer ?? tokenize;
+ const tokens = tok(code, language);
+ if (tokens.length === 0) return;
+ return applyHighlightRangesChunked(codeEl, tokens);
+ }
+
const abortController = new AbortController();
let cleanup: (() => void) | undefined;
tokenizeAsync(code, language, abortController.signal).then(tokens => {
if (abortController.signal.aborted) return;
if (tokens.length === 0) return;
- cleanup = applyHighlightRanges(codeEl, tokens);
+ cleanup = applyHighlightRangesChunked(codeEl, tokens);
});
return () => {
abortController.abort();
cleanup?.();
};
- }, [useSpans, code, language, customTokenizer, instanceId]);
+ }, [code, language, customTokenizer, instanceId]);
- // Ensure styles are injected for span mode too
- useLayoutEffect(() => {
- if (useSpans) {
- ensureHighlightStyles();
+ function renderLineContent(line: string): React.ReactNode {
+ return line || '\u200b';
+ }
+
+ return (
+ <code
+ ref={codeRef}
+ {...stylex.props(
+ styles.code,
+ sizeStyle,
+ isWrapped && styles.codeWrapped,
+ )}>
+ {/* No content-visibility chunking in range mode — TreeWalker
+ can't see text nodes inside content-visibility: auto divs,
+ so highlight ranges would be missing for off-screen lines. */}
+ {renderLines(lines, highlightSet, renderLineContent, Infinity)}
+ </code>
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Main component
+// ---------------------------------------------------------------------------
+
+/**
+ * A read-only syntax-highlighted code block.
+ *
+ * Uses the CSS Custom Highlight API for zero-DOM-overhead syntax coloring.
+ * Falls back to span-based rendering in browsers without support, or when
+ * `highlightMode="spans"` is explicitly set.
+ *
+ * @example
+ * ```
+ * <XDSCodeBlock
+ * code={`const x = 42;`}
+ * language="typescript"
+ * hasLineNumbers
+ * />
+ * ```
+ */
+export function XDSCodeBlock({
+ code,
+ language = 'plaintext',
+ title,
+ hasLanguageLabel = true,
+ hasLineNumbers = false,
+ highlightLines,
+ hasCopyButton = true,
+ onCopy,
+ isWrapped = false,
+ maxHeight,
+ size = 'md',
+ tokenizer: customTokenizer,
+ highlightMode = 'auto',
+ xstyle,
+ className,
+ style,
+ ref,
+ ...props
+}: XDSCodeBlockInternalProps) {
+ const [copied, setCopied] = useState(false);
+
+ const useSpans =
+ highlightMode === 'spans' ||
+ (highlightMode === 'auto' && !hasHighlightAPI());
+
+ const {lines, lineOffsets} = useMemo(() => {
+ const l = code.split('\n');
+ if (l.length > 1 && l[l.length - 1] === '') {
+ l.pop();
+ }
+ const offsets = new Array<number>(l.length);
+ let offset = 0;
+ for (let i = 0; i < l.length; i++) {
+ offsets[i] = offset;
+ offset += l[i].length + 1;
}
- }, [useSpans]);
+ return {lines: l, lineOffsets: offsets};
+ }, [code]);
+
+ const highlightSet = useMemo(
+ () => (highlightLines ? new Set(highlightLines) : null),
+ [highlightLines],
+ );
+
+ const handleCopy = useCallback(() => {
+ navigator.clipboard.writeText(code).then(() => {
+ setCopied(true);
+ onCopy?.();
+ setTimeout(() => setCopied(false), 2000);
+ });
+ }, [code, onCopy]);
const sizeStyle = size === 'sm' ? styles.sizeSm : styles.sizeMd;
const gutterSizeStyle = size === 'sm' ? styles.gutterSm : styles.gutterMd;
@@ -457,21 +613,6 @@ export function XDSCodeBlock({
</button>
) : null;
- // Build line content: spans mode renders tokens inline, highlight mode
- // renders plain text (CSS Highlight API colors it via ranges).
- function renderLineContent(line: string, lineIndex: number): React.ReactNode {
- if (!useSpans) {
- return line || '\u200b';
- }
- // Calculate the character offset of this line in the full code string.
- // Each previous line + 1 for the \n separator.
- let lineStart = 0;
- for (let i = 0; i < lineIndex; i++) {
- lineStart += lines[i].length + 1;
- }
- return buildSpanLine(line, lineStart, spanTokens);
- }
-
return (
<pre
ref={ref}
@@ -505,25 +646,28 @@ export function XDSCodeBlock({
))}
</div>
)}
- <code
- ref={codeRef}
- {...stylex.props(
- styles.code,
- sizeStyle,
- isWrapped && styles.codeWrapped,
- )}>
- {lines.map((line, i) => (
- <div
- key={i}
- data-line={i + 1}
- {...stylex.props(
- styles.line,
- highlightSet?.has(i + 1) && styles.lineHighlighted,
- )}>
- {renderLineContent(line, i)}
- </div>
- ))}
- </code>
+ {useSpans ? (
+ <SpanCodeContent
+ code={code}
+ language={language}
+ lines={lines}
+ lineOffsets={lineOffsets}
+ highlightSet={highlightSet}
+ isWrapped={isWrapped}
+ sizeStyle={sizeStyle}
+ customTokenizer={customTokenizer}
+ />
+ ) : (
+ <RangeCodeContent
+ code={code}
+ language={language}
+ lines={lines}
+ highlightSet={highlightSet}
+ isWrapped={isWrapped}
+ sizeStyle={sizeStyle}
+ customTokenizer={customTokenizer}
+ />
+ )}
</div>
</div>
{!showHeader && copyButtonEl}
@@ -532,100 +676,3 @@ export function XDSCodeBlock({
}
XDSCodeBlock.displayName = 'XDSCodeBlock';
-
-// ---------------------------------------------------------------------------
-// Shared highlight range application
-// ---------------------------------------------------------------------------
-
-/**
- * Apply CSS Custom Highlight API ranges to a code element.
- * Returns a cleanup function that removes the ranges.
- */
-function applyHighlightRanges(
- codeEl: HTMLElement,
- tokens: Token[],
-): () => void {
- // Group tokens by type
- const tokensByType = new Map<string, Token[]>();
- for (const token of tokens) {
- const existing = tokensByType.get(token.type);
- if (existing) {
- existing.push(token);
- } else {
- tokensByType.set(token.type, [token]);
- }
- }
-
- // Build text node mapping using TreeWalker — same approach as CodeEditor.
- const walker = document.createTreeWalker(codeEl, NodeFilter.SHOW_TEXT);
- const textNodes: Array<{node: Text; start: number}> = [];
- let charOffset = 0;
-
- let currentNode = walker.nextNode();
- while (currentNode) {
- const text = currentNode as Text;
- const content = text.textContent ?? '';
- if (content === '\u200b') {
- charOffset += 1;
- } else {
- textNodes.push({node: text, start: charOffset});
- charOffset += content.length + 1;
- }
- currentNode = walker.nextNode();
- }
-
- function findPosition(offset: number): {node: Text; offset: number} | null {
- for (let i = textNodes.length - 1; i >= 0; i--) {
- const entry = textNodes[i];
- if (offset >= entry.start) {
- const localOffset = offset - entry.start;
- if (localOffset <= (entry.node.textContent?.length ?? 0)) {
- return {node: entry.node, offset: localOffset};
- }
- return null;
- }
- }
- return null;
- }
-
- const myRanges: Range[] = [];
-
- for (const tokenType of TOKEN_TYPES) {
- const typedTokens = tokensByType.get(tokenType);
- if (!typedTokens || typedTokens.length === 0) continue;
-
- const name = `xds-${tokenType}`;
- let highlight = CSS.highlights.get(name);
- if (!highlight) {
- highlight = new Highlight();
- CSS.highlights.set(name, highlight);
- }
-
- for (const token of typedTokens) {
- const startPos = findPosition(token.start);
- const endPos = findPosition(token.end);
- if (!startPos || !endPos) continue;
-
- try {
- const range = new Range();
- range.setStart(startPos.node, startPos.offset);
- range.setEnd(endPos.node, endPos.offset);
- highlight.add(range);
- myRanges.push(range);
- } catch {
- // Skip invalid ranges
- }
- }
- }
-
- return () => {
- for (const range of myRanges) {
- for (const tokenType of TOKEN_TYPES) {
- const highlight = CSS.highlights.get(`xds-${tokenType}`);
- if (highlight) {
- highlight.delete(range);
- }
- }
- }
- };
-}
diff --git a/packages/core/src/CodeBlock/highlightRanges.test.ts b/packages/core/src/CodeBlock/highlightRanges.test.ts
new file mode 100644
index 0000000000..a40b49f420
--- /dev/null
+++ b/packages/core/src/CodeBlock/highlightRanges.test.ts
@@ -0,0 +1,203 @@
+/**
+ * @file highlightRanges.test.ts
+ * Tests for binary search, text node mapping, and range application.
+ */
+
+import {describe, it, expect, beforeEach, afterEach} from 'vitest';
+import {buildTextNodeMap, applyHighlightRanges} from './highlightRanges';
+
+// ---------------------------------------------------------------------------
+// DOM helpers
+// ---------------------------------------------------------------------------
+
+function makeCodeEl(lines: string[]): HTMLElement {
+ const code = document.createElement('code');
+ for (const line of lines) {
+ const div = document.createElement('div');
+ div.textContent = line || '\u200b';
+ code.appendChild(div);
+ }
+ document.body.appendChild(code);
+ return code;
+}
+
+afterEach(() => {
+ document.body.innerHTML = '';
+});
+
+// ---------------------------------------------------------------------------
+// buildTextNodeMap
+// ---------------------------------------------------------------------------
+
+describe('buildTextNodeMap', () => {
+ it('maps single-line code', () => {
+ const el = makeCodeEl(['const x = 1;']);
+ const nodes = buildTextNodeMap(el);
+
+ expect(nodes).toHaveLength(1);
+ expect(nodes[0].start).toBe(0);
+ expect(nodes[0].node.textContent).toBe('const x = 1;');
+ });
+
+ it('maps multi-line code with correct offsets', () => {
+ const el = makeCodeEl(['hello', 'world']);
+ const nodes = buildTextNodeMap(el);
+
+ expect(nodes).toHaveLength(2);
+ expect(nodes[0].start).toBe(0);
+ expect(nodes[1].start).toBe(6); // "hello"(5) + 1 for \n
+ });
+
+ it('handles empty lines (zero-width space)', () => {
+ const el = makeCodeEl(['hello', '', 'world']);
+ const nodes = buildTextNodeMap(el);
+
+ // ZWSP nodes not included in array
+ expect(nodes).toHaveLength(2);
+ expect(nodes[0].start).toBe(0);
+ expect(nodes[1].start).toBe(7); // "hello"(5) + \n(1) + ZWSP(1)
+ });
+
+ it('returns empty for empty element', () => {
+ const el = document.createElement('code');
+ document.body.appendChild(el);
+ expect(buildTextNodeMap(el)).toHaveLength(0);
+ });
+
+ it('offset accounts for multiple consecutive empty lines', () => {
+ const el = makeCodeEl(['a', '', '', 'b']);
+ const nodes = buildTextNodeMap(el);
+
+ expect(nodes).toHaveLength(2);
+ expect(nodes[0].start).toBe(0); // "a"
+ expect(nodes[1].start).toBe(4); // "a"(1) + \n(1) + ZWSP(1) + ZWSP(1)
+ });
+});
+
+// ---------------------------------------------------------------------------
+// applyHighlightRanges
+// ---------------------------------------------------------------------------
+
+describe('applyHighlightRanges', () => {
+ let mockHighlights: Map<string, Set<Range>>;
+
+ beforeEach(() => {
+ mockHighlights = new Map();
+
+ if (typeof CSS === 'undefined') {
+ (globalThis as Record<string, unknown>).CSS = {};
+ }
+ (CSS as Record<string, unknown>).highlights = {
+ get(name: string) {
+ return mockHighlights.get(name);
+ },
+ set(name: string, highlight: Set<Range>) {
+ mockHighlights.set(name, highlight);
+ },
+ };
+
+ (globalThis as Record<string, unknown>).Highlight =
+ class MockHighlight extends Set<Range> {};
+ });
+
+ afterEach(() => {
+ delete (CSS as Record<string, unknown>).highlights;
+ delete (globalThis as Record<string, unknown>).Highlight;
+ });
+
+ it('creates ranges for tokens', () => {
+ const el = makeCodeEl(['const x = 1;']);
+ const tokens = [
+ {type: 'keyword', start: 0, end: 5},
+ {type: 'variable', start: 6, end: 7},
+ {type: 'number', start: 10, end: 11},
+ ];
+
+ const cleanupFn = applyHighlightRanges(el, tokens);
+
+ expect(mockHighlights.has('xds-keyword')).toBe(true);
+ expect(mockHighlights.has('xds-variable')).toBe(true);
+ expect(mockHighlights.has('xds-number')).toBe(true);
+ expect(mockHighlights.get('xds-keyword')!.size).toBe(1);
+ expect(mockHighlights.get('xds-variable')!.size).toBe(1);
+ expect(mockHighlights.get('xds-number')!.size).toBe(1);
+
+ cleanupFn();
+ });
+
+ it('handles multi-line tokens', () => {
+ const el = makeCodeEl(['const x = 1;', 'let y = 2;']);
+ const tokens = [
+ {type: 'keyword', start: 0, end: 5},
+ {type: 'keyword', start: 14, end: 17},
+ ];
+
+ const cleanupFn = applyHighlightRanges(el, tokens);
+ expect(mockHighlights.get('xds-keyword')!.size).toBe(2);
+ cleanupFn();
+ });
+
+ it('skips tokens with out-of-bounds offsets', () => {
+ const el = makeCodeEl(['hello']);
+ const tokens = [
+ {type: 'keyword', start: 0, end: 5},
+ {type: 'keyword', start: 100, end: 105},
+ ];
+
+ const cleanupFn = applyHighlightRanges(el, tokens);
+ expect(mockHighlights.get('xds-keyword')!.size).toBe(1);
+ cleanupFn();
+ });
+
+ it('cleanup removes all ranges', () => {
+ const el = makeCodeEl(['const x = 1;']);
+ const tokens = [
+ {type: 'keyword', start: 0, end: 5},
+ {type: 'number', start: 10, end: 11},
+ ];
+
+ const cleanupFn = applyHighlightRanges(el, tokens);
+ expect(mockHighlights.get('xds-keyword')!.size).toBe(1);
+ expect(mockHighlights.get('xds-number')!.size).toBe(1);
+
+ cleanupFn();
+
+ expect(mockHighlights.get('xds-keyword')!.size).toBe(0);
+ expect(mockHighlights.get('xds-number')!.size).toBe(0);
+ });
+
+ it('returns no-op cleanup for empty tokens', () => {
+ const el = makeCodeEl(['hello']);
+ const cleanupFn = applyHighlightRanges(el, []);
+
+ // No highlights created for unused types
+ expect(mockHighlights.size).toBe(0);
+
+ // Should not throw
+ cleanupFn();
+ });
+
+ it('handles tokens across empty lines', () => {
+ // "if (x)\n\n return y;"
+ const el = makeCodeEl(['if (x)', '', ' return y;']);
+ const tokens = [
+ {type: 'keyword', start: 0, end: 2},
+ {type: 'keyword', start: 10, end: 16},
+ ];
+
+ const cleanupFn = applyHighlightRanges(el, tokens);
+ expect(mockHighlights.get('xds-keyword')!.size).toBe(2);
+ cleanupFn();
+ });
+
+ it('registers highlights for arbitrary token types', () => {
+ const el = makeCodeEl(['hello']);
+ const tokens = [{type: 'made_up_type', start: 0, end: 5}];
+
+ const cleanupFn = applyHighlightRanges(el, tokens);
+ expect(mockHighlights.has('xds-made_up_type')).toBe(true);
+ expect(mockHighlights.get('xds-made_up_type')!.size).toBe(1);
+ cleanupFn();
+ expect(mockHighlights.get('xds-made_up_type')!.size).toBe(0);
+ });
+});
diff --git a/packages/core/src/CodeBlock/highlightRanges.ts b/packages/core/src/CodeBlock/highlightRanges.ts
new file mode 100644
index 0000000000..0196edbb33
--- /dev/null
+++ b/packages/core/src/CodeBlock/highlightRanges.ts
@@ -0,0 +1,313 @@
+/**
+ * @file highlightRanges.ts
+ * @input Code element, tokens array, CSS Custom Highlight API
+ * @output Creates/removes highlight Range objects for syntax coloring
+ * @position Shared utility consumed by XDSCodeBlock (ranges mode)
+ */
+
+import type {Token} from './tokenizer';
+import {ensureHighlightStyles} from './highlightStyles';
+
+// ---------------------------------------------------------------------------
+// Text node mapping
+// ---------------------------------------------------------------------------
+
+interface TextNodeEntry {
+ node: Text;
+ start: number;
+}
+
+/**
+ * Walk a code element's text nodes and build a sorted map of
+ * character offsets. Each entry maps a Text node to its starting
+ * offset in the original code string.
+ *
+ * Zero-width spaces (empty-line placeholders) count as 1 character
+ * to stay aligned with the tokenizer's newline-separated offsets.
+ */
+export function buildTextNodeMap(codeEl: HTMLElement): TextNodeEntry[] {
+ const walker = document.createTreeWalker(codeEl, NodeFilter.SHOW_TEXT);
+ const textNodes: TextNodeEntry[] = [];
+ let charOffset = 0;
+
+ let currentNode = walker.nextNode();
+ while (currentNode) {
+ const text = currentNode as Text;
+ const content = text.textContent ?? '';
+ if (content === '\u200b') {
+ charOffset += 1;
+ } else {
+ textNodes.push({node: text, start: charOffset});
+ charOffset += content.length + 1;
+ }
+ currentNode = walker.nextNode();
+ }
+ return textNodes;
+}
+
+// ---------------------------------------------------------------------------
+// Binary search
+// ---------------------------------------------------------------------------
+
+/**
+ * Binary search for the Text node containing a character offset.
+ * Returns the node and the local offset within that node, or null
+ * if the offset falls outside any mapped node.
+ */
+function findPosition(
+ textNodes: TextNodeEntry[],
+ offset: number,
+): {node: Text; offset: number} | null {
+ let lo = 0;
+ let hi = textNodes.length - 1;
+
+ while (lo <= hi) {
+ const mid = (lo + hi) >>> 1;
+ const entry = textNodes[mid];
+ if (offset < entry.start) {
+ hi = mid - 1;
+ } else if (
+ mid + 1 < textNodes.length &&
+ offset >= textNodes[mid + 1].start
+ ) {
+ lo = mid + 1;
+ } else {
+ const localOffset = offset - entry.start;
+ if (localOffset <= (entry.node.textContent?.length ?? 0)) {
+ return {node: entry.node, offset: localOffset};
+ }
+ return null;
+ }
+ }
+ return null;
+}
+
+// ---------------------------------------------------------------------------
+// Dynamic ::highlight() style injection
+// ---------------------------------------------------------------------------
+
+/**
+ * Track which token types already have a ::highlight() CSS rule.
+ * Known types are injected statically by ensureHighlightStyles();
+ * unknown types (e.g. from a Shiki adapter) get rules injected lazily.
+ */
+const registeredHighlightTypes = new Set<string>();
+let dynamicStyleSheet: CSSStyleSheet | null = null;
+
+/**
+ * Ensure a ::highlight(xds-{type}) CSS rule exists for the given token type.
+ * For the built-in types this is a no-op (static sheet covers them).
+ * For unknown types, injects a rule that maps to a --color-syntax-{type}
+ * custom property, falling back to currentColor.
+ */
+function ensureHighlightType(tokenType: string): void {
+ if (registeredHighlightTypes.has(tokenType)) return;
+ registeredHighlightTypes.add(tokenType);
+
+ // Static styles cover the built-in types; only inject for unknown ones
+ ensureHighlightStyles();
+ if (typeof document === 'undefined') return;
+
+ if (!dynamicStyleSheet) {
+ const style = document.createElement('style');
+ style.setAttribute('data-xds-highlight-dynamic', '');
+ document.head.appendChild(style);
+ dynamicStyleSheet = style.sheet!;
+ }
+
+ const name = `xds-${tokenType}`;
+ const colorVar = `var(--color-syntax-${tokenType}, currentColor)`;
+ dynamicStyleSheet.insertRule(
+ `.xds-codeblock ::highlight(${name}), .xds-codeeditor ::highlight(${name}) { color: ${colorVar}; }`,
+ );
+}
+
+// ---------------------------------------------------------------------------
+// Range application
+// ---------------------------------------------------------------------------
+
+/**
+ * Apply CSS Custom Highlight API ranges to a code element.
+ *
+ * Derives token types from the tokens themselves (not a hardcoded list),
+ * so custom tokenizers (e.g. Shiki adapters) can produce arbitrary
+ * scope names and they'll be registered automatically.
+ *
+ * Groups tokens by type, resolves each token's character offsets to
+ * DOM Range objects via binary search over the text node map, and
+ * registers them with the global CSS.highlights registry.
+ *
+ * Returns a cleanup function that removes all created ranges.
+ */
+/**
+ * Tokens per chunk when applying ranges progressively.
+ * Smaller = more responsive, larger = fewer frames to full color.
+ */
+const RANGE_CHUNK_SIZE = 200;
+
+/**
+ * Resolve a flat list of tokens into Highlight entries, returning
+ * the ranges and their associated Highlight objects for cleanup.
+ */
+function resolveTokenRanges(
+ tokens: Token[],
+ textNodes: TextNodeEntry[],
+): Array<{range: Range; highlight: Highlight}> {
+ // Group tokens by type
+ const tokensByType = new Map<string, Token[]>();
+ for (const token of tokens) {
+ const existing = tokensByType.get(token.type);
+ if (existing) {
+ existing.push(token);
+ } else {
+ tokensByType.set(token.type, [token]);
+ }
+ }
+
+ const results: Array<{range: Range; highlight: Highlight}> = [];
+
+ for (const [tokenType, typedTokens] of tokensByType) {
+ ensureHighlightType(tokenType);
+
+ const name = `xds-${tokenType}`;
+ let highlight = CSS.highlights.get(name);
+ if (!highlight) {
+ highlight = new Highlight();
+ CSS.highlights.set(name, highlight);
+ }
+
+ for (const token of typedTokens) {
+ const startPos = findPosition(textNodes, token.start);
+ const endPos = findPosition(textNodes, token.end);
+ if (!startPos || !endPos) continue;
+
+ try {
+ const range = new Range();
+ range.setStart(startPos.node, startPos.offset);
+ range.setEnd(endPos.node, endPos.offset);
+ highlight.add(range);
+ results.push({range, highlight});
+ } catch {
+ // Skip invalid ranges (detached nodes, out-of-bounds offsets)
+ }
+ }
+ }
+
+ return results;
+}
+
+function cleanupRanges(
+ ranges: Array<{range: Range; highlight: Highlight}>,
+): void {
+ for (const {range, highlight} of ranges) {
+ highlight.delete(range);
+ }
+}
+
+/**
+ * Apply CSS Custom Highlight API ranges synchronously.
+ * Best for small token sets (< RANGE_CHUNK_SIZE).
+ * Returns a cleanup function that removes all created ranges.
+ */
+export function applyHighlightRanges(
+ codeEl: HTMLElement,
+ tokens: Token[],
+): () => void {
+ const textNodes = buildTextNodeMap(codeEl);
+ const myRanges = resolveTokenRanges(tokens, textNodes);
+
+ return function cleanup() {
+ cleanupRanges(myRanges);
+ };
+}
+
+/**
+ * Apply CSS Custom Highlight API ranges in chunks, yielding to the
+ * browser between batches via requestAnimationFrame. Colors appear
+ * progressively over a few frames instead of blocking the main thread.
+ *
+ * Returns a cleanup function that cancels pending work and removes
+ * all ranges applied so far.
+ */
+export function applyHighlightRangesChunked(
+ codeEl: HTMLElement,
+ tokens: Token[],
+ chunkSize: number = RANGE_CHUNK_SIZE,
+): () => void {
+ // For small token sets, apply synchronously — no chunking overhead
+ if (tokens.length <= chunkSize) {
+ return applyHighlightRanges(codeEl, tokens);
+ }
+
+ const textNodes = buildTextNodeMap(codeEl);
+
+ // Pre-group tokens by type and resolve highlights once
+ const tokensByType = new Map<
+ string,
+ {tokens: Token[]; highlight: Highlight}
+ >();
+ for (const token of tokens) {
+ let entry = tokensByType.get(token.type);
+ if (!entry) {
+ ensureHighlightType(token.type);
+ const name = `xds-${token.type}`;
+ let highlight = CSS.highlights.get(name);
+ if (!highlight) {
+ highlight = new Highlight();
+ CSS.highlights.set(name, highlight);
+ }
+ entry = {tokens: [], highlight};
+ tokensByType.set(token.type, entry);
+ }
+ entry.tokens.push(token);
+ }
+
+ // Flatten to a single ordered list for chunked iteration
+ const allEntries: Array<{token: Token; highlight: Highlight}> = [];
+ for (const {tokens: typedTokens, highlight} of tokensByType.values()) {
+ for (const token of typedTokens) {
+ allEntries.push({token, highlight});
+ }
+ }
+
+ const myRanges: Array<{range: Range; highlight: Highlight}> = [];
+ let cursor = 0;
+ let rafId = 0;
+ let cancelled = false;
+
+ function processChunk() {
+ if (cancelled) return;
+
+ const end = Math.min(cursor + chunkSize, allEntries.length);
+ for (let i = cursor; i < end; i++) {
+ const {token, highlight} = allEntries[i];
+ const startPos = findPosition(textNodes, token.start);
+ const endPos = findPosition(textNodes, token.end);
+ if (!startPos || !endPos) continue;
+
+ try {
+ const range = new Range();
+ range.setStart(startPos.node, startPos.offset);
+ range.setEnd(endPos.node, endPos.offset);
+ highlight.add(range);
+ myRanges.push({range, highlight});
+ } catch {
+ // Skip invalid ranges
+ }
+ }
+ cursor = end;
+
+ if (cursor < allEntries.length) {
+ rafId = requestAnimationFrame(processChunk);
+ }
+ }
+
+ // Start first chunk synchronously for immediate partial coloring
+ processChunk();
+
+ return function cleanup() {
+ cancelled = true;
+ cancelAnimationFrame(rafId);
+ cleanupRanges(myRanges);
+ };
+}