@texuli/blocks 0.0.0-stage → 0.1.0-next.0

package/dist/core/schema/media-family.js

@@ -0,0 +1,260 @@
+import { classifyMediaSource } from "../safety.js";
+import { plainObject } from "./parse-family.js";
+import { BLOCK_CONTENT_LIMITS, fail, ok, parsePlainText, } from "./primitives.js";
+function parseMediaDimension(value, path) {
+    if (typeof value !== 'number' ||
+        !Number.isInteger(value) ||
+        value < 1 ||
+        value > BLOCK_CONTENT_LIMITS.mediaDimension) {
+        return fail(path, `dimension must be an integer from 1 to ${BLOCK_CONTENT_LIMITS.mediaDimension}`);
+    }
+    return ok(value);
+}
+function parseImageSource(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        return fail(path, 'src must be a non-empty string');
+    }
+    const result = classifyMediaSource(value, 'image');
+    if (!result.ok)
+        return fail(path, result.message);
+    return ok(value);
+}
+function parseVideoSource(value, path) {
+    if (typeof value !== 'string' || value.length === 0) {
+        return fail(path, 'src must be a non-empty string');
+    }
+    const result = classifyMediaSource(value, 'video');
+    if (!result.ok)
+        return fail(path, result.message);
+    return ok(value);
+}
+function parseFit(value, path) {
+    if (value === undefined)
+        return ok(undefined);
+    if (value !== 'contain' && value !== 'cover') {
+        return fail(path, 'fit must be "contain" or "cover"');
+    }
+    return ok(value);
+}
+function parseOptionalBoolean(value, path) {
+    if (value === undefined)
+        return ok(undefined);
+    if (typeof value !== 'boolean')
+        return fail(path, 'must be a boolean');
+    return ok(value);
+}
+function parseAltRules(record, path) {
+    const decorative = parseOptionalBoolean(record.decorative, [...path, 'decorative']);
+    if (!decorative.success)
+        return decorative;
+    let alt;
+    if (record.alt !== undefined) {
+        const parsed = parsePlainText(record.alt, [...path, 'alt'], 280);
+        if (!parsed.success)
+            return parsed;
+        alt = parsed.data;
+    }
+    if (decorative.data === true && alt !== undefined) {
+        return fail([...path, 'alt'], 'A decorative image has no alt text; drop alt or decorative');
+    }
+    if (decorative.data !== true && alt === undefined) {
+        return fail([...path, 'alt'], 'Describe the image in alt, or mark it decorative: true');
+    }
+    return ok({
+        ...(alt !== undefined ? { alt } : {}),
+        ...(decorative.data !== undefined ? { decorative: decorative.data } : {}),
+    });
+}
+function parseImageLikeFields(record, path) {
+    const src = parseImageSource(record.src, [...path, 'src']);
+    if (!src.success)
+        return src;
+    const width = parseMediaDimension(record.width, [...path, 'width']);
+    if (!width.success)
+        return width;
+    const height = parseMediaDimension(record.height, [...path, 'height']);
+    if (!height.success)
+        return height;
+    const altRules = parseAltRules(record, path);
+    if (!altRules.success)
+        return altRules;
+    const fit = parseFit(record.fit, [...path, 'fit']);
+    if (!fit.success)
+        return fit;
+    let credit;
+    if (record.credit !== undefined) {
+        const parsed = parsePlainText(record.credit, [...path, 'credit'], 120);
+        if (!parsed.success)
+            return parsed;
+        credit = parsed.data;
+    }
+    return ok({
+        src: src.data,
+        width: width.data,
+        height: height.data,
+        ...altRules.data,
+        ...(fit.data !== undefined ? { fit: fit.data } : {}),
+        ...(credit !== undefined ? { credit } : {}),
+    });
+}
+function parseImage(record, path, base) {
+    const fields = parseImageLikeFields(record, path);
+    if (!fields.success)
+        return fields;
+    let caption;
+    if (record.caption !== undefined) {
+        const parsed = parsePlainText(record.caption, [...path, 'caption'], 280);
+        if (!parsed.success)
+            return parsed;
+        caption = parsed.data;
+    }
+    return ok({
+        ...base,
+        type: 'image',
+        ...fields.data,
+        ...(caption !== undefined ? { caption } : {}),
+    });
+}
+function parseFigure(record, path, base) {
+    const fields = parseImageLikeFields(record, path);
+    if (!fields.success)
+        return fields;
+    const caption = parsePlainText(record.caption, [...path, 'caption'], 280);
+    if (!caption.success)
+        return caption;
+    return ok({
+        ...base,
+        type: 'figure',
+        ...fields.data,
+        caption: caption.data,
+    });
+}
+function parseVideo(record, path, base) {
+    const src = parseVideoSource(record.src, [...path, 'src']);
+    if (!src.success)
+        return src;
+    const label = parsePlainText(record.label, [...path, 'label'], 160);
+    if (!label.success)
+        return label;
+    const width = parseMediaDimension(record.width, [...path, 'width']);
+    if (!width.success)
+        return width;
+    const height = parseMediaDimension(record.height, [...path, 'height']);
+    if (!height.success)
+        return height;
+    let poster;
+    if (record.poster !== undefined) {
+        const parsed = parseImageSource(record.poster, [...path, 'poster']);
+        if (!parsed.success)
+            return parsed;
+        poster = parsed.data;
+    }
+    let caption;
+    if (record.caption !== undefined) {
+        const parsed = parsePlainText(record.caption, [...path, 'caption'], 280);
+        if (!parsed.success)
+            return parsed;
+        caption = parsed.data;
+    }
+    const autoplay = parseOptionalBoolean(record.autoplay, [...path, 'autoplay']);
+    if (!autoplay.success)
+        return autoplay;
+    const loop = parseOptionalBoolean(record.loop, [...path, 'loop']);
+    if (!loop.success)
+        return loop;
+    const muted = parseOptionalBoolean(record.muted, [...path, 'muted']);
+    if (!muted.success)
+        return muted;
+    const controls = parseOptionalBoolean(record.controls, [...path, 'controls']);
+    if (!controls.success)
+        return controls;
+    if (autoplay.data === true && muted.data !== true) {
+        return fail([...path, 'muted'], 'An autoplaying video must be muted: true');
+    }
+    return ok({
+        ...base,
+        type: 'video',
+        src: src.data,
+        label: label.data,
+        width: width.data,
+        height: height.data,
+        ...(poster !== undefined ? { poster } : {}),
+        ...(caption !== undefined ? { caption } : {}),
+        ...(autoplay.data !== undefined ? { autoplay: autoplay.data } : {}),
+        ...(loop.data !== undefined ? { loop: loop.data } : {}),
+        ...(muted.data !== undefined ? { muted: muted.data } : {}),
+        ...(controls.data !== undefined ? { controls: controls.data } : {}),
+    });
+}
+function parseGalleryItem(value, path) {
+    const object = plainObject(value, path);
+    if (!object.success)
+        return object;
+    const fields = parseImageLikeFields(object.data, path);
+    if (!fields.success)
+        return fields;
+    let caption;
+    if (object.data.caption !== undefined) {
+        const parsed = parsePlainText(object.data.caption, [...path, 'caption'], 280);
+        if (!parsed.success)
+            return parsed;
+        caption = parsed.data;
+    }
+    // Gallery items do not carry credit (block-level only on figure/image).
+    const { credit: _credit, ...item } = fields.data;
+    return ok({
+        ...item,
+        ...(caption !== undefined ? { caption } : {}),
+    });
+}
+function parseGallery(record, path, base) {
+    if (!Array.isArray(record.items) || record.items.length === 0) {
+        return fail([...path, 'items'], 'gallery needs at least one item');
+    }
+    if (record.items.length > BLOCK_CONTENT_LIMITS.galleryItems) {
+        return fail([...path, 'items'], `gallery may contain at most ${BLOCK_CONTENT_LIMITS.galleryItems} items`);
+    }
+    const items = [];
+    for (let i = 0; i < record.items.length; i += 1) {
+        const item = parseGalleryItem(record.items[i], [...path, 'items', i]);
+        if (!item.success)
+            return item;
+        items.push(item.data);
+    }
+    let title;
+    if (record.title !== undefined) {
+        const parsed = parsePlainText(record.title, [...path, 'title'], 120);
+        if (!parsed.success)
+            return parsed;
+        title = parsed.data;
+    }
+    let columns;
+    if (record.columns !== undefined) {
+        if (record.columns !== 2 && record.columns !== 3 && record.columns !== 4) {
+            return fail([...path, 'columns'], 'columns must be 2, 3 or 4');
+        }
+        columns = record.columns;
+    }
+    return ok({
+        ...base,
+        type: 'gallery',
+        items,
+        ...(title !== undefined ? { title } : {}),
+        ...(columns !== undefined ? { columns } : {}),
+    });
+}
+/** Media family: image, figure, video and gallery. */
+export function parseMediaFamilyBlock(type, record, path, base) {
+    switch (type) {
+        case 'image':
+            return parseImage(record, path, base);
+        case 'figure':
+            return parseFigure(record, path, base);
+        case 'video':
+            return parseVideo(record, path, base);
+        case 'gallery':
+            return parseGallery(record, path, base);
+        default:
+            return null;
+    }
+}

package/dist/core/schema/parse-family.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Shared entry for family-scoped block parsing (no family parser imported here).
+ */
+import { type BlockBase, type ParseResult } from './primitives.js';
+export declare function plainObject(value: unknown, path: (string | number)[]): ParseResult<Record<string, unknown>>;
+/** One family's parser: the block for `type`, or `null` when the type is not the family's. */
+export type FamilyParser = (type: string, record: Record<string, unknown>, path: (string | number)[], base: BlockBase) => ParseResult<unknown> | null;
+/**
+ * Parses one untrusted block with only the given family parsers: the plain
+ * object and the shared base fields first, then the family's own rules. A
+ * family renderer uses this instead of \`safeParseBlock\`, so it bundles its
+ * own parser and not every family's. A type no parser claims is rejected.
+ */
+export declare function parseFamilyBlock<T>(value: unknown, parsers: readonly FamilyParser[], family: string): ParseResult<T>;

package/dist/core/schema/parse-family.js

@@ -0,0 +1,37 @@
+/**
+ * Shared entry for family-scoped block parsing (no family parser imported here).
+ */
+import { fail, ok, parseBlockBase } from "./primitives.js";
+export function plainObject(value, path) {
+    if (value === null || typeof value !== 'object' || Array.isArray(value)) {
+        return fail(path, 'Expected a plain block object');
+    }
+    const prototype = Object.getPrototypeOf(value);
+    if (prototype !== Object.prototype && prototype !== null) {
+        return fail(path, 'Block objects must be plain JSON data');
+    }
+    return ok(value);
+}
+/**
+ * Parses one untrusted block with only the given family parsers: the plain
+ * object and the shared base fields first, then the family's own rules. A
+ * family renderer uses this instead of \`safeParseBlock\`, so it bundles its
+ * own parser and not every family's. A type no parser claims is rejected.
+ */
+export function parseFamilyBlock(value, parsers, family) {
+    const object = plainObject(value, []);
+    if (!object.success)
+        return object;
+    const record = object.data;
+    if (typeof record.type !== 'string')
+        return fail(['type'], 'block type is required');
+    const base = parseBlockBase(record, []);
+    if (!base.success)
+        return base;
+    for (const parse of parsers) {
+        const parsed = parse(record.type, record, [], base.data);
+        if (parsed)
+            return parsed;
+    }
+    return fail(['type'], `"${record.type}" is not a ${family} block`);
+}

package/dist/core/schema/primitives.d.ts

@@ -0,0 +1,73 @@
+import { type BlockReveal, type BlockTone } from './vocabulary.js';
+/**
+ * Content limits per block. They follow layout limits so a block always fits a
+ * slide, a page section or a doc. Owned validators — no third-party schema lib.
+ */
+export declare const BLOCK_CONTENT_LIMITS: Readonly<{
+    markdown: 4000;
+    shortMarkdown: 600;
+    listItems: 12;
+    statItems: 6;
+    tableColumns: 8;
+    tableRows: 50;
+    timelineEvents: 12;
+    steps: 8;
+    comparisonColumns: 4;
+    comparisonRows: 8;
+    cards: 12;
+    people: 24;
+    ctaActions: 3;
+    columns: 4;
+    blocksPerColumn: 12;
+    containerDepth: 3;
+    tabPanels: 6;
+    pollOptions: 8;
+    formFields: 20;
+    formTextLength: 4000;
+    code: 20000;
+    codeLines: 400;
+    /** Highlight steps per code block, characters per line spec, caption length. */
+    codeHighlightSteps: 16;
+    codeHighlightSpec: 120;
+    codeCaption: 200;
+    mediaDimension: 4096;
+    galleryItems: 12;
+    href: 2048;
+    heading: 200;
+    plain: 500;
+}>;
+/** Blueprint-style JSONPath, e.g. `$[0]["text"]`. */
+export declare function toJsonPath(path: readonly (string | number)[]): string;
+export interface FieldIssue {
+    path: (string | number)[];
+    message: string;
+}
+export type ParseOk<T> = {
+    success: true;
+    data: T;
+    issues: [];
+};
+export type ParseFail = {
+    success: false;
+    data: null;
+    issues: FieldIssue[];
+};
+export type ParseResult<T> = ParseOk<T> | ParseFail;
+export declare function ok<T>(data: T): ParseOk<T>;
+export declare function fail(path: (string | number)[], message: string): ParseFail;
+export declare function failMany(issues: FieldIssue[]): ParseFail;
+export declare function parseBlockId(value: unknown, path: (string | number)[]): ParseResult<string | undefined>;
+export declare function parseStep(value: unknown, path: (string | number)[]): ParseResult<number | undefined>;
+export declare function parseTone(value: unknown, path: (string | number)[]): ParseResult<BlockTone | undefined>;
+export declare function parseReveal(value: unknown, path: (string | number)[]): ParseResult<BlockReveal | undefined>;
+/** One line of plain text: no line breaks, control or bidi override characters. */
+export declare function parsePlainText(value: unknown, path: (string | number)[], max: number): ParseResult<string>;
+/** Multiline markdown-ish body: newlines allowed; tabs only when allowTabs. */
+export declare function parseMultilineText(value: unknown, path: (string | number)[], max: number, allowTabs?: boolean): ParseResult<string>;
+export interface BlockBase {
+    id?: string;
+    step?: number;
+    reveal?: BlockReveal;
+    tone?: BlockTone;
+}
+export declare function parseBlockBase(record: Record<string, unknown>, path: (string | number)[]): ParseResult<BlockBase>;

package/dist/core/schema/primitives.js

@@ -0,0 +1,140 @@
+import { hasUnsafeText } from "../safety.js";
+import { isBlockReveal, isBlockTone } from "./vocabulary.js";
+/**
+ * Content limits per block. They follow layout limits so a block always fits a
+ * slide, a page section or a doc. Owned validators — no third-party schema lib.
+ */
+export const BLOCK_CONTENT_LIMITS = Object.freeze({
+    markdown: 4_000,
+    shortMarkdown: 600,
+    listItems: 12,
+    statItems: 6,
+    tableColumns: 8,
+    tableRows: 50,
+    timelineEvents: 12,
+    steps: 8,
+    comparisonColumns: 4,
+    comparisonRows: 8,
+    cards: 12,
+    people: 24,
+    ctaActions: 3,
+    columns: 4,
+    blocksPerColumn: 12,
+    containerDepth: 3,
+    tabPanels: 6,
+    pollOptions: 8,
+    formFields: 20,
+    formTextLength: 4_000,
+    code: 20_000,
+    codeLines: 400,
+    /** Highlight steps per code block, characters per line spec, caption length. */
+    codeHighlightSteps: 16,
+    codeHighlightSpec: 120,
+    codeCaption: 200,
+    mediaDimension: 4_096,
+    galleryItems: 12,
+    href: 2_048,
+    heading: 200,
+    plain: 500,
+});
+/** Blueprint-style JSONPath, e.g. `$[0]["text"]`. */
+export function toJsonPath(path) {
+    let result = '$';
+    for (const segment of path) {
+        result += typeof segment === 'number' ? `[${segment}]` : `[${JSON.stringify(segment)}]`;
+    }
+    return result;
+}
+export function ok(data) {
+    return { success: true, data, issues: [] };
+}
+export function fail(path, message) {
+    return { success: false, data: null, issues: [{ path, message }] };
+}
+export function failMany(issues) {
+    return { success: false, data: null, issues };
+}
+/** A stable block id: deep links and interactive state keys use it. */
+const BLOCK_ID = /^[a-z][a-z0-9-]{0,47}$/;
+export function parseBlockId(value, path) {
+    if (value === undefined)
+        return ok(undefined);
+    if (typeof value !== 'string' || !BLOCK_ID.test(value)) {
+        return fail(path, 'Use 1–48 lowercase letters, digits or hyphens, starting with a letter');
+    }
+    return ok(value);
+}
+export function parseStep(value, path) {
+    if (value === undefined)
+        return ok(undefined);
+    if (typeof value !== 'number' || !Number.isInteger(value) || value < 0 || value > 32) {
+        return fail(path, 'step must be an integer from 0 to 32');
+    }
+    return ok(value);
+}
+export function parseTone(value, path) {
+    if (value === undefined)
+        return ok(undefined);
+    if (!isBlockTone(value))
+        return fail(path, 'tone must be a block tone token');
+    return ok(value);
+}
+export function parseReveal(value, path) {
+    if (value === undefined)
+        return ok(undefined);
+    if (!isBlockReveal(value))
+        return fail(path, 'reveal must be a known animation token');
+    return ok(value);
+}
+/** One line of plain text: no line breaks, control or bidi override characters. */
+export function parsePlainText(value, path, max) {
+    if (typeof value !== 'string')
+        return fail(path, 'Expected a string');
+    if (value.length === 0)
+        return fail(path, 'Text must not be empty');
+    if ([...value].length > max)
+        return fail(path, `Text must be at most ${max} characters`);
+    if (hasUnsafeText(value, false, false)) {
+        return fail(path, 'Text contains control or bidi override characters');
+    }
+    if (/[\r\n]/.test(value))
+        return fail(path, 'Plain text must be a single line');
+    return ok(value);
+}
+/** Multiline markdown-ish body: newlines allowed; tabs only when allowTabs. */
+export function parseMultilineText(value, path, max, allowTabs = false) {
+    if (typeof value !== 'string')
+        return fail(path, 'Expected a string');
+    if (value.length === 0)
+        return fail(path, 'Text must not be empty');
+    if ([...value].length > max)
+        return fail(path, `Text must be at most ${max} characters`);
+    if (hasUnsafeText(value, true, allowTabs)) {
+        return fail(path, 'Text contains control or bidi override characters');
+    }
+    return ok(value);
+}
+export function parseBlockBase(record, path) {
+    const id = parseBlockId(record.id, [...path, 'id']);
+    if (!id.success)
+        return id;
+    const step = parseStep(record.step, [...path, 'step']);
+    if (!step.success)
+        return step;
+    const reveal = parseReveal(record.reveal, [...path, 'reveal']);
+    if (!reveal.success)
+        return reveal;
+    const tone = parseTone(record.tone, [...path, 'tone']);
+    if (!tone.success)
+        return tone;
+    const base = {};
+    if (id.data !== undefined)
+        base.id = id.data;
+    if (step.data !== undefined)
+        base.step = step.data;
+    if (reveal.data !== undefined)
+        base.reveal = reveal.data;
+    if (tone.data !== undefined)
+        base.tone = tone.data;
+    return ok(base);
+}

package/dist/core/schema/text-family.d.ts

@@ -0,0 +1,4 @@
+import type { CalloutBlock, HeadingBlock, ListBlock, QuoteBlock, TextBlock } from './blocks.js';
+import { type BlockBase, type ParseResult } from './primitives.js';
+/** Text family: heading, text, list, quote and callout. */
+export declare function parseTextFamilyBlock(type: string, record: Record<string, unknown>, path: (string | number)[], base: BlockBase): ParseResult<HeadingBlock | TextBlock | ListBlock | QuoteBlock | CalloutBlock> | null;

package/dist/core/schema/text-family.js

@@ -0,0 +1,121 @@
+import { plainObject } from "./parse-family.js";
+import { BLOCK_CONTENT_LIMITS, fail, ok, parseMultilineText, parsePlainText, } from "./primitives.js";
+function parseHeading(record, path, base) {
+    const level = record.level;
+    if (level !== 1 && level !== 2 && level !== 3 && level !== 4) {
+        return fail([...path, 'level'], 'heading level must be 1–4');
+    }
+    const text = parsePlainText(record.text, [...path, 'text'], BLOCK_CONTENT_LIMITS.heading);
+    if (!text.success)
+        return text;
+    let eyebrow;
+    if (record.eyebrow !== undefined) {
+        const parsed = parsePlainText(record.eyebrow, [...path, 'eyebrow'], BLOCK_CONTENT_LIMITS.plain);
+        if (!parsed.success)
+            return parsed;
+        eyebrow = parsed.data;
+    }
+    let subtitle;
+    if (record.subtitle !== undefined) {
+        const parsed = parsePlainText(record.subtitle, [...path, 'subtitle'], BLOCK_CONTENT_LIMITS.plain);
+        if (!parsed.success)
+            return parsed;
+        subtitle = parsed.data;
+    }
+    return ok({
+        ...base,
+        type: 'heading',
+        level,
+        text: text.data,
+        ...(eyebrow !== undefined ? { eyebrow } : {}),
+        ...(subtitle !== undefined ? { subtitle } : {}),
+    });
+}
+function parseTextBlock(record, path, base) {
+    const markdown = parseMultilineText(record.markdown, [...path, 'markdown'], BLOCK_CONTENT_LIMITS.markdown);
+    if (!markdown.success)
+        return markdown;
+    return ok({ ...base, type: 'text', markdown: markdown.data });
+}
+function parseList(record, path, base) {
+    if (!Array.isArray(record.items) || record.items.length === 0) {
+        return fail([...path, 'items'], 'list needs at least one item');
+    }
+    if (record.items.length > BLOCK_CONTENT_LIMITS.listItems) {
+        return fail([...path, 'items'], `list may contain at most ${BLOCK_CONTENT_LIMITS.listItems} items`);
+    }
+    const items = [];
+    for (let i = 0; i < record.items.length; i += 1) {
+        const itemPath = [...path, 'items', i];
+        const item = plainObject(record.items[i], itemPath);
+        if (!item.success)
+            return item;
+        const text = parseMultilineText(item.data.text, [...itemPath, 'text'], BLOCK_CONTENT_LIMITS.shortMarkdown);
+        if (!text.success)
+            return text;
+        items.push({ text: text.data });
+    }
+    const ordered = record.ordered === true ? true : record.ordered === false ? false : undefined;
+    if (record.ordered !== undefined && ordered === undefined) {
+        return fail([...path, 'ordered'], 'ordered must be a boolean');
+    }
+    return ok({
+        ...base,
+        type: 'list',
+        items,
+        ...(ordered !== undefined ? { ordered } : {}),
+    });
+}
+function parseQuote(record, path, base) {
+    const quote = parseMultilineText(record.quote, [...path, 'quote'], BLOCK_CONTENT_LIMITS.shortMarkdown);
+    if (!quote.success)
+        return quote;
+    let cite;
+    if (record.cite !== undefined) {
+        const parsed = parsePlainText(record.cite, [...path, 'cite'], BLOCK_CONTENT_LIMITS.plain);
+        if (!parsed.success)
+            return parsed;
+        cite = parsed.data;
+    }
+    return ok({
+        ...base,
+        type: 'quote',
+        quote: quote.data,
+        ...(cite !== undefined ? { cite } : {}),
+    });
+}
+function parseCallout(record, path, base) {
+    const body = parseMultilineText(record.body, [...path, 'body'], BLOCK_CONTENT_LIMITS.shortMarkdown);
+    if (!body.success)
+        return body;
+    let title;
+    if (record.title !== undefined) {
+        const parsed = parsePlainText(record.title, [...path, 'title'], BLOCK_CONTENT_LIMITS.plain);
+        if (!parsed.success)
+            return parsed;
+        title = parsed.data;
+    }
+    return ok({
+        ...base,
+        type: 'callout',
+        body: body.data,
+        ...(title !== undefined ? { title } : {}),
+    });
+}
+/** Text family: heading, text, list, quote and callout. */
+export function parseTextFamilyBlock(type, record, path, base) {
+    switch (type) {
+        case 'heading':
+            return parseHeading(record, path, base);
+        case 'text':
+            return parseTextBlock(record, path, base);
+        case 'list':
+            return parseList(record, path, base);
+        case 'quote':
+            return parseQuote(record, path, base);
+        case 'callout':
+            return parseCallout(record, path, base);
+        default:
+            return null;
+    }
+}

package/dist/core/schema/vocabulary.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Colors in block data are tones, never CSS, hex values or style strings.
+ * Renderers map each tone to theme tokens so contrast holds in every theme.
+ */
+export declare const BLOCK_TONES: readonly ["neutral", "accent", "info", "success", "warning", "danger"];
+export type BlockTone = (typeof BLOCK_TONES)[number];
+/**
+ * Render families. Each one is a lazy UI subpath so a document downloads only
+ * the families its blocks use.
+ */
+export declare const BLOCK_FAMILIES: readonly ["text", "media", "data", "structure", "code", "diagram", "interactive", "map", "embed"];
+export type BlockFamily = (typeof BLOCK_FAMILIES)[number];
+/** True when `value` is one of the block tones. */
+export declare function isBlockTone(value: unknown): value is BlockTone;
+/** True when `value` is one of the render families. */
+export declare function isBlockFamily(value: unknown): value is BlockFamily;
+/** Fragment order inside a slide; pages and docs ignore it. */
+export declare const BLOCK_REVEALS: readonly ["fade", "fade-up", "grow", "highlight", "strike"];
+export type BlockReveal = (typeof BLOCK_REVEALS)[number];
+export declare function isBlockReveal(value: unknown): value is BlockReveal;