dsh-featherhunter-plugin-base 0.0.1 → 0.0.2-drill

package/dist/client/index.js

@@ -2,9 +2,9 @@
 var BASELINE = {
   "manifest": {
     "schema": 1,
-    "version": "0.0.1",
-    "revision": 1,
-    "updatedAt": "2026-10-23T00:00:00+08:00",
+    "version": "0.0.2-drill",
+    "revision": 2,
+    "updatedAt": "2026-10-31T00:00:00+08:00",
     "fallbackUrl": "https://github.com/FeatherHunter/featherhunter-plugin-manage",
     "groups": [
       {
@@ -79,10 +79,10 @@ var BASELINE = {
           "zh": "DSH \u63D2\u4EF6\u4EA4\u6D41\u7FA4\u5FAE\u4FE1\u7FA4\u4E8C\u7EF4\u7801",
           "en": "DSH plugin community group WeChat QR code"
         },
-        "card": "card-wechat-2026-10-23.png",
+        "card": "card-wechat-2026-11-06.png",
         "qr": {
           "kind": "remote",
-          "path": "qr-wechat-2026-10-23.png"
+          "path": "qr-wechat-2026-11-06.png"
         },
         "title": {
           "zh": "DSH \u63D2\u4EF6\u4EA4\u6D41\u7FA4",
@@ -92,7 +92,7 @@ var BASELINE = {
           "zh": "\u7FA4\u804A\uFF1ADSH \u63D2\u4EF6\u4EA4\u6D41\u7FA4",
           "en": "Group chat: DSH Plugin Community"
         },
-        "validUntil": "2026-10-30"
+        "validUntil": "2026-11-06"
       }
     ],
     "plugins": [
@@ -227,6 +227,411 @@ function formatValidity(validUntil, options) {
   }
   return `\u8BE5\u4E8C\u7EF4\u7801 ${days} \u5929\u5185\uFF08${month} \u6708 ${day} \u65E5\u524D\uFF09\u6709\u6548\uFF0C\u91CD\u65B0\u8FDB\u5165\u5C06\u66F4\u65B0`;
 }
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString(record, key, where) {
+  const value = record[key];
+  if (typeof value !== "string" || value.length === 0) {
+    throw new Error(`manifest: ${where}.${key} must be a non-empty string`);
+  }
+  return value;
+}
+function requireI18n(record, key, where) {
+  const value = record[key];
+  if (!isRecord(value)) throw new Error(`manifest: ${where}.${key} must be an object`);
+  const zh = value.zh;
+  const en = value.en;
+  if (typeof zh !== "string" || zh.length === 0) {
+    throw new Error(`manifest: ${where}.${key}.zh must be a non-empty string`);
+  }
+  if (typeof en !== "string" || en.length === 0) {
+    throw new Error(`manifest: ${where}.${key}.en must be a non-empty string`);
+  }
+  return { zh, en };
+}
+function requireOrder(record, where) {
+  const value = record["order"];
+  if (typeof value !== "number" || !Number.isFinite(value)) {
+    throw new Error(`manifest: ${where}.order must be a number`);
+  }
+  return value;
+}
+function validateGroup(value, index) {
+  const where = `groups[${index}]`;
+  if (!isRecord(value)) throw new Error(`manifest: ${where} must be an object`);
+  const id = requireString(value, "id", where);
+  const platform = requireString(value, "platform", where);
+  const order = requireOrder(value, where);
+  const readmeTitle = requireI18n(value, "readmeTitle", where);
+  const alt = requireI18n(value, "alt", where);
+  const card = requireString(value, "card", where);
+  const title = requireI18n(value, "title", where);
+  const qrRaw = value["qr"];
+  if (!isRecord(qrRaw)) throw new Error(`manifest: ${where}.qr must be an object`);
+  const kind = qrRaw["kind"];
+  let qr;
+  if (kind === "bundled") {
+    qr = { kind: "bundled", key: requireString(qrRaw, "key", `${where}.qr`) };
+  } else if (kind === "remote") {
+    qr = { kind: "remote", path: requireString(qrRaw, "path", `${where}.qr`) };
+  } else {
+    throw new Error(`manifest: ${where}.qr.kind must be "bundled" or "remote"`);
+  }
+  const group = { id, platform, order, readmeTitle, alt, card, qr, title };
+  const subtitle = value["subtitle"];
+  if (subtitle !== void 0) {
+    if (!isRecord(subtitle)) throw new Error(`manifest: ${where}.subtitle must be an object`);
+    group.subtitle = requireI18n(value, "subtitle", where);
+  }
+  const note = value["note"];
+  if (note !== void 0) {
+    if (!isRecord(note)) throw new Error(`manifest: ${where}.note must be an object`);
+    group.note = requireI18n(value, "note", where);
+  }
+  const validUntil = value["validUntil"];
+  if (validUntil !== void 0) {
+    if (typeof validUntil !== "string" || parseDateOnly(validUntil) === null) {
+      throw new Error(`manifest: ${where}.validUntil must be a valid YYYY-MM-DD date`);
+    }
+    group.validUntil = validUntil;
+  }
+  return group;
+}
+function validatePlugin(value, index) {
+  const where = `plugins[${index}]`;
+  if (!isRecord(value)) throw new Error(`manifest: ${where} must be an object`);
+  const id = requireString(value, "id", where);
+  const order = requireOrder(value, where);
+  const verifiedAt = requireString(value, "verifiedAt", where);
+  if (parseDateOnly(verifiedAt) === null) {
+    throw new Error(`manifest: ${where}.verifiedAt must be a valid YYYY-MM-DD date`);
+  }
+  const name = requireString(value, "name", where);
+  const repo = requireString(value, "repo", where);
+  const desc = requireI18n(value, "desc", where);
+  const entry = { id, order, verifiedAt, name, repo, desc };
+  const url = value["url"];
+  if (url !== void 0) entry.url = requireString(value, "url", where);
+  return entry;
+}
+function parseManifest(raw) {
+  if (!isRecord(raw)) throw new Error("manifest: root must be an object");
+  if (raw["schema"] !== 1) throw new Error("manifest: schema must be 1");
+  const version = requireString(raw, "version", "manifest");
+  const revision = raw["revision"];
+  if (typeof revision !== "number" || !Number.isInteger(revision) || revision < 0) {
+    throw new Error("manifest: revision must be a non-negative integer");
+  }
+  const updatedAt = requireString(raw, "updatedAt", "manifest");
+  if (Number.isNaN(Date.parse(updatedAt))) {
+    throw new Error("manifest: updatedAt must be a parseable timestamp");
+  }
+  const fallbackUrl = requireString(raw, "fallbackUrl", "manifest");
+  if (!/^https?:\/\//.test(fallbackUrl)) {
+    throw new Error("manifest: fallbackUrl must be an absolute http(s) URL");
+  }
+  const groupsRaw = raw["groups"];
+  if (!Array.isArray(groupsRaw)) throw new Error("manifest: groups must be an array");
+  if (groupsRaw.length === 0) throw new Error("manifest: groups must not be empty");
+  const pluginsRaw = raw["plugins"];
+  if (!Array.isArray(pluginsRaw)) throw new Error("manifest: plugins must be an array");
+  if (pluginsRaw.length === 0) throw new Error("manifest: plugins must not be empty");
+  const groups = groupsRaw.map(validateGroup);
+  const plugins = pluginsRaw.map(validatePlugin);
+  const ids = /* @__PURE__ */ new Set();
+  for (const group of groups) {
+    if (ids.has(group.id)) throw new Error(`manifest: duplicate group id "${group.id}"`);
+    ids.add(group.id);
+  }
+  return { schema: 1, version, revision, updatedAt, fallbackUrl, groups, plugins };
+}
+
+// src/client/content.ts
+var PACKAGE_NAME = "dsh-featherhunter-plugin-base";
+var MANIFEST_TIMEOUT_MS = 1500;
+var MANIFEST_CACHE_TTL_MS = 30 * 60 * 1e3;
+var MAX_IMAGE_BYTES = 512 * 1024;
+var ALLOWED_CDN_HOSTS = [
+  "unpkg.com",
+  "registry.npmmirror.com",
+  "cdn.jsdelivr.net"
+];
+var SEMVER_PATTERN = /^\d+\.\d+\.\d+(?:-[0-9A-Za-z.-]+)?(?:\+[0-9A-Za-z.-]+)?$/;
+var PACKAGE_NAME_PATTERN = /^[a-z0-9][a-z0-9._-]*$/;
+var IMAGE_PATH_PATTERN = /^[a-z0-9][a-z0-9._-]*\.(?:png|jpe?g)$/i;
+var MAX_ID_LENGTH = 64;
+var MAX_TEXT_LENGTH = 200;
+var MAX_NOTE_LENGTH = 300;
+var MAX_PATH_LENGTH = 128;
+function fail(message) {
+  throw new Error("manifest: " + message);
+}
+function isRecord2(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function requireString2(value, field, maxLength) {
+  if (typeof value !== "string" || value.length === 0) fail(field + " must be a non-empty string");
+  if (value.length > maxLength) fail(field + " is longer than " + maxLength + " characters");
+  return value;
+}
+function requireI18nText(value, field) {
+  if (!isRecord2(value)) fail(field + " must be an object with zh/en");
+  requireString2(value["zh"], field + ".zh", MAX_TEXT_LENGTH);
+  requireString2(value["en"], field + ".en", MAX_TEXT_LENGTH);
+}
+function parseUrl(value) {
+  try {
+    return new URL(value);
+  } catch {
+    return null;
+  }
+}
+function isHttpsUrl(value) {
+  const url = parseUrl(value);
+  return url !== null && url.protocol === "https:";
+}
+function isAllowedCdnUrl(value) {
+  const url = parseUrl(value);
+  if (!url || url.protocol !== "https:") return false;
+  return ALLOWED_CDN_HOSTS.includes(url.hostname);
+}
+function imageUrls(version, path, packageName = PACKAGE_NAME) {
+  if (!SEMVER_PATTERN.test(version)) return [];
+  if (!IMAGE_PATH_PATTERN.test(path) || path.length > MAX_PATH_LENGTH) return [];
+  return [
+    "https://cdn.jsdelivr.net/npm/" + packageName + "@" + version + "/data/img/" + path,
+    "https://registry.npmmirror.com/" + packageName + "/" + version + "/files/data/img/" + path
+  ];
+}
+function defaultChannels(packageName = PACKAGE_NAME) {
+  const unpkgUrl = "https://unpkg.com/" + packageName + "@latest/data/manifest.json";
+  const npmmirrorLatest = "https://registry.npmmirror.com/" + packageName + "/latest";
+  const jsdelivrUrl = "https://cdn.jsdelivr.net/npm/" + packageName + "@latest/data/manifest.json";
+  return [
+    {
+      name: "unpkg",
+      load: async (context) => ({ raw: JSON.parse(await context.fetchText(unpkgUrl)), url: unpkgUrl })
+    },
+    {
+      // Two steps on purpose: the dist-tag document names the exact version,
+      // and only the versioned file listing is immutable enough to trust.
+      name: "npmmirror",
+      load: async (context) => {
+        const latest = await context.fetchJson(npmmirrorLatest);
+        const version = isRecord2(latest) ? latest["version"] : void 0;
+        if (typeof version !== "string" || !SEMVER_PATTERN.test(version)) {
+          fail("npmmirror latest is missing a usable version");
+        }
+        const url = "https://registry.npmmirror.com/" + packageName + "/" + version + "/files/data/manifest.json";
+        return { raw: JSON.parse(await context.fetchText(url)), url };
+      }
+    },
+    {
+      name: "jsdelivr",
+      load: async (context) => ({
+        raw: JSON.parse(await context.fetchText(jsdelivrUrl)),
+        url: jsdelivrUrl
+      })
+    }
+  ];
+}
+function validateRemoteManifest(raw) {
+  const manifest = parseManifest(raw);
+  if (!SEMVER_PATTERN.test(manifest.version)) fail("version must be a semantic version");
+  if (!isHttpsUrl(manifest.fallbackUrl)) fail("fallbackUrl must be https");
+  const seen = /* @__PURE__ */ new Set();
+  for (const group of manifest.groups) {
+    if (group.id.length > MAX_ID_LENGTH) fail("group id is too long");
+    if (seen.has(group.id)) fail("duplicate group id " + group.id);
+    seen.add(group.id);
+    requireString2(group.platform, "group.platform", MAX_ID_LENGTH);
+    requireI18nText(group.readmeTitle, "group.readmeTitle");
+    requireI18nText(group.alt, "group.alt");
+    requireI18nText(group.title, "group.title");
+    if (group.subtitle) requireI18nText(group.subtitle, "group.subtitle");
+    if (group.note) {
+      if (!isRecord2(group.note)) fail("group.note must be an object with zh/en");
+      requireString2(group.note.zh, "group.note.zh", MAX_NOTE_LENGTH);
+      requireString2(group.note.en, "group.note.en", MAX_NOTE_LENGTH);
+    }
+    requireString2(group.card, "group.card", MAX_PATH_LENGTH);
+    if (!IMAGE_PATH_PATTERN.test(group.card)) fail("group.card must be a png/jpg file name");
+    if (group.qr.kind === "remote") {
+      if (!IMAGE_PATH_PATTERN.test(group.qr.path)) fail("group.qr.path must be a png/jpg file name");
+      if (group.qr.path.length > MAX_PATH_LENGTH) fail("group.qr.path is too long");
+    } else {
+      requireString2(group.qr.key, "group.qr.key", MAX_ID_LENGTH);
+    }
+  }
+  return manifest;
+}
+function toDataUrl(bytes, contentType) {
+  let binary = "";
+  const chunk = 32768;
+  for (let index = 0; index < bytes.length; index += chunk) {
+    binary += String.fromCharCode(...bytes.subarray(index, index + chunk));
+  }
+  const type = contentType && contentType.startsWith("image/") ? contentType : "image/png";
+  return "data:" + type + ";base64," + btoa(binary);
+}
+var sessionCache = null;
+var inFlight = null;
+function resetContentCache() {
+  sessionCache = null;
+  inFlight = null;
+}
+var ContentLoader = class {
+  packageName;
+  timeoutMs;
+  maxImageBytes;
+  fetchImpl;
+  now;
+  channels;
+  constructor(options = {}) {
+    this.packageName = options.packageName ?? PACKAGE_NAME;
+    if (!PACKAGE_NAME_PATTERN.test(this.packageName)) {
+      throw new Error("invalid package name: " + this.packageName);
+    }
+    this.timeoutMs = options.timeoutMs ?? MANIFEST_TIMEOUT_MS;
+    this.maxImageBytes = options.maxImageBytes ?? MAX_IMAGE_BYTES;
+    this.now = options.now ?? (() => Date.now());
+    const injected = options.fetchImpl ?? globalThis.fetch;
+    if (typeof injected !== "function") throw new Error("fetch is not available in this environment");
+    this.fetchImpl = injected;
+    if (options.manifestUrl !== void 0) {
+      if (!isHttpsUrl(options.manifestUrl)) throw new Error("manifestUrl must be https");
+      const url = options.manifestUrl;
+      this.channels = [
+        { name: "custom", load: async (context) => ({ raw: JSON.parse(await context.fetchText(url)), url }) }
+      ];
+    } else if (options.channels) {
+      this.channels = options.channels.slice();
+    } else {
+      this.channels = defaultChannels(this.packageName);
+    }
+  }
+  /** Cached content when it is still inside the 30 minute window. */
+  getCached() {
+    if (!sessionCache) return null;
+    if (this.now() - sessionCache.at >= MANIFEST_CACHE_TTL_MS) return null;
+    return sessionCache.content;
+  }
+  /**
+   * Fetch and validate the manifest once per 30 minutes; concurrent callers
+   * share one request. Resolves to null when every channel failed.
+   */
+  load() {
+    const cached = this.getCached();
+    if (cached !== null || sessionCache !== null && this.now() - sessionCache.at < MANIFEST_CACHE_TTL_MS) {
+      return Promise.resolve(cached);
+    }
+    if (inFlight) return inFlight;
+    const startedAt = this.now();
+    const promise = this.fetchContent(startedAt).then((content) => {
+      sessionCache = { at: this.now(), content };
+      return content;
+    }).finally(() => {
+      inFlight = null;
+    });
+    inFlight = promise;
+    return promise;
+  }
+  /** Prefetch every remote QR image of a manifest (best effort). */
+  async ensureImages(content) {
+    const pending = [];
+    for (const group of content.manifest.groups) {
+      if (group.qr.kind !== "remote") continue;
+      const key = content.manifest.version + "/" + group.qr.path;
+      if (content.images.has(key)) continue;
+      pending.push(this.loadImage(content, group.qr.path, key));
+    }
+    await Promise.all(pending);
+  }
+  /** Data URI for a remote QR path, or null when it is not prefetched. */
+  imageFor(content, path) {
+    if (!content) return null;
+    return content.images.get(content.manifest.version + "/" + path) ?? null;
+  }
+  /** Warm the cache: manifest plus images. Never rejects. */
+  async preload() {
+    try {
+      const content = await this.load();
+      if (content) await this.ensureImages(content);
+    } catch {
+    }
+  }
+  async loadImage(content, path, key) {
+    for (const url of imageUrls(content.manifest.version, path, this.packageName)) {
+      if (!isAllowedCdnUrl(url)) continue;
+      try {
+        const data = await this.fetchImage(url);
+        if (data) {
+          content.images.set(key, data);
+          return;
+        }
+      } catch {
+      }
+    }
+  }
+  async fetchImage(url) {
+    const response = await this.request(url);
+    if (!response.ok) return null;
+    const declared = Number(response.headers.get("content-length"));
+    if (Number.isFinite(declared) && declared > this.maxImageBytes) return null;
+    const buffer = await response.arrayBuffer();
+    if (buffer.byteLength > this.maxImageBytes) return null;
+    return toDataUrl(new Uint8Array(buffer), response.headers.get("content-type"));
+  }
+  async fetchContent(fetchedAt) {
+    const context = {
+      packageName: this.packageName,
+      fetchText: (url) => this.fetchText(url),
+      fetchJson: async (url) => JSON.parse(await this.fetchText(url))
+    };
+    for (const channel of this.channels) {
+      try {
+        const result = await channel.load(context);
+        const manifest = validateRemoteManifest(result.raw);
+        return { manifest, source: channel.name, fetchedAt, images: /* @__PURE__ */ new Map() };
+      } catch {
+      }
+    }
+    return null;
+  }
+  async fetchText(url) {
+    const response = await this.request(url);
+    if (!response.ok) throw new Error("HTTP " + response.status);
+    return response.text();
+  }
+  /** One request with the 1.5s abort window; the timer is always cleared. */
+  async request(url) {
+    if (!isAllowedCdnUrl(url)) throw new Error("blocked url: " + url);
+    const controller = typeof AbortController === "function" ? new AbortController() : null;
+    let timer;
+    const timeout = new Promise((_resolve, reject) => {
+      timer = setTimeout(() => {
+        if (controller) controller.abort();
+        reject(new Error("timeout after " + this.timeoutMs + "ms"));
+      }, this.timeoutMs);
+    });
+    try {
+      const request = this.fetchImpl(url, {
+        signal: controller ? controller.signal : void 0,
+        cache: "no-store",
+        credentials: "omit"
+      });
+      request.catch(() => {
+      });
+      return await Promise.race([request, timeout]);
+    } finally {
+      if (timer !== void 0) clearTimeout(timer);
+    }
+  }
+};
+function createContentLoader(options = {}) {
+  return new ContentLoader(options);
+}
 
 // src/client/styles.ts
 var BASE_STYLE_ID = "dsh-base-style";
@@ -351,6 +756,7 @@ var FOCUSABLE_SELECTOR = 'a[href], button:not([disabled]), input:not([disabled])
 function mountContactModal(config) {
   const { doc, lang } = config;
   const win = doc.defaultView;
+  let current = config;
   const t = (key) => resolveText(key, lang, config.texts);
   ensureBaseStyles(doc);
   const dialog = doc.createElement("dialog");
@@ -388,8 +794,11 @@ function mountContactModal(config) {
   body.className = "dsh-base-modal__body";
   const grid = doc.createElement("div");
   grid.className = "dsh-base-modal__grid";
-  grid.style.setProperty("--dsh-base-columns", String(config.columns));
-  for (const group of sortByOrder(config.groups)) grid.append(buildCard(group));
+  function renderGroups(groups, columns) {
+    grid.style.setProperty("--dsh-base-columns", String(columns));
+    grid.replaceChildren(...sortByOrder(groups).map((group) => buildCard(group)));
+  }
+  renderGroups(current.groups, current.columns);
   body.append(grid);
   const footer = doc.createElement("div");
   footer.className = "dsh-base-modal__footer";
@@ -474,9 +883,9 @@ function mountContactModal(config) {
     const card = doc.createElement("div");
     card.className = "dsh-base-modal__card";
     card.dataset.groupId = group.id;
-    const expired = isExpired(group.validUntil, config.now);
+    const expired = isExpired(group.validUntil, current.now);
     if (expired) card.classList.add("dsh-base-modal__card--expired");
-    const qrSrc = expired ? null : config.resolveQr(group);
+    const qrSrc = expired ? null : current.resolveQr(group);
     const cardTitle = doc.createElement("h3");
     cardTitle.className = "dsh-base-modal__card-title";
     cardTitle.textContent = pickText(group.title, lang);
@@ -505,7 +914,7 @@ function mountContactModal(config) {
       note.textContent = t("expired");
       card.append(note);
     } else {
-      const validity = formatValidity(group.validUntil, { lang, now: config.now });
+      const validity = formatValidity(group.validUntil, { lang, now: current.now });
       const noteText = validity ?? (group.note ? pickText(group.note, lang) : null);
       if (noteText) {
         const note = doc.createElement("span");
@@ -517,7 +926,7 @@ function mountContactModal(config) {
     if (!qrSrc) {
       const link = doc.createElement("a");
       link.className = "dsh-base-modal__card-link";
-      link.href = config.fallbackUrl;
+      link.href = current.fallbackUrl;
       link.target = "_blank";
       link.rel = "noopener noreferrer";
       link.textContent = t("fallback");
@@ -545,9 +954,15 @@ function mountContactModal(config) {
       selectText();
     }
   }
+  function update(next) {
+    if (closed) return;
+    current = { ...current, ...next };
+    renderGroups(current.groups, current.columns);
+  }
   return {
     dialog,
-    close: (restoreFocus = true) => destroy(restoreFocus)
+    close: (restoreFocus = true) => destroy(restoreFocus),
+    update
   };
 }
 
@@ -683,6 +1098,11 @@ function resolveBaselineQr(group) {
   if (group.qr.kind !== "bundled") return null;
   return BASELINE.qr[group.qr.key] ?? null;
 }
+function resolveGroupQr(group, content, loader) {
+  if (group.qr.kind === "bundled") return resolveBaselineQr(group);
+  if (!content || !loader) return null;
+  return loader.imageFor(content, group.qr.path);
+}
 function mergeTexts(overrides, extra) {
   if (!overrides && !extra) return void 0;
   return { ...overrides, ...extra };
@@ -692,6 +1112,19 @@ function classes(base, extra) {
 }
 function createBaseUI(React, options = {}) {
   let active = null;
+  let loader = options.contentLoader ?? null;
+  function getLoader() {
+    if (loader) return loader;
+    try {
+      loader = createContentLoader({
+        manifestUrl: options.manifestUrl,
+        fetchImpl: options.fetchImpl
+      });
+    } catch {
+      loader = null;
+    }
+    return loader;
+  }
   function widgetText(key) {
     return resolveText(key, detectLang(options.lang), options.texts);
   }
@@ -705,6 +1138,41 @@ function createBaseUI(React, options = {}) {
   function closeContactModal() {
     closeActive(true);
   }
+  function buildResolver(callOptions, content) {
+    const custom = callOptions.resolveQr ?? options.resolveQr;
+    if (custom) return custom;
+    return (group) => resolveGroupQr(group, content, loader);
+  }
+  function applyContent(handle, content) {
+    if (active !== handle) return;
+    const groups = content.manifest.groups.length > 0 ? content.manifest.groups : BASELINE.manifest.groups;
+    handle.update({
+      groups,
+      columns: clampColumns(void 0, groups.length),
+      fallbackUrl: content.manifest.fallbackUrl,
+      resolveQr: (group) => resolveGroupQr(group, content, loader) ?? null
+    });
+  }
+  async function refreshRemote(handle, callOptions) {
+    if (callOptions.groups && callOptions.groups.length > 0) return;
+    const currentLoader = getLoader();
+    if (!currentLoader) return;
+    const content = await currentLoader.load();
+    if (!content || active !== handle) return;
+    await currentLoader.ensureImages(content);
+    if (active !== handle) return;
+    const custom = callOptions.resolveQr ?? options.resolveQr;
+    if (custom) {
+      handle.update({
+        groups: content.manifest.groups,
+        columns: clampColumns(callOptions.columns ?? options.columns, content.manifest.groups.length),
+        fallbackUrl: content.manifest.fallbackUrl,
+        resolveQr: (group) => custom(group) ?? null
+      });
+      return;
+    }
+    applyContent(handle, content);
+  }
   function openContactModal(callOptions = {}) {
     if (typeof document === "undefined") return () => {
     };
@@ -716,14 +1184,15 @@ function createBaseUI(React, options = {}) {
     const lang = detectLang(callOptions.lang ?? options.lang);
     const candidate = callOptions.trigger ?? document.activeElement;
     const trigger = candidate && typeof candidate.focus === "function" ? candidate : null;
-    const resolver = callOptions.resolveQr ?? options.resolveQr ?? resolveBaselineQr;
+    const cached = getLoader()?.getCached() ?? null;
+    const resolver = buildResolver(callOptions, cached);
     const handle = mountContactModal({
       doc: document,
       lang,
       groups,
       columns: clampColumns(callOptions.columns ?? options.columns, groups.length),
       trigger,
-      fallbackUrl: callOptions.fallbackUrl ?? options.fallbackUrl ?? BASELINE.manifest.fallbackUrl,
+      fallbackUrl: callOptions.fallbackUrl ?? options.fallbackUrl ?? cached?.manifest.fallbackUrl ?? BASELINE.manifest.fallbackUrl,
       texts: mergeTexts(options.texts, callOptions.texts),
       resolveQr: (group) => resolver(group) ?? null,
       now: callOptions.now
@@ -734,6 +1203,7 @@ function createBaseUI(React, options = {}) {
       if (active === handle) active = null;
       if (sharedModal === handle) sharedModal = null;
     });
+    void refreshRemote(handle, callOptions);
     return () => {
       if (active === handle) active = null;
       if (sharedModal === handle) sharedModal = null;
@@ -806,6 +1276,15 @@ function createBaseUI(React, options = {}) {
     });
   }
   async function preloadContent() {
+    const currentLoader = getLoader();
+    if (!currentLoader) return;
+    await currentLoader.preload();
+    if (options.resolveQr) return;
+    const content = currentLoader.getCached();
+    const handle = active;
+    if (!content || !handle) return;
+    if (active !== handle) return;
+    applyContent(handle, content);
   }
   return {
     ContactButton,
@@ -817,10 +1296,22 @@ function createBaseUI(React, options = {}) {
   };
 }
 export {
+  ALLOWED_CDN_HOSTS,
   BASE_CSS,
   BASE_STYLE_ID,
+  ContentLoader,
+  MANIFEST_CACHE_TTL_MS,
+  MANIFEST_TIMEOUT_MS,
+  MAX_IMAGE_BYTES,
   MESSAGES,
   createBaseUI,
+  createContentLoader,
+  defaultChannels,
   ensureBaseStyles,
-  resolveText
+  imageUrls,
+  isAllowedCdnUrl,
+  isHttpsUrl,
+  resetContentCache,
+  resolveText,
+  validateRemoteManifest
 };

package/dist/client/modal.d.ts

@@ -15,10 +15,24 @@ export interface ContactModalConfig {
     /** Clock override for date-dependent validity text. */
     now?: Date;
 }
+export interface ContactModalUpdate {
+    groups?: readonly Group[];
+    /** Already clamped to 1..4 columns. */
+    columns?: number;
+    /** Returns null when no image is available (card degrades to a link). */
+    resolveQr?: (group: Group) => string | null;
+    fallbackUrl?: string;
+    now?: Date;
+}
 export interface ContactModalHandle {
     dialog: HTMLDialogElement;
     /** Destroy the dialog; restore focus by default. */
     close: (restoreFocus?: boolean) => void;
+    /**
+     * Re-render the group cards in place. Used when the remote manifest arrives
+     * after the baseline was painted, so the dialog is never rebuilt.
+     */
+    update: (next: ContactModalUpdate) => void;
 }
 /**
  * Build the contact dialog, enter it into the top layer with showModal() and

package/dist/client/types.d.ts

@@ -1,5 +1,6 @@
 import type { ComponentType } from "react";
 import type { Group, Lang, PluginEntry } from "../core/types";
+import type { ContentLoader, FetchLike } from "./content";
 import type { TextOverrides } from "./texts";
 /**
  * Resolve the image source for a group's QR code.
@@ -18,6 +19,10 @@ export interface BaseUIOptions {
     selfId?: string;
     /** Manifest URL override (defaults to the published CDN manifest). */
     manifestUrl?: string;
+    /** Fetch implementation override (testing seam). */
+    fetchImpl?: FetchLike;
+    /** Pre-built content loader override (testing seam). */
+    contentLoader?: ContentLoader;
     /** Text overrides keyed by message id. */
     texts?: TextOverrides;
     /** Max columns of the contact grid (hard ceiling: 4). */