recall: AnkiDroid-color occlusion masks by default (mono palette kept as fallback)

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>

Author: 2 people

tool/src/main/kotlin/com/dvdutch/recall/api/RenderNode.kt

@@ -96,10 +96,10 @@ enum class ShapeState {
 
     /**
      * Solid opaque mask for the TESTED shape on the FRONT — the region being asked. Drawn
-     * with a distinguishing high-contrast border so that, among many hide-all masks, the
-     * studier can tell exactly WHICH hidden region they must recall. Still fully opaque:
-     * the answer stays covered. (AnkiDroid renders this pink vs. tan; we do it in
-     * monochrome — see [maskStyle].)
+     * in a distinguishing colour so that, among many hide-all masks, the studier can tell
+     * exactly WHICH hidden region they must recall. Still fully opaque: the answer stays
+     * covered. (Matches AnkiDroid: salmon `#FF8E8E` tested vs. tan `#FFEBA2` inactive by
+     * default — see [maskStyle].)
      */
     MASKED_TESTED,
 

tool/src/main/kotlin/com/dvdutch/recall/ui/OcclusionImage.kt

@@ -39,26 +39,70 @@ import com.thelightphone.sdk.ui.gridUnitsAsDp
  */
 private const val OCCLUSION_TAG = "OcclusionImage"
 
+// --- Mono palette (grayscale-only fallback) -----------------------------------
+
 /**
- * Solid mask fill for masked shapes ([ShapeState.MASKED] / [ShapeState.MASKED_TESTED]).
- * On the black theme a mid/light grey block reads clearly as "something is hidden here"
- * while staying monochrome. Fully opaque so the answer region underneath is genuinely
- * covered — this is identical for tested and inactive masks; the tested one is set apart
- * by its border, never by a lighter/translucent fill.
+ * Solid mask fill for masked shapes under [MaskPalette.Mono]. A mid/light grey block
+ * reads clearly as "something is hidden here" while staying monochrome. Fully opaque so
+ * the answer region underneath is genuinely covered — identical for tested and inactive
+ * masks; the tested one is set apart by its two-tone ring, never by a lighter fill.
  */
-private val MASK_FILL = Color(0xFFBBBBBB)
+private val MONO_MASK_FILL = Color(0xFFBBBBBB)
 
 /**
- * Outline colour for [ShapeState.REVEALED_OUTLINE] shapes (the tested answer on the
- * back). White reads as a highlight ring around the now-visible region on the black
- * theme.
+ * Outline colour for [ShapeState.REVEALED_OUTLINE] under [MaskPalette.Mono]. White reads
+ * as a highlight ring around the now-visible region on the black theme.
  */
-private val OUTLINE_COLOR = Color.White
+private val MONO_OUTLINE_COLOR = Color.White
+
+// --- Anki palette (default — matches AnkiDroid / Anki desktop) -----------------
+//
+// Our base images render in full colour, so the masks match Anki's real IO palette
+// rather than a monochrome stand-in. Values are the authoritative Anki defaults
+// (Anki desktop / AnkiDroid image-occlusion CSS custom properties), corroborated by
+// pixel-sampling the AnkiDroid comparison screenshots:
+//   --inactive-shape-color: #ffeba2   (tan/cream fill)
+//   --active-shape-color:   #ff8e8e   (salmon/red fill — the tested mask on the front)
+//   --highlight-shape-border: 1px #ff8e8e  (red outline of the revealed region on the back)
+// AnkiDroid draws the SAME thin dark 1px border on both inactive and active masks; the
+// tested/inactive distinction is carried purely by the FILL colour (tan vs salmon), so
+// no two-tone ring is used here. The two fills also keep a wide relative-luminance gap
+// (see [relativeLuminance]) so tested vs inactive stays distinguishable if the device
+// grayscales.
+
+/** Anki inactive-mask fill (`--inactive-shape-color: #ffeba2`). */
+private val ANKI_INACTIVE_FILL = Color(0xFFFFEBA2)
+
+/** Anki active/tested-mask fill (`--active-shape-color: #ff8e8e`). */
+private val ANKI_TESTED_FILL = Color(0xFFFF8E8E)
+
+/** Anki revealed-region outline colour (`--highlight-shape-border: #ff8e8e`). */
+private val ANKI_OUTLINE_COLOR = Color(0xFFFF8E8E)
+
+/** Anki shape border (`--inactive/active-shape-border: 1px #212121`), single-tone. */
+private val ANKI_MASK_BORDER = MaskBorder(
+    outerColor = Color(0xFF212121),
+    outerWidthPx = 2f,
+    innerColor = Color(0xFF212121),
+    innerWidthPx = 2f,
+)
 
 /** Outline stroke width, in natural-image pixels (scaled with the image). */
 private const val OUTLINE_STROKE_PX = 2f
 
-// --- Mask styling (the single point a future COLOR mode would swap) -----------
+// --- Mask styling (the single point the palette is swapped) -------------------
+
+/**
+ * Which colour palette the occlusion masks are drawn in. [Anki] is the default — it
+ * matches AnkiDroid / Anki desktop exactly (tan inactive, salmon tested, red revealed
+ * outline) because our images render in full colour. [Mono] is a grayscale-only fallback
+ * (mid-grey block + two-tone ring + white outline) retained for a future device-colour
+ * toggle; there is no settings UI yet.
+ */
+enum class MaskPalette { Anki, Mono }
+
+/** The default palette used everywhere until a device-colour toggle is added. */
+private val DEFAULT_PALETTE = MaskPalette.Anki
 
 /**
  * A two-tone ring drawn around the tested mask: a thick [outerColor] stroke with a
@@ -85,33 +129,67 @@ data class MaskStyle(
     val border: MaskBorder? = null,
 )
 
-/** Border for the tested front mask: heavy black outer ring + white inner ring. */
-private val TESTED_BORDER = MaskBorder(
+/** Mono tested-mask ring: heavy black outer ring + white inner ring (two-tone). */
+private val MONO_TESTED_BORDER = MaskBorder(
     outerColor = Color.Black,
     outerWidthPx = 6f,
     innerColor = Color.White,
     innerWidthPx = 2f,
 )
 
 /**
- * The SINGLE pure mapping from a resolved [ShapeState] to how it must be drawn. Every
- * mask/outline styling decision lives here, so a future COLOR mode (pink tested / tan
- * inactive, behind a settings toggle) is a one-function swap. Returns `null` for
- * [ShapeState.CONTEXT] (draw nothing).
- *
- *  - [ShapeState.MASKED]        → plain solid grey block (inactive, hide-all).
- *  - [ShapeState.MASKED_TESTED] → same solid grey block PLUS a heavy two-tone ring so the
- *    asked region is unmistakable among many masks (monochrome default).
- *  - [ShapeState.REVEALED_OUTLINE] → stroke-only white outline (tested answer, back).
- *  - [ShapeState.CONTEXT]       → null (shows through, drawn nothing).
+ * WCAG relative luminance of [color] in the sRGB space (0 = black, 1 = white). Used to
+ * prove the [MaskPalette.Anki] fills stay distinguishable by brightness alone if the
+ * device grayscales — see the luminance-gap assertion in the mask-style tests.
  */
-fun maskStyle(state: ShapeState): MaskStyle? = when (state) {
-    ShapeState.CONTEXT -> null
-    ShapeState.MASKED -> MaskStyle(filled = true, fill = MASK_FILL)
-    ShapeState.MASKED_TESTED -> MaskStyle(filled = true, fill = MASK_FILL, border = TESTED_BORDER)
-    ShapeState.REVEALED_OUTLINE -> MaskStyle(filled = false, fill = OUTLINE_COLOR)
+fun relativeLuminance(color: Color): Double {
+    fun lin(c: Float): Double {
+        val d = c.toDouble()
+        return if (d <= 0.03928) d / 12.92 else Math.pow((d + 0.055) / 1.055, 2.4)
+    }
+    return 0.2126 * lin(color.red) + 0.7152 * lin(color.green) + 0.0722 * lin(color.blue)
 }
 
+/**
+ * The SINGLE pure mapping from a resolved [ShapeState] to how it must be drawn, under the
+ * chosen [palette]. Every mask/outline styling decision lives here, so switching palettes
+ * (once a device-colour toggle exists) is a one-argument swap. [palette] defaults to
+ * [MaskPalette.Anki]. Returns `null` for [ShapeState.CONTEXT] (draw nothing).
+ *
+ * [MaskPalette.Anki] (default — our images are full colour, so match AnkiDroid exactly):
+ *  - [ShapeState.MASKED]        → solid tan `#FFEBA2` block + thin dark border.
+ *  - [ShapeState.MASKED_TESTED] → solid salmon `#FF8E8E` block + the SAME thin dark border
+ *    (the tested/inactive distinction is the fill colour, matching AnkiDroid — no ring).
+ *  - [ShapeState.REVEALED_OUTLINE] → stroke-only red `#FF8E8E` outline (revealed answer).
+ *
+ * [MaskPalette.Mono] (grayscale-only fallback):
+ *  - [ShapeState.MASKED]        → plain solid grey block.
+ *  - [ShapeState.MASKED_TESTED] → same grey block PLUS a heavy two-tone ring.
+ *  - [ShapeState.REVEALED_OUTLINE] → stroke-only white outline.
+ *
+ * [ShapeState.CONTEXT] → null (shows through, drawn nothing) in both palettes.
+ */
+fun maskStyle(state: ShapeState, palette: MaskPalette = DEFAULT_PALETTE): MaskStyle? =
+    when (palette) {
+        MaskPalette.Anki -> when (state) {
+            ShapeState.CONTEXT -> null
+            ShapeState.MASKED ->
+                MaskStyle(filled = true, fill = ANKI_INACTIVE_FILL, border = ANKI_MASK_BORDER)
+            ShapeState.MASKED_TESTED ->
+                MaskStyle(filled = true, fill = ANKI_TESTED_FILL, border = ANKI_MASK_BORDER)
+            ShapeState.REVEALED_OUTLINE ->
+                MaskStyle(filled = false, fill = ANKI_OUTLINE_COLOR)
+        }
+
+        MaskPalette.Mono -> when (state) {
+            ShapeState.CONTEXT -> null
+            ShapeState.MASKED -> MaskStyle(filled = true, fill = MONO_MASK_FILL)
+            ShapeState.MASKED_TESTED ->
+                MaskStyle(filled = true, fill = MONO_MASK_FILL, border = MONO_TESTED_BORDER)
+            ShapeState.REVEALED_OUTLINE -> MaskStyle(filled = false, fill = MONO_OUTLINE_COLOR)
+        }
+    }
+
 /**
  * The pure state mapping behind the "Toggle Masks" peek (AnkiDroid parity). When
  * [masksHidden] is true, EVERY resolved [ShapeState] collapses to [ShapeState.CONTEXT] —
@@ -130,8 +208,8 @@ fun effectiveShapeState(state: ShapeState, masksHidden: Boolean): ShapeState =
  * The three states an occlusion base image can be in.
  *
  * This exists to kill a real UX bug: the generic [ImageNodePlaceholder] is a *solid
- * grey filled box*, and a masked occlusion shape ([MASK_FILL]) is *also* a solid grey
- * box. So a mid-load occlusion card rendered through the shared placeholder was visually
+ * grey filled box*, and a masked occlusion shape is *also* a solid filled box. So a
+ * mid-load occlusion card rendered through the shared placeholder was visually
  * indistinguishable from an occlusion whose mask never lifts — it read as broken. The
  * loading and failed states must therefore be *text in a bordered (unfilled) box*, never
  * a solid fill, so they can never be mistaken for a mask.
@@ -486,8 +564,8 @@ private fun polygonPath(points: List<Pair<Float, Float>>): Path = Path().apply {
 
 /**
  * The non-drawn states of an occlusion base image: a *bordered, text-labelled, unfilled*
- * box — deliberately NOT the solid grey [ImageNodePlaceholder]. A solid grey fill is
- * exactly what a [MASK_FILL] mask looks like, so reusing it made a mid-load (or missing)
+ * box — deliberately NOT the solid grey [ImageNodePlaceholder]. A solid filled box is
+ * exactly what a mask looks like, so reusing it made a mid-load (or missing)
  * occlusion card indistinguishable from an occlusion whose mask never lifts. Text plus an
  * outline (no fill) can never be mistaken for a mask.
  *

tool/src/test/kotlin/com/dvdutch/recall/ui/MaskStyleTest.kt

@@ -1,5 +1,6 @@
 package com.dvdutch.recall.ui
 
+import androidx.compose.ui.graphics.Color
 import com.dvdutch.recall.api.ShapeState
 import kotlin.test.Test
 import kotlin.test.assertEquals
@@ -9,50 +10,132 @@ import kotlin.test.assertTrue
 
 /**
  * Unit coverage for [maskStyle], the single pure styling function that maps a resolved
- * [ShapeState] onto its fill/outline/border draw spec. Centralising this here is what
- * lets a future COLOR mode (pink tested / tan inactive, AnkiDroid-style) be added by
- * swapping ONE function — and it makes the load-bearing UX rule ("the tested mask must
- * be unmistakable among many inactive masks") unit-testable without a device.
+ * [ShapeState] onto its fill/outline/border draw spec, across BOTH palettes.
+ *
+ * The DEFAULT palette is [MaskPalette.Anki] — it matches the exact colours AnkiDroid /
+ * Anki desktop draw (inactive tan `#FFEBA2`, tested salmon `#FF8E8E`, revealed red
+ * outline `#FF8E8E`), because our images render in full colour. The [MaskPalette.Mono]
+ * palette is kept as a grayscale-only fallback (mid grey block + two-tone ring) for a
+ * future device-colour toggle. Both must keep the load-bearing UX rule ("the tested mask
+ * must be unmistakable among many inactive masks"), and the Anki fills must stay
+ * distinguishable even if the device grayscales — asserted here via a relative-luminance
+ * gap — so the palette is provably grayscale-safe without a device.
  */
 class MaskStyleTest {
 
+    // --- Default palette (Anki) ----------------------------------------------
+
+    @Test
+    fun `default palette is Anki`() {
+        // maskStyle(state) with no palette arg must resolve identically to the Anki palette.
+        for (state in ShapeState.entries) {
+            assertEquals(
+                maskStyle(state, MaskPalette.Anki),
+                maskStyle(state),
+                "default maskStyle($state) must equal the Anki palette",
+            )
+        }
+    }
+
+    @Test
+    fun `context draws nothing (both palettes)`() {
+        assertNull(maskStyle(ShapeState.CONTEXT, MaskPalette.Anki))
+        assertNull(maskStyle(ShapeState.CONTEXT, MaskPalette.Mono))
+    }
+
+    // --- Anki palette per-state ----------------------------------------------
+
+    @Test
+    fun `anki inactive masked is a solid tan block`() {
+        val s = maskStyle(ShapeState.MASKED, MaskPalette.Anki)
+        assertNotNull(s)
+        assertTrue(s.filled, "inactive mask must be a solid fill")
+        assertEquals(Color(0xFFFFEBA2), s.fill, "Anki inactive fill is #FFEBA2")
+    }
+
+    @Test
+    fun `anki tested masked is a solid salmon block (no two-tone ring)`() {
+        val s = maskStyle(ShapeState.MASKED_TESTED, MaskPalette.Anki)
+        assertNotNull(s)
+        assertTrue(s.filled, "tested mask is still a solid fill (region stays hidden)")
+        assertEquals(Color(0xFFFF8E8E), s.fill, "Anki tested fill is #FF8E8E")
+        // AnkiDroid draws the SAME thin dark border on tested as on inactive — the
+        // distinction is the fill colour, not a heavy ring. So no two-tone ring here.
+        val border = s.border
+        if (border != null) {
+            assertEquals(border.outerColor, border.innerColor, "Anki tested border is single-tone")
+        }
+    }
+
+    @Test
+    fun `anki tested and inactive fills DIFFER (colour carries the distinction)`() {
+        assertTrue(
+            maskStyle(ShapeState.MASKED, MaskPalette.Anki)!!.fill !=
+                maskStyle(ShapeState.MASKED_TESTED, MaskPalette.Anki)!!.fill,
+            "Anki distinguishes tested from inactive by fill colour",
+        )
+    }
+
     @Test
-    fun `context draws nothing`() {
-        assertNull(maskStyle(ShapeState.CONTEXT))
+    fun `anki revealed outline is stroke-only red`() {
+        val s = maskStyle(ShapeState.REVEALED_OUTLINE, MaskPalette.Anki)
+        assertNotNull(s)
+        assertTrue(!s.filled, "revealed answer is an outline, not a fill")
+        assertEquals(Color(0xFFFF8E8E), s.fill, "Anki revealed outline is red #FF8E8E")
     }
 
+    // --- Mono palette per-state (preserved fallback) -------------------------
+
     @Test
-    fun `inactive masked is a plain filled block with no distinguishing border`() {
-        val s = maskStyle(ShapeState.MASKED)
+    fun `mono inactive masked is a plain filled block with no distinguishing border`() {
+        val s = maskStyle(ShapeState.MASKED, MaskPalette.Mono)
         assertNotNull(s)
         assertTrue(s.filled, "inactive mask must be a solid fill")
         assertNull(s.border, "inactive mask has no distinguishing border")
     }
 
     @Test
-    fun `tested masked is a filled block WITH a heavy distinguishing border`() {
-        val s = maskStyle(ShapeState.MASKED_TESTED)
+    fun `mono tested masked is a filled block WITH a heavy two-tone distinguishing border`() {
+        val s = maskStyle(ShapeState.MASKED_TESTED, MaskPalette.Mono)
         assertNotNull(s)
         assertTrue(s.filled, "tested mask is still a solid fill (region stays hidden)")
         val border = s.border
-        assertNotNull(border, "tested mask MUST carry a distinguishing border")
+        assertNotNull(border, "mono tested mask MUST carry a distinguishing border")
         assertTrue(border.outerWidthPx > 0f, "border must be visible")
-        // A two-tone ring (contrasting outer/inner colours) so it pops on both light and
-        // dark image regions in monochrome.
         assertTrue(border.outerColor != border.innerColor, "ring must be two-tone for contrast")
     }
 
     @Test
-    fun `tested and inactive fills are the same (both genuinely hide the region)`() {
-        // Distinction is carried by the border, not by making the tested fill translucent
-        // — the answer must stay covered on the front.
-        assertEquals(maskStyle(ShapeState.MASKED)!!.fill, maskStyle(ShapeState.MASKED_TESTED)!!.fill)
+    fun `mono tested and inactive fills are the same (both genuinely hide the region)`() {
+        assertEquals(
+            maskStyle(ShapeState.MASKED, MaskPalette.Mono)!!.fill,
+            maskStyle(ShapeState.MASKED_TESTED, MaskPalette.Mono)!!.fill,
+        )
     }
 
     @Test
-    fun `revealed outline is stroke-only (not filled)`() {
-        val s = maskStyle(ShapeState.REVEALED_OUTLINE)
+    fun `mono revealed outline is stroke-only (not filled)`() {
+        val s = maskStyle(ShapeState.REVEALED_OUTLINE, MaskPalette.Mono)
         assertNotNull(s)
         assertTrue(!s.filled, "revealed answer is an outline, not a fill")
     }
+
+    // --- Grayscale-safety: luminance separation ------------------------------
+
+    @Test
+    fun `anki tested vs inactive fills have a healthy relative-luminance gap`() {
+        // If the device grayscales, tested vs inactive must still be distinguishable by
+        // brightness alone. Assert a healthy gap so the palette is provably grayscale-safe.
+        val inactive = relativeLuminance(maskStyle(ShapeState.MASKED, MaskPalette.Anki)!!.fill)
+        val tested = relativeLuminance(maskStyle(ShapeState.MASKED_TESTED, MaskPalette.Anki)!!.fill)
+        val gap = kotlin.math.abs(inactive - tested)
+        assertTrue(gap > 0.15, "Anki tested/inactive luminance gap must exceed 0.15, was $gap")
+    }
+
+    @Test
+    fun `relativeLuminance matches the sRGB formula for known colours`() {
+        // Black = 0, white = 1 anchors the WCAG relative-luminance computation.
+        assertEquals(0.0, relativeLuminance(Color(0xFF000000)), 1e-6)
+        assertEquals(1.0, relativeLuminance(Color(0xFFFFFFFF)), 1e-6)
+    }
 }