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

package/dist/diagram/layout.js

@@ -0,0 +1,165 @@
+const FLOW_NODE_WIDTH = 160;
+const FLOW_NODE_HEIGHT = 64;
+const FLOW_GAP = 48;
+const TREE_NODE_WIDTH = 176;
+const TREE_NODE_HEIGHT = 56;
+const TREE_X_GAP = 48;
+const TREE_Y_GAP = 40;
+const BOARD_COLUMN_WIDTH = 224;
+const BOARD_CARD_WIDTH = 200;
+const BOARD_CARD_HEIGHT = 64;
+const BOARD_ROW_GAP = 16;
+export function layoutFlow(diagram) {
+    const positions = diagram.nodes.map((node, index) => ({
+        id: node.id,
+        x: index * (FLOW_NODE_WIDTH + FLOW_GAP),
+        y: 0,
+        width: FLOW_NODE_WIDTH,
+        height: FLOW_NODE_HEIGHT,
+        label: node.label,
+        ...(node.tone === undefined ? {} : { tone: node.tone }),
+    }));
+    const edges = diagram.nodes.slice(1).map((node, index) => ({
+        from: diagram.nodes[index]?.id ?? '',
+        to: node.id,
+        kind: 'flow',
+    }));
+    if (diagram.loopBack && diagram.nodes.length > 1) {
+        edges.push({
+            from: diagram.nodes.at(-1)?.id ?? '',
+            to: diagram.nodes[0]?.id ?? '',
+            kind: 'loop-back',
+        });
+    }
+    return {
+        width: diagram.nodes.length * FLOW_NODE_WIDTH + (diagram.nodes.length - 1) * FLOW_GAP,
+        height: FLOW_NODE_HEIGHT + (diagram.loopBack ? 40 : 0),
+        positions,
+        edges,
+    };
+}
+export function layoutTree(diagram) {
+    const byId = new Map(diagram.nodes.map((node) => [node.id, node]));
+    const children = new Map();
+    for (const node of diagram.nodes) {
+        const list = children.get(node.parentId) ?? [];
+        list.push(node.id);
+        children.set(node.parentId, list);
+    }
+    const roots = children.get(null) ?? [];
+    const positions = new Map();
+    const edges = [];
+    if (diagram.style === 'file-tree') {
+        let row = 0;
+        const walk = (id, depth) => {
+            const node = byId.get(id);
+            if (!node)
+                return;
+            positions.set(id, {
+                id,
+                x: depth * (TREE_NODE_WIDTH / 2),
+                y: row * (TREE_NODE_HEIGHT + TREE_Y_GAP),
+                width: TREE_NODE_WIDTH,
+                height: TREE_NODE_HEIGHT,
+                label: node.label,
+                ...(node.tone === undefined ? {} : { tone: node.tone }),
+            });
+            row += 1;
+            for (const childId of children.get(id) ?? []) {
+                edges.push({ from: id, to: childId, kind: 'parent' });
+                walk(childId, depth + 1);
+            }
+        };
+        for (const root of roots)
+            walk(root, 0);
+        const width = Math.max(TREE_NODE_WIDTH, ...[...positions.values()].map((position) => position.x + position.width));
+        const height = Math.max(TREE_NODE_HEIGHT, positions.size * (TREE_NODE_HEIGHT + TREE_Y_GAP) - TREE_Y_GAP);
+        return { width, height, positions: [...positions.values()], edges };
+    }
+    let leaf = 0;
+    let maxDepth = 0;
+    const place = (id, depth) => {
+        const node = byId.get(id);
+        if (!node)
+            return 0;
+        maxDepth = Math.max(maxDepth, depth);
+        const childIds = children.get(id) ?? [];
+        let x;
+        if (childIds.length === 0) {
+            x = leaf * (TREE_NODE_WIDTH + TREE_X_GAP);
+            leaf += 1;
+        }
+        else {
+            const childXs = childIds.map((childId) => {
+                edges.push({ from: id, to: childId, kind: 'parent' });
+                return place(childId, depth + 1);
+            });
+            x = ((childXs[0] ?? 0) + (childXs.at(-1) ?? 0)) / 2;
+        }
+        positions.set(id, {
+            id,
+            x,
+            y: depth * (TREE_NODE_HEIGHT + TREE_Y_GAP),
+            width: TREE_NODE_WIDTH,
+            height: TREE_NODE_HEIGHT,
+            label: node.label,
+            ...(node.tone === undefined ? {} : { tone: node.tone }),
+        });
+        return x;
+    };
+    for (const root of roots)
+        place(root, 0);
+    const values = [...positions.values()];
+    // Each leaf receives a stable top-left slot; parents center between their
+    // first and last child slots.
+    const width = Math.max(TREE_NODE_WIDTH, leaf * (TREE_NODE_WIDTH + TREE_X_GAP) - TREE_X_GAP);
+    const height = (maxDepth + 1) * (TREE_NODE_HEIGHT + TREE_Y_GAP) - TREE_Y_GAP;
+    return { width, height, positions: values, edges };
+}
+export function layoutBoard(diagram) {
+    const positions = [];
+    const edges = [];
+    diagram.columns.forEach((column, columnIndex) => {
+        const x = columnIndex * BOARD_COLUMN_WIDTH;
+        positions.push({
+            id: column.id,
+            x,
+            y: 0,
+            width: BOARD_CARD_WIDTH,
+            height: BOARD_CARD_HEIGHT,
+            label: column.title,
+        });
+        column.cards.forEach((card, cardIndex) => {
+            positions.push({
+                id: card.id,
+                x,
+                y: (cardIndex + 1) * (BOARD_CARD_HEIGHT + BOARD_ROW_GAP),
+                width: BOARD_CARD_WIDTH,
+                height: BOARD_CARD_HEIGHT,
+                label: card.title,
+                ...(card.tone === undefined ? {} : { tone: card.tone }),
+            });
+            edges.push({ from: column.id, to: card.id, kind: 'parent' });
+        });
+    });
+    const maxCards = Math.max(0, ...diagram.columns.map((column) => column.cards.length));
+    return {
+        width: diagram.columns.length * BOARD_COLUMN_WIDTH - (BOARD_COLUMN_WIDTH - BOARD_CARD_WIDTH),
+        height: (maxCards + 1) * (BOARD_CARD_HEIGHT + BOARD_ROW_GAP) - BOARD_ROW_GAP,
+        positions,
+        edges,
+    };
+}
+export function layoutTerminal(diagram) {
+    const lineHeight = 28;
+    const positions = diagram.lines.map((line, index) => ({
+        id: `line-${index + 1}`,
+        x: 0,
+        y: index * lineHeight,
+        width: 720,
+        height: lineHeight,
+        label: line.text,
+        kind: line.kind,
+    }));
+    return { width: 720, height: diagram.lines.length * lineHeight, positions, edges: [] };
+}

package/dist/diagram/schema.d.ts

@@ -0,0 +1,74 @@
+/**
+ * Bounded diagram models (flow, tree/org, board, terminal). Untrusted input
+ * is parsed without throwing; diagnostics use blueprint-style JSON paths.
+ * No third-party schema library.
+ */
+import type { BlockBase } from '../core/schema/primitives.js';
+import type { BlockTone } from '../core/schema/vocabulary.js';
+export declare const DIAGRAM_LIMITS: Readonly<{
+    flowNodes: 12;
+    treeNodes: 64;
+    treeDepth: 6;
+    boardColumns: 6;
+    boardCardsPerColumn: 8;
+    terminalLines: 40;
+}>;
+export type FlowNode = {
+    id: string;
+    label: string;
+    tone?: BlockTone;
+};
+export type FlowDiagram = BlockBase & {
+    type: 'flow';
+    nodes: FlowNode[];
+    loopBack?: boolean;
+};
+export type TreeNode = {
+    id: string;
+    parentId: string | null;
+    label: string;
+    tone?: BlockTone;
+};
+export type TreeDiagram = BlockBase & {
+    type: 'tree';
+    style: 'file-tree' | 'org';
+    nodes: TreeNode[];
+};
+export type BoardCard = {
+    id: string;
+    title: string;
+    tone?: BlockTone;
+};
+export type BoardColumn = {
+    id: string;
+    title: string;
+    cards: BoardCard[];
+};
+export type BoardDiagram = BlockBase & {
+    type: 'board';
+    columns: BoardColumn[];
+};
+export type TerminalLine = {
+    kind: 'prompt' | 'output' | 'comment';
+    text: string;
+};
+export type TerminalDiagram = BlockBase & {
+    type: 'terminal';
+    lines: TerminalLine[];
+};
+export type Diagram = FlowDiagram | TreeDiagram | BoardDiagram | TerminalDiagram;
+export type DiagramType = Diagram['type'];
+export declare const DIAGRAM_BLOCK_TYPES: readonly ["flow", "tree", "board", "terminal"];
+export type DiagramParseResult = {
+    success: true;
+    data: Diagram;
+} | {
+    success: false;
+    issues: {
+        jsonPath: string;
+        message: string;
+    }[];
+};
+export declare function diagramJsonPath(path: readonly (string | number)[]): string;
+/** Parse an untrusted diagram without throwing. */
+export declare function parseDiagram(input: unknown): DiagramParseResult;

package/dist/diagram/schema.js

@@ -0,0 +1,358 @@
+/**
+ * Bounded diagram models (flow, tree/org, board, terminal). Untrusted input
+ * is parsed without throwing; diagnostics use blueprint-style JSON paths.
+ * No third-party schema library.
+ */
+import { BLOCK_LIMITS } from "../core/limits.js";
+import { fail, failMany, ok, parseBlockBase, parsePlainText, parseTone, toJsonPath, } from "../core/schema/primitives.js";
+export const DIAGRAM_LIMITS = Object.freeze({
+    flowNodes: BLOCK_LIMITS.flowNodes,
+    treeNodes: BLOCK_LIMITS.treeNodes,
+    treeDepth: BLOCK_LIMITS.treeDepth,
+    boardColumns: BLOCK_LIMITS.boardColumns,
+    boardCardsPerColumn: BLOCK_LIMITS.boardCardsPerColumn,
+    terminalLines: BLOCK_LIMITS.terminalLines,
+});
+const DIAGRAM_ID = /^[a-z][a-z0-9-]{0,47}$/;
+export const DIAGRAM_BLOCK_TYPES = [
+    'flow',
+    'tree',
+    'board',
+    'terminal',
+];
+export function diagramJsonPath(path) {
+    return toJsonPath(path);
+}
+function isPlainObject(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+function parseDiagramId(value, path) {
+    if (typeof value !== 'string' || !DIAGRAM_ID.test(value)) {
+        return fail(path, 'Use 1–48 lowercase letters, digits or hyphens, starting with a letter');
+    }
+    return ok(value);
+}
+function parseFlow(record, path) {
+    const base = parseBlockBase(record, path);
+    if (!base.success)
+        return base;
+    if (!Array.isArray(record.nodes))
+        return fail([...path, 'nodes'], 'nodes must be an array');
+    if (record.nodes.length < 1 || record.nodes.length > DIAGRAM_LIMITS.flowNodes) {
+        return fail([...path, 'nodes'], `nodes must have 1–${DIAGRAM_LIMITS.flowNodes} items`);
+    }
+    if (record.loopBack !== undefined && typeof record.loopBack !== 'boolean') {
+        return fail([...path, 'loopBack'], 'loopBack must be a boolean');
+    }
+    const nodes = [];
+    const ids = new Set();
+    const issues = [];
+    record.nodes.forEach((raw, index) => {
+        if (!isPlainObject(raw)) {
+            issues.push({ path: [...path, 'nodes', index], message: 'Expected a node object' });
+            return;
+        }
+        const id = parseDiagramId(raw.id, [...path, 'nodes', index, 'id']);
+        if (!id.success) {
+            issues.push(...id.issues);
+            return;
+        }
+        if (ids.has(id.data)) {
+            issues.push({
+                path: [...path, 'nodes', index, 'id'],
+                message: `Duplicate node id: ${id.data}`,
+            });
+        }
+        ids.add(id.data);
+        const label = parsePlainText(raw.label, [...path, 'nodes', index, 'label'], 120);
+        if (!label.success) {
+            issues.push(...label.issues);
+            return;
+        }
+        const tone = parseTone(raw.tone, [...path, 'nodes', index, 'tone']);
+        if (!tone.success) {
+            issues.push(...tone.issues);
+            return;
+        }
+        const node = { id: id.data, label: label.data };
+        if (tone.data !== undefined)
+            node.tone = tone.data;
+        nodes.push(node);
+    });
+    if (issues.length > 0)
+        return failMany(issues);
+    const data = { ...base.data, type: 'flow', nodes };
+    if (record.loopBack === true)
+        data.loopBack = true;
+    return ok(data);
+}
+function parseTree(record, path) {
+    const base = parseBlockBase(record, path);
+    if (!base.success)
+        return base;
+    if (record.style !== 'file-tree' && record.style !== 'org') {
+        return fail([...path, 'style'], 'style must be "file-tree" or "org"');
+    }
+    if (!Array.isArray(record.nodes))
+        return fail([...path, 'nodes'], 'nodes must be an array');
+    if (record.nodes.length < 1 || record.nodes.length > DIAGRAM_LIMITS.treeNodes) {
+        return fail([...path, 'nodes'], `nodes must have 1–${DIAGRAM_LIMITS.treeNodes} items`);
+    }
+    const nodes = [];
+    const byId = new Map();
+    const issues = [];
+    record.nodes.forEach((raw, index) => {
+        if (!isPlainObject(raw)) {
+            issues.push({ path: [...path, 'nodes', index], message: 'Expected a node object' });
+            return;
+        }
+        const id = parseDiagramId(raw.id, [...path, 'nodes', index, 'id']);
+        if (!id.success) {
+            issues.push(...id.issues);
+            return;
+        }
+        if (byId.has(id.data)) {
+            issues.push({
+                path: [...path, 'nodes', index, 'id'],
+                message: `Duplicate node id: ${id.data}`,
+            });
+        }
+        let parentId;
+        if (raw.parentId === null)
+            parentId = null;
+        else {
+            const parent = parseDiagramId(raw.parentId, [...path, 'nodes', index, 'parentId']);
+            if (!parent.success) {
+                issues.push(...parent.issues);
+                return;
+            }
+            parentId = parent.data;
+        }
+        const label = parsePlainText(raw.label, [...path, 'nodes', index, 'label'], 120);
+        if (!label.success) {
+            issues.push(...label.issues);
+            return;
+        }
+        const tone = parseTone(raw.tone, [...path, 'nodes', index, 'tone']);
+        if (!tone.success) {
+            issues.push(...tone.issues);
+            return;
+        }
+        const node = { id: id.data, parentId, label: label.data };
+        if (tone.data !== undefined)
+            node.tone = tone.data;
+        nodes.push(node);
+        byId.set(node.id, node);
+    });
+    if (issues.length > 0)
+        return failMany(issues);
+    const roots = nodes.filter((n) => n.parentId === null);
+    if (roots.length === 0) {
+        return fail([...path, 'nodes'], 'A tree needs at least one root node');
+    }
+    for (let index = 0; index < nodes.length; index++) {
+        const node = nodes[index];
+        if (!node)
+            continue;
+        if (node.parentId !== null && !byId.has(node.parentId)) {
+            issues.push({
+                path: [...path, 'nodes', index, 'parentId'],
+                message: `Unknown parent id: ${node.parentId}`,
+            });
+            continue;
+        }
+        let depth = 1;
+        let parentId = node.parentId;
+        const visited = new Set([node.id]);
+        while (parentId !== null && byId.has(parentId)) {
+            if (visited.has(parentId)) {
+                issues.push({
+                    path: [...path, 'nodes', index, 'parentId'],
+                    message: 'Tree contains a parent cycle',
+                });
+                break;
+            }
+            visited.add(parentId);
+            depth += 1;
+            parentId = byId.get(parentId)?.parentId ?? null;
+        }
+        if (depth > DIAGRAM_LIMITS.treeDepth) {
+            issues.push({
+                path: [...path, 'nodes', index],
+                message: `Tree depth exceeds ${DIAGRAM_LIMITS.treeDepth}`,
+            });
+        }
+    }
+    if (issues.length > 0)
+        return failMany(issues);
+    return ok({ ...base.data, type: 'tree', style: record.style, nodes });
+}
+function parseBoard(record, path) {
+    const base = parseBlockBase(record, path);
+    if (!base.success)
+        return base;
+    if (!Array.isArray(record.columns))
+        return fail([...path, 'columns'], 'columns must be an array');
+    if (record.columns.length < 1 || record.columns.length > DIAGRAM_LIMITS.boardColumns) {
+        return fail([...path, 'columns'], `columns must have 1–${DIAGRAM_LIMITS.boardColumns} items`);
+    }
+    const columns = [];
+    const ids = new Set();
+    const issues = [];
+    record.columns.forEach((rawCol, columnIndex) => {
+        if (!isPlainObject(rawCol)) {
+            issues.push({ path: [...path, 'columns', columnIndex], message: 'Expected a column object' });
+            return;
+        }
+        const id = parseDiagramId(rawCol.id, [...path, 'columns', columnIndex, 'id']);
+        if (!id.success) {
+            issues.push(...id.issues);
+            return;
+        }
+        if (ids.has(id.data)) {
+            issues.push({
+                path: [...path, 'columns', columnIndex, 'id'],
+                message: `Duplicate diagram id: ${id.data}`,
+            });
+        }
+        ids.add(id.data);
+        const title = parsePlainText(rawCol.title, [...path, 'columns', columnIndex, 'title'], 120);
+        if (!title.success) {
+            issues.push(...title.issues);
+            return;
+        }
+        if (!Array.isArray(rawCol.cards)) {
+            issues.push({
+                path: [...path, 'columns', columnIndex, 'cards'],
+                message: 'cards must be an array',
+            });
+            return;
+        }
+        if (rawCol.cards.length > DIAGRAM_LIMITS.boardCardsPerColumn) {
+            issues.push({
+                path: [...path, 'columns', columnIndex, 'cards'],
+                message: `cards must have at most ${DIAGRAM_LIMITS.boardCardsPerColumn} items`,
+            });
+            return;
+        }
+        const cards = [];
+        rawCol.cards.forEach((rawCard, cardIndex) => {
+            if (!isPlainObject(rawCard)) {
+                issues.push({
+                    path: [...path, 'columns', columnIndex, 'cards', cardIndex],
+                    message: 'Expected a card object',
+                });
+                return;
+            }
+            const cardId = parseDiagramId(rawCard.id, [
+                ...path,
+                'columns',
+                columnIndex,
+                'cards',
+                cardIndex,
+                'id',
+            ]);
+            if (!cardId.success) {
+                issues.push(...cardId.issues);
+                return;
+            }
+            if (ids.has(cardId.data)) {
+                issues.push({
+                    path: [...path, 'columns', columnIndex, 'cards', cardIndex, 'id'],
+                    message: `Duplicate diagram id: ${cardId.data}`,
+                });
+            }
+            ids.add(cardId.data);
+            const cardTitle = parsePlainText(rawCard.title, [...path, 'columns', columnIndex, 'cards', cardIndex, 'title'], 120);
+            if (!cardTitle.success) {
+                issues.push(...cardTitle.issues);
+                return;
+            }
+            const tone = parseTone(rawCard.tone, [
+                ...path,
+                'columns',
+                columnIndex,
+                'cards',
+                cardIndex,
+                'tone',
+            ]);
+            if (!tone.success) {
+                issues.push(...tone.issues);
+                return;
+            }
+            const card = { id: cardId.data, title: cardTitle.data };
+            if (tone.data !== undefined)
+                card.tone = tone.data;
+            cards.push(card);
+        });
+        columns.push({ id: id.data, title: title.data, cards });
+    });
+    if (issues.length > 0)
+        return failMany(issues);
+    return ok({ ...base.data, type: 'board', columns });
+}
+function parseTerminal(record, path) {
+    const base = parseBlockBase(record, path);
+    if (!base.success)
+        return base;
+    if (!Array.isArray(record.lines))
+        return fail([...path, 'lines'], 'lines must be an array');
+    if (record.lines.length < 1 || record.lines.length > DIAGRAM_LIMITS.terminalLines) {
+        return fail([...path, 'lines'], `lines must have 1–${DIAGRAM_LIMITS.terminalLines} items`);
+    }
+    const lines = [];
+    const issues = [];
+    record.lines.forEach((raw, index) => {
+        if (!isPlainObject(raw)) {
+            issues.push({ path: [...path, 'lines', index], message: 'Expected a line object' });
+            return;
+        }
+        if (raw.kind !== 'prompt' && raw.kind !== 'output' && raw.kind !== 'comment') {
+            issues.push({
+                path: [...path, 'lines', index, 'kind'],
+                message: 'kind must be prompt, output or comment',
+            });
+            return;
+        }
+        const text = parsePlainText(raw.text, [...path, 'lines', index, 'text'], 240);
+        if (!text.success) {
+            issues.push(...text.issues);
+            return;
+        }
+        lines.push({ kind: raw.kind, text: text.data });
+    });
+    if (issues.length > 0)
+        return failMany(issues);
+    return ok({ ...base.data, type: 'terminal', lines });
+}
+/** Parse an untrusted diagram without throwing. */
+export function parseDiagram(input) {
+    if (!isPlainObject(input)) {
+        return { success: false, issues: [{ jsonPath: '$', message: 'Expected a diagram object' }] };
+    }
+    const type = input.type;
+    let result;
+    if (type === 'flow')
+        result = parseFlow(input, []);
+    else if (type === 'tree')
+        result = parseTree(input, []);
+    else if (type === 'board')
+        result = parseBoard(input, []);
+    else if (type === 'terminal')
+        result = parseTerminal(input, []);
+    else {
+        return {
+            success: false,
+            issues: [{ jsonPath: '$["type"]', message: 'type must be flow, tree, board or terminal' }],
+        };
+    }
+    if (result.success)
+        return { success: true, data: result.data };
+    return {
+        success: false,
+        issues: result.issues.map((issue) => ({
+            jsonPath: diagramJsonPath(issue.path),
+            message: issue.message,
+        })),
+    };
+}

package/dist/diagram/tones.d.ts

@@ -0,0 +1,6 @@
+import type { BlockTone } from '../core/schema/vocabulary.js';
+/** Diagram pad around SVG/HTML layout boxes (px). */
+export declare const DIAGRAM_PAD = 16;
+/** Map block tones to accent border classes (token colors). */
+export declare const TONE_BORDER: Readonly<Record<BlockTone, string>>;
+export declare function toneBorder(tone: string | undefined): string;

package/dist/diagram/tones.js

@@ -0,0 +1,16 @@
+/** Diagram pad around SVG/HTML layout boxes (px). */
+export const DIAGRAM_PAD = 16;
+/** Map block tones to accent border classes (token colors). */
+export const TONE_BORDER = Object.freeze({
+    neutral: 'tx-diagram-tone--neutral',
+    accent: 'tx-diagram-tone--accent',
+    info: 'tx-diagram-tone--info',
+    success: 'tx-diagram-tone--success',
+    warning: 'tx-diagram-tone--warning',
+    danger: 'tx-diagram-tone--danger',
+});
+export function toneBorder(tone) {
+    if (tone && tone in TONE_BORDER)
+        return TONE_BORDER[tone];
+    return TONE_BORDER.neutral;
+}