=== MapAPlace ===
Contributors: mapaplace
Tags: maps, gutenberg, block, embed
Requires at least: 6.5
Requires PHP: 8.1
Stable tag: 0.1.31
License: GPL-2.0-or-later

Connect WordPress to MapAPlace and render published maps directly with a Gutenberg block.

== Installation ==

1. Upload the `mapaplace` directory to `/wp-content/plugins/` and activate the plugin.
2. Open MapAPlace > Connect in WordPress admin and select Connect to MapAPlace.
3. Sign in to MapAPlace in the popup and approve the connection. WordPress stores and tests the generated map-management credential automatically.
4. Add the MapAPlace Map block and select a published map from the block settings sidebar.

The generated credential is used only in server-side requests. Stored secrets and short-lived access-token caches are encrypted using native or WordPress-compatible Sodium, or AES-256-GCM when Sodium is unavailable. Published artifacts are loaded through the connected account and cached against that credential, so blocks cannot continue loading a previous account's maps after the connection changes. The published artifact is passed to the shared MapAPlace JavaScript renderer, so the map does not use an iframe.

== Capabilities ==

* `manage_options` is always required to connect or disconnect MapAPlace and to access connection settings. This requirement is deliberately not filterable.
* `edit_mapaplace_maps` controls access to the embedded MapAPlace editor and its secure bridge. It is granted to administrators by default.
* `use_mapaplace_block` controls whether a user can insert the block and request published map choices and previews. It is granted to administrators, editors, authors, and contributors by default.

Sites can assign the custom capabilities to different roles. The `mapaplace_map_editor_capability` and `mapaplace_block_editor_capability` filters can map editor or block access to another valid WordPress capability. Invalid filtered values fail closed.

== Extension hooks ==

The free plugin exposes focused extension points for separately installed add-ons. An add-on registers its own bootstrap, activation, uninstall, settings, assets, and translations, then attaches modules to `mapaplace_register_modules`.

== Uninstall ==

Deleting the plugin removes its locally stored connection settings, capabilities, access tokens, connection requests, extension-access leases, published-map caches, and generated renderer stylesheet files from every site in a WordPress multisite network. It does not revoke the remote MapAPlace API credential, remove server-managed `MAPAPLACE_API_*` constants, delete maps stored by MapAPlace, remove separately installed add-ons, or alter user-authored post and page content. Disconnect the integration before deleting the plugin when the remote credential should also be revoked.

* `mapaplace_register_services` action: register services in the shared container.
* `access.extensions` container service: check an extension's declared required access level through the MapAPlace API and briefly cache the credential-bound, fail-closed result.
* `mapaplace_extension_access_purchase_url` filter: provide the checkout URL used by locked extension cards. Receives the extension ID and required access level after the default URL.
* `mapaplace_show_extensions_page` filter: return true from an active add-on to create the shared Extensions submenu.
* `mapaplace_modules` filter: add or replace modules before registration.
* `mapaplace_register_modules` action: add modules through the module registry.
* `mapaplace_module_registered` action: runs after each module registers.
* `mapaplace_admin_menu_registered` action: add module submenu pages below the shared MapAPlace admin menu.
* `mapaplace_disconnected` action: runs after the locally stored connection and token cache are removed.
* `mapaplace_connection_verified` action: runs after the free plugin verifies a live connection, allowing an installed add-on to register its own remote integration without coupling that feature to the free plugin.
* `mapaplace_loaded` action: runs after the plugin has completed booting.
* `mapaplace_api_request_args` filter: adjust the bounded request timeout and user agent. Security-critical URL, credential, redirect, TLS, origin, and size controls cannot be replaced.
* `mapaplace_api_max_map_pages` filter: adjust the bounded number of remote map-list pages.
* `mapaplace_api_maps` filter: adjust normalized maps returned by the API client.
* `mapaplace_block_map_choices` filter: adjust published choices sent to Gutenberg. Choices are normalized again before output.
* `mapaplace_map_editor_capability` filter: replace the capability required to open and extend the embedded editor. Defaults to `edit_mapaplace_maps`.
* `mapaplace_block_editor_capability` filter: replace the capability required to insert the block and load map choices or previews. Defaults to `use_mapaplace_block`.
* `mapaplace_block_wrapper_classes` filter: add sanitized block wrapper classes.
* `mapaplace_renderer_style_cache_ttl` filter: control how often the content-hashed renderer stylesheet cached in WordPress uploads is checked for updates (one day by default, bounded from one hour to seven days).
* `mapaplace_before_map_block_render` and `mapaplace_after_map_block_render` actions: observe dynamic block rendering.
* `mapaplace_settings_page_sections` action: render an extension-owned card on the connected Connect page.
* `mapaplace_extensions_page_notices` action: render notices on the connected Extensions page.
* `mapaplace_extension_settings_panels` action: render an installed add-on's settings card on the Extensions page.
* `mapaplace_block_runtime_marker_collections` filter: add bounded dynamic marker/category collections to frontend and Gutenberg renderer calls.
* `mapaplace_editor_panels` filter: register bounded declarative settings panels in the MapAPlace editor embedded in WordPress admin.

An add-on can register a panel without executing its PHP or JavaScript inside the cross-origin MapAPlace frame:

`add_filter('mapaplace_editor_panels', function (array $panels): array {`
`    $panels[] = array(`
`        'id' => 'venue',`
`        'title' => 'Venue',`
`        'sections' => array(array(`
`            'id' => 'display',`
`            'title' => 'Display',`
`            'controls' => array(array(`
`                'id' => 'show-label',`
`                'type' => 'toggle',`
`                'label' => 'Show label',`
`                'default' => true,`
`            )),`
`        )),`
`    );`
`    return $panels;`
`});`

JavaScript add-ons can depend on the `mapaplace-editor-bridge` script handle and call `window.MapAPlaceWordPressEditor.registerPanel(definition)` for declarative fields or `registerExtension(definition)` for an installed MapAPlace editor extension. Panel values are saved with the map under `extensions.wordpress.values`. Definitions support dropdown, number, text, textarea, and toggle controls only. Every parent-to-editor message uses a short-lived API-signed ticket, every editor-to-parent message checks the live connection, and both sides require the exact iframe window, origin, channel, sequence, and payload hash.

Premium functionality, including Post Type Markers, is distributed as a separate add-on and is not included in this free plugin.

== Changelog ==

= 0.1.31 =
* Hidden the Extensions page until WordPress has a configured MapAPlace connection.

= 0.1.30 =
* Added a throttled self-repair for stale connection-check proof tokens.

= 0.1.29 =
* Retried failed connection-target synchronisation promptly and improved connection-check diagnostics.

= 0.1.28 =
* Fixed connection checks for WordPress installations hosted in a subdirectory.

= 0.1.27 =
* Added self-contained styling for Routes and Navigation controls in WordPress maps.

= 0.1.26 =
* Restored saved routes and live navigation in Gutenberg map previews and published blocks.

= 0.1.25 =
* Moved Post Type Markers into a separately installed premium add-on.
* Replaced bundled-extension loading with generic add-on registration and connection-verification hooks.
