@webikon/webentor-core 0.9.14 → 0.10.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # Webentor Core Changelog
 
+## 0.10.0
+
+- Refactor responsive settings and improve UX
+  - **BREAKING**: Run keys migrator from `Settings -> Webentor Migrator`
+  - **BREAKING**: Attributes keys changed, so supports in `block.json` and other usage in theme needs to be checked and renamed:
+    - `flexboxItem` -> `flexItem`
+    - `display` -> `layout` (for `display`) and `sizing` (for `width`, `height`, `minWidth`, `minHeight`, `maxWidth`, `maxHeight`)
+  - Added reset buttons for breakpoints
+  - Better values grouping
+  - Better cascade breakpoints conditioning
+  - Spacing linking
+- Add `webentor/block_wrapper_class_properties` filter to exclude generated class groups such as `backgroundColor` and `textColor` from filtered `classes_by_property` and wrapper output, while keeping the raw generated map available for `block_custom_classes`
+- Add Wrap with Flexible container
+- Add applied classes viewer to see which responsive classes are applied
+- Add Quick layout presets, customizable with filter `webentor.core.responsiveSettings.layoutPresets`
+- Fix PHP path in `init.php`
+- Add package module exports, you can now use `@webikon/webentor-core` instead of `@webentorCore` when importing in the theme
+- Add `webentor.core.l-section.output` filter to customize the section editor preview markup
+
+
 ## 0.9.14
 
 - Fix Button link display

package/README.md

@@ -21,6 +21,47 @@ pnpm install
 pnpm build
 ```
 
+## JS Package Exports
+
+This package exports raw TypeScript source so the consumer's Vite pipeline
+compiles it together with the rest of the project. Consumer projects using
+Vite 7+ must enable the TypeScript-aware config loader:
+
+```jsonc
+// package.json scripts
+"dev": "vite --configLoader runner",
+"build": "vite build --configLoader runner"
+```
+
+Available subpath imports:
+
+```ts
+import { debounce } from '@webikon/webentor-core';
+import { Alpine } from '@webikon/webentor-core/_alpine';
+import { SliderComponent } from '@webikon/webentor-core/_slider';
+import { WebentorButton } from '@webikon/webentor-core/blocks-components';
+import { initResponsiveSettings } from '@webikon/webentor-core/blocks-filters';
+import { buildSafelist, webentorDefaultConfig } from '@webikon/webentor-core/config';
+import type { WebentorConfig } from '@webikon/webentor-core/types';
+```
+
+## WP-CLI
+
+Use the responsive attributes migration command on an existing project when you
+want to scan or migrate block content without opening the WordPress admin.
+
+```bash
+wp webentor migrate-responsive-attributes
+wp webentor migrate-responsive-attributes --migrate
+wp webentor migrate-responsive-attributes --cleanup
+wp webentor migrate-responsive-attributes --site-id=7 --cleanup
+```
+
+By default the command only scans and reports how many posts and blocks still
+need migration or cleanup. `--migrate` writes v2 attributes while keeping legacy
+keys, and `--cleanup` removes the legacy keys after backfilling the v2 shape.
+On multisite, `--site-id=<id>` runs the command against a specific site.
+
 ## Linting
 
 Core consumes shared presets from `@webikon/webentor-configs` to keep lint behavior aligned across repositories.

package/core-js/_alpine.ts

@@ -1,6 +1,12 @@
 import collapse from '@alpinejs/collapse';
 import Alpine from 'alpinejs';
 
+declare global {
+  interface Window {
+    Alpine?: typeof Alpine;
+  }
+}
+
 // Initialize Alpine if it's not already initialized
 const AlpineInstance = window.Alpine || Alpine;
 if (!window.Alpine) {

package/core-js/_slider.ts

@@ -3,18 +3,21 @@ import Swiper from 'swiper/bundle';
 
 import { debounce, throttle } from './_utils';
 
-type BreakpointConfig = Swiper & {
+type SliderParams = Record<string, any> & {
+  autoplayControl: boolean;
+  breakpoints: Record<string, BreakpointConfig>;
+  on?: Record<string, (...args: any[]) => void>;
+};
+
+type BreakpointConfig = Record<string, any> & {
   enabled: boolean;
 };
 
 class SliderComponent {
   private element: HTMLElement;
-  private params: Swiper & {
-    breakpoints: Record<string, BreakpointConfig>;
-    autoplayControl: boolean;
-  };
+  private params: SliderParams;
   private swiper: Swiper | null;
-  private container: HTMLElement;
+  private container: HTMLElement | null;
   private breakpoints: Record<string, BreakpointConfig> | null;
   private autoplayButton: HTMLElement | null;
   private timerSeconds: HTMLElement | null;
@@ -108,10 +111,14 @@ class SliderComponent {
           }
         },
         autoplayTimeLeft: (swiper, time, progress) => {
-          if (this.autoplayControlEnabled) {
+          if (
+            this.autoplayControlEnabled &&
+            this.timerCircle &&
+            this.timerSeconds
+          ) {
             this.timerCircle.style.setProperty(
               '--slider-timer-progress',
-              1 - progress,
+              String(1 - progress),
             );
             this.timerSeconds.textContent = `${Math.ceil(time / 1000)}s`;
           }
@@ -125,8 +132,12 @@ class SliderComponent {
         ...this.params.on,
       },
       navigation: {
-        nextEl: this.element.querySelector('.js-slider-button-next'),
-        prevEl: this.element.querySelector('.js-slider-button-prev'),
+        nextEl: this.element.querySelector(
+          '.js-slider-button-next',
+        ) as HTMLElement | null,
+        prevEl: this.element.querySelector(
+          '.js-slider-button-prev',
+        ) as HTMLElement | null,
       },
     });
 
@@ -174,7 +185,7 @@ class SliderComponent {
 
     if (!wrapper) return;
 
-    const slides = Array.from(wrapper.children);
+    const slides = Array.from(wrapper.children) as HTMLElement[];
 
     if (slides.length === 0) return;
 

package/core-js/blocks-components/button.tsx

@@ -87,7 +87,20 @@ import { __ } from '@wordpress/i18n';
   }
  */
 
-export const WebentorButton = (props) => {
+type WebentorButtonProps = {
+  attributeName: string;
+  attributes: Record<string, any>;
+  buttonClassName?: string;
+  className?: string;
+  hideLink?: boolean;
+  hideSize?: boolean;
+  hideVariant?: boolean;
+  innerClassName?: string;
+  placement?: string;
+  setAttributes: (attributes: Record<string, any>) => void;
+};
+
+export const WebentorButton = (props: WebentorButtonProps) => {
   const {
     placement,
     className,
@@ -199,7 +212,7 @@ export const WebentorButton = (props) => {
     </button>,
     props,
     buttonClassName,
-  );
+  ) as React.ReactNode;
 
   return (
     <span className={`${className ?? ''} wbtr:relative wbtr:inline-block`}>
@@ -300,6 +313,7 @@ export const WebentorButton = (props) => {
             <SelectControl
               label={__('Button HTML Element', 'webentor')}
               value={attributes[attributeName]?.htmlElement}
+              __nextHasNoMarginBottom
               options={[
                 { label: __('Link (<a>)', 'webentor'), value: 'a' },
                 { label: __('Button (<button>)', 'webentor'), value: 'button' },
@@ -378,6 +392,7 @@ export const WebentorButton = (props) => {
                     <SelectControl
                       label="Icon Position"
                       value={attributes[attributeName]?.iconPosition}
+                      __nextHasNoMarginBottom
                       options={iconPositions}
                       onChange={(value) =>
                         updateObjectAttribute(

package/core-js/blocks-components/custom-image-sizes-panel.tsx

@@ -43,7 +43,9 @@ export const CustomImageSizesPanel: React.FC<Props> = (props: Props) => {
     noticeAfter,
   } = props;
 
-  const breakpoints = applyFilters('webentor.core.twBreakpoints', ['basic']);
+  const breakpoints = applyFilters('webentor.core.twBreakpoints', [
+    'basic',
+  ]) as string[];
 
   const hasSizeSettingsForBreakpoint = (attributes, breakpoint) => {
     return (

package/core-js/blocks-components/typography-picker-select.tsx

@@ -1,7 +1,22 @@
 import { CustomSelectControl } from '@wordpress/components';
 import { __, sprintf } from '@wordpress/i18n';
 
-export const WebentorTypographyPickerSelect = (props) => {
+type TypographyOption = {
+  key: string;
+  name: string;
+  value: string;
+};
+
+type WebentorTypographyPickerSelectProps = {
+  __next40pxDefaultSize?: boolean;
+  onChange: (value: string) => void;
+  options: TypographyOption[];
+  value?: string;
+};
+
+export const WebentorTypographyPickerSelect = (
+  props: WebentorTypographyPickerSelectProps,
+) => {
   const { __next40pxDefaultSize, value, onChange, options } = props;
 
   const selectedOption = value

package/core-js/blocks-filters/_filter-core-typography.tsx

@@ -13,6 +13,13 @@ const BLOCKS = [
   'core/post-title',
 ];
 
+type TypographyOption = {
+  __experimentalHint?: string;
+  key: string;
+  name: string;
+  value: string;
+};
+
 /**
  * BlockEdit
  *
@@ -27,7 +34,10 @@ const BLOCKS = [
 function BlockEdit(props) {
   const { customTypography } = props.attributes;
 
-  const options = applyFilters('webentor.core.customTypographyKeys', []);
+  const options = applyFilters(
+    'webentor.core.customTypographyKeys',
+    [],
+  ) as TypographyOption[];
 
   return (
     <InspectorControls group="styles">

package/core-js/blocks-filters/_slider-settings.tsx

@@ -23,7 +23,7 @@ const initSliderSettings = () => {
 
       const breakpoints = applyFilters('webentor.core.twBreakpoints', [
         'basic',
-      ]);
+      ]) as string[];
 
       const { attributes, setAttributes } = props;
 

package/core-js/blocks-filters/_wrap-with-container.tsx

@@ -0,0 +1,104 @@
+import {
+  BlockControls,
+  store as blockEditorStore,
+} from '@wordpress/block-editor';
+import { cloneBlock, createBlock } from '@wordpress/blocks';
+import { ToolbarButton, ToolbarGroup } from '@wordpress/components';
+import { createHigherOrderComponent } from '@wordpress/compose';
+import { select as dataSelect, useDispatch, useSelect } from '@wordpress/data';
+import { Fragment } from '@wordpress/element';
+import { addFilter, applyFilters } from '@wordpress/hooks';
+import { __ } from '@wordpress/i18n';
+import { group as groupIcon } from '@wordpress/icons';
+
+const withWrapContainerButton = createHigherOrderComponent((BlockEdit) => {
+  return (props) => {
+    const { clientId, name } = props;
+
+    // Allow themes to exclude specific blocks via filter
+    const excludedBlocks: string[] = applyFilters(
+      'webentor.core.wrapWithContainer.excludedBlocks',
+      ['webentor/l-section'],
+    );
+
+    if (excludedBlocks.includes(name)) {
+      return <BlockEdit {...props} />;
+    }
+
+    const { replaceBlocks } = useDispatch(blockEditorStore);
+
+    const { isMultiSelected, isFirstInMultiSelection } = useSelect(
+      (select) => {
+        const store = select(blockEditorStore);
+        const multiIds = store.getMultiSelectedBlockClientIds();
+        const isMulti = multiIds.length > 0;
+
+        return {
+          isMultiSelected: isMulti,
+          isFirstInMultiSelection: isMulti && multiIds[0] === clientId,
+        };
+      },
+      [clientId],
+    );
+
+    // During multi-selection, only render the button on the first selected block
+    if (isMultiSelected && !isFirstInMultiSelection) {
+      return <BlockEdit {...props} />;
+    }
+
+    const handleWrap = () => {
+      const store = dataSelect(blockEditorStore);
+      const allSelectedClientIds = store.getMultiSelectedBlockClientIds();
+
+      // Build the selected block list on demand so useSelect only returns stable values.
+      const allSelectedBlocks = allSelectedClientIds
+        .map((selectedClientId) => store.getBlock(selectedClientId))
+        .filter(Boolean);
+
+      if (allSelectedBlocks.length > 0) {
+        const clonedBlocks = allSelectedBlocks.map((b) => cloneBlock(b));
+        const containerBlock = createBlock(
+          'webentor/l-flexible-container',
+          {},
+          clonedBlocks,
+        );
+        replaceBlocks(allSelectedClientIds, [containerBlock]);
+      } else {
+        const currentBlock = store.getBlock(clientId);
+
+        if (!currentBlock) return;
+
+        const clonedBlock = cloneBlock(currentBlock);
+        const containerBlock = createBlock(
+          'webentor/l-flexible-container',
+          {},
+          [clonedBlock],
+        );
+        replaceBlocks(clientId, [containerBlock]);
+      }
+    };
+
+    return (
+      <Fragment>
+        <BlockControls group="other">
+          <ToolbarGroup>
+            <ToolbarButton
+              icon={groupIcon}
+              label={__('Wrap with Flexible Container', 'webentor')}
+              onClick={handleWrap}
+            />
+          </ToolbarGroup>
+        </BlockControls>
+
+        <BlockEdit {...props} />
+      </Fragment>
+    );
+  };
+}, 'withWrapContainerButton');
+
+// Self-register -- imported from core editor.ts, no manual init needed
+addFilter(
+  'editor.BlockEdit',
+  'webentor/blockEdit/wrapWithContainer',
+  withWrapContainerButton,
+);

package/core-js/blocks-filters/responsive-settings/AGENTS.md

@@ -0,0 +1,255 @@
+# Responsive Settings — AI Guide
+
+This file documents the architecture, data flow, and conventions of the
+responsive settings system so AI agents can work on it without re-exploring.
+
+## Purpose
+
+Provides per-breakpoint (responsive) block controls in the WordPress editor
+sidebar. Users can configure spacing, display mode, sizing, flexbox, grid,
+flex/grid item behaviour, borders, and presets — all with breakpoint tabs
+(`basic`, `sm`, `md`, `lg`, `xl`, `2xl`). Values are stored as Tailwind
+class names and output as CSS classes on the block wrapper.
+
+## File Structure
+
+```
+responsive-settings/
+  index.tsx              — Entry point: attribute filter, registerBlockExtension, BlockEdit
+  registry.ts            — SettingsRegistry singleton (Map-based, panelGroup queries)
+  migration.ts           — Display value helpers + display-specific cascade helpers
+  utils.ts               — Class generation orchestrator + border preview helpers + generic breakpoint cascade utilities
+  constants.ts           — Legacy includedBlocks map (currently empty, kept for fallback)
+  types/index.ts         — All TypeScript interfaces (SettingDefinition, PanelGroup, BlockAttributes, etc.)
+
+  panels/                — Thin PanelBody wrappers, one per UI panel
+    SpacingPanel.tsx      — panelGroup='spacing'
+    DisplayLayoutPanel.tsx — panelGroup='displayLayout' (presets rendered above tabs)
+    BorderPanel.tsx       — panelGroup='border'
+    BlockLinkPanel.tsx    — panelGroup='blockLink' (standalone, no breakpoint tabs)
+    index.ts
+
+  components/            — Shared UI components
+    ResponsiveTabPanel.tsx    — Breakpoint tab wrapper with active-settings indicator
+    ResponsiveSelectGroup.tsx — Generic SelectControl list renderer (+ optgroup support)
+    BreakpointResetButton.tsx — Per-breakpoint "Reset" button inside tabs
+    DebugPanel.tsx            — JSON attribute inspector (gated by window flag)
+    BoxModelControl.tsx       — Margin/padding box-model layout with link modes
+    LinkedValuesControl.tsx   — Link/unlink toggle + reset button
+    DisabledSliderInfo.tsx    — Info message when slider overrides settings
+    InheritedIndicator.tsx    — "Inherited from {breakpoint}" label for cascaded settings
+
+  settings/
+    presets/              — Quick layout presets (panelGroup: displayLayout, order: 0)
+    layout/               — Display mode: flex/grid/block/hidden (panelGroup: displayLayout, order: 10)
+    sizing/               — Width/height/min/max dimensions (panelGroup: displayLayout, order: 20)
+    flexbox/              — Flexbox container controls (panelGroup: displayLayout, order: 30)
+    grid/                 — Grid container controls (panelGroup: displayLayout, order: 40)
+    flex-item/            — Flex child controls (panelGroup: displayLayout, order: 50)
+    grid-item/            — Grid child controls (panelGroup: displayLayout, order: 60)
+    spacing/              — Margin/padding (panelGroup: spacing, order: 10)
+    border/               — Border + border-radius (panelGroup: border, order: 10)
+    block-link/           — Block link (panelGroup: blockLink, order: 100)
+    shared/               — Shared value generators (gap-values, layout-values, tw-values)
+```
+
+## Architecture
+
+### Two-Layer Pattern: Panel Groups + Setting Modules
+
+The UI has **4 collapsible panels** (SpacingPanel, DisplayLayoutPanel, BorderPanel, BlockLinkPanel).
+Internally, the code is modular: each setting module is self-contained and
+declares which `panelGroup` it belongs to.
+
+Panel components are thin wrappers: they render a `PanelBody` with
+`ResponsiveTabPanel` tabs, query the registry for all modules in their
+`panelGroup` (sorted by `order`), and render each module's `SettingsComponent`.
+
+### SettingsRegistry (`registry.ts`)
+
+Singleton `Map<string, SettingDefinition>`. Modules self-register via
+side-effect imports in their `registration.ts` files.
+
+Key methods:
+- `register(def)` — add a setting module
+- `getAll()` — all modules sorted by order
+- `getByPanelGroup(group)` — modules for a specific panel
+- `isSupported(supports, def)` — check if a block supports a setting
+
+### SettingDefinition Interface
+
+```typescript
+{
+  name: string;                    // e.g. 'layout', 'sizing', 'flexbox'
+  panelGroup: PanelGroup;          // 'spacing' | 'displayLayout' | 'border'
+  order: number;                   // render order within panel (lower = higher)
+  attributeKey: string;            // WP attribute key (e.g. 'layout', 'spacing')
+  supportKey: string | string[];   // webentor.* support flag(s)
+  attributeSchema: object;         // WP attribute schema
+  initAttributes?: Function;       // custom attribute defaults (e.g. flex default)
+  SettingsComponent: React.FC;     // renders inline within the panel
+  generateClasses: Function;       // Tailwind class array per breakpoint
+  hasActiveSettings: Function;     // tab indicator (breakpoint has values?)
+  migrateFromV1?: Function;        // optional per-module migration
+}
+```
+
+### Data Flow
+
+1. **Attribute injection** (`blocks.registerBlockType` filter in `index.tsx`):
+   - Iterates all registered modules
+   - Checks `supports.webentor.*` against each module's `supportKey`
+   - Merges attribute schemas into the block
+   - Runs `initAttributes` for defaults (e.g. `layout.display = 'flex'`)
+
+2. **Editor rendering** (`BlockEdit` in `index.tsx`):
+   - Renders SpacingPanel, DisplayLayoutPanel, BorderPanel, BlockLinkPanel
+   - Each panel queries registry and renders SettingsComponents
+
+3. **Class generation** (`generateClassNames` in `utils.ts`):
+   - Called by `registerBlockExtension` classNameGenerator hook
+   - Collects breakpoints from all attribute values
+   - Calls each module's `generateClasses(attributes, breakpoint, context)` per breakpoint
+   - Concatenates results
+
+4. **PHP class generation** (`blocks-settings.php`):
+   - `SettingsRegistry::generateClasses()` iterates registered handlers
+   - Each handler reads attribute values and generates Tailwind classes
+   - `prepareBlockClassesFromSettings()` orchestrates all handlers
+
+## Attribute Shape
+
+All responsive values follow the same pattern:
+
+```
+attributes.{attributeKey}.{propertyName}.value.{breakpoint} = "tailwind-class"
+```
+
+Example:
+```json
+{
+  "layout": { "display": { "value": { "basic": "flex", "md": "grid" } } },
+  "spacing": { "margin-top": { "value": { "basic": "mt-4", "lg": "mt-8" } } },
+  "border": { "border": { "value": { "basic": { "top": { "width": "1", "style": "solid", "color": "black" }, "linked": true } } } }
+}
+```
+
+## Migration
+
+- Runtime code only reads canonical v2 keys
+- PHP migration lives in `app/blocks-migration.php`
+- `getDisplayValue()` / `getParentDisplayValue()` are the canonical display readers for `layout.display`
+
+## PHP Side (`app/blocks-settings.php`)
+
+- `SettingsRegistry` class mirrors the JS pattern
+- `get_display_value_for_breakpoint()` helper for explicit display reads
+- `get_effective_display_value_for_breakpoint()` cascaded display (min-width inheritance)
+- `get_effective_parent_display_value_for_breakpoint()` cascaded parent display
+- Handlers: `prepareLayoutBlockClassesFromSettings`, `prepareSizingBlockClassesFromSettings`,
+  `prepareFlexItemBlockClassesFromSettings` (new), plus unchanged handlers for spacing,
+  grid, gridItem, flexbox, border
+- `prepareBlockClassesFromSettings()` also outputs `_presetClasses` directly
+
+## Presets
+
+Defined in `settings/presets/presets.ts` as `LayoutPreset[]`. Each preset
+specifies `applies` (attribute values per module) and optional `customClasses`
+for edge cases that need non-Tailwind CSS (e.g. flex-wrap + gap + equal columns).
+
+Selecting a preset fills in the individual settings (which remain editable)
+and stores `_preset` (ID marker) and `_presetClasses` (custom CSS classes).
+
+Custom CSS utilities for presets live in `resources/styles/common/_utilities.css`:
+- `.w-flex-cols` — flex container with wrapping
+- `.w-flex-cols-{2-6}` — sets child width via `calc()` accounting for gap
+- `.w-gap-{0-12}` — gap + `--w-col-gap` CSS var
+
+## Block.json Support Keys
+
+### Supported Keys
+
+```json
+"webentor": {
+  "spacing": true,
+  "layout": true,
+  "sizing": true,
+  "grid": true,
+  "gridItem": true,
+  "flexbox": true,
+  "flexItem": true,
+  "border": true,
+  "borderRadius": true,
+  "blockLink": true,
+  "presets": true
+}
+```
+
+## JSON Schema
+
+`schemas/webentor-block.json` defines the canonical support keys under `supports.webentor`.
+
+## Contextual Rendering Rules
+
+Display checks use **breakpoint cascading** (min-width inheritance): if `display=flex`
+is set at `basic`, flexbox settings are visible at `sm`, `md`, etc. even without an
+explicit value, because the effective display cascades from `basic`. An
+`InheritedIndicator` label is shown when the value is inherited.
+
+- **Flexbox settings**: show when **effective** `display=flex` at the active breakpoint
+- **Grid settings**: show when **effective** `display=grid` at the active breakpoint
+- **Flex-item settings**: show when **parent** block's **effective** `display=flex`
+- **Grid-item settings**: show when **parent** block's **effective** `display=grid`
+- **Slider override**: when `slider.enabled=true` at a breakpoint, display/flexbox/spacing settings are disabled
+
+### Generic Cascade Functions (`utils.ts`)
+
+| Function | Purpose |
+|----------|---------|
+| `getEffectiveValue(attrs, attrKey, prop, bp, bps)` | Generic cascade for any string attribute property |
+| `getInheritedFromBreakpoint(attrs, attrKey, prop, bp, bps)` | Source breakpoint for inheritance (UI indicator) |
+| `getEffectiveObjectValue(attrs, attrKey, prop, bp, bps)` | Cascade for object-typed values (borders, radius) |
+| `getObjectInheritedFromBreakpoint(attrs, attrKey, prop, bp, bps)` | Source breakpoint for inherited object values |
+
+### Display Cascade Functions (`migration.ts`)
+
+| Function | Purpose |
+|----------|---------|
+| `getEffectiveDisplayValue(attrs, bp, bps)` | Cascaded display mode |
+| `getEffectiveParentDisplayValue(parentAttrs, bp, bps)` | Cascaded parent display |
+| `getDisplayInheritedFromBreakpoint(attrs, bp, bps)` | Display-specific inheritance source |
+
+PHP equivalents in `blocks-settings.php`:
+- `get_effective_display_value_for_breakpoint($attributes, $breakpoint)`
+- `get_effective_parent_display_value_for_breakpoint($parent_block, $breakpoint)`
+
+### Per-Property Cascade Indicators
+
+Every property control shows inherited values from lower breakpoints:
+
+- **`ResponsiveSelectGroup`** — when a select has no explicit value but an inherited
+  value exists, the placeholder changes from "None selected" to e.g. "Flex Row (from basic)"
+  and the select is styled with `.wbtr-inherited-value` (italic, muted color).
+- **`BoxModelControl`** — same placeholder replacement per side select for spacing.
+- **`BorderSettings` / `BorderRadiusSettings`** — section-level `InheritedIndicator`
+  label shown when border/radius objects cascade from a lower breakpoint.
+
+The `breakpoints` prop is threaded from `SettingsComponentProps` → `ResponsiveSelectGroup` /
+`BoxModelControl` to enable cascade lookups. CSS class `.wbtr-inherited-value` in
+`resources/styles/common/_editor.css` provides the visual styling.
+
+## Adding a New Setting Module
+
+1. Create `settings/{name}/` with: `index.ts`, `properties.ts`, `settings.tsx`, `registration.ts`
+2. In `registration.ts`, call `registry.register({ name, panelGroup, order, ... })`
+3. Import `./settings/{name}` in `index.tsx` (side-effect import)
+4. Add a matching PHP handler in `blocks-settings.php` and register it
+5. Update `schemas/webentor-block.json` if adding a new support key
+
+## Common Mistakes to Avoid
+
+- **Don't read `attributes.layout.display` directly in contextual modules** — use `getDisplayValue()` from `migration.ts`
+- **Don't read parent display directly** — use `getParentDisplayValue()`
+- **Don't create a new PanelBody in a SettingsComponent** — it renders inline within an existing panel
+- **Don't forget both JS and PHP** — class generation runs on both sides
+- **Don't change version numbers here unless the task is an explicit release change** — follow the root `AGENTS.md` release policy for manual versioning and changelog updates