@mentra/engine 3.4.0-dev.990 → 3.4.0-dev.991

package/build/services/otaInstallPolicy.d.ts

@@ -87,8 +87,8 @@ export declare const OtaProgressMessages: {
     readonly globalTimeout: "Update took too long. Please try again.";
     readonly restartTimeout: "Glasses did not finish restarting. Restart them before trying the update again.";
     readonly sendOtaStartFailed: "Failed to communicate with glasses.";
-    readonly hotspotArtifactDownloadFailed: "Could not download the update to your phone. Check phone internet and try again.";
-    readonly hotspotArtifactVerifyFailed: "The update package could not be verified. Please try again later.";
+    readonly hotspotArtifactDownloadFailed: "The update could not be downloaded to your phone. Please try again.";
+    readonly hotspotArtifactVerifyFailed: "The update file could not be verified. Please try again later.";
     readonly hotspotWifiPermissionDenied: "Allow nearby devices access so the phone can connect to the glasses hotspot.";
     readonly hotspotStartFailed: "Could not start the glasses hotspot. Please try again.";
     readonly hotspotJoinFailed: "Could not connect the phone to the glasses hotspot. Please try again.";

package/build/services/otaInstallPolicy.js

@@ -111,8 +111,8 @@ export const OtaProgressMessages = {
     globalTimeout: "Update took too long. Please try again.",
     restartTimeout: "Glasses did not finish restarting. Restart them before trying the update again.",
     sendOtaStartFailed: "Failed to communicate with glasses.",
-    hotspotArtifactDownloadFailed: "Could not download the update to your phone. Check phone internet and try again.",
-    hotspotArtifactVerifyFailed: "The update package could not be verified. Please try again later.",
+    hotspotArtifactDownloadFailed: "The update could not be downloaded to your phone. Please try again.",
+    hotspotArtifactVerifyFailed: "The update file could not be verified. Please try again later.",
     hotspotWifiPermissionDenied: "Allow nearby devices access so the phone can connect to the glasses hotspot.",
     hotspotStartFailed: "Could not start the glasses hotspot. Please try again.",
     hotspotJoinFailed: "Could not connect the phone to the glasses hotspot. Please try again.",

package/build/services/otaInstallPolicy.js.map

@@ -1 +1 @@
-{"version":3,"file":"otaInstallPolicy.js","sourceRoot":"","sources":["../../src/services/otaInstallPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["/** Shared OTA progress watchdog timings (see progress-legacy.tsx / progress.tsx). */\nimport type {OtaProgress, OtaStatus} from \"@mentra/bluetooth-sdk\"\n\n/**\n * First glasses `build_number` (ASG `versionCode`) that uses `progress.tsx` with unified\n * `ota_status` session UI. Strictly lower builds use `/ota/progress-legacy` (routed from\n * `check-for-updates.tsx` before navigation), and get the LEGACY_* padded policy below\n * in the unified OtaInstallCoordinator (WP 8C). Change only here.\n */\nexport const MINIMUM_OTA_STATUS_BUILD = 37\n\nexport const MAX_RETRIES = 3\n/** Wait between ended native ota_start requests; never overlaps a pending request. */\nexport const RETRY_INTERVAL_MS = 5000\n/** APK/BES and general install when progress events are expected */\nexport const PROGRESS_TIMEOUT_MS = 120_000\n/** Fail if still at 0% in starting/downloading */\nexport const DOWNLOAD_STUCK_TIMEOUT_MS = 70_000\n/** MTK system install often goes quiet for long periods */\nexport const MTK_INSTALL_TIMEOUT_MS = 300_000\n/** Whole multi-step session cap */\nexport const GLOBAL_OTA_TIMEOUT_MS = 20 * 60 * 1000\n/** BLE keepalive during OTA */\nexport const PING_INTERVAL_MS = 10_000\n/**\n * If we sent ota_query_status (e.g. on reconnect) and the glasses haven't\n * replied with an ota_status by then, fall back to ota_start. This recovers\n * from the case where the glasses process restarted between mount and\n * reconnect — the session is gone, ota_query_status returns nothing, and\n * the user would otherwise sit on the spinner forever.\n */\nexport const QUERY_REPLY_TIMEOUT_MS = 6000\n/** 15s lockout on the Continue button after a BES restart, to prevent an accidental tap. */\nexport const BES_CONTINUE_LOCKOUT_MS = 15_000\n/** Fail closed if a BES reboot never reconnects; normal restarts complete in a fraction of this window. */\nexport const BES_RESTART_TIMEOUT_MS = 120_000\n\n// --- Legacy old-build (< MINIMUM_OTA_STATUS_BUILD) OTA policy (WP 8C) ---\n//\n// Ported verbatim from mobile/src/app/ota/progress-legacy.tsx, which padded EVERY\n// watchdog/timer by +20s for old ASG builds (\"Legacy OTA: +20s on every watchdog /\n// timer duration\"). Old builds respond slower on every path, so where the legacy\n// screen used a longer duration the coordinator applies the longer value whenever\n// the session is legacy-shaped (see isLegacyShapedOtaStatus / the coordinator's\n// session-shape check). Builds >= 37 keep the unpadded values above.\n\n/** The uniform pad progress-legacy.tsx added to every duration for old builds. */\nexport const LEGACY_EXTRA_TIMEOUT_MS = 20_000\nexport const LEGACY_RETRY_INTERVAL_MS = RETRY_INTERVAL_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_PROGRESS_TIMEOUT_MS = PROGRESS_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_DOWNLOAD_STUCK_TIMEOUT_MS = DOWNLOAD_STUCK_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_MTK_INSTALL_TIMEOUT_MS = MTK_INSTALL_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_GLOBAL_OTA_TIMEOUT_MS = GLOBAL_OTA_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_PING_INTERVAL_MS = PING_INTERVAL_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_BES_CONTINUE_LOCKOUT_MS = BES_CONTINUE_LOCKOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_BES_RESTART_TIMEOUT_MS = BES_RESTART_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\n/**\n * After a legacy apk `install FINISHED` observed in-flight, the legacy screen held the\n * completed state for 12s (+20s pad) so the ASG process restart settles (and fresh\n * version_info lands) before the user can continue.\n */\nexport const LEGACY_APK_COMPLETION_SETTLE_MS = 12_000 + LEGACY_EXTRA_TIMEOUT_MS\n/**\n * Legacy MTK install stall simulation (display-only): the MTK system install typically\n * stalls around 49-50%. After LEGACY_MTK_STALL_DETECT_MS without a new event in the\n * [45, 55) zone, the legacy screen simulated +1% every LEGACY_MTK_SIM_TICK_MS starting\n * at max(stall+1, 51) and capped at 60%, purely to keep the user informed.\n */\nexport const LEGACY_MTK_STALL_DETECT_MS = 20_000 + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_MTK_SIM_TICK_MS = 15_000 + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_MTK_STALL_ZONE_MIN_PERCENT = 45\nexport const LEGACY_MTK_STALL_ZONE_MAX_PERCENT = 55\nexport const LEGACY_MTK_SIM_FLOOR_PERCENT = 51\nexport const LEGACY_MTK_SIM_CAP_PERCENT = 60\n\nexport type OtaProtocolProfile = \"legacy\" | \"unified\"\n\n/**\n * Legacy-shaped ota_status: old (< 37) ASG builds send `ota_progress`, which the SDK\n * (Android MentraLive.kt / iOS MentraLive.swift) maps to a unified ota_status with\n * sessionId \"\" and totalSteps 1, and FINISHED→\"complete\" regardless of phase. A real\n * (>= 37) session always carries a sessionId; an \"idle\" reply also has sessionId \"\" but\n * proves the glasses speak the unified protocol, so it is NOT legacy-shaped.\n */\nexport function isLegacyShapedOtaStatus(otaStatus: OtaStatus | null): boolean {\n  return !!otaStatus && otaStatus.sessionId === \"\" && otaStatus.status !== \"idle\"\n}\n\n/**\n * Is the current install session legacy-shaped? Event shape wins when events exist\n * (per the WP 8C rule: key off legacy-shaped inputs, not a build flag, where possible);\n * before any event arrives only the glasses build number can tell.\n */\nexport function isLegacyShapedOtaSession(\n  otaStatus: OtaStatus | null,\n  otaProgress: OtaProgress | null,\n  buildNumber: string | null | undefined,\n): boolean {\n  if (otaStatus) return isLegacyShapedOtaStatus(otaStatus)\n  if (otaProgress) return true\n  const build = Number.parseInt(buildNumber ?? \"\", 10)\n  return Number.isFinite(build) && build > 0 && build < MINIMUM_OTA_STATUS_BUILD\n}\n\n/**\n * Select the compatibility profile once at install-screen attach. The old split\n * routes made this decision from the pre-update build and kept it for the whole\n * mounted flow, even when an APK step restarted into a newer ASG build. Returning\n * null leaves the coordinator undecided until the first meaningful OTA event.\n */\nexport function selectOtaProtocolProfile(\n  otaStatus: OtaStatus | null,\n  otaProgress: OtaProgress | null,\n  buildNumber: string | null | undefined,\n): OtaProtocolProfile | null {\n  const build = Number.parseInt(buildNumber ?? \"\", 10)\n  if (Number.isFinite(build) && build > 0) {\n    return build < MINIMUM_OTA_STATUS_BUILD ? \"legacy\" : \"unified\"\n  }\n  if (otaStatus) return isLegacyShapedOtaStatus(otaStatus) ? \"legacy\" : \"unified\"\n  if (otaProgress) return \"legacy\"\n  return null\n}\n\nexport const OtaProgressMessages = {\n  stalledOrStuck: \"Update may have failed. Ensure glasses have internet access and try again.\",\n  globalTimeout: \"Update took too long. Please try again.\",\n  restartTimeout: \"Glasses did not finish restarting. Restart them before trying the update again.\",\n  sendOtaStartFailed: \"Failed to communicate with glasses.\",\n  hotspotArtifactDownloadFailed: \"Could not download the update to your phone. Check phone internet and try again.\",\n  hotspotArtifactVerifyFailed: \"The update package could not be verified. Please try again later.\",\n  hotspotWifiPermissionDenied: \"Allow nearby devices access so the phone can connect to the glasses hotspot.\",\n  hotspotStartFailed: \"Could not start the glasses hotspot. Please try again.\",\n  hotspotJoinFailed: \"Could not connect the phone to the glasses hotspot. Please try again.\",\n  hotspotServerFailed: \"Could not make the update available to the glasses. Please try again.\",\n} as const\n"]}
+{"version":3,"file":"otaInstallPolicy.js","sourceRoot":"","sources":["../../src/services/otaInstallPolicy.ts"],"names":[],"mappings":"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","sourcesContent":["/** Shared OTA progress watchdog timings (see progress-legacy.tsx / progress.tsx). */\nimport type {OtaProgress, OtaStatus} from \"@mentra/bluetooth-sdk\"\n\n/**\n * First glasses `build_number` (ASG `versionCode`) that uses `progress.tsx` with unified\n * `ota_status` session UI. Strictly lower builds use `/ota/progress-legacy` (routed from\n * `check-for-updates.tsx` before navigation), and get the LEGACY_* padded policy below\n * in the unified OtaInstallCoordinator (WP 8C). Change only here.\n */\nexport const MINIMUM_OTA_STATUS_BUILD = 37\n\nexport const MAX_RETRIES = 3\n/** Wait between ended native ota_start requests; never overlaps a pending request. */\nexport const RETRY_INTERVAL_MS = 5000\n/** APK/BES and general install when progress events are expected */\nexport const PROGRESS_TIMEOUT_MS = 120_000\n/** Fail if still at 0% in starting/downloading */\nexport const DOWNLOAD_STUCK_TIMEOUT_MS = 70_000\n/** MTK system install often goes quiet for long periods */\nexport const MTK_INSTALL_TIMEOUT_MS = 300_000\n/** Whole multi-step session cap */\nexport const GLOBAL_OTA_TIMEOUT_MS = 20 * 60 * 1000\n/** BLE keepalive during OTA */\nexport const PING_INTERVAL_MS = 10_000\n/**\n * If we sent ota_query_status (e.g. on reconnect) and the glasses haven't\n * replied with an ota_status by then, fall back to ota_start. This recovers\n * from the case where the glasses process restarted between mount and\n * reconnect — the session is gone, ota_query_status returns nothing, and\n * the user would otherwise sit on the spinner forever.\n */\nexport const QUERY_REPLY_TIMEOUT_MS = 6000\n/** 15s lockout on the Continue button after a BES restart, to prevent an accidental tap. */\nexport const BES_CONTINUE_LOCKOUT_MS = 15_000\n/** Fail closed if a BES reboot never reconnects; normal restarts complete in a fraction of this window. */\nexport const BES_RESTART_TIMEOUT_MS = 120_000\n\n// --- Legacy old-build (< MINIMUM_OTA_STATUS_BUILD) OTA policy (WP 8C) ---\n//\n// Ported verbatim from mobile/src/app/ota/progress-legacy.tsx, which padded EVERY\n// watchdog/timer by +20s for old ASG builds (\"Legacy OTA: +20s on every watchdog /\n// timer duration\"). Old builds respond slower on every path, so where the legacy\n// screen used a longer duration the coordinator applies the longer value whenever\n// the session is legacy-shaped (see isLegacyShapedOtaStatus / the coordinator's\n// session-shape check). Builds >= 37 keep the unpadded values above.\n\n/** The uniform pad progress-legacy.tsx added to every duration for old builds. */\nexport const LEGACY_EXTRA_TIMEOUT_MS = 20_000\nexport const LEGACY_RETRY_INTERVAL_MS = RETRY_INTERVAL_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_PROGRESS_TIMEOUT_MS = PROGRESS_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_DOWNLOAD_STUCK_TIMEOUT_MS = DOWNLOAD_STUCK_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_MTK_INSTALL_TIMEOUT_MS = MTK_INSTALL_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_GLOBAL_OTA_TIMEOUT_MS = GLOBAL_OTA_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_PING_INTERVAL_MS = PING_INTERVAL_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_BES_CONTINUE_LOCKOUT_MS = BES_CONTINUE_LOCKOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_BES_RESTART_TIMEOUT_MS = BES_RESTART_TIMEOUT_MS + LEGACY_EXTRA_TIMEOUT_MS\n/**\n * After a legacy apk `install FINISHED` observed in-flight, the legacy screen held the\n * completed state for 12s (+20s pad) so the ASG process restart settles (and fresh\n * version_info lands) before the user can continue.\n */\nexport const LEGACY_APK_COMPLETION_SETTLE_MS = 12_000 + LEGACY_EXTRA_TIMEOUT_MS\n/**\n * Legacy MTK install stall simulation (display-only): the MTK system install typically\n * stalls around 49-50%. After LEGACY_MTK_STALL_DETECT_MS without a new event in the\n * [45, 55) zone, the legacy screen simulated +1% every LEGACY_MTK_SIM_TICK_MS starting\n * at max(stall+1, 51) and capped at 60%, purely to keep the user informed.\n */\nexport const LEGACY_MTK_STALL_DETECT_MS = 20_000 + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_MTK_SIM_TICK_MS = 15_000 + LEGACY_EXTRA_TIMEOUT_MS\nexport const LEGACY_MTK_STALL_ZONE_MIN_PERCENT = 45\nexport const LEGACY_MTK_STALL_ZONE_MAX_PERCENT = 55\nexport const LEGACY_MTK_SIM_FLOOR_PERCENT = 51\nexport const LEGACY_MTK_SIM_CAP_PERCENT = 60\n\nexport type OtaProtocolProfile = \"legacy\" | \"unified\"\n\n/**\n * Legacy-shaped ota_status: old (< 37) ASG builds send `ota_progress`, which the SDK\n * (Android MentraLive.kt / iOS MentraLive.swift) maps to a unified ota_status with\n * sessionId \"\" and totalSteps 1, and FINISHED→\"complete\" regardless of phase. A real\n * (>= 37) session always carries a sessionId; an \"idle\" reply also has sessionId \"\" but\n * proves the glasses speak the unified protocol, so it is NOT legacy-shaped.\n */\nexport function isLegacyShapedOtaStatus(otaStatus: OtaStatus | null): boolean {\n  return !!otaStatus && otaStatus.sessionId === \"\" && otaStatus.status !== \"idle\"\n}\n\n/**\n * Is the current install session legacy-shaped? Event shape wins when events exist\n * (per the WP 8C rule: key off legacy-shaped inputs, not a build flag, where possible);\n * before any event arrives only the glasses build number can tell.\n */\nexport function isLegacyShapedOtaSession(\n  otaStatus: OtaStatus | null,\n  otaProgress: OtaProgress | null,\n  buildNumber: string | null | undefined,\n): boolean {\n  if (otaStatus) return isLegacyShapedOtaStatus(otaStatus)\n  if (otaProgress) return true\n  const build = Number.parseInt(buildNumber ?? \"\", 10)\n  return Number.isFinite(build) && build > 0 && build < MINIMUM_OTA_STATUS_BUILD\n}\n\n/**\n * Select the compatibility profile once at install-screen attach. The old split\n * routes made this decision from the pre-update build and kept it for the whole\n * mounted flow, even when an APK step restarted into a newer ASG build. Returning\n * null leaves the coordinator undecided until the first meaningful OTA event.\n */\nexport function selectOtaProtocolProfile(\n  otaStatus: OtaStatus | null,\n  otaProgress: OtaProgress | null,\n  buildNumber: string | null | undefined,\n): OtaProtocolProfile | null {\n  const build = Number.parseInt(buildNumber ?? \"\", 10)\n  if (Number.isFinite(build) && build > 0) {\n    return build < MINIMUM_OTA_STATUS_BUILD ? \"legacy\" : \"unified\"\n  }\n  if (otaStatus) return isLegacyShapedOtaStatus(otaStatus) ? \"legacy\" : \"unified\"\n  if (otaProgress) return \"legacy\"\n  return null\n}\n\nexport const OtaProgressMessages = {\n  stalledOrStuck: \"Update may have failed. Ensure glasses have internet access and try again.\",\n  globalTimeout: \"Update took too long. Please try again.\",\n  restartTimeout: \"Glasses did not finish restarting. Restart them before trying the update again.\",\n  sendOtaStartFailed: \"Failed to communicate with glasses.\",\n  hotspotArtifactDownloadFailed: \"The update could not be downloaded to your phone. Please try again.\",\n  hotspotArtifactVerifyFailed: \"The update file could not be verified. Please try again later.\",\n  hotspotWifiPermissionDenied: \"Allow nearby devices access so the phone can connect to the glasses hotspot.\",\n  hotspotStartFailed: \"Could not start the glasses hotspot. Please try again.\",\n  hotspotJoinFailed: \"Could not connect the phone to the glasses hotspot. Please try again.\",\n  hotspotServerFailed: \"Could not make the update available to the glasses. Please try again.\",\n} as const\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mentra/engine",
-  "version": "3.4.0-dev.990",
+  "version": "3.4.0-dev.991",
   "description": "Mentra Engine — miniapp registry, WebView bridge, and miniapp store",
   "main": "build/index.js",
   "react-native": "src/index.ts",
@@ -97,13 +97,13 @@
     "registry": "https://registry.npmjs.org/"
   },
   "dependencies": {
-    "@mentra/acs-meeting": "3.4.0-dev.990",
-    "@mentra/glasses-media": "3.4.0-dev.990",
-    "@mentra/bluetooth-sdk": "3.4.0-dev.990",
-    "@mentra/cloud-client": "3.4.0-dev.990",
-    "@mentra/cloud-protocol": "3.4.0-dev.990",
-    "@mentra/crust": "3.4.0-dev.990",
-    "@mentra/miniapp": "3.4.0-dev.990",
+    "@mentra/acs-meeting": "3.4.0-dev.991",
+    "@mentra/glasses-media": "3.4.0-dev.991",
+    "@mentra/bluetooth-sdk": "3.4.0-dev.991",
+    "@mentra/cloud-client": "3.4.0-dev.991",
+    "@mentra/cloud-protocol": "3.4.0-dev.991",
+    "@mentra/crust": "3.4.0-dev.991",
+    "@mentra/miniapp": "3.4.0-dev.991",
     "buffer": "^6.0.3",
     "events": "^3.3.0",
     "jszip": "^3.10.1",

package/src/generated/releaseMetadata.ts

@@ -12,9 +12,9 @@ export interface EngineReleaseMetadata {
 export const ENGINE_RELEASE_METADATA: Readonly<EngineReleaseMetadata> = Object.freeze({
   "schemaVersion": 1,
   "familyBaseVersion": "3.4.0",
-  "releaseIdentity": "3.4.0-dev.990",
-  "releaseSetId": "mentra-3.4.0-dev.990",
-  "sourceCommit": "1e8a712475c14cc287dff714d68128601d82799c",
-  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.4.0/mentra-live-ota-3.4.0-dev.990.json",
-  "otaManifestSha256": "b024179ae3dff36b60de1e24033be243dae000b227ecd209b863609e68f45a83"
+  "releaseIdentity": "3.4.0-dev.991",
+  "releaseSetId": "mentra-3.4.0-dev.991",
+  "sourceCommit": "0694bd698d4328d72d98e25b982e520f930039e1",
+  "otaManifestUrl": "https://artifactscdn.mentraglass.com/Mentra-Community/MentraOS/releases/mentra-builds-v3.4.0/mentra-live-ota-3.4.0-dev.991.json",
+  "otaManifestSha256": "1039d426367531957e74c6a2f436f6e577198dd01df5ffb1e76a937eb6be3f9c"
 })

package/src/react/MentraLiveOtaFlow.tsx

@@ -618,11 +618,7 @@ function OtaFlowContent({
         icon="alert"
         title={translate("ota:updateFailed")}>
         <BodyText colors={colors}>{failureMessage(state.error, translate)}</BodyText>
-        {state.error?.glassesCode ? (
-          <Text style={[styles.errorCode, {color: colors.textDim}]} testID="ota-error-code">
-            {translate("ota:errorCode", {code: state.error.glassesCode})}
-          </Text>
-        ) : null}
+
       </FlowPage>
     )
   }
@@ -898,7 +894,6 @@ const styles = StyleSheet.create({
   svgIcon: {alignItems: "center", height: 72, justifyContent: "center", width: 72},
   title: {fontSize: 20, fontWeight: "600", textAlign: "center"},
   body: {fontSize: 14, lineHeight: 20, maxWidth: 420, textAlign: "center"},
-  errorCode: {fontSize: 12, fontVariant: ["tabular-nums"], lineHeight: 16, opacity: 0.7, textAlign: "center"},
   percent: {fontSize: 30, fontVariant: ["tabular-nums"], fontWeight: "700"},
   progressTrack: {borderRadius: 4, height: 8, maxWidth: 420, overflow: "hidden", width: "100%"},
   progressFill: {borderRadius: 4, height: 8},

package/src/react/useMentraLiveOta.ts

@@ -838,7 +838,7 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
     // phone-side copy outranks it. Only a failed ota_status carries a current code.
     const glassesCode = installSnapshot.otaStatus?.status === "failed" ? installSnapshot.otaStatus.error || null : null
     // Precedence mirrors the legacy screen: the BES restart instruction, then a phone-side
-    // watchdog/preflight message (English-only, no copy key), then the glasses code mapped to
+    // watchdog/preflight message (translated when a copy key is available), then the glasses code mapped to
     // copy (unknown codes get the generic glasses-error copy rather than the raw code).
     let displayedError: string
     let copyKey: string | null
@@ -847,7 +847,7 @@ export function useMentraLiveOta(options: UseMentraLiveOtaOptions = {}): MentraL
       copyKey = OTA_ERROR_BES_RESTART_REQUIRED_COPY_KEY
     } else if (installSnapshot.errorMsg) {
       displayedError = installSnapshot.errorMsg
-      copyKey = null
+      copyKey = installSnapshot.errorCopyKey ?? null
     } else {
       displayedError = getOtaErrorMessage(glassesCode)
       copyKey = otaErrorCopyKey(glassesCode)

package/src/services/OtaArtifactDownloader.ts

@@ -1,4 +1,5 @@
 import * as RNFS from "@dr.pogodin/react-native-fs"
+import {otaArtifactFailure, type OtaArtifactFailure} from "./OtaArtifactFailure"
 import type {OtaCheckCurrentGlassesResult, VersionJson} from "./OtaUpdateCheckService"
 
 /**
@@ -45,12 +46,33 @@ export class OtaArtifactError extends Error {
   constructor(
     public readonly code: "artifact_download_failed" | "artifact_verify_failed" | "manifest_invalid",
     message: string,
+    public readonly failure?: OtaArtifactFailure,
+    cause?: unknown,
   ) {
     super(message)
     this.name = "OtaArtifactError"
+    // Native Errors may contain URLs and paths. Keep the original available locally,
+    // but only the bounded, redacted failure snapshot can enter JSON/incident evidence.
+    if (cause !== undefined) Object.defineProperty(this, "cause", {value: cause})
   }
 }
 
+function artifactPreparationError(
+  error: unknown,
+  context: Omit<OtaArtifactFailure, "category" | "nativeErrors">,
+): OtaArtifactError {
+  return new OtaArtifactError(
+    error instanceof OtaArtifactError
+      ? error.code
+      : context.stage === "verify"
+      ? "artifact_verify_failed"
+      : "artifact_download_failed",
+    error instanceof OtaArtifactError ? error.message : "Preparing the update artifact failed",
+    otaArtifactFailure(error, context),
+    error,
+  )
+}
+
 const ASG_PACKAGE = "com.mentra.asg_client"
 
 export function otaArtifactsDirectory(): string {
@@ -135,7 +157,16 @@ export async function prepareArtifacts(
   ) => Promise<{statusCode: number}>,
 ): Promise<PreparedOtaArtifact[]> {
   const directory = otaArtifactsDirectory()
-  await RNFS.mkdir(directory, {NSURLIsExcludedFromBackupKey: true})
+  try {
+    await RNFS.mkdir(directory, {NSURLIsExcludedFromBackupKey: true})
+  } catch (error) {
+    throw artifactPreparationError(error, {
+      artifact: null,
+      stage: "save",
+      bytesWritten: 0,
+      contentLength: 0,
+    })
+  }
 
   const prepared: PreparedOtaArtifact[] = []
   for (let index = 0; index < plan.length; index++) {
@@ -152,19 +183,34 @@ export async function prepareArtifacts(
     })
 
     const cachedPath = `${directory}/${entry.sha256}`
-    if (await RNFS.exists(cachedPath)) {
-      const cachedHash = (await RNFS.hash(cachedPath, "sha256")).toLowerCase()
-      if (cachedHash === entry.sha256) {
-        prepared.push({...entry, filePath: cachedPath})
-        continue
+    try {
+      if (await RNFS.exists(cachedPath)) {
+        const cachedHash = (await RNFS.hash(cachedPath, "sha256")).toLowerCase()
+        if (cachedHash === entry.sha256) {
+          prepared.push({...entry, filePath: cachedPath})
+          continue
+        }
+        await safeUnlink(cachedPath)
       }
-      await safeUnlink(cachedPath)
+    } catch (error) {
+      throw artifactPreparationError(error, {
+        artifact: entry.kind,
+        stage: "verify",
+        bytesWritten: 0,
+        contentLength: 0,
+      })
     }
 
     const partPath = `${directory}/download-${index}.part`
     await safeUnlink(partPath)
+    let stage: OtaArtifactFailure["stage"] = "download"
+    let bytesWritten = 0
+    let contentLength = 0
+    let httpStatus: number | undefined
     try {
-      const reportProgress = (bytesWritten: number, contentLength: number) => {
+      const reportProgress = (written: number, length: number) => {
+        bytesWritten = written
+        contentLength = length
         onProgress?.({
           kind: entry.kind,
           index,
@@ -182,10 +228,15 @@ export async function prepareArtifacts(
             connectionTimeout: 30_000,
             readTimeout: 30_000,
             progressDivider: 5,
+            begin: (res) => {
+              httpStatus = res.statusCode
+              contentLength = res.contentLength
+            },
             progress: (res: RNFS.DownloadProgressCallbackResultT) => {
               reportProgress(res.bytesWritten, res.contentLength)
             },
           }).promise
+      httpStatus = downloadResult.statusCode
       // A resumed native download can finish with 206. Accept it only through
       // the same full-file manifest SHA256 verification below.
       if (downloadResult.statusCode !== 200 && downloadResult.statusCode !== 206) {
@@ -195,6 +246,7 @@ export async function prepareArtifacts(
         )
       }
 
+      stage = "verify"
       const actualSha256 = (await RNFS.hash(partPath, "sha256")).toLowerCase()
       if (actualSha256 !== entry.sha256) {
         throw new OtaArtifactError(
@@ -203,19 +255,14 @@ export async function prepareArtifacts(
         )
       }
 
+      stage = "save"
       const finalPath = `${directory}/${entry.sha256}`
       await safeUnlink(finalPath)
       await RNFS.moveFile(partPath, finalPath)
       prepared.push({...entry, filePath: finalPath})
     } catch (error) {
       await safeUnlink(partPath)
-      if (error instanceof OtaArtifactError) {
-        throw error
-      }
-      throw new OtaArtifactError(
-        "artifact_download_failed",
-        `Download of ${entry.kind} artifact failed: ${error instanceof Error ? error.message : String(error)}`,
-      )
+      throw artifactPreparationError(error, {artifact: entry.kind, stage, httpStatus, bytesWritten, contentLength})
     }
   }
   return prepared

package/src/services/OtaArtifactFailure.ts

@@ -0,0 +1,102 @@
+export type OtaArtifactFailureCategory =
+  | "internet"
+  | "connection"
+  | "server"
+  | "timeout"
+  | "storage"
+  | "save"
+  | "secure_connection"
+  | "download"
+  | "verify"
+
+export interface OtaArtifactFailure {
+  artifact: "apk" | "mtk" | "bes" | null
+  stage: "download" | "verify" | "save"
+  category: OtaArtifactFailureCategory
+  httpStatus?: number
+  bytesWritten: number
+  contentLength: number
+  nativeErrors: {name?: string; code?: string; domain?: string; message?: string}[]
+}
+
+/** Never retain artifact URLs, local paths, headers, or arbitrary native userInfo. */
+function privateErrorText(value: unknown): string | undefined {
+  if (typeof value !== "string" && typeof value !== "number") return undefined
+  return String(value)
+    .replace(/(?:https?|file):\/\/[^\s"'<>]+/gi, "[REDACTED_URL]")
+    .replace(/\/(?:data|var|private|storage|Users)\/[^\s"'<>]*/g, "[REDACTED_PATH]")
+    .replace(/\b(?:authorization|proxy-authorization|cookie|set-cookie)\s*[:=][^\r\n]*/gi, "[REDACTED_HEADER]")
+    .replace(
+      /\b(?:bearer\s+\S+|(?:token|password|signature|api[_-]?key)\s*[:=]\s*(?:"[^"]*"|'[^']*'|\S+))/gi,
+      "[REDACTED]",
+    )
+    .slice(0, 500)
+}
+
+/** Preserve Error's non-enumerable fields before JSON serialization drops them. */
+export function otaArtifactFailure(
+  error: unknown,
+  context: Omit<OtaArtifactFailure, "category" | "nativeErrors">,
+): OtaArtifactFailure {
+  const nativeErrors: OtaArtifactFailure["nativeErrors"] = []
+  const seen = new Set<unknown>()
+  let current = error
+  for (let depth = 0; current != null && depth < 4 && !seen.has(current); depth++) {
+    seen.add(current)
+    if (typeof current !== "object") {
+      nativeErrors.push({message: privateErrorText(current)})
+      break
+    }
+    const detail = current as Record<string, unknown>
+    nativeErrors.push({
+      name: privateErrorText(detail.name),
+      code: privateErrorText(detail.code),
+      domain: privateErrorText(detail.domain),
+      message: privateErrorText(detail.message),
+    })
+    current = detail.cause
+  }
+  const text = nativeErrors.map((entry) => Object.values(entry).join(" ")).join(" ")
+  let httpStatus = context.httpStatus
+  if (context.stage === "download" && httpStatus === undefined) {
+    // BackgroundOtaArtifactDownloader.swift rejects non-2xx responses instead of
+    // resolving a status. Expo can wrap this exact producer message in another Error.
+    for (const entry of nativeErrors) {
+      const response = /\bArtifact download failed with HTTP ([1-5]\d{2})\b/.exec(entry.message ?? "")
+      if (response) {
+        httpStatus = Number(response[1])
+        break
+      }
+    }
+  }
+  // A DNS error, timeout, reset, or HTTP failure alone does not establish no internet.
+  let category: OtaArtifactFailureCategory = context.stage === "verify" ? "verify" : "download"
+  if (/\bENOSPC\b|No space left on device/i.test(text)) category = "storage"
+  else if (context.stage === "save") category = "save"
+  else if (context.stage === "download") {
+    if (/\b(?:EACCES|EROFS)\b|Permission denied|Read-only file system/i.test(text)) category = "save"
+    else if (
+      httpStatus !== undefined &&
+      httpStatus >= 100 &&
+      httpStatus <= 599 &&
+      httpStatus !== 200 &&
+      httpStatus !== 206
+    )
+      category = "server"
+    else if (
+      nativeErrors.some((entry) => entry.domain === "NSURLErrorDomain" && entry.code === "-1009") ||
+      /\b(?:ENETDOWN|NSURLErrorNotConnectedToInternet)\b|Network is down|not connected to the Internet/i.test(text)
+    )
+      category = "internet"
+    else if (/\b(?:ETIMEDOUT|SocketTimeoutException)\b|timed? out/i.test(text)) category = "timeout"
+    else if (/\b(?:SSLHandshakeException|SSLPeerUnverifiedException|CERTIFICATE_VERIFY_FAILED)\b/i.test(text))
+      category = "secure_connection"
+    else if (
+      /\b(?:ENETUNREACH|ECONNRESET|ECONNABORTED|EPIPE|UnknownHostException|EAI_NODATA|EAI_AGAIN)\b|Software caused connection abort|Connection reset|Unable to resolve host/i.test(
+        text,
+      )
+    )
+      category = "connection"
+  }
+  return {...context, httpStatus, category, nativeErrors}
+}

package/src/services/OtaErrorMapping.ts

@@ -8,8 +8,8 @@ import type {OtaProgress, OtaStatus} from "../facades/ota"
  * The glasses-side producers are `sendProgressToPhone(..., "FAILED", errorCode)` in the
  * ASG client's OtaHelper (download classification, install failures, and the downgrade
  * handoff to the recovery worker). Keep this table in sync with those codes; anything
- * else falls back to `OTA_ERROR_UNKNOWN_GLASSES_COPY_KEY` and the raw code is shown in a
- * secondary line so support can still identify it.
+ * else falls back to `OTA_ERROR_UNKNOWN_GLASSES_COPY_KEY`. Raw codes remain in private
+ * incident evidence rather than the product failure page.
  */
 export const OTA_GLASSES_ERROR_COPY_KEYS: Readonly<Record<string, string>> = {
   dns_failed: "ota:errorDnsFailed",
@@ -42,6 +42,45 @@ export const OTA_ERROR_UNKNOWN_GLASSES_COPY_KEY = "ota:errorGlassesUnknown"
 export const OTA_ERROR_GENERIC_COPY_KEY = "ota:errorGeneric"
 export const OTA_ERROR_BES_RESTART_REQUIRED_COPY_KEY = "ota:errorBesRestartRequired"
 
+const PHONE_ARTIFACT_COPY_KEYS: Readonly<Record<string, string>> = {
+  internet: "ota:errorPhoneInternet",
+  connection: "ota:errorPhoneConnection",
+  server: "ota:errorPhoneDownloadServer",
+  timeout: "ota:errorPhoneDownloadTimeout",
+  storage: "ota:errorPhoneStorage",
+  save: "ota:errorPhoneSave",
+  secure_connection: "ota:errorPhoneSecureConnection",
+  download: "ota:errorPhoneDownload",
+  verify: "ota:errorPhoneVerify",
+}
+
+/** A known failed stage is useful; it is not evidence of an internet outage. */
+export function phoneOtaErrorCopyKey(error: unknown): string {
+  if (typeof error !== "object" || error === null) return OTA_ERROR_GENERIC_COPY_KEY
+  const detail = error as {code?: unknown; failure?: {category?: unknown}}
+  switch (detail.code) {
+    case "artifact_download_failed":
+    case "artifact_verify_failed": {
+      const category = detail.failure?.category
+      if (typeof category === "string" && hasOwn(PHONE_ARTIFACT_COPY_KEYS, category))
+        return PHONE_ARTIFACT_COPY_KEYS[category]
+      return detail.code === "artifact_verify_failed" ? "ota:errorPhoneVerify" : "ota:errorPhoneDownload"
+    }
+    case "manifest_invalid":
+      return "ota:errorPhoneVerify"
+    case "hotspot_wifi_permission_denied":
+      return "ota:errorPhoneNearbyPermission"
+    case "hotspot_start_failed":
+      return "ota:errorGlassesHotspotStart"
+    case "hotspot_join_failed":
+      return "ota:errorPhoneHotspotJoin"
+    case "hotspot_server_failed":
+      return "ota:errorPhoneShareUpdate"
+    default:
+      return OTA_ERROR_GENERIC_COPY_KEY
+  }
+}
+
 /** English copy for every OTA error key above. Mirrored in the Mentra App's `ota` i18n namespace. */
 export const OTA_ERROR_ENGLISH_COPY: Readonly<Record<string, string>> = {
   "ota:errorDnsFailed": "Could not find the update server — retry, or check glasses Wi-Fi if this continues",
@@ -63,12 +102,12 @@ export const OTA_ERROR_ENGLISH_COPY: Readonly<Record<string, string>> = {
   "ota:errorNoInternet": "Glasses Wi-Fi has no internet connection",
   "ota:errorClockSkew": "Glasses clock is wrong — syncing time from your phone, then retrying update check",
   "ota:errorSslError": "Secure connection failed — try a different Wi-Fi network",
-  "ota:errorDownloadFailed": "Download failed — check glasses Wi-Fi connection",
+  "ota:errorDownloadFailed": "The update could not be downloaded to your glasses. Please try again.",
   "ota:errorInsufficientStorage": "Not enough storage on your glasses — free up space before trying again",
   "ota:errorFirmwareTooLarge": "Firmware file is unexpectedly large — please contact support",
   "ota:errorFirmwareVerifyFailed": "Firmware verification failed — please try again or contact support",
   "ota:errorApkVerifyFailed": "Update verification failed — please try again or contact support",
-  "ota:errorInstallFailed": "Install failed — please try again",
+  "ota:errorInstallFailed": "The update could not be installed on your glasses. Please try again.",
   "ota:errorApkRestartGuardNotPersisted":
     "Your glasses could not save the update before restarting. Restart your glasses and try again.",
   "ota:errorDowngradeHandoffRefused":
@@ -77,8 +116,23 @@ export const OTA_ERROR_ENGLISH_COPY: Readonly<Record<string, string>> = {
     "The recovery service on your glasses did not respond. Restart your glasses and try again.",
   "ota:errorDowngradeTransactionStalled":
     "The version change on your glasses did not finish. Restart your glasses and try again.",
-  "ota:errorGlassesUnknown": "Your glasses reported an unexpected error. Restart your glasses and try again.",
-  "ota:errorGeneric": "Update failed",
+  "ota:errorGlassesUnknown": "Something went wrong. Please try again.",
+  "ota:errorGeneric": "Something went wrong. Please try again.",
+  "ota:errorPhoneInternet": "Your phone could not connect to the internet. Check its connection and try again.",
+  "ota:errorPhoneConnection": "Your phone could not reach the update server. Check its connection and try again.",
+  "ota:errorPhoneDownloadServer": "The update server could not provide the download. Please try again later.",
+  "ota:errorPhoneDownloadTimeout": "The update download took too long. Please try again.",
+  "ota:errorPhoneStorage": "There is not enough space on your phone for the update. Free up space and try again.",
+  "ota:errorPhoneSave": "Your phone could not save the update. Please try again.",
+  "ota:errorPhoneSecureConnection":
+    "Your phone could not make a secure connection to the update server. Please try again later.",
+  "ota:errorPhoneDownload": "The update could not be downloaded to your phone. Please try again.",
+  "ota:errorPhoneVerify": "The update file could not be verified. Please try again later.",
+  "ota:errorPhoneNearbyPermission": "Allow nearby devices access so your phone can connect to your glasses.",
+  "ota:errorGlassesHotspotStart":
+    "Your glasses could not start the connection needed for the update. Please try again.",
+  "ota:errorPhoneHotspotJoin": "Your phone could not connect to your glasses for the update. Please try again.",
+  "ota:errorPhoneShareUpdate": "Your phone could not send the update to your glasses. Please try again.",
   "ota:errorBesRestartRequired": "Restart your glasses to safely exit firmware update mode before trying again",
   "ota:errorCode": "Error code: {{code}}",
 }

package/src/services/OtaFailureReportService.ts

@@ -1,5 +1,6 @@
 import type {OtaProgress, OtaStatus} from "@mentra/bluetooth-sdk"
 
+import type {OtaArtifactFailure} from "./OtaArtifactFailure"
 import {redactOtaDiagnosticError} from "../utils/otaDiagnosticRedaction"
 
 export type OtaFailureReason =
@@ -15,6 +16,7 @@ export interface OtaFailureEvidence {
   attemptId: string
   deviceRevision: number
   reason: OtaFailureReason
+  artifactFailure?: OtaArtifactFailure
   transport: "wifi" | "hotspot" | null
   hotspotPhase: string
   connected: boolean

package/src/services/OtaInstallCoordinator.ts

@@ -23,9 +23,11 @@ import GlobalEventEmitter from "../utils/GlobalEventEmitter"
 import {isGlassesConnected, useGlassesStore} from "../stores/glasses"
 import {resolveOtaManifestUrl} from "./otaManifestUrl"
 import {hotspotOtaTransport, type HotspotOtaPhase} from "./HotspotOtaTransport"
+import {OTA_ERROR_ENGLISH_COPY, phoneOtaErrorCopyKey} from "./OtaErrorMapping"
+import type {OtaArtifactFailure} from "./OtaArtifactFailure"
 import {waitForOtaInternet} from "./OtaInternetRecovery"
 import {submitOtaFailureReport, type OtaFailureReason} from "./OtaFailureReportService"
-import type {OtaArtifactDownloadProgress} from "./OtaArtifactDownloader"
+import {OtaArtifactError, type OtaArtifactDownloadProgress} from "./OtaArtifactDownloader"
 import {otaDeviceSessionRevision, subscribeOtaDeviceSession} from "./OtaDeviceSession"
 import {checkCurrentGlassesForUpdate, isOtaCheckForCurrentDevice} from "./OtaUpdateCheckService"
 import type {OtaCheckCurrentGlassesResult} from "./OtaUpdateCheckService"
@@ -67,28 +69,6 @@ function isTerminalForWatchdog(d: DisplayState): boolean {
   return d === "complete" || d === "failed" || d === "restarting"
 }
 
-function hotspotPreflightErrorMessage(error: unknown): string {
-  const code =
-    typeof error === "object" && error !== null && "code" in error ? String((error as {code: unknown}).code) : ""
-  switch (code) {
-    case "artifact_download_failed":
-      return OtaProgressMessages.hotspotArtifactDownloadFailed
-    case "artifact_verify_failed":
-    case "manifest_invalid":
-      return OtaProgressMessages.hotspotArtifactVerifyFailed
-    case "hotspot_wifi_permission_denied":
-      return OtaProgressMessages.hotspotWifiPermissionDenied
-    case "hotspot_start_failed":
-      return OtaProgressMessages.hotspotStartFailed
-    case "hotspot_join_failed":
-      return OtaProgressMessages.hotspotJoinFailed
-    case "hotspot_server_failed":
-      return OtaProgressMessages.hotspotServerFailed
-    default:
-      return OtaProgressMessages.hotspotServerFailed
-  }
-}
-
 /** Non-empty when glasses are actively reporting work — drives stall timeout reset. */
 function buildProgressStalenessSignature(
   otaStatus: OtaStatus | null,
@@ -149,6 +129,7 @@ function hasRecoveringOtaReply(otaStatus: OtaStatus | null, otaProgress: OtaProg
 export interface OtaInstallSnapshot {
   displayState: DisplayState
   errorMsg: string
+  errorCopyKey?: string | null
   continueButtonDisabled: boolean
   connected: boolean
   otaStatus: OtaStatus | null
@@ -220,6 +201,7 @@ class OtaInstallCoordinator {
 
   // Genuinely session-local state (was component state/refs).
   private errorMsg = ""
+  private errorCopyKey: string | null = null
   private reportAttemptId = `${Date.now()}-0`
   private reportAttemptSequence = 0
   private finishCompletion: {attemptId: string; deviceRevision: number; promise: Promise<void>} | null = null
@@ -598,6 +580,7 @@ class OtaInstallCoordinator {
         versionChangeSession: this.versionChangeSession,
       }),
       errorMsg: this.errorMsg,
+      errorCopyKey: this.errorCopyKey,
       // Keep Continue disabled while the expected BES reboot is still in flight.
       continueButtonDisabled: this.continueButtonDisabled || this.besRestartRecovery === "awaiting",
       connected,
@@ -672,6 +655,7 @@ class OtaInstallCoordinator {
   private resetSessionState(): void {
     this.finishCompletion = null
     this.errorMsg = ""
+    this.errorCopyKey = null
     this.versionChangeReconnected = false
     this.sawReconnectEdge = false
     this.continueButtonDisabled = false
@@ -736,12 +720,13 @@ class OtaInstallCoordinator {
 
   // Setters mirror the old setState calls: bail on identical values (React's
   // setState bailout), notify snapshot subscribers, and queue a reaction pass.
-  private reportFailure(reason: OtaFailureReason): void {
+  private reportFailure(reason: OtaFailureReason, artifactFailure?: OtaArtifactFailure): void {
     const state = useGlassesStore.getState()
     void submitOtaFailureReport({
       attemptId: this.reportAttemptId,
       deviceRevision: otaDeviceSessionRevision(),
       reason,
+      artifactFailure,
       transport: this.observedTransport,
       hotspotPhase: this.hotspotPhase,
       connected: isGlassesConnected(state.connection),
@@ -763,9 +748,10 @@ class OtaInstallCoordinator {
     })
   }
 
-  private setErrorMsg(next: string, failureReason?: OtaFailureReason): void {
-    if (this.errorMsg === next) return
+  private setErrorMsg(next: string, failureReason?: OtaFailureReason, copyKey: string | null = null): void {
+    if (this.errorMsg === next && this.errorCopyKey === copyKey) return
     this.errorMsg = next
+    this.errorCopyKey = copyKey
     if (next && failureReason) this.reportFailure(failureReason)
     this.emitInternalChange()
     this.react()
@@ -1736,10 +1722,13 @@ class OtaInstallCoordinator {
       if (this.selectedTransport === "hotspot" && !nativeStartAttempted) {
         ownership.outcome = "rejected"
         this.clearStuckTimeout()
-        this.reportFailure("hotspot_preflight_failed")
+        this.reportFailure("hotspot_preflight_failed", err instanceof OtaArtifactError ? err.failure : undefined)
         await this.teardownHotspotTransport()
         if (!isCurrentAttempt()) return
-        if (this.attached) this.setErrorMsg(hotspotPreflightErrorMessage(err))
+        if (this.attached) {
+          const copyKey = phoneOtaErrorCopyKey(err)
+          this.setErrorMsg(OTA_ERROR_ENGLISH_COPY[copyKey], undefined, copyKey)
+        }
         return
       }