@cosmicdrift/kumiko-types 0.387.0 → 0.389.0

package/dist/feature.d.ts

@@ -1,20 +1,16 @@
 import type * as z from "zod";
 import type { ZodType } from "zod";
-import type { ConfigKeyDefinition, ConfigKeyHandle, ConfigKeyType, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, JobHandlerFn, NotificationDataFn, NotificationDefinition, NotificationLocalizedTemplate, NotificationRecipientFn, NotificationRecordMapping, NotificationTemplateBody, NotificationTemplateFn, NotificationTemplateMeta, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TemplateVariables, TranslationKeys, TranslationsDef } from "./config.ts";
-import type { QueryHandlerDefinition, StreamHandlerDefinition, WriteHandlerDefinition } from "./define-handler.ts";
-import type { RegisterEntityCrudOptions } from "./entity-handlers.ts";
+import type { ConfigKeyDefinition, ConfigSeedDef, ExtensionSelectorDef, ExtensionSelectorPanel, JobDefinition, NotificationDefinition, ReferenceDataDef, RegistrarExtensionDef, RegistrarExtensionRegistration, TranslationKeys } from "./config.ts";
 import type { EntityTableMeta } from "./entity-table-meta-types.ts";
-import type { KumikoEventTypeMap } from "./event-type-map.ts";
-import type { ExtensionOptionsArgs, ExtensionOptionsFor } from "./extension-options-map.ts";
 import type { EntityDefinition } from "./fields.ts";
-import type { AccessRule, AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, ClaimKeyHandle, ClaimKeyType, DeclarativeEventMigration, EntityRef, EscapeHatchDeclaration, EventDef, EventMigrationDef, EventPiiStance, EventUpcastFn, HandlerRef, NameOrRef, QualifiedEventName, QueryHandlerDef, RateLimitDeclaration, StreamHandlerDef, StreamHandlerFn, WriteHandlerDef } from "./handlers.ts";
-import type { EntityHookMap, HookMap, HookPhase, OwnedFn, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SearchPayloadContributorFn, ValidationHookFn } from "./hooks.ts";
+import type { AuthClaimsFn, AuthClaimsHookDef, ClaimKeyDefinition, EventDef, EventMigrationDef, EventUpcastFn, QueryHandlerDef, StreamHandlerDef, WriteHandlerDef } from "./handlers.ts";
+import type { EntityHookMap, HookMap, HookPhase, OwnedFn, PostDeleteHookFn, PostQueryHookFn, PostSaveHookFn, PreDeleteHookFn, PreQueryHookFn, PreSaveHookFn, SearchPayloadContributorFn } from "./hooks.ts";
 import type { HttpRouteDefinition } from "./http-route.ts";
 import type { ContentCollectionDefinition, NavDefinition } from "./nav.ts";
 import type { EntityProjectionExtension, MultiStreamProjectionDefinition, ProjectionDefinition } from "./projection.ts";
 import type { EntityRelations, RelationDefinition } from "./relations.ts";
 import type { ScreenDefinition } from "./screen.ts";
-import type { TreeActionDef, TreeActionsHandle } from "./tree-node.ts";
+import type { TreeActionDef } from "./tree-node.ts";
 import type { WebSocketRouteDefinition } from "./websocket-route.ts";
 import type { WorkspaceDefinition } from "./workspace.ts";
 export type FeatureMetricType = "counter" | "histogram" | "gauge";
@@ -116,7 +112,7 @@ export type BootCheckContext = {
 };
 export type BootCheckFn = (ctx: BootCheckContext) => void;
 /** runProdApp options a stack can depend on; runProdApp checks the set at boot. */
-export type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "demoMode" | "seeds" | "signals" | "rateLimit";
+export type BootOptionName = "mail" | "kmsMode" | "fileStorage" | "billing" | "featureToggles" | "rateLimit";
 export type StackBootRequirement = {
     readonly stack: string;
     readonly options: readonly BootOptionName[];
@@ -133,6 +129,7 @@ export type FeatureDefinition = {
     readonly requiredProjections: ReadonlySet<string>;
     readonly requiredSteps: ReadonlySet<string>;
     readonly toggleableDefault?: boolean;
+    readonly adoptsBundledLists?: true;
     readonly uiHints?: UiHints;
     readonly entities?: Readonly<Record<string, EntityDefinition>>;
     readonly entityTables?: Readonly<Record<string, unknown>>;
@@ -198,310 +195,6 @@ export type FeatureDefinition = {
     readonly envSchema?: z.ZodObject<z.ZodRawShape>;
     readonly dedupeOptions?: Readonly<Record<string, unknown>>;
 };
-type RefOrRefs = NameOrRef | readonly NameOrRef[];
-type HookTarget = RefOrRefs | {
-    readonly allOf: NameOrRef;
-};
-export type EntityObjectDefinition = {
-    readonly name: string;
-    readonly backingTable?: unknown;
-} & EntityDefinition;
-type HookEscapeHatch = {
-    readonly escapeHatch?: EscapeHatchDeclaration;
-};
-type HookPhaseOption = {
-    readonly phase?: HookPhase;
-};
-export type HookDefinition = {
-    readonly type: "validation";
-    readonly target: RefOrRefs;
-    readonly handler: ValidationHookFn;
-    readonly escapeHatch?: never;
-    readonly phase?: never;
-} | ({
-    readonly type: "preSave";
-    readonly target: RefOrRefs;
-    readonly handler: PreSaveHookFn;
-    readonly phase?: never;
-} & HookEscapeHatch) | ({
-    readonly type: "postSave";
-    readonly target: HookTarget;
-    readonly handler: PostSaveHookFn;
-} & HookEscapeHatch & HookPhaseOption) | ({
-    readonly type: "preDelete";
-    readonly target: HookTarget;
-    readonly handler: PreDeleteHookFn;
-    readonly phase?: never;
-} & HookEscapeHatch) | ({
-    readonly type: "postDelete";
-    readonly target: HookTarget;
-    readonly handler: PostDeleteHookFn;
-} & HookEscapeHatch & HookPhaseOption) | ({
-    readonly type: "preQuery";
-    readonly target: RefOrRefs;
-    readonly handler: PreQueryHookFn;
-    readonly phase?: never;
-} & HookEscapeHatch) | ({
-    readonly type: "postQuery";
-    readonly target: HookTarget;
-    readonly handler: PostQueryHookFn;
-    readonly phase?: never;
-} & HookEscapeHatch);
-/**
- * `r.requires({ features })` declares the features this one depends on; the
- * `.projection` extension declares read-side projection tables that this
- * feature's pipeline steps are allowed to write via
- * `r.step.unsafeProjectionUpsert` (hard-required for any unsafeProjection-*
- * step usage, see Q10).
- *
- * @example r.requires({ features: ["auth", "tenant"] });
- */
-export type RequiresApi = ((options: {
-    readonly features: readonly string[];
-}) => void) & {
-    readonly projection: (tableName: string) => void;
-    readonly step: (stepKind: string) => void;
-};
-/**
- * `TFeature` is the literal feature-name from `defineFeature("foo", ...)` —
- * default-`string` keeps every existing usage zero-config. Strict-typed
- * features (apps that opt into the literal-name flavour) get propagated
- * through to `defineEvent` so the returned `EventDef.name` is a literal
- * `${CamelToKebab<TFeature>}:event:${CamelToKebab<TInner>}`. That literal
- * threads through `ctx.appendEvent({ type: eventDef.name, ... })`,
- * keeping strict-mode alive even when handlers route via `eventDef.name`
- * instead of hand-typed string literals.
- */
-export type FeatureRegistrar<TFeature extends string = string> = {
-    systemScope(): void;
-    describe(text: string): void;
-    requires: RequiresApi;
-    optionalRequires(...featureNames: string[]): void;
-    optionalRequires(options: {
-        readonly features: readonly string[];
-    }): void;
-    toggleable(options: {
-        default: boolean;
-    }): void;
-    uiHints(hints: UiHints): void;
-    /**
-     * @example r.entity({ name: "note", fields: { title: createTextField({ required: true }) } });
-     */
-    entity(definition: EntityObjectDefinition): EntityRef;
-    crud(entityName: string, entity: EntityDefinition, options?: RegisterEntityCrudOptions): void;
-    /**
-     * @example r.writeHandler({ name: "note:archive", schema, handler, access: { roles: ["User"] } });
-     */
-    writeHandler<TName extends string, TSchema extends ZodType, TPrepared = undefined>(def: WriteHandlerDefinition<TName, TSchema, unknown, KumikoEventTypeMap, TPrepared>): HandlerRef;
-    /**
-     * @example r.queryHandler({ name: "note:list", schema, handler, access: { roles: ["User"] } });
-     */
-    queryHandler<TName extends string, TSchema extends ZodType>(def: QueryHandlerDefinition<TName, TSchema>): HandlerRef;
-    streamHandler<TName extends string, TSchema extends ZodType>(def: StreamHandlerDefinition<TName, TSchema>): HandlerRef;
-    streamHandler<TSchema extends ZodType>(name: string, schema: TSchema, handler: StreamHandlerFn<z.infer<TSchema>>, options: {
-        access: AccessRule;
-        rateLimit?: RateLimitDeclaration;
-        escapeHatch?: EscapeHatchDeclaration;
-    }): HandlerRef;
-    relation(entity: NameOrRef, relationName: string, definition: RelationDefinition): void;
-    relation<TDef extends RelationDefinition>(definition: {
-        readonly entity: NameOrRef;
-        readonly name: string;
-    } & TDef): void;
-    /**
-     * @example r.hook({ type: "postSave", target: { allOf: noteRef }, handler: notifyOwner });
-     */
-    hook(definition: HookDefinition): void;
-    searchPayloadExtension(entity: NameOrRef, fn: SearchPayloadContributorFn): void;
-    config<T extends ConfigKeyType>(keyName: string, def: ConfigKeyDefinition<T>): ConfigKeyHandle<T>;
-    config<TKeys extends Readonly<Record<string, ConfigKeyDefinition<ConfigKeyType>>>>(definition: {
-        readonly keys: TKeys;
-        readonly seeds?: Readonly<Record<string, ConfigSeedDef>>;
-    }): {
-        readonly [K in keyof TKeys]: ConfigKeyHandle<TKeys[K]["type"]>;
-    };
-    job(name: string, options: Omit<JobDefinition, "name" | "handler">, handler: JobHandlerFn): void;
-    job(definition: JobDefinition): void;
-    notification(name: string, definition: {
-        readonly trigger?: {
-            readonly on: NameOrRef;
-        };
-        readonly recipient?: NotificationRecipientFn;
-        readonly data?: NotificationDataFn;
-        readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
-        readonly variables?: TemplateVariables;
-        readonly record?: NotificationRecordMapping;
-        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
-        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
-        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
-        readonly renamedFrom?: readonly string[];
-        readonly systemOnly?: boolean;
-        readonly unsubscribe?: boolean;
-        readonly tenantTransport?: boolean;
-    }): void;
-    notification(definition: {
-        readonly name: string;
-        readonly trigger?: {
-            readonly on: NameOrRef;
-        };
-        readonly recipient?: NotificationRecipientFn;
-        readonly data?: NotificationDataFn;
-        readonly templates?: Readonly<Record<string, NotificationTemplateFn>>;
-        readonly variables?: TemplateVariables;
-        readonly record?: NotificationRecordMapping;
-        readonly template?: Readonly<Record<string, NotificationTemplateBody>>;
-        readonly meta?: Readonly<Record<string, NotificationTemplateMeta>>;
-        readonly localizedTemplate?: () => NotificationLocalizedTemplate;
-        readonly renamedFrom?: readonly string[];
-        readonly systemOnly?: boolean;
-        readonly unsubscribe?: boolean;
-        readonly tenantTransport?: boolean;
-    }): void;
-    translations(def: TranslationsDef): void;
-    defineEvent<const TInner extends string, TPayload>(name: TInner, schema: ZodType<TPayload>, options: {
-        readonly version?: number;
-        readonly piiFields: EventPiiStance;
-        readonly migrations?: readonly {
-            readonly fromVersion: number;
-            readonly toVersion: number;
-            readonly transform: EventUpcastFn | DeclarativeEventMigration;
-        }[];
-    }): EventDef<TPayload, QualifiedEventName<TFeature, TInner>>;
-    readsConfig(...qualifiedKeys: string[]): void;
-    readsConfig(options: {
-        readonly keys: readonly string[];
-    }): void;
-    referenceData(entity: NameOrRef, data: readonly Record<string, unknown>[], options?: {
-        upsertKey?: string;
-    }): void;
-    referenceData(definition: {
-        readonly entity: NameOrRef;
-        readonly data: readonly Record<string, unknown>[];
-        readonly upsertKey?: string;
-    }): void;
-    extendsRegistrar(name: string, def: RegistrarExtensionDef): void;
-    useExtension<N extends string>(extensionName: N, entity: NameOrRef, ...options: ExtensionOptionsArgs<N>): void;
-    useExtension<N extends string>(definition: {
-        readonly name: N;
-        readonly entity: NameOrRef;
-    } & ExtensionOptionsFor<N>): void;
-    /**
-     * Declares which config key selects the active provider under an
-     * extension point — called by the point-owning foundation (e.g.
-     * `r.extensionSelector("mailTransport", configKeys.provider)`).
-     * Readiness gating counts a provider-feature's `required` keys and
-     * secrets only while that provider is the selected one. Registry-build
-     * fails on duplicate declarations per extension and on selector keys
-     * that no mounted feature declares. A masked tenant selector key makes the
-     * Settings-Hub render one tenant dashboard for the owner: the selector as a
-     * select of the mounted plugin ids, the selected plugin's config and secrets
-     * as panels, and plugin features lose their own tenant nav. `config:write:set`
-     * rejects unknown plugin ids (`""` clears). `options.panels` adds the owner's own
-     * `custom`/`screen` panels to that dashboard, after the selection and before the
-     * plugin panels (a short `screen` id means a screen of the declaring feature).
-     */
-    extensionSelector(extensionName: string, key: {
-        readonly name: string;
-    } | string, options?: {
-        readonly panels?: readonly ExtensionSelectorPanel[];
-    }): void;
-    /**
-     * Marker declaration: this feature provides a cross-feature API under the
-     * given name. The implementation is registered separately as a query or
-     * write handler under the QN pattern; `r.exposesApi` is only a boot-check
-     * surface.
-     *
-     * The boot validator checks that every `r.usesApi(name)` finds a matching
-     * exposer, that the exposer feature is listed in requires/optionalRequires,
-     * and that no API name is exposed more than once.
-     *
-     * ```ts
-     * defineFeature("compliance-profiles", (r) => {
-     *   r.exposesApi("compliance.forTenant");
-     *   r.queryHandler({
-     *     name: "compliance:query:for-tenant",
-     *     // ... actual implementation
-     *   });
-     * });
-     * ```
-     */
-    exposesApi(apiName: string): void;
-    /**
-     * Declares that this feature calls a cross-feature API. The boot validator
-     * checks that another feature provides `r.exposesApi(apiName)` and that
-     * this feature lists it in `r.requires/optionalRequires`.
-     *
-     * ```ts
-     * defineFeature("user-data-rights", (r) => {
-     *   r.requires({ features: ["compliance-profiles"] });
-     *   r.usesApi("compliance.forTenant");
-     * });
-     * ```
-     */
-    usesApi(apiName: string): void;
-    /**
-     * Declares a boot-time mount-invariant for this feature. `fn` runs once
-     * at boot with a ctx exposing every mounted feature — throw to fail the
-     * boot with a clear message. Multiple calls per feature are allowed.
-     *
-     * Use for cross-feature invariants that `r.requires` can't express
-     * because they're conditional (only fail when the feature has a
-     * specific shape), e.g. "if this feature has PII entities, some
-     * user-data-hook feature must be mounted" (the prompt-store trap —
-     * a UserData feature was written but never mounted, and nothing caught
-     * it at boot):
-     *
-     * ```ts
-     * defineFeature("prompt-store", (r) => {
-     *   const promptFields = { text: createTextField({ personal: "self", find: "none" }) };
-     *   r.entity({ name: "prompt", fields: promptFields });
-     *   r.bootCheck(({ features }) => {
-     *     // Conditional on this feature's own shape (has a pii field) —
-     *     // r.requires({ features: ["user-data-hook"] }) can't express that, it would fail
-     *     // even for a prompt-store variant with no PII fields at all.
-     *     const hasPiiField = Object.values(promptFields).some((f) => f.pii);
-     *     const hasUserDataHook = features.some((f) => f.name === "user-data-hook");
-     *     if (hasPiiField && !hasUserDataHook) {
-     *       throw new Error("prompt-store has PII fields but no user-data-hook feature is mounted");
-     *     }
-     *   });
-     * });
-     * ```
-     */
-    bootCheck(fn: BootCheckFn): void;
-    metric(shortName: string, options: MetricOptions): void;
-    metric(definition: {
-        readonly name: string;
-    } & MetricOptions): void;
-    secret(shortName: string, options: SecretOptions): SecretKeyHandle;
-    secret(definition: {
-        readonly name: string;
-    } & SecretOptions): SecretKeyHandle;
-    secretNamespace(shortName: string, options: SecretNamespaceOptions): SecretNamespaceHandle;
-    secretNamespace(definition: {
-        readonly name: string;
-    } & SecretNamespaceOptions): SecretNamespaceHandle;
-    projection(definition: ProjectionDefinition): void;
-    multiStreamProjection(definition: MultiStreamProjectionDefinition): void;
-    extendEntityProjection(entityName: string, extension: EntityProjectionExtension): void;
-    authClaims(fn: AuthClaimsFn): void;
-    claimKey<T extends ClaimKeyType>(shortName: string, options: {
-        readonly type: T;
-    }): ClaimKeyHandle<T>;
-    claimKey<T extends ClaimKeyType>(definition: {
-        readonly name: string;
-        readonly type: T;
-    }): ClaimKeyHandle<T>;
-    screen(definition: ScreenDefinition): void;
-    nav(definition: NavDefinition): void;
-    contentCollection(definition: ContentCollectionDefinition): string;
-    workspace(definition: WorkspaceDefinition): void;
-    httpRoute(definition: HttpRouteDefinition): void;
-    webSocketRoute(definition: WebSocketRouteDefinition): void;
-    storeTable(meta: EntityTableMeta, options: StoreTableOptions): void;
-    treeActions<const TActions extends Record<string, TreeActionDef>>(actions: TActions): TreeActionsHandle<TFeature, TActions>;
-    envSchema(schema: z.ZodObject<z.ZodRawShape>): void;
-};
 export type Registry = {
     readonly features: ReadonlyMap<string, FeatureDefinition>;
     getFeature(name: string): FeatureDefinition | undefined;
@@ -595,4 +288,3 @@ export type Registry = {
     getDefaultWorkspace(): WorkspaceDefinition | undefined;
     getTreeActions(featureName: string): Readonly<Record<string, TreeActionDef>> | undefined;
 };
-export {};

package/dist/fields.js

@@ -47,7 +47,7 @@ function isFieldTypeName(name) {
 export const FIELD_TYPE_NAMES = Object.keys(FIELD_TYPE_NAME_FLAGS).filter(isFieldTypeName);
 // Field types with no bound, editable widget on the auto-wired entityEdit
 // path (render-field.tsx renders a read-only banner instead) — shared by
-// the boot validator (packages/framework/src/engine/boot-validator/screens.ts)
+// the boot validator (packages/framework/src/engine/boot-validator/screens-forms.ts)
 // and the client-side required-field check (packages/renderer/src/app/form-schema.ts).
 // Embedded LIST fields (`multiple: true`) are the one exception — they get
 // their own EmbeddedListField grid widget — callers must check that

package/dist/handlers.d.ts

@@ -256,6 +256,7 @@ type SharedContextFields = {
     readonly signal?: AbortSignal;
     readonly effectiveFeatures?: (tenantId: TenantId) => ReadonlySet<string>;
     readonly scheduleAfterCommit?: (hook: () => Promise<void>) => void;
+    readonly scheduleAfterRollback?: (hook: () => Promise<void>) => void;
     readonly queryAsMember?: MemberReader;
 };
 export type AppContext = SharedContextFields & {
@@ -350,6 +351,10 @@ export type HandlerContext<TMap extends object = KumikoEventTypeMap> = SharedCon
     readonly fetchForWriting: (args: FetchForWritingArgs) => Promise<AggregateStreamHandle>;
     readonly loadAggregate: (aggregateId: string, options?: {
         readonly asOf?: Temporal.Instant;
+        readonly atVersion?: never;
+    } | {
+        readonly atVersion?: number;
+        readonly asOf?: never;
     }) => Promise<readonly import("./event-store-types.ts").StoredEvent[]>;
     readonly archiveStream: (aggregateId: string, args: {
         readonly aggregateType: string;
@@ -405,12 +410,6 @@ export type JobContext = SharedContextFields & {
     readonly triggerEvent?: JobTriggerEvent;
     readonly _tenantId?: TenantId;
 };
-/**
- * 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>;
@@ -632,6 +631,9 @@ export type WriteHandlerDef = {
     /** Per-payload-field limits, e.g. per recipient address. Complements
      *  `rateLimit`; anonymous handlers still need an ip-keyed `rateLimit`. */
     readonly additionalRateLimits?: readonly PayloadRateLimitOption[];
+    /** Tokens each request books on every declared rateLimit bucket, computed from the validated
+     *  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
      *  reservation cannot run, so the dispatcher rejects it unless the top-level batch reserved it. */

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

@@ -0,0 +1,43 @@
+import * as z from "zod";
+import type { AggregateKey } from "./aggregate-types.ts";
+export declare const MAX_LIST_AGGREGATE_MEASURES = 20;
+export declare const LIST_AGGREGATE_MEASURE_KINDS: readonly ["sum", "avg", "count", "min", "max"];
+export type ListAggregateMeasureKind = (typeof LIST_AGGREGATE_MEASURE_KINDS)[number];
+export declare const listAggregatePayloadSchema: z.ZodObject<{
+    groupBy: z.ZodOptional<z.ZodString>;
+    measures: z.ZodDefault<z.ZodArray<z.ZodObject<{
+        field: z.ZodString;
+        kind: z.ZodEnum<{
+            avg: "avg";
+            count: "count";
+            max: "max";
+            min: "min";
+            sum: "sum";
+        }>;
+    }, z.core.$strip>>>;
+}, z.core.$strip>;
+export type ListAggregatePayload = {
+    readonly groupBy?: string | undefined;
+    readonly measures: readonly {
+        readonly field: string;
+        readonly kind: ListAggregateMeasureKind;
+    }[];
+};
+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;
+    readonly count: number;
+    readonly measures: readonly ListAggregateValue[];
+};
+export type ListAggregateResult = {
+    readonly groups: readonly ListAggregateGroup[];
+    readonly truncated?: true;
+    readonly searchTruncated?: true;
+};
+export declare function isListAggregateResult(value: unknown): value is ListAggregateResult;

package/dist/list-aggregate-types.js

@@ -0,0 +1,22 @@
+import * as z from "zod";
+import { isPlainObject } from "./type-guards.js";
+export const MAX_LIST_AGGREGATE_MEASURES = 20;
+export const LIST_AGGREGATE_MEASURE_KINDS = ["sum", "avg", "count", "min", "max"];
+export const listAggregatePayloadSchema = z.object({
+    groupBy: z.string().optional(),
+    measures: z
+        .array(z.object({ field: z.string(), kind: z.enum(LIST_AGGREGATE_MEASURE_KINDS) }))
+        .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.
+export function isListAggregateResult(value) {
+    return (isPlainObject(value) &&
+        Array.isArray(value["groups"]) &&
+        Object.keys(value).every((key) => LIST_AGGREGATE_RESULT_KEYS.includes(key)));
+}

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;
+};