svelte-highlight 7.22.0 → 7.23.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -21,6 +21,16 @@
21
21
  */
22
22
  export let checkpointInterval = 100;
23
23
 
24
+ /**
25
+ * Tokenize the rest of the document in idle time after the first paint,
26
+ * so a far jump (scrollToLine, dragging the scrollbar) doesn't stall on
27
+ * tokenizing everything before it. Off by default: the engine session
28
+ * keeps every event it produces, so a full pass retains about 117 MB
29
+ * per 100k lines of TypeScript, even if nobody scrolls.
30
+ * @type {boolean}
31
+ */
32
+ export let tokenizeAhead = false;
33
+
24
34
  import { createEventDispatcher, onMount, tick } from "svelte";
25
35
  import { createTokenizedDocument } from "./tokenized-document.js";
26
36
  import { watchLineHeight, windowRange } from "./virtual-window.js";
@@ -107,7 +117,11 @@
107
117
  dispatchedWindowStart = start;
108
118
  dispatchedWindowEnd = end;
109
119
  dispatchedWindowLineCount = lineCount;
110
- dispatch("windowchange", { start, end, lineCount });
120
+ // Dispatch once the new rows are in the DOM, so a listener that paints
121
+ // into them (e.g. search's highlightMatches) doesn't paint the old
122
+ // rows Svelte is about to replace.
123
+ const detail = { start, end, lineCount };
124
+ tick().then(() => dispatch("windowchange", detail));
111
125
  }
112
126
  }
113
127
 
@@ -167,6 +181,62 @@
167
181
  lineCount = doc.lineCount();
168
182
  computeWindow();
169
183
  syncFromContainer();
184
+ scheduleTokenizeAhead();
185
+ }
186
+
187
+ $: if (hydrated) {
188
+ if (tokenizeAhead) scheduleTokenizeAhead();
189
+ else cancelTokenizeAhead();
190
+ }
191
+
192
+ // Idle-time tokenizing ahead. A first jump to the end of a 500k-line file
193
+ // otherwise tokenizes ~24 MB synchronously (seconds); after this pass,
194
+ // checkpoints cover the whole document and any jump is a few ms.
195
+ const requestIdle =
196
+ typeof requestIdleCallback === "function"
197
+ ? (/** @type {IdleRequestCallback} */ callback) =>
198
+ requestIdleCallback(callback, { timeout: 1000 })
199
+ : (/** @type {IdleRequestCallback} */ callback) =>
200
+ setTimeout(
201
+ () => callback({ didTimeout: false, timeRemaining: () => 8 }),
202
+ 16,
203
+ );
204
+ const cancelIdle =
205
+ typeof cancelIdleCallback === "function"
206
+ ? cancelIdleCallback
207
+ : clearTimeout;
208
+
209
+ /** @type {any} */
210
+ let aheadHandle;
211
+ // Bumped on every (re)schedule so a callback from an older document stops.
212
+ let aheadGeneration = 0;
213
+
214
+ function cancelTokenizeAhead() {
215
+ aheadGeneration++;
216
+ if (aheadHandle !== undefined) cancelIdle(aheadHandle);
217
+ aheadHandle = undefined;
218
+ }
219
+
220
+ function scheduleTokenizeAhead() {
221
+ cancelTokenizeAhead();
222
+ if (!tokenizeAhead || !doc) return;
223
+ const generation = aheadGeneration;
224
+ /** @param {IdleDeadline} deadline */
225
+ const step = (deadline) => {
226
+ aheadHandle = undefined;
227
+ if (generation !== aheadGeneration || !doc) return;
228
+ let done = false;
229
+ // At least one batch per callback, so a busy page still progresses.
230
+ do {
231
+ done = doc.tokenizeThrough(doc.tokenizedThrough() + checkpointInterval);
232
+ } while (!done && deadline.timeRemaining() > 2);
233
+ dispatch("tokenize", {
234
+ through: done ? doc.lineCount() : doc.tokenizedThrough(),
235
+ lineCount: doc.lineCount(),
236
+ });
237
+ if (!done) aheadHandle = requestIdle(step);
238
+ };
239
+ aheadHandle = requestIdle(step);
170
240
  }
171
241
 
172
242
  // Scroll/resize/overscan/lineHeight-driven window recompute.
@@ -180,12 +250,19 @@
180
250
  }
181
251
 
182
252
  /**
183
- * Scroll a given line into the rendered window.
253
+ * Scroll a given line into the rendered window. Jumps instantly (sets
254
+ * `scrollTop`), so there's no scroll animation.
184
255
  * @param {number} line
256
+ * @param {{ align?: "start" | "center" }} [options] Where the line lands
257
+ * in the viewport: the top edge (default) or the middle.
185
258
  */
186
- export function scrollToLine(line) {
259
+ export function scrollToLine(line, options = {}) {
187
260
  if (!container) return;
188
- const target = Math.max(0, Math.min(line, lineCount)) * lineHeight;
261
+ const lineTop = Math.max(0, Math.min(line, lineCount)) * lineHeight;
262
+ const target =
263
+ options.align === "center"
264
+ ? lineTop - (container.clientHeight - lineHeight) / 2
265
+ : lineTop;
189
266
  const maxScrollTop = Math.max(
190
267
  0,
191
268
  container.scrollHeight - container.clientHeight,
@@ -209,6 +286,7 @@
209
286
 
210
287
  return () => {
211
288
  cancelFrame();
289
+ cancelTokenizeAhead();
212
290
  resizeObserver?.disconnect();
213
291
  };
214
292
  });
@@ -27,6 +27,13 @@ export type HighlightVirtualProps = HTMLAttributes<HTMLPreElement> & {
27
27
  * @default 100
28
28
  */
29
29
  checkpointInterval?: number;
30
+
31
+ /**
32
+ * Tokenize the rest of the document in idle time after the first paint,
33
+ * so far jumps don't stall. Costs memory for the whole document up front.
34
+ * @default false
35
+ */
36
+ tokenizeAhead?: boolean;
30
37
  };
31
38
 
32
39
  export type HighlightVirtualEvents = {
@@ -34,6 +41,12 @@ export type HighlightVirtualEvents = {
34
41
  * Fired whenever the rendered window changes.
35
42
  */
36
43
  windowchange: CustomEvent<{ start: number; end: number; lineCount: number }>;
44
+
45
+ /**
46
+ * Fired after each idle slice of `tokenizeAhead`, with how many lines
47
+ * are tokenized so far. `through === lineCount` once it's done.
48
+ */
49
+ tokenize: CustomEvent<{ through: number; lineCount: number }>;
37
50
  };
38
51
 
39
52
  export default class HighlightVirtual extends SvelteComponentTyped<
@@ -41,6 +54,10 @@ export default class HighlightVirtual extends SvelteComponentTyped<
41
54
  HighlightVirtualEvents,
42
55
  Record<string, never>
43
56
  > {
44
- /** Scroll a given line into the rendered window. */
45
- scrollToLine(line: number): void;
57
+ /**
58
+ * Scroll a given line into the rendered window, without animation.
59
+ * `align` places the line at the viewport's top edge (default) or
60
+ * middle.
61
+ */
62
+ scrollToLine(line: number, options?: { align?: "start" | "center" }): void;
46
63
  }
@@ -101,11 +101,19 @@
101
101
  * that only closed over `resolvedLanguages` would not re-run when a
102
102
  * grammar finished loading (Svelte 3/4, and Svelte 5's `untrack` of
103
103
  * helper bodies).
104
+ *
105
+ * Takes the cache key, not the segment, so the result doesn't depend on
106
+ * the segment object. Svelte 5's legacy mode marks every keyed `{#each}`
107
+ * item as changed whenever `segments` changes, and treats any object as
108
+ * changed. A `language` read off the segment would reach every closed
109
+ * fence's HighlightStream on every chunk. Through the (string) key, it
110
+ * only changes when the key or a grammar does -
111
+ * tests/markdown-stream-updates.test.ts.
104
112
  * @param {Record<string, import("./languages").LanguageType<string>>} languages
105
- * @param {import("./fence.d.ts").FenceSegment} segment
113
+ * @param {string} key
106
114
  */
107
- function languageFor(languages, segment) {
108
- return languages[cacheKey(segment.lang)] ?? plaintext;
115
+ function languageFor(languages, key) {
116
+ return languages[key] ?? plaintext;
109
117
  }
110
118
 
111
119
  // Feed the splitter, then re-read its (identity-stable) segment list.
@@ -166,19 +174,18 @@
166
174
 
167
175
  <div class="shl-md" aria-busy={!done} {...$$restProps}>
168
176
  {#each segments as segment (segment.id)}
177
+ {@const languageKey =
178
+ segment.kind === "fence" ? cacheKey(segment.lang) : ""}
179
+ {@const language = languageFor(resolvedLanguages, languageKey)}
169
180
  {#if segment.kind === "text"}
170
181
  <slot name="text" {segment}>
171
182
  <div class="shl-md-text">{segment.text}</div>
172
183
  </slot>
173
184
  {:else}
174
- <slot
175
- name="fence"
176
- {segment}
177
- language={languageFor(resolvedLanguages, segment)}
178
- >
185
+ <slot name="fence" {segment} {language}>
179
186
  <HighlightStream
180
187
  code={segment.code}
181
- language={languageFor(resolvedLanguages, segment)}
188
+ {language}
182
189
  done={done || !segment.open}
183
190
  caret={caret && segment.id === lastOpenFenceId}
184
191
  {autoScroll}
package/README.md CHANGED
@@ -1978,9 +1978,11 @@ See [Code-splitting](#code-splitting) for the tradeoffs between a static import
1978
1978
  <HighlightVirtual language={json} code={hugeLogDump} style="height: 480px" />
1979
1979
  ```
1980
1980
 
1981
+ It's tested up to 500,000 lines (about 24 MB of TypeScript). The first paint takes milliseconds at any size. Tokenizing is lazy, so a first jump far ahead tokenizes everything before it: about 0.9 s to the end of 100k lines of TypeScript and 3.8 s for 500k, in Chrome on an M4 Max. After that, jumps anywhere take a few milliseconds. Add `tokenizeAhead` (`<HighlightVirtual tokenizeAhead ... />`) to tokenize the rest of the document in idle time after the first paint, a few milliseconds per slice, so far jumps are fast from the start. It's off by default because it retains memory for the whole document up front, about 117 MB per 100k lines of TypeScript today. `on:tokenize` reports its progress as `{ through, lineCount }`. The [large files](https://svhe.onrender.com/preview-large-file) page lets you try it.
1982
+
1981
1983
  The rendered `<pre>` is the scroll container itself -- size it with `style`/`class`/`$$restProps`, same as `Highlight`, but `white-space` can't be overridden this way: it's pinned to `pre` because the windowing math depends on a uniform line height. Content doesn't wrap (uniform line height is a v1 constraint, measured once from a rendered probe line). `overscan` (default `12`) controls how many extra lines render above/below the viewport; `checkpointInterval` (default `100`) controls how often the engine snapshots its parse state, trading a little memory for cheaper random access. Concretely, memory scales with `document lines / checkpointInterval` retained checkpoints, each holding a full engine snapshot plus open-scope/pending-HTML state -- and checkpoints are never evicted: they're retained for the entire lifetime of the `TokenizedDocument` instance, across any number of `append()` calls, until a `setCode()` call with unrelated content triggers a full reset. This is fine for the target "huge static document" use case, since checkpoints are bounded by that one document's size, but worth knowing for a long-lived instance that's repeatedly `setCode()`-reset with genuinely new documents rather than recreated. A consumer worried about retained memory can call `doc.checkpointCount()` directly rather than estimating it from `lineCount()`/`checkpointInterval`. Server-rendered output is the full document as plain escaped text (predictable cost for huge documents); the windowed, highlighted view takes over after hydration. In practice this means every page load flashes from unstyled monochrome text to highlighted, windowed content right after hydration, with no fade -- unlike `HighlightStream`'s default (non-`virtualize`) mode, which SSRs already-highlighted HTML. Nothing here requires a component change to soften today: since the container already needs an explicit size (`style`/`class`/`$$restProps`, above), reserving that same `min-height`/`height` up front prevents layout shift, and a CSS transition keyed off a `data-hydrated` attribute or class toggle you set yourself -- e.g. in `onMount` on a wrapping element -- can fade the flash instead of leaving it instant.
1982
1984
 
1983
- `on:windowchange` fires with `{ start, end, lineCount }` whenever the rendered window moves, so you can show something like "lines *N*-*M* of *T*" without counting DOM nodes yourself. `bind:this`, then call `scrollToLine(line)` to scroll a given line into view -- useful for a "jump to line" control -- without guessing at the line height yourself.
1985
+ `on:windowchange` fires with `{ start, end, lineCount }` whenever the rendered window moves, once the new rows are in the DOM, so you can show something like "lines *N*-*M* of *T*" or paint into the rows (as `highlightMatches` does) without counting DOM nodes yourself. `bind:this`, then call `scrollToLine(line, { align })` to scroll a given line into view -- useful for a "jump to line" control -- without guessing at the line height yourself.
1984
1986
 
1985
1987
  For custom virtualization, servers, or tests, `svelte-highlight/tokenized-document` exposes the same windowing primitive headlessly:
1986
1988
 
@@ -2048,7 +2050,7 @@ Each line is its own block-level `<div>`, not a row in a `<table>`/`<tr>` (the w
2048
2050
 
2049
2051
  Browser Cmd+F can't see rows a virtualized view (`HighlightVirtual`, `HighlightStream`'s `virtualize` mode) hasn't mounted, and neither of them ships a search box -- `svelte-highlight/search` is a headless find-in-document engine plus a DOM-painting helper, so any consumer can build one. No `<input>` component is exported; that's application UI, not a library primitive.
2050
2052
 
2051
- `createSearch(source)` accepts a plain `string` (split on `"\n"`), a `string[]` of lines, or a `TokenizedDocument` (duck-typed -- only `lineCount`/`lineRange` are used, never checked via `instanceof`), such as the one backing a `HighlightStream` in `virtualize` mode. Against a `TokenizedDocument`, repeated `query()` calls with unchanged text/options only rescan lines appended since the last call, instead of rescanning the whole document every time:
2053
+ `createSearch(source)` accepts a plain `string` (split on `"\n"`), a `string[]` of lines, or a `TokenizedDocument` (duck-typed -- only `lineCount`/`lineRange`/`textRange` are used, never checked via `instanceof`; plain text comes from `textRange` when present, so searching never tokenizes the document), such as the one backing a `HighlightStream` in `virtualize` mode. Against a `TokenizedDocument`, repeated `query()` calls with unchanged text/options only rescan lines appended since the last call, instead of rescanning the whole document every time:
2052
2054
 
2053
2055
  ```svelte
2054
2056
  <script>
@@ -2081,7 +2083,7 @@ Browser Cmd+F can't see rows a virtualized view (`HighlightVirtual`, `HighlightS
2081
2083
 
2082
2084
  function next() {
2083
2085
  const match = search.next();
2084
- if (match) ref.scrollToLine(match.line);
2086
+ if (match) ref.scrollToLine(match.line, { align: "center" });
2085
2087
  }
2086
2088
  </script>
2087
2089
 
@@ -2170,6 +2172,22 @@ parseAnsi("\x1b[31merror\x1b[0m");
2170
2172
  // => [{ text: "error", fg: { name: "red" } }]
2171
2173
  ```
2172
2174
 
2175
+ For streamed output, `createAnsiSession` from `svelte-highlight/ansi` parses chunk by chunk and keeps sequences that straddle a chunk boundary intact. Call `delta()` after each `append()` to get only what changed: truncate your copy of the segments to `start`, then append `segments`.
2176
+
2177
+ ```js
2178
+ import { createAnsiSession } from "svelte-highlight/ansi";
2179
+
2180
+ const session = createAnsiSession();
2181
+ const segments = [];
2182
+
2183
+ session.append("\x1b[31merr");
2184
+ session.append("or\x1b[0m done");
2185
+ const { start, segments: changed } = session.delta();
2186
+ segments.length = start;
2187
+ segments.push(...changed);
2188
+ // => [{ text: "error", fg: { name: "red" } }, { text: " done" }]
2189
+ ```
2190
+
2173
2191
  ## File Tabs
2174
2192
 
2175
2193
  `FileTabs` groups code snippets behind a tab strip, like files in an editor. Pass file names as `files`, then use `let:active` in the default slot to render the matching snippet.
@@ -2527,7 +2545,7 @@ Use `bind:this`, then call `scrollToLine(line)` -- works in both `virtualize` an
2527
2545
 
2528
2546
  - **on:highlight**: fired after each highlight pass, with `{ highlighted }` -- not dispatched when `virtualize` is set
2529
2547
  - **on:done**: fired after the final full highlight once `done` is set
2530
- - **on:windowchange**: fired with `{ start, end, lineCount }` whenever the rendered window moves -- only dispatched when `virtualize` is set
2548
+ - **on:windowchange**: fired with `{ start, end, lineCount }` whenever the rendered window moves, once the new rows are in the DOM -- only dispatched when `virtualize` is set
2531
2549
 
2532
2550
  ```svelte
2533
2551
  <HighlightStream
@@ -2587,16 +2605,18 @@ Use `bind:this`, then call `scrollToLine(line)` -- works in both `virtualize` an
2587
2605
  | language | { name: `string`; register: `object` } | N/A (required) |
2588
2606
  | overscan | `number` | `12` |
2589
2607
  | checkpointInterval | `number` | `100` |
2608
+ | tokenizeAhead | `boolean` | `false` |
2590
2609
 
2591
2610
  `$$restProps` are forwarded to the top-level `pre` element (the scroll container -- size it with `style`/`class`, but `white-space` is pinned to `pre` and can't be overridden this way).
2592
2611
 
2593
2612
  #### Methods
2594
2613
 
2595
- Use `bind:this`, then call `scrollToLine(line)`.
2614
+ Use `bind:this`, then call `scrollToLine(line, { align })`. It jumps without animation. `align` is `"start"` (default, line at the top edge) or `"center"` (line in the middle of the viewport).
2596
2615
 
2597
2616
  #### Dispatched Events
2598
2617
 
2599
- - **on:windowchange**: fired whenever the rendered window changes, with `{ start, end, lineCount }`
2618
+ - **on:windowchange**: fired whenever the rendered window changes, once the new rows are in the DOM, with `{ start, end, lineCount }`
2619
+ - **on:tokenize**: fired after each idle slice of `tokenizeAhead`, with `{ through, lineCount }`; `through === lineCount` once the whole document is tokenized
2600
2620
 
2601
2621
  ```svelte
2602
2622
  <HighlightVirtual language={json} code={hugeLogDump} style="height: 480px" />
@@ -2677,7 +2697,7 @@ See it as a complete page in [examples/cdn](examples/cdn).
2677
2697
 
2678
2698
  ### Stability tiers
2679
2699
 
2680
- - **Stable, semver-governed:** `ScopeEvent`, `TEXT`/`OPEN`/`CLOSE`, `TokenRange`, `HighlightResult`, `LineToken`, `Renderer`, `renderHtml`, `toRanges`, `extendLines`, `tokenLines`, `escapeHtml`, `createHtmlRenderer`, `createRangeRenderer`, `createLineRenderer`, `Registry` and its methods, `createRegistry`, `registerAll`, `StreamSession`, `TokenizedDocument`, `createTokenizedDocument`, `TextSegment`, `FenceSegment`, `MarkdownSegment`, `FenceSplitter`, `createFenceSplitter`, `SearchMatch`, `SearchOptions`, `Search`, `createSearch`, `highlightMatches`, `UnknownLanguageError`, `TokenizerLoopError`. `Snapshot` is a serializable format that round-trips within one library version, but is **not** guaranteed stable across versions — a snapshot from an older release may be rejected on resume. The same caveat applies to `TokenizedDocument`: its method surface (`setCode`/`append`/`lineCount`/`lineRange`/`tokenizedThrough`/`checkpointCount`) is stable and semver-governed, but internally it resumes from `Snapshot`s the same way `StreamSession` does, so anything that tried to serialize and later resume a `TokenizedDocument`'s internal state directly would hit the same cross-version instability -- the public API doesn't expose that today.
2700
+ - **Stable, semver-governed:** `ScopeEvent`, `TEXT`/`OPEN`/`CLOSE`, `TokenRange`, `HighlightResult`, `LineToken`, `Renderer`, `renderHtml`, `toRanges`, `extendLines`, `tokenLines`, `escapeHtml`, `createHtmlRenderer`, `createRangeRenderer`, `createLineRenderer`, `Registry` and its methods, `createRegistry`, `registerAll`, `StreamSession`, `TokenizedDocument`, `createTokenizedDocument`, `TextSegment`, `FenceSegment`, `MarkdownSegment`, `FenceSplitter`, `createFenceSplitter`, `SearchMatch`, `SearchOptions`, `Search`, `createSearch`, `highlightMatches`, `UnknownLanguageError`, `TokenizerLoopError`. `Snapshot` is a serializable format that round-trips within one library version, but is **not** guaranteed stable across versions — a snapshot from an older release may be rejected on resume. The same caveat applies to `TokenizedDocument`: its method surface (`setCode`/`append`/`lineCount`/`lineRange`/`textRange`/`tokenizedThrough`/`checkpointCount`) is stable and semver-governed, but internally it resumes from `Snapshot`s the same way `StreamSession` does, so anything that tried to serialize and later resume a `TokenizedDocument`'s internal state directly would hit the same cross-version instability -- the public API doesn't expose that today.
2681
2701
  - **Generated data, versioned with the library:** `GrammarIR`/`GrammarState`. These come from the build pipeline and are consumed by `registerAll`; treat them as opaque payloads whose field-level structure may change in any minor release. Always load grammars from the same package version as the engine.
2682
2702
  - **Experimental, may change in a minor release:** `createWorkerHighlighter`, `serveHighlighter`, `PostMessageTarget`, `WorkerHighlighter`, `WorkerSession`, `ServeHighlighterOptions` (`svelte-highlight/worker`). The wire protocol between the two halves is not part of the public contract — only the documented function behavior is.
2683
2703
 
package/ansi-color.js CHANGED
@@ -63,16 +63,44 @@ function indexedRgb(index) {
63
63
  ];
64
64
  }
65
65
 
66
+ /**
67
+ * `indexedHex` results by palette index, filled on first use. A colored log
68
+ * repeats the same few indices, and building each string costs a few
69
+ * array allocations (see bench/ansi.bench.ts).
70
+ * @type {string[]}
71
+ */
72
+ const INDEXED_HEX = [];
73
+
66
74
  /**
67
75
  * 256-color index to hex.
68
76
  * @param {number} index
69
77
  * @returns {string}
70
78
  */
71
79
  export function indexedHex(index) {
80
+ const cached = INDEXED_HEX[index];
81
+ if (cached !== undefined) return cached;
72
82
  const [r, g, b] = indexedRgb(index);
73
- return `#${[r, g, b].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
83
+ const hex = `#${[r, g, b].map((c) => c.toString(16).padStart(2, "0")).join("")}`;
84
+ // Cache only the 240 real palette slots, so an out-of-range index can't
85
+ // grow the table.
86
+ if (Number.isInteger(index) && index >= 16 && index <= 255) {
87
+ INDEXED_HEX[index] = hex;
88
+ }
89
+ return hex;
74
90
  }
75
91
 
92
+ /**
93
+ * `cssColor`'s `var(--ansi-<name>, <default>)` string for each of the 16
94
+ * named colors, built once instead of per segment.
95
+ * @type {Map<string, string>}
96
+ */
97
+ const NAMED_CSS = new Map(
98
+ Object.entries(ANSI_COLOR_DEFAULTS).map(([name, hex]) => [
99
+ name,
100
+ `var(--ansi-${name}, ${hex})`,
101
+ ]),
102
+ );
103
+
76
104
  /**
77
105
  * Parsed color to CSS (named colors use `--ansi-*` vars).
78
106
  * @param {AnsiColor} color
@@ -80,7 +108,10 @@ export function indexedHex(index) {
80
108
  */
81
109
  export function cssColor(color) {
82
110
  if ("name" in color) {
83
- return `var(--ansi-${color.name}, ${ANSI_COLOR_DEFAULTS[color.name]})`;
111
+ return (
112
+ NAMED_CSS.get(color.name) ??
113
+ `var(--ansi-${color.name}, ${ANSI_COLOR_DEFAULTS[color.name]})`
114
+ );
84
115
  }
85
116
  if ("rgb" in color) {
86
117
  return `rgb(${color.rgb[0]}, ${color.rgb[1]}, ${color.rgb[2]})`;
@@ -114,21 +145,42 @@ export function colorToRgb(color) {
114
145
  return indexedRgb(color.index);
115
146
  }
116
147
 
148
+ /**
149
+ * sRGB channel (0-255) to linear light.
150
+ * @param {number} c
151
+ * @returns {number}
152
+ */
153
+ function linearChannel(c) {
154
+ const v = c / 255;
155
+ return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
156
+ }
157
+
158
+ // `linearChannel` for every integer channel, so the per-segment contrast
159
+ // check reads a table instead of calling `**` (see bench/ansi.bench.ts).
160
+ const LINEAR = Array.from({ length: 256 }, (_, c) => linearChannel(c));
161
+
117
162
  /**
118
163
  * WCAG relative luminance.
119
164
  * @param {[number, number, number]} rgb
120
165
  * @returns {number}
121
166
  */
122
167
  export function luminance(rgb) {
123
- const toLinear = (/** @type {number} */ c) => {
124
- const v = c / 255;
125
- return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
126
- };
127
- return (
128
- 0.2126 * toLinear(rgb[0]) +
129
- 0.7152 * toLinear(rgb[1]) +
130
- 0.0722 * toLinear(rgb[2])
131
- );
168
+ // A channel outside the table (a truecolor value past 255) is computed
169
+ // directly, with the same result the table would hold.
170
+ const r = LINEAR[rgb[0]] ?? linearChannel(rgb[0]);
171
+ const g = LINEAR[rgb[1]] ?? linearChannel(rgb[1]);
172
+ const b = LINEAR[rgb[2]] ?? linearChannel(rgb[2]);
173
+ return 0.2126 * r + 0.7152 * g + 0.0722 * b;
174
+ }
175
+
176
+ /**
177
+ * WCAG contrast ratio from two relative luminances.
178
+ * @param {number} la
179
+ * @param {number} lb
180
+ * @returns {number}
181
+ */
182
+ function luminanceRatio(la, lb) {
183
+ return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
132
184
  }
133
185
 
134
186
  /**
@@ -138,9 +190,22 @@ export function luminance(rgb) {
138
190
  * @returns {number}
139
191
  */
140
192
  export function contrastRatio(a, b) {
141
- const la = luminance(a);
142
- const lb = luminance(b);
143
- return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
193
+ return luminanceRatio(luminance(a), luminance(b));
194
+ }
195
+
196
+ const BLACK_LUMINANCE = luminance(BLACK);
197
+ const WHITE_LUMINANCE = luminance(WHITE);
198
+
199
+ /**
200
+ * `readableForeground` for a background whose luminance is already known.
201
+ * @param {number} bgLuminance
202
+ * @returns {string}
203
+ */
204
+ function readableForegroundFor(bgLuminance) {
205
+ return luminanceRatio(BLACK_LUMINANCE, bgLuminance) >=
206
+ luminanceRatio(WHITE_LUMINANCE, bgLuminance)
207
+ ? "#000000"
208
+ : "#ffffff";
144
209
  }
145
210
 
146
211
  /**
@@ -149,9 +214,29 @@ export function contrastRatio(a, b) {
149
214
  * @returns {string}
150
215
  */
151
216
  export function readableForeground(bg) {
152
- return contrastRatio(BLACK, bg) >= contrastRatio(WHITE, bg)
153
- ? "#000000"
154
- : "#ffffff";
217
+ return readableForegroundFor(luminance(bg));
218
+ }
219
+
220
+ // Luminance of each named color's default and of the fallback foreground,
221
+ // computed once: `foregroundCss` needs them for most segments with a
222
+ // background, and re-parsing the hex string each time dominated the check.
223
+ /** @type {Map<string, number>} */
224
+ const NAMED_LUMINANCE = new Map(
225
+ Object.entries(ANSI_COLOR_DEFAULTS).map(([name, hex]) => [
226
+ name,
227
+ luminance(hexToRgb(hex)),
228
+ ]),
229
+ );
230
+ const FALLBACK_LUMINANCE = luminance(hexToRgb(FOREGROUND_FALLBACK));
231
+
232
+ /**
233
+ * `luminance(colorToRgb(color))`, without re-parsing a named color's hex.
234
+ * @param {AnsiColor} color
235
+ * @returns {number}
236
+ */
237
+ function colorLuminance(color) {
238
+ const named = "name" in color ? NAMED_LUMINANCE.get(color.name) : undefined;
239
+ return named ?? luminance(colorToRgb(color));
155
240
  }
156
241
 
157
242
  /**
@@ -164,11 +249,13 @@ export function foregroundCss(segment, autoContrast) {
164
249
  // Concealed text is rendered transparent (layout and copy text stay).
165
250
  if (segment.conceal) return "transparent";
166
251
  if (autoContrast && segment.bg) {
167
- const bg = colorToRgb(segment.bg);
168
- const fg = segment.fg
169
- ? colorToRgb(segment.fg)
170
- : hexToRgb(FOREGROUND_FALLBACK);
171
- if (contrastRatio(fg, bg) < CONTRAST_TARGET) return readableForeground(bg);
252
+ // Each luminance is computed once and reused for both the contrast check
253
+ // and the black/white pick (it used to be computed up to three times).
254
+ const bg = colorLuminance(segment.bg);
255
+ const fg = segment.fg ? colorLuminance(segment.fg) : FALLBACK_LUMINANCE;
256
+ if (luminanceRatio(fg, bg) < CONTRAST_TARGET) {
257
+ return readableForegroundFor(bg);
258
+ }
172
259
  }
173
260
  return segment.fg ? cssColor(segment.fg) : undefined;
174
261
  }
package/ansi-output.js ADDED
@@ -0,0 +1,93 @@
1
+ /**
2
+ * AnsiOutput's per-update pipeline: feed `text` into an incremental ANSI
3
+ * session, then compute each segment's class and inline style for the
4
+ * template. Split out of the component so it can be benched
5
+ * (bench/ansi.bench.ts) and tested without a DOM.
6
+ */
7
+
8
+ import { createAnsiSession } from "./ansi.js";
9
+ import { classNames, inlineStyle } from "./ansi-color.js";
10
+
11
+ /** @typedef {import("./ansi.d.ts").AnsiSegment} AnsiSegment */
12
+
13
+ /**
14
+ * @typedef {{
15
+ * text: string;
16
+ * class: string | undefined;
17
+ * style: string | undefined;
18
+ * link: string | undefined;
19
+ * }} RenderedAnsiSegment
20
+ */
21
+
22
+ /**
23
+ * @param {AnsiSegment} segment
24
+ * @param {boolean} autoContrast
25
+ * @returns {RenderedAnsiSegment}
26
+ */
27
+ function render(segment, autoContrast) {
28
+ return {
29
+ text: segment.text,
30
+ class: classNames(segment),
31
+ style: inlineStyle(segment, autoContrast),
32
+ link: segment.link,
33
+ };
34
+ }
35
+
36
+ /**
37
+ * @returns {{
38
+ * update: (text: string, autoContrast: boolean) => RenderedAnsiSegment[],
39
+ * }}
40
+ */
41
+ export function createAnsiOutput() {
42
+ let session = createAnsiSession();
43
+ // Prefix of `text` already fed to `session`. If `text` stops starting
44
+ // with this, treat it as a restart (not an append) and re-parse fresh.
45
+ let fedText = "";
46
+ /** @type {RenderedAnsiSegment[]} */
47
+ const rendered = [];
48
+ /** @type {boolean | undefined} */
49
+ let renderedContrast;
50
+
51
+ return {
52
+ /**
53
+ * Returns the same array on every call, updated in place; entries for
54
+ * unchanged segments keep their identity across calls.
55
+ * @param {string} text
56
+ * @param {boolean} autoContrast
57
+ * @returns {RenderedAnsiSegment[]}
58
+ */
59
+ update(text, autoContrast) {
60
+ // Re-parsing the whole string on every change is O(n^2) over a
61
+ // growing (live-tailed or streamed) `text`, so only feed the new
62
+ // suffix when `text` grows by a pure append; anything else gets a
63
+ // fresh session.
64
+ if (text.startsWith(fedText)) {
65
+ if (text.length > fedText.length) {
66
+ session.append(text.slice(fedText.length));
67
+ fedText = text;
68
+ }
69
+ } else {
70
+ session = createAnsiSession();
71
+ session.append(text);
72
+ fedText = text;
73
+ }
74
+
75
+ // Only the segments the session reports as changed get a fresh
76
+ // class/style. Copying every segment and recomputing all of them
77
+ // per chunk made a streamed 20,000-segment output quadratic
78
+ // (bench/ansi.bench.ts, "repeated append: AnsiOutput update").
79
+ let { start, segments } = session.delta();
80
+ if (autoContrast !== renderedContrast) {
81
+ // Every inline style depends on `autoContrast`; rebuild them all.
82
+ renderedContrast = autoContrast;
83
+ start = 0;
84
+ segments = session.segments();
85
+ }
86
+ rendered.length = start;
87
+ for (const segment of segments) {
88
+ rendered.push(render(segment, autoContrast));
89
+ }
90
+ return rendered;
91
+ },
92
+ };
93
+ }
package/ansi.d.ts CHANGED
@@ -57,6 +57,14 @@ export type AnsiSegment = {
57
57
  */
58
58
  export declare function parseAnsi(text: string): AnsiSegment[];
59
59
 
60
+ /** Changed segments from {@link AnsiSession.delta}. */
61
+ export interface AnsiDelta {
62
+ /** Index of the first changed segment. */
63
+ start: number;
64
+ /** Segments from `start` to the end, including the live trailing one. */
65
+ segments: AnsiSegment[];
66
+ }
67
+
60
68
  /** An incremental ANSI parser session; see {@link createAnsiSession}. */
61
69
  export interface AnsiSession {
62
70
  /** Feed the next chunk of text into the session. */
@@ -66,6 +74,16 @@ export interface AnsiSession {
66
74
  * buffered-but-not-yet-flushed text. Does not mutate session state.
67
75
  */
68
76
  segments(): AnsiSegment[];
77
+ /**
78
+ * What changed since the previous `delta()` call (or since the session
79
+ * started): `segments().slice(start)`, the same tail `segments()` would
80
+ * return from index `start`. Every segment before `start` is unchanged
81
+ * since the previous call, so a consumer that mirrors the segments can
82
+ * truncate its copy to `start` and append `segments`, paying for the
83
+ * new segments instead of the whole output. A `\r` overwrite can move
84
+ * `start` below the previous call's end. Does not affect `segments()`.
85
+ */
86
+ delta(): AnsiDelta;
69
87
  /**
70
88
  * Flush remaining buffered text and drop any still-pending incomplete
71
89
  * sequence, then return the final segments. Calling `append()` after