@coldsmirk/abacus-core 0.3.1 → 0.4.1

package/README.md

@@ -423,4 +423,4 @@ class ExpressionNotReadyError extends ExpressionError {  // a *Sync helper calle
 
 ## License
 
-Apache-2.0
+UNLICENSED — proprietary. All rights reserved; no use, copying, or redistribution without the author's permission.

package/dist/index.cjs

@@ -1,10 +1,5 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 //#region src/engine/errors.ts
-/**
-* Error raised when the ZEN engine fails to load or an expression cannot be
-* evaluated. The original failure is preserved on {@link cause} and the
-* offending expression (if any) on {@link expression}.
-*/
 var ExpressionError = class extends Error {
 	expression;
 	constructor(message, expression, cause) {
@@ -13,11 +8,6 @@ var ExpressionError = class extends Error {
 		this.expression = expression;
 	}
 };
-/**
-* Raised by the synchronous evaluation helpers when the engine has not finished
-* initializing yet. Await {@link loadEngine} (or render under
-* `<ExpressionEngineProvider>`) before evaluating synchronously.
-*/
 var ExpressionNotReadyError = class extends ExpressionError {
 	constructor(message = "Expression engine is not initialized. Await loadEngine() or render under <ExpressionEngineProvider>.") {
 		super(message);
@@ -26,11 +16,6 @@ var ExpressionNotReadyError = class extends ExpressionError {
 };
 //#endregion
 //#region src/internal/predicates.ts
-/**
-* Minimal internal type predicates. Inlined so the engine stays dependency-free
-* (no shared-utility package), keeping `@coldsmirk/abacus-core` framework- and
-* ecosystem-agnostic.
-*/
 function isUndefined(value) {
 	return value === void 0;
 }
@@ -65,32 +50,10 @@ function loadFailureMessage() {
 	if (typeof window === "undefined") return `${base}. In a non-browser or non-DOM host (Node, SSR, Web Worker) the wasm cannot be auto-resolved; call configureEngine({ wasmInput }) with the wasm bytes or URL before loading.`;
 	return base;
 }
-/**
-* Configure how the wasm binary is located, before the engine loads. Must be
-* called before the first {@link loadEngine} (or any evaluation), so that the
-* configured input is the one actually used — calling it after the engine has
-* started loading throws, rather than silently taking no effect.
-*/
 function configureEngine(options) {
 	if (enginePromise || engineSync) throw new ExpressionError("configureEngine() must be called before the engine loads.");
 	configuredInput = options.wasmInput;
 }
-/**
-* Load and initialize the ZEN expression engine exactly once. Concurrent and
-* subsequent calls share the same in-flight promise / resolved instance. Set a
-* custom wasm source up front with {@link configureEngine}.
-*
-* The GoRules wasm dependency is reached via a dynamic `import()` on purpose: it
-* keeps this module usable from the package's CommonJS build (the dep is
-* ESM-only, so a static `require` would throw) and defers the multi-megabyte
-* wasm download until the engine is actually needed. Do NOT convert this to a
-* static import.
-*
-* A failed load is not cached: the rejected promise is dropped (the error is
-* latched on {@link getEngineError} for inspection), so calling `loadEngine()`
-* again retries from scratch. This is the clear-and-reload retry primitive after
-* a transient failure — an error boundary should call it before resetting.
-*/
 function loadEngine() {
 	if (enginePromise) return enginePromise;
 	engineError = null;
@@ -154,35 +117,16 @@ function loadEngine() {
 	});
 	return enginePromise;
 }
-/**
-* Whether the engine has finished initializing and is ready for sync use.
-*/
 function isEngineReady() {
 	return engineSync?.isReady() ?? false;
 }
-/**
-* The error from the last failed {@link loadEngine} attempt, or `null`. Used by
-* the React provider to surface a wasm-load failure to an error boundary rather
-* than suspending forever, and by imperative pollers to tell "failed" apart from
-* "still loading". Cleared when a new load starts or {@link resetEngine}.
-*/
 function getEngineError() {
 	return engineError;
 }
-/**
-* Return the already-initialized engine synchronously, or throw
-* {@link ExpressionNotReadyError} if {@link loadEngine} has not resolved yet.
-*/
 function getEngineSync() {
 	if (!engineSync) throw new ExpressionNotReadyError();
 	return engineSync;
 }
-/**
-* Reset the engine singleton — drops the loaded engine, the cached type context,
-* the latched error, and the configured wasm input. Mainly for tests, but also the
-* way to re-run {@link configureEngine} after a load (configure throws once the
-* engine has started loading).
-*/
 function resetEngine() {
 	typeContextCache?.handle.free();
 	typeContextCache = null;
@@ -193,16 +137,6 @@ function resetEngine() {
 }
 //#endregion
 //#region src/internal/env.ts
-/**
-* Best-effort development-mode flag for diagnostic-only code paths.
-*
-* Detected from `process.env.NODE_ENV` (defined by Node, test runners, webpack,
-* and Vite's SSR/`define`). The `typeof` guard is load-bearing: in a plain
-* browser bundle `process` is not declared at all, and any bare reference would
-* throw a ReferenceError while this module is being imported. Hosts without a
-* `process` default to "production" — the safe choice, since `isDev` only gates
-* extra developer-facing warnings.
-*/
 const isDev = detectDev();
 function detectDev() {
 	if (typeof process === "undefined") return false;
@@ -210,14 +144,6 @@ function detectDev() {
 }
 //#endregion
 //#region src/condition/subject.ts
-/**
-* Shared subject-path guard for the condition compilers. A subject / left-hand
-* path is emitted **verbatim** into ZEN source, so both {@link compileCondition}
-* (which writes that source) and {@link liftConditionTree} (which reads it back)
-* gate paths through this one predicate — a single definition of "what is a safe
-* field path" that cannot drift between the writer and the reader, which matters
-* because the guard is also the compiler's injection defense.
-*/
 const SUBJECT_PATTERN = /^[A-Z_$][\w$]*(?:\.[A-Z_$][\w$]*|\[\d+\])*$/i;
 const ZEN_RESERVED_WORDS = new Set([
 	"and",
@@ -228,26 +154,11 @@ const ZEN_RESERVED_WORDS = new Set([
 	"false",
 	"null"
 ]);
-/**
-* Whether `subject` is a plain identifier path safe to emit verbatim into ZEN
-* source: dotted/indexed segments only, none of which is a ZEN reserved word.
-*/
 function isIdentifierPath(subject) {
 	return SUBJECT_PATTERN.test(subject) && (subject.match(/[A-Z_$][\w$]*/gi) ?? []).every((segment) => !ZEN_RESERVED_WORDS.has(segment));
 }
 //#endregion
 //#region src/condition/compile.ts
-/**
-* Serialize a JavaScript value into a ZEN literal. Nullish becomes `null`;
-* numbers / booleans / bigints are emitted verbatim; strings are quoted via
-* {@link encodeZenString}; arrays become `[a, b, ...]`.
-*
-* Throws {@link ExpressionError} for a value with no faithful ZEN
-* representation — an object, symbol, or function, or a string containing both
-* quote styles. Callers that need a sentinel instead of a throw go through
-* {@link compileCondition}, which degrades such a value to a non-compiling
-* (null) condition.
-*/
 function toZenLiteral(value) {
 	if (isNullish(value)) return "null";
 	if (typeof value === "number") {
@@ -259,13 +170,6 @@ function toZenLiteral(value) {
 	if (isArray(value)) return `[${value.map((item) => toZenLiteral(item)).join(", ")}]`;
 	throw new ExpressionError(`Value of type "${typeof value}" has no ZEN literal representation`);
 }
-/**
-* Encode a string as a ZEN literal. ZEN string literals are **raw** between
-* matching quotes and honor no backslash escapes (`'a\nb'` is the four
-* characters `a \ n b`), so the encoder must not escape — it picks a delimiter
-* the value does not contain. A value containing both quote styles cannot be
-* represented as a raw ZEN literal and throws.
-*/
 function encodeZenString(value) {
 	const hasSingle = value.includes("'");
 	const hasDouble = value.includes("\"");
@@ -275,15 +179,6 @@ function encodeZenString(value) {
 function toArrayLiteral(value) {
 	return isArray(value) ? toZenLiteral(value) : `[${toZenLiteral(value)}]`;
 }
-/**
-* Emit the ZEN emptiness test matching the backend field evaluator's
-* `isEmptyValue`: null, blank (whitespace-only) text, and empty arrays are
-* empty; numbers and booleans never are. ZEN's `or` short-circuits, so the
-* type-guarded branches never evaluate against a null subject. The backend
-* additionally treats an empty map as empty for totality, but form values —
-* the only subjects this compiler targets — are never objects, and ZEN's
-* `len()` does not accept one.
-*/
 function zenIsEmpty(subject) {
 	return `(${subject} == null or (type(${subject}) == 'string' and len(trim(${subject})) == 0) or (type(${subject}) == 'array' and len(${subject}) == 0))`;
 }
@@ -306,12 +201,6 @@ function compileFieldCondition(subject, operator, value) {
 		default: throw new ExpressionError(`Unsupported operator: ${String(operator)}`);
 	}
 }
-/**
-* Compile a single condition into a ZEN boolean expression. Field conditions map
-* their operator to ZEN; expression conditions are wrapped in parentheses to
-* preserve their grouping. Returns `null` when the condition is empty, its
-* subject is not an identifier path, or its value has no ZEN representation.
-*/
 function compileCondition(condition) {
 	if (condition.kind === "expression") {
 		const expression = condition.expression.trim();
@@ -325,34 +214,14 @@ function compileCondition(condition) {
 		return null;
 	}
 }
-/**
-* Compile a condition group (its conditions joined with AND). Returns `null`
-* when the group has no compilable conditions.
-*/
 function compileGroup(group) {
 	const parts = group.conditions.map((condition) => compileCondition(condition)).filter((part) => part !== null);
 	return parts.length === 0 ? null : parts.join(" and ");
 }
-/**
-* Compile a branch's condition groups into a single ZEN expression (groups
-* joined with OR). Returns `null` when the branch has no compilable groups
-* (e.g. a default branch).
-*/
 function compileBranch(branch) {
 	const groups = (branch.conditionGroups ?? []).map((group) => compileGroup(group)).filter((group) => group !== null);
 	return groups.length === 0 ? null : groups.map((group) => `(${group})`).join(" or ");
 }
-/**
-* Pick the matching branch for the given context using a pre-loaded engine.
-* Non-default branches are tested in ascending `priority` order; the first whose
-* compiled expression evaluates to `true` wins. Falls back to the default
-* branch, or a `null` id when neither matches.
-*
-* A branch whose expression throws for the given context (e.g. ZEN's `>`
-* throws when the subject is missing or non-numeric) is treated as not matching
-* rather than propagating — so a missing field degrades to the default branch
-* instead of crashing the caller.
-*/
 function selectBranchWith(branches, context, engine) {
 	const ordered = branches.toSorted((a, b) => a.priority - b.priority);
 	for (const branch of ordered) {
@@ -389,30 +258,11 @@ function reportEvaluationFailure(engine, expression, error) {
 	}
 	if (!isNullish(diagnostic)) console.warn(`[expression] compiled branch expression failed to parse: ${expression}`, diagnostic, error);
 }
-/**
-* Pick the matching branch for the given context, loading the ZEN engine on
-* first use. See {@link selectBranchWith} for the selection semantics.
-*/
 async function selectBranch(branches, context) {
 	return selectBranchWith(branches, context, await loadEngine());
 }
 //#endregion
 //#region src/condition/types.ts
-/**
-* Structural shapes for the visual condition model compiled to ZEN. They mirror
-* the condition types used in the form and flow editors so a host can map those
-* definitions to {@link compileCondition} / {@link selectBranch} without this
-* package depending on either editor. The editors keep a flat working model for
-* form ergonomics (a row can hold both a half-typed field triple and an
-* expression while the author toggles between them); this discriminated input is
-* the narrowed, compiler-facing shape where each kind carries only what it uses.
-*/
-/**
-* The closed operator vocabulary understood by {@link compileCondition}, as a
-* runtime constant so validators can build allow-lists from it instead of
-* re-declaring the set. The {@link ConditionOperator} type derives from this
-* array — one definition site for both the type and the runtime list.
-*/
 const CONDITION_OPERATORS = [
 	"eq",
 	"ne",
@@ -445,32 +295,15 @@ const CONDITION_OPERATOR_ARITIES = {
 	is_empty: "none",
 	is_not_empty: "none"
 };
-/**
-* The arity of `operator`'s right-hand operand (see
-* {@link ConditionOperatorArity}). One definition site next to
-* {@link CONDITION_OPERATORS}, so the tree compiler's arity enforcement and a
-* condition editor's operand controls classify operators identically instead of
-* each keeping a drift-prone copy.
-*/
 function conditionOperatorArity(operator) {
 	return CONDITION_OPERATOR_ARITIES[operator];
 }
 //#endregion
 //#region src/condition/compile-tree.ts
-/**
-* Compile a condition tree to a canonical ZEN expression, or `""` when no rule in
-* the tree is compilable (see the module note for the drop semantics).
-*/
 function compileConditionTree(tree) {
 	const normalized = normalizeNode(tree);
 	return normalized === null ? "" : emitNode(normalized, true);
 }
-/**
-* Prune a node to its compilable core: drop rules {@link compileRule} rejects, drop
-* emptied groups, and collapse a single-surviving-item group to that item (so the
-* emitted shape carries no redundant parentheses). Returns `null` when nothing in
-* the node survives.
-*/
 function normalizeNode(node) {
 	if (node.kind === "rule") return compileRule(node) === null ? null : node;
 	const items = node.items.map((item) => normalizeNode(item)).filter((item) => item !== null);
@@ -482,27 +315,11 @@ function normalizeNode(node) {
 		items
 	};
 }
-/**
-* Render a normalized node. A rule emits its lowered ZEN; a group joins its items
-* with ` and ` / ` or ` and, unless it is the top-level group, wraps them in
-* parentheses so the tree structure survives ZEN's operator precedence on lift.
-*/
 function emitNode(node, topLevel) {
 	if (node.kind === "rule") return compileRule(node);
 	const joined = node.items.map((item) => emitNode(item, false)).join(node.op === "and" ? " and " : " or ");
 	return topLevel ? joined : `(${joined})`;
 }
-/**
-* Lower a leaf rule to ZEN via {@link compileCondition}, or `null` for a rule the
-* compiler cannot represent. The rule's `right` must match its operator's arity —
-* a single scalar for the comparison / string operators, an array of scalars for
-* `in` / `not_in`, absent for the emptiness operators (the contract
-* {@link ConditionTreeValue} documents); an off-arity rule is non-compilable and
-* drops. Enforcing arity here, not just relying on `compileCondition`, is what
-* keeps every emitted expression liftable: the flat compiler's lax value handling
-* would happily serialize e.g. a missing `right` as a `null` literal, which is not
-* part of the canonical grammar.
-*/
 function compileRule(rule) {
 	if (!matchesOperatorArity(rule)) return null;
 	return compileCondition({
@@ -563,13 +380,6 @@ const CALL_OPERATORS = {
 	endsWith: "ends_with"
 };
 const MAX_GROUP_DEPTH = 64;
-/**
-* Lift a ZEN expression to a condition tree, or `null` when it is not in the
-* canonical form {@link compileConditionTree} produces (the consumer then keeps the
-* raw expression). Groups nested deeper than 64 parenthesized levels are refused as
-* non-canonical rather than risking parser-stack overflow on adversarial input. The
-* returned root is always a group.
-*/
 function liftConditionTree(expression) {
 	const tokens = tokenize(expression);
 	if (tokens === null || tokens.length === 0) return null;
@@ -801,12 +611,6 @@ function liftConditionTree(expression) {
 	if (parsed === null || pos !== tokens.length) return null;
 	return asGroup(parsed);
 }
-/**
-* Read a dotted/indexed identifier path starting at `from`, validated through
-* {@link isIdentifierPath}. Pure over the token array (no cursor) so it can probe a
-* candidate path — the emptiness oracle reads the blob's subject without committing
-* the cursor. Returns the path and the index just past it, or `null`.
-*/
 function readPath(tokens, from) {
 	const head = tokens[from];
 	if (head === void 0 || head.kind !== "ident") return null;
@@ -844,13 +648,6 @@ function asGroup(node) {
 function isPunct(token, value) {
 	return token !== void 0 && token.kind === "punct" && token.value === value;
 }
-/**
-* Split a ZEN expression into tokens, or `null` on an unexpected character or an
-* unterminated string. Whitespace is dropped, so the parser (and the emptiness
-* oracle's token match) is insensitive to spacing. String literals are read raw
-* between matching quotes — ZEN honors no backslash escapes, mirroring the encoder
-* in {@link compileCondition}.
-*/
 function tokenize(input) {
 	const tokens = [];
 	let index = 0;
@@ -913,56 +710,20 @@ function tokenize(input) {
 }
 //#endregion
 //#region src/condition/tree-types.ts
-/**
-* The visual condition **tree** model: an arbitrarily nested and/or tree of typed
-* comparison rules that {@link compileConditionTree} serializes to a single ZEN
-* boolean expression and {@link liftConditionTree} reconstructs from one. It is a
-* distinct, self-contained shape from the compiler's flat {@link ConditionInput} —
-* the tree is what a structured builder UI edits, whereas `ConditionInput` is the
-* narrowed per-condition shape the compiler consumes. The two meet only at the
-* leaf: a {@link ConditionTreeRule} lowers to a field {@link ConditionInput} so the
-* operator vocabulary, literal encoding, and injection guard have one owner.
-*/
-/**
-* The tree's operator vocabulary as a runtime list — the compiler's full
-* {@link CONDITION_OPERATORS} set under the tree name. An alias, not a second
-* hand-maintained list, so the tree vocabulary can never drift from the compiler's;
-* it gives tree code and the builder UI one tree-named import for the operators they
-* support.
-*/
 const CONDITION_TREE_OPERATORS = CONDITION_OPERATORS;
 //#endregion
 //#region src/engine/evaluate.ts
-/**
-* Evaluate a standard ZEN expression, loading the engine on first use.
-*
-* `T` is an **unchecked** assertion — the value is returned as `T` with no
-* runtime validation, and ZEN's result type depends on the expression and
-* context. Prefer the `unknown` default and narrow at the call site.
-*/
 async function evaluate(expression, context) {
 	await loadEngine();
 	return evaluateSync(expression, context);
 }
-/**
-* Evaluate a ZEN unary (test) expression, loading the engine on first use.
-*/
 async function evaluateUnary(expression, context) {
 	await loadEngine();
 	return evaluateUnarySync(expression, context);
 }
-/**
-* Evaluate a standard ZEN expression synchronously. Throws
-* {@link ExpressionNotReadyError} when the engine has not loaded yet — use this
-* only behind a readiness gate (e.g. under `<ExpressionEngineProvider>`).
-*/
 function evaluateSync(expression, context) {
 	return getEngineSync().evaluate(expression, context);
 }
-/**
-* Evaluate a ZEN unary (test) expression synchronously. Throws
-* {@link ExpressionNotReadyError} when the engine has not loaded yet.
-*/
 function evaluateUnarySync(expression, context) {
 	return getEngineSync().evaluateUnary(expression, context);
 }
@@ -1071,9 +832,6 @@ const ZH_SOURCE_LABELS = {
 function sourceLabelFrom(table, fallback, type) {
 	return (type === void 0 ? void 0 : table[type]) ?? fallback;
 }
-/**
-* Built-in English message catalog (the default).
-*/
 const enMessages = {
 	sourceLabel: (type) => sourceLabelFrom(EN_SOURCE_LABELS, "Error", type),
 	completionInfo: (info) => info,
@@ -1081,9 +839,6 @@ const enMessages = {
 	expectedBoolean: (actualType) => `Expected a boolean test expression, received \`${actualType}\`.`,
 	expectedType: (expectedType, actualType) => `Expected \`${expectedType}\`, received \`${actualType}\`.`
 };
-/**
-* Built-in Simplified Chinese message catalog.
-*/
 const zhCNMessages = {
 	sourceLabel: (type) => sourceLabelFrom(ZH_SOURCE_LABELS, "错误", type),
 	completionInfo: (info) => info === "" ? "" : COMPLETION_INFO_ZH[info] ?? info,
@@ -1093,20 +848,9 @@ const zhCNMessages = {
 };
 const localeRegistry = new Map([["en-US", enMessages], ["zh-CN", zhCNMessages]]);
 let activeMessages = enMessages;
-/**
-* Register (or replace) the message catalog for a locale key, making it selectable
-* via {@link configureExpressionMessages}. This is how a host adds a language the
-* library does not ship — the built-in locales are registered the same way, so
-* there is no privileged path.
-*/
 function registerExpressionLocale(locale, messages) {
 	localeRegistry.set(locale, messages);
 }
-/**
-* Configure the active message catalog. Pass a `locale`, a partial `messages`
-* override, or both (overrides win). Idempotent and module-global, so a host
-* configures it once (e.g. through `ExpressionConfigProvider`).
-*/
 function configureExpressionMessages({ locale, messages }) {
 	const base = locale === void 0 ? activeMessages : localeRegistry.get(locale) ?? activeMessages;
 	activeMessages = messages === void 0 ? base : {
@@ -1114,9 +858,6 @@ function configureExpressionMessages({ locale, messages }) {
 		...messages
 	};
 }
-/**
-* The active {@link ExpressionMessages} catalog (English by default).
-*/
 function getExpressionMessages() {
 	return activeMessages;
 }
@@ -1126,11 +867,6 @@ function parseOffset(text) {
 	const trimmed = text?.trim();
 	return trimmed ? Number(trimmed) : NaN;
 }
-/**
-* Parse a trailing `... at (from, to)` / `... at pos` position out of a ZEN error
-* message. Returns a `[from, to]` range — a single offset collapses to
-* `[pos, pos]` — or `null` when no position is present.
-*/
 function extractPosition(message) {
 	const segments = message.split(" at ");
 	const last = segments.length <= 1 ? void 0 : segments.at(-1);
@@ -1141,10 +877,6 @@ function extractPosition(message) {
 	const to = parseOffset(right);
 	return [from, Number.isNaN(to) ? from : to];
 }
-/**
-* Normalize the wasm validate payload (`null` or `{ type, source }`) into a
-* positioned {@link ExpressionDiagnostic}, or `null` when the expression is valid.
-*/
 function normalizeDiagnostic(raw, source) {
 	if (raw === null || raw === void 0) return null;
 	const errorType = isRecord(raw) && typeof raw.type === "string" ? raw.type : void 0;
@@ -1157,10 +889,6 @@ function normalizeDiagnostic(raw, source) {
 		source: getExpressionMessages().sourceLabel(errorType)
 	};
 }
-/**
-* Normalize the wasm `getCompletions` payload into a typed list, dropping
-* malformed entries and stripping the backtick markers ZEN wraps type names in.
-*/
 function normalizeCompletions(raw) {
 	if (!Array.isArray(raw)) return [];
 	const messages = getExpressionMessages();
@@ -1176,75 +904,38 @@ function normalizeCompletions(raw) {
 		}];
 	});
 }
-/**
-* Validate an expression, loading the engine on first use. Resolves to `null`
-* when the expression is valid, or a positioned diagnostic otherwise.
-*/
 async function getDiagnostics(expression, mode) {
 	await loadEngine();
 	return getDiagnosticsSync(expression, mode);
 }
-/**
-* Synchronous {@link getDiagnostics}. Throws `ExpressionNotReadyError` if the
-* engine has not loaded yet — use only behind a readiness gate.
-*/
 function getDiagnosticsSync(expression, mode) {
 	const engine = getEngineSync();
 	return normalizeDiagnostic(mode === "unary" ? engine.validateUnary(expression) : engine.validate(expression), expression);
 }
-/**
-* Return the ZEN built-in completion list, loading the engine on first use.
-*/
 async function getCompletionItems() {
 	await loadEngine();
 	return getCompletionItemsSync();
 }
-/**
-* Synchronous {@link getCompletionItems}. Throws `ExpressionNotReadyError` if the
-* engine has not loaded yet.
-*/
 function getCompletionItemsSync() {
 	return normalizeCompletions(getEngineSync().getCompletions());
 }
-/**
-* Type-check an expression against a `variables` context, loading the engine on
-* first use. See {@link ExpressionAnalysis}.
-*/
 async function analyzeTypes(variables, source, mode) {
 	await loadEngine();
 	return analyzeTypesSync(variables, source, mode);
 }
-/**
-* Synchronous {@link analyzeTypes}. Throws `ExpressionNotReadyError` if the
-* engine has not loaded yet.
-*/
 function analyzeTypesSync(variables, source, mode) {
 	return getEngineSync().analyze(variables, source, mode === "unary");
 }
-/**
-* Whether `actual` satisfies (is assignable to) `expected`, loading the engine on
-* first use. Used for expected-return-type validation.
-*/
 async function satisfiesType(actual, expected) {
 	await loadEngine();
 	return satisfiesTypeSync(actual, expected);
 }
-/**
-* Synchronous {@link satisfiesType}. Throws `ExpressionNotReadyError` if the
-* engine has not loaded yet.
-*/
 function satisfiesTypeSync(actual, expected) {
 	return getEngineSync().satisfies(actual, expected);
 }
 //#endregion
 //#region src/engine/template.ts
 const HOLE_PATTERN = /\{\{(?<expression>[^{}]*)\}\}/g;
-/**
-* Extract every `{{ expression }}` hole from a template document, in source
-* order. Literal text outside holes is ignored. Pure string scan — no engine
-* required — matching the `@gorules/lezer-zen-template` hole grammar, so it is
-* consistent with the editor's highlighting and completion gating.
-*/
 function parseTemplateHoles(source) {
 	const holes = [];
 	HOLE_PATTERN.lastIndex = 0;
@@ -1259,31 +950,12 @@ function parseTemplateHoles(source) {
 	}
 	return holes;
 }
-/**
-* The template hole whose inner expression range contains `pos` (boundaries
-* included, so a caret sitting right after `{{` or right before `}}` counts as
-* inside), or `null` when `pos` is in literal text. Drives the editor's
-* hole-scoped completion and hover: intelligence fires inside a hole, nothing in
-* the surrounding literal text.
-*/
 function templateHoleAt(source, pos) {
 	return parseTemplateHoles(source).find((hole) => pos >= hole.from && pos <= hole.to) ?? null;
 }
 function hasExpression(hole) {
 	return hole.expression.trim().length > 0;
 }
-/**
-* Type-check every hole of a template against a `variables` context and merge the
-* results into one {@link ExpressionAnalysis} whose spans are offset onto the
-* template document. Each hole is a standard ZEN value expression; literal text
-* contributes nothing. `rootKind` is the context itself (shared by every hole),
-* so top-level completion works even in an empty hole.
-*
-* Best-effort: a hole that fails to analyze (e.g. mid-edit syntax) is skipped
-* rather than discarding the spans of its siblings. Throws
-* {@link ExpressionNotReadyError} if the engine has not loaded — use only behind
-* a readiness gate.
-*/
 function analyzeTemplateSync(variables, source) {
 	if (!isEngineReady()) throw new ExpressionNotReadyError();
 	const spans = [];
@@ -1301,22 +973,10 @@ function analyzeTemplateSync(variables, source) {
 		spans
 	};
 }
-/**
-* Async {@link analyzeTemplateSync}, loading the engine on first use.
-*/
 async function analyzeTemplate(variables, source) {
 	await loadEngine();
 	return analyzeTemplateSync(variables, source);
 }
-/**
-* Validate every hole of a template and return their syntax diagnostics, each
-* offset onto the template document (empty holes and literal text produce none).
-* The single-expression {@link getDiagnosticsSync} yields at most one diagnostic
-* per hole, so a template with several broken holes surfaces each one.
-*
-* Throws {@link ExpressionNotReadyError} if the engine has not loaded — use only
-* behind a readiness gate.
-*/
 function getTemplateDiagnosticsSync(source) {
 	if (!isEngineReady()) throw new ExpressionNotReadyError();
 	const diagnostics = [];
@@ -1331,9 +991,6 @@ function getTemplateDiagnosticsSync(source) {
 	}
 	return diagnostics;
 }
-/**
-* Async {@link getTemplateDiagnosticsSync}, loading the engine on first use.
-*/
 async function getTemplateDiagnostics(source) {
 	await loadEngine();
 	return getTemplateDiagnosticsSync(source);
@@ -1381,5 +1038,3 @@ exports.selectBranchWith = selectBranchWith;
 exports.templateHoleAt = templateHoleAt;
 exports.toZenLiteral = toZenLiteral;
 exports.zhCNMessages = zhCNMessages;
-
-//# sourceMappingURL=index.cjs.map

package/dist/index.d.cts

@@ -677,5 +677,4 @@ declare function getTemplateDiagnosticsSync(source: string): ExpressionDiagnosti
  */
 declare function getTemplateDiagnostics(source: string): Promise<ExpressionDiagnostic[]>;
 //#endregion
-export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, enMessages, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, liftConditionTree, loadEngine, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };
-//# sourceMappingURL=index.d.cts.map
+export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, enMessages, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, liftConditionTree, loadEngine, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };

package/dist/index.d.ts

@@ -677,5 +677,4 @@ declare function getTemplateDiagnosticsSync(source: string): ExpressionDiagnosti
  */
 declare function getTemplateDiagnostics(source: string): Promise<ExpressionDiagnostic[]>;
 //#endregion
-export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, enMessages, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, liftConditionTree, loadEngine, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };
-//# sourceMappingURL=index.d.ts.map
+export { type BranchSelection, type BuiltInExpressionLocale, CONDITION_OPERATORS, CONDITION_TREE_OPERATORS, type ConditionBranchInput, type ConditionGroupInput, type ConditionInput, type ConditionOperator, type ConditionOperatorArity, type ConditionScalar, type ConditionTreeGroup, type ConditionTreeNode, type ConditionTreeOperator, type ConditionTreeRule, type ConditionTreeValue, type ConfigureMessagesOptions, type ExpressionAnalysis, type ExpressionCompletion, type ExpressionConditionInput, type ExpressionContext, type ExpressionDiagnostic, type ExpressionEngine, ExpressionError, type ExpressionLocale, type ExpressionMessages, type ExpressionMode, ExpressionNotReadyError, type ExpressionType, type ExpressionTypeSpan, type FieldConditionInput, type LoadEngineOptions, type TemplateHole, analyzeTemplate, analyzeTemplateSync, analyzeTypes, analyzeTypesSync, compileBranch, compileCondition, compileConditionTree, compileGroup, conditionOperatorArity, configureEngine, configureExpressionMessages, enMessages, evaluate, evaluateSync, evaluateUnary, evaluateUnarySync, getCompletionItems, getCompletionItemsSync, getDiagnostics, getDiagnosticsSync, getEngineError, getEngineSync, getExpressionMessages, getTemplateDiagnostics, getTemplateDiagnosticsSync, isEngineReady, liftConditionTree, loadEngine, parseTemplateHoles, registerExpressionLocale, resetEngine, satisfiesType, satisfiesTypeSync, selectBranch, selectBranchWith, templateHoleAt, toZenLiteral, zhCNMessages };