sol-components 2.1.0

package/core/rdf-utils.js

@@ -0,0 +1,411 @@
+// All RDF operations for sol-query.
+// Adapters (SPARQL execution), store loading, triple-pattern matching.
+
+import {
+  sanitizeHtml,
+  toPlainResults,
+  ComunicaSparqlAdapter,
+  NativeSparqlAdapter,
+} from './utils.js';
+import { rdf } from './rdf.js';
+
+// Re-export pure-logic functions from rdf-core so existing importers
+// (sol-query.js, views, tests) continue to work unchanged.
+export {
+  KNOWN_PREFIXES,
+  ACCEPT_TYPES,
+  detectFormat,
+  termToString,
+  termToCell,
+  expandCurie,
+  knownPrefixesAsSparql,
+  w3cResults,
+  _NAMED_VAR_RE,
+  triplePatternTermToNode,
+  tokenizeTriplePattern,
+  parsePatternParts,
+  patternVarNames,
+  matchStore,
+  selectVars as _selectVars,
+  isRdfDoc as _isRdfDoc,
+} from './rdf-core.js';
+
+import {
+  ACCEPT_TYPES,
+  detectFormat,
+  termToCell,
+  parsePatternParts,
+  matchStore,
+  patternVarNames,
+  selectVars as _selectVars,
+  isRdfDoc as _isRdfDoc,
+  bindingsToResults,
+  w3cResults,
+} from './rdf-core.js';
+
+// Re-export the rdf singleton so downstream can import either symbol
+export { rdf };
+
+// Re-export sanitizeHtml so downstream (sol-include) can import from here or utils
+export { sanitizeHtml };
+// Re-export queryHtmlWithSelector for sol-query.js
+export { queryHtmlWithSelector } from './utils.js';
+
+// Backwards-compatible alias (deprecated — prefer triplePatternTermToNode).
+export { triplePatternTermToNode as miniTermToNode } from './rdf-core.js';
+
+// ─── Store loading ───────────────────────────────────────────────────────────
+
+export async function loadRdfStore(endpoint, fetchFn = fetch, opts = {}) {
+  if (!rdf.isReady()) throw new Error('rdflib not available');
+  const rdflib = rdf;
+
+  // Parsers (notably JSON-LD) require an absolute base IRI, so resolve relative
+  // endpoints against the current document before handing them to rdflib.parse.
+  try { endpoint = new URL(endpoint, document.baseURI).href; } catch {}
+
+  // shared=true routes parsing into rdf.store (the singleton shared with
+  // solid-logic/solid-ui/mashlib) and dedupes subsequent loads of the same
+  // URL. Intended for stored-query RDF libraries where many <sol-query>
+  // elements reference the same .ttl file.
+  //
+  // Cache reads are unconditional: once a URL is in the singleton (because
+  // some earlier caller asked for shared), every subsequent load hits the
+  // cache regardless of opts. Cache writes still require shared, so callers
+  // can't pollute the singleton without opting in.
+  const shared = !!opts.shared;
+  if (rdf.isLoaded(endpoint)) return rdf.store;
+
+  const store = shared ? rdf.store : rdflib.graph();
+  const diagnostics = [];
+  let lastError = null;
+  const markOk = () => { if (shared) rdf.markLoaded(endpoint); };
+
+  // Attempt each Accept type; 405 Method-Not-Allowed is fatal (wrong HTTP method),
+  // everything else (including 501) just moves on to the next type.
+  for (const accept of ACCEPT_TYPES) {
+    try {
+      const resp = await fetchFn(endpoint, { headers: { Accept: accept } });
+      diagnostics.push({ accept, status: resp.status, contentType: resp.headers.get('content-type') });
+
+      if (!resp.ok) {
+        lastError = new Error(`HTTP ${resp.status}`);
+        if (resp.status === 405) break;   // method not supported — no point retrying
+        continue;
+      }
+
+      const text = await resp.text();
+      const ct = (resp.headers.get('content-type') || '').split(';')[0].trim();
+      if (ct.includes('html') || /<html/i.test(text)) {
+        // Try RDFa parsing; tag store so callers know it came from HTML
+        try {
+          const clean = await sanitizeHtml(text, { WHOLE_DOCUMENT: true, FORCE_BODY: false });
+          rdflib.parse(clean, store, endpoint, 'text/html');
+          store._isHtml   = true;
+          store._rawHtml  = clean;
+          store._diagnostics = diagnostics;
+          markOk();
+          return store;
+        } catch (rdfa) {
+          lastError = new Error(`Server returned HTML (${ct})`);
+          continue;
+        }
+      }
+
+      try {
+        rdflib.parse(text, store, endpoint, detectFormat(ct, accept));
+        store._diagnostics = diagnostics;
+        markOk();
+        return store;
+      } catch (parseErr) {
+        lastError = parseErr;
+        diagnostics.push({ accept, parseError: parseErr.message });
+      }
+    } catch (err) {
+      diagnostics.push({ accept, error: err.message });
+      lastError = err;
+    }
+  }
+
+  // Last resort: no Accept header (plain fetch, let server decide content-type)
+  try {
+    const resp = await fetchFn(endpoint);
+    if (resp.ok) {
+      const text = await resp.text();
+      const ct = (resp.headers.get('content-type') || '').split(';')[0].trim();
+      if (ct.includes('html') || /<html/i.test(text)) {
+        try {
+          const clean = await sanitizeHtml(text, { WHOLE_DOCUMENT: true, FORCE_BODY: false });
+          rdflib.parse(clean, store, endpoint, 'text/html');
+          store._isHtml  = true;
+          store._rawHtml = clean;
+          store._diagnostics = diagnostics;
+          markOk();
+          return store;
+        } catch {}
+      } else {
+        try {
+          rdflib.parse(text, store, endpoint, detectFormat(ct, ''));
+          store._diagnostics = diagnostics;
+          markOk();
+          return store;
+        } catch (parseErr) {
+          lastError = parseErr;
+        }
+      }
+    }
+  } catch (err) {
+    lastError = err;
+  }
+
+  const err = lastError || new Error('Failed to load or parse RDF');
+  err.diagnostics = diagnostics;
+  throw err;
+}
+
+// ─── Blank-node processing ───────────────────────────────────────────────────
+export function expandBnodes(store, data) {
+  let vars     = data.head.vars;
+  let bindings = data.results.bindings;
+
+  if (bindings.length > 0) {
+    const allBnodeCols = vars.filter(v => bindings.every(r => r[v]?.type === 'bnode'));
+    if (allBnodeCols.length) {
+      vars = vars.filter(v => !allBnodeCols.includes(v));
+      bindings = bindings.map(r => {
+        const nr = { ...r };
+        allBnodeCols.forEach(v => delete nr[v]);
+        return nr;
+      });
+    }
+  }
+
+  const objVars = vars.filter(v => v !== 's' && v !== 'p');
+  const hasBnode = bindings.some(row => objVars.some(v => row[v]?.type === 'bnode'));
+  if (!hasBnode) return w3cResults(vars, bindings);
+
+  bindings = bindings.map(row => {
+    const newRow = {};
+    for (const [k, cell] of Object.entries(row)) {
+      newRow[k] = (objVars.includes(k) && cell?.type === 'bnode')
+        ? _bnodeToModal(store, cell._term)
+        : cell;
+    }
+    return newRow;
+  });
+  return w3cResults(vars, bindings);
+}
+
+function _bnodeToModal(store, bnodeTerm) {
+  const stmts = (store.match(bnodeTerm, null, null, null) || [])
+    .filter(st => st.object.termType !== 'BlankNode');
+  const bindings = stmts.map(st => ({
+    p: termToCell(st.predicate),
+    o: termToCell(st.object),
+  }));
+  return { type: 'bnode', value: '[…]', _data: w3cResults(['p', 'o'], bindings) };
+}
+
+// ─── Widen subjects into rows-of-properties ──────────────────────────────────
+export function pivotSubjectsToRows(store, subjects, subjectName = 's') {
+  const shortName = uri => (uri || '').replace(/.*[/#]([^/#]+)\/?$/, '$1') || uri;
+  const cols = [subjectName];
+  const seen = new Set([subjectName]);
+  const rows = [];
+
+  for (const subj of subjects) {
+    const row = { [subjectName]: termToCell(subj) };
+    const stmts = store.match(subj, null, null, null) || [];
+    for (const st of stmts) {
+      const col = shortName(st.predicate.value);
+      const cell = termToCell(st.object);
+      if (!seen.has(col)) { cols.push(col); seen.add(col); }
+      if (row[col] === undefined) row[col] = cell;
+      else if (row[col].type === 'multi') row[col].values.push(cell);
+      else row[col] = { type: 'multi', values: [row[col], cell] };
+    }
+    rows.push(row);
+  }
+  return w3cResults(cols, rows);
+}
+
+export function promoteDisplayColumns(data, subjectCol) {
+  let cols = data.head.vars.filter(v => v !== subjectCol);
+  const lead = cols.find(v => /^(name|label|title)$/i.test(v));
+  if (lead) cols = [lead, ...cols.filter(v => v !== lead)];
+  return w3cResults(cols, data.results.bindings);
+}
+
+// ─── Full store → flat renderer results ──────────────────────────────────────
+export function storeToResults(store) {
+  const stmts = Array.isArray(store.statements)
+    ? store.statements
+    : (typeof store.match === 'function' ? store.match(null, null, null) : []);
+
+  const bindings = stmts.map(st => ({
+    s: termToCell(st.subject),
+    p: termToCell(st.predicate),
+    o: termToCell(st.object),
+  }));
+
+  return w3cResults(['s', 'p', 'o'], bindings);
+}
+
+// ─── Fetch SPARQL query text from an RDF file ────────────────────────────────
+export async function fetchQueryFromRdf(queryUrl, fetchFn = fetch) {
+  if (!rdf.isReady()) throw new Error('rdflib not available');
+  const rdflib = rdf;
+
+  try { queryUrl = new URL(queryUrl, document.baseURI).href; } catch {}
+
+  const docUrl = queryUrl.split('#')[0];
+  const store  = await loadRdfStore(docUrl, fetchFn, { shared: true });
+
+  const subject = rdflib.sym(queryUrl);
+  const q = store.any(subject, rdflib.sym('http://www.w3.org/ns/sparql#query'))
+         || store.any(subject, rdflib.sym('http://www.w3.org/2000/01/rdf-schema#comment'))
+         || store.any(subject, rdflib.sym('http://purl.org/dc/terms/description'));
+
+  if (!q) throw new Error(`No query found at ${queryUrl}`);
+  return q.value;
+}
+
+// ─── runQuery: call from a script, returns plain JS values ───────────────────
+export async function runQuery({ endpoint, sparql, pattern, wanted, vars: patternVars } = {}) {
+  const pat = pattern || wanted;
+  if (!endpoint) throw new Error('endpoint is required');
+  if (!sparql && !pat) throw new Error('sparql or pattern is required');
+
+  let data;
+
+  if (sparql) {
+    let queryText = sparql;
+    const isStoredRef = !/\s/.test(sparql) && /^https?:\/\/|^\/|^\.\.?\//.test(sparql.trim());
+    if (isStoredRef) queryText = await fetchQueryFromRdf(sparql);
+    data = await execSparql(queryText, endpoint);
+  } else {
+    const store  = await loadRdfStore(endpoint);
+    const [s, p, o] = parsePatternParts(pat, rdf, {}, endpoint);
+    data = matchStore(store, s, p, o);
+  }
+
+  return toPlainResults(data, patternVars);
+}
+
+// ─── Run SPARQL against a pre-loaded rdflib store ────────────────────────────
+async function _localSparql(queryText, endpoint) {
+  if (!rdf.hasSparqlEngine()) throw new Error('rdflib SPARQL engine not available');
+
+  // rdflib's local SPARQL parses LIMIT/OFFSET/ORDER BY but doesn't enforce
+  // them, so a query with these clauses silently returns the unbounded /
+  // unsorted result set. Surface it instead of letting the user wonder why
+  // their LIMIT is being ignored. To honor these clauses, load Comunica
+  // (e.g. via the vendored UMD: `<script src=".../@comunica-query-sparql.umd.js">`).
+  if (/\b(LIMIT|OFFSET|ORDER\s+BY)\b/i.test(queryText)) {
+    console.warn(
+      '[sol-query] LIMIT/OFFSET/ORDER BY present but rdflib local SPARQL ignores them. ' +
+      'Load @comunica/query-sparql to enforce these clauses against RDF documents.'
+    );
+  }
+
+  const store  = await loadRdfStore(endpoint);
+  const parsed = rdf.sparqlToQuery(queryText, false, store);
+  if (!parsed) throw new Error('Could not parse SPARQL query');
+
+  return new Promise((resolve, reject) => {
+    const bindings = [];
+    try {
+      store.query(
+        parsed,
+        b  => bindings.push(b),
+        rdf.fetcher(store),
+        () => resolve(bindingsToResults(bindings, queryText)),
+      );
+    } catch (err) {
+      reject(err);
+    }
+  });
+}
+
+// ─── SPARQL execution ────────────────────────────────────────────────────────
+// `fetchFn` is the authenticated fetch (from getAuthFetch) when one is
+// available; passed to Comunica via its query context and to the native
+// SPARQL adapter for endpoints that aren't RDF documents.
+export async function execSparql(query, endpoint, fetchFn) {
+  // Multi-source federation only works through Comunica.
+  if (Array.isArray(endpoint)) {
+    const factory = ComunicaSparqlAdapter.getComunicaEngine();
+    if (!factory) throw new Error('Multiple endpoints require Comunica');
+    return await new ComunicaSparqlAdapter(factory).executeQuery(query, endpoint, fetchFn);
+  }
+
+  try { endpoint = new URL(endpoint, document.baseURI).href; } catch {}
+
+  const isRdf = _isRdfDoc(endpoint);
+
+  const comunicaFactory = ComunicaSparqlAdapter.getComunicaEngine();
+  if (comunicaFactory) {
+    try { return await new ComunicaSparqlAdapter(comunicaFactory).executeQuery(query, endpoint, fetchFn); }
+    catch (err) {
+      console.warn('[sol-query] Comunica failed, falling back to rdflib:', err);
+    }
+  } else if (typeof window !== 'undefined' && window.Comunica) {
+    console.warn('[sol-query] window.Comunica is set but no QueryEngine factory was found.',
+      'Top-level keys:', Object.keys(window.Comunica),
+      window.Comunica.default ? 'default keys: ' + Object.keys(window.Comunica.default).slice(0, 10).join(', ') : '');
+  }
+
+  if (isRdf) {
+    return await _localSparql(query, endpoint);
+  }
+
+  const rdflibAdapter = new RdflibSparqlAdapter();
+  if (rdflibAdapter.isAvailable()) {
+    try { return await rdflibAdapter.executeQuery(query, endpoint, true); } catch {
+      try { return await rdflibAdapter.executeQuery(query, endpoint, false); } catch {}
+    }
+  }
+  return await new NativeSparqlAdapter().executeQuery(query, endpoint, fetchFn);
+}
+
+// ─── SPARQL adapter (rdflib-based) ───────────────────────────────────────────
+
+export class RdflibSparqlAdapter {
+  isAvailable() {
+    return rdf.hasRemoteSparql();
+  }
+
+  async executeQuery(query, endpoint, withCredentials = true) {
+    if (!rdf.isReady()) throw new Error('rdflib not available');
+    try {
+      return await this._attempt(query, endpoint, withCredentials);
+    } catch (err) {
+      if (withCredentials) {
+        return await this._attempt(query, endpoint, false);
+      }
+      throw err;
+    }
+  }
+
+  async _attempt(query, endpoint, withCredentials) {
+    const raw = await rdf.sparqlQuery(query, { endpoint, withCredentials });
+    const selectVarsResult = _selectVars(query);
+    const vars = selectVarsResult
+      ?? (raw.length ? Object.keys(raw[0]).filter(k => !k.startsWith('?')) : []);
+    const bindings = raw.map(binding => {
+      const row = {};
+      vars.forEach(v => {
+        const val = binding[v];
+        const cell = {
+          type: val ? (val.termType || 'literal').toLowerCase() : 'literal',
+          value: val ? (val.value || String(val)) : '',
+        };
+        if (val?.language)        cell['xml:lang'] = val.language;
+        if (val?.datatype?.value) cell.datatype    = val.datatype.value;
+        row[v] = cell;
+      });
+      return row;
+    });
+    return w3cResults(vars, bindings);
+  }
+}

package/core/rdf.js

@@ -0,0 +1,154 @@
+// Singleton wrapper around rdflib. The rest of the codebase goes through this
+// class so rdflib is imported in exactly one place. Rollup treats `rdflib` as
+// external (mapped to the `$rdf` UMD global); jest's moduleNameMapper maps it
+// to a mock; importmaps/bundlers resolve it normally.
+
+// Bare specifier — resolved by the consumer's importmap (CDN or local
+// vendored copy) or by a bundler. Per-component UMD builds list `rdflib`
+// in `external` so it stays a runtime global.
+import * as _rdflib from 'rdflib';
+import { register as registerService } from './services.js';
+
+// `import * as _rdflib` exposes rdflib's named exports directly.
+const _lib = _rdflib;
+
+class Rdf {
+  constructor() {
+    this._store = null;    // lazy shared singleton store
+    this._fetcher = null;  // fetcher bound to _store
+    this._adopted = false; // a host explicitly adopted an external store (wins)
+    this._loaded = new Set(); // URLs already parsed into _store (cache key)
+  }
+
+  // Record that `url` has been parsed into the shared store.
+  markLoaded(url) { this._loaded.add(url); }
+  isLoaded(url)   { return this._loaded.has(url); }
+
+  // Term constructors
+  sym(uri)                         { return _lib.sym(uri); }
+  // rdflib.literal accepts either (value, langOrDatatype) — second arg
+  // is the language tag if a string, or the datatype if a NamedNode —
+  // or (value, lang, datatype). Pass through whichever form the caller
+  // used so typed literals like "45.52"^^xsd:decimal survive.
+  literal(value, langOrDatatype, datatype) {
+    if (datatype !== undefined) return _lib.literal(value, langOrDatatype, datatype);
+    return _lib.literal(value, langOrDatatype);
+  }
+  blankNode(id)                    { return _lib.blankNode(id); }
+
+  // Stores & parsing
+  graph()                          { return _lib.graph(); }
+  parse(text, store, base, type)   { return _lib.parse(text, store, base, type); }
+  st(s, p, o, g)                   { return _lib.st(s, p, o, g); }
+
+  // Shared singleton store — interop point with solid-logic / solid-ui / mashlib.
+  // **When solid-logic's singleton is present on `window`, that's THE store**
+  // — every sol-* component, solid-ui module, mashlib, etc. point at the same
+  // rdflib graph, so cross-component reads/writes are coherent and solid-ui's
+  // captured-at-import-time `kb` references work without any swap dance.
+  // Falls back to a freshly created graph in environments without solid-logic
+  // (unit tests, headless scripts without the singleton wired up).
+  get store() {
+    // A host that explicitly adopted a foreign store (useStore — e.g. another
+    // component library's rdflib graph handed over at runtime) wins outright,
+    // so swc components share THAT graph regardless of solid-logic's singleton.
+    if (this._adopted && this._store) return this._store;
+    // Otherwise always re-probe so consumers reach solid-logic's singleton even
+    // if an early access happened before solid-logic finished loading. Once
+    // solid-logic is up, every call returns ITS store; before then, a
+    // local fresh graph is used and persists until the singleton appears.
+    const sl = (typeof window !== 'undefined') &&
+      (window[Symbol.for('solid-logic-singleton')] || window.SolidLogic);
+    if (sl?.store) {
+      this._store = sl.store;
+      return sl.store;
+    }
+    if (!this._store) this._store = _lib.graph();
+    return this._store;
+  }
+  useStore(externalStore) {
+    if (!externalStore || typeof externalStore.match !== 'function') return false;
+    this._store = externalStore;
+    this._fetcher = externalStore.fetcher || null;
+    this._adopted = true;
+    this._loaded.clear();
+    return true;
+  }
+  get storeFetcher() {
+    if (this._fetcher) return this._fetcher;
+    if (this.store.fetcher) { this._fetcher = this.store.fetcher; return this._fetcher; }
+    this._fetcher = new _lib.Fetcher(this.store);
+    this.store.fetcher = this._fetcher;
+    return this._fetcher;
+  }
+
+  // Fetch a document into the shared store via the shared (auth-aware) Fetcher,
+  // at most once per document. Returns the shared store. This is the convenience
+  // a component reaches through window.SolidWebComponents.rdf.load(url).
+  async load(url) {
+    const doc = String(url).split('#')[0];
+    if (!this.isLoaded(doc)) {
+      await this.storeFetcher.load(doc);
+      this.markLoaded(doc);
+    }
+    return this.store;
+  }
+
+  // SPARQL
+  fetcher(store, opts)             { return new _lib.Fetcher(store, opts); }
+  sparqlToQuery(query, isUpdate, store) { return _lib.SPARQLToQuery(query, isUpdate, store); }
+  sparqlQuery(query, opts)         { return _lib.sparqlQuery(query, opts); }
+
+  // Capability probes
+  isReady()          { return !!_lib && typeof _lib.graph === 'function'; }
+  hasSparqlEngine()  { return typeof _lib.SPARQLToQuery === 'function'; }
+  hasRemoteSparql()  { return typeof _lib.sparqlQuery === 'function'; }
+
+  // Serialization
+  serialize(doc, store, base, contentType) {
+    return _lib.serialize(doc, store, base, contentType);
+  }
+
+  // UpdateManager — for PATCH-based edits and putBack
+  get UpdateManager() { return _lib.UpdateManager; }
+
+  // Escape hatches for the few places that need rdflib-shaped access
+  // (e.g. `new rdflib.Fetcher(...)`). Prefer the methods above.
+  get SPARQLToQuery() { return _lib.SPARQLToQuery; }
+  get Fetcher()       { return _lib.Fetcher; }
+  get NamedNode()     { return _lib.NamedNode; }
+  get BlankNode()     { return _lib.BlankNode; }
+  get Literal()       { return _lib.Literal; }
+  get Collection()    { return _lib.Collection; }
+  get Statement()     { return _lib.Statement; }
+}
+
+// Cross-bundle singleton. Every bundle (each UMD component, the app's own
+// code, solid-ui's world) compiles its own copy of this module; without a
+// shared instance each would mint its OWN store + storeFetcher, so e.g.
+// <sol-login>'s `_integrateWithRdflib()` patch would be invisible to an app
+// reading `rdf.store` from a different bundle. Publishing ONE instance on
+// `window` makes the store, fetcher and loaded-set page-wide, so any app can
+// just load components from sol-loader and share one coherent store — no
+// bundling-from-source workaround. (Paired with the rdflib→window.$rdf shim
+// so all bundles also share one rdflib *library*, for term `instanceof`.)
+//
+// Browser only: in Node / jest each module keeps its own instance (no `window`),
+// preserving test isolation.
+const _RDF_SINGLETON = Symbol.for('sol-components:rdf-singleton');
+export const rdf = (typeof window !== 'undefined')
+  ? (window[_RDF_SINGLETON] || (window[_RDF_SINGLETON] = new Rdf()))
+  : new Rdf();
+export default rdf;
+
+// Publish the shared store as the `rdf` host-service so any component can reach
+// it via window.SolidWebComponents.rdf — no import of this module required.
+registerService('rdf', rdf);
+
+// Register the broker consumer that adopts a foreign rdflib store: the loader
+// invokes it for a manifest `consumes: { rdf: { call: 'rdf.useStore' } }`. (The
+// loader publishes registerConsumer; absent in Node/jest, so this is guarded.)
+if (typeof window !== 'undefined' && window.SolidWebComponents
+    && typeof window.SolidWebComponents.registerConsumer === 'function') {
+  window.SolidWebComponents.registerConsumer('rdf.useStore', function (store) { rdf.useStore(store); });
+}

package/core/services.js

@@ -0,0 +1,106 @@
+// core/services.js — import-side accessor for the host-services registry.
+//
+// The ecosystem's "share resources without importing each other" surface. The
+// component-interop loader publishes a tiny registry at `window.ComponentInterop.services`
+// (services.js#root() also accepts a window.SolidWebComponents surface); swc capability modules import THIS file
+// to register the shared services they provide:
+//
+//   import { register } from '../core/services.js';
+//   register('rdf', rdf);                 // core/rdf.js
+//   register('auth', { fetch, manager }); // web/sol-login.js
+//   register('defaults', { get, onChange });
+//
+// Any component (swc's or a third party's) then reads them, import-free, via
+// `window.SolidWebComponents.{ rdf, auth, fetch, defaults, has, services }`.
+//
+// Mirrors core/rdf.js: in the browser everything funnels through the one
+// window-shared registry; in Node/jest there's no `window`, so a module-local
+// fallback registry is used (preserving test isolation). The registry is
+// duck-typed by its methods, so it doesn't matter whether the loader or this
+// module created it.
+
+import { EVENTS } from './events.js';
+
+function makeRegistry() {
+  const map = new Map();
+  const waiters = new Map();
+  return {
+    register(name, impl) {
+      map.set(name, impl);
+      const ws = waiters.get(name);
+      if (ws) { waiters.delete(name); ws.forEach((fn) => fn(impl)); }
+    },
+    get(name) { return map.get(name); },
+    has(name) { return map.has(name); },
+    names() { return Array.from(map.keys()); },
+    whenReady(name) {
+      if (map.has(name)) return Promise.resolve(map.get(name));
+      return new Promise((res) => {
+        const a = waiters.get(name) || [];
+        a.push(res);
+        waiters.set(name, a);
+      });
+    },
+  };
+}
+
+let _local = null;
+
+/** The one shared host surface. It is the broker's `window.ComponentInterop`
+ *  when component-interop's loader is on the page; `window.SolidWebComponents`
+ *  is swc's historical alias for the SAME object. Unifying them here lets swc
+ *  work whether the page loaded component-interop's generic loader OR swc's own
+ *  (which vendors it). A Node-side stand-in is used in tests without a window. */
+export function root() {
+  if (typeof window !== 'undefined') {
+    const surface = window.ComponentInterop || window.SolidWebComponents || {};
+    window.ComponentInterop = surface;
+    window.SolidWebComponents = surface;
+    return surface;
+  }
+  return (_local = _local || {});
+}
+
+/** The shared services registry — the loader's if present, else one we create. */
+export function services() {
+  const r = root();
+  if (!r.services) r.services = makeRegistry();
+  if (!r.EVENTS) r.EVENTS = EVENTS;   // the loader doesn't bake the table
+  return r.services;
+}
+
+export function register(name, impl) { return services().register(name, impl); }
+export function get(name)            { return services().get(name); }
+export function has(name)            { return services().has(name); }
+export function whenReady(name)      { return services().whenReady(name); }
+
+/**
+ * Adopt a foreign authenticated fetch as the page's default authenticated fetch
+ * when no <sol-login> is present. This lets swc components ride a session
+ * established by another component library (e.g. PodOS, which hands its
+ * `authenticatedFetch` out via its `pod-os:loaded` event). getAuthFetch()
+ * (core/auth-fetch.js) returns it as the fallback after the <sol-login> lookup.
+ * A logged-in <sol-login> still wins — this is the no-sol-login fallback.
+ *
+ * @param {(input: RequestInfo, init?: RequestInit) => Promise<Response>} fn
+ * @param {object} [info]  e.g. { webId }
+ * @returns the adopted fetch (or null when cleared)
+ */
+export function adoptFetch(fn, info) {
+  const r = root();
+  r.adoptedFetch = (typeof fn === 'function') ? fn : null;
+  if (info && info.webId) r.adoptedWebId = info.webId;
+  return r.adoptedFetch;
+}
+
+// Expose adoptFetch on the host surface so import-free host glue can call
+// `window.SolidWebComponents.adoptFetch(fn, { webId })`.
+if (typeof window !== 'undefined') {
+  const r = root();
+  if (!r.adoptFetch) r.adoptFetch = adoptFetch;
+  // Register the broker consumer that adopts a foreign authenticated fetch: the
+  // loader invokes it for a manifest `consumes: { auth: { call: 'adoptFetch' } }`.
+  if (typeof r.registerConsumer === 'function') r.registerConsumer('adoptFetch', (fn) => adoptFetch(fn));
+}
+
+export { EVENTS };