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.
- package/AnsiOutput.svelte +6 -30
- package/FileTabs.svelte +3 -1
- package/HighlightEditable.svelte +115 -143
- package/HighlightStream.svelte +44 -48
- package/HighlightStyle.svelte +9 -21
- package/HighlightVirtual.svelte +82 -4
- package/HighlightVirtual.svelte.d.ts +19 -2
- package/MarkdownStream.svelte +16 -9
- package/README.md +27 -7
- package/ansi-color.js +109 -22
- package/ansi-output.js +93 -0
- package/ansi.d.ts +18 -0
- package/ansi.js +85 -24
- package/css-walk.js +9 -12
- package/editable-css-paint.js +118 -0
- package/editable-dom-paint.js +217 -146
- package/editable-line-dom.js +241 -0
- package/engine.d.ts +28 -6
- package/engine.js +707 -144
- package/fence.d.ts +5 -5
- package/fence.js +196 -56
- package/highlight-theme.js +10 -4
- package/incremental-tokenize.js +95 -17
- package/package.json +1 -1
- package/preprocessor.js +16 -2
- package/scoped.js +15 -13
- package/search.d.ts +6 -4
- package/search.js +427 -85
- package/stream-final-highlight.js +52 -0
- package/stream-highlighted.js +17 -0
- package/stream-preview.js +7 -2
- package/stream-regenerate.js +262 -0
- package/style-registry.js +60 -0
- package/text-diff.js +66 -18
- package/tokenized-document.d.ts +8 -0
- package/tokenized-document.js +60 -15
- package/worker.js +14 -2
package/HighlightVirtual.svelte
CHANGED
|
@@ -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
|
-
|
|
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
|
|
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
|
-
/**
|
|
45
|
-
|
|
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
|
}
|
package/MarkdownStream.svelte
CHANGED
|
@@ -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 {
|
|
113
|
+
* @param {string} key
|
|
106
114
|
*/
|
|
107
|
-
function languageFor(languages,
|
|
108
|
-
return languages[
|
|
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
|
|
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
|
-
|
|
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
|
|
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
|
-
|
|
124
|
-
|
|
125
|
-
|
|
126
|
-
|
|
127
|
-
|
|
128
|
-
|
|
129
|
-
|
|
130
|
-
|
|
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
|
-
|
|
142
|
-
|
|
143
|
-
|
|
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
|
|
153
|
-
|
|
154
|
-
|
|
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
|
-
|
|
168
|
-
|
|
169
|
-
|
|
170
|
-
|
|
171
|
-
if (
|
|
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
|