@ai-matrx/kit 0.5.0

package/dist/index.d.ts

@@ -0,0 +1,897 @@
+export { AutosaveStatus, UseAutosaveResult, useAutosave } from './autosave.js';
+export { BeginRequest, useLatestRequest } from './latest-request.js';
+export { ClipboardNotifyKind, UseClipboardOptions, UseClipboardResult, useClipboard } from './clipboard.js';
+export { DraftSource, LocalDraft, LocalDraftInput, captureDrafts, discardDraft, getDraft, getDraftsVersion, listDrafts, registerDraftSource, subscribeDrafts, useDurableDraft } from './drafts.js';
+export { ConfirmDialog, ConfirmDialogHost, ConfirmDialogProps, ConfirmOptions, confirm } from './confirm.js';
+export { CapturedToastInfo, CreateMatrxToastOptions, MatrxToast, SonnerLikeToast, ToastData, ToastMessage, createMatrxToast } from './toast.js';
+export { FlushState, IdlePriority, IdleRegistration, UnregisterFn, getSchedulerState, onFlushComplete, registerIdleTask, resetScheduler, useIdleGate, useIdleReady, useIdleRegister, useIdleTask, whenPageIdle } from './idle-scheduler.js';
+export { MirroredUrlStateOptions, SetUrlStateOptions, UrlHistoryMode, UrlStateCodec, UrlStateRouter, booleanUrlCodec, commitUrlParams, enumUrlCodec, historyModeForParamChange, jsonUrlCodec, positiveIntegerUrlCodec, setUrlStateRouter, stringUrlCodec, useMirroredUrlState, useUrlSearchParams, useUrlState } from './url-state.js';
+import { IDBPDatabase } from 'idb';
+import * as React from 'react';
+
+/**
+ * Relevance-weighted search scoring.
+ *
+ * Use instead of the naive `name.includes(q) || description.includes(q)` pattern
+ * so that title/name matches rank above description matches, and exact/prefix
+ * matches rank above partial ones.
+ *
+ * ── Quick start ────────────────────────────────────────────────────────────────
+ *   const filtered = filterAndSortBySearch(items, query, [
+ *     { get: (t) => t.name, weight: "title" },
+ *     { get: (t) => t.description, weight: "body" },
+ *     { get: (t) => t.tags, weight: "tag" },
+ *   ]);
+ *
+ * ── Weight tiers (higher = more important field) ──────────────────────────────
+ *   title    — the primary identifier (name, label, subject)
+ *   subtitle — secondary identifier (vendor, author, category name)
+ *   body     — long-form descriptive text (description, summary)
+ *   tag      — tag/category labels
+ *   meta     — weak metadata (modelId, type)
+ *   id       — raw identifiers (uuid, slug) — only useful for pasted-id lookups
+ *
+ * Within each field, an EXACT match > STARTS-WITH match > INCLUDES match.
+ * Fields declared first are a slight tiebreaker (via field-index bonus).
+ *
+ * ── Automatic id matching ─────────────────────────────────────────────────────
+ * Every item with a string `id` is ALSO matched against the query at the `id`
+ * weight tier, automatically — you do NOT need to declare an id field. This
+ * means a user can paste a full or partial UUID into ANY search box wired to
+ * this helper and find the record. It kicks in from {@link MIN_AUTO_ID_QUERY_LEN}
+ * characters up (so short queries don't match random hex). Declare an explicit
+ * `{ weight: "id" }` field only if you want id matching at any length / on a
+ * non-`id` property; doing so opts that callsite out of the automatic pass.
+ */
+type SearchFieldWeight = "title" | "subtitle" | "body" | "tag" | "meta" | "id" | "custom";
+interface SearchFieldConfig<T> {
+    /**
+     * Extracts the value(s) from the item. Return a string, an array of strings,
+     * or null/undefined. Arrays score based on the best-matching element.
+     */
+    get: (item: T) => string | string[] | null | undefined;
+    /** Field importance tier. Defaults to "body". */
+    weight?: SearchFieldWeight;
+    /** Optional override for custom tiers. Ignored when `weight` is preset. */
+    exact?: number;
+    startsWith?: number;
+    includes?: number;
+}
+/**
+ * Compute a weighted relevance score for `item` against `query`.
+ * Returns 0 if there is no match — callers can treat `> 0` as a match predicate.
+ *
+ * Within each field, multiple values (e.g. tags) contribute the BEST match,
+ * not the sum, so an item with many tags doesn't unfairly outrank one with a
+ * single exact title match.
+ */
+declare function computeSearchScore<T>(item: T, query: string, fields: SearchFieldConfig<T>[]): number;
+declare function matchesSearch<T>(item: T, query: string, fields: SearchFieldConfig<T>[]): boolean;
+/**
+ * Drop-in id-match for hand-rolled `.filter()` predicates that can't (yet) move
+ * onto {@link filterAndSortBySearch}. Returns true when `query` is a substring
+ * of the item's string `id`, applying the same {@link MIN_AUTO_ID_QUERY_LEN}
+ * guard as the automatic pass so short queries don't match random hex.
+ *
+ *   list.filter((x) => x.name.toLowerCase().includes(q) || idMatchesQuery(x, q))
+ *
+ * Prefer migrating the callsite to `filterAndSortBySearch` (which does this for
+ * free); reach for this only when an existing custom sort must be preserved.
+ */
+declare function idMatchesQuery(item: unknown, query: string): boolean;
+/**
+ * Filter out non-matches and sort remaining items by descending relevance.
+ * Stable with respect to the original order when two items tie.
+ */
+declare function filterAndSortBySearch<T>(items: readonly T[], query: string, fields: SearchFieldConfig<T>[]): T[];
+
+interface ConcurrencyFailure<T> {
+    item: T;
+    index: number;
+    error: unknown;
+}
+interface ConcurrencyResult<T> {
+    started: number;
+    succeeded: number;
+    failed: number;
+    failures: ConcurrencyFailure<T>[];
+}
+/**
+ * Runs independent items through a bounded worker pool. One item failing does
+ * not stop the rest, and `shouldStart` can stop new work without interrupting
+ * items already in flight.
+ */
+declare function runWithConcurrency<T>(items: readonly T[], limit: number, worker: (item: T, index: number) => Promise<void>, shouldStart?: () => boolean): Promise<ConcurrencyResult<T>>;
+
+/**
+ * Text formatting options
+ */
+type TextCaseOption = 'title' | 'sentence' | 'normal' | 'lower' | 'upper';
+interface TextFormatterOptions {
+    /**
+     * Text case to apply after normalization
+     * - title: First Letter Of Each Word Capitalized
+     * - sentence: First letter of first word capitalized
+     * - normal: No case transformation after normalization
+     * - lower: all text lowercase
+     * - upper: ALL TEXT UPPERCASE
+     */
+    textCase?: TextCaseOption;
+    /**
+     * Map of words to replace with specific formatting
+     * Example: { 'api': 'API', 'ui': 'UI' }
+     */
+    wordReplacements?: Record<string, string>;
+    /**
+     * Whether to trim the result
+     */
+    trim?: boolean;
+}
+/**
+ * Default word replacements for common acronyms and terms
+ */
+type ReplacementMap = Readonly<Record<string, string>>;
+declare const DEFAULT_WORD_REPLACEMENTS: ReplacementMap;
+/**
+ * Formats text by normalizing case styles, applying case transformations,
+ * and replacing specific words with custom formatting.
+ *
+ * @param text The input text to format
+ * @param options Formatting options
+ * @returns Formatted text
+ */
+declare function formatText(text: string, options?: TextFormatterOptions): string;
+/**
+ * Creates a pre-configured formatter function with specific options
+ *
+ * @param defaultOptions Default options for the formatter
+ * @returns A formatter function with the specified default options
+ */
+declare function createFormatter(defaultOptions?: TextFormatterOptions): (text: string, overrideOptions?: TextFormatterOptions) => string;
+declare const formatTitleCase: (text: string, overrideOptions?: TextFormatterOptions) => string;
+declare const formatSentenceCase: (text: string, overrideOptions?: TextFormatterOptions) => string;
+declare const formatNormalCase: (text: string, overrideOptions?: TextFormatterOptions) => string;
+declare const formatUpperCase: (text: string, overrideOptions?: TextFormatterOptions) => string;
+declare const formatLowerCase: (text: string, overrideOptions?: TextFormatterOptions) => string;
+declare const formatWithoutReplacements: (text: string, overrideOptions?: TextFormatterOptions) => string;
+
+/**
+ * @ai-matrx/kit/invalidation — a tiny name-keyed callback registry that lets a
+ * UBIQUITOUS module (a stream processor, an effect runner) trigger cache
+ * invalidation inside a HEAVY chunk cluster with ZERO import edge between them.
+ *
+ * WHY THIS EXISTS (the fragmentation-law incident): a module statically
+ * reachable from ~every route context reached a heavy registry cluster with an
+ * `await import()` — one line that added +14 GB peak build RSS / +50% compile
+ * time and OOM-killed 12 straight production builds. The sanctioned shape is
+ * the INVERSION implemented here: the heavy cluster registers a callback at
+ * its own module init (it is always initialized wherever its output can
+ * render — if the chunk never loaded, nothing stale is mounted), and the
+ * ubiquitous module fires the callback by NAME. The only shared code is this
+ * module, which imports nothing.
+ *
+ * RULES:
+ *  - This module must NEVER grow an import. It is in every chunk that touches
+ *    it; any dependency it gains is multiplied across all of them.
+ *  - Firing an unregistered name is a NO-OP by design, not an error — the
+ *    consumer chunk simply isn't loaded in this tab, so there is nothing
+ *    stale to invalidate.
+ *  - Callbacks never break the caller: each runs in its own try/catch and
+ *    screams to the console on failure.
+ *  - Key constants live in the HOST app (one shared constants module per app),
+ *    so producer and consumer agree on the name without importing each other.
+ *    The registry itself is generic over names — app-specific keys never move
+ *    into this package.
+ *
+ * Ported from matrx-frontend `lib/invalidation/invalidation-registry.ts`, with
+ * ONE structural inversion: the callback map lives on `globalThis` under a
+ * `Symbol.for` slot instead of a module-level variable. With the package built
+ * `splitting: false` in dual ESM/CJS format, this module is duplicated into
+ * the root bundle and the `./invalidation` bundle, and CJS/ESM each
+ * instantiate their own module graph — a module-level Map would silently split
+ * the producers from the consumers (the same hazard the confirm opener
+ * documents). Behavior is unchanged; never "clean this up" into a module
+ * local.
+ */
+type InvalidationCallback = (detail?: unknown) => void;
+/**
+ * Register a callback for a name. Idempotent-friendly: returns the
+ * unsubscribe. Module-scope registration in the consumer chunk is the
+ * intended pattern (register once per chunk load, never unsubscribe).
+ */
+declare function registerInvalidationCallback(name: string, callback: InvalidationCallback): () => void;
+/**
+ * Fire every callback registered under `name`. Returns true when at least one
+ * callback ran. Never throws — a failing callback screams and the rest run.
+ */
+declare function fireInvalidation(name: string, detail?: unknown): boolean;
+
+/**
+ * @ai-matrx/kit/delimiter-guard — stops ONE stray markdown delimiter from
+ * swallowing a whole section of a streamed answer.
+ *
+ * THE FAILURE CLASS
+ * -----------------
+ * Markdown delimiters pair greedily and blindly. A single stray opener emitted
+ * by a model (the common shape is a mangled citation:
+ * `…/a-quicker-way-to-heal-prp-and-prf$$ .`) pairs with the next matching
+ * delimiter anywhere later in the message, and everything in between —
+ * headings, bold, links, whole sections — collapses into one node.
+ *
+ * Two delimiters cause this in a remark-math + CommonMark pipeline:
+ *
+ * 1. `$$` (remark-math). The swallowed prose becomes a math node, KaTeX fails
+ *    to parse it, and `rehype-katex` falls back to its built-in error
+ *    rendering: the raw source re-emitted inside `<span class="katex-error"
+ *    style="color:#cc0000">`. The symptom is a huge block of BRIGHT RED
+ *    unrendered markdown mid-answer. That red is KaTeX reporting a parse error
+ *    on text that was never math — not a style of yours.
+ * 2. `[` (CommonMark link label). The swallowed prose becomes the label of one
+ *    enormous hyperlink — the same bug wearing blue instead of red.
+ *
+ * WHAT THIS DOES
+ * --------------
+ * Before the markdown pipeline runs, each candidate span is checked for
+ * plausibility. A `$$…$$` span carrying markdown structure (links, URLs, bold,
+ * headings, list markers) or reading as prose is not math; a link label that is
+ * hundreds of characters long or contains block structure is not a label. The
+ * offending OPENER is neutralized (`&#36;&#36;`, `&#91;`) and scanning resumes at the next
+ * delimiter, so genuine math and genuine links later in the same message still
+ * render. Real content is never touched.
+ *
+ * LOUD RECOVERY: every firing is a real upstream defect (a model emitting
+ * malformed delimiters, or a producer mangling a citation). Callers report the
+ * returned violations — see `reportDelimiterViolations`.
+ *
+ * Ported verbatim from matrx-frontend `lib/markdown/delimiter-guard.ts`, with
+ * ONE coupling inversion: the app's `captureError` store import became the
+ * injected `capture` sink on `reportDelimiterViolations`' context (payload
+ * shape preserved exactly). No sink means console-only loud recovery.
+ */
+type DelimiterViolationReason = 
+/** A `$$…$$` pair whose contents are prose/markdown, not math. */
+"prose-span"
+/** A `$$` with no closing partner in the content. */
+ | "unpaired"
+/** A `[…](…)` link whose label swallowed prose/structure. */
+ | "runaway-link";
+interface DelimiterViolation {
+    reason: DelimiterViolationReason;
+    /** Character offset of the offending delimiter in the input string. */
+    index: number;
+    /** Length of the span between the delimiters (0 for `unpaired`). */
+    spanLength: number;
+    /** Short excerpt of what would have been swallowed. */
+    preview: string;
+}
+interface DelimiterGuardResult {
+    /** Input with runaway openers escaped. */
+    text: string;
+    violations: DelimiterViolation[];
+}
+/**
+ * Escapes `$$` delimiters that would make remark-math swallow non-math text.
+ * Pure — safe to call on every render / stream chunk.
+ */
+declare function guardMathDelimiters(text: string): DelimiterGuardResult;
+/**
+ * Escapes the `[` of a markdown link whose label ran away — the link twin of
+ * the stray-`$$` bug. An unclosed citation bracket pairs with a `]` hundreds of
+ * characters later and turns an entire section into one hyperlink.
+ *
+ * Pure. Runs after the math guard so both share one escaping pass conceptually,
+ * but each is independently usable.
+ */
+declare function guardRunawayLinks(text: string): DelimiterGuardResult;
+/**
+ * The front door: run every delimiter guard in order. Offsets in the returned
+ * violations refer to each guard's own input, so they are for diagnostics only.
+ */
+declare function guardMarkdownDelimiters(text: string): DelimiterGuardResult;
+/**
+ * The payload handed to the injected capture sink — exactly the shape the
+ * original passed to the Matrx `captureError` store. A Matrx host passes
+ * `captureError` straight through; any host can log/report it its own way.
+ */
+interface DelimiterCaptureInput {
+    source: "markdown-delimiters";
+    message: string;
+    relation: string;
+    details: string;
+    conversationId?: string | undefined;
+    callSite: "guardMarkdownDelimiters";
+    raw: {
+        messageId?: string | undefined;
+        violations: DelimiterViolation[];
+    };
+}
+interface DelimiterReportContext {
+    renderPath: string;
+    messageId?: string | undefined;
+    conversationId?: string | undefined;
+    /**
+     * Optional error-capture sink (a Matrx host passes its `captureError`).
+     * Absent, the loud recovery is console-only. Must never be relied on to
+     * throw — failures inside it are swallowed so capture can never break
+     * rendering.
+     */
+    capture?: ((input: DelimiterCaptureInput) => void) | undefined;
+}
+/**
+ * Loud recovery. A firing means malformed math delimiters reached the renderer
+ * — the guard kept the message readable, but the producer is still emitting
+ * broken content and must be found.
+ */
+declare function reportDelimiterViolations(violations: DelimiterViolation[], context: DelimiterReportContext): void;
+
+/**
+ * Canonical JSON value types + narrowing guards.
+ *
+ * Ported (the subset this subpath needs) from matrx-frontend `types/json.ts` —
+ * the honest names for "this is just JSON" that are NOT `any` and NOT a bare
+ * `unknown`. The package must stand alone, so the types live here; a Matrx
+ * host keeps using its own `@/types/json` for app code and the two are
+ * structurally identical.
+ */
+type JsonPrimitive = string | number | boolean | null;
+/**
+ * A JSON object. Values are `JsonValue | undefined` so optional keys read
+ * cleanly (mirrors Supabase's original generated `Json` object member).
+ */
+interface JsonObject {
+    [key: string]: JsonValue | undefined;
+}
+type JsonArray = JsonValue[];
+type JsonValue = JsonPrimitive | JsonObject | JsonArray;
+/**
+ * Narrow an `unknown` (e.g. a bare JSONB column) to a `JsonObject`.
+ * Plain object only — arrays and `null` return false.
+ */
+declare function isJsonObject(value: unknown): value is JsonObject;
+/** Narrow an `unknown` to a `JsonArray`. */
+declare function isJsonArray(value: unknown): value is JsonArray;
+/** Narrow an `unknown` to a JSON primitive (string | number | boolean | null). */
+declare function isJsonPrimitive(value: unknown): value is JsonPrimitive;
+
+/**
+ * How the JSON is laid out.
+ *
+ * - `minify`  — one line, zero optional whitespace. The smallest legal form.
+ * - `compact` — width-aware: any subtree that fits within `width` is inlined,
+ *               and sibling entries that fit are packed onto shared lines.
+ *               Readable AND small; this is the "scrunch it down" default.
+ * - `pretty`  — classic one-entry-per-line indentation.
+ */
+type JsonFormatStyle = "minify" | "compact" | "pretty";
+/** What to do with the markdown code fence around the JSON. */
+type JsonFenceMode = 
+/** Keep the fence exactly as it arrived (and add none if there was none). */
+"preserve"
+/** Remove the fence, leaving bare JSON. */
+ | "strip"
+/** Ensure a ```json fence, adding one if the source was bare. */
+ | "add";
+/** A markdown code fence wrapping the JSON payload. */
+interface JsonFence {
+    /** The opening marker as written, e.g. "```" or "~~~~". */
+    marker: string;
+    /** Info string after the marker, e.g. "json" (empty when the fence was bare). */
+    lang: string;
+    /** Whitespace the opening fence line was indented by. */
+    indent: string;
+    /** False when the source ran out before a closing fence (unterminated). */
+    closed: boolean;
+}
+/** Which JSON container sits at the root of the payload. */
+type JsonRootKind = "object" | "array" | "scalar";
+/** How permissively the payload had to be parsed. */
+type JsonParser = 
+/** Valid JSON — `JSON.parse` accepted it verbatim. */
+"strict"
+/** Only JSON5 accepted it: trailing commas, comments, unquoted keys, … */
+ | "tolerant";
+interface JsonDetection {
+    /** The payload parsed (strictly or tolerantly) into a value. */
+    ok: boolean;
+    /**
+     * The text is JSON-SHAPED even if it did not parse — it opens with `{`/`[`
+     * and closes with the matching bracket, or it arrived in a ```json fence.
+     * This is the gate for OFFERING json actions; `ok` is the gate for running
+     * them.
+     */
+    looksLikeJson: boolean;
+    /** The parsed value. Present only when `ok`. */
+    value?: JsonValue | undefined;
+    parser?: JsonParser | undefined;
+    /** Human-readable parse failure. Present only when `!ok`. */
+    error?: string | undefined;
+    /** The fence that was stripped before parsing, when the source had one. */
+    fence: JsonFence | null;
+    /** Text before the payload (fence excluded) — preserved verbatim on format. */
+    leading: string;
+    /** Text after the payload (fence excluded) — preserved verbatim on format. */
+    trailing: string;
+    /** The JSON text itself: fence and surrounding whitespace removed. */
+    payload: string;
+    root?: JsonRootKind | undefined;
+    /** Lines the payload currently occupies. */
+    lineCount: number;
+    /** Characters the payload currently occupies. */
+    charCount: number;
+}
+interface JsonFormatOptions {
+    style: JsonFormatStyle;
+    /** Spaces per indent level for `compact` / `pretty`. Default 2. */
+    indent?: number | undefined;
+    /** Target line width for `compact`. Default 100. Ignored otherwise. */
+    width?: number | undefined;
+    /** Sort object keys alphabetically at every depth. Default false. */
+    sortKeys?: boolean | undefined;
+    /** Fence handling. Default "preserve". */
+    fence?: JsonFenceMode | undefined;
+}
+/** Size of a chunk of text, for before/after reporting. */
+interface JsonTextSize {
+    lines: number;
+    chars: number;
+}
+interface JsonFormatResult {
+    /** False when the text could not be parsed; `text` is then the input, unchanged. */
+    ok: boolean;
+    /** The re-formatted text (full input: leading + fence + payload + trailing). */
+    text: string;
+    error?: string | undefined;
+    /** True when `text` differs from the input. */
+    changed: boolean;
+    detection: JsonDetection;
+    before: JsonTextSize;
+    after: JsonTextSize;
+}
+
+/**
+ * Detect JSON in `text`. Never throws; a non-JSON string comes back with
+ * `ok: false` and `looksLikeJson: false`, which is the signal to offer nothing.
+ */
+declare function detectJson(text: string): JsonDetection;
+
+declare const DEFAULT_JSON_INDENT = 2;
+declare const DEFAULT_JSON_WIDTH = 100;
+/**
+ * Serialize a JSON value in one of the three styles. This is the entry point
+ * for callers that already HAVE a value (a DB JSONB blob, an API frame) and
+ * just want it laid out; text callers want {@link formatJsonText}.
+ */
+declare function stringifyJson(value: JsonValue, options: JsonFormatOptions): string;
+/**
+ * Format the JSON found in `text`, preserving everything around it.
+ *
+ * Never throws. When the text does not parse, the result is `ok: false`,
+ * `changed: false`, and `text` is the input verbatim — a formatter that
+ * mangles text it did not understand is a data-loss bug.
+ */
+declare function formatJsonText(text: string, options: JsonFormatOptions): JsonFormatResult;
+
+/**
+ * @ai-matrx/kit/idb-store — base manager.
+ *
+ * Ported verbatim from matrx-frontend `lib/idb/store-manager.ts`, with ONE
+ * structural inversion: the original documented a `protected static _instance`
+ * convention (each subclass held its singleton on its own static field).
+ * A class-static is module state — with this package built `splitting: false`
+ * in dual ESM/CJS format the class is duplicated into the root bundle and the
+ * `./idb-store` bundle, and CJS/ESM each instantiate their own module graph,
+ * so a static field would silently split "the" singleton into up to four
+ * instances racing the same IndexedDB database. The singleton slot therefore
+ * lives on `globalThis` under `Symbol.for("ai-matrx.kit.idb-store-state")`
+ * instead — see `singleton.ts` (`getIdbStoreSingleton`). Never "clean this
+ * up" back into a static field.
+ */
+
+type AsyncResult<T> = Promise<{
+    data: T | null;
+    error: Error | null;
+}>;
+declare abstract class DBStoreManager<T> {
+    protected db: IDBPDatabase | null;
+    protected dbName: string;
+    protected version: number;
+    protected constructor(dbName: string, version: number);
+    protected abstract setupStores(db: IDBPDatabase): void;
+    protected initDB(): Promise<void>;
+    protected add<TRecord = T>(storeName: string, data: TRecord): AsyncResult<string>;
+    protected get<TRecord = T>(storeName: string, id: string): AsyncResult<TRecord>;
+    protected getAll(storeName: string): AsyncResult<T[]>;
+    protected update<U extends object>(storeName: string, id: number, data: Partial<U>): AsyncResult<boolean>;
+    protected delete(storeName: string, id: number): AsyncResult<boolean>;
+    protected query<U>(storeName: string, indexName: string, query: IDBValidKey | IDBKeyRange): AsyncResult<U[]>;
+}
+
+/**
+ * Public CRUD surface over `DBStoreManager` — ported verbatim from
+ * matrx-frontend `lib/idb/store-interface.ts`. The base keeps its operations
+ * `protected` so feature stores expose intent-named methods; this subclass is
+ * the escape hatch for hosts that want the raw generic surface (e.g. a
+ * `useIDB(store)` hook driving arbitrary stores).
+ *
+ * NOTE (original API shape, kept verbatim): `getItem` takes a string id while
+ * `updateItem`/`deleteItem` take a number id. With an `autoIncrement` key path
+ * the generated keys are numbers, so reads use `String(id)` only against
+ * string-keyed stores — this asymmetry is the original public contract.
+ */
+
+declare abstract class PublicStoreManager<T> extends DBStoreManager<T> {
+    constructor(dbName: string, version: number);
+    addItem(storeName: string, data: T): AsyncResult<string>;
+    getItem(storeName: string, id: string): AsyncResult<T>;
+    getAllItems(storeName: string): AsyncResult<T[]>;
+    updateItem<U extends object>(storeName: string, id: number, data: Partial<U>): AsyncResult<boolean>;
+    deleteItem(storeName: string, id: number): AsyncResult<boolean>;
+    queryItems<U>(storeName: string, indexName: string, query: IDBValidKey | IDBKeyRange): AsyncResult<U[]>;
+}
+
+/**
+ * Convenience base for a store class bound to one named object store —
+ * ported from matrx-frontend `lib/idb/feature-store.ts`.
+ *
+ * DEFECT FIX vs the original: the constructor kicks off `initDB()` without
+ * awaiting it (by design — construction stays synchronous and operations
+ * before init resolve `{ error: "Database not initialized" }`), but the
+ * original left that floating promise unhandled, so a failed `openDB` (e.g.
+ * private-mode storage denial) surfaced as an unhandled promise rejection on
+ * top of the `initDB` console.error. The rejection is now absorbed here —
+ * `initDB` has already screamed, and every operation still reports the
+ * uninitialized state through its `AsyncResult` error.
+ */
+
+declare abstract class FeatureStore<T> extends PublicStoreManager<T> {
+    protected storeName: string;
+    protected constructor(dbName: string, version: number, storeName: string);
+    protected abstract setupStores(db: IDBPDatabase): void;
+    getStoreName(): string;
+}
+
+/**
+ * The one place a store singleton may live.
+ *
+ * The original host pattern held each store's singleton on a
+ * `protected static _instance` field of the store class. In this package that
+ * is a hazard, not a convenience: built `splitting: false` in dual ESM/CJS
+ * format, the class body is duplicated into the root bundle and the
+ * `./idb-store` bundle, and the ESM and CJS graphs each instantiate their own
+ * copy — a class-static would silently split "the" singleton into several
+ * instances, each opening its own connection (and racing upgrades) against
+ * the same IndexedDB database. So per-store instances live on `globalThis`
+ * under `Symbol.for("ai-matrx.kit.idb-store-state")`, keyed by a
+ * caller-chosen name. Never "clean this up" into module or class state.
+ *
+ * Host usage (replaces the old static `getInstance` body):
+ *
+ *   class AudioStore extends DBStoreManager<Recording> { ... }
+ *   export const audioStore = getIdbStoreSingleton("voiceNotesDB/audio", () => new AudioStore());
+ */
+/**
+ * Returns the one instance registered under `key`, creating it via `create`
+ * on first call. The key should uniquely name the store (a good convention is
+ * `"<dbName>/<storeName>"`) — two different classes registering the same key
+ * is a caller bug and gets whichever registered first.
+ */
+declare function getIdbStoreSingleton<T>(key: string, create: () => T): T;
+/** @internal Test-only: drop every registered store instance. */
+declare function _resetIdbStoreSingletons(): void;
+
+/**
+ * The bidirectional Tailwind-token mapping — the heart of the S14 unit,
+ * ported from matrx-frontend `utils/color-utils/color-change-util.ts` /
+ * `tailwind-color-util.ts`.
+ *
+ * token → hex: `getColorFromTailwind("slate-500")` → `"#64748b"` (plus the
+ * fuzzy `formatTailwindColor` for messy user input like `"skyblue598"`).
+ * color → token: `findNearestTailwindColor` — the verbatim nearest-match
+ * scan. The original took a colord instance; the colord coupling is inverted
+ * structurally: pass any object with `.delta(hex) => number` (every colord
+ * instance with the lab plugin qualifies — no import, no peer), or pass a
+ * plain hex / `rgb()` string and the built-in colord-identical CIEDE2000
+ * engine (`lab-delta.ts`) computes the distances with zero dependencies.
+ */
+/**
+ * Anything that can measure its perceptual distance to a hex color —
+ * structurally satisfied by a colord instance extended with the lab plugin.
+ */
+interface ColorDelta {
+    delta(color: string): number;
+}
+/**
+ * Function to find the hex value for a given Tailwind color string.
+ * @param tailwindColorString - The Tailwind color string (e.g., 'slate-500').
+ * @returns The hex value of the corresponding color (e.g., '#64748b'), or an empty string if not found.
+ */
+declare function getColorFromTailwind(tailwindColorString: string): string;
+/**
+ * Function to find the nearest Tailwind color for a given input color.
+ * @param inputColor - The input color: a hex or `rgb()` string, or any
+ *   `{ delta(hex) }` measurer (e.g. a colord instance with the lab plugin).
+ * @returns The nearest Tailwind color string (e.g., 'slate-500'), or an
+ *   empty string when a string input cannot be parsed.
+ */
+declare function findNearestTailwindColor(inputColor: string | ColorDelta): string;
+/**
+ * Utility to format a Tailwind color string.
+ * Matches Tailwind color names and returns the closest Tailwind value.
+ * Handles cases like "skyblue600", "sky598", or "sky-600".
+ * @param tailwindColor - The user-provided Tailwind color string.
+ * @returns A properly formatted Tailwind color string.
+ */
+declare function formatTailwindColor(tailwindColor: string): string;
+
+/**
+ * The Tailwind CSS default palette lookup table — ported verbatim from
+ * matrx-frontend `constants/tailwind-colors.ts` (the data the S14
+ * "tailwind-color-util" unit does its lookups against). 22 color groups,
+ * shades 50–950.
+ */
+interface TailwindColorGroup {
+    name: string;
+    shades: Record<string, string>;
+}
+declare const tailwindColors: readonly TailwindColorGroup[];
+
+/**
+ * The pure input normalizers — ported verbatim from matrx-frontend
+ * `utils/color-utils/color-change-util.ts`. Each takes the messy shape a
+ * human pastes ("61, 135, 204", "r:61,g:135,b:204", "94% 29% 0% 9%",
+ * "0x3d87cc"…) and returns the canonical string for that format, or `''`
+ * when the input does not fit — string in, string out, zero dependencies.
+ *
+ * ONE deliberate divergence from the original: `formatLabString` /
+ * `formatLchString` logged every call (input, match, miss) with
+ * unconditional `console.log`s — debug spam on a parse path, removed here.
+ * Matching/return behavior is unchanged.
+ */
+/**
+ * Utility to format a hex string.
+ * Adds the # prefix if missing.
+ * @param hex - The user-provided hex color.
+ * @returns A properly formatted hex color string.
+ */
+declare function formatHex(hex: string): string;
+/**
+ * Utility to format an rgb string.
+ * Accepts various formats like "61, 135, 204" or "(61, 135, 204)".
+ * @param rgb - The user-provided rgb color.
+ * @returns A properly formatted rgb color string.
+ */
+declare function formatRgbString(rgb: string): string;
+/**
+ * Utility to format an RGB object.
+ * Accepts various object-like formats such as '{"r":61,"g":135,"b":204,"a":1}', '"r":61,"g":135,"b":204,"a":1', or 'r:61,g:135,b:204,a:1'.
+ * @param rgbObject - The user-provided RGB object-like string.
+ * @returns A properly formatted RGB object.
+ */
+declare function formatRgbObject(rgbObject: string): string;
+/**
+ * Utility to format an HSL object.
+ * Accepts various object-like formats such as '{"h":199,"s":89,"l":48,"a":1}' or 'h:199,s:89,l:48,a:1'.
+ * @param hslObject - The user-provided HSL object-like string.
+ * @returns A properly formatted HSL object.
+ */
+declare function formatHslObject(hslObject: string): string;
+/**
+ * Utility to format an HSL string.
+ * Accepts formats like "hsl(199, 89%, 48%)" or "199, 89%, 48%".
+ * @param hslString - The user-provided HSL string.
+ * @returns A properly formatted HSL string.
+ */
+declare function formatHslString(hslString: string): string;
+/**
+ * Utility to format an HSV percentage string.
+ * Accepts formats like "94% 29% 0%" or "(94% 29% 0%)".
+ * @param hsvString - The user-provided HSV percentage string.
+ * @returns A properly formatted HSV string.
+ */
+declare function formatHsvString(hsvString: string): string;
+/**
+ * Utility to format a regular CMYK string.
+ * Accepts formats like "94, 29, 0, 9" or "(94, 29, 0, 9)".
+ * @param cmykString - The user-provided CMYK string.
+ * @returns A properly formatted CMYK string.
+ */
+declare function formatRegularCmykString(cmykString: string): string;
+/**
+ * Utility to format a CMYK object.
+ * Accepts various object-like formats such as '{"c":94,"m":29,"y":0,"k":9,"a":1}' or 'c:94,m:29,y:0,k:9,a:1'.
+ * @param cmykObject - The user-provided CMYK object-like string.
+ * @returns A properly formatted CMYK object.
+ */
+declare function formatCmykObject(cmykObject: string): string;
+/**
+ * Utility to format a CMYK percentage string.
+ * Accepts formats like "94% 29% 0% 9%" or "(94% 29% 0% 9%)".
+ * @param cmykString - The user-provided CMYK percentage string.
+ * @returns A properly formatted CMYK string.
+ */
+declare function formatCmykString(cmykString: string): string;
+/**
+ * Utility to detect device-cmyk color strings ("device-cmyk(94% 29% 0% 9%)").
+ * @param cmykString - The user-provided CMYK string.
+ * @returns True when the string is a well-formed device-cmyk expression.
+ */
+declare function isDeviceCmyk(cmykString: string): boolean;
+/**
+ * Utility to format an HWB string.
+ * Accepts formats like "hwb(199 24% 20%)" or "hwb(199deg 24% 20%)".
+ * @param hwbString - The user-provided HWB string.
+ * @returns A properly formatted HWB string.
+ */
+declare function formatHwbString(hwbString: string): string;
+/**
+ * Utility to format a Lab string.
+ * Accepts formats like "lab(55.715 -14.02 -32.329)" or "55.715 -14.02 -32.329".
+ * @param labString - The user-provided Lab string.
+ * @returns A properly formatted Lab string.
+ */
+declare function formatLabString(labString: string): string;
+/**
+ * Utility to format an LCH string.
+ * Accepts formats like "lch(55.715 35.17 246.6)" or "55.715 35.17 246.6".
+ * @param lchString - The user-provided LCH string.
+ * @returns A properly formatted LCH string.
+ */
+declare function formatLchString(lchString: string): string;
+/**
+ * Utility to format a hex string with 0x prefix.
+ * Converts "0x3d87cc" to "#3d87cc".
+ * @param hex - The user-provided hex color with 0x prefix.
+ * @returns A properly formatted hex color string.
+ */
+declare function formatHexWith0x(hex: string): string;
+
+/**
+ * The "accept anything a human pastes" waterfall — ported from matrx-frontend
+ * `color-change-util.ts` `normalizeColorInput`, with the colord coupling
+ * inverted: the original gated several tiers on `colord(input).isValid()`;
+ * here the host injects that validity check (`createColorNormalizer({
+ * isValid })` — pass `(c) => colord(c).isValid()` or any equivalent). The
+ * tier ORDER, the tiers that skip validation, and the returned
+ * `{ value, type }` shapes are verbatim.
+ *
+ * Deliberate divergence (same class as formats.ts): the original logged every
+ * tier hit/miss with unconditional `console.log`s — removed.
+ */
+interface NormalizedColor {
+    value: string;
+    type: string;
+}
+interface ColorNormalizerOptions {
+    /**
+     * "Can this string be parsed as a color?" — the host's color engine
+     * (e.g. `(c) => colord(c).isValid()`).
+     */
+    isValid: (color: string) => boolean;
+}
+/**
+ * Builds `normalizeColorInput`: tries the format conversions in the original
+ * fixed order until one produces a valid (or structurally well-formed) color,
+ * returning `{ value, type }`, or `null` when nothing fits.
+ */
+declare function createColorNormalizer({ isValid }: ColorNormalizerOptions): (colorInput: string) => NormalizedColor | null;
+
+/**
+ * The zero-dependency perceptual-distance engine behind the string input path
+ * of `findNearestTailwindColor`.
+ *
+ * The matrx-frontend original computed distance through colord's lab plugin
+ * (`colordInstance.delta(hex)`). This module reproduces that plugin's exact
+ * pipeline — sRGB → XYZ(D65) → chromatic adaptation to D50 (colord's
+ * matrices, including its channel clamps) → CIE L*a*b* rounded to 2 decimals
+ * → CIEDE2000 (colord >= 2.10 formulation) ÷ 100, rounded to 3 decimals and
+ * clamped to [0, 1] — so the nearest-token answer is bit-identical to the
+ * colord path. The test suite cross-checks this against colord itself (a
+ * devDependency only).
+ */
+interface Rgb {
+    r: number;
+    g: number;
+    b: number;
+}
+interface Lab {
+    l: number;
+    a: number;
+    b: number;
+}
+/** RGB → CIE L*a*b*, rounded to 2 decimals exactly like colord's `toLab`. */
+declare function rgbToLab(rgb: Rgb): Lab;
+/**
+ * Perceptual distance between two RGB colors, normalized exactly like
+ * colord's `.delta()`: CIEDE2000 / 100, rounded to 3 decimals, clamped [0,1].
+ */
+declare function rgbDelta(rgb1: Rgb, rgb2: Rgb): number;
+/**
+ * Parses the two input shapes this unit is chartered for — hex (`#rgb`,
+ * `#rrggbb`, with or without `#`, alpha digits tolerated and ignored) and
+ * `rgb()`/`rgba()` strings — into RGB channels. Returns `null` for anything
+ * else; this is deliberately NOT a general CSS color parser.
+ */
+declare function parseHexOrRgb(input: string): Rgb | null;
+
+/**
+ * @ai-matrx/kit/react-tree — safe React children-tree scanning.
+ *
+ * Ported from matrx-frontend `lib/react/treeContainsComponent.ts`; this
+ * subpath is the ONE home of the scanner inside the kit (the `/confirm`
+ * subpath's alert-dialog imports it from here — no duplicate bodies).
+ *
+ * Two deliberate divergences from the frontend original, both documented:
+ * - the dev-mode scream checks `typeof process` first, since this package may
+ *   load in an unbundled browser context where `process` is undefined;
+ * - a React PORTAL child (`createPortal(...)` passed as a child) is a valid
+ *   React child, but it is not an element, an iterable, or a primitive — the
+ *   original fell through to the non-renderable branch, screamed a false
+ *   positive in dev, and skipped the portal's content. Portals are now
+ *   recognized and their children traversed.
+ */
+
+/**
+ * Returns true if `Component` appears anywhere in the React element tree under
+ * `node`. Used to detect optional a11y children (e.g. DialogDescription)
+ * without rendering duplicates.
+ *
+ * DEFENSIVE + LOUD. A non-renderable node — a plain object or function passed
+ * as a React child — is a real bug: React throws "Objects are not valid as a
+ * React child" the instant it renders one. This a11y probe must NOT be the
+ * crash site. `React.Children.toArray` would throw HERE, producing a trace that
+ * points at the dialog primitive instead of the component that leaked the
+ * object (this misdirection has burned real debugging hours). So we walk the
+ * tree by hand, SKIP any non-renderable node, and scream in dev with its keys —
+ * then let React report the defect at the true render site with the offending
+ * component in the stack. For every VALID tree the result is identical to the
+ * old `React.Children.toArray(node).some(...)`.
+ */
+declare function treeContainsComponent(node: React.ReactNode, Component: React.ElementType): boolean;
+
+/**
+ * @ai-matrx/kit/qr — THE QR-code decoder (client-side, in memory). Ported
+ * verbatim from matrx-frontend `lib/qr/decode.ts`.
+ *
+ * One primitive, three inputs (a File/Blob, an `ImageData` frame, a
+ * `<video>`/`<canvas>` element), one answer: the text the QR encodes, or
+ * `null` when no code is present. Nothing here uploads, stores, or persists
+ * anything — the bytes live in a canvas for the length of one call.
+ *
+ * Engine order:
+ *   1. `BarcodeDetector` — native, fast, handles rotation and poor contrast.
+ *   2. `jsqr` — pure-JS fallback (lazily imported, so it only enters the
+ *      bundle of a surface that actually decodes), for Safari/Firefox where
+ *      the native detector does not exist.
+ *
+ * Runtime dependency of this subpath (and only when the fallback fires):
+ * `jsqr` — a browser without `BarcodeDetector` decoding a pasted screenshot
+ * IS the capability, not an optional extra; without the fallback the unit
+ * silently does nothing on Safari/Firefox.
+ *
+ * Browser capability: decoding needs a DOM (`document`, canvas 2D,
+ * `createImageBitmap`) at call time; importing is inert and SSR-safe, and
+ * `hasNativeQrDetector()` is safe to call anywhere (it only probes
+ * `globalThis`).
+ *
+ * 🚨 Reach for THIS, never a second decoder. If a surface needs a new input
+ * shape, add an adapter here.
+ */
+/** True when the browser can decode without downloading the JS fallback. */
+declare function hasNativeQrDetector(): boolean;
+/** Decode a QR code out of an already-rasterised frame. */
+declare function decodeQrFromImageData(frame: ImageData): Promise<string | null>;
+/**
+ * Decode a QR code out of a live `<video>` (a camera preview) or a `<canvas>`.
+ * Returns `null` when the current frame holds no code — call it on a tick.
+ */
+declare function decodeQrFromElement(element: HTMLVideoElement | HTMLCanvasElement): Promise<string | null>;
+/**
+ * Decode a QR code out of an image File/Blob — a pasted screenshot, a dropped
+ * PNG, a photo from the OS camera sheet.
+ *
+ * Resolves `null` when the image holds no QR code. Throws only when the file
+ * is not decodable as an image at all.
+ */
+declare function decodeQrFromImageFile(file: Blob): Promise<string | null>;
+
+export { type AsyncResult, type ColorDelta, type ColorNormalizerOptions, type ConcurrencyFailure, type ConcurrencyResult, DBStoreManager, DEFAULT_JSON_INDENT, DEFAULT_JSON_WIDTH, DEFAULT_WORD_REPLACEMENTS, type DelimiterCaptureInput, type DelimiterGuardResult, type DelimiterReportContext, type DelimiterViolation, type DelimiterViolationReason, FeatureStore, type InvalidationCallback, type JsonArray, type JsonDetection, type JsonFence, type JsonFenceMode, type JsonFormatOptions, type JsonFormatResult, type JsonFormatStyle, type JsonObject, type JsonParser, type JsonPrimitive, type JsonRootKind, type JsonTextSize, type JsonValue, type NormalizedColor, PublicStoreManager, type ReplacementMap, type Rgb, type SearchFieldConfig, type SearchFieldWeight, type TailwindColorGroup, type TextCaseOption, type TextFormatterOptions, _resetIdbStoreSingletons, computeSearchScore, createColorNormalizer, createFormatter, decodeQrFromElement, decodeQrFromImageData, decodeQrFromImageFile, detectJson, filterAndSortBySearch, findNearestTailwindColor, fireInvalidation, formatCmykObject, formatCmykString, formatHex, formatHexWith0x, formatHslObject, formatHslString, formatHsvString, formatHwbString, formatJsonText, formatLabString, formatLchString, formatLowerCase, formatNormalCase, formatRegularCmykString, formatRgbObject, formatRgbString, formatSentenceCase, formatTailwindColor, formatText, formatTitleCase, formatUpperCase, formatWithoutReplacements, getColorFromTailwind, getIdbStoreSingleton, guardMarkdownDelimiters, guardMathDelimiters, guardRunawayLinks, hasNativeQrDetector, idMatchesQuery, isDeviceCmyk, isJsonArray, isJsonObject, isJsonPrimitive, matchesSearch, parseHexOrRgb, registerInvalidationCallback, reportDelimiterViolations, rgbDelta, rgbToLab, runWithConcurrency, stringifyJson, tailwindColors, treeContainsComponent };