@prenta/core 0.118.0

package/dist/search/index.js

@@ -0,0 +1,189 @@
+import { getDB } from '../db.js';
+/** Hard cap on search page size so a client can't request an unbounded scan. */
+const MAX_SEARCH_PAGE_SIZE = 100;
+/**
+ * Convert a user query into a Postgres tsquery-compatible string.
+ * Splits on whitespace, strips non-word chars, joins with & for AND matching.
+ */
+function toTsQuery(query) {
+    const terms = query
+        .replace(/[^\w\s]/g, ' ')
+        .trim()
+        .split(/\s+/)
+        .filter(Boolean)
+        .map((t) => `${t}:*`);
+    return terms.join(' & ');
+}
+/** Search documents using Postgres full-text search with relevance ranking. */
+export async function searchDocuments(query, options = {}) {
+    const db = getDB();
+    const { collection, locale, status, page = 1, pageSize = 20 } = options;
+    const offset = (page - 1) * pageSize;
+    const sanitized = query.replace(/[^\w\s]/g, ' ').trim();
+    if (!sanitized) {
+        return { results: [], total: 0, page, pageSize };
+    }
+    const tsQueryStr = toTsQuery(sanitized);
+    if (!tsQueryStr) {
+        return { results: [], total: 0, page, pageSize };
+    }
+    // Filters shared by both the FTS and the ILIKE fallback pass.
+    const baseConditions = [`d."deletedAt" IS NULL`];
+    const baseParams = [];
+    let paramIdx = 1;
+    // tsquery as a parameter instead of inline interpolation
+    baseParams.push(tsQueryStr);
+    const tsQueryParam = `$${paramIdx++}`;
+    if (collection) {
+        baseConditions.push(`d."collection" = $${paramIdx++}`);
+        baseParams.push(collection);
+    }
+    if (locale) {
+        baseConditions.push(`d."locale" = $${paramIdx++}`);
+        baseParams.push(locale);
+    }
+    if (status) {
+        baseConditions.push(`d."status"::text = $${paramIdx++}`);
+        baseParams.push(status);
+    }
+    const baseWhere = baseConditions.join(' AND ');
+    const ftsVector = `to_tsvector('english', COALESCE(d."title", '') || ' ' || COALESCE(d."plainText", ''))`;
+    const ftsCondition = `(${ftsVector} @@ to_tsquery('english', ${tsQueryParam}))`;
+    const rankExpr = `ts_rank_cd(${ftsVector}, to_tsquery('english', ${tsQueryParam}))`;
+    const headline = `ts_headline('english', COALESCE(d."plainText", ''), to_tsquery('english', ${tsQueryParam}), 'StartSel=<mark>, StopSel=</mark>, MaxWords=35, MinWords=15, MaxFragments=2')`;
+    // Clamp pagination so a client can't request an unbounded page (LIMIT/OFFSET
+    // were previously taken from the request verbatim).
+    const safePageSize = Math.min(Math.max(1, Math.floor(pageSize)), MAX_SEARCH_PAGE_SIZE);
+    const safeOffset = Math.max(0, (page - 1) * safePageSize);
+    const selectList = `
+      d."id",
+      d."title",
+      d."slug",
+      d."collection",
+      d."status",
+      d."updatedAt",
+      ${rankExpr} AS score,
+      ${headline} AS headline,
+      LEFT(COALESCE(d."plainText", ''), 200) AS excerpt`;
+    // First free placeholder after the base params.
+    const nextIdx = paramIdx;
+    // Primary query: FTS only. Critically, the WHERE does NOT OR-in an
+    // un-indexable ILIKE, so Postgres can use the `idx_prenta_documents_fts`
+    // GIN index instead of sequentially scanning every row on each search.
+    const ftsRowsSql = `
+    SELECT ${selectList}
+    FROM "prenta_documents" d
+    WHERE ${baseWhere} AND ${ftsCondition}
+    ORDER BY score DESC, d."updatedAt" DESC
+    LIMIT $${nextIdx} OFFSET $${nextIdx + 1}
+  `;
+    const ftsCountSql = `SELECT COUNT(*)::int AS total FROM "prenta_documents" d WHERE ${baseWhere} AND ${ftsCondition}`;
+    // Substring fallback (ILIKE) — only run when FTS matches nothing, so the
+    // common path never pays for the sequential scan.
+    const ilikeParam = `$${nextIdx}`;
+    const ilikeCondition = `(d."title" ILIKE ${ilikeParam} OR d."plainText" ILIKE ${ilikeParam})`;
+    const ilikeRowsSql = `
+    SELECT ${selectList}
+    FROM "prenta_documents" d
+    WHERE ${baseWhere} AND ${ilikeCondition}
+    ORDER BY score DESC, d."updatedAt" DESC
+    LIMIT $${nextIdx + 1} OFFSET $${nextIdx + 2}
+  `;
+    const ilikeCountSql = `SELECT COUNT(*)::int AS total FROM "prenta_documents" d WHERE ${baseWhere} AND ${ilikeCondition}`;
+    const ilikeValue = `%${sanitized}%`;
+    try {
+        let rows;
+        let total;
+        const [ftsRows, ftsCountRows] = await Promise.all([
+            db.$queryRawUnsafe(ftsRowsSql, ...baseParams, safePageSize, safeOffset),
+            db.$queryRawUnsafe(ftsCountSql, ...baseParams),
+        ]);
+        total = ftsCountRows[0]?.total ?? 0;
+        if (total > 0) {
+            rows = ftsRows;
+        }
+        else {
+            const [ilikeRows, ilikeCountRows] = await Promise.all([
+                db.$queryRawUnsafe(ilikeRowsSql, ...baseParams, ilikeValue, safePageSize, safeOffset),
+                db.$queryRawUnsafe(ilikeCountSql, ...baseParams, ilikeValue),
+            ]);
+            rows = ilikeRows;
+            total = ilikeCountRows[0]?.total ?? 0;
+        }
+        const results = rows.map((row) => {
+            const headlineText = row.headline ?? '';
+            const highlights = headlineText
+                .match(/<mark>(.*?)<\/mark>/g)
+                ?.map((m) => m.replace(/<\/?mark>/g, '')) ?? [];
+            return {
+                id: row.id,
+                title: row.title ?? '',
+                slug: row.slug ?? '',
+                collection: row.collection,
+                excerpt: headlineText || row.excerpt || '',
+                score: parseFloat(row.score) || 0,
+                highlights,
+            };
+        });
+        return { results, total, page, pageSize: safePageSize };
+    }
+    catch {
+        return fallbackSearch(sanitized, options);
+    }
+}
+/** Fallback search using Prisma contains (for non-Postgres or when FTS fails). */
+async function fallbackSearch(query, options) {
+    const db = getDB();
+    const { collection, locale, status, page = 1, pageSize = 20 } = options;
+    const offset = (page - 1) * pageSize;
+    const where = {
+        deletedAt: null,
+        OR: [
+            { plainText: { contains: query, mode: 'insensitive' } },
+            { title: { contains: query, mode: 'insensitive' } },
+        ],
+    };
+    if (collection)
+        where.collection = collection;
+    if (locale)
+        where.locale = locale;
+    if (status)
+        where.status = status;
+    const [results, total] = await Promise.all([
+        db.document.findMany({
+            where,
+            orderBy: { updatedAt: 'desc' },
+            skip: offset,
+            take: pageSize,
+            select: {
+                id: true,
+                title: true,
+                slug: true,
+                collection: true,
+                plainText: true,
+            },
+        }),
+        db.document.count({ where }),
+    ]);
+    return {
+        results: results.map((doc) => {
+            const text = doc.plainText ?? '';
+            const idx = text.toLowerCase().indexOf(query.toLowerCase());
+            const start = Math.max(0, idx - 40);
+            const excerpt = idx >= 0 ? '...' + text.substring(start, start + 200) + '...' : text.substring(0, 200);
+            return {
+                id: doc.id,
+                title: doc.title ?? '',
+                slug: doc.slug ?? '',
+                collection: doc.collection,
+                excerpt,
+                score: doc.title?.toLowerCase().includes(query.toLowerCase()) ? 2 : 1,
+                highlights: [query],
+            };
+        }),
+        total,
+        page,
+        pageSize,
+    };
+}
+//# sourceMappingURL=index.js.map

package/dist/search/index.js.map

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

package/dist/sections/bridge.d.ts

@@ -0,0 +1,8 @@
+import type { PageSection } from './types.js';
+/**
+ * Convert a page-builder `_layout` tree (or any partial/untrusted shape) into a
+ * best-effort canonical `PageSection[]`. Returns `[]` for anything it can't
+ * read. Never throws.
+ */
+export declare function layoutTreeToSections(layout: unknown): PageSection[];
+//# sourceMappingURL=bridge.d.ts.map

package/dist/sections/bridge.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"bridge.d.ts","sourceRoot":"","sources":["../../src/sections/bridge.ts"],"names":[],"mappings":"AAgCA,OAAO,KAAK,EAAE,WAAW,EAAkC,MAAM,YAAY,CAAA;AAwK7E;;;;GAIG;AACH,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,OAAO,GAAG,WAAW,EAAE,CAsBnE"}

package/dist/sections/bridge.js

@@ -0,0 +1,211 @@
+/**
+ * Bridge: page-builder tree (Model B, `data._layout`) → canonical flat
+ * sections (Model A, `data.sections`).
+ *
+ * ADR 0001 makes the flat `PageSection[]` array the single public content
+ * contract and reframes the recursive page-builder `BlockNode` tree as an
+ * optional, admin-only authoring layer. Documents that were authored only in
+ * the tree must still render through the canonical `<Sections>` renderer, so
+ * this module performs a best-effort, **never-throwing** conversion. No
+ * page-builder content is stranded (roadmap WS-A5).
+ *
+ * Fidelity notes:
+ *   - The tree's nesting (page → section → container/row/column → block) is
+ *     flattened to an ordered list of leaf blocks in document order. Each block
+ *     becomes one canonical section.
+ *   - Each block's `settings.blockType` is mapped to the closest canonical
+ *     section type. Unknown/complex block types degrade to a `text` section
+ *     that surfaces whatever string content the block carried, so content is
+ *     shown rather than silently dropped.
+ *   - The enclosing builder section's `htmlId` (anchor) and hidden visibility
+ *     are propagated. Free-form CSS settings (arbitrary background colors,
+ *     pixel paddings) are intentionally NOT mapped — they don't translate to
+ *     the canonical token-based settings and would produce wrong styling.
+ *   - `savedSectionRef` nodes reference a separate saved-section document and
+ *     can't be resolved without a DB lookup; they are skipped here. Callers
+ *     that need them must expand refs before calling this function.
+ *
+ * This is intentionally DB-free and pure so it runs at read time (the resolve
+ * endpoint), in a one-off migration script, or in tests identically.
+ */
+import { generateSectionId } from './helpers.js';
+import { SECTION_TYPES } from './registry.js';
+// ─── Defensive readers (the tree arrives as untrusted JSON) ──────────
+function isObj(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+function str(v) {
+    return typeof v === 'string' ? v : '';
+}
+/** Extract a URL from a media value that may be a string, `{ url }`, or an id. */
+function mediaUrl(v) {
+    if (typeof v === 'string')
+        return v;
+    if (isObj(v) && typeof v.url === 'string')
+        return v.url;
+    return '';
+}
+/** Drop empty-string / null / undefined values so defaults aren't clobbered with blanks. */
+function compact(obj) {
+    const out = {};
+    for (const [k, val] of Object.entries(obj)) {
+        if (val === '' || val === null || val === undefined)
+            continue;
+        out[k] = val;
+    }
+    return out;
+}
+/**
+ * Generic fallback: surface any readable text the block carried as a `text`
+ * section so content is never lost when a block type has no clean canonical
+ * equivalent (cards, faq, video, form, code, custom blocks…).
+ */
+function fallbackTextSection(blockType, data) {
+    const parts = [];
+    const visit = (value) => {
+        if (typeof value === 'string') {
+            const t = value.trim();
+            if (t)
+                parts.push(t);
+        }
+        else if (Array.isArray(value)) {
+            for (const item of value)
+                visit(item);
+        }
+        else if (isObj(value)) {
+            for (const v of Object.values(value))
+                visit(v);
+        }
+    };
+    visit(data);
+    return {
+        type: 'text',
+        name: SECTION_TYPES.text.name,
+        content: compact({ heading: '', body: parts.join('\n\n') }),
+    };
+}
+const BLOCK_MAPPERS = {
+    hero: (d) => ({
+        type: 'hero',
+        content: compact({
+            heading: str(d.title),
+            body: str(d.subtitle),
+            primaryButtonLabel: str(d.ctaText),
+            primaryButtonUrl: str(d.ctaLink),
+        }),
+    }),
+    text: (d) => ({
+        type: 'text',
+        content: compact({ heading: str(d.heading), body: str(d.body) }),
+    }),
+    cta: (d) => ({
+        type: 'cta',
+        content: compact({
+            heading: str(d.heading),
+            body: str(d.body),
+            buttonLabel: str(d.buttonText),
+            buttonUrl: str(d.buttonLink),
+        }),
+    }),
+    image: (d) => ({
+        type: 'feature',
+        name: 'Image',
+        content: compact({
+            imageUrl: mediaUrl(d.src),
+            imageAlt: str(d.alt),
+            body: str(d.caption),
+        }),
+    }),
+    gallery: (d) => ({
+        type: 'gallery',
+        content: compact({
+            images: Array.isArray(d.images)
+                ? d.images
+                    .filter(isObj)
+                    .map((img) => compact({ url: mediaUrl(img.src), alt: str(img.alt), caption: str(img.caption) }))
+                : [],
+        }),
+    }),
+};
+function mapBlock(blockType, data) {
+    const mapper = BLOCK_MAPPERS[blockType];
+    return mapper ? mapper(data) : fallbackTextSection(blockType, data);
+}
+/** Read the anchor + visibility a builder `section` node imposes on its blocks. */
+function sectionContext(node) {
+    const settings = isObj(node.settings) ? node.settings : {};
+    const anchorId = str(settings.htmlId) || undefined;
+    const visible = settings.visibility !== 'hidden';
+    return { anchorId, visible };
+}
+function childrenOf(node) {
+    if (isObj(node) && Array.isArray(node.children))
+        return node.children;
+    return [];
+}
+function makeSection(mapped, ctx) {
+    const def = SECTION_TYPES[mapped.type];
+    return {
+        id: generateSectionId(),
+        sectionType: mapped.type,
+        name: mapped.name && mapped.name.trim() ? mapped.name : def.name,
+        visible: ctx.visible,
+        content: mapped.content,
+        settings: {
+            ...structuredClone(def.defaultSettings),
+            ...(ctx.anchorId ? { anchorId: ctx.anchorId } : {}),
+        },
+    };
+}
+/** Depth-first collect every leaf `block` node under `node`, in document order. */
+function collectBlocks(node, out, ctx) {
+    for (const child of childrenOf(node)) {
+        if (!isObj(child))
+            continue;
+        if (child.type === 'block') {
+            const settings = isObj(child.settings) ? child.settings : {};
+            const blockType = str(settings.blockType);
+            const data = isObj(child.data) ? child.data : {};
+            out.push(makeSection(mapBlock(blockType, data), ctx));
+        }
+        else if (child.type === 'savedSectionRef') {
+            // Can't resolve a saved-section reference without a DB lookup — skip.
+            continue;
+        }
+        else {
+            collectBlocks(child, out, ctx);
+        }
+    }
+}
+/**
+ * Convert a page-builder `_layout` tree (or any partial/untrusted shape) into a
+ * best-effort canonical `PageSection[]`. Returns `[]` for anything it can't
+ * read. Never throws.
+ */
+export function layoutTreeToSections(layout) {
+    if (!isObj(layout))
+        return [];
+    const sections = [];
+    for (const node of childrenOf(layout)) {
+        if (!isObj(node))
+            continue;
+        if (node.type === 'section') {
+            collectBlocks(node, sections, sectionContext(node));
+        }
+        else if (node.type === 'block') {
+            // Tolerate trees where a block sits directly under the page.
+            const settings = isObj(node.settings) ? node.settings : {};
+            sections.push(makeSection(mapBlock(str(settings.blockType), isObj(node.data) ? node.data : {}), {
+                visible: true,
+            }));
+        }
+        else if (node.type === 'savedSectionRef') {
+            continue;
+        }
+        else {
+            collectBlocks(node, sections, { visible: true });
+        }
+    }
+    return sections;
+}
+//# sourceMappingURL=bridge.js.map

package/dist/sections/bridge.js.map

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

package/dist/sections/define.d.ts

@@ -0,0 +1,21 @@
+import type { CustomSectionTypeInput, SectionFieldType } from './types.js';
+/** Runtime mirror of the {@link SectionFieldType} union, for validation. */
+export declare const SECTION_FIELD_TYPES: readonly SectionFieldType[];
+/**
+ * Validate an array of custom section type definitions, returning every
+ * problem found (empty array = valid). Exposed for tooling that wants the
+ * issue list without throwing; most consumers should use
+ * {@link defineSectionTypes} instead.
+ */
+export declare function validateSectionTypeInputs(types: readonly CustomSectionTypeInput[]): string[];
+/**
+ * Define custom section types with eager validation. Returns the input
+ * unchanged (identity function) so the result can be passed straight to
+ * `sections.types` in `prenta.config.ts` — and to
+ * `registerSectionRenderer` lookups on the public site.
+ *
+ * @throws Error listing every validation problem when any definition is
+ *   malformed, duplicates an id, or shadows a built-in section type.
+ */
+export declare function defineSectionTypes<const T extends readonly CustomSectionTypeInput[]>(types: T): T;
+//# sourceMappingURL=define.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"define.d.ts","sourceRoot":"","sources":["../../src/sections/define.ts"],"names":[],"mappings":"AAiCA,OAAO,KAAK,EAAE,sBAAsB,EAAmB,gBAAgB,EAAE,MAAM,YAAY,CAAA;AAE3F,4EAA4E;AAC5E,eAAO,MAAM,mBAAmB,EAAE,SAAS,gBAAgB,EAa1D,CAAA;AAsDD;;;;;GAKG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,SAAS,sBAAsB,EAAE,GAAG,MAAM,EAAE,CAyC5F;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAAC,KAAK,CAAC,CAAC,SAAS,SAAS,sBAAsB,EAAE,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CASjG"}

package/dist/sections/define.js

@@ -0,0 +1,160 @@
+/**
+ * Typed authoring helper for custom section types.
+ *
+ * `defineSectionTypes` is to `sections.types` what `defineConfig` is to the
+ * config file: an identity function that gives consumers full type inference
+ * and eager, fail-fast validation at module-evaluation time.
+ *
+ * The runtime registry (`registerSectionTypes`) deliberately SKIPS invalid
+ * entries so a malformed config can never crash a running site — but that
+ * silence makes authoring mistakes (a typo'd field type, an id that collides
+ * with a built-in) surface only as a mysteriously missing section type in the
+ * Add Section gallery. This helper is the loud counterpart: it throws a
+ * single aggregated error naming every problem with its exact path, so
+ * mistakes are caught where the types are written.
+ *
+ * Usage in a consumer app:
+ *
+ * ```ts
+ * import { defineConfig, defineSectionTypes } from '@prenta/core'
+ *
+ * const customSections = defineSectionTypes([
+ *   {
+ *     id: 'pricing',
+ *     name: 'Pricing Table',
+ *     scope: ['page'],
+ *     fields: [{ key: 'heading', label: 'Heading', type: 'text', required: true }],
+ *   },
+ * ])
+ *
+ * export default defineConfig({ sections: { types: customSections }, ... })
+ * ```
+ */
+import { SECTION_TYPES } from './registry.js';
+/** Runtime mirror of the {@link SectionFieldType} union, for validation. */
+export const SECTION_FIELD_TYPES = [
+    'text',
+    'textarea',
+    'richText',
+    'url',
+    'media',
+    'select',
+    'boolean',
+    'color',
+    'relationship',
+    'repeater',
+    'stats',
+    'gallery',
+];
+const FIELD_TYPE_SET = new Set(SECTION_FIELD_TYPES);
+const SCOPES = new Set(['page', 'post']);
+function isNonBlankString(v) {
+    return typeof v === 'string' && v.trim().length > 0;
+}
+function validateFields(fields, path, errors) {
+    if (!Array.isArray(fields)) {
+        errors.push(`${path}.fields must be an array (use [] for a type with no editable fields)`);
+        return;
+    }
+    const seenKeys = new Set();
+    fields.forEach((field, i) => {
+        const fpath = `${path}.fields[${i}]`;
+        if (!field || typeof field !== 'object') {
+            errors.push(`${fpath} must be an object`);
+            return;
+        }
+        if (!isNonBlankString(field.key)) {
+            errors.push(`${fpath}.key must be a non-empty string`);
+        }
+        else if (seenKeys.has(field.key)) {
+            errors.push(`${fpath}.key "${field.key}" is duplicated within ${path}`);
+        }
+        else {
+            seenKeys.add(field.key);
+        }
+        if (!isNonBlankString(field.label)) {
+            errors.push(`${fpath}.label must be a non-empty string`);
+        }
+        if (!FIELD_TYPE_SET.has(field.type)) {
+            errors.push(`${fpath}.type "${String(field.type)}" is not a known field type. ` +
+                `Valid types: ${SECTION_FIELD_TYPES.join(', ')}`);
+        }
+        if (field.type === 'select' && (!Array.isArray(field.options) || field.options.length === 0)) {
+            errors.push(`${fpath} is a select field and must declare a non-empty \`options\` array`);
+        }
+        if (field.type === 'repeater') {
+            if (!Array.isArray(field.fields) || field.fields.length === 0) {
+                errors.push(`${fpath} is a repeater and must declare a non-empty \`fields\` sub-schema`);
+            }
+            else {
+                validateFields(field.fields, fpath, errors);
+            }
+        }
+    });
+}
+/**
+ * Validate an array of custom section type definitions, returning every
+ * problem found (empty array = valid). Exposed for tooling that wants the
+ * issue list without throwing; most consumers should use
+ * {@link defineSectionTypes} instead.
+ */
+export function validateSectionTypeInputs(types) {
+    const errors = [];
+    if (!Array.isArray(types)) {
+        return ['defineSectionTypes expects an array of section type definitions'];
+    }
+    const seenIds = new Set();
+    types.forEach((type, i) => {
+        const path = `types[${i}]`;
+        if (!type || typeof type !== 'object') {
+            errors.push(`${path} must be an object`);
+            return;
+        }
+        if (!isNonBlankString(type.id)) {
+            errors.push(`${path}.id must be a non-empty string`);
+        }
+        else {
+            if (type.id in SECTION_TYPES) {
+                errors.push(`${path}.id "${type.id}" collides with a built-in section type. ` +
+                    'Built-ins always win on an id collision, so this type would be silently ignored — pick a different id.');
+            }
+            if (seenIds.has(type.id)) {
+                errors.push(`${path}.id "${type.id}" is duplicated — section type ids must be unique`);
+            }
+            seenIds.add(type.id);
+        }
+        if (!isNonBlankString(type.name)) {
+            errors.push(`${path}.name must be a non-empty string`);
+        }
+        if (!Array.isArray(type.scope) || type.scope.length === 0) {
+            errors.push(`${path}.scope must be a non-empty array of 'page' | 'post'`);
+        }
+        else {
+            for (const s of type.scope) {
+                if (!SCOPES.has(s)) {
+                    errors.push(`${path}.scope contains "${String(s)}" — valid scopes are 'page' and 'post'`);
+                }
+            }
+        }
+        validateFields(type.fields, path, errors);
+    });
+    return errors;
+}
+/**
+ * Define custom section types with eager validation. Returns the input
+ * unchanged (identity function) so the result can be passed straight to
+ * `sections.types` in `prenta.config.ts` — and to
+ * `registerSectionRenderer` lookups on the public site.
+ *
+ * @throws Error listing every validation problem when any definition is
+ *   malformed, duplicates an id, or shadows a built-in section type.
+ */
+export function defineSectionTypes(types) {
+    const errors = validateSectionTypeInputs(types);
+    if (errors.length > 0) {
+        throw new Error(`Invalid custom section type definition${errors.length > 1 ? 's' : ''}:\n` +
+            errors.map((e) => `  - ${e}`).join('\n'));
+    }
+    return types;
+}
+//# sourceMappingURL=define.js.map

package/dist/sections/define.js.map

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

package/dist/sections/embed.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Embed/video provider allowlist + URL parsing for the `embed` section.
+ *
+ * Only YouTube, Vimeo, and Loom are allowed; each source URL is mapped to its
+ * privacy-friendly iframe `src`. Parsing is deterministic and pure (no network)
+ * so the section validator (cms-core) and the public renderer (sections-react)
+ * agree on exactly what is embeddable — an arbitrary URL can never reach an
+ * `<iframe>`.
+ */
+export type EmbedProvider = 'youtube' | 'vimeo' | 'loom';
+export interface ParsedEmbed {
+    provider: EmbedProvider;
+    /** Provider-specific id extracted from the source URL. */
+    id: string;
+    /** The iframe `src` to render. */
+    embedUrl: string;
+}
+export declare const EMBED_PROVIDER_LABEL: Record<EmbedProvider, string>;
+/**
+ * Resolve a pasted video URL to a provider + iframe `src`, or `null` when the
+ * URL is not an allowed provider (or is malformed).
+ */
+export declare function parseEmbed(raw: unknown): ParsedEmbed | null;
+//# sourceMappingURL=embed.d.ts.map

package/dist/sections/embed.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.d.ts","sourceRoot":"","sources":["../../src/sections/embed.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAEH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,OAAO,GAAG,MAAM,CAAA;AAExD,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,aAAa,CAAA;IACvB,0DAA0D;IAC1D,EAAE,EAAE,MAAM,CAAA;IACV,kCAAkC;IAClC,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,eAAO,MAAM,oBAAoB,EAAE,MAAM,CAAC,aAAa,EAAE,MAAM,CAI9D,CAAA;AAmCD;;;GAGG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,OAAO,GAAG,WAAW,GAAG,IAAI,CAuB3D"}