@object-ui/react 17.5.0 → 17.7.0

package/dist/hooks/index.js

@@ -5,46 +5,55 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-export * from './useExpression';
+export * from './useExpression.js';
 // Session scope for filter placeholders ({current_user_id}/{current_org_id}).
-export * from './useFilterScope';
-export * from './useActionRunner';
-export * from './useNavigationOverlay';
-export * from './usePageVariables';
-export * from './usePageVariableActionBridge';
-export * from './useViewData';
+export * from './useFilterScope.js';
+// The ONE hold a data node resolves its own authored `filter` through
+// (objectui#10666), fed by `useFilterScope()`.
+export * from './useResolvedFilter.js';
+export * from './useActionRunner.js';
+export * from './useNavigationOverlay.js';
+export * from './usePageVariables.js';
+export * from './usePageVariableActionBridge.js';
+export * from './useViewData.js';
 // PageComponentSchema.dataSource — the spec's per-element data binding.
-export * from './useElementDataSource';
-export * from './useDynamicApp';
-export * from './useDiscovery';
-export * from './useFocusTrap';
-export * from './useFocusManagement';
-export * from './useKeyboardShortcuts';
-export * from './useCrudShortcuts';
-export * from './useReducedMotion';
-export * from './useAnimation';
-export * from './useDensityMode';
-export * from './useViewSharing';
-export * from './useClientNotifications';
-export * from './useOffline';
-export * from './usePerformance';
-export * from './usePerformanceBudget';
-export * from './usePageTransition';
-export * from './useViewTransition';
-export * from './useETagCache';
-export * from './useSchemaPersistence';
-export * from './useGlobalUndo';
-export * from './useDebugMode';
-export * from './useActionEngine';
+export * from './useElementDataSource.js';
+export * from './useDynamicApp.js';
+export * from './useDiscovery.js';
+export * from './useFocusTrap.js';
+export * from './useFocusManagement.js';
+export * from './useKeyboardShortcuts.js';
+export * from './useCrudShortcuts.js';
+export * from './useReducedMotion.js';
+export * from './useAnimation.js';
+export * from './useDensityMode.js';
+export * from './useViewSharing.js';
+export * from './useOffline.js';
+export * from './usePerformance.js';
+export * from './usePerformanceBudget.js';
+export * from './usePageTransition.js';
+export * from './useViewTransition.js';
+export * from './useETagCache.js';
+export * from './useSchemaPersistence.js';
+export * from './useGlobalUndo.js';
+export * from './useDebugMode.js';
+export * from './useActionEngine.js';
 // The ONE application of `useObjectLabel`'s action resolvers over the three
 // authored strings an action carries (label / confirmText / successMessage).
-export * from './useActionTextLocalizer';
-export * from './useCapabilityGate';
+export * from './useActionTextLocalizer.js';
+export * from './useCapabilityGate.js';
+// The `SchemaRenderer` memo's `properties` evaluation, for an action container's
+// members, which are drawn without `SchemaRenderer` (objectui#10290).
+export * from './useConfigBagEvaluator.js';
 // The analytics label net's React glue, consumed by BOTH plugin-dashboard's
 // `DatasetWidget` and plugin-report's dataset block (objectui#4389). It lives
 // here rather than in `@object-ui/core` because it reads `SchemaRendererContext`
 // — see the file header for the measured dependency direction.
-export * from './useDatasetDimensionLabels';
-export * from './useDataRefresh';
-export * from './usePageAssignment';
-export * from './useRecordSearch';
+export * from './useDatasetDimensionLabels.js';
+export * from './useDataRefresh.js';
+export * from './usePageAssignment.js';
+export * from './useRecordSearch.js';
+// The settled-schema RESOLUTION half shared across ObjectKanban / ObjectView /
+// ObjectCalendar's hand copies (objectui#6482, maintainer ruling Option A).
+// Gate PLACEMENT stays per-component — see the hook's own doc comment.
+export * from './useSettledSchema.js';

package/dist/hooks/useActionEngine.js

@@ -22,8 +22,9 @@
  * ```
  */
 import { useCallback, useContext, useMemo } from 'react';
-import { ActionEngine, } from '@object-ui/core';
-import { ActionCtxReact } from '../context/ActionContext';
+import { ActionEngine, subjectPermissionsOf, } from '@object-ui/core';
+import { ActionCtxReact } from '../context/ActionContext.js';
+import { usePredicateScope } from './useExpression.js';
 export function useActionEngine(options = {}) {
     const { actions = [], context = {} } = options;
     // When wrapped in an <ActionProvider>, reuse its ActionRunner so that:
@@ -39,7 +40,42 @@ export function useActionEngine(options = {}) {
     // fall back to a self-contained runner constructed from the `context` arg.
     const providerCtx = useContext(ActionCtxReact);
     const sharedRunner = providerCtx?.runner ?? null;
+    // The acting subject the host's predicate scope binds as `current_user`
+    // (objectui#11212): the ONE object `ExpressionProvider` publishes under
+    // `current_user` / `user` / `ctx.user` / `os.user`, carrying the caller's
+    // effective object permissions once they have loaded. The engine filters
+    // `visible` against the RUNNER's bag, which a host seeds with its own `user`
+    // and never with `current_user` — so `current_user.can(…)`, and any other
+    // `current_user.*` predicate, faulted on this path in every state and the
+    // action was hidden even for a grant holder, while the same predicate
+    // answered on every predicate-scope surface. Binding the scope's subject
+    // itself — the same object, not a copy, because the engine answers `can`
+    // only for a receiver IDENTICAL to the bound `current_user` — is what makes
+    // the two paths one bag (objectui#6493). With no host scope (`{}`) nothing
+    // is bound and the path behaves as it always did.
+    //
+    // Only `current_user` is added. The runner's `user` / `ctx.user` / `os.user`
+    // stay the host's own object: it carries what the runner itself reads (the
+    // `systemPermissions` capability set), which the scope's subject does not.
+    //
+    // Since objectui#11242 `<ActionProvider>` binds the same subject on its own
+    // runner, so under a provider mounted INSIDE the predicate scope this write
+    // re-binds the object that is already there. It stays for the two runners
+    // no provider binds: this hook's own standalone runner (no provider at
+    // all), and a shared runner whose provider sits ABOVE the scope — the
+    // console's global provider does (`GlobalActionRuntimeProvider` wraps the
+    // routes, and `ExpressionProvider` is mounted inside them) — where the
+    // provider has no scope to read.
+    const subject = usePredicateScope().current_user;
+    // Keyed on what the binding READS, never on the subject's identity (a
+    // memoised value upstream — AGENTS.md #10): its serialisable fields, and the
+    // permissions map it carries, which the upstream adapter caches per payload
+    // outside React. A discarded-and-recomputed subject with the same content
+    // keeps the engine; the permissions arriving (or leaving) rebuilds it.
+    const subjectKey = subject === undefined ? '' : JSON.stringify(subject);
+    const subjectPermissions = subjectPermissionsOf(subject);
     const engine = useMemo(() => {
+        const bound = subject !== undefined ? { current_user: subject } : {};
         // When standalone (no surrounding `<ActionProvider>`), normalize the
         // context so predicates can use both `record`/`user` and `ctx.*`.
         const normalizedStandalone = (context && Object.keys(context).length > 0)
@@ -48,8 +84,9 @@ export function useActionEngine(options = {}) {
                 ctx: (context.ctx && typeof context.ctx === 'object')
                     ? { ...context, ...context.ctx }
                     : { ...context },
+                ...bound,
             }
-            : context;
+            : { ...context, ...bound };
         const e = sharedRunner ? new ActionEngine(sharedRunner) : new ActionEngine(normalizedStandalone);
         // When sharing a provider runner, MERGE per-render flat keys into the
         // existing `ctx` instead of overwriting it. The provider seeds
@@ -67,13 +104,19 @@ export function useActionEngine(options = {}) {
             const merged = {
                 ...context,
                 ctx: { ...existingCtx, ...callerCtx },
+                ...bound,
             };
             runner.updateContext(merged);
         }
+        else if (sharedRunner && subject !== undefined) {
+            // A caller that passes no per-render keys: the subject is still bound,
+            // onto the same shared runner the location filter reads.
+            e.getRunner().updateContext(bound);
+        }
         e.registerActions(actions);
         return e;
         // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [sharedRunner, JSON.stringify(actions), JSON.stringify(context)]);
+    }, [sharedRunner, JSON.stringify(actions), JSON.stringify(context), subjectKey, subjectPermissions]);
     const getActionsForLocation = useCallback((location) => engine.getActionsForLocation(location), [engine]);
     const getBulkActions = useCallback(() => engine.getBulkActions(), [engine]);
     const executeAction = useCallback((name, contextOverride) => engine.executeAction(name, contextOverride), [engine]);

package/dist/hooks/useActionRunner.js

@@ -7,6 +7,7 @@
  */
 import { useState, useCallback, useMemo } from 'react';
 import { ActionRunner, } from '@object-ui/core';
+import { useActionRunnerTranslator } from '../context/actionRunnerTranslator.js';
 /**
  * Hook for executing actions with loading state, typed with ActionDef.
  *
@@ -35,8 +36,11 @@ export function useActionRunner(optionsOrContext = {}) {
     const [loading, setLoading] = useState(false);
     const [error, setError] = useState(null);
     const [result, setResult] = useState(null);
+    // The runner's own copy (the generic success toast) in the session's language.
+    const translate = useActionRunnerTranslator();
     const runner = useMemo(() => {
         const r = new ActionRunner(context);
+        r.setTranslator(translate);
         if (onConfirm)
             r.setConfirmHandler(onConfirm);
         if (onToast)

package/dist/hooks/useActionTextLocalizer.d.ts

@@ -47,11 +47,23 @@
  *   Translation localizes what exists; it does not add behaviour. This mirrors
  *   what the already-correct call sites (`RecordDetailView`, `ObjectView`,
  *   `DeclaredActionsBar`) each spelled out by hand.
- * - **`label` is reduced through `pickLocalized` first**, because since rc.6 an
- *   authored `label` may be an `I18nLabel` map rather than a string. The map is
- *   collapsed to the active language BEFORE it is offered to the bundle as the
- *   fallback, so a per-locale literal and a bundle entry cannot disagree about
- *   what "the authored label" is.
+ * - **`outcomeMessages` follows the same rule, entry by entry**
+ *   (`@objectstack/spec` 17.6.0, objectui#11344): each outcome the action
+ *   declares resolves `_actions.<name>.outcomeMessages.<outcome>`; a bundle
+ *   entry for an outcome the action does not declare is never read, so a
+ *   bundle cannot add copy for an answer the author never wrote one for.
+ * - **`label`, `successMessage` and each `outcomeMessages` entry are reduced
+ *   through `pickLocalized` first**, because each is an `I18nLabel` — a string
+ *   or an inline per-locale map. The map is collapsed to the active language
+ *   BEFORE it is offered to the bundle as the fallback, so a per-locale
+ *   literal and a bundle entry cannot disagree about what "the authored text"
+ *   is, and the action runner, which has no language, only ever receives a
+ *   string.
+ * - **The success copy stays a template.** A `${result.*}` token, in a bundle
+ *   entry or in the authored text, passes through this hook untouched: the
+ *   action has not run yet, so there is no result to read. The runner fills
+ *   the token in after the action succeeds, through the same `${result.*}`
+ *   scope `onSuccess.navigate` reads — one interpolation, in one place.
  */
 export interface ActionTextLocalizerOptions {
     /**
@@ -61,9 +73,10 @@ export interface ActionTextLocalizerOptions {
     fallbackLabel?: string;
 }
 /**
- * Returns a copy of `action` with `label` — plus `confirmText` and
- * `successMessage` when the action declares them — resolved from the active
- * locale's bundle, falling back to the authored literals.
+ * Returns a copy of `action` with `label` — plus `confirmText`,
+ * `successMessage` and `outcomeMessages` when the action declares them —
+ * resolved from the active locale's bundle, falling back to the authored
+ * literals.
  */
 export type ActionTextLocalizer = <T extends Record<string, any>>(objectName: string | undefined, action: T, options?: ActionTextLocalizerOptions) => T;
 export declare function useActionTextLocalizer(): ActionTextLocalizer;

package/dist/hooks/useActionTextLocalizer.js

@@ -47,16 +47,29 @@
  *   Translation localizes what exists; it does not add behaviour. This mirrors
  *   what the already-correct call sites (`RecordDetailView`, `ObjectView`,
  *   `DeclaredActionsBar`) each spelled out by hand.
- * - **`label` is reduced through `pickLocalized` first**, because since rc.6 an
- *   authored `label` may be an `I18nLabel` map rather than a string. The map is
- *   collapsed to the active language BEFORE it is offered to the bundle as the
- *   fallback, so a per-locale literal and a bundle entry cannot disagree about
- *   what "the authored label" is.
+ * - **`outcomeMessages` follows the same rule, entry by entry**
+ *   (`@objectstack/spec` 17.6.0, objectui#11344): each outcome the action
+ *   declares resolves `_actions.<name>.outcomeMessages.<outcome>`; a bundle
+ *   entry for an outcome the action does not declare is never read, so a
+ *   bundle cannot add copy for an answer the author never wrote one for.
+ * - **`label`, `successMessage` and each `outcomeMessages` entry are reduced
+ *   through `pickLocalized` first**, because each is an `I18nLabel` — a string
+ *   or an inline per-locale map. The map is collapsed to the active language
+ *   BEFORE it is offered to the bundle as the fallback, so a per-locale
+ *   literal and a bundle entry cannot disagree about what "the authored text"
+ *   is, and the action runner, which has no language, only ever receives a
+ *   string.
+ * - **The success copy stays a template.** A `${result.*}` token, in a bundle
+ *   entry or in the authored text, passes through this hook untouched: the
+ *   action has not run yet, so there is no result to read. The runner fills
+ *   the token in after the action succeeds, through the same `${result.*}`
+ *   scope `onSuccess.navigate` reads — one interpolation, in one place.
  */
 import { useMemo } from 'react';
 import { useObjectLabel, useObjectTranslation, pickLocalized } from '@object-ui/i18n';
+import { isConfigBag } from '../utils/configBag.js';
 export function useActionTextLocalizer() {
-    const { actionLabel, actionConfirm, actionSuccess } = useObjectLabel();
+    const { actionLabel, actionConfirm, actionSuccess, actionOutcome } = useObjectLabel();
     const { language } = useObjectTranslation();
     return useMemo(() => {
         return ((objectName, action, options) => {
@@ -83,9 +96,21 @@ export function useActionTextLocalizer() {
                 out.confirmText = actionConfirm(objectName, name, action.confirmText);
             }
             if (action.successMessage !== undefined) {
-                out.successMessage = actionSuccess(objectName, name, action.successMessage);
+                out.successMessage = actionSuccess(objectName, name, pickLocalized(action.successMessage, language));
+            }
+            // The map is an authored bag (outcome → copy), so the one "is this a
+            // real bag?" predicate in this package answers whether to read it.
+            const authoredOutcomes = action.outcomeMessages;
+            if (isConfigBag(authoredOutcomes)) {
+                const outcomeMessages = {};
+                for (const [outcome, copy] of Object.entries(authoredOutcomes)) {
+                    const text = actionOutcome(objectName, name, outcome, pickLocalized(copy, language));
+                    if (text !== undefined)
+                        outcomeMessages[outcome] = text;
+                }
+                out.outcomeMessages = outcomeMessages;
             }
             return out;
         });
-    }, [actionLabel, actionConfirm, actionSuccess, language]);
+    }, [actionLabel, actionConfirm, actionSuccess, actionOutcome, language]);
 }

package/dist/hooks/useCapabilityGate.js

@@ -23,13 +23,14 @@
  *
  * **Fail-OPEN when unknown.** No runner, no user, no `systemPermissions` array:
  * the action shows. Unknown is not denied, the server is the authority
- * (ADR-0057 D10), and hiding a permitted user's button on missing client data
- * is the worse failure. An EMPTY array is not unknown — it means "holds
- * nothing" and gates normally.
+ * (the framework's ADR-0124 D1 — server enforces, client is courtesy), and
+ * hiding a permitted user's button on missing client data is the worse
+ * failure. An EMPTY array is not unknown — it means "holds nothing" and gates
+ * normally.
  */
 import { useCallback, useContext } from 'react';
-import { ActionCtxReact } from '../context/ActionContext';
-import { usePredicateScope } from './useExpression';
+import { ActionCtxReact } from '../context/ActionContext.js';
+import { usePredicateScope } from './useExpression.js';
 /**
  * The caller's system capabilities, or `undefined` when the host never supplied
  * them (→ callers must fail open).

package/dist/hooks/useConfigBagEvaluator.d.ts

@@ -0,0 +1,30 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+/**
+ * The `properties` evaluation of the `SchemaRenderer` memo, for a node that is
+ * rendered WITHOUT `SchemaRenderer` (objectui#10290).
+ *
+ * The action containers (`action:bar`, `action:group`, `action:menu` in
+ * `@object-ui/components`) draw their member actions themselves, so a member's
+ * `properties` never passes through the memo. Its static execution values ride
+ * `properties.params` (objectui#10289), and those values are templates
+ * evaluated where `properties` are (objectui#7867). This hook is that
+ * evaluation: the memo's per-key rule, its `ExpressionEvaluator`, and its
+ * scope (the host's ambient roots, `current_user`, the page's bound row as
+ * `record`, and page variables as `page`), read from the same contexts the memo
+ * reads. It is not a second template engine. See `evaluateConfigBagInScope`.
+ *
+ * The returned function takes a config bag and returns a new, evaluated bag. A
+ * value that is not a config bag is returned unchanged. Call it once per
+ * authored bag: the result is already evaluated, and evaluating it again would
+ * interpolate text that came out of the row.
+ *
+ * A fresh function each render. Nothing may depend on its identity
+ * (AGENTS.md #10).
+ */
+export declare function useConfigBagEvaluator(): (bag: unknown) => unknown;

package/dist/hooks/useConfigBagEvaluator.js

@@ -0,0 +1,39 @@
+/**
+ * ObjectUI
+ * Copyright (c) 2024-present ObjectStack Inc.
+ *
+ * This source code is licensed under the MIT license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+import { useRecordContext } from '../context/RecordContext.js';
+import { evaluateConfigBagInScope } from '../SchemaRenderer.js';
+import { usePredicateScope } from './useExpression.js';
+import { usePageVariables } from './usePageVariables.js';
+/**
+ * The `properties` evaluation of the `SchemaRenderer` memo, for a node that is
+ * rendered WITHOUT `SchemaRenderer` (objectui#10290).
+ *
+ * The action containers (`action:bar`, `action:group`, `action:menu` in
+ * `@object-ui/components`) draw their member actions themselves, so a member's
+ * `properties` never passes through the memo. Its static execution values ride
+ * `properties.params` (objectui#10289), and those values are templates
+ * evaluated where `properties` are (objectui#7867). This hook is that
+ * evaluation: the memo's per-key rule, its `ExpressionEvaluator`, and its
+ * scope (the host's ambient roots, `current_user`, the page's bound row as
+ * `record`, and page variables as `page`), read from the same contexts the memo
+ * reads. It is not a second template engine. See `evaluateConfigBagInScope`.
+ *
+ * The returned function takes a config bag and returns a new, evaluated bag. A
+ * value that is not a config bag is returned unchanged. Call it once per
+ * authored bag: the result is already evaluated, and evaluating it again would
+ * interpolate text that came out of the row.
+ *
+ * A fresh function each render. Nothing may depend on its identity
+ * (AGENTS.md #10).
+ */
+export function useConfigBagEvaluator() {
+    const predicateScope = usePredicateScope();
+    const boundRecord = useRecordContext()?.data;
+    const { variables: pageVariables } = usePageVariables();
+    return (bag) => evaluateConfigBagInScope(bag, predicateScope, boundRecord, pageVariables);
+}

package/dist/hooks/useCrudShortcuts.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useMemo } from 'react';
-import { useKeyboardShortcuts, } from './useKeyboardShortcuts';
+import { useKeyboardShortcuts, } from './useKeyboardShortcuts.js';
 /**
  * Registers standard CRUD keyboard shortcuts using the useKeyboardShortcuts hook.
  *

package/dist/hooks/useDatasetDimensionLabels.js

@@ -61,7 +61,7 @@
 import { useContext, useEffect, useMemo, useState } from 'react';
 import { deriveDimensionLabelMaps, loadDimensionFieldMeta, } from '@object-ui/core';
 import { useSafeFieldLabel } from '@object-ui/i18n';
-import { SchemaRendererContext } from '../context/SchemaRendererContext';
+import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
 /**
  * Resolve one dataset query's dimension field metadata — the LOCALE-FREE half.
  *

package/dist/hooks/useDensityMode.d.ts

@@ -50,8 +50,12 @@ export interface DensityResult {
  *
  * @example
  * ```tsx
- * const density = useDensityMode(activeView?.densityMode ?? 'comfortable', {
- *   onChange: (m) => dataSource.updateViewConfig(obj, vid, { densityMode: m }),
+ * import { DENSITY_MODE_TO_ROW_HEIGHT, rowHeightToDensityMode } from '@object-ui/core';
+ *
+ * // A view stores the protocol's `rowHeight`; the legacy `densityMode` key is
+ * // retired on `NamedListView` (objectui#7924), so persist the spec value.
+ * const density = useDensityMode(rowHeightToDensityMode(activeView?.rowHeight) ?? 'comfortable', {
+ *   onChange: (m) => dataSource.updateViewConfig(obj, vid, { rowHeight: DENSITY_MODE_TO_ROW_HEIGHT[m] }),
  * });
  * ```
  */

package/dist/hooks/useDensityMode.js

@@ -35,8 +35,12 @@ const DENSITY_ORDER = ['compact', 'comfortable', 'spacious'];
  *
  * @example
  * ```tsx
- * const density = useDensityMode(activeView?.densityMode ?? 'comfortable', {
- *   onChange: (m) => dataSource.updateViewConfig(obj, vid, { densityMode: m }),
+ * import { DENSITY_MODE_TO_ROW_HEIGHT, rowHeightToDensityMode } from '@object-ui/core';
+ *
+ * // A view stores the protocol's `rowHeight`; the legacy `densityMode` key is
+ * // retired on `NamedListView` (objectui#7924), so persist the spec value.
+ * const density = useDensityMode(rowHeightToDensityMode(activeView?.rowHeight) ?? 'comfortable', {
+ *   onChange: (m) => dataSource.updateViewConfig(obj, vid, { rowHeight: DENSITY_MODE_TO_ROW_HEIGHT[m] }),
  * });
  * ```
  */

package/dist/hooks/useDiscovery.d.ts

@@ -40,17 +40,8 @@ export interface DiscoveryInfo {
     /** Server name and version */
     name?: string;
     version?: string;
-    /** Runtime mode (e.g., 'development', 'production', 'preview') */
+    /** Runtime mode the server reports (`RuntimeMode` in `@objectstack/spec`) */
     mode?: string;
-    /** Preview mode configuration from the kernel (present when mode is 'preview') */
-    previewMode?: {
-        autoLogin?: boolean;
-        simulatedRole?: 'admin' | 'user' | 'viewer';
-        simulatedUserName?: string;
-        readOnly?: boolean;
-        expiresInSeconds?: number;
-        bannerMessage?: string;
-    };
     /** Service availability status */
     services?: {
         /** Authentication service status */

package/dist/hooks/useDiscovery.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useState, useEffect, useContext } from 'react';
-import { SchemaRendererContext } from '../context/SchemaRendererContext';
+import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
 /**
  * The backward-compatible "can I actually use this service?" check
  * (ADR-0076 D12 console slice):

package/dist/hooks/useETagCache.js

@@ -5,7 +5,7 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
-import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useInsertionEffect, useMemo, useRef, useState } from 'react';
 // ---------------------------------------------------------------------------
 // Defaults
 // ---------------------------------------------------------------------------
@@ -141,9 +141,30 @@ export function useETagCache(userConfig = {}) {
     const swUrl = userConfig.serviceWorkerUrl ?? DEFAULTS.serviceWorkerUrl;
     const [cacheSize, setCacheSize] = useState(0);
     const [serviceWorkerActive, setServiceWorkerActive] = useState(false);
-    // Keep config in a ref so callbacks always see latest values
-    const configRef = useRef({ enabled, storage, storagePrefix, maxEntries, ttl });
-    configRef.current = { enabled, storage, storagePrefix, maxEntries, ttl };
+    // Keep config in a ref so callbacks always see latest values. Every reader
+    // below is a `useCallback` with `[]` deps whose identity consumers may key
+    // effects on, so the config has to reach them without changing it — that is
+    // the ref's job. Only the WRITE moves: done in the render body it also ran
+    // for renders React discards or replays, publishing config from a tree that
+    // never committed. `useInsertionEffect` runs in the mutation phase, ahead of
+    // every layout effect, ref attachment and paint, so the sole window deferred
+    // is the render phase — where `fetchWithETag` / `clearCache` and the other
+    // side effects are not callable anyway.
+    //
+    // The object itself is built by `useMemo` rather than inline at the two
+    // places that consume it. `useRef({ ... })` evaluates its argument on EVERY
+    // render and keeps only the first result, so every later render allocated a
+    // five-key object that was thrown away (objectui#6817) — the same shape PR
+    // objectui#6796 repaired in `useSchemaPersistence`. Its identity is
+    // unobservable from outside the hook: the ref is private and every reader
+    // only reads fields off `.current`, so a memo React chooses to discard is
+    // harmless — it rebuilds an equal object, which is what every render used
+    // to do unconditionally.
+    const config = useMemo(() => ({ enabled, storage, storagePrefix, maxEntries, ttl }), [enabled, storage, storagePrefix, maxEntries, ttl]);
+    const configRef = useRef(config);
+    useInsertionEffect(() => {
+        configRef.current = config;
+    });
     // Hydrate memory cache from localStorage on mount
     useEffect(() => {
         if (storage === 'localStorage') {

package/dist/hooks/useElementDataSource.d.ts

@@ -19,7 +19,7 @@
  * still ignores `view`), and the remaining object-bound blocks will need the same
  * resolution. One resolver in the runtime layer, not one per plugin.
  */
-import { type ComposedElementDataSource, type ElementDataSourceConfig, type ElementSavedView } from '@object-ui/core';
+import { FilterOperatorError, type ComposedElementDataSource, type ElementDataSourceConfig, type ElementSavedView } from '@object-ui/core';
 /**
  * Where a resolution attempt stands. Distinguishing `loading` from `missing`
  * matters: a component that treated "not resolved yet" as "does not exist" would
@@ -34,7 +34,12 @@ export type ElementDataSourceStatus =
  | 'loading'
 /** The named `view` was found and composed in. */
  | 'resolved'
-/** The named `view` does not exist on the object (or could not be read). */
+/**
+ * The binding cannot be applied: the named `view` does not exist on the
+ * object (or could not be read), or a filter it combines is REFUSED by the
+ * filter converter — then `filterRefusal` carries the refusal (objectui#10789).
+ * Either way `composed` is withheld, so no query runs without the filter.
+ */
  | 'missing';
 export interface UseElementDataSourceResult {
     status: ElementDataSourceStatus;
@@ -50,6 +55,14 @@ export interface UseElementDataSourceResult {
     view?: ElementSavedView;
     /** Author-facing explanation, set only for `missing`. */
     error?: string;
+    /**
+     * Why the binding could not be composed, when the reason is a refused
+     * filter — set only with `missing`, and `error` then carries its message
+     * (objectui#10789). A caller that draws the malformed-filter notice reads the
+     * refused operator or field off it (`filterRefusalSubject`) rather than
+     * scraping `error`.
+     */
+    filterRefusal?: FilterOperatorError;
 }
 /**
  * Resolve a schema node's `dataSource` binding, fetching the named saved view.

package/dist/hooks/useElementDataSource.js

@@ -20,8 +20,8 @@
  * resolution. One resolver in the runtime layer, not one per plugin.
  */
 import { useContext, useEffect, useMemo, useState } from 'react';
-import { collectSavedViews, composeElementDataSource, elementDataSourceViewNotFoundMessage, isElementDataSourceConfig, resolveSavedView, } from '@object-ui/core';
-import { SchemaRendererContext } from '../context/SchemaRendererContext';
+import { collectSavedViews, composeElementDataSource, elementDataSourceViewNotFoundMessage, FilterOperatorError, isElementDataSourceConfig, resolveSavedView, } from '@object-ui/core';
+import { SchemaRendererContext } from '../context/SchemaRendererContext.js';
 const isRecord = (v) => !!v && typeof v === 'object';
 /**
  * Read every saved view for `object` from the two places they live, in the same
@@ -45,7 +45,10 @@ async function fetchSavedViews(dataSource, object) {
     if (!canReadObjectDef && !canReadOverlay)
         return { capable: false, views: {} };
     const embedded = canReadObjectDef
-        ? dataSource.getObjectSchema(object).then((def) => (isRecord(def) ? (def.listViews ?? def.list_views) : undefined), () => undefined)
+        ? dataSource.getObjectSchema(object).then(
+        // `listViews` is canonical (#5362); the snake leg is a compatibility READ for
+        // stored pre-settlement documents (never censused: objectstack#7917).
+        (def) => (isRecord(def) ? (def.listViews ?? def.list_views) : undefined), () => undefined)
         : Promise.resolve(undefined);
     const overlay = canReadOverlay
         ? dataSource.listViews(object).then((rows) => rows, () => undefined)
@@ -68,6 +71,9 @@ async function fetchSavedViews(dataSource, object) {
  * ```
  */
 export function useElementDataSource(schema, dataSource) {
+    // Read AS DECLARED (objectui#7209) — no cast between the hook and the value,
+    // so a member the context does not declare is a compile error here. Pinned by
+    // `useElementDataSource.schemaRendererContextRead-7209.test.ts`.
     const context = useContext(SchemaRendererContext);
     const adapter = (dataSource ?? context?.dataSource ?? null);
     const config = useMemo(() => {
@@ -128,11 +134,25 @@ export function useElementDataSource(schema, dataSource) {
             return { status: 'loading', config };
         if (resolved.view === null)
             return { status: 'missing', config, error: resolved.error };
-        return {
-            status: 'resolved',
-            config,
-            view: resolved.view,
-            composed: composeElementDataSource(config, resolved.view),
-        };
+        // objectui#10789 — composing the view's filter with the binding's own is a
+        // MERGE, and the merge lowers both through the throwing converter form.
+        // This is a render-time `useMemo`, so an uncaught refusal was a render
+        // error: the block's error boundary instead of a sentence naming the
+        // operator. The refusal is kept as a VALUE and reported as `missing`,
+        // which every caller already answers by withholding the query — never as
+        // `undefined`, which would read as "no filter" and widen the read. Only a
+        // `FilterOperatorError` is caught, the rule `toFilterNodeSafely` states:
+        // anything else is a defect, not a statement about the author's filter.
+        // (The `ready` branch above composes no view, so nothing is merged there.)
+        let composed;
+        try {
+            composed = composeElementDataSource(config, resolved.view);
+        }
+        catch (error) {
+            if (!(error instanceof FilterOperatorError))
+                throw error;
+            return { status: 'missing', config, error: error.message, filterRefusal: error };
+        }
+        return { status: 'resolved', config, view: resolved.view, composed };
     }, [config, resolved, requestKey]);
 }