devframe 0.1.19 → 0.1.21

package/dist/utils/shared-state.d.mts

@@ -1,2 +1,2 @@
-import { C as ImmutableSet, D as createSharedState, E as SharedStateOptions, S as ImmutableObject, T as SharedStateEvents, b as ImmutableArray, k as Patch, w as SharedState, x as ImmutableMap, y as Immutable } from "../devtool-CIqONpYU.mjs";
-export { Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableSet, SharedState, SharedStateEvents, SharedStateOptions, Patch as SharedStatePatch, createSharedState };
+import { A as ImmutableArray, F as SharedStateEvents, I as SharedStateOptions, L as SharedStatePatch, M as ImmutableObject, N as ImmutableSet, P as SharedState, R as createSharedState, j as ImmutableMap, k as Immutable } from "../devtool-CNvLs2_Y.mjs";
+export { Immutable, ImmutableArray, ImmutableMap, ImmutableObject, ImmutableSet, SharedState, SharedStateEvents, SharedStateOptions, SharedStatePatch, createSharedState };

package/dist/utils/shared-state.mjs

@@ -1,6 +1,6 @@
 import { createEventEmitter } from "./events.mjs";
-import { i as produceWithPatches, n as enablePatches, r as produce, t as applyPatches } from "../immer-HjMAm3b6.mjs";
 import { nanoid } from "./nanoid.mjs";
+import { applyPatches, enablePatches, produce, produceWithPatches } from "immer";
 //#region src/utils/shared-state.ts
 function createSharedState(options) {
 	const { enablePatches: enablePatches$1 = false } = options;

package/dist/utils/state.d.mts

@@ -1,4 +1,5 @@
-import { O as Objectish, Zt as EventEmitter, k as Patch } from "../devtool-CIqONpYU.mjs";
+import { ct as EventEmitter } from "../devtool-CNvLs2_Y.mjs";
+import { Objectish, Patch } from "immer";
 
 //#region src/utils/state.d.ts
 type ImmutablePrimitive = undefined | null | boolean | string | number | Function;

package/dist/utils/state.mjs

@@ -1,5 +1,5 @@
 import { createEventEmitter } from "./events.mjs";
-import { i as produceWithPatches, r as produce, t as applyPatches } from "../immer-HjMAm3b6.mjs";
+import { applyPatches, produce, produceWithPatches } from "immer";
 //#region src/utils/state.ts
 function createSharedState(options) {
 	const { enablePatches = false } = options;

package/dist/utils/streaming-channel.d.mts

@@ -0,0 +1,2 @@
+import { C as StreamErrorPayload, D as createStreamReader, E as StreamSinkEvents, O as createStreamSink, S as CreateStreamSinkOptions, T as StreamSink, b as BufferedChunk, w as StreamReader, x as CreateStreamReaderOptions } from "../devtool-CNvLs2_Y.mjs";
+export { BufferedChunk, CreateStreamReaderOptions, CreateStreamSinkOptions, StreamErrorPayload, StreamReader, StreamSink, StreamSinkEvents, createStreamReader, createStreamSink };

package/dist/utils/streaming-channel.mjs

@@ -0,0 +1,255 @@
+import { createEventEmitter } from "./events.mjs";
+import { nanoid } from "./nanoid.mjs";
+//#region src/utils/streaming-channel.ts
+const DEFAULT_HIGH_WATER_MARK = 256;
+var StreamClosedError = class extends Error {
+	name = "StreamClosedError";
+};
+/**
+* Build a server-side stream sink. RPC-agnostic — the RPC host wires
+* `events.on('chunk' | 'end')` to broadcast, and reads `buffer` to replay
+* for late or reconnecting subscribers.
+*/
+function createStreamSink(options = {}) {
+	const id = options.id ?? nanoid();
+	const replayWindow = Math.max(0, options.replayWindow ?? 0);
+	const events = createEventEmitter();
+	const controller = new AbortController();
+	const buffer = [];
+	let closed = false;
+	let lastSeq = 0;
+	function write(chunk) {
+		if (closed) throw new StreamClosedError(`Cannot write to a closed stream "${id}"`);
+		lastSeq += 1;
+		if (replayWindow > 0) {
+			buffer.push({
+				seq: lastSeq,
+				chunk
+			});
+			if (buffer.length > replayWindow) buffer.splice(0, buffer.length - replayWindow);
+		}
+		events.emit("chunk", lastSeq, chunk);
+	}
+	function error(reason) {
+		if (closed) return;
+		closed = true;
+		const payload = toErrorPayload(reason);
+		controller.abort(reason);
+		events.emit("end", payload);
+	}
+	function close() {
+		if (closed) return;
+		closed = true;
+		if (!controller.signal.aborted) controller.abort("stream closed");
+		events.emit("end", void 0);
+	}
+	function abort(reason) {
+		if (closed) return;
+		if (!controller.signal.aborted) controller.abort(reason ?? "aborted");
+	}
+	const writable = new WritableStream({
+		write(chunk) {
+			write(chunk);
+		},
+		close() {
+			close();
+		},
+		abort(reason) {
+			error(reason);
+		}
+	});
+	return {
+		id,
+		signal: controller.signal,
+		get closed() {
+			return closed;
+		},
+		get lastSeq() {
+			return lastSeq;
+		},
+		write,
+		error,
+		close,
+		abort,
+		writable,
+		events,
+		buffer
+	};
+}
+/**
+* Build a client-side stream reader. RPC-agnostic — the RPC host calls
+* `_push(seq, chunk)` on each incoming chunk and `_end(error?)` on the
+* terminal frame. Consumers iterate with `for await` or pipe `readable`.
+*/
+function createStreamReader(options = {}) {
+	const id = options.id ?? nanoid();
+	const highWaterMark = Math.max(1, options.highWaterMark ?? DEFAULT_HIGH_WATER_MARK);
+	const queue = [];
+	let lastSeenSeq = 0;
+	let done = false;
+	let cancelled = false;
+	let endError;
+	let pending;
+	let pullController;
+	let readableInstance;
+	function drainNext() {
+		if (!pending) return;
+		if (queue.length > 0) {
+			const value = queue.shift();
+			const r = pending;
+			pending = void 0;
+			r.resolve({
+				value,
+				done: false
+			});
+			return;
+		}
+		if (done) {
+			const r = pending;
+			pending = void 0;
+			if (endError) {
+				const err = new Error(endError.message);
+				err.name = endError.name;
+				r.reject(err);
+			} else r.resolve({
+				value: void 0,
+				done: true
+			});
+		}
+	}
+	function feedReadable() {
+		if (!pullController) return;
+		while (queue.length > 0) {
+			const v = queue.shift();
+			try {
+				pullController.enqueue(v);
+			} catch {
+				break;
+			}
+		}
+		if (done && pullController) {
+			try {
+				if (endError) {
+					const err = new Error(endError.message);
+					err.name = endError.name;
+					pullController.error(err);
+				} else pullController.close();
+			} catch {}
+			pullController = void 0;
+		}
+	}
+	function push(seq, chunk) {
+		if (done || cancelled) return;
+		if (seq <= lastSeenSeq) return;
+		lastSeenSeq = seq;
+		queue.push(chunk);
+		if (queue.length > highWaterMark) {
+			const overflow = queue.length - highWaterMark;
+			queue.splice(0, overflow);
+			options.onOverflow?.(overflow);
+		}
+		drainNext();
+		if (readableInstance) feedReadable();
+	}
+	function end(error) {
+		if (done) return;
+		done = true;
+		endError = error;
+		drainNext();
+		if (readableInstance) feedReadable();
+	}
+	function cancel() {
+		if (cancelled || done) return;
+		cancelled = true;
+		options.onCancel?.();
+		end(void 0);
+	}
+	function getReadable() {
+		if (readableInstance) return readableInstance;
+		readableInstance = new ReadableStream({
+			start(controller) {
+				pullController = controller;
+				feedReadable();
+			},
+			cancel() {
+				cancel();
+			}
+		});
+		return readableInstance;
+	}
+	return {
+		id,
+		get cancelled() {
+			return cancelled;
+		},
+		get done() {
+			return done;
+		},
+		get lastSeenSeq() {
+			return lastSeenSeq;
+		},
+		get readable() {
+			return getReadable();
+		},
+		cancel,
+		_push: push,
+		_end: end,
+		[Symbol.asyncIterator]() {
+			return {
+				next() {
+					if (queue.length > 0) return Promise.resolve({
+						value: queue.shift(),
+						done: false
+					});
+					if (done) {
+						if (endError) {
+							const err = new Error(endError.message);
+							err.name = endError.name;
+							return Promise.reject(err);
+						}
+						return Promise.resolve({
+							value: void 0,
+							done: true
+						});
+					}
+					return new Promise((resolve, reject) => {
+						pending = {
+							resolve,
+							reject
+						};
+					});
+				},
+				return() {
+					cancel();
+					return Promise.resolve({
+						value: void 0,
+						done: true
+					});
+				}
+			};
+		}
+	};
+}
+function toErrorPayload(reason) {
+	if (reason instanceof Error) return {
+		name: reason.name || "Error",
+		message: reason.message
+	};
+	if (typeof reason === "string") return {
+		name: "Error",
+		message: reason
+	};
+	try {
+		return {
+			name: "Error",
+			message: JSON.stringify(reason)
+		};
+	} catch {
+		return {
+			name: "Error",
+			message: String(reason)
+		};
+	}
+}
+//#endregion
+export { createStreamReader, createStreamSink };

package/dist/utils/when.d.mts

@@ -1,2 +1,401 @@
-import { i as resolveContextValue, n as WhenExpression, r as evaluateWhen, t as WhenContext } from "../when-BAE663Hv.mjs";
-export { WhenContext, WhenExpression, evaluateWhen, resolveContextValue };
+//#region ../../../node_modules/.pnpm/whenexpr@0.1.2/node_modules/whenexpr/dist/index.d.mts
+//#region src/paths.d.ts
+/**
+ * Union of valid context paths for `T` — both flat keys (`keyof T`) and
+ * `.`/`:`-separated nested paths. Mirrors the runtime `resolve()` lookup:
+ * first a flat literal key, then a segmented path.
+ *
+ * @example
+ * type P = ContextPaths<{ editor: { lang: string }, debug: boolean }>
+ * // 'editor' | 'debug' | 'editor.lang' | 'editor:lang'
+ */
+type ContextPaths<T, P extends string = ''> = { [K in keyof T & string]: `${P}${K}` | (T[K] extends readonly unknown[] ? never : T[K] extends ((...args: never[]) => unknown) ? never : T[K] extends object ? ContextPaths<T[K], `${P}${K}.`> | ContextPaths<T[K], `${P}${K}:`> : never) }[keyof T & string]; //#endregion
+//#region src/types.d.ts
+/**
+ * Branded error type surfaced at the call site of `evaluateWhen` when the
+ * expression string fails static validation. The embedded message appears in
+ * the TS error tooltip because `WhenExpressionError<M>` is not assignable from a
+ * plain string literal.
+ */
+type WhenExpressionError<M extends string> = string & {
+  readonly __whenExpressionError: M;
+};
+type Ws = ' ' | '\t' | '\n' | '\r';
+type Digit = '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9';
+type Lower = 'a' | 'b' | 'c' | 'd' | 'e' | 'f' | 'g' | 'h' | 'i' | 'j' | 'k' | 'l' | 'm' | 'n' | 'o' | 'p' | 'q' | 'r' | 's' | 't' | 'u' | 'v' | 'w' | 'x' | 'y' | 'z';
+type Upper = 'A' | 'B' | 'C' | 'D' | 'E' | 'F' | 'G' | 'H' | 'I' | 'J' | 'K' | 'L' | 'M' | 'N' | 'O' | 'P' | 'Q' | 'R' | 'S' | 'T' | 'U' | 'V' | 'W' | 'X' | 'Y' | 'Z';
+type IdentStart = Lower | Upper | '_' | '$';
+type IdentCont = IdentStart | Digit | '.' | ':';
+type Op = '===' | '!==' | '==' | '!=' | '<=' | '>=' | '&&' | '||' | '<' | '>' | '+' | '-' | '*' | '/' | '%' | '!';
+type Tok = {
+  k: 'num';
+  v: string;
+} | {
+  k: 'str';
+  v: string;
+} | {
+  k: 'id';
+  v: string;
+} | {
+  k: 'bool';
+  v: 'true' | 'false';
+} | {
+  k: 'op';
+  v: Op;
+} | {
+  k: 'lp';
+} | {
+  k: 'rp';
+} | {
+  k: 'eof';
+};
+interface TokErr {
+  __err: string;
+}
+type Tokenize<S extends string, Acc extends Tok[] = []> = S extends '' ? [...Acc, {
+  k: 'eof';
+}] : S extends `${Ws}${infer R}` ? Tokenize<R, Acc> : S extends `===${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '===';
+}]> : S extends `!==${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '!==';
+}]> : S extends `==${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '==';
+}]> : S extends `!=${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '!=';
+}]> : S extends `<=${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '<=';
+}]> : S extends `>=${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '>=';
+}]> : S extends `&&${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '&&';
+}]> : S extends `||${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '||';
+}]> : S extends `<${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '<';
+}]> : S extends `>${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '>';
+}]> : S extends `+${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '+';
+}]> : S extends `-${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '-';
+}]> : S extends `*${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '*';
+}]> : S extends `/${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '/';
+}]> : S extends `%${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '%';
+}]> : S extends `!${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'op';
+  v: '!';
+}]> : S extends `(${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'lp';
+}]> : S extends `)${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'rp';
+}]> : S extends `"${infer R}` ? ConsumeStr<R, '', '"', Acc> : S extends `'${infer R}` ? ConsumeStr<R, '', '\'', Acc> : S extends `${infer C extends Digit}${infer R}` ? ConsumeNum<R, C, Acc> : S extends `${infer C extends IdentStart}${infer R}` ? ConsumeIdent<R, C, Acc> : {
+  __err: `Unexpected character in "${S}"`;
+};
+type ConsumeNum<S extends string, N extends string, Acc extends Tok[]> = S extends `${infer C extends Digit}${infer R}` ? ConsumeNum<R, `${N}${C}`, Acc> : S extends `.${infer C extends Digit}${infer R}` ? ConsumeNumFrac<R, `${N}.${C}`, Acc> : Tokenize<S, [...Acc, {
+  k: 'num';
+  v: N;
+}]>;
+type ConsumeNumFrac<S extends string, N extends string, Acc extends Tok[]> = S extends `${infer C extends Digit}${infer R}` ? ConsumeNumFrac<R, `${N}${C}`, Acc> : Tokenize<S, [...Acc, {
+  k: 'num';
+  v: N;
+}]>;
+type ConsumeIdent<S extends string, N extends string, Acc extends Tok[]> = S extends `${infer C extends IdentCont}${infer R}` ? ConsumeIdent<R, `${N}${C}`, Acc> : Tokenize<S, [...Acc, ClassifyIdent<N>]>;
+type ClassifyIdent<N extends string> = N extends 'true' ? {
+  k: 'bool';
+  v: 'true';
+} : N extends 'false' ? {
+  k: 'bool';
+  v: 'false';
+} : {
+  k: 'id';
+  v: N;
+};
+type ConsumeStr<S extends string, V extends string, Q extends '"' | '\'', Acc extends Tok[]> = S extends `${Q}${infer R}` ? Tokenize<R, [...Acc, {
+  k: 'str';
+  v: V;
+}]> : S extends `\\${infer C}${infer R}` ? ConsumeStr<R, `${V}${C}`, Q, Acc> : S extends `${infer C}${infer R}` ? ConsumeStr<R, `${V}${C}`, Q, Acc> : {
+  __err: 'Unterminated string literal';
+};
+type BinOp = '||' | '&&' | '==' | '!=' | '===' | '!==' | '<' | '>' | '<=' | '>=' | '+' | '-' | '*' | '/' | '%';
+type UnOp = '!' | '-' | '+';
+interface LitNode {
+  t: 'lit';
+  v: string;
+}
+interface KeyNode {
+  t: 'key';
+  v: string;
+}
+interface UnNode {
+  t: 'un';
+  op: UnOp;
+  x: Ast;
+}
+interface BinNode {
+  t: 'bin';
+  op: BinOp;
+  l: Ast;
+  r: Ast;
+}
+type Ast = LitNode | KeyNode | UnNode | BinNode;
+type Parse<Toks extends Tok[]> = ParseOr<Toks>;
+type ParseOr<T extends Tok[]> = OrTail<ParseAnd<T>>;
+type OrTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
+  k: 'op';
+  v: '||';
+}, ...infer After extends Tok[]] ? ParseAnd<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? OrTail<[{
+  t: 'bin';
+  op: '||';
+  l: L;
+  r: Rh;
+}, Next]> : 'err' : R : R;
+type ParseAnd<T extends Tok[]> = AndTail<ParseEq<T>>;
+type AndTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
+  k: 'op';
+  v: '&&';
+}, ...infer After extends Tok[]] ? ParseEq<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? AndTail<[{
+  t: 'bin';
+  op: '&&';
+  l: L;
+  r: Rh;
+}, Next]> : 'err' : R : R;
+type ParseEq<T extends Tok[]> = EqTail<ParseRel<T>>;
+type EqTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
+  k: 'op';
+  v: infer O extends '==' | '!=';
+}, ...infer After extends Tok[]] ? ParseValueRhs<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? EqTail<[{
+  t: 'bin';
+  op: O;
+  l: L;
+  r: Rh;
+}, Next]> : 'err' : Rest extends [{
+  k: 'op';
+  v: infer O extends '===' | '!==';
+}, ...infer After extends Tok[]] ? ParseRel<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? EqTail<[{
+  t: 'bin';
+  op: O;
+  l: L;
+  r: Rh;
+}, Next]> : 'err' : R : R;
+type ParseValueRhs<T extends Tok[]> = T extends [{
+  k: 'id';
+  v: infer V extends string;
+}, ...infer R extends Tok[]] ? [{
+  t: 'lit';
+  v: V;
+}, R] : T extends [{
+  k: 'str';
+  v: infer V extends string;
+}, ...infer R extends Tok[]] ? [{
+  t: 'lit';
+  v: V;
+}, R] : T extends [{
+  k: 'num';
+  v: infer V extends string;
+}, ...infer R extends Tok[]] ? [{
+  t: 'lit';
+  v: V;
+}, R] : T extends [{
+  k: 'bool';
+  v: infer V extends string;
+}, ...infer R extends Tok[]] ? [{
+  t: 'lit';
+  v: V;
+}, R] : 'err';
+type ParseRel<T extends Tok[]> = RelTail<ParseAdd<T>>;
+type RelTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
+  k: 'op';
+  v: infer O extends '<=' | '>=' | '<' | '>';
+}, ...infer After extends Tok[]] ? ParseAdd<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? RelTail<[{
+  t: 'bin';
+  op: O;
+  l: L;
+  r: Rh;
+}, Next]> : 'err' : R : R;
+type ParseAdd<T extends Tok[]> = AddTail<ParseMul<T>>;
+type AddTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
+  k: 'op';
+  v: infer O extends '+' | '-';
+}, ...infer After extends Tok[]] ? ParseMul<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? AddTail<[{
+  t: 'bin';
+  op: O;
+  l: L;
+  r: Rh;
+}, Next]> : 'err' : R : R;
+type ParseMul<T extends Tok[]> = MulTail<ParseUnary<T>>;
+type MulTail<R> = R extends [infer L extends Ast, infer Rest extends Tok[]] ? Rest extends [{
+  k: 'op';
+  v: infer O extends '*' | '/' | '%';
+}, ...infer After extends Tok[]] ? ParseUnary<After> extends [infer Rh extends Ast, infer Next extends Tok[]] ? MulTail<[{
+  t: 'bin';
+  op: O;
+  l: L;
+  r: Rh;
+}, Next]> : 'err' : R : R;
+type ParseUnary<T extends Tok[]> = T extends [{
+  k: 'op';
+  v: infer O extends UnOp;
+}, ...infer Rest extends Tok[]] ? ParseUnary<Rest> extends [infer X extends Ast, infer Next extends Tok[]] ? [{
+  t: 'un';
+  op: O;
+  x: X;
+}, Next] : 'err' : ParsePrimary<T>;
+type ParsePrimary<T extends Tok[]> = T extends [{
+  k: 'num';
+  v: infer V extends string;
+}, ...infer R extends Tok[]] ? [{
+  t: 'lit';
+  v: V;
+}, R] : T extends [{
+  k: 'str';
+  v: infer V extends string;
+}, ...infer R extends Tok[]] ? [{
+  t: 'lit';
+  v: V;
+}, R] : T extends [{
+  k: 'bool';
+  v: infer V extends string;
+}, ...infer R extends Tok[]] ? [{
+  t: 'lit';
+  v: V;
+}, R] : T extends [{
+  k: 'id';
+  v: infer V extends string;
+}, ...infer R extends Tok[]] ? [{
+  t: 'key';
+  v: V;
+}, R] : T extends [{
+  k: 'lp';
+}, ...infer Rest extends Tok[]] ? ParseOr<Rest> extends [infer N extends Ast, infer After extends Tok[]] ? After extends [{
+  k: 'rp';
+}, ...infer Next extends Tok[]] ? [N, Next] : 'err' : 'err' : 'err';
+type CollectKeys<N> = N extends KeyNode ? N['v'] : N extends UnNode ? CollectKeys<N['x']> : N extends {
+  t: 'bin';
+  op: '==' | '!=';
+  l: infer L;
+} ? CollectKeys<L> : N extends BinNode ? CollectKeys<N['l']> | CollectKeys<N['r']> : never;
+/**
+ * Validate a when-clause expression string `S` against context type `T`.
+ * Returns `S` on success, or a `WhenExpressionError<Msg>` branded error string
+ * that surfaces at the call site with a human-readable message.
+ *
+ * - Dynamic `string` expressions skip all validation.
+ * - Wide context types (`object`, `any`, `unknown`, `Record<string, unknown>`,
+ *   empty `{}`, etc.) still run **syntax** checking but skip **key** checking.
+ * - Specific context types run full validation (syntax + keys).
+ */
+type ValidateExpression<S extends string, T> = string extends S ? S : Tokenize<S> extends infer Toks ? Toks extends TokErr ? WhenExpressionError<`Syntax error: ${Toks['__err']}`> : Toks extends Tok[] ? Parse<Toks> extends [infer N extends Ast, [{
+  k: 'eof';
+}]] ? [keyof T] extends [never] ? S : string extends keyof T ? S : Exclude<CollectKeys<N>, ContextPaths<T>> extends infer Missing ? [Missing] extends [never] ? S : WhenExpressionError<`Unknown context key: "${Extract<Missing, string>}"`> : never : WhenExpressionError<'Syntax error in expression'> : never : never;
+/**
+ * A when-clause expression string validated against context type `T`.
+ * Use inside your own typed define helpers to have TypeScript check `when`
+ * fields at the call site.
+ *
+ * @example
+ * interface AppCtx { mode: 'dev' | 'prod', debug: boolean }
+ *
+ * function defineCommand<const W extends string>(cmd: {
+ *   name: string
+ *   title: string
+ *   when?: WhenExpression<AppCtx, W>
+ * }): typeof cmd {
+ *   return cmd
+ * }
+ *
+ * defineCommand({ name: 'x', title: 'X', when: 'debug && mode == dev' })
+ * defineCommand({ name: 'x', title: 'X', when: 'typo' })
+ * //                                            ^^^^^ type error
+ */
+type WhenExpression<T, S extends string> = S & ValidateExpression<S, T>; //#endregion
+//#region src/index.d.ts
+interface EvaluateOptions {
+  /**
+   * If `true`, throw when the expression references a context key that does
+   * not exist. Defaults to `false`, where unknown keys evaluate to `undefined`.
+   */
+  strict?: boolean;
+}
+/**
+ * Evaluate a when-clause expression string against a context object.
+ * Equivalent to `evaluate(parse(expression), ctx, options)`.
+ *
+ * Supports a JS-expression subset:
+ * - Literals: booleans, numbers, strings (quoted with `"` or `'`)
+ * - Identifiers: bare keys, including namespaced (`vite.mode`, `vite:buildMode`)
+ * - Logical: `&&`, `||`, `!`
+ * - Equality: `==`, `!=` (string comparison, bare identifier RHS treated as string),
+ *             `===`, `!==` (JS strict equality with full expression RHS)
+ * - Relational: `<`, `<=`, `>`, `>=`
+ * - Arithmetic: `+`, `-`, `*`, `/`, `%`, unary `-` / `+`
+ * - Grouping: `(` … `)`
+ *
+ * When `ctx` has a specific type with known keys, the expression string is
+ * **statically validated** — unknown context keys and syntax errors surface
+ * as TypeScript errors at the call site. Pass `ctx` typed as
+ * `Record<string, unknown>`, or the expression as `string`, to opt out of
+ * static checking (e.g. for dynamic expressions).
+ *
+ * With `{ strict: true }`, referencing an unknown context key at runtime
+ * throws. Short-circuit evaluation still applies — keys not reached are not
+ * checked.
+ */
+declare function evaluateWhen<T extends object, const E extends string>(expression: E & ValidateExpression<E, T>, ctx: T, options?: EvaluateOptions): boolean;
+/**
+ * Resolve a context value by key. Supports namespaced keys with `.` or `:` separators.
+ *
+ * Lookup order:
+ * 1. Exact match — `ctx['plugin.mode']` or `ctx['plugin:mode']`
+ * 2. Nested path — e.g. `plugin.mode` falls back to `ctx.plugin?.mode`
+ *
+ * Returns `undefined` for unknown keys.
+ */
+declare function resolveContextValue<T extends Record<string, unknown>>(key: string, ctx: T): unknown; //#endregion
+//#endregion
+//#region src/utils/when.d.ts
+/**
+ * Context object for evaluating `when` expressions.
+ *
+ * Built-in variables:
+ * - `clientType` — `'embedded' | 'standalone'`
+ * - `dockOpen` — whether the dock panel is open
+ * - `paletteOpen` — whether the command palette is open
+ * - `dockSelectedId` — ID of the selected dock entry (empty string if none)
+ *
+ * Plugins can add namespaced variables using dot or colon separators:
+ * - `vite.mode`, `vite:mode` — stored as `{ 'vite.mode': 'development' }` or nested `{ vite: { mode: 'development' } }`
+ *
+ * The expression language — including all operators and precedence — is provided by
+ * the [`whenexpr`](https://github.com/antfu/whenexpr) package. In addition to the
+ * VS-Code-style `!`/`==`/`!=`/`&&`/`||` operators, parentheses, strict equality
+ * (`===`/`!==`), relational (`<`/`<=`/`>`/`>=`), arithmetic (`+ - * / %`), and
+ * number/string literals are supported.
+ */
+interface WhenContext {
+  clientType: 'embedded' | 'standalone';
+  dockOpen: boolean;
+  paletteOpen: boolean;
+  dockSelectedId: string;
+  /** Allow custom context variables from plugins */
+  [key: string]: unknown;
+}
+//#endregion
+export { WhenContext, type WhenExpression, evaluateWhen, resolveContextValue };