apostrophe 4.29.0 → 4.30.0

package/.claude/settings.local.json

@@ -0,0 +1,15 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(timeout 180 npx mocha:*)",
+      "Bash(timeout 600 npx mocha:*)",
+      "Bash(npm ls:*)",
+      "Bash(timeout 540 npx mocha:*)",
+      "Bash(echo:*)",
+      "Bash(timeout 10 node:*)",
+      "Bash(timeout 300 npx mocha:*)",
+      "Bash(timeout 60 npx mocha:*)",
+      "Bash(timeout 120 npx mocha:*)"
+    ]
+  }
+}

package/CHANGELOG.md

@@ -1,5 +1,39 @@
 # Changelog
 
+## 4.30.0
+
+### Adds
+
+- Layout widget gap is now controllable through the styles system, both site-wide via a global `layoutGap` preset and per widget via a `gap` styles field. A new `className` option allows additional CSS classes to be added to the widget grid container.
+
+### Fixes
+
+- Fixed layout widget not regaining full focus when switching back to Edit content mode.
+- Fixed illegal HTML `id` attribute values generated by the admin UI.
+- Fixed orderable table array items dragging the entire floating window.
+- Fixed keyboard shortcuts for widget operations (copy, cut, paste, duplicate, remove) blocking the browser's native clipboard behavior when no widget was focused. Previously, selecting and copying text while logged in was intercepted unconditionally by the admin UI.
+- Removed duplicate `<meta charset>` tag from `outerLayoutBase.html` and standardized charset to `utf-8`.
+- Updated `apostrophe` and `oembetter` to remove oembed services that no longer support public access, eliminating them as a potential future XSS vector. New `minimumAllowlist` and `minimumEndpoints` options on `@apostrophecms/oembed` allow developers to prune the list further.
+
+### Security
+
+- **Password reset base URL requirement:** The password reset feature now refuses to operate unless `baseUrl` or `APOS_BASE_URL` is set, preventing a vulnerability where ApostropheCMS could be convinced to send emails with links to attacker-controlled sites. Only affects projects with `passwordReset: true` on the login module. Thanks to [SPIDY](https://github.com/Mujahidkhan525) for reporting.
+- **XSS via full name field:** A malicious full name containing HTML was executed in the page title tooltip in the admin bar, posing an XSS risk to other users. All multi-user projects should update promptly. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting.
+- **XSS via image widget link URL:** Users with editing privileges could trigger arbitrary JavaScript via a `javascript:` URL in the image widget's link URL field. A migration is included to strip any such URLs already in the database. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting.
+- **SSRF via rich text HTML import:** The rich text widget's HTML import feature no longer fetches images from arbitrary hosts, which could be used to probe internal networks or exfiltrate internal images. Configure `imageImportAllowedHostnames` on `@apostrophecms/rich-text-widget` to opt in. Thanks to [Yiğit Şengezer](https://github.com/yigitsengezer) and [Sainithin0309](https://github.com/Sainithin0309) for reporting.
+-  **the xmp tag could be used to pass forbidden markup through sanitize-html**, even when xmp itself. This was fixed in `sanitize-html` and the dependency was bumped. Thanks to [Vincenzo Turturro](https://github.com/sushi-gif) for reporting the vulnerability.
+- **the `linkHref` field of image widgets was an XSS vulnerability** because it did not use the `url` field type. This means that a user with editing privileges could potentially carry out XSS. In addition, we have updated the `launder` module to sanitize URLs more robustly for the `url` field type, and bumped that dependency. Also, a database migration is included to clean any XSS attacks that could be present in existing links. Thanks to [Muhammad Uwais](https://github.com/MuhammadUwais) for reporting the issue.
+
+### Accessibility
+
+- Corrected ARIA semantics on the top admin navigation bar.
+- Improved the document context title (admin bar middle group) and the underlying `AposContextMenu` machinery.
+- Improved the locale switcher (`AposLocalePicker`).
+- The Recently Edited Documents tray icon now exposes its action via `aria-label`.
+- Fixed `.apos-sr-only` so screen-reader-only content is correctly exposed to the accessibility tree.
+- Icon-only context-utility buttons in the admin bar tray (e.g. the global settings cog) now expose their action via `aria-label`.
+
+
 ## 4.29.0 (2026-04-15)
 
 ### Adds

package/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBar.vue

@@ -11,7 +11,6 @@
     <nav
       ref="adminBar"
       :class="classes"
-      role="menubar"
       aria-label="Apostrophe Admin Bar"
     >
       <div class="apos-admin-bar__row">

package/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposAdminBarMenu.vue

@@ -1,8 +1,5 @@
 <template>
-  <ol
-    class="apos-admin-bar__items"
-    role="menu"
-  >
+  <ol class="apos-admin-bar__items">
     <li
       v-if="pageTree"
       class="apos-admin-bar__item"
@@ -12,7 +9,6 @@
         label="apostrophe:pages"
         class="apos-admin-bar__btn"
         :modifiers="['no-motion']"
-        role="menuitem"
         action-test-label="page-manager-button"
         @click="emitEvent({ action: '@apostrophecms/page:manager' })"
       />
@@ -33,7 +29,6 @@
           class: 'apos-admin-bar__btn',
           type: 'subtle'
         }"
-        role="menuitem"
         @item-clicked="emitEvent"
       />
       <Component
@@ -44,7 +39,6 @@
         :modifiers="['no-motion']"
         class="apos-admin-bar__btn"
         :action-test-label="`${item.name}-manager-button`"
-        role="menuitem"
         @click="emitEvent(item)"
       />
     </li>
@@ -62,7 +56,6 @@
           type: 'primary',
           modifiers: ['round', 'no-motion']
         }"
-        role="menuitem"
         @item-clicked="emitEvent"
       />
     </li>
@@ -89,6 +82,7 @@
           :label="item.label"
           :action="item.action"
           :state="trayItemState[item.name] ? [ 'active' ] : []"
+          :attrs="trayItemAttrs(item)"
           @click="emitEvent(item)"
         />
       </template>
@@ -185,6 +179,29 @@ export default {
       } else {
         return item.options.tooltip;
       }
+    },
+    // Tray utility buttons render icon-only, so the visible label
+    // (e.g. "Global Content") is sr-only and doesn't describe what the
+    // button does. Make them accessible by providing an aria-label based on
+    // the tooltip content.
+    trayItemAttrs(item) {
+      const tooltip = item.options?.tooltip;
+      let key = null;
+      if (item.options?.toggle) {
+        if (this.trayItemState[item.name] && tooltip?.deactivate) {
+          key = tooltip.deactivate;
+        } else if (tooltip?.activate) {
+          key = tooltip.activate;
+        }
+      } else if (typeof tooltip === 'string') {
+        key = tooltip;
+      } else if (tooltip && typeof tooltip.content === 'string') {
+        key = tooltip.content;
+      }
+      if (!key) {
+        return {};
+      }
+      return { 'aria-label': this.$t(key) };
     }
   }
 };

package/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextBreakpointPreviewMode.vue

@@ -14,6 +14,7 @@
         :label="screen.label"
         :tooltip="$t(screen.label)"
         :title="$t(screen.label)"
+        :attrs="shortcutAttrs(screen)"
         :icon="screen.icon"
         :icon-only="true"
         type="subtle"
@@ -36,6 +37,7 @@
       :active-item="mode"
       :center-on-icon="true"
       menu-placement="bottom-end"
+      :dialog-label="'apostrophe:breakpointPreviewSelectMenu'"
       @item-clicked="selectBreakpoint"
     />
     <Transition>
@@ -320,6 +322,13 @@ export default {
     },
     setShowDropdown() {
       this.showDropdown = Object.values(this.screens).some(({ shortcut }) => !shortcut);
+    },
+    shortcutAttrs(screen) {
+      return {
+        'aria-label': this.$t('apostrophe:breakpointPreviewShortcut', {
+          breakpoint: this.$t(screen.label)
+        })
+      };
     }
   }
 };

package/modules/@apostrophecms/admin-bar/ui/apos/components/TheAposContextTitle.vue

@@ -33,6 +33,8 @@
           :disabled="hasCustomUi || isUnpublished"
           :center-on-icon="true"
           menu-placement="bottom-end"
+          :dialog-label="'apostrophe:publicationStatusMenu'"
+          :trigger-aria-label="draftTriggerAriaLabel"
           @item-clicked="switchDraftMode"
         />
         <AposLabel
@@ -56,6 +58,15 @@
 <script>
 import dayjs from 'dayjs';
 
+function escapeHtml(s) {
+  return String(s)
+    .replace(/&/g, '&amp;')
+    .replace(/</g, '&lt;')
+    .replace(/>/g, '&gt;')
+    .replace(/"/g, '&quot;')
+    .replace(/'/g, '&#39;');
+}
+
 export default {
   name: 'TheAposContextTitle',
   props: {
@@ -78,8 +89,8 @@ export default {
       if (this.context.updatedBy) {
         const editor = this.context.updatedBy;
         editorLabel = '';
-        editorLabel += editor.title ? `${editor.title} ` : '';
-        editorLabel += editor.username ? `(${editor.username})` : '';
+        editorLabel += editor.title ? `${escapeHtml(editor.title)} ` : '';
+        editorLabel += editor.username ? `(${escapeHtml(editor.username)})` : '';
       }
       return editorLabel;
     },
@@ -91,6 +102,13 @@ export default {
         type: 'quiet'
       };
     },
+    draftTriggerAriaLabel() {
+      return this.$t('apostrophe:publicationStatusTrigger', {
+        status: this.$t(
+          this.draftMode === 'draft' ? 'apostrophe:draft' : 'apostrophe:published'
+        )
+      });
+    },
     isUnpublished() {
       return !this.context.lastPublishedAt;
     },

package/modules/@apostrophecms/area/index.js

@@ -19,7 +19,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-cut-widget'
           },
-          shortcut: 'Ctrl+X Meta+X'
+          shortcut: 'Ctrl+X Meta+X',
+          requireWidgetFocus: true
         },
         [`${self.__meta.name}:copy-widget`]: {
           type: 'item',
@@ -27,7 +28,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-copy-widget'
           },
-          shortcut: 'Ctrl+C Meta+C'
+          shortcut: 'Ctrl+C Meta+C',
+          requireWidgetFocus: true
         },
         [`${self.__meta.name}:paste-widget`]: {
           type: 'item',
@@ -35,7 +37,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-paste-widget'
           },
-          shortcut: 'Ctrl+V Meta+V'
+          shortcut: 'Ctrl+V Meta+V',
+          requireWidgetFocus: true
         },
         [`${self.__meta.name}:duplicate-widget`]: {
           type: 'item',
@@ -43,7 +46,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-duplicate-widget'
           },
-          shortcut: 'Ctrl+Shift+D Meta+Shift+D'
+          shortcut: 'Ctrl+Shift+D Meta+Shift+D',
+          requireWidgetFocus: true
         },
         [`${self.__meta.name}:remove-widget`]: {
           type: 'item',
@@ -51,7 +55,8 @@ module.exports = {
           action: {
             type: 'command-menu-area-remove-widget'
           },
-          shortcut: 'Backspace'
+          shortcut: 'Backspace',
+          requireWidgetFocus: true
         }
       },
       modal: {

package/modules/@apostrophecms/area/ui/apos/components/AposAreaWidget.vue

@@ -536,6 +536,7 @@ export default {
     apos.bus.$on('widget-focus-parent', this.focusParent);
     apos.bus.$on('context-menu-toggled', this.getFocusForMenu);
     apos.bus.$on('suppress-focused-widget-controls', this.doSuppressWidgetControls);
+    apos.bus.$on('clear-focused-widget-control-suppression', this.clearSuppressionFlags);
 
     this.breadcrumbs.$lastEl = this.$el;
 
@@ -573,6 +574,7 @@ export default {
     // Remove the focus parent listener when unmounted
     apos.bus.$off('widget-focus-parent', this.focusParent);
     apos.bus.$off('suppress-focused-widget-controls', this.doSuppressWidgetControls);
+    apos.bus.$off('clear-focused-widget-control-suppression', this.clearSuppressionFlags);
     window.removeEventListener('scroll', this.stickyControlsScroll);
     window.removeEventListener('resize', this.stickyControlsResize);
     this.unregisterFromGraph();

package/modules/@apostrophecms/command-menu/ui/apos/components/TheAposCommandMenu.vue

@@ -10,6 +10,7 @@
 import { mapActions, mapState } from 'pinia';
 import AposThemeMixin from 'Modules/@apostrophecms/ui/mixins/AposThemeMixin';
 import { useModalStore } from 'Modules/@apostrophecms/ui/stores/modal';
+import { useWidgetStore } from 'Modules/@apostrophecms/ui/stores/widget';
 
 export default {
   name: 'TheAposCommandMenu',
@@ -50,7 +51,13 @@ export default {
               .flatMap(command => {
                 return command.shortcut
                   .split(' ')
-                  .map(shortcut => [ shortcut.toUpperCase(), command.action ]);
+                  .map(shortcut => [
+                    shortcut.toUpperCase(),
+                    {
+                      ...command.action,
+                      requireWidgetFocus: command.requireWidgetFocus || false
+                    }
+                  ]);
               });
           })
       );
@@ -111,6 +118,9 @@ export default {
             ? keys.slice('SHIFT+'.length)
             : keys];
         if (action) {
+          if (action.requireWidgetFocus && !useWidgetStore().focusedWidget) {
+            return;
+          }
           event.preventDefault();
           apos.bus.$emit(action.type, action.payload);
           return;

package/modules/@apostrophecms/i18n/i18n/en.json

@@ -89,6 +89,8 @@
   "breakpointPreviewExit": "Exit",
   "breakpointPreviewMobile": "Mobile",
   "breakpointPreviewSelect": "Select Breakpoint",
+  "breakpointPreviewSelectMenu": "Breakpoint preview menu",
+  "breakpointPreviewShortcut": "Preview at {{ breakpoint }} breakpoint",
   "breakpointPreviewTablet": "Tablet",
   "browse": "Browse",
   "browseDocType": "Browse {{ type }}",
@@ -387,6 +389,7 @@
   "mediaUploadViaDrop": "Drop ’em when you’re ready",
   "mediaUploadViaExplorer": "Or click to open the file explorer",
   "mergeCells": "Merge Cells",
+  "menu": "Menu",
   "minLabel": "Min:",
   "minSize": "Min size of {{ width }}x{{ height }}",
   "minimumSize": "Minimum size of {{ width }} x {{ height }} px",
@@ -475,6 +478,8 @@
   "publishBeforeUsingTooltip": "Publish this content before using it in a relationship",
   "publishType": "Publish {{ type }}",
   "published": "Published",
+  "publicationStatusMenu": "Publication status",
+  "publicationStatusTrigger": "Publication status: {{ status }}. Change publication status.",
   "publishingBatchConfirmation": "Are you sure you want to publish {{ count }} {{ type }}?",
   "publishingBatchConfirmationButton": "Yes, publish content.",
   "rawCssAndJs": "Raw CSS and JS",
@@ -490,6 +495,7 @@
   "recentlyEditedActionSubmitted": "Submitted",
   "recentlyEditedCurrentUser": "Me ({{ user }})",
   "recentlyEditedDocuments": "Recently edited documents",
+  "recentlyEditedManagerOpen": "Open recently edited documents manager",
   "recentlyEditedEditedBy": "Edited by",
   "recentlyEditedClearAllFilters": "Clear all filters",
   "recentlyEditedClearSearch": "Clear search",
@@ -643,6 +649,8 @@
   "styleGradientAngle": "Angle",
   "styleGradientEnd": "End Color",
   "styleGradientStart": "Start Color",
+  "styleLayoutGap": "Layout Gap",
+  "styleLayoutGapHelp": "Sets the spacing between columns inside layout sections across the site.",
   "styleLeft": "Left",
   "styleMargin": "Margin",
   "styleOverlayColor": "Overlay Color",

package/modules/@apostrophecms/i18n/index.js

@@ -29,10 +29,6 @@
 // in the same language as the website content.
 // Example: `defaultAdminLocale: 'fr'`.
 //
-// ### `encoding`
-//
-// Defaults to `'utf-8'`. You almost certainly do not want to change this.
-//
 // ### `slugDirection`
 //
 // Controls the default `direction` value of slug schema. Can be `ltr`, `rtl` or
@@ -81,8 +77,6 @@ module.exports = {
     },
     // If true, slugifying will strip accents from Latin characters
     stripUrlAccents: false,
-    // You almost certainly do not want to change this
-    encoding: 'utf-8',
     slugDirection: 'ltr'
   },
   async init(self) {
@@ -166,7 +160,6 @@ module.exports = {
     await self.i18next.init(i18nextOptions);
     self.addInitialResources();
     self.enableBrowserData();
-    self.encoding = self.options.encoding;
   },
   handlers(self) {
     return {
@@ -1369,7 +1362,7 @@ module.exports = {
   helpers(self) {
     return {
       encoding() {
-        return self.encoding;
+        return 'utf-8';
       }
     };
   }

package/modules/@apostrophecms/image-widget/index.js

@@ -102,7 +102,7 @@ module.exports = {
         linkHref: {
           label: 'apostrophe:url',
           help: 'apostrophe:linkHrefHelp',
-          type: 'string',
+          type: 'url',
           required: true,
           if: {
             linkTo: '_url'
@@ -147,6 +147,7 @@ module.exports = {
     self.showPlaceholder = self.options.placeholder !== false;
     self.options.placeholder = true;
     self.determineBestAssetUrl('placeholder');
+    self.addCleanLinkHrefMigration();
   },
   handlers(self) {
     return {
@@ -159,6 +160,33 @@ module.exports = {
   },
   methods(self) {
     return {
+      // Clear link hrefs that use dangerous URL schemes (e.g.
+      // `javascript:`) and may have been stored before the linkHref
+      // schema field was changed to `type: 'url'`. Registered per
+      // module instance so subclasses of this widget are migrated
+      // under their own widget type and migration name.
+      addCleanLinkHrefMigration() {
+        self.apos.migration.add(
+          `${self.__meta.name}:clean-naughty-link-href`,
+          async () => {
+            await self.apos.migration.eachWidget({}, async (doc, widget, dotPath) => {
+              if (widget.type !== self.name) {
+                return;
+              }
+              if (!widget.linkHref) {
+                return;
+              }
+              if (!self.apos.launder.naughtyHref(widget.linkHref)) {
+                return;
+              }
+              await self.apos.doc.db.updateOne(
+                { _id: doc._id },
+                { $set: { [`${dotPath}.linkHref`]: '' } }
+              );
+            });
+          }
+        );
+      },
       validateAndAddSchemaLabels() {
         const linkWithType = self.options.linkWithType;
 

package/modules/@apostrophecms/layout-widget/index.js

@@ -19,6 +19,10 @@ module.exports = {
     gap: '1.5rem',
     defaultCellHorizontalAlignment: null,
     defaultCellVerticalAlignment: null,
+    // Extra class name(s) to append to the rendered layout-widget area
+    // wrapper, in addition to the built-in `layout-widget` class. Accepts
+    // a string of space-separated class names.
+    className: '',
     injectStyles: true,
     minifyStyles: true
   },
@@ -98,6 +102,25 @@ module.exports = {
         validateAndIdentifyTypes() {
           const { column } = self.validateAndIdentifyTypes();
           self.columnWidgetName = column;
+        },
+        // Detect the widget-style "gap" field (any styles field whose
+        // CSS `property` resolves to `gap`). Only the first match is used.
+        // Also detect whether the @apostrophecms/styles module has a
+        // site-wide layout gap field configured (via the `layoutGap`
+        // preset / `layoutGapDefault: true` marker).
+        detectGapFields() {
+          const widgetGapFields = self.apos.styles
+            .fieldsWithProperty(self.schema, 'gap');
+          if (widgetGapFields.length > 1) {
+            self.apos.util.warn(
+              `[${self.__meta.name}] Multiple style fields produce the ` +
+              `CSS \`gap\` property (${widgetGapFields.join(', ')}). ` +
+              'Only the first one will be honoured as the widget-scope gap.'
+            );
+          }
+          self.widgetGapFieldName = widgetGapFields[0] || null;
+          self.globalGapEnabled = !!self.apos.modules['@apostrophecms/styles']
+            ?.layoutGapFieldName;
         }
       }
     };
@@ -118,6 +141,17 @@ module.exports = {
             defaultCellHorizontalAlignment: self.options.defaultCellHorizontalAlignment,
             defaultCellVerticalAlignment: self.options.defaultCellVerticalAlignment
           },
+          widgetGapFieldName: self.widgetGapFieldName || null,
+          widgetGapFieldUnit: self.widgetGapFieldName
+            ? (self.apos.styles
+              .getFieldByPath(self.schema, self.widgetGapFieldName)
+              ?.unit || '')
+            : '',
+          globalGapEnabled: !!self.globalGapEnabled,
+          // Opt-in flag read by the generic widget editor: when true,
+          // it broadcasts `apos-widget-live-preview` events on the apos bus
+          // during the style-only fast path.
+          subscribesToLivePreview: !!self.widgetGapFieldName,
           columnWidgetName: self.columnWidgetName
         };
       },
@@ -132,6 +166,7 @@ module.exports = {
           defaultCellHorizontalAlignment,
           defaultCellVerticalAlignment
         } = self.options;
+        const widgetGap = self.resolveWidgetGap(widget);
         return {
           ..._super(widget, { scene }),
           columns,
@@ -141,13 +176,53 @@ module.exports = {
           tablet,
           gap,
           defaultCellHorizontalAlignment,
-          defaultCellVerticalAlignment
+          defaultCellVerticalAlignment,
+          _gap: widgetGap,
+          _gapHasGlobal: !!self.globalGapEnabled
         };
       }
     };
   },
   methods(self) {
     return {
+      // Resolve the widget-scope gap for a widget instance, if this
+      // module declares a styles field with `property: 'gap'`. Returns
+      // the resolved value (with unit, when applicable). When the
+      // widget has no explicit value, falls back to the field's `def`.
+      // Returns `null` only when no widget gap field is
+      // configured, no widget value is set, and no `def` is declared
+      // on the field.
+      resolveWidgetGap(widget) {
+        if (!self.widgetGapFieldName || !widget) {
+          return null;
+        }
+        const field = self.apos.styles.getFieldByPath(
+          self.schema, self.widgetGapFieldName
+        );
+        let value = self.apos.util.get(widget, self.widgetGapFieldName);
+        if (value === null || value === undefined || value === '') {
+          if (field?.def === null || field?.def === undefined || field?.def === '') {
+            return null;
+          }
+          value = field.def;
+        }
+        if (field?.unit && typeof value !== 'string') {
+          return `${value}${field.unit}`;
+        }
+        return value;
+      },
+      // Determine whether the inline `--grid-gap` CSS variable should
+      // be omitted on the grid container so the global cascade
+      // (`var(--apos-layout-gap, …)`) can take effect. The inline var
+      // is omitted whenever:
+      //   - no widget-scope gap value is set, AND
+      //   - the global layout-gap field is configured.
+      shouldOmitInlineGap(widget, global) {
+        if (!self.globalGapEnabled) {
+          return false;
+        }
+        return self.resolveWidgetGap(widget) === null;
+      },
       publicCssNodes(req) {
         return [
           {
@@ -277,11 +352,13 @@ module.exports = {
         const mobileBreakpointPlus = mobileBreakpoint + 1;
         const tabletBreakpoint = self.options.tablet?.breakpoint || 1024;
         const tabletBreakpointPlus = tabletBreakpoint + 1;
+        const gapDefault = self.options.gap || '0';
         cssContent = cssContent
           .replace(/\{\$mobile\}/g, mobileBreakpoint)
           .replace(/\{\$mobile-plus\}/g, mobileBreakpointPlus)
           .replace(/\{\$tablet\}/g, tabletBreakpoint)
-          .replace(/\{\$tablet-plus\}/g, tabletBreakpointPlus);
+          .replace(/\{\$tablet-plus\}/g, tabletBreakpointPlus)
+          .replace(/\{\$gap-default\}/g, gapDefault);
 
         return self.processCss(cssContent, scene);
       },
@@ -371,6 +448,51 @@ module.exports = {
           (a.order ?? 0) - (b.order ?? 0)
         );
         return items[items.length - 1]._id;
+      },
+      // Compute the `--grid-gap: <value>;` declaration to inline on the
+      // grid container, or an empty string when the cascade should
+      // resolve gap via `var(--apos-layout-gap, …)` instead.
+      // Honours the priority order:
+      //   1. Widget-style gap (when set on this widget instance).
+      //   2. Static module option (BC) — when no global gap field is
+      //      configured, or it has no value.
+      //   3. Otherwise, omit the inline var so the global cascade wins.
+      // Must be invoked via the widget's own module namespace —
+      // `apos.modules[data.manager.__meta.name].gapInlineCss(...)` —
+      // so that `self` resolves to the actual subclass and picks up
+      // its `widgetGapFieldName` / `globalGapEnabled`.
+      gapInlineCss(widget, options, global) {
+        const widgetGap = self.resolveWidgetGap(widget);
+        if (widgetGap !== null) {
+          return ` --grid-gap: ${widgetGap};`;
+        }
+        if (self.shouldOmitInlineGap(widget, global)) {
+          return '';
+        }
+        const fallback = (options && options.gap) || self.options.gap || '0';
+        return ` --grid-gap: ${fallback};`;
+      },
+      // Build the `aposParentOptions` payload passed by the rendered
+      // layout-widget area to the in-place editor (AposAreaLayoutEditor).
+      // Includes the widget's resolved gap (from its `gap` styles field,
+      // when present) so the live editor's grid container reflects the
+      // saved per-widget value rather than only the static module
+      // option. Sets `gap: null` to signal the editor to omit
+      // `--grid-gap` so the global cascade resolves it through
+      // `:root { --apos-layout-gap }`. Must be invoked via the widget's
+      // own module namespace, like `gapInlineCss`.
+      parentOptionsForArea(widget, options, global) {
+        const opts = {
+          ...(options || {}),
+          widgetId: widget._id
+        };
+        const widgetGap = self.resolveWidgetGap(widget);
+        if (widgetGap !== null) {
+          opts.gap = widgetGap;
+        } else if (self.shouldOmitInlineGap(widget, global)) {
+          opts.gap = null;
+        }
+        return opts;
       }
     };
   }