@fuzdev/fuz_ui 0.198.1 → 0.199.0

package/src/lib/mdz_stream_state.svelte.ts

@@ -0,0 +1,387 @@
+/**
+ * Reactive state for the mdz streaming renderer.
+ *
+ * Maintains a reactive tree of `MdzStreamNode` objects that Svelte 5 can
+ * efficiently update. Opcodes from `MdzStreamParser` are applied via
+ * `apply()` or `apply_batch()`, mutating the tree in place.
+ *
+ * @module
+ */
+
+import {DEV} from 'esm-env';
+
+import type {MdzNodeId, MdzNodeType, MdzOpcode} from './mdz_opcodes.js';
+
+/**
+ * A reactive node in the stream renderer tree.
+ * Fields are `$state` so Svelte re-renders only what changes.
+ */
+export class MdzStreamNode {
+	id: MdzNodeId;
+	type: MdzNodeType;
+	content: string = $state('');
+	children: Array<MdzStreamNode> = $state([]);
+	// metadata
+	level?: number;
+	reference?: string = $state();
+	link_type?: string = $state();
+	name?: string;
+	lang?: string | null;
+	heading_id?: string = $state();
+
+	constructor(id: MdzNodeId, type: MdzNodeType) {
+		this.id = id;
+		this.type = type;
+	}
+}
+
+/**
+ * Reactive state manager for streaming mdz content.
+ * Apply opcodes to incrementally build and update the render tree.
+ */
+export class MdzStreamState {
+	root: Array<MdzStreamNode> = $state([]);
+
+	/** Node lookup by ID. */
+	#nodes = new Map<MdzNodeId, MdzStreamNode>();
+
+	/** Parent tracking for re-parenting during revert. */
+	#parents = new Map<MdzNodeId, MdzNodeId | null>();
+
+	/** Stack of open container IDs (for knowing current parent). */
+	#stack: Array<MdzNodeId> = [];
+
+	/**
+	 * Register a new node and attach it to its current parent (innermost open
+	 * container, or root). Shared by `open`, `text`, and `void` paths.
+	 */
+	#attach(node: MdzStreamNode): void {
+		this.#nodes.set(node.id, node);
+		const parent_id = this.#stack.length > 0 ? this.#stack[this.#stack.length - 1]! : null;
+		this.#parents.set(node.id, parent_id);
+		if (parent_id !== null) {
+			const parent = this.#nodes.get(parent_id);
+			if (DEV && !parent) {
+				throw new Error(`MdzStreamState: parent id ${parent_id} on stack but missing from nodes`);
+			}
+			if (parent) parent.children.push(node);
+		} else {
+			this.root.push(node);
+		}
+	}
+
+	/**
+	 * Apply a single opcode.
+	 */
+	apply(opcode: MdzOpcode): void {
+		switch (opcode.type) {
+			case 'open': {
+				if (DEV && this.#nodes.has(opcode.id)) {
+					throw new Error(
+						`MdzStreamState: duplicate open for id ${opcode.id} (node_type '${opcode.node_type}')`,
+					);
+				}
+				const node = new MdzStreamNode(opcode.id, opcode.node_type);
+				if (opcode.level !== undefined) node.level = opcode.level;
+				if (opcode.name !== undefined) node.name = opcode.name;
+				if (opcode.lang !== undefined) node.lang = opcode.lang;
+				this.#attach(node);
+				this.#stack.push(opcode.id);
+				break;
+			}
+
+			case 'close': {
+				if (DEV) {
+					if (!this.#nodes.has(opcode.id)) {
+						throw new Error(`MdzStreamState: close for unknown id ${opcode.id}`);
+					}
+					if (!this.#stack.includes(opcode.id)) {
+						throw new Error(`MdzStreamState: close for id ${opcode.id} which is not on the stack`);
+					}
+				}
+				const node = this.#nodes.get(opcode.id);
+				if (node) {
+					if (opcode.discard) {
+						// drop the node and its descendants from its parent's children
+						const parent_id = this.#parents.get(opcode.id);
+						const parent_children =
+							parent_id !== null && parent_id !== undefined
+								? this.#nodes.get(parent_id)?.children
+								: this.root;
+						if (parent_children) {
+							const idx = parent_children.indexOf(node);
+							if (idx !== -1) parent_children.splice(idx, 1);
+						}
+					} else {
+						// apply deferred metadata
+						if (opcode.reference !== undefined) node.reference = opcode.reference;
+						if (opcode.link_type !== undefined) node.link_type = opcode.link_type;
+						if (opcode.heading_id !== undefined) node.heading_id = opcode.heading_id;
+						// Code/Codeblock: collapse text children into `content` so renderers
+						// can read it directly without walking children every render.
+						if (node.type === 'Code' || node.type === 'Codeblock') {
+							let content = '';
+							for (const child of node.children) content += child.content;
+							node.content = content;
+						}
+					}
+				}
+				// pop from stack
+				const idx = this.#stack.lastIndexOf(opcode.id);
+				if (idx !== -1) this.#stack.splice(idx, 1);
+				// cleanup: closed nodes have no further opcode interactions.
+				// children are retained in the render tree via children arrays
+				// (discarded nodes' subtrees also need full cleanup, which the
+				// traversal in `#cleanup_node` already handles).
+				this.#cleanup_node(opcode.id);
+				break;
+			}
+
+			case 'text': {
+				if (DEV && this.#nodes.has(opcode.id)) {
+					throw new Error(
+						`MdzStreamState: duplicate text for id ${opcode.id} (text_type '${opcode.text_type}')`,
+					);
+				}
+				const node = new MdzStreamNode(opcode.id, opcode.text_type);
+				node.content = opcode.content;
+				this.#attach(node);
+				break;
+			}
+
+			case 'append_text': {
+				if (DEV && !this.#nodes.has(opcode.id)) {
+					throw new Error(`MdzStreamState: append_text for unknown id ${opcode.id}`);
+				}
+				const node = this.#nodes.get(opcode.id);
+				if (node) {
+					node.content += opcode.content;
+				}
+				break;
+			}
+
+			case 'trim_text': {
+				if (DEV && !this.#nodes.has(opcode.id)) {
+					throw new Error(`MdzStreamState: trim_text for unknown id ${opcode.id}`);
+				}
+				const node = this.#nodes.get(opcode.id);
+				if (node) {
+					node.content = node.content.slice(0, node.content.length - opcode.count);
+					if (node.content.length === 0) {
+						const parent_id = this.#parents.get(opcode.id);
+						const parent_children =
+							parent_id !== null && parent_id !== undefined
+								? this.#nodes.get(parent_id)?.children
+								: this.root;
+						if (parent_children) {
+							const idx = parent_children.indexOf(node);
+							if (idx !== -1) parent_children.splice(idx, 1);
+						}
+						this.#nodes.delete(opcode.id);
+						this.#parents.delete(opcode.id);
+					}
+				}
+				break;
+			}
+
+			case 'void': {
+				if (DEV && this.#nodes.has(opcode.id)) {
+					throw new Error(
+						`MdzStreamState: duplicate void for id ${opcode.id} (node_type '${opcode.node_type}')`,
+					);
+				}
+				const node = new MdzStreamNode(opcode.id, opcode.node_type);
+				this.#attach(node);
+				break;
+			}
+
+			case 'revert': {
+				if (DEV) {
+					if (!this.#nodes.has(opcode.id)) {
+						throw new Error(`MdzStreamState: revert for unknown id ${opcode.id}`);
+					}
+					if (!this.#stack.includes(opcode.id)) {
+						throw new Error(`MdzStreamState: revert for id ${opcode.id} which is not on the stack`);
+					}
+				}
+				const node = this.#nodes.get(opcode.id);
+				if (!node) break;
+
+				const parent_id = this.#parents.get(opcode.id);
+				const parent_children =
+					parent_id !== null && parent_id !== undefined
+						? this.#nodes.get(parent_id)?.children
+						: this.root;
+
+				if (!parent_children) {
+					if (DEV) {
+						throw new Error(
+							`MdzStreamState: revert for id ${opcode.id} but parent has no children array`,
+						);
+					}
+					break;
+				}
+
+				// find the node in parent's children
+				let node_idx = -1;
+				for (let i = 0; i < parent_children.length; i++) {
+					if (parent_children[i]!.id === opcode.id) {
+						node_idx = i;
+						break;
+					}
+				}
+				if (node_idx === -1) {
+					if (DEV) {
+						throw new Error(
+							`MdzStreamState: revert for id ${opcode.id} but node not found in parent's children`,
+						);
+					}
+					break;
+				}
+
+				// collect replacement content: literal delimiter text + re-parented children
+				const replacement_nodes: Array<MdzStreamNode> = [];
+				if (opcode.replacement_text) {
+					const text_node = new MdzStreamNode(opcode.id, 'Text');
+					text_node.content = opcode.replacement_text;
+					replacement_nodes.push(text_node);
+				}
+				for (const child of node.children) {
+					replacement_nodes.push(child);
+				}
+
+				if (opcode.wrap_node_type != null && opcode.wrap_id != null) {
+					if (DEV && this.#nodes.has(opcode.wrap_id)) {
+						throw new Error(
+							`MdzStreamState: revert wrap_id ${opcode.wrap_id} already exists in nodes`,
+						);
+					}
+					// block-level revert: wrap content in a new container and push onto stack
+					const wrapper = new MdzStreamNode(opcode.wrap_id, opcode.wrap_node_type);
+					for (const rn of replacement_nodes) {
+						wrapper.children.push(rn);
+					}
+					for (const child of node.children) {
+						this.#parents.set(child.id, opcode.wrap_id);
+					}
+					this.#nodes.set(opcode.wrap_id, wrapper);
+					this.#parents.set(opcode.wrap_id, parent_id ?? null);
+					parent_children.splice(node_idx, 1, wrapper);
+					this.#stack.push(opcode.wrap_id);
+				} else {
+					// inline revert: re-parent directly to grandparent
+					for (const child of node.children) {
+						this.#parents.set(child.id, parent_id ?? null);
+					}
+					parent_children.splice(node_idx, 1, ...replacement_nodes);
+				}
+
+				// remove reverted node from stack
+				const stack_idx = this.#stack.lastIndexOf(opcode.id);
+				if (stack_idx !== -1) this.#stack.splice(stack_idx, 1);
+
+				// cleanup
+				this.#nodes.delete(opcode.id);
+				this.#parents.delete(opcode.id);
+				break;
+			}
+
+			case 'wrap': {
+				if (DEV) {
+					if (!this.#nodes.has(opcode.target_id)) {
+						throw new Error(`MdzStreamState: wrap target_id ${opcode.target_id} not in nodes`);
+					}
+					if (this.#nodes.has(opcode.id)) {
+						throw new Error(`MdzStreamState: wrap id ${opcode.id} already exists in nodes`);
+					}
+				}
+				const target = this.#nodes.get(opcode.target_id);
+				if (!target) break;
+
+				const parent_id = this.#parents.get(opcode.target_id);
+				const parent_children =
+					parent_id !== null && parent_id !== undefined
+						? this.#nodes.get(parent_id)?.children
+						: this.root;
+
+				if (!parent_children) break;
+
+				// find target in parent's children
+				let target_idx = -1;
+				for (let i = 0; i < parent_children.length; i++) {
+					if (parent_children[i]!.id === opcode.target_id) {
+						target_idx = i;
+						break;
+					}
+				}
+				if (target_idx === -1) break;
+
+				// handle trailing punctuation trim
+				let trimmed_node: MdzStreamNode | null = null;
+				if (opcode.trim_end && opcode.trim_end > 0 && opcode.trim_id != null) {
+					const trimmed_content = target.content.slice(target.content.length - opcode.trim_end);
+					target.content = target.content.slice(0, target.content.length - opcode.trim_end);
+					trimmed_node = new MdzStreamNode(opcode.trim_id, 'Text');
+					trimmed_node.content = trimmed_content;
+					this.#nodes.set(opcode.trim_id, trimmed_node);
+					this.#parents.set(opcode.trim_id, parent_id ?? null);
+				}
+
+				// create Link wrapper containing target
+				const link = new MdzStreamNode(opcode.id, opcode.node_type);
+				link.reference = opcode.reference;
+				link.link_type = opcode.link_type;
+				link.children.push(target);
+				this.#nodes.set(opcode.id, link);
+				this.#parents.set(opcode.id, parent_id ?? null);
+				this.#parents.set(opcode.target_id, opcode.id);
+
+				// replace target with [Link, trimmed?] in parent's children
+				if (trimmed_node) {
+					parent_children.splice(target_idx, 1, link, trimmed_node);
+				} else {
+					parent_children[target_idx] = link;
+				}
+
+				// cleanup: Link is complete (no close opcode coming).
+				// trim_id (if any) stays in maps — cleaned when parent closes.
+				this.#cleanup_node(opcode.id);
+				break;
+			}
+		}
+	}
+
+	/**
+	 * Remove a node and its descendants from the lookup maps. Iterative to avoid
+	 * stack overflow on deep trees.
+	 *
+	 * Parser invariant: once a container closes, no future opcode targets that
+	 * subtree (no `append_text` to a closed Text, no nested `wrap`/`revert`).
+	 * Children stay reachable via `parent.children` arrays — only the lookup
+	 * maps are pruned. If this invariant is violated, the misbehaving opcode
+	 * triggers a DEV throw in `apply()` and silently no-ops in production.
+	 */
+	#cleanup_node(id: MdzNodeId): void {
+		const queue: Array<MdzNodeId> = [id];
+		while (queue.length > 0) {
+			const current_id = queue.pop()!;
+			const node = this.#nodes.get(current_id);
+			if (node) {
+				for (const child of node.children) {
+					queue.push(child.id);
+				}
+			}
+			this.#nodes.delete(current_id);
+			this.#parents.delete(current_id);
+		}
+	}
+
+	/**
+	 * Apply a batch of opcodes.
+	 */
+	apply_batch(opcodes: Array<MdzOpcode>): void {
+		for (const op of opcodes) {
+			this.apply(op);
+		}
+	}
+}

package/src/lib/mdz_token_parser.ts

@@ -18,7 +18,12 @@ import type {
 	MdzElementNode,
 	MdzComponentNode,
 } from './mdz.js';
-import {extract_single_tag, mdz_heading_id} from './mdz_helpers.js';
+import {
+	extract_single_tag,
+	mdz_heading_id,
+	mdz_merge_adjacent_text,
+	mdz_push_merging_text,
+} from './mdz_helpers.js';
 import {
 	MdzLexer,
 	type MdzToken,
@@ -124,7 +129,7 @@ class MdzTokenParser {
 			if (node) children.push(node);
 		}
 
-		const merged = this.#merge_adjacent_text(children);
+		const merged = mdz_merge_adjacent_text(children);
 		const end = merged.length > 0 ? merged[merged.length - 1]!.end : start + level + 1;
 
 		return {type: 'Heading', level, id: mdz_heading_id(merged), children: merged, start, end};
@@ -228,7 +233,7 @@ class MdzTokenParser {
 				break;
 			}
 			const node = this.#parse_inline();
-			if (node) children.push(node);
+			if (node) mdz_push_merging_text(children, node);
 		}
 
 		// Unclosed - treat as text
@@ -257,7 +262,7 @@ class MdzTokenParser {
 				break;
 			}
 			const node = this.#parse_inline();
-			if (node) children.push(node);
+			if (node) mdz_push_merging_text(children, node);
 		}
 
 		return {type: 'Text', content: '_', start, end: start + 1};
@@ -285,7 +290,7 @@ class MdzTokenParser {
 				break;
 			}
 			const node = this.#parse_inline();
-			if (node) children.push(node);
+			if (node) mdz_push_merging_text(children, node);
 		}
 
 		return {type: 'Text', content: '~', start, end: start + 1};
@@ -329,7 +334,7 @@ class MdzTokenParser {
 				break;
 			}
 			const node = this.#parse_inline();
-			if (node) children.push(node);
+			if (node) mdz_push_merging_text(children, node);
 		}
 
 		return {type: 'Text', content: '[', start, end: start + 1};
@@ -364,7 +369,7 @@ class MdzTokenParser {
 				return {type: node_type, name: tag_name, children, start, end: t.end};
 			}
 			const node = this.#parse_inline();
-			if (node) children.push(node);
+			if (node) mdz_push_merging_text(children, node);
 		}
 
 		// Unclosed tag
@@ -414,7 +419,7 @@ class MdzTokenParser {
 		}
 
 		// Merge adjacent text nodes
-		const merged = this.#merge_adjacent_text(paragraph_children.slice());
+		const merged = mdz_merge_adjacent_text(paragraph_children.slice());
 		paragraph_children.length = 0;
 
 		if (merged.length === 0) return null;
@@ -426,36 +431,4 @@ class MdzTokenParser {
 			end: merged[merged.length - 1]!.end,
 		};
 	}
-
-	#merge_adjacent_text(nodes: Array<MdzNode>): Array<MdzNode> {
-		if (nodes.length <= 1) return nodes;
-
-		const merged: Array<MdzNode> = [];
-		let pending_text: MdzTextNode | null = null;
-
-		for (const node of nodes) {
-			if (node.type === 'Text') {
-				if (pending_text) {
-					pending_text = {
-						type: 'Text',
-						content: pending_text.content + node.content,
-						start: pending_text.start,
-						end: node.end,
-					};
-				} else {
-					pending_text = {...node};
-				}
-			} else {
-				if (pending_text) {
-					merged.push(pending_text);
-					pending_text = null;
-				}
-				merged.push(node);
-			}
-		}
-
-		if (pending_text) merged.push(pending_text);
-
-		return merged;
-	}
 }

package/src/lib/module.svelte.ts

@@ -2,7 +2,7 @@ import type {ModuleJsonInput} from 'svelte-docinfo/types.js';
 
 import {Declaration} from './declaration.svelte.js';
 import type {Library} from './library.svelte.js';
-import {url_github_file} from './package_helpers.js';
+import {url_github_file} from '@fuzdev/fuz_util/package_helpers.js';
 
 /**
  * Rich runtime representation of a module with computed properties.

package/src/lib/site.svelte.ts

@@ -1,6 +1,8 @@
 import type {Url} from '@fuzdev/fuz_util/url.js';
+import type {PkgJson} from '@fuzdev/fuz_util/pkg_json.js';
 
 import {create_context} from './context_helpers.js';
+import {repo_url_parse} from '@fuzdev/fuz_util/package_helpers.js';
 import type {SvgData} from './svg.js';
 
 export interface SiteStateOptions {
@@ -10,12 +12,20 @@ export interface SiteStateOptions {
 	icon?: SvgData | null;
 	/**
 	 * The site's glyph, a single unicode character identifying the project.
+	 * Falls back to `pkg_json.glyph`.
 	 */
 	glyph?: string | null;
 	/**
 	 * The site's source repository url, e.g. for `DocsFooter` links.
+	 * Falls back to the url parsed from `pkg_json.repository`.
 	 */
 	repo_url?: Url | null;
+	/**
+	 * Curated `package.json`, typically the default export of `virtual:pkg.json`.
+	 * `glyph` and `repo_url` derive from it when not given explicitly; explicit
+	 * props always win.
+	 */
+	pkg_json?: PkgJson | null;
 }
 
 /**
@@ -23,6 +33,10 @@ export interface SiteStateOptions {
  * by components like `Breadcrumb` and `DocsFooter`. Set once per app at the root
  * layout. Distinct from `library_context`, which carries the heavy
  * module/declaration metadata that only docs and API pages need.
+ *
+ * Pass `pkg_json` (from `virtual:pkg.json`) to derive `glyph`/`repo_url` from the
+ * package's own metadata instead of hardcoding them; `icon` stays an explicit
+ * logo import since it's structured `SvgData`, not package metadata.
  */
 export class SiteState {
 	icon: SvgData | null = $state.raw(null);
@@ -31,8 +45,9 @@ export class SiteState {
 
 	constructor(options: SiteStateOptions = {}) {
 		this.icon = options.icon ?? null;
-		this.glyph = options.glyph ?? null;
-		this.repo_url = options.repo_url ?? null;
+		this.glyph = options.glyph ?? options.pkg_json?.glyph ?? null;
+		this.repo_url =
+			options.repo_url ?? (options.pkg_json ? repo_url_parse(options.pkg_json.repository) : null);
 	}
 }
 

package/src/lib/tsdoc_mdz.ts

@@ -37,8 +37,8 @@ const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${
  * tsdoc_see_to_mdz('{@link SomeType}')
  * // → '`SomeType`'
  *
- * tsdoc_see_to_mdz('https://example.com')
- * // → 'https://example.com'
+ * tsdoc_see_to_mdz('https://fuz.dev')
+ * // → 'https://fuz.dev'
  *
  * tsdoc_see_to_mdz('[svelte-docinfo](https://github.com/ryanatkn/svelte-docinfo) for the analysis library')
  * // → '[svelte-docinfo](https://github.com/ryanatkn/svelte-docinfo) for the analysis library'