@object-ui/react 16.1.0 → 17.2.0

package/dist/hooks/useClientNotifications.js

@@ -17,8 +17,13 @@
  * `sys_inbox_message` materialization and the `sys_notification_receipt`
  * read-state spine (the re-modeled `sys_notification` L2 event carries no
  * recipient/read columns). This hook only needs to call the SDK with its
- * current signatures: `list(options)`, `markRead(ids[])`, `markAllRead()`,
- * and `registerDevice(request)`.
+ * current signatures: `list(options)`, `markRead(ids[])`, `markAllRead()`.
+ *
+ * The former registerDevice/getPreferences/updatePreferences delegates were
+ * removed (objectstack#3612): the SDK deleted those methods because the
+ * /notifications/devices and /notifications/preferences server routes were
+ * never built — every call was a guaranteed error. They return when the
+ * server side exists.
  */
 import { useCallback, useContext, useEffect, useRef, useState } from 'react';
 import { SchemaRendererContext } from '../context/SchemaRendererContext';
@@ -113,54 +118,6 @@ export function useClientNotifications(options = {}) {
             setLoading(false);
         }
     }, [client, notify]);
-    /* ---- registerDevice ---- */
-    const registerDevice = useCallback(async (token, platform) => {
-        if (!client?.notifications)
-            return;
-        setError(null);
-        try {
-            // ADR-0030 / @objectstack/client v7+: registerDevice takes a single
-            // RegisterDeviceRequest object (`{ token, platform }`), not positional
-            // args. `platform` is the device platform enum.
-            await client.notifications.registerDevice({
-                token,
-                platform: platform,
-            });
-        }
-        catch (err) {
-            const wrapped = err instanceof Error ? err : new Error('Failed to register device');
-            setError(wrapped);
-            throw wrapped;
-        }
-    }, [client]);
-    /* ---- getPreferences ---- */
-    const getPreferences = useCallback(async () => {
-        if (!client?.notifications)
-            return null;
-        setError(null);
-        try {
-            return await client.notifications.getPreferences();
-        }
-        catch (err) {
-            const wrapped = err instanceof Error ? err : new Error('Failed to get preferences');
-            setError(wrapped);
-            throw wrapped;
-        }
-    }, [client]);
-    /* ---- updatePreferences ---- */
-    const updatePreferences = useCallback(async (prefs) => {
-        if (!client?.notifications)
-            return;
-        setError(null);
-        try {
-            await client.notifications.updatePreferences(prefs);
-        }
-        catch (err) {
-            const wrapped = err instanceof Error ? err : new Error('Failed to update preferences');
-            setError(wrapped);
-            throw wrapped;
-        }
-    }, [client]);
     /* ---- markAsRead (server + local) ---- */
     const markAsRead = useCallback(async (id) => {
         // Optimistically mark locally first
@@ -198,9 +155,6 @@ export function useClientNotifications(options = {}) {
     }, [pollInterval, client, fetchNotifications]);
     return {
         fetchNotifications,
-        registerDevice,
-        getPreferences,
-        updatePreferences,
         markAsRead,
         loading,
         error,

package/dist/hooks/useFilterScope.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.
+ */
+import { type ReactNode } from 'react';
+import type { FilterTokenScope } from '@object-ui/core';
+/**
+ * Provide the session scope used to resolve filter placeholders.
+ *
+ * Mount once, above any surface that renders filtered data. The console shell
+ * mounts it next to `ExpressionProvider`, where both the signed-in user and
+ * the active organization are already resolved.
+ */
+export declare function FilterScopeProvider({ currentUserId, currentOrgId, children, }: {
+    currentUserId?: string | null;
+    currentOrgId?: string | null;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<FilterTokenScope>>;
+/**
+ * Read the session scope for filter placeholder resolution.
+ *
+ * Pass the result straight to `resolveFilterPlaceholders(filter, scope)` from
+ * `@object-ui/core` — that helper expands every placeholder vocabulary in one
+ * call, which is the point: resolving only some of them is the defect behind
+ * #3574.
+ */
+export declare function useFilterScope(): FilterTokenScope;

package/dist/hooks/useFilterScope.js

@@ -0,0 +1,55 @@
+/**
+ * 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 { createContext, createElement, useContext, useMemo } from 'react';
+/**
+ * The session values filter placeholders resolve against — `{current_user_id}`
+ * and `{current_org_id}` (framework #3574).
+ *
+ * ## Why a dedicated context
+ *
+ * The renderer packages (`plugin-dashboard`, `plugin-charts`, `plugin-list`)
+ * deliberately do not depend on `@object-ui/auth`; they receive everything
+ * they need as schema or context. But a widget cannot resolve
+ * `{current_user_id}` without knowing who is signed in, and the surfaces that
+ * DO know (the app-shell) sit above them.
+ *
+ * `PredicateScopeContext` already carries `current_user` and would have
+ * covered the user id, but it is the *expression* evaluation scope — it
+ * carries no organization, and widening it for an unrelated consumer would
+ * couple filter resolution to predicate semantics. A separate, two-field
+ * context keeps the contract explicit and lets a non-console host provide
+ * exactly these values without adopting the expression stack.
+ *
+ * When no provider is mounted this returns an empty scope. That is a safe
+ * default: unresolved tokens are left intact by the resolver, so the filter
+ * matches nothing rather than silently widening, and the resolver emits one
+ * warning naming the token.
+ */
+const FilterScopeContext = createContext({});
+/**
+ * Provide the session scope used to resolve filter placeholders.
+ *
+ * Mount once, above any surface that renders filtered data. The console shell
+ * mounts it next to `ExpressionProvider`, where both the signed-in user and
+ * the active organization are already resolved.
+ */
+export function FilterScopeProvider({ currentUserId, currentOrgId, children, }) {
+    const value = useMemo(() => ({ currentUserId, currentOrgId }), [currentUserId, currentOrgId]);
+    return createElement(FilterScopeContext.Provider, { value }, children);
+}
+/**
+ * Read the session scope for filter placeholder resolution.
+ *
+ * Pass the result straight to `resolveFilterPlaceholders(filter, scope)` from
+ * `@object-ui/core` — that helper expands every placeholder vocabulary in one
+ * call, which is the point: resolving only some of them is the defect behind
+ * #3574.
+ */
+export function useFilterScope() {
+    return useContext(FilterScopeContext);
+}

package/dist/hooks/useNavigationOverlay.d.ts

@@ -5,18 +5,42 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { NavigationConfigSchema } from '@objectstack/spec/ui';
+import type { SpecAuthoredInput } from '../spec-input';
 /**
- * Inline ViewNavigationConfig to avoid importing from @object-ui/types
- * (which may not be a direct dependency of @object-ui/react).
- * Mirrors the canonical definition in @object-ui/types/objectql.ts.
+ * The spec's `NavigationConfigSchema`, authoring side, with `mode` required.
+ *
+ * This was a hand copy carrying the note "inline … to avoid importing from
+ * @object-ui/types (which may not be a direct dependency of @object-ui/react)".
+ * That reasoning is about the wrong package: the vocabulary belongs to
+ * `@objectstack/spec`, which IS a direct dependency of this one — the same
+ * expired "kept local to avoid a dependency" comment objectui#3169 found in
+ * `@object-ui/app-shell`, where the dependency had likewise been there all
+ * along. Check `package.json` before believing such a note (objectstack#4115).
+ *
+ * The ONE divergence: the spec defaults `mode`, so its authoring side makes it
+ * optional; this hook dispatches on `mode` and its callers always supply one,
+ * so it is required here. Every other key is the spec's, by reference. Pinned
+ * by `__tests__/offline-nav-performance-spec-parity.test.ts`.
+ *
+ * Two per-key notes the hand copy carried, kept here because a derived alias
+ * has no members to hang them on:
+ *  - `size` is the coarse overlay bucket added by #2578; `resolveOverlayWidth`
+ *    below maps it through {@link OVERLAY_SIZE_WIDTHS}.
+ *  - `width` is DEPRECATED by #2578 in favour of `size`. It still wins when
+ *    present, because app-shell pre-resolves `size` into it.
  */
-export interface NavigationConfig {
-    mode: 'page' | 'drawer' | 'modal' | 'split' | 'popover' | 'new_window' | 'none';
-    view?: string;
-    preventNavigation?: boolean;
-    openNewTab?: boolean;
-    width?: string | number;
-}
+export type NavigationConfig = Omit<SpecAuthoredInput<typeof NavigationConfigSchema>, 'mode'> & {
+    mode: NonNullable<SpecAuthoredInput<typeof NavigationConfigSchema>['mode']>;
+};
+/**
+ * Resolve the overlay width from a NavigationConfig: an explicit `width` wins
+ * (app-shell pre-resolves `size` into it); otherwise a declared bucket maps
+ * through {@link OVERLAY_SIZE_WIDTHS}. `'auto'`/absent stays `undefined` — the
+ * host's default width — because deriving `auto` needs the object's field
+ * count, which only schema-aware hosts have. Exported for the parity test.
+ */
+export declare function resolveOverlayWidth(navigation: NavigationConfig | undefined): string | number | undefined;
 export type NavigationMode = NavigationConfig['mode'];
 export interface UseNavigationOverlayOptions {
     /** The navigation configuration from the schema */

package/dist/hooks/useNavigationOverlay.js

@@ -16,6 +16,40 @@
  * NavigationConfig support.
  */
 import { useState, useCallback, useMemo } from 'react';
+/**
+ * Pixel cap per overlay `size` bucket, clamped to the viewport at render —
+ * mirrors `plugin-view/src/recordSurface.ts` (`OVERLAY_SIZE_PX`), which owns
+ * the `size: 'auto'` field-count derivation this layer cannot perform (no
+ * object schema here). Kept in lockstep by the spec-parity test.
+ *
+ * Before #2942 this hook only read the deprecated `width`, so an authored
+ * `size` bucket was silently ignored by every host except app-shell (which
+ * pre-resolves it before calling in).
+ */
+const OVERLAY_SIZE_WIDTHS = {
+    sm: 'min(92vw, 480px)',
+    md: 'min(92vw, 720px)',
+    lg: 'min(92vw, 960px)',
+    xl: 'min(92vw, 1200px)',
+    full: 'min(92vw, 1600px)',
+};
+/**
+ * Resolve the overlay width from a NavigationConfig: an explicit `width` wins
+ * (app-shell pre-resolves `size` into it); otherwise a declared bucket maps
+ * through {@link OVERLAY_SIZE_WIDTHS}. `'auto'`/absent stays `undefined` — the
+ * host's default width — because deriving `auto` needs the object's field
+ * count, which only schema-aware hosts have. Exported for the parity test.
+ */
+export function resolveOverlayWidth(navigation) {
+    if (!navigation)
+        return undefined;
+    if (navigation.width !== undefined)
+        return navigation.width;
+    const size = navigation.size;
+    if (size && size !== 'auto')
+        return OVERLAY_SIZE_WIDTHS[size];
+    return undefined;
+}
 /**
  * Hook for NavigationConfig-driven navigation overlay.
  *
@@ -48,7 +82,7 @@ export function useNavigationOverlay(options) {
     const [isOpen, setIsOpen] = useState(false);
     const [selectedRecord, setSelectedRecord] = useState(null);
     const mode = navigation?.mode ?? 'page';
-    const width = navigation?.width;
+    const width = resolveOverlayWidth(navigation);
     const view = navigation?.view;
     const isOverlay = mode === 'drawer' || mode === 'modal' || mode === 'split' || mode === 'popover';
     const close = useCallback(() => {

package/dist/hooks/useOffline.d.ts

@@ -5,14 +5,25 @@
  * This source code is licensed under the MIT license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import type { OfflineStrategy, ConflictResolution, PersistStorage, EvictionPolicy, OfflineCacheConfigSchema, OfflineConfigSchema, SyncConfigSchema } from '@objectstack/spec/ui';
+import type { SpecAuthoredInput } from '../spec-input';
 /** Offline strategy determines how data is fetched when connectivity is limited. */
-export type OfflineStrategy = 'cache_first' | 'network_first' | 'stale_while_revalidate' | 'network_only' | 'cache_only';
-/** Conflict resolution strategy for sync operations. */
-export type ConflictResolutionStrategy = 'manual' | 'client_wins' | 'server_wins' | 'last_write_wins';
+export type { OfflineStrategy };
+/**
+ * Conflict resolution strategy for sync operations.
+ *
+ * Renamed from `ConflictResolutionStrategy` — that name belongs to a DIFFERENT
+ * spec export (`@objectstack/spec/api`: `error | priority | first-wins |
+ * last-wins`, the metadata-merge policy). The spec's name for the union this
+ * hook actually uses is `ConflictResolution`, so the fix was to take the spec's
+ * own name and its binding at once, the same move `FieldGroup` →
+ * `ObjectFieldGroup` made in objectui#3169.
+ */
+export type { ConflictResolution };
 /** Persist storage backend. */
-export type PersistStorageType = 'indexeddb' | 'localstorage' | 'sqlite';
+export type PersistStorageType = PersistStorage;
 /** Eviction policy for cache management. */
-export type EvictionPolicyType = 'lru' | 'lfu' | 'fifo';
+export type EvictionPolicyType = EvictionPolicy;
 /** Sync state of the offline system. */
 export type SyncState = 'idle' | 'syncing' | 'error' | 'offline';
 /** A queued mutation waiting to be synced. */
@@ -23,31 +34,38 @@ export interface QueuedMutation {
     resource: string;
     data?: Record<string, unknown>;
 }
-/** Cache configuration aligned with OfflineCacheConfigSchema. */
-export interface OfflineCacheConfig {
-    maxSize?: number;
-    ttl?: number;
-    persistStorage?: PersistStorageType;
-    evictionPolicy?: EvictionPolicyType;
-}
-/** Sync configuration aligned with SyncConfigSchema. */
-export interface OfflineSyncConfig {
-    strategy?: OfflineStrategy;
-    conflictResolution?: ConflictResolutionStrategy;
-    retryInterval?: number;
-    maxRetries?: number;
-    batchSize?: number;
-}
-/** Top-level offline configuration aligned with OfflineConfigSchema. */
-export interface OfflineConfig {
-    enabled?: boolean;
-    strategy?: OfflineStrategy;
-    cache?: OfflineCacheConfig;
-    sync?: OfflineSyncConfig;
-    offlineIndicator?: boolean;
-    offlineMessage?: string;
-    queueMaxSize?: number;
-}
+/**
+ * Cache configuration — the AUTHORING side of the spec's
+ * `OfflineCacheConfigSchema`.
+ *
+ * `persistStorage` and `evictionPolicy` carry `.default()`s, so they are
+ * optional to write and present after a parse. This hook is handed what an app
+ * author wrote, hence the input side; see {@link SpecAuthoredInput}.
+ */
+export type OfflineCacheConfig = SpecAuthoredInput<typeof OfflineCacheConfigSchema>;
+/**
+ * Sync configuration — the AUTHORING side of the spec's `SyncConfigSchema`.
+ *
+ * `strategy` and `conflictResolution` carry `.default()`s, so the output type
+ * makes them required; this hook is handed what an app author wrote.
+ */
+export type OfflineSyncConfig = SpecAuthoredInput<typeof SyncConfigSchema>;
+/**
+ * Top-level offline configuration — the AUTHORING side of the spec's
+ * `OfflineConfigSchema`.
+ *
+ * This name stays with `@object-ui/react` (objectui#3156 / objectui#3159): the
+ * `OfflineConfig` that used to sit in `@object-ui/types` was a service-worker
+ * ROUTE cache and has been renamed `PWAOfflineConfig`, so there is no
+ * cross-package clash left — this hook's config is the spec's concept, key for
+ * key, and takes the spec's binding.
+ *
+ * Input side, not `z.infer`, and here the reason is visible in the signature:
+ * `useOffline(config: OfflineConfig = {})` defaults to the empty object, which
+ * the output type — where `enabled`, `strategy` and `offlineIndicator` are all
+ * required once their `.default()`s have run — would reject outright.
+ */
+export type OfflineConfig = SpecAuthoredInput<typeof OfflineConfigSchema>;
 /** Result returned by the useOffline hook. */
 export interface OfflineResult {
     /** Whether the browser is currently online. */
@@ -72,9 +90,9 @@ export interface OfflineResult {
     offlineMessage: string;
 }
 /**
- * Hook for offline mode detection and sync queue management.
- * Implements OfflineConfigSchema, SyncConfigSchema, and ConflictResolutionSchema
- * from @objectstack/spec v2.0.7.
+ * Hook for offline mode detection and sync queue management. Its config types
+ * ARE the spec's `OfflineConfigSchema` / `SyncConfigSchema` / `ConflictResolution`
+ * (authoring side) — see {@link OfflineConfig}.
  *
  * @example
  * ```tsx

package/dist/hooks/useOffline.js

@@ -66,9 +66,9 @@ const DEFAULTS = {
     queueMaxSize: 100,
 };
 /**
- * Hook for offline mode detection and sync queue management.
- * Implements OfflineConfigSchema, SyncConfigSchema, and ConflictResolutionSchema
- * from @objectstack/spec v2.0.7.
+ * Hook for offline mode detection and sync queue management. Its config types
+ * ARE the spec's `OfflineConfigSchema` / `SyncConfigSchema` / `ConflictResolution`
+ * (authoring side) — see {@link OfflineConfig}.
  *
  * @example
  * ```tsx

package/dist/hooks/usePageVariables.js

@@ -117,18 +117,30 @@ PageVariablesProvider.displayName = 'PageVariablesProvider';
  */
 export function usePageVariables() {
     const ctx = useContext(PageVariablesContext);
-    if (!ctx) {
-        // Graceful fallback — allows components to work outside a Page
-        return {
-            variables: {},
-            definitions: [],
-            setVariable: () => { },
-            setVariables: () => { },
-            resetVariables: () => { },
-        };
-    }
-    return ctx;
+    return ctx ?? OUTSIDE_PAGE;
 }
+/**
+ * Graceful fallback — allows components to work outside a Page.
+ *
+ * MUST be a module constant, not a fresh literal per call. `SchemaRenderer`
+ * feeds `variables` into the `evaluatedSchema` memo's dependency list, so a new
+ * object each render defeats that memo for every component rendered outside a
+ * PageVariablesProvider — and hands children a new schema identity every time.
+ * A `kind:'react'` page memoises its compiled source on that identity, so the
+ * page was being remounted and its `useState` reset (objectui#2954).
+ *
+ * Frozen through, because sharing one instance means a stray write would no
+ * longer be scoped to one render — it would leak to every consumer outside a
+ * provider. There is no writer today (the setters are the API, and here they
+ * are no-ops); the freeze keeps it that way.
+ */
+const OUTSIDE_PAGE = Object.freeze({
+    variables: Object.freeze({}),
+    definitions: Object.freeze([]),
+    setVariable: () => { },
+    setVariables: () => { },
+    resetVariables: () => { },
+});
 /**
  * Hook to check if a PageVariablesProvider is available.
  */

package/dist/hooks/usePerformance.d.ts

@@ -13,7 +13,7 @@ export interface VirtualScrollConfig {
     itemHeight?: number;
     overscan?: number;
 }
-/** Performance configuration aligned with PerformanceConfigSchema. */
+/** Performance configuration. */
 export interface PerformanceConfig {
     /** Whether to lazy-load components/data. */
     lazyLoad?: boolean;
@@ -55,8 +55,8 @@ export interface PerformanceResult {
     debounce: <T extends (...args: unknown[]) => void>(fn: T) => T;
 }
 /**
- * Hook for performance monitoring and configuration aligned with
- * PerformanceConfigSchema from @objectstack/spec v2.0.7.
+ * Hook for performance monitoring and configuration. Its config type IS the
+ * spec's `PerformanceConfigSchema` (authoring side) — see {@link PerformanceConfig}.
  *
  * Provides resolved config values, Web Vitals metrics, and utility functions
  * (debounce, render marking) for performance-aware components.

package/dist/hooks/usePerformance.js

@@ -52,8 +52,8 @@ function getLCP() {
 // usePerformance hook
 // ---------------------------------------------------------------------------
 /**
- * Hook for performance monitoring and configuration aligned with
- * PerformanceConfigSchema from @objectstack/spec v2.0.7.
+ * Hook for performance monitoring and configuration. Its config type IS the
+ * spec's `PerformanceConfigSchema` (authoring side) — see {@link PerformanceConfig}.
  *
  * Provides resolved config values, Web Vitals metrics, and utility functions
  * (debounce, render marking) for performance-aware components.

package/dist/hooks/useRecordSearch.js

@@ -7,6 +7,7 @@
  */
 import { useEffect, useMemo, useRef, useState } from 'react';
 import { getRecordDisplayName as defaultDisplayName } 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 →
 // `displayNameField` → type-aware derivation → `Record #<id>`). Callers can
@@ -80,6 +81,15 @@ export function useRecordSearch(opts) {
     // Stable signature derived from the object metadata fields we actually
     // touch. Prevents pointless re-runs when the parent re-renders with a
     // new array reference but identical content.
+    //
+    // Deliberately UNCAPPED: `maxObjectsQueried` bounds the number of parallel
+    // per-object requests on the fanout path (applied there), not the search
+    // scope itself. Capping here also truncated the `objects` whitelist sent to
+    // the single-request `/api/v1/search` call, so the palette silently searched
+    // only the first N nav objects — records in every later object were
+    // unfindable no matter what the user typed. Measured symptom: ⌘K in an app
+    // with 40+ searchable objects only ever queried the first 8 nav entries,
+    // so which sidebar group happened to come first decided what was findable.
     const candidates = useMemo(() => {
         if (!Array.isArray(objects) || objects.length === 0)
             return [];
@@ -99,8 +109,8 @@ export function useRecordSearch(opts) {
         else {
             pool = objects.filter((o) => o?.searchable !== false);
         }
-        return pool.slice(0, maxObjectsQueried);
-    }, [objects, objectNames, maxObjectsQueried]);
+        return pool;
+    }, [objects, objectNames]);
     const candidateSignature = useMemo(() => {
         return candidates.map((o) => `${o?.name}:${o?.titleField ?? ''}`).join('|');
     }, [candidates]);
@@ -127,7 +137,90 @@ export function useRecordSearch(opts) {
             // Skip if a newer run started during the debounce window.
             if (runIdRef.current !== myRunId)
                 return;
-            const requests = candidates.map((obj) => Promise.resolve()
+            // Prefer the platform's unified global-search endpoint when the data
+            // source exposes it (ObjectStackAdapter → GET /api/v1/search?q=). The
+            // 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
+            // palette never showed. When `searchAll` is absent (mock/test adapters,
+            // non-ObjectStack backends) we fall back to the fanout.
+            const searchAll = dataSource.searchAll;
+            if (typeof searchAll === 'function') {
+                // Scope to the candidate objects (the app's searchable nav objects) so
+                // the palette doesn't surface records from objects the current app
+                // can't route to. We both ask the server to scope (`objects`) and
+                // re-filter locally, guarding servers that ignore the param.
+                const byName = new Map();
+                for (const obj of candidates) {
+                    if (typeof obj?.name === 'string')
+                        byName.set(obj.name, obj);
+                }
+                Promise.resolve()
+                    .then(() => searchAll.call(dataSource, trimmed, {
+                    limit: maxObjectsQueried * topPerObject,
+                    objects: Array.from(byName.keys()),
+                }))
+                    .then((res) => {
+                    // Discard if a newer run started while we were waiting.
+                    if (runIdRef.current !== myRunId)
+                        return;
+                    const rawHits = Array.isArray(res?.hits)
+                        ? res.hits
+                        : Array.isArray(res)
+                            ? res
+                            : [];
+                    const hits = [];
+                    for (const h of rawHits) {
+                        const objectName = h?.object ?? h?.objectName;
+                        if (typeof objectName !== 'string')
+                            continue;
+                        // Keep only whitelisted objects (no-op when the server already
+                        // honored `objects`).
+                        if (byName.size > 0 && !byName.has(objectName))
+                            continue;
+                        const recordId = h?.id ?? h?.record?.id ?? h?.record?._id;
+                        if (recordId == null)
+                            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 snippet = typeof h?.snippet === 'string' ? h.snippet.trim() : '';
+                        hits.push({
+                            objectName,
+                            objectLabel: typeof objDef.label === 'string' && objDef.label.length > 0
+                                ? objDef.label
+                                : objectName,
+                            recordId: String(recordId),
+                            display,
+                            // Only surface a snippet when it adds information beyond the title.
+                            subtitle: snippet && snippet !== display ? snippet : undefined,
+                            icon: objDef?.icon,
+                            score: scoreHit(trimmed, display, String(recordId)),
+                            raw: h?.record ?? h,
+                        });
+                    }
+                    // The server already ranks hits across objects; preserve that order.
+                    // Only float an exact-id paste to the very top (parity with the
+                    // fanout path). Array.prototype.sort is stable, so every other hit
+                    // keeps the server ordering.
+                    hits.sort((a, b) => (b.score === 110 ? 1 : 0) - (a.score === 110 ? 1 : 0));
+                    setResults(hits);
+                    setIsSearching(false);
+                    setError(undefined);
+                })
+                    .catch((err) => {
+                    if (runIdRef.current !== myRunId)
+                        return;
+                    setResults([]);
+                    setIsSearching(false);
+                    setError(err instanceof Error ? err : new Error(String(err)));
+                });
+                return;
+            }
+            // Fanout fallback only: one request per object, so THIS is where the
+            // parallel-request cap applies.
+            const requests = candidates.slice(0, maxObjectsQueried).map((obj) => Promise.resolve()
                 .then(() => dataSource.find(obj.name, {
                 $search: trimmed,
                 $top: topPerObject,
@@ -149,7 +242,7 @@ export function useRecordSearch(opts) {
                         // last real error so the UI can show a non-blocking hint.
                         const status = err?.httpStatus ?? err?.status;
                         const code = err?.code;
-                        if (status === 404 || code === 'object_not_found')
+                        if (status === 404 || errorCodeIs(err, 'OBJECT_NOT_FOUND'))
                             continue;
                         lastError = err instanceof Error ? err : new Error(String(err));
                         continue;
@@ -194,6 +287,7 @@ export function useRecordSearch(opts) {
         dataSource,
         candidateSignature,
         topPerObject,
+        maxObjectsQueried,
         minLength,
         debounceMs,
         getDisplayName,

package/dist/index.d.ts

@@ -12,5 +12,6 @@ export * from './LazyPluginLoader';
 export * from './spec-bridge';
 export * from './data-invalidation';
 export { resolveI18nLabel } from './utils/i18n';
-export { extractWriteErrorMessage, isPermissionError } from './utils/error-message';
+export { extractWriteErrorMessage, isPermissionError, extractFieldErrors } from './utils/error-message';
+export type { WriteFieldError } from './utils/error-message';
 export { I18nProvider, useObjectTranslation, useSafeTranslate, useObjectLabel, useSafeFieldLabel, useI18nContext, createI18n, getDirection, getAvailableLanguages, formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, type I18nConfig, type I18nProviderProps, type TranslationKeys, type DateFormatOptions, type CurrencyFormatOptions, type NumberFormatOptions, } from '@object-ui/i18n';

package/dist/index.js

@@ -15,6 +15,6 @@ export * from './data-invalidation';
 export { resolveI18nLabel } from './utils/i18n';
 // Write-error surfacing utilities (shared by drag-write plugins so a failed
 // PATCH — e.g. an RLS 403 — is never silently swallowed).
-export { extractWriteErrorMessage, isPermissionError } from './utils/error-message';
+export { extractWriteErrorMessage, isPermissionError, extractFieldErrors } from './utils/error-message';
 // Built-in i18n support
 export { I18nProvider, useObjectTranslation, useSafeTranslate, useObjectLabel, useSafeFieldLabel, useI18nContext, createI18n, getDirection, getAvailableLanguages, formatDate, formatDateTime, formatRelativeTime, formatCurrency, formatNumber, } from '@object-ui/i18n';

package/dist/spec-bridge/SpecBridge.d.ts

@@ -18,9 +18,5 @@ export declare class SpecBridge {
     transformListView(spec: any): SchemaNode;
     /** Transform a FormView spec */
     transformFormView(spec: any): SchemaNode;
-    /** Transform a Page spec */
-    transformPage(spec: any): SchemaNode;
-    /** Transform a Dashboard spec */
-    transformDashboard(spec: any): SchemaNode;
     updateContext(ctx: Partial<BridgeContext>): void;
 }