domma-cms 0.40.2 → 0.41.0

package/server/services/markdown.js

@@ -3828,16 +3828,20 @@ function processSlideoverBlocks(markdown) {
  *   [menu slug="my-menu" /]
  *   [menu location="navbar" /]
  *   [menu slug="..." depth="2" variant="..." class="..." /]
+ *   [menu slug="..." orientation="horizontal" /]
  *
  * Items flagged `hidden: true` are dropped. Items with a `visibility` field
  * are filtered against the supplied user via `checkVisibility`. The `depth`
  * attribute caps the nesting depth (1-indexed; depth="1" = top-level only).
+ * `orientation` overrides the menu's own setting for this one placement.
  *
  * @param {string} markdown
  * @param {object|null} user
+ * @param {{urlPath?: string, project?: string|null}} [ctx] - page context, so a
+ *   `location=` lookup honours menus bound to this page or project
  * @returns {Promise<string>}
  */
-async function processMenuBlocks(markdown, user) {
+async function processMenuBlocks(markdown, user, ctx = {}) {
     const re = /\[menu(\s+[^\]]*?)?\s*\/\]/gi;
     const matches = [...markdown.matchAll(re)];
     if (!matches.length) return markdown;
@@ -3847,7 +3851,7 @@ async function processMenuBlocks(markdown, user) {
         const attrs = parseShortcodeAttrs(m[1] || '');
         let menu = null;
         if (attrs.slug)          menu = await getMenu(attrs.slug);
-        else if (attrs.location) menu = await resolveLocation(attrs.location, user || null);
+        else if (attrs.location) menu = await resolveLocation(attrs.location, user || null, ctx);
         if (!menu) { out = out.replace(m[0], ''); continue; }
 
         // The slug path skipped resolveLocation, so filter visibility + hidden manually here.
@@ -3859,6 +3863,14 @@ async function processMenuBlocks(markdown, user) {
         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
@@ -3868,12 +3880,30 @@ async function processMenuBlocks(markdown, user) {
         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)}${variantClass}${floatClass}${klass}" data-menu="${escapeAttr(menu.slug)}"${floatAttrs}>${renderMenuItemsAsUl(decorated)}</nav>`;
+        const html = `<nav class="dm-menu dm-menu--${escapeAttr(menu.slug)}${orientClass}${variantClass}${floatClass}${klass}" data-menu="${escapeAttr(menu.slug)}"${floatAttrs}>${renderMenuItemsAsUl(decorated)}</nav>`;
         out = out.replace(m[0], html);
     }
     return out;
 }
 
+/**
+ * Project a URL belongs to, for menu-binding lookups. Dynamically imported so
+ * the markdown service keeps no load-time dependency on the projects service.
+ * Failures resolve to null — a missing project only means project bindings
+ * don't match, never a broken page.
+ *
+ * @param   {string} urlPath
+ * @returns {Promise<string|null>}
+ */
+async function resolveProjectForUrl(urlPath) {
+    try {
+        const {getProjectForPage} = await import('./projects.js');
+        return await getProjectForPage(urlPath);
+    } catch {
+        return null;
+    }
+}
+
 function renderMenuItemsAsUl(items) {
     if (!items.length) return '';
     const lis = items.map(it => {
@@ -3987,6 +4017,10 @@ function processCtaBlocks(markdown) {
  * @param {object|null} [opts.user] - Authenticated user (`{role, additionalRoles}`)
  *   or null for anonymous. Used to filter menu items gated by `visibility` in
  *   the `[menu]` shortcode. Backwards compatible — defaults to anonymous.
+ * @param {string} [opts.urlPath] - URL of the page being parsed. Lets
+ *   `[menu location="…"]` honour menus bound to this page or its project.
+ * @param {string|null} [opts.project] - Project the page belongs to; resolved
+ *   from `urlPath` when omitted.
  * @returns {{ data: object, content: string, html: string }}
  */
 export async function parseMarkdown(raw, opts = {}) {
@@ -4003,7 +4037,10 @@ export async function parseMarkdown(raw, opts = {}) {
   const withCollection = await processCollectionBlocks(withComponents, tagSet);
   const withView = await processViewBlocks(withCollection, tagSet);
   const withStaticBlock = await processStaticBlocks(withView, tagSet);
-  const withMenu = await processMenuBlocks(withStaticBlock, opts.user || null);
+  const menuCtx = opts.urlPath
+      ? {urlPath: opts.urlPath, project: opts.project ?? await resolveProjectForUrl(opts.urlPath)}
+      : {};
+  const withMenu = await processMenuBlocks(withStaticBlock, opts.user || null, menuCtx);
   const withDconfig = processDConfigBlocks(withMenu);
     const withEffects = processEffectsBlocks(withDconfig);
     const withPluginShortcodes = await processPluginShortcodes(withEffects);

package/server/services/menus-migration.js

@@ -12,6 +12,7 @@
 import fs from 'fs/promises';
 import path from 'path';
 import {fileURLToPath} from 'url';
+import {invalidateMenuIndex} from './menus.js';
 
 const __filename = fileURLToPath(import.meta.url);
 const DEFAULT_CONFIG_DIR = path.resolve(path.dirname(__filename), '..', '..', 'config');
@@ -27,6 +28,9 @@ async function readJson(p) {
 
 async function writeJson(p, data) {
     await fs.writeFile(p, JSON.stringify(data, null, 2) + '\n', 'utf8');
+    // Menu files written outside the menus service — drop its cached index so
+    // binding resolution sees the migrated menus.
+    invalidateMenuIndex();
 }
 
 /**

package/server/services/menus.js

@@ -94,12 +94,54 @@ export const FLOAT_ANCHORS = new Set(['TL', 'TR', 'BL', 'BR', 'L', 'R']);
 
 export const FLOAT_DEFAULTS = {anchor: 'TL', offsetX: 16, offsetY: 16, zIndex: 150};
 
+// Panel surface options for a floating menu. Each maps to a theme token rather
+// than a literal, so a floating panel still tracks the active theme.
+// Keep FLOAT_SHADOWS / floatSurfaceCss in sync with public/js/menu-decor.mjs.
+export const FLOAT_SHADOWS = {
+    none: 'none',
+    sm:   'var(--dm-shadow-sm)',
+    md:   'var(--dm-shadow-md)',
+    lg:   'var(--dm-shadow-lg)',
+    xl:   'var(--dm-shadow-xl)'
+};
+
 function floatNumber(value, fallback, min, max) {
     const n = Number(value);
     if (!Number.isFinite(n)) return fallback;
     return Math.min(max, Math.max(min, Math.round(n)));
 }
 
+/**
+ * Surface declarations for a floating panel — corner rounding, drop shadow and
+ * accent colour. Everything is optional: an omitted field falls through to the
+ * `.dm-menu-floating` defaults in site.css rather than being frozen inline.
+ *
+ * The accent both tints the border and publishes `--dm-menu-accent`, which
+ * site.css uses to draw the leading edge stripe.
+ *
+ * @param   {object} f - the menu's `float` block
+ * @returns {string[]} CSS declarations
+ */
+function floatSurfaceCss(f) {
+    const decls = [];
+    if (f.radius != null && f.radius !== '') {
+        decls.push(`border-radius:${floatNumber(f.radius, 8, 0, 48)}px`);
+    }
+    if (f.shadow != null && f.shadow !== '' && Object.prototype.hasOwnProperty.call(FLOAT_SHADOWS, f.shadow)) {
+        decls.push(`box-shadow:${FLOAT_SHADOWS[f.shadow]}`);
+    }
+    if (f.accent && isValidColour(f.accent)) {
+        const css = colourToCss(f.accent);
+        decls.push(`--dm-menu-accent:${css}`, `border-color:${css}`);
+    }
+    if (f.opacity != null && f.opacity !== '') {
+        // Panel translucency, not item translucency — the backdrop filter in
+        // site.css keeps the text readable over busy page content.
+        decls.push(`--dm-menu-panel-opacity:${floatNumber(f.opacity, 100, 20, 100) / 100}`);
+    }
+    return decls;
+}
+
 /**
  * Build the inline CSS for a floating menu. Returns '' for any menu that is
  * not floating, so callers can apply it unconditionally.
@@ -137,9 +179,70 @@ export function floatToCss(menu) {
     // A pinned panel must never grow past the viewport — it scrolls instead.
     decls.push(`max-height:calc(100vh - ${(anchor === 'L' || anchor === 'R') ? 32 : y * 2}px)`);
 
+    decls.push(...floatSurfaceCss(f));
+
     return decls.join(';');
 }
 
+// ---------------------------------------------------------------------------
+// Orientation — how the menu flows where it renders. `horizontal` is the
+// historic behaviour and stays the default for every menu without the field.
+// `vertical` stacks the items into a column: a side rail for the navbar slot,
+// a stacked list for `[menu]` and floating panels.
+//
+// `side` only means anything for a vertical menu in the navbar slot — it picks
+// the viewport edge the rail docks to.
+// ---------------------------------------------------------------------------
+export const ORIENTATIONS = new Set(['horizontal', 'vertical']);
+export const SIDES        = new Set(['left', 'right']);
+
+// ---------------------------------------------------------------------------
+// Bindings — a menu can claim a slot for a subset of the site instead of being
+// mapped to it globally in menu-locations.json. `binding.slot` names the slot
+// it takes over; `binding.projects` and `binding.pages` say where.
+//
+//   {"slot": "navbar", "projects": ["shop"], "pages": ["/about", "/docs/*"]}
+//
+// Match precedence (see resolveBoundMenu): an exact page URL beats a page glob,
+// a page glob beats a project, and any binding beats the menu-locations
+// default. Ties break on the longest pattern, then slug, so resolution is
+// deterministic regardless of directory order.
+// ---------------------------------------------------------------------------
+
+/** A page pattern is a URL path, optionally ending in a `/*` wildcard. */
+const PAGE_PATTERN_RE = /^\/(?:[^\s?#*]*)?(?:\/\*)?$|^\/\*$/;
+
+/** True if `pattern` is a well-formed page pattern. */
+export function isValidPagePattern(pattern) {
+    return typeof pattern === 'string' && pattern !== '' && PAGE_PATTERN_RE.test(pattern);
+}
+
+/**
+ * Match a page pattern against a URL path.
+ *
+ * `/about`   matches only `/about`.
+ * `/docs/*`  matches `/docs` and everything beneath it.
+ * `/*`       matches every page.
+ *
+ * Trailing slashes on the URL are ignored (`/about/` === `/about`), matching
+ * how the public router resolves pages.
+ *
+ * @param   {string} pattern
+ * @param   {string} urlPath
+ * @returns {boolean}
+ */
+export function matchesPagePattern(pattern, urlPath) {
+    if (typeof pattern !== 'string' || typeof urlPath !== 'string') return false;
+    const url = urlPath.length > 1 ? urlPath.replace(/\/+$/, '') : urlPath;
+    if (pattern === '/*') return true;
+    if (pattern.endsWith('/*')) {
+        const prefix = pattern.slice(0, -2) || '/';
+        return url === prefix || url.startsWith(prefix === '/' ? '/' : prefix + '/');
+    }
+    const exact = pattern.length > 1 ? pattern.replace(/\/+$/, '') : pattern;
+    return url === exact;
+}
+
 /**
  * Walk a menu tree and resolve live badge counts. For any item whose
  * `badge.countFrom` names a collection, the entry count replaces `badge.text`.
@@ -196,6 +299,7 @@ async function readMenuFile(slug) {
 async function writeMenuFile(menu) {
     await ensureMenusDir();
     await fs.writeFile(menuPath(menu.slug), JSON.stringify(menu, null, 2) + '\n', 'utf8');
+    invalidateMenuIndex();
     // Menu content / behaviour / style changed — drop the cached public pages.
     await invalidateNavCache();
 }
@@ -222,6 +326,7 @@ export async function listMenus() {
                 name:        menu.name || '',
                 description: menu.description || '',
                 itemsCount:  Array.isArray(menu.items) ? menu.items.length : 0,
+                ...(menu.binding && {binding: menu.binding}),
                 meta:        menu.meta || {}
             });
         } catch (err) {
@@ -262,7 +367,10 @@ export async function createMenu(input) {
     if (await getMenu(input.slug)) {
         throw new Error(`Menu "${input.slug}" already exists`);
     }
-    const errors = validateMenu(input);
+    // Normalise the binding first so validation judges what will actually be
+    // written — surrounding whitespace and duplicates are tidied, not rejected.
+    const binding = normaliseBinding(input.binding);
+    const errors = validateMenu({...input, binding});
     if (errors.length) {
         throw new Error('Validation failed: ' + errors.join('; '));
     }
@@ -273,9 +381,12 @@ export async function createMenu(input) {
         description: input.description || '',
         ...(input.variant  != null && {variant:  input.variant}),
         ...(input.position != null && {position: input.position}),
+        ...(input.orientation != null && {orientation: input.orientation}),
+        ...(input.side     != null && {side:     input.side}),
         ...(input.appearOnHover != null && {appearOnHover: !!input.appearOnHover}),
         ...(input.float    != null && {float:    input.float}),
         ...(input.style    != null && {style:    input.style}),
+        ...(binding != null && {binding}),
         items: Array.isArray(input.items) ? input.items : [],
         meta: {
             createdAt:   now,
@@ -301,7 +412,8 @@ export async function createMenu(input) {
 export async function updateMenu(slug, input) {
     const existing = await getMenu(slug);
     if (!existing) throw new Error(`Menu "${slug}" not found`);
-    const errors = validateMenu({...input, slug});
+    const binding = normaliseBinding(input.binding);
+    const errors = validateMenu({...input, slug, binding});
     if (errors.length) {
         throw new Error('Validation failed: ' + errors.join('; '));
     }
@@ -312,9 +424,12 @@ export async function updateMenu(slug, input) {
         description: input.description || '',
         ...(input.variant  != null && {variant:  input.variant}),
         ...(input.position != null && {position: input.position}),
+        ...(input.orientation != null && {orientation: input.orientation}),
+        ...(input.side     != null && {side:     input.side}),
         ...(input.appearOnHover != null && {appearOnHover: !!input.appearOnHover}),
         ...(input.float    != null && {float:    input.float}),
         ...(input.style    != null && {style:    input.style}),
+        ...(binding != null && {binding}),
         items: Array.isArray(input.items) ? input.items : [],
         meta: {
             ...existing.meta,
@@ -339,6 +454,7 @@ export async function deleteMenu(slug) {
     if (!validateSlug(slug)) return false;
     try {
         await fs.unlink(menuPath(slug));
+        invalidateMenuIndex();
         await invalidateNavCache();
         return true;
     } catch (err) {
@@ -367,6 +483,9 @@ export async function duplicateMenu(slug) {
         ...source,
         slug: candidate,
         name: source.name + ' (copy)',
+        // Bindings are deliberately NOT copied: two menus claiming the same
+        // slot on the same pages is a conflict the admin never asked for.
+        binding: null,
         meta: {bundled: false, presetOwner: null}
     });
 }
@@ -374,6 +493,32 @@ export async function duplicateMenu(slug) {
 const POSITIONS = new Set(['sticky', 'fixed', 'static', 'floating']);
 const URL_PREFIX_RE = /^(\/|#|https?:\/\/|mailto:)/;
 
+/**
+ * Coerce a binding block into its persisted shape: a slot plus de-duplicated,
+ * trimmed project/page lists. Empty lists are dropped so a binding that targets
+ * nothing doesn't linger in the file as noise.
+ *
+ * @param   {object} binding
+ * @returns {object|undefined} undefined when the binding claims no slot
+ */
+function normaliseBinding(binding) {
+    if (!binding || typeof binding !== 'object' || Array.isArray(binding)) return undefined;
+    const slot = typeof binding.slot === 'string' ? binding.slot.trim() : '';
+    if (!slot) return undefined;
+    const clean = (list) => [...new Set(
+        (Array.isArray(list) ? list : [])
+            .map(v => typeof v === 'string' ? v.trim() : '')
+            .filter(Boolean)
+    )];
+    const projects = clean(binding.projects);
+    const pages    = clean(binding.pages);
+    return {
+        slot,
+        ...(projects.length && {projects}),
+        ...(pages.length    && {pages})
+    };
+}
+
 /**
  * Validate a menu object. Returns an array of human-readable error strings
  * (empty on success). Performs structural + per-item recursive checks; does
@@ -394,6 +539,38 @@ export function validateMenu(menu) {
     if (menu.position != null && !POSITIONS.has(menu.position)) {
         errors.push(`Invalid position "${menu.position}" — expected one of: ${[...POSITIONS].join(', ')}`);
     }
+    if (menu.orientation != null && !ORIENTATIONS.has(menu.orientation)) {
+        errors.push(`Invalid orientation "${menu.orientation}" — expected one of: ${[...ORIENTATIONS].join(', ')}`);
+    }
+    if (menu.side != null && !SIDES.has(menu.side)) {
+        errors.push(`Invalid side "${menu.side}" — expected one of: ${[...SIDES].join(', ')}`);
+    }
+    if (menu.binding != null) {
+        if (typeof menu.binding !== 'object' || Array.isArray(menu.binding)) {
+            errors.push('binding must be an object');
+        } else {
+            const {slot, projects, pages} = menu.binding;
+            // A binding with no slot is inert rather than invalid — the admin
+            // sends an empty block when the feature is switched off — but a
+            // slot that IS present has to be a usable slot name.
+            if (slot != null && slot !== '' && !validateSlug(slot)) {
+                errors.push(`binding.slot "${slot}" — lowercase alphanumeric + hyphen only`);
+            }
+            for (const [key, list] of [['projects', projects], ['pages', pages]]) {
+                if (list == null) continue;
+                if (!Array.isArray(list)) { errors.push(`binding.${key} must be an array`); continue; }
+                for (const v of list) {
+                    if (typeof v !== 'string') { errors.push(`binding.${key} entries must be strings`); continue; }
+                    if (key === 'projects' && !validateSlug(v)) {
+                        errors.push(`binding.projects "${v}" is not a valid project slug`);
+                    }
+                    if (key === 'pages' && !isValidPagePattern(v)) {
+                        errors.push(`binding.pages "${v}" must be a URL path, optionally ending in /*`);
+                    }
+                }
+            }
+        }
+    }
     if (menu.float != null) {
         if (typeof menu.float !== 'object' || Array.isArray(menu.float)) {
             errors.push('float must be an object');
@@ -401,12 +578,19 @@ export function validateMenu(menu) {
             if (menu.float.anchor != null && !FLOAT_ANCHORS.has(menu.float.anchor)) {
                 errors.push(`float.anchor must be one of: ${[...FLOAT_ANCHORS].join(', ')}`);
             }
-            for (const key of ['offsetX', 'offsetY', 'width', 'zIndex']) {
+            for (const key of ['offsetX', 'offsetY', 'width', 'zIndex', 'radius', 'opacity']) {
                 const v = menu.float[key];
                 if (v != null && v !== '' && !Number.isFinite(Number(v))) {
                     errors.push(`float.${key} must be a number`);
                 }
             }
+            if (menu.float.shadow != null && menu.float.shadow !== ''
+                && !Object.prototype.hasOwnProperty.call(FLOAT_SHADOWS, menu.float.shadow)) {
+                errors.push(`float.shadow must be one of: ${Object.keys(FLOAT_SHADOWS).join(', ')}`);
+            }
+            if (menu.float.accent != null && menu.float.accent !== '' && !isValidColour(menu.float.accent)) {
+                errors.push('float.accent must be a preset key or #rrggbb');
+            }
         }
     }
     if (!Array.isArray(menu.items)) {
@@ -578,25 +762,141 @@ export async function setLocations(map) {
 // ---------------------------------------------------------------------------
 
 /**
- * Resolve the menu mapped to `slot` for `user`, with items filtered by
- * `hidden` (always dropped) and `visibility` (per-user role gating).
- * Returns null if the slot is unmapped or the mapped menu is missing.
+ * Every menu on disk, cached in memory. Bound-menu resolution has to consider
+ * all of them on each render, and the alternative — re-reading the directory
+ * three times per uncached page — is wasteful for a set of files that only
+ * changes when an admin saves a menu.
+ *
+ * Every write path in this module invalidates the cache; anything writing menu
+ * files directly (the boot migrations) must call `invalidateMenuIndex()`.
+ */
+let _menuIndex = null;
+
+/** Drop the cached menu index — call after writing menu files out-of-band. */
+export function invalidateMenuIndex() {
+    _menuIndex = null;
+}
+
+/**
+ * Read every menu file, memoised. Malformed files are skipped with a warning,
+ * exactly as listMenus() does.
+ *
+ * @returns {Promise<object[]>} full menu records, sorted by slug
+ */
+export async function getAllMenus() {
+    if (_menuIndex) return _menuIndex;
+    await ensureMenusDir();
+    const files = await fs.readdir(MENUS_DIR);
+    const out = [];
+    for (const file of files) {
+        if (!file.endsWith('.json')) continue;
+        const slug = file.slice(0, -5);
+        if (!validateSlug(slug)) continue;
+        try {
+            out.push(await readMenuFile(slug));
+        } catch (err) {
+            console.warn(`[menus] Skipping malformed menu "${slug}": ${err.message}`);
+        }
+    }
+    out.sort((a, b) => String(a.slug).localeCompare(String(b.slug)));
+    _menuIndex = out;
+    return out;
+}
+
+// Match strengths, most specific first. Exact page > page glob > project.
+const MATCH_PAGE_EXACT = 3;
+const MATCH_PAGE_GLOB  = 2;
+const MATCH_PROJECT    = 1;
+
+/**
+ * Score a menu's binding against the current page context.
+ *
+ * @param   {object} binding
+ * @param   {{urlPath?: string, project?: string|null}} ctx
+ * @returns {{strength: number, specificity: number}|null} null when it doesn't apply
+ */
+function scoreBinding(binding, ctx) {
+    let strength    = 0;
+    let specificity = 0;
+    if (ctx.urlPath) {
+        for (const pattern of binding.pages || []) {
+            if (!matchesPagePattern(pattern, ctx.urlPath)) continue;
+            const s = pattern.endsWith('/*') ? MATCH_PAGE_GLOB : MATCH_PAGE_EXACT;
+            if (s > strength || (s === strength && pattern.length > specificity)) {
+                strength    = s;
+                specificity = Math.max(specificity, pattern.length);
+            }
+        }
+    }
+    if (strength === 0 && ctx.project && (binding.projects || []).includes(ctx.project)) {
+        strength    = MATCH_PROJECT;
+        specificity = ctx.project.length;
+    }
+    return strength ? {strength, specificity} : null;
+}
+
+/**
+ * Find the menu whose binding claims `slot` for this page, if any.
+ *
+ * Bindings are how a menu takes a slot over for part of the site: the project
+ * a page belongs to, or a list of page URL patterns. The most specific match
+ * wins (exact page > page glob > project); ties break on the longest pattern
+ * and then the slug, so the result never depends on directory order.
+ *
+ * @param   {string} slot
+ * @param   {{urlPath?: string, project?: string|null}} [ctx]
+ * @returns {Promise<object|null>} the winning menu record, or null
+ */
+export async function resolveBoundMenu(slot, ctx = {}) {
+    if (!slot || (!ctx.urlPath && !ctx.project)) return null;
+    let best = null;
+    let bestScore = null;
+    for (const menu of await getAllMenus()) {
+        if (menu?.binding?.slot !== slot) continue;
+        const score = scoreBinding(menu.binding, ctx);
+        if (!score) continue;
+        const better = !bestScore
+            || score.strength > bestScore.strength
+            || (score.strength === bestScore.strength && score.specificity > bestScore.specificity)
+            || (score.strength === bestScore.strength && score.specificity === bestScore.specificity
+                && String(menu.slug) < String(best.slug));
+        if (better) {
+            best      = menu;
+            bestScore = score;
+        }
+    }
+    return best;
+}
+
+/**
+ * Resolve the menu that should render in `slot` for `user`, with items filtered
+ * by `hidden` (always dropped) and `visibility` (per-user role gating).
+ * Returns null if nothing claims the slot or the mapped menu is missing.
+ *
+ * A menu bound to the current page or project (see `resolveBoundMenu`) takes
+ * the slot over; otherwise the `menu-locations.json` mapping applies. Callers
+ * that know the page they are rendering should pass `ctx` — without it only the
+ * global mapping is considered, which is the pre-binding behaviour.
  *
  * Note: `user` may be null (anonymous). `user.role` and
  * `user.additionalRoles` are honoured via `checkVisibility`.
  *
  * @param {string} slot
  * @param {object|null} user
+ * @param {{urlPath?: string, project?: string|null}} [ctx] - current page context
  * @returns {Promise<object|null>}
  */
-export async function resolveLocation(slot, user) {
-    const map = await getLocations();
-    const slug = map[slot];
-    if (!slug) return null;
-    const menu = await getMenu(slug);
+export async function resolveLocation(slot, user, ctx = {}) {
+    let menu = await resolveBoundMenu(slot, ctx);
     if (!menu) {
-        console.warn(`[menus] Slot "${slot}" maps to "${slug}" which doesn't exist`);
-        return null;
+        const map  = await getLocations();
+        const slug = map[slot];
+        if (!slug) return null;
+        menu = await getMenu(slug);
+        if (!menu) {
+            console.warn(`[menus] Slot "${slot}" maps to "${slug}" which doesn't exist`);
+            return null;
+        }
     }
     return {
         ...menu,