docs: 聚珍 HTML 文檔（使用文檔＋變更紀錄）

docs 分支僅含文檔，與程式碼歷史脫鉤（orphan，無 src／dist 等舊實現之提交）。以 HTML manifest 模板（report 模式）構建為自含單檔，無外部依賴。 - docs/index.html 使用文檔：安裝／用法／功能／選項／halt 與 margin 後備／字型偏側與配字工作流／CSS 基礎設定／分頁器相容／v1 相容。 - docs/changelog.html 變更紀錄。 - *.src.html 為可編輯之文檔源。程式碼正本與其歷史在 main；本分支不記錄任何實現。
2026-06-02 01:41:35 +08:00
commit 92c37cf63e
5 changed files with 11819 additions and 0 deletions
@@ -0,0 +1,3 @@
+.DS_Store
+node_modules/
+*.log
@@ -0,0 +1,127 @@
+<!DOCTYPE html>
+<html lang="zh-Hant">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>變更紀錄（Changelog）</title>
+<meta name="generated-at" content="2026-06-02">
+<meta name="source" content="cjk-autospace · 變更紀錄">
+<!-- RUNTIME_CSS -->
+</head>
+<body>
+
+<header class="page">
+    <div class="meta">
+        <h1>變更紀錄（Changelog）</h1>
+        <p class="subtitle">聚珍（Juzhen）／cjk-autospace 之版本變更紀錄。</p>
+        <p class="timestamp"><time>2026-06-02</time> · <span>cjk-autospace · 變更紀錄</span></p>
+    </div>
+    <div class="actions">
+<!-- ACTIONS -->
+    </div>
+</header>
+
+<main>
+<!-- BODY -->
+<p class="lede">聚珍（Juzhen）／cjk-autospace 變更紀錄。<a href="./index.html">← 回文檔</a></p>
+
+<h2>v2 切片 1 · 增補 <span class="badge accent">2026-06</span></h2>
+<p>切片 1 之上的修補與強化，聚焦標點半形對缺 <code>halt</code> 字型之支援，及下游回饋之邊界／分頁器修復。</p>
+
+<h3>新增</h3>
+<ul>
+<li><strong>標點半形 <code>margin</code> 後備模式</strong>（缺 OpenType <code>halt</code> 之字型）：<code>jiya.halfWidth: "halt"</code>（預設）｜<code>"margin"</code>。<code>margin</code> 以 <code>width:0.5em</code> ＋字身依墨色偏側溢出定位，於 CSS 盒模型重現 <code>halt</code> 之半形 advance（真 0.5em；相鄰標點各 0.5em、合佔 1em，無負 margin 之鄰接疊加／單側重疊）。模式由 <code>data-jz-halfwidth</code> 子樹屬性決定，可逐區塊／逐 <code>lang</code>（含 halt-island 反置）。</li>
+<li><strong>字形偏側表 <code>inkBias</code></strong>：依字身墨色中心給 <code>left／center／right／full</code>；彎引號／角括號／尖括號偏一側、圓方括號近中。參考表據方正書宋 GBK 實測，可經 <code>jiya.bias</code> 逐 <code>lang</code> 逐字覆寫。</li>
+<li><strong>字型適配工具與工作流</strong>：<code>tools/measure-bias.py</code>（量 glyph ink 中心、產偏側建議表）＋文檔之「字型適配工作流」。<code>demo/fallback.html</code>：方正書宋 GBK 對照 halt 失效 vs margin 生效。</li>
+<li><strong><code>justifyAtoms</code> 選項</strong>：預設 <code>true</code>；設 <code>false</code> 時 <code>jz-char</code>／<code>jz-jinze</code> 改 <code>display:inline</code>，相容分頁器（Paged.js）之對齊引擎（<code>halt</code> 半形與禁則 <code>nowrap</code> 保留）。</li>
+</ul>
+
+<h3>修復</h3>
+<ul>
+<li><strong>字型不覆寫消費端</strong>：<code>_lang.css</code> 之 Noto 字型堆疊改為純後備——全包 <code>:where()</code> 零特異度、只命中帶 <code>lang</code> 屬性之元素、不直接覆寫標點字面容器 <code>jz-inner</code>。消費端 <code>font-family</code> 恆優先，標點隨之以消費端字型渲染（修正先前標點被強制換成 Noto 之缺陷）。</li>
+<li><strong>pill 緊鄰標點之左緣間隙</strong>：<code>adjacentLogicalChar</code> 透明穿越 <code>jz-jinze</code>（同 <code>jz-hws</code>／樣式行內）→ pill 後接 CJK 標點時，左緣 <code>jz-hws</code> 與作者空格剝除復原。</li>
+<li><strong>CJK↔CJK 贅餘作者空格</strong>：含跨 inline 標籤者一律剝除、不留隙，與 CJK↔西文之邊界正規化一致（全形空格 U+3000 不動）。</li>
+</ul>
+
+<h3>已知限制</h3>
+<ul>
+<li><code>margin</code> 後備半形依賴 <code>inline-block</code>（<code>width:0.5em</code>），與 <code>justifyAtoms:false</code> 不可兼得——分頁器場景請用含 <code>halt</code> 之字型。</li>
+<li><code>margin</code> 偏側為三檔量化（0／0.25／0.5em）之近似；字形極端者須以 <code>jiya.bias</code> 逐字微調。</li>
+</ul>
+
+<h2>v2.0.0 <span class="badge accent">切片 1</span> · 從零重寫</h2>
+<p>依 <code>ARCHITECTURE.md</code> 契約，從零重寫為「現代簡／繁中文網頁排版套件」。倉庫名 <code>cjk-autospace</code> 不變；公開 API 為 <code>createJuzhen</code> ／全域 <code>Juzhen</code>；自訂元素前綴 <code>jz-</code>。v1 完整保留於 <code>v1-autospace</code> 分支。</p>
+
+<h3>新增</h3>
+<ul>
+<li><strong>核心引擎</strong>：<code>finder</code>（遍歷／avoid／<code>scope.include</code>／邏輯 run／pill 鄰字／分塊閘 <code>featureEnabledFor</code>）、<code>unicode</code>（字元表＋標點子類＋字形側位）、<code>locale</code>（語言分類＋全角／開明政策）、<code>dom</code>（<code>jz-*</code> 工廠＋可還原標記）、<code>pass</code> 聚合管線。</li>
+<li><strong>中西間隙</strong>（margin 模型）：包裹邊界左側字、以 <code>margin-right</code> 留隙，<strong>不注入空白字元</strong> → <code>textContent</code> 完全不變、複製緊湊、<code>justify</code> 不暴增、不撐框、行首乾淨。<code>gapTrim</code> layout pass 行末去隙以齊右。</li>
+<li><strong>標點擠壓</strong>：全角式／開明式／半角式，三機制（baseline 政策＋行內連續擠壓＋行端擠壓）。半形以字型 OpenType <code>halt</code> 渲染。全域 <code>lang.style</code> ＋逐 <code>lang</code> <code>policy</code>。</li>
+<li><strong>禁則（避頭尾）</strong>：閉類／點號綁前一字、開類綁後一字，以詞元為邊界、長引文中段可斷；兼作 <code>justify</code> 綁定。</li>
+<li><strong>長英文詞</strong>：<code>&lt;span lang&gt;</code> ＋ <code>hyphens</code> 原生斷詞。</li>
+<li><strong>justify 句末單份間距</strong>：<code>jz-char</code> inline-block 原子化。</li>
+<li><strong>v1 相容層</strong>：<code>createCjkAutospace().apply()</code> 映射；IIFE 全域別名。</li>
+<li><strong>構建／測試</strong>：esbuild（ESM／IIFE／CSS）＋ tsc（d.ts）；jsdom 測試；<code>demo/</code> 簡繁並列＋justify＋標點寬度量測。</li>
+</ul>
+
+<h3>相對 v1 之改進</h3>
+<ul>
+<li>中西間隙複製乾淨（<code>textContent</code> 不變；v1 之 <code>&lt;span&gt;</code> 真實空格會被選取）。</li>
+<li>擠壓由「<code>halt</code> 套整段＝半角式」進化為依 <code>lang</code> 之全角／開明／半角，且加入行內連續與行端擠壓。</li>
+<li>新增禁則避頭尾、justify 句末單份間距、跨瀏覽器一致策略與顯式禁用層。</li>
+</ul>
+
+<h2>v1（cjk-autospace） · v1-autospace 分支</h2>
+<p>Pangu.js v7.2.1 風格之 CJK↔Latin 邊界自動間距 shim，工廠 <code>createCjkAutospace(options).apply(root)</code>。</p>
+<ul>
+<li>Pass A：跨樣式邊界中西間隙（marker span 含真實空格 ＋ <code>user-select:none</code>）。</li>
+<li>Pass B：pill（<code>code</code>／<code>kbd</code>）邊界間隙。</li>
+<li>Pass C：長英文詞 <code>&lt;span lang&gt;</code> ＋ <code>hyphens</code>。</li>
+<li>Pass D：開明式標點擠壓（句內點號 <code>font-feature-settings:"halt"</code> 半形）。</li>
+</ul>
+
+</main>
+
+<footer class="page">
+    <p>本頁由聚珍排版工程記錄。所有文檔操作均於 docs 分支進行；main 僅存一份未追蹤之本地鏡像。</p>
+</footer>
+
+<!-- RUNTIME_SPRITE -->
+
+<script type="text/markdown" id="md-source">
+# 變更紀錄（Changelog）— 聚珍（Juzhen）／cjk-autospace
+
+## v2 切片 1 · 增補（2026-06）
+
+### 新增
+- 標點半形 margin 後備模式（缺 halt 字型）：jiya.halfWidth "halt"|"margin"；margin 以 width:0.5em＋字身偏側溢出定位重現 halt。模式由 data-jz-halfwidth 子樹屬性決定。
+- 字形偏側表 inkBias（left/center/right/full），jiya.bias 逐 lang 逐字覆寫。
+- tools/measure-bias.py 字型偏側量測＋字型適配工作流；demo/fallback.html。
+- justifyAtoms 選項（false → jz-char/jz-jinze 改 inline，相容 Paged.js）。
+
+### 修復
+- _lang.css 字型堆疊改純後備（:where 零特異度、只命中 [lang] 元素、不覆寫 jz-inner）→ 消費端字型恆優先。
+- adjacentLogicalChar 透明穿越 jz-jinze → pill 緊鄰標點之左緣間隙與作者空格剝除復原。
+- CJK↔CJK 贅餘作者空格（含跨 inline 標籤）剝除不留隙。
+
+### 已知限制
+- margin 後備與 justifyAtoms:false 不可兼得（分頁器場景用 halt 字型）。
+
+## v2.0.0 切片 1 · 從零重寫
+
+依 ARCHITECTURE.md 從零重寫。公開 API createJuzhen／全域 Juzhen，前綴 jz-。
+
+- 核心引擎 finder／unicode／locale／dom／pass。
+- 中西間隙（margin 模型，copy-clean）＋gapTrim 行末去隙。
+- 標點擠壓 全角／開明／半角，三機制，半形 halt。
+- 禁則避頭尾＋justify 綁定；長英文詞；justify 句末單份間距；v1 相容層。
+
+## v1（cjk-autospace，v1-autospace 分支）
+
+Pangu 風格 CJK↔Latin 間距 shim。Pass A 中西間隙／B pill／C 長詞／D 開明擠壓。
+</script>
+
+<!-- RUNTIME_JS -->
+
+</body>
+</html>
@@ -0,0 +1,223 @@
+<!DOCTYPE html>
+<html lang="zh-Hant">
+<head>
+<meta charset="UTF-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>聚珍（Juzhen）</title>
+<meta name="generated-at" content="2026-06-02">
+<meta name="source" content="cjk-autospace · 使用文檔">
+<!-- RUNTIME_CSS -->
+</head>
+<body data-toc="1">
+
+<header class="page">
+    <div class="meta">
+        <h1>聚珍（Juzhen）</h1>
+        <p class="subtitle">現代簡／繁中文網頁排版套件——Han.css 之現代化重寫，複製乾淨、依 lang 全角／開明切換、justify 句末標點單份間距、跨瀏覽器一致。</p>
+        <p class="timestamp"><time>2026-06-02</time> · <span>cjk-autospace · 使用文檔</span></p>
+    </div>
+    <div class="actions">
+<!-- ACTIONS -->
+    </div>
+</header>
+
+<main>
+<!-- BODY -->
+<p class="lede">聚珍（Juzhen）是現代簡／繁中文網頁排版套件，Han.css 之現代化重寫，沿其功能版圖，並針對四點作調整：複製乾淨（中西間隙不入剪貼板）、依 <code>lang</code> 全角／開明自動切換、<code>justify</code> 下句末標點只佔一份間距、跨瀏覽器一致。倉庫名仍為 <code>cjk-autospace</code>；公開 API 為 <code>createJuzhen</code> ／全域 <code>Juzhen</code>；注入之自訂元素前綴 <code>jz-</code>。</p>
+
+<p>本版（2.x）為從零重寫。v1 之 <code>createCjkAutospace</code> API 由相容層保留，既有消費端不需改碼即可運行；v1 原始碼保存於 <code>v1-autospace</code> 分支。設計契約見 <code>ARCHITECTURE.md</code>。</p>
+
+<h2>安裝與構建</h2>
+<pre><code>npm install
+npm run build   # esbuild → dist/juzhen.{mjs,iife.js,css}；tsc → dist/index.d.ts
+npm test        # jsdom DOM 正確性測試</code></pre>
+<p>產物（<code>dist/</code>，已入庫）：<code>juzhen.mjs</code>（ESM，供打包器／TypeScript）、<code>juzhen.iife.js</code>（IIFE，全域 <code>Juzhen</code>，原生 <code>&lt;script&gt;</code> 直跑）、<code>juzhen.css</code>（合併樣式，<strong>必須引入</strong>）、<code>index.d.ts</code>（型別宣告）。</p>
+
+<h2>用法</h2>
+<h3>原生 <code>&lt;script&gt;</code></h3>
+<pre><code>&lt;link rel="stylesheet" href="dist/juzhen.css"&gt;
+&lt;script src="dist/juzhen.iife.js"&gt;&lt;/script&gt;
+&lt;script&gt;
+    const jz = Juzhen.createJuzhen({ scope: { include: ".prose" } });
+    jz.render();      // 對 document.body 套用（僅命中 .prose 子樹）
+    // jz.revert();    // 還原
+&lt;/script&gt;</code></pre>
+<h3>ESM／TypeScript</h3>
+<pre><code>import { createJuzhen } from "cjk-autospace";
+import "cjk-autospace/css";
+
+createJuzhen({ lang: { default: "zh-Hant" } }).render(document.querySelector("main"));</code></pre>
+<div class="callout info"><span class="label">JS 與 CSS 缺一不可</span> JS 只注入 <code>jz-*</code> 結構，所有視覺尺寸（間隙寬度、擠壓量、<code>justify</code> 原子化、字體堆疊）都在 <code>juzhen.css</code>。缺 CSS 則全部失效。</div>
+
+<h2>已實作功能</h2>
+<table>
+<thead><tr><th>功能</th><th>說明</th></tr></thead>
+<tbody>
+<tr><td>中西間隙 <code>spacing</code></td><td>CJK↔西文邊界，<strong>margin 模型</strong>：包裹左側字、以 <code>margin-right</code> 留隙，不注入空白字元 → <code>textContent</code> 完全不變、複製緊湊、<code>justify</code> 不暴增、行首乾淨；行末由 <code>gapTrim</code> layout pass 去隙以齊右。含跨樣式邊界與 <code>code</code>／<code>kbd</code> pill（pill 緊鄰標點時穿越 <code>jz-jinze</code> 仍補間隙）。贅餘作者空格一律正規化：CJK↔西文吸收為受管間隙、CJK↔CJK（含跨 inline 標籤）剝除不留隙。</td></tr>
+<tr><td>長英文詞 <code>longWord</code></td><td><code>[A-Za-z]{6,}</code> 包入 <code>&lt;span lang="en"&gt;</code>，配合消費端 CSS <code>hyphens:auto</code> 原生斷詞（DOM 無連字符 → 複製不污染）。</td></tr>
+<tr><td>標點擠壓 <code>jiya</code></td><td>標點 charify 為 <code>jz-char</code> ＋ <code>bd-*</code> class。三機制：baseline 政策（全角式不擠／開明式擠句內點號＋括號引號／半角式全擠）＋行內連續擠壓＋行端擠壓。半形預設以字型 OpenType <code>halt</code> 渲染；缺 <code>halt</code> 字型可切 <code>margin</code> 後備模式（見下）。</td></tr>
+<tr><td>禁則 <code>jinze</code></td><td>行首行末避頭尾：閉類／點號綁前一字（不置行首）、開類綁後一字（不置行末）；只隔離邊界詞元，長引文中段仍可斷。亦為 <code>justify</code> 綁定載體。</td></tr>
+<tr><td>justify 單份間距</td><td>每個 <code>jz-char</code> 為 <code>inline-block</code> 原子，句末標點只貢獻一份對齊伸縮量。</td></tr>
+</tbody>
+</table>
+<p>後續（架構已預留，不返工）：標點懸掛、標點修正（簡↔繁）、著重號、注音／Ruby。</p>
+
+<h2>選項</h2>
+<pre><code>createJuzhen({
+    lang: {
+        default: "zh-Hant",                        // 無 lang 祖先時之預設語言標籤
+        style: "kaiming",                          // 全域擠壓預設：quanjiao｜kaiming｜banjiao
+        policy: { "zh-Hant": "quanjiao" },         // 逐 lang 覆寫（最高優先）
+    },
+    scope: { root: document.body, include: ".prose", avoid: "blockquote.raw" },
+    spacing: true,
+    longWord: { minLength: 6, lang: "en" },
+    jiya: true,                                    // 或物件：{ halfWidth: "halt"|"margin", bias }
+    jinze: true,
+    justifyAtoms: true,                            // 分頁器下設 false 改 inline（見下）
+    blocks: [ { selector: ".code-comment", features: [ "spacing" ] } ],
+});</code></pre>
+<p>擠壓政策優先序：<strong>逐 lang <code>policy</code> ＞ 全域 <code>style</code> ＞ 內建預設</strong>（繁→全角、簡→開明）。</p>
+<h3>分塊功能選擇（HTML 屬性，就近繼承）</h3>
+<pre><code>&lt;p data-juzhen="spacing jiya"&gt;…&lt;/p&gt;      &lt;!-- 白名單：僅此二功能 --&gt;
+&lt;p data-juzhen-off="jiya"&gt;…&lt;/p&gt;          &lt;!-- 黑名單：停用 jiya，其餘繼承 --&gt;
+&lt;div lang="zh-Hans"&gt;…&lt;/div&gt;              &lt;!-- lang 驅動全角／開明 --&gt;</code></pre>
+
+<h2>標點半形：<code>halt</code> 預設與 <code>margin</code> 後備</h2>
+<p>開明／半角式把標點收成「半形」，有兩種渲染機制：</p>
+<table>
+<thead><tr><th>機制</th><th>設定</th><th>原理</th><th>適用</th></tr></thead>
+<tbody>
+<tr><td><code>halt</code>（預設）</td><td><code>jiya: true</code></td><td>字型 OpenType <code>halt</code>，由字型按字形正確定位、不重疊</td><td>字型含 <code>halt</code>（Noto CJK／思源系列）</td></tr>
+<tr><td><code>margin</code>（後備）</td><td><code>jiya: { halfWidth: "margin" }</code></td><td><code>width:0.5em</code> ＋字身依墨色偏側溢出定位（以 CSS 重現 halt）</td><td>字型<strong>缺</strong> <code>halt</code>（多數系統字型、GBK 老字型如方正書宋 GBK、PingFang）</td></tr>
+</tbody>
+</table>
+<div class="callout warn"><span class="label">為何需要後備</span> <code>halt</code> 缺席時開明式擠壓「完全無效」（標點仍佔全形）。實測<strong>方正書宋 GBK 僅含 <code>vert</code>、無 <code>halt</code></strong> → halt 模式不擠；切 <code>margin</code> 後備後，同句行寬 <code>24.0em → 19.5em</code>、單一標點 <code>1.0em → 0.5em</code>，半形生效。</div>
+
+<h3>激活與粒度</h3>
+<p>模式由 <strong><code>data-jz-halfwidth</code> 屬性所在子樹</strong>決定（CSS 後代選擇器），故粒度極靈活：</p>
+<ul>
+<li><strong>全域</strong>：<code>jiya: { halfWidth: "margin" }</code> → <code>render()</code> 於處理 root 自動掛屬性。</li>
+<li><strong>逐區塊／逐語言</strong>：在 HTML 任一祖先手寫 <code>data-jz-halfwidth="margin"</code>（或 <code>"halt"</code>），即令該子樹用對應機制，無需另建實例。常見如「全頁 <code>halt</code>，某用無 <code>halt</code> 字型之區塊掛 <code>margin</code>」，或反之（<code>margin</code> 頁中嵌一塊 <code>halt</code> 島）。</li>
+</ul>
+<pre><code>&lt;!-- 全頁 halt（預設），此塊改用無 halt 字型 → 局部 margin 後備 --&gt;
+&lt;section data-jz-halfwidth="margin" style="font-family: '方正书宋_GBK'"&gt;…&lt;/section&gt;</code></pre>
+
+<h3>機制與字形偏側表（<code>margin</code> 模式專用，可覆寫）</h3>
+<p><code>margin</code> 模式把標點 <code>jz-char</code> 之 inline-block 寬收為 <strong>0.5em（真半形 advance）</strong>，字身（<code>jz-inner</code>）以 <code>overflow</code> 溢出該盒，再依<strong>墨色偏側</strong>左移、使墨色落於 0.5em 盒內、空白溢向外側——即以 CSS 盒模型重現 <code>halt</code> 之「收字身寬＋按字形定位」。相鄰兩標點各 0.5em、合佔 1em，無鄰接疊加或單側重疊問題。</p>
+<p>偏側依每字墨色中心。聚珍內建<strong>參考表</strong>（依方正書宋 GBK 實測之 glyph ink 位）：簡體點號 <code>，、。；：！？</code> 偏左；繁體點號居中；彎引號 <code>“”‘’</code>、角括號 <code>「」</code>、尖括號 <code>〈〉</code> 墨色強偏一側（開→<code>right</code>、閉→<code>left</code>）；圓／方／書名等括號 <code>（）【】《》…</code> 墨色近中→<code>center</code>。可逐 <code>lang</code> 逐字覆寫：</p>
+<pre><code>createJuzhen({
+    jiya: {
+        halfWidth: "margin",
+        bias: {
+            "zh-Hans": { "，": "center", "（": "right" },  // 覆寫參考預設
+            "zh-Hant": { "。": "center" },
+        },
+    },
+});
+// 偏側值（決定字身於 0.5em 盒內之左移）：
+//   left   墨偏左 → 不移（字身左對齊）
+//   center 墨居中 → 左移 0.25em
+//   right  墨偏右 → 左移 0.5em（右半入盒）
+//   full   無可壓縮空白 → 不收、維持全形</code></pre>
+
+<h3>字型適配工作流（margin 模式配字）</h3>
+<p>換用新字型時，依下列步驟確認半形渲染：</p>
+<ol>
+<li><strong>驗 <code>halt</code></strong>：<code>python3 tools/measure-bias.py &lt;font.ttf&gt;</code>（需 <code>pip install fonttools</code>）。首行報該字型是否含 OpenType <code>halt</code>。有則直接用預設（halt 模式），到此為止；無則用 <code>margin</code> 後備，續下。</li>
+<li><strong>取偏側建議</strong>：同一工具量各標點 glyph 之墨色中心、印出建議偏側表與可貼入 <code>jiya.bias</code> 之 JSON。</li>
+<li><strong>套用</strong>：<code>createJuzhen({ jiya: { halfWidth: "margin", bias: &lt;貼入 JSON&gt; } })</code>；多數宋體系 GBK 字型與內建參考表相符，未必需覆寫。</li>
+<li><strong>目視微調</strong>：與原文對照逐字檢查——標點與鄰字<strong>重疊</strong>則偏側往「不移」方向調（<code>right→center→left</code>）；標點與內容<strong>仍有空隙</strong>則往「多移」方向調（<code>left→center→right</code>）；某標點無可壓空白則設 <code>full</code>。</li>
+<li><strong>記錄</strong>：把該字型之 <code>bias</code> 覆寫存入專案設定，作為該字型之適配結果。</li>
+</ol>
+<p>偏側是「字身於 0.5em 盒內左移多少」的三檔量化（0／0.25／0.5em）；量測值近門檻時以目視為準。<code>halt</code> 字型由字型精確定位，無此配字需求——<code>margin</code> 配字僅為缺 <code>halt</code> 字型之務實近似。</p>
+
+<h2>CSS 基礎設定（消費端須知）</h2>
+<p>JS 只注入 <code>jz-*</code> 結構，<strong>所有視覺尺寸在 <code>juzhen.css</code></strong>。消費端須備妥：</p>
+<ol>
+<li><strong>引入樣式（必須）</strong>：<code>&lt;link rel="stylesheet" href="dist/juzhen.css"&gt;</code>（或 ESM <code>import "cjk-autospace/css"</code>）。</li>
+<li><strong>設定 <code>lang</code>（強烈建議）</strong>：內容容器標 <code>lang="zh-Hans"</code>／<code>"zh-Hant"</code>／<code>"ja"</code>，驅動全角／開明政策與字形 <code>locl</code>。</li>
+<li><strong>作用域類</strong>：若設 <code>scope.include: ".juzhen"</code>，須給內容容器加對應 class；<code>juzhen.css</code> 之 normalize／字型堆疊亦收斂於此域。</li>
+<li><strong>長英文詞斷字</strong>：須由消費端 CSS 提供 <code>hyphens: auto</code>（含 <code>-webkit-hyphens</code>）。</li>
+<li><strong><code>justify</code>（選用）</strong>：欲兩端對齊則自設 <code>text-align: justify</code>；句末標點單份間距與行末去隙由聚珍處理。</li>
+<li><strong>字型（影響擠壓）</strong>：半形預設依字型 <code>halt</code>；含 <code>halt</code> 字型（Noto CJK／思源）即可，缺則用 <code>margin</code> 後備。<code>juzhen.css</code> 內建依 <code>:lang</code> 之 Noto CJK 字型堆疊，但<strong>僅作後備</strong>（全包 <code>:where()</code> 零特異度、只命中帶 <code>lang</code> 屬性之元素、不直接覆寫標點字面容器）——<strong>消費端 <code>font-family</code> 恆優先</strong>，標點亦隨之以消費端字型渲染。</li>
+<li><strong>自動處理</strong>：<code>juzhen.css</code> 已於 <code>.juzhen</code> 範圍內以 <code>@supports</code> 關閉 Blink 原生 <code>text-spacing-trim</code>／<code>text-autospace</code>，並令注入間隙 <code>user-select: none</code>（複製乾淨）。</li>
+</ol>
+
+<h2>分頁器（Paged.js 等）相容：<code>justifyAtoms</code></h2>
+<p>預設 <code>jz-char</code>／<code>jz-jinze</code> 為 <code>inline-block</code>，作 <code>justify</code> 之單一對齊原子。但<strong>分頁器</strong>（如 Paged.js）之對齊引擎會把每個 inline-block 邊界當伸縮點、與 CJK inter-ideograph 疊加，於窄欄混排時字距失控、整段散架。此時設 <code>justifyAtoms: false</code>——<code>jz-char</code>／<code>jz-jinze</code> 改 <code>display:inline</code>（半形 <code>halt</code> 與禁則 <code>nowrap</code> 綁定均保留）。常規流式版面無需設定。</p>
+<div class="callout warn"><span class="label">注意</span> <code>margin</code> 後備半形依賴 <code>inline-block</code>（<code>width:0.5em</code>），故 <code>justifyAtoms:false</code> 與 <code>margin</code> 模式不可兼得——分頁器場景請用含 <code>halt</code> 之字型。</div>
+
+<h2>v1 向下相容</h2>
+<pre><code>const cjk = createCjkAutospace({ pillSelector: "code, kbd" });
+cjk.apply(document.body);   // → render</code></pre>
+<p>IIFE 另掛 <code>globalThis.createCjkAutospace</code> 別名。與 v1 之差異（行為等價、不要求逐位一致）：間隙由 <code>&lt;span&gt;</code> ＋真實空格改為 <code>jz-hws</code> margin（複製更乾淨）；擠壓改由 <code>juzhen.css</code> 託管，預設仍以字型 <code>halt</code> 渲染半形（同 v1 機制），缺 <code>halt</code> 字型可切 <code>margin</code> 後備。</p>
+
+<h2>目視驗證</h2>
+<p><code>demo/index.html</code> 載入 <code>dist/</code> 產物，簡繁並列、可切 <code>justify</code>、附 copy-clean 測試區。<code>demo/fallback.html</code> 以方正書宋 GBK（無 <code>halt</code>）對照 <code>halt</code> 失效 vs <code>margin</code> 後備生效。版面相關結論（justify 單份間距、擠壓視覺量、行端、<code>inline-block</code> 基線）須於 Chrome／Safari／Firefox 三引擎目視核對——jsdom 僅驗證 DOM 結構正確性。</p>
+
+</main>
+
+<footer class="page">
+    <p>本頁為聚珍（Juzhen）使用文檔。所有文檔操作均於 docs 分支進行；main 僅存一份未追蹤之本地鏡像。MIT 授權；借鑑 Han.css／Heti 之思路與分類表，成品自含。</p>
+</footer>
+
+<!-- RUNTIME_SPRITE -->
+
+<script type="text/markdown" id="md-source">
+# 聚珍（Juzhen）
+
+現代簡／繁中文網頁排版套件。Han.css 之現代化重寫：複製乾淨、依 `lang` 全角／開明切換、`justify` 句末標點單份間距、跨瀏覽器一致。公開 API `createJuzhen` ／全域 `Juzhen`，自訂元素前綴 `jz-`。
+
+## 用法
+
+```html
+<link rel="stylesheet" href="dist/juzhen.css">
+<script src="dist/juzhen.iife.js"></script>
+<script>
+  Juzhen.createJuzhen({ scope: { include: ".prose" } }).render();
+</script>
+```
+
+JS 只注入 `jz-*` 結構，所有視覺尺寸在 juzhen.css，缺一不可。
+
+## 已實作功能
+
+- spacing 中西間隙（margin 模型，copy-clean；含 pill 與作者空格正規化）
+- longWord 長英文詞包裝（`<span lang>` + hyphens:auto）
+- jiya 標點擠壓（全角／開明／半角；半形 halt 預設、margin 後備）
+- jinze 禁則（避頭尾、justify 綁定）
+- justify 句末標點單份間距（jz-char inline-block 原子）
+
+## 標點半形：halt 預設與 margin 後備
+
+- halt（預設，`jiya: true`）：字型 OpenType halt 定位，需字型支援。
+- margin（`jiya: { halfWidth: "margin" }`）：width:0.5em＋字身依墨色偏側溢出定位，以 CSS 重現 halt；供缺 halt 字型（如方正書宋 GBK，僅含 vert）。
+- 模式由 `data-jz-halfwidth` 子樹屬性決定，可逐區塊／lang。
+- 偏側 inkBias 給 left/center/right/full，可 `jiya.bias` 逐 lang 逐字覆寫。
+
+### 字型適配工作流
+
+1. `python3 tools/measure-bias.py <font.ttf>` 驗 halt、量偏側。
+2. 有 halt → 用預設；無 halt → margin 後備＋偏側表。
+3. 套用 jiya.bias，瀏覽器目視微調（重疊→往不移；有隙→往多移）。
+
+## CSS 基礎設定
+
+引入 juzhen.css（必須）；設 lang；scope class；hyphens:auto；text-align:justify（選用）；含 halt 字型或 margin 後備。juzhen.css 之 Noto 字型堆疊僅作後備，消費端 font-family 恆優先。
+
+## 分頁器相容
+
+`justifyAtoms: false` → jz-char/jz-jinze 改 display:inline，相容 Paged.js。margin 後備與 justifyAtoms:false 不可兼得。
+
+## v1 相容
+
+`createCjkAutospace(opts).apply(root)` 經相容層映射至 createJuzhen，零改動可跑。
+
+MIT。借鑑 Han.css／Heti 思路與分類表，成品自含。
+</script>
+
+<!-- RUNTIME_JS -->
+
+</body>
+</html>