@jxsuite/studio 0.23.2 → 0.24.0

package/src/markdown/{md-convert.js → md-convert.ts}

@@ -1,3 +1,4 @@
+/// <reference lib="dom" />
 /**
  * Md-convert.js — Bidirectional mdast ↔ Jx conversion
  *
@@ -14,9 +15,12 @@ import { unified } from "unified";
 import remarkStringify from "remark-stringify";
 import remarkDirective from "remark-directive";
 import remarkGfm from "remark-gfm";
-import { MD_ALL } from "./md-allowlist.js";
+import { MD_ALL } from "./md-allowlist";
 import { htmlToJx } from "@jxsuite/parser/transpile";
 
+import type { JxElement, JxMutableNode } from "@jxsuite/schema/types";
+import type { MdastNode } from "@jxsuite/parser/types";
+
 // ─── mdast → Jx ──────────────────────────────────────────────────────────
 
 /**
@@ -24,8 +28,8 @@ import { htmlToJx } from "@jxsuite/parser/transpile";
  *
  * @type {Record<string, (n: MdastNode) => string>}
  */
-const MDAST_TAG_MAP = {
-  heading: (/** @type {MdastNode} */ n) => `h${n.depth}`,
+const MDAST_TAG_MAP: Record<string, (n: MdastNode) => string> = {
+  heading: (n: MdastNode) => `h${n.depth}`,
   paragraph: () => "p",
   text: () => "span",
   emphasis: () => "em",
@@ -35,13 +39,13 @@ const MDAST_TAG_MAP = {
   link: () => "a",
   image: () => "img",
   blockquote: () => "blockquote",
-  list: (/** @type {MdastNode} */ n) => (n.ordered ? "ol" : "ul"),
+  list: (n: MdastNode) => (n.ordered ? "ol" : "ul"),
   listItem: () => "li",
   code: () => "pre",
   thematicBreak: () => "hr",
   table: () => "table",
   tableRow: () => "tr",
-  tableCell: (/** @type {MdastNode} */ n) => (n.isHeader ? "th" : "td"),
+  tableCell: (n: MdastNode) => (n.isHeader ? "th" : "td"),
   break: () => "br",
 };
 
@@ -51,25 +55,23 @@ const MDAST_TAG_MAP = {
  * @param {MdastNode} mdast - Root mdast node (type: 'root')
  * @returns {JxElement} Jx element tree
  */
-export function mdToJx(mdast) {
+export function mdToJx(mdast: MdastNode) {
   if (mdast.type === "root") {
     return {
-      children: /** @type {(JxElement | string)[]} */ (
-        (mdast.children ?? [])
-          .filter((/** @type {MdastNode} */ n) => n.type !== "yaml" && n.type !== "toml")
-          .flatMap(convertMdastNode)
-          .filter(Boolean)
-      ),
+      children: (mdast.children ?? [])
+        .filter((n: MdastNode) => n.type !== "yaml" && n.type !== "toml")
+        .flatMap(convertMdastNode)
+        .filter(Boolean) as (JxElement | string)[],
     };
   }
-  return /** @type {JxElement} */ (convertMdastNode(mdast));
+  return convertMdastNode(mdast) as JxElement;
 }
 
 /**
  * @param {MdastNode} node
  * @returns {JxElement | null}
  */
-function convertMdastNode(node) {
+function convertMdastNode(node: MdastNode) {
   if (!node) return null;
 
   // Directive nodes → custom elements
@@ -84,62 +86,62 @@ function convertMdastNode(node) {
   if (node.type === "html") {
     if (!node.value) return null;
     const nodes = htmlToJx(node.value);
-    return nodes.length === 1
-      ? /** @type {JxElement} */ (nodes[0])
-      : { tagName: "div", children: nodes };
+    return nodes.length === 1 ? (nodes[0] as JxElement) : { tagName: "div", children: nodes };
   }
 
   const tagFn = MDAST_TAG_MAP[node.type];
   if (!tagFn) return null;
 
   const tag = tagFn(node);
-  /** @type {JxElement} */
-  const el = { tagName: tag };
+  const el: JxElement = { tagName: tag };
 
   switch (node.type) {
     case "heading":
     case "paragraph": {
       // If contains only a single text child, flatten to textContent
       if (node.children?.length === 1 && node.children[0].type === "text") {
-        el.textContent = node.children[0].value;
+        el.textContent = node.children[0].value ?? null;
       } else if (node.children?.length) {
-        el.children = /** @type {(JxElement | string)[]} */ (
-          node.children.flatMap(convertMdastNode).filter(Boolean)
-        );
+        el.children = node.children.flatMap(convertMdastNode).filter(Boolean) as (
+          | JxElement
+          | string
+        )[];
       }
       break;
     }
 
     case "text":
-      el.textContent = node.value;
+      el.textContent = node.value ?? null;
       break;
 
     case "emphasis":
     case "strong":
     case "delete": {
       if (node.children?.length === 1 && node.children[0].type === "text") {
-        el.textContent = node.children[0].value;
+        el.textContent = node.children[0].value ?? null;
       } else if (node.children?.length) {
-        el.children = /** @type {(JxElement | string)[]} */ (
-          node.children.flatMap(convertMdastNode).filter(Boolean)
-        );
+        el.children = node.children.flatMap(convertMdastNode).filter(Boolean) as (
+          | JxElement
+          | string
+        )[];
       }
       break;
     }
 
     case "inlineCode":
-      el.textContent = node.value;
+      el.textContent = node.value ?? null;
       break;
 
     case "link":
       el.attributes = { href: node.url ?? "" };
       if (node.title) el.attributes.title = node.title;
       if (node.children?.length === 1 && node.children[0].type === "text") {
-        el.textContent = node.children[0].value;
+        el.textContent = node.children[0].value ?? null;
       } else if (node.children?.length) {
-        el.children = /** @type {(JxElement | string)[]} */ (
-          node.children.flatMap(convertMdastNode).filter(Boolean)
-        );
+        el.children = node.children.flatMap(convertMdastNode).filter(Boolean) as (
+          | JxElement
+          | string
+        )[];
       }
       break;
 
@@ -151,17 +153,19 @@ function convertMdastNode(node) {
     case "blockquote":
     case "listItem":
       if (node.children?.length) {
-        el.children = /** @type {(JxElement | string)[]} */ (
-          node.children.flatMap(convertMdastNode).filter(Boolean)
-        );
+        el.children = node.children.flatMap(convertMdastNode).filter(Boolean) as (
+          | JxElement
+          | string
+        )[];
       }
       break;
 
     case "list":
       if (node.children?.length) {
-        el.children = /** @type {(JxElement | string)[]} */ (
-          node.children.flatMap(convertMdastNode).filter(Boolean)
-        );
+        el.children = node.children.flatMap(convertMdastNode).filter(Boolean) as (
+          | JxElement
+          | string
+        )[];
       }
       if (node.start != null && node.start !== 1) {
         el.attributes = { start: String(node.start) };
@@ -173,7 +177,7 @@ function convertMdastNode(node) {
       el.children = [
         {
           tagName: "code",
-          textContent: node.value,
+          textContent: node.value ?? null,
           ...(node.lang ? { attributes: { class: `language-${node.lang}` } } : {}),
         },
       ];
@@ -186,36 +190,36 @@ function convertMdastNode(node) {
 
     case "table": {
       // Mdast tables have rows directly; split into thead/tbody
-      const rows = /** @type {JxElement[]} */ (
-        (node.children ?? []).flatMap(convertMdastNode).filter(Boolean)
-      );
+      const rows = (node.children ?? []).flatMap(convertMdastNode).filter(Boolean) as JxElement[];
       const thead =
         rows.length > 0
-          ? { tagName: "thead", children: /** @type {(JxElement | string)[]} */ ([rows[0]]) }
+          ? { tagName: "thead", children: [rows[0]] as (JxElement | string)[] }
           : null;
       const tbody =
         rows.length > 1
-          ? { tagName: "tbody", children: /** @type {(JxElement | string)[]} */ (rows.slice(1)) }
+          ? { tagName: "tbody", children: rows.slice(1) as (JxElement | string)[] }
           : null;
-      el.children = /** @type {(JxElement | string)[]} */ ([thead, tbody].filter(Boolean));
+      el.children = [thead, tbody].filter(Boolean) as (JxElement | string)[];
       break;
     }
 
     case "tableRow":
       if (node.children?.length) {
-        el.children = /** @type {(JxElement | string)[]} */ (
-          node.children.flatMap(convertMdastNode).filter(Boolean)
-        );
+        el.children = node.children.flatMap(convertMdastNode).filter(Boolean) as (
+          | JxElement
+          | string
+        )[];
       }
       break;
 
     case "tableCell":
       if (node.children?.length === 1 && node.children[0].type === "text") {
-        el.textContent = node.children[0].value;
+        el.textContent = node.children[0].value ?? null;
       } else if (node.children?.length) {
-        el.children = /** @type {(JxElement | string)[]} */ (
-          node.children.flatMap(convertMdastNode).filter(Boolean)
-        );
+        el.children = node.children.flatMap(convertMdastNode).filter(Boolean) as (
+          | JxElement
+          | string
+        )[];
       }
       break;
   }
@@ -227,25 +231,23 @@ function convertMdastNode(node) {
  * @param {MdastNode} node
  * @returns {JxElement | null}
  */
-function convertDirective(node) {
-  /** @type {JxElement} */
-  const el = { tagName: node.name };
+function convertDirective(node: MdastNode) {
+  const el: JxElement = { tagName: node.name ?? "div" };
   if (node.attributes && Object.keys(node.attributes).length > 0) {
     el.attributes = { ...node.attributes };
   }
   if (node.type === "textDirective") {
     // Text directives place label as textContent
     if (node.children?.length === 1 && node.children[0].type === "text") {
-      el.textContent = node.children[0].value;
+      el.textContent = node.children[0].value ?? null;
     } else if (node.children?.length) {
-      el.children = /** @type {(JxElement | string)[]} */ (
-        node.children.flatMap(convertMdastNode).filter(Boolean)
-      );
+      el.children = node.children.flatMap(convertMdastNode).filter(Boolean) as (
+        | JxElement
+        | string
+      )[];
     }
   } else if (node.type === "containerDirective" && node.children?.length) {
-    el.children = /** @type {(JxElement | string)[]} */ (
-      node.children.flatMap(convertMdastNode).filter(Boolean)
-    );
+    el.children = node.children.flatMap(convertMdastNode).filter(Boolean) as (JxElement | string)[];
   }
   return el;
 }
@@ -308,15 +310,11 @@ const TAG_MDAST_MAP = {
  * @param {JxElement} jx - Jx element tree (root content div)
  * @returns {MdastNode} Mdast root node
  */
-export function jxToMd(jx) {
-  const childArray = /** @type {(JxElement | string)[]} */ (
-    Array.isArray(jx.children) ? jx.children : []
-  );
-  const children = /** @type {MdastNode[]} */ (
-    childArray
-      .map((/** @type {JxElement | string} */ child) => convertJxNode(child, true))
-      .filter(Boolean)
-  );
+export function jxToMd(jx: JxElement) {
+  const childArray = Array.isArray(jx.children) ? jx.children : ([] as (JxElement | string)[]);
+  const children = childArray
+    .map((child: JxElement | string) => convertJxNode(child, true))
+    .filter(Boolean) as MdastNode[];
 
   return { type: "root", children };
 }
@@ -328,7 +326,7 @@ export function jxToMd(jx) {
  * @param {JxElement} el
  * @returns {boolean}
  */
-function hasJxProps(el) {
+function hasJxProps(el: JxElement) {
   for (const key of Object.keys(el)) {
     if (
       key === "tagName" ||
@@ -350,7 +348,7 @@ function hasJxProps(el) {
  * @param {boolean} isBlock - Whether this element is in a block context
  * @returns {MdastNode | null} Mdast node
  */
-function convertJxNode(el, isBlock) {
+function convertJxNode(el: JxElement | string | number, isBlock: boolean): MdastNode | null {
   // Bare string/number text nodes → mdast text nodes
   if (typeof el === "string" || typeof el === "number") {
     return { type: "text", value: String(el) };
@@ -364,7 +362,7 @@ function convertJxNode(el, isBlock) {
     return convertToDirective(el, isBlock);
   }
 
-  const mdastType = /** @type {Record<string, string>} */ (TAG_MDAST_MAP)[tag];
+  const mdastType = (TAG_MDAST_MAP as Record<string, string>)[tag];
   if (!mdastType) return null;
 
   switch (mdastType) {
@@ -398,17 +396,17 @@ function convertJxNode(el, isBlock) {
     case "link":
       return {
         type: "link",
-        url: /** @type {string} */ (el.attributes?.href) ?? "",
-        title: /** @type {string | null} */ (el.attributes?.title) ?? null,
+        url: (el.attributes?.href as string) ?? "",
+        title: (el.attributes?.title as string | null) ?? null,
         children: inlineChildren(el),
       };
 
     case "image":
       return {
         type: "image",
-        url: /** @type {string} */ (el.attributes?.src) ?? "",
-        alt: /** @type {string} */ (el.attributes?.alt) ?? "",
-        title: /** @type {string | null} */ (el.attributes?.title) ?? null,
+        url: (el.attributes?.src as string) ?? "",
+        alt: (el.attributes?.alt as string) ?? "",
+        title: (el.attributes?.title as string | null) ?? null,
       };
 
     case "blockquote":
@@ -421,14 +419,11 @@ function convertJxNode(el, isBlock) {
       return {
         type: "list",
         ordered: tag === "ol",
-        start:
-          tag === "ol" ? parseInt(/** @type {string} */ (el.attributes?.start), 10) || 1 : null,
+        start: tag === "ol" ? parseInt(el.attributes?.start as string, 10) || 1 : null,
         spread: false,
-        children: /** @type {MdastNode[]} */ (
-          /** @type {(JxElement | string)[]} */ (el.children ?? [])
-            .map((/** @type {JxElement | string} */ c) => convertJxNode(c, true))
-            .filter(Boolean)
-        ),
+        children: ((el.children ?? []) as (JxElement | string)[])
+          .map((c: JxElement | string) => convertJxNode(c, true))
+          .filter(Boolean) as MdastNode[],
       };
 
     case "listItem":
@@ -440,10 +435,10 @@ function convertJxNode(el, isBlock) {
 
     case "code": {
       // pre > code → fenced code block
-      const codeChild = /** @type {JxElement | undefined} */ (
-        Array.isArray(el.children) ? el.children[0] : undefined
-      );
-      const langClass = /** @type {string} */ (codeChild?.attributes?.class) ?? "";
+      const codeChild = Array.isArray(el.children)
+        ? (el.children[0] as JxElement | undefined)
+        : undefined;
+      const langClass = (codeChild?.attributes?.class as string) ?? "";
       const lang = langClass.replace("language-", "") || null;
       return {
         type: "code",
@@ -460,12 +455,11 @@ function convertJxNode(el, isBlock) {
 
     case "table": {
       // Flatten thead/tbody back to rows
-      /** @type {MdastNode[]} */
-      const rows = [];
-      for (const section of /** @type {(JxElement | string)[]} */ (el.children ?? [])) {
+      const rows: MdastNode[] = [];
+      for (const section of (el.children ?? []) as (JxElement | string)[]) {
         if (typeof section === "string") continue;
         if (section.tagName === "thead" || section.tagName === "tbody") {
-          for (const row of /** @type {(JxElement | string)[]} */ (section.children ?? [])) {
+          for (const row of (section.children ?? []) as (JxElement | string)[]) {
             const mdRow = convertJxNode(row, true);
             if (mdRow) {
               // Mark header cells
@@ -488,11 +482,9 @@ function convertJxNode(el, isBlock) {
     case "tableRow":
       return {
         type: "tableRow",
-        children: /** @type {MdastNode[]} */ (
-          /** @type {(JxElement | string)[]} */ (el.children ?? [])
-            .map((/** @type {JxElement | string} */ c) => convertJxNode(c, false))
-            .filter(Boolean)
-        ),
+        children: ((el.children ?? []) as (JxElement | string)[])
+          .map((c: JxElement | string) => convertJxNode(c, false))
+          .filter(Boolean) as MdastNode[],
       };
 
     case "tableCell":
@@ -512,15 +504,13 @@ function convertJxNode(el, isBlock) {
  * @param {JxElement} el
  * @returns {MdastNode[]}
  */
-function inlineChildren(el) {
+function inlineChildren(el: JxElement): MdastNode[] {
   if (el.textContent != null) {
     return [{ type: "text", value: String(el.textContent) }];
   }
-  return /** @type {MdastNode[]} */ (
-    /** @type {(JxElement | string)[]} */ (el.children ?? [])
-      .map((/** @type {JxElement | string} */ c) => convertJxNode(c, false))
-      .filter(Boolean)
-  );
+  return ((el.children ?? []) as (JxElement | string)[])
+    .map((c: JxElement | string) => convertJxNode(c, false))
+    .filter(Boolean) as MdastNode[];
 }
 
 /**
@@ -529,16 +519,14 @@ function inlineChildren(el) {
  * @param {JxElement} el
  * @returns {MdastNode[]}
  */
-function blockChildren(el) {
+function blockChildren(el: JxElement): MdastNode[] {
   if (el.textContent != null) {
     // Wrap bare text in a paragraph
     return [{ type: "paragraph", children: [{ type: "text", value: String(el.textContent) }] }];
   }
-  return /** @type {MdastNode[]} */ (
-    /** @type {(JxElement | string)[]} */ (el.children ?? [])
-      .map((/** @type {JxElement | string} */ c) => convertJxNode(c, true))
-      .filter(Boolean)
-  );
+  return ((el.children ?? []) as (JxElement | string)[])
+    .map((c: JxElement | string) => convertJxNode(c, true))
+    .filter(Boolean) as MdastNode[];
 }
 
 /**
@@ -549,27 +537,24 @@ function blockChildren(el) {
  * @param {JxElement} el
  * @returns {Record<string, string>}
  */
-function collectDirectiveAttrs(el) {
-  /** @type {Record<string, unknown>} */
-  const propsObj = {};
+function collectDirectiveAttrs(el: JxElement) {
+  const propsObj: Record<string, unknown> = {};
 
   for (const [key, value] of Object.entries(el)) {
-    if (
-      key === "tagName" ||
-      key === "children" ||
-      key === "textContent" ||
-      key === "innerHTML" ||
-      key === "attributes"
-    )
+    if (key === "tagName" || key === "textContent" || key === "innerHTML" || key === "attributes")
       continue;
+    if (key === "children") {
+      if (value && typeof value === "object" && !Array.isArray(value)) {
+        propsObj.children = value;
+      }
+      continue;
+    }
     propsObj[key] = value;
   }
 
   // Merge HTML attributes
   if (el.attributes) {
-    for (const [key, value] of Object.entries(
-      /** @type {Record<string, unknown>} */ (el.attributes),
-    )) {
+    for (const [key, value] of Object.entries(el.attributes as Record<string, unknown>)) {
       propsObj[key] = value;
     }
   }
@@ -585,8 +570,8 @@ function collectDirectiveAttrs(el) {
  * @param {boolean} isBlock
  * @returns {MdastNode}
  */
-function convertToDirective(el, isBlock) {
-  const tag = /** @type {string} */ (el.tagName) ?? "div";
+function convertToDirective(el: JxElement, isBlock: boolean): MdastNode {
+  const tag = (el.tagName as string) ?? "div";
   const attrs = collectDirectiveAttrs(el);
 
   if (!isBlock) {
@@ -598,16 +583,19 @@ function convertToDirective(el, isBlock) {
       children:
         el.textContent != null
           ? [{ type: "text", value: String(el.textContent) }]
-          : /** @type {MdastNode[]} */ (
-              /** @type {(JxElement | string)[]} */ (el.children ?? [])
-                .map((/** @type {JxElement | string} */ c) => convertJxNode(c, false))
-                .filter(Boolean)
-            ),
+          : (((el.children ?? []) as (JxElement | string)[])
+              .map((c: JxElement | string) => convertJxNode(c, false))
+              .filter(Boolean) as MdastNode[]),
     };
   }
 
   // Block without children → leafDirective
-  const childArray = /** @type {(JxElement | string)[] | undefined} */ (el.children);
+  const rawChildren = el.children;
+  const childrenIsObject =
+    rawChildren && typeof rawChildren === "object" && !Array.isArray(rawChildren);
+  const childArray = childrenIsObject
+    ? undefined
+    : (rawChildren as (JxElement | string)[] | undefined);
   if (!childArray?.length && el.textContent == null) {
     return {
       type: "leafDirective",
@@ -627,19 +615,15 @@ function convertToDirective(el, isBlock) {
   } else if (INLINE_CONTENT_TAGS.has(tag)) {
     // Tags with inline content model: wrap all children in a single paragraph
     // so remark serializes them as one continuous inline flow
-    const inlineNodes = /** @type {MdastNode[]} */ (
-      /** @type {(JxElement | string)[]} */ (el.children ?? [])
-        .map((/** @type {JxElement | string} */ c) => convertJxNode(c, false))
-        .filter(Boolean)
-    );
+    const inlineNodes = ((el.children ?? []) as (JxElement | string)[])
+      .map((c: JxElement | string) => convertJxNode(c, false))
+      .filter(Boolean) as MdastNode[];
     directiveChildren =
       inlineNodes.length > 0 ? [{ type: "paragraph", children: inlineNodes }] : [];
   } else {
-    directiveChildren = /** @type {MdastNode[]} */ (
-      /** @type {(JxElement | string)[]} */ (el.children ?? [])
-        .map((/** @type {JxElement | string} */ c) => convertJxNode(c, true))
-        .filter(Boolean)
-    );
+    directiveChildren = ((el.children ?? []) as (JxElement | string)[])
+      .map((c: JxElement | string) => convertJxNode(c, true))
+      .filter(Boolean) as MdastNode[];
   }
 
   return {
@@ -696,15 +680,13 @@ const JX_ANNOTATION_KEYS = new Set(["$title", "$description"]);
  * @param {JxMutableNode} doc - Jx JSON document
  * @returns {string} Jx Markdown source
  */
-export function jxDocToMd(doc) {
+export function jxDocToMd(doc: JxMutableNode) {
   const { stringify: stringifyYaml } = yamlImport();
 
-  /** @type {string[]} */
-  const lines = [];
+  const lines: string[] = [];
 
   // Emit YAML frontmatter
-  /** @type {Record<string, unknown>} */
-  const frontmatter = {};
+  const frontmatter: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(doc)) {
     if (key === "children") continue;
     frontmatter[key] = value;
@@ -719,20 +701,16 @@ export function jxDocToMd(doc) {
 
   // Convert children to mdast and stringify with remark
   if (Array.isArray(doc.children) && doc.children.length > 0) {
-    const mdastChildren = /** @type {MdastNode[]} */ (
-      doc.children
-        .map((/** @type {JxMutableNode | string} */ child) =>
-          convertJxNode(/** @type {JxElement | string} */ (child), true),
-        )
-        .filter(Boolean)
-    );
+    const mdastChildren = doc.children
+      .map((child: JxMutableNode | string) => convertJxNode(child as JxElement | string, true))
+      .filter(Boolean) as MdastNode[];
 
     const mdast = { type: "root", children: mdastChildren };
     const md = unified()
       .use(remarkGfm)
       .use(remarkDirective)
       .use(remarkStringify, { bullet: "-", emphasis: "*", strong: "*" })
-      .stringify(/** @type {import("mdast").Root} */ (/** @type {unknown} */ (mdast)));
+      .stringify(mdast as unknown as import("mdast").Root);
 
     lines.push(/** @type {string} */ (md));
   }
@@ -750,7 +728,7 @@ export function jxDocToMd(doc) {
  *
  * @returns {{ stringify: (v: unknown) => string }}
  */
-let _yaml = /** @type {{ stringify: (v: unknown) => string } | null} */ (null);
+let _yaml: { stringify: (v: unknown) => string } | null = null;
 function yamlImport() {
   if (!_yaml) {
     // Dynamic require avoided; use the yaml package already available in studio
@@ -767,7 +745,7 @@ function yamlImport() {
  * @param {number} indent
  * @returns {string}
  */
-function yamlStringifySimple(value, indent = 0) {
+function yamlStringifySimple(value: unknown, indent: number = 0): string {
   if (value === null || value === undefined) return "null";
   if (typeof value === "boolean") return String(value);
   if (typeof value === "number") return String(value);
@@ -785,13 +763,13 @@ function yamlStringifySimple(value, indent = 0) {
     if (value.length === 0) return "[]";
     return value
       .map((item) => {
-        const itemStr = yamlStringifySimple(item, indent + 1);
+        const itemStr: string = yamlStringifySimple(item, indent + 1);
         if (typeof item === "object" && item !== null && !Array.isArray(item)) {
           // Object items: first key on same line as -, rest indented
-          const objLines = itemStr.split("\n");
+          const objLines: string[] = itemStr.split("\n");
           return `${prefix}- ${objLines[0]}\n${objLines
             .slice(1)
-            .map((l) => `${prefix}  ${l}`)
+            .map((l: string) => `${prefix}  ${l}`)
             .join("\n")}`;
         }
         return `${prefix}- ${itemStr}`;
@@ -800,11 +778,11 @@ function yamlStringifySimple(value, indent = 0) {
   }
 
   if (typeof value === "object") {
-    const entries = Object.entries(/** @type {Record<string, unknown>} */ (value));
+    const entries = Object.entries(value as Record<string, unknown>);
     if (entries.length === 0) return "{}";
     return entries
       .map(([k, v]) => {
-        const valStr = yamlStringifySimple(v, indent + 1);
+        const valStr: string = yamlStringifySimple(v, indent + 1);
         if (typeof v === "object" && v !== null) {
           return `${prefix}${k}:\n${valStr}`;
         }
@@ -823,11 +801,10 @@ function yamlStringifySimple(value, indent = 0) {
  * @param {Record<string, unknown>} propsObj
  * @returns {Record<string, string>}
  */
-function collapsePropsToAttrMap(propsObj) {
-  /** @type {Record<string, string>} */
-  const result = {};
+function collapsePropsToAttrMap(propsObj: Record<string, unknown>) {
+  const result: Record<string, string> = {};
 
-  function walk(/** @type {Record<string, unknown>} */ obj, /** @type {string} */ prefix) {
+  function walk(obj: Record<string, unknown>, prefix: string) {
     for (const [key, value] of Object.entries(obj)) {
       let mdAttrKey = key;
       // Strip $ prefix for Jx keywords
@@ -846,7 +823,7 @@ function collapsePropsToAttrMap(propsObj) {
       if (key === "@") {
         // Bare "@" (no media name) — treat contents as base-level style props
         if (value && typeof value === "object" && !Array.isArray(value)) {
-          walk(/** @type {Record<string, unknown>} */ (value), prefix);
+          walk(value as Record<string, unknown>, prefix);
         }
         continue;
       }
@@ -857,7 +834,7 @@ function collapsePropsToAttrMap(propsObj) {
       const fullKey = prefix ? `${prefix}.${mdAttrKey}` : mdAttrKey;
 
       if (value && typeof value === "object" && !Array.isArray(value)) {
-        walk(/** @type {Record<string, unknown>} */ (value), fullKey);
+        walk(value as Record<string, unknown>, fullKey);
       } else {
         result[fullKey] = String(value);
       }