@drawnagency/primitives 0.1.111 → 0.1.112

package/src/components/shell/SiteSettingsDecks.tsx

@@ -0,0 +1,41 @@
+import { AudienceChips } from "./AudienceChips";
+import type { SiteConfig } from "../../schemas/site-config";
+import type { Audience } from "../../auth/types";
+
+interface Props {
+  siteConfig: SiteConfig;
+  onSiteConfigChange: (config: SiteConfig) => void;
+  audiences: Audience[];
+}
+
+/** Deck Builder settings. One control today — the creation opt-in — because
+ *  that is the only `deckBuilder` key that exists; public sharing (#37) is the
+ *  next one and belongs on this tab. */
+export function SiteSettingsDecks({ siteConfig, onSiteConfigChange, audiences }: Props) {
+  const selected = siteConfig.deckBuilder.audiences;
+
+  function toggle(name: string) {
+    const next = selected.includes(name) ? selected.filter((n) => n !== name) : [...selected, name];
+    onSiteConfigChange({ ...siteConfig, deckBuilder: { ...siteConfig.deckBuilder, audiences: next } });
+  }
+
+  return (
+    <div className="space-y-3">
+      <div>
+        <h3 className="mb-1 text-sm font-medium text-base-contrast">Who can build decks</h3>
+        <p className="mb-2 text-xs text-base-contrast-light">
+          Members of the selected audiences get the Decks button and can create and publish their own presentations.
+          None selected means no viewer can start a new one. Editors always can.
+        </p>
+        <AudienceChips audiences={audiences} selected={selected} onToggle={toggle} />
+      </div>
+      <p className="text-xs text-base-contrast-light">
+        Removing an audience here stops its members starting new decks. Decks they already own stay theirs — they can
+        still open, edit and delete them — so remove the deck itself if that is what you want gone.
+      </p>
+      <p className="text-xs text-base-contrast-light">
+        A deck is private to the person who made it. Sharing it with an audience, or by public link, comes later.
+      </p>
+    </div>
+  );
+}

package/src/components/shell/SiteSettingsModal.tsx

@@ -6,6 +6,7 @@ import { SiteSettingsViewerAccess } from "./SiteSettingsViewerAccess";
 import { SiteSettingsDisplay } from "./SiteSettingsDisplay";
 import { SiteSettingsUsers } from "./SiteSettingsUsers";
 import { SiteSettingsChatbot } from "./SiteSettingsChatbot";
+import { SiteSettingsDecks } from "./SiteSettingsDecks";
 import type { SiteConfig } from "../../schemas/site-config";
 import type { Audience } from "../../auth/types";
 
@@ -81,6 +82,16 @@ export function SiteSettingsModal({ isOpen, onClose, siteConfig, onSiteConfigCha
         </div>
       ),
     },
+    {
+      id: "decks",
+      label: "Decks",
+      show: true,
+      content: (
+        <div data-testid="site-settings-tab-panel" className="flex flex-1 flex-col overflow-y-auto px-6 py-4">
+          <SiteSettingsDecks siteConfig={siteConfig} onSiteConfigChange={onSiteConfigChange} audiences={audiences} />
+        </div>
+      ),
+    },
     {
       id: "display",
       label: "Display",

package/src/deck/DeckComponentView.tsx

@@ -0,0 +1,28 @@
+import type { DeckTextSlot } from "../lib/deck-edit";
+import type { DeckComponent } from "../schemas/deck";
+import { DeckImage } from "./components/DeckImage";
+import { DeckImageGrid } from "./components/DeckImageGrid";
+import { DeckRichText } from "./components/DeckRichText";
+import { DeckVideo } from "./components/DeckVideo";
+
+interface Props {
+  component: DeckComponent;
+  /** The Layout slot this component fills — carried only so text leaves can
+   *  address themselves for inline editing (#39). Optional: a caller that omits
+   *  it gets the read-only render. */
+  slot?: DeckTextSlot;
+}
+
+/** Dispatches a Deck Component onto its runtime implementation. */
+export function DeckComponentView({ component, slot }: Props) {
+  switch (component.type) {
+    case "richText":
+      return <DeckRichText content={component} slot={slot} />;
+    case "image":
+      return <DeckImage content={component} />;
+    case "imageGrid":
+      return <DeckImageGrid content={component} />;
+    case "video":
+      return <DeckVideo content={component} />;
+  }
+}

package/src/deck/DeckPlayer.tsx

@@ -0,0 +1,166 @@
+import { ChevronLeft, ChevronRight } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState } from "react";
+import { cn } from "../lib/cn";
+import type { Deck, DeckMediaAsset, DeckMediaResolver } from "../schemas/deck";
+import { DeckMediaProvider } from "./media";
+import { DeckStage } from "./DeckStage";
+import { DeckSlideView } from "./DeckSlideView";
+
+interface Props {
+  deck: Deck;
+  /** Slide to open on. Out-of-range values clamp into the deck. */
+  initialSlide?: number;
+  /** Window-level arrow/space/Home/End navigation. Off for thumbnails. */
+  keyboard?: boolean;
+  /** Turns media references into bytes. The Deck Builder injects the real one. */
+  resolveMedia?: DeckMediaResolver;
+  /**
+   * Pre-resolved portal media, keyed by media id. The serializable form of the
+   * same seam, for callers that cross an Astro island boundary — a function
+   * prop cannot survive that trip. Ignored when `resolveMedia` is given.
+   */
+  mediaAssets?: Record<string, DeckMediaAsset>;
+  className?: string;
+}
+
+function clamp(index: number, length: number): number {
+  return Math.min(Math.max(index, 0), length - 1);
+}
+
+/** Arrow keys must not steal typing from a chat panel docked beside the stage. */
+function isTypingTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  return target.isContentEditable || ["INPUT", "TEXTAREA", "SELECT"].includes(target.tagName);
+}
+
+/**
+ * A native button activates on Space *keyup*; the keydown only marks it active
+ * and suppresses scrolling. Calling preventDefault on that keydown cancels the
+ * activation — so Space on a focused "Previous slide" used to swallow the click
+ * and step FORWARD instead. Enter needs no such guard: it has no case below, so
+ * it never reaches preventDefault.
+ */
+function isActivatableTarget(target: EventTarget | null): boolean {
+  if (!(target instanceof HTMLElement)) return false;
+  if (target.tagName === "BUTTON" || target.tagName === "SUMMARY") return true;
+  if (target.tagName === "A" && target.hasAttribute("href")) return true;
+  return target.getAttribute("role") === "button";
+}
+
+const NAV_BUTTON =
+  "flex size-[38px] items-center justify-center rounded-[var(--radius-outer)] border border-base-200 text-base-contrast transition-colors hover:bg-base-accent disabled:cursor-not-allowed disabled:opacity-35 disabled:hover:bg-transparent";
+
+/**
+ * The deck runtime's presentation surface: one 16:9 stage plus slide
+ * navigation. Deliberately self-contained — the Deck Builder, the in-portal
+ * deck view and the Public Link view all mount this same component, so slide
+ * state lives here rather than in any one of those shells.
+ */
+export function DeckPlayer({ deck, initialSlide = 0, keyboard = true, resolveMedia, mediaAssets, className }: Props) {
+  const total = deck.slides.length;
+  const [index, setIndex] = useState(() => clamp(initialSlide, total));
+  // `Object.hasOwn`, not indexing: a media id is author-supplied, and a plain
+  // object answers `"constructor"` and `"toString"` with inherited members that
+  // are not assets at all. The schema's charset rules those ids out too — this
+  // is the second lock on the same door. The `kind` check keeps the map form
+  // honest the day a second media kind lands: it resolves portal ids, and says
+  // so by refusing everything else rather than looking the id up anyway.
+  const resolve = useMemo<DeckMediaResolver>(
+    () =>
+      resolveMedia ??
+      ((ref) =>
+        ref.kind === "portal" && mediaAssets !== undefined && Object.hasOwn(mediaAssets, ref.id)
+          ? mediaAssets[ref.id]
+          : null),
+    [resolveMedia, mediaAssets],
+  );
+
+  const current = clamp(index, total);
+  const slide = deck.slides[current];
+
+  const goTo = useCallback((next: number) => setIndex(clamp(next, total)), [total]);
+  // `prev` is clamped BEFORE the delta: the builder live-replaces the deck every
+  // LLM turn, so a shrunk deck can leave the stored index past the end. Without
+  // the inner clamp the first Previous press would land back on the slide
+  // already showing — a visible no-op.
+  const step = useCallback(
+    (delta: number) => setIndex((prev) => clamp(clamp(prev, total) + delta, total)),
+    [total],
+  );
+
+  useEffect(() => {
+    if (!keyboard) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.metaKey || event.ctrlKey || event.altKey) return;
+      if (isTypingTarget(event.target)) return;
+      switch (event.key) {
+        case " ":
+          if (isActivatableTarget(event.target)) return;
+          event.preventDefault();
+          step(1);
+          break;
+        case "ArrowRight":
+        case "PageDown":
+          event.preventDefault();
+          step(1);
+          break;
+        case "ArrowLeft":
+        case "PageUp":
+          event.preventDefault();
+          step(-1);
+          break;
+        case "Home":
+          event.preventDefault();
+          setIndex(0);
+          break;
+        case "End":
+          event.preventDefault();
+          setIndex(total - 1);
+          break;
+      }
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [keyboard, step, total]);
+
+  return (
+    <div data-deck-player={deck.id} className={cn("flex h-full min-h-0 w-full flex-col gap-4 bg-base p-4", className)}>
+      <DeckStage className="flex-1">
+        <DeckMediaProvider resolve={resolve}>
+          <DeckSlideView slide={slide} />
+        </DeckMediaProvider>
+      </DeckStage>
+
+      <nav aria-label={`${deck.title} slides`} className="flex shrink-0 items-center justify-center gap-4">
+        <button type="button" className={NAV_BUTTON} onClick={() => step(-1)} disabled={current === 0} aria-label="Previous slide">
+          <ChevronLeft className="size-5" aria-hidden="true" />
+        </button>
+
+        <ol className="flex items-center gap-2">
+          {deck.slides.map((s, i) => (
+            <li key={s.id}>
+              <button
+                type="button"
+                onClick={() => goTo(i)}
+                aria-current={i === current ? "true" : undefined}
+                aria-label={s.title ? `Slide ${i + 1}: ${s.title}` : `Slide ${i + 1}`}
+                className={cn(
+                  "size-[10px] rounded-full transition-colors",
+                  i === current ? "bg-primary" : "bg-base-300 hover:bg-base-contrast-light",
+                )}
+              />
+            </li>
+          ))}
+        </ol>
+
+        <button type="button" className={NAV_BUTTON} onClick={() => step(1)} disabled={current === total - 1} aria-label="Next slide">
+          <ChevronRight className="size-5" aria-hidden="true" />
+        </button>
+
+        <p aria-live="polite" className="ml-2 text-sm tabular-nums text-base-contrast-light">
+          {current + 1} / {total}
+        </p>
+      </nav>
+    </div>
+  );
+}

package/src/deck/DeckSlideView.tsx

@@ -0,0 +1,38 @@
+import type { DeckSlide } from "../schemas/deck";
+import { CenteredTextLayout } from "./layouts/CenteredTextLayout";
+import { ColumnSplitLayout } from "./layouts/ColumnSplitLayout";
+import { FullBleedImageLayout } from "./layouts/FullBleedImageLayout";
+
+interface Props {
+  slide: DeckSlide;
+}
+
+function LayoutView({ slide }: Props) {
+  const { layout } = slide;
+  switch (layout.type) {
+    case "centeredText":
+      return <CenteredTextLayout layout={layout} />;
+    case "fullBleedImage":
+      return <FullBleedImageLayout layout={layout} />;
+    case "columnSplit":
+      return <ColumnSplitLayout layout={layout} />;
+  }
+}
+
+/**
+ * Dispatches a slide onto its Layout. One slide uses exactly one Layout.
+ *
+ * Keyed by slide id, and that key is load-bearing rather than a lint nicety:
+ * two slides sharing a Layout shape reconcile onto the SAME component
+ * instances, so an expanded image-grid tile or a playing video on slide 1 was
+ * inherited by slide 2 the moment you pressed the arrow key. The key forces the
+ * subtree to remount, which is the only thing that makes a slide's interaction
+ * state belong to that slide.
+ */
+export function DeckSlideView({ slide }: Props) {
+  return (
+    <div key={slide.id} data-deck-slide={slide.id} className="size-full">
+      <LayoutView slide={slide} />
+    </div>
+  );
+}

package/src/deck/DeckStage.tsx

@@ -0,0 +1,39 @@
+import { useRef, type ReactNode } from "react";
+import { cn } from "../lib/cn";
+import { DECK_STAGE_HEIGHT, DECK_STAGE_WIDTH } from "../schemas/deck";
+import { useStageScale } from "./useStageScale";
+
+interface Props {
+  children: ReactNode;
+  /** Applied to the fit box, which is what the stage is scaled to fill. */
+  className?: string;
+}
+
+/**
+ * The 16:9 stage: a fixed logical canvas centered in — and scaled to fit — its
+ * container, so slide contents are authored in px against one coordinate system
+ * regardless of the viewport. Scaling by transform (rather than by a font-size
+ * cascade) keeps every measurement, including line breaks, identical at every
+ * size, which is what makes a screenshared deck look the same as its preview.
+ */
+export function DeckStage({ children, className }: Props) {
+  const fitRef = useRef<HTMLDivElement>(null);
+  const scale = useStageScale(fitRef);
+
+  return (
+    <div ref={fitRef} className={cn("relative min-h-0 w-full overflow-hidden", className)} data-deck-fit="">
+      <div
+        data-deck-stage=""
+        data-deck-scale={scale === null ? undefined : scale.toFixed(4)}
+        className="absolute top-1/2 left-1/2 origin-center overflow-hidden rounded-[var(--radius-outer)] font-body"
+        style={{
+          width: DECK_STAGE_WIDTH,
+          height: DECK_STAGE_HEIGHT,
+          transform: scale === null ? "translate(-50%, -50%)" : `translate(-50%, -50%) scale(${scale})`,
+        }}
+      >
+        {children}
+      </div>
+    </div>
+  );
+}

package/src/deck/components/DeckImage.tsx

@@ -0,0 +1,38 @@
+import type { DeckImage as DeckImageContent } from "../../schemas/deck";
+import { DeckMissingMedia, useDeckMedia } from "../media";
+import { surfaceInk } from "../tokens";
+
+interface Props {
+  content: DeckImageContent;
+}
+
+/**
+ * Deck Component — image.
+ *
+ * Fills its slot and crops. The caption is a solid brand block sitting on the
+ * image's bottom edge rather than a gradient scrim: a scrim needs a literal
+ * color to darken toward, and legibility here comes from the block.
+ */
+export function DeckImage({ content }: Props) {
+  const asset = useDeckMedia(content.media);
+
+  return (
+    <figure data-deck-component="image" className="relative size-full overflow-hidden bg-base-200">
+      {asset === null ? (
+        <DeckMissingMedia />
+      ) : (
+        <img src={asset.src} alt={asset.alt} className="size-full object-cover" />
+      )}
+
+      {content.caption !== undefined && (
+        <figcaption
+          data-deck-surface="brand"
+          style={surfaceInk("brand")}
+          className="absolute right-0 bottom-0 left-0 bg-primary px-[28px] py-[18px] text-[18px] tracking-[0.06em] text-[var(--deck-ink)] [text-transform:var(--nav-text-transform)]"
+        >
+          {content.caption}
+        </figcaption>
+      )}
+    </figure>
+  );
+}

package/src/deck/components/DeckImageGrid.tsx

@@ -0,0 +1,254 @@
+import { useCallback, useEffect, useLayoutEffect, useMemo, useRef, useState } from "react";
+import { cn } from "../../lib/cn";
+import type { DeckImageGrid as DeckImageGridContent, DeckImageGridItem, DeckMediaAsset } from "../../schemas/deck";
+import { captureTileRects, playTileFlip, type TileRects } from "../flip";
+import { DeckMissingMedia, useDeckMediaResolver } from "../media";
+import { DECK_ELEVATION, surfaceInk } from "../tokens";
+
+interface Props {
+  content: DeckImageGridContent;
+}
+
+/**
+ * Two columns for a small set, three once there are enough tiles to fill them.
+ * Deliberately not a schema field: it is presentation, and one fewer knob for
+ * an author to get wrong.
+ */
+function columnsFor(count: number): number {
+  return count <= 4 ? 2 : 3;
+}
+
+/**
+ * A tile's height as a multiple of the column width. Falls back to a square
+ * when the resolver reports no dimensions — the packing still has to be
+ * deterministic, and a square is the least-wrong guess.
+ */
+function tileRatio(asset: DeckMediaAsset | null): number {
+  if (asset?.width === undefined || asset.height === undefined || asset.width <= 0) return 1;
+  return asset.height / asset.width;
+}
+
+/**
+ * Greedy shortest-column packing: each tile joins whichever column is currently
+ * least tall, ties going left. With uniform aspect ratios that degenerates to
+ * round-robin, which is what makes the simple cases look deliberate.
+ */
+export function packMasonry(ratios: number[], columns: number): number[][] {
+  const packed: number[][] = Array.from({ length: columns }, () => []);
+  const filled = new Array<number>(columns).fill(0);
+  ratios.forEach((ratio, index) => {
+    let target = 0;
+    for (let column = 1; column < columns; column++) {
+      if (filled[column] < filled[target]) target = column;
+    }
+    packed[target].push(index);
+    filled[target] += ratio;
+  });
+  return packed;
+}
+
+const TILE_BASE =
+  "group relative block shrink-0 overflow-hidden bg-base-200 will-change-transform transition-[transform,box-shadow,opacity] duration-[380ms] ease-[cubic-bezier(0.2,0.75,0.2,1)] focus-visible:outline-2 focus-visible:outline-offset-[-6px] focus-visible:outline-[var(--color-primary)]";
+
+/**
+ * Deck Component — image grid, and the runtime's signature interaction.
+ *
+ * Masonry columns: every image keeps its own aspect ratio, the column width
+ * decides its height, and a stack that runs past the bottom of the slot is
+ * clipped there. That clip is the point — on a fixed 16:9 stage a collage that
+ * runs off the bottom edge reads better than one that crops every frame to a
+ * uniform cell, and nothing may spill past the slot onto the rest of the slide.
+ *
+ * Hover lifts a tile; activating it expands that tile to fill the whole grid
+ * region as a lightbox contained inside the slide (never a full-screen overlay
+ * — the deck stays the deck). Activating again, the close affordance, or Escape
+ * returns it. Tiles are real buttons, so keyboard activation is the browser's.
+ */
+export function DeckImageGrid({ content }: Props) {
+  const [active, setActive] = useState<number | null>(null);
+  const gridRef = useRef<HTMLDivElement>(null);
+  const pendingRects = useRef<TileRects | null>(null);
+
+  const expanded = active !== null;
+  const resolve = useDeckMediaResolver();
+  const count = content.items.length;
+
+  const assets = useMemo(() => content.items.map((item) => resolve(item.media)), [content.items, resolve]);
+  const columns = columnsFor(count);
+  const packed = useMemo(() => packMasonry(assets.map(tileRatio), columns), [assets, columns]);
+
+  // Measure BEFORE the state change: React moves the DOM, and FLIP needs the
+  // pre-move rects, which no longer exist by the time the effect runs.
+  const transitionTo = useCallback((next: number | null) => {
+    const grid = gridRef.current;
+    if (grid) pendingRects.current = captureTileRects(grid);
+    setActive(next);
+  }, []);
+
+  useLayoutEffect(() => {
+    const grid = gridRef.current;
+    const before = pendingRects.current;
+    pendingRects.current = null;
+    if (grid && before) playTileFlip(grid, before);
+  }, [active]);
+
+  // The Deck Builder replaces the whole deck every LLM turn, so a grid can lose
+  // tiles under an open lightbox. Left alone, the expanded index would point
+  // past the end and every tile would render hidden — a blank slot with no way
+  // out but Escape.
+  useEffect(() => {
+    setActive((prev) => (prev === null || prev < count ? prev : null));
+  }, [count]);
+
+  useEffect(() => {
+    if (!expanded) return;
+    const onKeyDown = (event: KeyboardEvent) => {
+      if (event.key !== "Escape") return;
+      // NOTE: this stops the event travelling to an ancestor, which for a
+      // window listener is nothing at all — it does NOT stop other listeners on
+      // window from also seeing this Escape. A future shell-level Escape (exit
+      // presentation, close the builder) has to coordinate with the grid
+      // explicitly; it cannot rely on this call to have swallowed the key.
+      event.stopPropagation();
+      transitionTo(null);
+    };
+    window.addEventListener("keydown", onKeyDown);
+    return () => window.removeEventListener("keydown", onKeyDown);
+  }, [expanded, transitionTo]);
+
+  /**
+   * Close returns focus to the tile that was expanded. Without it the close
+   * button unmounts under the caret and focus falls to <body>, which strands a
+   * keyboard user outside the grid entirely. Focus first, then re-render, so
+   * the unmounting button is no longer the active element when it goes.
+   */
+  const close = useCallback(() => {
+    gridRef.current?.querySelector<HTMLElement>(`[data-deck-tile="${active}"]`)?.focus({ preventScroll: true });
+    transitionTo(null);
+  }, [active, transitionTo]);
+
+  return (
+    <div
+      ref={gridRef}
+      data-deck-component="imageGrid"
+      data-deck-grid-expanded={expanded ? "true" : "false"}
+      data-deck-grid-columns={columns}
+      style={DECK_ELEVATION}
+      // Clipped, not scrolled: a deck slide has no scrollbars, and a stack that
+      // runs long is meant to run off the bottom of the slot.
+      className="relative flex size-full gap-[14px] overflow-hidden"
+    >
+      {packed.map((indices, column) => (
+        // `flex-1` rather than a width fraction: the columns have to share the
+        // gap between them, and equal flex bases divide what is left over.
+        <div key={column} data-deck-grid-column={column} className="flex min-w-0 flex-1 flex-col gap-[14px]">
+          {indices.map((index) => (
+            <Tile
+              key={index}
+              item={content.items[index]}
+              asset={assets[index]}
+              index={index}
+              expanded={expanded}
+              active={index === active}
+              onActivate={() => transitionTo(index === active ? null : index)}
+            />
+          ))}
+        </div>
+      ))}
+
+      {expanded && (
+        <button
+          type="button"
+          data-deck-grid-close=""
+          onClick={close}
+          data-deck-surface="brand"
+          style={surfaceInk("brand")}
+          className="absolute top-[14px] right-[14px] z-[4] bg-primary px-[18px] py-[10px] text-[15px] font-semibold tracking-[0.12em] text-[var(--deck-ink)] uppercase"
+        >
+          Close
+        </button>
+      )}
+    </div>
+  );
+}
+
+interface TileProps {
+  item: DeckImageGridItem;
+  asset: DeckMediaAsset | null;
+  index: number;
+  expanded: boolean;
+  active: boolean;
+  onActivate: () => void;
+}
+
+function Tile({ item, asset, index, expanded, active, onActivate }: TileProps) {
+  const label = item.caption ?? asset?.alt ?? `Image ${index + 1}`;
+
+  return (
+    <button
+      type="button"
+      data-deck-tile={index}
+      data-deck-tile-active={active ? "true" : "false"}
+      aria-expanded={active}
+      aria-label={active ? `Close ${label}` : `Expand ${label}`}
+      tabIndex={expanded && !active ? -1 : 0}
+      onClick={onActivate}
+      className={cn(
+        TILE_BASE,
+        // Every tile leaves the column flow when one is expanded, not only the
+        // active one: leaving the siblings in place would let the columns
+        // re-pack around the gap, which both reflows the tiles the lightbox is
+        // covering and moves the ones the FLIP is animating.
+        expanded ? "absolute inset-0 flex items-center justify-center" : "w-full",
+        expanded && !active && "pointer-events-none opacity-0",
+        // Transparent, not the tile's loading plate: an expanded frame is
+        // letterboxed inside the slot, and the field around it should read as
+        // the slide showing through rather than as a grey box drawn on top.
+        expanded && active && "z-[3] bg-transparent opacity-100",
+        !expanded && "cursor-pointer hover:z-[2] hover:scale-[1.035] hover:shadow-[var(--deck-lift)]",
+      )}
+    >
+      {asset === null ? (
+        <DeckMissingMedia className={active ? "size-full" : "aspect-square h-auto w-full"} />
+      ) : (
+        <img
+          src={asset.src}
+          alt=""
+          // The intrinsic size, when the resolver knows it, so the column
+          // reserves the right height before a byte arrives — otherwise the
+          // masonry re-packs visibly as each image lands.
+          width={asset.width}
+          height={asset.height}
+          // The elevation moves onto the image when expanded: the button box is
+          // the whole slot now, and a shadow on THAT would outline the
+          // letterbox instead of the frame the viewer is looking at.
+          className={
+            active ? "max-h-full max-w-full object-contain shadow-[var(--deck-lift-strong)]" : "block h-auto w-full"
+          }
+        />
+      )}
+
+      <span
+        aria-hidden="true"
+        data-deck-surface="brand"
+        style={surfaceInk("brand")}
+        className="absolute top-0 left-0 bg-primary px-[12px] py-[6px] text-[15px] font-bold tracking-[0.1em] text-[var(--deck-ink)] tabular-nums"
+      >
+        {String(index + 1).padStart(2, "0")}
+      </span>
+
+      {item.caption !== undefined && (
+        <span
+          data-deck-surface="brand"
+          style={surfaceInk("brand")}
+          className={cn(
+            "absolute right-0 bottom-0 left-0 bg-primary text-left tracking-[0.04em] text-[var(--deck-ink)] transition-opacity duration-200",
+            active ? "px-[30px] py-[22px] text-[24px] opacity-100" : "px-[18px] py-[14px] text-[18px] opacity-0 group-hover:opacity-100",
+          )}
+        >
+          {item.caption}
+        </span>
+      )}
+    </button>
+  );
+}