webc.com 0.1.25 → 0.1.26

package/Lg/Lg.styl

@@ -0,0 +1,30 @@
+.Lg
+  position relative
+  z-index 1
+
+  &::before
+    backdrop-filter blur(30px) saturate(150%) var(--glassSvg)
+    background linear-gradient(180deg, #f5f5f54d, #f5f5f580)
+    border-radius inherit
+    content ''
+    filter var(--highlightSvg)
+    inset 0
+    position absolute
+    transition background 0.3s cubic-bezier(0.4, 0, 0.2, 1)
+    z-index -1
+
+  &::after
+    background-clip border-box
+    background-image linear-gradient(180deg, #00000026, #0000000f)
+    background-origin border-box
+    border 1px solid transparent
+    border-radius inherit
+    border-width 0.5px
+    content ''
+    inset 0
+    mask-clip content-box, border-box
+    mask-composite exclude
+    mask-image linear-gradient(#fff 0 0), linear-gradient(#fff 0 0)
+    pointer-events none
+    position absolute
+    z-index -1

package/Lg/svg/glass.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg"/>

package/Lg/svg/highlight.svg

@@ -0,0 +1 @@
+<svg xmlns="http://www.w3.org/2000/svg"/>

package/Lg/var.styl

@@ -0,0 +1,3 @@
+:root
+  --glassSvg url('./svg/glass.svg#l')
+  --highlightSvg url('./svg/highlight.svg#hl')

package/README.md

@@ -1,14 +1,14 @@
-# WebC
+# WebC.site
 
-面向 AI 辅助开发设计的 Web Components 组件库与开发规范。
+[组件库在线预览](https://webc-zh.pages.dev)
 
-[组件库在线预览](https://webc-zh.github.io)
+面向 AI 辅助开发设计的 Web Components 组件库与开发规范。
 
 ## 特性
 
 - **跨框架**：基于原生 Web Components 构建，兼容 React、Vue、Svelte、Solid 等前端框架。
 - **无样式**：逻辑与样式解耦，支持仅引入逻辑以自定义样式。
-- **免构建与构建双模式**：
+- **免构建与构建双模式**
   - **免构建（CDN 模式）**：在浏览器中直接通过 CDN 引用 JS 与 CSS 文件。
   - **构建模式（本地命令行）**：提供本地命令行工具，按需将组件源码集成至项目。
 - **在线调试**：提供组件预览与“在线调试”入口，支持直接调试免构建组件。
@@ -19,6 +19,8 @@
 
 在免构建场景下，可通过 CDN 直接在浏览器中引用 JS 与 CSS 文件。
 
+适用于无需开发环境配置、直接引用的轻量化场景。
+
 以 `Scroll`（虚拟滚动条）组件为例：
 
 #### 使用 jsdelivr
@@ -42,23 +44,16 @@
 > [!TIP]
 > **自定义 CSS 变量（重写样式与替换背景资源）**
 > 如需重写默认样式，可引用前缀为 `_` 的样式文件（该文件不包含 `var.css` 声明）：
->
-> ```html
-> <link href="//cdn.jsdelivr.net/npm/webc.site@0.1.23/_Scroll.css" rel="stylesheet" />
-> ```
 
-### 2. 构建模式
-
-构建模式与免构建（CDN）模式特性对比：
+```html
+<link href="//cdn.jsdelivr.net/npm/webc.site@0.1.23/_Scroll.css" rel="stylesheet" />
+```
 
-- **免构建（CDN 模式）**：适用于无需开发环境配置、直接引用的轻量化场景。
-- **构建模式**：支持摇树优化与按需引入以减少构建体积，并支持静态资源优化（如 SVG 资源内联与去重）。
+### 2. 构建模式
 
-在构建项目中，可运行以下命令将组件源码引入本地：
+支持摇树优化与按需引入以减少构建体积，并支持静态资源优化（如 SVG 资源内联与去重）。
 
-```bash
-bunx webc.add <组件名>
-```
+源码会直接下载至本地，便于直接修改源码二次开发。
 
 例如添加 `Scroll`（虚拟滚动条）组件：
 
@@ -66,30 +61,72 @@ bunx webc.add <组件名>
 bunx webc.add Scroll
 ```
 
-#### 命令行工作原理
+添加组件后，本地项目将生成以下目录结构与文件（使用只需导入 `lib/<组件名>.js` 即可，会自动引入组件下的 JS 与 CSS）：
+
+| 路径                               | 说明                                           |
+| :--------------------------------- | :--------------------------------------------- |
+| `lib/<组件名>.js`                  | 组件入口文件                                   |
+| `lib/<组件名>/`                    | 组件源码编译目录                               |
+| `lib/<组件名>/index.js`            | 组件 JavaScript 逻辑文件                       |
+| `lib/<组件名>/index.css`           | 组件 CSS 样式文件（Stylus 编译产物）           |
+| `lib/css/`                         | 公共样式目录                                   |
+| `lib/css/<样式名>.css`             | 公共 Stylus 样式编译出的 CSS（如 `reset.css`） |
+| `lib/x/`                           | 依赖的公共基础模块目录（按需下载）             |
+| `lib/x/<模块名>.js`                | 依赖的公共基础模块文件                         |
+| `public/com/<组件名>/`             | 组件静态资源目录                               |
+| `public/com/<组件名>/<资源名>.svg` | 组件引用的 SVG 静态资源                        |
+
+### 3. SVG 资源优化
+
+在 Vite 构建配置中，推荐配合使用 [vite-plugin-svg-var](https://www.npmjs.com/package/vite-plugin-svg-var) 插件优化 SVG 资源加载。
 
-1. **解析依赖**：查询 npm 注册表并解析 `webc.com` 包源。
-2. **源码集成**：下载包源并提取目标组件源码，编译输出至本地项目的 `lib/<组件名>` 目录。
-3. **样式处理**：将组件关联的 Stylus 代码编译为 CSS，并集成至公共样式。
+#### 核心功能
 
-### 3. SVG 资源优化 (`vite-plugin-svg-var`)
+构建或开发阶段，插件在项目入口 JS（匹配 `/page/entry/**/*.js`）中注入 CSS 变量样式，并将 CSS/Stylus/Svelte 中引用的本地 SVG 路径（如 `url("/com/Scroll/cursor/grab.svg")`）自动替换为 `var(--grabSvg)` 形式，以减少网络请求。
 
-在 Vite 构建配置中，配合使用 [vite-plugin-svg-var](https://www.npmjs.com/package/vite-plugin-svg-var) 插件优化 SVG 资源加载：
+#### 特性
 
-- **内容去重**：对 `public/svg` 目录下的 SVG 进行 MD5 哈希校验。内容相同的 SVG 文件仅生成单个 CSS 变量，避免资源冗余。
-- **UTF-8 编码**：将 SVG 转为 UTF-8 编码的 `data:image/svg+xml` 并写入 CSS 变量，降低编码体积，提升压缩率。
-- **替换与注入**：构建或开发阶段，插件在项目入口 JS（匹配 `/page/entry/**/*.js`）中注入 CSS 变量样式，并将 CSS/Stylus/Svelte 中引用的 `url("/svg/xxx.svg")` 替换为 `var(--xxxSvg)` 形式，减少网络请求。
-- **热更新**：监听 `public/svg` 目录变动，在新增、修改或删除 SVG 文件时，重新计算 CSS 变量并触发热重载。
+- **UTF-8 编码**：将 SVG 转为 UTF-8 编码的 `data:image/svg+xml`（而不是 base64）并写入 CSS 变量，降低编码体积，提升压缩率。
+- **内容去重**：内容相同的 SVG 文件仅生成单个 CSS 变量，避免资源冗余。
+- **热更新**：监听 `public` 目录变动，在新增、修改或删除 SVG 文件时，重新计算 CSS 变量并触发热重载。
 
-## AI 驱动开发规范
+### 4. 中文字体分片
+
+为了优化中文字体在 Web 端的加载体验，组件库引入了中文字体分片包 **[18s](https://www.npmjs.com/package/18s)**。
+
+- **按需分片加载**：通过中文字体分片技术，将体积庞大的中文字体（如思源黑体）和代码/等宽字体（如 JetBrains Mono）切分为 128KB 左右的 WOFF2 小分片，浏览器根据页面实际显示的字符按需下载分片，显著缩短中文字体加载的白屏与闪烁时间。
+- **内容寻址与长缓存**：字体分片基于其内容的 MD5 Base64url 哈希值命名，防止命名冲突，并提升 CDN 缓存命中率。
+- **可变字重支持**：引入的思源黑体（别名 `t`，为 text 的缩写）与 JetBrains Mono（别名 `c`，为 code 的缩写）均为**可变字体（Variable Fonts）**。可变字体允许使用 `font-variation-settings` 属性对字重进行精准的连续调节，例如 `font-variation-settings: "wght" 500`。关于可变字体的详细介绍和使用技巧，可参考 [MDN 可变字体指南](https://developer.mozilla.org/zh-CN/docs/Web/CSS/CSS_fonts/Variable_fonts_guide) 以及 [MDN font-variation-settings 文档](https://developer.mozilla.org/zh-CN/docs/Web/CSS/font-variation-settings)。
+- **项目结构**：
+  - 构建工作区位于 **[font-gen](https://github.com/webc-site/font-gen)** (包含原始 TTF 字体、分片及样式重写脚本等)。
+  - 编译后发布的分发资源及文档位于 **[font](https://github.com/webc-site/font)**。
+- **全局样式集成**：
+  在基础样式重置文件 **[styl/reset.styl](https://github.com/webc-site/webc-zh/blob/main/styl/reset.styl)** 中通过 `@import` 引入了 `18s` 包的合并样式，并为全局和代码元素配置了字体别名与字重设置：
+
+```stylus
+  // 引入 18s 合并后的字体样式映射表
+  @import url('//registry.npmmirror.com/18s/0.2.16/files/_.css')
+
+  // 全局正文字体配置（思源黑体，别名 t 为 text 缩写，使用 font-variation-settings 精准配置可变字重）
+  html, :host
+    font-family t, ui-sans-serif, ...
+    font-variation-settings 'wght' 500
+
+  // 代码及等宽字体配置（JetBrains Mono，别名 c 为 code 缩写，同样精准配置可变字重）
+  code, kbd, samp, pre
+    font-family c, ui-monospace, ...
+    font-variation-settings 'wght' 400
+```
+
+## 人工智能驱动开发
 
 ### 1. 状态与逻辑解耦
 
-AI 智能体在通过自动化浏览器（如 Antigravity）进行界面调试时，常因交互链路长、鉴权限制以及对后端数据的依赖而导致调试中断。
+AI 通过自动化浏览器（如 Antigravity）进行开发与调试时，常因交互链路长、鉴权限制以及对后端数据的依赖而导致调试中断。
 
-为提升 AI 开发效率，本项目采用以下设计规范：
+为提效，采用以下设计规范：
 
-- **数据流向上管理**：组件内部不直接调用后端接口，数据交互均通过异步回调函数向外暴露。
+- **不调用后端**：组件内部不直接调用后端接口，数据交互均通过异步回调函数向外暴露。
 - **数据模拟**：在 `Demo.svelte` 中传入模拟数据，以展现组件在多种状态下的交互表现，免除鉴权及后端环境依赖。
 
 ### 2. 组件架构与本地调试
@@ -102,8 +139,90 @@ AI 智能体在通过自动化浏览器（如 Antigravity）进行界面调试
   ./comDev.sh com/<组件名>
   ```
 
-### 3. 智能体提示词配置
+### 3. Agent 提示词配置
 
 开发提示词配置参见 [.agents/skills/com/SKILL.md](.agents/skills/com/SKILL.md)。在谷歌反重力（Antigravity）环境下，使用 `/com` 命令即可调用。
 
 ![](https://i-01.eu.org/1779351273.avif)
+
+### 4. OpenCode 集成与 AI 提效脚本
+
+项目在 **[bin](https://github.com/webc-site/webc-zh/tree/main/bin)** 目录下提供了可以直接在终端调用的命令行工具，并结合 **[ai](https://github.com/webc-site/webc-zh/tree/main/ai)** 目录下的 AI 提效工具实现自动化提效：
+
+- **[bin/gci](https://github.com/webc-site/webc-zh/blob/main/bin/gci)**：自动生成提交信息并执行提交的 Git 工具。
+
+#### svelteSvg.js
+
+自动提取并优化 Svelte 模板中的内联 SVG 资源，防止源码因 AI 生成的内联 SVG 而臃肿。
+
+##### 背景
+
+人工智能在编写页面时，喜欢直接将 SVG 矢量图以内联方式写入 CSS。这会导致：
+
+- Svelte 源码极度臃肿，严重降低代码可读性，浪费词元。
+- 相同的 SVG 资源无法复用，无法进行静态资源去重。
+
+##### 实现原理
+
+在代码提交或通过 `bin/gci` 触发时运行 **[ai/svelteSvg.js](https://github.com/webc-site/webc-zh/blob/main/ai/svelteSvg.js)**：
+
+1. **正则扫描**：匹配 Svelte 中的内联 SVG Data URI。
+2. **AI 智能命名**：调用 LLM 自动根据 SVG 形状生成简短的小驼峰文件名（如 `search.svg`）。
+3. **压缩与修复**：使用 SVGO 压缩 SVG 内容，压缩失败则调用 AI 自动修复语法错误。
+4. **持久化与重写**：将 SVG 写入 `public/svg/` 目录，并重写模板中的内联路径为相对路径，再配合 `vite-plugin-svg-var` 转换为全局 CSS 变量引用。
+
+#### xDoc.js
+
+自动为 `x/` 目录下的公共基础模块生成和修订说明文档。
+
+##### 核心功能
+
+执行 **[ai/xDoc.js](https://github.com/webc-site/webc-zh/blob/main/ai/xDoc.js)** 进行文档自动化管理：
+
+1. **导出提取**：使用 `oxc-parser` 静态解析 JS 代码，自动提取其导出的变量、函数及参数。
+2. **动生 Schema**：根据提取出的导出结构，动态生成严密的 JSON Schema，限定 AI 响应的文档结构。
+3. **校验与自愈**：结合 `ai.js` 接口与 OpenCode 对话，自动对返回的 JSON 执行空字段过滤与 Schema 校验，校验失败将错误反馈给 AI 进行重试修复（最多 3 次）。
+4. **Markdown 渲染**：将验证通过的 JSON 结构渲染为符合 `SKILL.md` 规范的说明文档（`x/*.md`）。
+5. **两级缓存**：使用 `.tmp/xDoc.msgpack` 缓存文件大小与修改时间做加速变更检测，配合 `.cache/xDoc.yml` 缓存文件 MD5 避免无修改文件重复调用 AI。
+
+## 开发工具
+
+### 1. 环境变量自动设置 - `mise`
+
+项目使用 [mise](https://mise.jdx.dev/) 自动设置环境变量。配置文件 **[.mise.toml](https://github.com/webc-site/webc-zh/blob/main/.mise.toml)** 将 `bin` 目录加入到 `PATH`，并自动加载 `.env.sh` 环境变量。
+
+### 2. 代码提交钩子
+
+项目集成了 [Husky](https://typicode.github.io/husky/) 与 [lint-staged](https://github.com/okonet/lint-staged)，在提交代码时会自动触发校验、格式化以及资源优化，确保代码质量并减少包体积。
+
+#### 触发流程
+
+在提交代码时，[.husky/pre-commit](https://github.com/webc-site/webc-zh/blob/main/.husky/pre-commit) 钩子会按以下顺序执行：
+
+1. **全局校验与扫描**：执行 [sh/hook/fmt.sh](https://github.com/webc-site/webc-zh/blob/main/sh/hook/fmt.sh) 进行全量代码格式化与死代码扫描。
+2. **暂存文件优化**：执行 `lint-staged` 对暂存区文件根据后缀名分别调用针对性的优化脚本（配置见 [package.json](https://github.com/webc-site/webc-zh/blob/main/package.json) 中的 `lint-staged` 部分）。
+3. **自动更新暂存区**：如果环境变量 `$S` 未设置，脚本会自动运行 `git add -u` 将格式化和优化后的最新修改加入暂存区，保证提交内容的一致性。
+
+#### 钩子脚本与功能介绍
+
+##### 格式校验
+
+[sh/hook/fmt.sh](https://github.com/webc-site/webc-zh/blob/main/sh/hook/fmt.sh)
+
+- **`oxfmt`**：使用 Rust 编写的高性能格式化工具快速美化代码。
+- **`oxlint --fix`**：使用高性能校验工具扫描并自动修复可修复的 JavaScript 代码问题。
+- **`knip-bun`**：分析并输出未使用的文件、导出项和依赖，辅助代码瘦身。
+
+##### 优化代码
+
+- `**/*.svg` — [sh/hook/svg.js](https://github.com/webc-site/webc-zh/blob/main/sh/hook/svg.js)
+  对暂存的 SVG 矢量图进行压缩与规范化（使用 SVGO 引擎），删除多余元数据并精简路径，减小文件体积。
+- `**/*.svelte` — [sh/hook/svelte.js](https://github.com/webc-site/webc-zh/blob/main/sh/hook/svelte.js)
+  1. **自动修正导入路径**：调用 [importFix.js](https://github.com/webc-site/webc-zh/blob/main/sh/hook/importFix.js) 将所有相对导入路径（如 `./`、`../`）统一重写为项目绝对别名（如 `~/` 或 `x/`）。
+  2. **格式化校验**：使用 `fmt_svelte` 进行格式化，若包含语法或结构错误将拒绝提交。
+  3. **SVG 内联压缩**：通过 [svelteSvgMinify.js](https://github.com/webc-site/webc-zh/blob/main/sh/hook/svelteSvgMinify.js) 自动压缩 Svelte 模板中包含的内联 SVG 标签和样式中引用的编码数据。
+- `**/*.styl` — [sh/hook/styl.js](https://github.com/webc-site/webc-zh/blob/main/sh/hook/styl.js)
+  1. **自动修正引入路径**：重写 `@import` 中的相对路径。
+  2. **代码格式化**：调用 `stylus-supremacy` 配合项目根目录的 [supremacy.yml](https://github.com/webc-site/webc-zh/blob/main/supremacy.yml) 对 Stylus 样式代码进行格式化。
+- `**/*.js` — [sh/hook/js.js](https://github.com/webc-site/webc-zh/blob/main/sh/hook/js.js)
+  **自动修正导入路径**：调用 [importFix.js](https://github.com/webc-site/webc-zh/blob/main/sh/hook/importFix.js) 统一重写 JS 文件中的相对导入路径。

package/index.js

@@ -1 +1 @@
-export default ["Wait","Scroll"];
+export default ["Wait","Scroll","Lg"];

package/package.json

@@ -1 +1 @@
-{"name":"webc.com","version":"0.1.25","description":"","keywords":[],"homepage":"https://webc-zh.github.io","license":"MulanPSL-2.0","author":"i18n.site@gmail.com","repository":{"type":"git","url":"git+https://github.com/webc-zh/webc-zh.github.io.git"},"bin":{"webc-i":"./cli.js"},"files":["./*"],"type":"module","exports":{"./*":"./*"},"scripts":{},"dependencies":{"@3-/read":"^0.1.4","ansis":"^4.3.0","stylus":"^0.64.0","tar":"^7.5.15","yargs":"^18.0.0"},"devDependencies":{}}
+{"name":"webc.com","version":"0.1.26","description":"","keywords":[],"homepage":"https://webc-zh.pages.dev","license":"MIT","author":"i18n.site@gmail.com","repository":{"type":"git","url":"git+https://github.com/webc-site/webc-zh.git"},"bin":{"webc-i":"./cli.js"},"files":["./*"],"type":"module","exports":{"./*":"./*"},"scripts":{},"dependencies":{"@3-/log":"^0.1.9","@3-/read":"^0.1.4","stylus":"^0.64.0","tar":"^7.5.15","yargs":"^18.0.0"},"devDependencies":{}}

package/styl/reset.styl

@@ -1,3 +1,5 @@
+@import url('//registry.npmmirror.com/18s/0.2.16/files/_.css')
+
 /*
 Please read: https://github.com/unocss/unocss/blob/main/packages-presets/reset/tailwind-compat.md
 */
@@ -22,9 +24,10 @@ Please read: https://github.com/unocss/unocss/blob/main/packages-presets/reset/t
 7. Disable tap highlights on iOS.
 */
 html, :host
-  font-family ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji' /* 4 */
+  font-family t, ui-sans-serif, system-ui, sans-serif, 'Apple Color Emoji', 'Segoe UI Emoji', 'Segoe UI Symbol', 'Noto Color Emoji' /* 4 */
   font-feature-settings normal /* 5 */
-  font-variation-settings normal /* 6 */
+  font-variation-settings 'wght' 400 /* 6 */
+  font-weight 400
   line-height 1.5 /* 1 */
   tab-size 4 /* 3 */
   -moz-tab-size 4 /* 3 */
@@ -82,7 +85,7 @@ b, strong
 4. Correct the odd `em` font sizing in all browsers.
 */
 code, kbd, samp, pre
-  font-family ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace /* 1 */
+  font-family c, ui-monospace, SFMono-Regular, Menlo, Monaco, Consolas, 'Liberation Mono', 'Courier New', monospace /* 1 */
   font-feature-settings normal /* 2 */
   font-size 1em /* 4 */
   font-variation-settings normal /* 3 */

package/x/On.md

@@ -1,8 +1,12 @@
 # 绑定与解绑事件监听
 
-- `On(elem, dict)`
-  - `elem`: DOM 元素。
-  - `dict`: 事件与回调对象。键为事件名，值为回调函数。回调函数格式：
-    - 参数：`e`（事件对象）。
-    - 返回值：无。
-  - 返回值：解绑函数。格式为 `() => void`。
+## `On` : 批量绑定事件监听器到指定的 DOM 元素或对象，并返回一键解绑函数
+
+### 参数
+
+- elem : DOM 元素或支持 addEventListener 接口的事件目标对象
+- dict : 键为事件名称、值为事件处理回调函数的映射对象
+
+### 返回值
+
+解绑该次批量绑定的所有事件监听器的函数

package/x/README.md

@@ -0,0 +1 @@
+# x : webc.site 的基础依赖库

package/x/a.md

@@ -1,3 +1,3 @@
-# 拦截链接点击实现无刷新跳转
+# 页面跳转拦截
 
-无导出函数。导入时自动在 `document.body` 监听点击事件。点击同站链接时阻止默认行为并调用 `goto` 跳转，点击外链且无 `target` 属性时将其设为 `_blank`。
+全局监听 DOM 点击事件，向上追溯 A 标签。若 A 标签含有效 href，调用 `selfA(p, e)` 处理链接：若返回非 undefined 值，则阻止默认行为并调用 `goto` 进行无刷新跳转；否则，若 A 标签未指定 `target` 属性，则自动设为 `_blank` 在新窗口打开。遍历至 BODY 元素则终止。

package/x/dom.md

@@ -1,7 +1,15 @@
-# DOM 属性与方法简写
+# DOM 常用对象与元素创建捷径
 
-- `D`: `document` 实例。
-- `B`: `document.body` 元素。
-- `newEl(tagName)`
-  - `tagName`: 字符串，HTML 标签名。
-  - 返回值：新创建的 DOM 元素。
+## `D` : 快捷访问全局 document 对象
+
+## `B` : 快捷访问 document.body 元素
+
+## `newEl()` : 绑定到全局 document 对象的 createElement 方法，用于快速创建 DOM 元素
+
+### 参数
+
+- tagName : 待创建 HTML 元素的标签名
+
+### 返回值
+
+新创建的 HTML 元素

package/x/package.json

@@ -3,12 +3,12 @@
   "version": "0.2.0",
   "description": "",
   "keywords": [],
-  "homepage": "https://webc-zh.github.io",
-  "license": "MulanPSL-2.0",
+  "homepage": "https://webc-zh.pages.dev",
+  "license": "MIT",
   "author": "i18n.site@gmail.com",
   "repository": {
     "type": "git",
-    "url": "git+https://github.com/webc-zh/webc-zh.github.io.git"
+    "url": "git+https://github.com/webc-site/webc-zh.git"
   },
   "files": [
     "./*"

package/x/rmWait.js

@@ -1,2 +1,2 @@
-import { D } from "./dom.js";
+import { D } from "x/dom.js";
 D.getElementById("W").remove();

package/x/rmWait.md

@@ -1,3 +1,3 @@
-# 移除加载等待元素
+# 页面初始加载动画移除
 
-无导出函数。导入时自动从 DOM 中移除 ID 为 `W` 的元素。
+DOM初始化后导入即触发。通过获取 ID 为 'W' 的页面加载动画元素并执行 `remove()` 进行销毁，以呈现最终渲染页面。

package/x/route.js

@@ -1,60 +1,59 @@
 import { On } from "x/On.js";
 
-export const nowUrl = () => location.pathname.slice(1),
-  [route, setPre, preUrl, refresh, removeSlash, split, setUrl, goto] = (() => {
-    let PRE = nowUrl(),
-      HOOK = [];
-    if (location.hash) PRE += location.hash;
+const HASH = "#";
+
+let pre,
+  hooks = [];
 
-    const HASH = "#",
-      route = (hook) => {
-        HOOK.push(hook);
-        hook(nowUrl());
-        return () => {
-          HOOK = HOOK.filter((f) => f !== hook);
-        };
-      },
-      setPre = (url) => {
-        PRE = url;
-      },
-      preUrl = () => PRE,
-      refresh = (url) => {
-        url = url || nowUrl();
-        for (const f of HOOK) f(url, PRE);
-        setPre(url);
-      },
-      removeSlash = (url) => (url[0] === "/" ? url.slice(1) : url),
-      split = (str, s) => {
-        const p = str.indexOf(s);
-        return p >= 0 ? [str.slice(0, p), str.slice(p + 1)] : [str, ""];
-      },
-      setUrl = (url) => {
-        url = removeSlash(url);
-        if (url !== PRE) {
-          const [path, hash] = split(url, HASH),
-            [p] = split(PRE, HASH);
-          setPre(url);
-          if (path !== p) {
-            history.pushState(null, "", "/" + url);
-            return 1;
-          }
-          if (location.hash.slice(1) !== hash) {
-            location.hash = hash;
-            return;
-          }
-        }
-        window.dispatchEvent(new HashChangeEvent("hashchange"));
-      },
-      goto = (url) => {
-        if (setUrl(url)) refresh(url);
-      };
+export const nowUrl = () => location.pathname.slice(1),
+  route = (hook) => {
+    hooks.push(hook);
+    hook(nowUrl());
+    return () => {
+      hooks = hooks.filter((f) => f !== hook);
+    };
+  },
+  setPre = (url) => {
+    pre = url;
+  },
+  preUrl = () => pre,
+  refresh = (url) => {
+    url = url || nowUrl();
+    for (const f of hooks) f(url, pre);
+    setPre(url);
+  },
+  removeSlash = (url) => (url[0] === "/" ? url.slice(1) : url),
+  split = (str, s) => {
+    const p = str.indexOf(s);
+    return p >= 0 ? [str.slice(0, p), str.slice(p + 1)] : [str, ""];
+  },
+  setUrl = (url) => {
+    url = removeSlash(url);
+    if (url !== pre) {
+      const [path, hash] = split(url, HASH),
+        [p] = split(pre, HASH);
+      setPre(url);
+      if (path !== p) {
+        history.pushState(null, "", "/" + url);
+        return 1;
+      }
+      if (location.hash.slice(1) !== hash) {
+        location.hash = hash;
+        return;
+      }
+    }
+    window.dispatchEvent(new HashChangeEvent("hashchange"));
+  },
+  goto = (url) => {
+    if (setUrl(url)) refresh(url);
+  };
 
-    On(window, {
-      popstate: () => {
-        const url = nowUrl();
-        if (url !== split(PRE, HASH)[0]) refresh(url);
-      },
-    });
+pre = nowUrl();
+if (location.hash) pre += location.hash;
 
-    return [route, setPre, preUrl, refresh, removeSlash, split, setUrl, goto];
-  })();
+On(window, {
+  popstate: () => {
+    const url = nowUrl();
+    if (url !== split(pre, HASH)[0]) refresh(url);
+  },
+});

package/x/route.md

@@ -1,37 +1,72 @@
-# 路由管理与跳转
+# 前端路由管理与历史记录同步
 
-- `nowUrl()`
-  - 返回值：当前 URL 路径（不含首部斜杠）。
+## `nowUrl()` : 获取当前页面的路径名，并去除首部的斜杠字符
 
-- `route(hook)`
-  - `hook`: 路由变化时执行的回调函数。格式：
-    - 参数：
-      - `url`: 字符串，新 URL 路径。
-      - `preUrl`: 字符串（可选），旧 URL 路径。
-    - 返回值：无。
-  - 返回值：取消订阅的函数，格式为 `() => void`。
+### 返回值
 
-- `setPre(url)`
-  - `url`: 字符串，新的前一次 URL 路径。
+当前不含首部斜杠的路径名字符串
 
-- `preUrl()`
-  - 返回值：前一次的 URL 路径。
+## `route` : 注册路由变化监听钩子函数，并立即以当前路径名执行一次该钩子
 
-- `refresh(url)`
-  - `url`: 字符串（可选），要触发回调的 URL 路径，默认是当前 URL。
+### 参数
 
-- `removeSlash(url)`
-  - `url`: 字符串。
-  - 返回值：移除首部斜杠后的字符串。
+- hook : 监听路由变化的回调函数。接收参数：当前 URL 字符串 (string) 和前一个 URL 字符串或 undefined (string|undefined)；无返回值。
 
-- `split(str, s)`
-  - `str`: 待拆分字符串。
-  - `s`: 分隔符。
-  - 返回值：包含两个元素的数组 `[前部, 后部]`。
+### 返回值
 
-- `setUrl(url)`
-  - `url`: 目标 URL 路径。
-  - 返回值：若路径改变返回 `1`，若仅 hash 改变不返回值。
+注销该监听函数的函数
 
-- `goto(url)`
-  - `url`: 目标 URL 路径。
+## `setPre` : 手动更新记录的前一个 URL 状态值
+
+### 参数
+
+- url : 需要设置的前一个 URL 字符串
+
+## `preUrl()` : 获取记录的前一个 URL 状态值
+
+### 返回值
+
+前一个 URL 状态值字符串
+
+## `refresh` : 强制触发所有已注册 of 路由监听钩子函数，并更新前一个 URL 记录
+
+### 参数
+
+- url : 触发钩子使用的目标 URL 字符串，默认为当前 URL 路径名
+
+## `removeSlash` : 若 URL 字符串首位为斜杠则予以移除
+
+### 参数
+
+- url : 待处理的 URL 字符串
+
+### 返回值
+
+处理后不以斜杠开头的 URL 字符串
+
+## `split` : 根据指定分隔符将字符串拆分为两部分
+
+### 参数
+
+- str : 待拆分的原始字符串
+- s : 分隔符字符串
+
+### 返回值
+
+包含拆分后两部分字符串的数组。若未找到分隔符，则第二项为空字符串。
+
+## `setUrl` : 静默更新当前 URL、历史状态及 Hash，而不触发路由监听钩子回调
+
+### 参数
+
+- url : 目标 URL 字符串
+
+### 返回值
+
+若路径部分发生改变且已推入历史记录则返回数字 1
+
+## `goto` : 跳转至目标 URL，同步更新历史记录并在路径改变时触发所有路由监听钩子回调
+
+### 参数
+
+- url : 目标 URL 字符串

package/x/{delayRoute.js → routeDelay.js}

@@ -1,7 +1,7 @@
-import { route } from "./route.js";
+import { route } from "x/route.js";
 
 // 避免 onMount 之前，route 被触发，导致重复加载数据
-export const delayRoute = (loadUrl) => {
+export const routeDelay = (loadUrl) => {
   let t;
   const unbind = route((url, preUrl) => {
     t = setTimeout(() => {
@@ -13,5 +13,3 @@ export const delayRoute = (loadUrl) => {
     clearTimeout(t);
   };
 };
-
-export default delayRoute;

package/x/routeDelay.md

@@ -0,0 +1,11 @@
+# 延迟触发路由数据加载
+
+## `routeDelay` : 延迟绑定路由变化回调，避免组件挂载前重复加载数据
+
+### 参数
+
+- loadUrl : 路由变化时的回调函数。接收当前URL字符串（url）和前一个URL字符串（preUrl）作为参数，无返回值。
+
+### 返回值
+
+解绑函数，调用后注销路由监听并清除延迟定时器。

package/x/selfA.md

@@ -1,6 +1,12 @@
-# 同站链接点击校验与处理
+# 校验并处理同站 A 标签点击
 
-- `selfA(p, e)`
-  - `p`: `<a>` 元素。
-  - `e`: 点击事件对象。
-  - 返回值：若是同站链接，阻止默认行为并返回包含 search/hash 的相对路径，否则返回 `undefined`。
+## `selfA` : 判断 A 标签 href 是否为当前站点，若是则阻止默认点击事件并返回相对 URL 路径
+
+### 参数
+
+- p : HTMLAnchorElement 元素对象
+- e : MouseEvent 点击事件对象
+
+### 返回值
+
+同站链接的相对 URL 路径，若非同站则返回 undefined

package/x/delayRoute.md

@@ -1,11 +0,0 @@
-# 延迟路由触发避免重复加载数据
-
-用于 Svelte，避免组件被卸载前触发路由导致重复加载数据。
-
-- `delayRoute(loadUrl)`
-  - `loadUrl`: 路由变化时的回调函数。格式：
-    - 参数：
-      - `url`: 字符串，新 URL 路径。
-      - `preUrl`: 字符串（可选），旧 URL 路径。
-    - 返回值：无。
-  - 返回值：取消路由订阅并清除定时器的函数，格式为 `() => void`。