# Carve classColors.ts out of 06_annotations into its own component dir

**Task**: AZ-511_classcolors_carve_out
**Name**: classColors carve-out to dedicated component (closes F3)
**Description**: Move `src/features/annotations/classColors.ts` to its own component directory `src/class-colors/` with a barrel; update the four consumer import paths to go through the barrel; remove the STC-ARCH-01 F3-pending exemption; clean up the five coupled documentation/script callouts. Closes the High Architecture baseline finding F3 and eliminates the carry-forward exemption surface logged in `LESSONS.md` ("5 coupled places").
**Complexity**: 3 points
**Dependencies**: AZ-485 (Public API barrels + STC-ARCH-01) — the F3 exemption only exists because AZ-485 landed; this task lives on top of that boundary.
**Component**: 11_class-colors (gains a physical home); 06_annotations (loses the misplaced file from its owns-glob); 03_shared-ui (consumer); plus three doc/script artifacts.
**Tracker**: AZ-511
**Epic**: AZ-509

## Problem

Baseline finding **F3** (`_docs/02_document/architecture_compliance_baseline.md`): `src/features/annotations/classColors.ts` is a Layer 0 / 1 shared kernel logically owned by component `11_class-colors`, but it physically sits inside `06_annotations`'s owns-glob. Re-exporting it through the `06_annotations` barrel would create a runtime circular import:

```
AnnotationsPage → DetectionClasses (03_shared-ui) → 06_annotations barrel → AnnotationsPage
```

So after AZ-485 landed the per-component barrel architecture, F3 became visible. The workaround documented in `_docs/02_document/module-layout.md` Layout Rule #3 leaves the file in place and adds an exemption regex to `scripts/check-arch-imports.mjs` so consumers can deep-import `'../features/annotations/classColors'` without tripping STC-ARCH-01.

The exemption is correct but expensive — it lives in **five coupled places**, captured as a lesson on 2026-05-12:

1. `scripts/check-arch-imports.mjs` — `EXEMPT_RE` allowing the deep import.
2. `tests/architecture_imports.test.ts` — fixture asserting the exemption holds.
3. `src/features/annotations/index.ts` — 7-line carry-over comment block explaining why classColors is NOT re-exported here.
4. `_docs/02_document/components/11_class-colors/description.md` — Caveats §7 "Physical location is misplaced today" + Module Inventory's "physical location pending refactor" suffix.
5. `_docs/02_document/module-layout.md` — Layout Rule #3 exemption clause + Per-Component Mapping for `11_class-colors` ("Directories: none today...") + Verification Needed #1 + `shared/class-colors` proposed section + `06_annotations` Owns clause ("EXCEPT `classColors.ts`").

Every contributor reading any one of those touches the exemption — and the lesson explicitly warns that the carry-over **never silently drifts** because each touchpoint is enforced (static check, unit test, doc, layout rule). The cost is real ongoing tax; closing F3 removes all of it at once.

## Outcome

- `classColors.ts` lives at its logical layer (`src/class-colors/classColors.ts`) with a proper barrel (`src/class-colors/index.ts`); consumers import from the barrel (`'../class-colors'` or `'../../class-colors'`) like every other component.
- The STC-ARCH-01 exemption regex disappears from `scripts/check-arch-imports.mjs` and from the architecture test fixture; running `bun run --bun scripts/check-arch-imports.mjs --mode=arch-imports` finds zero deep imports anywhere in `src/`.
- The five coupled doc/script callouts above are simplified: each reflects the new physical home; none reference an exemption.
- `bun run build` succeeds with no runtime circular-import warnings (the original concern is gone because `class-colors` is no longer a subtree of `06_annotations`).
- `architecture_compliance_baseline.md` F3 row reads **CLOSED** with the task and commit reference, mirroring the AZ-485 → F4 and AZ-486 → F7 patterns.

## Scope

### Included

**Source changes**

- Create directory `src/class-colors/` containing:
  - `classColors.ts` — exact byte-for-byte copy of `src/features/annotations/classColors.ts` (12-color palette, 12 fallback names, `getClassColor`, `getPhotoModeSuffix`, `getClassNameFallback`, `FALLBACK_CLASS_NAMES` — no behaviour change).
  - `index.ts` — re-exports the four public symbols: `getClassColor`, `getClassNameFallback`, `getPhotoModeSuffix`, `FALLBACK_CLASS_NAMES`.
- Delete `src/features/annotations/classColors.ts`.
- Update 4 consumer imports (currently shown by `rg classColors src/`):
  - `src/components/DetectionClasses.tsx` — `from '../features/annotations/classColors'` → `from '../class-colors'`.
  - `src/features/annotations/CanvasEditor.tsx` — `from './classColors'` → `from '../../class-colors'`.
  - `src/features/annotations/AnnotationsSidebar.tsx` — `from './classColors'` → `from '../../class-colors'`.
  - `src/features/annotations/AnnotationsPage.tsx` — `from './classColors'` → `from '../../class-colors'`.
- Drop the "classColors symbols are NOT re-exported here" comment block from `src/features/annotations/index.ts` (lines 5-12 of the current file).

**Script + test changes**

- Remove the F3-pending exemption from `scripts/check-arch-imports.mjs` (the `EXEMPT_RE` entry covering `features/annotations/classColors`).
- Update `tests/architecture_imports.test.ts` so the fixture asserting the exemption is either deleted (preferred) or rewritten to assert "no exemptions remain". Whichever shape, the test must still pass and continue to catch regressions.

**Documentation changes**

- `_docs/02_document/module-layout.md`:
  - Layout Rule #3 — drop the "One F3-pending exemption" clause.
  - Per-Component Mapping for `11_class-colors` — `Directories: src/class-colors/**` (not "none today"); `Public API exported from src/class-colors/index.ts` (not "no barrel today").
  - Verification Needed #1 — mark as RESOLVED with task reference.
  - `## Shared / Cross-Cutting` → `### shared/class-colors` block — remove the workaround note about READ-ONLY for `06_annotations` tasks.
  - Per-Component Mapping for `06_annotations` — drop the "EXCEPT `classColors.ts`" clause from Owns.
- `_docs/02_document/components/11_class-colors/description.md` — Caveats §7 "Physical location is misplaced today" → rewrite as "Physical location: `src/class-colors/`" with the historical note moved to a single line citing the closing task; Module Inventory path updated.
- `_docs/02_document/architecture_compliance_baseline.md` — F3 row gets the CLOSED marker (same shape as F4, F7), with task + commit hash placeholder for the implementer to fill at merge time.

### Excluded

- Moving `CanvasEditor.tsx` (Finding F2 — different cross-feature edge; separate task).
- Creating `src/shared/` (Finding F6 — distinct decision; deliberately NOT used as the target so this task doesn't pre-empt F6 design).
- Changing the `classColors.ts` API surface — pure file move + import-path updates. The dead `??` guard noted in `11_class-colors/description.md` §5 stays dead; the redundancy with `DetectionClass.photoMode` stays unaddressed; both are Step 4/5 review items, not this task.
- Renaming any of the four exported symbols.
- Adding `localization` for the suffix strings (Step 4 i18n item; separate concern).

## Acceptance Criteria

**AC-1: File physically lives at new location**
Given the repository after the task lands
When `ls src/class-colors/`
Then it contains `classColors.ts` and `index.ts`; running `find src/features/annotations -name classColors.ts` returns no results.

**AC-2: Consumers import via barrel**
Given the four consumer files (`DetectionClasses.tsx`, `CanvasEditor.tsx`, `AnnotationsSidebar.tsx`, `AnnotationsPage.tsx`)
When their imports are inspected
Then each imports from `'../class-colors'` or `'../../class-colors'` (the barrel), not from `'.../classColors'` (the file).

**AC-3: Architecture static check has zero exemptions**
Given the codebase after the task lands
When `bun run --bun scripts/check-arch-imports.mjs --mode=arch-imports` runs
Then the exit code is 0; the `EXEMPT_RE` block in the script contains no entry for `classColors`; `tests/architecture_imports.test.ts` passes without referencing a classColors exemption.

**AC-4: Build succeeds with no circular-import warnings**
Given the codebase after the task lands
When `bun run build` runs
Then it succeeds; Vite output contains no "Circular dependency" warnings involving `class-colors`, `annotations`, or `DetectionClasses`.

**AC-5: Full test suite green**
Given the codebase after the task lands
When `bun run test` runs
Then all previously-passing tests still pass — including `tests/detection_classes.test.tsx` (AZ-472), `tests/architecture_imports.test.ts`, and any test that imports a consumer file.

**AC-6: Documentation is consistent**
Given the codebase after the task lands
When the 5 coupled doc/script touchpoints are inspected
Then `module-layout.md`, `11_class-colors/description.md`, `architecture_compliance_baseline.md`, `src/features/annotations/index.ts`, and `scripts/check-arch-imports.mjs` all reflect the new physical home; no surviving reference describes classColors as "physically misplaced", "F3-pending", or "exempt".

## Non-Functional Requirements

**Compatibility**: zero runtime behaviour change. Bundle size is identical (same exported symbols, same implementation). Bundle composition shifts by one chunk boundary but tree-shaking preserves dead-code-elimination semantics.

**Reliability**: the structural fix removes a long-standing risk that a new contributor accidentally re-introduces the circular import by re-exporting classColors from the 06_annotations barrel. After this task lands, that re-export becomes legal but no longer creates a cycle (because class-colors is its own component).

## Unit Tests

| AC Ref | What to Test | Required Outcome |
|--------|--------------|------------------|
| AC-1 | `import { getClassColor } from '../class-colors'` | resolves to the new file; `getClassColor(0)` returns the same hex as today |
| AC-2 | Static scan of import declarations in the 4 consumers | every import is via barrel; no file-path import remains |
| AC-3 | Architecture test fixture (`tests/architecture_imports.test.ts`) | passes after the F3 exemption fixture is removed |
| AC-5 | All existing classColors-touching tests | unchanged assertions, all green |

## Blackbox Tests

| AC Ref | Initial Data/Conditions | What to Test | Expected Behavior | NFR References |
|--------|------------------------|--------------|-------------------|----------------|
| AC-4 | Clean clone, `bun install` complete | `bun run build` | succeeds; no circular-import warnings | Reliability |
| AC-2 + AC-3 | Clean clone, `bun install` complete | `bun run --bun scripts/check-arch-imports.mjs --mode=arch-imports` | exit 0; no exemption block matches classColors | — |
| AC-5 | Clean clone, `bun install` complete | `bun run test` | full suite passes | — |

## Constraints

- The file move must be a single atomic commit (or one PR's worth of commits). Splitting "move file" from "update imports" creates a broken intermediate state where neither path works.
- The new directory name is `src/class-colors/` — kebab-case, matching every other component dir established by AZ-485. Do NOT use `src/classColors/` (camel-case) or `src/shared/class-colors/` (opens F6).
- The barrel must re-export ALL four current public symbols. Dropping `FALLBACK_CLASS_NAMES` (currently used by `DetectionClasses.tsx` for the empty-state fallback row) would break the consumer.
- The `EXEMPT_RE` regex literal in `scripts/check-arch-imports.mjs` may be a single combined pattern — read the script first to understand its shape before editing.

## Risks & Mitigation

**Risk 1: A consumer was missed**
- *Risk*: A test file, story, or sample (`tests/**`, `e2e/**`, `_docs/02_document/modules/*.md`) imports `classColors` from the old path and breaks after the move.
- *Mitigation*: Before deletion, `rg "features/annotations/classColors" .` from the repo root. Every match outside `_docs/` is a consumer that must be updated. Doc references inside `_docs/` are addressed in the documentation changes above.

**Risk 2: Vite hot-module resolution caches the old path**
- *Risk*: After the move, a stale dev-server HMR session continues to resolve `'../features/annotations/classColors'` from cache.
- *Mitigation*: Cold-restart `bun run dev` after the move. CI is unaffected.

**Risk 3: A circular import resurfaces from a different direction**
- *Risk*: A future contributor re-introduces a circle by importing something from `06_annotations` inside `src/class-colors/classColors.ts`. The new physical separation doesn't make all circles impossible.
- *Mitigation*: Out of scope for this task. The general "no cross-component deep imports" rule (STC-ARCH-01) is already in place and now applies to `class-colors` symmetrically; that's the standing protection.

**Risk 4: The architecture test fixture deletion loses regression coverage**
- *Risk*: The current `tests/architecture_imports.test.ts` fixture asserts that the exemption WORKS. Deleting the fixture removes that regression check; if a future change accidentally re-introduces a similar exemption, the test won't catch it.
- *Mitigation*: Replace the fixture with a stronger assertion: "no `EXEMPT_RE` entries match any path under `src/`". That keeps the safety net while removing the F3-specific coupling.

## References

- `_docs/02_document/architecture_compliance_baseline.md` — F3 (High / Architecture); to be marked CLOSED on completion.
- `_docs/02_document/module-layout.md` — Layout Rule #3, Per-Component Mapping `11_class-colors`, `06_annotations`, Verification Needed #1, `## Shared / Cross-Cutting` → `### shared/class-colors`.
- `_docs/02_document/components/11_class-colors/description.md` — Caveats §7, Module Inventory.
- `_docs/LESSONS.md` — 2026-05-12 architecture lesson on the 5-coupled-places exemption pattern.
- `_docs/02_tasks/done/AZ-485_refactor_public_api_barrels.md` — establishes the per-component barrel pattern this task extends.
