blume 0.0.0 → 0.1.1

package/src/astro/index.ts

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

package/src/astro/integration.ts

@@ -0,0 +1,74 @@
+import type { IncomingMessage, ServerResponse } from "node:http";
+
+import type { AstroIntegration } from "astro";
+
+import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
+
+/** A user page mounted into the generated runtime. */
+export interface BlumePageRoute {
+  /** Route pattern, e.g. `/changelog` or `/examples/[slug]`. */
+  pattern: string;
+  /** Absolute path to the user's `.astro` page file. */
+  entrypoint: string;
+}
+
+export interface BlumeIntegrationOptions {
+  pages: BlumePageRoute[];
+  /** Page routes that have a raw-Markdown variant (the content manifest). */
+  contentRoutes: string[];
+}
+
+/**
+ * Dev-server content negotiation: when a client asks for `text/markdown`,
+ * transparently rewrite a content-page request to its `.md` variant so the
+ * existing raw-Markdown endpoint serves it. Runs only under `blume dev`; static
+ * and server builds expose the same content at the `.md` URL. Only routes with
+ * a Markdown variant are rewritten, so landing pages and user `.astro` pages
+ * keep serving HTML.
+ */
+const negotiateMarkdown =
+  (routes: ReadonlySet<string>) =>
+  (req: IncomingMessage, res: ServerResponse, next: () => void): void => {
+    if (
+      (req.method === "GET" || req.method === "HEAD") &&
+      prefersMarkdown(req.headers.accept)
+    ) {
+      const variant = markdownVariantUrl(req.url, routes);
+      if (variant) {
+        res.setHeader("Vary", "Accept");
+        req.url = variant;
+      }
+    }
+    next();
+  };
+
+/**
+ * Blume's Astro integration. Mounts user-authored pages from `pages/` into the
+ * generated runtime via `injectRoute`, keeping each file in its original
+ * location so relative imports and `getStaticPaths` keep working, and teaches
+ * the dev server to honour `Accept: text/markdown`.
+ */
+export const blumeIntegration = (
+  options: BlumeIntegrationOptions
+): AstroIntegration => ({
+  hooks: {
+    "astro:config:setup": ({ injectRoute }) => {
+      for (const page of options.pages) {
+        injectRoute({
+          entrypoint: page.entrypoint,
+          pattern: page.pattern,
+          prerender: true,
+        });
+      }
+    },
+    "astro:server:setup": ({ server }) => {
+      // Prepend so the rewrite happens before Astro's own request handler,
+      // letting the rewritten URL resolve to the `.md` endpoint.
+      server.middlewares.stack.unshift({
+        handle: negotiateMarkdown(new Set(options.contentRoutes)),
+        route: "",
+      });
+    },
+  },
+  name: "blume",
+});

package/src/astro/islands.ts

@@ -0,0 +1,131 @@
+import { readFile } from "node:fs/promises";
+
+import { basename, join } from "pathe";
+import { glob } from "tinyglobby";
+
+/** Astro hydration directives Blume applies to a convention island. */
+export type IslandClientMode = "idle" | "load" | "only" | "visible";
+
+/** Client framework an island is authored in, inferred from its extension. */
+export type IslandFramework = "react" | "svelte" | "vue";
+
+/** A discovered `islands/` component, ready to wrap and expose to MDX. */
+export interface IslandSpec {
+  /** Hydration directive, from `export const client` or the default. */
+  client: IslandClientMode;
+  /** Absolute path to the island source file. */
+  file: string;
+  /** Astro client framework, used to enable the renderer and for `client:only`. */
+  framework: IslandFramework;
+  /** Component name used in MDX — the file's basename without extension. */
+  name: string;
+}
+
+export interface IslandDiscovery {
+  islands: IslandSpec[];
+  warnings: string[];
+}
+
+/** Hydration mode used when an island doesn't declare one. */
+const DEFAULT_CLIENT: IslandClientMode = "visible";
+
+const VALID_MODES = new Set<IslandClientMode>([
+  "idle",
+  "load",
+  "only",
+  "visible",
+]);
+
+/** Island extensions mapped to the Astro renderer that handles them. */
+const FRAMEWORK_BY_EXT: Record<string, IslandFramework> = {
+  jsx: "react",
+  svelte: "svelte",
+  tsx: "react",
+  vue: "vue",
+};
+
+// Captures the extension so we can both strip it from the name and pick the
+// framework. Kept in sync with the glob below.
+const ISLAND_FILE = /\.(?<ext>jsx|svelte|tsx|vue)$/u;
+
+// Matches `export const client = "load"` (with optional type annotation and
+// either quote style). Read statically so we never execute island code in Node.
+const CLIENT_EXPORT =
+  /export\s+const\s+client\s*(?::[^=]+)?=\s*["'](?<mode>\w+)["']/u;
+
+export const readClientMode = (
+  source: string,
+  file: string,
+  warnings: string[]
+): IslandClientMode => {
+  const mode = source.match(CLIENT_EXPORT)?.groups?.mode;
+  if (!mode) {
+    return DEFAULT_CLIENT;
+  }
+  if (!VALID_MODES.has(mode as IslandClientMode)) {
+    warnings.push(
+      `Island "${file}" declares an unknown client mode "${mode}"; defaulting to "${DEFAULT_CLIENT}". Use "load", "idle", "visible", or "only".`
+    );
+    return DEFAULT_CLIENT;
+  }
+  return mode as IslandClientMode;
+};
+
+/**
+ * Discover convention islands under `<root>/islands`. Every `.tsx`/`.jsx`/
+ * `.vue`/`.svelte` file becomes a globally-available, hydrated MDX component
+ * named after the file (which must be PascalCase to be usable as a JSX tag).
+ * Hydration defaults to `client:visible`; a file opts out with `export const
+ * client = "load" | "idle" | "only"`. Discovery is path-based (a glob), so no
+ * user code is executed.
+ */
+export const discoverIslands = async (
+  root: string
+): Promise<IslandDiscovery> => {
+  const dir = join(root, "islands");
+  const matches = await glob(["**/*.{jsx,svelte,tsx,vue}"], {
+    absolute: true,
+    cwd: dir,
+    onlyFiles: true,
+  });
+  const files = matches.toSorted();
+  const sources = await Promise.all(
+    files.map((file) => readFile(file, "utf-8"))
+  );
+
+  const islands: IslandSpec[] = [];
+  const warnings: string[] = [];
+  const seen = new Map<string, string>();
+
+  for (const [index, file] of files.entries()) {
+    const base = basename(file);
+    const ext = base.match(ISLAND_FILE)?.groups?.ext;
+    const framework = ext ? FRAMEWORK_BY_EXT[ext] : undefined;
+    if (!framework) {
+      continue;
+    }
+    const name = base.replace(ISLAND_FILE, "");
+    if (!/^[A-Z]/u.test(name)) {
+      warnings.push(
+        `Island "${file}" must have a PascalCase filename to be used in MDX (e.g. Counter.tsx → <Counter />); skipping it.`
+      );
+      continue;
+    }
+    const existing = seen.get(name);
+    if (existing) {
+      warnings.push(
+        `Two islands both resolve to <${name}> ("${existing}" and "${file}"); ignoring the second. Give them distinct filenames.`
+      );
+      continue;
+    }
+    seen.set(name, file);
+    islands.push({
+      client: readClientMode(sources[index] ?? "", file, warnings),
+      file,
+      framework,
+      name,
+    });
+  }
+
+  return { islands, warnings };
+};

package/src/astro/markdown-negotiation.ts

@@ -0,0 +1,68 @@
+/**
+ * HTTP content negotiation for the raw-Markdown variants. The `<route>.md`
+ * endpoints already serve a page's source verbatim; these helpers let the dev
+ * server honour `Accept: text/markdown` by transparently rewriting a page
+ * request to its `.md` variant.
+ */
+
+interface AcceptEntry {
+  q: number;
+  type: string;
+}
+
+const parseAccept = (accept: string): AcceptEntry[] =>
+  accept.split(",").map((part) => {
+    const segments = part.trim().split(";");
+    const type = (segments[0] ?? "").trim().toLowerCase();
+    const qSegment = segments
+      .slice(1)
+      .map((segment) => segment.trim())
+      .find((segment) => segment.startsWith("q="));
+    const q = qSegment ? Number.parseFloat(qSegment.slice(2)) : 1;
+    return { q: Number.isNaN(q) ? 1 : q, type };
+  });
+
+/**
+ * Whether the client explicitly prefers Markdown over HTML. Browsers never send
+ * `text/markdown`, so an ordinary page request (`text/html`, `*​/*`) is false.
+ */
+export const prefersMarkdown = (accept: string | null | undefined): boolean => {
+  if (!accept) {
+    return false;
+  }
+  let markdownQ = -1;
+  let htmlQ = 0;
+  for (const { q, type } of parseAccept(accept)) {
+    if (type === "text/markdown" || type === "text/x-markdown") {
+      markdownQ = Math.max(markdownQ, q);
+    } else if (type === "text/html") {
+      htmlQ = Math.max(htmlQ, q);
+    }
+  }
+  return markdownQ > 0 && markdownQ >= htmlQ;
+};
+
+/**
+ * Map a page request URL to its `.md` variant, or `null` when the requested
+ * path is not a known content route (Vite/Astro internals, assets, API routes,
+ * landing pages, and user `.astro` pages all fall through). `routes` is the set
+ * of page paths that have a raw-Markdown variant.
+ */
+export const markdownVariantUrl = (
+  rawUrl: string | null | undefined,
+  routes: ReadonlySet<string>
+): string | null => {
+  if (!rawUrl) {
+    return null;
+  }
+  const queryIndex = rawUrl.indexOf("?");
+  const query = queryIndex === -1 ? "" : rawUrl.slice(queryIndex);
+  const rawPath = queryIndex === -1 ? rawUrl : rawUrl.slice(0, queryIndex);
+  const pathname =
+    rawPath !== "/" && rawPath.endsWith("/") ? rawPath.slice(0, -1) : rawPath;
+  if (!routes.has(pathname)) {
+    return null;
+  }
+  const target = pathname === "/" ? "/index" : pathname;
+  return `${target}.md${query}`;
+};

package/src/astro/pages.ts

@@ -0,0 +1,87 @@
+import { extname, relative } from "pathe";
+import { glob } from "tinyglobby";
+
+import type { BlumePageRoute } from "./integration.ts";
+
+/**
+ * Discover user `.astro` pages and map them to route patterns. Files keep their
+ * original location; only the route pattern is derived (index -> parent,
+ * dynamic `[param]` segments preserved).
+ */
+export const discoverPages = async (
+  pagesRoot: string
+): Promise<BlumePageRoute[]> => {
+  const files = await glob(["**/*.astro"], {
+    absolute: true,
+    cwd: pagesRoot,
+    onlyFiles: true,
+  });
+  files.sort();
+
+  return files.map((file) => {
+    const rel = relative(pagesRoot, file);
+    const withoutExt = rel.slice(0, rel.length - extname(rel).length);
+    const parts = withoutExt.split("/").filter((part) => part !== "index");
+    const pattern = parts.length === 0 ? "/" : `/${parts.join("/")}`;
+    return { entrypoint: file, pattern };
+  });
+};
+
+/** A custom-page route that should get a generated OG card. */
+export interface OgCustomRoute {
+  /** `og/<slug>.png` path segment; `index` for the site root. */
+  slug: string;
+  /** Card title. */
+  title: string;
+  /** Small eyebrow line above the title. */
+  eyebrow?: string;
+}
+
+/** Skip private (`_partial`, `.well-known`) and Astro dynamic (`[param]`) parts. */
+const PRIVATE_SEGMENT = /^[._]/u;
+
+const humanizeSegment = (segment: string): string =>
+  segment
+    .split(/[-_]/u)
+    .filter(Boolean)
+    .map((word) => word.charAt(0).toUpperCase() + word.slice(1))
+    .join(" ");
+
+/**
+ * Pick the custom-page routes that should get a generated Open Graph card, with
+ * the card's slug and text. OG is otherwise content-route only, so a custom page
+ * — most importantly the landing `/`, the most-shared URL — would have no card.
+ *
+ * Dynamic (`[param]`) routes and private segments (`_partials`, `.well-known`)
+ * are skipped: they aren't shareable pages. The home is titled with the site
+ * title (eyebrow: the site description); a deeper page is titled from its last
+ * path segment.
+ */
+export const customOgRoutes = (
+  pages: BlumePageRoute[],
+  siteTitle: string,
+  siteDescription?: string
+): OgCustomRoute[] => {
+  const seen = new Set<string>();
+  const routes: OgCustomRoute[] = [];
+  for (const { pattern } of pages) {
+    const segments = pattern.split("/").filter(Boolean);
+    if (
+      segments.some((part) => PRIVATE_SEGMENT.test(part) || part.includes("["))
+    ) {
+      continue;
+    }
+    const slug = segments.length === 0 ? "index" : segments.join("/");
+    if (seen.has(slug)) {
+      continue;
+    }
+    seen.add(slug);
+    const last = segments.at(-1);
+    routes.push(
+      last
+        ? { eyebrow: siteTitle, slug, title: humanizeSegment(last) }
+        : { eyebrow: siteDescription, slug, title: siteTitle }
+    );
+  }
+  return routes;
+};