@draftbase/renderer 0.5.1 → 0.5.2

package/README.md

@@ -126,6 +126,8 @@ createReactNativeRenderer({ Text, View, Image }, { unstyled: true });
 
 This package never imports the `react-native` package itself — you pass its `Text`/`View`/`Image` in, so nothing RN-specific ends up in a web or Vue bundle.
 
+RN has no DOM to silently fall back on the way web does — a JSX component the source references but you didn't map (a typo'd custom component, a raw HTML tag RN has no native view for) would otherwise crash the whole screen. `Content` catches that automatically: it's logged via `console.error` and the raw source renders as plain text in place of the broken content, instead of taking down the app. No setup needed — this is on by default, unlike the web/Vue entry points where you wrap `Content` in `MDXErrorBoundary` yourself.
+
 ## Astro
 
 Astro components aren't React, so render through a React island. Compile server-side in the `.astro` frontmatter (Astro's runtime does allow `await` there), then hand the compiled `Content` to a small client React wrapper component:
@@ -290,6 +292,25 @@ function EntryLink({ id, children }: { id: string; children: React.ReactNode })
 <MDXContent source={entry.fields.body} components={{ EntryLink }} />;
 ```
 
+## Images
+
+A markdown image (`![alt](url)`) renders as a plain `<img loading="lazy" decoding="async">` by default — no framework-specific optimizer, so this works identically across every web/RSC/Vue target and `toHtml`. Swap in your own (e.g. Next.js's `<Image>`) by overriding `img` like any other standard element:
+
+```tsx
+import NextImage from "next/image";
+
+<MDXContent
+  source={entry.fields.body}
+  components={{
+    img: ({ src, alt }) => <NextImage src={src} alt={alt ?? ""} width={800} height={450} />,
+  }}
+/>;
+```
+
+An explicit `loading`/`decoding` written into the source (rare, but possible via raw `<img>` JSX in MDX) still wins over the default — only the no-attributes case gets the lazy default filled in.
+
+Every Draftbase asset URL — the one in an `![]()` src, or `asset.url` from `@draftbase/sdk` used outside MDX entirely — also supports on-demand resizing via query params: append `?w=800` (and/or `&h=450`) to shrink it server-side, capped to the size it was originally uploaded at (never upscales). Sizes are snapped to a fixed breakpoint set at the CDN edge, so requesting arbitrary values (`?w=803`) still hits a shared cache entry instead of minting a new one per pixel.
+
 ## Styling
 
 `@draftbase/renderer/styles.css` wraps output in a `.db-content` class with slim, sensible defaults (typography, tables, code blocks). Web-only, opt-in:
@@ -310,7 +331,7 @@ If you're an agent wiring this into a project, follow this checklist:
 2. **Pick the right entry point first** — check the target framework in the table at the top of this file, then import only that one (`@draftbase/renderer` vs `@draftbase/renderer/vue`). Importing the wrong one pulls in a peer dependency (React or Vue) the project may not have installed, and will fail to resolve.
 3. **Detect RSC support before choosing a pattern**: Next.js App Router (or another RSC framework) → use `<MDXContent source={...} />` directly, it's an async Server Component. Everything else (client-side React, React Native, Remix, Vite SPA, Vue) → use the `compileMDX(source)` + state/ref pattern shown above; do not try to `await` it inside a plain client component render.
 4. **Every `compileMDX`/`MDXContent` result is a discriminated union** — always branch on `.ok` before touching `.Content`; treat `!ok` as a real render path (show `.error` or fallback text), don't just assume success.
-5. **Non-DOM renderers (React Native, custom email/RSS pipelines) have no intrinsic HTML tags** — you must pass a `components` map covering every markdown element actually used in the source (`p`, `h1`-`h6`, `a`, `img`, `table`, ...), or those elements will fail to render. For plain HTML output (email, RSS, non-React embeds) use `toHtml` instead of a component tree.
+5. **Non-DOM renderers (React Native, custom email/RSS pipelines) have no intrinsic HTML tags** — you must pass a `components` map covering every markdown element actually used in the source (`p`, `h1`-`h6`, `a`, `img`, `table`, ...), or those elements render as an unstyled RN default (React Native's `createReactNativeRenderer` already ships styled defaults, so this mainly matters for a fully custom RN setup). React Native specifically never crashes the screen over this — an unmapped/missing component logs to `console.error` and falls back to plain text instead. For plain HTML output (email, RSS, non-React embeds) use `toHtml` instead of a component tree.
 6. **Don't hand-roll styling** — import `@draftbase/renderer/styles.css` for sensible defaults, or pass `unstyled`/`className` on `MDXContent`, rather than writing new prose/typography CSS from scratch.
 7. **This package ships zero bundled React/Vue** — both are optional peer dependencies. If the target project doesn't already have the matching framework installed, install it too or the build will fail.
 

package/dist/MDXContent.js

@@ -1,10 +1,13 @@
 import { jsx as _jsx, Fragment as _Fragment, jsxs as _jsxs } from "react/jsx-runtime";
 import * as runtime from "react/jsx-runtime";
-import { compileMDXCore, makeDefaultEntryLink } from "./core.js";
+import { compileMDXCore, makeDefaultEntryLink, makeDefaultImage } from "./core.js";
 import { wrapperClassName } from "./wrapperClassName.js";
 import { MDXErrorBoundary } from "./MDXErrorBoundary.js";
 import { CSS_TEXT } from "./cssText.js";
-const defaultComponents = { EntryLink: makeDefaultEntryLink(runtime) };
+const defaultComponents = {
+    EntryLink: makeDefaultEntryLink(runtime),
+    img: makeDefaultImage(runtime),
+};
 /**
  * Compiles raw MDX/markdown into a renderable React component — no DOM assumptions, safe for client effects or RSC.
  * Standard markdown elements render via real DOM tags with zero setup; only a JSX component with no built-in default needs `components`.

package/dist/compileMDX.test.js

@@ -44,6 +44,35 @@ test("vue EntryLink renders as a link to /entries/{id} with no components map su
     assert.equal(link.type, "a");
     assert.equal(link.props.href, "/entries/abc123");
 });
+// A standalone `![]()` compiles to a <p><img/></p> — resolve the paragraph, then its one child.
+function imgFrom(paragraph) {
+    const child = paragraph.props.children;
+    return resolve(Array.isArray(child) ? child[0] : child);
+}
+test("react img gets lazy-loading defaults with no components map supplied", async () => {
+    const result = await compileReactMDX("![alt text](https://example.com/a.png)");
+    assert.equal(result.ok, true);
+    if (!result.ok)
+        return;
+    const paragraph = resolve(result.Content({}));
+    const img = imgFrom(paragraph);
+    assert.equal(img.type, "img");
+    assert.equal(img.props.loading, "lazy");
+    assert.equal(img.props.decoding, "async");
+    assert.equal(img.props.src, "https://example.com/a.png");
+});
+test("a supplied img override still wins over the default", async () => {
+    const result = await compileReactMDX("![alt text](https://example.com/a.png)");
+    assert.equal(result.ok, true);
+    if (!result.ok)
+        return;
+    const CustomImage = () => ({ type: "custom-image", props: {} });
+    const paragraph = resolve(result.Content({
+        components: { img: CustomImage },
+    }));
+    const img = imgFrom(paragraph);
+    assert.equal(img.type, "custom-image");
+});
 test("a supplied EntryLink override still wins over the default", async () => {
     const result = await compileReactMDX('<EntryLink id="abc123">Read more</EntryLink>');
     assert.equal(result.ok, true);

package/dist/core.d.ts

@@ -19,3 +19,7 @@ export declare function makeDefaultEntryLink(jsxRuntime: JsxRuntime): ({ id, chi
     id?: string;
     children?: unknown;
 }) => JSX.Element;
+/** Default `img` for a given JSX runtime — defers offscreen image loads instead of the browser's
+ * eager default. Apps that want `next/image` (or another optimizer) override it via `components.img`;
+ * an explicit `loading`/`decoding` on the element itself (rare, but author-settable) still wins. */
+export declare function makeDefaultImage(jsxRuntime: JsxRuntime): (props: Record<string, unknown>) => JSX.Element;

package/dist/core.js

@@ -38,3 +38,11 @@ export function makeDefaultEntryLink(jsxRuntime) {
         return jsxRuntime.jsx("a", { href: id ? `/entries/${id}` : undefined, children });
     };
 }
+/** Default `img` for a given JSX runtime — defers offscreen image loads instead of the browser's
+ * eager default. Apps that want `next/image` (or another optimizer) override it via `components.img`;
+ * an explicit `loading`/`decoding` on the element itself (rare, but author-settable) still wins. */
+export function makeDefaultImage(jsxRuntime) {
+    return function Img(props) {
+        return jsxRuntime.jsx("img", { loading: "lazy", decoding: "async", ...props });
+    };
+}

package/dist/reactNative.d.ts

@@ -12,6 +12,9 @@ export type { FailedMDX };
 /**
  * Wires up a React Native `compileMDX` with default Text/View/Image mappings for every standard markdown element
  * (and `EntryLink`), so a project sets up its RN primitives once instead of mapping every tag on every call.
+ * A tag/component the source references but nothing maps (a typo'd custom component, a raw HTML tag RN has no
+ * native view for) is caught at render — logged via `console.error` and replaced with the raw source as
+ * plain text, instead of crashing the screen.
  */
 export declare function createReactNativeRenderer(primitives: ReactNativePrimitives, styleOptions?: ReactNativeStyleOptions): {
     compileMDX: (source: string) => Promise<CompiledMDX | FailedMDX>;

package/dist/reactNative.js

@@ -1,9 +1,13 @@
 import * as runtime from "react/jsx-runtime";
 import { compileMDXCore } from "./core.js";
+import { MDXErrorBoundary } from "./MDXErrorBoundary.js";
 import { buildReactNativeComponents, } from "./reactNativeComponents.js";
 /**
  * Wires up a React Native `compileMDX` with default Text/View/Image mappings for every standard markdown element
  * (and `EntryLink`), so a project sets up its RN primitives once instead of mapping every tag on every call.
+ * A tag/component the source references but nothing maps (a typo'd custom component, a raw HTML tag RN has no
+ * native view for) is caught at render — logged via `console.error` and replaced with the raw source as
+ * plain text, instead of crashing the screen.
  */
 export function createReactNativeRenderer(primitives, styleOptions) {
     const defaultComponents = buildReactNativeComponents(primitives, styleOptions);
@@ -27,9 +31,17 @@ export function createReactNativeRenderer(primitives, styleOptions) {
                 : wrapped;
             return stripWhitespaceRootChildren(rootElement);
         };
+        // A JSX component referenced in `source` but missing from `components`, or a raw HTML tag RN has
+        // no native view for, throws mid-render — RN has no DOM to silently fall back on the way web
+        // does, so catch it here instead of taking down the whole screen, and log it loudly so the
+        // content author (or whoever wired up `components`) notices and fixes it.
+        const SafeContent = (props) => runtime.jsx(MDXErrorBoundary, {
+            fallback: runtime.jsx(primitives.Text, { children: source }),
+            children: runtime.jsx(RootWithoutWhitespace, props),
+        });
         return {
             ok: true,
-            Content: RootWithoutWhitespace,
+            Content: SafeContent,
         };
     }
     return { compileMDX };

package/dist/reactNative.test.js

@@ -1,17 +1,23 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { createReactNativeRenderer } from "./reactNative.js";
+import { MDXErrorBoundary } from "./MDXErrorBoundary.js";
 // Fakes standing in for react-native's Text/View/Image — see reactNativeComponents.test.ts.
 const Text = () => null;
 const View = () => null;
 const Image = () => null;
 const LEAVES = [Text, View, Image];
 /** Unwraps nested function-component elements down to the RN primitive actually used,
- * without calling into it (Text/View/Image are opaque leaves here, not JSX). */
+ * without calling into it (Text/View/Image are opaque leaves here, not JSX). Class components
+ * (MDXErrorBoundary) can't be invoked directly like a function — unwrap via `children`,
+ * matching its non-error render path. */
 function resolve(element) {
-    return typeof element.type === "function" && !LEAVES.includes(element.type)
-        ? resolve(element.type(element.props))
-        : element;
+    if (typeof element.type !== "function" || LEAVES.includes(element.type))
+        return element;
+    const type = element.type;
+    return type.prototype?.isReactComponent
+        ? resolve(element.props.children)
+        : resolve(element.type(element.props));
 }
 test("React Native smoke test: renders standard markdown through Text/View with zero setup beyond the three primitives", async () => {
     const { compileMDX } = createReactNativeRenderer({ Text, View, Image });
@@ -24,6 +30,38 @@ test("React Native smoke test: renders standard markdown through Text/View with
     assert.equal(heading.type, Text);
     assert.equal(heading.props.style.fontSize, 28);
 });
+test("React Native falls back to the raw source and logs to console instead of crashing on an unknown tag", async () => {
+    const { compileMDX } = createReactNativeRenderer({ Text, View, Image });
+    const result = await compileMDX("<Callout>hi</Callout>");
+    assert.equal(result.ok, true);
+    if (!result.ok)
+        return;
+    const originalConsoleError = console.error;
+    const logged = [];
+    console.error = (...args) => logged.push(args);
+    try {
+        // No react-dom/test-renderer in this package — drive the real MDXErrorBoundary class by
+        // hand the way React would: render children, and on throw, catch + re-render the fallback.
+        const boundaryElement = result.Content({});
+        assert.equal(boundaryElement.type, MDXErrorBoundary);
+        const boundary = new MDXErrorBoundary(boundaryElement.props);
+        try {
+            resolve(boundaryElement.props.children);
+            assert.fail("expected the missing <Callout> component to throw");
+        }
+        catch (error) {
+            boundary.componentDidCatch(error);
+            Object.assign(boundary.state, MDXErrorBoundary.getDerivedStateFromError());
+        }
+        const fallback = resolve(boundary.render());
+        assert.equal(fallback.type, Text);
+        assert.equal(fallback.props.children, "<Callout>hi</Callout>");
+    }
+    finally {
+        console.error = originalConsoleError;
+    }
+    assert.equal(logged.length, 1);
+});
 test("React Native EntryLink renders out of the box (no components map)", async () => {
     const { compileMDX } = createReactNativeRenderer({ Text, View, Image });
     const result = await compileMDX('<EntryLink id="abc123">Read more</EntryLink>');

package/dist/toHtml.js

@@ -48,6 +48,10 @@ function rehypeDraftbase(options) {
                 }
                 return;
             }
+            if (node.tagName === "img") {
+                node.properties = { loading: "lazy", decoding: "async", ...node.properties };
+                return;
+            }
             if (node.tagName === "a" && options.externalLinks) {
                 const href = node.properties?.href;
                 if (typeof href !== "string" || !SCHEME_HREF.test(href))

package/dist/toHtml.test.js

@@ -19,6 +19,10 @@ test("className merges onto the wrapper div, styles still inlined", async () =>
     const html = await toHtml("hi", { className: "prose" });
     assert.equal(html, `<style>${CSS_TEXT}</style><div class="db-content prose"><p>hi</p></div>`);
 });
+test("img gets lazy-loading defaults with no components option supplied", async () => {
+    const html = await toHtml("![alt text](https://example.com/a.png)", { unstyled: true });
+    assert.equal(html, '<p><img loading="lazy" decoding="async" src="https://example.com/a.png" alt="alt text"></p>');
+});
 test("supports gfm tables", async () => {
     const html = await toHtml("| a | b |\n| - | - |\n| 1 | 2 |");
     assert.match(html, /<table>/);

package/dist/vue.js

@@ -1,6 +1,9 @@
-import { compileMDXCore, makeDefaultEntryLink } from "./core.js";
+import { compileMDXCore, makeDefaultEntryLink, makeDefaultImage } from "./core.js";
 import { vueJsxRuntime } from "./vueRuntime.js";
-const defaultComponents = { EntryLink: makeDefaultEntryLink(vueJsxRuntime) };
+const defaultComponents = {
+    EntryLink: makeDefaultEntryLink(vueJsxRuntime),
+    img: makeDefaultImage(vueJsxRuntime),
+};
 /**
  * Compiles raw MDX/markdown into a renderable Vue component. Vue has no RSC-style async component, so call this
  * from `setup()`/a composable and render the result yourself: `h(Content, props)`.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@draftbase/renderer",
-  "version": "0.5.1",
+  "version": "0.5.2",
   "description": "Framework-agnostic MDX renderer for Draftbase content (React, Next.js RSC, React Native, Astro, Vite, Vue)",
   "keywords": [
     "draftbase",