docs: 效能/增量 API 文檔+I1/I6 收緊(作者空格規範化不還原)

README:新增「動態頁面:增量恢復」(rerender/invalidate/observe/disconnect 用法+元素變化正確性
告示);新增「revert 之範圍」注(revert 淨移除 jz-* 結構、回邏輯等價態,但不還原 spacing 依契約
規範化之贅餘作者空格;需保留原始源者勿以 revert 當「還原到未處理源碼」)。

ARCHITECTURE:§3.1 增量 API;§4.1 記憶化(category+祖先游走)與快取生命週期/失效;§6.1a S1
對齊門。**I1/I6 收緊**(消除與固有 strip 行為之措辭張力,方案 A):
- I1 明示 spacing 規範化贅餘作者空格為刻意之常態例外(語義不變、但確刪空格且不經 revert 還原),
  除此之外預設「只包裝、不改寫文字」。
- I6 明示 revert 淨移除全部 jz-* 結構、回「邏輯等價」態;「邏輯等價≠逐字節」之唯一差異即被規範化
  之作者空格(穩定、不隨反覆 render/revert 累積;revert 後無 [data-jz] 殘留)。

依據:4 份真人撰寫真實文檔驗收——非空白字元多重集守恆、無字元改/增/漏/亂序,唯贅餘作者空格依
契約規範化(doc-A 55、B 31、C 0、D 85 個);真瀏覽器整條管線(含 lineEdge/gapTrim)零報錯。
This commit is contained in:
2026-07-12 02:21:07 +08:00
parent c5a503580c
commit 2f04ea4085
2 changed files with 87 additions and 10 deletions
+38
View File
@@ -59,6 +59,44 @@ jz.render(document.querySelector("main"));
**JS 與 CSS 缺一不可**JS 只注入 `jz-*` 結構,所有視覺尺寸(間隙寬度、擠壓量、
`justify` 原子化、字體堆疊)都在 `juzhen.css`
### 動態頁面:增量恢復(局部變化免全樹重掃)
`render(root)``revert(root)` **皆可傳入局部 Element**——頁面局部變化時,只重處理受影響
之子樹即可,成本 O(該塊) 而非 O(全文)(實測編輯 400 段中之一段,局部恢復較全樹快數百倍)。
```ts
const jz = createJuzhen();
jz.render(document.body); // 初次全樹
// 局部變化後(手動):
jz.rerender(changedBlock); // revert(changedBlock) + render(changedBlock)
jz.render(newlyAppendedBlock); // 新增之塊:直接 render(無須 revert
// 自動(opt-in):觀察 DOM,內容/分類屬性變化時自動只重處理受影響之最近塊。
jz.observe(document.body); // 之後 DOM 變動即自動增量恢復
// jz.disconnect(); // 停止觀察
```
- **`rerender(root?)`**`revert``render` 同一(子)樹(便利方法)。
- **`observe(root?)``disconnect()`**:以 `MutationObserver` 自動增量。juzhen 自身之注入
於處理期間暫停觀察、**絕不自觸發**;新增之塊直接 render(免全容器重掃)。需 `MutationObserver`
(瀏覽器/jsdom 有;無則 no-op)。
- **`invalidate(root?)`**:清該子樹之內部快取。**`revert` 已自動失效其子樹**,故僅在「改了既有
元素之分類相關屬性(`class``data-jz-*``lang` 等)**但不走 `revert`**」時才需顯式調用,以
免下次 render 沿用陳舊分類。內容(子節點/文本)變化不改分類、無需 `invalidate`(但須
`revert`+`render` 該塊方能重處理)。
> **元素變化之正確性**:實例內部對「元素分類(透明/pill/隔離/avoid)/功能級別/功能開關」
> 快取以加速跨 render 復用(快取隨實例持久、非每次 render 重建)。**改變既有元素之上列屬性後,
> 須經 `revert``rerender``invalidate``observe` 任一使該子樹快取失效**,否則沿用舊分類。
> 新增/移除元素與純內容編輯無此顧慮(新元素重新計算、移除者自動回收)。
> **`revert` 之範圍**`revert` 乾淨移除聚珍注入之全部結構(`jz-*``data-jz-*`),DOM 回到**邏輯
> 等價**態;但**不還原** `spacing` 依契約規範化之贅餘作者空格(CJK↔西文吸收為 margin 間隙、
> CJK↔CJK 剝除;見上表「中西間隙」)。即 `render→revert` 對含 CJK↔西文作者空格之源,還原後語義
> 一致、無 `jz-*` 殘留,唯該空格已正規化(此差異穩定、不隨反覆 render/revert 累積)。若消費端需
> 保留原始作者空格以供編輯,應自存原文、勿以 `revert` 當「還原到未處理源碼」。
---
## 切片 1 已實作功能