Add overlay user sharing system.

- Enables sharing of overlay profiles and presets
- Supports cross-environment portability

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,9 +2,8 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement overlay preset library:
-- Define preset schema
-- Provide default presets
-- Allow applying presets to profiles
-- Ensure compatibility with export/import and persistence
+Implement overlay user sharing system:
+- Create shareable profile packages
+- Import with validation and compatibility checks
+- Integrate with preset and persistence systems
 - Update roadmap status only

docs/dev/COMMIT_COMMENT.txt

@@ -1,4 +1,4 @@
-Add overlay preset library.
+Add overlay user sharing system.
 
-- Provides predefined configurations
-- Enables quick switching of overlay setups
+- Enables sharing of overlay profiles and presets
+- Supports cross-environment portability

docs/dev/reports/validation_checklist.txt

@@ -1,4 +1,4 @@
-[ ] Presets load correctly
-[ ] Presets apply without conflicts
-[ ] Compatible with persistence
+[ ] Share package export works
+[ ] Import works across environments
+[ ] Validation prevents incompatible data
 [ ] Roadmap updated

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -641,6 +641,7 @@
 - [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)
 - [x] Level 22 overlay preset library added (schema, defaults, and preset-to-profile apply with export/import+persistence compatibility)
+- [x] Level 22 overlay user sharing system added (shareable profile packages with validated import compatibility across preset and persistence systems)
 
 ### Sample Phase Tracks
 - [x] 3D phase normalized

docs/pr/BUILD_PR.md

@@ -1,18 +1,18 @@
-# BUILD_PR_LEVEL_22_7_OVERLAY_PRESET_LIBRARY
+# BUILD_PR_LEVEL_22_8_OVERLAY_USER_SHARING_SYSTEM
 
 ## Purpose
-Provide a library of predefined overlay configurations (presets).
+Enable sharing of overlay profiles and presets between users.
 
 ## Scope
-- Define preset schema
-- Include default presets (minimal, debug, full telemetry)
-- Allow loading presets into active profile
+- Generate shareable profile packages (JSON)
+- Import shared profiles safely
+- Provide version compatibility checks
 
 ## Test Steps
-1. Load preset
-2. Verify overlay changes
-3. Ensure compatibility with persistence
+1. Export share package
+2. Import into another environment
+3. Validate correct behavior
 
 ## Expected
-- Presets apply correctly
-- No conflicts with user settings
+- Profiles transferable between users
+- Safe import with validation

samples/phase-17/shared/overlayGameplayRuntime.js

@@ -11,6 +11,9 @@ import {
 } from '/samples/phase-17/shared/overlayCycleInput.js';
 
 const overlayRuntimePreferenceMemoryStore = new Map();
+const OVERLAY_RUNTIME_SHARE_PACKAGE_FORMAT = 'overlay-runtime-share-package';
+const OVERLAY_RUNTIME_SHARE_PACKAGE_VERSION = 1;
+const OVERLAY_RUNTIME_PROFILE_SCHEMA_VERSION = 1;
 const OVERLAY_RUNTIME_DEFAULT_PRESET_DEFINITIONS = Object.freeze([
   Object.freeze({
     id: 'minimal',
@@ -539,6 +542,96 @@ function resolveOverlayRuntimePresetFromLibrary(library = [], presetOrId = '') {
   return normalizeOverlayRuntimePresetEntry(presetOrId);
 }
 
+function validateOverlayRuntimeSharePackagePayload(payload, runtime = null) {
+  const errors = [];
+  if (!payload || typeof payload !== 'object' || Array.isArray(payload)) {
+    return {
+      valid: false,
+      errors: Object.freeze(['Overlay runtime share package must be an object.']),
+      value: null,
+    };
+  }
+
+  const format = String(payload.format || '').trim();
+  if (format !== OVERLAY_RUNTIME_SHARE_PACKAGE_FORMAT) {
+    errors.push(`Overlay runtime share package format must be "${OVERLAY_RUNTIME_SHARE_PACKAGE_FORMAT}".`);
+  }
+
+  const packageVersion = Number(payload.packageVersion);
+  if (!Number.isInteger(packageVersion) || packageVersion <= 0) {
+    errors.push('Overlay runtime share package version must be a positive integer.');
+  } else if (packageVersion > OVERLAY_RUNTIME_SHARE_PACKAGE_VERSION) {
+    errors.push(`Overlay runtime share package version ${packageVersion} is not supported by this runtime.`);
+  }
+
+  if (payload.compatibility !== undefined) {
+    if (!payload.compatibility || typeof payload.compatibility !== 'object' || Array.isArray(payload.compatibility)) {
+      errors.push('Overlay runtime share package compatibility must be an object when provided.');
+    } else if (payload.compatibility.profileSchemaVersion !== undefined) {
+      const profileSchemaVersion = Number(payload.compatibility.profileSchemaVersion);
+      if (!Number.isInteger(profileSchemaVersion) || profileSchemaVersion <= 0) {
+        errors.push('Overlay runtime share package compatibility.profileSchemaVersion must be a positive integer when provided.');
+      } else if (profileSchemaVersion > OVERLAY_RUNTIME_PROFILE_SCHEMA_VERSION) {
+        errors.push(
+          `Overlay runtime share package profile schema version ${profileSchemaVersion} is not supported by this runtime.`
+        );
+      }
+    }
+  }
+
+  const validatedProfile = validateOverlayRuntimePreferencePayload(payload.profile);
+  if (!validatedProfile.valid || !validatedProfile.value) {
+    for (let i = 0; i < validatedProfile.errors.length; i += 1) {
+      errors.push(`Share package profile: ${validatedProfile.errors[i]}`);
+    }
+  }
+
+  let preset = null;
+  if (Object.prototype.hasOwnProperty.call(payload, 'preset')) {
+    const normalizedPreset = normalizeOverlayRuntimePresetEntry(payload.preset, 0);
+    if (!normalizedPreset) {
+      errors.push('Overlay runtime share package preset is invalid.');
+    } else {
+      preset = normalizedPreset;
+    }
+  }
+
+  const rawPresetId = String(payload.presetId || '').trim();
+  const presetId = rawPresetId || (preset ? preset.id : '');
+  if (rawPresetId && preset && preset.id !== rawPresetId) {
+    errors.push('Overlay runtime share package presetId does not match included preset id.');
+  }
+  if (presetId && !preset) {
+    const availablePreset = resolveOverlayRuntimePresetFromLibrary(
+      getOverlayGameplayRuntimePresetLibrary(runtime, { includeDefaults: true }),
+      presetId
+    );
+    if (!availablePreset) {
+      errors.push(`Overlay runtime share package requires preset "${presetId}" which is not available in this runtime.`);
+    }
+  }
+
+  if (errors.length > 0) {
+    return {
+      valid: false,
+      errors: Object.freeze(errors),
+      value: null,
+    };
+  }
+
+  return {
+    valid: true,
+    errors: Object.freeze([]),
+    value: Object.freeze({
+      format,
+      packageVersion,
+      profile: validatedProfile.value,
+      presetId,
+      preset,
+    }),
+  };
+}
+
 function buildOverlayRuntimeLayoutPreferenceSnapshot(runtime) {
   const snapshot = {};
   const overrides = runtime?.interactionLayoutOverrides;
@@ -1802,14 +1895,53 @@ export function getOverlayGameplayRuntimePreferencesSnapshot(runtime) {
 export function exportOverlayGameplayRuntimeProfile(runtime, { pretty = false } = {}) {
   const snapshot = getOverlayGameplayRuntimePreferencesSnapshot(runtime);
   const payload = {
-    version: 1,
+    version: OVERLAY_RUNTIME_PROFILE_SCHEMA_VERSION,
     visibility: snapshot.visibility,
     layout: snapshot.layout,
     keybindProfile: snapshot.keybindProfile,
   };
   return JSON.stringify(payload, null, pretty ? 2 : 0);
 }
 
+export function exportOverlayGameplayRuntimeSharePackage(runtime, options = {}) {
+  const snapshot = getOverlayGameplayRuntimePreferencesSnapshot(runtime);
+  const profile = {
+    version: OVERLAY_RUNTIME_PROFILE_SCHEMA_VERSION,
+    visibility: snapshot.visibility,
+    layout: snapshot.layout,
+    keybindProfile: snapshot.keybindProfile,
+  };
+
+  const sharePackage = {
+    format: OVERLAY_RUNTIME_SHARE_PACKAGE_FORMAT,
+    packageVersion: OVERLAY_RUNTIME_SHARE_PACKAGE_VERSION,
+    compatibility: {
+      profileSchemaVersion: OVERLAY_RUNTIME_PROFILE_SCHEMA_VERSION,
+    },
+    source: String(options?.source || 'overlay-gameplay-runtime').trim() || 'overlay-gameplay-runtime',
+    exportedAt: typeof options?.exportedAt === 'string' && options.exportedAt.trim()
+      ? options.exportedAt.trim()
+      : new Date().toISOString(),
+    profile,
+  };
+
+  const hasPresetSelection = options?.presetOrId !== undefined && options?.presetOrId !== null && options?.presetOrId !== '';
+  if (hasPresetSelection) {
+    const presetLibrary = getOverlayGameplayRuntimePresetLibrary(runtime, {
+      includeDefaults: options?.includeDefaults !== false,
+    });
+    const resolvedPreset = resolveOverlayRuntimePresetFromLibrary(presetLibrary, options.presetOrId);
+    if (resolvedPreset) {
+      sharePackage.presetId = resolvedPreset.id;
+      if (options?.includePreset !== false) {
+        sharePackage.preset = resolvedPreset;
+      }
+    }
+  }
+
+  return JSON.stringify(sharePackage, null, options?.pretty === true ? 2 : 0);
+}
+
 export function saveOverlayGameplayRuntimePreferences(runtime, options = {}) {
   if (!runtime) {
     return false;
@@ -1894,6 +2026,70 @@ export function importOverlayGameplayRuntimeProfile(runtime, profileInput, optio
   });
 }
 
+export function importOverlayGameplayRuntimeSharePackage(runtime, sharePackageInput, options = {}) {
+  if (!runtime) {
+    return Object.freeze({
+      success: false,
+      errors: Object.freeze(['Overlay runtime is required for share package import.']),
+      presetId: '',
+      presetRegistered: false,
+    });
+  }
+
+  let parsedInput = null;
+  if (typeof sharePackageInput === 'string') {
+    try {
+      parsedInput = JSON.parse(sharePackageInput);
+    } catch {
+      return Object.freeze({
+        success: false,
+        errors: Object.freeze(['Overlay runtime share package JSON is invalid.']),
+        presetId: '',
+        presetRegistered: false,
+      });
+    }
+  } else {
+    parsedInput = cloneJsonCompatibleValue(sharePackageInput);
+  }
+
+  const validated = validateOverlayRuntimeSharePackagePayload(parsedInput, runtime);
+  if (!validated.valid || !validated.value) {
+    return Object.freeze({
+      success: false,
+      errors: validated.errors,
+      presetId: '',
+      presetRegistered: false,
+    });
+  }
+
+  let presetRegistered = false;
+  if (validated.value.preset && options?.registerPreset !== false) {
+    const customLibrary = getOverlayGameplayRuntimePresetLibrary(runtime, { includeDefaults: false });
+    setOverlayGameplayRuntimePresetLibrary(runtime, [...customLibrary, validated.value.preset]);
+    presetRegistered = true;
+  }
+
+  const profilePayload = createOverlayRuntimePreferencePayloadFromValidated(validated.value.profile);
+  const importResult = importOverlayGameplayRuntimeProfile(runtime, profilePayload, {
+    persist: options?.persist !== false,
+  });
+  if (importResult.success !== true) {
+    return Object.freeze({
+      success: false,
+      errors: importResult.errors,
+      presetId: validated.value.presetId,
+      presetRegistered,
+    });
+  }
+
+  return Object.freeze({
+    success: true,
+    errors: Object.freeze([]),
+    presetId: validated.value.presetId,
+    presetRegistered,
+  });
+}
+
 export function setOverlayGameplayRuntimeContextInputMap(runtime, contextInputMap) {
   if (!runtime) {
     return false;