@contentbit/core 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 contentbit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,15 @@
+# @contentbit/core
+
+Parser, validator, and registry for [Content Blocks](https://contentbit.dev): structured Markdown components without framework lock-in.
+
+```ts
+import { createBlockRegistry, parseDocument, validateDocument } from '@contentbit/core'
+import { genericBlocks } from '@contentbit/blocks'
+
+const registry = createBlockRegistry().use(genericBlocks())
+const result = validateDocument(parseDocument(markdown), registry)
+```
+
+Documents are plain Markdown with directive blocks. Validation runs before rendering and produces `file:line:col` diagnostics a human or an LLM can act on. The same registry generates LLM authoring instructions via `toAuthoringGuide()`.
+
+Docs: [contentbit.dev/docs](https://contentbit.dev/docs)

package/dist/ast.d.ts

@@ -0,0 +1,29 @@
+import type { SourceRange } from './diagnostics.js';
+export interface DocumentNode {
+    type: 'document';
+    children: ContentNode[];
+    position: SourceRange;
+}
+export type ContentNode = MarkdownNode | BlockNode;
+/** A verbatim run of plain Markdown between blocks. Core never parses inside it. */
+export interface MarkdownNode {
+    type: 'markdown';
+    value: string;
+    position: SourceRange;
+}
+export interface BlockNode {
+    type: 'block';
+    name: string;
+    /** Number of colons in the opening fence: >=3 container, 2 child. */
+    fence: number;
+    props: Record<string, unknown>;
+    rawProps: string | null;
+    children: ContentNode[];
+    /** Raw inner source between open and close lines (includes nested block text). */
+    body: string;
+    position: SourceRange;
+    openPosition: SourceRange;
+    /** null for implicitly closed child blocks and unclosed blocks. */
+    closePosition: SourceRange | null;
+}
+//# sourceMappingURL=ast.d.ts.map

package/dist/ast.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ast.d.ts","sourceRoot":"","sources":["../src/ast.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAA;IAChB,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB,QAAQ,EAAE,WAAW,CAAA;CACtB;AAED,MAAM,MAAM,WAAW,GAAG,YAAY,GAAG,SAAS,CAAA;AAElD,oFAAoF;AACpF,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,UAAU,CAAA;IAChB,KAAK,EAAE,MAAM,CAAA;IACb,QAAQ,EAAE,WAAW,CAAA;CACtB;AAED,MAAM,WAAW,SAAS;IACxB,IAAI,EAAE,OAAO,CAAA;IACb,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,KAAK,EAAE,MAAM,CAAA;IACb,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,QAAQ,EAAE,MAAM,GAAG,IAAI,CAAA;IACvB,QAAQ,EAAE,WAAW,EAAE,CAAA;IACvB,kFAAkF;IAClF,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,WAAW,CAAA;IACrB,YAAY,EAAE,WAAW,CAAA;IACzB,mEAAmE;IACnE,aAAa,EAAE,WAAW,GAAG,IAAI,CAAA;CAClC"}

package/dist/ast.js

@@ -0,0 +1 @@
+export {};

package/dist/authoring.d.ts

@@ -0,0 +1,8 @@
+import type { BlockDefinition } from './registry.js';
+export interface AuthoringGuideOptions {
+    audience?: 'llm' | 'human';
+    includeExamples?: boolean;
+    includeAvoidRules?: boolean;
+}
+export declare function generateAuthoringGuide(defs: BlockDefinition<unknown>[], opts?: AuthoringGuideOptions): string;
+//# sourceMappingURL=authoring.d.ts.map

package/dist/authoring.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"authoring.d.ts","sourceRoot":"","sources":["../src/authoring.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,EAAE,KAAK,GAAG,OAAO,CAAA;IAC1B,eAAe,CAAC,EAAE,OAAO,CAAA;IACzB,iBAAiB,CAAC,EAAE,OAAO,CAAA;CAC5B;AAWD,wBAAgB,sBAAsB,CACpC,IAAI,EAAE,eAAe,CAAC,OAAO,CAAC,EAAE,EAChC,IAAI,GAAE,qBAA0B,GAC/B,MAAM,CA0BR"}

package/dist/authoring.js

@@ -0,0 +1,33 @@
+const LLM_PREAMBLE = `# Content block authoring rules
+
+- write regular Markdown by default; use blocks only when they improve scanning or structure
+- never invent block names — only the blocks documented below exist
+- follow each block's syntax exactly; props use {key="value"} on the open line
+- close every :::block with a line containing only :::
+- validate generated content and fix diagnostics rather than bypassing them
+`;
+export function generateAuthoringGuide(defs, opts = {}) {
+    const includeExamples = opts.includeExamples ?? true;
+    const includeAvoid = opts.includeAvoidRules ?? true;
+    const sections = [];
+    if ((opts.audience ?? 'llm') === 'llm')
+        sections.push(LLM_PREAMBLE);
+    for (const def of defs) {
+        const lines = [`## ${def.name}`, ''];
+        lines.push(def.childOnly
+            ? `${def.description} (child block — only inside a parent that allows it)`
+            : def.description);
+        lines.push('', `Content: ${def.content.describe()}`);
+        if (def.authoring.useWhen.length > 0) {
+            lines.push('', 'Use when:', ...def.authoring.useWhen.map((u) => `- ${u}`));
+        }
+        if (includeAvoid && def.authoring.avoidWhen.length > 0) {
+            lines.push('', 'Avoid when:', ...def.authoring.avoidWhen.map((a) => `- ${a}`));
+        }
+        if (includeExamples && def.authoring.example.trim() !== '') {
+            lines.push('', 'Example:', '', '```md', def.authoring.example, '```');
+        }
+        sections.push(lines.join('\n'));
+    }
+    return sections.join('\n\n') + '\n';
+}

package/dist/content-models.d.ts

@@ -0,0 +1,48 @@
+import type { BlockNode } from './ast.js';
+import type { ContentModel } from './registry.js';
+export interface MarkdownBodyOptions {
+    required?: boolean;
+    minLength?: number;
+    maxLength?: number;
+}
+export interface MarkdownBodyData {
+    markdown: string;
+}
+export declare function markdownBody(opts?: MarkdownBodyOptions): ContentModel<MarkdownBodyData>;
+export interface PipeRowsOptions {
+    columns: string[];
+    /** Number of trailing columns that may be omitted (filled with ""). */
+    optionalColumns?: number;
+    minRows?: number;
+    maxRows?: number;
+    allowMarkdown?: boolean;
+}
+export interface PipeRowsData {
+    rows: Array<Record<string, string>>;
+}
+export declare function pipeRows(opts: PipeRowsOptions): ContentModel<PipeRowsData>;
+export interface ListItemsOptions {
+    /** signed = lines starting with `+ ` or `- ` (e.g. pros-cons). */
+    marker: 'bullet' | 'ordered' | 'signed';
+    minItems?: number;
+    maxItems?: number;
+}
+export interface ListItem {
+    text: string;
+    sign?: '+' | '-';
+}
+export interface ListItemsData {
+    items: ListItem[];
+}
+export declare function listItems(opts: ListItemsOptions): ContentModel<ListItemsData>;
+export interface ChildBlocksOptions {
+    allowed: string[];
+    required?: string[];
+    minChildren?: number;
+    maxChildren?: number;
+}
+export interface ChildBlocksData {
+    blocks: BlockNode[];
+}
+export declare function childBlocks(opts: ChildBlocksOptions): ContentModel<ChildBlocksData>;
+//# sourceMappingURL=content-models.d.ts.map

package/dist/content-models.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"content-models.d.ts","sourceRoot":"","sources":["../src/content-models.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,YAAY,EAAU,MAAM,eAAe,CAAA;AAgBzD,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,OAAO,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,SAAS,CAAC,EAAE,MAAM,CAAA;CACnB;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,EAAE,MAAM,CAAA;CACjB;AAED,wBAAgB,YAAY,CAAC,IAAI,GAAE,mBAAwB,GAAG,YAAY,CAAC,gBAAgB,CAAC,CAkC3F;AAID,MAAM,WAAW,eAAe;IAC9B,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,uEAAuE;IACvE,eAAe,CAAC,EAAE,MAAM,CAAA;IACxB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,aAAa,CAAC,EAAE,OAAO,CAAA;CACxB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,KAAK,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC,CAAA;CACpC;AASD,wBAAgB,QAAQ,CAAC,IAAI,EAAE,eAAe,GAAG,YAAY,CAAC,YAAY,CAAC,CA8D1E;AAID,MAAM,WAAW,gBAAgB;IAC/B,kEAAkE;IAClE,MAAM,EAAE,QAAQ,GAAG,SAAS,GAAG,QAAQ,CAAA;IACvC,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,CAAA;CAClB;AAED,MAAM,WAAW,QAAQ;IACvB,IAAI,EAAE,MAAM,CAAA;IACZ,IAAI,CAAC,EAAE,GAAG,GAAG,GAAG,CAAA;CACjB;AAED,MAAM,WAAW,aAAa;IAC5B,KAAK,EAAE,QAAQ,EAAE,CAAA;CAClB;AAQD,wBAAgB,SAAS,CAAC,IAAI,EAAE,gBAAgB,GAAG,YAAY,CAAC,aAAa,CAAC,CAkD7E;AAID,MAAM,WAAW,kBAAkB;IACjC,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAA;IACnB,WAAW,CAAC,EAAE,MAAM,CAAA;IACpB,WAAW,CAAC,EAAE,MAAM,CAAA;CACrB;AAED,MAAM,WAAW,eAAe;IAC9B,MAAM,EAAE,SAAS,EAAE,CAAA;CACpB;AAED,wBAAgB,WAAW,CAAC,IAAI,EAAE,kBAAkB,GAAG,YAAY,CAAC,eAAe,CAAC,CA0DnF"}

package/dist/content-models.js

@@ -0,0 +1,174 @@
+import { bodyLineRange } from './position.js';
+function blockDiag(node, code, message, hint, severity = 'error') {
+    return { code, severity, message, hint, blockName: node.name, position: node.openPosition };
+}
+export function markdownBody(opts = {}) {
+    const required = opts.required ?? true;
+    return {
+        kind: 'markdown',
+        describe: () => 'Markdown body',
+        parse(node, report) {
+            const markdown = node.body.trim();
+            if (required && markdown === '') {
+                report(blockDiag(node, 'CB_BODY_EMPTY', `:::${node.name} requires a body.`));
+            }
+            else if (opts.minLength !== undefined && markdown.length < opts.minLength) {
+                report(blockDiag(node, 'CB_BODY_LENGTH', `:::${node.name} body is shorter than ${opts.minLength} characters.`, undefined, 'warning'));
+            }
+            if (opts.maxLength !== undefined && markdown.length > opts.maxLength) {
+                report(blockDiag(node, 'CB_BODY_LENGTH', `:::${node.name} body exceeds ${opts.maxLength} characters.`, undefined, 'warning'));
+            }
+            return { markdown };
+        },
+    };
+}
+const ROW_RE = /^\s*-\s+(.*)$/;
+// Known limitation: a cell value ending in a literal backslash immediately
+// before a separator pipe (e.g. `foo\\|bar`) is treated as an escaped pipe
+// rather than a column separator. Write `\|` only to escape a pipe character;
+// avoid a trailing `\` at the end of a cell value.
+const UNESCAPED_PIPE = /(?<!\\)\|/;
+export function pipeRows(opts) {
+    const required = opts.columns.length - (opts.optionalColumns ?? 0);
+    return {
+        kind: 'rows',
+        describe: () => `List rows: \`- ${opts.columns.join(' | ')}\`${opts.optionalColumns ? ` (last ${opts.optionalColumns} optional)` : ''}`,
+        parse(node, report) {
+            const rows = [];
+            const bodyLines = node.body.split('\n');
+            for (let i = 0; i < bodyLines.length; i++) {
+                const line = bodyLines[i];
+                if (line.trim() === '')
+                    continue;
+                const m = line.match(ROW_RE);
+                if (!m) {
+                    report({
+                        code: 'CB_ROW_SYNTAX',
+                        severity: 'warning',
+                        message: `:::${node.name} rows must start with "- ". Ignored: "${line.trim()}".`,
+                        blockName: node.name,
+                        position: bodyLineRange(node, i),
+                    });
+                    continue;
+                }
+                const cells = m[1].split(UNESCAPED_PIPE).map((c) => c.replace(/\\\|/g, '|').trim());
+                if (cells.length < required || cells.length > opts.columns.length) {
+                    report({
+                        code: 'CB_ROW_COLUMNS',
+                        severity: 'error',
+                        message: `:::${node.name} rows require ${opts.columns.length} columns (${opts.columns.join(' | ')}). Found ${cells.length}.`,
+                        hint: `Format: - ${opts.columns.join(' | ')}`,
+                        blockName: node.name,
+                        position: bodyLineRange(node, i),
+                    });
+                    continue;
+                }
+                const row = {};
+                opts.columns.forEach((col, idx) => {
+                    row[col] = cells[idx] ?? '';
+                });
+                rows.push(row);
+            }
+            if (opts.minRows !== undefined && rows.length < opts.minRows) {
+                report(blockDiag(node, 'CB_ROW_COUNT', `:::${node.name} needs at least ${opts.minRows} rows, found ${rows.length}.`));
+            }
+            if (opts.maxRows !== undefined && rows.length > opts.maxRows) {
+                report(blockDiag(node, 'CB_ROW_COUNT', `:::${node.name} allows at most ${opts.maxRows} rows, found ${rows.length}.`));
+            }
+            return { rows };
+        },
+    };
+}
+const MARKERS = {
+    bullet: /^\s*-\s+(.*)$/,
+    ordered: /^\s*\d+[.)]\s+(.*)$/,
+    signed: /^\s*([+-])\s+(.*)$/,
+};
+export function listItems(opts) {
+    return {
+        kind: 'list',
+        describe: () => opts.marker === 'ordered'
+            ? 'Ordered list: `1. item`'
+            : opts.marker === 'signed'
+                ? 'Signed list: `+ positive` / `- negative`'
+                : 'Bullet list: `- item`',
+        parse(node, report) {
+            const items = [];
+            const bodyLines = node.body.split('\n');
+            for (let i = 0; i < bodyLines.length; i++) {
+                const line = bodyLines[i];
+                if (line.trim() === '')
+                    continue;
+                const m = line.match(MARKERS[opts.marker]);
+                if (!m) {
+                    report({
+                        code: 'CB_ITEM_SYNTAX',
+                        severity: 'warning',
+                        message: `:::${node.name} expects ${opts.marker} list items. Ignored: "${line.trim()}".`,
+                        blockName: node.name,
+                        position: bodyLineRange(node, i),
+                    });
+                    continue;
+                }
+                if (opts.marker === 'signed')
+                    items.push({ text: m[2], sign: m[1] });
+                else
+                    items.push({ text: m[1] });
+            }
+            if (opts.minItems !== undefined && items.length < opts.minItems) {
+                report(blockDiag(node, 'CB_ITEM_COUNT', `:::${node.name} needs at least ${opts.minItems} items, found ${items.length}.`));
+            }
+            if (opts.maxItems !== undefined && items.length > opts.maxItems) {
+                report(blockDiag(node, 'CB_ITEM_COUNT', `:::${node.name} allows at most ${opts.maxItems} items, found ${items.length}.`));
+            }
+            return { items };
+        },
+    };
+}
+export function childBlocks(opts) {
+    return {
+        kind: 'children',
+        describe: () => `Child blocks: ${opts.allowed.map((n) => `\`::${n}\``).join(', ')}`,
+        parse(node, report) {
+            const blocks = [];
+            for (const child of node.children) {
+                if (child.type === 'markdown') {
+                    if (child.value.trim() !== '') {
+                        report({
+                            code: 'CB_UNEXPECTED_CONTENT',
+                            severity: 'warning',
+                            message: `:::${node.name} only accepts ${opts.allowed.map((n) => `::${n}`).join(', ')} children; loose text is ignored.`,
+                            blockName: node.name,
+                            position: child.position,
+                        });
+                    }
+                    continue;
+                }
+                if (!opts.allowed.includes(child.name)) {
+                    report({
+                        code: 'CB_CHILD_NOT_ALLOWED',
+                        severity: 'error',
+                        message: `"::${child.name}" is not allowed inside :::${node.name}. Allowed: ${opts.allowed.join(', ')}.`,
+                        blockName: node.name,
+                        position: child.openPosition,
+                    });
+                    continue;
+                }
+                blocks.push(child);
+            }
+            for (const name of opts.required ?? []) {
+                if (!blocks.some((b) => b.name === name)) {
+                    report(blockDiag(node, 'CB_CHILD_MISSING', `:::${node.name} requires a ::${name} child.`));
+                }
+            }
+            const count = blocks.length;
+            if (opts.minChildren !== undefined && count < opts.minChildren) {
+                report(blockDiag(node, 'CB_CHILD_COUNT', `:::${node.name} needs at least ${opts.minChildren} children, found ${count}.`));
+            }
+            if (opts.maxChildren !== undefined && count > opts.maxChildren) {
+                report(blockDiag(node, 'CB_CHILD_COUNT', `:::${node.name} allows at most ${opts.maxChildren} children, found ${count}.`));
+            }
+            return { blocks };
+        },
+    };
+}

package/dist/diagnostics.d.ts

@@ -0,0 +1,23 @@
+export interface SourcePoint {
+    /** 1-based */
+    line: number;
+    /** 1-based */
+    column: number;
+    /** 0-based char offset into the source string */
+    offset: number;
+}
+export interface SourceRange {
+    start: SourcePoint;
+    end: SourcePoint;
+}
+export type Severity = 'error' | 'warning' | 'info';
+export interface Diagnostic {
+    code: string;
+    severity: Severity;
+    message: string;
+    hint?: string;
+    blockName?: string;
+    position: SourceRange;
+}
+export declare function formatDiagnostic(d: Diagnostic, file?: string): string;
+//# sourceMappingURL=diagnostics.d.ts.map

package/dist/diagnostics.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"diagnostics.d.ts","sourceRoot":"","sources":["../src/diagnostics.ts"],"names":[],"mappings":"AAAA,MAAM,WAAW,WAAW;IAC1B,cAAc;IACd,IAAI,EAAE,MAAM,CAAA;IACZ,cAAc;IACd,MAAM,EAAE,MAAM,CAAA;IACd,iDAAiD;IACjD,MAAM,EAAE,MAAM,CAAA;CACf;AAED,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,WAAW,CAAA;IAClB,GAAG,EAAE,WAAW,CAAA;CACjB;AAED,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,SAAS,GAAG,MAAM,CAAA;AAEnD,MAAM,WAAW,UAAU;IACzB,IAAI,EAAE,MAAM,CAAA;IACZ,QAAQ,EAAE,QAAQ,CAAA;IAClB,OAAO,EAAE,MAAM,CAAA;IACf,IAAI,CAAC,EAAE,MAAM,CAAA;IACb,SAAS,CAAC,EAAE,MAAM,CAAA;IAClB,QAAQ,EAAE,WAAW,CAAA;CACtB;AAED,wBAAgB,gBAAgB,CAAC,CAAC,EAAE,UAAU,EAAE,IAAI,SAAe,GAAG,MAAM,CAK3E"}

package/dist/diagnostics.js

@@ -0,0 +1,7 @@
+export function formatDiagnostic(d, file = 'content.md') {
+    const head = `${file}:${d.position.start.line}:${d.position.start.column} ${d.severity} ${d.code}`;
+    const lines = [head, d.message];
+    if (d.hint)
+        lines.push(`hint: ${d.hint}`);
+    return lines.join('\n');
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+export { VERSION } from './version.js';
+export type { SourcePoint, SourceRange, Severity, Diagnostic } from './diagnostics.js';
+export { formatDiagnostic } from './diagnostics.js';
+export type { DocumentNode, ContentNode, MarkdownNode, BlockNode } from './ast.js';
+export { parseDocument, type ParseResult } from './parser.js';
+export { parseProps } from './props.js';
+export { bodyLineRange } from './position.js';
+export { createBlockRegistry, defineBlock, BlockRegistry, type BlockDefinition, type ContentModel, type AuthoringMeta, type Report, } from './registry.js';
+export { markdownBody, pipeRows, listItems, childBlocks, type MarkdownBodyData, type PipeRowsData, type ListItemsData, type ListItem, type ChildBlocksData, } from './content-models.js';
+export { validateDocument, isValidatedBlock, type ValidateOptions, type ValidationResult, type ValidatedBlockNode, } from './validate.js';
+export { generateAuthoringGuide, type AuthoringGuideOptions } from './authoring.js';
+export { renderToMarkdown, type MarkdownBlockRenderer, type MarkdownRenderContext, type RenderToMarkdownOptions, } from './render-markdown.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAA;AACtC,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,QAAQ,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AACtF,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAA;AACnD,YAAY,EAAE,YAAY,EAAE,WAAW,EAAE,YAAY,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AAClF,OAAO,EAAE,aAAa,EAAE,KAAK,WAAW,EAAE,MAAM,aAAa,CAAA;AAC7D,OAAO,EAAE,UAAU,EAAE,MAAM,YAAY,CAAA;AACvC,OAAO,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAC7C,OAAO,EACL,mBAAmB,EACnB,WAAW,EACX,aAAa,EACb,KAAK,eAAe,EACpB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,MAAM,GACZ,MAAM,eAAe,CAAA;AACtB,OAAO,EACL,YAAY,EACZ,QAAQ,EACR,SAAS,EACT,WAAW,EACX,KAAK,gBAAgB,EACrB,KAAK,YAAY,EACjB,KAAK,aAAa,EAClB,KAAK,QAAQ,EACb,KAAK,eAAe,GACrB,MAAM,qBAAqB,CAAA;AAC5B,OAAO,EACL,gBAAgB,EAChB,gBAAgB,EAChB,KAAK,eAAe,EACpB,KAAK,gBAAgB,EACrB,KAAK,kBAAkB,GACxB,MAAM,eAAe,CAAA;AACtB,OAAO,EAAE,sBAAsB,EAAE,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AACnF,OAAO,EACL,gBAAgB,EAChB,KAAK,qBAAqB,EAC1B,KAAK,qBAAqB,EAC1B,KAAK,uBAAuB,GAC7B,MAAM,sBAAsB,CAAA"}

package/dist/index.js

@@ -0,0 +1,10 @@
+export { VERSION } from './version.js';
+export { formatDiagnostic } from './diagnostics.js';
+export { parseDocument } from './parser.js';
+export { parseProps } from './props.js';
+export { bodyLineRange } from './position.js';
+export { createBlockRegistry, defineBlock, BlockRegistry, } from './registry.js';
+export { markdownBody, pipeRows, listItems, childBlocks, } from './content-models.js';
+export { validateDocument, isValidatedBlock, } from './validate.js';
+export { generateAuthoringGuide } from './authoring.js';
+export { renderToMarkdown, } from './render-markdown.js';

package/dist/parser.d.ts

@@ -0,0 +1,8 @@
+import type { DocumentNode } from './ast.js';
+import type { Diagnostic } from './diagnostics.js';
+export interface ParseResult {
+    document: DocumentNode;
+    diagnostics: Diagnostic[];
+}
+export declare function parseDocument(source: string): ParseResult;
+//# sourceMappingURL=parser.d.ts.map

package/dist/parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"parser.d.ts","sourceRoot":"","sources":["../src/parser.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAA0B,YAAY,EAAgB,MAAM,UAAU,CAAA;AAClF,OAAO,KAAK,EAAE,UAAU,EAA4B,MAAM,kBAAkB,CAAA;AAI5E,MAAM,WAAW,WAAW;IAC1B,QAAQ,EAAE,YAAY,CAAA;IACtB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAcD,wBAAgB,aAAa,CAAC,MAAM,EAAE,MAAM,GAAG,WAAW,CAgNzD"}

package/dist/parser.js

@@ -0,0 +1,200 @@
+import { parseProps } from './props.js';
+const NAME = '[a-z][a-z0-9]*(?:-[a-z0-9]+)*';
+const OPEN_RE = new RegExp(`^(:{3,})(${NAME})(\\{.*)?\\s*$`);
+const CHILD_RE = new RegExp(`^::(${NAME})(\\{.*)?\\s*$`);
+const CLOSE_RE = /^(:{3,})\s*$/;
+const CODE_FENCE_RE = /^(`{3,}|~{3,})/;
+export function parseDocument(source) {
+    const diagnostics = [];
+    const lines = source.split('\n');
+    const lineStart = Array.from({ length: lines.length });
+    let off = 0;
+    for (let i = 0; i < lines.length; i++) {
+        lineStart[i] = off;
+        off += lines[i].length + 1;
+    }
+    const sourceEnd = source.length;
+    const point = (line, column, offset) => ({
+        line,
+        column,
+        offset,
+    });
+    const lineRange = (i) => ({
+        start: point(i + 1, 1, lineStart[i]),
+        end: point(i + 1, lines[i].length + 1, lineStart[i] + lines[i].length),
+    });
+    const eofPoint = () => point(lines.length, (lines[lines.length - 1] ?? '').length + 1, sourceEnd);
+    const document = {
+        type: 'document',
+        children: [],
+        position: { start: point(1, 1, 0), end: eofPoint() },
+    };
+    const stack = [];
+    let mdStartLine = null;
+    let codeFence = null;
+    const top = () => stack[stack.length - 1];
+    const sink = () => top()?.node.children ?? document.children;
+    function flushMarkdown(endLineExclusive) {
+        if (mdStartLine === null)
+            return;
+        const startOff = lineStart[mdStartLine];
+        const endOff = endLineExclusive >= lines.length
+            ? sourceEnd
+            : Math.max(startOff, lineStart[endLineExclusive] - 1);
+        const value = source.slice(startOff, endOff);
+        if (value.trim() !== '') {
+            const node = {
+                type: 'markdown',
+                value,
+                position: {
+                    start: point(mdStartLine + 1, 1, startOff),
+                    end: point(endLineExclusive, (lines[endLineExclusive - 1] ?? '').length + 1, endOff),
+                },
+            };
+            sink().push(node);
+        }
+        mdStartLine = null;
+    }
+    function openBlock(i, fence, name, rawProps) {
+        const openPosition = lineRange(i);
+        const parsed = parseProps(rawProps, openPosition);
+        for (const d of parsed.diagnostics)
+            diagnostics.push({ ...d, blockName: name });
+        const node = {
+            type: 'block',
+            name,
+            fence,
+            props: parsed.props,
+            rawProps,
+            children: [],
+            body: '',
+            position: { start: openPosition.start, end: openPosition.end },
+            openPosition,
+            closePosition: null,
+        };
+        sink().push(node);
+        stack.push({ node, bodyStart: i + 1 < lines.length ? lineStart[i + 1] : sourceEnd });
+    }
+    /** bodyEndLine = index of the line that terminates the body (close line, sibling open, or lines.length at EOF). */
+    function finalize(frame, bodyEndLine, closeLine) {
+        const endOff = bodyEndLine >= lines.length
+            ? sourceEnd
+            : Math.max(frame.bodyStart, lineStart[bodyEndLine] - 1);
+        frame.node.body = source.slice(frame.bodyStart, endOff);
+        if (closeLine !== null) {
+            frame.node.closePosition = lineRange(closeLine);
+            frame.node.position = {
+                start: frame.node.openPosition.start,
+                end: frame.node.closePosition.end,
+            };
+        }
+        else {
+            frame.node.position = {
+                start: frame.node.openPosition.start,
+                end: bodyEndLine >= lines.length
+                    ? eofPoint()
+                    : point(bodyEndLine, (lines[bodyEndLine - 1] ?? '').length + 1, endOff),
+            };
+        }
+    }
+    function popChildIfOpen(i) {
+        if (top()?.node.fence === 2) {
+            flushMarkdown(i);
+            finalize(stack.pop(), i, null);
+        }
+    }
+    for (let i = 0; i < lines.length; i++) {
+        const trimmed = lines[i].trim();
+        // Code fences are opaque: nothing inside them opens or closes blocks.
+        const fenceMatch = trimmed.match(CODE_FENCE_RE);
+        if (codeFence !== null) {
+            if (fenceMatch &&
+                fenceMatch[1][0] === codeFence[0] &&
+                fenceMatch[1].length >= codeFence.length) {
+                codeFence = null;
+            }
+            if (mdStartLine === null)
+                mdStartLine = i;
+            continue;
+        }
+        if (fenceMatch) {
+            codeFence = fenceMatch[1];
+            if (mdStartLine === null)
+                mdStartLine = i;
+            continue;
+        }
+        const close = trimmed.match(CLOSE_RE);
+        if (close) {
+            popChildIfOpen(i);
+            flushMarkdown(i);
+            const frame = top();
+            if (!frame) {
+                diagnostics.push({
+                    code: 'CB_UNMATCHED_CLOSE',
+                    severity: 'warning',
+                    message: `Closing fence "${close[1]}" has no open block.`,
+                    position: lineRange(i),
+                });
+                mdStartLine = i; // keep it as literal markdown
+                continue;
+            }
+            if (close[1].length !== frame.node.fence) {
+                diagnostics.push({
+                    code: 'CB_FENCE_MISMATCH',
+                    severity: 'warning',
+                    message: `Closing fence has ${close[1].length} colons but ":::${frame.node.name}" opened with ${frame.node.fence}.`,
+                    hint: 'Match the opening fence length, or use a longer fence on the outer block to disambiguate nesting.',
+                    blockName: frame.node.name,
+                    position: lineRange(i),
+                });
+            }
+            stack.pop();
+            finalize(frame, i, i);
+            continue;
+        }
+        const open = trimmed.match(OPEN_RE);
+        if (open) {
+            flushMarkdown(i);
+            openBlock(i, open[1].length, open[2], open[3] ?? null);
+            continue;
+        }
+        const child = trimmed.match(CHILD_RE);
+        if (child) {
+            if (stack.length === 0) {
+                diagnostics.push({
+                    code: 'CB_CHILD_OUTSIDE_BLOCK',
+                    severity: 'warning',
+                    message: `Child block "::${child[1]}" used outside of a container block; treated as plain text.`,
+                    blockName: child[1],
+                    position: lineRange(i),
+                });
+                if (mdStartLine === null)
+                    mdStartLine = i;
+                continue;
+            }
+            popChildIfOpen(i);
+            flushMarkdown(i);
+            openBlock(i, 2, child[1], child[2] ?? null);
+            continue;
+        }
+        if (mdStartLine === null)
+            mdStartLine = i;
+    }
+    // EOF: close children implicitly, report unclosed containers.
+    flushMarkdown(lines.length);
+    while (stack.length > 0) {
+        const frame = stack.pop();
+        finalize(frame, lines.length, null);
+        if (frame.node.fence >= 3) {
+            diagnostics.push({
+                code: 'CB_UNCLOSED_BLOCK',
+                severity: 'error',
+                message: `Block ":::${frame.node.name}" is never closed.`,
+                hint: `Add a line containing only "${':'.repeat(frame.node.fence)}" after the block body.`,
+                blockName: frame.node.name,
+                position: frame.node.openPosition,
+            });
+        }
+    }
+    return { document, diagnostics };
+}

package/dist/position.d.ts

@@ -0,0 +1,8 @@
+import type { BlockNode } from './ast.js';
+import type { SourceRange } from './diagnostics.js';
+/**
+ * Document-level range of the Nth line (0-based) of a block's body.
+ * Content models use this so row/item diagnostics point at the exact line.
+ */
+export declare function bodyLineRange(node: BlockNode, bodyLineIndex: number): SourceRange;
+//# sourceMappingURL=position.d.ts.map

package/dist/position.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"position.d.ts","sourceRoot":"","sources":["../src/position.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAEnD;;;GAGG;AACH,wBAAgB,aAAa,CAAC,IAAI,EAAE,SAAS,EAAE,aAAa,EAAE,MAAM,GAAG,WAAW,CAUjF"}

package/dist/position.js

@@ -0,0 +1,16 @@
+/**
+ * Document-level range of the Nth line (0-based) of a block's body.
+ * Content models use this so row/item diagnostics point at the exact line.
+ */
+export function bodyLineRange(node, bodyLineIndex) {
+    const bodyLines = node.body.split('\n');
+    const text = bodyLines[bodyLineIndex] ?? '';
+    let offset = node.openPosition.end.offset + 1; // skip the newline after the open line
+    for (let i = 0; i < bodyLineIndex; i++)
+        offset += bodyLines[i].length + 1;
+    const line = node.openPosition.start.line + 1 + bodyLineIndex;
+    return {
+        start: { line, column: 1, offset },
+        end: { line, column: text.length + 1, offset: offset + text.length },
+    };
+}

package/dist/props.d.ts

@@ -0,0 +1,12 @@
+import type { Diagnostic, SourceRange } from './diagnostics.js';
+export interface ParsedProps {
+    props: Record<string, unknown>;
+    diagnostics: Diagnostic[];
+}
+/**
+ * Parses the `{...}` props segment of a block open line.
+ * Grammar: key="quoted" | key=123 | key=true | key=bare-ident | key (flag = true).
+ * No expressions, arrays, or objects — by design (spec: Content Syntax / Props).
+ */
+export declare function parseProps(raw: string | null, position: SourceRange): ParsedProps;
+//# sourceMappingURL=props.d.ts.map

package/dist/props.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"props.d.ts","sourceRoot":"","sources":["../src/props.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAA;AAM/D,MAAM,WAAW,WAAW;IAC1B,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAA;IAC9B,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED;;;;GAIG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,IAAI,EAAE,QAAQ,EAAE,WAAW,GAAG,WAAW,CAyFjF"}

package/dist/props.js

@@ -0,0 +1,98 @@
+const KEY_RE = /^[a-zA-Z][a-zA-Z0-9_-]*/;
+const NUMBER_RE = /^-?\d+(\.\d+)?$/;
+const IDENT_RE = /^[a-zA-Z][a-zA-Z0-9_-]*$/;
+/**
+ * Parses the `{...}` props segment of a block open line.
+ * Grammar: key="quoted" | key=123 | key=true | key=bare-ident | key (flag = true).
+ * No expressions, arrays, or objects — by design (spec: Content Syntax / Props).
+ */
+export function parseProps(raw, position) {
+    const props = {};
+    const diagnostics = [];
+    if (raw === null)
+        return { props, diagnostics };
+    const err = (message) => diagnostics.push({
+        code: 'CB_PROPS_SYNTAX',
+        severity: 'error',
+        message,
+        hint: 'Props accept quoted strings, numbers, booleans, and bare identifiers only.',
+        position,
+    });
+    if (!raw.endsWith('}')) {
+        return {
+            props: {},
+            diagnostics: [
+                {
+                    code: 'CB_PROPS_SYNTAX',
+                    severity: 'error',
+                    message: 'Props are missing the closing "}".',
+                    hint: 'Props accept quoted strings, numbers, booleans, and bare identifiers only.',
+                    position,
+                },
+            ],
+        };
+    }
+    const inner = raw.slice(1, -1);
+    let i = 0;
+    while (i < inner.length) {
+        while (i < inner.length && /\s/.test(inner[i]))
+            i++;
+        if (i >= inner.length)
+            break;
+        const keyMatch = inner.slice(i).match(KEY_RE);
+        if (!keyMatch) {
+            err(`Unexpected character "${inner[i]}" in props.`);
+            return { props, diagnostics };
+        }
+        const key = keyMatch[0];
+        i += key.length;
+        if (inner[i] !== '=') {
+            props[key] = true; // flag shorthand
+            continue;
+        }
+        i++;
+        if (inner[i] === '"') {
+            i++;
+            let value = '';
+            let closed = false;
+            while (i < inner.length) {
+                if (inner[i] === '\\' && inner[i + 1] === '"') {
+                    value += '"';
+                    i += 2;
+                    continue;
+                }
+                if (inner[i] === '"') {
+                    closed = true;
+                    i++;
+                    break;
+                }
+                value += inner[i];
+                i++;
+            }
+            if (!closed) {
+                err(`Unterminated string for prop "${key}".`);
+                return { props, diagnostics };
+            }
+            props[key] = value;
+            continue;
+        }
+        const valMatch = inner.slice(i).match(/^[^\s]+/);
+        if (!valMatch) {
+            err(`Missing value for prop "${key}".`);
+            return { props, diagnostics };
+        }
+        const rawVal = valMatch[0];
+        i += rawVal.length;
+        if (rawVal === 'true')
+            props[key] = true;
+        else if (rawVal === 'false')
+            props[key] = false;
+        else if (NUMBER_RE.test(rawVal))
+            props[key] = Number(rawVal);
+        else if (IDENT_RE.test(rawVal))
+            props[key] = rawVal;
+        else
+            err(`Invalid value "${rawVal}" for prop "${key}".`);
+    }
+    return { props, diagnostics };
+}

package/dist/registry.d.ts

@@ -0,0 +1,42 @@
+import type { ZodType } from 'zod';
+import type { BlockNode } from './ast.js';
+import type { Diagnostic } from './diagnostics.js';
+import { type AuthoringGuideOptions } from './authoring.js';
+export type Report = (d: Diagnostic) => void;
+/** How a block's body is parsed and validated. Created via content-model helpers. */
+export interface ContentModel<TData = unknown> {
+    kind: string;
+    /** One-line shape description used in generated authoring guides. */
+    describe(): string;
+    /** Parse the body; report() diagnostics with positions; always return best-effort data. */
+    parse(node: BlockNode, report: Report): TData;
+}
+export interface AuthoringMeta {
+    useWhen: string[];
+    avoidWhen: string[];
+    example: string;
+}
+export interface BlockDefinition<TData = unknown> {
+    name: string;
+    description: string;
+    /** zod schema for the open-line props. Omit for prop-less blocks. */
+    props?: ZodType;
+    content: ContentModel<TData>;
+    /** Only valid nested inside a parent that allows it (e.g. `tab` inside `tabs`). */
+    childOnly?: boolean;
+    /** Hint for renderers: needs client-side behavior (e.g. tabs). */
+    interactive?: boolean;
+    version?: string;
+    authoring: AuthoringMeta;
+}
+export declare function defineBlock<TData>(def: BlockDefinition<TData>): BlockDefinition<TData>;
+export declare class BlockRegistry {
+    private defs;
+    use(pack: ReadonlyArray<BlockDefinition<never>> | ReadonlyArray<BlockDefinition<unknown>>): this;
+    add(def: BlockDefinition<never> | BlockDefinition<unknown>): this;
+    get(name: string): BlockDefinition<unknown> | undefined;
+    all(): BlockDefinition<unknown>[];
+    toAuthoringGuide(opts?: AuthoringGuideOptions): string;
+}
+export declare function createBlockRegistry(): BlockRegistry;
+//# sourceMappingURL=registry.d.ts.map

package/dist/registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"registry.d.ts","sourceRoot":"","sources":["../src/registry.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAA;AAElC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,UAAU,CAAA;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAA;AAElD,OAAO,EAA0B,KAAK,qBAAqB,EAAE,MAAM,gBAAgB,CAAA;AAEnF,MAAM,MAAM,MAAM,GAAG,CAAC,CAAC,EAAE,UAAU,KAAK,IAAI,CAAA;AAE5C,qFAAqF;AACrF,MAAM,WAAW,YAAY,CAAC,KAAK,GAAG,OAAO;IAC3C,IAAI,EAAE,MAAM,CAAA;IACZ,qEAAqE;IACrE,QAAQ,IAAI,MAAM,CAAA;IAClB,2FAA2F;IAC3F,KAAK,CAAC,IAAI,EAAE,SAAS,EAAE,MAAM,EAAE,MAAM,GAAG,KAAK,CAAA;CAC9C;AAED,MAAM,WAAW,aAAa;IAC5B,OAAO,EAAE,MAAM,EAAE,CAAA;IACjB,SAAS,EAAE,MAAM,EAAE,CAAA;IACnB,OAAO,EAAE,MAAM,CAAA;CAChB;AAED,MAAM,WAAW,eAAe,CAAC,KAAK,GAAG,OAAO;IAC9C,IAAI,EAAE,MAAM,CAAA;IACZ,WAAW,EAAE,MAAM,CAAA;IACnB,qEAAqE;IACrE,KAAK,CAAC,EAAE,OAAO,CAAA;IACf,OAAO,EAAE,YAAY,CAAC,KAAK,CAAC,CAAA;IAC5B,mFAAmF;IACnF,SAAS,CAAC,EAAE,OAAO,CAAA;IACnB,kEAAkE;IAClE,WAAW,CAAC,EAAE,OAAO,CAAA;IACrB,OAAO,CAAC,EAAE,MAAM,CAAA;IAChB,SAAS,EAAE,aAAa,CAAA;CACzB;AAID,wBAAgB,WAAW,CAAC,KAAK,EAAE,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,KAAK,CAAC,CAKtF;AAED,qBAAa,aAAa;IACxB,OAAO,CAAC,IAAI,CAA8C;IAE1D,GAAG,CAAC,IAAI,EAAE,aAAa,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC,GAAG,aAAa,CAAC,eAAe,CAAC,OAAO,CAAC,CAAC,GAAG,IAAI;IAKhG,GAAG,CAAC,GAAG,EAAE,eAAe,CAAC,KAAK,CAAC,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,IAAI;IAWjE,GAAG,CAAC,IAAI,EAAE,MAAM,GAAG,eAAe,CAAC,OAAO,CAAC,GAAG,SAAS;IAIvD,GAAG,IAAI,eAAe,CAAC,OAAO,CAAC,EAAE;IAIjC,gBAAgB,CAAC,IAAI,GAAE,qBAA0B,GAAG,MAAM;CAG3D;AAED,wBAAgB,mBAAmB,IAAI,aAAa,CAEnD"}

package/dist/registry.js

@@ -0,0 +1,36 @@
+import { generateAuthoringGuide } from './authoring.js';
+const KEBAB_RE = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+export function defineBlock(def) {
+    if (!KEBAB_RE.test(def.name)) {
+        throw new Error(`Block name "${def.name}" must be lowercase kebab-case.`);
+    }
+    return def;
+}
+export class BlockRegistry {
+    defs = new Map();
+    use(pack) {
+        for (const def of pack)
+            this.add(def);
+        return this;
+    }
+    add(def) {
+        const d = def;
+        if (this.defs.has(d.name)) {
+            throw new Error(`Duplicate block "${d.name}". Namespace it (e.g. "acme-${d.name}") or remove the duplicate.`);
+        }
+        this.defs.set(d.name, d);
+        return this;
+    }
+    get(name) {
+        return this.defs.get(name);
+    }
+    all() {
+        return [...this.defs.values()];
+    }
+    toAuthoringGuide(opts = {}) {
+        return generateAuthoringGuide(this.all(), opts);
+    }
+}
+export function createBlockRegistry() {
+    return new BlockRegistry();
+}

package/dist/render-markdown.d.ts

@@ -0,0 +1,16 @@
+import type { ContentNode, DocumentNode } from './ast.js';
+import { type ValidatedBlockNode } from './validate.js';
+export interface MarkdownRenderContext {
+    renderNodes(nodes: ContentNode[]): string;
+}
+export type MarkdownBlockRenderer = (node: ValidatedBlockNode<unknown>, ctx: MarkdownRenderContext) => string;
+export interface RenderToMarkdownOptions {
+    renderers?: Record<string, MarkdownBlockRenderer>;
+}
+/**
+ * Plain-Markdown fallback: preserves prose verbatim, converts blocks via the
+ * supplied renderers, and degrades unrenderable blocks to their raw body so
+ * no information is lost (spec: Markdown fallback renderer).
+ */
+export declare function renderToMarkdown(document: DocumentNode, opts?: RenderToMarkdownOptions): string;
+//# sourceMappingURL=render-markdown.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"render-markdown.d.ts","sourceRoot":"","sources":["../src/render-markdown.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AAEzD,OAAO,EAAoB,KAAK,kBAAkB,EAAE,MAAM,eAAe,CAAA;AAEzE,MAAM,WAAW,qBAAqB;IACpC,WAAW,CAAC,KAAK,EAAE,WAAW,EAAE,GAAG,MAAM,CAAA;CAC1C;AAED,MAAM,MAAM,qBAAqB,GAAG,CAClC,IAAI,EAAE,kBAAkB,CAAC,OAAO,CAAC,EACjC,GAAG,EAAE,qBAAqB,KACvB,MAAM,CAAA;AAEX,MAAM,WAAW,uBAAuB;IACtC,SAAS,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,qBAAqB,CAAC,CAAA;CAClD;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAC9B,QAAQ,EAAE,YAAY,EACtB,IAAI,GAAE,uBAA4B,GACjC,MAAM,CAeR"}

package/dist/render-markdown.js

@@ -0,0 +1,24 @@
+import { isValidatedBlock } from './validate.js';
+/**
+ * Plain-Markdown fallback: preserves prose verbatim, converts blocks via the
+ * supplied renderers, and degrades unrenderable blocks to their raw body so
+ * no information is lost (spec: Markdown fallback renderer).
+ */
+export function renderToMarkdown(document, opts = {}) {
+    const ctx = {
+        renderNodes(nodes) {
+            return nodes
+                .map((node) => {
+                if (node.type === 'markdown')
+                    return node.value.trim();
+                const renderer = opts.renderers?.[node.name];
+                if (renderer && isValidatedBlock(node))
+                    return renderer(node, ctx).trim();
+                return node.body.trim();
+            })
+                .filter((s) => s !== '')
+                .join('\n\n');
+        },
+    };
+    return ctx.renderNodes(document.children) + '\n';
+}

package/dist/validate.d.ts

@@ -0,0 +1,24 @@
+import type { BlockNode, ContentNode, DocumentNode } from './ast.js';
+import type { Diagnostic } from './diagnostics.js';
+import type { ParseResult } from './parser.js';
+import type { BlockDefinition, BlockRegistry } from './registry.js';
+export interface ValidateOptions {
+    /** Severity of unknown block names. Default "error". */
+    unknownBlocks?: 'error' | 'warning';
+    /** Max block nesting depth. Default 4. */
+    maxDepth?: number;
+    /** URL protocols allowed in markdown links. Default http/https/mailto. */
+    allowedProtocols?: string[];
+}
+export interface ValidationResult {
+    ok: boolean;
+    document: DocumentNode;
+    diagnostics: Diagnostic[];
+}
+export type ValidatedBlockNode<TData = unknown> = BlockNode & {
+    data: TData;
+    definition: BlockDefinition<TData>;
+};
+export declare function isValidatedBlock(node: ContentNode): node is ValidatedBlockNode;
+export declare function validateDocument(parsed: ParseResult, registry: BlockRegistry, options?: ValidateOptions): ValidationResult;
+//# sourceMappingURL=validate.d.ts.map

package/dist/validate.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validate.d.ts","sourceRoot":"","sources":["../src/validate.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,WAAW,EAAE,YAAY,EAAE,MAAM,UAAU,CAAA;AACpE,OAAO,KAAK,EAAE,UAAU,EAAe,MAAM,kBAAkB,CAAA;AAC/D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAA;AAC9C,OAAO,KAAK,EAAE,eAAe,EAAE,aAAa,EAAE,MAAM,eAAe,CAAA;AAEnE,MAAM,WAAW,eAAe;IAC9B,wDAAwD;IACxD,aAAa,CAAC,EAAE,OAAO,GAAG,SAAS,CAAA;IACnC,0CAA0C;IAC1C,QAAQ,CAAC,EAAE,MAAM,CAAA;IACjB,0EAA0E;IAC1E,gBAAgB,CAAC,EAAE,MAAM,EAAE,CAAA;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,EAAE,EAAE,OAAO,CAAA;IACX,QAAQ,EAAE,YAAY,CAAA;IACtB,WAAW,EAAE,UAAU,EAAE,CAAA;CAC1B;AAED,MAAM,MAAM,kBAAkB,CAAC,KAAK,GAAG,OAAO,IAAI,SAAS,GAAG;IAC5D,IAAI,EAAE,KAAK,CAAA;IACX,UAAU,EAAE,eAAe,CAAC,KAAK,CAAC,CAAA;CACnC,CAAA;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,WAAW,GAAG,IAAI,IAAI,kBAAkB,CAE9E;AA4BD,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,WAAW,EACnB,QAAQ,EAAE,aAAa,EACvB,OAAO,GAAE,eAAoB,GAC5B,gBAAgB,CA4FlB"}

package/dist/validate.js

@@ -0,0 +1,114 @@
+export function isValidatedBlock(node) {
+    return node.type === 'block' && 'data' in node && 'definition' in node;
+}
+const LINK_URL_RE = /\]\(([^)\s]+)/g;
+const HAS_SCHEME_RE = /^[a-zA-Z][a-zA-Z0-9+.-]*:/;
+function checkUrls(value, position, allowed, report) {
+    for (const match of value.matchAll(LINK_URL_RE)) {
+        const url = match[1];
+        const scheme = url.match(HAS_SCHEME_RE);
+        if (!scheme)
+            continue; // relative URLs are fine
+        const protocol = `${scheme[0].slice(0, -1).toLowerCase()}:`;
+        if (!allowed.includes(protocol)) {
+            report({
+                code: 'CB_URL_PROTOCOL',
+                severity: 'error',
+                message: `URL protocol "${protocol}" is not allowed.`,
+                hint: `Allowed: ${allowed.join(', ')}. Configure via validateDocument options.allowedProtocols.`,
+                position,
+            });
+        }
+    }
+}
+export function validateDocument(parsed, registry, options = {}) {
+    const opts = {
+        unknownBlocks: options.unknownBlocks ?? 'error',
+        maxDepth: options.maxDepth ?? 4,
+        allowedProtocols: options.allowedProtocols ?? ['http:', 'https:', 'mailto:'],
+    };
+    const diagnostics = [...parsed.diagnostics];
+    const report = (d) => diagnostics.push(d);
+    function walk(nodes, parent, depth) {
+        for (const node of nodes) {
+            if (node.type === 'markdown') {
+                checkUrls(node.value, node.position, opts.allowedProtocols, report);
+                continue;
+            }
+            if (depth > opts.maxDepth) {
+                report({
+                    code: 'CB_NESTING_DEPTH',
+                    severity: 'error',
+                    message: `Block "${node.name}" exceeds the maximum nesting depth of ${opts.maxDepth}.`,
+                    blockName: node.name,
+                    position: node.openPosition,
+                });
+                continue;
+            }
+            const def = registry.get(node.name);
+            if (!def) {
+                report({
+                    code: 'CB_UNKNOWN_BLOCK',
+                    severity: opts.unknownBlocks,
+                    message: `Unknown block "${node.name}".`,
+                    hint: `Known blocks: ${registry
+                        .all()
+                        .map((d) => d.name)
+                        .join(', ')}.`,
+                    blockName: node.name,
+                    position: node.openPosition,
+                });
+                continue;
+            }
+            let valid = true;
+            if (def.childOnly && parent === null) {
+                valid = false;
+                report({
+                    code: 'CB_CHILD_ONLY',
+                    severity: 'error',
+                    message: `"${node.name}" is a child block and cannot be used at the top level.`,
+                    blockName: node.name,
+                    position: node.openPosition,
+                });
+            }
+            if (def.props) {
+                const result = def.props.safeParse(node.props);
+                if (result.success) {
+                    node.props = result.data;
+                }
+                else {
+                    valid = false;
+                    for (const issue of result.error.issues) {
+                        report({
+                            code: 'CB_PROPS_INVALID',
+                            severity: 'error',
+                            message: `${node.name}: prop "${issue.path.join('.') || '(root)'}" ${issue.message}`,
+                            blockName: node.name,
+                            position: node.openPosition,
+                        });
+                    }
+                }
+            }
+            const before = diagnostics.length;
+            const data = def.content.parse(node, report);
+            let contentError = false;
+            for (let j = before; j < diagnostics.length; j++) {
+                if (diagnostics[j].severity === 'error') {
+                    contentError = true;
+                    break;
+                }
+            }
+            if (contentError)
+                valid = false;
+            if (valid) {
+                ;
+                node.data = data;
+                node.definition = def;
+            }
+            walk(node.children, node, depth + 1);
+        }
+    }
+    walk(parsed.document.children, null, 1);
+    const ok = !diagnostics.some((d) => d.severity === 'error');
+    return { ok, document: parsed.document, diagnostics };
+}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION = "0.1.0";
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,eAAO,MAAM,OAAO,UAAU,CAAA"}

package/dist/version.js

@@ -0,0 +1 @@
+export const VERSION = '0.1.0';

package/package.json

@@ -0,0 +1,47 @@
+{
+  "name": "@contentbit/core",
+  "version": "0.1.0",
+  "description": "Parser, validator, and registry for Content Blocks: structured Markdown components without framework lock-in.",
+  "keywords": [
+    "ast",
+    "content",
+    "directives",
+    "llm",
+    "markdown",
+    "validation"
+  ],
+  "homepage": "https://contentbit.dev",
+  "bugs": "https://github.com/agonist/contentbit/issues",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/agonist/contentbit.git",
+    "directory": "packages/core"
+  },
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "zod": "^4.0.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.17"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  }
+}