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

package/dist/core/safety.js

@@ -0,0 +1,110 @@
+/**
+ * Dependency-light safety predicates shared by block schemas and the
+ * untrusted-input loader. No Svelte, no schema graph.
+ */
+// C0/C1 controls, bidi marks/embeddings/overrides/isolates ("Trojan Source"),
+// BOMs, invisible zero-width space and word joiner, Unicode line/paragraph
+// separators. ZWJ/ZWNJ stay for emoji and some scripts.
+const UNSAFE_TEXT_CODE_POINT_RANGES = [
+    [0x00, 0x1f],
+    [0x7f, 0x9f],
+    [0x061c, 0x061c],
+    [0x200b, 0x200b],
+    [0x200e, 0x200f],
+    [0x2028, 0x2029],
+    [0x202a, 0x202e],
+    [0x2060, 0x2060],
+    [0x2066, 0x2069],
+    [0xfeff, 0xfeff],
+];
+/**
+ * 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 function normalizeLineSeparators(value, keepNewlines) {
+    return value.replace(/[\u2028\u2029]/g, keepNewlines ? '\n' : ' ');
+}
+export function isUnsafeTextCharacter(character, allowNewlines = false, allowTabs = false) {
+    const code = character.codePointAt(0) ?? 0;
+    if (code === 0x0a && allowNewlines)
+        return false;
+    if (code === 0x0d && allowNewlines)
+        return false;
+    if (code === 0x09 && allowTabs)
+        return false;
+    return UNSAFE_TEXT_CODE_POINT_RANGES.some(([start, end]) => code >= start && code <= end);
+}
+/** True when any code point in `value` is unsafe under the given rules. */
+export function hasUnsafeText(value, allowNewlines = false, allowTabs = false) {
+    return [...value].some((character) => isUnsafeTextCharacter(character, allowNewlines, allowTabs));
+}
+/** Decoded bytes allowed in one `data:` source. */
+export const MEDIA_DATA_URI_MAX_BYTES = 192 * 1024;
+const RELATIVE_MAX_LENGTH = 512;
+const DATA_URI_MAX_LENGTH = Math.ceil(MEDIA_DATA_URI_MAX_BYTES / 3) * 4 + 64;
+const DATA_TYPES = {
+    image: ['image/png', 'image/jpeg', 'image/webp', 'image/gif'],
+    video: ['video/mp4', 'video/webm'],
+};
+const EXTENSIONS = {
+    image: /\.(?:png|jpe?g|webp|gif|avif)$/i,
+    video: /\.(?:mp4|webm)$/i,
+};
+const RELATIVE = /^(?:\.\/)?(?:[A-Za-z0-9_][A-Za-z0-9._-]*\/)*[A-Za-z0-9_][A-Za-z0-9._-]*$/;
+const DATA_URI = /^data:([a-z]+\/[a-z0-9.+-]+);base64,([A-Za-z0-9+/]*={0,2})$/;
+/** Fictional portrait ids (av-001 … av-175), same shape as the planned avatars pack. */
+const AVATAR_ID = /^av-(?:0[0-9]{2}|1[0-6][0-9]|17[0-5])$/;
+/** Decoded size of a base64 payload. */
+export function base64DecodedBytes(payload) {
+    const padding = payload.endsWith('==') ? 2 : payload.endsWith('=') ? 1 : 0;
+    return Math.floor((payload.length * 3) / 4) - padding;
+}
+/**
+ * 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 function classifyMediaSource(src, media) {
+    if (src.startsWith('avatar:')) {
+        if (media !== 'image')
+            return { ok: false, message: 'Avatars are images, not videos' };
+        return AVATAR_ID.test(src.slice('avatar:'.length))
+            ? { ok: true, kind: 'avatar', bytes: 0 }
+            : { ok: false, message: 'Use an avatar id from av-001 to av-175, as avatar:av-007' };
+    }
+    if (src.startsWith('data:')) {
+        if (src.length > DATA_URI_MAX_LENGTH) {
+            return {
+                ok: false,
+                message: `Embedded media must be at most ${MEDIA_DATA_URI_MAX_BYTES / 1024} KB`,
+            };
+        }
+        const match = DATA_URI.exec(src);
+        if (!match)
+            return { ok: false, message: 'Use a base64 data URI, as data:image/png;base64,…' };
+        const type = match[1] ?? '';
+        const payload = match[2] ?? '';
+        if (!DATA_TYPES[media].includes(type)) {
+            return { ok: false, message: `Embedded ${media}s must be ${DATA_TYPES[media].join(', ')}` };
+        }
+        if (payload.length === 0 || payload.length % 4 !== 0) {
+            return { ok: false, message: 'The base64 payload is empty or malformed' };
+        }
+        const bytes = base64DecodedBytes(payload);
+        if (bytes > MEDIA_DATA_URI_MAX_BYTES) {
+            return {
+                ok: false,
+                message: `Embedded media must be at most ${MEDIA_DATA_URI_MAX_BYTES / 1024} KB`,
+            };
+        }
+        return { ok: true, kind: 'data', bytes };
+    }
+    if (src.length <= RELATIVE_MAX_LENGTH && RELATIVE.test(src) && EXTENSIONS[media].test(src)) {
+        return { ok: true, kind: 'relative', bytes: 0 };
+    }
+    return {
+        ok: false,
+        message: media === 'image'
+            ? 'Use avatar:av-001…175, a png/jpeg/webp/gif data URI, or a relative image path (no SVG or remote URLs)'
+            : 'Use an mp4/webm data URI or a relative video path (no remote URLs)',
+    };
+}

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

@@ -0,0 +1,138 @@
+import { type ChartBlock, type KpiBlock, type StatBlock, type TableBlock } from '../../data/schema.js';
+import { type CalculatorBlock, type ChecklistBlock, type PollBlock, type QuizBlock } from '../../interactive/schema.js';
+import { type AccordionBlock, type CardsBlock, type GridBlock, type TabsBlock } from '../../structure/schema.js';
+import { type BlockBase, type ParseResult, toJsonPath } from './primitives.js';
+/**
+ * Closed core vocabulary for the untrusted guard and catalog (T-blocks-core).
+ * Family-specific blocks (charts, diagrams, interactive) land in later tasks.
+ */
+export type HeadingBlock = BlockBase & {
+    type: 'heading';
+    level: 1 | 2 | 3 | 4;
+    text: string;
+    eyebrow?: string;
+    subtitle?: string;
+};
+export type TextBlock = BlockBase & {
+    type: 'text';
+    markdown: string;
+};
+export type ListItem = {
+    text: string;
+};
+export type ListBlock = BlockBase & {
+    type: 'list';
+    ordered?: boolean;
+    items: ListItem[];
+};
+export type QuoteBlock = BlockBase & {
+    type: 'quote';
+    quote: string;
+    cite?: string;
+};
+export type CalloutBlock = BlockBase & {
+    type: 'callout';
+    title?: string;
+    body: string;
+};
+export type DividerBlock = BlockBase & {
+    type: 'divider';
+};
+export type CodeBlock = BlockBase & {
+    type: 'code';
+    lang?: string;
+    code: string;
+    filename?: string;
+    /** Plain text shown under the code. */
+    caption?: string;
+    /** Show line numbers (drawn by the renderer, never part of the code text). */
+    lineNumbers?: boolean;
+    /**
+     * Stepped line highlights, one line spec per step (`["1-2", "4,6-8"]`).
+     * In a deck, the block's `step` is where they start: deck step `step + i`
+     * shows `highlights[i]`. Elsewhere the first step shows.
+     */
+    highlights?: string[];
+};
+export type CtaAction = {
+    label: string;
+    href: string;
+};
+export type CtaBlock = BlockBase & {
+    type: 'cta';
+    actions: CtaAction[];
+};
+export type ColumnsBlock = BlockBase & {
+    type: 'columns';
+    columns: Block[][];
+};
+export type ImageFit = 'contain' | 'cover';
+/** Single image (optional caption). */
+export type ImageBlock = BlockBase & {
+    type: 'image';
+    src: string;
+    /** Required unless decorative. */
+    alt?: string;
+    decorative?: boolean;
+    width: number;
+    height: number;
+    caption?: string;
+    credit?: string;
+    fit?: ImageFit;
+};
+/** Figure with a required caption (and optional credit). */
+export type FigureBlock = BlockBase & {
+    type: 'figure';
+    src: string;
+    alt?: string;
+    decorative?: boolean;
+    width: number;
+    height: number;
+    caption: string;
+    credit?: string;
+    fit?: ImageFit;
+};
+export type VideoBlock = BlockBase & {
+    type: 'video';
+    src: string;
+    /** Accessible name of the video. */
+    label: string;
+    poster?: string;
+    width: number;
+    height: number;
+    caption?: string;
+    autoplay?: boolean;
+    loop?: boolean;
+    muted?: boolean;
+    controls?: boolean;
+};
+export type GalleryItem = {
+    src: string;
+    alt?: string;
+    decorative?: boolean;
+    width: number;
+    height: number;
+    caption?: string;
+};
+export type GalleryBlock = BlockBase & {
+    type: 'gallery';
+    title?: string;
+    /** Preferred column count on wide viewports (2–4). */
+    columns?: 2 | 3 | 4;
+    items: GalleryItem[];
+};
+export type Block = HeadingBlock | TextBlock | ListBlock | QuoteBlock | CalloutBlock | DividerBlock | CodeBlock | CtaBlock | ColumnsBlock | TabsBlock | AccordionBlock | CardsBlock | GridBlock | ImageBlock | FigureBlock | VideoBlock | GalleryBlock | TableBlock | StatBlock | KpiBlock | ChartBlock | PollBlock | QuizBlock | CalculatorBlock | ChecklistBlock;
+export type BlockType = Block['type'];
+export declare const BLOCK_TYPES: readonly ["heading", "text", "list", "quote", "callout", "divider", "code", "cta", "columns", "tabs", "accordion", "cards", "grid", "image", "figure", "video", "gallery", "table", "stat", "kpi", "chart", "poll", "quiz", "calculator", "checklist"];
+export type { AccordionBlock, CardsBlock, GridBlock, TabsBlock };
+export type BlockParseResult<T> = ParseResult<T>;
+export declare function parseBlockList(value: unknown, path?: (string | number)[], containerDepth?: number): ParseResult<Block[]>;
+export declare function safeParseBlocks(value: unknown): BlockParseResult<Block[]>;
+export declare function safeParseBlock(value: unknown): BlockParseResult<Block>;
+/**
+ * Depth-first walk of every block, including nested columns.
+ * Callback receives the block and its path from the root list.
+ */
+export declare function forEachBlock(blocks: readonly Block[], visit: (block: Block, path: readonly (string | number)[]) => void, path?: readonly (string | number)[]): void;
+export type { ChartBlock, ChartKind, ChartSeries, DataBlock, KpiBlock, StatBlock, TableBlock, TableCellValue, TableColumn, TableRow, } from '../../data/schema.js';
+export { toJsonPath };

package/dist/core/schema/blocks.js

@@ -0,0 +1,181 @@
+import { safeHref } from '@texuli/core/url-policy';
+import { parseDataBlock, } from "../../data/schema.js";
+import { parseInteractiveBlock, } from "../../interactive/schema.js";
+import { parseStructureBlock, } from "../../structure/schema.js";
+import { parseCodeFamilyBlock } from "./code-family.js";
+import { parseMediaFamilyBlock } from "./media-family.js";
+import { plainObject } from "./parse-family.js";
+import { BLOCK_CONTENT_LIMITS, fail, failMany, ok, parseBlockBase, parsePlainText, toJsonPath, } from "./primitives.js";
+import { parseTextFamilyBlock } from "./text-family.js";
+export const BLOCK_TYPES = [
+    'heading',
+    'text',
+    'list',
+    'quote',
+    'callout',
+    'divider',
+    'code',
+    'cta',
+    'columns',
+    'tabs',
+    'accordion',
+    'cards',
+    'grid',
+    'image',
+    'figure',
+    'video',
+    'gallery',
+    'table',
+    'stat',
+    'kpi',
+    'chart',
+    'poll',
+    'quiz',
+    'calculator',
+    'checklist',
+];
+function parseCta(record, path, base) {
+    if (!Array.isArray(record.actions) || record.actions.length === 0) {
+        return fail([...path, 'actions'], 'cta needs at least one action');
+    }
+    if (record.actions.length > BLOCK_CONTENT_LIMITS.ctaActions) {
+        return fail([...path, 'actions'], `cta may have at most ${BLOCK_CONTENT_LIMITS.ctaActions} actions`);
+    }
+    const actions = [];
+    for (let i = 0; i < record.actions.length; i += 1) {
+        const actionPath = [...path, 'actions', i];
+        const action = plainObject(record.actions[i], actionPath);
+        if (!action.success)
+            return action;
+        const label = parsePlainText(action.data.label, [...actionPath, 'label'], BLOCK_CONTENT_LIMITS.plain);
+        if (!label.success)
+            return label;
+        if (typeof action.data.href !== 'string') {
+            return fail([...actionPath, 'href'], 'href must be a string');
+        }
+        if (action.data.href.length > BLOCK_CONTENT_LIMITS.href) {
+            return fail([...actionPath, 'href'], `href must be at most ${BLOCK_CONTENT_LIMITS.href} characters`);
+        }
+        const href = safeHref(action.data.href, 'untrusted');
+        if (!href) {
+            return fail([...actionPath, 'href'], 'href must be an https, mailto or same-document link (untrusted tier)');
+        }
+        actions.push({ label: label.data, href });
+    }
+    return ok({ ...base, type: 'cta', actions });
+}
+function parseColumns(record, path, base, containerDepth) {
+    if (containerDepth >= BLOCK_CONTENT_LIMITS.containerDepth) {
+        return fail(path, `containers nest at most ${BLOCK_CONTENT_LIMITS.containerDepth} deep`);
+    }
+    if (!Array.isArray(record.columns) || record.columns.length < 2) {
+        return fail([...path, 'columns'], 'columns needs at least two columns');
+    }
+    if (record.columns.length > BLOCK_CONTENT_LIMITS.columns) {
+        return fail([...path, 'columns'], `at most ${BLOCK_CONTENT_LIMITS.columns} columns`);
+    }
+    const columns = [];
+    for (let c = 0; c < record.columns.length; c += 1) {
+        const column = record.columns[c];
+        if (!Array.isArray(column)) {
+            return fail([...path, 'columns', c], 'each column must be a block array');
+        }
+        if (column.length > BLOCK_CONTENT_LIMITS.blocksPerColumn) {
+            return fail([...path, 'columns', c], `at most ${BLOCK_CONTENT_LIMITS.blocksPerColumn} blocks per column`);
+        }
+        const parsed = parseBlockList(column, [...path, 'columns', c], containerDepth + 1);
+        if (!parsed.success)
+            return parsed;
+        columns.push(parsed.data);
+    }
+    return ok({ ...base, type: 'columns', columns });
+}
+function parseOneBlock(value, path, containerDepth) {
+    const object = plainObject(value, path);
+    if (!object.success)
+        return object;
+    const record = object.data;
+    if (typeof record.type !== 'string')
+        return fail([...path, 'type'], 'block type is required');
+    const base = parseBlockBase(record, path);
+    if (!base.success)
+        return base;
+    switch (record.type) {
+        case 'divider':
+            return ok({ ...base.data, type: 'divider' });
+        case 'cta':
+            return parseCta(record, path, base.data);
+        case 'columns':
+            return parseColumns(record, path, base.data, containerDepth);
+        default: {
+            const family = parseTextFamilyBlock(record.type, record, path, base.data) ??
+                parseCodeFamilyBlock(record.type, record, path, base.data) ??
+                parseMediaFamilyBlock(record.type, record, path, base.data);
+            if (family)
+                return family;
+            const structure = parseStructureBlock(record.type, record, path, base.data, containerDepth, parseBlockList);
+            if (structure)
+                return structure;
+            const data = parseDataBlock(record.type, record, path, base.data);
+            if (data)
+                return data;
+            const interactive = parseInteractiveBlock(record.type, record, path, base.data);
+            if (interactive)
+                return interactive;
+            return fail([...path, 'type'], `Unknown block type "${record.type}"`);
+        }
+    }
+}
+export function parseBlockList(value, path = [], containerDepth = 0) {
+    if (!Array.isArray(value))
+        return fail(path, 'Expected a block array');
+    const blocks = [];
+    const issues = [];
+    for (let i = 0; i < value.length; i += 1) {
+        const parsed = parseOneBlock(value[i], [...path, i], containerDepth);
+        if (!parsed.success) {
+            issues.push(...parsed.issues);
+            continue;
+        }
+        blocks.push(parsed.data);
+    }
+    if (issues.length > 0)
+        return failMany(issues);
+    return ok(blocks);
+}
+export function safeParseBlocks(value) {
+    return parseBlockList(value, []);
+}
+export function safeParseBlock(value) {
+    return parseOneBlock(value, [], 0);
+}
+/**
+ * Depth-first walk of every block, including nested columns.
+ * Callback receives the block and its path from the root list.
+ */
+export function forEachBlock(blocks, visit, path = []) {
+    for (let i = 0; i < blocks.length; i += 1) {
+        const block = blocks[i];
+        if (!block)
+            continue;
+        const blockPath = [...path, i];
+        visit(block, blockPath);
+        if (block.type === 'columns') {
+            for (let c = 0; c < block.columns.length; c += 1) {
+                const column = block.columns[c];
+                if (!column)
+                    continue;
+                forEachBlock(column, visit, [...blockPath, 'columns', c]);
+            }
+        }
+        else if (block.type === 'tabs') {
+            for (let p = 0; p < block.panels.length; p += 1) {
+                const panel = block.panels[p];
+                if (!panel)
+                    continue;
+                forEachBlock(panel.blocks, visit, [...blockPath, 'panels', p, 'blocks']);
+            }
+        }
+    }
+}
+export { toJsonPath };

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

@@ -0,0 +1,4 @@
+import type { CodeBlock } from './blocks.js';
+import { type BlockBase, type ParseResult } from './primitives.js';
+/** Code family: code blocks. */
+export declare function parseCodeFamilyBlock(type: string, record: Record<string, unknown>, path: (string | number)[], base: BlockBase): ParseResult<CodeBlock> | null;

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

@@ -0,0 +1,75 @@
+import { parseLineSpec } from "./line-spec.js";
+import { BLOCK_CONTENT_LIMITS, fail, ok, parseMultilineText, parsePlainText, } from "./primitives.js";
+function parseCode(record, path, base) {
+    const code = parseMultilineText(record.code, [...path, 'code'], BLOCK_CONTENT_LIMITS.code, true);
+    if (!code.success)
+        return code;
+    const lines = code.data.split('\n').length;
+    if (lines > BLOCK_CONTENT_LIMITS.codeLines) {
+        return fail([...path, 'code'], `code may have at most ${BLOCK_CONTENT_LIMITS.codeLines} lines`);
+    }
+    let lang;
+    if (record.lang !== undefined) {
+        if (typeof record.lang !== 'string' || !/^[a-z][a-z0-9+-]{0,31}$/.test(record.lang)) {
+            return fail([...path, 'lang'], 'lang must be a short lowercase token');
+        }
+        lang = record.lang;
+    }
+    let filename;
+    if (record.filename !== undefined) {
+        const parsed = parsePlainText(record.filename, [...path, 'filename'], BLOCK_CONTENT_LIMITS.plain);
+        if (!parsed.success)
+            return parsed;
+        filename = parsed.data;
+    }
+    let caption;
+    if (record.caption !== undefined) {
+        const parsed = parsePlainText(record.caption, [...path, 'caption'], BLOCK_CONTENT_LIMITS.codeCaption);
+        if (!parsed.success)
+            return parsed;
+        caption = parsed.data;
+    }
+    if (record.lineNumbers !== undefined && typeof record.lineNumbers !== 'boolean') {
+        return fail([...path, 'lineNumbers'], 'lineNumbers must be a boolean');
+    }
+    const highlights = parseCodeHighlights(record.highlights, [...path, 'highlights'], lines);
+    if (!highlights.success)
+        return highlights;
+    return ok({
+        ...base,
+        type: 'code',
+        code: code.data,
+        ...(lang !== undefined ? { lang } : {}),
+        ...(filename !== undefined ? { filename } : {}),
+        ...(caption !== undefined ? { caption } : {}),
+        ...(record.lineNumbers !== undefined ? { lineNumbers: record.lineNumbers } : {}),
+        ...(highlights.data !== undefined ? { highlights: highlights.data } : {}),
+    });
+}
+/** 1 to 16 line specs (`"1-2,4"`), each within the code's lines. */
+function parseCodeHighlights(value, path, lines) {
+    if (value === undefined)
+        return ok(undefined);
+    const max = BLOCK_CONTENT_LIMITS.codeHighlightSteps;
+    if (!Array.isArray(value) || value.length === 0 || value.length > max) {
+        return fail(path, `highlights must list 1 to ${max} line specs`);
+    }
+    for (const [index, spec] of value.entries()) {
+        const ranges = typeof spec === 'string' && spec.length <= BLOCK_CONTENT_LIMITS.codeHighlightSpec
+            ? parseLineSpec(spec)
+            : null;
+        if (!ranges || ranges.some(([, end]) => end > lines)) {
+            return fail([...path, index], `Use line specs like "1-2,4" within the ${lines} lines`);
+        }
+    }
+    return ok([...value]);
+}
+/** Code family: code blocks. */
+export function parseCodeFamilyBlock(type, record, path, base) {
+    switch (type) {
+        case 'code':
+            return parseCode(record, path, base);
+        default:
+            return null;
+    }
+}

package/dist/core/schema/line-spec.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Line specs for code highlights: `"1-2,4"` names lines 1, 2 and 4 (1-based).
+ * Shared by the code block schema and the code renderer, so data that
+ * validates always highlights the same lines.
+ */
+/** Parses `"1-2,4"` into `[[1, 2], [4, 4]]`, or `null` when malformed or reversed. */
+export declare function parseLineSpec(spec: string): [number, number][] | null;

package/dist/core/schema/line-spec.js

@@ -0,0 +1,19 @@
+/**
+ * Line specs for code highlights: `"1-2,4"` names lines 1, 2 and 4 (1-based).
+ * Shared by the code block schema and the code renderer, so data that
+ * validates always highlights the same lines.
+ */
+const LINE_SPEC = /^\d{1,4}(?:-\d{1,4})?(?:,\d{1,4}(?:-\d{1,4})?)*$/;
+/** Parses `"1-2,4"` into `[[1, 2], [4, 4]]`, or `null` when malformed or reversed. */
+export function parseLineSpec(spec) {
+    if (!LINE_SPEC.test(spec))
+        return null;
+    const ranges = [];
+    for (const part of spec.split(',')) {
+        const [a, b = a] = part.split('-').map(Number);
+        if (a < 1 || b < a)
+            return null;
+        ranges.push([a, b]);
+    }
+    return ranges;
+}

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

@@ -0,0 +1,4 @@
+import type { FigureBlock, GalleryBlock, ImageBlock, VideoBlock } from './blocks.js';
+import { type BlockBase, type ParseResult } from './primitives.js';
+/** Media family: image, figure, video and gallery. */
+export declare function parseMediaFamilyBlock(type: string, record: Record<string, unknown>, path: (string | number)[], base: BlockBase): ParseResult<ImageBlock | FigureBlock | VideoBlock | GalleryBlock> | null;