@kernlang/core 3.1.5 → 3.1.7

package/dist/parser.js

@@ -1,341 +1,20 @@
+/**
+ * KERN Parser — public API surface.
+ *
+ * Implementation is split across sibling modules:
+ * - parser-diagnostics.ts — diagnostic infrastructure
+ * - parser-tokenizer.ts   — character-level tokenizer
+ * - parser-token-stream.ts — token cursor
+ * - parser-style.ts       — style block parsing
+ * - parser-keywords.ts    — keyword-specific handlers
+ * - parser-core.ts        — line parsing, tree building, orchestration
+ */
 import { KernParseError } from './errors.js';
-import { isKnownNodeType } from './spec.js';
+import { parseInternal } from './parser-core.js';
 import { defaultRuntime } from './runtime.js';
 import { validateSchema } from './schema.js';
-// Parse diagnostics now live in defaultRuntime. This alias provides backward compatibility.
-const DIAGNOSTIC_SUGGESTIONS = {
-    UNCLOSED_EXPR: 'Close the `{{ ... }}` expression or move the unfinished code into a quoted string.',
-    UNCLOSED_STYLE: 'Close the `{ ... }` style block with `}` and keep any commas inside the block.',
-    UNCLOSED_STRING: 'Add the missing closing quote or escape any embedded quotes inside the string.',
-    UNEXPECTED_TOKEN: 'Remove the stray token or quote it so the parser can treat it as a value.',
-    EMPTY_DOCUMENT: 'Add at least one root KERN node such as `screen`, `view`, or `text`.',
-    INVALID_INDENT: 'Replace tabs with spaces so indentation is consistent across sibling nodes.',
-    UNKNOWN_NODE_TYPE: 'Rename this node to a supported KERN keyword or register it as an evolved node type.',
-    INDENT_JUMP: 'Align this line with an existing indentation level so the parent-child structure is unambiguous.',
-    DUPLICATE_PROP: 'Remove the duplicate property or merge the values into a single prop assignment.',
-    DROPPED_LINE: 'Rewrite this line so it starts with a valid KERN node type and move stray symbols into props.',
-};
-function createParseState() {
-    return { diagnostics: [] };
-}
-function commitParseState(state, runtime = defaultRuntime) {
-    runtime.lastParseDiagnostics = state.diagnostics.map(d => ({ ...d }));
-}
-function emitDiagnostic(state, code, severity, message, line, col, options = {}) {
-    state.diagnostics.push({
-        code,
-        severity,
-        message,
-        line,
-        col,
-        endCol: Math.max(options.endCol ?? (col + 1), col),
-        suggestion: options.suggestion ?? DIAGNOSTIC_SUGGESTIONS[code],
-    });
-}
-// ── Tokenizer ────────────────────────────────────────────────────────────
-function isIdentStart(ch) {
-    return (ch >= 'A' && ch <= 'Z') || (ch >= 'a' && ch <= 'z') || ch === '_';
-}
-function isIdentChar(ch) {
-    return isIdentStart(ch) || (ch >= '0' && ch <= '9') || ch === '-';
-}
-function isDigit(ch) {
-    return ch >= '0' && ch <= '9';
-}
-/** Character-by-character tokenizer for a single KERN line (after indent stripped). */
-function tokenizeLineInternal(line, state) {
-    const tokens = [];
-    let i = 0;
-    while (i < line.length) {
-        const ch = line[i];
-        // Whitespace
-        if (ch === ' ' || ch === '\t') {
-            const start = i;
-            while (i < line.length && (line[i] === ' ' || line[i] === '\t'))
-                i++;
-            tokens.push({ kind: 'whitespace', value: line.slice(start, i), pos: start });
-            continue;
-        }
-        // Expression block {{ ... }}
-        if (ch === '{' && i + 1 < line.length && line[i + 1] === '{') {
-            const start = i;
-            i += 2;
-            let depth = 1;
-            while (i < line.length - 1 && depth > 0) {
-                if (line[i] === '{' && line[i + 1] === '{') {
-                    depth++;
-                    i += 2;
-                }
-                else if (line[i] === '}' && line[i + 1] === '}') {
-                    depth--;
-                    if (depth === 0)
-                        break;
-                    i += 2;
-                }
-                else
-                    i++;
-            }
-            if (depth > 0) {
-                if (state) {
-                    emitDiagnostic(state, 'UNCLOSED_EXPR', 'error', `Unclosed expression block '{{' at column ${start + 1}`, 0, start + 1, { endCol: start + 3 });
-                }
-            }
-            const inner = line.slice(start + 2, i).trim();
-            if (i < line.length - 1)
-                i += 2;
-            else
-                i = line.length;
-            tokens.push({ kind: 'expr', value: inner, pos: start });
-            continue;
-        }
-        // Style block { ... } — find matching } respecting quotes
-        if (ch === '{') {
-            const start = i;
-            let inQuote = false;
-            let j = i + 1;
-            let closed = false;
-            while (j < line.length) {
-                if (line[j] === '\\' && j + 1 < line.length) {
-                    j += 2;
-                    continue;
-                }
-                if (line[j] === '"')
-                    inQuote = !inQuote;
-                if (!inQuote && line[j] === '}') {
-                    j++;
-                    closed = true;
-                    break;
-                }
-                j++;
-            }
-            if (!closed) {
-                if (state) {
-                    emitDiagnostic(state, 'UNCLOSED_STYLE', 'error', `Unclosed style block '{' at column ${start + 1}`, 0, start + 1, { endCol: start + 2 });
-                }
-            }
-            tokens.push({ kind: 'style', value: line.slice(start + 1, closed ? j - 1 : j), pos: start });
-            i = j;
-            continue;
-        }
-        // Quoted string "..." with \" escape support
-        if (ch === '"') {
-            const start = i;
-            i++;
-            let inner = '';
-            while (i < line.length && line[i] !== '"') {
-                if (line[i] === '\\' && i + 1 < line.length) {
-                    const next = line[i + 1];
-                    if (next === '"') {
-                        inner += '"';
-                        i += 2;
-                    }
-                    else if (next === '\\') {
-                        inner += '\\';
-                        i += 2;
-                    }
-                    else {
-                        inner += line[i];
-                        i++;
-                    }
-                }
-                else {
-                    inner += line[i];
-                    i++;
-                }
-            }
-            if (i >= line.length) {
-                if (state) {
-                    emitDiagnostic(state, 'UNCLOSED_STRING', 'error', `Unclosed quoted string at column ${start + 1}`, 0, start + 1, { endCol: start + 2 });
-                }
-            }
-            else {
-                i++; // skip closing quote
-            }
-            tokens.push({ kind: 'quoted', value: inner, pos: start });
-            continue;
-        }
-        // Theme ref $name
-        if (ch === '$' && i + 1 < line.length && isIdentStart(line[i + 1])) {
-            const start = i;
-            i++;
-            while (i < line.length && isIdentChar(line[i]))
-                i++;
-            tokens.push({ kind: 'themeRef', value: line.slice(start + 1, i), pos: start });
-            continue;
-        }
-        // Equals
-        if (ch === '=') {
-            tokens.push({ kind: 'equals', value: '=', pos: i });
-            i++;
-            continue;
-        }
-        // Comma
-        if (ch === ',') {
-            tokens.push({ kind: 'comma', value: ',', pos: i });
-            i++;
-            continue;
-        }
-        // Slash-prefixed path: /something
-        if (ch === '/') {
-            const start = i;
-            while (i < line.length && line[i] !== ' ' && line[i] !== '\t' && line[i] !== '{' && line[i] !== '$')
-                i++;
-            tokens.push({ kind: 'slash', value: line.slice(start, i), pos: start });
-            continue;
-        }
-        // Number (pure digits)
-        if (isDigit(ch)) {
-            const start = i;
-            while (i < line.length && isDigit(line[i]))
-                i++;
-            tokens.push({ kind: 'number', value: line.slice(start, i), pos: start });
-            continue;
-        }
-        // Identifier: [A-Za-z_][A-Za-z0-9_-]*
-        // Handles evolved: prefix (evolved:keyword → strips prefix, returns keyword)
-        if (isIdentStart(ch)) {
-            const start = i;
-            while (i < line.length && isIdentChar(line[i]))
-                i++;
-            if (line[i] === ':' && line.slice(start, i) === 'evolved' && i + 1 < line.length && isIdentStart(line[i + 1])) {
-                i++;
-                const nameStart = i;
-                while (i < line.length && isIdentChar(line[i]))
-                    i++;
-                tokens.push({ kind: 'identifier', value: line.slice(nameStart, i), pos: start });
-            }
-            else {
-                tokens.push({ kind: 'identifier', value: line.slice(start, i), pos: start });
-            }
-            continue;
-        }
-        // Unknown character
-        tokens.push({ kind: 'unknown', value: ch, pos: i });
-        i++;
-    }
-    return tokens;
-}
-export function tokenizeLine(line) {
-    return tokenizeLineInternal(line);
-}
-// ── Token stream ─────────────────────────────────────────────────────────
-// Opus: class-based cursor. Codex contribution: consumeAnyValue for evolved hints.
-class TokenStream {
-    tokens;
-    idx = 0;
-    constructor(tokens) { this.tokens = tokens; }
-    peek() { return this.tokens[this.idx]; }
-    next() { return this.tokens[this.idx++]; }
-    done() { return this.idx >= this.tokens.length; }
-    position() { return this.idx; }
-    setPosition(pos) { this.idx = pos; }
-    skipWS() {
-        while (this.idx < this.tokens.length && this.tokens[this.idx].kind === 'whitespace')
-            this.idx++;
-    }
-    /** Try to consume an identifier. Returns its value or null. */
-    tryIdent() {
-        if (this.idx < this.tokens.length && this.tokens[this.idx].kind === 'identifier') {
-            return this.tokens[this.idx++].value;
-        }
-        return null;
-    }
-    /** Try to consume a number token. Returns its value or null. */
-    tryNumber() {
-        if (this.idx < this.tokens.length && this.tokens[this.idx].kind === 'number') {
-            return this.tokens[this.idx++].value;
-        }
-        return null;
-    }
-    /** Check if the next non-WS token is an identifier followed by '='. */
-    isKeyValue() {
-        let j = this.idx;
-        while (j < this.tokens.length && this.tokens[j].kind === 'whitespace')
-            j++;
-        if (j >= this.tokens.length || this.tokens[j].kind !== 'identifier')
-            return false;
-        return j + 1 < this.tokens.length && this.tokens[j + 1].kind === 'equals';
-    }
-    /** Check if any remaining token contains '='. */
-    hasEquals() {
-        for (let j = this.idx; j < this.tokens.length; j++) {
-            if (this.tokens[j].kind === 'equals')
-                return true;
-        }
-        return false;
-    }
-    /** Check if there are more non-whitespace tokens. */
-    hasMore() {
-        let j = this.idx;
-        while (j < this.tokens.length && this.tokens[j].kind === 'whitespace')
-            j++;
-        return j < this.tokens.length;
-    }
-    /** Get remaining raw text from current position (for fallback / params). */
-    remainingRaw(line) {
-        if (this.idx >= this.tokens.length)
-            return '';
-        const startPos = this.tokens[this.idx].pos;
-        this.idx = this.tokens.length;
-        return line.slice(startPos);
-    }
-    /** Consume any single non-whitespace token as a value (for evolved positional args). */
-    consumeAnyValue() {
-        this.skipWS();
-        const tok = this.peek();
-        if (!tok || tok.kind === 'whitespace')
-            return undefined;
-        return this.next();
-    }
-}
-// ── Prop parsing (extracted from Codex's parsePropToken pattern) ──────────
-/** Map a value token to its JS representation. */
-function tokenValue(tok) {
-    if (tok.kind === 'expr')
-        return { __expr: true, code: tok.value };
-    if (tok.kind === 'quoted')
-        return tok.value;
-    return tok.value;
-}
-/** Try to parse a key=value prop from the stream. Returns true if consumed. */
-function parseProp(state, s, props, lineNum, col) {
-    if (!s.isKeyValue())
-        return false;
-    s.skipWS();
-    const keyTok = s.next();
-    const key = keyTok.value; // identifier
-    s.next(); // =
-    if (key in props) {
-        emitDiagnostic(state, 'DUPLICATE_PROP', 'warning', `Duplicate property '${key}' at line ${lineNum ?? 0}`, lineNum ?? 0, (col ?? 0) + keyTok.pos, {
-            endCol: (col ?? 0) + keyTok.pos + key.length,
-        });
-    }
-    const valTok = s.peek();
-    if (!valTok || valTok.kind === 'whitespace') {
-        props[key] = '';
-        return true;
-    }
-    // key={{expr}} or key="quoted"
-    if (valTok.kind === 'expr' || valTok.kind === 'quoted') {
-        props[key] = tokenValue(s.next());
-        return true;
-    }
-    // key=bareValue — collect tokens up to next WS/style/themeRef
-    let value = '';
-    while (!s.done()) {
-        const vt = s.peek();
-        if (vt.kind === 'whitespace' || vt.kind === 'style' || vt.kind === 'themeRef')
-            break;
-        value += vt.value;
-        s.next();
-    }
-    props[key] = value;
-    return true;
-}
-// defaultRuntime.multilineBlockTypes now lives in defaultRuntime.multilineBlockTypes
-// (initialized with 'logic', 'handler', 'cleanup', 'body' by the KernRuntime constructor).
-// ── Evolved Node Parser Hints (v4) ──────────────────────────────────────
-// ParserHintsConfig is now defined in runtime.ts. Parser hints live in defaultRuntime.
+export { tokenizeLine } from './parser-tokenizer.js';
+// ── Evolved Node Parser Hints ───────────────────────────────────────────
 /** Register parser hints for an evolved node type. */
 export function registerParserHints(keyword, hints) {
     defaultRuntime.registerParserHints(keyword, hints);
@@ -348,515 +27,41 @@ export function unregisterParserHints(keyword) {
 export function clearParserHints() {
     defaultRuntime.clearParserHints();
 }
-/** Consume a bare identifier into props if it's not a key=value pair. */
-function consumeBareIdent(s, props, propName) {
-    s.skipWS();
-    if (s.isKeyValue())
-        return;
-    const id = s.tryIdent();
-    if (id)
-        props[propName] = id;
-}
-const KEYWORD_HANDLERS = new Map([
-    ['theme', (s, props) => {
-            consumeBareIdent(s, props, 'name');
-        }],
-    ['import', (s, props) => {
-            s.skipWS();
-            const pos = s.position();
-            const id = s.tryIdent();
-            if (id === 'default') {
-                if (!s.done() && s.peek()?.kind !== 'equals') {
-                    props.default = true;
-                    s.skipWS();
-                }
-                else if (s.peek()?.kind === 'equals') {
-                    s.setPosition(pos);
-                    return;
-                }
-                else {
-                    props.default = true;
-                    return;
-                }
-            }
-            else if (id) {
-                s.setPosition(pos);
-            }
-            if (!s.isKeyValue()) {
-                s.skipWS();
-                const name = s.tryIdent();
-                if (name)
-                    props.name = name;
-            }
-        }],
-    ['route', (s, props) => {
-            s.skipWS();
-            const pos = s.position();
-            const verb = s.tryIdent();
-            if (verb && /^(GET|POST|PUT|DELETE|PATCH|HEAD|OPTIONS)$/i.test(verb)) {
-                props.method = verb.toLowerCase();
-                s.skipWS();
-                const tok = s.peek();
-                if (tok && tok.kind === 'slash') {
-                    props.path = tok.value;
-                    s.next();
-                }
-            }
-            else if (verb) {
-                s.setPosition(pos);
-            }
-        }],
-    ['params', (s, props, content) => {
-            s.skipWS();
-            const remaining = s.remainingRaw(content);
-            if (remaining.length > 0) {
-                const items = [];
-                const parts = remaining.split(',').map(p => p.trim()).filter(Boolean);
-                for (const part of parts) {
-                    const m = part.match(/^([A-Za-z_]\w*):([A-Za-z_]\w*(?:\[\])?)(?:\s*=\s*(.+))?$/);
-                    if (m) {
-                        const item = { name: m[1], type: m[2] };
-                        if (m[3] !== undefined)
-                            item.default = m[3].trim();
-                        items.push(item);
-                    }
-                }
-                props.items = items;
-            }
-        }],
-    ['auth', (s, props) => { consumeBareIdent(s, props, 'mode'); }],
-    ['validate', (s, props) => { consumeBareIdent(s, props, 'schema'); }],
-    ['error', (s, props) => {
-            s.skipWS();
-            const num = s.tryNumber();
-            if (num) {
-                props.status = parseInt(num, 10);
-                s.skipWS();
-                const tok = s.peek();
-                if (tok && tok.kind === 'quoted') {
-                    props.message = tok.value;
-                    s.next();
-                }
-            }
-        }],
-    ['derive', (s, props) => { consumeBareIdent(s, props, 'name'); }],
-    ['guard', (s, props) => { consumeBareIdent(s, props, 'name'); }],
-    ['effect', (s, props) => { consumeBareIdent(s, props, 'name'); }],
-    ['strategy', (s, props) => { consumeBareIdent(s, props, 'name'); }],
-    ['trigger', (s, props) => { consumeBareIdent(s, props, 'kind'); }],
-    ['respond', (s, props) => {
-            s.skipWS();
-            const num = s.tryNumber();
-            if (num)
-                props.status = parseInt(num, 10);
-        }],
-    // Rule syntax — native .kern lint rules
-    ['rule', (s, props) => {
-            // rule id severity=error category=bug confidence=0.9
-            consumeBareIdent(s, props, 'id');
-        }],
-    ['message', (s, props) => {
-            // message "template with {{interpolation}}"
-            s.skipWS();
-            const tok = s.peek();
-            if (tok && tok.kind === 'quoted') {
-                props.template = tok.value;
-                s.next();
-            }
-        }],
-    ['middleware', (s, props, content) => {
-            s.skipWS();
-            if (!s.hasMore())
-                return;
-            if (s.hasEquals())
-                return;
-            const remaining = s.remainingRaw(content).trim();
-            if (remaining.length > 0) {
-                const names = remaining.split(',').map(n => n.trim()).filter(Boolean);
-                if (names.length > 1) {
-                    props.names = names;
-                }
-                else if (names.length === 1) {
-                    props.name = names[0];
-                }
-            }
-        }],
-]);
-// ── parseLine (token-based) ──────────────────────────────────────────────
-function parseLine(state, raw, lineNum, runtime = defaultRuntime) {
-    if (raw.trim() === '')
-        return null;
-    const indent = raw.search(/\S/);
-    const indentText = raw.slice(0, indent);
-    const content = raw.slice(indent);
-    const col = indent + 1;
-    if (indentText.includes('\t')) {
-        emitDiagnostic(state, 'INVALID_INDENT', 'warning', `Tab indentation at line ${lineNum}`, lineNum, 1, {
-            endCol: indent + 1,
-        });
-    }
-    const diagBefore = state.diagnostics.length;
-    const tokens = tokenizeLineInternal(content, state);
-    for (let d = diagBefore; d < state.diagnostics.length; d++) {
-        if (state.diagnostics[d].line === 0)
-            state.diagnostics[d].line = lineNum;
-        state.diagnostics[d].col += indent;
-        state.diagnostics[d].endCol += indent;
-    }
-    const s = new TokenStream(tokens);
-    // First token must be an identifier (the node type)
-    const typeToken = s.tryIdent();
-    if (!typeToken) {
-        const firstToken = tokens.find(tok => tok.kind !== 'whitespace');
-        if (firstToken) {
-            emitDiagnostic(state, 'DROPPED_LINE', 'error', `Dropped line ${lineNum}: expected a node type at the start of the line`, lineNum, col + firstToken.pos, {
-                endCol: col + content.length,
-            });
-        }
-        return null;
-    }
-    const type = typeToken;
-    if (!isKnownNodeType(type, runtime) && !runtime.multilineBlockTypes.has(type) && !runtime.isTemplateNode(type)) {
-        emitDiagnostic(state, 'UNKNOWN_NODE_TYPE', 'warning', `Unknown node type '${type}' at line ${lineNum}`, lineNum, col, {
-            endCol: col + type.length,
-        });
-    }
-    const props = {};
-    const styles = {};
-    const pseudoStyles = {};
-    const themeRefs = [];
-    // ── Evolved node parser hints (v4) ──────────────────────────────────
-    const evolvedHints = runtime.parserHints.get(type);
-    if (evolvedHints) {
-        if (evolvedHints.positionalArgs) {
-            for (const argName of evolvedHints.positionalArgs) {
-                const tok = s.consumeAnyValue();
-                if (tok)
-                    props[argName] = tok.value;
-            }
-        }
-        if (evolvedHints.bareWord) {
-            s.skipWS();
-            if (!s.isKeyValue()) {
-                const id = s.tryIdent();
-                if (id)
-                    props[evolvedHints.bareWord] = id;
-            }
-        }
-    }
-    // ── Keyword-specific handling ──────────────────────────────────────
-    const handler = KEYWORD_HANDLERS.get(type);
-    if (handler)
-        handler(s, props, content);
-    // ── Generic prop/style/theme parsing ───────────────────────────────
-    while (!s.done()) {
-        s.skipWS();
-        if (s.done())
-            break;
-        const tok = s.peek();
-        // Style block
-        if (tok.kind === 'style') {
-            parseStyleBlock(tok.value, styles, pseudoStyles);
-            s.next();
-            continue;
-        }
-        // Theme ref
-        if (tok.kind === 'themeRef') {
-            themeRefs.push(tok.value);
-            s.next();
-            continue;
-        }
-        // Key=value prop (extracted helper from Codex)
-        if (parseProp(state, s, props, lineNum, col))
-            continue;
-        // Unknown token — skip with warning
-        const skipped = s.next();
-        const errCol = col + skipped.pos;
-        emitDiagnostic(state, 'UNEXPECTED_TOKEN', 'warning', `Unexpected token "${skipped.value}" at line ${lineNum}:${errCol}`, lineNum, errCol, {
-            endCol: errCol + skipped.value.length,
-        });
-    }
-    return {
-        indent,
-        rawLength: content.length,
-        type,
-        props,
-        styles,
-        pseudoStyles,
-        themeRefs,
-        loc: { line: lineNum, col, endLine: lineNum, endCol: col + content.length },
-    };
-}
-// ── Style block parsing (unchanged) ──────────────────────────────────────
-function splitStylePairs(block) {
-    const pairs = [];
-    let current = '';
-    let inQuote = false;
-    let parenDepth = 0;
-    for (let i = 0; i < block.length; i++) {
-        const ch = block[i];
-        if (ch === '\\' && i + 1 < block.length) {
-            current += ch + block[i + 1];
-            i++;
-        }
-        else if (ch === '"') {
-            inQuote = !inQuote;
-            current += ch;
-        }
-        else if (!inQuote && ch === '(') {
-            parenDepth++;
-            current += ch;
-        }
-        else if (!inQuote && ch === ')') {
-            parenDepth--;
-            current += ch;
-        }
-        else if (!inQuote && parenDepth === 0 && ch === ',') {
-            if (current.trim())
-                pairs.push(current.trim());
-            current = '';
-        }
-        else {
-            current += ch;
-        }
-    }
-    if (current.trim())
-        pairs.push(current.trim());
-    return pairs;
-}
-function parseStyleBlock(block, styles, pseudoStyles) {
-    const pairs = splitStylePairs(block);
-    for (const pair of pairs) {
-        // Pseudo-selector: :press:bg:#005BB5
-        const pseudoMatch = pair.match(/^:([a-z]+):([A-Za-z0-9_-]+):(.+)$/);
-        if (pseudoMatch) {
-            const [, pseudo, key, value] = pseudoMatch;
-            if (!pseudoStyles[pseudo])
-                pseudoStyles[pseudo] = {};
-            pseudoStyles[pseudo][key] = value.trim();
-            continue;
-        }
-        // Quoted key: "backdrop-filter":"blur(8px)"
-        const quotedKeyMatch = pair.match(/^"([^"]+)"\s*:\s*(.*)/);
-        if (quotedKeyMatch) {
-            const key = quotedKeyMatch[1];
-            let value = quotedKeyMatch[2].trim();
-            if (value.startsWith('"') && value.endsWith('"')) {
-                value = value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
-            }
-            styles[key] = value;
-            continue;
-        }
-        // Normal: key:value (value may be quoted)
-        const colonIdx = pair.indexOf(':');
-        if (colonIdx > 0) {
-            const key = pair.slice(0, colonIdx).trim();
-            let value = pair.slice(colonIdx + 1).trim();
-            if (value.startsWith('"') && value.endsWith('"')) {
-                value = value.slice(1, -1).replace(/\\"/g, '"').replace(/\\\\/g, '\\');
-            }
-            styles[key] = value;
-        }
-    }
-}
-function expandMinified(source) {
-    if (!source.includes('(') || source.split('\n').length > 1)
-        return source;
-    const result = [];
-    let depth = 0;
-    let current = '';
-    let inQuote = false;
-    let inBraces = 0;
-    for (let i = 0; i < source.length; i++) {
-        const ch = source[i];
-        if (ch === '"') {
-            inQuote = !inQuote;
-            current += ch;
-            continue;
-        }
-        if (inQuote) {
-            current += ch;
-            continue;
-        }
-        if (ch === '{') {
-            inBraces++;
-            current += ch;
-            continue;
-        }
-        if (ch === '}') {
-            inBraces--;
-            current += ch;
-            continue;
-        }
-        if (inBraces > 0) {
-            current += ch;
-            continue;
-        }
-        if (ch === '(') {
-            result.push('  '.repeat(depth) + current.trim());
-            current = '';
-            depth++;
-        }
-        else if (ch === ')') {
-            if (current.trim())
-                result.push('  '.repeat(depth) + current.trim());
-            current = '';
-            depth--;
-        }
-        else if (ch === ',' && inBraces === 0) {
-            if (current.trim())
-                result.push('  '.repeat(depth) + current.trim());
-            current = '';
-        }
-        else {
-            current += ch;
-        }
-    }
-    if (current.trim())
-        result.push('  '.repeat(depth) + current.trim());
-    return result.join('\n');
-}
-/** Get warnings from the last parse() call */
+// ── Diagnostics API ─────────────────────────────────────────────────────
+/**
+ * Get diagnostic messages from the last parse() call as plain strings.
+ *
+ * @remarks Returns messages for all severities (error, warning, info).
+ * For structured diagnostics with severity filtering, use {@link getParseDiagnostics}.
+ */
 export function getParseWarnings() {
-    return defaultRuntime.lastParseDiagnostics.map(d => d.message);
+    return defaultRuntime.lastParseDiagnostics.map((d) => d.message);
 }
-// ── Shared parse helpers ─────────────────────────────────────────────────
-/** Process source lines into ParsedLine entries (multiline blocks + regular lines). */
-function parseLines(state, source, runtime = defaultRuntime) {
-    const lines = expandMinified(source).split('\n');
-    const parsed = [];
-    for (let i = 0; i < lines.length; i++) {
-        const trimmed = lines[i].trimStart();
-        const multilineType = [...runtime.multilineBlockTypes].find(type => trimmed.startsWith(`${type} <<<`));
-        if (multilineType) {
-            const indent = lines[i].search(/\S/);
-            const codeLines = [];
-            const startLine = i + 1;
-            const blockOpen = `${multilineType} <<<`;
-            const afterOpen = trimmed.slice(blockOpen.length);
-            let closed = false;
-            if (afterOpen.includes('>>>')) {
-                closed = true;
-                codeLines.push(afterOpen.split('>>>')[0]);
-            }
-            else {
-                i++;
-                while (i < lines.length && !lines[i].trimStart().startsWith('>>>')) {
-                    codeLines.push(lines[i]);
-                    i++;
-                }
-                if (i < lines.length) {
-                    closed = true;
-                    const closeLine = lines[i];
-                    const closeIdx = closeLine.indexOf('>>>');
-                    if (closeIdx > 0) {
-                        const before = closeLine.slice(0, closeIdx).trim();
-                        if (before)
-                            codeLines.push(before);
-                    }
-                }
-            }
-            if (!closed) {
-                emitDiagnostic(state, 'UNEXPECTED_TOKEN', 'error', `Unclosed multiline block '${multilineType} <<<' at line ${startLine}`, startLine, indent + 1, {
-                    endCol: indent + 1 + blockOpen.length,
-                    suggestion: `Close the '${multilineType} <<<' block with a matching '>>>' marker before the file ends.`,
-                });
-            }
-            parsed.push({
-                indent,
-                rawLength: lines[startLine - 1].slice(indent).length,
-                type: multilineType,
-                props: { code: codeLines.join('\n').replace(/^\n+|\n+$/g, '') },
-                styles: {},
-                pseudoStyles: {},
-                themeRefs: [],
-                loc: {
-                    line: startLine,
-                    col: indent + 1,
-                    endLine: startLine,
-                    endCol: indent + 1 + lines[startLine - 1].slice(indent).length,
-                },
-            });
-            continue;
-        }
-        const p = parseLine(state, lines[i], i + 1, runtime);
-        if (p)
-            parsed.push(p);
-    }
-    return parsed;
-}
-/** Convert a ParsedLine to an IRNode (no children yet). */
-function toNode(p) {
-    const node = {
-        type: p.type,
-        loc: p.loc,
-        props: { ...p.props },
-        children: [],
-    };
-    if (Object.keys(p.styles).length > 0)
-        node.props.styles = p.styles;
-    if (Object.keys(p.pseudoStyles).length > 0)
-        node.props.pseudoStyles = p.pseudoStyles;
-    if (p.themeRefs.length > 0)
-        node.props.themeRefs = p.themeRefs;
-    return node;
-}
-/** Build a tree from parsed lines using indent-based stack. */
-function buildTree(state, parsed, root, rootIndent) {
-    const stack = [{ node: root, indent: rootIndent }];
-    const seenIndents = new Set([rootIndent]);
-    for (let i = 0; i < parsed.length; i++) {
-        const p = parsed[i];
-        const node = toNode(p);
-        if (p.indent < (stack[stack.length - 1]?.indent ?? 0) && !seenIndents.has(p.indent)) {
-            emitDiagnostic(state, 'INDENT_JUMP', 'warning', `Dedent to unseen indent level ${p.indent} at line ${p.loc.line}`, p.loc.line, p.loc.col, {
-                endCol: p.loc.col + p.type.length,
-            });
-        }
-        while (stack.length > 1 && stack[stack.length - 1].indent >= p.indent) {
-            stack.pop();
-        }
-        seenIndents.add(p.indent);
-        const parent = stack[stack.length - 1].node;
-        if (!parent.children)
-            parent.children = [];
-        parent.children.push(node);
-        stack.push({ node, indent: p.indent });
-    }
+/** Get structured diagnostics from the last parse() call. */
+export function getParseDiagnostics(runtime) {
+    const rt = runtime ?? defaultRuntime;
+    return [...rt.lastParseDiagnostics];
 }
-// ── Public parse API ─────────────────────────────────────────────────────
+// ── Public parse API ────────────────────────────────────────────────────
 /**
- * Parse KERN source into an IR tree. The first node becomes the root.
- * WARNING: For multi-root content (e.g., multiple `rule` definitions),
- * use `parseDocument()` instead — this function treats subsequent
- * top-level nodes as children of the first node.
- * @see parseDocument
+ * Parse KERN source into an IR node tree.
+ *
+ * Recovers from errors gracefully — malformed lines produce `DROPPED_LINE`
+ * diagnostics but never throw. Use {@link parseStrict} if you want errors to throw.
+ *
+ * @param source - KERN indentation-based source text
+ * @param runtime - Optional KernRuntime instance for isolation (defaults to shared singleton)
+ * @returns Root IRNode of the parsed tree
+ *
+ * @example
+ * ```ts
+ * const root = parse('page "Home"\n  text "Hello"');
+ * // root.type === 'page', root.children[0].type === 'text'
+ * ```
+ *
+ * @see {@link parseWithDiagnostics} to also receive parse diagnostics
+ * @see {@link parseStrict} to throw on errors
  */
-function parseInternal(source, asDocument, runtime) {
-    const rt = runtime ?? defaultRuntime;
-    const state = createParseState();
-    const parsed = parseLines(state, source, rt);
-    if (parsed.length === 0) {
-        if (source.trim() === '') {
-            emitDiagnostic(state, 'EMPTY_DOCUMENT', 'info', 'Source document is empty', 1, 1, { endCol: 1 });
-        }
-        const root = { type: 'document', children: [], loc: { line: 1, col: 1, endLine: 1, endCol: 1 } };
-        commitParseState(state, rt);
-        return { root, diagnostics: [...state.diagnostics] };
-    }
-    let root;
-    if (asDocument) {
-        root = { type: 'document', children: [], loc: { line: 1, col: 1 } };
-        buildTree(state, parsed, root, -1);
-    }
-    else {
-        root = toNode(parsed[0]);
-        buildTree(state, parsed.slice(1), root, parsed[0].indent);
-    }
-    computeEndSpans(root);
-    commitParseState(state, rt);
-    return { root, diagnostics: [...state.diagnostics] };
-}
 export function parse(source, runtime) {
     return parseInternal(source, false, runtime).root;
 }
@@ -868,29 +73,16 @@ export function parse(source, runtime) {
 export function parseDocument(source, runtime) {
     return parseInternal(source, true, runtime).root;
 }
-/** Recursively compute endLine/endCol for each node based on its last child. */
-function computeEndSpans(node) {
-    if (node.children && node.children.length > 0) {
-        for (const child of node.children)
-            computeEndSpans(child);
-        const lastChild = node.children[node.children.length - 1];
-        if (lastChild.loc && node.loc) {
-            node.loc.endLine = lastChild.loc.endLine ?? lastChild.loc.line;
-            node.loc.endCol = lastChild.loc.endCol ?? lastChild.loc.col;
-        }
-    }
-    else if (node.loc) {
-        node.loc.endLine = node.loc.endLine ?? node.loc.line;
-        node.loc.endCol = node.loc.endCol ?? node.loc.col;
-    }
-}
-// ── Diagnostics API ──────────────────────────────────────────────────────
-/** Get structured diagnostics from the last parse() call. */
-export function getParseDiagnostics(runtime) {
-    const rt = runtime ?? defaultRuntime;
-    return [...rt.lastParseDiagnostics];
-}
-/** Parse with diagnostics — returns both tree and structured diagnostics. */
+/**
+ * Parse KERN source and return both the IR tree and structured diagnostics.
+ *
+ * Unlike {@link parse}, this returns a {@link ParseResult} containing the full
+ * diagnostics array, useful for editor integrations and lint-style reporting.
+ *
+ * @param source - KERN indentation-based source text
+ * @param runtime - Optional KernRuntime instance for isolation
+ * @returns `{ root: IRNode, diagnostics: ParseDiagnostic[] }`
+ */
 export function parseWithDiagnostics(source, runtime) {
     return parseInternal(source, false, runtime);
 }
@@ -898,10 +90,18 @@ export function parseWithDiagnostics(source, runtime) {
 export function parseDocumentWithDiagnostics(source, runtime) {
     return parseInternal(source, true, runtime);
 }
-/** Strict parse — throws KernParseError if any diagnostic has severity=error or schema violation. */
+/**
+ * Strict parse — throws if any diagnostic has severity `'error'` or a schema violation is found.
+ *
+ * @param source - KERN indentation-based source text
+ * @param runtime - Optional KernRuntime instance for isolation
+ * @returns Root IRNode of the parsed tree
+ * @throws {KernParseError} When the source contains errors or schema violations.
+ *   The error includes a code frame and the full diagnostics array.
+ */
 export function parseStrict(source, runtime) {
     const { root, diagnostics } = parseWithDiagnostics(source, runtime);
-    const errors = diagnostics.filter(d => d.severity === 'error');
+    const errors = diagnostics.filter((d) => d.severity === 'error');
     if (errors.length > 0) {
         const first = errors[0];
         const err = new KernParseError(first.message, first.line, first.col, source);
@@ -921,7 +121,7 @@ export function parseStrict(source, runtime) {
 /** Strict document parse — throws KernParseError if any diagnostic has severity=error or schema violation. */
 export function parseDocumentStrict(source, runtime) {
     const { root, diagnostics } = parseDocumentWithDiagnostics(source, runtime);
-    const errors = diagnostics.filter(d => d.severity === 'error');
+    const errors = diagnostics.filter((d) => d.severity === 'error');
     if (errors.length > 0) {
         const first = errors[0];
         const err = new KernParseError(first.message, first.line, first.col, source);