@north-light/api 0.3.580 → 0.3.588

package/dist/core/human/page-html-markdown.js

@@ -0,0 +1,260 @@
+/** An HTML page's document projected to markdown, so a terminal reader sees the
+ *  page's actual content instead of a placeholder line. HTML pages are authored
+ *  for a browser surface and carry no slots, so this is a reading projection
+ *  only — layout, styling, and scripting are dropped, and what survives is the
+ *  prose, headings, lists, links, code, and table cells the author wrote. */
+const DROPPED = new Set(['script', 'style', 'head', 'template', 'noscript', 'svg', 'iframe', 'object']);
+const BLOCK = new Set([
+    'address', 'article', 'aside', 'blockquote', 'details', 'dialog', 'div', 'dl', 'fieldset', 'figcaption', 'figure',
+    'footer', 'form', 'header', 'main', 'nav', 'p', 'section', 'summary', 'table', 'tbody', 'tfoot', 'thead', 'video',
+]);
+const VOID = new Set(['area', 'base', 'br', 'col', 'embed', 'hr', 'img', 'input', 'link', 'meta', 'param', 'source', 'track', 'wbr']);
+const ENTITIES = { amp: '&', lt: '<', gt: '>', quot: '"', apos: "'", nbsp: ' ', mdash: '—', ndash: '–', hellip: '…', rsquo: '’', lsquo: '‘', rdquo: '”', ldquo: '“' };
+const TAG = /<!--[\s\S]*?-->|<!\[CDATA\[[\s\S]*?\]\]>|<![^>]*>|<(\/?)([a-zA-Z][^\s/>]*)((?:"[^"]*"|'[^']*'|[^>])*?)\/?>/g;
+const ATTR = /([^\s=/>]+)(?:\s*=\s*(?:"([^"]*)"|'([^']*)'|([^\s"'>]+)))?/g;
+function decode(value) {
+    return value.replace(/&(#x?[0-9a-fA-F]+|[a-zA-Z][a-zA-Z0-9]*);/g, (whole, body) => {
+        if (body.startsWith('#')) {
+            const code = body[1] === 'x' || body[1] === 'X' ? Number.parseInt(body.slice(2), 16) : Number.parseInt(body.slice(1), 10);
+            return Number.isFinite(code) && code > 0 && code <= 0x10ffff ? String.fromCodePoint(code) : whole;
+        }
+        return ENTITIES[body.toLowerCase()] ?? whole;
+    });
+}
+function attrsOf(source) {
+    const attrs = new Map();
+    for (const match of source.matchAll(ATTR))
+        attrs.set(match[1].toLowerCase(), decode(match[2] ?? match[3] ?? match[4] ?? ''));
+    return attrs;
+}
+function tokenize(document) {
+    const tokens = [];
+    let at = 0;
+    for (const match of document.matchAll(TAG)) {
+        if (match.index > at)
+            tokens.push({ kind: 'text', text: document.slice(at, match.index) });
+        at = match.index + match[0].length;
+        if (match[2] !== undefined)
+            tokens.push({ kind: 'tag', name: match[2].toLowerCase(), closing: match[1] === '/', selfClosing: match[0].endsWith('/>'), attrs: attrsOf(match[3] ?? '') });
+    }
+    if (at < document.length)
+        tokens.push({ kind: 'text', text: document.slice(at) });
+    return tokens;
+}
+/** Markdown's structural characters, escaped so authored prose reads as prose.
+ *  Mirrors the JSX projection's escaping so both dialects render alike. */
+function escapeText(value) {
+    return value.replace(/([\\`*_[\]<>#])/g, '\\$1');
+}
+class Sink {
+    buffers = [''];
+    write(text) { this.buffers[this.buffers.length - 1] += text; }
+    get top() { return this.buffers[this.buffers.length - 1]; }
+    set top(value) { this.buffers[this.buffers.length - 1] = value; }
+    push() { this.buffers.push(''); }
+    pop() { return this.buffers.length > 1 ? this.buffers.pop() : ''; }
+    get nested() { return this.buffers.length > 1; }
+    /** End the current line without opening a new block. */
+    line() {
+        this.top = this.top.replace(/[ \t]+$/, '');
+        if (this.top !== '' && !this.top.endsWith('\n'))
+            this.write('\n');
+    }
+    /** Separate what follows from what precedes by one blank line. */
+    block() {
+        this.top = this.top.replace(/[ \t\n]+$/, '');
+        if (this.top !== '')
+            this.write('\n\n');
+    }
+    done() { return this.buffers.join('').replace(/\n{3,}/g, '\n\n').replace(/[ \t]+\n/g, '\n').trim(); }
+}
+/** Project one authored HTML document to markdown. Never throws: a document
+ *  this cannot make sense of yields whatever text it did find, down to ''. */
+export function projectHtmlDocumentMarkdown(document) {
+    const sink = new Sink();
+    const lists = [];
+    const anchors = [];
+    const dropped = [];
+    let preDepth = 0;
+    let cellOpen = false;
+    let headerRow = false;
+    let rowCells = 0;
+    const indent = () => '  '.repeat(Math.max(0, lists.length - 1));
+    for (const token of tokenize(document)) {
+        if (token.kind === 'text') {
+            if (dropped.length > 0)
+                continue;
+            if (preDepth > 0) {
+                sink.write(token.text);
+                continue;
+            }
+            const text = decode(token.text).replace(/\s+/g, ' ');
+            if (text.trim() === '') {
+                if (/\s/.test(text))
+                    sink.write(' ');
+                continue;
+            }
+            sink.write(escapeText(text));
+            continue;
+        }
+        const { name, closing, attrs } = token;
+        // Unwinding to the matching open keeps one stray close tag from reopening
+        // the whole document, and one stray open from swallowing the rest of it.
+        if (DROPPED.has(name)) {
+            if (closing) {
+                const at = dropped.lastIndexOf(name);
+                if (at >= 0)
+                    dropped.length = at;
+            }
+            else if (!token.selfClosing)
+                dropped.push(name);
+            continue;
+        }
+        if (dropped.length > 0)
+            continue;
+        const heading = /^h([1-6])$/.exec(name);
+        if (heading !== null) {
+            sink.block();
+            if (!closing)
+                sink.write(`${'#'.repeat(Number(heading[1]))} `);
+            continue;
+        }
+        if (name === 'pre') {
+            if (closing) {
+                preDepth = Math.max(0, preDepth - 1);
+                sink.line();
+                sink.write('```');
+                sink.block();
+            }
+            else {
+                sink.block();
+                sink.write('```\n');
+                preDepth++;
+            }
+            continue;
+        }
+        if (name === 'br') {
+            sink.line();
+            continue;
+        }
+        if (name === 'hr') {
+            sink.block();
+            sink.write('---');
+            sink.block();
+            continue;
+        }
+        if (name === 'ul' || name === 'ol') {
+            if (closing)
+                lists.pop();
+            else {
+                sink.block();
+                lists.push({ ordered: name === 'ol', index: 0 });
+            }
+            if (closing)
+                sink.block();
+            continue;
+        }
+        if (name === 'li') {
+            if (closing)
+                continue;
+            const frame = lists[lists.length - 1];
+            sink.line();
+            if (frame === undefined)
+                sink.write('- ');
+            else {
+                frame.index++;
+                sink.write(`${indent()}${frame.ordered ? `${frame.index}. ` : '- '}`);
+            }
+            continue;
+        }
+        if (name === 'dt' || name === 'dd') {
+            sink.line();
+            if (!closing)
+                sink.write(name === 'dt' ? '' : '  ');
+            continue;
+        }
+        if (name === 'tr') {
+            if (closing) {
+                sink.write(rowCells > 0 ? ' |' : '');
+                if (headerRow && rowCells > 0) {
+                    sink.line();
+                    sink.write(`|${' --- |'.repeat(rowCells)}`);
+                }
+                sink.line();
+            }
+            else {
+                sink.line();
+                headerRow = false;
+                rowCells = 0;
+            }
+            continue;
+        }
+        if (name === 'td' || name === 'th') {
+            if (closing) {
+                if (!cellOpen)
+                    continue;
+                cellOpen = false;
+                sink.write(sink.pop().replace(/\s+/g, ' ').trim());
+            }
+            else {
+                if (name === 'th')
+                    headerRow = true;
+                rowCells++;
+                sink.write(rowCells === 1 ? '| ' : ' | ');
+                sink.push();
+                cellOpen = true;
+            }
+            continue;
+        }
+        if (name === 'a') {
+            // The label is captured rather than streamed, so a link with no text
+            // never leaves a bare `[](url)` behind.
+            if (closing) {
+                if (anchors.length === 0)
+                    continue;
+                const href = anchors.pop();
+                if (href === null)
+                    continue;
+                const label = sink.pop().replace(/\s+/g, ' ').trim();
+                if (label !== '')
+                    sink.write(`[${label}](${href})`);
+                continue;
+            }
+            const href = attrs.get('href');
+            const linkable = href !== undefined && href !== '' && !href.startsWith('#');
+            anchors.push(linkable ? href : null);
+            if (linkable)
+                sink.push();
+            continue;
+        }
+        if (name === 'code' && preDepth === 0) {
+            sink.write('`');
+            continue;
+        }
+        if (name === 'strong' || name === 'b') {
+            sink.write('**');
+            continue;
+        }
+        if (name === 'em' || name === 'i') {
+            sink.write('*');
+            continue;
+        }
+        if (name === 'img') {
+            const alt = attrs.get('alt');
+            if (alt !== undefined && alt !== '')
+                sink.write(escapeText(alt));
+            continue;
+        }
+        if (name === 'blockquote') {
+            sink.block();
+            if (!closing)
+                sink.write('> ');
+            continue;
+        }
+        if (BLOCK.has(name) && !VOID.has(name)) {
+            sink.block();
+            continue;
+        }
+    }
+    return sink.done();
+}

package/dist/core/human/page-markdown.d.ts

@@ -0,0 +1,3 @@
+import type { PageManifest } from './page-schema.js';
+/** Project the authored display JSX only. Manifest slots remain the authoritative terminal rendering for questions, inputs, charts, and product components. */
+export declare function projectPageDisplayMarkdown(document: string, manifest: PageManifest): string;

package/dist/core/human/page-markdown.js

@@ -0,0 +1,295 @@
+import { BUILTIN_KIND_BY_TAG, BUILTIN_PAGE_COMPONENT_TAGS, DISPLAY_PAGE_COMPONENT_TAGS, pageComponentTag } from './page-catalog.js';
+import { evaluatePageTree } from './page-eval.js';
+import { PageAuthoringError } from './page-errors.js';
+import { compilePage } from './page.js';
+const SLOT_TAGS = new Set(Object.keys(BUILTIN_KIND_BY_TAG));
+const BLOCK_TAGS = new Set([
+    'Page', 'Step',
+    'Card', 'CardHeader', 'CardTitle', 'CardDescription', 'CardContent', 'CardFooter', 'CardAction',
+    'Separator', 'Progress', 'Alert', 'AlertTitle', 'AlertDescription',
+    'Table', 'TableHeader', 'TableBody', 'TableFooter', 'TableRow', 'TableHead', 'TableCell', 'TableCaption',
+    'Tabs', 'TabsList', 'TabsTrigger', 'TabsContent',
+    'Accordion', 'AccordionItem', 'AccordionTrigger', 'AccordionContent',
+    'address', 'article', 'aside', 'blockquote', 'details', 'dialog', 'div', 'dl', 'dt', 'dd', 'fieldset', 'figcaption', 'figure', 'footer', 'form',
+    'h1', 'h2', 'h3', 'h4', 'h5', 'h6', 'header', 'hr', 'li', 'main', 'nav', 'ol', 'p', 'pre', 'section', 'summary', 'table', 'thead', 'tbody', 'tfoot', 'tr', 'th', 'td', 'ul',
+]);
+function isElement(node) {
+    return node.kind === 'element';
+}
+function markdownText(value) {
+    return value.replace(/\s+/g, ' ').replace(/([\\`*_[\]<>#])/g, '\\$1');
+}
+function cleanInline(value) {
+    return value.replace(/[ \t]+\n/g, '\n').replace(/\n[ \t]+/g, '\n').trim();
+}
+function rawText(nodes, context) {
+    let out = '';
+    for (const node of nodes) {
+        if (!isElement(node)) {
+            out += node.text;
+            continue;
+        }
+        if (context.slotTags.has(node.tag))
+            continue;
+        out += rawText(node.children, context);
+    }
+    return out;
+}
+function inlineCode(value) {
+    const text = value.replace(/\s+/g, ' ').trim();
+    if (text === '')
+        return '';
+    const longest = Math.max(0, ...[...text.matchAll(/`+/g)].map((match) => match[0].length));
+    const fence = '`'.repeat(longest + 1);
+    const pad = /^`|`$|^ | $/.test(text) ? ' ' : '';
+    return `${fence}${pad}${text}${pad}${fence}`;
+}
+function inline(nodes, context) {
+    let out = '';
+    for (const node of nodes) {
+        if (!isElement(node)) {
+            out += markdownText(node.text);
+            continue;
+        }
+        if (context.slotTags.has(node.tag))
+            continue;
+        const body = () => inline(node.children, context);
+        switch (node.tag) {
+            case 'br':
+                out += '\n';
+                break;
+            case 'code':
+                out += inlineCode(rawText(node.children, context));
+                break;
+            case 'strong':
+            case 'b': {
+                const text = cleanInline(body());
+                if (text !== '')
+                    out += `**${text}**`;
+                break;
+            }
+            case 'em':
+            case 'i': {
+                const text = cleanInline(body());
+                if (text !== '')
+                    out += `*${text}*`;
+                break;
+            }
+            case 'del':
+            case 's': {
+                const text = cleanInline(body());
+                if (text !== '')
+                    out += `~~${text}~~`;
+                break;
+            }
+            case 'a': {
+                const text = cleanInline(body());
+                const href = node.props['href'];
+                out += typeof href === 'string' && href !== ''
+                    ? `[${text === '' ? markdownText(href) : text}](${href.replace(/([\\()])/g, '\\$1')})`
+                    : text;
+                break;
+            }
+            case 'img': {
+                const alt = typeof node.props['alt'] === 'string' ? markdownText(node.props['alt']) : 'image';
+                const src = node.props['src'];
+                out += typeof src === 'string' && src !== '' ? `![${alt}](${src.replace(/([\\()])/g, '\\$1')})` : alt;
+                break;
+            }
+            case 'Badge': {
+                const text = cleanInline(body());
+                if (text !== '')
+                    out += `**${text}**`;
+                break;
+            }
+            default:
+                out += body();
+        }
+    }
+    return out;
+}
+function quote(block) {
+    return block.split('\n').map((line) => line === '' ? '>' : `> ${line}`).join('\n');
+}
+function languageFor(node) {
+    const candidates = [node.props['className']];
+    const code = node.children.find((child) => isElement(child) && child.tag === 'code');
+    if (code !== undefined)
+        candidates.push(code.props['className']);
+    for (const candidate of candidates) {
+        if (typeof candidate !== 'string')
+            continue;
+        const language = /(?:^|\s)language-([A-Za-z0-9_+-]+)/.exec(candidate)?.[1];
+        if (language !== undefined)
+            return language;
+    }
+    return '';
+}
+function codeBlock(node, context) {
+    const source = rawText(node.children, context).replace(/^\n/, '').replace(/\n$/, '');
+    if (source === '')
+        return '';
+    const longest = Math.max(0, ...[...source.matchAll(/`+/g)].map((match) => match[0].length));
+    const fence = '`'.repeat(Math.max(3, longest + 1));
+    return `${fence}${languageFor(node)}\n${source}\n${fence}`;
+}
+function list(node, ordered, context) {
+    const items = node.children.filter((child) => isElement(child) && child.tag === 'li');
+    return items.map((item, index) => {
+        const marker = ordered ? `${index + 1}.` : '-';
+        const body = flow(item.children, context);
+        if (body === '')
+            return '';
+        const continuation = ' '.repeat(marker.length + 1);
+        return body.split('\n').map((line, lineIndex) => lineIndex === 0 ? `${marker} ${line}` : line === '' ? '' : `${continuation}${line}`).join('\n');
+    }).filter((item) => item !== '').join('\n');
+}
+function table(node, context) {
+    const rows = [];
+    let caption = '';
+    const visit = (nodes) => {
+        for (const child of nodes) {
+            if (!isElement(child) || context.slotTags.has(child.tag))
+                continue;
+            if (child.tag === 'TableCaption' || child.tag === 'caption') {
+                caption = cleanInline(inline(child.children, context));
+                continue;
+            }
+            if (child.tag === 'TableRow' || child.tag === 'tr') {
+                const cells = child.children.filter((cell) => isElement(cell) && ['TableHead', 'TableCell', 'th', 'td'].includes(cell.tag));
+                if (cells.length > 0) {
+                    rows.push({
+                        header: cells.every((cell) => cell.tag === 'TableHead' || cell.tag === 'th'),
+                        cells: cells.map((cell) => cleanInline(inline(cell.children, context)).replaceAll('|', '\\|').replaceAll('\n', '<br>')),
+                    });
+                }
+                continue;
+            }
+            visit(child.children);
+        }
+    };
+    visit(node.children);
+    if (rows.length === 0)
+        return flow(node.children, context);
+    const headerIndex = rows.findIndex((row) => row.header);
+    const header = headerIndex === -1 ? rows[0] : rows[headerIndex];
+    const data = rows.filter((_row, index) => index !== (headerIndex === -1 ? 0 : headerIndex));
+    const width = Math.max(header.cells.length, ...data.map((row) => row.cells.length));
+    const cells = (row) => Array.from({ length: width }, (_value, index) => row[index] ?? '');
+    const lines = [
+        `| ${cells(header.cells).join(' | ')} |`,
+        `| ${Array.from({ length: width }, () => '---').join(' | ')} |`,
+        ...data.map((row) => `| ${cells(row.cells).join(' | ')} |`),
+    ];
+    if (caption !== '')
+        lines.push('', `*${caption}*`);
+    return lines.join('\n');
+}
+function block(node, context) {
+    if (context.slotTags.has(node.tag))
+        return '';
+    const contents = () => flow(node.children, context);
+    switch (node.tag) {
+        case 'Page': return contents();
+        case 'Step': {
+            const title = node.props['title'];
+            const body = contents();
+            const heading = typeof title === 'string' && title.trim() !== '' ? `## ${markdownText(title.trim())}` : '';
+            return [heading, body].filter((part) => part !== '').join('\n\n');
+        }
+        case 'p': return cleanInline(inline(node.children, context));
+        case 'h1':
+        case 'h2':
+        case 'h3':
+        case 'h4':
+        case 'h5':
+        case 'h6': {
+            const text = cleanInline(inline(node.children, context));
+            const level = Math.min(6, Number(node.tag[1]) + 1);
+            return text === '' ? '' : `${'#'.repeat(level)} ${text}`;
+        }
+        case 'ul': return list(node, false, context);
+        case 'ol': return list(node, true, context);
+        case 'li': return cleanInline(contents());
+        case 'pre': return codeBlock(node, context);
+        case 'blockquote': return quote(contents());
+        case 'hr':
+        case 'Separator': return '---';
+        case 'CardTitle':
+        case 'AlertTitle': {
+            const text = cleanInline(inline(node.children, context));
+            return text === '' ? '' : `**${text}**`;
+        }
+        case 'CardDescription': return cleanInline(inline(node.children, context));
+        case 'Alert': {
+            const body = contents();
+            return body === '' ? '' : quote(body);
+        }
+        case 'AlertDescription': return contents();
+        case 'Table':
+        case 'table': return table(node, context);
+        case 'TableRow':
+        case 'TableHead':
+        case 'TableCell':
+        case 'tr':
+        case 'th':
+        case 'td': return cleanInline(inline(node.children, context));
+        case 'TabsTrigger':
+        case 'AccordionTrigger':
+        case 'summary':
+        case 'dt': {
+            const text = cleanInline(inline(node.children, context));
+            return text === '' ? '' : `**${text}**`;
+        }
+        case 'Progress': {
+            const body = contents();
+            const value = node.props['value'];
+            return body !== '' ? body : typeof value === 'number' || typeof value === 'string' ? `Progress: ${markdownText(String(value))}%` : '';
+        }
+        default: return contents();
+    }
+}
+function flow(nodes, context) {
+    const blocks = [];
+    let pending = '';
+    const flush = () => {
+        const text = cleanInline(pending);
+        pending = '';
+        if (text !== '')
+            blocks.push(text);
+    };
+    for (const node of nodes) {
+        if (!isElement(node) || (!context.slotTags.has(node.tag) && !BLOCK_TAGS.has(node.tag))) {
+            pending += isElement(node) ? inline([node], context) : markdownText(node.text);
+            continue;
+        }
+        flush();
+        const rendered = block(node, context).trim();
+        if (rendered !== '')
+            blocks.push(rendered);
+    }
+    flush();
+    return blocks.join('\n\n');
+}
+/** Project the authored display JSX only. Manifest slots remain the authoritative terminal rendering for questions, inputs, charts, and product components. */
+export function projectPageDisplayMarkdown(document, manifest) {
+    if (manifest.dialect !== 'jsx')
+        return '';
+    const productTags = new Set(manifest.slots.filter((slot) => slot.unvalidated === true).map((slot) => pageComponentTag(slot.kind)));
+    const inScope = [...BUILTIN_PAGE_COMPONENT_TAGS, ...DISPLAY_PAGE_COMPONENT_TAGS, ...productTags];
+    const roots = evaluatePageTree(compilePage(document), inScope);
+    const pages = [];
+    const collect = (nodes) => {
+        for (const node of nodes) {
+            if (!isElement(node))
+                continue;
+            if (node.tag === 'Page')
+                pages.push(node);
+            collect(node.children);
+        }
+    };
+    collect(roots);
+    if (pages.length !== 1)
+        throw new PageAuthoringError(`page display projection expected one <Page> element; found ${pages.length}`);
+    return flow(pages[0].children, { slotTags: new Set([...SLOT_TAGS, ...productTags]) }).trim();
+}