=== Granpai3DGlobe ===
Contributors: higranpai
Tags: globe, map, 3d map, interactive map, world map
Requires at least: 6.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 2.6.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A high-performance WebGL 3D Globe / flat world map plugin, organized into Maps, each with its own list of interactive Pins.

== Description ==

Granpai3DGlobe lets you drop an interactive, rotating 3D globe (or a flat world map) anywhere on your site with a simple shortcode. Add pins for offices, stores, events, or team members, and each pin opens a clean modal with its own heading and text when clicked.

**Core features (Free)**

* 3D Globe or Flat map mode, each with a Dark or Light theme
* Photoreal (satellite imagery) or Minimal (clean line-art) globe style
* Custom pin color per map
* Unlimited maps and pins are a Pro feature - Free includes 1 map with up to 2 pins, so you can try it fully before upgrading
* Simple shortcode: `[Granpai3DGlobe id="123"]`
* Import / Export your maps and pins as JSON

**Pro add-on (sold separately)**

* Unlimited maps and pins
* Pin images and contact/social icons (email, phone, website, Facebook, X, Instagram, LinkedIn) shown in the pin's modal
* Next / Previous navigation between pins, with an animated flight-line arc and a focus "flash" on the destination marker
* Custom initial camera focus point per map
* Modal tag color, modal border color, and globe base color overrides

Pro is a separate, small companion plugin that only ever hooks into the extension points this plugin exposes - it never modifies this plugin's files.

== Installation ==

1. Upload the plugin files to `/wp-content/plugins/granpai3dglobe`, or install directly through the WordPress plugins screen.
2. Activate the plugin through the 'Plugins' screen in WordPress.
3. Go to **3D Globe Maps > Add New Map** in the admin sidebar, configure it, and add your pins.
4. Copy the shortcode shown on the map's edit screen into any post, page, or widget.

== Frequently Asked Questions ==

= Does this work without a Pro license? =

Yes. The Free plan includes 1 map with up to 2 pins, every render mode/theme/style, and the full Import/Export tools - enough to fully evaluate the plugin before deciding on Pro.

= Can I recolor the Photoreal globe style? =

No - Photoreal uses a real satellite photo texture of Earth, which can't be recolored as a flat color. The Minimal style (Pro) supports a custom globe base color instead.

= Where do I manage my Pro license? =

Under **3D Globe Maps > Settings > License** once the Pro add-on is installed and active.

== Changelog ==

= 2.6.0-alpha =
* Redesigned pin clustering: overlapping pins are no longer hidden behind a single marker with a count badge - every pin now stays visible and individually clickable, fanned out in a small arc with a thin leg connecting it back to its true position. Fixes clustered pins being unreachable (or seemingly not navigating anywhere) from the Pin List Sidebar.

= 2.5.5-alpha =
* Fixed the real, likely long-standing cause of the modal behaving erratically specifically in the admin Map Settings preview: every field change rebuilds the whole preview from scratch (js/admin-map-preview.js), but the PREVIOUS instance's own document/window-level listeners (Escape key, arrow-key navigation, resize, the initial cluster calculation) were never cleaned up - they kept running against now-removed elements, one more leaking in on every single change. All of them now check that their own instance is still actually on the page before doing anything.

= 2.5.4-alpha =
* Further fix for the false-positive cluster badge on page load (e.g. a lone pin near Paris showing "2"): the very first cluster calculation now waits noticeably longer for three-globe to finish positioning every marker to match the initial camera framing, instead of trusting a single animation frame.

= 2.5.3-alpha =
* Fixed a false-positive cluster: a pin on the globe's far side could project to the same screen pixel as one on the near side and get wrongly counted together, showing a "2" badge on a genuinely lone pin. Far-side pins are now excluded from clustering.
* Fixed lingering erratic modal/navigation behavior: the docked-modal overflow fix now only ever adjusts for the admin preview's own known box, never any other page element - and cluster recalculation now pauses entirely once a pin has been selected, so it can never change a marker's visibility while Next/Prev or the modal are in use.

= 2.5.2-alpha =
* Fixed a fatal PHP error introduced in 2.5.0-alpha ("critical error" site-wide) - a CSS comment used double quotes inside a double-quoted PHP string, terminating it early. Every PHP file in the plugin has been syntax-checked to confirm nothing else is affected.

= 2.5.1-alpha =
* Fixed the new marker clustering (2.5.0-alpha) recomputing on a marker's own hover-pause, which could hide the very marker being hovered and cascade into a pause/resume/hide/show loop - erratic modal behavior when clicking a pin or using Next/Prev. Clustering now only recomputes when the camera genuinely settles (drag/zoom end) or on initial load.

= 2.5.0-alpha =
* Added marker clustering for pins that render on top of each other on-screen (same coordinates, or just close enough at the current zoom level): they now group into a single marker with a count badge instead of hiding each other. Works in both 3D Globe and Flat map modes. Clicking a grouped marker currently opens the first pin in the group - a proper picker to choose which one is a follow-up.

= 2.4.2-alpha =
* Fixed the admin Map Settings live preview blurring the rest of the edit screen (Map Settings, Pins, Publish box) when testing a pin, with no way to undo it.

= 2.4.1-alpha =
* Fixed a regression from 2.4.0-alpha's admin-preview overflow fix that could push the pin modal off-screen (wrong position) from the second pin onward on some sites - the fix now only kicks in for a genuinely narrow clipping box (like the admin preview), not a full-width section that merely sets overflow:hidden for unrelated reasons.
* Cached the Pro license check for the duration of a page load, cutting down repeated calls on pages with many pins.

= 2.4.0-alpha =
* Added a "Clone" row action on the Globe Maps list to duplicate a map together with all its pins (created as a draft for review before publishing).
* Fixed the admin Map Settings live preview's modal close button becoming unreachable when the docked modal overflowed the narrow preview box.
* Fixed a Pro-only issue where opening a pin could leave the page permanently blurred with no way back, when using the Pin List Sidebar layout.

= 2.3.0-alpha =
* Added a small hook (granpai:goto-pin event + pin index on granpai:modal-open) so a Pro-only feature can move the camera/view to a specific pin and stay in sync - no visible change for Free-only installs.

= 2.2.0-alpha =
* Added a Zoom on/off toggle for 3D Globe mode (Map Settings) - turn it off to keep only the auto-rotate spin effect, with no mouse-wheel/hover zoom in/out.
* Fixed the docked pin modal overflowing off-screen when the map is embedded in a wide/full-width section - it now measures the exact overflow and nudges itself back on-canvas by only that amount, instead of a fixed viewport-width guess.

= 2.1.1-alpha =
* Fixed the globe getting cropped on all sides when clicking a pin (camera zoom now respects the container's aspect ratio instead of a fixed close-up altitude).
* Modal height on wide/docked layouts is no longer capped by the map's own container height - uses available viewport height instead.
* Pin modal now blurs surrounding page content outside the map itself when open, drawing focus to the pin without touching the map/modal.
* Pin images in the modal now show at full/natural height instead of being cropped to a fixed 200px band.

= 2.1.0-alpha =
* Compacted the Map Settings screen layout.
* Added a live preview in the Map editor.
* Added per-map initial camera focus point (latitude/longitude).
* Added Pro: modal next/prev navigation with a flight-line arc between pins.
* Added Pro: modal label/border color and globe base color overrides, with an on/off toggle for the flight-line arc.
* Pro features now correctly pause (without losing any saved data) if a license lapses, instead of continuing to show stale data.
* Removed the unused "General" defaults tab.

= 2.0.0-alpha =
* Rebuilt from scratch around a Map + Pin data model (previously a single shortcode with attributes).
* Added Flat map mode, Light theme, and Minimal globe style.
* Added Import / Export.
* Added the Pro add-on: pin images/contacts, modal navigation with flight-line arcs, and appearance overrides.

== Upgrade Notice ==

= 2.1.0-alpha =
If you're running the Pro add-on, update both plugins together - Pro checks the free plugin's version and pauses its features with a clear notice if they're out of sync.
