@cavelang/highlight 0.35.0 → 0.36.0

package/README.md

@@ -3,7 +3,10 @@
 CAVE syntax highlighting for terminals — web-tree-sitter over the
 [`@cavelang/tree-sitter-cave`](../tree-sitter-cave) grammar, colored by the
 grammar's own `queries/highlights.scm` so terminal output and editor
-highlighting share one source of truth.
+highlighting share one source of truth. Explicit full-claim `@claim`
+markers use keyword highlighting; reserved and numeric-looking subjects remain
+entities, while a
+trailing `@claim` remains a context label.
 
 ```ts
 import { highlighter } from '@cavelang/highlight'
@@ -21,3 +24,37 @@ process.stdout.write(ansi('auth/middleware USES jwt @ 90% #security\n'))
 
 The default theme leaves entities uncolored — they are the bulk of every
 line; color carries the structure (verbs, values, metadata, comments).
+Theme lookup uses only the object's own entries, with the longest dotted prefix
+winning; inherited properties never supply styles. Custom `paint` spans use
+JavaScript UTF-16 offsets and must be ordered, non-overlapping integer ranges
+within `0..text.length`, with `start <= end`. Adjacent and empty ranges are
+allowed. Invalid ranges throw `TypeError` rather than silently duplicating or
+truncating source text. The grammar-backed `spans()` already supplies valid
+ordered ranges.
+`paint()` captures the supplied range values before looking up theme styles.
+Theme getters cannot rewrite those validated ranges or extend the in-progress
+render by changing the caller's span array.
+
+`highlighter()` shares one in-flight or successful initialization per process.
+A failed initialization rejects its callers and clears that cache, allowing a
+later call to retry after the underlying problem is repaired. It does not retry
+automatically or create a retry loop.
+
+The shared factory releases its compiled query and allocated parser if parser
+setup fails. Per-call parse trees are released even when capture extraction
+throws. `createHighlighter(language, querySource)` and
+`createBrowserHighlighter(options)` return an `OwnedHighlighter`. Call its
+`close()` when finished to release the parser and compiled query. Closing twice
+is harmless; `spans()` and `ansi()` throw after closure. The initialized language
+and WASM runtime are not unloaded.
+
+When setup or capture fails and releasing its resources also fails, an
+`AggregateError` retains the original error as its cause and first entry and
+the cleanup error as its second entry. Multiple owned-resource cleanup failures
+are retained in parser, then query order. Single errors propagate unchanged;
+every resource release is attempted, and `close()` never retries failed cleanup.
+
+`highlighter()` returns the shared `Highlighter` interface without `close()`;
+its parser and query remain available for the process lifetime. The website's
+cached browser highlighter likewise lives for the page lifetime. Components
+borrowing that cache must not close it on unmount.

package/dist/src/browser.d.ts

@@ -1,5 +1,5 @@
 /** Browser entry point for CAVE's Tree-sitter highlighter. */
-import { type Highlighter } from './core.ts';
+import { type OwnedHighlighter } from './core.ts';
 export * from './core.ts';
 export type BrowserHighlighterOptions = {
     /** URL emitted for `web-tree-sitter/web-tree-sitter.wasm`. */
@@ -10,5 +10,5 @@ export type BrowserHighlighterOptions = {
     readonly querySource: string;
 };
 /** Loads the parser and CAVE grammar WASM, then creates a browser highlighter. */
-export declare const createBrowserHighlighter: ({ parserWasmUrl, languageWasmUrl, querySource, }: BrowserHighlighterOptions) => Promise<Highlighter>;
+export declare const createBrowserHighlighter: ({ parserWasmUrl, languageWasmUrl, querySource, }: BrowserHighlighterOptions) => Promise<OwnedHighlighter>;
 //# sourceMappingURL=browser.d.ts.map

package/dist/src/browser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAG9D,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAE/D,cAAc,WAAW,CAAA;AAEzB,MAAM,MAAM,yBAAyB,GAAG;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,GAAU,kDAI5C,yBAAyB,KAAG,OAAO,CAAC,WAAW,CAIjD,CAAA"}
+{"version":3,"file":"browser.d.ts","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAG9D,OAAO,EAAqB,KAAK,gBAAgB,EAAE,MAAM,WAAW,CAAA;AAEpE,cAAc,WAAW,CAAA;AAEzB,MAAM,MAAM,yBAAyB,GAAG;IACtC,8DAA8D;IAC9D,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAA;IAC9B,yDAAyD;IACzD,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAA;IAChC,2DAA2D;IAC3D,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAA;CAC7B,CAAA;AAED,kFAAkF;AAClF,eAAO,MAAM,wBAAwB,GAAU,kDAI5C,yBAAyB,KAAG,OAAO,CAAC,gBAAgB,CAItD,CAAA"}

package/dist/src/browser.js.map

@@ -1 +1 @@
-{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAE9D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,iBAAiB,EAAoB,MAAM,WAAW,CAAA;AAE/D,cAAc,WAAW,CAAA;AAWzB,kFAAkF;AAClF,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,EAAE,EAC7C,aAAa,EACb,eAAe,EACf,WAAW,GACe,EAAwB,EAAE;IACpD,MAAM,MAAM,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE,CAAC,CAAA;IACtD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;IACrD,OAAO,iBAAiB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAA;AACjD,CAAC,CAAA"}
+{"version":3,"file":"browser.js","sourceRoot":"","sources":["../../src/browser.ts"],"names":[],"mappings":"AAAA,8DAA8D;AAE9D,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,iBAAiB,EAAyB,MAAM,WAAW,CAAA;AAEpE,cAAc,WAAW,CAAA;AAWzB,kFAAkF;AAClF,MAAM,CAAC,MAAM,wBAAwB,GAAG,KAAK,EAAE,EAC7C,aAAa,EACb,eAAe,EACf,WAAW,GACe,EAA6B,EAAE;IACzD,MAAM,MAAM,CAAC,IAAI,CAAC,EAAE,UAAU,EAAE,GAAG,EAAE,CAAC,aAAa,EAAE,CAAC,CAAA;IACtD,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,eAAe,CAAC,CAAA;IACrD,OAAO,iBAAiB,CAAC,QAAQ,EAAE,WAAW,CAAC,CAAA;AACjD,CAAC,CAAA"}

package/dist/src/core.d.ts

@@ -18,8 +18,13 @@ export type Highlighter = {
     /** `text` with ANSI colors applied per `theme` (default {@link defaultTheme}). */
     readonly ansi: (text: string, theme?: Theme) => string;
 };
+/** A factory-created highlighter whose parser and query belong to the caller. */
+export type OwnedHighlighter = Highlighter & {
+    /** Release the parser and query once; subsequent spans/ansi calls throw. */
+    readonly close: () => void;
+};
 /** Renders `spans` over `text` as ANSI; exported for custom span sources. */
 export declare const paint: (text: string, spans: readonly Span[], theme?: Theme) => string;
 /** Creates a highlighter from an initialized Tree-sitter language and query. */
-export declare const createHighlighter: (language: Language, querySource: string) => Highlighter;
+export declare const createHighlighter: (language: Language, querySource: string) => OwnedHighlighter;
 //# sourceMappingURL=core.d.ts.map

package/dist/src/core.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE9D,kFAAkF;AAClF,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,oFAAoF;AACpF,MAAM,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAEpD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,KAc1B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,EAAE,CAAA;IACjD,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,MAAM,CAAA;CACvD,CAAA;AAeD,6EAA6E;AAC7E,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,EAAE,OAAO,SAAS,IAAI,EAAE,EAAE,QAAO,KAAoB,KAAG,MAWzF,CAAA;AAED,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,GAAI,UAAU,QAAQ,EAAE,aAAa,MAAM,KAAG,WAiC3E,CAAA"}
+{"version":3,"file":"core.d.ts","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"AAAA,OAAO,EAAiB,KAAK,QAAQ,EAAE,MAAM,iBAAiB,CAAA;AAE9D,kFAAkF;AAClF,MAAM,MAAM,IAAI,GAAG;IACjB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;IACtB,QAAQ,CAAC,GAAG,EAAE,MAAM,CAAA;IACpB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CACzB,CAAA;AAED,oFAAoF;AACpF,MAAM,MAAM,KAAK,GAAG,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;AAEpD;;;GAGG;AACH,eAAO,MAAM,YAAY,EAAE,KAc1B,CAAA;AAED,MAAM,MAAM,WAAW,GAAG;IACxB,kEAAkE;IAClE,QAAQ,CAAC,KAAK,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,SAAS,IAAI,EAAE,CAAA;IACjD,kFAAkF;IAClF,QAAQ,CAAC,IAAI,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,KAAK,KAAK,MAAM,CAAA;CACvD,CAAA;AAED,iFAAiF;AACjF,MAAM,MAAM,gBAAgB,GAAG,WAAW,GAAG;IAC3C,4EAA4E;IAC5E,QAAQ,CAAC,KAAK,EAAE,MAAM,IAAI,CAAA;CAC3B,CAAA;AAeD,6EAA6E;AAC7E,eAAO,MAAM,KAAK,GAAI,MAAM,MAAM,EAAE,OAAO,SAAS,IAAI,EAAE,EAAE,QAAO,KAAoB,KAAG,MAgBzF,CAAA;AAeD,gFAAgF;AAChF,eAAO,MAAM,iBAAiB,GAAI,UAAU,QAAQ,EAAE,aAAa,MAAM,KAAG,gBAoD3E,CAAA"}

package/dist/src/core.js

@@ -21,7 +21,7 @@ export const defaultTheme = {
 /** Longest dotted prefix of `capture` present in `theme`. */
 const styleOf = (theme, capture) => {
     for (let name = capture;; name = name.slice(0, name.lastIndexOf('.'))) {
-        const style = theme[name];
+        const style = Object.hasOwn(theme, name) ? theme[name] : undefined;
         if (style !== undefined) {
             return style;
         }
@@ -32,9 +32,14 @@ const styleOf = (theme, capture) => {
 };
 /** Renders `spans` over `text` as ANSI; exported for custom span sources. */
 export const paint = (text, spans, theme = defaultTheme) => {
+    const ranges = spans.map(({ start, end, capture }) => ({ start, end, capture }));
     let out = '';
     let at = 0;
-    for (const span of spans) {
+    for (const span of ranges) {
+        if (!Number.isSafeInteger(span.start) || !Number.isSafeInteger(span.end) ||
+            span.start < at || span.end < span.start || span.end > text.length) {
+            throw new TypeError('Highlight spans must be ordered, non-overlapping integer ranges within the source');
+        }
         const style = styleOf(theme, span.capture);
         out += text.slice(at, span.start);
         const piece = text.slice(span.start, span.end);
@@ -43,17 +48,64 @@ export const paint = (text, spans, theme = defaultTheme) => {
     }
     return out + text.slice(at);
 };
+/** Release an owned resource without replacing a primary failure. */
+const withCleanup = (body, cleanup, message) => {
+    let result;
+    try {
+        result = body();
+    }
+    catch (error) {
+        try {
+            cleanup();
+        }
+        catch (cleanupError) {
+            throw new AggregateError([error, cleanupError], message, { cause: error });
+        }
+        throw error;
+    }
+    cleanup();
+    return result;
+};
 /** Creates a highlighter from an initialized Tree-sitter language and query. */
 export const createHighlighter = (language, querySource) => {
     const query = new Query(language, querySource);
-    const parser = new Parser();
-    parser.setLanguage(language);
+    let parser;
+    const release = () => {
+        const errors = [];
+        try {
+            parser?.delete();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        try {
+            query.delete();
+        }
+        catch (error) {
+            errors.push(error);
+        }
+        if (errors.length === 1)
+            throw errors[0];
+        if (errors.length > 1) {
+            throw new AggregateError(errors, 'Highlighter cleanup failed', { cause: errors[0] });
+        }
+    };
+    try {
+        parser = new Parser();
+        parser.setLanguage(language);
+    }
+    catch (error) {
+        withCleanup(() => { throw error; }, release, 'Highlighter setup failed and cleanup also failed');
+    }
+    let closed = false;
     const spans = (text) => {
+        if (closed)
+            throw new Error('Highlighter is closed');
         const tree = parser.parse(text);
         if (tree === null) {
             return [];
         }
-        try {
+        return withCleanup(() => {
             const all = query.captures(tree.rootNode)
                 .map(({ name, node }) => ({ start: node.startIndex, end: node.endIndex, capture: name }))
                 .filter(span => span.end > span.start)
@@ -69,14 +121,17 @@ export const createHighlighter = (language, querySource) => {
                 }
             }
             return disjoint;
-        }
-        finally {
-            tree.delete();
-        }
+        }, () => tree.delete(), 'Highlight capture failed and tree cleanup also failed');
     };
     return {
         spans,
-        ansi: (text, theme = defaultTheme) => paint(text, spans(text), theme)
+        ansi: (text, theme = defaultTheme) => paint(text, spans(text), theme),
+        close: () => {
+            if (closed)
+                return;
+            closed = true;
+            release();
+        }
     };
 };
 //# sourceMappingURL=core.js.map

package/dist/src/core.js.map

@@ -1 +1 @@
-{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"core.js","sourceRoot":"","sources":["../../src/core.ts"],"names":[],"mappings":"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"}

package/dist/src/index.d.ts

@@ -13,6 +13,6 @@
  */
 import { type Highlighter } from './core.ts';
 export * from './core.ts';
-/** The process-wide highlighter; loads the grammar WASM on first call. */
+/** The process-wide highlighter; failed loads may be retried by later calls. */
 export declare const highlighter: () => Promise<Highlighter>;
 //# sourceMappingURL=index.d.ts.map

package/dist/src/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAE/D,cAAc,WAAW,CAAA;AAazB,0EAA0E;AAC1E,eAAO,MAAM,WAAW,QAAO,OAAO,CAAC,WAAW,CAC7B,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAKH,OAAO,EAAqB,KAAK,WAAW,EAAE,MAAM,WAAW,CAAA;AAE/D,cAAc,WAAW,CAAA;AAczB,gFAAgF;AAChF,eAAO,MAAM,WAAW,QAAO,OAAO,CAAC,WAAW,CAI9C,CAAA"}

package/dist/src/index.js

@@ -20,9 +20,13 @@ const resolvePath = (specifier) => fileURLToPath(import.meta.resolve(specifier))
 const create = async () => {
     await Parser.init();
     const language = await Language.load(resolvePath('@cavelang/tree-sitter-cave/wasm'));
-    return createHighlighter(language, readFileSync(resolvePath('@cavelang/tree-sitter-cave/highlights'), 'utf8'));
+    const { spans, ansi } = createHighlighter(language, readFileSync(resolvePath('@cavelang/tree-sitter-cave/highlights'), 'utf8'));
+    return { spans, ansi };
 };
 let cached;
-/** The process-wide highlighter; loads the grammar WASM on first call. */
-export const highlighter = () => cached ??= create();
+/** The process-wide highlighter; failed loads may be retried by later calls. */
+export const highlighter = () => cached ??= create().catch(error => {
+    cached = undefined;
+    throw error;
+});
 //# sourceMappingURL=index.js.map

package/dist/src/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,iBAAiB,EAAoB,MAAM,WAAW,CAAA;AAE/D,cAAc,WAAW,CAAA;AAEzB,MAAM,WAAW,GAAG,CAAC,SAAiB,EAAU,EAAE,CAChD,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAA;AAE/C,MAAM,MAAM,GAAG,KAAK,IAA0B,EAAE;IAC9C,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;IACnB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,iCAAiC,CAAC,CAAC,CAAA;IACpF,OAAO,iBAAiB,CAAC,QAAQ,EAAE,YAAY,CAAC,WAAW,CAAC,uCAAuC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;AAChH,CAAC,CAAA;AAED,IAAI,MAAwC,CAAA;AAE5C,0EAA0E;AAC1E,MAAM,CAAC,MAAM,WAAW,GAAG,GAAyB,EAAE,CACpD,MAAM,KAAK,MAAM,EAAE,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,YAAY,EAAE,MAAM,SAAS,CAAA;AACtC,OAAO,EAAE,aAAa,EAAE,MAAM,UAAU,CAAA;AACxC,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,MAAM,iBAAiB,CAAA;AAClD,OAAO,EAAE,iBAAiB,EAAoB,MAAM,WAAW,CAAA;AAE/D,cAAc,WAAW,CAAA;AAEzB,MAAM,WAAW,GAAG,CAAC,SAAiB,EAAU,EAAE,CAChD,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,OAAO,CAAC,SAAS,CAAC,CAAC,CAAA;AAE/C,MAAM,MAAM,GAAG,KAAK,IAA0B,EAAE;IAC9C,MAAM,MAAM,CAAC,IAAI,EAAE,CAAA;IACnB,MAAM,QAAQ,GAAG,MAAM,QAAQ,CAAC,IAAI,CAAC,WAAW,CAAC,iCAAiC,CAAC,CAAC,CAAA;IACpF,MAAM,EAAE,KAAK,EAAE,IAAI,EAAE,GAAG,iBAAiB,CAAC,QAAQ,EAAE,YAAY,CAAC,WAAW,CAAC,uCAAuC,CAAC,EAAE,MAAM,CAAC,CAAC,CAAA;IAC/H,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAA;AACxB,CAAC,CAAA;AAED,IAAI,MAAwC,CAAA;AAE5C,gFAAgF;AAChF,MAAM,CAAC,MAAM,WAAW,GAAG,GAAyB,EAAE,CACpD,MAAM,KAAK,MAAM,EAAE,CAAC,KAAK,CAAC,KAAK,CAAC,EAAE;IAChC,MAAM,GAAG,SAAS,CAAA;IAClB,MAAM,KAAK,CAAA;AACb,CAAC,CAAC,CAAA"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cavelang/highlight",
-  "version": "0.35.0",
+  "version": "0.36.0",
   "type": "module",
   "description": "CAVE syntax highlighting — web-tree-sitter over the @cavelang/tree-sitter-cave grammar, rendered to ANSI for terminals.",
   "keywords": [
@@ -21,7 +21,7 @@
     "directory": "packages/highlight"
   },
   "engines": {
-    "node": "^22.18.0 || ^24.0.0 || ^26.0.0"
+    "node": "^24.16.0 || ^26.1.0"
   },
   "exports": {
     ".": {
@@ -47,9 +47,9 @@
     "access": "public"
   },
   "dependencies": {
-    "@types/emscripten": "^1.41.5",
-    "web-tree-sitter": "^0.26.13",
-    "@cavelang/tree-sitter-cave": "0.35.0"
+    "@types/emscripten": "^1.41.6",
+    "web-tree-sitter": "^0.27.0",
+    "@cavelang/tree-sitter-cave": "0.36.0"
   },
   "scripts": {
     "build": "tsc -b",

package/src/browser.ts

@@ -1,7 +1,7 @@
 /** Browser entry point for CAVE's Tree-sitter highlighter. */
 
 import { Language, Parser } from 'web-tree-sitter'
-import { createHighlighter, type Highlighter } from './core.ts'
+import { createHighlighter, type OwnedHighlighter } from './core.ts'
 
 export * from './core.ts'
 
@@ -19,7 +19,7 @@ export const createBrowserHighlighter = async ({
   parserWasmUrl,
   languageWasmUrl,
   querySource,
-}: BrowserHighlighterOptions): Promise<Highlighter> => {
+}: BrowserHighlighterOptions): Promise<OwnedHighlighter> => {
   await Parser.init({ locateFile: () => parserWasmUrl })
   const language = await Language.load(languageWasmUrl)
   return createHighlighter(language, querySource)

package/src/core.ts

@@ -37,10 +37,16 @@ export type Highlighter = {
   readonly ansi: (text: string, theme?: Theme) => string
 }
 
+/** A factory-created highlighter whose parser and query belong to the caller. */
+export type OwnedHighlighter = Highlighter & {
+  /** Release the parser and query once; subsequent spans/ansi calls throw. */
+  readonly close: () => void
+}
+
 /** Longest dotted prefix of `capture` present in `theme`. */
 const styleOf = (theme: Theme, capture: string): undefined | string => {
   for (let name = capture; ; name = name.slice(0, name.lastIndexOf('.'))) {
-    const style = theme[name]
+    const style = Object.hasOwn(theme, name) ? theme[name] : undefined
     if (style !== undefined) {
       return style
     }
@@ -52,9 +58,14 @@ const styleOf = (theme: Theme, capture: string): undefined | string => {
 
 /** Renders `spans` over `text` as ANSI; exported for custom span sources. */
 export const paint = (text: string, spans: readonly Span[], theme: Theme = defaultTheme): string => {
+  const ranges = spans.map(({ start, end, capture }) => ({ start, end, capture }))
   let out = ''
   let at = 0
-  for (const span of spans) {
+  for (const span of ranges) {
+    if (!Number.isSafeInteger(span.start) || !Number.isSafeInteger(span.end) ||
+        span.start < at || span.end < span.start || span.end > text.length) {
+      throw new TypeError('Highlight spans must be ordered, non-overlapping integer ranges within the source')
+    }
     const style = styleOf(theme, span.capture)
     out += text.slice(at, span.start)
     const piece = text.slice(span.start, span.end)
@@ -64,17 +75,46 @@ export const paint = (text: string, spans: readonly Span[], theme: Theme = defau
   return out + text.slice(at)
 }
 
+/** Release an owned resource without replacing a primary failure. */
+const withCleanup = <T>(body: () => T, cleanup: () => void, message: string): T => {
+  let result: T
+  try { result = body() } catch (error) {
+    try { cleanup() } catch (cleanupError) {
+      throw new AggregateError([error, cleanupError], message, { cause: error })
+    }
+    throw error
+  }
+  cleanup()
+  return result
+}
+
 /** Creates a highlighter from an initialized Tree-sitter language and query. */
-export const createHighlighter = (language: Language, querySource: string): Highlighter => {
+export const createHighlighter = (language: Language, querySource: string): OwnedHighlighter => {
   const query = new Query(language, querySource)
-  const parser = new Parser()
-  parser.setLanguage(language)
+  let parser: Parser | undefined
+  const release = (): void => {
+    const errors: unknown[] = []
+    try { parser?.delete() } catch (error) { errors.push(error) }
+    try { query.delete() } catch (error) { errors.push(error) }
+    if (errors.length === 1) throw errors[0]
+    if (errors.length > 1) {
+      throw new AggregateError(errors, 'Highlighter cleanup failed', { cause: errors[0] })
+    }
+  }
+  try {
+    parser = new Parser()
+    parser.setLanguage(language)
+  } catch (error) {
+    withCleanup(() => { throw error }, release, 'Highlighter setup failed and cleanup also failed')
+  }
+  let closed = false
   const spans = (text: string): readonly Span[] => {
-    const tree = parser.parse(text)
+    if (closed) throw new Error('Highlighter is closed')
+    const tree = parser!.parse(text)
     if (tree === null) {
       return []
     }
-    try {
+    return withCleanup(() => {
       const all = query.captures(tree.rootNode)
         .map(({ name, node }) => ({ start: node.startIndex, end: node.endIndex, capture: name }))
         .filter(span => span.end > span.start)
@@ -90,12 +130,15 @@ export const createHighlighter = (language: Language, querySource: string): High
         }
       }
       return disjoint
-    } finally {
-      tree.delete()
-    }
+    }, () => tree.delete(), 'Highlight capture failed and tree cleanup also failed')
   }
   return {
     spans,
-    ansi: (text, theme = defaultTheme) => paint(text, spans(text), theme)
+    ansi: (text, theme = defaultTheme) => paint(text, spans(text), theme),
+    close: () => {
+      if (closed) return
+      closed = true
+      release()
+    }
   }
 }

package/src/index.ts

@@ -25,11 +25,15 @@ const resolvePath = (specifier: string): string =>
 const create = async (): Promise<Highlighter> => {
   await Parser.init()
   const language = await Language.load(resolvePath('@cavelang/tree-sitter-cave/wasm'))
-  return createHighlighter(language, readFileSync(resolvePath('@cavelang/tree-sitter-cave/highlights'), 'utf8'))
+  const { spans, ansi } = createHighlighter(language, readFileSync(resolvePath('@cavelang/tree-sitter-cave/highlights'), 'utf8'))
+  return { spans, ansi }
 }
 
 let cached: undefined | Promise<Highlighter>
 
-/** The process-wide highlighter; loads the grammar WASM on first call. */
+/** The process-wide highlighter; failed loads may be retried by later calls. */
 export const highlighter = (): Promise<Highlighter> =>
-  cached ??= create()
+  cached ??= create().catch(error => {
+    cached = undefined
+    throw error
+  })