# PatchEntry SearchHints and CandidateFileNames in Wand-Enhancer: Purpose and Implementation

> Discover the purpose of PatchEntry SearchHints and CandidateFileNames in Wand-Enhancer. Ensure secure JavaScript patching by verifying file paths and code versions.

- Repository: [k1tbyte/Wand-Enhancer](https://github.com/k1tbyte/Wand-Enhancer)
- Tags: internals
- Published: 2026-09-01

---

**PatchEntry's SearchHints and CandidateFileNames properties provide a two-step verification system that ensures JavaScript patches are applied only to correct file paths and specific code versions, preventing application corruption when Wand updates alter its bundle structure.**

The **Wand-Enhancer** project implements a robust patching mechanism for modifying Wand's JavaScript bundles packaged within ASAR archives. At the core of this configuration-driven system lies the `PatchEntry` class defined in [`WandEnhancer/Core/EnhancerConfig.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/EnhancerConfig.cs), which leverages **SearchHints** and **CandidateFileNames** to accurately locate target code while maintaining version safety across different Wand releases.

## Two-Step Verification: File Targeting and Version Safety

The patching engine employs a defensive strategy that verifies both file location and content integrity before applying any modifications. This dual-check mechanism prevents the injector from corrupting unsupported Wand versions when the target code has changed between updates.

### CandidateFileNames Property

**CandidateFileNames** is a string array containing file-path patterns relative to the ASAR root where the patch might validly reside. This property narrows the search space by filtering the extracted ASAR contents to only relevant bundles, such as [`renderer.js`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/renderer.js) or [`services/account.js`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/services/account.js), rather than scanning every file in the archive.

### SearchHints Property

**SearchHints** is a string array containing unique identifiers—such as function names, endpoint URLs, or specific comments—that must exist within the target file's source code. Before a patch is applied, the engine validates that the file content contains at least one of these hints, confirming the file matches the expected version and structure the patch was designed to modify.

## Implementation in the Wand-Enhancer Source Code

According to the source code in the `k1tbyte/Wand-Enhancer` repository, the verification logic is implemented in [`WandEnhancer/Core/Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/Enhancer.cs) through the `CanSearchPatchInFile` and `ContainsSearchHint` methods. The `PatchEntry` class itself is defined in [`WandEnhancer/Core/EnhancerConfig.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/EnhancerConfig.cs) alongside a static dictionary mapping `EPatchType` values to their respective patch configurations.

The patching workflow follows this sequence:

1. The engine extracts the ASAR archive and iterates through the extracted files.
2. For each `PatchEntry`, `CanSearchPatchInFile` checks if the current file path ends with any of the `CandidateFileNames` entries.
3. If the filename matches, `ContainsSearchHint` scans the file content for any string in the `SearchHints` array.
4. Only when both conditions pass does the engine invoke `ApplyJsPatch` to inject the JavaScript modification.

```csharp
// Example PatchEntry configuration from EnhancerConfig.cs
new PatchEntry {
    Patch = "// JavaScript code to inject...",
    SearchHints = new[] {
        "getUserAccount()", 
        "/v3/account"
    },
    CandidateFileNames = new[] { 
        "renderer.js", 
        "services/account.js" 
    }
};

```

```csharp
// Core verification logic concept from Enhancer.cs
bool CanApplyPatch(string filePath, string fileContent, PatchEntry entry) =>
    entry.CandidateFileNames.Any(name => filePath.EndsWith(name)) &&
    entry.SearchHints.Any(hint => fileContent.Contains(hint));

```

## Summary

- **CandidateFileNames** filters the ASAR extraction to specific file paths, ensuring the patch engine only inspects relevant JavaScript bundles like [`renderer.js`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/renderer.js) or service files.
- **SearchHints** provides content-based verification by checking for unique code signatures, protecting against version mismatches that could corrupt the application.
- Both properties must validate successfully before `ApplyJsPatch` executes, creating a fail-safe mechanism that skips incompatible patches silently rather than causing runtime errors.
- The configuration resides in [`WandEnhancer/Core/EnhancerConfig.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/EnhancerConfig.cs) while the execution logic lives in [`WandEnhancer/Core/Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/Enhancer.cs), with UI selection handled in [`WandEnhancer/View/Popups/PatchVectorsPopup.xaml.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/View/Popups/PatchVectorsPopup.xaml.cs) and settings managed through [`WandEnhancer/Models/PatchConfig.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Models/PatchConfig.cs).

## Frequently Asked Questions

### What happens if SearchHints are not found in a matching candidate file?

If the file path matches a `CandidateFileNames` entry but `ContainsSearchHint` fails to locate any hints in the content, the patch engine skips that file and reports that the patch could not be applied. This typically indicates the user's Wand build is newer or older than the patch supports, preventing accidental code corruption.

### Can CandidateFileNames use wildcards or regular expressions?

Based on the source implementation in [`Enhancer.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/Enhancer.cs), the matching uses simple string suffix checks (typically `filePath.EndsWith(name)`). While the examples show specific filenames like [`renderer.js`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/renderer.js), the array structure supports multiple entries to cover different possible paths without requiring regex patterns.

### How does this system prevent corruption when Wand updates?

The two-step verification requires both filename and content confirmation. When Wand updates change line numbers or rename functions, the `SearchHints` check fails because the expected strings no longer exist in the source. This causes the patcher to skip the modification rather than injecting code into the wrong location, ensuring the application remains functional even when patches become outdated.

### Where are patch definitions configured in the codebase?

Static patch definitions are stored in [`WandEnhancer/Core/EnhancerConfig.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/WandEnhancer/Core/EnhancerConfig.cs) as a dictionary mapping `EPatchType` enums to `PatchEntry` instances. At runtime, the UI in [`PatchVectorsPopup.xaml.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/PatchVectorsPopup.xaml.cs) presents these options to the user, and the selected types are passed via [`PatchConfig.cs`](https://github.com/k1tbyte/Wand-Enhancer/blob/main/PatchConfig.cs) to the `Enhancer` class which orchestrates the patching process.