From c4f29615da7abc94073515e6063fbe64614c398c Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 30 Sep 2026 11:36:40 +0000
Subject: [PATCH 1/2] fix: compatibility and robustness hardening, 0.1.2

No consumer config changes are needed; only inputs that were already
silently broken now fail at build time.

- tracking: never touch window/document when they are absent, so the
  enhancement is a no-op in SSR/tests instead of a ReferenceError;
  recognise cross-realm elements by nodeType
- tracking: isolate the one-widget:click dispatch and the dataLayer push
  so a throwing listener or a non-array dataLayer cannot break the other
  sink or navigation; one bad widget no longer stops the rest
- tracking: report middle-click opens via auxclick; ignore right clicks
- tracking: match ?from= case-insensitively after trimming, and report
  the configured spelling so buckets stay low-cardinality
- render: return "" when no item is enabled instead of an empty <nav>
  landmark; blank ariaLabel falls back to the default; trim tracking
  strings and de-duplicate the allowlist; accept null options
- model: treat null optional fields (JSON/CMS exports) as unset; reject
  mailto: links without a recipient
- registry: normalise declared hosts like URL#hostname (case, IDN,
  trailing dot, pasted scheme) while leaving path-scoped entries
  unmatched as before; protocols may omit the colon; a differently-cased
  custom key replaces the built-in; accept Map definitions; reject
  non-object platforms/icons and non-Map registries with clear errors
- package: add main/types/typesVersions and "default" export conditions
  so node10 resolution and default-only tooling resolve entries and types
- types: readonly item arrays, nullable options, TrackingEnvironment
  exported from the main entry
- css: wrap long labels, keep the focus ring unclipped in the inline
  scroller, :focus fallback without :focus-visible, forced-colors
  borders, clip-path for sr-only text
- ci: GitHub Actions on Node 20/22/24 plus Astro 5/6/7 fixture builds
- docs: CHANGELOG 0.1.2 (unreleased), README and architecture notes

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SSHDa6j758YbQZUK7QHez4
---
 .github/workflows/ci.yml |  46 ++++++++++++++++
 CHANGELOG.md             |  33 ++++++++++++
 README.md                |   9 ++--
 docs/architecture.md     |  11 +++-
 package.json             |  17 ++++--
 src/icons.js             |  14 ++++-
 src/index.d.ts           |  29 ++++++----
 src/model.js             |  26 ++++++---
 src/registry.js          |  66 ++++++++++++++++++++---
 src/render.js            |  62 +++++++++++++--------
 src/styles.css           |  46 ++++++++++++++++
 src/tracking.d.ts        |  15 ++----
 src/tracking.js          | 114 +++++++++++++++++++++++++++++----------
 test/model.test.js       |  76 ++++++++++++++++++++++++++
 test/render.test.js      |  37 +++++++++++++
 test/tracking.test.js    |  68 ++++++++++++++++++++++-
 16 files changed, 576 insertions(+), 93 deletions(-)
 create mode 100644 .github/workflows/ci.yml

diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml
new file mode 100644
index 0000000..91b29aa
--- /dev/null
+++ b/.github/workflows/ci.yml
@@ -0,0 +1,46 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+    tags: ["v*"]
+  pull_request:
+
+permissions:
+  contents: read
+
+jobs:
+  check:
+    name: Node ${{ matrix.node }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # engines.node is ">=20": test the floor plus current releases.
+        node: [20, 22, 24]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: ${{ matrix.node }}
+      - run: npm run check
+      - run: npm run pack:check
+
+  astro:
+    name: Astro ${{ matrix.astro }}
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        # Mirrors peerDependencies.astro ("^5 || ^6 || ^7").
+        astro: [5, 6, 7]
+    defaults:
+      run:
+        working-directory: test/fixtures/astro
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with:
+          node-version: 22
+      - run: npm install --no-audit --no-fund
+      - run: npm run verify:astro${{ matrix.astro }}
diff --git a/CHANGELOG.md b/CHANGELOG.md
index e50b894..b31aec8 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,6 +2,39 @@
 
 版本策略见 [README 的「升级与版本策略」](README.md#升级与版本策略)。每条变更都标注**调用方是否需要改配置**，升级时只读这一列即可。
 
+## 0.1.2 - 未发布
+
+需要改配置：否。兼容性与健壮性加固，现有 `items` / `tracking` 配置原样可用。只有此前就会静默出错的输入会改为构建期报错（见最后三条）。
+
+行为变化（无需改配置，但升级后数据或输出可能不同）：
+
+- 归因：`?from=` 的值会去掉首尾空白并忽略大小写匹配 allowlist，上报时统一使用配置里的写法。此前 `?from=GitHub`、`?from=blog%20` 会被归为 `other`。
+- 归因：中键点击（“在新标签页打开”）现在也会上报。此前浏览器不为中键触发 `click`，这部分访问会漏记；右键不上报。
+- 渲染：所有条目都 `enabled: false` 时 `renderPromotionLinks()` 返回空字符串，不再输出一个空的、带名字的 `<nav>` 地标。
+- 渲染：`tracking` 的字符串值与 `allowedSources` 会去除首尾空白，allowlist 去重；空白的 `ariaLabel` 回落到默认的 `Project links`。
+
+健壮性：
+
+- 客户端增强在没有 `window` / `document` 的环境（SSR、测试、Worker）里调用不再抛 `ReferenceError`；跨 iframe 的元素按 `nodeType` 识别。
+- 点击时 `one-widget:click` 与 `dataLayer` 两条上报互相隔离：页面监听器抛错、或站点把 `dataLayer` 定义成非数组，都不会影响另一条，也不会影响跳转。
+- `enhancePromotionWidgets()` 中某个 widget 出错不再中断同页其它 widget 的增强。
+- CMS / JSON 导出的 `null` 可选字段按“未设置”处理，不再报类型错误。
+- `renderPromotionLinks()` / `normalizePromotionItems()` 接受 `options` 为 `null`；`platforms` / `icons` 除对象外也接受 `Map`。
+- 平台 `hosts` 按 `URL#hostname` 的规则规范化：大小写、国际化域名（punycode）、结尾点号、误贴的 `https://…/` 都能匹配；`protocols` 可省略冒号（`"mailto"`）。自定义平台键以大小写不同的方式覆盖内建平台（如 `GitHub`）时替换而不是并存。
+
+兼容性：
+
+- `package.json` 增加 `main`、`types`、`typesVersions` 以及导出的 `default` 条件：TypeScript `moduleResolution: "node10"` 与只认 `default`/`require` 条件的工具也能解析入口和类型。
+- 类型：函数参数接受 `readonly` 数组（`as const` 配置可直接传入），`TrackingEnvironment` 从主入口导出。
+- 样式：长标签（URL、无空格的中文）自动换行，不再撑破 390px 视口；`inline` 布局的滚动容器不再裁掉焦点环；不支持 `:focus-visible` 的浏览器回落为 `:focus` 焦点环；Windows 高对比度模式下按钮保留系统色边框；读屏专用文本改用 `clip-path`。
+- CI：新增 GitHub Actions，在 Node 20 / 22 / 24 上跑 `npm run check`，并用 Astro 5 / 6 / 7 实际构建 fixture。本版已在本地 Astro 5.18.2 / 6.4.8 / 7.3.5 上构建并断言通过。
+
+新增构建期报错（仅针对此前就无法正常工作的配置）：
+
+- `mailto:` 链接没有收件人（`mailto:`、`mailto:?subject=…`）。
+- `platforms` / `icons` 传入数组或非对象。此前数组会生成名为 `"0"`、`"1"` 的平台。
+- `options.registry` / `options.iconRegistry` 不是 `Map`。此前会在渲染中途抛出含义不明的错误。
+
 ## 0.1.1 - 2026-09-24
 
 需要改配置：否。全部为可选新增或修正，现有 `items` / `tracking` 配置不升级也能继续工作。
diff --git a/README.md b/README.md
index 8c67de2..17919c3 100644
--- a/README.md
+++ b/README.md
@@ -74,7 +74,9 @@ const items = [
 2. 点击时派发 `one-widget:click` DOM 事件；
 3. 若页面使用 GTM，则向 `window.dataLayer` 推送同名分析事件。
 
-未知来源统一归入 `other`，没有参数时归入 `direct`。查询参数不会被拼到付款链接上。
+未知来源统一归入 `other`，没有参数时归入 `direct`。来源值会去掉首尾空白并忽略大小写匹配（`?from=GitHub` 记为配置里的 `github`），中键“在新标签页打开”也会上报。查询参数不会被拼到付款链接上。
+
+增强脚本是尽力而为的：没有 `window`/`document` 时不做任何事；页面监听器抛错或 `dataLayer` 被定义成非数组时，另一条上报和链接跳转都不受影响。
 
 Eigentime 现有 `/zh/support/` 与 `/en/support/` 的具体替换方式见 [docs/eigentime-integration.md](docs/eigentime-integration.md)。
 
@@ -120,7 +122,8 @@ interface PromotionItem {
 
 - 未显式设置 `order` 的条目会以它在数组中的下标作为 `order`,再与其它条目一起排序。因此只给部分条目写 `order` 时,未写的那条可能穿插到中间(例如 `order: 1`、下标 2、`order: 5` 会排成 `1, 2, 5`)。要精确控制顺序,建议要么全写、要么全不写。
 - 相同 `order` 时,数组顺序作为稳定后备顺序。
-- `enabled: false` 会保留配置但不渲染，适合临时下线某个平台。
+- `enabled: false` 会保留配置但不渲染，适合临时下线某个平台。全部条目都被禁用时整个组件输出空字符串，不会留下空的 `<nav>`。
+- 来自 CMS / JSON 的 `null` 可选字段等同于未填写。
 - 未填 `platform` 时会根据 URL 推断；显式值始终优先。
 - 未填 `kind`、`icon`、`appearance`、`emphasis` 时，才从平台注册与业务语义推导默认值。
 - `appearance: "icon"` 仍保留 `aria-label` 和屏幕阅读器文本，可点击区域固定不小于 44×44px。
@@ -197,6 +200,6 @@ npm run verify:astro6
 npm run verify:astro7
 ```
 
-最近一次多版本验证：Astro 5.18.2、6.4.8、7.3.4，三个大版本均构建并断言通过。
+最近一次多版本验证：Astro 5.18.2、6.4.8、7.3.5，三个大版本均构建并断言通过。GitHub Actions 会在每次推送时于 Node 20 / 22 / 24 上跑 `npm run check`，并用 Astro 5 / 6 / 7 构建 fixture。
 
 架构与稳定 API 边界见 [docs/architecture.md](docs/architecture.md)。
diff --git a/docs/architecture.md b/docs/architecture.md
index 08a50c5..d83d12a 100644
--- a/docs/architecture.md
+++ b/docs/architecture.md
@@ -54,14 +54,21 @@ tracking.js：可选的来源归因与事件增强
 配置错误在构建期抛出异常，而不是悄悄隐藏：
 
 - ID 重复或格式不合法；
-- URL 不是绝对地址、协议不安全或含内嵌凭据；
+- URL 不是绝对地址、协议不安全、含内嵌凭据，或 `mailto:` 没有收件人；
 - `kind`、`appearance`、`emphasis`、layout、theme 不属于支持值；
 - 布尔字段或数值字段类型错误；
 - `eventName` 为空串或纯空白；
-- 自定义图标缺少 `viewBox` 或 path。
+- 自定义图标缺少 `viewBox` 或 path；
+- `platforms` / `icons` 不是对象或 `Map`，`registry` / `iconRegistry` 不是 `Map`。
+
+`null` 可选字段视为未设置，因为这是 JSON / CMS 表达“没填”的常见方式，而不是配置错误。
 
 只有两类情况使用可预期的 fallback：未知平台使用 `custom` 语义；找不到图标 key 时使用中性的 link 图标。前者保证新平台无需升级包，后者保证图标配置错误不会让链接本身消失。
 
+新增校验只针对此前就会静默出错的输入，已能正常渲染的配置升级后不会开始报错，这是“升级不需要重新配置”的一部分。
+
+客户端增强相反，永远不抛错：缺少 DOM 全局对象时直接跳过，`one-widget:click` 派发与 `dataLayer` 推送各自 `try/catch`，单个 widget 失败不影响同页其它 widget。它丢失的只是归因，不能影响链接本身。
+
 ## 安全边界
 
 - 所有 label、class、URL、data attribute 与 SVG path 属性都会 HTML 转义；
diff --git a/package.json b/package.json
index 2793e2a..fe946b4 100644
--- a/package.json
+++ b/package.json
@@ -1,21 +1,32 @@
 {
   "name": "@eigentime/one-widget",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "Static-first, accessible promotion and sponsorship links for Eigentime and other sites.",
   "type": "module",
+  "main": "./src/index.js",
+  "types": "./src/index.d.ts",
+  "typesVersions": {
+    "*": {
+      "tracking": [
+        "./src/tracking.d.ts"
+      ]
+    }
+  },
   "sideEffects": [
     "./src/styles.css"
   ],
   "exports": {
     ".": {
       "types": "./src/index.d.ts",
-      "import": "./src/index.js"
+      "import": "./src/index.js",
+      "default": "./src/index.js"
     },
     "./astro": "./src/astro/PromotionLinks.astro",
     "./styles.css": "./src/styles.css",
     "./tracking": {
       "types": "./src/tracking.d.ts",
-      "import": "./src/tracking.js"
+      "import": "./src/tracking.js",
+      "default": "./src/tracking.js"
     },
     "./package.json": "./package.json"
   },
diff --git a/src/icons.js b/src/icons.js
index 80a9070..2554b56 100644
--- a/src/icons.js
+++ b/src/icons.js
@@ -76,7 +76,12 @@ export function createIconRegistry(customIcons = {}) {
   // Custom keys are lowercased to stay consistent with registerIcon() and the
   // lowercased item.icon lookup in model.js; otherwise a key like "Forge"
   // would never match and silently fall back to the default link icon.
-  for (const [key, definition] of Object.entries(customIcons)) {
+  if (customIcons !== null && customIcons !== undefined
+    && (typeof customIcons !== "object" || Array.isArray(customIcons))) {
+    throw new TypeError("icons must be an object keyed by icon name.");
+  }
+  const customEntries = customIcons instanceof Map ? [...customIcons] : Object.entries(customIcons ?? {});
+  for (const [key, definition] of customEntries) {
     const normalizedKey = String(key).trim().toLowerCase();
     if (!normalizedKey) throw new TypeError("Icon key cannot be empty.");
     registry.set(normalizedKey, normalizeIconDefinition(normalizedKey, definition));
@@ -84,10 +89,15 @@ export function createIconRegistry(customIcons = {}) {
   return registry;
 }
 
-export function registerIcon(registry, key, definition) {
+export function assertIconRegistry(registry) {
   if (!(registry instanceof Map)) {
     throw new TypeError("Icon registry must be a Map created by createIconRegistry().");
   }
+  return registry;
+}
+
+export function registerIcon(registry, key, definition) {
+  assertIconRegistry(registry);
   const normalizedKey = String(key).trim().toLowerCase();
   if (!normalizedKey) throw new TypeError("Icon key cannot be empty.");
 
diff --git a/src/index.d.ts b/src/index.d.ts
index 64bb175..277772f 100644
--- a/src/index.d.ts
+++ b/src/index.d.ts
@@ -57,8 +57,16 @@ export interface RenderOptions {
   tracking?: TrackingOptions;
   registry?: Map<string, Required<PlatformDefinition>>;
   iconRegistry?: Map<string, IconDefinition>;
-  platforms?: Record<string, PlatformDefinition>;
-  icons?: Record<string, IconDefinition>;
+  platforms?: Record<string, PlatformDefinition> | Map<string, PlatformDefinition>;
+  icons?: Record<string, IconDefinition> | Map<string, IconDefinition>;
+}
+
+export interface TrackingEnvironment {
+  location?: Pick<Location, "search">;
+  globalObject?: (Window & { dataLayer?: Array<Record<string, unknown>> }) | { dataLayer?: Array<Record<string, unknown>> };
+  Element?: typeof Element;
+  HTMLAnchorElement?: typeof HTMLAnchorElement;
+  CustomEvent?: typeof CustomEvent;
 }
 
 export interface NormalizedPromotionItem extends Required<Omit<PromotionItem, "shortLabel" | "eventName">> {
@@ -71,15 +79,16 @@ export const PROMOTION_KINDS: readonly PromotionKind[];
 export const BUILTIN_PLATFORMS: readonly string[];
 export const BUILTIN_ICONS: readonly string[];
 
-export function createPlatformRegistry(customPlatforms?: Record<string, PlatformDefinition>): Map<string, Required<PlatformDefinition>>;
+export function createPlatformRegistry(customPlatforms?: Record<string, PlatformDefinition> | Map<string, PlatformDefinition> | null): Map<string, Required<PlatformDefinition>>;
 export function registerPlatform(registry: Map<string, Required<PlatformDefinition>>, key: string, definition: PlatformDefinition): Map<string, Required<PlatformDefinition>>;
 export function inferPlatform(url: string | URL, registry?: Map<string, Required<PlatformDefinition>>): string | undefined;
-export function createIconRegistry(customIcons?: Record<string, IconDefinition>): Map<string, IconDefinition>;
+export function createIconRegistry(customIcons?: Record<string, IconDefinition> | Map<string, IconDefinition> | null): Map<string, IconDefinition>;
 export function registerIcon(registry: Map<string, IconDefinition>, key: string, definition: IconDefinition): Map<string, IconDefinition>;
 export function normalizeUrl(value: string, path?: string): string;
-export function normalizePromotionItems(items: PromotionItem[], options?: RenderOptions): NormalizedPromotionItem[];
-export function renderableItems(items: PromotionItem[], options?: RenderOptions): NormalizedPromotionItem[];
-export function renderPromotionLinks(items: PromotionItem[], options?: RenderOptions): string;
-export function resolveTrackingSource(search: string, config?: TrackingOptions): string;
-export function enhancePromotionWidget(root: Element, environment?: Record<string, unknown>): void;
-export function enhancePromotionWidgets(scope?: ParentNode): void;
+export function normalizePromotionItems(items: readonly PromotionItem[], options?: RenderOptions | null): NormalizedPromotionItem[];
+export function renderableItems(items: readonly PromotionItem[], options?: RenderOptions | null): NormalizedPromotionItem[];
+/** Returns an empty string when no item is enabled, so no empty landmark is emitted. */
+export function renderPromotionLinks(items: readonly PromotionItem[], options?: RenderOptions | null): string;
+export function resolveTrackingSource(search: string | null | undefined, config?: TrackingOptions | null): string;
+export function enhancePromotionWidget(root: Element, environment?: TrackingEnvironment | null): void;
+export function enhancePromotionWidgets(scope?: ParentNode | null): void;
diff --git a/src/model.js b/src/model.js
index 3bb7f1a..000783a 100644
--- a/src/model.js
+++ b/src/model.js
@@ -1,4 +1,4 @@
-import { createPlatformRegistry, inferPlatform } from "./registry.js";
+import { assertPlatformRegistry, createPlatformRegistry, inferPlatform } from "./registry.js";
 
 export const PROMOTION_KINDS = Object.freeze([
   "social",
@@ -36,6 +36,11 @@ export function normalizeUrl(value, path = "url") {
   if ((parsed.protocol === "http:" || parsed.protocol === "https:") && !parsed.hostname) {
     throw new TypeError(`${path} must include a hostname.`);
   }
+  // "mailto:" or "mailto:?subject=hi" parses fine but opens an empty draft
+  // with no recipient, which is never what a promotion link intends.
+  if (parsed.protocol === "mailto:" && !parsed.pathname.trim()) {
+    throw new TypeError(`${path} must include an email address.`);
+  }
   if (parsed.username || parsed.password) {
     throw new TypeError(`${path} must not contain embedded credentials.`);
   }
@@ -62,11 +67,14 @@ function defaultIcon(kind) {
   return "link";
 }
 
-export function normalizePromotionItems(items, options = {}) {
+export function normalizePromotionItems(items, options) {
   if (!Array.isArray(items)) throw new TypeError("items must be an array.");
+  options ??= {};
 
-  const registry = options.registry ?? createPlatformRegistry(options.platforms);
-  if (options.openInNewTab !== undefined && typeof options.openInNewTab !== "boolean") {
+  const registry = options.registry
+    ? assertPlatformRegistry(options.registry)
+    : createPlatformRegistry(options.platforms);
+  if (options.openInNewTab != null && typeof options.openInNewTab !== "boolean") {
     throw new TypeError("options.openInNewTab must be a boolean.");
   }
   const defaultOpenInNewTab = options.openInNewTab ?? true;
@@ -104,18 +112,20 @@ export function normalizePromotionItems(items, options = {}) {
       throw new TypeError(`${path}.emphasis must be primary, secondary, or quiet.`);
     }
 
+    // null is what JSON / CMS exports emit for "not set", so treat it like
+    // undefined for every optional field instead of failing on it.
     const order = item.order ?? index;
     if (!Number.isFinite(order)) throw new TypeError(`${path}.order must be a finite number.`);
-    if (item.enabled !== undefined && typeof item.enabled !== "boolean") {
+    if (item.enabled != null && typeof item.enabled !== "boolean") {
       throw new TypeError(`${path}.enabled must be a boolean.`);
     }
-    if (item.openInNewTab !== undefined && typeof item.openInNewTab !== "boolean") {
+    if (item.openInNewTab != null && typeof item.openInNewTab !== "boolean") {
       throw new TypeError(`${path}.openInNewTab must be a boolean.`);
     }
-    if (item.icon !== undefined && item.icon !== false && (typeof item.icon !== "string" || !item.icon.trim())) {
+    if (item.icon != null && item.icon !== false && (typeof item.icon !== "string" || !item.icon.trim())) {
       throw new TypeError(`${path}.icon must be a non-empty string or false.`);
     }
-    if (item.eventName !== undefined && (typeof item.eventName !== "string" || !item.eventName.trim())) {
+    if (item.eventName != null && (typeof item.eventName !== "string" || !item.eventName.trim())) {
       throw new TypeError(`${path}.eventName must be a non-empty string.`);
     }
 
diff --git a/src/registry.js b/src/registry.js
index 6eb8be5..9a3521b 100644
--- a/src/registry.js
+++ b/src/registry.js
@@ -71,6 +71,34 @@ const PLATFORM_DEFINITIONS = {
   }
 };
 
+// Hosts are compared against URL#hostname, which is lowercase, punycoded and
+// may carry a trailing dot. Normalise declared hosts the same way so that
+// "例子.com", "Code.Example.org." or a pasted "https://code.example.org/" still
+// match. Anything else is kept as-is, because it never matched before either:
+// an unparsable value must not turn into a build error, and an entry with a
+// path ("github.com/someone") must not silently widen to the whole host.
+function normalizeHost(host) {
+  const raw = String(host).trim().toLowerCase();
+  if (!raw) return "";
+  try {
+    const parsed = new URL(raw.includes("://") ? raw : `http://${raw}`);
+    if (parsed.pathname !== "/" || parsed.search || parsed.hash || parsed.port) return raw;
+    return stripTrailingDot(parsed.hostname) || raw;
+  } catch {
+    return raw;
+  }
+}
+
+function normalizeProtocol(protocol) {
+  const raw = String(protocol).trim().toLowerCase();
+  if (!raw) return "";
+  return raw.endsWith(":") ? raw : `${raw}:`;
+}
+
+function stripTrailingDot(hostname) {
+  return hostname.endsWith(".") ? hostname.slice(0, -1) : hostname;
+}
+
 function normalizePlatformDefinition(key, definition) {
   if (!definition || typeof definition !== "object") {
     throw new TypeError(`Platform "${key}" must be an object.`);
@@ -81,31 +109,57 @@ function normalizePlatformDefinition(key, definition) {
     defaultLabel: definition.defaultLabel ?? key,
     icon: definition.icon ?? "link",
     hosts: Array.isArray(definition.hosts)
-      ? definition.hosts.map((host) => String(host).trim().toLowerCase()).filter(Boolean)
+      ? definition.hosts.map(normalizeHost).filter(Boolean)
       : [],
     protocols: Array.isArray(definition.protocols)
-      ? definition.protocols.map((protocol) => String(protocol).trim().toLowerCase()).filter(Boolean)
+      ? definition.protocols.map(normalizeProtocol).filter(Boolean)
       : []
   };
 }
 
 export function createPlatformRegistry(customPlatforms = {}) {
   const registry = new Map();
-  for (const [key, definition] of Object.entries({ ...PLATFORM_DEFINITIONS, ...customPlatforms })) {
-    const normalizedKey = key.trim().toLowerCase();
+  for (const [key, definition] of Object.entries(PLATFORM_DEFINITIONS)) {
+    registry.set(key, normalizePlatformDefinition(key, definition));
+  }
+  // Custom keys are applied after the built-ins and normalised first, so a
+  // custom "GitHub" replaces the built-in "github" instead of coexisting with it.
+  for (const [key, definition] of entries(customPlatforms, "platforms")) {
+    const normalizedKey = String(key).trim().toLowerCase();
+    if (!normalizedKey) throw new TypeError("Platform key cannot be empty.");
+    registry.delete(normalizedKey);
     registry.set(normalizedKey, normalizePlatformDefinition(normalizedKey, definition));
   }
   return registry;
 }
 
-export function registerPlatform(registry, key, definition) {
+// Accepts a plain object (the documented form) or a Map, which is what a
+// caller building definitions programmatically tends to reach for.
+function entries(value, name) {
+  if (value === undefined || value === null) return [];
+  if (value instanceof Map) return [...value];
+  if (typeof value !== "object" || Array.isArray(value)) {
+    throw new TypeError(`${name} must be an object keyed by name.`);
+  }
+  return Object.entries(value);
+}
+
+export function assertPlatformRegistry(registry) {
   if (!(registry instanceof Map)) {
     throw new TypeError("Platform registry must be a Map created by createPlatformRegistry().");
   }
+  return registry;
+}
+
+export function registerPlatform(registry, key, definition) {
+  assertPlatformRegistry(registry);
   const normalizedKey = String(key).trim().toLowerCase();
   if (!normalizedKey) throw new TypeError("Platform key cannot be empty.");
 
   const next = new Map(registry);
+  // Re-insert at the end so an overriding registration also wins host ties,
+  // matching createPlatformRegistry().
+  next.delete(normalizedKey);
   next.set(normalizedKey, normalizePlatformDefinition(normalizedKey, definition));
   return next;
 }
@@ -119,7 +173,7 @@ export function inferPlatform(url, registry = createPlatformRegistry()) {
   }
 
   const protocol = parsed.protocol.toLowerCase();
-  const hostname = parsed.hostname.toLowerCase();
+  const hostname = stripTrailingDot(parsed.hostname.toLowerCase());
 
   // Pick the most specific match rather than the first one in iteration order.
   // An exact host beats a suffix match, and a longer host beats a shorter one,
diff --git a/src/render.js b/src/render.js
index 3fb874e..fa8489d 100644
--- a/src/render.js
+++ b/src/render.js
@@ -1,14 +1,19 @@
-import { createIconRegistry } from "./icons.js";
-import { createPlatformRegistry } from "./registry.js";
+import { assertIconRegistry, createIconRegistry } from "./icons.js";
+import { assertPlatformRegistry, createPlatformRegistry } from "./registry.js";
 import { renderableItems } from "./model.js";
 
+const HTML_ESCAPES = {
+  "&": "&amp;",
+  "<": "&lt;",
+  ">": "&gt;",
+  '"': "&quot;",
+  "'": "&#39;"
+};
+
+// A single regex pass instead of String#replaceAll keeps the renderer usable
+// from older bundler targets that future adapters may ship to the browser.
 function escapeHtml(value) {
-  return String(value)
-    .replaceAll("&", "&amp;")
-    .replaceAll("<", "&lt;")
-    .replaceAll(">", "&gt;")
-    .replaceAll('"', "&quot;")
-    .replaceAll("'", "&#39;");
+  return String(value).replace(/[&<>"']/g, (character) => HTML_ESCAPES[character]);
 }
 
 function attribute(name, value) {
@@ -32,15 +37,19 @@ function normalizeTracking(tracking) {
     throw new TypeError("tracking must be an object.");
   }
 
+  const fields = {};
   for (const field of ["sourceParam", "defaultSource", "unknownSource", "eventName"]) {
     const value = tracking[field];
-    if (value !== undefined && (typeof value !== "string" || !value.trim())) {
+    if (value != null && (typeof value !== "string" || !value.trim())) {
       throw new TypeError(`tracking.${field} must be a non-empty string.`);
     }
+    // Trim so a stray space in a config file cannot create a second, invisible
+    // analytics bucket such as "direct " next to "direct".
+    fields[field] = value?.trim();
   }
 
   let allowedSources = [];
-  if (tracking.allowedSources !== undefined) {
+  if (tracking.allowedSources != null) {
     if (!Array.isArray(tracking.allowedSources)) {
       throw new TypeError("tracking.allowedSources must be an array of strings.");
     }
@@ -48,22 +57,27 @@ function normalizeTracking(tracking) {
       if (typeof source !== "string" || !source.trim()) {
         throw new TypeError(`tracking.allowedSources[${index}] must be a non-empty string.`);
       }
-      return source;
+      return source.trim();
     });
   }
 
   return {
-    sourceParam: tracking.sourceParam ?? "from",
-    allowedSources,
-    defaultSource: tracking.defaultSource ?? "direct",
-    unknownSource: tracking.unknownSource ?? "other",
-    eventName: tracking.eventName ?? "promotion_click"
+    sourceParam: fields.sourceParam ?? "from",
+    allowedSources: [...new Set(allowedSources)],
+    defaultSource: fields.defaultSource ?? "direct",
+    unknownSource: fields.unknownSource ?? "other",
+    eventName: fields.eventName ?? "promotion_click"
   };
 }
 
-export function renderPromotionLinks(items, options = {}) {
-  const platformRegistry = options.registry ?? createPlatformRegistry(options.platforms);
-  const iconRegistry = options.iconRegistry ?? createIconRegistry(options.icons);
+export function renderPromotionLinks(items, options) {
+  options ??= {};
+  const platformRegistry = options.registry
+    ? assertPlatformRegistry(options.registry)
+    : createPlatformRegistry(options.platforms);
+  const iconRegistry = options.iconRegistry
+    ? assertIconRegistry(options.iconRegistry)
+    : createIconRegistry(options.icons);
   const visibleItems = renderableItems(items, {
     registry: platformRegistry,
     openInNewTab: options.openInNewTab
@@ -71,7 +85,9 @@ export function renderPromotionLinks(items, options = {}) {
   const tracking = normalizeTracking(options.tracking);
   const layout = options.layout ?? "wrap";
   const theme = options.theme ?? "inherit";
-  const ariaLabel = options.ariaLabel ?? "Project links";
+  // An empty aria-label leaves the <nav> landmark unnamed, which is worse than
+  // the generic default, so blank values fall back to it.
+  const ariaLabel = String(options.ariaLabel ?? "").trim() || "Project links";
 
   if (!["wrap", "stack", "inline"].includes(layout)) {
     throw new TypeError("layout must be wrap, stack, or inline.");
@@ -80,8 +96,12 @@ export function renderPromotionLinks(items, options = {}) {
     throw new TypeError("theme must be inherit, light, or dark.");
   }
 
+  // Every item disabled (e.g. a platform temporarily taken offline) must not
+  // leave an empty, labelled navigation landmark in the page.
+  if (visibleItems.length === 0) return "";
+
   const rootAttributes = [
-    attribute("class", `one-widget${options.className ? ` ${options.className}` : ""}`),
+    attribute("class", ["one-widget", options.className ? String(options.className).trim() : ""].filter(Boolean).join(" ")),
     attribute("aria-label", ariaLabel),
     attribute("data-one-widget", true),
     attribute("data-layout", layout),
diff --git a/src/styles.css b/src/styles.css
index 320bea1..8d22581 100644
--- a/src/styles.css
+++ b/src/styles.css
@@ -50,13 +50,25 @@
   flex-wrap: nowrap;
   overflow-x: auto;
   scrollbar-width: thin;
+  /* overflow-x: auto also clips vertically, cutting off the 2px + 3px focus
+     ring; pad it back in and cancel the padding with a negative margin so the
+     layout is unchanged. Block axis only: an inline-axis negative margin
+     would add horizontal page scroll on a full-bleed narrow viewport. */
+  margin-block: -5px;
+  padding-block: 5px;
 }
 
 .one-widget__item {
+  min-width: 0;
+  max-width: 100%;
   margin: 0;
   padding: 0;
 }
 
+.one-widget[data-layout="inline"] .one-widget__item {
+  flex: 0 0 auto;
+}
+
 .one-widget[data-layout="stack"] .one-widget__item {
   width: 100%;
 }
@@ -76,7 +88,12 @@
   font-family: var(--one-font-ui);
   font-size: 0.875rem;
   line-height: 1.25;
+  text-align: center;
   text-decoration: none;
+  /* Long unbroken labels (URLs, CJK without spaces) must wrap instead of
+     pushing the page wider than a 390px viewport. */
+  max-width: 100%;
+  overflow-wrap: anywhere;
   transition: border-color 120ms ease, background-color 120ms ease, color 120ms ease;
 }
 
@@ -89,6 +106,17 @@
   color: var(--one-accent);
 }
 
+.one-widget__link:focus {
+  outline: 2px solid var(--one-accent);
+  outline-offset: 3px;
+}
+
+/* Browsers with :focus-visible keep the ring for keyboard users only; older
+   ones fall back to the :focus rule above so focus is never invisible. */
+.one-widget__link:focus:not(:focus-visible) {
+  outline: none;
+}
+
 .one-widget__link:focus-visible {
   outline: 2px solid var(--one-accent);
   outline-offset: 3px;
@@ -114,6 +142,7 @@
 
 .one-widget__link--icon {
   width: 44px;
+  min-width: 44px;
   padding: 0;
 }
 
@@ -132,6 +161,7 @@
   margin: -1px;
   overflow: hidden;
   clip: rect(0, 0, 0, 0);
+  clip-path: inset(50%);
   white-space: nowrap;
   border: 0;
 }
@@ -146,6 +176,22 @@
   }
 }
 
+/* Windows High Contrast / forced colours drop backgrounds, so the primary
+   button would lose its only affordance; keep a system-coloured border and
+   let the icon follow the link text colour. */
+@media (forced-colors: active) {
+  .one-widget__link,
+  .one-widget__link--primary,
+  .one-widget__link--quiet {
+    border-color: LinkText;
+    color: LinkText;
+  }
+
+  .one-widget__link:focus-visible {
+    outline-color: Highlight;
+  }
+}
+
 @media (prefers-reduced-motion: reduce) {
   .one-widget__link {
     transition: none;
diff --git a/src/tracking.d.ts b/src/tracking.d.ts
index 1967c26..bcd5790 100644
--- a/src/tracking.d.ts
+++ b/src/tracking.d.ts
@@ -1,12 +1,7 @@
-import type { TrackingOptions } from "./index.js";
+import type { TrackingEnvironment, TrackingOptions } from "./index.js";
 
-export interface TrackingEnvironment {
-  location?: Location;
-  globalObject?: Window & { dataLayer?: Array<Record<string, unknown>> };
-  Element?: typeof Element;
-  HTMLAnchorElement?: typeof HTMLAnchorElement;
-}
+export type { TrackingEnvironment };
 
-export function resolveTrackingSource(search: string, config?: TrackingOptions): string;
-export function enhancePromotionWidget(root: Element, environment?: TrackingEnvironment): void;
-export function enhancePromotionWidgets(scope?: ParentNode): void;
+export function resolveTrackingSource(search: string | null | undefined, config?: TrackingOptions | null): string;
+export function enhancePromotionWidget(root: Element, environment?: TrackingEnvironment | null): void;
+export function enhancePromotionWidgets(scope?: ParentNode | null): void;
diff --git a/src/tracking.js b/src/tracking.js
index dde143e..4f60133 100644
--- a/src/tracking.js
+++ b/src/tracking.js
@@ -1,5 +1,19 @@
 const enhancedRoots = new WeakSet();
 
+// Element nodes from another realm (an iframe, a test DOM) fail instanceof
+// against this realm's constructors, so fall back to the node type.
+function isElement(value, ElementConstructor) {
+  if (!value || typeof value !== "object") return false;
+  if (ElementConstructor && value instanceof ElementConstructor) return true;
+  return value.nodeType === 1 && typeof value.querySelectorAll === "function";
+}
+
+function isAnchor(value, AnchorConstructor) {
+  if (!value || typeof value !== "object") return false;
+  if (AnchorConstructor && value instanceof AnchorConstructor) return true;
+  return value.nodeType === 1 && String(value.localName ?? value.tagName ?? "").toLowerCase() === "a";
+}
+
 function parseTrackingConfig(root) {
   let allowedSources = [];
   try {
@@ -11,67 +25,113 @@ function parseTrackingConfig(root) {
 
   return {
     sourceParam: root.dataset.sourceParam || "from",
-    allowedSources,
+    allowedSources: allowedSources.filter((source) => typeof source === "string"),
     defaultSource: root.dataset.sourceDefault || "direct",
     unknownSource: root.dataset.sourceUnknown || "other",
     eventName: root.dataset.eventName || "promotion_click"
   };
 }
 
-export function resolveTrackingSource(search, config = {}) {
+export function resolveTrackingSource(search, config) {
+  config ??= {};
   const sourceParam = config.sourceParam ?? "from";
-  const allowedSources = config.allowedSources ?? [];
+  const allowedSources = Array.isArray(config.allowedSources) ? config.allowedSources : [];
   const defaultSource = config.defaultSource ?? "direct";
   const unknownSource = config.unknownSource ?? "other";
   let raw;
 
   try {
-    raw = new URLSearchParams(search).get(sourceParam);
+    raw = new URLSearchParams(search ?? "").get(sourceParam);
   } catch {
     return defaultSource;
   }
 
+  raw = raw?.trim();
   if (!raw) return defaultSource;
-  if (raw === defaultSource || allowedSources.includes(raw)) return raw;
+
+  // Links shared by hand pick up stray case ("?from=Blog") and trailing
+  // whitespace; match case-insensitively but always report the configured
+  // spelling so the analytics buckets stay low-cardinality.
+  const wanted = raw.toLowerCase();
+  for (const candidate of [defaultSource, ...allowedSources]) {
+    if (typeof candidate === "string" && candidate.trim().toLowerCase() === wanted) {
+      return candidate.trim();
+    }
+  }
   return unknownSource;
 }
 
-export function enhancePromotionWidget(root, environment = {}) {
+function report(root, link, source, config, globalObject, CustomEventConstructor) {
+  const detail = {
+    item_id: link.dataset.oneItem || "unknown",
+    kind: link.dataset.kind || "custom",
+    platform: link.dataset.platform || "custom",
+    source_project: source
+  };
+
+  // Each sink is isolated: a throwing listener or a foreign dataLayer must not
+  // stop the other sink, and neither may ever get in the way of navigation.
+  try {
+    if (typeof CustomEventConstructor === "function") {
+      root.dispatchEvent(new CustomEventConstructor("one-widget:click", { detail, bubbles: true }));
+    }
+  } catch {
+    // Attribution is best-effort.
+  }
+
+  try {
+    if (!globalObject) return;
+    globalObject.dataLayer = globalObject.dataLayer || [];
+    if (typeof globalObject.dataLayer.push !== "function") return;
+    // A per-item data-event-name wins over the group default so a repository
+    // link in a support widget is not counted as a support conversion.
+    globalObject.dataLayer.push({ event: link.dataset.eventName || config.eventName, ...detail });
+  } catch {
+    // Attribution is best-effort.
+  }
+}
+
+export function enhancePromotionWidget(root, environment) {
+  environment ??= {};
   const ElementConstructor = environment.Element ?? globalThis.Element;
   const AnchorConstructor = environment.HTMLAnchorElement ?? globalThis.HTMLAnchorElement;
-  if (!ElementConstructor || !(root instanceof ElementConstructor) || enhancedRoots.has(root)) return;
+  if (!isElement(root, ElementConstructor) || !root.dataset || enhancedRoots.has(root)) return;
   enhancedRoots.add(root);
 
   const config = parseTrackingConfig(root);
   if (!root.dataset.eventName) return;
 
-  const locationObject = environment.location ?? window.location;
-  const source = resolveTrackingSource(locationObject.search, config);
+  const globalObject = environment.globalObject ?? globalThis.window;
+  const locationObject = environment.location ?? globalThis.location;
+  const CustomEventConstructor = environment.CustomEvent ?? globalThis.CustomEvent;
+  const source = resolveTrackingSource(locationObject?.search ?? "", config);
 
   for (const link of root.querySelectorAll("[data-one-item]")) {
-    if (!AnchorConstructor || !(link instanceof AnchorConstructor)) continue;
+    if (!isAnchor(link, AnchorConstructor) || !link.dataset) continue;
     link.dataset.sourceProject = source;
-    link.addEventListener("click", () => {
-      const detail = {
-        item_id: link.dataset.oneItem || "unknown",
-        kind: link.dataset.kind || "custom",
-        platform: link.dataset.platform || "custom",
-        source_project: source
-      };
-
-      root.dispatchEvent(new CustomEvent("one-widget:click", { detail, bubbles: true }));
-
-      const globalObject = environment.globalObject ?? window;
-      globalObject.dataLayer = globalObject.dataLayer || [];
-      // A per-item data-event-name wins over the group default so a repository
-      // link in a support widget is not counted as a support conversion.
-      globalObject.dataLayer.push({ event: link.dataset.eventName || config.eventName, ...detail });
+
+    const track = () => report(root, link, source, config, globalObject, CustomEventConstructor);
+    link.addEventListener("click", (event) => {
+      // Only the primary button; a middle click is reported via auxclick below.
+      if (!event?.button) track();
+    });
+    // Middle-click ("open in new tab") never fires click in modern browsers,
+    // so without this those visits would go unattributed.
+    link.addEventListener("auxclick", (event) => {
+      if (event?.button === 1) track();
     });
   }
 }
 
-export function enhancePromotionWidgets(scope = document) {
+export function enhancePromotionWidgets(scope) {
+  scope ??= globalThis.document;
+  if (!scope || typeof scope.querySelectorAll !== "function") return;
   for (const root of scope.querySelectorAll("[data-one-widget]")) {
-    enhancePromotionWidget(root);
+    try {
+      enhancePromotionWidget(root);
+    } catch {
+      // One malformed widget must not prevent the rest of the page from being
+      // enhanced; its static links keep working either way.
+    }
   }
 }
diff --git a/test/model.test.js b/test/model.test.js
index 2ff95be..0204fef 100644
--- a/test/model.test.js
+++ b/test/model.test.js
@@ -108,3 +108,79 @@ test("matches custom icon keys regardless of case", () => {
   ]);
   assert.equal(item.icon, "forge", "item.icon should resolve to the lowercased key");
 });
+
+test("treats null optional fields from JSON / CMS exports as unset", () => {
+  const [item] = normalizePromotionItems([
+    {
+      id: "cms",
+      url: "https://afdian.com/a/eigentime",
+      label: "Support",
+      kind: null,
+      platform: null,
+      shortLabel: null,
+      icon: null,
+      enabled: null,
+      order: null,
+      openInNewTab: null,
+      appearance: null,
+      emphasis: null,
+      eventName: null
+    }
+  ], null);
+
+  assert.equal(item.platform, "afdian");
+  assert.equal(item.kind, "support");
+  assert.equal(item.enabled, true);
+  assert.equal(item.openInNewTab, true);
+  assert.equal(item.eventName, undefined);
+});
+
+test("rejects a mailto URL without a recipient", () => {
+  assert.throws(() => normalizeUrl("mailto:"), /email address/);
+  assert.throws(() => normalizeUrl("mailto:?subject=hi"), /email address/);
+  assert.equal(normalizeUrl("mailto:hi@example.com"), "mailto:hi@example.com");
+});
+
+test("normalises declared platform hosts the way URL#hostname does", () => {
+  const registry = createPlatformRegistry({
+    pasted: { hosts: ["https://Code.Example.org/"] },
+    scoped: { hosts: ["gitlab.com/someone"] },
+    dotted: { hosts: ["docs.example.net."] },
+    idn: { hosts: ["例子.com"] },
+    bare: { protocols: ["MAILTO"] }
+  });
+
+  assert.equal(inferPlatform("https://code.example.org/team/repo", registry), "pasted");
+  assert.equal(inferPlatform("https://docs.example.net/", registry), "dotted");
+  assert.equal(inferPlatform("https://docs.example.net./", registry), "dotted", "FQDN with trailing dot");
+  assert.equal(inferPlatform("https://例子.com/a", registry), "idn");
+  assert.equal(inferPlatform("https://github.com./user", registry), "github");
+  assert.equal(inferPlatform("https://gitlab.com/other", registry), "gitlab", "a host with a path must not widen to the whole host");
+  assert.equal(inferPlatform("mailto:hi@example.com", registry), "bare");
+});
+
+test("a custom platform key overrides the built-in regardless of case", () => {
+  const registry = createPlatformRegistry({
+    GitHub: { defaultKind: "social", hosts: ["github.com"] }
+  });
+
+  assert.equal([...registry.keys()].filter((key) => key === "github").length, 1);
+  assert.equal(registry.get("github").defaultKind, "social");
+  assert.equal(inferPlatform("https://github.com/user", registry), "github");
+});
+
+test("accepts platform and icon definitions as a Map", () => {
+  const platforms = new Map([["forgejo", { defaultKind: "repository", icon: "forge", hosts: ["code.example.org"] }]]);
+  const icons = new Map([["forge", { viewBox: "0 0 24 24", paths: [{ d: "M4 4h16v16H4z" }] }]]);
+
+  assert.equal(inferPlatform("https://code.example.org/x", createPlatformRegistry(platforms)), "forgejo");
+  assert.ok(createIconRegistry(icons).has("forge"));
+});
+
+test("rejects registries and definition maps of the wrong shape with a clear error", () => {
+  const items = [{ id: "a", url: "https://example.com", label: "A" }];
+
+  assert.throws(() => normalizePromotionItems(items, { registry: {} }), /createPlatformRegistry/);
+  assert.throws(() => createPlatformRegistry([{ hosts: ["example.com"] }]), /platforms must be an object/);
+  assert.throws(() => createIconRegistry([{ viewBox: "0 0 24 24", paths: [{ d: "M0 0" }] }]), /icons must be an object/);
+});
diff --git a/test/render.test.js b/test/render.test.js
index 9629c87..8027eb6 100644
--- a/test/render.test.js
+++ b/test/render.test.js
@@ -135,3 +135,40 @@ test("rejects malformed tracking configuration instead of silently degrading", (
     /eventName must be a non-empty string/
   );
 });
+
+test("renders nothing when no item is enabled instead of an empty landmark", () => {
+  const html = renderPromotionLinks([
+    { id: "a", url: "https://afdian.com/a/x", label: "Support", enabled: false }
+  ], { ariaLabel: "Support links", tracking: { eventName: "support_click" } });
+
+  assert.equal(html, "");
+  assert.equal(renderPromotionLinks([]), "");
+  // Configuration errors still surface even when nothing would be shown.
+  assert.throws(() => renderPromotionLinks([], { layout: "grid" }), /layout must be/);
+});
+
+test("falls back to the default landmark name for a blank ariaLabel", () => {
+  const items = [{ id: "a", url: "https://example.com", label: "A" }];
+
+  assert.match(renderPromotionLinks(items, { ariaLabel: "   " }), /<nav[^>]*aria-label="Project links"/);
+  assert.match(renderPromotionLinks(items, null), /<nav[^>]*aria-label="Project links"/);
+  assert.match(renderPromotionLinks(items, { className: "  extra  " }), /<nav class="one-widget extra"/);
+});
+
+test("trims tracking values and de-duplicates the source allowlist", () => {
+  const html = renderPromotionLinks([{ id: "a", url: "https://afdian.com/a/x", label: "Support" }], {
+    tracking: {
+      sourceParam: " from ",
+      allowedSources: ["blog", " blog ", "github"],
+      defaultSource: "direct ",
+      unknownSource: null,
+      eventName: " support_click"
+    }
+  });
+
+  assert.match(html, /data-source-param="from"/);
+  assert.match(html, /data-source-allowlist="\[&quot;blog&quot;,&quot;github&quot;\]"/);
+  assert.match(html, /data-source-default="direct"/);
+  assert.match(html, /data-source-unknown="other"/);
+  assert.match(html, /<nav[^>]*data-event-name="support_click"/);
+});
diff --git a/test/tracking.test.js b/test/tracking.test.js
index 90cc650..4075da5 100644
--- a/test/tracking.test.js
+++ b/test/tracking.test.js
@@ -1,6 +1,6 @@
 import test from "node:test";
 import assert from "node:assert/strict";
-import { enhancePromotionWidget } from "../src/index.js";
+import { enhancePromotionWidget, enhancePromotionWidgets, resolveTrackingSource } from "../src/index.js";
 import { MockAnchor, MockElement, makeEnvironment } from "./helpers/mock-dom.js";
 
 function buildWidget(datasetOverrides = {}, anchors) {
@@ -107,3 +107,69 @@ test("is a no-op when no tracking config is present", () => {
   assert.doesNotThrow(() => enhancePromotionWidget(root, makeEnvironment("?from=blog")));
   assert.equal(anchor.dataset.sourceProject, undefined);
 });
+
+test("matches sources case-insensitively and reports the configured spelling", () => {
+  const config = { allowedSources: ["one-stop-job", "GitHub"], defaultSource: "direct", unknownSource: "other" };
+
+  assert.equal(resolveTrackingSource("?from=One-Stop-Job", config), "one-stop-job");
+  assert.equal(resolveTrackingSource("?from=github%20", config), "GitHub");
+  assert.equal(resolveTrackingSource("?from=%20%20", config), "direct");
+  assert.equal(resolveTrackingSource("?from=DIRECT", config), "direct");
+  assert.equal(resolveTrackingSource(undefined, null), "direct");
+});
+
+test("reports middle-click opens but not right clicks", () => {
+  const { root, anchor } = buildWidget();
+  const environment = makeEnvironment("?from=blog");
+  enhancePromotionWidget(root, environment);
+
+  anchor.dispatchEvent({ type: "auxclick", button: 1 });
+  anchor.dispatchEvent({ type: "auxclick", button: 2 });
+  anchor.dispatchEvent({ type: "click", button: 1 });
+
+  assert.equal(environment.globalObject.dataLayer.length, 1, "only the middle click is reported, once");
+});
+
+test("a foreign dataLayer or a throwing listener never breaks the click", () => {
+  const { root, anchor } = buildWidget();
+  const environment = makeEnvironment("?from=blog");
+  environment.globalObject.dataLayer = { not: "an array" };
+  root.addEventListener("one-widget:click", () => {
+    throw new Error("listener failure");
+  });
+  enhancePromotionWidget(root, environment);
+
+  assert.doesNotThrow(() => anchor.dispatchEvent({ type: "click" }));
+  assert.equal(root.dispatched.filter((event) => event.type === "one-widget:click").length, 1);
+
+  const second = buildWidget();
+  const secondEnvironment = makeEnvironment("?from=blog");
+  second.root.addEventListener("one-widget:click", () => {
+    throw new Error("listener failure");
+  });
+  enhancePromotionWidget(second.root, secondEnvironment);
+  second.anchor.dispatchEvent({ type: "click" });
+  assert.equal(secondEnvironment.globalObject.dataLayer.length, 1, "dataLayer still receives the event");
+});
+
+test("does not touch browser globals when run outside a browser", () => {
+  assert.doesNotThrow(() => enhancePromotionWidgets());
+  assert.doesNotThrow(() => enhancePromotionWidgets(null));
+
+  const { root, anchor } = buildWidget();
+  assert.doesNotThrow(() => enhancePromotionWidget(root, { Element: MockElement, HTMLAnchorElement: MockAnchor }));
+  assert.equal(anchor.dataset.sourceProject, "direct", "no location means no ?from= to read");
+  assert.doesNotThrow(() => anchor.dispatchEvent({ type: "click" }));
+});
+
+test("accepts element nodes from another realm by node type", () => {
+  const anchor = { nodeType: 1, localName: "a", dataset: { oneItem: "afdian", kind: "support", platform: "afdian" }, addEventListener() {} };
+  const root = {
+    nodeType: 1,
+    dataset: { eventName: "support_click", sourceAllowlist: "[\"blog\", 42]" },
+    querySelectorAll: () => [anchor]
+  };
+
+  enhancePromotionWidget(root, { location: { search: "?from=blog" }, globalObject: {} });
+  assert.equal(anchor.dataset.sourceProject, "blog");
+});

From a851e498297994d5e697b4d3cc525ffafa14dcf4 Mon Sep 17 00:00:00 2001
From: Claude <noreply@anthropic.com>
Date: Wed, 30 Sep 2026 11:39:10 +0000
Subject: [PATCH 2/2] docs: date the 0.1.2 changelog entry for release

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01SSHDa6j758YbQZUK7QHez4
---
 CHANGELOG.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/CHANGELOG.md b/CHANGELOG.md
index b31aec8..5bdbc2c 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -2,7 +2,7 @@
 
 版本策略见 [README 的「升级与版本策略」](README.md#升级与版本策略)。每条变更都标注**调用方是否需要改配置**，升级时只读这一列即可。
 
-## 0.1.2 - 未发布
+## 0.1.2 - 2026-09-30
 
 需要改配置：否。兼容性与健壮性加固，现有 `items` / `tracking` 配置原样可用。只有此前就会静默出错的输入会改为构建期报错（见最后三条）。