@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/schema.js

@@ -0,0 +1,1269 @@
+import { CatalogSchema, LayoutIdSchema } from '@protoyard/core';
+import { GEO_REGIONS } from '@protoyard/scenarios';
+import { z } from 'zod';
+import { ArchetypeSchema } from "./archetypes/schema.js";
+import { canvasScreenIssues, canvasScreenSchema } from "./canvas-screen.js";
+import { BlueprintMotionSchema } from "./motion.js";
+import { sheetScreenIssues, sheetScreenSchema } from "./sheet-screen.js";
+import { ValidationSchema, validationIssues } from "./validation-tasks.js";
+/**
+ * `blueprint.json` — a data-only description of a product (ADR-017):
+ * entities with typed fields and relations, roles with per-entity actions,
+ * and screens. It contains no executable code; every derivation (stores,
+ * inputs, policy, generators, services) reads this validated shape.
+ *
+ * Shapes are strict so typos fail loudly, and cross-references (relation
+ * targets, title fields, owner fields, board columns) are checked after
+ * parsing with path-specific messages.
+ */
+export const BLUEPRINT_SCHEMA_URL = 'https://github.com/DailybotHQ/protoyard/schema/blueprint/v1';
+/** Entity, plural and role names: lowercase kebab-case. */
+const NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+/** Field names become row properties: lowerCamelCase. */
+const FIELD_PATTERN = /^[a-z][a-zA-Z0-9]*$/;
+/** Table names allow `_` only so the reserved `py_` prefix gets a clear message. */
+const TABLE_PATTERN = /^[a-z][a-zA-Z0-9_]*$/;
+const RESERVED_PREFIX = 'py_';
+/** Columns the platform manages on every row; blueprints cannot redeclare them. */
+export const RESERVED_FIELD_NAMES = [
+    'id',
+    'createdAt',
+    'updatedAt',
+    'deletedAt',
+    'deletedBy',
+];
+const name = (what) => z.string().regex(NAME_PATTERN, { message: `${what} must be lowercase kebab-case` });
+const fieldName = z
+    .string()
+    .regex(FIELD_PATTERN, { message: 'field names must be lowerCamelCase' });
+const cents = z.number().int({ message: 'money is integer cents, never a float' });
+const fieldBase = {
+    name: fieldName,
+    label: z.string().min(1).max(60).optional(),
+    description: z.string().max(200).optional(),
+    required: z.boolean().default(false),
+    /** Redacted from audit diffs. */
+    sensitive: z.boolean().default(false),
+    /** Generator hint: a Faker path such as `company.name`. */
+    fake: z
+        .string()
+        .regex(/^[a-z]+\.[a-zA-Z]+$/, { message: 'fake must look like "module.method"' })
+        .optional(),
+};
+const lengths = (max) => ({
+    minLength: z.number().int().nonnegative().optional(),
+    maxLength: z.number().int().positive().max(max).default(max),
+});
+/**
+ * How generated values of a number, integer or money field evolve with the
+ * row's `createdAt`: `growth` and `decline` trend over time, `seasonal` adds
+ * weekly and yearly rhythm. Generation hint only; inputs are not affected.
+ */
+export const FIELD_TRENDS = ['flat', 'growth', 'decline', 'seasonal'];
+const trend = z.enum(FIELD_TRENDS).optional();
+/**
+ * Where generated dates fall, relative to the scenario's now: `past` (since
+ * the organization started, the default), `future` (the next 30 days),
+ * `around` (14 days either side), or `{ from, to }` in days (negative is past).
+ * Past dates never precede the organization; dates after now are allowed and
+ * are therefore left out of the "nothing in the future" integrity check.
+ */
+export const DateWindowSchema = z.union([
+    z.enum(['past', 'future', 'around']),
+    z.strictObject({
+        from: z.number().int().min(-3650).max(3650),
+        to: z.number().int().min(-3650).max(3650),
+    }),
+]);
+/** A window as day offsets from now; `null` from means "since the organization started". */
+export function dateWindowDays(window) {
+    if (window === undefined || window === 'past')
+        return { from: null, to: 0 };
+    if (window === 'future')
+        return { from: 0, to: 30 };
+    if (window === 'around')
+        return { from: -14, to: 14 };
+    return window;
+}
+const field = (kind, extra) => z.strictObject({ ...fieldBase, kind: z.literal(kind), ...extra });
+export const FieldSchema = z.discriminatedUnion('kind', [
+    field('text', {
+        ...lengths(200),
+        default: z.string().optional(),
+    }),
+    field('longText', {
+        ...lengths(10_000),
+        default: z.string().optional(),
+    }),
+    field('number', {
+        min: z.number().optional(),
+        max: z.number().optional(),
+        default: z.number().optional(),
+        trend,
+    }),
+    field('integer', {
+        min: z.number().int().optional(),
+        max: z.number().int().optional(),
+        default: z.number().int().optional(),
+        trend,
+    }),
+    field('money', {
+        currency: z
+            .string()
+            .regex(/^[A-Z]{3}$/, { message: 'currency must be an ISO 4217 code such as "USD"' })
+            .default('USD'),
+        min: cents.optional(),
+        max: cents.optional(),
+        default: cents.optional(),
+        trend,
+    }),
+    field('boolean', { default: z.boolean().optional() }),
+    field('date', { window: DateWindowSchema.optional() }),
+    field('datetime', { window: DateWindowSchema.optional() }),
+    field('enum', {
+        values: z
+            .array(z.string().regex(/^[a-z0-9][a-z0-9_-]*$/, { message: 'enum values are lowercase' }))
+            .min(1, { message: 'enum fields need at least one value' }),
+        labels: z.record(z.string(), z.string().min(1)).optional(),
+        default: z.string().optional(),
+        /** Relative generation weights, one per value (default: equal). */
+        weights: z.array(z.number().nonnegative()).optional(),
+    }),
+    field('email'),
+    field('url'),
+    field('phone'),
+    field('tags', {
+        maxItems: z.number().int().positive().max(64).default(8),
+    }),
+    field('relation', {
+        /** Target entity `name`; the declaring entity owns the stored foreign key. */
+        to: z.string().min(1),
+        /** `required: false` is a nullable one-reference / empty many-collection. */
+        cardinality: z.enum(['one', 'many']).default('one'),
+        /** Delete behavior for rows that reference this field's target. */
+        onDelete: z.enum(['restrict', 'cascade', 'nullify']).default('restrict'),
+    }),
+    /** References a persona in the reserved `py_personas` table. */
+    field('persona'),
+    field('file', {
+        /** MIME types or wildcards (`image/*`). Empty accepts any type. */
+        accept: z.array(z.string().regex(/^[a-z]+\/(?:\*|[a-z0-9.+-]+)$/)).default([]),
+        maxSizeBytes: z
+            .number()
+            .int()
+            .positive()
+            .max(50 * 1024 * 1024)
+            .default(5 * 1024 * 1024),
+        multiple: z.boolean().default(false),
+    }),
+    field('json'),
+    /**
+     * A point stored as `{ lat, lng }` (5 decimals). `region` names a fictional
+     * region from `@protoyard/scenarios` that generated points fall inside.
+     */
+    field('geo', {
+        region: z.enum(Object.keys(GEO_REGIONS)).optional(),
+    }),
+    /**
+     * A face from the avatar library, stored as its id (`av-001` … `av-175`).
+     * Generated rows get distinct seeded faces; never indexed, searched or sorted.
+     */
+    field('avatar'),
+]);
+export const FIELD_KINDS = FieldSchema.options.map((option) => option.shape.kind.value);
+export const EntityFeaturesSchema = z.strictObject({
+    softDelete: z.boolean().default(false),
+    audit: z.boolean().default(false),
+    notifications: z.boolean().default(false),
+    files: z.boolean().default(false),
+    csv: z.boolean().default(false),
+});
+const EntityScreenDefaultsSchema = z
+    .strictObject({
+    /** Standard CRUD views; when present, this is the entity's enabled view set. */
+    views: z.array(z.enum(['list', 'detail', 'form'])).min(1),
+    list: z
+        .strictObject({
+        /** Visible list columns; defaults to the entity's ordinary columns. */
+        columns: z.array(fieldName).optional(),
+    })
+        .optional(),
+    detail: z
+        .strictObject({
+        /** Default related sections and built-in detail tabs. */
+        tabs: z
+            .array(z.union([
+            z.enum(['overview', 'activity', 'files', 'audit']),
+            z.string().regex(/^related:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/, {
+                message: 'tabs are overview, activity, files, audit or related:<entity>',
+            }),
+        ]))
+            .min(1)
+            .optional(),
+    })
+        .optional(),
+})
+    .superRefine((defaults, ctx) => {
+    for (const view of duplicates(defaults.views)) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['views'],
+            message: `duplicate view "${view}"`,
+        });
+    }
+    if (defaults.list && !defaults.views.includes('list')) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['list'],
+            message: 'list defaults require "list" in views',
+        });
+    }
+    if (defaults.detail && !defaults.views.includes('detail')) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['detail'],
+            message: 'detail defaults require "detail" in views',
+        });
+    }
+});
+export const EntitySchema = z.strictObject({
+    /** Singular kebab-case name: `deal`, `support-ticket`. */
+    name: name('entity name'),
+    plural: name('entity plural'),
+    label: z.string().min(1).max(60).optional(),
+    /** Dexie table name; defaults to the plural in lowerCamelCase (see `entityTable`). */
+    table: z.string().regex(TABLE_PATTERN, { message: 'table must be lowerCamelCase' }).optional(),
+    fields: z.array(FieldSchema).min(1, { message: 'an entity needs at least one field' }),
+    /** Field shown as the record's title in lists, pickers and search. */
+    titleField: fieldName,
+    searchable: z.array(fieldName).default([]),
+    /** A `persona` field naming who owns the record (enables `:own` actions). */
+    ownerField: fieldName.optional(),
+    indexes: z.array(fieldName).default([]),
+    defaultSort: z
+        .strictObject({ field: fieldName, direction: z.enum(['asc', 'desc']).default('asc') })
+        .optional(),
+    /** Rows to generate at `normal` density (scaled by density); default 4 for roots, 8 for dependents. */
+    seedCount: z.number().int().min(1).max(500).optional(),
+    /** Optional CRUD defaults; missing keeps the legacy list/detail routes. */
+    screenDefaults: EntityScreenDefaultsSchema.optional(),
+    features: EntityFeaturesSchema.default({
+        softDelete: false,
+        audit: false,
+        notifications: false,
+        files: false,
+        csv: false,
+    }),
+});
+export const ENTITY_ACTIONS = [
+    'read',
+    'create',
+    'update',
+    'update:own',
+    'delete',
+    'delete:own',
+    'import',
+    'export',
+];
+/** Exact capability denials are accepted for the runtime's `-capability` semantics. */
+export const PermissionActionSchema = z.union([
+    z.enum([...ENTITY_ACTIONS, '*']),
+    z.string().regex(/^-[a-z][a-z0-9-]*(?::[a-z][a-z0-9:*-]*)?$/, {
+        message: 'denials must name an exact capability such as "-ticket:delete"',
+    }),
+]);
+export const RoleSchema = z.strictObject({
+    name: name('role name'),
+    label: z.string().min(1).max(40).optional(),
+    description: z.string().max(200).optional(),
+    /** Entity name (or `*` for every entity) → allowed actions (`*` for all). */
+    permissions: z.record(z.string(), z.array(PermissionActionSchema)),
+});
+/**
+ * Lucide icon names (kebab-case) a screen's `nav.icon` may use. An allow-list
+ * keeps generated imports static and tree-shakeable.
+ */
+export const SCREEN_NAV_ICONS = [
+    'activity',
+    'bell',
+    'book-open',
+    'briefcase',
+    'building',
+    'calendar',
+    'calendar-days',
+    'chart-bar',
+    'chart-gantt',
+    'chart-line',
+    'chart-pie',
+    'clock',
+    'cpu',
+    'database',
+    'dollar-sign',
+    'file-text',
+    'folder',
+    'globe',
+    'graduation-cap',
+    'heart-pulse',
+    'house',
+    'inbox',
+    'kanban',
+    'layout-dashboard',
+    'list',
+    'map',
+    'map-pin',
+    'message-square',
+    'package',
+    'receipt',
+    'settings',
+    'shopping-cart',
+    'star',
+    'table',
+    'tag',
+    'ticket',
+    'truck',
+    'users',
+    'wallet',
+    'wrench',
+    'zap',
+];
+/** Sidebar entry options shared by every screen. */
+export const ScreenNavSchema = z.strictObject({
+    label: z.string().min(1).max(40).optional(),
+    icon: z.enum(SCREEN_NAV_ICONS).optional(),
+    /** Lower comes first; screens without an order keep blueprint order after ordered ones. */
+    order: z.number().int().min(0).max(999).optional(),
+    /** Routed but not listed in the sidebar. */
+    hidden: z.boolean().default(false),
+});
+const screenBase = {
+    /** Hash route; defaults are derived from the kind and entity (see `screenPath`). */
+    path: z
+        .string()
+        .regex(/^\/[a-z0-9/:-]*$/, { message: 'path must be a hash route such as "/deals"' })
+        .optional(),
+    title: z.string().min(1).max(60).optional(),
+    nav: ScreenNavSchema.optional(),
+};
+export const AGGREGATES = ['count', 'sum', 'avg', 'min', 'max'];
+export const BUCKET_UNITS = ['day', 'week', 'month'];
+export const CHART_KINDS = ['line', 'area', 'bar', 'donut'];
+export const DETAIL_TABS = ['overview', 'activity', 'files', 'audit'];
+export const SETTINGS_SECTIONS = [
+    'profile',
+    'workspace',
+    'appearance',
+    'notifications',
+    'danger',
+];
+const filterValue = z.union([z.string(), z.number(), z.boolean()]);
+/** Restricts the rows a widget reads: `{ field, op, value }`; `in` takes an array. */
+export const ScreenFilterSchema = z.strictObject({
+    field: fieldName,
+    op: z.enum(['eq', 'in', 'gte', 'lte']),
+    value: z.union([filterValue, z.array(filterValue).min(1)]),
+});
+/** Date bucketing for time series: `{ field: 'createdAt', unit: 'week' }`. */
+export const ScreenBucketSchema = z.strictObject({
+    /** A `date` or `datetime` field, or the managed `createdAt` / `updatedAt`. */
+    field: fieldName,
+    unit: z.enum(BUCKET_UNITS),
+});
+const widgetBase = {
+    label: z.string().min(1).max(60),
+    entity: z.string().min(1),
+    filter: ScreenFilterSchema.optional(),
+    /** Grid columns the widget spans (1–4). */
+    span: z.number().int().min(1).max(4).optional(),
+};
+const measure = {
+    aggregate: z.enum(AGGREGATES).default('count'),
+    /** Required for every aggregate except `count`. */
+    field: fieldName.optional(),
+};
+export const DashboardWidgetSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ ...widgetBase, ...measure, kind: z.literal('kpi') }),
+    z.strictObject({
+        ...widgetBase,
+        ...measure,
+        kind: z.literal('chart'),
+        chart: z.enum(CHART_KINDS),
+        /** An `enum`, `relation`, `persona` or `boolean` field: one series or slice per value. */
+        groupBy: fieldName.optional(),
+        bucket: ScreenBucketSchema.optional(),
+    }),
+    z.strictObject({
+        ...widgetBase,
+        kind: z.literal('list'),
+        limit: z.number().int().min(1).max(20).default(5),
+        sort: z
+            .strictObject({ field: fieldName, direction: z.enum(['asc', 'desc']).default('desc') })
+            .optional(),
+    }),
+    z.strictObject({
+        ...widgetBase,
+        kind: z.literal('board-summary'),
+        /** An `enum` field: one count per value, linking to the board. */
+        groupBy: fieldName,
+    }),
+]);
+/** formatVersion 1 dashboard metric; parsed into a `kpi` widget. */
+const LegacyMetricSchema = z.strictObject({
+    label: z.string().min(1).max(60),
+    entity: z.string().min(1),
+    aggregate: z.enum(['count', 'sum']),
+    /** Required for `sum`: a number, integer or money field. */
+    field: fieldName.optional(),
+});
+const entityScreen = (type, extra) => z.strictObject({
+    ...screenBase,
+    type: z.literal(type),
+    entity: z.string().min(1),
+    ...extra,
+});
+const DetailTabSchema = z.union([
+    z.enum(DETAIL_TABS),
+    z.string().regex(/^related:[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/, {
+        message: 'tabs are overview, activity, files, audit or related:<entity>',
+    }),
+]);
+/**
+ * Screens a generated prototype routes. Additive to formatVersion 1: older
+ * files parse unchanged. Parsing keeps what the file says so issues point at
+ * real paths; consumers normalize with `dashboardWidgets` (legacy `metrics`
+ * become `kpi` widgets) and `screenPath` (default routes).
+ */
+export const ScreenSchema = z.discriminatedUnion('type', [
+    entityScreen('list', { columns: z.array(fieldName).optional() }),
+    entityScreen('detail', {
+        /** Record page tabs; omitted means the edit form only. */
+        tabs: z.array(DetailTabSchema).min(1).optional(),
+    }),
+    entityScreen('form'),
+    entityScreen('board', {
+        /** An `enum` field; each value becomes a column. */
+        groupBy: fieldName,
+        cardFields: z.array(fieldName).max(6).optional(),
+        /** A number, integer or money field summed per column. */
+        sumField: fieldName.optional(),
+    }),
+    entityScreen('calendar', {
+        /** A `date` or `datetime` field. */
+        dateField: fieldName,
+        /** Optional end of the event, same kinds as `dateField`. */
+        endField: fieldName.optional(),
+        /** An `enum` field that colors events. */
+        colorBy: fieldName.optional(),
+        view: z.enum(['month', 'week', 'day', 'agenda']).default('month'),
+    }),
+    entityScreen('timeline', {
+        startField: fieldName,
+        endField: fieldName,
+        /** An `enum`, `relation` or `persona` field: one row per value. */
+        groupBy: fieldName.optional(),
+        zoom: z.enum(['week', 'month', 'quarter']).default('month'),
+    }),
+    entityScreen('map', {
+        /** A `geo` field. */
+        geoField: fieldName,
+        colorBy: fieldName.optional(),
+    }),
+    entityScreen('analytics', {
+        /** A `date` or `datetime` field (or `createdAt`) the explorer buckets by. */
+        dateField: fieldName,
+        measures: z
+            .array(z.strictObject({ label: z.string().min(1).max(60).optional(), ...measure }))
+            .min(1),
+        /** `enum`, `relation`, `persona` or `boolean` fields to break measures down by. */
+        dimensions: z.array(fieldName).default([]),
+    }),
+    z.strictObject({
+        ...screenBase,
+        type: z.literal('dashboard'),
+        /** formatVersion 1 KPI list; read both through `dashboardWidgets`. */
+        metrics: z.array(LegacyMetricSchema).optional(),
+        widgets: z.array(DashboardWidgetSchema).default([]),
+    }),
+    sheetScreenSchema(screenBase, fieldName),
+    canvasScreenSchema(screenBase, fieldName),
+    z.strictObject({
+        ...screenBase,
+        type: z.literal('settings'),
+        sections: z
+            .array(z.enum(SETTINGS_SECTIONS))
+            .min(1)
+            .default(['profile', 'workspace', 'appearance']),
+    }),
+]);
+export const SCREEN_TYPES = [
+    'list',
+    'detail',
+    'form',
+    'board',
+    'calendar',
+    'timeline',
+    'map',
+    'analytics',
+    'dashboard',
+    'settings',
+    'sheet',
+    'canvas',
+];
+/** A dashboard's widgets with its legacy `metrics` first, as `kpi` widgets. */
+export function dashboardWidgets(screen) {
+    const legacy = (screen.metrics ?? []).map((metric) => ({ ...metric, kind: 'kpi' }));
+    return [...legacy, ...screen.widgets];
+}
+/** Route segment each entity-scoped view kind gets below `/<plural>`. */
+const VIEW_SEGMENT = {
+    board: 'board',
+    calendar: 'calendar',
+    timeline: 'timeline',
+    map: 'map',
+    analytics: 'analytics',
+    sheet: 'sheet',
+    canvas: 'canvas',
+};
+/**
+ * The hash route a screen gets: its `path`, or the default for its kind —
+ * `/<plural>`, `/<plural>/:id`, `/<plural>/new`, `/<plural>/<kind>`,
+ * `/dashboard` and `/settings`. Null when the entity is unknown.
+ */
+export function screenPath(screen, entities) {
+    if (screen.path)
+        return screen.path;
+    if (screen.type === 'dashboard')
+        return '/dashboard';
+    if (screen.type === 'settings')
+        return '/settings';
+    const entity = entities.find((e) => e.name === screen.entity);
+    if (!entity)
+        return null;
+    if (screen.type === 'list')
+        return `/${entity.plural}`;
+    if (screen.type === 'detail')
+        return `/${entity.plural}/:id`;
+    if (screen.type === 'form')
+        return `/${entity.plural}/new`;
+    return `/${entity.plural}/${VIEW_SEGMENT[screen.type]}`;
+}
+/** Routes the generated app always owns; screens cannot claim them. */
+export const RESERVED_SCREEN_PATHS = ['/members'];
+const NotificationRuleSchema = z
+    .strictObject({
+    on: z.enum(['create', 'update', 'assign']),
+    entity: name('notification entity'),
+    field: fieldName.optional(),
+    notify: z.string().regex(/^(owner|assignee|role:[a-z][a-z0-9]*(?:-[a-z0-9]+)*)$/),
+    /** Plain text; `{field}` tokens are substituted from the changed entity row. */
+    title: z
+        .string()
+        .min(1)
+        .max(120)
+        .refine((value) => value.length <= 120 && !/<\/?[a-z][^>]*>/i.test(value), {
+        message: 'notification titles must be plain text, not HTML',
+    }),
+})
+    .superRefine((rule, ctx) => {
+    if (rule.on === 'assign' && !rule.field) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['field'],
+            message: 'assign rules need a persona field',
+        });
+    }
+    if (rule.on !== 'assign' && rule.field !== undefined) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['field'],
+            message: 'field is only valid for assign rules',
+        });
+    }
+});
+/**
+ * A previous blueprint kept by `protoyard generate` so every database version
+ * can be rebuilt from data alone: version 1 is the first entry's stores, and
+ * each later entry (and finally the current blueprint) is diffed against the
+ * one before it. `migrateNext` holds the options of that next diff.
+ */
+export const BlueprintHistoryEntrySchema = z.strictObject({
+    schemaVersion: z.number().int().positive(),
+    /** The blueprint as it was (without its own history); validated when versions are derived. */
+    blueprint: z.record(z.string(), z.unknown()),
+    migrateNext: z.strictObject({ allowDrop: z.boolean().optional() }).optional(),
+});
+/** Brand fields a `libraryTheme` replaces; setting any of them alongside it is an error. */
+const LIBRARY_EXCLUSIVE_KEYS = [
+    'id',
+    'seed',
+    'secondary',
+    'preset',
+    'styleProfile',
+    'font',
+    'radius',
+    'density',
+];
+/** Brand hex seed (`#rgb` or `#rrggbb`). */
+const brandHex = z.string().regex(/^#(?:[0-9a-fA-F]{3}|[0-9a-fA-F]{6})$/, {
+    message: 'brand colors must be #rgb or #rrggbb hex',
+});
+/**
+ * Optional product brand for `protoyard generate`. When set, the CLI builds a
+ * WCAG AA theme (seed palette and/or built-in preset + style profile + font)
+ * and wires it as the prototype default. `libraryTheme` instead names one of
+ * the `@protoyard/themes` library looks: the prototype ships it by id, with no
+ * generated theme module. Absent brand → template default theme.
+ */
+export const BlueprintBrandSchema = z
+    .strictObject({
+    /**
+     * Theme id written into the prototype (kebab-case: no leading, trailing or
+     * doubled hyphens, so it always maps to a valid export name). Defaults from name.
+     */
+    id: z
+        .string()
+        .regex(NAME_PATTERN, { message: 'brand id must be lowercase kebab-case' })
+        .max(40)
+        .optional(),
+    /** Display name for the generated theme (max 40; ThemeSchema limit). */
+    name: z.string().min(1).max(40).optional(),
+    /** Brand seed for the palette engine. Required unless `preset` is set. */
+    seed: brandHex.optional(),
+    /** Optional secondary seed for charts and secondary fills. */
+    secondary: brandHex.optional(),
+    /**
+     * Built-in preset id (`violet`, `ocean`, …). Used as the full theme when
+     * `seed` is omitted; ignored for palette when `seed` is present.
+     */
+    preset: z.enum(['violet', 'ocean', 'emerald', 'rose', 'amber', 'monochrome']).optional(),
+    /**
+     * Named style profile: radius, density and elevation knobs applied after
+     * the palette (or preset) is chosen.
+     */
+    styleProfile: z.enum(['soft', 'crisp', 'flat', 'rounded', 'editorial', 'mono']).optional(),
+    /** `FONT_CATALOG` id from `@protoyard/themes`. */
+    font: z
+        .enum([
+        'system',
+        'humanist',
+        'geometric',
+        'grotesk',
+        'editorial',
+        'rounded',
+        'condensed',
+        'mono',
+    ])
+        .optional(),
+    /** CSS radius length (`0.5rem`, `8px`). */
+    radius: z
+        .string()
+        .regex(/^(?:0|\d{1,3}(?:\.\d{1,4})?(?:px|rem|em))$/, {
+        message: 'radius must look like 0.5rem or 8px',
+    })
+        .optional(),
+    /** Spacing multiplier 0.75–1.25. */
+    density: z.number().min(0.75).max(1.25).optional(),
+    /**
+     * Library theme id (`fintech-ledger`, `health-clinic`, … any of the 204
+     * in `ALL_LIBRARY_THEME_IDS`, catalog or expanded) used as-is.
+     * Its palette, fonts, radius and density come from the library (AA-tested
+     * there), so it excludes `id`, `seed`, `secondary`, `preset`,
+     * `styleProfile`, `font`, `radius` and `density`. The id is checked against
+     * the library by `brandLibraryThemeId` (generate, `blueprint validate`), not
+     * here: `parseBlueprint` runs in prototype bundles, which load the library
+     * lazily.
+     */
+    libraryTheme: z
+        .string()
+        .regex(/^[a-z][a-z0-9-]*$/, { message: 'libraryTheme must be a lowercase kebab-case id' })
+        .max(40)
+        .optional(),
+})
+    .superRefine((brand, ctx) => {
+    if (brand.libraryTheme !== undefined) {
+        for (const key of LIBRARY_EXCLUSIVE_KEYS) {
+            if (brand[key] !== undefined) {
+                ctx.addIssue({
+                    code: 'custom',
+                    path: [key],
+                    message: `brand.${key} cannot be combined with libraryTheme (the library theme is used as-is)`,
+                });
+            }
+        }
+        return;
+    }
+    if (!brand.seed && !brand.preset) {
+        ctx.addIssue({
+            code: 'custom',
+            path: ['seed'],
+            message: 'brand needs a seed color, a theme preset or a libraryTheme',
+        });
+    }
+});
+/**
+ * Root keys every blueprint kind shares (ADR-036): identity, catalog metadata
+ * and brand. App-only keys (entities, roles, screens, layout, archetype,
+ * notifications, history, validation) stay on the app shape; content kinds
+ * add their own body key (`deck`, `page`, `doc`) in `kinds/`.
+ */
+export const BLUEPRINT_BASE_SHAPE = {
+    $schema: z.string().optional(),
+    formatVersion: z.literal(1),
+    name: z.string().min(1).max(80),
+    description: z.string().max(280).optional(),
+    /**
+     * Marketplace shelf metadata (optional). Catalog blueprints under
+     * `blueprints/` set this so the registry can index them without a
+     * `protoyard.json`. Same shape as the manifest `catalog` block.
+     */
+    catalog: CatalogSchema.optional(),
+    /** Gallery tags when this file is indexed as a catalog blueprint. */
+    tags: z.array(z.string().min(1).max(32)).max(16).default([]),
+    /** Emoji or short glyph for catalog cards. */
+    icon: z.string().max(8).optional(),
+    /** Coarse category string (falls back to `catalog.category` when indexed). */
+    category: z.string().min(1).max(40).optional(),
+    /** Optional brand → generated on-brand theme for `protoyard generate`. */
+    brand: BlueprintBrandSchema.optional(),
+    /** Optional motion ceiling (`full`, `subtle`, `none`) rendered by `texuli/motion` (motion.ts). */
+    motion: BlueprintMotionSchema.optional(),
+};
+/** @internal Shared app input shape used by the generated kind-union schema. */
+export const BlueprintShape = z.strictObject({
+    ...BLUEPRINT_BASE_SHAPE,
+    /**
+     * The blueprint kind (ADR-036). A missing kind means an app; an explicit
+     * `"app"` is accepted and removed by parsing, so both share one identity.
+     * There is deliberately no default: a default would change every identity.
+     */
+    kind: z.literal('app').optional(),
+    /** Shared app layout selected by generated apps. */
+    layout: z
+        .strictObject({
+        id: LayoutIdSchema,
+        mobile: LayoutIdSchema.optional(),
+    })
+        .optional(),
+    /** Portable kit-backed runtime data; omitted by ordinary CRUD blueprints. */
+    archetype: ArchetypeSchema.optional(),
+    entities: z.array(EntitySchema).min(1, { message: 'a blueprint needs at least one entity' }),
+    roles: z.array(RoleSchema).min(1, { message: 'a blueprint needs at least one role' }),
+    notifications: z.array(NotificationRuleSchema).default([]),
+    screens: z.array(ScreenSchema).default([]),
+    /** Earlier versions, oldest first. Written by `protoyard generate`; do not edit by hand. */
+    history: z.array(BlueprintHistoryEntrySchema).default([]),
+    /** Optional validation tasks for exploration sessions (see validation-tasks.ts). */
+    validation: ValidationSchema.optional(),
+});
+/** `plural` in lowerCamelCase unless `table` is set: `support-tickets` → `supportTickets`. */
+export function entityTable(entity) {
+    return entity.table ?? entity.plural.replace(/-([a-z0-9])/g, (_, c) => c.toUpperCase());
+}
+const TITLE_KINDS = new Set(['text', 'email', 'url', 'phone', 'enum', 'integer']);
+const SUM_KINDS = new Set(['number', 'integer', 'money']);
+/** Kinds that are never indexed, searched or used to sort a list. */
+const UNSORTABLE_KINDS = new Set(['geo', 'avatar']);
+function duplicates(values) {
+    const seen = new Set();
+    const dupes = new Set();
+    for (const value of values)
+        (seen.has(value) ? dupes : seen).add(value);
+    return dupes;
+}
+function checkEntity(entity, at, names, add) {
+    const base = ['entities', at];
+    const fields = new Map(entity.fields.map((f) => [f.name, f]));
+    const table = entityTable(entity);
+    if (table.startsWith(RESERVED_PREFIX)) {
+        add([...base, 'table'], `table "${table}" uses the reserved "${RESERVED_PREFIX}" prefix`);
+    }
+    const dupes = duplicates(entity.fields.map((f) => f.name));
+    entity.fields.forEach((field, i) => {
+        const path = [...base, 'fields', i];
+        if (RESERVED_FIELD_NAMES.includes(field.name)) {
+            add([...path, 'name'], `"${field.name}" is managed by the platform and cannot be declared`);
+        }
+        if (dupes.has(field.name)) {
+            add([...path, 'name'], `duplicate field "${field.name}"`);
+        }
+        if (field.kind === 'relation') {
+            if (!names.has(field.to)) {
+                add([...path, 'to'], `relation "${entity.name}.${field.name}" targets unknown entity "${field.to}"`);
+            }
+            if (field.onDelete === 'nullify' && field.required) {
+                add([...path, 'onDelete'], `required relation "${field.name}" cannot use onDelete "nullify"`);
+            }
+        }
+        if (field.kind === 'enum') {
+            for (const value of duplicates(field.values)) {
+                add([...path, 'values'], `duplicate enum value "${value}"`);
+            }
+            if (field.default !== undefined && !field.values.includes(field.default)) {
+                add([...path, 'default'], `default "${field.default}" is not one of ${field.values.join(', ')}`);
+            }
+            if (field.weights !== undefined) {
+                if (field.weights.length !== field.values.length) {
+                    add([...path, 'weights'], `weights needs one entry per value (${field.values.length})`);
+                }
+                else if (!field.weights.some((w) => w > 0)) {
+                    add([...path, 'weights'], 'weights needs at least one positive entry');
+                }
+            }
+        }
+        if ((field.kind === 'date' || field.kind === 'datetime') && typeof field.window === 'object') {
+            if (field.window.from > field.window.to) {
+                add([...path, 'window'], 'window.from must not be after window.to');
+            }
+        }
+        if ('min' in field && field.min !== undefined && field.max !== undefined) {
+            if (field.min > field.max) {
+                add([...path, 'min'], 'min must not exceed max');
+            }
+        }
+    });
+    const title = fields.get(entity.titleField);
+    if (!title) {
+        add([...base, 'titleField'], `titleField "${entity.titleField}" is not a field of "${entity.name}"`);
+    }
+    else if (!TITLE_KINDS.has(title.kind)) {
+        add([...base, 'titleField'], `titleField "${entity.titleField}" must be a text-like field, not ${title.kind}`);
+    }
+    if (entity.ownerField !== undefined && fields.get(entity.ownerField)?.kind !== 'persona') {
+        add([...base, 'ownerField'], `ownerField "${entity.ownerField}" must be a persona field of "${entity.name}"`);
+    }
+    for (const key of ['searchable', 'indexes']) {
+        entity[key].forEach((ref, i) => {
+            if (!fields.has(ref)) {
+                add([...base, key, i], `unknown field "${ref}"`);
+            }
+            else if (UNSORTABLE_KINDS.has(fields.get(ref)?.kind)) {
+                add([...base, key, i], `${fields.get(ref)?.kind} field "${ref}" cannot be ${key === 'indexes' ? 'indexed' : 'searched'}`);
+            }
+        });
+    }
+    if (entity.defaultSort && !fields.has(entity.defaultSort.field)) {
+        add([...base, 'defaultSort', 'field'], `unknown field "${entity.defaultSort.field}"`);
+    }
+    else if (entity.defaultSort &&
+        UNSORTABLE_KINDS.has(fields.get(entity.defaultSort.field)?.kind)) {
+        add([...base, 'defaultSort', 'field'], `${fields.get(entity.defaultSort.field)?.kind} field "${entity.defaultSort.field}" cannot sort a list`);
+    }
+    if (entity.features.files && !entity.fields.some((f) => f.kind === 'file')) {
+        add([...base, 'features', 'files'], `features.files needs at least one file field on "${entity.name}"`);
+    }
+}
+function checkEntityScreenDefaults(entity, at, entities, add) {
+    const defaults = entity.screenDefaults;
+    if (!defaults)
+        return;
+    const base = ['entities', at, 'screenDefaults'];
+    defaults.list?.columns?.forEach((field, i) => {
+        if (!entity.fields.some((candidate) => candidate.name === field)) {
+            add([...base, 'list', 'columns', i], `unknown field "${field}" on "${entity.name}"`);
+        }
+    });
+    defaults.detail?.tabs?.forEach((tab, i) => {
+        const path = [...base, 'detail', 'tabs', i];
+        if ((tab === 'activity' || tab === 'audit') && !entity.features.audit) {
+            add(path, `the ${tab} tab needs features.audit on "${entity.name}"`);
+        }
+        else if (tab === 'files' && !entity.features.files) {
+            add(path, `the files tab needs features.files on "${entity.name}"`);
+        }
+        else if (tab.startsWith('related:')) {
+            const targetName = tab.slice('related:'.length);
+            const target = entities.get(targetName);
+            if (!target) {
+                add(path, `unknown entity "${targetName}"`);
+            }
+            else if (!target.fields.some((field) => field.kind === 'relation' && field.to === entity.name)) {
+                add(path, `"${target.name}" has no relation field to "${entity.name}"`);
+            }
+        }
+    });
+    for (const tab of duplicates(defaults.detail?.tabs ?? [])) {
+        add([...base, 'detail', 'tabs'], `duplicate tab "${tab}"`);
+    }
+}
+/** Cross-reference checks that a JSON shape cannot express. */
+export function blueprintIssues(blueprint) {
+    const issues = [];
+    const add = (path, message) => {
+        issues.push({ path, message });
+    };
+    const entities = new Map(blueprint.entities.map((e) => [e.name, e]));
+    const names = new Set(entities.keys());
+    for (const [key, values] of [
+        ['name', blueprint.entities.map((e) => e.name)],
+        ['plural', blueprint.entities.map((e) => e.plural)],
+        ['table', blueprint.entities.map(entityTable)],
+    ]) {
+        const dupes = duplicates(values);
+        values.forEach((value, i) => {
+            if (dupes.has(value)) {
+                add(['entities', i, key], `duplicate entity ${key} "${value}"`);
+            }
+        });
+    }
+    blueprint.entities.forEach((entity, i) => {
+        checkEntity(entity, i, names, add);
+        checkEntityScreenDefaults(entity, i, entities, add);
+    });
+    if (blueprint.validation)
+        validationIssues(blueprint.validation, entities, add);
+    if (blueprint.archetype) {
+        for (const [slot, entityName] of Object.entries(blueprint.archetype.entities)) {
+            if (!entities.has(entityName)) {
+                add(['archetype', 'entities', slot], `archetype entity slot "${slot}" references unknown entity "${entityName}"`);
+            }
+        }
+    }
+    blueprint.notifications.forEach((rule, i) => {
+        const path = ['notifications', i];
+        const entity = entities.get(rule.entity);
+        if (!entity) {
+            add([...path, 'entity'], `unknown entity "${rule.entity}"`);
+            return;
+        }
+        const fields = new Map(entity.fields.map((field) => [field.name, field]));
+        if (rule.on === 'assign' && rule.field && fields.get(rule.field)?.kind !== 'persona') {
+            add([...path, 'field'], `assign field "${rule.field}" must be a persona field of "${entity.name}"`);
+        }
+        if (rule.notify === 'owner' &&
+            (!entity.ownerField || fields.get(entity.ownerField)?.kind !== 'persona')) {
+            add([...path, 'notify'], `notify "owner" needs an ownerField on "${entity.name}"`);
+        }
+        if (rule.notify === 'assignee' &&
+            !entity.fields.some((field) => field.name === 'assignee' && field.kind === 'persona')) {
+            add([...path, 'notify'], `notify "assignee" needs an assignee persona field on "${entity.name}"`);
+        }
+        if (rule.notify.startsWith('role:')) {
+            const roleName = rule.notify.slice('role:'.length);
+            if (!blueprint.roles.some((role) => role.name === roleName)) {
+                add([...path, 'notify'], `unknown notification role "${roleName}"`);
+            }
+        }
+        for (const match of rule.title.matchAll(/\{([^{}]+)\}/g)) {
+            const field = fields.get(match[1] ?? '');
+            if (!field) {
+                add([...path, 'title'], `unknown title placeholder "${match[1]}" on "${entity.name}"`);
+            }
+            else if (field.sensitive) {
+                add([...path, 'title'], `sensitive field "${field.name}" cannot be used in a notification title`);
+            }
+        }
+    });
+    const roleDupes = duplicates(blueprint.roles.map((r) => r.name));
+    blueprint.roles.forEach((role, i) => {
+        if (roleDupes.has(role.name)) {
+            add(['roles', i, 'name'], `duplicate role "${role.name}"`);
+        }
+        for (const [target, actions] of Object.entries(role.permissions)) {
+            const path = ['roles', i, 'permissions', target];
+            const entity = entities.get(target);
+            if (target !== '*' && !entity) {
+                add(path, `unknown entity "${target}"`);
+                continue;
+            }
+            const own = actions.filter((a) => a.endsWith(':own'));
+            if (own.length > 0) {
+                const lacking = target === '*'
+                    ? blueprint.entities.filter((e) => !e.ownerField)
+                    : entity && !entity.ownerField
+                        ? [entity]
+                        : [];
+                for (const e of lacking) {
+                    add(path, `"${own.join('", "')}" needs an ownerField on entity "${e.name}"`);
+                }
+            }
+        }
+    });
+    checkScreens(blueprint, add);
+    const explicitViews = new Set(blueprint.screens.flatMap((screen) => 'entity' in screen ? [`${screen.entity}:${screen.type}`] : []));
+    const explicitPaths = new Set([
+        ...blueprint.screens.map((screen) => screenPath(screen, blueprint.entities)),
+        ...(blueprint.archetype?.screens.map((screen) => screen.path) ?? []),
+    ].filter(Boolean));
+    blueprint.entities.forEach((entity, entityIndex) => {
+        entity.screenDefaults?.views.forEach((view, viewIndex) => {
+            if (explicitViews.has(`${entity.name}:${view}`))
+                return;
+            const path = view === 'list'
+                ? `/${entity.plural}`
+                : view === 'detail'
+                    ? `/${entity.plural}/:id`
+                    : `/${entity.plural}/new`;
+            if (explicitPaths.has(path)) {
+                add(['entities', entityIndex, 'screenDefaults', 'views', viewIndex], `path "${path}" is already used by a top-level screen`);
+            }
+        });
+    });
+    return issues;
+}
+/** The managed timestamps are valid date fields for buckets and analytics. */
+const MANAGED_DATE_FIELDS = new Set(['createdAt', 'updatedAt']);
+const DATE_KINDS = new Set(['date', 'datetime']);
+const GROUP_KINDS = new Set(['enum', 'relation', 'persona', 'boolean']);
+const MIN_MAX_KINDS = new Set([...SUM_KINDS, ...DATE_KINDS]);
+/** Field kinds a map screen can plot. */
+const GEO_KINDS = new Set(['geo']);
+/** `a number, integer or money` / `an enum`: the kinds as an English list with its article. */
+function kindList(kinds) {
+    const list = [...kinds];
+    const text = list.length === 1 ? list[0] : `${list.slice(0, -1).join(', ')} or ${list.at(-1)}`;
+    return `${/^[aeiou]/.test(text) ? 'an' : 'a'} ${text}`;
+}
+/** Cross-reference checks for screens, dashboard widgets and routes. */
+function checkScreens(blueprint, add) {
+    const entities = new Map(blueprint.entities.map((e) => [e.name, e]));
+    /** Looks up `name` on `entity` and reports it unless its kind is in `kinds`. */
+    const expectField = (entity, name, kinds, path, what, managedDates = false) => {
+        if (managedDates && MANAGED_DATE_FIELDS.has(name))
+            return undefined;
+        const field = entity.fields.find((f) => f.name === name);
+        if (!field) {
+            add(path, `unknown field "${name}" on "${entity.name}"`);
+        }
+        else if (kinds && !kinds.has(field.kind)) {
+            const managed = managedDates ? ' (or createdAt / updatedAt)' : '';
+            add(path, `${what} "${name}" must be ${kindList(kinds)} field of "${entity.name}"${managed}`);
+        }
+        return field;
+    };
+    const checkMeasure = (entity, measure, path) => {
+        if (measure.aggregate === 'count') {
+            if (measure.field !== undefined)
+                add([...path, 'field'], 'count does not take a field');
+            return;
+        }
+        const kinds = measure.aggregate === 'min' || measure.aggregate === 'max' ? MIN_MAX_KINDS : SUM_KINDS;
+        const field = entity.fields.find((f) => f.name === measure.field);
+        if (!field || !kinds.has(field.kind)) {
+            add([...path, 'field'], `${measure.aggregate} needs ${kindList(kinds)} field`);
+        }
+    };
+    const checkFilter = (entity, filter, path) => {
+        const field = expectField(entity, filter.field, null, [...path, 'field'], 'filter field');
+        if ((filter.op === 'in') !== Array.isArray(filter.value)) {
+            add([...path, 'value'], filter.op === 'in'
+                ? 'op "in" needs an array value'
+                : `op "${filter.op}" needs a single value`);
+        }
+        if (field?.kind === 'enum') {
+            const values = Array.isArray(filter.value) ? filter.value : [filter.value];
+            for (const value of values) {
+                if (!field.values.includes(String(value))) {
+                    add([...path, 'value'], `"${value}" is not one of ${field.values.join(', ')}`);
+                }
+            }
+        }
+    };
+    const seen = new Map();
+    blueprint.screens.forEach((screen, i) => {
+        const path = ['screens', i];
+        const route = screenPath(screen, blueprint.entities);
+        if (route !== null) {
+            if (RESERVED_SCREEN_PATHS.includes(route)) {
+                add([...path, 'path'], `path "${route}" is reserved by the generated app`);
+            }
+            const first = seen.get(route);
+            if (first !== undefined) {
+                add([...path, 'path'], `path "${route}" is already used by screens.${first}`);
+            }
+            else {
+                seen.set(route, i);
+            }
+        }
+        if (screen.type === 'settings') {
+            if (screen.sections.includes('notifications') &&
+                !blueprint.entities.some((e) => e.features.notifications)) {
+                add([...path, 'sections'], 'the notifications section needs an entity with features.notifications');
+            }
+            for (const section of duplicates(screen.sections)) {
+                add([...path, 'sections'], `duplicate section "${section}"`);
+            }
+            return;
+        }
+        if (screen.type === 'dashboard') {
+            const legacy = screen.metrics ?? [];
+            dashboardWidgets(screen).forEach((widget, n) => {
+                const at = n < legacy.length ? [...path, 'metrics', n] : [...path, 'widgets', n - legacy.length];
+                const entity = entities.get(widget.entity);
+                if (!entity) {
+                    add([...at, 'entity'], `unknown entity "${widget.entity}"`);
+                    return;
+                }
+                if (widget.filter)
+                    checkFilter(entity, widget.filter, [...at, 'filter']);
+                if (widget.kind === 'kpi' || widget.kind === 'chart')
+                    checkMeasure(entity, widget, at);
+                if (widget.kind === 'list' && widget.sort) {
+                    expectField(entity, widget.sort.field, null, [...at, 'sort', 'field'], 'sort field');
+                }
+                if (widget.kind === 'board-summary') {
+                    expectField(entity, widget.groupBy, new Set(['enum']), [...at, 'groupBy'], 'groupBy');
+                }
+                if (widget.kind === 'chart') {
+                    if (widget.groupBy !== undefined) {
+                        expectField(entity, widget.groupBy, GROUP_KINDS, [...at, 'groupBy'], 'groupBy');
+                    }
+                    if (widget.bucket) {
+                        expectField(entity, widget.bucket.field, DATE_KINDS, [...at, 'bucket', 'field'], 'bucket field', true);
+                    }
+                    if (widget.chart === 'donut' && (!widget.groupBy || widget.bucket)) {
+                        add([...at, 'chart'], 'a donut chart needs groupBy and no bucket');
+                    }
+                    if ((widget.chart === 'line' || widget.chart === 'area') && !widget.bucket) {
+                        add([...at, 'bucket'], `a ${widget.chart} chart needs a date bucket`);
+                    }
+                    if (widget.chart === 'bar' && !widget.groupBy && !widget.bucket) {
+                        add([...at, 'chart'], 'a bar chart needs groupBy or a date bucket');
+                    }
+                }
+            });
+            return;
+        }
+        const entity = entities.get(screen.entity);
+        if (!entity) {
+            add([...path, 'entity'], `unknown entity "${screen.entity}"`);
+            return;
+        }
+        const fields = new Map(entity.fields.map((f) => [f.name, f]));
+        const enumOnly = new Set(['enum']);
+        switch (screen.type) {
+            case 'list':
+                screen.columns?.forEach((column, j) => {
+                    if (!fields.has(column))
+                        add([...path, 'columns', j], `unknown field "${column}"`);
+                });
+                break;
+            case 'detail':
+                for (const tab of duplicates(screen.tabs ?? [])) {
+                    add([...path, 'tabs'], `duplicate tab "${tab}"`);
+                }
+                screen.tabs?.forEach((tab, j) => {
+                    const at = [...path, 'tabs', j];
+                    if ((tab === 'activity' || tab === 'audit') && !entity.features.audit) {
+                        add(at, `the ${tab} tab needs features.audit on "${entity.name}"`);
+                    }
+                    else if (tab === 'files' && !entity.features.files) {
+                        add(at, `the files tab needs features.files on "${entity.name}"`);
+                    }
+                    else if (tab.startsWith('related:')) {
+                        const other = entities.get(tab.slice('related:'.length));
+                        if (!other) {
+                            add(at, `unknown entity "${tab.slice('related:'.length)}"`);
+                        }
+                        else if (!other.fields.some((f) => f.kind === 'relation' && f.to === entity.name)) {
+                            add(at, `"${other.name}" has no relation field to "${entity.name}"`);
+                        }
+                    }
+                });
+                break;
+            case 'board':
+                if (fields.get(screen.groupBy)?.kind !== 'enum') {
+                    add([...path, 'groupBy'], `groupBy "${screen.groupBy}" must be an enum field of "${entity.name}"`);
+                }
+                screen.cardFields?.forEach((name, j) => {
+                    expectField(entity, name, null, [...path, 'cardFields', j], 'card field');
+                });
+                if (screen.sumField !== undefined) {
+                    expectField(entity, screen.sumField, SUM_KINDS, [...path, 'sumField'], 'sumField');
+                }
+                break;
+            case 'calendar':
+                expectField(entity, screen.dateField, DATE_KINDS, [...path, 'dateField'], 'dateField');
+                if (screen.endField !== undefined) {
+                    expectField(entity, screen.endField, DATE_KINDS, [...path, 'endField'], 'endField');
+                    if (screen.endField === screen.dateField) {
+                        add([...path, 'endField'], 'endField must differ from dateField');
+                    }
+                }
+                if (screen.colorBy !== undefined) {
+                    expectField(entity, screen.colorBy, enumOnly, [...path, 'colorBy'], 'colorBy');
+                }
+                break;
+            case 'timeline':
+                expectField(entity, screen.startField, DATE_KINDS, [...path, 'startField'], 'startField');
+                expectField(entity, screen.endField, DATE_KINDS, [...path, 'endField'], 'endField');
+                if (screen.endField === screen.startField) {
+                    add([...path, 'endField'], 'endField must differ from startField');
+                }
+                if (screen.groupBy !== undefined) {
+                    expectField(entity, screen.groupBy, new Set(['enum', 'relation', 'persona']), [...path, 'groupBy'], 'groupBy');
+                }
+                break;
+            case 'map':
+                expectField(entity, screen.geoField, GEO_KINDS, [...path, 'geoField'], 'geoField');
+                if (screen.colorBy !== undefined) {
+                    expectField(entity, screen.colorBy, enumOnly, [...path, 'colorBy'], 'colorBy');
+                }
+                break;
+            case 'analytics':
+                expectField(entity, screen.dateField, DATE_KINDS, [...path, 'dateField'], 'dateField', true);
+                screen.measures.forEach((measure, j) => {
+                    checkMeasure(entity, measure, [...path, 'measures', j]);
+                });
+                screen.dimensions.forEach((name, j) => {
+                    expectField(entity, name, GROUP_KINDS, [...path, 'dimensions', j], 'dimension');
+                });
+                break;
+            case 'form':
+                break;
+            case 'sheet':
+                sheetScreenIssues(entity, screen, path, add);
+                break;
+            case 'canvas':
+                canvasScreenIssues(entity, screen, path, add);
+                break;
+        }
+    });
+    blueprint.archetype?.screens.forEach((screen, i) => {
+        const path = ['archetype', 'screens', i, 'path'];
+        if (RESERVED_SCREEN_PATHS.includes(screen.path)) {
+            add(path, `path "${screen.path}" is reserved by the generated app`);
+        }
+        const first = seen.get(screen.path);
+        if (first !== undefined) {
+            add(path, `path "${screen.path}" is already used by screens.${first}`);
+        }
+        else {
+            seen.set(screen.path, blueprint.screens.length + i);
+        }
+    });
+}
+/**
+ * The parsed app blueprint: an explicit `kind: "app"` is dropped (a missing
+ * kind means app), then entity CRUD defaults are materialized.
+ */
+function withoutAppKind(blueprint) {
+    const { kind: _kind, ...app } = withEntityScreenDefaults(blueprint);
+    return app;
+}
+/** Materializes entity CRUD defaults into ordinary screens for every consumer. */
+function withEntityScreenDefaults(blueprint) {
+    const screens = [...blueprint.screens];
+    const explicitViews = new Set(screens.flatMap((screen) => ('entity' in screen ? [`${screen.entity}:${screen.type}`] : [])));
+    for (const entity of blueprint.entities) {
+        const defaults = entity.screenDefaults;
+        if (!defaults)
+            continue;
+        for (const view of defaults.views) {
+            if (explicitViews.has(`${entity.name}:${view}`))
+                continue;
+            const config = view === 'list' ? defaults.list : view === 'detail' ? defaults.detail : undefined;
+            screens.push(ScreenSchema.parse({ type: view, entity: entity.name, ...config }));
+        }
+    }
+    return { ...blueprint, screens };
+}
+export const BlueprintSchema = BlueprintShape.superRefine((blueprint, ctx) => {
+    for (const issue of blueprintIssues(blueprint)) {
+        ctx.addIssue({ code: 'custom', path: issue.path, message: issue.message });
+    }
+}).transform(withoutAppKind);
+export function parseBlueprint(input) {
+    return BlueprintSchema.parse(input);
+}
+export function safeParseBlueprint(input) {
+    return BlueprintSchema.safeParse(input);
+}