@robotical/webapp-types 3.25.5 → 3.25.6

package/dist-types/package.json

@@ -1,6 +1,6 @@
 {
     "name": "marty-web-app",
-    "version": "3.25.5",
+    "version": "3.25.6",
     "private": true,
     "engines": {
         "node": ">=20"

package/dist-types/src/application/RAFTs/Marty/PublishedDataAnalyser.d.ts

@@ -1,5 +1,6 @@
 /// <reference types="node" />
 import EventEmitter from "events";
+import { ColourSignalProfile } from "../../../utils/colour-classifier";
 import RAFT from "../RAFT";
 import type { RICStateInfo } from "@robotical/roboticaljs";
 import { type ColourSensorValues } from "./published-data-helpers";
@@ -39,8 +40,7 @@ declare class PublishedDataAnalyser extends EventEmitter {
     setNoiseSense(noiseSense: MartyState["noiseSense"]): void;
 }
 declare class ColourSensedDetection {
-    private thresholds;
-    detectColourSensed({ r, g, b, clear, air }: ColourSensorValues, analyser: PublishedDataAnalyser): void;
+    detectColourSensed({ r, g, b, clear, air }: ColourSensorValues, analyser: PublishedDataAnalyser, profile?: ColourSignalProfile): void;
 }
 declare class LightSenseDetection {
     private lowLightThreshold;

package/dist-types/src/application/RAFTs/Marty/PublishedDataAnalyser.js

@@ -14,9 +14,10 @@ var __extends = (this && this.__extends) || (function () {
     };
 })();
 import EventEmitter from "events";
-import colourPolicy from "../../../utils/marty-colour-policy.json";
+import { classifyColour } from "../../../utils/colour-classifier";
+import { getAddonColourSensorProfile } from "../../../utils/colour-sensor-profile";
 import { createRaftPubSubscriptionHelper } from "../raft-subscription-helpers";
-import { getColourSensor, getLightSensor, getObjectSensor, getNoiseSensor, getRGBFromColourSensorVals, getHueChroma, getLightSenseValues, getObjectIsTouchingFromVals, getNoiseSenseValue, } from "./published-data-helpers";
+import { getColourSensor, getLightSensor, getObjectSensor, getNoiseSensor, getRGBFromColourSensorVals, getLightSenseValues, getObjectIsTouchingFromVals, getNoiseSenseValue, } from "./published-data-helpers";
 var PublishedDataAnalyser = /** @class */ (function (_super) {
     __extends(PublishedDataAnalyser, _super);
     function PublishedDataAnalyser(marty) {
@@ -80,6 +81,7 @@ var PublishedDataAnalyser = /** @class */ (function (_super) {
         (_a = this.pubSub) === null || _a === void 0 ? void 0 : _a.unsubscribe();
     };
     PublishedDataAnalyser.prototype.analyse = function (data) {
+        var _a;
         if (!data)
             return;
         var colourSensor = getColourSensor(data);
@@ -87,7 +89,7 @@ var PublishedDataAnalyser = /** @class */ (function (_super) {
         var objectSensor = getObjectSensor(data);
         var noiseSensor = getNoiseSensor(data);
         colourSensor &&
-            this.colourSensedDetection.detectColourSensed(getRGBFromColourSensorVals(colourSensor), this);
+            this.colourSensedDetection.detectColourSensed(getRGBFromColourSensorVals(colourSensor), this, (_a = getAddonColourSensorProfile(this.marty, colourSensor)) === null || _a === void 0 ? void 0 : _a.signal);
         (objectSensor || colourSensor) &&
             this.objectSenseDetection.detectObjectSense(getObjectIsTouchingFromVals(objectSensor, colourSensor), this);
         lightSensor &&
@@ -119,28 +121,10 @@ var PublishedDataAnalyser = /** @class */ (function (_super) {
 }(EventEmitter));
 var ColourSensedDetection = /** @class */ (function () {
     function ColourSensedDetection() {
-        this.thresholds = colourPolicy.boundaries;
     }
-    ColourSensedDetection.prototype.detectColourSensed = function (_a, analyser) {
+    ColourSensedDetection.prototype.detectColourSensed = function (_a, analyser, profile) {
         var r = _a.r, g = _a.g, b = _a.b, clear = _a.clear, air = _a.air;
-        if (air) {
-            return analyser.setColourSensed("air");
-        }
-        else {
-            var _b = getHueChroma(r, g, b), hue = _b[0], chroma = _b[1];
-            for (var _i = 0, _c = this.thresholds; _i < _c.length; _i++) {
-                var colour = _c[_i];
-                if (colour.hue[0] <= hue &&
-                    hue <= colour.hue[1] &&
-                    colour.chroma[0] <= chroma &&
-                    chroma <= colour.chroma[1] &&
-                    colour.clear[0] <= clear &&
-                    clear <= colour.clear[1]) {
-                    return analyser.setColourSensed(colour.name);
-                }
-            }
-            return analyser.setColourSensed("unclear");
-        }
+        return analyser.setColourSensed(classifyColour({ red: r, green: g, blue: b, clear: clear, air: air }, profile).classifiedColour);
     };
     return ColourSensedDetection;
 }());

package/dist-types/src/components/oneoffs/calibration-screens/ColourSensorCalibration/messages.d.ts

@@ -1,5 +1,12 @@
 declare const english: {
     readonly title: "Colour sensor calibration";
+    readonly sessionId: "Diagnostics session ID";
+    readonly uploading: "Saving calibration readings and results to the database…";
+    readonly uploadsSaved: "Calibration readings and results are saved automatically to the database under this session ID.";
+    readonly uploadPending: "Some calibration data is waiting to upload. It is saved on this device and will retry automatically when the connection is available.";
+    readonly uploadStorageWarning: "Some calibration data could not be saved on this device yet. Keep the app open and retry uploading before closing it.";
+    readonly phoneUploadPending: "Calibration data is waiting to upload. Keep the app open until uploading finishes so these readings are not lost.";
+    readonly retryUpload: "Retry calibration upload";
     readonly introduction: "Keep Marty connected to USB power. We will collect {{count}} readings each for air and white. If you have a purple colour card, you can also use it for an optional step. Keep the lighting the same throughout.";
     readonly sensor: "Colour sensor";
     readonly selectSensor: "Select a colour sensor";
@@ -22,16 +29,21 @@ declare const english: {
     readonly capturePurple: "Capture purple and save calibration";
     readonly skipPurple: "Skip and save calibration";
     readonly startAgain: "Start again";
+    readonly restartCalibration: "Calibrate this sensor again";
     readonly saved: "Calibration saved on Marty: {{count}} readings for each position. This sensor's ground threshold is {{threshold}}.";
     readonly savedWithoutPurple: "Calibration saved on Marty: {{count}} readings each for air and white. Purple was skipped, so the current ground threshold was kept.";
+    readonly savedWithRGB: "Calibration saved: {{count}} readings for air, white and purple. Purple's colour signal is usable, but its brightness overlaps air. The app will use the calibrated colour signal and keep Marty's current ground threshold.";
     readonly reconnectStep: "Final step: reconnect Marty";
     readonly reconnect: "Disconnect Marty below, then use Connect Marty to connect the same robot again. Your calibration is saved. Colour diagnostics will unlock once Marty has loaded the new sensor settings.";
     readonly disconnectToFinish: "Disconnect Marty to finish calibration";
     readonly disconnecting: "Disconnecting Marty…";
     readonly loadingCalibration: "Marty has reconnected. Waiting for the new sensor settings and fresh readings…";
-    readonly calibrationReloadFailed: "The saved calibration could not be confirmed for this sensor. Keep the same sensor attached, disconnect Marty and reconnect it again.";
+    readonly calibrationCheckDelayed: "Marty is connected, but the sensor check is taking longer than expected. The app is retrying automatically. Keep the sensor attached and Marty on USB power. If this continues, disconnect and reconnect Marty.";
+    readonly calibrationSensorChanged: "The attached colour sensor is different from the one that was calibrated. Reattach the original sensor to finish, or use the calibration screen to calibrate this sensor again.";
+    readonly calibrationSettingsChanged: "The sensor's stored white reference differs from the calibration that was saved. Reconnect Marty once; if this message remains, use the calibration screen to calibrate this sensor again.";
+    readonly disconnectFailed: "Marty could not be disconnected. Try the disconnect button again.";
     readonly reconnected: "Calibration complete. Marty has reconnected and loaded the saved sensor settings. Use Settings → Diagnostics to check all five cards and air.";
-    readonly download: "Download calibration results";
+    readonly download: "Download a copy (optional)";
     readonly back: "Back to calibration";
     readonly usbRequired: "Connect Marty to USB power and keep it connected until calibration finishes.";
     readonly notInAir: "Lift Marty so both feet are clear of the surface, then try again.";

package/dist-types/src/components/oneoffs/calibration-screens/ColourSensorCalibration/messages.js

@@ -1,5 +1,12 @@
 var english = {
     title: "Colour sensor calibration",
+    sessionId: "Diagnostics session ID",
+    uploading: "Saving calibration readings and results to the database…",
+    uploadsSaved: "Calibration readings and results are saved automatically to the database under this session ID.",
+    uploadPending: "Some calibration data is waiting to upload. It is saved on this device and will retry automatically when the connection is available.",
+    uploadStorageWarning: "Some calibration data could not be saved on this device yet. Keep the app open and retry uploading before closing it.",
+    phoneUploadPending: "Calibration data is waiting to upload. Keep the app open until uploading finishes so these readings are not lost.",
+    retryUpload: "Retry calibration upload",
     introduction: "Keep Marty connected to USB power. We will collect {{count}} readings each for air and white. If you have a purple colour card, you can also use it for an optional step. Keep the lighting the same throughout.",
     sensor: "Colour sensor",
     selectSensor: "Select a colour sensor",
@@ -22,16 +29,21 @@ var english = {
     capturePurple: "Capture purple and save calibration",
     skipPurple: "Skip and save calibration",
     startAgain: "Start again",
+    restartCalibration: "Calibrate this sensor again",
     saved: "Calibration saved on Marty: {{count}} readings for each position. This sensor's ground threshold is {{threshold}}.",
     savedWithoutPurple: "Calibration saved on Marty: {{count}} readings each for air and white. Purple was skipped, so the current ground threshold was kept.",
+    savedWithRGB: "Calibration saved: {{count}} readings for air, white and purple. Purple's colour signal is usable, but its brightness overlaps air. The app will use the calibrated colour signal and keep Marty's current ground threshold.",
     reconnectStep: "Final step: reconnect Marty",
     reconnect: "Disconnect Marty below, then use Connect Marty to connect the same robot again. Your calibration is saved. Colour diagnostics will unlock once Marty has loaded the new sensor settings.",
     disconnectToFinish: "Disconnect Marty to finish calibration",
     disconnecting: "Disconnecting Marty…",
     loadingCalibration: "Marty has reconnected. Waiting for the new sensor settings and fresh readings…",
-    calibrationReloadFailed: "The saved calibration could not be confirmed for this sensor. Keep the same sensor attached, disconnect Marty and reconnect it again.",
+    calibrationCheckDelayed: "Marty is connected, but the sensor check is taking longer than expected. The app is retrying automatically. Keep the sensor attached and Marty on USB power. If this continues, disconnect and reconnect Marty.",
+    calibrationSensorChanged: "The attached colour sensor is different from the one that was calibrated. Reattach the original sensor to finish, or use the calibration screen to calibrate this sensor again.",
+    calibrationSettingsChanged: "The sensor's stored white reference differs from the calibration that was saved. Reconnect Marty once; if this message remains, use the calibration screen to calibrate this sensor again.",
+    disconnectFailed: "Marty could not be disconnected. Try the disconnect button again.",
     reconnected: "Calibration complete. Marty has reconnected and loaded the saved sensor settings. Use Settings → Diagnostics to check all five cards and air.",
-    download: "Download calibration results",
+    download: "Download a copy (optional)",
     back: "Back to calibration",
     usbRequired: "Connect Marty to USB power and keep it connected until calibration finishes.",
     notInAir: "Lift Marty so both feet are clear of the surface, then try again.",

package/dist-types/src/screens/configuration/marty/Diagnostics/ColourSensorDiagnostics/messages.d.ts

@@ -17,6 +17,7 @@ declare const colourDiagnosticsEnglish: {
     airPrompt: string;
     result: string;
     withoutAir: string;
+    firmwareAir: string;
     waiting: string;
     capture: string;
     captureAir: string;
@@ -33,6 +34,7 @@ declare const colourDiagnosticsEnglish: {
     storageWarning: string;
     sensorDisconnected: string;
     sensorInitialising: string;
+    sensorBusy: string;
     calibrationReconnectRequired: string;
     sensorAsleep: string;
     sensorOffline: string;

package/dist-types/src/screens/configuration/marty/Diagnostics/ColourSensorDiagnostics/messages.js

@@ -11,7 +11,8 @@ var colourDiagnosticsEnglish = {
     prompt: "Place the selected sensor on the {{colour}} card.",
     airPrompt: "Lift Marty so both feet are at least 10 cm above any card or surface, with the sensors facing down and uncovered. Keep the lighting the same and hold still.",
     result: "Blocks interpretation: {{result}}",
-    withoutAir: "Colour match before the air flag is applied: {{result}}",
+    withoutAir: "Firmware reports air; the RGB signal matches {{result}}.",
+    firmwareAir: "Firmware Air",
     waiting: "Select a sensor and wait for fresh readings.",
     capture: "Take {{colour}} snapshot",
     captureAir: "Take air snapshot",
@@ -28,6 +29,7 @@ var colourDiagnosticsEnglish = {
     storageWarning: "This browser cannot keep a local backup. Download the data before closing this page.",
     sensorDisconnected: "The selected sensor disconnected. Reconnect Marty and select the sensor again.",
     sensorInitialising: "Marty is still loading the sensor settings. Wait a few seconds and try again.",
+    sensorBusy: "The sensor is completing another check. Wait a moment and take the snapshot again.",
     calibrationReconnectRequired: "Reconnect Marty to finish calibration before taking more colour snapshots.",
     sensorAsleep: "Marty's sensor power is asleep. Taking a snapshot wakes the sensors before collecting readings.",
     sensorOffline: "The colour sensor is offline. Take a snapshot to wake it. If it stays offline, check the sensor connection.",

package/dist-types/src/utils/colour-calibration-reconnect.d.ts

@@ -0,0 +1,19 @@
+import type { ColourSensor } from "./colour-sensor-diagnostics";
+import { CalibrationRecordRef } from "./colour-calibration-records";
+type PendingCalibration = {
+    connectionInstanceId: string;
+    serialNumber: string;
+    whiteCalibrationHex: string;
+    calibrationRecord?: CalibrationRecordRef;
+};
+export declare class ColourCalibrationReconnectError extends Error {
+    reason: "calibrationSensorChanged" | "calibrationSettingsChanged";
+    constructor(reason: "calibrationSensorChanged" | "calibrationSettingsChanged");
+}
+export declare const getPendingColourCalibration: (sensor: ColourSensor) => PendingCalibration | null;
+export declare const markColourCalibrationPending: (sensor: ColourSensor, serialNumber: string, whiteCalibrationHex: string, calibrationRecord?: CalibrationRecordRef) => void;
+export declare const restorePendingColourCalibration: (sensor: ColourSensor, pending: PendingCalibration) => void;
+export declare const clearPendingColourCalibration: (sensor: ColourSensor) => void;
+/** Read-only completion check, shared by browsers and native WebViews through the existing REST bridge. */
+export declare const finishColourCalibrationReconnect: (sensor: ColourSensor, signal: AbortSignal) => Promise<boolean>;
+export {};

package/dist-types/src/utils/colour-calibration-reconnect.js

@@ -0,0 +1,261 @@
+var __extends = (this && this.__extends) || (function () {
+    var extendStatics = function (d, b) {
+        extendStatics = Object.setPrototypeOf ||
+            ({ __proto__: [] } instanceof Array && function (d, b) { d.__proto__ = b; }) ||
+            function (d, b) { for (var p in b) if (Object.prototype.hasOwnProperty.call(b, p)) d[p] = b[p]; };
+        return extendStatics(d, b);
+    };
+    return function (d, b) {
+        if (typeof b !== "function" && b !== null)
+            throw new TypeError("Class extends value " + String(b) + " is not a constructor or null");
+        extendStatics(d, b);
+        function __() { this.constructor = d; }
+        d.prototype = b === null ? Object.create(b) : (__.prototype = b.prototype, new __());
+    };
+})();
+var __assign = (this && this.__assign) || function () {
+    __assign = Object.assign || function(t) {
+        for (var s, i = 1, n = arguments.length; i < n; i++) {
+            s = arguments[i];
+            for (var p in s) if (Object.prototype.hasOwnProperty.call(s, p))
+                t[p] = s[p];
+        }
+        return t;
+    };
+    return __assign.apply(this, arguments);
+};
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+var __generator = (this && this.__generator) || function (thisArg, body) {
+    var _ = { label: 0, sent: function() { if (t[0] & 1) throw t[1]; return t[1]; }, trys: [], ops: [] }, f, y, t, g;
+    return g = { next: verb(0), "throw": verb(1), "return": verb(2) }, typeof Symbol === "function" && (g[Symbol.iterator] = function() { return this; }), g;
+    function verb(n) { return function (v) { return step([n, v]); }; }
+    function step(op) {
+        if (f) throw new TypeError("Generator is already executing.");
+        while (g && (g = 0, op[0] && (_ = 0)), _) try {
+            if (f = 1, y && (t = op[0] & 2 ? y["return"] : op[0] ? y["throw"] || ((t = y["return"]) && t.call(y), 0) : y.next) && !(t = t.call(y, op[1])).done) return t;
+            if (y = 0, t) op = [op[0] & 2, t.value];
+            switch (op[0]) {
+                case 0: case 1: t = op; break;
+                case 4: _.label++; return { value: op[1], done: false };
+                case 5: _.label++; y = op[1]; op = [0]; continue;
+                case 7: op = _.ops.pop(); _.trys.pop(); continue;
+                default:
+                    if (!(t = _.trys, t = t.length > 0 && t[t.length - 1]) && (op[0] === 6 || op[0] === 2)) { _ = 0; continue; }
+                    if (op[0] === 3 && (!t || (op[1] > t[0] && op[1] < t[3]))) { _.label = op[1]; break; }
+                    if (op[0] === 6 && _.label < t[1]) { _.label = t[1]; t = op; break; }
+                    if (t && _.label < t[2]) { _.label = t[2]; _.ops.push(op); break; }
+                    if (t[2]) _.ops.pop();
+                    _.trys.pop(); continue;
+            }
+            op = body.call(thisArg, _);
+        } catch (e) { op = [6, e]; y = 0; } finally { f = t = 0; }
+        if (op[0] & 5) throw op[1]; return { value: op[0] ? op[1] : void 0, done: true };
+    }
+};
+import { loadColourSession, persistColourSession } from "./colour-sensor-diagnostics";
+import { readColourSensorHardware, readColourSensorReadiness, readColourSensorRegister, wakeColourSensor } from "./colour-sensor-registers";
+import { createColourCalibrationRecorder, recordColourCalibrationEvent } from "./colour-calibration-records";
+import { lockColourSensorOperation } from "./colour-sensor-operation";
+var keyFor = function (sensor) { return "marty-colour-calibration-pending:".concat(JSON.stringify([sensor.raftId, sensor.key])); };
+var cached = new Map();
+var checking = new WeakSet();
+var checks = new WeakMap();
+var ColourCalibrationReconnectError = /** @class */ (function (_super) {
+    __extends(ColourCalibrationReconnectError, _super);
+    function ColourCalibrationReconnectError(reason) {
+        var _this = _super.call(this, "calibrationReloadFailed") || this;
+        _this.reason = reason;
+        return _this;
+    }
+    return ColourCalibrationReconnectError;
+}(Error));
+export { ColourCalibrationReconnectError };
+export var getPendingColourCalibration = function (sensor) {
+    var key = keyFor(sensor);
+    try {
+        var value = localStorage.getItem(key);
+        if (!value) {
+            cached.delete(key);
+            return null;
+        }
+        var parsed = JSON.parse(value);
+        if (typeof parsed.connectionInstanceId !== "string" || typeof parsed.serialNumber !== "string" ||
+            !/^[a-f0-9]{16}$/.test(parsed.whiteCalibrationHex))
+            throw new Error("Invalid pending calibration");
+        cached.set(key, parsed);
+        return parsed;
+    }
+    catch (_a) {
+        // Never unlock a known pending calibration just because storage becomes unavailable.
+        return cached.get(key) || null;
+    }
+};
+export var markColourCalibrationPending = function (sensor, serialNumber, whiteCalibrationHex, calibrationRecord) {
+    var pending = { connectionInstanceId: sensor.raft.connectionInstanceId || "", serialNumber: serialNumber, whiteCalibrationHex: whiteCalibrationHex, calibrationRecord: calibrationRecord };
+    restorePendingColourCalibration(sensor, pending);
+};
+export var restorePendingColourCalibration = function (sensor, pending) {
+    localStorage.setItem(keyFor(sensor), JSON.stringify(pending));
+    cached.set(keyFor(sensor), pending);
+};
+export var clearPendingColourCalibration = function (sensor) {
+    localStorage.removeItem(keyFor(sensor));
+    cached.delete(keyFor(sensor));
+};
+/** Read-only completion check, shared by browsers and native WebViews through the existing REST bridge. */
+export var finishColourCalibrationReconnect = function (sensor, signal) { return __awaiter(void 0, void 0, void 0, function () {
+    var pending, instanceId, release, pendingKey, connectionChecks, previousCheck, check, record, checkActive, session, recorder, ref, linked, readiness, power, hardware, white, latest, state, addon;
+    return __generator(this, function (_a) {
+        switch (_a.label) {
+            case 0:
+                pending = getPendingColourCalibration(sensor);
+                if (!pending)
+                    return [2 /*return*/, true];
+                instanceId = sensor.raft.connectionInstanceId;
+                // A fresh packet, repeated verification, or a different selected robot is not a reconnect.
+                if (!instanceId || instanceId === pending.connectionInstanceId)
+                    return [2 /*return*/, false];
+                // Add-ons have one raw response slot. Independent mounted panels must not overwrite each other's commands.
+                if (checking.has(sensor.raft))
+                    return [2 /*return*/, false];
+                release = lockColourSensorOperation(sensor.raft);
+                if (!release)
+                    return [2 /*return*/, false];
+                checking.add(sensor.raft);
+                pendingKey = JSON.stringify(pending);
+                connectionChecks = checks.get(sensor.raft);
+                if (!connectionChecks) {
+                    connectionChecks = new Map();
+                    checks.set(sensor.raft, connectionChecks);
+                }
+                previousCheck = connectionChecks.get(sensor.key);
+                check = (previousCheck === null || previousCheck === void 0 ? void 0 : previousCheck.pending) === pendingKey ? previousCheck :
+                    { pending: pendingKey, calibrationRecord: pending.calibrationRecord };
+                connectionChecks.set(sensor.key, check);
+                record = function (reason, data) {
+                    if (!check.calibrationRecord || (check.loggedReason === reason && Date.now() - check.loggedAtMs < 30000))
+                        return;
+                    check.loggedReason = reason;
+                    check.loggedAtMs = Date.now();
+                    // Upload problems must never turn a successful hardware check into a failed calibration.
+                    try {
+                        recordColourCalibrationEvent(check.calibrationRecord, "reconnectCheck", __assign({ reason: reason, connectionInstanceId: instanceId, expectedSerialNumber: pending.serialNumber, expectedWhiteCalibrationHex: pending.whiteCalibrationHex, readyAtMs: check.readyAtMs }, data));
+                    }
+                    catch ( /* The upload queue reports its own failures. */_a) { /* The upload queue reports its own failures. */ }
+                };
+                checkActive = function () {
+                    var _a;
+                    var current = window.applicationManager.connectedRafts[sensor.raftId];
+                    if (signal.aborted || document.hidden || current !== sensor.raft || !current.isVerified ||
+                        !((_a = sensor.raft.raftStateInfo) === null || _a === void 0 ? void 0 : _a.addOnInfo.addons.some(function (addon) { return addon.id === sensor.addon.id && addon.name === sensor.addon.name; }))) {
+                        throw new Error("cancelled");
+                    }
+                };
+                _a.label = 1;
+            case 1:
+                _a.trys.push([1, , 6, 7]);
+                checkActive();
+                // Older app versions saved pending settings without an upload reference. Log their reconnect too.
+                if (!check.calibrationRecord) {
+                    try {
+                        session = loadColourSession();
+                        persistColourSession(session);
+                        recorder = createColourCalibrationRecorder(sensor, session);
+                        ref = { sessionId: recorder.sessionId, attemptId: recorder.attemptId };
+                        check.calibrationRecord = ref;
+                        linked = __assign(__assign({}, pending), { calibrationRecord: ref });
+                        try {
+                            restorePendingColourCalibration(sensor, linked);
+                            Object.assign(pending, linked);
+                            pendingKey = check.pending = JSON.stringify(linked);
+                        }
+                        catch ( /* The in-memory check can still upload when pending-record storage is unavailable. */_b) { /* The in-memory check can still upload when pending-record storage is unavailable. */ }
+                        recorder.record("reconnectStarted", { reconnectOnly: true, expectedSerialNumber: pending.serialNumber,
+                            expectedWhiteCalibrationHex: pending.whiteCalibrationHex, connectionInstanceId: instanceId });
+                    }
+                    catch ( /* Logging must not prevent read-only hardware confirmation. */_c) { /* Logging must not prevent read-only hardware confirmation. */ }
+                }
+                return [4 /*yield*/, readColourSensorReadiness(sensor, signal, checkActive)];
+            case 2:
+                readiness = _a.sent();
+                if (readiness.status !== "ok" || !readiness.value) {
+                    // A new initialization cycle on this connection invalidates the previous freshness reference.
+                    if (readiness.status === "ok")
+                        check.readyAtMs = undefined;
+                    record("initialising", { readiness: readiness });
+                    return [2 /*return*/, false];
+                }
+                // Keep the first confirmed initialization time. Polling must not keep moving the freshness target.
+                if (check.readyAtMs === undefined)
+                    check.readyAtMs = readiness.receivedAtMs;
+                return [4 /*yield*/, wakeColourSensor(sensor, signal, checkActive)];
+            case 3:
+                power = _a.sent();
+                if (power.status !== "ok") {
+                    record("sensorWakeUnavailable", { readiness: readiness, power: power });
+                    return [2 /*return*/, false];
+                }
+                return [4 /*yield*/, readColourSensorHardware(sensor, signal, checkActive)];
+            case 4:
+                hardware = _a.sent();
+                if (hardware.status !== "ok" || !hardware.value.serialNumber || hardware.value.commsOk === 0) {
+                    record("hardwareReadUnavailable", { readiness: readiness, power: power, hardware: hardware });
+                    return [2 /*return*/, false];
+                }
+                if (JSON.stringify(getPendingColourCalibration(sensor)) !== pendingKey)
+                    return [2 /*return*/, false];
+                if (hardware.value.serialNumber !== pending.serialNumber) {
+                    record("sensorChanged", { hardware: hardware });
+                    throw new ColourCalibrationReconnectError("calibrationSensorChanged");
+                }
+                return [4 /*yield*/, readColourSensorRegister(sensor, "4020", signal, checkActive)];
+            case 5:
+                white = _a.sent();
+                checkActive();
+                latest = getPendingColourCalibration(sensor);
+                if (!latest || JSON.stringify(latest) !== pendingKey)
+                    return [2 /*return*/, false];
+                if (white.status !== "ok") {
+                    record("whiteReadUnavailable", { hardware: hardware, whiteCalibration: white });
+                    return [2 /*return*/, false];
+                }
+                if (white.value !== pending.whiteCalibrationHex) {
+                    record("settingsChanged", { hardware: hardware, whiteCalibration: white });
+                    throw new ColourCalibrationReconnectError("calibrationSettingsChanged");
+                }
+                state = sensor.raft.raftStateInfo;
+                addon = state.addOnInfo.addons.find(function (candidate) { return candidate.id === sensor.addon.id && candidate.name === sensor.addon.name; });
+                if (state.addOnInfoValidMs < check.readyAtMs || Date.now() - state.addOnInfoValidMs > 1500 ||
+                    state.addOnInfoValidMs > Date.now() || (addon.status !== undefined && !(addon.status & 0x80))) {
+                    record("waitingForTelemetry", { hardware: hardware, whiteCalibration: white, receivedAtMs: state.addOnInfoValidMs, sensor: addon });
+                    return [2 /*return*/, false];
+                }
+                clearPendingColourCalibration(sensor);
+                if (check.calibrationRecord) {
+                    try {
+                        recordColourCalibrationEvent(check.calibrationRecord, "reconnectCompleted", {
+                            connectionInstanceId: instanceId,
+                            hardware: hardware,
+                            whiteCalibration: white, readyAtMs: check.readyAtMs,
+                            receivedAtMs: state.addOnInfoValidMs, sensor: addon,
+                        });
+                    }
+                    catch ( /* Hardware confirmation remains valid if logging fails. */_d) { /* Hardware confirmation remains valid if logging fails. */ }
+                }
+                return [2 /*return*/, true];
+            case 6:
+                checking.delete(sensor.raft);
+                release();
+                return [7 /*endfinally*/];
+            case 7: return [2 /*return*/];
+        }
+    });
+}); };

package/dist-types/src/utils/colour-calibration-records.d.ts

@@ -0,0 +1,21 @@
+import type { ColourSensor, ColourSession } from "./colour-sensor-diagnostics";
+export type CalibrationRecordRef = {
+    sessionId: string;
+    attemptId: string;
+};
+export type CalibrationRecorder = CalibrationRecordRef & {
+    record: (type: string, data: Record<string, unknown>) => void;
+};
+/** Immutable event IDs allow safe retries after an unknown HTTP outcome or a reload. */
+export declare const recordColourCalibrationEvent: (ref: CalibrationRecordRef, type: string, data: Record<string, unknown>, metadata?: Record<string, unknown>, sequence?: number) => void;
+export declare const getColourCalibrationUploadState: (sessionId: string) => {
+    pendingCount: number;
+    inMemoryOnly: boolean;
+    temporaryStorage: boolean;
+    uploading: boolean;
+    error: string;
+};
+export declare const subscribeColourCalibrationRecords: (listener: () => void) => () => void;
+export declare const flushColourCalibrationRecords: () => Promise<void>;
+export declare const startColourCalibrationRecordSync: () => () => void;
+export declare const createColourCalibrationRecorder: (sensor: ColourSensor, session: ColourSession) => CalibrationRecorder;