@beechcms/core 0.6.0-preview.1 → 0.6.0-preview.2

package/dist/dashboard-layout.d.ts

@@ -0,0 +1,154 @@
+import { z } from 'zod';
+import type { Seed } from './types.js';
+/** A placed widget. `type` is namespaced ('core/stat', '@acme/weather').
+ *  `config` is opaque to core/API except for the optional `seedSlug` key,
+ *  which enables auto-cleanup when the referenced seed disappears. */
+export interface DashboardWidgetInstance {
+    id: string;
+    type: string;
+    title?: string;
+    config: Record<string, unknown>;
+}
+export interface DashboardColumn {
+    id: string;
+    widgets: DashboardWidgetInstance[];
+}
+export interface DashboardSection {
+    id: string;
+    label?: string;
+    hideLabel?: boolean;
+    collapsible?: boolean;
+    /** 1–4 columns. Enforced by validator. */
+    columns: DashboardColumn[];
+    /** Optional spans on a 12-unit grid, parallel to `columns`, must sum to 12.
+     *  Absent = equal split. */
+    columnSpans?: number[];
+}
+export interface DashboardPageLayout {
+    id: string;
+    /** URL identity (?page=<slug>). Unique within the layout. */
+    slug: string;
+    label: string;
+    /** Lucide icon name, same convention as DashboardSeedConfig.icon. */
+    icon?: string;
+    sections: DashboardSection[];
+}
+export interface DashboardLayout {
+    /** Format version — bump when introducing breaking changes. */
+    version: 1;
+    pages: DashboardPageLayout[];
+}
+/** Namespaced widget type — lowercase npm-name-compatible.
+ *  Built-ins use the 'core/' prefix; custom widgets '@scope/name'. */
+export declare const WIDGET_TYPE_REGEX: RegExp;
+/** Max serialized size of a single widget `config`
+ *  (`JSON.stringify(widget.config).length`) — guards D1 row bloat. */
+export declare const MAX_WIDGET_CONFIG_BYTES = 8192;
+export declare const dashboardWidgetInstanceSchema: z.ZodObject<{
+    id: z.ZodString;
+    type: z.ZodString;
+    title: z.ZodOptional<z.ZodString>;
+    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+}, z.core.$strip>;
+export declare const dashboardColumnSchema: z.ZodObject<{
+    id: z.ZodString;
+    widgets: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        type: z.ZodString;
+        title: z.ZodOptional<z.ZodString>;
+        config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const dashboardSectionSchema: z.ZodObject<{
+    id: z.ZodString;
+    label: z.ZodOptional<z.ZodString>;
+    hideLabel: z.ZodOptional<z.ZodBoolean>;
+    collapsible: z.ZodOptional<z.ZodBoolean>;
+    columns: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        widgets: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            type: z.ZodString;
+            title: z.ZodOptional<z.ZodString>;
+            config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+    columnSpans: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+}, z.core.$strip>;
+export declare const dashboardPageSchema: z.ZodObject<{
+    id: z.ZodString;
+    slug: z.ZodString;
+    label: z.ZodString;
+    icon: z.ZodOptional<z.ZodString>;
+    sections: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        label: z.ZodOptional<z.ZodString>;
+        hideLabel: z.ZodOptional<z.ZodBoolean>;
+        collapsible: z.ZodOptional<z.ZodBoolean>;
+        columns: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            widgets: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                type: z.ZodString;
+                title: z.ZodOptional<z.ZodString>;
+                config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+            }, z.core.$strip>>;
+        }, z.core.$strip>>;
+        columnSpans: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const dashboardLayoutSchema: z.ZodObject<{
+    version: z.ZodLiteral<1>;
+    pages: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        slug: z.ZodString;
+        label: z.ZodString;
+        icon: z.ZodOptional<z.ZodString>;
+        sections: z.ZodArray<z.ZodObject<{
+            id: z.ZodString;
+            label: z.ZodOptional<z.ZodString>;
+            hideLabel: z.ZodOptional<z.ZodBoolean>;
+            collapsible: z.ZodOptional<z.ZodBoolean>;
+            columns: z.ZodArray<z.ZodObject<{
+                id: z.ZodString;
+                widgets: z.ZodArray<z.ZodObject<{
+                    id: z.ZodString;
+                    type: z.ZodString;
+                    title: z.ZodOptional<z.ZodString>;
+                    config: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+                }, z.core.$strip>>;
+            }, z.core.$strip>>;
+            columnSpans: z.ZodOptional<z.ZodArray<z.ZodNumber>>;
+        }, z.core.$strip>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/** Structural port of the legacy hardcoded dashboard config into a single
+ *  'Overview' page. Widgets fetch their own data: configs carry only the
+ *  variant and (where relevant) the default seed binding. */
+export declare function generateDefaultDashboardLayout(seeds: Seed[], opts?: {
+    newId: () => string;
+}): DashboardLayout;
+export interface DashboardLayoutContext {
+    /** Slugs of currently registered seeds (from ISeedRegistry.all()). */
+    seedSlugs: ReadonlySet<string>;
+    /** Optional: widget types known to the caller (frontend registry).
+     *  When provided, unknown types produce WARNINGS, never strips. */
+    knownWidgetTypes?: ReadonlySet<string>;
+}
+export type ValidateDashboardLayoutResult = {
+    ok: true;
+    cleaned: DashboardLayout;
+    warnings: string[];
+} | {
+    ok: false;
+    errors: string[];
+    cleaned: DashboardLayout;
+    warnings: string[];
+};
+/** Semantic validation on top of the Zod shape check (the caller's job).
+ *  Widgets bound to a seed that no longer exists are silently stripped
+ *  (auto-cleanup, recorded as a warning). Unknown widget types only warn —
+ *  custom widgets are invisible to the Worker and must never be stripped.
+ *  `cleaned` is always returned, errors or not. */
+export declare function validateDashboardLayout(layout: DashboardLayout, ctx: DashboardLayoutContext): ValidateDashboardLayoutResult;
+//# sourceMappingURL=dashboard-layout.d.ts.map

package/dist/dashboard-layout.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-layout.d.ts","sourceRoot":"","sources":["../src/dashboard-layout.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAA;AACvB,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAMtC;;sEAEsE;AACtE,MAAM,WAAW,uBAAuB;IACtC,EAAE,EAAE,MAAM,CAAA;IACV,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAChC;AAED,MAAM,WAAW,eAAe;IAC9B,EAAE,EAAE,MAAM,CAAA;IACV,OAAO,EAAE,uBAAuB,EAAE,CAAA;CACnC;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,CAAC,EAAE,MAAM,CAAA;IACd,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,0CAA0C;IAC1C,OAAO,EAAE,eAAe,EAAE,CAAA;IAC1B;gCAC4B;IAC5B,WAAW,CAAC,EAAE,MAAM,EAAE,CAAA;CACvB;AAED,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,6DAA6D;IAC7D,IAAI,EAAE,MAAM,CAAA;IACZ,KAAK,EAAE,MAAM,CAAA;IACb,qEAAqE;IACrE,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,gBAAgB,EAAE,CAAA;CAC7B;AAED,MAAM,WAAW,eAAe;IAC9B,+DAA+D;IAC/D,OAAO,EAAE,CAAC,CAAA;IACV,KAAK,EAAE,mBAAmB,EAAE,CAAA;CAC7B;AAMD;sEACsE;AACtE,eAAO,MAAM,iBAAiB,QAA6B,CAAA;AAE3D;sEACsE;AACtE,eAAO,MAAM,uBAAuB,OAAO,CAAA;AAM3C,eAAO,MAAM,6BAA6B;;;;;iBAKxC,CAAA;AACF,eAAO,MAAM,qBAAqB;;;;;;;;iBAGhC,CAAA;AACF,eAAO,MAAM,sBAAsB;;;;;;;;;;;;;;;iBAOjC,CAAA;AACF,eAAO,MAAM,mBAAmB;;;;;;;;;;;;;;;;;;;;;iBAM9B,CAAA;AACF,eAAO,MAAM,qBAAqB;;;;;;;;;;;;;;;;;;;;;;;;iBAGhC,CAAA;AAQF;;6DAE6D;AAC7D,wBAAgB,8BAA8B,CAC5C,KAAK,EAAE,IAAI,EAAE,EACb,IAAI,CAAC,EAAE;IAAE,KAAK,EAAE,MAAM,MAAM,CAAA;CAAE,GAC7B,eAAe,CA2EjB;AAMD,MAAM,WAAW,sBAAsB;IACrC,sEAAsE;IACtE,SAAS,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;IAC9B;uEACmE;IACnE,gBAAgB,CAAC,EAAE,WAAW,CAAC,MAAM,CAAC,CAAA;CACvC;AAED,MAAM,MAAM,6BAA6B,GACrC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,OAAO,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,GAC1D;IAAE,EAAE,EAAE,KAAK,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAC;IAAC,OAAO,EAAE,eAAe,CAAC;IAAC,QAAQ,EAAE,MAAM,EAAE,CAAA;CAAE,CAAA;AAEjF;;;;mDAImD;AACnD,wBAAgB,uBAAuB,CACrC,MAAM,EAAE,eAAe,EACvB,GAAG,EAAE,sBAAsB,GAC1B,6BAA6B,CA2E/B"}

package/dist/dashboard-layout.js

@@ -0,0 +1,186 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { z } from 'zod';
+// ---------------------------------------------------------------------------
+// Shared rules used by both the Zod schemas and the semantic validator.
+// ---------------------------------------------------------------------------
+/** Namespaced widget type — lowercase npm-name-compatible.
+ *  Built-ins use the 'core/' prefix; custom widgets '@scope/name'. */
+export const WIDGET_TYPE_REGEX = /^[a-z0-9@][a-z0-9@/_-]*$/;
+/** Max serialized size of a single widget `config`
+ *  (`JSON.stringify(widget.config).length`) — guards D1 row bloat. */
+export const MAX_WIDGET_CONFIG_BYTES = 8192;
+// ---------------------------------------------------------------------------
+// Zod schemas for shape validation
+// ---------------------------------------------------------------------------
+export const dashboardWidgetInstanceSchema = z.object({
+    id: z.string().min(1),
+    type: z.string().regex(WIDGET_TYPE_REGEX),
+    title: z.string().max(80).optional(),
+    config: z.record(z.string(), z.unknown()),
+});
+export const dashboardColumnSchema = z.object({
+    id: z.string().min(1),
+    widgets: z.array(dashboardWidgetInstanceSchema),
+});
+export const dashboardSectionSchema = z.object({
+    id: z.string().min(1),
+    label: z.string().max(60).optional(),
+    hideLabel: z.boolean().optional(),
+    collapsible: z.boolean().optional(),
+    columns: z.array(dashboardColumnSchema).min(1).max(4),
+    columnSpans: z.array(z.number().int().min(1).max(12)).optional(),
+});
+export const dashboardPageSchema = z.object({
+    id: z.string().min(1),
+    slug: z.string().regex(/^[a-z0-9][a-z0-9-]*$/).max(40),
+    label: z.string().min(1).max(60),
+    icon: z.string().max(40).optional(),
+    sections: z.array(dashboardSectionSchema).min(1),
+});
+export const dashboardLayoutSchema = z.object({
+    version: z.literal(1),
+    pages: z.array(dashboardPageSchema).min(1).max(8),
+});
+// ---------------------------------------------------------------------------
+// Default dashboard layout generator
+// ---------------------------------------------------------------------------
+const defaultIdFactory = () => crypto.randomUUID();
+/** Structural port of the legacy hardcoded dashboard config into a single
+ *  'Overview' page. Widgets fetch their own data: configs carry only the
+ *  variant and (where relevant) the default seed binding. */
+export function generateDefaultDashboardLayout(seeds, opts) {
+    const newId = opts?.newId ?? defaultIdFactory;
+    const widget = (type, config) => ({ id: newId(), type, config });
+    const singleWidgetColumn = (w) => ({
+        id: newId(),
+        widgets: [w],
+    });
+    const sections = [];
+    // Setup checklist, full width.
+    sections.push({
+        id: newId(),
+        hideLabel: true,
+        columns: [singleWidgetColumn(widget('core/setup-checklist', { variant: 'full' }))],
+    });
+    // Status row: equal columns; quick-draft needs at least one seed to target.
+    const statusWidgets = [
+        widget('core/site-status', { variant: 'badge' }),
+        widget('core/storage', { variant: 'gauge' }),
+        widget('core/publication-stats', { variant: 'trio' }),
+    ];
+    if (seeds.length > 0) {
+        statusWidgets.push(widget('core/quick-draft', { variant: 'minimal' }));
+    }
+    sections.push({
+        id: newId(),
+        hideLabel: true,
+        columns: statusWidgets.map(singleWidgetColumn),
+    });
+    if (seeds.length > 0) {
+        const seedSlug = seeds.find((s) => s.slug === 'articoli')?.slug ?? seeds[0].slug;
+        // Content row: recent content | pending drafts.
+        sections.push({
+            id: newId(),
+            hideLabel: true,
+            columns: [
+                singleWidgetColumn(widget('core/recent-content', { seedSlug, variant: 'list' })),
+                singleWidgetColumn(widget('core/pending-drafts', { seedSlug, variant: 'list' })),
+            ],
+            columnSpans: [6, 6],
+        });
+        // Media & activity row: media gallery | activity feed.
+        sections.push({
+            id: newId(),
+            hideLabel: true,
+            columns: [
+                singleWidgetColumn(widget('core/media-gallery', { seedSlug, variant: 'grid' })),
+                singleWidgetColumn(widget('core/activity-feed', { seedSlug, variant: 'feed' })),
+            ],
+            columnSpans: [6, 6],
+        });
+    }
+    return {
+        version: 1,
+        pages: [
+            {
+                id: newId(),
+                slug: 'overview',
+                label: 'Overview',
+                icon: 'LayoutDashboard',
+                sections,
+            },
+        ],
+    };
+}
+/** Semantic validation on top of the Zod shape check (the caller's job).
+ *  Widgets bound to a seed that no longer exists are silently stripped
+ *  (auto-cleanup, recorded as a warning). Unknown widget types only warn —
+ *  custom widgets are invisible to the Worker and must never be stripped.
+ *  `cleaned` is always returned, errors or not. */
+export function validateDashboardLayout(layout, ctx) {
+    const errors = [];
+    const warnings = [];
+    // Auto-cleanup: drop widgets whose config.seedSlug references a missing seed.
+    const cleanedPages = layout.pages.map((page) => ({
+        ...page,
+        sections: page.sections.map((section) => ({
+            ...section,
+            columns: section.columns.map((col) => ({
+                ...col,
+                widgets: (col.widgets ?? []).filter((w) => {
+                    const seedSlug = (w.config ?? {})['seedSlug'];
+                    if (typeof seedSlug === 'string' && !ctx.seedSlugs.has(seedSlug)) {
+                        warnings.push(`Widget '${w.type}' (id=${w.id}) removed: seed '${seedSlug}' is not registered.`);
+                        return false;
+                    }
+                    return true;
+                }),
+            })),
+        })),
+    }));
+    // Semantic checks on the cleaned layout
+    const seenWidgetIds = new Set();
+    const seenPageSlugs = new Set();
+    for (const page of cleanedPages) {
+        if (seenPageSlugs.has(page.slug)) {
+            errors.push(`Page slug '${page.slug}' appears more than once in the layout.`);
+        }
+        else {
+            seenPageSlugs.add(page.slug);
+        }
+        for (const section of page.sections) {
+            if (section.columnSpans !== undefined) {
+                if (section.columnSpans.length !== section.columns.length) {
+                    errors.push(`Section ${section.id}: columnSpans has ${section.columnSpans.length} entries for ${section.columns.length} columns.`);
+                }
+                else {
+                    const sum = section.columnSpans.reduce((acc, span) => acc + span, 0);
+                    if (sum !== 12) {
+                        errors.push(`Section ${section.id}: columnSpans must sum to 12, got ${sum}.`);
+                    }
+                }
+            }
+            for (const col of section.columns) {
+                for (const w of col.widgets) {
+                    if (seenWidgetIds.has(w.id)) {
+                        errors.push(`Widget id '${w.id}' appears more than once in the layout.`);
+                    }
+                    else {
+                        seenWidgetIds.add(w.id);
+                    }
+                    if (JSON.stringify(w.config ?? {}).length > MAX_WIDGET_CONFIG_BYTES) {
+                        errors.push(`Widget '${w.type}' (id=${w.id}): config exceeds ${MAX_WIDGET_CONFIG_BYTES} bytes when serialized.`);
+                    }
+                    if (ctx.knownWidgetTypes !== undefined && !ctx.knownWidgetTypes.has(w.type)) {
+                        warnings.push(`Widget '${w.type}' (id=${w.id}) is not a known widget type.`);
+                    }
+                }
+            }
+        }
+    }
+    const cleaned = { ...layout, pages: cleanedPages };
+    if (errors.length > 0)
+        return { ok: false, errors, cleaned, warnings };
+    return { ok: true, cleaned, warnings };
+}

package/dist/dashboard-layout.repository.d.ts

@@ -0,0 +1,18 @@
+import type { DashboardLayout } from './dashboard-layout.js';
+export interface DashboardLayoutRecord {
+    scope: string;
+    layout: DashboardLayout;
+    updatedAt: number;
+    updatedBy: string;
+}
+export interface IDashboardLayoutRepository {
+    /** Stored layout for a scope, or null if none was ever saved. */
+    get(scope: string): Promise<DashboardLayoutRecord | null>;
+    /** Scopes that currently have a stored row — used by the Sprint 06 builder UI. */
+    listScopes(): Promise<string[]>;
+    /** Upsert. `updatedBy` is the writer's user id. */
+    upsert(scope: string, layout: DashboardLayout, updatedBy: string): Promise<void>;
+    /** Remove the stored row — the "Reset" action. */
+    remove(scope: string): Promise<void>;
+}
+//# sourceMappingURL=dashboard-layout.repository.d.ts.map

package/dist/dashboard-layout.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-layout.repository.d.ts","sourceRoot":"","sources":["../src/dashboard-layout.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,uBAAuB,CAAA;AAE5D,MAAM,WAAW,qBAAqB;IACpC,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,eAAe,CAAA;IACvB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,0BAA0B;IACzC,iEAAiE;IACjE,GAAG,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,qBAAqB,GAAG,IAAI,CAAC,CAAA;IACzD,kFAAkF;IAClF,UAAU,IAAI,OAAO,CAAC,MAAM,EAAE,CAAC,CAAA;IAC/B,mDAAmD;IACnD,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,eAAe,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAChF,kDAAkD;IAClD,MAAM,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;CACrC"}

package/dist/dashboard-layout.repository.js

@@ -0,0 +1,3 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export {};

package/dist/dashboard-permissions.d.ts

@@ -0,0 +1,3 @@
+export declare const ROLES_ALLOWED_TO_EDIT_DASHBOARD: ReadonlyArray<string>;
+export declare function canEditDashboard(role: string | undefined | null): boolean;
+//# sourceMappingURL=dashboard-permissions.d.ts.map

package/dist/dashboard-permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-permissions.d.ts","sourceRoot":"","sources":["../src/dashboard-permissions.ts"],"names":[],"mappings":"AAMA,eAAO,MAAM,+BAA+B,EAAE,aAAa,CAAC,MAAM,CAAa,CAAA;AAE/E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,OAAO,CAGzE"}

package/dist/dashboard-permissions.js

@@ -0,0 +1,11 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+// NOTE: change this list to extend write-access to other roles
+// (e.g. add 'editor', or introduce a fine-grained 'dashboard:edit' permission).
+// Single source of truth — used by both API guards and dashboard buttons.
+export const ROLES_ALLOWED_TO_EDIT_DASHBOARD = ['admin'];
+export function canEditDashboard(role) {
+    if (!role)
+        return false;
+    return ROLES_ALLOWED_TO_EDIT_DASHBOARD.includes(role);
+}

package/dist/dashboard-scopes.d.ts

@@ -0,0 +1,12 @@
+/** Roles that may have their own dashboard layout. Single source of truth —
+ *  extend this list if a new role is introduced. */
+export declare const KNOWN_DASHBOARD_ROLES: ReadonlyArray<string>;
+export declare const DEFAULT_DASHBOARD_SCOPE = "default";
+/** Builds the per-role scope string, e.g. `roleScope('editor') === 'role:editor'`. */
+export declare function roleScope(role: string): string;
+/** Whether `scope` is one of the closed set: `'default' | 'role:<known role>'`. */
+export declare function isValidDashboardScope(scope: string): boolean;
+/** Read-resolution order for a caller's role: `['role:<role>', 'default']`,
+ *  or just `['default']` for unknown/missing roles. */
+export declare function resolveDashboardScopeChain(role: string | undefined | null): string[];
+//# sourceMappingURL=dashboard-scopes.d.ts.map

package/dist/dashboard-scopes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dashboard-scopes.d.ts","sourceRoot":"","sources":["../src/dashboard-scopes.ts"],"names":[],"mappings":"AAOA;oDACoD;AACpD,eAAO,MAAM,qBAAqB,EAAE,aAAa,CAAC,MAAM,CAAuB,CAAA;AAE/E,eAAO,MAAM,uBAAuB,YAAY,CAAA;AAEhD,sFAAsF;AACtF,wBAAgB,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAE9C;AAED,mFAAmF;AACnF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAK5D;AAED;uDACuD;AACvD,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,GAAG,IAAI,GAAG,MAAM,EAAE,CAKpF"}

package/dist/dashboard-scopes.js

@@ -0,0 +1,30 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+// ---------------------------------------------------------------------------
+// Dashboard layout scopes (Sprint 06: role-based dashboards)
+// ---------------------------------------------------------------------------
+/** Roles that may have their own dashboard layout. Single source of truth —
+ *  extend this list if a new role is introduced. */
+export const KNOWN_DASHBOARD_ROLES = ['admin', 'editor'];
+export const DEFAULT_DASHBOARD_SCOPE = 'default';
+/** Builds the per-role scope string, e.g. `roleScope('editor') === 'role:editor'`. */
+export function roleScope(role) {
+    return `role:${role}`;
+}
+/** Whether `scope` is one of the closed set: `'default' | 'role:<known role>'`. */
+export function isValidDashboardScope(scope) {
+    if (scope === DEFAULT_DASHBOARD_SCOPE)
+        return true;
+    const match = /^role:(.+)$/.exec(scope);
+    if (!match)
+        return false;
+    return KNOWN_DASHBOARD_ROLES.includes(match[1]);
+}
+/** Read-resolution order for a caller's role: `['role:<role>', 'default']`,
+ *  or just `['default']` for unknown/missing roles. */
+export function resolveDashboardScopeChain(role) {
+    if (role && KNOWN_DASHBOARD_ROLES.includes(role)) {
+        return [roleScope(role), DEFAULT_DASHBOARD_SCOPE];
+    }
+    return [DEFAULT_DASHBOARD_SCOPE];
+}

package/dist/engine.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EACV,IAAI,EACJ,MAAM,EAKN,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAqCnB,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAI5D;AAkED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CA0BtD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAyB5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAuBpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAc1D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAgCxD;AAID;;;;GAIG;AAGH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CAqE5F;AAgHD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;CACd;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,EAAE,CAiB7D;AAID;;;GAGG;AAEH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAmCrF;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAkBxE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM5E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAapF;AAcD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CA0BtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBzE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CA6BzE"}
+{"version":3,"file":"engine.d.ts","sourceRoot":"","sources":["../src/engine.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EACV,IAAI,EACJ,MAAM,EAKN,aAAa,EACb,kBAAkB,EACnB,MAAM,YAAY,CAAA;AAsCnB,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAI5D;AAkED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,CA0BtD;AAED;;;;GAIG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAyB5D;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAGpE;AAED;;;GAGG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAuBpD;AAED;;;GAGG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,GAAG,IAAI,CAc1D;AAED;;;;GAIG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAgCxD;AAID;;;;GAIG;AAGH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,IAAI,EAAE,OAAO,GAAE,aAAkB,GAAG,kBAAkB,CAqE5F;AAgHD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAA;IACZ,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;IACpC,OAAO,EAAE,OAAO,CAAA;IAChB,IAAI,EAAE,OAAO,CAAA;CACd;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,GAAG,YAAY,EAAE,CAiB7D;AAID;;;GAGG;AAEH,wBAAgB,cAAc,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,IAAI,CAwCrF;AAID;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,QAAQ,EAAE,MAAM,EAAE,WAAW,EAAE,MAAM,GAAG,MAAM,CAE/E;AAED;;;;;;;GAOG;AACH,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,CAkBxE;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAM5E;AAED;;;;;GAKG;AACH,wBAAgB,0BAA0B,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAapF;AAcD;;;;;;;;;GASG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CA0BtD;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAiBtE;AAED;;;;;;;;;;GAUG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBnF;AAED;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAkBzE;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,OAAO,GAAG,OAAO,CAqCzE"}

package/dist/engine.js

@@ -10,6 +10,7 @@ const BRANCH_TYPE_SQL = {
     file: { sqlType: 'TEXT' }, // URL singolo o JSON array di URL
     tags: { sqlType: 'TEXT' }, // JSON array di stringhe
     relation: { sqlType: 'TEXT' }, // FK reference stored as TEXT (id of the target row)
+    repeater: { sqlType: 'TEXT' }, // JSON array di record (sub-branch alias -> value)
 };
 const SYSTEM_COLUMNS = new Set(['id', 'slug', 'status', 'created_at', 'updated_at']);
 // ---- Private helpers ----
@@ -469,6 +470,10 @@ export function serializeForDb(branch, value) {
                 return Array.isArray(value) ? JSON.stringify(value) : typeof value === 'string' ? value : null;
             }
             return typeof value === 'string' ? value : null;
+        case 'repeater':
+            // Non-array input is rejected by serializing as an empty list — validation.ts
+            // is responsible for ever letting a non-array repeater value reach here.
+            return JSON.stringify(Array.isArray(value) ? value : []);
         default:
             return typeof value === 'string' ? value : typeof value === 'number' ? value : null;
     }
@@ -676,6 +681,14 @@ export function generateRetypeColumn(seed, branch) {
  * 0/1 → boolean | Unix timestamp → ISO 8601 | JSON string → object
  */
 export function deserializeFromDb(branch, value) {
+    // Repeater columns deserialize to [] (never null) — drafts and rows that
+    // predate the column being added carry NULL, which is an empty list of items.
+    if (branch.type === 'repeater') {
+        if (typeof value !== 'string' || value.length === 0)
+            return [];
+        const parsed = parseJsonSafe(value);
+        return Array.isArray(parsed) ? parsed : [];
+    }
     if (value === null || value === undefined)
         return null;
     switch (branch.type) {

package/dist/index.d.ts

@@ -51,6 +51,10 @@ export * from './demo-data.repository.js';
 export * from './seed-layout.js';
 export * from './seed-layout.repository.js';
 export * from './layout-permissions.js';
+export * from './dashboard-layout.js';
+export * from './dashboard-scopes.js';
+export * from './dashboard-permissions.js';
+export * from './dashboard-layout.repository.js';
 export * from './seed.repository.js';
 export * from './seed-validation.js';
 export * from './seed-ddl.js';

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,yBAAyB,CAAA;AACvC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2CAA2C,CAAA;AACzD,cAAc,8BAA8B,CAAA;AAC5C,cAAc,oCAAoC,CAAA;AAClD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,yCAAyC,CAAA;AACvD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,yCAAyC,CAAA;AACvD,cAAc,+BAA+B,CAAA;AAC7C,cAAc,+BAA+B,CAAA;AAC7C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,wBAAwB,CAAA;AACtC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,mCAAmC,CAAA;AACjD,cAAc,uCAAuC,CAAA;AACrD,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,yBAAyB,CAAA;AACvC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,+BAA+B,CAAA;AAC7C,cAAc,2BAA2B,CAAA;AACzC,cAAc,kBAAkB,CAAA;AAChC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,yBAAyB,CAAA;AACvC,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAGA;;;;;;;;GAQG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,kBAAkB,CAAA;AAChC,cAAc,YAAY,CAAA;AAC1B,cAAc,aAAa,CAAA;AAC3B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,eAAe,CAAA;AAC7B,cAAc,sBAAsB,CAAA;AACpC,cAAc,iBAAiB,CAAA;AAC/B,cAAc,yBAAyB,CAAA;AACvC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,uBAAuB,CAAA;AACrC,cAAc,cAAc,CAAA;AAC5B,cAAc,eAAe,CAAA;AAC7B,cAAc,yBAAyB,CAAA;AACvC,cAAc,yBAAyB,CAAA;AACvC,cAAc,2BAA2B,CAAA;AACzC,cAAc,8BAA8B,CAAA;AAC5C,cAAc,2CAA2C,CAAA;AACzD,cAAc,8BAA8B,CAAA;AAC5C,cAAc,oCAAoC,CAAA;AAClD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,yCAAyC,CAAA;AACvD,cAAc,4CAA4C,CAAA;AAC1D,cAAc,yCAAyC,CAAA;AACvD,cAAc,+BAA+B,CAAA;AAC7C,cAAc,+BAA+B,CAAA;AAC7C,cAAc,8BAA8B,CAAA;AAC5C,cAAc,YAAY,CAAA;AAC1B,cAAc,mBAAmB,CAAA;AACjC,cAAc,oBAAoB,CAAA;AAClC,cAAc,wBAAwB,CAAA;AACtC,cAAc,gCAAgC,CAAA;AAC9C,cAAc,mCAAmC,CAAA;AACjD,cAAc,uCAAuC,CAAA;AACrD,cAAc,0BAA0B,CAAA;AACxC,cAAc,qBAAqB,CAAA;AACnC,cAAc,yBAAyB,CAAA;AACvC,cAAc,gBAAgB,CAAA;AAC9B,cAAc,+BAA+B,CAAA;AAC7C,cAAc,2BAA2B,CAAA;AACzC,cAAc,kBAAkB,CAAA;AAChC,cAAc,6BAA6B,CAAA;AAC3C,cAAc,yBAAyB,CAAA;AACvC,cAAc,uBAAuB,CAAA;AACrC,cAAc,uBAAuB,CAAA;AACrC,cAAc,4BAA4B,CAAA;AAC1C,cAAc,kCAAkC,CAAA;AAChD,cAAc,sBAAsB,CAAA;AACpC,cAAc,sBAAsB,CAAA;AACpC,cAAc,eAAe,CAAA;AAC7B,cAAc,qBAAqB,CAAA"}

package/dist/index.js

@@ -53,6 +53,10 @@ export * from './demo-data.repository.js';
 export * from './seed-layout.js';
 export * from './seed-layout.repository.js';
 export * from './layout-permissions.js';
+export * from './dashboard-layout.js';
+export * from './dashboard-scopes.js';
+export * from './dashboard-permissions.js';
+export * from './dashboard-layout.repository.js';
 export * from './seed.repository.js';
 export * from './seed-validation.js';
 export * from './seed-ddl.js';

package/dist/policies.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK9D;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAazF"}
+{"version":3,"file":"policies.d.ts","sourceRoot":"","sources":["../src/policies.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,YAAY,CAAA;AAExC,wBAAsB,SAAS,CAAC,KAAK,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAK9D;AAED,wBAAsB,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAEzF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAgBzF"}

package/dist/policies.js

@@ -19,12 +19,15 @@ export function resolvePolicies(branch) {
     // Non-plain privacy implies hidden by default: the CMS hashes/encrypts on write,
     // so returning the stored value would leak the digest to readers.
     const defaultVisibility = privacy !== 'plain' ? 'hidden' : 'full';
+    // Repeaters live in a single JSON column — never filterable, sortable, or
+    // searchable/facetable in v1, regardless of what's set on the branch.
+    const isRepeater = branch.type === 'repeater';
     return {
         privacy,
         visibility: branch.policies?.visibility ?? defaultVisibility,
-        search: branch.policies?.search ?? true,
-        filter: branch.policies?.filter ?? true,
-        sort: branch.policies?.sort ?? true,
+        search: isRepeater ? false : branch.policies?.search ?? true,
+        filter: isRepeater ? false : branch.policies?.filter ?? true,
+        sort: isRepeater ? false : branch.policies?.sort ?? true,
         public: branch.policies?.public ?? true,
     };
 }

package/dist/seed-ddl-destructive.d.ts

@@ -0,0 +1,40 @@
+import type { Seed, BranchType } from './types.js';
+/**
+ * Ordered DROP TABLE statements for a full hard-delete of a seed's tables.
+ * Order: junction drafts → junctions → FTS triggers → FTS table → drafts → main table.
+ * All statements use IF EXISTS (idempotent).
+ */
+export declare function generateDropTable(seed: Seed): string[];
+/**
+ * DROP COLUMN statements for a single branch (by alias).
+ * For multi-relation branches: drops the junction tables (no column on parent).
+ * For regular branches: drops from main table + drafts table (if allowDrafts).
+ * Does NOT include FTS handling — callers must prepend ftsTriggerDrops() and
+ * append planFtsRebuild() when the branch is searchable.
+ */
+export declare function generateDropColumn(seed: Seed, alias: string): string[];
+/**
+ * RENAME COLUMN statements for a branch alias change.
+ * Updates main table + drafts (if allowDrafts).
+ * Does NOT handle FTS — callers must rebuild FTS separately (SQLite auto-updates
+ * trigger bodies on RENAME but the FTS virtual-table columns keep the old name).
+ */
+export declare function generateRenameColumn(seed: Seed, fromAlias: string, toAlias: string): string[];
+/**
+ * Full FTS rebuild: drop triggers + FTS table, then recreate them, then backfill.
+ * Returns an empty array if the seed has no searchable branches.
+ * The drop steps use IF EXISTS so this is safe to call even if FTS was already dropped.
+ */
+export declare function planFtsRebuild(seed: Seed): string[];
+export interface RetypeColumnPlan {
+    statements: string[];
+    ftsRebuildNeeded: boolean;
+}
+/**
+ * Generates statements to change a branch's SQL storage type using the
+ * add-new-column / copy / drop-old / rename approach.
+ * Includes FTS rebuild statements when the branch is (or becomes) searchable.
+ * `updatedSeed` must already reflect the new type on the renamed branch.
+ */
+export declare function planRetypeColumn(seed: Seed, alias: string, newType: BranchType, updatedSeed: Seed): RetypeColumnPlan;
+//# sourceMappingURL=seed-ddl-destructive.d.ts.map

package/dist/seed-ddl-destructive.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"seed-ddl-destructive.d.ts","sourceRoot":"","sources":["../src/seed-ddl-destructive.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAU,UAAU,EAAE,MAAM,YAAY,CAAA;AAkC1D;;;;GAIG;AACH,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAgBtD;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,IAAI,EAAE,IAAI,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAgBtE;AAED;;;;;GAKG;AACH,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,MAAM,EAAE,CAQ7F;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,IAAI,GAAG,MAAM,EAAE,CAiBnD;AAED,MAAM,WAAW,gBAAgB;IAC/B,UAAU,EAAE,MAAM,EAAE,CAAA;IACpB,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,IAAI,EACV,KAAK,EAAE,MAAM,EACb,OAAO,EAAE,UAAU,EACnB,WAAW,EAAE,IAAI,GAChB,gBAAgB,CAyClB"}

package/dist/seed-ddl-destructive.js

@@ -0,0 +1,149 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { junctionTableName, generateFtsTable, generateFtsTriggers } from './engine.js';
+const BRANCH_SQL_TYPE = {
+    text: 'TEXT',
+    number: 'REAL',
+    boolean: 'INTEGER',
+    date: 'INTEGER',
+    json: 'TEXT',
+    richtext: 'TEXT',
+    file: 'TEXT',
+    tags: 'TEXT',
+    relation: 'TEXT',
+    repeater: 'TEXT',
+};
+/** Branch types that receive a B-tree index in generateIndexes (used by retype to drop/recreate). */
+const INDEXABLE_TYPES = new Set(['text', 'number', 'date', 'boolean', 'relation']);
+function searchBranches(seed) {
+    return seed.branches.filter(b => (b.type === 'text' || b.type === 'richtext') && b.policies?.search !== false);
+}
+function ftsTriggerDrops(slug) {
+    return [
+        `DROP TRIGGER IF EXISTS fts_${slug}_insert;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_update;`,
+        `DROP TRIGGER IF EXISTS fts_${slug}_delete;`,
+        `DROP TABLE IF EXISTS fts_${slug};`,
+    ];
+}
+/**
+ * Ordered DROP TABLE statements for a full hard-delete of a seed's tables.
+ * Order: junction drafts → junctions → FTS triggers → FTS table → drafts → main table.
+ * All statements use IF EXISTS (idempotent).
+ */
+export function generateDropTable(seed) {
+    const stmts = [];
+    const { slug } = seed;
+    for (const branch of seed.branches) {
+        if (branch.type !== 'relation' || branch.multiple !== true)
+            continue;
+        const jt = junctionTableName(slug, branch.alias);
+        stmts.push(`DROP TABLE IF EXISTS ${jt}_drafts;`);
+        stmts.push(`DROP TABLE IF EXISTS ${jt};`);
+    }
+    stmts.push(...ftsTriggerDrops(slug));
+    stmts.push(`DROP TABLE IF EXISTS content_${slug}_drafts;`);
+    stmts.push(`DROP TABLE IF EXISTS content_${slug};`);
+    return stmts;
+}
+/**
+ * DROP COLUMN statements for a single branch (by alias).
+ * For multi-relation branches: drops the junction tables (no column on parent).
+ * For regular branches: drops from main table + drafts table (if allowDrafts).
+ * Does NOT include FTS handling — callers must prepend ftsTriggerDrops() and
+ * append planFtsRebuild() when the branch is searchable.
+ */
+export function generateDropColumn(seed, alias) {
+    const stmts = [];
+    const { slug } = seed;
+    const branch = seed.branches.find(b => b.alias === alias);
+    if (!branch)
+        throw new Error(`Branch '${alias}' not found in seed '${slug}'`);
+    if (branch.type === 'relation' && branch.multiple === true) {
+        const jt = junctionTableName(slug, alias);
+        if (seed.allowDrafts)
+            stmts.push(`DROP TABLE IF EXISTS ${jt}_drafts;`);
+        stmts.push(`DROP TABLE IF EXISTS ${jt};`);
+    }
+    else {
+        stmts.push(`ALTER TABLE content_${slug} DROP COLUMN ${alias};`);
+        if (seed.allowDrafts)
+            stmts.push(`ALTER TABLE content_${slug}_drafts DROP COLUMN ${alias};`);
+    }
+    return stmts;
+}
+/**
+ * RENAME COLUMN statements for a branch alias change.
+ * Updates main table + drafts (if allowDrafts).
+ * Does NOT handle FTS — callers must rebuild FTS separately (SQLite auto-updates
+ * trigger bodies on RENAME but the FTS virtual-table columns keep the old name).
+ */
+export function generateRenameColumn(seed, fromAlias, toAlias) {
+    const stmts = [];
+    const { slug } = seed;
+    stmts.push(`ALTER TABLE content_${slug} RENAME COLUMN ${fromAlias} TO ${toAlias};`);
+    if (seed.allowDrafts) {
+        stmts.push(`ALTER TABLE content_${slug}_drafts RENAME COLUMN ${fromAlias} TO ${toAlias};`);
+    }
+    return stmts;
+}
+/**
+ * Full FTS rebuild: drop triggers + FTS table, then recreate them, then backfill.
+ * Returns an empty array if the seed has no searchable branches.
+ * The drop steps use IF EXISTS so this is safe to call even if FTS was already dropped.
+ */
+export function planFtsRebuild(seed) {
+    const rtBranches = searchBranches(seed);
+    if (rtBranches.length === 0)
+        return [];
+    const { slug } = seed;
+    const stmts = [...ftsTriggerDrops(slug)];
+    const ftsTable = generateFtsTable(seed);
+    if (ftsTable)
+        stmts.push(ftsTable);
+    stmts.push(...generateFtsTriggers(seed));
+    const cols = rtBranches.map(b => b.alias);
+    stmts.push(`INSERT INTO fts_${slug}(entry_id, ${cols.join(', ')}) SELECT id, ${cols.join(', ')} FROM content_${slug};`);
+    return stmts;
+}
+/**
+ * Generates statements to change a branch's SQL storage type using the
+ * add-new-column / copy / drop-old / rename approach.
+ * Includes FTS rebuild statements when the branch is (or becomes) searchable.
+ * `updatedSeed` must already reflect the new type on the renamed branch.
+ */
+export function planRetypeColumn(seed, alias, newType, updatedSeed) {
+    const branch = seed.branches.find(b => b.alias === alias);
+    if (!branch)
+        throw new Error(`Branch '${alias}' not found in seed '${seed.slug}'`);
+    const { slug } = seed;
+    const newSqlType = BRANCH_SQL_TYPE[newType];
+    const tmpAlias = `${alias}_migrate`;
+    const stmts = [];
+    // Always drop FTS first to avoid "column referenced in trigger" errors on DROP COLUMN.
+    stmts.push(...ftsTriggerDrops(slug));
+    // Drop the branch index if it exists on the old column (required before DROP COLUMN).
+    if (INDEXABLE_TYPES.has(branch.type) && branch.policies?.filter !== false) {
+        stmts.push(`DROP INDEX IF EXISTS idx_${slug}_${alias};`);
+    }
+    // Main table: add migration column, copy data, drop old, rename.
+    stmts.push(`ALTER TABLE content_${slug} ADD COLUMN ${tmpAlias} ${newSqlType};`);
+    stmts.push(`UPDATE content_${slug} SET ${tmpAlias} = CAST(${alias} AS ${newSqlType});`);
+    stmts.push(`ALTER TABLE content_${slug} DROP COLUMN ${alias};`);
+    stmts.push(`ALTER TABLE content_${slug} RENAME COLUMN ${tmpAlias} TO ${alias};`);
+    // Recreate index for the renamed column if the new type warrants it.
+    if (INDEXABLE_TYPES.has(newType) && branch.policies?.filter !== false) {
+        stmts.push(`CREATE INDEX IF NOT EXISTS idx_${slug}_${alias} ON content_${slug}(${alias});`);
+    }
+    // Drafts table (no indexes to worry about).
+    if (seed.allowDrafts) {
+        stmts.push(`ALTER TABLE content_${slug}_drafts ADD COLUMN ${tmpAlias} ${newSqlType};`);
+        stmts.push(`UPDATE content_${slug}_drafts SET ${tmpAlias} = CAST(${alias} AS ${newSqlType});`);
+        stmts.push(`ALTER TABLE content_${slug}_drafts DROP COLUMN ${alias};`);
+        stmts.push(`ALTER TABLE content_${slug}_drafts RENAME COLUMN ${tmpAlias} TO ${alias};`);
+    }
+    // Rebuild FTS if the seed has searchable branches in the updated definition.
+    const rebuild = planFtsRebuild(updatedSeed);
+    stmts.push(...rebuild);
+    return { statements: stmts, ftsRebuildNeeded: rebuild.length > 0 };
+}

package/dist/seed-validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../src/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAsB,CAAA;AAElD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,mBAAmB,EAAE,CA6I5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}
+{"version":3,"file":"seed-validation.d.ts","sourceRoot":"","sources":["../src/seed-validation.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAMtC;;;;;;GAMG;AACH,eAAO,MAAM,eAAe,QAAyB,CAAA;AAErD,MAAM,WAAW,mBAAmB;IAClC,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,MAAM,EAAE,CAAA;IAClB,KAAK,EAAE,OAAO,CAAA;CACf;AAED;;;;GAIG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,mBAAmB,EAAE,CA0N5E;AAED,6CAA6C;AAC7C,wBAAgB,cAAc,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,OAAO,CAErD"}

package/dist/seed-validation.js

@@ -10,7 +10,7 @@ const BRANCH_ID_RE = /^br_[A-Za-z0-9]+$/;
  * prevent DDL/query injection. Exported so the seeds API rename route reuses the
  * exact same guard — do not inline a divergent copy.
  */
-export const BRANCH_ALIAS_RE = /^[a-z][a-z0-9_]*$/;
+export const BRANCH_ALIAS_RE = /^[a-z][a-zA-Z0-9_]*$/;
 /**
  * Pure, console-free, throw-free validation of a seed set.
  * The single seed being created/edited should be validated in the context of
@@ -93,7 +93,7 @@ export function validateSeedDefinitions(seeds) {
             // identifier charset before it can reach DDL/query string interpolation.
             if (typeof branch.alias !== 'string' || !BRANCH_ALIAS_RE.test(branch.alias)) {
                 messages.push(`branch alias '${branch.alias}' is invalid. Expected format ${BRANCH_ALIAS_RE.source} ` +
-                    `(lowercase letter followed by lowercase letters, digits or underscores).`);
+                    `(lowercase letter followed by alphanumeric characters or underscores).`);
             }
         }
         if (messages.length > 0)
@@ -111,6 +111,44 @@ export function validateSeedDefinitions(seeds) {
         if (messages.length > 0)
             result.push({ slug: seed.slug, messages, fatal: true });
     }
+    // ── Fatal 10: repeater sub-field constraints ─────────────────────────────
+    {
+        const REPEATER_DISALLOWED_SUBTYPES = new Set(['repeater', 'relation', 'file']);
+        for (const seed of seeds) {
+            const messages = [];
+            for (const branch of seed.branches) {
+                if (branch.type !== 'repeater')
+                    continue;
+                const subIds = new Set();
+                const subAliases = new Set();
+                for (const sub of branch.fields ?? []) {
+                    if (REPEATER_DISALLOWED_SUBTYPES.has(sub.type)) {
+                        messages.push(`branch '${branch.alias}': sub-field '${sub.alias}' has disallowed type '${sub.type}'. ` +
+                            `Repeater sub-fields cannot be 'repeater', 'relation', or 'file' in v1.`);
+                    }
+                    if (!sub.id || !BRANCH_ID_RE.test(sub.id)) {
+                        messages.push(`branch '${branch.alias}': sub-field '${sub.alias}' has invalid id '${sub.id}'. ` +
+                            `Expected format ^br_[A-Za-z0-9]+$.`);
+                    }
+                    else if (subIds.has(sub.id)) {
+                        messages.push(`branch '${branch.alias}': duplicate sub-field id '${sub.id}'`);
+                    }
+                    if (sub.id)
+                        subIds.add(sub.id);
+                    if (typeof sub.alias !== 'string' || !BRANCH_ALIAS_RE.test(sub.alias)) {
+                        messages.push(`branch '${branch.alias}': sub-field alias '${sub.alias}' is invalid. ` +
+                            `Expected format ${BRANCH_ALIAS_RE.source}.`);
+                    }
+                    else if (subAliases.has(sub.alias)) {
+                        messages.push(`branch '${branch.alias}': duplicate sub-field alias '${sub.alias}'`);
+                    }
+                    subAliases.add(sub.alias);
+                }
+            }
+            if (messages.length > 0)
+                result.push({ slug: seed.slug, messages, fatal: true });
+        }
+    }
     // ── Warning 7: duplicate slug ─────────────────────────────────────────────
     {
         const slugsSeen = new Set();
@@ -148,6 +186,36 @@ export function validateSeedDefinitions(seeds) {
             });
         }
     }
+    // ── Fatal 11 / Warning 10: repeater cardinality bounds ───────────────────
+    {
+        for (const seed of seeds) {
+            const fatals = [];
+            const warnings = [];
+            for (const branch of seed.branches) {
+                const hasBounds = branch.minItems !== undefined || branch.maxItems !== undefined;
+                if (!hasBounds)
+                    continue;
+                if (branch.type !== 'repeater') {
+                    warnings.push(`branch '${branch.alias}': minItems/maxItems are ignored on type ` +
+                        `'${branch.type}' (repeater-only).`);
+                    continue;
+                }
+                for (const [key, val] of [['minItems', branch.minItems], ['maxItems', branch.maxItems]]) {
+                    if (val !== undefined && (!Number.isInteger(val) || val < 0)) {
+                        fatals.push(`branch '${branch.alias}': ${key} must be a non-negative integer (got ${val}).`);
+                    }
+                }
+                if (Number.isInteger(branch.minItems) && Number.isInteger(branch.maxItems) &&
+                    branch.minItems > branch.maxItems) {
+                    fatals.push(`branch '${branch.alias}': minItems (${branch.minItems}) must be <= maxItems (${branch.maxItems}).`);
+                }
+            }
+            if (fatals.length > 0)
+                result.push({ slug: seed.slug, messages: fatals, fatal: true });
+            if (warnings.length > 0)
+                result.push({ slug: seed.slug, messages: warnings, fatal: false });
+        }
+    }
     return result;
 }
 /** Convenience: true iff no fatal issues. */

package/dist/types.d.ts

@@ -1,5 +1,5 @@
 import type { FileAccept } from './file-types.js';
-export type BranchType = 'text' | 'number' | 'boolean' | 'json' | 'date' | 'richtext' | 'file' | 'tags' | 'relation';
+export type BranchType = 'text' | 'number' | 'boolean' | 'json' | 'date' | 'richtext' | 'file' | 'tags' | 'relation' | 'repeater';
 /** Configurazioni specializzate per il tipo di branch 'number' */
 export interface NumberFieldOptions {
     /** Stile di presentazione visiva. Default: 'decimal' */
@@ -120,6 +120,32 @@ export interface Branch {
      * 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 {

package/dist/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}

package/dist/validation.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAE9C,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC/B,2BAA2B,CAAC,EAAE,OAAO,CAAA;IACrC,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAuBD,QAAA,MAAM,aAAa,2CAA4C,CAAA;AAmD/D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAM1F;AA8hBD;;;;;;GAMG;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;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAE5F"}
+{"version":3,"file":"validation.d.ts","sourceRoot":"","sources":["../src/validation.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,MAAM,EAAc,IAAI,EAAE,MAAM,YAAY,CAAA;AAE1D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,iBAAiB,CAAA;AAEjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,mBAAmB,CAAA;AAErD,MAAM,WAAW,gBAAgB;IAC/B,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,MAAM,CAAA;IAChB,QAAQ,EAAE,MAAM,CAAA;IAChB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,0BAA0B;IACzC,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,SAAS,CAAC,EAAE,QAAQ,GAAG,QAAQ,CAAA;IAC/B,2BAA2B,CAAC,EAAE,OAAO,CAAA;IACrC,qBAAqB,CAAC,EAAE,OAAO,CAAA;IAC/B,aAAa,CAAC,EAAE,MAAM,CAAA;IACtB;;;;;OAKG;IACH,WAAW,CAAC,EAAE,YAAY,CAAA;CAC3B;AAED,MAAM,WAAW,yBAAyB;IACxC,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC7B,OAAO,EAAE,gBAAgB,EAAE,CAAA;IAC3B,cAAc,EAAE,MAAM,EAAE,CAAA;IACxB,eAAe,EAAE,MAAM,EAAE,CAAA;IACzB,qBAAqB,EAAE,MAAM,EAAE,CAAA;IAC/B,gBAAgB,EAAE,OAAO,CAAA;CAC1B;AAuBD,QAAA,MAAM,aAAa,2CAA4C,CAAA;AAmD/D,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,MAAM,EAAE,UAAU,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,CAM1F;AA2lBD;;;;;;GAMG;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;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,CAAC,OAAO,aAAa,CAAC,CAAC,MAAM,CAAC,CAE5F"}

package/dist/validation.js

@@ -348,6 +348,33 @@ function fileSchema(branch, allowNull) {
         .pipe(z.string().url());
     return withNullable(withEmptyPreprocessing(inner, allowNull), allowNull);
 }
+// Sub-branches of a `repeater` are restricted to leaf/scalar types — no nested
+// `repeater`, `relation`, or `file` (v1 restriction, see types.ts Branch.fields).
+const REPEATER_DISALLOWED_SUBTYPES = new Set(['repeater', 'relation', 'file']);
+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 = {};
+    for (const sub of subBranches) {
+        const subSchema = schemaForBranch(sub, options);
+        shape[sub.alias] = sub[requiredFlag] ? subSchema : subSchema.optional();
+    }
+    // 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);
+    let arraySchema = z.array(itemSchema);
+    if (Number.isInteger(branch.minItems) && branch.minItems >= 0) {
+        arraySchema = arraySchema.min(branch.minItems, {
+            message: `Expected array(min:${branch.minItems})`,
+        });
+    }
+    if (Number.isInteger(branch.maxItems) && branch.maxItems >= 0) {
+        arraySchema = arraySchema.max(branch.maxItems, {
+            message: `Expected array(max:${branch.maxItems})`,
+        });
+    }
+    return withNullable(withEmptyPreprocessing(arraySchema, options.allowNull), options.allowNull);
+}
 const BRANCH_SCHEMA_BUILDERS = {
     text: (_branch, options) => textSchema(options, options.allowNull),
     richtext: (_branch, options) => richtextSchema(options, options.allowNull),
@@ -358,6 +385,7 @@ const BRANCH_SCHEMA_BUILDERS = {
     tags: (_branch, options) => jsonOrTagsSchema(options.allowNull),
     file: (branch, options) => fileSchema(branch, options.allowNull),
     relation: (branch, options) => relationSchema(branch, options),
+    repeater: (branch, options) => repeaterSchema(branch, options),
 };
 function schemaForBranch(branch, options) {
     const builder = BRANCH_SCHEMA_BUILDERS[branch.type];
@@ -380,6 +408,14 @@ function buildSeedFingerprint(seed) {
         ru: branch.requiredOnUpdate === true,
         n: branch.numberOptions ?? null,
         fi: branch.fileOptions ?? null,
+        mi: branch.minItems ?? null,
+        ma: branch.maxItems ?? null,
+        sub: branch.fields?.map((sub) => ({
+            a: sub.alias,
+            t: sub.type,
+            rc: sub.requiredOnCreate === true,
+            ru: sub.requiredOnUpdate === true,
+        })) ?? null,
     }));
     return JSON.stringify({ s: seed.slug, b: parts });
 }
@@ -500,11 +536,32 @@ function splitUnknownAliases(seed, payload) {
     }
     return { filtered, unknown, details };
 }
+function flattenZodIssues(issues, parentPath = []) {
+    const result = [];
+    for (const issue of issues) {
+        const issuePath = issue.path;
+        const currentPath = [...parentPath, ...issuePath];
+        if (issue.code === 'invalid_union' && 'errors' in issue) {
+            const unionErrors = issue.errors;
+            for (const subIssues of unionErrors) {
+                result.push(...flattenZodIssues(subIssues, currentPath));
+            }
+        }
+        else {
+            result.push({
+                ...issue,
+                path: currentPath,
+            });
+        }
+    }
+    return result;
+}
 function processZodIssues(seed, issues, filtered, options) {
     const details = [];
     const unknown = [];
     const dangerous = [];
-    for (const issue of issues) {
+    const flatIssues = flattenZodIssues(issues);
+    for (const issue of flatIssues) {
         if (issue.code === 'unrecognized_keys') {
             for (const alias of issue.keys) {
                 unknown.push(alias);

package/dist/widget/widget.repository.d.ts

@@ -36,6 +36,23 @@ export type AggregateFormula = {
  * 7 days, 1 month, and 1 year respectively, anchored on `created_at`.
  */
 export type TimeWindow = 'week' | 'month' | 'year' | 'all';
+/**
+ * Explicit time range applied as a WHERE filter, anchored on `created_at`.
+ *
+ * Both bounds are unix seconds (inclusive). Used when the dashboard sets a
+ * custom date reference instead of one of the relative {@link TimeWindow} presets.
+ */
+export interface DateRange {
+    from: number;
+    to: number;
+}
+/**
+ * Time filter accepted by widget queries: either a relative preset
+ * ({@link TimeWindow}) or an explicit {@link DateRange}.
+ */
+export type WidgetWindow = TimeWindow | DateRange;
+/** Narrows a {@link WidgetWindow} to a {@link DateRange}. */
+export declare function isDateRange(window: WidgetWindow): window is DateRange;
 export interface LeaderboardEntry {
     id: string;
     label: string;
@@ -71,6 +88,10 @@ export interface GrowthResult {
     currentValue: number;
     previousValue: number;
 }
+export interface DistributionSlice {
+    label: string;
+    value: number;
+}
 /**
  * Read-only data access contract for widget routes.
  *
@@ -84,14 +105,14 @@ export interface IWidgetRepository {
      * Returns the formula result for the given time window. Always returns a
      * number; implementations must return 0 when the query produces no rows.
      */
-    aggregate(seed: Seed, formula: AggregateFormula, window: TimeWindow): Promise<number>;
+    aggregate(seed: Seed, formula: AggregateFormula, window: WidgetWindow): Promise<number>;
     /**
      * Evaluates the formula twice — once for the current window period and once
      * for the equivalent previous period — to support trend calculations.
      * Implementations must return { currentValue: 0, previousValue: 0 } on
      * empty results.
      */
-    growth(seed: Seed, formula: AggregateFormula, window: TimeWindow): Promise<GrowthResult>;
+    growth(seed: Seed, formula: AggregateFormula, window: WidgetWindow): Promise<GrowthResult>;
     /**
      * Returns entries sorted by scoreColumn, excluding nulls. label resolves
      * from seed.displayNameAlias; falls back to id when not set.
@@ -108,6 +129,14 @@ export interface IWidgetRepository {
      * the formula. Days with no entries are omitted (no zero-fill). Points are
      * ordered ascending by label.
      */
-    timeseries(seed: Seed, formula: AggregateFormula, window: TimeWindow, groupColumn: string): Promise<TimeseriesPoint[]>;
+    timeseries(seed: Seed, formula: AggregateFormula, window: WidgetWindow, groupColumn: string): Promise<TimeseriesPoint[]>;
+    /**
+     * Counts entries grouped by the values of `column` within the window,
+     * descending by count, capped at `limit` slices. Implementations must
+     * validate `column` against the seed (UNSAFE_COLUMN on failure) and must
+     * return [] on empty results. Values beyond `limit` are NOT merged into
+     * an 'other' bucket — the client decides how to present truncation.
+     */
+    distribution(seed: Seed, column: string, window: WidgetWindow, limit: number): Promise<DistributionSlice[]>;
 }
 //# sourceMappingURL=widget.repository.d.ts.map

package/dist/widget/widget.repository.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"widget.repository.d.ts","sourceRoot":"","sources":["../../src/widget/widget.repository.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"widget.repository.d.ts","sourceRoot":"","sources":["../../src/widget/widget.repository.ts"],"names":[],"mappings":"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"}

package/dist/widget/widget.repository.js

@@ -1,3 +1,6 @@
 // SPDX-License-Identifier: MIT
 // Copyright (c) 2024–2026 Flavio De Musso
-export {};
+/** Narrows a {@link WidgetWindow} to a {@link DateRange}. */
+export function isDateRange(window) {
+    return typeof window === 'object' && window !== null;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@beechcms/core",
-  "version": "0.6.0-preview.1",
+  "version": "0.6.0-preview.2",
   "type": "module",
   "main": "./dist/index.js",
   "module": "./dist/index.js",