@astryxdesign/cli 0.1.8-canary.3bb5896 → 0.1.8-canary.3cbbe66

package/{src/api → api/blog}/blog.mjs

@@ -10,9 +10,9 @@
  * blog's structure can change freely without touching the CLI.
  */
 
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {SITE_URL, SITE_ORIGIN} from '../lib/site.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {SITE_URL, SITE_ORIGIN} from '../../lib/site.mjs';
 
 /** Abort a feed/post fetch that hangs, and cap how much we'll read. */
 const FETCH_TIMEOUT_MS = 15000;
@@ -20,6 +20,10 @@ const MAX_BYTES = 5 * 1024 * 1024; // 5 MB — a blog feed is never larger.
 
 const FEED_URL = new URL('/rss.xml', SITE_URL).toString();
 
+/**
+ * @param {string} url
+ * @returns {Promise<string>}
+ */
 async function fetchText(url) {
   const controller = new AbortController();
   const timer = setTimeout(() => controller.abort(), FETCH_TIMEOUT_MS);
@@ -31,7 +35,12 @@ async function fetchText(url) {
     });
   } catch (e) {
     clearTimeout(timer);
-    const reason = e.name === 'AbortError' ? 'timed out' : e.message;
+    const reason =
+      e instanceof Error
+        ? e.name === 'AbortError'
+          ? 'timed out'
+          : e.message
+        : String(e);
     throw new AstryxError(
       `Could not reach ${url}: ${reason}`,
       [],
@@ -61,6 +70,7 @@ async function fetchText(url) {
  * Defense in depth: a post's plaintext URL comes from feed content. Require it
  * to live on the canonical origin so even a tampered feed can't redirect the
  * CLI to another host.
+ * @param {string} target
  */
 function assertCanonicalOrigin(target) {
   let targetOrigin;
@@ -82,6 +92,10 @@ function assertCanonicalOrigin(target) {
   }
 }
 
+/**
+ * @param {string} value
+ * @returns {string}
+ */
 function unescapeXml(value) {
   return value
     .replace(/&lt;/g, '<')
@@ -91,12 +105,23 @@ function unescapeXml(value) {
     .replace(/&amp;/g, '&');
 }
 
+/**
+ * @param {string} item
+ * @param {string} name
+ * @returns {string}
+ */
 function tag(item, name) {
   const m = item.match(new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`));
   return m ? unescapeXml(m[1].trim()) : '';
 }
 
+/**
+ * @param {string} item
+ * @param {string} name
+ * @returns {string[]}
+ */
 function tagAll(item, name) {
+  /** @type {string[]} */
   const out = [];
   const re = new RegExp(`<${name}[^>]*>([\\s\\S]*?)</${name}>`, 'g');
   let m;
@@ -104,7 +129,11 @@ function tagAll(item, name) {
   return out;
 }
 
-/** Extract the plaintext alternate href from an <item>. */
+/**
+ * Extract the plaintext alternate href from an <item>.
+ * @param {string} item
+ * @returns {string | null}
+ */
 function textHref(item) {
   // Match the atom:link alternate regardless of attribute order/quoting; then
   // confirm it's the text/plain alternate before trusting the href.
@@ -121,7 +150,11 @@ function textHref(item) {
   return null;
 }
 
-/** Derive a slug from a post link (last path segment). */
+/**
+ * Derive a slug from a post link (last path segment).
+ * @param {string} link
+ * @returns {string}
+ */
 function slugFromLink(link) {
   try {
     const path = new URL(link).pathname.replace(/\/$/, '');
@@ -131,6 +164,9 @@ function slugFromLink(link) {
   }
 }
 
+/**
+ * @param {string} xml
+ */
 function parseFeed(xml) {
   const items = [];
   const re = /<item>([\s\S]*?)<\/item>/g;

package/{src/api → api/blog}/blog.test.mjs

@@ -9,8 +9,8 @@
 
 import {describe, it, expect, beforeEach, afterEach, vi} from 'vitest';
 import {blog} from './blog.mjs';
-import {AstryxError} from './error.mjs';
-import {SITE_URL} from '../lib/site.mjs';
+import {AstryxError} from '../error.mjs';
+import {SITE_URL} from '../../lib/site.mjs';
 
 const FEED = `<?xml version="1.0" encoding="UTF-8"?>
 <rss version="2.0" xmlns:atom="http://www.w3.org/2005/Atom">

package/{src/api → api/component}/component.mjs

@@ -9,8 +9,8 @@
 
 import * as fs from 'node:fs';
 import * as path from 'node:path';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
-import {findCoreDir, discoverExternalPackages} from '../utils/paths.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
+import {findCoreDir, discoverExternalPackages} from '../../utils/paths.mjs';
 import {
   CORE_PACKAGE,
   discoverComponents,
@@ -22,24 +22,46 @@ import {
   findIntegrationComponentDoc,
   findIntegrationComponentSource,
   resolveImportPath,
-} from '../lib/component-discovery.mjs';
-import {Project} from '../lib/project.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {searchComponents} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {findShowcase, findRelatedBlocks} from './template.mjs';
+} from '../../lib/component-discovery.mjs';
+import {Project} from '../../lib/project.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {searchComponents} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {findShowcase, findRelatedBlocks} from '../template/template.mjs';
+
+/**
+ * A loaded component doc. `loadDocs` returns the authored `.doc.mjs` shape,
+ * which is either a single-component or multi-component doc; this loose view
+ * captures the fields the API reads across both forms.
+ * @typedef {object} LoadedComponentDoc
+ * @property {string} [name]
+ * @property {string} [description]
+ * @property {any[]} [props]
+ * @property {any[]} [components]
+ * @property {{description?: string}} [usage]
+ * @property {any} [theming]
+ */
+
+/**
+ * Options object for `loadDocs`, matching its declared parameter shape (used
+ * as a cast target so `lang` (which the API may hold as `string|null`) type
+ * checks against `loadDocs`'s `lang?: string`).
+ * @typedef {{zh?: boolean, dense?: boolean, lang?: string}} LoadDocsOpts
+ */
 
 /**
  * Load the configured integrations for `cwd`, swallowing any config errors so
  * component discovery never hard-fails on a malformed/absent integration. An
  * empty list means "core only".
  * @param {string} cwd
- * @returns {Promise<Array<{name: string, components?: string, issuesUrl?: string}>>}
+ * @returns {Promise<import('../../lib/integrations.mjs').LoadedIntegration[]>}
  */
 async function loadIntegrationsSafely(cwd) {
   try {
     const project = await Project.load(cwd);
-    return project.loadedIntegrations;
+    return /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
+      project.loadedIntegrations
+    );
   } catch {
     return [];
   }
@@ -47,7 +69,7 @@ async function loadIntegrationsSafely(cwd) {
 
 /**
  * Resolve a loaded integration by package name.
- * @param {Array<{name: string}>} loadedIntegrations
+ * @param {import('../../lib/integrations.mjs').LoadedIntegration[]} loadedIntegrations
  * @param {string} packageName
  */
 function findLoadedIntegration(loadedIntegrations, packageName) {
@@ -133,7 +155,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              const docs = await loadDocs(readme, {zh, lang});
+              const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang})));
               entries.push({name: comp, description: docs.usage?.description || docs.description || '', import: resolveImportPath(coreDir, comp)});
             } catch {
               entries.push({name: comp, description: '', import: resolveImportPath(coreDir, comp)});
@@ -151,7 +173,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              entries.push(await loadDocs(readme, {zh, lang, dense}));
+              entries.push(await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang, dense})));
             } catch {
               entries.push({name: `XDS${comp}`, description: ''});
             }
@@ -173,7 +195,7 @@ export async function component(name, options = {}) {
 
     // All components — merge core + external packages with grouped subcategories
     if (detail === 'compact') {
-      /** @type {Record<string, Array<import('../types/component').ComponentBriefEntry>>} */
+      /** @type {Record<string, Array<import('../../types/component').ComponentBriefEntry>>} */
       const result = {};
       for (const [cat, comps] of Object.entries(components)) {
         result[cat] = [];
@@ -181,7 +203,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              const docs = await loadDocs(readme, {zh, lang});
+              const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang})));
               result[cat].push({name: comp, description: docs.usage?.description || docs.description || '', import: resolveImportPath(coreDir, comp)});
             } catch {
               result[cat].push({name: comp, description: '', import: resolveImportPath(coreDir, comp)});
@@ -203,7 +225,7 @@ export async function component(name, options = {}) {
           const readme = findComponentReadme(coreDir, comp);
           if (readme && readme.endsWith('.doc.mjs')) {
             try {
-              result[cat].push(await loadDocs(readme, {zh, lang, dense}));
+              result[cat].push(await loadDocs(readme, /** @type {LoadDocsOpts} */ ({zh, lang, dense})));
             } catch {
               result[cat].push({name: `XDS${comp}`, description: ''});
             }
@@ -238,7 +260,7 @@ export async function component(name, options = {}) {
         const groupLabel = rec.group ?? integration.name;
         const key = `${groupLabel} (${integration.name})`;
         if (!byGroup.has(key)) byGroup.set(key, []);
-        byGroup.get(key).push({name: rec.name, package: integration.name});
+        byGroup.get(key)?.push({name: rec.name, package: integration.name});
       }
       for (const [key, members] of byGroup) {
         members.sort((a, b) => a.name.localeCompare(b.name));
@@ -334,14 +356,14 @@ export async function component(name, options = {}) {
    * `package`, the resolved `import` specifier, and `sourceAvailable` (whether
    * a swizzleable source file exists for the owner). Existing doc fields
    * (name, usage, props, …) are preserved.
-   * @param {object} docs
+   * @param {LoadedComponentDoc} docs
    * @param {{package: string, sourcePath: string|null}} owner
    * @param {string} componentName
    */
   function withOwnership(docs, owner, componentName) {
     const importSpec =
       owner.package === CORE_PACKAGE
-        ? resolveImportPath(coreDir, componentName)
+        ? resolveImportPath(/** @type {string} */ (coreDir), componentName)
         : `${owner.package}/${componentName}`;
     return {
       ...docs,
@@ -368,7 +390,7 @@ export async function component(name, options = {}) {
         }
         return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
       }
-      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(owner.docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
       if (props) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
         return {type: 'component.detail.props', data: p};
@@ -389,7 +411,7 @@ export async function component(name, options = {}) {
         }
         return {type: 'component.detail.source', data: {component: dirName, source: fs.readFileSync(owner.sourcePath, 'utf-8')}};
       }
-      const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+      const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(owner.docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
       if (props) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
         return {type: 'component.detail.props', data: p};
@@ -420,7 +442,7 @@ export async function component(name, options = {}) {
 
     const extDocPath = findExternalComponentDoc(ext.docsDir, dirName);
     if (extDocPath && extDocPath.endsWith('.doc.mjs')) {
-      const docs = await loadDocs(extDocPath, {zh, dense, lang});
+      const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(extDocPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
 
       if (props) {
         const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
@@ -461,7 +483,7 @@ export async function component(name, options = {}) {
     if (showcase) {
       throw new AstryxError(`No showcase found for "${name}"`, undefined, ERROR_CODES.ERR_NO_SHOWCASE);
     }
-    const docs = await loadDocs(owner.docPath, {zh, dense, lang});
+    const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(owner.docPath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
     if (props) {
       const p = docs.props || (docs.components ? docs.components.flatMap(c => c.props || []) : []);
       return {type: 'component.detail.props', data: p};
@@ -546,12 +568,12 @@ export async function component(name, options = {}) {
     throw new AstryxError(`No .doc.mjs found for "${resolvedName}". The component needs a typed doc file.`, undefined, ERROR_CODES.ERR_NO_DOC);
   }
 
-  const docs = await loadDocs(readmePath, {zh, dense, lang});
+  const docs = /** @type {LoadedComponentDoc} */ (await loadDocs(readmePath, /** @type {LoadDocsOpts} */ ({zh, dense, lang})));
 
   // ── Blocks mode ──────────────────────────────────────────────
   if (blocks) {
     const allBlocks = await findRelatedBlocks(dirName);
-    const toEntry = (b) => ({
+    const toEntry = (/** @type {any} */ b) => ({
       name: b.dirName,
       displayName: b.name,
       description: b.description,
@@ -561,7 +583,7 @@ export async function component(name, options = {}) {
 
     // Examples: blocks in the component's own directory, or
     // componentsUsed match for sub-components without a directory.
-    const ownDir = allBlocks.filter(b => path.basename(b.category) === dirName);
+    const ownDir = allBlocks.filter((/** @type {any} */ b) => path.basename(b.category) === dirName);
     const examples = ownDir.length > 0
       ? ownDir
       : allBlocks.filter(b => b.componentsUsed?.some(c => c === dirName));
@@ -595,6 +617,7 @@ export async function component(name, options = {}) {
     : null;
 
   if (matchingComponent) {
+    /** @type {LoadedComponentDoc & {parentDoc?: string, import?: string}} */
     const scoped = {
       name: dirName,
       description: matchingComponent.description,

package/{src/api → api/discover}/discover.mjs

@@ -4,28 +4,37 @@
  * @file Programmatic API for the discover command.
  */
 
-import {Project} from '../lib/project.mjs';
+import {Project} from '../../lib/project.mjs';
 import {
   scanAllPackages,
   findComponentInPackages,
-} from '../lib/package-scanner.mjs';
-import {loadDocs} from '../lib/component-loader.mjs';
-import {levenshteinDistance} from '../lib/string-utils.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+} from '../../lib/package-scanner.mjs';
+import {loadDocs} from '../../lib/component-loader.mjs';
+import {levenshteinDistance} from '../../lib/string-utils.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
+/**
+ * @typedef {import('../../lib/package-scanner.mjs').ScannedPackage} ScannedPackage
+ */
+
+/**
+ * @param {unknown} docs
+ * @returns {string | null}
+ */
 function validateDocs(docs) {
   if (!docs || typeof docs !== 'object')
     return 'docs export is missing or not an object';
-  if (typeof docs.name !== 'string' || !docs.name)
+  const d = /** @type {Record<string, any>} */ (docs);
+  if (typeof d.name !== 'string' || !d.name)
     return 'docs.name is missing or not a string';
-  if (!docs.usage || typeof docs.usage.description !== 'string')
+  if (!d.usage || typeof d.usage.description !== 'string')
     return 'docs.usage.description is missing or not a string';
-  if (docs.props && !Array.isArray(docs.props))
+  if (d.props && !Array.isArray(d.props))
     return 'docs.props must be an array';
-  if (docs.components && !Array.isArray(docs.components))
+  if (d.components && !Array.isArray(d.components))
     return 'docs.components must be an array';
-  if (docs.usage?.bestPractices && !Array.isArray(docs.usage.bestPractices))
+  if (d.usage?.bestPractices && !Array.isArray(d.usage.bestPractices))
     return 'docs.usage.bestPractices must be an array';
   return null;
 }
@@ -36,11 +45,21 @@ function validateDocs(docs) {
  * @param {boolean} [options.components]
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
- * @returns {Promise<{type: string, data: unknown}>}
+ * @returns {Promise<
+ *   import('../../types/discover').DiscoverListResponse |
+ *   import('../../types/discover').DiscoverDetailResponse |
+ *   import('../../types/discover').DiscoverDetailDocResponse |
+ *   import('../../types/discover').DiscoverSearchResponse
+ * >}
  */
 export async function discover(query, options = {}) {
   const {lang = null, zh = false} = options;
   const project = await Project.load();
+  const loadedIntegrations =
+    /** @type {import('../../lib/integrations.mjs').LoadedIntegration[]} */ (
+      project.loadedIntegrations
+    );
+  /** @param {ScannedPackage} pkg */
   const toEntry = pkg => ({
     name: pkg.name,
     category: pkg.category,
@@ -52,7 +71,7 @@ export async function discover(query, options = {}) {
 
   // External packages come from configured integrations that declare a
   // components root. Each becomes a scannable package keyed by its docsDir.
-  const explicitPackages = project.loadedIntegrations
+  const explicitPackages = loadedIntegrations
     .filter(integration => integration.components)
     .map(integration => ({
       name: integration.name,
@@ -64,7 +83,10 @@ export async function discover(query, options = {}) {
     return {type: 'discover.list', data: [], meta: {configured: false}};
   }
 
-  const packages = scanAllPackages([], explicitPackages);
+  const packages = scanAllPackages(
+    [],
+    /** @type {ScannedPackage[]} */ (/** @type {unknown} */ (explicitPackages)),
+  );
 
   if (packages.length === 0) {
     return {type: 'discover.list', data: [], meta: {configured: true}};
@@ -105,7 +127,7 @@ export async function discover(query, options = {}) {
     return await loadAndValidate(exact, {lang, zh});
   }
 
-  const substringMatches = [];
+  const substringMatches = /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
   for (const pkg of packages) {
     for (const comp of pkg.components) {
       if (comp.toLowerCase().includes(lower)) {
@@ -134,7 +156,7 @@ export async function discover(query, options = {}) {
   }
 
   // Fuzzy fallback
-  const allComponents = [];
+  const allComponents = /** @type {Array<{pkg: ScannedPackage, comp: string}>} */ ([]);
   for (const pkg of packages) {
     for (const comp of pkg.components) {
       allComponents.push({pkg, comp});
@@ -167,6 +189,13 @@ export async function discover(query, options = {}) {
   );
 }
 
+/**
+ * @param {ScannedPackage[]} packages
+ * @param {string} compName
+ * @param {string} pkgName
+ * @param {{lang?: string|null, zh?: boolean}} opts
+ * @returns {Promise<import('../../types/discover').DiscoverDetailDocResponse>}
+ */
 async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
   const pkg = packages.find(p => p.name === pkgName);
   if (!pkg)
@@ -202,13 +231,21 @@ async function resolveComponentDocs(packages, compName, pkgName, {lang, zh}) {
   return await loadAndValidate(result, {lang, zh});
 }
 
+/**
+ * @param {{docPath: string, componentName: string, pkg: ScannedPackage}} result
+ * @param {{lang?: string|null, zh?: boolean}} opts
+ * @returns {Promise<import('../../types/discover').DiscoverDetailDocResponse>}
+ */
 async function loadAndValidate(result, {lang, zh}) {
   let docs;
   try {
-    docs = await loadDocs(result.docPath, {zh, lang});
+    docs = await loadDocs(
+      result.docPath,
+      /** @type {{zh?: boolean, dense?: boolean, lang?: string}} */ ({zh, lang}),
+    );
   } catch (e) {
     throw new AstryxError(
-      `Failed to load docs for ${result.componentName}: ${e.message}`,
+      `Failed to load docs for ${result.componentName}: ${/** @type {any} */ (e).message}`,
       undefined,
       ERROR_CODES.ERR_INVALID_DOC,
     );

package/{src/api → api/docs}/docs.mjs

@@ -7,13 +7,17 @@
 import * as fs from 'node:fs';
 import * as path from 'node:path';
 import {pathToFileURL} from 'node:url';
-import {CLI_ROOT} from '../utils/paths.mjs';
-import {AstryxError} from './error.mjs';
-import {ERROR_CODES} from '../lib/error-codes.mjs';
+import {CLI_ROOT} from '../../utils/paths.mjs';
+import {AstryxError} from '../error.mjs';
+import {ERROR_CODES} from '../../lib/error-codes.mjs';
 
 const DOCS_DIR = path.join(CLI_ROOT, 'docs');
 
+/**
+ * @returns {Record<string, string>}
+ */
 function discoverTopics() {
+  /** @type {Record<string, string>} */
   const topics = {};
   if (!fs.existsSync(DOCS_DIR)) return topics;
   for (const file of fs.readdirSync(DOCS_DIR)) {
@@ -23,6 +27,11 @@ function discoverTopics() {
   return topics;
 }
 
+/**
+ * @param {string} docPath
+ * @param {{lang?: string|null}} [opts]
+ * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
+ */
 async function loadReferenceDocs(docPath, {lang} = {}) {
   const mod = await import(pathToFileURL(docPath).href);
   const docs = mod.docs;
@@ -45,6 +54,7 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
   // printed the colour table under a "Spacing" heading (#2182). An overlay may
   // now cover any subset of sections, in any order; sections it does not name
   // keep their base content.
+  /** @type {Map<string, any>} */
   const bySection = new Map();
   for (const ts of translation.sections ?? []) {
     if (ts?.section != null) bySection.set(ts.section, ts);
@@ -53,32 +63,43 @@ async function loadReferenceDocs(docPath, {lang} = {}) {
   return {
     ...docs,
     description: translation.description || docs.description,
-    sections: docs.sections.map(section => {
-      const ts = bySection.get(section.title);
-      if (!ts) return section;
-      return {
-        ...section,
-        title: ts.title || section.title,
-        content: section.content.map((block, bi) => {
-          const tb = ts.content?.[bi];
-          if (!tb) return block;
-          if (tb.type === 'prose' && block.type === 'prose') return {...block, text: tb.text};
-          if (tb.type === 'list' && block.type === 'list') return {...block, items: tb.items};
-          return block;
-        }),
-      };
-    }),
+    sections: docs.sections.map(
+      (/** @type {import('../../../core/src/docs-types').ReferenceSection} */ section) => {
+        const ts = bySection.get(section.title);
+        if (!ts) return section;
+        return {
+          ...section,
+          title: ts.title || section.title,
+          content: section.content.map(
+            (
+              /** @type {import('../../../core/src/docs-types').ContentBlock} */ block,
+              /** @type {number} */ bi,
+            ) => {
+              const tb = ts.content?.[bi];
+              if (!tb) return block;
+              if (tb.type === 'prose' && block.type === 'prose') return {...block, text: tb.text};
+              if (tb.type === 'list' && block.type === 'list') return {...block, items: tb.items};
+              return block;
+            },
+          ),
+        };
+      },
+    ),
   };
 }
 
 /**
  * Resolve token-ref blocks by inlining the referenced section's table.
  * This allows section docs to reference token tables without duplicating data.
+ * @param {import('../../types/docs').DocsDetailResponse['data']} docsData
+ * @param {Record<string, string>} topics
+ * @returns {Promise<import('../../types/docs').DocsDetailResponse['data']>}
  */
 async function resolveTokenRefs(docsData, topics) {
   const resolved = {...docsData, sections: [...docsData.sections]};
   for (let si = 0; si < resolved.sections.length; si++) {
     const section = resolved.sections[si];
+    /** @type {import('../../../core/src/docs-types').ContentBlock[]} */
     const newContent = [];
     for (const block of section.content) {
       if (block.type === 'token-ref') {
@@ -90,7 +111,8 @@ async function resolveTokenRefs(docsData, topics) {
         const refMod = await import(pathToFileURL(refPath).href);
         const refDocs = refMod.docs;
         const refSection = refDocs.sections.find(
-          s => s.title.toLowerCase() === block.section.toLowerCase(),
+          (/** @type {import('../../../core/src/docs-types').ReferenceSection} */ s) =>
+            s.title.toLowerCase() === block.section.toLowerCase(),
         );
         if (!refSection) {
           newContent.push({type: 'prose', text: `[token-ref: section "${block.section}" not found in "${block.topic}"]`});
@@ -125,7 +147,11 @@ async function resolveTokenRefs(docsData, topics) {
  * @param {string} [options.lang]
  * @param {boolean} [options.zh]
  * @param {boolean} [options.dense]
- * @returns {Promise<{type: string, data: unknown}>}
+ * @returns {Promise<
+ *   import('../../types/docs').DocsListResponse |
+ *   import('../../types/docs').DocsDetailResponse |
+ *   import('../../types/docs').DocsDetailSectionResponse
+ * >}
  */
 export async function docs(topic, section, options = {}) {
   const {lang = null, zh = false, dense = false} = options;
@@ -133,7 +159,7 @@ export async function docs(topic, section, options = {}) {
   const topics = discoverTopics();
 
   if (!topic) {
-    /** @type {Array<import('../types/docs').DocsListEntry>} */
+    /** @type {Array<import('../../types/docs').DocsListEntry>} */
     const entries = [];
     for (const [name, docPath] of Object.entries(topics)) {
       try {