=== HTFlow for Kirki ===
Contributors: htflow
Tags: kirki, htflow, page builder, components, library
Requires at least: 5.8
Tested up to: 6.9
Requires PHP: 7.4
Stable tag: 1.0.0
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Browse your HTFlow library — sites, sections and the public showcase — from inside the Kirki visual builder and copy any page or section straight into your canvas.

== Description ==

**HTFlow for Kirki** plugs the HTFlow library directly into the Kirki visual builder.

When you open a Kirki page for editing, an HTFlow trigger appears in Kirki's left toolbar. Click it and a floating panel slides in from the right with three things at hand:

* **Components** — your saved HTFlow sections and the full public component library.
* **Websites** — your own HTFlow sites and the public showcase, page by page, with a live preview.
* **Copy to Kirki** — one button on every page or section. It converts HTFlow's HTML/CSS into Kirki's block format and writes it to the clipboard so Cmd/Ctrl+V drops it into your canvas.

Everything is proxied through your WordPress site, so your HTFlow access token never leaves the server. The panel UI itself is built with React (`@wordpress/element`) and styled to match the Kirki editor's own design tokens — light or dark, it follows whatever theme Kirki is on.

= What you need =

* An active **Kirki** plugin (the visual builder this addon hooks into).
* An **HTFlow account** at [htflow.com](https://htflow.com). The free tier lets you browse the public library; a paid plan unlocks the converter so you can copy public components straight into Kirki.

= Privacy =

The plugin talks to `htflow.com` only when you're using it — browsing the library, signing in, or copying a page. It never phones home in the background and stores no analytics on your server. Your HTFlow bearer token is kept in WordPress user meta on your own server, never synced anywhere else, and wiped when you uninstall.

== Installation ==

1. Make sure the **Kirki** plugin is installed and activated.
2. Upload the `htflow-for-kirki` folder to `/wp-content/plugins/`, or install through the Plugins screen.
3. Activate **HTFlow for Kirki** through the Plugins screen.
4. Edit any page with Kirki — the HTFlow icon will appear in the left toolbar.
5. Sign in with your HTFlow account on first use.

== External services ==

This plugin connects to the HTFlow API to load your component library. All traffic is server-to-server from your WordPress install — the browser only ever talks to your own site.

Endpoints used:

* `https://htflow.com/api/auth/extension-login` — exchanges your HTFlow credentials for an access token. The token is stored on the WordPress site, never sent back to the browser.
* `https://htflow.com/api/websites/extension` — lists your HTFlow sites and fetches a single page's build.
* `https://htflow.com/api/extension/sections` — lists, updates and deletes your saved sections.
* `https://htflow.com/api/public/components` and `https://htflow.com/api/public/books` — load the public component and site showcase.
* `https://htflow.com/api/webflow/convert` — converts a copied HTML/CSS payload into Kirki block JSON.

Data transmitted: your HTFlow email and password on first connect; the access token on subsequent calls; the search, pagination and identifiers required by each request; and — when you click "Copy to Kirki" — the HTML/CSS of the page or section you copied. No WordPress content is transmitted unless you explicitly import or sync a section.

* HTFlow terms of service: https://htflow.com/terms
* HTFlow privacy policy: https://htflow.com/privacy

== Frequently Asked Questions ==

= Where does my HTFlow login go? =

Email and password are sent once to htflow.com to exchange for an access token. The token lives in `wp_usermeta` on your server. It is never echoed back to the browser, never stored in localStorage, and never sent to any third party.

= I activated the plugin but the HTFlow icon doesn't show in Kirki. =

The panel only loads on the Kirki editor URL (`?action=kirki`). If you're sure you're on that screen and still don't see the icon, hard-reload the editor — build assets are versioned, but browser caches sometimes hang on to the old bundle.

= Does this work without Kirki? =

No. The plugin is a Kirki addon — it requires Kirki to be active. On WordPress 6.5+ the dependency is enforced at activation time; on older versions you'll see an admin notice.

= Can I copy content from the public showcase if I don't have a paid plan? =

You can browse and preview everything for free. The converter — the part that turns HTML/CSS into Kirki blocks — requires a paid HTFlow plan.

= Does the plugin make outbound calls in the background? =

No. The plugin only calls htflow.com in response to something you do — opening the panel, listing sites, previewing a page, or copying. It doesn't poll, run cron jobs, or load anything on the public front-end of your site.

== Screenshots ==

1. The HTFlow panel docked next to the Kirki canvas.
2. Browsing your own sites — pages preview at full desktop width.
3. The public showcase — same flow, full-page preview, one-click copy.
4. Saved sections with rename and delete.

== Changelog ==

= 1.0.0 — Initial release =

**Panel UI**

* HTFlow trigger button in the Kirki left toolbar (survives Kirki's React re-renders via a `MutationObserver`).
* Floating right-anchored panel built with `@wordpress/element`, styled with Kirki design tokens (auto light/dark).
* Components tab — Mine (saved sections) + Public (HTFlow component library).
* Websites tab — Mine (your HTFlow sites) + Public (showcase).
* Account dropdown with HTFlow account, HTFlow MCP and Sign out.
* "Create Website" CTA linking to htflow.com/websites.

**Browsing & navigation**

* Numbered client-side pagination on all four panes with smooth scroll-to-top.
* Live search filtering — instant after the initial fetch.
* 5-minute in-memory cache for list payloads; reopens are instant.
* Refresh icon busts both the browser cache and the WP transient.
* Lazy-loaded website thumbnails via `IntersectionObserver`.
* Dropdown page picker (`PagesNavigator`) for jumping between pages inside a site.
* Full desktop-width (1333px) previews scaled to fit the panel.

**Copy to Kirki**

* One-click copy on every page or section.
* Runs HTML/CSS through `htflow.com/api/webflow/convert` and writes the resulting block JSON to `localStorage["kirkiClipStore"]`.
* Briefly overrides `navigator.clipboard.readText` so Cmd/Ctrl+V drops the payload into the canvas without OS-clipboard interference.
* Rewrites `source: 'droip'` → `'kirki'` so copied sections render on the published front-end.

**Authentication**

* "Sign in with HTFlow" popup — opens htflow.com's hosted extension-auth page; token round-trips through a WP REST proxy and lands in user-meta, never in browser storage.
* Classic email and password form available as a fallback.
* Tokens validated against htflow.com (`/api/auth/me`) before they're persisted.

**Self-hosted auto-updates**

* `Updater` polls `https://plugins.htflow.com/kirki/update-manifest.json` and hooks into WordPress's standard update transients — new releases appear on the Plugins screen with the usual "Update now" button.
* Activation busts the WP update transient so fresh installs see pending updates immediately instead of waiting for the 12-hour cron.
* 3-hour manifest cache, automatically cleared after a successful upgrade.
* `HTFLOW_KIRKI_DISABLE_UPDATE_CACHE` constant + `htflow_kirki_manifest_url` filter for local testing.
* "Changelog" link on the plugin row points at the public release history.

**PHP architecture**

* PHP REST proxy under `/wp-json/htflow/v1/` for every htflow.com endpoint we use, so bearer tokens never reach the browser.
* Transient-based caching keyed per user and per query, with a refresh flag (`?refresh=1`) for explicit re-fetches.
* `htflow_kirki_api_base` and `htflow_kirki_api_request_args` filters for advanced overrides.
* Activation, deactivation and uninstall hooks; version tracking via the `htflow_kirki_version` option for future migrations.

**Standards**

* Translation-ready (text domain `htflow-for-kirki`).
* WordPress.org-style readme and plugin headers, `Requires Plugins: kirki` honoured on WP 6.5+.

== Upgrade Notice ==

= 1.0.0 =
Initial public release.
