@fuzdev/fuz_ui 0.184.0 → 0.185.1

package/dist/declaration.svelte.d.ts

@@ -52,6 +52,15 @@ export declare class Declaration {
         description?: string | undefined;
         default_value?: string | undefined;
         bindable?: boolean | undefined;
+        examples?: string[] | undefined;
+        deprecated_message?: string | undefined;
+        see_also?: string[] | undefined;
+        throws?: {
+            [x: string]: unknown;
+            description: string;
+            type?: string | undefined;
+        }[] | undefined;
+        since?: string | undefined;
     }[] | undefined;
     return_type: string | undefined;
     return_description: string | undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"declaration.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/declaration.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,eAAe,EAGpB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,oBAAoB,CAAC;AAG/C;;GAEG;AACH,qBAAa,WAAW;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAiB;IACxC,QAAQ,CAAC,gBAAgB,EAAE,eAAe,CAAiB;IAE3D,OAAO,wCAAiC;IAExC;;OAEG;IACH,WAAW,SAA8B;IAEzC,IAAI,SAAwC;IAC5C,IAAI,4FAAwC;IAE5C;;OAEG;IACH,UAAU,qBAQR;IAEF;;OAEG;IACH,OAAO,SAAoF;IAE3F;;OAEG;IACH,gBAAgB,SAMd;IAEF;;OAEG;IACH,YAAY,qBAIV;IAEF;;OAEG;IACH,YAAY,SAAiE;IAE7E,cAAc,qBAAkD;IAChE,WAAW,qBAA+C;IAC1D,kBAAkB,qBAAsD;IACxE,UAAU;;;;;;;oBAA8C;IACxD,KAAK;;;;;;;;oBAAyC;IAC9C,WAAW,qBAA+C;IAC1D,kBAAkB,qBAAsD;IACxE,cAAc;;;;;oBAAkD;IAChE,OAAO,uBAA2C;IAClD,UAAU,uBAA8C;IACxD,MAAM;;;;oBAA0C;IAChD,KAAK,qBAAyC;IAC9C,QAAQ,uBAA4C;IACpD,QAAQ,uBAA4C;IACpD,OAAO,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,SAAS,CAEzC;IACF,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,SAAS,CAE5C;IAEF,YAAY,UAA2D;IACvE,aAAa,UAAuC;IACpD,iBAAiB,UAAgC;IACjD,cAAc,UAA+D;IAC7E,SAAS,UAAqD;IAC9D,YAAY,UAAuE;gBAEvE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe;CAI7D"}
+{"version":3,"file":"declaration.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/declaration.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,EACN,KAAK,eAAe,EAGpB,MAAM,iCAAiC,CAAC;AAEzC,OAAO,KAAK,EAAC,MAAM,EAAC,MAAM,oBAAoB,CAAC;AAK/C;;GAEG;AACH,qBAAa,WAAW;IACvB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAiB;IACxC,QAAQ,CAAC,gBAAgB,EAAE,eAAe,CAAiB;IAE3D,OAAO,wCAAiC;IAExC;;OAEG;IACH,WAAW,SAA8B;IAEzC,IAAI,SAAwC;IAC5C,IAAI,4FAAwC;IAE5C;;OAEG;IACH,UAAU,qBAQR;IAEF;;OAEG;IACH,OAAO,SAAoF;IAE3F;;OAEG;IACH,gBAAgB,SAMd;IAEF;;OAEG;IACH,YAAY,qBAIV;IAEF;;OAEG;IACH,YAAY,SAAiE;IAE7E,cAAc,qBAAkD;IAChE,WAAW,qBAA+C;IAC1D,kBAAkB,qBAAsD;IACxE,UAAU;;;;;;;oBAA8C;IACxD,KAAK;;;;;;;;;;;;;;;;;oBAAyC;IAC9C,WAAW,qBAA+C;IAC1D,kBAAkB,qBAAsD;IACxE,cAAc;;;;;oBAAkD;IAChE,OAAO,uBAA2C;IAClD,UAAU,uBAA8C;IACxD,MAAM;;;;oBAA0C;IAChD,KAAK,qBAAyC;IAC9C,QAAQ,uBAA4C;IACpD,QAAQ,uBAA4C;IACpD,OAAO,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,SAAS,CAEzC;IACF,UAAU,EAAE,KAAK,CAAC,eAAe,CAAC,GAAG,SAAS,CAE5C;IAEF,YAAY,UAA2D;IACvE,aAAa,UAAuC;IACpD,iBAAiB,UAAgC;IACjD,cAAc,UAA+D;IAC7E,SAAS,UAAqD;IAC9D,YAAY,UAAuE;gBAEvE,MAAM,EAAE,MAAM,EAAE,gBAAgB,EAAE,eAAe;CAI7D"}

package/dist/declaration.svelte.js

@@ -1,5 +1,6 @@
 import { declaration_generate_import, declaration_get_display_name, } from '@fuzdev/fuz_util/source_json.js';
 import { url_github_file } from './package_helpers.js';
+/* eslint-disable @typescript-eslint/no-deprecated */
 /**
  * Rich runtime representation of an exported declaration.
  */

package/dist/library.svelte.d.ts

@@ -126,6 +126,7 @@ export declare class Library {
                     type?: string | undefined;
                 }[] | undefined;
                 since?: string | undefined;
+                mutates?: Record<string, string> | undefined;
                 extends?: string[] | undefined;
                 implements?: string[] | undefined;
                 members?: Record<string, unknown>[] | undefined;
@@ -138,11 +139,21 @@ export declare class Library {
                     description?: string | undefined;
                     default_value?: string | undefined;
                     bindable?: boolean | undefined;
+                    examples?: string[] | undefined;
+                    deprecated_message?: string | undefined;
+                    see_also?: string[] | undefined;
+                    throws?: {
+                        [x: string]: unknown;
+                        description: string;
+                        type?: string | undefined;
+                    }[] | undefined;
+                    since?: string | undefined;
                 }[] | undefined;
                 also_exported_from?: string[] | undefined;
                 alias_of?: {
                     module: string;
                     name: string;
+                    kind: "function" | "class" | "type" | "json" | "variable" | "constructor" | "component" | "css";
                 } | undefined;
             }[] | undefined;
             module_comment?: string | undefined;

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

@@ -1 +1 @@
-{"version":3,"file":"library.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kCAAkC,CAAC;AAIlE,OAAO,EAAC,WAAW,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAC,MAAM,EAAC,MAAM,oBAAoB,CAAC;AAE1C;;GAEG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,OAAO,KAAG,MAGzD,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,OAAO;IACnB,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAiB;IAEnD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAA4C;IACxD,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAA2C;IAEtD,IAAI,SAAoC;IACxC,SAAS,SAAyC;IAClD,QAAQ,wCAAwC;IAChD,UAAU,gBAA0C;IACpD,YAAY,+CAA4C;IACxD,QAAQ,+CAAwC;IAChD,QAAQ,SAAwC;IAChD,OAAO,+CAAuC;IAC9C,aAAa,+CAA6C;IAC1D,SAAS,UAAyC;IAElD;;OAEG;IACH,OAAO,gBAML;IAEF;;OAEG;IACH,OAAO,WAIL;IAEF;;OAEG;IACH,cAAc,WAA4E;IAE1F;;OAEG;IACH,YAAY,gBAAmE;IAE/E;;OAEG;IACH,eAAe,2BAAgE;gBAEnE,YAAY,EAAE,WAAW,EAAE,UAAU,SAAK;IAKtD;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIzD;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAItC;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI/C;;OAEG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC;CAGtD;AAED,eAAO,MAAM,eAAe;;;;CAA4B,CAAC"}
+{"version":3,"file":"library.svelte.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/library.svelte.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAC,WAAW,EAAC,MAAM,kCAAkC,CAAC;AAIlE,OAAO,EAAC,WAAW,EAAC,MAAM,yBAAyB,CAAC;AACpD,OAAO,EAAC,MAAM,EAAC,MAAM,oBAAoB,CAAC;AAE1C;;GAEG;AACH,eAAO,MAAM,wBAAwB,GAAI,OAAO,OAAO,KAAG,MAGzD,CAAC;AAEF;;;;;;;;GAQG;AACH,qBAAa,OAAO;IACnB,QAAQ,CAAC,YAAY,EAAE,WAAW,CAAiB;IAEnD;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B,YAAY;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAA4C;IACxD,WAAW;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;MAA2C;IAEtD,IAAI,SAAoC;IACxC,SAAS,SAAyC;IAClD,QAAQ,wCAAwC;IAChD,UAAU,gBAA0C;IACpD,YAAY,+CAA4C;IACxD,QAAQ,+CAAwC;IAChD,QAAQ,SAAwC;IAChD,OAAO,+CAAuC;IAC9C,aAAa,+CAA6C;IAC1D,SAAS,UAAyC;IAElD;;OAEG;IACH,OAAO,gBAML;IAEF;;OAEG;IACH,OAAO,WAIL;IAEF;;OAEG;IACH,cAAc,WAA4E;IAE1F;;OAEG;IACH,YAAY,gBAAmE;IAE/E;;OAEG;IACH,eAAe,2BAAgE;gBAEnE,YAAY,EAAE,WAAW,EAAE,UAAU,SAAK;IAKtD;;OAEG;IACH,kBAAkB,CAAC,IAAI,EAAE,MAAM,GAAG,WAAW,GAAG,SAAS;IAIzD;;OAEG;IACH,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO;IAItC;;OAEG;IACH,aAAa,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS;IAI/C;;OAEG;IACH,mBAAmB,CAAC,KAAK,EAAE,MAAM,GAAG,KAAK,CAAC,WAAW,CAAC;CAGtD;AAED,eAAO,MAAM,eAAe;;;;CAA4B,CAAC"}

package/dist/mdz.d.ts

@@ -16,8 +16,8 @@
  *
  * ## Design philosophy
  *
- * - **False negatives over false positives**: Strict syntax prevents accidentally
- *   interpreting plain text as formatting. When in doubt, treat as plain text.
+ * - **False negatives over false positives**: When in doubt, treat as plain text.
+ *   Block elements can interrupt paragraphs without blank lines; inline formatting is strict.
  * - **One way to do things**: Single unambiguous syntax per feature. No alternatives.
  * - **Explicit over implicit**: Clear delimiters and column-0 requirements avoid ambiguity.
  * - **Simple over complete**: Prefer simple parsing rules over complex edge case handling.
@@ -102,6 +102,9 @@ export declare class MdzParser {
     /**
      * Main parse method. Returns flat array of nodes,
      * with paragraph nodes wrapping content between double newlines.
+     *
+     * Block elements (headings, HR, codeblocks) are detected at every column-0
+     * position — they can interrupt paragraphs without requiring blank lines.
      */
     parse(): Array<MdzNode>;
 }

package/dist/mdz.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"mdz.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,OAAO,CAAgC,CAAC;AAEvF,MAAM,MAAM,OAAO,GAChB,WAAW,GACX,WAAW,GACX,gBAAgB,GAChB,WAAW,GACX,aAAa,GACb,oBAAoB,GACpB,WAAW,GACX,gBAAgB,GAChB,SAAS,GACT,cAAc,GACd,cAAc,GACd,gBAAgB,CAAC;AAEpB,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IACjD,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACxD,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;CACnC;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC7C,IAAI,EAAE,IAAI,CAAC;CACX;AAED,MAAM,WAAW,cAAe,SAAQ,WAAW;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,cAAe,SAAQ,WAAW;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AA+CD;;;;GAIG;AACH,qBAAa,SAAS;;gBAQT,QAAQ,EAAE,MAAM;IAI5B;;;OAGG;IACH,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC;CA8lDvB;AAQD,eAAO,MAAM,UAAU,GAAI,GAAG,MAAM,KAAG,OAA8B,CAAC"}
+{"version":3,"file":"mdz.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/mdz.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AAIH;;GAEG;AACH,eAAO,MAAM,SAAS,GAAI,MAAM,MAAM,KAAG,KAAK,CAAC,OAAO,CAAgC,CAAC;AAEvF,MAAM,MAAM,OAAO,GAChB,WAAW,GACX,WAAW,GACX,gBAAgB,GAChB,WAAW,GACX,aAAa,GACb,oBAAoB,GACpB,WAAW,GACX,gBAAgB,GAChB,SAAS,GACT,cAAc,GACd,cAAc,GACd,gBAAgB,CAAC;AAEpB,MAAM,WAAW,WAAW;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,KAAK,EAAE,MAAM,CAAC;IACd,GAAG,EAAE,MAAM,CAAC;CACZ;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,OAAO,EAAE,MAAM,CAAC;CAChB;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,aAAc,SAAQ,WAAW;IACjD,IAAI,EAAE,QAAQ,CAAC;IACf,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,oBAAqB,SAAQ,WAAW;IACxD,IAAI,EAAE,eAAe,CAAC;IACtB,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,WAAY,SAAQ,WAAW;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,EAAE,MAAM,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;IACzB,SAAS,EAAE,UAAU,GAAG,UAAU,CAAC;CACnC;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,SAAU,SAAQ,WAAW;IAC7C,IAAI,EAAE,IAAI,CAAC;CACX;AAED,MAAM,WAAW,cAAe,SAAQ,WAAW;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,KAAK,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC;IAC7B,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,cAAe,SAAQ,WAAW;IAClD,IAAI,EAAE,SAAS,CAAC;IAChB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,gBAAiB,SAAQ,WAAW;IACpD,IAAI,EAAE,WAAW,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,QAAQ,EAAE,KAAK,CAAC,OAAO,CAAC,CAAC;CACzB;AA+CD;;;;GAIG;AACH,qBAAa,SAAS;;gBAQT,QAAQ,EAAE,MAAM;IAI5B;;;;;;OAMG;IACH,KAAK,IAAI,KAAK,CAAC,OAAO,CAAC;CAslDvB;AAQD,eAAO,MAAM,UAAU,GAAI,GAAG,MAAM,KAAG,OAA8B,CAAC"}

package/dist/mdz.js

@@ -16,8 +16,8 @@
  *
  * ## Design philosophy
  *
- * - **False negatives over false positives**: Strict syntax prevents accidentally
- *   interpreting plain text as formatting. When in doubt, treat as plain text.
+ * - **False negatives over false positives**: When in doubt, treat as plain text.
+ *   Block elements can interrupt paragraphs without blank lines; inline formatting is strict.
  * - **One way to do things**: Single unambiguous syntax per feature. No alternatives.
  * - **Explicit over implicit**: Clear delimiters and column-0 requirements avoid ambiguity.
  * - **Simple over complete**: Prefer simple parsing rules over complex edge case handling.
@@ -95,88 +95,121 @@ export class MdzParser {
     /**
      * Main parse method. Returns flat array of nodes,
      * with paragraph nodes wrapping content between double newlines.
+     *
+     * Block elements (headings, HR, codeblocks) are detected at every column-0
+     * position — they can interrupt paragraphs without requiring blank lines.
      */
     parse() {
         this.#nodes.length = 0;
         const root_nodes = [];
         const paragraph_children = [];
-        // Check for block element at document start
-        const start_block = this.#try_parse_block_element();
-        if (start_block) {
-            root_nodes.push(start_block);
-        }
+        // Skip leading newlines
+        this.#skip_newlines();
         while (this.#index < this.#template.length) {
+            // Peek for block element (read-only match), flush paragraph first, then parse.
+            // Flush must happen before parse because parse modifies accumulation state.
+            const block_type = this.#peek_block_element();
+            if (block_type) {
+                const flushed = this.#flush_paragraph(paragraph_children, true);
+                if (flushed)
+                    root_nodes.push(flushed);
+                if (block_type === 'heading')
+                    root_nodes.push(this.#parse_heading());
+                else if (block_type === 'hr')
+                    root_nodes.push(this.#parse_hr());
+                else
+                    root_nodes.push(this.#parse_code_block());
+                this.#skip_newlines();
+                continue;
+            }
             // Check for paragraph break (double newline)
             if (this.#is_at_paragraph_break()) {
-                this.#flush_text();
-                // Move flushed nodes to paragraph_children
-                if (this.#nodes.length > 0) {
-                    paragraph_children.push(...this.#nodes);
-                    this.#nodes.length = 0;
-                }
-                // Wrap accumulated nodes in paragraph (or add single tag directly)
-                if (paragraph_children.length > 0) {
-                    if (this.#is_single_tag(paragraph_children)) {
-                        // Single tag (component/element) - add directly without paragraph wrapper (MDX convention)
-                        const tag = paragraph_children.find((n) => n.type === 'Component' || n.type === 'Element');
-                        root_nodes.push(tag);
-                    }
-                    else {
-                        // Regular paragraph
-                        root_nodes.push({
-                            type: 'Paragraph',
-                            children: paragraph_children.slice(),
-                            start: paragraph_children[0].start,
-                            end: paragraph_children[paragraph_children.length - 1].end,
-                        });
-                    }
-                    paragraph_children.length = 0;
-                }
-                // Consume the paragraph break
-                this.#eat('\n\n');
-                // Check for block element after paragraph break
-                const block = this.#try_parse_block_element();
-                if (block) {
-                    root_nodes.push(block);
-                }
+                const flushed = this.#flush_paragraph(paragraph_children, true);
+                if (flushed)
+                    root_nodes.push(flushed);
+                this.#skip_newlines();
+                continue;
+            }
+            // Parse inline content
+            const node = this.#parse_node();
+            if (node.type === 'Text') {
+                this.#accumulate_text(node.content, node.start);
             }
             else {
-                const node = this.#parse_node();
-                if (node.type === 'Text') {
-                    this.#accumulate_text(node.content, node.start);
-                }
-                else {
-                    this.#flush_text();
-                    this.#nodes.push(node);
-                }
-                if (this.#nodes.length > 0) {
-                    paragraph_children.push(...this.#nodes);
-                    this.#nodes.length = 0;
-                }
+                this.#flush_text();
+                this.#nodes.push(node);
+            }
+            if (this.#nodes.length > 0) {
+                paragraph_children.push(...this.#nodes);
+                this.#nodes.length = 0;
             }
         }
+        // Flush remaining content as final paragraph
+        const final_paragraph = this.#flush_paragraph(paragraph_children, true);
+        if (final_paragraph)
+            root_nodes.push(final_paragraph);
+        return root_nodes;
+    }
+    /**
+     * Flush accumulated inline content as a paragraph node (or single tag).
+     * When `trim_trailing` is true, trims trailing newlines from the last text node
+     * (the line break before a block element or paragraph break).
+     *
+     * @mutates paragraph_children - trims last text node, removes whitespace-only nodes, clears array
+     */
+    #flush_paragraph(paragraph_children, trim_trailing = false) {
         this.#flush_text();
         if (this.#nodes.length > 0) {
             paragraph_children.push(...this.#nodes);
-        }
-        // Wrap remaining nodes in final paragraph if any (or add single tag directly)
-        if (paragraph_children.length > 0) {
-            if (this.#is_single_tag(paragraph_children)) {
-                // Single tag (component/element) - add directly without paragraph wrapper (MDX convention)
-                const tag = paragraph_children.find((n) => n.type === 'Component' || n.type === 'Element');
-                root_nodes.push(tag);
+            this.#nodes.length = 0;
+        }
+        if (paragraph_children.length === 0) {
+            return null;
+        }
+        if (trim_trailing) {
+            // Trim trailing newlines from the last text node (line break before block element)
+            const last = paragraph_children[paragraph_children.length - 1];
+            if (last.type === 'Text') {
+                const trimmed = last.content.replace(/\n+$/, '');
+                if (trimmed) {
+                    last.content = trimmed;
+                    last.end = last.start + trimmed.length;
+                }
+                else {
+                    paragraph_children.pop();
+                }
             }
-            else {
-                // Regular paragraph
-                root_nodes.push({
-                    type: 'Paragraph',
-                    children: paragraph_children,
-                    start: paragraph_children[0].start,
-                    end: paragraph_children[paragraph_children.length - 1].end,
-                });
+            // Skip whitespace-only paragraphs (e.g. newlines between consecutive blocks)
+            const has_content = paragraph_children.some((n) => n.type !== 'Text' || n.content.trim().length > 0);
+            if (!has_content) {
+                paragraph_children.length = 0;
+                return null;
             }
         }
-        return root_nodes;
+        // Single tag (component/element) - add directly without paragraph wrapper (MDX convention)
+        const single_tag = this.#extract_single_tag(paragraph_children);
+        if (single_tag) {
+            paragraph_children.length = 0;
+            return single_tag;
+        }
+        // Regular paragraph
+        const result = {
+            type: 'Paragraph',
+            children: paragraph_children.slice(),
+            start: paragraph_children[0].start,
+            end: paragraph_children[paragraph_children.length - 1].end,
+        };
+        paragraph_children.length = 0;
+        return result;
+    }
+    /**
+     * Consume consecutive newline characters.
+     */
+    #skip_newlines() {
+        while (this.#index < this.#template.length &&
+            this.#template.charCodeAt(this.#index) === NEWLINE) {
+            this.#index++;
+        }
     }
     /**
      * Accumulate text for later flushing (performance optimization).
@@ -667,50 +700,42 @@ export class MdzParser {
         };
     }
     /**
-     * Check if nodes represent a single tag (component or element) with only whitespace text nodes.
-     * Used to determine if paragraph wrapping should be skipped (MDX convention).
-     * Returns true if there's exactly one Component/Element node and all other nodes are whitespace-only Text nodes.
+     * Extract a single tag (component or element) if it's the only non-whitespace content.
+     * Returns the tag node if paragraph wrapping should be skipped (MDX convention),
+     * or null if the content should be wrapped in a paragraph.
      */
-    #is_single_tag(nodes) {
-        let found_tag = false;
+    #extract_single_tag(nodes) {
+        let tag = null;
         for (const node of nodes) {
             if (node.type === 'Component' || node.type === 'Element') {
-                if (found_tag)
-                    return false; // Multiple tags
-                found_tag = true;
+                if (tag)
+                    return null; // Multiple tags
+                tag = node;
             }
             else if (node.type === 'Text') {
                 // Allow only whitespace-only text nodes
                 if (node.content.trim() !== '')
-                    return false;
+                    return null;
             }
             else {
                 // Any other node type means not a single tag
-                return false;
+                return null;
             }
         }
-        return found_tag;
+        return tag;
     }
     /**
-     * Try to parse a block element (heading, hr, or codeblock) at current position.
-     * Returns the parsed block node if a match is found, null otherwise.
-     *
-     * Block elements must:
-     * - Start at column 0 (no leading whitespace)
-     * - Be followed by blank line or EOF
-     *
-     * This helper eliminates duplication between document start and post-paragraph-break parsing.
+     * Read-only check if current position matches a block element.
+     * Does not modify parser state — used to peek before flushing paragraph.
+     * Returns which block type matched, or null if none.
      */
-    #try_parse_block_element() {
-        if (this.#match_heading()) {
-            return this.#parse_heading();
-        }
-        else if (this.#match_hr()) {
-            return this.#parse_hr();
-        }
-        else if (this.#match_code_block()) {
-            return this.#parse_code_block();
-        }
+    #peek_block_element() {
+        if (this.#match_heading())
+            return 'heading';
+        if (this.#match_hr())
+            return 'hr';
+        if (this.#match_code_block())
+            return 'codeblock';
         return null;
     }
     /**
@@ -1037,6 +1062,20 @@ export class MdzParser {
             if (this.#is_at_paragraph_break()) {
                 break;
             }
+            // When next line could start a block element, consume the newline and stop.
+            // The main loop will try block detection at the next character.
+            // Consuming the newline here avoids a 3-iteration detour (break before \n,
+            // fail peek at \n, safety-increment, then succeed peek at block char).
+            if (char_code === NEWLINE) {
+                const next_i = this.#index + 1;
+                if (next_i < this.#template.length) {
+                    const next_char = this.#template.charCodeAt(next_i);
+                    if (next_char === HASH || next_char === HYPHEN || next_char === BACKTICK) {
+                        this.#index++; // consume the newline
+                        break;
+                    }
+                }
+            }
             // Check for URL or internal path mid-text
             if (this.#is_at_url() || this.#is_at_internal_path()) {
                 break;
@@ -1127,18 +1166,15 @@ export class MdzParser {
     }
     /**
      * Check if current position matches a horizontal rule.
-     * HR must be exactly `---` at column 0, followed by blank line or EOF.
+     * HR must be exactly `---` at column 0, followed by newline or EOF.
      *
-     * Blank line requirement rationale:
-     * Prevents block elements from accidentally consuming following content.
-     * Without this, `---` followed by regular text would create an hr and treat
-     * the next line as a new paragraph, which could be surprising. The blank line
-     * makes block element boundaries explicit and predictable.
+     * mdz has no setext headings, so `---` after a paragraph is unambiguous
+     * (always an HR, unlike CommonMark where it becomes a setext heading).
      */
     #match_hr() {
         let i = this.#index;
-        // Must start at column 0 (no leading whitespace)
-        if (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+        // Must start at column 0 (beginning of input or after newline)
+        if (i > 0 && this.#template.charCodeAt(i - 1) !== NEWLINE) {
             return false;
         }
         // Must have exactly three hyphens
@@ -1153,15 +1189,7 @@ export class MdzParser {
         while (i < this.#template.length) {
             const char_code = this.#template.charCodeAt(i);
             if (char_code === NEWLINE) {
-                // Found newline - check if followed by another newline (blank line) or EOF
-                const next_i = i + 1;
-                if (next_i >= this.#template.length) {
-                    return true; // hr followed by newline + EOF
-                }
-                if (this.#template.charCodeAt(next_i) === NEWLINE) {
-                    return true; // hr followed by blank line
-                }
-                return false; // hr followed by single newline + content
+                return true;
             }
             if (char_code !== SPACE) {
                 return false; // Non-whitespace after ---, not an hr
@@ -1194,17 +1222,12 @@ export class MdzParser {
     /**
      * Check if current position matches a heading.
      * Heading must be 1-6 hashes at column 0, followed by space and content,
-     * followed by blank line or EOF.
-     *
-     * Blank line requirement rationale:
-     * Ensures headings are visually and semantically separate from following content.
-     * Without this, `# Heading\nText` would be ambiguous - is the text part of the
-     * heading or a new paragraph? The blank line makes document structure explicit.
+     * followed by newline or EOF.
      */
     #match_heading() {
         let i = this.#index;
-        // Must start at column 0 (no leading whitespace)
-        if (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+        // Must start at column 0 (beginning of input or after newline)
+        if (i > 0 && this.#template.charCodeAt(i - 1) !== NEWLINE) {
             return false;
         }
         // Count hashes (must be 1-6)
@@ -1235,23 +1258,8 @@ export class MdzParser {
         if (!has_content) {
             return false; // heading with only whitespace, treat as plain text
         }
-        // At this point we're at newline or EOF
-        // Check for blank line after (newline + newline) or EOF
-        if (i >= this.#template.length) {
-            return true; // heading at EOF
-        }
-        // Must have newline
-        if (this.#template.charCodeAt(i) !== NEWLINE) {
-            return false;
-        }
-        const next_i = i + 1;
-        if (next_i >= this.#template.length) {
-            return true; // heading followed by newline + EOF
-        }
-        if (this.#template.charCodeAt(next_i) === NEWLINE) {
-            return true; // heading followed by blank line
-        }
-        return false; // heading followed by single newline + content
+        // At newline or EOF — both are valid
+        return true;
     }
     /**
      * Parse heading: `# Heading text`
@@ -1312,19 +1320,13 @@ export class MdzParser {
     }
     /**
      * Check if current position matches a code block.
-     * Code block must be 3+ backticks at column 0, followed by blank line or EOF.
+     * Code block must be 3+ backticks at column 0, closing fence followed by newline or EOF.
      * Empty code blocks (no content) are treated as invalid.
-     *
-     * Blank line requirement rationale:
-     * Separates code blocks from following content to prevent ambiguity.
-     * Codeblocks are distinct semantic units that should be visually isolated.
-     * The blank line makes it explicit where the code block ends and regular
-     * content begins, following the "explicit over implicit" design principle.
      */
     #match_code_block() {
         let i = this.#index;
-        // Must start at column 0 (no leading whitespace)
-        if (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+        // Must start at column 0 (beginning of input or after newline)
+        if (i > 0 && this.#template.charCodeAt(i - 1) !== NEWLINE) {
             return false;
         }
         // Must have at least three backticks
@@ -1386,15 +1388,7 @@ export class MdzParser {
                         // closing fence has non-whitespace after it on same line - not a code block
                         return false;
                     }
-                    // Check if followed by blank line or EOF
-                    const next_j = j + 1;
-                    if (next_j >= this.#template.length) {
-                        return true; // code block followed by newline + EOF
-                    }
-                    if (this.#template.charCodeAt(next_j) === NEWLINE) {
-                        return true; // code block followed by blank line
-                    }
-                    return false; // code block followed by single newline + content
+                    return true; // code block followed by newline or EOF
                 }
             }
             i++;

package/dist/ts_helpers.js

@@ -140,7 +140,7 @@ export const ts_analyze_module_exports = (source_file, checker, options, ctx) =>
                                 const decl = {
                                     name: export_symbol.name,
                                     kind,
-                                    alias_of: { module: original_module, name: original_name },
+                                    alias_of: { module: original_module, name: original_name, kind },
                                 };
                                 // Renamed re-exports aren't nodocs - they're new declarations pointing to the original
                                 declarations.push({ declaration: decl, nodocs: false });

package/dist/tsdoc_helpers.d.ts

@@ -30,7 +30,8 @@
  * ## Behavioral notes
  *
  * Due to TS Compiler API limitations:
- * - Preserves dash separator in `@param` descriptions: `@param x desc` → `"- desc"`
+ * - `@param` and `@mutates` descriptions have leading `- ` stripped for visual consistency
+ *   (TSDoc spec uses `@param name - description` but the separator is aesthetic)
  * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
  * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
  *

package/dist/tsdoc_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tsdoc_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACrD,oCAAoC;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GACvB,MAAM,EAAE,CAAC,IAAI,EACb,aAAa,EAAE,CAAC,UAAU,KACxB,kBAAkB,GAAG,SAyFvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,eAAe,EAC5B,OAAO,kBAAkB,GAAG,SAAS,KACnC,IAmBF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,MAAM,GAAG,SAUnE,CAAC"}
+{"version":3,"file":"tsdoc_helpers.d.ts","sourceRoot":"../src/lib/","sources":["../src/lib/tsdoc_helpers.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAwCG;AAEH,OAAO,EAAE,MAAM,YAAY,CAAC;AAC5B,OAAO,KAAK,EAAC,eAAe,EAAC,MAAM,iCAAiC,CAAC;AAErE;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAClC,+CAA+C;IAC/C,IAAI,EAAE,MAAM,CAAC;IACb,sDAAsD;IACtD,MAAM,EAAE,GAAG,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5B,+CAA+C;IAC/C,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,mCAAmC;IACnC,MAAM,CAAC,EAAE,KAAK,CAAC;QAAC,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAA;KAAC,CAAC,CAAC;IACrD,oCAAoC;IACpC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,6CAA6C;IAC7C,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,qCAAqC;IACrC,QAAQ,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACzB,wCAAwC;IACxC,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,4DAA4D;IAC5D,OAAO,CAAC,EAAE,KAAK,CAAC,MAAM,CAAC,CAAC;IACxB,iEAAiE;IACjE,MAAM,CAAC,EAAE,OAAO,CAAC;CACjB;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,eAAO,MAAM,WAAW,GACvB,MAAM,EAAE,CAAC,IAAI,EACb,aAAa,EAAE,CAAC,UAAU,KACxB,kBAAkB,GAAG,SAyFvB,CAAC;AAEF;;;;;;;;;GASG;AACH,eAAO,MAAM,0BAA0B,GACtC,aAAa,eAAe,EAC5B,OAAO,kBAAkB,GAAG,SAAS,KACnC,IAmBF,CAAC;AAEF;;;;;;;GAOG;AACH,eAAO,MAAM,mBAAmB,GAAI,cAAc,MAAM,KAAG,MAAM,GAAG,SAUnE,CAAC"}

package/dist/tsdoc_helpers.js

@@ -30,7 +30,8 @@
  * ## Behavioral notes
  *
  * Due to TS Compiler API limitations:
- * - Preserves dash separator in `@param` descriptions: `@param x desc` → `"- desc"`
+ * - `@param` and `@mutates` descriptions have leading `- ` stripped for visual consistency
+ *   (TSDoc spec uses `@param name - description` but the separator is aesthetic)
  * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
  * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
  *
@@ -88,7 +89,7 @@ export const tsdoc_parse = (node, source_file) => {
             // Extract parameter name and description
             const param_name = ts.isIdentifier(tag.name) ? tag.name.text : tag.name.getText();
             if (param_name && tag_text) {
-                params.set(param_name, tag_text.trim());
+                params.set(param_name, tag_text.trim().replace(/^-\s+/, ''));
             }
         }
         else if (tag_name === 'returns' && tag_text) {
@@ -127,7 +128,7 @@ export const tsdoc_parse = (node, source_file) => {
             since = tag_text.trim();
         }
         else if (tag_name === 'mutates' && tag_text) {
-            mutates.push(tag_text.trim());
+            mutates.push(tag_text.trim().replace(/^-\s+/, ''));
         }
         else if (tag_name === 'nodocs') {
             nodocs = true;

package/dist/tsdoc_mdz.d.ts

@@ -16,8 +16,9 @@
  * - `{@link identifier}` → `` `identifier` `` (code formatting)
  * - Bare URLs → returned as-is
  * - Bare identifiers → wrapped in backticks
+ * - `identifier description text` → `` `identifier` description text `` (first token is the reference)
  *
- * @param content Raw `@see` tag content in TSDoc format
+ * @param content - raw `@see` tag content in TSDoc format
  * @returns mdz-formatted string ready for `Mdz` component
  *
  * @example
@@ -30,6 +31,9 @@
  *
  * tsdoc_see_to_mdz('https://example.com')
  * // → 'https://example.com'
+ *
+ * tsdoc_see_to_mdz('library_gen.ts for Gro-specific integration')
+ * // → '`library_gen.ts` for Gro-specific integration'
  * ```
  */
 export declare const tsdoc_see_to_mdz: (content: string) => string;

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;;;;;;;;;;;;;;;;;;;;;;;;GAwBG;AACH,eAAO,MAAM,gBAAgB,GAAI,SAAS,MAAM,KAAG,MAqBlD,CAAC"}
+{"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"}

package/dist/tsdoc_mdz.js

@@ -19,8 +19,9 @@ const format_reference = (ref) => (mdz_is_url(ref) ? ref : `\`${ref}\``);
  * - `{@link identifier}` → `` `identifier` `` (code formatting)
  * - Bare URLs → returned as-is
  * - Bare identifiers → wrapped in backticks
+ * - `identifier description text` → `` `identifier` description text `` (first token is the reference)
  *
- * @param content Raw `@see` tag content in TSDoc format
+ * @param content - raw `@see` tag content in TSDoc format
  * @returns mdz-formatted string ready for `Mdz` component
  *
  * @example
@@ -33,6 +34,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('library_gen.ts for Gro-specific integration')
+ * // → '`library_gen.ts` for Gro-specific integration'
  * ```
  */
 export const tsdoc_see_to_mdz = (content) => {
@@ -52,5 +56,12 @@ export const tsdoc_see_to_mdz = (content) => {
         }
         return format_reference(inner);
     }
-    return format_reference(trimmed);
+    // Split at first whitespace: first token is the reference, rest is description
+    const space_index = trimmed.indexOf(' ');
+    if (space_index === -1) {
+        return format_reference(trimmed);
+    }
+    const reference = trimmed.slice(0, space_index);
+    const description = trimmed.slice(space_index); // preserve leading space
+    return format_reference(reference) + description;
 };

package/package.json

@@ -1,12 +1,11 @@
 {
   "name": "@fuzdev/fuz_ui",
-  "version": "0.184.0",
+  "version": "0.185.1",
   "description": "Svelte UI library",
   "motto": "friendly user zystem",
   "glyph": "🧶",
   "logo": "logo.svg",
   "logo_alt": "a friendly brown spider facing you",
-  "public": true,
   "license": "MIT",
   "homepage": "https://ui.fuz.dev/",
   "author": {
@@ -35,10 +34,10 @@
     "node": ">=22.15"
   },
   "peerDependencies": {
-    "@fuzdev/fuz_code": ">=0.45.0",
-    "@fuzdev/fuz_css": ">=0.47.0",
-    "@fuzdev/fuz_util": ">=0.50.1",
-    "@fuzdev/gro": ">=0.192.0",
+    "@fuzdev/fuz_code": ">=0.45.1",
+    "@fuzdev/fuz_css": ">=0.53.0",
+    "@fuzdev/fuz_util": ">=0.52.0",
+    "@fuzdev/gro": ">=0.195.0",
     "@jridgewell/trace-mapping": "^0.3",
     "@sveltejs/kit": "^2.47.3",
     "@types/estree": "^1",
@@ -76,9 +75,9 @@
   "devDependencies": {
     "@changesets/changelog-git": "^0.2.1",
     "@fuzdev/fuz_code": "^0.45.1",
-    "@fuzdev/fuz_css": "^0.51.0",
-    "@fuzdev/fuz_util": "^0.50.1",
-    "@fuzdev/gro": "^0.194.0",
+    "@fuzdev/fuz_css": "^0.53.0",
+    "@fuzdev/fuz_util": "^0.52.0",
+    "@fuzdev/gro": "^0.195.0",
     "@jridgewell/trace-mapping": "^0.3.31",
     "@ryanatkn/eslint-config": "^0.9.0",
     "@sveltejs/adapter-static": "^3.0.10",

package/src/lib/declaration.svelte.ts

@@ -7,6 +7,8 @@ import {
 import type {Module} from './module.svelte.js';
 import {url_github_file} from './package_helpers.js';
 
+/* eslint-disable @typescript-eslint/no-deprecated */
+
 /**
  * Rich runtime representation of an exported declaration.
  */

package/src/lib/mdz.ts

@@ -16,8 +16,8 @@
  *
  * ## Design philosophy
  *
- * - **False negatives over false positives**: Strict syntax prevents accidentally
- *   interpreting plain text as formatting. When in doubt, treat as plain text.
+ * - **False negatives over false positives**: When in doubt, treat as plain text.
+ *   Block elements can interrupt paragraphs without blank lines; inline formatting is strict.
  * - **One way to do things**: Single unambiguous syntax per feature. No alternatives.
  * - **Explicit over implicit**: Clear delimiters and column-0 requirements avoid ambiguity.
  * - **Simple over complete**: Prefer simple parsing rules over complex edge case handling.
@@ -186,92 +186,130 @@ export class MdzParser {
 	/**
 	 * Main parse method. Returns flat array of nodes,
 	 * with paragraph nodes wrapping content between double newlines.
+	 *
+	 * Block elements (headings, HR, codeblocks) are detected at every column-0
+	 * position — they can interrupt paragraphs without requiring blank lines.
 	 */
 	parse(): Array<MdzNode> {
 		this.#nodes.length = 0;
 		const root_nodes: Array<MdzNode> = [];
 		const paragraph_children: Array<MdzNode> = [];
 
-		// Check for block element at document start
-		const start_block = this.#try_parse_block_element();
-		if (start_block) {
-			root_nodes.push(start_block);
-		}
+		// Skip leading newlines
+		this.#skip_newlines();
 
 		while (this.#index < this.#template.length) {
+			// Peek for block element (read-only match), flush paragraph first, then parse.
+			// Flush must happen before parse because parse modifies accumulation state.
+			const block_type = this.#peek_block_element();
+			if (block_type) {
+				const flushed = this.#flush_paragraph(paragraph_children, true);
+				if (flushed) root_nodes.push(flushed);
+				if (block_type === 'heading') root_nodes.push(this.#parse_heading());
+				else if (block_type === 'hr') root_nodes.push(this.#parse_hr());
+				else root_nodes.push(this.#parse_code_block());
+				this.#skip_newlines();
+				continue;
+			}
+
 			// Check for paragraph break (double newline)
 			if (this.#is_at_paragraph_break()) {
-				this.#flush_text();
-				// Move flushed nodes to paragraph_children
-				if (this.#nodes.length > 0) {
-					paragraph_children.push(...this.#nodes);
-					this.#nodes.length = 0;
-				}
-				// Wrap accumulated nodes in paragraph (or add single tag directly)
-				if (paragraph_children.length > 0) {
-					if (this.#is_single_tag(paragraph_children)) {
-						// Single tag (component/element) - add directly without paragraph wrapper (MDX convention)
-						const tag = paragraph_children.find(
-							(n) => n.type === 'Component' || n.type === 'Element',
-						)!;
-						root_nodes.push(tag);
-					} else {
-						// Regular paragraph
-						root_nodes.push({
-							type: 'Paragraph',
-							children: paragraph_children.slice(),
-							start: paragraph_children[0]!.start,
-							end: paragraph_children[paragraph_children.length - 1]!.end,
-						});
-					}
-					paragraph_children.length = 0;
-				}
-				// Consume the paragraph break
-				this.#eat('\n\n');
+				const flushed = this.#flush_paragraph(paragraph_children, true);
+				if (flushed) root_nodes.push(flushed);
+				this.#skip_newlines();
+				continue;
+			}
 
-				// Check for block element after paragraph break
-				const block = this.#try_parse_block_element();
-				if (block) {
-					root_nodes.push(block);
-				}
+			// Parse inline content
+			const node = this.#parse_node();
+			if (node.type === 'Text') {
+				this.#accumulate_text(node.content, node.start);
 			} else {
-				const node = this.#parse_node();
-				if (node.type === 'Text') {
-					this.#accumulate_text(node.content, node.start);
-				} else {
-					this.#flush_text();
-					this.#nodes.push(node);
-				}
-				if (this.#nodes.length > 0) {
-					paragraph_children.push(...this.#nodes);
-					this.#nodes.length = 0;
-				}
+				this.#flush_text();
+				this.#nodes.push(node);
+			}
+			if (this.#nodes.length > 0) {
+				paragraph_children.push(...this.#nodes);
+				this.#nodes.length = 0;
 			}
 		}
 
+		// Flush remaining content as final paragraph
+		const final_paragraph = this.#flush_paragraph(paragraph_children, true);
+		if (final_paragraph) root_nodes.push(final_paragraph);
+
+		return root_nodes;
+	}
+
+	/**
+	 * Flush accumulated inline content as a paragraph node (or single tag).
+	 * When `trim_trailing` is true, trims trailing newlines from the last text node
+	 * (the line break before a block element or paragraph break).
+	 *
+	 * @mutates paragraph_children - trims last text node, removes whitespace-only nodes, clears array
+	 */
+	#flush_paragraph(paragraph_children: Array<MdzNode>, trim_trailing = false): MdzNode | null {
 		this.#flush_text();
 		if (this.#nodes.length > 0) {
 			paragraph_children.push(...this.#nodes);
+			this.#nodes.length = 0;
 		}
 
-		// Wrap remaining nodes in final paragraph if any (or add single tag directly)
-		if (paragraph_children.length > 0) {
-			if (this.#is_single_tag(paragraph_children)) {
-				// Single tag (component/element) - add directly without paragraph wrapper (MDX convention)
-				const tag = paragraph_children.find((n) => n.type === 'Component' || n.type === 'Element')!;
-				root_nodes.push(tag);
-			} else {
-				// Regular paragraph
-				root_nodes.push({
-					type: 'Paragraph',
-					children: paragraph_children,
-					start: paragraph_children[0]!.start,
-					end: paragraph_children[paragraph_children.length - 1]!.end,
-				});
+		if (paragraph_children.length === 0) {
+			return null;
+		}
+
+		if (trim_trailing) {
+			// Trim trailing newlines from the last text node (line break before block element)
+			const last = paragraph_children[paragraph_children.length - 1]!;
+			if (last.type === 'Text') {
+				const trimmed = last.content.replace(/\n+$/, '');
+				if (trimmed) {
+					last.content = trimmed;
+					last.end = last.start + trimmed.length;
+				} else {
+					paragraph_children.pop();
+				}
+			}
+
+			// Skip whitespace-only paragraphs (e.g. newlines between consecutive blocks)
+			const has_content = paragraph_children.some(
+				(n) => n.type !== 'Text' || n.content.trim().length > 0,
+			);
+			if (!has_content) {
+				paragraph_children.length = 0;
+				return null;
 			}
 		}
 
-		return root_nodes;
+		// Single tag (component/element) - add directly without paragraph wrapper (MDX convention)
+		const single_tag = this.#extract_single_tag(paragraph_children);
+		if (single_tag) {
+			paragraph_children.length = 0;
+			return single_tag;
+		}
+
+		// Regular paragraph
+		const result: MdzParagraphNode = {
+			type: 'Paragraph',
+			children: paragraph_children.slice(),
+			start: paragraph_children[0]!.start,
+			end: paragraph_children[paragraph_children.length - 1]!.end,
+		};
+		paragraph_children.length = 0;
+		return result;
+	}
+
+	/**
+	 * Consume consecutive newline characters.
+	 */
+	#skip_newlines(): void {
+		while (
+			this.#index < this.#template.length &&
+			this.#template.charCodeAt(this.#index) === NEWLINE
+		) {
+			this.#index++;
+		}
 	}
 
 	/**
@@ -870,47 +908,38 @@ export class MdzParser {
 	}
 
 	/**
-	 * Check if nodes represent a single tag (component or element) with only whitespace text nodes.
-	 * Used to determine if paragraph wrapping should be skipped (MDX convention).
-	 * Returns true if there's exactly one Component/Element node and all other nodes are whitespace-only Text nodes.
+	 * Extract a single tag (component or element) if it's the only non-whitespace content.
+	 * Returns the tag node if paragraph wrapping should be skipped (MDX convention),
+	 * or null if the content should be wrapped in a paragraph.
 	 */
-	#is_single_tag(nodes: Array<MdzNode>): boolean {
-		let found_tag = false;
+	#extract_single_tag(nodes: Array<MdzNode>): MdzComponentNode | MdzElementNode | null {
+		let tag: MdzComponentNode | MdzElementNode | null = null;
 
 		for (const node of nodes) {
 			if (node.type === 'Component' || node.type === 'Element') {
-				if (found_tag) return false; // Multiple tags
-				found_tag = true;
+				if (tag) return null; // Multiple tags
+				tag = node;
 			} else if (node.type === 'Text') {
 				// Allow only whitespace-only text nodes
-				if (node.content.trim() !== '') return false;
+				if (node.content.trim() !== '') return null;
 			} else {
 				// Any other node type means not a single tag
-				return false;
+				return null;
 			}
 		}
 
-		return found_tag;
+		return tag;
 	}
 
 	/**
-	 * Try to parse a block element (heading, hr, or codeblock) at current position.
-	 * Returns the parsed block node if a match is found, null otherwise.
-	 *
-	 * Block elements must:
-	 * - Start at column 0 (no leading whitespace)
-	 * - Be followed by blank line or EOF
-	 *
-	 * This helper eliminates duplication between document start and post-paragraph-break parsing.
+	 * Read-only check if current position matches a block element.
+	 * Does not modify parser state — used to peek before flushing paragraph.
+	 * Returns which block type matched, or null if none.
 	 */
-	#try_parse_block_element(): MdzHeadingNode | MdzHrNode | MdzCodeblockNode | null {
-		if (this.#match_heading()) {
-			return this.#parse_heading();
-		} else if (this.#match_hr()) {
-			return this.#parse_hr();
-		} else if (this.#match_code_block()) {
-			return this.#parse_code_block();
-		}
+	#peek_block_element(): 'heading' | 'hr' | 'codeblock' | null {
+		if (this.#match_heading()) return 'heading';
+		if (this.#match_hr()) return 'hr';
+		if (this.#match_code_block()) return 'codeblock';
 		return null;
 	}
 
@@ -1288,6 +1317,21 @@ export class MdzParser {
 				break;
 			}
 
+			// When next line could start a block element, consume the newline and stop.
+			// The main loop will try block detection at the next character.
+			// Consuming the newline here avoids a 3-iteration detour (break before \n,
+			// fail peek at \n, safety-increment, then succeed peek at block char).
+			if (char_code === NEWLINE) {
+				const next_i = this.#index + 1;
+				if (next_i < this.#template.length) {
+					const next_char = this.#template.charCodeAt(next_i);
+					if (next_char === HASH || next_char === HYPHEN || next_char === BACKTICK) {
+						this.#index++; // consume the newline
+						break;
+					}
+				}
+			}
+
 			// Check for URL or internal path mid-text
 			if (this.#is_at_url() || this.#is_at_internal_path()) {
 				break;
@@ -1395,19 +1439,16 @@ export class MdzParser {
 
 	/**
 	 * Check if current position matches a horizontal rule.
-	 * HR must be exactly `---` at column 0, followed by blank line or EOF.
+	 * HR must be exactly `---` at column 0, followed by newline or EOF.
 	 *
-	 * Blank line requirement rationale:
-	 * Prevents block elements from accidentally consuming following content.
-	 * Without this, `---` followed by regular text would create an hr and treat
-	 * the next line as a new paragraph, which could be surprising. The blank line
-	 * makes block element boundaries explicit and predictable.
+	 * mdz has no setext headings, so `---` after a paragraph is unambiguous
+	 * (always an HR, unlike CommonMark where it becomes a setext heading).
 	 */
 	#match_hr(): boolean {
 		let i = this.#index;
 
-		// Must start at column 0 (no leading whitespace)
-		if (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+		// Must start at column 0 (beginning of input or after newline)
+		if (i > 0 && this.#template.charCodeAt(i - 1) !== NEWLINE) {
 			return false;
 		}
 
@@ -1426,15 +1467,7 @@ export class MdzParser {
 		while (i < this.#template.length) {
 			const char_code = this.#template.charCodeAt(i);
 			if (char_code === NEWLINE) {
-				// Found newline - check if followed by another newline (blank line) or EOF
-				const next_i = i + 1;
-				if (next_i >= this.#template.length) {
-					return true; // hr followed by newline + EOF
-				}
-				if (this.#template.charCodeAt(next_i) === NEWLINE) {
-					return true; // hr followed by blank line
-				}
-				return false; // hr followed by single newline + content
+				return true;
 			}
 			if (char_code !== SPACE) {
 				return false; // Non-whitespace after ---, not an hr
@@ -1476,18 +1509,13 @@ export class MdzParser {
 	/**
 	 * Check if current position matches a heading.
 	 * Heading must be 1-6 hashes at column 0, followed by space and content,
-	 * followed by blank line or EOF.
-	 *
-	 * Blank line requirement rationale:
-	 * Ensures headings are visually and semantically separate from following content.
-	 * Without this, `# Heading\nText` would be ambiguous - is the text part of the
-	 * heading or a new paragraph? The blank line makes document structure explicit.
+	 * followed by newline or EOF.
 	 */
 	#match_heading(): boolean {
 		let i = this.#index;
 
-		// Must start at column 0 (no leading whitespace)
-		if (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+		// Must start at column 0 (beginning of input or after newline)
+		if (i > 0 && this.#template.charCodeAt(i - 1) !== NEWLINE) {
 			return false;
 		}
 
@@ -1526,27 +1554,8 @@ export class MdzParser {
 			return false; // heading with only whitespace, treat as plain text
 		}
 
-		// At this point we're at newline or EOF
-		// Check for blank line after (newline + newline) or EOF
-		if (i >= this.#template.length) {
-			return true; // heading at EOF
-		}
-
-		// Must have newline
-		if (this.#template.charCodeAt(i) !== NEWLINE) {
-			return false;
-		}
-
-		const next_i = i + 1;
-		if (next_i >= this.#template.length) {
-			return true; // heading followed by newline + EOF
-		}
-
-		if (this.#template.charCodeAt(next_i) === NEWLINE) {
-			return true; // heading followed by blank line
-		}
-
-		return false; // heading followed by single newline + content
+		// At newline or EOF — both are valid
+		return true;
 	}
 
 	/**
@@ -1616,20 +1625,14 @@ export class MdzParser {
 
 	/**
 	 * Check if current position matches a code block.
-	 * Code block must be 3+ backticks at column 0, followed by blank line or EOF.
+	 * Code block must be 3+ backticks at column 0, closing fence followed by newline or EOF.
 	 * Empty code blocks (no content) are treated as invalid.
-	 *
-	 * Blank line requirement rationale:
-	 * Separates code blocks from following content to prevent ambiguity.
-	 * Codeblocks are distinct semantic units that should be visually isolated.
-	 * The blank line makes it explicit where the code block ends and regular
-	 * content begins, following the "explicit over implicit" design principle.
 	 */
 	#match_code_block(): boolean {
 		let i = this.#index;
 
-		// Must start at column 0 (no leading whitespace)
-		if (i < this.#template.length && this.#template.charCodeAt(i) === SPACE) {
+		// Must start at column 0 (beginning of input or after newline)
+		if (i > 0 && this.#template.charCodeAt(i - 1) !== NEWLINE) {
 			return false;
 		}
 
@@ -1704,15 +1707,7 @@ export class MdzParser {
 						return false;
 					}
 
-					// Check if followed by blank line or EOF
-					const next_j = j + 1;
-					if (next_j >= this.#template.length) {
-						return true; // code block followed by newline + EOF
-					}
-					if (this.#template.charCodeAt(next_j) === NEWLINE) {
-						return true; // code block followed by blank line
-					}
-					return false; // code block followed by single newline + content
+					return true; // code block followed by newline or EOF
 				}
 			}
 			i++;

package/src/lib/ts_helpers.ts

@@ -228,7 +228,7 @@ export const ts_analyze_module_exports = (
 								const decl: DeclarationJson = {
 									name: export_symbol.name,
 									kind,
-									alias_of: {module: original_module, name: original_name},
+									alias_of: {module: original_module, name: original_name, kind},
 								};
 								// Renamed re-exports aren't nodocs - they're new declarations pointing to the original
 								declarations.push({declaration: decl, nodocs: false});

package/src/lib/tsdoc_helpers.ts

@@ -30,7 +30,8 @@
  * ## Behavioral notes
  *
  * Due to TS Compiler API limitations:
- * - Preserves dash separator in `@param` descriptions: `@param x desc` → `"- desc"`
+ * - `@param` and `@mutates` descriptions have leading `- ` stripped for visual consistency
+ *   (TSDoc spec uses `@param name - description` but the separator is aesthetic)
  * - `@throws` tags have `{Type}` stripped by TS API; fallback regex extracts first word as error type
  * - TS API strips URL protocols from `@see` tag text; we use `getText()` to preserve original format including `{@link}` syntax
  *
@@ -125,7 +126,7 @@ export const tsdoc_parse = (
 			// Extract parameter name and description
 			const param_name = ts.isIdentifier(tag.name) ? tag.name.text : tag.name.getText();
 			if (param_name && tag_text) {
-				params.set(param_name, tag_text.trim());
+				params.set(param_name, tag_text.trim().replace(/^-\s+/, ''));
 			}
 		} else if (tag_name === 'returns' && tag_text) {
 			returns = tag_text.trim();
@@ -157,7 +158,7 @@ export const tsdoc_parse = (
 		} else if (tag_name === 'since' && tag_text) {
 			since = tag_text.trim();
 		} else if (tag_name === 'mutates' && tag_text) {
-			mutates.push(tag_text.trim());
+			mutates.push(tag_text.trim().replace(/^-\s+/, ''));
 		} else if (tag_name === 'nodocs') {
 			nodocs = true;
 		}

package/src/lib/tsdoc_mdz.ts

@@ -22,8 +22,9 @@ const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${
  * - `{@link identifier}` → `` `identifier` `` (code formatting)
  * - Bare URLs → returned as-is
  * - Bare identifiers → wrapped in backticks
+ * - `identifier description text` → `` `identifier` description text `` (first token is the reference)
  *
- * @param content Raw `@see` tag content in TSDoc format
+ * @param content - raw `@see` tag content in TSDoc format
  * @returns mdz-formatted string ready for `Mdz` component
  *
  * @example
@@ -36,6 +37,9 @@ const format_reference = (ref: string): string => (mdz_is_url(ref) ? ref : `\`${
  *
  * tsdoc_see_to_mdz('https://example.com')
  * // → 'https://example.com'
+ *
+ * tsdoc_see_to_mdz('library_gen.ts for Gro-specific integration')
+ * // → '`library_gen.ts` for Gro-specific integration'
  * ```
  */
 export const tsdoc_see_to_mdz = (content: string): string => {
@@ -58,5 +62,13 @@ export const tsdoc_see_to_mdz = (content: string): string => {
 		return format_reference(inner);
 	}
 
-	return format_reference(trimmed);
+	// Split at first whitespace: first token is the reference, rest is description
+	const space_index = trimmed.indexOf(' ');
+	if (space_index === -1) {
+		return format_reference(trimmed);
+	}
+
+	const reference = trimmed.slice(0, space_index);
+	const description = trimmed.slice(space_index); // preserve leading space
+	return format_reference(reference) + description;
 };