@fuzdev/fuz_ui 0.198.0 → 0.199.0

package/dist/mdz_opcodes_to_nodes.js

@@ -0,0 +1,332 @@
+/**
+ * Converts a stream of mdz opcodes to the `MdzNode[]` tree representation.
+ *
+ * Stack-based replay: `open` pushes a frame, `close` pops and builds the node,
+ * `text`/`void` create leaf nodes, `append_text` extends the last text node,
+ * `revert` undoes an optimistic open and re-parents children.
+ *
+ * The output is identical to `mdz_parse()` from `mdz.ts`, enabling
+ * validation of the streaming parser against the existing fixture suite.
+ *
+ * @module
+ */
+import { DEV } from 'esm-env';
+import { extract_single_tag, mdz_heading_id, mdz_merge_adjacent_text, mdz_push_merging_text, } from './mdz_helpers.js';
+/**
+ * Convert an array of mdz opcodes to the `MdzNode[]` tree.
+ * Produces output identical to `mdz_parse()`.
+ */
+export const mdz_opcodes_to_nodes = (opcodes) => {
+    const root = [];
+    const stack = [];
+    // index node IDs to their text content (for append_text and wrap)
+    const text_nodes = new Map();
+    // track which children array contains each text node (for wrap)
+    const node_parents = new Map();
+    const target = () => {
+        return stack.length > 0 ? stack[stack.length - 1].children : root;
+    };
+    for (const op of opcodes) {
+        switch (op.type) {
+            case 'open': {
+                stack.push({
+                    id: op.id,
+                    node_type: op.node_type,
+                    children: [],
+                    start: op.start,
+                    level: op.level,
+                    name: op.name,
+                    lang: op.lang,
+                });
+                break;
+            }
+            case 'close': {
+                if (DEV && stack.length === 0) {
+                    throw new Error(`mdz_opcodes_to_nodes: close for id ${op.id} but stack is empty`);
+                }
+                const frame = stack.pop();
+                if (!frame)
+                    break;
+                // discard signal: the parser determined this node and its descendants
+                // should not appear in the tree (e.g. whitespace-only paragraph)
+                if (op.discard)
+                    break;
+                // apply deferred metadata
+                frame.end = op.end;
+                if (op.reference !== undefined)
+                    frame.reference = op.reference;
+                if (op.link_type !== undefined)
+                    frame.link_type = op.link_type;
+                if (op.heading_id !== undefined)
+                    frame.heading_id = op.heading_id;
+                const node = build_node(frame);
+                if (node)
+                    target().push(node);
+                break;
+            }
+            case 'text': {
+                const node = op.text_type === 'Code'
+                    ? { type: 'Code', content: op.content, start: op.start, end: op.end }
+                    : { type: 'Text', content: op.content, start: op.start, end: op.end };
+                text_nodes.set(op.id, node);
+                const dest = target();
+                dest.push(node);
+                node_parents.set(op.id, dest);
+                break;
+            }
+            case 'append_text': {
+                if (DEV && !text_nodes.has(op.id)) {
+                    throw new Error(`mdz_opcodes_to_nodes: append_text for unknown id ${op.id}`);
+                }
+                const existing = text_nodes.get(op.id);
+                if (existing) {
+                    existing.content += op.content;
+                    existing.end += op.content.length;
+                }
+                break;
+            }
+            case 'trim_text': {
+                if (DEV && !text_nodes.has(op.id)) {
+                    throw new Error(`mdz_opcodes_to_nodes: trim_text for unknown id ${op.id}`);
+                }
+                const existing = text_nodes.get(op.id);
+                if (existing) {
+                    existing.content = existing.content.slice(0, existing.content.length - op.count);
+                    existing.end -= op.count;
+                    if (existing.content.length === 0) {
+                        const parent = node_parents.get(op.id);
+                        if (parent) {
+                            const idx = parent.indexOf(existing);
+                            if (idx !== -1)
+                                parent.splice(idx, 1);
+                        }
+                        text_nodes.delete(op.id);
+                        node_parents.delete(op.id);
+                    }
+                }
+                break;
+            }
+            case 'void': {
+                target().push({ type: 'Hr', start: op.start, end: op.end });
+                break;
+            }
+            case 'revert': {
+                // find and remove the reverted node's frame from the stack.
+                // fast path: reverts from #revert_all_optimistic always target the
+                // top of stack, so check that first to avoid splice + array alloc.
+                let reverted_frame = null;
+                if (stack.length > 0 && stack[stack.length - 1].id === op.id) {
+                    reverted_frame = stack.pop();
+                }
+                else {
+                    for (let i = stack.length - 1; i >= 0; i--) {
+                        if (stack[i].id === op.id) {
+                            reverted_frame = stack.splice(i, 1)[0];
+                            break;
+                        }
+                    }
+                }
+                if (DEV && !reverted_frame) {
+                    throw new Error(`mdz_opcodes_to_nodes: revert for id ${op.id} but not found on stack`);
+                }
+                if (reverted_frame) {
+                    if (op.wrap_node_type != null && op.wrap_id != null) {
+                        // block-level revert: wrap content in a new container (e.g. Paragraph)
+                        // and push it onto the stack so future opcodes flow into it.
+                        const wrapper = {
+                            id: op.wrap_id,
+                            node_type: op.wrap_node_type,
+                            children: [],
+                            start: op.start,
+                        };
+                        if (op.replacement_text) {
+                            mdz_push_merging_text(wrapper.children, {
+                                type: 'Text',
+                                content: op.replacement_text,
+                                start: op.start,
+                                end: op.start + op.replacement_text.length,
+                            });
+                        }
+                        for (const child of reverted_frame.children) {
+                            mdz_push_merging_text(wrapper.children, child);
+                        }
+                        stack.push(wrapper);
+                    }
+                    else {
+                        const dest = target();
+                        // Re-parent replacement text and children, coalescing adjacent
+                        // Text nodes inline. This reduces deeply nested reverts from
+                        // O(n²) array pushes to O(n) string concatenations — each revert
+                        // merges into the parent's last text node instead of growing the array.
+                        if (op.replacement_text) {
+                            mdz_push_merging_text(dest, {
+                                type: 'Text',
+                                content: op.replacement_text,
+                                start: op.start,
+                                end: op.start + op.replacement_text.length,
+                            });
+                        }
+                        for (const child of reverted_frame.children) {
+                            mdz_push_merging_text(dest, child);
+                        }
+                    }
+                }
+                break;
+            }
+            case 'wrap': {
+                const text_node = text_nodes.get(op.target_id);
+                const parent_children = node_parents.get(op.target_id);
+                if (!text_node || !parent_children)
+                    break;
+                const idx = parent_children.indexOf(text_node);
+                if (idx === -1)
+                    break;
+                // handle trailing punctuation trim
+                let trimmed_node = null;
+                if (op.trim_end && op.trim_end > 0 && op.trim_id != null) {
+                    const trimmed_content = text_node.content.slice(text_node.content.length - op.trim_end);
+                    text_node.content = text_node.content.slice(0, text_node.content.length - op.trim_end);
+                    text_node.end -= op.trim_end;
+                    trimmed_node = {
+                        type: 'Text',
+                        content: trimmed_content,
+                        start: text_node.end,
+                        end: text_node.end + trimmed_content.length,
+                    };
+                    text_nodes.set(op.trim_id, trimmed_node);
+                    node_parents.set(op.trim_id, parent_children);
+                }
+                // create Link wrapping the text node
+                const link = {
+                    type: 'Link',
+                    reference: op.reference,
+                    children: [text_node],
+                    link_type: op.link_type,
+                    start: op.start,
+                    end: op.end,
+                };
+                // replace text node with [Link, trimmed?] in parent
+                if (trimmed_node) {
+                    parent_children.splice(idx, 1, link, trimmed_node);
+                }
+                else {
+                    parent_children[idx] = link;
+                }
+                node_parents.delete(op.target_id);
+                break;
+            }
+        }
+    }
+    return root;
+};
+/**
+ * Build an `MdzNode` from a completed stack frame.
+ */
+const build_node = (frame) => {
+    switch (frame.node_type) {
+        case 'Paragraph': {
+            const children = mdz_merge_adjacent_text(frame.children);
+            if (children.length === 0)
+                return null;
+            // extract single tag (MDX convention)
+            const single_tag = extract_single_tag(children);
+            if (single_tag)
+                return single_tag;
+            return {
+                type: 'Paragraph',
+                children,
+                start: children[0].start,
+                end: children[children.length - 1].end,
+            };
+        }
+        case 'Heading': {
+            const children = mdz_merge_adjacent_text(frame.children);
+            const id = frame.heading_id ?? mdz_heading_id(children);
+            return {
+                type: 'Heading',
+                level: frame.level ?? 1,
+                id,
+                children,
+                start: frame.start,
+                end: frame.end,
+            };
+        }
+        case 'Bold':
+            return {
+                type: 'Bold',
+                children: mdz_merge_adjacent_text(frame.children),
+                start: frame.start,
+                end: frame.end,
+            };
+        case 'Italic':
+            return {
+                type: 'Italic',
+                children: mdz_merge_adjacent_text(frame.children),
+                start: frame.start,
+                end: frame.end,
+            };
+        case 'Strikethrough':
+            return {
+                type: 'Strikethrough',
+                children: mdz_merge_adjacent_text(frame.children),
+                start: frame.start,
+                end: frame.end,
+            };
+        case 'Link':
+            return {
+                type: 'Link',
+                reference: frame.reference ?? '',
+                children: mdz_merge_adjacent_text(frame.children),
+                link_type: frame.link_type ?? 'internal',
+                start: frame.start,
+                end: frame.end,
+            };
+        case 'Code': {
+            // optimistic inline code container — concatenate children text into leaf MdzCodeNode
+            let content = '';
+            for (const c of frame.children) {
+                if (c.type === 'Text')
+                    content += c.content;
+            }
+            return {
+                type: 'Code',
+                content,
+                start: frame.start,
+                end: frame.end,
+            };
+        }
+        case 'Codeblock': {
+            // code block content is in children as text
+            let content = '';
+            for (const c of frame.children) {
+                if (c.type === 'Text')
+                    content += c.content;
+            }
+            return {
+                type: 'Codeblock',
+                lang: frame.lang ?? null,
+                content,
+                start: frame.start,
+                end: frame.end,
+            };
+        }
+        case 'Element':
+            return {
+                type: 'Element',
+                name: frame.name ?? '',
+                children: mdz_merge_adjacent_text(frame.children),
+                start: frame.start,
+                end: frame.end,
+            };
+        case 'Component':
+            return {
+                type: 'Component',
+                name: frame.name ?? '',
+                children: mdz_merge_adjacent_text(frame.children),
+                start: frame.start,
+                end: frame.end,
+            };
+        default:
+            return null;
+    }
+};

package/dist/mdz_stream_parser.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Streaming opcode parser for mdz.
+ *
+ * Fed chunks of text (e.g., from LLM output), emits opcodes as rendering
+ * instructions. Makes optimistic assumptions about ambiguous syntax and
+ * emits `revert` opcodes to correct when wrong. Never re-parses.
+ *
+ * The design was independently arrived at but shares goals with
+ * {@link https://bsky.app/profile/pngwn.at/post/3mi527zntb22n @pngwn.at}'s
+ * Penguin-Flavoured Markdown (PFM): restrict the syntax so streaming is tractable,
+ * render optimistically and correct when wrong, emit serializable opcodes
+ * to avoid re-parsing, and keep the opcodes target-agnostic so any renderer
+ * can consume them. mdz diverges in one respect: the Svelte consumer
+ * (`MdzStreamState`) does build a reactive tree from opcodes — the platform
+ * dictates this — but mutations are fine-grained via `$state`, not diffed.
+ *
+ * The parser is split across sibling modules: this file holds the public
+ * `MdzStreamParser` class and the `process_loop` / `process_inline`
+ * orchestrators. Per-category handlers (block / inline / link / url / text)
+ * live in `mdz_stream_parser_*.ts` as free functions taking the shared
+ * `MdzStreamParserState` as first argument.
+ *
+ * Usage:
+ * ```ts
+ * const parser = new MdzStreamParser();
+ * parser.feed('hello **bold');
+ * const ops1 = parser.take_opcodes(); // open Paragraph, text "hello ", open Bold, text "bold"
+ * parser.feed('** world');
+ * const ops2 = parser.take_opcodes(); // close Bold, text " world"
+ * parser.finish();
+ * const ops3 = parser.take_opcodes(); // close Paragraph
+ * ```
+ *
+ * @module
+ */
+import type { MdzOpcode } from './mdz_opcodes.js';
+/**
+ * Streaming opcode parser for mdz content.
+ * Feed chunks via `feed()`, retrieve opcodes via `take_opcodes()`, call `finish()` at end.
+ *
+ * The opcode sequence is not deterministic across chunk boundaries — the same input
+ * fed in different chunk sizes may produce different `text`/`append_text` splits and
+ * different optimistic/revert sequences. The final tree (via `mdz_opcodes_to_nodes`)
+ * matches the one-shot result for all input except one case: italic (`_..._`) where
+ * the opening and closing delimiters straddle a chunk boundary. Italic is
+ * non-optimistic — it requires a confirmed closer in the buffer — so when the
+ * closer arrives only in a later chunk, the opening `_` has already been emitted
+ * as text and italic cannot apply retroactively. See `try_italic` in
+ * `mdz_stream_parser_inline.ts`.
+ */
+export declare class MdzStreamParser {
+    #private;
+    /**
+     * Feed a chunk of text to the parser.
+     * Opcodes are accumulated and retrieved via `take_opcodes()`.
+     */
+    feed(chunk: string): void;
+    /**
+     * Signal end of input. Resolves all pending state: closes open blocks,
+     * reverts unclosed optimistic opens, trims trailing newlines.
+     *
+     * Trailing-newline trimming is handled in one place: `trim_trailing_newline()`
+     * called at the top of `close_paragraph()` and `close_codeblock_at_eof()`,
+     * before either function reverts its inner stack. The trim sees the
+     * just-flushed text node's `last_text_id` (or a still-accumulated `\n`) and
+     * emits a `trim_text` opcode. Revert opcodes only fire after.
+     *
+     * Optimistic-container revert is handled by `close_paragraph` and
+     * `close_heading` (each pops its own inner stack), so no separate
+     * `revert_all_optimistic` is needed — optimistic containers can only exist
+     * inside an open Paragraph or Heading (parser invariant).
+     */
+    finish(): void;
+    /**
+     * Drain and return all accumulated opcodes.
+     * Destructive — empties the internal queue. The returned array is owned by the caller.
+     */
+    take_opcodes(): Array<MdzOpcode>;
+}
+//# sourceMappingURL=mdz_stream_parser.d.ts.map

package/dist/mdz_stream_parser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdz_stream_parser.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz_stream_parser.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG;AAEH,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,kBAAkB,CAAC;AAgEhD;;;;;;;;;;;;;GAaG;AACH,qBAAa,eAAe;;IAG3B;;;OAGG;IACH,IAAI,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAczB;;;;;;;;;;;;;;OAcG;IACH,MAAM,IAAI,IAAI;IA0Bd;;;OAGG;IACH,YAAY,IAAI,KAAK,CAAC,SAAS,CAAC;CAKhC"}