@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

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;

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

@@ -0,0 +1,235 @@
+import { SELECT_OPTION_TONES } from "@cosmicdrift/kumiko-types/fields";
+import { isExtensionEditSection, isFieldsEditSection, isWriteFormEditSection, normalizeEditField, sectionFieldSpecs, } from "../screen-helpers.js";
+import { assertWriteHandlerRegistered, resolveRowActionNavigateTarget, validateActionHasIcon, validatePrimaryActionTarget, } from "./screens-actions.js";
+import { rejectWriteOnlyFormField, validateFieldsXorGroups, validateFormSelectOptions, validateTabSections, } from "./screens-forms.js";
+import { assertExtensionSectionHasComponent, editSectionLabel, listActionContext, navigateActionFromLink, rejectEmptySections, rejectMissingQuery, validateRecordHeaderAction, validateRecordSectionActions, } from "./screens-kind-shared.js";
+import { assertRefTargetRegistered, validateListActionTargets, validateRelatedListSection, } from "./screens-lists.js";
+import { isSelectOptionTone } from "./select-option-tone.js";
+function validateProjectionDetailFlags(featureName, screenId, screen) {
+    if (screen.singleton === true && screen.idParam !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) sets both singleton: true ` +
+            `and idParam — singleton means the server picks the row from the caller's context, so there ` +
+            `is no row id to send under idParam. Remove idParam.`);
+    }
+    // singleton has no row id in the path, but the auto-generated "Edit"
+    // action (defaultEditAction in kumiko-screen.tsx) navigates
+    // to the detailFor entity's entityEdit screen using that path id —
+    // under singleton it would silently open that screen in CREATE mode
+    // instead of editing the singleton row. Reject rather than let that
+    // win silently, same as the idParam check above.
+    if (screen.singleton === true && screen.detailFor !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) sets both singleton: true ` +
+            `and detailFor — the auto-generated "Edit" action navigates using the path's row id, which a ` +
+            `singleton screen never has. Remove detailFor, or declare an explicit "edit" action instead.`);
+    }
+    if (screen.recordTitleField !== undefined && screen.header !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) sets both header and ` +
+            `recordTitleField — header.title already names the record, so drop recordTitleField.`);
+    }
+}
+function validateProjectionDetailTabs(featureName, screenId, screen) {
+    if (screen.layout.mode === "tabs") {
+        validateTabSections(featureName, screenId, "projectionDetail", screen.layout.sections);
+        for (const section of screen.layout.sections) {
+            if (isFieldsEditSection(section) && "groups" in section && section.actions !== undefined) {
+                throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.id}" ` +
+                    `declares both groups and actions in tabs mode — actions has no single group's Card to sit ` +
+                    `in, and an extra title-less Card around the group cards would nest a Card inside a Card. ` +
+                    `Move the actions onto one group's title, or drop groups for a flat fields grid.`);
+            }
+        }
+    }
+}
+function validateProjectionDetailMetricNavigate(ctx, screenId, screen, field, navigate) {
+    const featureName = ctx.feature.name;
+    if (navigate.screen === undefined && navigate.entity === undefined) {
+        if (navigate.tab !== undefined &&
+            !screen.layout.sections.some((section) => section.id === navigate.tab)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) metric "${field}" ` +
+                `navigates to tab "${navigate.tab}", which is not a section id on this screen. Navigate to an existing section id or remove navigate.tab.`);
+        }
+    }
+    else {
+        // Also runs without `tab`: a typo'd screen/entity or an entity
+        // target without entityId would otherwise render a clickable
+        // metric that silently does nothing.
+        resolveRowActionNavigateTarget(featureName, screenId, "projectionDetail", "metric", navigateActionFromLink(field, navigate), ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
+    }
+}
+function validateProjectionDetailMetric(ctx, screenId, screen, metric) {
+    if (typeof metric.label !== "string" || metric.label.length === 0) {
+        throw new Error(`[Feature ${ctx.feature.name}] Screen "${screenId}" (projectionDetail) metric "${metric.field}" has ` +
+            `no "label" — every metric needs an i18n label key, ` +
+            `there is no fallback to the raw column name.`);
+    }
+    if (metric.navigate !== undefined) {
+        validateProjectionDetailMetricNavigate(ctx, screenId, screen, metric.field, metric.navigate);
+    }
+}
+function validateProjectionDetailStatusTones(featureName, screenId, screen) {
+    for (const [statusValue, tone] of Object.entries(screen.header?.statusTones ?? {})) {
+        if (!isSelectOptionTone(tone)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) header.statusTones["${statusValue}"] ` +
+                `is "${String(tone)}" — expected one of ${SELECT_OPTION_TONES.join(", ")}.`);
+        }
+    }
+}
+function validateProjectionDetailSubtitleParts(ctx, screenId, subtitleHref, parts) {
+    const featureName = ctx.feature.name;
+    if (subtitleHref !== undefined) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) sets header.subtitleHref ` +
+            `together with a multi-part header.subtitle — subtitleHref only works with the string form. Use a single-field subtitle or remove subtitleHref.`);
+    }
+    const seenPartFields = new Set();
+    for (const part of parts) {
+        const partField = typeof part === "string" ? part : part.field;
+        if (seenPartFields.has(partField)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) header.subtitle ` +
+                `lists field "${partField}" twice. List each field once.`);
+        }
+        seenPartFields.add(partField);
+        const navigate = typeof part === "string" ? undefined : part.navigate;
+        if (navigate === undefined)
+            continue;
+        if (navigate.screen === undefined && navigate.entity === undefined) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) header.subtitle part ` +
+                `"${partField}" navigates with neither "screen" nor "entity" — a tab-only navigate has no link target.`);
+        }
+        resolveRowActionNavigateTarget(featureName, screenId, "projectionDetail", "subtitle part", navigateActionFromLink(partField, navigate), ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
+    }
+}
+function validateProjectionDetailSubtitle(ctx, screenId, screen) {
+    const header = screen.header;
+    if (header !== undefined && Array.isArray(header.subtitle)) {
+        validateProjectionDetailSubtitleParts(ctx, screenId, header.subtitleHref, header.subtitle);
+    }
+}
+function validateProjectionDetailExtensionSection(featureName, screenId, section) {
+    // projectionDetail is read-only (no composed form submit) — an
+    // extension that persists through the host's Save button has
+    // nothing to save against. Extensions that persist themselves
+    // (e.g. notes-history NotesSection, via their own dispatcher
+    // writes) are fine.
+    if (section.contributesToFormSubmit === true) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) extension section ` +
+            `"${section.title}" sets contributesToFormSubmit: true, but projectionDetail has no ` +
+            `form submit to contribute to (read-only screen). Omit contributesToFormSubmit and ` +
+            `persist through the extension's own dispatcher writes instead.`);
+    }
+    assertExtensionSectionHasComponent(featureName, screenId, "projectionDetail", section);
+    // The host-derived entity name on projectionDetail is an internal
+    // placeholder (no real entity backs this screen) — a self-
+    // persisting extension needs the real domain entity name declared
+    // explicitly, or it silently reads/writes against the wrong type.
+    if (section.entityName === undefined || section.entityName.trim().length === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) extension section ` +
+            `"${section.title}" has no entityName — projectionDetail has no real entity, so the ` +
+            `extension must declare entityName explicitly (the domain entity it persists against).`);
+    }
+}
+function validateProjectionDetailRelatedList(ctx, screenId, screen, section) {
+    if (screen.layout.mode === "wizard") {
+        throw new Error(`[Feature ${ctx.feature.name}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+            `is kind "relatedList" in a wizard layout — a read-only list is not supported in a ` +
+            `stepped form. Remove mode: "wizard" or drop the relatedList section.`);
+    }
+    validateRelatedListSection({
+        featureName: ctx.feature.name,
+        featureMap: ctx.featureMap,
+        screenId,
+        screenType: "projectionDetail",
+        where: `Screen "${screenId}" (projectionDetail) section "${section.title}" (relatedList)`,
+        section,
+        screens: ctx.feature.screens,
+        allWriteHandlerQns: ctx.allWriteHandlerQns,
+        allScreenQns: ctx.allScreenQns,
+        navTargetShortIds: ctx.navTargetShortIds,
+        screensByShortId: ctx.screensByShortId,
+        detailForScreens: ctx.detailForScreens,
+    });
+}
+function validateProjectionDetailWriteForm(ctx, screenId, screen, section) {
+    const featureName = ctx.feature.name;
+    if (Object.keys(section.fieldDefs).length === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+            `(writeForm) has an empty fieldDefs map — declare at least one field type.`);
+    }
+    if (section.fields.length === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+            `(writeForm) has zero fields — drop the section or add fields to it.`);
+    }
+    // A ref to a fieldDef the form never renders would never resolve.
+    const writeFormFieldNames = new Set(section.fields.map((f) => normalizeEditField(f).field));
+    for (const [defName, fdef] of Object.entries(section.fieldDefs)) {
+        validateFormSelectOptions(featureName, screenId, `projectionDetail section "${section.title}" writeForm`, defName, fdef, writeFormFieldNames);
+        rejectWriteOnlyFormField(featureName, screenId, `projectionDetail section "${section.title}" writeForm`, defName, fdef);
+    }
+    for (const f of section.fields) {
+        const fieldName = normalizeEditField(f).field;
+        if (section.fieldDefs[fieldName] === undefined) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+                `(writeForm) field "${fieldName}" has no entry in fieldDefs — every rendered field needs ` +
+                `a type declared there. Add the field to fieldDefs.`);
+        }
+    }
+    if (screen.layout.mode === "wizard") {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail) section "${section.title}" ` +
+            `is kind "writeForm" in a wizard layout — a self-persisting form is not supported in a ` +
+            `stepped form. Remove mode: "wizard" or drop the writeForm section.`);
+    }
+    assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (projectionDetail) section "${section.title}" (writeForm)`, section.handler, ctx.allWriteHandlerQns);
+}
+function validateProjectionDetailFieldsSection(ctx, screenId, section) {
+    const featureName = ctx.feature.name;
+    validateFieldsXorGroups(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`, section);
+    for (const fieldSpec of sectionFieldSpecs(section)) {
+        const normalizedField = normalizeEditField(fieldSpec);
+        if (normalizedField.refEntity !== undefined) {
+            assertRefTargetRegistered(`[Feature ${featureName}] Screen "${screenId}" (projectionDetail)`, `field "${normalizedField.field}" (refEntity)`, normalizedField.refEntity, featureName, ctx.featureMap);
+        }
+    }
+}
+function validateProjectionDetailSection(ctx, screenId, screen, section) {
+    const featureName = ctx.feature.name;
+    validateRecordSectionActions(ctx, screenId, "projectionDetail", section);
+    if (section.kind === "relatedList" && section.emptyState?.action !== undefined) {
+        const sectionLabel = editSectionLabel(section);
+        validateActionHasIcon(featureName, screenId, "projectionDetail", `section "${sectionLabel}" emptyState action`, section.emptyState.action);
+        validateListActionTargets(listActionContext(ctx, screenId, "projectionDetail", undefined, `Screen "${screenId}" (projectionDetail) section "${sectionLabel}"`), "emptyState action", section.emptyState.action);
+    }
+    if (isExtensionEditSection(section)) {
+        validateProjectionDetailExtensionSection(featureName, screenId, section);
+    }
+    else if (section.kind === "relatedList") {
+        validateProjectionDetailRelatedList(ctx, screenId, screen, section);
+    }
+    else if (isWriteFormEditSection(section)) {
+        validateProjectionDetailWriteForm(ctx, screenId, screen, section);
+    }
+    else {
+        validateProjectionDetailFieldsSection(ctx, screenId, section);
+    }
+}
+// Query-driven like projectionList, but a single row plus layout instead of
+// columns. No entity check is possible: fields resolve against the query
+// response at render time, not against an entity.
+export function validateProjectionDetailScreen(ctx, screenId, screen) {
+    const featureName = ctx.feature.name;
+    rejectMissingQuery(featureName, screenId, "projectionDetail", screen.query);
+    validateProjectionDetailFlags(featureName, screenId, screen);
+    rejectEmptySections(featureName, screenId, "projectionDetail", screen.layout.sections.length);
+    validateProjectionDetailTabs(featureName, screenId, screen);
+    for (const metric of screen.metrics ?? []) {
+        validateProjectionDetailMetric(ctx, screenId, screen, metric);
+    }
+    validateProjectionDetailStatusTones(featureName, screenId, screen);
+    validateProjectionDetailSubtitle(ctx, screenId, screen);
+    for (const section of screen.layout.sections) {
+        validateProjectionDetailSection(ctx, screenId, screen, section);
+    }
+    validatePrimaryActionTarget(featureName, screenId, screen);
+    for (const action of screen.actions ?? []) {
+        validateActionHasIcon(featureName, screenId, "projectionDetail", "action", action);
+        validateRecordHeaderAction(ctx, screenId, "projectionDetail", screen.detailFor, action);
+    }
+}

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

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

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

@@ -0,0 +1,52 @@
+import { normalizeListColumn } from "../screen-helpers.js";
+import { assertWriteHandlerRegistered, resolveRowActionNavigateTarget, validateAtMostOneRowClick, validateDrawerTargetAction, } from "./screens-actions.js";
+import { listActionContext, rejectEmptyColumns, rejectMissingQuery, rejectNonArrayInFilter, validateListColumnRendering, } from "./screens-kind-shared.js";
+import { validateListActionTargets, validateListFacets } from "./screens-lists.js";
+function validateProjectionListRowActions(ctx, screenId, rowActions) {
+    const listContext = listActionContext(ctx, screenId, "projectionList", undefined, `Screen "${screenId}" (projectionList)`);
+    for (const action of rowActions) {
+        validateListActionTargets(listContext, "rowAction", action);
+    }
+    validateAtMostOneRowClick(ctx.feature.name, screenId, "projectionList", rowActions);
+}
+// Plain navigate toolbarActions (no tab) have no boot check yet.
+function validateProjectionListToolbarActions(ctx, screenId, toolbarActions) {
+    const featureName = ctx.feature.name;
+    for (const action of toolbarActions) {
+        if (action.kind === "drawer") {
+            validateDrawerTargetAction(featureName, screenId, "projectionList", "toolbarAction", action, ctx.feature.screens);
+        }
+        else if (action.kind === "writeHandler") {
+            assertWriteHandlerRegistered(featureName, `Screen "${screenId}" (projectionList) toolbarAction "${action.id}"`, action.handler, ctx.allWriteHandlerQns);
+        }
+        if (action.kind === "navigate" && action.tab !== undefined) {
+            resolveRowActionNavigateTarget(featureName, screenId, "projectionList", "toolbarAction", action, ctx.allScreenQns, ctx.navTargetShortIds, ctx.screensByShortId, ctx.detailForScreens);
+        }
+    }
+}
+// Query-driven, no entity, so only query + columns are checked (the column
+// fields cannot be checked against an entity; they resolve against the
+// projection rows at render time).
+export function validateProjectionListScreen(ctx, screenId, screen) {
+    const featureName = ctx.feature.name;
+    rejectMissingQuery(featureName, screenId, "projectionList", screen.query);
+    rejectEmptyColumns(featureName, screenId, "projectionList", screen.columns.length);
+    for (const col of screen.columns) {
+        validateListColumnRendering(ctx, screenId, "projectionList", normalizeListColumn(col));
+    }
+    // Screen filter: field existence can't be checked without an entity (columns
+    // aren't a complete field inventory of the underlying query), so only the
+    // structure is pinned: "in" requires an array.
+    if (screen.filter !== undefined) {
+        rejectNonArrayInFilter(featureName, screenId, "projectionList", screen.filter);
+    }
+    if (screen.facets !== undefined) {
+        validateListFacets(`[Feature ${featureName}] Screen "${screenId}" (projectionList)`, screen.facets, screen.columns, featureName, ctx.featureMap);
+    }
+    if (screen.rowActions !== undefined) {
+        validateProjectionListRowActions(ctx, screenId, screen.rowActions);
+    }
+    if (screen.toolbarActions !== undefined) {
+        validateProjectionListToolbarActions(ctx, screenId, screen.toolbarActions);
+    }
+}

package/dist/engine/boot-validator/screens-kind-secret-mint.d.ts

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

package/dist/engine/boot-validator/screens-kind-secret-mint.js

@@ -0,0 +1,28 @@
+import { validateInlineFormScreen, validateSecretMintConfirm } from "./screens-forms.js";
+function validateSecretMintRevealFields(featureName, screenId, screen) {
+    if (screen.reveal.fields.length === 0) {
+        throw new Error(`[Feature ${featureName}] Screen "${screenId}" (secretMint) has an empty reveal.fields ` +
+            `list — declare at least one field to reveal.`);
+    }
+    const revealFieldNames = new Set();
+    for (const revealField of screen.reveal.fields) {
+        if (typeof revealField.field !== "string" || revealField.field.trim() === "") {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (secretMint) has a reveal.fields entry ` +
+                `with an empty or non-string "field". Set field to a non-empty string.`);
+        }
+        if (revealFieldNames.has(revealField.field)) {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (secretMint) reveal.fields has a ` +
+                `duplicate field "${revealField.field}" — each revealed field must be unique.`);
+        }
+        revealFieldNames.add(revealField.field);
+        if (typeof revealField.label !== "string" || revealField.label.trim() === "") {
+            throw new Error(`[Feature ${featureName}] Screen "${screenId}" (secretMint) reveal.fields entry ` +
+                `"${revealField.field}" has an empty or non-string "label". Set label to a non-empty string.`);
+        }
+    }
+}
+export function validateSecretMintScreen(ctx, screenId, screen) {
+    validateInlineFormScreen(ctx.feature, screenId, screen, "secretMint", ctx.allWriteHandlerQns, ctx, ctx.featureMap);
+    validateSecretMintRevealFields(ctx.feature.name, screenId, screen);
+    validateSecretMintConfirm(ctx.feature, screenId, screen, ctx.allWriteHandlerQns);
+}