@fuzdev/fuz_ui 0.198.1 → 0.199.0

package/dist/mdz_stream_state.svelte.js

@@ -0,0 +1,357 @@
+/**
+ * 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';
+/**
+ * A reactive node in the stream renderer tree.
+ * Fields are `$state` so Svelte re-renders only what changes.
+ */
+export class MdzStreamNode {
+    id;
+    type;
+    content = $state('');
+    children = $state([]);
+    // metadata
+    level;
+    reference = $state();
+    link_type = $state();
+    name;
+    lang;
+    heading_id = $state();
+    constructor(id, type) {
+        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 = $state([]);
+    /** Node lookup by ID. */
+    #nodes = new Map();
+    /** Parent tracking for re-parenting during revert. */
+    #parents = new Map();
+    /** Stack of open container IDs (for knowing current parent). */
+    #stack = [];
+    /**
+     * 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) {
+        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) {
+        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 = [];
+                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 = 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) {
+        const queue = [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) {
+        for (const op of opcodes) {
+            this.apply(op);
+        }
+    }
+}

package/dist/mdz_token_parser.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mdz_token_parser.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz_token_parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACX,OAAO,EASP,MAAM,UAAU,CAAC;AAgBlB;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,OAAO,CAG3D,CAAC"}
+{"version":3,"file":"mdz_token_parser.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz_token_parser.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACX,OAAO,EASP,MAAM,UAAU,CAAC;AAqBlB;;GAEG;AACH,eAAO,MAAM,eAAe,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,OAAO,CAG3D,CAAC"}

package/dist/mdz_token_parser.js

@@ -6,7 +6,7 @@
  *
  * @module
  */
-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, } from './mdz_lexer.js';
 /**
  * Parses text to an array of `MdzNode` using a two-phase lexer+parser approach.
@@ -91,7 +91,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 };
     }
@@ -173,7 +173,7 @@ class MdzTokenParser {
             }
             const node = this.#parse_inline();
             if (node)
-                children.push(node);
+                mdz_push_merging_text(children, node);
         }
         // Unclosed - treat as text
         return { type: 'Text', content: '**', start, end: start + 2 };
@@ -197,7 +197,7 @@ class MdzTokenParser {
             }
             const node = this.#parse_inline();
             if (node)
-                children.push(node);
+                mdz_push_merging_text(children, node);
         }
         return { type: 'Text', content: '_', start, end: start + 1 };
     }
@@ -220,7 +220,7 @@ class MdzTokenParser {
             }
             const node = this.#parse_inline();
             if (node)
-                children.push(node);
+                mdz_push_merging_text(children, node);
         }
         return { type: 'Text', content: '~', start, end: start + 1 };
     }
@@ -257,7 +257,7 @@ class MdzTokenParser {
             }
             const node = this.#parse_inline();
             if (node)
-                children.push(node);
+                mdz_push_merging_text(children, node);
         }
         return { type: 'Text', content: '[', start, end: start + 1 };
     }
@@ -288,7 +288,7 @@ class MdzTokenParser {
             }
             const node = this.#parse_inline();
             if (node)
-                children.push(node);
+                mdz_push_merging_text(children, node);
         }
         // Unclosed tag
         return { type: 'Text', content: '<', start, end: start + 1 };
@@ -330,7 +330,7 @@ class MdzTokenParser {
             return single_tag;
         }
         // 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;
@@ -341,35 +341,4 @@ class MdzTokenParser {
             end: merged[merged.length - 1].end,
         };
     }
-    #merge_adjacent_text(nodes) {
-        if (nodes.length <= 1)
-            return nodes;
-        const merged = [];
-        let pending_text = 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/dist/module.svelte.js

@@ -1,5 +1,5 @@
 import { Declaration } from './declaration.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/dist/site.svelte.d.ts

@@ -1,4 +1,5 @@
 import type { Url } from '@fuzdev/fuz_util/url.js';
+import type { PkgJson } from '@fuzdev/fuz_util/pkg_json.js';
 import type { SvgData } from './svg.js';
 export interface SiteStateOptions {
     /**
@@ -7,18 +8,30 @@ 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;
 }
 /**
  * Light site-identity values for app chrome - the icon, glyph, and repo url used
  * 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 declare class SiteState {
     icon: SvgData | null;

package/dist/site.svelte.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"site.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/site.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,yBAAyB,CAAC;AAGjD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,UAAU,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB;;OAEG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;OAEG;IACH,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;CACtB;AAED;;;;;GAKG;AACH,qBAAa,SAAS;IACrB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAoB;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAoB;IACxC,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAoB;gBAE5B,OAAO,GAAE,gBAAqB;CAK1C;AAED,eAAO,MAAM,YAAY;;;;CAA8B,CAAC"}
+{"version":3,"file":"site.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/site.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,GAAG,EAAC,MAAM,yBAAyB,CAAC;AACjD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,8BAA8B,CAAC;AAI1D,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,UAAU,CAAC;AAEtC,MAAM,WAAW,gBAAgB;IAChC;;OAEG;IACH,IAAI,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;IACtB;;;OAGG;IACH,KAAK,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,EAAE,GAAG,GAAG,IAAI,CAAC;IACtB;;;;OAIG;IACH,QAAQ,CAAC,EAAE,OAAO,GAAG,IAAI,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,qBAAa,SAAS;IACrB,IAAI,EAAE,OAAO,GAAG,IAAI,CAAoB;IACxC,KAAK,EAAE,MAAM,GAAG,IAAI,CAAoB;IACxC,QAAQ,EAAE,GAAG,GAAG,IAAI,CAAoB;gBAE5B,OAAO,GAAE,gBAAqB;CAM1C;AAED,eAAO,MAAM,YAAY;;;;CAA8B,CAAC"}

package/dist/site.svelte.js

@@ -1,9 +1,14 @@
 import { create_context } from './context_helpers.js';
+import { repo_url_parse } from '@fuzdev/fuz_util/package_helpers.js';
 /**
  * Light site-identity values for app chrome - the icon, glyph, and repo url used
  * 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 = $state.raw(null);
@@ -11,8 +16,9 @@ export class SiteState {
     repo_url = $state.raw(null);
     constructor(options = {}) {
         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);
     }
 }
 export const site_context = create_context();

package/dist/tsdoc_mdz.d.ts

@@ -31,8 +31,8 @@
  * 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'

package/dist/tsdoc_mdz.js

@@ -34,8 +34,8 @@ const format_reference = (ref) => (mdz_is_url(ref) ? 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'

package/dist/vite_plugin_pkg_json.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Vite plugin serving a curated, publish-safe `package.json` as the virtual
+ * module `virtual:pkg.json`.
+ *
+ * Consumers' `src/routes/library.ts` (and root layouts) need package identity —
+ * name, version, the Fuz extension fields — in the client. Importing the root
+ * `package.json` directly inlines the *whole* file into the client bundle
+ * (`scripts`, `dependencies`, `devDependencies`, private config) and trips
+ * SvelteKit's `server.fs.allow` on cold HMR reloads. This plugin reads the
+ * project's `package.json` at build time, strips it to `pkg_json_keys`, and
+ * serves only that subset. Consumers combine it with `virtual:svelte-docinfo`'s
+ * analyzed `modules` via `library_json_from_modules` to build a `LibraryJson`
+ * (see `src/routes/library.ts` for the canonical pattern).
+ *
+ * The `.json` suffix on the virtual id is load-bearing, mirroring how
+ * `vite_plugin_fuz_css`'s `virtual:fuz.css` relies on `.css`: `load()` returns
+ * raw JSON text and Vite's built-in `vite:json` plugin transforms it into an ES
+ * module (default export plus named exports), so consumers write
+ * `import package_json from 'virtual:pkg.json'`. Do *not* return a JS module
+ * here — the `.json` id would double-transform it.
+ *
+ * ```ts
+ * // vite.config.ts
+ * import {vite_plugin_pkg_json} from './vite_plugin_pkg_json.js';
+ * export default defineConfig({plugins: [vite_plugin_pkg_json(), sveltekit()]});
+ * ```
+ *
+ * The kept field set defaults to `pkg_json_keys`. To expose extra publish-safe
+ * fields, pass a wider `keys` list — typically composed from the default with a
+ * spread (`` keys: [...pkg_json_keys, 'keywords'] ``). Because `library_json_from_modules`
+ * re-strips at runtime, the *same* list must reach that call (and the consumer's
+ * `virtual:pkg.json` ambient type) for the extras to survive end to end — share
+ * one const across all three sites:
+ *
+ * ```ts
+ * // src/routes/pkg_json_keys.ts
+ * import {pkg_json_keys} from '@fuzdev/fuz_util/pkg_json.js';
+ * export const pkg_json_keys_custom = [...pkg_json_keys, 'keywords'] as const;
+ *
+ * // vite.config.ts        → vite_plugin_pkg_json({keys: pkg_json_keys_custom})
+ * // src/routes/library.ts → library_json_from_modules(pkg_json, modules, pkg_json_keys_custom)
+ * ```
+ *
+ * @module
+ */
+import type { Plugin } from 'vite';
+import type { PackageJson } from '@fuzdev/fuz_util/package_json.js';
+/** Options for `vite_plugin_pkg_json`. */
+export interface VitePluginPkgJsonOptions {
+    /**
+     * The `package.json` fields to keep in the served subset. Defaults to the
+     * curated, publish-safe `pkg_json_keys`. Pass a wider list — usually
+     * `` [...pkg_json_keys, 'extra'] `` — to expose more fields; the same list
+     * must reach `library_json_from_modules` (see the module comment).
+     */
+    keys?: ReadonlyArray<keyof PackageJson>;
+}
+/**
+ * Creates the `virtual:pkg.json` plugin. Zero-config for canonical fuz usage —
+ * the publish-safe field set defaults to `pkg_json_keys`; widen it via `keys`.
+ */
+export declare const vite_plugin_pkg_json: (options?: VitePluginPkgJsonOptions) => Plugin;
+//# sourceMappingURL=vite_plugin_pkg_json.d.ts.map

package/dist/vite_plugin_pkg_json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"vite_plugin_pkg_json.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/vite_plugin_pkg_json.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4CG;AAIH,OAAO,KAAK,EAAC,MAAM,EAAS,MAAM,MAAM,CAAC;AACzC,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kCAAkC,CAAC;AAkBlE,0CAA0C;AAC1C,MAAM,WAAW,wBAAwB;IACxC;;;;;OAKG;IACH,IAAI,CAAC,EAAE,aAAa,CAAC,MAAM,WAAW,CAAC,CAAC;CACxC;AAED;;;GAGG;AACH,eAAO,MAAM,oBAAoB,GAAI,UAAS,wBAA6B,KAAG,MA2D7E,CAAC"}