blume 1.4.2 → 1.5.0

package/src/ai/tar.ts

@@ -1,10 +1,15 @@
 import { gzipSync } from "node:zlib";
 
+import { createTar } from "nanotar";
+
 /**
- * Minimal, dependency-free `.tar.gz` writer for agent-skill archives (POSIX
- * ustar). Deterministic by construction — fixed mtime/uid/gid, caller-ordered
- * entries, and Node's gzip header carries no timestamp — so a skill's archive
- * digest only changes when its content does.
+ * `.tar.gz` writer for agent-skill archives, on nanotar's ustar writer.
+ * Deterministic by construction — fixed mtime/uid/gid/owner attrs,
+ * caller-ordered entries, and Node's gzip header carries no timestamp — so a
+ * skill's archive digest only changes when its content does. That holds per
+ * machine: the tar bytes are portable, but zlib's compressed stream differs
+ * across architectures, so gzip-layer digests are not comparable across
+ * platforms.
  */
 
 /** One regular file to archive. Paths are `/`-separated, relative, no `..`. */
@@ -17,67 +22,18 @@ export interface TarEntry {
   path: string;
 }
 
-const BLOCK = 512;
 /** ustar `name` field capacity; skill layouts are shallow, so no `prefix`. */
 const NAME_MAX = 100;
 
 const encoder = new TextEncoder();
 
-/** Write an octal field: zero-padded digits followed by a NUL terminator. */
-const octal = (
-  header: Uint8Array,
-  offset: number,
-  length: number,
-  value: number
-): void => {
-  const text = value.toString(8).padStart(length - 1, "0");
-  header.set(encoder.encode(text), offset);
-  header[offset + length - 1] = 0;
-};
-
-const text = (header: Uint8Array, offset: number, value: string): void => {
-  header.set(encoder.encode(value), offset);
-};
-
-const fileHeader = (entry: TarEntry): Uint8Array => {
-  const header = new Uint8Array(BLOCK);
-  text(header, 0, entry.path);
-  octal(header, 100, 8, entry.executable ? 0o755 : 0o644);
-  // uid and gid: root-owned, fixed for determinism.
-  octal(header, 108, 8, 0);
-  octal(header, 116, 8, 0);
-  octal(header, 124, 12, entry.content.byteLength);
-  // mtime: fixed at the epoch for determinism.
-  octal(header, 136, 12, 0);
-  // typeflag "0": regular file.
-  text(header, 156, "0");
-  text(header, 257, "ustar");
-  header[262] = 0;
-  text(header, 263, "00");
-  // devmajor and devminor.
-  octal(header, 329, 8, 0);
-  octal(header, 337, 8, 0);
-  // Checksum: computed with the checksum field treated as eight spaces, then
-  // written as six octal digits, NUL, space (the historical ustar format).
-  header.fill(0x20, 148, 156);
-  let sum = 0;
-  for (const byte of header) {
-    sum += byte;
-  }
-  text(header, 148, sum.toString(8).padStart(6, "0"));
-  header[154] = 0;
-  header[155] = 0x20;
-  return header;
-};
-
 /**
  * Build a gzipped ustar archive of the given files, in the given order. Paths
- * longer than the ustar `name` field or escaping the archive root are the
- * caller's responsibility to filter — this throws to surface a programming
- * error rather than emitting a corrupt archive.
+ * longer than the ustar `name` field or escaping the archive root throw to
+ * surface a programming error — nanotar would silently truncate an oversized
+ * name into a corrupt archive, so the validation stays here.
  */
 export const buildTarGz = (entries: readonly TarEntry[]): Uint8Array => {
-  const blocks: Uint8Array[] = [];
   for (const entry of entries) {
     if (encoder.encode(entry.path).byteLength > NAME_MAX) {
       throw new Error(`tar path exceeds ${NAME_MAX} bytes: ${entry.path}`);
@@ -85,20 +41,23 @@ export const buildTarGz = (entries: readonly TarEntry[]): Uint8Array => {
     if (entry.path.startsWith("/") || entry.path.split("/").includes("..")) {
       throw new Error(`tar path must be archive-relative: ${entry.path}`);
     }
-    blocks.push(fileHeader(entry), entry.content);
-    const overhang = entry.content.byteLength % BLOCK;
-    if (overhang > 0) {
-      blocks.push(new Uint8Array(BLOCK - overhang));
-    }
-  }
-  // End-of-archive marker: two zero blocks.
-  blocks.push(new Uint8Array(BLOCK * 2));
-  const total = blocks.reduce((sum, block) => sum + block.byteLength, 0);
-  const tar = new Uint8Array(total);
-  let offset = 0;
-  for (const block of blocks) {
-    tar.set(block, offset);
-    offset += block.byteLength;
   }
+  const tar = createTar(
+    entries.map((entry) => ({
+      // Root-owned, epoch-mtime, empty owner names: every field a rebuild
+      // could vary is pinned so the archive bytes are a function of content.
+      attrs: {
+        gid: 0,
+        group: "",
+        mode: entry.executable ? "755" : "644",
+        mtime: 0,
+        uid: 0,
+        user: "",
+      },
+      data: entry.content,
+      name: entry.path,
+    }))
+  );
+  // Sync gzip with a pinned level; Node writes no timestamp into the header.
   return new Uint8Array(gzipSync(tar, { level: 9 }));
 };

package/src/ai/visibility.ts

@@ -19,10 +19,10 @@ const visibilityBlock = (audience: VisibilityAudience): RegExp =>
     "gu"
   );
 
-const BLOCKS: Record<VisibilityAudience, RegExp> = {
+const BLOCKS = {
   agents: visibilityBlock("agents"),
   web: visibilityBlock("web"),
-};
+} satisfies Record<VisibilityAudience, RegExp>;
 
 /**
  * Resolve `<Visibility>` blocks for one audience: blocks addressed to the

package/src/astro/component-slots.ts

@@ -77,6 +77,8 @@ const importClause = (variable: string, name: string, path: string): string =>
 
 /** A wrapper `.astro` that statically imports a component and hydrates it. */
 const wrapperContent = (override: NormalizedOverride): string => {
+  // SAFETY: the only caller guards `if (!source)` and bails before invoking
+  // this, so the override always carries a resolved source here.
   const { name, path } = override.source as NonNullable<
     NormalizedOverride["source"]
   >;

package/src/astro/examples.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 
+import pMap from "p-map";
 import { join, relative } from "pathe";
 import { glob } from "tinyglobby";
 
@@ -32,7 +33,11 @@ export interface ExampleDiscovery {
 }
 
 /** Example extensions mapped to the framework that renders them. */
-const FRAMEWORK_BY_EXT: Record<string, ExampleFramework> = {
+interface FrameworkByExtension {
+  [extension: string]: ExampleFramework;
+}
+
+const FRAMEWORK_BY_EXT: FrameworkByExtension = {
   astro: "astro",
   jsx: "react",
   svelte: "svelte",
@@ -48,6 +53,9 @@ 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}";
 
+/** Ceiling on concurrent example-file reads; unbounded fan-out risks EMFILE. */
+const READ_CONCURRENCY = 16;
+
 // 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.
@@ -58,7 +66,7 @@ const GLOB_MAGIC = /[!*?[\]{}]/u;
  * 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 splitGlobBase = (pattern: string) => {
   const segments = pattern.split("/");
   // Only called when the pattern contains glob magic (see the caller), and `/`
   // is never magic, so the magic char always lands in a segment — `findIndex`
@@ -102,9 +110,9 @@ export const discoverExamples = async (
     onlyFiles: true,
   });
   const files = matches.toSorted();
-  const sources = await Promise.all(
-    files.map((file) => readFile(file, "utf-8"))
-  );
+  const sources = await pMap(files, (file) => readFile(file, "utf-8"), {
+    concurrency: READ_CONCURRENCY,
+  });
 
   const examples: ExampleSpec[] = [];
   const warnings: string[] = [];

package/src/astro/generate.ts

@@ -12,11 +12,13 @@ import {
 import { createRequire } from "node:module";
 import { pathToFileURL } from "node:url";
 
+import { imageSize } from "image-size";
+import pMap from "p-map";
 import { basename, dirname, join, normalize, relative, resolve } from "pathe";
 import { glob } from "tinyglobby";
 
 import { buildAskData } from "../ai/ask-data.ts";
-import { resolveAskBackend } from "../ai/ask.ts";
+import { askBackendRuntimeDep, resolveAskBackend } from "../ai/ask.ts";
 import { buildRawMarkdown, markdownRoutePaths } from "../ai/markdown.ts";
 import { buildMcpData } from "../ai/mcp/data.ts";
 import { buildMcpDiscovery, buildMcpServerCard } from "../ai/mcp/discovery.ts";
@@ -487,12 +489,14 @@ export const ensureDepsLink = async (
  * (`<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()
-): {
+export interface PrerenderDepsPlugin {
   name: string;
   writeBundle: (options: { dir?: string }) => Promise<void>;
-} => ({
+}
+
+export const prerenderDepsPlugin = (
+  pkgDir: string = packageRoot()
+): PrerenderDepsPlugin => ({
   name: "blume:prerender-deps",
   writeBundle: async (options) => {
     if (!options.dir || basename(options.dir) !== ".prerender") {
@@ -526,14 +530,16 @@ interface ServerAppResolveContext {
  * Stripping the spurious `.js` and delegating back to Astro's resolver lets the
  * reload complete cleanly, so the renamed route resolves without a restart.
  */
-export const serverAppResolvePlugin = (): {
+export interface ServerAppResolvePlugin {
   enforce: "pre";
   name: string;
   resolveId: (
     this: ServerAppResolveContext,
     id: string
   ) => Promise<string | null>;
-} => ({
+}
+
+export const serverAppResolvePlugin = (): ServerAppResolvePlugin => ({
   enforce: "pre",
   name: "blume:server-app-resolve",
   async resolveId(id) {
@@ -546,20 +552,20 @@ export const serverAppResolvePlugin = (): {
 });
 
 /** Astro integration package each non-React island framework needs installed. */
-const ISLAND_FRAMEWORK_DEPS: Record<string, string> = {
-  svelte: "@astrojs/svelte",
-  vue: "@astrojs/vue",
-};
+const ISLAND_FRAMEWORK_DEPS = new Map([
+  ["svelte", "@astrojs/svelte"],
+  ["vue", "@astrojs/vue"],
+]);
 
 /**
  * Adapter package the project must install itself for each deployment
  * platform whose adapter Blume doesn't ship. Node and Vercel ship with Blume,
  * so they never need this.
  */
-const DEPLOYMENT_ADAPTER_DEPS: Record<string, string> = {
-  cloudflare: "@astrojs/cloudflare",
-  netlify: "@astrojs/netlify",
-};
+const DEPLOYMENT_ADAPTER_DEPS = new Map([
+  ["cloudflare", "@astrojs/cloudflare"],
+  ["netlify", "@astrojs/netlify"],
+]);
 
 /**
  * Warn when a Vue/Svelte island is present but its Astro integration isn't
@@ -572,7 +578,7 @@ const islandFrameworkWarnings = (
 ): string[] => {
   const warnings: string[] = [];
   for (const framework of frameworks) {
-    const dep = ISLAND_FRAMEWORK_DEPS[framework];
+    const dep = ISLAND_FRAMEWORK_DEPS.get(framework);
     if (dep && !canResolveFrom(root, dep)) {
       warnings.push(
         `Islands use ${framework}, which needs "${dep}". Install it (e.g. \`npm install ${dep} ${framework}\`).`
@@ -597,7 +603,7 @@ const deploymentAdapterWarnings = (
 ): string[] => {
   const dep =
     deployment.output === "server" && deployment.adapter
-      ? DEPLOYMENT_ADAPTER_DEPS[deployment.adapter]
+      ? DEPLOYMENT_ADAPTER_DEPS.get(deployment.adapter)
       : undefined;
   if (
     dep &&
@@ -638,6 +644,33 @@ export const searchProviderWarnings = (
   return warnings;
 };
 
+/**
+ * Warn when the Ask AI backend's provider SDK is missing. Like search provider
+ * SDKs, these are optional peers the project must install (only `gateway`
+ * needs nothing beyond the core `ai` package Blume ships) — warn early with
+ * the package name rather than let Vite fail to resolve the import opaquely.
+ * Same resolution rule as {@link searchProviderWarnings}: available if the
+ * project installed it or Blume can resolve it. `pkgDir` is injectable for
+ * testing.
+ */
+export const askProviderWarnings = (
+  ask: ResolvedConfig["ai"]["ask"],
+  root: string,
+  pkgDir: string = packageRoot()
+): string[] => {
+  // An external `endpoint` means no generated route, so no SDK is imported.
+  if (!ask?.enabled || ask.endpoint) {
+    return [];
+  }
+  const dep = askBackendRuntimeDep(ask);
+  if (!dep || canResolveFrom(root, dep) || canResolveFrom(pkgDir, dep)) {
+    return [];
+  }
+  return [
+    `Ask AI provider "${ask.provider}" needs "${dep}", which isn't installed. Run \`npm install ${dep}\` (or your package manager's equivalent).`,
+  ];
+};
+
 /** Absolute path to the configured `examples.css`, or null when unset. */
 const examplesCssFile = (
   root: string,
@@ -708,6 +741,9 @@ export const detectNeedsReact = async (root: string): Promise<boolean> => {
 const containsMath = (content: string): boolean =>
   content.includes("$$") || content.includes("<Math");
 
+/** Ceiling on concurrent content-file reads; unbounded fan-out risks EMFILE. */
+const READ_CONCURRENCY = 16;
+
 /**
  * Detect whether the project can render math: block math (`$$…$$`) or an
  * explicit `<Math>` tag in any local `.md`/`.mdx`, or in staged (non-filesystem)
@@ -726,9 +762,9 @@ export const detectUsesMath = async (
     ignore: ["**/node_modules/**", "**/.blume/**", "**/dist/**"],
     onlyFiles: true,
   });
-  const contents = await Promise.all(
-    files.map((file) => readOptional(join(root, file)))
-  );
+  const contents = await pMap(files, (file) => readOptional(join(root, file)), {
+    concurrency: READ_CONCURRENCY,
+  });
   return [...contents, ...staged].some(containsMath);
 };
 
@@ -838,33 +874,24 @@ interface LogoDimensions {
   width: number;
 }
 
-const SVG_ROOT = /<svg\b(?<attributes>[^>]*)>/u;
-const SVG_WIDTH = /\bwidth\s*=\s*["'](?<value>[^"']+)["']/u;
-const SVG_HEIGHT = /\bheight\s*=\s*["'](?<value>[^"']+)["']/u;
-const SVG_LENGTH = /^\s*(?<value>[\d.]+)(?:px)?\s*$/u;
-const SVG_VIEW_BOX =
-  /\bviewBox\s*=\s*["'][\d.-]+[\s,]+[\d.-]+[\s,]+(?<width>[\d.]+)[\s,]+(?<height>[\d.]+)["']/u;
-
-const parseSvgLength = (value: string | undefined): number | undefined => {
-  const length = Number(value?.match(SVG_LENGTH)?.groups?.value);
-  return length > 0 ? length : undefined;
-};
-
-/** Read dimensions from an SVG's explicit size or its view box. */
+/**
+ * Read dimensions from an SVG's explicit size or its view box. Measured with
+ * image-size — the same parser og/card.ts uses for the OG brand mark, so the
+ * header and the card can't disagree about one logo — which also tolerates
+ * the spellings the old regex missed (unquoted values, `em`/`pt` lengths, a
+ * `>` inside another attribute). An SVG with no usable size returns partial
+ * dimensions or throws; both collapse to undefined.
+ */
 const svgDimensions = (svg: string | undefined): LogoDimensions | undefined => {
-  const attributes = svg?.match(SVG_ROOT)?.groups?.attributes;
-  const width = parseSvgLength(attributes?.match(SVG_WIDTH)?.groups?.value);
-  const height = parseSvgLength(attributes?.match(SVG_HEIGHT)?.groups?.value);
-  if (width && height) {
-    return { height, width };
+  if (!svg) {
+    return;
+  }
+  try {
+    const { height, width } = imageSize(Buffer.from(svg));
+    return height && width ? { height, width } : undefined;
+  } catch {
+    return undefined;
   }
-
-  const viewBox = attributes?.match(SVG_VIEW_BOX);
-  const viewBoxWidth = Number(viewBox?.groups?.width);
-  const viewBoxHeight = Number(viewBox?.groups?.height);
-  return viewBoxWidth > 0 && viewBoxHeight > 0
-    ? { height: viewBoxHeight, width: viewBoxWidth }
-    : undefined;
 };
 
 /** Read a local SVG logo from the project root or public directory. */
@@ -883,6 +910,10 @@ const readLogoSvg = (
   return file ? readFileSync(file, "utf-8") : undefined;
 };
 
+/** Narrows a config union's string shorthand from its object form. */
+const isStringShorthand = <T>(value: T | string): value is string =>
+  typeof value === "string";
+
 /**
  * Resolve the configured logo. A single SVG is read and inlined so a
  * `currentColor` logo follows the theme; other images keep their URL for an
@@ -893,12 +924,12 @@ const resolveLogo = (project: BlumeProject): BlumeLogo | null => {
   if (!logo) {
     return null;
   }
-  const config = typeof logo === "string" ? { image: logo } : logo;
+  const config = isStringShorthand(logo) ? { image: logo } : logo;
   // `text` is passed through verbatim: `undefined` lets the brand fall back to
   // the site title, `""` renders the mark alone (a logo with the wordmark baked
   // in).
   const { href, image: source, text } = config;
-  const image = typeof source === "string" ? { light: source } : source;
+  const image = isStringShorthand(source) ? { light: source } : source;
   const light = image?.light ?? image?.dark;
   const dark = image?.dark ?? image?.light;
   const alt = image?.alt ?? "";
@@ -934,18 +965,18 @@ const FAVICON_CANDIDATES = [
 ];
 
 /** `<link type>` MIME for the favicon extensions we recognize. */
-const FAVICON_TYPES: Record<string, string> = {
-  ico: "image/x-icon",
-  jpeg: "image/jpeg",
-  jpg: "image/jpeg",
-  png: "image/png",
-  svg: "image/svg+xml",
-};
+const FAVICON_TYPES = new Map([
+  ["ico", "image/x-icon"],
+  ["jpeg", "image/jpeg"],
+  ["jpg", "image/jpeg"],
+  ["png", "image/png"],
+  ["svg", "image/svg+xml"],
+]);
 
 /** Infer the `<link type>` MIME from a filename, when we recognize the extension. */
 const faviconType = (name: string): string | undefined => {
   const ext = name.split(".").pop()?.toLowerCase();
-  return ext ? FAVICON_TYPES[ext] : undefined;
+  return ext ? FAVICON_TYPES.get(ext) : undefined;
 };
 
 /** Read a file and encode it as a `data:` URI of the given MIME type. */
@@ -1018,7 +1049,7 @@ const resolveBanner = (config: ResolvedConfig): BlumeBanner | null => {
   if (!banner) {
     return null;
   }
-  if (typeof banner === "string") {
+  if (isStringShorthand(banner)) {
     return { content: banner, dismissible: false, key: banner };
   }
   return {
@@ -1211,6 +1242,7 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       theme: config.theme,
       title: config.title,
       toc: config.toc,
+      versions: config.versions ?? null,
       webmcp: {
         enabled: config.ai.webmcp,
         llms: config.ai.llmsTxt.enabled,
@@ -1227,6 +1259,19 @@ export const buildRuntimeData = (project: BlumeProject): string => {
     navigation: withRepoUrl(graph.navigation),
     // Per-locale navigation; the catch-all selects the active locale's tree.
     navigationByLocale,
+    // Per-archived-version navigation; the catch-all selects by the route's
+    // version, then locale.
+    navigationByVersion: Object.fromEntries(
+      Object.entries(graph.navigationByVersion).map(([id, byLocale]) => [
+        id,
+        Object.fromEntries(
+          Object.entries(byLocale).map(([code, nav]) => [
+            code,
+            withRepoUrl(nav),
+          ])
+        ),
+      ])
+    ),
     routes: manifest.routes.map((route) => ({
       alternates: route.alternates,
       collection: route.collection,
@@ -1241,6 +1286,8 @@ export const buildRuntimeData = (project: BlumeProject): string => {
       locale: route.locale,
       path: route.path,
       title: route.title,
+      version: route.version,
+      versionAlternates: route.versionAlternates,
     })),
     // Default-locale chrome strings (English baseline when not under i18n).
     ui: defaultUi,
@@ -1370,7 +1417,7 @@ const writeAskFiles = async (
   }
   await write(
     join(srcDir, "pages", "api", "ask.ts"),
-    askEndpointTemplate(resolveAskBackend(ask), grounded)
+    askEndpointTemplate(resolveAskBackend(ask), grounded, ask.instructions)
   );
 };
 
@@ -1838,8 +1885,9 @@ export const generateRuntime = async (
     ]);
   }
 
-  // API/AsyncAPI reference pages (Scalar). One self-contained page per source,
-  // mounted on its configured route and regenerated each run.
+  // Scalar-rendered API/AsyncAPI reference pages (`renderer: "scalar"`). One
+  // self-contained page per source, mounted on its configured route and
+  // regenerated each run.
   const warnings: string[] = [
     ...(depsLinkWarning ? [depsLinkWarning] : []),
     ...reactCompilerWarnings(config, needsReact, reactCompilerPath),
@@ -1878,10 +1926,11 @@ export const generateRuntime = async (
     ...islandDiscovery.islands.map((island) => island.name),
     ...overrideTags,
   ]);
-  // Missing-dependency preflights: the search provider's SDK, the deployment
-  // adapter's package, and — since React ships with Blume while Vue/Svelte
-  // don't — any island framework's Astro integration. Warn early rather than
-  // let Vite fail to resolve them opaquely.
+  // Missing-dependency preflights: the search provider's SDK, the Ask AI
+  // backend's provider SDK, the deployment adapter's package, and — since
+  // React ships with Blume while Vue/Svelte don't — any island framework's
+  // Astro integration. Warn early rather than let Vite fail to resolve them
+  // opaquely.
   warnings.push(
     ...validateUsedComponents(
       project.graph.pages,
@@ -1889,6 +1938,7 @@ export const generateRuntime = async (
       new Set(registry.map((item) => item.name))
     ).map(diagnosticWarning),
     ...searchProviderWarnings(config.search.provider, context.root),
+    ...askProviderWarnings(config.ai.ask, context.root),
     ...deploymentAdapterWarnings(config.deployment, context.root),
     ...islandFrameworkWarnings(frameworks, context.root)
   );

package/src/astro/integration.ts

@@ -6,9 +6,20 @@ import { enrichDiagnostic } from "../core/diagnostics.ts";
 import type { Diagnostic } from "../core/types.ts";
 import { markdownVariantUrl, prefersMarkdown } from "./markdown-negotiation.ts";
 
+/** The `{ type: "error" }` payload Vite's browser overlay renders. */
+interface OverlayErrorPayload {
+  err: {
+    id?: string;
+    message: string;
+    plugin: string;
+    stack: string;
+  };
+  type: "error";
+}
+
 /** The dev server's HMR channel — either `.ws` (Vite ≤5) or `.hot` (Vite 6+). */
 interface OverlayChannel {
-  send: (payload: unknown) => void;
+  send: (payload: OverlayErrorPayload) => void;
 }
 interface OverlayServer {
   hot?: OverlayChannel;
@@ -164,7 +175,7 @@ export const blumeIntegration = (
     "astro:server:setup": ({ server }) => {
       // Keep a handle on the dev server so Blume diagnostics can be pushed to
       // its browser error overlay (see `showBlumeErrorOverlay`).
-      overlayServer = server as unknown as OverlayServer;
+      overlayServer = 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({

package/src/astro/islands.ts

@@ -1,5 +1,6 @@
 import { readFile } from "node:fs/promises";
 
+import pMap from "p-map";
 import { basename, join } from "pathe";
 import { glob } from "tinyglobby";
 
@@ -29,6 +30,9 @@ export interface IslandDiscovery {
 /** Hydration mode used when an island doesn't declare one. */
 const DEFAULT_CLIENT: IslandClientMode = "visible";
 
+/** Ceiling on concurrent island-file reads; unbounded fan-out risks EMFILE. */
+const READ_CONCURRENCY = 16;
+
 const VALID_MODES = new Set<IslandClientMode>([
   "idle",
   "load",
@@ -36,13 +40,20 @@ const VALID_MODES = new Set<IslandClientMode>([
   "visible",
 ]);
 
+/** Whether a declared client mode is one Astro's directives support. */
+const isClientMode = (mode: string): mode is IslandClientMode =>
+  // SAFETY: `Set.has` only compares identity at runtime; the assertion widens
+  // the lookup key so the narrower-typed set accepts it, and the `has` result
+  // is exactly the predicate being claimed.
+  VALID_MODES.has(mode as IslandClientMode);
+
 /** 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",
-};
+const FRAMEWORK_BY_EXT = new Map<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.
@@ -62,13 +73,13 @@ export const readClientMode = (
   if (!mode) {
     return DEFAULT_CLIENT;
   }
-  if (!VALID_MODES.has(mode as IslandClientMode)) {
+  if (!isClientMode(mode)) {
     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;
+  return mode;
 };
 
 /**
@@ -92,9 +103,9 @@ export const discoverIslands = async (
     onlyFiles: true,
   });
   const files = matches.toSorted();
-  const sources = await Promise.all(
-    files.map((file) => readFile(file, "utf-8"))
-  );
+  const sources = await pMap(files, (file) => readFile(file, "utf-8"), {
+    concurrency: READ_CONCURRENCY,
+  });
 
   const islands: IslandSpec[] = [];
   const warnings: string[] = [];
@@ -105,7 +116,7 @@ export const discoverIslands = async (
   const collectIsland = (file: string, source: string): void => {
     const base = basename(file);
     const ext = base.match(ISLAND_FILE)?.groups?.ext;
-    const framework = ext ? FRAMEWORK_BY_EXT[ext] : undefined;
+    const framework = ext ? FRAMEWORK_BY_EXT.get(ext) : undefined;
     if (!framework) {
       return;
     }