@beechcms/core 0.6.0-preview.4 → 0.6.1

package/dist/engine/types.d.ts

@@ -0,0 +1,278 @@
+/**
+ * @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';
+/** Specialized configuration for a branch of type 'number'. */
+export interface NumberFieldOptions {
+    /** Visual display style. Default: 'decimal'. */
+    format?: 'decimal' | 'currency' | 'percentage' | 'compact';
+    /** ISO 4217 currency code (required when format === 'currency'). E.g. 'EUR', 'USD'. */
+    currency?: string;
+    /** Custom text prepended to the formatted value. */
+    prefix?: string;
+    /** Custom unit appended to the formatted value (e.g. 'kg', 'm²'). */
+    suffix?: string;
+    /** Explicit number of decimal digits to display and enforce. */
+    decimals?: number;
+    /** Enable/disable thousands separator grouping. Default: true. */
+    grouping?: boolean;
+    /** Alternative input mechanism for the entry editor. Default: 'input'. */
+    control?: 'input' | 'slider' | 'rating' | 'stepper';
+    /** Minimum allowed value. */
+    min?: number;
+    /** Maximum allowed value. */
+    max?: number;
+    /** Value increment (e.g. 1 for strict integers, 0.5 for half-steps). */
+    step?: number;
+}
+/** Specialized configuration for a branch of type 'file'. */
+export interface FileFieldOptions {
+    /**
+     * Semantic type of file accepted.
+     * - 'image': renderable images with preview
+     * - 'document': PDF/Office/text
+     * - 'any': any file (default — UI shows a generic icon, no image render attempt)
+     * Default: 'any'.
+     */
+    accept?: FileAccept;
+    /**
+     * 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: 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'.
+     * Format: ^br_[A-Za-z0-9]+$ — enforced by SeedRegistry at boot (sprint 04-pre).
+     *
+     * Used by every persistence layer that needs a reference that survives alias renames
+     * (FTS triggers, draft indexing, layout JSON, automations). NEVER use alias for that purpose.
+     *
+     * The Botanical Engine still emits alias as the SQL column name; id is a logical handle.
+     */
+    id: string;
+    /** Human-readable alias, used in the API payload and as the SQL column name in the dedicated table. */
+    alias: string;
+    /** UI display label. */
+    label: string;
+    /** Optional help text shown as a tooltip next to the label in the form. UI-only, ignored by the engine. */
+    hint?: string;
+    /** Value type. */
+    type: BranchType;
+    /**
+     * 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';
+    /**
+     * Optional cardinality for media fields:
+     * - false/undefined: single asset (string URL)
+     * - true: asset list (string[] URL)
+     */
+    multiple?: boolean;
+    /**
+     * Predefined vocabulary for tag/select/multiselect fields.
+     * Static list defined in the Seed (not persisted to the DB).
+     */
+    options?: string[];
+    /** Required on create — generates NOT NULL in generateCreateTable. */
+    requiredOnCreate?: boolean;
+    /** Required on update. */
+    requiredOnUpdate?: boolean;
+    /**
+     * Access and handling policy for the field.
+     * All values are optional — `resolvePolicies(branch)` supplies the defaults.
+     */
+    policies?: {
+        /** How the value is stored. Default: 'plain'. */
+        privacy?: 'plain' | 'hash' | 'encrypt';
+        /** How the value is returned in API responses. Default: 'full'. */
+        visibility?: 'full' | 'masked' | 'hidden';
+        /** Whether the field is included in full-text search queries. Default: true. */
+        search?: boolean;
+        /** Whether the field is available as a filter column in the dashboard. Default: true. */
+        filter?: boolean;
+        /** Whether the field is available as a sort column in the dashboard. Default: true. */
+        sort?: boolean;
+        /** Whether the field is included in Public API responses. Default: true. */
+        public?: boolean;
+    };
+    /** Advanced options for number fields. Ignored if type !== 'number'. */
+    numberOptions?: NumberFieldOptions;
+    /** Advanced options for file fields. Ignored if type !== 'file'. */
+    fileOptions?: FileFieldOptions;
+    /**
+     * Slug of the referenced Seed (without the `content_` prefix).
+     * REQUIRED when `type === 'relation'`. Ignored otherwise.
+     * Example: 'team' → references table `content_team(id)`.
+     */
+    targetSeed?: string;
+    /**
+     * SQLite ON DELETE rule applied to the foreign-key constraint.
+     * Defaults to 'SET NULL' when `type === 'relation'` and no value is provided.
+     * - CASCADE  : delete dependent rows when the parent is deleted.
+     * - SET NULL : null out the column when the parent is deleted (default).
+     * - RESTRICT : block parent deletion while dependent rows exist.
+     *
+     * NOTE: When `multiple: true` (introduced in Sprint 5 for many-to-many), this
+     * rule applies to the FK from the junction table to the target table.
+     */
+    onDelete?: 'CASCADE' | 'SET NULL' | 'RESTRICT';
+    /**
+     * Sub-schema for `type === 'repeater'`. Each item of the repeater's array
+     * value is a record keyed by sub-branch alias, validated against this list.
+     * Sub-branches are restricted to leaf/scalar types (no nested `repeater`,
+     * `relation`, or `file`) — enforced by validation.ts and seed-validation.ts.
+     * Ignored for any other branch type.
+     */
+    fields?: Branch[];
+    /**
+     * Minimum number of items a `repeater` value must contain when a value is
+     * provided. Repeater-only — ignored for every other branch type.
+     *
+     * NOTE: this constrains array *length when the field is present*. It does NOT by
+     * itself make the field mandatory — an absent/null payload is still allowed unless
+     * `requiredOnCreate` / `requiredOnUpdate` is also set. To model "exactly one
+     * required object", combine `minItems: 1, maxItems: 1, requiredOnCreate: true`.
+     * Must be a non-negative integer and `<= maxItems` when both are set
+     * (enforced at boot by seed-validation.ts).
+     */
+    minItems?: number;
+    /**
+     * Maximum number of items a `repeater` value may contain. Repeater-only — ignored
+     * for every other branch type. `maxItems: 1` models a single "object" column.
+     * Must be a non-negative integer and `>= minItems` when both are set.
+     */
+    maxItems?: number;
+}
+/** 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'. */
+    icon?: string;
+    /** Sidebar group label. Ungrouped seeds share a single 'Contents' section. */
+    group?: string;
+    /** Sort order within the group. Lower = higher. Default: 99. */
+    order?: number;
+    /** Hide from sidebar navigation. Default: false. */
+    hidden?: boolean;
+    /** Tooltip description shown in the sidebar. */
+    description?: string;
+    /** UI feature toggles. All default to true unless specified. */
+    features?: {
+        search?: boolean;
+        filter?: boolean;
+        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: schema definition of a content type. */
+export interface Seed {
+    /** Identifying slug — also the table name: `content_{slug}`. */
+    slug: string;
+    /** Singular UI label. */
+    label: string;
+    /** Plural UI label. Falls back to `label` when absent. */
+    labelPlural?: string;
+    /** Enable reads from the Public API (`GET /api/v1/public/:seed`). Default: false. */
+    allowPublicRead?: boolean;
+    /** Enable creation from the Public API (`POST /api/v1/public/:seed/add`). Default: false. */
+    allowPublicPost?: boolean;
+    /** Enable edits from the Public API (`PUT /api/v1/public/:seed/edit/:id`). Default: false. */
+    allowPublicEdit?: boolean;
+    /**
+     * 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 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;
+    /** List of fields (Branch). */
+    branches: Branch[];
+    /** Optional dashboard-specific UI config. Ignored by the Botanical Engine. */
+    dashboard?: DashboardSeedConfig;
+    /** Custom editor form layout. Absent when no override is stored.
+     *  Populated server-side by GET /api/schema. Ignored by the Botanical Engine.
+     *  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 {
+    /** 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. Joined by `filterLogic` (default AND); conditions within a group are always ANDed. */
+    filters?: FilterGroup[];
+    /** How top-level `filters` groups are combined. Defaults to 'AND'. */
+    filterLogic?: 'AND' | 'OR';
+    /** Sort column and direction. Ignored when `kanbanOrder` is set. */
+    orderBy?: {
+        column: string;
+        dir: 'ASC' | 'DESC';
+    };
+    /** LIMIT/OFFSET pagination. */
+    pagination?: {
+        limit: number;
+        offset: number;
+    };
+    /** Filters by status. null = no status filter. */
+    status?: string | null;
+    /** Full-text search — uses FTS5 if the seed has indexable richtext/text branches. */
+    search?: string;
+    /** 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;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"}

package/dist/engine/validation/cache.js

@@ -0,0 +1,136 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { z } from 'zod';
+import { schemaForBranch } 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. */
+const seedSchemaCache = new Map();
+/**
+ * Per-`idGenerator`-instance caches for seeds with relation branches.
+ * Partitioning by instance identity keeps schemas compiled with different
+ * generators (and thus different `isValid()` semantics) from colliding,
+ * without needing a stable identifier on {@link IIdGenerator}.
+ */
+const relationSchemaCacheByGenerator = new WeakMap();
+/**
+ * Retrieves a cache entry and marks it as most recently used.
+ *
+ * @param cache - The cache map to read from.
+ * @param key - The cache key.
+ * @returns The cached schema, or undefined if absent.
+ */
+function getCachedSchema(cache, key) {
+    const cached = cache.get(key);
+    if (cached) {
+        cache.delete(key);
+        cache.set(key, cached);
+    }
+    return cached;
+}
+/**
+ * Stores a cache entry, evicting the least recently used one if over capacity.
+ *
+ * @param cache - The cache map to write to.
+ * @param key - The cache key.
+ * @param value - The compiled schema to cache.
+ */
+function setCachedSchema(cache, key, value) {
+    if (cache.size >= SEED_SCHEMA_CACHE_MAX_SIZE) {
+        const oldestKey = cache.keys().next().value;
+        if (oldestKey !== undefined)
+            cache.delete(oldestKey);
+    }
+    cache.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 capture the idGenerator by closure, so their
+    // schemas are cached per generator instance instead of in the shared cache
+    // (different generators, e.g. SystemIdGenerator vs a test double, have
+    // different isValid() semantics).
+    const hasRelation = seed.branches.some((b) => b.type === 'relation');
+    const key = buildCacheKey(seed, options);
+    let cache;
+    if (hasRelation) {
+        if (options.idGenerator) {
+            cache = relationSchemaCacheByGenerator.get(options.idGenerator);
+            if (!cache) {
+                cache = new Map();
+                relationSchemaCacheByGenerator.set(options.idGenerator, cache);
+            }
+        }
+    }
+    else {
+        cache = seedSchemaCache;
+    }
+    if (cache) {
+        const cached = getCachedSchema(cache, 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 (cache)
+        setCachedSchema(cache, 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 or the list exceeds the cap.
+ */
+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;AAKD;;;;;;GAMG;AACH,wBAAgB,qBAAqB,CAAC,GAAG,EAAE,OAAO,GAAG,aAAa,EAAE,GAAG,IAAI,CAiB1E"}

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

@@ -0,0 +1,133 @@
+// 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) };
+}
+/** Maximum number of items accepted in an asset list to prevent unbounded processing. */
+const MAX_ASSET_LIST_ITEMS = 100;
+/**
+ * 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 or the list exceeds the cap.
+ */
+export function collectAssetListItems(raw) {
+    if (raw === null)
+        return null;
+    const source = typeof raw === 'string' ? tryParseJson(raw) : raw;
+    const items = Array.isArray(source) ? source : [source];
+    if (items.length > MAX_ASSET_LIST_ITEMS)
+        return null;
+    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;
+}