feat(engine,client): show the marker token a face-down permanent was made with (#7532)

client/src/adapter/types.ts

@@ -795,6 +795,18 @@ export interface TokenCharacteristics {
   keywords: Keyword[];
 }
 
+/**
+ * Which keyword action put a permanent onto the battlefield face down
+ * (engine `FaceDownCause`). Only meaningful while `face_down` is true.
+ * `TurnedFaceDown` is the Ixidron class, for which no marker token is printed.
+ */
+export type FaceDownCause =
+  | "Manifest"
+  | "Morph"
+  | "Cloak"
+  | "Disguise"
+  | "TurnedFaceDown";
+
 export interface TokenImageRef {
   scryfall_id: string;
   scryfall_oracle_id?: string | null;
@@ -1008,6 +1020,8 @@ export interface GameObject {
   display_visible_to_viewer?: boolean;
   tapped: boolean;
   face_down: boolean;
+  /** Set only while `face_down` is true; absent on older saves. */
+  face_down_cause?: FaceDownCause | null;
   flipped: boolean;
   transformed: boolean;
   damage_marked: number;

client/src/components/board/AttachmentFan.tsx

@@ -319,6 +319,7 @@ function FanCard({
           tokenImageRef={isToken ? obj.token_image_ref : undefined}
           oracleText={isToken ? obj.token_rules_text : undefined}
           faceDown={shouldRenderCardBack(obj)}
+          faceDownCause={obj.face_down ? obj.face_down_cause : undefined}
           className="!w-[var(--fan-card-w)] !h-[var(--fan-card-h)]"
         />
       </div>

client/src/components/board/PermanentCard.tsx

@@ -913,7 +913,7 @@ export const PermanentCard = memo(function PermanentCard({
       ) : (
         <>
           <div className="relative z-10 rounded-lg overflow-hidden">
-            <CardImage cardName={imgName} faceIndex={imgFace} oracleId={imgOracleId} faceName={imgFaceName} size="small" unimplementedMechanics={obj.unimplemented_mechanics} colors={displayColors} isToken={obj.display_source === "Token"} tokenFilters={obj.display_source === "Token" ? tokenFiltersForObject(obj) : undefined} tokenImageRef={obj.token_image_ref} oracleText={obj.display_source === "Token" ? obj.token_rules_text : undefined} faceDown={renderCardBack} />
+            <CardImage cardName={imgName} faceIndex={imgFace} oracleId={imgOracleId} faceName={imgFaceName} size="small" unimplementedMechanics={obj.unimplemented_mechanics} colors={displayColors} isToken={obj.display_source === "Token"} tokenFilters={obj.display_source === "Token" ? tokenFiltersForObject(obj) : undefined} tokenImageRef={obj.token_image_ref} oracleText={obj.display_source === "Token" ? obj.token_rules_text : undefined} faceDown={renderCardBack} faceDownCause={obj.face_down ? obj.face_down_cause : undefined} />
             {/* CR 702.26: phased-out tint overlay — sky-blue mix-blend-screen
                 matches the player-area treatment (PlayerArea.tsx 4d6cfb506). */}
             {isPhasedOut && (
@@ -1266,7 +1266,7 @@ const ExileGhostCard = memo(function ExileGhostCard({ objectId, offset }: ExileG
       {useArtCrop ? (
         <ArtCropCard objectId={objectId} />
       ) : (
-        <CardImage cardName={imgName} faceIndex={imgFace} oracleId={imgOracleId} faceName={imgFaceName} size="small" colors={displayColors} isToken={obj.display_source === "Token"} tokenFilters={obj.display_source === "Token" ? tokenFiltersForObject(obj) : undefined} tokenImageRef={obj.token_image_ref} oracleText={obj.display_source === "Token" ? obj.token_rules_text : undefined} faceDown={obj.face_down} />
+        <CardImage cardName={imgName} faceIndex={imgFace} oracleId={imgOracleId} faceName={imgFaceName} size="small" colors={displayColors} isToken={obj.display_source === "Token"} tokenFilters={obj.display_source === "Token" ? tokenFiltersForObject(obj) : undefined} tokenImageRef={obj.token_image_ref} oracleText={obj.display_source === "Token" ? obj.token_rules_text : undefined} faceDown={obj.face_down} faceDownCause={obj.face_down_cause} />
       )}
     </div>
   );

client/src/components/card/ArtCropCard.tsx

@@ -8,6 +8,7 @@ import { useIsMobile } from "../../hooks/useIsMobile.ts";
 import { isUnbounded, pillsOf, useCounterDisplay } from "../../hooks/useCounterDisplay.ts";
 import { cardImageLookup, tokenFiltersForObject } from "../../services/cardImageLookup.ts";
 import { CARD_BACK_URL } from "../../services/scryfall.ts";
+import { faceDownMarkerRef } from "./faceDownMarker.ts";
 import { useGameStore } from "../../stores/gameStore.ts";
 import { useUiStore } from "../../stores/uiStore.ts";
 import { COUNTER_COLORS, computePTDisplay, hasOtherPrintedFace, shouldRenderCardBack, toRoman } from "../../viewmodel/cardProps.ts";
@@ -43,12 +44,20 @@ export const ArtCropCard = memo(function ArtCropCard({ objectId }: ArtCropCardPr
     ? cardImageLookup(obj)
     : { name: "", faceIndex: 0, oracleId: undefined, faceName: undefined };
   const isToken = obj?.display_source === "Token";
+  // A face-down permanent shows the marker token for the ability that turned it
+  // face down (Morph / Manifest / A Mysterious Creature), the way paper play
+  // does. Without a marker the card back is rendered exactly as before.
+  const faceDownMarker = faceDownMarkerRef(obj?.face_down ?? false, obj?.face_down_cause);
   const { src: cardSrc, isLoading: cardLoading } = useCardImage(renderCardBack ? "" : imageLookup.name, {
     size: "art_crop",
     faceIndex: imageLookup.faceIndex,
-    isToken: renderCardBack ? false : isToken,
+    isToken: renderCardBack ? faceDownMarker !== null : isToken,
     tokenFilters: !renderCardBack && isToken && obj ? tokenFiltersForObject(obj) : undefined,
-    tokenImageRef: !renderCardBack && isToken && obj ? obj.token_image_ref : undefined,
+    tokenImageRef: renderCardBack
+      ? (faceDownMarker ?? undefined)
+      : isToken && obj
+        ? obj.token_image_ref
+        : undefined,
     oracleId: renderCardBack ? undefined : imageLookup.oracleId,
     faceName: renderCardBack ? undefined : imageLookup.faceName,
   });
@@ -74,7 +83,7 @@ export const ArtCropCard = memo(function ArtCropCard({ objectId }: ArtCropCardPr
 
   if (!obj) return null;
 
-  const src = renderCardBack ? CARD_BACK_URL : cardSrc;
+  const src = renderCardBack ? (cardSrc ?? CARD_BACK_URL) : cardSrc;
   const isLoading = renderCardBack ? false : cardLoading;
   // CR 712 vs CR 710: `back_face != null` is NOT "has a second face" — a
   // Kamigawa flip card stores its alternative half in the same slot and has no
@@ -110,7 +119,13 @@ export const ArtCropCard = memo(function ArtCropCard({ objectId }: ArtCropCardPr
     );
   }
 
-  const renderedSrc = renderCardBack ? CARD_BACK_URL : (src ?? "");
+  // The card back is the fallback in BOTH directions: a marker that never
+  // resolves and a marker URL whose `<img>` fails to load both land here. The
+  // artless text tile below is for face-UP cards with no printing; a face-down
+  // permanent always has the card back to fall back to.
+  const renderedSrc = renderCardBack
+    ? (artError ? CARD_BACK_URL : (src ?? CARD_BACK_URL))
+    : (src ?? "");
   const headerHeight = isCompactHeight
     ? "clamp(8px, calc(var(--art-crop-h) * 0.16), 12px)"
     : "clamp(8px, calc(var(--art-crop-h) * 0.18), 20px)";
@@ -185,7 +200,7 @@ export const ArtCropCard = memo(function ArtCropCard({ objectId }: ArtCropCardPr
                   an artless permanent loses its picture but never its game
                   state. `src` is non-null for face-down cards (CARD_BACK_URL),
                   so those still render the card back here. */}
-              {src && !artError ? (
+              {renderCardBack || (src && !artError) ? (
                 <img
                   src={renderedSrc}
                   alt={cardName}

client/src/components/card/CardImage.tsx

@@ -3,8 +3,9 @@ import { useTranslation } from "react-i18next";
 import { useCardImage } from "../../hooks/useCardImage.ts";
 import { useEngineCardData } from "../../hooks/useEngineCardData.ts";
 import type { TokenSearchFilters } from "../../services/scryfall.ts";
-import type { TokenImageRef } from "../../adapter/types.ts";
+import type { FaceDownCause, TokenImageRef } from "../../adapter/types.ts";
 import { CARD_BACK_URL } from "../../services/scryfall.ts";
+import { faceDownMarkerRef } from "./faceDownMarker.ts";
 import { getBevelBorderStyle } from "./cardFrame.ts";
 import { getCardImageSrcSetProps } from "./cardImageSrcSet.ts";
 import { CardArtFallback } from "./CardArtFallback.tsx";
@@ -23,6 +24,12 @@ interface CardImageProps {
   tokenFilters?: TokenSearchFilters;
   tokenImageRef?: TokenImageRef | null;
   faceDown?: boolean;
+  /**
+   * Which keyword action turned the permanent face down. Selects the marker
+   * token paper play uses (Morph / Manifest / A Mysterious Creature); without
+   * it — or for a cause with no printed marker — the generic card back stays.
+   */
+  faceDownCause?: FaceDownCause | null;
   /**
    * Renders a {T} symbol overlay in the corner to mark a tapped battlefield
    * permanent. Used by selection modals — which display cards upright rather
@@ -56,18 +63,24 @@ export function CardImage({
   tokenFilters,
   tokenImageRef,
   faceDown = false,
+  faceDownCause,
   tapIndicator = false,
   oracleId,
   faceName,
   oracleText,
 }: CardImageProps) {
   const { t } = useTranslation("game");
+  // A face-down permanent shows the marker token for the ability that turned it
+  // face down, the way paper play does. With no marker (unknown cause, or the
+  // Ixidron class, which has no printing) the lookup is skipped entirely and the
+  // generic card back is rendered exactly as before.
+  const faceDownMarker = faceDownMarkerRef(faceDown, faceDownCause);
   const { src, isLoading } = useCardImage(faceDown ? "" : cardName, {
     size,
     faceIndex,
-    isToken: faceDown ? false : isToken,
+    isToken: faceDown ? faceDownMarker !== null : isToken,
     tokenFilters: faceDown ? undefined : tokenFilters,
-    tokenImageRef: faceDown ? undefined : tokenImageRef,
+    tokenImageRef: faceDown ? (faceDownMarker ?? undefined) : tokenImageRef,
     oracleId: faceDown ? undefined : oracleId,
     faceName: faceDown ? undefined : faceName,
   });
@@ -113,7 +126,15 @@ export function CardImage({
   //   - `imageError`: the resolved `<img>` failed to load.
   // Both render the card/token name (and Oracle text when known) so every artless
   // card or token — not just one hard-coded name — stays identifiable.
-  const renderedSrc = faceDown ? CARD_BACK_URL : (src ?? "");
+  // The card back is the fallback in BOTH directions: a marker that never
+  // resolves (`!src`) and a marker URL whose `<img>` fails to load
+  // (`imageError` — offline, CDN gap, stale printing) both fall back to it. A
+  // face-down permanent must never render a broken image, and it must never
+  // fall through to the artless text tile either: `showArtFallback` stays gated
+  // on `!faceDown`, so this is the only fallback the face-down path has.
+  const renderedSrc = faceDown
+    ? (imageError ? CARD_BACK_URL : (src ?? CARD_BACK_URL))
+    : (src ?? "");
   const renderedAlt = faceDown ? t("card.faceDownName") : cardName;
 
   return (

client/src/components/card/__tests__/ArtCropCard.test.tsx

@@ -3,6 +3,7 @@ import { afterEach, beforeEach, describe, expect, it, vi } from "vitest";
 
 import type { GameObject } from "../../../adapter/types.ts";
 import { useCardImage } from "../../../hooks/useCardImage.ts";
+import { CARD_BACK_URL } from "../../../services/scryfall.ts";
 import { useGameStore } from "../../../stores/gameStore.ts";
 import { ArtCropCard } from "../ArtCropCard.tsx";
 
@@ -278,6 +279,43 @@ describe("ArtCropCard", () => {
     expect(screen.getByAltText("Hidden Sorcery")).toBeInTheDocument();
   });
 
+  it("falls back to the card back when face-down marker art fails to load", () => {
+    // ArtCropCard is the default battlefield renderer. Keep its marker failure
+    // path covered separately from CardImage: the component owns its own
+    // artError state and must never leave a face-down permanent as a broken
+    // image when a marker printing is unavailable.
+    mockUseCardImage.mockReturnValue({
+      src: "https://cards.scryfall.io/normal/front/m/a/manifest.jpg",
+      isLoading: false,
+      isRotated: false,
+      isFlip: false,
+    });
+    const permanent = {
+      ...transformedPermanent(),
+      face_down: true,
+      face_down_cause: "Manifest" as const,
+      transformed: false,
+      back_face: null,
+      color: [],
+      base_color: [],
+    };
+    useGameStore.setState({
+      gameState: { objects: { [permanent.id]: permanent } } as never,
+    });
+
+    render(<ArtCropCard objectId={101} />);
+
+    const marker = screen.getByAltText("Face-down card");
+    expect(marker).toHaveAttribute(
+      "src",
+      "https://cards.scryfall.io/normal/front/m/a/manifest.jpg",
+    );
+
+    fireEvent.error(marker);
+
+    expect(screen.getByAltText("Face-down card")).toHaveAttribute("src", CARD_BACK_URL);
+  });
+
   it("keeps loyalty and P/T readable for planeswalkers and creature planeswalkers", () => {
     mockUseCardImage.mockReturnValue({
       src: "card.png",

client/src/components/card/__tests__/CardImage.test.tsx

@@ -227,3 +227,54 @@ describe("CardImage art fallback (issue #6156)", () => {
     expect(img!.getAttribute("src")).toBe("https://example.invalid/back.png");
   });
 });
+
+describe("CardImage face-down marker (#7532)", () => {
+  it("renders the marker token art for a face-down permanent", () => {
+    mockUseCardImage.mockReturnValue({
+      src: "https://cards.scryfall.io/normal/front/m/a/manifest.jpg",
+      isLoading: false,
+      isRotated: false,
+      isFlip: false,
+    });
+
+    render(<CardImage cardName="Hidden" faceDown faceDownCause="Manifest" />);
+
+    const img = screen.getByRole("img");
+    expect(img).toHaveAttribute(
+      "src",
+      "https://cards.scryfall.io/normal/front/m/a/manifest.jpg",
+    );
+  });
+
+  it("falls back to the card back when the marker image fails to load", () => {
+    mockUseCardImage.mockReturnValue({
+      src: "https://cards.scryfall.io/normal/front/m/a/manifest.jpg",
+      isLoading: false,
+      isRotated: false,
+      isFlip: false,
+    });
+
+    render(<CardImage cardName="Hidden" faceDown faceDownCause="Manifest" />);
+    const img = screen.getByRole("img");
+    // A resolved marker URL can still 404 (CDN gap, stale printing). A face-down
+    // permanent must never show a broken image, and must not fall through to the
+    // artless text tile either — the card back is its only fallback.
+    fireEvent.error(img);
+
+    expect(screen.getByRole("img")).toHaveAttribute("src", CARD_BACK_URL);
+  });
+
+  it("keeps the card back when no marker applies", () => {
+    mockUseCardImage.mockReturnValue({
+      src: null,
+      isLoading: false,
+      isRotated: false,
+      isFlip: false,
+    });
+
+    // `TurnedFaceDown` (Ixidron) has no printed marker token.
+    render(<CardImage cardName="Hidden" faceDown faceDownCause="TurnedFaceDown" />);
+
+    expect(screen.getByRole("img")).toHaveAttribute("src", CARD_BACK_URL);
+  });
+});

client/src/components/card/__tests__/faceDownMarker.test.ts

@@ -0,0 +1,31 @@
+import { describe, expect, it } from "vitest";
+import { faceDownMarkerRef } from "../faceDownMarker.ts";
+
+describe("faceDownMarkerRef", () => {
+  it("maps each rules cause onto the printing paper play uses", () => {
+    expect(faceDownMarkerRef(true, "Manifest")?.face_name).toBe("manifest");
+    expect(faceDownMarkerRef(true, "Morph")?.face_name).toBe("morph");
+    // Cloak (CR 701.58a) and disguise (CR 702.168a) are different rules that
+    // share one printed token — the mapping is where they converge, not the
+    // engine's enum.
+    expect(faceDownMarkerRef(true, "Cloak")?.face_name).toBe("a mysterious creature");
+    expect(faceDownMarkerRef(true, "Disguise")?.face_name).toBe("a mysterious creature");
+    expect(faceDownMarkerRef(true, "Cloak")?.scryfall_oracle_id).toBe(
+      faceDownMarkerRef(true, "Disguise")?.scryfall_oracle_id,
+    );
+  });
+
+  it("has no marker for a cause with no printed token", () => {
+    // Ixidron turns permanents face down with no keyword action, and Wizards
+    // prints nothing for it — the generic card back stays.
+    expect(faceDownMarkerRef(true, "TurnedFaceDown")).toBeNull();
+  });
+
+  it("stays null unless the permanent is actually face down", () => {
+    // The engine leaves the cause on the object after it turns face up, so
+    // every reader must gate on `face_down`. This is that gate.
+    expect(faceDownMarkerRef(false, "Manifest")).toBeNull();
+    expect(faceDownMarkerRef(true, null)).toBeNull();
+    expect(faceDownMarkerRef(true, undefined)).toBeNull();
+  });
+});

client/src/components/card/faceDownMarker.ts

@@ -0,0 +1,61 @@
+import type { FaceDownCause, TokenImageRef } from "../../adapter/types.ts";
+
+/**
+ * The marker token Wizards prints for each face-down family.
+ *
+ * Paper play uses these as the required "what ability caused them to be face
+ * down" reminder (Duskmourn rulings, 2024-09-20), and the engine already tells
+ * us the cause. Mapping the cause onto a printing is a display decision, which
+ * is why the ids live here and not in the engine: four rules-level causes share
+ * three printed tokens, and one cause has no token at all.
+ *
+ * Oracle ids are used rather than a single printing's Scryfall id so the lookup
+ * survives a reprint — `fetchTokenImageByRef` falls back to the oracle key that
+ * `scryfall-token-images.json` already indexes for all three.
+ */
+const MARKERS: Partial<Record<FaceDownCause, TokenImageRef>> = {
+  // https://scryfall.com/card/tfrf/4/manifest — also used for manifest dread,
+  // which is the same keyword action with a different card-selection step.
+  Manifest: {
+    scryfall_id: "",
+    scryfall_oracle_id: "f4f184ef-f456-47d8-9012-095629a5ea4d",
+    face_name: "manifest",
+    preset_id: "face-down-manifest",
+  },
+  // https://scryfall.com/card/tdtk/7/morph — megamorph shares it.
+  Morph: {
+    scryfall_id: "",
+    scryfall_oracle_id: "8f92f8d7-ec89-426f-86dc-fbc259eb5559",
+    face_name: "morph",
+    preset_id: "face-down-morph",
+  },
+  // https://scryfall.com/card/tmkm/21/a-mysterious-creature — cloak and
+  // disguise are different rules (CR 701.58a vs CR 702.168a) with one printing.
+  Cloak: {
+    scryfall_id: "",
+    scryfall_oracle_id: "6481a124-6859-4f02-9fd3-b1302528dd2e",
+    face_name: "a mysterious creature",
+    preset_id: "face-down-cloak",
+  },
+  Disguise: {
+    scryfall_id: "",
+    scryfall_oracle_id: "6481a124-6859-4f02-9fd3-b1302528dd2e",
+    face_name: "a mysterious creature",
+    preset_id: "face-down-cloak",
+  },
+  // `TurnedFaceDown` (Ixidron class) is deliberately absent: no marker token is
+  // printed for it, so it keeps the generic card back.
+};
+
+/**
+ * The marker printing for a face-down permanent, or `null` when none applies —
+ * the permanent is face up, the engine did not record a cause (older saves), or
+ * the cause has no printed token.
+ */
+export function faceDownMarkerRef(
+  faceDown: boolean,
+  cause: FaceDownCause | null | undefined,
+): TokenImageRef | null {
+  if (!faceDown || !cause) return null;
+  return MARKERS[cause] ?? null;
+}