Add overlay profile export/import.

- Enables sharing and portability of user settings

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,9 +2,8 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement overlay user preferences and persistence:
-- Store preferences (visibility, layout, keybind profile)
-- Restore preferences on runtime load
-- Ensure compatibility with adaptive UI and contextual input
-- Use lightweight storage (local or existing state system)
+Implement profile export/import:
+- Export overlay preferences to JSON
+- Import with validation
+- Ensure compatibility with persistence system
 - Update roadmap status only

docs/dev/COMMIT_COMMENT.txt

@@ -1,5 +1,3 @@
-Add user preferences and persistence for overlays.
+Add overlay profile export/import.
 
-PR Details:
-- Enables saving and restoring overlay configuration
-- Supports personalization across sessions
+- Enables sharing and portability of user settings

docs/dev/reports/validation_checklist.txt

@@ -1,5 +1,4 @@
-[ ] Preferences save correctly
-[ ] Preferences restore correctly
-[ ] No regression in behavior
-[ ] Compatible with adaptive UI
+[ ] Export works
+[ ] Import works
+[ ] Validation prevents bad data
 [ ] Roadmap updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -639,6 +639,7 @@
 - [x] Level 22 contextual input mapping added (active overlay/layer stack-aware resolution across keybind and gesture actions)
 - [x] Level 22 adaptive overlay UI rules added (visibility/size/emphasis responsive to gameplay state, overlay context, and telemetry)
 - [x] Level 22 overlay preferences persistence added (visibility, layout overrides, and keybind profile restored on runtime load)
+- [x] Level 22 overlay profile export/import added (validated JSON portability with persistence-system compatibility)
 
 ### Sample Phase Tracks
 - [x] 3D phase normalized

docs/pr/BUILD_PR.md

@@ -1,21 +1,17 @@
-# BUILD_PR_LEVEL_22_5_OVERLAY_USER_PREFERENCES_AND_PERSISTENCE
+# BUILD_PR_LEVEL_22_6_OVERLAY_PROFILE_EXPORT_IMPORT
 
 ## Purpose
-Persist user preferences for overlay behavior and customization.
-
-## Roadmap Improvement
-Completes Level 22 by adding persistence and personalization.
+Enable export and import of overlay user profiles.
 
 ## Scope
-- Store user preferences (visibility, layout, keybind profile)
-- Restore preferences on load
-- Ensure compatibility with adaptive UI and contextual input systems
+- Export preferences to JSON
+- Import preferences from JSON
+- Validate schema and compatibility
 
 ## Test Steps
-1. Modify overlay preferences
-2. Reload runtime
-3. Verify preferences persist
+1. Export profile
+2. Import profile
+3. Verify settings applied
 
 ## Expected
-- Preferences saved and restored
-- No regression in overlay behavior
+- Profiles portable across sessions/devices

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -249,6 +249,149 @@ function writeOverlayRuntimePreferencePayloadToStorage(preferenceStorageKey, pay
   return true;
 }
 
+function validateOverlayRuntimePreferencePayload(payload) {
+  const errors = [];
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return {
+      valid: false,
+      errors: Object.freeze(['Overlay runtime profile payload must be an object.']),
+      value: null,
+    };
+  }
+
+  const hasVisibility = Object.prototype.hasOwnProperty.call(payload, 'visibility');
+  const hasLayout = Object.prototype.hasOwnProperty.call(payload, 'layout');
+  const hasKeybindProfile = Object.prototype.hasOwnProperty.call(payload, 'keybindProfile');
+  if (!hasVisibility && !hasLayout && !hasKeybindProfile) {
+    errors.push('Overlay runtime profile payload must include at least one of visibility, layout, or keybindProfile.');
+  }
+
+  const versionRaw = payload.version;
+  if (versionRaw !== undefined) {
+    const version = Number(versionRaw);
+    if (!Number.isInteger(version) || version <= 0) {
+      errors.push('Overlay runtime profile version must be a positive integer when provided.');
+    }
+  }
+
+  let visibility = null;
+  if (hasVisibility) {
+    if (payload.visibility === true || payload.visibility === false) {
+      visibility = payload.visibility;
+    } else {
+      errors.push('Overlay runtime profile visibility must be a boolean.');
+    }
+  }
+
+  let layout = null;
+  if (hasLayout) {
+    if (!payload.layout || typeof payload.layout !== 'object' || Array.isArray(payload.layout)) {
+      errors.push('Overlay runtime profile layout must be an object.');
+    } else {
+      layout = {};
+      const entries = Object.entries(payload.layout);
+      for (let i = 0; i < entries.length; i += 1) {
+        const [layoutKey, layoutRect] = entries[i];
+        const normalizedLayoutKey = String(layoutKey || '').trim();
+        const normalizedRect = normalizeLayoutOverrideRect(layoutRect);
+        if (!normalizedLayoutKey || !normalizedRect) {
+          errors.push(`Overlay runtime profile layout entry "${normalizedLayoutKey || '<empty>'}" is invalid.`);
+          continue;
+        }
+        layout[normalizedLayoutKey] = normalizedRect;
+      }
+    }
+  }
+
+  let keybindProfile = null;
+  if (hasKeybindProfile) {
+    if (!payload.keybindProfile || typeof payload.keybindProfile !== 'object' || Array.isArray(payload.keybindProfile)) {
+      errors.push('Overlay runtime profile keybindProfile must be an object.');
+    } else {
+      keybindProfile = {};
+      if (Object.prototype.hasOwnProperty.call(payload.keybindProfile, 'id')) {
+        keybindProfile.id = String(payload.keybindProfile.id || '').trim();
+      }
+      if (Object.prototype.hasOwnProperty.call(payload.keybindProfile, 'cycleKey')) {
+        const cycleKey = String(payload.keybindProfile.cycleKey || '').trim();
+        if (!cycleKey) {
+          errors.push('Overlay runtime profile keybindProfile.cycleKey must be a non-empty string when provided.');
+        } else {
+          keybindProfile.cycleKey = cycleKey;
+        }
+      }
+      if (Object.prototype.hasOwnProperty.call(payload.keybindProfile, 'contextInputMap')) {
+        const contextInputMap = payload.keybindProfile.contextInputMap;
+        if (contextInputMap === null) {
+          keybindProfile.contextInputMap = null;
+          keybindProfile.contextInputMapSpecified = true;
+        } else if (contextInputMap && typeof contextInputMap === 'object' && !Array.isArray(contextInputMap)) {
+          const clonedContextInputMap = cloneJsonCompatibleValue(contextInputMap);
+          if (clonedContextInputMap && typeof clonedContextInputMap === 'object') {
+            keybindProfile.contextInputMap = clonedContextInputMap;
+            keybindProfile.contextInputMapSpecified = true;
+          } else {
+            errors.push('Overlay runtime profile keybindProfile.contextInputMap must be JSON-compatible.');
+          }
+        } else {
+          errors.push('Overlay runtime profile keybindProfile.contextInputMap must be an object or null.');
+        }
+      }
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      valid: false,
+      errors: Object.freeze(errors),
+      value: null,
+    };
+  }
+
+  return {
+    valid: true,
+    errors: Object.freeze([]),
+    value: Object.freeze({
+      version: Number.isInteger(Number(payload.version)) && Number(payload.version) > 0
+        ? Number(payload.version)
+        : 1,
+      hasVisibility,
+      hasLayout,
+      hasKeybindProfile,
+      visibility,
+      layout: layout || {},
+      keybindProfile: keybindProfile || {},
+    }),
+  };
+}
+
+function applyOverlayRuntimePreferencePayload(runtime, validatedPayload) {
+  if (!runtime || !validatedPayload || typeof validatedPayload !== 'object') {
+    return false;
+  }
+  if (validatedPayload.hasVisibility && (validatedPayload.visibility === true || validatedPayload.visibility === false)) {
+    runtime.interactionVisible = validatedPayload.visibility;
+  }
+  if (validatedPayload.hasLayout) {
+    applyOverlayRuntimeLayoutPreferences(runtime, validatedPayload.layout);
+  }
+  if (validatedPayload.hasKeybindProfile) {
+    const keybindProfile = validatedPayload.keybindProfile || {};
+    if (Object.prototype.hasOwnProperty.call(keybindProfile, 'id')) {
+      runtime.interactionKeybindProfileId = String(keybindProfile.id || '').trim();
+    }
+    if (Object.prototype.hasOwnProperty.call(keybindProfile, 'cycleKey')) {
+      runtime.interactionCycleKey = String(keybindProfile.cycleKey || '').trim() || LEVEL17_OVERLAY_CYCLE_KEY;
+    }
+    if (keybindProfile.contextInputMapSpecified === true) {
+      runtime.interactionContextInputMap = keybindProfile.contextInputMap === null
+        ? null
+        : (cloneJsonCompatibleValue(keybindProfile.contextInputMap) ?? null);
+    }
+  }
+  return true;
+}
+
 function buildOverlayRuntimeLayoutPreferenceSnapshot(runtime) {
   const snapshot = {};
   const overrides = runtime?.interactionLayoutOverrides;
@@ -1439,6 +1582,17 @@ export function getOverlayGameplayRuntimePreferencesSnapshot(runtime) {
   });
 }
 
+export function exportOverlayGameplayRuntimeProfile(runtime, { pretty = false } = {}) {
+  const snapshot = getOverlayGameplayRuntimePreferencesSnapshot(runtime);
+  const payload = {
+    version: 1,
+    visibility: snapshot.visibility,
+    layout: snapshot.layout,
+    keybindProfile: snapshot.keybindProfile,
+  };
+  return JSON.stringify(payload, null, pretty ? 2 : 0);
+}
+
 export function saveOverlayGameplayRuntimePreferences(runtime, options = {}) {
   if (!runtime) {
     return false;
@@ -1476,28 +1630,51 @@ export function loadOverlayGameplayRuntimePreferences(runtime, options = {}) {
   if (!payload || typeof payload !== 'object') {
     return false;
   }
+  const validated = validateOverlayRuntimePreferencePayload(payload);
+  if (!validated.valid || !validated.value) {
+    return false;
+  }
+  return applyOverlayRuntimePreferencePayload(runtime, validated.value);
+}
 
-  if (payload.visibility === true || payload.visibility === false) {
-    runtime.interactionVisible = payload.visibility;
+export function importOverlayGameplayRuntimeProfile(runtime, profileInput, options = {}) {
+  if (!runtime) {
+    return Object.freeze({
+      success: false,
+      errors: Object.freeze(['Overlay runtime is required for profile import.']),
+    });
   }
-  applyOverlayRuntimeLayoutPreferences(runtime, payload.layout);
-  const keybindProfile = payload.keybindProfile && typeof payload.keybindProfile === 'object'
-    ? payload.keybindProfile
-    : null;
-  if (keybindProfile) {
-    runtime.interactionKeybindProfileId = String(keybindProfile.id || '').trim();
-    const cycleKey = String(keybindProfile.cycleKey || '').trim();
-    if (cycleKey) {
-      runtime.interactionCycleKey = cycleKey;
-    }
-    if (keybindProfile.contextInputMap && typeof keybindProfile.contextInputMap === 'object') {
-      const clonedContextInputMap = cloneJsonCompatibleValue(keybindProfile.contextInputMap);
-      if (clonedContextInputMap && typeof clonedContextInputMap === 'object') {
-        runtime.interactionContextInputMap = clonedContextInputMap;
-      }
+
+  let parsedInput = null;
+  if (typeof profileInput === 'string') {
+    try {
+      parsedInput = JSON.parse(profileInput);
+    } catch {
+      return Object.freeze({
+        success: false,
+        errors: Object.freeze(['Overlay runtime profile JSON is invalid.']),
+      });
     }
+  } else {
+    parsedInput = cloneJsonCompatibleValue(profileInput);
   }
-  return true;
+
+  const validated = validateOverlayRuntimePreferencePayload(parsedInput);
+  if (!validated.valid || !validated.value) {
+    return Object.freeze({
+      success: false,
+      errors: validated.errors,
+    });
+  }
+
+  applyOverlayRuntimePreferencePayload(runtime, validated.value);
+  if (options?.persist !== false) {
+    saveOverlayGameplayRuntimePreferences(runtime, { silent: true });
+  }
+  return Object.freeze({
+    success: true,
+    errors: Object.freeze([]),
+  });
 }
 
 export function setOverlayGameplayRuntimeContextInputMap(runtime, contextInputMap) {

tests/runtime/Phase19OverlayExpansionFramework.test.mjs

@@ -13,9 +13,11 @@ import {
   LEVEL19_OVERLAY_RUNTIME_TOGGLE_MODIFIERS,
 } from '../../samples/phase-17/shared/overlayCycleInput.js';
 import {
+  exportOverlayGameplayRuntimeProfile,
   enqueueOverlayGameplayRuntimeSyncEvent,
   getOverlayGameplayRuntimeCompositionSnapshot,
   getOverlayGameplayRuntimeInteractionSnapshot,
+  importOverlayGameplayRuntimeProfile,
   saveOverlayGameplayRuntimePreferences,
   renderOverlayGameplayRuntime,
   resolveOverlayGameplayRuntimeInputAction,
@@ -952,6 +954,73 @@ function assertOverlayPreferencesPersistenceCompatibility() {
   assert.equal(runtimeAFrame.adaptiveEmphasis > 1, true, 'Adaptive UI emphasis should remain active after preference restoration.');
 }
 
+function assertOverlayProfileExportImportValidation() {
+  const framework = createPhase19OverlayExpansionFramework();
+  framework.registerExtension(definePhase19OverlayExtension({
+    id: 'phase19-overlay-profile-export-import',
+    overlays: [
+      { id: 'runtime-a', label: 'Runtime A' },
+      { id: 'runtime-b', label: 'Runtime B' },
+    ],
+    initialOverlayId: 'runtime-a',
+    persistenceKey: 'phase19:overlay-profile-export-import',
+    runtimeExtensions: [
+      { overlayId: 'runtime-a', compose: true, layerOrder: 10, visualPriority: 10, panelWidth: 220, panelHeight: 96, onRender() {} },
+      { overlayId: 'runtime-b', compose: true, layerOrder: 20, visualPriority: 20, panelWidth: 220, panelHeight: 96, onRender() {} },
+    ],
+  }));
+
+  const sourceRuntime = framework.createRuntimeForExtension('phase19-overlay-profile-export-import');
+  setOverlayGameplayRuntimeVisible(sourceRuntime, false);
+  setOverlayGameplayRuntimeKeybindProfile(sourceRuntime, {
+    id: 'portable-profile',
+    cycleKey: 'KeyJ',
+    contextInputMap: {
+      byOverlayId: {
+        'runtime-b': {
+          'cycle-next': 'toggle-visibility',
+        },
+      },
+    },
+  });
+  sourceRuntime.interactionLayoutOverrides['id:runtime-b'] = {
+    x: 70,
+    y: 102,
+    width: 260,
+    height: 118,
+  };
+
+  const exportedJson = exportOverlayGameplayRuntimeProfile(sourceRuntime);
+  const exportedPayload = JSON.parse(exportedJson);
+  assert.equal(exportedPayload.version, 1, 'Exported overlay profile should include schema version.');
+  assert.equal(exportedPayload.visibility, false, 'Exported overlay profile should include visibility preference.');
+  assert.equal(exportedPayload.keybindProfile.cycleKey, 'KeyJ', 'Exported overlay profile should include keybind cycle key.');
+  assert.equal(exportedPayload.layout['id:runtime-b'].width, 260, 'Exported overlay profile should include layout override width.');
+
+  const importedRuntime = framework.createRuntimeForExtension('phase19-overlay-profile-export-import');
+  const importResult = importOverlayGameplayRuntimeProfile(importedRuntime, exportedJson);
+  assert.equal(importResult.success, true, 'Overlay profile import should succeed for valid exported JSON.');
+  assert.equal(importResult.errors.length, 0, 'Overlay profile import should not report errors for valid exported JSON.');
+  assert.equal(importedRuntime.interactionVisible, false, 'Imported overlay profile should restore visibility preference.');
+  assert.equal(importedRuntime.interactionCycleKey, 'KeyJ', 'Imported overlay profile should restore cycle key preference.');
+  assert.equal(importedRuntime.interactionKeybindProfileId, 'portable-profile', 'Imported overlay profile should restore keybind profile id.');
+  assert.equal(importedRuntime.interactionLayoutOverrides['id:runtime-b'].x, 70, 'Imported overlay profile should restore layout override X position.');
+  assert.equal(importedRuntime.interactionLayoutOverrides['id:runtime-b'].height, 118, 'Imported overlay profile should restore layout override height.');
+
+  importedRuntime.interactionIndex = 1;
+  const contextualAction = resolveOverlayGameplayRuntimeInputAction(importedRuntime, 'cycle-next');
+  assert.equal(contextualAction.action, 'toggle-visibility', 'Imported profile context mapping should remain compatible with contextual input resolver.');
+
+  const invalidImportResult = importOverlayGameplayRuntimeProfile(importedRuntime, '{"version":1,"visibility":"yes"}');
+  assert.equal(invalidImportResult.success, false, 'Overlay profile import should fail validation for invalid payload types.');
+  assert.equal(invalidImportResult.errors.length > 0, true, 'Overlay profile import should report validation errors for invalid payloads.');
+
+  const reloadedRuntime = framework.createRuntimeForExtension('phase19-overlay-profile-export-import');
+  assert.equal(reloadedRuntime.interactionVisible, false, 'Imported overlay profile should persist and restore visibility on runtime load.');
+  assert.equal(reloadedRuntime.interactionCycleKey, 'KeyJ', 'Imported overlay profile should persist and restore cycle key on runtime load.');
+  assert.equal(reloadedRuntime.interactionLayoutOverrides['id:runtime-b'].y, 102, 'Imported overlay profile should persist and restore layout override Y position.');
+}
+
 export function run() {
   assertExpansionRegistrationAndCompatibility();
   assertExtensionLifecycleMutations();
@@ -964,4 +1033,5 @@ export function run() {
   assertContextualInputMappingUsesOverlayContextAndStack();
   assertAdaptiveOverlayUiRulesReactToGameplayTelemetryAndContext();
   assertOverlayPreferencesPersistenceCompatibility();
+  assertOverlayProfileExportImportValidation();
 }