@blogmcp/mdx-render-react 0.3.0 → 0.4.0

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

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

@@ -0,0 +1,17 @@
+/**
+ * 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';
+export interface MdxArticleContextValue {
+    filename: string;
+    language?: string;
+}
+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.4.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": {
@@ -36,7 +36,8 @@
   },
   "dependencies": {
     "@ark-ui/react": "^5.0.0",
-    "@blogmcp/mdx-schema": "^0.3.0",
+    "@blogmcp/mdx-schema": "^0.4.0",
+    "@blogmcp/tripmap-core": "^0.1.0",
     "@blogmcp/sanitize": "^0.3.0",
     "@blogmcp/sdk": "^0.3.0",
     "@iconify/react": "^6.0.0",

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,200 @@
+'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,
+} 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 } = props
+  const article = useContext(MdxArticleContext)
+
+  const rootRef = useRef<HTMLDivElement | null>(null)
+  const mapRef = 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 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,
+          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,
+        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])
+
+  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}
+
+      {showFacade && slugList.length > 0 ? (
+        <ol className={tripMapStyles.strip}>
+          {slugList.map((slug) => (
+            <li key={slug} className={tripMapStyles.stripItem}>
+              <img
+                src={`/api/media/thumb/${encodeURIComponent(slug)}?width=192`}
+                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 && handNodes.length > 0 ? (
+        <ol className={tripMapStyles.stopList}>
+          {handNodes.map((node, i) => (
+            <li key={node.id || i}>
+              {node.capturedAt ? (
+                <span className={tripMapStyles.stopTime}>{tripMapFormatTime(node.capturedAt)}</span>
+              ) : null}
+              <span>{node.title || `${node.lat}, ${node.lng}`}</span>
+            </li>
+          ))}
+        </ol>
+      ) : null}
+
+      {showFacade ? <p className={tripMapStyles.note}>{texts.unavailable}</p> : null}
+    </div>
+  )
+}

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

@@ -0,0 +1,28 @@
+'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'
+
+export interface MdxArticleContextValue {
+  filename: string
+  language?: string
+}
+
+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,
 }
 
 /**