18s 0.2.9 → 0.2.16

package/README.md

@@ -3,9 +3,11 @@
 ---
 
 <a id="en"></a>
-# 18s : High-performance subsetted font packages for the WebC component library
+# 18s : Chinese font subsetting packages for the WebC component library
 
-Online Preview: [https://webc-zh.github.io](https://webc-zh.github.io)
+WebC is a Web Components library designed for AI-assisted development. This package provides Chinese font subsetting support for WebC.
+
+Online Preview: [https://webc-zh.pages.dev](https://webc-zh.pages.dev)
 
 * [Features](#features)
 * [Directory Structure](#directory-structure)
@@ -16,10 +18,10 @@ Online Preview: [https://webc-zh.github.io](https://webc-zh.github.io)
 
 ## Features
 
-- **Dynamic Subsetting**: Splits large CJK fonts into small WOFF2 chunks (typically 128KB) to minimize browser loading times.
-- **Cache Busting**: Uses MD5 hashes of chunk content as filenames to prevent cache collision and maximize caching efficiency.
-- **Font Varieties**: Includes variable font versions of Source Han Sans SC (`t`) and JetBrains Mono (`c`).
-- **Clean CSS**: Output minimized CSS containing subsetted `@font-face` rules mapping local character ranges to the respective chunks.
+- **Chinese Font Subsetting**: Splits Chinese fonts (CJK) into WOFF2 chunks (128KB) to reduce loading times.
+- **Cache Busting**: Uses MD5 hashes of chunk content as filenames to prevent collision and improve caching.
+- **Variable Fonts**: Includes Source Han Sans SC (`t`) and JetBrains Mono (`c`).
+- **CSS**: Outputs minimized CSS containing `@font-face` rules mapping character ranges to chunks.
 
 ## Directory Structure
 
@@ -44,21 +46,21 @@ Online Preview: [https://webc-zh.github.io](https://webc-zh.github.io)
 
 ## Design & Process
 
-The compiler processes fonts defined in `gen/ttf/gen.yml`, splitting them and preparing production-ready CSS and font chunks.
+The compiler processes fonts defined in `gen/ttf/gen.yml`, splitting them and preparing CSS and font chunks.
 
 ```mermaid
 graph TD
-    A[Font TTF Source files: SourceHanSansSC / JetBrainsMono] --> B[fontSplit / cn-font-split]
-    B --> C[Generate WOFF2 character subsets & result.css]
-    C --> D[Rename WOFF2 subsets to unique MD5 Base64url hashes]
-    D --> E[Rewrite result.css font-family & subset URLs]
-    E --> F[Output optimized woff2/t.css, woff2/c.css & woff2/_.css]
+    A[Font files: SourceHanSansSC / JetBrainsMono] --> B[fontSplit / cn-font-split]
+    B --> C[Generate WOFF2 subsets & result.css]
+    C --> D[Rename WOFF2 subsets to MD5 Base64url hashes]
+    D --> E[Rewrite CSS font-family & URLs]
+    E --> F[Output woff2/t.css, woff2/c.css & woff2/_.css]
 ```
 
 1. **Splitting**: Fonts are subsetted using `cn-font-split` into WOFF2 chunks.
-2. **Hashing**: Each chunk filename is renamed to its MD5 base64url hash prefix (starting at length 4, resolving conflicts by expanding length).
-3. **Rewriting**: The generated CSS file is parsed to replace original font-family names with short aliases (`t` and `c`), omit local search paths, and update chunk URLs.
-4. **Publishing**: Minimized CSS (both individual files and the merged `_.css`) and hashed WOFF2 chunks are output to `woff2/` for direct npm publication.
+2. **Hashing**: Each chunk is renamed to its MD5 base64url hash (starting at length 4, expanding on conflict).
+3. **Rewriting**: CSS is parsed to replace font-family names with aliases (`t` and `c`), omit local paths, and update chunk URLs.
+4. **Publishing**: CSS and WOFF2 chunks are output to `woff2/` for npm publication.
 
 ## Tech Stack
 
@@ -105,18 +107,20 @@ code {
 
 ## History & Background
 
-CJK (Chinese, Japanese, Korean) font files are traditionally large (often 10MB to 50MB) because they contain tens of thousands of glyphs. Directly loading them in browsers causes severe rendering latency. Historically, developers embedded static, hand-selected character subsets or relied on system defaults, limiting design options.
+CJK font files are large (10MB to 50MB) as they contain tens of thousands of glyphs. Loading them in browsers causes rendering latency. Previously, developers embedded static character subsets or relied on system defaults, limiting design options.
 
-Source Han Sans, introduced jointly by Adobe and Google in 2014, solved the CJK typeface quality problem but still suffered from file size issues. The advent of modern dynamic subsetting, exemplified by tools like `cn-font-split`, split these typefaces into hundreds of micro-chunks based on character frequency. Browsers only fetch chunks containing characters actually present on the page, unlocking high-fidelity, performant CJK web typography.
+Source Han Sans, introduced by Adobe and Google in 2014, solved CJK typeface quality issues but still had large file sizes. Font splitters like `cn-font-split` split these typefaces into chunks based on character frequency. Browsers fetch chunks containing characters present on the page, improving performance.
 
-JetBrains Mono, released in 2020, focuses on readability for developers. Project `18s` bundles these optimized typefaces as variable fonts, ensuring lightweight integration for the WebC component library.
+JetBrains Mono, released in 2020, is designed for readability. Project `18s` bundles these typefaces as variable fonts to provide Chinese font support for WebC.
 
 ---
 
 <a id="zh"></a>
-# 18s : 面向 WebC 组件库的高性能分片字体包
+# 18s : WebC 组件库中文字体分片包
+
+WebC 是面向 AI 辅助开发的 Web Components 组件库。本包为 WebC 提供中文字体分片支持。
 
-组件库在线浏览地址：[https://webc-zh.github.io](https://webc-zh.github.io)
+组件库在线浏览地址：[https://webc-zh.pages.dev](https://webc-zh.pages.dev)
 
 * [功能特性](#功能特性)
 * [目录结构](#目录结构)
@@ -127,10 +131,10 @@ JetBrains Mono, released in 2020, focuses on readability for developers. Project
 
 ## 功能特性
 
-- **动态分片**：将庞大 CJK 字体切分为微小 WOFF2 分片（默认 128KB），大幅降低首屏字体加载时延。
+- **中文字体分片**：将中文字体（CJK）切分为 WOFF2 分片（默认 128KB），降低加载时延。
 - **防止冲突**：基于分片内容生成 MD5 哈希作为文件名，解决缓存冲突并提升缓存命中率。
 - **可变字重**：提供思源黑体（`t`）与 JetBrains Mono（`c`）可变字重版本。
-- **轻量 CSS**：输出压缩后的 CSS 代码，内置 `@font-face` 规则，精确映射字符区间至对应字体分片。
+- **CSS**：输出压缩的 CSS 代码，内置 `@font-face` 规则，映射字符区间至对应字体分片。
 
 ## 目录结构
 
@@ -159,17 +163,17 @@ JetBrains Mono, released in 2020, focuses on readability for developers. Project
 
 ```mermaid
 graph TD
-    A[字体 TTF 源文件: SourceHanSansSC / JetBrainsMono] --> B[fontSplit / cn-font-split]
-    B --> C[生成 WOFF2 字符分片与 result.css]
-    C --> D[将 WOFF2 分片重命名为唯一 MD5 Base64url 哈希]
+    A[Font files: SourceHanSansSC / JetBrainsMono] --> B[fontSplit / cn-font-split]
+    B --> C[生成 WOFF2 分片与 result.css]
+    C --> D[将 WOFF2 分片重命名为 MD5 Base64url 哈希]
     D --> E[重写 CSS 字体族名称与分片路径]
-    E --> F[输出压缩后的 woff2/t.css、woff2/c.css 与 woff2/_.css]
+    E --> F[输出 woff2/t.css、woff2/c.css 与 woff2/_.css]
 ```
 
-1. **分片处理**：调用 `cn-font-split` 工具，将原始字体切分为 WOFF2 格式片段。
-2. **哈希映射**：计算各分片内容的 MD5 base64url 哈希值，以此作为文件名（初始长度 4，遇冲突时递增长度），实现内容寻址。
-3. **样式重写**：解析 CSS，将默认 font-family 替换为简短别名（`t` 或 `c`），移除本地路径（`local`）查询，更新字体分片 URL 引用。
-4. **资源输出**：将 CSS（包含各字体独立文件以及合并后的 `_.css`）及字体分片写入发布目录 `woff2/`，以便独立进行 npm 发布。
+1. **分片处理**：调用 `cn-font-split` 工具，将字体切分为 WOFF2 片段。
+2. **哈希映射**：计算分片内容的 MD5 base64url 哈希作为文件名（长度从 4 开始，遇冲突时递增），实现内容寻址。
+3. **样式重写**：解析 CSS，将 font-family 替换为别名（`t` 或 `c`），移除本地路径（`local`）查询，更新字体分片 URL 引用。
+4. **资源输出**：将 CSS 及字体分片写入发布目录 `woff2/`，进行 npm 发布。
 
 ## 技术堆栈
 
@@ -216,8 +220,8 @@ code {
 
 ## 历史背景
 
-汉字、日文和韩文（CJK）字体由于字符繁多，文件大小通常在 10MB 至 50MB 之间。直接在网页中加载此类字体会导致严重的白屏或字体闪烁问题。早期 Web 开发多采用系统默认字体，或通过繁琐的静态抽字工具仅保留特定字词，限制了动态内容的展示。
+CJK 字体由于文件大（10MB 至 50MB），直接加载会导致白屏或字体闪烁。以往开发多采用系统默认字体，或通过静态抽字工具仅保留部分字词，限制了动态内容展示。
 
-2014 年，Adobe 与 Google 联合推出开源 CJK 字体思源黑体（Source Han Sans），解决了多语种排版设计问题，但体积瓶颈依旧存在。随着动态分片技术（如 `cn-font-split`）出现，字体文件能按字符使用频率和字符集关联动态切分为数百个微小分片。浏览器仅按需下载当前页面渲染所需的字型分片，极大地优化了中文字体在 Web 端的加载体验。
+2014 年，Adobe 与 Google 推出 CJK 字体思源黑体（Source Han Sans），但体积问题依旧存在。随着分片技术（如 `cn-font-split`）出现，字体文件能按字符使用频率切分为数百个分片。浏览器按需下载分片，优化了中文字体加载体验。
 
-JetBrains Mono 是 JetBrains 于 2020 年发布的专为代码阅读设计的开源编程字体。本项目 `18s` 将思源黑体与 JetBrains Mono 作为可变字体整合分片，旨在为 WebC 组件库提供轻量、美观、一致的视觉呈现。
+JetBrains Mono 是 2020 年发布的编程字体。`18s` 将思源黑体与 JetBrains Mono 作为可变字体整合分片，为 WebC 提供中文字体支持。