@docubook/flame 1.3.3 → 1.3.5

package/.docu/node/build.ts

@@ -112,8 +112,8 @@ async function renderDocsPage(
     });
   }
 
-  const title = (frontmatter.title as string) || slug || "Docs";
-  const description = (frontmatter.description as string) || "";
+  const title = (typeof frontmatter.title === "string" ? frontmatter.title : "") || slug || "Docs";
+  const description = typeof frontmatter.description === "string" ? frontmatter.description : "";
   const slugParts = slug ? slug.split("/") : [];
 
   const page = React.createElement(

package/.docu/node/plugin-builder.ts

@@ -52,11 +52,7 @@ export class BuildPluginBuilder implements PluginBuilder {
       try {
         const result = cb(context);
         if (result) {
-          if (Array.isArray(result)) {
-            items.push(...result);
-          } else {
-            items.push(result);
-          }
+          this.collectItems(items, result, "injectBody");
         }
       } catch (err) {
         throw new Error(
@@ -83,11 +79,7 @@ export class BuildPluginBuilder implements PluginBuilder {
       try {
         const result = cb(context);
         if (result) {
-          if (Array.isArray(result)) {
-            items.push(...result);
-          } else {
-            items.push(result);
-          }
+          this.collectItems(items, result, "injectHead");
         }
       } catch (err) {
         throw new Error(
@@ -373,6 +365,8 @@ export class BuildPluginBuilder implements PluginBuilder {
    * Each callback receives the **previous** callback's return value (or the
    * original frontmatter for the first). Callbacks that return `undefined` or
    * `null` pass the current value through unchanged.
+   * Callbacks that return a non-object (string, number, array) are skipped
+   * with a console warning — only plain objects are accepted.
    * Errors inside individual callbacks are caught and logged — the current
    * frontmatter passes through unchanged for that step.
    *
@@ -389,7 +383,13 @@ export class BuildPluginBuilder implements PluginBuilder {
       try {
         const next = await this._transformFrontmatter[i](result, context);
         if (next !== undefined && next !== null) {
-          result = next;
+          if (typeof next === "object" && !Array.isArray(next)) {
+            result = next;
+          } else {
+            console.warn(
+              `[plugin] transformFrontmatter callback #${i + 1} returned invalid type (expected a plain object), skipping`
+            );
+          }
         }
       } catch (err) {
         console.error(
@@ -430,6 +430,10 @@ export class BuildPluginBuilder implements PluginBuilder {
    * Callbacks are chained in a waterfall: the return value of one is passed
    * as input to the next. Return `undefined` to pass through unchanged.
    *
+   * **Note:** Only plain objects are accepted as return values. Returning
+   * a string, number, or array will be silently skipped with a warning.
+   * Plugin authors should validate their return values before returning.
+   *
    * @param callback - Receives frontmatter object and page context.
    *
    * @example
@@ -462,4 +466,28 @@ export class BuildPluginBuilder implements PluginBuilder {
   transformHtml(callback: (html: string, context: PageContext) => Awaitable<string>): void {
     this._transformHtml.push(callback);
   }
+
+  /**
+   * Collect items from a callback result, filtering only valid strings.
+   * Non-string items and unexpected types are logged as warnings.
+   */
+  private collectItems(items: string[], result: string | string[], hookName: string): void {
+    if (Array.isArray(result)) {
+      for (const item of result) {
+        if (typeof item === "string") {
+          items.push(item);
+        } else {
+          console.warn(
+            `[plugin] ${hookName} callback returned non-string item (got ${typeof item}), skipping`
+          );
+        }
+      }
+    } else if (typeof result === "string") {
+      items.push(result);
+    } else {
+      console.warn(
+        `[plugin] ${hookName} callback returned unexpected type (got ${typeof result}), expected string or string[], skipping`
+      );
+    }
+  }
 }

package/.docu/node/plugin.ts

@@ -167,6 +167,9 @@ export interface PluginBuilder {
    * Register a callback that returns HTML strings to inject inside `<head>`.
    * Results from all plugins are merged and deduplicated.
    *
+   * ⚠️ Sanitize any user-controlled or external data before injecting.
+   * Plugin-provided strings are injected raw into the final HTML.
+   *
    * Use for: analytics snippets, meta tags, stylesheet links.
    *
    * @param callback - Returns a single HTML string or an array. Called once per page.
@@ -182,6 +185,9 @@ export interface PluginBuilder {
    * Register a callback that returns HTML strings to inject before `</body>`.
    * Results from all plugins are merged and deduplicated.
    *
+   * ⚠️ Sanitize any user-controlled or external data before injecting.
+   * Plugin-provided strings are injected raw into the final HTML.
+   *
    * Use for: chat widgets, live-script loaders, deferred scripts.
    *
    * @param callback - Returns a single HTML string or an array. Called once per page.

package/.docu/node/server-routes.ts

@@ -121,8 +121,12 @@ async function renderDocsServerPage(
   pathname: string,
   state: ServerState
 ): Promise<Response> {
-  const title = (doc.frontmatter.title as string) || slug.join("/") || "Docs";
-  const description = (doc.frontmatter.description as string) || "";
+  const title =
+    (typeof doc.frontmatter.title === "string" ? doc.frontmatter.title : "") ||
+    slug.join("/") ||
+    "Docs";
+  const description =
+    typeof doc.frontmatter.description === "string" ? doc.frontmatter.description : "";
 
   const page = React.createElement(
     DocsLayout,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docubook/flame",
-  "version": "1.3.3",
+  "version": "1.3.5",
   "description": "A blazing-fast React + MDX framework powered by Bun, built for modern documentation experiences.",
   "type": "module",
   "bin": {
@@ -53,9 +53,9 @@
     "react-dom": "^19.2.7",
     "unified": "^11.0.0",
     "@docubook/core": "^1.7.2",
-    "@docubook/mdx-content": "^3.2.2",
     "@docubook/themes-colors": "^0.10.2",
-    "@docubook/ui-react": "^0.1.4"
+    "@docubook/ui-react": "^0.1.4",
+    "@docubook/mdx-content": "^3.2.2"
   },
   "peerDependencies": {
     "@sentry/bun": "^10.0.0"