@bygghammar/cms-platform 0.61.1 → 0.62.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bygghammar/cms-platform",
-  "version": "0.61.1",
+  "version": "0.62.0",
   "description": "Shared CMS platform: blocks, block types, i18n core, UI primitives and design-token contract used by every Bygghammar/Voyara site.",
   "type": "module",
   "sideEffects": [
@@ -219,7 +219,10 @@
     "./server/page-seo-save-core": "./src/server/page-seo-save-core.ts",
     "./site/routes/public-page": "./src/site/routes/public-page.tsx",
     "./site/routes/preview-page": "./src/site/routes/preview-page.tsx",
-    "./site/routes/section-preview": "./src/site/routes/section-preview.tsx"
+    "./site/routes/section-preview": "./src/site/routes/section-preview.tsx",
+    "./media/priority": "./src/media/priority.tsx",
+    "./media/preload": "./src/media/preload.ts",
+    "./ui/NearViewport": "./src/ui/NearViewport.tsx"
   },
   "dependencies": {
     "fflate": "^0.8.3"

package/src/blocks/components/HeroFullBlock.tsx

@@ -2,6 +2,7 @@ import { ArrowRight, ChevronDown } from "lucide-react";
 import { useT } from "../../i18n";
 import { FocalImage } from "../../host";
 import { LazyVideo } from "../../host";
+import { useClaimPriority } from "../../media/priority";
 import type { HeroFullProps } from "../types";
 
 const HEIGHTS: Record<NonNullable<HeroFullProps["height"]>, string> = {
@@ -56,6 +57,12 @@ export function HeroFullBlock({ props: p }: { props: HeroFullProps }) {
   const poster = p.posterSrc;
   const posterMobile = p.posterSrcMobile || poster;
 
+  // A hero image is a candidate for the page's one priority image, but only the
+  // first block to ask wins: an editor can place a hero halfway down a page.
+  const heroIsPriority = useClaimPriority(
+    mediaType === "image" ? image || imageMobile : null,
+  );
+
   const alignClass =
     align === "center" ? "items-center text-center" : align === "right" ? "items-end text-right" : "items-start text-left";
   const rowClass =
@@ -128,25 +135,23 @@ export function HeroFullBlock({ props: p }: { props: HeroFullProps }) {
             />
           </>
         ) : image || imageMobile ? (
-          <>
-            {image ? (
-              <FocalImage
-                src={image}
-                alt={t(p.imageAlt) || ""}
-                sizes="100vw"
-                className="hidden size-full object-cover md:block"
-              />
-            ) : null}
-            {imageMobile ? (
-              <FocalImage
-                src={imageMobile}
-                alt={t(p.imageAlt) || ""}
-                sizes="100vw"
-                className="size-full object-cover md:hidden"
-              />
-            ) : null}
-          </>
+          // One <picture> with one <img>: two CSS-hidden images can both be
+          // fetched, so the hidden twin would double the hero's cost. The
+          // mobile artwork becomes a media-scoped <source> instead.
+          <FocalImage
+            src={image || imageMobile}
+            artDirected={
+              imageMobile && image && imageMobile !== image
+                ? [{ media: "(max-width: 767px)", src: imageMobile }]
+                : undefined
+            }
+            alt={t(p.imageAlt) || ""}
+            sizes="100vw"
+            priority={heroIsPriority}
+            className="size-full object-cover"
+          />
         ) : null}
+
         <div className={`absolute inset-0 ${OVERLAYS[p.overlay ?? "medium"]}`} />
       </div>
 

package/src/blocks/components/InstagramBlock.tsx

@@ -1,7 +1,9 @@
+import { lazy, Suspense } from "react";
 import { Instagram as InstagramIcon, ExternalLink } from "lucide-react";
 import { useT } from "../../i18n";
-import type { InstagramProps, InstagramItem } from "../types";
-import { FocalImage } from "../../host";
+import type { InstagramProps } from "../types";
+import { NearViewport, ChunkErrorBoundary } from "../../ui/NearViewport";
+import { ASPECT_CLASS } from "./InstagramTiles";
 
 const GAP_CLASS: Record<NonNullable<InstagramProps["gap"]>, string> = {
   none: "gap-0",
@@ -10,61 +12,16 @@ const GAP_CLASS: Record<NonNullable<InstagramProps["gap"]>, string> = {
   lg: "gap-5 md:gap-8",
 };
 
-const ASPECT_CLASS: Record<NonNullable<InstagramProps["aspect"]>, string> = {
-  square: "aspect-square",
-  portrait: "aspect-[4/5]",
-  landscape: "aspect-[4/3]",
-};
+// Dynamic import + a near-viewport gate. `lazy` alone would fetch the chunk on
+// first render, which is exactly what we are trying to avoid for a wall of
+// photos that usually sits at the bottom of the page.
+const InstagramTiles = lazy(() => import("./InstagramTiles"));
 
 function clamp(n: number | undefined, min: number, max: number, fallback: number) {
   const v = typeof n === "number" && Number.isFinite(n) ? n : fallback;
   return Math.min(max, Math.max(min, v));
 }
 
-function Tile({
-  item,
-  aspect,
-  showOverlay,
-}: {
-  item: InstagramItem;
-  aspect: NonNullable<InstagramProps["aspect"]>;
-  showOverlay: boolean;
-}) {
-  const { t } = useT();
-  const alt = item.alt ? t(item.alt as Parameters<typeof t>[0]) : "";
-  const inner = (
-    <div className={`relative ${ASPECT_CLASS[aspect]} bg-ink/5 overflow-hidden group`}>
-      {item.image ? (
-        <FocalImage
-          src={item.image}
-          responsive={false}
-          alt={alt}
-          loading="lazy"
-          className="absolute inset-0 h-full w-full object-cover transition-transform duration-500 group-hover:scale-105"
-        />
-      ) : (
-        <div className="absolute inset-0 grid place-items-center text-ink/25">
-          <InstagramIcon className="size-8" />
-        </div>
-      )}
-      {showOverlay && item.image ? (
-        <div className="absolute inset-0 grid place-items-center bg-ink/0 group-hover:bg-ink/40 transition-colors">
-          <InstagramIcon className="size-6 text-paper opacity-0 group-hover:opacity-100 transition-opacity" />
-        </div>
-      ) : null}
-    </div>
-  );
-
-  if (item.href) {
-    return (
-      <a href={item.href} target="_blank" rel="noreferrer noopener" className="block">
-        {inner}
-      </a>
-    );
-  }
-  return inner;
-}
-
 export function InstagramBlock({ props }: { props: InstagramProps }) {
   const { t } = useT();
   const layout = props.layout ?? "grid";
@@ -85,11 +42,27 @@ export function InstagramBlock({ props }: { props: InstagramProps }) {
   const profileHref =
     props.profileHref ?? (handle ? `https://instagram.com/${handle}` : undefined);
 
-  // Inline styles for arbitrary column counts (Tailwind JIT can't infer runtime numbers).
-  const gridStyle = {
-    display: "grid",
-    gridTemplateColumns: `repeat(var(--ig-cols, ${cM}), minmax(0, 1fr))`,
-  } as React.CSSProperties;
+  // Reserve the tile wall's height so nothing moves when the chunk arrives:
+  // the same aspect ratio, the same number of rows, the same gaps.
+  const reservedRows = layout === "grid" ? rows : 1;
+  const placeholder = (
+    <div className={`ig-reserve ${gap}`} style={{ display: "grid", gridTemplateColumns: "1fr" }}>
+      {Array.from({ length: reservedRows }).map((_, r) => (
+        <div key={r} className={`${ASPECT_CLASS[aspect]} w-full bg-ink/5`} />
+      ))}
+    </div>
+  );
+
+  const staticFallback = profileHref ? (
+    <a
+      href={profileHref}
+      target="_blank"
+      rel="noreferrer noopener"
+      className="inline-flex items-center gap-2 text-sm text-ink underline"
+    >
+      View the photos on Instagram <ExternalLink className="size-3.5" />
+    </a>
+  ) : null;
 
   return (
     <section className="bg-white py-20 md:py-28">
@@ -122,38 +95,28 @@ export function InstagramBlock({ props }: { props: InstagramProps }) {
           </div>
         ) : null}
 
-        {layout === "carousel" ? (
-          <div className={`flex overflow-x-auto snap-x snap-mandatory ${gap} -mx-6 px-6 pb-2`}>
-            {items.map((item) => (
-              <div
-                key={item.id}
-                className="snap-start shrink-0"
-                style={{ width: `min(80vw, ${100 / cD}%)` }}
-              >
-                <Tile item={item} aspect={aspect} showOverlay={showOverlay} />
-              </div>
-            ))}
-          </div>
+        {items.length > 0 ? (
+          <NearViewport placeholder={placeholder}>
+            <ChunkErrorBoundary fallback={staticFallback}>
+              <Suspense fallback={placeholder}>
+                <InstagramTiles
+                  items={items}
+                  layout={layout}
+                  aspect={aspect}
+                  showOverlay={showOverlay}
+                  gap={gap}
+                  columnsMobile={cM}
+                  columnsTablet={cT}
+                  columnsDesktop={cD}
+                />
+              </Suspense>
+            </ChunkErrorBoundary>
+          </NearViewport>
         ) : (
-          <>
-            <style>{`
-              .ig-grid { --ig-cols: ${cM}; }
-              @media (min-width: 768px) { .ig-grid { --ig-cols: ${cT}; } }
-              @media (min-width: 1024px) { .ig-grid { --ig-cols: ${cD}; } }
-            `}</style>
-            <div className={`ig-grid ${gap}`} style={gridStyle}>
-              {items.map((item) => (
-                <Tile key={item.id} item={item} aspect={aspect} showOverlay={showOverlay} />
-              ))}
-            </div>
-          </>
-        )}
-
-        {items.length === 0 ? (
           <div className="mt-8 border border-dashed border-ink/15 p-10 text-center text-ink/70 text-sm">
             No Instagram posts yet. Add images in the block inspector.
           </div>
-        ) : null}
+        )}
       </div>
     </section>
   );

package/src/blocks/components/InstagramTiles.tsx

@@ -0,0 +1,138 @@
+/**
+ * The Instagram grid/carousel itself, in its own chunk.
+ *
+ * The block's heading, handle and profile link stay in the server-rendered
+ * HTML (they are content, and crawlers should see them); the tile wall — dozens
+ * of images plus the scroll/grid machinery — is only imported once the reader
+ * approaches it. See `InstagramBlock`.
+ */
+import { Instagram as InstagramIcon } from "lucide-react";
+import { useT } from "../../i18n";
+import { FocalImage } from "../../host";
+import type { InstagramProps, InstagramItem } from "../types";
+
+export const ASPECT_CLASS: Record<NonNullable<InstagramProps["aspect"]>, string> = {
+  square: "aspect-square",
+  portrait: "aspect-[4/5]",
+  landscape: "aspect-[4/3]",
+};
+
+export type InstagramTilesProps = {
+  items: InstagramItem[];
+  layout: NonNullable<InstagramProps["layout"]>;
+  aspect: NonNullable<InstagramProps["aspect"]>;
+  showOverlay: boolean;
+  gap: string;
+  columnsMobile: number;
+  columnsTablet: number;
+  columnsDesktop: number;
+};
+
+function Tile({
+  item,
+  aspect,
+  showOverlay,
+  sizes,
+}: {
+  item: InstagramItem;
+  aspect: NonNullable<InstagramProps["aspect"]>;
+  showOverlay: boolean;
+  sizes: string;
+}) {
+  const { t } = useT();
+  const alt = item.alt ? t(item.alt as Parameters<typeof t>[0]) : "";
+  const inner = (
+    <div className={`relative ${ASPECT_CLASS[aspect]} bg-ink/5 overflow-hidden group`}>
+      {item.image ? (
+        <FocalImage
+          src={item.image}
+          sizes={sizes}
+          alt={alt}
+          className="absolute inset-0 h-full w-full object-cover transition-transform duration-500 group-hover:scale-105"
+        />
+      ) : (
+        <div className="absolute inset-0 grid place-items-center text-ink/25">
+          <InstagramIcon className="size-8" />
+        </div>
+      )}
+      {showOverlay && item.image ? (
+        <div className="absolute inset-0 grid place-items-center bg-ink/0 group-hover:bg-ink/40 transition-colors">
+          <InstagramIcon className="size-6 text-paper opacity-0 group-hover:opacity-100 transition-opacity" />
+        </div>
+      ) : null}
+    </div>
+  );
+
+  if (item.href) {
+    return (
+      <a href={item.href} target="_blank" rel="noreferrer noopener" className="block">
+        {inner}
+      </a>
+    );
+  }
+  return inner;
+}
+
+/**
+ * `sizes` for one tile in a column grid: the tile is roughly the container width
+ * divided by the column count at that breakpoint, so the browser never fetches
+ * a full-width variant for a quarter-width tile.
+ */
+export function tileSizes(cM: number, cT: number, cD: number): string {
+  const pct = (cols: number) => `${Math.round(100 / Math.max(1, cols))}vw`;
+  return [
+    `(max-width: 767px) ${pct(cM)}`,
+    `(max-width: 1023px) ${pct(cT)}`,
+    `${Math.round(1280 / Math.max(1, cD))}px`,
+  ].join(", ");
+}
+
+export function InstagramTiles({
+  items,
+  layout,
+  aspect,
+  showOverlay,
+  gap,
+  columnsMobile: cM,
+  columnsTablet: cT,
+  columnsDesktop: cD,
+}: InstagramTilesProps) {
+  const sizes = tileSizes(cM, cT, cD);
+  const gridStyle = {
+    display: "grid",
+    gridTemplateColumns: `repeat(var(--ig-cols, ${cM}), minmax(0, 1fr))`,
+  } as React.CSSProperties;
+
+  if (layout === "carousel") {
+    return (
+      <div className={`flex overflow-x-auto snap-x snap-mandatory ${gap} -mx-6 px-6 pb-2`}>
+        {items.map((item) => (
+          <div
+            key={item.id}
+            className="snap-start shrink-0"
+            style={{ width: `min(80vw, ${100 / Math.max(1, cD)}%)` }}
+          >
+            <Tile item={item} aspect={aspect} showOverlay={showOverlay} sizes={sizes} />
+          </div>
+        ))}
+      </div>
+    );
+  }
+
+  return (
+    <>
+      <style>{`
+        .ig-grid { --ig-cols: ${cM}; }
+        @media (min-width: 768px) { .ig-grid { --ig-cols: ${cT}; } }
+        @media (min-width: 1024px) { .ig-grid { --ig-cols: ${cD}; } }
+      `}</style>
+      <div className={`ig-grid ${gap}`} style={gridStyle}>
+        {items.map((item) => (
+          <Tile key={item.id} item={item} aspect={aspect} showOverlay={showOverlay} sizes={sizes} />
+        ))}
+      </div>
+    </>
+  );
+}
+
+export default InstagramTiles;

package/src/blocks/components/MediaSplitBlock.tsx

@@ -7,6 +7,7 @@ import { Reveal } from "../../ui/Reveal";
 import { Lightbox } from "../../ui/Lightbox";
 import { FocalImage } from "../../host";
 import { LazyVideo } from "../../host";
+import { useClaimPriority } from "../../media/priority";
 import type { MediaSplitProps, MediaSplitSlide } from "../types";
 
 
@@ -48,6 +49,9 @@ function Slideshow({
   radius: string;
 }) {
   const { t } = useT();
+  // The first slide is the only slide visible on load, so it is this block's
+  // priority candidate — but only if no earlier block already claimed it.
+  const slidePriority = useClaimPriority(slides[0]?.image ?? null);
   const trackRef = useRef<HTMLDivElement>(null);
   const [index, setIndex] = useState(0);
   const indexRef = useRef(0);
@@ -129,7 +133,7 @@ function Slideshow({
                   src={s.image}
                   sizes="(min-width: 768px) 50vw, 100vw"
                   alt={alt}
-                  loading={i === 0 ? "eager" : "lazy"}
+                  priority={i === 0 && slidePriority}
                   className={`absolute inset-0 h-full w-full ${props.mediaFit === "contain" ? "object-contain" : "object-cover"}`}
                 />
               ) : (
@@ -202,6 +206,11 @@ function Slideshow({
  * then the rest of the text.
  */
 export function MediaSplitBlock({ props }: { props: MediaSplitProps }) {
+  // Claimed before rendering the media so a media-split placed first on a page
+  // gets the priority image when there is no hero above it.
+  const imagePriority = useClaimPriority(
+    props.mediaType === "slideshow" || props.mediaType === "video" ? null : props.image ?? null,
+  );
   const { t } = useT();
   const side = props.mediaSide ?? "left";
   const tone = props.tone ?? "white";
@@ -300,6 +309,7 @@ export function MediaSplitBlock({ props }: { props: MediaSplitProps }) {
           src={props.image}
           sizes="(min-width: 768px) 50vw, 100vw"
           alt={props.imageAlt ? t(props.imageAlt as Parameters<typeof t>[0]) : ""}
+          priority={imagePriority}
           className={`absolute inset-0 h-full w-full ${fitClass}`}
         />
       </div>

package/src/host/index.tsx

@@ -12,11 +12,21 @@ import type { LocalizedString } from "../i18n/types";
  * server functions per-site while block markup and inspector UI stay shared.
  */
 
+export type HostArtDirectedSource = {
+  media: string;
+  src: string;
+  sizes?: string;
+};
+
 export type HostFocalImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, "src"> & {
   src: string | undefined;
   /** When set, the host may build a responsive srcSet. */
   sizes?: string;
   responsive?: boolean;
+  /** Breakpoint-specific artwork, so only one file downloads per viewport. */
+  artDirected?: HostArtDirectedSource[];
+  /** The page's single first-screen image: eager, high fetch priority. */
+  priority?: boolean;
 };
 
 export type HostLazyVideoProps = {

package/src/media/FocalImage.tsx

@@ -67,17 +67,42 @@ export function useFocalStyle(src: string | undefined): {
   };
 }
 
+export type ArtDirectedSource = {
+  /** Media query this artwork applies to, e.g. `(max-width: 767px)`. */
+  media: string;
+  /** The image URL for that breakpoint. */
+  src: string;
+  /** `sizes` for that breakpoint; defaults to the element's `sizes`. */
+  sizes?: string;
+};
+
 export type FocalImageProps = Omit<ImgHTMLAttributes<HTMLImageElement>, "src"> & {
   src: string | undefined;
   /** When set, builds a responsive srcSet from the media library variants. */
   sizes?: string;
   responsive?: boolean;
+  /**
+   * Breakpoint-specific artwork. Rendered as `<source media=…>` before the
+   * default candidates, so exactly ONE file downloads per viewport — unlike two
+   * CSS-hidden `<img>` elements, which can both be fetched.
+   */
+  artDirected?: ArtDirectedSource[];
+  /**
+   * Marks this as the page's largest first-screen image: eager, high fetch
+   * priority. At most one image per page should set it — `HeroFullBlock` and
+   * other first-screen blocks claim it through `useClaimPriority`.
+   */
+  priority?: boolean;
 };
 
 /**
  * `<img>` that always crops around the image's editor-chosen focus point.
  * Falls back to a centred crop when no focus point is stored.
  *
+ * Loading defaults are safe rather than fast: `loading="lazy"` and
+ * `decoding="async"`, so an image nobody asked to prioritize can never compete
+ * with the first screen. The one image that should compete says `priority`.
+ *
  * When the source is a responsive WebP variant with a `-fallback.png` sibling,
  * renders a `<picture>` so browsers that do not support WebP (or need explicit
  * alpha handling) still receive a transparent PNG.
@@ -86,8 +111,13 @@ export function FocalImage({
   src,
   sizes,
   responsive = true,
+  artDirected,
+  priority = false,
   style,
   onError,
+  loading,
+  decoding,
+  fetchPriority,
   ...rest
 }: FocalImageProps) {
   const focal = useFocalStyle(src);
@@ -97,10 +127,37 @@ export function FocalImage({
   const [srcSetFailed, setSrcSetFailed] = useState(false);
   useEffect(() => setSrcSetFailed(false), [src]);
 
+  if (process.env['NODE_ENV'] !== "production" && priority) {
+    if (loading === "lazy") {
+      console.warn(
+        "[FocalImage] priority image was also given loading=\"lazy\"; priority wins.",
+      );
+    }
+    if (fetchPriority && fetchPriority !== "high") {
+      console.warn(
+        `[FocalImage] priority image was also given fetchPriority="${fetchPriority}"; priority wins.`,
+      );
+    }
+  }
+
+  // `priority` always wins over conflicting props; otherwise the caller decides
+  // and, failing that, the safe default applies. `decoding` is never "sync":
+  // blocking the main thread on a decode delays paint instead of helping it.
+  const loadingAttr = priority ? "eager" : (loading ?? "lazy");
+  const fetchPriorityAttr = priority ? "high" : fetchPriority;
+  const decodingAttr = decoding === "sync" ? "async" : (decoding ?? "async");
+
   const img = responsive && !srcSetFailed ? responsiveImage(src, sizes) : { src: src ?? "" };
   const merged: CSSProperties = { ...focal.style, ...style };
   const className = [focal.className, rest.className].filter(Boolean).join(" ");
 
+  const imgProps = {
+    ...rest,
+    loading: loadingAttr,
+    decoding: decodingAttr,
+    fetchPriority: fetchPriorityAttr,
+  };
+
   // Only wrap in <picture> when a fallback PNG is advertised. The fallback URL
   // is always derived, but it only exists for transparent uploads; using it for
   // every image would cause unnecessary 404s on opaque assets.
@@ -112,17 +169,33 @@ export function FocalImage({
     img.type === "image/webp" &&
     img.srcSet;
 
-  if (hasFallback && "fallbackSrc" in img) {
+  const artSources =
+    responsive && !srcSetFailed
+      ? (artDirected ?? [])
+          .map((a) => ({ media: a.media, img: responsiveImage(a.src, a.sizes ?? sizes) }))
+          .filter((a) => a.img.src)
+      : [];
+
+  if (artSources.length || (hasFallback && "fallbackSrc" in img)) {
     // The <picture> is only a source selector: it must not take the layout or
     // focus classes, or the inner <img> loses `object-position` and the crop
     // ignores the editor-chosen focus point.
     return (
       <picture style={{ display: "contents" }}>
-        <source srcSet={img.srcSet} sizes={img.sizes} type="image/webp" />
+        {artSources.map((a) => (
+          <source
+            key={a.media}
+            media={a.media}
+            srcSet={a.img.srcSet ?? a.img.src}
+            sizes={a.img.srcSet ? a.img.sizes : undefined}
+            type={a.img.srcSet ? "image/webp" : undefined}
+          />
+        ))}
+        {img.srcSet ? <source srcSet={img.srcSet} sizes={img.sizes} type="image/webp" /> : null}
         <img
-          {...rest}
+          {...imgProps}
           className={className}
-          src={img.fallbackSrc}
+          src={hasFallback && "fallbackSrc" in img ? img.fallbackSrc : img.src}
           alt={rest.alt}
           style={merged}
           onError={(event) => {
@@ -136,7 +209,7 @@ export function FocalImage({
 
   return (
     <img
-      {...rest}
+      {...imgProps}
       className={className}
       src={img.src}
       srcSet={"srcSet" in img ? img.srcSet : undefined}
@@ -150,3 +223,4 @@ export function FocalImage({
     />
   );
 }
+

package/src/media/preload.ts

@@ -0,0 +1,87 @@
+/**
+ * Preload attributes for a page's one priority image.
+ *
+ * A preload only helps when the browser would otherwise discover the image
+ * late: a CSS background, an image inserted after hydration, or artwork behind
+ * a client-only component. When the image is already an `<img>` in the
+ * server-rendered HTML, `fetchpriority="high"` on that element is enough — a
+ * preload adds a second candidate list that can disagree with the rendered one
+ * and fetch a second file. `heroPreloadLink` therefore refuses to build a link
+ * unless the caller states the image is discovered late.
+ *
+ * The attributes are derived from exactly the same `responsiveImage()` output
+ * the rendered element uses, so the browser cannot pick a different candidate.
+ */
+import { responsiveImage } from "./srcset";
+
+export type PreloadLink = {
+  rel: "preload";
+  as: "image";
+  href: string;
+  imageSrcSet?: string;
+  imageSizes?: string;
+  media?: string;
+  fetchPriority: "high";
+  crossOrigin?: "anonymous";
+};
+
+export type HeroPreloadInput = {
+  /** The image URL the page will render. */
+  src: string | undefined | null;
+  /** The exact `sizes` the rendered element uses. */
+  sizes?: string;
+  /** Media query, when the artwork is art-directed per breakpoint. */
+  media?: string;
+  /**
+   * True only when the image is NOT an `<img>`/`<picture>` in the initial HTML
+   * (CSS background, client-only component, post-hydration insert).
+   */
+  discoveredLate: boolean;
+  /** Set when the asset is served from another origin with CORS. */
+  crossOrigin?: "anonymous";
+};
+
+/**
+ * The preload link for a late-discovered hero, or null when preloading would
+ * be redundant (already in the HTML) or impossible (no image).
+ */
+export function heroPreloadLink(input: HeroPreloadInput): PreloadLink | null {
+  if (!input.src || !input.discoveredLate) return null;
+  const img = responsiveImage(input.src, input.sizes);
+  if (!img.src) return null;
+  const link: PreloadLink = {
+    rel: "preload",
+    as: "image",
+    href: img.src,
+    fetchPriority: "high",
+  };
+  if (img.srcSet) {
+    link.imageSrcSet = img.srcSet;
+    link.imageSizes = img.sizes;
+  }
+  if (input.media) link.media = input.media;
+  if (input.crossOrigin) link.crossOrigin = input.crossOrigin;
+  return link;
+}
+
+/**
+ * The same link as the `head().links` shape TanStack routes expect: React DOM
+ * spells these attributes camelCase, the HTML attributes are lowercase.
+ */
+export function heroPreloadHeadLink(
+  input: HeroPreloadInput,
+): Record<string, string> | null {
+  const link = heroPreloadLink(input);
+  if (!link) return null;
+  const out: Record<string, string> = {
+    rel: link.rel,
+    as: link.as,
+    href: link.href,
+    fetchpriority: link.fetchPriority,
+  };
+  if (link.imageSrcSet) out.imagesrcset = link.imageSrcSet;
+  if (link.imageSizes) out.imagesizes = link.imageSizes;
+  if (link.media) out.media = link.media;
+  if (link.crossOrigin) out.crossorigin = link.crossOrigin;
+  return out;
+}

package/src/media/priority.tsx

@@ -0,0 +1,69 @@
+/**
+ * Exactly one priority image per page.
+ *
+ * The largest image on the first screen should download eagerly at high fetch
+ * priority; every other image on the page should not. Which image that is
+ * depends on what the editor put first, so it cannot be hardcoded to one block
+ * type — and it must be decided while rendering (server included), never after
+ * hydration by measuring the viewport, or the decision arrives too late to
+ * matter.
+ *
+ * A page wraps its rendered blocks in `PriorityMediaProvider`. The first image
+ * that asks (`useClaimPriority`) during the first render pass wins, and every
+ * later asker is told no. Render order is deterministic and identical on the
+ * server and the client, so the same image wins in both.
+ */
+import { createContext, useContext, useRef, type ReactNode } from "react";
+
+type Claim = {
+  /** The winning claim key, or null while nobody has claimed yet. */
+  claimed: string | null;
+  /** Whether this page allows a priority image at all. */
+  enabled: boolean;
+};
+
+const PriorityContext = createContext<{ ref: { current: Claim } } | null>(null);
+
+/**
+ * Scopes the single priority claim to one page render.
+ *
+ * `enabled` exists for renders where no image should be prioritized at all —
+ * the block library preview, an admin thumbnail grid, an email render.
+ */
+export function PriorityMediaProvider({
+  enabled = true,
+  children,
+}: {
+  enabled?: boolean;
+  children: ReactNode;
+}) {
+  const ref = useRef<Claim>({ claimed: null, enabled });
+  ref.current.enabled = enabled;
+  return <PriorityContext.Provider value={{ ref }}>{children}</PriorityContext.Provider>;
+}
+
+/**
+ * Ask to be the page's priority image.
+ *
+ * `key` is normally the image URL. Asking twice with the same key (a component
+ * that re-renders) keeps the claim rather than losing it to a later image.
+ * Outside a provider nothing is prioritized, which is the safe answer for
+ * previews and standalone component renders.
+ */
+export function useClaimPriority(key: string | undefined | null): boolean {
+  const ctx = useContext(PriorityContext);
+  if (!ctx || !key) return false;
+  const state = ctx.ref.current;
+  if (!state.enabled) return false;
+  if (state.claimed === null) {
+    state.claimed = key;
+    return true;
+  }
+  return state.claimed === key;
+}
+
+/** The claim that won, for tests and for deriving a matching preload link. */
+export function usePriorityClaim(): string | null {
+  const ctx = useContext(PriorityContext);
+  return ctx ? ctx.ref.current.claimed : null;
+}

package/src/site/routes/public-page.tsx

@@ -8,6 +8,7 @@
  */
 import { notFound, redirect } from "@tanstack/react-router";
 import type { ComponentType, ReactElement, ReactNode } from "react";
+import { PriorityMediaProvider } from "../../media/priority";
 
 export type ResolvedPath =
   | { kind: "page"; pageKey: string }
@@ -89,10 +90,14 @@ export function createPublicPageRoute<Ctx>(deps: PublicPageRouteDeps<Ctx>): Publ
       return deps.buildPageHead(loaderData.pageKey, loaderData.ctx);
     },
 
+    // Only the page content may hold the priority image: chrome (header logo,
+    // footer marks) is small, and one page gets exactly one priority claim.
     PublicPage: ({ pageKey }) => (
       <Shell>
         <div className={deps.contentClassName ?? "pt-24 md:pt-32"}>
-          <deps.PageRenderer pageKey={pageKey} />
+          <PriorityMediaProvider>
+            <deps.PageRenderer pageKey={pageKey} />
+          </PriorityMediaProvider>
         </div>
       </Shell>
     ),

package/src/ui/NearViewport.tsx

@@ -0,0 +1,83 @@
+/**
+ * Renders its children only once the placeholder is near the viewport.
+ *
+ * `React.lazy` on its own does not defer anything: if the lazy element is part
+ * of the first render, its chunk is requested immediately. Heavy integrations
+ * (embeds, interactive maps, third-party scripts) therefore need a second gate
+ * — this one — so the import starts when the reader is actually approaching.
+ *
+ * The placeholder keeps the block's height, so nothing shifts when the real
+ * content arrives. Without IntersectionObserver (old browsers, SSR) the gate
+ * opens on mount rather than never.
+ */
+import { Component, useEffect, useRef, useState, type ReactNode } from "react";
+
+export type NearViewportProps = {
+  children: ReactNode;
+  /** Space reserved before loading; keep it equal to the loaded height. */
+  placeholder?: ReactNode;
+  /** How early to start loading. */
+  rootMargin?: string;
+  className?: string;
+};
+
+export function NearViewport({
+  children,
+  placeholder = null,
+  rootMargin = "800px 0px",
+  className,
+}: NearViewportProps) {
+  const ref = useRef<HTMLDivElement | null>(null);
+  const [near, setNear] = useState(false);
+
+  useEffect(() => {
+    if (near) return;
+    const node = ref.current;
+    if (!node) return;
+    if (typeof IntersectionObserver === "undefined") {
+      setNear(true);
+      return;
+    }
+    const io = new IntersectionObserver(
+      (entries) => {
+        if (entries.some((e) => e.isIntersecting)) {
+          setNear(true);
+          io.disconnect();
+        }
+      },
+      { rootMargin },
+    );
+    io.observe(node);
+    return () => io.disconnect();
+  }, [near, rootMargin]);
+
+  return (
+    <div ref={ref} className={className}>
+      {near ? children : placeholder}
+    </div>
+  );
+}
+
+/**
+ * Keeps one failed chunk load from blanking the page.
+ *
+ * A deferred chunk is fetched long after the document loaded, so a flaky
+ * network or a deploy that replaced the file is a normal outcome, not a bug.
+ * The fallback keeps the reserved space and whatever static alternative the
+ * block passed in.
+ */
+export class ChunkErrorBoundary extends Component<
+  { children: ReactNode; fallback?: ReactNode },
+  { failed: boolean }
+> {
+  state = { failed: false };
+
+  static getDerivedStateFromError() {
+    return { failed: true };
+  }
+
+  render() {
+    if (this.state.failed) return this.props.fallback ?? null;
+    return this.props.children;
+  }
+}