# Conventions

This document defines project engineering standards.

## Naming

- Use Genshin domain language where it makes behavior clearer: artifact, slot, set, main stat, substat, triage, build.
- Name booleans as predicates such as `isScanning`, `bridgeReady`, or `isGenshinCandidate`.
- Prefer explicit scanner names such as `createArtifactCrops` over generic names such as `processImage`.

## File Organization

- Keep Electron OS integration in `electron/`.
- Keep Electron `main.ts` as composition/wiring. Move durable window, file, helper, capture, OCR, or dev-control responsibilities into named modules under `electron/`.
- Keep React components in `src/`, with extraction when `App.tsx` becomes hard to review.
- Keep feature controller hooks small enough to review. If a hook owns persistence, import/export, entry choreography, scan-loop orchestration, and UI state at once, split those concerns into feature-local hooks or services.
- Keep pure domain logic in `src/lib/`.
- Keep shared contracts in `src/types/`.
- Keep generated outputs in `dist/`, `dist-electron/`, and `outputs/`.
- Keep `src/styles/global.css` as the stylesheet entrypoint. Put broad app styles in `base.css` and dev/diagnostic-only styling in `diagnostics.css` unless a more specific style module is introduced.

## UI Rules

- The scan page should prioritize the capture workspace over secondary status content.
- The active scan view should read as preview plus compact result rail, not as a dashboard of live diagnostics.
- Details and debug information belong in modals or secondary panels.
- Avoid long, overfilled cards on scanner pages.
- Do not collapse OCR/extraction confidence and artifact value into one ambiguous UI state; uncertain reads should be visibly `Review`.
- Artifact value pills should be short, stable labels backed by deterministic data, with detailed reasons behind click-through detail.
- The design direction is a premium, cinematic Galaxy system with restrained
  glass surfaces, semantic contrast, and focused controls; reuse shared tokens
  instead of feature-local state colors.
- Use skeletons for initial content layout, inline spinners for bounded work,
  and toasts only for explicit mutation outcomes. Durable progress, blockers,
  and errors stay in the owning view.
- Respect `prefers-reduced-motion`, keep focus-visible styling intact, and never
  rely on color or animation as the only status signal.
- Disable buttons when their required data does not exist.
- Route user-facing renderer copy through `src/i18n`. English is the default
  application locale; German is an explicit settings choice. Do not use an app
  language switch to imply that another Genshin OCR/capture language is
  supported.
- Keep stable `data-*` hooks for scripted renderer acceptance. Tests should not
  depend on localized visible strings when a semantic hook is available.
- A destructive-looking local-data control must say what it removes and state
  that it does not change Genshin. Require confirmation before local deletion.

## Scanner Rules

- Prefer focused crops over full-screen OCR.
- Confidence and raw OCR details must remain inspectable.
- Heuristics should fail safely into unknown fields or review notes.
- Do not add irreversible game actions.
- Treat global aliases as unsafe when the OCR text is ambiguous across pieces.
  Canonicalize a partial artifact name only when independent high-confidence
  field evidence, such as a direct slot read, leaves one valid match.
- Keep auto-entry choreography separate from scan-loop execution. Entry code may navigate to a readable artifact detail state; loop code should process verified grid targets.

## TypeScript Rules

- Keep strict type checks passing.
- Do not use `any` for capture, OCR, artifact, or recommendation contracts unless a boundary genuinely requires it.
- Parser functions should be deterministic and testable.

## Testing

- Use unit tests for parser and scoring logic.
- Use build/type checks for Electron IPC contract changes.
- Use manual Smart Capture smoke tests for crop and capture changes.
- For native timing claims, validate a complete `run-timing.json` and derive
  end-to-end time from one request-to-reconciliation interval. Never add
  overlapping capture and processing durations.
- Test local native-result removal for active-run blocking, tombstone filtering,
  raw-evidence preservation, crop-path containment, and exact Store-record
  scope.

## Documentation

- Update `docs/PROJECT.md` when product scope changes.
- Update `docs/ARCHITECTURE.md` when module boundaries or flows change.
- Add an ADR to `docs/DECISIONS.md` for durable technical trade-offs.
- Keep workflow/runbook docs linked from `docs/PROJECT.md` so future sessions
  do not depend on chat history.
- Do not store tokens, passwords, cookies, or generated credentials in project
  files. Use Git Credential Manager for Gitea HTTPS credentials; document only
  the setup path in `docs/GITEA_AUTH.md`.