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

package/dist/core/formula/parse.js

@@ -0,0 +1,452 @@
+/** Caps that keep parsing and evaluation small and linear. */
+export const FORMULA_LIMITS = Object.freeze({
+    nodes: 64,
+    depth: 12,
+    args: 8,
+    exponent: 64,
+    roundDigits: 6,
+    literal: 1e15,
+});
+const NUMBER_OPS = [
+    'num',
+    'var',
+    'add',
+    'sub',
+    'mul',
+    'div',
+    'pow',
+    'min',
+    'max',
+    'round',
+    'clamp',
+    'if',
+];
+const CONDITION_OPS = ['lt', 'lte', 'gt', 'gte', 'eq', 'neq', 'and', 'or', 'not'];
+const RESERVED_VARIABLE_NAMES = new Set(['constructor', 'prototype']);
+const VARIABLE_NAME = /^[a-z][a-zA-Z0-9]{0,31}$/;
+export function formulaJsonPath(path) {
+    let result = '$';
+    for (const segment of path) {
+        result += typeof segment === 'number' ? `[${segment}]` : `[${JSON.stringify(segment)}]`;
+    }
+    return result;
+}
+function diagnostic(code, path, message, hint) {
+    return { code, path, jsonPath: formulaJsonPath(path), message, hint };
+}
+function preflight(input) {
+    const seen = new WeakSet();
+    const stack = [
+        { value: input, depth: 0, path: [] },
+    ];
+    let nodes = 0;
+    let containers = 0;
+    const tooLarge = (path) => diagnostic('formula-too-large', path, `A formula has at most ${FORMULA_LIMITS.nodes} nodes`, 'Split the calculation into several outputs, or simplify it.');
+    while (stack.length > 0) {
+        const current = stack.pop();
+        if (!current)
+            continue;
+        const { value, path } = current;
+        if (value === null || typeof value !== 'object')
+            continue;
+        if (seen.has(value)) {
+            return diagnostic('cyclic-formula', path, 'A formula must not contain cycles', 'Use plain JSON.');
+        }
+        seen.add(value);
+        containers += 1;
+        if (containers > FORMULA_LIMITS.nodes * 2)
+            return tooLarge(path);
+        if (Array.isArray(value)) {
+            if (value.length > FORMULA_LIMITS.nodes)
+                return tooLarge(path);
+            for (let i = value.length - 1; i >= 0; i -= 1) {
+                stack.push({ value: value[i], depth: current.depth, path: [...path, i] });
+            }
+            continue;
+        }
+        const prototype = Object.getPrototypeOf(value);
+        if (prototype !== Object.prototype && prototype !== null) {
+            return diagnostic('invalid-container', path, 'Formula nodes must be plain JSON objects', 'Use plain JSON.');
+        }
+        nodes += 1;
+        if (nodes > FORMULA_LIMITS.nodes)
+            return tooLarge(path);
+        const depth = current.depth + 1;
+        if (depth > FORMULA_LIMITS.depth) {
+            return diagnostic('formula-too-deep', path, `A formula nests at most ${FORMULA_LIMITS.depth} levels`, 'Flatten the calculation, for example with min/max over several operands.');
+        }
+        const keys = Object.keys(value);
+        if (keys.length > 8) {
+            return diagnostic('invalid-formula', path, 'A formula node has too many keys', 'Use only the keys of its op.');
+        }
+        for (const key of keys.reverse()) {
+            stack.push({ value: value[key], depth, path: [...path, key] });
+        }
+    }
+    return null;
+}
+function parseVarName(value, path) {
+    if (typeof value !== 'string' || !VARIABLE_NAME.test(value)) {
+        return {
+            ok: false,
+            diagnostic: diagnostic('invalid-formula', path, 'Use a lowerCamelCase name of at most 32 characters', 'Rename the variable.'),
+        };
+    }
+    if (RESERVED_VARIABLE_NAMES.has(value)) {
+        return {
+            ok: false,
+            diagnostic: diagnostic('invalid-formula', path, '"constructor" and "prototype" are reserved; choose another name', 'Rename the variable.'),
+        };
+    }
+    return { ok: true, name: value };
+}
+function parseNode(input, path, kind) {
+    if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+        return {
+            ok: false,
+            diagnostics: [
+                diagnostic('invalid-formula', path, 'Expected a formula node object', 'Use plain JSON.'),
+            ],
+        };
+    }
+    const record = input;
+    const op = record.op;
+    if (typeof op !== 'string') {
+        return {
+            ok: false,
+            diagnostics: [diagnostic('invalid-formula', [...path, 'op'], 'op is required', 'Set op.')],
+        };
+    }
+    const isNumberOp = NUMBER_OPS.includes(op);
+    const isConditionOp = CONDITION_OPS.includes(op);
+    if (kind === 'number' && isConditionOp) {
+        return {
+            ok: false,
+            diagnostics: [
+                diagnostic('type-mismatch', path, `Expected a number here, got the condition "${op}"`, 'Turn a condition into a number with { "op": "if", "test": …, "ifTrue": …, "ifFalse": … }.'),
+            ],
+        };
+    }
+    if (kind === 'condition' && isNumberOp) {
+        return {
+            ok: false,
+            diagnostics: [
+                diagnostic('type-mismatch', path, `Expected a condition here, got the number expression "${op}"`, 'Compare two numbers with lt, lte, gt, gte, eq or neq.'),
+            ],
+        };
+    }
+    if (!isNumberOp && !isConditionOp) {
+        return {
+            ok: false,
+            diagnostics: [
+                diagnostic('unknown-op', path, `Unknown formula op ${JSON.stringify(op)}`, `Use one of ${(kind === 'condition' ? CONDITION_OPS : NUMBER_OPS).join(', ')}.`),
+            ],
+        };
+    }
+    const child = (key, expected) => parseNode(record[key], [...path, key], expected);
+    switch (op) {
+        case 'num': {
+            if (typeof record.value !== 'number' || !Number.isFinite(record.value)) {
+                return {
+                    ok: false,
+                    diagnostics: [
+                        diagnostic('invalid-formula', [...path, 'value'], 'num.value must be a finite number', 'Use a finite literal.'),
+                    ],
+                };
+            }
+            if (Math.abs(record.value) > FORMULA_LIMITS.literal) {
+                return {
+                    ok: false,
+                    diagnostics: [
+                        diagnostic('invalid-formula', [...path, 'value'], `Literal magnitude is at most ${FORMULA_LIMITS.literal}`, 'Use a smaller number.'),
+                    ],
+                };
+            }
+            return { ok: true, node: { op: 'num', value: record.value } };
+        }
+        case 'var': {
+            const name = parseVarName(record.name, [...path, 'name']);
+            if (!name.ok)
+                return { ok: false, diagnostics: [name.diagnostic] };
+            return { ok: true, node: { op: 'var', name: name.name } };
+        }
+        case 'add':
+        case 'sub':
+        case 'mul':
+        case 'div': {
+            const left = child('left', 'number');
+            if (!left.ok)
+                return left;
+            const right = child('right', 'number');
+            if (!right.ok)
+                return right;
+            return {
+                ok: true,
+                node: {
+                    op,
+                    left: left.node,
+                    right: right.node,
+                },
+            };
+        }
+        case 'pow': {
+            const base = child('base', 'number');
+            if (!base.ok)
+                return base;
+            const exponent = child('exponent', 'number');
+            if (!exponent.ok)
+                return exponent;
+            return {
+                ok: true,
+                node: {
+                    op: 'pow',
+                    base: base.node,
+                    exponent: exponent.node,
+                },
+            };
+        }
+        case 'min':
+        case 'max': {
+            if (!Array.isArray(record.args) ||
+                record.args.length < 2 ||
+                record.args.length > FORMULA_LIMITS.args) {
+                return {
+                    ok: false,
+                    diagnostics: [
+                        diagnostic('invalid-formula', [...path, 'args'], `args must have 2–${FORMULA_LIMITS.args} number formulas`, 'Pass a short args array.'),
+                    ],
+                };
+            }
+            const args = [];
+            for (let i = 0; i < record.args.length; i += 1) {
+                const parsed = parseNode(record.args[i], [...path, 'args', i], 'number');
+                if (!parsed.ok)
+                    return parsed;
+                args.push(parsed.node);
+            }
+            return { ok: true, node: { op, args } };
+        }
+        case 'round': {
+            const value = child('value', 'number');
+            if (!value.ok)
+                return value;
+            let digits;
+            if (record.digits !== undefined) {
+                if (typeof record.digits !== 'number' ||
+                    !Number.isInteger(record.digits) ||
+                    Math.abs(record.digits) > FORMULA_LIMITS.roundDigits) {
+                    return {
+                        ok: false,
+                        diagnostics: [
+                            diagnostic('invalid-formula', [...path, 'digits'], `digits must be an integer from −${FORMULA_LIMITS.roundDigits} to ${FORMULA_LIMITS.roundDigits}`, 'Adjust digits.'),
+                        ],
+                    };
+                }
+                digits = record.digits;
+            }
+            return {
+                ok: true,
+                node: digits === undefined
+                    ? { op: 'round', value: value.node }
+                    : { op: 'round', value: value.node, digits },
+            };
+        }
+        case 'clamp': {
+            const value = child('value', 'number');
+            if (!value.ok)
+                return value;
+            const min = child('min', 'number');
+            if (!min.ok)
+                return min;
+            const max = child('max', 'number');
+            if (!max.ok)
+                return max;
+            return {
+                ok: true,
+                node: {
+                    op: 'clamp',
+                    value: value.node,
+                    min: min.node,
+                    max: max.node,
+                },
+            };
+        }
+        case 'if': {
+            const test = child('test', 'condition');
+            if (!test.ok)
+                return test;
+            const ifTrue = child('ifTrue', 'number');
+            if (!ifTrue.ok)
+                return ifTrue;
+            const ifFalse = child('ifFalse', 'number');
+            if (!ifFalse.ok)
+                return ifFalse;
+            return {
+                ok: true,
+                node: {
+                    op: 'if',
+                    test: test.node,
+                    ifTrue: ifTrue.node,
+                    ifFalse: ifFalse.node,
+                },
+            };
+        }
+        case 'lt':
+        case 'lte':
+        case 'gt':
+        case 'gte':
+        case 'eq':
+        case 'neq': {
+            const left = child('left', 'number');
+            if (!left.ok)
+                return left;
+            const right = child('right', 'number');
+            if (!right.ok)
+                return right;
+            return {
+                ok: true,
+                node: {
+                    op,
+                    left: left.node,
+                    right: right.node,
+                },
+            };
+        }
+        case 'and':
+        case 'or': {
+            if (!Array.isArray(record.args) ||
+                record.args.length < 2 ||
+                record.args.length > FORMULA_LIMITS.args) {
+                return {
+                    ok: false,
+                    diagnostics: [
+                        diagnostic('invalid-formula', [...path, 'args'], `args must have 2–${FORMULA_LIMITS.args} conditions`, 'Pass a short args array.'),
+                    ],
+                };
+            }
+            const args = [];
+            for (let i = 0; i < record.args.length; i += 1) {
+                const parsed = parseNode(record.args[i], [...path, 'args', i], 'condition');
+                if (!parsed.ok)
+                    return parsed;
+                args.push(parsed.node);
+            }
+            return { ok: true, node: { op, args } };
+        }
+        case 'not': {
+            const value = child('value', 'condition');
+            if (!value.ok)
+                return value;
+            return { ok: true, node: { op: 'not', value: value.node } };
+        }
+        default:
+            return {
+                ok: false,
+                diagnostics: [
+                    diagnostic('unknown-op', path, `Unknown formula op ${JSON.stringify(op)}`, 'Use a known op.'),
+                ],
+            };
+    }
+}
+/** Variable names a formula reads, sorted and unique. */
+export function formulaVariables(formula) {
+    const names = new Set();
+    const visit = (node) => {
+        switch (node.op) {
+            case 'num':
+                return;
+            case 'var':
+                names.add(node.name);
+                return;
+            case 'add':
+            case 'sub':
+            case 'mul':
+            case 'div':
+            case 'lt':
+            case 'lte':
+            case 'gt':
+            case 'gte':
+            case 'eq':
+            case 'neq':
+                visit(node.left);
+                visit(node.right);
+                return;
+            case 'pow':
+                visit(node.base);
+                visit(node.exponent);
+                return;
+            case 'min':
+            case 'max':
+            case 'and':
+            case 'or':
+                for (const arg of node.args)
+                    visit(arg);
+                return;
+            case 'round':
+            case 'not':
+                visit(node.value);
+                return;
+            case 'clamp':
+                visit(node.value);
+                visit(node.min);
+                visit(node.max);
+                return;
+            case 'if':
+                visit(node.test);
+                visit(node.ifTrue);
+                visit(node.ifFalse);
+        }
+    };
+    visit(formula);
+    return [...names].sort();
+}
+function variablePaths(node, path, out) {
+    if (node === null || typeof node !== 'object')
+        return;
+    if (Array.isArray(node)) {
+        node.forEach((child, i) => {
+            variablePaths(child, [...path, i], out);
+        });
+        return;
+    }
+    const record = node;
+    if (record.op === 'var' && typeof record.name === 'string') {
+        out.push({ name: record.name, path: [...path, 'name'] });
+        return;
+    }
+    for (const [key, child] of Object.entries(record))
+        variablePaths(child, [...path, key], out);
+}
+/** Validates untrusted formula JSON. Never throws and never executes anything. */
+export function parseFormula(input, options = {}) {
+    const failed = (diagnostics) => ({
+        success: false,
+        formula: null,
+        variables: [],
+        diagnostics,
+    });
+    const size = preflight(input);
+    if (size)
+        return failed([size]);
+    const parsed = parseNode(input, [], 'number');
+    if (!parsed.ok)
+        return failed(parsed.diagnostics);
+    const formula = parsed.node;
+    if (options.variables) {
+        const known = new Set(options.variables);
+        const found = [];
+        variablePaths(formula, [], found);
+        const unknown = found.filter((ref) => !known.has(ref.name));
+        if (unknown.length > 0) {
+            return failed(unknown.map((ref) => diagnostic('unknown-variable', ref.path, `Unknown variable "${ref.name}"`, known.size > 0
+                ? `Use one of the calculator inputs: ${[...known].sort().join(', ')}.`
+                : 'Add a calculator input with this name.')));
+        }
+    }
+    return {
+        success: true,
+        formula,
+        variables: formulaVariables(formula),
+        diagnostics: [],
+    };
+}

package/dist/core/formula/types.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The closed formula grammar for calculator blocks. A formula is plain JSON:
+ * every node names its operation in `op`, and there is no string syntax, no
+ * function call by name and no way to reach host objects. Numbers and
+ * conditions are separate node kinds.
+ */
+export type ArithmeticOp = 'add' | 'sub' | 'mul' | 'div';
+export type ComparisonOp = 'lt' | 'lte' | 'gt' | 'gte' | 'eq' | 'neq';
+/** An expression that evaluates to a number, or `null` when undefined. */
+export type NumberFormula = {
+    op: 'num';
+    value: number;
+} | {
+    op: 'var';
+    name: string;
+} | {
+    op: ArithmeticOp;
+    left: NumberFormula;
+    right: NumberFormula;
+} | {
+    op: 'pow';
+    base: NumberFormula;
+    exponent: NumberFormula;
+} | {
+    op: 'min' | 'max';
+    args: NumberFormula[];
+} | {
+    op: 'round';
+    value: NumberFormula;
+    digits?: number | undefined;
+} | {
+    op: 'clamp';
+    value: NumberFormula;
+    min: NumberFormula;
+    max: NumberFormula;
+} | {
+    op: 'if';
+    test: Condition;
+    ifTrue: NumberFormula;
+    ifFalse: NumberFormula;
+};
+/** An expression that evaluates to true, false, or `null` when an operand is undefined. */
+export type Condition = {
+    op: ComparisonOp;
+    left: NumberFormula;
+    right: NumberFormula;
+} | {
+    op: 'and' | 'or';
+    args: Condition[];
+} | {
+    op: 'not';
+    value: Condition;
+};
+/** Input values by variable name. Missing, `null` and non-finite inputs are undefined. */
+export type FormulaInputs = Readonly<Record<string, number | null | undefined>>;
+/** One problem with a formula, addressed like authoring diagnostics. */
+export interface FormulaDiagnostic {
+    code: string;
+    path: (string | number)[];
+    jsonPath: string;
+    message: string;
+    hint: string;
+}
+export type FormulaParseResult = {
+    success: true;
+    formula: NumberFormula;
+    variables: string[];
+    diagnostics: [];
+} | {
+    success: false;
+    formula: null;
+    variables: [];
+    diagnostics: FormulaDiagnostic[];
+};
+/** How a calculator output is shown. */
+export type FormulaUnit = 'number' | 'compact' | 'cents' | 'percent';

package/dist/core/formula/types.js

@@ -0,0 +1,7 @@
+/**
+ * The closed formula grammar for calculator blocks. A formula is plain JSON:
+ * every node names its operation in `op`, and there is no string syntax, no
+ * function call by name and no way to reach host objects. Numbers and
+ * conditions are separate node kinds.
+ */
+export {};

package/dist/core/index.d.ts

@@ -0,0 +1,14 @@
+/// <reference path="../css-modules.d.ts" />
+/**
+ * `@texuli/blocks` core — schemas, limits, untrusted-input guard, formula AST,
+ * text helpers and catalog metadata. Framework-free TypeScript (no Svelte).
+ */
+export { BLOCK_CATALOG, type BlockAuthoringDiagnostic, type BlockAuthoringValidation, type BlockCatalogEntry, getCatalogEntry, listCatalogTypes, parseBlocksForAuthoring, validateBlocksForAuthoring, } from './catalog/index.js';
+export { type Condition, evaluateCondition, evaluateFormula, FORMULA_LIMITS, type FormatFormulaOptions, type FormulaDiagnostic, type FormulaInputs, type FormulaParseResult, type FormulaUnit, formatFormulaValue, formulaJsonPath, formulaVariables, type NumberFormula, type ParseFormulaOptions, parseFormula, roundTo, } from './formula/index.js';
+export { BLOCK_LIMITS, type BlockLimits, } from './limits.js';
+export { base64DecodedBytes, classifyMediaSource, hasUnsafeText, isUnsafeTextCharacter, MEDIA_DATA_URI_MAX_BYTES, type MediaKind, type MediaSourceKind, normalizeLineSeparators, } from './safety.js';
+export { type AccordionBlock, BLOCK_TYPES, type Block, type BlockParseResult, type BlockType, type CalloutBlock, type CardsBlock, type ChartBlock, type ChartKind, type ChartSeries, type CodeBlock, type ColumnsBlock, type CtaBlock, type DataBlock, type DividerBlock, type FigureBlock, forEachBlock, type GalleryBlock, type GalleryItem, type GridBlock, type HeadingBlock, type ImageBlock, type ImageFit, type KpiBlock, type ListBlock, type ListItem, type QuoteBlock, type StatBlock, safeParseBlock, safeParseBlocks, type TableBlock, type TableCellValue, type TableColumn, type TableRow, type TabsBlock, type TextBlock, toJsonPath, type VideoBlock, } from './schema/blocks.js';
+export { BLOCK_CONTENT_LIMITS, type BlockBase, type FieldIssue, type ParseResult, parseBlockBase, parseBlockId, parseMultilineText, parsePlainText, } from './schema/primitives.js';
+export { BLOCK_FAMILIES, BLOCK_REVEALS, BLOCK_TONES, type BlockFamily, type BlockReveal, type BlockTone, isBlockFamily, isBlockReveal, isBlockTone, } from './schema/vocabulary.js';
+export { blockText, documentText, headingOutline, slugifyHeading, stripLightMarkdown, uniqueSlug, type WalkedBlock, walkBlocks, } from './text.js';
+export { parseUntrustedBlocks, type UntrustedBlockIssue, type UntrustedBlocksResult, } from './untrusted.js';

package/dist/core/index.js

@@ -0,0 +1,13 @@
+/**
+ * `@texuli/blocks` core — schemas, limits, untrusted-input guard, formula AST,
+ * text helpers and catalog metadata. Framework-free TypeScript (no Svelte).
+ */
+export { BLOCK_CATALOG, getCatalogEntry, listCatalogTypes, parseBlocksForAuthoring, validateBlocksForAuthoring, } from "./catalog/index.js";
+export { evaluateCondition, evaluateFormula, FORMULA_LIMITS, formatFormulaValue, formulaJsonPath, formulaVariables, parseFormula, roundTo, } from "./formula/index.js";
+export { BLOCK_LIMITS, } from "./limits.js";
+export { base64DecodedBytes, classifyMediaSource, hasUnsafeText, isUnsafeTextCharacter, MEDIA_DATA_URI_MAX_BYTES, normalizeLineSeparators, } from "./safety.js";
+export { BLOCK_TYPES, forEachBlock, safeParseBlock, safeParseBlocks, toJsonPath, } from "./schema/blocks.js";
+export { BLOCK_CONTENT_LIMITS, parseBlockBase, parseBlockId, parseMultilineText, parsePlainText, } from "./schema/primitives.js";
+export { BLOCK_FAMILIES, BLOCK_REVEALS, BLOCK_TONES, isBlockFamily, isBlockReveal, isBlockTone, } from "./schema/vocabulary.js";
+export { blockText, documentText, headingOutline, slugifyHeading, stripLightMarkdown, uniqueSlug, walkBlocks, } from "./text.js";
+export { parseUntrustedBlocks, } from "./untrusted.js";

package/dist/core/limits.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Hard upper bounds for block documents accepted from files, links or paste.
+ * Individual schemas impose smaller field caps; these are the outer guards.
+ */
+export declare const BLOCK_LIMITS: Readonly<{
+    /** Serialized UTF-8 JSON bytes, including embedded media data URIs. */
+    maxBytes: number;
+    /** JSON object/array nesting in one block document. */
+    maxDepth: 12;
+    maxBlocks: 2000;
+    maxContainerDepth: 3;
+    maxDataUriBytes: number;
+    maxDocumentDataUriBytes: number;
+    /** General guard ceiling; field schemas are tighter. */
+    maxTextLength: 20000;
+    maxTableCells: number;
+    /** Diagram model caps (flow / tree / board / terminal). */
+    flowNodes: 12;
+    treeNodes: 64;
+    treeDepth: 6;
+    boardColumns: 6;
+    boardCardsPerColumn: 8;
+    terminalLines: 40;
+}>;
+export type BlockLimits = {
+    [Key in keyof typeof BLOCK_LIMITS]: number;
+};

package/dist/core/limits.js

@@ -0,0 +1,26 @@
+import { MEDIA_DATA_URI_MAX_BYTES } from "./safety.js";
+import { BLOCK_CONTENT_LIMITS } from "./schema/primitives.js";
+/**
+ * Hard upper bounds for block documents accepted from files, links or paste.
+ * Individual schemas impose smaller field caps; these are the outer guards.
+ */
+export const BLOCK_LIMITS = Object.freeze({
+    /** Serialized UTF-8 JSON bytes, including embedded media data URIs. */
+    maxBytes: 1024 * 1024,
+    /** JSON object/array nesting in one block document. */
+    maxDepth: 12,
+    maxBlocks: 2_000,
+    maxContainerDepth: BLOCK_CONTENT_LIMITS.containerDepth,
+    maxDataUriBytes: MEDIA_DATA_URI_MAX_BYTES,
+    maxDocumentDataUriBytes: 512 * 1024,
+    /** General guard ceiling; field schemas are tighter. */
+    maxTextLength: BLOCK_CONTENT_LIMITS.code,
+    maxTableCells: BLOCK_CONTENT_LIMITS.tableColumns * BLOCK_CONTENT_LIMITS.tableRows,
+    /** Diagram model caps (flow / tree / board / terminal). */
+    flowNodes: 12,
+    treeNodes: 64,
+    treeDepth: 6,
+    boardColumns: 6,
+    boardCardsPerColumn: 8,
+    terminalLines: 40,
+});

package/dist/core/safety.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Dependency-light safety predicates shared by block schemas and the
+ * untrusted-input loader. No Svelte, no schema graph.
+ */
+/**
+ * Turns U+2028/U+2029 into a line break (multiline) or a space so loaders keep
+ * the word boundary before the schema refuses them.
+ */
+export declare function normalizeLineSeparators(value: string, keepNewlines: boolean): string;
+export declare function isUnsafeTextCharacter(character: string, allowNewlines?: boolean, allowTabs?: boolean): boolean;
+/** True when any code point in `value` is unsafe under the given rules. */
+export declare function hasUnsafeText(value: string, allowNewlines?: boolean, allowTabs?: boolean): boolean;
+/** Decoded bytes allowed in one `data:` source. */
+export declare const MEDIA_DATA_URI_MAX_BYTES: number;
+export type MediaKind = 'image' | 'video';
+export type MediaSourceKind = 'avatar' | 'data' | 'relative';
+/** Decoded size of a base64 payload. */
+export declare function base64DecodedBytes(payload: string): number;
+/**
+ * Classifies a media source, or explains why it is refused. Hosts use the kind
+ * to apply level rules and per-document byte caps. No remote URLs.
+ */
+export declare function classifyMediaSource(src: string, media: MediaKind): {
+    ok: true;
+    kind: MediaSourceKind;
+    bytes: number;
+} | {
+    ok: false;
+    message: string;
+};