@vielzeug/scout 2.1.1 → 2.2.0

package/dist/adapters.cjs

@@ -1,2 +1,2 @@
-const e=require("./_index-state.cjs");function t(t,n){let r,i=-1,a=new Set;return(o,s)=>{let c=e.getIndexRevision(t);return(s!==r||c!==i)&&(r=s,i=c,a=new Set(t.search(s,n).map(e=>e.item))),a.has(o)}}function n(e,t,n){let r=new Set(e.search(t,n).map(e=>e.item));return e=>r.has(e)}exports.toFilterPredicate=n,exports.toSearchMatcher=t;
+function e(e,t){let n,r=-1,i=new Set;return(a,o)=>((o!==n||e.revision!==r)&&(n=o,r=e.revision,i=new Set(e.search(o,t).map(e=>e.item))),i.has(a))}function t(e,t,n){let r=new Set(e.search(t,n).map(e=>e.item));return e=>r.has(e)}exports.toFilterPredicate=t,exports.toSearchMatcher=e;
 //# sourceMappingURL=adapters.cjs.map

package/dist/adapters.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.cjs","names":[],"sources":["../src/adapters.ts"],"sourcesContent":["import type { ScoutIndex } from './scout-index';\nimport type { SearchConstraints } from './types';\n\nimport { getIndexRevision } from './_index-state';\n\n/**\n * Adapts a `ScoutIndex` to sourcerer's explicit local `match` callback.\n * Caches one match set per query so local filtering does not repeat index work per item.\n */\nexport function toSearchMatcher<T>(\n  index: ScoutIndex<T>,\n  options?: SearchConstraints,\n): (item: T, query: string) => boolean {\n  let lastQuery: string | undefined;\n  let lastRevision = -1;\n  let matches = new Set<T>();\n\n  return (item, query) => {\n    const revision = getIndexRevision(index);\n\n    if (query !== lastQuery || revision !== lastRevision) {\n      lastQuery = query;\n      lastRevision = revision;\n      matches = new Set(index.search(query, options).map((result) => result.item));\n    }\n\n    return matches.has(item);\n  };\n}\n\n/**\n * Returns a predicate that returns `true` for items matching `query` in the given index.\n *\n * The predicate is computed once at call time — call `toFilterPredicate` again if the\n * query or corpus changes.\n *\n * Compatible with `Array.filter`, `vault`'s `query.filter()`, or any predicate pipeline.\n */\nexport function toFilterPredicate<T>(\n  index: ScoutIndex<T>,\n  query: string,\n  options?: SearchConstraints,\n): (item: T) => boolean {\n  const matchSet = new Set(index.search(query, options).map((result) => result.item));\n\n  return (item) => matchSet.has(item);\n}\n"],"mappings":"sCASA,SAAgB,EACd,EACA,EACqC,CACrC,IAAI,EACA,EAAe,GACf,EAAU,IAAI,IAElB,OAAQ,EAAM,IAAU,CACtB,IAAM,EAAW,EAAA,iBAAiB,CAAK,EAQvC,OANI,IAAU,GAAa,IAAa,KACtC,EAAY,EACZ,EAAe,EACf,EAAU,IAAI,IAAI,EAAM,OAAO,EAAO,CAAO,CAAC,CAAC,IAAK,GAAW,EAAO,IAAI,CAAC,GAGtE,EAAQ,IAAI,CAAI,CACzB,CACF,CAUA,SAAgB,EACd,EACA,EACA,EACsB,CACtB,IAAM,EAAW,IAAI,IAAI,EAAM,OAAO,EAAO,CAAO,CAAC,CAAC,IAAK,GAAW,EAAO,IAAI,CAAC,EAElF,MAAQ,IAAS,EAAS,IAAI,CAAI,CACpC"}
+{"version":3,"file":"adapters.cjs","names":[],"sources":["../src/adapters.ts"],"sourcesContent":["import type { ScoutIndex } from './scout-index';\nimport type { SearchConstraints } from './types';\n\n/**\n * Adapts a `ScoutIndex` to sourcerer's explicit local `match` callback.\n * Caches one match set per query so local filtering does not repeat index work per item.\n */\nexport function toSearchMatcher<T>(\n  index: ScoutIndex<T>,\n  options?: SearchConstraints,\n): (item: T, query: string) => boolean {\n  let lastQuery: string | undefined;\n  let lastRevision = -1;\n  let matches = new Set<T>();\n\n  return (item, query) => {\n    if (query !== lastQuery || index.revision !== lastRevision) {\n      lastQuery = query;\n      lastRevision = index.revision;\n      matches = new Set(index.search(query, options).map((result) => result.item));\n    }\n\n    return matches.has(item);\n  };\n}\n\n/**\n * Returns a predicate that returns `true` for items matching `query` in the given index.\n *\n * The predicate is computed once at call time — call `toFilterPredicate` again if the\n * query or corpus changes.\n *\n * Compatible with `Array.filter`, `vault`'s `query.filter()`, or any predicate pipeline.\n */\nexport function toFilterPredicate<T>(\n  index: ScoutIndex<T>,\n  query: string,\n  options?: SearchConstraints,\n): (item: T) => boolean {\n  const matchSet = new Set(index.search(query, options).map((result) => result.item));\n\n  return (item) => matchSet.has(item);\n}\n"],"mappings":"AAOA,SAAgB,EACd,EACA,EACqC,CACrC,IAAI,EACA,EAAe,GACf,EAAU,IAAI,IAElB,OAAQ,EAAM,MACR,IAAU,GAAa,EAAM,WAAa,KAC5C,EAAY,EACZ,EAAe,EAAM,SACrB,EAAU,IAAI,IAAI,EAAM,OAAO,EAAO,CAAO,CAAC,CAAC,IAAK,GAAW,EAAO,IAAI,CAAC,GAGtE,EAAQ,IAAI,CAAI,EAE3B,CAUA,SAAgB,EACd,EACA,EACA,EACsB,CACtB,IAAM,EAAW,IAAI,IAAI,EAAM,OAAO,EAAO,CAAO,CAAC,CAAC,IAAK,GAAW,EAAO,IAAI,CAAC,EAElF,MAAQ,IAAS,EAAS,IAAI,CAAI,CACpC"}

package/dist/adapters.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAIjD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAgBrC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAItB"}
+{"version":3,"file":"adapters.d.ts","sourceRoot":"","sources":["../src/adapters.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,SAAS,CAAC;AAEjD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,CAAC,EAC/B,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EACpB,OAAO,CAAC,EAAE,iBAAiB,GAC1B,CAAC,IAAI,EAAE,CAAC,EAAE,KAAK,EAAE,MAAM,KAAK,OAAO,CAcrC;AAED;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EACjC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EACpB,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,iBAAiB,GAC1B,CAAC,IAAI,EAAE,CAAC,KAAK,OAAO,CAItB"}

package/dist/adapters.js

@@ -1,17 +1,13 @@
-import { getIndexRevision as e } from "./_index-state.js";
 //#region src/adapters.ts
-function t(t, n) {
-	let r, i = -1, a = /* @__PURE__ */ new Set();
-	return (o, s) => {
-		let c = e(t);
-		return (s !== r || c !== i) && (r = s, i = c, a = new Set(t.search(s, n).map((e) => e.item))), a.has(o);
-	};
+function e(e, t) {
+	let n, r = -1, i = /* @__PURE__ */ new Set();
+	return (a, o) => ((o !== n || e.revision !== r) && (n = o, r = e.revision, i = new Set(e.search(o, t).map((e) => e.item))), i.has(a));
 }
-function n(e, t, n) {
+function t(e, t, n) {
 	let r = new Set(e.search(t, n).map((e) => e.item));
 	return (e) => r.has(e);
 }
 //#endregion
-export { n as toFilterPredicate, t as toSearchMatcher };
+export { t as toFilterPredicate, e as toSearchMatcher };
 
 //# sourceMappingURL=adapters.js.map

package/dist/adapters.js.map

@@ -1 +1 @@
-{"version":3,"file":"adapters.js","names":[],"sources":["../src/adapters.ts"],"sourcesContent":["import type { ScoutIndex } from './scout-index';\nimport type { SearchConstraints } from './types';\n\nimport { getIndexRevision } from './_index-state';\n\n/**\n * Adapts a `ScoutIndex` to sourcerer's explicit local `match` callback.\n * Caches one match set per query so local filtering does not repeat index work per item.\n */\nexport function toSearchMatcher<T>(\n  index: ScoutIndex<T>,\n  options?: SearchConstraints,\n): (item: T, query: string) => boolean {\n  let lastQuery: string | undefined;\n  let lastRevision = -1;\n  let matches = new Set<T>();\n\n  return (item, query) => {\n    const revision = getIndexRevision(index);\n\n    if (query !== lastQuery || revision !== lastRevision) {\n      lastQuery = query;\n      lastRevision = revision;\n      matches = new Set(index.search(query, options).map((result) => result.item));\n    }\n\n    return matches.has(item);\n  };\n}\n\n/**\n * Returns a predicate that returns `true` for items matching `query` in the given index.\n *\n * The predicate is computed once at call time — call `toFilterPredicate` again if the\n * query or corpus changes.\n *\n * Compatible with `Array.filter`, `vault`'s `query.filter()`, or any predicate pipeline.\n */\nexport function toFilterPredicate<T>(\n  index: ScoutIndex<T>,\n  query: string,\n  options?: SearchConstraints,\n): (item: T) => boolean {\n  const matchSet = new Set(index.search(query, options).map((result) => result.item));\n\n  return (item) => matchSet.has(item);\n}\n"],"mappings":";;AASA,SAAgB,EACd,GACA,GACqC;CACrC,IAAI,GACA,IAAe,IACf,oBAAU,IAAI,IAAO;CAEzB,QAAQ,GAAM,MAAU;EACtB,IAAM,IAAW,EAAiB,CAAK;EAQvC,QANI,MAAU,KAAa,MAAa,OACtC,IAAY,GACZ,IAAe,GACf,IAAU,IAAI,IAAI,EAAM,OAAO,GAAO,CAAO,CAAC,CAAC,KAAK,MAAW,EAAO,IAAI,CAAC,IAGtE,EAAQ,IAAI,CAAI;CACzB;AACF;AAUA,SAAgB,EACd,GACA,GACA,GACsB;CACtB,IAAM,IAAW,IAAI,IAAI,EAAM,OAAO,GAAO,CAAO,CAAC,CAAC,KAAK,MAAW,EAAO,IAAI,CAAC;CAElF,QAAQ,MAAS,EAAS,IAAI,CAAI;AACpC"}
+{"version":3,"file":"adapters.js","names":[],"sources":["../src/adapters.ts"],"sourcesContent":["import type { ScoutIndex } from './scout-index';\nimport type { SearchConstraints } from './types';\n\n/**\n * Adapts a `ScoutIndex` to sourcerer's explicit local `match` callback.\n * Caches one match set per query so local filtering does not repeat index work per item.\n */\nexport function toSearchMatcher<T>(\n  index: ScoutIndex<T>,\n  options?: SearchConstraints,\n): (item: T, query: string) => boolean {\n  let lastQuery: string | undefined;\n  let lastRevision = -1;\n  let matches = new Set<T>();\n\n  return (item, query) => {\n    if (query !== lastQuery || index.revision !== lastRevision) {\n      lastQuery = query;\n      lastRevision = index.revision;\n      matches = new Set(index.search(query, options).map((result) => result.item));\n    }\n\n    return matches.has(item);\n  };\n}\n\n/**\n * Returns a predicate that returns `true` for items matching `query` in the given index.\n *\n * The predicate is computed once at call time — call `toFilterPredicate` again if the\n * query or corpus changes.\n *\n * Compatible with `Array.filter`, `vault`'s `query.filter()`, or any predicate pipeline.\n */\nexport function toFilterPredicate<T>(\n  index: ScoutIndex<T>,\n  query: string,\n  options?: SearchConstraints,\n): (item: T) => boolean {\n  const matchSet = new Set(index.search(query, options).map((result) => result.item));\n\n  return (item) => matchSet.has(item);\n}\n"],"mappings":";AAOA,SAAgB,EACd,GACA,GACqC;CACrC,IAAI,GACA,IAAe,IACf,oBAAU,IAAI,IAAO;CAEzB,QAAQ,GAAM,QACR,MAAU,KAAa,EAAM,aAAa,OAC5C,IAAY,GACZ,IAAe,EAAM,UACrB,IAAU,IAAI,IAAI,EAAM,OAAO,GAAO,CAAO,CAAC,CAAC,KAAK,MAAW,EAAO,IAAI,CAAC,IAGtE,EAAQ,IAAI,CAAI;AAE3B;AAUA,SAAgB,EACd,GACA,GACA,GACsB;CACtB,IAAM,IAAW,IAAI,IAAI,EAAM,OAAO,GAAO,CAAO,CAAC,CAAC,KAAK,MAAW,EAAO,IAAI,CAAC;CAElF,QAAQ,MAAS,EAAS,IAAI,CAAI;AACpC"}

package/dist/errors.cjs

@@ -1,2 +1,2 @@
-var e=class e extends Error{constructor(e,t){super(e,t),this.name=new.target.name,Object.setPrototypeOf(this,new.target.prototype)}static is(t){return t instanceof e}},t=class extends e{},n=class extends e{};exports.ScoutConfigurationError=n,exports.ScoutDisposedError=t,exports.ScoutError=e;
+var e=class extends Error{constructor(e,t){super(e,t),this.name=new.target.name,Object.setPrototypeOf(this,new.target.prototype)}},t=class extends e{},n=class extends e{};exports.ScoutConfigurationError=n,exports.ScoutDisposedError=t,exports.ScoutError=e;
 //# sourceMappingURL=errors.cjs.map

package/dist/errors.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"errors.cjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/** Base class for all scout errors. Use `instanceof ScoutError` to catch any scout-originated error. */\nexport class ScoutError extends Error {\n  constructor(message: string, opts?: ErrorOptions) {\n    super(message, opts);\n    this.name = new.target.name;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  static is(err: unknown): err is ScoutError {\n    return err instanceof ScoutError;\n  }\n}\n\n/** Thrown when a method is called on a disposed search state instance. */\nexport class ScoutDisposedError extends ScoutError {}\n\n/** Thrown when an index, search, or reactive search receives an invalid configuration. */\nexport class ScoutConfigurationError extends ScoutError {}\n"],"mappings":"AACA,IAAa,EAAb,MAAa,UAAmB,KAAM,CACpC,YAAY,EAAiB,EAAqB,CAChD,MAAM,EAAS,CAAI,EACnB,KAAK,KAAO,WAAW,KACvB,OAAO,eAAe,KAAM,WAAW,SAAS,CAClD,CAEA,OAAO,GAAG,EAAiC,CACzC,OAAO,aAAe,CACxB,CACF,EAGa,EAAb,cAAwC,CAAW,CAAC,EAGvC,EAAb,cAA6C,CAAW,CAAC"}
+{"version":3,"file":"errors.cjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/** Base class for all scout errors. Use `instanceof ScoutError` to catch any scout-originated error. */\nexport class ScoutError extends Error {\n  constructor(message: string, opts?: ErrorOptions) {\n    super(message, opts);\n    this.name = new.target.name;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Thrown when a method is called on a disposed search state instance. */\nexport class ScoutDisposedError extends ScoutError {}\n\n/** Thrown when an index, search, or reactive search receives an invalid configuration. */\nexport class ScoutConfigurationError extends ScoutError {}\n"],"mappings":"AACA,IAAa,EAAb,cAAgC,KAAM,CACpC,YAAY,EAAiB,EAAqB,CAChD,MAAM,EAAS,CAAI,EACnB,KAAK,KAAO,WAAW,KACvB,OAAO,eAAe,KAAM,WAAW,SAAS,CAClD,CACF,EAGa,EAAb,cAAwC,CAAW,CAAC,EAGvC,EAAb,cAA6C,CAAW,CAAC"}

package/dist/errors.d.ts

@@ -1,7 +1,6 @@
 /** Base class for all scout errors. Use `instanceof ScoutError` to catch any scout-originated error. */
 export declare class ScoutError extends Error {
     constructor(message: string, opts?: ErrorOptions);
-    static is(err: unknown): err is ScoutError;
 }
 /** Thrown when a method is called on a disposed search state instance. */
 export declare class ScoutDisposedError extends ScoutError {

package/dist/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY;IAMhD,MAAM,CAAC,EAAE,CAAC,GAAG,EAAE,OAAO,GAAG,GAAG,IAAI,UAAU;CAG3C;AAED,0EAA0E;AAC1E,qBAAa,kBAAmB,SAAQ,UAAU;CAAG;AAErD,0FAA0F;AAC1F,qBAAa,uBAAwB,SAAQ,UAAU;CAAG"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../src/errors.ts"],"names":[],"mappings":"AAAA,wGAAwG;AACxG,qBAAa,UAAW,SAAQ,KAAK;gBACvB,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,YAAY;CAKjD;AAED,0EAA0E;AAC1E,qBAAa,kBAAmB,SAAQ,UAAU;CAAG;AAErD,0FAA0F;AAC1F,qBAAa,uBAAwB,SAAQ,UAAU;CAAG"}

package/dist/errors.js

@@ -1,11 +1,8 @@
 //#region src/errors.ts
-var e = class e extends Error {
+var e = class extends Error {
 	constructor(e, t) {
 		super(e, t), this.name = new.target.name, Object.setPrototypeOf(this, new.target.prototype);
 	}
-	static is(t) {
-		return t instanceof e;
-	}
 }, t = class extends e {}, n = class extends e {};
 //#endregion
 export { n as ScoutConfigurationError, t as ScoutDisposedError, e as ScoutError };

package/dist/errors.js.map

@@ -1 +1 @@
-{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/** Base class for all scout errors. Use `instanceof ScoutError` to catch any scout-originated error. */\nexport class ScoutError extends Error {\n  constructor(message: string, opts?: ErrorOptions) {\n    super(message, opts);\n    this.name = new.target.name;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n\n  static is(err: unknown): err is ScoutError {\n    return err instanceof ScoutError;\n  }\n}\n\n/** Thrown when a method is called on a disposed search state instance. */\nexport class ScoutDisposedError extends ScoutError {}\n\n/** Thrown when an index, search, or reactive search receives an invalid configuration. */\nexport class ScoutConfigurationError extends ScoutError {}\n"],"mappings":";AACA,IAAa,IAAb,MAAa,UAAmB,MAAM;CACpC,YAAY,GAAiB,GAAqB;EAGhD,AAFA,MAAM,GAAS,CAAI,GACnB,KAAK,OAAO,WAAW,MACvB,OAAO,eAAe,MAAM,WAAW,SAAS;CAClD;CAEA,OAAO,GAAG,GAAiC;EACzC,OAAO,aAAe;CACxB;AACF,GAGa,IAAb,cAAwC,EAAW,CAAC,GAGvC,IAAb,cAA6C,EAAW,CAAC"}
+{"version":3,"file":"errors.js","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/** Base class for all scout errors. Use `instanceof ScoutError` to catch any scout-originated error. */\nexport class ScoutError extends Error {\n  constructor(message: string, opts?: ErrorOptions) {\n    super(message, opts);\n    this.name = new.target.name;\n    Object.setPrototypeOf(this, new.target.prototype);\n  }\n}\n\n/** Thrown when a method is called on a disposed search state instance. */\nexport class ScoutDisposedError extends ScoutError {}\n\n/** Thrown when an index, search, or reactive search receives an invalid configuration. */\nexport class ScoutConfigurationError extends ScoutError {}\n"],"mappings":";AACA,IAAa,IAAb,cAAgC,MAAM;CACpC,YAAY,GAAiB,GAAqB;EAGhD,AAFA,MAAM,GAAS,CAAI,GACnB,KAAK,OAAO,WAAW,MACvB,OAAO,eAAe,MAAM,WAAW,SAAS;CAClD;AACF,GAGa,IAAb,cAAwC,EAAW,CAAC,GAGvC,IAAb,cAA6C,EAAW,CAAC"}

package/dist/highlight.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"highlight.cjs","names":[],"sources":["../src/highlight.ts"],"sourcesContent":["import type { HighlightPart, SearchResult } from './types';\n\nimport { tokenize } from './tokenize';\n\n/**\n * Finds character ranges within `text` where `query` words appear.\n * Ranges are sorted and overlapping ranges are merged.\n *\n * Useful when you need to apply match ranges to a different string than the\n * indexed field value (e.g. a truncated preview or a differently formatted display string).\n *\n * @param text - The string to search within.\n * @param query - Raw query text. It is normalized with Scout's tokenizer before literal lookup.\n * @returns Sorted, non-overlapping `[start, end]` character ranges.\n */\nexport function findMatchRanges(text: string, query: string): [number, number][] {\n  const lower = text.toLowerCase();\n  const words = tokenize(query).split(' ').filter(Boolean);\n  const ranges: [number, number][] = [];\n\n  for (const word of words) {\n    let pos = 0;\n\n    while (pos < lower.length) {\n      const idx = lower.indexOf(word, pos);\n\n      if (idx === -1) break;\n\n      ranges.push([idx, idx + word.length]);\n      pos = idx + 1;\n    }\n  }\n\n  ranges.sort((a, b) => a[0] - b[0]);\n\n  const merged: [number, number][] = [];\n\n  for (const range of ranges) {\n    const last = merged[merged.length - 1];\n\n    if (last && range[0] <= last[1]) {\n      last[1] = Math.max(last[1], range[1]);\n    } else {\n      merged.push([range[0], range[1]]);\n    }\n  }\n\n  return merged;\n}\n\n/**\n * Splits `text` into highlighted and unhighlighted fragments using match `ranges`.\n *\n * Ranges must be sorted and non-overlapping (as produced by `SearchResult.matches[n].ranges`).\n * Use the returned parts to render highlighted text in a UI component.\n *\n * **`part.text` is the original, unescaped field value** (e.g. a user's name, bio, or\n * product title) — this function does no HTML escaping. Render each part via safe DOM APIs\n * (`textContent`, a framework's text binding) and wrap `highlighted` parts in your own\n * element (e.g. `<mark>`); never concatenate `part.text` into an HTML string for\n * `innerHTML` — that reintroduces the XSS risk this structured return shape avoids.\n *\n * @example\n * ```ts\n * highlight('Hello World', [[0, 5]]);\n * // [{ text: 'Hello', highlighted: true }, { text: ' World', highlighted: false }]\n *\n * highlight('Hello World', [[0, 5], [6, 11]]);\n * // [\n * //   { text: 'Hello', highlighted: true },\n * //   { text: ' ',     highlighted: false },\n * //   { text: 'World', highlighted: true },\n * // ]\n * ```\n *\n * @param text - The original field value to split.\n * @param ranges - Sorted, non-overlapping `[start, end]` ranges from `FieldMatch.ranges`.\n * @returns An array of `HighlightPart` objects. Returns an empty array for an empty `text`.\n */\nexport function highlight(text: string, ranges: [number, number][]): HighlightPart[] {\n  if (!text) return [];\n\n  if (!ranges.length) return [{ highlighted: false, text }];\n\n  const parts: HighlightPart[] = [];\n  let cursor = 0;\n\n  for (const [start, end] of ranges) {\n    if (start > cursor) {\n      parts.push({ highlighted: false, text: text.slice(cursor, start) });\n    }\n\n    if (end > start) {\n      parts.push({ highlighted: true, text: text.slice(start, end) });\n    }\n\n    cursor = end;\n  }\n\n  if (cursor < text.length) {\n    parts.push({ highlighted: false, text: text.slice(cursor) });\n  }\n\n  return parts;\n}\n\n/**\n * Finds the match ranges for `field` in `result` and splits `text` into\n * highlighted and unhighlighted fragments in one step.\n *\n * This is the ergonomic shorthand for the common pattern:\n * ```ts\n * const match = result.matches.find(m => m.field === 'name');\n * const parts = highlight(item.name, match?.ranges ?? []);\n * ```\n *\n * @example\n * ```ts\n * for (const result of index.search('alice')) {\n *   const parts = highlightField(result, 'name', result.item.name);\n *   console.log(parts.map(p => p.highlighted ? `[${p.text}]` : p.text).join(''));\n * }\n * ```\n *\n * @param result - A `SearchResult` from `ScoutIndex.search()`.\n * @param field - The field name to look up in `result.matches`.\n * @param text - The original field value string to split.\n * @returns An array of `HighlightPart` objects.\n */\nexport function highlightField<T>(result: SearchResult<T>, field: keyof T & string, text: string): HighlightPart[] {\n  const match = result.matches.find((m) => m.field === field);\n\n  return highlight(text, match?.ranges ?? []);\n}\n"],"mappings":"kCAeA,SAAgB,EAAgB,EAAc,EAAmC,CAC/E,IAAM,EAAQ,EAAK,YAAY,EACzB,EAAQ,EAAA,SAAS,CAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,EACjD,EAA6B,CAAC,EAEpC,IAAK,IAAM,KAAQ,EAAO,CACxB,IAAI,EAAM,EAEV,KAAO,EAAM,EAAM,QAAQ,CACzB,IAAM,EAAM,EAAM,QAAQ,EAAM,CAAG,EAEnC,GAAI,IAAQ,GAAI,MAEhB,EAAO,KAAK,CAAC,EAAK,EAAM,EAAK,MAAM,CAAC,EACpC,EAAM,EAAM,CACd,CACF,CAEA,EAAO,MAAM,EAAG,IAAM,EAAE,GAAK,EAAE,EAAE,EAEjC,IAAM,EAA6B,CAAC,EAEpC,IAAK,IAAM,KAAS,EAAQ,CAC1B,IAAM,EAAO,EAAO,EAAO,OAAS,GAEhC,GAAQ,EAAM,IAAM,EAAK,GAC3B,EAAK,GAAK,KAAK,IAAI,EAAK,GAAI,EAAM,EAAE,EAEpC,EAAO,KAAK,CAAC,EAAM,GAAI,EAAM,EAAE,CAAC,CAEpC,CAEA,OAAO,CACT,CA+BA,SAAgB,EAAU,EAAc,EAA6C,CACnF,GAAI,CAAC,EAAM,MAAO,CAAC,EAEnB,GAAI,CAAC,EAAO,OAAQ,MAAO,CAAC,CAAE,YAAa,GAAO,MAAK,CAAC,EAExD,IAAM,EAAyB,CAAC,EAC5B,EAAS,EAEb,IAAK,GAAM,CAAC,EAAO,KAAQ,EACrB,EAAQ,GACV,EAAM,KAAK,CAAE,YAAa,GAAO,KAAM,EAAK,MAAM,EAAQ,CAAK,CAAE,CAAC,EAGhE,EAAM,GACR,EAAM,KAAK,CAAE,YAAa,GAAM,KAAM,EAAK,MAAM,EAAO,CAAG,CAAE,CAAC,EAGhE,EAAS,EAOX,OAJI,EAAS,EAAK,QAChB,EAAM,KAAK,CAAE,YAAa,GAAO,KAAM,EAAK,MAAM,CAAM,CAAE,CAAC,EAGtD,CACT,CAyBA,SAAgB,EAAkB,EAAyB,EAAyB,EAA+B,CAGjH,OAAO,EAAU,EAFH,EAAO,QAAQ,KAAM,GAAM,EAAE,QAAU,CAE9B,CAAA,EAAO,QAAU,CAAC,CAAC,CAC5C"}
+{"version":3,"file":"highlight.cjs","names":[],"sources":["../src/highlight.ts"],"sourcesContent":["import { tokenize } from './tokenize';\nimport type { HighlightPart, SearchResult } from './types';\n\n/**\n * Finds character ranges within `text` where `query` words appear.\n * Ranges are sorted and overlapping ranges are merged.\n *\n * Useful when you need to apply match ranges to a different string than the\n * indexed field value (e.g. a truncated preview or a differently formatted display string).\n *\n * @param text - The string to search within.\n * @param query - Raw query text. It is normalized with Scout's tokenizer before literal lookup.\n * @returns Sorted, non-overlapping `[start, end]` character ranges.\n */\nexport function findMatchRanges(text: string, query: string): [number, number][] {\n  const lower = text.toLowerCase();\n  const words = tokenize(query).split(' ').filter(Boolean);\n  const ranges: [number, number][] = [];\n\n  for (const word of words) {\n    let pos = 0;\n\n    while (pos < lower.length) {\n      const idx = lower.indexOf(word, pos);\n\n      if (idx === -1) break;\n\n      ranges.push([idx, idx + word.length]);\n      pos = idx + 1;\n    }\n  }\n\n  ranges.sort((a, b) => a[0] - b[0]);\n\n  const merged: [number, number][] = [];\n\n  for (const range of ranges) {\n    const last = merged[merged.length - 1];\n\n    if (last && range[0] <= last[1]) {\n      last[1] = Math.max(last[1], range[1]);\n    } else {\n      merged.push([range[0], range[1]]);\n    }\n  }\n\n  return merged;\n}\n\n/**\n * Splits `text` into highlighted and unhighlighted fragments using match `ranges`.\n *\n * Ranges must be sorted and non-overlapping (as produced by `SearchResult.matches[n].ranges`).\n * Use the returned parts to render highlighted text in a UI component.\n *\n * **`part.text` is the original, unescaped field value** (e.g. a user's name, bio, or\n * product title) — this function does no HTML escaping. Render each part via safe DOM APIs\n * (`textContent`, a framework's text binding) and wrap `highlighted` parts in your own\n * element (e.g. `<mark>`); never concatenate `part.text` into an HTML string for\n * `innerHTML` — that reintroduces the XSS risk this structured return shape avoids.\n *\n * @example\n * ```ts\n * highlight('Hello World', [[0, 5]]);\n * // [{ text: 'Hello', highlighted: true }, { text: ' World', highlighted: false }]\n *\n * highlight('Hello World', [[0, 5], [6, 11]]);\n * // [\n * //   { text: 'Hello', highlighted: true },\n * //   { text: ' ',     highlighted: false },\n * //   { text: 'World', highlighted: true },\n * // ]\n * ```\n *\n * @param text - The original field value to split.\n * @param ranges - Sorted, non-overlapping `[start, end]` ranges from `FieldMatch.ranges`.\n * @returns An array of `HighlightPart` objects. Returns an empty array for an empty `text`.\n */\nexport function highlight(text: string, ranges: [number, number][]): HighlightPart[] {\n  if (!text) return [];\n\n  if (!ranges.length) return [{ highlighted: false, text }];\n\n  const parts: HighlightPart[] = [];\n  let cursor = 0;\n\n  for (const [start, end] of ranges) {\n    if (start > cursor) {\n      parts.push({ highlighted: false, text: text.slice(cursor, start) });\n    }\n\n    if (end > start) {\n      parts.push({ highlighted: true, text: text.slice(start, end) });\n    }\n\n    cursor = end;\n  }\n\n  if (cursor < text.length) {\n    parts.push({ highlighted: false, text: text.slice(cursor) });\n  }\n\n  return parts;\n}\n\n/**\n * Finds the match ranges for `field` in `result` and splits `text` into\n * highlighted and unhighlighted fragments in one step.\n *\n * This is the ergonomic shorthand for the common pattern:\n * ```ts\n * const match = result.matches.find(m => m.field === 'name');\n * const parts = highlight(item.name, match?.ranges ?? []);\n * ```\n *\n * @example\n * ```ts\n * for (const result of index.search('alice')) {\n *   const parts = highlightField(result, 'name', result.item.name);\n *   console.log(parts.map(p => p.highlighted ? `[${p.text}]` : p.text).join(''));\n * }\n * ```\n *\n * @param result - A `SearchResult` from `ScoutIndex.search()`.\n * @param field - The field name to look up in `result.matches`.\n * @param text - The original field value string to split.\n * @returns An array of `HighlightPart` objects.\n */\nexport function highlightField<T>(result: SearchResult<T>, field: keyof T & string, text: string): HighlightPart[] {\n  const match = result.matches.find((m) => m.field === field);\n\n  return highlight(text, match?.ranges ?? []);\n}\n"],"mappings":"kCAcA,SAAgB,EAAgB,EAAc,EAAmC,CAC/E,IAAM,EAAQ,EAAK,YAAY,EACzB,EAAQ,EAAA,SAAS,CAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,EACjD,EAA6B,CAAC,EAEpC,IAAK,IAAM,KAAQ,EAAO,CACxB,IAAI,EAAM,EAEV,KAAO,EAAM,EAAM,QAAQ,CACzB,IAAM,EAAM,EAAM,QAAQ,EAAM,CAAG,EAEnC,GAAI,IAAQ,GAAI,MAEhB,EAAO,KAAK,CAAC,EAAK,EAAM,EAAK,MAAM,CAAC,EACpC,EAAM,EAAM,CACd,CACF,CAEA,EAAO,MAAM,EAAG,IAAM,EAAE,GAAK,EAAE,EAAE,EAEjC,IAAM,EAA6B,CAAC,EAEpC,IAAK,IAAM,KAAS,EAAQ,CAC1B,IAAM,EAAO,EAAO,EAAO,OAAS,GAEhC,GAAQ,EAAM,IAAM,EAAK,GAC3B,EAAK,GAAK,KAAK,IAAI,EAAK,GAAI,EAAM,EAAE,EAEpC,EAAO,KAAK,CAAC,EAAM,GAAI,EAAM,EAAE,CAAC,CAEpC,CAEA,OAAO,CACT,CA+BA,SAAgB,EAAU,EAAc,EAA6C,CACnF,GAAI,CAAC,EAAM,MAAO,CAAC,EAEnB,GAAI,CAAC,EAAO,OAAQ,MAAO,CAAC,CAAE,YAAa,GAAO,MAAK,CAAC,EAExD,IAAM,EAAyB,CAAC,EAC5B,EAAS,EAEb,IAAK,GAAM,CAAC,EAAO,KAAQ,EACrB,EAAQ,GACV,EAAM,KAAK,CAAE,YAAa,GAAO,KAAM,EAAK,MAAM,EAAQ,CAAK,CAAE,CAAC,EAGhE,EAAM,GACR,EAAM,KAAK,CAAE,YAAa,GAAM,KAAM,EAAK,MAAM,EAAO,CAAG,CAAE,CAAC,EAGhE,EAAS,EAOX,OAJI,EAAS,EAAK,QAChB,EAAM,KAAK,CAAE,YAAa,GAAO,KAAM,EAAK,MAAM,CAAM,CAAE,CAAC,EAGtD,CACT,CAyBA,SAAgB,EAAkB,EAAyB,EAAyB,EAA+B,CAGjH,OAAO,EAAU,EAFH,EAAO,QAAQ,KAAM,GAAM,EAAE,QAAU,CAE9B,CAAA,EAAO,QAAU,CAAC,CAAC,CAC5C"}

package/dist/highlight.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"highlight.d.ts","sourceRoot":"","sources":["../src/highlight.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAI3D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAiC/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,aAAa,EAAE,CAyBnF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAIjH"}
+{"version":3,"file":"highlight.d.ts","sourceRoot":"","sources":["../src/highlight.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAE3D;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAiC/E;AAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,GAAG,aAAa,EAAE,CAyBnF;AAED;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAgB,cAAc,CAAC,CAAC,EAAE,MAAM,EAAE,YAAY,CAAC,CAAC,CAAC,EAAE,KAAK,EAAE,MAAM,CAAC,GAAG,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,aAAa,EAAE,CAIjH"}

package/dist/highlight.js.map

@@ -1 +1 @@
-{"version":3,"file":"highlight.js","names":[],"sources":["../src/highlight.ts"],"sourcesContent":["import type { HighlightPart, SearchResult } from './types';\n\nimport { tokenize } from './tokenize';\n\n/**\n * Finds character ranges within `text` where `query` words appear.\n * Ranges are sorted and overlapping ranges are merged.\n *\n * Useful when you need to apply match ranges to a different string than the\n * indexed field value (e.g. a truncated preview or a differently formatted display string).\n *\n * @param text - The string to search within.\n * @param query - Raw query text. It is normalized with Scout's tokenizer before literal lookup.\n * @returns Sorted, non-overlapping `[start, end]` character ranges.\n */\nexport function findMatchRanges(text: string, query: string): [number, number][] {\n  const lower = text.toLowerCase();\n  const words = tokenize(query).split(' ').filter(Boolean);\n  const ranges: [number, number][] = [];\n\n  for (const word of words) {\n    let pos = 0;\n\n    while (pos < lower.length) {\n      const idx = lower.indexOf(word, pos);\n\n      if (idx === -1) break;\n\n      ranges.push([idx, idx + word.length]);\n      pos = idx + 1;\n    }\n  }\n\n  ranges.sort((a, b) => a[0] - b[0]);\n\n  const merged: [number, number][] = [];\n\n  for (const range of ranges) {\n    const last = merged[merged.length - 1];\n\n    if (last && range[0] <= last[1]) {\n      last[1] = Math.max(last[1], range[1]);\n    } else {\n      merged.push([range[0], range[1]]);\n    }\n  }\n\n  return merged;\n}\n\n/**\n * Splits `text` into highlighted and unhighlighted fragments using match `ranges`.\n *\n * Ranges must be sorted and non-overlapping (as produced by `SearchResult.matches[n].ranges`).\n * Use the returned parts to render highlighted text in a UI component.\n *\n * **`part.text` is the original, unescaped field value** (e.g. a user's name, bio, or\n * product title) — this function does no HTML escaping. Render each part via safe DOM APIs\n * (`textContent`, a framework's text binding) and wrap `highlighted` parts in your own\n * element (e.g. `<mark>`); never concatenate `part.text` into an HTML string for\n * `innerHTML` — that reintroduces the XSS risk this structured return shape avoids.\n *\n * @example\n * ```ts\n * highlight('Hello World', [[0, 5]]);\n * // [{ text: 'Hello', highlighted: true }, { text: ' World', highlighted: false }]\n *\n * highlight('Hello World', [[0, 5], [6, 11]]);\n * // [\n * //   { text: 'Hello', highlighted: true },\n * //   { text: ' ',     highlighted: false },\n * //   { text: 'World', highlighted: true },\n * // ]\n * ```\n *\n * @param text - The original field value to split.\n * @param ranges - Sorted, non-overlapping `[start, end]` ranges from `FieldMatch.ranges`.\n * @returns An array of `HighlightPart` objects. Returns an empty array for an empty `text`.\n */\nexport function highlight(text: string, ranges: [number, number][]): HighlightPart[] {\n  if (!text) return [];\n\n  if (!ranges.length) return [{ highlighted: false, text }];\n\n  const parts: HighlightPart[] = [];\n  let cursor = 0;\n\n  for (const [start, end] of ranges) {\n    if (start > cursor) {\n      parts.push({ highlighted: false, text: text.slice(cursor, start) });\n    }\n\n    if (end > start) {\n      parts.push({ highlighted: true, text: text.slice(start, end) });\n    }\n\n    cursor = end;\n  }\n\n  if (cursor < text.length) {\n    parts.push({ highlighted: false, text: text.slice(cursor) });\n  }\n\n  return parts;\n}\n\n/**\n * Finds the match ranges for `field` in `result` and splits `text` into\n * highlighted and unhighlighted fragments in one step.\n *\n * This is the ergonomic shorthand for the common pattern:\n * ```ts\n * const match = result.matches.find(m => m.field === 'name');\n * const parts = highlight(item.name, match?.ranges ?? []);\n * ```\n *\n * @example\n * ```ts\n * for (const result of index.search('alice')) {\n *   const parts = highlightField(result, 'name', result.item.name);\n *   console.log(parts.map(p => p.highlighted ? `[${p.text}]` : p.text).join(''));\n * }\n * ```\n *\n * @param result - A `SearchResult` from `ScoutIndex.search()`.\n * @param field - The field name to look up in `result.matches`.\n * @param text - The original field value string to split.\n * @returns An array of `HighlightPart` objects.\n */\nexport function highlightField<T>(result: SearchResult<T>, field: keyof T & string, text: string): HighlightPart[] {\n  const match = result.matches.find((m) => m.field === field);\n\n  return highlight(text, match?.ranges ?? []);\n}\n"],"mappings":";;AAeA,SAAgB,EAAgB,GAAc,GAAmC;CAC/E,IAAM,IAAQ,EAAK,YAAY,GACzB,IAAQ,EAAS,CAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,GACjD,IAA6B,CAAC;CAEpC,KAAK,IAAM,KAAQ,GAAO;EACxB,IAAI,IAAM;EAEV,OAAO,IAAM,EAAM,SAAQ;GACzB,IAAM,IAAM,EAAM,QAAQ,GAAM,CAAG;GAEnC,IAAI,MAAQ,IAAI;GAGhB,AADA,EAAO,KAAK,CAAC,GAAK,IAAM,EAAK,MAAM,CAAC,GACpC,IAAM,IAAM;EACd;CACF;CAEA,EAAO,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE;CAEjC,IAAM,IAA6B,CAAC;CAEpC,KAAK,IAAM,KAAS,GAAQ;EAC1B,IAAM,IAAO,EAAO,EAAO,SAAS;EAEpC,AAAI,KAAQ,EAAM,MAAM,EAAK,KAC3B,EAAK,KAAK,KAAK,IAAI,EAAK,IAAI,EAAM,EAAE,IAEpC,EAAO,KAAK,CAAC,EAAM,IAAI,EAAM,EAAE,CAAC;CAEpC;CAEA,OAAO;AACT;AA+BA,SAAgB,EAAU,GAAc,GAA6C;CACnF,IAAI,CAAC,GAAM,OAAO,CAAC;CAEnB,IAAI,CAAC,EAAO,QAAQ,OAAO,CAAC;EAAE,aAAa;EAAO;CAAK,CAAC;CAExD,IAAM,IAAyB,CAAC,GAC5B,IAAS;CAEb,KAAK,IAAM,CAAC,GAAO,MAAQ,GASzB,AARI,IAAQ,KACV,EAAM,KAAK;EAAE,aAAa;EAAO,MAAM,EAAK,MAAM,GAAQ,CAAK;CAAE,CAAC,GAGhE,IAAM,KACR,EAAM,KAAK;EAAE,aAAa;EAAM,MAAM,EAAK,MAAM,GAAO,CAAG;CAAE,CAAC,GAGhE,IAAS;CAOX,OAJI,IAAS,EAAK,UAChB,EAAM,KAAK;EAAE,aAAa;EAAO,MAAM,EAAK,MAAM,CAAM;CAAE,CAAC,GAGtD;AACT;AAyBA,SAAgB,EAAkB,GAAyB,GAAyB,GAA+B;CAGjH,OAAO,EAAU,GAFH,EAAO,QAAQ,MAAM,MAAM,EAAE,UAAU,CAE9B,CAAA,EAAO,UAAU,CAAC,CAAC;AAC5C"}
+{"version":3,"file":"highlight.js","names":[],"sources":["../src/highlight.ts"],"sourcesContent":["import { tokenize } from './tokenize';\nimport type { HighlightPart, SearchResult } from './types';\n\n/**\n * Finds character ranges within `text` where `query` words appear.\n * Ranges are sorted and overlapping ranges are merged.\n *\n * Useful when you need to apply match ranges to a different string than the\n * indexed field value (e.g. a truncated preview or a differently formatted display string).\n *\n * @param text - The string to search within.\n * @param query - Raw query text. It is normalized with Scout's tokenizer before literal lookup.\n * @returns Sorted, non-overlapping `[start, end]` character ranges.\n */\nexport function findMatchRanges(text: string, query: string): [number, number][] {\n  const lower = text.toLowerCase();\n  const words = tokenize(query).split(' ').filter(Boolean);\n  const ranges: [number, number][] = [];\n\n  for (const word of words) {\n    let pos = 0;\n\n    while (pos < lower.length) {\n      const idx = lower.indexOf(word, pos);\n\n      if (idx === -1) break;\n\n      ranges.push([idx, idx + word.length]);\n      pos = idx + 1;\n    }\n  }\n\n  ranges.sort((a, b) => a[0] - b[0]);\n\n  const merged: [number, number][] = [];\n\n  for (const range of ranges) {\n    const last = merged[merged.length - 1];\n\n    if (last && range[0] <= last[1]) {\n      last[1] = Math.max(last[1], range[1]);\n    } else {\n      merged.push([range[0], range[1]]);\n    }\n  }\n\n  return merged;\n}\n\n/**\n * Splits `text` into highlighted and unhighlighted fragments using match `ranges`.\n *\n * Ranges must be sorted and non-overlapping (as produced by `SearchResult.matches[n].ranges`).\n * Use the returned parts to render highlighted text in a UI component.\n *\n * **`part.text` is the original, unescaped field value** (e.g. a user's name, bio, or\n * product title) — this function does no HTML escaping. Render each part via safe DOM APIs\n * (`textContent`, a framework's text binding) and wrap `highlighted` parts in your own\n * element (e.g. `<mark>`); never concatenate `part.text` into an HTML string for\n * `innerHTML` — that reintroduces the XSS risk this structured return shape avoids.\n *\n * @example\n * ```ts\n * highlight('Hello World', [[0, 5]]);\n * // [{ text: 'Hello', highlighted: true }, { text: ' World', highlighted: false }]\n *\n * highlight('Hello World', [[0, 5], [6, 11]]);\n * // [\n * //   { text: 'Hello', highlighted: true },\n * //   { text: ' ',     highlighted: false },\n * //   { text: 'World', highlighted: true },\n * // ]\n * ```\n *\n * @param text - The original field value to split.\n * @param ranges - Sorted, non-overlapping `[start, end]` ranges from `FieldMatch.ranges`.\n * @returns An array of `HighlightPart` objects. Returns an empty array for an empty `text`.\n */\nexport function highlight(text: string, ranges: [number, number][]): HighlightPart[] {\n  if (!text) return [];\n\n  if (!ranges.length) return [{ highlighted: false, text }];\n\n  const parts: HighlightPart[] = [];\n  let cursor = 0;\n\n  for (const [start, end] of ranges) {\n    if (start > cursor) {\n      parts.push({ highlighted: false, text: text.slice(cursor, start) });\n    }\n\n    if (end > start) {\n      parts.push({ highlighted: true, text: text.slice(start, end) });\n    }\n\n    cursor = end;\n  }\n\n  if (cursor < text.length) {\n    parts.push({ highlighted: false, text: text.slice(cursor) });\n  }\n\n  return parts;\n}\n\n/**\n * Finds the match ranges for `field` in `result` and splits `text` into\n * highlighted and unhighlighted fragments in one step.\n *\n * This is the ergonomic shorthand for the common pattern:\n * ```ts\n * const match = result.matches.find(m => m.field === 'name');\n * const parts = highlight(item.name, match?.ranges ?? []);\n * ```\n *\n * @example\n * ```ts\n * for (const result of index.search('alice')) {\n *   const parts = highlightField(result, 'name', result.item.name);\n *   console.log(parts.map(p => p.highlighted ? `[${p.text}]` : p.text).join(''));\n * }\n * ```\n *\n * @param result - A `SearchResult` from `ScoutIndex.search()`.\n * @param field - The field name to look up in `result.matches`.\n * @param text - The original field value string to split.\n * @returns An array of `HighlightPart` objects.\n */\nexport function highlightField<T>(result: SearchResult<T>, field: keyof T & string, text: string): HighlightPart[] {\n  const match = result.matches.find((m) => m.field === field);\n\n  return highlight(text, match?.ranges ?? []);\n}\n"],"mappings":";;AAcA,SAAgB,EAAgB,GAAc,GAAmC;CAC/E,IAAM,IAAQ,EAAK,YAAY,GACzB,IAAQ,EAAS,CAAK,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,OAAO,OAAO,GACjD,IAA6B,CAAC;CAEpC,KAAK,IAAM,KAAQ,GAAO;EACxB,IAAI,IAAM;EAEV,OAAO,IAAM,EAAM,SAAQ;GACzB,IAAM,IAAM,EAAM,QAAQ,GAAM,CAAG;GAEnC,IAAI,MAAQ,IAAI;GAGhB,AADA,EAAO,KAAK,CAAC,GAAK,IAAM,EAAK,MAAM,CAAC,GACpC,IAAM,IAAM;EACd;CACF;CAEA,EAAO,MAAM,GAAG,MAAM,EAAE,KAAK,EAAE,EAAE;CAEjC,IAAM,IAA6B,CAAC;CAEpC,KAAK,IAAM,KAAS,GAAQ;EAC1B,IAAM,IAAO,EAAO,EAAO,SAAS;EAEpC,AAAI,KAAQ,EAAM,MAAM,EAAK,KAC3B,EAAK,KAAK,KAAK,IAAI,EAAK,IAAI,EAAM,EAAE,IAEpC,EAAO,KAAK,CAAC,EAAM,IAAI,EAAM,EAAE,CAAC;CAEpC;CAEA,OAAO;AACT;AA+BA,SAAgB,EAAU,GAAc,GAA6C;CACnF,IAAI,CAAC,GAAM,OAAO,CAAC;CAEnB,IAAI,CAAC,EAAO,QAAQ,OAAO,CAAC;EAAE,aAAa;EAAO;CAAK,CAAC;CAExD,IAAM,IAAyB,CAAC,GAC5B,IAAS;CAEb,KAAK,IAAM,CAAC,GAAO,MAAQ,GASzB,AARI,IAAQ,KACV,EAAM,KAAK;EAAE,aAAa;EAAO,MAAM,EAAK,MAAM,GAAQ,CAAK;CAAE,CAAC,GAGhE,IAAM,KACR,EAAM,KAAK;EAAE,aAAa;EAAM,MAAM,EAAK,MAAM,GAAO,CAAG;CAAE,CAAC,GAGhE,IAAS;CAOX,OAJI,IAAS,EAAK,UAChB,EAAM,KAAK;EAAE,aAAa;EAAO,MAAM,EAAK,MAAM,CAAM;CAAE,CAAC,GAGtD;AACT;AAyBA,SAAgB,EAAkB,GAAyB,GAAyB,GAA+B;CAGjH,OAAO,EAAU,GAFH,EAAO,QAAQ,MAAM,MAAM,EAAE,UAAU,CAE9B,CAAA,EAAO,UAAU,CAAC,CAAC;AAC5C"}

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { toFilterPredicate, toSearchMatcher } from './adapters';
 export { ScoutConfigurationError, ScoutDisposedError, ScoutError } from './errors';
 export { findMatchRanges, highlight, highlightField } from './highlight';
-export { createReactiveSearch, createSearch } from './reactive';
 export type { ReactiveSearch } from './reactive';
+export { createReactiveSearch, createSearch } from './reactive';
 export type { ScoutIndex } from './scout-index';
 export { createIndex } from './scout-index';
 export { segmentWords } from './segment';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAChE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EACV,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,WAAW,GACZ,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,eAAe,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAE,uBAAuB,EAAE,kBAAkB,EAAE,UAAU,EAAE,MAAM,UAAU,CAAC;AACnF,OAAO,EAAE,eAAe,EAAE,SAAS,EAAE,cAAc,EAAE,MAAM,aAAa,CAAC;AACzE,YAAY,EAAE,cAAc,EAAE,MAAM,YAAY,CAAC;AACjD,OAAO,EAAE,oBAAoB,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAChE,YAAY,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAAE,WAAW,EAAE,MAAM,eAAe,CAAC;AAC5C,OAAO,EAAE,YAAY,EAAE,MAAM,WAAW,CAAC;AACzC,YAAY,EACV,mBAAmB,EACnB,QAAQ,EACR,UAAU,EACV,aAAa,EACb,iBAAiB,EACjB,iBAAiB,EACjB,YAAY,EACZ,WAAW,GACZ,MAAM,SAAS,CAAC"}

package/dist/reactive.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"reactive.cjs","names":[],"sources":["../src/reactive.ts"],"sourcesContent":["import { batch, computed, signal } from '@vielzeug/ripple';\n\nimport type { CreateSearchOptions, ScoutIndexOptions, SearchResult, SearchState } from './types';\n\nimport { ScoutConfigurationError, ScoutDisposedError } from './errors';\nimport { createIndex, type ScoutIndex } from './scout-index';\n\n/**\n * Combined index + reactive search state returned by `createReactiveSearch()`.\n * Exposes the underlying `ScoutIndex` for incremental mutations (`add`, `remove`, `reindex`).\n */\nexport type ReactiveSearch<T> = SearchState<T> & {\n  readonly index: ScoutIndex<T>;\n};\n\nconst DEFAULT_DEBOUNCE = 200;\n\n/**\n * Creates a reactive search state backed by a `ScoutIndex`.\n *\n * - Set `state.query.value` to trigger a (debounced) search.\n * - Read `state.results.value` inside an `effect` or `computed` to consume results reactively.\n * - `state.isSearching.value` is `true` while debouncing, `false` otherwise.\n * - Call `state.dispose()` (or `using state = createSearch(...)`) to release subscriptions.\n *\n * @example\n * ```ts\n * const index = createIndex(users, { fields: ['name', 'email'] });\n * const search = createSearch(index, { debounce: 150 });\n *\n * effect(() => {\n *   const results = search.results.value;\n *   renderList(results.map(r => r.item));\n * });\n *\n * // Wire to an input\n * input.addEventListener('input', e => {\n *   search.query.value = e.currentTarget.value;\n * });\n *\n * // Clean up\n * search.dispose();\n * ```\n *\n * `results` also updates when the index is mutated directly via `index.add()` / `.remove()`\n * / `.reindex()` / `.setItems()` (not just when `query` changes), by subscribing to `index.onMutate()`.\n *\n * @param index - A `ScoutIndex` built with `createIndex()`.\n * @param options.debounce - Milliseconds to wait before committing query changes. Default: `200`.\n * @param options.limit - Override the index-level result limit.\n * @param options.minQueryLength - Override the index-level minimum query length.\n * @param options.threshold - Override the index-level score threshold.\n */\nexport function createSearch<T>(index: ScoutIndex<T>, options: CreateSearchOptions = {}): SearchState<T> {\n  const { debounce: debounceMs = DEFAULT_DEBOUNCE, limit, minQueryLength, threshold } = options;\n\n  if (!Number.isFinite(debounceMs) || !Number.isInteger(debounceMs) || debounceMs < 0) {\n    throw new ScoutConfigurationError('debounce must be a finite non-negative integer.');\n  }\n\n  const query = signal<string>('', { name: 'scout:query' });\n  const committedQuery = signal<string>('', { name: 'scout:committedQuery' });\n  const indexVersion = signal(0, { name: 'scout:indexVersion' });\n\n  const unsubscribeMutations = index.onMutate(() => {\n    indexVersion.value++;\n  });\n\n  const isSearching = computed(() => query.value !== committedQuery.value, { name: 'scout:isSearching' });\n\n  const results = computed<SearchResult<T>[]>(\n    () => {\n      // Reading .value establishes a dependency so index mutations trigger a recompute.\n      void indexVersion.value;\n\n      return index.search(committedQuery.value, { limit, minQueryLength, threshold });\n    },\n    { name: 'scout:results' },\n  );\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  function cancelTimer(): void {\n    if (timer !== null) {\n      clearTimeout(timer);\n      timer = null;\n    }\n  }\n\n  const subscription = query.subscribe(() => {\n    const q = query.peek();\n\n    cancelTimer();\n\n    if (q === committedQuery.peek()) return;\n\n    if (debounceMs === 0) {\n      committedQuery.value = q;\n\n      return;\n    }\n\n    timer = setTimeout(() => {\n      committedQuery.value = q;\n      timer = null;\n    }, debounceMs);\n  });\n\n  function clear(): void {\n    if (isDisposed) throw new ScoutDisposedError('SearchState.clear() called after dispose()');\n\n    cancelTimer();\n\n    batch(() => {\n      query.value = '';\n      committedQuery.value = '';\n    });\n  }\n\n  let isDisposed = false;\n  const ac = new AbortController();\n\n  function dispose(): void {\n    isDisposed = true;\n    ac.abort();\n    cancelTimer();\n    subscription();\n    unsubscribeMutations();\n  }\n\n  return {\n    clear,\n    get disposalSignal(): AbortSignal {\n      return ac.signal;\n    },\n    dispose,\n    get disposed(): boolean {\n      return isDisposed;\n    },\n    isSearching,\n    query,\n    results,\n    [Symbol.dispose](): void {\n      dispose();\n    },\n  };\n}\n\n/**\n * Creates a `ScoutIndex` and a reactive search state in one call — the shorthand\n * for the common pattern of `createIndex` + `createSearch`.\n *\n * The returned `ReactiveSearch` exposes the underlying index via `.index` for\n * incremental mutations (`add`, `remove`, `reindex`, `setItems`) after construction.\n *\n * @example\n * ```ts\n * const search = createReactiveSearch(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   debounce: 150,\n * });\n *\n * effect(() => renderList(search.results.value.map(r => r.item)));\n *\n * // Wire to an input\n * input.addEventListener('input', e => { search.query.value = e.currentTarget.value; });\n *\n * // Add a new item at runtime\n * search.index.add(newUser);\n * ```\n *\n * @param items - Initial corpus to index.\n * @param options - Index options (`fields`, `limit`, `minQueryLength`, `threshold`) plus optional `debounce`.\n */\nexport function createReactiveSearch<T>(\n  items: T[],\n  options: ScoutIndexOptions<T> & Pick<CreateSearchOptions, 'debounce'>,\n): ReactiveSearch<T> {\n  const index = createIndex(items, {\n    fields: options.fields,\n    limit: options.limit,\n    minQueryLength: options.minQueryLength,\n    threshold: options.threshold,\n  });\n  const state = createSearch(index, { debounce: options.debounce });\n\n  return Object.assign(Object.create(state), { index }) as ReactiveSearch<T>;\n}\n"],"mappings":"iGAeA,IAAM,EAAmB,IAsCzB,SAAgB,EAAgB,EAAsB,EAA+B,CAAC,EAAmB,CACvG,GAAM,CAAE,SAAU,EAAa,EAAkB,QAAO,iBAAgB,aAAc,EAEtF,GAAI,CAAC,OAAO,SAAS,CAAU,GAAK,CAAC,OAAO,UAAU,CAAU,GAAK,EAAa,EAChF,MAAM,IAAI,EAAA,wBAAwB,iDAAiD,EAGrF,IAAM,GAAA,EAAQ,EAAA,OAAA,CAAe,GAAI,CAAE,KAAM,aAAc,CAAC,EAClD,GAAA,EAAiB,EAAA,OAAA,CAAe,GAAI,CAAE,KAAM,sBAAuB,CAAC,EACpE,GAAA,EAAe,EAAA,OAAA,CAAO,EAAG,CAAE,KAAM,oBAAqB,CAAC,EAEvD,EAAuB,EAAM,aAAe,CAChD,EAAa,OACf,CAAC,EAEK,GAAA,EAAc,EAAA,SAAA,KAAe,EAAM,QAAU,EAAe,MAAO,CAAE,KAAM,mBAAoB,CAAC,EAEhG,GAAA,EAAU,EAAA,SAAA,MAGZ,EAAkB,MAEX,EAAM,OAAO,EAAe,MAAO,CAAE,QAAO,iBAAgB,WAAU,CAAC,GAEhF,CAAE,KAAM,eAAgB,CAC1B,EAEI,EAA8C,KAElD,SAAS,GAAoB,CACvB,IAAU,OACZ,aAAa,CAAK,EAClB,EAAQ,KAEZ,CAEA,IAAM,EAAe,EAAM,cAAgB,CACzC,IAAM,EAAI,EAAM,KAAK,EAErB,KAAY,EAER,IAAM,EAAe,KAAK,EAE9B,IAAI,IAAe,EAAG,CACpB,EAAe,MAAQ,EAEvB,MACF,CAEA,EAAQ,eAAiB,CACvB,EAAe,MAAQ,EACvB,EAAQ,IACV,EAAG,CAAU,CALb,CAMF,CAAC,EAED,SAAS,GAAc,CACrB,GAAI,EAAY,MAAM,IAAI,EAAA,mBAAmB,4CAA4C,EAEzF,EAAY,GAEZ,EAAA,EAAA,MAAA,KAAY,CACV,EAAM,MAAQ,GACd,EAAe,MAAQ,EACzB,CAAC,CACH,CAEA,IAAI,EAAa,GACX,EAAK,IAAI,gBAEf,SAAS,GAAgB,CACvB,EAAa,GACb,EAAG,MAAM,EACT,EAAY,EACZ,EAAa,EACb,EAAqB,CACvB,CAEA,MAAO,CACL,QACA,IAAI,gBAA8B,CAChC,OAAO,EAAG,MACZ,EACA,UACA,IAAI,UAAoB,CACtB,OAAO,CACT,EACA,cACA,QACA,UACA,CAAC,OAAO,UAAiB,CACvB,EAAQ,CACV,CACF,CACF,CA4BA,SAAgB,EACd,EACA,EACmB,CACnB,IAAM,EAAQ,EAAA,YAAY,EAAO,CAC/B,OAAQ,EAAQ,OAChB,MAAO,EAAQ,MACf,eAAgB,EAAQ,eACxB,UAAW,EAAQ,SACrB,CAAC,EACK,EAAQ,EAAa,EAAO,CAAE,SAAU,EAAQ,QAAS,CAAC,EAEhE,OAAO,OAAO,OAAO,OAAO,OAAO,CAAK,EAAG,CAAE,OAAM,CAAC,CACtD"}
+{"version":3,"file":"reactive.cjs","names":[],"sources":["../src/reactive.ts"],"sourcesContent":["import { batch, computed, signal } from '@vielzeug/ripple';\nimport { ScoutConfigurationError, ScoutDisposedError } from './errors';\nimport { createIndex, type ScoutIndex } from './scout-index';\nimport type { CreateSearchOptions, ScoutIndexOptions, SearchResult, SearchState } from './types';\n\n/**\n * Combined index + reactive search state returned by `createReactiveSearch()`.\n * Exposes the underlying `ScoutIndex` for incremental mutations (`add`, `remove`, `reindex`).\n */\nexport type ReactiveSearch<T> = SearchState<T> & {\n  readonly index: ScoutIndex<T>;\n};\n\nconst DEFAULT_DEBOUNCE = 200;\n\n/**\n * Creates a reactive search state backed by a `ScoutIndex`.\n *\n * - Set `state.query.value` to trigger a (debounced) search.\n * - Read `state.results.value` inside an `effect` or `computed` to consume results reactively.\n * - `state.isSearching.value` is `true` while debouncing, `false` otherwise.\n * - Call `state.dispose()` (or `using state = createSearch(...)`) to release subscriptions.\n *\n * @example\n * ```ts\n * const index = createIndex(users, { fields: ['name', 'email'] });\n * const search = createSearch(index, { debounce: 150 });\n *\n * effect(() => {\n *   const results = search.results.value;\n *   renderList(results.map(r => r.item));\n * });\n *\n * // Wire to an input\n * input.addEventListener('input', e => {\n *   search.query.value = e.currentTarget.value;\n * });\n *\n * // Clean up\n * search.dispose();\n * ```\n *\n * `results` also updates when the index is mutated directly via `index.add()` / `.remove()`\n * / `.reindex()` / `.setItems()` (not just when `query` changes), by subscribing to `index.onMutate()`.\n *\n * @param index - A `ScoutIndex` built with `createIndex()`.\n * @param options.debounce - Milliseconds to wait before committing query changes. Default: `200`.\n * @param options.limit - Override the index-level result limit.\n * @param options.minQueryLength - Override the index-level minimum query length.\n * @param options.threshold - Override the index-level score threshold.\n */\nexport function createSearch<T>(index: ScoutIndex<T>, options: CreateSearchOptions = {}): SearchState<T> {\n  const { debounce: debounceMs = DEFAULT_DEBOUNCE, limit, minQueryLength, threshold } = options;\n\n  if (!Number.isFinite(debounceMs) || !Number.isInteger(debounceMs) || debounceMs < 0) {\n    throw new ScoutConfigurationError('debounce must be a finite non-negative integer.');\n  }\n\n  const query = signal<string>('', { name: 'scout:query' });\n  const committedQuery = signal<string>('', { name: 'scout:committedQuery' });\n  const indexVersion = signal(0, { name: 'scout:indexVersion' });\n\n  const unsubscribeMutations = index.onMutate(() => {\n    indexVersion.value++;\n  });\n\n  const isSearching = computed(() => query.value !== committedQuery.value, { name: 'scout:isSearching' });\n\n  const results = computed<SearchResult<T>[]>(\n    () => {\n      // Reading .value establishes a dependency so index mutations trigger a recompute.\n      void indexVersion.value;\n\n      return index.search(committedQuery.value, { limit, minQueryLength, threshold });\n    },\n    { name: 'scout:results' },\n  );\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  function cancelTimer(): void {\n    if (timer !== null) {\n      clearTimeout(timer);\n      timer = null;\n    }\n  }\n\n  const subscription = query.subscribe(() => {\n    const q = query.peek();\n\n    cancelTimer();\n\n    if (q === committedQuery.peek()) return;\n\n    if (debounceMs === 0) {\n      committedQuery.value = q;\n\n      return;\n    }\n\n    timer = setTimeout(() => {\n      committedQuery.value = q;\n      timer = null;\n    }, debounceMs);\n  });\n\n  function clear(): void {\n    if (isDisposed) throw new ScoutDisposedError('SearchState.clear() called after dispose()');\n\n    cancelTimer();\n\n    batch(() => {\n      query.value = '';\n      committedQuery.value = '';\n    });\n  }\n\n  let isDisposed = false;\n  const ac = new AbortController();\n\n  function dispose(): void {\n    isDisposed = true;\n    ac.abort();\n    cancelTimer();\n    subscription();\n    unsubscribeMutations();\n  }\n\n  return {\n    clear,\n    get disposalSignal(): AbortSignal {\n      return ac.signal;\n    },\n    dispose,\n    get disposed(): boolean {\n      return isDisposed;\n    },\n    isSearching,\n    query,\n    results,\n    [Symbol.dispose](): void {\n      dispose();\n    },\n  };\n}\n\n/**\n * Creates a `ScoutIndex` and a reactive search state in one call — the shorthand\n * for the common pattern of `createIndex` + `createSearch`.\n *\n * The returned `ReactiveSearch` exposes the underlying index via `.index` for\n * incremental mutations (`add`, `remove`, `reindex`, `setItems`) after construction.\n *\n * @example\n * ```ts\n * const search = createReactiveSearch(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   debounce: 150,\n * });\n *\n * effect(() => renderList(search.results.value.map(r => r.item)));\n *\n * // Wire to an input\n * input.addEventListener('input', e => { search.query.value = e.currentTarget.value; });\n *\n * // Add a new item at runtime\n * search.index.add(newUser);\n * ```\n *\n * @param items - Initial corpus to index.\n * @param options - Index options (`fields`, `limit`, `minQueryLength`, `threshold`) plus optional `debounce`.\n */\nexport function createReactiveSearch<T>(\n  items: T[],\n  options: ScoutIndexOptions<T> & Pick<CreateSearchOptions, 'debounce'>,\n): ReactiveSearch<T> {\n  const index = createIndex(items, {\n    fields: options.fields,\n    limit: options.limit,\n    minQueryLength: options.minQueryLength,\n    threshold: options.threshold,\n  });\n  const state = createSearch(index, { debounce: options.debounce });\n\n  return Object.assign(Object.create(state), { index }) as ReactiveSearch<T>;\n}\n"],"mappings":"iGAaA,IAAM,EAAmB,IAsCzB,SAAgB,EAAgB,EAAsB,EAA+B,CAAC,EAAmB,CACvG,GAAM,CAAE,SAAU,EAAa,EAAkB,QAAO,iBAAgB,aAAc,EAEtF,GAAI,CAAC,OAAO,SAAS,CAAU,GAAK,CAAC,OAAO,UAAU,CAAU,GAAK,EAAa,EAChF,MAAM,IAAI,EAAA,wBAAwB,iDAAiD,EAGrF,IAAM,GAAA,EAAQ,EAAA,OAAA,CAAe,GAAI,CAAE,KAAM,aAAc,CAAC,EAClD,GAAA,EAAiB,EAAA,OAAA,CAAe,GAAI,CAAE,KAAM,sBAAuB,CAAC,EACpE,GAAA,EAAe,EAAA,OAAA,CAAO,EAAG,CAAE,KAAM,oBAAqB,CAAC,EAEvD,EAAuB,EAAM,aAAe,CAChD,EAAa,OACf,CAAC,EAEK,GAAA,EAAc,EAAA,SAAA,KAAe,EAAM,QAAU,EAAe,MAAO,CAAE,KAAM,mBAAoB,CAAC,EAEhG,GAAA,EAAU,EAAA,SAAA,MAGZ,EAAkB,MAEX,EAAM,OAAO,EAAe,MAAO,CAAE,QAAO,iBAAgB,WAAU,CAAC,GAEhF,CAAE,KAAM,eAAgB,CAC1B,EAEI,EAA8C,KAElD,SAAS,GAAoB,CACvB,IAAU,OACZ,aAAa,CAAK,EAClB,EAAQ,KAEZ,CAEA,IAAM,EAAe,EAAM,cAAgB,CACzC,IAAM,EAAI,EAAM,KAAK,EAErB,KAAY,EAER,IAAM,EAAe,KAAK,EAE9B,IAAI,IAAe,EAAG,CACpB,EAAe,MAAQ,EAEvB,MACF,CAEA,EAAQ,eAAiB,CACvB,EAAe,MAAQ,EACvB,EAAQ,IACV,EAAG,CAAU,CALb,CAMF,CAAC,EAED,SAAS,GAAc,CACrB,GAAI,EAAY,MAAM,IAAI,EAAA,mBAAmB,4CAA4C,EAEzF,EAAY,GAEZ,EAAA,EAAA,MAAA,KAAY,CACV,EAAM,MAAQ,GACd,EAAe,MAAQ,EACzB,CAAC,CACH,CAEA,IAAI,EAAa,GACX,EAAK,IAAI,gBAEf,SAAS,GAAgB,CACvB,EAAa,GACb,EAAG,MAAM,EACT,EAAY,EACZ,EAAa,EACb,EAAqB,CACvB,CAEA,MAAO,CACL,QACA,IAAI,gBAA8B,CAChC,OAAO,EAAG,MACZ,EACA,UACA,IAAI,UAAoB,CACtB,OAAO,CACT,EACA,cACA,QACA,UACA,CAAC,OAAO,UAAiB,CACvB,EAAQ,CACV,CACF,CACF,CA4BA,SAAgB,EACd,EACA,EACmB,CACnB,IAAM,EAAQ,EAAA,YAAY,EAAO,CAC/B,OAAQ,EAAQ,OAChB,MAAO,EAAQ,MACf,eAAgB,EAAQ,eACxB,UAAW,EAAQ,SACrB,CAAC,EACK,EAAQ,EAAa,EAAO,CAAE,SAAU,EAAQ,QAAS,CAAC,EAEhE,OAAO,OAAO,OAAO,OAAO,OAAO,CAAK,EAAG,CAAE,OAAM,CAAC,CACtD"}

package/dist/reactive.d.ts

@@ -1,5 +1,5 @@
-import type { CreateSearchOptions, ScoutIndexOptions, SearchState } from './types';
 import { type ScoutIndex } from './scout-index';
+import type { CreateSearchOptions, ScoutIndexOptions, SearchState } from './types';
 /**
  * Combined index + reactive search state returned by `createReactiveSearch()`.
  * Exposes the underlying `ScoutIndex` for incremental mutations (`add`, `remove`, `reindex`).

package/dist/reactive.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAgB,WAAW,EAAE,MAAM,SAAS,CAAC;AAGjG,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAE7D;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IAC/C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;CAC/B,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,mBAAwB,GAAG,WAAW,CAAC,CAAC,CAAC,CA6FvG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,GACpE,cAAc,CAAC,CAAC,CAAC,CAUnB"}
+{"version":3,"file":"reactive.d.ts","sourceRoot":"","sources":["../src/reactive.ts"],"names":[],"mappings":"AAEA,OAAO,EAAe,KAAK,UAAU,EAAE,MAAM,eAAe,CAAC;AAC7D,OAAO,KAAK,EAAE,mBAAmB,EAAE,iBAAiB,EAAgB,WAAW,EAAE,MAAM,SAAS,CAAC;AAEjG;;;GAGG;AACH,MAAM,MAAM,cAAc,CAAC,CAAC,IAAI,WAAW,CAAC,CAAC,CAAC,GAAG;IAC/C,QAAQ,CAAC,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,CAAC;CAC/B,CAAC;AAIF;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AACH,wBAAgB,YAAY,CAAC,CAAC,EAAE,KAAK,EAAE,UAAU,CAAC,CAAC,CAAC,EAAE,OAAO,GAAE,mBAAwB,GAAG,WAAW,CAAC,CAAC,CAAC,CA6FvG;AAED;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EACpC,KAAK,EAAE,CAAC,EAAE,EACV,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,IAAI,CAAC,mBAAmB,EAAE,UAAU,CAAC,GACpE,cAAc,CAAC,CAAC,CAAC,CAUnB"}

package/dist/reactive.js.map

@@ -1 +1 @@
-{"version":3,"file":"reactive.js","names":[],"sources":["../src/reactive.ts"],"sourcesContent":["import { batch, computed, signal } from '@vielzeug/ripple';\n\nimport type { CreateSearchOptions, ScoutIndexOptions, SearchResult, SearchState } from './types';\n\nimport { ScoutConfigurationError, ScoutDisposedError } from './errors';\nimport { createIndex, type ScoutIndex } from './scout-index';\n\n/**\n * Combined index + reactive search state returned by `createReactiveSearch()`.\n * Exposes the underlying `ScoutIndex` for incremental mutations (`add`, `remove`, `reindex`).\n */\nexport type ReactiveSearch<T> = SearchState<T> & {\n  readonly index: ScoutIndex<T>;\n};\n\nconst DEFAULT_DEBOUNCE = 200;\n\n/**\n * Creates a reactive search state backed by a `ScoutIndex`.\n *\n * - Set `state.query.value` to trigger a (debounced) search.\n * - Read `state.results.value` inside an `effect` or `computed` to consume results reactively.\n * - `state.isSearching.value` is `true` while debouncing, `false` otherwise.\n * - Call `state.dispose()` (or `using state = createSearch(...)`) to release subscriptions.\n *\n * @example\n * ```ts\n * const index = createIndex(users, { fields: ['name', 'email'] });\n * const search = createSearch(index, { debounce: 150 });\n *\n * effect(() => {\n *   const results = search.results.value;\n *   renderList(results.map(r => r.item));\n * });\n *\n * // Wire to an input\n * input.addEventListener('input', e => {\n *   search.query.value = e.currentTarget.value;\n * });\n *\n * // Clean up\n * search.dispose();\n * ```\n *\n * `results` also updates when the index is mutated directly via `index.add()` / `.remove()`\n * / `.reindex()` / `.setItems()` (not just when `query` changes), by subscribing to `index.onMutate()`.\n *\n * @param index - A `ScoutIndex` built with `createIndex()`.\n * @param options.debounce - Milliseconds to wait before committing query changes. Default: `200`.\n * @param options.limit - Override the index-level result limit.\n * @param options.minQueryLength - Override the index-level minimum query length.\n * @param options.threshold - Override the index-level score threshold.\n */\nexport function createSearch<T>(index: ScoutIndex<T>, options: CreateSearchOptions = {}): SearchState<T> {\n  const { debounce: debounceMs = DEFAULT_DEBOUNCE, limit, minQueryLength, threshold } = options;\n\n  if (!Number.isFinite(debounceMs) || !Number.isInteger(debounceMs) || debounceMs < 0) {\n    throw new ScoutConfigurationError('debounce must be a finite non-negative integer.');\n  }\n\n  const query = signal<string>('', { name: 'scout:query' });\n  const committedQuery = signal<string>('', { name: 'scout:committedQuery' });\n  const indexVersion = signal(0, { name: 'scout:indexVersion' });\n\n  const unsubscribeMutations = index.onMutate(() => {\n    indexVersion.value++;\n  });\n\n  const isSearching = computed(() => query.value !== committedQuery.value, { name: 'scout:isSearching' });\n\n  const results = computed<SearchResult<T>[]>(\n    () => {\n      // Reading .value establishes a dependency so index mutations trigger a recompute.\n      void indexVersion.value;\n\n      return index.search(committedQuery.value, { limit, minQueryLength, threshold });\n    },\n    { name: 'scout:results' },\n  );\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  function cancelTimer(): void {\n    if (timer !== null) {\n      clearTimeout(timer);\n      timer = null;\n    }\n  }\n\n  const subscription = query.subscribe(() => {\n    const q = query.peek();\n\n    cancelTimer();\n\n    if (q === committedQuery.peek()) return;\n\n    if (debounceMs === 0) {\n      committedQuery.value = q;\n\n      return;\n    }\n\n    timer = setTimeout(() => {\n      committedQuery.value = q;\n      timer = null;\n    }, debounceMs);\n  });\n\n  function clear(): void {\n    if (isDisposed) throw new ScoutDisposedError('SearchState.clear() called after dispose()');\n\n    cancelTimer();\n\n    batch(() => {\n      query.value = '';\n      committedQuery.value = '';\n    });\n  }\n\n  let isDisposed = false;\n  const ac = new AbortController();\n\n  function dispose(): void {\n    isDisposed = true;\n    ac.abort();\n    cancelTimer();\n    subscription();\n    unsubscribeMutations();\n  }\n\n  return {\n    clear,\n    get disposalSignal(): AbortSignal {\n      return ac.signal;\n    },\n    dispose,\n    get disposed(): boolean {\n      return isDisposed;\n    },\n    isSearching,\n    query,\n    results,\n    [Symbol.dispose](): void {\n      dispose();\n    },\n  };\n}\n\n/**\n * Creates a `ScoutIndex` and a reactive search state in one call — the shorthand\n * for the common pattern of `createIndex` + `createSearch`.\n *\n * The returned `ReactiveSearch` exposes the underlying index via `.index` for\n * incremental mutations (`add`, `remove`, `reindex`, `setItems`) after construction.\n *\n * @example\n * ```ts\n * const search = createReactiveSearch(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   debounce: 150,\n * });\n *\n * effect(() => renderList(search.results.value.map(r => r.item)));\n *\n * // Wire to an input\n * input.addEventListener('input', e => { search.query.value = e.currentTarget.value; });\n *\n * // Add a new item at runtime\n * search.index.add(newUser);\n * ```\n *\n * @param items - Initial corpus to index.\n * @param options - Index options (`fields`, `limit`, `minQueryLength`, `threshold`) plus optional `debounce`.\n */\nexport function createReactiveSearch<T>(\n  items: T[],\n  options: ScoutIndexOptions<T> & Pick<CreateSearchOptions, 'debounce'>,\n): ReactiveSearch<T> {\n  const index = createIndex(items, {\n    fields: options.fields,\n    limit: options.limit,\n    minQueryLength: options.minQueryLength,\n    threshold: options.threshold,\n  });\n  const state = createSearch(index, { debounce: options.debounce });\n\n  return Object.assign(Object.create(state), { index }) as ReactiveSearch<T>;\n}\n"],"mappings":";;;;AAeA,IAAM,IAAmB;AAsCzB,SAAgB,EAAgB,GAAsB,IAA+B,CAAC,GAAmB;CACvG,IAAM,EAAE,UAAU,IAAa,GAAkB,UAAO,mBAAgB,iBAAc;CAEtF,IAAI,CAAC,OAAO,SAAS,CAAU,KAAK,CAAC,OAAO,UAAU,CAAU,KAAK,IAAa,GAChF,MAAM,IAAI,EAAwB,iDAAiD;CAGrF,IAAM,IAAQ,EAAe,IAAI,EAAE,MAAM,cAAc,CAAC,GAClD,IAAiB,EAAe,IAAI,EAAE,MAAM,uBAAuB,CAAC,GACpE,IAAe,EAAO,GAAG,EAAE,MAAM,qBAAqB,CAAC,GAEvD,IAAuB,EAAM,eAAe;EAChD,EAAa;CACf,CAAC,GAEK,IAAc,QAAe,EAAM,UAAU,EAAe,OAAO,EAAE,MAAM,oBAAoB,CAAC,GAEhG,IAAU,SAGZ,EAAkB,OAEX,EAAM,OAAO,EAAe,OAAO;EAAE;EAAO;EAAgB;CAAU,CAAC,IAEhF,EAAE,MAAM,gBAAgB,CAC1B,GAEI,IAA8C;CAElD,SAAS,IAAoB;EAC3B,AAAI,MAAU,SACZ,aAAa,CAAK,GAClB,IAAQ;CAEZ;CAEA,IAAM,IAAe,EAAM,gBAAgB;EACzC,IAAM,IAAI,EAAM,KAAK;EAErB,MAAY,GAER,MAAM,EAAe,KAAK,GAE9B;OAAI,MAAe,GAAG;IACpB,EAAe,QAAQ;IAEvB;GACF;GAEA,IAAQ,iBAAiB;IAEvB,AADA,EAAe,QAAQ,GACvB,IAAQ;GACV,GAAG,CAAU;EALb;CAMF,CAAC;CAED,SAAS,IAAc;EACrB,IAAI,GAAY,MAAM,IAAI,EAAmB,4CAA4C;EAIzF,AAFA,EAAY,GAEZ,QAAY;GAEV,AADA,EAAM,QAAQ,IACd,EAAe,QAAQ;EACzB,CAAC;CACH;CAEA,IAAI,IAAa,IACX,IAAK,IAAI,gBAAgB;CAE/B,SAAS,IAAgB;EAKvB,AAJA,IAAa,IACb,EAAG,MAAM,GACT,EAAY,GACZ,EAAa,GACb,EAAqB;CACvB;CAEA,OAAO;EACL;EACA,IAAI,iBAA8B;GAChC,OAAO,EAAG;EACZ;EACA;EACA,IAAI,WAAoB;GACtB,OAAO;EACT;EACA;EACA;EACA;EACA,CAAC,OAAO,WAAiB;GACvB,EAAQ;EACV;CACF;AACF;AA4BA,SAAgB,EACd,GACA,GACmB;CACnB,IAAM,IAAQ,EAAY,GAAO;EAC/B,QAAQ,EAAQ;EAChB,OAAO,EAAQ;EACf,gBAAgB,EAAQ;EACxB,WAAW,EAAQ;CACrB,CAAC,GACK,IAAQ,EAAa,GAAO,EAAE,UAAU,EAAQ,SAAS,CAAC;CAEhE,OAAO,OAAO,OAAO,OAAO,OAAO,CAAK,GAAG,EAAE,SAAM,CAAC;AACtD"}
+{"version":3,"file":"reactive.js","names":[],"sources":["../src/reactive.ts"],"sourcesContent":["import { batch, computed, signal } from '@vielzeug/ripple';\nimport { ScoutConfigurationError, ScoutDisposedError } from './errors';\nimport { createIndex, type ScoutIndex } from './scout-index';\nimport type { CreateSearchOptions, ScoutIndexOptions, SearchResult, SearchState } from './types';\n\n/**\n * Combined index + reactive search state returned by `createReactiveSearch()`.\n * Exposes the underlying `ScoutIndex` for incremental mutations (`add`, `remove`, `reindex`).\n */\nexport type ReactiveSearch<T> = SearchState<T> & {\n  readonly index: ScoutIndex<T>;\n};\n\nconst DEFAULT_DEBOUNCE = 200;\n\n/**\n * Creates a reactive search state backed by a `ScoutIndex`.\n *\n * - Set `state.query.value` to trigger a (debounced) search.\n * - Read `state.results.value` inside an `effect` or `computed` to consume results reactively.\n * - `state.isSearching.value` is `true` while debouncing, `false` otherwise.\n * - Call `state.dispose()` (or `using state = createSearch(...)`) to release subscriptions.\n *\n * @example\n * ```ts\n * const index = createIndex(users, { fields: ['name', 'email'] });\n * const search = createSearch(index, { debounce: 150 });\n *\n * effect(() => {\n *   const results = search.results.value;\n *   renderList(results.map(r => r.item));\n * });\n *\n * // Wire to an input\n * input.addEventListener('input', e => {\n *   search.query.value = e.currentTarget.value;\n * });\n *\n * // Clean up\n * search.dispose();\n * ```\n *\n * `results` also updates when the index is mutated directly via `index.add()` / `.remove()`\n * / `.reindex()` / `.setItems()` (not just when `query` changes), by subscribing to `index.onMutate()`.\n *\n * @param index - A `ScoutIndex` built with `createIndex()`.\n * @param options.debounce - Milliseconds to wait before committing query changes. Default: `200`.\n * @param options.limit - Override the index-level result limit.\n * @param options.minQueryLength - Override the index-level minimum query length.\n * @param options.threshold - Override the index-level score threshold.\n */\nexport function createSearch<T>(index: ScoutIndex<T>, options: CreateSearchOptions = {}): SearchState<T> {\n  const { debounce: debounceMs = DEFAULT_DEBOUNCE, limit, minQueryLength, threshold } = options;\n\n  if (!Number.isFinite(debounceMs) || !Number.isInteger(debounceMs) || debounceMs < 0) {\n    throw new ScoutConfigurationError('debounce must be a finite non-negative integer.');\n  }\n\n  const query = signal<string>('', { name: 'scout:query' });\n  const committedQuery = signal<string>('', { name: 'scout:committedQuery' });\n  const indexVersion = signal(0, { name: 'scout:indexVersion' });\n\n  const unsubscribeMutations = index.onMutate(() => {\n    indexVersion.value++;\n  });\n\n  const isSearching = computed(() => query.value !== committedQuery.value, { name: 'scout:isSearching' });\n\n  const results = computed<SearchResult<T>[]>(\n    () => {\n      // Reading .value establishes a dependency so index mutations trigger a recompute.\n      void indexVersion.value;\n\n      return index.search(committedQuery.value, { limit, minQueryLength, threshold });\n    },\n    { name: 'scout:results' },\n  );\n\n  let timer: ReturnType<typeof setTimeout> | null = null;\n\n  function cancelTimer(): void {\n    if (timer !== null) {\n      clearTimeout(timer);\n      timer = null;\n    }\n  }\n\n  const subscription = query.subscribe(() => {\n    const q = query.peek();\n\n    cancelTimer();\n\n    if (q === committedQuery.peek()) return;\n\n    if (debounceMs === 0) {\n      committedQuery.value = q;\n\n      return;\n    }\n\n    timer = setTimeout(() => {\n      committedQuery.value = q;\n      timer = null;\n    }, debounceMs);\n  });\n\n  function clear(): void {\n    if (isDisposed) throw new ScoutDisposedError('SearchState.clear() called after dispose()');\n\n    cancelTimer();\n\n    batch(() => {\n      query.value = '';\n      committedQuery.value = '';\n    });\n  }\n\n  let isDisposed = false;\n  const ac = new AbortController();\n\n  function dispose(): void {\n    isDisposed = true;\n    ac.abort();\n    cancelTimer();\n    subscription();\n    unsubscribeMutations();\n  }\n\n  return {\n    clear,\n    get disposalSignal(): AbortSignal {\n      return ac.signal;\n    },\n    dispose,\n    get disposed(): boolean {\n      return isDisposed;\n    },\n    isSearching,\n    query,\n    results,\n    [Symbol.dispose](): void {\n      dispose();\n    },\n  };\n}\n\n/**\n * Creates a `ScoutIndex` and a reactive search state in one call — the shorthand\n * for the common pattern of `createIndex` + `createSearch`.\n *\n * The returned `ReactiveSearch` exposes the underlying index via `.index` for\n * incremental mutations (`add`, `remove`, `reindex`, `setItems`) after construction.\n *\n * @example\n * ```ts\n * const search = createReactiveSearch(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   debounce: 150,\n * });\n *\n * effect(() => renderList(search.results.value.map(r => r.item)));\n *\n * // Wire to an input\n * input.addEventListener('input', e => { search.query.value = e.currentTarget.value; });\n *\n * // Add a new item at runtime\n * search.index.add(newUser);\n * ```\n *\n * @param items - Initial corpus to index.\n * @param options - Index options (`fields`, `limit`, `minQueryLength`, `threshold`) plus optional `debounce`.\n */\nexport function createReactiveSearch<T>(\n  items: T[],\n  options: ScoutIndexOptions<T> & Pick<CreateSearchOptions, 'debounce'>,\n): ReactiveSearch<T> {\n  const index = createIndex(items, {\n    fields: options.fields,\n    limit: options.limit,\n    minQueryLength: options.minQueryLength,\n    threshold: options.threshold,\n  });\n  const state = createSearch(index, { debounce: options.debounce });\n\n  return Object.assign(Object.create(state), { index }) as ReactiveSearch<T>;\n}\n"],"mappings":";;;;AAaA,IAAM,IAAmB;AAsCzB,SAAgB,EAAgB,GAAsB,IAA+B,CAAC,GAAmB;CACvG,IAAM,EAAE,UAAU,IAAa,GAAkB,UAAO,mBAAgB,iBAAc;CAEtF,IAAI,CAAC,OAAO,SAAS,CAAU,KAAK,CAAC,OAAO,UAAU,CAAU,KAAK,IAAa,GAChF,MAAM,IAAI,EAAwB,iDAAiD;CAGrF,IAAM,IAAQ,EAAe,IAAI,EAAE,MAAM,cAAc,CAAC,GAClD,IAAiB,EAAe,IAAI,EAAE,MAAM,uBAAuB,CAAC,GACpE,IAAe,EAAO,GAAG,EAAE,MAAM,qBAAqB,CAAC,GAEvD,IAAuB,EAAM,eAAe;EAChD,EAAa;CACf,CAAC,GAEK,IAAc,QAAe,EAAM,UAAU,EAAe,OAAO,EAAE,MAAM,oBAAoB,CAAC,GAEhG,IAAU,SAGZ,EAAkB,OAEX,EAAM,OAAO,EAAe,OAAO;EAAE;EAAO;EAAgB;CAAU,CAAC,IAEhF,EAAE,MAAM,gBAAgB,CAC1B,GAEI,IAA8C;CAElD,SAAS,IAAoB;EAC3B,AAAI,MAAU,SACZ,aAAa,CAAK,GAClB,IAAQ;CAEZ;CAEA,IAAM,IAAe,EAAM,gBAAgB;EACzC,IAAM,IAAI,EAAM,KAAK;EAErB,MAAY,GAER,MAAM,EAAe,KAAK,GAE9B;OAAI,MAAe,GAAG;IACpB,EAAe,QAAQ;IAEvB;GACF;GAEA,IAAQ,iBAAiB;IAEvB,AADA,EAAe,QAAQ,GACvB,IAAQ;GACV,GAAG,CAAU;EALb;CAMF,CAAC;CAED,SAAS,IAAc;EACrB,IAAI,GAAY,MAAM,IAAI,EAAmB,4CAA4C;EAIzF,AAFA,EAAY,GAEZ,QAAY;GAEV,AADA,EAAM,QAAQ,IACd,EAAe,QAAQ;EACzB,CAAC;CACH;CAEA,IAAI,IAAa,IACX,IAAK,IAAI,gBAAgB;CAE/B,SAAS,IAAgB;EAKvB,AAJA,IAAa,IACb,EAAG,MAAM,GACT,EAAY,GACZ,EAAa,GACb,EAAqB;CACvB;CAEA,OAAO;EACL;EACA,IAAI,iBAA8B;GAChC,OAAO,EAAG;EACZ;EACA;EACA,IAAI,WAAoB;GACtB,OAAO;EACT;EACA;EACA;EACA;EACA,CAAC,OAAO,WAAiB;GACvB,EAAQ;EACV;CACF;AACF;AA4BA,SAAgB,EACd,GACA,GACmB;CACnB,IAAM,IAAQ,EAAY,GAAO;EAC/B,QAAQ,EAAQ;EAChB,OAAO,EAAQ;EACf,gBAAgB,EAAQ;EACxB,WAAW,EAAQ;CACrB,CAAC,GACK,IAAQ,EAAa,GAAO,EAAE,UAAU,EAAQ,SAAS,CAAC;CAEhE,OAAO,OAAO,OAAO,OAAO,OAAO,CAAK,GAAG,EAAE,SAAM,CAAC;AACtD"}

package/dist/scout-index.cjs

@@ -1,2 +1,2 @@
-const e=require("./_index-state.cjs"),t=require("./errors.cjs"),n=require("./tokenize.cjs"),r=require("./highlight.cjs"),i=require("./trigram.cjs");function a(e,n,r){if(!Number.isFinite(e)||!Number.isInteger(e)||e<r)throw new t.ScoutConfigurationError(`${n} must be a finite integer greater than or equal to ${r}.`);return e}function o(e,n,r,i=1/0){if(!Number.isFinite(e)||e<r||e>i)throw new t.ScoutConfigurationError(`${n} must be a finite number between ${r} and ${i}.`);return e}function s(e){return e.map(e=>typeof e==`string`?{field:e,stringify:n.defaultStringify,weight:1}:{field:e.field,stringify:e.stringify??n.defaultStringify,weight:o(e.weight??1,`weight for field "${e.field}"`,Number.MIN_VALUE)})}function c(c,l){if(l.fields.length===0)throw new t.ScoutConfigurationError(`createIndex: at least one field is required.`);let u=s(l.fields),d=u.reduce((e,t)=>Math.max(e,t.weight),1),f=o(l.threshold??.2,`threshold`,0,1),p=a(l.limit??50,`limit`,0),m=a(l.minQueryLength??3,`minQueryLength`,1),h=new Map,g=new Map,_=new Set,v=0;function y(){v++;for(let e of _)e()}let b=null,x=null;function S(e){return e===b&&x!==null?x:(b=e,x=i.generateTrigrams(e),x)}function C(e,t){for(let n of t){let t=g.get(n);t||(t=new Set,g.set(n,t)),t.add(e)}}function w(e,t){for(let n of t){let t=g.get(n);t&&(t.delete(e),t.size===0&&g.delete(n))}}function T(e){let t=new Map,r=new Map;for(let{field:a,stringify:o}of u){let s=e[a],c=o(s),l=n.tokenize(c),u=l.length>=1?i.generateTrigrams(l):new Set;t.set(a,u),r.set(a,c),C(e,u)}h.set(e,{trigrams:t,values:r})}function E(e){let t=new Set;for(let[n,r]of h)for(let i of r.values.values())if(i.toLowerCase().includes(e)){t.add(n);break}return t}function D(e){let t=new Set;for(let n of e){let e=g.get(n);if(e)for(let n of e)t.add(n)}return t}function O(e,t,n){let r=0;for(let{field:a,weight:o}of u){let s;if(t===null)s=+!!(n.values.get(a)??``).toLowerCase().includes(e);else{let e=n.trigrams.get(a);if(!e||e.size===0)continue;s=i.overlapSimilarity(t,e)}let c=o/d*s;c>r&&(r=c)}return r}function k(e,t){let n=[];for(let{field:i}of u){let a=t.get(i);if(!a)continue;let o=r.findMatchRanges(a,e);o.length>0&&n.push({field:i,ranges:o})}return n}function A(e){let t=h.get(e);if(!t)return!1;let r=!1;for(let{field:a,stringify:o}of u){let s=o(e[a]);if(s===t.values.get(a))continue;r=!0;let c=t.trigrams.get(a);c&&w(e,c);let l=n.tokenize(s),u=l.length>=1?i.generateTrigrams(l):new Set;t.trigrams.set(a,u),t.values.set(a,s),C(e,u)}return r}function j(e){let t=h.get(e);if(!t)return!1;for(let n of t.trigrams.values())w(e,n);return h.delete(e),!0}for(let e of c)h.has(e)||T(e);let M={add(e){h.has(e)||(T(e),y())},get items(){return[...h.keys()]},onMutate(e){return _.add(e),()=>{_.delete(e)}},reindex(e){A(e)&&y()},remove(e){j(e)&&y()},search(e,t){let r=o(t?.threshold??f,`threshold`,0,1),i=a(t?.limit??p,`limit`,0),s=a(t?.minQueryLength??m,`minQueryLength`,1);if(!e.trim())return[...h.keys()].slice(0,i).map(e=>({item:e,matches:[],score:1}));let c=n.tokenize(e);if(!c)return[];let l=c.length<s?null:S(c),u=l===null?E(c):D(l),d=[];for(let e of u){let t=h.get(e);if(!t)continue;let n=O(c,l,t);if(n>=r){let r=k(c,t.values);d.push({item:e,matches:r,score:n})}}return d.sort((e,t)=>t.score-e.score).slice(0,i)},setItems(e){let t=new Set(e),n=[...t],r=!1;for(let e of[...h.keys()])t.has(e)||(j(e),r=!0);for(let e of n)h.has(e)?A(e)&&(r=!0):(T(e),r=!0);let i=[...h.keys()];if(i.length!==n.length||i.some((e,t)=>e!==n[t])){let e=new Map(n.map(e=>[e,h.get(e)]));h.clear();for(let[t,n]of e)h.set(t,n);r=!0}r&&y()},get size(){return h.size}};return e.registerIndexRevision(M,()=>v),M}exports.createIndex=c;
+const e=require("./errors.cjs"),t=require("./tokenize.cjs"),n=require("./highlight.cjs"),r=require("./trigram.cjs");function i(t,n,r){if(!Number.isFinite(t)||!Number.isInteger(t)||t<r)throw new e.ScoutConfigurationError(`${n} must be a finite integer greater than or equal to ${r}.`);return t}function a(t,n,r,i=1/0){if(!Number.isFinite(t)||t<r||t>i)throw new e.ScoutConfigurationError(`${n} must be a finite number between ${r} and ${i}.`);return t}function o(e){return e.map(e=>typeof e==`string`?{field:e,stringify:t.defaultStringify,weight:1}:{field:e.field,stringify:e.stringify??t.defaultStringify,weight:a(e.weight??1,`weight for field "${e.field}"`,Number.MIN_VALUE)})}function s(s,c){if(c.fields.length===0)throw new e.ScoutConfigurationError(`createIndex: at least one field is required.`);let l=o(c.fields),u=l.reduce((e,t)=>Math.max(e,t.weight),1),d=a(c.threshold??.2,`threshold`,0,1),f=i(c.limit??50,`limit`,0),p=i(c.minQueryLength??3,`minQueryLength`,1),m=new Map,h=new Map,g=new Set,_=0;function v(){_++;for(let e of g)e()}let y=null,b=null;function x(e){return e===y&&b!==null?b:(y=e,b=r.generateTrigrams(e),b)}function S(e,t){for(let n of t){let t=h.get(n);t||(t=new Set,h.set(n,t)),t.add(e)}}function C(e,t){for(let n of t){let t=h.get(n);t&&(t.delete(e),t.size===0&&h.delete(n))}}function w(e){let n=new Map,i=new Map;for(let{field:a,stringify:o}of l){let s=e[a],c=o(s),l=t.tokenize(c),u=l.length>=1?r.generateTrigrams(l):new Set;n.set(a,u),i.set(a,c),S(e,u)}m.set(e,{trigrams:n,values:i})}function T(e){let t=new Set;for(let[n,r]of m)for(let i of r.values.values())if(i.toLowerCase().includes(e)){t.add(n);break}return t}function E(e){let t=new Set;for(let n of e){let e=h.get(n);if(e)for(let n of e)t.add(n)}return t}function D(e,t,n){let i=0;for(let{field:a,weight:o}of l){let s;if(t===null)s=+!!(n.values.get(a)??``).toLowerCase().includes(e);else{let e=n.trigrams.get(a);if(!e||e.size===0)continue;s=r.overlapSimilarity(t,e)}let c=o/u*s;c>i&&(i=c)}return i}function O(e,t){let r=[];for(let{field:i}of l){let a=t.get(i);if(!a)continue;let o=n.findMatchRanges(a,e);o.length>0&&r.push({field:i,ranges:o})}return r}function k(e){let n=m.get(e);if(!n)return!1;let i=!1;for(let{field:a,stringify:o}of l){let s=o(e[a]);if(s===n.values.get(a))continue;i=!0;let c=n.trigrams.get(a);c&&C(e,c);let l=t.tokenize(s),u=l.length>=1?r.generateTrigrams(l):new Set;n.trigrams.set(a,u),n.values.set(a,s),S(e,u)}return i}function A(e){let t=m.get(e);if(!t)return!1;for(let n of t.trigrams.values())C(e,n);return m.delete(e),!0}for(let e of s)m.has(e)||w(e);return{add(e){m.has(e)||(w(e),v())},get items(){return[...m.keys()]},onMutate(e){return g.add(e),()=>{g.delete(e)}},reindex(e){k(e)&&v()},remove(e){A(e)&&v()},get revision(){return _},search(e,n){let r=a(n?.threshold??d,`threshold`,0,1),o=i(n?.limit??f,`limit`,0),s=i(n?.minQueryLength??p,`minQueryLength`,1);if(!e.trim())return[...m.keys()].slice(0,o).map(e=>({item:e,matches:[],score:1}));let c=t.tokenize(e);if(!c)return[];let l=c.length<s?null:x(c),u=l===null?T(c):E(l),h=[];for(let e of u){let t=m.get(e);if(!t)continue;let n=D(c,l,t);if(n>=r){let r=O(c,t.values);h.push({item:e,matches:r,score:n})}}return h.sort((e,t)=>t.score-e.score).slice(0,o)},setItems(e){let t=new Set(e),n=[...t],r=!1;for(let e of[...m.keys()])t.has(e)||(A(e),r=!0);for(let e of n)m.has(e)?k(e)&&(r=!0):(w(e),r=!0);let i=[...m.keys()];if(i.length!==n.length||i.some((e,t)=>e!==n[t])){let e=new Map(n.map(e=>[e,m.get(e)]));m.clear();for(let[t,n]of e)m.set(t,n);r=!0}r&&v()},get size(){return m.size}}}exports.createIndex=s;
 //# sourceMappingURL=scout-index.cjs.map

package/dist/scout-index.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"scout-index.cjs","names":[],"sources":["../src/scout-index.ts"],"sourcesContent":["import type { FieldDef, FieldMatch, ScoutIndexOptions, SearchConstraints, SearchResult } from './types';\n\nimport { registerIndexRevision } from './_index-state';\nimport { ScoutConfigurationError } from './errors';\nimport { findMatchRanges } from './highlight';\nimport { defaultStringify, tokenize } from './tokenize';\nimport { generateTrigrams, overlapSimilarity } from './trigram';\n\ntype FieldConfig<T> = {\n  field: keyof T & string;\n  stringify: (v: unknown) => string;\n  weight: number;\n};\n\ntype ItemRecord = {\n  /** Per-field trigrams for scoring. */\n  trigrams: Map<string, Set<string>>;\n  /** Per-field original text for highlighting. */\n  values: Map<string, string>;\n};\n\n/**\n * A stateful, indexed search corpus. Created via `createIndex()`.\n *\n * Supports incremental `add()`, `remove()`, and `reindex()` operations — each patches\n * the trigram index in O(field_length) without a full rebuild.\n */\nexport interface ScoutIndex<T> {\n  /** All items currently in the index, in insertion order. */\n  readonly items: readonly T[];\n  /** Number of items currently in the index. */\n  readonly size: number;\n  /** Adds `item` to the index. No-op if the item is already indexed (by reference). */\n  add(item: T): void;\n  /**\n   * Re-reads the item's current field values and rebuilds its index entry in-place,\n   * only updating fields whose values have changed. Preserves insertion order.\n   * No-op if the item is not in the index.\n   */\n  reindex(item: T): void;\n  /**\n   * Removes `item` from the index by reference equality.\n   * No-op if the item is not in the index.\n   */\n  remove(item: T): void;\n  /**\n   * Reconciles the index to `items` by reference identity. Retained items are reindexed,\n   * new items are added, missing items are removed, and one mutation notification fires\n   * when indexed corpus or field values change. Duplicate references collapse to one item.\n   */\n  setItems(items: readonly T[]): void;\n  /**\n   * Searches the index for `query` and returns results sorted by score descending.\n   *\n   * An empty (or whitespace-only) `query` returns all indexed items with `score = 1`.\n   * A `query` with no indexable content after normalization (e.g. punctuation-only) returns\n   * no results. Results below `threshold` are excluded. At most `limit` results are returned.\n   */\n  search(query: string, options?: SearchConstraints): SearchResult<T>[];\n  /**\n   * Subscribes `listener` to be called after every changed `add()` / `remove()` / `reindex()`\n   * / `setItems()` operation. No-ops — e.g. removing an unindexed item or reconciling an\n   * unchanged corpus — do not fire it. Each changed `setItems()` reconciliation fires once.\n   * Returns an unsubscribe function.\n   *\n   * Framework-agnostic extension point: `createSearch()` uses this internally to keep\n   * reactive `results` in sync with index mutations. Most callers won't need this directly.\n   */\n  onMutate(listener: () => void): () => void;\n}\n\nfunction requireFiniteInteger(value: number, name: string, minimum: number): number {\n  if (!Number.isFinite(value) || !Number.isInteger(value) || value < minimum) {\n    throw new ScoutConfigurationError(`${name} must be a finite integer greater than or equal to ${minimum}.`);\n  }\n\n  return value;\n}\n\nfunction requireFiniteNumber(value: number, name: string, minimum: number, maximum = Number.POSITIVE_INFINITY): number {\n  if (!Number.isFinite(value) || value < minimum || value > maximum) {\n    throw new ScoutConfigurationError(`${name} must be a finite number between ${minimum} and ${maximum}.`);\n  }\n\n  return value;\n}\n\nfunction resolveFields<T>(defs: ReadonlyArray<FieldDef<T>>): FieldConfig<T>[] {\n  return defs.map((def) => {\n    if (typeof def === 'string') {\n      return { field: def, stringify: defaultStringify, weight: 1 };\n    }\n\n    return {\n      field: def.field,\n      stringify: def.stringify ?? defaultStringify,\n      weight: requireFiniteNumber(def.weight ?? 1, `weight for field \"${def.field}\"`, Number.MIN_VALUE),\n    };\n  });\n}\n\n/**\n * Builds a trigram inverted index over `items` for fast fuzzy search.\n *\n * Construction is O(corpus × field_length). Subsequent `search()` calls are\n * O(candidates) — far faster than per-query Levenshtein for large corpora.\n *\n * @example\n * ```ts\n * const index = createIndex(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   threshold: 0.3,\n *   limit: 20,\n * });\n *\n * const results = index.search('alice');\n * ```\n *\n * @throws {ScoutConfigurationError} If options use an invalid field or numeric configuration.\n */\nexport function createIndex<T>(items: T[], options: ScoutIndexOptions<T>): ScoutIndex<T> {\n  if (options.fields.length === 0) {\n    throw new ScoutConfigurationError('createIndex: at least one field is required.');\n  }\n\n  const fields = resolveFields(options.fields);\n  const maxWeight = fields.reduce((max, f) => Math.max(max, f.weight), 1);\n  const defaultThreshold = requireFiniteNumber(options.threshold ?? 0.2, 'threshold', 0, 1);\n  const defaultLimit = requireFiniteInteger(options.limit ?? 50, 'limit', 0);\n  const defaultMinQueryLength = requireFiniteInteger(options.minQueryLength ?? 3, 'minQueryLength', 1);\n\n  /** item → per-item record, preserves insertion order for `items` getter */\n  const itemData = new Map<T, ItemRecord>();\n  /** trigram → set of items that contain it */\n  const invertedIndex = new Map<string, Set<T>>();\n  const mutationListeners = new Set<() => void>();\n  let revision = 0;\n\n  function notifyMutation(): void {\n    revision++;\n\n    for (const listener of mutationListeners) listener();\n  }\n\n  /** Single-entry cache for the most recent normalized query's trigrams (F2). */\n  let cachedNormalized: string | null = null;\n  let cachedTrigrams: Set<string> | null = null;\n\n  function getQueryTrigrams(normalized: string): Set<string> {\n    if (normalized === cachedNormalized && cachedTrigrams !== null) return cachedTrigrams;\n\n    cachedNormalized = normalized;\n    cachedTrigrams = generateTrigrams(normalized);\n\n    return cachedTrigrams;\n  }\n\n  function addFieldToIndex(item: T, fieldTrigrams: Set<string>): void {\n    for (const trigram of fieldTrigrams) {\n      let bucket = invertedIndex.get(trigram);\n\n      if (!bucket) {\n        bucket = new Set<T>();\n        invertedIndex.set(trigram, bucket);\n      }\n\n      bucket.add(item);\n    }\n  }\n\n  function removeFieldFromIndex(item: T, fieldTrigrams: Set<string>): void {\n    for (const trigram of fieldTrigrams) {\n      const bucket = invertedIndex.get(trigram);\n\n      if (bucket) {\n        bucket.delete(item);\n\n        if (bucket.size === 0) invertedIndex.delete(trigram);\n      }\n    }\n  }\n\n  function addItem(item: T): void {\n    const trigrams = new Map<string, Set<string>>();\n    const values = new Map<string, string>();\n\n    for (const { field, stringify } of fields) {\n      const raw = item[field];\n      const text = stringify(raw);\n      const normalized = tokenize(text);\n      const fieldTrigrams = normalized.length >= 1 ? generateTrigrams(normalized) : new Set<string>();\n\n      trigrams.set(field, fieldTrigrams);\n      values.set(field, text);\n      addFieldToIndex(item, fieldTrigrams);\n    }\n\n    itemData.set(item, { trigrams, values });\n  }\n\n  /**\n   * Performs a full linear scan over all items for short queries.\n   * O(n × field_count) — acceptable for small corpora; consider raising\n   * `minQueryLength` on large datasets to avoid triggering this path.\n   */\n  function containmentScan(query: string): Set<T> {\n    const result = new Set<T>();\n\n    for (const [item, record] of itemData) {\n      for (const value of record.values.values()) {\n        if (value.toLowerCase().includes(query)) {\n          result.add(item);\n          break;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  function trigramCandidates(queryTrigrams: Set<string>): Set<T> {\n    const candidates = new Set<T>();\n\n    for (const trigram of queryTrigrams) {\n      const items = invertedIndex.get(trigram);\n\n      if (items) {\n        for (const item of items) candidates.add(item);\n      }\n    }\n\n    return candidates;\n  }\n\n  function scoreCandidate(normalized: string, queryTrigrams: Set<string> | null, record: ItemRecord): number {\n    let bestScore = 0;\n\n    for (const { field, weight } of fields) {\n      let fieldScore: number;\n\n      if (queryTrigrams === null) {\n        const raw = record.values.get(field) ?? '';\n\n        fieldScore = raw.toLowerCase().includes(normalized) ? 1.0 : 0;\n      } else {\n        const itemTrigrams = record.trigrams.get(field);\n\n        if (!itemTrigrams || itemTrigrams.size === 0) continue;\n\n        fieldScore = overlapSimilarity(queryTrigrams, itemTrigrams);\n      }\n\n      const weighted = fieldScore * (weight / maxWeight);\n\n      if (weighted > bestScore) bestScore = weighted;\n    }\n\n    return bestScore;\n  }\n\n  function computeMatches(query: string, values: Map<string, string>): FieldMatch<keyof T & string>[] {\n    const matches: FieldMatch<keyof T & string>[] = [];\n\n    for (const { field } of fields) {\n      const text = values.get(field);\n\n      if (!text) continue;\n\n      const ranges = findMatchRanges(text, query);\n\n      if (ranges.length > 0) matches.push({ field, ranges });\n    }\n\n    return matches;\n  }\n\n  function reindexItem(item: T): boolean {\n    const record = itemData.get(item);\n\n    if (!record) return false;\n\n    let changed = false;\n\n    for (const { field, stringify } of fields) {\n      const newText = stringify(item[field]);\n      const oldText = record.values.get(field);\n\n      if (newText === oldText) continue;\n\n      changed = true;\n\n      const oldTrigrams = record.trigrams.get(field);\n\n      if (oldTrigrams) removeFieldFromIndex(item, oldTrigrams);\n\n      const normalized = tokenize(newText);\n      const newTrigrams = normalized.length >= 1 ? generateTrigrams(normalized) : new Set<string>();\n\n      record.trigrams.set(field, newTrigrams);\n      record.values.set(field, newText);\n      addFieldToIndex(item, newTrigrams);\n    }\n\n    return changed;\n  }\n\n  function removeItem(item: T): boolean {\n    const record = itemData.get(item);\n\n    if (!record) return false;\n\n    for (const fieldTrigrams of record.trigrams.values()) {\n      removeFieldFromIndex(item, fieldTrigrams);\n    }\n\n    itemData.delete(item);\n\n    return true;\n  }\n\n  for (const item of items) {\n    if (!itemData.has(item)) addItem(item);\n  }\n\n  const index: ScoutIndex<T> = {\n    add(item: T): void {\n      if (itemData.has(item)) return;\n\n      addItem(item);\n      notifyMutation();\n    },\n\n    get items(): readonly T[] {\n      return [...itemData.keys()];\n    },\n\n    onMutate(listener: () => void): () => void {\n      mutationListeners.add(listener);\n\n      return () => {\n        mutationListeners.delete(listener);\n      };\n    },\n\n    reindex(item: T): void {\n      if (reindexItem(item)) notifyMutation();\n    },\n\n    remove(item: T): void {\n      if (removeItem(item)) notifyMutation();\n    },\n\n    search(query: string, options?: SearchConstraints): SearchResult<T>[] {\n      const threshold = requireFiniteNumber(options?.threshold ?? defaultThreshold, 'threshold', 0, 1);\n      const limit = requireFiniteInteger(options?.limit ?? defaultLimit, 'limit', 0);\n      const minQueryLength = requireFiniteInteger(\n        options?.minQueryLength ?? defaultMinQueryLength,\n        'minQueryLength',\n        1,\n      );\n\n      if (!query.trim()) {\n        return [...itemData.keys()].slice(0, limit).map((item) => ({ item, matches: [], score: 1 }));\n      }\n\n      const normalized = tokenize(query);\n\n      // Query had no indexable content (e.g. punctuation-only) — no match, not \"match all\".\n      if (!normalized) return [];\n\n      const isShort = normalized.length < minQueryLength;\n      const queryTrigrams = isShort ? null : getQueryTrigrams(normalized);\n      const candidates = queryTrigrams === null ? containmentScan(normalized) : trigramCandidates(queryTrigrams);\n      const results: SearchResult<T>[] = [];\n\n      for (const item of candidates) {\n        const record = itemData.get(item);\n\n        if (!record) continue;\n\n        const score = scoreCandidate(normalized, queryTrigrams, record);\n\n        if (score >= threshold) {\n          const matches = computeMatches(normalized, record.values);\n\n          results.push({ item, matches, score });\n        }\n      }\n\n      return results.sort((a, b) => b.score - a.score).slice(0, limit);\n    },\n\n    setItems(items: readonly T[]): void {\n      const incoming = new Set(items);\n      const next = [...incoming];\n      let changed = false;\n\n      for (const item of [...itemData.keys()]) {\n        if (incoming.has(item)) continue;\n\n        removeItem(item);\n        changed = true;\n      }\n\n      for (const item of next) {\n        if (!itemData.has(item)) {\n          addItem(item);\n          changed = true;\n        } else if (reindexItem(item)) {\n          changed = true;\n        }\n      }\n\n      const current = [...itemData.keys()];\n      const orderChanged = current.length !== next.length || current.some((item, index) => item !== next[index]);\n\n      if (orderChanged) {\n        const records = new Map(next.map((item) => [item, itemData.get(item)!]));\n\n        itemData.clear();\n\n        for (const [item, record] of records) itemData.set(item, record);\n\n        changed = true;\n      }\n\n      if (changed) notifyMutation();\n    },\n\n    get size(): number {\n      return itemData.size;\n    },\n  };\n\n  registerIndexRevision(index, () => revision);\n\n  return index;\n}\n"],"mappings":"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"}
+{"version":3,"file":"scout-index.cjs","names":[],"sources":["../src/scout-index.ts"],"sourcesContent":["import { ScoutConfigurationError } from './errors';\nimport { findMatchRanges } from './highlight';\nimport { defaultStringify, tokenize } from './tokenize';\nimport { generateTrigrams, overlapSimilarity } from './trigram';\nimport type { FieldDef, FieldMatch, ScoutIndexOptions, SearchConstraints, SearchResult } from './types';\n\ntype FieldConfig<T> = {\n  field: keyof T & string;\n  stringify: (v: unknown) => string;\n  weight: number;\n};\n\ntype ItemRecord = {\n  /** Per-field trigrams for scoring. */\n  trigrams: Map<string, Set<string>>;\n  /** Per-field original text for highlighting. */\n  values: Map<string, string>;\n};\n\n/**\n * A stateful, indexed search corpus. Created via `createIndex()`.\n *\n * Supports incremental `add()`, `remove()`, and `reindex()` operations — each patches\n * the trigram index in O(field_length) without a full rebuild.\n */\nexport interface ScoutIndex<T> {\n  /** Adds `item` to the index. No-op if the item is already indexed (by reference). */\n  add(item: T): void;\n  /** All items currently in the index, in insertion order. */\n  readonly items: readonly T[];\n  /**\n   * Subscribes `listener` to be called after every changed `add()` / `remove()` / `reindex()`\n   * / `setItems()` operation. No-ops — e.g. removing an unindexed item or reconciling an\n   * unchanged corpus — do not fire it. Each changed `setItems()` reconciliation fires once.\n   * Returns an unsubscribe function.\n   *\n   * Framework-agnostic extension point: `createSearch()` uses this internally to keep\n   * reactive `results` in sync with index mutations. Most callers won't need this directly.\n   */\n  onMutate(listener: () => void): () => void;\n  /**\n   * Re-reads the item's current field values and rebuilds its index entry in-place,\n   * only updating fields whose values have changed. Preserves insertion order.\n   * No-op if the item is not in the index.\n   */\n  reindex(item: T): void;\n  /**\n   * Removes `item` from the index by reference equality.\n   * No-op if the item is not in the index.\n   */\n  remove(item: T): void;\n  /**\n   * Monotonically increasing counter, incremented after every changed `add()` / `remove()` /\n   * `reindex()` / `setItems()` operation. Use as a cache-busting token when caching search\n   * results outside the index — `toSearchMatcher()` uses it for this purpose.\n   */\n  readonly revision: number;\n  /**\n   * Searches the index for `query` and returns results sorted by score descending.\n   *\n   * An empty (or whitespace-only) `query` returns all indexed items with `score = 1`.\n   * A `query` with no indexable content after normalization (e.g. punctuation-only) returns\n   * no results. Results below `threshold` are excluded. At most `limit` results are returned.\n   */\n  search(query: string, options?: SearchConstraints): SearchResult<T>[];\n  /**\n   * Reconciles the index to `items` by reference identity. Retained items are reindexed,\n   * new items are added, missing items are removed, and one mutation notification fires\n   * when indexed corpus or field values change. Duplicate references collapse to one item.\n   */\n  setItems(items: readonly T[]): void;\n  /** Number of items currently in the index. */\n  readonly size: number;\n}\n\nfunction requireFiniteInteger(value: number, name: string, minimum: number): number {\n  if (!Number.isFinite(value) || !Number.isInteger(value) || value < minimum) {\n    throw new ScoutConfigurationError(`${name} must be a finite integer greater than or equal to ${minimum}.`);\n  }\n\n  return value;\n}\n\nfunction requireFiniteNumber(value: number, name: string, minimum: number, maximum = Number.POSITIVE_INFINITY): number {\n  if (!Number.isFinite(value) || value < minimum || value > maximum) {\n    throw new ScoutConfigurationError(`${name} must be a finite number between ${minimum} and ${maximum}.`);\n  }\n\n  return value;\n}\n\nfunction resolveFields<T>(defs: ReadonlyArray<FieldDef<T>>): FieldConfig<T>[] {\n  return defs.map((def) => {\n    if (typeof def === 'string') {\n      return { field: def, stringify: defaultStringify, weight: 1 };\n    }\n\n    return {\n      field: def.field,\n      stringify: def.stringify ?? defaultStringify,\n      weight: requireFiniteNumber(def.weight ?? 1, `weight for field \"${def.field}\"`, Number.MIN_VALUE),\n    };\n  });\n}\n\n/**\n * Builds a trigram inverted index over `items` for fast fuzzy search.\n *\n * Construction is O(corpus × field_length). Subsequent `search()` calls are\n * O(candidates) — far faster than per-query Levenshtein for large corpora.\n *\n * @example\n * ```ts\n * const index = createIndex(users, {\n *   fields: [{ field: 'name', weight: 2 }, 'email'],\n *   threshold: 0.3,\n *   limit: 20,\n * });\n *\n * const results = index.search('alice');\n * ```\n *\n * @throws {ScoutConfigurationError} If options use an invalid field or numeric configuration.\n */\nexport function createIndex<T>(items: T[], options: ScoutIndexOptions<T>): ScoutIndex<T> {\n  if (options.fields.length === 0) {\n    throw new ScoutConfigurationError('createIndex: at least one field is required.');\n  }\n\n  const fields = resolveFields(options.fields);\n  const maxWeight = fields.reduce((max, f) => Math.max(max, f.weight), 1);\n  const defaultThreshold = requireFiniteNumber(options.threshold ?? 0.2, 'threshold', 0, 1);\n  const defaultLimit = requireFiniteInteger(options.limit ?? 50, 'limit', 0);\n  const defaultMinQueryLength = requireFiniteInteger(options.minQueryLength ?? 3, 'minQueryLength', 1);\n\n  /** item → per-item record, preserves insertion order for `items` getter */\n  const itemData = new Map<T, ItemRecord>();\n  /** trigram → set of items that contain it */\n  const invertedIndex = new Map<string, Set<T>>();\n  const mutationListeners = new Set<() => void>();\n  let revision = 0;\n\n  function notifyMutation(): void {\n    revision++;\n\n    for (const listener of mutationListeners) listener();\n  }\n\n  /** Single-entry cache for the most recent normalized query's trigrams (F2). */\n  let cachedNormalized: string | null = null;\n  let cachedTrigrams: Set<string> | null = null;\n\n  function getQueryTrigrams(normalized: string): Set<string> {\n    if (normalized === cachedNormalized && cachedTrigrams !== null) return cachedTrigrams;\n\n    cachedNormalized = normalized;\n    cachedTrigrams = generateTrigrams(normalized);\n\n    return cachedTrigrams;\n  }\n\n  function addFieldToIndex(item: T, fieldTrigrams: Set<string>): void {\n    for (const trigram of fieldTrigrams) {\n      let bucket = invertedIndex.get(trigram);\n\n      if (!bucket) {\n        bucket = new Set<T>();\n        invertedIndex.set(trigram, bucket);\n      }\n\n      bucket.add(item);\n    }\n  }\n\n  function removeFieldFromIndex(item: T, fieldTrigrams: Set<string>): void {\n    for (const trigram of fieldTrigrams) {\n      const bucket = invertedIndex.get(trigram);\n\n      if (bucket) {\n        bucket.delete(item);\n\n        if (bucket.size === 0) invertedIndex.delete(trigram);\n      }\n    }\n  }\n\n  function addItem(item: T): void {\n    const trigrams = new Map<string, Set<string>>();\n    const values = new Map<string, string>();\n\n    for (const { field, stringify } of fields) {\n      const raw = item[field];\n      const text = stringify(raw);\n      const normalized = tokenize(text);\n      const fieldTrigrams = normalized.length >= 1 ? generateTrigrams(normalized) : new Set<string>();\n\n      trigrams.set(field, fieldTrigrams);\n      values.set(field, text);\n      addFieldToIndex(item, fieldTrigrams);\n    }\n\n    itemData.set(item, { trigrams, values });\n  }\n\n  /**\n   * Performs a full linear scan over all items for short queries.\n   * O(n × field_count) — acceptable for small corpora; consider raising\n   * `minQueryLength` on large datasets to avoid triggering this path.\n   */\n  function containmentScan(query: string): Set<T> {\n    const result = new Set<T>();\n\n    for (const [item, record] of itemData) {\n      for (const value of record.values.values()) {\n        if (value.toLowerCase().includes(query)) {\n          result.add(item);\n          break;\n        }\n      }\n    }\n\n    return result;\n  }\n\n  function trigramCandidates(queryTrigrams: Set<string>): Set<T> {\n    const candidates = new Set<T>();\n\n    for (const trigram of queryTrigrams) {\n      const items = invertedIndex.get(trigram);\n\n      if (items) {\n        for (const item of items) candidates.add(item);\n      }\n    }\n\n    return candidates;\n  }\n\n  function scoreCandidate(normalized: string, queryTrigrams: Set<string> | null, record: ItemRecord): number {\n    let bestScore = 0;\n\n    for (const { field, weight } of fields) {\n      let fieldScore: number;\n\n      if (queryTrigrams === null) {\n        const raw = record.values.get(field) ?? '';\n\n        fieldScore = raw.toLowerCase().includes(normalized) ? 1.0 : 0;\n      } else {\n        const itemTrigrams = record.trigrams.get(field);\n\n        if (!itemTrigrams || itemTrigrams.size === 0) continue;\n\n        fieldScore = overlapSimilarity(queryTrigrams, itemTrigrams);\n      }\n\n      const weighted = fieldScore * (weight / maxWeight);\n\n      if (weighted > bestScore) bestScore = weighted;\n    }\n\n    return bestScore;\n  }\n\n  function computeMatches(query: string, values: Map<string, string>): FieldMatch<keyof T & string>[] {\n    const matches: FieldMatch<keyof T & string>[] = [];\n\n    for (const { field } of fields) {\n      const text = values.get(field);\n\n      if (!text) continue;\n\n      const ranges = findMatchRanges(text, query);\n\n      if (ranges.length > 0) matches.push({ field, ranges });\n    }\n\n    return matches;\n  }\n\n  function reindexItem(item: T): boolean {\n    const record = itemData.get(item);\n\n    if (!record) return false;\n\n    let changed = false;\n\n    for (const { field, stringify } of fields) {\n      const newText = stringify(item[field]);\n      const oldText = record.values.get(field);\n\n      if (newText === oldText) continue;\n\n      changed = true;\n\n      const oldTrigrams = record.trigrams.get(field);\n\n      if (oldTrigrams) removeFieldFromIndex(item, oldTrigrams);\n\n      const normalized = tokenize(newText);\n      const newTrigrams = normalized.length >= 1 ? generateTrigrams(normalized) : new Set<string>();\n\n      record.trigrams.set(field, newTrigrams);\n      record.values.set(field, newText);\n      addFieldToIndex(item, newTrigrams);\n    }\n\n    return changed;\n  }\n\n  function removeItem(item: T): boolean {\n    const record = itemData.get(item);\n\n    if (!record) return false;\n\n    for (const fieldTrigrams of record.trigrams.values()) {\n      removeFieldFromIndex(item, fieldTrigrams);\n    }\n\n    itemData.delete(item);\n\n    return true;\n  }\n\n  for (const item of items) {\n    if (!itemData.has(item)) addItem(item);\n  }\n\n  const index: ScoutIndex<T> = {\n    add(item: T): void {\n      if (itemData.has(item)) return;\n\n      addItem(item);\n      notifyMutation();\n    },\n\n    get items(): readonly T[] {\n      return [...itemData.keys()];\n    },\n\n    onMutate(listener: () => void): () => void {\n      mutationListeners.add(listener);\n\n      return () => {\n        mutationListeners.delete(listener);\n      };\n    },\n\n    reindex(item: T): void {\n      if (reindexItem(item)) notifyMutation();\n    },\n\n    remove(item: T): void {\n      if (removeItem(item)) notifyMutation();\n    },\n\n    get revision(): number {\n      return revision;\n    },\n\n    search(query: string, options?: SearchConstraints): SearchResult<T>[] {\n      const threshold = requireFiniteNumber(options?.threshold ?? defaultThreshold, 'threshold', 0, 1);\n      const limit = requireFiniteInteger(options?.limit ?? defaultLimit, 'limit', 0);\n      const minQueryLength = requireFiniteInteger(\n        options?.minQueryLength ?? defaultMinQueryLength,\n        'minQueryLength',\n        1,\n      );\n\n      if (!query.trim()) {\n        return [...itemData.keys()].slice(0, limit).map((item) => ({ item, matches: [], score: 1 }));\n      }\n\n      const normalized = tokenize(query);\n\n      // Query had no indexable content (e.g. punctuation-only) — no match, not \"match all\".\n      if (!normalized) return [];\n\n      const isShort = normalized.length < minQueryLength;\n      const queryTrigrams = isShort ? null : getQueryTrigrams(normalized);\n      const candidates = queryTrigrams === null ? containmentScan(normalized) : trigramCandidates(queryTrigrams);\n      const results: SearchResult<T>[] = [];\n\n      for (const item of candidates) {\n        const record = itemData.get(item);\n\n        if (!record) continue;\n\n        const score = scoreCandidate(normalized, queryTrigrams, record);\n\n        if (score >= threshold) {\n          const matches = computeMatches(normalized, record.values);\n\n          results.push({ item, matches, score });\n        }\n      }\n\n      return results.sort((a, b) => b.score - a.score).slice(0, limit);\n    },\n\n    setItems(items: readonly T[]): void {\n      const incoming = new Set(items);\n      const next = [...incoming];\n      let changed = false;\n\n      for (const item of [...itemData.keys()]) {\n        if (incoming.has(item)) continue;\n\n        removeItem(item);\n        changed = true;\n      }\n\n      for (const item of next) {\n        if (!itemData.has(item)) {\n          addItem(item);\n          changed = true;\n        } else if (reindexItem(item)) {\n          changed = true;\n        }\n      }\n\n      const current = [...itemData.keys()];\n      const orderChanged = current.length !== next.length || current.some((item, index) => item !== next[index]);\n\n      if (orderChanged) {\n        const records = new Map(next.map((item) => [item, itemData.get(item)!]));\n\n        itemData.clear();\n\n        for (const [item, record] of records) itemData.set(item, record);\n\n        changed = true;\n      }\n\n      if (changed) notifyMutation();\n    },\n\n    get size(): number {\n      return itemData.size;\n    },\n  };\n\n  return index;\n}\n"],"mappings":"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"}

package/dist/scout-index.d.ts

@@ -6,12 +6,20 @@ import type { ScoutIndexOptions, SearchConstraints, SearchResult } from './types
  * the trigram index in O(field_length) without a full rebuild.
  */
 export interface ScoutIndex<T> {
-    /** All items currently in the index, in insertion order. */
-    readonly items: readonly T[];
-    /** Number of items currently in the index. */
-    readonly size: number;
     /** Adds `item` to the index. No-op if the item is already indexed (by reference). */
     add(item: T): void;
+    /** All items currently in the index, in insertion order. */
+    readonly items: readonly T[];
+    /**
+     * Subscribes `listener` to be called after every changed `add()` / `remove()` / `reindex()`
+     * / `setItems()` operation. No-ops — e.g. removing an unindexed item or reconciling an
+     * unchanged corpus — do not fire it. Each changed `setItems()` reconciliation fires once.
+     * Returns an unsubscribe function.
+     *
+     * Framework-agnostic extension point: `createSearch()` uses this internally to keep
+     * reactive `results` in sync with index mutations. Most callers won't need this directly.
+     */
+    onMutate(listener: () => void): () => void;
     /**
      * Re-reads the item's current field values and rebuilds its index entry in-place,
      * only updating fields whose values have changed. Preserves insertion order.
@@ -24,11 +32,11 @@ export interface ScoutIndex<T> {
      */
     remove(item: T): void;
     /**
-     * Reconciles the index to `items` by reference identity. Retained items are reindexed,
-     * new items are added, missing items are removed, and one mutation notification fires
-     * when indexed corpus or field values change. Duplicate references collapse to one item.
+     * Monotonically increasing counter, incremented after every changed `add()` / `remove()` /
+     * `reindex()` / `setItems()` operation. Use as a cache-busting token when caching search
+     * results outside the index — `toSearchMatcher()` uses it for this purpose.
      */
-    setItems(items: readonly T[]): void;
+    readonly revision: number;
     /**
      * Searches the index for `query` and returns results sorted by score descending.
      *
@@ -38,15 +46,13 @@ export interface ScoutIndex<T> {
      */
     search(query: string, options?: SearchConstraints): SearchResult<T>[];
     /**
-     * Subscribes `listener` to be called after every changed `add()` / `remove()` / `reindex()`
-     * / `setItems()` operation. No-ops — e.g. removing an unindexed item or reconciling an
-     * unchanged corpus — do not fire it. Each changed `setItems()` reconciliation fires once.
-     * Returns an unsubscribe function.
-     *
-     * Framework-agnostic extension point: `createSearch()` uses this internally to keep
-     * reactive `results` in sync with index mutations. Most callers won't need this directly.
+     * Reconciles the index to `items` by reference identity. Retained items are reindexed,
+     * new items are added, missing items are removed, and one mutation notification fires
+     * when indexed corpus or field values change. Duplicate references collapse to one item.
      */
-    onMutate(listener: () => void): () => void;
+    setItems(items: readonly T[]): void;
+    /** Number of items currently in the index. */
+    readonly size: number;
 }
 /**
  * Builds a trigram inverted index over `items` for fast fuzzy search.

package/dist/scout-index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"scout-index.d.ts","sourceRoot":"","sources":["../src/scout-index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAwB,iBAAiB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAqBxG;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,qFAAqF;IACrF,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACnB;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;IACpC;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;CAC5C;AAgCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CA6TvF"}
+{"version":3,"file":"scout-index.d.ts","sourceRoot":"","sources":["../src/scout-index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAwB,iBAAiB,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,SAAS,CAAC;AAexG;;;;;GAKG;AACH,MAAM,WAAW,UAAU,CAAC,CAAC;IAC3B,qFAAqF;IACrF,GAAG,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACnB,4DAA4D;IAC5D,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,CAAC;IAC7B;;;;;;;;OAQG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,IAAI,GAAG,MAAM,IAAI,CAAC;IAC3C;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACvB;;;OAGG;IACH,MAAM,CAAC,IAAI,EAAE,CAAC,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B;;;;;;OAMG;IACH,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,iBAAiB,GAAG,YAAY,CAAC,CAAC,CAAC,EAAE,CAAC;IACtE;;;;OAIG;IACH,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,EAAE,GAAG,IAAI,CAAC;IACpC,8CAA8C;IAC9C,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAgCD;;;;;;;;;;;;;;;;;;GAkBG;AACH,wBAAgB,WAAW,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,EAAE,EAAE,OAAO,EAAE,iBAAiB,CAAC,CAAC,CAAC,GAAG,UAAU,CAAC,CAAC,CAAC,CA+TvF"}