@object-ui/react 17.6.0 → 17.7.0

package/dist/hooks/useNavigationOverlay.js

@@ -14,8 +14,80 @@
  *
  * Used by plugin-grid, plugin-list, plugin-detail and any component that needs
  * NavigationConfig support.
+ *
+ * ## The RETIRED `view` key (objectui#9874)
+ *
+ * `view.list.navigation.view` was removed in `@objectstack/spec` 17.5.0 under
+ * ADR-0049 (enforce-or-remove). This hook was its one shipped consumer, and the
+ * spec's own tombstone describes THIS file: the authored value "was passed
+ * straight into the navigation-MODE argument of the console's `onNavigate`,
+ * where anything other than `edit` or `view` matched no branch, so the key
+ * selected nothing and could silently deaden the row click."
+ *
+ * ⭐ The point that is one character wide in the source and total in meaning:
+ * `onNavigate`'s second argument is the navigation MODE token, not a view name.
+ * An authored `view` did not SELECT a view, it SUBSTITUTED for the mode — so
+ * `{ mode: 'page', view: 'summary_view' }` dispatched `'summary_view'` into the
+ * slot a host reads against its closed `edit`/`view` vocabulary, matching
+ * neither branch. Two reads (`view ?? 'view'`, in the no-config and the `page`
+ * branch) are now the literal `'view'`, which is what every config without the
+ * key already dispatched and what every config dispatches now.
+ *
+ * The replacement route is NOT in this hook and no fallback belongs here. Per
+ * the same tombstone: to choose what opens for a record, assign a `record` page
+ * to the object and let `isDefault` pick the one that opens — page assignment
+ * is the machinery that resolves a detail layout, and a list view's
+ * `navigation` block only decides HOW the detail is surfaced (`mode`, `size`).
+ *
+ * ⚠️ `NavigationOverlayState` lost its `view` member with the read. It could
+ * only ever carry the retired key, so keeping it would publish a field that is
+ * permanently `undefined` — the same "declared, consumed, and wrong" state the
+ * retirement exists to end. Measured before removing it: zero readers of that
+ * member in this repository (`(navOverlay|nav|state).view` → no lines, against
+ * a lit control on its sibling members in the same command). Hosts outside this
+ * repository were NOT measured.
+ *
+ * ## `page` with no `onNavigate`: the HOST's record navigator (objectui#11293)
+ *
+ * `page` is the spec's default `mode`, so it is what `{ mode: 'page' }` and
+ * every authored block written without `mode` (`{ size: 'lg' }`) resolve to.
+ * The branch used to call `onNavigate` and nothing else, and a host that
+ * renders a block without wiring one — a board, a calendar, a gallery or a
+ * grid placed on a page as a standalone block — has no `onNavigate`: the
+ * click did nothing at all. Measured before the change: a standalone
+ * `object-kanban` / `object-calendar` with either spelling opened no overlay,
+ * called no navigation and no `window.open`, and a standalone `object-grid`
+ * did the same, because the grid's own `onNavigate` is host-supplied too.
+ *
+ * So when no `onNavigate` is supplied, a `page` click is handed to the record
+ * navigator the host PUBLISHES on `RelatedRecordActionsContext`
+ * (`openRecord(objectName, recordId)`). That is the seam the grid's link
+ * column and the lookup cells already read: the route is built by the host
+ * that owns it and never re-derived here, which is why this file still builds
+ * no record URL for `page`. Precedence is unchanged above it: an `onRowClick`
+ * takes the click first, and a supplied `onNavigate` wins over the published
+ * navigator, so every host that wires one (the grid's, the console's list
+ * views) behaves exactly as before. A host that publishes no navigator (the
+ * Studio preview, a bare React mount) has no record page to open, and the
+ * click still opens nothing: the context's documented absent state.
+ *
+ * ⚠️ Scoped to an AUTHORED block that resolves to `page`. An absent
+ * `navigation` stays the host's call (`onNavigate`, or nothing), and that is
+ * load-bearing rather than cautious: a host WITHHOLDS navigation by passing
+ * neither callback. `RelatedList` renders its mobile rows as an
+ * `object-gallery` with no `navigation` and an `onRowClick` that is undefined
+ * when the bridge withheld `onView`; reading the published navigator on the
+ * absent-key path would open those records anyway, under the very bridge that
+ * withheld them. So `{}` and no config still agree whenever an `onNavigate`
+ * is supplied, and part only where a host published a navigator but wired no
+ * callback. The kanban, calendar and gantt default an absent key to a drawer
+ * before it reaches this hook in any case. Modifier clicks and `new_window`
+ * are untouched as well. Pinned by
+ * `__tests__/useNavigationOverlay.hostRecordNavigator-11293.test.tsx` here and
+ * at the mounts by the kanban's and calendar's `NavigationMembers-8652` pins.
  */
 import { useState, useCallback, useMemo } from 'react';
+import { useRelatedRecordActions } from '../context/RelatedRecordActionsContext.js';
 /**
  * Pixel cap per overlay `size` bucket, clamped to the viewport at render —
  * mirrors `plugin-view/src/recordSurface.ts` (`OVERLAY_SIZE_PX`), which owns
@@ -53,12 +125,36 @@ export function resolveOverlayWidth(navigation) {
 /**
  * Hook for NavigationConfig-driven navigation overlay.
  *
+ * ## What to hand `objectName`
+ *
+ * The block's RECORD SOURCE — the object the clicked rows actually came from —
+ * and never a bare top-level `schema.objectName` read in its place. `77cb489b4`
+ * published `objectName` as the THIRD RUNG of one record-source ladder (`data`,
+ * then `staticData`, then `objectName`), not as a parallel "page object"
+ * concept, so a block has exactly ONE record source. `handleClick` below builds
+ * the record-page URL `/{objectName}/record/{id}` out of whatever it is handed:
+ * a caller that hands it the top-level key while its rows came from
+ * `data.object` navigates to a record that the URL's own object does not
+ * contain (`2ce2612df`).
+ *
+ * A caller that resolves a data config reads that ladder through the ONE shared
+ * reader — `resolveRecordSourceObjectName` from `@object-ui/core`
+ * (`b041b9c0c`) — as the example does. A caller with NO data config has
+ * nothing above rung three, and its `schema.objectName` already IS its record
+ * source; that spelling is correct there and needs no conversion.
+ *
  * @example
  * ```tsx
+ * import {
+ *   resolveRecordSourceConfig,
+ *   resolveRecordSourceObjectName,
+ * } from '@object-ui/core';
+ *
+ * const dataConfig = useMemo(() => resolveRecordSourceConfig(schema), [schema]);
  * const { handleClick, isOpen, selectedRecord, mode, close, width } =
  *   useNavigationOverlay({
  *     navigation: schema.navigation,
- *     objectName: schema.objectName,
+ *     objectName: resolveRecordSourceObjectName(schema, dataConfig),
  *     onNavigate: schema.onNavigate,
  *     onRowClick: props.onRowClick,
  *   });
@@ -79,11 +175,13 @@ export function resolveOverlayWidth(navigation) {
  */
 export function useNavigationOverlay(options) {
     const { navigation, objectName, onNavigate, onRowClick } = options;
+    // The host's published record navigator — read for the `page` branch only,
+    // and only when no `onNavigate` was supplied (objectui#11293).
+    const openRecord = useRelatedRecordActions()?.openRecord;
     const [isOpen, setIsOpen] = useState(false);
     const [selectedRecord, setSelectedRecord] = useState(null);
     const mode = navigation?.mode ?? 'page';
     const width = resolveOverlayWidth(navigation);
-    const view = navigation?.view;
     const isOverlay = mode === 'drawer' || mode === 'modal' || mode === 'split' || mode === 'popover';
     const close = useCallback(() => {
         setIsOpen(false);
@@ -97,6 +195,12 @@ export function useNavigationOverlay(options) {
         // External onRowClick takes full priority. Forward the modifier event
         // so parent handlers (e.g. ObjectView) can still implement Cmd/Ctrl/
         // middle-click → open in new tab.
+        //
+        // Called straight through the declaration (objectui#9357). This used to
+        // carry a type assertion widening the option to two parameters at the
+        // call — the producer paying for its own understated declaration, which
+        // AGENTS.md #0.1 sends back to the producer. The producer is this file,
+        // and the option above now declares what this line passes.
         if (onRowClick) {
             onRowClick(record, event);
             return;
@@ -117,7 +221,7 @@ export function useNavigationOverlay(options) {
         if (!navigation) {
             const recordId = record.id || record._id;
             if (onNavigate && recordId != null) {
-                onNavigate(recordId, view ?? 'view');
+                onNavigate(recordId, 'view');
             }
             return;
         }
@@ -143,11 +247,18 @@ export function useNavigationOverlay(options) {
             window.open(url, '_blank');
             return;
         }
-        // page — delegate to onNavigate callback
+        // page — delegate to onNavigate; with none supplied, to the record
+        // navigator the host publishes (objectui#11293). No URL is built here.
         if (mode === 'page') {
             const recordId = record.id || record._id;
-            if (onNavigate && recordId != null) {
-                onNavigate(recordId, view ?? 'view');
+            if (recordId == null)
+                return;
+            if (onNavigate) {
+                onNavigate(recordId, 'view');
+                return;
+            }
+            if (objectName && openRecord) {
+                openRecord(objectName, recordId);
             }
             return;
         }
@@ -157,7 +268,7 @@ export function useNavigationOverlay(options) {
             setIsOpen(true);
             return;
         }
-    }, [onRowClick, navigation, mode, objectName, onNavigate, isOverlay, view]);
+    }, [onRowClick, navigation, mode, objectName, onNavigate, openRecord, isOverlay]);
     return useMemo(() => ({
         isOpen,
         selectedRecord,
@@ -167,7 +278,6 @@ export function useNavigationOverlay(options) {
         setIsOpen,
         handleClick,
         width,
-        view,
         isOverlay,
-    }), [isOpen, selectedRecord, mode, close, open, handleClick, width, view, isOverlay]);
+    }), [isOpen, selectedRecord, mode, close, open, handleClick, width, isOverlay]);
 }

package/dist/hooks/useOffline.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, useSyncExternalStore } from 'react';
+import { useCallback, useEffect, useInsertionEffect, useMemo, useRef, useState, useSyncExternalStore, } from 'react';
 // ---------------------------------------------------------------------------
 // Online/offline external store (SSR-safe)
 // ---------------------------------------------------------------------------
@@ -93,7 +93,31 @@ export function useOffline(config = {}) {
     const [queue, setQueue] = useState(loadQueue);
     const [syncState, setSyncState] = useState('idle');
     const syncConfigRef = useRef(syncConfig);
-    syncConfigRef.current = syncConfig;
+    // `sync` below is keyed on `[enabled, queue]`, so a config-only change keeps
+    // the SAME `sync` closure alive — and the auto-sync effect deliberately
+    // captures one and fires it 100ms later. The ref is how those retained
+    // closures still read the newest `sync` config; putting `syncConfig` in
+    // `sync`'s deps instead would rebuild `sync` (and the memoised result) on
+    // every render, because callers pass `sync: { ... }` as an inline literal.
+    // Only the write moves out of the render body: `useInsertionEffect` runs in
+    // the mutation phase, ahead of every layout effect and paint, so no caller
+    // that could legally reach `sync()` observes a different value than before.
+    useInsertionEffect(() => {
+        syncConfigRef.current = syncConfig;
+    });
+    // The queue reaches `sync` through the SAME commit-phase mirror the sync
+    // config uses (objectui#6818). It used to come from `sync`'s own closure
+    // while `batchSize` came from the ref above, so the two halves of one call
+    // disagreed about how current they were: a retained `sync` — and the
+    // auto-sync effect below deliberately retains one and fires it 100ms later —
+    // batched a queue snapshot from an older render against the newest
+    // `batchSize`. Mirroring the queue makes both halves the newest COMMITTED
+    // value, and it is what takes `queue` out of `sync`'s dependency list, so
+    // `sync` stops changing identity on every queued mutation.
+    const queueRef = useRef(queue);
+    useInsertionEffect(() => {
+        queueRef.current = queue;
+    });
     // Persist queue to localStorage whenever it changes
     useEffect(() => {
         persistQueue(queue);
@@ -130,14 +154,16 @@ export function useOffline(config = {}) {
         setQueue([]);
     }, []);
     const sync = useCallback(async () => {
-        if (!enabled || queue.length === 0)
+        // Newest committed queue, not this closure's snapshot — see `queueRef`.
+        const pending = queueRef.current;
+        if (!enabled || pending.length === 0)
             return;
         setSyncState('syncing');
         try {
             // In a real implementation, this would batch-send mutations to the server.
             // For now, we simulate a successful sync by clearing the queue.
-            const batchSize = syncConfigRef.current?.batchSize ?? queue.length;
-            const batch = queue.slice(0, batchSize);
+            const batchSize = syncConfigRef.current?.batchSize ?? pending.length;
+            const batch = pending.slice(0, batchSize);
             // Simulate network round-trip
             await new Promise((resolve) => setTimeout(resolve, 0));
             // Remove synced mutations from queue
@@ -147,18 +173,46 @@ export function useOffline(config = {}) {
         catch {
             setSyncState('error');
         }
-    }, [enabled, queue]);
-    // Auto-sync when coming back online (short stabilization delay)
+    }, [enabled]);
+    // Auto-sync while online and holding queued mutations (short stabilization
+    // delay).
+    //
+    // The dependency list used to be `[isOnline, enabled]` with
+    // `react-hooks/exhaustive-deps` suppressed, on the stated grounds that
+    // re-running "on every queue change" would restart the 100ms timer once per
+    // queued mutation. That reason is real and is preserved below — the
+    // dependency is the BOOLEAN `hasPendingMutations`, never `queue` and never
+    // `queue.length`, so queueing a second mutation while a timer is already
+    // armed does not re-run this effect and does not restart the timer.
+    //
+    // What the suppression also did, and never justified, was evaluate the
+    // emptiness guard against a queue snapshot from whenever `isOnline` or
+    // `enabled` last changed. `queueMutation` accepts entries whenever the hook
+    // is enabled — it has never been conditional on being offline — so anything
+    // queued while ALREADY online found this effect asleep and had no auto-sync
+    // path at all; only an explicit `sync()` drained it (objectui#6818). Keying
+    // on the boolean re-evaluates the guard exactly when it can change answer.
+    //
+    // `sync` is now stable across queue changes (it reads the queue through
+    // `queueRef`), so naming it here costs no extra timer restart and the array
+    // is genuinely exhaustive — the suppression is gone rather than reworded.
+    //
+    // Known remaining edge, deliberately not widened here: a `batchSize` smaller
+    // than the queue drains one batch and leaves `hasPendingMutations` true, so
+    // the remainder waits for the next transition rather than chaining a second
+    // batch. That is the pre-existing behaviour, not a regression. Whether one
+    // auto-sync should drain the whole queue batch-by-batch is a semantics
+    // question about `batchSize` rather than a bug in this guard, and it is
+    // filed separately as objectui#6857.
+    const hasPendingMutations = queue.length > 0;
     useEffect(() => {
-        if (!enabled || !isOnline || queue.length === 0)
+        if (!enabled || !isOnline || !hasPendingMutations)
             return;
         const timer = setTimeout(() => {
             void sync();
         }, 100);
         return () => clearTimeout(timer);
-        // Only trigger on isOnline changes, not on every queue change
-        // eslint-disable-next-line react-hooks/exhaustive-deps
-    }, [isOnline, enabled]);
+    }, [isOnline, enabled, hasPendingMutations, sync]);
     return useMemo(() => ({
         isOnline,
         enabled,

package/dist/hooks/usePageAssignment.d.ts

@@ -7,7 +7,7 @@
  *
  * `usePageAssignment` — resolve the record PageSchema that should be rendered
  * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`
- * and returns the first PageSchema whose `pageType === 'record'` and `object`
+ * and returns the first PageSchema whose `type === 'record'` and `object`
  * matches the requested name.
  *
  * Returns a discriminated result by `PageSchema.kind`:
@@ -18,10 +18,13 @@
  *     `buildDefaultPageSchema(objectDef, { slots })` so omitted slots
  *     fall through to synthesized defaults.
  *
- * Future work (deferred): recordType / profile / app / formFactor filtering
- * and priority-based selection. For now we return the first match so that
- * callers can deterministically fall back to the auto-generated DetailView
- * when no record Page is authored.
+ * Selection is by DECLARATION ORDER: the first matching page wins, so callers
+ * can deterministically fall back to the auto-generated DetailView when no
+ * record Page is authored.
+ *
+ * Future work (deferred): recordType / profile / app / formFactor filtering.
+ * Any author-driven ordering would have to be DECLARED on `PageSchema` in
+ * `@objectstack/spec` first — see the note on the selection itself below.
  */
 export interface PageAssignmentOptions {
     /** Salesforce-style record type filter (reserved for future use). */

package/dist/hooks/usePageAssignment.js

@@ -7,7 +7,7 @@
  *
  * `usePageAssignment` — resolve the record PageSchema that should be rendered
  * for a given object. Walks the metadata cache exposed by `<MetadataProvider>`
- * and returns the first PageSchema whose `pageType === 'record'` and `object`
+ * and returns the first PageSchema whose `type === 'record'` and `object`
  * matches the requested name.
  *
  * Returns a discriminated result by `PageSchema.kind`:
@@ -18,10 +18,13 @@
  *     `buildDefaultPageSchema(objectDef, { slots })` so omitted slots
  *     fall through to synthesized defaults.
  *
- * Future work (deferred): recordType / profile / app / formFactor filtering
- * and priority-based selection. For now we return the first match so that
- * callers can deterministically fall back to the auto-generated DetailView
- * when no record Page is authored.
+ * Selection is by DECLARATION ORDER: the first matching page wins, so callers
+ * can deterministically fall back to the auto-generated DetailView when no
+ * record Page is authored.
+ *
+ * Future work (deferred): recordType / profile / app / formFactor filtering.
+ * Any author-driven ordering would have to be DECLARED on `PageSchema` in
+ * `@objectstack/spec` first — see the note on the selection itself below.
  */
 import { useEffect, useMemo, useState } from 'react';
 import { useMetadata } from '../context/AppShellContext.js';
@@ -75,14 +78,20 @@ export function usePageAssignment(objectName, opts = {}) {
         const candidates = pages.filter(p => {
             if (!p)
                 return false;
-            // Only `pageType: 'record'` (or bare `type: 'record'`) is a
-            // user-facing record-detail page. Any other `pageType` — notably the
-            // designer-side `'record_detail'`, dropped from `PageType` in
-            // framework#2265 but still expressible in raw metadata — must NOT be
-            // picked up here, otherwise opening any record would render it.
-            const pt = p.pageType ?? (p.type === 'record' ? 'record' : undefined);
-            const isRecord = pt === 'record';
-            if (!isRecord)
+            // `type` is the ONE discriminator: only `type: 'record'` is a
+            // user-facing record-detail page, and every other page type
+            // (`home` / `app` / `utility` / `list`) is skipped.
+            //
+            // `pageType` is deliberately NOT read (objectui#9674). `PageSchema` is
+            // a `strictObject` that refuses `pageType` by name — it is a declared
+            // ALIAS of `type`, and a page carrying it is a hard parse error that
+            // names `type` as the key to write — so no page that parses carries it,
+            // and reading it would teach the refused spelling onward. A consumer-side
+            // alias for a refused key is the fallback AGENTS.md #0.1 rules out. The
+            // designer-side `'record_detail'` is not expressible either: it left
+            // `PageTypeSchema` (framework#2265), so `type: 'record_detail'` is an
+            // invalid enum value.
+            if (p.type !== 'record')
                 return false;
             if (p.object !== objectName)
                 return false;
@@ -90,9 +99,21 @@ export function usePageAssignment(objectName, opts = {}) {
         });
         if (!candidates.length)
             return null;
-        // Stable ordering: respect explicit `priority` if present (higher wins),
-        // otherwise fall back to declaration order.
-        candidates.sort((a, b) => (b?.priority ?? 0) - (a?.priority ?? 0));
+        // Declaration order decides: the first match wins.
+        //
+        // This used to sort on a `priority` key read off the candidate. No author
+        // could ever set it: `PageSchema` is a `strictObject` and does not declare
+        // `priority`, so a page carrying one is a HARD PARSE ERROR, not a page that
+        // sorts first. Every candidate therefore read `0`, the comparator returned
+        // `0` for every pair, and a stable sort left declaration order untouched —
+        // the sort documented an affordance the schema refuses (objectui#7298).
+        //
+        // `isDefault` is not consulted here either. It IS declared on `PageSchema`,
+        // so unlike `priority` it is writable — but nothing in this decision reads
+        // it, which makes the flag on a shipped page (e.g. the platform's
+        // `sys_user_detail`) inert while looking decisive. Reading it would be new
+        // behaviour, not a repair; it is recorded here so the next reader does not
+        // mistake the flag for the thing that picks the page.
         return candidates[0];
     }, [meta.pages, objectName, opts.pageName, opts.recordType, opts.profile, opts.app, opts.formFactor]);
     // Discriminate by `kind`: full pages populate `page`, slotted pages

package/dist/hooks/useRecordSearch.d.ts

@@ -23,7 +23,10 @@ export interface RecordSearchHit {
      * objects. Stable across runs for the same (query, display) pair.
      */
     score: number;
-    /** Raw record payload, for callers that want extra context. */
+    /**
+     * Raw record payload, for callers that want extra context. It is the row as
+     * served: `fieldReadPolicy` gates the `display` label, not this payload.
+     */
     raw: any;
 }
 export interface UseRecordSearchOptions {
@@ -60,8 +63,38 @@ export interface UseRecordSearchOptions {
      * Optional display-name resolver. Defaults to the same `titleFormat`
      * fallback chain used by app-shell. Pass `getRecordDisplayName` from
      * `@object-ui/app-shell` to share that implementation exactly.
+     *
+     * Safe to pass inline: the resolver's identity never re-runs the search.
+     * Each run reads the resolver of the latest render, so a swapped resolver
+     * labels the hits of the next run; results already shown keep their labels.
      */
     getDisplayName?: (objectDef: any, record: any) => string;
+    /**
+     * Optional field-level read policy: pass `usePermissions()` from
+     * `@object-ui/permissions` (objectui#10500). Once it is loaded, a hit is
+     * labelled from its record with the fields the policy denies on the hit's
+     * object removed, `id` and `_id` kept. The row is gated BEFORE
+     * `getDisplayName` reads it, so a caller-supplied resolver is gated too. A
+     * denied field then reads exactly as an absent one and the resolver falls
+     * through to its next rung, the label a backend that strips denied fields
+     * (ObjectStack's `FieldMasker`) already yields. The rule is
+     * `withoutDeniedFields` from `@object-ui/core` (objectui#10594), the one the
+     * record title (objectui#10434) and the lookup option label (objectui#10411)
+     * call too.
+     *
+     * Omitted, or not loaded yet, the row is labelled as served. A title the
+     * server computed (`searchAll`'s `hit.title`) is the server's answer and is
+     * not re-judged here.
+     *
+     * Safe to pass inline: only `isLoaded` decides whether a run happens. When
+     * it changes the search re-runs, so hits labelled before the policy loaded
+     * are relabelled from the gated row. Otherwise each run reads the policy of
+     * the latest render, as it does `getDisplayName`.
+     */
+    fieldReadPolicy?: {
+        isLoaded: boolean;
+        checkField: (object: string, field: string, action: 'read') => boolean;
+    };
 }
 export interface UseRecordSearchResult {
     results: RecordSearchHit[];

package/dist/hooks/useRecordSearch.js

@@ -6,7 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useEffect, useMemo, useRef, useState } from 'react';
-import { getRecordDisplayName as defaultDisplayName } from '@object-ui/core';
+import { getRecordDisplayName as defaultDisplayName, withoutDeniedFields } from '@object-ui/core';
 import { errorCodeIs } from '@object-ui/types';
 // ADR-0079: the global-search default display-name resolver is now the ONE
 // shared `getRecordDisplayName` from `@object-ui/core` (honors titleFormat →
@@ -74,7 +74,10 @@ function scoreHit(query, display, recordId) {
  * `$filter` translation.
  */
 export function useRecordSearch(opts) {
-    const { query, objects, dataSource, objectNames, maxObjectsQueried = 8, topPerObject = 3, minLength = 2, debounceMs = 250, enabled = true, getDisplayName = defaultDisplayName, } = opts;
+    const { query, objects, dataSource, objectNames, maxObjectsQueried = 8, topPerObject = 3, minLength = 2, debounceMs = 250, enabled = true, getDisplayName = defaultDisplayName, fieldReadPolicy, } = opts;
+    // The one member of the read policy that decides whether a run happens: a
+    // primitive, so an inline policy object never re-runs the search by identity.
+    const policyLoaded = fieldReadPolicy?.isLoaded === true;
     const [results, setResults] = useState([]);
     const [isSearching, setIsSearching] = useState(false);
     const [error, setError] = useState(undefined);
@@ -111,11 +114,41 @@ export function useRecordSearch(opts) {
         }
         return pool;
     }, [objects, objectNames]);
+    // The object NAME is the whole signature: it is the only field of an object
+    // definition this effect consumes (`dataSource.find(obj.name, …)` and the
+    // `objects` whitelist sent to `searchAll`); `label` / `icon` are read per hit
+    // at render time and never decide whether the fanout re-runs.
+    //
+    // An `o?.titleField ?? ''` half used to be appended to each entry. It could
+    // never vary: `@objectstack/spec`'s object schema is a `strictObject` that
+    // REJECTS `titleField` with `unrecognized_keys` (objectui#6531), so no legal
+    // object metadata carries it and the half was permanently `''` — a constant
+    // suffix in a cache key, which also read as evidence that some producer ships
+    // the key. Removed in objectui#6557; the display name comes from
+    // `getRecordDisplayName`, which does not consult it either.
     const candidateSignature = useMemo(() => {
-        return candidates.map((o) => `${o?.name}:${o?.titleField ?? ''}`).join('|');
+        return candidates.map((o) => String(o?.name)).join('|');
     }, [candidates]);
     // Run ID for racing-request guarding. Stable across renders.
     const runIdRef = useRef(0);
+    // `getDisplayName` is caller-supplied and read only INSIDE a run, to label
+    // hits — it never decides whether a run happens. So the search effect reads
+    // the latest resolver through this ref and does not key on its identity
+    // (AGENTS.md §5 #10, objectui#10044). Keyed on it, an inline resolver (a new
+    // function every render) re-ran the effect on each render, and the cleanup
+    // cleared the pending debounce timer: renders faster than `debounceMs` never
+    // searched, and sparser renders issued a second identical request. Declared
+    // before the search effect, so it is current before any timer is armed.
+    //
+    // `fieldReadPolicy` is read the same way (objectui#10500): the run reads the
+    // latest policy through a ref, and only its `isLoaded` primitive
+    // (`policyLoaded`) is a dependency of the search effect.
+    const getDisplayNameRef = useRef(getDisplayName);
+    const fieldReadPolicyRef = useRef(fieldReadPolicy);
+    useEffect(() => {
+        getDisplayNameRef.current = getDisplayName;
+        fieldReadPolicyRef.current = fieldReadPolicy;
+    });
     useEffect(() => {
         if (!enabled || !dataSource || candidates.length === 0) {
             setResults([]);
@@ -142,7 +175,7 @@ export function useRecordSearch(opts) {
             // per-object `find({ $search })` fanout below only runs each object's
             // metadata-driven search (ADR-0061) and can miss records the global
             // search index knows about — the command-palette symptom in framework
-            // #3371, where `/api/v1/search` returned an account/opportunity the
+            // objectstack-ai/objectstack#3371, where `/api/v1/search` returned an account/opportunity the
             // palette never showed. When `searchAll` is absent (mock/test adapters,
             // non-ObjectStack backends) we fall back to the fanout.
             const searchAll = dataSource.searchAll;
@@ -184,7 +217,9 @@ export function useRecordSearch(opts) {
                             continue;
                         const objDef = byName.get(objectName) ?? { name: objectName };
                         const title = typeof h?.title === 'string' && h.title.trim() !== '' ? h.title.trim() : '';
-                        const display = title || getDisplayName(objDef, h?.record ?? {}) || `Record #${recordId}`;
+                        const display = title ||
+                            getDisplayNameRef.current(objDef, withoutDeniedFields(h?.record ?? {}, fieldReadPolicyRef.current, objectName)) ||
+                            `Record #${recordId}`;
                         const snippet = typeof h?.snippet === 'string' ? h.snippet.trim() : '';
                         hits.push({
                             objectName,
@@ -256,7 +291,7 @@ export function useRecordSearch(opts) {
                         const recordId = record?.id ?? record?._id;
                         if (recordId == null)
                             continue;
-                        const display = getDisplayName(obj, record);
+                        const display = getDisplayNameRef.current(obj, withoutDeniedFields(record, fieldReadPolicyRef.current, obj.name));
                         hits.push({
                             objectName: obj.name,
                             objectLabel: typeof obj.label === 'string' && obj.label.length > 0
@@ -290,7 +325,7 @@ export function useRecordSearch(opts) {
         maxObjectsQueried,
         minLength,
         debounceMs,
-        getDisplayName,
+        policyLoaded,
     ]);
     return { results, isSearching, error };
 }

package/dist/hooks/useResolvedFilter.d.ts

@@ -0,0 +1,46 @@
+/**
+ * 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 { type FilterTokenScope } from '@object-ui/core';
+/**
+ * Resolve a data node's own authored `filter` ONCE, and hold the result.
+ *
+ * Every context token the spec defines for filters (`{current_user_id}`,
+ * `{current_org_id}`, `{record_id}` where a record is in view, and the date
+ * macros such as `{today}`) is expanded by `@object-ui/core`'s shared
+ * `resolveFilterPlaceholders`, against the scope `useFilterScope()` reads: the
+ * session scope the host provides plus the mounted record's id
+ * (objectui#7297). Pass `useFilterScope()` as `scope`:
+ *
+ * ```tsx
+ * const filterScope = useFilterScope();
+ * const filter = useResolvedFilter(schema.filter, filterScope);
+ * // query with `filter`, and key the fetch effect on `filter`, never on schema.filter
+ * ```
+ *
+ * ⛔ Not a second resolver, and no fallback: a token the scope cannot resolve
+ * is whatever `resolveFilterPlaceholders` makes of it (left intact, with one
+ * warning naming it).
+ *
+ * The result is HELD against its inputs, the shape `plugin-view`'s
+ * `useResolvedFilterSegments` uses. A fetch effect keys on this filter, so a
+ * resolved copy minted on every render would refetch on every render; and a
+ * date macro such as `{now}` resolves to a new value at every call, so
+ * comparing OUTPUTS cannot stop that. The key is the authored filter, compared
+ * by structure (a host that rebuilds an equal filter inline must not
+ * re-query), plus each scope member read one by one (`recordId` among them,
+ * so moving to another record resolves again), never the scope object's
+ * identity (AGENTS.md #10). The held pair lives in state, so the
+ * value handed out is always the one React committed. A structurally different
+ * filter, or a changed scope member, resolves again and hands out a new value.
+ *
+ * A filter the resolver leaves unchanged (no token, or only tokens the scope
+ * cannot resolve) is handed out as the authored value itself, not as the
+ * resolver's equal copy, so a token-free filter reaches the query exactly as
+ * it did before any resolution.
+ */
+export declare function useResolvedFilter<T>(authored: T, scope: FilterTokenScope): T;