=== Sangar Studio Access Flow ===
Contributors: sangarstudio
Author: Sangar Studio
Author URI: https://sangar.studio
Donate link: https://sangar.studio
Tags: accessibility, neurodiversity, adhd, dyslexia, focus
Requires at least: 5.8
Tested up to: 7.0
Stable tag: 1.0.0
Requires PHP: 7.4
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

A cognitive adaptation layer for neurodivergent users: ADHD, dyslexia, autism and sensory sensitivity.

== Description ==

**Sangar Studio Access Flow** is not a generic WCAG accessibility overlay. It is a **cognitive adaptation layer** designed specifically for people with ADHD, dyslexia, autism, anxiety and sensory overload.

Unlike traditional accessibility plugins that offer static controls (font size sliders, contrast, big cursor), Access Flow combines **preconfigured neurodivergent profiles**, **proactive behavioral adaptation** and **reading transformations** like Bionic Reading and Reading Ruler that the target audience recognizes immediately.

=== Philosophy ===

* Does not promise WCAG legal compliance on its own.
* Speaks in human language ("How do you prefer to read today?"), not clinical.
* Lets the user describe how they are, not what disability they have.
* Honors `prefers-reduced-motion` and the system's forced-colors mode.

=== Main features ===

* **Neurodivergent profiles:** The user picks how they prefer to read today (ADHD / Dyslexia / Autism / Sensory sensitivity) and the optimal mode combination is enabled automatically.
* **Behavioral UX Engine:** Detects erratic scrolling and frustration clicks in real time and proactively suggests Focus Mode when cognitive overload is detected.
* **Focus Mode:** Dims sidebars, banners, popups, ads and iframes detected automatically for the active theme (Astra, GeneratePress, OceanWP, Storefront, Divi) and through admin-configurable custom selectors.
* **Bionic Reading:** Bolds the prefix of each word in the main content so the eye anchors faster, reducing reading fatigue. Especially effective for ADHD and dyslexia. Fully reversible.
* **Reading Ruler:** A horizontal band that follows the cursor or finger, guiding the reading line and preventing line skipping.
* **Dyslexia Reading:** Adapted typography (OpenDyslexic / Comic Sans MS), increased line height, letter spacing and word spacing. Excludes icons, code and SVG so they are not broken.
* **Calm Interface:** Disables animations, reduces saturation and applies a warm tint to mitigate sensory overload.
* **Smart Content Simplifier:** Summarizes the main content of the page using OpenAI (`gpt-4o-mini`) in plain language, short sentences and lists. Hourly cache to save quota.
* **Customizable identity:** Primary color, icon color, border color and position (left or right) configurable from the admin so the widget integrates with the site's brand.

=== Accessibility of the widget itself ===

* `role="dialog"` + `aria-modal="true"` + `aria-labelledby` + focus trap.
* Full keyboard navigation: Tab / Shift+Tab inside the panel, Escape to close.
* `aria-pressed` on mode buttons, `aria-busy` during requests.
* `:focus-visible` with an amber outline on all controls.
* Honors `prefers-reduced-motion` and `forced-colors` (Windows high contrast).
* The widget is not dimmed by Calm Mode so its contrast stays intact.

== Installation ==

1. Upload the plugin folder to `/wp-content/plugins/sangar-studio-access-flow/`.
2. Activate it from the **Plugins** screen in WordPress admin.
3. Go to the new **Access Flow** menu in the sidebar.
4. (Optional) Configure your **OpenAI API Key** if you want AI summaries.
5. Customize the **Toolbar Identity** (colors and position) to integrate the widget with your site.
6. The widget appears vertically centered on the chosen edge of the frontend.

== External services ==

This plugin can connect to OpenAI to generate AI-powered summaries of the current page content. This service is **only used when the site administrator provides an OpenAI API key in the plugin settings and the visitor explicitly clicks the "Summarize this page" button** in the floating widget. If no API key is configured, or the feature is disabled in settings, no request to OpenAI is ever made.

= What the service is and what it is used for =
OpenAI provides the Chat Completions API. The plugin uses the model `gpt-4o-mini` (configurable via the `accessflow_openai_model` filter) to generate a plain-language summary of the article the visitor is reading, formatted with short sentences and bullet lists to improve readability for users with cognitive overload, ADHD or dyslexia.

= What data is sent and when =
When a visitor clicks the "Summarize this page" button, the plugin extracts up to the first 3000 characters of plain text from the `<main>` (or `<article>`, or `<body>` as fallback) element of the current page and sends it to `https://api.openai.com/v1/chat/completions`, together with the site's OpenAI API key in the `Authorization` header. No personal data, IP address, cookies, user identifiers or browsing history are sent. The text payload is cached server-side (WordPress transient) for one hour, keyed by hash, so identical requests do not re-hit the API.

No data is sent to OpenAI on page load, on visitor identification, in the background or for analytics. The request happens only on explicit user action.

= Terms and Privacy =
This service is provided by OpenAI, L.L.C.

* Terms of Use: https://openai.com/policies/terms-of-use
* Privacy Policy: https://openai.com/policies/privacy-policy

Site administrators are responsible for disclosing this third-party processing to their own visitors in their site's privacy policy where required by applicable law (such as the GDPR).

== Frequently Asked Questions ==

= How is it different from other accessibility plugins? =
Other accessibility plugins are generic WCAG overlays aimed at corporate legal compliance. Access Flow is built for the neurodivergent end user: the vocabulary, the features (Bionic Reading, Reading Ruler, profiles), the proactive behavioral detection and the aesthetic do not start from a WCAG checklist but from how a person with ADHD, dyslexia or autism actually reads.

= How does the plugin detect cognitive overload? =
Two triggers:
1. **Erratic scrolling:** five or more direction changes within a three-second window.
2. **Frustration clicks:** three or more clicks on non-interactive areas within one second.
When triggered, the `accessflow:overloadDetected` event fires and the widget suggests enabling Focus Mode with a visual pulse.

= Is the OpenAI integration safe? =
Yes. The API key is stored as a WordPress option and is never exposed to the frontend. The call is server-side from `wp-json/accessflow/v1/summarize`, with nonce verification, per-IP rate limiting (10 requests per 10 minutes) and a one-hour cache keyed by text hash.

= Does Bionic Reading break icons or code? =
No. The transformation walks text nodes using a `TreeWalker` and skips `SCRIPT/STYLE/CODE/PRE/KBD/SVG/INPUT/BUTTON` and the widget itself. When disabled, wrappers are replaced by the original text nodes and the DOM is normalized.

= Does it work on mobile? =
Yes. The Reading Ruler also listens to `touchmove`. Scroll listeners are passive so the main thread is not blocked on slower devices.

= Does it affect performance? =
Minimally. Vanilla JavaScript, no dependencies, passive listeners, debounced scroll. Assets are enqueued only on the frontend (not in admin or embeds).

= Can I extend the selectors that Focus Mode dims? =
Yes, in three ways: 1) a custom CSS selectors field in the admin; 2) automatic theme profiles (Astra, GeneratePress, OceanWP, Storefront, Divi); 3) the `accessflow_distraction_selectors` filter for developers.

== Screenshots ==

1. Frontend widget panel with the neurodivergent profile selector.
2. Reading Ruler active following the cursor.
3. Bionic Reading applied to the main content.
4. Admin panel with the toolbar identity configuration.
5. AI summary generated inside the widget.

== Changelog ==

= 1.0.0 =
* Initial release by Sangar Studio.
* Neurodivergent Profiles (ADHD, Dyslexia, Autism, Sensory sensitivity).
* Modes: Focus, Dyslexia, Bionic Reading, Reading Ruler, Calm Interface.
* Behavioral Engine with erratic-scroll and frustration-click detection.
* Smart Content Simplifier using OpenAI (gpt-4o-mini) with hourly cache.
* Customizable Toolbar Identity (colors, position).
* Widget accessibility: focus trap, aria-modal, prefers-reduced-motion, forced-colors.
* Full i18n (text domain `sangar-studio-access-flow`).

== Upgrade Notice ==

= 1.0.0 =
First public release.
