scrying-pool/_bmad-output/implementation-artifacts/review-4-2/02-edge-case-hunter-prompt.md

# Edge Case Hunter — Story 4.2 Code Review

You are an **Edge Case Hunter**. You receive the diff below AND read access to the project. Walk every branching path and boundary condition. Report ONLY unhandled edge cases.

## Instructions

- Review the diff against the existing project codebase.
- Walk all: conditional branches, type transitions, null/undefined checks, boundary values, error paths, async flows, DOM states, mock/fake surfaces, API integration points.
- Report ONLY issues where an edge case is unhandled or handled incorrectly — not general critique.
- Each finding: **one-line title**, file + line, the edge condition, and why it matters.
- If every edge case is properly handled, say "No unhandled edge cases found."

## Project Access

You have read access to the full project at: `/home/morr/work/foundryvtt/video-view-manager/`

Key files to cross-reference:
- `src/contracts/privacy-settings.js` — existing contract (read the full file for context around the diff)
- `src/core/PlayerPrivacyManager.js` — existing manager (read the full file for context around the diff)
- `src/core/PortraitFallbackHandler.js` — new file (shown in full below)
- `src/foundry/FoundryAdapter.js` — adapter interface
- `src/ui/RoleRenderer.js` — eventual integration target
- `src/ui/player/PlayerPrivacyPanel.js` — eventual UI target
- `tests/helpers/foundryAdapterMock.js` — existing mock patterns
- `tests/helpers/playerPrivacyManagerMock.js` — new mock helper

## Diff

=== MODIFIED FILES ===

```diff
diff --git a/src/contracts/privacy-settings.js b/src/contracts/privacy-settings.js
index b838445..f618241 100644
--- a/src/contracts/privacy-settings.js
+++ b/src/contracts/privacy-settings.js
@@ -5,15 +5,34 @@
  * their on-screen presence. Settings are stored as user flags on the user document.
  *
  * Storage key: game.user.setFlag('video-view-manager', key, value)
- * Shape: { reactionCamEnabled: boolean, hpReactiveCamStylingEnabled: boolean }
+ * Shape: { reactionCamEnabled: boolean, hpReactiveCamStylingEnabled: boolean, customPortraitFallback: string | null }
  *
  * @module contracts/privacy-settings
  */
 
+export const MAX_PORTRAIT_SIZE = 5 * 1024 * 1024;
+
+export const VALID_PORTRAIT_FORMATS = Object.freeze([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+]);
+
 /**
  * @typedef {Object} PrivacySettings
  * @property {boolean} reactionCamEnabled
  * @property {boolean} hpReactiveCamStylingEnabled
+ * @property {string|null} customPortraitFallback
  */
 
 export const PRIVACY_SETTINGS_VERSION = 1;
@@ -25,6 +44,7 @@ export const PRIVACY_SETTINGS_VERSION = 1;
 export const PRIVACY_SETTINGS_DEFAULT = {
   reactionCamEnabled: false,
   hpReactiveCamStylingEnabled: false,
+  customPortraitFallback: null,
 };
 
@@ -34,6 +54,7 @@ export const PRIVACY_SETTING_KEYS = Object.freeze([
   "reactionCamEnabled",
   "hpReactiveCamStylingEnabled",
+  "customPortraitFallback",
 ]);
 
@@ -45,6 +66,49 @@ export const FEATURE_NAME_MAP = Object.freeze({
   hpReactiveCamStyling: "hpReactiveCamStylingEnabled",
 });
 
+export function validatePortraitDataURL(dataURL) {
+  if (dataURL === null || dataURL === undefined) {
+    return dataURL;
+  }
+  if (typeof dataURL !== "string") {
+    throw new TypeError(`Invalid DataURL: expected string, got ${typeof dataURL}`);
+  }
+  if (dataURL === "") {
+    return dataURL;
+  }
+
+  if (!dataURL.startsWith("data:")) {
+    throw new TypeError("Invalid DataURL format: must start with 'data:'");
+  }
+
+  const mimeMatch = dataURL.match(/^data:(image\/[a-zA-Z0-9+\-.]+|video\/[a-zA-Z0-9+\-.]+)/);
+  if (!mimeMatch) {
+    throw new TypeError("Invalid DataURL format: missing or invalid MIME type");
+  }
+
+  const mimeType = mimeMatch[1].toLowerCase();
+
+  if (!VALID_PORTRAIT_FORMATS.includes(mimeType)) {
+    throw new TypeError(
+      `Unsupported portrait format: ${mimeType}. Supported: ${VALID_PORTRAIT_FORMATS.join(", ")}`
+    );
+  }
+
+  return dataURL;
+}
+
 /**
  * Creates a new PrivacySettings object with defaults.
  */
@@ -63,6 +127,7 @@ export function createPrivacySettings(overrides = {}) {
 
 /**
  * Validates a PrivacySettings DTO. Throws TypeError on any violation.
+ * Backward compatible: accepts settings without customPortraitFallback key.
  */
@@ -75,23 +140,50 @@ export function isValidPrivacySettings(data) {
     throw new TypeError("PrivacySettings: must be an object");
   }
   const obj = /** @type {Record<string, unknown>} */ (data);
-  const { reactionCamEnabled, hpReactiveCamStylingEnabled, ...rest } = obj;
-  if (Object.keys(rest).length > 0) {
+
+  const knownKeys = new Set(PRIVACY_SETTING_KEYS);
+  const unknownKeys = Object.keys(obj).filter((k) => !knownKeys.has(k));
+  if (unknownKeys.length > 0) {
     throw new TypeError(
-      `PrivacySettings: unknown keys: ${Object.keys(rest).join(", ")}`
+      `PrivacySettings: unknown keys: ${unknownKeys.join(", ")}`
     );
   }
-  if (typeof reactionCamEnabled !== "boolean") {
-    throw new TypeError(
-      `PrivacySettings: reactionCamEnabled must be a boolean, got ${typeof reactionCamEnabled}`
-    );
+
+  if ("reactionCamEnabled" in obj) {
+    if (typeof obj.reactionCamEnabled !== "boolean") {
+      throw new TypeError(
+        `PrivacySettings: reactionCamEnabled must be a boolean, got ${typeof obj.reactionCamEnabled}`
+      );
+    }
   }
-  if (typeof hpReactiveCamStylingEnabled !== "boolean") {
-    throw new TypeError(
-      `PrivacySettings: hpReactiveCamStylingEnabled must be a boolean, got ${typeof hpReactiveCamStylingEnabled}`
-    );
+  if ("hpReactiveCamStylingEnabled" in obj) {
+    if (typeof obj.hpReactiveCamStylingEnabled !== "boolean") {
+      throw new TypeError(
+        `PrivacySettings: hpReactiveCamStylingEnabled must be a boolean, got ${typeof obj.hpReactiveCamStylingEnabled}`
+      );
+    }
   }
-  return /** @type {PrivacySettings} */ (data);
+  if ("customPortraitFallback" in obj) {
+    if (obj.customPortraitFallback !== null && typeof obj.customPortraitFallback !== "string") {
+      throw new TypeError(
+        `PrivacySettings: customPortraitFallback must be a string or null, got ${typeof obj.customPortraitFallback}`
+      );
+    }
+    if (typeof obj.customPortraitFallback === "string" && obj.customPortraitFallback !== "") {
+      try {
+        validatePortraitDataURL(obj.customPortraitFallback);
+      } catch (e) {
+        throw new TypeError(
+          `PrivacySettings: customPortraitFallback ${e.message}`
+        );
+      }
+    }
+  }
+
+  return /** @type {PrivacySettings} */ (obj);
 }
 
diff --git a/src/core/PlayerPrivacyManager.js b/src/core/PlayerPrivacyManager.js
index 117afa2..9347edd 100644
--- a/src/core/PlayerPrivacyManager.js
+++ b/src/core/PlayerPrivacyManager.js
@@ -15,9 +15,11 @@ import {
   PRIVACY_SETTINGS_DEFAULT,
   PRIVACY_SETTING_KEYS,
   FEATURE_NAME_MAP,
+  MAX_PORTRAIT_SIZE,
   validateSettingKey,
   validateSettingValue,
   validateFeatureName,
+  validatePortraitDataURL,
 } from "../contracts/privacy-settings.js";
 
@@ -118,12 +120,19 @@ export class PlayerPrivacyManager {
    * @param {string} key
    * @param {boolean} value
    */
   async setSetting(userId, key, value) {
+    if (key === "customPortraitFallback") {
+      throw new TypeError(
+        "PlayerPrivacyManager: customPortraitFallback must use setPortraitFallback() method"
+      );
+    }
+
     // Validate key
     validateSettingKey(key);
 
@@ -245,6 +254,149 @@ export class PlayerPrivacyManager {
     }
   }
 
+  async setPortraitFallback(userId, dataURL) {
+    validatePortraitDataURL(dataURL);
+
+    const user = this._adapter.users.get(userId);
+    if (!user) {
+      throw new TypeError(`PlayerPrivacyManager: User '${userId}' not found`);
+    }
+
+    if (typeof user.setFlag !== "function") {
+      throw new TypeError(`PlayerPrivacyManager: User '${userId}' does not support setFlag`);
+    }
+
+    const previousValue = this.getPortraitFallback(userId);
+
+    await user.setFlag("video-view-manager", "customPortraitFallback", dataURL);
+
+    this._notifyPortraitChange(userId, dataURL, previousValue);
+  }
+
+  getPortraitFallback(userId) {
+    const user = this._adapter.users.get(userId);
+
+    if (!user || typeof user.getFlag !== "function") {
+      return null;
+    }
+
+    const dataURL = user.getFlag("video-view-manager", "customPortraitFallback");
+
+    if (dataURL !== null && dataURL !== undefined) {
+      try {
+        if (typeof dataURL === "string" && dataURL !== "") {
+          validatePortraitDataURL(dataURL);
+        }
+        return dataURL ?? null;
+      } catch (e) {
+        console.warn(`[ScryingPool] PlayerPrivacyManager: Invalid stored portrait DataURL for user '${userId}': ${e.message}`);
+        return null;
+      }
+    }
+
+    return null;
+  }
+
+  getPortraitFallbackDataURL(userId) {
+    return this.getPortraitFallback(userId);
+  }
+
+  async removePortraitFallback(userId) {
+    const user = this._adapter.users.get(userId);
+    if (!user) {
+      throw new TypeError(`PlayerPrivacyManager: User '${userId}' not found`);
+    }
+
+    if (typeof user.unsetFlag !== "function") {
+      throw new TypeError(`PlayerPrivacyManager: User '${userId}' does not support unsetFlag`);
+    }
+
+    const previousValue = this.getPortraitFallback(userId);
+
+    await user.unsetFlag("video-view-manager", "customPortraitFallback");
+
+    this._notifyPortraitChange(userId, null, previousValue);
+  }
+
+  _notifyPortraitChange(userId, newValue, previousValue) {
+    for (const callback of this._subscribers) {
+      try {
+        callback(userId, "customPortraitFallback", newValue, previousValue);
+      } catch (err) {
+        console.error(`[ScryingPool] PlayerPrivacyManager portrait subscriber error:`, err);
+      }
+    }
+  }
+
   /**
    * Cleans up internal state.
   teardown() { ... }
```

=== NEW FILES ===

**src/core/PortraitFallbackHandler.js** (249 lines — full file available at that path)

**tests/helpers/playerPrivacyManagerMock.js** (50 lines — full file available at that path)