Fix installed vision hardware diagnostics

Author: supermang617

app/camera-state.js

@@ -3,6 +3,10 @@ export function cameraErrorMessage(error) {
   const message = String(error?.message || error || "").trim();
   const normalized = `${name} ${message}`.toLowerCase();
 
+  if (name === "CameraDeviceUnavailableError" || normalized.includes("could not open a usable camera")) {
+    return "Camera devices were found, but Iris could not open a usable camera. Close other camera apps and check Windows camera privacy or driver settings, then try again.";
+  }
+
   if (
     name === "NotFoundError" ||
     normalized.includes("requested device not found") ||
@@ -27,3 +31,84 @@ export function cameraErrorMessage(error) {
 
   return message || "Camera snapshot failed.";
 }
+
+export function rankCameraDevice(device) {
+  const label = String(device?.label || "").toLowerCase();
+  let score = 0;
+
+  if (label.includes("windows studio effects")) {
+    score += 120;
+  }
+  if (label.includes("brio") || label.includes("webcam")) {
+    score += 90;
+  }
+  if (label.includes("camera")) {
+    score += 40;
+  }
+  if (label.includes("front")) {
+    score += 8;
+  }
+  if (label.includes("ir") || label.includes("infrared") || label.includes("depth")) {
+    score -= 120;
+  }
+  if (!label) {
+    score -= 20;
+  }
+
+  return score;
+}
+
+export function cameraDiagnosticLabel(device, index) {
+  const label = String(device?.label || "").trim();
+  return label || `Camera ${index + 1}`;
+}
+
+export function buildCameraCapturePlan(devices, videoConstraints) {
+  const baseVideoConstraints = { ...videoConstraints };
+  const attempts = [
+    {
+      attemptId: "default",
+      label: "Default camera",
+      constraints: {
+        audio: false,
+        video: baseVideoConstraints
+      }
+    }
+  ];
+
+  const rankedDevices = Array.from(devices || [])
+    .map((device, index) => ({ device, index, score: rankCameraDevice(device) }))
+    .filter(({ device }) => device?.kind === "videoinput" && device.deviceId)
+    .sort((left, right) => right.score - left.score || left.index - right.index);
+
+  for (const { device, index } of rankedDevices) {
+    attempts.push({
+      attemptId: `device-${index}`,
+      label: cameraDiagnosticLabel(device, index),
+      constraints: {
+        audio: false,
+        video: {
+          ...baseVideoConstraints,
+          deviceId: { exact: device.deviceId }
+        }
+      }
+    });
+  }
+
+  return attempts;
+}
+
+export function cameraAttemptDiagnostic(attempt, error) {
+  return {
+    attemptId: String(attempt?.attemptId || "unknown"),
+    label: String(attempt?.label || "Unknown camera"),
+    errorName: String(error?.name || "Error"),
+    errorMessage: String(error?.message || error || "Camera attempt failed.")
+  };
+}
+
+export function createCameraUnavailableError() {
+  const error = new Error("Camera devices were found, but Iris could not open a usable camera.");
+  error.name = "CameraDeviceUnavailableError";
+  return error;
+}

app/camera-state.test.mjs

@@ -1,6 +1,12 @@
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { cameraErrorMessage } from "./camera-state.js";
+import {
+  buildCameraCapturePlan,
+  cameraAttemptDiagnostic,
+  cameraErrorMessage,
+  createCameraUnavailableError,
+  rankCameraDevice
+} from "./camera-state.js";
 
 test("camera errors show no-camera guidance instead of raw DOM exceptions", () => {
   assert.equal(
@@ -26,3 +32,52 @@ test("busy camera errors show close-other-apps guidance", () => {
 test("unknown camera errors preserve useful details", () => {
   assert.equal(cameraErrorMessage(new Error("Camera driver crashed.")), "Camera driver crashed.");
 });
+
+test("camera fallback errors show usable device recovery guidance", () => {
+  assert.equal(
+    cameraErrorMessage(createCameraUnavailableError()),
+    "Camera devices were found, but Iris could not open a usable camera. Close other camera apps and check Windows camera privacy or driver settings, then try again."
+  );
+});
+
+test("camera ranking prefers visible usable cameras over IR cameras", () => {
+  assert.ok(
+    rankCameraDevice({ label: "Windows Studio Effects Camera" }) >
+      rankCameraDevice({ label: "Surface IR Camera Front" })
+  );
+  assert.ok(
+    rankCameraDevice({ label: "Camera MX Brio" }) >
+      rankCameraDevice({ label: "Surface Camera Front" })
+  );
+});
+
+test("camera capture plan tries default then ranked device ids", () => {
+  const plan = buildCameraCapturePlan(
+    [
+      { kind: "audioinput", label: "Microphone", deviceId: "mic-1" },
+      { kind: "videoinput", label: "Surface IR Camera Front", deviceId: "ir-1" },
+      { kind: "videoinput", label: "Windows Studio Effects Camera", deviceId: "studio-1" },
+      { kind: "videoinput", label: "Surface Camera Front", deviceId: "front-1" }
+    ],
+    { width: { ideal: 640 }, height: { ideal: 480 } }
+  );
+
+  assert.equal(plan[0].attemptId, "default");
+  assert.equal(plan[1].label, "Windows Studio Effects Camera");
+  assert.equal(plan[1].constraints.video.deviceId.exact, "studio-1");
+  assert.equal(plan.at(-1).label, "Surface IR Camera Front");
+});
+
+test("camera attempt diagnostics omit raw device ids", () => {
+  const diagnostic = cameraAttemptDiagnostic(
+    { attemptId: "device-2", label: "Surface Camera Front" },
+    new DOMException("Could not start video source", "NotReadableError")
+  );
+
+  assert.deepEqual(diagnostic, {
+    attemptId: "device-2",
+    label: "Surface Camera Front",
+    errorName: "NotReadableError",
+    errorMessage: "Could not start video source"
+  });
+});

app/main.js

@@ -11,7 +11,12 @@ import {
 } from "./attachment-state.js";
 import { requireTrustedBlobUrl } from "./attachment-url.js";
 import { latestBrowserPreview } from "./browser-preview.js";
-import { cameraErrorMessage } from "./camera-state.js";
+import {
+  buildCameraCapturePlan,
+  cameraAttemptDiagnostic,
+  cameraErrorMessage,
+  createCameraUnavailableError
+} from "./camera-state.js";
 import {
   formatDynamicContextStatus,
   parseDynamicContextCommand
@@ -1893,30 +1898,68 @@ async function captureCameraSnapshot() {
   cameraCaptureInProgress = true;
   elements.visionButton.disabled = true;
   elements.hudOutput.textContent = "Camera starting.";
-  let stream = null;
+  const videoConstraints = {
+    width: { ideal: cameraSnapshotWidth, max: cameraSnapshotWidth },
+    height: { ideal: cameraSnapshotHeight, max: cameraSnapshotHeight },
+    frameRate: { ideal: 5, max: 10 }
+  };
+  const devices = await enumerateCameraDevices();
+  const capturePlan = buildCameraCapturePlan(devices, videoConstraints);
+  const attempts = [];
   try {
-    stream = await navigator.mediaDevices.getUserMedia({
-      audio: false,
-      video: {
-        width: { ideal: cameraSnapshotWidth, max: cameraSnapshotWidth },
-        height: { ideal: cameraSnapshotHeight, max: cameraSnapshotHeight },
-        frameRate: { ideal: 5, max: 10 }
-      }
-    });
-    const snapshot = await snapshotFromStream(stream);
-    await saveCameraSnapshotDiagnostic(snapshot);
-    return snapshot;
-  } finally {
-    if (stream) {
-      for (const track of stream.getTracks()) {
-        track.stop();
+    for (const attempt of capturePlan) {
+      let stream = null;
+      try {
+        elements.hudOutput.textContent =
+          attempt.attemptId === "default"
+            ? "Camera starting."
+            : `Trying ${attempt.label}.`;
+        stream = await navigator.mediaDevices.getUserMedia(attempt.constraints);
+        const snapshot = await snapshotFromStream(stream);
+        await saveCameraSnapshotDiagnostic(snapshot, attempt, attempts.length + 1);
+        return snapshot;
+      } catch (error) {
+        attempts.push(cameraAttemptDiagnostic(attempt, error));
+      } finally {
+        if (stream) {
+          for (const track of stream.getTracks()) {
+            track.stop();
+          }
+        }
       }
     }
+
+    const error =
+      capturePlan.length > 1
+        ? createCameraUnavailableError()
+        : cameraErrorFromAttemptDiagnostic(attempts[0]);
+    await saveCameraCaptureErrorDiagnostic(error.message, attempts);
+    throw error;
+  } finally {
     cameraCaptureInProgress = false;
     elements.visionButton.disabled = false;
   }
 }
 
+function cameraErrorFromAttemptDiagnostic(attempt) {
+  const error = new Error(attempt?.errorMessage || "Camera snapshot failed.");
+  error.name = attempt?.errorName || "Error";
+  return error;
+}
+
+async function enumerateCameraDevices() {
+  if (!navigator.mediaDevices?.enumerateDevices) {
+    return [];
+  }
+
+  try {
+    return await navigator.mediaDevices.enumerateDevices();
+  } catch (error) {
+    logVoice("camera_enumerate_error", String(error));
+    return [];
+  }
+}
+
 async function snapshotFromStream(stream) {
   const video = document.createElement("video");
   video.muted = true;
@@ -1953,23 +1996,38 @@ async function snapshotFromStream(stream) {
   };
 }
 
-async function saveCameraSnapshotDiagnostic(snapshot) {
+async function saveCameraSnapshotDiagnostic(snapshot, selectedAttempt, attemptCount) {
   try {
     const diagnostic = await call("save_camera_snapshot_diagnostic", {
       imageBytes: snapshot.bytes,
       width: snapshot.width,
-      height: snapshot.height
+      height: snapshot.height,
+      selectedDeviceLabel: selectedAttempt?.label || null,
+      attemptCount
     });
     const imagePath = diagnostic.imagePath || diagnostic.image_path || "";
     logVoice(
       "camera_snapshot_diagnostic",
-      `bytes=${snapshot.bytes.length}; width=${snapshot.width}; height=${snapshot.height}; path=${imagePath}`
+      `bytes=${snapshot.bytes.length}; width=${snapshot.width}; height=${snapshot.height}; device=${selectedAttempt?.label || "unknown"}; attempts=${attemptCount}; path=${imagePath}`
     );
   } catch (error) {
     logVoice("camera_snapshot_diagnostic_error", String(error));
   }
 }
 
+async function saveCameraCaptureErrorDiagnostic(message, attempts) {
+  try {
+    const diagnostic = await call("save_camera_capture_error_diagnostic", {
+      message,
+      attempts
+    });
+    const jsonPath = diagnostic.jsonPath || diagnostic.json_path || "";
+    logVoice("camera_capture_error_diagnostic", `attempts=${attempts.length}; path=${jsonPath}`);
+  } catch (error) {
+    logVoice("camera_capture_error_diagnostic_error", String(error));
+  }
+}
+
 async function snapshotFromVideoFile(file) {
   validateVideoSize(file);
   const video = document.createElement("video");

scripts/validate_site.mjs

@@ -30,9 +30,9 @@ const sitemap = readFileSync(join(siteDir, "sitemap.xml"), "utf8");
 const llms = readFileSync(join(siteDir, "llms.txt"), "utf8");
 
 const expectedHashes = new Map([
-  ["iris-windows-installer.zip", "6c6219cde08729eb579d58fb31ac49a3f937a0f96c85f4933aa98b6283973215"],
-  ["iris-windows.zip", "843b0ff6463e2f18f78ceab4294f6f4238d7df31e7c98ebbaf4eb05ad0e4687b"],
-  ["install-iris-windows.ps1", "9ec2016adfa53e2bbd9035c2b55d149f8017f499d9e5b1550cd5191dc49f4038"],
+  ["iris-windows-installer.zip", "a38fa91c1674dd5997ac67e671cd92d49b6f519f01c4f10deccc1fc6ee3800ab"],
+  ["iris-windows.zip", "a346e276ffc08717e05634b9915006a21693b75970455e10336e3d57ce83e9fd"],
+  ["install-iris-windows.ps1", "a17c96b685c11416f6510891bad3b0c201d4ddfd014be0ea91c52b8e13f0f9cc"],
 ]);
 
 const requiredFragments = [

site/index.html

@@ -146,15 +146,15 @@ <h3 id="checksum-title">Release checksums</h3>
           <dl>
             <div>
               <dt>iris-windows-installer.zip</dt>
-              <dd><code>6c6219cde08729eb579d58fb31ac49a3f937a0f96c85f4933aa98b6283973215</code></dd>
+              <dd><code>a38fa91c1674dd5997ac67e671cd92d49b6f519f01c4f10deccc1fc6ee3800ab</code></dd>
             </div>
             <div>
               <dt>iris-windows.zip</dt>
-              <dd><code>843b0ff6463e2f18f78ceab4294f6f4238d7df31e7c98ebbaf4eb05ad0e4687b</code></dd>
+              <dd><code>a346e276ffc08717e05634b9915006a21693b75970455e10336e3d57ce83e9fd</code></dd>
             </div>
             <div>
               <dt>install-iris-windows.ps1</dt>
-              <dd><code>9ec2016adfa53e2bbd9035c2b55d149f8017f499d9e5b1550cd5191dc49f4038</code></dd>
+              <dd><code>a17c96b685c11416f6510891bad3b0c201d4ddfd014be0ea91c52b8e13f0f9cc</code></dd>
             </div>
           </dl>
           <p>

site/release-manifest.json

@@ -6,17 +6,17 @@
     {
       "name": "iris-windows-installer.zip",
       "url": "https://github.com/supermang617/IRIS/releases/download/v1/iris-windows-installer.zip",
-      "sha256": "6c6219cde08729eb579d58fb31ac49a3f937a0f96c85f4933aa98b6283973215"
+      "sha256": "a38fa91c1674dd5997ac67e671cd92d49b6f519f01c4f10deccc1fc6ee3800ab"
     },
     {
       "name": "iris-windows.zip",
       "url": "https://github.com/supermang617/IRIS/releases/download/v1/iris-windows.zip",
-      "sha256": "843b0ff6463e2f18f78ceab4294f6f4238d7df31e7c98ebbaf4eb05ad0e4687b"
+      "sha256": "a346e276ffc08717e05634b9915006a21693b75970455e10336e3d57ce83e9fd"
     },
     {
       "name": "install-iris-windows.ps1",
       "url": "https://github.com/supermang617/IRIS/releases/download/v1/install-iris-windows.ps1",
-      "sha256": "9ec2016adfa53e2bbd9035c2b55d149f8017f499d9e5b1550cd5191dc49f4038"
+      "sha256": "a17c96b685c11416f6510891bad3b0c201d4ddfd014be0ea91c52b8e13f0f9cc"
     }
   ]
 }