sol-components 2.1.0

package/core/form-utils.js

@@ -0,0 +1,210 @@
+// Environment-agnostic helpers for walking ui:Form definitions and
+// managing rdf:Collection data in an rdflib store. Used by both the
+// browser <sol-form> component and the Node.js sol-form API.
+
+import * as $rdf from 'rdflib';
+
+export const UI  = 'http://www.w3.org/ns/ui#';
+export const RDF = 'http://www.w3.org/1999/02/22-rdf-syntax-ns#';
+
+// Thin shim so the rest of the file reads the same whether the caller
+// passes the core/rdf.js singleton or raw rdflib.
+const rdf = {
+  sym:       (u) => $rdf.sym(u),
+  literal:   (v, d) => $rdf.literal(v, d),
+  blankNode: (id) => $rdf.blankNode(id),
+  Collection: $rdf.Collection,
+};
+
+export const MAX_DEPTH = 5;
+
+export function fieldType(store, field) {
+  const typeP = rdf.sym(RDF + 'type');
+  const types = store.each(field, typeP);
+  for (const t of types) {
+    if (t.value && t.value.startsWith(UI)) return t.value;
+  }
+  return UI + 'SingleLineTextField';
+}
+
+export function readFormParts(store, form) {
+  const node = store.any(form, rdf.sym(UI + 'parts'));
+  if (node && node.elements) return node.elements;
+  const alt = store.each(form, rdf.sym(UI + 'part'));
+  return alt.length ? alt : [];
+}
+
+export function readList(store, subject, property, doc) {
+  const val = store.any(subject, property, null, doc);
+  if (!val) return [];
+  if (val.elements) return [...val.elements];
+  const FIRST = rdf.sym(RDF + 'first'), REST = rdf.sym(RDF + 'rest'), NIL = rdf.sym(RDF + 'nil');
+  const result = [];
+  let cur = val;
+  while (cur && cur.termType === 'BlankNode') {
+    const f = store.any(cur, FIRST);
+    if (!f) break;
+    result.push(f);
+    const next = store.any(cur, REST);
+    if (!next || next.value === NIL.value) break;
+    cur = next;
+  }
+  return result;
+}
+
+export function syncCollection(store, subject, property, items, doc) {
+  for (const st of [...store.statementsMatching(subject, property, null, doc)]) {
+    if (st.object.termType === 'BlankNode') removeChain(store, st.object, doc);
+    store.remove(st);
+  }
+  if (!items.length) return;
+  const col = new (rdf.Collection)(items);
+  store.add(subject, property, col, doc);
+}
+
+export function removeChain(store, node, doc) {
+  const FIRST = rdf.sym(RDF + 'first'), REST = rdf.sym(RDF + 'rest');
+  let cur = node;
+  while (cur && cur.termType === 'BlankNode') {
+    const rests = store.statementsMatching(cur, REST, null, doc);
+    const next = rests.length ? rests[0].object : null;
+    for (const s of store.statementsMatching(cur, FIRST, null, doc)) store.remove(s);
+    for (const s of rests) store.remove(s);
+    if (!next || next.termType !== 'BlankNode') break;
+    cur = next;
+  }
+}
+
+export function removeItemData(store, item, doc) {
+  for (const st of [...store.statementsMatching(item, null, null, doc)]) {
+    if (st.object.termType === 'BlankNode') removeItemData(store, st.object, doc);
+    if (st.object.elements) {
+      for (const el of st.object.elements) {
+        if (el.termType === 'BlankNode') removeItemData(store, el, doc);
+      }
+    }
+  }
+  for (const s of [...store.statementsMatching(item, null, null, doc)]) store.remove(s);
+}
+
+export function setDefaults(store, form, subject, doc) {
+  for (const field of readFormParts(store, form)) {
+    const property = store.any(field, rdf.sym(UI + 'property'));
+    const dflt = store.any(field, rdf.sym(UI + 'default'));
+    if (!property || !dflt) continue;
+    const nn = store.anyValue(field, rdf.sym(UI + 'namedNode')) === 'true';
+    store.add(subject, property, nn ? rdf.sym(dflt.value) : rdf.literal(dflt.value), doc);
+  }
+}
+
+// Walk a form definition and populate an rdflib store from a plain JS
+// data object. Used by the Node.js programmatic API; the browser version
+// uses DOM-based rendering instead.
+export function populateStore(store, form, subject, doc, data, depth) {
+  if (!data || depth > MAX_DEPTH) return;
+  const fields = readFormParts(store, form);
+
+  for (const field of fields) {
+    const type = fieldType(store, field);
+    const property = store.any(field, rdf.sym(UI + 'property'));
+
+    if (type === UI + 'Form' || type === UI + 'Group') {
+      populateStore(store, field, subject, doc, data, depth);
+      continue;
+    }
+
+    if (type === UI + 'Options') {
+      const dependsOn = store.any(field, rdf.sym(UI + 'dependingOn'));
+      if (!dependsOn) continue;
+      const cur = store.any(subject, dependsOn, null, doc);
+      if (!cur) continue;
+      const cases = store.each(field, rdf.sym(UI + 'case'));
+      for (const c of cases) {
+        const forVal = store.any(c, rdf.sym(UI + 'for'));
+        if (forVal && forVal.value === cur.value) {
+          const useForm = store.any(c, rdf.sym(UI + 'use'));
+          if (useForm) populateStore(store, useForm, subject, doc, data, depth);
+          break;
+        }
+      }
+      continue;
+    }
+
+    if (!property) continue;
+    const localName = property.value.replace(/.*[/#]/, '');
+
+    if (type === UI + 'Multiple') {
+      const arr = data[localName];
+      if (!Array.isArray(arr) || !arr.length) continue;
+      const partForm = store.any(field, rdf.sym(UI + 'part'));
+      if (!partForm) continue;
+      const items = [];
+      for (const itemData of arr) {
+        const node = rdf.blankNode();
+        setDefaults(store, partForm, node, doc);
+        populateStore(store, partForm, node, doc, itemData, depth + 1);
+        items.push(node);
+      }
+      syncCollection(store, subject, property, items, doc);
+      continue;
+    }
+
+    if (type === UI + 'Choice') {
+      const val = data[localName];
+      for (const s of [...store.statementsMatching(subject, property, null, doc)]) store.remove(s);
+      if (val == null) {
+        const dflt = store.any(field, rdf.sym(UI + 'default'));
+        if (dflt) {
+          const nn = store.anyValue(field, rdf.sym(UI + 'namedNode')) === 'true';
+          store.add(subject, property, nn ? rdf.sym(dflt.value) : rdf.literal(dflt.value), doc);
+        }
+        continue;
+      }
+      const nn = store.anyValue(field, rdf.sym(UI + 'namedNode')) === 'true';
+      const resolved = nn ? resolveChoiceValue(store, field, String(val)) : null;
+      if (nn && resolved) {
+        store.add(subject, property, rdf.sym(resolved), doc);
+      } else {
+        store.add(subject, property, rdf.literal(String(val)), doc);
+      }
+      continue;
+    }
+
+    const val = data[localName];
+    for (const s of [...store.statementsMatching(subject, property, null, doc)]) store.remove(s);
+    if (val != null && String(val).trim()) {
+      store.add(subject, property, rdf.literal(String(val)), doc);
+    } else {
+      const dflt = store.anyValue(field, rdf.sym(UI + 'default'));
+      if (dflt) store.add(subject, property, rdf.literal(dflt), doc);
+    }
+  }
+}
+
+// Resolve a short Choice value (e.g. "ui:Link" or "Link") to the full
+// URI by matching against the declared ui:option values.
+function resolveChoiceValue(store, field, val) {
+  const opts = store.each(field, rdf.sym(UI + 'option'));
+  for (const opt of opts) {
+    if (opt.value === val) return val;
+    if (opt.value.endsWith('#' + val) || opt.value.endsWith('/' + val)) return opt.value;
+    const local = opt.value.replace(/.*[/#]/, '');
+    if (local === val) return opt.value;
+  }
+  if (val.includes(':') || val.includes('/')) return val;
+  return null;
+}
+
+// Find the first ui:Form node in a store, optionally matching a fragment.
+export function findForm(store, sourceUri) {
+  const formType = rdf.sym(UI + 'Form');
+  const typeP = rdf.sym(RDF + 'type');
+  const docUrl = sourceUri.split('#')[0];
+  const fragment = sourceUri.includes('#') ? sourceUri.split('#')[1] : null;
+  if (fragment) {
+    const candidate = rdf.sym(docUrl + '#' + fragment);
+    if (store.holds(candidate, typeP, formType)) return candidate;
+  }
+  const forms = store.each(null, typeP, formType);
+  return forms[0] || null;
+}

package/core/from-query.js

@@ -0,0 +1,138 @@
+// core/from-query.js — the `data-from-query` capability attribute (part of the
+// `sparql` capability). Makes ANY element query-driven WITHOUT pulling in the
+// <sol-query> component: it runs the query through the shared engine
+// (core/rdf-utils.js) and renders the result INTO the host element based on the
+// host's TAG — there is no `view` here. The split with <sol-query> is deliberate:
+//   • want swc to choose the view → use the <sol-query> element (view-driven)
+//   • want to choose yourself      → use this attribute (container-driven)
+//
+//   <ul data-from-query endpoint="data.ttl" sparql="SELECT ?name …"></ul>          <!-- → <li> per row -->
+//   <select data-from-query endpoint="…" sparql="SELECT ?label ?uri …"></select>   <!-- → <option> per row -->
+//   <div data-from-query endpoint="…" sparql="…"></div>                            <!-- no DOM: read el.swcData -->
+//
+// Output by host tag: <ul>/<ol> → one <li> per row; <select> → one <option> per
+// row (+ a `sol-select` event on change); anything else → nothing is rendered and
+// the W3C SPARQL 1.1 Query Results JSON is left on `el.swcData` for you to use.
+//
+// Config attributes (endpoint, pattern, sparql, query, var-<name>) may be written
+// bare OR `data-`-prefixed (data-endpoint, …, data-var-<name>) to keep the markup
+// spec-valid HTML; bare wins if both are given. `data-from-query` is the trigger.
+import { activate } from './activate.js';
+import { rdf } from './rdf.js';
+import { getAuthFetch } from './auth-fetch.js';
+import { substituteVariables, assertSafeQuery } from './sparql-safety.js';
+import { execSparql, loadRdfStore, parsePatternParts, matchStore, fetchQueryFromRdf } from './rdf-utils.js';
+
+// Config attributes may be written bare (`endpoint`) or `data-`-prefixed
+// (`data-endpoint`) — the latter keeps the host markup spec-valid HTML. Bare
+// wins when both are present. (`data-from-query` itself stays the trigger.)
+function attr(el, name) {
+  const v = el.getAttribute(name);
+  return v != null ? v : el.getAttribute('data-' + name);
+}
+function readVars(el) {
+  const vars = {};
+  // `var-foo` or `data-var-foo`; data-* is read first so a bare `var-foo` wins.
+  for (const a of Array.from(el.attributes)) if (a.name.indexOf('data-var-') === 0) vars[a.name.slice(9)] = a.value;
+  for (const a of Array.from(el.attributes)) if (a.name.indexOf('var-') === 0) vars[a.name.slice(4)] = a.value;
+  return vars;
+}
+function endpointsOf(el) {
+  const raw = attr(el, 'endpoint');
+  return raw ? raw.trim().split(/[\s,]+/).filter(Boolean) : [];
+}
+function isStoredRef(s) { return !/\s/.test(s) && /^https?:\/\/|^\/|^\.\.?\//.test(s.trim()); }
+
+// Build the W3C SPARQL Results JSON for the element's query config (same engine
+// the <sol-query> element uses: SPARQL via execSparql, triple-pattern via rdflib).
+async function buildData(el) {
+  const eps = endpointsOf(el);
+  if (!eps.length) throw new Error('data-from-query needs an `endpoint`');
+  const pattern = attr(el, 'pattern');
+  const sparql = attr(el, 'sparql') || attr(el, 'query') ||
+    (pattern ? '' : (el.getAttribute('data-from-query') || ''));
+
+  if (sparql) {
+    let q = isStoredRef(sparql) ? await fetchQueryFromRdf(sparql) : sparql;
+    q = substituteVariables(q, readVars(el));
+    assertSafeQuery(q);
+    const target = eps.length > 1 ? eps : eps[0];
+    const fetchUrl = Array.isArray(target) ? target[0] : target;
+    return execSparql(q, target, getAuthFetch(fetchUrl));
+  }
+  if (pattern) {
+    const store = await loadRdfStore(eps[0]);
+    const [s, p, o] = parsePatternParts(pattern, rdf, {}, eps[0]);
+    return matchStore(store, s, p, o);
+  }
+  throw new Error('data-from-query needs `sparql`, `query`, `pattern`, or a query value');
+}
+
+// ── render: the host's tag decides the shape (no `view`) ─────────────────────
+function cellText(cell) {
+  if (!cell) return '';
+  if (cell.type === 'uri') return cell.value.replace(/.*[/#]([^/#]+)\/?$/, '$1') || cell.value;
+  return cell.value ?? '';
+}
+function cellValue(cell) { return cell ? (cell.value ?? '') : ''; }
+
+// Display text for a row across however many SELECT variables there are.
+function rowText(vars, row) {
+  return vars.map((v) => cellText(row[v])).filter(Boolean).join(' — ');
+}
+
+function fillList(el, vars, rows) {
+  el.replaceChildren(...rows.map((row) => {
+    const li = document.createElement('li');
+    li.textContent = rowText(vars, row);
+    return li;
+  }));
+}
+
+function fillSelect(el, vars, rows) {
+  const opts = rows.map((row, i) => {
+    const opt = document.createElement('option');
+    // 1 col → text & value are the cell; 2 cols → text col0, value col1;
+    // 3+ cols → text "col0 — col1", value is the last column.
+    if (vars.length === 1)      { opt.textContent = cellText(row[vars[0]]); opt.value = cellValue(row[vars[0]]); }
+    else if (vars.length === 2) { opt.textContent = cellText(row[vars[0]]); opt.value = cellValue(row[vars[1]]); }
+    else { opt.textContent = `${cellText(row[vars[0]])} — ${cellText(row[vars[1]])}`; opt.value = cellValue(row[vars[vars.length - 1]]); }
+    opt.dataset.rowIndex = String(i);
+    return opt;
+  });
+  const placeholder = document.createElement('option');
+  placeholder.value = ''; placeholder.disabled = true; placeholder.selected = true;
+  placeholder.textContent = `— ${rows.length} result${rows.length === 1 ? '' : 's'} —`;
+  el.replaceChildren(placeholder, ...opts);
+  el._swcRows = rows;
+  if (!el._swcSelectWired) {                            // emit sol-select like the select view
+    el._swcSelectWired = true;
+    el.addEventListener('change', () => {
+      const chosen = el.options[el.selectedIndex];
+      const i = chosen ? parseInt(chosen.dataset.rowIndex, 10) : -1;
+      el.dispatchEvent(new CustomEvent('sol-select', {
+        bubbles: true, composed: true,
+        detail: { value: el.value, row: el._swcRows ? el._swcRows[i] : undefined, index: i },
+      }));
+    });
+  }
+}
+
+// The host's tag picks the shape. Unknown tags render nothing — the W3C JSON is
+// left on `el.swcData` for the page to consume.
+function renderInto(el, data) {
+  el.swcData = data;
+  const vars = data.head.vars;
+  const rows = data.results.bindings;
+  const tag = el.localName;
+  if (tag === 'ul' || tag === 'ol') return fillList(el, vars, rows);
+  if (tag === 'select')            return fillSelect(el, vars, rows);
+  // anything else: leave the DOM untouched; the JSON is on el.swcData.
+}
+
+activate('[data-from-query]', (el) => {
+  if (el.localName === 'sol-query') return;            // the element handles itself
+  buildData(el)
+    .then((data) => renderInto(el, data))
+    .catch((e) => { el.innerHTML = `<div class="error">${(e && e.message) || e}</div>`; console.error('[data-from-query]', e); });
+});

package/core/from-rdf.js

@@ -0,0 +1,52 @@
+// core/from-rdf.js — the `data-from-rdf` capability attribute (part of the `rdf`
+// capability). It LOADS RDF from a Turtle document (it does not render) and hands
+// the element the loaded data as a **W3C SPARQL 1.1 Query Results JSON** object —
+// the SAME format `data-from-query` returns — expressed as the document's triples
+// bound to `?s ?p ?o`. The calling component then does something with it.
+//
+// Delivery (symmetric with data-from-query's custom views): the object is set on
+// the element as `el.swcData`, and, if the element carries `view="…/view.js"`,
+// that module's `render(container, data, el)` is called with it. No built-in
+// rendering — `data-from-rdf` never paints HTML itself.
+import { activate } from './activate.js';
+import { rdf } from './rdf.js';
+
+function termToBinding(t) {
+  if (!t) return undefined;
+  if (t.termType === 'BlankNode') return { type: 'bnode', value: t.value };
+  if (t.termType === 'Literal') {
+    const b = { type: 'literal', value: t.value };
+    if (t.language) b['xml:lang'] = t.language;
+    else if (t.datatype && t.datatype.value &&
+             t.datatype.value !== 'http://www.w3.org/2001/XMLSchema#string') b.datatype = t.datatype.value;
+    return b;
+  }
+  return { type: 'uri', value: t.value };   // NamedNode
+}
+
+// The W3C SPARQL Results JSON envelope for a set of triples (vars s, p, o).
+function toW3C(statements) {
+  const bindings = statements.map((st) => ({
+    s: termToBinding(st.subject), p: termToBinding(st.predicate), o: termToBinding(st.object),
+  }));
+  return { head: { vars: ['s', 'p', 'o'] }, results: { bindings } };
+}
+
+activate('[data-from-rdf]', async (el) => {
+  const ref = el.getAttribute('data-from-rdf');
+  if (!ref) return;
+  const doc = new URL(ref, document.baseURI).href.split('#')[0];
+  try {
+    await rdf.load(doc);
+    const data = toW3C(rdf.store.statementsMatching(null, null, null, rdf.sym(doc)));
+    el.swcData = data;                                  // host component can read it
+    const view = el.getAttribute('view');
+    if (view) {
+      const mod = await import(new URL(view, document.baseURI).href);
+      const fn = mod.render ?? mod.default;
+      if (typeof fn === 'function') fn(el, data, el);    // (container, data, el)
+    }
+  } catch (e) {
+    console.error('[data-from-rdf] failed to load', doc, e);
+  }
+});

package/core/here.js

@@ -0,0 +1,33 @@
+// Resolve a sibling module URL that works in both ESM and IIFE/UMD contexts.
+//
+// Background: `import.meta.url` is the natural way to locate sibling modules,
+// but esbuild's IIFE output (used by podz when it bundles sol-components
+// source into a single script) flattens `import.meta.url` to `undefined`.
+// rollup's UMD output is the same. Result: dynamic-import paths like
+// `new URL('./sibling.js', import.meta.url)` silently break in those bundles.
+//
+// `siblingUrl(name, importMetaUrl)` accepts the caller's `import.meta.url`
+// (which the bundler may eat) and falls back through:
+//   1. import.meta.url             — when present (real ESM in the browser)
+//   2. document.currentScript.src  — when the host script is a classic <script>
+//   3. document.baseURI            — last-resort: the page's base URL
+//
+// Callers pass `import.meta.url` explicitly so the bundler can statically see
+// the use-site and substitute when it can; the fallback covers the rest.
+
+export function siblingUrl(name, importMetaUrl) {
+  // import.meta.url, when present, is always best.
+  if (importMetaUrl) {
+    try { return new URL(name, importMetaUrl).href; } catch {}
+  }
+  // Inside a classic <script> tag we have document.currentScript.
+  if (typeof document !== 'undefined') {
+    const cur = document.currentScript;
+    if (cur && cur.src) {
+      try { return new URL(name, cur.src).href; } catch {}
+    }
+    // Final fallback: resolve against the page itself.
+    try { return new URL(name, document.baseURI).href; } catch {}
+  }
+  return name;
+}

package/core/include-core.js

@@ -0,0 +1,73 @@
+let _marked = null;
+
+export async function getMarked() {
+  if (_marked) return _marked;
+  const g = typeof globalThis !== 'undefined' ? globalThis : {};
+  if (g.marked?.parse) { _marked = g.marked; return _marked; }
+  try {
+    const mod = await import('marked');
+    _marked = mod.marked ?? mod.default ?? mod;
+    return _marked;
+  } catch {}
+  return null;
+}
+
+export function detectIncludeFormat(contentType, url) {
+  const ct = (contentType || '').split(';')[0].trim();
+  const ext = url.split('?')[0].split('#')[0].split('.').pop().toLowerCase();
+  const isMarkdown = ct.includes('markdown') || ct.includes('text/x-markdown')
+                  || ['md', 'markdown'].includes(ext);
+  const isHtml = ct.includes('html') || ext === 'html' || ext === 'htm';
+  return { isMarkdown, isHtml };
+}
+
+/**
+ * Fetch a URL and return processed content.
+ * @param {string} source - URL to fetch
+ * @param {object} [opts]
+ * @param {boolean} [opts.raw] - return raw text without processing
+ * @param {boolean} [opts.trusted] - skip sanitization
+ * @param {function} [opts.sanitize] - async (html) => sanitized html
+ * @param {function} [opts.fetchFn] - fetch implementation
+ * @param {AbortSignal} [opts.signal] - cancel the underlying fetch
+ * @returns {Promise<{type: 'html'|'raw', content: string}>}
+ */
+export async function fetchIncludeContent(source, { raw = false, trusted = false, sanitize, fetchFn = globalThis.fetch, signal } = {}) {
+  const resp = await fetchFn(source, signal ? { signal } : undefined);
+  if (!resp.ok) throw new Error(`HTTP ${resp.status}`);
+  const ct = (resp.headers.get('content-type') || '').split(';')[0].trim();
+  const text = await resp.text();
+  const { isMarkdown, isHtml } = detectIncludeFormat(ct, source);
+
+  if (raw) return { type: 'raw', content: text };
+
+  if (isMarkdown) {
+    const markedLib = await getMarked();
+    if (!markedLib) throw new Error('marked library not available — add to importmap');
+    let html = typeof markedLib.parse === 'function' ? markedLib.parse(text) : markedLib(text);
+    if (!trusted && sanitize) html = await sanitize(html);
+    return { type: 'html', content: html };
+  }
+
+  if (isHtml) {
+    const html = (!trusted && sanitize) ? await sanitize(text) : text;
+    return { type: 'html', content: html };
+  }
+
+  return { type: 'raw', content: text };
+}
+
+/**
+ * Filter HTML with a CSS selector.
+ * @param {string} html - HTML string
+ * @param {string} selector - CSS selector
+ * @param {function} createContainer - (html) => DOM element with parsed content
+ * @returns {string|null} filtered HTML or null if no matches
+ */
+export function filterWithSelector(html, selector, createContainer) {
+  if (!selector) return html;
+  const container = createContainer(html);
+  const els = Array.from(container.querySelectorAll(selector));
+  if (!els.length) return null;
+  return els.map(el => el.outerHTML).join('\n');
+}

package/core/inrupt-global.js

@@ -0,0 +1,18 @@
+// core/inrupt-global.js — publish the inrupt Session class as the global
+// <sol-login> expects, from the manifest-mapped ESM build.
+//
+// <sol-login> reads the inrupt Session class from `window.solidClientAuthn`
+// (a UMD-style global) and throws if it is absent (see web/sol-login.js
+// getSessionClass). But the loader manifest maps
+// `@inrupt/solid-client-authn-browser` to an ESM build that sets no global, so
+// the `auth` capability could only work when the page ALSO loaded a separate
+// UMD <script> first. This shim imports the same mapped specifier and publishes
+// it at `window.solidClientAuthn`, so `data-extend-with="auth"` is self-contained
+// on every stage. It is listed BEFORE `sol-login` in the manifest's `auth`
+// capability, so the global is set by the time sol-login runs.
+import * as inrupt from '@inrupt/solid-client-authn-browser';
+
+if (typeof window !== 'undefined' && !window.solidClientAuthn) {
+  // sol-login looks up `.Session`; the ESM namespace exposes it directly.
+  window.solidClientAuthn = inrupt;
+}

package/core/menu-consumer.js

@@ -0,0 +1,41 @@
+// Shared registry of components that can consume a ui:Menu RDF document via
+// `from-rdf` (sol-tabs, sol-menu, and SolMenu subclasses like sol-dropdown-button).
+//
+// Kept deliberately rdflib-free: a base component registers itself here at module
+// load and otherwise stays declarative-only. The opt-in `web/menu-from-rdf.js`
+// add-on calls installFromRdfLoader() with the rdflib-backed loader; we then set
+// it on each consumer's static `fromRdfLoader`. Without that add-on imported,
+// `from-rdf` is inert and rdflib never enters the module graph.
+//
+// The registry lives on a Symbol.for() global (mirroring the solid-logic store
+// singleton) so a single page shares ONE registry even when the components and
+// the add-on arrive as separately-built UMD bundles, each with its own inlined
+// copy of this module. Wiring is order-independent: register-after-install and
+// install-after-register both end up wired.
+
+const KEY = Symbol.for('sol-components.menu-consumers');
+const reg = (globalThis[KEY] ||= { consumers: new Set(), loader: null, pending: new Set() });
+
+export function registerMenuConsumer(klass) {
+  reg.consumers.add(klass);
+  if (reg.loader) klass.fromRdfLoader = reg.loader;   // add-on already active
+}
+
+// Called by a component from `_loadFromRdf` when no loader is installed yet:
+// the element parks itself and renders nothing for now. If/when the add-on
+// arrives it is driven via reload() — so activation is order-independent (the
+// add-on may load before OR after the component, sync, deferred or as ESM).
+// Returns true when parked (caller should return), false if a loader is ready.
+export function deferUntilLoader(el) {
+  if (reg.loader) return false;
+  reg.pending.add(el);
+  return true;
+}
+
+export function installFromRdfLoader(loader) {
+  reg.loader = loader;
+  for (const klass of reg.consumers) klass.fromRdfLoader = loader;
+  const waiting = [...reg.pending];
+  reg.pending.clear();
+  for (const el of waiting) { try { el.reload?.(); } catch { /* el gone / not ready */ } }
+}