@cosmicdrift/kumiko-types 0.388.0 → 0.390.0

package/dist/handlers.d.ts

@@ -11,11 +11,15 @@ import type { KumikoEventTypeMap } from "./event-type-map.ts";
 import type { FileContext } from "./file-handle-types.ts";
 import type { FileProviderResolver } from "./file-provider-resolver-types.ts";
 import type { GeoTzProvider } from "./geo-tz.ts";
+import type { BeforeTransactionContext, HandlerAuth, HandlerDb, HandlerDispatch, HandlerEvents, HandlerObservability, JobDispatch, JobEvents, JobObservability, ReservationContext } from "./handler-context-facets.ts";
+import type { ContextServices, HandlerLifecycle, HandlerTenants, JobLifecycle } from "./handler-context-services.ts";
 import type { Logger } from "./logger.ts";
-import type { Meter, MetricsHandle, Tracer } from "./observability/index.ts";
+import type { Meter, Tracer } from "./observability/index.ts";
 import type { SearchAdapter } from "./search-adapter.ts";
 import type { CrossTenantReads, TenantDb } from "./tenant-db-types.ts";
 import type { Clock, TzContext } from "./tz-context.ts";
+export type { BeforeTransactionContext, HandlerAuth, HandlerDb, HandlerDispatch, HandlerEvents, HandlerObservability, JobDispatch, JobEvents, JobObservability, ReservationContext, } from "./handler-context-facets.ts";
+export type { ContextServices, HandlerLifecycle, HandlerTenants, JobLifecycle, } from "./handler-context-services.ts";
 export type OpenToAllPersonalData = "tenant-members";
 export type OpenToAllDeclaration = {
     readonly reason: string;
@@ -214,27 +218,12 @@ type SharedContextFields = {
     readonly jobRunner?: JobRunnerRef;
     readonly configResolver?: ConfigResolver;
     readonly config?: ConfigAccessor;
-    /**
-     * Config accessor resolved for ANOTHER tenant, identity = that tenant's system
-     * user (the caller's user-scope config never leaks in). Cross-tenant calls
-     * throw AccessDeniedError unless the caller is a system identity or has the
-     * SystemAdmin role; the caller's own tenant needs no privilege. Present when
-     * the config feature wired its accessor factory.
-     */
+    /** Becomes `ctx.tenants.config`. */
     readonly configFor?: (tenantId: TenantId) => ConfigAccessor;
-    /**
-     * Write target for ANOTHER tenant: a tenant-mode db bound to it plus the
-     * `streamTenantId` to hand the executor, so the event actor stays the
-     * operator. Cross-tenant calls throw AccessDeniedError unless the caller is
-     * SystemAdmin (the tenantIdOverride gate); the caller's own tenant needs no
-     * privilege and yields `streamTenantId: undefined`. Write handlers only;
-     * absent for r.systemScope() handlers and without a db.
-     */
+    /** Becomes `ctx.tenants.writeTarget`. */
     readonly forTenant?: (tenantId: TenantId) => TenantWriteTarget;
     /** Mints the per-request `ctx.config`; set by the boot (`addConfigAccessorFactory`) from the effective `configResolver`, overriding an app-supplied value. */
     readonly configAccessorFactory?: ConfigAccessorFactory;
-    /** @deprecated Use `configAccessorFactory`; the underscore name is removed in 0.390.0. */
-    readonly _configAccessorFactory?: ConfigAccessorFactory;
     readonly configEncryption?: import("./envelope-cipher-types.ts").EnvelopeCipher;
     readonly rateLimit?: import("./rate-limit-types.ts").RateLimitResolver;
     readonly _rateLimitPayloadDigest?: (value: string) => string;
@@ -255,10 +244,13 @@ type SharedContextFields = {
     readonly meter?: Meter;
     readonly signal?: AbortSignal;
     readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
+    /** Becomes `ctx.lifecycle.afterCommit`. */
     readonly scheduleAfterCommit?: (hook: () => Promise<void>) => void;
-    readonly queryAsMember?: MemberReader;
+    /** Becomes `ctx.lifecycle.afterRollback`. */
+    readonly scheduleAfterRollback?: (hook: () => Promise<void>) => void;
 };
 export type AppContext = SharedContextFields & {
+    readonly services?: never;
     readonly db?: DbConnection | TenantDb;
     readonly systemDb?: UncheckedSystemDb;
     readonly registry?: Registry;
@@ -284,7 +276,7 @@ export type AppContext = SharedContextFields & {
     /** Tenant of the current pipeline call. The dispatcher mirrors
      *  `user.tenantId` here when building HandlerContext so the lifecycle
      *  pipeline and system hooks can access it without the user object.
-     *  `effectiveFeatures(ctx._tenantId)` uses it at hook-filter points. */
+     *  `effectiveFeatures(ctx.user.tenantId)` uses it at hook-filter points. */
     readonly _tenantId?: TenantId;
     /** Boot-configured default locale (BCP-47). Last fallback in ctx.locale's
      *  Request-Locale → Boot-Default chain (dispatch-shared.ts) — used when
@@ -292,18 +284,8 @@ export type AppContext = SharedContextFields & {
      *  Absent falls back to "en". */
     readonly defaultLocale?: string;
 };
-export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedContextFields & {
-    readonly db: TenantDb;
-    /**
-     * Same tenant scoping as `db`, but never bound to the handler's tx: writes through it survive
-     * a rollback. `undefined` only in the denial phases (member-resolution, before-transaction)
-     * and in platform-metering tenant mode; narrow with `hasOutsideTransactionDb(ctx)` or take it
-     * via `requireOutsideTransactionDb(ctx)` (`@cosmicdrift/kumiko-framework/db`). For atomic
-     * multi-statement writes outside the tx use `runInOwnTransaction(ctx.dbOutsideTransaction, fn)`; `fn`
-     * must not touch rows the handler's own tx has locked. For
-     * r.systemScope() handlers it is a fail-closed Proxy; use `systemDb.outsideTransaction`.
-     */
-    readonly dbOutsideTransaction: TenantDb | undefined;
+export type HandlerContext<TMap extends object = KumikoEventTypeMap> = {
+    readonly db: HandlerDb;
     readonly systemDb?: UncheckedSystemDb;
     readonly crossTenantReads?: CrossTenantReads;
     readonly registry: Registry;
@@ -313,80 +295,35 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
      *  The value is identical to `event.user`; identity switches still use
      *  `queryAs`/`writeAs`. */
     readonly user: SessionUser;
-    readonly systemUser?: SessionUser;
-    readonly log?: Logger;
-    readonly triggeredBy?: {
-        readonly id: string;
-        readonly tenantId: TenantId;
-    } | null;
     /** Keyed digest for handler-owned rate-limit keys, so Redis never holds a
      *  plaintext or plainly hashed identifier. Scoped to the running handler:
      *  the same input yields a different digest per handler and never matches a
      *  dispatcher payload-bucket digest. Absent when the app wires no digest key. */
     readonly rateLimitDigest?: (value: string) => string;
     readonly includeDeleted?: boolean;
-    readonly runPreSave?: (handlerName: string, changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean) => Promise<Record<string, unknown>>;
-    readonly query: (qn: string, payload: unknown) => Promise<unknown>;
-    readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
-    readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
-    readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
+    readonly dispatch: HandlerDispatch;
     readonly hasFeature: (featureName: string) => Promise<boolean>;
-    /**
-     * Default append: a typed domain event on one aggregate stream in the current tx. The runtime
-     * bumps the stream version and fires matching projections in the same transaction. A version
-     * conflict throws and poisons the transaction.
-     */
-    readonly appendEvent: AppendEventFn<TMap>;
-    /**
-     * Untyped append (`payload: unknown`) with the same runtime as `appendEvent`. Only for
-     * migrations and upcasters, where the event type is not knowable at compile time.
-     */
-    readonly unsafeAppendEvent: UnsafeAppendEventFn;
-    /**
-     * Optimistic append: runs in a savepoint and returns a version conflict as a result instead of
-     * throwing, so the handler can continue after losing a race on the same aggregate stream.
-     */
-    readonly tryAppendEvent: TryAppendEventFn;
-    readonly fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
-    readonly loadAggregate: (aggregateId: string, options?: {
-        readonly asOf?: Temporal.Instant;
-    }) => Promise<readonly import("./event-store-types.ts").StoredEvent[]>;
-    readonly archiveStream: (aggregateId: string, args: {
-        readonly aggregateType: string;
-        readonly reason?: string;
-    }) => Promise<void>;
-    readonly restoreStream: (aggregateId: string) => Promise<void>;
-    readonly isStreamArchived: (aggregateId: string) => Promise<boolean>;
-    readonly snapshotAggregate: (args: {
-        readonly aggregateId: string;
-        readonly aggregateType: string;
-        readonly version: number;
-        readonly state: Record<string, unknown>;
-        readonly snapshotVersion?: number;
-    }) => Promise<void>;
-    readonly loadAggregateWithSnapshot: <TState extends Record<string, unknown>>(aggregateId: string, reducer: import("./snapshot-types.ts").SnapshotReducer<TState>, initial: TState, options?: Omit<import("./snapshot-types.ts").LoadAggregateWithSnapshotOptions, "upcastEvent">) => Promise<import("./snapshot-types.ts").LoadAggregateWithSnapshotResult<TState>>;
-    readonly queryProjection: <T = Record<string, unknown>>(qualifiedName: string, options?: {
-        readonly unsafeAllTenants?: boolean;
-    }) => Promise<readonly T[]>;
-    readonly metrics: MetricsHandle;
-    readonly metricsFor: (featureName: string) => MetricsHandle;
-    readonly tracer: Tracer;
+    readonly events: HandlerEvents<TMap>;
+    readonly obs: HandlerObservability;
     readonly tz: TzContext;
     readonly locale: string;
-    readonly resolveAuthClaims: (user: SessionUser) => Promise<Record<string, unknown>>;
-    readonly resolveActiveMembership: (userId: string, tenantId: TenantId) => Promise<ActiveMembershipResult>;
-    readonly queryAsMember: MemberReader;
+    readonly auth: HandlerAuth;
+    readonly config?: ConfigAccessor;
+    readonly notify?: NotifyFn;
+    readonly services: ContextServices;
+    readonly lifecycle: HandlerLifecycle;
+    readonly tenants: HandlerTenants;
 };
 export type JobDeferral = {
     readonly kind: "job-deferral";
     readonly delayMs: number;
 };
-export type JobContext = SharedContextFields & {
+export type JobContext = {
     readonly db: TenantDb;
+    readonly events: JobEvents;
     readonly registry: Registry;
     readonly systemUser: SessionUser;
-    readonly log: Logger;
-    readonly metricsFor: (featureName: string) => MetricsHandle;
+    readonly obs: JobObservability;
     readonly tz: TzContext;
     readonly triggeredBy: {
         readonly id: string;
@@ -395,22 +332,18 @@ export type JobContext = SharedContextFields & {
     readonly attempt: number;
     readonly finalAttempt: boolean;
     readonly defer: (delayMs: number) => JobDeferral;
+    readonly canDefer: boolean;
     readonly systemDb?: UncheckedSystemDb;
     readonly crossTenantReads?: CrossTenantReads;
-    readonly write: (qn: string, payload: unknown) => Promise<WriteResult>;
-    readonly writeAs: (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
-    readonly queryAs: (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
-    readonly queryAsMember: MemberReader;
+    readonly dispatch: JobDispatch;
     readonly triggerName?: string;
     readonly triggerEvent?: JobTriggerEvent;
     readonly _tenantId?: TenantId;
+    readonly config?: ConfigAccessor;
+    readonly notify?: NotifyFn;
+    readonly services: ContextServices;
+    readonly lifecycle: JobLifecycle;
 };
-/**
- * What a provider plugin (`build`, `capabilitiesFor`, ...) may read. Both write/query handlers
- * and jobs can produce one (`providerPluginContextFromHandler`, `providerPluginContextFromJob`),
- * so a plugin never depends on a request-bound field.
- */
-export type ProviderPluginContext = Pick<HandlerContext, "db" | "dbOutsideTransaction" | "systemDb" | "registry" | "user" | "log" | "triggeredBy" | "config" | "secrets">;
 export type WriteHandlerFn<TPayload = unknown, TData = unknown> = (event: WriteEvent<TPayload>, context: HandlerContext) => Promise<WriteResult<TData>>;
 export type QueryHandlerFn<TPayload = unknown, TResult = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => Promise<TResult>;
 export type StreamHandlerFn<TPayload = unknown, TChunk = unknown> = (query: QueryEvent<TPayload>, context: HandlerContext) => AsyncGenerator<TChunk>;
@@ -419,7 +352,7 @@ export type StreamHandlerFn<TPayload = unknown, TChunk = unknown> = (query: Quer
  * → kebab-case. Drives the literal-type of `EventDef.name`, so that
  * `r.defineEvent("foo", schema)` inside `defineFeature("driverOrders")`
  * carries `name: "driver-orders:event:foo"` as a literal — strict-mode
- * for `ctx.appendEvent({ type: eventDef.name, ... })` lights up.
+ * for `ctx.events.append({ type: eventDef.name, ... })` lights up.
  *
  * Algorithm mirrors the runtime regex pipeline:
  *   1. `.` → `-` (dot acts as word-boundary)
@@ -607,14 +540,14 @@ export type ReservationHandle = {
  *  its own short write instead of holding a second connection while the transaction is open.
  *  The returned release (or handle.release) runs when the transaction does not commit (failure
  *  result, throw, rollback, failed commit). Throwing a KumikoError rejects the write. */
-export type PreTransactionReservation = (event: WriteEvent, ctx: HandlerContext) => Promise<ReservationRelease | ReservationHandle | undefined>;
+export type PreTransactionReservation = (event: WriteEvent, ctx: ReservationContext) => Promise<ReservationRelease | ReservationHandle | undefined>;
 /** Outcome of a write handler's pre-transaction phase. `release` runs when the handler transaction does not commit (failure result, throw, rollback, failed commit with unknown outcome), so it must itself tolerate a commit that actually happened. */
 export type BeforeTransactionResult<TPrepared = unknown> = {
     readonly isSuccess: true;
     readonly data: TPrepared;
     readonly release?: ReservationRelease;
 } | WriteFailure;
-export type BeforeTransactionPhase<TPayload = unknown, TPrepared = unknown> = (event: WriteEvent<TPayload>, ctx: HandlerContext) => Promise<BeforeTransactionResult<TPrepared>>;
+export type BeforeTransactionPhase<TPayload = unknown, TPrepared = unknown> = (event: WriteEvent<TPayload>, ctx: BeforeTransactionContext) => Promise<BeforeTransactionResult<TPrepared>>;
 /** `perCommand`: the handler runs without a transaction of its own. */
 export type WriteHandlerTransactionMode = "perCommand";
 export type WriteHandlerDef = {
@@ -636,17 +569,17 @@ export type WriteHandlerDef = {
      *  payload (e.g. `(p) => p.files.length`). Replaces the options' `cost`; results below 1 count as 1. */
     readonly rateLimitCost?: (payload: unknown) => number;
     readonly escapeHatch?: EscapeHatchDeclaration;
-    /** Reserves before the handler transaction opens. Reached through a nested ctx.write the
+    /** Reserves before the handler transaction opens. Reached through a nested ctx.dispatch.write the
      *  reservation cannot run, so the dispatcher rejects it unless the top-level batch reserved it. */
     readonly reserveBeforeTransaction?: PreTransactionReservation;
     /** Runs after all pre-handler gates (and after reserveBeforeTransaction) and before the
      *  transaction opens: no transaction and no connection held, for external I/O and reads only.
      *  Its `data` reaches the handler as `event.prepared`; a failure result or throw rejects the
-     *  write before anything is written. A handler with this phase cannot run as a nested ctx.write.
-     *  `ctx.forTenant` is available but read-only here: its db denies writes for the own and a
+     *  write before anything is written. A handler with this phase cannot run as a nested ctx.dispatch.write.
+     *  `ctx.tenants.writeTarget` is available but read-only here: its db denies writes for the own and a
      *  foreign tenant alike (a foreign tenant stays gated by the SystemAdmin check). */
     readonly beforeTransaction?: BeforeTransactionPhase;
-    /** `"perCommand"`: the handler runs without a transaction of its own. Every ctx.write/writeAs it
+    /** `"perCommand"`: the handler runs without a transaction of its own. Every ctx.dispatch.write/writeAs it
      *  issues runs as its own top-level command with its own transaction and afterCommit hooks;
      *  ctx.db writes and event appends throw. It cannot run as a nested write or inside a
      *  multi-command batch, and cannot be combined with beforeTransaction/reserveBeforeTransaction. */
@@ -693,4 +626,3 @@ export type StreamHandlerDef = {
     readonly rateLimit?: RateLimitDeclaration;
     readonly escapeHatch?: EscapeHatchDeclaration;
 };
-export {};

package/dist/hooks.d.ts

@@ -1,5 +1,5 @@
 import type { StoredEvent } from "./event-store-types.ts";
-import type { AppContext } from "./handlers.ts";
+import type { HandlerContext } from "./handlers.ts";
 import type { HookPhase } from "./hook-phase.ts";
 import type { EntityId } from "./identifiers.ts";
 export type ValidationError = {
@@ -26,23 +26,22 @@ export type DeleteContext = {
     readonly lockGuardBypassed?: boolean | undefined;
 };
 export type LifecycleResult = SaveContext | DeleteContext;
-export type PreSaveHookFn = (changes: Record<string, unknown>, context: AppContext & {
+export type PreSaveHookFn = (changes: Record<string, unknown>, context: HandlerContext & {
     readonly previous: Readonly<Record<string, unknown>>;
     readonly isNew: boolean;
 }) => Promise<Record<string, unknown>>;
-export type PostSaveHookFn = (result: SaveContext, context: AppContext) => Promise<void>;
-export type PostSaveBatchHookFn = (results: readonly SaveContext[], context: AppContext) => Promise<void>;
-export type PreDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
-export type PostDeleteHookFn = (payload: DeleteContext, context: AppContext) => Promise<void>;
-export type PostDeleteBatchHookFn = (payloads: readonly DeleteContext[], context: AppContext) => Promise<void>;
-export type PreQueryHookFn = (payload: Record<string, unknown>, context: AppContext) => Promise<Record<string, unknown>>;
+export type PostSaveHookFn = (result: SaveContext, context: HandlerContext) => Promise<void>;
+export type PostSaveBatchHookFn = (results: readonly SaveContext[], context: HandlerContext) => Promise<void>;
+export type PreDeleteHookFn = (payload: DeleteContext, context: HandlerContext) => Promise<void>;
+export type PostDeleteHookFn = (payload: DeleteContext, context: HandlerContext) => Promise<void>;
+export type PostDeleteBatchHookFn = (payloads: readonly DeleteContext[], context: HandlerContext) => Promise<void>;
 export type PostQueryHookFn = (result: {
     readonly entityName: string | undefined;
     readonly rows: ReadonlyArray<Record<string, unknown>>;
-}, context: AppContext) => Promise<{
+}, context: HandlerContext) => Promise<{
     rows: ReadonlyArray<Record<string, unknown>>;
 }>;
-export type LifecycleHookFn = PreSaveHookFn | PostSaveHookFn | PreDeleteHookFn | PostDeleteHookFn | PreQueryHookFn | PostQueryHookFn;
+export type LifecycleHookFn = PreSaveHookFn | PostSaveHookFn | PreDeleteHookFn | PostDeleteHookFn | PostQueryHookFn;
 export type { HookPhase } from "./hook-phase.ts";
 export type HookOwner = {
     readonly featureName?: string;
@@ -60,7 +59,6 @@ export type HookMap = {
     readonly postSave?: Readonly<Record<string, readonly PhasedHook<PostSaveHookFn>[]>>;
     readonly preDelete?: Readonly<Record<string, readonly PhasedHook<PreDeleteHookFn>[]>>;
     readonly postDelete?: Readonly<Record<string, readonly PhasedHook<PostDeleteHookFn>[]>>;
-    readonly preQuery?: Readonly<Record<string, readonly OwnedFn<PreQueryHookFn>[]>>;
     readonly postQuery?: Readonly<Record<string, readonly OwnedFn<PostQueryHookFn>[]>>;
 };
 export type EntityHookMap = {

package/dist/list-aggregate-types.d.ts

@@ -23,7 +23,12 @@ export type ListAggregatePayload = {
         readonly kind: ListAggregateMeasureKind;
     }[];
 };
-export type ListAggregateValue = number | string | null;
+export type ListAggregateCurrencyAmount = {
+    readonly currency: string;
+    readonly value: number;
+};
+export type ListAggregateValue = number | string | null | readonly ListAggregateCurrencyAmount[];
+export declare function isListAggregateCurrencyAmounts(value: ListAggregateValue | undefined): value is readonly ListAggregateCurrencyAmount[];
 export type ListAggregateGroup = {
     readonly key: AggregateKey;
     readonly label?: string | null;

package/dist/list-aggregate-types.js

@@ -9,6 +9,9 @@ export const listAggregatePayloadSchema = z.object({
         .max(MAX_LIST_AGGREGATE_MEASURES)
         .default([]),
 });
+export function isListAggregateCurrencyAmounts(value) {
+    return Array.isArray(value);
+}
 const LIST_AGGREGATE_RESULT_KEYS = ["groups", "truncated", "searchTruncated"];
 // Closed key set: a row that merely has a `groups` field (jsonb column) must not
 // be mistaken for an aggregate and skip the row-level read filter.

package/dist/observability/metric.js

@@ -1,3 +1,3 @@
-// Metric + Meter contract. Feature code interacts through ctx.metrics
+// Metric + Meter contract. Feature code interacts through ctx.obs.metrics
 // (MetricsHandle); the framework wires Counter/Histogram/Gauge behind that.
 export {};

package/dist/screen-entity-edit.d.ts

@@ -6,6 +6,8 @@ import type { FieldRenderer, PlatformComponent, ScreenNavSugar, ScreenSlots } fr
 import type { ActionFormRedirect } from "./screen-action-form.ts";
 import type { DashboardPanelVisibility } from "./screen-dashboard.ts";
 import type { ListColumnSpec, ListSortSpec, RelatedListToolbarAction, RowAction, RowActionMode, RowFieldExtractor } from "./screen-entity-list.ts";
+import type { ListBulkAction } from "./screen-list-bulk.ts";
+import type { ListTableGrouping, ListTableOptions } from "./screen-list-table.ts";
 import type { ListFacetSpec } from "./screen-projection.ts";
 export type EditFieldSpec = string | {
     readonly field: string;
@@ -168,25 +170,9 @@ export type EditExtensionSection = {
      *  (declared or id-derived); the boot-validator rejects one that doesn't. */
     readonly actions?: readonly RowAction[];
 };
-/** Rows are grouped by `field` in order of first appearance. Every group gets
- *  a collapsible header. */
-export type RelatedListGroupBy = {
-    readonly field: string;
-    /** Groups whose field value equals this start collapsed; the others start open. */
-    readonly collapsedWhen?: string | number | boolean | null;
-    /** i18n key of the group header. Placeholders: `{count}` rows in the group,
-     *  `{value}` the group's field value, `{lastDate}` the group's latest
-     *  `dateField` value as a locale date. A group with neither `label` nor an
-     *  entry in `labels` renders its rows without a header and never collapses. */
-    readonly label?: string;
-    /** Header i18n key per group value (as string), overriding `label`. */
-    readonly labels?: Readonly<Record<string, string>>;
-    /** Row field (ISO date or timestamp) behind `{lastDate}`. */
-    readonly dateField?: string;
-};
-/** Group key of a field value; `collapsedWhen` and row values both go through it. */
+/** Group key of a field value; `collapsedWhen` and server group keys both go through it. */
 export declare function relatedListGroupKey(value: unknown): string;
-export declare function relatedListGroupHeaderLabel(groupBy: RelatedListGroupBy, groupKey: string): string | undefined;
+export declare function relatedListGroupHeaderLabel(grouping: Pick<ListTableGrouping, "label" | "labels">, groupKey: string): string | undefined;
 /** Row tint rule: rows where the `FieldCondition` (`{ field, eq }`, `{ field,
  *  in }` …) holds get the tone. `bad` renders red. */
 export type RelatedListRowTone = Exclude<FieldCondition, boolean> & {
@@ -240,6 +226,8 @@ export type EditRelatedListSection = {
      *  "3 Positionen"). Omitted: generic "entries" wording. */
     readonly itemNoun?: string;
     readonly pageSize?: number;
+    /** Opt-in table behaviour: remembered state, reset, column picker, density. */
+    readonly table?: ListTableOptions;
     /** Initial sort on mount, applied client-side over the already-loaded rows
      *  (this section has no pager; if the fetch is truncated, `nextCursor !== null`,
      *  the section shows a hint banner that the sort covers only the loaded rows).
@@ -278,8 +266,8 @@ export type EditRelatedListSection = {
     readonly rowActions?: readonly RowAction[];
     /** Layout of the row-action column — see `RowActionMode`. */
     readonly rowActionMode?: RowActionMode;
-    /** Groups rows by the value of a field under collapsible group headers. */
-    readonly groupBy?: RelatedListGroupBy;
+    /** Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action. Adds a checkbox column and a selection bar; without it the list has no checkboxes. */
+    readonly bulkActions?: readonly ListBulkAction[];
     /** Tints rows whose field matches — a declarative rule, not a function, so
      *  the screen definition stays serializable. */
     readonly rowTone?: RelatedListRowTone;

package/dist/screen-entity-edit.js

@@ -1,8 +1,10 @@
-/** Group key of a field value; `collapsedWhen` and row values both go through it. */
+/** Group key of a field value; `collapsedWhen` and server group keys both go through it. */
 export function relatedListGroupKey(value) {
     return value === undefined || value === null ? "" : String(value);
 }
-export function relatedListGroupHeaderLabel(groupBy, groupKey) {
-    const labels = groupBy.labels;
-    return labels !== undefined && Object.hasOwn(labels, groupKey) ? labels[groupKey] : groupBy.label;
+export function relatedListGroupHeaderLabel(grouping, groupKey) {
+    const labels = grouping.labels;
+    return labels !== undefined && Object.hasOwn(labels, groupKey)
+        ? labels[groupKey]
+        : grouping.label;
 }

package/dist/screen-entity-list.d.ts

@@ -4,7 +4,10 @@ import type { IconKey } from "./nav-icon.ts";
 import type { FieldRenderer, PlatformComponent, ScreenNavSugar, ScreenSlots } from "./screen.ts";
 import type { ActionFormRedirect } from "./screen-action-form.ts";
 import type { DashboardPanelVisibility } from "./screen-dashboard.ts";
-import type { EditRelatedListSection, ListEmptyStateSpec } from "./screen-entity-edit.ts";
+import type { ListEmptyStateSpec } from "./screen-entity-edit.ts";
+import type { EntityListExpandableRow } from "./screen-expandable-row.ts";
+import type { ListBulkAction } from "./screen-list-bulk.ts";
+import type { ListColumnPin, ListTableOptions } from "./screen-list-table.ts";
 export type ListColumnSpec = string | {
     readonly field: string;
     readonly renderer?: FieldRenderer;
@@ -49,6 +52,16 @@ export type ListColumnSpec = string | {
      *  `md` breakpoint (tables keep it). For columns that only make sense
      *  next to the others, like a sort key. */
     readonly hideOnNarrow?: boolean;
+    /** Start state for the column picker: the column begins hidden and the
+     *  user can show it. Only valid together with `table.columnPicker`. */
+    readonly hidden?: boolean;
+    /** Start pin for the column: it sticks to this edge while the table scrolls
+     *  horizontally. Only valid together with `table.pinning`. */
+    readonly pinned?: ListColumnPin;
+    /** Start width in px. Only valid together with `table.resizing`. */
+    readonly width?: number;
+    /** Smallest width in px the user can resize to. Only valid together with `table.resizing`. */
+    readonly minWidth?: number;
     /** Dashboard list panels only. "bar": field holds a 0..1 fraction, drawn
      *  as bar + percent. "badge": field holds a label, drawn as a pill whose
      *  tone comes from `badgeToneField`. "datetime": field holds an ISO string or
@@ -321,11 +334,6 @@ export type RelatedListToolbarAction = (Extract<ToolbarAction, {
 }> & {
     readonly visible?: FieldCondition;
 });
-/** Expandable area of an `entityList` row: a relatedList of the row's record.
- *  `id` (tab id) and `countField` (tab badge) have no meaning outside a tabs
- *  layout and are therefore omitted. `kind` stays the discriminator so further
- *  expansion kinds can be added without a breaking change. */
-export type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField">;
 /** An extra choice on a facet next to the field's own options: a named
  *  bundle of values ("Running" = several statuses) or "no filter" (`values:
  *  []`, e.g. "All"). Chips only. */
@@ -340,8 +348,9 @@ export type EntityListFacetExtraOption = {
 };
 export type EntityListFacetConfig = {
     /** `"select"` (default): dropdown with checkboxes. `"chips"`: one toggle
-     *  chip per option, single choice. */
-    readonly display?: "select" | "chips";
+     *  chip per option, single choice. `"range"`: "from" and "to" inputs on a
+     *  number, decimal, money or bigInt field, sent as `gte`/`lte`. */
+    readonly display?: "select" | "chips" | "range";
     /** Chips show how many rows each option matches (other facets and the
      *  search apply). Counts come from the list query itself, one `limit: 1`
      *  count request per chip. */
@@ -387,6 +396,8 @@ export type EntityListScreenDefinition = {
     readonly rowActions?: readonly RowAction[];
     /** Layout of the row-action column — see `RowActionMode`. */
     readonly rowActionMode?: RowActionMode;
+    /** Bulk actions over checkbox-selected rows, each pointing at a writeHandler row action. Adds a checkbox column and a selection bar; without it the list has no checkboxes. */
+    readonly bulkActions?: readonly ListBulkAction[];
     /** Toolbar actions (list header). "Open Incident", "Schedule Maintenance"
      *  etc. — next to "+ New" if present. Array order = UI order,
      *  primary-style links. */
@@ -403,6 +414,8 @@ export type EntityListScreenDefinition = {
     readonly filter?: ScreenFilter;
     readonly pagination?: ListPaginationMode;
     readonly pageSize?: number;
+    /** Opt-in table behaviour: remembered state, reset, column picker, density. */
+    readonly table?: ListTableOptions;
     readonly defaultSort?: ListSortSpec;
     /** Initial facet selection, per filterable field: option values (string
      *  facets) or a boolean. Applies only while the URL carries no value for

package/dist/screen-expandable-row.d.ts

@@ -0,0 +1,16 @@
+import type { EditRelatedListSection } from "./screen-entity-edit.ts";
+import type { ListTableGrouping } from "./screen-list-table.ts";
+/** Server-side grouping of an expandable row's sub-list: a fixed `field`, no "Group by" choice. */
+export type ExpandableRowGrouping = Omit<ListTableGrouping, "field" | "userChoice" | "fields"> & {
+    readonly field: string;
+};
+/** Expandable area of an `entityList` row: a relatedList of the row's record.
+ *  `id` (tab id) and `countField` (tab badge) have no meaning outside a tabs
+ *  layout and are therefore omitted. `kind` stays the discriminator so further
+ *  expansion kinds can be added without a breaking change. `table` takes only
+ *  `grouping`; the other table options belong on the entityList itself. */
+export type EntityListExpandableRow = Omit<EditRelatedListSection, "id" | "countField" | "table" | "bulkActions"> & {
+    readonly table?: {
+        readonly grouping?: ExpandableRowGrouping;
+    };
+};

package/dist/screen-expandable-row.js

@@ -0,0 +1 @@
+export {};

package/dist/screen-list-bulk.d.ts

@@ -0,0 +1,12 @@
+export declare const LIST_BULK_ACTION_KEYS: readonly ["id", "rowAction", "confirm"];
+/** Most rows one selection can hold; the loaded page caps it further. */
+export declare const MAX_BULK_SELECTION = 100;
+/** An action that runs a writeHandler row action once per checkbox-selected row. One `/api/write` per row, so access, validation and audit stay per row. */
+export type ListBulkAction = {
+    /** Stable id, kebab-case, unique among the screen's bulk actions. */
+    readonly id: string;
+    /** Id of a writeHandler entry in the same screen's `rowActions`; it supplies handler, payload, label, style and `visible`. Rows the action's `visible` hides are skipped. */
+    readonly rowAction: string;
+    /** i18n key of the one confirm dialog for the whole selection; gets `{count}` and `{action}`. Without it a `confirm` or `style: "danger"` on the row action still asks once with the default text. */
+    readonly confirm?: string;
+};

package/dist/screen-list-bulk.js

@@ -0,0 +1,3 @@
+export const LIST_BULK_ACTION_KEYS = ["id", "rowAction", "confirm"];
+/** Most rows one selection can hold; the loaded page caps it further. */
+export const MAX_BULK_SELECTION = 100;

package/dist/screen-list-table.d.ts

@@ -0,0 +1,70 @@
+import type { ListAggregateMeasureKind } from "./list-aggregate-types.ts";
+export declare const LIST_TABLE_DENSITIES: readonly ["comfortable", "compact"];
+export type ListTableDensity = (typeof LIST_TABLE_DENSITIES)[number];
+export declare const LIST_COLUMN_PINS: readonly ["left", "right"];
+export type ListColumnPin = (typeof LIST_COLUMN_PINS)[number];
+export declare const LIST_TABLE_OPTION_KEYS: readonly ["rememberState", "resetAll", "columnPicker", "density", "pinning", "resizing", "keyboardNavigation", "export", "grouping", "totals"];
+export declare const LIST_TABLE_GROUPING_KEYS: readonly ["field", "label", "labels", "collapsedWhen", "userChoice", "fields"];
+export declare const LIST_TABLE_TOTAL_KEYS: readonly ["field", "kind"];
+export declare const LIST_TABLE_EXPORT_KEYS: readonly ["xlsx", "maxRows"];
+export declare const DEFAULT_EXPORT_MAX_ROWS = 10000;
+/** Hard cap: the server builds the whole workbook in memory. */
+export declare const MAX_EXPORT_MAX_ROWS = 100000;
+export declare const LIST_TABLE_DENSITY_KEYS: readonly ["default", "userChoice"];
+/** Opt-in table behaviour of a list. Without the block a list renders and behaves exactly as before. */
+export type ListTableOptions = {
+    /** Keeps search, sort, page size, facets and date range for the browser session and restores them when the screen is opened without list parameters in the URL. A link with parameters always wins. */
+    readonly rememberState?: boolean;
+    /** Replaces the facet reset with one button that resets search, sort, page size, facets and date range, and drops the remembered list parameters (column and density choices stay). */
+    readonly resetAll?: boolean;
+    /** Lets the user hide and reorder columns in the view menu. Columns marked `hidden` start hidden. */
+    readonly columnPicker?: boolean;
+    /** Lets the user pin columns left or right in the view menu; columns may start pinned via `pinned`. Pinned columns stay sticky while scrolling horizontally. No effect in the card layout below `md`. */
+    readonly pinning?: boolean;
+    /** Switches the table to table-layout fixed; the user drags or uses the arrow keys on the header edge to resize. `width` and `minWidth` on a column are start values; widths are remembered per session. No effect in the card layout. */
+    readonly resizing?: boolean;
+    /** Rows become one tab stop; ArrowUp/ArrowDown move, Home/End jump, Enter runs the row click. Space stays reserved for selection. */
+    readonly keyboardNavigation?: boolean;
+    readonly density?: {
+        /** Row density on first visit. Default "comfortable". */
+        readonly default?: ListTableDensity;
+        /** Shows the density choice in the view menu and remembers it per session. */
+        readonly userChoice?: boolean;
+    };
+    /** Shows an export button; the server reads the whole filtered list (not just the visible page). */
+    readonly export?: ListTableExportOptions;
+    /** Server-side grouping: group headers with count and the `totals` measures over all matching rows; each open group loads its own rows. */
+    readonly grouping?: ListTableGrouping;
+    /** Footer row under the rows, computed by the server over all rows matching the current filters and search. In grouped mode the same measures show in each group header. */
+    readonly totals?: readonly ListTableTotal[];
+};
+export type ListTableGrouping = {
+    /** Start grouping. Without it the list starts ungrouped and the user picks from `fields`. */
+    readonly field?: string;
+    /** Groups whose key equals this start collapsed and load no rows until opened. */
+    readonly collapsedWhen?: string | number | boolean | null;
+    /** i18n key of the group header. Placeholders: `{count}` rows in the group, `{value}` the group's value. Default: the value itself. */
+    readonly label?: string;
+    /** Header i18n key per group key (as string), overriding `label`. */
+    readonly labels?: Readonly<Record<string, string>>;
+    /** Shows "Group by" in the view menu (needs `fields` or `field`) and remembers the choice per session. */
+    readonly userChoice?: boolean;
+    /** Fields offered under "Group by"; `field` is always offered. */
+    readonly fields?: readonly string[];
+};
+export type ListTableTotal = {
+    readonly field: string;
+    /** sum and avg on number, decimal, money and bigInt; min and max also on date and timestamp. Money is shown per currency, never added across currencies. */
+    readonly kind: ListAggregateMeasureKind;
+};
+export type ListTableExportOptions = {
+    readonly xlsx: true;
+    /** Export is refused above this many rows. Default 10000, hard cap 100000. Encrypted, sensitive and virtual columns are never written. */
+    readonly maxRows?: number;
+};
+/** One `table` block for every entityList, projectionList and relatedList of the bundled features. A screen's own `table` keys win per key. `grouping` and `totals` are not accepted here. */
+export type BundledListsOptions = {
+    readonly table: ListTableOptions;
+    /** Pins the first column left on every bundled list where no column is pinned. Needs `table.pinning: true`. */
+    readonly pinFirstColumn?: boolean;
+};

package/dist/screen-list-table.js

@@ -0,0 +1,28 @@
+export const LIST_TABLE_DENSITIES = ["comfortable", "compact"];
+export const LIST_COLUMN_PINS = ["left", "right"];
+export const LIST_TABLE_OPTION_KEYS = [
+    "rememberState",
+    "resetAll",
+    "columnPicker",
+    "density",
+    "pinning",
+    "resizing",
+    "keyboardNavigation",
+    "export",
+    "grouping",
+    "totals",
+];
+export const LIST_TABLE_GROUPING_KEYS = [
+    "field",
+    "label",
+    "labels",
+    "collapsedWhen",
+    "userChoice",
+    "fields",
+];
+export const LIST_TABLE_TOTAL_KEYS = ["field", "kind"];
+export const LIST_TABLE_EXPORT_KEYS = ["xlsx", "maxRows"];
+export const DEFAULT_EXPORT_MAX_ROWS = 10000;
+/** Hard cap: the server builds the whole workbook in memory. */
+export const MAX_EXPORT_MAX_ROWS = 100000;
+export const LIST_TABLE_DENSITY_KEYS = ["default", "userChoice"];