feat(scanner): complete localized artifact quality checkpoint

This commit is contained in:
AzuTear
2026-07-11 15:59:19 +02:00
parent 639b0b7f59
commit 8b9f948c6b
215 changed files with 35440 additions and 7273 deletions
+279 -37
View File
@@ -62,8 +62,11 @@ flowchart LR
| `electron/appWindowManager.ts` | Main window and overlay window lifecycle, menu-bar removal, dashboard focus behavior, and renderer window command delivery |
| `electron/services/inputHelper.ts` | Stable JSON protocol client for the compiled C# input/capture sidecar plus PowerShell fallback startup |
| `electron/services/inputHelperPowerShellFallback.ts` | PowerShell fallback script body for environments where the compiled helper is unavailable |
| `electron/services/nativeScannerProcessingService.ts` | Post-capture processor for native IK runs; reads crop jobs, OCRs/parses card crops, matches IK metadata, writes processing outputs, and safely loads native crop previews |
| `electron/services/nativeScannerResultWorkflowService.ts` | Authoritative promotion and review workflow for native results; reloads run state, validates edits, updates durable results/logs, and only writes the artifact store after explicit confirmation |
| `electron/services/nativeScannerProcessingService.ts` | Streaming native-result processor; tails crop jobs, runs bounded ordered OCR/parse/evaluation, publishes result deltas, writes durable processing outputs, and safely loads native crop previews |
| `electron/services/nativeScannerResultWorkflowService.ts` | Authoritative promotion, review, and local-deletion workflow for native results; reloads run state, validates edits, appends local tombstones, safely removes contained crops, and writes/removes the artifact store only after explicit confirmation |
| `electron/services/nativeScannerResultTombstones.ts` | Append-only local tombstone contract that hides removed native rows without rewriting their raw scan evidence |
| `electron/services/nativeScannerRunTiming.ts` | Atomic, first-observation timing record for request, native scanner, capture, processing, durable-result, and reconciliation milestones |
| `electron/repositories/artifactStoreRepository.ts` | Local JSON artifact-store persistence including exact single-record removal through the main-process boundary |
| `electron/services/goodFileService.ts` | Local GOOD export file writing and GOOD import file dialog/read handling |
| `electron/preload.cjs` | Safe renderer bridge exposed as `window.assistantApi` |
| `native/input-helper/IkInventoryLists.cs` | Loads and validates the vendored IK `inventorylists` feature catalog |
@@ -72,29 +75,49 @@ flowchart LR
| `src/lib/ikArtifactMatcher.ts` | Pure IK inventorylist matcher for native artifact set/piece/slot validation and GOOD key metadata |
| `src/lib/ikCatalogMatcher.ts` | Pure IK inventorylist matcher for simple weapon, character, and material names plus compact GOOD-key samples |
| `src/lib/ikScanCapabilities.ts` | Pure capability summary that separates IK catalog coverage from implemented native capture support |
| `src/lib/scanResultEntry.ts` | Pure durable scan-result entry/status helpers that keep extraction confidence separate from deferred artifact value evaluation |
| `src/lib/scanResultEntry.ts` | Pure durable scan-result entry/status helpers that keep extraction confidence separate from versioned Artifact evaluation |
| `src/App.tsx` | Thin React entry that renders the app page |
| `src/pages/AppPage.tsx` and `src/pages/app/*` | App page composition and high-level layout routing |
| `src/features/layout/*` | Scanner-first navigation, grouped workspace/tool items, shell, topbar readiness, and view-level metadata |
| `src/features/feedback/*` | Renderer-only feedback primitives: queued mutation toasts, inline spinner, and content skeletons |
| `src/features/scan/hooks/useScanViewController.ts` | Scan feature state composition and view-controller assembly |
| `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 ESC/B fallback paths |
| `src/features/scan/hooks/useScanGoodInterop.ts` | Scan-page GOOD import/export actions against renderer repository ports |
| `src/features/inventory/*` | Scanned-artifact inventory browser for native result entries, stored artifacts, filters, sorting, compact detail state, native crop preview display, and IK catalog status |
| `src/features/settings/*` | Application settings modal, including persisted renderer-language selection |
| `src/i18n/*` | Renderer locale contract, English/German message catalogs, local persistence, document-language synchronization, and translation hook |
| `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/artifactEvaluation.ts` | Deterministic legal-roll efficiency, review/unknown safety, reason codes, stored-result enrichment, and conservative 5-star Worst/Middle/Best under-level projection |
| `src/lib/buildFitContract*.ts`, `src/lib/buildFitEligibility.ts`, and `src/types/buildFit.ts` | Versioned Build-Fit facade, contract validation including source expiry, native-result input mapping, hard extraction/Review eligibility gates, conflict evidence, and score-free V1 assessment output |
| `src/lib/buildFitCombination.ts` | Deterministic score-free five-Artifact verifier for unique slots, Set-plan shapes, sourced full-build aggregate context, nested eligibility, and assignment/equipment conflicts |
| `src/lib/buildFitEvidenceRanking.ts` | Bounded, deterministic, read-only selection of up to three source-bound complete combinations; it uses Set/Main-Stat/Substat evidence only and never Roll-Efficiency or OCR confidence as a rank weight |
| `src/lib/buildFitExplicitContext.ts` | Converts a user-confirmed, session-only full-build value into a source-bound aggregate context without inferring weapon/team/rotation values |
| `src/data/buildFitProfiles.ts` | Versioned curated profile corpus with explicit target assumptions, direct source references, expiry, safe evidence thresholds, and no authority outside its documented scope |
| `src/eval/nativeScanReplay.ts` | Node-only deterministic replay/report contract for repeatedly evaluating existing native scan results without capture or input |
| `scripts/replay-native-results.ts` | CLI wrapper that locates saved scan results and writes ignored offline replay evidence |
| `scripts/validate-saved-native-runs.ts` | Read-only accepted-target validator (including 2,211) for run contracts, PNG containment, non-persistence, review provenance, deterministic evaluation, and projection boundaries |
| `scripts/analyze-native-review.ts` | Read-only reparse and reason-distribution analyzer for a saved native run, including current Review-rate gating without capture or persistence |
| `scripts/run-offline-acceptance.mjs` | Sequential non-live acceptance runner that records lint, tests, OCR/assessment, saved-run validation, package build/verification, audits, and diff-check outcomes |
| `scripts/run-packaged-builds-acceptance.mjs` | Built-renderer acceptance runner for fresh English locale, German switching, Builds state, focus, reduced motion, overflow, screenshots, diagnostics, and local-delete confirmation probing |
| `scripts/native-live-smoke.ps1` | Non-persisting native smoke runner that validates result reconciliation and complete shared-clock timing evidence |
| `scripts/verify-packaged-app.mjs` | Static and unpacked-app verifier for executable, ASAR entries, relative renderer assets, current runtime signature, preload, C# helper, IK resources, and version consistency |
| `electron/runtimePaths.ts` | Pure runtime-resource policy: packaged builds use `process.resourcesPath`; repository fallbacks exist only in development unless an explicit environment override is set |
| `src/lib/scoring.ts` | Legacy demo-only recommendation/build scorer; real local account snapshots never call it, while Build-Fit reads source-safe native evidence through its separate ranker |
| `src/lib/demoData.ts` | Temporary local demo snapshot |
| `data/ik-inventorylists/*` | 1:1 vendored Inventory Kamera inventory lists used by the native scanner data preflight and future matching |
| `src/data/genshinGameData.json` | Generated local dictionary of characters, artifact sets, slots, and stats |
| `scripts/generate-genshin-data.cjs` | Regenerates the local Genshin dictionary from `genshin-db` |
| `src/types/*` | Shared app, capture, and domain contracts |
| `src/styles/global.css` | Stylesheet entrypoint importing split style modules |
| `src/styles/base.css` | Shared application, layout, scanner workspace, modal, triage, build, and overlay styles |
| `src/styles/global.css` | Legacy stylesheet entrypoint importing the base and diagnostics modules |
| `src/styles/tokens.css` | Galaxy color, surface, typography, spacing, depth, motion, and layer tokens |
| `src/styles/motion.css` and `src/styles/feedback.css` | Focus-visible, reduced-motion, page/micro-motion, toast, spinner, and skeleton presentation |
| `src/styles/*-galaxy.css` and `src/features/inventory/inventory-galaxy.css` | Feature-scoped Galaxy shell, scanner, secondary-view, and inventory presentation |
| `src/styles/base.css` | Shared application, layout, scanner workspace, modal, triage, build, and overlay compatibility styles |
| `src/styles/diagnostics.css` | Diagnose/dev-view specific styles |
## Dependency Rules
@@ -103,7 +126,16 @@ flowchart LR
- Electron main process must not import React renderer modules.
- Pure parsing and scoring modules must not depend on Electron APIs.
- OCR uncertainty must be represented in data, not hidden in UI only.
- Feedback primitives may reflect an operation but must not become the source of
truth for scan, review, promotion, or persistence state.
- Generated folders must not be treated as source of truth.
- Application copy is rendered through the locale provider. New, missing, or
invalid persisted locale values resolve to English; German is a user-selected
renderer preference. This does not expand the English-only Genshin OCR/crop
profile.
- Local-delete flows must remain behind the Electron main-process boundary.
They may remove app-local records and contained crop files only; they must not
call the input helper or dispatch game input.
## Smart Capture Flow
@@ -139,12 +171,16 @@ sequenceDiagram
| IK inventorylists | `data/ik-inventorylists` copied from Inventory Kamera 1.4.4 | Source data package | Native scanner data preflight and future matcher |
| IK simple catalog match | IK weapon/character/material inventorylist catalog | `IkCatalogItemMatch` | Future category scanners, inventory catalog evidence |
| Game dictionary | `genshin-db` generated JSON | `src/data/genshinGameData.json` | OCR parser |
| Application locale | Local renderer storage key `gaa-ui-locale` | `src/i18n` | App shell and feature copy; defaults to English |
| Parsed artifact candidate | OCR parser | Renderer domain logic | Result panel, post-capture report, future local DB |
| IK artifact match | IK artifact inventorylist catalog | `ScanResultIkMatch` | Native post-capture review gate, scan result entry, inventory detail |
| Parser field confidence | Native post-capture parser | `ScanResultFieldConfidence` | Scan result entry, inventory detail review signal |
| Scan result entry | Scan loop or native post-capture processor | `StoredScanResultEntry` / native run `scan-results.json` | Live scan rail, artifact inventory, summary |
| Native-result tombstone | Confirmed local deletion | Native run `deleted-results.jsonl` | Native-result loaders; raw `scan-results.json` remains replay evidence |
| Native run timing | First observed lifecycle events | Native run `run-timing.json` | Live-smoke validator, diagnostics, timing reports |
| Artifact evaluation | Deterministic evaluator | `src/lib` | Result pills, inventory sort/filter, detail reasons |
| Upgrade projection | Projection helper | `src/lib` | Artifact detail view only |
| Build-Fit suggestions | Latest complete native `scan-results.json` plus explicit session context | Renderer-only Build-Fit model | Builds surface; read-only profile evidence, never legacy demo scoring |
| 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 |
@@ -161,6 +197,10 @@ sequenceDiagram
capture. Mouse movement is sent as iterated relative input deltas instead of
relying on a single absolute cursor jump. The helper verifies the cursor
reached the target and refuses to click otherwise.
- Native and PowerShell helper discovery accepts only the exact supported game
process names `GenshinImpact` and `YuanShen`. Cached HWNDs are revalidated
against that whitelist before reuse, so the assistant cannot become its own
capture/input target merely because its title contains `Genshin`.
- `npm run dev:admin` is the validated dev path for automation when elevated
input is required. The elevated PowerShell startup is handled by
`scripts/dev-admin.ps1` and logged to `outputs/admin-start/admin-dev.log`.
@@ -193,13 +233,67 @@ sequenceDiagram
changes and stabilizes.
- Scrolling sends one wheel notch per grid row with the cursor anchored over the inventory (assumption: roughly one row per notch; overlap is absorbed by dedupe, and a page without new artifacts stops the scan).
- The scan never deletes, enhances, feeds, locks, or spends anything; it only selects tiles to read them.
- Inventory cleanup is separate from game interaction: a confirmed local removal may tombstone one native scan result, delete only its contained PNG crop, and optionally remove its explicitly linked local Store record. It never invokes the input helper or changes Genshin data.
**Native IK capture scan** is the new high-speed path. It runs inside the C#
sidecar, computes a fixed 16:9 8x4 visible-inventory grid, clicks and scrolls
natively, captures the artifact detail card as PNG crops, and reports progress
through IPC/dev-control. The renderer only starts, stops, and displays status.
OCR, parsing, GOOD persistence, and artifact value evaluation are deliberately
separate follow-up stages so capture speed is not blocked by UI work.
through IPC/dev-control. The renderer starts/stops capture and starts one
downstream processor when the run directory becomes available. OCR, parsing,
review gating, and artifact value evaluation run concurrently on bounded
workers so capture speed is not blocked by UI work; GOOD persistence remains a
separate explicit action.
Before the first native Artifact click, the helper moves the cursor to the grid
anchor, sends a fixed bounded upward wheel sequence that covers the supported
2,400-item inventory capacity, and waits for the inventory to stabilize. Total,
top-reset, and active capture timings remain separate so reset cost does not
distort capture throughput. For streaming end-to-end timing, the app must use
one wall-clock span from native start through final result reconciliation;
capture and processing durations may overlap and must never be added. Genshin may be
focused once during scan startup; after that, the helper compares the actual
foreground HWND with the original Genshin HWND immediately before every click
and every wheel event. Focus loss blocks the run without refocusing or sending
further input. Stop, ESC, Enter, and F9 use the same guard path.
The bounded wheel reset remains the production start strategy. Closing or
toggling the inventory with `B` and then selecting the Artifact tab is only a
candidate experiment: it depends on the current game/menu state and an
additional coordinate click, and it has not been live benchmarked against the
accepted wheel reset. It must not replace that reset without a guarded A/B live
test that proves both reliability and a meaningful timing benefit.
### Scan Scope Resolution
The normal renderer scan starts with `{ mode: "all" }`. Before starting the
native helper it reads the inventory counter and resolves the target from the
currently owned Artifact count (`current`), never from the slot capacity
(`total`). Capacity is only a plausibility bound. A missing, invalid, or
out-of-range owned count blocks a full-inventory run instead of guessing a
target, because the native helper does not yet have a reliable end-of-list
detector.
The optional bounded scopes are normalized before they reach the helper:
- an Artifact limit becomes `min(requested artifacts, owned artifacts)`;
- a row limit becomes `min(requested rows * detected grid columns, owned
artifacts)`; the accepted 16:9 profile currently has eight columns;
- every resolved target stays within the supported 2,400-Artifact safety bound.
Scope selection is session state. A new app session returns to the full owned
inventory default rather than silently reusing an earlier partial limit.
The Artifact-limit branch has one real Settings-UI acceptance run at limit 5:
Genshin/detail/grid preflight passed; target, captured, processed, and parsed
all reached 5; review and processing errors stayed at 0; persistence remained
disabled; and the session rail showed five results. A later packaged Settings-
UI run resolved one row to eight Artifacts and completed 8/8. The packaged
full-owned-inventory run then resolved 2,211 from the OCR-owned count, captured
2,211 crops over 70 pages, and populated 2,211 session rows with live capture/
evaluation overlap. The initial 490-Review result correctly failed the 15% gate;
current-package reprocessing of the same complete corpus passed at 136 Review
(6.15%), zero errors, and zero persistence writes. Saved-run validation passed
with zero issues.
Each native run writes a self-contained run directory under app userData:
@@ -218,32 +312,99 @@ Each native run writes a self-contained run directory under app userData:
weapons, characters, and materials are catalog-only until their own capture
flows have evidence.
- `scan-results.json`: durable per-artifact result entries with capture
metadata, parsed artifact identity when available, extraction status, and
value status. Native capture currently writes `deferred` value status for
clean extraction and `review` for uncertain extraction.
- `processing-report.json`: optional post-capture OCR/parse report generated
from `capture-jobs.jsonl`. It records `queueConcurrency` for the bounded
post-capture OCR/parse worker and is non-persisting by default until native
crop OCR has live validation evidence.
metadata, parsed artifact identity, extraction status, versioned value
evaluation, reason codes, roll breakdown, and score. Clean legal Artifact
extraction writes `evaluated`; uncertain extraction writes `review`;
inconsistent/incomplete value data writes `unknown`. `deferred` remains a
compatibility state and for non-evaluated category/build context boundaries.
- `processing-report.json`: incremental and final OCR/parse report generated
from the tailed `capture-jobs.jsonl`. It records `queueConcurrency` for the
bounded worker pool and is non-persisting by default until native crop OCR
has live validation evidence.
- `run-timing.json`: atomic `native-scanner-run-timing-v1` evidence. It records
first-observed request, scanner, capture, processing, durable-result, and
result-reconciliation timestamps, then derives request-to-durable and
request-to-reconciled durations directly from those endpoints.
- `deleted-results.jsonl`: append-only tombstones for confirmed local removals.
Loaders hide tombstoned rows while preserving the original result array for
replay/audit. A tombstone can name one safely contained crop and an optional
exact linked Store record; it is not a game action.
Parsed artifacts from manual and renderer auto-scan modes are persisted into
`artifact-store.json` keyed by a content signature that excludes the equipped
character, so re-equipping updates a record instead of duplicating it. Leveling
an artifact currently creates a new record (documented limitation until
rescan-merge exists). Native IK capture currently writes card crops first; a
downstream OCR/parse processor can report parsed artifacts from those crops
without slowing capture. Store promotion remains opt-in until native crop OCR is
validated.
rescan-merge exists). Native IK capture flushes each crop job immediately; the
downstream processor tails, OCRs, parses, evaluates, and publishes that job
without waiting for the full capture target. Store promotion remains opt-in
until native crop OCR is validated.
The Inventory surface derives a dry-run promotion summary from native
`scan-results.json` entries and the local artifact store. It can show which
native artifacts are ready for explicit promotion, already stored, review-only,
or blocked, but it does not write store records by itself.
or blocked, but it does not write store records by itself. It evaluates legacy
saved results on load, displays roll-efficiency reasons, and computes
under-level projection without requiring a rescan.
During auto-scan, artifact store writes can be batched and flushed after the
click/capture/OCR loop to avoid per-artifact save/reload churn in the hot path.
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`.
### Run Timing Evidence
The timing contract is intentionally separate from scanner status polling. The
first valid timestamp for each milestone is immutable, so retries and later
renderer polls cannot rewrite a measured interval. `requestToResultsReconciledMs`
is calculated only from `requestStartedAt` to `resultsReconciledAt`; capture and
processing can overlap and are never summed to create a synthetic end-to-end
duration. A live timing claim requires all terminal markers, a valid ordering,
and final result reconciliation.
### Local Artifact Removal
The detail delete control is an app-data correction tool, not an in-game action.
It is unavailable while the relevant native scan or processor is active and
requires a user confirmation. For a native result, the authoritative workflow
first appends a tombstone, filters the row from the local view, then removes a
PNG only after verifying that its resolved path stays within the selected run
directory. The raw `scan-results.json` evidence is never rewritten. A linked
Store record is removable only when it exactly matches the selected local
record and the user explicitly includes it; a Store-only row uses the same
main-process-scoped local removal. None of these paths invoke the input helper,
focus Genshin, or modify game data.
## Scanner-First Information Architecture
The renderer follows the user's task sequence instead of exposing every
technical subsystem at the same level:
1. **Scanner** is the default workspace and owns readiness, start/stop,
progress, preview, the completed-result rail, and access to review.
2. **Artifacts** owns collection browsing, filters, selected detail, explicit
single-result promotion/review, and secondary technical evidence. Collection-
level pipeline evidence opens in a modal; selected-result OCR evidence stays
in a local disclosure.
3. **Review** summarizes extraction uncertainty and routes the user back to the
relevant Artifact detail. It does not make trash, feed, or deletion claims.
4. **Builds** reads only the newest complete native result run because it
retains canonical IK Set keys and per-field confidence. It can show at most
three source-bound, read-only profile suggestions from the separate evidence
ranker. Profile expiry, Review gates, complete Set shape, required aggregate
context, conflict evidence, and non-overlap remain explicit. Current roll
efficiency is never presented as build fit, and character ownership/team/
weapon/rotation are not inferred from Artifact data.
5. **Overlay** and **Diagnostics** are secondary tools. They remain available
without competing with the primary scan-to-review journey.
6. **Settings** is a shell-level secondary modal. It currently owns the
persisted app-language preference; changing it updates renderer copy only
and does not imply support for another Genshin OCR language.
On the Scanner surface, app/Genshin readiness and one primary start/stop action
come before source selection or manual capture. Advanced source, scope, and
manual-read controls stay in one focus-trapped modal so opening them never
reflows the scanner workspace. This is a presentation rule; it does not weaken
preflight, focus, review, or persistence gates.
## Scan Results And Inventory UX
The next product surface is documented in
@@ -251,14 +412,21 @@ The next product surface is documented in
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.
show readiness, one primary start/stop action, the left preview/work surface,
the right-side live result rail, progress/status, and review access. While a
scan is active, the left work surface owns capture phase and target progress;
the right result surface owns the independent OCR/parse/evaluation progress
and completed-result stream. A second standalone progress card would
duplicate that state and is not part of the layout.
- The live result rail receives fully evaluated artifacts from the current app
scan session only, in ascending capture sequence, and starts empty on app
launch. Intermediate OCR/debug payloads stay in diagnostics or detail, while
older persisted records remain available in the Artifacts view.
- 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, opening detail,
and showing the current artifact-only native pipeline state.
and showing the current artifact-only native pipeline state. Pipeline and IK
evidence should be collapsed unless the user asks for it.
- Weapons, materials, and character details stay out of the active Inventory UI
until their values are actually scanned; loaded IK catalog data alone is not a
user-facing scanner capability.
@@ -272,12 +440,21 @@ Architecture rules:
review can explain which OCR/parser fields are trustworthy.
- Upgrade projection is a local deterministic/probabilistic helper, never a
claim that an artifact will roll a specific way.
- `build-fit-evidence-ranking-v1` is not a damage formula or optimizer. It
ranks only documented Set/Main-Stat/Substat rule coverage after the scanner
confidence gate. It never consumes Roll-Efficiency, roll magnitude, or OCR
confidence as a ranking component.
- A profile with an expired source review fails closed. Required aggregate
targets remain deferred unless an explicit, user-confirmed session context
references a declared local/user contract source.
Planned result flow:
Implemented result flow:
```mermaid
flowchart LR
ScanLoop["Scan loop"]
ScanLoop["Native capture producer"]
Queue["capture-jobs.jsonl"]
Workers["Bounded OCR/parse workers"]
Parsed["Parsed artifact"]
ReviewGate["Extraction confidence / review gate"]
Value["Artifact value evaluator"]
@@ -286,7 +463,9 @@ flowchart LR
Inventory["Artifact inventory"]
Detail["Artifact detail"]
ScanLoop --> Parsed
ScanLoop --> Queue
Queue --> Workers
Workers --> Parsed
Parsed --> ReviewGate
ReviewGate --> Value
Value --> Store
@@ -296,15 +475,78 @@ flowchart LR
Inventory --> Detail
```
Future queue refactor:
Queue and replay state:
- One capture/game-control worker may click, scroll, focus, and poll failsafes.
- OCR/parse/evaluation may process bounded queued screenshot/crop jobs.
- One capture/game-control producer may click, scroll, focus, poll failsafes,
and append flushed crop jobs.
- Up to four OCR/parse/evaluation workers tail complete queue records while the
producer runs. Temporary EOF is non-terminal; producer terminal plus a fully
drained queue is terminal.
- Queueing must preserve stop behavior, duplicate handling, review decisions,
and the existing read-only safety boundary.
- The native post-capture processor already consumes crop jobs with bounded
parallelism while preserving report order. Further queue work is secondary to
live throughput evidence and result quality.
- Results are sequence-deduplicated, reordered to capture order, evaluated
before publication, exposed to the renderer as monotonic deltas, and written
incrementally to `scan-results.json` before final reconciliation.
- Saved `scan-results.json` can be replayed repeatedly through the same value
and projection code. Replay hashes the complete derived payload and fails
when a clean parsed Artifact remains unevaluated; it never touches Genshin.
## UI Feedback And Motion
- Scan progress is durable view state and remains visible while a scan runs;
toast messages never replace progress, blockers, or final result state.
- Scan progress is measured against the resolved owned-inventory target or the
user-selected Artifact/row limit and distinguishes capture/read, parse,
persistence, review, duplicate, and error outcomes.
- Skeletons reserve the Inventory list/detail layout during initial reads.
Inline spinners indicate bounded refresh, preview, promotion, and review work.
- Toasts report the outcome of explicit renderer mutations such as promotion,
review approval/rejection, and GOOD import/export. Errors use alert semantics;
informational and success messages use polite live regions.
- Shared Galaxy design tokens own semantic colors, surfaces, spacing, depth,
focus, and motion timing. Feature styles consume those tokens instead of
inventing scanner-state colors independently.
- Micro-motion may clarify entry, progress, and state changes, but functionality
must remain complete with `prefers-reduced-motion: reduce`; focus-visible
treatment and text/icons must carry meaning without motion or color alone.
## Evaluation Boundaries
- `roll-efficiency-v1` measures legal substat roll-tier quality only.
- Set preference, main-stat desirability, character role, and substat usefulness
are build context and remain `deferred`.
- Locked/equipped state affects workflow, not intrinsic roll quality.
- Evaluation uses rarity-specific roll tables and legal total roll counts.
- Review or incomplete data receives no confident normal score.
- `roll-efficiency-projection-v1` is available only for unambiguously identified
5-star Artifacts with four known legal substats below +20. It models legal
tier bounds, not guaranteed future rolls; 4-star or rarity-ambiguous data is
deliberately unavailable.
## Packaging Boundary
- Production packaging uses Electron 43 and electron-builder.
- Renderer/main/preload live inside `app.asar`; the native helper and IK lists
are explicit unpacked `extraResources`.
- Vite uses the relative base `./`, because production windows load
`dist/index.html` with `BrowserWindow.loadFile` instead of an HTTP origin.
- In packaged mode helper and IK lookup use `process.resourcesPath` and do not
search `process.cwd()` or the repository implicitly. Explicit
`INPUT_HELPER_EXE` and `IK_INVENTORYLISTS_DIR` overrides remain available.
- `npm run package:offline-check` builds and verifies those paths without
launching the app or sending game input. The verifier rejects absolute
renderer asset references and a packaged runtime signature that differs from
current source.
- The built-renderer execution of `npm run package:live:builds` passed the
current English/German locale flow, Builds loading/context/focus, reduced
motion, overflow, and local-delete confirmation probe. It is renderer
evidence only: it did not launch an elevated packaged executable or prove its
UAC/bridge/native-runtime path, and it is not a substitute for native Genshin
smoke evidence.
- Packaged runtime, UAC, preload calls, native capture, result loading, and
Inventory rendering passed live acceptance from `%TEMP%` on 2026-07-10.
The packaged 5er remained non-persistent; see
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).
## Security And Safety
@@ -0,0 +1,138 @@
# Artifact Evaluation And Offline Validation - 2026-07-10
Historical pre-live snapshot. The deferred live work described here was
completed later on 2026-07-10; see
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).
This report records the implementation of the five post-ingestion phases. No
live Genshin smoke test was run during this work. Existing native scan results
were used as the only real Artifact input.
## Implemented Phases
### 1. Deterministic Artifact evaluation
- `src/lib/artifactEvaluation.ts` implements `roll-efficiency-v1`.
- The score measures legal substat roll-tier efficiency from `0-100`; it does
not pretend to be universal character or build value.
- Main stat validity, extraction confidence, roll legality, and build fit stay
separate.
- Clean results become `evaluated`; uncertain extraction remains `review`;
inconsistent or incomplete clean data becomes `unknown` instead of receiving
a fabricated score.
- Locked and equipped state do not change Artifact quality.
### 2. Inventory and detail integration
- Native `scan-results.json` entries now carry a versioned value evaluation,
score, reason codes, legal roll counts, and per-substat efficiency.
- Legacy saved results are evaluated on load without requiring a rescan.
- The scan result rail shows compact roll-efficiency values.
- Inventory adds evaluated/open filters and roll-value sorting.
- Artifact detail shows score reasons, roll breakdown, and the explicit
`Build-Fit offen` boundary.
- Review results never receive a normal quality score.
### 3. Offline packaged-app verification
- Electron was upgraded from 33 to `43.1.0` because the old runtime was listed
by the production dependency audit.
- Deprecated `NativeImage.getBitmap()` calls were migrated to `toBitmap()`.
- `electron-builder`, `@electron/asar`, and repeatable package scripts were
added.
- `npm run package:offline-check` builds the C# helper, renderer, Electron main
process, and an unpacked Windows app without launching it.
- `scripts/verify-packaged-app.mjs` verifies the executable, ASAR entries,
relative renderer assets, current runtime signature, preload, helper, IK
lists, and matching IK version.
- Packaged helper and IK lookup now use only `process.resourcesPath` by default;
repository paths remain development-only and cannot mask missing packaged
resources.
- The unpacked app passed `27/27` project/package checks. Runtime launch and
Genshin interaction remain deliberately deferred to the next live session.
### 4. Offline repeatability replay
- `npm run scan:native:replay -- --run-dir=<saved-run> --repeats=5` evaluates a
saved `scan-results.json` repeatedly and compares deterministic SHA-256
payload hashes.
- It writes `outputs/native-replay/<run>/native-replay-report.json` and fails if
a clean parsed Artifact cannot be evaluated.
- The replay never focuses, captures, clicks, scrolls, or starts Genshin.
| Saved run | Repeats | Results | Evaluated | Review | Unknown | Projection | Deterministic |
| --- | ---: | ---: | ---: | ---: | ---: | --- | --- |
| `20260709-223006` | 5 | 20 | 20 | 0 | 0 | 20 complete | yes |
| `20260709-223041` | 5 | 50 | 49 | 1 historical review | 0 | 49 complete | yes |
| `20260709-223441` | 5 | 100 | 100 | 0 | 0 | 9 available, 91 complete | yes |
The 100-result run produced a score range of `76.1-92.5` with average `84.3`.
This is roll-tier efficiency, not build fit.
### 5. Upgrade projection
- Under-leveled, unambiguously identified 5-star Artifacts with four known legal
substats receive deterministic worst/middle/best roll-efficiency bounds up to
+20.
- The calculation uses remaining +4 steps and legal rarity-specific roll tiers.
- Three-substat, 4-star, ambiguous-rarity, review, incomplete, or illegal data
disables projection.
- +20 Artifacts are marked complete and do not show invented future rolls.
- Every visible projection states that target substat and roll tier are random
and that the result is not guaranteed.
## Static Evidence
- `npm run lint`: passed
- `npm test`: passed, `262/262` tests in `40/40` files
- `npm run build`: passed
- `npm run eval`: `26/26` exact cases, `77/77` fields
- `npm run scan:assessment:test`: passed
- `npm run package:verify`: `27/27` checks passed
- `npm audit`: `0` vulnerabilities
- `npm audit --omit=dev`: `0` vulnerabilities
- `git diff --check`: passed; only the known line-ending warnings may be shown
## Additional Non-Live Runtime Evidence
The current source build was started once through the normal non-elevated dev
runtime without calling capture, preflight, probe, click, scroll, or scan
endpoints. It proved the following boundaries without sending Genshin input:
- `/health` reported the current runtime signature, one main window, and all
four registered hotkeys.
- `/scanner/status` found `GenshinImpact`, reported `isElevated: false`, and
reached the C# helper while the native scanner remained `idle`.
- IK data `6.7.0` loaded as valid with 61 Artifact sets and 289 pieces;
weapons, characters, and materials remained `catalog_only`.
- Four OCR workers warmed successfully in `212 ms`.
- The saved 100-result run loaded through the runtime and legacy `deferred`
values were enriched to `evaluated` without rewriting the source run.
- A valid native PNG crop loaded successfully. An outside path, a JSON file,
and a traversal path were all blocked with HTTP `409`.
- The runtime was then shut down through `/dev/shutdown`; no stale Electron
process or port listener remained.
`npm run scan:native:validate:saved` now validates the newest complete
20/50/100 evidence set in one read-only command. It checks run contracts, PNG
containment, non-persistence, review-log provenance, five-repeat determinism,
scores, and projection boundaries. The current evidence set passed with zero
issues.
`npm run acceptance:offline` is the durable umbrella gate for work that does
not require Genshin input. It runs lint, all unit tests, OCR eval, assessment
self-test, saved native evidence validation, a fresh helper/app package build,
27 package checks, full and production dependency audits, and
`git diff --check`. The current run passed every step and writes its machine-
readable report under `outputs/offline-acceptance/`.
## Deliberately Not Claimed Yet
- No packaged executable was launched.
- No live Smart Capture or native scan was started.
- No later-session 20/50/100 live repeatability claim was added.
- No Inventory Kamera parity or 3-artifacts/second end-to-end claim was added.
- Build-fit scoring and account recommendations remain separate later work.
The required live and visual checks are listed in
[TOMORROW_LIVE_TEST_PLAN_2026-07-10.md](TOMORROW_LIVE_TEST_PLAN_2026-07-10.md).
+154 -8
View File
@@ -30,6 +30,31 @@ English UI:
nothing to the artifact store. Full evidence and the parser/timestamp fixes
are recorded in
[NATIVE_SCANNER_VALIDATION_2026-07-09.md](NATIVE_SCANNER_VALIDATION_2026-07-09.md).
- On 2026-07-10, a fresh later-session chain passed with the hardened native
helper: `5/20/50/100`, all parsed/evaluated, `0` Review, `0` processing
errors, and `0` store writes. The new 100er captured `100/100` over four
pages at `4.37/s` and processed at `3.15/s`, with no duplicate PNG hash group,
repeated page, or identical page boundary.
- A later real Settings-UI acceptance selected `Eigenes Limit -> Artefakte ->
5`. Genshin, visible detail, and the 4x8 grid passed preflight;
target/captured/processed/parsed were all 5, Review and processing errors were
0, persistence stayed disabled, and the current-session result rail contained
five entries. A later packaged row-limit run resolved one detected row to
eight Artifacts and passed 8/8 with the same non-persistence boundary.
- The packaged full-owned-inventory run `20260710-223233` resolved the target
from the OCR-confirmed owned count `2,211`, captured all 2,211 crops over 70
pages, streamed results during capture, and produced zero processing errors
and zero store writes. Its first parser pass correctly failed the 15% Review
gate at 490 Review. After the structurally safe five-star +0 repair, the
current package reprocessed the same complete corpus at 136 Review (6.15%);
the saved-run validator then passed with zero issues.
- The bounded inventory-top reset now completes in about `1.7 s` instead of
about `50.7 s`; the 3,200-event range and per-event foreground/stop guards
remain intact.
- A packaged build started from `%TEMP%` and completed a native 5er through
renderer, preload, IPC, packaged helper, and packaged IK resources with
`persist=false`. See
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).
The old alternate OCR-engine and comparison paths have been retired. The app now
runs the current OCR/capture path only. Performance claims should be stated as
@@ -126,6 +151,17 @@ npm run scan:native:smoke
npm run scan:native:smoke:5
```
For the gated live scale chain, run and validate each size before continuing:
```powershell
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\native-live-smoke.ps1 -Limit 20
npm run scan:native:validate:saved -- --targets=20
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\native-live-smoke.ps1 -Limit 50
npm run scan:native:validate:saved -- --targets=50
powershell -NoProfile -ExecutionPolicy Bypass -File scripts\native-live-smoke.ps1 -Limit 100
npm run scan:native:validate:saved -- --targets=100
```
It checks `/health`, `/scanner/native/data`,
`/scanner/native/preflight?category=artifacts` including the native visual
blank-capture guard, runs the guarded
@@ -140,6 +176,67 @@ outputs/native-live-smoke/<timestamp>/
Use this native smoke path before enabling any artifact-store promotion from
native `scan-results.json`.
For a deliberate packaged-runtime acceptance, first build with
`npm run package:offline-check`, then launch the unpacked EXE from a foreign
working directory with a loopback-only temporary CDP port:
```powershell
$exe = (Resolve-Path "outputs\dist\win-unpacked\Genshin Artifact Assistant.exe").Path
Start-Process -FilePath $exe `
-ArgumentList "--remote-debugging-address=127.0.0.1", "--remote-debugging-port=9223" `
-WorkingDirectory $env:TEMP -Verb RunAs
npm run package:live:inspect
```
`package:live:inspect` is read-only. The following command is a real bounded
five-card Genshin scan and therefore requires the same live authorization and
preconditions as every other input test:
```powershell
npm run package:live:scan5
```
The runner calls packaged renderer/preload/IPC methods serially, validates the
5-result non-persistence contract, and writes JSON plus a screenshot below
`outputs/packaged-live/`. Close the packaged app after testing so the temporary
CDP port disappears.
For the streaming pipeline, use the real Settings-UI path with a bounded target
large enough to observe overlap:
```powershell
npm run package:live:ui-stream20
```
This acceptance is stricter than a correct final count. It requires native
capture to be observed as running while at least one processing worker has
finished and at least one current-session result card is already visible. It
also records the maximum evaluated/result counts seen during capture, verifies
all 20 final entries, and checks the insertion animation unless the operating
system requests reduced motion. Persistence remains disabled.
The same packaged Settings-UI runner exposes all accepted scope paths:
```powershell
npm run package:live:ui-scan5
npm run package:live:ui-row1
npm run package:live:ui-stream20
npm run package:live:ui-full-inventory
```
`package:live:ui-full-inventory` explicitly selects `Gesamtes Inventar` and
never supplies a numeric fallback. It accepts the target only from the running
scanner status after the app has read the current owned Artifact count. The
runner rejects targets outside `1..2400`, requires exact captured/processed/
parsed/result/UI-row counts, checks `pages = ceil(target / 32)`, enforces at
most 15% Review with zero processing errors, verifies streaming overlap and
document fit, and requires `persist=false` with zero store writes. Its timeout
is 15 minutes. The real elevated run `20260710-223233` reached 2,211/2,211 over
70 pages. Because the initial parser produced 490 Review, the gate rejected the
first result honestly; current-package reprocessing reduced that to 136 Review
(6.15%), and `scan:native:validate:saved -- --targets=2211` passed with zero
issues. This two-stage evidence is the accepted full-inventory baseline.
The native preflight and start endpoints both accept an explicit category:
```powershell
@@ -157,8 +254,32 @@ almost entirely white/black, or too visually uniform to be trusted.
The probe-click endpoint additionally requires a detected Genshin-client
artifact inventory grid and visible artifact detail card before sending input.
At native Artifact-scan startup, the helper first resets the inventory to the
top with a bounded upward wheel sequence at the calibrated grid anchor and then
waits for the UI to stabilize. Genshin is focused only for initial startup. The
native loop checks that the same Genshin HWND is still foreground immediately
before every click and every wheel event; focus loss stops the run without an
automatic refocus. Stop, ESC, Enter, and F9 remain active during the reset,
stabilization, clicks, captures, and page scrolling. Native status reports
`initialTopResetMs` and `totalMs` separately; `activeMs` starts after the reset
and remains the capture-rate denominator.
Do not replace this production reset with `B` plus an Artifact-tab click based
on event count alone. Reopening depends on the current menu/inventory state and
adds a key toggle plus a coordinate target. It has not been live benchmarked
against the accepted bounded wheel reset. If evaluated later, run it as a
separate guarded A/B probe and compare successful top-state detection, focus/
stop behavior, coordinate robustness, and elapsed reset time before changing
the default.
## Evidence Commands
The commands in this first subsection exercise the older visible-inventory
engine and its assessment format. They remain useful for regression work on
that engine, but they do not post-process or validate the current native C#
capture path. Use `native-live-smoke.ps1` plus
`scan:native:validate:saved` for current native acceptance.
After the elevated app is running and Genshin is open on the artifact inventory,
the non-elevated terminal can drive the local dev-control endpoints and save a
full evidence bundle:
@@ -210,12 +331,35 @@ npm run scan:assessment:validate -- --latest --summary --limit=20 --max-active-a
100-artifact current run is valid scanner evidence; it is not evidence that the
3 artifacts/second budget was met unless this budget check also passes.
The historical `native-live-smoke.ps1` path is intentionally serial: it waits
for native capture to finish and only then invokes post-capture processing.
Do not divide a target by the sum of those two durations and describe the
result as the current streaming pipeline's end-to-end rate. The 2026-07-11
read-only streaming-20 check (`20260711-090019`) proved overlap (a result was
visible before capture completed) and observed 20/20 clean results at 4.43
capture/s and 2.39/s from request issue to result reconciliation. That bounded
observation is not a general performance claim: native start, capture start/end,
processing start/end, and final reconciliation still need one persisted shared
clock before publishing an end-to-end budget result.
The assessment self-test does not need Genshin:
```powershell
npm run scan:assessment:test
```
Saved native results can be re-evaluated without Genshin, focus changes, or
input automation:
```powershell
npm run scan:native:replay -- --run-dir=<native-run-dir> --repeats=5
```
This is an offline determinism and result-contract check. It does not replace a
live capture smoke test. The ordered checklist was executed on 2026-07-10; its
results are in
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).
## Review-To-Eval Quality Loop
After any live scan that creates review samples, export candidates before adding
@@ -263,11 +407,13 @@ as higher risk and validated with Smart Capture plus the probe.
Before marking an automation change done:
1. Run `npm run lint`.
2. Run `npx tsc -p tsconfig.electron.json` when Electron/preload/main changed.
3. Run `npm test`.
4. Run `npm run build`.
5. If Genshin is available, run `/automation/probe-click?index=1`.
6. For scan-loop changes, run
`/scanner/start?entry=visible-inventory&limit=2` before any broader scan.
7. Record new live findings in this file and in `docs/scanner-rework-status.md`.
1. Run `npm run helper:test` when native input safety changed.
2. Run `npm run lint`.
3. Run `npx tsc -p tsconfig.electron.json` when Electron/preload/main changed.
4. Run `npm test`.
5. Run `npm run build`.
6. If Genshin is available, run `/automation/probe-click?index=1`.
7. For native scan-loop changes, run `npm run scan:native:smoke:5` before any
20/50/100 progression. Use the explicit visible-inventory endpoint only
when that legacy engine itself changed.
8. Record new live findings in this file and in `docs/scanner-rework-status.md`.
+153
View File
@@ -0,0 +1,153 @@
# Build-Fit Contract V1
Status: the versioned contract, hard extraction gates, deterministic five-piece
verifier, four source-bound profiles, source expiry, a separate explainable
evidence-coverage ranker, session-only aggregate context, and a read-only Builds
surface are implemented and offline-tested. This document does not claim a new
live or packaged UI acceptance.
## Purpose
`build-fit-contract-v1` defines what must be known before an Artifact may enter
a character/build evaluation. It remains separate from:
- OCR/extraction confidence, which is a hard eligibility gate;
- `roll-efficiency-v1`, which describes legal roll-tier quality without build
context;
- `build-fit-evidence-ranking-v1`, a separate product rule that ranks only
source-bound profile evidence and is not a damage, optimizer, OCR-confidence,
or Roll-Efficiency score.
The foundation lives in:
- `src/types/buildFit.ts` for versioned contracts and ranking payloads;
- `src/lib/buildFitContractValidation.ts` for schema, safety-floor, and source-
expiry validation;
- `src/lib/buildFitEligibility.ts` for native-result mapping and deterministic
eligibility evidence;
- `src/lib/buildFitCombination.ts` for complete-build shape, aggregate-context,
and conflict verification;
- `src/lib/buildFitEvidenceRanking.ts` for bounded deterministic selection;
- `src/lib/buildFitExplicitContext.ts` for session-only user-confirmed
non-Artifact context;
- `src/data/buildFitProfiles.ts` for curated assumptions, provenance, expiry,
and direct source references;
- `src/features/builds/*` for the read-only renderer surface.
## Contract Inputs
Every character/build target provides:
| Area | V1 requirement |
| --- | --- |
| Identity | Stable id, positive revision, character id/name, target id/label/role/description, and explicit unique assumptions |
| Provenance | Game version, review timestamp, explicit expiry, and at least one versioned curated, user, or imported source |
| Set plans | Explained preferred or alternative legal 2-piece, 4-piece, or 2+2 shapes |
| Main stats | Explained priority 1-3 choices for Sands, Goblet, and Circlet; Flower and Plume stay fixed |
| Substats | Unique canonical stats with explained relative weights in `(0, 1]` |
| Aggregate targets | Optional full-build minimum/maximum targets; never inferred from one Artifact |
| Evidence gates | Overall extraction confidence, required field confidences, and all identity/value fields |
| Conflicts | Explicit `warn` or `block` behavior for equipment and cross-build assignment conflicts |
V1 single-Artifact and combination assessments deliberately continue to emit
`score: null` and `recommendationStatus: deferred`. The separate ranker can
only work with a complete safe combination and a non-expired profile.
## Curated Profile Corpus
`build-fit-profile-corpus-v2` has four deliberately narrow candidates. Every
profile has a direct KQM reference, game-version label, review timestamp, and
`validUntil` date. A stale profile fails closed before it can rank a build.
| Profile | Scope | Sourced Set plan | Guide version |
| --- | --- | --- | --- |
| Furina Off-field Solo Hydro C0-C1 | Ousia off-field damage and Burst support; complete ER context required | 4pc Golden Troupe | KQM `Luna II` |
| Neuvillette On-field Charged Attack | On-field Charged Attack damage, not driver-only | 4pc Marechaussee Hunter | KQM `Luna IV` |
| Raiden Off-field Hyperbloom Trigger | Off-field Hyperbloom trigger only; no Burst/Aggravate/Quickbloom claim | 4pc Flower of Paradise Lost or 4pc Gilded Dreams | KQM `5.7` |
| Nahida Off-field Deepwood Support | Off-field Skill application while Nahida is the intended Deepwood holder | 4pc Deepwood Memories | KQM `5.6` |
The direct guide references are stored in `src/data/buildFitProfiles.ts`:
- `https://keqingmains.com/q/furina-quickguide/`
- `https://keqingmains.com/q/neuvillette-quickguide/`
- `https://keqingmains.com/q/raiden-quickguide/`
- `https://keqingmains.com/q/nahida-quickguide/`
Tests validate every profile against vendored IK 6.7.0 character and Artifact-
set keys. Each profile has a Golden complete-set fixture; Furina also has the
context-pending fixture, and every additional profile has a Review adversarial
fixture. No profile source is treated as a universal build rule outside its
documented assumptions.
## Eligibility And Five-Piece Verification
1. A persisted native Artifact result maps to `build-fit-input-v1`; store-only
rows are intentionally not used because they do not retain IK set keys and
per-field confidence evidence.
2. Non-Artifact categories, Review, non-final extraction, missing fields,
confidence below the contract floor, and free-text Set guesses block before
profile evaluation.
3. `build-fit-combination-input-v1` verifies exactly five unique canonical
slots, nested Artifact gates, complete 2pc/4pc/2+2 Set forms, sourced
aggregate context, and conflicts in deterministic slot order.
4. Missing full-build context remains `pending`; a missed aggregate target is
fit evidence, not an OCR repair opportunity.
The verifier remains order-independent, source-bound, and score-free.
## Evidence Ranking And Explicit Context
`build-fit-evidence-ranking-v1` is a separate, deterministic, read-only layer
over complete eligible combinations from the newest complete native scanner run.
It returns at most three non-overlapping profile suggestions.
Its displayed `evidenceCoverage` is intentionally narrow and explainable:
- a visible component for the sourced preferred or alternative Set plan;
- the documented priority for the three variable main-stat slots;
- presence/ordinal coverage of the profile's documented substats;
- required aggregate targets only when they are met.
It never uses Roll-Efficiency, artifact roll value, OCR confidence, a guessed
character roster, team, weapon, rotation, or hidden damage constants as a rank
component. OCR confidence remains a gate only. Conflicts stay visible as
warnings and do not become a concealed damage penalty.
Furina's 200%+ Solo-Hydro Energy Recharge target is the current aggregate
context example. The user may enter and explicitly confirm the complete
non-Artifact contribution for the current session. The value is not inferred
from a scan, is not persisted, and is accepted only through the declared
`local-build-context-v1` source. Without confirmation, Furina stays deferred.
## Builds Surface Boundary
The Builds surface:
- reads only the newest complete native result run, up to the 2,400-Artifact
scan safety bound;
- shows profile, Set path, five selected artifacts, rule coverage, sources,
reasons, warnings, and blocked-context explanations;
- exposes at most three non-overlapping candidates;
- repeats that character ownership, team, weapon, and rotation are not proven
by an Artifact scan;
- never starts a scan, writes the Artifact store, edits a review, or sends
in-game input.
`src/lib/scoring.ts`, `data/presets.json`, and `createLocalAccountSnapshot`
remain legacy/demo boundaries. Real local snapshots still do not run through
the legacy scorer or emit legacy builds/recommendations.
## Next Acceptance Steps
1. The saved 20/50/100/2,211 validation gates passed for this checkpoint;
preserve them for later Build-Fit changes and do not weaken scanner review
gates.
2. Perform a packaged renderer/UI acceptance before calling the new Builds
surface live-accepted.
3. Refresh every profile before its explicit expiry and add Golden plus
Review/low-confidence adversarial coverage for every new profile.
4. Visually label the remaining 136 Review crops before changing parser or
profile rules; do not relax gates from aggregate statistics.
5. Add later profiles only when their team/weapon/rotation assumptions can be
represented explicitly without hidden constants. No suggestion may imply
deletion, feeding, enhancement, or automatic in-game mutation.
+224 -3
View File
@@ -5,10 +5,34 @@
- [ ] The expected crop or capture behavior is clear.
- [ ] Genshin is not accessed through memory reads, hooks, injection, or game files.
- [ ] Auto-scan starts only from confirmed artifact inventory plus visible detail card, or blocks with a reason.
- [ ] Native Artifact scan resets the inventory to the top with a bounded grid-anchor scroll and stabilization wait.
- [ ] A user-facing full-inventory run resolves its target from the OCR-confirmed
current owned Artifact count, never from inventory capacity; missing or
invalid current count blocks safely before native start.
- [ ] Artifact and row limits both clamp to the owned count and the 2,400 target
safety bound; row conversion uses the detected grid column count.
- [ ] A `B` plus Artifact-tab reopen is not promoted over the bounded wheel reset
without a guarded live A/B test for state safety, targeting, and timing.
- [ ] Native automated clicks and wheel events require Genshin to remain foreground; focus loss stops without refocusing.
- [ ] Stop, ESC, Enter, and F9 remain active during native reset, capture, and scrolling.
- [ ] Capture failures are shown to the user.
- [ ] OCR uncertainty remains inspectable in Details.
- [ ] Parser output does not silently trust low-confidence text.
- [ ] Current native capture jobs preserve direct visual `starCount`,
`starConfidence`, and `starSource`; an absent, invalid, or conflicting star
field is never silently assumed to be 5★.
- [ ] Direct visual rarity ambiguity enters `Review` before value evaluation.
- [ ] Scanner controls contain no automatic in-game salvage, Quick Select,
deletion, feed, enhance, lock/unlock, or resource-spending action.
- [ ] Any Inventory local-result removal is explicitly confirmed, tombstones the
result before crop cleanup, preserves raw `scan-results.json` evidence,
remains contained to app-local files, and never invokes game input. An
optional Store-record removal is limited to the exact linked local record.
- [ ] A native-result deletion is blocked while capture or processing is active,
remains idempotent after its tombstone, and cannot remove a crop outside the
selected run directory.
- [ ] `npm run lint` passes.
- [ ] `npm run helper:test` passes when native input safety changed.
- [ ] `npm test` passes when parser/scoring logic changed.
- [ ] `npm run build` passes.
- [ ] Manual Smart Capture is tested when possible.
@@ -30,21 +54,101 @@
- [ ] Parsed count is at least the requested count.
- [ ] Miss rate is at or below 2%.
- [ ] Review rate is at or below 15%.
- [ ] Speed reporting uses active scan timing plus quality, not click count alone.
- [ ] Capture rate, processing rate, and end-to-end rate are reported as separate metrics.
- [ ] A streaming end-to-end claim records native start, capture start/end,
processing start/end, and final result reconciliation on one shared wall clock.
- [ ] `run-timing.json` is present, uses `native-scanner-run-timing-v1`, and
contains valid ordered first-observed lifecycle markers through durable result
reconciliation.
- [ ] The smoke report validates target/capture/queue/parse/durable-result
reconciliation together with the timing record; a historical timing report is
not reused for a current-build claim.
- [ ] Overlapping capture and processing durations are never added to derive an
end-to-end rate.
- [ ] Speed reporting uses quality gates, not click count alone.
## Revised Scope Live Acceptance
- [x] Current elevated-dev 50-artifact smoke `20260711-154827`: target/captured/
clicked/queued/processed/parsed/loaded `50/50`, 2 pages, 0 Review, 0 errors,
0 Store writes, `persist=false`, and 50 jobs/non-empty PNGs. A valid
`native-scanner-run-timing-v1` record reconciled at `28,022 ms`; it is not a
3/s performance claim.
- [x] Real Settings-UI Artifact limit 5: Genshin/detail/grid preflight passed;
target/captured/processed/parsed `5/5`, Review/errors `0`, `persist=false`, and
five current-session result rows.
- [x] Complete packaged full-inventory baseline resolves OCR-owned target 2,211,
captures 2,211 crops over 70 pages, reprocesses all 2,211 with the current
package at 136 Review (6.15%), 0 errors, `persist=false`, and passes saved-run
validation with 0 issues.
- [x] Real packaged Settings-UI row limit 1 resolves the detected eight-column
grid to target 8 and finishes captured/processed/parsed `8/8`, Review/errors
`0`, `persist=false`; foreground loss is proven to block with zero clicks.
- [ ] Any `B`-reopen candidate is benchmarked separately and does not replace
the accepted wheel reset without stronger reliability and timing evidence.
## UI Change
- [ ] Scanner, Artifacts, Review, and Builds preview follow the primary user
journey; Overlay and Diagnostics remain secondary tools.
- [ ] The Scanner page shows app/Genshin readiness and one unambiguous primary
start/stop action before advanced controls.
- [ ] The main workflow remains visible without unnecessary scrolling.
- [ ] Debug or secondary information is moved behind buttons/modals where appropriate.
- [ ] Builds stays visibly labeled as a preview until Build-Fit is implemented;
roll efficiency is not presented as character/build suitability.
- [ ] Review describes extraction correction and never implies trash, feed,
deletion, or an in-game mutation.
- [ ] Disabled states prevent actions without required data.
- [ ] Initial content loading reserves layout with a skeleton; bounded actions
use a spinner; scan progress remains durable view state.
- [ ] During scanning, the left main work surface shows phase,
processed-versus-target progress, and read/parsed/stored/review/duplicate/error
outcomes without a duplicate standalone progress card.
- [ ] Toasts confirm explicit mutations and failures without replacing durable
progress, review, blocked, or error state.
- [ ] Status meaning is available through text/icons and not color or animation alone.
- [ ] Keyboard focus is visible for navigation, buttons, disclosures, fields,
dialogs, and toast dismissal.
- [ ] `prefers-reduced-motion: reduce` disables non-essential motion without
hiding state changes or feedback.
- [ ] Text fits in controls and panels.
- [ ] Desktop viewport is checked manually.
- [ ] The Scanner, Artifacts, Review, Builds preview, Overlay, and Diagnostics
views are checked at the packaged desktop viewport for clipping, overflow,
accidental page-level scroll, nested-scroll traps, and empty/loading/error states.
- [ ] Primary scanner controls remain usable at the smallest supported desktop
window; narrower layouts reflow instead of clipping cards or action labels.
- [ ] Before/after screenshots or equivalent current-build visual evidence are
inspected for the changed views.
- [ ] A fresh/missing/invalid app locale starts in English, German can be
selected in Settings, and the preference persists locally without changing
the English-only Genshin scanner contract.
- [ ] Localized UI acceptance uses stable semantic hooks where possible and
verifies that translated labels do not cause clipping, focus, or overflow.
- [ ] The artifact detail local-delete control states its app-local scope,
requires confirmation, and remains unavailable for an active native run.
- [ ] `npm run lint` and relevant renderer tests pass.
- [ ] `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.
- [ ] The result rail is empty on a fresh app launch, contains only results from
the current app scan session, and leaves persisted history in Artifacts.
- [ ] Progress and completion use the resolved owned-inventory target or the
selected Artifact/row limit consistently.
- [ ] Capture and evaluation progress advance independently: the left bar uses
captured/target while the right result panel uses evaluated/target.
- [ ] Processing starts once when the native run first exposes `runDir`, keeps
waiting across temporary JSONL EOF, and finishes only after producer terminal
plus queue drain.
- [ ] The live rail shows fully evaluated artifact rows only, not intermediate
OCR/debug state, and appends every current-session row in capture order.
- [ ] Result delta polling deduplicates stable IDs/sequences and a final full
load reconciles captured, processed, and durable-result counts.
- [ ] Newly inserted result rows use a left-to-right mount cue; reduced-motion
users receive the same content and status without the animation.
- [ ] 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.
- [ ] Native post-capture runs write `scan-results.json` with extraction status and deferred/review value status.
@@ -61,6 +165,12 @@
- [ ] Native live smoke uses `npm run scan:native:smoke` before broad native timing or store-promotion claims.
- [ ] Artifact-only scope is visible in the UI; weapons, materials, and character details are not presented as active scanner features while they are not scanned.
- [ ] Low-confidence or conflicting reads show `Review` instead of a normal weak/strong value decision.
- [ ] Explicit visual 14★ native results use `excluded`, receive no score,
projection, or store promotion, and remain visible for manual inspection.
- [ ] The separate read-only `Nicht 5★` filter contains only explicitly
recognized 14★ entries and retains screenshot/crop plus parsed details.
- [ ] The `Nicht 5★` view does not call entries safe to salvage and exposes no
automatic salvage or Quick Select control.
- [ ] 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.
@@ -76,13 +186,124 @@
- [ ] Character, set, stat, and slot dictionaries are updated deliberately.
- [ ] Tests cover changed behavior when practical.
## Artifact Roll Evaluation
- [ ] Extraction status and value status remain separate fields.
- [ ] Clean legal results become `evaluated`; Review receives no normal score.
- [ ] Only explicitly confirmed 5★ evidence enters `roll-efficiency-v1` for
current native jobs.
- [ ] Explicit visual 14★ evidence becomes `excluded`, not a weak score;
missing, invalid, or conflicting direct star evidence becomes `Review`.
- [ ] Incomplete or inconsistent clean data becomes `unknown`, not a guessed score.
- [ ] Score is labeled as roll efficiency, not universal Artifact or build value.
- [ ] Build fit stays explicitly deferred without character/build context.
- [ ] Locked and equipped state do not change roll efficiency.
- [ ] Rarity-specific legal values and total roll counts are enforced.
- [ ] Reason codes and per-substat roll breakdown explain the result.
- [ ] Legacy saved scan results are enriched on load without requiring a rescan.
- [ ] Unit tests cover evaluated, review, unknown, ambiguity, and rarity edges.
## Build-Fit Contract
- [x] Input, contract, and assessment schemas are explicitly versioned.
- [x] Contracts require character/target identity, revision, game-versioned
provenance, explained Set/Main-Stat/Substat rules, aggregate targets, and
explicit conflict behavior.
- [x] V1 safety floors cannot be lowered below 80% overall extraction and 70%
for every required identity/value field.
- [x] Review, non-parsed, incomplete, low-confidence, or non-canonical Set data
blocks before downstream fit work.
- [x] Native Artifact results map into the contract without guessing a Set key;
non-Artifact categories are rejected.
- [x] Roll-Efficiency is recorded only as separate context and is never used as
Build-Fit eligibility or presented as a fit score.
- [x] V1 assessments retain `score: null` and deferred recommendations even
when the separate evidence-ranking layer is available.
- [x] Real local account snapshots do not call the legacy demo scorer.
- [x] Four current profiles (Furina, Neuvillette, Raiden Hyperbloom, Nahida
Deepwood) are source-bound, game-versioned, IK-6.7.0-key validated, have
explicit expiry, and are covered by Golden plus Review/low-confidence or
pending-context adversarial fixtures.
- [ ] Every further character/build profile is sourced, game-versioned,
reviewed, expiry-bound, and covered by Golden/adversarial fixtures before
product use.
- [x] Five-piece evaluation verifies unique slots, Set shape, sourced aggregate
targets, nested extraction gates, and cross-character/build conflicts together;
missing non-Artifact context remains `pending` rather than guessed.
- [x] The Builds UI reads only the newest complete native run and exposes at
most three non-overlapping, read-only suggestions with profile, source,
Set/Main-Stat/Substat evidence, conflicts, uncertainty, and selection reason.
- [x] The ranker never uses `roll-efficiency-v1`, roll magnitude, or OCR
confidence as a rank weight; confidence stays a hard gate.
- [x] Required aggregate targets accept only explicit, user-confirmed,
session-only local context and otherwise defer the profile.
- [x] The built-renderer Builds/UI acceptance verifies fresh English, German
switching/restoration, loading, deferred/context, suggestion, focus,
reduced-motion, overflow, and native plus Store local-delete confirmation probes.
- [ ] An elevated packaged-executable run separately verifies the same renderer
behavior when making a package-runtime claim; built-renderer evidence alone
does not prove UAC, bridge, or native runtime behavior.
## Upgrade Projection
- [ ] Projection appears only below +20 with four known legal substats.
- [ ] Worst is less than or equal to Middle; Middle is less than or equal to Best.
- [ ] Remaining roll count matches the current Artifact level.
- [ ] Review, illegal, incomplete, three-substat, 4-star, and rarity-ambiguous
data disables projection.
- [ ] +20 is complete and does not invent future rolls.
- [ ] UI states that target substat and tier are random and not guaranteed.
- [ ] Projection does not claim character/build usefulness.
## Native Offline Replay
- [ ] Replay reads an existing `scan-results.json` and never starts capture/input.
- [ ] At least three repeats produce the same full derived-payload hash.
- [ ] Every clean parsed Artifact is evaluated or the command fails.
- [ ] Explicit 14★ entries replay as stable `excluded` results and are not
counted as clean-but-unevaluated failures.
- [ ] Review remains Review and is not counted as an evaluation failure.
- [ ] Report includes value/projection counts and score range.
- [ ] Accepted bounded 20/50/100 runs and the 2,211 full-inventory corpus are
replayed before changing the evaluation contract.
- [ ] `npm run scan:native:validate:saved` passes for the latest complete
evidence set, including `-- --targets=2211` for full-inventory-sensitive work.
- [ ] Saved-run validation confirms manifest/status/job/result counts, PNG
containment, zero processing errors, non-persistence, review provenance,
and projection ordering.
## Release Or Packaging
- [ ] `npm run acceptance:offline` passes before the live acceptance session.
- [ ] Production build succeeds.
- [ ] Electron preload bridge is copied to `dist-electron/preload.cjs`.
- [ ] App starts outside browser preview.
- [ ] Smart Capture bridge is available.
- [ ] No generated debug artifacts are included accidentally.
- [ ] `npm audit --omit=dev` reports zero production vulnerabilities.
- [ ] `npm run package:offline-check` passes before packaged runtime testing.
- [ ] ASAR contains renderer, Electron main, preload, and package manifest.
- [ ] Packaged `dist/index.html` uses relative `./assets/...` references; the
verifier rejects root-absolute `/assets/...` references.
- [ ] `resources/input-helper/InputHelper.exe` exists in the unpacked app.
- [ ] `resources/ik-inventorylists` exists and its version matches source data.
- [ ] Packaged helper/IK resolution uses `process.resourcesPath` without an
implicit `process.cwd()` repository fallback.
- [ ] Packaged and source `APP_RUNTIME_SIGNATURE` values match, so evidence from
an older runtime is rejected as stale.
- [x] `npm run package:live:builds` passed against the built renderer: fresh
English, German selection, restored English, Builds loading/context/focus,
reduced motion, no document overflow, and native plus Store delete-confirmation UI probes.
- [ ] The same UI evidence is collected from an elevated packaged executable
before claiming current package-runtime/UAC behavior.
- [ ] Packaged runtime launch, UAC, bridge, helper, and crop preview are tested
separately; offline resource checks do not prove runtime behavior.
## Next Live Acceptance Session
Use [TOMORROW_LIVE_TEST_PLAN_2026-07-10.md](TOMORROW_LIVE_TEST_PLAN_2026-07-10.md)
in order. Start with packaged launch and existing Inventory data, then one
Smart Capture, native 5, and only then gated 20/50/100 runs.
## Git Merge And Gitea Push
+25 -1
View File
@@ -27,8 +27,23 @@ This document defines project engineering standards.
- 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.
- 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
@@ -36,6 +51,9 @@ This document defines project engineering standards.
- 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
@@ -49,6 +67,12 @@ This document defines project engineering standards.
- 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
+103 -125
View File
@@ -1,139 +1,117 @@
# Current App Status
Updated: 2026-07-09
Updated: 2026-07-11 — current-build live-smoke checkpoint for the
English-default renderer, local artifact removal, shared-clock timing evidence,
and visually reviewed OCR corpus corrections.
This document is the short current-state entry point. For deeper architecture
details see [ARCHITECTURE.md](ARCHITECTURE.md). For the scanner and inventory
roadmap see [scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md).
For live scanner runbooks see [AUTOMATION_LIVE_SCAN.md](AUTOMATION_LIVE_SCAN.md).
Historical live evidence remains documented in
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).
The current checkpoint and its explicit remaining release gates are documented
in
[LOCALIZATION_LOCAL_DELETION_TIMING_CHECKPOINT_2026-07-11.md](LOCALIZATION_LOCAL_DELETION_TIMING_CHECKPOINT_2026-07-11.md).
The fresh current-build smoke is documented in
[NATIVE_SCANNER_LIVE_SMOKE_2026-07-11.md](NATIVE_SCANNER_LIVE_SMOKE_2026-07-11.md).
## Summary
## What It Can Do
The app is now an Artifact-first local scanner with a native high-speed capture
path validated at 20/50/100-item scale in the current live session. The current product scope is intentionally limited to
artifacts. Weapons, materials, and character details may exist as vendored IK
catalog data, but they are not active scanner features while their values are
not scanned.
- Read-only Artifact scanning remains scoped to the accepted English 16:9
Genshin Artifact inventory with a visible detail card. The scanner guards the
target process/window, foreground state, stop controls, and input safety.
- The native path captures card crops while bounded OCR/parse/evaluation workers
stream ordered safe results into the session rail. Review, roll efficiency,
crop evidence, parser confidence, and local promotion/review actions remain
separate concepts.
- Artifacts can be browsed, filtered, sorted, and inspected with local crop,
parser, IK, review, and value evidence. Explicit 14★ native results remain
excluded/manual-review entries; they do not become a salvage or Quick Select
workflow.
- The Builds surface reads only the newest complete native run and shows at
most three read-only, source-bound evidence suggestions. It is not an
optimizer, DPS score, ownership inference, or game-action surface.
- The application UI now defaults to English. German is selectable in Settings
and persists locally. The preference updates the renderer/document language
only; it does not change the English-Genshin Smart Capture contract.
- Artifact detail now has a confirmed local-delete action for a wrong scan,
screenshot, or Store row. Native deletion appends a tombstone, keeps raw
`scan-results.json` evidence intact, deletes only a PNG proven to be within
the selected run directory, and can remove only an explicitly chosen exact
linked Store record. It never focuses Genshin, invokes the input helper, or
performs an in-game action.
- Native runs now write `run-timing.json` using
`native-scanner-run-timing-v1`. It records first-observed request, scanner,
capture, processing, durable-result, and reconciliation milestones so the
end-to-end duration is measured from one shared clock.
- The former 136-item full-inventory Review set has been visually audited for
the current corpus work: 128 are explicit 14★ entries, six have the same
exact duplicated-decimal OCR defect, one requires slot-safe name resolution,
and one incomplete crop intentionally remains `Review`.
Electron/React should act as the visual control and status surface. The C#
helper owns fast Genshin focus, click, scroll, and card-crop capture for the
native path. OCR, parsing, review, promotion, and value evaluation remain
separate downstream stages so capture speed is not blocked by UI work.
## Verified Evidence
## What Works Now
The historical scanner acceptance is still useful regression evidence, but it
does not certify the current change set by itself:
- Smart Capture can read the currently opened artifact detail view through
focused crops, OCR preprocessing, deterministic parsing, confidence, and
notes.
- The visible-inventory auto-scan path is the current stable production
baseline: preflight, grid detection, read-only tile selection, detail
verification, OCR, parse, store/review, scroll, and summary.
- The native IK-style artifact capture path is wired through the C# helper.
It captures visible 16:9 Artifact inventory detail card crops and writes a
self-contained run directory.
- Native runs write `manifest.json`, `capture-jobs.jsonl`, and `status.json`.
Post-capture processing can consume the job file and write
`scan-results.json` plus `processing-report.json`.
- Vendored Inventory Kamera `inventorylists` are copied under
`data/ik-inventorylists` and packaged as scanner reference data. Current
version is `6.7.0`.
- Native artifact post-processing matches parsed artifacts against IK artifact
set/piece/slot data and sends conflicts to review.
- The scan page has a compact latest-results rail. Native parsed results are
labeled as `Geparst`, persisted results as stored, uncertain results as
review, and value evaluation as `Wert offen`.
- The Inventory view can browse native scan results, stored artifacts, and
snapshot fallback rows. It shows native crop previews, field confidence,
IK/GOOD metadata, dry-run promotion status, and a per-result
`Naechster Schritt`.
- The Inventory view now shows an Artifact-only pipeline strip for scope,
native capture, OCR queue, review gate, promotion, and evidence.
- GOOD import/export, review samples, local text replacements, scanner
diagnostics, OCR eval, and local artifact storage exist.
- Historical dev runs completed 5/20/50/100 with zero Review, errors, and Store
writes; the historical packaged paths include bounded 5/8/20 and the 2,211
full-owned-inventory soak.
- The saved 50-artifact evidence set still validates at `50/50`, with zero
replay issues, zero Review, zero unknown, and no projection failures.
- The current checkpoint has focused coverage for locale persistence/catalog
parity, artifact Store removal, native-result tombstones/crop containment,
shared-clock timing validation, and the new confirmed OCR corpus cases.
- The final current-build offline gate passed: `npm run acceptance:offline`
completed TypeScript, 72 test files / 444 tests, OCR evaluation, saved-run
validation, package verification (27/27), both dependency audits, and the
diff check.
- The built-renderer Builds/UI acceptance passed with stable semantic hooks:
fresh English, German selection, restored English, Builds context/focus,
reduced motion, overflow, and native plus Store local-delete confirmation
probes. This is deliberately not described as an elevated packaged-executable
run.
- The elevated development current-build smoke `20260711-154827` passed with
50/50 target/capture/click/queue/parse/load reconciliation, 0 Review,
0 processing errors, 0 Store writes, `persist=false`, and a complete
`native-scanner-run-timing-v1` record. Request-to-reconciliation was
`28,022 ms` (`~1.78 Artifacts/s`); that is a functional/safety result, not a
3/s performance claim.
## What Was Just Done
## What Still Needs Testing
- The active UI scope was narrowed to Artifact scanning only.
- Weapon, material, and character-detail IK catalog coverage was removed from
the primary Inventory feature surface so it cannot look like implemented scan
support.
- Native result labels were made more honest:
`Geparst` means extracted, `Stored` means persisted, `Review` means unsafe,
and `Wert offen` means artifact value evaluation has not run yet.
- The Inventory detail panel gained a `Naechster Schritt` card:
ready for promotion, review first, already in store, blocked, or value later.
- New filters were added for native rows and promotable rows.
- Native 20/50/100-item dry runs were completed. A live OCR decimal-loss bug
and missing native result timestamp were fixed and regression-tested.
- Native Inventory results now support explicit single-result promotion with a
second confirmation, authoritative main-process revalidation, duplicate
detection, store write, scan-result update, and `promotion-log.jsonl`.
- Review-required native results now have an inline editor for identity,
main stat/value, level, substats, equipped state, lock state, and notes.
Approve requires IK identity validation, canonical main-value validation,
and legal substat rolls; Reject keeps the result blocked. Approved cases
write `review-log.jsonl` and reuse `review-samples.jsonl` for OCR eval export.
- The three real Review rows from the 100-item native run were manually
corrected and approved through that workflow. The run now has zero remaining
Review rows, all three corrections reached the eval candidate pipeline, and
the confirmed cases are permanent OCR regressions.
- The parser can now repair the confirmed dropped/extra-digit substat cases at
+20 only when one legal 5-star roll-count combination exists. Ambiguous OCR
stays reviewable.
- Project docs and roadmap were updated to state Artifact-only scope and the
next scanner/product priorities.
- If making a current package-runtime claim, separately launch the elevated
packaged executable and verify UAC, preload bridge, helper, and renderer
behavior. The passing built-renderer acceptance does not prove that boundary.
- Repeat the passing native and Store local-delete confirmation probes during an
elevated packaged-executable acceptance if a package-runtime release claim is
needed.
Unit coverage already protects the authoritative tombstone, active-run,
containment, and exact-Store boundaries.
- Do not claim German Genshin OCR/capture support: only the application UI is
localized. Non-16:9 layouts, other Genshin UI languages, and other inventory
categories remain outside accepted scanner scope.
## Current Evidence
## Known Limitations
- `npm run lint` passed.
- `npm test` passed with `252` tests.
- `npm run build` passed.
- `git diff --check` passed; only existing CRLF warnings were reported for
`electron/services/inputHelperPowerShellFallback.ts` and `src/styles/base.css`.
- Native IK dry runs on 2026-07-09 completed at 20, 50, and 100 items with
complete crop/job/result counts, `0` processing errors, and `persisted: false`.
The 100-item run captured `100/100` across 4 pages in `24,673 ms`, parsed
`100/100`, and safely routed 3 OCR value losses into Review. See
[NATIVE_SCANNER_VALIDATION_2026-07-09.md](NATIVE_SCANNER_VALIDATION_2026-07-09.md).
- The older visible-inventory path has broader live evidence, including a
100-artifact run with `100/100` verified and parsed, `98` stored,
`2` duplicates, `0` review samples, `0` misses, and `393 ms/artifact`.
- OCR can still fail on a new game layout or unreadable crop. The app must route
uncertainty to `Review`; it must not relax matching thresholds or invent a
canonical name from ambiguous text.
- The current parser fixes only the observed exact duplicate decimal punctuation
and uses slot-based artifact-name resolution only when independent
high-confidence slot evidence gives one valid match. The incomplete audited
crop stays `Review` by design.
- Build-Fit remains evidence ranking, not character/build optimization. Team,
weapon, rotation, character ownership, and unsourced aggregate values are not
inferred from Artifacts.
- The current live 50-artifact smoke measured `28,022 ms` request-to-result
reconciliation (`~1.78 Artifacts/s`). The functional gate passed, but the
separate 3/s performance target remains unproven.
## Known Limits
## Next Priorities
- Native IK-style capture has current-session scale evidence, but later-session
repeatability and packaged-app evidence are still open.
- The native path is limited to visible 16:9 Artifact inventory with a visible
detail card.
- Native post-capture results do not persist by default. Clean selected results
can now be promoted explicitly after a second UI confirmation.
- Artifact value scoring and upgrade projection are not implemented for native
results yet.
- Review/edit/approve is implemented for one selected native result at a time.
Batch review is intentionally not available.
- The `333 ms/artifact` target for 3 artifacts/second is not proven.
- The native capture worker exceeded 4 artifacts/second, but the smoke runner
still captures and processes sequentially; 3 artifacts/second end to end is
therefore not proven.
- Weapons, materials, and character details are intentionally ignored until
their values are actually scanned.
## What Is Next
1. Add Artifact value evaluation after extraction is trustworthy. Keep value
reasons separate from OCR confidence.
2. Add detail-level value reasons and optional upgrade projection. Projection
must stay labeled as probabilistic.
3. Confirm packaged-app behavior for the C# helper, IK lists, preload bridge,
native crop previews, and smoke commands.
4. Repeat the native 20/50/100 evidence in a later session to prove repeatability.
5. Return to recommendations only after native artifact ingestion, promotion,
review, value scoring, and repeatability are strong enough.
## Not Next
- Do not prioritize weapons, materials, or character details yet.
- Do not auto-persist native scan results before review/promotion is safe.
- Do not claim Inventory Kamera parity until broad native Artifact runs prove
repeatable speed and quality.
- Do not merge extraction confidence and artifact value into one UI score.
1. Keep the passing built-renderer acceptance distinct from the optional
elevated packaged-executable runtime/UAC check.
2. Clean generated workspace outputs, commit the coherent checkpoint, and push
the intended branch; the current-build 50-artifact live gate has passed.
3. Continue the next quality phase with visually confirmed corpus growth,
fail-closed parser behavior, profile-source refreshes, and packaged UI
regression coverage. Do not broaden game-category scope or add in-game
mutation.
+627 -9
View File
@@ -19,6 +19,19 @@ This document contains Architecture Decision Records.
| ADR-011 | Retire alternate OCR comparison paths after current scanner baseline | Superseded | 2026-07-09 |
| ADR-012 | Separate live scan results, artifact inventory, and value evaluation | Accepted | 2026-07-09 |
| ADR-013 | Move high-speed scanning into the native helper and vendor IK inventorylists | Accepted | 2026-07-09 |
| ADR-014 | Separate roll efficiency from build fit and project only legal roll bounds | Accepted | 2026-07-10 |
| ADR-015 | Adopt a scanner-first Galaxy UI and explicit feedback primitives | Accepted | 2026-07-10 |
| ADR-016 | Default to the owned inventory and keep scan feedback session-bound | Accepted | 2026-07-10 |
| ADR-017 | Stream native capture jobs into bounded evaluation workers | Accepted | 2026-07-10 |
| ADR-018 | Gate Build-Fit behind a versioned evidence contract before scoring | Accepted | 2026-07-10 |
| ADR-019 | Repair five-star +0 main values only from structural rarity evidence | Accepted | 2026-07-10 |
| ADR-020 | Target only exact supported Genshin process names | Accepted | 2026-07-10 |
| ADR-021 | Require explicit profile assumptions and source-bound aggregate context | Accepted | 2026-07-10 |
| ADR-022 | Rank only source-bound Build-Fit evidence with profile expiry | Accepted | 2026-07-11 |
| ADR-023 | Fail-closed visual rarity gate and read-only non-five-star inventory | Accepted | 2026-07-11 |
| ADR-024 | Default renderer copy to English while preserving the English scanner boundary | Accepted | 2026-07-11 |
| ADR-025 | Make artifact deletion an app-local tombstone workflow | Accepted | 2026-07-11 |
| ADR-026 | Persist first-observed native run timing on one shared clock | Accepted | 2026-07-11 |
## ADR-001: Build A Local Electron App First
@@ -377,9 +390,9 @@ Adopt a split scan/result/inventory model:
- 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.
- Use one game-control producer for click/scroll/capture and bounded downstream
OCR/parse/evaluation workers. Publish only fully evaluated entries into the
current-session result rail.
### Consequences
@@ -416,22 +429,627 @@ steps. Each native run writes `manifest.json`, `capture-jobs.jsonl`, and
`status.json`; downstream workers must consume those files instead of asking the
renderer to do per-artifact scanner work.
The first downstream worker is a post-capture processor that reads
The first downstream worker is a native result processor that tails
`capture-jobs.jsonl` and writes both `scan-results.json` and
`processing-report.json`. `scan-results.json` is the durable result contract:
one entry per captured artifact card with extraction status, artifact identity
when parsed, review state, and deferred value status. `processing-report.json`
remains the diagnostic OCR/parse report. The worker OCRs/parses after capture
and does not persist by default; DB writes require explicit opt-in after native
crop OCR is validated with live evidence.
when parsed, review state, and versioned value evaluation. `processing-report.json`
remains the diagnostic OCR/parse report. The worker may OCR, parse, and evaluate
while capture is still producing jobs, then drains the remaining queue after a
done or stopped producer. It does not persist by default; DB writes require
explicit opt-in after native crop OCR is validated with live evidence.
### Consequences
- Capture throughput can be optimized without renderer roundtrips per artifact.
- The scanner data source now matches IK's artifact names and set/piece keys.
Other vendored IK lists are data only until those values are actually scanned.
- Evaluation can remain deferred without blocking capture speed.
- Evaluation remains downstream and cannot block capture speed.
- Live safety stays read-only: no memory reads, hooks, injection, game-file
modification, deleting, feeding, enhancing, or spending resources.
- Non-16:9 layouts currently block in native preflight until layout support is
expanded.
## ADR-014: Separate Roll Efficiency From Build Fit And Project Only Legal Roll Bounds
### Status
Accepted
### Context
A universal Artifact quality score is misleading without a character, role,
team, and build target. However, the visible substat values do contain one
objective signal: how efficient their legal roll tiers were. Extraction
confidence is a third concept and must not be collapsed into either one.
Under-leveled Artifacts also invite false precision. A projection cannot know
which substat receives the next roll or which legal tier is selected.
### Decision
Implement `roll-efficiency-v1` as a context-free `0-100` score derived only
from rarity-specific legal roll values, legal total roll counts, and displayed
rounding. Persist reason codes and per-substat breakdown. Keep build fit
explicitly `deferred`; do not add set, main-stat preference, locked state, or
equipped state to roll efficiency.
Review, incomplete, or inconsistent results receive `review` or `unknown` and
no normal score. For under-leveled Artifacts, show a detail-only
Worst/Middle/Best bound from remaining +4 steps and legal roll tiers, only for
an unambiguously identified 5-star Artifact when all four current substats are
known. Label it as non-guaranteed; 4-star or rarity-ambiguous data stays
unavailable in V1.
### Consequences
- Users can compare roll-tier luck without being told that every high-roll
Artifact fits every build.
- Build-aware recommendation scoring remains a separate future contract.
- Existing saved native results can be evaluated without rescanning.
- Offline replay can hash derived results and detect non-determinism.
- Projection is conservative and unavailable when the fourth substat or clean
extraction is missing.
## ADR-015: Adopt A Scanner-First Galaxy UI And Explicit Feedback Primitives
### Status
Accepted. The original Builds lock is narrowed by ADR-022: the surface may now
show only source-bound, read-only evidence suggestions, never a general build
or optimizer claim.
### Context
The application exposed scanner setup, technical pipeline state, inventory,
review, prototype recommendations, overlay, and diagnostics with similar visual
weight. The default scan path was harder to understand than the underlying
workflow, while the Builds and triage surfaces could imply confidence that the
current Build-Fit contract and review data do not support.
The renderer also lacked one consistent contract for loading, mutation
feedback, focus, and motion. Local status text alone made successful promotion,
review, import, or export actions easy to miss.
### Decision
Adopt a scanner-first information architecture and tokenized Galaxy visual
system:
- Group Scanner, Artifacts, Review, and the explicitly labeled Builds preview
as the main workspace. Keep Overlay and Diagnostics as secondary tools.
- Lead the Scanner page with app/Genshin readiness and one primary start/stop
action. Keep source selection, scan scope, and manual capture under advanced
options while preserving all preflight and safety gates.
- Treat Review as scan-data correction. Do not derive or display trash, feed,
deletion, or universal quality judgments from extraction uncertainty.
- Keep Builds clearly bounded until the versioned Build-Fit contract exists.
Under ADR-022 it may show only source-bound, read-only evidence suggestions;
`roll-efficiency-v1` remains visible in Artifact detail but is not relabeled
as build suitability.
- Centralize semantic colors, surfaces, focus, depth, spacing, and motion in
Galaxy design tokens. Use shared skeleton, spinner, and toast primitives for
content loading and explicit mutation outcomes.
- Preserve durable progress and error state in the owning view. Toasts are
transient confirmation only. Respect `prefers-reduced-motion` and keep state
understandable through text/icons without relying on animation or color.
### Consequences
- A first-time user can follow the scan-to-review journey without opening
diagnostics or understanding the native pipeline.
- Technical evidence remains available but no longer dominates the default
inventory and scan surfaces.
- Loading and mutation feedback becomes consistent across features without
changing the scanner, review, or persistence authority boundaries.
- New renderer views must reuse the shared tokens and feedback semantics and
pass keyboard, reduced-motion, overflow, and desktop visual acceptance.
## ADR-016: Default To The Owned Inventory And Keep Scan Feedback Session-Bound
### Status
Accepted. The real Settings-UI Artifact-limit path is live accepted at 5/5, the
packaged row-limit path at one detected eight-column row is accepted at 8/8,
and the packaged full-owned-inventory baseline is accepted at 2,211/2,211 over
70 pages with current-package reprocessing at 136 Review (6.15%).
### Context
A small numeric default makes the main scan action behave like a sample even
when the user's intent is to import the whole owned Artifact collection. At the
same time, using the inventory capacity as the target would be incorrect: it is
not the number of owned Artifacts, and the native scanner does not yet detect
the physical end of the list reliably enough to stop an oversized target
without risking repeated bottom rows.
The Scanner also showed progress in a separate card while the larger left work
surface displayed onboarding or a capture. That split made the most important
running state harder to follow. Loading previous stored/native results into the
right rail at startup further blurred the distinction between this run and the
long-lived Artifact collection.
Reopening the inventory with `B` could theoretically replace many upward wheel
events, but it also introduces menu-toggle state, tab-selection coordinates,
and another guarded key/click sequence. It has not been live benchmarked as a
more reliable reset.
### Decision
- Default the user-facing scan scope to the entire currently owned Artifact
inventory.
- Read and validate the current owned count at scan start. Use that `current`
value as the hard target basis; never substitute the inventory capacity
`total`.
- If the current owned count is unavailable or invalid, block a full-inventory
scan with a reviewable reason instead of guessing.
- Offer one optional limit with either Artifacts or rows. Convert rows through
the detected grid column count and clamp both forms to the owned count and the
2,400-Artifact safety bound.
- Keep scope selection session-local so a new app launch returns to the full
owned inventory default.
- During a run, use the left main work surface for capture phase and
captured-versus-target progress. Keep the independently advancing OCR/parse/
evaluation progress beside the live results on the right. Remove the
duplicate standalone progress card.
- Keep the right result rail current-session only and empty on app launch.
Persisted history remains available in the Artifacts view.
- Retain the bounded, foreground-guarded wheel-to-top reset as the production
path. Treat `B` plus Artifact-tab reopening only as a future live A/B
experiment.
### Consequences
- The primary action matches the common collection-import intent without
hiding a partial numeric default.
- A row limit remains understandable while the helper still receives one
bounded Artifact count.
- Full-inventory start now depends on a trustworthy owned-count read and fails
safely when that evidence is missing.
- The Scanner separates ephemeral run feedback from the durable Artifact
collection and has one clear progress surface.
- The accepted 5/20/50/100 evidence validates the wheel reset and bounded native
engine. Real packaged Settings-UI runs additionally validate Artifact limit 5,
one detected row at 8/8, streaming overlap at 20/20, and the complete owned
target at 2,211/2,211 over 70 pages. The complete corpus passes the current
Review gate at 136/2,211 (6.15%), zero errors, and zero writes. A `B`-based
reset remains only an unaccepted experiment.
## ADR-017: Stream Native Capture Jobs Into Bounded Evaluation Workers
### Status
Accepted. Packaged 20-result and 2,211-result runs prove that evaluated result
cards become visible while native capture is still running; deterministic
service/UI tests cover ordering, deltas, reconciliation, and reduced motion.
### Context
Native capture already appends and flushes one line per crop to
`capture-jobs.jsonl`, but Electron previously opened that queue only after the
helper had captured the complete target. Users therefore saw no results during
long runs and then waited for a second, fully sequential phase. The right-side
result rail also could not explain evaluation independently from capture.
Starting the whole processor repeatedly on every poll would duplicate OCR,
race durable files, and make ordering non-deterministic. Treating a temporary
end-of-file as completion would lose jobs that the still-running producer adds
later.
### Decision
- Start one single-flight processor as soon as the active native run first
exposes a non-empty `runDir`.
- Tail complete JSONL records while the native producer is running. A temporary
empty queue means `waiting`, not completion; a partial final line is retried.
- Deduplicate jobs by sequence, run at most four OCR/parse/evaluation workers,
and publish completed results in canonical capture-sequence order.
- A result reaches the renderer only after extraction review gating and
`roll-efficiency-v1` evaluation have produced its final safe status.
- Keep capture and evaluation counters independent. The left workspace reports
capture progress; the right result surface reports evaluated/target plus
parsed, review, and error counts.
- Load live results as monotonic sequence deltas and reconcile against the full
durable result set before declaring a successful session complete.
- Do not finish processing until capture is terminal and every observed job is
drained. A user stop ends game input immediately but keeps already captured
jobs available for evaluation; the final session outcome remains `stopped`.
- Persist intermediate ordered `scan-results.json` snapshots so a renderer
refresh or process boundary does not make completed work disappear.
### Consequences
- Long scans provide useful, reviewable results before capture ends.
- Capture speed is isolated from OCR latency while bounded concurrency prevents
unbounded CPU/memory growth.
- Single-flight processing, sequence deltas, and final reconciliation prevent
duplicate cards, stale-run leakage, and false-complete summaries.
- The current-session rail can keep all results in top-to-bottom capture order;
newly mounted cards use motion only as an insertion cue and respect reduced
motion.
- Live acceptance must measure actual phase overlap, not infer streaming from a
correct final result count.
- A streaming end-to-end claim must use one shared wall clock from native start
through final result reconciliation. Capture and processing durations are
retained as separate diagnostics and must never be added when they overlap.
## ADR-018: Gate Build-Fit Behind A Versioned Evidence Contract Before Scoring
### Status
Accepted. The contract, validator, native-result adapter, deterministic five-
piece evidence verifier, four sourced profiles, safety tests, legacy production-
path separation, and the separate read-only ranker are implemented. ADR-022
defines the visible ranking/expiry policy; the V1 assessments remain score-free.
### Context
The repository already contained an early preset scorer that could emit
character recommendations and builds from local Artifact records. Its weights,
thresholds, inferred characters, and partial builds were useful as a prototype,
but they had no versioned provenance or validated Build-Fit semantics. Hiding
those suggestions in the Builds UI was not enough while real account snapshots
still calculated them internally.
Roll-Efficiency, OCR confidence, and character/build suitability are different
concepts. A high legal-roll score does not prove that a Set, Main Stat, or
Substat mix fits a target, while low or Review extraction data must never enter
downstream fit logic.
### Decision
- Introduce `build-fit-contract-v1`, `build-fit-input-v1`, and
`build-fit-assessment-v1` as separate shared contracts.
- Require stable identity/revision, game-versioned provenance, explained legal
Set plans, variable-slot Main-Stat priorities, relative Substat weights,
optional full-build aggregate targets, and explicit conflict policies.
- Enforce V1 safety floors of 80% overall extraction confidence and 70% on all
required identity/value fields. Contracts may be stricter but cannot weaken
those floors.
- Require final parsed/non-Review data and a canonical IK Set key. Missing or
uncertain evidence produces reason-coded blockers.
- Map safe facts and conflicts into structured evidence. Verify complete
five-piece slot/Set shape and sourced aggregate context without ranking it,
and keep V1 output at `score: null` plus `recommendationStatus: deferred`
until a sourced profile corpus and ranking formula are validated.
- Record Roll-Efficiency as separate context and never fold it into Build-Fit
eligibility or imply that it is a fit score.
- Stop running real local account snapshots through the legacy scorer. Keep
that implementation limited to explicit demo/test fixtures.
### Consequences
- Sourced profiles and ranking fixtures can evolve on the combination verifier
without changing the scanner/OCR authority boundary.
- Review, low-confidence, incomplete, or non-canonical data fails closed before
any character recommendation.
- The Builds page can show source-bound evidence candidates while remaining
explicit about scope, uncertainty, and missing non-Artifact context.
- No user-facing fit score exists yet; `eligible` means only safe input for a
future ranker.
- Complete-build aggregate targets stay `pending` unless an explicit non-
Artifact contribution references known contract sources; no character,
weapon, or team baseline is guessed.
- The detailed contract and next gates are documented in
[BUILD_FIT_CONTRACT_V1.md](BUILD_FIT_CONTRACT_V1.md).
## ADR-019: Repair Five-Star +0 Main Values Only From Structural Rarity Evidence
### Status
Accepted. The rule is implemented in the OCR parser, covered by positive and
ambiguity-preserving tests, and validated against the complete 2,211-crop corpus.
### Context
The first full-inventory parser pass routed 490 results to Review. Of the 388
low-confidence Main-Value cases, 360 were level 0 and already had four parsed
Substats. A lower-rarity Artifact cannot begin at level 0 with four Substats, so
that combination is structural evidence for five-star rarity. Without that
evidence, a +0 Main Value can be valid at several rarities and must stay
reviewable.
### Decision
- Derive the canonical five-star +0 Main Value only when `level === 0` and
exactly four Substats were parsed.
- Mark the repaired Main Value with explicit parser confidence; do not silently
generalize the rule to three, two, or incomplete Substats.
- Keep all ambiguous rarity cases in Review and retain reason-coded analysis of
the saved corpus.
### Consequences
- Current-package reprocessing reduced Review from 490 to 136 without
reclassifying any previously clean result into Review.
- 360 Main Values were repaired from structural evidence; ambiguous three-
Substat +0 Artifacts remain visible for review.
- Future rarity extraction can replace this inference, but it must preserve the
same fail-closed behavior when rarity evidence is uncertain.
## ADR-020: Target Only Exact Supported Genshin Process Names
### Status
Accepted. Both the native helper and PowerShell fallback use the exact whitelist;
the final packaged no-Genshin safety smoke passed with no source and no errors.
### Context
A broad process-name match containing `Genshin` allowed the assistant process
itself to look like a game target after the real client closed. Reusing a cached
HWND without validating its owning process could preserve the same unsafe state.
### Decision
- Recognize only `GenshinImpact` and `YuanShen` as supported game processes.
- Revalidate every cached HWND against the exact whitelist before returning it;
clear invalid cache state immediately.
- Apply the same behavior to the PowerShell fallback and keep the allow-list
covered by helper/static tests.
### Consequences
- Closing Genshin produces `genshinFound=false`, HWND `0`, an empty target
process, and no capture source even while the assistant remains open.
- New official client process names require an explicit reviewed allow-list
change instead of being picked up accidentally.
## ADR-021: Require Explicit Profile Assumptions And Source-Bound Aggregate Context
### Status
Accepted. The contract requires target assumptions and source-bound aggregate
context; the profile corpus, expiry gate, and Golden/adversarial context tests
are implemented.
### Context
Character recommendations vary with constellation, weapon, teammates, rotation,
and game version. A single ER threshold or Main-Stat order without those
assumptions would look authoritative while silently applying the wrong build
context. Artifact contributions alone also cannot prove a total-build stat such
as Energy Recharge because character and weapon values are outside the scan.
### Decision
- Require every V1 target to list non-empty, unique assumptions alongside its
role and description.
- Store curated candidates in a versioned corpus with game version, review time,
source version, and direct reference.
- Start narrowly with Furina off-field/Solo Hydro C0-C1 from the KQM Furina
Quick Guide labeled `Luna II`; do not generalize its 200%+ ER requirement to
other Hydro counts, C2+, no-Burst teams, weapons, or rotations.
- Treat Substat weights as documented ordinal source order only, never as damage
multipliers or a ranking formula.
- Evaluate a full-build aggregate target only when a complete non-Artifact value
references an allowed curated/user/imported source. Otherwise keep it
`pending`.
- Cross-check profile character and Set keys against vendored IK 6.7.0 data.
### Consequences
- Profiles remain auditable without turning hidden team/weapon assumptions into
Artifact-derived facts.
- Team, weapon, Favonius, and rotation inputs cannot be smuggled in as hidden
constants; callers must provide them explicitly.
- Profile expansion now carries a clear maintenance cost: source review, version
update, catalog validation, Golden fixtures, and adversarial safety cases.
## ADR-022: Rank Only Source-Bound Build-Fit Evidence With Profile Expiry
### Status
Accepted. `build-fit-evidence-ranking-v1`, four profile fixtures, explicit
source expiry, session-only aggregate context, and the read-only Builds surface
are implemented and offline-tested. Packaged renderer acceptance remains open.
### Context
The score-free V1 verifier can prove that five scanned Artifacts are structurally
safe and satisfy a profile's facts, but it intentionally cannot emit a damage
score. Leaving the Builds page locked forever would strand the validated
evidence, while turning Roll-Efficiency, raw OCR confidence, or arbitrary
substat weights into a fit score would overstate what the data proves.
Guide advice also changes with game versions. A version label and review date
alone do not prevent an old profile from silently continuing to rank an account.
Finally, native results are the only renderer-visible data source that preserves
both canonical IK Set IDs and per-field confidence; store records do not.
### Decision
- Keep `build-fit-assessment-v1` and
`build-fit-combination-assessment-v1` score-free (`score: null`).
- Add `build-fit-evidence-ranking-v1` as a separate, bounded, deterministic,
read-only ranker. It considers only complete eligible five-piece combinations
and returns at most three non-overlapping profile suggestions.
- Make the visible `evidenceCoverage` a product-rule coverage measure: sourced
Set-plan tier, variable Main-Stat priority, and ordinal Substat presence. It
is not a DPS, optimizer, Roll-Efficiency, or OCR-confidence score.
- Treat OCR confidence strictly as a hard gate. Do not use roll values, roll
efficiency, character ownership, team, weapon, rotation, or unrecorded
constants as ranking inputs.
- Require `provenance.validUntil` on every profile. Expired profiles fail closed
until a maintainer refreshes their direct source review.
- Permit required aggregate targets only from explicit, user-confirmed,
session-only non-Artifact context that references a declared local/user
source. Missing context keeps the profile deferred; it is never guessed or
persisted.
- Read Builds data only from the newest complete native result run. The Builds
surface does not scan, mutate review/store data, or send game input.
### Consequences
- The app can expose useful, inspectable profile candidates without pretending
that it is a complete optimizer.
- Users see why a candidate ranked and why a profile is deferred, including
missing full-build context or conflicts.
- Profile maintenance has an explicit renewal deadline and source fixture cost.
- A renderer/package acceptance is still required before this UI is called
live-accepted; scanner live evidence is not reused as UI evidence.
## ADR-023: Visuelle Seltenheit fail-closed und Nicht-5★-Ansicht ohne Spielaktion
### Status
Accepted
### Context
Die bisherige Roll-Efficiency-Auswertung kennt rarity-spezifische Regeln, hatte
bei neuen nativen Kartencrops aber keine direkte, persistierte Evidenz für die
sichtbare Sternreihe. Eine aus Level, Main-Value oder Substats abgeleitete
Seltenheit ist für einzelne etablierte Legacy-Regeln nützlich, darf aber eine
fehlende oder widersprüchliche aktuelle Sternreihe nicht stillschweigend in ein
5★-Ergebnis verwandeln.
Gleichzeitig sind explizit erkannte 14★-Artefakte für die Sammlung und
manuelle Sichtung relevant. Daraus folgt jedoch keine sichere
Bergungsentscheidung: Sperr-/Ausgerüstet-Status, Crop, Detaildaten und die
Spieloberfläche müssen weiterhin durch den Nutzer geprüft werden. Automatische
Bergung oder Quick Select wäre eine irreversible Spielaktion und widerspricht
dem Scanner-Sicherheitsrahmen aus ADR-004, ADR-010 und ADR-013.
### Decision
- Aktuelle native Capture-Jobs schreiben die direkte visuelle Stern-Evidenz als
`starCount`, `starConfidence` und `starSource` in den dauerhaften
Ergebnispfad.
- Nur explizit bestätigte 5★-Evidenz darf in `roll-efficiency-v1` eingehen.
Explizit bestätigte 14★-Ergebnisse erhalten `valueStatus: "excluded"` und
keinen Wert, keine Projektion und keine Store-Promotion.
- Wenn visuelle Stern-Evidenz vorliegt, aber `starCount` fehlt, ungültig oder
widersprüchlich ist, wird nicht auf 5★ geraten. Das Ergebnis bleibt `Review`
und seine Evidenz bleibt sichtbar.
- Legacy-Ergebnisse ohne das neue visuelle Sternfeld werden durch diese
Entscheidung nicht rückwirkend als visueller Beweis ausgegeben; für sie
gelten bis zum Rescan die bestehenden strukturellen Regeln.
- Die Inventory-Ansicht bietet einen separaten schreibgeschützten Filter
`Nicht 5★` nur für explizit erkannte 14★-Ergebnisse. Er zeigt Crop/Bild und
Detaildaten zur manuellen Prüfung, nicht die Behauptung "sicher bergbar".
- Es gibt weder eine Scan-Checkbox noch einen Ablauf für automatische Bergung
oder Quick Select. Diese Aktion bleibt verboten und aufgeschoben; ein
zukünftiger Vorschlag bräuchte eine neue explizite Sicherheits- und
Produktentscheidung und dürfte den bestehenden Nicht-Mutationsrahmen nicht
umgehen.
### Consequences
- Nicht-5★-Artefakte bleiben als vollständige, nachvollziehbare
Scan-Ergebnisse sichtbar, ohne die Wertung oder Empfehlungen zu verzerren.
- Die UI trennt klar zwischen `excluded` (direkt erkannte 14★) und `Review`
(unsichere Evidenz), statt beide als schwache 5★-Artefakte darzustellen.
- Replay-, Detail- und Promotion-Pfade müssen Stern-Evidenz, Ausschluss und
Review deterministisch erhalten.
- Der einzige zulässige nächste Schritt für einen Nutzer in der `Nicht 5★`-
Ansicht ist die manuelle Prüfung im Spiel; die App sendet dafür keine
Bergungs-, Auswahl- oder sonstige mutierende Eingabe.
## ADR-024: Default Renderer Copy To English While Preserving The English Scanner Boundary
### Status
Accepted
### Context
The application previously exposed a largely German renderer while its only
validated OCR/crop profile is the English Genshin UI. Treating the two language
concerns as one setting would either make a German-speaking user unable to
choose their application language or incorrectly imply that German Genshin OCR
is supported.
### Decision
- Make English the default renderer locale for a fresh, missing, or invalid
local preference.
- Offer German as a user-selectable Settings preference and persist it locally
under one application-scoped key.
- Keep message catalogs structurally aligned and route renderer copy through the
locale provider rather than hard-coded feature strings.
- Keep the scanner contract explicit: changing the application language changes
application copy only; Smart Capture remains validated for English Genshin.
- Preserve stable semantic UI hooks for renderer acceptance so tests do not
depend on a particular translated label.
### Consequences
- New users receive an English interface by default while German remains
available without a restart.
- The document language and accessible renderer labels track the selected
locale.
- Future Genshin OCR-language support requires separate crop, parser, corpus,
and live-acceptance evidence; it cannot be inferred from this setting.
## ADR-025: Make Artifact Deletion An App-Local Tombstone Workflow
### Status
Accepted
### Context
A wrong OCR read or wrong screenshot needs a way to disappear from the local
Artifact inventory. Directly mutating the game's inventory is prohibited, and
rewriting native `scan-results.json` would destroy the raw evidence needed for
replay, debugging, and corpus review. A delete control also needs to prevent an
active scan from racing a local cleanup.
### Decision
- Expose a confirmed local-delete control only in artifact detail.
- For native results, append an immutable entry to `deleted-results.jsonl` and
filter it at load time instead of rewriting `scan-results.json`.
- Delete a crop only after its resolved path is proved to be a PNG contained by
the selected native run directory.
- Block deletion while the target native run or its processor is active; make a
repeat deletion idempotent.
- Allow Store deletion only for one exact local record: either a Store-only row
or an explicitly selected record linked to the deleted native result.
- Keep the whole workflow behind main-process IPC. It must never focus Genshin,
call the input helper, or dispatch a game action.
### Consequences
- Users can correct local inventory mistakes without jeopardizing the game or
losing raw scan evidence.
- Tombstones become part of the local run contract and loaders/replay tooling
must apply them deliberately.
- The UI must communicate that the action removes app-local data only, and
confirmation remains mandatory because local data and screenshots can be
removed.
## ADR-026: Persist First-Observed Native Run Timing On One Shared Clock
### Status
Accepted
### Context
Native capture and downstream OCR/parse work overlap. Earlier reports could
show phase rates but did not retain one durable, validated endpoint-to-endpoint
clock for the current run. Adding capture and processing durations would double
count their overlap and produce a misleading end-to-end claim.
### Decision
- Write atomic `run-timing.json` records using
`native-scanner-run-timing-v1` in each native run directory.
- Record the first valid observation of request start, native scanner start,
capture start/end, processing start/end, durable result write, and final
result reconciliation. Later polling or retries cannot replace a marker.
- Derive request-to-durable and request-to-reconciled milliseconds directly from
their timestamps and validate marker ordering.
- Require a complete valid timing record and final count reconciliation for a
live streaming/end-to-end claim.
### Consequences
- Capture, processing, and end-to-end rate can be reported as distinct metrics
without double counting overlap.
- A historical timing observation cannot stand in for current-build live
evidence.
- Timing files are durable diagnostic evidence and must be included in native
smoke validation, not merely displayed in the renderer.
@@ -0,0 +1,117 @@
# Localization, Local Deletion, Timing, and OCR Corpus Checkpoint
Date: 2026-07-11
Status: implementation, offline-validation, and current-build live-smoke
checkpoint. The non-persisting 50-artifact development smoke passed on
2026-07-11; its durable evidence is in
[NATIVE_SCANNER_LIVE_SMOKE_2026-07-11.md](NATIVE_SCANNER_LIVE_SMOKE_2026-07-11.md).
An elevated packaged executable remains a separate package-runtime boundary and
is not claimed here.
## Delivered Scope
### English-default renderer with German Settings option
- `en` is the default for a fresh, missing, or invalid persisted locale.
- Settings exposes English and German; the selected app locale is persisted
locally and keeps the document language in sync.
- Visible app-shell, navigation, Scanner, Artifacts, Review, Builds, Overlay,
Diagnostics, Settings, and local-delete chrome use the renderer translation
catalog. Source/domain evidence remains deliberately distinct from translated
UI chrome.
- The setting changes application copy only. Smart Capture remains validated
for the English Genshin UI; it does not claim German Genshin OCR/crop support.
- The package UI runner uses stable `data-*` hooks instead of translated text
for core interaction checks.
### Local artifact removal
The delete control corrects app-local data only. It is not a Genshin action.
| Selected row | Local effect | Preserved / prohibited behavior |
| --- | --- | --- |
| Native scan result | Appends a `deleted-results.jsonl` tombstone, hides the row, and removes its crop only if the resolved PNG stays inside the selected run directory. | Raw `scan-results.json` remains replay evidence. Active capture/processing blocks removal. No input helper or game action is called. |
| Exact Store record linked to native row | Removed only when the user explicitly includes that exact local record in the confirmed removal. | No broad Store deletion and no inferred record matching. |
| Store-only row | Removes that one explicit local Store record through main-process IPC. | No native scan evidence or Genshin state is touched. |
The workflow is idempotent for an already tombstoned native row. It retains the
native run's raw result array for audit/replay and limits file deletion to
contained PNG paths.
### Shared-clock native run timing
Each native run can now write atomic `run-timing.json` evidence with version
`native-scanner-run-timing-v1`.
- Markers are first-observed and immutable after a valid value is written.
- The record covers request start, native scanner start, capture start/end,
processing start/end, durable results, and final reconciliation.
- `requestToResultsDurableMs` and `requestToResultsReconciledMs` are derived
directly from their endpoints and validated against timestamp ordering.
- Capture and processing remain separate metrics. They may overlap and are
never added to create an end-to-end duration.
### Confirmed OCR corpus changes
The historical 136-result Review population was inspected against saved crops,
not treated as self-labeled training data:
| Audit result | Count | Current behavior |
| --- | ---: | --- |
| Explicit visual 14★ | 128 | Remain excluded/manual-inspection entries, not value-scored parser labels. |
| Confirmed `HP+4..1%` OCR punctuation defect | 6 | Exact duplicated decimal punctuation is repaired to `HP+4.1%`; the regression cases are in the confirmed corpus. |
| Confirmed 5★ partial-name case with direct slot evidence | 1 | The unsafe global alias was removed. Canonicalization is now allowed only when independent high-confidence slot evidence makes one piece valid. |
| Incomplete/malformed 5★ crop | 1 | Remains `Review`; no heuristic converts it into a clean artifact. |
This preserves the fail-closed rule: ambiguous OCR becomes unknown or Review,
not a guessed canonical artifact.
## Offline Evidence Recorded For This Checkpoint
- Focused localization tests cover English fallback, persisted locale behavior,
and English/German catalog-key parity.
- Native deletion tests cover tombstone filtering, raw-evidence preservation,
active-run blocking, contained crop cleanup, idempotency, and exact Store
scope.
- Native timing tests cover first-observation behavior, ordering validation, and
derived durations.
- Parser/corpus evaluation covers the duplicate-decimal repair and slot-safe
name behavior. The latest saved 50-artifact evidence validation completed at
`50/50` with zero validation issues.
- The final current-build offline gate passed after all localization, deletion,
timing, corpus, and acceptance-runner changes: `npm run acceptance:offline`
completed TypeScript, 72 test files / 444 tests, OCR evaluation, saved-run
validation, package verification (27/27), both dependency audits, and the
diff check.
- The built-renderer Builds/UI acceptance passed fresh English, German
selection, English restoration, Builds context/focus, reduced motion,
overflow, and native plus Store local-delete confirmation probes. It did not
launch an elevated packaged executable, so it is not
UAC/preload/helper/native-runtime evidence.
## Remaining Release Gates
1. If a package-runtime/UAC claim is needed, separately launch the elevated
packaged executable and verify its bridge/helper/runtime behavior. Do not
substitute the passed built-renderer UI acceptance for that evidence.
2. The required elevated development 50-artifact smoke now passes: 50/50
capture, click, queue, parse, durable-result reconciliation, zero Review,
zero processing errors, zero Store writes, and a complete valid
`run-timing.json`. It measured `28,022 ms` request-to-reconciliation, so it
does not claim the separate 3/s performance target.
3. Remove generated workspace outputs, commit the coherent checkpoint, and
push the intended branch.
## Follow-on Quality Phase
- Extend the corpus only from visually confirmed crops and preserve ambiguity as
`Review`.
- Refresh Build-Fit source profiles before their explicit expiry and add Golden
plus adversarial fixtures for each profile expansion.
- Keep the bounded wheel reset as the production baseline; test any alternate
inventory-entry/reset choreography as a separate guarded experiment.
- Keep Builds read-only and Artifact-only until a separately sourced product
decision introduces character, weapon, team, or rotation inputs.
@@ -0,0 +1,235 @@
# Native Scanner Live Acceptance - 2026-07-10
## Ergebnis
Die Artifact-first Scanner-Kette ist fuer den validierten Zustand `1920x1080`,
16:9, englische Artifact-Inventaransicht mit sichtbarer Detailkarte live
abgenommen. Dev- und Packaged-Runtime nutzten denselben Runtime-Vertrag
`2026-07-10-packaged-runtime-acceptance`. Alle Scans blieben read-only und
liefen mit `persist=false`.
Die Abnahme umfasst inzwischen auch das komplette OCR-bestaetigte Inventar:
Run `20260710-223233` erfasste exakt 2.211 Artifacts ueber 70 Seiten. Der erste
Parserstand verfehlte den Review-Grenzwert ehrlich; nach einer strukturell
belegten +0-Korrektur reprozessierte das aktuelle Paket denselben vollstaendigen
Corpus mit 136 Review (6,15%), 0 Fehlern und 0 Store-Writes. Der gespeicherte
Run-Validator meldet 0 Issues.
Der Scanner-Core darf damit in die naechste Produktphase uebergehen. Der
strikte End-to-End-Zielwert von drei Artifacts pro Sekunde ist dagegen nicht
erreicht und wird nicht behauptet.
## Live-Matrix
| Runtime | Run | Ziel | Seiten | Reset | Capture | Capture/s | Processing | Processing/s | Review | Fehler | Store |
| --- | --- | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: | ---: |
| Dev | `20260710-102344` | 5 | 1 | 1.701 ms | 1.123 ms | 4,45 | 1.806 ms | 2,77 | 0 | 0 | 0 |
| Dev | `20260710-102421` | 20 | 1 | 1.704 ms | 4.443 ms | 4,50 | 6.430 ms | 3,11 | 0 | 0 | 0 |
| Dev | `20260710-102450` | 50 | 2 | 1.744 ms | 11.328 ms | 4,41 | 15.579 ms | 3,21 | 0 | 0 | 0 |
| Dev | `20260710-102547` | 100 | 4 | 1.718 ms | 22.877 ms | 4,37 | 31.731 ms | 3,15 | 0 | 0 | 0 |
| Packaged | `20260710-103736` | 5 | 1 | 1.702 ms | 1.162 ms | 4,30 | 1.801 ms | 2,78 | 0 | 0 | 0 |
| Packaged streaming UI | `20260710-201614` | 20 | 1 | 1.701 ms | 4.486 ms | 4,46 | 8.032 ms | 2,49 | 0 | 0 | 0 |
| Packaged full inventory | `20260710-223233` | 2.211 | 70 | 1.739 ms | 522.005 ms | 4,24 | 722.164 ms | 3,06 | 490* | 0 | 0 |
`*` Der Vollinventar-Runner lehnte diesen ersten Endstand wegen 22,16% Review
korrekt ab. Die anschliessende Reprozessierung mit dem reparierten aktuellen
Parser verarbeitete 2.211/2.211 in 689.049 ms (3,21/s) und endete bei 136 Review
(6,15%), 0 Fehlern, 0 Writes und 2.211 Results. Capture/Streaming und aktuelle
Parserqualitaet sind damit als zwei explizite, gespeicherte Evidenzschritte
akzeptiert; ein nachtraeglich behaupteter Ein-Pass-Lauf wird nicht erfunden.
Die fruehere `1,77/s`-Aussage beschreibt ausschliesslich den historischen,
seriellen Dev-100-Smoke: `100 / (24.623 ms Reset/Capture + 31.731 ms
Batch-Processing)`. `native-live-smoke.ps1` wartete dort bewusst auf das
Capture-Ende und startete erst danach den Processor. Die Zahl ist rechnerisch
korrekt, aber keine aktuelle End-to-End-Messung der Streaming-Pipeline.
Der erneute erhoehte Streaming-Livetest am 2026-07-11 (`20260711-090019`)
lief dry mit 20/20 Capture, Parse und Resultaten, 0 Review, 0 Fehlern und 0
Writes. Das erste Resultat war sichtbar, bevor Capture endete. Die gemessenen
Teilwerte waren `4,43 Capture/s` (`4.517 ms` active) und `7.668 ms`
Processor-Laufzeit; die beobachtete Zeit vom Startrequest bis zur finalen
Result-Reconciliation betrug `8.370 ms` (`2,39/s`). Diese kleine,
clientseitige Beobachtung ist kein allgemeiner Durchsatzclaim, weil der
gemeinsame Clock-Contract noch nicht als dauerhafter Run-Wert gespeichert wird.
Bei ueberlappenden Phasen duerfen Capture- und Processing-Dauer nie addiert
werden. Kuenftige End-to-End-Claims muessen Start, Capture-Start/-Ende,
Processing-Start/-Ende und finale Result-Reconciliation auf einer gemeinsamen
Wall-Clock belegen; Capture- und Processing-Raten bleiben getrennte Werte. Das
3/s-Gesamtziel ist weiterhin nicht bewiesen.
## Qualitaets- und Dateivertraege
- Alle neuen 5/20/50/100-Runs hatten exakt so viele Jobs, PNGs, Klicks,
verarbeitete Zeilen und geladene Results wie angefordert.
- Jeder Job war an genau eine nichtleere `artifact-NNNN.png`, eine eindeutige
Sequenz, den erwarteten absoluten Pfad und genau zwei Click-Events gebunden.
- Der 100er verteilte sich auf `32/32/32/4` Captures ueber vier Seiten.
- Der Validator fand im 100er keine PNG-Hash-Duplikatgruppen, keine komplett
wiederholten Seiten und keine identischen Seiten-Grenzpaare.
- Der Vollinventar-Run enthielt exakt 2.211 Jobs, PNGs und Results. Der letzte
Job war Sequenz 2.211 auf Seite 70, Zeile 0, Spalte 2, passend zur partiellen
Schlussseite nach 69 vollen 32er-Seiten.
- Der gespeicherte Vollinventar-Validator fand zwar vier Gruppen identischer
Einzel-Crops, aber keine wiederholten Seitenpaare und keine identischen
Seiten-Grenzpaare; sein gesamter Run-Vertrag bestand mit 0 Issues. Identische
Einzelkarten werden daher nicht mit einem haengenden Scroll verwechselt.
- Der aktuelle Vollinventar-Replay ist ueber fuenf Wiederholungen deterministisch:
2.075 Results sind `evaluated`, 136 bleiben `review`, 0 sind `unknown`.
1.952 unterlevelte Results haben eine Projektion, 123 sind bereits komplett.
- Fuenf Offline-Replays des neuen 100ers waren hashidentisch. Alle 100 Results
waren `parsed` und `evaluated`; Scorebereich `76.1-92.5`, 0 Review, 0 unknown.
- Die neuen 100 Artifacts waren alle +20, daher korrekt 0 offene Projektionen.
Die Projektionslogik bleibt durch die vorhandene Offline-Evidenz fuer
unterlevelte Artifacts abgedeckt.
- Artifact-Store und `review-samples.jsonl` waren innerhalb jedes Dry-Runs vor
und nach dem Scan bytegleich. Die Review-Datei blieb bei
`83A222F49E7246054B16363C0CA7083168F7CE0AB595916313B44CB279BF9B8C`.
## Safety-Nachweise
- Probe-Klick: Genshin-Fenster, erkanntes 4x8-Grid, sichtbare Detailkarte und
geaenderter Detail-Fingerprint wurden vor dem breiten Lauf bewiesen.
- Fokusverlust-Run `20260710-101820`: `blocked`, 0 Klicks, 0 Captures; der
Helper refokussierte nicht automatisch.
- Stop-Run `20260710-102735`: Stop waehrend des Initial-Resets nach `87 ms`,
Status `stopped`, 0 Klicks, 0 Captures.
- Foreground-HWND wird vor jedem Reset-/Scroll-Event, Klick und Crop-Capture
geprueft. ESC, Enter, F9 und expliziter Stop bleiben auch im Reset aktiv.
- Der vollstaendige Top-Reset bleibt auf 3.200 Events begrenzt, pausiert aber
nur noch nach jeweils 39 Events. Live sank er dadurch von `50.698 ms` auf
stabil rund `1.7 s`, ohne Guard oder Reichweite zu lockern.
- Native Helper und PowerShell-Fallback erkennen nur die exakten Prozessnamen
`GenshinImpact` oder `YuanShen` und validieren gecachte HWNDs erneut. Nachdem
das Spiel waehrend der Reprozessierung extern geschlossen war, konnte die App
sich dadurch nicht mehr selbst als Genshin-Ziel erfassen. Der finale
No-Genshin-Smoke meldete `genshinFound=false`, HWND 0, leeren Zielprozess,
keine Capture-Quelle und 0 Renderer-/Konsolenfehler.
## Packaged-Runtime
- Start aus `%TEMP%`, `isDev=false`, Runtime und Helper-Guard beide
`isElevated=true`.
- Renderer wurde aus `resources/app.asar` geladen; relative Vite-Assets waren
vorhanden.
- Helper lief aus `resources/input-helper/InputHelper.exe`.
- IK 6.7.0 wurde aus `resources/ik-inventorylists` geladen: 61 Sets,
289 Pieces.
- Die Preload-Bridge stellte 36 erwartete Methoden bereit.
- Vor dem neuen Scan wurde automatisch der neueste vollstaendige 100er geladen;
neuere gestoppte oder unprozessierte Runs wurden korrekt ignoriert.
- Der paketierte 5er lief ueber Renderer -> Preload -> IPC -> C# Helper und
bestand Capture, Processing, Result-Load und Non-Persistence.
- Finale Inventory-Ansicht: 5/5 geparst, 0 Review, 5 bewertet,
`0 speicherbar - 5 im Store - 0 Review - 0 blockiert`.
- Der aktuelle paketierte Renderer bestand zusaetzlich den echten
Settings-UI-Pfad `Eigenes Limit -> Reihen -> 1`: das erkannte 8-Spalten-Raster
ergab Ziel 8; Run `20260710-180851` endete mit 8/8 Captures, 8/8 Processing,
8/8 Parsing, 0 Review, 0 Fehlern und `persist=false`. Der Top-Reset brauchte
1.715 ms. Zwei vorherige Vordergrundverluste blockierten sicher mit 0 Klicks.
- Der echte Settings-UI-Streamingpfad mit Artifact-Limit 20 bewies die
Phasenueberlappung: waehrend der Helper noch `running` meldete, waren bereits
11 Ergebnisse komplett geparst, bewertet und in der Rail sichtbar. Neue
Karten verwendeten die konfigurierte Slide-in-Mountanimation. Final standen
20 eindeutige Sequenzen 1-20, 20 evaluierte Results, 0 Review, 0 Fehler und
0 Persistenzwrites. Der Dokument-Viewport blieb 1304x821 ohne Overflow; die
Ergebnis-Rail scrollte intern.
- Der Vollinventar-Settings-Pfad las als Ziel ausschliesslich den aktuellen
OCR-Besitzwert 2.211, nie die Kapazitaet. Capture erreichte 2.211/2.211 auf 70
Seiten, waehrend der laufenden Erfassung waren bereits bis zu 1.656 Result-
Rows und 1.659 Auswertungen sichtbar, alle 2.211 Zeilen standen am Ende in der
Rail, die Slide-in-Mountanimation wurde beobachtet und der 1304x821-Dokument-
Viewport blieb ohne Overflow.
- Das paketierte `reprocess-run`-Gate reprozessierte denselben Corpus mit dem
aktuellen Parser vollstaendig und non-persistent: 2.211 processed/parsed,
136 Review, 0 Fehler, 0 gespeichert, 2.211 Result-Eintraege.
Lokale Evidenz zum Abnahmezeitpunkt:
Die folgenden Pfade bezeichneten temporaere lokale Testartefakte. Sie wurden
bei der angeforderten Workspace-Bereinigung am 2026-07-11 entfernt; die oben
dokumentierten Run-IDs, Messwerte und Vertragspruefungen bleiben der dauerhafte
Nachweis.
- `outputs/offline-acceptance/offline-acceptance-report.json`
- `outputs/packaging/offline-package-report.json`
- `outputs/native-live-smoke/20260710-102341/`
- `outputs/native-live-smoke/20260710-102418/`
- `outputs/native-live-smoke/20260710-102447/`
- `outputs/native-live-smoke/20260710-102544/`
- `outputs/native-replay/saved-native-validation-report.json`
- `outputs/packaged-live/packaged-final-scan5.json`
- `outputs/packaged-live/packaged-final-inventory-fixed.json`
- `outputs/packaged-live/packaged-final-inventory-fixed.png`
- `outputs/packaged-live/final-artifact-probe.json`
- `outputs/packaged-live/final-ui-row1-pass.json`
- `outputs/packaged-live/final-ui-row1-pass.png`
- `outputs/packaged-live/streaming-ui-20.json`
- `outputs/packaged-live/streaming-ui-20.png`
- `outputs/packaged-live/streaming-ui-20-results-view.json`
- `outputs/packaged-live/streaming-ui-20-results-view.png`
- `outputs/full-inventory-phase/packaged-preflight-restored.json`
- `outputs/full-inventory-phase/packaged-ui-full-inventory.json`
- `outputs/full-inventory-phase/packaged-ui-full-inventory.png`
- `outputs/native-review-analysis/20260710-223233/native-review-analysis.json`
- `outputs/full-inventory-phase/packaged-reprocess-2211.json`
- `outputs/full-inventory-phase/packaged-reprocess-2211.png`
- `outputs/full-inventory-phase/packaged-no-genshin-safety.json`
- `outputs/full-inventory-phase/packaged-no-genshin-safety.png`
## Waehrend der Abnahme behobene Fehler
1. Eigene App-Titel mit `Genshin` konnten als Capture-Quelle erscheinen.
2. Dev-Cleanup konnte den Codex-CUA-Node allein wegen seines Working Directory
als alte App-Instanz klassifizieren.
3. Native Runs starteten nicht garantiert am Inventaranfang und prueften den
Foreground nicht waehrend jedes Input-Schritts.
4. Der sichere Initial-Reset dauerte wegen Windows-Timer-Rundung etwa 50 s.
5. Smoke-Gates akzeptierten zu schwache Summen-/Cleanup-Vertraege.
6. Run-Aufloesung konnte ohne explizites `runDir` unvollstaendige Runs waehlen.
7. Packaged Runtime-Pfade und absolute Vite-Assets konnten durch das Repo-CWD
kaschiert werden.
8. Helper-Guard verlor das echte Elevation-Signal.
9. Inventory-Metriken lagen wegen einer impliziten dritten Grid-Zeile ueber der
View; ein Store-Duplikat mit unsicherem optionalem Feld erschien irrefuehrend
als Promotion-Review.
10. Capture und Auswertung liefen seriell; die Result-Rail blieb bis zum Ende
leer. Der Processor tailt jetzt JSONL, ist pro Run single-flight, liefert
Sequenz-Deltas und reconciled vor dem Abschluss den Vollbestand.
11. Vier-Substat-+0-Fuenfsterne wurden wegen OCR-unsicherem Main Value
uebermaessig in Review geschickt. Nur die strukturell eindeutige Kombination
`level === 0` plus vier Substats erhaelt jetzt den kanonischen Fuenfsterne-
Startwert; Drei-Substat-Faelle bleiben absichtlich unsicher.
12. Eine breite Prozessnamensuche konnte die eigene App als Genshin erkennen.
Exakte Allowlist und gecachte-HWND-Revalidierung schliessen dieses Ziel aus.
13. Die Scan-Zusammenfassung addierte Capture- und Processing-Zeit trotz echter
Ueberlappung. Sie verwendet jetzt die groessere Wall-Clock-Zeit.
## Offene Grenzen und naechste Phase
- Aktiv bleibt nur Artifact-Scanning. Weapons, Materials und Character Details
sind weiterhin Katalogdaten, keine Scannerfeatures.
- Nicht-16:9, andere Sprachen und ungewoehnliche UI-Zustaende bleiben bewusst
blockiert, bis eigene Profile live validiert sind.
- Der Renderer-Chunk von rund 586 kB und das Default-Electron-Icon sind
nicht-blockierende technische/cosmetische Arbeit.
- Eine echte Review-Korrektur oder Promotion wurde nicht absichtlich in den
Store geschrieben. Die statischen und Main-Process-Gates bestehen; der
Mutation-Pfad bleibt ein separater, explizit bestaetigter QA-Fall.
- Die verbliebenen 136 Review-Faelle des kompletten Corpus sind der naechste
Scanner-Qualitaetsbestand: 128 tragen `substats_implausible`, 65
`substats_incomplete`, 28 eine niedrige Main-Value-Konfidenz und 4 einen
IK-Mismatch; Gruende koennen sich ueberlappen. Sie werden nicht automatisch
als sauber umetikettiert.
Die score-freie Grundlage von `build-fit-contract-v1` ist inzwischen
implementiert: gesourcte Eingaben, OCR-/Review-Gates, Set-/Mainstat-/Substat-
Regeln, Gesamtziele und Konflikte sind versioniert, waehrend echte lokale
Snapshots keine Legacy-Demo-Empfehlungen mehr erzeugen. Der deterministische
Fuenfer-Verifier prueft inzwischen Slot-/Set-Form, verschachtelte Gates,
gesourcte Gesamtwerte und Konflikte, bleibt aber score-frei. Ein erster enger
Furina-`Luna II`-Candidate ist samt IK-Key- und Kontext-Fixtures versioniert.
Vor sichtbaren charakterbezogenen Empfehlungen fehlen weiterhin breitere
Profile, eine validierte Rangfolge und weitere Golden Fixtures fuer sichere
sowie adversarielle Eingaben. Das ist jetzt die aktive Produktphase.
@@ -0,0 +1,43 @@
# Native Scanner Current-Build Live Smoke - 2026-07-11
## Result
The required current-build, elevated development smoke passed against the
accepted English 16:9 Genshin Artifact inventory with a visible detail card.
The scanner remained read-only and ran with `persist=false`.
| Contract | Result |
| --- | --- |
| Run ID | `20260711-154827` |
| Requested / target / captured / clicked / queued | `50 / 50 / 50 / 50 / 50` |
| Processed / parsed / loaded | `50 / 50 / 50` |
| Pages | `2` |
| Review / processing errors | `0 / 0` |
| Store writes / persisted | `0 / false` |
| Jobs / non-empty PNGs | `50 / 50` |
| Visual preflight | Genshin found, 16:9, 4x8 grid, visible Artifact inventory |
| Read-only probe | Detail fingerprint changed before the run |
The run wrote a complete `native-scanner-run-timing-v1` record. Its
request-to-durable-results duration was `27,916 ms`; final reconciliation
completed at `28,022 ms` from the request start. That is approximately
`1.78 Artifacts/s` end-to-end for this exact smoke. Capture and processing are
reported separately; they are not added together.
## Scope And Non-Claims
- This is an elevated **development** runtime smoke, not an elevated packaged
executable acceptance.
- It proves the current 50-item functional/safety/reconciliation gate, not the
three-Artifacts-per-second product target.
- It did not write to the local Artifact Store and did not modify Genshin.
- The raw run remains local runtime evidence. The generated workspace summary
is intentionally disposable after this durable record is updated.
## Follow-Up
The required scanner release gate is complete. The next approved actions are
workspace cleanup, a coherent repository commit, and push of the current
checkpoint. The remaining quality work is visually confirmed corpus growth,
source-profile refresh, and a separate elevated packaged-runtime check only if
that specific binary-runtime claim is needed.
@@ -1,5 +1,9 @@
# Native Artifact Scanner Validation - 2026-07-09
Historical first-session evidence. The later-session and packaged acceptance
that was still deferred here passed on 2026-07-10; see
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).
This report records the first bounded 20/50/100-item validation of the native
Artifact capture and post-capture processing path. All runs used the visible
1920x1080 16:9 Artifact inventory, category `artifacts`, and `persist=0`.
@@ -82,3 +86,21 @@ next implementation focus from capture expansion, promotion, and single-result
review to deterministic Artifact value evaluation. The visible-inventory path
remains the production baseline until packaged behavior and later-session
native repeatability are also proven.
## Offline Follow-Up - 2026-07-10
The saved 20/50/100 native runs were replayed through the new deterministic
roll-efficiency evaluator without opening Genshin or sending input:
| Saved run | Results | Evaluated | Review | Projection | Deterministic repeats |
| --- | ---: | ---: | ---: | ---: | ---: |
| `20260709-223006` | 20 | 20 | 0 | 0 | 5/5 |
| `20260709-223041` | 50 | 49 | 1 historical | 0 | 5/5 |
| `20260709-223441` | 100 | 100 | 0 | 9 | 5/5 |
This proves deterministic offline processing of the saved evidence, not a new
live scanner run. The complete implementation and package evidence is recorded
in
[ARTIFACT_EVALUATION_OFFLINE_VALIDATION_2026-07-10.md](ARTIFACT_EVALUATION_OFFLINE_VALIDATION_2026-07-10.md).
The next live and packaged-app acceptance pass is intentionally deferred to
[TOMORROW_LIVE_TEST_PLAN_2026-07-10.md](TOMORROW_LIVE_TEST_PLAN_2026-07-10.md).
+221 -72
View File
@@ -8,13 +8,22 @@ 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).
For the completed evaluation/offline phases and executed live acceptance, see
[ARTIFACT_EVALUATION_OFFLINE_VALIDATION_2026-07-10.md](ARTIFACT_EVALUATION_OFFLINE_VALIDATION_2026-07-10.md)
and [NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md),
plus the current-build [NATIVE_SCANNER_LIVE_SMOKE_2026-07-11.md](NATIVE_SCANNER_LIVE_SMOKE_2026-07-11.md).
For the score-free Build-Fit V1 data and safety contract, see
[BUILD_FIT_CONTRACT_V1.md](BUILD_FIT_CONTRACT_V1.md).
For the current English-default UI, local-result removal, timing, and reviewed
OCR-corpus checkpoint, see
[LOCALIZATION_LOCAL_DELETION_TIMING_CHECKPOINT_2026-07-11.md](LOCALIZATION_LOCAL_DELETION_TIMING_CHECKPOINT_2026-07-11.md).
## Project Identity
| Field | Value |
| --- | --- |
| Project name | Genshin Artifact Assistant |
| Status | Artifact-first scanner baseline with native IK-style 20/50/100 scale evidence, explicit selected promotion, review/edit/approve, scan result rail, and Artifact-only Inventory pipeline; value scoring and later-session repeatability are next |
| Status | Artifact-first native scanner with historical live-accepted dev 5/20/50/100, packaged bounded/UI paths, and a complete packaged 2,211-Artifact inventory soak; scanner-first Galaxy UI, explicit review/promotion gates, deterministic roll-efficiency, an English-default/Deutsch-selectable app UI, local-only artifact removal, durable timing evidence, and an offline-tested source-bound Build-Fit evidence-ranking layer. The current-build elevated-dev 50-artifact smoke now passes its functional/safety gate; the 3/s performance target remains separate and unproven. |
| Platform | Windows desktop |
| Target users | Genshin Impact players who want artifact decisions without complex optimizer setup |
| Runtime | Electron app with React UI and TypeScript |
@@ -32,8 +41,14 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
- 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.
- Make scan readiness, the primary scan action, progress, and safe next steps understandable without opening technical views.
- Make the primary scan cover the recognized owned Artifact inventory by
default, while allowing an explicit limit by Artifact count or grid rows.
- 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.
- Die sichtbare Sternreihe einer nativen Artefaktkarte direkt erfassen: Nur
explizit bestätigte 5★-Artefakte erhalten eine Roll-Efficiency-Bewertung;
bestätigte 14★-Artefakte bleiben als manuell prüfbare Ergebnisse erhalten.
- Keep the app offline-first and usable without optimizer imports, Enka, HoYoLAB,
or any external scanner as a core dependency.
- Re-introduce recommendations only after the scanner base is trustworthy.
@@ -41,7 +56,9 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
## Non-Goals
- No memory reads, process hooks, game modification, packet inspection, or anti-cheat bypassing.
- No automatic deleting, feeding, enhancing, or spending resources.
- Keine automatische Bergung, Quick-Select-Auswahl, Löschung, Fütterung,
Verbesserung, Sperr-/Entsperraktionen oder Ressourcenverbrauch — auch nicht
für erkannte 14★-Artefakte.
- No advanced formula editor or full power-user optimizer in the MVP.
- No cloud sync by default.
@@ -56,19 +73,24 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
| FR-005 | Run a stable automatic inventory scan: detect grid, click tile, verify detail change, parse, store, continue, scroll, resume. | Must | Implemented for visible-inventory baseline |
| FR-006 | Save low-confidence, failed, conflicting, or stale scans automatically as review samples with reason codes. | Must | Implemented baseline |
| FR-007 | Apply local learned fixes from review corrections before every new parse. | Must | Implemented baseline |
| FR-008 | Keep the scan UI operator-friendly: main preview first, debug in modals or drawers, completion summary after scan. | Must | Implemented baseline |
| FR-008 | Keep the scan UI operator-friendly: readiness and primary action first, preview plus result rail during scanning, debug in collapsed or secondary surfaces. | Must | Implemented scanner-first baseline |
| 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 | Partial foundation |
| FR-013 | Provide a scanned artifact inventory view with compact score pills, filters, sorting, and click-through detail. | Should | Partial foundation |
| FR-014 | Provide artifact detail evaluation with screenshot/crops, parsed fields, OCR confidence, value reasons, and optional upgrade projection. | Should | Planned |
| 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 | Implemented baseline |
| FR-013 | Provide a scanned artifact inventory view with compact score pills, filters, sorting, and click-through detail. | Should | Implemented baseline |
| FR-014 | Provide artifact detail evaluation with screenshot/crops, parsed fields, OCR confidence, value reasons, and optional upgrade projection. | Should | Implemented; packaged visual acceptance passed, under-level projection remains corpus-backed |
| FR-015 | Provide clear loading, success, review, blocked, and error feedback through progress, spinners, skeletons, and mutation toasts without hiding durable state. | Should | Implemented UI baseline |
| FR-016 | Die sichtbare Sternreihe je nativer Artefaktkarte erfassen; nur explizit bestätigte 5★-Artefakte bewerten, bestätigte 14★-Artefakte ohne Wertung mit Bild und Details in einer separaten schreibgeschützten `Nicht 5★`-Ansicht zeigen. | Must | Implementiert; aktueller 50er-Smoke bestanden |
| FR-017 | Provide an English-default application interface and let the user switch the renderer to German in Settings without changing the scanner contract. | Should | Implemented; built-renderer acceptance passed, elevated packaged-executable runtime remains separate |
| FR-018 | Let the user remove an incorrectly scanned artifact from local app data only, including its local crop when safe, without any Genshin mutation. | Should | Implemented, unit tested, and confirmation paths exercised; no data-removing test was run |
## Non-Functional Requirements
| Category | Requirement | Measurement |
| --- | --- | --- |
| Safety | Never perform irreversible in-game actions. | Code review and manual test |
| Evaluation safety | Explizit visuelle 14★-Evidenz wird ausgeschlossen; fehlende, widersprüchliche oder unsichere Stern-Evidenz geht in `Review`. | Result-/Replay-Tests und Detailprüfung |
| Performance | Single artifact read should feel interactive and batch scan should not stall on false progress. | Capture latency monitored manually; auto-scan stops on blocked verification |
| Performance | A 100-artifact visible-inventory run should finish cleanly with low review/miss rates and report timing evidence. | `npm run scan:goal:validated` or `npm run scan:goal:validated:wait` quality-gated report |
| Privacy | Captures and parsed data stay local by default. | No remote upload in scanner path |
@@ -76,18 +98,20 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
| 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 |
| Usability | The default path should expose one primary next action and keep advanced controls secondary. | Scanner-first navigation and desktop visual acceptance |
| Accessibility | Focus, status, loading, and motion must remain understandable without relying on animation or color alone. | Keyboard review, ARIA status semantics, and `prefers-reduced-motion` |
## Tech Stack
| Area | Choice | Notes |
| --- | --- | --- |
| Desktop shell | Electron | Windows local app and overlay windows |
| Desktop shell | Electron 43 | Windows local app and overlay windows |
| Frontend | React + TypeScript + Vite | UI and client state |
| Styling | CSS with dark purple glassmorphism system | Premium fintech-inspired visual direction |
| Styling | CSS design tokens with dark Galaxy glass surfaces | Cinematic depth with restrained violet, cyan, gold, and semantic state accents |
| OCR | Tesseract.js prototype plus deterministic normalization/derivation | OCR alone is not trusted as the decision source |
| Capture | Electron desktopCapturer plus Windows GDI Smart Capture | GDI path is used for Genshin Smart Capture reliability |
| Input automation | C# sidecar with elevated dev runner when needed | Live-validated for read-only inventory selection clicks; see `docs/AUTOMATION_LIVE_SCAN.md` |
| Tests | Vitest + TypeScript checks | Current validation baseline; regression samples must expand |
| Tests | Vitest 4 + TypeScript checks | OCR eval, helper/cleanup safety, Build-Fit contract/combination/profile/ranking/context gates, localization/deletion/timing tests, packaged acceptance runners, and saved-run replay |
| Packaging | electron-builder | Configured in `package.json` |
## Runtime
@@ -97,6 +121,10 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
| Local dev | `npm run dev` | Starts Vite and Electron |
| Local dev with automation | `npm run dev:admin` | Required when `GenshinImpact.exe` is elevated; Windows blocks lower-integrity cursor/click input |
| Production build | `npm run build` | Builds React and Electron main process |
| Complete non-live gate | `npm run acceptance:offline` | Runs tests, OCR/assessment gates, saved-run validation, fresh package build/verification, audits, and diff checks |
| Unpacked package | `npm run package:offline-check` | Builds helper/app and verifies ASAR/resources without launching Genshin |
| Saved-run replay | `npm run scan:native:replay` | Re-evaluates the newest existing native scan without capture or input |
| Saved-run evidence set | `npm run scan:native:validate:saved` | Validates requested accepted targets (bounded 20/50/100 or full 2,211), files, review provenance, replay, and projection boundaries without capture or input |
| Preview | `npm run preview` | Browser preview only; capture bridge is unavailable |
## Current State Review
@@ -108,8 +136,8 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
- A local canonical data package already exists in `src/data/genshinGameData.json`, generated from `genshin-db`.
- The parser already uses known sets, pieces, slots, stat aliases, set aliases, character aliases, and derived slot/set mapping.
- Review samples, learned replacements, parser notes, and stored artifacts already persist locally.
- The scan surface has an initial recent-results rail backed by the newest
stored artifacts.
- The scan surface has a current-session result rail that starts empty; older
persisted Artifacts remain available in the dedicated inventory view.
- The auto-scan loop is no longer a naive click spammer: it has preflight, verification, miss handling, page fingerprinting, and stop conditions.
- The scanner now has a validated visible-inventory path: 32 safe artifact
targets per page, lookup-derived fields, fast OCR crop profile, and a
@@ -133,16 +161,56 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
- Native IK-style Artifact capture is wired through the C# helper. It writes
card crops and run artifacts for downstream OCR/parse processing instead of
making React do per-artifact work in the hot capture loop.
- The native post-capture processor can write `scan-results.json` and
`processing-report.json`, preserve parser field confidence, match Artifact
results against IK artifact set/piece/slot data, and keep store persistence
opt-in.
- The native result processor tails flushed capture jobs while the helper is
still scanning, evaluates them with four bounded workers, publishes ordered
live deltas, and writes incremental `scan-results.json` plus
`processing-report.json`. Parser confidence and IK set/piece/slot conflicts
remain reviewable, and store persistence stays opt-in.
- The Inventory view now has an Artifact-only pipeline surface for scope,
native capture, OCR queue, review gate, promotion, and evidence. Native rows
expose crop previews, IK/GOOD metadata, dry-run promotion state, and a
`Naechster Schritt` card.
- The active UI intentionally hides weapon, material, and character-detail IK
catalog coverage until those values are actually scanned.
- Clean Artifact results now receive deterministic `roll-efficiency-v1`
evaluations. Inventory/detail show score reasons and legal roll breakdown;
build fit remains explicitly deferred.
- Under-leveled, unambiguously identified 5-star Artifacts with four known
substats receive a detail-only Worst/Middle/Best projection. 4-star,
rarity-ambiguous, incomplete, or review data receives none.
- Existing 20/50/100 native results passed five-repeat offline determinism
replay; the approved 100-result run evaluated 100/100 with zero unknown.
- An Electron 43 unpacked app passed 27/27 static package checks and live launch
from `%TEMP%`. ASAR renderer, preload, IPC, packaged C# helper, IK resources,
elevation telemetry, Inventory UI, and a packaged 5-result dry run passed.
- The renderer now uses a scanner-first information architecture: Scanner,
Artifacts, Review, and the clearly labeled Builds preview form the workspace;
Overlay and Diagnostics remain secondary tools.
- The Scanner surface leads with Genshin/app readiness, one primary start/stop
action, a three-step empty state, explicit scan phases, and one modal for
scan scope, capture source, and manual tools. Inventory loading uses
skeletons/spinners, and confirmed
promotion, review, import, and export mutations report through accessible
toasts.
- Shared Galaxy tokens, focus-visible treatment, micro-motion, and a
`prefers-reduced-motion` fallback now define the visual/feedback baseline.
- The renderer now defaults to English on a fresh, missing, or invalid locale
setting. Users can choose German from Settings; the preference is local to the
app and updates the document language. This changes application copy only:
Smart Capture remains validated for the English Genshin UI.
- Artifact detail now exposes a small, confirmed local-delete action. Native
scan results are tombstoned rather than rewritten, their crop is removed only
when it is contained in the selected run directory, and an exact linked Store
record is removable only through an explicit local confirmation. No delete
path calls the input helper or changes Genshin.
- Native runs now retain an atomic `run-timing.json` record from request start
through durable result reconciliation. It measures capture and processing
separately and derives end-to-end duration from one wall-clock interval
instead of adding overlapping phases.
- The 136 historical full-inventory Review samples were audited against their
crops. The confirmed corpus now distinguishes 128 explicit non-five-star
entries, six exact duplicated-decimal repairs, one slot-safe artifact-name
correction, and one incomplete entry that intentionally remains `Review`.
### What is still structurally weak
@@ -154,20 +222,28 @@ The app is not intended to replace deep min-max tools. It prioritizes time savin
- 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 now has a minimalist recent-results rail, and the Inventory view
can inspect native Artifact results, crop previews, IK match state, promotion
dry-runs, and pipeline risk/status. Value scoring remains incomplete;
single-result review/edit/approve is implemented and batch review is
intentionally unavailable.
- The new native IK-style path has same-session 20/50/100 live scale evidence
with complete capture/result counts and safe Review gating. Later-session
repeatability and packaged behavior remain open.
dry-runs, pipeline risk/status, roll-efficiency reasons, and upgrade
projection. Single-result review/edit/approve is implemented and batch
review is intentionally unavailable.
- The native IK-style path has fresh later-session 5/20/50/100 scale evidence,
deterministic replay, focus-loss and stop evidence, plus a packaged 5-result
runtime smoke. Non-16:9 and other UI-language profiles remain open.
- Store promotion from native `scan-results.json` now supports one selected,
confirmed result at a time with main-process revalidation and a durable log.
Batch promotion intentionally remains unavailable.
- Native Review results can be corrected and approved or rejected one at a
time. Approval revalidates IK identity, canonical main values, and legal
substat rolls, then feeds the existing review-to-eval candidate pipeline.
- Recommendations and build logic exist, but artifact inventory, detail review,
and value scoring should land first so recommendations have trustworthy inputs.
- Recommendations and build logic exist, but build-aware fit must be designed
separately from the now-implemented context-free roll-efficiency score.
- The Builds navigation item now reads only the newest complete native run and
can surface up to three source-bound, read-only profile suggestions. It must
not imply character ownership, team, weapon, rotation, DPS, or optimizer
certainty; the built-renderer acceptance now passes, while an elevated
packaged-executable runtime remains a separate packaging check.
- The historical 136-item Review queue is not a source of labels by itself.
Its audit added only visually confirmed parser/corpus cases; the one
incomplete crop remains fail-closed in `Review`.
- Repeatability and 3 artifacts/second are still open; speed work should not
outrank result clarity, inventory UX, or corpus growth while the current path
is stable.
@@ -183,10 +259,30 @@ the helper captures Artifact card crops quickly, while OCR, parsing, review,
promotion, and value evaluation run downstream.
The next product phase is not broad category expansion. Weapons, materials, and
character details stay out of active scope. The priority is later-session
native repeatability, value
evaluation, and detail explanations before recommendations become the core
product surface.
character details stay out of active scope. Packaged/live acceptance passed on
2026-07-10 for the bounded 5/20/50/100 scanner and packaged 5er. A later real
Settings-UI run also accepted the revised Artifact-limit path at 5/5 through
preflight, capture, processing, parsing, and the session result rail with no
review, processing error, or persistence. The packaged Settings UI then
accepted a one-row limit as an eight-Artifact target at 8/8 with the same safe
outcome. The complete Settings-UI full-owned-inventory soak then accepted the
OCR-owned target 2,211 with exact 2,211 captures/results across 70 pages. After
one evidence-driven parser correction, the current packaged reprocess completed
2,211/2,211 with 136 Review (6.15%), zero errors/writes, and zero saved-run
validation issues. The current Build-Fit checkpoint now has four sourced
profiles, profile-expiry gates, a deterministic non-Roll-Efficiency evidence
ranker, explicit session-only Furina context, and a read-only Builds surface.
The renderer now defaults to English with a German Settings option, and local
artifact removal is deliberately confined to app-local result/store records and
contained crops. The current scanner also writes durable shared-clock timing
evidence and has a visually reviewed corpus correction for the audited
136-entry Review set. These current-build changes are offline/unit validated,
and the built-renderer Builds/UI acceptance passed, including the local-delete
confirmation probes. That is not an elevated packaged-executable claim. The
current elevated development 50-artifact native smoke now passes with complete
timing evidence and zero writes; its `28,022 ms` end-to-end result does not
prove the separate 3/s target. The remaining Review corpus continues to grow
only from visually confirmed labels.
## Product Direction
@@ -196,11 +292,23 @@ product surface.
- External scanners are not runtime dependencies. The app owns its scan
choreography, OCR, and quality gates.
- 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.
- The scan workspace should be an operator surface: the left area shows preview
when idle and owns capture-versus-target progress during a run; the right
rail contains current-session results plus independent evaluation progress.
Stop, status, and review access remain visible. Detailed debug evidence
belongs in diagnostics, summaries, or artifact detail.
- Primary navigation should follow the user journey: scan, inspect artifacts,
review uncertainty, then enter future build guidance. Overlay and diagnostics
remain tools instead of competing with that journey.
- Feedback should match the action: progress for long-running scans, skeletons
for content loading, inline state for durable blockers, and toasts for the
outcome of explicit mutations.
- Artifact value scoring must not hide OCR uncertainty. `Review` is a distinct
outcome, not just a weak artifact score.
- Explizit bestätigte visuelle 14★-Artefakte sind keine
Bergungs-/Lösch-Empfehlung: Sie erscheinen nur in der schreibgeschützten
`Nicht 5★`-Ansicht mit Bild und Details zur manuellen Prüfung. Eine
fehlende oder widersprüchliche Sternreihe bleibt `Review`.
## Execution Plan
@@ -212,9 +320,15 @@ Outcome:
- Scan completion popup summarizes scanned, stored, duplicates, review samples, blocked reason, and elapsed time.
Status:
- Mostly done for the scanner baseline. The Diagnose/dev surface is separated
and scrollable, scan summaries are compact, and the normal Auto-Scan path is
guarded. Further UI polish remains useful but no longer blocks scanner merge.
- Implemented as the scanner-first Galaxy baseline. Readiness and the primary
scan action lead the page, the left surface owns capture progress, and the
larger right surface owns ordered live results plus compact independent
evaluation progress. The current-session result rail starts empty, advanced
controls open in a modal without shifting the workspace, and Diagnose remains
a separate scrollable tool. The
Artifact-limit path and consolidated progress/result layout passed a real
five-result Settings-UI run, the one-row path at 8/8, and the full-owned path
at 2,211/2,211 with current-package Review below the 15% gate.
### Phase 1 - Canonical game data package
@@ -318,7 +432,11 @@ Outcome:
Status:
- Prepared in code for text replacements, field aliases, constrained fixes,
crop adjustment proposals, and UI-profile adjustment proposals. Crop/profile
changes still require live review before being auto-applied.
changes still require live review before being auto-applied. The current
review-corpus checkpoint adds only visually confirmed cases: exact duplicate
decimal punctuation is repaired, and a partial artifact name is canonicalized
only when independent, high-confidence slot evidence leaves one safe match.
Ambiguous or incomplete crops remain `Review`.
### Phase 6 - Minimal scan result rail and artifact inventory
@@ -334,31 +452,46 @@ Outcome:
Status:
- Started with a scan result rail in the scan surface and an `Inventory` view.
The rail can show native `scan-results.json` entries after post-processing
and falls back to recent stored artifacts. The inventory browser can filter,
The rail shows native `scan-results.json` entries from the current app scan
session after post-processing and does not preload older stored/native rows
at startup. The inventory browser can filter,
sort, inspect native/store/snapshot rows, and preview native card crops from
the selected run directory. It also exposes the current IK inventorylist
version, active Artifact-only scope, and pipeline status for capture,
post-processing, review, promotion, and evidence. Native Artifact rows carry
IK/GOOD match status from the post-capture processor and a dry-run promotion
decision that shows whether a native result is speicherbar, already stored,
review-only, or blocked without writing to the store. Detail review exists;
deterministic value score and value reasons are still pending. See
review-only, or blocked without writing to the store. Detail review,
deterministic roll-efficiency reasons, evaluated/open filters, score sorting,
and under-level projection are implemented. The browser prioritizes the
collection, filters, selected detail, and explicit next actions; technical
pipeline evidence remains available in collapsible detail. See
[scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md)
for the implementation phases and acceptance criteria.
for the implementation phases and acceptance criteria. The separate,
read-only `Nicht 5★` filter retains explicitly recognized 14★ native
results with their crop and details, excludes them from roll evaluation, and
exposes no in-game action. A confirmed local-delete action can remove a
wrong native result from the visible local inventory through an append-only
tombstone and safely contained crop cleanup; it can remove a Store-only row
or exact linked Store record only locally and never changes Genshin.
### 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.
- Upgrade projection is available only for unambiguously identified 5-star data
with four known legal substats 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.
- Implemented as `roll-efficiency-v1` plus detail-only
`roll-efficiency-projection-v1`. Static/build/replay, fresh dev 5/20/50/100,
packaged runtime, and final Inventory visual acceptance pass. The new live
100 contained only +20 Artifacts, so under-level projections remain covered
by the confirmed saved-run corpus rather than a new live sample.
### Phase 8 - Recommendations come back on top of a trusted scanner
@@ -367,35 +500,51 @@ Outcome:
- Recommendations explain uncertainty and surface conflicts instead of pretending perfect certainty.
Status:
- 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.
- `build-fit-contract-v1` continues to keep per-Artifact and five-piece
assessments score-free. On top of it, the offline-tested
`build-fit-evidence-ranking-v1` selects at most three non-overlapping safe
combinations from the newest complete native run. The sourced corpus now
covers Furina Solo-Hydro C0-C1, Neuvillette Charged Attack, Raiden off-field
Hyperbloom, and Nahida off-field Deepwood. Profiles expire explicitly;
Roll-Efficiency and OCR confidence are not ranking inputs. Furina's required
whole-build ER target accepts only explicit, session-only user context and
otherwise stays deferred. The Builds surface explains Set/Main-Stat/Substat
coverage, sources, warnings, and uncertainty without writing data or sending
game input. A built-renderer acceptance now covers fresh English locale,
German switching/restoration, Builds loading/context/focus, reduced motion,
overflow, and native plus Store local-delete confirmation probes. It is not evidence of an
elevated packaged-executable launch; that runtime boundary remains separate.
See
[BUILD_FIT_CONTRACT_V1.md](BUILD_FIT_CONTRACT_V1.md).
## Immediate Next Implementation Order
## Immediate Next Validation Order
1. Add deterministic Artifact value evaluation with explainable reasons.
2. 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.
3. Keep the active native scope artifact-only until weapons, materials, and
character details are actually scanned.
4. Finish the scan result and inventory detail contracts from
[scanner-results-inventory-roadmap.md](scanner-results-inventory-roadmap.md),
preserving separate extraction confidence and artifact value.
5. Finish value reasons in the existing Artifact inventory detail view before
expanding broad build recommendations.
6. Keep the existing scan preview/result rail and Inventory workflow compact;
move new diagnostics behind the dedicated diagnostics surface.
7. Continue growing the confirmed OCR corpus from review samples exported by
`npm run eval:review-candidates` and prepared through
`npm run eval:prepare-confirmed`.
8. Repeat live scanner runs in later sessions to prove repeatability across
pages, locked/unlocked artifacts, equipped footers, and duplicate handling.
9. Continue the optional `3 artifacts/second` work only if the next change can
reduce OCR/capture transport time without weakening quality gates.
10. Start recommendation/product UX work only after inventory/detail evaluation,
repeat scan quality, and confirmed corpus coverage are strong enough to trust
stored artifacts.
1. The final current-build offline gate passed after the localization, deletion,
timing, corpus, and acceptance-runner changes: `npm run acceptance:offline`
completed TypeScript, 72 test files / 444 tests, OCR evaluation, saved-run
validation, package verification (27/27), both dependency audits, and the
diff check.
2. Preserve the passing built-renderer acceptance as renderer evidence, but
separately verify an elevated packaged-executable launch/UAC bridge before a
binary release claim. It is not a substitute for scanner smoke evidence.
3. The current elevated development 50-artifact smoke passed with full
reconciliation, zero Review/errors/writes, and
`requestToResultsReconciledMs=28,022`. This is a functional/safety gate;
it does not claim 3 Artifacts/s.
4. Clean generated workspace output, commit the coherent checkpoint, and push
the intended branch. A package-runtime/UAC test is required only for that
separate claim.
5. Continue review-corpus growth only from visually confirmed crops. Keep
explicit 14★ evidence excluded, ambiguous evidence in `Review`, and reject
aliases that cannot be justified by independent field evidence.
6. Refresh source-bound profiles before expiry and add Golden plus
Review/low-confidence adversarial fixtures for each additional profile.
7. Keep the bounded wheel reset as the production baseline. Benchmark a `B`
plus Artifact-tab reopen only as a separate guarded experiment before any
reset strategy change.
8. Keep Build-Fit profile suggestions read-only and Artifact-only until an
explicit product decision adds owned-character, weapon, team, and rotation
inputs with their own sources.
## Open Questions
@@ -403,7 +552,7 @@ 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 |
| What scan-quality threshold is high enough before profile suggestions can be called live-accepted? | Scanner gate passed for accepted 16:9 English Artifact scope; Build-Fit unit/repository gate and built-renderer acceptance passed, while elevated packaged-executable runtime and current scanner smoke remain separate |
| What exact first-pass value formula should drive the `0-100` artifact score before build-aware recommendations exist? | Resolved for V1: legal roll-tier efficiency only; build fit remains separate |
| Which upgrade projection model is honest enough for early UX: deterministic roll buckets, probability-weighted outcomes, or a deliberately simple best/middle/worst estimate? | Resolved for V1: legal Worst/Middle/Best roll-efficiency bounds with explicit uncertainty |
| Which Genshin UI languages should be supported after English once the scanner contract is stable? | Open |
+201
View File
@@ -0,0 +1,201 @@
# Tomorrow Live Test Plan - 2026-07-10
> Historical execution plan. Its bounded acceptance matrix was completed and
> later extended by the packaged 2,211-Artifact full-owned-inventory baseline.
> The current authoritative result is
> [NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).
This is the ordered acceptance checklist for the first live session after the
five evaluation phases. It intentionally separates packaged-app, UI, scanner,
safety, quality, and performance evidence. Do not skip directly to a 100-item
run.
Executed on 2026-07-10. The result table below and
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md)
are authoritative; the unchecked boxes above remain the original reusable
operator checklist rather than a claim that the session is still pending.
## Preconditions
- [ ] PC started fresh; no stale Electron, Vite, helper, or old dev-server process.
- [ ] Genshin uses borderless `1920x1080` 16:9.
- [ ] Artifact inventory is open and one Artifact detail card is visible.
- [ ] No enhancement, feeding, deletion, locking, or resource-spending UI is involved.
- [ ] Current source worktree and commit are recorded before testing.
- [ ] `outputs/dist/win-unpacked/Genshin Artifact Assistant.exe` exists.
- [ ] Existing `%APPDATA%/genshin-artifact-assistant/native-scans` data stays intact.
## 1. Static Recheck After Boot
```powershell
npm run lint
npm test
npm run build
npm run eval
npm run package:verify
npm audit
```
Expected:
- [ ] `262/262` or more tests pass.
- [ ] OCR eval remains `26/26` exact and `77/77` fields.
- [ ] Package verifier remains `27/27`.
- [ ] Dependency audit remains at zero.
## 2. Packaged-App Launch
Launch the unpacked executable and approve its UAC prompt:
```powershell
& "outputs\dist\win-unpacked\Genshin Artifact Assistant.exe"
```
- [ ] App opens without a blank window, crash, or native menu bar.
- [ ] Scanner, Inventory, Diagnose, Triage, Builds, and Overlay navigation render.
- [ ] Runtime reports Electron `43.1.0` and the current app signature.
- [ ] Elevation/automation guard reports the packaged app as elevated.
- [ ] IK data reports version `6.7.0`, 61 sets, and 289 pieces.
- [ ] Packaged C# helper resolves from `resources/input-helper`.
- [ ] Browser-preview-only bridge warnings do not appear in the packaged app.
Stop immediately if helper resolution, preload, IK data, or elevation is broken.
## 3. Existing Scanned-Artifact UI
Open Inventory before starting any new scan.
- [ ] Existing native results load without changing Genshin.
- [ ] Latest approved 100-result run shows 100 parsed/evaluated and zero Review.
- [ ] Result rows show `xx% Roll`, extraction status, and source separately.
- [ ] `Bewertet` filter returns evaluated rows.
- [ ] `Wert offen` does not include normally evaluated clean rows.
- [ ] `Roll-Wert` sorting orders numeric scores descending and leaves unknown last.
- [ ] A +20 detail shows score reasons and per-substat roll/efficiency breakdown.
- [ ] Detail explicitly says build fit is still open.
- [ ] Locked/equipped state does not change the same Artifact's roll score.
- [ ] Native PNG crop preview loads only from the selected run directory.
Projection samples from run `20260709-223441`:
- [ ] Select an under-leveled Artifact such as sequence `#96` (+16) or `#100` (+4).
- [ ] Projection appears only in detail, not as a guaranteed result in the list.
- [ ] `Worst <= Middle <= Best`.
- [ ] Remaining roll count matches the current level.
- [ ] Disclaimer states random target/roll tier and no guarantee.
- [ ] +20 Artifacts show no future projection card.
## 4. Review And Promotion Safety
- [ ] A Review result has no normal numeric value score.
- [ ] Invalid manual substat totals are rejected even if each value is individually plausible.
- [ ] A 4-star-only roll value cannot be approved on a +20 Artifact.
- [ ] Reject keeps the result blocked.
- [ ] Approve requires IK identity, canonical main value, and legal total roll count.
- [ ] Promotion still requires explicit selection and second confirmation.
- [ ] Canceling promotion writes nothing.
- [ ] If one promotion is deliberately tested, store count changes exactly once and the durable log is written.
- [ ] No action changes anything inside the Genshin inventory.
## 5. Manual Smart Capture Smoke
This is the first live capture of the session.
- [ ] Genshin focus/preflight succeeds with the visible detail card.
- [ ] One Artifact is captured and parsed.
- [ ] Crop preview matches the selected Artifact.
- [ ] Name, set, slot, level, main stat/value, substats, equipped, and locked state are checked visually.
- [ ] Clean extraction receives a roll-efficiency score.
- [ ] Uncertain extraction goes to Review and receives no normal score.
- [ ] Stop/failsafe remains responsive.
## 6. Native Five-Artifact Smoke
```powershell
npm run scan:native:smoke:5
```
- [ ] Exactly 5 capture jobs, PNG crops, and durable results.
- [ ] Zero processing errors and zero automatic store writes.
- [ ] Result order and capture timestamps are preserved.
- [ ] Evaluation is present for every clean parsed result.
- [ ] Run the offline gate against the new run:
```powershell
npm run scan:native:replay -- --run-dir="<new-run-dir>" --repeats=5
```
- [ ] Replay is deterministic and has zero clean unevaluated rows.
## 7. Bounded 20/50/100 Progression
Only continue when the previous size passes.
For each run:
- [ ] Requested crop/job/result count is complete.
- [ ] Processing errors are zero.
- [ ] Store writes remain zero unless explicitly requested separately.
- [ ] Review reason is inspectable for every Review row.
- [ ] Miss rate is `<=2%` and Review rate is `<=15%`.
- [ ] Stop works during capture and processing.
- [ ] Offline replay with five repeats is deterministic.
- [ ] Evidence directory and timings are recorded.
Final 100-item checks:
- [ ] Pages and scrolling advance without duplicates or skipped visible tiles.
- [ ] Previously confirmed decimal-loss cases are repaired only when unique.
- [ ] Ambiguous OCR stays Review.
- [ ] Eligible under-leveled 5-star Artifacts receive projection; 4-star or
ambiguous-rarity data does not; +20 Artifacts are complete.
- [ ] Capture, processing, and end-to-end rates are reported separately.
- [ ] Do not claim 3 artifacts/second unless measured end to end with quality gates.
## 8. Packaged Runtime Regression
Repeat the key five-item smoke from the packaged executable, not only dev mode:
- [ ] Packaged preload bridge exposes all native scanner methods.
- [ ] Packaged helper can focus/click/capture under UAC.
- [ ] Packaged IK resource path resolves.
- [ ] Packaged crop preview bridge accepts valid PNG and blocks outside paths/non-PNG.
- [ ] Close/reopen preserves saved Inventory and review/promotion state.
## Abort Criteria
Stop the current run immediately when any of these occurs:
- Wrong Genshin category or no visible Artifact detail card.
- Blank/too-uniform capture passes preflight.
- Click lands outside the validated Artifact grid.
- Genshin loses focus and the worker continues clicking.
- Result count exceeds requested limit.
- Any automatic store write occurs during a dry run.
- Review data receives a confident normal score.
- Projection appears with missing fourth substat or claims certainty.
- Helper/preload/IK packaged resource is missing.
- App attempts delete, feed, enhance, lock/unlock, or resource spending.
## Result Record
Recorded after the session:
| Check | Result | Evidence path / note |
| --- | --- | --- |
| Static suite | passed | Final `npm run acceptance:offline`: 296/296 tests, 27/27 package checks, both audits clean |
| Packaged launch | passed | Started elevated from `%TEMP%`; ASAR renderer, preload, helper and IK resources resolved |
| Existing Inventory UI | passed | `outputs/packaged-live/packaged-final-inventory-fixed.png`; layout and latest complete-run discovery accepted |
| Evaluation reasons | passed | New 20/50/100 five-repeat replay; 100/100 evaluated, 0 unknown |
| Upgrade projection | passed offline, no new live sample | Existing under-level corpus passes; new live 100 contained only +20 Artifacts |
| Review/promotion safety | passed non-mutating boundary | Main-process/tests pass; duplicates show `5 im Store, 0 Review`; no deliberate store mutation performed |
| Single Smart Capture | passed | Real source `Genshin Impact`, `captureTarget=genshin-client`, 4x8 detected grid |
| Native 5 | passed | Dev `20260710-102344`: 5/5, 0 Review/errors/writes |
| Native 20 | passed | `20260710-102421`: 20/20, capture 4.50/s, processing 3.11/s |
| Native 50 | passed | `20260710-102450`: 50/50, capture 4.41/s, processing 3.21/s |
| Native 100 | passed | `20260710-102547`: 100/100, four pages, no duplicate page/hash evidence |
| Focus/stop safety | passed | Focus-loss `20260710-101820` blocked at 0; stop `20260710-102735` stopped at 0 |
| Packaged native smoke | passed | `20260710-103736`: 5/5 via renderer/preload/IPC/packaged helper, persist=false |
Full evidence and the next-phase decision are in
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).
+16
View File
@@ -57,6 +57,22 @@ marks missing fast-profile fields so stale/partial captures do not crowd out
useful cases, and surfaces ownership/lock evidence (`artifact-footer`,
`equipped`, and `locked=true/false`) for the next validation pass.
Current local snapshot from 2026-07-10:
- 177 records read, 0 invalid
- 138 unique candidates
- 80 exported candidates
- 36 candidates with complete fast-profile fields
- 41 likely stale or partial captures
- 14 equipped-footer candidates
- 3 `native-review-approved` cases already represented in
`confirmedReviewCorpus.ts`; the remaining 77 exported cases still require
explicit human labels
These counts describe the current local queue and may grow after later live
sessions. Do not treat the 36 complete-field candidates as automatically
correct; complete OCR is still only a review candidate until visually checked.
After manually checking one candidate against the real artifact, create a
confirmed corpus snippet with explicit expected labels:
+169 -44
View File
@@ -8,6 +8,9 @@ downstream work so the Electron app remains a visual/status surface instead of
the worker.
For the short current status, see [CURRENT_STATUS.md](CURRENT_STATUS.md).
For the current localization, local-deletion, timing, and reviewed-corpus
checkpoint, see
[LOCALIZATION_LOCAL_DELETION_TIMING_CHECKPOINT_2026-07-11.md](LOCALIZATION_LOCAL_DELETION_TIMING_CHECKPOINT_2026-07-11.md).
## Product Stance
@@ -21,24 +24,46 @@ For the short current status, see [CURRENT_STATUS.md](CURRENT_STATUS.md).
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.
- Treat direct visual star evidence as an evaluation gate: explicitly confirmed
14★ results remain visible but are excluded from roll evaluation; missing or
conflicting star evidence fails closed to `Review`.
- The `Nicht 5★` inventory filter is a read-only manual-inspection view, not a
salvage decision. It must never expose automatic salvage or Quick Select.
- The app renderer defaults to English; German is a Settings preference only.
The setting must not be presented as German Genshin OCR support.
- A wrong local artifact may be removed only through a confirmed app-local
workflow. It must preserve raw scan evidence, restrict crop cleanup to the
selected run directory, and never send game input.
- Prioritize extracting correct artifact content over another speed pass unless
live timings regress materially.
## Current 2026-07-11 Checkpoint
The implementation now has an English-default/Deutsch-selectable renderer,
confirmed local artifact removal, a shared-clock native run timing record, and
new visually reviewed OCR corpus cases. These are implementation and offline
validation results, not a new live-release claim. The remaining release gates
include the non-persisting 50-artifact native smoke that produces a complete
`run-timing.json`. The built-renderer Builds/UI acceptance already passed; an
elevated packaged-executable runtime remains a separate packaging boundary.
## 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:
4. A compact live result rail on the right receives one row per finished safe
artifact result.
5. Each evaluated 5★ 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,
6. An explicitly recognized 14★ row shows `Nicht bewertet`; an unconfirmed or
conflicting star row stays `Review` rather than assuming 5★.
7. After the scan, the user opens the inventory menu to browse all scanned
artifacts, including the separate read-only `Nicht 5★` filter.
8. Clicking an artifact opens a detail view with screenshot, parsed fields,
OCR confidence, scoring reasons, and optional upgrade projection.
## Score Contract
@@ -48,12 +73,17 @@ 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. |
| Visual star evidence | Direct `starCount`, confidence, and source from the native card crop. | Confirmed 14★ is `excluded`; missing, invalid, or conflicting evidence is `Review`; only confirmed 5★ proceeds to evaluation. |
| 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.
- An explicit 14★ result gets no value score, projection, or promotion. It is
visible only as an `excluded` manual-review item with its crop and details.
- Never infer a 5★ result from an absent, invalid, or conflicting direct visual
star field in a current native job; it must stay `Review`.
- 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.
@@ -137,9 +167,13 @@ 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. Initial native entries use
`valueStatus: "deferred"` for clean parses and `valueStatus: "review"` for
uncertain extraction.
status, direct visual rarity evidence, duplicate/review flags, and timestamps. Initial native entries use
`valueStatus: "deferred"` for clean parses, `valueStatus: "review"` for
uncertain extraction, and `valueStatus: "excluded"` for explicit direct
14★ evidence.
- Preserve `starCount`, `starConfidence`, and `starSource` for current native
jobs so the downstream gate can distinguish explicit 14★ exclusion from an
ambiguous result that must remain `Review`.
- Keep existing stored artifact records compatible.
- Add tests for status derivation so low-confidence OCR cannot become a normal
`Good` or `Strong` result.
@@ -154,16 +188,24 @@ Likely files:
### Phase 2 - Minimal live result rail
Status: foundation implemented for native post-capture results. The scan main
section shows newest stored artifacts as fallback and can display the latest
native `scan-results.json` entries after post-processing. Result rail rows can
open the Inventory surface for crop/IK/detail inspection. Value scores are still
pending.
Status: implemented for current-session native post-capture results. The rail
starts empty on app launch and receives only results loaded for a scan started
in the current app session. Older stored/native history stays in the Inventory
surface. Result rail rows can open that surface for crop/IK/detail inspection.
A real Settings-UI Artifact-limit-5 run completed with 5 captured, processed,
and parsed results, 0 review/errors, `persist=false`, and five rail rows. A
real row-limit run completed at 8/8. The packaged full-owned-inventory baseline
then captured 2,211/2,211 over 70 pages and showed all 2,211 live-session rows;
current-package reprocessing passed at 136 Review (6.15%), 0 errors, and 0
store writes.
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.
- Rework the scan main section into a left preview/progress work surface plus a
right-side current-session result rail.
- Keep phase and outcome counts in that left work surface during a run; remove
the duplicate standalone progress card and noisy debug 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.
@@ -186,20 +228,26 @@ crop preview loading are present. The view now surfaces the vendored IK
Artifact version/counts, active Artifact-only scope, compact pipeline state for
native capture, OCR queue, review, promotion, and evidence, plus per-result
IK/GOOD match status for native artifacts. The inventory view also computes a
dry-run promotion summary from `scan-results.json` plus the local artifact
store, separating `speicherbar`, already stored, review, and blocked native
results. One selected clean result can now be promoted after a second UI
confirmation; the main process revalidates the run result, writes the store,
updates `scan-results.json`, and appends `promotion-log.jsonl`. Weapons,
materials, and character details
dry-run promotion summary from `scan-results.json` plus the local artifact
store, separating `speicherbar`, already stored, review, and blocked native
results. One selected clean result can now be promoted after a second UI
confirmation; the main process revalidates the run result, writes the store,
updates `scan-results.json`, and appends `promotion-log.jsonl`. Weapons,
materials, and character details
remain hidden from the active feature UI while they are not scanned. The native
helper still reports the category distinction in
`supportedCategories` via `catalogAvailable`, `nativeCaptureSupported`, and
`scanStatus`, so dev-control evidence cannot accidentally claim that every IK
catalog has an implemented scanner. Native scan start, status, manifest, and
capture jobs now carry an explicit scan category; only `artifacts` can currently
produce native capture jobs. Value scoring is still pending; single-result
review/edit/approve is implemented in the detail phase below.
produce native capture jobs. Deterministic roll-efficiency evaluation and
single-result review/edit/approve are implemented in the detail phases below.
The current checkpoint also adds a confirmed local-delete path. A native
result is hidden by an append-only tombstone rather than an in-place result
rewrite; its PNG crop is removed only after run-directory containment
succeeds. A Store-only row, or the exact Store record linked to a native row,
can be removed locally after confirmation. Active scans/processors block the
action, and no delete path sends Genshin input.
Support code for simple IK weapon, character, and material name/GOOD-key
matching exists, but those categories still need their own capture flows before
@@ -212,6 +260,13 @@ Outcome:
- 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.
- Provide a separate read-only `Nicht 5★` filter for explicitly recognized
14★ native results. It must retain screenshot/crop and parsed detail for
manual inspection, use no "safe to salvage" language, and offer no automatic
salvage or Quick Select action.
- Provide a small confirmed local-delete action in artifact detail. It must
describe its app-local scope, preserve raw native result evidence, limit crop
removal to a contained PNG, and keep Store removal exact and opt-in.
- Avoid a marketing/landing layout; the first screen is the actual inventory.
Likely files:
@@ -224,13 +279,15 @@ Likely files:
### Phase 4 - Artifact detail view
Status: started for native scan results. Inventory detail can show the native
Status: implemented baseline for native scan results. Inventory detail shows the native
card crop from the run directory through the Electron bridge, constrained to
PNG files inside the active native run folder. It also shows stored parser
field-confidence rows from native `scan-results.json`, IK/GOOD metadata, dry-run
promotion state, and a `Naechster Schritt` card. Native Review results now have
an inline field editor with approve/reject, authoritative validation, run logs,
and review-to-eval export. Value reasons are still pending.
and review-to-eval export. It now also shows roll-efficiency reasons,
per-substat legal roll breakdown, build-fit deferral, and under-level
projection when safe.
Outcome:
@@ -250,17 +307,24 @@ Likely files:
### Phase 5 - Artifact value evaluation
Status: next product feature after the now-completed same-session native scale,
selected promotion, and review/edit/approve workflow.
Status: implemented as `roll-efficiency-v1`. Clean legal Artifacts are
evaluated; Review and unknown data receive no confident score. For current
native jobs, only explicitly confirmed 5★ evidence enters evaluation;
explicit 14★ evidence becomes `excluded` with no score or projection, while
ambiguous direct star evidence remains `Review`. Existing saved results are
enriched on load and replayed offline without rescanning.
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.
- Explain the score through legal roll-tier quality and total roll counts.
- Keep set/main-stat desirability and character/build context separate.
- Keep locked/equipped state out of intrinsic roll quality.
- The evaluator must accept incomplete data and return review/unknown instead
of confident nonsense.
- Do not turn an `excluded` 14★ result into an evaluation, store-promotion,
projection, or automatic in-game action.
Likely files:
@@ -272,11 +336,16 @@ Likely files:
### Phase 6 - Upgrade projection
Status: later detail-level feature after artifact value evaluation.
Status: implemented as detail-only `roll-efficiency-projection-v1` for
under-leveled, unambiguously identified 5-star Artifacts with four known legal
substats. Packaged visual/live acceptance passed on 2026-07-10; the new live
100er contained only +20 Artifacts, so under-level behavior remains covered by
the confirmed saved-run corpus.
Outcome:
- For artifacts below max level, show optional projection only in detail.
- For unambiguously identified 5-star 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
@@ -284,7 +353,7 @@ Outcome:
Likely files:
- `src/lib/upgradeProjection.ts`
- `src/lib/artifactEvaluation.ts`
- `src/lib/substatRolls.ts`
- `src/features/inventory/components/*`
- parser/scoring tests
@@ -300,10 +369,15 @@ Outcome:
- Preserve stop/failsafe behavior and review decisions.
- Compare throughput against the current baseline without weakening accuracy.
Status: started for post-capture processing. Native capture already writes
crop jobs without waiting for OCR. The downstream processor now consumes those
jobs with bounded parallelism and writes stable ordered reports. Live throughput
comparison remains a final validation item.
Status: implemented and live accepted. Native capture writes crop jobs without
waiting for OCR. The downstream processor tails those jobs with bounded
parallelism, streams stable ordered deltas into the result rail, and writes
durable reports. Packaged 20-result and 2,211-result runs proved live capture/
evaluation overlap; the full corpus also passed five-repeat deterministic replay
and saved-run validation after current-package reprocessing. The current build
also writes immutable first-observed lifecycle markers to `run-timing.json`.
It derives end-to-end time directly from request to result reconciliation;
capture and processing durations remain separate and must not be added.
Likely files:
@@ -314,14 +388,28 @@ Likely files:
### Phase 8 - Recommendation promotion
Status: intentionally delayed until native artifact ingestion, review,
promotion, value scoring, and repeatability are trustworthy.
Status: offline implementation checkpoint completed. The Builds surface reads
the newest complete native result run, validates source-bound profiles and
five-piece evidence, and exposes up to three read-only, non-overlapping
suggestions. The current package acceptance runner covers the fresh
English/German locale flow, Builds context/focus, reduced motion, and overflow,
and its built-renderer execution passed together with the local-delete
confirmation probe. It is not evidence of an elevated packaged-executable
launch, UAC, preload bridge, or native runtime; those remain separate from the
renderer result and the required current-build scanner smoke.
Outcome:
- Promote account-level recommendations only after scan result quality,
- Promote only source-bound profile suggestions after scan result quality,
inventory browsing, detail review, and value scoring are trustworthy.
- Recommendations must reference stored artifact quality and uncertainty.
- Read Build-Fit inputs from complete native results, not metadata-poor store
records, because canonical IK Set keys and field-confidence evidence are
required.
- Keep `roll-efficiency-v1` and OCR confidence out of ranking. The visible
rule-coverage value may use only documented Set/Main-Stat/Substat evidence;
required full-build context must be explicit.
- Keep suggestions read-only, explain uncertainty/conflicts, and never infer
character ownership, team, weapon, rotation, or an in-game action.
## Acceptance Criteria
@@ -333,7 +421,22 @@ Outcome:
- 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.
- Explicit 14★ results are visibly excluded rather than scored; ambiguous
visual rarity is visibly `Review`.
- The `Nicht 5★` inventory filter presents only manual review evidence
(screenshot/crop and details), never a salvage or Quick Select control.
- A freshly initialized renderer is English; the Settings locale control can
select German and restore English without implying German Genshin OCR support.
- Artifact detail can remove a wrong local row only after confirmation. Native
removal preserves raw result evidence through a tombstone, constrains crop
cleanup to the run directory, and never sends game input.
- Streaming/end-to-end reports use a complete, ordered shared-clock
`run-timing.json` rather than summed capture and processing durations.
- Upgrade projection never implies a guaranteed future roll.
- Build suggestions use only complete native evidence, source-valid profiles,
complete Set shapes, and explicit required aggregate context.
- Builds explains profile, sources, chosen five Artifacts, rule coverage,
conflicts, and deferrals without presenting an optimizer or DPS score.
- Existing safety constraints and scan quality gates remain intact.
## Validation Plan
@@ -342,12 +445,34 @@ Outcome:
- `npm test`
- `npm run build`
- `git diff --check`
- `npm run scan:native:replay` against accepted bounded runs and the 2,211 corpus
- `npm run package:offline-check`
- Preserve the passing built-renderer `npm run package:live:builds` evidence
for locale/Builds/delete UI behavior. Separately launch an elevated packaged
executable before making a package-runtime/UAC claim.
- `npm audit`
- `npm run scan:native:smoke` before claiming native capture plus
post-capture processing on live Genshin data.
- Broader native Artifact runs with 20/50/100 items before claiming IK-style
speed or stability.
- For this checkpoint, run the smoke at exactly 50 artifacts with
`scripts/native-live-smoke.ps1 -Limit 50`; require reconciliation, zero
processing errors, the review-rate gate, and a complete valid
`run-timing.json` before cleanup, commit, or push.
- Test local deletion offline for active-run blocking, raw-result preservation,
tombstone filtering, crop containment, and exact Store scope. The built
renderer already passed the visible confirmation probe; repeat it only for a
separate elevated packaged-executable runtime claim.
- Test fresh English/default, German selection, and English restoration through
the app Settings modal; do not use translated text as the primary automation
selector.
- Preserve the accepted 20/50/100 and 2,211 evidence before changing capture,
parser, Review, or evaluation contracts.
- Add unit tests for score/status derivation and upgrade projection.
- Add direct visual 5★/4★/3★ and ambiguous-star fixtures. Verify that 14★ is
stable `excluded`, ambiguity is `Review`, and neither path can be promoted or
expose an in-game mutation.
- For scanner-facing changes, run a low-limit visible-inventory live scan before
wider validation.
broad validation, then use the saved full corpus whenever new input is not
required. The original execution plan is retained in
[TOMORROW_LIVE_TEST_PLAN_2026-07-10.md](TOMORROW_LIVE_TEST_PLAN_2026-07-10.md).
- Keep `npm run scan:repeatability:wait` for later regression checks, not for
every UI-only pass.
+174 -152
View File
@@ -1,173 +1,195 @@
# Scanner Rework Status
Updated: 2026-07-09
Updated: 2026-07-11 after the 2,211-Artifact full-inventory acceptance,
review-gate correction, strict game-process targeting, and the offline-tested
Build-Fit evidence-ranking checkpoint
Short current-state entry point: [CURRENT_STATUS.md](CURRENT_STATUS.md).
Detailed evidence:
[NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md](NATIVE_SCANNER_LIVE_ACCEPTANCE_2026-07-10.md).
## Was Es Kann
- Native IK-Erfassung ist als neuer schneller Pfad verdrahtet: Electron/React
starten und zeigen Status, der C# Helper prueft IK-Listen, fokussiert Genshin,
klickt das 16:9 8x4 Grid, scrollt und schreibt Detailkarten-Crops.
- IK `inventorylists` aus Inventory Kamera 1.4.4 sind 1:1 unter
`data/ik-inventorylists` uebernommen und werden in Builds als Resource
mitgeliefert. Der Helper meldet Version `6.7.0` mit `61` Artifact-Sets,
`289` Artifact-Pieces, `247` Waffen, `119` Charakteren und `715` Materialien.
- Jeder native Run legt `manifest.json`, `capture-jobs.jsonl` und `status.json`
im Run-Ordner an. Damit kann OCR/Parsing als nachgelagerte Queue laufen,
ohne den Capture-Loop wieder in React/Electron zu ziehen.
- Nach einem nativen Run kann die App `capture-jobs.jsonl` nachgelagert
verarbeiten und `scan-results.json` plus `processing-report.json` schreiben.
`scan-results.json` enthaelt dauerhafte Ergebnis-Eintraege mit
Extraction-Status, Review-Zustand und bewusst deferierter Value-Auswertung.
Diese Stufe OCRt/parst nach der Erfassung, matched native Artifact-Ergebnisse
gegen IK `inventorylists`, zwingt IK-Konflikte in Review, verarbeitet Crops
ueber eine bounded Queue, schreibt Parser-Feldconfidence in die Resultate und
persistiert standardmaessig noch nicht in die DB.
- Smart Capture reads the current artifact detail view through focused 16:9
crops, OCR preprocessing, deterministic parser matching, and local lookup data.
- Visible-inventory auto-scan is the production baseline: preflight, grid
detection, focus, click, detail verification, OCR, parse, store/review, scroll,
and summary.
- The current live path has completed a 100-artifact run with `100/100` verified
and parsed, `98` stored, `2` duplicates, `0` review samples, `0` misses, and
`393 ms/artifact`.
- Native IK live smoke passed on 2026-07-09 with runtime signature
`2026-07-09-native-ik-visual-probe`: visual preflight ready, guarded probe
changed the detail panel, `2/2` native artifact card crops captured,
post-capture processing parsed `2/2`, `0` review, `0` errors, and
`queueConcurrency: 2` without persisting to the artifact store.
- Native 20/50/100 dry validation also passed in the same live session. The
100-item run captured and parsed `100/100` across 4 pages with `0` errors,
`3` correctly gated Review results, and `0` store writes. See
`docs/NATIVE_SCANNER_VALIDATION_2026-07-09.md`.
- Stored artifacts, review samples, local text replacements, GOOD-compatible
import/export, scanner diagnostics, and OCR eval are implemented.
- The scan page now has a compact `Letzte Ergebnisse` rail. It uses the latest
native `scan-results.json` entries after post-processing and falls back to
newest stored artifacts when no native run result is loaded. Rail rows open
the Inventory surface for detail inspection.
- The app now has an `Inventory` navigation view for browsing native scan
result entries, stored artifacts, and snapshot fallback rows with filters,
sorting, a detail panel, and native crop previews loaded from the scan run
directory. The same view is now scoped to Artifact scanning: it shows IK
Artifact set/piece coverage, a Native Artifact pipeline strip for capture,
post-processing, review, promotion, and evidence, plus a per-result
`Naechster Schritt` panel. Weapons, materials, and character details remain
loaded data only and are intentionally hidden from the active feature UI while
they are not scanned.
- The live-soak runner writes JSON/CSV evidence bundles and validates quality via
`scan-performance-assessment.json`.
- Der native Artifact-Scanner setzt das 2.400-Slot-Inventar begrenzt an den
Anfang, erfasst ein validiertes 4x8-Grid ueber mehrere Seiten und streamt
jeden Crop direkt in vier begrenzte OCR-/Parse-/Evaluierungsworker.
- Genshin-HWND, Stop-Signale und Input-Erfolg werden vor jedem relevanten
Wheel-, Klick- und Capture-Schritt geprueft. Fokusverlust refokussiert nicht.
- Die frische Live-Kette `5/20/50/100` bestand mit 0 Review, 0 Fehlern und
0 Store-Writes. Der 100er `20260710-102547` erreichte 4,37 Captures/s und
3,15 verarbeitete Results/s.
- Gespeicherte Runs werden auf exakte Jobs/PNGs/Results, Sequenzen, Pfade,
Click-Events, Seitenwiederholung, PNG-Hashes und Replay-Determinismus geprueft.
- Inventory zeigt Native- und Store-Zeilen mit getrennten Signalen fuer
Extraktion, Review, IK, Roll-Efficiency, Promotion und spaeteren Build-Fit.
- Die unpacked App ist aus `%TEMP%` live gestartet. Renderer, Preload, IPC,
paketierter C#-Helper und IK 6.7.0 funktionierten; der paketierte 5er
`20260710-103736` bestand ohne Persistenz.
## Was Zuletzt Gemacht Wurde
- Der aktive UI-Scope wurde auf Artifact scanning begrenzt.
- Waffen, Materialien und Charakterdetails bleiben als vendored IK-Daten
vorhanden, werden aber nicht mehr als aktive Scanner-Features in der
Inventory UI dargestellt.
- Die Inventory UI zeigt jetzt eine Native Artifact Pipeline:
Scope, Native Capture, OCR Queue, Review Gate, Promotion und Evidenz.
- Native Ergebnislabels wurden geschaerft:
`Geparst` bedeutet extrahiert, `Stored` bedeutet persistiert, `Review`
bedeutet unsicher und `Wert offen` bedeutet bewusst noch nicht bewertet.
- Native Artifact Details zeigen jetzt einen `Naechster Schritt`:
Promotion bereit, Review zuerst, bereits im Store, blockiert oder Wert spaeter.
- Inventory Filter wurden um native Ergebnisse und speicherbare Ergebnisse
erweitert.
- Ein ausgewaehltes, sauberes natives Ergebnis kann jetzt nach einer zweiten
UI-Bestaetigung promotet werden. Der Main-Prozess validiert die autoritative
Run-Datei erneut, prueft Store-Duplikate, schreibt den Store, aktualisiert
`scan-results.json` und protokolliert in `promotion-log.jsonl`.
- Native Review-Ergebnisse koennen direkt im Inventory anhand des Crops editiert,
gegen IK, kanonische Main-Werte und legale Substat-Rolls validiert sowie
freigegeben oder abgelehnt werden. Freigaben aktualisieren `scan-results.json`,
schreiben `review-log.jsonl` und erzeugen einen normalen Eval-Review-Sample.
- Projekt-, Roadmap-, Architektur-, Runbook- und Checklist-Doku wurden auf
Artifact-only Scope nachgezogen.
- Capture-Quellenklassifizierung schliesst die eigene App trotz `Genshin` im
Titel aus.
- Dev-Cleanup beendet nur echte Repo-Vite/Electron/Helper-Prozesse und nicht
mehr den Codex-CUA-Node.
- Native Runs starten immer mit einem begrenzten Top-Reset und pruefen den
Foreground vor jedem Input/Capture. Reset-Pacing senkte die Live-Zeit von
50,7 s auf rund 1,7 s.
- Der Smoke-Gate prueft exakte Counts, Dateivertraege, Reviewrate,
Non-Persistence und bestaetigten Stop-Cleanup.
- Run-Aufloesung waehlt nur den neuesten vollstaendigen Run; gestoppte oder
unprozessierte Runs ersetzen die Inventory-Evidenz nicht.
- Packaged Pfade verwenden `resourcesPath`, Vite relative Assets und eine
verifizierte Runtime-Signatur.
- Elevation wird sowohl im Runtime- als auch im Helper-Guard korrekt angezeigt.
- Inventory-Layout und Promotion-Duplikatstatus wurden im finalen Paket visuell
korrigiert und abgenommen.
- Der aktuelle Renderer-Stand setzt den Scanumfang standardmaessig auf die
erkannte Besitzanzahl und bietet optional ein Artifact- oder Reihenlimit. Die
linke Hauptflaeche uebernimmt den Lauf-Fortschritt; die separate
Fortschrittskarte entfaellt und die Ergebnisleiste startet sitzungsleer.
- Der bestehende gebundene Wheel-Top-Reset bleibt Produktionsstandard. Ein
`B`-Reopen mit Artifact-Tab ist nur eine spaeter live zu benchmarkende
Alternative, nicht Teil des aktuellen Produktionspfads.
- Ein realer Settings-UI-Lauf mit Artifact-Limit 5 bestand Genshin-, Detail-
und Grid-Preflight. Ziel/Capture/Processing/Parsing endeten bei 5/5,
Review/Fehler bei 0, `persist=false`; die sitzungsgebundene Ergebnisleiste
zeigte alle 5 Resultate.
- Der paketierte Settings-UI-Reihenlauf `20260710-180851` loeste eine Reihe
ueber das erkannte 8-Spalten-Raster zu Ziel 8 auf. Capture, Processing und
Parsing endeten bei 8/8, Review/Fehler bei 0 und der Top-Reset bei 1.715 ms.
Zwei Fokusverlust-Versuche blockierten vorher korrekt mit 0 Klicks.
- Der paketierte Streaming-Lauf `20260710-201614` startete Processing beim
ersten verfuegbaren Run-Verzeichnis. Noch waehrend Capture `running` war,
zeigte die Session-Rail bereits 11 ausgewertete Ergebnisse. Final waren
Capture/Processing/Parsing/Evaluation 20/20, Review/Fehler/Store-Writes 0;
alle Sequenzen 1-20 waren eindeutig und chronologisch sichtbar.
- Die Scanner-Hierarchie nutzt jetzt mehr Breite fuer die sitzungsgebundenen
Ergebnisse als fuer Guide/Capture. Scanbereitschaft und Live-Auswertung sind
kompakte Statusleisten statt verschachtelter Karten.
- Scanumfang, Aufnahmequelle und manuelle Werkzeuge liegen in einem
fokusgefangenen `Scanoptionen`-Modal und verschieben den Arbeitsbereich nicht
mehr. Collection-Pipeline-Details im Inventory liegen ebenfalls in einem
Modal; Diagnose-Import/-Export ist standardmaessig eingeklappt.
- Der frisch paketierte UI-Lauf `20260710-214406` bestaetigte die neue
Hierarchie erneut live: 20/20 Capture, Processing, Parsing und Evaluation,
0 Review/Fehler/Store-Writes, bis zu 9 sichtbare Ergebniszeilen und 12 bereits
ausgewertete Resultate waehrend Capture noch lief. Der erste Startversuch
blockierte korrekt an der doppelten Detailkarten-Pruefung; nach stabiler
Detailkarte lief derselbe begrenzte Pfad durch.
- `build-fit-contract-v1` trennt gesourcte Character-/Zielregeln,
Set-Pfade, Main-Stat-Prioritaeten, Substat-Gewichte, Gesamtziele, Konflikte
und Profil-Ablaufdaten von OCR und Roll-Efficiency. Unsichere oder nicht
kanonische Scanergebnisse blockieren; V1 gibt absichtlich noch keinen
Fit-Score aus.
- Reale lokale Account-Snapshots rufen den alten Demo-Scorer nicht mehr auf.
Der getrennte `build-fit-evidence-ranking-v1` liest stattdessen nur den
neuesten vollstaendigen nativen Run und kann bis zu drei read-only
Profilvorschlaege ausgeben.
- Der score-freie Fuenfer-Verifier prueft genau einen Eintrag pro Slot,
vollstaendige Set-Formen, verschachtelte OCR-/Review-Gates, Konflikte und
optional gesourcte Gesamtwerte. Fehlender Nicht-Artifact-Kontext bleibt
`pending` und wird nicht geraten.
- Der Profil-Corpus umfasst Furina Off-field/Solo Hydro C0-C1, Neuvillette
Charged Attack, Raiden Off-field Hyperbloom und Nahida Off-field Deepwood.
Jede Regel ist quellen-/versions-/ablaufgebunden, gegen reale IK-6.7.0-Keys
geprueft und durch Golden plus adversarial Fixture abgesichert.
- Die sichtbare Regelabdeckung kombiniert nur Set-Form, Main-Stat-Prioritaet
und dokumentierte Substat-Praesenz. Roll-Efficiency, Rollhoehe und OCR-
Confidence sind keine Rankinggewichte; Charakterbesitz, Team, Waffe und
Rotation werden nicht geraten. Furinas ER-Kontext ist nur explizit und
sitzungsgebunden bestaetigbar.
- Der reale Vollinventar-Lauf `20260710-223233` nahm den OCR-Besitzwert 2.211,
erfasste exakt 2.211 Karten auf 70 Seiten mit 4,24/s und schrieb nichts in
den Store. Die aktuelle paketierte Reprozessierung erreichte 2.211/2.211,
136 Review (6,15%), 0 Fehler und 0 Writes; der Saved-Run-Validator meldet
`issues=0`.
- Der erste Parse desselben Laufs wurde bei 490 Review (22,16%) korrekt nicht
akzeptiert. 360 widerspruechliche `+0`-Main-Values werden jetzt nur dann aus
der kanonischen 5-Sterne-Tabelle repariert, wenn vier Anfangs-Substats die
Seltenheit strukturell beweisen; Drei-Substat-Faelle bleiben Review.
- Native Helper und PowerShell-Fallback akzeptieren nur noch die exakten
Prozessnamen `GenshinImpact` oder `YuanShen`. Bei geschlossenem Spiel bestand
der Package-Smoke mit `genshinFound=false`, HWND 0 und leerem Zielprozess.
## Was Noch Nicht
- Native IK-Erfassung captured aktuell Karten-Crops; OCR/Parser laufen erst
nachgelagert ueber den Processor. GOOD-Speichern und Evaluierung laufen noch
nicht automatisch im nativen Pipeline-Nachgang.
- Native IK-Erfassung ist aktuell auf das sichtbare 16:9 Artifact-Inventar
begrenzt.
- The result rail is still a foundation: it can show native `scan-results.json`
entries after post-processing, but does not yet calculate or show real value
scores.
- The inventory browser is still a foundation: value scoring and richer
review/edit flows are not complete.
- Upgrade projection and build recommendations should wait until inventory and
detail evaluation have trustworthy stored artifacts.
- Repeatability across later sessions, more accounts, more locked/equipped
combinations, and more confirmed OCR corpus cases still needs growth.
- The strict `333 ms/artifact` budget for 3 artifacts/second is not proven.
- Weapons, materials, and character details are intentionally out of active
scope until their values are actually scanned.
- Roll-Efficiency ist weiterhin kein Build-Fit. Die offline getestete Builds-
Oberflaeche ist keine Optimizer- oder DPS-Aussage und wurde noch nicht als
frischer paketierter Renderer-Fall live abgenommen.
- Weapons, Materials und Character Details bleiben ausserhalb des aktiven
Scanner-Scope.
- Andere Aufloesungen, Seitenverhaeltnisse und UI-Sprachen haben noch kein
live validiertes Profil.
- Batch-Review/-Promotion und automatische Store-Persistenz bleiben aus.
- Der absichtlich schreibende Review-/Promotion-Pfad wurde nicht live
ausgefuehrt; er bleibt zustimmungspflichtige separate QA.
## Wo Es Noch Probleme Macht
- Die native Pipeline hat jetzt 20/50/100-Skalenevidenz aus einer Live-Session.
Spaetere Session-Repeatability und Packaged-App-Evidenz stehen noch aus.
- Capture roundtrip and OCR remain the main timing costs in the 100-artifact
path.
- Auto-scan still requires a visible artifact inventory detail card for the
production path; broader auto-entry modes remain dev experiments.
- OCR/parser quality is good on the confirmed corpus, but review samples must be
manually labeled before they can become permanent eval ground truth.
- Non-16:9 or unusual game layouts are intentionally higher risk and should
block or fall into review instead of silently scanning.
- The UI now labels these risks in the Artifact Inventory pipeline. Same-session
scale is proven, but external-tool parity and later-session repeatability are
intentionally not claimed.
- Die fruehere `1,77/s`-Zahl ist nur der historische serielle 100er-Smoke:
Capture/Reset und danach Batch-Processing wurden addiert. Sie darf nicht als
aktuelle Streaming-End-to-End-Rate gelesen werden. Der dry Streaming-20er
`20260711-090019` lief 20/20 mit 0 Review/Fehlern/Writes, lieferte das erste
Ergebnis vor Capture-Ende, mass `4,43 Capture/s` und beobachtet `2,39/s`
vom Startrequest bis zur Result-Reconciliation. Der gemeinsame Clock-Contract
ist jetzt persistiert: der aktuelle 50er `20260711-154827` bestand mit
50/50 Capture/Parse/Results, 0 Review/Fehler/Writes und `28.022 ms`
Request-to-Reconciliation (`~1,78/s`). Der 3/s-Gesamtclaim bleibt offen.
- Neue OCR-Zustaende koennen weiterhin Review ausloesen; das ist ein sicherer
Fallback, kein Grund die Plausibilitaetsgates zu lockern.
- Der Renderer hat weiter einen nicht-blockierenden ~630-kB-Chunk.
- Die neuen Live-Artifacts waren alle +20, deshalb entstand kein neuer echter
Under-Level-Projektionsfall.
- Ohne plausiblen OCR-Wert fuer die aktuelle Besitzanzahl blockiert der
Full-Inventory-Lauf absichtlich; Kapazitaet darf das Ziel nicht ersetzen und
der native Helper erkennt das Listenende noch nicht verlaesslich selbst.
## Was Noch Verbesserungsfaehig Ist
- Repeat the bounded 20/50/100 native runs in a later session and in a packaged
app to verify that the current post-capture queue remains repeatable.
- Keep native persistence explicit: clean selected results can be promoted
after confirmation, while uncertain results must pass single-item review.
- Finish value scoring and value-reason contracts in the existing detail view from
`docs/scanner-results-inventory-roadmap.md`.
- Keep diagnostics available but out of the primary scan surface.
- Continue expanding confirmed OCR eval cases from real review samples. The
first three native Review cases are corrected, approved, and permanent
regression cases.
- Add artifact value/detail evaluation without collapsing extraction confidence
and artifact value into one ambiguous status.
- Continue performance work only when it reduces capture/OCR overhead without
weakening review, miss, duplicate, or safety gates.
1. Die Builds-Oberflaeche hat nun eine gebaute Renderer-Abnahme fuer frisches
Englisch, Deutsch-Umschaltung, Kontext, Fokus und Overflow bestanden. Ein
elevated Paket-Start bleibt nur fuer einen gesonderten Runtime/UAC-Claim
offen; der frische native 50er-Smoke bestand als Scanner-Release-Gate.
2. Profilquellen vor Ablauf erneuern und jedes weitere Profil wieder mit
Golden-/adversarial Fixtures absichern.
3. Die verbleibenden 136 Review-Faelle nur nach visueller Crop-Bestaetigung in
Parser-Corpus oder Lernregeln uebernehmen.
4. Result-Klarheit und explizite Mutation-QA weiter staerken.
5. Erst nach eigenen Quellen fuer Charakterbesitz, Team, Waffe und Rotation
eine breitere Optimizer- oder Empfehlungsphase erwägen.
## Was Als Naechstes Ansteht
## Aktueller Nachweis
1. Artifact Value Evaluation ergaenzen, aber erst nach sauberer Extraktion und
weiterhin getrennt von OCR/Parser-Confidence.
2. Detail-Ansicht um Value-Gruende und optionale Upgrade-Projektion erweitern.
3. Packaged-App-Verhalten fuer Helper, IK-Listen, Preload-Bridge,
Crop-Preview und Smoke-Kommandos pruefen.
4. Empfehlungen und Build-UX erst danach wieder nach vorne ziehen.
## Current Validation Commands
```powershell
npm run scan:live:preflight
npm run scan:iterate:validated
npm run scan:goal:validated
npm run scan:repeatability:wait
npm run scan:assessment:validate -- --latest --summary
npm run eval
npm test
npm run build
```
Latest static validation after the Artifact-only Inventory UI update:
```powershell
npm run lint # passed
npm test # passed, 252 tests
npm run build # passed
git diff --check
```
`git diff --check` passed with existing CRLF warnings for
`electron/services/inputHelperPowerShellFallback.ts` and `src/styles/base.css`.
- `npm run acceptance:offline`: PASS
- `npm test`: 444/444 in 72 Dateien
- `npm run acceptance:offline`: final PASS nach Lokalisierung, lokaler
Loeschung, Timing, Korpus und UI-Acceptance-Runner; Package-Verifier 27/27
- Build-Fit-Ranker/Kontext/Profile: offline PASS; gebaute Renderer-UI PASS,
aber kein elevated Paket- oder neuer nativer Live-Claim
- `npm run package:verify`: 27/27
- `npm audit` und `npm audit --omit=dev`: 0 Findings
- Dev live: 5/20/50/100 PASS
- Settings UI live: Artifact-Limit 5, 5/5 Capture/Processing/Parsing,
0 Review/Fehler, `persist=false`, Ergebnisleiste 5 PASS
- Packaged Settings UI live: Reihenlimit 1 -> Ziel 8, 8/8
Capture/Processing/Parsing, 0 Review/Fehler, `persist=false` PASS
- Packaged Settings UI streaming: Artifact-Limit 20, maximal 11 Live-Resultate
waehrend Capture, final 20/20, 0 Review/Fehler/Writes PASS
- Packaged UI-Dichteabnahme `20260710-214406`: maximal 9 sichtbare Resultate
und 12 Evaluierungen waehrend Capture, final 20/20, 0 Review/Fehler/Writes;
Ergebnisflaeche 634 px bei 1304x821 ohne Dokument-Overflow PASS
- Packaged Full Inventory `20260710-223233`: OCR-Ziel/Capture/Results
2.211/2.211, 70 Seiten, 4,24 Capture/s, aktueller Package-Reprocess
2.211/2.211 mit 136 Review (6,15%), 0 Fehler/Writes; Saved-Run-Validator
2.075 evaluated, 0 unknown, `issues=0` PASS
- Packaged No-Genshin Safety: `genshinFound=false`, HWND 0, leerer
Zielprozess, keine Capture-Quelle und 0 Renderer-Fehler PASS
- Packaged live: Start/Bridge/Resources/Inventory und nativer 5er PASS
- Finale visuelle Evidenz:
`outputs/ui-qa/final-scan.png`, `outputs/ui-qa/final-scan-settings.png`,
`outputs/ui-qa/final-inventory.png` und die weiteren `final-*.png`-Ansichten
unter `outputs/ui-qa/`.
sowie `outputs/packaged-live/streaming-ui-20-results-view.png`
(temporäre lokale Dateien zum Abnahmezeitpunkt; bei der angeforderten
Workspace-Bereinigung am 2026-07-11 entfernt).