domma-cms 0.41.1 → 0.43.1

package/server/services/markdown.js

@@ -11,8 +11,10 @@ import {fileURLToPath} from 'url';
 import {applyTransforms, getSanitizeExtensions, getShortcodeProcessors} from './hooks.js';
 import {getConfig} from '../config.js';
 import {getCollection, listEntries} from './collections.js';
-import {getMenu, resolveLocation, resolveMenuDecorations, colourToCss, floatToCss} from './menus.js';
+import {getMenu, resolveLocation, resolveMenuDecorations} from './menus.js';
+import {buildMenuNav} from './menuRender.js';
 import {checkVisibility} from '../middleware/auth.js';
+import {getRoleHierarchy} from './roles.js';
 
 const __dirname_md = path.dirname(fileURLToPath(import.meta.url));
 const BLOCKS_DIR = path.resolve(__dirname_md, '../../content/blocks');
@@ -173,6 +175,51 @@ function formatDate(input, fmt) {
         t => String(tokens[t]()));
 }
 
+const EXPORT_FORMATS = ['csv', 'json'];
+
+/**
+ * Decide whether a display offers export, and to whom. First match wins:
+ *   1. schema export.enabled === false  → never (exportable="true" ignored)
+ *   2. exportable="true" on the shortcode → public (grandfathered: that is
+ *      exactly what the attribute has always meant)
+ *   3. schema export.access             → as configured
+ *   4. otherwise                        → the least-privileged role
+ *
+ * @param {object|undefined} schemaExport - schema.json `export` block
+ * @param {object} attrs                  - shortcode attributes
+ * @param {string} defaultRole            - least-privileged role name
+ */
+export function resolveExportConfig(schemaExport, attrs, defaultRole) {
+    const cfg = schemaExport || {};
+    if (cfg.enabled === false) return {allowed: false, access: null, formats: [], roles: []};
+    const formats = (Array.isArray(cfg.formats) ? cfg.formats : EXPORT_FORMATS)
+        .filter(f => EXPORT_FORMATS.includes(f));
+    const access = attrs?.exportable === 'true' ? 'public' : (cfg.access || defaultRole);
+    return {allowed: true, access, formats, roles: rolesAtOrAbove(access)};
+}
+
+/**
+ * The role names permitted by an `access` setting — the named role plus every
+ * more-privileged one above it.
+ *
+ * The browser cannot do this itself: it learns the visitor's role name from
+ * /api/auth/me but has no copy of the hierarchy, so without this list it could
+ * only ask "is anyone signed in?" and every role setting would behave
+ * identically. Resolving it server-side keeps the check a single membership
+ * test on the client.
+ *
+ * @param {string} access - 'public', or a role name
+ * @returns {string[]} empty for 'public' (no check needed) or an unknown role
+ */
+function rolesAtOrAbove(access) {
+    if (access === 'public') return [];
+    const hierarchy = getRoleHierarchy();          // most → least privileged
+    const idx = hierarchy.indexOf(access);
+    // Unknown role name: fail closed with an empty list rather than granting
+    // everyone, so a typo in schema.json cannot open export up.
+    return idx === -1 ? [] : hierarchy.slice(0, idx + 1);
+}
+
 /**
  * Build the `data-ctx` attribute that powers the public-site right-click
  * search/filter menu (public/js/collection-context.js). The payload carries
@@ -181,9 +228,12 @@ function formatDate(input, fmt) {
  *
  * @param {Array<{name: string, label?: string}>} fields - displayed fields
  * @param {object[]} entries - collection entries {id, data}
+ * @param {object} [opts]
+ * @param {string} [opts.slug]   - collection slug (for export requests)
+ * @param {object} [opts.export] - resolveExportConfig() result
  * @returns {string} ` data-ctx="<base64 JSON>"` (leading space included)
  */
-function buildCtxAttr(fields, entries) {
+function buildCtxAttr(fields, entries, opts = {}) {
     const names = [...new Set(fields.map(f => f?.name).filter(Boolean))];
     if (!names.length || !entries.length) return '';
     const payload = {
@@ -193,6 +243,8 @@ function buildCtxAttr(fields, entries) {
             data: Object.fromEntries(names.map(n => [n, e.data?.[n] ?? '']))
         }))
     };
+    if (opts.slug) payload.slug = opts.slug;
+    if (opts.export) payload.export = opts.export;
     return ` data-ctx="${Buffer.from(JSON.stringify(payload), 'utf8').toString('base64')}"`;
 }
 
@@ -254,7 +306,7 @@ function interpolateBlockTemplate(blockTemplate, e) {
  * @param {object|null} ctaOpts  - Optional CTA button options
  * @returns {string}
  */
-function renderCollectionBlocks(entries, blockTemplate, emptyMsg, ctaOpts, cols, blockName = '', blockCss = '') {
+function renderCollectionBlocks(entries, blockTemplate, emptyMsg, ctaOpts, cols, blockName = '', blockCss = '', ctxOpts = {}) {
     if (!entries.length) {
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
     }
@@ -286,7 +338,7 @@ function renderCollectionBlocks(entries, blockTemplate, emptyMsg, ctaOpts, cols,
         ? `dm-collection-display dm-collection-blocks grid ${responsiveGridCols(validCols).join(' ')} gap-4`
         : 'dm-collection-display dm-collection-blocks';
 
-    const ctx = buildCtxAttr(blockTemplateFields(blockTemplate), entries);
+    const ctx = buildCtxAttr(blockTemplateFields(blockTemplate), entries, ctxOpts);
     const styleTag = buildBlockStyleTag(blockName, blockCss);
     return `${styleTag}<div class="${wrapperClass}"${ctx}>\n${items.join('\n')}\n</div>`;
 }
@@ -455,7 +507,7 @@ function displayValueHtml(entry, field) {
     return escapeHtmlText(displayValue(entry, field));
 }
 
-function renderCollectionTable(slug, entries, visibleFields, attrs, ctaOpts) {
+function renderCollectionTable(slug, entries, visibleFields, attrs, ctaOpts, ctxOpts = {}) {
     const columns = visibleFields.map(f => ({key: f.name, title: f.label || f.name}));
     const rows = entries.map(e => {
         const row = {};
@@ -473,14 +525,16 @@ function renderCollectionTable(slug, entries, visibleFields, attrs, ctaOpts) {
         sortable: attrs.sortable !== 'false',
         exportable: attrs.exportable === 'true',
         pageSize: parseInt(attrs['page-size'], 10) || 25,
-        empty: attrs.empty || 'No entries found'
+        empty: attrs.empty || 'No entries found',
+        slug: ctxOpts.slug || slug,
+        exportCfg: ctxOpts.export || {allowed: false, access: null, formats: []}
     };
     if (ctaOpts) tableOpts.ctaConfig = ctaOpts;
     const payload = Buffer.from(JSON.stringify(tableOpts)).toString('base64');
     return `<div class="dm-collection-display" data-collection-table data-slug="${escapeAttr(slug)}" data-payload="${payload}"></div>`;
 }
 
-function renderCollectionCards(entries, visibleFields, titleField, columns, emptyMsg, ctaOpts) {
+function renderCollectionCards(entries, visibleFields, titleField, columns, emptyMsg, ctaOpts, ctxOpts = {}) {
     const cols = ['2', '3', '4'].includes(String(columns)) ? columns : '3';
     if (!entries.length) {
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
@@ -505,10 +559,10 @@ function renderCollectionCards(entries, visibleFields, titleField, columns, empt
         }
         return `<div class="card" data-entry-id="${escapeAttr(String(e.id ?? ''))}">${title ? `<div class="card-header">${title}</div>` : ''}<div class="card-body">${body || '&nbsp;'}</div>${footer}</div>`;
     }).join('\n');
-    return `<div class="dm-collection-display grid ${responsiveGridCols(cols).join(' ')} gap-4"${buildCtxAttr(visibleFields, entries)}>\n${cards}\n</div>`;
+    return `<div class="dm-collection-display grid ${responsiveGridCols(cols).join(' ')} gap-4"${buildCtxAttr(visibleFields, entries, ctxOpts)}>\n${cards}\n</div>`;
 }
 
-function renderCollectionList(entries, visibleFields, titleField, emptyMsg, ctaOpts) {
+function renderCollectionList(entries, visibleFields, titleField, emptyMsg, ctaOpts, ctxOpts = {}) {
     if (!entries.length) {
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
     }
@@ -532,7 +586,7 @@ function renderCollectionList(entries, visibleFields, titleField, emptyMsg, ctaO
         }
         return `<div class="dm-collection-list-item" data-entry-id="${escapeAttr(String(e.id ?? ''))}">${title ? `<strong>${title}</strong>` : ''}${rest}${ctaHtml}</div>`;
     }).join('\n');
-    return `<div class="dm-collection-display dm-collection-list"${buildCtxAttr(visibleFields, entries)}>\n${items}\n</div>`;
+    return `<div class="dm-collection-display dm-collection-list"${buildCtxAttr(visibleFields, entries, ctxOpts)}>\n${items}\n</div>`;
 }
 
 /**
@@ -544,7 +598,7 @@ function renderCollectionList(entries, visibleFields, titleField, emptyMsg, ctaO
  * @param {string} emptyMsg
  * @returns {string}
  */
-function renderCollectionAccordion(entries, titleField, bodyField, multiple, emptyMsg) {
+function renderCollectionAccordion(entries, titleField, bodyField, multiple, emptyMsg, ctxOpts = {}) {
     if (!entries.length) {
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
     }
@@ -563,7 +617,7 @@ function renderCollectionAccordion(entries, titleField, bodyField, multiple, emp
         );
     }).join('\n');
 
-    const ctx = buildCtxAttr([{name: titleField}, {name: bodyField}], entries);
+    const ctx = buildCtxAttr([{name: titleField}, {name: bodyField}], entries, ctxOpts);
     return `<div class="dm-collection-display accordion"${multiAttr}${ctx}>\n${items}\n</div>`;
 }
 
@@ -584,7 +638,7 @@ function renderCollectionAccordion(entries, titleField, bodyField, multiple, emp
  * @param {string} opts.emptyMsg
  * @returns {string}
  */
-function renderCollectionTimeline(entries, opts) {
+function renderCollectionTimeline(entries, opts, ctxOpts = {}) {
     const {titleField, dateField, statusField, iconField, bodyField, layout, theme, mode, emptyMsg} = opts;
     if (!entries.length) {
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
@@ -603,7 +657,8 @@ function renderCollectionTimeline(entries, opts) {
 
     const ctx = buildCtxAttr(
         [{name: titleField}, {name: dateField}, {name: statusField}, {name: bodyField}].filter(f => f.name),
-        entries
+        entries,
+        ctxOpts
     );
     return `<div class="dm-collection-display dm-progression" data-layout="${layout}" data-theme="${theme}" data-mode="${mode}"${ctx}>\n${items}\n</div>`;
 }
@@ -629,7 +684,7 @@ function renderCollectionTimeline(entries, opts) {
  * @param {string} opts.emptyMsg
  * @returns {string}
  */
-function renderCollectionCarousel(entries, opts) {
+function renderCollectionCarousel(entries, opts, ctxOpts = {}) {
     const {imageField, titleField, bodyField, blockTemplate, blockName, blockCss, dataAttrs = {}, emptyMsg} = opts;
     if (!entries.length) {
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
@@ -663,7 +718,7 @@ function renderCollectionCarousel(entries, opts) {
     const ctxFields = blockTemplate
         ? blockTemplateFields(blockTemplate)
         : [{name: titleField}, {name: bodyField}].filter(f => f.name);
-    const ctx = buildCtxAttr(ctxFields, entries);
+    const ctx = buildCtxAttr(ctxFields, entries, ctxOpts);
     const styleTag = blockTemplate ? buildBlockStyleTag(blockName, blockCss) : '';
     return `${styleTag}<div class="dm-collection-display carousel"${passthrough}${ctx}><div class="carousel-track">${slides}</div></div>`;
 }
@@ -716,7 +771,7 @@ async function loadOptionalBlockAssets(blockName) {
     }
 }
 
-function renderCollectionListgroup(entries, opts) {
+function renderCollectionListgroup(entries, opts, ctxOpts = {}) {
     const {titleField, bodyField, variant, size, itemVariant, action, blockTemplate, blockName, blockCss, emptyMsg} = opts;
     if (!entries.length) {
         return `<div class="dm-collection-display dm-collection-empty"><p>${escapeHtmlText(emptyMsg)}</p></div>`;
@@ -756,7 +811,7 @@ function renderCollectionListgroup(entries, opts) {
     const ctxFields = blockTemplate
         ? blockTemplateFields(blockTemplate)
         : [{name: titleField}, {name: bodyField}].filter(f => f.name);
-    const ctx = buildCtxAttr(ctxFields, entries);
+    const ctx = buildCtxAttr(ctxFields, entries, ctxOpts);
     const styleTag = blockTemplate ? buildBlockStyleTag(blockName, blockCss) : '';
     return `${styleTag}<div class="${wrapperClasses.join(' ')}"${ctx}>\n${items}\n</div>`;
 }
@@ -825,6 +880,19 @@ async function processViewBlocks(markdown, tagSet) {
             // Map MongoDB docs to { id, data } shape. MongoAdapter docs have a top-level id field.
             const entries = results.map(doc => ({id: doc.id || '', data: doc.data || doc}));
 
+            // Resolve the view's underlying collection schema to compute export
+            // permission. Views don't own a schema themselves — [dis]allowing
+            // export must fall back CLOSED if the source collection can't be
+            // resolved, since an open fallback would be a permission bypass.
+            const sourceSlug = viewConfig?.pipeline?.source || '';
+            const sourceSchema = sourceSlug ? await getCollection(sourceSlug) : null;
+            const ctxOpts = sourceSchema
+                ? {
+                    slug: sourceSlug,
+                    export: resolveExportConfig(sourceSchema.export, attrs, getRoleHierarchy().at(-1))
+                }
+                : {slug: sourceSlug || undefined, export: {allowed: false, access: null, formats: []}};
+
             // Derive visible fields from attr filter or first entry's data keys
             let fields;
             if (fieldFilter?.length) {
@@ -840,14 +908,14 @@ async function processViewBlocks(markdown, tagSet) {
             const display = displayAttr || viewConfig?.display?.mode || 'table';
 
             if (display === 'cards') {
-                replacement = renderCollectionCards(entries, fields, titleField, columns, emptyMsg, ctaOpts);
+                replacement = renderCollectionCards(entries, fields, titleField, columns, emptyMsg, ctaOpts, ctxOpts);
             } else if (display === 'list') {
-                replacement = renderCollectionList(entries, fields, titleField, emptyMsg, ctaOpts);
+                replacement = renderCollectionList(entries, fields, titleField, emptyMsg, ctaOpts, ctxOpts);
             } else if (display === 'accordion') {
                 const accordionTitleField = attrs['title-field'] || 'title';
                 const bodyField           = attrs['body-field']  || 'description';
                 const multiple            = attrs.multiple === 'true';
-                replacement = renderCollectionAccordion(entries, accordionTitleField, bodyField, multiple, emptyMsg);
+                replacement = renderCollectionAccordion(entries, accordionTitleField, bodyField, multiple, emptyMsg, ctxOpts);
             } else if (display === 'timeline') {
                 const timelineLayout = ['vertical', 'centred', 'horizontal'].includes(attrs.layout) ? attrs.layout : 'vertical';
                 const timelineTheme  = ['minimal', 'corporate', 'modern'].includes(attrs.theme)   ? attrs.theme  : 'minimal';
@@ -862,7 +930,7 @@ async function processViewBlocks(markdown, tagSet) {
                     theme:  timelineTheme,
                     mode:   timelineMode,
                     emptyMsg,
-                });
+                }, ctxOpts);
             } else if (display === 'carousel') {
                 const {tpl, css, missing} = await loadOptionalBlockAssets(attrs.block);
                 replacement = missing
@@ -876,7 +944,7 @@ async function processViewBlocks(markdown, tagSet) {
                         blockCss: css,
                         dataAttrs: attrs,
                         emptyMsg,
-                    });
+                    }, ctxOpts);
             } else if (display === 'listgroup') {
                 const {tpl, css, missing} = await loadOptionalBlockAssets(attrs.block);
                 replacement = missing
@@ -892,7 +960,7 @@ async function processViewBlocks(markdown, tagSet) {
                         blockName: attrs.block || '',
                         blockCss: css,
                         emptyMsg,
-                    });
+                    }, ctxOpts);
             } else if (display === 'block') {
                 const blockName = attrs.block || viewConfig?.display?.block || '';
                 if (blockName) {
@@ -901,13 +969,13 @@ async function processViewBlocks(markdown, tagSet) {
                             loadBlockTemplate(blockName),
                             loadBlockCss(blockName),
                         ]);
-                        replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts, '', blockName, css);
+                        replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts, '', blockName, css, ctxOpts);
                     } catch {
                         replacement = blockNotFoundHtml(blockName);
                     }
                 }
             } else {
-                replacement = renderCollectionTable(`view:${slug}`, entries, fields, attrs, ctaOpts);
+                replacement = renderCollectionTable(`view:${slug}`, entries, fields, attrs, ctaOpts, ctxOpts);
             }
         } catch {
             // View not found or pipeline error — show empty state
@@ -1305,6 +1373,12 @@ export async function renderCollectionFragment(attrs, { extraFilter = null } = {
         const schema = await getCollection(slug);
         if (!schema) throw new Error('not found');
 
+        const defaultRole = getRoleHierarchy().at(-1);
+        const ctxOpts = {
+            slug: schema.slug,
+            export: resolveExportConfig(schema.export, attrs, defaultRole)
+        };
+
         const filter = buildShortcodeFilter(attrs);
         if (extraFilter) Object.assign(filter, extraFilter);
 
@@ -1327,14 +1401,14 @@ export async function renderCollectionFragment(attrs, { extraFilter = null } = {
         }
 
         if (display === 'cards') {
-            replacement = renderCollectionCards(entries, fields, titleField, columns, emptyMsg, ctaOpts);
+            replacement = renderCollectionCards(entries, fields, titleField, columns, emptyMsg, ctaOpts, ctxOpts);
         } else if (display === 'list') {
-            replacement = renderCollectionList(entries, fields, titleField, emptyMsg, ctaOpts);
+            replacement = renderCollectionList(entries, fields, titleField, emptyMsg, ctaOpts, ctxOpts);
         } else if (display === 'accordion') {
             const accordionTitleField = attrs['title-field'] || 'title';
             const bodyField           = attrs['body-field']  || 'description';
             const multiple            = attrs.multiple === 'true';
-            replacement = renderCollectionAccordion(entries, accordionTitleField, bodyField, multiple, emptyMsg);
+            replacement = renderCollectionAccordion(entries, accordionTitleField, bodyField, multiple, emptyMsg, ctxOpts);
         } else if (display === 'timeline') {
             const timelineLayout = ['vertical', 'centred', 'horizontal'].includes(attrs.layout) ? attrs.layout : 'vertical';
             const timelineTheme  = ['minimal', 'corporate', 'modern'].includes(attrs.theme)   ? attrs.theme  : 'minimal';
@@ -1349,7 +1423,7 @@ export async function renderCollectionFragment(attrs, { extraFilter = null } = {
                 theme:  timelineTheme,
                 mode:   timelineMode,
                 emptyMsg,
-            });
+            }, ctxOpts);
         } else if (display === 'carousel') {
             const {tpl, css, missing} = await loadOptionalBlockAssets(attrs.block);
             replacement = missing
@@ -1363,7 +1437,7 @@ export async function renderCollectionFragment(attrs, { extraFilter = null } = {
                     blockCss: css,
                     dataAttrs: attrs,
                     emptyMsg,
-                });
+                }, ctxOpts);
         } else if (display === 'listgroup') {
             const {tpl, css, missing} = await loadOptionalBlockAssets(attrs.block);
             replacement = missing
@@ -1379,7 +1453,7 @@ export async function renderCollectionFragment(attrs, { extraFilter = null } = {
                     blockName: attrs.block || '',
                     blockCss: css,
                     emptyMsg,
-                });
+                }, ctxOpts);
         } else if (display === 'block') {
             const blockName = attrs.block || '';
             if (blockName) {
@@ -1389,13 +1463,13 @@ export async function renderCollectionFragment(attrs, { extraFilter = null } = {
                         loadBlockCss(blockName),
                     ]);
                     const cols = attrs.cols || '';
-                    replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts, cols, blockName, css);
+                    replacement = renderCollectionBlocks(entries, tpl, emptyMsg, ctaOpts, cols, blockName, css, ctxOpts);
                 } catch {
                     replacement = blockNotFoundHtml(blockName);
                 }
             }
         } else {
-            replacement = renderCollectionTable(slug, entries, fields, attrs, ctaOpts);
+            replacement = renderCollectionTable(slug, entries, fields, attrs, ctaOpts, ctxOpts);
         }
     } catch {
         // Collection not found or read error — show empty message
@@ -3894,26 +3968,15 @@ async function processMenuBlocks(markdown, user, ctx = {}) {
 
         const depth = Number.parseInt(attrs.depth, 10);
         const capped = Number.isFinite(depth) && depth > 0 ? capDepth(items, depth) : items;
-        const klass        = attrs.class   ? ` ${escapeAttr(attrs.class)}`                    : '';
-        const variantClass = attrs.variant ? ` dm-menu--variant-${escapeAttr(attrs.variant)}` : '';
-        // Orientation: the shortcode attribute wins over the menu's own setting,
-        // so one placement can run horizontally while the menu is vertical in
-        // its slot. A menu that sets neither emits no orientation class at all
-        // and keeps the historic plain-nested-list rendering.
-        const orientation = ['horizontal', 'vertical'].includes(attrs.orientation)
-            ? attrs.orientation
-            : (['horizontal', 'vertical'].includes(menu.orientation) ? menu.orientation : null);
-        const orientClass = orientation ? ` dm-menu--${orientation}` : '';
         const decorated = await resolveMenuDecorations(capped);
-        // A floating menu pins itself to a viewport corner/edge. `float="no"`
-        // opts a single placement out, so the same menu can be floated in its
-        // slot yet rendered inline where the shortcode drops it.
-        const floatCss   = attrs.float === 'no' ? '' : floatToCss(menu);
-        const floatClass = floatCss ? ' dm-menu-floating' : '';
-        const floatAttrs = floatCss
-            ? ` style="${escapeAttr(floatCss)}" data-float-anchor="${escapeAttr(menu.float?.anchor || 'TL')}"`
-            : '';
-        const html = `<nav class="dm-menu dm-menu--${escapeAttr(menu.slug)}${orientClass}${variantClass}${floatClass}${klass}" data-menu="${escapeAttr(menu.slug)}"${floatAttrs}>${renderMenuItemsAsUl(decorated)}</nav>`;
+        // `orientation` overrides the menu for this one placement; `float="no"`
+        // renders inline here even when the menu floats in its slot.
+        const html = buildMenuNav(menu, decorated, {
+            orientation: attrs.orientation,
+            variant:     attrs.variant,
+            class:       attrs.class,
+            noFloat:     attrs.float === 'no'
+        });
         out = out.replace(m[0], html);
     }
     return out;
@@ -3942,32 +4005,6 @@ async function resolveProjectForUrl(urlPath) {
     }
 }
 
-function renderMenuItemsAsUl(items) {
-    if (!items.length) return '';
-    const lis = items.map(it => {
-        // Separator items render as a list-style <hr> divider.
-        if (it && it.type === 'separator') return '<li class="dm-menu-sep" role="separator"><hr></li>';
-        const href  = escapeAttr(it.url || '#');
-        const text  = escapeAttr(it.text || '');
-        const child = Array.isArray(it.items) && it.items.length ? renderMenuItemsAsUl(it.items) : '';
-
-        // Colour override (server sanitiser allows inline style on <a>).
-        const colourCss = it.colour ? colourToCss(it.colour) : '';
-        const styleAttr = colourCss ? ` style="color:${colourCss}"` : '';
-
-        // Badge (static text or resolver-stamped count). Background from variant.
-        let badge = '';
-        if (it.badge && it.badge.text != null && it.badge.text !== '') {
-            const bg = it.badge.variant ? colourToCss(it.badge.variant) : '';
-            const badgeStyle = bg ? ` style="background:${bg};color:#fff"` : '';
-            badge = `<span class="dm-menu-badge"${badgeStyle}>${escapeAttr(String(it.badge.text))}</span>`;
-        }
-
-        return `<li><a href="${href}"${styleAttr}>${text}${badge}</a>${child}</li>`;
-    }).join('');
-    return `<ul>${lis}</ul>`;
-}
-
 function capDepth(items, max, depth = 1) {
     return items.map(it => ({
         ...it,

package/server/services/menuRender.js

@@ -0,0 +1,90 @@
+/**
+ * Menu → HTML.
+ *
+ * One builder, three callers: the `[menu]` shortcode, the overlay menus the
+ * renderer injects into the page shell, and anything a plugin wants to render
+ * itself. Keeping it here means a menu looks the same however it reaches the
+ * page — the shortcode and an overlay binding of the same menu produce byte-
+ * identical markup.
+ *
+ * Item filtering (visibility, `hidden`), depth capping and badge-count
+ * resolution happen before this — callers hand in the items they want drawn.
+ */
+import {colourToCss, floatToCss} from './menus.js';
+
+/** Attribute-safe escaping — mirrors escapeAttr in markdown.js. */
+function esc(str) {
+    return String(str ?? '')
+        .replace(/&/g, '&')
+        .replace(/"/g, '"')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;');
+}
+
+/**
+ * Render a menu's items as a nested `<ul>`.
+ *
+ * Separators become a classed `<li><hr></li>`; colour, badge and nested
+ * children are drawn inline. Returns '' for an empty list so callers can
+ * decide whether an empty menu is worth a wrapper at all.
+ *
+ * @param   {Array} items
+ * @returns {string}
+ */
+export function renderMenuItemsAsUl(items) {
+    if (!items || !items.length) return '';
+    const lis = items.map(it => {
+        if (it && it.type === 'separator') return '<li class="dm-menu-sep" role="separator"><hr></li>';
+        const href  = esc(it.url || '#');
+        const text  = esc(it.text || '');
+        const child = Array.isArray(it.items) && it.items.length ? renderMenuItemsAsUl(it.items) : '';
+
+        // Colour override (the server sanitiser allows inline style on <a>).
+        const colourCss = it.colour ? colourToCss(it.colour) : '';
+        const styleAttr = colourCss ? ` style="color:${colourCss}"` : '';
+
+        // Badge — static text, or a count stamped on by resolveMenuDecorations.
+        let badge = '';
+        if (it.badge && it.badge.text != null && it.badge.text !== '') {
+            const bg = it.badge.variant ? colourToCss(it.badge.variant) : '';
+            const badgeStyle = bg ? ` style="background:${bg};color:#fff"` : '';
+            badge = `<span class="dm-menu-badge"${badgeStyle}>${esc(String(it.badge.text))}</span>`;
+        }
+
+        return `<li><a href="${href}"${styleAttr}>${text}${badge}</a>${child}</li>`;
+    }).join('');
+    return `<ul>${lis}</ul>`;
+}
+
+/**
+ * Build the full `<nav>` for a menu.
+ *
+ * @param {object} menu            The menu record (slug, orientation, position, float)
+ * @param {Array}  items           Items to draw — already filtered/capped/decorated
+ * @param {object} [opts]
+ * @param {string} [opts.orientation] Override the menu's own orientation for this placement
+ * @param {string} [opts.variant]     Adds `dm-menu--variant-<x>`
+ * @param {string} [opts.class]       Extra classes on the wrapper
+ * @param {boolean}[opts.noFloat]     Render inline even if the menu floats in its slot
+ * @returns {string}
+ */
+export function buildMenuNav(menu, items, opts = {}) {
+    const klass        = opts.class   ? ` ${esc(opts.class)}`                    : '';
+    const variantClass = opts.variant ? ` dm-menu--variant-${esc(opts.variant)}` : '';
+
+    // A menu that declares no orientation emits no class at all and keeps the
+    // historic plain-nested-list rendering.
+    const orientation = ['horizontal', 'vertical'].includes(opts.orientation)
+        ? opts.orientation
+        : (['horizontal', 'vertical'].includes(menu.orientation) ? menu.orientation : null);
+    const orientClass = orientation ? ` dm-menu--${orientation}` : '';
+
+    const floatCss   = opts.noFloat ? '' : floatToCss(menu);
+    const floatClass = floatCss ? ' dm-menu-floating' : '';
+    const floatAttrs = floatCss
+        ? ` style="${esc(floatCss)}" data-float-anchor="${esc(menu.float?.anchor || 'TL')}"`
+        : '';
+
+    return `<nav class="dm-menu dm-menu--${esc(menu.slug)}${orientClass}${variantClass}${floatClass}${klass}"`
+        + ` data-menu="${esc(menu.slug)}"${floatAttrs}>${renderMenuItemsAsUl(items)}</nav>`;
+}

package/server/services/menus.js

@@ -710,6 +710,11 @@ registerLocation('navbar',         {label: 'Navbar',         description: 'Site
 registerLocation('footer-primary', {label: 'Footer primary', description: 'Primary footer column', source: 'core', maxDepth: 1});
 registerLocation('footer-legal',   {label: 'Footer legal',   description: 'Legal/secondary footer column', source: 'core', maxDepth: 1});
 registerLocation('admin-sidebar',  {label: 'Admin sidebar',  description: 'The left-side navigation in the admin panel', source: 'core', maxDepth: null});
+// The overlay slot is the "anywhere" placement: menus bound to it render on
+// matching pages positioned by their own `float` config, with no navbar, no
+// footer and no shortcode involved. Unlike the other slots it is not
+// one-menu-wins — a page can carry several overlays at once.
+registerLocation('overlay',        {label: 'Page overlay',   description: 'Floating menus placed on matching pages by their binding', source: 'core', maxDepth: null});
 
 // ---------------------------------------------------------------------------
 // Slot → menu-slug map
@@ -904,6 +909,47 @@ export async function resolveLocation(slot, user, ctx = {}) {
     };
 }
 
+/** The slot whose menus are drawn over the page rather than in a fixed region. */
+export const OVERLAY_SLOT = 'overlay';
+
+/**
+ * Every overlay menu that applies to this page.
+ *
+ * Overlays are the "place a menu anywhere" path: instead of one menu winning a
+ * region, *all* menus whose binding matches the page render, each positioned by
+ * its own `float` config. A menu mapped to the overlay slot in
+ * menu-locations.json applies site-wide and joins the list.
+ *
+ * Menus left with no visible items after per-user filtering are dropped, so a
+ * fully gated overlay doesn't leave an empty box floating on the page.
+ *
+ * @param   {{urlPath?: string, project?: string|null}} ctx
+ * @param   {object|null} user
+ * @returns {Promise<object[]>} menus with filtered items, ordered by slug
+ */
+export async function resolveOverlaysForPage(ctx = {}, user = null) {
+    const bySlug = new Map();
+
+    for (const menu of await getAllMenus()) {
+        if (menu?.binding?.slot !== OVERLAY_SLOT) continue;
+        if (!scoreBinding(menu.binding, ctx)) continue;
+        bySlug.set(menu.slug, menu);
+    }
+
+    // A site-wide overlay: mapped rather than bound, so it needs no page rules.
+    const mappedSlug = (await getLocations())[OVERLAY_SLOT];
+    if (mappedSlug && !bySlug.has(mappedSlug)) {
+        const mapped = await getMenu(mappedSlug);
+        if (mapped) bySlug.set(mapped.slug, mapped);
+        else console.warn(`[menus] Overlay slot maps to "${mappedSlug}" which doesn't exist`);
+    }
+
+    return [...bySlug.values()]
+        .map(menu => ({...menu, items: filterItemsForUser(menu.items || [], user)}))
+        .filter(menu => menu.items.length > 0)
+        .sort((a, b) => String(a.slug).localeCompare(String(b.slug)));
+}
+
 function filterItemsForUser(items, user) {
     const out = [];
     for (const item of items) {