@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/authoring/select-deck-layouts.js

@@ -0,0 +1,213 @@
+/**
+ * Deterministic deck layout selection from slide roles, pacing, block contents
+ * and optional author overrides. Pure: no Math.random, no Date.now.
+ *
+ * Uses the read-only `@protoyard/decks/layouts` catalog (AUTHORING + DECKS).
+ */
+import { DECK_LAYOUT_BY_ID, DECK_LAYOUTS, } from '@protoyard/decks/layouts';
+/** Preferred catalog layouts for each outline role (ordered). */
+const ROLE_LAYOUTS = Object.freeze({
+    title: ['title-hero'],
+    agenda: ['section-divider', 'two-column-split', 'process-steps'],
+    close: ['closing-cta', 'quote'],
+    ask: ['closing-cta'],
+    section: ['section-divider'],
+    hook: ['title-hero', 'big-stat', 'quote'],
+    problem: ['two-column-split', 'image-left', 'free'],
+    solution: ['two-column-split', 'three-column-cards', 'process-steps'],
+    'business-model': ['two-column-split', 'three-column-cards'],
+    'why-now': ['big-stat', 'two-column-split'],
+    pricing: ['comparison-table', 'three-column-cards'],
+    metrics: ['big-stat', 'chart'],
+    chart: ['chart', 'big-stat'],
+    comparison: ['comparison-table'],
+    steps: ['process-steps'],
+    process: ['process-steps'],
+    progress: ['process-steps', 'timeline'],
+    timeline: ['timeline'],
+    roadmap: ['timeline', 'process-steps'],
+    plan: ['timeline', 'process-steps', 'two-column-split'],
+    team: ['team-avatars'],
+    quote: ['quote'],
+    story: ['process-steps', 'timeline', 'free'],
+    demo: ['image-centered', 'video-centered', 'image-left'],
+    code: ['code-with-callout'],
+    concept: ['two-column-split', 'three-column-cards', 'free'],
+    context: ['two-column-split', 'free'],
+    findings: ['three-column-cards', 'two-column-split', 'chart'],
+    method: ['process-steps', 'two-column-split'],
+    objectives: ['three-column-cards', 'process-steps'],
+    wins: ['three-column-cards', 'big-stat'],
+    misses: ['two-column-split', 'free'],
+    risks: ['two-column-split', 'free'],
+    recommendations: ['process-steps', 'three-column-cards'],
+    resources: ['three-column-cards', 'free'],
+    recap: ['process-steps', 'section-divider'],
+    homework: ['process-steps', 'free'],
+    poll: ['free'],
+    quiz: ['free'],
+    audience: ['team-avatars', 'free'],
+    activity: ['process-steps', 'free'],
+    example: ['image-right', 'two-column-split', 'free'],
+});
+/** Block types that strongly suggest a layout. */
+const BLOCK_LAYOUTS = Object.freeze({
+    chart: ['chart'],
+    table: ['comparison-table'],
+    comparison: ['comparison-table'],
+    steps: ['process-steps'],
+    timeline: ['timeline'],
+    people: ['team-avatars'],
+    quote: ['quote'],
+    cards: ['three-column-cards'],
+    code: ['code-with-callout'],
+    image: ['image-centered', 'image-left', 'image-right'],
+    video: ['video-centered', 'video-left'],
+    cta: ['closing-cta'],
+    stat: ['big-stat'],
+});
+const FALLBACK_BY_PACING = Object.freeze({
+    punch: ['big-stat', 'section-divider', 'quote', 'title-hero', 'free'],
+    idea: ['two-column-split', 'three-column-cards', 'process-steps', 'free'],
+    diagram: ['process-steps', 'timeline', 'chart', 'comparison-table', 'free'],
+    story: ['timeline', 'process-steps', 'quote', 'image-full-bleed', 'free'],
+});
+/**
+ * Select one catalog layout per slide. Deterministic for the same inputs.
+ * Avoids three identical layouts in a row when another compatible layout fits.
+ */
+export function selectDeckLayouts(slides, options = {}) {
+    const catalog = options.catalog ?? DECK_LAYOUTS;
+    const byId = new Map(catalog.map((entry) => [entry.id, entry]));
+    const aspect = options.aspect ?? '16:9';
+    const previous = [];
+    const out = [];
+    for (const slide of slides) {
+        const override = slide.layout?.trim();
+        if (override && byId.has(override)) {
+            out.push({
+                id: slide.id,
+                layout: override,
+                rationale: `Author override: layout "${override}".`,
+                override: true,
+            });
+            previous.push(override);
+            continue;
+        }
+        const candidates = rankCandidates(slide, byId, aspect);
+        let chosen = candidates[0] ?? 'free';
+        let avoidedRepeat = false;
+        // Avoid three identical layouts in a row when an alternative remains.
+        if (previous.length >= 2 &&
+            previous[previous.length - 1] === previous[previous.length - 2] &&
+            previous[previous.length - 1] === chosen) {
+            const alt = candidates.find((id) => id !== chosen);
+            if (alt) {
+                chosen = alt;
+                avoidedRepeat = true;
+            }
+        }
+        const entry = byId.get(chosen);
+        const reasons = [
+            `Role "${slide.role}" with pacing "${slide.pacing}"`,
+            slide.blockTypes && slide.blockTypes.length > 0
+                ? `blocks [${[...new Set(slide.blockTypes)].sort().join(', ')}]`
+                : null,
+            entry ? `fits catalog "${entry.id}" (${entry.label})` : null,
+            avoidedRepeat ? 'avoided a third identical layout in a row' : null,
+            aspect !== '16:9' ? `aspect ${aspect}` : null,
+        ].filter(Boolean);
+        out.push({
+            id: slide.id,
+            layout: chosen,
+            rationale: `${reasons.join('; ')}.`,
+            override: false,
+        });
+        previous.push(chosen);
+    }
+    return out;
+}
+/**
+ * Minimal valid catalog `props` for a layout, seeded from the slide title.
+ * Used when rewriting free outline slides to catalog slides.
+ */
+export function propsForSelectedLayout(layoutId, slide) {
+    const entry = DECK_LAYOUT_BY_ID[layoutId] ?? getFromList(layoutId);
+    const sample = entry && typeof entry.sample === 'object' && entry.sample !== null
+        ? structuredClone(entry.sample)
+        : {};
+    if (layoutId === 'free' || entry?.id === 'free') {
+        return { blocks: [] };
+    }
+    const title = slide.title?.trim();
+    if (title) {
+        if ('title' in sample)
+            sample.title = title;
+        else if (layoutId === 'big-stat' && 'label' in sample)
+            sample.label = title;
+    }
+    return sample;
+}
+function getFromList(id) {
+    return DECK_LAYOUTS.find((entry) => entry.id === id);
+}
+function rankCandidates(slide, byId, aspect) {
+    const pacing = normalizePacing(slide.pacing);
+    const roleKey = slide.role.trim().toLowerCase();
+    const fromRole = ROLE_LAYOUTS[roleKey] ?? [];
+    const fromBlocks = blockHints(slide.blockTypes);
+    const fromPacing = FALLBACK_BY_PACING[pacing] ?? FALLBACK_BY_PACING.idea ?? ['free'];
+    const ordered = unique([...fromBlocks, ...fromRole, ...fromPacing, 'free']);
+    const filtered = ordered.filter((id) => {
+        const entry = byId.get(id);
+        if (!entry)
+            return id === 'free';
+        if (entry.pacing.length > 0 && !entry.pacing.includes(pacing)) {
+            // Still allow if role strongly requested it
+            if (fromRole.includes(id) || fromBlocks.includes(id))
+                return true;
+            return false;
+        }
+        return true;
+    });
+    // Portrait decks: prefer centered/free over wide multi-column when tied.
+    if (aspect === '9:16' || aspect === '1:1') {
+        filtered.sort((a, b) => portraitScore(b) - portraitScore(a));
+    }
+    return filtered.length > 0 ? filtered : ['free'];
+}
+function blockHints(types) {
+    if (!types || types.length === 0)
+        return [];
+    const out = [];
+    for (const type of types) {
+        const layouts = BLOCK_LAYOUTS[type];
+        if (layouts)
+            out.push(...layouts);
+    }
+    return out;
+}
+function normalizePacing(value) {
+    const v = value.trim().toLowerCase();
+    if (v === 'punch' || v === 'idea' || v === 'diagram' || v === 'story')
+        return v;
+    return 'idea';
+}
+function unique(ids) {
+    const seen = new Set();
+    const out = [];
+    for (const id of ids) {
+        if (seen.has(id))
+            continue;
+        seen.add(id);
+        out.push(id);
+    }
+    return out;
+}
+function portraitScore(layoutId) {
+    if (layoutId === 'free' || layoutId.includes('centered') || layoutId === 'title-hero')
+        return 2;
+    if (layoutId === 'section-divider' || layoutId === 'quote' || layoutId === 'big-stat')
+        return 1;
+    return 0;
+}

package/dist/authoring-apis.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The lazy authoring chunk behind `loadAuthoringApis()` (see `index.ts`).
+ *
+ * Keep this a separate module: a dynamic `import()` of modules that the root
+ * entry also re-exports statically would pull them into the importer's first
+ * chunk, while a dynamic import of this file keeps them, and the deck layout
+ * catalog, in a chunk of their own.
+ */
+export { DECK_LAYOUTS as deckLayouts, describeLayouts as describeDeckLayouts, getDeckLayout, } from '@protoyard/decks/layouts';
+export { lintDeckAssets, lintDeckContent, lintDeckStructure } from './authoring/deck-lint.ts';
+export { propsForSelectedLayout, selectDeckLayouts } from './authoring/index.ts';
+export { validateBlueprintForAuthoring } from './authoring-validation.ts';
+export { blueprintFromBrief, buildDocOutline, buildPageOutline, detectBriefKind, synthesizeContentFromBrief, synthesizeDeckOutline, } from './brief/index.ts';

package/dist/authoring-apis.js

@@ -0,0 +1,13 @@
+/**
+ * The lazy authoring chunk behind `loadAuthoringApis()` (see `index.ts`).
+ *
+ * Keep this a separate module: a dynamic `import()` of modules that the root
+ * entry also re-exports statically would pull them into the importer's first
+ * chunk, while a dynamic import of this file keeps them, and the deck layout
+ * catalog, in a chunk of their own.
+ */
+export { DECK_LAYOUTS as deckLayouts, describeLayouts as describeDeckLayouts, getDeckLayout, } from '@protoyard/decks/layouts';
+export { lintDeckAssets, lintDeckContent, lintDeckStructure } from "./authoring/deck-lint.js";
+export { propsForSelectedLayout, selectDeckLayouts } from "./authoring/index.js";
+export { validateBlueprintForAuthoring } from "./authoring-validation.js";
+export { blueprintFromBrief, buildDocOutline, buildPageOutline, detectBriefKind, synthesizeContentFromBrief, synthesizeDeckOutline, } from "./brief/index.js";

package/dist/authoring-validation.d.ts

@@ -0,0 +1,65 @@
+import { type BlueprintKind, type ContentKind } from './kinds/kind.ts';
+/** A JSON path segment in a blueprint validation diagnostic. */
+export type BlueprintDiagnosticPath = string | number;
+/** One stable, actionable blueprint validation diagnostic. */
+export type BlueprintAuthoringDiagnostic = {
+    /** Stable machine-readable category, independent of the Zod error wording. */
+    code: string;
+    /** Original JSON path segments. */
+    path: BlueprintDiagnosticPath[];
+    /** JSONPath-style rendering of `path`, with keys quoted for unambiguous use. */
+    jsonPath: string;
+    /** Concise schema or cross-reference explanation. */
+    message: string;
+    /** A next step an author can take to resolve this diagnostic. */
+    hint: string;
+};
+/** Full blueprint validity and diagnostics. `valid` uses the complete Zod schema. */
+export type BlueprintAuthoringValidation = {
+    valid: boolean;
+    /**
+     * The kind the input was validated as: `app` when `kind` is missing (the
+     * legacy compatibility rule), `null` when `kind` itself is unusable.
+     */
+    kind: BlueprintKind | null;
+    diagnostics: BlueprintAuthoringDiagnostic[];
+};
+/**
+ * Validate untrusted author input of any kind and return path-addressed repair
+ * guidance. Each kind runs through the shared kind union
+ * (`safeParseAnyBlueprint`): an app (with no `kind`, or `kind: "app"`) through
+ * the full app schema, including cross-reference checks, and a deck, page or
+ * doc through its strict envelope and body schema. A JSON Schema shape check
+ * alone is not enough to establish `valid`.
+ *
+ * Diagnostics never fetch network assets and never render markdown as HTML.
+ * Block and media failures map to stable codes (unknown block type, chart
+ * specs, alt text, URL schemes, step/fragment targets) with the original path.
+ */
+export declare function validateBlueprintForAuthoring(input: unknown): Promise<BlueprintAuthoringValidation>;
+/**
+ * Map path-addressed block issues (from `@protoyard/blocks` `safeParseBlock` /
+ * `safeParseBlocks` / `parseUntrustedBlocks`) into authoring diagnostics.
+ * `pathPrefix` is prepended (for example `["deck","slides",0,"blocks"]`) so
+ * the JSON path stays relative to the blueprint root. Does not mutate or
+ * auto-repair the input.
+ */
+export declare function diagnosticsFromBlockIssues(issues: readonly {
+    path: readonly (string | number)[];
+    message: string;
+}[], pathPrefix?: readonly BlueprintDiagnosticPath[]): BlueprintAuthoringDiagnostic[];
+/** Turn one Zod issue into a stable authoring diagnostic. */
+export declare function issueToDiagnostic(issue: {
+    code: string;
+    message: string;
+    path: readonly PropertyKey[];
+    keys?: readonly PropertyKey[];
+}, contentKind?: ContentKind | null): BlueprintAuthoringDiagnostic;
+export declare function toJsonPath(path: readonly BlueprintDiagnosticPath[]): string;
+/**
+ * Stable codes for authoring tools. Block/media messages are matched before
+ * generic Zod codes so chart, alt and scheme failures stay specific.
+ */
+export declare function diagnosticCode(zodCode: string, message: string, path?: readonly BlueprintDiagnosticPath[]): string;
+/** Hints for block, media and generic blueprint failures. Never auto-repairs. */
+export declare function blockOrAssetHint(code: string, message: string): string;

package/dist/authoring-validation.js

@@ -0,0 +1,267 @@
+import { safeParseAnyBlueprint } from "./kinds/envelope.js";
+import { BLUEPRINT_KINDS, detectBlueprintKind, isContentKind, } from "./kinds/kind.js";
+import { BLUEPRINT_BASE_SHAPE } from "./schema.js";
+/**
+ * Validate untrusted author input of any kind and return path-addressed repair
+ * guidance. Each kind runs through the shared kind union
+ * (`safeParseAnyBlueprint`): an app (with no `kind`, or `kind: "app"`) through
+ * the full app schema, including cross-reference checks, and a deck, page or
+ * doc through its strict envelope and body schema. A JSON Schema shape check
+ * alone is not enough to establish `valid`.
+ *
+ * Diagnostics never fetch network assets and never render markdown as HTML.
+ * Block and media failures map to stable codes (unknown block type, chart
+ * specs, alt text, URL schemes, step/fragment targets) with the original path.
+ */
+export async function validateBlueprintForAuthoring(input) {
+    const detected = detectBlueprintKind(input);
+    if (!detected.ok) {
+        return {
+            valid: false,
+            kind: null,
+            diagnostics: [kindDiagnostic(input, detected.message, detected.fix)],
+        };
+    }
+    const kind = detected.kind;
+    const result = await safeParseAnyBlueprint(input);
+    if (result.success)
+        return { valid: true, kind, diagnostics: [] };
+    return {
+        valid: false,
+        kind,
+        diagnostics: result.error.issues.map((issue) => issueToDiagnostic(issue, isContentKind(kind) ? kind : null)),
+    };
+}
+/**
+ * Map path-addressed block issues (from `@protoyard/blocks` `safeParseBlock` /
+ * `safeParseBlocks` / `parseUntrustedBlocks`) into authoring diagnostics.
+ * `pathPrefix` is prepended (for example `["deck","slides",0,"blocks"]`) so
+ * the JSON path stays relative to the blueprint root. Does not mutate or
+ * auto-repair the input.
+ */
+export function diagnosticsFromBlockIssues(issues, pathPrefix = []) {
+    return issues.map((issue) => {
+        const path = [...pathPrefix, ...issue.path];
+        const code = diagnosticCode('custom', issue.message, path);
+        return {
+            code,
+            path,
+            jsonPath: toJsonPath(path),
+            message: issue.message,
+            hint: blockOrAssetHint(code, issue.message),
+        };
+    });
+}
+/** Turn one Zod issue into a stable authoring diagnostic. */
+export function issueToDiagnostic(issue, contentKind = null) {
+    const path = [...issue.path];
+    const message = issue.message;
+    if (contentKind && issue.code === 'custom' && path.length === 1 && path[0] === 'kind') {
+        return {
+            code: 'kind-unavailable',
+            path,
+            jsonPath: toJsonPath(path),
+            message,
+            hint: `Update Protoyard to a build that ships the ${contentKind} engine, or author an app blueprint instead.`,
+        };
+    }
+    const code = diagnosticCode(issue.code, message, path);
+    return {
+        code,
+        path,
+        jsonPath: toJsonPath(path),
+        message,
+        hint: contentKind
+            ? contentHint(contentKind, code, issue, path, message)
+            : blockOrAssetHint(code, message),
+    };
+}
+/** `kind` is not a string, or names a kind this version does not know. */
+function kindDiagnostic(input, message, fix) {
+    const kind = input.kind;
+    return {
+        code: typeof kind === 'string' ? 'unknown-kind' : 'invalid-kind',
+        path: ['kind'],
+        jsonPath: toJsonPath(['kind']),
+        message,
+        hint: fix,
+    };
+}
+const SHARED_KEYS = Object.keys(BLUEPRINT_BASE_SHAPE);
+function contentHint(kind, code, issue, path, message) {
+    if (code === 'unknown-key' && path.length === 0) {
+        const others = (issue.keys ?? []).filter((key) => BLUEPRINT_KINDS.includes(key));
+        if (others.length) {
+            return `A ${kind} blueprint has exactly one body, "${kind}". Remove ${others.map((key) => `"${String(key)}"`).join(', ')}, or change "kind" to match it.`;
+        }
+        return `A ${kind} blueprint accepts only ${[...SHARED_KEYS, 'kind', kind].join(', ')}. App keys such as entities, roles and screens belong to app blueprints: remove them, or drop "kind" to author an app.`;
+    }
+    if (code === 'invalid-type' && path.length === 1 && path[0] === kind) {
+        return `Add the "${kind}" body: an object with the ${kind}'s content.`;
+    }
+    return blockOrAssetHint(code, message);
+}
+export function toJsonPath(path) {
+    let result = '$';
+    for (const segment of path) {
+        result += typeof segment === 'number' ? `[${segment}]` : `[${JSON.stringify(segment)}]`;
+    }
+    return result;
+}
+/**
+ * Stable codes for authoring tools. Block/media messages are matched before
+ * generic Zod codes so chart, alt and scheme failures stay specific.
+ */
+export function diagnosticCode(zodCode, message, path = []) {
+    const lower = message.toLowerCase();
+    const last = path.length > 0 ? path[path.length - 1] : undefined;
+    if (lower.includes('invalid discriminator') ||
+        (last === 'type' &&
+            (lower.includes('expected') ||
+                lower.includes('invalid option') ||
+                lower.includes('invalid input')))) {
+        return 'unknown-block-type';
+    }
+    if (lower.includes('describe the image in alt') ||
+        lower.includes('mark it decorative') ||
+        (last === 'alt' && lower.includes('alt'))) {
+        return 'missing-alt-text';
+    }
+    if (lower.includes('decorative image has no alt')) {
+        return 'invalid-alt-text';
+    }
+    if (lower.includes('http(s), mailto') ||
+        lower.includes('https: or mailto:') ||
+        lower.includes('no svg or remote') ||
+        lower.includes('no remote urls') ||
+        lower.includes('relative image path') ||
+        lower.includes('relative video path') ||
+        lower.includes('use avatar:av-') ||
+        lower.includes('base64 data uri') ||
+        lower.includes('javascript:') ||
+        lower.includes('protocol-relative')) {
+        return 'unsupported-url-scheme';
+    }
+    if (lower.includes('needs one value per label') ||
+        lower.includes('chart takes exactly one series') ||
+        lower.includes('chart needs non-negative') ||
+        lower.includes('chart data is not valid json') ||
+        lower.includes('chart data is too large') ||
+        lower.includes('invalid chart') ||
+        (path.includes('spec') &&
+            (lower.includes('series') || lower.includes('label') || lower.includes('kind')))) {
+        return 'invalid-chart-spec';
+    }
+    if (lower.includes('duplicate block id') || lower.includes('first used at')) {
+        return 'duplicate-block-id';
+    }
+    if (lower.includes('no such step') ||
+        lower.includes('unknown step') ||
+        lower.includes('invalid step') ||
+        lower.includes('fragment target') ||
+        lower.includes('unknown fragment') ||
+        lower.includes('unknown block id') ||
+        lower.includes('no such block') ||
+        (lower.includes('fragment') && lower.includes('target')) ||
+        (last === 'step' &&
+            (lower.includes('integer') || lower.includes('max') || lower.includes('min')))) {
+        return 'invalid-step-or-fragment-target';
+    }
+    if (message.startsWith('unknown entity') || message.includes('unknown entity "')) {
+        return 'unknown-entity';
+    }
+    if (message.startsWith('unknown field') ||
+        message.includes('unknown field "') ||
+        message.includes('is not a field of')) {
+        return 'unknown-field';
+    }
+    if (message.includes('must be one of') || message.includes('not one of')) {
+        return 'invalid-reference';
+    }
+    if (message.startsWith('duplicate ') || message.includes('duplicate ')) {
+        return 'duplicate-value';
+    }
+    if (message.includes('needs an ownerField'))
+        return 'missing-owner-field';
+    if (message.includes('cannot be') || message.includes('must be '))
+        return 'invalid-field-kind';
+    if (zodCode === 'unrecognized_keys')
+        return 'unknown-key';
+    if (zodCode === 'invalid_type')
+        return 'invalid-type';
+    if (zodCode === 'too_small')
+        return 'value-too-small';
+    if (zodCode === 'too_big')
+        return 'value-too-large';
+    if (zodCode === 'invalid_value')
+        return 'invalid-value';
+    if (zodCode === 'invalid_format')
+        return 'invalid-format';
+    if (zodCode === 'custom')
+        return 'invalid-reference';
+    return 'invalid-value';
+}
+/** Hints for block, media and generic blueprint failures. Never auto-repairs. */
+export function blockOrAssetHint(code, message) {
+    if (code === 'unknown-block-type') {
+        return 'Set "type" to a supported block type (heading, text, image, chart, …). Custom or script types are not allowed.';
+    }
+    if (code === 'missing-alt-text') {
+        return 'Add a short alt description of the image, or set decorative: true when the image is purely decorative.';
+    }
+    if (code === 'invalid-alt-text') {
+        return 'Remove alt when decorative is true, or drop decorative and keep a meaningful alt.';
+    }
+    if (code === 'unsupported-url-scheme') {
+        return 'Use only allowed sources: avatar:av-001…175, a bounded data: URI, a relative asset path, or https:, mailto: and #section links. Remote media, http: links, relative links and javascript: URLs are refused; nothing is fetched during validation.';
+    }
+    if (code === 'invalid-chart-spec') {
+        return 'Fix the chart spec: every series needs one value per label; part-whole charts need one series of non-negative numbers; keep kind, title and labels within the schema bounds.';
+    }
+    if (code === 'duplicate-block-id') {
+        return 'Give each block a unique id within the document (deep links and interactive state key on id).';
+    }
+    if (code === 'invalid-step-or-fragment-target') {
+        return 'Point the step or fragment at an existing block id or a step index in range (0–32). Do not invent targets.';
+    }
+    return diagnosticHint(code, message);
+}
+function diagnosticHint(code, message) {
+    if (code === 'unknown-entity') {
+        return 'Use the exact name of an entity declared in entities, or add that entity first.';
+    }
+    if (code === 'unknown-field') {
+        return 'Use the exact field name declared on this entity, or add the field first.';
+    }
+    if (code === 'unknown-key') {
+        return 'Remove this key or replace it with a property supported by the blueprint schema.';
+    }
+    if (code === 'invalid-type') {
+        return 'Change this value to the type required by the schema at this path.';
+    }
+    if (code === 'value-too-small') {
+        return 'Add the required minimum number of items or increase this value to the allowed minimum.';
+    }
+    if (code === 'value-too-large') {
+        return 'Remove items or reduce this value to the allowed maximum.';
+    }
+    if (code === 'invalid-format') {
+        return 'Use the format shown by the schema message, such as kebab-case names or an ISO currency code.';
+    }
+    if (code === 'duplicate-value') {
+        return 'Give each item a unique name or value within its collection.';
+    }
+    if (code === 'missing-owner-field') {
+        return 'Add an ownerField that names a persona field, or remove the :own permission.';
+    }
+    if (code === 'invalid-field-kind') {
+        return 'Choose a field of the required kind, or change this setting to match the existing field.';
+    }
+    if (code === 'invalid-reference') {
+        return 'Update the reference to point to a declared entity, field, role, route, or allowed value.';
+    }
+    if (message.includes('money is integer cents')) {
+        return 'Use an integer amount in cents; for example, 1250 represents 12.50.';
+    }
+    return 'Adjust this value to satisfy the schema constraint described in the message.';
+}

package/dist/avatar.d.ts

@@ -0,0 +1,25 @@
+import { AVATAR_IDS, type AvatarId, isAvatarId } from '@protoyard/scenarios';
+import type { BlueprintEntity, BlueprintField } from './schema.ts';
+/**
+ * Avatar fields: a face from the avatar library stored as its id
+ * (`av-001` … `av-175`). Generated rows get seeded faces in the generator;
+ * a person changes a face through `EntityService.shuffleAvatar` (a service
+ * mutation) or by picking one in the form.
+ */
+export type AvatarField = Extract<BlueprintField, {
+    kind: 'avatar';
+}>;
+export { AVATAR_IDS, type AvatarId, isAvatarId };
+/** The entity's avatar fields, in declaration order. */
+export declare function avatarFields(entity: Pick<BlueprintEntity, 'fields'>): AvatarField[];
+/** The face shown next to a record's title: the entity's first avatar field. */
+export declare function primaryAvatarField(entity: Pick<BlueprintEntity, 'fields'>): AvatarField | undefined;
+/**
+ * The next face after `current` for a stable `key` (for example
+ * `customer:<id>:avatar`). Deterministic, with no clock or random source:
+ * each key walks the library with its own step, coprime with the library
+ * size, so repeated shuffles visit every face once before any repeats and
+ * never return `current`. A missing or unknown `current` starts at a
+ * key-derived face.
+ */
+export declare function nextAvatar(current: unknown, key: string): AvatarId;

package/dist/avatar.js

@@ -0,0 +1,30 @@
+import { hashString } from '@protoyard/core';
+import { AVATAR_IDS, isAvatarId } from '@protoyard/scenarios';
+export { AVATAR_IDS, isAvatarId };
+/** The entity's avatar fields, in declaration order. */
+export function avatarFields(entity) {
+    return entity.fields.filter((field) => field.kind === 'avatar');
+}
+/** The face shown next to a record's title: the entity's first avatar field. */
+export function primaryAvatarField(entity) {
+    return avatarFields(entity)[0];
+}
+const gcd = (a, b) => (b === 0 ? a : gcd(b, a % b));
+/**
+ * The next face after `current` for a stable `key` (for example
+ * `customer:<id>:avatar`). Deterministic, with no clock or random source:
+ * each key walks the library with its own step, coprime with the library
+ * size, so repeated shuffles visit every face once before any repeats and
+ * never return `current`. A missing or unknown `current` starts at a
+ * key-derived face.
+ */
+export function nextAvatar(current, key) {
+    const count = AVATAR_IDS.length;
+    const hash = hashString(key);
+    let step = 1 + (hash % (count - 1));
+    while (gcd(step, count) !== 1)
+        step = (step % (count - 1)) + 1;
+    const index = isAvatarId(current) ? AVATAR_IDS.indexOf(current) : -1;
+    const next = index < 0 ? hash % count : (index + step) % count;
+    return AVATAR_IDS[next];
+}