blume 0.6.7 → 0.8.0

package/src/astro/templates.ts

@@ -1,12 +1,15 @@
 import { existsSync, readFileSync } from "node:fs";
+import { pathToFileURL } from "node:url";
 
 import { dirname, isAbsolute, join, relative } from "pathe";
 
 import { askBackendRuntimeDep } from "../ai/ask.ts";
 import type { AskBackend } from "../ai/ask.ts";
+import { normalizeBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
 import type { ProjectContext } from "../core/types.ts";
+import { applyBaseToRedirects } from "../deploy/redirects.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 import { buildFontEntries } from "../theme/fonts.ts";
@@ -184,6 +187,19 @@ const renderUserAliases = (
 const astroOutDir = (context: ProjectContext): string =>
   context.distDir ?? `${context.root}/dist`;
 
+/**
+ * The `react()` integration call. When `compilerPath` is set (the resolved
+ * absolute path to `babel-plugin-react-compiler`), react() carries the compiler
+ * as the first babel plugin — an absolute path, because @vitejs/plugin-react
+ * resolves babel plugins from the *project* root, not `.blume/`, so a bare
+ * specifier wouldn't resolve in a user project. `target: "19"` matches Blume's
+ * React pin. `null`/`undefined` (compiler off or unresolvable) emits bare react().
+ */
+const reactIntegration = (compilerPath: string | null | undefined): string =>
+  compilerPath
+    ? `react({ babel: { plugins: [[${JSON.stringify(compilerPath)}, { target: "19" }]] } })`
+    : "react()";
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -194,9 +210,17 @@ export const astroConfigTemplate = (options: {
   contentRoutes: string[];
   dataPath: string;
   examplesPath: string;
+  /** The example-preview Tailwind entry (`blume:examples-theme`). */
+  examplesThemePath: string;
   themePath: string;
   searchClientPath: string;
   openapiPath: string;
+  /**
+   * Absolute path to `babel-plugin-react-compiler` when the React Compiler is
+   * enabled (resolved from Blume's package root by the caller); null/absent
+   * disables the compiler and emits a bare `react()`.
+   */
+  reactCompilerPath?: string | null;
   /** Project tsconfig path aliases (`find` -> absolute dir), e.g. `@` -> src. */
   aliases?: Record<string, string>;
 }): string => {
@@ -204,6 +228,7 @@ export const astroConfigTemplate = (options: {
   const {
     contentRoutes,
     examplesPath,
+    examplesThemePath,
     needsSvelte,
     needsVue,
     openapiPath,
@@ -248,11 +273,17 @@ export const astroConfigTemplate = (options: {
       })},`
     : "";
 
+  // Base the redirect paths the same way routes are based, so a redirect lands
+  // under `basePath` too. Astro layers its own `base` (deployment.base) on top.
+  const basedRedirects = applyBaseToRedirects(
+    config.redirects,
+    config.basePath
+  );
   const redirectsOption =
-    config.redirects.length > 0
+    basedRedirects.length > 0
       ? `\n  redirects: ${JSON.stringify(
           Object.fromEntries(
-            config.redirects.map((redirect) => [
+            basedRedirects.map((redirect) => [
               redirect.from,
               { destination: redirect.to, status: redirect.status },
             ])
@@ -288,7 +319,7 @@ export const astroConfigTemplate = (options: {
   const svelteImport = needsSvelte
     ? `import svelte from "@astrojs/svelte";\n`
     : "";
-  const blumeImport = `import { blumeIntegration, prerenderDepsPlugin } from "blume/astro";\n`;
+  const blumeImport = `import { blumeIntegration, prerenderDepsPlugin, serverAppResolvePlugin } from "blume/astro";\n`;
 
   // Twoslash runs first, before the always-on transformers, but only on fences
   // with the `twoslash` meta (explicitTrigger) — so it's opt-in per block with
@@ -297,13 +328,24 @@ export const astroConfigTemplate = (options: {
   const twoslashTransformer =
     "transformerTwoslash({ explicitTrigger: true }), ";
 
+  // Content links are rewritten to their real served URL: the `deployment.base`
+  // subdirectory (Astro doesn't rewrite `<a href>`) layered over the site-wide
+  // `basePath` baked into routes. The layers are passed separately so a
+  // hand-written `basePath` link (`/docs/x`) isn't double-prefixed (see
+  // `withComposedBasePath`). The link checker validates the base-less authored
+  // path against `basePath` routes separately.
+  const deployBase = normalizeBasePath(deployment.base);
+
   const integrations = [
     `mdx({ processor: blumeMdxProcessor(${JSON.stringify({
+      basePath: config.basePath,
+      codeThemes: config.markdown.codeBlocks.theme,
+      deployBase,
       headingAnchors: config.markdown.headingAnchors,
     })}) })`,
   ];
   if (needsReact) {
-    integrations.push("react()");
+    integrations.push(reactIntegration(options.reactCompilerPath));
   }
   if (needsVue) {
     integrations.push("vue()");
@@ -332,12 +374,15 @@ export default defineConfig({
   integrations: [${integrations.join(", ")}],
   markdown: {
     processor: blumeMarkdownProcessor(${JSON.stringify({
+      basePath: config.basePath,
+      codeThemes: config.markdown.codeBlocks.theme,
+      deployBase,
       headingAnchors: config.markdown.headingAnchors,
     })}),
     shikiConfig: {
       themes: {
-        light: "github-light",
-        dark: "github-dark",
+        light: ${JSON.stringify(config.markdown.codeBlocks.theme.light)},
+        dark: ${JSON.stringify(config.markdown.codeBlocks.theme.dark)},
       },
       defaultColor: false,
       transformers: [${twoslashTransformer}...blumeShikiTransformers(${JSON.stringify(
@@ -347,7 +392,7 @@ export default defineConfig({
   },
   devToolbar: { enabled: false },
   vite: {
-    plugins: [tailwindcss(), prerenderDepsPlugin()],
+    plugins: [tailwindcss(), prerenderDepsPlugin(), serverAppResolvePlugin()],
     // Blume's render-time deps are forced external on both build environments so
     // native bindings resolve at runtime and isolated linkers don't bundle
     // symlinked store copies (which would surface their children as unresolvable
@@ -368,6 +413,7 @@ export default defineConfig({
       alias: {
         "blume:data": ${JSON.stringify(dataPath)},
         "blume:examples": ${JSON.stringify(examplesPath)},
+        "blume:examples-theme": ${JSON.stringify(examplesThemePath)},
         "blume:openapi": ${JSON.stringify(openapiPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
         "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
@@ -396,6 +442,17 @@ export default defineConfig({
 export const stagedContentDir = (outDir: string): string =>
   join(outDir, "content");
 
+/**
+ * Astro's glob loader resolves `base` with `new URL(base, config.root)`. On
+ * Windows an absolute path like `C:\\docs\\content` makes `new URL` parse the
+ * drive letter as a URL scheme, so the result isn't a `file:` URL and Astro's
+ * subsequent `fileURLToPath` throws "The URL must be of scheme file". Emit an
+ * absolute base as a proper `file://` URL so the drive letter can't be mistaken
+ * for a scheme; relative bases resolve against `config.root` unchanged.
+ */
+const astroGlobBase = (base: string): string =>
+  isAbsolute(base) ? pathToFileURL(base).href : base;
+
 /** Generate `.blume/src/content.config.ts`. */
 export const contentConfigTemplate = (options: {
   context: ProjectContext;
@@ -454,8 +511,8 @@ export const contentConfigTemplate = (options: {
         // e.g. a prior `dist/*.mdx` render — and crash the content-module graph.
         // The runtime dir (`.blume`, or a custom distDir) is excluded precisely
         // by `outDirIgnore` instead, so it's left out of this baseline.
-        ...BLUME_IGNORE_DIRS.filter((dir) => dir !== ".blume").map(
-          (dir) => `!**/${dir}/**`
+        ...BLUME_IGNORE_DIRS.flatMap((dir) =>
+          dir === ".blume" ? [] : [`!**/${dir}/**`]
         ),
         ...outDirIgnore,
       ]
@@ -468,7 +525,7 @@ export const contentConfigTemplate = (options: {
 const staged = defineCollection({
   loader: glob({
     pattern: ["**/*.{md,mdx}"],
-    base: ${JSON.stringify(stagedBase)},
+    base: ${JSON.stringify(astroGlobBase(stagedBase))},
     generateId: ({ entry }) => entry,
   }),
 });
@@ -482,7 +539,7 @@ import { glob } from "astro/loaders";
 const docs = defineCollection({
   loader: glob({
     pattern: ${JSON.stringify(docsPattern)},
-    base: ${JSON.stringify(collectionBase)},
+    base: ${JSON.stringify(astroGlobBase(collectionBase))},
     generateId: ({ entry }) => entry,
   }),
 });
@@ -562,6 +619,31 @@ export const askEndpointTemplate = (
     content: m.content,
     role: m.role,
   }));`;
+  // `streamText` returns synchronously and defers provider/auth/network errors
+  // to stream consumption, so the handler's try/catch never sees them: without
+  // these the client gets a 200 whose stream aborts mid-flight and nothing is
+  // logged server-side. A missing credential is rejected up front as a real
+  // 500; everything else is at least logged via `onError`.
+  const keyCheck =
+    backend.kind === "gateway"
+      ? `  // The AI Gateway authenticates with an API key or Vercel's OIDC token.
+  if (!(process.env.AI_GATEWAY_API_KEY || process.env.VERCEL_OIDC_TOKEN)) {
+    return new Response(
+      "Ask AI is not configured: set AI_GATEWAY_API_KEY (or deploy on Vercel with OIDC).",
+      { status: 500 }
+    );
+  }`
+      : `  if (!process.env[${JSON.stringify(backend.apiKeyEnv)}]) {
+    return new Response(
+      ${JSON.stringify(`Ask AI is not configured: set ${backend.apiKeyEnv}.`)},
+      { status: 500 }
+    );
+  }`;
+  // Provider errors surface mid-stream, after the 200 is committed; this is
+  // the only place they can be observed server-side.
+  const onError = `      onError({ error }) {
+        console.error("Ask AI provider error:", error);
+      },`;
   const stream = grounded
     ? `    const system =
       (await ground(messages, body.page)) ??
@@ -570,15 +652,18 @@ export const askEndpointTemplate = (
       model: ${modelExpr},
       system,
       messages,
+${onError}
     });`
     : `    const result = streamText({
       model: ${modelExpr},
       system:
         "You are a helpful documentation assistant. Answer using the project's documentation.",
       messages,
+${onError}
     });`;
   const handler = `export const POST: APIRoute = async ({ request }) => {
 ${validate}
+${keyCheck}
   try {
 ${stream}
     return result.toTextStreamResponse();
@@ -751,9 +836,13 @@ export const POST: APIRoute = async ({ request }) => {
 
 /**
  * Generate the raw-Markdown endpoints (`[...slug].md.ts` and `[...slug].mdx.ts`).
- * Each route's source is served verbatim so `/<route>.md` returns plain Markdown.
+ * Both read `raw-markdown.json`, whose entries hold the verbatim source (`mdx`)
+ * plus a component-downleveled variant (`md`) when the page uses components:
+ * `/<route>.mdx` serves the source exactly as written, `/<route>.md` serves
+ * plain Markdown with `<TypeTable>`-style components converted for consumers
+ * that can't interpret JSX.
  */
-export const rawMarkdownEndpointTemplate = (): string =>
+export const rawMarkdownEndpointTemplate = (kind: "md" | "mdx"): string =>
   `// Generated by Blume. Do not edit.
 import raw from "../generated/raw-markdown.json";
 
@@ -767,7 +856,10 @@ export function getStaticPaths() {
 }
 
 export function GET({ props }) {
-  return new Response(raw[props.route] ?? "", {
+  const entry = raw[props.route];
+  return new Response(entry ? ${
+    kind === "md" ? "(entry.md ?? entry.mdx)" : "entry.mdx"
+  } : "", {
     headers: { "Content-Type": "text/markdown; charset=utf-8" },
   });
 }
@@ -946,6 +1038,7 @@ const configuration = ${JSON.stringify(options.configuration, null, 2)};
   searchEnabled={data.config.search.enabled}
   site={{ title: data.config.title, description: data.config.description }}
   themeMode={data.config.theme.mode}
+  ui={data.ui}
 >
   <ScalarComponent configuration={configuration} renderMode="client" />
 </ReferenceLayout>
@@ -978,6 +1071,7 @@ export const catchAllPageTemplate = (options: {
 // Generated by Blume. Do not edit.
 import { getEntry, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 ${askImport}
 import Accordion from "blume/components/content/Accordion.astro";
@@ -1103,13 +1197,16 @@ const ogPath = data.config.og.enabled
   ? \`/og/\${route === "/" ? "index" : route.slice(1)}.png\`
   : null;
 const ogRel = seo.image ?? ogPath;
-// Only absolutize root-relative paths: \`seo.image\` may be an external URL,
-// which must pass through verbatim (mirrors PageLayout's absolutizeOgImage).
+// Absolute URLs also carry the deployment base (the page is served under it):
+// \`site + base + path\`. Only absolutize root-relative paths: \`seo.image\` may be
+// an external URL, which passes through verbatim (mirrors PageLayout).
 const ogImage =
-  ogRel && base && ogRel.startsWith("/") ? \`\${base}\${ogRel}\` : ogRel;
+  ogRel && base && ogRel.startsWith("/") ? \`\${base}\${withBase(ogRel)}\` : ogRel;
 
+const basedRoute = withBase(route);
 const canonical =
-  seo.canonical ?? (base ? \`\${base}\${route === "/" ? "" : route}\` : null);
+  seo.canonical ??
+  (base ? \`\${base}\${basedRoute === "/" ? "" : basedRoute}\` : null);
 
 // Locale resolution. With i18n on, pick the active locale's nav + dictionary,
 // build hreflang alternates, and derive the language-switcher targets.
@@ -1142,7 +1239,10 @@ const contentLocale =
 const contentDir = i18n
   ? (i18n.locales.find((l) => l.code === contentLocale)?.dir ?? "ltr")
   : "ltr";
-const absolute = (path) => base + (path === "/" ? "" : path);
+const absolute = (path) => {
+  const p = withBase(path);
+  return base + (p === "/" ? "" : p);
+};
 
 const localeAlternates =
   i18n && base
@@ -1254,6 +1354,7 @@ export const changelogIndexTemplate = (options: {
 import { getCollection, render } from "astro:content";
 import RootLayout from "blume/components/layout/RootLayout.astro";
 import Update from "blume/components/content/Update.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
 import { resolveSlot } from "blume/components/layout/overrides.ts";
 import { layoutOverrides } from "../generated/components.ts";
 ${askImport}import data from "../generated/data.json";
@@ -1334,6 +1435,20 @@ const items = await Promise.all(
   })
 );
 
+// Repeated labels slug to the same id (e.g. two entries with neither a title
+// nor a version both falling back to "update"); suffix the later ones -2, -3,
+// ... so every heading deep-links to its own entry. The first keeps the plain
+// slug, and the rendered ids stay in lockstep with the \`headings\` list below.
+const seenIds = new Set();
+for (const item of items) {
+  let uniqueId = item.id;
+  for (let n = 2; seenIds.has(uniqueId); n += 1) {
+    uniqueId = item.id + "-" + n;
+  }
+  seenIds.add(uniqueId);
+  item.id = uniqueId;
+}
+
 // A changelog is semver-paginated only when every visible release parses as
 // semver and they span more than one major line. Older majors then collapse
 // into groups the reader reveals one at a time; otherwise the timeline is flat.
@@ -1354,7 +1469,20 @@ const headings = items.map((item) => ({
 }));
 
 const base = data.config.site ? data.config.site.replace(/\\/$/, "") : null;
-const canonical = base ? base + "/changelog" : null;
+// The canonical URL carries the deployment base (the page is served under it),
+// matching how the catch-all canonicalizes via \`withBase(route)\`.
+const basedRoute = withBase("/changelog");
+const canonical = base ? base + basedRoute : null;
+
+// The changelog is an unlocalized route, so its chrome renders in the default
+// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the catch-all's locale wiring.
+const i18n = data.config.i18n;
+const localeMeta = i18n
+  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
+  : null;
+const dir = localeMeta?.dir ?? "ltr";
+const htmlLang = i18n ? i18n.defaultLocale : "en";
 
 const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 ---
@@ -1371,6 +1499,9 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
   imageZoom={data.config.imageZoom}
   codeWrap={data.config.codeWrap}
   navigation={data.navigation}
+  locale={htmlLang}
+  dir={dir}
+  ui={data.ui}
   page={{
     title: data.config.title + " changelog",
     description: "Product updates and release notes.",
@@ -1398,7 +1529,10 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
     items.length === 0 ? (
       <p>No changelog entries yet.</p>
     ) : paginate ? (
-      <blume-changelog class="not-prose mt-8 block">
+      <blume-changelog
+        class="not-prose mt-8 block"
+        data-i18n-more={data.ui.changelog?.showReleases}
+      >
         {majorGroups[0].items.map(({ Content, href, id, label, date, tags }) => (
           <Update description={date} href={href} id={id} label={label} tags={tags}>
             <Content />
@@ -1457,11 +1591,22 @@ const LayoutComponent = resolveSlot(layoutOverrides.Layout, RootLayout);
 export const notFoundPageTemplate = (): string => `---
 // Generated by Blume. Do not edit. Override by adding \`pages/404.astro\`.
 import PageLayout from "blume/components/layout/PageLayout.astro";
+import { withBase } from "blume/components/islands/base-path.ts";
 import data from "../generated/data.json";
 
 export const prerender = true;
 
 const nf = data.ui.notFound;
+
+// The 404 page is an unlocalized route, so its chrome renders in the default
+// locale's dictionary and direction (\`data.ui\` is the default locale's resolved
+// dictionary), mirroring the catch-all's locale wiring.
+const i18n = data.config.i18n;
+const localeMeta = i18n
+  ? i18n.locales.find((l) => l.code === i18n.defaultLocale)
+  : null;
+const dir = localeMeta?.dir ?? "ltr";
+const htmlLang = i18n ? i18n.defaultLocale : "en";
 ---
 
 <PageLayout
@@ -1476,6 +1621,8 @@ const nf = data.ui.notFound;
   themeMode={data.config.theme.mode}
   fontCssVars={data.fontCssVars}
   searchEnabled={data.config.search.enabled}
+  locale={htmlLang}
+  dir={dir}
   ui={data.ui}
   noindex={true}
 >
@@ -1487,7 +1634,7 @@ const nf = data.ui.notFound;
     <p class="text-muted-foreground">{nf.description}</p>
     <a
       class="mt-2 rounded-md bg-accent px-4 py-2 text-sm font-medium text-accent-foreground"
-      href="/">{nf.home}</a
+      href={withBase("/")}>{nf.home}</a
     >
   </div>
 </PageLayout>
@@ -1575,15 +1722,31 @@ import Example from ${JSON.stringify(spec.file)};
 <Example ${exampleDirective(spec)}{...Astro.props}><slot /></Example>
 `;
 
+/**
+ * The route prefix `<Component />` preview frames are served under:
+ * `{basePath}/blume-examples/<example path>`. `deployment.base` is layered on
+ * top by Astro (components apply it with `withBase`).
+ */
+export const examplesRouteBase = (basePath: string): string =>
+  `${basePath}/blume-examples`;
+
 /**
  * Generate `.blume/src/generated/examples.ts` — a map of example path to its live
- * wrapper component plus raw source and language for the code tab. Reached by the
- * shipped `Component.astro` via the `blume:examples` alias. Always written (an
+ * wrapper component plus raw source and language for the code tab, and the route
+ * base preview iframes point at. Reached by the shipped `Component.astro` and the
+ * generated preview page via the `blume:examples` alias. Always written (an
  * empty object when there are no examples) so the alias resolves.
  */
-export const exampleMapTemplate = (specs: ExampleSpec[]): string => {
+export const exampleMapTemplate = (
+  specs: ExampleSpec[],
+  basePath: string
+): string => {
+  const base = `export const examplesBase = ${JSON.stringify(
+    examplesRouteBase(basePath)
+  )};`;
   if (specs.length === 0) {
     return `// Generated by Blume. Do not edit.
+${base}
 export const examples = {};
 `;
   }
@@ -1603,12 +1766,83 @@ export const examples = {};
     .join("\n");
   return `// Generated by Blume. Do not edit.
 ${imports}
+${base}
 export const examples = {
 ${entries}
 };
 `;
 };
 
+/**
+ * Generate the `<Component />` preview page — one prerendered route per
+ * example under `{basePath}/blume-examples/`, rendered as a bare document
+ * (no layout) that an iframe in the docs page embeds. The iframe boundary is
+ * what isolates examples from the docs CSS: the only stylesheet here is the
+ * example entry (`blume:examples-theme` — Tailwind, the Blume tokens, and the
+ * user's configured examples css), so users can preview components styled by
+ * their own design system (e.g. shadcn) with no prose styles bleeding in.
+ *
+ * The inline script mirrors the docs theme before first paint — same-document
+ * reads of the parent's `data-theme` (same origin) with a MutationObserver for
+ * live toggles — and sets both `data-theme` and a `dark` class so either
+ * dark-mode convention works in user CSS. When the page is opened directly
+ * (no parent), it falls back to the stored preference, then the OS setting.
+ */
+export const examplesPageTemplate = (): string =>
+  `---
+// Generated by Blume. Do not edit.
+import { examples } from "blume:examples";
+import "blume:examples-theme";
+
+// Prerendered even in server output, like docs content.
+export const prerender = true;
+
+export const getStaticPaths = () =>
+  Object.keys(examples).map((path) => ({ params: { path } }));
+
+const { path } = Astro.params;
+const entry = examples[path];
+const Example = entry.Component;
+---
+
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <meta name="robots" content="noindex" />
+    <title>{path}</title>
+    <script is:inline>
+      (() => {
+        const root = document.documentElement;
+        const apply = (theme) => {
+          root.dataset.theme = theme;
+          root.classList.toggle("dark", theme === "dark");
+        };
+        const stored = () =>
+          localStorage.getItem("blume-theme") ??
+          (matchMedia("(prefers-color-scheme: dark)").matches
+            ? "dark"
+            : "light");
+        try {
+          const host = window.parent.document.documentElement;
+          apply(host.dataset.theme ?? stored());
+          new MutationObserver(() => {
+            apply(host.dataset.theme ?? stored());
+          }).observe(host, { attributeFilter: ["data-theme"] });
+        } catch {
+          apply(stored());
+        }
+      })();
+    </script>
+  </head>
+  <!-- Flex + margin:auto centers the example and, unlike place-items, keeps
+       the top edge reachable when the example outgrows the frame. -->
+  <body style="display:flex;min-height:100svh;padding:1.5rem">
+    <div style="margin:auto"><Example /></div>
+  </body>
+</html>
+`;
+
 /** Generate `.blume/src/env.d.ts`. */
 export const envTemplate =
   (): string => `/// <reference path="../.astro/types.d.ts" />

package/src/blume-modules.d.ts

@@ -15,6 +15,14 @@ declare module "blume:search-client" {
   export const createSearch: () => Fn | Promise<Fn>;
 }
 
+declare module "blume:data" {
+  /** The generated per-project data snapshot (see `core/data.ts`). */
+  // biome-ignore lint/style/useImportType: ambient module must stay a global script
+  // oxlint-disable-next-line typescript/consistent-type-imports
+  const data: import("./core/data.ts").BlumeData;
+  export default data;
+}
+
 // Package-only shim so `components/props.ts` can extract `.astro` prop types with
 // `ComponentProps<typeof import("./X.astro").default>` under the package's own
 // `tsc` (where the Astro TS plugin isn't active). Not shipped in `dist/types`, so