blume 0.1.0 → 0.1.2

package/src/astro/templates.ts

@@ -8,8 +8,10 @@ import type { ResolvedConfig } from "../core/schema.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { searchProviderMeta } from "../search/providers.ts";
 import { buildFontEntries } from "../theme/fonts.ts";
+import type { ExampleSpec } from "./examples.ts";
 import type { BlumePageRoute } from "./integration.ts";
 import type { IslandSpec } from "./islands.ts";
+import type { OgCustomRoute } from "./pages.ts";
 
 const WORKSPACE_MARKERS = [
   ".git",
@@ -122,6 +124,59 @@ export const runtimeDependencies = (options: {
 };
 
 /** Generate `.blume/astro.config.mjs`. */
+/**
+ * Render project tsconfig path aliases as `vite.resolve.alias` object entries.
+ * Longest find first, so a more specific prefix (`@components`) is matched
+ * 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 =>
+  Object.entries(aliases ?? {})
+    .toSorted(([a], [b]) => b.length - a.length)
+    .map(
+      ([find, replacement]) =>
+        `\n        ${JSON.stringify(find)}: ${JSON.stringify(replacement)},`
+    )
+    .join("");
+
 export const astroConfigTemplate = (options: {
   context: ProjectContext;
   config: ResolvedConfig;
@@ -131,12 +186,22 @@ export const astroConfigTemplate = (options: {
   pages: BlumePageRoute[];
   contentRoutes: string[];
   dataPath: string;
+  examplesPath: string;
   themePath: string;
   searchClientPath: string;
+  /** Project tsconfig path aliases (`find` -> absolute dir), e.g. `@` -> src. */
+  aliases?: Record<string, string>;
 }): string => {
   const { context, config, needsReact, pages, dataPath, themePath } = options;
-  const { contentRoutes, needsSvelte, needsVue, searchClientPath } = options;
+  const {
+    contentRoutes,
+    examplesPath,
+    needsSvelte,
+    needsVue,
+    searchClientPath,
+  } = options;
   const { deployment } = config;
+  const userAliasLines = renderUserAliases(options.aliases);
   const server = deployment.output === "server";
 
   // The project root plus the workspace root, so hoisted dependencies (e.g.
@@ -214,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
@@ -276,25 +341,21 @@ 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: {
         "blume:data": ${JSON.stringify(dataPath)},
+        "blume:examples": ${JSON.stringify(examplesPath)},
         "blume:search-client": ${JSON.stringify(searchClientPath)},
-        "blume:theme": ${JSON.stringify(themePath)},
+        "blume:theme": ${JSON.stringify(themePath)},${userAliasLines}
       },
     },
     server: {
@@ -645,25 +706,47 @@ export function GET({ props }) {
 `;
 
 /** Generate the OG image endpoint (`.blume/src/pages/_og/[...slug].png.ts`). */
-export const ogEndpointTemplate = (): string =>
+export const ogEndpointTemplate = (
+  customRoutes: OgCustomRoute[] = []
+): string =>
   `// Generated by Blume. Do not edit.
 import { renderOgImage } from "blume/og";
 import data from "../../generated/data.json";
 
 export const prerender = true;
 
+// Custom (non-content) pages opted into a generated card, baked in at build.
+const customRoutes = ${JSON.stringify(customRoutes)};
+
 export function getStaticPaths() {
-  return data.routes.map((route) => ({
-    params: { slug: route.path === "/" ? "index" : route.path.slice(1) },
-    props: { title: route.title },
-  }));
+  const seen = new Set();
+  const paths = [];
+  const add = (slug, title, eyebrow) => {
+    if (seen.has(slug)) {
+      return;
+    }
+    seen.add(slug);
+    paths.push({ params: { slug }, props: { eyebrow, title } });
+  };
+  // A custom page wins over a content route sharing its path, so add it first.
+  for (const route of customRoutes) {
+    add(route.slug, route.title, route.eyebrow);
+  }
+  for (const route of data.routes) {
+    add(
+      route.path === "/" ? "index" : route.path.slice(1),
+      route.title,
+      data.config.title
+    );
+  }
+  return paths;
 }
 
 export async function GET({ props }) {
   const png = await renderOgImage({
-    title: props.title,
-    eyebrow: data.config.title,
     accent: data.config.theme.accent,
+    eyebrow: props.eyebrow,
+    title: props.title,
   });
   return new Response(png, {
     headers: {
@@ -706,6 +789,7 @@ const configuration = ${JSON.stringify(options.configuration, null, 2)};
   fontCssVars={data.fontCssVars}
   logo={data.config.logo}
   favicon={data.config.favicon}
+  appleIcon={data.config.appleIcon}
   navigation={data.navigation}
   pageTitle={${JSON.stringify(options.title)}}
   route={${JSON.stringify(options.route)}}
@@ -746,12 +830,15 @@ import Badge from "blume/components/content/Badge.astro";
 import Callout from "blume/components/content/Callout.astro";
 import Card from "blume/components/content/Card.astro";
 import CardGroup from "blume/components/content/CardGroup.astro";
+import CodeBlock from "blume/components/content/CodeBlock.astro";
 import CodeGroup from "blume/components/content/CodeGroup.astro";
 import ColorRoot from "blume/components/content/Color.astro";
 import ColorItem from "blume/components/content/ColorItem.astro";
 import ColorRow from "blume/components/content/ColorRow.astro";
 import Column from "blume/components/content/Column.astro";
 import Columns from "blume/components/content/Columns.astro";
+import Component from "blume/components/content/Component.astro";
+import Diff from "blume/components/content/Diff.astro";
 import Expandable from "blume/components/content/Expandable.astro";
 import FileTree from "blume/components/content/FileTree.astro";
 import Frame from "blume/components/content/Frame.astro";
@@ -791,10 +878,13 @@ const components = {
   Callout,
   Card,
   CardGroup,
+  CodeBlock,
   CodeGroup,
   Color,
   Column,
   Columns,
+  Component,
+  Diff,
   Expandable,
   FileTree,
   Frame,
@@ -915,6 +1005,7 @@ const localeSwitch = i18n
   logo={data.config.logo}
   mcp={data.config.mcp}
   favicon={data.config.favicon}
+  appleIcon={data.config.appleIcon}
   banner={data.config.banner}
   analytics={data.config.analytics}
   imageZoom={data.config.imageZoom}
@@ -1053,6 +1144,7 @@ const canonical = base ? base + "/changelog" : null;
   logo={data.config.logo}
   mcp={data.config.mcp}
   favicon={data.config.favicon}
+  appleIcon={data.config.appleIcon}
   banner={data.config.banner}
   analytics={data.config.analytics}
   imageZoom={data.config.imageZoom}
@@ -1164,10 +1256,76 @@ ${entries}
 `;
 };
 
+/** The literal Astro hydration directive for an example's framework/client. */
+const exampleDirective = (spec: ExampleSpec): string => {
+  if (spec.framework === "astro" || !spec.client) {
+    return "";
+  }
+  return spec.client === "only"
+    ? `client:only="${spec.framework}" `
+    : `client:${spec.client} `;
+};
+
+/** Filesystem-safe slug for an example's generated wrapper file. */
+export const exampleSlug = (path: string): string =>
+  path.replaceAll("/", "__").replaceAll(/[^a-zA-Z0-9_]+/gu, "-");
+
+/**
+ * Generate `.blume/src/generated/examples/<slug>.astro` — a wrapper that renders
+ * one example live, with its hydration directive applied (none for `.astro`).
+ * Mirrors {@link islandWrapperTemplate}; `<Component>` resolves these by path.
+ */
+export const exampleWrapperTemplate = (spec: ExampleSpec): string =>
+  `---
+// Generated by Blume. Do not edit.
+import Example from ${JSON.stringify(spec.file)};
+---
+<Example ${exampleDirective(spec)}{...Astro.props}><slot /></Example>
+`;
+
+/**
+ * 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
+ * empty object when there are no examples) so the alias resolves.
+ */
+export const exampleMapTemplate = (specs: ExampleSpec[]): string => {
+  if (specs.length === 0) {
+    return `// Generated by Blume. Do not edit.
+export const examples = {};
+`;
+  }
+  const imports = specs
+    .map(
+      (spec, index) =>
+        `import E${index} from "./examples/${exampleSlug(spec.path)}.astro";`
+    )
+    .join("\n");
+  const entries = specs
+    .map(
+      (spec, index) =>
+        `  ${JSON.stringify(spec.path)}: { Component: E${index}, code: ${JSON.stringify(
+          spec.source
+        )}, lang: ${JSON.stringify(spec.lang)} },`
+    )
+    .join("\n");
+  return `// Generated by Blume. Do not edit.
+${imports}
+export const examples = {
+${entries}
+};
+`;
+};
+
 /** Generate `.blume/src/env.d.ts`. */
 export const envTemplate =
   (): string => `/// <reference path="../.astro/types.d.ts" />
 /// <reference types="astro/client" />
+
+declare module "blume:data" {
+  const data: import("blume").BlumeData;
+  export default data;
+}
 `;
 
 /** Generate `.blume/package.json`. */

package/src/cli/commands/validate.ts

@@ -39,6 +39,7 @@ export const validateCommand = defineCommand({
         ...(await validateLinks(project.graph, {
           checkExternal: Boolean(args.external),
           publicDir: existsSync(publicDir) ? publicDir : null,
+          redirects: project.config.redirects,
         }))
       );
     } catch (error) {

package/src/components/content/CodeBlock.astro

@@ -0,0 +1,28 @@
+---
+// Render a code string highlighted with Blume's Markdown code-block theme — the
+// same Shiki themes, transformers, and dual light/dark swap as fenced code.
+// Use it to show themed code outside the Markdown pipeline (a landing page, a
+// custom component) where there's no fence to write.
+//
+//   <CodeBlock lang="ts" code={`export const x = 1;`} />
+//
+// The theme's code styles are scoped to `.prose`, so the output is wrapped in a
+// `.prose` container (`max-w-none` so it fills its own column rather than the
+// prose reading measure); that's what makes the light/dark swap work on a bare
+// page without the manual `[data-theme]` CSS it would otherwise need.
+import { highlightCode } from "../../markdown/index.ts";
+
+interface Props {
+  /** The source to highlight. */
+  code: string;
+  /** Shiki language id (default `txt`); an unknown one renders plain. */
+  lang?: string;
+  /** Show the brand language icon in the header (default on, like fences). */
+  icons?: boolean;
+}
+
+const { code, lang = "txt", icons } = Astro.props;
+const html = await highlightCode(code.replace(/\n+$/u, ""), lang, { icons });
+---
+
+<div class="prose max-w-none"><Fragment set:html={html} /></div>

package/src/components/content/Component.astro

@@ -0,0 +1,65 @@
+---
+// Render an example file (under the project's `examples/` dir) as a live,
+// hydrated preview alongside its highlighted source, in tabs. `path` is the
+// file's location under `examples/` without its extension, e.g.
+// `<Component path="forms/login" />` for `examples/forms/login.tsx`.
+//
+// Blume discovers `examples/` at build time and generates `blume:examples`: a
+// map of path → { Component (a static hydration wrapper), code, lang }. React,
+// Vue, Svelte, and Astro examples are all supported. The source is highlighted
+// with the same Shiki setup as ordinary code fences.
+import { highlightCode } from "../../markdown/index.ts";
+import Tab from "./Tab.astro";
+import Tabs from "./Tabs.astro";
+// Generated per project; resolves to an empty map when there are no examples.
+import { examples } from "blume:examples";
+
+interface Props {
+  path: string;
+}
+
+const { path } = Astro.props;
+const entry = examples[path];
+const Preview = entry?.Component;
+
+// Highlight the source with the shared helper so it matches Markdown fences.
+// `blume-source` makes the inner `<code>` (not the `<pre>`) the scroll/height-
+// capped box — see the theme entry — so the copy button, pinned to the `<pre>`,
+// stays put. This pane already lives inside `.prose`, so the theme styles it.
+const codeHtml = entry
+  ? await highlightCode(entry.code, entry.lang, { className: "blume-source" })
+  : undefined;
+
+// Both tabs share one height so toggling them never shifts the layout. Size it
+// to the source (≈21px/line + padding), clamped to a comfortable 18rem floor and
+// a 400px ceiling — taller sources scroll inside the pane.
+const LINE_PX = 21;
+const PADDING_PX = 36;
+const lineCount = entry ? entry.code.replace(/\n+$/u, "").split("\n").length : 0;
+const paneHeight = Math.min(400, Math.max(288, lineCount * LINE_PX + PADDING_PX));
+const paneStyle = `height:${paneHeight}px`;
+---
+
+{
+  entry ? (
+    // `sync={false}`: each preview's Preview/Code tabs are independent — unlike
+    // CodeGroup, switching one Component must not switch the others.
+    <Tabs hash={false} sync={false}>
+      <Tab
+        class="flex items-center justify-center overflow-auto"
+        style={paneStyle}
+        title="Preview"
+      >
+        <Preview />
+      </Tab>
+      <Tab class="overflow-hidden" style={paneStyle} title="Code">
+        <Fragment set:html={codeHtml} />
+      </Tab>
+    </Tabs>
+  ) : (
+    <div class="not-prose my-6 rounded-blume border border-border px-3 py-2 text-muted-foreground text-sm">
+      No example found at <code class="font-mono">{path}</code>. Add it under{" "}
+      <code class="font-mono">examples/</code> in your project.
+    </div>
+  )
+}

package/src/components/content/Diff.astro

@@ -0,0 +1,44 @@
+---
+// Render a git-style diff with `@pierre/diffs`, fully at build time. The library
+// emits a self-contained blob whose styles are scoped to `:host`, so we mount it
+// in a declarative shadow root — no client JS. `--blume-diff-color-scheme`
+// (set in the theme entry from `data-theme`) drives the diff's `light-dark()`.
+//
+// Inputs (one of): `patch`/`src` (unified patch), `before`+`after` (file paths),
+// or `old`+`new` (inline strings, with optional `lang`).
+import { renderDiff } from "./diff.ts";
+
+interface Props {
+  after?: string;
+  before?: string;
+  lang?: string;
+  new?: string;
+  old?: string;
+  patch?: string;
+  src?: string;
+}
+
+let html: string | undefined;
+let error: string | undefined;
+
+try {
+  html = await renderDiff(Astro.props);
+} catch (cause) {
+  error = cause instanceof Error ? cause.message : String(cause);
+}
+
+const COLOR_SCHEME =
+  "<style>:host{color-scheme:var(--blume-diff-color-scheme, light dark)}</style>";
+---
+
+{
+  error ? (
+    <div class="not-prose my-6 rounded-blume border border-border px-3 py-2 text-muted-foreground text-sm">
+      Could not render diff: {error}
+    </div>
+  ) : (
+    <blume-diff class="not-prose my-6 block overflow-hidden rounded-blume border border-border">
+      <template shadowrootmode="open" set:html={html + COLOR_SCHEME} />
+    </blume-diff>
+  )
+}

package/src/components/content/Tab.astro

@@ -2,13 +2,15 @@
 import Icon from "../Icon.astro";
 
 interface Props {
+  class?: string;
   icon?: string;
   iconType?: string;
   id?: string;
+  style?: string;
   title: string;
 }
 
-const { icon, iconType, id, title } = Astro.props;
+const { class: className, icon, iconType, id, style, title } = Astro.props;
 const slugify = (value: string): string =>
   value
     .toLowerCase()
@@ -21,8 +23,12 @@ const tabId = id ?? slugify(title);
 ---
 
 <div
-  class="px-4 py-3 [&:has(>pre)]:p-0 [&>:first-child]:mt-0! [&>:last-child]:mb-0!"
+  class:list={[
+    "px-4 py-3 [&:has(>pre)]:p-0 [&>:first-child]:mt-0! [&>:last-child]:mb-0!",
+    className,
+  ]}
   data-blume-tab-panel
+  style={style}
   data-icon={icon}
   data-tab-id={tabId}
   data-title={title}

package/src/components/content/diff.ts

@@ -0,0 +1,95 @@
+/**
+ * Build-time diff rendering for `<Diff>`.
+ *
+ * Produces a self-contained HTML string with [`@pierre/diffs`](https://diffs.com)
+ * via its `./ssr` entry — no DOM, no React, no client JS. The returned markup
+ * carries its own `:host` stylesheet and is meant to be placed inside a
+ * declarative shadow root (see `Diff.astro`). Three input shapes are supported:
+ * a unified patch (string or `.patch`/`.diff` file), a pair of file paths, or a
+ * pair of inline strings.
+ */
+import { readFile } from "node:fs/promises";
+
+import { preloadDiffHTML, preloadPatchDiff } from "@pierre/diffs/ssr";
+import { isAbsolute, join } from "pathe";
+
+export interface DiffOptions {
+  /** Path to the "after" file, resolved relative to {@link DiffOptions.root}. */
+  after?: string;
+  /** Path to the "before" file, resolved relative to {@link DiffOptions.root}. */
+  before?: string;
+  /** Language for inline {@link DiffOptions.old}/{@link DiffOptions.new} input. */
+  lang?: string;
+  /** The "after" contents, as an inline string. Pairs with {@link DiffOptions.old}. */
+  new?: string;
+  /** The "before" contents, as an inline string. Pairs with {@link DiffOptions.new}. */
+  old?: string;
+  /** A unified diff/patch as an inline string. */
+  patch?: string;
+  /** Base directory for resolving relative paths. Defaults to `process.cwd()`. */
+  root?: string;
+  /** Path to a `.patch`/`.diff` file, resolved relative to {@link DiffOptions.root}. */
+  src?: string;
+}
+
+/** Dual-theme config mirroring Blume's Shiki convention (see `templates.ts`). */
+const THEME = { dark: "github-dark", light: "github-light" } as const;
+
+const resolvePath = (path: string, root: string): string =>
+  isAbsolute(path) ? path : join(root, path);
+
+const readText = (path: string, root: string): Promise<string> =>
+  readFile(resolvePath(path, root), "utf-8");
+
+/**
+ * Resolve `<Diff>` inputs to a prerendered HTML string. Throws when no input
+ * group is supplied or a pair is half-specified, so the component can degrade
+ * to an inline notice.
+ */
+export const renderDiff = async (options: DiffOptions): Promise<string> => {
+  const {
+    after,
+    before,
+    lang,
+    new: newText,
+    old,
+    patch,
+    root = process.cwd(),
+    src,
+  } = options;
+
+  if (patch !== undefined || src !== undefined) {
+    const text = patch ?? (await readText(src as string, root));
+    const result = await preloadPatchDiff({
+      options: { theme: THEME },
+      patch: text,
+    });
+    return result.prerenderedHTML;
+  }
+
+  if (before !== undefined || after !== undefined) {
+    if (before === undefined || after === undefined) {
+      throw new Error("<Diff> needs both `before` and `after` file paths.");
+    }
+    return await preloadDiffHTML({
+      newFile: { contents: await readText(after, root), name: after },
+      oldFile: { contents: await readText(before, root), name: before },
+      options: { theme: THEME },
+    });
+  }
+
+  if (old !== undefined || newText !== undefined) {
+    if (old === undefined || newText === undefined) {
+      throw new Error("<Diff> needs both `old` and `new` strings.");
+    }
+    return await preloadDiffHTML({
+      newFile: { contents: newText, lang, name: "snippet" },
+      oldFile: { contents: old, lang, name: "snippet" },
+      options: { disableFileHeader: true, theme: THEME },
+    });
+  }
+
+  throw new Error(
+    "<Diff> requires one input: `patch`/`src`, `before`+`after`, or `old`+`new`."
+  );
+};

package/src/components/layout/Favicon.astro

@@ -1,15 +1,22 @@
 ---
-// Emits the favicon <link> for the document <head>. The href is either a URL to
-// a file the project ships in public/, or a data URI (a root-level icon, or the
-// bundled Blume default) — both resolved by the generator's resolveFavicon.
+// Emits the icon <link>s for the document <head>: the favicon (rel="icon") and,
+// when the project ships one, the Apple touch icon (rel="apple-touch-icon").
+// Each href is either a URL to a file the project ships in public/, or a data
+// URI (a root-level icon, or the bundled Blume favicon default) — both resolved
+// by the generator's resolveFavicon / resolveAppleIcon.
 interface Props {
   favicon?: {
     href: string;
     type?: string;
   } | null;
+  appleIcon?: {
+    href: string;
+    type?: string;
+  } | null;
 }
 
-const { favicon } = Astro.props;
+const { appleIcon, favicon } = Astro.props;
 ---
 
 {favicon && <link href={favicon.href} rel="icon" type={favicon.type} />}
+{appleIcon && <link href={appleIcon.href} rel="apple-touch-icon" />}