@cosmicdrift/kumiko-renderer 0.397.0 → 0.399.0

package/dist/app/entity-list-facet-specs.js

@@ -13,6 +13,7 @@ export function resolveEntityFacetSpecs(fields, featureName, entityName, transla
             options: propertyOf(rawDef, "options"),
             entity: propertyOf(rawDef, "entity"),
             labelField: propertyOf(rawDef, "labelField"),
+            optionsQuery: propertyOf(rawDef, "optionsQuery"),
         };
         if (def.filterable !== true)
             continue;
@@ -57,6 +58,7 @@ export function resolveEntityFacetSpecs(fields, featureName, entityName, transla
                     refEntity: target.entityName,
                     refFeature: target.featureName,
                     labelField: typeof def.labelField === "string" ? def.labelField : "id",
+                    ...(typeof def.optionsQuery === "string" && { optionsQuery: def.optionsQuery }),
                 },
             });
         }

package/dist/app/entity-list-screen.js

@@ -25,7 +25,7 @@ import { isDefaultFilterActive, isListNarrowed, useListEmptyContent, } from "./l
 import { buildEntityFilterFacets, buildFacetCountRequests, buildFilterPayload, mergeReferenceFacetOptions, normalizeDefaultFilters, } from "./list-facets.js";
 import { useNav } from "./nav.js";
 import { QueryErrorBanner, QueryLoadingBanner } from "./query-state-banners.js";
-import { ReferenceFacetBridges } from "./reference-facet-bridge.js";
+import { ReferenceFacetBridges, withReferenceFacetState, } from "./reference-facet-bridge.js";
 import { navigateWithReturnTo, useReturnHost } from "./return-to.js";
 import { buildClientActionRowAction, buildDefaultEditRowAction, buildDrawerRowAction, buildProjectionToolbarActions, buildWriteHandlerRowAction, findRowClickAction, navigateActionSearchParams, runDrawerRowAction, } from "./row-actions.js";
 import { findEditScreenFor } from "./screen-access.js";
@@ -154,7 +154,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
         await refreshListAfterWrite();
     }, [refreshFacetCounts, refreshListAfterWrite]);
     const [entityReferenceFacetOptions, setEntityReferenceFacetOptions] = useState({});
-    const handleEntityFacetOptions = useCallback((field, options) => setEntityReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
+    const handleEntityFacetOptions = useCallback((field, state) => setEntityReferenceFacetOptions((prev) => withReferenceFacetState(prev, field, state)), []);
     const [facetCounts, setFacetCounts] = useState({});
     const handleFacetCount = useCallback((key, count) => setFacetCounts((prev) => (prev[key] === count ? prev : { ...prev, [key]: count })), []);
     const filterFacets = useMemo(() => buildEntityFilterFacets(mergeReferenceFacetOptions(entityFacetSpecs, entityReferenceFacetOptions), screen.facets, effectiveTranslate, facetCounts), [entityFacetSpecs, entityReferenceFacetOptions, screen.facets, effectiveTranslate, facetCounts]);
@@ -395,7 +395,7 @@ function EntityListBody({ schema, screen, entity, translate, onRowClick, }) {
     // arrives async; until it is there RenderList renders the table without a
     // pager (the pager has its own total>0 guard).
     const pager = listPager({ usePager, page: listRows.page, limit, urlState });
-    return (_jsxs(_Fragment, { children: [refetchErrorBanner, _jsx(ListGroupPageBridges, { ...listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, onOptions: handleEntityFacetOptions }), _jsx(FacetCountBridges, { queryType: queryType, queries: facetCountQueries, onCount: handleFacetCount, refreshNonce: facetCountRefreshNonce }), _jsx(RenderList, { screen: screen, entity: entity, rows: listRows.rows, featureName: featureName, searchable: searchable, narrowed: isListNarrowed(urlState.q, urlState.filters, defaultFilters), defaultFilterActive: isDefaultFilterActive(urlState.q, urlState.filters, defaultFilters), ...(screen.description !== undefined && {
+    return (_jsxs(_Fragment, { children: [refetchErrorBanner, _jsx(ListGroupPageBridges, { ...listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: entityFacetSpecs, selected: urlState.filters, onState: handleEntityFacetOptions }), _jsx(FacetCountBridges, { queryType: queryType, queries: facetCountQueries, onCount: handleFacetCount, refreshNonce: facetCountRefreshNonce }), _jsx(RenderList, { screen: screen, entity: entity, rows: listRows.rows, featureName: featureName, searchable: searchable, narrowed: isListNarrowed(urlState.q, urlState.filters, defaultFilters), defaultFilterActive: isDefaultFilterActive(urlState.q, urlState.filters, defaultFilters), ...(screen.description !== undefined && {
                     description: effectiveTranslate(screen.description),
                 }), ...(emptyContent !== undefined && { emptyContent }), searchValue: urlState.q, onSearchChange: urlState.setQ, sort: effectiveSort, onSortChange: urlState.setSort, ...(isEmbeddedScreen
                     ? { screenPadding: false, chromeless: true }

package/dist/app/list-facets.d.ts

@@ -1,6 +1,7 @@
 import type { EntityListFacetConfig, ListFacetSpec } from "@cosmicdrift/kumiko-framework/ui-types";
 import type { Translate } from "../headless/index.ts";
 import type { DataTableFacet, DataTableFacetChip } from "../primitives.tsx";
+import type { ReferenceFacetState } from "./reference-facet-bridge.tsx";
 export type ResolvedFacetSpec = {
     readonly field: string;
     readonly type: "select" | "boolean" | "reference";
@@ -17,12 +18,14 @@ export type ResolvedFacetSpec = {
         readonly refEntity: string;
         readonly refFeature: string;
         readonly labelField: string;
+        /** Author handler that serves the options instead of the entity list. */
+        readonly optionsQuery?: string;
     };
+    /** Reference facets only: set once the bridge resolved it. Makes the facet searchable. */
+    readonly onSearchChange?: (query: string) => void;
+    readonly searching?: boolean;
 };
-export declare function mergeReferenceFacetOptions(specs: readonly ResolvedFacetSpec[], optionsByField: Readonly<Record<string, readonly {
-    readonly value: string;
-    readonly label: string;
-}[]>>): ResolvedFacetSpec[];
+export declare function mergeReferenceFacetOptions(specs: readonly ResolvedFacetSpec[], stateByField: Readonly<Record<string, ReferenceFacetState>>): ResolvedFacetSpec[];
 export declare function buildFilterFacets(specs: readonly ResolvedFacetSpec[]): DataTableFacet[];
 type FacetConfigByField = Readonly<Record<string, EntityListFacetConfig | false>>;
 export declare function buildFacetChips(spec: ResolvedFacetSpec, config: EntityListFacetConfig, translate: Translate): DataTableFacetChip[];

package/dist/app/list-facets.js

@@ -4,13 +4,30 @@ import { parseRefTarget } from "@cosmicdrift/kumiko-framework/ui-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 // Fills in a "reference" spec's initially-empty `options` from the
 // field-keyed options ReferenceFacetBridges resolved, shared by every caller.
-export function mergeReferenceFacetOptions(specs, optionsByField) {
-    return specs.map((spec) => spec.reference !== undefined
-        ? { ...spec, options: optionsByField[spec.field] ?? spec.options }
-        : spec);
+export function mergeReferenceFacetOptions(specs, stateByField) {
+    return specs.map((spec) => {
+        const state = stateByField[spec.field];
+        return spec.reference !== undefined && state !== undefined
+            ? {
+                ...spec,
+                options: state.options,
+                onSearchChange: state.onSearchChange,
+                searching: state.searching,
+            }
+            : spec;
+    });
+}
+function facetBase(spec) {
+    return {
+        field: spec.field,
+        label: spec.label,
+        options: spec.options,
+        ...(spec.onSearchChange !== undefined && { onSearchChange: spec.onSearchChange }),
+        ...(spec.searching !== undefined && { searching: spec.searching }),
+    };
 }
 export function buildFilterFacets(specs) {
-    return specs.map((spec) => ({ field: spec.field, label: spec.label, options: spec.options }));
+    return specs.map(facetBase);
 }
 // Chips are the field's own options plus the declared extra choices
 // ("Running" bundle, "All"), in the order the config's `position` asks for.
@@ -39,7 +56,7 @@ export function buildEntityFilterFacets(specs, configs, translate, counts) {
         const config = configs?.[spec.field];
         if (config === false)
             continue;
-        const base = { field: spec.field, label: spec.label, options: spec.options };
+        const base = facetBase(spec);
         if (config?.display !== "chips") {
             out.push(base);
             continue;

package/dist/app/projection-list-body.js

@@ -108,7 +108,7 @@ export function ProjectionListBody({ schema, screen, translate, onRowClick, }) {
         limit: query.limit,
         urlState: query.urlState,
     });
-    return (_jsxs(_Fragment, { children: [refetchErrorBanner, actions.toolbarGateQueries, _jsx(ListGroupPageBridges, { ...data.listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: query.facetSpecs, onOptions: query.handleProjectionFacetOptions }), renderProjectionList({
+    return (_jsxs(_Fragment, { children: [refetchErrorBanner, actions.toolbarGateQueries, _jsx(ListGroupPageBridges, { ...data.listTable.aggregates.groupPages }), _jsx(ReferenceFacetBridges, { specs: query.facetSpecs, selected: query.urlState.filters, onState: query.handleProjectionFacetOptions }), renderProjectionList({
                 schema,
                 screen,
                 translate,

package/dist/app/reference-facet-bridge.d.ts

@@ -4,7 +4,19 @@ export type ReferenceFacetOption = {
     readonly value: string;
     readonly label: string;
 };
-export declare function ReferenceFacetBridges({ specs, onOptions, }: {
+/** What a bridge publishes for its facet: the options for the current search term plus the
+ *  handle that changes the term. */
+export type ReferenceFacetState = {
+    readonly options: readonly ReferenceFacetOption[];
+    readonly onSearchChange: (query: string) => void;
+    readonly searching: boolean;
+};
+/** Reducer step for the callers' state: same state keeps the previous object, so an unchanged
+ *  bridge does not re-render the list. */
+export declare function withReferenceFacetState(previous: Readonly<Record<string, ReferenceFacetState>>, field: string, state: ReferenceFacetState): Readonly<Record<string, ReferenceFacetState>>;
+export declare function ReferenceFacetBridges({ specs, selected, onState, }: {
     readonly specs: readonly ResolvedFacetSpec[];
-    readonly onOptions: (field: string, options: readonly ReferenceFacetOption[]) => void;
+    /** The facet selections of the list (field to chosen ids), so chosen values keep their label. */
+    readonly selected: Readonly<Record<string, readonly string[]>>;
+    readonly onState: (field: string, state: ReferenceFacetState) => void;
 }): ReactNode;

package/dist/app/reference-facet-bridge.js

@@ -1,29 +1,48 @@
 import { Fragment as _Fragment, jsx as _jsx } from "react/jsx-runtime";
 // One bridge component per reference facet, mirroring ReferenceLookupBridge —
 // facet count varies per screen, so the hook can't be called in a loop.
-import { useEffect } from "react";
-import { rendererWarn } from "../dev-console.js";
-import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
-import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
-function ReferenceFacetOptionsBridge({ field, refEntity, refFeature, labelField, onOptions, }) {
-    const lookup = useReferenceLookup(refFeature, refEntity, labelField);
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
+import { useQuery } from "../hooks/use-query.js";
+import { referenceOptionSource, storedReferenceRowsPayload, withUnlistedSelectedRows, } from "../hooks/use-reference-lookup.js";
+/** Reducer step for the callers' state: same state keeps the previous object, so an unchanged
+ *  bridge does not re-render the list. */
+export function withReferenceFacetState(previous, field, state) {
+    const before = previous[field];
+    const unchanged = before?.options === state.options &&
+        before.searching === state.searching &&
+        before.onSearchChange === state.onSearchChange;
+    return unchanged ? previous : { ...previous, [field]: state };
+}
+function ReferenceFacetOptionsBridge({ field, refEntity, refFeature, labelField, optionsQuery, selected, onState, }) {
+    const { queryQn, labelKey } = referenceOptionSource({
+        refLabelField: labelField,
+        ...(optionsQuery !== undefined && { refOptionsQuery: optionsQuery }),
+    }, refFeature, refEntity);
+    const [searchTerm, setSearchTerm] = useState("");
+    const payload = useMemo(() => searchTerm === ""
+        ? { limit: REFERENCE_COMBOBOX_LIMIT }
+        : { limit: REFERENCE_COMBOBOX_LIMIT, search: searchTerm }, [searchTerm]);
+    const listed = useQuery(queryQn, payload);
+    // The first page can miss a chosen value; without its row the chip would show the raw id.
+    const chosen = useQuery(queryQn, storedReferenceRowsPayload(optionsQuery !== undefined ? { refOptionsQuery: optionsQuery } : {}, selected, REFERENCE_COMBOBOX_LIMIT), { enabled: selected.length > 0 });
+    const onSearchChange = useCallback((query) => setSearchTerm(query), []);
+    const options = useMemo(() => withUnlistedSelectedRows(listed.data?.rows ?? [], chosen.data?.rows ?? []).map((row) => {
+        const value = String(row["id"] ?? "");
+        return { value, label: String(row[labelKey] ?? value) };
+    }), [listed.data, chosen.data, labelKey]);
+    const searching = listed.loading;
     useEffect(() => {
-        if (lookup.loading)
-            return;
-        // The lookup is one capped list fetch; a full page means the facet may be
-        // missing values the user wants to filter by.
-        if (lookup.map.size >= REFERENCE_LIST_LOOKUP_LIMIT) {
-            rendererWarn(`[kumiko] reference facet "${field}" shows only the first ${REFERENCE_LIST_LOOKUP_LIMIT} ${refEntity} rows; further values cannot be filtered by`);
-        }
-        onOptions(field, [...lookup.map.entries()].map(([value, label]) => ({ value, label })));
-    }, [lookup.loading, lookup.map, field, refEntity, onOptions]);
+        onState(field, { options, onSearchChange, searching });
+    }, [field, options, onSearchChange, searching, onState]);
     return null;
 }
 // One invisible bridge per "reference" facet spec, each publishing its
-// resolved options back via `onOptions` once loaded.
-export function ReferenceFacetBridges({ specs, onOptions, }) {
+// resolved options back via `onState` once loaded.
+export function ReferenceFacetBridges({ specs, selected, onState, }) {
     const referenceSpecs = specs.filter((spec) => spec.reference !== undefined);
     if (referenceSpecs.length === 0)
         return null;
-    return (_jsx(_Fragment, { children: referenceSpecs.map((spec) => (_jsx(ReferenceFacetOptionsBridge, { field: spec.field, refEntity: spec.reference?.refEntity ?? "", refFeature: spec.reference?.refFeature ?? "", labelField: spec.reference?.labelField ?? "id", onOptions: onOptions }, spec.field))) }));
+    return (_jsx(_Fragment, { children: referenceSpecs.map((spec) => (_jsx(ReferenceFacetOptionsBridge, { field: spec.field, refEntity: spec.reference?.refEntity ?? "", refFeature: spec.reference?.refFeature ?? "", labelField: spec.reference?.labelField ?? "id", optionsQuery: spec.reference?.optionsQuery, selected: selected[spec.field] ?? NO_SELECTION, onState: onState }, spec.field))) }));
 }
+const NO_SELECTION = [];

package/dist/app/screen-shared.js

@@ -7,7 +7,7 @@ import { rendererWarn } from "../dev-console.js";
 import { applyFormatSpec } from "../headless/index.js";
 import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
 import { PAGE_SIZE_OPTIONS } from "../hooks/use-list-url-state.js";
-import { referenceLookupSource } from "../hooks/use-reference-lookup.js";
+import { referenceLookupSource, referenceRowsByIdsPayload } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
 import { ISO_DATE_PATTERN, isMoneyValue } from "./entity-edit-prefill.js";
@@ -139,14 +139,7 @@ export async function resolveSuccessMessageParams(screen, featureName, values, d
             return;
         const target = parseRefTarget(def.entity, featureName);
         const { queryQn, labelKey } = referenceLookupSource(target.featureName, target.entityName, def.labelField ?? "id");
-        // Ask for exactly the chosen record so it cannot fall beyond the lookup cap: `ids` is the
-        // by-id input of directory sources, `filters` that of entity list handlers. A source that
-        // knows neither returns its capped list and the scan below still finds the row if present.
-        const lookup = await dispatcher.query(queryQn, {
-            limit: REFERENCE_LIST_LOOKUP_LIMIT,
-            ids: [raw],
-            filters: [{ field: "id", op: "in", value: [raw] }],
-        });
+        const lookup = await dispatcher.query(queryQn, referenceRowsByIdsPayload([raw], REFERENCE_LIST_LOOKUP_LIMIT));
         if (!lookup.isSuccess)
             return;
         const row = lookup.data.rows.find((candidate) => candidate["id"] === raw);

package/dist/app/use-projection-list-query.d.ts

@@ -2,7 +2,7 @@ import type { ProjectionListScreenDefinition } from "@cosmicdrift/kumiko-framewo
 import type { Translate } from "../headless/index.ts";
 import { type ListUrlStateApi } from "../hooks/use-list-url-state.ts";
 import type { synthesizeProjectionEntity } from "./projection-list-shim.ts";
-import type { ReferenceFacetOption } from "./reference-facet-bridge.tsx";
+import { type ReferenceFacetState } from "./reference-facet-bridge.tsx";
 type ProjectionListQueryInput = {
     readonly screen: ProjectionListScreenDefinition;
     readonly featureName: string;
@@ -19,7 +19,7 @@ export declare function useProjectionListQuery(input: ProjectionListQueryInput):
     limit: number;
     usePager: boolean;
     facetSpecs: import("./list-facets.ts").ResolvedFacetSpec[];
-    handleProjectionFacetOptions: (field: string, options: readonly ReferenceFacetOption[]) => void;
+    handleProjectionFacetOptions: (field: string, state: ReferenceFacetState) => void;
     resolvedFacetSpecs: import("./list-facets.ts").ResolvedFacetSpec[];
     dateRangeFacets: import("../data-table-facet-types.ts").DataTableDateRangeFacet[];
     handleDateRangeChange: (field: string, bound: "from" | "to", value: string) => void;

package/dist/app/use-projection-list-query.js

@@ -1,6 +1,7 @@
 import { useCallback, useMemo, useState } from "react";
 import { useListUrlState } from "../hooks/use-list-url-state.js";
 import { buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "./list-facets.js";
+import { withReferenceFacetState } from "./reference-facet-bridge.js";
 import { buildListQueryPayload } from "./screen-shared.js";
 import { useProjectionDateRange } from "./use-projection-date-range.js";
 // Same predicate that makes a header clickable: a stale link onto a
@@ -30,7 +31,7 @@ export function useProjectionListQuery(input) {
     // buildFilterFacets/buildFilterPayload.
     const facetSpecs = useMemo(() => resolveProjectionFacetSpecs(screen.facets, effectiveTranslate, featureName), [screen.facets, effectiveTranslate, featureName]);
     const [projectionReferenceFacetOptions, setProjectionReferenceFacetOptions] = useState({});
-    const handleProjectionFacetOptions = useCallback((field, options) => setProjectionReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
+    const handleProjectionFacetOptions = useCallback((field, state) => setProjectionReferenceFacetOptions((prev) => withReferenceFacetState(prev, field, state)), []);
     const resolvedFacetSpecs = useMemo(() => mergeReferenceFacetOptions(facetSpecs, projectionReferenceFacetOptions), [facetSpecs, projectionReferenceFacetOptions]);
     const filterPayload = useMemo(() => buildFilterPayload(urlState.filters, (field) => facetSpecs.find((spec) => spec.field === field)?.type), [urlState.filters, facetSpecs]);
     const { dateRangePayload, dateRangeFacets, handleDateRangeChange } = useProjectionDateRange(screen.facets, effectiveTranslate, urlState);

package/dist/components/embedded-list-field.js

@@ -4,9 +4,18 @@ import { computeDerivedCellValue, currencyDecimals, groupEmbeddedListIssues, rou
 import { pluralKey } from "../headless/plural-key.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
-import { referenceOptionSource } from "../hooks/use-reference-lookup.js";
+import { referenceOptionSource, storedReferenceRowsPayload, withUnlistedSelectedRows, } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
+function storedCellIds(rows, cellField) {
+    const ids = new Set();
+    for (const row of rows) {
+        const value = row[cellField];
+        if (typeof value === "string" && value !== "")
+            ids.add(value);
+    }
+    return [...ids].sort();
+}
 function withRecomputedDerived(row, derived, cells) {
     if (derived === undefined)
         return row;
@@ -124,6 +133,12 @@ function EmbeddedListFieldInner({ field, id, onChange, allIssues, featureName, }
     useQuery(source.queryQn, {
         limit: REFERENCE_COMBOBOX_LIMIT,
     }));
+    // The first options page can miss a stored value; without its row the cell shows no label.
+    const storedReferenceQueries = referenceCells.map((cell, idx) => {
+        const storedIds = storedCellIds(rows, cell.field);
+        // biome-ignore lint/correctness/useHookAtTopLevel: same fixed per-mount hook count as referenceQueries above.
+        return useQuery(referenceSources[idx]?.queryQn ?? "", storedReferenceRowsPayload(cell, storedIds, REFERENCE_COMBOBOX_LIMIT), { enabled: storedIds.length > 0 });
+    });
     if (EmbeddedListInput === undefined)
         return null;
     const columns = cells.map((cell) => {
@@ -132,7 +147,7 @@ function EmbeddedListFieldInner({ field, id, onChange, allIssues, featureName, }
             const idx = referenceCells.indexOf(cell);
             const query = referenceQueries[idx];
             const labelKey = referenceSources[idx]?.labelKey ?? "id";
-            const referenceOptions = (query?.data?.rows ?? []).map((row) => ({
+            const referenceOptions = withUnlistedSelectedRows(query?.data?.rows ?? [], storedReferenceQueries[idx]?.data?.rows ?? []).map((row) => ({
                 value: String(row["id"] ?? ""),
                 label: String(row[labelKey] ?? row["id"] ?? ""),
             }));

package/dist/components/related-list-section.js

@@ -8,7 +8,7 @@ import { useListBulk } from "../app/list-bulk-actions.js";
 import { buildFilterFacets, buildFilterPayload, mergeReferenceFacetOptions, resolveProjectionFacetSpecs, } from "../app/list-facets.js";
 import { useNav } from "../app/nav.js";
 import { SYNTHESIZED_FIELD_PII_REASON } from "../app/projection-list-shim.js";
-import { ReferenceFacetBridges, } from "../app/reference-facet-bridge.js";
+import { ReferenceFacetBridges, withReferenceFacetState, } from "../app/reference-facet-bridge.js";
 import { navigateWithReturnTo, useReturnHost } from "../app/return-to.js";
 import { buildDefaultEditRowAction, buildProjectionRowActions, buildProjectionToolbarActions, buildRecordActions, findRowClickAction, runDrawerRowAction, runProjectionRowNavigate, } from "../app/row-actions.js";
 import { findEditScreenFor } from "../app/screen-access.js";
@@ -142,7 +142,7 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
     const { search, filters, sort, setSearch, setFilters, setSort, listTable, groupField } = useRelatedListState(section, nav.route?.screenId);
     const facetSpecs = useMemo(() => resolveProjectionFacetSpecs(section.facets, effectiveTranslate, featureName), [section.facets, effectiveTranslate, featureName]);
     const [referenceFacetOptions, setReferenceFacetOptions] = useState({});
-    const handleFacetOptions = useCallback((field, options) => setReferenceFacetOptions((prev) => prev[field] === options ? prev : { ...prev, [field]: options }), []);
+    const handleFacetOptions = useCallback((field, state) => setReferenceFacetOptions((prev) => withReferenceFacetState(prev, field, state)), []);
     const resolvedFacetSpecs = useMemo(() => mergeReferenceFacetOptions(facetSpecs, referenceFacetOptions), [facetSpecs, referenceFacetOptions]);
     const filterPayload = useMemo(() => buildFilterPayload(filters, (field) => resolvedFacetSpecs.find((spec) => spec.field === field)?.type), [filters, resolvedFacetSpecs]);
     const filterFacets = useMemo(() => buildFilterFacets(resolvedFacetSpecs), [resolvedFacetSpecs]);
@@ -332,7 +332,7 @@ export function RelatedListSection({ section, parentId, record, featureName, tra
     // `renderer` stays DOM-free. Stacked (non-tabs) sections keep their own
     // Section card and document-flow height since they render a visible title
     // and aren't confined to a tab panel.
-    const bridges = _jsx(ReferenceFacetBridges, { specs: facetSpecs, onOptions: handleFacetOptions });
+    const bridges = (_jsx(ReferenceFacetBridges, { specs: facetSpecs, selected: filters, onState: handleFacetOptions }));
     if (embedded === true) {
         const countSuffix = listRows.hasData
             ? ` · ${aggregates.serverGroups?.totalCount ?? listRows.rows.length}`

package/dist/components/render-edit-fields-section.js

@@ -10,7 +10,7 @@ function renderTabbedGroupsSection(rc, section, sectionKey) {
     // group cards (Card-in-Card) — the boot-validator rejects that
     // combination in tabs mode, so `sectionActionsEl` is always
     // undefined here at runtime.
-    return rc.wrapWizardStep(sectionKey, _jsx(Card, { options: { framed: false }, children: groupsGrid }, sectionKey));
+    return rc.wrapWizardStep(sectionKey, _jsx(Card, { options: { framed: false }, ...(section.description !== undefined && { slots: { subtitle: section.description } }), children: groupsGrid }, sectionKey));
 }
 function renderTabbedFieldsSection(rc, section, sectionKey) {
     if (section.groups !== undefined)

package/dist/components/render-field-reference.js

@@ -5,11 +5,11 @@ import { useReferenceLinkResolver } from "../app/reference-link.js";
 import { EMPTY_VALUE_PLACEHOLDER } from "../headless/index.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
-import { isCompleteRowPage, referenceOptionSource } from "../hooks/use-reference-lookup.js";
+import { isCompleteRowPage, referenceOptionSource, referenceRowsByIdsPayload, storedReferenceRowsPayload, withUnlistedSelectedRows, } from "../hooks/use-reference-lookup.js";
 import { useTranslation } from "../i18n.js";
 import { usePrimitives } from "../primitives.js";
 import { ReferenceCreateDialog } from "./reference-create-dialog.js";
-import { stringArrayOf } from "./render-field-values.js";
+import { selectedReferenceIds, stringArrayOf } from "./render-field-values.js";
 import { useReferenceInputState } from "./use-reference-input-state.js";
 // ReferenceInput renders a searchable combobox populated by a live query for
 // the referenced entity. With the default limit of 200, larger datasets miss
@@ -64,19 +64,17 @@ export function ReadOnlyReferenceValue({ field, featureName, }) {
     const resolveReferenceLink = useReferenceLinkResolver();
     const refEntity = field.refEntity ?? "";
     const refFeature = field.refFeature ?? featureName;
-    const isMultiple = field.refMultiple === true;
     const { queryQn, labelKey } = referenceOptionSource(field, refFeature, refEntity);
-    const queryResult = useQuery(queryQn, {
-        limit: REFERENCE_COMBOBOX_LIMIT,
-    });
-    const ids = isMultiple
-        ? stringArrayOf(field.value)
-        : typeof field.value === "string" && field.value !== ""
-            ? [field.value]
-            : [];
+    const ids = selectedReferenceIds(field);
+    // An author `refOptionsQuery` keeps its capped picker page; a strict handler schema
+    // that rejects `ids` then only fails the extra stored-rows query.
+    const queryResult = useQuery(queryQn, field.refOptionsQuery === undefined
+        ? referenceRowsByIdsPayload(ids, REFERENCE_COMBOBOX_LIMIT)
+        : { limit: REFERENCE_COMBOBOX_LIMIT }, { enabled: ids.length > 0 });
+    const storedResult = useQuery(queryQn, storedReferenceRowsPayload(field, ids, REFERENCE_COMBOBOX_LIMIT), { enabled: field.refOptionsQuery !== undefined && ids.length > 0 });
     if (ids.length === 0)
         return _jsx(Text, { testId: `field-value-${field.field}`, children: EMPTY_VALUE_PLACEHOLDER });
-    const rows = queryResult.data?.rows ?? [];
+    const rows = withUnlistedSelectedRows(queryResult.data?.rows ?? [], storedResult.data?.rows ?? []);
     // System-scope ids (e.g. SYSTEM_TENANT_ID) never have a backing row —
     // same central fallback as useReferenceLookup (render-list.tsx), so a
     // reference field showing one on the detail path also gets a label

package/dist/components/render-field-values.d.ts

@@ -8,6 +8,10 @@ export declare function resolveNumberUnit(unit: string | {
 } | undefined, row: Readonly<Record<string, unknown>> | undefined): string | undefined;
 export declare function resolveAffix(affix: FieldAffix | undefined, row: Readonly<Record<string, unknown>> | undefined): string | undefined;
 export declare function stringArrayOf(value: unknown): readonly string[];
+export declare function selectedReferenceIds(field: {
+    readonly value: unknown;
+    readonly refMultiple?: boolean;
+}): readonly string[];
 export declare function withPinnedValues(next: readonly string[], options: readonly SelectOptionEntry[], current: readonly string[]): readonly string[];
 export declare function moneyMinorValue(v: unknown, currency: string): number | "";
 export declare function moneyPayload(minorUnits: number | undefined, currency: string): unknown;

package/dist/components/render-field-values.js

@@ -67,6 +67,13 @@ export function stringArrayOf(value) {
         ? value.filter((item) => typeof item === "string")
         : [];
 }
+// The ids a reference field currently points at: the array of a `refMultiple`
+// field, else the single non-empty id.
+export function selectedReferenceIds(field) {
+    if (field.refMultiple === true)
+        return stringArrayOf(field.value);
+    return typeof field.value === "string" && field.value !== "" ? [field.value] : [];
+}
 // The combobox cannot disable a single option, so removals of disabled options
 // the form already holds are merged back.
 export function withPinnedValues(next, options, current) {

package/dist/components/render-list-reference-bridge.d.ts

@@ -1,3 +1,4 @@
 import type { ReactNode } from "react";
-import type { PublishedReferenceLookup, ReferenceColumnSpec } from "./render-list-reference-columns.ts";
-export declare function renderReferenceLookupBridges(referenceColumns: readonly ReferenceColumnSpec[], onMap: (field: string, lookup: PublishedReferenceLookup) => void): ReactNode;
+import { type PublishedReferenceChunk, type ReferenceLookupRequest } from "./render-list-reference-columns.ts";
+export type ReferenceChunkPublisher = (field: string, chunkIndex: number, lookup: PublishedReferenceChunk) => void;
+export declare function renderReferenceLookupBridges(referenceRequests: readonly ReferenceLookupRequest[], onMap: ReferenceChunkPublisher): ReactNode;

package/dist/components/render-list-reference-bridge.js

@@ -1,12 +1,13 @@
 import { jsx as _jsx } from "react/jsx-runtime";
 import { useEffect } from "react";
 import { useReferenceLookup } from "../hooks/use-reference-lookup.js";
+import { referenceChunkKey, } from "./render-list-reference-columns.js";
 // Bridge component for each reference column. It is mounted once per
 // column, calls useReferenceLookup unconditionally, and publishes the map
 // to the parent through onMap. React manages mounting and unmounting when
 // the schema changes through the key prop in the parent's map loop.
-function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMap, }) {
-    const lookup = useReferenceLookup(featureName, refEntity, labelField);
+function ReferenceLookupBridge({ field, chunkIndex, ids, refEntity, labelField, featureName, onMap, }) {
+    const lookup = useReferenceLookup(featureName, refEntity, labelField, ids);
     // Use an effect rather than calling directly so setState runs outside the
     // render path; otherwise React warns about updating one component while
     // rendering another.
@@ -14,12 +15,15 @@ function ReferenceLookupBridge({ field, refEntity, labelField, featureName, onMa
     // "not resolved", whereas an empty published map means "nothing found".
     // Only the latter may display "Unknown".
     const resolved = !lookup.loading && !lookup.failed;
+    const idsKey = referenceChunkKey(ids);
+    // The parent keys this bridge by its ids, so a changed id set remounts it and
+    // useQuery starts loading instead of handing back the previous ids' rows.
     useEffect(() => {
         if (resolved)
-            onMap(field, { map: lookup.map, complete: lookup.complete });
-    }, [field, lookup.map, lookup.complete, resolved, onMap]);
+            onMap(field, chunkIndex, { map: lookup.map, complete: lookup.complete, idsKey });
+    }, [field, chunkIndex, idsKey, lookup.map, lookup.complete, resolved, onMap]);
     return null;
 }
-export function renderReferenceLookupBridges(referenceColumns, onMap) {
-    return referenceColumns.map((rc) => (_jsx(ReferenceLookupBridge, { field: rc.field, refEntity: rc.refEntity, labelField: rc.labelField, featureName: rc.refFeature, onMap: onMap }, rc.field)));
+export function renderReferenceLookupBridges(referenceRequests, onMap) {
+    return referenceRequests.flatMap((request) => request.idChunks.map((ids, chunkIndex) => (_jsx(ReferenceLookupBridge, { field: request.field, chunkIndex: chunkIndex, ids: ids, refEntity: request.refEntity, labelField: request.labelField, featureName: request.refFeature, onMap: onMap }, `${request.field}:${referenceChunkKey(ids)}`))));
 }

package/dist/components/render-list-reference-columns.d.ts

@@ -4,6 +4,8 @@ import type { ReferenceLookupMap } from "../hooks/use-reference-lookup.ts";
 export type PublishedReferenceLookup = {
     readonly map: ReferenceLookupMap;
     readonly complete: boolean;
+    /** The map is from an earlier id set; the current ids are still loading. */
+    readonly pending?: true;
 };
 export type ReferenceColumnSpec = {
     readonly field: string;
@@ -11,6 +13,15 @@ export type ReferenceColumnSpec = {
     readonly refFeature: string;
     readonly labelField: string;
 };
+export type ReferenceLookupRequest = ReferenceColumnSpec & {
+    readonly idChunks: readonly (readonly string[])[];
+};
+export declare function referenceIdChunks(rows: readonly Readonly<Record<string, unknown>>[], field: string, chunkSize: number): string[][];
+export type PublishedReferenceChunk = PublishedReferenceLookup & {
+    readonly idsKey: string;
+};
+export declare function referenceChunkKey(ids: readonly string[]): string;
+export declare function mergeChunkLookups(idChunks: readonly (readonly string[])[], published: Readonly<Record<number, PublishedReferenceChunk>> | undefined): PublishedReferenceLookup | undefined;
 type ResolveReferenceLink = ReturnType<typeof useReferenceLinkResolver>;
 export declare function selectReferenceColumns(columns: readonly ListColumnViewModel[], featureName: string): ReferenceColumnSpec[];
 export type EnrichReferenceColumnsInput = {

package/dist/components/render-list-reference-columns.js

@@ -1,5 +1,47 @@
 import { UNRESOLVED_REFERENCE_LABEL_KEYS } from "@cosmicdrift/kumiko-framework/ui-types";
 import { EMPTY_VALUE_PLACEHOLDER } from "../headless/index.js";
+// Chunks in first-seen order, so appending an infinite-scroll page only
+// re-queries the last chunk; the chunk size stays within the list handler's limit.
+export function referenceIdChunks(rows, field, chunkSize) {
+    const ids = new Set();
+    for (const row of rows) {
+        const value = row[field];
+        for (const entry of Array.isArray(value) ? value : [value]) {
+            if (typeof entry === "string" && entry !== "")
+                ids.add(entry);
+        }
+    }
+    const ordered = [...ids];
+    const chunks = [];
+    for (let start = 0; start < ordered.length; start += chunkSize) {
+        chunks.push(ordered.slice(start, start + chunkSize));
+    }
+    return chunks;
+}
+export function referenceChunkKey(ids) {
+    return ids.join("\n");
+}
+// A chunk last resolved for other ids keeps its labels on screen, but it is
+// `pending` and cannot prove absence until the current ids have loaded.
+export function mergeChunkLookups(idChunks, published) {
+    const chunks = idChunks.map((ids, chunkIndex) => {
+        const chunk = published?.[chunkIndex];
+        return { chunk, current: chunk?.idsKey === referenceChunkKey(ids) };
+    });
+    const resolved = chunks.flatMap(({ chunk }) => (chunk === undefined ? [] : [chunk]));
+    if (resolved.length === 0)
+        return undefined;
+    const pending = !chunks.every(({ current }) => current);
+    const complete = !pending && resolved.every((chunk) => chunk.complete);
+    const only = resolved.length === 1 && chunks.length === 1 ? resolved[0] : undefined;
+    if (only !== undefined && !pending)
+        return only;
+    const map = new Map();
+    for (const chunk of resolved)
+        for (const [id, label] of chunk.map)
+            map.set(id, label);
+    return { map, complete, ...(pending && { pending }) };
+}
 function isPlainRecord(value) {
     return typeof value === "object" && value !== null && !Array.isArray(value);
 }
@@ -32,7 +74,7 @@ export function selectReferenceColumns(columns, featureName) {
 function unresolvedLabelFor(unknownKey, published, translate) {
     return (id) => unknownKey === undefined
         ? id
-        : published === undefined
+        : published === undefined || published.pending === true
             ? EMPTY_VALUE_PLACEHOLDER
             : published.complete
                 ? translate(unknownKey)

package/dist/components/render-list.js

@@ -24,7 +24,7 @@ export function RenderList(props) {
     const [menuActionBusyId, setMenuActionBusyId] = useState(null);
     const [menuActionError, setMenuActionError] = useState(null);
     const { localQ, setLocalQ } = useRenderListSearch(searchValue, onSearchChange);
-    const { referenceColumns, handleLookupMap, enrichedVm } = useRenderListColumns({
+    const { referenceRequests, handleLookupMap, enrichedVm } = useRenderListColumns({
         screen,
         entity,
         rows,
@@ -93,7 +93,7 @@ export function RenderList(props) {
     const toolbarTitle = resolveToolbarTitle(screen, translate);
     return (_jsxs(_Fragment, { children: [headerActions !== undefined &&
                 PageHeader !== undefined &&
-                renderPageHeader(PageHeader, headerActions, split.promotedInOverflowMenu, promotedMenuItems), menuActionError !== null && renderMenuActionError(Banner, menuActionError), renderReferenceLookupBridges(referenceColumns, handleLookupMap), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...tableChromeProps({
+                renderPageHeader(PageHeader, headerActions, split.promotedInOverflowMenu, promotedMenuItems), menuActionError !== null && renderMenuActionError(Banner, menuActionError), renderReferenceLookupBridges(referenceRequests, handleLookupMap), _jsx(DataTable, { columns: enrichedVm.columns, rows: enrichedVm.rows, toolbarTitle: toolbarTitle, ...tableChromeProps({
                     onRowClick,
                     composedEmptyState,
                     toolbarStart,

package/dist/components/use-reference-input-state.js

@@ -5,8 +5,8 @@ import { useUserRoles } from "../context/user-roles-context.js";
 import { rendererError } from "../dev-console.js";
 import { REFERENCE_COMBOBOX_LIMIT } from "../hooks/reference-limits.js";
 import { useQuery } from "../hooks/use-query.js";
-import { referenceOptionSource } from "../hooks/use-reference-lookup.js";
-import { stringArrayOf } from "./render-field-values.js";
+import { referenceOptionSource, storedReferenceRowsPayload, withUnlistedSelectedRows, } from "../hooks/use-reference-lookup.js";
+import { selectedReferenceIds, stringArrayOf } from "./render-field-values.js";
 export function useReferenceInputState(field, featureName, onChange) {
     const refEntity = field.refEntity ?? "";
     const refFeature = field.refFeature ?? featureName;
@@ -41,6 +41,9 @@ export function useReferenceInputState(field, featureName, onChange) {
         ? { limit: REFERENCE_COMBOBOX_LIMIT }
         : { limit: REFERENCE_COMBOBOX_LIMIT, search: searchTerm }, [searchTerm]);
     const queryResult = useQuery(queryQn, queryPayload);
+    // The first page can miss the stored value; without its row the combobox shows no label.
+    const selectedIds = selectedReferenceIds(field);
+    const selectedResult = useQuery(queryQn, storedReferenceRowsPayload(field, selectedIds, REFERENCE_COMBOBOX_LIMIT), { enabled: selectedIds.length > 0 });
     const handleSearchChange = useCallback((q) => setSearchTerm(q), []);
     const createTarget = !field.readOnly && refCreateScreen !== undefined && refEntityDef !== undefined
         ? { screen: refCreateScreen, entity: refEntityDef }
@@ -63,13 +66,13 @@ export function useReferenceInputState(field, featureName, onChange) {
         }
     }, [isMultiple, field.value, onChange, queryResult.refetch]);
     const options = useMemo(() => {
-        const rows = queryResult.data?.rows ?? [];
+        const rows = withUnlistedSelectedRows(queryResult.data?.rows ?? [], selectedResult.data?.rows ?? []);
         return rows.map((row) => {
             const idVal = String(row["id"] ?? "");
             const label = String(row[labelKey] ?? idVal);
             return { value: idVal, label };
         });
-    }, [queryResult.data, labelKey]);
+    }, [queryResult.data, selectedResult.data, labelKey]);
     return {
         refFeature,
         isMultiple,

package/dist/components/use-render-list-columns.d.ts

@@ -1,7 +1,7 @@
 import type { EntityDefinition, EntityListScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
 import { type ScreenLinkResolver } from "../app/reference-link.ts";
 import type { ListColumnViewModel, ListViewModel, Translate } from "../headless/index.ts";
-import { type PublishedReferenceLookup } from "./render-list-reference-columns.ts";
+import { type PublishedReferenceChunk, type ReferenceLookupRequest } from "./render-list-reference-columns.ts";
 export declare function withScreenLinks(columns: readonly ListColumnViewModel[], screen: EntityListScreenDefinition, resolveScreenLink: ScreenLinkResolver): readonly ListColumnViewModel[];
 type RenderListColumnsInput = {
     readonly screen: EntityListScreenDefinition;
@@ -11,8 +11,8 @@ type RenderListColumnsInput = {
     readonly translate: Translate;
 };
 export declare function useRenderListColumns(input: RenderListColumnsInput): {
-    referenceColumns: import("./render-list-reference-columns.ts").ReferenceColumnSpec[];
-    handleLookupMap: (field: string, lookup: PublishedReferenceLookup) => void;
+    referenceRequests: readonly ReferenceLookupRequest[];
+    handleLookupMap: (field: string, chunkIndex: number, lookup: PublishedReferenceChunk) => void;
     enrichedVm: Omit<ListViewModel, "columns"> & {
         columns: readonly ListColumnViewModel[];
     };

package/dist/components/use-render-list-columns.js

@@ -2,7 +2,8 @@ import { normalizeListColumn } from "@cosmicdrift/kumiko-framework/ui-types";
 import { useCallback, useMemo, useState } from "react";
 import { useReferenceLinkResolver, useScreenLinkResolver, } from "../app/reference-link.js";
 import { computeListViewModel } from "../headless/index.js";
-import { enrichReferenceColumns, selectReferenceColumns, } from "./render-list-reference-columns.js";
+import { REFERENCE_LIST_LOOKUP_LIMIT } from "../hooks/reference-limits.js";
+import { enrichReferenceColumns, mergeChunkLookups, referenceIdChunks, selectReferenceColumns, } from "./render-list-reference-columns.js";
 // A column whose rows name their own target screen links each cell there.
 export function withScreenLinks(columns, screen, resolveScreenLink) {
     const linkFields = new Map();
@@ -37,18 +38,34 @@ export function useRenderListColumns(input) {
     // through onMap. Each bridge makes a constant number of hook calls (one),
     // and React manages its lifecycle when the schema changes via key.
     const referenceColumns = useMemo(() => selectReferenceColumns(vm.columns, featureName), [vm.columns, featureName]);
-    const [referenceLookups, setReferenceLookups] = useState({});
-    const handleLookupMap = useCallback((field, lookup) => {
-        setReferenceLookups((prev) => {
+    const referenceRequests = useMemo(() => referenceColumns.map((column) => ({
+        ...column,
+        idChunks: referenceIdChunks(rows, column.field, REFERENCE_LIST_LOOKUP_LIMIT),
+    })), [referenceColumns, rows]);
+    const [chunkLookups, setChunkLookups] = useState({});
+    const handleLookupMap = useCallback((field, chunkIndex, lookup) => {
+        setChunkLookups((prev) => {
             // Skip the update when the lookup is identical. Otherwise the bridge
             // would re-render and send the same map back until React entered
             // an infinite loop.
-            const current = prev[field];
-            if (current?.map === lookup.map && current.complete === lookup.complete)
+            const current = prev[field]?.[chunkIndex];
+            const unchanged = current?.map === lookup.map &&
+                current.complete === lookup.complete &&
+                current.idsKey === lookup.idsKey;
+            if (unchanged)
                 return prev;
-            return { ...prev, [field]: lookup };
+            return { ...prev, [field]: { ...prev[field], [chunkIndex]: lookup } };
         });
     }, []);
+    const referenceLookups = useMemo(() => {
+        const merged = {};
+        for (const request of referenceRequests) {
+            const lookup = mergeChunkLookups(request.idChunks, chunkLookups[request.field]);
+            if (lookup !== undefined)
+                merged[request.field] = lookup;
+        }
+        return merged;
+    }, [referenceRequests, chunkLookups]);
     const resolveReferenceLink = useReferenceLinkResolver();
     const resolveScreenLink = useScreenLinkResolver();
     const enrichedColumns = useMemo(() => withScreenLinks(enrichReferenceColumns({
@@ -72,5 +89,5 @@ export function useRenderListColumns(input) {
         ...vm,
         columns: enrichedColumns,
     }), [vm, enrichedColumns]);
-    return { referenceColumns, handleLookupMap, enrichedVm };
+    return { referenceRequests, handleLookupMap, enrichedVm };
 }

package/dist/data-table-facet-types.d.ts

@@ -16,6 +16,11 @@ export type DataTableFacet = {
     readonly showCounts?: boolean;
     /** Chips only: hide chips whose `count` is 0 (unless pressed). */
     readonly hideEmpty?: boolean;
+    /** Present: the options come from a server-side search (reference facets), so the dropdown
+     *  shows a search field and reports the typed term instead of filtering `options` itself. */
+    readonly onSearchChange?: (query: string) => void;
+    /** The search is loading; the option list may still show the previous term's rows. */
+    readonly searching?: boolean;
 };
 export type DataTableFacetChip = {
     readonly id: string;

package/dist/hooks/use-reference-lookup.d.ts

@@ -13,18 +13,27 @@ export declare function referenceOptionSource(field: {
     readonly queryQn: string;
     readonly labelKey: string;
 };
+export declare function referenceRowsByIdsPayload(ids: readonly string[], capLimit: number): Record<string, unknown>;
+type ReferenceRow = Readonly<Record<string, unknown>>;
+export declare function withUnlistedSelectedRows(listedRows: readonly ReferenceRow[], selectedRows: readonly ReferenceRow[]): readonly ReferenceRow[];
+export declare function storedReferenceRowsPayload(field: {
+    readonly refOptionsQuery?: string;
+}, ids: readonly string[], capLimit: number): Record<string, unknown>;
 export declare function isCompleteRowPage(data: {
     readonly nextCursor?: string | null;
 } | null): boolean;
-/** `map` holds the resolved labels; while the query loads or has failed an id is
+/** Without `ids` the lookup reads the first capped page, as an option source does;
+ *  with `ids` it asks for exactly those rows.
+ *  `map` holds the resolved labels; while the query loads or has failed an id is
  *  simply not in it. Callers decide the fallback: the raw id, or the "Unknown"
  *  label for entities listed in `UNRESOLVED_REFERENCE_LABEL_KEYS` once the
  *  lookup is complete.
  *  `featureName` is the reference's target feature, not the screen's. */
-export declare function useReferenceLookup(featureName: string, refEntity: string, labelField: string): {
+export declare function useReferenceLookup(featureName: string, refEntity: string, labelField: string, ids?: readonly string[]): {
     readonly map: ReferenceLookupMap;
     readonly loading: boolean;
     readonly failed: boolean;
     /** False when the lookup page was capped: absent ids may still exist. */
     readonly complete: boolean;
 };
+export {};

package/dist/hooks/use-reference-lookup.js

@@ -1,21 +1,16 @@
 // Renderer-side eager load for reference fields.
 //
 // Each reference column of a list calls `<feature>:query:
-// <refEntity>:list` (limit:200) once, builds a Map<uuid, displayValue>,
-// and the renderer uses it as the cell display renderer.
+// <refEntity>:list` for the ids on screen (in chunks of 200), builds a
+// Map<uuid, displayValue>, and the renderer uses it as the cell display renderer.
 //
 // Strategy trade-offs:
 //   - Server-side Drizzle joins would be more efficient (one query instead
 //     of N+1) but would have to extend the executor API with lookupTables.
 //     The renderer-side path wins for the MVP.
-//   - limit:200 is a hard UX limit: with more entries in the referenced
-//     entity, the last rows fall back to the raw id (or "Unknown" for
-//     opt-in entities once the lookup is complete). A searchable combobox plus a
-//     server-side eager load with an ID whitelist will lift that later.
-//
-// The hook is call-stable: useQuery's internal cache shares the lookup map
-// between list and edit form for the same entity, and live updates arrive
-// via SSE (use-query-live).
+//   - A source that ignores both by-id inputs still answers its first 200 rows,
+//     so later ids fall back to the raw id (or "Unknown" for opt-in entities
+//     once the lookup is complete).
 import { REFERENCE_LOOKUP_SOURCES, SYSTEM_REFERENCE_LABELS, } from "@cosmicdrift/kumiko-framework/ui-types";
 import { PII_ERASED_SENTINEL } from "@cosmicdrift/kumiko-types/kms-adapter-types";
 import { useMemo } from "react";
@@ -45,21 +40,48 @@ export function referenceOptionSource(field, refFeature, refEntity) {
     }
     return referenceLookupSource(refFeature, refEntity, field.refLabelField ?? "id");
 }
+// Asks a label source for exactly these rows, so a stored id cannot fall beyond a
+// lookup cap: `ids` is the by-id input of directory sources, `filters` that of entity
+// list handlers. Both only narrow the caller's own read scope. A hand-written handler
+// that knows neither still answers its first `capLimit` rows, as before.
+export function referenceRowsByIdsPayload(ids, capLimit) {
+    return {
+        limit: Math.max(ids.length, capLimit),
+        ids,
+        filters: [{ field: "id", op: "in", value: ids }],
+    };
+}
+// Option rows of a picker plus the stored ones its first page did not carry, so a
+// stored value keeps its label without dropping the picker's own order.
+export function withUnlistedSelectedRows(listedRows, selectedRows) {
+    const listedIds = new Set(listedRows.map((row) => String(row["id"] ?? "")));
+    const unlisted = selectedRows.filter((row) => !listedIds.has(String(row["id"] ?? "")));
+    return unlisted.length === 0 ? listedRows : [...listedRows, ...unlisted];
+}
+// An author `refOptionsQuery` takes `{ limit, search? }` for its picker page and `ids`
+// for stored values; it knows no list filters.
+export function storedReferenceRowsPayload(field, ids, capLimit) {
+    return field.refOptionsQuery === undefined
+        ? referenceRowsByIdsPayload(ids, capLimit)
+        : { limit: Math.max(ids.length, capLimit), ids };
+}
 // A page with a continuation cursor is only a prefix of the referenced rows,
 // so a missing id in it proves nothing about the row's existence.
 export function isCompleteRowPage(data) {
     return data !== null && (data.nextCursor ?? null) === null;
 }
-/** `map` holds the resolved labels; while the query loads or has failed an id is
+/** Without `ids` the lookup reads the first capped page, as an option source does;
+ *  with `ids` it asks for exactly those rows.
+ *  `map` holds the resolved labels; while the query loads or has failed an id is
  *  simply not in it. Callers decide the fallback: the raw id, or the "Unknown"
  *  label for entities listed in `UNRESOLVED_REFERENCE_LABEL_KEYS` once the
  *  lookup is complete.
  *  `featureName` is the reference's target feature, not the screen's. */
-export function useReferenceLookup(featureName, refEntity, labelField) {
+export function useReferenceLookup(featureName, refEntity, labelField, ids) {
     const { queryQn, labelKey } = referenceLookupSource(featureName, refEntity, labelField);
-    const result = useQuery(queryQn, {
-        limit: REFERENCE_LIST_LOOKUP_LIMIT,
-    });
+    const result = useQuery(queryQn, ids === undefined
+        ? { limit: REFERENCE_LIST_LOOKUP_LIMIT }
+        : referenceRowsByIdsPayload(ids, REFERENCE_LIST_LOOKUP_LIMIT), { enabled: ids === undefined || ids.length > 0 });
     const translate = useTranslation();
     const systemLabel = SYSTEM_REFERENCE_LABELS[`${featureName}:${refEntity}`];
     const map = useMemo(() => {

package/dist/i18n-defaults.js

@@ -242,6 +242,14 @@ export const kumikoDefaultTranslations = {
         "kumiko.nav.expand": "Expand",
         "kumiko.nav.collapse": "Collapse",
         "kumiko.nav.search": "Search navigation…",
+        "kumiko.notifications.label": "Notifications",
+        "kumiko.notifications.labelUnread": "Notifications, {count} unread",
+        "kumiko.notifications.title": "Notifications",
+        "kumiko.notifications.empty": "No notifications yet.",
+        "kumiko.notifications.markAllRead": "Mark all as read",
+        "kumiko.notifications.loadMore": "Load more",
+        "kumiko.notifications.unread": "Unread",
+        "kumiko.notifications.loadFailed": "Notifications could not be loaded.",
         "kumiko.nav.language": "Language",
         "kumiko.workspace.switch": "Switch workspace",
         // Workspace-Switcher fallback label when activeId points at no visible workspace.

package/dist/web/layout/notification-bell.d.ts

@@ -0,0 +1,5 @@
+import type { ScreenDefinition } from "@cosmicdrift/kumiko-framework/ui-types";
+import { type ReactNode } from "react";
+export declare function NotificationBell({ screens, }: {
+    readonly screens: readonly ScreenDefinition[];
+}): ReactNode;

package/dist/web/layout/notification-bell.js

@@ -0,0 +1,39 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { Bell } from "lucide-react";
+import { Popover as PopoverPrimitive } from "radix-ui";
+import { useState } from "react";
+import { lastSegment, useLocale, useNav, useTranslation } from "../../index.js";
+import { useRelativeTimeFormatter } from "../app/relative-time.js";
+import { cn } from "../lib/cn.js";
+import { useInAppInbox } from "./use-in-app-inbox.js";
+const MAX_BADGE_COUNT = 99;
+const triggerClass = "relative inline-flex size-8 shrink-0 items-center justify-center rounded-md border border-input " +
+    "bg-background text-foreground shadow-xs transition-colors hover:bg-accent " +
+    "focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring";
+const panelClass = "z-50 flex max-h-[28rem] w-[min(22rem,calc(100vw-1.5rem))] flex-col overflow-hidden rounded-md border " +
+    "bg-popover text-popover-foreground shadow-md";
+export function NotificationBell({ screens, }) {
+    const t = useTranslation();
+    const nav = useNav();
+    const locale = useLocale().locale();
+    const formatRelative = useRelativeTimeFormatter(locale);
+    const [open, setOpen] = useState(false);
+    const inbox = useInAppInbox(open);
+    const badge = inbox.unreadCount > MAX_BADGE_COUNT ? `${MAX_BADGE_COUNT}+` : String(inbox.unreadCount);
+    const label = inbox.unreadCount > 0
+        ? t("kumiko.notifications.labelUnread", { count: badge })
+        : t("kumiko.notifications.label");
+    const openRow = async (row) => {
+        if (!row.isRead)
+            await inbox.markRead(row.id);
+        const target = row.target;
+        if (target === null)
+            return;
+        if (!screens.some((screen) => screen.id === target.screenId))
+            return;
+        const screenId = lastSegment(target.screenId);
+        setOpen(false);
+        nav.navigate(target.entityId === undefined ? { screenId } : { screenId, entityId: target.entityId });
+    };
+    return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Trigger, { asChild: true, children: _jsxs("button", { type: "button", "aria-label": label, "data-kumiko-layout": "notification-bell", className: triggerClass, children: [_jsx(Bell, { className: "size-4", "aria-hidden": "true" }), inbox.unreadCount > 0 && (_jsx("span", { "data-kumiko-layout": "notification-bell-badge", className: "absolute -right-1.5 -top-1.5 flex min-w-4 items-center justify-center rounded-full bg-destructive px-1 text-[10px] font-semibold leading-4 text-destructive-foreground", children: badge }))] }) }), _jsx(PopoverPrimitive.Portal, { children: _jsxs(PopoverPrimitive.Content, { align: "end", sideOffset: 6, className: panelClass, children: [_jsxs("div", { className: "flex items-center justify-between gap-2 border-b border-border px-3 py-2", children: [_jsx("h2", { className: "text-sm font-semibold", children: t("kumiko.notifications.title") }), inbox.unreadCount > 0 && (_jsx("button", { type: "button", className: "text-xs text-primary hover:underline", onClick: () => void inbox.markAllRead(), children: t("kumiko.notifications.markAllRead") }))] }), _jsxs("div", { className: "min-h-0 flex-1 overflow-y-auto", children: [inbox.failed && (_jsx("p", { role: "alert", className: "px-3 py-4 text-sm text-destructive", children: t("kumiko.notifications.loadFailed") })), !inbox.failed && !inbox.loading && inbox.rows.length === 0 && (_jsx("p", { className: "px-3 py-6 text-center text-sm text-muted-foreground", children: t("kumiko.notifications.empty") })), _jsx("ul", { children: inbox.rows.map((row) => (_jsx("li", { children: _jsxs("button", { type: "button", "data-unread": row.isRead ? undefined : "true", className: "flex w-full items-start gap-2 border-b border-border px-3 py-2 text-left hover:bg-accent focus-visible:bg-accent focus-visible:outline-none", onClick: () => void openRow(row), children: [_jsx("span", { "aria-hidden": "true", className: cn("mt-1.5 size-2 shrink-0 rounded-full", row.isRead ? "bg-transparent" : "bg-primary") }), !row.isRead && (_jsx("span", { className: "sr-only", children: t("kumiko.notifications.unread") })), _jsxs("span", { className: "min-w-0 flex-1", children: [_jsx("span", { className: cn("block truncate text-sm", !row.isRead && "font-semibold"), children: row.title }), row.body !== null && (_jsx("span", { className: "block truncate text-xs text-muted-foreground", children: row.body })), _jsx("span", { className: "block text-xs text-muted-foreground", children: formatRelative(Date.parse(row.createdAt)) })] })] }) }, row.id))) }), inbox.hasMore && (_jsx("button", { type: "button", className: "w-full px-3 py-2 text-sm text-primary hover:bg-accent", onClick: () => void inbox.loadMore(), children: t("kumiko.notifications.loadMore") }))] })] }) })] }));
+}

package/dist/web/layout/shell-header.js

@@ -7,6 +7,7 @@ import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-run
 // The `data-kumiko-layout="shell-header"` marker drives `--shell-header-height`
 // in styles.css (:has() selector) — the single source for the header height
 // that Drawer's `belowHeader` prop also reads.
+import { IN_APP_NOTIFICATION_FEATURE } from "@cosmicdrift/kumiko-types/in-app-notification-types";
 import { MoreHorizontal } from "lucide-react";
 import { Fragment, useEffect, useId, useMemo, useRef, useState, } from "react";
 import { resolveNavigation } from "../../headless/index.js";
@@ -17,6 +18,7 @@ import { Breadcrumb, BreadcrumbItem, BreadcrumbLink, BreadcrumbList, BreadcrumbP
 import { SidebarTrigger } from "../ui/sidebar.js";
 import { HeaderOverflowMenuContext, headerOverflowMenuItemClass } from "./header-overflow-menu.js";
 import { buildNavRegistrySliceForApp } from "./nav-tree.js";
+import { NotificationBell } from "./notification-bell.js";
 import { usePageHeaderSlot } from "./page-header-slot.js";
 import { activeNavLabel, resolveDetailBreadcrumb, screenTitleKey, } from "./shell-breadcrumb.js";
 import { SHELL_HEADER_CONTROLS_CLASSES } from "./uniform-bar-controls.js";
@@ -35,6 +37,7 @@ export function ShellHeader({ schema, user, headerActions, allowedNavQns, }) {
         return resolveNavigation({ source, ...(user !== undefined && { user }) });
     }, [appSchema, user, allowedNavQns]);
     const allScreens = useMemo(() => appSchema.features.flatMap((f) => f.screens), [appSchema.features]);
+    const hasInAppChannel = appSchema.features.some((feature) => feature.featureName === IN_APP_NOTIFICATION_FEATURE);
     const slot = usePageHeaderSlot();
     const standInScreenId = slot?.breadcrumbScreenId;
     const screenId = standInScreenId ?? nav.route?.screenId;
@@ -78,7 +81,7 @@ export function ShellHeader({ schema, user, headerActions, allowedNavQns, }) {
                                                     e.preventDefault();
                                                     nav.navigate({ screenId });
                                                 }, children: crumb.label })) : isLast ? (_jsx("h1", { "aria-current": "page", title: titleOverride ?? crumb.label, className: "truncate text-lg font-semibold text-foreground", children: titleOverride ?? crumb.label })) : (_jsx(BreadcrumbPage, { className: "whitespace-nowrap text-foreground-secondary", children: crumb.label })) })] }, screenId ?? crumb.label));
-                            }) }) })), _jsx("div", { ref: setStatusElement, "data-kumiko-layout": "page-header-status", className: cn("flex items-center gap-2 empty:hidden", compact ? "min-w-0 overflow-hidden" : "shrink-0") })] }), _jsxs("div", { className: cn("ml-auto flex items-center gap-2", compact ? "min-w-0 max-w-[60%]" : "min-w-0 max-w-[50%] shrink-0 sm:max-w-none"), children: [_jsx("div", { ref: setActionsElement, "data-kumiko-layout": "page-header-actions", className: cn(SHELL_HEADER_CONTROLS_CLASSES, "flex min-w-0 items-center gap-2 empty:hidden [&_*]:min-w-0 [&_*]:max-w-full [&_button]:overflow-hidden [&_button]:whitespace-nowrap", compact && "overflow-hidden") }), !compact && headerActions !== undefined && (_jsx("div", { "data-kumiko-layout": "header-actions", className: "flex items-center gap-2", children: headerActions })), hasOverflow && _jsx(HeaderOverflow, { items: overflowItems, headerActions: headerActions })] })] }));
+                            }) }) })), _jsx("div", { ref: setStatusElement, "data-kumiko-layout": "page-header-status", className: cn("flex items-center gap-2 empty:hidden", compact ? "min-w-0 overflow-hidden" : "shrink-0") })] }), _jsxs("div", { className: cn("ml-auto flex items-center gap-2", compact ? "min-w-0 max-w-[60%]" : "min-w-0 max-w-[50%] shrink-0 sm:max-w-none"), children: [_jsx("div", { ref: setActionsElement, "data-kumiko-layout": "page-header-actions", className: cn(SHELL_HEADER_CONTROLS_CLASSES, "flex min-w-0 items-center gap-2 empty:hidden [&_*]:min-w-0 [&_*]:max-w-full [&_button]:overflow-hidden [&_button]:whitespace-nowrap", compact && "overflow-hidden") }), user !== undefined && hasInAppChannel && _jsx(NotificationBell, { screens: allScreens }), !compact && headerActions !== undefined && (_jsx("div", { "data-kumiko-layout": "header-actions", className: "flex items-center gap-2", children: headerActions })), hasOverflow && _jsx(HeaderOverflow, { items: overflowItems, headerActions: headerActions })] })] }));
 }
 // A hand-rolled menu instead of Radix DropdownMenu: app headerActions are opaque
 // nodes with their own popovers, and the panel stays mounted while closed so their

package/dist/web/layout/use-in-app-inbox.d.ts

@@ -0,0 +1,15 @@
+import { type InAppInboxRow } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+export declare const IN_APP_INBOX_PAGE_SIZE = 20;
+export type InAppInbox = {
+    readonly unreadCount: number;
+    readonly rows: readonly InAppInboxRow[];
+    readonly hasMore: boolean;
+    readonly loading: boolean;
+    readonly failed: boolean;
+    readonly loadMore: () => Promise<void>;
+    readonly markRead: (id: number) => Promise<void>;
+    readonly markAllRead: () => Promise<void>;
+};
+/** Headless state of the notification bell: the unread count always, the list only while `open`.
+ *  The delivered signal refetches both; no polling. */
+export declare function useInAppInbox(open: boolean): InAppInbox;

package/dist/web/layout/use-in-app-inbox.js

@@ -0,0 +1,61 @@
+import { IN_APP_NOTIFICATION_DELIVERED_EVENT, IN_APP_NOTIFICATION_QUERIES, IN_APP_NOTIFICATION_WRITES, } from "@cosmicdrift/kumiko-types/in-app-notification-types";
+import { useCallback, useEffect, useState } from "react";
+import { useDispatcher } from "../../context/dispatcher-context.js";
+import { useMutation } from "../../hooks/use-mutation.js";
+import { useQuery } from "../../hooks/use-query.js";
+import { useLiveEvents } from "../../sse/live-events.js";
+export const IN_APP_INBOX_PAGE_SIZE = 20;
+/** Headless state of the notification bell: the unread count always, the list only while `open`.
+ *  The delivered signal refetches both; no polling. */
+export function useInAppInbox(open) {
+    const dispatcher = useDispatcher();
+    const subscribe = useLiveEvents();
+    const count = useQuery(IN_APP_NOTIFICATION_QUERIES.unreadCount, {});
+    const firstPage = useQuery(IN_APP_NOTIFICATION_QUERIES.inbox, { limit: IN_APP_INBOX_PAGE_SIZE }, { enabled: open });
+    const [olderRows, setOlderRows] = useState([]);
+    const [olderCursor, setOlderCursor] = useState(undefined);
+    const markReadWrite = useMutation(IN_APP_NOTIFICATION_WRITES.markRead);
+    const markAllReadWrite = useMutation(IN_APP_NOTIFICATION_WRITES.markAllRead);
+    const refetchCount = count.refetch;
+    const refetchFirstPage = firstPage.refetch;
+    const refetchAll = useCallback(async () => {
+        setOlderRows([]);
+        setOlderCursor(undefined);
+        await Promise.all([refetchCount(), open ? refetchFirstPage() : Promise.resolve()]);
+    }, [refetchCount, refetchFirstPage, open]);
+    useEffect(() => subscribe(IN_APP_NOTIFICATION_DELIVERED_EVENT, () => void refetchAll()), [subscribe, refetchAll]);
+    const firstRows = firstPage.data?.rows ?? [];
+    const nextCursor = olderCursor === undefined ? (firstPage.data?.nextCursor ?? null) : olderCursor;
+    const loadMore = useCallback(async () => {
+        // skip: no older page left
+        if (nextCursor === null)
+            return;
+        const result = await dispatcher.query(IN_APP_NOTIFICATION_QUERIES.inbox, {
+            limit: IN_APP_INBOX_PAGE_SIZE,
+            cursor: nextCursor,
+        });
+        // skip: keep the loaded rows, the next click retries
+        if (!result.isSuccess)
+            return;
+        setOlderRows((previous) => [...previous, ...result.data.rows]);
+        setOlderCursor(result.data.nextCursor);
+    }, [dispatcher, nextCursor]);
+    const markRead = useCallback(async (id) => {
+        await markReadWrite.mutate({ id });
+        await refetchAll();
+    }, [markReadWrite.mutate, refetchAll]);
+    const markAllRead = useCallback(async () => {
+        await markAllReadWrite.mutate({});
+        await refetchAll();
+    }, [markAllReadWrite.mutate, refetchAll]);
+    return {
+        unreadCount: count.data?.count ?? 0,
+        rows: [...firstRows, ...olderRows],
+        hasMore: nextCursor !== null,
+        loading: firstPage.loading,
+        failed: firstPage.error !== null,
+        loadMore,
+        markRead,
+        markAllRead,
+    };
+}

package/dist/web/primitives/facet-filter.js

@@ -6,6 +6,7 @@ import { Button as UiButton } from "../ui/button.js";
 import { DropdownMenu, DropdownMenuCheckboxItem, DropdownMenuContent, DropdownMenuTrigger, } from "./dropdown-menu.js";
 import "../react-css-custom-properties.js";
 import { DefaultButton } from "./button.js";
+import { FacetSearchFilter } from "./facet-search-filter.js";
 // ---- DataTable (shadcn: Table) ----
 function sameValueSet(a, b) {
     return a.length === b.length && a.every((value) => b.includes(value));
@@ -26,6 +27,9 @@ export function FacetFilter({ facet, selected, onChange, dense = false, }) {
     if (facet.chips !== undefined) {
         return _jsx(FacetChips, { facet: facet, selected: selected, onChange: onChange });
     }
+    if (facet.onSearchChange !== undefined) {
+        return (_jsx(FacetSearchFilter, { facet: facet, onSearchChange: facet.onSearchChange, selected: selected, onChange: onChange, dense: dense }));
+    }
     return (_jsxs(DropdownMenu, { children: [_jsx(DropdownMenuTrigger, { asChild: true, children: _jsxs(UiButton, { variant: "outline", size: "sm", className: cn("h-9", dense && "border-border-strong px-2.5"), "data-testid": `facet-${facet.field}`, children: [facet.label, selected.length > 0 && (_jsx(Badge, { variant: "secondary", className: "ml-1 rounded-sm px-1 font-normal tabular-nums", children: selected.length })), _jsx(ChevronDown, { className: "text-muted-foreground" })] }) }), _jsx(DropdownMenuContent, { align: "start", className: "max-h-[var(--radix-dropdown-menu-content-available-height)] w-44 overflow-y-auto", children: facet.options.map((opt) => (_jsx(DropdownMenuCheckboxItem, { checked: selected.includes(opt.value), onCheckedChange: (checked) => toggle(opt.value, checked), onSelect: (e) => e.preventDefault(), "data-testid": `facet-${facet.field}-${opt.value}`, children: opt.label }, opt.value))) })] }));
 }
 // Time-range filter: two native <input type="date"> instead of a

package/dist/web/primitives/facet-search-filter.d.ts

@@ -0,0 +1,9 @@
+import { type ReactNode } from "react";
+import { type DataTableFacet } from "../../index.ts";
+export declare function FacetSearchFilter({ facet, onSearchChange, selected, onChange, dense, }: {
+    facet: DataTableFacet;
+    onSearchChange: (query: string) => void;
+    selected: readonly string[];
+    onChange: (field: string, values: readonly string[]) => void;
+    dense: boolean;
+}): ReactNode;

package/dist/web/primitives/facet-search-filter.js

@@ -0,0 +1,31 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+// Facet dropdown with a server-side search field, for reference facets whose option list is a
+// capped page. A Radix DropdownMenu would swallow the typed keys for its typeahead, so this is a
+// Popover + cmdk list like ComboboxInput, with the facet's own trigger button.
+import { Command } from "cmdk";
+import { Check, ChevronDown, Loader2 } from "lucide-react";
+import { Popover as PopoverPrimitive } from "radix-ui";
+import { useEffect, useState } from "react";
+import { REFERENCE_SEARCH_DEBOUNCE_MS, useTranslation } from "../../index.js";
+import { cn } from "../lib/cn.js";
+import { Badge } from "../ui/badge.js";
+import { Button as UiButton } from "../ui/button.js";
+export function FacetSearchFilter({ facet, onSearchChange, selected, onChange, dense, }) {
+    const t = useTranslation();
+    const [open, setOpen] = useState(false);
+    const [searchTerm, setSearchTerm] = useState("");
+    useEffect(() => {
+        const timer = setTimeout(() => onSearchChange(searchTerm), REFERENCE_SEARCH_DEBOUNCE_MS);
+        return () => clearTimeout(timer);
+    }, [searchTerm, onSearchChange]);
+    useEffect(() => {
+        if (!open && searchTerm !== "")
+            setSearchTerm("");
+    }, [open, searchTerm]);
+    const toggle = (value) => {
+        onChange(facet.field, selected.includes(value) ? selected.filter((v) => v !== value) : [...selected, value]);
+    };
+    return (_jsxs(PopoverPrimitive.Root, { open: open, onOpenChange: setOpen, children: [_jsx(PopoverPrimitive.Trigger, { asChild: true, children: _jsxs(UiButton, { variant: "outline", size: "sm", className: cn("h-9", dense && "border-border-strong px-2.5"), "data-testid": `facet-${facet.field}`, children: [facet.label, selected.length > 0 && (_jsx(Badge, { variant: "secondary", className: "ml-1 rounded-sm px-1 font-normal tabular-nums", children: selected.length })), _jsx(ChevronDown, { className: "text-muted-foreground" })] }) }), _jsx(PopoverPrimitive.Portal, { children: _jsx(PopoverPrimitive.Content, { align: "start", sideOffset: 4, className: "z-50 w-64 rounded-md border bg-popover p-0 text-popover-foreground shadow-md outline-none", children: _jsxs(Command, { shouldFilter: false, children: [_jsxs("div", { className: "relative", children: [_jsx(Command.Input, { value: searchTerm, onValueChange: setSearchTerm, placeholder: t("kumiko.combobox.search-placeholder"), "data-testid": `facet-${facet.field}-search`, className: "flex h-9 w-full border-0 border-b border-border bg-transparent px-3 py-1 text-sm outline-none placeholder:text-muted-foreground" }), facet.searching === true && (_jsx(Loader2, { className: "absolute right-2 top-2.5 h-4 w-4 animate-spin text-muted-foreground" }))] }), _jsxs(Command.List, { className: "max-h-64 overflow-y-auto p-1", children: [_jsx(Command.Empty, { className: "py-3 text-center text-sm text-muted-foreground", children: facet.searching === true
+                                            ? t("kumiko.combobox.loading")
+                                            : t("kumiko.combobox.empty") }), facet.options.map((opt) => (_jsxs(Command.Item, { value: opt.value, onSelect: () => toggle(opt.value), "data-testid": `facet-${facet.field}-${opt.value}`, className: "relative flex cursor-pointer select-none items-center rounded-sm py-1.5 pl-8 pr-2 text-sm outline-none aria-selected:bg-accent aria-selected:text-accent-foreground", children: [selected.includes(opt.value) && (_jsx("span", { className: "absolute left-2 flex h-3.5 w-3.5 items-center justify-center", children: _jsx(Check, { className: "h-4 w-4" }) })), opt.label] }, opt.value)))] })] }) }) })] }));
+}

package/dist/web/sse/live-events.js

@@ -78,10 +78,21 @@ export function createEventSourceLiveEvents(options = {}) {
     // addEventListener(entityName, ...) gate below only filters which frames
     // arrive at all, not which subscriber a given frame is for. Without this
     // filter, an `invoice` subscriber would also fire on every `user` frame.
-    const handleEvent = (raw) => {
+    // Frames without an aggregateType (channel-in-app:event:delivered) are named after their
+    // event type, so the frame name is the subscription key and the signal is synthesized.
+    const handleEvent = (raw, frameName) => {
         let parsed;
         try {
-            parsed = JSON.parse(raw);
+            const body = JSON.parse(raw);
+            const aggregateType = propertyOf(body, "aggregateType");
+            parsed =
+                typeof aggregateType === "string"
+                    ? body
+                    : {
+                        aggregateType: frameName,
+                        eventType: frameName,
+                        createdAt: Temporal.Instant.fromEpochMilliseconds(now()).toString(),
+                    };
         }
         catch {
             // skip: malformed SSE payload, drop it rather than crash all subscribers
@@ -109,7 +120,7 @@ export function createEventSourceLiveEvents(options = {}) {
         connection.addEventListener(entityName, (e) => {
             const data = propertyOf(e, "data");
             if (typeof data === "string")
-                handleEvent(data);
+                handleEvent(data, entityName);
         });
         wiredEntities.add(entityName);
     };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cosmicdrift/kumiko-renderer",
-  "version": "0.397.0",
+  "version": "0.399.0",
   "description": "React renderer for Kumiko screens. The root export holds the platform-agnostic logic (primitives contract, hooks, KumikoScreen, navigation and SSE abstractions); ./headless the DOM-free UI logic, ./live the HTTP dispatcher, ./web the browser bindings (HTML primitives, history navigation, EventSource live events, createKumikoApp).",
   "license": "MIT",
   "author": "Marc Frost <marc@cosmicdriftgamestudio.com>",
@@ -48,8 +48,8 @@
     }
   },
   "dependencies": {
-    "@cosmicdrift/kumiko-framework": "0.397.0",
-    "@cosmicdrift/kumiko-types": "0.397.0",
+    "@cosmicdrift/kumiko-framework": "0.399.0",
+    "@cosmicdrift/kumiko-types": "0.399.0",
     "@types/qrcode": "^1.5.5",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
@@ -79,11 +79,11 @@
     }
   },
   "devDependencies": {
-    "@cosmicdrift/kumiko-locale-de": "0.397.0",
-    "@cosmicdrift/kumiko-testing": "0.397.0",
+    "@cosmicdrift/kumiko-locale-de": "0.399.0",
+    "@cosmicdrift/kumiko-testing": "0.399.0",
     "@tailwindcss/cli": "^4.3.3",
-    "@testing-library/react": "^16.3.2",
-    "@testing-library/user-event": "^14.6.1",
+    "@testing-library/react": "^16.3.3",
+    "@testing-library/user-event": "^14.6.8",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
     "jsdom": "^29.1.1",

package/src/changes.json

@@ -1,4 +1,28 @@
 [
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Notification bell in the shell header",
+    "detail": "With the channel-in-app feature in the schema and a signed-in user, ShellHeader renders a bell with an unread badge (99+ from 100) and a popover list with title, body, relative time, mark all read and load more. A click marks the entry read and opens its target screen when the schema has it. The delivered signal refetches the count and the open list; there is no polling. SSE frames without an aggregateType now reach subscribers keyed by the frame name. New keys `kumiko.notifications.*` in the default bundle and in all four locale packages."
+  },
+  {
+    "version": "0.399.0",
+    "type": "fix",
+    "title": "Tab description is rendered on groups tabs",
+    "detail": "The `description` of a section with tabbed groups was dropped; only fields and relatedList tabs showed it. The outer card of a groups tab now renders it as its subtitle, also when a relatedList tab has no rows."
+  },
+  {
+    "version": "0.399.0",
+    "type": "improvement",
+    "title": "Searchable reference facets",
+    "detail": "A reference facet in entityList, projectionList and relatedList loads a page of options and a search field narrows them on the server (300 ms debounce), so values beyond the first page can be filtered by. Chosen values keep their label from a separate by-id request, also after a reload from the URL. A reference field with `optionsQuery` uses that handler for the facet. The 200-row warning is gone; `DataTableFacet` gets optional `onSearchChange` and `searching`."
+  },
+  {
+    "version": "0.398.0",
+    "type": "fix",
+    "title": "Reference labels resolve by id beyond the lookup caps",
+    "detail": "ReadOnlyReferenceValue, the reference combobox and embedded-list reference cells request the stored ids next to their first options page; list reference columns request the ids on screen in chunks of 200 instead of the first 200 rows of the target. The ids go out as `ids` for directory sources and an id-in filter for entity list handlers, which only narrow the caller's list query, so tenant, ownership and field-read rules keep applying. Author `optionsQuery` handlers on reference fields keep their capped `{ limit, search? }` picker page and are additionally asked for stored values with `{ limit, ids }`; a handler that ignores `ids` keeps the previous capped behaviour. List columns keep labels already known while the ids of a new page load and only claim \"Unknown\" once the current ids have resolved."
+  },
   {
     "version": "0.395.0",
     "type": "improvement",