@blogmcp/mdx-render-react 0.4.0 → 0.6.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/render/tripmap/TripMap.js

@@ -1,13 +1,13 @@
 "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");
+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 {
@@ -15,93 +15,97 @@ function se(p) {
             if (!e.ok) throw new Error(`media/geo ${e.status}`);
             return await e.json();
           } catch (e) {
-            if (C) return { nodes: [] };
+            if (E) 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) => ({
+        }, [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
-        })), H = i.buildTripNodes(v, c);
-        if (H.length === 0 || !f.current) {
-          o("empty");
+        })), C = l.buildTripNodes(N, S);
+        if (C.length === 0 || !g.current) {
+          u("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 });
+        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 i.TripMap(f.current, {
-          styleUrl: F || s.config?.styleUrl || "",
+        const w = new l.TripMap(g.current, {
+          styleUrl: I || s.config?.styleUrl || "",
           darkStyleUrl: s.config?.darkStyleUrl,
-          theme: k ?? "auto",
-          cluster: I ?? !0,
+          theme: F ?? "auto",
+          cluster: A ?? !0,
           showLine: U ?? !0,
-          showFilmstrip: A ?? !0,
-          showPlayback: _ ?? !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: E,
-          initialView: O,
+          labels: O,
+          initialView: G,
           events: {}
         });
-        w.setNodes(H), await w.init(), g.current = () => w.destroy(), o("live");
+        w.setNodes(C), await w.init(), y.current = () => w.destroy(), u("live");
       } catch {
-        o((t) => t === "loading" ? "facade" : t);
+        u((t) => t === "loading" ? "facade" : t);
       }
     }
-  }, [j, C, c, F, k, I, U, A, E, m, R]);
-  G(() => {
+  }, [j, E, S, I, F, A, U, k, O, f, R, c, h]);
+  _(() => {
     const t = L.current;
     if (!t) return;
     if (typeof IntersectionObserver > "u") {
-      N();
+      v();
       return;
     }
-    const i = new IntersectionObserver(
+    const l = new IntersectionObserver(
       (s) => {
-        s.some((v) => v.isIntersecting) && (i.disconnect(), N());
+        s.some((N) => N.isIntersecting) && (l.disconnect(), v());
       },
       { rootMargin: "300px" }
     );
-    return i.observe(t), () => i.disconnect();
-  }, [N]), G(
+    return l.observe(t), () => l.disconnect();
+  }, [v]), _(
     () => () => {
-      g.current?.(), g.current = null;
+      y.current?.(), y.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(
+  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: `/api/media/thumb/${encodeURIComponent(t)}?width=192`,
-        alt: "",
+        src: t.src,
+        alt: t.alt,
         width: 80,
         height: 80,
         loading: "lazy",
         decoding: "async",
-        className: a.stripImg
+        className: r.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
+    ) }, 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
     ] }),
-    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
+    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 {
-  se as default
+  de as default
 };

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

@@ -6,9 +6,23 @@
  * 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;
+    /**
+     * Set ONLY by a draft preview: the draft-preview token of the page (`/preview/<token>`).
+     * AUTO mode then asks kb-api for the article's WORKING COPY photo set; without it a draft
+     * maps nothing (a reader's request for a draft is a 404) and an article with unpublished
+     * edits maps its published photos. Never set it on a published page.
+     */
+    previewToken?: 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, }: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blogmcp/mdx-render-react",
-  "version": "0.4.0",
+  "version": "0.6.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,14 +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.4.0",
-    "@blogmcp/tripmap-core": "^0.1.0",
-    "@blogmcp/sanitize": "^0.3.0",
-    "@blogmcp/sdk": "^0.3.0",
+    "@blogmcp/mdx-schema": "^0.6.0",
+    "@blogmcp/tripmap-core": "^0.1.2",
+    "@blogmcp/sanitize": "^0.6.0",
+    "@blogmcp/sdk": "^0.6.0",
     "@iconify/react": "^6.0.0",
     "marked": "^15.0.7"
   },

package/src/render/tripmap/TripMap.tsx

@@ -23,6 +23,7 @@ import {
   tripMapPlaybackLabels,
   tripMapUiTexts,
   type TripMapGeoResponse,
+  tripMapFacade,
 } from '@blogmcp/mdx-schema/tripmap'
 
 import { MdxArticleContext } from './article-context'
@@ -30,11 +31,13 @@ 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 { 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')
@@ -46,6 +49,7 @@ export default function TripMap(props: TripMapProps) {
   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
@@ -75,6 +79,7 @@ export default function TripMap(props: TripMapProps) {
           capturedAt: n.capturedAt ?? undefined,
           thumbnailUrl: n.thumbnailUrl ?? undefined,
           imageUrl: n.url ?? undefined,
+          largeImageUrl: n.largeUrl ?? undefined,
           altText: n.altText ?? undefined,
           title: n.placeName ?? undefined,
         }))
@@ -96,6 +101,9 @@ export default function TripMap(props: TripMapProps) {
         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,
@@ -110,7 +118,7 @@ export default function TripMap(props: TripMapProps) {
       // 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])
+  }, [geoUrl, configOnly, handNodes, styleUrl, theme, cluster, line, filmstrip, labels, center, zoom, title, detail])
 
   useEffect(() => {
     const el = rootRef.current
@@ -146,13 +154,14 @@ export default function TripMap(props: TripMapProps) {
     <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 ? (
+      {/* Server-rendered strip with alt text — what crawlers read; replaced by the live filmstrip. */}
+      {showFacade && facade.thumbs.length > 0 ? (
         <ol className={tripMapStyles.strip}>
-          {slugList.map((slug) => (
-            <li key={slug} className={tripMapStyles.stripItem}>
+          {facade.thumbs.map((thumb) => (
+            <li key={thumb.slug} className={tripMapStyles.stripItem}>
               <img
-                src={`/api/media/thumb/${encodeURIComponent(slug)}?width=192`}
-                alt=""
+                src={thumb.src}
+                alt={thumb.alt}
                 width={80}
                 height={80}
                 loading="lazy"
@@ -181,14 +190,14 @@ export default function TripMap(props: TripMapProps) {
         ) : null}
       </div>
 
-      {showFacade && handNodes.length > 0 ? (
+      {showFacade && facade.stops.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>
+          {facade.stops.map((stop) => (
+            <li key={stop.key}>
+              {stop.capturedAt ? (
+                <span className={tripMapStyles.stopTime}>{tripMapFormatTime(stop.capturedAt)}</span>
               ) : null}
-              <span>{node.title || `${node.lat}, ${node.lng}`}</span>
+              <span>{stop.title}</span>
             </li>
           ))}
         </ol>

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

@@ -9,10 +9,24 @@
  */
 
 import { createContext, createElement, type ReactNode } from 'react'
+import type { TripMapFacadeMedia } from '@blogmcp/mdx-schema/tripmap'
 
 export interface MdxArticleContextValue {
   filename: string
   language?: string
+  /**
+   * Set ONLY by a draft preview: the draft-preview token of the page (`/preview/<token>`).
+   * AUTO mode then asks kb-api for the article's WORKING COPY photo set; without it a draft
+   * maps nothing (a reader's request for a draft is a 404) and an article with unpublished
+   * edits maps its published photos. Never set it on a published page.
+   */
+  previewToken?: 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)