@epxing/icons 0.0.0-stage → 5.3.0-beta.2

package/API.md

@@ -0,0 +1,111 @@
+# @epxing/icons API
+
+Vite 构建插件和浏览器图标补齐工具。根入口用于 Node 构建，/runtime 用于浏览器。
+
+本页对应包版本 `5.3.0-beta.2`。导出名、子路径和签名从当前源码、package.json 与类型声明生成。
+
+## 安装与使用
+
+
+```sh
+pnpm add @epxing/icons@5.3.0-beta.2
+```
+
+
+```js
+// vite.config.mjs（Node）
+import epxIcons from '@epxing/icons'
+export default { plugins: [epxIcons()] }
+
+// 产品入口（浏览器）
+// import { configureIcons, collectIconNames, ensureIcons, createEndpointLoader } from '@epxing/icons/runtime'
+// configureIcons({ loader: createEndpointLoader({ url: '/api/icons' }), timeout: 3000 })
+// await ensureIcons(collectIconNames(pageConfig))
+```
+
+## 接入约定
+
+浏览器从 @epxing/icons/runtime 导入，避免把 Node 构建依赖带进产品。图标宿主样式由 @epxing/theme/src/icons/base.scss 提供；loader 补入图案前需先加载底座样式。ready/missing 表示本次检查结果；静态分片的编号规则与 shardOf 保持一致。
+
+## 根入口完整导出
+
+| 导出名 | 形态 | 用途 | 参数 / 配置 / 事件 |
+| --- | --- | --- | --- |
+| `emitShards` | 函数 | 构建图标静态分片；在 Node 构建阶段调用，输出位置和分片数由选项决定。 | [详细参考](../../docs/revision/icons/api/vite-plugin.md) |
+| `default` | 默认导出 | epxIcons(options?)：Vite 图标构建插件工厂。 | [详细参考](../../docs/revision/icons/api/vite-plugin.md) |
+
+## 函数、类与工具对象
+
+签名中的 any 表示现有声明未进一步限定结构；源代码方法签名保留默认参数。异步结果与泛型以声明为准。
+
+### emitShards
+
+构建图标静态分片；在 Node 构建阶段调用，输出位置和分片数由选项决定。
+
+```ts
+emitShards(options?: IconOptions): unknown
+```
+
+[详细参考](../../docs/revision/icons/api/vite-plugin.md)，包括参数、返回值与运行约束。
+
+## 稳定子路径
+
+下表按实际 package.json 的公开入口列出。default 使用默认导入，其他名称使用具名导入；类型接口用 import type。
+
+| 导入路径 | 完整导出名 | 用途 / 详细说明 |
+| --- | --- | --- |
+| `@epxing/icons/runtime` | `configureIcons`、`collectIconNames`、`ensureIcons`、`ensureIcon`、`createEndpointLoader`、`createShardLoader`、`shardOf`、`__reset`、`IconRuntimeOptions`（类型）、`IconResult`（类型） | 浏览器图标运行时：配置 loader、收集名称、补齐图案、创建加载器和计算分片编号。 [详细参考](../../docs/revision/icons/api/runtime.md) |
+
+### 浏览器 runtime 函数
+
+| 函数 | 调用签名 | 用途 |
+| --- | --- | --- |
+| `configureIcons` | `configureIcons(options?: IconRuntimeOptions): void` | 配置浏览器图标 loader、builtin、match 和 timeout；timeout 以毫秒计，默认 0 不设上限。 |
+| `collectIconNames` | `collectIconNames(config: unknown, out?: Set<string>): string[]` | 递归收集配置中的图标名并去重，返回字符串数组；可传入 Set 累积结果。 |
+| `ensureIcons` | `ensureIcons(names: Iterable<string>): Promise<IconResult>` | 批量补齐图标并合并并发请求，返回 Promise&lt;{ ready, missing }&gt;。 |
+| `ensureIcon` | `ensureIcon(name: string): Promise<IconResult>` | 确保单个图标可用，返回 Promise&lt;{ ready, missing }&gt;。 |
+| `createEndpointLoader` | `createEndpointLoader(options?: Record<string, unknown>): (names: string[]) => Promise<unknown>` | 创建从图标 HTTP 接口批量取图案的 loader，传给 configureIcons。 |
+| `createShardLoader` | `createShardLoader(options?: Record<string, unknown>): (names: string[]) => Promise<unknown>` | 创建从静态分片加载图标的 loader，传给 configureIcons。 |
+| `shardOf` | `shardOf(name: string, shards?: number): number` | 按图标名计算静态分片编号；构建端与运行时须使用相同分片数。 |
+| `__reset` | `__reset(): void` | 仅供测试：清空图标运行时缓存、loader 和已注入样式；产品业务代码不调用。 |
+
+## 导出的 TypeScript 类型
+
+以下名称仅存在于类型系统，用 import type 导入，不作为运行时对象使用。
+
+### IconOptions
+
+```ts
+interface IconOptions {
+  [key: string]: unknown
+}
+```
+
+### IconRuntimeOptions
+
+```ts
+interface IconRuntimeOptions {
+  loader?: (names: string[]) => Promise<unknown>
+  timeout?: number
+  [key: string]: unknown
+}
+```
+
+### IconResult
+
+```ts
+interface IconResult { ready: string[]; missing: string[] }
+```
+
+## 源码兼容与其他入口
+
+/src 路径保留给已有产品和源码级扩展，可能包含平台内部实现；新产品优先采用上方根导出与稳定子路径。通配符表示按实际文件名匹配，不代表所有源码都属于根入口。
+
+| 公开路径模式 | 实际目标 |
+| --- | --- |
+| `@epxing/icons/src/*` | `./src/*` |
+| `@epxing/icons/package.json` | `./package.json` |
+
+## 文档维护
+
+本页由 build/gen-package-api-docs.mjs 生成。修改公开入口并更新构建产物和类型声明后，在框架根运行 `pnpm docs:api`；`pnpm docs:api:check` 检查清单、类型、包内文档与站点镜像是否同步，同时验证页面编译和文档链接。用途和示例维护在 build/package-api-notes.mjs，组件和源码方法的详细参考位于 docs/revision。

package/README.md

@@ -1,3 +1,3 @@
-# Temporary Holding Version
+# @epxing/icons
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+[完整公开 API、导入方式与示例](./API.md)

package/package.json

@@ -1,6 +1,46 @@
 {
   "name": "@epxing/icons",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "5.3.0-beta.2",
+  "description": "图标构建工具 + 运行时（源码分发：在消费方的构建里跑，无需预构建）。构建期按需生成 Remix 图标与项目彩色图标的 CSS 规则；运行时按需补齐数据库里配的、构建期看不见的图标。渲染底座在 @epxing/theme 的 icons/base.scss。",
+  "type": "module",
+  "main": "./src/vite-plugin.mjs",
+  "exports": {
+    ".": {
+      "types": "./types/index.d.ts",
+      "import": "./src/vite-plugin.mjs",
+      "default": "./src/vite-plugin.mjs"
+    },
+    "./runtime": {
+      "types": "./types/runtime.d.ts",
+      "import": "./src/runtime.mjs",
+      "default": "./src/runtime.mjs"
+    },
+    "./src/*": "./src/*",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src",
+    "types",
+    "API.md"
+  ],
+  "peerDependencies": {
+    "@iconify-json/ri": "^1.2.10",
+    "vite": "^6.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@iconify-json/ri": {
+      "optional": true
+    },
+    "vite": {
+      "optional": true
+    }
+  },
+  "types": "./types/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "echo '@epxing/icons 为纯 Node 源码包，无需构建'"
+  }
 }

package/src/runtime.mjs

@@ -0,0 +1,390 @@
+// epx-frame 图标运行时：按需补齐「构建期不知道、只有运行时才知道」的图标。
+//
+// 解决的是什么问题：配置驱动的平台里，图标名存在**数据库**（菜单 FONT_ICON、
+// 按钮 operate.iconCls、页面配置 configs.icon）。构建期没有库连接、配置又随时可改，
+// 这些名字在原理上扫不到。此前唯一的办法是手工登记（icon-include.override.cjs），
+// 想让后台图标选择器放开到 Remix 全量 3229 个就不现实了——全量内联进 CSS 是
+// 259KB gzip（实测），是当前 461 个的 3.8 倍。
+//
+// 按需之所以在这套底座上特别便宜：渲染机制是 `--epx-i` 这一个 CSS 变量，
+// 盒子 / mask / currentColor 的宿主规则早就在 CSS 里了。运行时补一个图标 =
+// 补一条自定义属性声明，**不需要新增任何渲染机制**，也不碰 DOM 元素本身。
+// 实测单个图标 319B raw，一页用 15 个 = 1.6KB gzip、一次请求。
+//
+// 用法：
+//     import { configureIcons, ensureIcons, collectIconNames, createEndpointLoader }
+//       from '@epxing/icons/runtime'
+//
+//     configureIcons({ loader: createEndpointLoader({ url: '/api/icons' }) })
+//
+//     // 配置驱动页面的最佳时机：配置到手、渲染之前 —— 图标就位后再渲染，不闪
+//     await ensureIcons(collectIconNames(pageConfig))
+//
+// ⚠️ 本文件跑在**浏览器**里，与同目录的 vite-plugin.mjs（跑在 Node 构建期）
+// 是两套东西，不要互相 import：那会把 node:fs 拖进浏览器产物。
+
+// 归运行时管的名字。默认只管 `ri-`：`el-icon-*` / `epx-icon-*` 那 461 个是兼容层，
+// 随 lib 一起发布、永远在 CSS 里，探测它们纯属浪费。
+const DEFAULT_MATCH = /^ri-[a-z0-9-]+$/
+
+// 从任意配置对象里捞图标名时用的形状。比 DEFAULT_MATCH 宽——配置里存的可能是
+// 平台名，也可能是 Remix 名，先都捞出来，交给 match 去筛。
+const NAME_SHAPE = /^(?:ri|el-icon|epx-icon)-[a-z0-9-]+$/
+
+const STYLE_ATTR = 'data-epx-icons'
+
+let loader = null
+let match = DEFAULT_MATCH
+// 0 = 不设上限。放在渲染关键路径上时必须设：取数挂住（分片 404、后端超时、网络黑洞）
+// 不该把整页渲染一起拖住。超时只是**不再等**，不取消请求——晚到的数据照样注入，
+// 图标随后自己出来，比"永远空白"好。
+let timeoutMs = 0
+// 已确认可用的名字。三个来源：调用方声明的 builtin、探测判定为「已在 CSS 里」的、
+// 本运行时注入过的。判定一次就记住，同一个名字不会探测第二次。
+const ready = new Set()
+// 名字 → 正在进行的 Promise。并发调用同一个图标只发一次请求。
+const inflight = new Map()
+let warnedHostMissing = false
+
+const hasDom = () => typeof document !== 'undefined' && !!document.head
+
+/**
+ * 配置运行时。不调用也能工作（只是没有 loader，缺图标时会给出明确警告而不是静默空白）。
+ *
+ * @param {object}   opts
+ * @param {function} opts.loader  async (names: string[]) => ({ [name]: svg | {body,width,height} })
+ *                                返回值两种形状都认：完整的 `<svg>...</svg>` 字符串，
+ *                                或 iconify 的 { body, width, height }。
+ * @param {string[]} opts.builtin 已知**一定在 CSS 里**的名字，跳过探测。可选，
+ *                                纯性能优化——不给也不会错，探测会得出同样结论。
+ * @param {RegExp}   opts.match   哪些名字归运行时管，默认 /^ri-[a-z0-9-]+$/
+ * @param {number}   opts.timeout 单次 ensureIcons 最多等多少毫秒，0（默认）不设上限。
+ *                                挂在渲染关键路径上时**必须设**，见 timeoutMs 处注释。
+ */
+export function configureIcons (opts = {}) {
+  if (opts.loader) loader = opts.loader
+  if (opts.match) match = opts.match
+  if (opts.builtin) for (const n of opts.builtin) ready.add(n)
+  if (opts.timeout !== undefined) {
+    if (!Number.isFinite(opts.timeout) || opts.timeout < 0) {
+      throw new Error(`[epx-icons] timeout 必须是非负数，收到 ${opts.timeout}`)
+    }
+    timeoutMs = opts.timeout
+  }
+}
+
+/**
+ * 从任意配置结构里捞出图标名。
+ *
+ * 递归走完整个对象/数组，把**长得像图标名的字符串**收集起来。之所以不按固定字段名
+ * （configs.icon / iconCls / FONT_ICON）去取：配置形状随组件而变，写死字段名必然漏。
+ * 形状正则收得很紧（整串匹配，不是子串），误报的代价也只是一次查无此名的请求。
+ *
+ * class 属性里常有多个词（`epx-icon ri-rocket-line`），所以按空白切开逐个判。
+ */
+export function collectIconNames (config, out = new Set()) {
+  if (!config) return [...out]
+  if (typeof config === 'string') {
+    for (const token of config.split(/\s+/)) {
+      if (NAME_SHAPE.test(token)) out.add(token)
+    }
+    return [...out]
+  }
+  if (Array.isArray(config)) {
+    for (const item of config) collectIconNames(item, out)
+    return [...out]
+  }
+  if (typeof config === 'object') {
+    for (const key of Object.keys(config)) collectIconNames(config[key], out)
+    return [...out]
+  }
+  return [...out]
+}
+
+/**
+ * 探测这批名字在当前 CSS 里是不是已经有图案了。
+ *
+ * 为什么用探测而不是构建期清单：清单会和产物**版本漂移**（消费方装的 epx-frame
+ * 与插件生成的 CSS 未必同一批），而探测直接问浏览器「这个 class 现在画得出东西吗」，
+ * 自证、零构建耦合，而且不在乎图案是平台 lib 给的、插件给的、还是上次注入的。
+ *
+ * 判据来自底座本身：宿主规则给了 `--epx-i: linear-gradient(#0000,#0000)` 作缺省
+ * （见 theme 的 icons/base.scss），所以
+ *   maskImage 以 url( 开头  ⇒ 有图案
+ *   是那条透明渐变          ⇒ 没图案，要补
+ *   content 是 none         ⇒ **宿主规则整个没上**，补图案也没用（见下）
+ *
+ * 一次性建好全部探针再读，只触发一次重排。
+ */
+function probeMissing (names) {
+  if (!hasDom()) return names.slice()
+  const box = document.createElement('div')
+  box.setAttribute('aria-hidden', 'true')
+  box.style.cssText = 'position:absolute;left:-9999px;top:0;visibility:hidden;pointer-events:none'
+  const probes = names.map(name => {
+    const el = document.createElement('i')
+    el.className = name
+    box.appendChild(el)
+    return { name, el }
+  })
+  document.body.appendChild(box)
+
+  const missing = []
+  let hostMissing = false
+  for (const { name, el } of probes) {
+    const cs = getComputedStyle(el, '::before')
+    // 宿主规则没上：::before 压根没被生成，content 计算值是 none 而不是 ""
+    if (cs.content === 'none') { hostMissing = true; missing.push(name); continue }
+    const mask = cs.maskImage || cs.webkitMaskImage || ''
+    if (mask.startsWith('url(')) ready.add(name)
+    else missing.push(name)
+  }
+  document.body.removeChild(box)
+
+  // 这一条值得吵：宿主规则缺失时，补多少图案都画不出来（有变量没有盒子），
+  // 而表现是**静默空白、零报错**——本项目里最难查的那类故障。
+  if (hostMissing && !warnedHostMissing) {
+    warnedHostMissing = true
+    warn('宿主规则没有生效：[class^="ri-"]::before 不存在。\n' +
+      '  补图案也画不出来（有 --epx-i 变量但没有盒子）。检查：\n' +
+      '  · 项目是否引了 epx-frame 的样式（461 个平台图标同理依赖它）\n' +
+      '  · epx-frame 版本是否过旧（早期 lib 里没有 ri- 宿主选择器）\n' +
+      '  · 或在 vite.config 里挂上 @epxing/icons 插件并 import "virtual:epx-icons.css"')
+  }
+  return missing
+}
+
+function warn (msg) {
+  // eslint-disable-next-line no-console
+  console.warn('[epx-icons] ' + msg)
+}
+
+// 与构建期 vite-plugin.mjs 的 encodeSvgDataUri 同一套编码，产出的 data URI 逐字节可比。
+// 两处**必须一致**：同一个图标从两条路进来时长相要完全相同，否则排查时会以为是两个东西。
+function encodeSvgDataUri (svg) {
+  return svg.replace(/"/g, "'").replace(/%/g, '%25').replace(/#/g, '%23')
+    .replace(/</g, '%3C').replace(/>/g, '%3E').replace(/\s+/g, ' ')
+}
+
+// loader 返回值两种形状都认：完整 svg 字符串，或 iconify 的 { body, width, height }
+function toSvg (value) {
+  if (!value) return null
+  if (typeof value === 'string') {
+    const svg = value.trim()
+    return svg.startsWith('<svg') ? svg : null
+  }
+  if (typeof value.body !== 'string') return null
+  const w = value.width || 24
+  const h = value.height || 24
+  return `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}">${value.body}</svg>`
+}
+
+function inject (rules) {
+  if (!rules.length || !hasDom()) return
+  let style = document.head.querySelector(`style[${STYLE_ATTR}]`)
+  if (!style) {
+    style = document.createElement('style')
+    style.setAttribute(STYLE_ATTR, '')
+    document.head.appendChild(style)
+  }
+  // 追加而不是重建：已注入的规则保持原位，避免每次补图标都让浏览器重算整块样式表
+  style.appendChild(document.createTextNode(rules.join('\n')))
+}
+
+/**
+ * 确保这批图标在 CSS 里有图案，缺的取回来补上。
+ *
+ * 幂等、可并发：同一个名字重复调用不会重复请求（in-flight 去重 + ready 记账）。
+ * 任何失败都**不抛**——图标缺失不该让页面崩掉——但都会有明确的 console 警告，
+ * 绝不静默。
+ *
+ * @param {string[]} names
+ * @returns {Promise<{ready: string[], missing: string[]}>}
+ */
+export async function ensureIcons (names) {
+  const wanted = [...new Set((names || []).filter(Boolean))].filter(n => match.test(n))
+  if (!wanted.length) return { ready: [], missing: [] }
+
+  // 已判定可用的直接跳过；正在取的挂到同一个 Promise 上
+  const pending = []
+  const todo = []
+  for (const name of wanted) {
+    if (ready.has(name)) continue
+    const running = inflight.get(name)
+    if (running) pending.push(running)
+    else todo.push(name)
+  }
+
+  if (todo.length) {
+    const missing = probeMissing(todo)
+    if (missing.length) {
+      if (!loader) {
+        warn(`${missing.length} 个图标不在 CSS 里，又没有配 loader —— 会是空白：\n` +
+          `  ${missing.join(', ')}\n` +
+          '  用 configureIcons({ loader }) 配一个取数方式，或把它们登记进构建。')
+        missing.forEach(n => inflight.delete(n))
+      } else {
+        const job = fetchAndInject(missing)
+        missing.forEach(n => inflight.set(n, job))
+        pending.push(job)
+      }
+    }
+  }
+
+  if (pending.length) {
+    const all = Promise.all(pending)
+    if (timeoutMs > 0) {
+      let timer
+      const bell = new Promise(resolve => { timer = setTimeout(() => resolve('timeout'), timeoutMs) })
+      const who = await Promise.race([all.then(() => 'done'), bell])
+      clearTimeout(timer)
+      if (who === 'timeout') {
+        warn(`取图标超过 ${timeoutMs}ms 还没回来，先不等了（请求没取消，晚到的数据仍会注入）。`)
+      }
+    } else {
+      await all
+    }
+  }
+  const stillMissing = wanted.filter(n => !ready.has(n))
+  return { ready: wanted.filter(n => ready.has(n)), missing: stillMissing }
+}
+
+/** ensureIcons 的单个版本，给「运行时才出现一个图标」的场景（如 <epx-icon> 的 name 变化）。 */
+export function ensureIcon (name) {
+  return ensureIcons([name])
+}
+
+async function fetchAndInject (names) {
+  try {
+    const data = await loader(names)
+    const rules = []
+    const bad = []
+    for (const name of names) {
+      // loader 可以按裸名（rocket-line）或全名（ri-rocket-line）返回，两种都认
+      const raw = data && (data[name] !== undefined ? data[name] : data[name.replace(/^ri-/, '')])
+      const svg = toSvg(raw)
+      if (!svg) { bad.push(name); continue }
+      rules.push(`.${name}::before{--epx-i:url("data:image/svg+xml,${encodeSvgDataUri(svg)}")}`)
+      ready.add(name)
+    }
+    inject(rules)
+    if (bad.length) {
+      warn(`loader 没给回这 ${bad.length} 个图标的数据，它们会是空白：\n  ${bad.join(', ')}\n` +
+        '  多半是名字拼错了（去 https://remixicon.com 核对），或后端图标库里没有这一项。')
+    }
+  } catch (err) {
+    warn(`取图标失败，这批会是空白：${names.join(', ')}\n  ${err && err.message}`)
+  } finally {
+    names.forEach(n => inflight.delete(n))
+  }
+}
+
+/**
+ * 批量接口 loader：`GET {url}?names=ri-a,ri-b` → `{ "ri-a": "<svg…>", … }`
+ *
+ * 推荐形态。图标内容永不变，后端配 `Cache-Control: immutable` 之后二次访问零请求。
+ * names 很多时自动分批，免得 URL 超长（保守取 1500 字符）。
+ */
+export function createEndpointLoader (opts = {}) {
+  const { url, batchSize = 60, fetchOptions } = opts
+  if (!url) throw new Error('[epx-icons] createEndpointLoader 需要 url')
+  return async (names) => {
+    const out = {}
+    for (let i = 0; i < names.length; i += batchSize) {
+      const part = names.slice(i, i + batchSize)
+      const res = await fetch(`${url}?names=${encodeURIComponent(part.join(','))}`, fetchOptions)
+      if (!res.ok) throw new Error(`${res.status} ${res.statusText}`)
+      Object.assign(out, await res.json())
+    }
+    return out
+  }
+}
+
+/**
+ * 静态分片 loader：不想动后端时用。分片由构建期插件的 `shards` 选项产出。
+ *
+ * 目录形如：
+ *     {base}/manifest.json   { prefix, shards, hash, total }
+ *     {base}/0.json … {base}/{shards-1}.json   { prefix, width, height, icons: {裸名: {body,…}} }
+ *
+ * ⚠️ 片数**从 manifest 读，不从选项读**。写成选项的话，构建期把 count 从 64 改成 32
+ * 之后运行时仍按 64 算，会稳定地去错误的片里找 —— 表现是图标空白加一条「loader
+ * 没给回数据」的警告，极难往哈希函数上想。让 manifest 做唯一事实来源，这类不一致
+ * 在结构上就不存在了。
+ *
+ * manifest 的 hash 同时用来做缓存失效：分片 URL 带上 `?v={hash}`，
+ * 图标集没变时 URL 不变（可长缓存），变了就自动换 URL。
+ */
+export function createShardLoader (opts = {}) {
+  const { base, fetchOptions } = opts
+  if (!base) throw new Error('[epx-icons] createShardLoader 需要 base')
+
+  let manifestPromise = null
+  const getManifest = () => {
+    if (!manifestPromise) {
+      manifestPromise = fetch(`${base}/manifest.json`, fetchOptions).then(r => {
+        if (!r.ok) throw new Error(`manifest.json ${r.status} ${r.statusText}`)
+        return r.json()
+      }).then(m => {
+        if (!m || !Number.isInteger(m.shards) || m.shards < 1) {
+          throw new Error(`${base}/manifest.json 里没有合法的 shards 字段`)
+        }
+        return m
+      }).catch(err => {
+        manifestPromise = null // 别把失败缓存住，下次还能重试
+        throw err
+      })
+    }
+    return manifestPromise
+  }
+
+  const cache = new Map()
+  const load = (n, hash) => {
+    if (!cache.has(n)) {
+      const url = `${base}/${n}.json${hash ? `?v=${hash}` : ''}`
+      cache.set(n, fetch(url, fetchOptions).then(r => {
+        if (!r.ok) throw new Error(`${n}.json ${r.status} ${r.statusText}`)
+        return r.json()
+      }).catch(err => { cache.delete(n); throw err }))
+    }
+    return cache.get(n)
+  }
+
+  return async (names) => {
+    const m = await getManifest()
+    // ⚠️ 按**裸名**算片号：构建期切片时用的就是裸名（rocket-line），
+    //    这里传 'ri-rocket-line' 会算出另一个片号，稳定地取错。
+    const bare = names.map(n => n.replace(/^ri-/, ''))
+    const need = new Set(bare.map(n => shardOf(n, m.shards)))
+    const parts = await Promise.all([...need].map(n => load(n, m.hash)))
+    // 分片文件是 { prefix, width, height, icons }，要合的是 icons 那一层
+    return Object.assign({}, ...parts.map(p => (p && p.icons) || {}))
+  }
+}
+
+/**
+ * 名字 → 片号。FNV-1a 的变体，够均匀且实现极短。
+ * ⚠️ 构建期切片时**必须用同一个函数**，否则运行时会去错误的片里找。
+ */
+export function shardOf (name, shards = 64) {
+  let h = 2166136261
+  for (let i = 0; i < name.length; i++) {
+    h ^= name.charCodeAt(i)
+    h = Math.imul(h, 16777619)
+  }
+  return (h >>> 0) % shards
+}
+
+/** 仅供测试：清空运行时状态。 */
+export function __reset () {
+  loader = null
+  match = DEFAULT_MATCH
+  timeoutMs = 0
+  ready.clear()
+  inflight.clear()
+  warnedHostMissing = false
+  if (hasDom()) {
+    const style = document.head.querySelector(`style[${STYLE_ATTR}]`)
+    if (style) style.remove()
+  }
+}

package/src/vite-plugin.mjs

@@ -0,0 +1,345 @@
+// epx-frame 图标插件（产品项目用）：让消费方也能「直接写 ri-xxx」。
+//
+// 背景：461 个 el-icon-*/epx-icon-* 是**兼容层**，已经烤进 lib/assets/*.css 随包发布，
+// 消费方拿到即用、不需要这个插件。但 Remix 那 3229 个是**按需**的——用到哪些只有消费方
+// 自己的源码知道，平台没法替它决定，所以这部分必须在消费方的构建里生成。
+//
+// 为什么两层不会打架：名字空间完全不相交（el-icon-*/epx-icon-* vs ri-*）。
+// 宿主规则（给盒子/mask/currentColor）本插件**自带**一份（见下面 RI_HOST），
+// 不依赖消费方装的 epx-frame 版本里 base.scss 编出来的那份——两者等价，
+// 同时存在只是重复声明。曾经依赖过，代价是版本一旧图标就静默消失。
+//
+// 用法（vite.config.js）：
+//     import epxIcons from 'epx-frame/build/vite-plugin-icons.mjs'
+//     export default { plugins: [epxIcons()] }
+// 然后在入口引一次（与 UnoCSS 的 `import 'uno.css'` 同一约定）：
+//     import 'virtual:epx-icons.css'
+//
+// 之后写 <i class="ri-rocket-line"></i> 就能用，零配置。
+// 扫不到的两种（值来自数据库、名字是拼出来的）用 include 登记，见下面的选项说明。
+//
+// ⚠️ @iconify-json/ri 是 **optional peer**：只有要用 Remix 图标的项目才需要装它。
+// 没装时插件不报错、只是不产出任何规则（consumer 可能压根不用 ri-），
+// 但**写了 ri- 却没装**会拿到一条明确的提示，而不是图标静默消失。
+import fs from 'node:fs'
+import path from 'node:path'
+import crypto from 'node:crypto'
+import { createRequire } from 'node:module'
+// ⚠️ 方向是单向的：Node 端的插件可以引浏览器端的 runtime（它零 import、无顶层 DOM
+// 访问，在 Node 里 import 安全），反过来**绝对不行**——那会把 node:fs 拖进浏览器产物。
+//
+// 为什么非要引它而不是各写一份 shardOf：切片时用哪个函数决定图标落在哪一片，
+// 运行时用哪个函数决定去哪一片找。两边只要有一点不一致，运行时就会在错误的片里
+// 查无此图标 —— 而表现是**空白 + 一条"loader 没给回数据"的警告**，非常难往哈希
+// 函数上想。共用同一份是结构性保证，比"写两份再测它们相等"强一档。
+import { shardOf } from './runtime.mjs'
+
+const VIRTUAL = 'virtual:epx-icons.css'
+const RESOLVED = '\0' + VIRTUAL
+const DIRECT = /\bri-[a-z0-9-]+\b/g
+const DEFAULT_ROOTS = ['src']
+const DEFAULT_EXT = /\.(vue|js|jsx|ts|tsx|scss|css)$/
+
+function walk (dir, out = []) {
+  let items
+  try { items = fs.readdirSync(dir) } catch { return out }
+  for (const it of items) {
+    if (it === 'node_modules' || it.startsWith('.')) continue
+    const p = path.join(dir, it)
+    let st
+    try { st = fs.statSync(p) } catch { continue }
+    if (st.isDirectory()) walk(p, out)
+    else if (DEFAULT_EXT.test(p)) out.push(p)
+  }
+  return out
+}
+
+// 与平台 build/icons/gen-icon-css.mjs 同一套编码，产出的 data URI 逐字节可比
+function encodeSvgDataUri (svg) {
+  return svg.replace(/"/g, "'").replace(/%/g, '%25').replace(/#/g, '%23')
+    .replace(/</g, '%3C').replace(/>/g, '%3E').replace(/\s+/g, ' ')
+}
+
+// 存量彩色图标的名字（随 lib 的彩色字体一起发布，固定不变）。
+// 内联在这里只为一件事：项目新增的彩色图标**与这 24 个撞名会同时渲染两份**
+// （字体的 content 叠上这里的 background），必须挡住。名单是从
+// public/font/font_2612462/iconfont.css 现取的，字体换了要同步。
+const FONT_COLOR_NAMES = new Set([
+  'epx-icon-color-a-404', 'epx-icon-color-a-500', 'epx-icon-color-caozuochenggong',
+  'epx-icon-color-daorukaohejieguo', 'epx-icon-color-faqiniandukaohe', 'epx-icon-color-feishulogo',
+  'epx-icon-color-kaohedengji', 'epx-icon-color-kaohefangan', 'epx-icon-color-kaohejieguo',
+  'epx-icon-color-kaohetongji', 'epx-icon-color-kaohezhuti', 'epx-icon-color-kong',
+  'epx-icon-color-kong1', 'epx-icon-color-liulanqibuzhichi', 'epx-icon-color-mubiaozhiding',
+  'epx-icon-color-nianduhuibao', 'epx-icon-color-tab', 'epx-icon-color-tianjiabaobiao',
+  'epx-icon-color-tianjiazujian', 'epx-icon-color-tingyongtishi', 'epx-icon-color-yejishenbao',
+  'epx-icon-color-yichuli', 'epx-icon-color-yidongduankaohe', 'epx-icon-color-yinyong'
+])
+const COLOR_NAME_RE = /^epx-icon-color-[a-z0-9-]+$/
+
+// ri- 的宿主规则（盒子 + mask + currentColor），两条，交给下面的 join 拼。
+//
+// 为什么插件要自带一份：base.scss 里有等价的一份、随 lib 发布，但**不能依赖它**——
+// 消费方装的 epx-frame 可能比本插件旧（那个版本的 lib 里根本没有 ri- 宿主选择器），
+// 届时 --epx-i 有值却没有盒子去画 = 图标静默消失，零报错。实测发生过：base.scss 的
+// ri- 规则是后加的，早于它构建出来的 lib 里 ri- 命中数为 0。
+// colorRules 从一开始就是自包含的（见其头注释），这里只是让 ri- 跟上同一个原则。
+//
+// 与 lib 里那份等价，同时存在也只是重复声明：CSS 幂等，重复串 gzip 压掉。
+const RI_HOST = [
+  '[class^="ri-"],[class*=" ri-"]{display:inline-block;font-style:normal;' +
+  '-webkit-font-smoothing:antialiased;-moz-osx-font-smoothing:grayscale}',
+  '[class^="ri-"]::before,[class*=" ri-"]::before{--epx-i:linear-gradient(#0000,#0000);' +
+  'content:"";display:inline-block;width:1em;height:1em;background-color:currentColor;' +
+  '-webkit-mask:var(--epx-i) no-repeat center/100%;mask:var(--epx-i) no-repeat center/100%;' +
+  'vertical-align:-0.125em}'
+]
+
+// 项目新增的彩色图标 → 规则。彩色走 background-image 不是 mask：
+// mask + currentColor 产出的必然是单色剪影，多色 SVG 进去会被压成一个颜色。
+// 规则必须自包含——base.scss 的宿主规则把 epx-icon-color-* 排除在外，拿不到那边的盒子样式。
+function colorRules (color, projectRoot) {
+  const out = []
+  for (const [name, value] of Object.entries(color)) {
+    if (!COLOR_NAME_RE.test(name)) {
+      throw new Error(`[epx-icons] "${name}" 不是合法的彩色图标名——必须形如 epx-icon-color-xxx`)
+    }
+    if (FONT_COLOR_NAMES.has(name)) {
+      throw new Error(`[epx-icons] "${name}" 与平台存量彩色图标同名——会同时渲染两份（字体的 content 叠上这里的 background）。换个名字。`)
+    }
+    let svg = String(value).trim()
+    if (!svg.startsWith('<svg')) {
+      const file = path.resolve(projectRoot, svg)
+      if (!fs.existsSync(file)) {
+        throw new Error(`[epx-icons] "${name}" 指向的文件不存在：${file}（值不以 <svg 开头时按相对项目根解析）`)
+      }
+      svg = fs.readFileSync(file, 'utf8').trim()
+    }
+    if (!/^<svg[\s>]/.test(svg)) throw new Error(`[epx-icons] "${name}" 的内容不是 SVG`)
+    if (!/viewBox\s*=/.test(svg)) {
+      throw new Error(`[epx-icons] "${name}" 的 SVG 缺 viewBox——没有它就不会随 font-size 缩放，会静默走形。`)
+    }
+    out.push(`.${name}::before{content:'';display:inline-block;width:1em;height:1em;` +
+      `background:url("data:image/svg+xml,${encodeSvgDataUri(svg)}") no-repeat center/100%;` +
+      'vertical-align:-0.125em}')
+  }
+  return out
+}
+
+// 切片：把 Remix 全量数据切成 N 份静态 JSON，供运行时按需取。
+//
+// 定位要说清楚——这些**不进 JS/CSS bundle**，是躺在产物目录里的独立文件。
+// 磁盘上约 1MB，下载量取决于用户实际见到多少个长尾图标：一片约 4KB gzip，
+// 一个片都没用到就一个字节都不下。「热门内联 + 长尾按需」里，这是长尾那一半。
+//
+// 为什么切全量而不是「全量减去已内联的」：后者会让分片内容随「这次构建内联了哪些」
+// 变化 —— 加一个内联图标就让一堆分片的内容位移、缓存全废。切全量则内容只随
+// Remix 版本变，稳定得多；已内联的那些运行时探测直接放行，永远不会去取。
+//
+// 幂等：内容没变就不写盘（与本插件其余部分同一约定）。
+function writeShards (opts, data, projectRoot, log) {
+  const dir = path.resolve(projectRoot, opts.dir)
+  // ⚠️ 不能写 `opts.count || 64`：0 是 falsy，会被静默换成 64，
+  //    于是「非法值」变成「默认值」，下面那道校验永远拦不到 0。
+  const count = opts.count === undefined ? 64 : opts.count
+  if (!Number.isInteger(count) || count < 1) {
+    throw new Error(`[epx-icons] shards.count 必须是正整数，收到 ${count}`)
+  }
+
+  const names = Object.keys(data.icons)
+  const buckets = Array.from({ length: count }, () => ({}))
+  for (const name of names) {
+    // ⚠️ 这里用的是运行时导出的同一个 shardOf（见文件头 import 处的说明）。
+    //    切片按裸名（rocket-line）算，运行时也按裸名算 —— 两边必须同一口径。
+    buckets[shardOf(name, count)][name] = data.icons[name]
+  }
+
+  const payloads = buckets.map((icons, i) => JSON.stringify({
+    prefix: data.prefix || 'ri',
+    width: data.width || 24,
+    height: data.height || 24,
+    icons
+  }))
+  const hash = crypto.createHash('sha256')
+    .update(payloads.join('')).digest('hex').slice(0, 8)
+  const manifest = JSON.stringify({ prefix: data.prefix || 'ri', shards: count, hash, total: names.length })
+
+  fs.mkdirSync(dir, { recursive: true })
+
+  // 清掉上一次留下的、这一次不再产出的分片：count 从 64 改成 32 时，
+  // 32~63 号文件会**留在产物里继续被服务**，运行时按新 count 算出的片号
+  // 永远取不到它们，但它们又确实存在 —— 只删形如 <数字>.json 的，不碰别的文件。
+  let removed = 0
+  for (const f of fs.readdirSync(dir)) {
+    const m = /^(\d+)\.json$/.exec(f)
+    if (m && Number(m[1]) >= count) { fs.unlinkSync(path.join(dir, f)); removed++ }
+  }
+
+  let written = 0
+  const put = (file, content) => {
+    const abs = path.join(dir, file)
+    let prev = null
+    try { prev = fs.readFileSync(abs, 'utf8') } catch { /* 不存在 */ }
+    if (prev === content) return
+    fs.writeFileSync(abs, content)
+    written++
+  }
+  payloads.forEach((p, i) => put(`${i}.json`, p))
+  put('manifest.json', manifest)
+
+  const bytes = payloads.reduce((s, p) => s + Buffer.byteLength(p), 0)
+  log(`[epx-icons] 分片 ${count} 份、图标 ${names.length} 个、磁盘 ${(bytes / 1024 / 1024).toFixed(2)}MB` +
+    `（写 ${written} 个文件${removed ? `，清理陈旧 ${removed} 个` : ''}）→ ${opts.dir}`)
+  return { count, hash, total: names.length }
+}
+
+/**
+ * 单独产出分片，不经过插件。
+ *
+ * 给**有自己构建管线、不挂本插件**的消费方用——平台仓库就是这样：它的 461 条规则由
+ * build/icons/gen-icon-css.mjs 直接生成，vite.config.mjs 里没有 epxIcons 插件。让它
+ * 为了切片而挂一个「只写文件、CSS 产物没人用」的插件是本末倒置。
+ *
+ * @param {object} opts            同插件的 options.shards
+ * @param {string} opts.dir        写到哪（相对 cwd 或 opts.root）
+ * @param {number} [opts.count=64] 切几片
+ * @param {string} [opts.root]     项目根，默认 process.cwd()
+ * @param {function} [opts.log]    日志出口，默认 console.log
+ */
+export function emitShards (opts = {}) {
+  if (!opts.dir) throw new Error('[epx-icons] emitShards 需要 dir')
+  const root = opts.root || process.cwd()
+  let data
+  try {
+    data = createRequire(path.join(root, 'package.json'))('@iconify-json/ri/icons.json')
+  } catch {
+    throw new Error('[epx-icons] emitShards 需要 @iconify-json/ri，没装切不出分片。\n' +
+      '           装上 @iconify-json/ri（npm i -D / pnpm add -D）。')
+  }
+  // eslint-disable-next-line no-console
+  return writeShards(opts, data, root, opts.log || ((m) => console.log(m)))
+}
+
+/**
+ * @param {object} [options]
+ * @param {string[]} [options.roots='src']  扫描目录，相对项目根
+ * @param {string[]} [options.include]      显式登记的图标类名（如 'ri-rocket-line'）。
+ *   给扫描看不见的用：值来自数据库的（菜单图标、按钮 iconCls、页面配置 icon），
+ *   以及名字是拼出来的（`'ri-' + type`）。构建期没有库连接、配置又随时可改，
+ *   这两种在原理上就扫不到。
+ * @param {Record<string,string>} [options.color]  项目自己的**彩色**图标：名字 → SVG 路径（相对项目根）或内联 SVG。
+ *   平台那 24 个彩色插画已随 lib 发布、不用管；这里只加你自己的。撞名会响亮失败。
+ * @param {boolean} [options.failOnUnknown=true] 名字在 Remix 里查无此名时是否中断构建。
+ *   默认中断——静默跳过等于让拼错的图标悄悄变空白，很久之后才被用户发现。
+ * @param {object} [options.shards]       产出静态分片，供运行时按需取长尾图标。不给就不产出。
+ * @param {string} [options.shards.dir]   写到哪（相对项目根）。建议 'public/epx-icons'——
+ *   Vite 会把 public/ 原样拷进产物、dev 下也直接可访问，URL 因此是可预测的，
+ *   运行时才能「按名字算片号 → 直接拼 URL」，不需要额外的索引文件。
+ * @param {number} [options.shards.count=64] 切几片。与运行时无需对齐：运行时从
+ *   manifest.json 里读，改了这个值不会造成两边不一致。
+ */
+export default function epxIcons (options = {}) {
+  const {
+    roots = DEFAULT_ROOTS,
+    include = [],
+    color = {},
+    failOnUnknown = true,
+    shards = null
+  } = options
+
+  let projectRoot = process.cwd()
+  let css = ''
+
+  const loadRi = () => {
+    try {
+      return createRequire(path.join(projectRoot, 'package.json'))('@iconify-json/ri/icons.json')
+    } catch {
+      return null
+    }
+  }
+
+  const build = () => {
+    const names = new Set()
+    for (const n of include) names.add(n)
+    for (const r of roots) {
+      for (const abs of walk(path.resolve(projectRoot, r))) {
+        for (const m of fs.readFileSync(abs, 'utf8').matchAll(DIRECT)) names.add(m[0])
+      }
+    }
+    // 彩色图标与 ri- 无关，任何情况下都要产出
+    const cRules = colorRules(color, projectRoot)
+    const done = (riRules, unknown = []) => {
+      // 有 ri- 规则才带宿主：一个 ri- 都没用的项目，虚拟 CSS 里不该多出无用选择器
+      const all = (riRules.length ? RI_HOST : []).concat(riRules, cRules)
+      css = all.join('\n') + (all.length ? '\n' : '')
+      return { count: riRules.length, colorCount: cRules.length, unknown }
+    }
+
+    if (!names.size) return done([])
+
+    const data = loadRi()
+    if (!data) {
+      const msg = `[epx-icons] 源码里用到了 ${names.size} 个 ri- 图标，但没装 @iconify-json/ri。\n` +
+        '           装上 @iconify-json/ri（npm i -D / pnpm add -D）之后重新构建。\n' +
+        '           不装的话这些图标不会有任何样式规则——是空白，不会报错。'
+      if (failOnUnknown) throw new Error(msg)
+      // eslint-disable-next-line no-console
+      console.warn(msg)
+      return done([])
+    }
+
+    const rules = []
+    const unknown = []
+    for (const cls of [...names].sort()) {
+      const ic = data.icons[cls.slice(3)]
+      if (!ic) { unknown.push(cls); continue }
+      const w = ic.width || data.width || 24
+      const h = ic.height || data.height || 24
+      const svg = `<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 ${w} ${h}">${ic.body}</svg>`
+      rules.push(`.${cls}::before{--epx-i:url("data:image/svg+xml,${encodeSvgDataUri(svg)}")}`)
+    }
+    if (unknown.length) {
+      const msg = `[epx-icons] ${unknown.length} 个 ri- 图标名在 Remix 里查无此名：${unknown.join(', ')}\n` +
+        '           去 https://remixicon.com 核对拼写。名字对不上就不会生成规则，图标是空白、不报错。'
+      if (failOnUnknown) throw new Error(msg)
+      // eslint-disable-next-line no-console
+      console.warn(msg)
+    }
+    return done(rules, unknown)
+  }
+
+  return {
+    name: 'epx-icons',
+    configResolved (cfg) { projectRoot = cfg.root || process.cwd() },
+    buildStart () {
+      const { count, colorCount } = build()
+      // eslint-disable-next-line no-console
+      const log = (msg) => console.log(msg)
+      log(`[epx-icons] Remix 图标 ${count} 个（扫描 ${roots.join(', ')}` +
+        `${include.length ? ` + 登记 ${include.length}` : ''}）` +
+        `${colorCount ? `；项目彩色图标 ${colorCount} 个` : ''}`)
+
+      if (!shards) return
+      if (!shards.dir) throw new Error('[epx-icons] shards 需要 dir（建议 "public/epx-icons"）')
+      // 切片**不看扫描结果**：长尾图标的名字本来就来自数据库、源码里一个都没有，
+      // 按扫描结果切等于把要按需的那部分排除在外，正好切反了。
+      const data = loadRi()
+      if (!data) {
+        throw new Error('[epx-icons] 配了 shards 但没装 @iconify-json/ri，切不出分片。\n' +
+          '           装上 @iconify-json/ri（npm i -D / pnpm add -D）。')
+      }
+      writeShards(shards, data, projectRoot, log)
+    },
+    resolveId (id) { return id === VIRTUAL ? RESOLVED : null },
+    load (id) { return id === RESOLVED ? css : null },
+    // dev 下改了源码要能立刻反映新图标：源文件变更时重扫并让虚拟模块失效
+    handleHotUpdate ({ file, server }) {
+      if (!DEFAULT_EXT.test(file)) return
+      const before = css
+      build()
+      if (before === css) return
+      const mod = server.moduleGraph.getModuleById(RESOLVED)
+      if (mod) server.moduleGraph.invalidateModule(mod)
+      server.ws.send({ type: 'full-reload' })
+    }
+  }
+}

package/types/index.d.ts

@@ -0,0 +1,6 @@
+import type { Plugin } from 'vite'
+export interface IconOptions {
+  [key: string]: unknown
+}
+export declare function emitShards(options?: IconOptions): unknown
+export default function epxIcons(options?: IconOptions): Plugin

package/types/runtime.d.ts

@@ -0,0 +1,15 @@
+export interface IconRuntimeOptions {
+  loader?: (names: string[]) => Promise<unknown>
+  timeout?: number
+  [key: string]: unknown
+}
+export declare function configureIcons(options?: IconRuntimeOptions): void
+export declare function collectIconNames(config: unknown, out?: Set<string>): string[]
+export interface IconResult { ready: string[]; missing: string[] }
+export declare function ensureIcon(name: string): Promise<IconResult>
+export declare function ensureIcons(names: Iterable<string>): Promise<IconResult>
+export declare function createEndpointLoader(options?: Record<string, unknown>): (names: string[]) => Promise<unknown>
+export declare function createShardLoader(options?: Record<string, unknown>): (names: string[]) => Promise<unknown>
+export declare function shardOf(name: string, shards?: number): number
+/** @internal 仅供测试：清空图标运行时状态。 */
+export declare function __reset(): void