4.0.1: README rewrite, rendered screenshots, AI assistant guide, and five fixes

[itsarvinddev]

Summary

A rewrite of the README to make it clearer, with better screenshots and a guide for AI coding assistants. Rendering the screenshots through the real widgets also turned up five package defects, which are fixed here as 4.0.1.

Preview the README: https://github.com/itsarvinddev/map_location_picker/blob/docs/readme-visuals-and-llm-guide/README.md

README

• Getting started in four steps: requirements, API key, per-platform setup in collapsible sections, and a first pick.
• A section for each feature: picking modes, current location, search restriction, nearby places, embedding, the controller, reading the result, errors, localization, theming, customisation, and the standalone search field.
• Configuration reference, API key security and costs, and troubleshooting.
• Corrections:
  • The iOS AppDelegate snippet didn't match current Flutter templates.
  • Android was listed as API 21; google_maps_flutter_android needs 24.
• Newly documented:
  • An embedded map inside a scroll view needs an EagerGestureRecognizer, or it won't receive drags.
  • Dark mode needs a mapStyle or cloudMapId, because Google's tiles don't switch automatically.

Screenshots

• tool/screenshots renders eight scenes from the real widgets. Canned Places and Geocoding responses mean autocomplete, place details and nearby search all run through the package's own code. frame.py adds device frames and builds the hero image.
• Google's tiles can't load in a test, so the map is an illustration, and the README says so under the gallery.
• A single WebP set serves both the README and pub.dev. The pub.dev gallery grows from 3 images to 8, and the archive shrinks from about 10 MB to 915 KB.
• The README uses relative image paths. They render in this branch's preview, and pub.dev resolves them against the repository.

AI coding assistants

• llms.txt: an authoritative 4.x API reference for language models.
• Project rules to paste into CLAUDE.md, AGENTS.md, .github/copilot-instructions.md, .cursor/rules/*.mdc or GEMINI.md.
• Seven copy-paste prompts: integrate, delivery step, embed, migrate from 3.x, localize with gen-l10n, debug empty search, and write tests.

How the prompts were tested

Each prompt went to a fresh assistant that could not see the package source or run the analyzer. It worked in a small Flutter project built for that scenario. A second agent then ran flutter analyze (plus gen-l10n and flutter test where relevant), checked every identifier against lib/, and traced each failure back to the prompt text.

Prompt	Round 1	Round 2
Integrate	8	10
Delivery step	8	8
Embed	8	9
Migrate	6 (compile error)	9
Localize	8	10
Troubleshoot	8	9
Tests	9	9

In round 2, all seven analyze clean and use no invented APIs. Round 1 found:

• Migrate: searchConfig was moved inside MapLocationPickerConfig, which doesn't compile.
• Several prompts: the assistant advised enabling the legacy "Places API".
• Localize: the nearbyPlaces* strings were translated as "nearby places", but they label matching addresses.
• Troubleshoot: it missed that a String.fromEnvironment key without --dart-define is empty.
• Tests: it came close to using testWidgets, which fails on the controller's pending timer.

Both the prompts and llms.txt were fixed to cover each of these. A few smaller round-2 suggestions (location permissions and the web script tag in the delivery reply, and the scroll-view gesture note) were applied without a third run.

Package fixes (4.0.1)

• Migration path: showMapLocationPicker threw when a 3.x-style onNext popped with a GeocodingResult. The route now accepts any popped value and still returns the PickedPlace.
• Controller geocoder: a geocoder passed to MapLocationPickerController was silently replaced when the widget mounted.
• Layout:
  • The back button and search field now share one row.
  • bottomCardTitle is aligned with the address below it.
  • The default search hint is no longer clipped next to the back button.

Each fix has a regression test in test/show_picker_result_test.dart.

Verification

• dart format: clean.
• flutter analyze --fatal-infos, package and example: clean on 3.47.2 and on the 3.38.1 floor, including the pub downgrade pass.
• flutter test: 89 passed on both SDKs. The screenshot harness renders on both.
• Every Dart sample in the README compiles in example/lib/readme_samples.dart.
• flutter pub publish --dry-run: no warnings except uncommitted files at the time.
• pana: 160/160 with the eight new screenshots.

Pre-release audit (commit ca4ec43)

Before merging and publishing, every factual claim in the README, llms.txt, CHANGELOG and migration guide was checked against lib/, both Flutter app templates, the plugin sources and live Google endpoints.

• First pass: 478 claims checked, and 22 findings survived an adversarial refutation step.
• Second pass, over the corrections themselves: 106 claims checked, and 10 more survived.

The most important fixes:

• iOS deployment target: apps created with Flutter 3.38 target iOS 13, but the Google Maps plugin needs 14, so pod install failed. This is now documented.
• iOS snippet: it was shown as a complete AppDelegate.swift, and pasting it removed plugin registration. It now shows only the two additions.
• Web script: the Maps script is now loaded synchronously, as google_maps_flutter_web documents. This applies to the README, llms.txt, the prompts and the example app.
• Headers sample: it used dart:io Platform, which throws on web. The guidance now also covers the Geocoding API rejecting referrer-restricted keys.
• Error kinds, documented per API: with Places (New), a wrong key arrives as invalidRequest. With the Geocoding API it arrives as requestDenied. An empty key fails search with unknown in debug builds.
• Migration: the README section and prompt now follow MIGRATION_GUIDE.md. Previously they presented 1.x/2.x renames as 3.x→4.x changes.

The prompts were then re-evaluated blind (round 3). All seven analyze with zero errors and no invented APIs, scoring 9, 9, 8, 9, 10, 9 and 10.

Before merging

• The README and the prompts reference ^4.0.1, and the prompts link to llms.txt on master. Merge and publish 4.0.1 together, otherwise a user who copies the README during the gap gets a version that doesn't exist yet.
• Not verified: web map gestures along the bottom strip under PointerInterceptor. This is unchanged from 4.0.0.

🤖 Generated with Claude Code

[Copilot]

Copilot was unable to review this pull request because the user who requested the review has reached their quota limit.