@opensite/ui 3.10.0 → 3.11.2

package/dist/instagram-post-grid.cjs

@@ -2,11 +2,9 @@
 'use strict';
 
 var React = require('react');
+var mediaImmersive = require('@page-speed/media-immersive');
 var clsx = require('clsx');
 var tailwindMerge = require('tailwind-merge');
-var img = require('@page-speed/img');
-var video = require('@page-speed/video');
-var pressable = require('@page-speed/pressable');
 var icon = require('@page-speed/icon');
 var jsxRuntime = require('react/jsx-runtime');
 
@@ -423,23 +421,323 @@ var Section = React__namespace.default.forwardRef(
   }
 );
 Section.displayName = "Section";
-function EngagementBadge({
+var IG_TILE_WIDTH = 320;
+var IG_TILE_STYLE = { width: "100%" };
+var IG_TILE_RADIUS = 18;
+var TILE_WRAPPER_STYLE = {
+  position: "relative",
+  borderRadius: IG_TILE_RADIUS,
+  boxShadow: "0 1px 2px rgba(15, 23, 42, 0.08), 0 6px 16px rgba(15, 23, 42, 0.10)"
+};
+var CAPTION_SCRIM_STYLE = {
+  position: "absolute",
+  left: 0,
+  right: 0,
+  bottom: 0,
+  padding: "28px 14px 13px",
+  background: "linear-gradient(180deg, rgba(8,12,24,0) 0%, rgba(8,12,24,0.55) 45%, rgba(8,12,24,0.78) 100%)",
+  borderBottomLeftRadius: IG_TILE_RADIUS,
+  borderBottomRightRadius: IG_TILE_RADIUS,
+  pointerEvents: "none"
+};
+var CAPTION_TEXT_STYLE = {
+  color: "#fff",
+  fontSize: 13,
+  lineHeight: 1.4,
+  fontWeight: 600,
+  letterSpacing: "0.005em",
+  textShadow: "0 1px 2px rgba(0, 0, 0, 0.35)",
+  display: "-webkit-box",
+  WebkitLineClamp: 2,
+  WebkitBoxOrient: "vertical",
+  overflow: "hidden",
+  height: "2.8em"
+};
+var TITLE_MAX = 90;
+function truncate(text, max = TITLE_MAX) {
+  const trimmed = text.trim();
+  if (trimmed.length <= max) return trimmed;
+  const slice = trimmed.slice(0, max);
+  const lastSpace = slice.lastIndexOf(" ");
+  const head = lastSpace > max * 0.6 ? slice.slice(0, lastSpace) : slice;
+  return `${head.trimEnd()}\u2026`;
+}
+function captionToString(caption) {
+  return typeof caption === "string" ? caption : "";
+}
+function toMediaItem(item) {
+  const isVideo = Boolean(item.isVideo && item.videoUrl);
+  const fullCaption = captionToString(item.caption);
+  const title = truncate(fullCaption) || item.imageAlt || "Instagram post";
+  const meta = {
+    href: item.href,
+    likeCount: item.likeCount,
+    commentCount: item.commentCount,
+    viewCount: item.viewCount,
+    date: item.date
+  };
+  return {
+    id: item.id,
+    type: isVideo ? "video" : "image",
+    poster: item.image,
+    // Video source only when the post is a real video (image posts ignore it).
+    src: isVideo ? item.videoUrl : void 0,
+    title,
+    caption: fullCaption || void 0,
+    kind: "Instagram",
+    meta
+  };
+}
+function openPermalink(item) {
+  if (typeof window === "undefined") return;
+  const href = item.meta?.href;
+  if (!href) return;
+  window.open(href, "_blank", "noopener,noreferrer");
+}
+function likeBadge(likeCount) {
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "span",
+    {
+      "aria-label": `${likeCount.toLocaleString()} likes`,
+      style: {
+        display: "inline-flex",
+        alignItems: "center",
+        gap: 6,
+        // Breathing room from the tile's top-left corner (refinement #1).
+        margin: 6,
+        padding: "6px 11px",
+        borderRadius: 999,
+        background: "rgba(8, 12, 24, 0.55)",
+        backdropFilter: "blur(8px)",
+        WebkitBackdropFilter: "blur(8px)",
+        border: "1px solid rgba(255, 255, 255, 0.14)",
+        color: "#fff",
+        fontSize: 13,
+        fontWeight: 600,
+        lineHeight: 1,
+        letterSpacing: "0.01em"
+      },
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx(DynamicIcon, { name: "lucide/heart", size: 15, "aria-hidden": "true" }),
+        /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: likeCount.toLocaleString() })
+      ]
+    }
+  );
+}
+var VIEWER_ACTIONS = [
+  {
+    id: "open-in-instagram",
+    icon: /* @__PURE__ */ jsxRuntime.jsx(DynamicIcon, { name: "lucide/external-link", size: 22, "aria-hidden": "true" }),
+    label: "Instagram",
+    ariaLabel: "Open in Instagram",
+    onPress: (item) => openPermalink(item)
+  }
+];
+function RailStat({
   iconName,
   count,
-  label
+  label,
+  onPress
 }) {
   return /* @__PURE__ */ jsxRuntime.jsxs(
-    "span",
+    "button",
     {
-      className: "inline-flex items-center gap-1",
+      type: "button",
       "aria-label": `${count.toLocaleString()} ${label}`,
+      onClick: (e) => {
+        e.stopPropagation();
+        onPress();
+      },
+      style: {
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: 5,
+        padding: 0,
+        border: "none",
+        background: "transparent",
+        color: "inherit",
+        cursor: "pointer",
+        font: "inherit"
+      },
+      children: [
+        /* @__PURE__ */ jsxRuntime.jsx(
+          "span",
+          {
+            style: {
+              width: 46,
+              height: 46,
+              borderRadius: "50%",
+              background: "var(--psmi-chrome-bg, rgba(255,255,255,0.14))",
+              backdropFilter: "blur(6px)",
+              WebkitBackdropFilter: "blur(6px)",
+              display: "flex",
+              alignItems: "center",
+              justifyContent: "center"
+            },
+            children: /* @__PURE__ */ jsxRuntime.jsx(DynamicIcon, { name: iconName, size: 22, "aria-hidden": "true" })
+          }
+        ),
+        /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", style: { fontSize: 11, fontWeight: 600 }, children: count.toLocaleString() })
+      ]
+    }
+  );
+}
+function InstagramViewerRail({ item }) {
+  const meta = item.meta ?? {};
+  const open = () => openPermalink(item);
+  return /* @__PURE__ */ jsxRuntime.jsxs(
+    "div",
+    {
+      style: {
+        position: "absolute",
+        right: 11,
+        bottom: 135,
+        display: "flex",
+        flexDirection: "column",
+        alignItems: "center",
+        gap: 18,
+        color: "var(--psmi-chrome-fg, #fff)",
+        zIndex: 3
+      },
       children: [
-        /* @__PURE__ */ jsxRuntime.jsx(DynamicIcon, { name: iconName, size: 16, "aria-hidden": "true" }),
-        /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", children: count.toLocaleString() })
+        typeof meta.likeCount === "number" ? /* @__PURE__ */ jsxRuntime.jsx(
+          RailStat,
+          {
+            iconName: "lucide/heart",
+            count: meta.likeCount,
+            label: "likes",
+            onPress: open
+          }
+        ) : null,
+        typeof meta.commentCount === "number" ? /* @__PURE__ */ jsxRuntime.jsx(
+          RailStat,
+          {
+            iconName: "lucide/message-circle",
+            count: meta.commentCount,
+            label: "comments",
+            onPress: open
+          }
+        ) : null,
+        typeof meta.viewCount === "number" ? /* @__PURE__ */ jsxRuntime.jsx(
+          RailStat,
+          {
+            iconName: "lucide/eye",
+            count: meta.viewCount,
+            label: "views",
+            onPress: open
+          }
+        ) : null,
+        meta.href ? /* @__PURE__ */ jsxRuntime.jsxs(
+          "a",
+          {
+            href: meta.href,
+            target: "_blank",
+            rel: "noopener noreferrer",
+            "aria-label": "Open in Instagram",
+            onClick: (e) => e.stopPropagation(),
+            style: {
+              display: "flex",
+              flexDirection: "column",
+              alignItems: "center",
+              gap: 5,
+              padding: 0,
+              border: "none",
+              background: "transparent",
+              color: "inherit",
+              cursor: "pointer",
+              font: "inherit",
+              textDecoration: "none"
+            },
+            children: [
+              /* @__PURE__ */ jsxRuntime.jsx(
+                "span",
+                {
+                  style: {
+                    width: 46,
+                    height: 46,
+                    borderRadius: "50%",
+                    background: "var(--psmi-chrome-bg, rgba(255,255,255,0.14))",
+                    backdropFilter: "blur(6px)",
+                    WebkitBackdropFilter: "blur(6px)",
+                    display: "flex",
+                    alignItems: "center",
+                    justifyContent: "center"
+                  },
+                  children: /* @__PURE__ */ jsxRuntime.jsx(
+                    DynamicIcon,
+                    {
+                      name: "lucide/external-link",
+                      size: 22,
+                      "aria-hidden": "true"
+                    }
+                  )
+                }
+              ),
+              /* @__PURE__ */ jsxRuntime.jsx("span", { "aria-hidden": "true", style: { fontSize: 11, fontWeight: 600 }, children: "Instagram" })
+            ]
+          }
+        ) : null
       ]
     }
   );
 }
+function InstagramFeedGrid({
+  mediaItems,
+  gridClassName,
+  itemClassName,
+  imageClassName,
+  optixFlowConfig
+}) {
+  const { open } = mediaImmersive.useImmersiveFeed();
+  const posterImgProps = React.useMemo(() => {
+    const next = {};
+    if (imageClassName) next.className = imageClassName;
+    if (optixFlowConfig) next.optixFlowConfig = optixFlowConfig;
+    return Object.keys(next).length > 0 ? next : void 0;
+  }, [imageClassName, optixFlowConfig]);
+  return /* @__PURE__ */ jsxRuntime.jsx(
+    "div",
+    {
+      className: cn(
+        "grid grid-cols-2 gap-3 sm:grid-cols-3 lg:grid-cols-4",
+        gridClassName
+      ),
+      children: mediaItems.map((mediaItem) => {
+        const likeCount = mediaItem.meta?.likeCount;
+        return (
+          // The wrapper owns the tile's outer chrome (subtle boundary shadow,
+          // matching radius) and the block's own caption overlay — the card's
+          // built-in caption is hidden so 1- and 2-line captions can share a
+          // fixed-height, top-aligned text box (annotated refinements #2–#4).
+          /* @__PURE__ */ jsxRuntime.jsxs("div", { className: itemClassName, style: TILE_WRAPPER_STYLE, children: [
+            /* @__PURE__ */ jsxRuntime.jsx(
+              mediaImmersive.ThumbnailCard,
+              {
+                item: mediaItem,
+                onOpen: open,
+                size: IG_TILE_WIDTH,
+                style: IG_TILE_STYLE,
+                elevated: false,
+                hideCaption: true,
+                hideProgressHint: true,
+                showDuration: false,
+                glyphMode: "hover",
+                posterImgProps,
+                badgeSlot: typeof likeCount === "number" ? likeBadge(likeCount) : void 0
+              }
+            ),
+            mediaItem.title ? (
+              // aria-hidden: the card already announces the post title; this
+              // overlay is purely visual. pointer-events pass through to the card.
+              /* @__PURE__ */ jsxRuntime.jsx("div", { "aria-hidden": "true", style: CAPTION_SCRIM_STYLE, children: /* @__PURE__ */ jsxRuntime.jsx("div", { style: CAPTION_TEXT_STYLE, children: mediaItem.title }) })
+            ) : null
+          ] }, mediaItem.id)
+        );
+      })
+    }
+  );
+}
 function InstagramPostGrid({
   sectionId = "instagram-post-grid",
   heading,
@@ -447,118 +745,32 @@ function InstagramPostGrid({
   items,
   itemsSlot,
   className,
-  containerClassName,
+  containerClassName = "px-6 sm:px-6 md:px-8 lg:px-8",
+  spacing = "py-12 md:py-32",
   headerClassName,
   headingClassName,
   subheadingClassName,
   gridClassName,
   itemClassName,
   imageClassName,
+  optixFlowConfig,
   background,
-  spacing,
   pattern,
   patternOpacity,
-  patternClassName,
-  optixFlowConfig
+  patternClassName
 }) {
-  const tiles = React.useMemo(() => {
-    if (itemsSlot) return itemsSlot;
-    if (!items || items.length === 0) return null;
-    const visibleItems = items.filter((item) => Boolean(item.image));
-    return visibleItems.map((item) => {
-      const altText = item.imageAlt || (typeof item.caption === "string" ? item.caption : "") || "Instagram post";
-      const showVideo = Boolean(item.isVideo && item.videoUrl);
-      return /* @__PURE__ */ jsxRuntime.jsxs(
-        pressable.Pressable,
-        {
-          href: item.href,
-          "aria-label": typeof item.caption === "string" && item.caption.length > 0 ? item.caption : "View Instagram post",
-          className: cn(
-            "group relative block aspect-square overflow-hidden rounded-md bg-muted",
-            item.className,
-            itemClassName
-          ),
-          children: [
-            /* @__PURE__ */ jsxRuntime.jsx(
-              img.Img,
-              {
-                src: item.image,
-                alt: altText,
-                loading: "lazy",
-                className: cn(
-                  "h-full w-full object-cover object-center transition-transform duration-300 group-hover:scale-105 motion-reduce:transform-none motion-reduce:transition-none",
-                  imageClassName
-                ),
-                optixFlowConfig
-              }
-            ),
-            showVideo && /* @__PURE__ */ jsxRuntime.jsx(
-              video.Video,
-              {
-                src: item.videoUrl,
-                poster: item.image,
-                controls: false,
-                muted: true,
-                loop: true,
-                playsInline: true,
-                preload: "metadata",
-                onMouseEnter: (e) => {
-                  void e.currentTarget.play().catch(() => void 0);
-                },
-                onMouseLeave: (e) => {
-                  e.currentTarget.pause();
-                  e.currentTarget.currentTime = 0;
-                },
-                className: cn(
-                  "absolute inset-0 h-full w-full object-cover object-center opacity-0 transition-opacity duration-300 group-hover:opacity-100 motion-reduce:transition-none",
-                  imageClassName
-                )
-              }
-            ),
-            item.isVideo && /* @__PURE__ */ jsxRuntime.jsx(
-              "span",
-              {
-                className: "absolute right-2 top-2 text-white drop-shadow-md",
-                "aria-hidden": "true",
-                children: /* @__PURE__ */ jsxRuntime.jsx(DynamicIcon, { name: "lucide/play", size: 18 })
-              }
-            ),
-            (item.caption || item.date || typeof item.likeCount === "number" || typeof item.commentCount === "number" || typeof item.viewCount === "number") && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "pointer-events-none absolute inset-x-0 bottom-0 flex flex-col gap-1 bg-linear-to-t from-black/70 to-transparent p-3 text-left text-white opacity-0 transition-opacity duration-300 group-hover:opacity-100 motion-reduce:transition-none", children: [
-              item.caption && (typeof item.caption === "string" ? /* @__PURE__ */ jsxRuntime.jsx("p", { className: "line-clamp-2 text-xs leading-snug wrap-break-word", children: item.caption }) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: "line-clamp-2 text-xs leading-snug", children: item.caption })),
-              (typeof item.likeCount === "number" || typeof item.commentCount === "number" || typeof item.viewCount === "number" || item.date) && /* @__PURE__ */ jsxRuntime.jsxs("div", { className: "flex items-center gap-3 text-xs font-medium", children: [
-                typeof item.likeCount === "number" && /* @__PURE__ */ jsxRuntime.jsx(
-                  EngagementBadge,
-                  {
-                    iconName: "lucide/heart",
-                    count: item.likeCount,
-                    label: "likes"
-                  }
-                ),
-                typeof item.commentCount === "number" && /* @__PURE__ */ jsxRuntime.jsx(
-                  EngagementBadge,
-                  {
-                    iconName: "lucide/message-circle",
-                    count: item.commentCount,
-                    label: "comments"
-                  }
-                ),
-                typeof item.viewCount === "number" && /* @__PURE__ */ jsxRuntime.jsx(
-                  EngagementBadge,
-                  {
-                    iconName: "lucide/eye",
-                    count: item.viewCount,
-                    label: "views"
-                  }
-                ),
-                item.date && /* @__PURE__ */ jsxRuntime.jsx("span", { className: "ml-auto opacity-80", children: item.date })
-              ] })
-            ] })
-          ]
-        },
-        item.id
+  const mediaItems = React.useMemo(() => {
+    if (itemsSlot || !items) return [];
+    const withImage = items.filter((item) => Boolean(item.image));
+    if (process.env.NODE_ENV !== "production" && withImage.length < items.length) {
+      const skipped = items.filter((item) => !item.image);
+      const skippedIds = skipped.map((item) => item.id).join(", ");
+      console.warn(
+        `[instagram-post-grid] skipped ${skipped.length} item(s) without a resolvable image: ${skippedIds}`
       );
-    });
-  }, [itemsSlot, items, itemClassName, imageClassName, optixFlowConfig]);
+    }
+    return withImage.map(toMediaItem);
+  }, [items, itemsSlot]);
   if (!itemsSlot && (!items || items.length === 0)) {
     return null;
   }
@@ -596,16 +808,34 @@ function InstagramPostGrid({
             }
           ) : /* @__PURE__ */ jsxRuntime.jsx("div", { className: subheadingClassName, children: subheading }))
         ] }),
-        /* @__PURE__ */ jsxRuntime.jsx(
+        itemsSlot ? /* @__PURE__ */ jsxRuntime.jsx(
           "div",
           {
             className: cn(
-              "grid grid-cols-2 gap-2 sm:grid-cols-3 lg:grid-cols-4",
+              "grid grid-cols-2 gap-3 sm:grid-cols-3 lg:grid-cols-4",
               gridClassName
             ),
-            children: tiles
+            children: itemsSlot
           }
-        )
+        ) : /* @__PURE__ */ jsxRuntime.jsxs(mediaImmersive.ImmersiveFeedProvider, { items: mediaItems, actions: VIEWER_ACTIONS, children: [
+          /* @__PURE__ */ jsxRuntime.jsx(
+            InstagramFeedGrid,
+            {
+              mediaItems,
+              gridClassName,
+              itemClassName,
+              imageClassName,
+              optixFlowConfig
+            }
+          ),
+          /* @__PURE__ */ jsxRuntime.jsx(
+            mediaImmersive.ImmersiveViewer,
+            {
+              ariaLabel: "Instagram post viewer",
+              renderActions: ({ item }) => /* @__PURE__ */ jsxRuntime.jsx(InstagramViewerRail, { item })
+            }
+          )
+        ] })
       ]
     }
   );

package/dist/instagram-post-grid.d.cts

@@ -31,7 +31,15 @@ interface InstagramPostItem {
      */
     imageAlt?: string;
     /**
-     * Post caption (truncated for display)
+     * Post caption (truncated for display).
+     *
+     * NOTE: For immersive rendering the caption must be a **string** — the
+     * library's `MediaItem.title`/`caption` are string-typed, so a caption is
+     * flowed through as text. A rich `ReactNode` caption (hand-authored markup,
+     * only ever used by the legacy pre-immersive block) cannot be threaded into
+     * the immersive card/viewer; when supplied it is dropped and the tile/viewer
+     * title falls back to `imageAlt` (then `"Instagram post"`). Hydrated feeds
+     * always send plain strings, so this only affects hand-authored usage.
      */
     caption?: React.ReactNode;
     /**
@@ -140,17 +148,32 @@ interface InstagramPostGridProps {
     sectionId?: string;
 }
 /**
- * InstagramPostGrid displays a responsive, square-tiled grid of Instagram posts.
+ * InstagramPostGrid displays a website's Instagram feed as a responsive grid of
+ * vertical (9:16) tiles that open a fullscreen, swipeable immersive viewer.
  *
- * Each tile links out to the post's instagram.com permalink in a new tab. Images
- * render via `@page-speed/img`; video posts render an in-grid `@page-speed/video`
- * that plays muted on hover (progressive/on-interaction). Captions are truncated,
- * an optional date is shown, and like/comment/view badges appear only when the
- * corresponding count is present — never fabricated. Posts without an image are
- * skipped; an empty or missing `items` array renders nothing.
+ * Composition is powered by `@page-speed/media-immersive`: each post maps to a
+ * `MediaItem` (photos are first-class images, reels are videos), tiles are
+ * `ThumbnailCard`s, and tapping one opens `ImmersiveViewer` — a TikTok/Reels-
+ * style pager. Per the annotated design, each tile shows a like-count pill
+ * top-left (only when a numeric like count exists — never fabricated), no
+ * duration timestamp, and a center glyph on hover only (a play triangle for
+ * reels, an expand icon for photos). The fullscreen viewer carries the caption
+ * plus a read-only engagement rail (likes/comments/views) and an explicit
+ * "Open in Instagram" egress rendered as a real `<a target="_blank"
+ * rel="noopener noreferrer">` (a crawlable, affordance-correct link — not a
+ * scripted `window.open` button); the old whole-tile link-out is REPLACED by
+ * opening the viewer, with the permalink egress living in the viewer.
  *
- * Data is hydrated from the toastability Instagram feed. Media URLs are the
- * re-hosted MediaRecord CDN URLs, never expiring Instagram CDN URLs.
+ * Consumer image concerns are honored: `imageClassName` and `optixFlowConfig`
+ * are forwarded onto each tile's poster image via the library's
+ * `posterImgProps` passthrough.
+ *
+ * Captions should be plain strings when used with immersive rendering; a rich
+ * `ReactNode` caption falls back to `imageAlt` (see the `caption` field doc).
+ *
+ * Posts without an image are skipped; an empty or missing `items` array renders
+ * nothing. Data is hydrated from the toastability Instagram feed — media URLs
+ * are the re-hosted MediaRecord CDN URLs, never expiring Instagram CDN URLs.
  *
  * @example
  * ```tsx
@@ -169,6 +192,6 @@ interface InstagramPostGridProps {
  * />
  * ```
  */
-declare function InstagramPostGrid({ sectionId, heading, subheading, items, itemsSlot, className, containerClassName, headerClassName, headingClassName, subheadingClassName, gridClassName, itemClassName, imageClassName, background, spacing, pattern, patternOpacity, patternClassName, optixFlowConfig, }: InstagramPostGridProps): React.JSX.Element | null;
+declare function InstagramPostGrid({ sectionId, heading, subheading, items, itemsSlot, className, containerClassName, spacing, headerClassName, headingClassName, subheadingClassName, gridClassName, itemClassName, imageClassName, optixFlowConfig, background, pattern, patternOpacity, patternClassName, }: InstagramPostGridProps): React.JSX.Element | null;
 
 export { InstagramPostGrid, type InstagramPostGridProps, type InstagramPostItem };

package/dist/instagram-post-grid.d.ts

@@ -31,7 +31,15 @@ interface InstagramPostItem {
      */
     imageAlt?: string;
     /**
-     * Post caption (truncated for display)
+     * Post caption (truncated for display).
+     *
+     * NOTE: For immersive rendering the caption must be a **string** — the
+     * library's `MediaItem.title`/`caption` are string-typed, so a caption is
+     * flowed through as text. A rich `ReactNode` caption (hand-authored markup,
+     * only ever used by the legacy pre-immersive block) cannot be threaded into
+     * the immersive card/viewer; when supplied it is dropped and the tile/viewer
+     * title falls back to `imageAlt` (then `"Instagram post"`). Hydrated feeds
+     * always send plain strings, so this only affects hand-authored usage.
      */
     caption?: React.ReactNode;
     /**
@@ -140,17 +148,32 @@ interface InstagramPostGridProps {
     sectionId?: string;
 }
 /**
- * InstagramPostGrid displays a responsive, square-tiled grid of Instagram posts.
+ * InstagramPostGrid displays a website's Instagram feed as a responsive grid of
+ * vertical (9:16) tiles that open a fullscreen, swipeable immersive viewer.
  *
- * Each tile links out to the post's instagram.com permalink in a new tab. Images
- * render via `@page-speed/img`; video posts render an in-grid `@page-speed/video`
- * that plays muted on hover (progressive/on-interaction). Captions are truncated,
- * an optional date is shown, and like/comment/view badges appear only when the
- * corresponding count is present — never fabricated. Posts without an image are
- * skipped; an empty or missing `items` array renders nothing.
+ * Composition is powered by `@page-speed/media-immersive`: each post maps to a
+ * `MediaItem` (photos are first-class images, reels are videos), tiles are
+ * `ThumbnailCard`s, and tapping one opens `ImmersiveViewer` — a TikTok/Reels-
+ * style pager. Per the annotated design, each tile shows a like-count pill
+ * top-left (only when a numeric like count exists — never fabricated), no
+ * duration timestamp, and a center glyph on hover only (a play triangle for
+ * reels, an expand icon for photos). The fullscreen viewer carries the caption
+ * plus a read-only engagement rail (likes/comments/views) and an explicit
+ * "Open in Instagram" egress rendered as a real `<a target="_blank"
+ * rel="noopener noreferrer">` (a crawlable, affordance-correct link — not a
+ * scripted `window.open` button); the old whole-tile link-out is REPLACED by
+ * opening the viewer, with the permalink egress living in the viewer.
  *
- * Data is hydrated from the toastability Instagram feed. Media URLs are the
- * re-hosted MediaRecord CDN URLs, never expiring Instagram CDN URLs.
+ * Consumer image concerns are honored: `imageClassName` and `optixFlowConfig`
+ * are forwarded onto each tile's poster image via the library's
+ * `posterImgProps` passthrough.
+ *
+ * Captions should be plain strings when used with immersive rendering; a rich
+ * `ReactNode` caption falls back to `imageAlt` (see the `caption` field doc).
+ *
+ * Posts without an image are skipped; an empty or missing `items` array renders
+ * nothing. Data is hydrated from the toastability Instagram feed — media URLs
+ * are the re-hosted MediaRecord CDN URLs, never expiring Instagram CDN URLs.
  *
  * @example
  * ```tsx
@@ -169,6 +192,6 @@ interface InstagramPostGridProps {
  * />
  * ```
  */
-declare function InstagramPostGrid({ sectionId, heading, subheading, items, itemsSlot, className, containerClassName, headerClassName, headingClassName, subheadingClassName, gridClassName, itemClassName, imageClassName, background, spacing, pattern, patternOpacity, patternClassName, optixFlowConfig, }: InstagramPostGridProps): React.JSX.Element | null;
+declare function InstagramPostGrid({ sectionId, heading, subheading, items, itemsSlot, className, containerClassName, spacing, headerClassName, headingClassName, subheadingClassName, gridClassName, itemClassName, imageClassName, optixFlowConfig, background, pattern, patternOpacity, patternClassName, }: InstagramPostGridProps): React.JSX.Element | null;
 
 export { InstagramPostGrid, type InstagramPostGridProps, type InstagramPostItem };