genshin-assistant/docs/scanner-results-inventory-roadmap.md

Scanner Results And Artifact Inventory Roadmap

This document defines the next product phase after the validated visible-inventory scanner baseline. The scanner is already fast enough for the current milestone; the next work should improve artifact content extraction, review safety, and a minimal inventory experience that makes scanned artifacts useful.

Product Stance

• Keep the scan workspace focused on operation, not analysis.
• Keep the live preview as the dominant surface.
• Move debug metrics, OCR internals, and detailed evaluation behind details, diagnostics, or the inventory view.
• Do not merge scan confidence and artifact value into one ambiguous score.
• Treat uncertain OCR as review, not as a low-quality artifact.
• Prioritize extracting correct artifact content over another speed pass unless live timings regress materially.

Target User Flow

1. The user opens Artifact inventory in Genshin with a visible detail card.
2. The scanner runs the existing read-only visible-inventory flow.
3. The scan view shows the latest screenshot/preview on the left.
4. A compact live result rail on the right receives one row per finished artifact evaluation.
5. Each row shows only:
   • scan number,
   • artifact name or compact slot/set fallback,
   • artifact value score from 0 to 100,
   • a colored result pill.
6. After the scan, the user opens the inventory menu to browse all scanned artifacts.
7. Clicking an artifact opens a detail view with screenshot, parsed fields, OCR confidence, scoring reasons, and optional upgrade projection.

Score Contract

The UI must keep two concepts separate:

Concept	Meaning	UI behavior
Extraction confidence	How reliable the scan/OCR/parser result is.	Drives Review, warnings, and detail confidence rows.
Artifact value score	How useful the artifact appears for builds.	Drives the 0-100 value and good/mid/weak pill.

Rules:

• If extraction confidence is too low, show Review instead of a normal value decision, even when a tentative value score exists.
• If the artifact is a duplicate, show duplicate state separately from value.
• The live rail may show one compact pill, but the data model should preserve separate extractionStatus and valueStatus fields.
• Score labels should be stable and simple:

Value score	Label
90-100	Strong
70-89	Good
45-69	Mid
0-44	Weak
unknown or unsafe	Review

The exact formula can start simple and deterministic. It should explain its reasons in the detail view before it becomes a recommendation source.

Planned Pipeline Shape

The current scan loop can keep shipping while the UI and data contracts are built. A fuller producer/consumer pipeline is a later implementation step:

flowchart LR
    Capture["Single capture and game-control worker"]
    Queue["Bounded screenshot/crop queue"]
    OCR["OCR and parse workers"]
    Eval["Artifact evaluation"]
    Aggregate["Aggregator and store"]
    UI["Live rail and inventory"]

    Capture --> Queue
    Queue --> OCR
    OCR --> Eval
    Eval --> Aggregate
    Aggregate --> UI

Constraints:

• Only one worker may control Genshin input, focus, click, scroll, or failsafe polling.
• OCR/parse/evaluation workers may run concurrently on already captured screenshot/crop jobs.
• The queue must be bounded, initially around 4-8 jobs, so the scanner does not outrun retries, review decisions, or stop requests.
• The pipeline must preserve current safety rules: no memory reads, hooks, injection, game-file changes, deleting, feeding, enhancing, locking/unlocking, or spending resources.
• Do not implement the queue refactor before the result/inventory contracts are stable, unless timing evidence shows the current loop has become the blocker.

Implementation Phases

Phase 0 - Documentation and contracts

Status: prepared by this document.

Outcome:

• Product direction is documented.
• Main docs point to this roadmap.
• Acceptance criteria and checklists exist before code changes.

Phase 1 - Result data model

Outcome:

• Add a durable scan result entry model with sequence number, capture metadata, parsed artifact identity, extraction status, artifact value score, value status, duplicate/review flags, and timestamps.
• Keep existing stored artifact records compatible.
• Add tests for status derivation so low-confidence OCR cannot become a normal Good or Strong result.

Likely files:

• src/types/domain.ts
• src/types/storage.ts
• src/lib/scannerSession.ts
• src/lib/storedArtifactAdapter.ts
• src/lib/scanReviewUtils.ts

Phase 2 - Minimal live result rail

Outcome:

• Rework the scan main section into preview plus right-side result rail.
• Remove live evaluation cards and noisy stats from the primary scan area.
• Append rows only after an artifact has finished parse/evaluation.
• Keep Stop, scan status, and review access available.
• Keep debug stats in diagnostics or summary modals.

Likely files:

• src/features/scan/components/ScanMainSection.tsx
• src/features/scan/components/ScanResultCards.tsx
• src/features/scan/components/hooks/useScanMainSectionModel.ts
• src/features/scan/components/hooks/useScanResultCardsModel.ts
• src/styles/base.css

Phase 3 - Artifact inventory view

Outcome:

• Add a menu item for scanned artifact inventory.
• Show a compact, minimal list or dense grid of stored artifacts.
• Each entry shows the same score/pill language as the live rail.
• Provide filters and sorting for review, score, set, slot, equipped, locked, and newest scan.
• Avoid a marketing/landing layout; the first screen is the actual inventory.

Likely files:

• src/features/inventory/*
• src/features/layout/navigation.ts
• src/pages/app/*
• src/lib/artifactStore.ts
• repository bridge/storage files as needed

Phase 4 - Artifact detail view

Outcome:

• Clicking a live row or inventory item opens detail.
• Detail shows screenshot or detail crop when available.
• Detail lists parsed fields, OCR confidence, parser notes, extraction status, value score, and scoring reasons.
• Review-required items make the uncertainty explicit and do not present their score as final.

Likely files:

• src/features/inventory/components/*
• src/features/scan/components/modals/*
• src/lib/artifactOcrParser.ts
• src/lib/scoring.ts

Phase 5 - Artifact value evaluation

Outcome:

• Add a deterministic artifact value evaluator before promoting build recommendations.
• Explain the score through factors such as set, slot, main stat, substat quality, level, locked/equipped state, and available character/build context.
• The evaluator must accept incomplete data and return review/unknown instead of confident nonsense.

Likely files:

• src/lib/artifactEvaluation.ts
• src/lib/scoring.ts
• src/lib/substatRolls.ts
• src/lib/genshinLookup.ts
• targeted unit tests under src/lib/*.test.ts

Phase 6 - Upgrade projection

Outcome:

• For artifacts below max level, show optional projection only in detail.
• Provide worst, middle, and best projected value scores.
• Label projection as probabilistic and not a guaranteed result.
• Use known Genshin upgrade constraints and current substats; unknown or partially read data must disable or soften the projection.

Likely files:

• src/lib/upgradeProjection.ts
• src/lib/substatRolls.ts
• src/features/inventory/components/*
• parser/scoring tests

Phase 7 - Queue-based analysis pipeline

Outcome:

• Introduce a bounded screenshot/crop job queue only after the UI/data contract is stable.
• Keep one game-control worker.
• Allow OCR/parse/evaluation workers to process queued jobs.
• Preserve stop/failsafe behavior and review decisions.
• Compare throughput against the current baseline without weakening accuracy.

Likely files:

• src/lib/autoScanLoop.ts
• src/lib/scannerSession.ts
• Electron capture/OCR boundary in electron/main.ts or extracted services
• scan-loop tests and live soak scripts

Phase 8 - Recommendation promotion

Outcome:

• Promote account-level recommendations only after scan result quality, inventory browsing, detail review, and value scoring are trustworthy.
• Recommendations must reference stored artifact quality and uncertainty.

Acceptance Criteria

• The scan page still fits the primary workflow without page-level scrolling.
• The preview remains visible during active scan.
• The right rail shows finished artifact evaluations, not noisy intermediate parser/debug state.
• Review items are visibly different from weak artifacts.
• Artifact value score and extraction confidence remain separate in data.
• Inventory view can browse stored scan results without opening diagnostics.
• Detail view explains why an artifact received its score.
• Upgrade projection never implies a guaranteed future roll.
• Existing safety constraints and scan quality gates remain intact.

Validation Plan

• npm run lint
• npm test
• npm run build
• Add unit tests for score/status derivation and upgrade projection.
• For scanner-facing changes, run a low-limit visible-inventory live scan before wider validation.
• Keep npm run scan:repeatability:wait for later regression checks, not for every UI-only pass.