@lynx-go/ui-kit 0.1.0 → 0.2.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lynx-go/ui-kit",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "Headless core for data-dense console UIs — Query / Command / Subscription over TanStack engines",
   "type": "module",
   "license": "MIT",
@@ -28,19 +28,18 @@
     "./react": {
       "types": "./src/react/index.ts",
       "default": "./src/react/index.ts"
+    },
+    "./testing": {
+      "types": "./src/testing/index.ts",
+      "default": "./src/testing/index.ts"
     }
   },
   "files": [
     "src",
     "dist"
   ],
-  "scripts": {
-    "typecheck": "tsc -p tsconfig.json --noEmit",
-    "test": "vitest run",
-    "build": "tsup"
-  },
   "dependencies": {
-    "effect": "catalog:default"
+    "effect": "~4.0.6"
   },
   "peerDependencies": {
     "react": ">=19",
@@ -57,12 +56,21 @@
     }
   },
   "devDependencies": {
-    "@tanstack/react-query": "catalog:default",
-    "@tanstack/react-router": "catalog:default",
-    "@types/react": "catalog:default",
-    "react": "catalog:default",
-    "typescript": "catalog:default",
-    "vitest": "catalog:default",
-    "@tanstack/react-form": "catalog:default"
+    "@tanstack/react-query": "^5.104.5",
+    "@tanstack/react-router": "^1.170.46",
+    "@types/react": "^19.3.0",
+    "react": "^19.3.1",
+    "typescript": "~5.9.3",
+    "vitest": "^5.0.5",
+    "@tanstack/react-form": "^1.33.5",
+    "jsdom": "^28.0.0",
+    "@testing-library/react": "^16.3.0",
+    "react-dom": "^19.3.1",
+    "@types/react-dom": "^19.3.0"
+  },
+  "scripts": {
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run",
+    "build": "tsup"
   }
-}
+}

package/src/adapters/http.ts

@@ -60,7 +60,7 @@ export function runApi<A>(eff: Effect.Effect<A, AdapterFailure>): Promise<A> {
           return;
         }
         // defect（程序错误）——归一为可观测的包装，不混入 ApiError 封闭集
-        reject(new Error("fleet-ui: unexpected defect in adapter pipeline", { cause: err }));
+        reject(new Error("@lynx-go/ui-kit: unexpected defect in adapter pipeline", { cause: err }));
       }),
   );
 }
@@ -135,7 +135,7 @@ export function createHttp(options: HttpOptions = {}) {
             catch: () =>
               new HttpFailure({
                 status: response.status,
-                body: { message: `fleet-ui: response is not JSON (${path})` },
+                body: { message: `@lynx-go/ui-kit: response is not JSON (${path})` },
               }) as AdapterFailure,
           });
         }),

package/src/adapters/transport.ts

@@ -53,7 +53,7 @@ async function fetchOrApiError(
 
 class TransportInterrupt extends Error {
   constructor(detail: string) {
-    super(`fleet-ui: transport interrupted (${detail})`);
+    super(`@lynx-go/ui-kit: transport interrupted (${detail})`);
   }
 }
 

package/src/kernel/keys.ts

@@ -61,10 +61,10 @@ export function batchKey<T, ID, C extends CommandsRecord<ID>, S extends SubsReco
 
 // ============ 失效匹配（scope 交运算在此） ============
 
-const FLEET_KINDS = new Set(["collection", "record", "batch"]);
+const QUERY_KINDS = new Set(["collection", "record", "batch"]);
 
-export function isFleetKey(key: readonly unknown[]): boolean {
-  return typeof key[0] === "string" && FLEET_KINDS.has(key[0]);
+export function isKindedQueryKey(key: readonly unknown[]): boolean {
+  return typeof key[0] === "string" && QUERY_KINDS.has(key[0]);
 }
 
 /**
@@ -94,6 +94,6 @@ export function invalidationPredicate(
   commandScope: ResourceScope,
 ): (query: { queryKey: readonly unknown[] }) => boolean {
   return (query) =>
-    isFleetKey(query.queryKey) &&
+    isKindedQueryKey(query.queryKey) &&
     selectors.some((s) => selectorMatches(s, query.queryKey, commandScope));
 }

package/src/kernel/resource.ts

@@ -23,6 +23,13 @@ export interface CommandDescriptor<Input, Payload, ID = never> {
   readonly __id?: ID;
   /** 跨资源失效声明（纯数据）；默认与命令执行的 ctx scope 相交 */
   invalidates?: ReadonlyArray<QuerySelector>;
+  /**
+   * 存量键失效桥（迁移期）：ok 后按返回的前缀键失效（TanStack 前缀语义）。
+   * 与 invalidates（kit 键声明）互补——存量 react-query 键（如 ["groups",
+   * projectId]）无 fleet 键形，selector 匹配结构性不覆盖，声明面在此。
+   * defineResource 把 spec.legacyKeys 注入为各命令缺省；descriptor 自带优先。
+   */
+  legacyKeys?: (scope: ResourceScope) => ReadonlyArray<readonly unknown[]>;
   /** 结果覆写钩子：命令作者裁决协议层状态的领域语义（delete 已删 → 幂等 ok 等） */
   treatAs?: Partial<Record<"not-found" | "forbidden", CommandResult<Payload>>>;
   /**
@@ -40,9 +47,13 @@ export interface SubscriptionDescriptor<Params, Frame> {
 
 export type CommandsRecord<ID> = Record<string, CommandDescriptor<any, any, ID>>;
 
-/** defineResource 注入 __resource 后的命令映射（逐键保留具体 Input/Payload 类型） */
+/** defineResource 注入 __resource/legacyKeys 后的命令映射（逐键保留具体 Input/Payload 类型） */
 export type AttachedCommands<C> = {
-  [K in keyof C]: C[K] & { __resource?: ResourceName };
+  [K in keyof C]: C[K] & {
+    __resource?: ResourceName;
+    /** defineResource 从 spec.legacyKeys 注入（descriptor 自带优先）；类型面恒可选 */
+    legacyKeys?: (scope: ResourceScope) => ReadonlyArray<readonly unknown[]>;
+  };
 };
 export type SubsRecord = Record<string, SubscriptionDescriptor<any, any>>;
 
@@ -57,6 +68,11 @@ export interface ResourceSpec<
   getId?: (row: T) => ID;
   /** scope 键名（如 ["projectId"]），scoped() 约定用 */
   scope?: ReadonlyArray<string>;
+  /**
+   * 存量键失效桥（迁移期）：该资源命令 ok 后额外失效的 react-query 前缀键。
+   * 闭包收命令 ctx scope——消费方可把 scope 值嵌进键（如 ["groups", scope.projectId]）。
+   */
+  legacyKeys?: (scope: ResourceScope) => ReadonlyArray<readonly unknown[]>;
 
   collection?: (
     q: CollectionQuery,
@@ -83,6 +99,7 @@ export interface Resource<
   readonly name: ResourceName;
   readonly getId?: (row: T) => ID;
   readonly scope?: ReadonlyArray<string>;
+  readonly legacyKeys?: (scope: ResourceScope) => ReadonlyArray<readonly unknown[]>;
 
   readonly collection?: (
     q: CollectionQuery,
@@ -105,7 +122,24 @@ export interface Resource<
 /**
  * 定义一个实体/流族的交互面（三原语各自可选）。
  * 泛型 C/S 逐键保留具体 CommandDescriptor/SubscriptionDescriptor——不被擦成 any。
+ *
+ * 重载注：commands 在 spec 上出现时返回类型收窄为必填（消消费方 `commands!`——
+ * 演示/demo 的 `commands?.` 习惯保留在无 commands 的形态）。
  */
+export function defineResource<
+  T,
+  ID,
+  C extends CommandsRecord<ID> = Record<string, never>,
+  S extends SubsRecord = Record<string, never>,
+>(
+  spec: ResourceSpec<T, ID, C, S> & { commands: C },
+): Resource<T, ID, C, S> & { readonly commands: AttachedCommands<C> };
+export function defineResource<
+  T,
+  ID,
+  C extends CommandsRecord<ID> = Record<string, never>,
+  S extends SubsRecord = Record<string, never>,
+>(spec: ResourceSpec<T, ID, C, S>): Resource<T, ID, C, S>;
 export function defineResource<
   T,
   ID,
@@ -114,14 +148,19 @@ export function defineResource<
 >(spec: ResourceSpec<T, ID, C, S>): Resource<T, ID, C, S> {
   if (!/^[a-z][a-z0-9-]*$/.test(spec.name)) {
     throw new Error(
-      `fleet-ui: resource name "${spec.name}" must be kebab-case (it lives in query keys and URL diagnostics)`,
+      `@lynx-go/ui-kit: resource name "${spec.name}" must be kebab-case (it lives in query keys and URL diagnostics)`,
     );
   }
   const commands = spec.commands
     ? (Object.fromEntries(
         Object.entries(spec.commands).map(([verb, descriptor]) => [
           verb,
-          { ...descriptor, __resource: spec.name as ResourceName },
+          {
+            ...descriptor,
+            __resource: spec.name as ResourceName,
+            // 存量键桥缺省注入：资源级声明对全部命令生效，descriptor 自带优先
+            legacyKeys: descriptor.legacyKeys ?? spec.legacyKeys,
+          },
         ]),
       ) as AttachedCommands<C>)
     : undefined;

package/src/react/bindings.ts

@@ -16,6 +16,7 @@ import {
 } from "../kernel";
 import type { FlatPatch, QuerySearchSchema } from "../schema";
 import { batchQueryOptions, collectionQueryOptions, recordQueryOptions } from "./options";
+import { scopeReady, useContextScope } from "./scope";
 
 /**
  * useCollection —— collection Query ↔ URL ↔ Table 的绑定。
@@ -88,9 +89,15 @@ export function useCollection<T, ID, C extends CommandsRecord<ID>, S extends Sub
     replace?: boolean;
   }) => Promise<void>;
 
-  const target = options.scope ? scoped(resource, options.scope) : resource;
+  // scope 缺省链：显式传入 > ResourceScopeProvider context > 无 scope。
+  const contextScope = useContextScope();
+  const scope = options.scope ?? contextScope;
+  const target = scope ? scoped(resource, scope) : resource;
   const query = options.search.decode(rawSearch);
   const keepPrevious = options.query?.keepPrevious !== false;
+  // 未就绪自动停用（fail-safe）：资源声明的 scope 键缺值时不启用——
+  // 消费方不再需要逐页 enabled 守卫，也堵住"未就绪空段"污染无 scope 键。
+  const enabled = scopeReady(resource, scope) ? options.query?.enabled : false;
 
   const result = useQuery<Segment<T>, ApiError>({
     ...collectionQueryOptions(target, query, {
@@ -98,7 +105,7 @@ export function useCollection<T, ID, C extends CommandsRecord<ID>, S extends Sub
       ...(options.query?.refetchInterval !== undefined
         ? { refetchInterval: options.query.refetchInterval }
         : {}),
-      ...(options.query?.enabled !== undefined ? { enabled: options.query.enabled } : {}),
+      ...(enabled !== undefined ? { enabled } : {}),
     }),
     ...(keepPrevious ? { placeholderData: keepPreviousData } : {}),
   });
@@ -188,11 +195,13 @@ export function useRecord<T, ID, C extends CommandsRecord<ID>, S extends SubsRec
   resource: Resource<T, ID, C, S>,
   options: { id: ID | undefined; scope?: ResourceScope; query?: { staleTime?: number } },
 ): RecordHandle<T> {
-  const target = options.scope ? scoped(resource, options.scope) : resource;
+  const scope = options.scope ?? useContextScope();
+  const target = scope ? scoped(resource, scope) : resource;
   const result = useQuery<T, ApiError>({
     ...recordQueryOptions(target, options.id, {
       ...(options.query?.staleTime !== undefined ? { staleTime: options.query.staleTime } : {}),
     }),
+    ...(scopeReady(resource, scope) ? {} : { enabled: false }),
   });
   return {
     data: result.data,
@@ -213,11 +222,13 @@ export function useBatch<T, ID, C extends CommandsRecord<ID>, S extends SubsReco
   ids: ReadonlyArray<ID>,
   options: { scope?: ResourceScope; query?: { staleTime?: number } } = {},
 ): BatchHandle<T, ID> {
-  const target = options.scope ? scoped(resource, options.scope) : resource;
+  const scope = options.scope ?? useContextScope();
+  const target = scope ? scoped(resource, scope) : resource;
   const result = useQuery<ReadonlyArray<T>, ApiError>({
     ...batchQueryOptions(target, ids, {
       ...(options.query?.staleTime !== undefined ? { staleTime: options.query.staleTime } : {}),
     }),
+    ...(scopeReady(resource, scope) ? {} : { enabled: false }),
   });
   const rows = result.data ?? EMPTY_ROWS;
   const byId = new Map(

package/src/react/command.ts

@@ -1,5 +1,6 @@
 import { useForm } from "@tanstack/react-form";
 import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type { QueryClient } from "@tanstack/react-query";
 import {
   type ApiError,
   type CommandDescriptor,
@@ -9,6 +10,7 @@ import {
   type ResourceScope,
   runCommand,
 } from "../kernel";
+import { useContextScope } from "./scope";
 
 /**
  * useCommand —— Command 原语的绑定（问/令/听的"令"）。
@@ -16,7 +18,9 @@ import {
  * - rejected/conflict 是**结果**（mutation.data），只有失败（网络/401/解码）走 mutation.error；
  * - ok 后执行失效：descriptor.invalidates 声明优先，缺省 = 同资源全部查询（内置动词默认失效）；
  *   selector 默认与命令 ctx scope 相交（project A 的命令不清 project B 的缓存）；
+ *   legacyKeys 桥在此并行执行（存量 react-query 前缀键，迁移期声明面）；
  * - treatAs 裁决在 kernel runCommand 单源完成；
+ * - scope 省略时取 ResourceScopeProvider 的 context 值；
  * - 库不内置 toast：onSettled 回调交消费方（sonner 等）。
  */
 export interface UseCommandOptions<Payload> {
@@ -35,25 +39,37 @@ export interface CommandHandle<Input, Payload> {
   reset(): void;
 }
 
+/** ok 后的失效编排（kit selector 匹配 + legacyKeys 前缀桥）；导出供测试与命令式编排复用。 */
+export function invalidateAfterCommand(
+  queryClient: Pick<QueryClient, "invalidateQueries">,
+  descriptor: CommandDescriptor<any, any, any>,
+  scope: ResourceScope,
+): void {
+  const selectors: ReadonlyArray<QuerySelector> =
+    descriptor.invalidates ??
+    (descriptor.__resource !== undefined ? [{ resource: descriptor.__resource }] : []);
+  if (selectors.length > 0) {
+    void queryClient.invalidateQueries({
+      predicate: invalidationPredicate(selectors, scope),
+    });
+  }
+  for (const key of descriptor.legacyKeys?.(scope) ?? []) {
+    void queryClient.invalidateQueries({ queryKey: key });
+  }
+}
+
 export function useCommand<Input, Payload, ID = never>(
   descriptor: CommandDescriptor<Input, Payload, ID>,
   options: UseCommandOptions<Payload> = {},
 ): CommandHandle<Input, Payload> {
   const queryClient = useQueryClient();
-  const scope = options.scope ?? {};
+  const scope = options.scope ?? useContextScope() ?? {};
 
   const mutation = useMutation<CommandResult<Payload>, ApiError, Input>({
     mutationFn: (input) => runCommand(descriptor, input, scope),
     onSuccess: (result) => {
       if (result.status === "ok") {
-        const selectors: ReadonlyArray<QuerySelector> =
-          descriptor.invalidates ??
-          (descriptor.__resource !== undefined ? [{ resource: descriptor.__resource }] : []);
-        if (selectors.length > 0) {
-          void queryClient.invalidateQueries({
-            predicate: invalidationPredicate(selectors, scope),
-          });
-        }
+        invalidateAfterCommand(queryClient, descriptor, scope);
       }
       options.onSettled?.(result, null);
     },

package/src/react/index.ts

@@ -14,6 +14,7 @@ export {
 } from "./bindings";
 export {
   type CommandHandle,
+  invalidateAfterCommand,
   type UseCommandFormOptions,
   type UseCommandOptions,
   useCommand,
@@ -43,4 +44,9 @@ export {
   type PreferenceCodec,
   usePreference,
 } from "./preferences";
+export {
+  ResourceScopeProvider,
+  scopeReady,
+  useContextScope,
+} from "./scope";
 export { type UseSubscriptionOptions, useSubscription } from "./subscription";

package/src/react/options.ts

@@ -36,7 +36,7 @@ export function collectionQueryOptions<T, ID, C extends CommandsRecord<ID>, S ex
   const collection = resource.collection;
   if (!collection) {
     throw new Error(
-      `fleet-ui: resource "${String(resource.name)}" has no collection query — did you mean to wrap it with clientCollection()?`,
+      `@lynx-go/ui-kit: resource "${String(resource.name)}" has no collection query — did you mean to wrap it with clientCollection()?`,
     );
   }
   return {
@@ -59,7 +59,7 @@ export function recordQueryOptions<T, ID, C extends CommandsRecord<ID>, S extend
 } {
   const record = resource.record;
   if (!record) {
-    throw new Error(`fleet-ui: resource "${String(resource.name)}" has no record query`);
+    throw new Error(`@lynx-go/ui-kit: resource "${String(resource.name)}" has no record query`);
   }
   if (id === undefined)
     return {
@@ -89,7 +89,7 @@ export function batchQueryOptions<T, ID, C extends CommandsRecord<ID>, S extends
 } {
   const batch = resource.batch;
   if (!batch) {
-    throw new Error(`fleet-ui: resource "${String(resource.name)}" has no batch query`);
+    throw new Error(`@lynx-go/ui-kit: resource "${String(resource.name)}" has no batch query`);
   }
   const scope = scopeOf(resource);
   return {

package/src/react/scope.tsx

@@ -0,0 +1,43 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { ResourceScope } from "../kernel";
+
+/**
+ * ResourceScopeProvider —— scope 线程的 Context 单源（scoped() 约定的绑定侧）。
+ *
+ * 绑定（useCollection/useRecord/useBatch/useCommand/useCommandForm/useSubscription）
+ * 在调用点省略 scope 时从这里取值；显式传入的 scope 优先（逃生舱）。
+ * 消费方典型形态：应用根把"当前项目"等作用域单源挂进 Provider，页面绑定
+ * 不再逐处传 scope 字面量。
+ *
+ * 未就绪语义：资源声明了 scope 键（spec.scope）而生效 scope 中该键为
+ * undefined 时，查询绑定自动停用（enabled: false）——取代消费方逐页的
+ * enabled 守卫；"未就绪"查询不启用，也就不会产出"无 scope 键"下的空段
+ * 缓存（canonicalScope 丢 undefined 的同键污染面随之关闭）。
+ */
+const ResourceScopeContext = createContext<ResourceScope | undefined>(undefined);
+
+export function ResourceScopeProvider({
+  value,
+  children,
+}: {
+  value: ResourceScope;
+  children: ReactNode;
+}) {
+  return <ResourceScopeContext value={value}>{children}</ResourceScopeContext>;
+}
+
+/** @internal 绑定层共用的 context 读取（省略 scope 时的缺省源）。 */
+export function useContextScope(): ResourceScope | undefined {
+  return useContext(ResourceScopeContext);
+}
+
+/**
+ * 资源声明的 scope 键是否全部就绪（未声明 = 恒就绪）。
+ * 查询绑定用它做自动停用；显式 query.enabled 无法越过未就绪（fail-safe）。
+ */
+export function scopeReady(
+  resource: { scope?: ReadonlyArray<string> },
+  scope: ResourceScope | undefined,
+): boolean {
+  return (resource.scope ?? []).every((key) => scope?.[key] !== undefined);
+}

package/src/react/subscription.ts

@@ -7,6 +7,7 @@ import type {
   SubscriptionPolicy,
   Transport,
 } from "../kernel";
+import { useContextScope } from "./scope";
 
 /**
  * useSubscription —— Subscription 原语的绑定（问/令/听的"听"）。
@@ -73,8 +74,10 @@ export function useSubscription<Params, F>(
   const isDescriptor =
     typeof (source as { policy?: unknown }).policy === "object" &&
     typeof source.open === "function";
+  // scope 缺省链同查询/命令绑定：显式传入 > ResourceScopeProvider context > 空
+  const scope = options.scope ?? useContextScope() ?? {};
   const paramsKey = options.params === undefined ? "" : JSON.stringify(options.params);
-  const scopeKey = JSON.stringify(options.scope ?? {});
+  const scopeKey = JSON.stringify(scope);
   const policy = options.policy ?? descriptor.policy;
   const policyKey = JSON.stringify(policy ?? null);
   const anchorKey = options.cursor === undefined ? "\u0000waiting" : `\u0000${options.cursor}`;
@@ -82,7 +85,7 @@ export function useSubscription<Params, F>(
   // biome-ignore lint/correctness/useExhaustiveDependencies: descriptor.open/options.* 由 paramsKey/scopeKey 记忆——params 对象标识每渲染变化不应重开流
   const transport = useMemo<Transport<F>>(() => {
     if (!isDescriptor) return source as Transport<F>;
-    return descriptor.open(options.params as Params, options.scope ?? {});
+    return descriptor.open(options.params as Params, scope);
   }, [source, isDescriptor, paramsKey, scopeKey]);
 
   const [engine, setEngine] = useState<SubscriptionEngine<F> | null>(null);

package/src/schema/codec.ts

@@ -50,7 +50,7 @@ export type FlatPatch = Partial<
 export interface StandardSchemaV1<Input = unknown, Output = Input> {
   "~standard": {
     version: 1;
-    vendor: "fleet-ui";
+    vendor: "@lynx-go/ui-kit";
     validate(value: Input): { value: Output };
   };
 }
@@ -123,7 +123,7 @@ export function collectionQuerySchema(spec: QuerySchemaSpec = {}): QuerySearchSc
     );
     if (!isText) {
       throw new Error(
-        "fleet-ui: predicate with OR is not URL-serializable — keep it in local state or a custom search param",
+        "@lynx-go/ui-kit: predicate with OR is not URL-serializable — keep it in local state or a custom search param",
       );
     }
     return leaves;
@@ -211,7 +211,7 @@ export function collectionQuerySchema(spec: QuerySchemaSpec = {}): QuerySearchSc
       return {
         "~standard": {
           version: 1,
-          vendor: "fleet-ui",
+          vendor: "@lynx-go/ui-kit",
           validate(value: unknown) {
             return { value: normalize(value) };
           },

package/src/schema/filters.ts

@@ -0,0 +1,59 @@
+import type { FieldKey, Operator, Predicate } from "../kernel";
+
+/**
+ * 谓词 ↔ 过滤值的纯函数层（FilterBar 块与消费方过滤 UI 共用的投影）。
+ *
+ * 背景：CollectionQuery 的谓词是 AND/OR 树，但过滤 UI 的真身几乎总是
+ * "field → 单值"（下拉/输入框）。本层把两者间的样板（叶子抽取、归一化
+ * 拼装）收敛为纯函数——FilterBar 变薄壳，消费方不再逐页手写 filtersOf
+ * 与三元归一化。
+ */
+
+export interface FilterLeaf {
+  field: string;
+  op: Operator;
+  value: string | number | boolean | ReadonlyArray<string>;
+}
+
+/**
+ * 过滤叶子抽取：展开 AND 树（与 decode 产物同形）返回全部叶子。
+ * OR 分支（textPredicate 的 any 形）同样展开为叶子——值读取语义下
+ * OR 树仅由文本搜索产生；一般 OR 树不进 URL（codec 裁决），此函数
+ * 只作投影不做序列化，保持宽容。
+ */
+export function filterLeaves(predicate: Predicate | null | undefined): ReadonlyArray<FilterLeaf> {
+  if (predicate === null || predicate === undefined) return [];
+  if ("field" in predicate) return [predicate];
+  if ("all" in predicate) return predicate.all.flatMap(filterLeaves);
+  return predicate.any.flatMap(filterLeaves);
+}
+
+/**
+ * field → 单值投影（过滤 UI 的读路径）：每字段取叶子值，多叶子时后者
+ * 覆盖（与单选下拉语义一致）。数组值字段（in 算子）不出现在单值投影中
+ * ——需要时用 filterLeaves 直读。
+ */
+export function filterValues(
+  predicate: Predicate | null | undefined,
+): Record<string, string | number | boolean> {
+  const out: Record<string, string | number | boolean> = {};
+  for (const leaf of filterLeaves(predicate)) {
+    if (typeof leaf.value !== "object") out[leaf.field as string] = leaf.value;
+  }
+  return out;
+}
+
+/**
+ * 叶子清单 → 规范谓词（过滤 UI 的写路径）：0 → null（清除）、
+ * 1 → 裸叶、n → AND。与 setPredicate 配合使用，取代手写三元归一化。
+ */
+export function predicateOf(parts: ReadonlyArray<Predicate>): Predicate | null {
+  if (parts.length === 0) return null;
+  if (parts.length === 1) return parts[0] as Predicate;
+  return { all: [...parts] };
+}
+
+/** 便捷构造：等值过滤叶（过滤 UI 的最常见形态）。 */
+export function eqFilter(field: FieldKey, value: string | number | boolean): Predicate {
+  return { field, op: "eq", value };
+}

package/src/schema/index.ts

@@ -7,3 +7,10 @@ export {
   type QuerySearchSchema,
   type StandardSchemaV1,
 } from "./codec";
+export {
+  eqFilter,
+  type FilterLeaf,
+  filterLeaves,
+  filterValues,
+  predicateOf,
+} from "./filters";

package/src/testing/harness.tsx

@@ -0,0 +1,88 @@
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import {
+  createMemoryHistory,
+  createRootRoute,
+  createRoute,
+  createRouter,
+  RouterProvider,
+} from "@tanstack/react-router";
+import { act, render, type RenderOptions } from "@testing-library/react";
+import type { ReactElement } from "react";
+import type { ResourceScope } from "../kernel";
+import { ResourceScopeProvider } from "../react/scope";
+import type { QuerySearchSchema } from "../schema";
+
+/**
+ * /testing —— 消费方测试 harness（页面级渲染 + URL/Query/Scope 三上下文一体接线）。
+ *
+ * 消费方自建的样板（TestRouter + SearchProbe + per-test QueryClient + scope
+ * Provider 包装）在此单源：useCollection 系绑定需要全部三上下文，缺一即假绿。
+ * mock 面建议从"数据源"上移到"resource 动词"（defineResource 的 collection/
+ * commands 覆写）——本 harness 不绑 mock 方案。
+ */
+
+export interface RenderWithFleetOptions extends Omit<RenderOptions, "wrapper"> {
+  /** 挂载 ui 的路由路径（默认 "/"；支持 $param 段，值由 pathname 给出） */
+  path?: string;
+  /** 初始 search（经 searchSchema 归一——与真实 validateSearch 同路，非裸对象） */
+  search?: Record<string, unknown>;
+  /** 与被测页面共用的 schema 实例；给定时接线 validateSearch（不传则 search 原样） */
+  searchSchema?: QuerySearchSchema;
+  scope?: ResourceScope;
+  queryClient?: QueryClient;
+}
+
+export interface FleetRenderResult {
+  /** 解析后的 search 对象（断言用解析值，不读原始 query 串——TanStack 数组方言） */
+  getSearch(): Record<string, unknown>;
+  queryClient: QueryClient;
+}
+
+export async function renderWithFleet(
+  ui: ReactElement,
+  options: RenderWithFleetOptions = {},
+): Promise<FleetRenderResult> {
+  const queryClient =
+    options.queryClient ?? new QueryClient({ defaultOptions: { queries: { retry: false } } });
+  const path = options.path ?? "/";
+  const { searchSchema, search, scope, ...renderOptions } = options;
+  const initialSearch = search ?? {};
+
+  const validateSearch = searchSchema
+    ? ((input: unknown) =>
+        searchSchema.toSearchSchema()["~standard"].validate(input).value) as never
+    : undefined;
+
+  const rootRoute = createRootRoute({ validateSearch });
+  const pageRoute = createRoute({
+    getParentRoute: () => rootRoute,
+    path,
+    component: () => (
+      <ResourceScopeProvider value={scope ?? {}}>
+        <QueryClientProvider client={queryClient}>{ui}</QueryClientProvider>
+      </ResourceScopeProvider>
+    ),
+  });
+  const routeTree = rootRoute.addChildren([pageRoute]);
+  // initialEntries 只收字符串——按 TanStack 默认 search 方言（每值 JSON 编码）
+  // 自拼 query 串，与真实 URL 解析同路（数组=单键 JSON、数字不落字符串）。
+  const qs = Object.entries(initialSearch)
+    .filter(([, v]) => v !== undefined)
+    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(JSON.stringify(v))}`)
+    .join("&");
+  const router = createRouter({
+    routeTree,
+    history: createMemoryHistory({
+      initialEntries: [path + (qs ? `?${qs}` : "")],
+    }),
+  });
+
+  const rendered = render(<RouterProvider router={router} />, renderOptions);
+  // RouterProvider 首提交异步——冲刷到稳定再交还断言（torchwood TestRouter 同坑）
+  await act(async () => {});
+
+  return {
+    getSearch: () => router.state.location.search as Record<string, unknown>,
+    queryClient,
+  };
+}

package/src/testing/index.ts

@@ -0,0 +1,5 @@
+export {
+  type FleetRenderResult,
+  type RenderWithFleetOptions,
+  renderWithFleet,
+} from "./harness";