@object-ui/react 16.1.0 → 17.2.0

package/dist/context/NotificationContext.js

@@ -13,55 +13,192 @@ import { jsx as _jsx } from "react/jsx-runtime";
  * Implements NotificationSchema, NotificationConfigSchema, and
  * NotificationActionSchema from @objectstack/spec v2.0.7.
  */
-import { createContext, useCallback, useContext, useMemo, useState } from 'react';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+/**
+ * The presentation table — one entry per spec `NotificationTypeSchema` member.
+ *
+ * Typed as `Record<NotificationPresentation, …>`, so adding a member to the
+ * spec enum fails type-check here until its presentation is decided, rather
+ * than silently falling back to a toast.
+ */
+export const NOTIFICATION_PRESENTATIONS = {
+    toast: { surface: 'delegate', transient: true },
+    snackbar: { surface: 'snackbar', transient: true },
+    banner: { surface: 'banner', transient: false },
+    alert: { surface: 'alert', transient: false },
+    inline: { surface: 'inline', transient: false },
+};
+/**
+ * Resolve an authored `displayType` to the presentation that renders it:
+ * the spec default (`toast`) when absent, and `alert` for the deprecated
+ * `modal` dialect.
+ */
+export function resolveNotificationPresentation(displayType) {
+    if (displayType === 'modal')
+        return 'alert';
+    if (displayType && displayType in NOTIFICATION_PRESENTATIONS)
+        return displayType;
+    return 'toast';
+}
+/**
+ * The spec vocabularies this context implements — exported for the parity
+ * tests (#2942), which fail the moment `NotificationTypeSchema` /
+ * `NotificationPositionSchema` and these sets drift in either direction.
+ */
+export const SUPPORTED_NOTIFICATION_DISPLAY_TYPES = new Set(Object.keys(NOTIFICATION_PRESENTATIONS));
+export const SUPPORTED_NOTIFICATION_POSITIONS = new Set([
+    'top_left', 'top_center', 'top_right', 'bottom_left', 'bottom_center', 'bottom_right',
+]);
+/** The spec vocabulary this context implements — exported for the parity test. */
+export const SUPPORTED_NOTIFICATION_ACTION_VARIANTS = new Set([
+    'primary', 'secondary', 'link',
+]);
+/**
+ * Fold the deprecated spellings into the spec ones and apply the spec defaults
+ * (`NotificationConfigSchema`: 5000ms / 5 visible / stack down / pause on
+ * hover). `defaultPosition` gets no fabricated default — see the field docs.
+ */
+export function resolveNotificationConfig(config = {}) {
+    return {
+        defaultPosition: config.defaultPosition ?? config.position,
+        defaultDuration: config.defaultDuration ?? 5000,
+        // `stacking: false` means "don't stack" — one visible item.
+        maxVisible: config.stacking === false ? 1 : config.maxVisible ?? 5,
+        stackDirection: config.stackDirection ?? 'down',
+        pauseOnHover: config.pauseOnHover ?? true,
+    };
+}
 let notificationCounter = 0;
+/** Dev-build check — same idiom as `SchemaRenderer`'s `__DEV__`. */
+const __DEV__ = (() => {
+    try {
+        return globalThis.process?.env?.NODE_ENV
+            !== 'production';
+    }
+    catch {
+        return true;
+    }
+})();
+/** Dev-only guidance for a presentation raised with no surface mounted. */
+const SURFACE_HINTS = {
+    delegate: 'pass `onToast` to <NotificationProvider>',
+    snackbar: 'mount <NotificationSnackbar /> from @object-ui/components',
+    banner: 'mount <NotificationBanners /> from @object-ui/components',
+    alert: 'mount <NotificationAlerts /> from @object-ui/components',
+    inline: 'mount <NotificationInline /> from @object-ui/components at the raising surface',
+};
 const NotificationCtx = createContext(null);
 /**
  * NotificationProvider — Provides a spec-driven notification system.
  *
+ * Each spec display type is presented by its own surface. `toast` is delegated
+ * to the host (`onToast`); the other four are rendered by surface components
+ * that subscribe to this context — mount them where they belong:
+ * `NotificationSnackbar` / `NotificationAlerts` anywhere inside the provider,
+ * `NotificationBanners` at the top of the content area, and
+ * `NotificationInline` in the surface that raises the notification.
+ *
  * @example
  * ```tsx
  * <NotificationProvider
- *   config={{ position: 'top-right', defaultDuration: 5000, maxVisible: 5 }}
+ *   config={{ position: 'top_right', defaultDuration: 5000, maxVisible: 5 }}
  *   onToast={(n) => toast[n.severity](n.title, { description: n.message })}
  * >
+ *   <NotificationBanners />
  *   <App />
+ *   <NotificationSnackbar />
+ *   <NotificationAlerts />
  * </NotificationProvider>
  * ```
  */
 export const NotificationProvider = ({ children, config: userConfig = {}, onToast, }) => {
-    const config = useMemo(() => ({
-        position: 'top-right',
-        defaultDuration: 5000,
-        maxVisible: 5,
-        stacking: true,
-        ...userConfig,
-    }), 
+    const config = useMemo(() => resolveNotificationConfig(userConfig), 
     // eslint-disable-next-line react-hooks/exhaustive-deps
     [JSON.stringify(userConfig)]);
     const [notifications, setNotifications] = useState([]);
+    // Surfaces currently mounted, by presentation surface. A ref (not state) so
+    // `notify` can read the live set without re-creating itself on every mount.
+    const mountedSurfaces = useRef(new Map());
+    // Live auto-dismiss timers, so `pauseOnHover` can hold one and resume it with
+    // the time it had left. A plain `setTimeout` could only ever be cancelled,
+    // which is why the spec's `pauseOnHover` had nothing to attach to.
+    const timers = useRef(new Map());
+    const scheduleAutoDismiss = useCallback((id, ms) => {
+        const handle = setTimeout(() => {
+            timers.current.delete(id);
+            setNotifications((prev) => prev.filter((n) => n.id !== id));
+        }, ms);
+        timers.current.set(id, { handle, endsAt: Date.now() + ms, left: ms });
+    }, []);
+    const pauseAutoDismiss = useCallback((id) => {
+        const timer = timers.current.get(id);
+        if (!timer)
+            return;
+        clearTimeout(timer.handle);
+        timers.current.set(id, { ...timer, left: Math.max(0, timer.endsAt - Date.now()) });
+    }, []);
+    const resumeAutoDismiss = useCallback((id) => {
+        const timer = timers.current.get(id);
+        if (!timer)
+            return;
+        clearTimeout(timer.handle);
+        scheduleAutoDismiss(id, timer.left);
+    }, [scheduleAutoDismiss]);
+    // Never leave a timer running past unmount.
+    useEffect(() => () => {
+        for (const { handle } of timers.current.values())
+            clearTimeout(handle);
+        timers.current.clear();
+    }, []);
+    const registerSurface = useCallback((surface) => {
+        const counts = mountedSurfaces.current;
+        counts.set(surface, (counts.get(surface) ?? 0) + 1);
+        return () => {
+            const next = (counts.get(surface) ?? 1) - 1;
+            if (next > 0)
+                counts.set(surface, next);
+            else
+                counts.delete(surface);
+        };
+    }, []);
     const notify = useCallback((input) => {
         const id = `notification-${++notificationCounter}`;
+        // Materialize the declared presentation (spec default: toast; the legacy
+        // `modal` dialect presents as its nearest spec family, alert) so every
+        // stored item carries the presentation that will render it (#2942).
+        const presentation = resolveNotificationPresentation(input.displayType);
+        const { surface, transient } = NOTIFICATION_PRESENTATIONS[presentation];
         const notification = {
             ...input,
+            displayType: presentation,
             id,
             createdAt: new Date(),
             read: false,
         };
         setNotifications((prev) => [notification, ...prev]);
-        // Delegate to external toast handler if provided
-        if (onToast) {
-            onToast(notification);
-        }
-        // Auto-dismiss non-persistent notifications
-        const duration = input.duration ?? config.defaultDuration ?? 5000;
-        if (duration > 0) {
-            setTimeout(() => {
-                setNotifications((prev) => prev.filter((n) => n.id !== id));
-            }, duration);
+        // Route to the presentation's surface. `onToast` is the `toast` surface —
+        // it used to receive EVERY type, so a banner/alert/inline notification
+        // presented as a toast (#3014). The other four are rendered by the
+        // surface components subscribing through the context below.
+        if (surface === 'delegate')
+            onToast?.(notification, config);
+        // A surface-rendered presentation with no surface mounted is invisible —
+        // the "silently absent" shape this whole issue is about. Say so loudly in
+        // dev. `toast` is exempt: a provider with no `onToast` is the supported
+        // store-only mode (a notification centre with no overlay).
+        if (__DEV__ && surface !== 'delegate' && (mountedSurfaces.current.get(surface) ?? 0) === 0) {
+            console.warn(`[NotificationProvider] "${notification.title}" declares displayType ` +
+                `'${presentation}' but no ${presentation} surface is mounted, so it will ` +
+                `not be shown. To present it, ${SURFACE_HINTS[surface]}.`);
         }
+        // Auto-dismiss transient presentations. A banner/alert/inline stays until
+        // it is dismissed unless the raiser asked for a duration explicitly —
+        // sharing the toast timer made "persistent" presentations evaporate.
+        const duration = input.duration ?? (transient ? config.defaultDuration : 0);
+        if (duration > 0)
+            scheduleAutoDismiss(id, duration);
         return id;
-    }, [config.defaultDuration, onToast]);
+    }, [config, onToast, scheduleAutoDismiss]);
     const info = useCallback((title, message) => notify({ title, message, severity: 'info' }), [notify]);
     const success = useCallback((title, message) => notify({ title, message, severity: 'success' }), [notify]);
     const warning = useCallback((title, message) => notify({ title, message, severity: 'warning' }), [notify]);
@@ -73,6 +210,13 @@ export const NotificationProvider = ({ children, config: userConfig = {}, onToas
         setNotifications((prev) => prev.map((n) => ({ ...n, read: true })));
     }, []);
     const dismiss = useCallback((id) => {
+        // Drop any pending auto-dismiss with it — a held (hovered) timer would
+        // otherwise sit in the map until unmount.
+        const timer = timers.current.get(id);
+        if (timer) {
+            clearTimeout(timer.handle);
+            timers.current.delete(id);
+        }
         setNotifications((prev) => prev.filter((n) => n.id !== id));
     }, []);
     const clearAll = useCallback(() => {
@@ -92,6 +236,9 @@ export const NotificationProvider = ({ children, config: userConfig = {}, onToas
         dismiss,
         clearAll,
         config,
+        pauseAutoDismiss,
+        resumeAutoDismiss,
+        registerSurface,
     }), [
         notifications,
         unreadCount,
@@ -105,6 +252,9 @@ export const NotificationProvider = ({ children, config: userConfig = {}, onToas
         dismiss,
         clearAll,
         config,
+        pauseAutoDismiss,
+        resumeAutoDismiss,
+        registerSurface,
     ]);
     return (_jsx(NotificationCtx.Provider, { value: value, children: children }));
 };
@@ -128,3 +278,55 @@ export function useNotifications() {
 export function useHasNotificationProvider() {
     return useContext(NotificationCtx) !== null;
 }
+/**
+ * Apply the config's stack rules to a surface's items: keep the newest
+ * `maxVisible`, then order them so the stack GROWS in `stackDirection`
+ * (`down`, the spec default, puts the newest below the older ones).
+ *
+ * Shared by the stacking surfaces (banner, inline) so `maxVisible` means one
+ * thing. It used to mean nothing at all — the config carried it and no surface
+ * read it, while `NotificationBanners` capped at a hard-coded 3 of its own.
+ *
+ * @param items the surface's notifications, newest-first
+ */
+export function visibleNotificationStack(items, config) {
+    // Cap BEFORE ordering — an over-long stack drops its oldest, never its newest.
+    const capped = config.maxVisible > 0 ? items.slice(0, config.maxVisible) : items;
+    return config.stackDirection === 'up' ? capped : [...capped].reverse();
+}
+/**
+ * The screen position a FLOATING notification (toast, snackbar) should take:
+ * its own `position`, else the configured `defaultPosition`, else `undefined`.
+ *
+ * `undefined` is a meaningful answer, not a missing one — it means "nothing was
+ * declared", and the surface should keep its own anchor (a snackbar's bottom
+ * edge) or defer to the host's toast chrome, rather than being moved by a
+ * default nobody asked for. Always returns the spec (underscore) spelling.
+ */
+export function resolveNotificationPosition(notification, config) {
+    const declared = notification.position ?? config?.defaultPosition;
+    if (!declared)
+        return undefined;
+    const underscored = declared.replace(/-/g, '_');
+    return SUPPORTED_NOTIFICATION_POSITIONS.has(underscored) ? underscored : undefined;
+}
+/**
+ * Subscribe to the live notifications for ONE presentation — the contract a
+ * surface component implements (`@object-ui/components` ships one per spec
+ * type). Registering also tells the provider the surface exists, so raising a
+ * `banner` with no banner surface mounted warns in dev instead of vanishing.
+ *
+ * Items come back newest-first, matching `notifications`. A surface that wants
+ * FIFO order (an `alert` queue) reverses them itself.
+ *
+ * @param presentation the spec display type this surface renders
+ * @param scope optional `inline` routing key — when set, only items raised with
+ *   the same `scope` are returned; when omitted, only unscoped items are.
+ */
+export function useNotificationsByPresentation(presentation, scope) {
+    const { notifications, registerSurface } = useNotifications();
+    const { surface } = NOTIFICATION_PRESENTATIONS[presentation];
+    useEffect(() => registerSurface(surface), [registerSurface, surface]);
+    return useMemo(() => notifications.filter((n) => resolveNotificationPresentation(n.displayType) === presentation &&
+        (presentation !== 'inline' || (n.scope ?? undefined) === scope)), [notifications, presentation, scope]);
+}

package/dist/context/ThemeContext.js

@@ -131,14 +131,10 @@ export function ThemeProvider({ themes: themesInput = [], defaultTheme, defaultM
         // Apply mode class
         el.classList.remove('light', 'dark');
         el.classList.add(resolvedMode);
-        // Apply logo / favicon
-        if (resolvedTheme?.logo?.favicon && typeof document !== 'undefined') {
-            const link = document.querySelector('link[rel="icon"]')
-                ?? document.querySelector('#favicon');
-            if (link) {
-                link.href = resolvedTheme.logo.favicon;
-            }
-        }
+        // No favicon here: spec v17 (#3494) pruned `Theme.logo`, so the key is
+        // stripped at parse and could never arrive. The live favicon comes from
+        // operator branding (`getFaviconUrl()`), applied in the console's
+        // index.html, main.tsx, and on route change.
         return () => {
             // Cleanup: remove injected vars
             for (const prop of Object.keys(cssVars)) {

package/dist/hooks/index.d.ts

@@ -6,6 +6,7 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './useExpression';
+export * from './useFilterScope';
 export * from './useActionRunner';
 export * from './useNavigationOverlay';
 export * from './usePageVariables';
@@ -19,7 +20,6 @@ export * from './useKeyboardShortcuts';
 export * from './useCrudShortcuts';
 export * from './useReducedMotion';
 export * from './useAnimation';
-export * from './useColumnSummary';
 export * from './useDensityMode';
 export * from './useViewSharing';
 export * from './useClientNotifications';
@@ -33,6 +33,7 @@ export * from './useSchemaPersistence';
 export * from './useGlobalUndo';
 export * from './useDebugMode';
 export * from './useActionEngine';
+export * from './useCapabilityGate';
 export * from './useDataRefresh';
 export * from './usePageAssignment';
 export * from './useRecordSearch';

package/dist/hooks/index.js

@@ -6,6 +6,8 @@
  * LICENSE file in the root directory of this source tree.
  */
 export * from './useExpression';
+// Session scope for filter placeholders ({current_user_id}/{current_org_id}).
+export * from './useFilterScope';
 export * from './useActionRunner';
 export * from './useNavigationOverlay';
 export * from './usePageVariables';
@@ -19,7 +21,6 @@ export * from './useKeyboardShortcuts';
 export * from './useCrudShortcuts';
 export * from './useReducedMotion';
 export * from './useAnimation';
-export * from './useColumnSummary';
 export * from './useDensityMode';
 export * from './useViewSharing';
 export * from './useClientNotifications';
@@ -33,6 +34,7 @@ export * from './useSchemaPersistence';
 export * from './useGlobalUndo';
 export * from './useDebugMode';
 export * from './useActionEngine';
+export * from './useCapabilityGate';
 export * from './useDataRefresh';
 export * from './usePageAssignment';
 export * from './useRecordSearch';

package/dist/hooks/useAnimation.d.ts

@@ -7,10 +7,39 @@
  */
 /** Animation trigger type */
 export type AnimationTriggerType = 'enter' | 'exit' | 'hover' | 'focus' | 'click';
-/** Easing presets aligned with EasingFunctionSchema */
-export type EasingPreset = 'linear' | 'ease' | 'ease-in' | 'ease-out' | 'ease-in-out' | 'spring';
-/** Transition preset aligned with TransitionPresetSchema */
-export type TransitionPresetType = 'fade' | 'slide-up' | 'slide-down' | 'slide-left' | 'slide-right' | 'scale' | 'scale-fade' | 'none';
+/**
+ * Easing presets aligned with the spec `EasingFunctionSchema`
+ * (`ui/animation.zod.ts` — underscore spellings). The hyphen spellings are
+ * this hook's historical dialect, still accepted at runtime (normalized
+ * before lookup) so existing configs keep animating.
+ */
+export type EasingPreset = 'linear' | 'ease' | 'ease_in' | 'ease_out' | 'ease_in_out' | 'spring'
+/** @deprecated legacy spelling — use `ease_in` */
+ | 'ease-in'
+/** @deprecated legacy spelling — use `ease_out` */
+ | 'ease-out'
+/** @deprecated legacy spelling — use `ease_in_out` */
+ | 'ease-in-out';
+/**
+ * Transition presets aligned with the spec `TransitionPresetSchema`
+ * (`ui/animation.zod.ts` — underscore spellings, including `rotate` and
+ * `flip`). The hyphen spellings and `scale-fade` are this hook's historical
+ * dialect, still accepted at runtime so existing configs keep animating —
+ * but the spec's own spellings used to look up NOTHING here (#2942): the
+ * map was keyed in hyphens, so `preset: 'slide_up'` validated and rendered
+ * no animation at all.
+ */
+export type TransitionPresetType = 'fade' | 'slide_up' | 'slide_down' | 'slide_left' | 'slide_right' | 'scale' | 'rotate' | 'flip' | 'none'
+/** @deprecated legacy spelling — use `slide_up` */
+ | 'slide-up'
+/** @deprecated legacy spelling — use `slide_down` */
+ | 'slide-down'
+/** @deprecated legacy spelling — use `slide_left` */
+ | 'slide-left'
+/** @deprecated legacy spelling — use `slide_right` */
+ | 'slide-right'
+/** @deprecated legacy dialect (never in the spec) — use `flip` */
+ | 'scale-fade';
 export interface AnimationConfig {
     /** The animation/transition preset */
     preset?: TransitionPresetType;
@@ -30,6 +59,13 @@ export interface AnimationResult {
     /** Inline style for custom durations/delays (only when needed) */
     style: React.CSSProperties;
 }
+/**
+ * The spec vocabularies this hook implements — exported for the parity tests,
+ * which fail the moment `TransitionPresetSchema` / `EasingFunctionSchema` and
+ * these sets drift in either direction (#2942).
+ */
+export declare const SUPPORTED_TRANSITION_PRESETS: ReadonlySet<string>;
+export declare const SUPPORTED_EASING_FUNCTIONS: ReadonlySet<string>;
 /**
  * Hook for applying spec-driven animations to components.
  * Implements ComponentAnimationSchema and TransitionPresetSchema

package/dist/hooks/useAnimation.js

@@ -6,22 +6,48 @@
  * LICENSE file in the root directory of this source tree.
  */
 import { useMemo } from 'react';
+/**
+ * The spec vocabularies this hook implements — exported for the parity tests,
+ * which fail the moment `TransitionPresetSchema` / `EasingFunctionSchema` and
+ * these sets drift in either direction (#2942).
+ */
+export const SUPPORTED_TRANSITION_PRESETS = new Set([
+    'fade', 'slide_up', 'slide_down', 'slide_left', 'slide_right', 'scale', 'rotate', 'flip', 'none',
+]);
+export const SUPPORTED_EASING_FUNCTIONS = new Set([
+    'linear', 'ease', 'ease_in', 'ease_out', 'ease_in_out', 'spring',
+]);
+/**
+ * Normalize a legacy hyphen spelling (this hook's pre-#2942 dialect) onto the
+ * spec's underscore vocabulary. `scale-fade` never existed in the spec; its
+ * classes were identical to `flip`'s, so it maps there.
+ */
+function normalizePreset(preset) {
+    if (preset === 'scale-fade')
+        return 'flip';
+    return preset.replace(/-/g, '_');
+}
+// Keyed by the SPEC spellings (`ui/animation.zod.ts`). Class values for the
+// shared presets are unchanged; `rotate`/`flip` follow `usePageTransition`'s
+// enter classes (spin-in / fade+zoom), the sibling hook that always carried
+// the full spec vocabulary.
 const EASING_MAP = {
     linear: 'linear',
     ease: 'ease',
-    'ease-in': 'ease-in',
-    'ease-out': 'ease-out',
-    'ease-in-out': 'ease-in-out',
+    ease_in: 'ease-in',
+    ease_out: 'ease-out',
+    ease_in_out: 'ease-in-out',
     spring: 'cubic-bezier(0.34, 1.56, 0.64, 1)',
 };
 const PRESET_CLASSES = {
     fade: 'animate-in fade-in',
-    'slide-up': 'animate-in slide-in-from-bottom-2',
-    'slide-down': 'animate-in slide-in-from-top-2',
-    'slide-left': 'animate-in slide-in-from-right-2',
-    'slide-right': 'animate-in slide-in-from-left-2',
+    slide_up: 'animate-in slide-in-from-bottom-2',
+    slide_down: 'animate-in slide-in-from-top-2',
+    slide_left: 'animate-in slide-in-from-right-2',
+    slide_right: 'animate-in slide-in-from-left-2',
     scale: 'animate-in zoom-in-95',
-    'scale-fade': 'animate-in fade-in zoom-in-95',
+    rotate: 'animate-in spin-in-90',
+    flip: 'animate-in fade-in zoom-in-95',
     none: '',
 };
 /**
@@ -43,7 +69,7 @@ export function useAnimation(config = {}) {
         if (!enabled || preset === 'none') {
             return { className: '', style: {} };
         }
-        const className = PRESET_CLASSES[preset] || '';
+        const className = PRESET_CLASSES[normalizePreset(preset)] || '';
         const style = {};
         if (duration !== undefined) {
             style.animationDuration = `${duration}ms`;
@@ -52,7 +78,12 @@ export function useAnimation(config = {}) {
             style.animationDelay = `${delay}ms`;
         }
         if (easing) {
-            style.animationTimingFunction = EASING_MAP[easing] || easing;
+            // Spec spellings (and legacy hyphen ones) resolve through the map; an
+            // out-of-vocabulary string only passes through when it is plausible raw
+            // CSS (`cubic-bezier(…)`, `steps(…)`) — `ease_in_out` reaching the DOM
+            // verbatim was an invalid declaration the browser silently dropped.
+            style.animationTimingFunction =
+                EASING_MAP[normalizePreset(easing)] ?? (easing.includes('(') ? easing : undefined);
         }
         return { className, style };
     }, [preset, duration, delay, easing, enabled]);

package/dist/hooks/useCapabilityGate.d.ts

@@ -0,0 +1,16 @@
+/**
+ * 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 caller's system capabilities, or `undefined` when the host never supplied
+ * them (→ callers must fail open).
+ */
+export declare function useHeldCapabilities(): string[] | undefined;
+/**
+ * `(requiredPermissions) => mayInvoke`. Actions declaring nothing always pass.
+ */
+export declare function useCapabilityGate(): (required: unknown) => boolean;

package/dist/hooks/useCapabilityGate.js

@@ -0,0 +1,60 @@
+/**
+ * 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.
+ */
+/**
+ * useCapabilityGate — the UI half of ADR-0066 D4's `requiredPermissions`
+ * contract, for surfaces that filter actions THEMSELVES.
+ *
+ * `ActionEngine.getActionsForLocation` applies this gate for everything routed
+ * through the engine. But several renderers filter their own action lists —
+ * `page:header` (record_header / record_more) and the grid's row-action menu
+ * (list_item) — and each of those bypassed the engine entirely, so a button
+ * declaring a capability nobody holds still rendered (framework#3923). One hook
+ * so all three surfaces gate identically and can't drift apart.
+ *
+ * Source of truth for what the caller holds: the ActionProvider's runner
+ * context (`user.systemPermissions`) — the same object the engine reads — with
+ * the ambient predicate scope as fallback for hosts that mount an
+ * ExpressionProvider but no action runtime.
+ *
+ * **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.
+ */
+import { useCallback, useContext } from 'react';
+import { ActionCtxReact } from '../context/ActionContext';
+import { usePredicateScope } from './useExpression';
+/**
+ * The caller's system capabilities, or `undefined` when the host never supplied
+ * them (→ callers must fail open).
+ */
+export function useHeldCapabilities() {
+    const actionCtx = useContext(ActionCtxReact);
+    const predicateScope = usePredicateScope();
+    const runnerUser = actionCtx?.runner?.getContext?.()?.user;
+    if (Array.isArray(runnerUser?.systemPermissions))
+        return runnerUser.systemPermissions;
+    const scopeUser = predicateScope?.user;
+    if (Array.isArray(scopeUser?.systemPermissions))
+        return scopeUser.systemPermissions;
+    return undefined;
+}
+/**
+ * `(requiredPermissions) => mayInvoke`. Actions declaring nothing always pass.
+ */
+export function useCapabilityGate() {
+    const held = useHeldCapabilities();
+    return useCallback((required) => {
+        if (!Array.isArray(required) || required.length === 0)
+            return true;
+        if (!Array.isArray(held))
+            return true; // unknown → fail open
+        return required.every((p) => typeof p === 'string' && held.includes(p));
+    }, [held]);
+}

package/dist/hooks/useClientNotifications.d.ts

@@ -16,12 +16,6 @@ export interface UseClientNotificationsOptions {
 export interface UseClientNotificationsResult {
     /** Fetch notifications from server */
     fetchNotifications: () => Promise<void>;
-    /** Register device for push notifications */
-    registerDevice: (token: string, platform: string) => Promise<void>;
-    /** Get notification preferences */
-    getPreferences: () => Promise<any>;
-    /** Update notification preferences */
-    updatePreferences: (prefs: any) => Promise<void>;
     /** Mark a notification as read on the server */
     markAsRead: (id: string) => Promise<void>;
     /** Loading state */