@owask/tapace-templates 0.0.0-stage → 0.1.0

package/dist/contract/definition.js

@@ -0,0 +1,854 @@
+import { z } from 'zod';
+import { AssetRefSchema, BarcodeEncodingSchema, BarcodeFormatSchema, HexColorSchema, } from './primitives.js';
+import { FieldKeySchema, FieldListSchema, POSTER_SLOTS, PosterLayoutSchema, STANDARD_SLOTS, StandardLayoutSchema, } from './fields.js';
+import { FeaturedActionDefSchema, MAX_FEATURED_ACTIONS, } from './featured-actions.js';
+import { CardRowsSchema, cardItemRef, resolveCardItem } from './event.js';
+import { TemplateRelevanceSchema, } from './relevance.js';
+import { StampNotificationsSchema, StampSettingsSchema, stampAssetIds, } from './stamps.js';
+import { PointsNotificationsSchema, PointsSettingsSchema } from './points.js';
+import { upgradeDefinition } from './upgrade.js';
+import { newFieldId } from './ids.js';
+export const TEMPLATE_SCHEMA_VERSION = 2;
+/** Where a barcode's payload comes from. Resolved to a concrete message at issuance. */
+export const BarcodeSourceSchema = z.discriminatedUnion('kind', [
+    z.strictObject({ kind: z.literal('static'), value: z.string().min(1).max(2048) }),
+    z.strictObject({ kind: z.literal('passValue'), sampleValue: z.string().max(2048).optional() }),
+    z.strictObject({ kind: z.literal('serialNumber') }),
+]);
+export const BarcodeConfigSchema = z.strictObject({
+    format: BarcodeFormatSchema,
+    source: BarcodeSourceSchema,
+    altText: z.string().max(256).optional(),
+    showText: z.boolean().optional(),
+    messageEncoding: BarcodeEncodingSchema.optional(),
+});
+/**
+ * Each type accepts only the slots its Apple style renders; strip, background
+ * and footer break Apple issuance for `generic` (see TEMPLATE_MAPPING.md "Image
+ * slots by pass type"). `artwork` and `primaryLogo` are poster-only.
+ */
+export const GENERIC_IMAGE_SLOTS = ['icon', 'logo', 'thumbnail', 'artwork', 'primaryLogo'];
+export const EVENT_TICKET_IMAGE_SLOTS = [
+    'icon',
+    'logo',
+    'strip',
+    'thumbnail',
+    'background',
+    'artwork',
+    'primaryLogo',
+];
+/** A stamp card's strip is drawn from its stamp settings, never uploaded. */
+export const STAMP_CARD_IMAGE_SLOTS = ['icon', 'logo', 'artwork', 'primaryLogo'];
+export const POINTS_CARD_IMAGE_SLOTS = ['icon', 'logo', 'strip', 'artwork', 'primaryLogo'];
+export const ImageSlotsSchema = z.strictObject({
+    icon: AssetRefSchema,
+    logo: AssetRefSchema.optional(),
+    thumbnail: AssetRefSchema.optional(),
+    artwork: AssetRefSchema.optional(),
+    primaryLogo: AssetRefSchema.optional(),
+});
+export const EventTicketImageSlotsSchema = z.strictObject({
+    icon: AssetRefSchema,
+    logo: AssetRefSchema.optional(),
+    strip: AssetRefSchema.optional(),
+    thumbnail: AssetRefSchema.optional(),
+    background: AssetRefSchema.optional(),
+    artwork: AssetRefSchema.optional(),
+    primaryLogo: AssetRefSchema.optional(),
+});
+export const StampCardImageSlotsSchema = z.strictObject({
+    icon: AssetRefSchema,
+    logo: AssetRefSchema.optional(),
+    artwork: AssetRefSchema.optional(),
+    primaryLogo: AssetRefSchema.optional(),
+});
+/** A points card's strip is an uploaded image, unrelated to the balance. */
+export const PointsCardImageSlotsSchema = z.strictObject({
+    icon: AssetRefSchema,
+    logo: AssetRefSchema.optional(),
+    strip: AssetRefSchema.optional(),
+    artwork: AssetRefSchema.optional(),
+    primaryLogo: AssetRefSchema.optional(),
+});
+/**
+ * The wallets whose design this revision must keep valid: those offered on new
+ * passes or used by an active pass. The server sets it on save. A wallet left
+ * out may still hold design that is saved but not required.
+ */
+export const PlatformsSchema = z.strictObject({ apple: z.boolean(), google: z.boolean() });
+/**
+ * The iOS 27 poster. It stays stored while switched off. `brand` picks a logo,
+ * logo text, or both; with both, Wallet cuts the text to fit beside the logo.
+ */
+export const PosterSettingsSchema = z.strictObject({
+    enabled: z.boolean(),
+    brand: z.enum(['logo', 'text', 'logoAndText']),
+});
+/**
+ * Apple-only controls. `sharingProhibited` hides Wallet's Share button; Google's
+ * closest control is `google.singleHolder`.
+ * `hideLogoText` drops `logoText` from the Apple pass only, for a wide logo that
+ * already shows the name; Google keeps it as the card title.
+ */
+export const AppleSettingsSchema = z.strictObject({
+    sharingProhibited: z.boolean().optional(),
+    hideLogoText: z.boolean().optional(),
+    poster: PosterSettingsSchema.optional(),
+    featuredActions: z.array(FeaturedActionDefSchema).max(MAX_FEATURED_ACTIONS).optional(),
+});
+/**
+ * Google-only controls. The hero image is Google-only (Apple has no analogue).
+ * `logoAssetId` is Google's logo, required when Google is on: Google crops it
+ * into a circle, while `images.logo` is Apple's wide 160×50 pt header logo.
+ * `wideLogoAssetId` is an optional wide header logo; Google still shows the
+ * square logo in the pass list and details.
+ * `singleHolder` locks each pass to the first Google account that saves it. It
+ * lives on the class, so a save applies it to every issued pass at once; Google
+ * refuses to turn it on while anyone holds a pass of the class.
+ */
+export const GoogleSettingsSchema = z.strictObject({
+    heroAssetId: AssetRefSchema.optional(),
+    logoAssetId: AssetRefSchema.optional(),
+    wideLogoAssetId: AssetRefSchema.optional(),
+    singleHolder: z.boolean().optional(),
+});
+/** An event ticket's Google class also carries its card-front rows (`cardRows`). */
+export const EventTicketGoogleSettingsSchema = GoogleSettingsSchema.extend({
+    cardRows: CardRowsSchema.optional(),
+});
+/**
+ * A loyalty card's (stamp or points) Google class names (each falls back to logo
+ * text) and the fields shown as Member name and Member ID. Google requires the ID,
+ * so its field is a required per-pass field. On a stamp card the drawn stamps are
+ * the hero, so `heroAssetId` is rejected there.
+ */
+export const LoyaltyGoogleSettingsSchema = GoogleSettingsSchema.extend({
+    issuerName: z.string().trim().min(1).max(100).optional(),
+    programName: z.string().trim().min(1).max(100).optional(),
+    memberNameField: FieldKeySchema.optional(),
+    memberIdField: FieldKeySchema.optional(),
+});
+/** Design fields shared by every template type. `name` lives on the row, not here. */
+const sharedShape = {
+    schemaVersion: z.literal(TEMPLATE_SCHEMA_VERSION),
+    description: z.string().min(1).max(200),
+    organizationName: z.string().min(1).max(100),
+    logoText: z.string().max(100).optional(),
+    colors: z.strictObject({
+        background: HexColorSchema,
+        foreground: HexColorSchema,
+        label: HexColorSchema.optional(),
+    }),
+    barcode: BarcodeConfigSchema.optional(),
+    platforms: PlatformsSchema,
+    apple: AppleSettingsSchema.default({}),
+    /** "When and where": locations reach both wallets, date windows only Apple. */
+    relevance: TemplateRelevanceSchema.optional(),
+};
+export const GenericConfigSchema = z.strictObject({
+    fields: FieldListSchema,
+    layouts: z.strictObject({
+        standard: StandardLayoutSchema,
+        poster: PosterLayoutSchema.optional(),
+    }),
+});
+export const EventTicketConfigSchema = z.strictObject({
+    fields: FieldListSchema,
+    layouts: z.strictObject({
+        standard: StandardLayoutSchema,
+        poster: PosterLayoutSchema.optional(),
+    }),
+});
+/** Apple draws the primary field over the strip, so stamp cards' standard layout has none. */
+export const StampCardConfigSchema = z.strictObject({
+    fields: FieldListSchema,
+    layouts: z.strictObject({
+        standard: StandardLayoutSchema,
+        poster: PosterLayoutSchema.optional(),
+    }),
+    stamps: StampSettingsSchema,
+    notifications: StampNotificationsSchema.default({}),
+});
+export const PointsCardConfigSchema = z.strictObject({
+    fields: FieldListSchema,
+    layouts: z.strictObject({
+        standard: StandardLayoutSchema,
+        poster: PosterLayoutSchema.optional(),
+    }),
+    points: PointsSettingsSchema,
+    notifications: PointsNotificationsSchema.default({}),
+});
+export const RESERVED_FIELD_KEY_PREFIX = 'tapace_';
+/**
+ * The template definition: shared design fields plus a `type`-discriminated
+ * `config`. A new type is added by appending a member here (and its config
+ * schema) — never a separate table or `any`.
+ */
+export const TemplateDefinitionSchema = z
+    .discriminatedUnion('type', [
+    z.strictObject({
+        ...sharedShape,
+        type: z.literal('generic'),
+        images: ImageSlotsSchema,
+        google: GoogleSettingsSchema.default({}),
+        config: GenericConfigSchema,
+    }),
+    z.strictObject({
+        ...sharedShape,
+        type: z.literal('event_ticket'),
+        images: EventTicketImageSlotsSchema,
+        google: EventTicketGoogleSettingsSchema.default({}),
+        config: EventTicketConfigSchema,
+    }),
+    z.strictObject({
+        ...sharedShape,
+        type: z.literal('stamp_card'),
+        images: StampCardImageSlotsSchema,
+        google: LoyaltyGoogleSettingsSchema.default({}),
+        config: StampCardConfigSchema,
+    }),
+    z.strictObject({
+        ...sharedShape,
+        type: z.literal('points_card'),
+        images: PointsCardImageSlotsSchema,
+        google: LoyaltyGoogleSettingsSchema.default({}),
+        config: PointsCardConfigSchema,
+    }),
+])
+    .superRefine((def, ctx) => {
+    const fields = def.config.fields;
+    const seenKeys = new Set();
+    const seenIds = new Set();
+    fields.forEach((f, index) => {
+        if (seenKeys.has(f.key)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Duplicate field key "${f.key}".`,
+                path: ['config', 'fields', index, 'key'],
+            });
+        }
+        seenKeys.add(f.key);
+        if (f.key.toLowerCase().startsWith(RESERVED_FIELD_KEY_PREFIX)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Field keys starting with "${RESERVED_FIELD_KEY_PREFIX}" are reserved for TapAce notifications.`,
+                path: ['config', 'fields', index, 'key'],
+            });
+        }
+        if (f.id !== undefined) {
+            if (seenIds.has(f.id)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Duplicate field id "${f.id}".`,
+                    path: ['config', 'fields', index, 'id'],
+                });
+            }
+            seenIds.add(f.id);
+        }
+    });
+    const roles = new Set();
+    fields.forEach((f, index) => {
+        if (def.type !== 'event_ticket' && (f.binding === 'event' || f.googleRole)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'Event fields and Google roles are for event ticket templates.',
+                path: ['config', 'fields', index, f.binding === 'event' ? 'binding' : 'googleRole'],
+            });
+        }
+        if (f.googleRole) {
+            if (roles.has(f.googleRole)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Another field already has the Google role "${f.googleRole}".`,
+                    path: ['config', 'fields', index, 'googleRole'],
+                });
+            }
+            roles.add(f.googleRole);
+        }
+    });
+    if (def.type === 'event_ticket') {
+        const byKey = new Map(fields.map((f) => [f.key, f]));
+        const inRows = new Set();
+        def.google.cardRows?.forEach((row, rowIndex) => {
+            row.forEach((ref, index) => {
+                const path = ['google', 'cardRows', rowIndex, index];
+                const item = resolveCardItem(ref, fields);
+                const field = byKey.get(ref);
+                if (!item && !field) {
+                    ctx.addIssue({ code: 'custom', message: `No field has the key "${ref}".`, path });
+                    return;
+                }
+                if (!item) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        message: `"${field?.label}" already shows on the Google ticket; it can't be a card row item.`,
+                        path,
+                    });
+                    return;
+                }
+                if (item.kind === 'seat' && !fields.some((f) => f.googleRole === item.role)) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        message: `"${ref}" needs a per-pass field with the Google role "${item.role}".`,
+                        path,
+                    });
+                }
+                const identity = cardItemRef(item);
+                if (inRows.has(identity)) {
+                    ctx.addIssue({ code: 'custom', message: `"${ref}" is on the Google card twice.`, path });
+                }
+                inRows.add(identity);
+            });
+        });
+    }
+    fields.forEach((f, index) => {
+        if ((f.binding === 'stamps' || f.binding === 'stampsLeft') && def.type !== 'stamp_card') {
+            ctx.addIssue({
+                code: 'custom',
+                message: f.binding === 'stamps'
+                    ? 'The stamp count field is for stamp card templates.'
+                    : 'The stamps left field is for stamp card templates.',
+                path: ['config', 'fields', index, 'binding'],
+            });
+        }
+        if ((f.binding === 'points' || f.binding === 'pointsToGoal') && def.type !== 'points_card') {
+            ctx.addIssue({
+                code: 'custom',
+                message: f.binding === 'points'
+                    ? 'The points field is for points card templates.'
+                    : 'The points to goal field is for points card templates.',
+                path: ['config', 'fields', index, 'binding'],
+            });
+        }
+        if (f.binding === 'pointsToGoal' &&
+            def.type === 'points_card' &&
+            def.config.points.goal === undefined) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'Set a goal to use the points to goal field.',
+                path: ['config', 'fields', index, 'binding'],
+            });
+        }
+    });
+    const ONE_FIELD = [
+        ['stamps', 'A stamp card has one stamp count field.'],
+        ['points', 'A points card has one points field.'],
+        ['stampsLeft', 'A stamp card has one stamps left field.'],
+        ['pointsToGoal', 'A points card has one points to goal field.'],
+    ];
+    for (const [binding, message] of ONE_FIELD) {
+        if (fields.filter((f) => f.binding === binding).length > 1) {
+            ctx.addIssue({ code: 'custom', message, path: ['config', 'fields'] });
+        }
+    }
+    const notificationTexts = (notifications, required, missing) => {
+        for (const [key, enabled] of required) {
+            if (enabled && notifications[key] === undefined) {
+                ctx.addIssue({ code: 'custom', message: missing, path: ['config', 'notifications', key] });
+            }
+        }
+    };
+    if (def.type === 'stamp_card' || def.type === 'points_card') {
+        const byKey = new Map(fields.map((f) => [f.key, f]));
+        const memberField = (key, name, required) => {
+            if (key === undefined)
+                return;
+            const path = ['google', name];
+            const field = byKey.get(key);
+            if (!field) {
+                ctx.addIssue({ code: 'custom', message: `No field has the key "${key}".`, path });
+            }
+            else if (field.binding !== 'perPass' || (required && !field.required)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: required
+                        ? `Member ID must be a required per-pass field; "${field.label}" is not.`
+                        : `Member name must be a per-pass field; "${field.label}" is not.`,
+                    path,
+                });
+            }
+        };
+        memberField(def.google.memberNameField, 'memberNameField', false);
+        memberField(def.google.memberIdField, 'memberIdField', true);
+        if (def.platforms.google && def.google.memberIdField === undefined) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'Google Wallet needs a Member ID. Pick the field that holds it.',
+                path: ['google', 'memberIdField'],
+            });
+        }
+    }
+    if (def.type === 'points_card') {
+        const notifications = def.config.notifications;
+        notificationTexts(notifications, [
+            ['apple', def.platforms.apple],
+            ['googleTitle', def.platforms.google],
+            ['googleBody', def.platforms.google],
+        ], 'Write the notification text for points changes.');
+        if (def.config.points.goal === undefined) {
+            for (const key of ['goalApple', 'goalGoogleTitle', 'goalGoogleBody']) {
+                if (notifications[key] !== undefined) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        message: 'Set a goal to use goal texts.',
+                        path: ['config', 'notifications', key],
+                    });
+                }
+            }
+        }
+    }
+    if (def.type === 'stamp_card') {
+        if (def.config.layouts.standard.primary.length > 0) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'Stamp cards have no primary field: Apple draws it over the stamps.',
+                path: ['config', 'layouts', 'standard', 'primary'],
+            });
+        }
+        if (def.google.heroAssetId) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'The stamps are the Google hero image on a stamp card.',
+                path: ['google', 'heroAssetId'],
+            });
+        }
+        notificationTexts(def.config.notifications, [
+            ['apple', def.platforms.apple],
+            ['googleTitle', def.platforms.google],
+            ['googleBody', def.platforms.google],
+        ], 'Write the notification text for stamp changes.');
+    }
+    const placed = new Set();
+    for (const [layout, slots] of layoutEntries(def)) {
+        const inLayout = new Set();
+        for (const [slot, keys] of slots) {
+            keys.forEach((key, index) => {
+                const path = ['config', 'layouts', layout, slot, index];
+                if (!seenKeys.has(key)) {
+                    ctx.addIssue({ code: 'custom', message: `No field has the key "${key}".`, path });
+                }
+                else if (inLayout.has(key)) {
+                    ctx.addIssue({
+                        code: 'custom',
+                        message: `Field "${key}" is placed twice in the ${layout} layout.`,
+                        path,
+                    });
+                }
+                inLayout.add(key);
+                placed.add(key);
+            });
+        }
+    }
+    fields.forEach((f, index) => {
+        if (!placed.has(f.key)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Field "${f.label}" is not placed in any layout.`,
+                path: ['config', 'fields', index],
+            });
+        }
+    });
+    const poster = def.apple.poster;
+    if (poster?.enabled) {
+        if (!def.config.layouts.poster) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'Arrange the poster layout before turning the poster on.',
+                path: ['config', 'layouts', 'poster'],
+            });
+        }
+        if (def.type === 'stamp_card' && !def.config.stamps.poster) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'Choose how the stamps look on the poster.',
+                path: ['config', 'stamps', 'poster'],
+            });
+        }
+        const onColor = def.type === 'stamp_card' && def.config.stamps.poster?.background.kind === 'color';
+        if (!onColor && !def.images.artwork) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'The poster needs artwork. Upload a poster artwork image.',
+                path: ['images', 'artwork'],
+            });
+        }
+        if (poster.brand !== 'text' && !def.images.primaryLogo && !def.images.logo) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'The poster shows a logo. Upload a logo or show logo text instead.',
+                path: ['apple', 'poster', 'brand'],
+            });
+        }
+        if (poster.brand !== 'logo' && !def.logoText?.trim()) {
+            ctx.addIssue({
+                code: 'custom',
+                message: 'The poster shows logo text. Add logo text or show a logo instead.',
+                path: ['logoText'],
+            });
+        }
+    }
+    const actions = def.apple.featuredActions ?? [];
+    const actionKeys = new Set();
+    const actionIds = new Set();
+    actions.forEach((action, index) => {
+        if (actionKeys.has(action.key)) {
+            ctx.addIssue({
+                code: 'custom',
+                message: `Duplicate action key "${action.key}".`,
+                path: ['apple', 'featuredActions', index, 'key'],
+            });
+        }
+        actionKeys.add(action.key);
+        if (action.id !== undefined) {
+            if (actionIds.has(action.id)) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `Duplicate action id "${action.id}".`,
+                    path: ['apple', 'featuredActions', index, 'id'],
+                });
+            }
+            actionIds.add(action.id);
+        }
+    });
+    if (def.platforms.google && !def.google.logoAssetId) {
+        ctx.addIssue({
+            code: 'custom',
+            message: 'Google Wallet needs its own logo. Upload a Google logo.',
+            path: ['google', 'logoAssetId'],
+        });
+    }
+    // Apple's event ticket shows either a strip or a background with an optional
+    // thumbnail; a pass carrying both is not laid out the way the designer shows.
+    if (def.type === 'event_ticket' && def.images.strip) {
+        for (const slot of ['background', 'thumbnail']) {
+            if (def.images[slot]) {
+                ctx.addIssue({
+                    code: 'custom',
+                    message: `A strip can't be combined with a ${slot}. Choose either Strip or Background + thumbnail.`,
+                    path: ['images', slot],
+                });
+            }
+        }
+    }
+});
+export class TemplateValidationError extends Error {
+    issues;
+    constructor(issues) {
+        super('Template definition is invalid.');
+        this.issues = issues;
+        this.name = 'TemplateValidationError';
+    }
+}
+/**
+ * Parse an untrusted definition through the versioned schema. Version 1 bodies
+ * are converted first. `type` is the caller's declared type (from the row /
+ * request) and must match the body's discriminator — a mismatched type/config
+ * pair is rejected, never coerced.
+ */
+export function parseTemplateDefinition(declaredType, input) {
+    const result = TemplateDefinitionSchema.safeParse(upgradeDefinition(input));
+    if (!result.success)
+        throw new TemplateValidationError(result.error.issues);
+    if (result.data.type !== declaredType) {
+        throw new TemplateValidationError([
+            {
+                code: 'custom',
+                message: `Definition type "${result.data.type}" does not match template type "${declaredType}".`,
+                path: ['type'],
+                input,
+            },
+        ]);
+    }
+    return result.data;
+}
+/**
+ * A saved revision's definition. Saved definitions were validated on save;
+ * version 1 ones are converted, and ones saved before the platform blocks
+ * existed get empty ones.
+ */
+export function storedDefinition(raw) {
+    const def = upgradeDefinition(raw);
+    if (def.apple && def.google)
+        return def;
+    return { ...def, apple: def.apple ?? {}, google: def.google ?? {} };
+}
+function layoutEntries(def) {
+    const entries = [
+        ['standard', STANDARD_SLOTS.map((slot) => [slot, def.config.layouts.standard[slot]])],
+    ];
+    const poster = posterLayout(def);
+    if (poster)
+        entries.push(['poster', POSTER_SLOTS.map((slot) => [slot, poster[slot]])]);
+    return entries;
+}
+function posterLayout(def) {
+    return 'poster' in def.config.layouts ? def.config.layouts.poster : undefined;
+}
+/** True when the pass renders the poster: switched on, with a stored poster layout. */
+export function posterEnabled(def) {
+    return def.apple.poster?.enabled === true && !!posterLayout(def);
+}
+function fieldsByKey(def) {
+    return new Map(def.config.fields.map((f) => [f.key, f]));
+}
+/** The standard layout's fields per slot, in placement order. */
+export function standardLayoutFields(def) {
+    const byKey = fieldsByKey(def);
+    const out = {};
+    for (const slot of STANDARD_SLOTS) {
+        out[slot] = def.config.layouts.standard[slot]
+            .map((key) => byKey.get(key))
+            .filter((f) => !!f);
+    }
+    return out;
+}
+/** The poster layout's fields per slot, or undefined when the poster is not rendered. */
+export function posterLayoutFields(def) {
+    const poster = posterLayout(def);
+    if (!poster || !posterEnabled(def))
+        return undefined;
+    const byKey = fieldsByKey(def);
+    const out = {};
+    for (const slot of POSTER_SLOTS) {
+        out[slot] = poster[slot].map((key) => byKey.get(key)).filter((f) => !!f);
+    }
+    return out;
+}
+/**
+ * Fields placed in a rendered layout: the standard layout, plus the poster while
+ * it is on. Ordered by placement (standard slots, then poster slots).
+ */
+export function activeFields(def) {
+    const out = [];
+    const seen = new Set();
+    const add = (fields) => {
+        for (const f of fields) {
+            if (seen.has(f.key))
+                continue;
+            seen.add(f.key);
+            out.push(f);
+        }
+    };
+    const standard = standardLayoutFields(def);
+    for (const slot of STANDARD_SLOTS)
+        add(standard[slot]);
+    const poster = def.platforms.apple ? posterLayoutFields(def) : undefined;
+    if (poster)
+        for (const slot of POSTER_SLOTS)
+            add(poster[slot]);
+    return out;
+}
+/** Where a field shows: its standard slot, or its poster slot for a poster-only field. */
+export function fieldSlot(def, key) {
+    for (const slot of STANDARD_SLOTS) {
+        if (def.config.layouts.standard[slot].includes(key))
+            return slot;
+    }
+    const poster = posterLayout(def);
+    if (poster) {
+        for (const slot of POSTER_SLOTS)
+            if (poster[slot].includes(key))
+                return slot;
+    }
+    return undefined;
+}
+export function featuredActions(def) {
+    return def.platforms.apple ? (def.apple.featuredActions ?? []) : [];
+}
+/**
+ * The Lock Screen relevance a pass carries: its own lists, else the template's,
+ * else, on an event ticket, the venue and the doors-open (or start) to end window.
+ * Date windows need Apple; locations also reach Google.
+ */
+export function resolveRelevance(def, own) {
+    const event = def.type === 'event_ticket' ? def.event : undefined;
+    const opens = event?.doorsOpen ?? event?.start;
+    const eventLocations = event?.venue?.location ? [event.venue.location] : [];
+    const eventDates = opens && event?.end ? [{ start: opens, end: event.end }] : [];
+    return {
+        locations: own?.locations ?? def.relevance?.locations ?? eventLocations,
+        dates: def.platforms.apple ? (own?.dates ?? def.relevance?.dates ?? eventDates) : [],
+    };
+}
+export function imageSlotsOf(def) {
+    switch (def.type) {
+        case 'event_ticket':
+            return EVENT_TICKET_IMAGE_SLOTS;
+        case 'stamp_card':
+            return STAMP_CARD_IMAGE_SLOTS;
+        case 'points_card':
+            return POINTS_CARD_IMAGE_SLOTS;
+        case 'generic':
+            return GENERIC_IMAGE_SLOTS;
+    }
+}
+export function imageAssetId(def, slot) {
+    return def.images[slot];
+}
+/**
+ * The asset the poster shows as its logo: the poster logo override, else the
+ * Apple logo. Undefined when the poster is off or shows logo text only.
+ */
+export function posterLogoAssetId(def) {
+    if (!posterEnabled(def) || def.apple.poster?.brand === 'text')
+        return undefined;
+    return imageAssetId(def, 'primaryLogo') ?? imageAssetId(def, 'logo');
+}
+/** Asset ids a definition references, so they can be ownership-checked. */
+export function referencedAssetIds(def) {
+    const ids = imageSlotsOf(def)
+        .map((slot) => imageAssetId(def, slot))
+        .filter((id) => !!id);
+    if (def.google.heroAssetId)
+        ids.push(def.google.heroAssetId);
+    if (def.google.logoAssetId)
+        ids.push(def.google.logoAssetId);
+    if (def.google.wideLogoAssetId)
+        ids.push(def.google.wideLogoAssetId);
+    if (def.type === 'stamp_card')
+        ids.push(...stampAssetIds(def.config.stamps));
+    return [...new Set(ids)];
+}
+/** Keys the issue-pass form must collect: per-pass fields flagged required, in a rendered layout. */
+export function requiredFieldKeys(def) {
+    return activeFields(def)
+        .filter((f) => f.binding === 'perPass' && f.required)
+        .map((f) => f.key);
+}
+/** Featured actions every issued pass must supply a link for. */
+export function requiredActionKeys(def) {
+    return featuredActions(def)
+        .filter((a) => a.binding === 'perPass')
+        .map((a) => a.key);
+}
+function idIssue(message, path) {
+    return { code: 'custom', message, path };
+}
+/**
+ * Assign stable ids to new fields and featured actions, and reject unknown or
+ * duplicate ids. Within a layout a saved field keeps its slot: moving it means
+ * deleting it and creating a new field.
+ */
+export function normalizeFieldIds(def, previousDef) {
+    const issues = [];
+    const previousFieldIds = new Set((previousDef?.config.fields ?? []).flatMap((f) => (f.id ? [f.id] : [])));
+    const usedFieldIds = new Set();
+    const fields = def.config.fields.map((field, index) => {
+        if (field.id === undefined) {
+            return { ...field, id: mintId('fld', previousFieldIds, usedFieldIds) };
+        }
+        const path = ['config', 'fields', index, 'id'];
+        if (!previousFieldIds.has(field.id)) {
+            issues.push(idIssue(`Unknown field id "${field.id}".`, path));
+        }
+        else if (usedFieldIds.has(field.id)) {
+            issues.push(idIssue(`Duplicate field id "${field.id}".`, path));
+        }
+        usedFieldIds.add(field.id);
+        return field;
+    });
+    if (previousDef) {
+        const next = { ...def, config: { ...def.config, fields } };
+        const idOf = new Map(fields.map((f) => [f.key, f.id]));
+        const previousIdOf = new Map(previousDef.config.fields.map((f) => [f.key, f.id]));
+        const previousSlots = new Map();
+        for (const [layout, slots] of layoutEntries(previousDef)) {
+            const byId = new Map();
+            for (const [slot, keys] of slots) {
+                for (const key of keys) {
+                    const id = previousIdOf.get(key);
+                    if (id)
+                        byId.set(id, slot);
+                }
+            }
+            previousSlots.set(layout, byId);
+        }
+        for (const [layout, slots] of layoutEntries(next)) {
+            const before = previousSlots.get(layout);
+            if (!before)
+                continue;
+            for (const [slot, keys] of slots) {
+                keys.forEach((key, index) => {
+                    const id = idOf.get(key);
+                    const previousSlot = id ? before.get(id) : undefined;
+                    if (previousSlot !== undefined && previousSlot !== slot) {
+                        issues.push(idIssue(`Field "${key}" cannot move from "${previousSlot}" to "${slot}" in the ${layout} layout. Delete it and create a new field instead.`, ['config', 'layouts', layout, slot, index]));
+                    }
+                });
+            }
+        }
+    }
+    const previousActionIds = new Set((previousDef?.apple?.featuredActions ?? []).flatMap((a) => (a.id ? [a.id] : [])));
+    const usedActionIds = new Set();
+    const actions = def.apple.featuredActions?.map((action, index) => {
+        if (action.id === undefined) {
+            return { ...action, id: mintId('fa', previousActionIds, usedActionIds) };
+        }
+        const path = ['apple', 'featuredActions', index, 'id'];
+        if (!previousActionIds.has(action.id)) {
+            issues.push(idIssue(`Unknown action id "${action.id}".`, path));
+        }
+        else if (usedActionIds.has(action.id)) {
+            issues.push(idIssue(`Duplicate action id "${action.id}".`, path));
+        }
+        usedActionIds.add(action.id);
+        return action;
+    });
+    if (issues.length > 0)
+        throw new TemplateValidationError(issues);
+    return {
+        ...def,
+        apple: actions ? { ...def.apple, featuredActions: actions } : def.apple,
+        config: { ...def.config, fields },
+    };
+}
+function mintId(prefix, previousIds, usedIds) {
+    let id = newFieldId(prefix);
+    while (previousIds.has(id) || usedIds.has(id))
+        id = newFieldId(prefix);
+    usedIds.add(id);
+    return id;
+}
+/**
+ * Preview adapter: callers pass public key-based sample values, but the compiler
+ * resolves per-pass values by field id. This maps keys to ids and assigns
+ * ephemeral in-memory ids to unsaved (id-less) fields and actions so their
+ * sample values still resolve. The returned definition is for rendering only,
+ * never persisted; keys that match no field are dropped.
+ */
+export function previewFieldValues(def, sampleValues) {
+    const idByKey = new Map();
+    let ephemeral = 0;
+    const fields = def.config.fields.map((field) => {
+        const id = field.id ?? `preview_${ephemeral++}`;
+        idByKey.set(field.key, id);
+        return field.id === undefined ? { ...field, id } : field;
+    });
+    const actions = def.apple.featuredActions?.map((action) => action.id === undefined ? { ...action, id: `preview_${ephemeral++}` } : action);
+    const values = {};
+    for (const [key, value] of Object.entries(sampleValues)) {
+        const id = idByKey.get(key);
+        if (id !== undefined)
+            values[id] = value;
+    }
+    return {
+        def: {
+            ...def,
+            apple: actions ? { ...def.apple, featuredActions: actions } : def.apple,
+            config: { ...def.config, fields },
+        },
+        values,
+    };
+}
+export function fieldValuesByKey(def, byId) {
+    const keyOf = new Map(def.config.fields
+        .filter((f) => f.id !== undefined)
+        .map((f) => [f.id, f.key]));
+    const out = {};
+    for (const [id, value] of Object.entries(byId)) {
+        const key = keyOf.get(id);
+        if (key !== undefined)
+            out[key] = value;
+    }
+    return out;
+}