sol-components 2.1.0

package/core/popup-proxy.js

@@ -0,0 +1,255 @@
+/**
+ * popup-proxy — parent-side proxy for an OIDC session that lives in a
+ * popup window.
+ *
+ * Phase 0 established that two Inrupt `Session`s cannot coexist in one
+ * window (storage gets wiped; restoration redirects top-level). The
+ * workaround: each session lives in its own popup window, which holds
+ * the real `Session`. The parent never navigates, so multiple popups'
+ * sessions coexist. The parent talks to each popup over postMessage.
+ *
+ * `PopupProxySession` is shape-compatible with the bits of Inrupt's
+ * `Session` that callers use — `.info`, `.fetch`, `.logout` — so it can
+ * be stored in `AuthManager.sessions` alongside (or instead of) real
+ * `Session`s.
+ *
+ * Wire protocol (both directions use `source` to disambiguate):
+ *
+ *   parent → popup  { source:'sol-popup-parent', type, id, side, ... }
+ *   popup  → parent { source:'sol-popup-auth',   type, id, side, ... }
+ *
+ *   type 'fetch'        parent→popup  { url, init: SerializedInit }
+ *   type 'fetch-reply'  popup→parent  { ok,status,statusText,headers,body } | { error }
+ *   type 'logout'       parent→popup  {}
+ *   type 'logout-reply' popup→parent  {}
+ *   type 'logged-in'    popup→parent  { webId, sessionId, issuer }
+ *   type 'login-failed' popup→parent  { error }
+ *   type 'popup-ready'  popup→parent  {}
+ *
+ * Request/response bodies are buffered (not streamed) — fine for pod
+ * file ops, which are not huge. Blob and ArrayBuffer survive structured
+ * clone; ReadableStream does not, so it is buffered first.
+ */
+
+const PARENT_SRC = 'sol-popup-parent';
+const POPUP_SRC  = 'sol-popup-auth';
+
+/** Statuses whose Response MUST have a null body. */
+const NULL_BODY_STATUS = new Set([101, 204, 205, 304]);
+
+/**
+ * Serialize a fetch `init` (and a Request-ish input) into a structured-
+ * cloneable object. Headers → [[k,v]]; a streaming body is buffered to
+ * a Blob.
+ */
+export async function serializeRequest(input, init = {}) {
+  const url = typeof input === 'string'
+    ? input
+    : (input && input.url) || String(input);
+
+  const method = (init.method
+    || (typeof input !== 'string' && input && input.method)
+    || 'GET').toUpperCase();
+
+  // Merge headers from a Request input and the init.
+  const headers = [];
+  const collect = (h) => {
+    if (!h) return;
+    if (typeof h.forEach === 'function' && !(Array.isArray(h))) {
+      h.forEach((v, k) => headers.push([k, v]));
+    } else if (Array.isArray(h)) {
+      for (const [k, v] of h) headers.push([k, v]);
+    } else {
+      for (const k of Object.keys(h)) headers.push([k, h[k]]);
+    }
+  };
+  if (typeof input !== 'string' && input && input.headers) collect(input.headers);
+  if (init.headers) collect(init.headers);
+
+  let body = init.body;
+  if (body == null && typeof input !== 'string' && input && input.body) {
+    // Request input with a body — buffer it.
+    body = await input.clone().blob();
+  }
+  if (body instanceof ReadableStream) {
+    body = await new Response(body).blob();
+  }
+  // Blob, ArrayBuffer, ArrayBufferView, string, URLSearchParams all
+  // survive structured clone. FormData does too. Leave as-is.
+
+  return { url, init: { method, headers, body } };
+}
+
+/** Reconstruct a fetch call inside the popup from a serialized request. */
+export function deserializeRequest(msg) {
+  const init = {
+    method: msg.init.method,
+    headers: new Headers(msg.init.headers || []),
+  };
+  if (msg.init.body != null && msg.init.method !== 'GET' && msg.init.method !== 'HEAD') {
+    init.body = msg.init.body;
+  }
+  return { url: msg.url, init };
+}
+
+/** Serialize a Response (popup side) into a cloneable object. */
+export async function serializeResponse(res) {
+  const headers = [];
+  res.headers.forEach((v, k) => headers.push([k, v]));
+  let body = null;
+  if (!NULL_BODY_STATUS.has(res.status)) {
+    body = await res.blob();
+  }
+  return {
+    ok: res.ok,
+    status: res.status,
+    statusText: res.statusText,
+    headers,
+    body,
+  };
+}
+
+/** Reconstruct a Response (parent side) from a serialized reply. */
+export function deserializeResponse(reply) {
+  const init = {
+    status: reply.status,
+    statusText: reply.statusText,
+    headers: new Headers(reply.headers || []),
+  };
+  const body = NULL_BODY_STATUS.has(reply.status) ? null : reply.body;
+  return new Response(body, init);
+}
+
+/**
+ * Parent-side proxy. Holds a reference to the popup window and forwards
+ * `fetch` to it.
+ */
+export class PopupProxySession extends EventTarget {
+  /**
+   * @param {Window} popupWindow  the open popup running the callback page
+   * @param {Object} loginInfo    { webId, sessionId, issuer, side }
+   * @param {string} popupOrigin  origin to postMessage to (same-origin app)
+   */
+  constructor(popupWindow, loginInfo, popupOrigin) {
+    super();
+    this._popup = popupWindow;
+    this._origin = popupOrigin || (typeof window !== 'undefined' ? window.location.origin : '*');
+    this._side = loginInfo.side || null;
+    this._reqId = 0;
+    this._pending = new Map();
+
+    this.info = {
+      isLoggedIn: true,
+      sessionId: loginInfo.sessionId || null,
+      webId: loginInfo.webId || null,
+      issuer: loginInfo.issuer || null,
+      clientAppId: loginInfo.clientId || null,
+    };
+
+    this._onMessage = (e) => this._handleMessage(e);
+    window.addEventListener('message', this._onMessage);
+
+    // Close the popup when the app page goes away (tab close, navigation,
+    // browser quit) so we don't leave orphaned login windows behind.
+    // Skip when the page is going into the back/forward cache
+    // (event.persisted) — it may be restored, and the popup should
+    // survive with it.
+    this._onPageHide = (e) => {
+      if (e && e.persisted) return;
+      if (this._popup && !this._popup.closed) {
+        try { this._popup.close(); } catch (_) { /* ignore */ }
+      }
+    };
+    window.addEventListener('pagehide', this._onPageHide);
+
+    // Notice if the popup is closed out from under us.
+    this._closeWatch = setInterval(() => {
+      if (this._popup && this._popup.closed) this._handlePopupClosed();
+    }, 1500);
+  }
+
+  get side() { return this._side; }
+  get popupClosed() { return !this._popup || this._popup.closed; }
+
+  _handleMessage(e) {
+    const d = e.data;
+    if (!d || d.source !== POPUP_SRC) return;
+    if (this._side && d.side && d.side !== this._side) return;
+    if (d.type === 'fetch-reply' || d.type === 'logout-reply') {
+      const p = this._pending.get(d.id);
+      if (p) {
+        this._pending.delete(d.id);
+        if (d.error) p.reject(new Error(d.error));
+        else p.resolve(d);
+      }
+    }
+  }
+
+  _handlePopupClosed() {
+    clearInterval(this._closeWatch);
+    if (!this.info.isLoggedIn) return;
+    this.info.isLoggedIn = false;
+    for (const [, p] of this._pending) p.reject(new Error('popup closed'));
+    this._pending.clear();
+    this.dispatchEvent(new CustomEvent('logout', {
+      detail: { reason: 'popup-closed', side: this._side },
+    }));
+  }
+
+  _post(msg, transfer) {
+    if (this.popupClosed) throw new Error('popup is closed');
+    msg.source = PARENT_SRC;
+    msg.side = this._side;
+    this._popup.postMessage(msg, this._origin, transfer || []);
+  }
+
+  _request(msg, timeoutMs = 60000) {
+    const id = String(++this._reqId);
+    msg.id = id;
+    return new Promise((resolve, reject) => {
+      this._pending.set(id, { resolve, reject });
+      try {
+        this._post(msg);
+      } catch (err) {
+        this._pending.delete(id);
+        reject(err);
+        return;
+      }
+      setTimeout(() => {
+        if (this._pending.has(id)) {
+          this._pending.delete(id);
+          reject(new Error('popup request timed out'));
+        }
+      }, timeoutMs);
+    });
+  }
+
+  /** Authenticated fetch — proxied to the popup's real Session. */
+  fetch = async (input, init) => {
+    if (!this.info.isLoggedIn) throw new Error('PopupProxySession: not logged in');
+    const serialized = await serializeRequest(input, init);
+    const reply = await this._request({ type: 'fetch', ...serialized });
+    if (reply.error) throw new Error(reply.error);
+    return deserializeResponse(reply);
+  };
+
+  async logout() {
+    if (!this.popupClosed) {
+      try { await this._request({ type: 'logout' }, 5000); } catch (_) { /* ignore */ }
+    }
+    this.info.isLoggedIn = false;
+    this.dispatchEvent(new CustomEvent('logout', { detail: { reason: 'explicit', side: this._side } }));
+    this.destroy();
+  }
+
+  /** Tear down listeners and close the popup. */
+  destroy() {
+    clearInterval(this._closeWatch);
+    window.removeEventListener('message', this._onMessage);
+    window.removeEventListener('pagehide', this._onPageHide);
+    if (this._popup && !this._popup.closed) {
+      try { this._popup.close(); } catch (_) { /* ignore */ }
+    }
+    this._popup = null;
+  }
+}

package/core/rdf-core.js

@@ -0,0 +1,280 @@
+// Pure RDF utility functions shared between browser (rdf-utils.js) and
+// Node (sol-query-node.js). All rdflib-dependent functions accept an
+// rdflib-like object ({ sym, literal }) as a parameter.
+
+// ─── Namespace prefixes ──────────────────────────────────────────────────────
+export const KNOWN_PREFIXES = {
+  acl: 'http://www.w3.org/ns/auth/acl#',
+  arg: 'http://www.w3.org/ns/pim/arg#',
+  as: 'https://www.w3.org/ns/activitystreams#',
+  bookmark: 'http://www.w3.org/2002/01/bookmark#',
+  cal: 'http://www.w3.org/2002/12/cal/ical#',
+  cco: 'http://www.ontologyrepository.com/CommonCoreOntologies/',
+  cert: 'http://www.w3.org/ns/auth/cert#',
+  contact: 'http://www.w3.org/2000/10/swap/pim/contact#',
+  dc: 'http://purl.org/dc/elements/1.1/',
+  dct: 'http://purl.org/dc/terms/',
+  doap: 'http://usefulinc.com/ns/doap#',
+  foaf: 'http://xmlns.com/foaf/0.1/',
+  geo: 'http://www.w3.org/2003/01/geo/wgs84_pos#',
+  gpx: 'http://www.w3.org/ns/pim/gpx#',
+  gr: 'http://purl.org/goodrelations/v1#',
+  http: 'http://www.w3.org/2007/ont/http#',
+  httph: 'http://www.w3.org/2007/ont/httph#',
+  icalTZ: 'http://www.w3.org/2002/12/cal/icaltzd#',
+  ldp: 'http://www.w3.org/ns/ldp#',
+  link: 'http://www.w3.org/2007/ont/link#',
+  log: 'http://www.w3.org/2000/10/swap/log#',
+  meeting: 'http://www.w3.org/ns/pim/meeting#',
+  mo: 'http://purl.org/ontology/mo/',
+  org: 'http://www.w3.org/ns/org#',
+  owl: 'http://www.w3.org/2002/07/owl#',
+  pad: 'http://www.w3.org/ns/pim/pad#',
+  patch: 'http://www.w3.org/ns/pim/patch#',
+  prov: 'http://www.w3.org/ns/prov#',
+  pto: 'http://www.productontology.org/id/',
+  qu: 'http://www.w3.org/2000/10/swap/pim/qif#',
+  trip: 'http://www.w3.org/ns/pim/trip#',
+  rdf: 'http://www.w3.org/1999/02/22-rdf-syntax-ns#',
+  rdfs: 'http://www.w3.org/2000/01/rdf-schema#',
+  rss: 'http://purl.org/rss/1.0/',
+  sched: 'http://www.w3.org/ns/pim/schedule#',
+  schema: 'http://schema.org/',
+  sioc: 'http://rdfs.org/sioc/ns#',
+  skos: 'http://www.w3.org/2004/02/skos/core#',
+  solid: 'http://www.w3.org/ns/solid/terms#',
+  space: 'http://www.w3.org/ns/pim/space#',
+  stat: 'http://www.w3.org/ns/posix/stat#',
+  ui: 'http://www.w3.org/ns/ui#',
+  vann: 'http://purl.org/vocab/vann/',
+  vcard: 'http://www.w3.org/2006/vcard/ns#',
+  wf: 'http://www.w3.org/2005/01/wf/flow#',
+  xsd: 'http://www.w3.org/2001/XMLSchema#',
+};
+
+// ─── Accept types & format detection ─────────────────────────────────────────
+export const ACCEPT_TYPES = [
+  'text/turtle',
+  'application/ld+json',
+  'application/rdf+xml',
+  'text/n3',
+  'application/n-triples',
+];
+
+export function detectFormat(ct, accept) {
+  if (ct.includes('turtle')    || accept.includes('turtle'))    return 'text/turtle';
+  if (ct.includes('ld+json')   || accept.includes('ld+json'))   return 'application/ld+json';
+  if (ct.includes('rdf+xml'))                                   return 'application/rdf+xml';
+  if (ct.includes('n-triples') || accept.includes('n-triples')) return 'application/n-triples';
+  if (ct.includes('n3')        || accept.includes('n3'))        return 'text/n3';
+  return ct || 'text/turtle';
+}
+
+// ─── Term utilities ──────────────────────────────────────────────────────────
+export function termToString(term) {
+  if (!term) return '';
+  if (typeof term === 'string') return term;
+  if (typeof term.toNT === 'function') return term.toNT();
+  if (typeof term.value === 'string') return term.value;
+  return String(term);
+}
+
+export function termToCell(term) {
+  if (!term) return { type: 'literal', value: '' };
+  if (term.termType === 'NamedNode')  return { type: 'uri',   value: term.value };
+  if (term.termType === 'BlankNode')  return { type: 'bnode', value: term.value, _term: term };
+  // Preserve W3C SPARQL Query Results JSON literal extras when present.
+  const cell = { type: 'literal', value: term.value ?? String(term) };
+  if (term.language)            cell['xml:lang'] = term.language;
+  if (term.datatype?.value)     cell.datatype    = term.datatype.value;
+  return cell;
+}
+
+// Wrap (vars, bindings) as the W3C SPARQL Query Results JSON envelope.
+// All producers in this codebase use this so consumers see one shape.
+export function w3cResults(vars, bindings) {
+  return { head: { vars }, results: { bindings } };
+}
+
+// Build a SPARQL PREFIX block from KNOWN_PREFIXES (plus optional extras).
+// Used to make Comunica accept CURIE-style triple patterns ("?s foaf:name ?n")
+// without forcing callers to declare every prefix themselves.
+export function knownPrefixesAsSparql(extra = {}) {
+  const all = { ...KNOWN_PREFIXES, ...extra };
+  return Object.entries(all).map(([k, v]) => `PREFIX ${k}: <${v}>`).join('\n');
+}
+
+// ─── CURIE expansion ─────────────────────────────────────────────────────────
+export function expandCurie(curie, extraPrefixes = {}) {
+  const colon = curie.indexOf(':');
+  if (colon < 0) return null;
+  const prefix = curie.slice(0, colon);
+  const local  = curie.slice(colon + 1);
+  const ns = extraPrefixes[prefix] || KNOWN_PREFIXES[prefix];
+  return ns ? ns + local : null;
+}
+
+function _isCurie(token) {
+  return /^[a-zA-Z][a-zA-Z0-9]*:[^/\s]/.test(token);
+}
+
+function _resolveUri(raw, baseUri) {
+  if (!baseUri) return raw;
+  const docBase = baseUri.split('#')[0];
+  if (raw.startsWith('#'))  return docBase + raw;
+  try { return new URL(raw, baseUri).href; } catch { return raw; }
+}
+
+export const _NAMED_VAR_RE = /^\?[A-Za-z_][A-Za-z0-9_]*$/;
+
+// ─── Triple-pattern term parser ──────────────────────────────────────────────
+// rdflib: object with sym(uri) and literal(value, langOrType) methods.
+export function triplePatternTermToNode(term, rdflib, extraPrefixes = {}, baseUri = '') {
+  if (!term) throw new Error('Triple-pattern term is empty');
+  if (term === '?') {
+    throw new Error('Bare "?" is not allowed — use a named variable like "?x"');
+  }
+  if (term.startsWith('?')) {
+    if (!_NAMED_VAR_RE.test(term)) {
+      throw new Error(`Invalid variable "${term}" — must match ?[A-Za-z_][A-Za-z0-9_]*`);
+    }
+    return null;
+  }
+  if (term.startsWith('<') && term.endsWith('>')) {
+    const inner = term.slice(1, -1);
+    const resolved = (inner.startsWith('#') || inner.startsWith('.') || !/^[a-z][a-z0-9+\-.]*:/i.test(inner))
+      ? _resolveUri(inner, baseUri)
+      : inner;
+    return rdflib.sym(resolved);
+  }
+  if (term.startsWith('"')) {
+    const m = term.match(/^"([^"]*)"(?:\^\^<([^>]+)>|@([a-z-]+))?$/i);
+    if (!m) throw new Error(`Malformed literal "${term}" — must be "value" with optional @lang or ^^<datatype>`);
+    return rdflib.literal(m[1], m[3] || (m[2] ? rdflib.sym(m[2]) : undefined));
+  }
+  if (term.startsWith('#')) {
+    if (!baseUri) throw new Error(`Fragment "${term}" requires a baseUri to resolve`);
+    return rdflib.sym(_resolveUri(term, baseUri));
+  }
+  if (_isCurie(term)) {
+    const expanded = expandCurie(term, extraPrefixes);
+    return rdflib.sym(expanded || term);
+  }
+  throw new Error(
+    `Unrecognized term "${term}" — must be a named variable (?x), <uri>, prefix:local, #fragment, or quoted "literal"`
+  );
+}
+
+// ─── Tokenize a triple pattern ───────────────────────────────────────────────
+export function tokenizeTriplePattern(input) {
+  const out = [];
+  const s = input.trim();
+  let i = 0;
+  while (i < s.length) {
+    while (i < s.length && /\s/.test(s[i])) i++;
+    if (i >= s.length) break;
+    if (s[i] === '"') {
+      let j = i + 1;
+      while (j < s.length && s[j] !== '"') {
+        if (s[j] === '\\' && j + 1 < s.length) j += 2;
+        else j++;
+      }
+      if (j >= s.length) throw new Error(`Unterminated literal starting at position ${i}`);
+      j++;
+      if (s[j] === '@') {
+        j++;
+        while (j < s.length && /[A-Za-z-]/.test(s[j])) j++;
+      } else if (s[j] === '^' && s[j + 1] === '^' && s[j + 2] === '<') {
+        j += 3;
+        while (j < s.length && s[j] !== '>') j++;
+        if (j >= s.length) throw new Error(`Unterminated datatype IRI`);
+        j++;
+      }
+      out.push(s.slice(i, j));
+      i = j;
+    } else {
+      let j = i;
+      while (j < s.length && !/\s/.test(s[j])) j++;
+      out.push(s.slice(i, j));
+      i = j;
+    }
+  }
+  return out;
+}
+
+// ─── Parse a triple-pattern string into [sNode, pNode, oNode] ───────────────
+export function parsePatternParts(pattern, rdflib, extraPrefixes = {}, baseUri = '') {
+  const tokens = tokenizeTriplePattern(pattern);
+  if (tokens.length !== 3) {
+    throw new Error(`Triple pattern must have exactly 3 parts (subject predicate object) — got ${tokens.length}`);
+  }
+  const s = triplePatternTermToNode(tokens[0], rdflib, extraPrefixes, baseUri);
+  const p = triplePatternTermToNode(tokens[1], rdflib, extraPrefixes, baseUri);
+  const o = triplePatternTermToNode(tokens[2], rdflib, extraPrefixes, baseUri);
+  return [s, p, o];
+}
+
+// ─── Extract variable names from a triple pattern ───────────────────────────
+export function patternVarNames(pattern) {
+  const tokens = tokenizeTriplePattern(pattern);
+  if (tokens.length !== 3) return {};
+  const out = {};
+  const slots = ['s', 'p', 'o'];
+  tokens.forEach((tok, i) => {
+    if (_NAMED_VAR_RE.test(tok)) out[slots[i]] = tok.slice(1);
+  });
+  return out;
+}
+
+// ─── store.match → W3C SPARQL Query Results JSON envelope ──────────────────
+export function matchStore(store, s, p, o, names = {}) {
+  const stmts = store.match(s, p, o, null);
+  const slots = [];
+  if (!s) slots.push('s');
+  if (!p) slots.push('p');
+  if (!o) slots.push('o');
+  if (!slots.length) slots.push('s', 'p', 'o');
+
+  const cols = slots.map(slot => names[slot] || slot);
+  const bindings = stmts.map(st => {
+    const row = {};
+    slots.forEach((slot, i) => {
+      const node = slot === 's' ? st.subject : slot === 'p' ? st.predicate : st.object;
+      row[cols[i]] = termToCell(node);
+    });
+    return row;
+  });
+  return w3cResults(cols, bindings);
+}
+
+// ─── SPARQL helpers ──────────────────────────────────────────────────────────
+export function selectVars(queryText) {
+  const stripped = queryText.replace(/#[^\n]*/g, '');
+  const m = stripped.match(/\bSELECT\s+(?:DISTINCT\s+|REDUCED\s+)?(.*?)\s+WHERE\b/is);
+  if (!m) return null;
+  const clause = m[1].trim();
+  if (clause === '*') return null;
+  const vars = clause.match(/\?\w+/g);
+  return vars ? vars.map(v => v.slice(1)) : null;
+}
+
+export function isRdfDoc(url) {
+  return /\.(ttl|rdf|n3|jsonld|nt|nq|owl|trig)(\?|#|$)/i.test(url);
+}
+
+export function bindingsToResults(bindings, queryText) {
+  const selectVarsResult = selectVars(queryText);
+  const allKeys = bindings.length
+    ? Object.keys(bindings[0]).map(k => k.replace(/^\?/, ''))
+    : [];
+  const vars = selectVarsResult ?? allKeys;
+  const out = bindings.map(b => {
+    const row = {};
+    for (const v of vars) {
+      const node = b[`?${v}`];
+      row[v] = node ? termToCell(node) : { type: 'literal', value: '' };
+    }
+    return row;
+  });
+  return w3cResults(vars, out);
+}

package/core/rdf-render.js

@@ -0,0 +1,136 @@
+// Turns the plain item descriptions produced by core/menu-rdf.js
+// (parseMenuItems) into DOM render closures. Shared by <sol-menu> and
+// <sol-tabs> so both render the identical ui:Menu RDF shape the same way.
+//
+// The descriptions are component-agnostic; only the closures below touch
+// the DOM. A host element supplies a `ctx`:
+//
+//   { host, baseUrl, sourceName, embedClass }
+//
+//   host        — element used for getAttribute('handler') and sol-error
+//   baseUrl     — the host module's import.meta.url, for handler resolution
+//   sourceName  — host tag name, used in error messages / event detail
+//   embedClass  — CSS class added to each embedded element
+//                 ('sol-menu-embed' / 'sol-tab-embed')
+
+import { siblingUrl } from './here.js';
+import { displayItem, contentForHref } from './display-target.js';
+
+/**
+ * A ui:Component's `ui:name` is either a custom-element tag (render that
+ * component) or a *command* — an opaque registry key the host app resolves.
+ * Custom-element names must contain a hyphen (HTML spec), so a bare name that
+ * isn't a registered element is a command. The name is NOT a tag, a global, or
+ * a script: clicking it dispatches `sol-command` for the app to map; an
+ * unregistered key is a no-op. Bounded entirely by the app's registry.
+ *
+ * @param {string} name  a ui:Component ui:name value
+ * @returns {boolean}    true when it should be treated as a command
+ */
+export function isCommandName(name) {
+  if (!name) return false;
+  return !name.includes('-') && !customElements.get(name);
+}
+
+/** ui:attribute/ui:parameter pairs [[k,v],…] → { k: v, … } command args. */
+export function paramsToObject(params) {
+  return Object.fromEntries(params || []);
+}
+
+/**
+ * Dispatch a menu command. `command` is the registry key (from a ui:Component
+ * `ui:name`); `params` is the args object. Bubbling + composed so one
+ * document-level listener in the host app catches it.
+ *
+ * @param {HTMLElement} host
+ * @param {string} command
+ * @param {object} [params]
+ */
+export function dispatchCommand(host, command, params) {
+  host.dispatchEvent(new CustomEvent('sol-command', {
+    bubbles: true, composed: true,
+    detail: { command, params: params || {}, source: host },
+  }));
+}
+
+/**
+ * Lazy-import a sibling sol-* handler module on first use, so authors
+ * don't have to <script> every component a declared item references.
+ *
+ * @param {string} tag        custom-element tag, e.g. "sol-query"
+ * @param {HTMLElement} host  element that emits sol-error on failure
+ * @param {string} baseUrl    importing component's import.meta.url
+ * @param {string} sourceName host tag name, for the warning / event
+ */
+export function ensureHandler(tag, host, baseUrl, sourceName) {
+  if (!/^sol-[a-z-]+$/.test(tag)) return;
+  if (customElements.get(tag)) return;
+  import(siblingUrl(`./${tag}.js`, baseUrl)).catch(err => {
+    const msg = `<${sourceName}> could not auto-load handler "${tag}" — make sure its module is reachable and any externals are in the importmap (${err.message})`;
+    console.warn(msg);
+    if (host) host.dispatchEvent(new CustomEvent('sol-error', {
+      bubbles: true, composed: true,
+      detail: { source: sourceName, kind: 'handler-load', tag, message: err.message },
+    }));
+  });
+}
+
+/**
+ * Build a render closure for a ui:Component part. Placement is resolved from
+ * the HTML at click time by the dispatcher (region= cascade off the host,
+ * `data-for` claim by this item's id, or the host's own body as fallback).
+ * Components default to keep-alive.
+ *
+ * @param {object} desc { id, name, tag, params }
+ * @param {object} ctx  { host, baseUrl, sourceName, embedClass }
+ * @returns {(body: HTMLElement) => void}
+ */
+export function renderComponentItem(desc, ctx) {
+  return (body) => {
+    const { id, name, tag, params } = desc;
+    if (!tag) return;
+    const ensure = (t) => ensureHandler(t, ctx.host, ctx.baseUrl, ctx.sourceName);
+    ensure(tag);
+    displayItem({
+      launcher: ctx.host, id, name: name || id,
+      tag, attrs: params, replace: false,
+      embedClass: ctx.embedClass, fallbackEl: body, ensure,
+    });
+  };
+}
+
+/**
+ * Build a render closure for a ui:Link part. A `ui:contents` literal is
+ * injected as HTML; otherwise the `ui:href` is rendered by the origin-inferred
+ * element (same-origin → trusted `sol-include`, external → `iframe`). A
+ * non-default viewer is expressed as a `ui:Component`, not a handler.
+ * Placement is resolved from the HTML by the dispatcher (region= / data-for).
+ *
+ * @param {object} desc { id, name, href, contents }
+ * @param {object} ctx  { host, baseUrl, sourceName, embedClass }
+ * @returns {(body: HTMLElement) => void}
+ */
+export function renderLinkItem(desc, ctx) {
+  return (body) => {
+    const { id, name, href, contents } = desc;
+    const ensure = (t) => ensureHandler(t, ctx.host, ctx.baseUrl, ctx.sourceName);
+
+    if (contents != null) {
+      displayItem({
+        launcher: ctx.host, id, name: name || id, contents,
+        embedClass: ctx.embedClass, fallbackEl: body, ensure,
+      });
+      return;
+    }
+    if (!href) return;
+
+    const { tag, attrs, replace } = contentForHref(href);
+    ensure(tag);
+
+    displayItem({
+      launcher: ctx.host, id, name: name || id,
+      tag, attrs, href, replace,
+      embedClass: ctx.embedClass, fallbackEl: body, ensure,
+    });
+  };
+}