blume 0.1.1 → 0.1.3

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

@@ -1457,6 +1457,20 @@ export declare const blumeConfigSchema: z.ZodObject<{
         site?: string | undefined;
     }>>;
     description: z.ZodOptional<z.ZodString>;
+    /**
+     * Where `<Component path>` resolves live previews and their source from,
+     * relative to the project root. Defaults to the `examples` directory; point
+     * it elsewhere when examples live outside a top-level `examples/`.
+     *
+     * May be a glob (anything with `*`/`?`/`[]`/`{}`/`!`), in which case only
+     * matching files are discovered and a `<Component path>` key is relative to
+     * the glob's static prefix. Use this for a registry layout that colocates
+     * component sources with their examples — `registry/<pkg>/**\/examples/*`
+     * targets just the examples, leaving the sources (which have no default
+     * export to wrap) out, so the registry needn't be forked into its own
+     * examples 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 +2912,7 @@ export declare const blumeConfigSchema: z.ZodObject<{
         base?: string | undefined;
         site?: string | undefined;
     };
+    examples: string;
     export: {
         epub: boolean;
         pdf: boolean;
@@ -3299,6 +3314,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,42 @@ 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" />
+```
+
+`examples` can also be a glob (anything with `*`, `?`, `[]`, `{}`, or `!`). Only
+matching files are discovered, and `path` is relative to the glob's static prefix
+(the part before the first wildcard). This is for a registry that colocates each
+component's source with its example — point at just the examples so the sources,
+which have no default export to preview, aren't swept in:
+
+```ts
+// blume.config.ts
+export default defineConfig({
+  // registry/files-sdk/file-list/file-list.tsx — source, left out
+  // registry/files-sdk/file-list/examples/basic.tsx — discovered
+  examples: "registry/files-sdk/**/examples/*",
+});
+```
+
+```astro
+<!-- keyed relative to registry/files-sdk -->
+<Component path="file-list/examples/basic" />
+```
+
 <Component path="counter" />
 
 ```astro

package/package.json

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

package/src/astro/examples.ts

@@ -40,23 +40,62 @@ const FRAMEWORK_BY_EXT: Record<string, ExampleFramework> = {
 };
 
 // Captures the extension so we can strip it from the path key and pick the
-// framework. Kept in sync with the glob below.
+// framework. Kept in sync with the glob below — non-matching files a user glob
+// happens to sweep in (e.g. a registry's `.ts` sources) are dropped here.
 const EXAMPLE_FILE = /\.(?<ext>astro|jsx|svelte|tsx|vue)$/u;
 
+// Renderable example files when `examples` names a plain directory.
+const DEFAULT_EXAMPLE_GLOB = "**/*.{astro,jsx,svelte,tsx,vue}";
+
+// Glob magic that turns `examples` from a plain directory into a pattern. `()`,
+// `@`, and `+` are excluded so literal path segments (npm scopes, parens) keep
+// resolving as directories; the extglob leads `*?!` still trigger here.
+const GLOB_MAGIC = /[!*?[\]{}]/u;
+
+/**
+ * Split a glob into its static directory prefix and the remaining pattern, so
+ * discovered files can be keyed relative to that prefix (e.g.
+ * `registry/x/**\/examples/*` → `{ base: "registry/x", rest: "**\/examples/*" }`).
+ */
+const splitGlobBase = (pattern: string): { base: string; rest: string } => {
+  const segments = pattern.split("/");
+  const firstMagic = segments.findIndex((segment) => GLOB_MAGIC.test(segment));
+  if (firstMagic === -1) {
+    return { base: pattern, rest: "" };
+  }
+  return {
+    base: segments.slice(0, firstMagic).join("/"),
+    rest: segments.slice(firstMagic).join("/"),
+  };
+};
+
 /**
- * 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 for 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 without its
+ * extension (e.g. `forms/login.tsx` → `forms/login`).
+ *
+ * `pattern` is a directory by default, but may be a glob (anything with
+ * `*`/`?`/`[]`/`{}`/`!`) — then only matching files are discovered and each
+ * `<Component path>` key is relative to the glob's static prefix. This lets a
+ * registry layout that colocates component sources with their examples be
+ * targeted directly (e.g. `registry/<pkg>/**\/examples/*`) without the sources —
+ * which have no default export and so can't be wrapped — being swept in.
+ *
+ * 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,
+  pattern = "examples"
 ): Promise<ExampleDiscovery> => {
-  const dir = join(root, "examples");
-  const matches = await glob(["**/*.{astro,jsx,svelte,tsx,vue}"], {
+  const { base, rest } = GLOB_MAGIC.test(pattern)
+    ? splitGlobBase(pattern)
+    : { base: pattern, rest: DEFAULT_EXAMPLE_GLOB };
+  const dir = join(root, base);
+  const matches = await glob([rest], {
     absolute: true,
     cwd: dir,
     onlyFiles: true,

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,15 +1048,25 @@ 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,
   ];
 
-  // The new provider SDKs are optional peers; warn (rather than fail opaquely in
-  // Vite) when the configured provider's package isn't installed.
+  // Provider SDKs are optional peers; warn (rather than fail opaquely in Vite)
+  // when the configured provider's package isn't installed. A dep is available
+  // if the project installed it (resolves from the root) OR Blume ships it
+  // (resolves from the Blume package — the same set the `.blume` deps link
+  // exposes to the build). Resolving from the project root alone falsely flagged
+  // a shipped SDK like Orama (the default provider) as missing whenever it
+  // wasn't hoisted into the project, e.g. under isolated linkers. We resolve
+  // from each package's real location rather than through the `.blume` junction,
+  // which can't be traversed reliably for store-symlinked deps.
   for (const dep of searchProviderMeta(config.search.provider).runtimeDeps) {
-    if (!canResolveFrom(context.root, dep)) {
+    if (
+      !(canResolveFrom(context.root, dep) || canResolveFrom(packageRoot(), dep))
+    ) {
       warnings.push(
         `Search provider "${config.search.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`
       );

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,20 @@ export const blumeConfigSchema = z
     contextual: contextualConfigSchema.default({}),
     deployment: deploymentConfigSchema.default({}),
     description: z.string().optional(),
+    /**
+     * Where `<Component path>` resolves live previews and their source from,
+     * relative to the project root. Defaults to the `examples` directory; point
+     * it elsewhere when examples live outside a top-level `examples/`.
+     *
+     * May be a glob (anything with `*`/`?`/`[]`/`{}`/`!`), in which case only
+     * matching files are discovered and a `<Component path>` key is relative to
+     * the glob's static prefix. Use this for a registry layout that colocates
+     * component sources with their examples — `registry/<pkg>/**\/examples/*`
+     * targets just the examples, leaving the sources (which have no default
+     * export to wrap) out, so the registry needn't be forked into its own
+     * examples directory.
+     */
+    examples: z.string().default("examples"),
     export: exportConfigSchema.default(false),
     favicon: faviconConfigSchema.optional(),
     feedback: z.boolean().default(true),

package/src/registry/eject.ts

@@ -73,7 +73,7 @@ export const eject = async (root: string): Promise<string[]> => {
         : Promise.resolve(""),
       buildRawMarkdown(project),
       discoverIslands(root),
-      discoverExamples(root),
+      discoverExamples(root, config.examples),
     ]);
   // Island/example frameworks drive which Astro renderers the ejected config
   // wires in; React also switches on for project `.tsx`/`.jsx` and Ask AI.