@astryxdesign/cli 0.1.8-canary.4a7ce02 → 0.1.8-canary.4cc4d7a

package/bin/astryx.mjs

@@ -26,6 +26,7 @@ import {realpathSync} from 'node:fs';
 import {dirname, join} from 'node:path';
 
 const binDir = dirname(realpathSync(fileURLToPath(import.meta.url)));
+/** @param {string} rel */
 const importSrc = rel =>
   import(pathToFileURL(join(binDir, '..', 'src', rel)).href);
 
@@ -72,6 +73,7 @@ function inJsonMode() {
   return isJsonMode() || process.argv.slice(2).includes('--json');
 }
 
+/** @param {unknown} err */
 function handleFatal(err) {
   // CommanderError (parse errors, --help, unknown command) routes
   // through the JSON shim so that a --json consumer always gets a

package/docs/elevation.doc.mjs

@@ -36,10 +36,85 @@ export const docs = {
         },
       ],
     },
+    {
+      title: 'Choosing a level',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Pick the level by how far the surface sits from the page, not by how much shadow you want. Elevation encodes stacking order: a higher level means the surface is layered over more of the UI. Use exactly one level per surface, and only raise a surface above `none` when it actually sits above other content.',
+        },
+        {
+          type: 'table',
+          headers: ['Level', 'When to use', 'Examples'],
+          rows: [
+            [
+              'none',
+              'The component is flat and embedded in the surface — it is part of the page, not layered above it. This is the default for every surface except ChatComposer.',
+              'A Card in a grid, an inline Banner, a standard Button',
+            ],
+            [
+              'low',
+              'The component is in the normal page flow but should read as distinct from the background. Use for emphasis or to separate the component from the surface behind it — the component still sits on the page, it is not floating over other content.',
+              'A raised Card that needs emphasis, a ChatComposer, a resting Thumbnail',
+            ],
+            [
+              'med',
+              'The component sits over other content on the same page — it floats above nearby elements but not the whole screen.',
+              'A Popover, a floating Banner, a floating action Button',
+            ],
+            [
+              'high',
+              'The component is placed over the entire UI — it is the topmost layer and typically has a backdrop or takes focus from everything else.',
+              'A modal Dialog, a full-screen overlay surface',
+            ],
+          ],
+        },
+        {
+          type: 'prose',
+          text: 'If two surfaces overlap, the one on top takes the higher level. If a surface does not overlap anything, it is `none` or `low` — never `med` or `high`.',
+        },
+      ],
+    },
+    {
+      title: 'The elevation prop',
+  category: 'foundations',
+      content: [
+        {
+          type: 'prose',
+          text: 'Configurable surfaces expose a single `elevation` prop instead of asking consumers to hand-write a box-shadow. It takes the graded enum `none | low | med | high`, narrowed per component to the steps that surface needs: Card, ClickableCard, SelectableCard, Button, IconButton, ButtonGroup, Thumbnail, and Banner expose the full scale, while ChatComposer exposes only `none | low`. `none` is a flat literal (`box-shadow: none`); the other levels map to the `--shadow-*` tokens above, so a surface stays theme-agnostic.',
+        },
+        {
+          type: 'prose',
+          text: 'Prop defaults preserve current appearance: every surface defaults to `none` except ChatComposer, which defaults to `low` to keep its raised look. Set `elevation="none"` to flatten it — the flat composer draws a border with the same rest / hover / focus treatment as a text input. Thumbnail keeps its existing hover-only shadow at the `none` default.',
+        },
+        {
+          type: 'code',
+          lang: 'tsx',
+          label: 'Raising a surface with the elevation prop',
+          code: `// Flat by default — raise only when the surface needs to float.
+<Card elevation="low">Raised card</Card>
+
+// A floating action button.
+<IconButton icon={<Icon icon="add" />} label="New" variant="primary" elevation="med" />
+
+// Flatten the composer (defaults to 'low').
+<ChatComposer elevation="none" onSubmit={handleSubmit} />`,
+        },
+        {
+          type: 'prose',
+          text: 'Always float — no prop: intrinsic overlays (Dialog, Popover, Tooltip, Toast, HoverCard, DropdownMenu, and the components that compose them) bake their elevation in and never expose the prop. Flow content (inputs, Text, layout) is never elevated; input fields use inset rings, which are a separate concept from elevation.',
+        },
+      ],
+    },
     {
       title: 'Usage',
   category: 'foundations',
       content: [
+        {
+          type: 'prose',
+          text: 'When building a custom surface, read elevation from the token scale rather than a hand-rolled shadow — the same tokens the elevation prop resolves to.',
+        },
         {
           type: 'code',
           lang: 'tsx',
@@ -68,7 +143,8 @@ const styles = stylex.create({
           type: 'list',
           style: 'do',
           items: [
-            'Match elevation to interaction context: low for tooltips, med for dropdowns, high for dialogs.',
+            'Reach for the `elevation` prop on a configurable surface before writing any custom shadow.',
+            'Choose the level by how far the surface sits from the page: `none` when flat/embedded, `low` when in-flow but distinct, `med` when over page content, `high` when over the whole UI. See "Choosing a level".',
             'Use inset shadows for input focus/selection states; they compose better than outlines.',
           ],
         },
@@ -76,6 +152,8 @@ const styles = stylex.create({
           type: 'list',
           style: 'dont',
           items: [
+            'Hand-write a `box-shadow` in app code — set the `elevation` prop or read `shadowVars` instead.',
+            'Raise a surface that does not sit above other content — a non-overlapping surface is `none` or `low`, never `med` or `high`.',
             'Stack multiple elevation levels on the same element.',
             'Use elevation shadows for decorative borders. Use --color-border tokens instead.',
           ],

package/docs/internationalization.doc.mjs

@@ -49,7 +49,7 @@ function SaveButton() {
         },
         {
           type: 'prose',
-          text: "Astryx ships translations only for English today. First-party translations for other locales are on the roadmap; track https://github.com/facebook/astryx/issues/3641. In the meantime, if you want astryx UI translated into another locale, you can ship your own catalog through the `messages` prop (covered in the next section). If you're using `useTranslator` for your own strings, you'll want to ship your own catalog either way, since astryx only carries the fallback for `@astryx.*` keys, not the ones you author.",
+          text: "Astryx ships translations only for English today. First-party translations for other locales are on the roadmap. In the meantime, if you want astryx UI translated into another locale, you can ship your own catalog through the `messages` prop (covered in the next section). If you're using `useTranslator` for your own strings, you'll want to ship your own catalog either way, since astryx only carries the fallback for `@astryx.*` keys, not the ones you author.",
         },
       ],
     },
@@ -78,7 +78,7 @@ import fr from './locales/astryx/fr.json';
         },
         {
           type: 'prose',
-          text: 'A community-maintained set of astryx translations is on the roadmap but not shipped yet. For now, consumer apps that ship in multiple languages own their astryx catalogs alongside their app catalogs. Contributions to a first-party set are welcome; track discussion at https://github.com/facebook/astryx/issues/3641.',
+          text: 'A community-maintained set of astryx translations is on the roadmap but not shipped yet. For now, consumer apps that ship in multiple languages own their astryx catalogs alongside their app catalogs. Translations are coordinated through Crowdin — contribute at https://crowdin.com/project/astryx.',
         },
       ],
     },
@@ -237,6 +237,10 @@ export default function App() {
           type: 'prose',
           text: "Astryx's own strings live in `packages/core/locales/en.json`. New user-facing strings must go through `useTranslator`; this is enforced by the `@astryx/no-hardcoded-i18n-string` ESLint rule. See the AI contribution guide for the alias-and-resolve pattern used when adding new keys.",
         },
+        {
+          type: 'prose',
+          text: 'Translators: Crowdin is the preferred way to contribute — join a language at https://crowdin.com/project/astryx, translate strings in the web UI, and your work syncs back to the repo without opening a PR. Direct PRs against `packages/core/locales/*.json` also work if you prefer that flow.',
+        },
       ],
     },
   ],

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@astryxdesign/cli",
-  "version": "0.1.8-canary.4a7ce02",
+  "version": "0.1.8-canary.4cc4d7a",
   "displayName": "CLI",
   "description": "Scaffold projects, browse templates, generate themes, and get agent-ready docs from the command line.",
   "author": "Meta Open Source",
@@ -79,10 +79,10 @@
     "zod": "^4.4.3"
   },
   "peerDependencies": {
-    "@astryxdesign/charts": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/core": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/lab": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/theme-neutral": "0.1.8-canary.4a7ce02",
+    "@astryxdesign/charts": "0.1.8-canary.4cc4d7a",
+    "@astryxdesign/core": "0.1.8-canary.4cc4d7a",
+    "@astryxdesign/lab": "0.1.8-canary.4cc4d7a",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.4cc4d7a",
     "gpt-tokenizer": "^3.4.0"
   },
   "peerDependenciesMeta": {
@@ -100,16 +100,17 @@
     }
   },
   "devDependencies": {
-    "@astryxdesign/charts": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/core": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/lab": "0.1.8-canary.4a7ce02",
-    "@astryxdesign/theme-neutral": "0.1.8-canary.4a7ce02",
+    "@astryxdesign/charts": "0.1.8-canary.4cc4d7a",
+    "@astryxdesign/core": "0.1.8-canary.4cc4d7a",
+    "@astryxdesign/lab": "0.1.8-canary.4cc4d7a",
+    "@astryxdesign/theme-neutral": "0.1.8-canary.4cc4d7a",
     "gpt-tokenizer": "^3.4.0"
   },
   "scripts": {
     "astryx": "node bin/astryx.mjs",
     "postinstall": "node scripts/postinstall.mjs",
     "typecheck:template-docs": "tsc --project tsconfig.template-docs.json",
-    "typecheck:json-api": "tsc --project tsconfig.json-api.json && tsc --project tsconfig.api-contract.json"
+    "typecheck:json-api": "tsc --project tsconfig.json-api.json && tsc --project tsconfig.api-contract.json",
+    "typecheck:strict": "tsc --project tsconfig.strict.json"
   }
 }

package/scripts/postinstall.mjs

@@ -24,11 +24,11 @@ const HERE = fileURLToPath(import.meta.url);
  * Pure decision: should the postinstall print the setup nudge? Split out so the
  * matrix is unit-testable without an actual npm install.
  *
- * @param {object} opts
- * @param {string} opts.scriptPath - Absolute path of this script (location tells
+ * @param {object} [opts]
+ * @param {string} [opts.scriptPath] - Absolute path of this script (location tells
  *   us dependency vs monorepo vs npx-cache).
  * @param {string} [opts.npmCommand] - process.env.npm_command ('install', 'exec', …).
- * @param {boolean} opts.isSetUp - Whether the project already ran init.
+ * @param {boolean} [opts.isSetUp] - Whether the project already ran init.
  * @returns {boolean}
  */
 export function shouldNudge({scriptPath, npmCommand, isSetUp} = {}) {

package/src/api/blog.mjs

@@ -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/component.mjs

@@ -29,17 +29,39 @@ import {searchComponents} from '../lib/string-utils.mjs';
 import {AstryxError} from './error.mjs';
 import {findShowcase, findRelatedBlocks} from './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: ''});
             }
@@ -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/discover.mjs

@@ -14,18 +14,27 @@ 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,
     );