@protoyard/blueprint 0.0.0-stage → 1.1.0

package/dist/files.js

@@ -0,0 +1,246 @@
+import { createRuntimeId, parseInput, ValidationError, } from '@protoyard/core';
+import { z } from 'zod';
+import { entityTable, } from "./schema.js";
+import { FEATURE_TABLES, relationProperty } from "./storage.js";
+import { fieldLabel } from "./validation.js";
+export const DEFAULT_FILE_QUOTA_BYTES = 50 * 1024 * 1024;
+const UploadInputSchema = z.strictObject({
+    entity: z.string().min(1),
+    recordId: z.string().min(1),
+    field: z.string().min(1),
+    name: z.string().min(1).max(255).optional(),
+});
+export class FileUploadError extends Error {
+    code;
+    constructor(code, message) {
+        super(message);
+        this.name = 'FileUploadError';
+        this.code = code;
+    }
+}
+function asMetadata(row) {
+    const { blob: _blob, ...metadata } = row;
+    return metadata;
+}
+function accepts(field, type) {
+    if (field.accept.length === 0)
+        return true;
+    const mime = type.toLowerCase();
+    return field.accept.some((pattern) => {
+        const accepted = pattern.toLowerCase();
+        return accepted.endsWith('/*') ? mime.startsWith(accepted.slice(0, -1)) : mime === accepted;
+    });
+}
+function assertUpdateAllowed(runtime, entity, row) {
+    const capability = `${entity.name}:update`;
+    const owner = entity.ownerField
+        ? entity.fields.find((field) => field.name === entity.ownerField)
+        : undefined;
+    const ownerId = owner ? row[relationProperty(owner) ?? owner.name] : undefined;
+    if (runtime.session.can(capability, row) ||
+        (typeof ownerId === 'string' && runtime.session.can(`${entity.name}:update:own`, row))) {
+        return;
+    }
+    runtime.session.assert(capability, row);
+}
+function entityMap(blueprint) {
+    return new Map(blueprint.entities.map((entity) => [entity.name, entity]));
+}
+export function createFileServices(runtime, blueprint, options = {}) {
+    const db = runtime.db;
+    const files = db.table(FEATURE_TABLES.files);
+    const entities = entityMap(blueprint);
+    const quotaLimit = parseInput(z.number().int().nonnegative(), options.prototypeQuotaBytes ?? DEFAULT_FILE_QUOTA_BYTES);
+    function fileField(entity, fieldName) {
+        const field = entity.fields.find((candidate) => candidate.name === fieldName);
+        if (field?.kind !== 'file') {
+            throw new ValidationError({ [fieldName]: 'Choose a file field on this entity' });
+        }
+        return field;
+    }
+    function getEntity(entityName) {
+        const entity = entities.get(entityName);
+        if (!entity)
+            throw new FileUploadError('not-found', `No blueprint entity named "${entityName}".`);
+        if (!entity.features.files) {
+            throw new FileUploadError('files-disabled', `File uploads are disabled for "${entityName}".`);
+        }
+        return entity;
+    }
+    function actorId() {
+        const id = runtime.session.principal()?.persona.id;
+        if (!id)
+            throw new Error('No active persona. Load a scenario first.');
+        return id;
+    }
+    async function assertQuota(size) {
+        const stored = await files.toArray();
+        const prototypeUsage = stored.reduce((total, row) => {
+            const rowSize = row.size;
+            if (typeof rowSize !== 'number' || !Number.isSafeInteger(rowSize) || rowSize < 0) {
+                throw new FileUploadError('quota-exceeded', 'Stored file metadata exceeds the available quota.');
+            }
+            return total + rowSize;
+        }, 0);
+        const storage = runtime.storage();
+        const browserRemaining = storage.quotaBytes === undefined || storage.usageBytes === undefined
+            ? Number.POSITIVE_INFINITY
+            : Math.max(0, storage.quotaBytes - storage.usageBytes);
+        const limit = Math.min(quotaLimit, storage.quotaBytes ?? quotaLimit);
+        if (prototypeUsage + size > limit || size > browserRemaining) {
+            throw new FileUploadError('quota-exceeded', 'This prototype does not have enough storage quota for that file.');
+        }
+    }
+    async function record(entity, recordId) {
+        const row = await db.table(entityTable(entity)).get(recordId);
+        if (!row || row.deletedAt)
+            throw new FileUploadError('not-found', `No ${entity.name} with id "${recordId}".`);
+        assertUpdateAllowed(runtime, entity, row);
+        return row;
+    }
+    async function readRecord(entity, recordId) {
+        const row = await db.table(entityTable(entity)).get(recordId);
+        if (!row || row.deletedAt)
+            throw new FileUploadError('not-found', `No ${entity.name} with id "${recordId}".`);
+        runtime.session.assert(`${entity.name}:read`, row);
+        return row;
+    }
+    const serviceFor = (entity) => ({
+        async upload(input, onProgress) {
+            if (!entity.features.files) {
+                throw new FileUploadError('files-disabled', `File uploads are disabled for "${entity.name}".`);
+            }
+            const recordInput = typeof input === 'object' && input !== null ? input : {};
+            const { file: candidate, ...metadataInput } = recordInput;
+            if (typeof recordInput.recordId !== 'string') {
+                throw new ValidationError({ recordId: 'Choose a record' });
+            }
+            const current = await record(entity, recordInput.recordId);
+            const data = parseInput(UploadInputSchema, metadataInput);
+            if (typeof Blob === 'undefined' || !(candidate instanceof Blob)) {
+                throw new ValidationError({ file: 'Choose a file to upload' });
+            }
+            if (data.entity !== entity.name) {
+                throw new ValidationError({ entity: `Use the ${entity.name} file service` });
+            }
+            const field = fileField(entity, data.field);
+            const file = candidate;
+            const name = data.name ?? file.name ?? 'upload';
+            if (file.size > field.maxSizeBytes) {
+                throw new FileUploadError('size-limit', `${fieldLabel(field)} must be at most ${field.maxSizeBytes} bytes.`);
+            }
+            if (!accepts(field, file.type)) {
+                throw new FileUploadError('type-not-allowed', `${fieldLabel(field)} does not accept ${file.type || 'an unknown file type'}.`);
+            }
+            await assertQuota(file.size);
+            const id = createRuntimeId('file');
+            const ownerId = actorId();
+            const property = relationProperty(field);
+            const oldIds = field.multiple
+                ? (current[property] ?? [])
+                : typeof current[property] === 'string'
+                    ? [current[property]]
+                    : [];
+            const nextIds = field.multiple ? [...new Set([...oldIds, id])] : [id];
+            const metadata = {
+                id,
+                name,
+                type: file.type,
+                size: file.size,
+                ownerId,
+                entity: entity.name,
+                recordId: data.recordId,
+                createdAt: runtime.clock.now().toISOString(),
+            };
+            onProgress?.({ loaded: 0, total: file.size, percent: 0 });
+            return runtime.environment.run('files.upload', async () => {
+                onProgress?.({ loaded: Math.floor(file.size / 2), total: file.size, percent: 50 });
+                // Keep binary bytes in IndexedDB; the service reconstructs a Blob on demand.
+                const storedBytes = await file.arrayBuffer();
+                await db.transaction('rw', [entityTable(entity), FEATURE_TABLES.files, 'py_personas'], async () => {
+                    await record(entity, data.recordId);
+                    await assertQuota(file.size);
+                    if (!field.multiple) {
+                        for (const oldId of oldIds)
+                            await files.delete(oldId);
+                    }
+                    await files.put({ ...metadata, blob: storedBytes });
+                    await db.table(entityTable(entity)).update(data.recordId, {
+                        [property]: field.multiple ? nextIds : id,
+                        updatedAt: runtime.clock.now().toISOString(),
+                    });
+                });
+                onProgress?.({ loaded: file.size, total: file.size, percent: 100 });
+                return metadata;
+            });
+        },
+        async list(entityName, recordId, fieldName) {
+            const targetEntity = getEntity(entityName);
+            if (targetEntity.name !== entity.name)
+                throw new ValidationError({ entity: 'Use the matching file service' });
+            const row = await readRecord(targetEntity, recordId);
+            const selectedFields = targetEntity.fields.filter((field) => field.kind === 'file' && (!fieldName || field.name === fieldName));
+            const ids = new Set(selectedFields.flatMap((field) => {
+                const value = row[relationProperty(field)];
+                return Array.isArray(value) ? value : typeof value === 'string' ? [value] : [];
+            }));
+            const all = await files.toArray();
+            return all.filter((file) => ids.has(file.id)).map(asMetadata);
+        },
+        async get(id) {
+            if (!entity.features.files) {
+                throw new FileUploadError('files-disabled', `File uploads are disabled for "${entity.name}".`);
+            }
+            const file = await files.get(id);
+            if (!file || file.entity !== entity.name)
+                return undefined;
+            const target = getEntity(entity.name);
+            await readRecord(target, file.recordId);
+            const storedBlob = file.blob;
+            let blob;
+            if (typeof Blob !== 'undefined' && storedBlob instanceof Blob) {
+                blob = storedBlob;
+            }
+            else if (storedBlob instanceof ArrayBuffer) {
+                blob = new Blob([storedBlob], { type: file.type });
+            }
+            else {
+                throw new FileUploadError('data-unavailable', 'This attachment has no binary data. File contents are not preserved in JSON snapshots.');
+            }
+            return { ...file, blob };
+        },
+        async remove(id) {
+            if (!entity.features.files) {
+                throw new FileUploadError('files-disabled', `File uploads are disabled for "${entity.name}".`);
+            }
+            const file = await files.get(id);
+            if (!file || file.entity !== entity.name)
+                return false;
+            const target = getEntity(entity.name);
+            const row = await record(target, file.recordId);
+            const matchingField = target.fields.find((candidate) => candidate.kind === 'file' &&
+                (Array.isArray(row[relationProperty(candidate)])
+                    ? row[relationProperty(candidate)].includes(id)
+                    : row[relationProperty(candidate)] === id));
+            if (!matchingField)
+                return false;
+            const property = relationProperty(matchingField);
+            const fileFieldSchema = matchingField;
+            return runtime.environment.run('files.remove', () => db.transaction('rw', [entityTable(target), FEATURE_TABLES.files], async () => {
+                const latest = await record(target, file.recordId);
+                const value = latest[property];
+                await files.delete(id);
+                await db.table(entityTable(target)).update(file.recordId, {
+                    [property]: fileFieldSchema?.kind === 'file' && fileFieldSchema.multiple
+                        ? Array.isArray(value)
+                            ? value.filter((fileId) => fileId !== id)
+                            : []
+                        : null,
+                    updatedAt: runtime.clock.now().toISOString(),
+                });
+                return true;
+            }));
+        },
+    });
+    return Object.fromEntries(blueprint.entities.map((entity) => [entity.name, serviceFor(entity)]));
+}

package/dist/form-schema.d.ts

@@ -0,0 +1,124 @@
+import type { BlueprintEntity, BlueprintField, FieldKind } from './schema.ts';
+import { type EntityInput } from './validation.ts';
+/**
+ * Blueprint fields → a `@texuli/forms` schema (plain data, no Texuli import
+ * at runtime). `@protoyard/crud` paints entity forms with Texuli's
+ * `SchemaForm` from this mapping; the entity services stay the source of
+ * truth for validation (session.assert → zod → environment.run →
+ * db.transaction), so the schema only carries the rules that agree with the
+ * service: required, length and number bounds, whole-number and cent steps,
+ * and the tag count.
+ *
+ * Kinds Texuli has no control for (a paged relation picker, map points, the
+ * face library, uploads) are *hosted*: they are Texuli `custom` fields (G113)
+ * whose `kind` is the blueprint kind, so the host paints them with its own
+ * controls inside the same form, and Texuli labels, validates and submits
+ * them with the rest.
+ */
+/** The `@texuli/forms` field types this mapping emits. */
+export type EntityFormFieldType = 'text' | 'textarea' | 'number' | 'email' | 'url' | 'date' | 'datetime' | 'select' | 'checkbox' | 'tags' | 'custom';
+/** One choice of a `select` field (`@texuli/forms` `FormOption`). */
+export interface EntityFormOption {
+    readonly value: string;
+    readonly label: string;
+}
+/**
+ * One field of the emitted schema: the subset of `@texuli/forms` `FormField`
+ * this mapping uses (structurally assignable to it).
+ */
+export interface EntityFormField {
+    readonly name: string;
+    readonly type: EntityFormFieldType;
+    readonly label: string;
+    readonly description?: string;
+    readonly placeholder?: string;
+    readonly required?: boolean;
+    readonly options?: readonly EntityFormOption[];
+    readonly minLength?: number;
+    readonly maxLength?: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly maxItems?: number;
+    readonly rows?: number;
+    /** Url fields: the schemes the service accepts. */
+    readonly protocols?: readonly ('http' | 'https')[];
+    /** Custom fields: the blueprint field kind the host paints. */
+    readonly kind?: string;
+    /** Conditions; this mapping only emits a constant `enable` (a read-only form). */
+    readonly when?: {
+        readonly enable: {
+            readonly op: 'bool';
+            readonly value: boolean;
+        };
+    };
+}
+/** A one-page `@texuli/forms` `FormSchema` (structurally assignable to it). */
+export interface EntityFormSchema {
+    readonly title: string;
+    readonly submitLabel?: string;
+    readonly fields: readonly EntityFormField[];
+}
+/**
+ * Field kinds the host paints itself (no matching `@texuli/forms` control),
+ * as Texuli `custom` fields. Persona fields without people to pick and enums
+ * past Texuli's option cap are hosted too (see `ENTITY_FORM_CUSTOM_KINDS`).
+ */
+export declare const HOSTED_FORM_KINDS: ReadonlySet<FieldKind>;
+/**
+ * Every `kind` a hosted (`custom`) field of this mapping can carry. Pass it
+ * as `validateFormSchema(schema, { kinds })` so Texuli checks them.
+ */
+export declare const ENTITY_FORM_CUSTOM_KINDS: readonly FieldKind[];
+/**
+ * @deprecated No longer emitted. Since Texuli 0.10.0 an optional persona
+ * select offers its own empty "None" choice (G118), so the mapping adds no
+ * sentinel option. `fromFormValues` still reads it as unassigned.
+ */
+export declare const UNASSIGNED_OPTION = "~unassigned";
+export interface EntityFormSchemaOptions {
+    /** Create or edit (the default title and submit label follow it). Default `create`. */
+    mode?: 'create' | 'edit';
+    /** Form title (Texuli forms always have one). Default `New <entity>` / `Edit <entity>`. */
+    title?: string;
+    submitLabel?: string;
+    /**
+     * Paint every field disabled (`when.enable` is never true). Disabled
+     * fields are neither validated nor submitted by Texuli. A host that only
+     * needs a disabled form can pass SchemaForm's own `disabled` (G116).
+     */
+    readOnly?: boolean;
+    /**
+     * The people a persona field can pick. Without them persona fields are
+     * hosted (the host paints its own picker).
+     */
+    personaOptions?: readonly EntityFormOption[];
+}
+export interface EntityFormModel {
+    /** The schema to pass to `validateFormSchema` from `@texuli/forms`. */
+    readonly schema: EntityFormSchema;
+    /** Fields Texuli paints with its own controls, in blueprint order. */
+    readonly painted: readonly BlueprintField[];
+    /** Fields the host paints, as Texuli `custom` fields of the same form, in blueprint order. */
+    readonly hosted: readonly BlueprintField[];
+    /**
+     * The schema field name of each field, by `inputProperty`. It is the
+     * `inputProperty` itself unless Texuli refuses that name (`FORM_NAME`, an
+     * `Object.prototype` member); then it is `field_<index>`.
+     */
+    readonly names: ReadonlyMap<string, string>;
+    /** The blueprint field behind a schema field name. */
+    fieldFor(name: string): BlueprintField | undefined;
+    /**
+     * Starting form values by schema field name: the row's values (an edited
+     * record, or a create prefill), then the field defaults on create.
+     */
+    toFormValues(row: Readonly<Record<string, unknown>> | null | undefined): Record<string, unknown>;
+    /** Submitted form values → entity service input (keyed by `inputProperty`). */
+    fromFormValues(values: Readonly<Record<string, unknown>>): EntityInput;
+}
+/**
+ * Map an entity to a `@texuli/forms` schema plus the value converters for
+ * the fields Texuli paints. Pure and deterministic.
+ */
+export declare function entityFormModel(entity: BlueprintEntity, options?: EntityFormSchemaOptions): EntityFormModel;

package/dist/form-schema.js

@@ -0,0 +1,300 @@
+import { fieldLabel, inputProperty } from "./validation.js";
+/**
+ * Field kinds the host paints itself (no matching `@texuli/forms` control),
+ * as Texuli `custom` fields. Persona fields without people to pick and enums
+ * past Texuli's option cap are hosted too (see `ENTITY_FORM_CUSTOM_KINDS`).
+ */
+export const HOSTED_FORM_KINDS = new Set([
+    'relation',
+    'geo',
+    'avatar',
+    'file',
+]);
+/**
+ * Every `kind` a hosted (`custom`) field of this mapping can carry. Pass it
+ * as `validateFormSchema(schema, { kinds })` so Texuli checks them.
+ */
+export const ENTITY_FORM_CUSTOM_KINDS = [
+    ...HOSTED_FORM_KINDS,
+    'persona',
+    'enum',
+];
+/**
+ * @deprecated No longer emitted. Since Texuli 0.10.0 an optional persona
+ * select offers its own empty "None" choice (G118), so the mapping adds no
+ * sentinel option. `fromFormValues` still reads it as unassigned.
+ */
+export const UNASSIGNED_OPTION = '~unassigned';
+/** A `when` whose `enable` is never true. */
+const READ_ONLY = { enable: { op: 'bool', value: false } };
+/** `@texuli/forms` field-name rule and the names it refuses (`FORM_NAME`, `FORM_RESERVED_NAMES`). */
+const TEXULI_NAME = /^[a-z][A-Za-z0-9_]{0,63}$/;
+const RESERVED_NAMES = new Set(Object.getOwnPropertyNames(Object.prototype).filter((name) => TEXULI_NAME.test(name)));
+/** `@texuli/forms` `FORM_LIMITS.options`. */
+const MAX_OPTIONS = 200;
+/** `@texuli/forms` `FORM_LIMITS.valueLength`. */
+const MAX_TEXT = 10_000;
+/** `support-ticket` → `support ticket`. */
+function entityNoun(entity) {
+    return entity.name.replace(/-/g, ' ');
+}
+function truncate(text, max) {
+    return text.length > max ? text.slice(0, max) : text;
+}
+function personaOptionsFor(options) {
+    const list = [...options];
+    const seen = new Set();
+    for (const option of list) {
+        if (!option.value || seen.has(option.value))
+            return null;
+        seen.add(option.value);
+    }
+    return list.length > 0 && list.length <= MAX_OPTIONS ? list : null;
+}
+/** The schema field name of a blueprint field (its `inputProperty`, unless Texuli refuses it). */
+function schemaName(field, index) {
+    const name = inputProperty(field);
+    return TEXULI_NAME.test(name) && !RESERVED_NAMES.has(name) ? name : `field_${index}`;
+}
+/** A hosted field: a Texuli `custom` field the host paints for its blueprint kind. */
+function customField(field, name) {
+    return {
+        name,
+        type: 'custom',
+        kind: field.kind,
+        label: fieldLabel(field),
+        ...(field.description ? { description: field.description } : {}),
+        ...(field.required ? { required: true } : {}),
+    };
+}
+/** The Texuli field for a blueprint field, or `null` when the host paints it. */
+function paintField(field, name, personaOptions) {
+    if (HOSTED_FORM_KINDS.has(field.kind))
+        return null;
+    const label = fieldLabel(field);
+    const base = {
+        name,
+        label,
+        ...(field.description ? { description: field.description } : {}),
+        ...(field.required ? { required: true } : {}),
+    };
+    switch (field.kind) {
+        case 'text':
+            return {
+                ...base,
+                type: 'text',
+                ...(field.minLength ? { minLength: field.minLength } : {}),
+                maxLength: Math.min(field.maxLength, MAX_TEXT),
+            };
+        case 'longText':
+            return {
+                ...base,
+                type: 'textarea',
+                rows: 4,
+                ...(field.minLength ? { minLength: field.minLength } : {}),
+                maxLength: Math.min(field.maxLength, MAX_TEXT),
+            };
+        case 'json':
+            // The service parses the text and reports "must be valid JSON" inline.
+            return { ...base, type: 'textarea', rows: 6 };
+        case 'number':
+            return {
+                ...base,
+                type: 'number',
+                ...(field.min !== undefined ? { min: field.min } : {}),
+                ...(field.max !== undefined ? { max: field.max } : {}),
+            };
+        case 'integer':
+            return {
+                ...base,
+                type: 'number',
+                step: 1,
+                ...(field.min !== undefined ? { min: field.min } : {}),
+                ...(field.max !== undefined ? { max: field.max } : {}),
+            };
+        case 'money':
+            // Shown in major units; stored as integer cents (see `fromFormValues`).
+            return {
+                ...base,
+                type: 'number',
+                step: 0.01,
+                placeholder: '0.00',
+                ...(field.min !== undefined ? { min: field.min / 100 } : {}),
+                ...(field.max !== undefined ? { max: field.max / 100 } : {}),
+            };
+        case 'boolean': {
+            // A required checkbox means "must be checked" in Texuli; a blueprint
+            // boolean is required to have a value, which a checkbox always has.
+            const { required: _required, ...rest } = base;
+            return { ...rest, type: 'checkbox' };
+        }
+        case 'date':
+            return { ...base, type: 'date' };
+        case 'datetime':
+            // `YYYY-MM-DDTHH:MM`, the value the service stores for a datetime field.
+            return { ...base, type: 'datetime' };
+        case 'enum': {
+            if (field.values.length > MAX_OPTIONS)
+                return null;
+            return {
+                ...base,
+                type: 'select',
+                placeholder: `Select ${label.toLowerCase()}`,
+                options: field.values.map((value) => ({ value, label: field.labels?.[value] ?? value })),
+            };
+        }
+        case 'email':
+            return { ...base, type: 'email' };
+        case 'url':
+            // The service accepts http and https (G121).
+            return { ...base, type: 'url', placeholder: 'https://', protocols: ['http', 'https'] };
+        case 'phone':
+            return { ...base, type: 'text' };
+        case 'tags':
+            return { ...base, type: 'tags', maxItems: field.maxItems };
+        case 'persona': {
+            // An optional select offers Texuli's empty "None" choice (G118).
+            const options = personaOptions ? personaOptionsFor(personaOptions) : null;
+            if (!options)
+                return null;
+            return {
+                ...base,
+                type: 'select',
+                placeholder: `Select ${label.toLowerCase()}`,
+                options,
+            };
+        }
+        default:
+            return null;
+    }
+}
+/** A stored value → the value its Texuli control holds. */
+function toFormValue(field, value) {
+    switch (field.kind) {
+        case 'money':
+            return typeof value === 'number' && Number.isFinite(value) ? value / 100 : null;
+        case 'number':
+        case 'integer':
+            return typeof value === 'number' && Number.isFinite(value) ? value : null;
+        case 'boolean':
+            return value === true;
+        case 'date':
+            return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}/.test(value)
+                ? value.slice(0, 10)
+                : null;
+        case 'datetime': {
+            // The UTC wall time (`YYYY-MM-DDTHH:MM`) of the stored instant, the same on every machine.
+            if (typeof value !== 'string' || !/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}/.test(value))
+                return null;
+            const date = new Date(value);
+            return Number.isNaN(date.getTime()) ? null : date.toISOString().slice(0, 16);
+        }
+        case 'enum':
+            return typeof value === 'string' && field.values.includes(value) ? value : null;
+        case 'persona':
+            return typeof value === 'string' && value ? value : null;
+        case 'tags':
+            return Array.isArray(value)
+                ? value.filter((tag) => typeof tag === 'string')
+                : [];
+        case 'json':
+            if (value === null || value === undefined)
+                return '';
+            return typeof value === 'string' ? value : JSON.stringify(value, null, 2);
+        default:
+            return typeof value === 'string' ? value : value == null ? '' : String(value);
+    }
+}
+/** A hosted field's starting value (any JSON its host control holds). */
+function toHostedValue(field, value) {
+    if (value !== undefined && value !== null)
+        return value;
+    return field.kind === 'boolean' ? false : field.kind === 'tags' ? [] : null;
+}
+/** A submitted Texuli value → the entity service input value. */
+function fromFormValue(field, value) {
+    switch (field.kind) {
+        case 'money':
+            return typeof value === 'number' && Number.isFinite(value) ? Math.round(value * 100) : null;
+        case 'persona':
+            return typeof value === 'string' && value !== '' && value !== UNASSIGNED_OPTION
+                ? value
+                : null;
+        case 'json':
+            return typeof value === 'string' && value.trim() !== '' ? value : null;
+        case 'datetime':
+            // Texuli edits the stored instant's UTC wall time (`toFormValue`), so it goes back as UTC.
+            return typeof value === 'string' && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}$/.test(value)
+                ? `${value}:00.000Z`
+                : typeof value === 'string' && value !== ''
+                    ? value
+                    : null;
+        case 'enum':
+        case 'date':
+            return typeof value === 'string' && value !== '' ? value : null;
+        default:
+            return value === undefined ? null : value;
+    }
+}
+/**
+ * Map an entity to a `@texuli/forms` schema plus the value converters for
+ * the fields Texuli paints. Pure and deterministic.
+ */
+export function entityFormModel(entity, options = {}) {
+    const mode = options.mode ?? 'create';
+    const fields = [];
+    const painted = [];
+    const hosted = [];
+    const names = new Map();
+    const byName = new Map();
+    entity.fields.forEach((field, index) => {
+        const name = schemaName(field, index);
+        names.set(inputProperty(field), name);
+        byName.set(name, field);
+        const mapped = paintField(field, name, options.personaOptions);
+        const emitted = mapped ?? customField(field, name);
+        fields.push(options.readOnly ? { ...emitted, when: READ_ONLY } : emitted);
+        (mapped ? painted : hosted).push(field);
+    });
+    const title = truncate(options.title ?? `${mode === 'create' ? 'New' : 'Edit'} ${entityNoun(entity)}`, 200);
+    const schema = {
+        title,
+        ...(options.submitLabel ? { submitLabel: truncate(options.submitLabel, 200) } : {}),
+        fields,
+    };
+    const isHosted = (field) => hosted.includes(field);
+    return {
+        schema,
+        painted,
+        hosted,
+        names,
+        fieldFor: (name) => byName.get(name),
+        toFormValues(row) {
+            const values = {};
+            for (const field of entity.fields) {
+                const key = inputProperty(field);
+                const name = names.get(key) ?? key;
+                const convert = isHosted(field) ? toHostedValue : toFormValue;
+                if (row && key in row)
+                    values[name] = convert(field, row[key]);
+                else if (mode === 'create' && 'default' in field && field.default !== undefined) {
+                    values[name] = convert(field, field.default);
+                }
+                else
+                    values[name] = convert(field, null);
+            }
+            return values;
+        },
+        fromFormValues(values) {
+            const input = {};
+            for (const field of entity.fields) {
+                const key = inputProperty(field);
+                const name = names.get(key) ?? key;
+                if (!Object.hasOwn(values, name))
+                    continue;
+                input[key] = isHosted(field) ? (values[name] ?? null) : fromFormValue(field, values[name]);
+            }
+            return input;
+        },
+    };
+}

package/dist/generator-version.d.ts

@@ -0,0 +1,11 @@
+import type { Blueprint } from './schema.ts';
+/**
+ * The world generator's version, apart from the generator itself: the
+ * runtime definition needs it synchronously, while the generator
+ * (`@protoyard/blueprint/generator`) loads lazily when a scenario seeds.
+ */
+/** Bump when the same blueprint + seed can produce a different world shape. */
+export declare const BLUEPRINT_GENERATOR_SDK = 6;
+/** Stable hash of a blueprint's generative surface (entities, fields, features). */
+export declare function hashBlueprint(blueprint: Blueprint): number;
+export declare function blueprintGeneratorVersion(blueprint: Blueprint): number;