@draftbase/renderer 0.4.3 → 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.d.ts

@@ -19,7 +19,7 @@ export interface MDXContentProps {
     /** Custom components available by name inside the MDX source, and/or overrides for standard markdown elements —
      * required on non-DOM renderers such as React Native, which have no intrinsic `div`/`p`/`a` tags. */
     components?: MDXComponents;
-    /** Skip the default `db-content` styling class. */
+    /** Skip the default `db-content` styling class and its inlined styles. */
     unstyled?: boolean;
     /** Extra class name(s) merged onto the wrapper element. */
     className?: string;
@@ -29,9 +29,13 @@ export interface MDXContentProps {
     /** Element/component used to render the fallback plain-text output when `source` fails to
      * compile as MDX. Defaults to `"p"`; pass React Native's `Text`. */
     errorTag?: ElementType;
+    /** Called (in addition to `console.error`) when `source` fails to compile, or a component
+     * throws while rendering. Either way the fallback plain-text output still renders instead of
+     * crashing. */
+    onError?: (error: unknown) => void;
 }
 /**
  * Next.js Server Component wrapper around {@link compileMDX}. For non-RSC React, call `compileMDX` directly instead —
  * `await` inside a component body only works as an RSC.
  */
-export declare function MDXContent({ source, components, unstyled, className, wrapperTag, errorTag, }: MDXContentProps): Promise<ReactNode>;
+export declare function MDXContent({ source, components, unstyled, className, wrapperTag, errorTag, onError, }: MDXContentProps): Promise<ReactNode>;

package/dist/MDXContent.js

@@ -1,9 +1,13 @@
-import { jsx as _jsx } from "react/jsx-runtime";
+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";
-const defaultComponents = { EntryLink: makeDefaultEntryLink(runtime) };
+import { CSS_TEXT } from "./cssText.js";
+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`.
@@ -15,17 +19,21 @@ export async function compileMDX(source) {
  * Next.js Server Component wrapper around {@link compileMDX}. For non-RSC React, call `compileMDX` directly instead —
  * `await` inside a component body only works as an RSC.
  */
-export async function MDXContent({ source, components, unstyled, className, wrapperTag = "div", errorTag = "p", }) {
+export async function MDXContent({ source, components, unstyled, className, wrapperTag = "div", errorTag = "p", onError, }) {
     const Wrapper = wrapperTag;
     const ErrorTag = errorTag;
     const wrapperClass = wrapperClassName(unstyled, className);
+    // `href` + `precedence` make React DOM treat this as a de-duplicated, hoisted stylesheet
+    // resource (React 19+) instead of a plain inline tag repeated per render.
+    const styles = unstyled ? null : (_jsx("style", { href: "db-content-styles", precedence: "default", children: CSS_TEXT }));
     const compiled = await compileMDX(source);
     if (!compiled.ok) {
         // Source isn't valid MDX/JSX (e.g. stray `<`/`{` in prose) — fail soft instead
         // of crashing the page; render it as plain text so the copy still shows.
         console.error("MDX compile failed, rendering as plain text", compiled.error);
-        return (_jsx(Wrapper, { className: wrapperClass, children: _jsx(ErrorTag, { children: source }) }));
+        onError?.(compiled.error);
+        return (_jsxs(_Fragment, { children: [styles, _jsx(Wrapper, { className: wrapperClass, children: _jsx(ErrorTag, { children: source }) })] }));
     }
     const { Content } = compiled;
-    return (_jsx(Wrapper, { className: wrapperClass, children: _jsx(MDXErrorBoundary, { fallback: _jsx(ErrorTag, { children: source }), children: _jsx(Content, { components: components }) }) }));
+    return (_jsxs(_Fragment, { children: [styles, _jsx(Wrapper, { className: wrapperClass, children: _jsx(MDXErrorBoundary, { fallback: _jsx(ErrorTag, { children: source }), onError: onError, children: _jsx(Content, { components: components }) }) })] }));
 }

package/dist/MDXContent.test.js

@@ -1,18 +1,33 @@
 import assert from "node:assert/strict";
 import test from "node:test";
 import { MDXContent } from "./MDXContent.js";
-// MDXContent is an async Server Component; call it directly (as React's RSC runtime would) and inspect the returned element tree.
+// MDXContent is an async Server Component; call it directly (as React's RSC runtime would) and inspect
+// the returned element tree. It returns a fragment: [inlined <style> | null, the wrapper element].
+function wrapperOf(fragment) {
+    const [, wrapper] = fragment.props.children;
+    return wrapper;
+}
 test("MDXContent wraps compiled MDX in the styled wrapper element", async () => {
-    const element = (await MDXContent({ source: "# Hello" }));
+    const fragment = (await MDXContent({ source: "# Hello" }));
+    const [styles] = fragment.props.children;
+    assert.equal(styles.type, "style");
+    const element = wrapperOf(fragment);
     assert.equal(element.type, "div");
     assert.equal(element.props.className, "db-content");
 });
-test("unstyled drops the db-content class", async () => {
-    const element = (await MDXContent({ source: "# Hello", unstyled: true }));
+test("unstyled drops the db-content class and the inlined styles", async () => {
+    const fragment = (await MDXContent({
+        source: "# Hello",
+        unstyled: true,
+    }));
+    const [styles] = fragment.props.children;
+    assert.equal(styles, null);
+    const element = wrapperOf(fragment);
     assert.equal(element.props.className, undefined);
 });
 test("falls back to plain text when the source fails to compile as MDX", async () => {
-    const element = (await MDXContent({ source: "<broken" }));
+    const fragment = (await MDXContent({ source: "<broken" }));
+    const element = wrapperOf(fragment);
     const fallback = element.props.children;
     assert.equal(fallback.type, "p");
     assert.equal(fallback.props.children, "<broken");

package/dist/MDXErrorBoundary.d.ts

@@ -2,6 +2,7 @@ import { Component, type ReactNode } from "react";
 interface MDXErrorBoundaryProps {
     children: ReactNode;
     fallback: ReactNode;
+    onError?: (error: unknown) => void;
 }
 interface MDXErrorBoundaryState {
     hasError: boolean;

package/dist/MDXErrorBoundary.js

@@ -9,6 +9,7 @@ export class MDXErrorBoundary extends Component {
     }
     componentDidCatch(error) {
         console.error("MDX content failed to render", error);
+        this.props.onError?.(error);
     }
     render() {
         return this.state.hasError ? this.props.fallback : this.props.children;

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/cssText.d.ts

@@ -0,0 +1 @@
+export declare const CSS_TEXT = "/* Slim default typography for Draftbase MDX content.\n   Opt-in: import \"@draftbase/renderer/styles.css\".\n   Disable per-render: <MDXContent unstyled /> or toHtml(source, { unstyled: true }).\n   Theme via custom properties: --db-heading-color, --db-link-color, --db-accent-border,\n   --db-target-bg. Override further: target \".db-content\" with higher-specificity or\n   later-loaded rules. */\n\n.db-content {\n  line-height: 1.6;\n  color: inherit;\n  overflow-wrap: break-word;\n}\n\n.db-content h1,\n.db-content h2,\n.db-content h3,\n.db-content h4,\n.db-content h5,\n.db-content h6 {\n  color: var(--db-heading-color, inherit);\n}\n\n.db-content a {\n  color: var(--db-link-color, inherit);\n}\n\n/* remark-gfm emits the footnotes label as .sr-only; define it so it stays hidden\n   without the consumer needing Tailwind or their own utility. */\n.db-content .sr-only {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip-path: inset(50%);\n  white-space: nowrap;\n}\n\n.db-content > :first-child {\n  margin-top: 0;\n}\n.db-content > :last-child {\n  margin-bottom: 0;\n}\n\n.db-content h1,\n.db-content h2,\n.db-content h3,\n.db-content h4,\n.db-content h5,\n.db-content h6 {\n  font-weight: 600;\n  line-height: 1.25;\n  margin: 1.5em 0 0.5em;\n}\n\n/* Highlights a footnote/citation anchor when the URL hash lands on it, e.g. #fn-1. */\n.db-content :target {\n  background: var(--db-target-bg, rgba(127, 127, 127, 0.15));\n}\n\n.db-content h1 {\n  font-size: 2.25em;\n  font-weight: 700;\n  line-height: 1.2;\n  letter-spacing: -0.025em;\n  margin-top: 1.25em;\n}\n\n.db-content h2 {\n  font-size: 1.5em;\n  line-height: 1.25;\n  letter-spacing: -0.02em;\n  margin-top: 1.75em;\n}\n\n.db-content h3 {\n  font-size: 1.25em;\n  line-height: 1.3;\n}\n\n.db-content h4 {\n  font-size: 1.125em;\n  line-height: 1.35;\n}\n\n.db-content h5 {\n  font-size: 1em;\n  line-height: 1.4;\n}\n\n.db-content h6 {\n  font-size: 0.875em;\n  line-height: 1.4;\n}\n\n@media (max-width: 640px) {\n  .db-content h1 {\n    font-size: 1.875em;\n  }\n  .db-content h2 {\n    font-size: 1.25em;\n  }\n  .db-content h3 {\n    font-size: 1.125em;\n  }\n}\n\n.db-content p,\n.db-content ul,\n.db-content ol,\n.db-content blockquote,\n.db-content pre,\n.db-content table {\n  margin: 0 0 1em;\n}\n\n.db-content ul,\n.db-content ol {\n  padding-left: 1.5em;\n}\n\n.db-content ul {\n  list-style-type: disc;\n}\n\n.db-content ol {\n  list-style-type: decimal;\n}\n\n.db-content ul ul {\n  list-style-type: circle;\n}\n\n.db-content ol ol {\n  list-style-type: lower-alpha;\n}\n\n.db-content ul ul ul,\n.db-content ol ol ol {\n  list-style-type: square;\n}\n\n.db-content li {\n  margin: 0.25em 0;\n}\n.db-content li > ul,\n.db-content li > ol {\n  margin: 0.25em 0 0;\n}\n.db-content li > p {\n  margin: 0;\n}\n\n.db-content ul.contains-task-list {\n  list-style: none;\n  padding-left: 0.25em;\n}\n.db-content li.task-list-item {\n  list-style: none;\n  margin-left: 0;\n}\n.db-content li.task-list-item input[type=\"checkbox\"] {\n  margin-right: 0.5em;\n}\n\n.db-content strong {\n  font-weight: 600;\n}\n.db-content em {\n  font-style: italic;\n}\n.db-content del {\n  text-decoration: line-through;\n  opacity: 0.75;\n}\n\n.db-content blockquote {\n  margin-left: 0;\n  padding-left: 1em;\n  border-left: 3px solid var(--db-accent-border, currentColor);\n  opacity: 0.85;\n}\n\n.db-content code {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.9em;\n  padding: 0.15em 0.35em;\n  background: rgba(127, 127, 127, 0.15);\n  border-radius: 4px;\n}\n\n.db-content pre {\n  padding: 1em;\n  overflow-x: auto;\n  background: rgba(127, 127, 127, 0.1);\n  border-radius: 8px;\n}\n.db-content pre code {\n  padding: 0;\n  background: none;\n}\n\n/* display:block so wide tables scroll instead of overflowing the page on mobile;\n   costs full-bleed stretch for narrow tables. */\n.db-content table {\n  border-collapse: collapse;\n  display: block;\n  width: max-content;\n  max-width: 100%;\n  overflow-x: auto;\n}\n\n.db-content th,\n.db-content td {\n  border: 1px solid rgba(127, 127, 127, 0.3);\n  padding: 0.5em 0.75em;\n  text-align: left;\n}\n\n.db-content th {\n  background: rgba(127, 127, 127, 0.08);\n  font-weight: 600;\n}\n\n.db-content img {\n  max-width: 100%;\n  height: auto;\n  border-radius: 8px;\n}\n\n.db-content a {\n  text-decoration: underline;\n  text-underline-offset: 2px;\n}\n.db-content a:hover {\n  opacity: 0.8;\n}\n\n.db-content hr {\n  border: none;\n  border-top: 1px solid rgba(127, 127, 127, 0.3);\n  margin: 2em 0;\n}\n";

package/dist/cssText.js

@@ -0,0 +1,2 @@
+// Generated from styles.css by scripts/generate-css-text.mjs — do not edit directly.
+export const CSS_TEXT = "/* Slim default typography for Draftbase MDX content.\n   Opt-in: import \"@draftbase/renderer/styles.css\".\n   Disable per-render: <MDXContent unstyled /> or toHtml(source, { unstyled: true }).\n   Theme via custom properties: --db-heading-color, --db-link-color, --db-accent-border,\n   --db-target-bg. Override further: target \".db-content\" with higher-specificity or\n   later-loaded rules. */\n\n.db-content {\n  line-height: 1.6;\n  color: inherit;\n  overflow-wrap: break-word;\n}\n\n.db-content h1,\n.db-content h2,\n.db-content h3,\n.db-content h4,\n.db-content h5,\n.db-content h6 {\n  color: var(--db-heading-color, inherit);\n}\n\n.db-content a {\n  color: var(--db-link-color, inherit);\n}\n\n/* remark-gfm emits the footnotes label as .sr-only; define it so it stays hidden\n   without the consumer needing Tailwind or their own utility. */\n.db-content .sr-only {\n  position: absolute;\n  width: 1px;\n  height: 1px;\n  padding: 0;\n  margin: -1px;\n  overflow: hidden;\n  clip-path: inset(50%);\n  white-space: nowrap;\n}\n\n.db-content > :first-child {\n  margin-top: 0;\n}\n.db-content > :last-child {\n  margin-bottom: 0;\n}\n\n.db-content h1,\n.db-content h2,\n.db-content h3,\n.db-content h4,\n.db-content h5,\n.db-content h6 {\n  font-weight: 600;\n  line-height: 1.25;\n  margin: 1.5em 0 0.5em;\n}\n\n/* Highlights a footnote/citation anchor when the URL hash lands on it, e.g. #fn-1. */\n.db-content :target {\n  background: var(--db-target-bg, rgba(127, 127, 127, 0.15));\n}\n\n.db-content h1 {\n  font-size: 2.25em;\n  font-weight: 700;\n  line-height: 1.2;\n  letter-spacing: -0.025em;\n  margin-top: 1.25em;\n}\n\n.db-content h2 {\n  font-size: 1.5em;\n  line-height: 1.25;\n  letter-spacing: -0.02em;\n  margin-top: 1.75em;\n}\n\n.db-content h3 {\n  font-size: 1.25em;\n  line-height: 1.3;\n}\n\n.db-content h4 {\n  font-size: 1.125em;\n  line-height: 1.35;\n}\n\n.db-content h5 {\n  font-size: 1em;\n  line-height: 1.4;\n}\n\n.db-content h6 {\n  font-size: 0.875em;\n  line-height: 1.4;\n}\n\n@media (max-width: 640px) {\n  .db-content h1 {\n    font-size: 1.875em;\n  }\n  .db-content h2 {\n    font-size: 1.25em;\n  }\n  .db-content h3 {\n    font-size: 1.125em;\n  }\n}\n\n.db-content p,\n.db-content ul,\n.db-content ol,\n.db-content blockquote,\n.db-content pre,\n.db-content table {\n  margin: 0 0 1em;\n}\n\n.db-content ul,\n.db-content ol {\n  padding-left: 1.5em;\n}\n\n.db-content ul {\n  list-style-type: disc;\n}\n\n.db-content ol {\n  list-style-type: decimal;\n}\n\n.db-content ul ul {\n  list-style-type: circle;\n}\n\n.db-content ol ol {\n  list-style-type: lower-alpha;\n}\n\n.db-content ul ul ul,\n.db-content ol ol ol {\n  list-style-type: square;\n}\n\n.db-content li {\n  margin: 0.25em 0;\n}\n.db-content li > ul,\n.db-content li > ol {\n  margin: 0.25em 0 0;\n}\n.db-content li > p {\n  margin: 0;\n}\n\n.db-content ul.contains-task-list {\n  list-style: none;\n  padding-left: 0.25em;\n}\n.db-content li.task-list-item {\n  list-style: none;\n  margin-left: 0;\n}\n.db-content li.task-list-item input[type=\"checkbox\"] {\n  margin-right: 0.5em;\n}\n\n.db-content strong {\n  font-weight: 600;\n}\n.db-content em {\n  font-style: italic;\n}\n.db-content del {\n  text-decoration: line-through;\n  opacity: 0.75;\n}\n\n.db-content blockquote {\n  margin-left: 0;\n  padding-left: 1em;\n  border-left: 3px solid var(--db-accent-border, currentColor);\n  opacity: 0.85;\n}\n\n.db-content code {\n  font-family: ui-monospace, SFMono-Regular, Menlo, monospace;\n  font-size: 0.9em;\n  padding: 0.15em 0.35em;\n  background: rgba(127, 127, 127, 0.15);\n  border-radius: 4px;\n}\n\n.db-content pre {\n  padding: 1em;\n  overflow-x: auto;\n  background: rgba(127, 127, 127, 0.1);\n  border-radius: 8px;\n}\n.db-content pre code {\n  padding: 0;\n  background: none;\n}\n\n/* display:block so wide tables scroll instead of overflowing the page on mobile;\n   costs full-bleed stretch for narrow tables. */\n.db-content table {\n  border-collapse: collapse;\n  display: block;\n  width: max-content;\n  max-width: 100%;\n  overflow-x: auto;\n}\n\n.db-content th,\n.db-content td {\n  border: 1px solid rgba(127, 127, 127, 0.3);\n  padding: 0.5em 0.75em;\n  text-align: left;\n}\n\n.db-content th {\n  background: rgba(127, 127, 127, 0.08);\n  font-weight: 600;\n}\n\n.db-content img {\n  max-width: 100%;\n  height: auto;\n  border-radius: 8px;\n}\n\n.db-content a {\n  text-decoration: underline;\n  text-underline-offset: 2px;\n}\n.db-content a:hover {\n  opacity: 0.8;\n}\n\n.db-content hr {\n  border: none;\n  border-top: 1px solid rgba(127, 127, 127, 0.3);\n  margin: 2em 0;\n}\n";

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/styles.css

@@ -1,7 +1,9 @@
 /* Slim default typography for Draftbase MDX content.
-   Opt-in: import "@draftbase/react/styles.css".
-   Disable per-render: <MDXContent unstyled />.
-   Override: target ".db-content" with higher-specificity or later-loaded rules. */
+   Opt-in: import "@draftbase/renderer/styles.css".
+   Disable per-render: <MDXContent unstyled /> or toHtml(source, { unstyled: true }).
+   Theme via custom properties: --db-heading-color, --db-link-color, --db-accent-border,
+   --db-target-bg. Override further: target ".db-content" with higher-specificity or
+   later-loaded rules. */
 
 .db-content {
   line-height: 1.6;
@@ -9,6 +11,19 @@
   overflow-wrap: break-word;
 }
 
+.db-content h1,
+.db-content h2,
+.db-content h3,
+.db-content h4,
+.db-content h5,
+.db-content h6 {
+  color: var(--db-heading-color, inherit);
+}
+
+.db-content a {
+  color: var(--db-link-color, inherit);
+}
+
 /* remark-gfm emits the footnotes label as .sr-only; define it so it stays hidden
    without the consumer needing Tailwind or their own utility. */
 .db-content .sr-only {
@@ -38,7 +53,6 @@
   font-weight: 600;
   line-height: 1.25;
   margin: 1.5em 0 0.5em;
-  color: inherit;
 }
 
 /* Highlights a footnote/citation anchor when the URL hash lands on it, e.g. #fn-1. */
@@ -165,7 +179,7 @@
 .db-content blockquote {
   margin-left: 0;
   padding-left: 1em;
-  border-left: 3px solid currentColor;
+  border-left: 3px solid var(--db-accent-border, currentColor);
   opacity: 0.85;
 }
 
@@ -217,7 +231,6 @@
 }
 
 .db-content a {
-  color: inherit;
   text-decoration: underline;
   text-underline-offset: 2px;
 }

package/dist/toHtml.d.ts

@@ -11,7 +11,19 @@ export interface ToHtmlOptions {
         target?: string;
         rel?: string;
     };
+    /** Skip wrapping the output in a `db-content`-classed `<div>` and the inlined default
+     * styles (see below). Same semantics as `MDXContent`'s `unstyled` prop. */
+    unstyled?: boolean;
+    /** Extra class name(s) merged onto the wrapper `<div>`. */
+    className?: string;
+    /** Called (in addition to `console.error`) when a custom component (from `components`) throws
+     * while rendering. The tag is left as literal HTML instead of failing the whole render. */
+    onError?: (error: unknown, tagName: string) => void;
 }
-/** Renders MDX/markdown to a static HTML string — no React, no mounted tree. Use
- * `compileMDX`/`MDXContent` instead when you need a React tree. */
+/** Renders MDX/markdown to a static, self-contained HTML string: pre-wrapped in
+ * `<div class="db-content">` with the default styles inlined as a `<style>` tag ahead of it —
+ * no separate `styles.css` import needed. Calling `toHtml` more than once on the same page
+ * repeats that `<style>` tag (harmless, just redundant bytes); pass `unstyled: true` and load
+ * `@draftbase/renderer/styles.css` yourself once if that matters. No React, no mounted tree —
+ * use `compileMDX`/`MDXContent` instead when you need a React tree. */
 export declare function toHtml(source: string, options?: ToHtmlOptions): Promise<string>;

package/dist/toHtml.js

@@ -6,6 +6,8 @@ import rehypeRaw from "rehype-raw";
 import rehypeSlug from "rehype-slug";
 import rehypeStringify from "rehype-stringify";
 import { toHtml as hastToHtml } from "hast-util-to-html";
+import { wrapperClassName } from "./wrapperClassName.js";
+import { CSS_TEXT } from "./cssText.js";
 const SCHEME_HREF = /^[a-z][a-z0-9+.-]*:/i;
 const defaultEntryLink = (props, childrenHtml) => `<a href="/entries/${props.id ?? ""}">${childrenHtml}</a>`;
 function hastPropsToStrings(properties) {
@@ -28,16 +30,26 @@ function rehypeDraftbase(options) {
                 transform(child);
             if (node.type !== "element" || !node.tagName)
                 return;
-            const render = componentsByTag?.get(node.tagName);
+            const tagName = node.tagName;
+            const render = componentsByTag?.get(tagName);
             if (render) {
-                const childrenHtml = hastToHtml({ type: "root", children: node.children ?? [] }, {
-                    allowDangerousHtml: true,
-                });
-                node.value = render(hastPropsToStrings(node.properties), childrenHtml);
-                node.type = "raw";
-                node.tagName = undefined;
-                node.properties = undefined;
-                node.children = undefined;
+                try {
+                    const childrenHtml = hastToHtml({ type: "root", children: node.children ?? [] }, { allowDangerousHtml: true });
+                    node.value = render(hastPropsToStrings(node.properties), childrenHtml);
+                    node.type = "raw";
+                    node.tagName = undefined;
+                    node.properties = undefined;
+                    node.children = undefined;
+                }
+                catch (error) {
+                    // Leave the tag as literal HTML instead of failing the whole render.
+                    console.error(`Draftbase component "${tagName}" failed to render`, error);
+                    options.onError?.(error, tagName);
+                }
+                return;
+            }
+            if (node.tagName === "img") {
+                node.properties = { loading: "lazy", decoding: "async", ...node.properties };
                 return;
             }
             if (node.tagName === "a" && options.externalLinks) {
@@ -55,8 +67,12 @@ function rehypeDraftbase(options) {
         transform(tree);
     };
 }
-/** Renders MDX/markdown to a static HTML string — no React, no mounted tree. Use
- * `compileMDX`/`MDXContent` instead when you need a React tree. */
+/** Renders MDX/markdown to a static, self-contained HTML string: pre-wrapped in
+ * `<div class="db-content">` with the default styles inlined as a `<style>` tag ahead of it —
+ * no separate `styles.css` import needed. Calling `toHtml` more than once on the same page
+ * repeats that `<style>` tag (harmless, just redundant bytes); pass `unstyled: true` and load
+ * `@draftbase/renderer/styles.css` yourself once if that matters. No React, no mounted tree —
+ * use `compileMDX`/`MDXContent` instead when you need a React tree. */
 export async function toHtml(source, options = {}) {
     const needsRawParse = Boolean(options.components);
     const processor = unified()
@@ -70,5 +86,11 @@ export async function toHtml(source, options = {}) {
         .use(rehypeDraftbase, options)
         .use(rehypeStringify, { allowDangerousHtml: true });
     const file = await processor.process(source);
-    return String(file);
+    const html = String(file);
+    const wrapperClass = wrapperClassName(options.unstyled, options.className);
+    if (!wrapperClass)
+        return html;
+    return options.unstyled
+        ? `<div class="${wrapperClass}">${html}</div>`
+        : `<style>${CSS_TEXT}</style><div class="${wrapperClass}">${html}</div>`;
 }

package/dist/toHtml.test.js

@@ -1,11 +1,28 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
 import { toHtml } from "./toHtml.js";
+import { CSS_TEXT } from "./cssText.js";
 test("renders markdown to html", async () => {
     const html = await toHtml("# Title\n\nSome **bold** text.");
     assert.match(html, /<h1 id="title">Title<\/h1>/);
     assert.match(html, /<strong>bold<\/strong>/);
 });
+test("wraps output in a db-content div with inlined styles by default", async () => {
+    const html = await toHtml("hi");
+    assert.equal(html, `<style>${CSS_TEXT}</style><div class="db-content"><p>hi</p></div>`);
+});
+test("unstyled skips the wrapper div and the inlined styles", async () => {
+    const html = await toHtml("hi", { unstyled: true });
+    assert.equal(html, "<p>hi</p>");
+});
+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>/);
@@ -43,6 +60,21 @@ test("components resolves nested custom tags before serializing the parent's chi
     });
     assert.match(html, /<div><a href="\/entries\/abc">Post<\/a><\/div>/);
 });
+test("a component that throws leaves the tag as literal HTML and calls onError", async () => {
+    const errors = [];
+    const html = await toHtml('<Callout type="warning">Careful</Callout>', {
+        components: {
+            Callout: () => {
+                throw new Error("boom");
+            },
+        },
+        onError: (error, tagName) => errors.push([error, tagName]),
+    });
+    assert.match(html, /<callout type="warning">Careful<\/callout>/);
+    assert.equal(errors.length, 1);
+    assert.equal(errors[0][0].message, "boom");
+    assert.equal(errors[0][1], "callout");
+});
 test("adds target/rel to external links when externalLinks is true", async () => {
     const html = await toHtml("[ext](https://example.com) and [rel](/local)", {
         externalLinks: true,

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.4.3",
+  "version": "0.5.2",
   "description": "Framework-agnostic MDX renderer for Draftbase content (React, Next.js RSC, React Native, Astro, Vite, Vue)",
   "keywords": [
     "draftbase",
@@ -40,8 +40,8 @@
     "README.md"
   ],
   "scripts": {
-    "build": "tsc -p tsconfig.json && cp src/styles.css dist/styles.css",
-    "lint": "tsc --noEmit",
+    "build": "node scripts/generate-css-text.mjs && tsc -p tsconfig.json && cp src/styles.css dist/styles.css",
+    "lint": "node scripts/generate-css-text.mjs && tsc --noEmit",
     "test": "node --test dist/wrapperClassName.test.js dist/toHtml.test.js dist/compileMDX.test.js dist/reactNativeComponents.test.js dist/reactNative.test.js dist/MDXContent.test.js"
   },
   "peerDependencies": {