@fuzdev/fuz_ui 0.193.1 → 0.195.0

package/dist/library_gen.js

@@ -1,25 +1,32 @@
 /**
  * Gro-specific library metadata generation.
  *
- * This module provides Gro integration for library generation. It wraps the generic
- * `library_generate` function with Gro's `Gen` interface and provides adapters for
- * converting Gro's `Disknode` to the build-tool agnostic `SourceFileInfo`.
+ * This module provides Gro integration for library generation. It uses svelte-docinfo's
+ * pure analysis (`analyze`) and wraps the results with fuz_ui's opinionated
+ * LibraryJson format (GitHub/npm metadata).
  *
- * For build-tool agnostic usage, see `library_generate.ts`.
+ * For build-tool agnostic usage, see `svelte-docinfo`.
  *
- * @see `library_generate.ts` for the generic generation entry point
- * @see `library_pipeline.ts` for pipeline helpers
- * @see `library_output.ts` for output file generation
+ * @see svelte-docinfo/analyze.js for the generic analysis entry point
+ * @see svelte-docinfo/postprocess.js for post-processing helpers
+ * @see library_output.js for output file generation
  *
  * @module
  */
 import { package_json_load } from '@fuzdev/gro/package_json.js';
-import { module_create_source_options, module_validate_source_options, module_is_source, module_get_source_root, } from './module_helpers.js';
-import { library_generate } from './library_generate.js';
+import { analyze, createSourceOptions, } from 'svelte-docinfo';
+import { normalizeSourceOptions, isSource, getSourceRoot } from 'svelte-docinfo/source-config.js';
+import { library_generate_output } from './library_output.js';
 /**
  * Convert Gro's `Disknode` to the build-tool agnostic `SourceFileInfo` interface.
  *
- * Use this when you want to analyze files using Gro's filer directly.
+ * Use this when you want to analyze files using Gro's filer directly. The
+ * `dependencies` field is populated from the filer's forward-edge graph — the
+ * svelte-docinfo session honors it as pre-resolved input and skips its own
+ * lex+resolve pass for these files, avoiding duplicate work the filer already did.
+ *
+ * Reverse edges (`dependents`) are not threaded through — svelte-docinfo
+ * computes them internally from the forward edges of the owned set.
  *
  * @throws Error if disknode has no content (should be loaded by Gro filer)
  */
@@ -31,14 +38,13 @@ export const source_file_from_disknode = (disknode) => {
         id: disknode.id,
         content: disknode.contents,
         dependencies: [...disknode.dependencies.keys()],
-        dependents: [...disknode.dependents.keys()],
     };
 };
 /**
  * Collect source files from Gro disknodes, filtering BEFORE conversion to `SourceFileInfo`.
  *
  * This avoids errors from files outside source directories (like test fixtures that may
- * have malformed paths or missing content). The filtering uses `module_is_source` which
+ * have malformed paths or missing content). The filtering uses `isSource` which
  * checks `source_paths` to only include files in configured source directories.
  *
  * @param disknodes - iterator of Gro disknodes from filer
@@ -46,22 +52,24 @@ export const source_file_from_disknode = (disknode) => {
  * @param log - optional logger for status messages
  */
 export const library_collect_source_files_from_disknodes = (disknodes, options, log) => {
-    // Validate options early to fail fast on misconfiguration
-    module_validate_source_options(options);
+    // Normalize options (throws on invalid config) and use the normalized form
+    // for downstream `isSource` / `getSourceRoot` calls, so callers that pass
+    // raw options (not via `createSourceOptions`) get consistent path handling.
+    const normalized_options = normalizeSourceOptions(options);
     const all_disknodes = Array.from(disknodes);
     log?.info(`received ${all_disknodes.length} files total from filer`);
     const source_files = [];
     for (const disknode of all_disknodes) {
         // Filter by source_paths BEFORE trying to convert
         // This avoids errors from test fixtures or other non-source files
-        if (!module_is_source(disknode.id, options)) {
+        if (!isSource(disknode.id, normalized_options)) {
             continue;
         }
         source_files.push(source_file_from_disknode(disknode));
     }
     log?.info(`found ${source_files.length} source files to analyze`);
     if (source_files.length === 0) {
-        const effective_root = module_get_source_root(options);
+        const effective_root = getSourceRoot(normalized_options);
         log?.warn(`No source files found in ${effective_root} - generating empty library metadata`);
         return [];
     }
@@ -74,10 +82,12 @@ export const library_collect_source_files_from_disknodes = (disknodes, options,
  *
  * This is the Gro-specific entry point. It handles:
  * - Reading files from Gro's filer
- * - Loading `package.json` via Gro utilities
- * - Returning output in Gro's `Gen` format
+ * - Loading package.json via Gro utilities
+ * - Analyzing source with svelte-docinfo (pure analysis)
+ * - Wrapping with LibraryJson (GitHub/npm metadata)
+ * - Returning output in Gro's Gen format
  *
- * For build-tool agnostic usage, use `library_generate` directly.
+ * For build-tool agnostic usage, use `analyze` directly.
  *
  * Usage in a `.gen.ts` file:
  *
@@ -95,29 +105,39 @@ export const library_gen = (options) => {
         generate: async ({ log, filer }) => {
             log.info('generating library metadata with full TypeScript analysis...');
             // Build source options with project_root from cwd
-            const source_options = options?.source && 'project_root' in options.source
+            const source_options = options?.source && 'projectRoot' in options.source
                 ? options.source
-                : module_create_source_options(process.cwd(), options?.source);
+                : createSourceOptions(process.cwd(), options?.source);
             // Ensure filer is initialized
             await filer.init();
             // Read package.json
             const package_json = await package_json_load();
             // Collect source files from Gro filer
             const source_files = library_collect_source_files_from_disknodes(filer.files.values(), source_options, log);
-            // Use generic library_generate for the actual work
-            const result = library_generate({
-                source_files,
-                package_json,
-                source_options,
-                on_duplicates: options?.on_duplicates,
-                log,
+            // Get pure analysis from svelte-docinfo (no package metadata).
+            const { modules } = await analyze({
+                sourceFiles: source_files,
+                sourceOptions: source_options,
+                onDuplicates: options?.on_duplicates,
+                log: log, // Type cast needed due to workspace dependency duplication
             });
+            if (!package_json.version) {
+                throw new Error('package.json is missing required "version" field');
+            }
+            // Wrap modules with package metadata (fuz_ui's own SourceJson type)
+            const source_json = {
+                name: package_json.name,
+                version: package_json.version,
+                repository: typeof package_json.repository === 'string'
+                    ? package_json.repository
+                    : package_json.repository?.url,
+                modules: modules, // TODO: remove cast when fuz_util SourceJson uses svelte-docinfo types
+            };
+            // Generate output files with fuz_ui's LibraryJson wrapper
+            const { json_content, ts_content } = library_generate_output(package_json, source_json);
             log.info('library metadata generation complete');
             // Return array of files in Gro's expected format
-            return [
-                { content: result.ts_content },
-                { content: result.json_content, filename: 'library.json' },
-            ];
+            return [{ content: ts_content }, { content: json_content, filename: 'library.json' }];
         },
     };
 };

package/dist/library_output.d.ts

@@ -1,11 +1,12 @@
 /**
  * Library output generation.
  *
- * Generates the `library.json` and `library.ts` files from analyzed metadata.
+ * Generates the library.json and library.ts files from analyzed metadata.
+ * Uses svelte-docinfo's `compactReplacer` to strip Zod default values
+ * (empty arrays, false booleans) for compact JSON output.
  *
- * @see `library_generate.ts` for the main generation entry point
- * @see `library_pipeline.ts` for pipeline orchestration functions
- * @see `library_gen.ts` for Gro-specific integration
+ * @see `library_gen.ts` for the main generation entry point
+ * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
  *
  * @module
  */

package/dist/library_output.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"library_output.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,iCAAiC,CAAC;AAGhE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,cAAc,WAAW,EACzB,aAAa,UAAU,KACrB,mBAuBF,CAAC"}
+{"version":3,"file":"library_output.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library_output.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kCAAkC,CAAC;AAClE,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,iCAAiC,CAAC;AAIhE;;;GAGG;AACH,MAAM,WAAW,mBAAmB;IACnC,uCAAuC;IACvC,YAAY,EAAE,MAAM,CAAC;IACrB,mDAAmD;IACnD,UAAU,EAAE,MAAM,CAAC;CACnB;AAED;;;;;;;;;GASG;AACH,eAAO,MAAM,uBAAuB,GACnC,cAAc,WAAW,EACzB,aAAa,UAAU,KACrB,mBAwBF,CAAC"}

package/dist/library_output.js

@@ -1,15 +1,17 @@
 /**
  * Library output generation.
  *
- * Generates the `library.json` and `library.ts` files from analyzed metadata.
+ * Generates the library.json and library.ts files from analyzed metadata.
+ * Uses svelte-docinfo's `compactReplacer` to strip Zod default values
+ * (empty arrays, false booleans) for compact JSON output.
  *
- * @see `library_generate.ts` for the main generation entry point
- * @see `library_pipeline.ts` for pipeline orchestration functions
- * @see `library_gen.ts` for Gro-specific integration
+ * @see `library_gen.ts` for the main generation entry point
+ * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
  *
  * @module
  */
 import { library_json_parse } from '@fuzdev/fuz_util/library_json.js';
+import { compactReplacer } from 'svelte-docinfo';
 /**
  * Generate the `library.json` and `library.ts` file contents.
  * Parses at generation time so runtime only needs the pre-computed result.
@@ -21,15 +23,16 @@ import { library_json_parse } from '@fuzdev/fuz_util/library_json.js';
  *   (JSON imports get widened types like `string` instead of literal unions)
  */
 export const library_generate_output = (package_json, source_json) => {
-    const is_this_fuz_util = package_json.name === '@fuzdev/fuz_util';
-    const fuz_util_prefix = is_this_fuz_util ? './' : '@fuzdev/fuz_util/';
+    // Compact source_json (strips Zod default values like empty arrays and false booleans)
+    // Only applied to source_json, not the outer library_json package metadata
+    const compacted_source_json = JSON.parse(JSON.stringify(source_json, compactReplacer));
     // Parse at generation time, not runtime
-    const library_json = library_json_parse(package_json, source_json);
+    const library_json = library_json_parse(package_json, compacted_source_json);
     const json_content = JSON.stringify(library_json, null, '\t') + '\n';
     const banner = '// generated by library.gen.ts - do not edit';
     const ts_content = `${banner}
 
-import type {LibraryJson} from '${fuz_util_prefix}library_json.js';
+import type {LibraryJson} from '@fuzdev/fuz_util/library_json.js';
 
 import json from './library.json' with {type: 'json'};
 

package/dist/mdz_components.d.ts

@@ -1,20 +1,4 @@
 import type { Component } from 'svelte';
-/**
- * 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>>;
-/**
- * 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 type MdzElements = Map<string, boolean>;
 /**
  * Context for providing custom mdz components.
  * Must be set by the application using mdz.
@@ -46,4 +30,20 @@ export declare const mdz_base_context: {
     get_maybe: () => (() => string | undefined) | undefined;
     set: (value: () => string | undefined) => () => 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>>;
+/**
+ * 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 type MdzElements = Map<string, boolean>;
 //# sourceMappingURL=mdz_components.d.ts.map

package/dist/mdz_components.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mdz_components.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz_components.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,QAAQ,CAAC;AAItC;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE/C;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;CAAkC,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;CAAgC,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;2CAAwB,MAAM,GAAG,SAAS;4BAAlB,MAAM,GAAG,SAAS;uBAAlB,MAAM,GAAG,SAAS,WAAlB,MAAM,GAAG,SAAS;CAAG,CAAC"}
+{"version":3,"file":"mdz_components.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz_components.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,QAAQ,CAAC;AAItC;;;GAGG;AACH,eAAO,MAAM,sBAAsB;;;;CAAkC,CAAC;AAEtE;;;;GAIG;AACH,eAAO,MAAM,oBAAoB;;;;CAAgC,CAAC;AAElE;;;;;;GAMG;AACH,eAAO,MAAM,gBAAgB;2CAAwB,MAAM,GAAG,SAAS;4BAAlB,MAAM,GAAG,SAAS;uBAAlB,MAAM,GAAG,SAAS,WAAlB,MAAM,GAAG,SAAS;CAAG,CAAC;AAE3E;;;;;;GAMG;AACH,MAAM,MAAM,aAAa,GAAG,GAAG,CAAC,MAAM,EAAE,SAAS,CAAC,GAAG,EAAE,GAAG,CAAC,CAAC,CAAC;AAE7D;;;;;;GAMG;AACH,MAAM,MAAM,WAAW,GAAG,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC"}

package/dist/module.svelte.d.ts

@@ -1,14 +1,28 @@
-import type { ModuleJson } from '@fuzdev/fuz_util/source_json.js';
+import type { ModuleJsonInput } from 'svelte-docinfo/types.js';
 import { Declaration } from './declaration.svelte.js';
 import type { Library } from './library.svelte.js';
 /**
  * Rich runtime representation of a module with computed properties.
+ *
+ * Wraps svelte-docinfo's `ModuleJson` with reactive derivations,
+ * URL generation, and `Declaration` instances.
+ *
+ * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
+ * @see `declaration.svelte.ts` for the `Declaration` wrapper class
  */
 export declare class Module {
     readonly library: Library;
-    readonly module_json: ModuleJson;
-    /**
-     * Canonical module path (e.g., 'Alert.ts', 'helpers/foo.ts').
+    readonly module_json: ModuleJsonInput;
+    /**
+     * Canonical module path — `src/lib/`-relative, with source extension
+     * (`.ts`, `.svelte`, etc.). Examples: `'Alert.ts'`, `'helpers/foo.ts'`,
+     * `'actions/composables.ts'`.
+     *
+     * This is the key `Library.module_by_path` indexes, so it's also the
+     * exact string TSDoc backtick references must use to auto-link to a
+     * module via `DocsLink.svelte` (e.g., `` `actions/composables.ts` ``).
+     * A leading `./` or a `.js` runtime extension will not match. Top-level
+     * files match by bare filename; nested files require the full sub-path.
      */
     path: string;
     /**
@@ -33,12 +47,12 @@ export declare class Module {
     /**
      * Modules this imports (paths relative to src/lib).
      */
-    dependencies: string[] | undefined;
+    dependencies: string[];
     /**
      * Modules that import this (paths relative to src/lib).
      */
-    dependents: string[] | undefined;
-    constructor(library: Library, module_json: ModuleJson);
+    dependents: string[];
+    constructor(library: Library, module_json: ModuleJsonInput);
     /**
      * Look up a declaration by name within this module.
      */

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

@@ -1 +1 @@
-{"version":3,"file":"module.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/module.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,UAAU,EAAC,MAAM,iCAAiC,CAAC;AAEhE,OAAO,EAAC,WAAW,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,qBAAqB,CAAC;AAGjD;;GAEG;AACH,qBAAa,MAAM;IAClB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAiB;IAC1C,QAAQ,CAAC,WAAW,EAAE,UAAU,CAAiB;IAEjD;;OAEG;IACH,IAAI,SAAmC;IAEvC;;OAEG;IACH,WAAW,SAA8B;IAEzC,cAAc,qBAA6C;IAE3D;;OAEG;IACH,YAAY,gBAMV;IAEF;;OAEG;IACH,OAAO,SAAgE;IAEvE;;OAEG;IACH,UAAU,qBAIR;IAEF,gBAAgB,EAAE,OAAO,CAEvB;IAEF,kBAAkB,EAAE,OAAO,CAA+C;IAE1E;;OAEG;IACH,YAAY,uBAA2C;IAEvD;;OAEG;IACH,UAAU,uBAAyC;gBAEvC,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,UAAU;IAKrD;;OAEG;IACH,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;CAG9D"}
+{"version":3,"file":"module.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/module.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,yBAAyB,CAAC;AAE7D,OAAO,EAAC,WAAW,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,KAAK,EAAC,OAAO,EAAC,MAAM,qBAAqB,CAAC;AAGjD;;;;;;;;GAQG;AACH,qBAAa,MAAM;IAClB,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAiB;IAI1C,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAiB;IAEtD;;;;;;;;;;OAUG;IACH,IAAI,SAAmC;IAEvC;;OAEG;IACH,WAAW,SAA8B;IAEzC,cAAc,qBAA4C;IAE1D;;OAEG;IACH,YAAY,gBAIV;IAEF;;OAEG;IACH,OAAO,SAAgE;IAEvE;;OAEG;IACH,UAAU,qBAIR;IAEF,gBAAgB,EAAE,OAAO,CAA8D;IAEvF,kBAAkB,EAAE,OAAO,CAAmC;IAE9D;;OAEG;IACH,YAAY,WAAiD;IAE7D;;OAEG;IACH,UAAU,WAA+C;gBAE7C,OAAO,EAAE,OAAO,EAAE,WAAW,EAAE,eAAe;IAK1D;;OAEG;IACH,uBAAuB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;CAG9D"}

package/dist/module.svelte.js

@@ -2,27 +2,42 @@ import { Declaration } from './declaration.svelte.js';
 import { url_github_file } from './package_helpers.js';
 /**
  * Rich runtime representation of a module with computed properties.
+ *
+ * Wraps svelte-docinfo's `ModuleJson` with reactive derivations,
+ * URL generation, and `Declaration` instances.
+ *
+ * @see {@link https://github.com/ryanatkn/svelte-docinfo svelte-docinfo} for the analysis library
+ * @see `declaration.svelte.ts` for the `Declaration` wrapper class
  */
 export class Module {
     library = $state.raw();
+    // `library.json` is compacted (svelte-docinfo's `compactReplacer` strips empty
+    // default arrays), so the on-disk data is the `*Input` shape. Typing it as
+    // input makes TypeScript force guards on defaulted-array reads.
     module_json = $state.raw();
     /**
-     * Canonical module path (e.g., 'Alert.ts', 'helpers/foo.ts').
+     * Canonical module path — `src/lib/`-relative, with source extension
+     * (`.ts`, `.svelte`, etc.). Examples: `'Alert.ts'`, `'helpers/foo.ts'`,
+     * `'actions/composables.ts'`.
+     *
+     * This is the key `Library.module_by_path` indexes, so it's also the
+     * exact string TSDoc backtick references must use to auto-link to a
+     * module via `DocsLink.svelte` (e.g., `` `actions/composables.ts` ``).
+     * A leading `./` or a `.js` runtime extension will not match. Top-level
+     * files match by bare filename; nested files require the full sub-path.
      */
     path = $derived(this.module_json.path);
     /**
      * Import-style path with ./ prefix.
      */
     path_import = $derived('./' + this.path);
-    module_comment = $derived(this.module_json.module_comment);
+    module_comment = $derived(this.module_json.moduleComment);
     /**
      * Array of `Declaration` instances. Filters out default exports.
      */
-    declarations = $derived(this.module_json.declarations
-        ? this.module_json.declarations
-            .filter((declaration_json) => declaration_json.name !== 'default')
-            .map((declaration_json) => new Declaration(this, declaration_json))
-        : []);
+    declarations = $derived((this.module_json.declarations ?? [])
+        .filter((declaration_json) => declaration_json.name !== 'default')
+        .map((declaration_json) => new Declaration(this, declaration_json)));
     /**
      * API documentation URL for this module.
      */
@@ -33,16 +48,16 @@ export class Module {
     url_github = $derived(this.library.repo_url
         ? url_github_file(this.library.repo_url, `src/lib/${this.path}`)
         : undefined);
-    has_declarations = $derived(!!(this.module_json.declarations && this.module_json.declarations.length > 0));
-    has_module_comment = $derived(!!this.module_json.module_comment);
+    has_declarations = $derived((this.module_json.declarations?.length ?? 0) > 0);
+    has_module_comment = $derived(!!this.module_comment);
     /**
      * Modules this imports (paths relative to src/lib).
      */
-    dependencies = $derived(this.module_json.dependencies);
+    dependencies = $derived(this.module_json.dependencies ?? []);
     /**
      * Modules that import this (paths relative to src/lib).
      */
-    dependents = $derived(this.module_json.dependents);
+    dependents = $derived(this.module_json.dependents ?? []);
     constructor(library, module_json) {
         this.library = library;
         this.module_json = module_json;

package/dist/style_variable_helpers.svelte.d.ts

@@ -1,10 +1,10 @@
 import type { StyleVariable } from '@fuzdev/fuz_css/variable.js';
-export declare class SelectedStyleVariable {
-    value: StyleVariable | null;
-    constructor(initial?: StyleVariable | null);
-}
 export declare const selected_variable_context: {
     get: () => SelectedStyleVariable;
     set: (value?: SelectedStyleVariable | undefined) => SelectedStyleVariable;
 };
+export declare class SelectedStyleVariable {
+    value: StyleVariable | null;
+    constructor(initial?: StyleVariable | null);
+}
 //# sourceMappingURL=style_variable_helpers.svelte.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"style_variable_helpers.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/style_variable_helpers.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAK/D,qBAAa,qBAAqB;IACjC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAiB;gBAEhC,OAAO,GAAE,aAAa,GAAG,IAAW;CAGhD;AAED,eAAO,MAAM,yBAAyB;;;CAAwD,CAAC"}
+{"version":3,"file":"style_variable_helpers.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/style_variable_helpers.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,aAAa,EAAC,MAAM,6BAA6B,CAAC;AAI/D,eAAO,MAAM,yBAAyB;;;CAAwD,CAAC;AAG/F,qBAAa,qBAAqB;IACjC,KAAK,EAAE,aAAa,GAAG,IAAI,CAAiB;gBAEhC,OAAO,GAAE,aAAa,GAAG,IAAW;CAGhD"}

package/dist/style_variable_helpers.svelte.js

@@ -1,4 +1,5 @@
 import { create_context } from './context_helpers.js';
+export const selected_variable_context = create_context(() => new SelectedStyleVariable(null));
 // TODO maybe change this to a generic wrapper class for any value?
 export class SelectedStyleVariable {
     value = $state.raw();
@@ -6,4 +7,3 @@ export class SelectedStyleVariable {
         this.value = initial;
     }
 }
-export const selected_variable_context = create_context(() => new SelectedStyleVariable(null));

package/dist/tome.d.ts

@@ -1,5 +1,15 @@
 import type { Component } from 'svelte';
 import { z } from 'zod';
+export declare const tomes_context: {
+    get: (error_message?: string) => () => Map<string, Tome>;
+    get_maybe: () => (() => Map<string, Tome>) | undefined;
+    set: (value: () => Map<string, Tome>) => () => Map<string, Tome>;
+};
+export declare const tome_context: {
+    get: (error_message?: string) => () => Tome;
+    get_maybe: () => (() => Tome) | undefined;
+    set: (value: () => Tome) => () => Tome;
+};
 export declare const Tome: z.ZodObject<{
     slug: z.ZodString;
     title: z.ZodOptional<z.ZodString>;
@@ -18,15 +28,5 @@ export declare const tome_to_pathname: (item: Tome | string, docs_path?: string,
  * The display label for a tome — its `title` if set, else its `slug`.
  */
 export declare const tome_to_title: (tome: Tome) => string;
-export declare const tomes_context: {
-    get: (error_message?: string) => () => Map<string, Tome>;
-    get_maybe: () => (() => Map<string, Tome>) | undefined;
-    set: (value: () => Map<string, Tome>) => () => Map<string, Tome>;
-};
 export declare const tome_get_by_slug: (slug: string) => Tome;
-export declare const tome_context: {
-    get: (error_message?: string) => () => Tome;
-    get_maybe: () => (() => Tome) | undefined;
-    set: (value: () => Tome) => () => Tome;
-};
 //# sourceMappingURL=tome.d.ts.map

package/dist/tome.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tome.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tome.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAMtB,eAAO,MAAM,IAAI;;;;;;;;iBAoBf,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC5B,MAAM,IAAI,GAAG,MAAM,EACnB,kBAA6B,EAC7B,OAAO,MAAM,KACX,MAIF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,IAAI,KAAG,MAAiC,CAAC;AAE7E,eAAO,MAAM,aAAa;2CAAwB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;4BAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;uBAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,WAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;CAAG,CAAC;AAEvE,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,IAK/C,CAAC;AAEF,eAAO,MAAM,YAAY;2CAAwB,IAAI;4BAAJ,IAAI;uBAAJ,IAAI,WAAJ,IAAI;CAAG,CAAC"}
+{"version":3,"file":"tome.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tome.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAC,SAAS,EAAC,MAAM,QAAQ,CAAC;AACtC,OAAO,EAAC,CAAC,EAAC,MAAM,KAAK,CAAC;AAMtB,eAAO,MAAM,aAAa;2CAAwB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;4BAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;uBAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC,WAAjB,GAAG,CAAC,MAAM,EAAE,IAAI,CAAC;CAAG,CAAC;AAEvE,eAAO,MAAM,YAAY;2CAAwB,IAAI;4BAAJ,IAAI;uBAAJ,IAAI,WAAJ,IAAI;CAAG,CAAC;AAEzD,eAAO,MAAM,IAAI;;;;;;;;iBAoBf,CAAC;AACH,MAAM,MAAM,IAAI,GAAG,CAAC,CAAC,KAAK,CAAC,OAAO,IAAI,CAAC,CAAC;AAExC;;GAEG;AACH,eAAO,MAAM,gBAAgB,GAC5B,MAAM,IAAI,GAAG,MAAM,EACnB,kBAA6B,EAC7B,OAAO,MAAM,KACX,MAIF,CAAC;AAEF;;GAEG;AACH,eAAO,MAAM,aAAa,GAAI,MAAM,IAAI,KAAG,MAAiC,CAAC;AAE7E,eAAO,MAAM,gBAAgB,GAAI,MAAM,MAAM,KAAG,IAK/C,CAAC"}

package/dist/tome.js

@@ -3,6 +3,8 @@ import { z } from 'zod';
 import { ensure_start } from '@fuzdev/fuz_util/string.js';
 import { create_context } from './context_helpers.js';
 import { DOCS_PATH_DEFAULT } from './docs_helpers.svelte.js';
+export const tomes_context = create_context();
+export const tome_context = create_context();
 export const Tome = z.object({
     /**
      * Stable identifier and URL path segment — must be a URL-safe slug
@@ -36,7 +38,6 @@ export const tome_to_pathname = (item, docs_path = DOCS_PATH_DEFAULT, hash) => {
  * The display label for a tome — its `title` if set, else its `slug`.
  */
 export const tome_to_title = (tome) => tome.title ?? tome.slug;
-export const tomes_context = create_context();
 export const tome_get_by_slug = (slug) => {
     const get_tomes = tomes_context.get();
     const tome = get_tomes().get(slug);
@@ -44,4 +45,3 @@ export const tome_get_by_slug = (slug) => {
         throw Error(`unable to find tome "${slug}"`);
     return tome;
 };
-export const tome_context = create_context();

package/dist/tsdoc_mdz.d.ts

@@ -11,10 +11,12 @@
  * Convert raw TSDoc `@see` content to mdz format for rendering.
  *
  * Handles TSDoc link syntax:
- * - `{@link url|text}` → `[text](url)` (markdown link)
+ * - `{@link url|text}` → `[text](url)` (markdown link, TSDoc canonical form)
+ * - `{@link url text}` → `[text](url)` (TS-lenient space-separated form)
  * - `{@link https://...}` → `https://...` (bare URL, auto-linked by mdz)
  * - `{@link identifier}` → `` `identifier` `` (code formatting)
  * - Bare URLs → returned as-is
+ * - Bare markdown links (`[text](url)` ...) → returned as-is
  * - Bare identifiers → wrapped in backticks
  * - `identifier description text` → `` `identifier` description text `` (first token is the reference)
  *
@@ -32,6 +34,9 @@
  * tsdoc_see_to_mdz('https://example.com')
  * // → 'https://example.com'
  *
+ * 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'
+ *
  * tsdoc_see_to_mdz('library_gen.ts for Gro-specific integration')
  * // → '`library_gen.ts` for Gro-specific integration'
  * ```

package/dist/tsdoc_mdz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tsdoc_mdz.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_mdz.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA4BG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,MA6BlD,CAAC"}
+{"version":3,"file":"tsdoc_mdz.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_mdz.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAOH;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,MA+ClD,CAAC"}

package/dist/tsdoc_mdz.js

@@ -14,10 +14,12 @@ const format_reference = (ref) => (mdz_is_url(ref) ? ref : `\`${ref}\``);
  * Convert raw TSDoc `@see` content to mdz format for rendering.
  *
  * Handles TSDoc link syntax:
- * - `{@link url|text}` → `[text](url)` (markdown link)
+ * - `{@link url|text}` → `[text](url)` (markdown link, TSDoc canonical form)
+ * - `{@link url text}` → `[text](url)` (TS-lenient space-separated form)
  * - `{@link https://...}` → `https://...` (bare URL, auto-linked by mdz)
  * - `{@link identifier}` → `` `identifier` `` (code formatting)
  * - Bare URLs → returned as-is
+ * - Bare markdown links (`[text](url)` ...) → returned as-is
  * - Bare identifiers → wrapped in backticks
  * - `identifier description text` → `` `identifier` description text `` (first token is the reference)
  *
@@ -35,6 +37,9 @@ const format_reference = (ref) => (mdz_is_url(ref) ? ref : `\`${ref}\``);
  * tsdoc_see_to_mdz('https://example.com')
  * // → 'https://example.com'
  *
+ * 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'
+ *
  * tsdoc_see_to_mdz('library_gen.ts for Gro-specific integration')
  * // → '`library_gen.ts` for Gro-specific integration'
  * ```
@@ -47,15 +52,31 @@ export const tsdoc_see_to_mdz = (content) => {
     const link_match = /^\{@(?:link|see)\s+([^}]+)\}$/.exec(trimmed);
     if (link_match) {
         const inner = link_match[1].trim();
-        // Check for pipe separator (custom display text)
+        // Pipe separator takes precedence (TSDoc canonical form)
         const pipe_index = inner.indexOf('|');
         if (pipe_index !== -1) {
             const reference = inner.slice(0, pipe_index).trim();
             const display_text = inner.slice(pipe_index + 1).trim();
             return `[${display_text}](${reference})`;
         }
+        // Space-separated form: TS accepts `{@link url text}` as equivalent to `{@link url|text}`.
+        // Only treat space as a separator when the first token looks like a link target (URL),
+        // so identifier-style references like `module.function` aren't split.
+        const space_index = inner.indexOf(' ');
+        if (space_index !== -1) {
+            const reference = inner.slice(0, space_index);
+            if (mdz_is_url(reference)) {
+                const display_text = inner.slice(space_index + 1).trim();
+                return `[${display_text}](${reference})`;
+            }
+        }
         return format_reference(inner);
     }
+    // Pass through bare markdown links (`[text](url)` optionally followed by description)
+    // so authors can write `@see [text](url) for context` directly.
+    if (trimmed.charCodeAt(0) === 91 /* [ */ && /^\[[^\]]+\]\([^)\s]+\)/.test(trimmed)) {
+        return trimmed;
+    }
     // Split at first whitespace: first token is the reference, rest is description
     const space_index = trimmed.indexOf(' ');
     if (space_index === -1) {