@fuzdev/fuz_ui 0.198.1 → 0.200.0

package/dist/vite_plugin_pkg_json.js

@@ -0,0 +1,126 @@
+/**
+ * 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 { readFileSync } from 'node:fs';
+import { join } from 'node:path';
+import { pkg_json_from_package_json, pkg_json_keys } from '@fuzdev/fuz_util/pkg_json.js';
+const VIRTUAL_ID = 'virtual:pkg.json';
+/**
+ * Resolved id, `\0`-prefixed — the conventional Rollup marker for "this id is
+ * mine," hiding the virtual module from other plugins and the dev module graph.
+ *
+ * This deliberately diverges from `vite_plugin_fuz_css`, which avoids the `\0`
+ * on its resolved id: SvelteKit's dev FOUC prevention inlines `virtual:fuz.css`
+ * into the SSR'd `<head>` via URL lookup and can't resolve the `\0`-encoded
+ * form, so the page would flash unstyled. JSON is never inlined into `<head>`,
+ * so that constraint doesn't apply here and the `\0` is free to do its normal
+ * job. The trailing `.json` survives the prefix, so Vite's built-in `vite:json`
+ * plugin still matches and transforms the loaded text (see the module comment).
+ */
+const RESOLVED_VIRTUAL_ID = '\0virtual:pkg.json';
+/**
+ * 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 const vite_plugin_pkg_json = (options = {}) => {
+    const { keys = pkg_json_keys } = options;
+    let root = '';
+    let is_dev = false;
+    /** Curated JSON cached for build; left `null` in dev so `load` re-reads. */
+    let cached = null;
+    /**
+     * Reads `package.json`, strips it to the configured `keys` subset via
+     * `pkg_json_from_package_json` (the same strip the runtime uses, so the two
+     * can't drift), and returns the curated JSON text. Routes failures through the
+     * plugin context (`ctx.error`/`ctx.warn`) so a missing or malformed file
+     * surfaces as a named, actionable diagnostic rather than a raw
+     * `readFileSync`/`JSON.parse` stack trace.
+     */
+    const read_curated = (ctx) => {
+        const package_json_path = join(root, 'package.json');
+        ctx.addWatchFile(package_json_path); // re-emit when package.json changes
+        let raw;
+        try {
+            raw = JSON.parse(readFileSync(package_json_path, 'utf8'));
+        }
+        catch (err) {
+            // ctx.error throws, so this never returns
+            return ctx.error(`vite_plugin_pkg_json: failed to read or parse ${package_json_path}: ${err.message}`);
+        }
+        if (raw.name === undefined) {
+            ctx.warn(`vite_plugin_pkg_json: ${package_json_path} has no "name" field`);
+        }
+        return JSON.stringify(pkg_json_from_package_json(raw, keys));
+    };
+    return {
+        name: 'vite-plugin-pkg-json',
+        // Resolve the virtual id before other plugins claim it.
+        enforce: 'pre',
+        configResolved(config) {
+            root = config.root;
+            is_dev = config.command === 'serve';
+        },
+        buildStart() {
+            // Read package.json once up front so a missing or malformed file fails
+            // immediately — at build start, or at dev-server startup — rather than
+            // only when something first imports the virtual module. In build the
+            // result is cached for `load`; in dev `load` re-reads each time so edits
+            // to package.json propagate through the `addWatchFile`-driven reload.
+            const curated = read_curated(this);
+            if (!is_dev)
+                cached = curated;
+        },
+        resolveId(id) {
+            if (id === VIRTUAL_ID)
+                return RESOLVED_VIRTUAL_ID;
+            return undefined;
+        },
+        load(id) {
+            if (id !== RESOLVED_VIRTUAL_ID)
+                return undefined;
+            return cached ?? read_curated(this);
+        },
+    };
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuzdev/fuz_ui",
-  "version": "0.198.1",
+  "version": "0.200.0",
   "description": "Svelte UI library",
   "tagline": "friendly user zystem",
   "glyph": "🧶",
@@ -29,7 +29,8 @@
     "preview": "vite preview",
     "deploy": "gro deploy",
     "benchmark": "gro run src/benchmarks/mdz.benchmark.ts",
-    "benchmark:save": "gro run src/benchmarks/mdz.benchmark.ts --save"
+    "benchmark:save": "gro run src/benchmarks/mdz.benchmark.ts --save",
+    "benchmark:clean": "rm -f src/benchmarks/baseline.json"
   },
   "type": "module",
   "engines": {
@@ -81,10 +82,10 @@
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
     "@fuzdev/blake3_wasm": "^0.1.1",
-    "@fuzdev/fuz_code": "^0.45.1",
-    "@fuzdev/fuz_css": "^0.61.1",
-    "@fuzdev/fuz_util": "^0.63.0",
-    "@fuzdev/gro": "^0.200.0",
+    "@fuzdev/fuz_code": "^0.46.0",
+    "@fuzdev/fuz_css": "^0.62.0",
+    "@fuzdev/fuz_util": "^0.65.1",
+    "@fuzdev/gro": "^0.204.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.12.1",
     "@sveltejs/acorn-typescript": "^1.0.9",
@@ -104,7 +105,7 @@
     "prettier-plugin-svelte": "^3.5.1",
     "svelte": "^5.56.0",
     "svelte-check": "^4.4.8",
-    "svelte-docinfo": "^0.2.1",
+    "svelte-docinfo": "^0.4.1",
     "svelte2tsx": "^0.7.55",
     "tslib": "^2.8.1",
     "typescript": "^5.9.3",

package/src/lib/api_search.svelte.ts

@@ -42,7 +42,8 @@ export const create_api_search = (library: Library): ApiSearchState => {
 	const all_declarations = $derived(library.declarations);
 	const filtered_declarations = $derived.by(() => {
 		const items = query.trim() ? library.search_declarations(query) : all_declarations;
-		return items.sort((a, b) => a.name.localeCompare(b.name));
+		// spread before sort — `items` may be the shared source array
+		return [...items].sort((a, b) => a.name.localeCompare(b.name));
 	});
 
 	return {
@@ -83,7 +84,8 @@ export const create_module_declaration_search = (
 
 	const filtered = $derived.by(() => {
 		const trimmed_query = query.trim();
-		if (!trimmed_query) return all.sort((a, b) => a.name.localeCompare(b.name));
+		// spread before sort — `all` is the shared source array
+		if (!trimmed_query) return [...all].sort((a, b) => a.name.localeCompare(b.name));
 
 		const terms = trimmed_query.toLowerCase().split(/\s+/);
 

package/src/lib/declaration.svelte.ts

@@ -5,11 +5,12 @@ import type {
 	ParameterJsonInput,
 	ComponentPropJsonInput,
 	OverloadJsonInput,
+	Reactivity,
 } from 'svelte-docinfo/types.js';
 import {generateImport, getDisplayName} from 'svelte-docinfo/declaration-helpers.js';
 
 import type {Module} from './module.svelte.js';
-import {url_github_file} from './package_helpers.js';
+import {url_github_file} from '@fuzdev/fuz_util/package_helpers.js';
 
 // The `virtual:svelte-docinfo` module is serialized with svelte-docinfo's
 // `compactReplacer`, which strips empty default arrays — so the runtime data
@@ -74,7 +75,7 @@ export class Declaration {
 		generateImport(
 			this.declaration_json as DeclarationJson,
 			this.module_path,
-			this.library.package_json.name,
+			this.library.pkg_json.name,
 		),
 	);
 
@@ -141,13 +142,27 @@ export class Declaration {
 	 */
 	alias_of = $derived(this.declaration_json.aliasOf);
 
+	/**
+	 * Other modules that also export this declaration (re-export paths
+	 * relative to src/lib). Absent when only exported from its defining module.
+	 */
+	also_exported_from = $derived(field<Array<string>>(this.declaration_json, 'alsoExportedFrom'));
+
 	/**
 	 * Mutation documentation from `@mutates` tags, mapping parameter names to descriptions.
 	 */
 	mutates = $derived(this.declaration_json.mutates);
 
+	/**
+	 * Svelte reactivity flavor (`$state`, `$state.raw`, `$derived`, `$derived.by`)
+	 * when this variable is initialized with a value-producing rune.
+	 * Present on `variable` kind only.
+	 */
+	reactivity = $derived(field<Reactivity>(this.declaration_json, 'reactivity'));
+
 	has_examples = $derived(this.examples.length > 0);
-	is_deprecated = $derived(!!this.deprecated_message);
+	// presence, not truthiness — a bare `@deprecated` (no message text) arrives as `''`
+	is_deprecated = $derived(this.deprecated_message !== undefined);
 	has_documentation = $derived(!!this.doc_comment);
 	has_parameters = $derived(!!(this.parameters && this.parameters.length > 0));
 	has_props = $derived(!!(this.props && this.props.length > 0));

package/src/lib/library.svelte.ts

@@ -1,9 +1,19 @@
 import type {LibraryJson} from '@fuzdev/fuz_util/library_json.js';
 import {ensure_start, strip_end} from '@fuzdev/fuz_util/string.js';
+import type {Url} from '@fuzdev/fuz_util/url.js';
 
 import {create_context} from './context_helpers.js';
 import {Declaration} from './declaration.svelte.js';
 import {Module} from './module.svelte.js';
+import {
+	package_is_published,
+	repo_name_parse,
+	repo_url_github_owner,
+	repo_url_parse,
+	url_github_file,
+	url_logo,
+	url_npm_package,
+} from '@fuzdev/fuz_util/package_helpers.js';
 
 export const library_context = create_context<Library>();
 
@@ -34,37 +44,36 @@ export class Library {
 	 */
 	readonly url_prefix: string;
 
-	readonly package_json = $derived(this.library_json.package_json);
+	readonly pkg_json = $derived(this.library_json.pkg_json);
 	readonly source_json = $derived(this.library_json.source_json);
 
-	readonly name = $derived(this.library_json.name);
-	readonly repo_name = $derived(this.library_json.repo_name);
-	readonly repo_url = $derived(this.library_json.repo_url);
-	readonly owner_name = $derived(this.library_json.owner_name);
-	readonly homepage_url = $derived(this.library_json.homepage_url);
-	readonly logo_url = $derived(this.library_json.logo_url);
-	readonly logo_alt = $derived(this.library_json.logo_alt);
-	readonly npm_url = $derived(this.library_json.npm_url);
-	readonly changelog_url = $derived(this.library_json.changelog_url);
-	readonly published = $derived(this.library_json.published);
+	// Everything below is derived from `pkg_json` — `LibraryJson` stores only the
+	// raw `pkg_json`/`source_json` pair, so derivation lives in exactly one place.
+	readonly name = $derived(this.pkg_json.name);
+	readonly repo_name = $derived(repo_name_parse(this.pkg_json.name));
+	/** Non-null — the constructor rejects a `pkg_json` without a parseable `repository`. */
+	readonly repo_url: Url = $derived(repo_url_parse(this.pkg_json.repository)!);
+	readonly owner_name = $derived(repo_url_github_owner(this.repo_url));
+	readonly homepage_url: Url | null = $derived(this.pkg_json.homepage ?? null);
+	readonly logo_url: Url | null = $derived(url_logo(this.homepage_url, this.pkg_json.logo));
+	readonly logo_alt = $derived(this.pkg_json.logo_alt ?? `logo for ${this.repo_name}`);
+	readonly published = $derived(package_is_published(this.pkg_json));
+	readonly npm_url: Url | null = $derived(this.published ? url_npm_package(this.name) : null);
+	readonly changelog_url: Url | null = $derived(
+		this.published ? url_github_file(this.repo_url, 'CHANGELOG.md') : null,
+	);
 
 	/**
-	 * Organization URL (e.g., 'https://github.com/ryanatkn').
+	 * Organization URL (e.g., 'https://github.com/ryanatkn'), built from `owner_name`.
 	 */
-	readonly org_url = $derived(
-		this.repo_url && this.repo_name
-			? this.repo_url.endsWith('/' + this.repo_name)
-				? this.repo_url.slice(0, -this.repo_name.length - 1)
-				: null
-			: null,
-	);
+	readonly org_url = $derived(this.owner_name ? 'https://github.com/' + this.owner_name : null);
 
 	/**
 	 * All modules as rich `Module` instances.
 	 */
 	readonly modules = $derived(
 		this.source_json.modules
-			? this.source_json.modules.map((module_json) => new Module(this, module_json as any)) // TODO: remove cast when fuz_util SourceJson uses svelte-docinfo types
+			? this.source_json.modules.map((module_json) => new Module(this, module_json))
 			: [],
 	);
 
@@ -91,6 +100,14 @@ export class Library {
 	readonly declaration_by_name = $derived(new Map(this.declarations.map((d) => [d.name, d])));
 
 	constructor(library_json: LibraryJson, url_prefix = '') {
+		// `repo_url` is exposed non-null and several derived URLs depend on it, so
+		// fail loud here rather than letting a missing/unparseable repository surface
+		// as a downstream `null`.
+		if (repo_url_parse(library_json.pkg_json.repository) === null) {
+			throw Error(
+				`failed to construct Library - pkg_json for "${library_json.pkg_json.name}" has no parseable \`repository\``,
+			);
+		}
 		this.library_json = library_json;
 		this.url_prefix = parse_library_url_prefix(url_prefix);
 	}

package/src/lib/library_helpers.ts

@@ -4,7 +4,7 @@
  * Runtime UI helpers for building URLs in the library documentation system.
  * These depend on fuz_ui's documentation paths and SvelteKit's runtime state.
  *
- * For generic package/repository URL helpers, see `package_helpers.ts`.
+ * For generic package/repository URL helpers, see `@fuzdev/fuz_util/package_helpers.js`.
  *
  * @module
  */
@@ -23,8 +23,8 @@ import {page} from '$app/state';
  *
  * @example
  * ```ts
- * // Assuming page.url.origin is 'https://example.com'
- * url_to_root_relative('https://example.com/docs/api')
+ * // Assuming page.url.origin is 'https://fuz.dev'
+ * url_to_root_relative('https://fuz.dev/docs/api')
  * // => '/docs/api'
  * ```
  */

package/src/lib/mdz.ts

@@ -51,8 +51,7 @@ import {
 	HR_HYPHEN_COUNT,
 	MIN_CODEBLOCK_BACKTICKS,
 	MAX_HEADING_LEVEL,
-	HTTPS_PREFIX_LENGTH,
-	HTTP_PREFIX_LENGTH,
+	match_url_prefix_case_insensitive,
 	is_letter,
 	is_tag_name_char,
 	is_word_char,
@@ -64,6 +63,8 @@ import {
 	extract_single_tag,
 	mdz_heading_id,
 	mdz_is_url,
+	mdz_is_safe_reference,
+	mdz_push_merging_text,
 } from './mdz_helpers.js';
 
 // TODO design incremental parsing or some system that preserves Svelte components across re-renders when possible
@@ -689,6 +690,19 @@ export class MdzParser {
 			}
 		}
 
+		// Reject unsafe protocols (javascript:, data:, etc.) — fall back to text.
+		// `is_valid_path_char` permits `:` so a malicious `[x](javascript:...)` would
+		// otherwise pass character validation and reach the renderer.
+		if (!mdz_is_safe_reference(reference)) {
+			this.#index = start + 1;
+			return {
+				type: 'Text',
+				content: '[',
+				start,
+				end: this.#index,
+			};
+		}
+
 		this.#index = close_paren + 1;
 
 		// Determine link type (external vs internal)
@@ -907,27 +921,26 @@ export class MdzParser {
 
 	/**
 	 * Check if current position is the start of an external URL (`https://` or `http://`).
+	 *
+	 * Requires the preceding character (if any) to not be a word character. This
+	 * matches the streaming parser and the spec's "false negatives over false
+	 * positives" policy — `xhttps://...` is treated as plain text rather than
+	 * `x` followed by a link.
+	 *
+	 * Scheme matching is case-insensitive (RFC 3986 §3.1); the original casing
+	 * is preserved in the emitted reference.
 	 */
 	#is_at_url(): boolean {
-		if (this.#match('https://')) {
-			// Check for protocol-only (e.g., just "https://")
-			// Must have at least one non-whitespace character after protocol
-			if (this.#index + HTTPS_PREFIX_LENGTH >= this.#template.length) {
-				return false;
-			}
-			const next_char = this.#template.charCodeAt(this.#index + HTTPS_PREFIX_LENGTH);
-			return next_char !== SPACE && next_char !== NEWLINE;
-		}
-		if (this.#match('http://')) {
-			// Check for protocol-only (e.g., just "http://")
-			// Must have at least one non-whitespace character after protocol
-			if (this.#index + HTTP_PREFIX_LENGTH >= this.#template.length) {
-				return false;
-			}
-			const next_char = this.#template.charCodeAt(this.#index + HTTP_PREFIX_LENGTH);
-			return next_char !== SPACE && next_char !== NEWLINE;
+		// word boundary check: skip when preceded by [A-Za-z0-9]
+		if (this.#index > 0 && is_word_char(this.#template.charCodeAt(this.#index - 1))) {
+			return false;
 		}
-		return false;
+		const prefix_len = match_url_prefix_case_insensitive(this.#template, this.#index);
+		if (prefix_len === 0) return false;
+		// Must have at least one non-whitespace character after protocol
+		if (this.#index + prefix_len >= this.#template.length) return false;
+		const next_char = this.#template.charCodeAt(this.#index + prefix_len);
+		return next_char !== SPACE && next_char !== NEWLINE;
 	}
 
 	/**
@@ -937,12 +950,8 @@ export class MdzParser {
 	#parse_auto_link_url(): MdzLinkNode {
 		const start = this.#index;
 
-		// Consume protocol
-		if (this.#match('https://')) {
-			this.#index += HTTPS_PREFIX_LENGTH;
-		} else if (this.#match('http://')) {
-			this.#index += HTTP_PREFIX_LENGTH;
-		}
+		// Consume protocol (case-insensitive match; original casing preserved in reference)
+		this.#index += match_url_prefix_case_insensitive(this.#template, this.#index);
 
 		// Collect URL characters using RFC 3986 whitelist
 		// Stop at whitespace or any character invalid in URIs
@@ -1065,7 +1074,7 @@ export class MdzParser {
 
 			// Check for URL or internal absolute/relative path mid-text (char code guard avoids startsWith on every char)
 			if (
-				(char_code === 104 /* h */ && this.#is_at_url()) ||
+				((char_code === 104 /* h */ || char_code === 72) /* H */ && this.#is_at_url()) ||
 				(char_code === SLASH && is_at_absolute_path(this.#template, this.#index)) ||
 				(char_code === PERIOD && is_at_relative_path(this.#template, this.#index))
 			) {
@@ -1129,8 +1138,8 @@ export class MdzParser {
 				break;
 			}
 
-			const node = this.#parse_node();
-			nodes.push(node);
+			// merge adjacent Text nodes (e.g., text + failed delimiter + text)
+			mdz_push_merging_text(nodes, this.#parse_node());
 		}
 
 		// Restore previous boundary

package/src/lib/mdz_components.ts

@@ -3,17 +3,35 @@ import type {Component} from 'svelte';
 import {create_context} from './context_helpers.js';
 
 /**
- * Context for providing custom mdz components.
- * Must be set by the application using mdz.
+ * Component registry for custom Svelte components that can be used in mdz content.
+ *
+ * For example, registering 'Alert' allows using `<Alert>...</Alert>` in mdz content.
+ *
+ * The Map values are the Svelte component constructors.
+ */
+export type MdzComponents = Map<string, Component<any, any>>; // TODO support params
+
+/**
+ * Element registry for HTML elements that can be used in mdz content.
+ *
+ * For example, registering 'div' allows using `<div>...</div>` in mdz content.
+ *
+ * The Map values are boolean placeholders for future configuration options.
  */
-export const mdz_components_context = create_context<MdzComponents>();
+export type MdzElements = Map<string, boolean>;
 
 /**
- * Context for providing allowed HTML elements.
- * Must be set by the application using mdz.
+ * Context for providing custom mdz components via a getter function.
+ * Set to a getter (e.g., `() => components`) so changes are reflected reactively.
+ */
+export const mdz_components_context = create_context<() => MdzComponents | undefined>();
+
+/**
+ * Context for providing allowed HTML elements via a getter function.
+ * Set to a getter (e.g., `() => elements`) so changes are reflected reactively.
  * By default, no HTML elements are allowed.
  */
-export const mdz_elements_context = create_context<MdzElements>();
+export const mdz_elements_context = create_context<() => MdzElements | undefined>();
 
 /**
  * Context for providing a base path getter for resolving relative links in mdz content.
@@ -24,20 +42,23 @@ export const mdz_elements_context = create_context<MdzElements>();
  */
 export const mdz_base_context = create_context<() => string | undefined>();
 
-/**
- * Component registry for custom Svelte components that can be used in mdz content.
- *
- * For example, registering 'Alert' allows using `<Alert>...</Alert>` in mdz content.
- *
- * The Map values are the Svelte component constructors.
- */
-export type MdzComponents = Map<string, Component<any, any>>; // TODO support params
+interface MdzGetterContext<T> {
+	get_maybe(): (() => T | undefined) | undefined;
+	set(value: () => T | undefined): unknown;
+}
 
 /**
- * Element registry for HTML elements that can be used in mdz content.
+ * Set an mdz context to a getter that prefers the local `value_fn` and falls
+ * back to the ancestor's value when `value_fn()` returns `undefined`.
  *
- * For example, registering 'div' allows using `<div>...</div>` in mdz content.
- *
- * The Map values are boolean placeholders for future configuration options.
+ * Pass `value_fn` as a getter (not a snapshot) so prop changes remain reactive.
+ * The ancestor lookup happens once at component init — that's intentional, it
+ * captures the surrounding scope's context at mount time.
  */
-export type MdzElements = Map<string, boolean>;
+export const set_mdz_context_with_fallback = <T>(
+	context: MdzGetterContext<T>,
+	value_fn: () => T | undefined,
+): void => {
+	const ancestor = context.get_maybe();
+	context.set(() => value_fn() ?? ancestor?.());
+};