=== Elementra Builder ===
Contributors: mohammedayman
Tags: page-builder, arabic, rtl, visual-editor, responsive
Requires at least: 6.5
Tested up to: 7.1
Requires PHP: 8.0
Stable tag: 0.19.1
License: GPLv2 or later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

Independent Arabic/English visual builder. EARLY ACCESS: evaluate on staging before production or sale.

== New in 0.11 (public beta) ==
Per-instance plain-text overrides for published shared sections. Select a section element, choose a published section, then Customize this instance. Check the text fields you want to replace; unchecked fields inherit future source edits. Apply to the draft and publish separately. Reset restores source text. The original shared template and other instances are not modified. Layout/styles remain linked. Maximum 50 source elements / 32 KB of text; each value is bounded and sanitized. URL, HTML, forms, structured items, nested shared references and template assignments cannot be overridden. Removed source IDs are ignored. Changing the referenced template clears old overrides. Exported documents retain them; the referenced published section must still exist on the destination site.

Post/page cards gain include/exclude ID filters (up to 50 per list), author ID, tag ID for posts, and skip offset (0–100). Filters intersect. Exclusions and the current page win; even explicit IDs cannot expose drafts/password-protected content. Query results remain bounded to 12. This is not arbitrary loop templating, AJAX filtering or pagination.

== New in 0.10 (public beta) ==
56 element types. Eight public post/archive/dynamic elements and nine WooCommerce product/archive elements. Administrators can create and explicitly assign single-post, archive, product and shop archive templates; cart/checkout are excluded and existing post-specific builder documents retain precedence. Dynamic fields require an explicit public-key allowlist, accept only scalar Meta/ACF values, and never expose protected meta keys. ACF must be installed separately for ACF values.

Forms accept up to eight additional text/email/tel/textarea/select/checkbox fields and optional required contact consent. Signed configurations are checked against the current published form and validated server-side. Email uses WordPress mail. The elementra_form_submission PHP action is a developer extension point, not an installed CRM/webhook integration. Forms require a singular published page/post/product; archive layouts omit them.

Linked global color tokens and sanitized responsive style classes with per-element overrides. Administrators manage them in Site settings and can capture an element's styles as a reusable linked class; local styles take precedence. Global saves affect linked published elements immediately; refresh caches. JSON editing is for structured data only and never executes code.

This is still a beta: browser/theme/plugin matrix, accessibility review, human beta feedback, demonstration media, complex ACF fields, per-instance component content overrides, CRM/webhook destinations, cart/checkout customization and paid delivery are not complete. See VERIFICATION.md for actual test evidence.

== New in 0.9 ==
Multi-selection of sibling layers for grouping, ungrouping, inherited editor locks, logical per-side spacing, line height and letter spacing. Locks are editor conveniences, not security controls; imports and undo can change them. Grouping requires siblings; ungrouping removes the container's styles. Bulk text replacement skips locked elements.

Three new widgets (39 total): a browser-generated table of contents, explicit social share links, and a flat published WordPress menu. The image strip now adds Previous/Next controls with reduced-motion preference support; native scrolling remains without JavaScript. Manage menu items under WordPress Appearance. Table-of-contents links require JavaScript and reflect visible headings at initial load.

Public beta: https://mohammedayman.is-a.dev/products/elementra-builder
Guide: https://mohammedayman.is-a.dev/guides/elementra-builder-guide

== New in 0.8 ==
Countdown widget with a WordPress-site-timezone deadline, escaped expired text and a once-per-second visitor display. A server-rendered snapshot remains without JavaScript; refresh caches when changing deadlines. Client clock accuracy affects the running timer. Notices optionally allow dismissal in the current page view; the close control is revealed only after JavaScript initializes. Dismissal is not stored.

Verification: 35 JavaScript model/runtime tests; 39 real WordPress checks on PHP 8.0 and 8.5; the same 39 passed following isolated ZIP installation on PHP 8.0. No live customer site changed. See VERIFICATION.md for evidence and limits.

== New in 0.7 ==
Eleven independent content widgets: image box, symbol list, native progress bar, static half-step star rating, informational notice, named social links, native audio player, price list, blockquote, native expandable text and a scrollable image strip. New widgets have bilingual inspector controls and PHP server rendering.

Scope: social links are text links, not a brand icon library. Audio accepts direct HTTP(S) files, not SoundCloud embeds. The image strip uses native scrolling, not autoplay/lightbox/navigation slides. Notices may be dismissible starting in 0.8. Ratings are author-entered display values, not collected reviews or review schema. Progress is a display value, not animated tracking. Expandable text uses details/summary and is not the WordPress excerpt Read More tag. Prices are display only; no checkout or payments.

== New in 0.6 ==
Bilingual quick-find palette (Ctrl/Cmd K), searchable/collapsible layers with editor-only names and parent breadcrumbs, literal text find/replace with preview counts and one-step undo, six active-breakpoint style presets, and clear screen overrides. Palette searches the current draft and can add widgets; it does not publish. Text replacement skips URLs, HTML, list syntax and editor labels. Changes remain local draft edits until explicitly saved/published. Native text replacement is case-sensitive and does not use regex.

== New in 0.5 ==
Complete element copy/paste (including nested content and responsive styles), transactional validated insert/duplicate/drag moves, and expanded editor shortcuts. Clipboard is in-memory, not the operating system clipboard. Paste inserts inside containers, after other elements, or at page root when deselected. Ctrl/Cmd D duplicates, C copies, V pastes, Y or Shift Z redoes; Escape deselects. Ctrl/Cmd S saves while typing. Native text editing remains available in input fields. The clipboard clears on reload.

== New in 0.4 ==
Configurable published post/page cards (1-12 results, category filter for posts, sort and 1-4 columns), safe text tabs with native keyboard/ARIA state, a bounded image gallery and a dynamic featured-image element. Seven contextual text tokens now include {{post_date}}. Each node can be scheduled by inclusive YYYY-MM-DD dates using the WordPress site timezone and limited to pages or posts. These are public presentation rules, not access control. Hidden items are omitted from server HTML; use Layers to edit them. Refresh page caches at schedule boundaries.

Tabs accept one Title|Plain text pair per line (maximum 12), not nested widgets or arbitrary HTML. Gallery accepts up to 12 absolute HTTP(S) URL|Alt text pairs, with no lightbox/carousel. Query supports posts/pages only, published and non-password-protected, excludes the current page and does not support pagination, custom loops, arbitrary SQL or ACF. The featured-image element reads the current WordPress page/post image. Existing posts elements retain a default of three results.

See docs/COMPETITOR-COVERAGE.md for the researched feature inventory, current scope and remaining work. It is not a parity or superiority claim.

== Description ==
Build WordPress pages and posts with an independent visual editor. No Elementor dependency, external editor CDN, telemetry or license service.

Included: 39 element types, nested containers, responsive desktop/tablet/mobile styles, layers, drag into containers, reorder/duplicate/delete, undo/redo, JSON import/export, nine starter layouts, global colors/fonts/content width, media picker, private drafts, explicit publication, 15 saved draft versions and optimistic conflict checks.

New in 0.2: reusable published sections; a site library for headers, footers, sections and popups; opt-in independent page canvas with selected header/footer; native modal popups with manual/delay/scroll triggers; six safe contextual text tokens; navigation and statistic widgets; copy/paste of responsive styles; local unsaved-draft recovery; and heuristic design/accessibility checks.

== Installation / upgrade ==
1. Back up a staging WordPress site.
2. Plugins > Add New > Upload Plugin > select elementra-builder-0.4.0.zip.
3. For an existing 0.1/0.2 installation, use WordPress's replace-current-plugin flow. Do not install a second differently named plugin folder.
4. Activate and open Elementra in the dashboard. No database migration is required; old documents gain safe default experience settings when read.
5. Choose or create a page, insert a starter layout, then edit content and responsive styles.
6. Save draft is private. Publish applies the public layout and publishes the WordPress page.

== New in 0.3: site rules and library controls ==
Administrators can open Site in the editor and select a published, enabled header/footer. Enable rules for all builder content, pages, posts or up to 100 explicit IDs, and exclude up to 100 IDs. Saving these rules applies immediately and replaces the theme wrapper of matching PUBLISHED Elementra pages/posts only. Native pages, archives, feeds, private/draft and password-gated content are not converted. Rules default to disabled on upgrade. Existing per-page independent canvas takes precedence. Inherit site layout rules > disable opts a page out (publish that page setting for public effect). No rule rewrites the stored document.

An explicit independent page still keeps its canvas when a selected template is disabled; that template renders nothing. With global rules, disabling the last valid header/footer falls back to the active theme. Disabled templates stay published in storage but are excluded from public rendering and pickers. Reenable from Library to restore their public uses immediately. Publishing edits does not automatically reenable a disabled template. Rename retains IDs and references. No template is deleted by these controls.

Site rule changes and template management use server conflict tokens and short locks. Another open draft may need reloading after a template is renamed/disabled/enabled. Rule edits use their own Save site rules button and are NOT included in page Save draft, JSON export, undo, or local recovery. Reloading loses unsaved rule form changes. Page editors cannot administer shared templates or site rules. Flush site/CDN caches after public rule/template changes if your hosting caches whole pages.

== Site template library ==
Users with edit_theme_options (normally administrators) may create and edit shared templates. Page editors with edit_pages may choose published templates but cannot read or alter shared drafts.

In Library, create Header, Footer, Section or Popup, edit and publish it. Each has separate draft/live documents. Editing a shared template changes every referencing page only after publication. Save section copies the selected element into a new shared section DRAFT; open it from Library and publish it before using it.

For a page-specific header/footer, open Page settings and enable Independent page canvas, then choose the published header/footer. This replaces the theme's page wrapper for that page only, preserves wp_head/wp_body_open/wp_footer and does not edit theme files. It is NOT a complete theme builder: basic site rules now cover published Elementra pages/posts only, with no archive/search/404 templates or theme navigation-menu sync.

The Shared section widget inserts a published section by ID. Invalid, draft, protected or mismatched references render nothing. Recursive references are capped at four nested templates and twenty embedded renders per request. JSON exports contain site-specific template IDs; recreate/reassign references when moving to another site. They are not a complete site export.

== Popups ==
Choose a published Popup in Page settings. Manual buttons link to #elra-popup. Automatic triggers support a bounded delay (0-120 seconds) or scroll percentage (10-100). Session frequency suppresses repeated AUTOMATIC opens using sessionStorage; manual links may reopen the dialog. Always means one automatic trigger per page load. Native dialog supports Escape, a close button, focus containment and restoration to the opener. Automatic behavior depends on JavaScript and browser dialog support. No marketing platform integrations, exit intent, device targeting or analytics are included.

== Dynamic fields ==
Supported text tokens: {{site_title}}, {{site_description}}, {{page_title}}, {{page_url}}, {{post_excerpt}}, {{current_year}}. Contextual text is escaped, and link/image destinations remain URL-sanitized. Tokens are not executed inside Safe HTML. Arbitrary metadata, user data, ACF, PHP and JavaScript expressions are not evaluated.

== Recovery and checks ==
Unsaved design changes are copied to this browser's localStorage after edits, scoped to this WordPress REST root, logged-in user ID and document ID. The copy is local, not a server backup or autosave. Open the page and select Recover local draft after a reload. If the server token changed, a specific warning requires confirmation. Recovery retains the current server token; review the merged choice before saving. A successful save clears the local copy. Copies expire after 14 days when next read. Delete local recovery copy clears it immediately. Browser storage may be blocked/full/cleared: use Save draft and JSON exports for dependable backups. Avoid leaving sensitive draft content in shared browser profiles.

Checks flag missing/multiple main headings, skipped heading levels, image alternative-text review, empty button destinations/names, possible low contrast and large document size. Contrast estimates use explicit desktop document colors, not the computed final theme, image backgrounds or all breakpoints. These are advisory checks, not an accessibility/SEO certificate. Decorative images may intentionally have empty alt text.

== Existing behavior and limits ==
The normal mode retains the theme header/footer/outer content-width constraints. Independent canvas is opt-in. Original post_content remains untouched. Deactivating Elementra returns original content and the normal theme wrapper; layouts are NOT converted into native WordPress blocks. Plugin data is retained on deactivation/removal for manual recovery, not silently deleted.

Limits: 250 nodes, nesting depth 8, 500 KB per document, 100 recent editable page/post/template items in the page selector, 100 library entries, 60 current-session undo checkpoints, 15 server draft snapshots. No automatic Elementor migration or server autosave. Password-protected pages keep WordPress's password gate and do not load independent canvas or popup content before access.

== Forms / external services ==
The basic contact form uses admin-post.php and wp_mail to the fixed WordPress administration address, including when embedded via published templates on a published page. It uses a nonce, honeypot and per-IP/page throttle (one attempt/minute). No submission inbox/database exists. Configure and verify actual SMTP inbox delivery, privacy text and production spam protection. wp_mail accepting a message is not proof of delivery. Public cached form nonces can expire; exclude form pages from long-lived caching or refresh regularly.

Latest posts excludes password-protected posts. WooCommerce displays three product cards if installed; it is not a product/cart/checkout template builder. YouTube embeds use youtube-nocookie.com. Chosen external image URLs are requested by visitors' browsers. No AI provider is configured and no AI requests or charges occur.

== Early-access limits / not implemented ==
No claim of Elementor parity or superiority. No archive/search/404 theme condition engine, archive/search builder, ACF/custom dynamic fields, full WooCommerce builder, advanced form integrations/inbox, AI assistant, cloud accounts, billing, license/update server, role-management UI, advanced animations or broad public extension API. No site-wide rewriting of native/non-builder content or existing-builder conversion.

Elementra is a provisional name, not cleared for trademark or domain availability. Independent project, no affiliation with Elementor. Commercial launch requires broader compatibility, accessibility, security, performance, upgrade and support validation. See VERIFICATION.md and the Arabic guide.

== Changelog ==
= 0.4.0 =
* Added bounded post/page query controls, gallery, accessible text tabs and featured image.
* Added node display schedules/type conditions and a publication-date token.
* Added a sourced competitor coverage inventory with explicit implementation gaps.
= 0.3.0 =
* Added basic site layout scope/inclusion/exclusion rules for published builder content.
* Added per-page rule opt-out and explicit-page precedence.
* Added shared-template rename, disable and reenable with conflict checks.
* Extended verification for permissions, fallback and site rules.
= 0.2.0 =
* Added shared template library and opt-in canvas header/footer.
* Added safe contextual fields, native popups, navigation/statistic/shared-section widgets.
* Added local recovery, design checks and responsive style clipboard.
* Extended permissions, password protection and recursion bounds to the new features.
* Expanded real WordPress and browser verification; formatted source for maintenance.
= 0.1.0 =
* Initial independent early-access implementation.

= 0.19.1 =
Protect unsaved work from delayed or overlapping JSON imports.

= 0.19.0 =
System status with runtime versions, browser capabilities and transparent release checks.

= 0.18.2 =
Fix blank canvas drop targeting and prevent failed drops polluting undo history.

= 0.18.1 =
Fix show visibility overrides losing grid/flex container layout.

= 0.18.0 =
Bulk responsive element visibility from Layers with atomic validation and undo.

= 0.17.0 =
Compare saved versions and safely restore into the draft with undo support.

= 0.16.0 =
Publication review with design checks, issue navigation and explicit public-site acknowledgement.

= 0.15.2 =
Harden local draft recovery validation and storage warning recovery.

= 0.15.1 =
Active-screen style replacement and merge; stricter malformed-document rejection. 63 automated Node tests passed. Staging validation required.
