@beechcms/core 0.8.0 → 0.9.0

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

@@ -0,0 +1,12 @@
+/**
+ * Checks if a value is effectively empty (e.g. null, undefined, empty string, empty array, or empty rich text).
+ *
+ * Shared by top-level required-field detection (`index.ts`) and repeater item validation
+ * (`schema-builders.ts`) so both tiers apply the same emptiness rule to required fields.
+ *
+ * @param value - The value to check.
+ * @param branchType - The type of the branch being checked.
+ * @returns True if effectively empty, false otherwise.
+ */
+export declare function isEffectivelyEmpty(value: unknown, branchType?: string): boolean;
+//# sourceMappingURL=emptiness.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"emptiness.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/emptiness.ts"],"names":[],"mappings":"AAOA;;;;;;;;;GASG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,OAAO,CAY/E"}

package/dist/engine/validation/emptiness.js

@@ -0,0 +1,33 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { isRichtextEnvelopeV1 } from '../../content/richtext/richtext.js';
+import { cleanString, isPlainObject } from './primitives.js';
+import { isRichtextDocEmpty } from './richtext-sanitizer.js';
+/**
+ * Checks if a value is effectively empty (e.g. null, undefined, empty string, empty array, or empty rich text).
+ *
+ * Shared by top-level required-field detection (`index.ts`) and repeater item validation
+ * (`schema-builders.ts`) so both tiers apply the same emptiness rule to required fields.
+ *
+ * @param value - The value to check.
+ * @param branchType - The type of the branch being checked.
+ * @returns True if effectively empty, false otherwise.
+ */
+export 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;
+}

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,6 +99,7 @@ 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"];

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,2CAA4C,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.

package/dist/engine/validation/richtext-sanitizer.d.ts

@@ -12,7 +12,7 @@ interface RichtextSanitizeResult {
 }
 /**
  * Main entrance helper to sanitize rich text, handling both v1 envelope formats and raw JSON payloads.
- * String-form input is rejected (JSON-only). Byte size is fail-fast checked before the sanitizing walk.
+ * String-form input (JSON string or plain text) is coerced to a valid TipTap doc. Byte size is fail-fast checked before the sanitizing walk.
  *
  * @param raw - The raw rich text input.
  * @param maxBytes - Maximum allowed serialized size, checked before the walk.
@@ -26,5 +26,13 @@ export declare function sanitizeRichtext(raw: unknown, maxBytes: number): Richte
  * @returns True if empty, false otherwise.
  */
 export declare function isRichtextDocEmpty(value: unknown): boolean;
+/**
+ * Flattens a rich text value (raw TipTap doc or v1 envelope) into plain text for indexing,
+ * joining block-level pieces with spaces. Depth-guarded via {@link gatherRichtextText}.
+ *
+ * @param value - The deserialized richtext value (object), as returned by `deserializeFromDb`.
+ * @returns The flattened text, or an empty string if `value` carries no text.
+ */
+export declare function extractRichtextText(value: unknown): string;
 export {};
 //# sourceMappingURL=richtext-sanitizer.d.ts.map

package/dist/engine/validation/richtext-sanitizer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"richtext-sanitizer.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/richtext-sanitizer.ts"],"names":[],"mappings":"AA2BA,+DAA+D;AAC/D,UAAU,sBAAsB;IAC9B,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAA;IAClB,mEAAmE;IACnE,KAAK,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAoID;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CAgCvF;AA2BD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAS1D"}
+{"version":3,"file":"richtext-sanitizer.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/richtext-sanitizer.ts"],"names":[],"mappings":"AA2BA,+DAA+D;AAC/D,UAAU,sBAAsB;IAC9B,2CAA2C;IAC3C,KAAK,EAAE,OAAO,CAAA;IACd,6DAA6D;IAC7D,SAAS,EAAE,OAAO,CAAA;IAClB,mEAAmE;IACnE,KAAK,EAAE,OAAO,CAAA;IACd,wCAAwC;IACxC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,CAAC,EAAE,OAAO,CAAA;CACnB;AAqID;;;;;;;GAOG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,OAAO,EAAE,QAAQ,EAAE,MAAM,GAAG,sBAAsB,CA2CvF;AA8BD;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAS1D;AAED;;;;;;GAMG;AACH,wBAAgB,mBAAmB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAM1D"}

package/dist/engine/validation/richtext-sanitizer.js

@@ -1,7 +1,7 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
 import { RICHTEXT_SCHEMA_VERSION, isRichtextEnvelopeV1 } from '../../content/richtext/richtext.js';
-import { stripControlChars, cleanString, isPlainObject, byteLength } from './primitives.js';
+import { stripControlChars, cleanString, isPlainObject, byteLength, exceedsMaxDepth } from './primitives.js';
 /** Allowlisted TipTap node `type` values. Keep in sync with
  *  richtext-render.ts::createRichTextHtmlExtensions. */
 const ALLOWED_RICHTEXT_NODE_TYPES = new Set([
@@ -67,7 +67,7 @@ function isProtocolAllowed(raw) {
  * @param state - The shared sanitization state tracking danger flags.
  * @returns The cleaned rich text node, or `undefined` if it must be removed.
  */
-function walkRichtextNode(node, state) {
+function walkRichtextNode(node, state, insideAttrs = false) {
     if (state.depth > RICHTEXT_MAX_DEPTH) {
         state.dangerous = true;
         return undefined;
@@ -78,7 +78,7 @@ function walkRichtextNode(node, state) {
         state.depth++;
         const mapped = [];
         for (const child of node) {
-            const walked = walkRichtextNode(child, state);
+            const walked = walkRichtextNode(child, state, insideAttrs);
             if (walked !== undefined)
                 mapped.push(walked);
         }
@@ -88,8 +88,9 @@ function walkRichtextNode(node, state) {
     if (!isPlainObject(node))
         return node;
     // Node/mark type allowlist: any present `type` that isn't an allowlisted string is dropped.
-    // Objects with no `type` key (e.g. attrs bags) are not nodes and skip this check.
-    if ('type' in node) {
+    // Skipped inside `attrs` bags: a `type` key there is ordinary attribute data (e.g. TipTap's
+    // OrderedList `attrs.type` list-style marker), not a node/mark discriminator.
+    if (!insideAttrs && 'type' in node) {
         const rawType = node.type;
         const isAllowed = typeof rawType === 'string' &&
             (ALLOWED_RICHTEXT_NODE_TYPES.has(rawType) || ALLOWED_RICHTEXT_MARK_TYPES.has(rawType));
@@ -115,7 +116,7 @@ function walkRichtextNode(node, state) {
             state.dangerous = true;
             continue; // drop disallowed URL
         }
-        const walked = walkRichtextNode(entry, state);
+        const walked = walkRichtextNode(entry, state, insideAttrs || key === 'attrs');
         if (walked !== undefined)
             result[key] = walked;
     }
@@ -144,7 +145,7 @@ function sanitizeRichtextJson(raw) {
 }
 /**
  * Main entrance helper to sanitize rich text, handling both v1 envelope formats and raw JSON payloads.
- * String-form input is rejected (JSON-only). Byte size is fail-fast checked before the sanitizing walk.
+ * String-form input (JSON string or plain text) is coerced to a valid TipTap doc. Byte size is fail-fast checked before the sanitizing walk.
  *
  * @param raw - The raw rich text input.
  * @param maxBytes - Maximum allowed serialized size, checked before the walk.
@@ -154,11 +155,21 @@ export function sanitizeRichtext(raw, maxBytes) {
     const envelopeMode = isRichtextEnvelopeV1(raw);
     const payload = envelopeMode ? raw.doc : raw;
     if (typeof payload === 'string') {
+        const rawSize = byteLength(payload);
+        if (rawSize > maxBytes) {
+            return { value: raw, dangerous: false, valid: false, size: rawSize, oversize: true };
+        }
         return sanitizeRichtextString(payload);
     }
     if (!isPlainObject(payload)) {
         return { value: raw, dangerous: false, valid: false, size: 0 };
     }
+    // Fail-fast depth pre-check BEFORE anything touches JSON.stringify: it recurses
+    // unboundedly and throws RangeError on a few thousand levels of nesting, well
+    // before the size check below or the depth-guarded walk ever run (#443).
+    if (exceedsMaxDepth(payload, RICHTEXT_MAX_DEPTH)) {
+        return { value: raw, dangerous: true, valid: false, size: 0, oversize: true };
+    }
     // Fail-fast DoS pre-check: size BEFORE the sanitizing walk.
     const rawSize = byteLength(JSON.stringify(payload));
     if (rawSize > maxBytes) {
@@ -203,6 +214,9 @@ function gatherRichtextText(node, sink, depth = 0) {
     if (isPlainObject(node.attrs) && typeof node.attrs.latex === 'string') {
         sink.push(cleanString(node.attrs.latex));
     }
+    if (node.type === 'image' || node.type === 'horizontalRule' || node.type === 'table') {
+        sink.push(node.type);
+    }
     if (Array.isArray(node.content)) {
         for (const child of node.content)
             gatherRichtextText(child, sink, depth + 1);
@@ -226,3 +240,18 @@ export function isRichtextDocEmpty(value) {
     gatherRichtextText(value, sink);
     return sink.join('').trim().length === 0;
 }
+/**
+ * Flattens a rich text value (raw TipTap doc or v1 envelope) into plain text for indexing,
+ * joining block-level pieces with spaces. Depth-guarded via {@link gatherRichtextText}.
+ *
+ * @param value - The deserialized richtext value (object), as returned by `deserializeFromDb`.
+ * @returns The flattened text, or an empty string if `value` carries no text.
+ */
+export function extractRichtextText(value) {
+    if (!isPlainObject(value))
+        return '';
+    const doc = isRichtextEnvelopeV1(value) ? value.doc : value;
+    const sink = [];
+    gatherRichtextText(doc, sink);
+    return sink.join(' ').trim();
+}

package/dist/engine/validation/schema-builders.d.ts

@@ -1,6 +1,7 @@
 import { z } from 'zod';
 import type { Branch } from '../types.js';
 import type { ResolvedOptions } from './index.js';
+import { type LocaleConfig } from '../localization/localization.js';
 /**
  * Returns the appropriate Zod schema builder for a given branch based on its type.
  *
@@ -9,4 +10,19 @@ import type { ResolvedOptions } from './index.js';
  * @returns The compiled schema.
  */
 export declare function schemaForBranch(branch: Branch, options: ResolvedOptions): z.ZodTypeAny;
+/**
+ * Compiles the schema of a localized branch. Top level only: `compileSeedSchema` is the sole caller, so
+ * repeater sub-fields (validated through `schemaForBranch`) can never reach it.
+ *
+ * Accepts a plain value (→ default locale) or a locale dictionary, normalises it with
+ * {@link toLocalizedPatch}, and validates every non-null locale value with the branch's base-type schema.
+ * Output is a {@link LocalizedPatch}. Failures are reported at `<alias>.<locale>` for dictionary input
+ * and at `<alias>` for a plain value, i.e. always at a path that exists in the client's payload.
+ *
+ * @param branch - A branch for which `isLocalizedBranch(branch)` is true.
+ * @param options - The resolved validation options.
+ * @param config - The project language configuration.
+ * @returns The compiled localized schema.
+ */
+export declare function localizedSchema(branch: Branch, options: ResolvedOptions, config: LocaleConfig): z.ZodTypeAny;
 //# sourceMappingURL=schema-builders.d.ts.map

package/dist/engine/validation/schema-builders.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schema-builders.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/schema-builders.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,aAAa,CAAA;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAmajD;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,CAAC,CAAC,UAAU,CAMtF"}
+{"version":3,"file":"schema-builders.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/schema-builders.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,MAAM,EAAc,MAAM,aAAa,CAAA;AAErD,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAEjD,OAAO,EAAgD,KAAK,YAAY,EAAuB,MAAM,iCAAiC,CAAA;AAydtI;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,CAAC,CAAC,UAAU,CAMtF;AAED;;;;;;;;;;;;;GAaG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,EAAE,YAAY,GAAG,CAAC,CAAC,UAAU,CAiC5G"}

package/dist/engine/validation/schema-builders.js

@@ -2,7 +2,11 @@
 // Copyright (c) 2024–2026 Flavio De Musso
 import { z } from 'zod';
 import { extensionFromUrl, isExtensionAccepted } from '../../media/file-types.js';
-import { cleanString, stripControlChars, byteLength, isPlainObject } from './primitives.js';
+import { isLocalizedWriteDictionary, toLocalizedPatch } from '../localization/localization.js';
+import { cleanString, stripControlChars, byteLength, isPlainObject, exceedsMaxDepth } from './primitives.js';
+import { isEffectivelyEmpty } from './emptiness.js';
+import { isSingleChoiceTags, tagOptionValues } from '../seeds/tag-options.js';
+import { normalizeTagValue, TAG_MAX_COUNT, TAG_MAX_LENGTH, TAG_RAW_MAX_COUNT } from '../seeds/tag-value.js';
 import { sanitizeRichtext } from './richtext-sanitizer.js';
 import { resolveFileOptions, isAssetListBranch, collectAssetListItems, extractFileCandidate } from './file-branch.js';
 /**
@@ -180,8 +184,6 @@ function dateSchema(allowNull) {
 }
 /** Max nesting depth accepted when walking a `json` branch value. */
 const JSON_MAX_DEPTH = 50;
-/** Max number of items accepted in a `tags` branch array. */
-const MAX_TAGS_COUNT = 100;
 /**
  * Recursively strips control characters from string leaves while enforcing a
  * depth cap, mirroring the richtext sanitizer's DoS guards for arbitrary JSON.
@@ -229,6 +231,13 @@ function jsonSchema(options, allowNull) {
     const base = z
         .union([z.record(z.string(), z.unknown()), z.array(z.unknown())])
         .transform((val, ctx) => {
+        // Fail-fast depth pre-check BEFORE any JSON.stringify: deep nesting stack-
+        // overflows JSON.stringify (recursive) before the size check or the
+        // depth-guarded sanitizing walk below ever run (#443).
+        if (exceedsMaxDepth(val, JSON_MAX_DEPTH)) {
+            ctx.addIssue({ code: 'custom', message: `Expected json(maxDepth:${JSON_MAX_DEPTH})` });
+            return z.NEVER;
+        }
         // Fail-fast size check before the sanitizing walk, same order as richtext.
         const rawSize = byteLength(JSON.stringify(val));
         if (rawSize > options.maxTextLength) {
@@ -245,23 +254,59 @@ function jsonSchema(options, allowNull) {
     return withEmptyPreprocessing(base, allowNull);
 }
 /**
- * Compiles a Zod validation schema for a `tags` branch, constraining it to a
- * bounded array of cleaned strings (fixes #183: previously any array/object
- * shape passed, breaking callers like the kanban swap that cast to `string[]`).
+ * Compiles a Zod validation schema for a `tags` branch: a small array of short labels.
+ * Free values go through {@link normalizeTagValue} (invisible/control characters removed, whitespace
+ * collapsed, NFC) and may not exceed {@link TAG_MAX_LENGTH} characters; at most {@link TAG_MAX_COUNT} survive.
+ * With `options` the array is a closed vocabulary (exact, case-sensitive match after NFC, no trimming);
+ * without, values are normalized and those that clean to nothing are dropped. Duplicates are rejected, never merged,
+ * and a single-choice branch (`multiple: false`) accepts at most one value. The first violated
+ * rule emits one issue for the whole array.
  *
- * @param options - The resolved validation options.
+ * @param branch - The tags branch definition.
  * @param allowNull - Whether null values are allowed.
  * @returns The compiled tags schema.
  */
-function tagsSchema(options, allowNull) {
-    const tagSchema = z
-        .string()
-        .transform((value) => cleanString(value))
-        .refine((value) => byteLength(value) <= options.maxTextLength, {
-        message: `Expected string(max:${options.maxTextLength})`,
-    });
-    const base = z.array(tagSchema).max(MAX_TAGS_COUNT, {
-        message: `Expected tags(max:${MAX_TAGS_COUNT})`,
+function tagsSchema(branch, allowNull) {
+    const allowedValues = tagOptionValues(branch);
+    const isClosedVocabulary = allowedValues.length > 0;
+    const base = z
+        .array(z.string())
+        // Coarse guard so a huge payload is not scanned; the real cap applies after blanks are dropped.
+        .max(TAG_RAW_MAX_COUNT, { message: `Expected tags(max:${TAG_MAX_COUNT})` })
+        .transform((tags, ctx) => {
+        const values = [];
+        for (const tag of tags) {
+            if (isClosedVocabulary) {
+                // Exact match: only NFC is applied, so a padded or invisible-char variant of an option is rejected.
+                values.push(tag.normalize('NFC'));
+                continue;
+            }
+            const normalized = normalizeTagValue(tag);
+            if (!normalized.ok) {
+                const expected = normalized.reason === 'too-long' ? `tags(item-max:${TAG_MAX_LENGTH})` : 'tags(valid-text)';
+                ctx.addIssue({ code: 'custom', message: `Expected ${expected}` });
+                return z.NEVER;
+            }
+            if (normalized.value.length > 0)
+                values.push(normalized.value);
+        }
+        if (isClosedVocabulary && values.some((tag) => !allowedValues.includes(tag))) {
+            ctx.addIssue({ code: 'custom', message: `Expected tags(one-of:${allowedValues.join('|')})` });
+            return z.NEVER;
+        }
+        if (values.length > TAG_MAX_COUNT) {
+            ctx.addIssue({ code: 'custom', message: `Expected tags(max:${TAG_MAX_COUNT})` });
+            return z.NEVER;
+        }
+        if (new Set(values).size !== values.length) {
+            ctx.addIssue({ code: 'custom', message: 'Expected tags(unique)' });
+            return z.NEVER;
+        }
+        if (isSingleChoiceTags(branch) && values.length > 1) {
+            ctx.addIssue({ code: 'custom', message: 'Expected tags(max:1)' });
+            return z.NEVER;
+        }
+        return values;
     });
     return withEmptyPreprocessing(base, allowNull);
 }
@@ -363,14 +408,27 @@ function repeaterSchema(branch, options) {
     const requiredFlag = options.operation === 'create' ? 'requiredOnCreate' : 'requiredOnUpdate';
     const subBranches = (branch.fields ?? []).filter((sub) => !REPEATER_DISALLOWED_SUBTYPES.has(sub.type));
     const shape = {};
+    const requiredSubs = [];
     for (const sub of subBranches) {
         const subSchema = schemaForBranch(sub, options);
         const isRequired = options.enforceRequiredFields && sub[requiredFlag];
         shape[sub.alias] = isRequired ? subSchema : subSchema.optional();
+        if (isRequired)
+            requiredSubs.push(sub);
     }
     // z.object() strips unknown keys by default — old item shapes from a renamed/
     // removed sub-field are dropped rather than rejected (sprint 10 §5.1).
-    const itemSchema = z.object(shape);
+    // Making the key non-optional above only guards presence: leaf schemas fold ""
+    // to `undefined` (withEmptyPreprocessing) or accept whitespace-only text, so a
+    // required sub-field still needs the same value-level emptiness check top-level
+    // required branches get from detectMissingRequired (issue #444).
+    const itemSchema = z.object(shape).superRefine((item, ctx) => {
+        for (const sub of requiredSubs) {
+            if (isEffectivelyEmpty(item[sub.alias], sub.type)) {
+                ctx.addIssue({ code: 'custom', path: [sub.alias], message: 'Expected non-empty(required)' });
+            }
+        }
+    });
     let arraySchema = z.array(itemSchema);
     if (Number.isInteger(branch.minItems) && branch.minItems >= 0) {
         arraySchema = arraySchema.min(branch.minItems, {
@@ -392,7 +450,7 @@ const BRANCH_SCHEMA_BUILDERS = {
     boolean: (_branch, options) => booleanSchema(options.allowNull),
     date: (_branch, options) => dateSchema(options.allowNull),
     json: (_branch, options) => jsonSchema(options, options.allowNull),
-    tags: (_branch, options) => tagsSchema(options, options.allowNull),
+    tags: (branch, options) => tagsSchema(branch, options.allowNull),
     file: (branch, options) => fileSchema(branch, options.allowNull),
     relation: (branch, options) => relationSchema(branch, options),
     repeater: (branch, options) => repeaterSchema(branch, options),
@@ -411,3 +469,52 @@ export function schemaForBranch(branch, options) {
     }
     return builder(branch, options);
 }
+/**
+ * Compiles the schema of a localized branch. Top level only: `compileSeedSchema` is the sole caller, so
+ * repeater sub-fields (validated through `schemaForBranch`) can never reach it.
+ *
+ * Accepts a plain value (→ default locale) or a locale dictionary, normalises it with
+ * {@link toLocalizedPatch}, and validates every non-null locale value with the branch's base-type schema.
+ * Output is a {@link LocalizedPatch}. Failures are reported at `<alias>.<locale>` for dictionary input
+ * and at `<alias>` for a plain value, i.e. always at a path that exists in the client's payload.
+ *
+ * @param branch - A branch for which `isLocalizedBranch(branch)` is true.
+ * @param options - The resolved validation options.
+ * @param config - The project language configuration.
+ * @returns The compiled localized schema.
+ */
+export function localizedSchema(branch, options, config) {
+    const valueSchema = schemaForBranch({ ...branch, localized: false }, { ...options, allowNull: false });
+    return z.any().transform((raw, ctx) => {
+        if (raw === null) {
+            if (!options.allowNull)
+                ctx.addIssue({ code: 'custom', message: 'Expected localized-value' });
+            return null;
+        }
+        const isDictionaryInput = isLocalizedWriteDictionary(raw, config);
+        const patch = toLocalizedPatch(raw, config);
+        const validated = {};
+        for (const [locale, localeValue] of Object.entries(patch)) {
+            if (localeValue === null) {
+                validated[locale] = null;
+                continue;
+            }
+            const parsed = valueSchema.safeParse(localeValue);
+            if (parsed.success) {
+                validated[locale] = parsed.data;
+                continue;
+            }
+            for (const issue of parsed.error.issues) {
+                const innerPath = issue.path;
+                ctx.addIssue({
+                    code: 'custom',
+                    path: isDictionaryInput ? [locale, ...innerPath] : innerPath,
+                    // Keep the "Expected <type>" convention expectedFromIssue() relies on.
+                    message: issue.code === 'invalid_type' ? `Expected ${issue.expected}` : issue.message,
+                    params: issue.params,
+                });
+            }
+        }
+        return validated;
+    });
+}