diff --git a/docs/ARCHITECTURE.md b/docs/ARCHITECTURE.md index e038147..870a65c 100644 --- a/docs/ARCHITECTURE.md +++ b/docs/ARCHITECTURE.md @@ -62,11 +62,14 @@ flowchart LR | `src/features/scan/hooks/scanViewScanActions.ts` | Manual scan and visible-grid scan orchestration | | `src/features/scan/hooks/scanViewEntryActions.ts` | Guided auto-entry choreography for visible inventory, direct inventory, and IK-style fallback paths | | `src/features/scan/hooks/useScanGoodInterop.ts` | Scan-page GOOD import/export actions against renderer repository ports | +| `src/features/inventory/*` | Planned scanned-artifact inventory, compact result list/grid, filters, and artifact detail views | | `src/lib/artifactOcrParser.ts` | Converts OCR output into a parsed artifact candidate with confidence and notes | | `src/lib/fuzzyMatch.ts` | Generic fuzzy string matching for OCR text against known game data | | `src/lib/genshinLookup.ts` | Pure lookup and validation API for generated Genshin data | | `src/lib/autoScanEntry.ts` | Pure entry-mode planning and auto-scan preflight validation | | `src/lib/cardReadyGate.ts` | Detail/page fingerprint readiness gate for scan timing | +| `src/lib/artifactEvaluation.ts` | Planned deterministic artifact value evaluation with score reasons and review-safe output | +| `src/lib/upgradeProjection.ts` | Planned best/middle/worst upgrade projection for under-leveled artifacts | | `src/lib/scoring.ts` | Recommendation and build scoring logic | | `src/lib/demoData.ts` | Temporary local demo snapshot | | `src/data/genshinGameData.json` | Generated local dictionary of characters, artifact sets, slots, and stats | @@ -116,6 +119,9 @@ sequenceDiagram | OCR crops | Electron main | Electron main | Details modal, parser | | Game dictionary | `genshin-db` generated JSON | `src/data/genshinGameData.json` | OCR parser | | Parsed artifact candidate | OCR parser | Renderer domain logic | Result panel, future local DB | +| Scan result entry | Scan loop and parser/evaluator | Renderer domain logic | Live scan rail, artifact inventory, summary | +| Artifact evaluation | Deterministic evaluator | `src/lib` | Result pills, inventory sort/filter, detail reasons | +| Upgrade projection | Projection helper | `src/lib` | Artifact detail view only | | Review samples | User action in Scan UI | Electron userData `review-samples.jsonl` | Future regression tests and OCR training | | Stored artifacts | Manual/automatic scans | Electron userData `artifact-store.json` (dedupe by content signature) | Future triage, recommendations, SQLite migration | | Recommendations | Scoring module | Renderer domain logic | Triage and builds views | @@ -173,6 +179,58 @@ Auto-scan artifact captures also bypass Electron source-list enumeration and use the GDI capture helper directly once the selected source/Genshin state has been preflighted. Manual captures and source refresh still use `desktopCapturer`. +## Scan Results And Inventory UX + +The next product surface is documented in +[scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md). +Architecture rules: + +- The active scan view is an operator surface, not the full evaluator. It should + show the screenshot/preview, the right-side live result rail, Stop/status + controls, and review access. +- The live result rail receives completed artifact results only. Intermediate + OCR/debug stats stay in diagnostics or detail. +- A scan result row preserves extraction status and artifact value status as + separate data even when the UI shows one compact pill. +- The artifact inventory view owns browsing, filtering, sorting, and opening + detail. +- The artifact detail view owns screenshot/crop inspection, OCR confidence, + parser notes, value score reasons, and upgrade projection. +- Upgrade projection is a local deterministic/probabilistic helper, never a + claim that an artifact will roll a specific way. + +Planned result flow: + +```mermaid +flowchart LR + ScanLoop["Scan loop"] + Parsed["Parsed artifact"] + ReviewGate["Extraction confidence / review gate"] + Value["Artifact value evaluator"] + Store["Artifact store"] + Rail["Live result rail"] + Inventory["Artifact inventory"] + Detail["Artifact detail"] + + ScanLoop --> Parsed + Parsed --> ReviewGate + ReviewGate --> Value + Value --> Store + Value --> Rail + Store --> Inventory + Rail --> Detail + Inventory --> Detail +``` + +Future queue refactor: + +- One capture/game-control worker may click, scroll, focus, and poll failsafes. +- OCR/parse/evaluation may process bounded queued screenshot/crop jobs. +- Queueing must preserve stop behavior, duplicate handling, review decisions, + and the existing read-only safety boundary. +- The queue refactor is secondary to content extraction and result/inventory + contracts while current scan speed remains acceptable. + ## Security And Safety | Area | Policy | @@ -198,3 +256,5 @@ The app keeps a Tesseract.js worker pool, can use the Inventory-Kamera `genshin_fast_09_04_21.traineddata` path for comparison, and reports capture, OCR, card-ready, scroll-ready, active-scan, and projected-100 timings. A default engine change requires a same-capture benchmark and a qualified live soak result. +For the next product phase, performance work should not displace extraction +quality, result clarity, or review safety unless evidence shows a regression. diff --git a/docs/CHECKLISTS.md b/docs/CHECKLISTS.md index 49387a6..9be9445 100644 --- a/docs/CHECKLISTS.md +++ b/docs/CHECKLISTS.md @@ -42,6 +42,21 @@ - [ ] Desktop viewport is checked manually. - [ ] `npm run build` passes. +## Scan Results And Inventory UX + +- [ ] The scan page keeps preview, Stop/status, and the live result rail visible without page-level scrolling. +- [ ] The live rail shows finished artifact rows only, not intermediate OCR/debug state. +- [ ] Each live row has scan number, artifact name or compact fallback, value score, and a short status pill. +- [ ] Extraction confidence and artifact value remain separate in the data model. +- [ ] Low-confidence or conflicting reads show `Review` instead of a normal weak/strong value decision. +- [ ] Duplicate state is represented separately from artifact quality. +- [ ] The artifact inventory view can browse stored scan results without opening diagnostics. +- [ ] Inventory filters/sorting cover review, score, set, slot, equipped, locked, and newest scan where data exists. +- [ ] Artifact detail shows screenshot/crop, parsed fields, OCR confidence, parser notes, value reasons, and review state. +- [ ] Upgrade projection, if shown, is labeled as a projection and includes worst/middle/best cases. +- [ ] Unit tests cover score/status derivation and projection edge cases when those modules change. +- [ ] Scanner safety rules and existing quality gates are unchanged. + ## Parser Or Scoring Change - [ ] Known-good OCR samples still parse correctly. @@ -56,3 +71,21 @@ - [ ] App starts outside browser preview. - [ ] Smart Capture bridge is available. - [ ] No generated debug artifacts are included accidentally. + +## Git Merge And Gitea Push + +- [ ] `git status --short --branch` is checked before switching branches, + committing, merging, or pushing. +- [ ] Work is committed on the intended feature branch before merging into + `main`. +- [ ] Merge into `main` uses fast-forward when possible, or a deliberate merge + commit when the history requires it. +- [ ] `main` is clean before push except for explicitly ignored or deliberately + untracked local files. +- [ ] `git remote -v` points to the intended Gitea remote before pushing. +- [ ] Gitea HTTPS credentials are stored through Git Credential Manager, not in + repository files or remote URLs. +- [ ] If authentication fails, refresh the credential using + [GITEA_AUTH.md](GITEA_AUTH.md), then rerun the same `git push`. +- [ ] After push, `git status --short --branch` shows `main...origin/main` + without ahead/behind drift. diff --git a/docs/CONVENTIONS.md b/docs/CONVENTIONS.md index 9c688c1..a18c0b2 100644 --- a/docs/CONVENTIONS.md +++ b/docs/CONVENTIONS.md @@ -22,8 +22,11 @@ This document defines project engineering standards. ## 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 dark purple fintech glassmorphism with premium, focused controls. - Disable buttons when their required data does not exist. @@ -52,3 +55,8 @@ This document defines project engineering standards. - 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`. diff --git a/docs/DECISIONS.md b/docs/DECISIONS.md index 3bd4108..77500fc 100644 --- a/docs/DECISIONS.md +++ b/docs/DECISIONS.md @@ -17,6 +17,7 @@ This document contains Architecture Decision Records. | ADR-009 | Resolution-anchored layout profiles and OCR preprocessing over color detection | Accepted | 2026-07-05 | | ADR-010 | Elevated dev runner and bounded live automation probes | Accepted | 2026-07-07 | | ADR-011 | Quality-gated Inventory Kamera comparison before OCR default changes | Accepted | 2026-07-07 | +| ADR-012 | Separate live scan results, artifact inventory, and value evaluation | Accepted | 2026-07-09 | ## ADR-001: Build A Local Electron App First @@ -339,3 +340,60 @@ winner and a complete `current` vs. `ik-traineddata` comparison. - The validated `:wait` scan scripts are acceptable for manual post-UAC startup; non-waiting scripts remain useful when automation should fail fast. - The goal remains open until the 100-artifact qualified comparison is captured. + +## ADR-012: Separate Live Scan Results, Artifact Inventory, And Value Evaluation + +### Status + +Accepted + +### Context + +The visible-inventory scanner baseline is fast enough for the current product +phase. The next user value comes from better artifact content extraction and a +clearer surface for scanned artifacts, not from another broad speed pass. + +The scan page currently has more diagnostic/result detail than the operator +needs during a live scan. Showing every stat, confidence value, and evaluation +while the scanner is running makes the main workspace noisy and increases the +risk that a user treats uncertain OCR as a final artifact judgment. + +The desired product flow is: + +- left side: screenshot/preview, +- right side: compact live list of finished artifact results, +- later menu item: browsable scanned artifact inventory, +- click-through detail: screenshot, parsed stats, OCR confidence, evaluation + reasons, and upgrade projection. + +### Decision + +Adopt a split scan/result/inventory model: + +- The active scan page shows the latest screenshot/preview and a compact live + result rail. +- The live rail shows only scan number, artifact name or compact fallback, + artifact value score `0-100`, and a result pill after evaluation has finished. +- Extraction confidence and artifact value are separate data concepts. A low + confidence read becomes `Review`; it must not be silently displayed as a + normal weak artifact. +- Debug stats, raw OCR, confidence breakdowns, and detailed evaluation belong in + diagnostics, scan summary, or artifact detail. +- Add a scanned artifact inventory view for browsing, filtering, sorting, and + opening details. +- Add artifact detail evaluation before promoting broad recommendations. +- Add upgrade projection only as a detail-level feature, with worst/middle/best + projected value scores and clear uncertainty labeling. +- Keep the producer/consumer screenshot queue as a later implementation phase: + one game-control worker may click/scroll/capture, while OCR/parse/evaluation + workers can process bounded queued jobs once the UI/data contracts are stable. + +### Consequences + +- The scan page becomes calmer and more task-focused. +- The app can surface useful artifact outcomes without hiding OCR uncertainty. +- Inventory and detail views become the natural place for richer analysis. +- Recommendation work has a cleaner dependency chain: trusted scans, compact + results, artifact inventory, detail evaluation, then build recommendations. +- Speed work remains possible, but it is secondary unless measured timings show + a real regression. diff --git a/docs/GITEA_AUTH.md b/docs/GITEA_AUTH.md index 3412cc1..64d2746 100644 --- a/docs/GITEA_AUTH.md +++ b/docs/GITEA_AUTH.md @@ -1,4 +1,4 @@ -# Gitea authentication +# Gitea Authentication Remote: @@ -13,7 +13,8 @@ https://git.noveria.net/user/settings/applications ``` Use the token as the HTTPS password when Git asks for credentials. Do not save -tokens, passwords, or generated credentials in this repository. +tokens, passwords, or generated credentials in this repository, in `.env` +files, or in the remote URL. On Windows, this repository uses Git Credential Manager from the system Git config: @@ -28,3 +29,24 @@ Credential Manager or let Git Credential Manager prompt again during: ```powershell git push origin main ``` + +Recommended push check: + +```powershell +git status --short --branch +git remote -v +git push origin main +git status --short --branch +``` + +Expected clean result after a successful push: + +```text +## main...origin/main +``` + +If Git reports `Failed to authenticate user`, do not change the remote to embed +a token. Open the token page above, create or refresh a token with repository +write access, clear the stale Windows credential for `git.noveria.net` if +needed, and rerun the same push command so Git Credential Manager can store the +new credential safely. diff --git a/docs/PROJECT.md b/docs/PROJECT.md index b32e968..ff4e4b7 100644 --- a/docs/PROJECT.md +++ b/docs/PROJECT.md @@ -5,14 +5,17 @@ This document is the source of truth for project intent, scope, runtime facts, a For implementation structure, see [ARCHITECTURE.md](ARCHITECTURE.md). For engineering standards, see [CONVENTIONS.md](CONVENTIONS.md). For the latest Inventory-Kamera comparison work, see [scanner-ik-progress-report.md](scanner-ik-progress-report.md). +For the next scan-result and artifact-inventory product phase, see +[scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md). For the 2026-07-09 scanner merge evidence, see [MERGE_READINESS.md](MERGE_READINESS.md). +For Gitea push/authentication setup, see [GITEA_AUTH.md](GITEA_AUTH.md). ## Project Identity | Field | Value | | --- | --- | | Project name | Genshin Artifact Assistant | -| Status | Scanner baseline merged to `main`; repeatability, corpus growth, and recommendation work are next | +| Status | Scanner baseline merged to `main`; scan result rail, artifact inventory, extraction quality, and corpus growth are next | | Platform | Windows desktop | | Target users | Genshin Impact players who want artifact decisions without complex optimizer setup | | Runtime | Electron app with React UI and TypeScript | @@ -29,6 +32,9 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin - Build one local canonical Genshin data package for artifact sets, pieces, slots, stats, and characters. - Parse artifact name, slot, main stat, substats, set, equipped state, and confidence deterministically against that package. - Save weak or failed reads automatically as review samples and turn corrections into reusable local fixes. +- Present finished scan results as a compact artifact list instead of a debug-heavy live stats surface. +- Keep extraction confidence separate from artifact value so uncertain OCR becomes review, not a misleading low score. +- Provide a browsable local artifact inventory with detail views before promoting broader recommendations. - Keep the app offline-first and usable without Genshin Optimizer, Inventory Kamera, Enka, or HoYoLAB. - Re-introduce recommendations only after the scanner base is trustworthy. @@ -54,6 +60,9 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin | FR-009 | Provide account-level artifact triage after scanner trust is acceptable. | Should | Pending | | FR-010 | Provide 1-3 simple build suggestions per character from owned artifacts after scanner trust is acceptable. | Should | Pending | | FR-011 | Farming overlay for reward scans. | Later | Prototype shell | +| FR-012 | Show active scan results as a minimal right-side rail with artifact number, name or compact fallback, value score, and status pill. | Should | Planned | +| FR-013 | Provide a scanned artifact inventory view with compact score pills, filters, sorting, and click-through detail. | Should | Planned | +| FR-014 | Provide artifact detail evaluation with screenshot/crops, parsed fields, OCR confidence, value reasons, and optional upgrade projection. | Should | Planned | ## Non-Functional Requirements @@ -64,6 +73,7 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin | IK target | First 100 artifacts should scan with accuracy at least as good as Inventory Kamera and equal or better speed. | `npm run scan:goal:compare:validated` or `npm run scan:goal:compare:validated:wait` quality-gated report | | Privacy | Captures and parsed data stay local by default. | No remote upload in scanner path | | Reliability | Uncertain OCR must be visible to the user. | Confidence and details view | +| Score integrity | Extraction confidence and artifact value are separate concepts. | Review state can block or qualify a value score | | Learning loop | Scanner mistakes should become reusable local review samples. | `review-samples.jsonl` | | Maintainability | Scanner heuristics must be isolated and documented. | Parser tests, scan-loop tests, data generator, review sample pipeline | @@ -128,8 +138,11 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin 2026-07-08. - OCR quality is still inconsistent enough that some fields are recovered by fallback and derivation more often than they should be. - Learned fixes currently focus on text replacements; they do not yet update crop offsets, UI profile variants, or scanner targeting rules in a structured way. -- The scan page is cleaner than before, but it still exposes too much operator/debug state in the main flow. -- Recommendations and build logic exist, but the scanner is not yet reliable enough to make them the core focus. +- The scan page is cleaner than before, but it still needs the next minimalist + result-rail pass so the main flow shows preview plus completed artifact + outcomes instead of live diagnostic/stat content. +- Recommendations and build logic exist, but artifact inventory, detail review, + and value scoring should land first so recommendations have trustworthy inputs. - The latest source has completed the final current-vs-IK-traineddata live comparison for this environment. Repeatability and 3 artifacts/second are still open. @@ -140,9 +153,10 @@ The app has crossed from OCR-demo/prototype into a validated scanner baseline on `main`. The current merge-ready path is the visible-inventory scan flow: the operator opens Artifact inventory with a visible detail card, the app verifies the state, scans read-only, persists parsed artifacts, and keeps uncertain data -reviewable. The next product phase is not another broad scanner rewrite; it is -repeatability, corpus growth, UI polish, and then recommendations on top of the -trusted artifact store. +reviewable. The next product phase is not another broad speed rewrite; current +speed is acceptable for now. The priority is better content extraction, a +minimal scan-result rail, a browsable artifact inventory, detail evaluation, and +corpus growth before recommendations become the core product surface. ## Product Direction @@ -151,6 +165,11 @@ trusted artifact store. - Team building stays out of the critical path until artifact ingestion is stable. - Inventory Kamera remains a reference for scan choreography and page movement, not a runtime dependency. - Self-learning stays deterministic and local first: review samples, aliases, crop offsets, and UI profile tuning before any ML retraining discussion. +- The scan workspace should be an operator surface: preview, live result rail, + Stop, status, and review access. Detailed stats and debug evidence belong in + diagnostics, summaries, or artifact detail. +- Artifact value scoring must not hide OCR uncertainty. `Review` is a distinct + outcome, not just a weak artifact score. ## Execution Plan @@ -270,31 +289,69 @@ Status: crop adjustment proposals, and UI-profile adjustment proposals. Crop/profile changes still require live review before being auto-applied. -### Phase 6 - Recommendations come back on top of a trusted scanner +### Phase 6 - Minimal scan result rail and artifact inventory + +Outcome: +- The scan page shows a large screenshot/preview and a compact right-side rail + of finished artifact evaluations. +- Each row shows scan number, artifact name or compact fallback, value score, + and a colored status pill. +- Debug stats, confidence breakdowns, and OCR internals move out of the main + scan surface. +- A new artifact inventory menu provides compact browsing, filters, sorting, + and click-through details. + +Status: +- Planned. See + [scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md) + for the implementation phases and acceptance criteria. + +### Phase 7 - Artifact detail evaluation and upgrade projection + +Outcome: +- Artifact detail explains parsed fields, OCR confidence, scoring reasons, and + review needs. +- Upgrade projection is available only when enough data is known and is labeled + as probabilistic, with worst/middle/best projected value scores. +- Low-confidence OCR disables or qualifies value conclusions instead of showing + false certainty. + +Status: +- Planned after the scan result rail and inventory data contracts. + +### Phase 8 - Recommendations come back on top of a trusted scanner Outcome: - Account snapshot and build suggestions are only promoted once scan quality is high enough to trust owned artifacts. - Recommendations explain uncertainty and surface conflicts instead of pretending perfect certainty. Status: -- Next major product area after repeatability and corpus work. Do not promote - recommendation UX until stored artifact quality is backed by more confirmed - review samples and repeat live scan runs. +- Next major product area after inventory, detail evaluation, repeatability, and + corpus work. Do not promote recommendation UX until stored artifact quality is + backed by more confirmed review samples and repeat live scan runs. ## Immediate Next Implementation Order 1. Keep the visible-inventory scanner path as the production baseline and avoid promoting `auto-entry`, `direct-inventory`, or `paimon-menu` until they pass their own low-limit live validations. -2. Grow the confirmed OCR corpus from review samples exported by +2. Implement the scan result and inventory data contracts from + [scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md), + preserving separate extraction confidence and artifact value. +3. Rework the scan page into preview plus minimal result rail; keep diagnostic + stats out of the primary scan surface. +4. Add the artifact inventory menu and detail view before expanding broad build + recommendations. +5. Grow the confirmed OCR corpus from review samples exported by `npm run eval:review-candidates` and prepared through `npm run eval:prepare-confirmed`. -3. Repeat live scanner runs in later sessions to prove repeatability across +6. Repeat live scanner runs in later sessions to prove repeatability across pages, locked/unlocked artifacts, equipped footers, and duplicate handling. -4. Continue the optional `3 artifacts/second` work only if the next change can +7. Continue the optional `3 artifacts/second` work only if the next change can reduce OCR/capture transport time without weakening quality gates. -5. Start recommendation/product UX work only after repeat scan quality and - confirmed corpus coverage are strong enough to trust stored artifacts. +8. Start recommendation/product UX work only after inventory/detail evaluation, + repeat scan quality, and confirmed corpus coverage are strong enough to trust + stored artifacts. ## Open Questions @@ -303,4 +360,6 @@ Status: | Is the current C# helper sufficient for production packaging, or does a later Rust/C++ sidecar still materially reduce latency or packaging risk? | Open | | When should UI-profile learning be allowed to change crop geometry automatically versus requiring review approval? | Open | | What scan-quality threshold is high enough before recommendations should be considered user-facing again? | Open | +| What exact first-pass value formula should drive the `0-100` artifact score before build-aware recommendations exist? | Open | +| Which upgrade projection model is honest enough for early UX: deterministic roll buckets, probability-weighted outcomes, or a deliberately simple best/middle/worst estimate? | Open | | Which Genshin UI languages should be supported after English once the scanner contract is stable? | Open | diff --git a/docs/scanner-ik-progress-report.md b/docs/scanner-ik-progress-report.md index 9014cba..96fb033 100644 --- a/docs/scanner-ik-progress-report.md +++ b/docs/scanner-ik-progress-report.md @@ -366,7 +366,11 @@ Expected bottleneck sequence: 4. Repeat equipped/locked live samples in later sessions if confidence or UI behavior changes, but the first positive locked proof has passed. 5. Keep recommendations secondary until scanner quality remains stable across - repeated live sessions. + repeated live sessions and the result rail, artifact inventory, and detail + evaluation flow are implemented. +6. Treat current speed as acceptable for the next product phase; prioritize + artifact content extraction and review-safe value scoring before another + broad speed pass. ## Definition of Done for the IK Target diff --git a/docs/scanner-results-inventory-roadmap.md b/docs/scanner-results-inventory-roadmap.md new file mode 100644 index 0000000..554d4c9 --- /dev/null +++ b/docs/scanner-results-inventory-roadmap.md @@ -0,0 +1,270 @@ +# 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: + +```mermaid +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. diff --git a/docs/scanner-rework-status.md b/docs/scanner-rework-status.md index 3989cd1..43f6fe9 100644 --- a/docs/scanner-rework-status.md +++ b/docs/scanner-rework-status.md @@ -4,6 +4,8 @@ Progress on the approved scanner/OCR rework. See ADR-007/008/009/010 in [DECISIONS.md](DECISIONS.md) for the decisions behind these. For the current live automation runbook, see [AUTOMATION_LIVE_SCAN.md](AUTOMATION_LIVE_SCAN.md). +For the next result/inventory product phase, see +[scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md). ## Current Scanner Status @@ -35,6 +37,10 @@ Current status after the 2026-07-09 merge to `main`: equipped characters (`Citlali`, `Linnea`), unlocked artifacts reported `locked: false`, a visibly locked artifact reported `locked: true`, and a bounded auto-scan persisted the locked/equipped state. +- Current speed is acceptable for the next product phase. The next work should + prioritize correct artifact content extraction, a minimal live result rail, + scanned artifact inventory, detail evaluation, and review-safe value scoring + before another broad speed pass. ## Done (implemented, unit-tested, build green) @@ -223,7 +229,26 @@ Current status after the 2026-07-09 merge to `main`: pixels because Electron's native bitmap channel order was ambiguous in live captures. -## Remaining — needs the live environment or a UI pass +## Next product phase - result rail and inventory + +The next implementation pass is planned in +[scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md). +Summary: + +1. Add result data contracts that preserve extraction confidence separately from + artifact value score. +2. Rework the scan view into screenshot/preview plus a compact right-side live + result rail. +3. Add a scanned artifact inventory menu with minimal list/grid rows and + score/review pills. +4. Add click-through artifact detail with screenshot/crops, parsed fields, OCR + confidence, value reasons, and review state. +5. Add upgrade projection later as a detail-only feature with worst/middle/best + cases and explicit uncertainty. +6. Defer the full screenshot queue/worker pipeline until the result/inventory + contracts are stable or timing evidence shows the current loop is the blocker. + +## Remaining - needs the live environment or a UI pass These cannot be finished/validated without Genshin running at the user's resolution or without UI work best tested live: