@texuli/core 0.1.0-next.0 → 0.1.0-next.2

package/dist/editor/load.d.ts

@@ -0,0 +1,44 @@
+import type { HrefTrust } from '../url/safe-href.js';
+import { type EditorIdSource } from './document.js';
+import { type EditorDocument, type EditorInline, type EditorIssue, type EditorIssueCode, type EditorLimits, type EditorMark } from './types.js';
+export interface EditorLoadOptions {
+    /** URL policy tier for link hrefs. Default `untrusted`. */
+    trust?: HrefTrust;
+    newId?: EditorIdSource;
+    /** Lower caps (a blocks `text` field holds 4,000 characters). */
+    limits?: Partial<EditorLimits>;
+}
+export interface EditorLoadResult {
+    doc: EditorDocument;
+    diagnostics: readonly EditorIssue[];
+}
+/** Caps shared by the loaders: blocks, characters and diagnostics. Internal. */
+export declare class LoadBudget {
+    readonly diagnostics: EditorIssue[];
+    readonly limits: EditorLimits;
+    readonly trust: HrefTrust;
+    readonly newId: EditorIdSource;
+    blocks: number;
+    chars: number;
+    private readonly once;
+    constructor(options: EditorLoadOptions);
+    report(code: EditorIssueCode, message: string, onlyOnce?: boolean): void;
+    /** Reserve one block; false (reported) once the cap is reached. */
+    block(): boolean;
+    /** Keep as much of `text` as the character cap allows. */
+    text(text: string): string;
+    clean(text: string, keep: string): string;
+    /** A policy-checked href, or `undefined` (reported). */
+    href(value: unknown): string | undefined;
+    /** Inline content for plain text under the caps. */
+    inline(text: string, marks?: readonly EditorMark[]): readonly EditorInline[];
+}
+/**
+ * Load an untrusted document (stored JSON, the editor's own clipboard) into a
+ * valid version 1 document. Never throws: malformed parts are dropped,
+ * unknown blocks become paragraphs of their text, deep nesting and oversized
+ * input are capped, and every link href passes `safeHref` at `trust`
+ * (`untrusted` by default). Each degradation is reported once in
+ * `diagnostics`. Every block gets a fresh id.
+ */
+export declare function loadEditorDocument(input: unknown, options?: EditorLoadOptions): EditorLoadResult;

package/dist/editor/load.js

@@ -0,0 +1,248 @@
+import { safeHref } from "../url/safe-href.js";
+import { LANG_PATTERN, nextEditorId, normalizeDocument, paragraph, } from "./document.js";
+import { cleanText, normalizeInline, textToInline } from "./inline.js";
+import { EDITOR_LIMITS, } from "./types.js";
+const MAX_DIAGNOSTICS = 50;
+/** Caps shared by the loaders: blocks, characters and diagnostics. Internal. */
+export class LoadBudget {
+    diagnostics = [];
+    limits;
+    trust;
+    newId;
+    blocks = 0;
+    chars = 0;
+    once = new Set();
+    constructor(options) {
+        this.limits = { ...EDITOR_LIMITS, ...options.limits };
+        this.trust = options.trust === 'developer' ? 'developer' : 'untrusted';
+        this.newId = options.newId ?? nextEditorId;
+    }
+    report(code, message, onlyOnce = true) {
+        if (onlyOnce && this.once.has(code))
+            return;
+        this.once.add(code);
+        if (this.diagnostics.length < MAX_DIAGNOSTICS)
+            this.diagnostics.push({ code, message });
+    }
+    /** Reserve one block; false (reported) once the cap is reached. */
+    block() {
+        if (this.blocks >= this.limits.blocks) {
+            this.report('blocks-capped', `Blocks after the first ${this.limits.blocks} were dropped.`);
+            return false;
+        }
+        this.blocks += 1;
+        return true;
+    }
+    /** Keep as much of `text` as the character cap allows. */
+    text(text) {
+        const room = Math.max(0, this.limits.chars - this.chars);
+        if (text.length > room) {
+            this.report('text-truncated', `Text after ${this.limits.chars} characters was dropped.`);
+            text = text.slice(0, room);
+        }
+        this.chars += text.length;
+        return text;
+    }
+    clean(text, keep) {
+        const clean = cleanText(text, keep);
+        if (clean.stripped)
+            this.report('characters-stripped', 'Control and bidirectional override characters were removed.');
+        return clean.text;
+    }
+    /** A policy-checked href, or `undefined` (reported). */
+    href(value) {
+        const href = typeof value === 'string' && value.length <= EDITOR_LIMITS.href
+            ? safeHref(value, this.trust)
+            : undefined;
+        if (href === undefined)
+            this.report('link-rejected', 'A link URL was refused by the URL policy; its text was kept.');
+        return href;
+    }
+    /** Inline content for plain text under the caps. */
+    inline(text, marks = []) {
+        const { content, stripped } = textToInline(this.text(text), marks);
+        if (stripped)
+            this.report('characters-stripped', 'Control and bidirectional override characters were removed.');
+        return content;
+    }
+}
+const isRecord = (value) => typeof value === 'object' && value !== null && !Array.isArray(value);
+/** Plain text found in an unknown value, depth- and size-bounded. */
+function plainOf(value, depth = 0, out = []) {
+    if (depth > 8 || out.length > 256)
+        return out;
+    if (typeof value === 'string')
+        out.push(value);
+    else if (Array.isArray(value))
+        for (const entry of value.slice(0, 256))
+            plainOf(entry, depth + 1, out);
+    else if (isRecord(value)) {
+        for (const key of ['text', 'content', 'blocks', 'items', 'alt'])
+            if (key in value)
+                plainOf(value[key], depth + 1, out);
+    }
+    return out;
+}
+function loadMarks(raw, budget) {
+    if (!Array.isArray(raw))
+        return [];
+    const marks = [];
+    for (const mark of raw.slice(0, 8)) {
+        const type = isRecord(mark) ? mark.type : undefined;
+        if (type === 'strong' || type === 'em' || type === 'strike' || type === 'code')
+            marks.push({ type });
+        else if (type === 'link') {
+            const href = budget.href(mark.href);
+            if (href)
+                marks.push({ type: 'link', href });
+        }
+        else
+            budget.report('unknown-mark', 'Unknown marks were dropped.');
+    }
+    return marks;
+}
+function loadInline(raw, budget) {
+    if (typeof raw === 'string')
+        return budget.inline(raw);
+    if (!Array.isArray(raw))
+        return [];
+    const out = [];
+    for (const node of raw) {
+        if (budget.chars >= budget.limits.chars) {
+            budget.report('text-truncated', `Text after ${budget.limits.chars} characters was dropped.`);
+            break;
+        }
+        if (isRecord(node) && node.type === 'break') {
+            out.push({ type: 'break' });
+            budget.chars += 1;
+        }
+        else if (isRecord(node) && node.type === 'text' && typeof node.text === 'string') {
+            out.push(...budget.inline(node.text, loadMarks(node.marks, budget)));
+        }
+        else
+            budget.report('invalid-shape', 'Malformed inline nodes were dropped.');
+    }
+    return normalizeInline(out);
+}
+/** Paragraphs holding the plain text of a value that cannot be kept as is. */
+function degrade(raw, budget) {
+    const text = plainOf(raw).join(' ').replace(/\s+/g, ' ').trim();
+    return text && budget.block() ? [paragraph(budget.inline(text), budget.newId())] : [];
+}
+function loadBlocks(raw, depth, budget) {
+    if (!Array.isArray(raw)) {
+        budget.report('invalid-shape', 'Blocks must be an array.');
+        return [];
+    }
+    const out = [];
+    for (const entry of raw) {
+        if (budget.blocks >= budget.limits.blocks) {
+            budget.block();
+            break;
+        }
+        out.push(...loadBlock(entry, depth, budget));
+    }
+    return out;
+}
+function loadBlock(raw, depth, budget) {
+    if (!isRecord(raw)) {
+        budget.report('invalid-shape', 'Malformed blocks were dropped.');
+        return [];
+    }
+    const type = raw.type;
+    if (type === 'list' || type === 'quote') {
+        if (depth >= budget.limits.depth) {
+            budget.report('depth-capped', `Lists and quotes deeper than ${budget.limits.depth} levels became text.`);
+            return degrade(raw, budget);
+        }
+        if (!budget.block())
+            return [];
+        const id = budget.newId();
+        if (type === 'quote') {
+            const blocks = loadBlocks(raw.blocks, depth + 1, budget);
+            return blocks.length ? [{ id, type: 'quote', blocks }] : [];
+        }
+        const kind = raw.kind === 'ordered' || raw.kind === 'todo' ? raw.kind : 'bullet';
+        const items = [];
+        for (const item of Array.isArray(raw.items) ? raw.items : []) {
+            if (!isRecord(item) || !budget.block())
+                continue;
+            const blocks = loadBlocks(item.blocks, depth + 1, budget);
+            items.push(kind === 'todo'
+                ? { id: budget.newId(), checked: item.checked === true, blocks }
+                : { id: budget.newId(), blocks });
+        }
+        const start = typeof raw.start === 'number' && Number.isInteger(raw.start) && raw.start >= 0
+            ? raw.start
+            : undefined;
+        return [
+            kind === 'ordered' && start !== undefined
+                ? { id, type: 'list', kind, start, items }
+                : { id, type: 'list', kind, items },
+        ];
+    }
+    if (type === 'paragraph' ||
+        type === 'heading' ||
+        type === 'code' ||
+        type === 'divider' ||
+        type === 'media') {
+        if (!budget.block())
+            return [];
+        const id = budget.newId();
+        if (type === 'divider')
+            return [{ id, type }];
+        if (type === 'code') {
+            const text = budget.text(budget.clean(typeof raw.text === 'string' ? raw.text : '', '\n\t'));
+            const lang = typeof raw.lang === 'string' ? raw.lang.toLowerCase() : undefined;
+            return [lang && LANG_PATTERN.test(lang) ? { id, type, lang, text } : { id, type, text }];
+        }
+        if (type === 'media') {
+            const ref = typeof raw.ref === 'string' && raw.ref.length <= EDITOR_LIMITS.href ? raw.ref.trim() : '';
+            if (!ref) {
+                budget.report('invalid-shape', 'Media without a usable ref was dropped.');
+                return [];
+            }
+            const alt = budget.text(budget.clean(typeof raw.alt === 'string' ? raw.alt : '', ''));
+            return [{ id, type, ref, alt }];
+        }
+        const content = loadInline(raw.content, budget);
+        if (type === 'heading') {
+            const level = typeof raw.level === 'number' && Number.isInteger(raw.level) ? raw.level : 0;
+            if (level >= 1 && level <= 6) {
+                if (level > 4)
+                    budget.report('heading-clamped', 'Headings deeper than level 4 became level 4.');
+                return [{ id, type, level: Math.min(level, 4), content }];
+            }
+            budget.report('invalid-shape', 'Headings without a valid level became paragraphs.');
+        }
+        return [{ id, type: 'paragraph', content }];
+    }
+    budget.report('unknown-node', 'Unknown block types became plain paragraphs.');
+    return degrade(raw, budget);
+}
+/**
+ * Load an untrusted document (stored JSON, the editor's own clipboard) into a
+ * valid version 1 document. Never throws: malformed parts are dropped,
+ * unknown blocks become paragraphs of their text, deep nesting and oversized
+ * input are capped, and every link href passes `safeHref` at `trust`
+ * (`untrusted` by default). Each degradation is reported once in
+ * `diagnostics`. Every block gets a fresh id.
+ */
+export function loadEditorDocument(input, options = {}) {
+    const budget = new LoadBudget(options);
+    const record = isRecord(input) ? input : null;
+    if (record && record.version !== undefined && record.version !== 1) {
+        budget.report('version-unsupported', `Document version ${String(record.version)} is not supported.`);
+        return {
+            doc: normalizeDocument({ version: 1, blocks: [] }, budget.newId),
+            diagnostics: budget.diagnostics,
+        };
+    }
+    if (!record || !Array.isArray(record.blocks))
+        budget.report('invalid-shape', 'A document is { version: 1, blocks: [...] }.');
+    const blocks = record ? loadBlocks(record.blocks ?? [], 0, budget) : [];
+    return {
+        doc: normalizeDocument({ version: 1, blocks }, budget.newId),
+        diagnostics: budget.diagnostics,
+    };
+}

package/dist/editor/markdown.d.ts

@@ -0,0 +1,33 @@
+import { type EditorLoadOptions, type EditorLoadResult } from './load.js';
+import type { EditorDocument } from './types.js';
+/**
+ * The editor's Markdown codec (ADR-003): the same closed subset that
+ * `@texuli/blocks` text blocks and the catalog's rich text parse, read into
+ * and written from the editor model. Nothing here produces or keeps HTML: raw
+ * tags stay literal text, every link passes `safeHref`, and images become
+ * their alt text (or a media block when one stands alone in a paragraph).
+ */
+export declare const MARKDOWN_CODEC_LIMITS: Readonly<{
+    /** Longest source read; the rest is dropped with a diagnostic. */
+    source: 100000;
+    /** Nested emphasis and links. */
+    inlineDepth: 6;
+}>;
+export interface MarkdownReadOptions extends EditorLoadOptions {
+    /** Override the source cap (a blocks `text` field holds 4,000 characters). */
+    maxSource?: number;
+}
+/**
+ * Read Markdown (untrusted by default) into a valid document. Never throws:
+ * nesting deeper than the depth cap and oversized input degrade to text,
+ * refused links keep their text, headings deeper than 4 become level 4, and
+ * each degradation is reported once in `diagnostics`.
+ */
+export declare function fromMarkdown(source: unknown, options?: MarkdownReadOptions): EditorLoadResult;
+/**
+ * Write a document as the closed Markdown subset. Reading the result back
+ * gives the same document, except for what the subset cannot spell: empty
+ * paragraphs, breaks in headings (written as spaces), breaks at the edges of
+ * a block, and whitespace at the edges of a paragraph or a mark.
+ */
+export declare function toMarkdown(doc: EditorDocument): string;