@beechcms/core 0.6.0-preview.4 → 0.6.0

package/dist/{types.d.ts → engine/types.d.ts}

@@ -1,47 +1,55 @@
-import type { FileAccept } from './file-types.js';
+/**
+ * @module Types
+ * Core schema types for the Botanical Engine: `Seed` (content type definition),
+ * `Branch` (field definition), and the query types consumed by `buildSelectQuery`.
+ * Pure data shapes — no runtime logic lives here.
+ */
+import type { FileAccept } from '../media/file-types.js';
+import type { DashboardView } from '../dashboard-layout/view-authorization.js';
+/** All supported field value types for a Branch. */
 export type BranchType = 'text' | 'number' | 'boolean' | 'json' | 'date' | 'richtext' | 'file' | 'tags' | 'relation' | 'repeater';
-/** Configurazioni specializzate per il tipo di branch 'number' */
+/** Specialized configuration for a branch of type 'number'. */
 export interface NumberFieldOptions {
-    /** Stile di presentazione visiva. Default: 'decimal' */
+    /** Visual display style. Default: 'decimal'. */
     format?: 'decimal' | 'currency' | 'percentage' | 'compact';
-    /** Codice valuta ISO 4217 (obbligatorio se format === 'currency'). Es. 'EUR', 'USD' */
+    /** ISO 4217 currency code (required when format === 'currency'). E.g. 'EUR', 'USD'. */
     currency?: string;
-    /** Testo personalizzato da anteporre al valore formattato */
+    /** Custom text prepended to the formatted value. */
     prefix?: string;
-    /** Unità di misura personalizzata da appendere al valore formattato (es. 'kg', 'm²') */
+    /** Custom unit appended to the formatted value (e.g. 'kg', 'm²'). */
     suffix?: string;
-    /** Numero esplicito di cifre decimali da visualizzare e imporre */
+    /** Explicit number of decimal digits to display and enforce. */
     decimals?: number;
-    /** Abilita/disabilita il separatore delle migliaia. Default: true */
+    /** Enable/disable thousands separator grouping. Default: true. */
     grouping?: boolean;
-    /** Meccanismo di input alternativo per l'editor delle entità. Default: 'input' */
+    /** Alternative input mechanism for the entry editor. Default: 'input'. */
     control?: 'input' | 'slider' | 'rating' | 'stepper';
-    /** Valore minimo consentito */
+    /** Minimum allowed value. */
     min?: number;
-    /** Valore massimo consentito */
+    /** Maximum allowed value. */
     max?: number;
-    /** Incremento del valore (es. 1 per interi stretti, 0.5 per mezzi passi) */
+    /** Value increment (e.g. 1 for strict integers, 0.5 for half-steps). */
     step?: number;
 }
-/** Configurazioni specializzate per il tipo di branch 'file' */
+/** Specialized configuration for a branch of type 'file'. */
 export interface FileFieldOptions {
     /**
-     * Tipo semantico di file accettato.
-     * - 'image': immagini renderizzabili come anteprima
+     * Semantic type of file accepted.
+     * - 'image': renderable images with preview
      * - 'document': PDF/Office/text
-     * - 'any': qualsiasi file (default — UI mostra icona generica, nessun tentativo di render immagine)
+     * - 'any': any file (default — UI shows a generic icon, no image render attempt)
      * Default: 'any'.
      */
     accept?: FileAccept;
     /**
-     * Dimensione massima del singolo file in byte.
-     * NOTA: il backend /upload applica MAX_FILE_SIZE_BYTES (5MB) globale —
-     * questo campo è informativo per la UI; non viene enforced in upload.
+     * Maximum size of a single file, in bytes.
+     * NOTE: the backend /upload endpoint enforces the global MAX_FILE_SIZE_BYTES (5MB) —
+     * this field is informational for the UI only; it is not enforced on upload.
      * Default: 5_242_880.
      */
     maxSize?: number;
 }
-/** Branch: definizione di una proprietà. alias = nome colonna SQL. */
+/** Branch: definition of a single field. `alias` is the SQL column name. */
 export interface Branch {
     /**
      * Stable logical id of this branch, e.g. 'br_01', 'br_title'.
@@ -53,55 +61,55 @@ export interface Branch {
      * The Botanical Engine still emits alias as the SQL column name; id is a logical handle.
      */
     id: string;
-    /** Alias human-readable, usato nel payload API e come nome colonna SQL nella tabella dedicata */
+    /** Human-readable alias, used in the API payload and as the SQL column name in the dedicated table. */
     alias: string;
-    /** Etichetta per la UI */
+    /** UI display label. */
     label: string;
-    /** Testo di aiuto opzionale mostrato come tooltip accanto al label nella form. UI-only, ignorato dall'engine. */
+    /** Optional help text shown as a tooltip next to the label in the form. UI-only, ignored by the engine. */
     hint?: string;
-    /** Tipo del valore */
+    /** Value type. */
     type: BranchType;
     /**
-     * Variante semantica opzionale del campo per UI/validazione.
-     * `asset-list` su `file` multiplo abilita la gestione galleria.
+     * Optional semantic variant of the field for UI/validation purposes.
+     * `asset-list` on a multiple `file` branch enables gallery management.
      */
     format?: 'plain' | 'markdown' | 'html' | 'date' | 'datetime' | 'asset-list';
     /**
-     * Cardinalità opzionale per campi media:
-     * - false/undefined: singolo asset (string URL)
-     * - true: lista asset (string[] URL)
+     * Optional cardinality for media fields:
+     * - false/undefined: single asset (string URL)
+     * - true: asset list (string[] URL)
      */
     multiple?: boolean;
     /**
-     * Vocabolario predefinito per campi tag/select/multiselect.
-     * Lista statica definita nel Seed (non salvata nel DB).
+     * Predefined vocabulary for tag/select/multiselect fields.
+     * Static list defined in the Seed (not persisted to the DB).
      */
     options?: string[];
-    /** Campo obbligatorio in creazione — genera NOT NULL in generateCreateTable */
+    /** Required on create — generates NOT NULL in generateCreateTable. */
     requiredOnCreate?: boolean;
-    /** Campo obbligatorio in update */
+    /** Required on update. */
     requiredOnUpdate?: boolean;
     /**
-     * Policy di accesso e trattamento del campo.
-     * Tutti i valori sono opzionali — `resolvePolicies(branch)` fornisce i default.
+     * Access and handling policy for the field.
+     * All values are optional — `resolvePolicies(branch)` supplies the defaults.
      */
     policies?: {
-        /** Come il valore viene memorizzato. Default: 'plain' */
+        /** How the value is stored. Default: 'plain'. */
         privacy?: 'plain' | 'hash' | 'encrypt';
-        /** Come il valore viene restituito nelle risposte API. Default: 'full' */
+        /** How the value is returned in API responses. Default: 'full'. */
         visibility?: 'full' | 'masked' | 'hidden';
-        /** Il campo è incluso nelle query di ricerca full-text. Default: true */
+        /** Whether the field is included in full-text search queries. Default: true. */
         search?: boolean;
-        /** Il campo è disponibile come colonna di filtro nella dashboard. Default: true */
+        /** Whether the field is available as a filter column in the dashboard. Default: true. */
         filter?: boolean;
-        /** Il campo è disponibile come colonna di ordinamento nella dashboard. Default: true */
+        /** Whether the field is available as a sort column in the dashboard. Default: true. */
         sort?: boolean;
-        /** Il campo è incluso nelle risposte della Public API. Default: true */
+        /** Whether the field is included in Public API responses. Default: true. */
         public?: boolean;
     };
-    /** Opzioni avanzate per i campi numerici. Ignorato se type !== 'number' */
+    /** Advanced options for number fields. Ignored if type !== 'number'. */
     numberOptions?: NumberFieldOptions;
-    /** Opzioni avanzate per i campi file. Ignorato se type !== 'file' */
+    /** Advanced options for file fields. Ignored if type !== 'file'. */
     fileOptions?: FileFieldOptions;
     /**
      * Slug of the referenced Seed (without the `content_` prefix).
@@ -149,13 +157,13 @@ export interface Branch {
 }
 /** Dashboard-specific config embedded in a Seed. All fields optional — defaults applied by the dashboard. */
 export interface DashboardSeedConfig {
-    /** Lucide icon name (string, resolved to component client-side). Default: 'Folder' */
+    /** Lucide icon name (string, resolved to component client-side). Default: 'Folder'. */
     icon?: string;
     /** Sidebar group label. Ungrouped seeds share a single 'Contents' section. */
     group?: string;
-    /** Sort order within the group. Lower = higher. Default: 99 */
+    /** Sort order within the group. Lower = higher. Default: 99. */
     order?: number;
-    /** Hide from sidebar navigation. Default: false */
+    /** Hide from sidebar navigation. Default: false. */
     hidden?: boolean;
     /** Tooltip description shown in the sidebar. */
     description?: string;
@@ -166,33 +174,39 @@ export interface DashboardSeedConfig {
         export?: boolean;
         bulkDelete?: boolean;
     };
+    /**
+     * Views authorized for this seed in the content manager. When omitted,
+     * the dashboard falls back to DEFAULT_AUTHORIZED_VIEWS. 'table' is always
+     * guaranteed at read time by resolveAuthorizedViews (universal fallback).
+     */
+    views?: DashboardView[];
 }
-/** Seed: definizione dello schema di un tipo di contenuto */
+/** Seed: schema definition of a content type. */
 export interface Seed {
-    /** Slug identificativo — anche nome tabella: `content_{slug}` */
+    /** Identifying slug — also the table name: `content_{slug}`. */
     slug: string;
-    /** Etichetta singolare per la UI */
+    /** Singular UI label. */
     label: string;
-    /** Etichetta plurale per la UI. Se assente si usa `label`. */
+    /** Plural UI label. Falls back to `label` when absent. */
     labelPlural?: string;
-    /** Abilita lettura dalla Public API (`GET /api/v1/public/:seed`). Default: false */
+    /** Enable reads from the Public API (`GET /api/v1/public/:seed`). Default: false. */
     allowPublicRead?: boolean;
-    /** Abilita creazione dalla Public API (`POST /api/v1/public/:seed/add`). Default: false */
+    /** Enable creation from the Public API (`POST /api/v1/public/:seed/add`). Default: false. */
     allowPublicPost?: boolean;
-    /** Abilita modifica dalla Public API (`PUT /api/v1/public/:seed/edit/:id`). Default: false */
+    /** Enable edits from the Public API (`PUT /api/v1/public/:seed/edit/:id`). Default: false. */
     allowPublicEdit?: boolean;
     /**
-     * Abilita la feature "bozza in attesa" per questo seed.
-     * Quando true, genera tabella `content_{slug}_drafts` e abilita gli endpoint `/draft`.
-     * Default: false
+     * Enables the "pending draft" feature for this seed.
+     * When true, generates the `content_{slug}_drafts` table and enables the `/draft` endpoints.
+     * Default: false.
      */
     allowDrafts?: boolean;
     /**
-     * Alias del branch usato come nome leggibile dell'entry (es. "title", "name", "author").
-     * Obbligatorio — le UI lo usano per display senza euristica.
+     * 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.
      */
     displayNameAlias: string;
-    /** Lista dei campi (Branch) */
+    /** List of fields (Branch). */
     branches: Branch[];
     /** Optional dashboard-specific UI config. Ignored by the Botanical Engine. */
     dashboard?: DashboardSeedConfig;
@@ -201,37 +215,62 @@ export interface Seed {
      *  Type matches FormLayout from seed-layout.ts — kept as unknown here to avoid circular imports. */
     layout?: unknown;
 }
+/** 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';
+/** A single operator + value pair applied to a FilterGroup's column. */
 export interface FilterCondition {
+    /** Operator to apply. */
     op: FilterOperator;
+    /** Comparison value(s). Arrays are only meaningful for `in`/`not_in`/`has_any_tag`/`has_all_tags`. */
     value: string | number | boolean | null | string[] | number[];
 }
 export interface FilterGroup {
-    /** Nome colonna: system column (id/slug/status/created_at/updated_at) o branch alias */
+    /** Column name: system column (id/slug/status/created_at/updated_at) or branch alias. */
     column: string;
+    /** Declared type of the column, used to normalize condition values. */
     type: FilterType;
+    /** Conditions applied to this column, ANDed together. */
     conditions: FilterCondition[];
 }
 export interface SelectOptions {
+    /** Filter groups, ANDed together. */
     filters?: FilterGroup[];
+    /** Sort column and direction. Ignored when `kanbanOrder` is set. */
     orderBy?: {
         column: string;
         dir: 'ASC' | 'DESC';
     };
+    /** LIMIT/OFFSET pagination. */
     pagination?: {
         limit: number;
         offset: number;
     };
-    /** Filtra per status. null = nessun filtro status. */
+    /** Filters by status. null = no status filter. */
     status?: string | null;
-    /** Full-text search — usa FTS5 se il seed ha branch richtext indicizzabili */
+    /** Full-text search — uses FTS5 if the seed has indexable richtext/text branches. */
     search?: string;
-    /** Proiezione colonne. Vuoto = SELECT * */
+    /** Column projection. Empty = SELECT *. */
     fields?: string[];
+    /** When set, LEFT JOIN kanban_positions and order by fractional index (KB-S04c/S05).
+     *  Mutually exclusive with `orderBy`; if both present, `kanbanOrder` wins. */
+    kanbanOrder?: {
+        seedSlug: string;
+        axisBranchId: string;
+    };
+    /**
+     * When true, generates a COUNT(*) query instead of fetching rows.
+     * This omits projections, sorting/ordering clauses, and pagination limits/offsets,
+     * while keeping the join/where clauses intact for accurate counts.
+     */
+    isCount?: boolean;
 }
+/** SQL string paired with its ordered parameter bindings, ready for a D1 `.bind(...)` call. */
 export interface ParameterizedQuery {
+    /** Parameterized SQL statement, using `?` placeholders. */
     sql: string;
+    /** Values bound to the `?` placeholders, in order. */
     bindings: (string | number | boolean | null)[];
 }
 //# sourceMappingURL=types.d.ts.map

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

@@ -0,0 +1 @@
+{"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

@@ -0,0 +1,12 @@
+import { z } from 'zod';
+import type { Seed } from '../types.js';
+import type { ResolvedOptions } from './index.js';
+/**
+ * Compiles or retrieves from cache the full Zod validation schema for a seed structure.
+ *
+ * @param seed - The seed definition.
+ * @param options - The resolved validation options.
+ * @returns The compiled strict Zod object schema.
+ */
+export declare function compileSeedSchema(seed: Seed, options: ResolvedOptions): z.ZodObject<Record<string, z.ZodTypeAny>>;
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +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;AACjG,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,YAAY,CAAA;AAoHjD;;;;;;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,CA2BjH"}

package/dist/engine/validation/cache.js

@@ -0,0 +1,115 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { z } from 'zod';
+import { schemaForBranch } from './schema-builders.js';
+/** Max entries kept in {@link seedSchemaCache} before evicting the least recently used. */
+const SEED_SCHEMA_CACHE_MAX_SIZE = 150;
+/** Cache storing compiled Zod schemas for seeds to optimize validation runs. */
+const seedSchemaCache = new Map();
+/**
+ * Retrieves a cache entry and marks it as most recently used.
+ *
+ * @param key - The cache key.
+ * @returns The cached schema, or undefined if absent.
+ */
+function getCachedSchema(key) {
+    const cached = seedSchemaCache.get(key);
+    if (cached) {
+        seedSchemaCache.delete(key);
+        seedSchemaCache.set(key, cached);
+    }
+    return cached;
+}
+/**
+ * Stores a cache entry, evicting the least recently used one if over capacity.
+ *
+ * @param key - The cache key.
+ * @param value - The compiled schema to cache.
+ */
+function setCachedSchema(key, value) {
+    if (seedSchemaCache.size >= SEED_SCHEMA_CACHE_MAX_SIZE) {
+        const oldestKey = seedSchemaCache.keys().next().value;
+        if (oldestKey !== undefined)
+            seedSchemaCache.delete(oldestKey);
+    }
+    seedSchemaCache.set(key, value);
+}
+/**
+ * Recursively generates a typesafe fingerprint object for a branch and its sub-branches.
+ *
+ * @param branch - The branch definition.
+ * @returns The structured branch fingerprint object.
+ */
+function buildBranchFingerprint(branch) {
+    return {
+        a: branch.alias,
+        t: branch.type,
+        f: branch.format ?? null,
+        m: branch.multiple === true,
+        rc: branch.requiredOnCreate === true,
+        ru: branch.requiredOnUpdate === true,
+        n: branch.numberOptions ?? null,
+        fi: branch.fileOptions ?? null,
+        mi: branch.minItems ?? null,
+        ma: branch.maxItems ?? null,
+        sub: branch.fields?.map(buildBranchFingerprint) ?? null,
+    };
+}
+/**
+ * Generates a unique JSON fingerprint string representing a seed's structure for caching.
+ *
+ * @param seed - The seed definition.
+ * @returns The fingerprint string.
+ */
+function buildSeedFingerprint(seed) {
+    const parts = seed.branches.map(buildBranchFingerprint);
+    return JSON.stringify({ s: seed.slug, b: parts });
+}
+/**
+ * Builds a cache key for a seed validation schema combining its fingerprint, operation, and options.
+ *
+ * @param seed - The seed definition.
+ * @param options - The resolved validation options.
+ * @returns The cache key string.
+ */
+function buildCacheKey(seed, options) {
+    return [
+        buildSeedFingerprint(seed),
+        options.operation,
+        options.allowNull ? '1' : '0',
+        options.enforceRequiredFields ? '1' : '0',
+        String(options.maxTextLength),
+    ].join('|');
+}
+/**
+ * Compiles or retrieves from cache the full Zod validation schema for a seed structure.
+ *
+ * @param seed - The seed definition.
+ * @param options - The resolved validation options.
+ * @returns The compiled strict Zod object schema.
+ */
+export function compileSeedSchema(seed, options) {
+    // Seeds with relation branches cannot be safely cached because the schema
+    // captures the idGenerator by closure, and different generators (e.g.
+    // SystemIdGenerator vs SequentialIdGenerator) have different isValid() semantics.
+    const hasRelation = seed.branches.some((b) => b.type === 'relation');
+    if (!hasRelation) {
+        const key = buildCacheKey(seed, options);
+        const cached = getCachedSchema(key);
+        if (cached)
+            return cached;
+    }
+    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;
+        shape[branch.alias] = isRequired ? branchSchema : branchSchema.optional();
+    }
+    const compiled = z.object(shape).strict();
+    if (!hasRelation) {
+        const key = buildCacheKey(seed, options);
+        setCachedSchema(key, compiled);
+    }
+    return compiled;
+}

package/dist/engine/validation/file-branch.d.ts

@@ -0,0 +1,48 @@
+import type { Branch } from '../types.js';
+import type { FileAccept } from '../../media/file-types.js';
+/**
+ * Parses a candidate value into a valid HTTP or HTTPS URL string, returning null if invalid.
+ *
+ * @param input - The value to validate.
+ * @returns The cleaned URL string, or null if invalid.
+ */
+export declare function parseHttpUrl(input: unknown): string | null;
+/**
+ * Resolves the file validation options for a branch, applying default values.
+ *
+ * @param branch - The file branch containing option overrides.
+ * @returns An object with resolved file acceptance rules and maximum size limit.
+ */
+export declare function resolveFileOptions(branch: Branch): {
+    accept: FileAccept;
+    maxSize: number;
+};
+/**
+ * Checks if a branch acts as an asset list (file type with multiple upload allowed or asset-list format).
+ *
+ * @param branch - The branch to check.
+ * @returns True if it is an asset list, false otherwise.
+ */
+export declare function isAssetListBranch(branch: Branch): boolean;
+/** A file URL paired with its byte size, when known from payload metadata. */
+export interface FileCandidate {
+    url: string;
+    size: number | null;
+}
+/**
+ * Extracts a URL and, when available, a byte size from a candidate value
+ * (a string URL, or an object with `url`/`size` fields, e.g. uploader output).
+ *
+ * @param candidate - The candidate value.
+ * @returns The extracted file candidate, or null if no valid URL was found.
+ */
+export declare function extractFileCandidate(candidate: unknown): FileCandidate | null;
+/**
+ * Collects and deduplicates valid file candidates (url + optional size) from a raw
+ * input representing an asset list.
+ *
+ * @param raw - The raw input data (can be array, JSON string, or single item).
+ * @returns The list of unique file candidates, or null if any item is invalid.
+ */
+export declare function collectAssetListItems(raw: unknown): FileCandidate[] | null;
+//# sourceMappingURL=file-branch.d.ts.map

package/dist/engine/validation/file-branch.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"file-branch.d.ts","sourceRoot":"","sources":["../../../src/engine/validation/file-branch.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,2BAA2B,CAAA;AAoB3D;;;;;GAKG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,IAAI,CAW1D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAM1F;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAEzD;AA6BD,8EAA8E;AAC9E,MAAM,WAAW,aAAa;IAC5B,GAAG,EAAE,MAAM,CAAA;IACX,IAAI,EAAE,MAAM,GAAG,IAAI,CAAA;CACpB;AAED;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAAC,SAAS,EAAE,OAAO,GAAG,aAAa,GAAG,IAAI,CAI7E;AAED;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,EAAE,GAAG,IAAI,CAe1E"}

package/dist/engine/validation/file-branch.js

@@ -0,0 +1,127 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { cleanString, isPlainObject } from './primitives.js';
+/** Default maximum file size in bytes for file branches. */
+const DEFAULT_FILE_MAX_SIZE = 5 * 1024 * 1024;
+/**
+ * Safely parses a JSON string, returning the parsed value, or the original string if parsing fails.
+ *
+ * @param raw - The string to attempt parsing.
+ * @returns The parsed object/array, or the original string.
+ */
+function tryParseJson(raw) {
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return raw;
+    }
+}
+/**
+ * Parses a candidate value into a valid HTTP or HTTPS URL string, returning null if invalid.
+ *
+ * @param input - The value to validate.
+ * @returns The cleaned URL string, or null if invalid.
+ */
+export function parseHttpUrl(input) {
+    if (typeof input !== 'string')
+        return null;
+    const cleaned = cleanString(input);
+    if (cleaned.length === 0)
+        return null;
+    let parsed;
+    try {
+        parsed = new URL(cleaned);
+    }
+    catch {
+        return null;
+    }
+    return (parsed.protocol === 'http:' || parsed.protocol === 'https:') ? cleaned : null;
+}
+/**
+ * Resolves the file validation options for a branch, applying default values.
+ *
+ * @param branch - The file branch containing option overrides.
+ * @returns An object with resolved file acceptance rules and maximum size limit.
+ */
+export function resolveFileOptions(branch) {
+    const opts = branch.fileOptions;
+    return {
+        accept: opts?.accept ?? 'any',
+        maxSize: opts?.maxSize ?? DEFAULT_FILE_MAX_SIZE,
+    };
+}
+/**
+ * Checks if a branch acts as an asset list (file type with multiple upload allowed or asset-list format).
+ *
+ * @param branch - The branch to check.
+ * @returns True if it is an asset list, false otherwise.
+ */
+export function isAssetListBranch(branch) {
+    return branch.type === 'file' && (branch.multiple === true || branch.format === 'asset-list');
+}
+/**
+ * Extracts a URL string from a candidate value (which can be a string URL or an object containing a `url` field).
+ *
+ * @param candidate - The candidate value.
+ * @returns The extracted URL string, or null if not found.
+ */
+function extractUrlFromCandidate(candidate) {
+    const direct = parseHttpUrl(candidate);
+    if (direct)
+        return direct;
+    if (isPlainObject(candidate)) {
+        return parseHttpUrl(candidate.url);
+    }
+    return null;
+}
+/**
+ * Extracts a byte size from a candidate value's `size` field, if present and valid.
+ *
+ * @param candidate - The candidate value.
+ * @returns The size in bytes, or null if not available.
+ */
+function extractSizeFromCandidate(candidate) {
+    if (!isPlainObject(candidate))
+        return null;
+    const raw = candidate.size;
+    return typeof raw === 'number' && Number.isFinite(raw) && raw >= 0 ? raw : null;
+}
+/**
+ * Extracts a URL and, when available, a byte size from a candidate value
+ * (a string URL, or an object with `url`/`size` fields, e.g. uploader output).
+ *
+ * @param candidate - The candidate value.
+ * @returns The extracted file candidate, or null if no valid URL was found.
+ */
+export function extractFileCandidate(candidate) {
+    const url = extractUrlFromCandidate(candidate);
+    if (!url)
+        return null;
+    return { url, size: extractSizeFromCandidate(candidate) };
+}
+/**
+ * Collects and deduplicates valid file candidates (url + optional size) from a raw
+ * input representing an asset list.
+ *
+ * @param raw - The raw input data (can be array, JSON string, or single item).
+ * @returns The list of unique file candidates, or null if any item is invalid.
+ */
+export function collectAssetListItems(raw) {
+    const source = typeof raw === 'string' ? tryParseJson(raw) : raw;
+    const items = Array.isArray(source) ? source : [source];
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        if (item === null || item === undefined)
+            continue;
+        const candidate = extractFileCandidate(item);
+        if (!candidate)
+            return null;
+        if (!seen.has(candidate.url)) {
+            seen.add(candidate.url);
+            out.push(candidate);
+        }
+    }
+    return out;
+}