@drawnagency/primitives 0.1.110 → 0.1.112

package/src/deck/components/DeckRichText.tsx

@@ -0,0 +1,111 @@
+import { Fragment, type ReactNode } from "react";
+import type { DeckTextPath, DeckTextSlot } from "../../lib/deck-edit";
+import type { DeckInlineText, DeckRichText as DeckRichTextContent } from "../../schemas/deck";
+import { EditableText } from "../editing";
+
+interface Props {
+  content: DeckRichTextContent;
+  /**
+   * Which slot of the enclosing Layout this component fills. Supplied only so a
+   * text leaf can address itself for inline editing (#39); absent means "no
+   * edit seam here", which is the read-only default every viewer surface gets.
+   */
+  slot?: DeckTextSlot;
+}
+
+/**
+ * A body line. A plain string renders as itself; a span run renders its marks
+ * as elements. Nothing here reads a string as markup — `bold` and `italic` are
+ * booleans on the span, which is the whole point of the representation.
+ *
+ * The editable unit is the LEAF, never the line: a marked run offers one field
+ * per span, so editing the words around a bold phrase cannot flatten it. That
+ * is what lets inline editing be plain-text-only without a formatting UI and
+ * without silently dropping marks (#39).
+ */
+function InlineText({ value, path }: { value: DeckInlineText; path?: DeckTextPath }) {
+  if (typeof value === "string") return <EditableText path={path}>{value}</EditableText>;
+  return (
+    <>
+      {value.map((span, i) => {
+        let node: ReactNode = (
+          <EditableText path={path && { ...path, span: i }}>{span.text}</EditableText>
+        );
+        if (span.italic) node = <em className="italic">{node}</em>;
+        // Bold pulls the phrase back to full ink: body copy renders muted, so
+        // weight alone barely registers at presentation size.
+        if (span.bold) node = <strong className="font-semibold text-[var(--deck-ink)]">{node}</strong>;
+        return <Fragment key={i}>{node}</Fragment>;
+      })}
+    </>
+  );
+}
+
+/**
+ * Deck Component — rich text.
+ *
+ * Every size is px against the 1600x900 stage; every color, family and radius
+ * is a token (`--deck-*` are set by the enclosing Layout, see ./tokens.ts).
+ * Fields are typographic roles, not markup: the schema carries plain strings
+ * and marked spans, so nothing here interpolates HTML.
+ */
+export function DeckRichText({ content, slot }: Props) {
+  const { kicker, heading, subheading, paragraphs, bullets } = content;
+  const at = (field: DeckTextPath["field"], line?: number): DeckTextPath | undefined =>
+    slot === undefined ? undefined : { slot, field, line };
+
+  return (
+    <div data-deck-component="richText" className="flex flex-col gap-[28px]">
+      {kicker !== undefined && (
+        <div className="flex flex-col gap-[18px]">
+          <p className="text-[22px] font-semibold tracking-[0.2em] text-[var(--deck-accent)] [text-transform:var(--nav-text-transform)]">
+            <EditableText path={at("kicker")}>{kicker}</EditableText>
+          </p>
+          <span
+            aria-hidden="true"
+            // Inline, not `self-[var(…)]`: Tailwind never generated CSS for that
+            // arbitrary self- value, so the divider silently ignored --deck-align
+            // and hugged the left edge on centered layouts.
+            style={{ alignSelf: "var(--deck-align, start)" }}
+            className="h-[4px] w-[84px] rounded-[var(--radius-inner)] bg-[var(--deck-accent)]"
+          />
+        </div>
+      )}
+
+      {heading !== undefined && (
+        <h1 className="font-heading text-[88px] leading-[1.06] font-medium tracking-[-0.015em] text-[var(--deck-ink)] [text-transform:var(--heading-text-transform)]">
+          <EditableText path={at("heading")}>{heading}</EditableText>
+        </h1>
+      )}
+
+      {subheading !== undefined && (
+        <h2 className="font-heading text-[38px] leading-[1.25] font-normal text-[var(--deck-ink-muted)] [text-transform:var(--subheading-text-transform)]">
+          <EditableText path={at("subheading")}>{subheading}</EditableText>
+        </h2>
+      )}
+
+      {paragraphs !== undefined && paragraphs.length > 0 && (
+        <div className="flex max-w-[1000px] flex-col gap-[18px] self-[var(--deck-align,start)]">
+          {paragraphs.map((paragraph, i) => (
+            <p key={i} className="text-[26px] leading-[1.6] text-[var(--deck-ink-muted)]">
+              <InlineText value={paragraph} path={at("paragraphs", i)} />
+            </p>
+          ))}
+        </div>
+      )}
+
+      {bullets !== undefined && bullets.length > 0 && (
+        <ul className="flex flex-col gap-[16px] self-[var(--deck-align,start)] text-left">
+          {bullets.map((bullet, i) => (
+            <li key={i} className="flex items-start gap-[18px] text-[26px] leading-[1.45] text-[var(--deck-ink)]">
+              <span aria-hidden="true" className="mt-[14px] size-[10px] shrink-0 rounded-full bg-[var(--deck-accent)]" />
+              <span>
+                <InlineText value={bullet} path={at("bullets", i)} />
+              </span>
+            </li>
+          ))}
+        </ul>
+      )}
+    </div>
+  );
+}

package/src/deck/components/DeckVideo.tsx

@@ -0,0 +1,81 @@
+import { Play } from "lucide-react";
+import { useRef, useState } from "react";
+import type { DeckVideo as DeckVideoContent } from "../../schemas/deck";
+import { DeckMissingMedia, useDeckMedia } from "../media";
+import { DECK_ELEVATION, surfaceInk } from "../tokens";
+
+interface Props {
+  content: DeckVideoContent;
+}
+
+/**
+ * Deck Component — video.
+ *
+ * Two states: a poster with a play affordance, and playback with the browser's
+ * own controls. Nothing custom drives the media element once it is playing —
+ * a presenter needs scrubbing and volume, and native controls are the ones
+ * their keyboard already knows.
+ */
+export function DeckVideo({ content }: Props) {
+  const asset = useDeckMedia(content.media);
+  const videoRef = useRef<HTMLVideoElement>(null);
+  const [playing, setPlaying] = useState(false);
+
+  const start = () => {
+    setPlaying(true);
+    // Rejects when the source is unplayable (wrong codec, a media id whose
+    // bytes are gone) — the poster is already dismissed, so just don't leave
+    // an unhandled rejection behind.
+    videoRef.current?.play()?.catch(() => undefined);
+  };
+
+  return (
+    <div
+      data-deck-component="video"
+      data-deck-video-state={playing ? "playing" : "idle"}
+      style={DECK_ELEVATION}
+      className="relative size-full overflow-hidden bg-base-200"
+    >
+      {asset === null ? (
+        <DeckMissingMedia />
+      ) : (
+        <video
+          ref={videoRef}
+          src={asset.src}
+          poster={asset.poster}
+          // Nothing is fetched until the poster is dismissed: a deck is mostly
+          // slides you never reach, and the poster is an explicit URL anyway.
+          preload="none"
+          playsInline
+          controls={playing}
+          onEnded={() => setPlaying(false)}
+          className="size-full object-cover"
+        />
+      )}
+
+      {!playing && asset !== null && (
+        <button
+          type="button"
+          data-deck-video-play=""
+          onClick={start}
+          aria-label={content.title === undefined ? "Play video" : `Play ${content.title}`}
+          className="group absolute inset-0 grid cursor-pointer place-items-center"
+        >
+          <span className="grid size-[108px] place-items-center rounded-full bg-primary text-[var(--color-on-primary)] shadow-[var(--deck-lift)] transition-transform duration-200 group-hover:scale-105">
+            <Play aria-hidden="true" className="ml-[6px] size-[44px] fill-current" />
+          </span>
+        </button>
+      )}
+
+      {!playing && content.title !== undefined && (
+        <span
+          data-deck-surface="brand"
+          style={surfaceInk("brand")}
+          className="pointer-events-none 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.title}
+        </span>
+      )}
+    </div>
+  );
+}

package/src/deck/editing.tsx

@@ -0,0 +1,201 @@
+import { createContext, useContext, useEffect, useRef, useState, type ReactNode } from "react";
+import type { DeckTextPath } from "../lib/deck-edit";
+
+/**
+ * The runtime's inline-editing seam (#39).
+ *
+ * Editing happens INSIDE the real renderer rather than in an overlay that
+ * imitates it, which is the only way "renders identically on blur" is true
+ * rather than approximately true — the element the author types into is the
+ * element the deck ships with.
+ *
+ * The seam is a context that defaults to null, so every read-only surface — a
+ * filmstrip thumbnail, an in-portal deck view, the Public Link route — renders
+ * exactly the markup it rendered before this file existed, with no affordance
+ * and no listeners. Providing the context is an explicit act, performed in one
+ * place (`DeckSlideSurface`).
+ */
+
+export interface DeckTextEditor {
+  /** Commit a leaf edit. The provider owns validation and staging. */
+  onEditText: (path: DeckTextPath, text: string) => void;
+  /**
+   * Locked while a chat turn is in flight: a turn rewrites the WHOLE deck
+   * (ADR 0001), so an edit committed mid-stream would be written over by the
+   * turn's own `putDeckDraft` with nothing anywhere saying so.
+   */
+  disabled?: boolean;
+}
+
+const DeckTextEditContext = createContext<DeckTextEditor | null>(null);
+
+export function DeckTextEditProvider({ editor, children }: { editor: DeckTextEditor | null; children: ReactNode }) {
+  return <DeckTextEditContext.Provider value={editor}>{children}</DeckTextEditContext.Provider>;
+}
+
+export function useDeckTextEditor(): DeckTextEditor | null {
+  return useContext(DeckTextEditContext);
+}
+
+interface EditableTextProps {
+  /** Absent when the enclosing component was rendered without a slot — i.e. by
+   *  a surface that never carries an edit seam. Renders inert. */
+  path?: DeckTextPath;
+  /** The leaf's current text. Always a plain string; that is the schema's shape. */
+  children: string;
+}
+
+/**
+ * One editable text leaf, or plain text when there is no editor.
+ *
+ * The two states are DIFFERENT ELEMENTS on purpose. React does not manage the
+ * text of a `contentEditable` node it has no children for, so the field can be
+ * written to freely while it is open, and swapping back to a React-rendered
+ * span on commit is what makes the committed value the one that renders — no
+ * reconciliation against a DOM the author mutated behind React's back.
+ */
+export function EditableText({ path, children }: EditableTextProps) {
+  const editor = useDeckTextEditor();
+  const [editing, setEditing] = useState(false);
+
+  const enabled = editor !== null && path !== undefined && editor.disabled !== true;
+
+  // Losing the seam mid-edit (a chat turn starting, the surface going
+  // read-only) closes the field rather than leaving an orphaned editable node.
+  useEffect(() => {
+    if (!enabled && editing) setEditing(false);
+  }, [enabled, editing]);
+
+  if (editor === null || path === undefined) return <>{children}</>;
+
+  if (editing && enabled) {
+    return (
+      <EditableField
+        initial={children}
+        onCommit={(text) => {
+          setEditing(false);
+          // An emptied field is a cancel, not an edit: every one of these leaves
+          // is `min(1)` in the schema, so committing "" could only ever be
+          // refused — and refusing it with an error message would read as a
+          // failure rather than as "nothing happened".
+          const trimmed = text.trim();
+          if (trimmed !== "" && trimmed !== children) editor.onEditText(path, trimmed);
+        }}
+        onCancel={() => setEditing(false)}
+      />
+    );
+  }
+
+  return (
+    <span
+      role="button"
+      tabIndex={enabled ? 0 : -1}
+      aria-disabled={enabled ? undefined : true}
+      data-deck-editable=""
+      onClick={enabled ? () => setEditing(true) : undefined}
+      onKeyDown={
+        enabled
+          ? (event) => {
+              if (event.key !== "Enter" && event.key !== " ") return;
+              event.preventDefault();
+              setEditing(true);
+            }
+          : undefined
+      }
+      className={
+        enabled
+          ? "cursor-text rounded-[var(--radius-inner)] decoration-dotted underline-offset-[6px] outline-none hover:underline focus-visible:underline"
+          : "opacity-70"
+      }
+    >
+      {children}
+    </span>
+  );
+}
+
+/**
+ * The open field. Rendered with no React children so React never fights the
+ * author for the node's text; the initial value is written once on mount.
+ */
+function EditableField({
+  initial,
+  onCommit,
+  onCancel,
+}: {
+  initial: string;
+  onCommit: (text: string) => void;
+  onCancel: () => void;
+}) {
+  const ref = useRef<HTMLSpanElement>(null);
+  // Escape has to beat the blur that follows it, and blur reads this ref rather
+  // than state because the two happen in the same tick.
+  const cancelled = useRef(false);
+
+  useEffect(() => {
+    const element = ref.current;
+    if (!element) return;
+    element.textContent = initial;
+    element.focus();
+    const selection = window.getSelection?.();
+    if (selection) {
+      const range = document.createRange();
+      range.selectNodeContents(element);
+      selection.removeAllRanges();
+      selection.addRange(range);
+    }
+  }, [initial]);
+
+  return (
+    <span
+      ref={ref}
+      contentEditable
+      suppressContentEditableWarning
+      role="textbox"
+      aria-label="Edit text"
+      spellCheck
+      data-deck-editing=""
+      onKeyDown={(event) => {
+        // Mid-composition, Enter and Escape belong to the IME: Enter accepts a
+        // conversion candidate and Escape abandons it. Committing or cancelling
+        // the field there cuts a CJK author off mid-word.
+        if (event.nativeEvent.isComposing) return;
+        if (event.key === "Enter") {
+          // A deck text leaf is one line in the schema, so Enter means "done",
+          // not "newline" — the layouts own line breaking.
+          event.preventDefault();
+          event.currentTarget.blur();
+          return;
+        }
+        if (event.key === "Escape") {
+          event.preventDefault();
+          cancelled.current = true;
+          event.currentTarget.blur();
+        }
+      }}
+      onPaste={(event) => {
+        // A deck text leaf is a plain string, and the field yields `textContent`
+        // — so pasted markup would show live formatting that vanishes on blur,
+        // and pasted block elements would join with no separator at all
+        // (`<div>a</div><div>b</div>` reads back as "ab"). Take the plain text
+        // and flatten its line breaks to spaces, which is what a one-line field
+        // can honestly hold.
+        event.preventDefault();
+        const text = event.clipboardData.getData("text/plain").replace(/\s+/g, " ").trim();
+        const doc = event.currentTarget.ownerDocument;
+        // Guarded because jsdom does not implement it; `insertText` is used
+        // rather than a Selection-API splice because it is what keeps the
+        // field's native undo stack intact.
+        if (text !== "" && typeof doc.execCommand === "function") doc.execCommand("insertText", false, text);
+      }}
+      onBlur={(event) => {
+        if (cancelled.current) {
+          cancelled.current = false;
+          onCancel();
+          return;
+        }
+        onCommit(event.currentTarget.textContent ?? "");
+      }}
+      className="rounded-[var(--radius-inner)] outline-2 outline-offset-2 outline-[var(--deck-accent)]"
+    />
+  );
+}

package/src/deck/flip.ts

@@ -0,0 +1,70 @@
+/**
+ * FLIP for the image grid's expand/collapse.
+ *
+ * The grid changes layout via React state, so the "First" rects have to be
+ * taken in the event handler (before `setState`) and the invert applied in a
+ * layout effect (after the DOM has moved, before paint).
+ */
+
+const TILE_SELECTOR = "[data-deck-tile]";
+
+export type TileRects = Map<Element, DOMRect>;
+
+export function captureTileRects(grid: HTMLElement): TileRects {
+  const rects: TileRects = new Map();
+  for (const tile of grid.querySelectorAll(TILE_SELECTOR)) rects.set(tile, tile.getBoundingClientRect());
+  return rects;
+}
+
+/**
+ * Rects are screen-space but the transform applies inside the stage, which is
+ * itself scaled — so translations divide by that scale or the tile overshoots
+ * by exactly the stage factor. `DeckStage` publishes it as `data-deck-scale`.
+ */
+function stageScale(el: Element): number {
+  const raw = el.closest("[data-deck-stage]")?.getAttribute("data-deck-scale");
+  const value = raw === null || raw === undefined ? Number.NaN : Number(raw);
+  return Number.isFinite(value) && value > 0 ? value : 1;
+}
+
+export function playTileFlip(grid: HTMLElement, before: TileRects): void {
+  const scale = stageScale(grid);
+  const moved: HTMLElement[] = [];
+
+  for (const tile of grid.querySelectorAll<HTMLElement>(TILE_SELECTOR)) {
+    const first = before.get(tile);
+    if (!first) continue;
+    const last = tile.getBoundingClientRect();
+    // Unmeasurable boxes (jsdom, a hidden ancestor) invert to NaN; skip them
+    // and the tile simply lands without an animation.
+    if (!first.width || !last.width) continue;
+
+    // Inverted about the element's CENTER, which is `transform-origin`'s
+    // default — so this never sets the property and never has to clean it up.
+    // A top-left origin would have to be cleared, and clearing it synchronously
+    // jumps an in-flight animation while leaving it behind makes the tile's
+    // next hover scale from its corner instead of its middle.
+    const dx = (first.left + first.width / 2 - (last.left + last.width / 2)) / scale;
+    const dy = (first.top + first.height / 2 - (last.top + last.height / 2)) / scale;
+    const sx = first.width / last.width;
+    const sy = first.height / last.height;
+    if (Math.abs(dx) < 0.5 && Math.abs(dy) < 0.5 && Math.abs(sx - 1) < 0.002) continue;
+
+    tile.style.transition = "none";
+    tile.style.transform = `translate(${dx}px, ${dy}px) scale(${sx}, ${sy})`;
+    moved.push(tile);
+  }
+
+  if (moved.length === 0) return;
+
+  // Commit the inverted start state with a synchronous reflow, NOT
+  // requestAnimationFrame: rAF does not run in a background tab, and a deck
+  // left on an inactive tab would come back with every tile stranded under its
+  // inverse transform.
+  void grid.offsetWidth;
+
+  for (const tile of moved) {
+    tile.style.transition = "";
+    tile.style.transform = "";
+  }
+}

package/src/deck/index.ts

@@ -0,0 +1,30 @@
+/**
+ * The deck runtime — a sealed subtree, like ./document.
+ *
+ * NOT re-exported from the primitives root barrel, and deliberately not a
+ * section type: nothing on an ordinary viewer page may pull this graph in.
+ * Only deck surfaces (the Deck Builder, in-portal deck views, the Public Link
+ * route) import from here.
+ */
+export { DeckPlayer } from "./DeckPlayer";
+export { DeckStage } from "./DeckStage";
+export { DeckSlideView } from "./DeckSlideView";
+export { DeckComponentView } from "./DeckComponentView";
+export { CenteredTextLayout } from "./layouts/CenteredTextLayout";
+export { ColumnSplitLayout } from "./layouts/ColumnSplitLayout";
+export { FullBleedImageLayout } from "./layouts/FullBleedImageLayout";
+export { DeckRichText } from "./components/DeckRichText";
+export { DeckImage } from "./components/DeckImage";
+export { DeckImageGrid } from "./components/DeckImageGrid";
+export { DeckVideo } from "./components/DeckVideo";
+export {
+  DeckMediaProvider,
+  DeckMissingMedia,
+  useDeckMedia,
+  useDeckMediaResolver,
+  type DeckMediaAsset,
+  type DeckMediaResolver,
+} from "./media";
+export { DeckTextEditProvider, EditableText, useDeckTextEditor, type DeckTextEditor } from "./editing";
+export { useStageScale } from "./useStageScale";
+export { deckAlign, surfaceInk, DECK_ELEVATION, SURFACE_BACKGROUND, type DeckAlign, type DeckSurface } from "./tokens";

package/src/deck/layouts/CenteredTextLayout.tsx

@@ -0,0 +1,29 @@
+import { cn } from "../../lib/cn";
+import type { CenteredTextLayout as CenteredTextLayoutNode } from "../../schemas/deck";
+import { DeckComponentView } from "../DeckComponentView";
+import { deckAlign, SURFACE_BACKGROUND, surfaceInk } from "../tokens";
+
+interface Props {
+  layout: CenteredTextLayoutNode;
+}
+
+/**
+ * Layout — centered text. A full-slide title card holding one Deck Component,
+ * centered on both axes. The Layout owns the surface (background + ink tokens)
+ * and the stage-relative padding; the component owns nothing but its own type.
+ */
+export function CenteredTextLayout({ layout }: Props) {
+  return (
+    <div
+      data-deck-layout="centeredText"
+      data-deck-surface={layout.background}
+      style={{ ...surfaceInk(layout.background), ...deckAlign("center") }}
+      className={cn(
+        "flex size-full flex-col items-center justify-center px-[180px] py-[110px] text-center",
+        SURFACE_BACKGROUND[layout.background],
+      )}
+    >
+      <DeckComponentView component={layout.content} slot="content" />
+    </div>
+  );
+}

package/src/deck/layouts/ColumnSplitLayout.tsx

@@ -0,0 +1,69 @@
+import { cn } from "../../lib/cn";
+import type { ColumnSplitLayout as ColumnSplitLayoutNode, DeckComponent, DeckSplitRatio } from "../../schemas/deck";
+import { DeckComponentView } from "../DeckComponentView";
+import { deckAlign, SURFACE_BACKGROUND, surfaceInk } from "../tokens";
+
+interface Props {
+  layout: ColumnSplitLayoutNode;
+}
+
+const RATIO: Record<DeckSplitRatio, string> = {
+  "1-2": "grid-cols-[1fr_2fr]",
+  "2-1": "grid-cols-[2fr_1fr]",
+};
+
+/**
+ * How much air a column gives its component. Text needs generous margins; an
+ * image is meant to run to the stage edge; a grid and a video need enough
+ * breathing room for a tile to lift without clipping.
+ */
+const COLUMN_PADDING: Record<DeckComponent["type"], string> = {
+  richText: "flex flex-col justify-center px-[64px] py-[96px]",
+  image: "",
+  imageGrid: "p-[44px]",
+  video: "p-[44px]",
+};
+
+/**
+ * Layout — left/right column split.
+ *
+ * The hairline runs down the text column's inner edge, which is the editorial
+ * treatment's only separator: the columns are set apart by the type and the
+ * crop, not by a card or a shadow.
+ */
+export function ColumnSplitLayout({ layout }: Props) {
+  // The rule belongs to the seam, so exactly one column ever draws it. Asking
+  // each text column for its own inner border drew a 2px rule whenever both
+  // columns held text — the one case where the hairline is doing the most work.
+  const seam = layout.left.type === "richText" ? "left" : layout.right.type === "richText" ? "right" : null;
+
+  return (
+    <div
+      data-deck-layout="columnSplit"
+      data-deck-ratio={layout.ratio}
+      data-deck-surface="base"
+      style={{ ...surfaceInk("base"), ...deckAlign("start") }}
+      className={cn("grid size-full text-left", RATIO[layout.ratio], SURFACE_BACKGROUND.base)}
+    >
+      <Column component={layout.left} side="left" rule={seam === "left"} />
+      <Column component={layout.right} side="right" rule={seam === "right"} />
+    </div>
+  );
+}
+
+// `side` doubles as the edit-seam slot name (see DeckTextPath) — the two are
+// the same coordinate, so keeping one avoids a mapping that could drift.
+function Column({ component, side, rule }: { component: DeckComponent; side: "left" | "right"; rule: boolean }) {
+  return (
+    <div
+      data-deck-column={side}
+      className={cn(
+        "relative min-w-0 overflow-hidden",
+        COLUMN_PADDING[component.type],
+        rule && (side === "left" ? "border-r border-base-200" : "border-l border-base-200"),
+      )}
+    >
+      <DeckComponentView component={component} slot={side} />
+    </div>
+  );
+}

package/src/deck/layouts/FullBleedImageLayout.tsx

@@ -0,0 +1,58 @@
+import { cn } from "../../lib/cn";
+import type { DeckOverlayPlacement, FullBleedImageLayout as FullBleedImageLayoutNode } from "../../schemas/deck";
+import { DeckRichText } from "../components/DeckRichText";
+import { DeckMissingMedia, useDeckMedia } from "../media";
+import { deckAlign, SURFACE_BACKGROUND, surfaceInk } from "../tokens";
+
+interface Props {
+  layout: FullBleedImageLayoutNode;
+}
+
+/**
+ * Panel geometry, stage-relative. Hard edges and full bleed to the stage sides
+ * — the panel is a block of brand color laid over the picture, not a card
+ * floating on it.
+ */
+const PLACEMENT: Record<DeckOverlayPlacement, string> = {
+  sideLeft: "top-0 bottom-0 left-0 w-[40%] justify-center px-[72px] py-[90px]",
+  sideRight: "top-0 bottom-0 right-0 w-[40%] justify-center px-[72px] py-[90px]",
+  bottomBand: "right-0 bottom-0 left-0 justify-end px-[96px] py-[56px]",
+};
+
+/**
+ * Layout — full-bleed image with an optional text overlay panel.
+ *
+ * The Layout owns both surfaces: the slide is base (the image covers it), the
+ * panel declares brand, so the rich text inside reads on-primary ink without
+ * knowing it sits over a photograph.
+ */
+export function FullBleedImageLayout({ layout }: Props) {
+  const asset = useDeckMedia(layout.media);
+  const { overlay } = layout;
+
+  return (
+    <div
+      data-deck-layout="fullBleedImage"
+      data-deck-surface="base"
+      style={{ ...surfaceInk("base"), ...deckAlign("start") }}
+      className={cn("relative size-full overflow-hidden", SURFACE_BACKGROUND.base)}
+    >
+      {asset === null ? (
+        <DeckMissingMedia className="absolute inset-0" />
+      ) : (
+        <img src={asset.src} alt={asset.alt} className="absolute inset-0 size-full object-cover" />
+      )}
+
+      {overlay !== undefined && (
+        <div
+          data-deck-overlay={overlay.placement}
+          data-deck-surface="brand"
+          style={surfaceInk("brand")}
+          className={cn("absolute z-[2] flex flex-col text-left", SURFACE_BACKGROUND.brand, PLACEMENT[overlay.placement])}
+        >
+          <DeckRichText content={overlay.content} slot="overlay" />
+        </div>
+      )}
+    </div>
+  );
+}