docs: ARCHITECTURE.md — 聚珍（Juzhen）架構契約
從零重寫之實作契約，先於程式碼。涵蓋： - 設計不變量 I1–I10（複製乾淨、JS/CSS 分離、依 lang、跨瀏覽器一致並顯式禁用 不一致原語、justify 單份間距、冪等可還原、邊界感知、v1 向下相容、遍歷聚合、 作用域與分塊）。 - createJuzhen API；3 階段聚合管線（collect/apply，把 ~9 次走訪壓到 3 次）。 - 核心基座 finder/unicode/locale/dom；jz-* 元素詞彙。 - 對照 Han.css 逐功能點實作方案（間隙/長詞/擠壓/禁則/懸掛/標點修正/著重號/注音）。 - 切片 1＝v1 對等之映射；§3.5 v1 相容層；§3.6 作用域與分塊功能選擇。 - §8 justify 句末單份間距解法；§9.1 顯式禁用層；§14 風險＋預案。
This commit is contained in:
+566
@@ -0,0 +1,566 @@
|
||||
# 聚珍（Juzhen）架構文檔
|
||||
|
||||
> 現代簡／繁中文網頁排版套件。Han.css 之現代化重寫，沿其功能版圖，並針對
|
||||
> 我們關注的數種情況（複製乾淨、依 `lang` 全角／開明切換、justify 句末標點
|
||||
> 單份間距、跨瀏覽器一致）作調整。
|
||||
>
|
||||
> 倉庫名 `cjk-autospace` 不變；公開 API 為 `createJuzhen` / 全域 `Juzhen`；
|
||||
> 自訂元素前綴 `jz-`。本文件先於任何程式碼，作為實作契約——後續每個功能點
|
||||
> 皆按此落地，以避免不一致與重大返工。
|
||||
|
||||
---
|
||||
|
||||
## 1. 目標與範圍
|
||||
|
||||
1. **第一垂直切片 = v1（cjk-autospace）全部功能**，在新引擎上重寫：中西間隙
|
||||
（Pass A／B）、長英文詞斷詞包裝（Pass C）、開明式標點擠壓（Pass D）。
|
||||
2. **架構須預留完整復刻 Han.css 的能力**：標點修正、擠壓、懸掛、禁則、著重號、
|
||||
注音／ruby、樣式正常化、字體偵測、計數器等，皆能在不改動切片 1 既有程式碼
|
||||
的前提下，以「新增一個 pass」的方式加入。
|
||||
3. **跨瀏覽器一致**（Chrome／Edge／Safari／WebKit／Firefox）：一致性關鍵的版面
|
||||
行為，只用普遍支援的 CSS 原語；原生新特性僅作非必要增強。
|
||||
|
||||
非目標：不依賴 Han.css／Heti 等既有庫之執行期程式碼（MIT 條款下可借鑑其思路與
|
||||
分類表，但成品自含）。
|
||||
|
||||
---
|
||||
|
||||
## 2. 設計不變量（所有 pass 必須遵守）
|
||||
|
||||
這些不變量是「避免返工」的核心。任何新功能點都不得違反。
|
||||
|
||||
- **I1 複製乾淨（copy-clean）**：注入之間隙與標記一律 `user-select: none`，且不
|
||||
改變邏輯 `textContent` 的語義；若某 pass 必須改寫文字（如標點替換），則須為
|
||||
顯式 opt-in 且可 `revert` 還原。預設「只包裝、不改寫文字」。
|
||||
- **I2 JS／CSS 職責分離**：JS 只注入**結構**（`jz-*` 元素、class、`data-jz-*`
|
||||
屬性）；**所有視覺尺寸（margin／letter-spacing／寬度／懸掛位移）一律寫在
|
||||
`juzhen.css`**。同一段 DOM 在 justify 與否、主題與否下都成立。此分離是擴充性
|
||||
與跨瀏覽器調校的關鍵。
|
||||
- **I3 依 `lang` 行為**：每個 pass 解析節點的有效 `lang`（最近祖先），行為與
|
||||
CSS 皆以 `:lang()` 與 locale 政策驅動。全角式／開明式之別即由此決定。
|
||||
- **I4 跨瀏覽器一致**：間隙、擠壓等一致性關鍵層只用 `margin`／`letter-spacing`／
|
||||
`inline-block`／`user-select` 等普遍原語。`text-spacing-trim`／
|
||||
`hanging-punctuation`／`text-emphasis` 等僅作漸進增強，絕不作為唯一機制。**且當
|
||||
某原生原語在各引擎支援不一致、會與我們託管之版面衝突或重複作用時，須在
|
||||
`.juzhen` 範圍內以 `@supports` 顯式禁用之**（如關閉 Blink 的 `text-spacing-trim`／
|
||||
`text-autospace`），使三引擎行為收斂於同一路徑（見 §9.1）。
|
||||
- **I5 justify 單份間距**：間隙與擠壓的結構設計，須保證每個標點在
|
||||
`text-align: justify` 下只貢獻**一份**對齊伸縮量（見 §8）。
|
||||
- **I6 冪等與可還原**：每個 pass 對其產物打標記，重跑跳過；提供 `revert` 乾淨
|
||||
移除，DOM 回到 pass 前狀態（至少邏輯等價）。
|
||||
- **I7 邊界感知**：跨樣式行內元素的鄰接（如 `<strong>是</strong>A`）須能識別並
|
||||
正確處理——由核心 finder 統一提供，各 pass 不自行重複造輪。
|
||||
- **I8 向下相容 v1**：既有 `createCjkAutospace(options).apply(root)` 消費端
|
||||
（build.sh 單檔串接、Nvim peek、Claude 模板）**不得 break、無功能倒退**。行為
|
||||
**不要求與 v1 完全一致**，但須等價可用；以相容層達成（見 §3.5）。
|
||||
- **I9 遍歷聚合**：邏輯上「一功能一 pass」，但執行上**相容之 pass 共享單次遍歷**
|
||||
（見 §3.4），以減少全樹走訪次數；聚合不得犧牲 I6（冪等可還原）與逐功能開關。
|
||||
- **I10 作用域與分塊**：作用範圍可由 `scope.include` 選擇器限定（opt-in）；功能集
|
||||
可逐塊覆寫（屬性或 `blocks` 映射），由 pass 在 `collect` 內以 per-node 閘解析
|
||||
（見 §3.6）。CSS 視覺規則須與 JS 作用域同域收斂，不外溢。
|
||||
|
||||
---
|
||||
|
||||
## 3. 整體架構
|
||||
|
||||
### 3.1 對外 API
|
||||
|
||||
```
|
||||
const jz = createJuzhen(options);
|
||||
jz.render(root?); // 對 root（預設 document.body）套用啟用之 pass
|
||||
jz.revert(root?); // 還原
|
||||
// 全域： window.Juzhen.createJuzhen(...)
|
||||
```
|
||||
|
||||
`options` 形如：
|
||||
|
||||
```
|
||||
{
|
||||
// 全域
|
||||
lang: { default: "zh-Hant", policy: { "zh-Hant": "quanjiao", "zh-Hans": "kaiming" } },
|
||||
classPrefix: "jz",
|
||||
|
||||
// 作用域限定（§3.6）
|
||||
scope: {
|
||||
root: document.body, // 預設處理根；render(root) 可逐次覆寫
|
||||
include: null, // 啟用選擇器；設則僅處理命中子樹（opt-in）
|
||||
// 如 ".juzhen, [data-juzhen]"
|
||||
avoid: "code, kbd, pre, samp, textarea, [contenteditable]", // 追加於內建 avoid
|
||||
},
|
||||
|
||||
// 全域逐功能開關（true/false 或細部物件），預設見各 pass
|
||||
spacing: true, // 中西間隙
|
||||
longWord: { minLength: 6, lang: "en" },
|
||||
jiya: true, // 標點擠壓
|
||||
jinze: true, // 禁則（含 justify 綁定）
|
||||
hanging: false, // 標點懸掛（預設關，繁體橫排不宜）
|
||||
biaodian: false, // 標點修正（opt-in，可能改寫文字）
|
||||
emphasis: false,
|
||||
ruby: false,
|
||||
|
||||
// 分塊功能選擇（§3.6）：選擇器 → 該塊內生效之功能集（覆寫全域）
|
||||
blocks: [
|
||||
{ selector: ".prose", features: ["spacing", "jiya", "jinze", "emphasis"] },
|
||||
{ selector: ".code-comment", features: ["spacing"] }, // 此塊只間隙、不擠壓
|
||||
],
|
||||
}
|
||||
```
|
||||
|
||||
### 3.2 Pass 管線
|
||||
|
||||
每個功能點是一個 `Pass`：
|
||||
|
||||
```
|
||||
interface Pass {
|
||||
name: string;
|
||||
phase: "P0" | "P1" | "P2"; // 遍歷階段，供聚合（§3.4）
|
||||
order: number; // phase 內 apply 先後（charify→擠壓→間隙→…）
|
||||
enabled(options): boolean;
|
||||
// 聚合模式：collect 純判定（同階段共享單次走訪），apply 批次變更
|
||||
collect(node: Text, ctx: RenderContext): Target[];
|
||||
apply(targets: Target[], ctx: RenderContext): void;
|
||||
revert(ctx: RenderContext): void;
|
||||
}
|
||||
```
|
||||
|
||||
需獨立走訪／layout 之 pass（如 hanging）可改採 `render(ctx)` 整段式而不參與
|
||||
collect 聚合；執行器兩種皆容納。
|
||||
|
||||
`createJuzhen` 內建一個**有序、可開關**的 pass 註冊表。`render` 依 `order` 執行
|
||||
已啟用者。順序契約（避免互相破壞）：
|
||||
|
||||
```
|
||||
10 biaodian 標點修正（若開，最先；可能改寫文字／包裝）
|
||||
20 charify 標點字元包裝（jz-char/jz-inner）——擠壓、禁則、著重號之共同前置
|
||||
30 jiya 標點擠壓（依 class + :lang 之 CSS）
|
||||
40 jinze 禁則 + justify 綁定
|
||||
50 spacing 中西間隙（jz-hws）
|
||||
60 longWord 長英文詞 lang 包裝
|
||||
70 emphasis 著重號
|
||||
80 ruby 注音／ruby
|
||||
90 hanging 標點懸掛（需 layout，最後；掛 ResizeObserver）
|
||||
```
|
||||
|
||||
> 順序理由：charify 先把標點變成可定址的 `jz-char`，擠壓／禁則／著重號才有對象；
|
||||
> 間隙在標點結構穩定後插入；懸掛依賴最終行盒，必須最後且 layout 後再算。
|
||||
|
||||
### 3.3 RenderContext
|
||||
|
||||
`render`／`revert` 收到統一上下文：`{ root, options, finder, locale }`。各 pass
|
||||
共用同一 `finder` 實例與 locale 解析，確保 avoid 名單、邊界規則、語言判定一致。
|
||||
|
||||
### 3.4 遍歷聚合（減少 pass 遍歷次數，I9）
|
||||
|
||||
樸素做法是每個 pass 各跑一次 `TreeWalker`，9 個 pass 即 9 次全樹走訪。為此引入
|
||||
**遍歷階段（phase）**：相容之 pass 共享單次走訪。Pass 介面拆為
|
||||
`collect(node, ctx) → targets[]`（純判定、不變更 DOM）與 `apply(targets, ctx)`
|
||||
（批次變更），執行器：
|
||||
|
||||
```
|
||||
for phase in phases:
|
||||
walk(root) 一次：對每個文本節點，依序呼叫該 phase 內各 pass 的 collect()
|
||||
依 order 對收集到的 targets 做 apply()（兩階段：先收集後變更，避免遍歷中改 DOM）
|
||||
```
|
||||
|
||||
階段劃分（把 ~9 次走訪壓到 3 次）：
|
||||
|
||||
| phase | 內含 pass | 走訪 | 備註 |
|
||||
|---|---|---|---|
|
||||
| P0 文字修正 | biaodian（opt-in） | 1 次 | 唯一可能改寫文字者，須最先 |
|
||||
| P1 行內結構 | charify／jiya 標記／jinze／spacing／longWord／emphasis | 1 次 | 共享走訪，`apply` 依 order |
|
||||
| P2 版面後處理 | hanging | 0 次走訪＋layout | 需最終行盒，掛 ResizeObserver |
|
||||
|
||||
> 聚合僅是**執行優化**：邏輯上仍「一功能一 pass」、可獨立開關與 `revert`（I6）；
|
||||
> 只是 P1 諸 pass 的 `collect` 在同一走訪內完成。若某 pass 不相容（需獨立走訪），
|
||||
> 退化為自跑一次，不影響正確性。
|
||||
|
||||
### 3.5 v1 向下相容層（I8，`src/compat/v1.ts`）
|
||||
|
||||
導出 `createCjkAutospace(options)`，把 v1 API 映射到 `createJuzhen`，**保證不
|
||||
break、無功能倒退**，行為等價但不要求完全一致：
|
||||
|
||||
| v1 選項／行為 | 映射 |
|
||||
|---|---|
|
||||
| `.apply(root)` | → `.render(root)` |
|
||||
| `pillSelector` | → pill 鄰接處理 + avoid |
|
||||
| `styleInlines`／`blockTags`／`skipTags` | → finder 設定 |
|
||||
| `autospaceClass`（預設 `cjk-autospace`） | → 套用於 `jz-hws` 之 class，使既有
|
||||
`.cjk-autospace{…}` CSS 仍命中間隙元素 |
|
||||
| `skipAttribute`／`isSkipped` | → avoid 判定 |
|
||||
| `longWordWrap` | → `longWord` |
|
||||
| `punctuationSqueeze`（v1 halt 句內半角） | → `jiya`（margin 開明／全角；行為近似，
|
||||
非逐位等同——符合「不要求完全一致」） |
|
||||
|
||||
IIFE 構建額外掛 `globalThis.createCjkAutospace` 別名，使
|
||||
`globalThis.createCjkAutospace` 之消費端（Nvim peek／模板）零改動可跑。相容層之
|
||||
差異（間隙元素由 `span.cjk-autospace` 變為 `jz-hws[class]`、擠壓由 halt 變 margin）
|
||||
於 README 明列。
|
||||
|
||||
### 3.6 作用域與分塊功能選擇（I10）
|
||||
|
||||
**作用域限定**——控制「在頁面何處生效」，避免污染無關內容：
|
||||
|
||||
- `scope.root`：處理根（節點或選擇器），預設 `document.body`；`render(root)` 可逐次
|
||||
覆寫；允許多實例／多根並存。
|
||||
- `scope.include`：**啟用選擇器**（opt-in 模式）。設定後，**僅處理命中該選擇器之
|
||||
子樹**（如 `".juzhen, [data-juzhen]"`），其餘一概不動——此即「限定作用範圍」。
|
||||
- `scope.avoid`：排除選擇器，與內建 avoid 合併。
|
||||
- **CSS 同域**：`juzhen.css` 之視覺規則一律收斂於同一啟用選擇器（如 `.juzhen` 下），
|
||||
與 JS 作用域一致，杜絕樣式外溢（呼應 I2、§9.1 之禁用層亦限於此域）。
|
||||
|
||||
**分塊功能選擇**——不同塊啟用不同功能集：
|
||||
|
||||
- **宣告式（屬性，就近繼承）**：
|
||||
- `data-juzhen="spacing jiya"`——白名單：此塊內僅啟用列出之功能。
|
||||
- `data-juzhen-off="jiya hanging"`——黑名單：此塊停用列出者，其餘繼承。
|
||||
- `lang`——驅動全角／開明（正交於功能開關）。
|
||||
- **程式式**：`options.blocks: [{ selector, features }]`，選擇器 → 功能集。
|
||||
- **解析（per-node 閘）**：對每個節點，向上找最近帶功能指令之祖先（屬性或命中
|
||||
`blocks` 選擇器者）決定其**有效功能集**，無則用全域 `options`；render 期間以
|
||||
元素為鍵快取。每個 pass 之 `collect(node)` 先問 `featureEnabledFor(node, name)`，
|
||||
否則跳過——**故分塊閘只是單次走訪內的 per-node 判定，不增遍歷、不破壞聚合
|
||||
（§3.4）**。
|
||||
- **與 revert 之關係**：`revert` 依標記移除某功能產物，**不受當前閘狀態影響**，故
|
||||
「關閉某功能 + revert」恆能乾淨還原（I6）。
|
||||
|
||||
---
|
||||
|
||||
## 4. 核心基座（`src/core/`）
|
||||
|
||||
### 4.1 `finder.ts`——文本遍歷引擎（取代 Fibre.js）
|
||||
|
||||
職責（所有 pass 的共同地基）：
|
||||
|
||||
- **遍歷**：`TreeWalker(SHOW_TEXT)` 走 `root` 下文本節點。
|
||||
- **avoid**：跳過 avoid 名單之子樹（內建：`code/kbd/pre/samp/textarea/script/
|
||||
style/SVG/[contenteditable]/[data-jz-skip]`，可由 `scope.avoid` 追加）。
|
||||
- **scope.include**：若設啟用選擇器，僅走訪命中之子樹（opt-in，§3.6）。
|
||||
- **featureEnabledFor(node, name)**：解析該節點之有效功能集（§3.6），供各 pass 之
|
||||
`collect` per-node 閘用；結果以元素為鍵快取。
|
||||
- **charify**：把符合條件之字元／字串包進指定 `jz-*` 元素（兩階段：先收集目標、
|
||||
後變更，避免遍歷中改 DOM 失效）。
|
||||
- **邊界感知 replace（I7）**：對「跨相鄰文本節點、可跨樣式行內元素」的邏輯字串
|
||||
做正則 find，回呼決定如何包裝／插入標記。樣式行內元素（`strong/em/a/span/…`）
|
||||
透明穿越；block／pill／avoid 中斷邏輯串。此即 v1 Pass A「剝離樣式收集邏輯文本
|
||||
再反映射」之一般化，提升為可重用引擎。
|
||||
|
||||
設計要點：finder 不知道任何具體排版規則；它只提供「在何處、跨何種邊界、對哪些
|
||||
字元」的遍歷與安全變更原語。規則由各 pass 以 unicode 表 + 回呼注入。
|
||||
|
||||
### 4.2 `unicode.ts`——字元分類與規則表
|
||||
|
||||
集中所有 Unicode 範圍與標點子類，供各 pass 共用，杜絕分類散落不一致：
|
||||
|
||||
- **CJK**：表意文字、假名、注音符號等範圍（沿用並擴充 v1 之 `PANGU_CJK`）。
|
||||
- **西文**：拉丁字母、數字、常見符號（v1 之 `AN_CHARS` 等）。
|
||||
- **標點（biaodian）子類**（對應 CSS class）：
|
||||
- `bd-open` 開始括號／引號：`「『（《〈【〖〔［｛` 等
|
||||
- `bd-close` 結束括號／引號：`」』）》〉】〗〕］｝` 等
|
||||
- `bd-cop` 句逗號（comma／period，字面偏移因簡繁而異）：`，。．`
|
||||
- `bd-stop` 句末其餘：`！？；：⁇‼` 等
|
||||
- `bd-sep` 分隔／間隔號：`·・‧`
|
||||
- `bd-liga` 連續省略／破折：`…—` 等
|
||||
- `quote` 彎引號：`“”‘’`
|
||||
- **規則正則**：中西間隙邊界、擠壓相鄰組合、禁則對象等，皆以此表組裝。
|
||||
|
||||
> 借鑑 Han 之 `regex/typeset.js`、`regex/unicode.js` 與 Heti 之分類字集，重寫為
|
||||
> 現代 TS 常數表。
|
||||
|
||||
### 4.3 `locale.ts`——語言與全角／開明政策
|
||||
|
||||
- `effectiveLang(node)`：最近祖先 `lang`（小寫），無則回退 `options.lang.default`。
|
||||
- `classify(lang)`：歸為 `zh-Hans` / `zh-Hant`（含 `zh-TW`/`zh-HK`）/ `ja` / 其他；
|
||||
BCP-47 前綴邊界比對（`zh` 命中 `zh-Hant`，不命中 `zhx`）。
|
||||
- `style(lang)`：回傳該語言之標點寬度政策——`quanjiao`（全角式）｜`kaiming`
|
||||
（開明式）｜`banjiao`（半角式）。預設：`zh-Hant`/`zh-HK` → 全角式；`zh-Hans`
|
||||
→ 開明式；可由 `options.lang.policy` 覆寫（即你要的「依 lang 自由選擇」）。
|
||||
|
||||
CSS 端對應以 `:lang()` 選擇器落實同一政策（I2／I3）。
|
||||
|
||||
### 4.4 `dom.ts`——`jz-*` 元素工廠與還原
|
||||
|
||||
`createEl('jz-char', {class, attrs})`、`wrap(node, el)`、`splitAt`、`insertMarker`、
|
||||
冪等標記（`data-jz="<pass>"`）、`revertPass(name, root)`（移除該 pass 之產物、
|
||||
解包 `jz-*`、合併回文本節點並 `normalize()`）。
|
||||
|
||||
---
|
||||
|
||||
## 5. 渲染元素詞彙（`jz-*`）
|
||||
|
||||
自訂元素皆含連字號（合法 custom element 名），預設 `display: inline`（未知元素
|
||||
天然 inline），語義中性，可被 `revert` 移除：
|
||||
|
||||
| 元素 | 用途 |
|
||||
|---|---|
|
||||
| `jz-hws` | 中西間隙。`user-select:none`，copy-clean，justify 安全（§8） |
|
||||
| `jz-char` | 包裝單一標點／漢字，承載 `bd-*` class 與 `data-jz` 屬性 |
|
||||
| `jz-inner` | `jz-char` 內層字面容器，供 margin／letter-spacing 擠壓而不動外盒 |
|
||||
| `jz-cs` | 字間補償空白（連續／行端擠壓用，於行邊界折疊） |
|
||||
| `jz-jinze` | 禁則群組：綁定不可斷單元（亦為 justify 綁定載體） |
|
||||
| `jz-em` | 著重號載體 |
|
||||
| `jz-ruby`／`jz-rb`／`jz-rt` | ruby／注音 |
|
||||
|
||||
class 約定：`bd`（標點）、`bd-open/close/cop/stop/sep/liga`、`cjk`、`jiya`、
|
||||
`jiya-consecutive`、`hangable`、`jinze-{tou,wei,touwei}` 等。
|
||||
|
||||
---
|
||||
|
||||
## 6. 功能點逐項實作方案（對照 Han.css）
|
||||
|
||||
每項列出：Han 做法 → 我們做法 → 跨瀏覽器 → lang → 我們的調整 → 切片歸屬。
|
||||
|
||||
### 6.1 中西間隙（HWS，漢字↔西文）— 切片 1
|
||||
|
||||
- **Han**：插入 `<h-hws hidden>`，內含**真實空格** + `::before{content:' '}`，
|
||||
**未加 `user-select:none`** → 選取／複製會帶上空格（其已知缺陷）。
|
||||
- **我們**：finder 邊界感知地在 CJK↔西文邊界插入 `jz-hws`；間隙寬度由 CSS
|
||||
（`::before` 或內含空白 + 負微調）給定，元素 `user-select:none`（I1，**修正
|
||||
Han 的選中缺陷**）。WHERE 之規則沿用 v1 pangu 規則表（已驗證）。
|
||||
- **跨瀏覽器**：`user-select`／inline 普遍支援。
|
||||
- **lang**：間隙量可依 `:lang` 微調（如日文與中文略異），預設一致。
|
||||
- **調整**：copy-clean（I1）＋ justify 安全（I5／§8）。涵蓋 v1 Pass A、Pass B
|
||||
（pill `code/kbd` 邊界亦走同一機制，pill 由 avoid 與鄰接判定處理）。
|
||||
|
||||
### 6.2 長英文詞斷詞包裝 — 切片 1
|
||||
|
||||
- **我們**：把 `[A-Za-z]{N,}` 長串包進 `<span lang="en">`，配合消費端
|
||||
`hyphens:auto` 由瀏覽器原生斷詞渲染連字符（DOM 不含連字符 → 複製不污染）。
|
||||
直接沿用 v1 Pass C。
|
||||
- **跨瀏覽器**：`hyphens` 各家支援良好（含 `-webkit-`）。
|
||||
- **切片**：v1 對等。
|
||||
|
||||
### 6.3 標點擠壓（Jiya）— 切片 1
|
||||
|
||||
- **Han**：charify 標點為 `<h-char class="bd-jiya …"><h-inner>`，以負
|
||||
`letter-spacing`／`margin` 擠壓；連續、行端、簡繁差異以 CSS + `:lang()` 落實
|
||||
（`bd-cop:lang(zh-Hant)` → 不擠＝全角式）。
|
||||
- **我們**：同構——charify → `jz-char.bd-jiya` + `jz-inner`；擠壓量寫在
|
||||
`juzhen.css`，依 `bd-*` class 與 `:lang()` 套用。**全角式**（zh-Hant：`bd-cop`
|
||||
不擠）／**開明式**（zh-Hans：`bd-cop` 擠半形），政策由 `locale.style` 與
|
||||
`:lang()` 一致驅動（I3）。
|
||||
- **跨瀏覽器（I4）**：用負 `margin`／`letter-spacing`，**不依賴** `halt`／
|
||||
`text-spacing-trim`，故 Chrome／Safari／FF 一致。（註：v1 Pass D 用 `halt`，
|
||||
跨瀏覽器不一致；此處即為改進。）
|
||||
- **調整**：行端擠壓以 `jz-cs` 補償空白於行邊界折疊之機制達成（CSS 主導，免
|
||||
逐行量測）；justify 安全見 §8。
|
||||
- **切片**：涵蓋並超越 v1 Pass D（開明式），且加入全角式與 lang 切換。
|
||||
|
||||
### 6.4 禁則（Jinze，避頭尾）+ justify 綁定 — 切片 1（基礎）／後續（完整）
|
||||
|
||||
- **Han**：`h-jinze` 綁定行首行尾不可出現之標點與鄰字，避免標點落行首／行尾。
|
||||
- **我們**：`jz-jinze` 綁定為不可斷單元（CSS `display:inline-block` 或等價，內部
|
||||
不開 justify gap）。**此亦為 §8 justify 單份間距之載體**：句末標點與其字面留白
|
||||
成一原子單元，justify 伸縮只落單元之間。
|
||||
- **切片**：切片 1 先做「足以保證 §8 與標點不破壞間距」之最小綁定；完整避頭尾
|
||||
（所有禁則對象、行首縮排聯動）列後續，但用同一 `jz-jinze` 結構，無返工。
|
||||
|
||||
### 6.5 標點懸掛（Hanging）— 後續
|
||||
|
||||
- **Han**：行尾標點懸掛出版心，需量測。
|
||||
- **我們**：layout pass——量測各行末，對行末可懸掛標點施負位移；掛
|
||||
`ResizeObserver` 重算。`order=90`（最後）。lang 閘：**繁體橫排預設不懸掛**
|
||||
（clreq；`zh-Hant` 預設關），可開。
|
||||
- **預留**：依賴 `jz-char`／`jz-cs` 既有結構 + 一個 layout 後鉤子；切片 1 的
|
||||
charify 已備妥對象，加入時不動既有 pass。
|
||||
|
||||
### 6.6 標點修正（Biaodian normalize）— 後續（opt-in）
|
||||
|
||||
- **Han**：`subst`／`biaodian` 修正標點變體、位置。
|
||||
- **我們**：opt-in pass，預設**只分類＋打 class**（不改文字，I1）；顯式開啟才做
|
||||
變體替換（簡↔繁標點、全半形修正），且可 `revert`。
|
||||
- **預留**：`order=10` 最先；產物為 `jz-char` 之 class／屬性，與 charify 銜接。
|
||||
|
||||
### 6.7 著重號（Emphasis）— 後續
|
||||
|
||||
- **Han**：逐字包裝加圈點。
|
||||
- **我們**：優先用原生 `text-emphasis`（Chrome／FF／Safari 支援良好）；需精細
|
||||
控制時退回 `jz-em` 逐字包裝 + CSS 圓點。lang 感知（位置簡繁略異）。
|
||||
- **預留**：charify 能力直接複用。
|
||||
|
||||
### 6.8 注音／Ruby — 後續（最複雜）
|
||||
|
||||
- **我們**：基於原生 `<ruby>` + `jz-ruby/jz-rt` 處理注音符號直排與聲調定位。
|
||||
- **預留**：獨立 pass，`order=80`；不影響其餘。
|
||||
|
||||
### 6.9 樣式正常化／字體堆疊 — 貫穿（CSS）
|
||||
|
||||
- **我們**：`juzhen.css` 內以 `:where()`（零特異度，易被消費端覆寫）提供 CJK
|
||||
normalize 與依 `:lang` 之 Noto Sans／Serif CJK SC／TC／HK／JP 字體堆疊。非破壞、
|
||||
opt-in（掛在 `.juzhen` 容器或 `[data-juzhen]` 下）。
|
||||
- **跨瀏覽器**：`:where()`／`:lang()` 普遍支援。
|
||||
|
||||
### 6.10 計數器／緊排（counter／well-knit）— 低優先
|
||||
|
||||
- 後續以純 CSS 模組加入，不涉 JS 引擎。
|
||||
|
||||
---
|
||||
|
||||
## 7. 第一垂直切片（v1 對等）
|
||||
|
||||
**範圍**：核心基座（finder／unicode／locale／dom／pass 管線）+ 以下功能 pass：
|
||||
|
||||
| v1 | 切片 1 對應 | 機制 |
|
||||
|---|---|---|
|
||||
| Pass A 中西間隙 | `spacing` | `jz-hws`，copy-clean，justify 安全 |
|
||||
| Pass B pill 邊界 | `spacing`（同引擎） | avoid + 鄰接判定 |
|
||||
| Pass C 長英文詞 | `longWord` | `<span lang>` + `hyphens` |
|
||||
| Pass D 開明式擠壓 | `jiya` + `jinze` | 跨瀏覽器負 margin + `:lang` 全角／開明 + justify 綁定 |
|
||||
|
||||
**交付**：可 `build` 出 ESM／IIFE／CSS／d.ts；jsdom 測試覆蓋 DOM 變換正確性
|
||||
（包裝、class、邊界、冪等、copy-clean、lang 政策）；justify／簡繁 demo 頁供瀏覽器
|
||||
目視驗證版面（layout 行為無法於 jsdom 驗證，見 §12）。
|
||||
|
||||
**擴充保證**：切片 1 所用之 finder／charify／pass 管線／`jz-*` 詞彙／CSS-JS 契約，
|
||||
即後續所有 Han 功能所用者；新增功能 = 新增一個遵守 §2 不變量的 pass，不改切片 1。
|
||||
|
||||
---
|
||||
|
||||
## 8. justify 句末標點單份間距解法（要求 #3）
|
||||
|
||||
**問題**：`text-align: justify` 下，UA 在「對齊機會點」插入伸縮量。全角句末標點
|
||||
（如 `。`）字面只占字框一部分、自帶半形留白；若 UA 在其**兩側**都開伸縮，標點
|
||||
看似分到「兩份」間距（伸縮 gap ＋ 自身留白）。
|
||||
|
||||
**解法**（CSS 主導，I2／I5）：
|
||||
|
||||
1. charify 句末／句逗標點為 `<jz-char class="bd …"><jz-inner>。</jz-inner>`。
|
||||
2. `jz-char` 設 `display: inline-block`：使其成為 justify 的**單一原子項**，內部
|
||||
不開伸縮 gap，標點與其字面留白同屬一項，對齊伸縮只落在**項與項之間** → 標點
|
||||
只貢獻一份。
|
||||
3. **開明式**下，`jz-inner` 以負 letter-spacing 擠去半形留白，該項本身即半形，
|
||||
justify 一份 gap 即足。
|
||||
4. **全角式**下，留白保留於原子項內，仍只算一份；以 `jz-jinze` 綁定確保不在留白
|
||||
側額外開機會點。
|
||||
|
||||
> inline-block 影響基線對齊與行內換行，須以 CSS 校正（`vertical-align`、行高），
|
||||
> 並**跨 Chrome／Safari／FF 目視驗證**（§12）；此為切片 1 的重點驗證項。
|
||||
|
||||
---
|
||||
|
||||
## 9. 跨瀏覽器策略
|
||||
|
||||
- **一致性關鍵層**（間隙、擠壓、justify）：只用 `margin`、`letter-spacing`、
|
||||
`inline-block`、`user-select`、`:lang()`、`:where()`、`hyphens`——三大引擎
|
||||
（Blink／WebKit／Gecko）皆穩定支援。
|
||||
- **漸進增強（非必要）**：`text-spacing-trim`（Blink）、`hanging-punctuation`
|
||||
（WebKit）、`text-emphasis`、`text-autospace`——僅在支援時錦上添花，缺席不影響
|
||||
基本排版（I4）。
|
||||
- **驗證矩陣**：Chrome（Blink，含 VSCode／Electron）、Safari／WebKit、Firefox
|
||||
（Gecko）。demo 頁含三引擎可開的測試案例。
|
||||
|
||||
### 9.1 顯式禁用不一致原語（I4）
|
||||
|
||||
當原生原語在各引擎支援不一，或會與我們託管之版面**重複作用**（雙重擠壓／間隙）
|
||||
時，在 `.juzhen` 範圍內以 `@supports` 偵測並**主動關閉**，使所有引擎收斂於我們的
|
||||
一致路徑：
|
||||
|
||||
```css
|
||||
@supports (text-spacing-trim: space-all) {
|
||||
.juzhen { text-spacing-trim: space-all; } /* 關閉 Blink 原生 CJK 標點 kerning */
|
||||
}
|
||||
@supports (text-autospace: no-autospace) {
|
||||
.juzhen { text-autospace: no-autospace; } /* 關閉原生中西自動間距 */
|
||||
}
|
||||
```
|
||||
|
||||
政策：凡屬「一致性關鍵層」者（間隙、擠壓），一律由我們統一處理並禁用對應原生
|
||||
原語；凡屬「漸進增強」且不致衝突者（如 Safari 之 `hanging-punctuation`，在我們未
|
||||
託管懸掛時），方任其生效。此清單隨功能演進維護於 `css/_normalize.css`。
|
||||
|
||||
---
|
||||
|
||||
## 10. 模組／檔案佈局
|
||||
|
||||
```
|
||||
src/
|
||||
index.ts createJuzhen / Juzhen / pass 註冊 / render / revert
|
||||
core/
|
||||
pass.ts Pass 介面 + 管線執行器
|
||||
finder.ts 遍歷／avoid／charify／邊界感知 replace
|
||||
unicode.ts 字元類 + 標點子類 + 規則正則表
|
||||
locale.ts 有效 lang / 分類 / 全角開明政策
|
||||
dom.ts jz-* 工廠 / wrap / split / marker / revert
|
||||
typeset/
|
||||
spacing.ts 中西間隙 [切片 1]
|
||||
longword.ts 長英文詞包裝 [切片 1]
|
||||
jiya.ts 標點擠壓 + 全角開明 [切片 1]
|
||||
jinze.ts 禁則 + justify 綁定 [切片 1 基礎]
|
||||
hanging.ts 標點懸掛 [後續]
|
||||
biaodian.ts 標點修正 [後續]
|
||||
emphasis.ts 著重號 [後續]
|
||||
ruby.ts 注音／ruby [後續]
|
||||
css/
|
||||
juzhen.css 入口（@import 各 partial）
|
||||
_normalize.css _lang.css _spacing.css _jiya.css _jinze.css
|
||||
_hanging.css _emphasis.css _ruby.css
|
||||
test/ jsdom DOM 正確性測試
|
||||
demo/ 瀏覽器 layout／justify／簡繁 目視驗證頁
|
||||
build.mjs esbuild：ESM + IIFE + CSS；tsc：d.ts
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 11. 構建與發佈
|
||||
|
||||
- **源碼**：TypeScript（strict），模組化。
|
||||
- **構建**：`build.mjs` 以 esbuild 產出
|
||||
- `dist/juzhen.mjs`（ESM，供打包器／TS）
|
||||
- `dist/juzhen.iife.js`（IIFE，全域 `Juzhen`，原生 `<script>` 直跑——保留
|
||||
build.sh／Nvim peek 之單檔串接消費）
|
||||
- `dist/juzhen.css`（合併之樣式）
|
||||
- `tsc --emitDeclarationOnly` → `dist/juzhen.d.ts`
|
||||
- **發佈物**：`dist/` 提交入庫（消費端可直接取單檔／CSS）。
|
||||
|
||||
---
|
||||
|
||||
## 12. 測試與驗證策略
|
||||
|
||||
- **jsdom（自動）**：驗證 DOM 變換——包裝結構、`bd-*` class、邊界處理、冪等、
|
||||
`revert` 還原、copy-clean（`textContent` 不被注入污染）、lang 政策分支。
|
||||
- **瀏覽器（目視，demo 頁）**：layout 相關**無法**於 jsdom 驗證——justify 單份
|
||||
間距、擠壓視覺量、行端折疊、懸掛、inline-block 基線。demo 頁載 Noto CJK，簡繁
|
||||
並列、可切 justify、附選取／複製測試區，於 Chrome／Safari／FF 目視核對。
|
||||
- 文件明確標注哪些結論來自自動測試、哪些待瀏覽器目視。
|
||||
|
||||
---
|
||||
|
||||
## 13. 擴充性保證（如何加新功能而不返工）
|
||||
|
||||
新增任一 Han 功能點，標準流程：
|
||||
|
||||
1. 在 `unicode.ts` 補該功能所需字元類／正則（集中、不散落）。
|
||||
2. 新增 `typeset/<feature>.ts`，實作 `Pass`（`render`／`revert`／`order`）。
|
||||
3. 在 `index.ts` 註冊，加 `options.<feature>` 開關。
|
||||
4. 在 `css/_<feature>.css` 寫視覺規則（I2：尺寸只在 CSS）。
|
||||
5. 補 jsdom 測試 + demo 案例。
|
||||
|
||||
因所有功能共用 finder／charify／locale／`jz-*`／CSS-JS 契約，且順序由 `order`
|
||||
集中編排，新增不觸動既有 pass——此即「預留完整復刻 Han.css 能力」之具體保證。
|
||||
|
||||
---
|
||||
|
||||
## 14. 風險與未決項
|
||||
|
||||
原則：**風險上線後持續觀察，但下列預案先行設計就緒**，一旦觀察指標踩線即可切換，
|
||||
不致臨時返工。
|
||||
|
||||
- **R1 justify／inline-block 基線**（§8）。觀察：句末標點在三引擎 justify 下是否
|
||||
單份間距、inline-block 是否擾動基線／行高／行內換行。**預案**：改採 Han 路線之
|
||||
`jz-cs` 補償空白法（標點維持 inline，以行邊界可折疊之 `jz-cs` 控制伸縮側），
|
||||
結構已預留，切換僅換 CSS 機制不動 JS。
|
||||
- **R2 行端擠壓免量測**。觀察：純 CSS（`jz-cs` 折疊）能否在三引擎一致達成行首行尾
|
||||
擠壓。**預案**：退化為「連續＋行內擠壓用 CSS（一致）＋ 行端擠壓交由 layout pass
|
||||
量測或漸進增強原語」，行端與連續解耦，互不影響。
|
||||
- **R3 標點修正改寫文字 vs I1**。觀察：opt-in 開啟後複製／序列化是否仍可接受。
|
||||
**預案**：預設只分類不改寫；改寫模式強制可 `revert`，並提供「僅視覺替換（CSS
|
||||
字符替身）不動文字」之次級模式作折衷。
|
||||
- **R4 注音／ruby 複雜度**。觀察：原生 `<ruby>` 對注音直排／聲調定位之不足。
|
||||
**預案**：獨立 pass、最後做；先以原生 `<ruby>` 覆蓋多數，注音特例再以 `jz-ruby`
|
||||
子結構補強，不影響其餘 pass。
|
||||
- **R5 DOM 重量**。觀察：長文 charify 之節點數與 render 耗時。**預案**：兩階段批次
|
||||
變更（§3.4）+ 僅包裝必要標點 + 可選分塊／`requestIdleCallback` 漸進渲染；demo
|
||||
量測超標才啟用分塊。
|
||||
|
||||
---
|
||||
|
||||
*本文件為實作契約。任何偏離（尤其 §2 不變量）須先更新本文件再改碼。*
|
||||
Reference in New Issue
Block a user