@nivaro/react 0.3.41 → 0.3.43

package/dist/index.d.ts

@@ -120,6 +120,164 @@ declare interface ActiveLayoutData {
     ungrouped_sort?: number | null;
 }
 
+/** Who really did it (nivaro_activity.actor, migration 516; derived for older rows). */
+declare interface ActivityActor {
+    kind: ActivityActorKind;
+    /** view_as: the admin; api_key: the key id; mcp: the connection; import: the definition
+     *  key; flow: the flow id; cron: the job id. */
+    id?: string | null;
+    name?: string | null;
+    /** The person the actor acted for / as (view_as: the person being viewed as). */
+    on_behalf_of?: string | null;
+}
+
+/**
+ * Activity sentences — one readable line per audit-trail entry.
+ *
+ *   "Pat moved PO 4471 from Draft to Approved"
+ *   "Sam deleted 3 invoices"
+ *   "Rob as Pat changed Vendor on Workflow 85607"
+ *   "Pat updated 40 workflows: Status → On Hold"
+ *
+ * Pure (no imports, no I/O): the Activity page, the activity detail page, the
+ * record history panels and the email digest all render through it. Labels
+ * come from POST /api/activity/labels (records read AS THE READER — a record
+ * the reader cannot see is "a record you can't see"; people by name;
+ * collection / field / choice labels); until they arrive the sentence falls
+ * back to the collection name and the stored id.
+ *
+ * TWIN FILE: packages/shared/src/lib/activity-sentence.ts and
+ * api/src/services/activity-sentence.ts must stay byte-identical (the API
+ * cannot import packages/shared; an API test compares the two files).
+ */
+declare type ActivityActorKind = 'person' | 'view_as' | 'api_key' | 'mcp' | 'import' | 'flow' | 'cron' | 'system';
+
+/** A linked approval decision the read API joined onto the entry. */
+declare interface ActivityApproval {
+    decision: string;
+    comment?: string | null;
+    chain?: string | null;
+    step?: string | number | null;
+    collection?: string | null;
+    item?: string | null;
+}
+
+/** A field change the read API summarised from the revision delta. */
+declare interface ActivityChange {
+    field: string;
+    value?: unknown;
+}
+
+export declare function ActivityEntry({ entry, labels, group, onOpen, actions, showTime, className }: ActivityEntryProps): JSX.Element;
+
+export declare interface ActivityEntryInput {
+    id?: number | string | null;
+    action: string | null;
+    /** The person (nivaro_activity.user); revisions call it user_id. */
+    user?: string | null;
+    user_id?: string | null;
+    first_name?: string | null;
+    last_name?: string | null;
+    user_email?: string | null;
+    collection?: string | null;
+    item?: string | number | null;
+    comment?: string | null;
+    timestamp?: string | Date | null;
+    origin?: string | null;
+    chain_parent?: string | null;
+    auth_method?: string | null;
+    api_key_id?: number | string | null;
+    api_key_name?: string | null;
+    mcp_conn?: string | null;
+    via_app?: string | null;
+    via_agent?: string | null;
+    group_key?: string | null;
+    /** Stored JSON (string) or the parsed object. */
+    actor?: ActivityActor | string | null;
+    changes?: ActivityChange[] | null;
+    changed_fields?: string[] | null;
+    delta?: Record<string, unknown> | null;
+    /** A pipeline event folded into a record's history (services/revisions.ts). */
+    event?: {
+        kind: 'transition' | 'start';
+        from_label?: string | null;
+        to_label?: string | null;
+        transition_label?: string | null;
+        source?: string | null;
+        on_behalf_of?: {
+            id: string;
+            name: string | null;
+        } | null;
+        addendum?: {
+            id: string;
+            title: string | null;
+        } | null;
+    } | null;
+    why?: ActivityWhy | null;
+}
+
+/**
+ * One audit-trail entry as a sentence ("Pat moved PO 4471 from Draft to Approved"), who
+ * really did it (View-as, API key, assistant, import, flow, scheduled job), why (change
+ * reason, transition note, linked approval) and when, in the reader's time zone. A burst
+ * (`group` with more than one entry: one bulk action, import run, flow run, MCP request…)
+ * reads as one line that expands to its entries.
+ *
+ * `actions` is a slot rendered at the row's end (Undo, Open…). Labels come from
+ * `useActivityLabels` (POST /api/activity/labels, read as the viewer).
+ */
+export declare interface ActivityEntryProps {
+    entry: ActivityEntryInput;
+    labels?: ActivityLabels | null;
+    /** The entry's whole burst, newest first (the entry itself included). */
+    group?: ActivityEntryInput[];
+    onOpen?: (entry: ActivityEntryInput) => void;
+    actions?: ReactNode;
+    /** Show the time at the row's end (default true). */
+    showTime?: boolean;
+    className?: string;
+}
+
+/** A list of entries with bursts folded (groupActivity) — each group one ActivityEntry. */
+export declare function ActivityFeed({ entries, labels, onOpen, actionsFor, empty, className }: {
+    entries: ActivityEntryInput[];
+    labels?: ActivityLabels | null;
+    onOpen?: (entry: ActivityEntryInput) => void;
+    /** The `actions` slot for a group's head entry. */
+    actionsFor?: (group: ActivityGroup) => ReactNode;
+    empty?: ReactNode;
+    className?: string;
+}): JSX.Element;
+
+declare interface ActivityGroup<T extends ActivityEntryInput = ActivityEntryInput> {
+    /** Stable React key. */
+    key: string;
+    /** Newest first, as given. */
+    entries: T[];
+    /** 'group_key' = written by one bulk action / import / flow / cron / batch / MCP request;
+     *  'time' = same actor + collection + action within the window (rows before 516). */
+    by: 'group_key' | 'time' | null;
+}
+
+/** What POST /api/activity/labels answers (plus the reader's time zone, if any). */
+export declare interface ActivityLabels {
+    /** Person id (any case) → display name. */
+    users?: Record<string, string>;
+    /** `collection:id` → label; null = the reader cannot see that record. */
+    records?: Record<string, string | null>;
+    /** Collection → names (or a bare display name). */
+    collections?: Record<string, CollectionNames | string>;
+    /** `collection.field` → field label. */
+    fields?: Record<string, string>;
+    /** `collection.field` → stored value → choice label. */
+    choices?: Record<string, Record<string, string>>;
+    /** `collection.field` → the collection a link field points at. Link values are ids, so a
+     *  sentence names the field, never the raw value. */
+    links?: Record<string, string>;
+    /** IANA zone dates in values render in; unset = the runtime's own zone. */
+    timeZone?: string | null;
+}
+
 /** A stretch of the recording where the author was typing in a text field,
  *  or touched nothing at all (#1518). Never what was typed. */
 declare type ActivitySpan = {
@@ -128,6 +286,25 @@ declare type ActivitySpan = {
     end_ms: number;
 };
 
+/** The "why" the read API joins onto an entry (#5): reason, note, approval. */
+declare interface ActivityWhy {
+    /** The change reason a person gave for a create / update / delete. */
+    reason?: string | null;
+    /** What a person wrote on a transition. */
+    note?: string | null;
+    approval?: ActivityApproval | null;
+}
+
+/** The entry's "why" as short lines: change reason, transition note, approval. */
+export declare function activityWhy(entry: ActivityEntryInput): {
+    reason: string | null;
+    note: string | null;
+    approval: string | null;
+};
+
+/** "Pat", "Rob as Pat", "API key “Partner sync”", "Claude for Pat", "Import “Vendors”". */
+export declare function actorName(entry: ActivityEntryInput, labels?: ActivityLabels | null): string;
+
 export declare function AddendumPanel({ collection, item, addendumLayoutId, canCreate, onActiveCountChange, onApplied, onCreated, defaultExpanded }: {
     collection: string;
     item: string;
@@ -786,6 +963,9 @@ export declare interface BackgroundRequest {
  * then offers to hand the read to the server. While the server runs it, the strip shows elapsed
  * time against the usual time; when the result is ready it fills the page's own query and the
  * strip goes away. Every state is inline — no dialog.
+ *
+ * #3231 — from ~3 s it also says what the read is waiting on ("Waiting for a free slot — busy
+ * right now", "Running PUB health — not cached yet"), before and beside the offer.
  */
 export declare function BackgroundRunOffer({ className, ...opts }: UseBackgroundRunOptions & {
     className?: string;
@@ -1052,6 +1232,20 @@ export declare function captureMaskedScreenshot(opts?: {
 
 export declare function captureReplayClip(kind?: ReplayClipKind, timeoutMs?: number): Promise<ReplayLink | null>;
 
+/**
+ * A card placeholder: optional title row, a KPI figure, a chart block or text lines — the shape
+ * of the card that is coming.
+ */
+export declare function CardSkeleton({ title, kpi, chart, lines, className, framed }: {
+    title?: boolean;
+    kpi?: boolean;
+    chart?: boolean;
+    lines?: number;
+    className?: string;
+    /** false = no border/background (the host already draws the card). */
+    framed?: boolean;
+}): JSX.Element;
+
 export { CascadeFilterRule }
 
 declare type CascadeRule = {
@@ -1111,6 +1305,17 @@ declare interface CellFilterLite {
     id_value?: number | null;
 }
 
+/**
+ * Shape-matched loading placeholders (#3229) — the pure half.
+ *
+ * A placeholder takes the shape of what is coming: a list's real columns (a date column gets a
+ * date-sized bar, a status column a pill, a number is right-aligned), a record form's real
+ * sections and field widths when its layout is known before the record, a card's header and
+ * lines. Widths are deterministic per (row, column) so a skeleton never flickers between renders.
+ * The components live in components/Skeletons.tsx.
+ */
+declare type CellShape = 'text' | 'long' | 'short' | 'number' | 'date' | 'badge' | 'avatar' | 'bool';
+
 /** Shape of the 422 CHANGE_REASON_REQUIRED challenge from the items service. */
 export declare interface ChangeReasonChallenge {
     fields_changed: string[];
@@ -1890,6 +2095,11 @@ export declare function CollectionImportPanel({ initialJobId, onJobOpen }: {
     onJobOpen?: (id: string | null) => void;
 }): JSX.Element;
 
+declare interface CollectionNames {
+    singular?: string | null;
+    plural?: string | null;
+}
+
 /**
  * Realtime sprint client contract. A HOST (admin, a portal app) owns the actual
  * Socket.io connection and provides this to shared components; components
@@ -2044,6 +2254,9 @@ export declare function ConformanceView({ className }: {
     className?: string;
 }): JSX.Element;
 
+/** Pure: may this connection prefetch? Not when it asks to save data or is 2g-slow. */
+export declare function connectionAllowsPrefetch(c: NetInfo | null | undefined): boolean;
+
 /**
  * "Copy as …" (#654): the request behind a list or a record, as a curl
  * command, an SDK call and a GraphQL document, each ready to paste. The
@@ -2480,6 +2693,20 @@ declare interface DisplayPrefs {
 
 export declare function DisplayPrefsCard(): JSX.Element;
 
+/**
+ * The crumbs to show: walk back from the current page, newest first, skipping
+ * the current page itself and repeats (the NEWEST visit of a page wins — the
+ * fewest steps back), and stop after the first "root" page (a list or hub the
+ * person started from) or `max` crumbs. Oldest first.
+ */
+export declare function displayTrail(chain: TrailEntry[], current: {
+    idx: number;
+    path: string;
+}, opts?: {
+    isRoot?: (pathname: string) => boolean;
+    max?: number;
+}): TrailCrumb[];
+
 declare type DmOpener = (userId: string, displayName?: string) => void;
 
 export declare function dmPeer(room: string, self: string): string | null;
@@ -2782,6 +3009,8 @@ export declare interface ErpSubmission {
      *  A record page hosting its OWN External requests dialog already IS that
      *  record, so it never needs this badge and doesn't send it. */
     record_label?: string;
+    /** #18 — a failed push in plain words + Fix it target (null when it did not fail). */
+    explanation?: IntegrationErrorExplanation | null;
 }
 
 export declare interface ErrorReplayLink {
@@ -3248,8 +3477,14 @@ export declare const FORCE_RELOAD_EVENT = "nvr:force-refresh";
  * Unsaved work (lib/unsaved-work.ts) holds the reload: past the deadline the
  * banner says a reload is waiting and reloads the moment the edits are saved
  * or discarded — or when the person clicks Reload now.
+ *
+ * Reload old tabs when idle (#2937): the banner also mounts IdleReloadWatcher, so a tab left on an
+ * older build after a release reloads by itself once idle (no countdown, no banner). Pass
+ * `idleReload={false}` to leave that out.
  */
-export declare function ForceReloadBanner(): JSX.Element | null;
+export declare function ForceReloadBanner({ idleReload }?: {
+    idleReload?: boolean;
+}): JSX.Element;
 
 /**
  * Sticky force refresh — the client half of api/src/services/sticky-refresh.ts.
@@ -3386,6 +3621,45 @@ export declare type FormSchema = {
     slotAssignments: FormSlotAssignment[];
 };
 
+/**
+ * A record form placeholder. With a plan (formSkeletonFromLayout) it paints the form's own tabs,
+ * section titles and field grid; without one, two generic sections.
+ */
+export declare function FormSkeleton({ plan, className }: {
+    plan: FormSkeletonPlan | null;
+    className?: string;
+}): JSX.Element;
+
+declare interface FormSkeletonField {
+    key: string;
+    /** Grid span out of 12. */
+    span: number;
+    /** A grid, widget or slot block (taller than an input). */
+    tall?: boolean;
+}
+
+/**
+ * The resolved layout (GET /collection-layouts/active) → the sections and field widths the form
+ * will paint. Null when there is no layout (the caller shows a generic form placeholder).
+ */
+export declare function formSkeletonFromLayout(layout: LayoutLike | null | undefined, opts?: {
+    isNew?: boolean;
+    maxSections?: number;
+    maxFields?: number;
+}): FormSkeletonPlan | null;
+
+export declare interface FormSkeletonPlan {
+    /** Tab labels, when the form opens on tabs (the first is the one that shows). */
+    tabs: string[];
+    sections: FormSkeletonSection[];
+}
+
+declare interface FormSkeletonSection {
+    key: string;
+    label: string | null;
+    fields: FormSkeletonField[];
+}
+
 export declare type FormSlotAssignment = {
     slot: string;
     groupKey: string | null;
@@ -3591,6 +3865,16 @@ declare interface GridSumCapConfig {
     message?: string;
 }
 
+/**
+ * Folds consecutive entries of one burst into one group. Entries sharing a
+ * group_key always fold; entries without one fold when the same actor did the
+ * same action on the same collection, each within `windowMs` of the previous
+ * (rows from before migration 516). Order is kept; singles are groups of one.
+ */
+export declare function groupActivity<T extends ActivityEntryInput>(entries: T[], opts?: {
+    windowMs?: number;
+}): ActivityGroup<T>[];
+
 /**
  * Run one identity call through the gate: `blocked()` answers without a request while the tab
  * is signed out (outside its probe window); a success opens the gate, a signed-out 401 closes it.
@@ -3891,6 +4175,13 @@ export declare interface HelpVideoDto {
      *  the page. Null when nothing was found or an author dismissed it;
      *  publishing clears it. Optional: older servers. */
     stale?: HelpVideoStale | null;
+    /** #18, GET /help-videos/for only: how the video matched the screen — tier
+     *  0 step, 1 screen, 2 screens like it, 3 record type, 4 area, 5 a term on
+     *  the screen. Optional: older servers. */
+    match?: {
+        tier: number;
+        reason: string;
+    };
 }
 
 export declare function HelpVideoEditor({ videoId, onClose }: {
@@ -3935,6 +4226,28 @@ export declare function HelpVideoLibrary({ watchId, editId, onWatch, onEdit, hea
     headerExtra?: React.ReactNode;
 }): JSX.Element;
 
+/**
+ * #18 — "Watch: How to submit an IR (2:10)": the screen's best help video,
+ * when there is a strong match the person has not finished. Renders nothing
+ * otherwise (no wrapper either), so a host can mount it in its header area
+ * unconditionally. × hides that video's chip for good (this browser).
+ *
+ * Hosts pass the route (`path`) and, when they have one, their page key /
+ * record context; the server ranks screen → screens like it → record type →
+ * area → glossary terms (GET /help-videos/for).
+ */
+export declare function HelpVideoMatchChip({ path, app, page, collection, item, terms, className }: {
+    path: string;
+    app?: string;
+    page?: string;
+    collection?: string;
+    item?: string | number;
+    /** Glossary terms the screen shows. */
+    terms?: string[];
+    /** Classes for the wrapper, which only renders when a chip shows. */
+    className?: string;
+}): JSX.Element;
+
 /** Keyed by video id: switching to another video starts a fresh player, so
  *  progress, the resume point and the one-retry flag never carry over. */
 export declare function HelpVideoPlayer(props: HelpVideoPlayerProps): JSX.Element;
@@ -4147,6 +4460,16 @@ export declare function huddleHolds(prefs: Record<string, unknown> | null | unde
 /** Time without real input before someone counts as idle. */
 export declare const IDLE_AFTER_MS: number;
 
+/**
+ * Reload old tabs when idle (#2937) — renders nothing. Mounted by ForceReloadBanner, so every
+ * host that shows pushed reloads also gets this. The decision is lib/idle-reload.ts
+ * `decideIdleReload` (pure, tested); this only feeds it and acts on it.
+ *
+ * Asks GET /realtime/build-status through the host's NivaroClient when there is one, else the
+ * same-origin /api (admin mounts the banner outside its NivaroProvider).
+ */
+export declare function IdleReloadWatcher(): null;
+
 /** The fields a presence heartbeat should carry. */
 export declare function idleState(): {
     is_idle: boolean;
@@ -4634,8 +4957,9 @@ declare interface InputBinding {
 export declare function installClientChaosFetch(): void;
 
 /**
- * Document-level intent listener: resting on (or keyboard-focusing) a same-origin link
- * preloads its screen's code, and a record link also warms the record. Returns the uninstaller.
+ * Document-level intent listener: resting on (or keyboard-focusing) a same-origin link preloads
+ * its screen's code; a record link also warms the record, a list link the list's metadata.
+ * Leaving the link before pressing it cancels what it started. Returns the uninstaller.
  */
 export declare function installIntentPrefetch(opts: IntentPrefetchOptions): () => void;
 
@@ -4661,6 +4985,17 @@ export declare interface IntegrationDotsProps {
     className?: string;
 }
 
+declare interface IntegrationErrorExplanation {
+    sentence: string;
+    cause: string;
+    fix_label: string | null;
+    fix: IntegrationFixTarget | null;
+    fix_link: string | null;
+    field: string | null;
+    detail: string | null;
+    rule: string;
+}
+
 /**
  * One entry of the integration events feed. The cross-record feed carries
  * `provider`; the per-record feed (GET /integration-events/record/...) carries
@@ -4718,6 +5053,25 @@ export declare type IntegrationEventPathTarget = {
     chainId: string;
 };
 
+/** GET answers' `explanation` (api services/integration-error-explain.ts). */
+declare type IntegrationFixTarget = {
+    kind: 'record';
+    collection: string;
+    item: string;
+    field?: string | null;
+} | {
+    kind: 'external_api';
+    id: number;
+    section?: 'auth' | 'endpoints' | 'connection' | 'response' | null;
+} | {
+    kind: 'partner';
+    id: number;
+} | {
+    kind: 'payload_template';
+    api_id: number;
+    key: string;
+};
+
 export declare function IntegrationObligationsView({ api, className }: IntegrationObligationsViewProps): JSX.Element;
 
 export declare interface IntegrationObligationsViewProps {
@@ -4915,10 +5269,6 @@ export declare interface IntegrationsConsoleTab {
     render: () => ReactNode;
 }
 
-/**
- * HTTP shapes served by GET /integration-signals and /integration-partners —
- * copied from the core routes so the shared package never imports api code.
- */
 export declare interface IntegrationSignalAction {
     kind: 'retry_submission' | 'resend' | 'open' | 'explain' | 'extension';
     label: string;
@@ -4984,12 +5334,29 @@ declare interface IntentPrefetchOptions {
     client: NivaroClient | null;
     /** A link's same-origin path → the record it opens, or null. */
     matchRecord?: (path: string) => RecordTarget | null;
+    /** A link's same-origin path → the collection list it opens, or null (#3230). */
+    matchList?: (path: string) => string | null;
     /** Load the code for the screen a same-origin path opens. */
     preloadRoute?: (path: string) => void;
     /** Only links inside this element (default: the whole document). */
     root?: HTMLElement | Document;
 }
 
+export declare interface IntentProps {
+    onPointerEnter: () => void;
+    onPointerLeave: () => void;
+    onPointerDown: () => void;
+    onFocus: () => void;
+    onBlur: () => void;
+}
+
+/**
+ * Handlers that turn resting on (or focusing) an element into `act()` after INTENT_DWELL_MS,
+ * and leaving it into a cancel of what `act` started (unless it was pressed). `group` names the
+ * intent (e.g. `record:projects:7`); `act` must start its prefetches under that group.
+ */
+export declare function intentProps(group: string, act: () => number | boolean | undefined): IntentProps;
+
 /** A title card before the recording (real extra edited time). Blank
  *  `title` / `subtitle` mean the video's title and the first line of its
  *  description. */
@@ -5283,6 +5650,12 @@ declare interface JsonMapEditorConfig {
     };
 }
 
+/**
+ * A total the person has already seen for this list, from any cached page of it (search, sort
+ * and filters aside) — so "Reading 48,000 invoices" never counts rows they cannot see.
+ */
+export declare function knownTotalFrom(entries: ReadonlyArray<readonly [unknown, unknown]>): number | null;
+
 declare interface LadderTier {
     after_hours: number;
     notify: string;
@@ -5311,6 +5684,15 @@ declare interface LayoutAssignment {
     default_expanded?: boolean | number | null;
 }
 
+declare interface LayoutAssignmentLike {
+    field: string;
+    sort?: number | null;
+    group_key?: string | null;
+    col_span?: number | null;
+    is_visible?: boolean | number | null;
+    widget_id?: number | null;
+}
+
 declare interface LayoutDesign {
     selected: DesignTarget | null;
     onSelect(t: DesignTarget, opts?: SelectOptions): void;
@@ -5382,10 +5764,15 @@ declare interface LayoutDesignProp {
  *
  * Zero CSS shipped — style via className props or data-* attributes.
  */
-export declare function LayoutForm({ form, components, className, style, sectionClassName, tabStripClassName, activeTabClassName, inactiveTabClassName, gridClassName, slotRenderers, itemId, stepperClassName, stepNavClassName, prevButtonClassName, nextButtonClassName, lastStepActions, layoutSlug: _layoutSlug }: LayoutFormProps): default_2.JSX.Element | null;
+export declare function LayoutForm({ form, components, className, style, sectionClassName, tabStripClassName, activeTabClassName, inactiveTabClassName, gridClassName, slotRenderers, itemId, stepperClassName, stepNavClassName, prevButtonClassName, nextButtonClassName, lastStepActions, layoutSlug: _layoutSlug, loadingFallback }: LayoutFormProps): string | number | bigint | boolean | default_2.JSX.Element | Iterable<default_2.ReactNode> | Promise<string | number | bigint | boolean | default_2.ReactPortal | default_2.ReactElement<unknown, string | default_2.JSXElementConstructor<any>> | Iterable<default_2.ReactNode> | null | undefined> | null;
 
 declare type LayoutFormProps = {
     form: UseNivaroFormReturn;
+    /**
+     * #3229 — shown while the schema or the record is still loading (default: nothing, the form
+     * stays headless). Pass a shape-matched placeholder, e.g. `<FormSkeleton plan={…} />`.
+     */
+    loadingFallback?: default_2.ReactNode;
     components?: ComponentOverrides;
     /** CSS class applied to the <form> element */
     className?: string;
@@ -5453,8 +5840,24 @@ declare interface LayoutGroup {
     summary_hide_empty?: boolean | number | null;
 }
 
+declare interface LayoutGroupLike {
+    id?: number | null;
+    key: string;
+    label?: string | null;
+    type?: string | null;
+    sort?: number | null;
+    container_id?: number | null;
+    visibility_mode?: string | null;
+}
+
 export declare type LayoutItem = FormGroupDescriptor | '__ungrouped__';
 
+declare interface LayoutLike {
+    groups?: LayoutGroupLike[] | null;
+    assignments?: LayoutAssignmentLike[] | null;
+    ungrouped_sort?: number | null;
+}
+
 declare interface LayoutMeta {
     id: number;
     name: string;
@@ -5588,6 +5991,11 @@ export declare function ListLoadError({ error, onRetry, className }: {
  */
 export declare function listLoadErrorText(err: unknown): string;
 
+/** The query key a collection list (CollectionBrowserView) reads its metadata under. */
+export declare function listQueryKeys(collection: string): {
+    meta: QueryKey;
+};
+
 /**
  * "Copy as …" (#654): the request a list or record view is making, rendered
  * as a curl command, an SDK call and a GraphQL document. Pure — no client,
@@ -5606,6 +6014,22 @@ declare interface ListRequest {
     page?: number;
 }
 
+/**
+ * A whole list placeholder for surfaces without a real header yet: a header strip (real labels
+ * when given) and rows at the real row height, one bar per column.
+ */
+export declare function ListSkeleton({ columns, rows, header, rowClassName, className }: {
+    columns: readonly (SkeletonColumn & {
+        label?: ReactNode;
+        grow?: number;
+    })[];
+    rows?: number;
+    /** false = no header strip. */
+    header?: boolean;
+    rowClassName?: string;
+    className?: string;
+}): JSX.Element;
+
 /**
  * Query-key heads of surfaces that keep themselves live with their own socket handlers (record
  * pages — RECORD_QUERY_HEADS in item-edit/RecordLiveSync — the collection browser's row reads,
@@ -5977,6 +6401,11 @@ declare interface MatrixEditorConfig {
     };
 }
 
+/** Prefetch requests one tab runs at once; the rest wait their turn. */
+export declare const MAX_PREFETCH_IN_FLIGHT = 2;
+
+declare type MaybeIntent = IntentProps | Record<string, never>;
+
 /**
  * The offset from a few samples: the server stamped its answer somewhere inside the round
  * trip, so assume the midpoint, and trust the sample with the shortest round trip (the least
@@ -6137,6 +6566,11 @@ export declare type NavigationContextValue = {
     helpVideosPath?: string;
 };
 
+declare interface NetInfo {
+    saveData?: boolean;
+    effectiveType?: string;
+}
+
 export declare function networkdaysBetween(a: Date, b: Date): number;
 
 export declare function NewImportDialog({ open, onOpenChange, definitions, runCounts, onQueued }: {
@@ -6284,7 +6718,7 @@ export declare function NotificationAnalyticsView({ className, compactHeader }:
  * click-through routing via the shared notification-target resolver. Needs
  * `<NivaroProvider>`.
  */
-export declare function NotificationBell({ routes, onNavigate, app, subscribe, buttonClassName, panelClassName, beforeList, extraBadge, mailLogUrl, renderTrigger, allPath, subscriptionsPath, onActionError, panelPlacement, tabBadge }: NotificationBellProps): JSX.Element;
+export declare function NotificationBell({ routes, onNavigate, app, subscribe, buttonClassName, panelClassName, beforeList, extraBadge, mailLogUrl, renderTrigger, allPath, subscriptionsPath, rulesPath, onActionError, panelPlacement, tabBadge }: NotificationBellProps): JSX.Element;
 
 export declare interface NotificationBellProps {
     /** Where each notification kind lands in the host app. */
@@ -6322,6 +6756,8 @@ export declare interface NotificationBellProps {
     allPath?: string | null;
     /** Path of the subscriptions page — a watch's "Why me?" offers a Manage link. */
     subscriptionsPath?: string | null;
+    /** Path of Profile → Notification rules — "Why?" offers a change link there (#3078). */
+    rulesPath?: string | null;
     /** Called with an error message when an inline action fails. */
     onActionError?: (message: string) => void;
     /** Where the panel opens relative to the trigger. 'below' (default) keeps
@@ -6360,7 +6796,7 @@ export declare interface NotificationBundle<R = unknown> {
     rows: R[];
 }
 
-export declare function NotificationCenterView({ routes, onNavigate, app, mailLogUrl, subscriptionsPath, onNotice, onError, className }: NotificationCenterViewProps): JSX.Element;
+export declare function NotificationCenterView({ routes, onNavigate, app, mailLogUrl, subscriptionsPath, rulesPath, changesId, onNotice, onError, className }: NotificationCenterViewProps): JSX.Element;
 
 export declare interface NotificationCenterViewProps {
     routes: NotificationRouteMap;
@@ -6369,6 +6805,11 @@ export declare interface NotificationCenterViewProps {
     mailLogUrl?: (mailLogId: number) => string | null;
     /** Host route of the subscriptions page (a watch's "Why me?" links there). */
     subscriptionsPath?: string | null;
+    /** Host route of Profile → Notification rules — "Why?" offers a change link there (#3078). */
+    rulesPath?: string | null;
+    /** #3079 — open on one notification's changes (the email's "See what changed" link lands
+     *  with ?changes=<id>). Undefined = read ?changes= from the address bar. */
+    changesId?: number | null;
     /** Toast hooks — hosts wire their own toaster. */
     onNotice?: (message: string) => void;
     onError?: (message: string) => void;
@@ -6837,6 +7278,8 @@ declare interface PartnerCall {
     triggered_by: string | null;
     has_body: boolean;
     user: PartnerCallUser | null;
+    /** #18 — a failed call in plain words + Fix it target (null when it did not fail). */
+    explanation?: IntegrationErrorExplanation | null;
 }
 
 /** One user recorded on a call — via nivaro_users, batch-resolved server-side
@@ -7062,7 +7505,7 @@ export declare interface PersonProfileData {
     } | null;
 }
 
-export declare type PersonProfileTab = 'overview' | 'access' | 'activity' | 'tools';
+export declare type PersonProfileTab = 'overview' | 'access' | 'activity' | 'did' | 'tools';
 
 /** Mirror of the server's PersonProfile (services/user-profile.ts). */
 declare interface PersonRef {
@@ -7112,7 +7555,7 @@ declare type PipelineBinding = {
     dimensions?: PipelineOwnerDimension[];
 };
 
-export declare type PipelineEditorSection = 'states' | 'transitions' | 'branches' | 'bindings' | 'matrix' | 'simulator' | 'canvas' | 'flow-map' | 'replay' | 'cumulative-flow' | 'migration' | 'coverage' | 'lint' | 'skip-report' | 'ai-review' | 'versions' | 'matrix-versions';
+export declare type PipelineEditorSection = 'states' | 'transitions' | 'branches' | 'bindings' | 'matrix' | 'simulator' | 'canvas' | 'flow-map' | 'replay' | 'cumulative-flow' | 'migration' | 'coverage' | 'lint' | 'skip-report' | 'history' | 'ai-review' | 'versions' | 'matrix-versions';
 
 export declare function PipelineEditorView({ templateId, onBack, onExport, hidden }: {
     templateId: string;
@@ -7282,12 +7725,22 @@ export declare function precisionOf(options: unknown, fallback?: number): number
 /** API prefetches one tab may make in any rolling minute. */
 export declare const PREFETCH_PER_MINUTE = 30;
 
+/**
+ * Warm a collection list: its metadata (fields, relations, browse config) — what the list waits
+ * on before it can ask for rows, and what shapes its loading skeleton. The rows themselves
+ * depend on the person's saved view, sort and filters, so they are not guessed.
+ */
+export declare function prefetchCollectionList(qc: QueryClient, client: NivaroClient, collection: string, opts?: {
+    group?: string | null;
+}): number;
+
 /**
  * Warm a record page: its readOne and the layout it will open with. Returns how many requests
- * went out (0 when both were fresh or the budget was spent).
+ * were queued (0 when both were fresh or the budget was spent).
  */
 export declare function prefetchRecord(qc: QueryClient, client: NivaroClient, collection: string, id: string | number, opts?: {
     layout?: boolean;
+    group?: string | null;
 }): number;
 
 export declare interface PreparedReplayClip {
@@ -7396,7 +7849,7 @@ export declare function ProfileView({ userId, className, initialTab, extra, push
     userId?: string | null;
     className?: string;
     /** Which tab an admin lands on for someone else's page. */
-    initialTab?: 'overview' | 'access' | 'activity' | 'tools';
+    initialTab?: 'overview' | 'access' | 'activity' | 'did' | 'tools';
     /** Host-only cards for the OWN profile (a browser-push card, say), rendered in the right column. */
     extra?: React.ReactNode;
     /** Service worker the Browser notifications card registers (same origin); false hides the card. */
@@ -8321,6 +8774,9 @@ declare type RecordingHandoff = {
     };
 };
 
+/** Feed one location change. Returns the entry now current. */
+export declare function recordNavigation(ev: TrailEvent): TrailEntry | undefined;
+
 /**
  * Mounted ONCE by a host (admin's AppLayout), inside a NivaroProvider and a
  * QueryClientProvider: binds the outbox to the signed-in person so saves left
@@ -8514,6 +8970,18 @@ export declare function registerHelpVideoPage(key: string): () => void;
 
 export declare function registerLayoutSlot(plugin: LayoutSlotPlugin): void;
 
+/**
+ * "Is this tab in the middle of something live that a reload would cut off?" — a live huddle, a
+ * screen clip being recorded. Not unsaved work (that is lib/unsaved-work.ts, the only source of
+ * "unsaved changes"): nothing here is lost to a reload, it is interrupted. Read by the automatic
+ * idle reload (lib/idle-reload.ts), which never reloads while any hold is on.
+ *
+ * Leaf module: the huddle store and the screen clip button report here, so the reload code never
+ * imports the chat code.
+ */
+/** Report something live; the returned function removes it. `active` is read at decision time. */
+export declare function registerReloadHold(label: string, active?: () => boolean): () => void;
+
 /** Called by a host's recorder module. Returns an undo for tests / HMR. */
 export declare function registerReplayCapture(fn: Capture, snap?: Snapshot): () => void;
 
@@ -8533,8 +9001,12 @@ export declare function RelatedRecordsPanel({ collection, itemId, title, default
     defaultExpanded?: boolean;
 }): JSX.Element;
 
-export declare function RelationCombobox({ collection, value, onChange, disabled, placeholder, extraFilter, autoSelectSingle, optionSort, requiredParent, facets, fieldKey, narrowedBy, pinned, missPlacement }: {
+export declare function RelationCombobox({ collection, value, onChange, disabled, placeholder, extraFilter, autoSelectSingle, optionSort, requiredParent, facets, fieldKey, narrowedBy, pinned, missPlacement, defaultOpen, onClose }: {
     collection: string;
+    /** Open the options panel on mount (a list cell's inline editor, #3224). */
+    defaultOpen?: boolean;
+    /** Called when the options panel closes (picked, clicked away or Escape). */
+    onClose?: () => void;
     /** The record-form placement this picker sits on: searches that find
      *  nothing are counted there (#2726). Absent = not reported. */
     missPlacement?: PickerMissPlacement | null;
@@ -8622,6 +9094,12 @@ export declare function releaseGatedReadsOnSharedFetch(cache: QueryCacheLike): (
 
 export declare function releaseHeld(): HeldItem[];
 
+/** "Pat updated 40 workflows: Status → On Hold"; a group of one reads as its entry. */
+export declare function renderActivityGroupSentence(entries: ActivityEntryInput[], labels?: ActivityLabels | null): string;
+
+/** One readable sentence for one activity entry. */
+export declare function renderActivitySentence(entry: ActivityEntryInput, labels?: ActivityLabels | null): string;
+
 export declare type RenderFieldProps = {
     field: any;
     value: unknown;
@@ -9326,6 +9804,13 @@ export declare function setServerClockOffset(ms: number): void;
 
 export declare function setTimeDisplay(mode: string | null | undefined): void;
 
+/**
+ * Name a page in the trail (what later crumbs will show for it): the current
+ * entry — and, when a key is given, only while that key is still current (a
+ * label that lands after the person moved on is dropped, never misfiled).
+ */
+export declare function setTrailLabel(label: string | null | undefined, key?: string): void;
+
 /** True when this browser can share a socket between tabs. */
 export declare function sharedWorkerSupported(): boolean;
 
@@ -9405,6 +9890,27 @@ declare type Size = {
     h: number;
 };
 
+export declare function SkeletonBar({ shape, width, className, style }: {
+    shape?: CellShape;
+    width?: string | number;
+    className?: string;
+    style?: CSSProperties;
+}): JSX.Element;
+
+export declare interface SkeletonColumn {
+    key: string;
+    shape?: CellShape;
+    /** Fixed column width in px (a resized column), when the list has one. */
+    width?: number | null;
+}
+
+/** Real list columns → skeleton columns (types decide the shapes). */
+export declare function skeletonColumnsFrom(keys: readonly string[], fields: ReadonlyArray<{
+    field: string;
+    type?: string | null;
+    interface?: string | null;
+}>, widths?: Record<string, number | undefined>): SkeletonColumn[];
+
 declare type SkipCondition = {
     type: 'no_owners';
 } | {
@@ -9488,6 +9994,80 @@ export declare type SlotRendererProps = {
     defaultExpanded: boolean;
 };
 
+/**
+ * "This is taking a while" with a reason (#3231). Renders nothing until the read has been
+ * loading ~3 s, then says what it is waiting on in plain words ("Reading 48,000 invoices",
+ * "Waiting for Fusion", "Waiting for a free slot — busy right now") with the elapsed time.
+ *
+ *   variant 'inline' — a line inside a loading area (widgets, query results, forms)
+ *   variant 'pill'   — a floating chip; the caller positions it (absolute) so nothing moves
+ *
+ * `children` ride beside the text (e.g. a Run in background button). Reads that can run in the
+ * background use BackgroundRunOffer, which shows the same reason.
+ */
+export declare function SlowNotice({ variant, className, children, reason: given, ...opts }: UseSlowReasonOptions & {
+    variant?: 'inline' | 'pill';
+    className?: string;
+    children?: ReactNode;
+    /** A reason the host already computed with useSlowReason (skips the hook's own asking). */
+    reason?: SlowReason;
+}): JSX.Element | null;
+
+export declare function SlowNoticeView({ reason, variant, className, extra }: {
+    reason: SlowReason;
+    variant?: 'inline' | 'pill';
+    className?: string;
+    extra?: ReactNode;
+}): JSX.Element;
+
+export declare interface SlowReadRequest {
+    method: 'GET' | 'POST';
+    /** API path (with or without /api); a query string is ignored. */
+    url: string;
+}
+
+/** The server's answer (api/src/services/wait-reasons.ts WaitAnswer). */
+export declare interface SlowReadWaitAnswer {
+    found: boolean;
+    kind?: WaitKind;
+    subject?: string | null;
+    shared?: boolean;
+    position?: number | null;
+    of?: number | null;
+    age_ms?: number;
+    statement_ms?: number;
+    rows_so_far?: number;
+    collection?: string | null;
+    /** About how many rows the table holds — administrators only. */
+    table_rows?: number | null;
+    peer?: boolean;
+}
+
+export declare interface SlowReason {
+    /** Loading for at least `afterMs`. */
+    slow: boolean;
+    /** How long it has been loading, ms (0 while not slow). */
+    elapsedMs: number;
+    /** The plain sentence, or null when the server knows nothing useful. */
+    text: string | null;
+    answer: SlowReadWaitAnswer | null;
+}
+
+declare interface SlowReasonContext {
+    /** Plural noun for what a list reads, e.g. "invoices". */
+    noun?: string | null;
+    /** What the page calls this read, e.g. "PUB health" (a query or widget title). */
+    label?: string | null;
+    /** Rows the person can see, when the page already knows (a total from an earlier load). */
+    knownRows?: number | null;
+}
+
+/**
+ * One plain sentence for what a slow read is waiting on, or null when the server knows nothing
+ * useful (the request already finished, another replica not seen yet, cloud mode).
+ */
+export declare function slowReasonText(answer: SlowReadWaitAnswer | null | undefined, ctx?: SlowReasonContext): string | null;
+
 /**
  * Two-phase capture: take the moment NOW (the clip's events, or the live
  * recording's offset), upload later. A support dialog snapshots when it
@@ -9961,6 +10541,23 @@ export declare type SynonymGroups = ReadonlyArray<ReadonlyArray<string>>;
 
 declare type TabKey = 'catalog' | 'rules' | 'subscriptions' | 'history' | 'widget_alerts' | 'widget_alert_history' | 'anomaly_rules' | 'anomaly_history';
 
+/**
+ * Body rows for a real `<table>` whose header is already on screen: one cell per real column
+ * (plus the table's own leading/trailing cells), with the row height and cell padding of the
+ * real rows. Render inside `<tbody>`.
+ */
+export declare function TableSkeletonRows({ columns, rows, rowClassName, cellClassName, leadingCells, trailingCells, cellStyle, barClassName }: {
+    columns: readonly SkeletonColumn[];
+    rows?: number;
+    rowClassName?: string;
+    cellClassName?: string;
+    leadingCells?: number;
+    trailingCells?: number;
+    /** Per-column style (pinned offsets, fixed widths) — the real cells' own. */
+    cellStyle?: (key: string) => CSSProperties | undefined;
+    barClassName?: string;
+}): JSX.Element;
+
 export declare type TabState = {
     activeTab: string | null;
     setActiveTab: (key: string) => void;
@@ -10141,6 +10738,68 @@ export declare function TrafficMiniMap({ window: win, tone, href, refreshMs, cla
     className?: string;
 }): JSX.Element | null;
 
+/**
+ * #3225 — breadcrumbs that know the path. A per-TAB record of the history
+ * entries this tab walked through (sessionStorage, so a reload keeps it and
+ * another tab has its own), keyed by the router's history index. The page
+ * header turns the entries before the current one into crumbs — how the
+ * person actually got here (Queue "Pending approvals" → PO 4471 → Line 3) —
+ * and a crumb click goes BACK that many history entries, so the page comes
+ * back exactly as it was left: same URL (filters, tab), and the scroll
+ * position the trail remembered.
+ *
+ * The host feeds it: call `recordNavigation()` on every location change with
+ * the router's action ('PUSH' | 'REPLACE' | 'POP'), the location key and
+ * `history.state.idx` (React Router keeps the index there across reloads).
+ * Nothing here touches the router, so any host (admin, efp-new) can wire it.
+ *
+ * Pure parts (`reduceTrail`, `trailChain`, `displayTrail`) are tested on their own.
+ */
+declare type TrailAction = 'PUSH' | 'REPLACE' | 'POP';
+
+/** The unbroken run of entries right before the current one, oldest first. */
+export declare function trailChain(state: TrailState): TrailEntry[];
+
+declare interface TrailCrumb {
+    key: string;
+    path: string;
+    label?: string;
+    /** History steps to go back to reach it (negative). */
+    delta: number;
+}
+
+declare interface TrailEntry {
+    key: string;
+    idx: number;
+    /** pathname + search + hash */
+    path: string;
+    label?: string;
+    scroll?: TrailScroll[];
+    at: number;
+}
+
+declare interface TrailEvent {
+    action: TrailAction;
+    key: string;
+    idx: number;
+    path: string;
+    at?: number;
+}
+
+declare interface TrailScroll {
+    /** '' = the page scroller itself; otherwise a child path from it (see scrollPathOf). */
+    path: string;
+    top: number;
+}
+
+declare interface TrailState {
+    entries: TrailEntry[];
+    current: {
+        key: string;
+        idx: number;
+    } | null;
+}
+
 /**
  * Translate scope values (target-collection IDS) into a filter's value space.
  * When the filter compares ids (valueField 'id'/undefined) this is identity;
@@ -10313,6 +10972,15 @@ declare type UploadRow = {
 
 export declare function useActiveGamedays(enabled?: boolean): ActiveGameday[];
 
+/**
+ * Labels for a page of entries, read AS THE VIEWER (POST /api/activity/labels): records they
+ * cannot see come back null ("a record you can't see"), people by display name, collection /
+ * field / choice labels. Adds the viewer's time zone. One request per distinct page.
+ */
+export declare function useActivityLabels(entries: ActivityEntryInput[], opts?: {
+    enabled?: boolean;
+}): ActivityLabels | undefined;
+
 /**
  * `useAfterIdle(ms)` — false on mount, true once the browser has had `ms` of
  * settle time after the first paint. Gate secondary reads on it (freshness
@@ -10645,10 +11313,19 @@ export declare function useHelpVideosFor(ctx: {
     item?: string | number;
     state?: string;
     page?: string;
+    /** #18: the route (`/collections/purchase_orders/12`); the server derives
+     *  the screen, screens like it, the record type and the area from it. */
+    path?: string;
+    /** #18: which app `path` belongs to (default `admin`). */
+    app?: string;
+    /** #18: comma list of glossary terms the screen shows. */
+    terms?: string;
 }, enabled?: boolean): UseQueryResult<NoInfer<{
 data: HelpVideoDto[];
 can_author: boolean;
 state: string | null;
+/** #18: the strong match this person has not finished. Older servers: absent. */
+best_id?: string | null;
 }>, Error>;
 
 /** "Show me on this page": the published version's labelled clicks. */
@@ -10786,6 +11463,9 @@ export declare function useMyScopes(): {
 
 export declare function useNavigation(): NavigationContextValue;
 
+/** The tab's trail, re-rendering on every change. */
+export declare function useNavTrail(): TrailState;
+
 export declare function useNivaroClient(): NivaroClient;
 
 /**
@@ -10911,6 +11591,16 @@ export declare function usePersonProfile(userId: string | null | undefined): Use
 
 export declare function usePlanGridHost(): PlanGridHost | null;
 
+/**
+ * `const intent = usePrefetchIntent()` → spread `{...intent.record(collection, id)}` on a row or
+ * button that opens a record, `{...intent.list(collection)}` on one that opens a list. Inert
+ * without a client (nothing to fetch with).
+ */
+export declare function usePrefetchIntent(): {
+    record: (collection: string, id: string | number) => MaybeIntent;
+    list: (collection: string) => MaybeIntent;
+};
+
 /** Who else is viewing one record (joins its room; names only). */
 export declare function usePresence(collection: string | null | undefined, item: string | number | null | undefined): RecordPresence;
 
@@ -11121,6 +11811,23 @@ action: IntegrationSignalRow["actions"][number];
 
 export declare function useSignals(tab?: string): UseQueryResult<NoInfer<IntegrationSignalsSnapshot>, Error>;
 
+/**
+ * #3231 — after ~3 s of loading, ask the server what this read is waiting on and keep asking
+ * every few seconds while it still loads (hidden tabs skip a beat). Nothing is asked for a read
+ * that finishes in time, so a fast page makes no extra call.
+ */
+export declare function useSlowReason(opts: UseSlowReasonOptions): SlowReason;
+
+declare interface UseSlowReasonOptions extends SlowReasonContext {
+    /** True while the page's own read is still loading. */
+    pending: boolean;
+    /** The read the page is making; null = ask nothing (the notice still says it is slow). */
+    request: SlowReadRequest | null;
+    /** How long before the read counts as slow (default 3 s). */
+    afterMs?: number;
+    enabled?: boolean;
+}
+
 export declare function useSnooze(): {
     add: UseMutationResult<unknown, Error, SnoozeInput, unknown>;
     remove: UseMutationResult<unknown, Error, number, unknown>;
@@ -11327,6 +12034,17 @@ declare type Visibility = {
     role_ids: string[];
 };
 
+/**
+ * "This is taking a while" with a reason (#3231) — the client half of
+ * GET /api/background-runs/waiting.
+ *
+ * The server tells a page what ITS OWN unfinished read is waiting on (a free heavy-read slot and
+ * where it stands in line, an external partner, an uncached query or widget, a statement still
+ * running); this file turns that answer into one plain sentence. Pure — the hook and the notice
+ * live in hooks/useSlowReason.ts and components/SlowNotice.tsx.
+ */
+declare type WaitKind = 'slot' | 'external' | 'query' | 'widget' | 'database' | 'auth' | 'working';
+
 /** One step of "Show me on this page" (GET /help-videos/:id/walk). */
 export declare interface WalkStep {
     label: string;