Companion Scanner 1.0.15 - WoW Forever
====================================

A standalone pet collector's checklist with round world-map vendor/drop pins and
nearby alerts. No other addon is required. Uses the standard WoW UI and icons,
with ForeverGear's website murloc, woodland bear and wizard owl in the header.

INSTALL
Extract the CompanionScanner folder into:
C:\World of Warcraft\_forever_\Interface\AddOns\
The file should be AddOns\CompanionScanner\CompanionScanner.toc.
Restart WoW after adding this new addon, then enable Companion Scanner in the
character-selection AddOns list. Existing addon settings are not changed.

USE
/cs                     Open/close the searchable companion checklist.
/companionscanner       Same command, if another addon also uses /cs.
/cs options             Alert, sound, map and ownership-display settings.
/cs map                 Enable markers and open the world map.
/cs status              Show version, map mode, pin count and filters in chat.
/cs scan                Rescan bags and learned companions.
/cs range 150           Set alert distance, from 50 to 500 yards.
/cs resetalerts         Clear visit cooldowns; owned pets still never alert.
/cs sources             Print data/guide addresses into your local chat.

Minimap button: left-click the checklist, right-click options, drag to move.
OneForAll: when its Collect minimap buttons option is enabled, Companion
Scanner joins its button bar automatically. The same clicks work there.
Turning collection off returns the button to its original minimap position.
Dragging is disabled while collected so it cannot fight the bar's layout.
World-map pet pins: hover for sources/prices, click for details, right-click
to open the vendor's map and set a waypoint when the client supports it.
Search by pet, teaching item or vendor. All / Owned / Unowned buttons filter
the checklist and save per character. Owned includes learned pets, teaching
items in bags and your last bank scan. These list filters do not re-enable
owned-pet alerts or change the separate Hide owned pets on the map option.
Select a pet for acquisition details, prices, locations and Ignore alerts.

The detail panel shows an in-game 3D pet preview when the client supplies a
display or creature model. Use the arrow buttons to rotate it. If the model
is unavailable or does not load, the pet icon is shown with an explanation.
No journal filters are modified and previewing never summons or learns a pet.

Window appearance in /cs options provides Size (75-150%) and Transparency
(0-60%, where 0% is solid) sliders. Changes apply immediately to the pet
checklist, options and alert windows and save per character. Oversized
windows fit the screen automatically. Reset appearance restores default
size and opacity without changing collection, alert or map preferences.

Show on map highlights your chosen pet's location with a persistent label:
vendor/source name, pet, zone and coordinates. The checklist closes so you
can see the map. In OpenMap's seamless view it also centers on that location.
This explicit selection stays visible even when normal pins or owned pets
are hidden, without changing your filters or ownership settings. Click the
label's X to clear it, or choose another pet to replace it. No hover is needed.

OpenMap is optional. Its seamless map uses OpenMap's public coordinate API
and places pet icons above its artwork. Opening the map, changing zones,
panning and zooming update pins immediately. OpenMap's menu has a Companion
pets (vendors / quests / drops) toggle. Normal Blizzard maps are also supported.
Pins use the pet's icon. Hover distinguishes vendor purchases from drops.
In standard zone view, only sources in that zone are shown. Owned pets can
be hidden by the existing Hide owned option; this also applies to drop pins.

ALERTS AND OWNERSHIP
Default radius: 150 yards. One nearby vendor alert per visit, with a minimum
15-minute interval between return visits. Alerts are private: a brief popup,
chat line and optional sound. Nothing is sent to players, groups or channels.
Alerts wait until your learned collection and bags are readable and pause
during combat. Pins and the checklist remain available.

Learned species, teaching items in bags, and items recorded during your last
bank visit suppress alerts. Visit the bank once to populate its cache and
again after changing bank contents. A brief grace period covers consuming
a teaching item before the collection updates. Journal filters are untouched.
Ignore alerts is a separate preference; it does not mark a pet as collected.

Vendor locations indicate where a pet is normally sold, not guaranteed stock.
Lil Timmy and Flik require a nearby sighting (nameplate, target or mouseover)
or a merchant visit before alerting because their presence is intermittent.
Other moving vendors use their recorded patrol area. Visit a vendor to check
current availability. Sold-out or currently unpurchasable items do not produce
a merchant-confirmed alert. The addon never purchases an item automatically.

DATA COVERAGE AND PRICES
122 distinct species from the supplied Forever pet catalogue, including pets
whose acquisition is unknown, plus 13 clearly labeled item-only references.
All 102 item IDs in the three-page Forever companion-item list reviewed on
7 Nov 2026 are represented, including item variants. 28 vendor pets across
12 vendors are mapped. Item records do not imply current obtainability.
Temporary Mage familiar scrolls are not permanently learned pets. Unverified
species never use a guessed Pet Journal ID or generate proximity alerts.
Search accepts item IDs and listed source names as well as pet names.
Three documented drop pets have two grouped map locations: Black Tabby at
the Dalaran Spellscribe's reference spawn area in Silverpine; Siamese (Cookie)
and Green Wing Macaw (Defias Pirate) at the Deadmines entrance in Westfall.
The latter tooltip clearly states that the loot is INSIDE the dungeon.
Drop pins describe chances, never guaranteed loot, and do not send vendor
purchase alerts. Other unverified/unknown sources do not get invented pins.

The source guide labels many original pet sources as Classic references,
not confirmed Forever availability. These locations are starting points.
Built-in copper prices are older Forever client base-price estimates. They
can differ with reputation, changed costs and current Forever vendor stock.
A merchant visit records your actual offered price, stock and known teaching
items. Special currency costs are labeled rather than presented as free.
The addon can remember additional vendors selling known catalogue pet items.
It cannot discover an unknown/unidentified pet teaching item from its name.

WoW addons do not browse websites. Updates to the bundled catalogue need a
new addon version; merchant observations and collection checks happen locally.
See SOURCES.txt for provenance. All saved data is per character.

VALIDATION
Lua 5.1 syntax and 32 automated behavior scenarios passed, covering ownership,
bank caching, alert gating, stock/prices, discovered vendors, map projection
and menu interaction, OpenMap layers/projection/events, drop pins, and actual
installed OneForAll collector code running with mocked WoW frame APIs,
selected-location labels with hidden pins, ownership, zoom and dismissal,
appearance persistence, reset and automatic screen fitting, collection tabs,
and model display/rotation, missing-data fallback and stale-load handling.
Live in-game appearance and behavior still need testing
on the current Forever client; automated tests use mocked client APIs.

MURLOC ALERTS AND PET QUESTS (1.0.5)
The alert is a speech bubble beside WoW's own Murky model, read from the
client's pet journal. If its model cannot load, WoW's murloc portrait is used.
No website illustration or copied model files are bundled. View pets opens
the pet's details and preview. The popup lasts 12 seconds, hides in combat,
and respects the saved window size and transparency.

Known quest routes cover Mechanical Chicken, Sprite Darter Hatchling,
Worg Pup, Smolderweb Hatchling, Speedy, Mr. Wiggles, Whiskers the Rat and
Spirit of Summer. Quest-chain markers identify intermediate steps, not
immediate rewards. Level, faction, prerequisites and completed quests are
checked before location alerts. Seasonal routes require a current quest
offer or an active quest; a seasonal NPC sighting alone is not enough.

Every alert checks learned species, bags, last bank scan and ignored pets.
Owned pets are excluded regardless of the All / Owned / Unowned list filter.
Disable quest alerts separately with Include pet reward quests in /cs options.
The Nearby pet alerts master switch controls both vendor and quest alerts.

Opening a quest can record additional known pet teaching items as rewards
and save that giver's interaction location. It never accepts or turns in
quests. Unknown pet items are not guessed. Some Forever pets have no verified
source, so this is not complete coverage of every pet quest. CLUCK is not
mapped until its reward can be matched reliably to a Forever pet species;
collector-edition entitlement quests are not mapped as normal pet quests.

Validation: 32 automated addon checks passed. Actual in-game visual layout
and model loading must still be confirmed in the Forever client.

MODEL ZOOM (1.0.6)
Use Zoom - / Zoom + below the pet preview or scroll the mouse wheel over
the model. Larger pets start with a wider camera view. Each pet remembers
its zoom per character. Reset restores default zoom and rotation. The
arrows still rotate the pet. Zoom controls appear once the model is ready.

MINIMAP AND THEMES
A draggable minimap shortcut works with OneForAll when Collect buttons is enabled.
Right-click opens this addon's settings. Windows follow your ForeverGear
companion theme; without ForeverGear, they use your character class colors.
Choose a companion theme with /fg themes.

FOREVER SOURCE UPDATE (7 NOV 2026)
Nine additional vendor pets now have map locations, including Prairie Wolf Pup.
Mayhoa Skyhoof patrols Orgrimmar; route pins are not a guaranteed current
position. Her nearby alert requires a recent NPC sighting and an unowned pet.
Adds rare-enemy drop areas for Baby Crocolisk, Condor Hatchling and Tallstrider
Hatchling. Snowy Wolf Pup still has no verified acquisition source.
Additional quest, currency and reputation requirements appear in pet details;
no coordinates are invented where a giver or vendor position is unverified.

LOCATION-SPECIFIC POPUP CHOICES (1.0.14)
Ignore here on a murloc popup remembers its shown pets at that source and
nearby trigger area for this character, including across reloads and visits.
Other sources, distant locations and pets not shown in that popup still alert.
Dismiss only closes the current popup. Options > Restore ignored locations
clears these local choices without changing your Ignore everywhere pet choices.
The trigger position is captured when the popup opens, not when you click it.
Map pins and collection entries remain visible under your existing filters.

COLLECTION TOOLTIP COLORS
Pet-list, map-source and native pet-item tooltips show green Collected for a
learned pet and yellow Not collected otherwise. Unlearned teaching items in
bags or the last bank scan are identified separately. Loading/uncertain data
says Checking collection. Item-only references never claim learned ownership.

BLIZZARD PET JOURNAL (1.0.14)
Select a pet in Blizzard's Pet Journal to see its acquisition details in the
lower-right panel, beneath the native model preview. The native pet list,
model and summon controls remain available. Pet details switches back to
Blizzard's usual lower panel; Where to get reopens source information.
The selected pet shows collection status, source, estimated or last-seen
price, coordinates, and recorded requirements. Use the source arrows for
alternative vendors or quest steps, then Show on map to pin that source.
Open Scanner takes you to the same pet's full catalogue entry.
Unknown pets and sources are identified; no map button is enabled without a
recorded location. Hovering the selected pet header also adds source details.
The source-view choice is remembered per character. Restart WoW after updating
to load the new journal module.

MAP ICON SIZE AND FILTER (1.0.15)
- Options > Map icon size: 16-40 pixels, with a smaller 22-pixel default.
- Updates immediately, saves per character, and stays the same apparent size at different map zoom levels.
- The selected Show on map marker also scales; its location label stays readable.
- Blizzard map filter > Companion Scanner pet locations toggles regular source markers.
- OpenMap > Show > Companion Scanner offers the same saved switch.
- Show on map can still highlight a specifically selected source while regular markers are hidden; close its label to dismiss it.
- Reset appearance restores map icons to 22 pixels along with window size/transparency.
