@cbcruk/highlight-kit 0.1.0

package/README.md

@@ -0,0 +1,259 @@
+# @cbcruk/highlight-kit
+
+CSS Custom Highlight API 기반 텍스트 하이라이팅 라이브러리. DOM을 건드리지 않고
+텍스트를 하이라이트합니다. 프레임워크 무관 core와 얇은 React 어댑터를 제공합니다.
+
+## 설치
+
+```bash
+pnpm add @cbcruk/highlight-kit
+```
+
+ESM 전용 패키지이며 타입 정의가 함께 포함됩니다. React 어댑터(`@cbcruk/highlight-kit/react`)는
+`react >= 18`을 필요로 하지만 **optional peer dependency**라, core만 쓰면 React 없이 동작합니다.
+
+## 사용법
+
+### Core (프레임워크 무관)
+
+```typescript
+import {
+  highlights,
+  computeRanges,
+  injectHighlightStyles,
+} from '@cbcruk/highlight-kit'
+
+injectHighlightStyles({
+  search: { backgroundColor: '#fef08a', color: '#854d0e' },
+})
+
+const el = document.querySelector('#article')!
+const ranges = computeRanges(el, 'wisdom', { caseSensitive: false })
+
+// (name, sourceId, ranges) — 같은 name에 여러 source가 union 됨
+highlights.set('search', 'my-source', ranges)
+
+highlights.remove('search', 'my-source') // 한 source만 제거
+highlights.clear('search') // name 통째로 제거
+```
+
+핵심: `set/remove/clear`는 name별로 여러 **source**의 기여를 합쳐 단일 `Highlight`로
+reconcile합니다. 서로 다른 패널 두 곳에서 `'error'` 이름으로 하이라이트해도, CSS는
+`::highlight(error)` 규칙 하나로 둘 다 스타일링됩니다.
+
+### React
+
+#### 선언적 컴포넌트
+
+```tsx
+import { Highlight } from '@cbcruk/highlight-kit/react'
+
+function Article({ keyword }: { keyword: string }) {
+  return (
+    <Highlight query={keyword} name="search">
+      <article>{/* ...긴 본문... */}</article>
+    </Highlight>
+  )
+}
+```
+
+```css
+::highlight(search) {
+  background: #fef08a;
+  color: #854d0e;
+}
+```
+
+`as` prop으로 wrapper 태그 변경, 레이아웃 영향을 없애려면 `display: contents`:
+
+```tsx
+<Highlight query={q} name="search" as="section" style={{ display: 'contents' }}>
+  {children}
+</Highlight>
+```
+
+#### Headless 훅
+
+```tsx
+import { useHighlight } from '@cbcruk/highlight-kit/react'
+
+function SearchableText({ query }: { query: string }) {
+  const { ref, count, active } = useHighlight<HTMLDivElement>({
+    query,
+    name: 'search',
+    caseSensitive: false,
+  })
+
+  return (
+    <>
+      <span>{count}개 일치</span>
+      <div ref={ref}>{/* ...본문... */}</div>
+    </>
+  )
+}
+```
+
+`name`을 생략하면 `useId` 기반 고유 이름이 자동 생성됩니다(인스턴스별 격리).
+
+#### 검색 + 네비게이션
+
+```tsx
+import { useRef, useState } from 'react'
+import {
+  HighlightStyles,
+  useHighlightSearch,
+} from '@cbcruk/highlight-kit/react'
+
+function Search() {
+  const ref = useRef<HTMLDivElement>(null)
+  const [query, setQuery] = useState('wisdom')
+  const { count, active, next, prev } = useHighlightSearch(ref, query)
+
+  return (
+    <>
+      <HighlightStyles />
+      <input value={query} onChange={(e) => setQuery(e.target.value)} />
+      <span>{count === 0 ? '0/0' : `${active + 1}/${count}`}</span>
+      <button onClick={prev}>↑</button>
+      <button onClick={next}>↓</button>
+      <div ref={ref}>...본문...</div>
+    </>
+  )
+}
+```
+
+전체 매치는 `search`, 현재 항목은 더 높은 priority의 `search-current` 이름으로
+하이라이트되고 자동으로 `scrollIntoView`됩니다. `options.name`으로 기본 이름을 바꿀 수
+있습니다. `<HighlightStyles />`는 이 두 이름의 기본 색상을 넣어 줍니다.
+
+#### 한 컨테이너에 여러 패턴: `Highlight.Root` + `Highlight.Match`
+
+```tsx
+import { Highlight } from '@cbcruk/highlight-kit/react'
+
+function Logs({ logs }: { logs: string }) {
+  return (
+    <Highlight.Root name="log-info" as="pre">
+      {logs}
+      <Highlight.Match name="log-error" pattern={/ERROR:[^\n]*/} />
+      <Highlight.Match name="log-warn" pattern={/WARN:[^\n]*/} />
+      {/* name 생략 → Root의 name */}
+      <Highlight.Match pattern={/INFO:[^\n]*/} />
+    </Highlight.Root>
+  )
+}
+```
+
+`Highlight.Match`는 effect-only(`return null`)입니다. Root 컨테이너를 스캔해 하이라이트만
+등록하며, 기본으로 DOM 변경을 `MutationObserver`로 추적합니다.
+
+#### 상태만 구독 / 지원 여부
+
+```tsx
+import {
+  useHighlightState,
+  useHighlightSupport,
+} from '@cbcruk/highlight-kit/react'
+
+const { count, active } = useHighlightState('search') // 읽기 전용 구독
+const all = useHighlightSnapshots() // { [name]: { count, active } }
+const supported = useHighlightSupport() // SSR 중엔 false
+```
+
+#### 테스트 / controller 주입
+
+jsdom에는 `Highlight`가 없으므로, 부수효과 없는 sink로 만든 controller를 주입해
+bookkeeping만 검증합니다.
+
+```tsx
+import {
+  createHighlightController,
+  createNoopSink,
+} from '@cbcruk/highlight-kit'
+import { HighlightProvider } from '@cbcruk/highlight-kit/react'
+
+const controller = createHighlightController({ sink: createNoopSink() })
+render(
+  <HighlightProvider controller={controller}>
+    <SearchUI />
+  </HighlightProvider>,
+)
+expect(controller.getSnapshot('search').count).toBe(3)
+```
+
+## API
+
+### core
+
+| export                                 | 설명                                                                                                                      |
+| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `highlights`                           | singleton 컨트롤러 (`set` / `remove` / `clear` / `clearAll` / `getRanges` / `subscribe` / `getSnapshot` / `getSnapshots`) |
+| `createHighlightController({ sink? })` | 격리된 컨트롤러 생성 (테스트·Provider용)                                                                                  |
+| `createCssHighlightSink()`             | `CSS.highlights`에 반영하는 기본 sink                                                                                     |
+| `createNoopSink()`                     | 부수효과 없는 sink (SSR/테스트용, 미지원 환경에서도 bookkeeping 수행)                                                     |
+| `computeRanges(root, pattern, opts?)`  | 패턴(string/RegExp) 매칭 → `Range[]` (`caseSensitive` / `wholeWord` 옵션)                                                 |
+| `rangesFromOffsets(root, spans)`       | 문자 offset 배열 → `Range[]` (`root.textContent` 기준, 공백만 있는 텍스트 노드 포함)                                      |
+| `getTextNodes(root)`                   | 하위 텍스트 노드 수집 (공백만 있는 노드 제외)                                                                             |
+| `isHighlightSupported()`               | API 지원 여부                                                                                                             |
+| `generateHighlightCSS(styles)`         | `::highlight()` CSS 문자열 생성 (주입 없이 반환)                                                                          |
+| `injectHighlightStyles(styles, id?)`   | `::highlight()` CSS 동적 주입 (`<style>` 삽입)                                                                            |
+
+### react (`@cbcruk/highlight-kit/react`)
+
+| export                                        | 설명                                                                          |
+| --------------------------------------------- | ----------------------------------------------------------------------------- |
+| `useHighlight(opts)`                          | headless. `ref` + `{ count, active, name }` 반환 (`priority`, `observe` 옵션) |
+| `useHighlightSearch(ref, query, opts?)`       | 검색 + `next`/`prev` 네비게이션                                               |
+| `useTextMatches(target, pattern, opts?)`      | 매칭된 `Range[]` 추적 (ref 또는 element, `observe` 기본 true)                 |
+| `useHighlightRanges(name, ranges, priority?)` | 직접 계산한 `Range[]` 등록 (effect-only)                                      |
+| `useHighlightState(name)`                     | name의 `{ count, active }` 읽기 전용 구독                                     |
+| `useHighlightSnapshots()`                     | 모든 활성 name의 스냅샷 구독                                                  |
+| `useHighlightSupport()`                       | 지원 여부 (SSR-safe)                                                          |
+| `useHighlightController()`                    | 현재 scope의 컨트롤러                                                         |
+| `<HighlightProvider controller?>`             | 컨트롤러 주입 (생략 시 격리된 컨트롤러 생성)                                  |
+| `<Highlight query name as>`                   | 선언적 wrapper                                                                |
+| `<Highlight.Root>` / `<Highlight.Match>`      | 한 컨테이너에 여러 패턴                                                       |
+| `<HighlightStyles styles?>`                   | `::highlight()` 규칙 `<style>` (기본: `search` / `search-current`)            |
+
+타입도 함께 export됩니다: `MatchOptions`, `HighlightSnapshot`, `HighlightController`,
+`HighlightSink`, `SourceId`, `UseHighlightOptions`, `UseHighlightResult`,
+`UseHighlightSearchOptions`, `UseHighlightSearchResult`, `TextMatchOptions`, `HighlightProps`,
+`HighlightRootProps`, `HighlightMatchProps`, `HighlightStyleMap`.
+
+## 설계 노트 / 한계
+
+- **DOM 변경 추적**: `useHighlight` / `<Highlight>`는 기본적으로 `query`/`name`/옵션이
+  바뀔 때만 재계산합니다. 동적 콘텐츠면 `observe`를 켜세요. `useTextMatches` /
+  `useHighlightSearch` / `<Highlight.Match>`는 기본으로 추적합니다.
+- **box model 미지원**: 둥근 테두리 등이 필요하면 `controller.getRanges(name)` →
+  `Range.getClientRects()`로 overlay를 직접 그립니다 (`src/demo.tsx` 참고).
+- **hit-test 불가**: 하이라이트는 클릭/hover 대상이 아닙니다.
+- **이름은 document 전역**: `HighlightProvider` 격리는 구독 그래프/테스트용이며, 같은 DOM에서
+  같은 이름을 두 컨트롤러가 칠하면 서로 덮어씁니다.
+- **Shadow DOM**: `TreeWalker`는 shadow 경계를 넘지 않습니다.
+- **SSR**: `getServerSnapshot`이 항상 빈 스냅샷을 반환하고, 등록은 layout effect에서
+  일어나므로 hydration 불일치가 없습니다.
+- **`::highlight()` 지원 속성**: `color`, `background-color`, `text-decoration`(브라우저
+  차이 있음), `text-shadow`, `-webkit-text-stroke/fill` 등 제한적.
+
+## 브라우저 지원
+
+Chrome/Edge 105+, Safari 17.2+, Firefox 140+ (2025-06~) — 전 메이저 브라우저 커버.
+
+## 개발
+
+eunsoolib 모노레포 패키지로 통합되어 있습니다. 진입점은
+[src/index.ts](src/index.ts)(core)와 [src/react.tsx](src/react.tsx)(React 어댑터)이며,
+[src/demo.tsx](src/demo.tsx)에 검색·다중 이름·RegExp·range overlay 데모가 있습니다.
+
+> `@cbcruk/use-highlight-search`는 이 패키지로 통합되었습니다. `HighlightStoreProvider` →
+> `HighlightProvider`, `createHighlightStore` → `createHighlightController`,
+> `useHighlight(name, ranges)` → `useHighlightRanges(name, ranges)`,
+> `store.getSnapshot()[name]` → `controller.getSnapshot(name).count`로 옮기면 됩니다.
+
+```bash
+pnpm test:run packages/highlight-kit   # Vitest (jsdom)
+```
+
+`src/highlight-api.d.ts`는 `lib.dom`이 아직 불완전하게 타입한 `HighlightRegistry`의
+maplike 멤버(`set`/`get`/`delete` 등)를 보강하는 빌드 전용 선언입니다.

package/dist/core-B8g04jvB.d.ts

@@ -0,0 +1,168 @@
+//#region src/core.d.ts
+/** Options controlling how a string pattern is matched against text. */
+interface MatchOptions {
+  /**
+   * Case sensitive match. Ignored for `RegExp` patterns, which keep their own flags.
+   * @default false
+   */
+  caseSensitive?: boolean;
+  /**
+   * Match whole words only (wraps the pattern in `\b`). Ignored for `RegExp` patterns.
+   * @default false
+   */
+  wholeWord?: boolean;
+}
+/** Reactive state of one highlight name, as exposed to subscribers. */
+interface HighlightSnapshot {
+  /** Whether this name currently has any registered ranges */
+  readonly active: boolean;
+  /** Number of ranges registered under this name */
+  readonly count: number;
+}
+/** A source contributing ranges, keyed by a unique id (e.g. React's useId) */
+type SourceId = string | symbol;
+/**
+ * Where reconciled ranges are written. The controller's bookkeeping always
+ * runs; only this side effect is swappable (CSS registry, no-op for tests/SSR).
+ */
+interface HighlightSink {
+  /** Replace the registered highlight for `name` with `ranges`. */
+  commit(name: string, ranges: Range[], priority: number): void;
+  /** Drop the registered highlight for `name`. */
+  remove(name: string): void;
+  /**
+   * When this returns false the controller skips bookkeeping entirely, so
+   * snapshots stay empty. Omit it to always track ranges.
+   */
+  isSupported?(): boolean;
+}
+/** Options for {@link createHighlightController}. */
+interface HighlightControllerOptions {
+  /** Where reconciled ranges are written. Defaults to {@link createCssHighlightSink}. */
+  sink?: HighlightSink;
+}
+/** Whether the CSS Custom Highlight API (`CSS.highlights` and `Highlight`) is available. */
+declare function isHighlightSupported(): boolean;
+/**
+ * Collect the text nodes under an element that contain non-whitespace text.
+ *
+ * Whitespace-only nodes (newlines, indentation between elements) are skipped,
+ * so this is suited to pattern matching, not to offset math against `textContent`.
+ */
+declare function getTextNodes(root: Node): Text[];
+/**
+ * Compute Range objects for every match of `pattern` within `root`.
+ * Pure: returns ranges, does not touch the registry.
+ */
+declare function computeRanges(root: Element, pattern: string | RegExp, options?: MatchOptions): Range[];
+/**
+ * Map flat character offsets onto Range objects. Useful when you already know positions.
+ *
+ * Offsets count over `root.textContent`, whitespace-only text nodes (newlines,
+ * indentation between elements) included, so positions computed from
+ * `textContent` or on a server against the same text line up. Unlike
+ * {@link computeRanges}, a span may cross text node boundaries; it yields one
+ * range per text node it touches. Out-of-bounds parts are ignored.
+ *
+ * @example
+ * ```ts
+ * import { rangesFromOffsets } from '@cbcruk/highlight-kit'
+ *
+ * const el = document.querySelector('#article')!
+ * const start = el.textContent!.indexOf('wisdom')
+ * rangesFromOffsets(el, [{ start, end: start + 'wisdom'.length }])
+ * ```
+ */
+declare function rangesFromOffsets(root: Element, spans: ReadonlyArray<{
+  start: number;
+  end: number;
+}>): Range[];
+/** Sink that writes to the document-global `CSS.highlights` registry. */
+declare function createCssHighlightSink(): HighlightSink;
+/** Side-effect-free sink: bookkeeping still runs, nothing is painted. */
+declare function createNoopSink(): HighlightSink;
+/**
+ * Tracks ranges per highlight name and source, and writes their union to a sink.
+ *
+ * Multiple sources may contribute to one name; each change reconciles the name
+ * into a single highlight and notifies `subscribe` listeners. Create instances
+ * with {@link createHighlightController} or use the shared {@link highlights}.
+ *
+ * @example
+ * ```ts
+ * import { computeRanges, highlights } from '@cbcruk/highlight-kit'
+ *
+ * const el = document.querySelector('#article')!
+ * highlights.set('search', 'my-source', computeRanges(el, 'wisdom'))
+ * highlights.getSnapshot('search') // { active: true, count: ... }
+ * highlights.remove('search', 'my-source')
+ * ```
+ */
+declare class HighlightController {
+  #private;
+  /** Create a controller that writes to `sink` (the CSS registry sink by default). */
+  constructor({ sink }?: HighlightControllerOptions);
+  /**
+   * Whether the sink reports support. `true` when the sink has no `isSupported`.
+   * When `false`, {@link HighlightController.set} is a no-op.
+   */
+  get supported(): boolean;
+  /** useSyncExternalStore: stable identity (arrow field on the instance). */
+  subscribe: (listener: () => void) => (() => void);
+  /** Snapshot for a given highlight name (referentially stable). */
+  getSnapshot: (name: string) => HighlightSnapshot;
+  /** Snapshots of every active name (referentially stable between changes). */
+  getSnapshots: () => Readonly<Record<string, HighlightSnapshot>>;
+  /** SSR / unsupported: constant empty snapshot. */
+  getServerSnapshot: () => HighlightSnapshot;
+  /** SSR / unsupported: constant empty record. */
+  getServerSnapshots: () => Readonly<Record<string, HighlightSnapshot>>;
+  /** Union of every source's ranges currently registered under `name`. */
+  getRanges(name: string): Range[];
+  /**
+   * Register/replace a source's ranges under a name, then reconcile.
+   * `priority` applies to the whole name; the most recent call wins.
+   */
+  set(name: string, sourceId: SourceId, ranges: Range[], priority?: number): void;
+  /** Remove a single source's contribution to a name. */
+  remove(name: string, sourceId: SourceId): void;
+  /** Drop a name entirely, regardless of sources. */
+  clear(name: string): void;
+  /** Drop everything this controller manages. */
+  clearAll(): void;
+}
+/**
+ * Create an isolated controller. Useful for tests (with {@link createNoopSink})
+ * or for scoping subscriptions via the React `HighlightProvider`. Highlight
+ * *names* are still document-global once painted by a CSS sink.
+ */
+declare function createHighlightController(options?: HighlightControllerOptions): HighlightController;
+/** The shared singleton. */
+declare const highlights: HighlightController;
+/**
+ * Build `::highlight(name)` CSS rules from a style map without injecting them.
+ *
+ * camelCase property names are converted to kebab-case; values are written as is.
+ *
+ * @example
+ * ```ts
+ * import { generateHighlightCSS } from '@cbcruk/highlight-kit'
+ *
+ * generateHighlightCSS({ search: { backgroundColor: 'yellow' } })
+ * // '::highlight(search) {\n  background-color: yellow;\n}'
+ * ```
+ */
+declare function generateHighlightCSS(styles: Record<string, Partial<CSSStyleDeclaration>>): string;
+/**
+ * Append a `<style>` element with `::highlight()` rules to `document.head`.
+ *
+ * An existing element with the same `id` is removed first, so calling it again
+ * replaces the previous rules.
+ *
+ * @param styles - Style declarations keyed by highlight name
+ * @param id - `id` of the `<style>` element
+ * @returns The inserted `<style>` element
+ */
+declare function injectHighlightStyles(styles: Record<string, Partial<CSSStyleDeclaration>>, id?: string): HTMLStyleElement;
+//#endregion
+export { MatchOptions as a, createCssHighlightSink as c, generateHighlightCSS as d, getTextNodes as f, rangesFromOffsets as g, isHighlightSupported as h, HighlightSnapshot as i, createHighlightController as l, injectHighlightStyles as m, HighlightControllerOptions as n, SourceId as o, highlights as p, HighlightSink as r, computeRanges as s, HighlightController as t, createNoopSink as u };

package/dist/core-LUnH63zG.js

@@ -0,0 +1,306 @@
+//#region src/core.ts
+/** Stable empty snapshot — referentially constant for useSyncExternalStore */
+const EMPTY_SNAPSHOT = Object.freeze({
+	active: false,
+	count: 0
+});
+/** Whether the CSS Custom Highlight API (`CSS.highlights` and `Highlight`) is available. */
+function isHighlightSupported() {
+	return typeof CSS !== "undefined" && "highlights" in CSS && typeof Highlight !== "undefined";
+}
+/**
+* Collect the text nodes under an element that contain non-whitespace text.
+*
+* Whitespace-only nodes (newlines, indentation between elements) are skipped,
+* so this is suited to pattern matching, not to offset math against `textContent`.
+*/
+function getTextNodes(root) {
+	const nodes = [];
+	const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
+	let node;
+	while (node = walker.nextNode()) if (node.textContent && node.textContent.trim()) nodes.push(node);
+	return nodes;
+}
+function toRegExp(pattern, options) {
+	if (pattern instanceof RegExp) return pattern.flags.includes("g") ? pattern : new RegExp(pattern.source, pattern.flags + "g");
+	const escaped = pattern.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+	const body = options.wholeWord ? `\\b${escaped}\\b` : escaped;
+	return new RegExp(body, options.caseSensitive ? "g" : "gi");
+}
+/**
+* Compute Range objects for every match of `pattern` within `root`.
+* Pure: returns ranges, does not touch the registry.
+*/
+function computeRanges(root, pattern, options = {}) {
+	if (!pattern) return [];
+	const regex = toRegExp(pattern, options);
+	const ranges = [];
+	for (const textNode of getTextNodes(root)) {
+		const text = textNode.textContent ?? "";
+		regex.lastIndex = 0;
+		let m;
+		while ((m = regex.exec(text)) !== null) {
+			if (m[0].length === 0) {
+				regex.lastIndex++;
+				continue;
+			}
+			try {
+				const range = new Range();
+				range.setStart(textNode, m.index);
+				range.setEnd(textNode, m.index + m[0].length);
+				ranges.push(range);
+			} catch {}
+		}
+	}
+	return ranges;
+}
+/** Collect every text node under `root`, whitespace-only ones included. */
+function getAllTextNodes(root) {
+	const nodes = [];
+	const walker = document.createTreeWalker(root, NodeFilter.SHOW_TEXT, null);
+	let node;
+	while (node = walker.nextNode()) nodes.push(node);
+	return nodes;
+}
+/**
+* Map flat character offsets onto Range objects. Useful when you already know positions.
+*
+* Offsets count over `root.textContent`, whitespace-only text nodes (newlines,
+* indentation between elements) included, so positions computed from
+* `textContent` or on a server against the same text line up. Unlike
+* {@link computeRanges}, a span may cross text node boundaries; it yields one
+* range per text node it touches. Out-of-bounds parts are ignored.
+*
+* @example
+* ```ts
+* import { rangesFromOffsets } from '@cbcruk/highlight-kit'
+*
+* const el = document.querySelector('#article')!
+* const start = el.textContent!.indexOf('wisdom')
+* rangesFromOffsets(el, [{ start, end: start + 'wisdom'.length }])
+* ```
+*/
+function rangesFromOffsets(root, spans) {
+	const nodes = getAllTextNodes(root);
+	const layout = [];
+	let offset = 0;
+	for (const node of nodes) {
+		const len = node.textContent?.length ?? 0;
+		if (len === 0) continue;
+		layout.push({
+			node,
+			start: offset,
+			end: offset + len
+		});
+		offset += len;
+	}
+	const ranges = [];
+	for (const { start, end } of spans) for (const { node, start: ns, end: ne } of layout) if (ns < end && ne > start) try {
+		const range = new Range();
+		range.setStart(node, Math.max(0, start - ns));
+		range.setEnd(node, Math.min(node.textContent?.length ?? 0, end - ns));
+		ranges.push(range);
+	} catch {}
+	return ranges;
+}
+/** Sink that writes to the document-global `CSS.highlights` registry. */
+function createCssHighlightSink() {
+	return {
+		commit(name, ranges, priority) {
+			if (!isHighlightSupported()) return;
+			const highlight = new Highlight(...ranges);
+			highlight.priority = priority;
+			CSS.highlights.set(name, highlight);
+		},
+		remove(name) {
+			if (!isHighlightSupported()) return;
+			CSS.highlights.delete(name);
+		},
+		isSupported: isHighlightSupported
+	};
+}
+/** Side-effect-free sink: bookkeeping still runs, nothing is painted. */
+function createNoopSink() {
+	return {
+		commit() {},
+		remove() {}
+	};
+}
+const EMPTY_SNAPSHOTS = Object.freeze({});
+/**
+* Tracks ranges per highlight name and source, and writes their union to a sink.
+*
+* Multiple sources may contribute to one name; each change reconciles the name
+* into a single highlight and notifies `subscribe` listeners. Create instances
+* with {@link createHighlightController} or use the shared {@link highlights}.
+*
+* @example
+* ```ts
+* import { computeRanges, highlights } from '@cbcruk/highlight-kit'
+*
+* const el = document.querySelector('#article')!
+* highlights.set('search', 'my-source', computeRanges(el, 'wisdom'))
+* highlights.getSnapshot('search') // { active: true, count: ... }
+* highlights.remove('search', 'my-source')
+* ```
+*/
+var HighlightController = class {
+	#sink;
+	/** name -> (sourceId -> ranges). Multiple sources may share a name. */
+	#entries = /* @__PURE__ */ new Map();
+	/** Cached per-name snapshots; refs are stable until that name changes. */
+	#snapshots = /* @__PURE__ */ new Map();
+	/** Cached name -> snapshot record; rebuilt on every emit. */
+	#allSnapshots = EMPTY_SNAPSHOTS;
+	/** External-store listeners. */
+	#listeners = /* @__PURE__ */ new Set();
+	/** Create a controller that writes to `sink` (the CSS registry sink by default). */
+	constructor({ sink = createCssHighlightSink() } = {}) {
+		this.#sink = sink;
+	}
+	/**
+	* Whether the sink reports support. `true` when the sink has no `isSupported`.
+	* When `false`, {@link HighlightController.set} is a no-op.
+	*/
+	get supported() {
+		return this.#sink.isSupported?.() ?? true;
+	}
+	/** useSyncExternalStore: stable identity (arrow field on the instance). */
+	subscribe = (listener) => {
+		this.#listeners.add(listener);
+		return () => this.#listeners.delete(listener);
+	};
+	/** Snapshot for a given highlight name (referentially stable). */
+	getSnapshot = (name) => {
+		return this.#snapshots.get(name) ?? EMPTY_SNAPSHOT;
+	};
+	/** Snapshots of every active name (referentially stable between changes). */
+	getSnapshots = () => {
+		return this.#allSnapshots;
+	};
+	/** SSR / unsupported: constant empty snapshot. */
+	getServerSnapshot = () => EMPTY_SNAPSHOT;
+	/** SSR / unsupported: constant empty record. */
+	getServerSnapshots = () => EMPTY_SNAPSHOTS;
+	/** Union of every source's ranges currently registered under `name`. */
+	getRanges(name) {
+		const entry = this.#entries.get(name);
+		return entry ? this.#merge(entry) : [];
+	}
+	/**
+	* Register/replace a source's ranges under a name, then reconcile.
+	* `priority` applies to the whole name; the most recent call wins.
+	*/
+	set(name, sourceId, ranges, priority = 0) {
+		if (!this.supported) return;
+		let entry = this.#entries.get(name);
+		if (!entry) {
+			entry = {
+				priority,
+				sources: /* @__PURE__ */ new Map()
+			};
+			this.#entries.set(name, entry);
+		} else entry.priority = priority;
+		entry.sources.set(sourceId, ranges);
+		this.#reconcile(name);
+		this.#emit();
+	}
+	/** Remove a single source's contribution to a name. */
+	remove(name, sourceId) {
+		const entry = this.#entries.get(name);
+		if (!entry || !entry.sources.delete(sourceId)) return;
+		if (entry.sources.size === 0) this.#entries.delete(name);
+		this.#reconcile(name);
+		this.#emit();
+	}
+	/** Drop a name entirely, regardless of sources. */
+	clear(name) {
+		if (!this.#entries.delete(name)) return;
+		this.#reconcile(name);
+		this.#emit();
+	}
+	/** Drop everything this controller manages. */
+	clearAll() {
+		const names = [...this.#entries.keys()];
+		this.#entries.clear();
+		for (const name of names) this.#sink.remove(name);
+		this.#snapshots.clear();
+		this.#emit();
+	}
+	#merge(entry) {
+		const all = [];
+		for (const ranges of entry.sources.values()) all.push(...ranges);
+		return all;
+	}
+	/** Union all sources for `name` into one highlight and update the snapshot. */
+	#reconcile(name) {
+		const entry = this.#entries.get(name);
+		const all = entry ? this.#merge(entry) : [];
+		if (!entry || all.length === 0) {
+			this.#sink.remove(name);
+			this.#snapshots.set(name, EMPTY_SNAPSHOT);
+			return;
+		}
+		this.#sink.commit(name, all, entry.priority);
+		this.#snapshots.set(name, {
+			active: true,
+			count: all.length
+		});
+	}
+	#emit() {
+		const next = {};
+		for (const [name, snapshot] of this.#snapshots) if (snapshot.active) next[name] = snapshot;
+		this.#allSnapshots = next;
+		for (const listener of this.#listeners) listener();
+	}
+};
+/**
+* Create an isolated controller. Useful for tests (with {@link createNoopSink})
+* or for scoping subscriptions via the React `HighlightProvider`. Highlight
+* *names* are still document-global once painted by a CSS sink.
+*/
+function createHighlightController(options) {
+	return new HighlightController(options);
+}
+/** The shared singleton. */
+const highlights = createHighlightController();
+/**
+* Build `::highlight(name)` CSS rules from a style map without injecting them.
+*
+* camelCase property names are converted to kebab-case; values are written as is.
+*
+* @example
+* ```ts
+* import { generateHighlightCSS } from '@cbcruk/highlight-kit'
+*
+* generateHighlightCSS({ search: { backgroundColor: 'yellow' } })
+* // '::highlight(search) {\n  background-color: yellow;\n}'
+* ```
+*/
+function generateHighlightCSS(styles) {
+	return Object.entries(styles).map(([name, style]) => {
+		return `::highlight(${name}) {\n${Object.entries(style).map(([prop, value]) => {
+			return `  ${prop.replace(/([A-Z])/g, "-$1").toLowerCase()}: ${value};`;
+		}).join("\n")}\n}`;
+	}).join("\n\n");
+}
+/**
+* Append a `<style>` element with `::highlight()` rules to `document.head`.
+*
+* An existing element with the same `id` is removed first, so calling it again
+* replaces the previous rules.
+*
+* @param styles - Style declarations keyed by highlight name
+* @param id - `id` of the `<style>` element
+* @returns The inserted `<style>` element
+*/
+function injectHighlightStyles(styles, id = "highlight-kit-styles") {
+	document.getElementById(id)?.remove();
+	const el = document.createElement("style");
+	el.id = id;
+	el.textContent = generateHighlightCSS(styles);
+	document.head.appendChild(el);
+	return el;
+}
+//#endregion
+export { generateHighlightCSS as a, injectHighlightStyles as c, createNoopSink as i, isHighlightSupported as l, createCssHighlightSink as n, getTextNodes as o, createHighlightController as r, highlights as s, computeRanges as t, rangesFromOffsets as u };

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+import { a as MatchOptions, c as createCssHighlightSink, d as generateHighlightCSS, f as getTextNodes, g as rangesFromOffsets, h as isHighlightSupported, i as HighlightSnapshot, l as createHighlightController, m as injectHighlightStyles, n as HighlightControllerOptions, o as SourceId, p as highlights, r as HighlightSink, s as computeRanges, t as HighlightController, u as createNoopSink } from "./core-B8g04jvB.js";
+export { type HighlightController, HighlightControllerOptions, HighlightSink, HighlightSnapshot, MatchOptions, SourceId, computeRanges, createCssHighlightSink, createHighlightController, createNoopSink, generateHighlightCSS, getTextNodes, highlights, injectHighlightStyles, isHighlightSupported, rangesFromOffsets };

package/dist/index.js

@@ -0,0 +1,2 @@
+import { a as generateHighlightCSS, c as injectHighlightStyles, i as createNoopSink, l as isHighlightSupported, n as createCssHighlightSink, o as getTextNodes, r as createHighlightController, s as highlights, t as computeRanges, u as rangesFromOffsets } from "./core-LUnH63zG.js";
+export { computeRanges, createCssHighlightSink, createHighlightController, createNoopSink, generateHighlightCSS, getTextNodes, highlights, injectHighlightStyles, isHighlightSupported, rangesFromOffsets };

package/dist/react.d.ts

@@ -0,0 +1,263 @@
+import { a as MatchOptions, i as HighlightSnapshot, p as highlights, t as HighlightController } from "./core-B8g04jvB.js";
+import { CSSProperties, ComponentPropsWithoutRef, ElementType, ReactNode, RefObject } from "react";
+//#region src/react.d.ts
+/** The controller in scope — the shared singleton unless a provider overrides it. */
+export declare function useHighlightController(): HighlightController;
+/** Props for {@link HighlightProvider}. */
+export interface HighlightProviderProps {
+  /** Omit to create an isolated controller once for this provider. */
+  controller?: HighlightController;
+  /** Subtree whose hooks use this controller. */
+  children?: ReactNode;
+}
+/**
+ * Scope hooks below to a specific controller. Mostly for tests (inject one
+ * built with `createNoopSink()`); highlight *names* remain document-global.
+ */
+export declare function HighlightProvider({ controller, children }: HighlightProviderProps): ReactNode;
+/** Read-only reactive subscription to one highlight name's state. */
+export declare function useHighlightState(name: string): HighlightSnapshot;
+/** Read-only reactive subscription to every active name's state. */
+export declare function useHighlightSnapshots(): Readonly<Record<string, HighlightSnapshot>>;
+/** Whether the Custom Highlight API is available (false during SSR). */
+export declare function useHighlightSupport(): boolean;
+/**
+ * Register precomputed `ranges` under `name` for this component instance.
+ * Effect-only: re-registers whenever the `ranges` reference changes and removes
+ * its contribution on unmount.
+ */
+export declare function useHighlightRanges(name: string, ranges: Range[], priority?: number): void;
+/** Match options for {@link useTextMatches}, plus DOM change tracking. */
+export interface TextMatchOptions extends MatchOptions {
+  /**
+   * Recompute when the container's DOM changes (MutationObserver).
+   * @default true
+   */
+  observe?: boolean;
+}
+/**
+ * Track the ranges matching `pattern` inside `target` (a ref or an element).
+ * With `observe` (default true) child/text mutations trigger a recompute.
+ *
+ * Pass the element itself when it is owned by a *parent* component: a parent's
+ * ref is attached only after its children's layout effects have run.
+ */
+export declare function useTextMatches(target: RefObject<Element | null> | Element | null, pattern: string | RegExp, options?: TextMatchOptions): Range[];
+/** Options for {@link useHighlight}. */
+export interface UseHighlightOptions extends MatchOptions {
+  /** The text/regex to highlight. Falsy clears this source. */
+  query: string | RegExp;
+  /** CSS ::highlight() name. Defaults to a unique per-instance name. */
+  name?: string;
+  /**
+   * Stacking order against other highlight names.
+   * @default 0
+   */
+  priority?: number;
+  /**
+   * Recompute when the container's DOM changes (MutationObserver).
+   * @default false
+   */
+  observe?: boolean;
+}
+/**
+ * Return value of {@link useHighlight}: the container ref, the resolved name,
+ * and that name's current snapshot.
+ *
+ * @template T - Element type the `ref` is attached to
+ */
+export interface UseHighlightResult<T extends Element = HTMLElement> extends HighlightSnapshot {
+  /** Attach to the element whose text you want to scan. */
+  ref: RefObject<T | null>;
+  /** The resolved highlight name (auto-generated if not provided). */
+  name: string;
+}
+/**
+ * Headless highlighting. Attach the returned `ref` to any container; the hook
+ * keeps that container's matches for `query` registered under `name`, and
+ * reconciles on every change. Cleans up its own contribution on unmount.
+ *
+ * @template T - Element type the `ref` is attached to
+ *
+ * @example
+ * ```tsx
+ * import { useHighlight } from '@cbcruk/highlight-kit/react'
+ *
+ * function SearchableText({ query }: { query: string }) {
+ *   const { ref, count } = useHighlight<HTMLDivElement>({ query, name: 'search' })
+ *   return (
+ *     <>
+ *       <span>{count} matches</span>
+ *       <div ref={ref}>...</div>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export declare function useHighlight<T extends Element = HTMLElement>(options: UseHighlightOptions): UseHighlightResult<T>;
+/** Options for {@link useHighlightSearch}. */
+export interface UseHighlightSearchOptions extends TextMatchOptions {
+  /**
+   * Base highlight name. The active match is registered under
+   * `${name}-current` with a higher priority.
+   * @default 'search'
+   */
+  name?: string;
+}
+/** Return value of {@link useHighlightSearch}. */
+export interface UseHighlightSearchResult {
+  /** Number of ranges registered under the base name. */
+  count: number;
+  /** Index of the active match, or -1 when there are no matches. */
+  active: number;
+  /** Move to the next match, wrapping to the first after the last. */
+  next(): void;
+  /** Move to the previous match, wrapping to the last before the first. */
+  prev(): void;
+}
+/**
+ * Search with next/prev navigation. All matches go to `name`, the active one to
+ * `${name}-current`, and the active match is scrolled into view.
+ *
+ * When the matches change, the active index is clamped to the new match count.
+ *
+ * @example
+ * ```tsx
+ * import { useRef, useState } from 'react'
+ * import { HighlightStyles, useHighlightSearch } from '@cbcruk/highlight-kit/react'
+ *
+ * function Search() {
+ *   const ref = useRef<HTMLDivElement>(null)
+ *   const [query, setQuery] = useState('wisdom')
+ *   const { count, active, next, prev } = useHighlightSearch(ref, query)
+ *   return (
+ *     <>
+ *       <HighlightStyles />
+ *       <input value={query} onChange={(e) => setQuery(e.target.value)} />
+ *       <span>{count === 0 ? '0/0' : `${active + 1}/${count}`}</span>
+ *       <button onClick={prev}>Prev</button>
+ *       <button onClick={next}>Next</button>
+ *       <div ref={ref}>...</div>
+ *     </>
+ *   )
+ * }
+ * ```
+ */
+export declare function useHighlightSearch(containerRef: RefObject<Element | null>, query: string | RegExp, options?: UseHighlightSearchOptions): UseHighlightSearchResult;
+/** Props for the declarative {@link Highlight} component. */
+export interface HighlightProps extends MatchOptions {
+  /** The text/regex to highlight. Falsy clears this source. */
+  query: string | RegExp;
+  /** CSS ::highlight() name. Defaults to a unique per-instance name. */
+  name?: string;
+  /**
+   * Stacking order against other highlight names.
+   * @default 0
+   */
+  priority?: number;
+  /**
+   * Recompute when the container's DOM changes (MutationObserver).
+   * @default false
+   */
+  observe?: boolean;
+  /**
+   * Element to render as the scan container.
+   * @default 'div'
+   */
+  as?: ElementType;
+  /** Content rendered inside the container and scanned for matches. */
+  children?: ReactNode;
+  /** Class name for the container element. */
+  className?: string;
+  /** Inline style for the container element. Tip: pass `{ display: 'contents' }` for zero layout impact. */
+  style?: CSSProperties;
+}
+declare function HighlightComponent({ query, name, priority, observe, as, caseSensitive, wholeWord, children, ...rest }: HighlightProps): ReactNode;
+/** Props for {@link HighlightRoot}; other `div` props go to the rendered element. */
+export interface HighlightRootProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
+  /** Default highlight name for nested <Highlight.Match> without `name`. */
+  name: string;
+  /**
+   * Element to render as the scan container.
+   * @default 'div'
+   */
+  as?: ElementType;
+  /** Content rendered inside the container, including `<Highlight.Match>` elements. */
+  children?: ReactNode;
+}
+/** Scan container for one or more <Highlight.Match> children. */
+export declare const HighlightRoot: import("react").ForwardRefExoticComponent<HighlightRootProps & import("react").RefAttributes<HTMLElement>>;
+/** Props for {@link HighlightMatch}. */
+export interface HighlightMatchProps extends TextMatchOptions {
+  /** The text/regex to find in the enclosing Root's container. */
+  pattern: string | RegExp;
+  /** Falls back to the enclosing Root's `name`. */
+  name?: string;
+  /**
+   * Stacking order against other highlight names.
+   * @default 0
+   */
+  priority?: number;
+}
+/**
+ * Effect-only: renders nothing, scans the enclosing Root's container and
+ * registers the matches. Tracks DOM changes by default (`observe`).
+ *
+ * @throws When rendered outside `<Highlight.Root>`.
+ */
+export declare function HighlightMatch({ pattern, name, priority, ...matchOptions }: HighlightMatchProps): null;
+/**
+ * Renders a single wrapper element and highlights matches of `query` within it.
+ *
+ * Multiple <Highlight> sharing the same `name` are unioned by the core, so one
+ * ::highlight(name) CSS rule styles them all.
+ *
+ * For several patterns over one container use the compound form:
+ * `Highlight.Root` with nested `Highlight.Match` elements.
+ *
+ * @example Single pattern
+ * ```tsx
+ * import { Highlight } from '@cbcruk/highlight-kit/react'
+ *
+ * function Article({ keyword }: { keyword: string }) {
+ *   return (
+ *     <Highlight query={keyword} name="search" style={{ display: 'contents' }}>
+ *       <article>...</article>
+ *     </Highlight>
+ *   )
+ * }
+ * ```
+ *
+ * @example Several patterns over one container
+ * ```tsx
+ * import { Highlight } from '@cbcruk/highlight-kit/react'
+ *
+ * function Logs({ logs }: { logs: string }) {
+ *   return (
+ *     <Highlight.Root name="log-info" as="pre">
+ *       {logs}
+ *       <Highlight.Match name="log-error" pattern={/ERROR:[^\n]+/} />
+ *       <Highlight.Match pattern={/INFO:[^\n]+/} />
+ *     </Highlight.Root>
+ *   )
+ * }
+ * ```
+ */
+export declare const Highlight: typeof HighlightComponent & {
+  Root: import("react").ForwardRefExoticComponent<HighlightRootProps & import("react").RefAttributes<HTMLElement>>;
+  Match: typeof HighlightMatch;
+};
+/** `::highlight()` style declarations keyed by highlight name. */
+export type HighlightStyleMap = Record<string, Partial<CSSStyleDeclaration>>;
+/** Props for {@link HighlightStyles}. */
+export interface HighlightStylesProps {
+  /** `::highlight()` rules by name (default: `search` / `search-current`). */
+  styles?: HighlightStyleMap;
+}
+/**
+ * Inline `<style>` with `::highlight()` rules. Defaults match the names used by
+ * {@link useHighlightSearch}.
+ */
+export declare function HighlightStyles({ styles }: HighlightStylesProps): ReactNode;
+//#endregion
+export { highlights };

package/dist/react.js

@@ -0,0 +1,320 @@
+import { a as generateHighlightCSS, l as isHighlightSupported, r as createHighlightController, s as highlights, t as computeRanges } from "./core-LUnH63zG.js";
+import { createContext, createElement, forwardRef, useCallback, useContext, useEffect, useId, useImperativeHandle, useLayoutEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
+import { jsx } from "react/jsx-runtime";
+//#region src/react.tsx
+/**
+* @highlight-kit/react
+*
+* Thin React adapter over the core controller.
+*   - reactive reads via useSyncExternalStore (SSR-safe)
+*   - each component instance is a distinct "source" via useId
+*   - writes happen in layout effects only; reads never trigger writes
+*   - declarative <Highlight> / <Highlight.Root> wrap the headless hooks
+*/
+const useIsomorphicLayoutEffect = typeof window !== "undefined" ? useLayoutEffect : useEffect;
+const ControllerContext = createContext(highlights);
+/** The controller in scope — the shared singleton unless a provider overrides it. */
+function useHighlightController() {
+	return useContext(ControllerContext);
+}
+/**
+* Scope hooks below to a specific controller. Mostly for tests (inject one
+* built with `createNoopSink()`); highlight *names* remain document-global.
+*/
+function HighlightProvider({ controller, children }) {
+	const fallback = useRef(null);
+	if (!controller && fallback.current === null) fallback.current = createHighlightController();
+	return /* @__PURE__ */ jsx(ControllerContext.Provider, {
+		value: controller ?? fallback.current,
+		children
+	});
+}
+/** Read-only reactive subscription to one highlight name's state. */
+function useHighlightState(name) {
+	const controller = useHighlightController();
+	return useSyncExternalStore(controller.subscribe, () => controller.getSnapshot(name), controller.getServerSnapshot);
+}
+/** Read-only reactive subscription to every active name's state. */
+function useHighlightSnapshots() {
+	const controller = useHighlightController();
+	return useSyncExternalStore(controller.subscribe, controller.getSnapshots, controller.getServerSnapshots);
+}
+/** Whether the Custom Highlight API is available (false during SSR). */
+function useHighlightSupport() {
+	return useSyncExternalStore(() => () => {}, () => isHighlightSupported(), () => false);
+}
+/**
+* Register precomputed `ranges` under `name` for this component instance.
+* Effect-only: re-registers whenever the `ranges` reference changes and removes
+* its contribution on unmount.
+*/
+function useHighlightRanges(name, ranges, priority = 0) {
+	const controller = useHighlightController();
+	const sourceId = useId();
+	useIsomorphicLayoutEffect(() => {
+		controller.set(name, sourceId, ranges, priority);
+		return () => controller.remove(name, sourceId);
+	}, [
+		controller,
+		name,
+		sourceId,
+		ranges,
+		priority
+	]);
+}
+/**
+* Track the ranges matching `pattern` inside `target` (a ref or an element).
+* With `observe` (default true) child/text mutations trigger a recompute.
+*
+* Pass the element itself when it is owned by a *parent* component: a parent's
+* ref is attached only after its children's layout effects have run.
+*/
+function useTextMatches(target, pattern, options = {}) {
+	const { caseSensitive, wholeWord, observe = true } = options;
+	const [ranges, setRanges] = useState([]);
+	useIsomorphicLayoutEffect(() => {
+		const el = target && "current" in target ? target.current : target;
+		if (!el) return;
+		const compute = () => setRanges(computeRanges(el, pattern, {
+			caseSensitive,
+			wholeWord
+		}));
+		compute();
+		if (!observe) return;
+		const observer = new MutationObserver(compute);
+		observer.observe(el, {
+			childList: true,
+			subtree: true,
+			characterData: true
+		});
+		return () => observer.disconnect();
+	}, [
+		target,
+		pattern,
+		caseSensitive,
+		wholeWord,
+		observe
+	]);
+	return ranges;
+}
+/**
+* Headless highlighting. Attach the returned `ref` to any container; the hook
+* keeps that container's matches for `query` registered under `name`, and
+* reconciles on every change. Cleans up its own contribution on unmount.
+*
+* @template T - Element type the `ref` is attached to
+*
+* @example
+* ```tsx
+* import { useHighlight } from '@cbcruk/highlight-kit/react'
+*
+* function SearchableText({ query }: { query: string }) {
+*   const { ref, count } = useHighlight<HTMLDivElement>({ query, name: 'search' })
+*   return (
+*     <>
+*       <span>{count} matches</span>
+*       <div ref={ref}>...</div>
+*     </>
+*   )
+* }
+* ```
+*/
+function useHighlight(options) {
+	const { query, caseSensitive, wholeWord, priority = 0, observe } = options;
+	const controller = useHighlightController();
+	const autoId = useId();
+	const name = options.name ?? `hk-${autoId}`;
+	const sourceId = autoId;
+	const ref = useRef(null);
+	useIsomorphicLayoutEffect(() => {
+		const el = ref.current;
+		if (!el || !query) {
+			controller.remove(name, sourceId);
+			return;
+		}
+		const register = () => controller.set(name, sourceId, computeRanges(el, query, {
+			caseSensitive,
+			wholeWord
+		}), priority);
+		register();
+		const observer = observe ? new MutationObserver(register) : null;
+		observer?.observe(el, {
+			childList: true,
+			subtree: true,
+			characterData: true
+		});
+		return () => {
+			observer?.disconnect();
+			controller.remove(name, sourceId);
+		};
+	}, [
+		controller,
+		name,
+		sourceId,
+		query,
+		caseSensitive,
+		wholeWord,
+		priority,
+		observe
+	]);
+	return {
+		ref,
+		name,
+		...useHighlightState(name)
+	};
+}
+/**
+* Search with next/prev navigation. All matches go to `name`, the active one to
+* `${name}-current`, and the active match is scrolled into view.
+*
+* When the matches change, the active index is clamped to the new match count.
+*
+* @example
+* ```tsx
+* import { useRef, useState } from 'react'
+* import { HighlightStyles, useHighlightSearch } from '@cbcruk/highlight-kit/react'
+*
+* function Search() {
+*   const ref = useRef<HTMLDivElement>(null)
+*   const [query, setQuery] = useState('wisdom')
+*   const { count, active, next, prev } = useHighlightSearch(ref, query)
+*   return (
+*     <>
+*       <HighlightStyles />
+*       <input value={query} onChange={(e) => setQuery(e.target.value)} />
+*       <span>{count === 0 ? '0/0' : `${active + 1}/${count}`}</span>
+*       <button onClick={prev}>Prev</button>
+*       <button onClick={next}>Next</button>
+*       <div ref={ref}>...</div>
+*     </>
+*   )
+* }
+* ```
+*/
+function useHighlightSearch(containerRef, query, options = {}) {
+	const { name = "search", ...matchOptions } = options;
+	const matches = useTextMatches(containerRef, query, matchOptions);
+	const [active, setActive] = useState(0);
+	useIsomorphicLayoutEffect(() => {
+		setActive((a) => matches.length === 0 ? 0 : Math.min(a, matches.length - 1));
+	}, [matches]);
+	const activeRange = useMemo(() => matches[active] ? [matches[active]] : [], [matches, active]);
+	useHighlightRanges(name, matches, 0);
+	useHighlightRanges(`${name}-current`, activeRange, 1);
+	useEffect(() => {
+		(matches[active]?.startContainer?.parentElement)?.scrollIntoView?.({ block: "nearest" });
+	}, [matches, active]);
+	const { count } = useHighlightState(name);
+	const next = useCallback(() => setActive((a) => matches.length ? (a + 1) % matches.length : 0), [matches.length]);
+	const prev = useCallback(() => setActive((a) => matches.length ? (a - 1 + matches.length) % matches.length : 0), [matches.length]);
+	return {
+		count,
+		active: matches.length ? active : -1,
+		next,
+		prev
+	};
+}
+function HighlightComponent({ query, name, priority, observe, as = "div", caseSensitive, wholeWord, children, ...rest }) {
+	const { ref } = useHighlight({
+		query,
+		name,
+		priority,
+		observe,
+		caseSensitive,
+		wholeWord
+	});
+	return createElement(as, {
+		ref,
+		...rest
+	}, children);
+}
+const HighlightRootContext = createContext(null);
+/** Scan container for one or more <Highlight.Match> children. */
+const HighlightRoot = forwardRef(function HighlightRoot({ name, as = "div", children, ...rest }, ref) {
+	const [container, setContainer] = useState(null);
+	useImperativeHandle(ref, () => container, [container]);
+	const ctx = useMemo(() => ({
+		name,
+		container
+	}), [name, container]);
+	return /* @__PURE__ */ jsx(HighlightRootContext.Provider, {
+		value: ctx,
+		children: createElement(as, {
+			ref: setContainer,
+			...rest
+		}, children)
+	});
+});
+/**
+* Effect-only: renders nothing, scans the enclosing Root's container and
+* registers the matches. Tracks DOM changes by default (`observe`).
+*
+* @throws When rendered outside `<Highlight.Root>`.
+*/
+function HighlightMatch({ pattern, name, priority = 0, ...matchOptions }) {
+	const ctx = useContext(HighlightRootContext);
+	if (!ctx) throw new Error("<Highlight.Match> must be used inside <Highlight.Root>");
+	const ranges = useTextMatches(ctx.container, pattern, matchOptions);
+	useHighlightRanges(name ?? ctx.name, ranges, priority);
+	return null;
+}
+/**
+* Renders a single wrapper element and highlights matches of `query` within it.
+*
+* Multiple <Highlight> sharing the same `name` are unioned by the core, so one
+* ::highlight(name) CSS rule styles them all.
+*
+* For several patterns over one container use the compound form:
+* `Highlight.Root` with nested `Highlight.Match` elements.
+*
+* @example Single pattern
+* ```tsx
+* import { Highlight } from '@cbcruk/highlight-kit/react'
+*
+* function Article({ keyword }: { keyword: string }) {
+*   return (
+*     <Highlight query={keyword} name="search" style={{ display: 'contents' }}>
+*       <article>...</article>
+*     </Highlight>
+*   )
+* }
+* ```
+*
+* @example Several patterns over one container
+* ```tsx
+* import { Highlight } from '@cbcruk/highlight-kit/react'
+*
+* function Logs({ logs }: { logs: string }) {
+*   return (
+*     <Highlight.Root name="log-info" as="pre">
+*       {logs}
+*       <Highlight.Match name="log-error" pattern={/ERROR:[^\n]+/} />
+*       <Highlight.Match pattern={/INFO:[^\n]+/} />
+*     </Highlight.Root>
+*   )
+* }
+* ```
+*/
+const Highlight = Object.assign(HighlightComponent, {
+	Root: HighlightRoot,
+	Match: HighlightMatch
+});
+const DEFAULT_SEARCH_STYLES = {
+	search: {
+		backgroundColor: "rgb(253 224 71)",
+		color: "rgb(113 63 18)"
+	},
+	"search-current": {
+		backgroundColor: "rgb(249 115 22)",
+		color: "white"
+	}
+};
+/**
+* Inline `<style>` with `::highlight()` rules. Defaults match the names used by
+* {@link useHighlightSearch}.
+*/
+function HighlightStyles({ styles = DEFAULT_SEARCH_STYLES }) {
+	return /* @__PURE__ */ jsx("style", { children: generateHighlightCSS(styles) });
+}
+//#endregion
+export { Highlight, HighlightMatch, HighlightProvider, HighlightRoot, HighlightStyles, highlights, useHighlight, useHighlightController, useHighlightRanges, useHighlightSearch, useHighlightSnapshots, useHighlightState, useHighlightSupport, useTextMatches };

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@cbcruk/highlight-kit",
+  "description": "CSS Custom Highlight API 기반 텍스트 하이라이트 core와 React 어댑터",
+  "version": "0.1.0",
+  "type": "module",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/cbcruk/eunsoolib.git",
+    "directory": "packages/highlight-kit"
+  },
+  "homepage": "https://cbcruk.github.io/eunsoolib/docs/dom/highlight-kit/",
+  "files": [
+    "dist"
+  ],
+  "exports": {
+    ".": "./dist/index.js",
+    "./react": "./dist/react.js",
+    "./package.json": "./package.json"
+  },
+  "peerDependencies": {
+    "react": ">=18.0.0"
+  },
+  "peerDependenciesMeta": {
+    "react": {
+      "optional": true
+    }
+  },
+  "eunsoolib": {
+    "category": "dom",
+    "runtime": [
+      "browser"
+    ]
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsdown --config ../../tsdown.config.ts"
+  }
+}