@beechcms/core 0.7.0 → 0.8.1

package/dist/rbac/invitation.repository.d.ts

@@ -0,0 +1,66 @@
+import type { Scope } from './permissions.js';
+/** One invitation row. `tokenHash` is deliberately absent: nothing above the storage
+ *  boundary ever needs it, and an administration listing must not carry credential
+ *  material (same rule as AccountSummary omitting passwordHash). */
+export interface InvitationRecord {
+    id: string;
+    email: string;
+    roleId: string;
+    scope: Scope;
+    invitedBy: string;
+    expiresAt: number;
+    createdAt: number;
+    /** Non-null once redeemed. Single-use is enforced by {@link IInvitationRepository.markUsed}. */
+    usedAt: number | null;
+}
+export interface NewInvitationInput {
+    email: string;
+    tokenHash: string;
+    roleId: string;
+    scope: Scope;
+    invitedBy: string;
+    expiresAt: number;
+}
+/** A live invitation resolved from a bearer token, with the pre-assignment it carries. */
+export interface ValidatedInvitation {
+    id: string;
+    email: string;
+    roleId: string;
+    scope: Scope;
+    invitedBy: string;
+}
+/**
+ * Storage contract for onboarding invitations.
+ *
+ * Deliberately shaped after {@link IPasswordResetTokenRepository}: a single-use,
+ * expiring, hash-only bearer credential is the same lifecycle, and the codebase keeps
+ * exactly one shape for it.
+ */
+export interface IInvitationRepository {
+    /** Consumes every pending invitation for an email before a new one is issued, so at
+     *  most one live token per address exists at any time. */
+    invalidatePending(email: string, nowTimestamp: number): Promise<void>;
+    /** Stores a new invitation. Only the hash is persisted, never the plaintext.
+     *  Returns the new invitation id. */
+    create(input: NewInvitationInput): Promise<string>;
+    /** Resolves a live (unused, unexpired) invitation by token hash. Null otherwise —
+     *  expired, already used and unknown are deliberately indistinguishable. */
+    findValidByHash(tokenHash: string, nowTimestamp: number): Promise<ValidatedInvitation | null>;
+    /**
+     * Consumes an invitation. Returns TRUE only when THIS call performed the transition
+     * (`used_at IS NULL` at write time), which is what makes redemption single-use under
+     * concurrency. A second concurrent redeem gets false and must be refused.
+     */
+    markUsed(invitationId: string, nowTimestamp: number): Promise<boolean>;
+    /** One invitation by id, regardless of state. Null when absent. */
+    findById(invitationId: string): Promise<InvitationRecord | null>;
+    /** Every invitation, newest first. Administration tables are small by nature. */
+    listAll(): Promise<InvitationRecord[]>;
+    /** Replaces the token and expiry of an existing PENDING-or-EXPIRED invitation,
+     *  preserving its (role, scope, email) pre-assignment. Returns false when the row is
+     *  absent or already used — a consumed invitation is never re-armed. */
+    regenerate(invitationId: string, tokenHash: string, expiresAt: number): Promise<boolean>;
+    /** Revokes (hard-deletes) an invitation. Returns false when it did not exist. */
+    delete(invitationId: string): Promise<boolean>;
+}
+//# sourceMappingURL=invitation.repository.d.ts.map

package/dist/rbac/invitation.repository.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"invitation.repository.d.ts","sourceRoot":"","sources":["../../src/rbac/invitation.repository.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAA;AAE7C;;oEAEoE;AACpE,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;IACjB,gGAAgG;IAChG,MAAM,EAAE,MAAM,GAAG,IAAI,CAAA;CACtB;AAED,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,MAAM,CAAA;IACb,SAAS,EAAE,MAAM,CAAA;IACjB,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;IACjB,SAAS,EAAE,MAAM,CAAA;CAClB;AAED,0FAA0F;AAC1F,MAAM,WAAW,mBAAmB;IAClC,EAAE,EAAE,MAAM,CAAA;IACV,KAAK,EAAE,MAAM,CAAA;IACb,MAAM,EAAE,MAAM,CAAA;IACd,KAAK,EAAE,KAAK,CAAA;IACZ,SAAS,EAAE,MAAM,CAAA;CAClB;AAED;;;;;;GAMG;AACH,MAAM,WAAW,qBAAqB;IACpC;8DAC0D;IAC1D,iBAAiB,CAAC,KAAK,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAA;IAErE;yCACqC;IACrC,MAAM,CAAC,KAAK,EAAE,kBAAkB,GAAG,OAAO,CAAC,MAAM,CAAC,CAAA;IAElD;gFAC4E;IAC5E,eAAe,CAAC,SAAS,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,mBAAmB,GAAG,IAAI,CAAC,CAAA;IAE7F;;;;OAIG;IACH,QAAQ,CAAC,YAAY,EAAE,MAAM,EAAE,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAEtE,mEAAmE;IACnE,QAAQ,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC,CAAA;IAEhE,iFAAiF;IACjF,OAAO,IAAI,OAAO,CAAC,gBAAgB,EAAE,CAAC,CAAA;IAEtC;;4EAEwE;IACxE,UAAU,CAAC,YAAY,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;IAExF,iFAAiF;IACjF,MAAM,CAAC,YAAY,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC,CAAA;CAC/C"}

package/dist/rbac/invitation.repository.js

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

package/dist/rbac/permissions.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The closed atomic permission vocabulary.
+ *
+ * This tuple is the single source of truth for what a role may contain. It is
+ * CLOSED BY DESIGN: new permissions arrive only as a developer code change plus a
+ * migration widening the `role_permissions` CHECK constraint. Nothing at runtime —
+ * no API, no plugin, no dashboard screen — may extend it.
+ *
+ * `manage_seeds` (or any schema-mutation permission) is deliberately absent and must
+ * never be added. Seed schema mutation stays a developer capability exercised outside
+ * the dashboard, via CLI and migrations.
+ *
+ * Each non-CRUD dashboard surface owns one dedicated permission (`view_analytics` is
+ * the first). Absence of the permission hides the surface; there is no default-visible
+ * exception.
+ */
+export declare const PERMISSIONS: readonly ["content:read", "content:create", "content:update", "content:delete", "manage_users", "manage_roles", "view_analytics"];
+/** A single atomic permission drawn from the closed vocabulary. */
+export type Permission = (typeof PERMISSIONS)[number];
+/**
+ * The sentinel scope granting a permission across every seed, present and future.
+ * Reserved for cross-cutting coordination roles (e.g. SuperAdmin).
+ */
+export declare const GLOBAL_SCOPE = "*";
+/**
+ * A permission perimeter: either {@link GLOBAL_SCOPE} or a `seeds.slug`.
+ * Isolation is per-seed, never row-level.
+ */
+export type Scope = string;
+/** Narrows an arbitrary string to a known permission. */
+export declare function isPermission(value: string): value is Permission;
+/**
+ * Name of the system role seeded by `0000_v040_base.sql` with the full permission set.
+ *
+ * `roles.name` is UNIQUE, so the name is a stable handle; the id is minted by the
+ * migration and differs per database, which is why nothing may hardcode it.
+ */
+export declare const SUPER_ADMIN_ROLE_NAME = "SuperAdmin";
+//# sourceMappingURL=permissions.d.ts.map

package/dist/rbac/permissions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.d.ts","sourceRoot":"","sources":["../../src/rbac/permissions.ts"],"names":[],"mappings":"AAGA;;;;;;;;;;;;;;;GAeG;AACH,eAAO,MAAM,WAAW,mIAQd,CAAA;AAEV,mEAAmE;AACnE,MAAM,MAAM,UAAU,GAAG,CAAC,OAAO,WAAW,CAAC,CAAC,MAAM,CAAC,CAAA;AAErD;;;GAGG;AACH,eAAO,MAAM,YAAY,MAAM,CAAA;AAE/B;;;GAGG;AACH,MAAM,MAAM,KAAK,GAAG,MAAM,CAAA;AAE1B,yDAAyD;AACzD,wBAAgB,YAAY,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,IAAI,UAAU,CAE/D;AAED;;;;;GAKG;AACH,eAAO,MAAM,qBAAqB,eAAe,CAAA"}

package/dist/rbac/permissions.js

@@ -0,0 +1,43 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * The closed atomic permission vocabulary.
+ *
+ * This tuple is the single source of truth for what a role may contain. It is
+ * CLOSED BY DESIGN: new permissions arrive only as a developer code change plus a
+ * migration widening the `role_permissions` CHECK constraint. Nothing at runtime —
+ * no API, no plugin, no dashboard screen — may extend it.
+ *
+ * `manage_seeds` (or any schema-mutation permission) is deliberately absent and must
+ * never be added. Seed schema mutation stays a developer capability exercised outside
+ * the dashboard, via CLI and migrations.
+ *
+ * Each non-CRUD dashboard surface owns one dedicated permission (`view_analytics` is
+ * the first). Absence of the permission hides the surface; there is no default-visible
+ * exception.
+ */
+export const PERMISSIONS = [
+    'content:read',
+    'content:create',
+    'content:update',
+    'content:delete',
+    'manage_users',
+    'manage_roles',
+    'view_analytics',
+];
+/**
+ * The sentinel scope granting a permission across every seed, present and future.
+ * Reserved for cross-cutting coordination roles (e.g. SuperAdmin).
+ */
+export const GLOBAL_SCOPE = '*';
+/** Narrows an arbitrary string to a known permission. */
+export function isPermission(value) {
+    return PERMISSIONS.includes(value);
+}
+/**
+ * Name of the system role seeded by `0000_v040_base.sql` with the full permission set.
+ *
+ * `roles.name` is UNIQUE, so the name is a stable handle; the id is minted by the
+ * migration and differs per database, which is why nothing may hardcode it.
+ */
+export const SUPER_ADMIN_ROLE_NAME = 'SuperAdmin';

package/dist/rbac/types.d.ts

@@ -0,0 +1,118 @@
+import type { Permission, Scope } from './permissions.js';
+/** A named, reusable bundle of atomic permissions. */
+export interface RoleRecord {
+    id: string;
+    name: string;
+    description: string | null;
+    icon?: string | null;
+    /** System roles (e.g. SuperAdmin) are seeded by migration and may not be deleted. */
+    isSystem: boolean;
+    /** Always a subset of `PERMISSIONS`; unknown values are dropped at the storage boundary. */
+    permissions: Permission[];
+    createdAt: number;
+    updatedAt: number;
+}
+/** One (user, role, scope) triple. A user may hold N independent assignments. */
+export interface PermissionAssignment {
+    id: string;
+    userId: string;
+    roleId: string;
+    scope: Scope;
+}
+export interface NewRoleInput {
+    name: string;
+    description: string | null;
+    icon?: string | null;
+    permissions: readonly Permission[];
+}
+export interface NewAssignmentInput {
+    userId: string;
+    roleId: string;
+    scope: Scope;
+}
+/**
+ * A caller's resolved authority, computed once per request from their active
+ * assignments. Purely additive: there is no negative permission and no conflict
+ * resolution between roles.
+ */
+export interface EffectivePermissions {
+    /** Permissions held at {@link GLOBAL_SCOPE}; they apply to every seed. */
+    global: ReadonlySet<Permission>;
+    /** Permissions held at a specific seed slug, keyed by that slug. */
+    byScope: ReadonlyMap<Scope, ReadonlySet<Permission>>;
+}
+/** Storage contract for roles and their permission bundles. */
+export interface IRoleRepository {
+    /** Retrieves a role with its permissions, or null when it does not exist. */
+    findById(roleId: string): Promise<RoleRecord | null>;
+    /** Retrieves several roles in one round trip. Missing ids are simply absent. */
+    findByIds(roleIds: readonly string[]): Promise<RoleRecord[]>;
+    /** Lists every role, system roles included, ordered by name. */
+    listAll(): Promise<RoleRecord[]>;
+    /** Creates a role and its permission rows atomically. Returns the new role id. */
+    create(input: NewRoleInput): Promise<string>;
+    /**
+     * Replaces a role's name, description and full permission set atomically.
+     *
+     * Returns false — changing NOTHING, permissions included — when the role does not
+     * exist or is a system role. System roles are seeded by migration and are immutable
+     * in both halves of the write, which is the guarantee callers rely on to keep
+     * `SuperAdmin` intact.
+     */
+    update(roleId: string, input: NewRoleInput): Promise<boolean>;
+    /**
+     * Deletes a non-system role and, by cascade, its permissions and assignments.
+     * Returns false when the role does not exist or is a system role.
+     */
+    delete(roleId: string): Promise<boolean>;
+}
+/** Storage contract for (user, role, scope) assignments. */
+export interface IRoleAssignmentRepository {
+    /**
+     * Lists a user's assignments that currently grant anything.
+     *
+     * An assignment is skipped when its scope names a seed that is absent or
+     * `status != 'active'`, so scopes decay with their seed and revive with it.
+     * {@link GLOBAL_SCOPE} assignments are always returned.
+     */
+    listActiveForUser(userId: string): Promise<PermissionAssignment[]>;
+    /** Lists every assignment referencing a role, decay filter NOT applied. */
+    listByRole(roleId: string): Promise<PermissionAssignment[]>;
+    /** Creates an assignment. Returns its id; an existing identical triple is a no-op. */
+    create(input: NewAssignmentInput): Promise<string>;
+    /** Removes one assignment. Returns false when it did not exist. */
+    delete(assignmentId: string): Promise<boolean>;
+    /**
+     * Counts accounts holding `manage_users` at {@link GLOBAL_SCOPE} and still active.
+     * Backs the last-SuperAdmin guardrail consumed by a later sprint.
+     */
+    countActiveGlobalAdmins(): Promise<number>;
+    /** One assignment by id, decay filter NOT applied. Null when absent. */
+    findById(assignmentId: string): Promise<PermissionAssignment | null>;
+    /**
+     * Every assignment in the system, decay filter NOT applied.
+     *
+     * Exists so the account-list endpoint can resolve each account's scopes in ONE round
+     * trip instead of one query per account. Administration tables are small by nature;
+     * content never flows through here.
+     */
+    listAll(): Promise<PermissionAssignment[]>;
+    /**
+     * Every assignment of one user, decay filter NOT applied — administration screens must
+     * see (and be able to remove) a row whose seed is currently deleted, which
+     * {@link listActiveForUser} deliberately hides.
+     */
+    listAllForUser(userId: string): Promise<PermissionAssignment[]>;
+    /**
+     * {@link countActiveGlobalAdmins} ignoring one user. `0` means that user is the last
+     * account able to administer the platform, and any operation revoking their authority
+     * must be refused.
+     */
+    countActiveGlobalAdminsExcludingUser(userId: string): Promise<number>;
+    /**
+     * {@link countActiveGlobalAdmins} ignoring every assignment that goes through one role.
+     * `0` means mutating that role would strip the platform of its last administrator.
+     */
+    countActiveGlobalAdminsExcludingRole(roleId: string): Promise<number>;
+}
+//# sourceMappingURL=types.d.ts.map

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

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

package/dist/rbac/types.js

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

package/dist/relations.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Back-reference helpers for the Beech CMS relation system.
+ *
+ * `buildBackrefMap` is a pure function that iterates the seed registry once
+ * and builds a lookup map: targetSlug → sources that point to it.
+ * Build this once at app factory time and cache it for the process lifetime.
+ */
+import type { Seed } from './types.js';
+export interface BackrefSource {
+    /** Slug of the seed that owns the relation branch */
+    sourceSlug: string;
+    /** `branch.alias` — the FK column name (single) or join-table name suffix (multi) */
+    branchAlias: string;
+    /** `branch.label` — human label for UI grouping */
+    branchLabel: string;
+    /** 'single' for direct FK, 'multi' for many-to-many join table */
+    relationship: 'single' | 'multi';
+    /** True when branch.onDelete === 'RESTRICT' — used to disable Delete button */
+    restricts: boolean;
+}
+/** Map: targetSlug → every source that points to it */
+export type BackrefMap = Map<string, BackrefSource[]>;
+/**
+ * Builds the back-reference map from an array of seeds.
+ * Pure function — no side-effects, safe to call at startup and cache forever.
+ */
+export declare function buildBackrefMap(seeds: Seed[]): BackrefMap;
+//# sourceMappingURL=relations.d.ts.map

package/dist/relations.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"relations.d.ts","sourceRoot":"","sources":["../src/relations.ts"],"names":[],"mappings":"AAGA;;;;;;GAMG;AACH,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,YAAY,CAAA;AAEtC,MAAM,WAAW,aAAa;IAC5B,qDAAqD;IACrD,UAAU,EAAE,MAAM,CAAA;IAClB,qFAAqF;IACrF,WAAW,EAAE,MAAM,CAAA;IACnB,mDAAmD;IACnD,WAAW,EAAE,MAAM,CAAA;IACnB,kEAAkE;IAClE,YAAY,EAAE,QAAQ,GAAG,OAAO,CAAA;IAChC,+EAA+E;IAC/E,SAAS,EAAE,OAAO,CAAA;CACnB;AAED,uDAAuD;AACvD,MAAM,MAAM,UAAU,GAAG,GAAG,CAAC,MAAM,EAAE,aAAa,EAAE,CAAC,CAAA;AAErD;;;GAGG;AACH,wBAAgB,eAAe,CAAC,KAAK,EAAE,IAAI,EAAE,GAAG,UAAU,CAoBzD"}

package/dist/relations.js

@@ -0,0 +1,25 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Builds the back-reference map from an array of seeds.
+ * Pure function — no side-effects, safe to call at startup and cache forever.
+ */
+export function buildBackrefMap(seeds) {
+    const map = new Map();
+    for (const seed of seeds) {
+        for (const branch of seed.branches) {
+            if (branch.type !== 'relation' || !branch.targetSeed)
+                continue;
+            const existing = map.get(branch.targetSeed) ?? [];
+            existing.push({
+                sourceSlug: seed.slug,
+                branchAlias: branch.alias,
+                branchLabel: branch.label,
+                relationship: branch.multiple === true ? 'multi' : 'single',
+                restricts: branch.onDelete === 'RESTRICT',
+            });
+            map.set(branch.targetSeed, existing);
+        }
+    }
+    return map;
+}

package/dist/richtext-render.d.ts

@@ -0,0 +1,11 @@
+import type { JSONContent } from '@tiptap/core';
+/**
+ * Accetta JSON TipTap (`{ type: 'doc', ... }`), envelope v1, o stringa HTML legacy.
+ */
+export declare function normalizeRichtextForRender(value: unknown): JSONContent | string | null;
+/**
+ * Render deterministico JSON → HTML (per display, anteprime, API pubblica).
+ * Per stringhe HTML legacy restituisce la stringa sanificata come pass-through (nessun parse TipTap).
+ */
+export declare function renderRichText(value: unknown): string;
+//# sourceMappingURL=richtext-render.d.ts.map

package/dist/richtext-render.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"richtext-render.d.ts","sourceRoot":"","sources":["../src/richtext-render.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,cAAc,CAAA;AAuD/C;;GAEG;AACH,wBAAgB,0BAA0B,CAAC,KAAK,EAAE,OAAO,GAAG,WAAW,GAAG,MAAM,GAAG,IAAI,CAatF;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAQrD"}

package/dist/richtext-render.js

@@ -0,0 +1,87 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+import { generateHTML } from '@tiptap/html';
+import Highlight from '@tiptap/extension-highlight';
+import Image from '@tiptap/extension-image';
+import Link from '@tiptap/extension-link';
+import Subscript from '@tiptap/extension-subscript';
+import Superscript from '@tiptap/extension-superscript';
+import { Table, TableCell, TableHeader, TableRow } from '@tiptap/extension-table';
+import TextAlign from '@tiptap/extension-text-align';
+import { Mathematics } from '@tiptap/extension-mathematics';
+import StarterKit from '@tiptap/starter-kit';
+import { isRichtextEnvelopeV1 } from './richtext.js';
+/**
+ * Allinea l'output HTML allo schema TipTap usato dall'editor dashboard.
+ * Mantieni sincronizzato con `apps/dashboard/src/features/richtext-editor/extensions/build-editor-extensions.ts`.
+ */
+function createRichTextHtmlExtensions() {
+    return [
+        StarterKit.configure({
+            link: false,
+            codeBlock: {
+                HTMLAttributes: {
+                    class: 'richtext-code-block',
+                },
+            },
+        }),
+        Link.configure({
+            openOnClick: false,
+            autolink: true,
+            defaultProtocol: 'https',
+        }),
+        Mathematics.configure({
+            katexOptions: {
+                throwOnError: false,
+            },
+        }),
+        Highlight,
+        Superscript,
+        Subscript,
+        Image.configure({
+            allowBase64: false,
+        }),
+        TextAlign.configure({
+            types: ['heading', 'paragraph'],
+        }),
+        Table.configure({
+            resizable: false,
+        }),
+        TableRow,
+        TableHeader,
+        TableCell,
+    ];
+}
+/**
+ * Accetta JSON TipTap (`{ type: 'doc', ... }`), envelope v1, o stringa HTML legacy.
+ */
+export function normalizeRichtextForRender(value) {
+    if (value == null || value === '')
+        return null;
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
+        const o = value;
+        if (isRichtextEnvelopeV1(value)) {
+            return o.doc;
+        }
+        if (o.type === 'doc') {
+            return value;
+        }
+    }
+    return null;
+}
+/**
+ * Render deterministico JSON → HTML (per display, anteprime, API pubblica).
+ * Per stringhe HTML legacy restituisce la stringa sanificata come pass-through (nessun parse TipTap).
+ */
+export function renderRichText(value) {
+    const normalized = normalizeRichtextForRender(value);
+    if (normalized == null)
+        return '';
+    if (typeof normalized === 'string') {
+        return normalized;
+    }
+    const extensions = createRichTextHtmlExtensions();
+    return generateHTML(normalized, extensions);
+}

package/dist/richtext.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Convenzione storage richtext TipTap nel Content Engine.
+ * @see docs/Sprints/tiptap-elevation.md
+ */
+export declare const RICHTEXT_SCHEMA_VERSION: 1;
+export type RichtextEnvelopeV1 = {
+    schemaVersion: typeof RICHTEXT_SCHEMA_VERSION;
+    doc: Record<string, unknown>;
+};
+export declare function isRichtextEnvelopeV1(value: unknown): value is RichtextEnvelopeV1;
+//# sourceMappingURL=richtext.d.ts.map

package/dist/richtext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"richtext.d.ts","sourceRoot":"","sources":["../src/richtext.ts"],"names":[],"mappings":"AAGA;;;GAGG;AACH,eAAO,MAAM,uBAAuB,EAAG,CAAU,CAAA;AAEjD,MAAM,MAAM,kBAAkB,GAAG;IAC/B,aAAa,EAAE,OAAO,uBAAuB,CAAA;IAC7C,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;CAC7B,CAAA;AAED,wBAAgB,oBAAoB,CAAC,KAAK,EAAE,OAAO,GAAG,KAAK,IAAI,kBAAkB,CAIhF"}

package/dist/richtext.js

@@ -0,0 +1,13 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * Convenzione storage richtext TipTap nel Content Engine.
+ * @see docs/Sprints/tiptap-elevation.md
+ */
+export const RICHTEXT_SCHEMA_VERSION = 1;
+export function isRichtextEnvelopeV1(value) {
+    if (typeof value !== 'object' || value === null || Array.isArray(value))
+        return false;
+    const o = value;
+    return o.schemaVersion === RICHTEXT_SCHEMA_VERSION && typeof o.doc === 'object' && o.doc !== null;
+}

package/dist/scheduler.interface.d.ts

@@ -0,0 +1,4 @@
+export interface IScheduler {
+    waitUntil(promise: Promise<unknown>): void;
+}
+//# sourceMappingURL=scheduler.interface.d.ts.map

package/dist/scheduler.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.interface.d.ts","sourceRoot":"","sources":["../src/scheduler.interface.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,UAAU;IACzB,SAAS,CAAC,OAAO,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI,CAAA;CAC3C"}

package/dist/scheduler.interface.js

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

package/dist/scheduler.stub.d.ts

@@ -0,0 +1,5 @@
+import type { IScheduler } from './scheduler.interface.js';
+export declare class NoOpScheduler implements IScheduler {
+    waitUntil(_promise: Promise<unknown>): void;
+}
+//# sourceMappingURL=scheduler.stub.d.ts.map

package/dist/scheduler.stub.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"scheduler.stub.d.ts","sourceRoot":"","sources":["../src/scheduler.stub.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,0BAA0B,CAAA;AAE1D,qBAAa,aAAc,YAAW,UAAU;IAC9C,SAAS,CAAC,QAAQ,EAAE,OAAO,CAAC,OAAO,CAAC,GAAG,IAAI;CAG5C"}

package/dist/scheduler.stub.js

@@ -0,0 +1,7 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+export class NoOpScheduler {
+    waitUntil(_promise) {
+        // intentionally empty
+    }
+}

package/dist/schema/canonical.d.ts

@@ -0,0 +1,15 @@
+import type { BeechSchemaManifest } from './manifest.types.js';
+/**
+ * Thrown when a manifest carries a value that cannot survive a JSON round-trip.
+ * Re-exported under its historical name: it is the SAME class object as
+ * `CanonicalSerializationError`, so existing `instanceof` checks keep working.
+ */
+export { CanonicalSerializationError as ManifestSerializationError } from '../common/canonical-json.js';
+/**
+ * Serializes a manifest to its canonical form: seeds sorted by slug, keys sorted, two-space
+ * indentation, trailing newline. Stable across authoring order and across key insertion order.
+ */
+export declare function toCanonicalJson(manifest: BeechSchemaManifest): string;
+/** Parses canonical JSON back into a manifest, refusing an unknown format version. */
+export declare function fromCanonicalJson(json: string): BeechSchemaManifest;
+//# sourceMappingURL=canonical.d.ts.map

package/dist/schema/canonical.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical.d.ts","sourceRoot":"","sources":["../../src/schema/canonical.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,mBAAmB,EAAE,MAAM,qBAAqB,CAAA;AAE9D;;;;GAIG;AACH,OAAO,EAAE,2BAA2B,IAAI,0BAA0B,EAAE,MAAM,6BAA6B,CAAA;AAEvG;;;GAGG;AACH,wBAAgB,eAAe,CAAC,QAAQ,EAAE,mBAAmB,GAAG,MAAM,CAGrE;AAED,sFAAsF;AACtF,wBAAgB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,mBAAmB,CASnE"}

package/dist/schema/canonical.js

@@ -0,0 +1,37 @@
+// SPDX-License-Identifier: MIT
+// Copyright (c) 2024–2026 Flavio De Musso
+/**
+ * @module schema/canonical
+ * Deterministic serialization of a manifest. The bytes produced here are the input the schema
+ * fingerprint hashes, so this format is a compatibility surface: changing it invalidates every
+ * already-published client. Treat it as frozen.
+ *
+ * The serializer itself moved to `common/canonical-json.ts` in sprint 2 so the Worker-side
+ * fingerprint can share it without importing this authoring-only module.
+ */
+import { canonicalStringify } from '../common/canonical-json.js';
+import { MANIFEST_VERSION } from './manifest.types.js';
+/**
+ * Thrown when a manifest carries a value that cannot survive a JSON round-trip.
+ * Re-exported under its historical name: it is the SAME class object as
+ * `CanonicalSerializationError`, so existing `instanceof` checks keep working.
+ */
+export { CanonicalSerializationError as ManifestSerializationError } from '../common/canonical-json.js';
+/**
+ * Serializes a manifest to its canonical form: seeds sorted by slug, keys sorted, two-space
+ * indentation, trailing newline. Stable across authoring order and across key insertion order.
+ */
+export function toCanonicalJson(manifest) {
+    const seeds = [...manifest.seeds].sort((a, b) => a.slug.localeCompare(b.slug));
+    return canonicalStringify({ version: manifest.version, seeds });
+}
+/** Parses canonical JSON back into a manifest, refusing an unknown format version. */
+export function fromCanonicalJson(json) {
+    const parsed = JSON.parse(json);
+    if (parsed.version !== MANIFEST_VERSION) {
+        throw new Error(`Unsupported manifest version ${String(parsed.version)}; this build understands ${MANIFEST_VERSION}.`);
+    }
+    if (!Array.isArray(parsed.seeds))
+        throw new Error('Manifest is missing a `seeds` array.');
+    return { version: MANIFEST_VERSION, seeds: parsed.seeds };
+}

package/dist/schema/define.d.ts

@@ -0,0 +1,42 @@
+import type { BeechSchemaManifest, FieldGroup, ManifestBranch, ManifestSeed } from './manifest.types.js';
+/** A field bundle, or the fields themselves, as accepted by `defineSeed`. */
+type BranchInput = ManifestBranch | FieldGroup;
+/**
+ * Declares the root manifest. Seeds are stored in authoring order here; canonical ordering is
+ * applied by `toCanonicalJson`, so a reordered manifest file produces byte-identical canonical JSON.
+ */
+export declare function defineSchema(input: {
+    seeds: ManifestSeed[];
+}): BeechSchemaManifest;
+/**
+ * Declares one content type, flattening any `defineGroup()` bundles into the branch list.
+ * Branch ORDER is preserved: it is the physical column order `planCreateSeed` will emit.
+ */
+export declare function defineSeed(input: Omit<ManifestSeed, 'branches'> & {
+    branches: BranchInput[];
+}): ManifestSeed;
+/** Declares a reusable field bundle. Expanded at author time by `defineSeed`; never persisted. */
+export declare function defineGroup(name: string, branches: ManifestBranch[]): FieldGroup;
+/**
+ * Typed field constructors. `relation` and `repeater` narrow their input because the engine treats
+ * `targetSeed` / `fields` as required for those types — making the compiler enforce what
+ * `validateSeedDefinitions` would otherwise only catch at apply time.
+ */
+export declare const defineField: {
+    readonly text: (input: Omit<ManifestBranch, "type">) => ManifestBranch;
+    readonly number: (input: Omit<ManifestBranch, "type">) => ManifestBranch;
+    readonly boolean: (input: Omit<ManifestBranch, "type">) => ManifestBranch;
+    readonly json: (input: Omit<ManifestBranch, "type">) => ManifestBranch;
+    readonly date: (input: Omit<ManifestBranch, "type">) => ManifestBranch;
+    readonly richtext: (input: Omit<ManifestBranch, "type">) => ManifestBranch;
+    readonly file: (input: Omit<ManifestBranch, "type">) => ManifestBranch;
+    readonly tags: (input: Omit<ManifestBranch, "type">) => ManifestBranch;
+    readonly relation: (input: Omit<ManifestBranch, "type" | "targetSeed"> & {
+        targetSeed: string;
+    }) => ManifestBranch;
+    readonly repeater: (input: Omit<ManifestBranch, "type" | "fields"> & {
+        fields: ManifestBranch[];
+    }) => ManifestBranch;
+};
+export {};
+//# sourceMappingURL=define.d.ts.map

package/dist/schema/define.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/schema/define.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EACV,mBAAmB,EACnB,UAAU,EACV,cAAc,EACd,YAAY,EACb,MAAM,qBAAqB,CAAA;AAE5B,6EAA6E;AAC7E,KAAK,WAAW,GAAG,cAAc,GAAG,UAAU,CAAA;AAM9C;;;GAGG;AACH,wBAAgB,YAAY,CAAC,KAAK,EAAE;IAAE,KAAK,EAAE,YAAY,EAAE,CAAA;CAAE,GAAG,mBAAmB,CAElF;AAED;;;GAGG;AACH,wBAAgB,UAAU,CACxB,KAAK,EAAE,IAAI,CAAC,YAAY,EAAE,UAAU,CAAC,GAAG;IAAE,QAAQ,EAAE,WAAW,EAAE,CAAA;CAAE,GAClE,YAAY,CAOd;AAED,kGAAkG;AAClG,wBAAgB,WAAW,CAAC,IAAI,EAAE,MAAM,EAAE,QAAQ,EAAE,cAAc,EAAE,GAAG,UAAU,CAEhF;AAMD;;;;GAIG;AACH,eAAO,MAAM,WAAW;2BARP,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,KAAG,cAAc;6BAA7C,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,KAAG,cAAc;8BAA7C,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,KAAG,cAAc;2BAA7C,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,KAAG,cAAc;2BAA7C,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,KAAG,cAAc;+BAA7C,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,KAAG,cAAc;2BAA7C,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,KAAG,cAAc;2BAA7C,IAAI,CAAC,cAAc,EAAE,MAAM,CAAC,KAAG,cAAc;+BAkBnD,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,YAAY,CAAC,GAAG;QAAE,UAAU,EAAE,MAAM,CAAA;KAAE,KAC1E,cAAc;+BAER,IAAI,CAAC,cAAc,EAAE,MAAM,GAAG,QAAQ,CAAC,GAAG;QAAE,MAAM,EAAE,cAAc,EAAE,CAAA;KAAE,KAC5E,cAAc;CACT,CAAA"}