@fuzdev/fuz_ui 0.198.1 → 0.200.0

package/dist/mdz_opcodes.d.ts

@@ -0,0 +1,174 @@
+/**
+ * Opcode types for the mdz streaming parser.
+ *
+ * Opcodes are serializable rendering instructions emitted by `MdzStreamParser`.
+ * They tell a renderer what to do next — open a container, append text, close it,
+ * or revert an optimistic assumption. Target-agnostic: works for HTML, Svelte, PDF, etc.
+ *
+ * The parser makes optimistic assumptions about ambiguous syntax (e.g., `**` is probably bold)
+ * and emits `revert` opcodes to correct when wrong. This enables true streaming rendering
+ * without ever re-parsing.
+ *
+ * @module
+ */
+/**
+ * Unique monotonic identifier for each node created by the parser.
+ * IDs are never reused within a parser instance.
+ */
+export type MdzNodeId = number;
+/** Node types that can be opened as containers. */
+export type MdzContainerNodeType = 'Paragraph' | 'Bold' | 'Italic' | 'Strikethrough' | 'Link' | 'Heading' | 'Element' | 'Component' | 'Codeblock' | 'Code';
+/** Node types for self-contained leaf elements. */
+export type MdzVoidNodeType = 'Hr';
+/** Discriminant for leaf text nodes. */
+export type MdzTextNodeType = 'Text' | 'Code';
+/**
+ * Open a container node. The renderer starts a new element/wrapper.
+ * Children are subsequent opcodes until the matching `close`.
+ */
+export interface MdzOpcodeOpen {
+    type: 'open';
+    id: MdzNodeId;
+    node_type: MdzContainerNodeType;
+    /** Byte offset in the full input where the opening delimiter begins. */
+    start: number;
+    /** Heading level (1-6). Present when `node_type` is `'Heading'`. */
+    level?: 1 | 2 | 3 | 4 | 5 | 6;
+    /** Tag name. Present when `node_type` is `'Element'` or `'Component'`. */
+    name?: string;
+    /** Language hint. Present when `node_type` is `'Codeblock'`. */
+    lang?: string | null;
+}
+/**
+ * Close a previously opened container node.
+ * Carries deferred metadata that wasn't known at open time.
+ */
+export interface MdzOpcodeClose {
+    type: 'close';
+    id: MdzNodeId;
+    /** Byte offset in the full input immediately after the closing delimiter. */
+    end: number;
+    /** Link URL/path, resolved when `](url)` completes. */
+    reference?: string;
+    /** Link type, resolved alongside `reference`. */
+    link_type?: 'external' | 'internal';
+    /** Heading slug, computed from full heading content. */
+    heading_id?: string;
+    /**
+     * If true, consumer drops this node and its descendants from the tree.
+     * Used for whitespace-only paragraphs that match nothing in `mdz_parse`'s
+     * output — the streaming parser emits open/text speculatively, then
+     * retroactively drops the empty wrapper at close.
+     */
+    discard?: boolean;
+}
+/**
+ * Create a leaf text or code node.
+ * The parent is implicit — the innermost open container on the renderer's stack.
+ */
+export interface MdzOpcodeText {
+    type: 'text';
+    id: MdzNodeId;
+    content: string;
+    text_type: MdzTextNodeType;
+    /** Byte offset where this node begins (for Code, the opening backtick). */
+    start: number;
+    /** Byte offset immediately after this node ends (for Code, after the closing backtick). */
+    end: number;
+}
+/**
+ * Append content to an existing text node.
+ * Streaming optimization — avoids creating a new node per chunk
+ * during plain text runs.
+ */
+export interface MdzOpcodeAppendText {
+    type: 'append_text';
+    id: MdzNodeId;
+    content: string;
+}
+/**
+ * Trim `count` characters from the end of an existing text node.
+ * If trimming empties the node, the consumer removes it from its parent.
+ *
+ * Used by paragraph/codeblock close to drop the trailing newline that
+ * separates inline content from the block boundary. Emitted instead of
+ * retroactively mutating the prior `text`/`append_text` opcode, so the
+ * opcode stream is append-only.
+ */
+export interface MdzOpcodeTrimText {
+    type: 'trim_text';
+    id: MdzNodeId;
+    count: number;
+}
+/**
+ * Create a self-contained leaf node (e.g., horizontal rule).
+ * Inserted as a child of the innermost open container, or at root level.
+ */
+export interface MdzOpcodeVoid {
+    type: 'void';
+    id: MdzNodeId;
+    node_type: MdzVoidNodeType;
+    /** Byte offset in the full input where this element begins. */
+    start: number;
+    /** Byte offset immediately after this element ends. */
+    end: number;
+}
+/**
+ * Undo an optimistic open. Removes the container wrapper,
+ * inserts `replacement_text` as literal text at the container's position,
+ * and re-parents the container's children to the grandparent.
+ *
+ * When `wrap_node_type` and `wrap_id` are set, the replacement text and
+ * re-parented children are wrapped in a new container of the given type
+ * instead of being placed directly at the grandparent level. The wrapper
+ * is pushed onto the consumer's stack (open for future content). This is
+ * used for block-level reverts (e.g., codeblock → paragraph) where the
+ * grandparent is root and content needs a container.
+ */
+export interface MdzOpcodeRevert {
+    type: 'revert';
+    id: MdzNodeId;
+    /** The delimiter text to emit as literal content (e.g., `"**"`, `"["`, `"<Tag>"`). */
+    replacement_text: string;
+    /** Byte offset of the original opening delimiter in the full input. */
+    start: number;
+    /** Wrap replacement text and re-parented children in a new container of this type. */
+    wrap_node_type?: MdzContainerNodeType;
+    /** ID for the wrapper node. Required when `wrap_node_type` is set. */
+    wrap_id?: MdzNodeId;
+}
+/**
+ * Retroactively wrap an existing text node in a container.
+ * Used for text-first auto-links: URL/path text streams as plain text,
+ * then gets wrapped in a Link when the URL boundary is found.
+ *
+ * When `trim_end` is set, trailing characters (punctuation) are trimmed
+ * from the target text node and placed in a new sibling Text node after
+ * the Link wrapper, identified by `trim_id`.
+ */
+export interface MdzOpcodeWrap {
+    type: 'wrap';
+    /** ID for the new Link container node. */
+    id: MdzNodeId;
+    /** Container type to wrap in (always `'Link'` for now). */
+    node_type: 'Link';
+    /** ID of the existing text node to wrap. */
+    target_id: MdzNodeId;
+    /** Resolved URL or path reference. */
+    reference: string;
+    /** Whether the link is external (URL) or internal (path). */
+    link_type: 'external' | 'internal';
+    /** Byte offset where the URL/path begins. */
+    start: number;
+    /** Byte offset immediately after the URL/path (before any trimmed punctuation). */
+    end: number;
+    /** Number of trailing chars to trim from target and place after the link. */
+    trim_end?: number;
+    /** ID for the trimmed-text sibling node. Required when `trim_end` > 0. */
+    trim_id?: MdzNodeId;
+}
+/** All node types that can appear in the mdz tree. */
+export type MdzNodeType = MdzContainerNodeType | MdzVoidNodeType | MdzTextNodeType;
+/** Discriminated union of all mdz opcodes. */
+export type MdzOpcode = MdzOpcodeOpen | MdzOpcodeClose | MdzOpcodeText | MdzOpcodeAppendText | MdzOpcodeTrimText | MdzOpcodeVoid | MdzOpcodeRevert | MdzOpcodeWrap;
+//# sourceMappingURL=mdz_opcodes.d.ts.map

package/dist/mdz_opcodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdz_opcodes.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz_opcodes.ts"],"names":[],"mappings":"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"}

package/dist/mdz_opcodes.js

@@ -0,0 +1,14 @@
+/**
+ * Opcode types for the mdz streaming parser.
+ *
+ * Opcodes are serializable rendering instructions emitted by `MdzStreamParser`.
+ * They tell a renderer what to do next — open a container, append text, close it,
+ * or revert an optimistic assumption. Target-agnostic: works for HTML, Svelte, PDF, etc.
+ *
+ * The parser makes optimistic assumptions about ambiguous syntax (e.g., `**` is probably bold)
+ * and emits `revert` opcodes to correct when wrong. This enables true streaming rendering
+ * without ever re-parsing.
+ *
+ * @module
+ */
+export {};

package/dist/mdz_opcodes_to_nodes.d.ts

@@ -0,0 +1,20 @@
+/**
+ * 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 type { MdzNode } from './mdz.js';
+import type { MdzOpcode } from './mdz_opcodes.js';
+/**
+ * Convert an array of mdz opcodes to the `MdzNode[]` tree.
+ * Produces output identical to `mdz_parse()`.
+ */
+export declare const mdz_opcodes_to_nodes: (opcodes: Array<MdzOpcode>) => Array<MdzNode>;
+//# sourceMappingURL=mdz_opcodes_to_nodes.d.ts.map

package/dist/mdz_opcodes_to_nodes.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"mdz_opcodes_to_nodes.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz_opcodes_to_nodes.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,OAAO,KAAK,EAAC,OAAO,EAAwD,MAAM,UAAU,CAAC;AAC7F,OAAO,KAAK,EAAC,SAAS,EAAY,MAAM,kBAAkB,CAAC;AAwB3D;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,SAAS,KAAK,CAAC,SAAS,CAAC,KAAG,KAAK,CAAC,OAAO,CAkN7E,CAAC"}

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"}