@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/validation-tasks.js

@@ -0,0 +1,199 @@
+import { z } from 'zod';
+/**
+ * Validation tasks (ADR-031): an optional `validation.tasks` block that turns
+ * an exploration into a small usability session ("book a class for Friday").
+ * A task succeeds on a route match and/or one restricted data predicate:
+ * an entity, a field, an operator from a closed list and a literal value.
+ * There is no expression language and nothing is ever evaluated as code, so
+ * a blueprint from a link stays data.
+ */
+export const VALIDATION_DATA_OPS = ['eq', 'contains', 'count>='];
+export const VALIDATION_MAX_TASKS = 20;
+const NAME_PATTERN = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
+const FIELD_PATTERN = /^[a-z][A-Za-z0-9]*$/;
+/** An app route as the hash router sees it: no query, fragment, spaces or `..`. */
+const ROUTE_PATTERN = /^\/(?:[A-Za-z0-9._~:@-]+(?:\/[A-Za-z0-9._~:@-]+)*\/?)?$/;
+const entityName = z
+    .string()
+    .regex(NAME_PATTERN, { message: 'entity must be a kebab-case entity name' });
+const fieldName = z
+    .string()
+    .regex(FIELD_PATTERN, { message: 'field must be a lowerCamelCase field name' });
+const Scalar = z.union([z.string().max(200), z.number().finite(), z.boolean(), z.null()]);
+export const ValidationRouteSchema = z.strictObject({
+    path: z
+        .string()
+        .max(200)
+        .regex(ROUTE_PATTERN, {
+        message: 'path must be an app route such as /bookings or /bookings/new',
+    })
+        .refine((path) => !path.split('/').some((segment) => segment === '.' || segment === '..'), {
+        message: 'path must not contain . or .. segments',
+    }),
+    /** `exact` (default) or `prefix`: `/bookings` also matches `/bookings/b-1`. */
+    match: z.enum(['exact', 'prefix']).default('exact'),
+});
+export const ValidationDataSchema = z.discriminatedUnion('op', [
+    /** Some row of `entity` has `field` equal to `value` (an array field: contains it). */
+    z.strictObject({ op: z.literal('eq'), entity: entityName, field: fieldName, value: Scalar }),
+    /** Some row of `entity` has a text `field` containing `value`, ignoring case. */
+    z.strictObject({
+        op: z.literal('contains'),
+        entity: entityName,
+        field: fieldName,
+        value: z.string().min(1).max(200),
+    }),
+    /**
+     * `entity` has at least `value` rows: more than when the task started
+     * (`from: "task-start"`, the default: "create a booking" means +1), or in
+     * total (`from: "zero"`).
+     */
+    z.strictObject({
+        op: z.literal('count>='),
+        entity: entityName,
+        value: z.number().int().min(0).max(100_000),
+        from: z.enum(['task-start', 'zero']).default('task-start'),
+    }),
+]);
+export const ValidationSuccessSchema = z
+    .strictObject({
+    route: ValidationRouteSchema.optional(),
+    data: ValidationDataSchema.optional(),
+})
+    .refine((success) => success.route !== undefined || success.data !== undefined, {
+    message: 'success needs a route, a data predicate, or both',
+});
+export const ValidationTaskSchema = z.strictObject({
+    id: z.string().regex(NAME_PATTERN, { message: 'task id must be lowercase kebab-case' }).max(48),
+    /** What the participant is asked to do, shown verbatim (plain text, never HTML). */
+    prompt: z.string().trim().min(1).max(280),
+    /** Seconds before the task counts as timed out (10 s to 1 h). */
+    timeLimitSeconds: z.number().int().min(10).max(3600).optional(),
+    /** Both parts must hold when both are given. */
+    success: ValidationSuccessSchema,
+});
+export const ValidationSchema = z.strictObject({
+    tasks: z
+        .array(ValidationTaskSchema)
+        .min(1, { message: 'validation needs at least one task' })
+        .max(VALIDATION_MAX_TASKS),
+});
+/** Field kinds `contains` can read: text values, or a string array for `tags`. */
+export const CONTAINS_FIELD_KINDS = new Set([
+    'text',
+    'longText',
+    'email',
+    'url',
+    'phone',
+    'enum',
+    'tags',
+]);
+/** Field kinds `eq` compares to a number, a boolean, or a string. */
+const NUMBER_KINDS = new Set(['number', 'integer', 'money']);
+const BOOLEAN_KINDS = new Set(['boolean']);
+const UNCOMPARABLE_KINDS = new Set(['json', 'file', 'geo']);
+/**
+ * Cross-reference checks the zod shape cannot express: unique task ids,
+ * entities and fields that exist, and values whose type fits the field.
+ */
+export function validationIssues(validation, entities, add) {
+    const seen = new Map();
+    validation.tasks.forEach((task, i) => {
+        const at = ['validation', 'tasks', i];
+        const first = seen.get(task.id);
+        if (first !== undefined)
+            add([...at, 'id'], `duplicate task id "${task.id}" (first at tasks.${first})`);
+        else
+            seen.set(task.id, i);
+        const data = task.success.data;
+        if (!data)
+            return;
+        const dataAt = [...at, 'success', 'data'];
+        const entity = entities.get(data.entity);
+        if (!entity) {
+            add([...dataAt, 'entity'], `unknown entity "${data.entity}"`);
+            return;
+        }
+        if (data.op === 'count>=')
+            return;
+        const field = entity.fields.find((candidate) => candidate.name === data.field);
+        if (!field) {
+            add([...dataAt, 'field'], `entity "${data.entity}" has no field "${data.field}"`);
+            return;
+        }
+        if (data.op === 'contains') {
+            if (!CONTAINS_FIELD_KINDS.has(field.kind))
+                add([...dataAt, 'field'], `contains needs a text, enum or tags field; "${data.field}" is ${field.kind}`);
+            return;
+        }
+        if (UNCOMPARABLE_KINDS.has(field.kind)) {
+            add([...dataAt, 'field'], `eq cannot compare a ${field.kind} field`);
+        }
+        else if (data.value !== null) {
+            const expected = NUMBER_KINDS.has(field.kind)
+                ? 'number'
+                : BOOLEAN_KINDS.has(field.kind)
+                    ? 'boolean'
+                    : 'string';
+            if (typeof data.value !== expected)
+                add([...dataAt, 'value'], `"${data.field}" is ${field.kind}; value must be a ${expected}`);
+        }
+    });
+}
+function normalizeRoute(route) {
+    const path = route.replace(/^#/, '').split(/[?#]/)[0] ?? '';
+    const withSlash = path.startsWith('/') ? path : `/${path}`;
+    return withSlash.length > 1 && withSlash.endsWith('/') ? withSlash.slice(0, -1) : withSlash;
+}
+export function routeMatches(condition, route) {
+    const current = normalizeRoute(route);
+    const wanted = normalizeRoute(condition.path);
+    if (condition.match === 'exact')
+        return current === wanted;
+    return wanted === '/' || current === wanted || current.startsWith(`${wanted}/`);
+}
+function valueContains(value, needle) {
+    const wanted = needle.toLowerCase();
+    if (typeof value === 'string')
+        return value.toLowerCase().includes(wanted);
+    if (Array.isArray(value))
+        return value.some((item) => typeof item === 'string' && item.toLowerCase().includes(wanted));
+    return false;
+}
+function valueEquals(value, expected) {
+    if (Array.isArray(value))
+        return value.some((item) => item === expected);
+    if (expected === null)
+        return value === null || value === undefined;
+    return value === expected;
+}
+export function dataHolds(condition, observation) {
+    const rows = observation.rows[condition.entity] ?? [];
+    switch (condition.op) {
+        case 'eq':
+            return rows.some((row) => valueEquals(row[condition.field], condition.value));
+        case 'contains':
+            return rows.some((row) => valueContains(row[condition.field], condition.value));
+        case 'count>=': {
+            const base = condition.from === 'zero' ? 0 : (observation.baseline?.[condition.entity] ?? 0);
+            return rows.length >= base + condition.value;
+        }
+    }
+}
+/**
+ * Pure and deterministic: the same success condition and observation always
+ * give the same outcome. No clock, no randomness, no code from the blueprint.
+ */
+export function evaluateValidationSuccess(success, observation) {
+    const route = success.route ? routeMatches(success.route, observation.route) : null;
+    const data = success.data ? dataHolds(success.data, observation) : null;
+    return {
+        met: route !== false && data !== false && (route !== null || data !== null),
+        route,
+        data,
+    };
+}
+/** Row counts per entity, to record as the `baseline` when a task starts. */
+export function validationBaseline(rows) {
+    return Object.fromEntries(Object.entries(rows).map(([entity, list]) => [entity, list.length]));
+}

package/dist/validation.d.ts

@@ -0,0 +1,35 @@
+import { z } from 'zod';
+import type { BlueprintEntity, BlueprintField } from './schema.ts';
+/**
+ * Create and update input schemas derived from an entity's fields, for the
+ * zod step of every entity service (use them with `parseInput` from
+ * `@protoyard/core`, which keys errors by field so forms show them inline).
+ *
+ * Inputs are keyed by row property: relation, persona and file fields use
+ * `customerId` / `relatedIds` (see `relationProperty`), everything else its
+ * name. Form strings are coerced: numbers, money (`'12.34'` → 1234 cents;
+ * plain numbers are already cents), booleans (`'on'`, `'true'`, `'1'`),
+ * comma-separated tags, JSON text and geo points (`{ lat, lng }` or `"lat, lng"`,
+ * kept to 5 decimals). Avatar fields accept library ids only (`av-001` …
+ * `av-175`). Blank optional values become `null` (or the field default on
+ * create); blank required values fail with "<Label> is required". Unknown
+ * keys are dropped.
+ */
+export type EntityInput = Record<string, unknown>;
+export interface EntityInputSchemas {
+    /** Required fields must be present and non-blank; absent optional fields get their default or `null`. */
+    create: z.ZodType<EntityInput, unknown>;
+    /** Partial: only keys present in the input are validated and returned. */
+    update: z.ZodType<EntityInput, unknown>;
+}
+/** `dueOn` → `Due on`, unless the field has a `label`. */
+export declare function fieldLabel(field: Pick<BlueprintField, 'name' | 'label'>): string;
+/** Row property that holds a field's value in inputs and rows. */
+export declare function inputProperty(field: BlueprintField): string;
+/**
+ * Major-unit money text to integer cents without floating point:
+ * `'1,234.5'` → 123450, `'-$3'` → -300. Returns null for anything else.
+ */
+export declare function parseMoneyText(text: string): number | null;
+/** Create/update schemas for an entity, built once on first use and cached. */
+export declare function deriveInputSchemas(entity: BlueprintEntity): EntityInputSchemas;

package/dist/validation.js

@@ -0,0 +1,312 @@
+import { isAvatarId } from '@protoyard/scenarios';
+import { z } from 'zod';
+import { relationProperty } from "./storage.js";
+const ok = (value) => ({ ok: true, value });
+const fail = (message) => ({ ok: false, message });
+/** `dueOn` → `Due on`, unless the field has a `label`. */
+export function fieldLabel(field) {
+    if (field.label)
+        return field.label;
+    const words = field.name.replace(/([a-z0-9])([A-Z])/g, '$1 $2').toLowerCase();
+    return words.charAt(0).toUpperCase() + words.slice(1);
+}
+/** Row property that holds a field's value in inputs and rows. */
+export function inputProperty(field) {
+    return relationProperty(field) ?? field.name;
+}
+const isBlank = (value) => value === undefined ||
+    value === null ||
+    (typeof value === 'string' && value.trim() === '') ||
+    (Array.isArray(value) && value.length === 0);
+/**
+ * Major-unit money text to integer cents without floating point:
+ * `'1,234.5'` → 123450, `'-$3'` → -300. Returns null for anything else.
+ */
+export function parseMoneyText(text) {
+    // Bound work before parsing. This is deliberately linear and avoids the
+    // backtracking behavior of the former grouped-number regular expression.
+    if (text.length > 128)
+        return null;
+    let source = text.trim();
+    let sign = 1;
+    if (source.startsWith('-')) {
+        sign = -1;
+        source = source.slice(1).trimStart();
+    }
+    if (source.length > 0 && !/[\d.,\s]/.test(source[0])) {
+        source = source.slice(1).trimStart();
+    }
+    if (!source)
+        return null;
+    const parts = source.split('.');
+    if (parts.length > 2)
+        return null;
+    const whole = parts[0];
+    const fraction = parts[1] ?? '';
+    if (!/^\d+(?:,\d{3})*$/.test(whole) || (parts.length === 2 && !/^\d{1,2}$/.test(fraction))) {
+        return null;
+    }
+    const units = Number(whole.replace(/,/g, ''));
+    const cents = units * 100 + Number(fraction.padEnd(2, '0') || '0');
+    if (!Number.isSafeInteger(cents))
+        return null;
+    return sign * cents;
+}
+const PHONE = /^\+?[\d\s().-]{4,32}$/;
+const ID = /^\S{1,128}$/;
+function toNumber(value) {
+    if (typeof value === 'number')
+        return Number.isFinite(value) ? value : null;
+    if (typeof value === 'string' && /^-?\d+(\.\d+)?(e[+-]?\d+)?$/i.test(value.trim())) {
+        return Number(value.trim());
+    }
+    return null;
+}
+function bounds(label, value, min, max, unit = '') {
+    if (min !== undefined && value < min)
+        return fail(`${label} must be at least ${min}${unit}`);
+    if (max !== undefined && value > max)
+        return fail(`${label} must be at most ${max}${unit}`);
+    return ok(value);
+}
+function ids(label, value, many) {
+    const list = many ? value : [value];
+    if (!Array.isArray(list) || !list.every((id) => typeof id === 'string' && ID.test(id))) {
+        return fail(`Pick ${many ? 'valid' : 'a valid'} ${label.toLowerCase()}`);
+    }
+    return ok(many ? [...new Set(list)] : list[0]);
+}
+/** Validates and coerces one non-blank value for a field. */
+function checkValue(field, value) {
+    const label = fieldLabel(field);
+    switch (field.kind) {
+        case 'text':
+        case 'longText': {
+            if (typeof value !== 'string')
+                return fail(`${label} must be text`);
+            const text = field.kind === 'text' ? value.trim() : value.replace(/\s+$/, '');
+            if (field.minLength !== undefined && text.length < field.minLength) {
+                return fail(`${label} must have at least ${field.minLength} characters`);
+            }
+            if (text.length > field.maxLength) {
+                return fail(`${label} must have at most ${field.maxLength} characters`);
+            }
+            return ok(text);
+        }
+        case 'number':
+        case 'integer': {
+            const n = toNumber(value);
+            if (n === null)
+                return fail(`${label} must be a number`);
+            if (field.kind === 'integer' && !Number.isInteger(n)) {
+                return fail(`${label} must be a whole number`);
+            }
+            return bounds(label, n, field.min, field.max);
+        }
+        case 'money': {
+            const cents = typeof value === 'number' ? (Number.isSafeInteger(value) ? value : null) : null;
+            const parsed = typeof value === 'string' ? parseMoneyText(value) : cents;
+            if (parsed === null)
+                return fail(`${label} must be an amount like 12.34`);
+            const show = (c) => (c / 100).toFixed(2);
+            if (field.min !== undefined && parsed < field.min) {
+                return fail(`${label} must be at least ${show(field.min)} ${field.currency}`);
+            }
+            if (field.max !== undefined && parsed > field.max) {
+                return fail(`${label} must be at most ${show(field.max)} ${field.currency}`);
+            }
+            return ok(parsed);
+        }
+        case 'boolean': {
+            if (typeof value === 'boolean')
+                return ok(value);
+            const text = String(value).trim().toLowerCase();
+            if (['true', 'on', '1', 'yes'].includes(text))
+                return ok(true);
+            if (['false', 'off', '0', 'no'].includes(text))
+                return ok(false);
+            return fail(`${label} must be yes or no`);
+        }
+        case 'date': {
+            const text = typeof value === 'string' ? value.trim() : '';
+            const dateOnly = /^(\d{4})-(\d{2})-(\d{2})$/.test(text);
+            const date = dateOnly
+                ? new Date(`${text}T00:00:00.000Z`)
+                : /^\d{4}-\d{2}-\d{2}T/.test(text)
+                    ? new Date(text)
+                    : null;
+            if (!date ||
+                Number.isNaN(date.getTime()) ||
+                (dateOnly && date.toISOString().slice(0, 10) !== text)) {
+                return fail(`${label} must be a date like 2026-03-02`);
+            }
+            return ok(dateOnly ? text : date.toISOString());
+        }
+        case 'datetime': {
+            const date = value instanceof Date
+                ? value
+                : typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T/.test(value.trim())
+                    ? new Date(value.trim())
+                    : null;
+            if (!date || Number.isNaN(date.getTime())) {
+                return fail(`${label} must be a date and time`);
+            }
+            return ok(date.toISOString());
+        }
+        case 'enum': {
+            const text = typeof value === 'string' ? value.trim() : '';
+            if (!field.values.includes(text)) {
+                const options = field.values.map((v) => field.labels?.[v] ?? v).join(', ');
+                return fail(`${label} must be one of: ${options}`);
+            }
+            return ok(text);
+        }
+        case 'email': {
+            const text = typeof value === 'string' ? value.trim().toLowerCase() : '';
+            return z.email().safeParse(text).success ? ok(text) : fail('Enter a valid email address');
+        }
+        case 'url': {
+            const text = typeof value === 'string' ? value.trim() : '';
+            return z.url({ protocol: /^https?$/ }).safeParse(text).success
+                ? ok(text)
+                : fail('Enter a valid URL starting with https://');
+        }
+        case 'phone': {
+            const text = typeof value === 'string' ? value.trim() : '';
+            const digits = text.replace(/\D/g, '').length;
+            return PHONE.test(text) && digits >= 4 && digits <= 20
+                ? ok(text)
+                : fail('Enter a valid phone number');
+        }
+        case 'tags': {
+            const list = typeof value === 'string' ? value.split(',') : value;
+            if (!Array.isArray(list) || !list.every((tag) => typeof tag === 'string')) {
+                return fail(`${label} must be a list of tags`);
+            }
+            const tags = [...new Set(list.map((tag) => tag.trim()).filter(Boolean))];
+            if (tags.some((tag) => tag.length > 32))
+                return fail('Tags must have at most 32 characters');
+            if (tags.length > field.maxItems) {
+                return fail(`${label} can have at most ${field.maxItems} tags`);
+            }
+            return ok(tags);
+        }
+        case 'relation':
+            return ids(label, value, field.cardinality === 'many');
+        case 'persona':
+            return ids(label, value, false);
+        case 'file':
+            return ids(label, value, field.multiple);
+        case 'json': {
+            if (typeof value !== 'string')
+                return ok(value);
+            try {
+                return ok(JSON.parse(value));
+            }
+            catch {
+                return fail(`${label} must be valid JSON`);
+            }
+        }
+        case 'geo':
+            return checkGeo(label, value);
+        case 'avatar': {
+            const text = typeof value === 'string' ? value.trim() : '';
+            return isAvatarId(text)
+                ? ok(text)
+                : fail(`${label} must be a library face from av-001 to av-175`);
+        }
+    }
+}
+const round5 = (n) => Math.round(n * 1e5) / 1e5;
+/** `{ lat, lng }` (numbers or numeric strings) or `"lat, lng"` → `{ lat, lng }` rounded to 5 decimals. */
+function checkGeo(label, value) {
+    let lat = null;
+    let lng = null;
+    if (typeof value === 'string') {
+        const parts = value.split(',');
+        if (parts.length === 2) {
+            lat = toNumber(parts[0]);
+            lng = toNumber(parts[1]);
+        }
+    }
+    else if (value && typeof value === 'object' && !Array.isArray(value)) {
+        lat = toNumber(value.lat);
+        lng = toNumber(value.lng);
+    }
+    if (lat === null || lng === null)
+        return fail(`${label} needs a latitude and a longitude`);
+    if (lat < -90 || lat > 90)
+        return fail(`${label} latitude must be between -90 and 90`);
+    if (lng < -180 || lng > 180)
+        return fail(`${label} longitude must be between -180 and 180`);
+    return ok({ lat: round5(lat), lng: round5(lng) });
+}
+/** A geo input whose latitude and longitude are both empty counts as blank. */
+function geoBlank(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return false;
+    const { lat, lng } = value;
+    return isBlank(lat) && isBlank(lng);
+}
+/** Value used on create when an optional field is blank or absent. */
+function blankValue(field) {
+    if ('default' in field && field.default !== undefined)
+        return field.default;
+    if (field.kind === 'boolean')
+        return false;
+    if (field.kind === 'tags' ||
+        (field.kind === 'relation' && field.cardinality === 'many') ||
+        (field.kind === 'file' && field.multiple)) {
+        return [];
+    }
+    return null;
+}
+function check(field, input, mode) {
+    const value = field.kind === 'geo' && geoBlank(input) ? null : input;
+    if (!isBlank(value)) {
+        const result = checkValue(field, value);
+        if (result.ok && field.required && isBlank(result.value)) {
+            return fail(`${fieldLabel(field)} is required`);
+        }
+        return result;
+    }
+    // An unchecked checkbox is `false`, never missing.
+    if (field.kind === 'boolean')
+        return ok(mode === 'create' ? blankValue(field) : false);
+    const fallback = blankValue(field);
+    const empty = Array.isArray(fallback) ? [] : null;
+    if (field.required) {
+        if (mode === 'create' && fallback !== null && !Array.isArray(fallback))
+            return ok(fallback);
+        return fail(`${fieldLabel(field)} is required`);
+    }
+    return ok(mode === 'create' ? fallback : empty);
+}
+function build(entity, mode) {
+    const props = entity.fields.map((field) => [inputProperty(field), field]);
+    const shape = Object.fromEntries(props.map(([prop]) => [prop, z.unknown().optional()]));
+    return z.object(shape).transform((input, ctx) => {
+        const output = {};
+        for (const [prop, field] of props) {
+            const value = input[prop];
+            if (mode === 'update' && value === undefined)
+                continue;
+            const result = check(field, value, mode);
+            if (result.ok)
+                output[prop] = result.value;
+            else
+                ctx.issues.push({ code: 'custom', message: result.message, path: [prop], input: value });
+        }
+        return output;
+    });
+}
+const cache = new WeakMap();
+/** Create/update schemas for an entity, built once on first use and cached. */
+export function deriveInputSchemas(entity) {
+    let schemas = cache.get(entity);
+    if (!schemas) {
+        schemas = { create: build(entity, 'create'), update: build(entity, 'update') };
+        cache.set(entity, schemas);
+    }
+    return schemas;
+}

package/dist/variants.d.ts

@@ -0,0 +1,112 @@
+import { type LayoutId } from '@protoyard/core';
+import type { DeckBlueprint, DocBlueprint, PageBlueprint } from './kinds/envelope.ts';
+import { type Blueprint } from './schema.ts';
+/**
+ * Deterministic blueprint variants for `protoyard quick --variants` (ADR-031).
+ * Each variant changes the shell, not the domain: its layout, theme, spacing
+ * density and which entity comes first. Entities, fields, roles and data stay
+ * the same, so variants of one idea compare like for like.
+ *
+ * The theme and layout catalogs come from the caller (the CLI reads them from
+ * @protoyard/themes and @protoyard/core), so this module needs no theme code.
+ * Randomness is a core seeded RNG over the caller's seed plus the blueprint's
+ * canonical JSON: the same input always yields byte-identical variants.
+ */
+/** Built-in theme presets a brand can name (`brand.preset`); other theme ids are library themes. */
+export declare const VARIANT_THEME_PRESETS: readonly ["violet", "ocean", "emerald", "rose", "amber", "monochrome"];
+export declare const VARIANT_DENSITIES: readonly ["compact", "comfortable", "spacious"];
+export type VariantDensity = (typeof VARIANT_DENSITIES)[number];
+/** `brand.density` multipliers (the schema allows 0.75–1.25). */
+export declare const VARIANT_DENSITY_SCALE: Readonly<Record<VariantDensity, number>>;
+export declare const VARIANT_MAX_COUNT = 8;
+export interface VariantAxes {
+    /** Layout ids to choose from; omitted or empty keeps the blueprint's layout. */
+    layouts?: readonly LayoutId[];
+    /** Theme ids: a built-in preset (`ocean`) or a library theme id; omitted keeps the brand. */
+    themes?: readonly string[];
+    /**
+     * Densities to choose from (default: all three). Density needs a preset or
+     * seed brand: a library theme carries its own, so it is not varied there.
+     */
+    densities?: readonly VariantDensity[];
+    /** Vary which entity comes first in navigation and screens (default true). */
+    emphasis?: boolean;
+}
+export interface DeriveVariantsOptions {
+    /** 1 to 8. */
+    count: number;
+    /** Any string; the same seed and blueprint give the same variants. */
+    seed?: string;
+    axes?: VariantAxes;
+}
+export interface VariantChanges {
+    layout?: LayoutId;
+    theme?: string;
+    density?: VariantDensity;
+    /** Entity name moved first. */
+    primaryEntity?: string;
+}
+export interface BlueprintVariant {
+    /** `v1` … `v8`. */
+    id: string;
+    /** What changed, for people: `Rail layout · Ocean theme · Compact · Bookings first`. */
+    label: string;
+    changes: VariantChanges;
+    blueprint: Blueprint;
+}
+/**
+ * Returns `count` distinct, valid variants of `blueprint`, none identical to
+ * the blueprint itself. Throws a RangeError when the axes cannot produce that
+ * many, and the schema's error when a catalog id is invalid (for example an
+ * unknown layout).
+ */
+export declare function deriveVariants(blueprint: Blueprint, options: DeriveVariantsOptions): BlueprintVariant[];
+/** Deck transitions a variant may set (`deck.style.transition`). */
+export declare const VARIANT_DECK_TRANSITIONS: readonly ["none", "fade", "slide", "zoom", "morph"];
+export type VariantDeckTransition = (typeof VARIANT_DECK_TRANSITIONS)[number];
+/**
+ * What a content-kind variant may change. A deck varies its own style
+ * (`deck.style`: theme, transition, density, font pair); a page or doc has no
+ * renderer style yet, so it varies its brand (theme and density), like an
+ * app's shell. Slides, sections, blocks and text never change.
+ */
+export interface KindVariantAxes {
+    /** Theme ids: a built-in preset or a library theme id. */
+    themes?: readonly string[];
+    /** Deck only (default: every transition). */
+    transitions?: readonly VariantDeckTransition[];
+    /** Default: all three. */
+    densities?: readonly VariantDensity[];
+    /** Deck only: font pairing ids (`@protoyard/themes` FONT_CATALOG). */
+    fontPairs?: readonly string[];
+}
+export interface KindVariantChanges {
+    theme?: string;
+    transition?: VariantDeckTransition;
+    density?: VariantDensity;
+    fontPair?: string;
+}
+export interface KindBlueprintVariant<B extends DeckBlueprint | PageBlueprint | DocBlueprint> {
+    /** `v1` … `v8`. */
+    id: string;
+    /** What changed: `Ocean theme · Fade transition · Compact · Humanist fonts`. */
+    label: string;
+    changes: KindVariantChanges;
+    blueprint: B;
+}
+export interface DeriveKindVariantsOptions {
+    /** 1 to 8. */
+    count: number;
+    /** Any string; the same seed and blueprint give the same variants. */
+    seed?: string;
+    axes?: KindVariantAxes;
+}
+/**
+ * `count` distinct variants of a deck, page or doc, none identical to it:
+ * only the style axes change (see `KindVariantAxes`). Deterministic like
+ * `deriveVariants`: the same blueprint, seed and axes give byte-identical
+ * variants. The caller validates the result (`safeParseAnyBlueprint`) when
+ * an axis value may be unknown. Throws a RangeError when the axes cannot
+ * produce that many.
+ */
+export declare function deriveKindVariants<B extends DeckBlueprint | PageBlueprint | DocBlueprint>(blueprint: B, options: DeriveKindVariantsOptions): KindBlueprintVariant<B>[];