refactor(state): type the day camera-usage helpers under strict TS

Converts state/cameraUsage.js to strict .ts (behavior-preserving). Public functions
(inferredCameraKeys / referencedCameraKeys / resolveDayCameraUsage → Camera[] /
findCameraAffectedDays) and the cameraKey helper are typed; raw animal/day inputs stay
`unknown` (permissive, per the shape-safe-boundary convention).

- Reads the day collections through the typed selectors (getDayTasks /
  getDayAssociatedVideos / getDayFsGuiYamls) instead of inline
  `Array.isArray(day?.x) ? day.x : []` — behavior-equivalent (the selectors ARE that
  guard) and removes raw `day?.x` access under the `unknown` input.
- task.camera_id is widened back to `unknown` (`const cameraId: unknown = task?.camera_id`)
  so the stray-scalar tolerance stays live per the type, not just at runtime.
- Two small documented reads remain: FsGuiYaml's interface omits `camera_id` (a
  pre-existing type gap; that field is read tolerantly via a cast), and
  `refs.has(cameraKey(...) as string)` preserves the exact `has(null) → false` runtime
  behavior without adding a redundant null branch.

No .ts consumers (workspaceUtils/CamerasContainer/CamerasUsedSection are JS), so the
rename is transparent. Verified: typecheck clean, cameraUsage suite (20) + golden
baselines (145) byte-identical, full suite 4793, CI=true build clean, e2e 104.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: edeno

.claude/docs/research/architecture-assessment.md

@@ -36,7 +36,7 @@ or enforced tokens** (F6), and **deferred lint debt that weakens the build gate*
 
 | Gap | Evidence | Why it bites refactoring |
 | --- | --- | --- |
-| **No static types** ⏳ PARTIAL | Incremental TS underway (`tsc --noEmit` CI gate live): `io/yaml.ts`, `state/workspaceTypes.ts` + the task-catalog modules, `domain/deviceOverrideMerge.ts`, and the Phase-9a validation leaf modules (`repairRouting`/`geometryProvenance`/`dayOverrideValidation`/`stepStatus`) are `.ts` under `strict`; the **entire `validation/` directory** (leaf predicates + `rules/*` families + `rulesValidation` composer + `index`/`schemaValidation`/`rawShape`/`quickChecks`/`useQuickChecks` + the shared `issueTypes.ts`) is now `.ts` under `strict`; the `state/` migration is underway — the persistence layer (`state/workspaceMigrations.ts` + `state/persistence.ts`) the canonical read layer (`state/workspaceSelectors.ts`, `unknown`-in / typed-container-out), and a first selector-consumer (`state/configDiff.ts`) are `.ts`. Remaining: most of `state/` (`workspaceUtils`/`workspaceTransitions`/`workspaceActions`/…) + `domain/`, most components, `useWorkspace`, and the legacy form path stay JS (`checkJs:false`) | Rename a domain fn or change an `Animal`/`Day` shape → **silent until a test happens to exercise it.** No safe IDE rename, no null-safety. Tooling agent scored type-safety **2/10** (improving as the pure core converts). |
+| **No static types** ⏳ PARTIAL | Incremental TS underway (`tsc --noEmit` CI gate live): `io/yaml.ts`, `state/workspaceTypes.ts` + the task-catalog modules, `domain/deviceOverrideMerge.ts`, and the Phase-9a validation leaf modules (`repairRouting`/`geometryProvenance`/`dayOverrideValidation`/`stepStatus`) are `.ts` under `strict`; the **entire `validation/` directory** (leaf predicates + `rules/*` families + `rulesValidation` composer + `index`/`schemaValidation`/`rawShape`/`quickChecks`/`useQuickChecks` + the shared `issueTypes.ts`) is now `.ts` under `strict`; the `state/` migration is underway — the persistence layer (`state/workspaceMigrations.ts` + `state/persistence.ts`) the canonical read layer (`state/workspaceSelectors.ts`, `unknown`-in / typed-container-out), and the first selector-consumers (`state/configDiff.ts`, `state/cameraUsage.ts`) are `.ts`. Remaining: most of `state/` (`workspaceUtils`/`workspaceTransitions`/`workspaceActions`/…) + `domain/`, most components, `useWorkspace`, and the legacy form path stay JS (`checkJs:false`) | Rename a domain fn or change an `Animal`/`Day` shape → **silent until a test happens to exercise it.** No safe IDE rename, no null-safety. Tooling agent scored type-safety **2/10** (improving as the pure core converts). |
 | **Oversized files/components** ⏳ PARTIAL | ~~`domain/validation.js` 1142~~ ✅ split (Phase 9a) into routing/provenance/producers/composer/step-status modules · ~~`validation/rulesValidation.js` 1108~~ ✅ split into `validation/rules/*` families (reference / opto / channelMap / electrodeGroup / dandiSubject / identity / behavioralEvent) + a 96-LOC composer · `valueList.js` 1073 · ~~`ValidationSummary/index.jsx` 1033~~ ✅ decomposed (Phase 9c-1) into rows-helpers / batch-action hook / ExportReport / BatchExportPreflight / DayStatusTable (index now 306) · ~~`DevicesStep.jsx` 825~~ ✅ decomposed (Phase 9c-3) into CamerasUsedSection / OverrideCleanupSection / ConfigVersionPanel / ElectrodeGroupsAccordion (step now 424) · `OptogeneticsFields.jsx` 826 · ~~`RecordingDaysTab.jsx` 822~~ ✅ decomposed (Phase 9c-2) into AnimalSetupCard / ExistingDataReview / DayList / DuplicateDayModal (tab now 496) · ~~`useWorkspace.js` 851~~ ✅ split into `workspaceActions` (createWorkspaceActions factory) / `useWorkspacePersistence` (status + autosave + saveNow) / `workspaceHydration` (resolveInitialWorkspace) + a pure `getAnimalDays` in `workspaceSelectors` (hook now 98) | High intrinsic load to change; many concerns per file; merge-conflict magnets. |
 | **~2,000 LOC legacy dead-weight** | `OptogeneticsFields.jsx` (826, imported only by `LegacyFormView`), `element/*`, `*Fields`, `LegacyFormView.jsx` — parallel to the workspace path | Every workspace UX/styling change risks needing a legacy twin; or the legacy code rots unmaintained. |
 | **CSS: no scoping, partial tokens** (= F6) | Global CSS, `.button-primary` redefined in 6 files, two different error icons, ~60% token adoption, mixed `.css`/`.scss` | Visual inconsistency *and* fragile edits — changing a shared style can leak across components. |

CHANGELOG.md

@@ -9,6 +9,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- **Typed the day camera-usage helpers under strict TS (refactor only, no behavior change).**
+  [state/cameraUsage.js](src/state/cameraUsage.ts) → `.ts`: `inferredCameraKeys` / `referencedCameraKeys`
+  / `resolveDayCameraUsage` (→ `Camera[]`) / `findCameraAffectedDays` and the `cameraKey` helper are
+  typed (`unknown` for the raw animal/day inputs). The day collections are now read through the typed
+  selectors (`getDayTasks` / `getDayAssociatedVideos` / `getDayFsGuiYamls`) instead of inline
+  `Array.isArray(day?.x) ? day.x : []` — behavior-equivalent and removes the raw `day?.x` access.
+  `task.camera_id` is read back as `unknown` to keep the stray-scalar tolerance honest. Two small,
+  documented reads remain: the `FsGuiYaml` interface omits `camera_id` (a pre-existing type gap — that
+  field is read tolerantly), and `refs.has(cameraKey(...) as string)` keeps the exact `has(null) →
+  false` behavior without a redundant null branch. cameraUsage suite (20) + golden baselines pass;
+  `npm run typecheck` + `CI=true` build clean; full suite 4793; e2e 104.
+
 - **Typed the probe-config diff utility under strict TS (refactor only, no behavior change).**
   [state/configDiff.js](src/state/configDiff.ts) → `.ts`: `diffProbeConfigs` now returns the defined
   `ProbeConfigDiff` and consumes the newly-typed selectors (`getProbeElectrodeGroups` → `ElectrodeGroup[]`,

src/state/cameraUsage.js src/state/cameraUsage.tssrc/state/cameraUsage.js renamed to src/state/cameraUsage.ts

@@ -18,16 +18,22 @@
  * (the export bridge) and by the camera edit/correction blast-radius UI.
  */
 
-import { getAnimalCameras, getDayCamerasUsed } from './workspaceSelectors';
+import {
+  getAnimalCameras,
+  getDayCamerasUsed,
+  getDayTasks,
+  getDayAssociatedVideos,
+  getDayFsGuiYamls,
+} from './workspaceSelectors';
+import type { Camera } from './workspaceTypes';
 
 /**
  * Normalize a camera id to a comparison key so a numeric `1` and a string `"1"` match (corrupt
  * imports can carry either). Returns null for an absent id.
  *
- * @param {*} id
- * @returns {string|null}
+ * @param id
  */
-function cameraKey(id) {
+function cameraKey(id: unknown): string | null {
   return id === null || id === undefined ? null : String(id);
 }
 
@@ -40,32 +46,33 @@ function cameraKey(id) {
  * uncheck a camera they only explicitly added, so the disabled decision must ignore `cameras_used`.
  * Shape-tolerant: non-array collections and null/undefined ids are skipped, never thrown on.
  *
- * @param {object} day - A recording-day record.
- * @returns {Set<string>} Normalized camera-id keys inferred from task/video/fs-gui references.
+ * @param day - A recording-day record.
+ * @returns Normalized camera-id keys inferred from task/video/fs-gui references.
  */
-export function inferredCameraKeys(day) {
-  const keys = new Set();
-  const add = (id) => {
+export function inferredCameraKeys(day: unknown): Set<string> {
+  const keys = new Set<string>();
+  const add = (id: unknown): void => {
     const key = cameraKey(id);
     if (key !== null) keys.add(key);
   };
 
-  const tasks = Array.isArray(day?.tasks) ? day.tasks : [];
-  for (const task of tasks) {
-    // task.camera_id is normally an array, but tolerate a stray scalar.
-    const ids = Array.isArray(task?.camera_id)
-      ? task.camera_id
-      : task?.camera_id !== undefined && task?.camera_id !== null
-        ? [task.camera_id]
+  for (const task of getDayTasks(day)) {
+    // task.camera_id is normally an array, but tolerate a stray scalar (raw corruption), so read
+    // it as `unknown` rather than the canonical `string[]`.
+    const cameraId: unknown = task?.camera_id;
+    const ids: unknown[] = Array.isArray(cameraId)
+      ? cameraId
+      : cameraId !== undefined && cameraId !== null
+        ? [cameraId]
         : [];
     ids.forEach(add);
   }
 
-  const videos = Array.isArray(day?.associated_video_files) ? day.associated_video_files : [];
-  for (const video of videos) add(video?.camera_id);
+  for (const video of getDayAssociatedVideos(day)) add(video?.camera_id);
 
-  const fsGui = Array.isArray(day?.fs_gui_yamls) ? day.fs_gui_yamls : [];
-  for (const protocol of fsGui) add(protocol?.camera_id);
+  // FsGuiYaml's type omits `camera_id` (the interface predates the FsGUI camera field that
+  // trodes_to_nwb + the `dangling_camera_ref` rule read), so read it tolerantly.
+  for (const protocol of getDayFsGuiYamls(day)) add((protocol as { camera_id?: unknown })?.camera_id);
 
   return keys;
 }
@@ -78,10 +85,10 @@ export function inferredCameraKeys(day) {
  * the cameras-used CHECKBOX disabled/hint decision use `inferredCameraKeys` instead, so an
  * explicitly-added camera stays uncheckable.
  *
- * @param {object} day - A recording-day record.
- * @returns {Set<string>} Normalized camera-id keys.
+ * @param day - A recording-day record.
+ * @returns Normalized camera-id keys.
  */
-export function referencedCameraKeys(day) {
+export function referencedCameraKeys(day: unknown): Set<string> {
   const keys = inferredCameraKeys(day);
 
   // UNION the explicit per-day "cameras used" set on top of the inferred references. For existing
@@ -108,26 +115,29 @@ export function referencedCameraKeys(day) {
  * matches ids by exact type, so it can only be MORE eager to block than this String-normalized
  * resolver), so a dangling reference never reaches a real export file.
  *
- * @param {object} animal - The owning animal (read shape-safely via `getAnimalCameras`).
- * @param {object} day - The recording day.
- * @returns {Array<object>} The day-used camera objects, in catalog order.
+ * @param animal - The owning animal (read shape-safely via `getAnimalCameras`).
+ * @param day - The recording day.
+ * @returns The day-used camera objects, in catalog order.
  */
-export function resolveDayCameraUsage(animal, day) {
+export function resolveDayCameraUsage(animal: unknown, day: unknown): Camera[] {
   const refs = referencedCameraKeys(day);
   if (refs.size === 0) return [];
-  return getAnimalCameras(animal).filter((camera) => refs.has(cameraKey(camera?.id)));
+  // `cameraKey` is `string | null`, but a null key is never present in `refs` (it is skipped when
+  // building the set), so `has(null)` is always false at runtime — the `as string` keeps that exact
+  // behavior without a redundant null branch.
+  return getAnimalCameras(animal).filter((camera) => refs.has(cameraKey(camera?.id) as string));
 }
 
 /**
  * Blast-radius helper: the ids of the given days that reference `cameraId`. Used to enumerate the
  * affected days before an "apply this camera correction to the N days using it" action (the
  * immutable-once-referenced rule), and never folded into the single-day export helper above.
  *
- * @param {Array<object>} days - Recording-day records to scan.
- * @param {*} cameraId - The camera id to look for.
- * @returns {Array<*>} The ids of days that reference the camera, in input order.
+ * @param days - Recording-day records to scan.
+ * @param cameraId - The camera id to look for.
+ * @returns The ids of days that reference the camera, in input order.
  */
-export function findCameraAffectedDays(days, cameraId) {
+export function findCameraAffectedDays(days: unknown, cameraId: unknown): unknown[] {
   const key = cameraKey(cameraId);
   if (key === null) return [];
   return (Array.isArray(days) ? days : [])