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,9 @@ export const ArtCropCard = memo(function ArtCropCard({ objectId }: ArtCropCardPr
     );
   }
 
-  const renderedSrc = renderCardBack ? CARD_BACK_URL : (src ?? "");
+  // The card back remains the fallback: a marker that fails to resolve must not
+  // leave the permanent blank.
+  const renderedSrc = renderCardBack ? (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)";

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,9 @@ 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 remains the fallback: a marker that fails to resolve (offline,
+  // missing printing) must not leave the permanent blank.
+  const renderedSrc = faceDown ? (src ?? CARD_BACK_URL) : (src ?? "");
   const renderedAlt = faceDown ? t("card.faceDownName") : cardName;
 
   return (

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.166a) 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.166a) 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;
+}

crates/engine/src/game/casting.rs

@@ -10340,10 +10340,15 @@ fn face_down_cast_profile(
     state: &GameState,
     object_id: ObjectId,
 ) -> crate::types::ability::FaceDownProfile {
+    // CR 702.166a / CR 702.36a: a face-down CAST reuses the manifest/cloak
+    // characteristics but is a different keyword action, so it restates the
+    // cause instead of leaving the constructor's default in place.
     if super::keywords::object_has_effective_keyword_kind(state, object_id, KeywordKind::Disguise) {
         crate::types::ability::FaceDownProfile::cloaked_2_2()
+            .caused_by(crate::types::ability::FaceDownCause::Disguise)
     } else {
         crate::types::ability::FaceDownProfile::vanilla_2_2()
+            .caused_by(crate::types::ability::FaceDownCause::Morph)
     }
 }
 

crates/engine/src/game/effects/change_zone.rs

@@ -8049,6 +8049,7 @@ mod tests {
                     extra_core_types: vec![CoreType::Artifact],
                     subtypes: vec!["Cyberman".to_string()],
                     ward: None,
+                    cause: crate::types::ability::FaceDownCause::Manifest,
                 }),
                 library_position: None,
                 random_order: false,
@@ -8738,6 +8739,7 @@ mod tests {
             extra_core_types: vec![CoreType::Land],
             subtypes: vec!["Forest".to_string()],
             ward: None,
+            cause: crate::types::ability::FaceDownCause::Manifest,
         };
 
         let ability = ResolvedAbility::new(

crates/engine/src/game/effects/manifest.rs

@@ -411,6 +411,7 @@ mod tests {
             extra_core_types: vec![CoreType::Artifact],
             subtypes: vec!["Cyberman".to_string()],
             ward: None,
+            cause: crate::types::ability::FaceDownCause::Manifest,
         };
         let ability = ResolvedAbility::new(
             Effect::Manifest {

crates/engine/src/game/effects/turn_face_down.rs

@@ -149,6 +149,7 @@ mod tests {
             extra_core_types: vec![CoreType::Artifact],
             subtypes: vec!["Cyberman".to_string()],
             ward: None,
+            cause: crate::types::ability::FaceDownCause::TurnedFaceDown,
         }
     }
 

crates/engine/src/game/game_object.rs

@@ -430,6 +430,23 @@ pub struct GameObject {
     // Battlefield state
     pub tapped: bool,
     pub face_down: bool,
+    /// Which keyword action put this permanent face down (CR 701.40a manifest,
+    /// CR 702.36a morph, CR 701.58a cloak, CR 702.166a disguise). `None` for a
+    /// face-up permanent.
+    ///
+    /// CR 708.2a makes every face-down permanent look alike, so this is not a
+    /// characteristic — it is the public record of how the permanent got here,
+    /// which the 2024-09-20 Duskmourn rulings require play to keep visible. No
+    /// game rule reads it; it exists so the display layer can show the marker
+    /// the physical game uses.
+    ///
+    /// Only meaningful while `face_down` is true. It is stamped on every
+    /// face-down entry and deliberately NOT cleared when the permanent turns
+    /// face up — a dozen unrelated paths clear `face_down`, and requiring each
+    /// to remember a second field is how a stale marker would eventually ship.
+    /// Read it gated on `face_down`.
+    #[serde(default, skip_serializing_if = "Option::is_none")]
+    pub face_down_cause: Option<crate::types::ability::FaceDownCause>,
     pub flipped: bool,
     pub transformed: bool,
     /// CR 701.27f: Number of successful transforms/conversions of this object.
@@ -1284,6 +1301,7 @@ fn _gameobject_partition_is_total(o: &GameObject) {
         display_visible_to_viewer: _,
         tapped: _,
         face_down: _,
+        face_down_cause: _,
         flipped: _,
         transformed: _,
         transformation_count: _,
@@ -2171,6 +2189,7 @@ impl GameObject {
             display_visible_to_viewer: false,
             tapped: false,
             face_down: false,
+            face_down_cause: None,
             flipped: false,
             transformed: false,
             transformation_count: 0,

crates/engine/src/game/morph.rs

@@ -1495,6 +1495,7 @@ mod tests {
             extra_core_types: vec![CoreType::Artifact],
             subtypes: vec!["Cyberman".to_string()],
             ward: None,
+            cause: crate::types::ability::FaceDownCause::Manifest,
         };
         {
             let obj = state.objects.get_mut(&id).unwrap();

crates/engine/src/game/zone_pipeline.rs

@@ -3186,6 +3186,11 @@ pub(crate) fn apply_face_down_entry_profile(
         // survive the entry guard (which runs before exit cleanup); this is the
         // authoritative final assertion that survives it.
         obj.face_down = true;
+        // The public record of WHICH keyword action put this permanent face
+        // down. Re-stamped on every face-down entry, and only meaningful while
+        // `face_down` is true — the many turn-face-up paths leave it alone
+        // rather than each having to remember to clear it.
+        obj.face_down_cause = Some(profile.cause);
         obj.back_face = Some(original);
     }
 }

crates/engine/src/parser/oracle_effect/sequence.rs

@@ -6129,6 +6129,7 @@ pub(super) fn parse_theyre_face_down_profile(lower: &str) -> Option<FaceDownProf
                 extra_core_types,
                 subtypes,
                 ward: None,
+                cause: crate::types::ability::FaceDownCause::Manifest,
             });
         }
         // Extra core type word (Creature excluded — always implicit).
@@ -6269,6 +6270,7 @@ pub(super) fn parse_its_face_down_profile(lower: &str) -> Option<FaceDownProfile
                     extra_core_types,
                     subtypes,
                     ward: None,
+                    cause: crate::types::ability::FaceDownCause::Manifest,
                 }),
                 // "... land/artifact/enchantment/planeswalker." — non-creature
                 // body whose core type is the terminal noun; no implicit
@@ -6287,6 +6289,7 @@ pub(super) fn parse_its_face_down_profile(lower: &str) -> Option<FaceDownProfile
                         extra_core_types,
                         subtypes,
                         ward: None,
+                        cause: crate::types::ability::FaceDownCause::Manifest,
                     })
                 }
             };