blume 0.1.1 → 0.1.2

package/dist/types/core/schema.d.ts

@@ -1457,6 +1457,14 @@ export declare const blumeConfigSchema: z.ZodObject<{
         site?: string | undefined;
     }>>;
     description: z.ZodOptional<z.ZodString>;
+    /**
+     * Directory (relative to the project root) that `<Component path>` resolves
+     * live previews and their source against. Defaults to `examples`; point it
+     * elsewhere when examples live outside a top-level `examples/` — e.g. a
+     * registry layout like `registry/<pkg>`, where a `<Component path>` key is
+     * then relative to that directory.
+     */
+    examples: z.ZodDefault<z.ZodString>;
     export: z.ZodDefault<z.ZodEffects<z.ZodUnion<[z.ZodBoolean, z.ZodObject<{
         epub: z.ZodDefault<z.ZodBoolean>;
         pdf: z.ZodDefault<z.ZodBoolean>;
@@ -2898,6 +2906,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
         base?: string | undefined;
         site?: string | undefined;
     };
+    examples: string;
     export: {
         epub: boolean;
         pdf: boolean;
@@ -3299,6 +3308,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
         output?: "static" | "server" | undefined;
         site?: string | undefined;
     } | undefined;
+    examples?: string | undefined;
     export?: boolean | {
         epub?: boolean | undefined;
         pdf?: boolean | undefined;

package/docs/content/components.mdx

@@ -573,6 +573,22 @@ a live preview alongside its highlighted source, in tabs. Point it at a file wit
 examples are all supported; framework examples hydrate, Astro ones render
 statically. It keeps the preview and the code in sync from a single file.
 
+The directory is configurable — set `examples` in `blume.config.ts` when your
+examples live elsewhere (e.g. a registry layout). `path` is always relative to
+it:
+
+```ts
+// blume.config.ts
+export default defineConfig({
+  examples: "registry/files-sdk",
+});
+```
+
+```astro
+<!-- registry/files-sdk/file-list/basic.tsx -->
+<Component path="file-list/basic" />
+```
+
 <Component path="counter" />
 
 ```astro

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",

package/src/astro/examples.ts

@@ -44,18 +44,20 @@ const FRAMEWORK_BY_EXT: Record<string, ExampleFramework> = {
 const EXAMPLE_FILE = /\.(?<ext>astro|jsx|svelte|tsx|vue)$/u;
 
 /**
- * Discover preview examples under `<root>/examples`. Every `.astro`/`.tsx`/
- * `.jsx`/`.vue`/`.svelte` file becomes addressable by `<Component path="...">`,
- * where the path is the file's location under `examples/` without its extension
- * (e.g. `forms/login.tsx` → `forms/login`). Discovery is path-based (a glob),
- * so no example code is executed. Framework examples carry a hydration mode
- * (default `client:visible`, overridable via `export const client`); `.astro`
- * examples render statically with no client directive.
+ * Discover preview examples under `<root>/<subdir>` (the `examples` config,
+ * default `examples`). Every `.astro`/`.tsx`/`.jsx`/`.vue`/`.svelte` file
+ * becomes addressable by `<Component path="...">`, where the path is the file's
+ * location under that directory without its extension (e.g. `forms/login.tsx` →
+ * `forms/login`). Discovery is path-based (a glob), so no example code is
+ * executed. Framework examples carry a hydration mode (default `client:visible`,
+ * overridable via `export const client`); `.astro` examples render statically
+ * with no client directive.
  */
 export const discoverExamples = async (
-  root: string
+  root: string,
+  subdir = "examples"
 ): Promise<ExampleDiscovery> => {
-  const dir = join(root, "examples");
+  const dir = join(root, subdir);
   const matches = await glob(["**/*.{astro,jsx,svelte,tsx,vue}"], {
     absolute: true,
     cwd: dir,

package/src/astro/generate.ts

@@ -11,7 +11,7 @@ import {
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
-import { dirname, join, normalize, relative } from "pathe";
+import { basename, dirname, join, normalize, relative } from "pathe";
 import { glob } from "tinyglobby";
 
 import { resolveAskBackend } from "../ai/ask.ts";
@@ -128,6 +128,61 @@ export const blumeDepsDir = (pkgDir: string = packageRoot()): string | null => {
   return candidates.find((dir) => existsSync(join(dir, "astro"))) ?? null;
 };
 
+/**
+ * Point `link` at Blume's dependency directory via a `node_modules` junction,
+ * replacing a stale junction we own and leaving a real directory untouched.
+ *
+ * `lstat`, not `existsSync`, so a broken junction (target since moved) is still
+ * detected — `existsSync` follows the link and reports a dangling one as absent.
+ */
+const linkDepsJunction = async (
+  link: string,
+  depsDir: string
+): Promise<void> => {
+  const existing = await lstat(link).catch(() => null);
+  if (existing) {
+    if (!existing.isSymbolicLink()) {
+      return;
+    }
+    await rm(link, { force: true });
+  }
+  await mkdir(dirname(link), { recursive: true });
+  await symlink(depsDir, link, "junction");
+};
+
+/** Read the `version` field of a `package.json`, or null when unreadable. */
+const readPkgVersion = (pkgJsonPath: string | null): string | null => {
+  if (!pkgJsonPath) {
+    return null;
+  }
+  try {
+    return JSON.parse(readFileSync(pkgJsonPath, "utf-8")).version ?? null;
+  } catch {
+    return null;
+  }
+};
+
+/**
+ * Build the diagnostic for a split-layout Astro conflict that a symlink can't
+ * repair: a different Astro is hoisted to the project root, shadowing Blume's,
+ * and `@astrojs/mdx` binds to the wrong copy. `blumeAstroPkg`/`shadowAstroPkg`
+ * are the resolved `astro/package.json` paths for Blume's set and the one the
+ * runtime actually resolves.
+ */
+const astroConflictWarning = (
+  blumeAstroPkg: string | null,
+  shadowAstroPkg: string | null
+): string => {
+  const blume = readPkgVersion(blumeAstroPkg);
+  const shadow = readPkgVersion(shadowAstroPkg);
+  const versions =
+    blume && shadow
+      ? `astro@${shadow} shadowing Blume's astro@${blume}`
+      : "a second copy of Astro shadowing Blume's";
+  const pin = blume ?? "<Blume's astro version>";
+  return `Astro version conflict: another dependency hoisted ${versions} to the project root, so @astrojs/mdx binds to the wrong copy and the build fails on a missing export (e.g. "chunkToString"). A single symlink can't reconcile a split install — pin Blume's Astro by adding a package.json "overrides" (npm/bun/pnpm) or "resolutions" (yarn) entry { "astro": "${pin}" }, then reinstall. Run \`npm ls astro\` to find the dependency pulling the older copy.`;
+};
+
 /**
  * Make the generated runtime resolve Astro and its integrations against Blume's
  * own dependency set. Two failure modes this repairs:
@@ -146,40 +201,81 @@ export const blumeDepsDir = (pkgDir: string = packageRoot()): string | null => {
  * are a *co-located, consistent* set (astro beside the `@astrojs/mdx` that binds
  * to it). A split layout — an integration hoisted away from a conflicting astro
  * — can't be made consistent by a single symlink and needs a root `overrides`/
- * `resolutions` pin instead, so we leave it untouched rather than half-fix it.
+ * `resolutions` pin instead. We can't fix that from `.blume/`, so we return a
+ * diagnostic naming the conflict rather than silently shipping a runtime that
+ * crashes downstream. Returns the warning, or null when nothing needs saying.
  */
 export const ensureDepsLink = async (
   outDir: string,
   pkgDir: string = packageRoot()
-): Promise<void> => {
+): Promise<string | null> => {
   const depsDir = blumeDepsDir(pkgDir);
-  if (!depsDir || !existsSync(join(depsDir, "@astrojs", "mdx"))) {
-    return;
+  if (!depsDir) {
+    return null;
   }
   // Already correct when `.blume/` resolves the very same astro Blume's deps
-  // provide — the clean hoisted case. Otherwise (unreachable, or a different
-  // astro shadowing Blume's) link Blume's deps in.
+  // provide — the clean hoisted case, nothing to do.
   const blumeAstro = resolvedAstroPath(depsDir);
-  if (blumeAstro && resolvedAstroPath(outDir) === blumeAstro) {
-    return;
+  const outDirAstro = resolvedAstroPath(outDir);
+  if (blumeAstro && outDirAstro === blumeAstro) {
+    return null;
   }
-  const link = join(outDir, "node_modules");
-  // `lstat`, not `existsSync`, so a broken junction (target since moved) is
-  // still detected — `existsSync` follows the link and reports a dangling one
-  // as absent. Reaching here means `outDir` doesn't resolve Blume's astro, so
-  // any existing link is stale: replace a link we own (a junction/symlink) and
-  // leave a real directory untouched.
-  const existing = await lstat(link).catch(() => null);
-  if (existing) {
-    if (!existing.isSymbolicLink()) {
-      return;
-    }
-    await rm(link, { force: true });
+  // A co-located, consistent set (astro beside the @astrojs/mdx that binds to
+  // it) can be linked in wholesale; this repairs the unreachable and the
+  // repairable-conflict cases. Any existing link here is stale and gets
+  // replaced.
+  if (existsSync(join(depsDir, "@astrojs", "mdx"))) {
+    await linkDepsJunction(join(outDir, "node_modules"), depsDir);
+    return null;
   }
-  await mkdir(outDir, { recursive: true });
-  await symlink(depsDir, link, "junction");
+  // Split layout: Blume's astro is nested (a conflicting astro took the root
+  // spot) but @astrojs/mdx hoisted away from it, binding to the shadow. Only a
+  // root pin fixes this — surface it.
+  return astroConflictWarning(blumeAstro, outDirAstro);
 };
 
+/**
+ * Vite plugin that makes Blume's externalized runtime deps (zod, shiki, sharp,
+ * `@takumi-rs/core`, …) resolvable when Astro executes the static prerender
+ * bundle under an isolated linker (Bun's `isolated` mode, pnpm).
+ *
+ * Astro's static build emits a self-contained SSR bundle to
+ * `<outDir>/.prerender/` and `import()`s it in-process to generate the HTML.
+ * That bundle externalizes Blume's render-time deps, so Node resolves them at
+ * prerender time by walking up from `.prerender/chunks/*.mjs`. {@link
+ * ensureDepsLink} only repairs resolution rooted at `.blume/`; `.prerender/`
+ * lives under `dist/`, a separate tree an isolated linker never hoists Blume's
+ * deps into — so the import dies with `Cannot find package 'zod'`. We drop the
+ * same `node_modules` junction into the prerender root, mirroring
+ * `.blume/node_modules`, so every externalized specifier — native bindings
+ * included, which can't be bundled — resolves. Astro deletes `.prerender/` once
+ * generation finishes (and the junction with it: `fs.rm` unlinks symlinks, it
+ * never follows them), so nothing leaks into the published `dist/`.
+ *
+ * Keyed off the output dir's basename (`.prerender`) — the name Astro 7 gives
+ * the prerender build for both static (`<outDir>/.prerender/`) and server
+ * (`<build.server>/.prerender/`) output — so it fires for exactly that build.
+ * Inert in dev, where there is no build and `writeBundle` never runs.
+ */
+export const prerenderDepsPlugin = (
+  pkgDir: string = packageRoot()
+): {
+  name: string;
+  writeBundle: (options: { dir?: string }) => Promise<void>;
+} => ({
+  name: "blume:prerender-deps",
+  writeBundle: async (options) => {
+    if (!options.dir || basename(options.dir) !== ".prerender") {
+      return;
+    }
+    const depsDir = blumeDepsDir(pkgDir);
+    if (!depsDir) {
+      return;
+    }
+    await linkDepsJunction(join(options.dir, "node_modules"), depsDir);
+  },
+});
+
 /** Astro integration package each non-React island framework needs installed. */
 const ISLAND_FRAMEWORK_DEPS: Record<string, string> = {
   svelte: "@astrojs/svelte",
@@ -720,7 +816,7 @@ export const generateRuntime = async (
     return writeIfChanged(path, content);
   };
 
-  await ensureDepsLink(out);
+  const depsLinkWarning = await ensureDepsLink(out);
 
   const askEnabled = config.ai.ask?.enabled ?? false;
   const exportPdf = config.export.pdf;
@@ -733,7 +829,7 @@ export const generateRuntime = async (
       detectNeedsReact(context.root),
       readOptional(context.themeFile),
       discoverIslands(context.root),
-      discoverExamples(context.root),
+      discoverExamples(context.root, config.examples),
     ]);
   // Each island/example framework enables its Astro renderer. React also
   // switches on for any project `.tsx`/`.jsx` and for Ask AI; Vue/Svelte are
@@ -952,6 +1048,7 @@ export const generateRuntime = async (
   // API/AsyncAPI reference pages (Scalar). One self-contained page per source,
   // mounted on its configured route and regenerated each run.
   const warnings: string[] = [
+    ...(depsLinkWarning ? [depsLinkWarning] : []),
     ...mcp.warnings,
     ...islandDiscovery.warnings,
     ...exampleDiscovery.warnings,

package/src/astro/index.ts

@@ -1,4 +1,4 @@
-export { generateRuntime } from "./generate.ts";
+export { generateRuntime, prerenderDepsPlugin } from "./generate.ts";
 export type { GenerateResult } from "./generate.ts";
 export { blumeIntegration } from "./integration.ts";
 export type { BlumeIntegrationOptions, BlumePageRoute } from "./integration.ts";

package/src/astro/templates.ts

@@ -130,6 +130,42 @@ export const runtimeDependencies = (options: {
  * before a broader one (`@`); these follow Blume's `blume:*` aliases, which
  * never overlap with a project's.
  */
+/**
+ * Blume's render-time dependencies, forced external on the build's SSR and
+ * static-prerender Vite environments.
+ *
+ * Two reasons a dep lands here:
+ *   - `@takumi-rs/core` (OG image rendering) is a native NAPI addon that loads a
+ *     platform-specific `.node` binding via `createRequire(import.meta.url)`.
+ *     Bundling it relocates `import.meta.url` and breaks the binding lookup
+ *     ("Cannot find native binding") on other platforms (e.g. the Linux CI
+ *     runner), so it must resolve from `node_modules` at runtime instead.
+ *   - The rest are pure-JS packages kept external so an isolated linker (Bun's
+ *     `isolated` mode, pnpm) doesn't bundle their symlinked store copies. When
+ *     Vite bundles such a package but leaves its own `node_modules` child
+ *     external, that child surfaces as an unresolvable bare import in the
+ *     prerender chunk (e.g. `batchwork` via `@astrojs/markdown-satteri`). Kept
+ *     external, each package's transitive imports resolve relative to its real
+ *     store location — reachable through the `node_modules` junction {@link
+ *     prerenderDepsPlugin} drops beside the prerender bundle.
+ *
+ * Astro 7 configures externalization per Vite environment, so this must be
+ * applied to both `prerender` (static) and `ssr` (server) — a top-level
+ * `ssr.external` only reaches the latter.
+ */
+const RENDER_EXTERNAL_DEPS = [
+  "@astrojs/markdown-satteri",
+  "@pierre/diffs",
+  "@shikijs/transformers",
+  "@takumi-rs/core",
+  "@takumi-rs/helpers",
+  "github-slugger",
+  "katex",
+  "shiki",
+  "simple-icons",
+  "zod",
+];
+
 const renderUserAliases = (
   aliases: Record<string, string> | undefined
 ): string =>
@@ -243,7 +279,7 @@ export const astroConfigTemplate = (options: {
   const svelteImport = needsSvelte
     ? `import svelte from "@astrojs/svelte";\n`
     : "";
-  const blumeImport = `import { blumeIntegration } from "blume/astro";\n`;
+  const blumeImport = `import { blumeIntegration, prerenderDepsPlugin } 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
@@ -305,19 +341,14 @@ export default defineConfig({
   },
   devToolbar: { enabled: false },
   vite: {
-    plugins: [tailwindcss()],
-    // @takumi-rs/core (OG image rendering) is a native NAPI addon that loads a
-    // platform-specific .node binding via createRequire(import.meta.url). Astro's
-    // build bundles it into the per-environment output by default, which
-    // relocates import.meta.url and breaks the binding lookup ("Cannot find
-    // native binding") on other platforms (e.g. the Linux CI runner). Astro 7
-    // configures externalization per Vite environment, so it must be forced
-    // external on the prerender (static) and ssr (server) environments -- a
-    // top-level ssr.external only reaches the latter -- so the binding resolves
-    // from node_modules at runtime instead.
+    plugins: [tailwindcss(), prerenderDepsPlugin()],
+    // 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
+    // imports). See RENDER_EXTERNAL_DEPS / prerenderDepsPlugin.
     environments: {
-      prerender: { resolve: { external: ["@takumi-rs/core"] } },
-      ssr: { resolve: { external: ["@takumi-rs/core"] } },
+      prerender: { resolve: { external: ${JSON.stringify(RENDER_EXTERNAL_DEPS)} } },
+      ssr: { resolve: { external: ${JSON.stringify(RENDER_EXTERNAL_DEPS)} } },
     },
     resolve: {
       alias: {

package/src/core/schema.ts

@@ -1021,6 +1021,14 @@ export const blumeConfigSchema = z
     contextual: contextualConfigSchema.default({}),
     deployment: deploymentConfigSchema.default({}),
     description: z.string().optional(),
+    /**
+     * Directory (relative to the project root) that `<Component path>` resolves
+     * live previews and their source against. Defaults to `examples`; point it
+     * elsewhere when examples live outside a top-level `examples/` — e.g. a
+     * registry layout like `registry/<pkg>`, where a `<Component path>` key is
+     * then relative to that directory.
+     */
+    examples: z.string().default("examples"),
     export: exportConfigSchema.default(false),
     favicon: faviconConfigSchema.optional(),
     feedback: z.boolean().default(true),