=== MJC Designs AI Design Assistant for Bricks Builder ===
Contributors: mjcdesigns
Tags: bricks, ai, design, assistant
Requires at least: 7.0
Tested up to: 7.1
Requires PHP: 7.4
Stable tag: 1.1.8
License: GPL-2.0-or-later
License URI: https://www.gnu.org/licenses/gpl-2.0.html

An AI design assistant that proposes and applies changes to Bricks Builder documents using the WordPress AI Client.

== Description ==

MJC Designs AI uses the WordPress AI Client and configured provider models to propose Bricks page changes for your review before applying them. Its optional Style Manager guides designs in the Main Workspace and Content to Pages Workspace with browser-session colors and variables. Its HTML and CSS workspace creates drafts for manual pasting into Bricks. Its Content to Pages Workspace extracts final copy from DOCX or text-based PDF files, creates WordPress draft pages, prepares separate Bricks designs for review, and can edit existing Bricks templates. The plugin is independent of Bricks Builder and is not affiliated with or endorsed by its developers. This alpha release is for evaluation: review each proposal and keep a backup before applying changes.

Visit the [MJC Designs AI YouTube channel](https://www.youtube.com/@MJCDesignsAIDesignAssistant). The About subpage also links to video tutorials and updates. YouTube content is not loaded in the plugin page.

== Requirements ==

* WordPress 7.0 or later with the WordPress AI Client.
* A compatible AI provider integration installed and configured under Settings > Connectors.
* Bricks 2.4 or later, with `get-page-elements`, `set-page-elements`, and `get-element-schema` abilities enabled under Bricks > AI > Abilities.
* PHP 7.4 or later.
* PHP Zip and XML extensions for DOCX extraction, and zlib for compressed PDF text in Content to Pages.

== Installation ==

1. In WordPress, go to Plugins > Add New Plugin > Upload Plugin.
2. Upload and activate the MJC Designs AI Design Assistant for Bricks Builder ZIP file.
3. Install and configure a compatible AI provider under WordPress Settings > Connectors. Provider setup and credentials are managed by the site administrator.
4. In Bricks > AI > Abilities, enable `get-page-elements`, `set-page-elements`, and `get-element-schema`.
5. Open MJC Designs AI, choose a configured provider model, select a page or Bricks template, enter a design request, review the preview and proposed edits, then apply them when ready.

When upgrading, the plugin removes credentials left by earlier releases. If you previously added `MJC_DESIGNS_AI_DESIGN_ASSISTANT_BRICKS_API_KEY` to `wp-config.php`, remove that unused constant manually.

== Features ==

* List editable WordPress pages and Bricks templates, including pages without existing Bricks elements. Blog posts are not available for editing.
* Select among compatible AI provider models configured through WordPress Connectors; the user's model preference is saved to their account.
* Use compatible vision models with optional JPG, PNG, or WebP reference images up to 5 MB.
* Choose up to five existing WordPress Media Library images for placement in proposed Bricks designs, or reserve image placeholder blocks when none are selected. Selected image titles, alternative text, dimensions, and IDs are sent to the chosen AI provider; image files are not sent by this feature.
* Read the selected page's element tree and propose focused edits. Validate setting names and choices against the live Bricks control schema before preview or apply.
* Change only registered native Bricks controls. AI proposals cannot write code controls or Custom CSS.
* Keep the Main Workspace conversation for each selected Bricks document in the current browser tab until it closes. Use the same Generate Design and Refine Design action styling across the three workspaces. Each workspace header has a Quick Guide button; the guide also appears automatically when no compatible provider is connected.
* Name one other editable page in a Main Workspace or Content to Pages prompt, such as “match this page to the About page”, to use a compact summary of its native Bricks layout and style settings as a reference. Only the selected page can receive proposed changes; its copy stays its own.
* When an unattended workspace finishes or fails a design request, mark its browser tab title with an unread count. Enable optional desktop alerts from the workspace header; they require browser permission and a secure connection. The tab must stay open until the request ends.
* Generate and refine static HTML and CSS drafts in up to five browser-session chats. Use code tabs, line wrapping, responsive previews, fullscreen controls, an adjustable conversation area, and a vertically resizable design request field. Copy drafts into Bricks manually; this workspace does not save a page or execute generated scripts.
* Use optional Style Manager in the Main Workspace and Content to Pages Workspace to guide AI proposals with shared browser-session colors and variables. Import or export Bricks palette and variable JSON, edit base colors with WordPress's color picker, adjust individual light, dark, and transparent shade steps, and edit fluid typography and spacing scales. Variable exports keep scale steps in their manual value order for Bricks import. Set the assumed HTML root font size and minimum/maximum screen widths for clamp calculations; these settings do not change the site's HTML font size. Save keeps the editor open and becomes available again when settings change. The picker shows HSLA values by default; color fields also accept hex, RGB/RGBA, and HSL. The HTML and CSS workspace does not use Style Manager. When enabled, the plugin checks every saved color and variable name against the site's Bricks global palettes and variables before requesting AI generation. If any are missing, generation pauses with an import reminder and examples of missing names; no provider request is sent. Matching imported names are linked as `var(--name)` in compatible font-size, padding, margin, gap, suitable positional offset, and color controls when they fit the request. A valid fixed spacing value remains available when a variable would harm the layout, including at smaller screen widths. Explicitly requested fixed values and exact colors take priority; a valid fixed value may be used when no Style Manager variable fits the requested control. On new Content to Pages designs, exact palette colors named primary and secondary lead the brand palette; when a multi-element proposal barely uses them, the assistant makes one focused correction attempt. Explicit color directions take priority. The plugin does not write Style Manager data to Bricks global settings. Import exported palette and variable JSON into Bricks Builder to make named references available there, and review fluid sizes in Bricks because its clamp calculations can differ slightly.
* Use the Content to Pages workspace to preview a DOCX or text-based PDF copy file up to 50 MB, set brand colors with WordPress's color picker when Style Manager is off, create draft pages, and generate a separate reviewed Bricks design for each page. The picker shows HSLA by default and also accepts opaque hex, RGB/RGBA, and HSL colors; planner colors are saved as six-digit hex values for the design request. When Style Manager is on, its palette supplies the available website colors and the planner color fields are hidden. When named primary and secondary colors exist, the AI uses them as the leading and supporting brand colors by default. With other names, it chooses suitable palette colors based on the design. Prompt and saved special instructions can assign different roles in either case. Generate Drafts detects existing page titles and skips them after confirmation. Page headings must use `Page: Title` or Word Heading 1. DOCX extraction retains common bold, italic, and safe external links for Bricks text proposals; the extracted-copy preview is plain text. PDF extraction groups readable text into paragraphs when possible but does not preserve styling or links; text-based PDFs with unsupported encodings and image-only scans may not extract correctly. Choose up to five existing Media Library images for a design, or reserve labeled placeholders for missing visuals. The server's PHP upload limit may be lower than 50 MB.
* When returning to Content to Pages in the same browser tab, choose whether to continue saved planner settings, chat, and shared Style Manager settings or start a new session. Starting new clears those browser-session settings, including Style Manager, but leaves WordPress pages unchanged. Re-upload the copy file to continue, because the plugin does not save the file or extracted text. Generate Drafts appears after planner settings are saved and stays unavailable until copy is extracted.
* Refine a selected section or the overall Content to Pages layout through a reviewed Bricks proposal. The AI can regroup native elements while preserving the planner rules and final page copy.
* Select an editable page or existing Bricks template in Content to Pages. Page drafts remain drafts after design changes, and publishing a page requires a separate confirmation and permission. Templates use the user's prompt and saved planner settings when available; naming an existing page in the prompt can supply its Bricks layout and matching uploaded copy as reference without editing that page. This workspace does not create templates, set template conditions, or add SEO details such as meta titles and descriptions to pages or templates. Do those tasks separately in Bricks, WordPress, or an SEO tool. Saved colors and instructions stay in the current browser tab until it closes. The plugin does not save uploaded copy files or extracted text as a WordPress project or in browser session storage; re-upload the copy after leaving or reloading the workspace.
* Add registered Bricks elements, including supported nested elements; move and remove elements while preserving IDs and child data.
* Review temporary frontend previews at the site's Bricks breakpoints, expand the preview, or open it in a new tab before applying.
* Expand Change Review in the Main Workspace and Content to Pages Workspace when a proposal contains edits, to inspect them in a larger dialog before applying.
* Open the selected page in Bricks Builder and undo the most recent assistant change.
* Provide About, Settings, Capabilities, FAQ, Version History, terms, and privacy guidance in WordPress admin.

Provider access, costs, quotas, and data handling vary; administrators should review current terms. Bricks validates final data and permissions. Some responsive-only changes may not create a native Bricks revision; use the assistant's Undo action to reverse them.

== Source Code ==

The plugin ships human-readable JavaScript and CSS source loaded directly without a build step: `assets/app.js`, `assets/admin.css`, `assets/admin-notices.js`, `assets/tab-notifications.js`, `assets/style-manager.js`, and `assets/style-manager.css` for the native Bricks workspaces; `assets/structure-workspace.js` and `assets/structure-workspace.css` for the HTML and CSS workspace; and `assets/content-workspace.css` for Content to Pages. Interface images and code are packaged locally, not loaded from a remote asset host. Browser alerts use built-in browser APIs without an external notification service or library.

== Frequently Asked Questions ==

= Does the assistant edit blog posts? =

No. It edits eligible pages and Bricks templates. It can configure supported Query Loops that display posts, but it does not edit posts.

= How do I connect an AI provider? =

An administrator configures a compatible provider under Settings > Connectors. Users choose from its compatible models. This plugin does not store provider credentials.

= Does using a provider cost money? =

Costs, free tiers, and quotas depend on the provider and model. Check the provider's current terms before use.

= What information is sent to the provider? =

The Main Workspace sends the prompt, selected Bricks document content, optional reference image, and metadata for selected Media Library images. When Style Manager is enabled, its colors, variables, scale settings, variable roles, and matching names found in Bricks global settings are also sent with Main Workspace and Content to Pages Workspace design requests. The HTML and CSS workspace sends the prompt and optional image; refinements also send the current draft. Selected Media Library image files are not sent. See Privacy below for storage and retention details.

= Can I use images from the Media Library? =

Yes. Choose up to five existing images and describe where to place them. The assistant uses suitable selected images first and can make labeled native Bricks placeholders for image slots without an available image. The provider receives selected image titles, alternative text, dimensions, and IDs, but not the image files. Review the proposed placement before applying.

= Are previews permanent? =

No. Main Workspace and Content to Pages previews are private temporary drafts removed when you leave, replace them, or after one hour. HTML and CSS drafts appear in an isolated browser frame without creating preview posts. Ordinary Content to Pages draft pages persist until you publish or delete them.

= What can the assistant change? =

The Main Workspace and Content to Pages Workspace propose changes to registered native Bricks elements and controls. Both can place suitable site images explicitly selected from the Media Library; when no image is available for a needed slot, they can build labeled placeholders with native Bricks elements. Neither workspace can write Custom CSS or code controls, or manage global styles or the Media Library. The HTML and CSS workspace creates a draft for manual copying only.

To reference another page's style, select the page to change and name one other editable page in your prompt, such as “Match this page's visual style to the About page.” The assistant reads a bounded summary of that page's native Bricks layout and visual settings. It does not copy the source page's text or images, change the source page, or inspect its full rendered appearance or global styles. Review the proposal before applying it.

= How do I use the HTML and CSS workspace? =

Choose a model and class prefix, describe a layout, and optionally attach a reference image. Review the preview, refine it in the same chat, then copy the HTML and CSS into Bricks. Up to five chats remain in this browser tab. The chosen document is not sent or modified; add real images and review converted classes and styles in Bricks before saving.

= How does Style Manager work? =

Enable Style Manager in the Main Workspace or Content to Pages Workspace to share palette colors and variables for this browser tab. Import existing Bricks JSON or create styles in the editor, then export and import the JSON into Bricks. The assistant checks that the names exist in Bricks before requesting a design; it does not install global styles itself. Suitable names are used in registered controls, while explicit fixed values and color directions in your prompt or saved special instructions take priority. The HTML and CSS workspace does not use Style Manager. Turning Style Manager off clears its shared settings and restores the Website Planner brand-color controls.

= How do I use Content to Pages Workspace? =

Prepare final copy with a clear heading for each page, such as `Page: Home`, followed by that page's copy. Include the brand name in the copy when it should appear in the design. Mark content headings `H1:` through `H6:` to preserve their intended hierarchy. Optional labels such as `Slogan:`, `Hero banner text:`, and `CTA Graphical Block:` distinguish visible words from layout direction. Use DOCX when inline bold, italic, or hyperlinks matter; PDF extraction groups readable text into paragraphs but does not preserve those styles or links. In Website Planner, upload a DOCX or text-based PDF, review the extracted copy, set brand colors and instructions, then create drafts. If a page title already exists, confirm that it should be skipped; only missing pages become new drafts. Reset planner clears the current inputs and uploaded copy without deleting WordPress pages. Select a page, optionally choose existing Media Library images, generate its design, review and apply the proposal, and publish only when ready. You can also select an existing Bricks template, describe its design in a prompt, and name an existing page to use its design and matching uploaded copy as reference. Only the selected template receives proposed changes. The workspace does not create templates, set template conditions, or add SEO fields such as meta titles and descriptions. Set those separately in Bricks, WordPress, or an SEO tool. Pages, templates, and applied designs persist in WordPress. Saved colors and special instructions remain in the current browser tab until it closes. The plugin does not save the uploaded copy file or extracted text to WordPress or browser session storage; re-upload and extract the file after a reload. A page without matching copy cannot be generated from that file.

When Style Manager is enabled, Website Planner hides its brand-color controls and uses the saved palette instead. Turn Style Manager off to choose brand colors in Website Planner again. If saved planner settings, chat, or shared Style Manager settings are found when you return to this workspace, a dialog lets you continue or start new. Continuing keeps those settings, then you upload the copy again. Starting new clears the shared Style Manager settings as well as the planner and chat; it does not delete WordPress draft pages.

= Will a PDF preserve bold, italics, and hyperlinks? =

No. The PDF extractor reads supported text and groups paragraphs when possible, but it does not retain text formatting or links for design generation. Use a DOCX when those details matter. The extracted-copy preview is plain text for both file types.

= Does MJC Designs AI include the full Bricks Skills package? =

No. It uses the WordPress Abilities API for page operations and does not load the external Bricks Skills package or WordPress MCP Adapter.

== Privacy ==

The Main Workspace sends the prompt, selected Bricks document content, optional reference image, and selected Media Library image metadata (IDs, titles, alternative text, and dimensions) through the WordPress AI Client to the chosen provider. Content to Pages can send the same metadata for images you select, along with the selected page's extracted copy, brand colors, special instructions, prompt, and current Bricks document elements. When Style Manager is enabled, its colors, variables, scale settings, variable roles, and matching names found in Bricks global settings are sent with Main Workspace and Content to Pages Workspace design requests. When you name another editable page as a design reference, a bounded summary of its native Bricks layout and visual settings is also sent. When you name an existing page as a template reference, its Bricks elements and matching uploaded copy may also be sent to the selected provider. Selected Media Library image files are not sent. The HTML and CSS workspace sends the prompt and optional reference image; refinements also send the current HTML and CSS. Provider terms govern data handling and costs; review them before submitting sensitive information.

The plugin does not save chats to WordPress, store reference image files in browser session storage, upload them to the Media Library, or send telemetry to its author. Main Workspace chats are stored per selected Bricks document; HTML and CSS chats and Content to Pages chat messages also remain in the current tab's session storage until the tab is closed. Content to Pages keeps saved brand colors and special instructions in this tab's session storage. Enabled Style Manager colors, variables, and scale settings are shared by the Main Workspace and Content to Pages Workspace in the same tab and are cleared when disabled or when a new Content to Pages session starts. They are not written to Bricks global settings. The plugin reads an uploaded copy file from PHP's temporary upload; it does not save that file or extracted text to WordPress, the Media Library, or browser session storage. Draft pages made from the copy and applied designs do remain in WordPress. Private temporary previews are removed when replaced, when leaving the workspace, or after one hour. Site backups and logs follow the site's policies. Administrators configure providers under Settings > Connectors and should review the suggested privacy text in Settings > Privacy.

An unread count in the workspace tab title appears only when a design request ends while the tab is unattended. Optional desktop alerts require a click on the Alerts button and browser permission. The on/off choice is kept only in that tab's session storage. Alert text is generic and includes no prompt, copy, page title, or image. The plugin sends no notification data to an outside service.

== Screenshots ==

1. Review a Bricks page’s structure, frontend preview, and assistant conversation in the Main Workspace.
2. Inspect a page’s element structure and proposed changes alongside its frontend preview.
3. Open the Quick Guide for an overview of the assistant’s review-first workflow.
4. Choose existing Media Library images to guide a page design.
5. Generate an HTML and CSS draft, chat about refinements, and review the live preview.
6. Inspect the generated HTML and CSS in an expanded code view with optional line wrapping.
7. Preview a generated responsive design in the HTML and CSS workspace.
8. Check the generated design in a narrow mobile preview.
9. Select a page and review its Content to Pages design workspace.
10. Set planner colors and instructions, then review extracted website copy.
11. Review existing WordPress pages that will be skipped when creating drafts.
12. Review a generated Bricks page design before applying the proposed changes.
13. Confirm that a page was published from the Content to Pages workspace.
14. Create a Style Manager palette color with a dark counterpart and editable light and dark shades.
15. Fine-tune an individual shade with the color picker or restore its generated value.
16. Organize Style Manager variables by category, edit values, and import or export JSON.
17. Set fluid typography minimum and maximum sizes and compare their live previews.
18. Inspect a saved Bricks page, its element tree, and frontend preview in the Main Workspace.
19. Review proposed settings that use Style Manager color, spacing, and typography variables.
20. Compare a design proposal using Style Manager variables with the current Bricks page before applying changes.
21. Use the shared Style Manager palette in Website Planner instead of choosing brand colors again.

== Changelog ==

= 1.1.8 =
* Video guides · Alpha · 2026-10-24 03:00:49 PHT
  Add a direct YouTube tutorial and update link to the About subpage without embedding video or loading third-party assets.
* Style Manager · Alpha · 2026-10-24 03:00:49 PHT
  1. Add optional session colors and variables for the Main Workspace and Content to Pages Workspace, with Bricks-compatible JSON import and export.
  2. Add overlay palette color pickers, editable shade steps, dark counterparts, fluid typography and spacing controls, and custom variable categories. Set root font size and viewport widths for clamp calculations. Show HSLA picker values by default while supporting other common color formats.
  3. Use Style Manager colors in Website Planner while enabled, and include shared settings in the continue-or-start-new session choice.
  4. Keep the workspace header controls compact with icon-only Quick Guide and fullscreen buttons.
  5. Center spacing and typography scale rows, separate variable navigation, and keep Style Manager open after saving with clear Bricks import guidance.
  6. Export typography and spacing variables in the same order as their manual scale steps so Bricks preserves the intended small and large sizes when regenerating them.
  7. Use confirmed Bricks variable names in compatible controls, prioritize exact primary and secondary palette colors in new Content designs, and make one correction attempt when they are underused.
  8. Name the Main Workspace consistently and clarify Style Manager import and export and responsive design guidance across the plugin pages.
  9. Disable Style Manager Reset while the editor is off, and show dismissible Website Planner errors inside its modal.

= 1.1.7 =
* Content to Pages Workspace · Alpha · 2026-10-21 06:30:07 PHT
  1. Extract final copy, create draft pages, and prepare Bricks designs for review before saving or publishing.
  2. Improve planner controls, focus page requests, preserve DOCX formatting, and detect existing pages.
  3. Keep saved planner details in the browser tab until it closes; the plugin does not save uploaded copy files.
  4. Allow selected Media Library images in Content to Pages designs while retaining placeholders for missing visuals.
  5. Let refinements reshape a section or page while preserving planner guidance and final copy.
  6. Edit existing Bricks templates with optional planner guidance and a named page as design context; configure conditions and SEO details separately.
  7. Group readable PDF text into paragraphs without retaining formatting or links.
  8. Offer a continue-or-start-new choice for saved browser sessions; show Generate Drafts after planner settings are saved.
* Workspace improvements · Alpha · 2026-10-21 06:30:07 PHT
  1. Match HTML and CSS workspace tooltips, image-drop guidance, and Bricks document labels across workspaces.
  2. Align Generate and Refine buttons and keep Main Workspace conversations for the browser session.
  3. Reserve labeled image placeholders with native Bricks elements when no site image is selected in the Main Workspace.
  4. Expand Change Review only when edits are proposed; show the HTML and CSS setup guide when no provider is connected.
  5. Open Quick Guide from every workspace header, and resize the HTML and CSS design request field vertically.
  6. Reduce Bricks schema data sent to AI, especially for new Content to Pages designs, while retaining full proposal validation.
  7. Allow more time for Bricks design proposals to return before the provider request times out.
  8. Use native Bricks color values, check complete copy and formatted DOCX labels, and report proposals with no edits accurately.
  9. Show completed requests in the tab title and offer optional browser alerts when a workspace is unattended.
  10. Let an editable page’s native Bricks layout and visual settings guide another page without changing the reference page.

Earlier release notes are included in `changelog.txt` and the dashboard's Version History.
