blume 1.0.0 → 1.0.2

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

@@ -0,0 +1,16 @@
+/**
+ * Single-character trimming, done without regular expressions.
+ *
+ * The obvious spellings — `/^\/+/`, `/\/+$/`, `/^\/+|\/+$/g` — take quadratic
+ * time on a run of the trimmed character, because a failed match at one start
+ * position tells the engine nothing about the next one. Every caller here trims
+ * a value that comes from outside Blume (a configured route, a spec URL, a site
+ * origin), so the slow path is reachable from user input rather than only from
+ * our own literals. These loops are linear and allocation-free.
+ */
+/** Drop every leading `char` (`"///a"` -> `"a"` for `"/"`). */
+export declare const trimStart: (text: string, char: string) => string;
+/** Drop every trailing `char` (`"a///"` -> `"a"` for `"/"`). */
+export declare const trimEnd: (text: string, char: string) => string;
+/** Drop every leading *and* trailing `char` (`"///a///"` -> `"a"`). */
+export declare const trimChar: (text: string, char: string) => string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "blume",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Documentation that's fast, AI-ready, and zero-config.",
   "keywords": [
     "astro",
@@ -22,7 +22,7 @@
     "directory": "packages/blume"
   },
   "bin": {
-    "blume": "./bin/blume.mjs"
+    "blume": "bin/blume.mjs"
   },
   "files": [
     "dist",

package/src/ai/mcp/discovery.ts

@@ -1,4 +1,5 @@
 import { withBasePath } from "../../core/base-path.ts";
+import { trimEnd } from "../../core/trim.ts";
 import { MCP_TOOLS } from "./tools.ts";
 
 /** Inputs needed to describe the MCP server in discovery documents. */
@@ -18,7 +19,7 @@ const serverUrl = (input: McpDiscoveryInput): string => {
   const path = withBasePath(input.base, input.route);
   // Concatenate rather than `new URL(path, site)` — a root-absolute path
   // would drop the base path of a subpath deployment (`acme.com/docs`).
-  return input.site ? `${input.site.replace(/\/+$/u, "")}${path}` : path;
+  return input.site ? `${trimEnd(input.site, "/")}${path}` : path;
 };
 
 /**

package/src/astro/templates.ts

@@ -8,6 +8,7 @@ import type { AskBackend } from "../ai/ask.ts";
 import { normalizeBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
 import { BLUME_IGNORE_DIRS } from "../core/sources/watch.ts";
+import { trimChar } from "../core/trim.ts";
 import type { ProjectContext } from "../core/types.ts";
 import { applyBaseToRedirects } from "../deploy/redirects.ts";
 import { hasScalarReferences } from "../openapi/references.ts";
@@ -879,10 +880,8 @@ export function GET({ props }) {
 `;
 
 /** The `src/pages` file that serves a route, e.g. `/mcp` -> `mcp.ts`. */
-export const mcpPageFile = (route: string): string => {
-  const clean = route.replace(/^\/+/u, "").replace(/\/+$/u, "");
-  return `${clean}.ts`;
-};
+export const mcpPageFile = (route: string): string =>
+  `${trimChar(route, "/")}.ts`;
 
 /**
  * Generate the hosted MCP server endpoint (e.g. `.blume/src/pages/mcp.ts`). A
@@ -891,7 +890,7 @@ export const mcpPageFile = (route: string): string => {
  * the docs over Streamable HTTP.
  */
 export const mcpEndpointTemplate = (route: string): string => {
-  const clean = route.replace(/^\/+/u, "").replace(/\/+$/u, "");
+  const clean = trimChar(route, "/");
   const up = "../".repeat(clean.split("/").length);
   return `// Generated by Blume. Do not edit.
 import type { APIRoute } from "astro";

package/src/components/layout/PageLayout.astro

@@ -37,7 +37,7 @@ import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
-import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
+import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
 import { isUnderPath } from "./nav-utils.ts";
 
@@ -169,10 +169,7 @@ const twitterCard = resolvedOgImage ? "summary_large_image" : "summary";
 const xSite = normalizeXHandle(x?.handle);
 const xCreator = normalizeXHandle(x?.creator);
 
-const initialThemeScript = themeInitScript(themeMode);
-const bannerScript = banner?.dismissible
-  ? bannerInitScript(banner.key)
-  : null;
+const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
 <!doctype html>
@@ -216,8 +213,12 @@ const bannerScript = banner?.dismissible
     {description && <meta content={description} name="twitter:description" />}
     {xSite && <meta content={xSite} name="twitter:site" />}
     {xCreator && <meta content={xCreator} name="twitter:creator" />}
-    {bannerScript && <script is:inline set:html={bannerScript} />}
-    <script is:inline set:html={initialThemeScript} />
+    {
+      bannerKey && (
+        <script data-key={bannerKey} is:inline set:html={BANNER_INIT_SCRIPT} />
+      )
+    }
+    <script data-mode={themeMode} is:inline set:html={THEME_INIT_SCRIPT} />
     <Analytics analytics={analytics} />
   </head>
   <body class="bg-background font-sans text-foreground antialiased">

package/src/components/layout/ReferenceLayout.astro

@@ -7,6 +7,7 @@ import Analytics from "./Analytics.astro";
 import Banner from "./Banner.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
+import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
 
 // A minimal shell for the Scalar API/AsyncAPI reference: Blume's banner + navbar
@@ -80,14 +81,7 @@ const {
 
 const strings = ui ?? EN_UI;
 
-// Set the theme before paint so the navbar never flashes the wrong colors
-// (mirrors RootLayout's pre-paint script).
-const initialThemeScript = `(()=>{const m=${JSON.stringify(themeMode)};const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);})();`;
-
-// Pre-paint: hide a previously-dismissed banner before it flashes in.
-const bannerScript = banner?.dismissible
-  ? `(()=>{if(localStorage.getItem("blume-banner:"+${JSON.stringify(banner.key)}))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`
-  : null;
+const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
 <!doctype html>
@@ -98,8 +92,12 @@ const bannerScript = banner?.dismissible
     <title>{pageTitle}</title>
     <Favicon favicon={favicon} appleIcon={appleIcon} />
     <Fonts cssVars={fontCssVars ?? []} />
-    {bannerScript && <script is:inline set:html={bannerScript} />}
-    <script is:inline set:html={initialThemeScript} />
+    {
+      bannerKey && (
+        <script data-key={bannerKey} is:inline set:html={BANNER_INIT_SCRIPT} />
+      )
+    }
+    <script data-mode={themeMode} is:inline set:html={THEME_INIT_SCRIPT} />
     <Analytics analytics={analytics} />
   </head>
   <body class="bg-background font-sans text-foreground antialiased">

package/src/components/layout/RootLayout.astro

@@ -23,7 +23,7 @@ import Breadcrumbs from "./Breadcrumbs.astro";
 import Empty from "./Empty.astro";
 import Favicon from "./Favicon.astro";
 import Fonts from "./Fonts.astro";
-import { bannerInitScript, themeInitScript } from "./head-scripts.ts";
+import { BANNER_INIT_SCRIPT, THEME_INIT_SCRIPT } from "./head-scripts.ts";
 import Header from "./Header.astro";
 import Icon from "../Icon.astro";
 import {
@@ -329,10 +329,7 @@ const structuredDataJson = structuredData
   ? JSON.stringify(structuredData).replaceAll("<", "\\u003c")
   : null;
 
-const initialThemeScript = themeInitScript(themeMode);
-const bannerScript = banner?.dismissible
-  ? bannerInitScript(banner.key)
-  : null;
+const bannerKey = banner?.dismissible ? banner.key : null;
 ---
 
 <!doctype html>
@@ -411,8 +408,12 @@ const bannerScript = banner?.dismissible
         />
       )
     }
-    {bannerScript && <script is:inline set:html={bannerScript} />}
-    <script is:inline set:html={initialThemeScript} />
+    {
+      bannerKey && (
+        <script data-key={bannerKey} is:inline set:html={BANNER_INIT_SCRIPT} />
+      )
+    }
+    <script data-mode={themeMode} is:inline set:html={THEME_INIT_SCRIPT} />
     <Analytics analytics={analytics} />
   </head>
   <body

package/src/components/layout/head-scripts.ts

@@ -1,19 +1,29 @@
 /**
  * Pre-paint inline scripts shared by the document layouts (`RootLayout`,
- * `SplashLayout`). They run synchronously in `<head>`, before first paint, so
- * the page never flashes the wrong theme or a since-dismissed banner. Kept in
- * one place so the two layouts can't drift on this timing-critical logic.
+ * `PageLayout`, `ReferenceLayout`). They run synchronously in `<head>`, before
+ * first paint, so the page never flashes the wrong theme or a since-dismissed
+ * banner. Kept in one place so the layouts can't drift on this timing-critical
+ * logic.
+ *
+ * Both are constants, never built by interpolating config into source text: the
+ * values they need ride in as `data-*` attributes on the script tag and are read
+ * back through `document.currentScript`. Baking a config string into JS — even
+ * via `JSON.stringify` — is code construction, and JSON escaping does not cover
+ * a script context (`</script>`, U+2028/U+2029 all survive it). Attributes are
+ * HTML-escaped by Astro, so the value can never be parsed as code.
  */
 
 /**
  * Set `data-theme` from the stored preference (or the configured default, or the
  * OS setting for `"system"`) before the body paints, avoiding a theme flash.
+ *
+ * Reads `data-mode` — `"system" | "light" | "dark"`.
  */
-export const themeInitScript = (
-  themeMode: "system" | "light" | "dark"
-): string =>
-  `(()=>{const m=${JSON.stringify(themeMode)};const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);})();`;
+export const THEME_INIT_SCRIPT = `(()=>{const m=document.currentScript?.dataset.mode??"system";const s=localStorage.getItem("blume-theme");const sys=matchMedia("(prefers-color-scheme: dark)").matches?"dark":"light";document.documentElement.dataset.theme=s??(m==="system"?sys:m);})();`;
 
-/** Hide a previously-dismissed banner before it can flash in. */
-export const bannerInitScript = (key: string): string =>
-  `(()=>{if(localStorage.getItem("blume-banner:"+${JSON.stringify(key)}))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`;
+/**
+ * Hide a previously-dismissed banner before it can flash in.
+ *
+ * Reads `data-key` — the banner's dismissal key.
+ */
+export const BANNER_INIT_SCRIPT = `(()=>{const k=document.currentScript?.dataset.key;if(k&&localStorage.getItem("blume-banner:"+k))document.documentElement.setAttribute("data-blume-banner-hidden","");})();`;

package/src/core/base-path.ts

@@ -21,10 +21,10 @@ export const normalizeBasePath = (input?: string): string => {
   if (!input) {
     return "";
   }
-  const trimmed = input
-    .trim()
-    .replaceAll(/^\/+|\/+$/gu, "")
-    .replaceAll(/\/{2,}/gu, "/");
+  // Splitting on "/" and dropping the empty parts trims the edges and collapses
+  // inner runs in one linear pass; the regex spellings of both are quadratic on
+  // a long run of slashes (see `core/trim.ts`).
+  const trimmed = input.trim().split("/").filter(Boolean).join("/");
   return trimmed === "" ? "" : `/${trimmed}`;
 };
 

package/src/core/trim.ts

@@ -0,0 +1,32 @@
+/**
+ * Single-character trimming, done without regular expressions.
+ *
+ * The obvious spellings — `/^\/+/`, `/\/+$/`, `/^\/+|\/+$/g` — take quadratic
+ * time on a run of the trimmed character, because a failed match at one start
+ * position tells the engine nothing about the next one. Every caller here trims
+ * a value that comes from outside Blume (a configured route, a spec URL, a site
+ * origin), so the slow path is reachable from user input rather than only from
+ * our own literals. These loops are linear and allocation-free.
+ */
+
+/** Drop every leading `char` (`"///a"` -> `"a"` for `"/"`). */
+export const trimStart = (text: string, char: string): string => {
+  let start = 0;
+  while (start < text.length && text[start] === char) {
+    start += 1;
+  }
+  return text.slice(start);
+};
+
+/** Drop every trailing `char` (`"a///"` -> `"a"` for `"/"`). */
+export const trimEnd = (text: string, char: string): string => {
+  let end = text.length;
+  while (end > 0 && text[end - 1] === char) {
+    end -= 1;
+  }
+  return text.slice(0, end);
+};
+
+/** Drop every leading *and* trailing `char` (`"///a///"` -> `"a"`). */
+export const trimChar = (text: string, char: string): string =>
+  trimEnd(trimStart(text, char), char);

package/src/openapi/references.ts

@@ -1,5 +1,6 @@
 import { withBasePath } from "../core/base-path.ts";
 import type { ResolvedConfig } from "../core/schema.ts";
+import { trimChar, trimEnd } from "../core/trim.ts";
 import type { NavTab } from "../core/types.ts";
 
 /**
@@ -52,24 +53,21 @@ export interface ReferenceSource {
 }
 
 const NON_SLUG = /[^a-z0-9]+/gu;
-const SLUG_EDGES = /^-+|-+$/gu;
-const ROUTE_EDGES = /^\/+|\/+$/gu;
-const TRAILING_SLASH = /\/+$/u;
 
 export const slugify = (text: string): string =>
-  text.toLowerCase().replace(NON_SLUG, "-").replace(SLUG_EDGES, "");
+  trimChar(text.toLowerCase().replace(NON_SLUG, "-"), "-");
 
 /** Normalize a configured route to a single leading slash, no trailing slash. */
 export const normalizeRoute = (route: string): string => {
   const trimmed = route.trim();
   const withSlash = trimmed.startsWith("/") ? trimmed : `/${trimmed}`;
-  const noTrailing = withSlash.replace(TRAILING_SLASH, "");
+  const noTrailing = trimEnd(withSlash, "/");
   return noTrailing === "" ? "/" : noTrailing;
 };
 
 /** A stable per-reference token from its route: `/api/events` -> `api-events`. */
 const routeSlug = (route: string): string =>
-  slugify(route.replace(ROUTE_EDGES, "")) || "reference";
+  slugify(trimChar(route, "/")) || "reference";
 
 type Block = ResolvedConfig["openapi"] | ResolvedConfig["asyncapi"];