@jxsuite/parser 0.23.2 → 0.25.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jxsuite/parser",
-  "version": "0.23.2",
+  "version": "0.25.0",
   "description": "Jx markdown parser and external class integration",
   "license": "MIT",
   "repository": {
@@ -13,29 +13,31 @@
   ],
   "type": "module",
   "exports": {
-    ".": "./src/md.js",
-    "./content": "./src/content.js",
+    ".": "./src/md.ts",
+    "./content": "./src/content.ts",
     "./ContentCollection.class.json": "./src/ContentCollection.class.json",
     "./ContentEntry.class.json": "./src/ContentEntry.class.json",
     "./MarkdownCollection.class.json": "./src/MarkdownCollection.class.json",
     "./MarkdownFile.class.json": "./src/MarkdownFile.class.json",
-    "./transpile": "./src/transpile.js",
-    "./html-to-jx": "./src/html-to-jx.js"
+    "./transpile": "./src/transpile.ts",
+    "./html-to-jx": "./src/html-to-jx.ts",
+    "./types": "./src/types.ts"
   },
   "publishConfig": {
     "provenance": true
   },
   "scripts": {
-    "test": "bun test",
-    "test:coverage": "bun test --coverage",
+    "test": "bun test --isolate",
+    "test:coverage": "bun test --isolate --coverage",
     "upgrade": "bunx npm-check-updates -u && bun install"
   },
   "dependencies": {
+    "@jxsuite/schema": "^0.25.0",
     "glob": "^13.0.6",
     "hast-util-from-html": "^2.0.3",
     "hast-util-whitespace": "^3.0.0",
     "mdast-util-to-string": "^4.0.0",
-    "property-information": "^7.1.0",
+    "property-information": "^7.2.0",
     "rehype-stringify": "^10.0.1",
     "remark-directive": "^4.0.0",
     "remark-frontmatter": "^5.0.0",
@@ -48,7 +50,7 @@
   },
   "devDependencies": {
     "@happy-dom/global-registrator": "^20.9.0",
-    "@jxsuite/runtime": "^0.23.2",
+    "@jxsuite/runtime": "^0.25.0",
     "@types/hast": "^3.0.4"
   }
 }

package/src/ContentCollection.class.json

@@ -4,7 +4,7 @@
   "description": "Query a project content type with filter, sort, and limit",
   "$prototype": "Class",
   "extends": "Object",
-  "$implementation": "./content.js",
+  "$implementation": "./content.ts",
 
   "$defs": {
     "parameters": {
@@ -105,6 +105,7 @@
         "scope": "instance",
         "identifier": "resolve",
         "parameters": [],
+        "returns": { "type": "array" },
         "description": "Query the content type entries with filter, sort, and limit"
       }
     }

package/src/ContentEntry.class.json

@@ -4,7 +4,7 @@
   "description": "Fetch a single entry from a content type by ID",
   "$prototype": "Class",
   "extends": "Object",
-  "$implementation": "./content.js",
+  "$implementation": "./content.ts",
 
   "$defs": {
     "parameters": {

package/src/{content.js → content.ts}

@@ -6,6 +6,26 @@
  * queryContentType, findEntry) used by both the classes and the server endpoint.
  */
 
+import type { ContentLoaderEntry } from "./types.ts";
+
+interface CollectionConfig {
+  contentType?: string;
+  filter?: unknown;
+  sort?: unknown;
+  limit?: number;
+  _project?: { contentTypes?: Map<string, ContentLoaderEntry[]>; [k: string]: unknown };
+  [k: string]: unknown;
+}
+
+interface EntryConfig {
+  contentType?: string;
+  id?: unknown;
+  field?: string;
+  _project?: { contentTypes?: Map<string, ContentLoaderEntry[]>; [k: string]: unknown };
+  _document?: { route?: { _pathParams?: Record<string, string> }; [k: string]: unknown };
+  [k: string]: unknown;
+}
+
 // ─── Query Functions ────────────────────────────────────────────────────────
 
 /**
@@ -15,7 +35,10 @@
  * @param {ContentLoaderEntry} entry
  * @returns {boolean}
  */
-export function evaluateFilterRule(rule, entry) {
+export function evaluateFilterRule(
+  rule: { field: string; op: string; value?: unknown },
+  entry: ContentLoaderEntry,
+) {
   const actual = rule.field === "id" ? entry.id : entry.data[rule.field];
   switch (rule.op) {
     case "==":
@@ -31,13 +54,13 @@ export function evaluateFilterRule(rule, entry) {
     case "not contains":
       return typeof actual === "string" && !actual.includes(String(rule.value ?? ""));
     case ">":
-      return /** @type {any} */ (actual) > /** @type {any} */ (rule.value);
+      return Number(actual) > Number(rule.value);
     case "<":
-      return /** @type {any} */ (actual) < /** @type {any} */ (rule.value);
+      return Number(actual) < Number(rule.value);
     case ">=":
-      return /** @type {any} */ (actual) >= /** @type {any} */ (rule.value);
+      return Number(actual) >= Number(rule.value);
     case "<=":
-      return /** @type {any} */ (actual) <= /** @type {any} */ (rule.value);
+      return Number(actual) <= Number(rule.value);
     default:
       return true;
   }
@@ -54,13 +77,19 @@ export function evaluateFilterRule(rule, entry) {
  * }} [query]
  * @returns {ContentLoaderEntry[]} Filtered, sorted, limited entries
  */
-export function queryContentType(entries, query = {}) {
+export function queryContentType(
+  entries: ContentLoaderEntry[],
+  query: {
+    filter?: Record<string, unknown> | Array<{ field: string; op: string; value?: unknown }>;
+    sort?: { field: string; order?: string } | Array<{ field: string; order?: string }>;
+    limit?: number;
+  } = {},
+) {
   let result = [...entries];
 
   // Filter
   if (query.filter) {
-    /** @type {{ field: string; op: string; value?: unknown }[]} */
-    let rules;
+    let rules: { field: string; op: string; value?: unknown }[];
     if (Array.isArray(query.filter)) {
       rules = query.filter;
     } else if (typeof query.filter === "object") {
@@ -76,8 +105,8 @@ export function queryContentType(entries, query = {}) {
     const sortRules = Array.isArray(query.sort) ? query.sort : [query.sort];
     result.sort((a, b) => {
       for (const { field, order = "asc" } of sortRules) {
-        const aVal = /** @type {string | number} */ (field === "id" ? a.id : (a.data[field] ?? ""));
-        const bVal = /** @type {string | number} */ (field === "id" ? b.id : (b.data[field] ?? ""));
+        const aVal = field === "id" ? a.id : ((a.data[field] ?? "") as string | number);
+        const bVal = field === "id" ? b.id : ((b.data[field] ?? "") as string | number);
         if (aVal < bVal) return order === "asc" ? -1 : 1;
         if (aVal > bVal) return order === "asc" ? 1 : -1;
       }
@@ -100,35 +129,16 @@ export function queryContentType(entries, query = {}) {
  * @param {string} id - Entry ID to find
  * @returns {ContentLoaderEntry | null} The matching entry or null
  */
-export function findEntry(entries, id) {
+export function findEntry(entries: ContentLoaderEntry[], id: string) {
   return entries.find((e) => e.id === id) ?? null;
 }
 
 // ─── Class Implementations ──────────────────────────────────────────────────
 
-/**
- * @typedef {{
- *   contentType?: string;
- *   filter?: unknown;
- *   sort?: unknown;
- *   limit?: number;
- *   _project?: { contentTypes?: Map<string, ContentLoaderEntry[]>; [k: string]: unknown };
- *   [k: string]: unknown;
- * }} CollectionConfig
- *
- * @typedef {{
- *   contentType?: string;
- *   id?: unknown;
- *   field?: string;
- *   _project?: { contentTypes?: Map<string, ContentLoaderEntry[]>; [k: string]: unknown };
- *   _document?: { route?: { _pathParams?: Record<string, string> }; [k: string]: unknown };
- *   [k: string]: unknown;
- * }} EntryConfig
- */
-
 export class ContentCollection {
+  config: CollectionConfig;
   /** @param {CollectionConfig} config */
-  constructor(config) {
+  constructor(config: CollectionConfig) {
     this.config = config;
   }
 
@@ -136,13 +146,24 @@ export class ContentCollection {
     const { contentType, filter, sort, limit, _project } = this.config;
     const entries = _project?.contentTypes?.get(contentType ?? "");
     if (!entries) return [];
-    return queryContentType(entries, /** @type {any} */ ({ filter, sort, limit }));
+    return queryContentType(entries, {
+      ...(filter != null && {
+        filter: filter as
+          | Record<string, unknown>
+          | Array<{ field: string; op: string; value?: unknown }>,
+      }),
+      ...(sort != null && {
+        sort: sort as { field: string; order?: string } | Array<{ field: string; order?: string }>,
+      }),
+      ...(limit != null && { limit }),
+    });
   }
 }
 
 export class ContentEntry {
+  config: EntryConfig;
   /** @param {EntryConfig} config */
-  constructor(config) {
+  constructor(config: EntryConfig) {
     this.config = config;
   }
 
@@ -155,16 +176,16 @@ export class ContentEntry {
     if (
       resolvedId &&
       typeof resolvedId === "object" &&
-      /** @type {{ $ref?: string }} */ (resolvedId).$ref?.startsWith("#/$params/")
+      (resolvedId as { $ref?: string }).$ref?.startsWith("#/$params/")
     ) {
-      const paramName = /** @type {{ $ref: string }} */ (resolvedId).$ref.replace("#/$params/", "");
+      const paramName = (resolvedId as { $ref: string }).$ref.replace("#/$params/", "");
       resolvedId = _document?.route?._pathParams?.[paramName];
     }
     if (!resolvedId) return null;
 
     if (field && field !== "id") {
-      return entries.find((e) => e.data[field] === resolvedId) ?? null;
+      return entries.find((e: ContentLoaderEntry) => e.data[field] === resolvedId) ?? null;
     }
-    return findEntry(entries, /** @type {string} */ (resolvedId));
+    return findEntry(entries, resolvedId as string);
   }
 }

package/src/{html-to-jx.js → html-to-jx.ts}

@@ -2,7 +2,8 @@ import { fromHtml } from "hast-util-from-html";
 import { whitespace } from "hast-util-whitespace";
 import { find, html as htmlInfo } from "property-information";
 
-/** @typedef {import("hast").Nodes} HastNode */
+import type { Nodes as HastNode } from "hast";
+import type { JxElement } from "@jxsuite/schema/types";
 
 /**
  * Convert an HTML string into an array of Jx tree nodes.
@@ -10,18 +11,17 @@ import { find, html as htmlInfo } from "property-information";
  * @param {string} htmlString
  * @returns {(JxElement | string)[]}
  */
-export function htmlToJx(htmlString) {
+export function htmlToJx(htmlString: string) {
   const hast = fromHtml(htmlString, { fragment: true });
-  return convertHastChildren(/** @type {HastNode[]} */ (hast.children));
+  return convertHastChildren(hast.children as HastNode[]);
 }
 
 /**
  * @param {HastNode[]} children
  * @returns {(JxElement | string)[]}
  */
-function convertHastChildren(children) {
-  /** @type {(JxElement | string)[]} */
-  const result = [];
+function convertHastChildren(children: HastNode[]) {
+  const result: (JxElement | string)[] = [];
   for (const child of children) {
     const converted = convertHastNode(child);
     if (converted != null) result.push(converted);
@@ -33,15 +33,14 @@ function convertHastChildren(children) {
  * @param {HastNode} node
  * @returns {JxElement | string | null}
  */
-function convertHastNode(node) {
+function convertHastNode(node: HastNode) {
   if (node.type === "text") {
-    if (whitespace(/** @type {HastNode} */ (/** @type {unknown} */ (node)))) return null;
+    if (whitespace(node as unknown as HastNode)) return null;
     return node.value ?? null;
   }
 
   if (node.type === "element") {
-    /** @type {JxElement} */
-    const el = { tagName: node.tagName };
+    const el: JxElement = { tagName: node.tagName };
 
     if (node.properties && Object.keys(node.properties).length > 0) {
       const { style, attrs } = hastPropsToJx(node.properties);
@@ -54,7 +53,7 @@ function convertHastNode(node) {
     if (kids.length === 1 && typeof kids[0] === "string") {
       el.textContent = kids[0];
     } else if (kids.length > 0) {
-      el.children = /** @type {JxElement[]} */ (kids);
+      el.children = kids as JxElement[];
     }
 
     return el;
@@ -67,11 +66,9 @@ function convertHastNode(node) {
  * @param {Record<string, unknown>} properties
  * @returns {{ style: Record<string, string>; attrs: Record<string, string> }}
  */
-function hastPropsToJx(properties) {
-  /** @type {Record<string, string>} */
-  const attrs = {};
-  /** @type {Record<string, string>} */
-  const style = {};
+function hastPropsToJx(properties: Record<string, unknown>) {
+  const attrs: Record<string, string> = {};
+  const style: Record<string, string> = {};
 
   for (const [key, value] of Object.entries(properties)) {
     if (value === false || value === undefined || value === null) continue;
@@ -99,7 +96,7 @@ function hastPropsToJx(properties) {
  * @param {string} styleStr
  * @param {Record<string, string>} out
  */
-function parseInlineStyle(styleStr, out) {
+function parseInlineStyle(styleStr: string, out: Record<string, string>) {
   for (const decl of styleStr.split(";")) {
     const colon = decl.indexOf(":");
     if (colon === -1) continue;

package/src/{md.js → md.ts}

@@ -20,7 +20,9 @@ import remarkDirective from "remark-directive";
 import { readFileSync } from "node:fs";
 import { basename, extname, resolve as resolvePath } from "node:path";
 import { globSync } from "glob";
-import { mdastNodeToJx } from "./transpile.js";
+import { mdastNodeToJx } from "./transpile.ts";
+import type { MarkdownFileResult, TocEntry, MdastNode } from "./types.ts";
+import type { JxElement } from "@jxsuite/schema/types";
 
 // ─── Tree utilities (inline to avoid Bun ESM resolution issues with unist-util-*) ──
 
@@ -31,18 +33,22 @@ import { mdastNodeToJx } from "./transpile.js";
  * @param {string | function} typeOrVisitor
  * @param {function} [maybeVisitor]
  */
-function visit(tree, typeOrVisitor, maybeVisitor) {
+function visit(
+  tree: MdastNode,
+  typeOrVisitor: string | ((node: MdastNode) => void),
+  maybeVisitor?: (node: MdastNode) => void,
+) {
   const type = typeof typeOrVisitor === "string" ? typeOrVisitor : null;
   const visitor = type ? maybeVisitor : typeOrVisitor;
 
-  function walk(/** @type {MdastNode} */ node) {
+  function walk(node: MdastNode) {
     if (!node || typeof node !== "object") return;
-    if (!type || node.type === type) /** @type {Function} */ (visitor)(node);
+    if (!type || node.type === type) (visitor as Function)(node);
     if (Array.isArray(node.children)) {
       for (const child of node.children) walk(child);
     }
   }
-  walk(/** @type {MdastNode} */ (tree));
+  walk(tree as MdastNode);
 }
 
 /**
@@ -51,7 +57,7 @@ function visit(tree, typeOrVisitor, maybeVisitor) {
  * @param {MdastNode} node
  * @returns {string}
  */
-function mdastToString(node) {
+function mdastToString(node: MdastNode): string {
   if (!node) return "";
   if (typeof node === "string") return node;
   if (node.value) return node.value;
@@ -67,7 +73,7 @@ function mdastToString(node) {
  * @param {string} text
  * @returns {number} Minutes (rounded up, minimum 1)
  */
-function readingTime(text) {
+function readingTime(text: string) {
   const words = text.split(/\s+/).filter(Boolean).length;
   return Math.max(1, Math.ceil(words / 200));
 }
@@ -78,10 +84,10 @@ function readingTime(text) {
  * @param {object} tree - Mdast AST
  * @returns {{ depth: number; text: string; id: string }[]}
  */
-function extractToc(tree) {
+function extractToc(tree: MdastNode) {
   /** @type {{ depth: number; text: string; id: string }[]} */
-  const entries = [];
-  visit(tree, "heading", (/** @type {MdastNode} */ node) => {
+  const entries: TocEntry[] = [];
+  visit(tree, "heading", (node: MdastNode) => {
     const text = mdastToString(node);
     const id = text
       .toLowerCase()
@@ -89,7 +95,7 @@ function extractToc(tree) {
       .replace(/\s+/g, "-")
       .replace(/-+/g, "-")
       .replace(/^-|-$/g, "");
-    entries.push({ depth: /** @type {number} */ (node.depth), text, id });
+    entries.push({ depth: node.depth as number, text, id });
   });
   return entries;
 }
@@ -100,10 +106,9 @@ function extractToc(tree) {
  * @param {object} tree - Mdast AST
  * @returns {string} Plain text of first paragraph, or empty string
  */
-function extractExcerpt(tree) {
-  /** @type {MdastNode | null} */
-  let firstParagraph = null;
-  visit(tree, "paragraph", (/** @type {MdastNode} */ node) => {
+function extractExcerpt(tree: MdastNode) {
+  let firstParagraph: MdastNode | null = null;
+  visit(tree, "paragraph", (node: MdastNode) => {
     if (!firstParagraph) firstParagraph = node;
   });
   if (!firstParagraph) return "";
@@ -122,7 +127,14 @@ function extractExcerpt(tree) {
  * @param {unknown} [config.directiveOptions] - Directive plugin options
  * @returns {MarkdownFileResult}
  */
-function processMarkdown(source, filePath, config = {}) {
+function processMarkdown(
+  source: string,
+  filePath: string,
+  config: {
+    directives?: boolean;
+    directiveOptions?: unknown;
+  } = {},
+) {
   let processor = unified()
     .use(remarkParse)
     .use(remarkFrontmatter, ["yaml"])
@@ -138,22 +150,20 @@ function processMarkdown(source, filePath, config = {}) {
   // @ts-ignore - vfile shape satisfies unified's internal contract
   processor.runSync(tree, vfile);
 
-  const vfileData = /** @type {Record<string, unknown>} */ (vfile.data);
-  const frontmatter = /** @type {Record<string, unknown>} */ (vfileData.frontmatter ?? {});
-  const mdTree = /** @type {MdastNode} */ (/** @type {unknown} */ (tree));
+  const vfileData = vfile.data as Record<string, unknown>;
+  const frontmatter = (vfileData.frontmatter ?? {}) as Record<string, unknown>;
+  const mdTree = tree as unknown as MdastNode;
   const plainText = mdastToString(mdTree);
   const toc = extractToc(tree);
   const excerpt = extractExcerpt(tree);
   const slug = basename(filePath, extname(filePath));
 
-  const bodyNodes = /** @type {MdastNode[]} */ (
-    tree.children.filter(
-      (/** @type {{ type: string }} */ n) => n.type !== "yaml" && n.type !== "toml",
-    )
-  );
-  const $children = /** @type {(JxElement | string)[]} */ (
-    bodyNodes.map(/** @type {(n: MdastNode) => any} */ (mdastNodeToJx)).filter(Boolean)
-  );
+  const bodyNodes = tree.children.filter(
+    (n: MdastNode) => n.type !== "yaml" && n.type !== "toml",
+  ) as MdastNode[];
+  const $children = bodyNodes
+    .map(/** @type {(n: MdastNode) => any} */ (mdastNodeToJx))
+    .filter(Boolean) as (JxElement | string)[];
 
   return {
     slug,
@@ -174,11 +184,11 @@ function processMarkdown(source, filePath, config = {}) {
  * @param {string} path
  * @returns {unknown}
  */
-function getNestedValue(obj, path) {
+function getNestedValue(obj: Record<string, unknown> | MarkdownFileResult, path: string) {
   return path
     .split(".")
     .reduce(
-      (/** @type {unknown} */ o, k) => /** @type {Record<string, unknown> | undefined} */ (o)?.[k],
+      (o: unknown, k) => (o as Record<string, unknown> | undefined)?.[k],
       /** @type {unknown} */ (obj),
     );
 }
@@ -192,6 +202,13 @@ function getNestedValue(obj, path) {
  *   { "$prototype": "MarkdownFile", "$src": "@jxsuite/md", "src": "./content/about.md" }
  */
 export class MarkdownFile {
+  config: {
+    src: string;
+    remarkPlugins?: unknown[];
+    rehypePlugins?: unknown[];
+    basePath?: string;
+    directives?: boolean;
+  };
   /**
    * @param {object} config
    * @param {string} config.src - File path to markdown file
@@ -200,7 +217,13 @@ export class MarkdownFile {
    * @param {string} [config.basePath] - Base path for resolving src
    * @param {boolean} [config.directives] - Enable directive support
    */
-  constructor(config) {
+  constructor(config: {
+    src: string;
+    remarkPlugins?: unknown[];
+    rehypePlugins?: unknown[];
+    basePath?: string;
+    directives?: boolean;
+  }) {
     this.config = config;
   }
 
@@ -227,19 +250,40 @@ export class MarkdownFile {
  *   { "$prototype": "MarkdownCollection", "$src": "@jxsuite/md", "src": "./posts/*.md" }
  */
 export class MarkdownCollection {
+  config: {
+    src: string;
+    sortBy?: string;
+    sortOrder?: string;
+    limit?: number;
+    filter?: (result: MarkdownFileResult) => boolean;
+    remarkPlugins?: unknown[];
+    rehypePlugins?: unknown[];
+    basePath?: string;
+    directives?: boolean;
+  };
   /**
    * @param {object} config
    * @param {string} config.src - Glob pattern or directory path
    * @param {string} [config.sortBy] Default is `'frontmatter.date'`
    * @param {string} [config.sortOrder] Default is `'desc'`
    * @param {number} [config.limit]
-   * @param {Function} [config.filter] - Filter function
+   * @param {(result: MarkdownFileResult) => boolean} [config.filter] - Filter function
    * @param {unknown[]} [config.remarkPlugins] Default is `[]`
    * @param {unknown[]} [config.rehypePlugins] Default is `[]`
    * @param {string} [config.basePath] - Base path for resolving glob
    * @param {boolean} [config.directives] - Enable directive support
    */
-  constructor(config) {
+  constructor(config: {
+    src: string;
+    sortBy?: string;
+    sortOrder?: string;
+    limit?: number;
+    filter?: (result: MarkdownFileResult) => boolean;
+    remarkPlugins?: unknown[];
+    rehypePlugins?: unknown[];
+    basePath?: string;
+    directives?: boolean;
+  }) {
     this.config = config;
   }
 
@@ -264,7 +308,7 @@ export class MarkdownCollection {
     const pattern = resolved.split("\\").join("/");
     const files = globSync(pattern, { absolute: true });
 
-    const results = files.map((/** @type {string} */ filePath) => {
+    const results = files.map((filePath: string) => {
       const source = readFileSync(filePath, "utf-8");
       return processMarkdown(source, filePath, processorConfig);
     });
@@ -276,9 +320,9 @@ export class MarkdownCollection {
     }
 
     // Sort
-    filtered.sort((/** @type {MarkdownFileResult} */ a, /** @type {MarkdownFileResult} */ b) => {
-      const aVal = /** @type {string | number} */ (getNestedValue(a, sortBy) ?? "");
-      const bVal = /** @type {string | number} */ (getNestedValue(b, sortBy) ?? "");
+    filtered.sort((a: MarkdownFileResult, b: MarkdownFileResult) => {
+      const aVal = getNestedValue(a, sortBy) ?? ("" as string | number);
+      const bVal = getNestedValue(b, sortBy) ?? ("" as string | number);
       if (aVal < bVal) return sortOrder === "asc" ? -1 : 1;
       if (aVal > bVal) return sortOrder === "asc" ? 1 : -1;
       return 0;
@@ -307,4 +351,4 @@ export {
   convertChildren,
   jxKey,
   mdKey,
-} from "./transpile.js";
+} from "./transpile.ts";

package/src/{transpile.js → transpile.ts}

@@ -17,7 +17,9 @@ import remarkFrontmatter from "remark-frontmatter";
 import remarkParseFrontmatter from "remark-parse-frontmatter";
 import remarkGfm from "remark-gfm";
 import remarkDirective from "remark-directive";
-import { htmlToJx } from "./html-to-jx.js";
+import { htmlToJx } from "./html-to-jx.ts";
+import type { MdastNode } from "./types.ts";
+import type { JxDocument, JxElement } from "@jxsuite/schema/types";
 export { htmlToJx };
 
 // ─── Dot-path expansion ─────────────────────────────────────────────────────
@@ -40,7 +42,7 @@ const JX_ANNOTATION_KEYS = new Set(["title", "description"]);
  * @param {string} key
  * @returns {string}
  */
-export function jxKey(key) {
+export function jxKey(key: string) {
   if (JX_DOLLAR_KEYS.has(key)) return `$${key}`;
   if (key.startsWith("--") && JX_ANNOTATION_KEYS.has(key.slice(2))) return `$${key.slice(2)}`;
   return key;
@@ -52,7 +54,7 @@ export function jxKey(key) {
  * @param {string} key
  * @returns {string}
  */
-export function mdKey(key) {
+export function mdKey(key: string) {
   if (key.startsWith("$") && JX_DOLLAR_KEYS.has(key.slice(1))) {
     return key.slice(1);
   }
@@ -68,9 +70,8 @@ export function mdKey(key) {
  * @param {Record<string, string>} attrs - Flat attribute map from remark-directive
  * @returns {Record<string, unknown>} Nested object
  */
-export function expandDotPaths(attrs) {
-  /** @type {Record<string, unknown>} */
-  const result = {};
+export function expandDotPaths(attrs: Record<string, string>) {
+  const result: Record<string, unknown> = {};
 
   for (const [key, value] of Object.entries(attrs)) {
     const dotIndex = key.indexOf(".");
@@ -86,7 +87,7 @@ export function expandDotPaths(attrs) {
       if (!(seg in target) || typeof target[seg] !== "object") {
         target[seg] = {};
       }
-      target = /** @type {Record<string, unknown>} */ (target[seg]);
+      target = target[seg] as Record<string, unknown>;
     }
     target[jxKey(segments[segments.length - 1])] = value;
   }
@@ -100,15 +101,14 @@ export function expandDotPaths(attrs) {
  * @param {Record<string, unknown>} obj - Nested object
  * @returns {Record<string, string>} Flat attribute map
  */
-export function collapseDotPaths(obj) {
-  /** @type {Record<string, string>} */
-  const result = {};
+export function collapseDotPaths(obj: Record<string, unknown>) {
+  const result: Record<string, string> = {};
 
-  function walk(/** @type {Record<string, unknown>} */ node, /** @type {string} */ prefix) {
+  function walk(node: Record<string, unknown>, prefix: string) {
     for (const [key, value] of Object.entries(node)) {
       const path = prefix ? `${prefix}.${key}` : key;
       if (value && typeof value === "object" && !Array.isArray(value)) {
-        walk(/** @type {Record<string, unknown>} */ (value), path);
+        walk(value as Record<string, unknown>, path);
       } else {
         result[path] = String(value);
       }
@@ -151,9 +151,8 @@ const CSS_PSEUDO_NAMES = new Set([
  * @param {Record<string, unknown>} styleObj
  * @returns {Record<string, unknown>}
  */
-export function applyStyleKeyMapping(styleObj) {
-  /** @type {Record<string, unknown>} */
-  const result = {};
+export function applyStyleKeyMapping(styleObj: Record<string, unknown>) {
+  const result: Record<string, unknown> = {};
   for (const [key, value] of Object.entries(styleObj)) {
     if (CSS_PSEUDO_NAMES.has(key)) {
       result[`:${key}`] = value;
@@ -175,7 +174,7 @@ export function applyStyleKeyMapping(styleObj) {
  * @param {Record<string, string>} attrs
  * @returns {Record<string, unknown>}
  */
-export function expandStylePaths(attrs) {
+export function expandStylePaths(attrs: Record<string, string>) {
   return applyStyleKeyMapping(expandDotPaths(attrs));
 }
 
@@ -188,9 +187,8 @@ export function expandStylePaths(attrs) {
  * @param {Record<string, unknown>} styleObj
  * @returns {Record<string, string>}
  */
-export function collapseStylePaths(styleObj) {
-  /** @type {Record<string, unknown>} */
-  const normalized = {};
+export function collapseStylePaths(styleObj: Record<string, unknown>) {
+  const normalized: Record<string, unknown> = {};
 
   for (const [key, value] of Object.entries(styleObj)) {
     if (key.startsWith(":") && CSS_PSEUDO_NAMES.has(key.slice(1))) {
@@ -214,7 +212,7 @@ export function collapseStylePaths(styleObj) {
  * @param {string} source - Raw markdown string
  * @returns {boolean}
  */
-export function isJxMarkdown(source) {
+export function isJxMarkdown(source: string) {
   const fmMatch = source.match(/^---\r?\n([\s\S]*?)\r?\n---/);
   if (!fmMatch) return false;
   return /^tagName:\s*.+-.+/m.test(fmMatch[1]);
@@ -273,22 +271,20 @@ const PHRASING_ELEMENTS = new Set([
  * @param {Record<string, string>} attrs
  * @returns {{ props: Record<string, unknown>; attributes: Record<string, string> }}
  */
-function routeAttributes(attrs) {
+function routeAttributes(attrs: Record<string, string>) {
   const expanded = expandDotPaths(attrs);
 
   // Apply style-key mapping (pseudo-classes, media queries) to the style sub-object
   if (expanded.style && typeof expanded.style === "object") {
-    expanded.style = applyStyleKeyMapping(/** @type {Record<string, unknown>} */ (expanded.style));
+    expanded.style = applyStyleKeyMapping(expanded.style as Record<string, unknown>);
   }
 
-  /** @type {Record<string, unknown>} */
-  const props = {};
-  /** @type {Record<string, string>} */
-  const attributes = {};
+  const props: Record<string, unknown> = {};
+  const attributes: Record<string, string> = {};
 
   for (const [key, value] of Object.entries(expanded)) {
     if (HTML_ATTR_PATTERN.test(key)) {
-      attributes[key] = /** @type {string} */ (value);
+      attributes[key] = value as string;
     } else {
       props[key] = value;
     }
@@ -302,8 +298,8 @@ function routeAttributes(attrs) {
  *
  * @type {Record<string, (n: MdastNode) => string>}
  */
-const JX_TAG_MAP = {
-  heading: (/** @type {MdastNode} */ n) => `h${n.depth}`,
+const JX_TAG_MAP: Record<string, (n: MdastNode) => string> = {
+  heading: (n: MdastNode) => `h${n.depth}`,
   paragraph: () => "p",
   emphasis: () => "em",
   strong: () => "strong",
@@ -312,14 +308,14 @@ const JX_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",
   break: () => "br",
   table: () => "table",
   tableRow: () => "tr",
-  tableCell: (/** @type {MdastNode} */ n) => (n.isHeader ? "th" : "td"),
+  tableCell: (n: MdastNode) => (n.isHeader ? "th" : "td"),
 };
 
 /**
@@ -328,7 +324,7 @@ const JX_TAG_MAP = {
  * @param {MdastNode} node
  * @returns {JxElement | string | (JxElement | string)[] | null} Jx element or null
  */
-export function mdastNodeToJx(node) {
+export function mdastNodeToJx(node: MdastNode) {
   if (!node || typeof node !== "object") return null;
 
   if (node.type === "yaml" || node.type === "toml") return null;
@@ -354,8 +350,7 @@ export function mdastNodeToJx(node) {
   if (!tagFn) return null;
 
   const tag = tagFn(node);
-  /** @type {JxElement} */
-  const el = { tagName: tag };
+  const el: JxElement = { tagName: tag };
 
   switch (node.type) {
     case "heading":
@@ -377,7 +372,7 @@ export function mdastNodeToJx(node) {
     }
 
     case "inlineCode":
-      el.textContent = node.value;
+      el.textContent = node.value ?? null;
       break;
 
     case "link":
@@ -411,7 +406,7 @@ export function mdastNodeToJx(node) {
       el.children = [
         {
           tagName: "code",
-          textContent: node.value,
+          textContent: node.value ?? null,
           ...(node.lang ? { className: `language-${node.lang}` } : {}),
         },
       ];
@@ -425,7 +420,7 @@ export function mdastNodeToJx(node) {
       const rows = convertChildren(node.children ?? []);
       const thead = rows.length > 0 ? { tagName: "thead", children: [rows[0]] } : null;
       const tbody = rows.length > 1 ? { tagName: "tbody", children: rows.slice(1) } : null;
-      el.children = /** @type {JxElement[]} */ ([thead, tbody].filter(Boolean));
+      el.children = [thead, tbody].filter(Boolean) as JxElement[];
       break;
     }
   }
@@ -439,13 +434,12 @@ export function mdastNodeToJx(node) {
  * @param {MdastNode} node
  * @returns {JxElement}
  */
-function directiveToJx(node) {
-  /** @type {JxElement} */
-  const el = { tagName: /** @type {string} */ (node.name) };
+function directiveToJx(node: MdastNode) {
+  const el: JxElement = { tagName: node.name as string };
 
   if (node.attributes && Object.keys(node.attributes).length > 0) {
     const { props, attributes } = routeAttributes(node.attributes);
-    const isCustomElement = /** @type {string} */ (node.name).includes("-");
+    const isCustomElement = (node.name as string).includes("-");
     if (isCustomElement) {
       // For custom elements:
       //   - style, children, textContent, innerHTML, $-prefixed → element-level
@@ -461,7 +455,7 @@ function directiveToJx(node) {
         ) {
           el[key] = value;
         } else if (key === "props") {
-          el.$props = /** @type {Record<string, unknown>} */ (value);
+          el.$props = value as Record<string, unknown>;
         } else {
           if (!el.attributes) el.attributes = {};
           el.attributes[key] = value;
@@ -516,9 +510,8 @@ function directiveToJx(node) {
   }
 
   if (node.children && node.children.length > 0) {
-    /** @type {(JxElement | string)[]} */
-    const jxChildren = [];
-    const isPhrasingParent = PHRASING_ELEMENTS.has(/** @type {string} */ (node.name));
+    const jxChildren: (JxElement | string)[] = [];
+    const isPhrasingParent = PHRASING_ELEMENTS.has(node.name as string);
 
     for (const child of node.children) {
       if (isPhrasingParent && child.type === "paragraph") {
@@ -557,11 +550,9 @@ function directiveToJx(node) {
  * @param {MdastNode[]} children
  * @returns {(JxElement | string)[]}
  */
-export function convertChildren(children) {
+export function convertChildren(children: MdastNode[]) {
   if (!children) return [];
-  return /** @type {(JxElement | string)[]} */ (
-    children.flatMap(mdastNodeToJx).filter((c) => c != null)
-  );
+  return children.flatMap(mdastNodeToJx).filter((c) => c != null) as (JxElement | string)[];
 }
 
 /**
@@ -573,7 +564,7 @@ export function convertChildren(children) {
  * @param {string} source - Raw markdown string
  * @returns {object} Complete Jx JSON document
  */
-export function transpileJxMarkdown(source) {
+export function transpileJxMarkdown(source: string) {
   const processor = unified()
     .use(remarkParse)
     .use(remarkFrontmatter, ["yaml"])
@@ -585,26 +576,19 @@ export function transpileJxMarkdown(source) {
   const vfile = { data: {} };
   processor.runSync(tree, vfile);
 
-  const frontmatter = /** @type {Record<string, unknown>} */ (/** @type {unknown} */ (vfile.data))
-    ?.frontmatter ?? {};
+  const frontmatter = (vfile.data as unknown as Record<string, unknown>)?.frontmatter ?? {};
 
-  /** @type {JxDocument} */
-  const doc = {};
+  const doc: JxDocument = {};
 
   for (const [key, value] of Object.entries(frontmatter)) {
     doc[key] = value;
   }
 
-  const bodyNodes = /** @type {MdastNode[]} */ (
-    /** @type {unknown} */ (
-      tree.children.filter(
-        (/** @type {{ type: string }} */ n) => n.type !== "yaml" && n.type !== "toml",
-      )
-    )
-  );
+  const bodyNodes = tree.children.filter(
+    (n: MdastNode) => n.type !== "yaml" && n.type !== "toml",
+  ) as unknown as MdastNode[];
 
-  /** @type {(JxElement | string)[]} */
-  const children = [];
+  const children: (JxElement | string)[] = [];
 
   for (const node of bodyNodes) {
     const converted = mdastNodeToJx(node);

package/src/types.ts

@@ -0,0 +1,65 @@
+import type { JxElement } from "@jxsuite/schema/types";
+
+export interface MarkdownFileResult {
+  slug: string;
+  path: string;
+  frontmatter: Record<string, unknown>;
+  $children: (JxElement | string)[];
+  $excerpt?: string;
+  $toc?: TocEntry[];
+  $readingTime?: number;
+  $wordCount?: number;
+  [key: string]: unknown;
+}
+
+export interface TocEntry {
+  depth: number;
+  text: string;
+  id: string;
+}
+
+export interface ContentEntry extends MarkdownFileResult {
+  [key: string]: unknown;
+}
+
+export interface ContentLoaderEntry {
+  id: string;
+  data: Record<string, unknown>;
+  body: string | null;
+  $children?: (JxElement | string)[];
+  _meta?: {
+    excerpt?: string;
+    toc?: TocEntry[];
+    readingTime?: number;
+    wordCount?: number;
+  };
+}
+
+export interface MdastNode {
+  type: string;
+  children?: MdastNode[];
+  value?: string;
+  data?: unknown;
+  position?: unknown;
+  depth?: number;
+  ordered?: boolean | null;
+  start?: number | null;
+  spread?: boolean;
+  isHeader?: boolean;
+  name?: string;
+  attributes?: Record<string, string>;
+  url?: string;
+  alt?: string;
+  title?: string | null;
+  lang?: string | null;
+  meta?: string | null;
+  align?: (string | null)[] | null;
+}
+
+export interface HastNode {
+  type: string;
+  tagName?: string;
+  properties?: Record<string, unknown>;
+  children?: HastNode[];
+  value?: string;
+}