@fuzdev/fuz_ui 0.204.0 → 0.205.0

package/src/lib/mdz_opcodes.ts

@@ -1,205 +0,0 @@
-/**
- * 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;

package/src/lib/mdz_opcodes_to_nodes.ts

@@ -1,375 +0,0 @@
-/**
- * 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 type {MdzNode, MdzTextNode, MdzLinkNode, MdzHeadingNode, MdzCodeNode} from './mdz.js';
-import type {MdzOpcode, MdzNodeId} from './mdz_opcodes.js';
-import {
-	extract_single_tag,
-	mdz_heading_id,
-	mdz_merge_adjacent_text,
-	mdz_push_merging_text,
-} from './mdz_helpers.js';
-
-interface StackFrame {
-	id: MdzNodeId;
-	node_type: string;
-	children: Array<MdzNode>;
-	start: number;
-	// metadata from open opcode
-	level?: number;
-	name?: string;
-	lang?: string | null;
-	// metadata from close opcode (deferred)
-	end?: number;
-	reference?: string;
-	link_type?: 'external' | 'internal';
-	heading_id?: string;
-}
-
-/**
- * Convert an array of mdz opcodes to the `MdzNode[]` tree.
- * Produces output identical to `mdz_parse()`.
- */
-export const mdz_opcodes_to_nodes = (opcodes: Array<MdzOpcode>): Array<MdzNode> => {
-	const root: Array<MdzNode> = [];
-	const stack: Array<StackFrame> = [];
-	// index node IDs to their text content (for append_text and wrap)
-	const text_nodes = new Map<MdzNodeId, MdzTextNode | MdzCodeNode>();
-	// track which children array contains each text node (for wrap)
-	const node_parents = new Map<number, Array<MdzNode>>();
-
-	const target = (): Array<MdzNode> => {
-		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: MdzTextNode | MdzCodeNode =
-					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: StackFrame | null = 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: StackFrame = {
-							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: MdzTextNode | null = 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: MdzLinkNode = {
-					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 as MdzNode, trimmed_node as MdzNode);
-				} 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: StackFrame): MdzNode | null => {
-	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!,
-			} as MdzHeadingNode;
-		}
-
-		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;
-	}
-};