@blogmcp/mdx-render-react 0.3.0 → 0.5.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Lukas Zubal
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -30,3 +30,12 @@ Tailwind classes verbatim.
 
 When the first React consumer appears (blog-react or editor-react). Until then, keep the package
 empty so the schema contract proves framework-neutral by construction.
+
+## Real-browser tests
+
+`npm run test:e2e` — Playwright against a Vite harness (`test/e2e/harness`, port 5097; JSX via
+esbuild's automatic runtime, no plugin-react) mounting the real `TripMap` renderer: hand-made nodes,
+the tenant-config path, AUTO mode through `MdxArticleProvider`, exclude, explicit slugs, an unknown
+article, clusters, the detail panel, export, the viewer — on a desktop and a phone project. The
+`/api/media/geo` mock is shared with the Vue harness (`packages/mdx-schema/test/harness/geo-mock.ts`).
+`npm run harness` serves the pages for manual work.

package/dist/index.js

@@ -1,43 +1,48 @@
 import { default as o } from "./MdxContent.js";
-import { serverRenderMap as r } from "./server-render-map.js";
-import { getComponentVariants as l, getRenderComponentAsync as m, reactRegistry as d } from "./registry.js";
-import { createMarked as u, marked as n } from "./marked.js";
+import { serverRenderMap as a } from "./server-render-map.js";
+import { getComponentVariants as l, getRenderComponentAsync as d, reactRegistry as m } from "./registry.js";
+import { createMarked as u, marked as x } from "./marked.js";
 import { default as s } from "./render/callout/CalloutDefault.js";
-import { default as g } from "./render/callout/CalloutMinimal.js";
+import { default as C } from "./render/callout/CalloutMinimal.js";
 import { default as c } from "./render/youtube/YouTubeDefault.js";
-import { default as y } from "./render/gallery/GalleryGrid.js";
-import { default as k } from "./render/codeblock/CodeBlockDefault.js";
+import { default as A } from "./render/gallery/GalleryGrid.js";
+import { default as D } from "./render/codeblock/CodeBlockDefault.js";
 import { default as B } from "./render/audioplayer/AudioPlayerDefault.js";
-import { default as G } from "./render/button/Button.js";
-import { default as T } from "./render/card/Card.js";
-import { default as v } from "./render/alert/Alert.js";
-import { default as N } from "./render/badge/Badge.js";
+import { default as T } from "./render/button/Button.js";
+import { default as G } from "./render/card/Card.js";
+import { default as P } from "./render/alert/Alert.js";
+import { default as H } from "./render/badge/Badge.js";
 import { default as V } from "./render/icon/Icon.js";
 import { default as h } from "./render/tooltip/Tooltip.js";
-import { componentMetadata as q, getComponentMetadata as w, getComponentNames as z } from "@blogmcp/mdx-schema/metadata";
-import { defaultImageHtml as F } from "@blogmcp/sdk";
+import { default as q } from "./render/tripmap/TripMap.js";
+import { MdxArticleContext as z, MdxArticleProvider as E } from "./render/tripmap/article-context.js";
+import { componentMetadata as J, getComponentMetadata as K, getComponentNames as L } from "@blogmcp/mdx-schema/metadata";
+import { defaultImageHtml as Q } from "@blogmcp/sdk";
 export {
-  v as Alert,
+  P as Alert,
   B as AudioPlayerDefault,
-  N as Badge,
-  G as Button,
+  H as Badge,
+  T as Button,
   s as CalloutDefault,
-  g as CalloutMinimal,
-  T as Card,
-  k as CodeBlockDefault,
-  y as GalleryGrid,
+  C as CalloutMinimal,
+  G as Card,
+  D as CodeBlockDefault,
+  A as GalleryGrid,
   V as Icon,
+  z as MdxArticleContext,
+  E as MdxArticleProvider,
   o as MdxContent,
   h as Tooltip,
+  q as TripMap,
   c as YouTubeDefault,
-  q as componentMetadata,
+  J as componentMetadata,
   u as createMarked,
-  F as defaultImageHtml,
-  w as getComponentMetadata,
-  z as getComponentNames,
+  Q as defaultImageHtml,
+  K as getComponentMetadata,
+  L as getComponentNames,
   l as getComponentVariants,
-  m as getRenderComponentAsync,
-  n as marked,
-  d as reactRegistry,
-  r as serverRenderMap
+  d as getRenderComponentAsync,
+  x as marked,
+  m as reactRegistry,
+  a as serverRenderMap
 };

package/dist/registry.js

@@ -57,6 +57,11 @@ const i = {
     render: {
       default: () => import("./render/tooltip/Tooltip.js")
     }
+  },
+  TripMap: {
+    render: {
+      default: () => import("./render/tripmap/TripMap.js")
+    }
   }
 }, o = Object.fromEntries(
   d.map((e) => {
@@ -68,11 +73,11 @@ const i = {
     return [e.name, { metadata: e, ...r }];
   })
 );
-function u(e) {
+function p(e) {
   const r = o[e];
   return r ? Object.keys(r.render) : [];
 }
-async function p(e, r = "default") {
+async function u(e, r = "default") {
   const t = o[e];
   if (!t) return;
   const n = t.render[r] || t.render.default;
@@ -82,7 +87,7 @@ export {
   f as componentMetadata,
   s as getComponentMetadata,
   g as getComponentNames,
-  u as getComponentVariants,
-  p as getRenderComponentAsync,
+  p as getComponentVariants,
+  u as getRenderComponentAsync,
   o as reactRegistry
 };

package/dist/render/index.d.ts

@@ -16,6 +16,9 @@ export { default as Alert } from './alert/Alert';
 export { default as Badge } from './badge/Badge';
 export { default as Icon } from './icon/Icon';
 export { default as Tooltip } from './tooltip/Tooltip';
+export { default as TripMap } from './tripmap/TripMap';
+export { MdxArticleContext, MdxArticleProvider } from './tripmap/article-context';
+export type { MdxArticleContextValue } from './tripmap/article-context';
 export type { ButtonProps } from './button/Button';
 export type { BadgeProps } from './badge/Badge';
 export type { AlertProps } from './alert/Alert';

package/dist/render/index.js

@@ -2,25 +2,30 @@ import { default as o } from "./callout/CalloutDefault.js";
 import { default as r } from "./callout/CalloutMinimal.js";
 import { default as l } from "./youtube/YouTubeDefault.js";
 import { default as d } from "./gallery/GalleryGrid.js";
-import { default as p } from "./codeblock/CodeBlockDefault.js";
-import { default as x } from "./audioplayer/AudioPlayerDefault.js";
+import { default as x } from "./codeblock/CodeBlockDefault.js";
+import { default as s } from "./audioplayer/AudioPlayerDefault.js";
 import { default as C } from "./button/Button.js";
 import { default as n } from "./card/Card.js";
-import { default as c } from "./alert/Alert.js";
-import { default as A } from "./badge/Badge.js";
-import { default as T } from "./icon/Icon.js";
-import { default as g } from "./tooltip/Tooltip.js";
+import { default as D } from "./alert/Alert.js";
+import { default as B } from "./badge/Badge.js";
+import { default as y } from "./icon/Icon.js";
+import { default as P } from "./tooltip/Tooltip.js";
+import { default as g } from "./tripmap/TripMap.js";
+import { MdxArticleContext as v, MdxArticleProvider as I } from "./tripmap/article-context.js";
 export {
-  c as Alert,
-  x as AudioPlayerDefault,
-  A as Badge,
+  D as Alert,
+  s as AudioPlayerDefault,
+  B as Badge,
   C as Button,
   o as CalloutDefault,
   r as CalloutMinimal,
   n as Card,
-  p as CodeBlockDefault,
+  x as CodeBlockDefault,
   d as GalleryGrid,
-  T as Icon,
-  g as Tooltip,
+  y as Icon,
+  v as MdxArticleContext,
+  I as MdxArticleProvider,
+  P as Tooltip,
+  g as TripMap,
   l as YouTubeDefault
 };

package/dist/render/tripmap/TripMap.d.ts

@@ -0,0 +1,2 @@
+import type { TripMapProps } from '@blogmcp/mdx-schema';
+export default function TripMap(props: TripMapProps): import("react/jsx-runtime").JSX.Element;

package/dist/render/tripmap/TripMap.js

@@ -0,0 +1,111 @@
+"use client";
+import { jsxs as M, jsx as a } from "react/jsx-runtime";
+import { useContext as q, useRef as d, useState as J, useMemo as n, useCallback as K, useEffect as _ } from "react";
+import { tripMapStyles as r } from "@blogmcp/mdx-schema/styles";
+import { splitTripMapList as Q, parseTripMapHandNodes as X, buildTripMapGeoUrl as Y, tripMapUiTexts as Z, tripMapPlaybackLabels as ee, tripMapFacade as te, TRIPMAP_DEFAULT_HEIGHT as ae, tripMapFormatTime as re } from "@blogmcp/mdx-schema/tripmap";
+import { MdxArticleContext as ie } from "./article-context.js";
+function de(o) {
+  const { slugs: T, nodes: x, height: B, line: U, filmstrip: k, playback: D, cluster: A, theme: F, styleUrl: I, center: f, zoom: R, title: c, detail: h } = o, i = q(ie), L = d(null), g = d(null), V = d(null), y = d(null), H = d(!1), [P, u] = J("facade"), W = n(() => Q(T), [T]), S = n(() => X(x), [x]), j = n(() => Y(o, i), [o, i]), E = W.length === 0 && !i?.filename, b = n(() => Z(i?.language), [i]), O = n(() => ee(i?.language), [i]), p = n(() => te(o, i), [o, i]), v = K(async () => {
+    if (!H.current) {
+      H.current = !0, u("loading");
+      try {
+        const t = async () => {
+          try {
+            const e = await fetch(j, { headers: { accept: "application/json" } });
+            if (!e.ok) throw new Error(`media/geo ${e.status}`);
+            return await e.json();
+          } catch (e) {
+            if (E) return { nodes: [] };
+            throw e;
+          }
+        }, [l, s] = await Promise.all([import("@blogmcp/tripmap-core"), t()]), N = (s.nodes ?? []).filter((e) => typeof e.latitude == "number" && typeof e.longitude == "number").map((e) => ({
+          id: e.slug,
+          lat: e.latitude,
+          lng: e.longitude,
+          capturedAt: e.capturedAt ?? void 0,
+          thumbnailUrl: e.thumbnailUrl ?? void 0,
+          imageUrl: e.url ?? void 0,
+          largeImageUrl: e.largeUrl ?? void 0,
+          altText: e.altText ?? void 0,
+          title: e.placeName ?? void 0
+        })), C = l.buildTripNodes(N, S);
+        if (C.length === 0 || !g.current) {
+          u("empty");
+          return;
+        }
+        let G;
+        if (f) {
+          const [e, z] = f.split(",").map(($) => Number.parseFloat($.trim()));
+          Number.isFinite(e) && Number.isFinite(z) && (G = { center: [z, e], zoom: R });
+        }
+        const w = new l.TripMap(g.current, {
+          styleUrl: I || s.config?.styleUrl || "",
+          darkStyleUrl: s.config?.darkStyleUrl,
+          theme: F ?? "auto",
+          cluster: A ?? !0,
+          showLine: U ?? !0,
+          showFilmstrip: k ?? !0,
+          showPlayback: D ?? !0,
+          title: c,
+          detail: h ?? "popup",
+          detailHost: h === "panel" ? V.current ?? void 0 : void 0,
+          extraAttribution: s.config?.attribution,
+          labels: O,
+          initialView: G,
+          events: {}
+        });
+        w.setNodes(C), await w.init(), y.current = () => w.destroy(), u("live");
+      } catch {
+        u((t) => t === "loading" ? "facade" : t);
+      }
+    }
+  }, [j, E, S, I, F, A, U, k, O, f, R, c, h]);
+  _(() => {
+    const t = L.current;
+    if (!t) return;
+    if (typeof IntersectionObserver > "u") {
+      v();
+      return;
+    }
+    const l = new IntersectionObserver(
+      (s) => {
+        s.some((N) => N.isIntersecting) && (l.disconnect(), v());
+      },
+      { rootMargin: "300px" }
+    );
+    return l.observe(t), () => l.disconnect();
+  }, [v]), _(
+    () => () => {
+      y.current?.(), y.current = null;
+    },
+    []
+  );
+  const m = P !== "live";
+  return /* @__PURE__ */ M("div", { ref: L, className: r.container, "data-mdx-component": "TripMap", "aria-label": c, children: [
+    c ? /* @__PURE__ */ a("p", { className: r.head, children: c }) : null,
+    m && p.thumbs.length > 0 ? /* @__PURE__ */ a("ol", { className: r.strip, children: p.thumbs.map((t) => /* @__PURE__ */ a("li", { className: r.stripItem, children: /* @__PURE__ */ a(
+      "img",
+      {
+        src: t.src,
+        alt: t.alt,
+        width: 80,
+        height: 80,
+        loading: "lazy",
+        decoding: "async",
+        className: r.stripImg
+      }
+    ) }, t.slug)) }) : null,
+    /* @__PURE__ */ M("div", { className: r.mapWrap, style: { height: B || ae }, children: [
+      /* @__PURE__ */ a("div", { ref: g, className: "absolute inset-0" }),
+      m ? /* @__PURE__ */ a("div", { className: r.mapOverlay, children: /* @__PURE__ */ a("div", { className: r.mapBox, children: /* @__PURE__ */ a("span", { className: r.mapHint, children: P === "empty" ? b.empty : b.hint }) }) }) : null
+    ] }),
+    m && p.stops.length > 0 ? /* @__PURE__ */ a("ol", { className: r.stopList, children: p.stops.map((t) => /* @__PURE__ */ M("li", { children: [
+      t.capturedAt ? /* @__PURE__ */ a("span", { className: r.stopTime, children: re(t.capturedAt) }) : null,
+      /* @__PURE__ */ a("span", { children: t.title })
+    ] }, t.key)) }) : null,
+    m ? /* @__PURE__ */ a("p", { className: r.note, children: b.unavailable }) : null
+  ] });
+}
+export {
+  de as default
+};

package/dist/render/tripmap/article-context.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Article identity for TripMap AUTO mode (map every geotagged media of the
+ * article). The host app wraps its rendered article body in the provider —
+ * the Next blog does in `app/articles/[slug]/page.tsx` AND the draft preview
+ * `app/preview/[token]/page.tsx`; a consumer that doesn't simply has no auto
+ * mode and TripMap needs explicit `slugs` or `nodes`.
+ */
+import { type ReactNode } from 'react';
+import type { TripMapFacadeMedia } from '@blogmcp/mdx-schema/tripmap';
+export interface MdxArticleContextValue {
+    filename: string;
+    language?: string;
+    /**
+     * The article's geotagged media (`contentImagesGeo`), when the host has
+     * them: the SERVER-RENDERED facade then carries real thumbnails with alt
+     * text and named stops in AUTO mode — what crawlers read. Optional.
+     */
+    media?: readonly TripMapFacadeMedia[] | null;
+}
+export declare const MdxArticleContext: import("react").Context<MdxArticleContextValue | null>;
+export declare function MdxArticleProvider({ value, children, }: {
+    value: MdxArticleContextValue | null;
+    children: ReactNode;
+}): import("react").FunctionComponentElement<import("react").ProviderProps<MdxArticleContextValue | null>>;

package/dist/render/tripmap/article-context.js

@@ -0,0 +1,13 @@
+"use client";
+import { createContext as r, createElement as o } from "react";
+const n = r(null);
+function i({
+  value: e,
+  children: t
+}) {
+  return o(n.Provider, { value: e }, t);
+}
+export {
+  n as MdxArticleContext,
+  i as MdxArticleProvider
+};

package/dist/server-render-map.js

@@ -11,7 +11,8 @@ import P from "./render/alert/Alert.js";
 import x from "./render/badge/Badge.js";
 import y from "./render/icon/Icon.js";
 import w from "./render/tooltip/Tooltip.js";
-const E = {
+import E from "./render/tripmap/TripMap.js";
+const R = {
   Callout: c,
   YouTube: f,
   Gallery: l,
@@ -22,35 +23,36 @@ const E = {
   Alert: P,
   Badge: x,
   Icon: y,
-  Tooltip: w
-}, R = "__mdxPreparePropsAppliedFor";
-function A(r, e) {
+  Tooltip: w,
+  TripMap: E
+}, A = "__mdxPreparePropsAppliedFor";
+function C(r, e) {
   const o = function(t) {
-    const { children: a, ...n } = t, m = i(n, e);
-    return p(r, m, a);
+    const { children: a, ...m } = t, n = i(m, e);
+    return p(r, n, a);
   };
-  return o[R] = e.name, o.displayName = `MdxPrepared(${e.name})`, o;
+  return o[A] = e.name, o.displayName = `MdxPrepared(${e.name})`, o;
 }
-const C = new Map(
+const D = new Map(
   d.map((r) => [r.name, r])
 );
-function D(r) {
-  const e = C.get(r);
+function T(r) {
+  const e = D.get(r);
   if (!e)
     throw new Error(
       `[mdx-render-react] No componentMetadata for "${r}" — the React render map has a component the schema does not know about. Add an entry in packages/mdx-schema/src/metadata/index.ts or remove the entry from serverRenderMap.`
     );
   return e;
 }
-const Y = Object.fromEntries(
-  Object.entries(E).map(([r, e]) => [
+const z = Object.fromEntries(
+  Object.entries(R).map(([r, e]) => [
     r,
-    A(e, D(r))
+    C(e, T(r))
   ])
 );
 export {
-  R as MDX_PREPARED_SENTINEL,
-  E as serverRenderMap,
-  A as wrapReactComponentForMdx,
-  Y as wrappedServerRenderMap
+  A as MDX_PREPARED_SENTINEL,
+  R as serverRenderMap,
+  C as wrapReactComponentForMdx,
+  z as wrappedServerRenderMap
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogmcp/mdx-render-react",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "React renderer for MDX components — implements the @blogmcp/mdx-schema contract alongside @blogmcp/mdx-render-vue. Server-Component-first with two client islands (Tooltip, AudioPlayer).",
   "type": "module",
   "publishConfig": {
@@ -32,13 +32,16 @@
     "dev": "vite build --watch",
     "test": "vitest run",
     "test:watch": "vitest",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test:e2e": "playwright test --config test/e2e/playwright.config.ts",
+    "harness": "vite --config test/e2e/harness/vite.config.ts --port 5097"
   },
   "dependencies": {
     "@ark-ui/react": "^5.0.0",
-    "@blogmcp/mdx-schema": "^0.3.0",
+    "@blogmcp/mdx-schema": "^0.5.0",
+    "@blogmcp/tripmap-core": "^0.1.2",
     "@blogmcp/sanitize": "^0.3.0",
-    "@blogmcp/sdk": "^0.3.0",
+    "@blogmcp/sdk": "^0.3.2",
     "@iconify/react": "^6.0.0",
     "marked": "^15.0.7"
   },

package/src/registry.ts

@@ -95,6 +95,11 @@ const reactWiring: Record<string, ReactWiring> = {
       default: () => import('./render/tooltip/Tooltip'),
     },
   },
+  TripMap: {
+    render: {
+      default: () => import('./render/tripmap/TripMap'),
+    },
+  },
 }
 
 /** Merged registry: schema metadata + React wiring, keyed by component name. */

package/src/render/index.ts

@@ -16,6 +16,9 @@ export { default as Alert } from './alert/Alert'
 export { default as Badge } from './badge/Badge'
 export { default as Icon } from './icon/Icon'
 export { default as Tooltip } from './tooltip/Tooltip'
+export { default as TripMap } from './tripmap/TripMap'
+export { MdxArticleContext, MdxArticleProvider } from './tripmap/article-context'
+export type { MdxArticleContextValue } from './tripmap/article-context'
 
 export type { ButtonProps } from './button/Button'
 export type { BadgeProps } from './badge/Badge'

package/src/render/tripmap/TripMap.tsx

@@ -0,0 +1,209 @@
+'use client'
+
+/**
+ * TripMap — client island (mirrors Vue TripMapDefault.vue).
+ *
+ * SSR-safe facade (thumb strip + waypoint list + placeholder box) that
+ * upgrades to the MapLibre map when scrolled near. The map engine is
+ * reached ONLY via dynamic `import('@blogmcp/tripmap-core')` — never a
+ * static import — so bundlers emit maplibre as a lazy chunk and the
+ * single-file article-review bundle (which externalizes the core) simply
+ * keeps the facade when the import rejects.
+ */
+
+import { useCallback, useContext, useEffect, useMemo, useRef, useState } from 'react'
+import type { TripMapProps } from '@blogmcp/mdx-schema'
+import { tripMapStyles } from '@blogmcp/mdx-schema/styles'
+import {
+  buildTripMapGeoUrl,
+  parseTripMapHandNodes,
+  splitTripMapList,
+  TRIPMAP_DEFAULT_HEIGHT,
+  tripMapFormatTime,
+  tripMapPlaybackLabels,
+  tripMapUiTexts,
+  type TripMapGeoResponse,
+  tripMapFacade,
+} from '@blogmcp/mdx-schema/tripmap'
+
+import { MdxArticleContext } from './article-context'
+
+type Status = 'facade' | 'loading' | 'live' | 'empty'
+
+export default function TripMap(props: TripMapProps) {
+  const { slugs, nodes, height, line, filmstrip, playback, cluster, theme, styleUrl, center, zoom, title, detail } = props
+  const article = useContext(MdxArticleContext)
+
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const mapRef = useRef<HTMLDivElement | null>(null)
+  // detail="panel": the engine mounts the photo panel here, below the sized map box.
+  const detailRef = useRef<HTMLDivElement | null>(null)
+  const destroyRef = useRef<(() => void) | null>(null)
+  const startedRef = useRef(false)
+  const [status, setStatus] = useState<Status>('facade')
+
+  const slugList = useMemo(() => splitTripMapList(slugs), [slugs])
+  const handNodes = useMemo(() => parseTripMapHandNodes(nodes), [nodes])
+  const geoUrl = useMemo(() => buildTripMapGeoUrl(props, article), [props, article])
+  // Nothing selects media: the geo call only carries the tenant basemap config.
+  const configOnly = slugList.length === 0 && !article?.filename
+  const texts = useMemo(() => tripMapUiTexts(article?.language), [article])
+  const labels = useMemo(() => tripMapPlaybackLabels(article?.language), [article])
+  const facade = useMemo(() => tripMapFacade(props, article), [props, article])
+
+  const start = useCallback(async () => {
+    if (startedRef.current) return
+    startedRef.current = true
+    setStatus('loading')
+    try {
+      const fetchGeo = async (): Promise<TripMapGeoResponse> => {
+        try {
+          const res = await fetch(geoUrl, { headers: { accept: 'application/json' } })
+          if (!res.ok) throw new Error(`media/geo ${res.status}`)
+          return (await res.json()) as TripMapGeoResponse
+        } catch (err) {
+          // Config-only (hand-made nodes only): keep the nodes, run on the
+          // core default style. With a selection the nodes ARE the response,
+          // so the failure propagates and the static facade stays.
+          if (configOnly) return { nodes: [] }
+          throw err
+        }
+      }
+      const [core, geo] = await Promise.all([import('@blogmcp/tripmap-core'), fetchGeo()])
+      const mediaNodes = (geo.nodes ?? [])
+        .filter((n) => typeof n.latitude === 'number' && typeof n.longitude === 'number')
+        .map((n) => ({
+          id: n.slug,
+          lat: n.latitude,
+          lng: n.longitude,
+          capturedAt: n.capturedAt ?? undefined,
+          thumbnailUrl: n.thumbnailUrl ?? undefined,
+          imageUrl: n.url ?? undefined,
+          largeImageUrl: n.largeUrl ?? undefined,
+          altText: n.altText ?? undefined,
+          title: n.placeName ?? undefined,
+        }))
+      const tripNodes = core.buildTripNodes(mediaNodes, handNodes)
+      if (tripNodes.length === 0 || !mapRef.current) {
+        setStatus('empty')
+        return
+      }
+      let initialView: { center?: [number, number]; zoom?: number } | undefined
+      if (center) {
+        const [lat, lng] = center.split(',').map((v) => Number.parseFloat(v.trim()))
+        if (Number.isFinite(lat) && Number.isFinite(lng)) initialView = { center: [lng, lat], zoom }
+      }
+      const map = new core.TripMap(mapRef.current, {
+        styleUrl: styleUrl || geo.config?.styleUrl || '',
+        darkStyleUrl: geo.config?.darkStyleUrl,
+        theme: theme ?? 'auto',
+        cluster: cluster ?? true,
+        showLine: line ?? true,
+        showFilmstrip: filmstrip ?? true,
+        showPlayback: playback ?? true,
+        title,
+        detail: detail ?? 'popup',
+        detailHost: detail === 'panel' ? (detailRef.current ?? undefined) : undefined,
+        extraAttribution: geo.config?.attribution,
+        labels,
+        initialView,
+        events: {},
+      })
+      map.setNodes(tripNodes)
+      await map.init()
+      destroyRef.current = () => map.destroy()
+      setStatus('live')
+    } catch {
+      // Core unavailable (review-app iframe, offline) or fetch failed —
+      // the static facade stays, which is the designed degradation.
+      setStatus((s) => (s === 'loading' ? 'facade' : s))
+    }
+  }, [geoUrl, configOnly, handNodes, styleUrl, theme, cluster, line, filmstrip, labels, center, zoom, title, detail])
+
+  useEffect(() => {
+    const el = rootRef.current
+    if (!el) return
+    if (typeof IntersectionObserver === 'undefined') {
+      void start()
+      return
+    }
+    const observer = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((e) => e.isIntersecting)) {
+          observer.disconnect()
+          void start()
+        }
+      },
+      { rootMargin: '300px' },
+    )
+    observer.observe(el)
+    return () => observer.disconnect()
+  }, [start])
+
+  useEffect(
+    () => () => {
+      destroyRef.current?.()
+      destroyRef.current = null
+    },
+    [],
+  )
+
+  const showFacade = status !== 'live'
+
+  return (
+    <div ref={rootRef} className={tripMapStyles.container} data-mdx-component="TripMap" aria-label={title}>
+      {title ? <p className={tripMapStyles.head}>{title}</p> : null}
+
+      {/* Server-rendered strip with alt text — what crawlers read; replaced by the live filmstrip. */}
+      {showFacade && facade.thumbs.length > 0 ? (
+        <ol className={tripMapStyles.strip}>
+          {facade.thumbs.map((thumb) => (
+            <li key={thumb.slug} className={tripMapStyles.stripItem}>
+              <img
+                src={thumb.src}
+                alt={thumb.alt}
+                width={80}
+                height={80}
+                loading="lazy"
+                decoding="async"
+                className={tripMapStyles.stripImg}
+              />
+            </li>
+          ))}
+        </ol>
+      ) : null}
+
+      {/*
+        Sized wrapper: the engine host is a static absolutely-positioned child
+        that React never re-patches (reactive props on the engine's container
+        would clobber the classes/children the engine adds); the facade box is
+        an overlay that simply unmounts when the map goes live.
+      */}
+      <div className={tripMapStyles.mapWrap} style={{ height: height || TRIPMAP_DEFAULT_HEIGHT }}>
+        <div ref={mapRef} className="absolute inset-0" />
+        {showFacade ? (
+          <div className={tripMapStyles.mapOverlay}>
+            <div className={tripMapStyles.mapBox}>
+              <span className={tripMapStyles.mapHint}>{status === 'empty' ? texts.empty : texts.hint}</span>
+            </div>
+          </div>
+        ) : null}
+      </div>
+
+      {showFacade && facade.stops.length > 0 ? (
+        <ol className={tripMapStyles.stopList}>
+          {facade.stops.map((stop) => (
+            <li key={stop.key}>
+              {stop.capturedAt ? (
+                <span className={tripMapStyles.stopTime}>{tripMapFormatTime(stop.capturedAt)}</span>
+              ) : null}
+              <span>{stop.title}</span>
+            </li>
+          ))}
+        </ol>
+      ) : null}
+
+      {showFacade ? <p className={tripMapStyles.note}>{texts.unavailable}</p> : null}
+    </div>
+  )
+}

package/src/render/tripmap/article-context.ts

@@ -0,0 +1,35 @@
+'use client'
+
+/**
+ * Article identity for TripMap AUTO mode (map every geotagged media of the
+ * article). The host app wraps its rendered article body in the provider —
+ * the Next blog does in `app/articles/[slug]/page.tsx` AND the draft preview
+ * `app/preview/[token]/page.tsx`; a consumer that doesn't simply has no auto
+ * mode and TripMap needs explicit `slugs` or `nodes`.
+ */
+
+import { createContext, createElement, type ReactNode } from 'react'
+import type { TripMapFacadeMedia } from '@blogmcp/mdx-schema/tripmap'
+
+export interface MdxArticleContextValue {
+  filename: string
+  language?: string
+  /**
+   * The article's geotagged media (`contentImagesGeo`), when the host has
+   * them: the SERVER-RENDERED facade then carries real thumbnails with alt
+   * text and named stops in AUTO mode — what crawlers read. Optional.
+   */
+  media?: readonly TripMapFacadeMedia[] | null
+}
+
+export const MdxArticleContext = createContext<MdxArticleContextValue | null>(null)
+
+export function MdxArticleProvider({
+  value,
+  children,
+}: {
+  value: MdxArticleContextValue | null
+  children: ReactNode
+}) {
+  return createElement(MdxArticleContext.Provider, { value }, children)
+}

package/src/server-render-map.ts

@@ -41,6 +41,7 @@ import Alert from './render/alert/Alert'
 import Badge from './render/badge/Badge'
 import Icon from './render/icon/Icon'
 import Tooltip from './render/tooltip/Tooltip'
+import TripMap from './render/tripmap/TripMap'
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export const serverRenderMap: Record<string, ComponentType<any>> = {
@@ -55,6 +56,7 @@ export const serverRenderMap: Record<string, ComponentType<any>> = {
   Badge,
   Icon,
   Tooltip,
+  TripMap,
 }
 
 /**