@arrai-innovations/reactive-helpers 23.0.0 → 23.0.2

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arrai-innovations/reactive-helpers",
-  "version": "23.0.0",
+  "version": "23.0.2",
   "description": "VueJS 3 utility composition functions to help manipulate objects and lists.",
   "main": "index.js",
   "type": "module",
@@ -44,7 +44,7 @@
   "devDependencies": {
     "@arrai-innovations/commitlint-config": "^3.0.0",
     "@arrai-innovations/diction-md": "^1.0.0",
-    "@arrai-innovations/vitepress-theme": "1.0.1",
+    "@arrai-innovations/vitepress-theme": "^1.0.2",
     "@commitlint/cli": "^21.2.1",
     "@eslint/js": "9.39.4",
     "@godaddy/dmd": "^1.0.4",
@@ -89,11 +89,16 @@
   },
   "scripts": {
     "benchmark": "vitest bench --run",
+    "benchmark:ci": "pnpm benchmark:list:ci && pnpm benchmark:stream:ci && pnpm benchmark:layers:ci && pnpm benchmark:observed:ci",
     "benchmark:list": "vitest bench --run tests/benchmarks/listPush.bench.js",
     "benchmark:list:ci": "vitest bench --run tests/benchmarks/listPush.bench.js --outputJson benchmark-results/list-push.json",
     "benchmark:check": "node check_benchmark.js",
     "benchmark:layers": "vitest bench --run tests/benchmarks/listLayers.bench.js",
+    "benchmark:layers:ci": "vitest bench --run tests/benchmarks/listLayers.bench.js --outputJson benchmark-results/list-layers.json",
+    "benchmark:observed": "vitest bench --run tests/benchmarks/listObserved.bench.js",
+    "benchmark:observed:ci": "vitest bench --run tests/benchmarks/listObserved.bench.js --outputJson benchmark-results/list-observed.json",
     "benchmark:stream": "vitest bench --run tests/benchmarks/listStream.bench.js",
+    "benchmark:stream:ci": "vitest bench --run tests/benchmarks/listStream.bench.js --outputJson benchmark-results/list-stream.json",
     "test": "vitest",
     "eslint": "eslint --fix index.js config/**/*.js tests/**/*.js use/**/*.js utils/**/*.js",
     "prettier": "prettier --write .",

package/types/tests/benchmarks/fixtures.d.ts

@@ -46,7 +46,7 @@ export namespace populatedRules {
     export { orderByRules_1 as orderByRules };
     export namespace relatedObjectsRules_1 {
         namespace org {
-            export let pkKey: string;
+            export let fkKey: string;
             export { relatedOrganizations as objects };
         }
     }

package/types/tests/benchmarks/listObserved.bench.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/benchmarks/reviewFixtures.d.ts

@@ -0,0 +1,102 @@
+/** How many entries each generated lookup collection holds. */
+export const lookupSize: 13;
+export function makeLookup(index: number): import("../../use/listInstance.js").ObjectsByPk;
+/** Lookup collection for the array-valued rule, which resolves a list of foreign keys per record. */
+export const tagLookup: import("../../use/listInstance.js").ObjectsByPk;
+/** The order the array-valued rule sorts its resolved tags into. */
+export const tagOrder: string[];
+export function makeRelatedRules(ruleCount: number, includeArrayRule?: boolean): import("../../use/listRelated.js").ListRelatedRules;
+export function makeCalculatedRules(ruleCount: number, relatedRuleCount: number): {
+    [rule: string]: (object: object, related: object, calculated: object) => any;
+};
+export function makeReviewRows(count: number, start?: number, fkCount?: number): object[];
+export function makeOrderByRules(sortOn: "none" | "plain" | "related" | "calculated"): import("../../use/listSort.js").OrderByRule[];
+export function makeReviewList({ relatedRuleCount, calculatedRuleCount, sortOn, includeArrayRule, filter, sortThrottleWait, }?: ReviewListOptions): ReturnType<typeof useList>;
+export function composeReviewStack({ relatedRuleCount, calculatedRuleCount, sortOn, includeArrayRule, filter, sortThrottleWait, }?: ReviewListOptions): {
+    states: {
+        [layer: string]: object;
+    };
+    push: (objects: object[]) => void;
+    stop: () => void;
+};
+export namespace readChannels {
+    let collection: {
+        [channel: string]: (state: object) => void;
+    };
+    let record: {
+        [channel: string]: (state: object, pk: string) => void;
+    };
+}
+export function attachRenderObservers(state: object, { collectionChannels, recordChannels }?: RenderObserverOptions): {
+    sync: () => void;
+    stop: () => void;
+    counts: {
+        [channel: string]: ChannelCounts;
+    };
+    totals: () => {
+        effects: number;
+        runs: number;
+        triggers: number;
+    };
+    reset: () => void;
+};
+/**
+ * The shape of the review list to build.
+ */
+export type ReviewListOptions = {
+    /**
+     * How many related rules the list carries.
+     */
+    relatedRuleCount?: number;
+    /**
+     * How many calculated rules the list carries.
+     */
+    calculatedRuleCount?: number;
+    /**
+     * Which value the sort orders on.
+     */
+    sortOn?: "none" | "plain" | "related" | "calculated";
+    /**
+     * Whether the related rules include an array-valued rule.
+     */
+    includeArrayRule?: boolean;
+    /**
+     * Whether an allowed filter is active.
+     */
+    filter?: boolean;
+    /**
+     * The sort throttle, in milliseconds.
+     */
+    sortThrottleWait?: number;
+};
+/**
+ * Which channels observe the list.
+ */
+export type RenderObserverOptions = {
+    /**
+     * Names from `readChannels.collection` to attach once.
+     */
+    collectionChannels?: string[];
+    /**
+     * Names from `readChannels.record` to attach per record.
+     */
+    recordChannels?: string[];
+};
+/**
+ * What one channel's effects have done.
+ */
+export type ChannelCounts = {
+    /**
+     * How many effects the channel has attached.
+     */
+    effects: number;
+    /**
+     * How many times those effects have evaluated.
+     */
+    runs: number;
+    /**
+     * How many times those effects have been notified.
+     */
+    triggers: number;
+};
+import { useList } from "../../use/list.js";

package/types/tests/unit/use/listLoadingPropagation.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/listMembershipWatch.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/listNotifications.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/tests/unit/use/listObjectsVersion.spec.d.ts

@@ -0,0 +1 @@
+export {};

package/types/use/listCalculated.d.ts

@@ -64,6 +64,7 @@
  * @typedef {object} ListCalculatedProperties - The properties for the list computed composition function.
  * @property {ListCalculatedState} state - The state for the list calculated property.
  * @property {ListCalculatedParentState} parentState - The parent state object.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - Stops composition's effects and cleans up resources.
  */
 /**
@@ -221,6 +222,10 @@ export type ListCalculatedProperties = {
      * The parent state object.
      */
     parentState: ListCalculatedParentState;
+    /**
+     * Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
+     */
+    watchMembershipChanged: import("../utils/watches.js").WatchMembershipChanged;
     /**
      * Stops composition's effects and cleans up resources.
      */

package/types/use/listFilter.d.ts

@@ -51,6 +51,7 @@
  * @typedef {object} ListFilterProperties - The properties of a list filter, including its state and associated Vue composition API utilities.
  * @property {ListFilterState} state - The reactive state managing the filter logic and results.
  * @property {ListFilterParentState} parentState - The state of the list being filtered.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - A function to stop the effect scope and clean up resources.
  */
 /**
@@ -166,6 +167,10 @@ export type ListFilterProperties = {
      * The state of the list being filtered.
      */
     parentState: ListFilterParentState;
+    /**
+     * Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
+     */
+    watchMembershipChanged: import("../utils/watches.js").WatchMembershipChanged;
     /**
      * A function to stop the effect scope and clean up resources.
      */

package/types/use/listInstance.d.ts

@@ -54,7 +54,7 @@
  * @property {object} params - Arguments passed to the server for listing operations.
  * @property {ObjectsMap} objectsMap - The map of objects stored by their pks.
  * @property {ObjectsByPk} objects - The list objects stored by their pks.
- * @property {number} objectsVersion - Increments when the set of object keys changes.
+ * @property {number} objectsVersion - Increments when this layer's set of object keys changes. Each layer that narrows membership publishes its own, so the value belongs to the state reporting it and is not comparable with another layer's. Watch it rather than reading it, and prefer `watchMembershipChanged`, which carries the same signal without exposing how it is counted.
  * @property {ListOrder} order - The order of objects in the list.
  * @property {ObjectsInOrder} objectsInOrder - The objects in the order specified by the list.
  * @property {import('vue').ShallowReactive<PaginateInfo>} paginateInfo - Pagination information for the list.
@@ -98,6 +98,7 @@
  * @property {(args: {action: string, pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|boolean|null>} executeAction - Initiates an action on all objects in the list, returning the response, or null if the action failed. The promise carries a `cancel` method when the handler's promise did.
  * @property {(info: PaginateInfo) => void} setPaginateInfo - The method to update pagination information.
  * @property {(total: ColumnTotals) => void} setColumnTotals - The method to update column totals.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  */
 /**
  * @typedef {ListInstanceMyFunctions & Pick<import('./loadingError.js').LoadingErrorStatus, "clearError">} ListInstanceFunctions - The methods contributed by the list instance, including its CRUD operations plus clearError.
@@ -321,7 +322,7 @@ export type ListInstanceRawMyState = {
      */
     objects: ObjectsByPk;
     /**
-     * Increments when the set of object keys changes.
+     * Increments when this layer's set of object keys changes. Each layer that narrows membership publishes its own, so the value belongs to the state reporting it and is not comparable with another layer's. Watch it rather than reading it, and prefer `watchMembershipChanged`, which carries the same signal without exposing how it is counted.
      */
     objectsVersion: number;
     /**
@@ -436,6 +437,10 @@ export type ListInstanceMyFunctions = {
      * The method to update column totals.
      */
     setColumnTotals: (total: ColumnTotals) => void;
+    /**
+     * Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
+     */
+    watchMembershipChanged: import("../utils/watches.js").WatchMembershipChanged;
 };
 /**
  * The methods contributed by the list instance, including its CRUD operations plus clearError.

package/types/use/listRelated.d.ts

@@ -59,6 +59,7 @@
  * @typedef {object} ListRelatedProperties - The properties for the list related composition function.
  * @property {ListRelatedState} state - The state for the list related property.
  * @property {ListRelatedParentState} parentState - The parent state object.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - Stops all effects of the list related property.
  */
 /**
@@ -289,6 +290,10 @@ export type ListRelatedProperties = {
      * The parent state object.
      */
     parentState: ListRelatedParentState;
+    /**
+     * Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
+     */
+    watchMembershipChanged: import("../utils/watches.js").WatchMembershipChanged;
     /**
      * Stops all effects of the list related property.
      */

package/types/use/listSearch.d.ts

@@ -67,6 +67,7 @@
  * @typedef {object} ListSearchProperties - The properties on a list search instance.
  * @property {ListSearchState} state - The state.
  * @property {import('./search.js').SearchInstance} textSearchIndex - The text search index.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - Stops the effect scope and cleans up resources.
  */
 /**
@@ -253,6 +254,10 @@ export type ListSearchProperties = {
      * The text search index.
      */
     textSearchIndex: import("./search.js").SearchInstance;
+    /**
+     * Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
+     */
+    watchMembershipChanged: import("../utils/watches.js").WatchMembershipChanged;
     /**
      * Stops the effect scope and cleans up resources.
      */

package/types/use/listSort.d.ts

@@ -55,6 +55,7 @@ export function setListSortDefaultOptions({ sortThrottleWait }: {
  * @typedef {object} ListSortProperties - The properties available on a list sort instance.
  * @property {ListSortState} state - The reactive state for the list sort.
  * @property {ListSortParentState} parentState - The parent state.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - A function to stop the effect scope and clean up resources.
  */
 /**
@@ -183,6 +184,10 @@ export type ListSortProperties = {
      * The parent state.
      */
     parentState: ListSortParentState;
+    /**
+     * Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
+     */
+    watchMembershipChanged: import("../utils/watches.js").WatchMembershipChanged;
     /**
      * A function to stop the effect scope and clean up resources.
      */

package/types/use/listSubscription.d.ts

@@ -33,6 +33,7 @@
  * @property {import('./listInstance.js').ListInstance} listInstance - The list instance used by the subscription.
  * @property {import('./cancellableIntent.js').CancellableIntent} listIntent - The `CancellableIntent` instance managing if the list should be (re)fetched.
  * @property {import('./cancellableIntent.js').CancellableIntent} subscribeIntent - The `CancellableIntent` instance managing if the subscription should be (un)subscribed.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  */
 /**
  * @typedef {ListSubscriptionFunctions & ListSubscriptionProperties} ListSubscription - An instance of a list subscription, returned by `useListSubscription`.
@@ -184,6 +185,10 @@ export type ListSubscriptionProperties = {
      * The `CancellableIntent` instance managing if the subscription should be (un)subscribed.
      */
     subscribeIntent: import("./cancellableIntent.js").CancellableIntent;
+    /**
+     * Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
+     */
+    watchMembershipChanged: import("../utils/watches.js").WatchMembershipChanged;
 };
 /**
  * An instance of a list subscription, returned by `useListSubscription`.

package/types/utils/watches.d.ts

@@ -1,3 +1,33 @@
+/**
+ * @module utils/watches.js
+ * @description
+ *
+ * A collection of utility classes and functions for managing Vue.js watchers.
+ *
+ */
+/**
+ * @callback WatchMembershipChanged - Calls back when a list layer's set of object keys changes.
+ *  Registers in the effect scope active where it is called, not in the layer's own scope, so the
+ *  returned handle and the surrounding scope own the watcher. Stopping the layer does not dispose it,
+ *  because the layer never owned it; it only silences it, since a stopped layer publishes nothing
+ *  further. Stop it through the returned handle or through the enclosing scope.
+ *  The callback takes no arguments: it reports that membership moved, not what it moved to. Read the
+ *  layer's collection views for that.
+ * @param {() => void} callback - Called after the layer's set of object keys changes.
+ * @param {import('vue').WatchOptions} [options] - Passed through to Vue's `watch`, so `immediate`,
+ *  `flush`, and `once` all behave as they do there.
+ * @returns {import('vue').WatchHandle} - Stops the watcher.
+ */
+/**
+ * Builds a layer's membership watcher over the counter that layer publishes.
+ *
+ * @internal
+ * @param {{objectsVersion: number}} state - The layer's own state.
+ * @returns {WatchMembershipChanged} - The watcher registration function for that layer.
+ */
+export function makeMembershipWatcher(state: {
+    objectsVersion: number;
+}): WatchMembershipChanged;
 /**
  * Helper function to get the resulting promise from an AwaitTimeout instance.
  *
@@ -23,13 +53,6 @@ export function doAwaitNot({ obj, prop, ref, couldAlreadyBeFalse, timeout }: {
     couldAlreadyBeFalse?: boolean;
     timeout?: number;
 }): Promise<any>;
-/**
- * @module utils/watches.js
- * @description
- *
- * A collection of utility classes and functions for managing Vue.js watchers.
- *
- */
 /**
  * Provides a mechanism for immediately starting and potentially stopping a Vue.js watcher
  * during its first invocation. This is useful when the need arises to terminate the watch
@@ -152,3 +175,13 @@ export class AwaitNot {
      */
     stop(): void;
 }
+/**
+ * Calls back when a list layer's set of object keys changes.
+ *  Registers in the effect scope active where it is called, not in the layer's own scope, so the
+ *  returned handle and the surrounding scope own the watcher. Stopping the layer does not dispose it,
+ *  because the layer never owned it; it only silences it, since a stopped layer publishes nothing
+ *  further. Stop it through the returned handle or through the enclosing scope.
+ *  The callback takes no arguments: it reports that membership moved, not what it moved to. Read the
+ *  layer's collection views for that.
+ */
+export type WatchMembershipChanged = (callback: () => void, options?: import("vue").WatchOptions) => import("vue").WatchHandle;

package/use/listCalculated.js

@@ -1,4 +1,5 @@
 import { keyDiff } from "../utils/keyDiff.js";
+import { makeMembershipWatcher } from "../utils/watches.js";
 import { loadingCombine } from "../utils/loadingCombine.js";
 import { proxyRunning } from "../utils/proxyRunning.js";
 import isEmpty from "lodash-es/isEmpty.js";
@@ -78,6 +79,7 @@ import { warnWrongSideRuleOptions } from "../utils/relatedCalculatedHelpers.js";
  * @typedef {object} ListCalculatedProperties - The properties for the list computed composition function.
  * @property {ListCalculatedState} state - The state for the list calculated property.
  * @property {ListCalculatedParentState} parentState - The parent state object.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - Stops composition's effects and cleans up resources.
  */
 
@@ -181,6 +183,14 @@ export function useListCalculated(options) {
         running: computed(() => loadingCombine(state.calculatedRunning, parentRunning.value)),
     });
     const calculatedObjectsEffectScopes = {};
+    // Records whose rule bag has not been reconciled against the rules yet. A record arriving with an
+    //  empty bag needs every rule applied. A record already carrying the full rule set needs nothing,
+    //  and rediscovering that by diffing its bag cost one keyDiff per record in the collection, per
+    //  page, along with a pair of refs and an effect scope activation for each.
+    const pendingObjectKeys = new Set();
+    // The rule keys the last reconciliation ran against, so a run can tell which of its two causes woke
+    //  it. Only a rule change touches records that were already reconciled.
+    let previousRuleKeys = [];
 
     function parentStateObjectsWatch() {
         const { addedKeys, removedKeys } = keyDiff(
@@ -188,6 +198,7 @@ export function useListCalculated(options) {
             Object.keys(state.calculatedObjects)
         );
         for (const removedKey of removedKeys) {
+            pendingObjectKeys.delete(removedKey);
             delete state.calculatedObjects[removedKey];
             if (calculatedObjectsEffectScopes[removedKey]) {
                 calculatedObjectsEffectScopes[removedKey].objectScope.stop();
@@ -196,6 +207,7 @@ export function useListCalculated(options) {
         }
         for (const addedKey of addedKeys) {
             state.calculatedObjects[addedKey] = {};
+            pendingObjectKeys.add(addedKey);
         }
         nextTick(() => {
             state.calculatedObjectsParentStateObjectsWatchRunning = false;
@@ -204,7 +216,18 @@ export function useListCalculated(options) {
 
     function calculatedObjectsWatch() {
         const calculatedObjectsRulesIsEmpty = !state.calculatedObjectsRules || isEmpty(state.calculatedObjectsRules);
-        for (const objectKey of Object.keys(state.calculatedObjects)) {
+        const ruleKeys = Object.keys(state.calculatedObjectsRules || {});
+        const { addedKeys: addedRules, removedKeys: removedRules } = keyDiff(ruleKeys, previousRuleKeys, {
+            sameKeys: false,
+        });
+        previousRuleKeys = ruleKeys;
+        // A rule change alters the bag of every record, so it is the only cause that has to walk the
+        //  collection. A page arriving leaves every record already present holding the rule set it
+        //  already held, so only the arrivals have anything to reconcile.
+        const rulesChanged = addedRules.size > 0 || removedRules.size > 0;
+        const objectKeys = rulesChanged ? Object.keys(state.calculatedObjects) : [...pendingObjectKeys];
+        pendingObjectKeys.clear();
+        for (const objectKey of objectKeys) {
             if (!state.calculatedObjects[objectKey]) {
                 state.calculatedObjects[objectKey] = {};
             }
@@ -292,6 +315,7 @@ export function useListCalculated(options) {
     return {
         state,
         parentState,
+        watchMembershipChanged: makeMembershipWatcher(state),
         stop: () => {
             es.stop();
             for (const key of Object.keys(calculatedObjectsEffectScopes)) {

package/use/listFilter.js

@@ -1,5 +1,18 @@
 import { keyDiff } from "../utils/keyDiff.js";
-import { computed, effectScope, isRef, reactive, shallowReadonly, toRef, toRefs, unref, watch } from "vue";
+import { makeMembershipWatcher } from "../utils/watches.js";
+import {
+    computed,
+    effectScope,
+    isRef,
+    reactive,
+    ref,
+    shallowReactive,
+    shallowReadonly,
+    toRef,
+    toRefs,
+    unref,
+    watch,
+} from "vue";
 
 /**
  * Provides reactive filtering functionality for lists within a Vue application. This composable
@@ -63,6 +76,7 @@ import { computed, effectScope, isRef, reactive, shallowReadonly, toRef, toRefs,
  * @typedef {object} ListFilterProperties - The properties of a list filter, including its state and associated Vue composition API utilities.
  * @property {ListFilterState} state - The reactive state managing the filter logic and results.
  * @property {ListFilterParentState} parentState - The state of the list being filtered.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - A function to stop the effect scope and clean up resources.
  */
 
@@ -125,10 +139,12 @@ export function useListFilter({ parentState, allowedFilter, excludedFilter }) {
     const getAllowed = () => (isRef(allowedFilter) ? allowedFilter.value : allowedFilter);
     const getExcluded = () => (isRef(excludedFilter) ? excludedFilter.value : excludedFilter);
 
-    const includeMap = reactive({});
+    // Track entry changes without proxying entries or unwrapping their computed refs.
+    /** @type {Map<import('../config/commonCrud.js').Pk, {scope: import('vue').EffectScope, include: import('vue').ComputedRef<boolean>}>} */
+    const includeMap = shallowReactive(new Map());
 
     function ensureIncludeComputed(pk) {
-        if (!includeMap[pk]) {
+        if (!includeMap.get(pk)) {
             const child = es.run(() => effectScope());
             const include = child.run(() => {
                 const objRef = toRef(parentState.objects, pk);
@@ -155,52 +171,148 @@ export function useListFilter({ parentState, allowedFilter, excludedFilter }) {
                 });
             });
 
-            includeMap[pk] = { scope: child, include };
+            includeMap.set(pk, { scope: child, include });
         }
-        return includeMap[pk].include;
+        return includeMap.get(pk).include;
     }
 
     function disposeIncludeComputed(pk) {
-        const entry = includeMap[pk];
+        const entry = includeMap.get(pk);
         if (entry) {
             entry.scope.stop();
-            delete includeMap[pk];
+            includeMap.delete(pk);
         }
     }
 
+    const isIncluded = (/** @type {import('../config/commonCrud.js').Pk} */ pk) => {
+        const entry = includeMap.get(pk);
+        return entry ? entry.include.value : false;
+    };
+
+    // Cache enumeration separately from per-key reads.
+    /** @type {import('vue').ComputedRef<import('./listInstance.js').ObjectsByPk>} */
+    const includedObjects = computed(() => {
+        /** @type {{[pk: import('../config/commonCrud.js').Pk]: import('./objectInstance.js').ExistingCrudObject}} */
+        const out = {};
+        for (const [pk, o] of Object.entries(parentState.objects)) {
+            if (isIncluded(pk)) {
+                out[pk] = o;
+            }
+        }
+        return out;
+    });
+
+    // This layer's membership is its own: a rule change or a record edit moves it without the parent's
+    //  key set moving, so the parent's objectsVersion does not describe this collection. Own one here
+    //  and keep the property's contract true for every layer downstream, which is what lets them watch
+    //  it instead of enumerating this layer once each.
+    const objectsVersion = ref(0);
+    /** @type {Set<import('../config/commonCrud.js').Pk>} */
+    const includedKeys = new Set();
+
     es.run(() => {
         watch(
             () => parentState.objectsVersion,
             () => {
                 const newVal = Object.keys(parentState.objects);
-                const { addedKeys, removedKeys } = keyDiff(newVal, Object.keys(includeMap));
+                const { addedKeys, removedKeys } = keyDiff(newVal, [...includeMap.keys()]);
+                // Only an arriving or departing record can move membership structurally, so the version
+                //  is settled from those keys rather than from a fresh pass over the collection. This
+                //  runs synchronously, and a full pass here would scale the synchronous half of a page
+                //  with the collection behind it.
+                let moved = false;
                 for (const pk of removedKeys) {
                     disposeIncludeComputed(pk);
+                    moved = includedKeys.delete(pk) || moved;
                 }
                 for (const pk of addedKeys) {
                     ensureIncludeComputed(pk);
+                    if (isIncluded(pk)) {
+                        includedKeys.add(pk);
+                        moved = true;
+                    }
+                }
+                if (moved) {
+                    objectsVersion.value++;
                 }
             },
             { immediate: true, flush: "sync" }
         );
+
+        // A rule change or a record edit flips inclusion without moving any key set, so neither reaches
+        //  the watcher above. Deferred on purpose: includedObjects invalidates once per record written,
+        //  and a synchronous watcher here would rebuild the whole map once per record in a page.
+        watch(includedObjects, (included) => {
+            let moved = false;
+            for (const pk of Object.keys(included)) {
+                if (!includedKeys.has(pk)) {
+                    includedKeys.add(pk);
+                    moved = true;
+                }
+            }
+            if (includedKeys.size !== Object.keys(included).length) {
+                for (const pk of [...includedKeys]) {
+                    if (!(pk in included)) {
+                        includedKeys.delete(pk);
+                        moved = true;
+                    }
+                }
+            }
+            if (moved) {
+                objectsVersion.value++;
+            }
+        });
     });
 
-    /** @type {import('vue').ComputedRef<import('./listInstance.js').ObjectsByPk>} */
-    const objects = computed(() => {
-        // built mutably here, then handed out read-only below
-        /** @type {{[pk: import('../config/commonCrud.js').Pk]: import('./objectInstance.js').ExistingCrudObject}} */
-        const out = {};
-        for (const [pk, o] of Object.entries(parentState.objects)) {
-            const inc = includeMap[pk]?.include;
-            if (inc) out[pk] = o;
-        }
-        // the computed rebuilds this object on every run, so a write into it would be discarded
-        //  silently on the next read. Report it instead.
-        return shallowReadonly(out);
+    // Resolve individual keys without tracking the full collection.
+    // Implement readonly behaviour here to avoid an extra proxy layer.
+    /** @type {import('./listInstance.js').ObjectsByPk} */
+    const objects = new Proxy(/** @type {any} */ ({}), {
+        get(target, prop) {
+            if (typeof prop === "symbol") {
+                return Reflect.get(target, prop);
+            }
+            if (prop === "__v_isReadonly") {
+                return true;
+            }
+            return isIncluded(prop) ? parentState.objects[prop] : undefined;
+        },
+        set(target, prop) {
+            console.warn(`useListFilter: set operation on key "${String(prop)}" failed: objects is read-only.`);
+            return true;
+        },
+        deleteProperty(target, prop) {
+            console.warn(`useListFilter: delete operation on key "${String(prop)}" failed: objects is read-only.`);
+            return true;
+        },
+        has(target, prop) {
+            if (typeof prop === "symbol") {
+                return Reflect.has(target, prop);
+            }
+            return isIncluded(prop) && prop in parentState.objects;
+        },
+        ownKeys() {
+            return Reflect.ownKeys(includedObjects.value);
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            if (typeof prop === "symbol") {
+                return Reflect.getOwnPropertyDescriptor(target, prop);
+            }
+            // Use the cached collection because descriptor lookups occur during enumeration.
+            const object = includedObjects.value[prop];
+            if (object === undefined) {
+                // Keep descriptors consistent with ownKeys().
+                return undefined;
+            }
+            return { configurable: true, enumerable: true, value: object, writable: true };
+        },
+        getPrototypeOf() {
+            return Object.prototype;
+        },
     });
 
     /** @type {import('./listInstance.js').ListOrder} */
-    const order = computed(() => shallowReadonly(parentState.order.filter((pk) => includeMap[pk]?.include)));
+    const order = computed(() => shallowReadonly(parentState.order.filter(isIncluded)));
 
     /** @type {import('./listInstance.js').ObjectsInOrder} */
     const objectsInOrder = computed(() => shallowReadonly(order.value.map((pk) => parentState.objects[pk])));
@@ -211,6 +323,7 @@ export function useListFilter({ parentState, allowedFilter, excludedFilter }) {
         allowedFilter,
         excludedFilter,
 
+        objectsVersion,
         objects,
         order,
         objectsInOrder,
@@ -223,11 +336,10 @@ export function useListFilter({ parentState, allowedFilter, excludedFilter }) {
     return {
         state,
         parentState,
+        watchMembershipChanged: makeMembershipWatcher(state),
         stop: () => {
             es.stop();
-            for (const pk of Object.keys(includeMap)) {
-                delete includeMap[pk];
-            }
+            includeMap.clear();
         },
     };
 }

package/use/listInstance.js

@@ -2,6 +2,7 @@ import { defaultListCrud, getListCrud } from "../config/listCrud.js";
 import { assignReactiveObject } from "../utils/assignReactiveObject.js";
 import { getFakePk } from "../utils/getFakePk.js";
 import { normalizePk } from "../utils/refIfReactive.js";
+import { makeMembershipWatcher } from "../utils/watches.js";
 import { useLoadingError } from "./loadingError.js";
 import inspect from "browser-util-inspect";
 import { computed, effectScope, isReactive, reactive, readonly, ref, shallowReactive, shallowReadonly } from "vue";
@@ -97,7 +98,7 @@ export class ListInstanceError extends Error {
  * @property {object} params - Arguments passed to the server for listing operations.
  * @property {ObjectsMap} objectsMap - The map of objects stored by their pks.
  * @property {ObjectsByPk} objects - The list objects stored by their pks.
- * @property {number} objectsVersion - Increments when the set of object keys changes.
+ * @property {number} objectsVersion - Increments when this layer's set of object keys changes. Each layer that narrows membership publishes its own, so the value belongs to the state reporting it and is not comparable with another layer's. Watch it rather than reading it, and prefer `watchMembershipChanged`, which carries the same signal without exposing how it is counted.
  * @property {ListOrder} order - The order of objects in the list.
  * @property {ObjectsInOrder} objectsInOrder - The objects in the order specified by the list.
  * @property {import('vue').ShallowReactive<PaginateInfo>} paginateInfo - Pagination information for the list.
@@ -149,6 +150,7 @@ export class ListInstanceError extends Error {
  * @property {(args: {action: string, pks?: import('../config/commonCrud.js').Pk[]} & import('../config/listCrud.js').AdditionalListArgs) => import('../utils/cancellablePromise.js').MaybeCancellablePromise<object|string|boolean|null>} executeAction - Initiates an action on all objects in the list, returning the response, or null if the action failed. The promise carries a `cancel` method when the handler's promise did.
  * @property {(info: PaginateInfo) => void} setPaginateInfo - The method to update pagination information.
  * @property {(total: ColumnTotals) => void} setColumnTotals - The method to update column totals.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  */
 
 /**
@@ -449,6 +451,7 @@ export function useListInstance({ props, handlers = {} }) {
     /** @type {ListInstance} */
     const self = {
         state,
+        watchMembershipChanged: makeMembershipWatcher(state),
         setPaginateInfo: (info) => {
             assignReactiveObject(state.paginateInfo, info || {});
         },

package/use/listRelated.js

@@ -1,4 +1,5 @@
 import { keyDiff } from "../utils/keyDiff.js";
+import { makeMembershipWatcher } from "../utils/watches.js";
 import { loadingCombine } from "../utils/loadingCombine.js";
 import { normalizePk } from "../utils/refIfReactive.js";
 import { proxyRunning } from "../utils/proxyRunning.js";
@@ -109,6 +110,7 @@ export class ListRelatedError extends Error {
  * @typedef {object} ListRelatedProperties - The properties for the list related composition function.
  * @property {ListRelatedState} state - The state for the list related property.
  * @property {ListRelatedParentState} parentState - The parent state object.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - Stops all effects of the list related property.
  */
 
@@ -238,6 +240,14 @@ export function useListRelated(options) {
         }
     );
     const relatedObjectsEffectScopes = {};
+    // Records whose rule bag has not been reconciled against the rules yet. A record arriving with an
+    //  empty bag needs every rule applied. A record already carrying the full rule set needs nothing,
+    //  and rediscovering that by diffing its bag cost one keyDiff per record in the collection, per
+    //  page, which is what made an identical page cost more the further into a stream it arrived.
+    const pendingObjectKeys = new Set();
+    // The rule keys the last reconciliation ran against, so a run can tell which of its two causes woke
+    //  it. Only a rule change touches records that were already reconciled.
+    let previousRuleKeys = [];
 
     function parentStateObjectsWatch() {
         const { addedKeys: addedIds, removedKeys: removedIds } = keyDiff(
@@ -245,6 +255,7 @@ export function useListRelated(options) {
             Object.keys(state.relatedObjects)
         );
         for (const removedId of removedIds) {
+            pendingObjectKeys.delete(removedId);
             delete state.relatedObjects[removedId];
             delete state.objAndKeyForPkAndRule[removedId];
             delete state.fkForPkAndRule[removedId];
@@ -257,6 +268,7 @@ export function useListRelated(options) {
             state.relatedObjects[addedId] = {};
             state.objAndKeyForPkAndRule[addedId] = {};
             state.fkForPkAndRule[addedId] = {};
+            pendingObjectKeys.add(addedId);
         }
         nextTick(() => {
             state.relatedObjectsParentStateObjectsWatchRunning = false;
@@ -326,7 +338,18 @@ export function useListRelated(options) {
 
     function relatedObjectsWatch() {
         const relatedObjectsRulesIsEmpty = !state.relatedObjectsRules || isEmpty(state.relatedObjectsRules);
-        for (const objectKey of Object.keys(state.relatedObjects)) {
+        const ruleKeys = Object.keys(state.relatedObjectsRules || {});
+        const { addedKeys: addedRules, removedKeys: removedRules } = keyDiff(ruleKeys, previousRuleKeys, {
+            sameKeys: false,
+        });
+        previousRuleKeys = ruleKeys;
+        // A rule change alters the bag of every record, so it is the only cause that has to walk the
+        //  collection. A page arriving leaves every record already present holding the rule set it
+        //  already held, so only the arrivals have anything to reconcile.
+        const rulesChanged = addedRules.size > 0 || removedRules.size > 0;
+        const objectKeys = rulesChanged ? Object.keys(state.relatedObjects) : [...pendingObjectKeys];
+        pendingObjectKeys.clear();
+        for (const objectKey of objectKeys) {
             let removedRuleKeys, addedRuleKeys;
             if (!relatedObjectsRulesIsEmpty) {
                 ({ removedKeys: removedRuleKeys, addedKeys: addedRuleKeys } = keyDiff(
@@ -401,6 +424,7 @@ export function useListRelated(options) {
     return {
         state,
         parentState,
+        watchMembershipChanged: makeMembershipWatcher(state),
         stop: () => {
             es.stop();
             for (const objectKey of Object.keys(relatedObjectsEffectScopes)) {

package/use/listSearch.js

@@ -1,4 +1,5 @@
 import { keyDiff } from "../utils/keyDiff.js";
+import { makeMembershipWatcher } from "../utils/watches.js";
 import { proxyRunning } from "../utils/proxyRunning.js";
 import { getObjectRelatedCalculatedByKey } from "../utils/relatedCalculatedHelpers.js";
 import { useSearch } from "./search.js";
@@ -87,6 +88,7 @@ import { refIfReactive } from "../utils/refIfReactive.js";
  * @typedef {object} ListSearchProperties - The properties on a list search instance.
  * @property {ListSearchState} state - The state.
  * @property {import('./search.js').SearchInstance} textSearchIndex - The text search index.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - Stops the effect scope and cleans up resources.
  */
 
@@ -186,16 +188,41 @@ export function useListSearch({ parentState, props, throttle = 500, showAllWhenE
     const _objects = reactive({});
     /** @type {import('vue').Ref<import('../config/commonCrud.js').Pk[]>} */
     const _order = ref([]);
+    const textSearchRules = refIfReactive(props, "textSearchRules", []);
+    const textSearchValue = refIfReactive(props, "textSearchValue", "");
+    // With no rules or no query the layer selects nothing, so it hands the parent's views on unchanged
+    //  rather than copying the collection into `_objects` once per page.
+    const passthrough = computed(() => !textSearchRules.value?.length || !textSearchValue.value?.length);
+    // Constant collection for a pass-through that shows nothing, read-only like every other view here.
+    const noObjects = shallowReadonly({});
+    // This layer's membership is its own: a query or rule change moves it without the parent's key set
+    //  moving, so the parent's objectsVersion does not describe this collection. Own one here and keep
+    //  the property's contract true for the sort layer downstream, which is what lets it watch the
+    //  version instead of enumerating this layer. Synced by syncObjectsVersion below.
+    const objectsVersion = ref(0);
+    const searchedObjects = shallowReadonly(_objects);
     /** @type {ListSearchState} */
     // @ts-ignore
     const state = reactive(
         /** @type {ListSearchRawState} */ {
             .../** @type {ListSearchParentStateToRefs} */ toRefs(parentState),
-            objects: shallowReadonly(_objects),
-            objectsInOrder: computed(() => shallowReadonly(internalState.objectsInOrderRefs.map((ref) => unref(ref)))),
+            objectsVersion,
+            objects: computed(() => {
+                if (!passthrough.value) {
+                    return searchedObjects;
+                }
+                return showAllWhenEmpty ? parentState.objects : noObjects;
+            }),
+            objectsInOrder: computed(() => {
+                if (passthrough.value) {
+                    // no private collection to hold refs into, so resolve against the parent per key
+                    return shallowReadonly(_order.value.map((pk) => parentState.objects[pk]));
+                }
+                return shallowReadonly(internalState.objectsInOrderRefs.map((ref) => unref(ref)));
+            }),
             order: computed(() => shallowReadonly(_order.value)),
-            textSearchRules: refIfReactive(props, "textSearchRules", []),
-            textSearchValue: refIfReactive(props, "textSearchValue", ""),
+            textSearchRules,
+            textSearchValue,
             objectIndexes: {},
             customDocumentOptions: refIfReactive(props, "customDocumentOptions", {}),
             customSearchOptions: refIfReactive(props, "customSearchOptions", {}),
@@ -237,6 +264,38 @@ export function useListSearch({ parentState, props, throttle = 500, showAllWhenE
     // @ts-ignore
     textSearchIndex.state.search = toRef(state, "textSearchValue");
 
+    /** @type {import('../config/commonCrud.js').Pk[]} */
+    let previousSearchedKeys = [];
+    /** @type {boolean} */
+    let previousPassthrough;
+    /** @type {number} */
+    let previousParentVersion;
+    const syncObjectsVersion = () => {
+        const parentVersion = parentState.objectsVersion;
+        const flipped = previousPassthrough !== passthrough.value;
+        if (passthrough.value) {
+            // The private collection is released while passing through, so the key set is either the
+            //  parent's or empty. Neither needs enumerating: a shown pass-through moves exactly when
+            //  the parent moves, and a hidden one never moves at all.
+            const moved = flipped || (showAllWhenEmpty && previousParentVersion !== parentVersion);
+            previousSearchedKeys = [];
+            previousPassthrough = true;
+            previousParentVersion = parentVersion;
+            if (moved) {
+                objectsVersion.value++;
+            }
+            return;
+        }
+        const searchedKeys = Object.keys(_objects);
+        const { addedKeys, removedKeys } = keyDiff(searchedKeys, previousSearchedKeys, { sameKeys: false });
+        previousSearchedKeys = searchedKeys;
+        previousPassthrough = false;
+        previousParentVersion = parentVersion;
+        if (flipped || addedKeys.size || removedKeys.size) {
+            objectsVersion.value++;
+        }
+    };
+
     const objectEffectScopes = {};
     const objectComputeds = {};
 
@@ -244,8 +303,9 @@ export function useListSearch({ parentState, props, throttle = 500, showAllWhenE
     const previousObjectIndexes = {};
 
     const doPassthrough = (cleanComputed = false) => {
-        // pass through the objects if there are no rules.
-        assignReactiveObject(_objects, showAllWhenEmpty ? parentState.objects : {});
+        // the state resolves against the parent while passing through, so the private collection is
+        //  released rather than rebuilt.
+        assignReactiveObject(_objects, {});
         if (!cleanComputed) {
             return;
         }
@@ -361,7 +421,7 @@ export function useListSearch({ parentState, props, throttle = 500, showAllWhenE
     };
 
     const updateObjectsForResults = () => {
-        if (!state.textSearchRules?.length || !state.textSearchValue?.length) {
+        if (passthrough.value) {
             doPassthrough();
             return;
         }
@@ -373,9 +433,21 @@ export function useListSearch({ parentState, props, throttle = 500, showAllWhenE
                     .map(([pk]) => [pk, toRef(parentState.objects, pk)])
             )
         );
+        // Published once the writes are done. Watching the collection instead would re-enumerate it on
+        //  every key assignReactiveObject writes.
+        syncObjectsVersion();
     };
 
     const updateOrder = () => {
+        if (passthrough.value) {
+            // Every parent key is a member, so the order needs no filtering against a private
+            //  collection and objectsInOrder needs no refs into one. `_order` is still written here
+            //  rather than read from the parent live: the write is what coalesces a page's worth of
+            //  parent order changes into one notification for everything downstream.
+            _order.value = showAllWhenEmpty ? [...parentState.order] : [];
+            assignReactiveObject(internalState.objectsInOrderRefs, []);
+            return;
+        }
         _order.value = parentState.order.filter((pk) => !!_objects[pk]);
         assignReactiveObject(
             internalState.objectsInOrderRefs,
@@ -396,10 +468,20 @@ export function useListSearch({ parentState, props, throttle = 500, showAllWhenE
     };
 
     es.run(() => {
-        watch([() => Object.keys(parentState.objects), toRef(state.textSearchRules)], makeComputeds, {
+        // The parent now owns a version that describes its own key set, so this watches the version
+        //  rather than enumerating the parent's collection on every invalidation of anything it tracks.
+        watch([() => parentState.objectsVersion, toRef(state.textSearchRules)], makeComputeds, {
             immediate: true,
         });
 
+        // Publish this layer's own key set changes. A parent structural change reaches this collection
+        //  only while passing through; the query-driven case is published by updateObjectsForResults
+        //  once it has finished writing, so nothing here enumerates the private collection per write.
+        watch([passthrough, () => parentState.objectsVersion], syncObjectsVersion, {
+            immediate: true,
+            flush: "sync",
+        });
+
         watch(
             toRef(state, "objectIndexes"),
             () => {
@@ -423,15 +505,21 @@ export function useListSearch({ parentState, props, throttle = 500, showAllWhenE
             }
         );
 
-        watch([() => Object.keys(_objects), toRef(parentState, "order")], updateOrder, {
-            immediate: true,
-            deep: true,
-        });
+        // While passing through, the private collection is empty and enumerating it buys nothing.
+        watch(
+            [passthrough, () => (passthrough.value ? null : Object.keys(_objects)), toRef(parentState, "order")],
+            updateOrder,
+            {
+                immediate: true,
+                deep: true,
+            }
+        );
     });
     textSearchIndex.events.addEventListener("newIndex", indexWasCleared);
     return {
         state,
         textSearchIndex,
+        watchMembershipChanged: makeMembershipWatcher(state),
         stop: () => {
             textSearchIndex.events.removeEventListener("newIndex", indexWasCleared);
             es.stop();

package/use/listSort.js

@@ -1,4 +1,5 @@
 import { keyDiff } from "../utils/keyDiff.js";
+import { makeMembershipWatcher } from "../utils/watches.js";
 import { loadingCombine } from "../utils/loadingCombine.js";
 import { proxyRunning } from "../utils/proxyRunning.js";
 import get from "lodash-es/get.js";
@@ -10,6 +11,7 @@ import {
     onScopeDispose,
     reactive,
     ref,
+    shallowReactive,
     shallowReadonly,
     toRef,
     toRefs,
@@ -98,6 +100,7 @@ export function setListSortDefaultOptions({ sortThrottleWait }) {
  * @typedef {object} ListSortProperties - The properties available on a list sort instance.
  * @property {ListSortState} state - The reactive state for the list sort.
  * @property {ListSortParentState} parentState - The parent state.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  * @property {() => void} stop - A function to stop the effect scope and clean up resources.
  */
 
@@ -189,11 +192,14 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
         ),
     });
 
-    const criteriaMap = reactive({});
+    // Track entry changes without proxying entries or unwrapping their computed refs.
+    /** @type {Map<import('../config/commonCrud.js').Pk, {scope: import('vue').EffectScope, crit: import('vue').ComputedRef<any[]>}>} */
+    const criteriaMap = shallowReactive(new Map());
 
     function ensureCriteria(pk) {
-        if (criteriaMap[pk]) {
-            return criteriaMap[pk];
+        const existing = criteriaMap.get(pk);
+        if (existing) {
+            return existing;
         }
         const scope = es.run(() => effectScope());
         const crit = scope.run(() =>
@@ -223,15 +229,15 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
                 );
             })
         );
-        criteriaMap[pk] = { scope, crit };
+        criteriaMap.set(pk, { scope, crit });
         return crit;
     }
 
     function syncCriteria(newKeys) {
-        const { addedKeys, removedKeys } = keyDiff(newKeys, Object.keys(criteriaMap));
+        const { addedKeys, removedKeys } = keyDiff(newKeys, [...criteriaMap.keys()]);
         for (const pk of removedKeys) {
-            criteriaMap[pk].scope.stop();
-            delete criteriaMap[pk];
+            criteriaMap.get(pk).scope.stop();
+            criteriaMap.delete(pk);
         }
         for (const pk of addedKeys) {
             ensureCriteria(pk);
@@ -239,6 +245,10 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     }
 
     es.run(() => {
+        // One structural pass per change. This used to carry a second, deferred watcher on the parent's
+        //  keys, because the filter and search layers moved their own key set without moving the
+        //  version they forwarded. Both own an accurate version now, so the sync watcher sees every
+        //  cause and criteria exist before anything reads them.
         watch(
             () => parentState.objectsVersion,
             () => {
@@ -246,15 +256,14 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
             },
             { immediate: true, flush: "sync" }
         );
-        watch(() => Object.keys(parentState.objects), syncCriteria);
     });
 
     const rawOrder = computed(() => {
         const arr = [...unref(toRef(parentState, "order"))];
         const rulesArr = internalState.orderByRules?.filter(identity) || [];
         return arr.sort((a, b) => {
-            const aCrit = criteriaMap[a]?.crit ?? [];
-            const bCrit = criteriaMap[b]?.crit ?? [];
+            const aCrit = criteriaMap.get(a)?.crit.value ?? [];
+            const bCrit = criteriaMap.get(b)?.crit.value ?? [];
             for (let i = 0; i < rulesArr.length; i++) {
                 const rule = rulesArr[i];
                 let x = aCrit[i],
@@ -286,17 +295,67 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
         });
     });
 
-    const objects = computed(() => {
-        // built mutably here, then handed out read-only below
+    // Track membership without reading the record's criteria.
+    const hasCriteria = (/** @type {import('../config/commonCrud.js').Pk} */ pk) => criteriaMap.has(pk);
+
+    // Cache enumeration separately from per-key reads.
+    /** @type {import('vue').ComputedRef<import('./listInstance.js').ObjectsByPk>} */
+    const criteriaObjects = computed(() => {
         /** @type {{[pk: import('../config/commonCrud.js').Pk]: import('./objectInstance.js').ExistingCrudObject}} */
         const out = {};
         for (const [pk, o] of Object.entries(parentState.objects)) {
-            const inc = criteriaMap[pk]?.crit;
-            if (inc) out[pk] = o;
+            if (hasCriteria(pk)) {
+                out[pk] = o;
+            }
         }
-        // the computed rebuilds this object on every run, so a write into it would be discarded
-        //  silently on the next read. Report it instead.
-        return shallowReadonly(out);
+        return out;
+    });
+
+    // Resolve individual keys without tracking the full collection.
+    // Implement readonly behaviour here to avoid an extra proxy layer.
+    /** @type {import('./listInstance.js').ObjectsByPk} */
+    const objects = new Proxy(/** @type {any} */ ({}), {
+        get(target, prop) {
+            if (typeof prop === "symbol") {
+                return Reflect.get(target, prop);
+            }
+            if (prop === "__v_isReadonly") {
+                return true;
+            }
+            return hasCriteria(prop) ? parentState.objects[prop] : undefined;
+        },
+        set(target, prop) {
+            console.warn(`useListSort: set operation on key "${String(prop)}" failed: objects is read-only.`);
+            return true;
+        },
+        deleteProperty(target, prop) {
+            console.warn(`useListSort: delete operation on key "${String(prop)}" failed: objects is read-only.`);
+            return true;
+        },
+        has(target, prop) {
+            if (typeof prop === "symbol") {
+                return Reflect.has(target, prop);
+            }
+            return hasCriteria(prop) && prop in parentState.objects;
+        },
+        ownKeys() {
+            return Reflect.ownKeys(criteriaObjects.value);
+        },
+        getOwnPropertyDescriptor(target, prop) {
+            if (typeof prop === "symbol") {
+                return Reflect.getOwnPropertyDescriptor(target, prop);
+            }
+            // Use the cached collection because descriptor lookups occur during enumeration.
+            const object = criteriaObjects.value[prop];
+            if (object === undefined) {
+                // Keep descriptors consistent with ownKeys().
+                return undefined;
+            }
+            return { configurable: true, enumerable: true, value: object, writable: true };
+        },
+        getPrototypeOf() {
+            return Object.prototype;
+        },
     });
 
     const order = ref([]);
@@ -343,23 +402,25 @@ export function useListSort({ parentState, orderByRules, sortThrottleWait = defa
     // 6) objectsInOrder just follows that
     const objectsInOrder = computed(() => shallowReadonly(order.value.map((pk) => parentState.objects[pk])));
 
+    /** @type {ListSortState} */
+    const state = reactive({
+        ...toRefs(parentState),
+        orderByRules: toRef(internalState, "orderByRules"),
+        orderByDesc: toRef(internalState, "orderByDesc"),
+        objects,
+        // the ref stays private to writeOrder; the state exposes a read-only view of it
+        order: computed(() => shallowReadonly(order.value)),
+        objectsInOrder,
+        running,
+    });
+
     return {
-        state: reactive({
-            ...toRefs(parentState),
-            orderByRules: toRef(internalState, "orderByRules"),
-            orderByDesc: toRef(internalState, "orderByDesc"),
-            objects,
-            // the ref stays private to writeOrder; the state exposes a read-only view of it
-            order: computed(() => shallowReadonly(order.value)),
-            objectsInOrder,
-            running,
-        }),
+        state,
         parentState,
+        watchMembershipChanged: makeMembershipWatcher(state),
         stop: () => {
             es.stop();
-            for (const key of Object.keys(criteriaMap)) {
-                delete criteriaMap[key];
-            }
+            criteriaMap.clear();
         },
     };
 }

package/use/listSubscription.js

@@ -2,6 +2,7 @@ import { useCancellableIntent } from "./cancellableIntent.js";
 import { useListInstance } from "./listInstance.js";
 import { useLoadingError } from "./loadingError.js";
 import { normalizePk } from "../utils/refIfReactive.js";
+import { makeMembershipWatcher } from "../utils/watches.js";
 import inspect from "browser-util-inspect";
 import cloneDeep from "lodash-es/cloneDeep.js";
 import isEmpty from "lodash-es/isEmpty.js";
@@ -74,6 +75,7 @@ export class ListSubscriptionError extends Error {
  * @property {import('./listInstance.js').ListInstance} listInstance - The list instance used by the subscription.
  * @property {import('./cancellableIntent.js').CancellableIntent} listIntent - The `CancellableIntent` instance managing if the list should be (re)fetched.
  * @property {import('./cancellableIntent.js').CancellableIntent} subscribeIntent - The `CancellableIntent` instance managing if the subscription should be (un)subscribed.
+ * @property {import('../utils/watches.js').WatchMembershipChanged} watchMembershipChanged - Registers a callback for changes to the set of object keys this layer holds. The watcher belongs to the effect scope active where it is called, not to this layer, so stopping this layer silences it without disposing it.
  */
 
 /**
@@ -339,6 +341,7 @@ export function useListSubscription({ listInstance, props, handlers }) {
         listInstance,
         listIntent,
         subscribeIntent,
+        watchMembershipChanged: makeMembershipWatcher(state),
         clearError: proxyLoadingError.clearError,
         // Stops both intents, mirroring useObjectSubscription, so a caller that owns this
         // subscription's lifetime does not have to know its intent inventory. The wrapped

package/utils/watches.js

@@ -8,6 +8,38 @@ import { watch, toRef } from "vue";
  *
  */
 
+/**
+ * @callback WatchMembershipChanged - Calls back when a list layer's set of object keys changes.
+ *  Registers in the effect scope active where it is called, not in the layer's own scope, so the
+ *  returned handle and the surrounding scope own the watcher. Stopping the layer does not dispose it,
+ *  because the layer never owned it; it only silences it, since a stopped layer publishes nothing
+ *  further. Stop it through the returned handle or through the enclosing scope.
+ *  The callback takes no arguments: it reports that membership moved, not what it moved to. Read the
+ *  layer's collection views for that.
+ * @param {() => void} callback - Called after the layer's set of object keys changes.
+ * @param {import('vue').WatchOptions} [options] - Passed through to Vue's `watch`, so `immediate`,
+ *  `flush`, and `once` all behave as they do there.
+ * @returns {import('vue').WatchHandle} - Stops the watcher.
+ */
+
+/**
+ * Builds a layer's membership watcher over the counter that layer publishes.
+ *
+ * @internal
+ * @param {{objectsVersion: number}} state - The layer's own state.
+ * @returns {WatchMembershipChanged} - The watcher registration function for that layer.
+ */
+export function makeMembershipWatcher(state) {
+    // The counter is an implementation detail of how membership changes are published, so it is not
+    //  passed to the callback. That keeps how the signal is carried free to change.
+    return (callback, options) =>
+        watch(
+            () => state.objectsVersion,
+            () => callback(),
+            options
+        );
+}
+
 /**
  * Provides a mechanism for immediately starting and potentially stopping a Vue.js watcher
  * during its first invocation. This is useful when the need arises to terminate the watch