@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/engine/boot-validator/screens-actions.js

@@ -7,7 +7,7 @@ export function isRowClickAction(action) {
     return (action.kind === "navigate" || action.kind === "drawer") && action.rowClick === true;
 }
 // entityList and projectionList both allow a rowAction to double as the
-// row-body click target (rowClick: true, fw#1708/#2164) — at most one per
+// row-body click target (rowClick: true) — at most one per
 // screen, or the renderer can't tell which one should fire.
 export function validateAtMostOneRowClick(featureName, screenId, screenType, rowActions) {
     const rowClickActions = rowActions.filter(isRowClickAction);
@@ -30,18 +30,17 @@ export function readsNavigateParamsAsFormPrefill(target, explicitEntityId, sourc
         return false;
     return sourceScreenEntity === undefined || target.entity !== sourceScreenEntity;
 }
-// Tier 2.7e navigate rowAction → target-screen params validity. Shared by
-// entityList and projectionList (framework#1708) — projectionList has no
+// Navigate rowAction → target-screen params validity. Shared by
+// entityList and projectionList — projectionList has no
 // `screen.entity`, so there's no same-entity row["id"] auto-fill case: any
 // entityEdit target without an explicit entityId reaches create there.
 //
-// dashboard targets (framework#1708 follow-up, commit 4e0d6cb26) also read
-// URL search params — but only for the single `filter.id` a dashboard
-// declares (useFilterParams in dashboard-body.tsx seeds its value from
-// `nav.searchParams[filter.id]`). A dashboard with no `filter` has nowhere
-// for the value to land, and a params extractor whose keys don't include
-// the filter's id would silently miss it — both are boot errors instead of
-// a silently-empty dashboard.
+// Dashboard targets also read URL search params — but only for the single
+// `filter.id` a dashboard declares (useFilterParams in dashboard-body.tsx
+// seeds its value from `nav.searchParams[filter.id]`). A dashboard with no
+// `filter` has nowhere for the value to land, and a params extractor whose
+// keys don't include the filter's id would silently miss it — both are boot
+// errors instead of a silently-empty dashboard.
 export function validateRowActionNavigateParams(featureName, screenId, screenType, screenEntity, action, target, actionLabel = "rowAction") {
     // skip: not a navigate-with-params action — nothing to validate here.
     if (action.kind !== "navigate" || action.params === undefined)
@@ -122,7 +121,7 @@ export function validateActionHasIcon(featureName, screenId, screenType, context
             `its kebab segments via the default icon map (resolveActionIcon).`);
     }
 }
-// Tier 2.7e-3: pin an action's declarative field references against the entity
+// Pin an action's declarative field references against the entity
 // fields — a typo in pick/map source fields or visible.field would otherwise
 // silently yield `undefined` in the payload or permanently wrong visibility
 // (same "typo only surfaces on click" class as navigate/handler). Exported for
@@ -203,12 +202,12 @@ export function validateScreenNavTarget(featureName, screenId, screenKind, field
 }
 // kind:"drawer" resolves same-feature only — unlike navigate/redirect,
 // which the runtime router resolves app-wide (see the comment on
-// validateScreens below), the drawer mounts the target inline using this
+// buildScreenValidationContext in screens.ts), the drawer mounts the target inline using this
 // feature's schema, so a cross-feature reference could never actually
 // render. Two distinct failure messages: dangling reference vs. wrong
-// screen type. Shared by ToolbarAction (fw#2225) and RowAction (fw#2710)
-// drawer variants — same target-resolution rule, only the label in the
-// error message ("toolbarAction" vs. "rowAction" vs. "action") differs.
+// screen type. Shared by ToolbarAction and RowAction drawer variants —
+// same target-resolution rule, only the label in the error message
+// ("toolbarAction" vs. "rowAction" vs. "action") differs.
 export function validateDrawerTargetAction(featureName, screenId, screenKind, actionLabel, action, screens) {
     const target = screens[action.screen];
     if (target === undefined) {
@@ -337,8 +336,8 @@ export function resolveRowActionNavigateTarget(featureName, screenId, screenType
 // redirect is either a short screen id (same-feature, e.g. "item-list") or
 // a fully-qualified cross-feature QN (`<feature>:screen:<id>`) — the
 // renderer strips the latter to the short id (lastSegment) when
-// navigating, which the nav-router resolves app-wide (#1946). The object
-// form (fw#2670) carries the same target under `screen` plus the payload
+// navigating, which the nav-router resolves app-wide. The object
+// form carries the same target under `screen` plus the payload
 // field `idFrom`. Shared by actionForm/secretMint (validateInlineFormNavTargets)
 // and entityEdit — same rule, same error message, one place to keep them in sync.
 export function validateRedirectTarget(feature, screenId, screenKind, redirect, lookups, 
@@ -486,3 +485,10 @@ export function validateNavigateActionTab(featureName, screenId, screenType, act
         return;
     resolveRowActionNavigateTarget(featureName, screenId, screenType, actionLabel, action, lookups.allScreenQns, lookups.navTargetShortIds, lookups.screensByShortId, lookups.detailForScreens);
 }
+export function assertWriteHandlerRegistered(featureName, subject, handler, allWriteHandlerQns) {
+    if (!allWriteHandlerQns.has(handler)) {
+        throw new Error(`[Feature ${featureName}] ${subject} handler "${handler}" ` +
+            `is not a registered write-handler. Check the QN spelling (expected ` +
+            `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
+    }
+}

package/dist/engine/boot-validator/screens-dashboard.js

@@ -1,6 +1,6 @@
 import { DASHBOARD_MIN_REFRESH_SECONDS } from "@cosmicdrift/kumiko-types/screen";
 import { normalizeListColumn } from "../screen-helpers.js";
-import { isRowClickAction, resolveRowActionNavigateTarget, resolveScreenTargetQn, validateActionHasIcon, validateClientActionName, validateRowActionNavigateParams, } from "./screens-actions.js";
+import { assertWriteHandlerRegistered, isRowClickAction, resolveRowActionNavigateTarget, resolveScreenTargetQn, validateActionHasIcon, validateClientActionName, validateRowActionNavigateParams, } from "./screens-actions.js";
 import { assertRefTargetRegistered, validateColumnRendererForm } from "./screens-lists.js";
 // Panel-driven, no entity — structural checks (unique panel ids, non-empty
 // queries/columns/valueField); the query contracts (stat record, points
@@ -68,10 +68,7 @@ export function validateDashboardActions(featureName, screenId, screen, allWrite
                 throw new Error(`${where} sets redirect — a dashboard action stays on the dashboard and refetches ` +
                     `after success. Remove redirect.`);
             }
-            if (!allWriteHandlerQns.has(action.handler)) {
-                throw new Error(`${where} handler "${action.handler}" is not a registered write-handler. Check the QN ` +
-                    `spelling (expected "<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
-            }
+            assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (dashboard) action "${action.id}"`, action.handler, allWriteHandlerQns);
         }
     }
 }

package/dist/engine/boot-validator/screens-forms.js

@@ -2,9 +2,9 @@ import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs } from "@cosmicdrift/kumik
 import { isKebabSegment } from "../qualified-name.js";
 import { isExtensionEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
 import { validateFormDerivations, validateFormDerivationsEnforced } from "./form-derivations.js";
-import { isSensitiveOrPasswordField, validateIdlessSuccessLink, validateRedirectTarget, validateScreenNavTarget, } from "./screens-actions.js";
+import { assertWriteHandlerRegistered, isSensitiveOrPasswordField, validateIdlessSuccessLink, validateRedirectTarget, validateScreenNavTarget, } from "./screens-actions.js";
 // A field type in NO_WIDGET_FIELD_TYPES renders read-only on the auto-wired
-// entityEdit path (#1925) — a required field the user can never fill would
+// entityEdit path — a required field the user can never fill would
 // block every save. Only the statically-resolvable case is caught here: a
 // literal `required: true` (screen-spec override or entity-level default).
 // A dynamic FieldCondition depends on runtime form values and can't be
@@ -95,7 +95,7 @@ export function validateNoWidgetRequiredField(featureName, screenId, entityDef,
     if (fieldDef === undefined || !NO_WIDGET_FIELD_TYPES.includes(fieldDef.type))
         return;
     // Embedded LIST fields (`multiple: true`) get their own EmbeddedListField
-    // grid widget (#1838) — only plain (non-list) embedded has no widget.
+    // grid widget — only plain (non-list) embedded has no widget.
     const isEmbeddedList = fieldDef.type === "embedded" && fieldDef.multiple === true;
     // skip: list variant has a widget — not the no-widget case this guard targets.
     if (isEmbeddedList)
@@ -115,8 +115,7 @@ export function validateNoWidgetRequiredField(featureName, screenId, entityDef,
 }
 // Shared by projectionDetail and entityEdit: a tab strip needs something to
 // label each tab with and a stable id per tab — the id anchors the ?tab=
-// param on projectionDetail and the jump-to-erroring-tab logic on entityEdit
-// (fw#3134).
+// param on projectionDetail and the jump-to-erroring-tab logic on entityEdit.
 export function validateTabSections(featureName, screenId, screenType, sections) {
     if (sections.length < 2) {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${screenType}) has mode: "tabs" but only ` +
@@ -149,7 +148,7 @@ export function validateTabSections(featureName, screenId, screenType, sections)
 export function validateWizardLayout(featureName, screenId, screenType, layout, featureMap) {
     // entityEdit renders tabs like wizard steps: every section stays mounted,
     // submit validates across all of them, and a field error jumps to the tab
-    // holding it (fw#3134). The other three have no such jump — actionForm and
+    // holding it. The other three have no such jump — actionForm and
     // secretMint are one-shot forms, configEdit fires a write per field — so a
     // required field on a hidden tab would still block their submit silently.
     if (layout.mode === "tabs") {
@@ -201,7 +200,7 @@ export function validateWizardLayout(featureName, screenId, screenType, layout,
 //
 // Field-level renderer QN strings (cross-feature `component:` references)
 // are NOT validated here — the r.uiComponent registry that would resolve
-// them ships in M4/M5. Until then those are kept opaque on purpose.
+// them ships later. Until then those are kept opaque on purpose.
 // Shared by the mint step's own handler (screen.handler) and its optional
 // confirm step (confirm.handler) — both are a bare write-handler QN with the
 // same registration requirement.
@@ -209,11 +208,7 @@ function validateWriteHandlerRegistered(featureName, screenId, context, handler,
     if (!handler || typeof handler !== "string") {
         throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) has empty or non-string handler. Set handler to a non-empty handler name.`);
     }
-    if (!allWriteHandlerQns.has(handler)) {
-        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (${context}) handler "${handler}" ` +
-            `is not a registered write-handler. Check the QN spelling (expected ` +
-            `"<feature>:write:<short>") and that the handler is declared via r.writeHandler(...).`);
-    }
+    assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (${context})`, handler, allWriteHandlerQns);
 }
 // Every field entry must carry a `type` discriminator. An author typo
 // (`title: { required: true }` without a type) would otherwise let
@@ -226,7 +221,7 @@ function validateWriteHandlerRegistered(featureName, screenId, context, handler,
 // secretMint's own `confirm` step — a second, independent inline form on the
 // same screen — can reuse the same checks as its `fields`/`layout` pair.
 // `allowEmpty` is only ever true for a secretMint's own mint step (an
-// input-less mint, fw#2838): the secret is server-generated and the mint
+// input-less mint): the secret is server-generated and the mint
 // step is just its submit button — actionForm and the confirm step always
 // require at least one field.
 function validateFormFieldsMap(featureName, screenId, context, fields, allowEmpty) {
@@ -330,7 +325,7 @@ export function validateFormSelectOptions(featureName, screenId, context, fieldN
         }
     }
 }
-// Fail-closed currency-source gate (fw#2839), the runtime half of the
+// Fail-closed currency-source gate, the runtime half of the
 // narrowed `FormFieldDefinition` — an untyped JS consumer has no compiler to
 // stop it. An inline form screen has no entity, so a money field there can't
 // borrow `entity.defaultCurrency`: without a declared source the renderer
@@ -454,7 +449,7 @@ function validateInlineFormNavTargets(feature, screenId, screen, kind, lookups)
 export function validateInlineFormScreen(feature, screenId, screen, kind, allWriteHandlerQns, lookups, featureMap) {
     validateWriteHandlerRegistered(feature.name, screenId, kind, screen.handler, allWriteHandlerQns);
     // Only a secretMint's own mint step may skip fields/sections entirely
-    // (input-less mint, fw#2838) — actionForm always needs at least one field.
+    // (input-less mint) — actionForm always needs at least one field.
     const allowEmptyMintForm = kind === "secretMint";
     const fieldNames = validateFormFieldsMap(feature.name, screenId, kind, screen.fields, allowEmptyMintForm);
     validateFormLayoutSections(feature.name, screenId, kind, screen.layout, fieldNames, screen.fields, allowEmptyMintForm && fieldNames.size === 0);
@@ -472,14 +467,14 @@ export function validateInlineFormScreen(feature, screenId, screen, kind, allWri
     }
     validateInlineFormNavTargets(feature, screenId, screen, kind, lookups);
 }
-// SecretMintConfirmStep (fw#2838): an optional proof-of-receipt form rendered
+// SecretMintConfirmStep: an optional proof-of-receipt form rendered
 // on the reveal card in place of the bare acknowledge button (TOTP enrollment:
 // scan the code, then enter one). Unlike the mint step, confirm always needs
 // at least one field — a step whose only job is proving receipt with no input
 // would be meaningless — and its layout is a single plain form, never a
 // wizard/tabs flow and never a persisted draft: a one-time reveal-confirm is
 // not a multi-step flow, and persisting a draft of it would re-open the leak
-// fw#2548 closed (a lingering copy of the just-revealed secret in storage).
+// (a lingering copy of the just-revealed secret in storage).
 export function validateSecretMintConfirm(feature, screenId, screen, allWriteHandlerQns) {
     const confirm = screen.confirm;
     // skip: the screen declares no confirm step — nothing to validate.

package/dist/engine/boot-validator/screens-kind-config-edit.d.ts

@@ -0,0 +1,3 @@
+import type { ConfigEditScreenDefinition } from "../types/screen.ts";
+import { type ScreenValidationContext } from "./screens-kind-shared.ts";
+export declare function validateConfigEditScreen(ctx: ScreenValidationContext, screenId: string, screen: ConfigEditScreenDefinition): void;

package/dist/engine/boot-validator/screens-kind-config-edit.js

@@ -0,0 +1,88 @@
+import { isEncryptedAtRest } from "../config-helpers.js";
+import { isExtensionEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
+import { isWriteOnlyField, validateConfigEditSecretField, validateFieldsXorGroups, validateFormSelectOptions, validateWizardLayout, } from "./screens-forms.js";
+import { assertExtensionSectionHasComponent, rejectEmptySections, rejectProjectionDetailOnlySection, } from "./screens-kind-shared.js";
+function validateConfigEditFields(featureName, screenId, screen, fieldNames) {
+    if (fieldNames.size === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (configEdit) has empty fields map — ` +
+            `declare at least one field.`);
+    }
+    for (const [fname, fdef] of Object.entries(screen.fields)) {
+        const fieldType = fdef.type;
+        if (typeof fieldType !== "string" || fieldType.length === 0) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (configEdit) field "${fname}" has no ` +
+                `\`type\` set. Each field must declare a type (e.g. "text", "number", "select").`);
+        }
+        validateFormSelectOptions(featureName, screenId, "configEdit", fname, fdef, fieldNames);
+    }
+}
+function validateConfigEditFieldsSection(featureName, screenId, fieldNames, section) {
+    rejectProjectionDetailOnlySection(featureName, screenId, "configEdit", section);
+    validateFieldsXorGroups(`[Feature ${featureName}] Screen "${screenId}" (configEdit)`, section);
+    for (const fieldSpec of sectionFieldSpecs(section)) {
+        const normalized = normalizeEditField(fieldSpec);
+        if (!fieldNames.has(normalized.field)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (configEdit) layout references unknown ` +
+                `field "${normalized.field}". Known fields: ${[...fieldNames].sort().join(", ")}`);
+        }
+    }
+}
+function validateConfigEditSection(featureName, screenId, fieldNames, section) {
+    if (isExtensionEditSection(section)) {
+        assertExtensionSectionHasComponent(featureName, screenId, "configEdit", section);
+    }
+    else {
+        validateConfigEditFieldsSection(featureName, screenId, fieldNames, section);
+    }
+}
+// configKeys: every fieldName must have a mapping entry, and every qualified
+// key must exist in the registry.
+function validateConfigEditFieldKey(ctx, screenId, screen, fname) {
+    const secretQn = screen.secretKeys?.[fname];
+    if (secretQn !== undefined) {
+        validateConfigEditSecretField(ctx.feature.name, screen, fname, secretQn, ctx.featureMap);
+    }
+    else {
+        validateConfigKeyMapping(ctx, screenId, screen, fname);
+    }
+}
+function validateConfigKeyMapping(ctx, screenId, screen, fname) {
+    const featureName = ctx.feature.name;
+    const qualified = screen.configKeys[fname];
+    if (qualified === undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (configEdit) field "${fname}" has ` +
+            `no entry in the configKeys map. Every declared field needs a mapping to a ` +
+            `qualified config key (\`<feature>:config:<short>\`). Add one to configKeys.`);
+    }
+    const configKeyDef = ctx.configKeyDefsByQn.get(qualified);
+    if (configKeyDef === undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (configEdit) field "${fname}" → ` +
+            `Config key "${qualified}" is not declared in any feature registry. Typo? ` +
+            `Expected format: "<feature>:config:<short>". Known keys: ${[...ctx.configKeyDefsByQn.keys()].sort().join(", ") || "(none)"}`);
+    }
+    if (isWriteOnlyField(screen.fields[fname]) && !isEncryptedAtRest(configKeyDef)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (configEdit) field "${fname}" declares writeOnly ` +
+            `but config key "${qualified}" is not encrypted at rest — writeOnly on a configEdit field ` +
+            `only hides a stored secret (declare the key with encrypted: true or backing: "secrets").`);
+    }
+}
+// Validate configEdit layout and fields like actionForm, then verify that
+// every qualified config key is registered and its scope matches the key.
+export function validateConfigEditScreen(ctx, screenId, screen) {
+    const featureName = ctx.feature.name;
+    const fieldNames = new Set(Object.keys(screen.fields));
+    validateConfigEditFields(featureName, screenId, screen, fieldNames);
+    rejectEmptySections(featureName, screenId, "configEdit", screen.layout.sections.length);
+    for (const section of screen.layout.sections) {
+        validateConfigEditSection(featureName, screenId, fieldNames, section);
+    }
+    validateWizardLayout(featureName, screenId, "configEdit", screen.layout, ctx.featureMap);
+    for (const fname of Object.keys(screen.secretKeys ?? {})) {
+        if (!fieldNames.has(fname)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (configEdit) secretKeys names unknown field "${fname}".`);
+        }
+    }
+    for (const fname of fieldNames) {
+        validateConfigEditFieldKey(ctx, screenId, screen, fname);
+    }
+}

package/dist/engine/boot-validator/screens-kind-entity-edit.d.ts

@@ -0,0 +1,3 @@
+import type { EntityEditScreenDefinition } from "../types/screen.ts";
+import { type ScreenValidationContext } from "./screens-kind-shared.ts";
+export declare function validateEntityEditScreen(ctx: ScreenValidationContext, screenId: string, screen: EntityEditScreenDefinition): void;

package/dist/engine/boot-validator/screens-kind-entity-edit.js

@@ -0,0 +1,55 @@
+import { isExtensionEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
+import { validateRedirectTarget } from "./screens-actions.js";
+import { validateEditFieldExtras, validateFieldFormRefs, validateFieldsXorGroups, validateFillActionTarget, validateNoWidgetRequiredField, validateWizardLayout, } from "./screens-forms.js";
+import { assertExtensionSectionHasComponent, buildUnknownFieldMessage, rejectEmptySections, rejectProjectionDetailOnlySection, resolveScreenEntity, validateRecordHeaderAction, validateRecordSectionActions, } from "./screens-kind-shared.js";
+function validateEntityEditField(featureName, screenId, entityName, entityDef, fieldNames, fieldSpec) {
+    const normalized = normalizeEditField(fieldSpec);
+    if (!fieldNames.has(normalized.field)) {
+        throw new Error(buildUnknownFieldMessage(featureName, screenId, normalized.field, entityName, fieldNames));
+    }
+    validateNoWidgetRequiredField(featureName, screenId, entityDef, normalized);
+    validateEditFieldExtras(featureName, screenId, entityDef, normalized);
+    const fieldWhere = `[Feature ${featureName}] Screen "${screenId}" (entityEdit) field "${normalized.field}"`;
+    validateFieldFormRefs(fieldWhere, normalized, fieldNames);
+    validateFillActionTarget(fieldWhere, normalized, entityDef.fields[normalized.field]);
+}
+function validateEntityEditSection(ctx, screenId, screen, entityDef, fieldNames, section) {
+    const featureName = ctx.feature.name;
+    validateRecordSectionActions(ctx, screenId, "entityEdit", section);
+    if (isExtensionEditSection(section)) {
+        assertExtensionSectionHasComponent(featureName, screenId, "entityEdit", section);
+    }
+    else {
+        rejectProjectionDetailOnlySection(featureName, screenId, "entityEdit", section);
+        validateFieldsXorGroups(`[Feature ${featureName}] Screen "${screenId}" (entityEdit)`, section);
+        for (const fieldSpec of sectionFieldSpecs(section)) {
+            validateEntityEditField(featureName, screenId, screen.entity, entityDef, fieldNames, fieldSpec);
+        }
+    }
+}
+export function validateEntityEditScreen(ctx, screenId, screen) {
+    const featureName = ctx.feature.name;
+    const entityDef = resolveScreenEntity(ctx, screenId, screen.entity);
+    const fieldNames = new Set(Object.keys(entityDef.fields));
+    rejectEmptySections(featureName, screenId, "entityEdit", screen.layout.sections.length);
+    for (const section of screen.layout.sections) {
+        validateEntityEditSection(ctx, screenId, screen, entityDef, fieldNames, section);
+    }
+    validateWizardLayout(featureName, screenId, "entityEdit", screen.layout, ctx.featureMap);
+    for (const action of screen.actions ?? []) {
+        validateRecordHeaderAction(ctx, screenId, "entityEdit", screen.entity, action);
+    }
+    if (screen.recordTitleField !== undefined && !fieldNames.has(screen.recordTitleField)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityEdit) recordTitleField ` +
+            `"${screen.recordTitleField}" is not a field of entity "${screen.entity}" ` +
+            `(known: ${[...fieldNames].sort().join(", ")}).`);
+    }
+    if (typeof screen.readOnly === "object" && !fieldNames.has(screen.readOnly.field)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityEdit) readOnly condition field ` +
+            `"${screen.readOnly.field}" is not a field of entity "${screen.entity}" ` +
+            `(known: ${[...fieldNames].sort().join(", ")}).`);
+    }
+    if (screen.redirect !== undefined) {
+        validateRedirectTarget(ctx.feature, screenId, "entityEdit", screen.redirect, ctx);
+    }
+}

package/dist/engine/boot-validator/screens-kind-entity-list.d.ts

@@ -0,0 +1,3 @@
+import type { EntityListScreenDefinition } from "../types/screen.ts";
+import { type ScreenValidationContext } from "./screens-kind-shared.ts";
+export declare function validateEntityListScreen(ctx: ScreenValidationContext, screenId: string, screen: EntityListScreenDefinition): void;

package/dist/engine/boot-validator/screens-kind-entity-list.js

@@ -0,0 +1,228 @@
+import { isListFilterAllowed } from "../../db/entity-field-encryption.js";
+import { rowMetaFieldNames } from "../../db/table-builder.js";
+import { qualifyEntityName } from "../qualified-name.js";
+import { getAllowedFilterOps, isFieldFilterable } from "../screen-filter-ops.js";
+import { normalizeListColumn } from "../screen-helpers.js";
+import { LIST_ROW_META_COLUMN_NAMES } from "./entity-list-screens.js";
+import { assertWriteHandlerRegistered, rejectRedirectOnListRowAction, resolveRowActionNavigateTarget, validateActionFieldRefs, validateAtMostOneRowClick, validateDrawerTargetAction, validateRowActionNavigateParams, } from "./screens-actions.js";
+import { buildUnknownFieldMessage, listActionContext, rejectEmptyColumns, rejectNonArrayInFilter, resolveScreenEntity, validateListColumnRendering, } from "./screens-kind-shared.js";
+import { validateRelatedListSection, validateRowActionTarget } from "./screens-lists.js";
+function resolveEntityListFields(ctx, screenId, entityName) {
+    const entityDef = resolveScreenEntity(ctx, screenId, entityName);
+    const fieldNames = new Set(Object.keys(entityDef.fields));
+    // List columns may also name a read-time derived field (not a stored
+    // column). Allowed for display; deliberately NOT added to `fieldNames`, so
+    // defaultSort/filter on a derived field still fails — server-side sort over
+    // a non-column is a silent no-op (see DerivedFieldDef).
+    const columnFieldNames = entityDef.derivedFields !== undefined
+        ? new Set([...fieldNames, ...Object.keys(entityDef.derivedFields)])
+        : fieldNames;
+    const rowMeta = rowMetaFieldNames(entityDef.softDelete ?? false);
+    return { entityDef, fieldNames, columnFieldNames, rowMeta };
+}
+function validateEntityListColumns(ctx, screenId, screen, fields) {
+    const featureName = ctx.feature.name;
+    rejectEmptyColumns(featureName, screenId, "entityList", screen.columns.length);
+    for (const col of screen.columns) {
+        const normalized = normalizeListColumn(col);
+        // A row-meta column (id/tenantId/version/insertedAt/modifiedAt/...) is a
+        // real DB column without being a declared entity field — e.g. a
+        // SystemAdmin cross-tenant list exposing tenantId. Accept it like a
+        // regular field name — but only the columns computeListViewModel can
+        // actually render (LIST_ROW_META_COLUMN_NAMES), not the wider
+        // softDelete-aware rowMeta set used for payload/visible refs.
+        //
+        // A virtual presentational column (drawn by a columnRenderer component
+        // from the row, e.g. tag chips) needs BOTH a label AND a renderer —
+        // renderer is what actually makes it "virtual" (label alone still
+        // needs list.ts's virtual-branch to have something to draw). A column
+        // with neither matching a real field/row-meta column NOR a renderer is
+        // a typo worth failing the boot.
+        if (!fields.columnFieldNames.has(normalized.field) &&
+            !LIST_ROW_META_COLUMN_NAMES.has(normalized.field) &&
+            !(normalized.label !== undefined && normalized.renderer !== undefined)) {
+            throw new Error(buildUnknownFieldMessage(featureName, screenId, normalized.field, screen.entity, fields.columnFieldNames));
+        }
+        validateListColumnRendering(ctx, screenId, "entityList", normalized);
+    }
+}
+function validateEntityListDefaultSort(featureName, screenId, defaultSort, fields) {
+    const sortField = defaultSort.field;
+    if (!fields.fieldNames.has(sortField)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) defaultSort references unknown ` +
+            `field "${sortField}". Known fields: ${[...fields.fieldNames].sort().join(", ")}`);
+    }
+    // `sortable: true` is required so the UI never sorts on a column that has
+    // no server-side DB index or that the schema deliberately keeps unsortable
+    // (audit fields, computed values). `sortable` currently
+    // exists only on TextFieldDef; the `in` narrowing also permits other
+    // field types without an explicit flag, which is acceptable because
+    // Number/Date fields are naturally sortable. Authors can mark them
+    // sortable when their field type supports it.
+    const fieldDef = fields.entityDef.fields[sortField];
+    const isSortable = fieldDef !== undefined && "sortable" in fieldDef && fieldDef.sortable === true;
+    if (!isSortable) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) defaultSort.field "${sortField}" ` +
+            `is not sortable. Set sortable: true on the field definition or pick another field.`);
+    }
+}
+// Screen filters are checked in three layers:
+//   1) The field exists on the entity; a typo would otherwise produce an
+//      empty list instead of a clear boot failure.
+//   2) The field has `filterable: true`, preventing accidental filtering
+//      of audit, computed, or encrypted fields.
+//   3) The operation matches the field type, so lt/gt on text fields
+//      fails at boot instead of causing surprising runtime behavior.
+// Additionally, "in" requires a readonly array.
+function validateEntityListFilter(featureName, screenId, filter, fields) {
+    const filterField = filter.field;
+    if (!fields.fieldNames.has(filterField)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) filter references unknown ` +
+            `field "${filterField}". Known fields: ${[...fields.fieldNames].sort().join(", ")}`);
+    }
+    if (!isListFilterAllowed(fields.entityDef, filterField, filter)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) filter references field ` +
+            `"${filterField}" which is encrypted, personal or secret, so the list handler rejects ` +
+            `this filter at runtime. Only op "eq" works on a personal field with find: "exact" or ` +
+            `"fuzzy"; otherwise drop the filter or filter on another field.`);
+    }
+    const fieldDef = fields.entityDef.fields[filterField];
+    if (fieldDef !== undefined && !isFieldFilterable(fieldDef)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) filter references field ` +
+            `"${filterField}" which is not filterable. Set filterable: true on the field ` +
+            `definition or pick another field.`);
+    }
+    if (fieldDef !== undefined) {
+        const allowedOps = getAllowedFilterOps(fieldDef);
+        if (!allowedOps.includes(filter.op)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) filter.op ` +
+                `"${filter.op}" is not allowed on field "${filterField}" ` +
+                `(type "${fieldDef.type}"). Allowed ops: ${allowedOps.join(", ") || "(none)"}.`);
+        }
+    }
+    rejectNonArrayInFilter(featureName, screenId, "entityList", filter);
+}
+// The renderer's default-entityId fallback (row["id"]) only fires for a
+// same-feature entityEdit target — it can't safely guess the id for a screen
+// owned by a different feature. Cross-feature + entityEdit therefore MUST set
+// an explicit entityId, or the edit screen silently opens with no entity
+// context at runtime. Entity-targets are exempt: the renderer always supplies
+// an id for them (explicit entityId, else row["id"]), regardless of which
+// feature the resolved detailFor screen belongs to.
+function rejectCrossFeatureEditTargetWithoutEntityId(featureName, screenId, action, target) {
+    if (action.screen !== undefined &&
+        target !== undefined &&
+        target.featureName !== featureName &&
+        target.screen.type === "entityEdit" &&
+        action.entityId === undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) rowAction "${action.id}" ` +
+            `navigates cross-feature to entityEdit screen "${action.screen}" (feature ` +
+            `"${target.featureName}") without an explicit entityId field — the renderer's ` +
+            `same-feature row["id"] fallback does not apply across features. Set entityId to ` +
+            `the row field that names the target entity's id.`);
+    }
+}
+// Pin rowActions at boot: a navigate target must exist and a writeHandler QN
+// must be registered. Typos would otherwise only surface on the first click as
+// "Screen not found" or a 404.
+function validateEntityListRowAction(ctx, screenId, screen, fields, action) {
+    const featureName = ctx.feature.name;
+    rejectRedirectOnListRowAction(featureName, screenId, "entityList", action);
+    if (action.kind === "navigate") {
+        const target = resolveRowActionNavigateTarget(featureName, screenId, "entityList", "rowAction", action, ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
+        rejectCrossFeatureEditTargetWithoutEntityId(featureName, screenId, action, target);
+        // params only have a reader in actionForm and entityEdit-CREATE; on
+        // projectionDetail/dashboard/configEdit/entityEdit-update they are
+        // silently ignored at runtime. `custom` is deliberately exempt: it renders
+        // an app-registered component the framework has no visibility into, so
+        // flagging it would be a false positive on working code.
+        //
+        // Whether an entityEdit target lands in create or update mode is decided
+        // by the same rule the renderer's runNavigate() uses: an explicit
+        // entityId always forces update mode, and (absent an explicit entityId) a
+        // same-entity target gets row["id"] auto-injected — only a cross-entity
+        // target with no explicit entityId reaches create.
+        validateRowActionNavigateParams(featureName, screenId, "entityList", screen.entity, action, target);
+    }
+    else {
+        validateRowActionTarget(listActionContext(ctx, screenId, "entityList", screen.entity, `Screen "${screenId}" (entityList)`), "rowAction", "rowAction", action);
+    }
+    validateActionFieldRefs(featureName, screenId, "rowAction", action.id, action, fields.fieldNames, fields.rowMeta);
+}
+// toolbarActions, analogous to rowActions: misspelled navigate targets and
+// unregistered writeHandler QNs fail at boot instead of on the first click.
+function validateEntityListToolbarAction(ctx, screenId, fields, action) {
+    const featureName = ctx.feature.name;
+    if (action.kind === "navigate") {
+        const candidateQn = qualifyEntityName(featureName, "screen", action.screen);
+        if (!ctx.allScreenQns.has(candidateQn) && !ctx.navTargetShortIds.has(action.screen)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) toolbarAction "${action.id}" ` +
+                `navigate-target "${action.screen}" does not resolve to a registered screen in any feature. Use "<feature>:screen:<id>" of an existing screen.`);
+        }
+        if (action.tab !== undefined) {
+            resolveRowActionNavigateTarget(featureName, screenId, "entityList", "toolbarAction", action, ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
+        }
+    }
+    else if (action.kind === "drawer") {
+        validateDrawerTargetAction(featureName, screenId, "entityList", "toolbarAction", action, ctx.feature.screens);
+    }
+    else {
+        assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (entityList) toolbarAction "${action.id}"`, action.handler, ctx.allWriteHandlerQns);
+    }
+    validateActionFieldRefs(featureName, screenId, "toolbarAction", action.id, action, fields.fieldNames, fields.rowMeta);
+}
+function validateEntityListExpandableRow(ctx, screenId, expandableRow, fields) {
+    validateRelatedListSection({
+        featureName: ctx.feature.name,
+        featureMap: ctx.featureMap,
+        screenId,
+        screenType: "entityList expandableRow",
+        where: `Screen "${screenId}" (entityList) expandableRow "${expandableRow.title}"`,
+        section: expandableRow,
+        screens: ctx.feature.screens,
+        allWriteHandlerQns: ctx.allWriteHandlerQns,
+        allScreenQns: ctx.allScreenQns,
+        navTargetShortIds: ctx.navTargetShortIds,
+        screensByShortId: ctx.screensByShortId,
+        detailForScreens: ctx.detailForScreens,
+    });
+    // Toolbar actions of the expansion evaluate against the host row.
+    for (const action of expandableRow.toolbarActions ?? []) {
+        validateActionFieldRefs(ctx.feature.name, screenId, "toolbarAction", action.id, action, fields.fieldNames, fields.rowMeta);
+    }
+}
+export function validateEntityListScreen(ctx, screenId, screen) {
+    const featureName = ctx.feature.name;
+    const fields = resolveEntityListFields(ctx, screenId, screen.entity);
+    validateEntityListColumns(ctx, screenId, screen, fields);
+    // Validate pagination, sorting, and search at boot so authoring errors
+    // fail before runtime debugging of empty or incorrectly sorted lists.
+    if (screen.pageSize !== undefined && screen.pageSize <= 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) has pageSize=${screen.pageSize} — ` +
+            `must be a positive integer.`);
+    }
+    if (screen.defaultSort !== undefined) {
+        validateEntityListDefaultSort(featureName, screenId, screen.defaultSort, fields);
+    }
+    if (screen.createScreen !== undefined &&
+        !Object.hasOwn(ctx.feature.screens, screen.createScreen)) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (entityList) createScreen ` +
+            `"${screen.createScreen}" does not resolve to a registered screen in this feature. ` +
+            `Known screens in this feature: ${Object.keys(ctx.feature.screens).sort().join(", ") || "(none)"}.`);
+    }
+    if (screen.filter !== undefined) {
+        validateEntityListFilter(featureName, screenId, screen.filter, fields);
+    }
+    if (screen.rowActions !== undefined) {
+        for (const action of screen.rowActions) {
+            validateEntityListRowAction(ctx, screenId, screen, fields, action);
+        }
+        validateAtMostOneRowClick(featureName, screenId, "entityList", screen.rowActions);
+    }
+    for (const action of screen.toolbarActions ?? []) {
+        validateEntityListToolbarAction(ctx, screenId, fields, action);
+    }
+    if (screen.expandableRow !== undefined) {
+        validateEntityListExpandableRow(ctx, screenId, screen.expandableRow, fields);
+    }
+}

package/dist/engine/boot-validator/screens-kind-projection-detail.d.ts

@@ -0,0 +1,3 @@
+import type { ProjectionDetailScreenDefinition } from "../types/screen.ts";
+import { type ScreenValidationContext } from "./screens-kind-shared.ts";
+export declare function validateProjectionDetailScreen(ctx: ScreenValidationContext, screenId: string, screen: ProjectionDetailScreenDefinition): void;