@asteby/metacore-runtime-react 36.1.0 → 37.0.1

package/dist/realtime-context.js

@@ -0,0 +1,182 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+// realtime-context — React surface over the host's RealtimeAPI
+// (`@asteby/metacore-sdk`): a provider the host mounts once, `useRealtime`
+// for handlers, `useRealtimeInvalidate` to refresh react-query caches, and
+// `useRealtimeTick` — the opt-in refetch signal `DynamicTable` /
+// `DynamicKanban` consume through their `realtime` prop.
+//
+// Module-federation note: a federated addon may run its OWN copy of this
+// module, in which case React context from the host is invisible to it. Every
+// hook therefore accepts an explicit `client` (pass `host.realtime` or
+// `api.realtime`) that wins over the context — the plain object crosses the
+// federation boundary, the context does not.
+//
+// react-query: `useRealtimeInvalidate` uses `useQueryClient()` so it always
+// targets the QueryClient the host mounted (single instance per page).
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react';
+import { useQueryClient } from '@tanstack/react-query';
+const RealtimeContext = createContext({ client: null, defaultRealtime: false });
+/**
+ * Mount once, inside the host's WebSocket provider and QueryClientProvider.
+ * `client` may be null while the host is still connecting — hooks become
+ * no-ops and re-subscribe when a client appears.
+ */
+export function RealtimeProvider({ client, defaultRealtime = false, children }) {
+    const value = useMemo(() => ({ client: client ?? null, defaultRealtime }), [client, defaultRealtime]);
+    return _jsx(RealtimeContext.Provider, { value: value, children: children });
+}
+/** The host realtime client from context (null when none is mounted). */
+export function useRealtimeClient(explicit) {
+    const ctx = useContext(RealtimeContext);
+    return explicit ?? ctx.client;
+}
+/** Whether dynamic components should refetch on data events by default. */
+export function useRealtimeDefault() {
+    return useContext(RealtimeContext).defaultRealtime;
+}
+/**
+ * Subscribe to data events for the given models. The handler is kept in a
+ * ref so callers don't need to memoise it; the subscription is torn down on
+ * unmount and re-created when models/events/client change.
+ *
+ *   useRealtime({ models: ['SalesOrder'], client: host.realtime }, (e) => {
+ *     if (e.action === 'resync' || e.id === currentId) refetch()
+ *   })
+ */
+export function useRealtime(options, handler) {
+    const client = useRealtimeClient(options.client);
+    const handlerRef = useRef(handler);
+    handlerRef.current = handler;
+    const enabled = options.enabled ?? true;
+    const modelsKey = (options.models ?? []).map((m) => m.trim().toLowerCase()).sort().join('|');
+    const eventsKey = (options.events ?? []).slice().sort().join('|');
+    useEffect(() => {
+        if (!client || !enabled || !modelsKey)
+            return;
+        const models = modelsKey.split('|');
+        const events = eventsKey ? eventsKey.split('|') : undefined;
+        let off = () => { };
+        try {
+            off = client.subscribe({ models, events }, (event) => handlerRef.current(event));
+        }
+        catch {
+            /* a host client must not throw, but never take the page down */
+        }
+        return off;
+    }, [client, enabled, modelsKey, eventsKey]);
+}
+/** Live status of the realtime client ('closed' when none). */
+export function useRealtimeStatus(explicit) {
+    const client = useRealtimeClient(explicit);
+    const [status, setStatus] = useState(() => client?.status() ?? 'closed');
+    useEffect(() => {
+        if (!client) {
+            setStatus('closed');
+            return;
+        }
+        setStatus(client.status());
+        if (!client.onStatus)
+            return;
+        return client.onStatus(setStatus);
+    }, [client]);
+    return status;
+}
+/** Default matcher: any string segment of the query key (case-insensitive)
+ *  equals the event's model, table or `addon.model`, or contains the model
+ *  as a path segment (`/data/sales_orders`). */
+export function queryKeyMatchesEvent(queryKey, event) {
+    const needles = [event.model, event.table ?? '', `${event.addon}.${event.model}`]
+        .map((s) => s.toLowerCase())
+        .filter(Boolean);
+    const parts = flattenKey(queryKey);
+    for (const part of parts) {
+        const p = part.toLowerCase();
+        for (const n of needles) {
+            if (p === n)
+                return true;
+            // '/data/sales_orders?x=1' or 'pos/SalesOrder' style segments.
+            const segs = p.split(/[/?&=]/);
+            if (segs.includes(n))
+                return true;
+        }
+    }
+    return false;
+}
+function flattenKey(key, out = [], depth = 0) {
+    if (depth > 4)
+        return out;
+    for (const item of key) {
+        if (typeof item === 'string')
+            out.push(item);
+        else if (Array.isArray(item))
+            flattenKey(item, out, depth + 1);
+        else if (item && typeof item === 'object') {
+            for (const v of Object.values(item)) {
+                if (typeof v === 'string')
+                    out.push(v);
+            }
+        }
+    }
+    return out;
+}
+/**
+ * Invalidate every react-query query whose key mentions the event's model /
+ * table (see `queryKeyMatchesEvent`). Uses the host's QueryClient. Bursts
+ * are debounced so a coalesced frame storm becomes a single refetch round.
+ *
+ *   useRealtimeInvalidate({ models: ['SalesOrder', 'sales_order_items'], client: host.realtime })
+ */
+export function useRealtimeInvalidate(options) {
+    const queryClient = useQueryClient();
+    const { match = queryKeyMatchesEvent, debounceMs = 250, onEvent } = options;
+    const pendingRef = useRef([]);
+    const timerRef = useRef(null);
+    const matchRef = useRef(match);
+    matchRef.current = match;
+    const onEventRef = useRef(onEvent);
+    onEventRef.current = onEvent;
+    const flush = useCallback(() => {
+        timerRef.current = null;
+        const batch = pendingRef.current;
+        pendingRef.current = [];
+        if (batch.length === 0)
+            return;
+        void queryClient.invalidateQueries({
+            predicate: (query) => batch.some((event) => matchRef.current(query.queryKey, event)),
+        });
+    }, [queryClient]);
+    useRealtime(options, (event) => {
+        pendingRef.current.push(event);
+        onEventRef.current?.(event);
+        if (timerRef.current)
+            return;
+        timerRef.current = setTimeout(flush, debounceMs);
+    });
+    useEffect(() => () => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+    }, []);
+}
+/**
+ * A counter that increments (debounced) whenever a data event lands for one
+ * of `models`. Fold it into a refetch effect's dependencies — that is exactly
+ * what `DynamicTable` / `DynamicKanban` do behind their `realtime` prop.
+ */
+export function useRealtimeTick(options) {
+    const [tick, setTick] = useState(0);
+    const timerRef = useRef(null);
+    const debounceMs = options.debounceMs ?? 300;
+    useRealtime({ models: options.models, client: options.client, enabled: options.enabled }, () => {
+        if (timerRef.current)
+            return;
+        timerRef.current = setTimeout(() => {
+            timerRef.current = null;
+            setTick((t) => t + 1);
+        }, debounceMs);
+    });
+    useEffect(() => () => {
+        if (timerRef.current)
+            clearTimeout(timerRef.current);
+    }, []);
+    return tick;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@asteby/metacore-runtime-react",
-  "version": "36.1.0",
+  "version": "37.0.1",
   "description": "React runtime for metacore hosts — renders addon contributions dynamically",
   "repository": {
     "type": "git",
@@ -37,7 +37,7 @@
     "react-i18next": ">=13",
     "sonner": ">=1.7",
     "zustand": ">=5",
-    "@asteby/metacore-sdk": "^3.6.0",
+    "@asteby/metacore-sdk": "^3.7.0",
     "@asteby/metacore-ui": "^2.17.3"
   },
   "peerDependenciesMeta": {
@@ -67,7 +67,7 @@
     "typescript": "^6.0.0",
     "vitest": "^4.0.0",
     "zustand": "^5.0.0",
-    "@asteby/metacore-sdk": "3.6.0",
+    "@asteby/metacore-sdk": "3.7.0",
     "@asteby/metacore-ui": "2.17.3"
   },
   "scripts": {

package/src/__tests__/metadata-label-i18n.test.ts

@@ -0,0 +1,19 @@
+import { describe, expect, it, vi } from 'vitest'
+import { translateMetadataLabel } from '../dynamic-columns-helpers'
+
+describe('translateMetadataLabel', () => {
+    it('resolves a host translation when available', () => {
+        const t = vi.fn(() => 'Estado del pago')
+        expect(translateMetadataLabel('models.orders.payment_status', t)).toBe('Estado del pago')
+        expect(t).toHaveBeenCalledWith('models.orders.payment_status', { defaultValue: 'Payment Status' })
+    })
+
+    it('humanizes the final segment when an addon locale is not loaded', () => {
+        const t = vi.fn((key: string) => key)
+        expect(translateMetadataLabel('models.addon.fields.custom_code', t)).toBe('Custom Code')
+    })
+
+    it('preserves already human labels', () => {
+        expect(translateMetadataLabel('Nombre comercial')).toBe('Nombre comercial')
+    })
+})

package/src/__tests__/realtime-context.test.tsx

@@ -0,0 +1,195 @@
+// @vitest-environment happy-dom
+//
+// Realtime hooks over a fake RealtimeAPI: useRealtime subscribes/unsubscribes
+// with normalised models, an explicit client beats the context (federation
+// boundary), useRealtimeInvalidate targets the host QueryClient by key match,
+// and useRealtimeTick debounces bursts into one bump.
+import { afterEach, describe, expect, it, vi } from 'vitest'
+import { act, cleanup, renderHook } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import type { ReactNode } from 'react'
+import type { DataEvent, DataEventHandler, RealtimeAPI, RealtimeSubscribeOptions } from '@asteby/metacore-sdk'
+import {
+    RealtimeProvider,
+    queryKeyMatchesEvent,
+    useRealtime,
+    useRealtimeInvalidate,
+    useRealtimeStatus,
+    useRealtimeTick,
+} from '../realtime-context'
+
+afterEach(cleanup)
+
+function fakeClient() {
+    const subs: Array<{ opts: RealtimeSubscribeOptions; handler: DataEventHandler }> = []
+    const statusListeners = new Set<(s: 'connecting' | 'open' | 'closed') => void>()
+    let status: 'connecting' | 'open' | 'closed' = 'open'
+    const client: RealtimeAPI & { subs: typeof subs; emit: (e: DataEvent) => void; setStatus: (s: typeof status) => void } = {
+        subs,
+        subscribe(opts, handler) {
+            const entry = { opts, handler }
+            subs.push(entry)
+            return () => {
+                const i = subs.indexOf(entry)
+                if (i >= 0) subs.splice(i, 1)
+            }
+        },
+        status: () => status,
+        onStatus(l) {
+            statusListeners.add(l)
+            return () => statusListeners.delete(l)
+        },
+        emit(e) {
+            subs.forEach((s) => s.handler(e))
+        },
+        setStatus(s) {
+            status = s
+            statusListeners.forEach((l) => l(s))
+        },
+    }
+    return client
+}
+
+const event = (over: Partial<DataEvent> = {}): DataEvent => ({
+    org_id: 'org',
+    addon: 'pos',
+    model: 'SalesOrder',
+    table: 'sales_orders',
+    action: 'updated',
+    id: '1',
+    at: '2026-08-31T00:00:00Z',
+    ...over,
+})
+
+describe('useRealtime', () => {
+    it('subscribes through the context client with normalised models and tears down on unmount', () => {
+        const client = fakeClient()
+        const handler = vi.fn()
+        const wrapper = ({ children }: { children: ReactNode }) => (
+            <RealtimeProvider client={client}>{children}</RealtimeProvider>
+        )
+        const { unmount } = renderHook(() => useRealtime({ models: [' SalesOrder ', 'WorkOrder'] }, handler), { wrapper })
+        expect(client.subs).toHaveLength(1)
+        expect(client.subs[0]!.opts.models).toEqual(['salesorder', 'workorder'])
+        client.emit(event())
+        expect(handler).toHaveBeenCalledTimes(1)
+        unmount()
+        expect(client.subs).toHaveLength(0)
+    })
+
+    it('prefers an explicit client over the context (federated addons)', () => {
+        const ctxClient = fakeClient()
+        const explicit = fakeClient()
+        const wrapper = ({ children }: { children: ReactNode }) => (
+            <RealtimeProvider client={ctxClient}>{children}</RealtimeProvider>
+        )
+        renderHook(() => useRealtime({ models: ['SalesOrder'], client: explicit }, () => {}), { wrapper })
+        expect(explicit.subs).toHaveLength(1)
+        expect(ctxClient.subs).toHaveLength(0)
+    })
+
+    it('is a no-op without a client, without models, or when disabled', () => {
+        const client = fakeClient()
+        renderHook(() => useRealtime({ models: ['SalesOrder'] }, () => {}))
+        renderHook(() => useRealtime({ models: [], client }, () => {}))
+        renderHook(() => useRealtime({ models: ['SalesOrder'], client, enabled: false }, () => {}))
+        expect(client.subs).toHaveLength(0)
+    })
+})
+
+describe('useRealtimeStatus', () => {
+    it('tracks the client status', () => {
+        const client = fakeClient()
+        const { result } = renderHook(() => useRealtimeStatus(client))
+        expect(result.current).toBe('open')
+        act(() => client.setStatus('connecting'))
+        expect(result.current).toBe('connecting')
+        const { result: none } = renderHook(() => useRealtimeStatus(null))
+        expect(none.current).toBe('closed')
+    })
+})
+
+describe('queryKeyMatchesEvent', () => {
+    it('matches model, table, qualified name and path segments (case-insensitive)', () => {
+        const e = event()
+        expect(queryKeyMatchesEvent(['salesorder', 'list'], e)).toBe(true)
+        expect(queryKeyMatchesEvent(['data', 'sales_orders', { page: 1 }], e)).toBe(true)
+        expect(queryKeyMatchesEvent(['pos.SalesOrder'], e)).toBe(true)
+        expect(queryKeyMatchesEvent(['/data/sales_orders?page=1'], e)).toBe(true)
+        expect(queryKeyMatchesEvent([{ model: 'SalesOrder' }], e)).toBe(true)
+        expect(queryKeyMatchesEvent(['work_orders'], e)).toBe(false)
+        expect(queryKeyMatchesEvent(['sales_orders_archive'], e)).toBe(false)
+    })
+})
+
+describe('useRealtimeInvalidate', () => {
+    it('invalidates only the queries whose key mentions the event model, debounced', async () => {
+        vi.useFakeTimers()
+        try {
+            const client = fakeClient()
+            const queryClient = new QueryClient()
+            queryClient.setQueryData(['sales_orders', 'list'], [])
+            queryClient.setQueryData(['work_orders', 'list'], [])
+            const invalidate = vi.spyOn(queryClient, 'invalidateQueries')
+            const wrapper = ({ children }: { children: ReactNode }) => (
+                <QueryClientProvider client={queryClient}>
+                    <RealtimeProvider client={client}>{children}</RealtimeProvider>
+                </QueryClientProvider>
+            )
+            const onEvent = vi.fn()
+            renderHook(() => useRealtimeInvalidate({ models: ['SalesOrder'], debounceMs: 100, onEvent }), { wrapper })
+
+            act(() => {
+                client.emit(event({ id: '1' }))
+                client.emit(event({ id: '2' }))
+            })
+            expect(onEvent).toHaveBeenCalledTimes(2)
+            expect(invalidate).not.toHaveBeenCalled()
+            act(() => {
+                vi.advanceTimersByTime(120)
+            })
+            expect(invalidate).toHaveBeenCalledTimes(1)
+            const predicate = (invalidate.mock.calls[0]![0] as { predicate: (q: { queryKey: unknown[] }) => boolean }).predicate
+            expect(predicate({ queryKey: ['sales_orders', 'list'] })).toBe(true)
+            expect(predicate({ queryKey: ['work_orders', 'list'] })).toBe(false)
+            expect(queryClient.getQueryState(['sales_orders', 'list'])?.isInvalidated).toBe(true)
+            expect(queryClient.getQueryState(['work_orders', 'list'])?.isInvalidated).toBe(false)
+        } finally {
+            vi.useRealTimers()
+        }
+    })
+})
+
+describe('useRealtimeTick', () => {
+    it('bumps once per burst and stays quiet when disabled', () => {
+        vi.useFakeTimers()
+        try {
+            const client = fakeClient()
+            const { result, rerender } = renderHook(
+                ({ enabled }: { enabled: boolean }) =>
+                    useRealtimeTick({ models: ['SalesOrder'], client, enabled, debounceMs: 50 }),
+                { initialProps: { enabled: true } },
+            )
+            expect(result.current).toBe(0)
+            act(() => {
+                client.emit(event())
+                client.emit(event({ id: '2' }))
+                client.emit(event({ id: '3' }))
+            })
+            expect(result.current).toBe(0)
+            act(() => {
+                vi.advanceTimersByTime(60)
+            })
+            expect(result.current).toBe(1)
+
+            rerender({ enabled: false })
+            expect(client.subs).toHaveLength(0)
+            act(() => {
+                vi.advanceTimersByTime(100)
+            })
+            expect(result.current).toBe(1)
+        } finally {
+            vi.useRealTimers()
+        }
+    })
+})

package/src/__tests__/resolve-row-actions.test.ts

@@ -78,6 +78,20 @@ describe('isRowActionVisible', () => {
         expect(isActionConditionMet({ condition: { field: 's', operator: 'neq', value: 'a' } }, { s: 'a' })).toBe(false)
     })
 
+    it('isActionConditionMet supports truthy/falsy (and the present/set/blank/empty aliases)', () => {
+        const hasBalance = { condition: { field: 'amount_due', operator: 'truthy' } }
+        const noBalance = { condition: { field: 'amount_due', operator: 'falsy' } }
+        expect(isActionConditionMet(hasBalance, { amount_due: 6180 })).toBe(true)
+        expect(isActionConditionMet(hasBalance, { amount_due: 0 })).toBe(false)
+        expect(isActionConditionMet(hasBalance, { amount_due: undefined })).toBe(false)
+        expect(isActionConditionMet(noBalance, { amount_due: 0 })).toBe(true)
+        expect(isActionConditionMet(noBalance, { amount_due: 6180 })).toBe(false)
+        expect(isActionConditionMet({ condition: { field: 'flag', operator: 'present' } }, { flag: 'x' })).toBe(true)
+        expect(isActionConditionMet({ condition: { field: 'flag', operator: 'set' } }, { flag: false })).toBe(false)
+        expect(isActionConditionMet({ condition: { field: 'flag', operator: 'blank' } }, { flag: '' })).toBe(true)
+        expect(isActionConditionMet({ condition: { field: 'flag', operator: 'empty' } }, { flag: 'x' })).toBe(false)
+    })
+
     it('isActionConditionMet resolves nested paths and equals/notEquals aliases', () => {
         const approve = {
             condition: { field: 'user.verified', operator: 'equals', value: false },

package/src/dynamic-columns-helpers.ts

@@ -56,3 +56,25 @@ export function humanizeToken(value: unknown): string {
         })
         .join(' ')
 }
+
+export type MetadataTranslator = (
+    key: string,
+    options?: { defaultValue?: string },
+) => string
+
+/**
+ * Resolve addon-contributed metadata at render time. Known i18n keys use the
+ * host locale; missing keys degrade to a readable label instead of leaking a
+ * machine path such as `models.orders.table.columns.payment_status`.
+ */
+export function translateMetadataLabel(
+    value: string | undefined,
+    translate?: MetadataTranslator,
+): string {
+    if (!value) return ''
+    const token = value.includes('.') ? value.split('.').at(-1) ?? value : value
+    const fallback = humanizeToken(token)
+    if (!translate) return fallback
+    const translated = translate(value, { defaultValue: fallback })
+    return translated && translated !== value ? translated : fallback
+}

package/src/dynamic-columns.tsx

@@ -42,7 +42,7 @@ import {
     relationChipStyles,
 } from '@asteby/metacore-ui/lib'
 import { Progress } from './dialogs/_primitives'
-import { humanizeToken } from './dynamic-columns-helpers'
+import { humanizeToken, translateMetadataLabel } from './dynamic-columns-helpers'
 import { objectLabel } from './dynamic-relation-helpers'
 import {
     OptionBadge,
@@ -244,9 +244,21 @@ export const isActionAllowedForRowState = (action: any, row: any): boolean => {
  * Declarative `condition` gate for a per-row action: shows the action only when
  * the row's `field` satisfies the operator. Supports both the SDK dialect
  * (`eq` | `neq` | `in` | `not_in`) and the common host dialect
- * (`equals` | `notEquals` | `not_in`). Nested paths (`user.verified`) are
- * resolved via `getNestedValue`. No condition → always shown. Unknown
- * operator → permissive.
+ * (`equals` | `notEquals` | `not_in`), plus the truthy/falsy family (same
+ * operator set as the host's document print gate — services/document_gate.go
+ * — kept in sync so a manifest author doesn't have to know which gate a given
+ * contribution goes through). Nested paths (`user.verified`) are resolved via
+ * `getNestedValue`. No condition → always shown.
+ *
+ * `default: return true` for a genuinely unknown operator is deliberate — an
+ * addon shipped against a newer SDK than the host runs should degrade to
+ * "always show" (worst case: an extra menu item), never to "always hide"
+ * (worst case: a feature silently vanishes). That same permissiveness is why
+ * `truthy`/`falsy` going unrecognized here was a real, silent bug rather
+ * than a build error: confirmed live — a `condition: {field: "amount_due",
+ * operator: "truthy"}` row action rendered on every row regardless of
+ * amount_due, because the switch fell through to the default and nothing
+ * ever signaled it wasn't actually gating anything.
  */
 export const isActionConditionMet = (action: any, row: any): boolean => {
     if (!action?.condition) return true
@@ -279,6 +291,14 @@ export const isActionConditionMet = (action: any, row: any): boolean => {
         case 'not_in':
         case 'notin':
             return !values.includes(rowValue)
+        case 'truthy':
+        case 'present':
+        case 'set':
+            return rowValue !== '' && rowValue !== 'false' && rowValue !== '0'
+        case 'falsy':
+        case 'blank':
+        case 'empty':
+            return rowValue === '' || rowValue === 'false' || rowValue === '0'
         default:
             return true
     }
@@ -854,7 +874,7 @@ export function makeDefaultGetDynamicColumns(
             // `visibility` scope (skips `'modal'` and `'list'`).
             if (!isColumnVisibleInTable(col)) return
 
-            const translatedLabel = col.label
+            const translatedLabel = translateMetadataLabel(col.label, t)
             const filterConfig = filterConfigs?.get(col.key)
 
             const columnMeta: Record<string, unknown> = {
@@ -1478,7 +1498,7 @@ export function makeDefaultGetDynamicColumns(
                                             onClick={() => onAction && onAction(action.key, row.original)}
                                         >
                                             <DynamicIcon name={action.icon} className="mr-2 h-4 w-4" />
-                                            {action.label}
+                                            {translateMetadataLabel(action.label, t)}
                                         </DropdownMenuItem>
                                     ))}
                             </DropdownMenuContent>

package/src/dynamic-kanban.tsx

@@ -90,6 +90,7 @@ import {
 import { ColumnFilterControl, FilterValueCombobox, type ColumnFilterType } from '@asteby/metacore-ui/data-table'
 import { generateBadgeStyles, optionColor } from '@asteby/metacore-ui/lib'
 import { useApi } from './api-context'
+import { useRealtimeDefault, useRealtimeTick } from './realtime-context'
 import {
     useStageAutomations,
     StageAutomationsButton,
@@ -462,6 +463,12 @@ export interface DynamicKanbanProps {
     endpoint?: string
     /** Bump to force a metadata + records refetch (same contract as DynamicTable). */
     refreshTrigger?: any
+    /**
+     * Refetch the board when the host's realtime client reports a data event
+     * for this model (same contract as DynamicTable's `realtime`). Off by
+     * default; `<RealtimeProvider defaultRealtime>` flips the default.
+     */
+    realtime?: boolean
     /** Called when a card is clicked (outside its action menu). */
     onCardClick?: (row: any) => void
     /**
@@ -497,6 +504,7 @@ export function DynamicKanban({
     model,
     endpoint,
     refreshTrigger,
+    realtime: realtimeProp,
     onCardClick,
     onAction,
     pageSize = 50,
@@ -508,6 +516,13 @@ export function DynamicKanban({
     const { t, i18n } = useTranslation()
     const api = useApi()
     const isDark = useIsDarkTheme()
+    // Realtime refetch (opt-in) — debounced counter bumped by DATA_EVENTs for
+    // this model; folded into the board refetch effect next to refreshTrigger.
+    const realtimeDefault = useRealtimeDefault()
+    const realtimeTick = useRealtimeTick({
+        models: [model],
+        enabled: realtimeProp ?? realtimeDefault,
+    })
 
     // Stage automations (Bitrix-style per-lane rules). Degrades to no-op when
     // the host has no `/stage-automations` endpoint — the ⚡ affordance hides.
@@ -782,7 +797,9 @@ export function DynamicKanban({
             void fetchData()
         }, 200)
         return () => clearTimeout(handle)
-    }, [fetchData, metadata, refreshTrigger])
+        // realtimeTick: data events for this model (see the `realtime` prop).
+        // eslint-disable-next-line react-hooks/exhaustive-deps
+    }, [fetchData, metadata, refreshTrigger, realtimeTick])
 
     // Filterable fields for the toolbar, in metadata order (explicit filters
     // first, then filterable columns), each labeled from its metadata source.