@beechcms/core 0.8.1 → 0.9.0

package/dist/engine/seeds/tag-options.js

@@ -0,0 +1,111 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { cleanString, isPlainObject } from '../validation/primitives.js';
+import { normalizeTagValue, TAG_MAX_LENGTH, TAG_OPTIONS_MAX_COUNT } from './tag-value.js';
+/** Accepted option color format: 6-digit hex, the value `<input type="color">` emits. */
+export const TAG_OPTION_COLOR_RE = /^#[0-9a-fA-F]{6}$/;
+/** True only for a `tags` branch with `multiple === false`. Omitted `multiple` on `tags` means multiple choice. */
+export function isSingleChoiceTags(branch) {
+    return branch.type === 'tags' && branch.multiple === false;
+}
+/** Option values in declared order; `[]` when the branch has no options. */
+export function tagOptionValues(branch) {
+    return (branch.options ?? []).map(option => option.value);
+}
+/** The option whose `value` equals `value` exactly, or `undefined`. */
+export function findTagOption(branch, value) {
+    return branch.options?.find(option => option.value === value);
+}
+/** Issues for one option entry; `seenValues` accumulates the values already declared on the branch. */
+function optionEntryIssues(prefix, entry, index, seenValues) {
+    if (typeof entry === 'string') {
+        return [`${prefix}option #${index} must be an object { value, color }, not a plain string.`];
+    }
+    if (!isPlainObject(entry)) {
+        return [`${prefix}option #${index} must be an object { value, color }.`];
+    }
+    const issues = [];
+    const { value, color } = entry;
+    const validValue = typeof value === 'string' && value !== '' && value === cleanString(value);
+    if (!validValue) {
+        issues.push(`${prefix}option #${index} value must be a non-empty string without leading or trailing whitespace.`);
+    }
+    else {
+        const normalized = normalizeTagValue(value);
+        if (!normalized.ok) {
+            issues.push(normalized.reason === 'too-long'
+                ? `${prefix}option '${value.slice(0, 40)}' value is too long (max ${TAG_MAX_LENGTH} characters).`
+                : `${prefix}option #${index} value is not valid text (lone surrogate).`);
+        }
+        else if (normalized.value !== value) {
+            issues.push(`${prefix}option #${index} value must already be normalized: no invisible or control characters, `
+                + `single spaces, Unicode NFC (use ${JSON.stringify(normalized.value)}).`);
+        }
+        else if (seenValues.has(value)) {
+            issues.push(`${prefix}duplicate option value '${value}'.`);
+        }
+        else {
+            seenValues.add(value);
+        }
+    }
+    if (typeof color !== 'string' || !TAG_OPTION_COLOR_RE.test(color)) {
+        const optionLabel = validValue ? `'${value}'` : `#${index}`;
+        issues.push(`${prefix}option ${optionLabel} color must be a hex color #RRGGBB (got '${String(color)}').`);
+    }
+    return issues;
+}
+function branchTagOptionsIssues(prefix, branch) {
+    const raw = branch;
+    const issues = [];
+    if (raw.options !== undefined) {
+        if (branch.type === 'text') {
+            return [
+                `${prefix}options are not supported on type 'text'. `
+                    + `Use type 'tags' with options (add multiple: false for a single choice).`,
+            ];
+        }
+        if (branch.type !== 'tags') {
+            return [`${prefix}options are only supported on type 'tags' (got '${String(branch.type)}').`];
+        }
+    }
+    if (branch.type === 'tags') {
+        if (raw.multiple !== undefined && typeof raw.multiple !== 'boolean') {
+            issues.push(`${prefix}multiple must be a boolean.`);
+        }
+        if (raw.options !== undefined) {
+            if (!Array.isArray(raw.options) || raw.options.length === 0) {
+                issues.push(`${prefix}options must be a non-empty array of { value, color } objects.`);
+            }
+            else if (raw.options.length > TAG_OPTIONS_MAX_COUNT) {
+                issues.push(`${prefix}options must contain at most ${TAG_OPTIONS_MAX_COUNT} entries (got ${raw.options.length}).`);
+            }
+            else {
+                const seenValues = new Set();
+                raw.options.forEach((entry, index) => {
+                    issues.push(...optionEntryIssues(prefix, entry, index, seenValues));
+                });
+            }
+        }
+    }
+    return issues;
+}
+/**
+ * Seed-definition issues for `options` / `multiple` on this branch AND, recursively, its repeater sub-fields.
+ * Pure, never throws, works on untyped input (stored JSON may carry any shape). `[]` = valid.
+ */
+export function tagOptionsIssues(branch) {
+    const issues = branchTagOptionsIssues(`branch '${branch.alias}': `, branch);
+    const subFields = Array.isArray(branch.fields) ? branch.fields : [];
+    for (const sub of subFields) {
+        issues.push(...subFieldIssues(branch.alias, sub));
+    }
+    return issues;
+}
+function subFieldIssues(parentAlias, sub) {
+    const issues = branchTagOptionsIssues(`branch '${parentAlias}': sub-field '${sub.alias}': `, sub);
+    const nested = Array.isArray(sub.fields) ? sub.fields : [];
+    for (const child of nested) {
+        issues.push(...subFieldIssues(sub.alias, child));
+    }
+    return issues;
+}

package/dist/engine/seeds/tag-value.d.ts

@@ -0,0 +1,31 @@
+/** Max tags stored in one `tags` field. Tags flag small things; more than this stops being a label set. */
+export declare const TAG_MAX_COUNT = 10;
+/** Max user-perceived characters (grapheme clusters) in one tag, so one emoji or `é` counts as 1. */
+export declare const TAG_MAX_LENGTH = 25;
+/** Hard UTF-8 byte ceiling per tag: bounds stacked combining marks ("zalgo") that fit in 25 graphemes. */
+export declare const TAG_MAX_BYTES = 100;
+/** Max options a closed-vocabulary `tags` branch may declare. */
+export declare const TAG_OPTIONS_MAX_COUNT = 50;
+/** Array size accepted before cleaning, so blanks the cleaner drops do not eat the real budget. */
+export declare const TAG_RAW_MAX_COUNT = 50;
+/** Why a tag value cannot be stored. */
+export type TagValueRejection = 'ill-formed' | 'too-long';
+/** Outcome of {@link normalizeTagValue}: the canonical value (possibly `''`), or why it was rejected. */
+export type TagValueResult = {
+    readonly ok: true;
+    readonly value: string;
+} | {
+    readonly ok: false;
+    readonly reason: TagValueRejection;
+};
+/**
+ * Canonical form of one tag, the single rule shared by payload validation, seed option validation and filters:
+ * invisible and control characters removed (an emoji-gluing joiner survives), every whitespace run (tab, newline,
+ * NBSP, line separator…) collapsed to one space, trimmed, Unicode NFC. Case is preserved (`Foo` ≠ `foo`).
+ *
+ * `ok: true` with `''` means the tag was blank after cleaning: callers decide whether to drop or reject it.
+ * Rejected, never repaired: a lone UTF-16 surrogate (not valid UTF-8) and a value over
+ * {@link TAG_MAX_LENGTH} characters or {@link TAG_MAX_BYTES} bytes. Pure, never throws.
+ */
+export declare function normalizeTagValue(raw: string): TagValueResult;
+//# sourceMappingURL=tag-value.d.ts.map

package/dist/engine/seeds/tag-value.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tag-value.d.ts","sourceRoot":"","sources":["../../../src/engine/seeds/tag-value.ts"],"names":[],"mappings":"AAKA,2GAA2G;AAC3G,eAAO,MAAM,aAAa,KAAK,CAAA;AAC/B,qGAAqG;AACrG,eAAO,MAAM,cAAc,KAAK,CAAA;AAChC,0GAA0G;AAC1G,eAAO,MAAM,aAAa,MAAM,CAAA;AAChC,iEAAiE;AACjE,eAAO,MAAM,qBAAqB,KAAK,CAAA;AACvC,mGAAmG;AACnG,eAAO,MAAM,iBAAiB,KAAK,CAAA;AAgBnC,wCAAwC;AACxC,MAAM,MAAM,iBAAiB,GAAG,YAAY,GAAG,UAAU,CAAA;AAEzD,yGAAyG;AACzG,MAAM,MAAM,cAAc,GACtB;IAAE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAAC,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAA;CAAE,GAC7C;IAAE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IAAC,QAAQ,CAAC,MAAM,EAAE,iBAAiB,CAAA;CAAE,CAAA;AAM9D;;;;;;;;GAQG;AACH,wBAAgB,iBAAiB,CAAC,GAAG,EAAE,MAAM,GAAG,cAAc,CAc7D"}

package/dist/engine/seeds/tag-value.js

@@ -0,0 +1,51 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { byteLength, stripControlChars } from '../validation/primitives.js';
+/** Max tags stored in one `tags` field. Tags flag small things; more than this stops being a label set. */
+export const TAG_MAX_COUNT = 10;
+/** Max user-perceived characters (grapheme clusters) in one tag, so one emoji or `é` counts as 1. */
+export const TAG_MAX_LENGTH = 25;
+/** Hard UTF-8 byte ceiling per tag: bounds stacked combining marks ("zalgo") that fit in 25 graphemes. */
+export const TAG_MAX_BYTES = 100;
+/** Max options a closed-vocabulary `tags` branch may declare. */
+export const TAG_OPTIONS_MAX_COUNT = 50;
+/** Array size accepted before cleaning, so blanks the cleaner drops do not eat the real budget. */
+export const TAG_RAW_MAX_COUNT = 50;
+/**
+ * Invisible or layout-altering code points that render as nothing but make two tags differ:
+ * C1 controls, soft hyphen, Mongolian vowel separator, zero-width space/non-joiner, LRM/RLM,
+ * bidi embeddings and isolates (spoofing), word joiner and invisible operators, BOM, and the
+ * Unicode "tag" block (invisible payloads). The zero-width joiner is handled by {@link STRAY_JOINER_RE}.
+ */
+const INVISIBLE_CHARS_RE = /[\u0080-\u009F\u00AD\u180E\u200B\u200C\u200E\u200F\u202A-\u202E\u2060-\u206F\uFEFF\u{E0000}-\u{E007F}]/gu;
+/** Zero-width joiner not gluing two emoji pictographs; between two (family, profession emoji) it is meaningful and kept. */
+const STRAY_JOINER_RE = /(?<!\p{Extended_Pictographic}\uFE0F?)\u200D|\u200D(?!\p{Extended_Pictographic})/gu;
+const LONE_SURROGATE_RE = /[\uD800-\uDBFF](?![\uDC00-\uDFFF])|(?<![\uD800-\uDBFF])[\uDC00-\uDFFF]/;
+const UNICODE_WHITESPACE_RUN_RE = /\s+/g;
+const graphemeSegmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+function graphemeCount(input) {
+    return [...graphemeSegmenter.segment(input)].length;
+}
+/**
+ * Canonical form of one tag, the single rule shared by payload validation, seed option validation and filters:
+ * invisible and control characters removed (an emoji-gluing joiner survives), every whitespace run (tab, newline,
+ * NBSP, line separator…) collapsed to one space, trimmed, Unicode NFC. Case is preserved (`Foo` ≠ `foo`).
+ *
+ * `ok: true` with `''` means the tag was blank after cleaning: callers decide whether to drop or reject it.
+ * Rejected, never repaired: a lone UTF-16 surrogate (not valid UTF-8) and a value over
+ * {@link TAG_MAX_LENGTH} characters or {@link TAG_MAX_BYTES} bytes. Pure, never throws.
+ */
+export function normalizeTagValue(raw) {
+    if (LONE_SURROGATE_RE.test(raw))
+        return { ok: false, reason: 'ill-formed' };
+    const value = stripControlChars(raw)
+        .replaceAll(INVISIBLE_CHARS_RE, '')
+        .replaceAll(STRAY_JOINER_RE, '')
+        .replaceAll(UNICODE_WHITESPACE_RUN_RE, ' ')
+        .trim()
+        .normalize('NFC');
+    if (byteLength(value) > TAG_MAX_BYTES || graphemeCount(value) > TAG_MAX_LENGTH) {
+        return { ok: false, reason: 'too-long' };
+    }
+    return { ok: true, value };
+}

package/dist/engine/types.d.ts

@@ -6,6 +6,7 @@
  */
 import type { FileAccept } from '../media/file-types.js';
 import type { DashboardView } from '../dashboard-layout/view-authorization.js';
+import type { LocaleConfig } from './localization/localization.js';
 /** All supported field value types for a Branch. */
 export type BranchType = 'text' | 'number' | 'boolean' | 'json' | 'date' | 'richtext' | 'file' | 'tags' | 'relation' | 'repeater';
 /** Specialized configuration for a branch of type 'number'. */
@@ -57,6 +58,16 @@ export interface ActorContext {
     userId?: string;
     role?: string;
 }
+/** One entry of a `tags` branch's closed vocabulary. Array order is significant (menu, kanban columns, sort). */
+export interface TagOption {
+    /**
+     * Stored value and identity. Unique within the branch; compared exactly (case-sensitive, never trimmed).
+     * Must already be in canonical form (`normalizeTagValue(value).value === value`) and at most `TAG_MAX_LENGTH` characters.
+     */
+    value: string;
+    /** Presentation-only color, `#RRGGBB`. Lives in the seed only — never persisted in entries. */
+    color: string;
+}
 /** Branch: definition of a single field. `alias` is the SQL column name. */
 export interface Branch {
     /**
@@ -83,16 +94,19 @@ export interface Branch {
      */
     format?: 'plain' | 'markdown' | 'html' | 'date' | 'datetime' | 'asset-list';
     /**
-     * Optional cardinality for media fields:
-     * - false/undefined: single asset (string URL)
-     * - true: asset list (string[] URL)
+     * Cardinality:
+     * - `file`: false/undefined → single URL; true → URL list.
+     * - `relation`: false/undefined → FK column; true → junction table.
+     * - `tags`: undefined/true → multiple choice (default); false → at most one value. The value is always an array.
      */
     multiple?: boolean;
     /**
-     * Predefined vocabulary for tag/select/multiselect fields.
-     * Static list defined in the Seed (not persisted to the DB).
+     * Closed vocabulary — valid ONLY on `tags` (any other type is a fatal seed error).
+     * When present: non-empty, at most `TAG_OPTIONS_MAX_COUNT` entries, unique canonical values, `#RRGGBB` colors;
+     * written values must be one of the option values.
+     * Static seed metadata, never persisted in entries.
      */
-    options?: string[];
+    options?: TagOption[];
     /** Required on create — generates NOT NULL in generateCreateTable. */
     requiredOnCreate?: boolean;
     /** Required on update. */
@@ -123,6 +137,15 @@ export interface Branch {
     numberOptions?: NumberFieldOptions;
     /** Advanced options for file fields. Ignored if type !== 'file'. */
     fileOptions?: FileFieldOptions;
+    /**
+     * Field-level localization. When true, the branch's existing column stores a locale dictionary
+     * (`{"it": "Scarpa", "en": "Shoe"}`) instead of a single value. Metadata-only: toggling it never
+     * emits DDL and never rewrites rows — values written before the toggle stay readable as-is.
+     * Valid only on top-level `text | richtext | json` branches with `plain` storage (not
+     * `confidential` / `restricted`); never on repeater sub-fields. Enforced by seed-validation.ts
+     * (Fatal 17). Default: false.
+     */
+    localized?: boolean;
     /**
      * Slug of the referenced Seed (without the `content_` prefix).
      * REQUIRED when `type === 'relation'`. Ignored otherwise.
@@ -213,6 +236,13 @@ export interface Seed {
      * Default: false.
      */
     allowDrafts?: boolean;
+    /**
+     * Enables the Trash for this content type. When true, `content_{slug}` carries a
+     * `deleted_at INTEGER NULL` column, `DELETE` becomes a reversible soft delete, and every
+     * read excludes trashed rows unless the caller opts in via `SelectOptions.trashed`.
+     * Default: false.
+     */
+    softDelete?: boolean;
     /**
      * Alias of the branch used as the entry's human-readable name (e.g. "title", "name", "author").
      * Required — UIs use it for display without heuristics.
@@ -235,7 +265,7 @@ export interface Seed {
 /** Comparison/matching operator applied by a filter condition. */
 export type FilterOperator = 'eq' | 'neq' | 'gt' | 'gte' | 'lt' | 'lte' | 'contains' | 'not_contains' | 'starts_with' | 'ends_with' | 'is_empty' | 'is_not_empty' | 'in' | 'not_in' | 'has_tag' | 'has_any_tag' | 'has_all_tags';
 /** Declared value type of a filtered column, used to normalize/coerce filter values before binding. */
-export type FilterType = 'text' | 'number' | 'date' | 'boolean' | 'tags' | 'select' | 'system' | 'json';
+export type FilterType = 'text' | 'number' | 'date' | 'boolean' | 'tags' | 'select' | 'system' | 'json' | 'repeater';
 /** A single operator + value pair applied to a FilterGroup's column. */
 export interface FilterCondition {
     /** Operator to apply. */
@@ -251,6 +281,20 @@ export interface FilterGroup {
     /** Conditions applied to this column, ANDed together. */
     conditions: FilterCondition[];
 }
+/**
+ * Soft-delete visibility for a read.
+ *  - 'active'  (default) — only rows with `deleted_at IS NULL`
+ *  - 'trashed'           — only rows with `deleted_at IS NOT NULL` (the Trash view)
+ *  - 'any'               — no predicate (restore/purge lookups, reconciliation)
+ * Ignored entirely for seeds without `softDelete: true`.
+ */
+export type TrashedMode = 'active' | 'trashed' | 'any';
+/** The language a read resolves localized branches to (consumed by `buildSelectQuery`). */
+export interface SelectLocale {
+    /** Locale that filters and ORDER BY compare in. Must match `LOCALE_CODE_RE`; the builder throws otherwise. */
+    readonly code: string;
+    readonly config: LocaleConfig;
+}
 export interface SelectOptions {
     /** Filter groups. Joined by `filterLogic` (default AND); conditions within a group are always ANDed. */
     filters?: FilterGroup[];
@@ -268,6 +312,8 @@ export interface SelectOptions {
     };
     /** Filters by status. null = no status filter. */
     status?: string | null;
+    /** Soft-delete visibility. Defaults to 'active': omitting it can never leak a trashed row. */
+    trashed?: TrashedMode;
     /** Full-text search — uses FTS5 if the seed has indexable richtext/text branches. */
     search?: string;
     /** Column projection. Empty = SELECT *. */
@@ -284,6 +330,12 @@ export interface SelectOptions {
      * while keeping the join/where clauses intact for accurate counts.
      */
     isCount?: boolean;
+    /**
+     * When set, filters and ORDER BY on localized branches compare the value resolved to `locale.code`
+     * (requested → default → first stored translation → legacy raw value) instead of the stored JSON.
+     * Absent: every column is compared raw, exactly as before localization existed.
+     */
+    locale?: SelectLocale;
 }
 /** SQL string paired with its ordered parameter bindings, ready for a D1 `.bind(...)` call. */
 export interface ParameterizedQuery {

package/dist/engine/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":"AAGA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,wBAAwB,CAAA;AACxD,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,2CAA2C,CAAA;AAE9E,oDAAoD;AACpD,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,UAAU,CAAA;AAEjI,+DAA+D;AAC/D,MAAM,WAAW,kBAAkB;IAEjC,gDAAgD;IAChD,MAAM,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,YAAY,GAAG,SAAS,CAAA;IAC1D,uFAAuF;IACvF,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,oDAAoD;IACpD,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,qEAAqE;IACrE,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,gEAAgE;IAChE,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,kEAAkE;IAClE,QAAQ,CAAC,EAAE,OAAO,CAAA;IAGlB,0EAA0E;IAC1E,OAAO,CAAC,EAAE,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,SAAS,CAAA;IAGnD,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,6BAA6B;IAC7B,GAAG,CAAC,EAAE,MAAM,CAAA;IACZ,wEAAwE;IACxE,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,6DAA6D;AAC7D,MAAM,WAAW,gBAAgB;IAC/B;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,UAAU,CAAA;IACnB;;;;;OAKG;IACH,OAAO,CAAC,EAAE,MAAM,CAAA;CACjB;AAED,sFAAsF;AACtF,MAAM,MAAM,kBAAkB,GAAG,QAAQ,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CAAA;AAEtF,wFAAwF;AACxF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,QAAQ,GAAG,eAAe,GAAG,QAAQ,CAAA;IAC3C,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;CACd;AAED,4EAA4E;AAC5E,MAAM,WAAW,MAAM;IACrB;;;;;;;;OAQG;IACH,EAAE,EAAE,MAAM,CAAA;IACV,uGAAuG;IACvG,KAAK,EAAE,MAAM,CAAA;IACb,wBAAwB;IACxB,KAAK,EAAE,MAAM,CAAA;IACb,2GAA2G;IAC3G,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,kBAAkB;IAClB,IAAI,EAAE,UAAU,CAAA;IAChB;;;OAGG;IACH,MAAM,CAAC,EAAE,OAAO,GAAG,UAAU,GAAG,MAAM,GAAG,MAAM,GAAG,UAAU,GAAG,YAAY,CAAA;IAC3E;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB;;;OAGG;IACH,OAAO,CAAC,EAAE,MAAM,EAAE,CAAA;IAClB,sEAAsE;IACtE,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B,0BAA0B;IAC1B,gBAAgB,CAAC,EAAE,OAAO,CAAA;IAC1B;;;OAGG;IACH,QAAQ,CAAC,EAAE;QACT,2DAA2D;QAC3D,cAAc,CAAC,EAAE,kBAAkB,GAAG,QAAQ,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CAAA;QAC3F,iDAAiD;QACjD,OAAO,CAAC,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,GAAG,kBAAkB,GAAG,QAAQ,GAAG,UAAU,GAAG,cAAc,GAAG,YAAY,CAAA;QACnH,mEAAmE;QACnE,UAAU,CAAC,EAAE,MAAM,GAAG,QAAQ,GAAG,QAAQ,CAAA;QACzC,gFAAgF;QAChF,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,yFAAyF;QACzF,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,uFAAuF;QACvF,IAAI,CAAC,EAAE,OAAO,CAAA;QACd,4EAA4E;QAC5E,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,wIAAwI;QACxI,UAAU,CAAC,EAAE,OAAO,CAAA;KACrB,CAAA;IACD,wEAAwE;IACxE,aAAa,CAAC,EAAE,kBAAkB,CAAA;IAClC,oEAAoE;IACpE,WAAW,CAAC,EAAE,gBAAgB,CAAA;IAE9B;;;;OAIG;IACH,UAAU,CAAC,EAAE,MAAM,CAAA;IAEnB;;;;;;;;;OASG;IACH,QAAQ,CAAC,EAAE,SAAS,GAAG,UAAU,GAAG,UAAU,CAAA;IAE9C;;;;;;OAMG;IACH,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IAEjB;;;;;;;;;;OAUG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;IAEjB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,6GAA6G;AAC7G,MAAM,WAAW,mBAAmB;IAClC,uFAAuF;IACvF,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,8EAA8E;IAC9E,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,gEAAgE;IAChE,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,oDAAoD;IACpD,MAAM,CAAC,EAAE,OAAO,CAAA;IAChB,gDAAgD;IAChD,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,gEAAgE;IAChE,QAAQ,CAAC,EAAE;QACT,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,MAAM,CAAC,EAAE,OAAO,CAAA;QAChB,UAAU,CAAC,EAAE,OAAO,CAAA;KACrB,CAAA;IACD;;;;OAIG;IACH,KAAK,CAAC,EAAE,aAAa,EAAE,CAAA;CACxB;AAED,iDAAiD;AACjD,MAAM,WAAW,IAAI;IACnB,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAA;IACZ,yBAAyB;IACzB,KAAK,EAAE,MAAM,CAAA;IACb,0DAA0D;IAC1D,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,qFAAqF;IACrF,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,6FAA6F;IAC7F,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,8FAA8F;IAC9F,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB;;;;OAIG;IACH,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB;;;OAGG;IACH,gBAAgB,EAAE,MAAM,CAAA;IACxB;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB,+BAA+B;IAC/B,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,8EAA8E;IAC9E,SAAS,CAAC,EAAE,mBAAmB,CAAA;IAC/B;;wGAEoG;IACpG,MAAM,CAAC,EAAE,OAAO,CAAA;CACjB;AAID,kEAAkE;AAClE,MAAM,MAAM,cAAc,GACtB,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,IAAI,GACJ,KAAK,GACL,UAAU,GACV,cAAc,GACd,aAAa,GACb,WAAW,GACX,UAAU,GACV,cAAc,GACd,IAAI,GACJ,QAAQ,GACR,SAAS,GACT,aAAa,GACb,cAAc,CAAA;AAElB,uGAAuG;AACvG,MAAM,MAAM,UAAU,GAAG,MAAM,GAAG,QAAQ,GAAG,MAAM,GAAG,SAAS,GAAG,MAAM,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAA;AAEvG,wEAAwE;AACxE,MAAM,WAAW,eAAe;IAC9B,yBAAyB;IACzB,EAAE,EAAE,cAAc,CAAA;IAClB,sGAAsG;IACtG,KAAK,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,GAAG,MAAM,EAAE,GAAG,MAAM,EAAE,CAAA;CAC9D;AAED,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,MAAM,EAAE,MAAM,CAAA;IACd,uEAAuE;IACvE,IAAI,EAAE,UAAU,CAAA;IAChB,yDAAyD;IACzD,UAAU,EAAE,eAAe,EAAE,CAAA;CAC9B;AAED,MAAM,WAAW,aAAa;IAC5B,wGAAwG;IACxG,OAAO,CAAC,EAAE,WAAW,EAAE,CAAA;IACvB,sEAAsE;IACtE,WAAW,CAAC,EAAE,KAAK,GAAG,IAAI,CAAA;IAC1B,oEAAoE;IACpE,OAAO,CAAC,EAAE;QAAE,MAAM,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,KAAK,GAAG,MAAM,CAAA;KAAE,CAAA;IACjD,+BAA+B;IAC/B,UAAU,CAAC,EAAE;QAAE,KAAK,EAAE,MAAM,CAAC;QAAC,MAAM,EAAE,MAAM,CAAA;KAAE,CAAA;IAC9C,kDAAkD;IAClD,MAAM,CAAC,EAAE,MAAM,GAAG,IAAI,CAAA;IACtB,qFAAqF;IACrF,MAAM,CAAC,EAAE,MAAM,CAAA;IACf,2CAA2C;IAC3C,MAAM,CAAC,EAAE,MAAM,EAAE,CAAA;IACjB;kFAC8E;IAC9E,WAAW,CAAC,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,YAAY,EAAE,MAAM,CAAA;KAAE,CAAA;IACxD;;;;OAIG;IACH,OAAO,CAAC,EAAE,OAAO,CAAA;CAClB;AAED,+FAA+F;AAC/F,MAAM,WAAW,kBAAkB;IACjC,2DAA2D;IAC3D,GAAG,EAAE,MAAM,CAAA;IACX,sDAAsD;IACtD,QAAQ,EAAE,CAAC,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC,EAAE,CAAA;CAC/C"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/engine/types.ts"],"names":[],"mappings":"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"}

package/dist/engine/validation/cache.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/cache.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAsB,IAAI,EAAwC,MAAM,aAAa,CAAA;AAEjG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAgIjD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CAsCjH"}
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/cache.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAsB,IAAI,EAAwC,MAAM,aAAa,CAAA;AAEjG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AA2IjD;;;;;;GAMG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,GAAG,CAAC,CAAC,SAAS,CAAC,MAAM,CAAC,MAAM,EAAE,CAAC,CAAC,UAAU,CAAC,CAAC,CA+CjH"}

package/dist/engine/validation/cache.js

@@ -1,7 +1,9 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
 import { z } from 'zod';
-import { schemaForBranch } from './schema-builders.js';
+import { isSingleChoiceTags, tagOptionValues } from '../seeds/tag-options.js';
+import { isLocalizedBranch } from '../localization/localization.js';
+import { schemaForBranch, localizedSchema } from './schema-builders.js';
 /** Max entries kept per cache map before evicting the least recently used. */
 const SEED_SCHEMA_CACHE_MAX_SIZE = 150;
 /** Cache storing compiled Zod schemas for relation-free seeds. */
@@ -54,7 +56,8 @@ function buildBranchFingerprint(branch) {
         a: branch.alias,
         t: branch.type,
         f: branch.format ?? null,
-        m: branch.multiple === true,
+        m: branch.type === 'tags' ? !isSingleChoiceTags(branch) : branch.multiple === true,
+        o: branch.options ? tagOptionValues(branch) : null,
         rc: branch.requiredOnCreate === true,
         ru: branch.requiredOnUpdate === true,
         n: branch.numberOptions ?? null,
@@ -62,6 +65,7 @@ function buildBranchFingerprint(branch) {
         mi: branch.minItems ?? null,
         ma: branch.maxItems ?? null,
         sub: branch.fields?.map(buildBranchFingerprint) ?? null,
+        lo: branch.localized === true,
     };
 }
 /**
@@ -88,6 +92,9 @@ function buildCacheKey(seed, options) {
         options.allowNull ? '1' : '0',
         options.enforceRequiredFields ? '1' : '0',
         String(options.maxTextLength),
+        options.localeConfig
+            ? `${options.localeConfig.defaultLocale}>${options.localeConfig.locales.join(',')}`
+            : '-',
     ].join('|');
 }
 /**
@@ -125,8 +132,17 @@ export function compileSeedSchema(seed, options) {
     const requiredFlag = options.operation === 'create' ? 'requiredOnCreate' : 'requiredOnUpdate';
     const shape = {};
     for (const branch of seed.branches) {
-        const branchSchema = schemaForBranch(branch, options);
-        const isRequired = branch[requiredFlag] && options.enforceRequiredFields;
+        const branchLocaleConfig = options.localeConfig && isLocalizedBranch(branch) ? options.localeConfig : undefined;
+        const branchSchema = branchLocaleConfig
+            ? localizedSchema(branch, options, branchLocaleConfig)
+            : schemaForBranch(branch, options);
+        // A localized branch uses patch semantics on update (buildLocalizedPatch omits it entirely when no
+        // locale was touched), so the object schema must accept the key being absent even when required —
+        // detectMissingRequired() checks the *value* (default-locale presence/emptiness) with full patch
+        // awareness; a non-optional key here would fail the whole payload's parse and silently drop every
+        // other submitted field with it.
+        const isPatchExempt = branchLocaleConfig != null && options.operation === 'update';
+        const isRequired = branch[requiredFlag] && options.enforceRequiredFields && !isPatchExempt;
         shape[branch.alias] = isRequired ? branchSchema : branchSchema.optional();
     }
     const compiled = z.object(shape).strict();

package/dist/engine/validation/index.d.ts

@@ -1,5 +1,8 @@
 import type { Seed } from '../types.js';
 import type { IIdGenerator } from '../../common/id-generator.js';
+import { type LocaleConfig } from '../localization/localization.js';
+import { isEffectivelyEmpty } from './emptiness.js';
+export { isEffectivelyEmpty };
 export { resolveFileOptions } from './file-branch.js';
 /**
  * @module Engine/Validation
@@ -58,6 +61,13 @@ export interface ValidateSeedPayloadOptions {
      * Do NOT pass a concrete class — inject via the middleware / factory.
      */
     idGenerator?: IIdGenerator;
+    /**
+     * Project language configuration. When provided, branches with `localized: true` accept a plain
+     * value (stored under `defaultLocale`) or a locale dictionary, and validate to a `LocalizedPatch`.
+     * When omitted, localized branches validate exactly like their base type — the pre-localization
+     * contract. `requiredOnCreate` / `requiredOnUpdate` then check the default locale only.
+     */
+    localeConfig?: LocaleConfig;
 }
 /**
  * The structured result returned by the seed payload validation process.
@@ -89,9 +99,10 @@ export type ResolvedOptions = {
     enforceRequiredFields: boolean;
     maxTextLength: number;
     idGenerator: IIdGenerator | undefined;
+    localeConfig: LocaleConfig | undefined;
 };
 /** Set of valid content status values. */
-declare const STATUS_VALUES: readonly ['draft', 'review', 'published'];
+declare const STATUS_VALUES: readonly ["draft", "review", "published"];
 /**
  * Validates and sanitizes a seed payload against its schema definition.
  *

package/dist/engine/validation/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAOhE,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAErD;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb,0GAA0G;IAC1G,QAAQ,EAAE,MAAM,CAAA;IAChB,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC/B;;;OAGG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAA;IACrC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;CAC3B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,+EAA+E;IAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,8FAA8F;IAC9F,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,4FAA4F;IAC5F,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,sEAAsE;IACtE,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,uFAAuF;IACvF,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC9B,2BAA2B,EAAE,OAAO,CAAA;IACpC,qBAAqB,EAAE,OAAO,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,YAAY,GAAG,SAAS,CAAA;CACtC,CAAA;AAKD,0CAA0C;AAC1C,QAAA,MAAM,aAAa,YAAI,OAAO,EAAE,QAAQ,EAAE,WAAW,CAAU,CAAA;AA+R/D;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,GAAE,0BAA+B,GACvC,yBAAyB,CAqD3B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAE5F"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/index.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,aAAa,CAAA;AACvC,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,8BAA8B,CAAA;AAChE,OAAO,EAAuC,KAAK,YAAY,EAAE,MAAM,iCAAiC,CAAA;AAExG,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAA;AAEnD,OAAO,EAAE,kBAAkB,EAAE,CAAA;AAG7B,OAAO,EAAE,kBAAkB,EAAE,MAAM,kBAAkB,CAAA;AAErD;;;;;;GAMG;AAEH;;GAEG;AACH,MAAM,WAAW,gBAAgB;IAC/B,6DAA6D;IAC7D,KAAK,EAAE,MAAM,CAAA;IACb,0GAA0G;IAC1G,QAAQ,EAAE,MAAM,CAAA;IAChB,kGAAkG;IAClG,QAAQ,EAAE,MAAM,CAAA;IAChB,uEAAuE;IACvE,OAAO,EAAE,MAAM,CAAA;CAChB;AAED;;GAEG;AACH,MAAM,WAAW,0BAA0B;IACzC;;;OAGG;IACH,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB;;;;OAIG;IACH,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC/B;;;OAGG;IACH,2BAA2B,CAAC,EAAE,OAAO,CAAA;IACrC;;;OAGG;IACH,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B;;;OAGG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;IAC1B;;;;;OAKG;IACH,YAAY,CAAC,EAAE,YAAY,CAAA;CAC5B;AAED;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;;OAGG;IACH,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,+EAA+E;IAC/E,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,8FAA8F;IAC9F,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,4FAA4F;IAC5F,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,sEAAsE;IACtE,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,uFAAuF;IACvF,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;GAEG;AACH,MAAM,MAAM,eAAe,GAAG;IAC5B,SAAS,EAAE,OAAO,CAAA;IAClB,SAAS,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC9B,2BAA2B,EAAE,OAAO,CAAA;IACpC,qBAAqB,EAAE,OAAO,CAAA;IAC9B,aAAa,EAAE,MAAM,CAAA;IACrB,WAAW,EAAE,YAAY,GAAG,SAAS,CAAA;IACrC,YAAY,EAAE,YAAY,GAAG,SAAS,CAAA;CACvC,CAAA;AAKD,0CAA0C;AAC1C,QAAA,MAAM,aAAa,2CAA4C,CAAA;AAyR/D;;;;;;;;;;;GAWG;AACH,wBAAgB,8BAA8B,CAC5C,IAAI,EAAE,IAAI,EACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAChC,OAAO,GAAE,0BAA+B,GACvC,yBAAyB,CA0D3B;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAE5F"}

package/dist/engine/validation/index.js

@@ -1,10 +1,10 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
 import { z } from 'zod';
-import { isRichtextEnvelopeV1 } from '../../content/richtext/richtext.js';
-import { cleanString, isPlainObject } from './primitives.js';
-import { isRichtextDocEmpty } from './richtext-sanitizer.js';
+import { isLocalizedBranch, toLocalizedPatch } from '../localization/localization.js';
 import { compileSeedSchema } from './cache.js';
+import { isEffectivelyEmpty } from './emptiness.js';
+export { isEffectivelyEmpty };
 // Re-export the public file-branch symbol so the barrel surface stays complete.
 export { resolveFileOptions } from './file-branch.js';
 /** Default maximum character length allowed for text and rich text branches. */
@@ -13,31 +13,6 @@ const DEFAULT_MAX_TEXT_LENGTH = 50_000;
 const STATUS_VALUES = ['draft', 'review', 'published'];
 /** Zod schema for content status enum validation. */
 const statusSchema = z.enum(STATUS_VALUES);
-/**
- * Checks if a value is effectively empty (e.g. null, undefined, empty string, empty array, or empty rich text).
- *
- * @param value - The value to check.
- * @param branchType - The type of the branch being checked.
- * @returns True if effectively empty, false otherwise.
- */
-function isEffectivelyEmpty(value, branchType) {
-    if (value === null || value === undefined)
-        return true;
-    if (typeof value === 'string')
-        return cleanString(value).length === 0;
-    if (Array.isArray(value))
-        return value.length === 0;
-    if (isPlainObject(value)) {
-        // Richtext envelope: delegate to the richtext emptiness check.
-        if (isRichtextEnvelopeV1(value))
-            return isRichtextDocEmpty(value.doc);
-        // Raw TipTap doc root: only delegate for richtext branches to avoid misclassifying generic json fields.
-        if (branchType === 'richtext' && value.type === 'doc')
-            return isRichtextDocEmpty(value);
-        return Object.keys(value).length === 0;
-    }
-    return false;
-}
 /**
  * Detects missing or empty required fields based on whether the operation is create or update.
  *
@@ -57,7 +32,13 @@ function detectMissingRequired(seed, rawPayload, filtered, parsedData, parseSucc
         const isRequired = op === 'create' ? branch.requiredOnCreate : branch.requiredOnUpdate;
         if (!isRequired)
             continue;
+        const isLocalizedUpdate = op === 'update' && options.localeConfig != null && isLocalizedBranch(branch);
         if (!Object.hasOwn(rawPayload, branch.alias)) {
+            // Localized branches use patch semantics on update: the dashboard omits the branch entirely
+            // when no locale was touched (see buildLocalizedPatch), which is equivalent to a patch that
+            // does not name the default locale — leave it as stored rather than flagging it missing.
+            if (isLocalizedUpdate)
+                continue;
             missing.push(branch.alias);
             details.push({
                 field: branch.alias,
@@ -67,7 +48,18 @@ function detectMissingRequired(seed, rawPayload, filtered, parsedData, parseSucc
             });
             continue;
         }
-        const candidate = parseSucceeded ? parsedData[branch.alias] : filtered[branch.alias];
+        const value = parseSucceeded ? parsedData[branch.alias] : filtered[branch.alias];
+        let candidate = value;
+        if (options.localeConfig && isLocalizedBranch(branch)) {
+            // A localized branch is present when its default locale is; other locales are optional (brief §4).
+            const { defaultLocale } = options.localeConfig;
+            const patch = toLocalizedPatch(value, options.localeConfig);
+            // An update that does not name the default locale leaves it as stored — the write path merges
+            // (applyLocalizedPatch) — so saving one translation cannot trip requiredOnUpdate.
+            if (op === 'update' && !Object.hasOwn(patch, defaultLocale))
+                continue;
+            candidate = patch[defaultLocale];
+        }
         if (isEffectivelyEmpty(candidate, branch.type)) {
             missing.push(branch.alias);
             details.push({
@@ -241,9 +233,8 @@ function processZodIssues(seed, issues, filtered, options) {
             continue;
         }
         // detectMissingRequired() already reports top-level required-and-missing branches;
-        // skip the redundant native invalid_type/undefined issue Zod v4 raises for the same field.
-        if (issue.code === 'invalid_type' &&
-            options.enforceRequiredFields &&
+        // skip redundant Zod issues when a required top-level field is omitted/undefined.
+        if (options.enforceRequiredFields &&
             issuePath.length === 1 &&
             valByPath === undefined) {
             continue;
@@ -290,6 +281,7 @@ export function validateAndSanitizeSeedPayload(seed, payload, options = {}) {
         enforceRequiredFields: options.enforceRequiredFields ?? true,
         maxTextLength: options.maxTextLength ?? DEFAULT_MAX_TEXT_LENGTH,
         idGenerator: options.idGenerator,
+        localeConfig: options.localeConfig,
     };
     const { filtered, unknown: preUnknown, details: preDetails } = splitUnknownAliases(seed, payload);
     const schema = compileSeedSchema(seed, resolved);
@@ -299,7 +291,11 @@ export function validateAndSanitizeSeedPayload(seed, payload, options = {}) {
     const dangerousFields = new Set();
     let data = {};
     if (parsed.success) {
-        data = { ...parsed.data };
+        for (const [key, value] of Object.entries(parsed.data)) {
+            if (value !== undefined) {
+                data[key] = value;
+            }
+        }
     }
     else {
         const zodOutcome = processZodIssues(seed, parsed.error.issues, filtered, resolved);

package/dist/engine/validation/primitives.d.ts

@@ -22,6 +22,18 @@ export declare function cleanString(input: string): string;
  * @returns True if the value is a plain object, false otherwise.
  */
 export declare function isPlainObject(input: unknown): input is Record<string, unknown>;
+/**
+ * Checks whether a JSON-like value nests deeper than `maxDepth`, without ever recursing
+ * past that bound. Safe to call on adversarial input BEFORE any operation (like
+ * `JSON.stringify`, which recurses unboundedly) that would otherwise overflow the call
+ * stack on a few thousand levels of nesting.
+ *
+ * @param value - The value to inspect.
+ * @param maxDepth - The maximum nesting depth allowed.
+ * @param depth - Current recursion depth (internal).
+ * @returns True if the value nests deeper than `maxDepth`.
+ */
+export declare function exceedsMaxDepth(value: unknown, maxDepth: number, depth?: number): boolean;
 /**
  * Measures the real UTF-8 byte length of a string, not UTF-16 code units.
  * `.length` undercounts multi-byte chars (CJK, emoji) by up to 4x, which matters

package/dist/engine/validation/primitives.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/primitives.ts"],"names":[],"mappings":"AAGA,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,QAAoD,CAAA;AAEpF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI9E;AAID;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}
+{"version":3,"file":"primitives.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/primitives.ts"],"names":[],"mappings":"AAGA,mEAAmE;AACnE,eAAO,MAAM,mBAAmB,QAAoD,CAAA;AAEpF;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEvD;AAED;;;;;GAKG;AACH,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEjD;AAED;;;;;;GAMG;AACH,wBAAgB,aAAa,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAI9E;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,EAAE,KAAK,SAAI,GAAG,OAAO,CASpF;AAID;;;;;;;GAOG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAEhD"}

package/dist/engine/validation/primitives.js

@@ -33,6 +33,28 @@ export function isPlainObject(input) {
     const proto = Object.getPrototypeOf(input);
     return proto === Object.prototype || proto === null;
 }
+/**
+ * Checks whether a JSON-like value nests deeper than `maxDepth`, without ever recursing
+ * past that bound. Safe to call on adversarial input BEFORE any operation (like
+ * `JSON.stringify`, which recurses unboundedly) that would otherwise overflow the call
+ * stack on a few thousand levels of nesting.
+ *
+ * @param value - The value to inspect.
+ * @param maxDepth - The maximum nesting depth allowed.
+ * @param depth - Current recursion depth (internal).
+ * @returns True if the value nests deeper than `maxDepth`.
+ */
+export function exceedsMaxDepth(value, maxDepth, depth = 0) {
+    if (depth > maxDepth)
+        return true;
+    if (Array.isArray(value)) {
+        return value.some((item) => exceedsMaxDepth(item, maxDepth, depth + 1));
+    }
+    if (isPlainObject(value)) {
+        return Object.values(value).some((item) => exceedsMaxDepth(item, maxDepth, depth + 1));
+    }
+    return false;
+}
 const byteLengthEncoder = new TextEncoder();
 /**
  * Measures the real UTF-8 byte length of a string, not UTF-16 code units.