feat: 功能分級（文本級 vs 段落級）＋ data-jz-level 標記（§6.5.0a）

整體計劃 §6.5 之前置基礎設施。把已實作功能切為兩級：
- 文本級（spacing 中西間隙、jiya 標點擠壓／鄰接）：任意文本片段皆適用。
- 段落級（jinze 禁則、longWord 斷詞、lineEdge 行端、gapTrim）：需行／段布局。

標記 API：
- 預設塊級元素 → 段落級（全功能）。
- 元素屬性 data-jz-level="text"｜"paragraph"（最近祖先勝）。
- 選項 level:{ text: "選擇器" }（如標題／按鈕一鍵降為文本級）。

實作：
- 每個 pass 加 level 元數據；Finder.levelFor／levelAllows（含快取）。
- charify 段落級 pass（longWord）於共享走訪受閘；standalone 段落級 pass
  （jinze／lineEdge／gapTrim）逐元素受閘。文本級不受限。
- spacing 補單元素 root 支援：root 為行內／單一非塊元素時亦處理（標題等
  之中西間隙、標點半形生效）。

6 項新單元測試（text-level 跳段落級、選擇器標記、巢狀最近勝、單元素 spacing、
預設段落級回歸）。共 76 測試全綠。

src/core/finder.ts

@@ -4,7 +4,7 @@
 // 行內元素透明、pill／block／avoid 中斷）、pill 鄰字查找、per-node 功能閘
 // （featureEnabledFor）。finder 不知具體排版規則，只提供遍歷與安全變更原語。
 
-import type { ResolvedOptions } from "../types.js";
+import type { FeatureLevel, ResolvedOptions } from "../types.js";
 
 /** 邏輯 run 中之單一字元來源位置。 */
 export interface CharPos
@@ -41,7 +41,9 @@ export class Finder
     private readonly includeSelector: string | null;
     private readonly skipAttr: string | null;
     private readonly userIsSkipped: ((node: Node) => boolean) | null;
+    private readonly levelTextSelector: string | null;
     private readonly featureCache: WeakMap<Element, Record<string, boolean>>;
+    private readonly levelCache: WeakMap<Element, FeatureLevel>;
 
     constructor(opts: ResolvedOptions)
     {
@@ -52,9 +54,11 @@ export class Finder
         this.pillSelector = opts.finder.pillSelector;
         this.skipAttr = opts.finder.skipAttribute;
         this.userIsSkipped = opts.finder.isSkipped;
+        this.levelTextSelector = opts.levelText;
         this.avoidSelector = opts.scope.avoid;
         this.includeSelector = opts.scope.include;
         this.featureCache = new WeakMap();
+        this.levelCache = new WeakMap();
     }
 
     /** 該元素是否匹配 pill 選擇器（行內塊，如 code/kbd）。 */
@@ -278,6 +282,46 @@ export class Finder
         }
     }
 
+    /**
+     * 節點之功能級別（§6.5.0a）。自 node 向上找**最近**之顯式信號：元素屬性
+     * `data-jz-level="text|paragraph"`（最優先），或命中 `level.text` 選擇器（→ text）；
+     * 皆無則預設 paragraph（全功能）。結果以解析後之元素為鍵快取。
+     */
+    levelFor(node: Node): FeatureLevel
+    {
+        const start = node.nodeType === 1 ? (node as Element) : node.parentElement;
+        if (!start) { return "paragraph"; }
+        const cached = this.levelCache.get(start);
+        if (cached) { return cached; }
+
+        let el: Element | null = start;
+        let result: FeatureLevel = "paragraph";
+        while (el)
+        {
+            const attr = el.getAttribute ? el.getAttribute("data-jz-level") : null;
+            if (attr === "text" || attr === "paragraph") { result = attr; break; }
+            if (this.levelTextSelector && el.matches && el.matches(this.levelTextSelector))
+            {
+                result = "text";
+                break;
+            }
+            el = el.parentElement;
+        }
+        this.levelCache.set(start, result);
+        return result;
+    }
+
+    /**
+     * 某級別之 pass 是否可作用於該節點（§6.5.0a gate）。文本級 pass 不受限（恆 true）；
+     * 段落級 pass 僅作用於段落級元素（text-level 子樹跳過）。與 featureEnabledFor 疊加：
+     * level 為粗粒度語義組（先判），blocks／屬性為細粒度逐功能（後調）。
+     */
+    levelAllows(node: Node, passLevel: FeatureLevel): boolean
+    {
+        if (passLevel === "text") { return true; }
+        return this.levelFor(node) === "paragraph";
+    }
+
     /**
      * 解析節點對某功能之有效啟用狀態（§3.6，per-node 閘）。向上找最近帶
      * 功能指令之祖先（data-juzhen 白名單 / data-juzhen-off 黑名單 / 命中

src/core/pass.ts

@@ -49,6 +49,9 @@ function runCharify(passes: CharifyPass[], ctx: RenderContext): void
         let requests: WrapRequest[] = [];
         for (const p of passes)
         {
+            // 功能分級閘（§6.5.0a）：段落級 charify pass（如 longWord）對 text-level
+            // 子樹跳過；文本級（如 jiya）不受限。
+            if (!ctx.finder.levelAllows(node, p.level)) { continue; }
             const got = p.collect(node, ctx);
             if (got.length > 0) { requests = requests.concat(got); }
         }

src/index.ts

@@ -86,6 +86,7 @@ export function normalizeOptions(opts: JuzhenOptions = {}): ResolvedOptions
         ruleset: resolveRuleset(opts.charClass),
         autospaceClass: opts.autospaceClass || "",
         justifyAtoms: opts.justifyAtoms === false ? false : true,
+        levelText: (opts.level && opts.level.text) || null,
         scope: {
             root: scope.root || null,
             include: scope.include || null,

src/types.ts

@@ -50,6 +50,15 @@ export interface JuzhenOptions
      *  全寬標點各子類，以覆寫 spacing／jiya 等規則之分類判定（追加語義）。 */
     charClass?: CharClassOverride;
 
+    /** 功能分級標記（§6.5.0a）。段落級功能（禁則／行端／懸掛／垂懸字／長詞斷字）
+     *  僅作用於段落級元素；文本級功能（中西間隙／標點擠壓）任意文本皆適用。
+     *  - `text`：選擇器，命中之子樹**僅文本級**（標題／按鈕／UI 文字典型）；亦可
+     *    經元素屬性 `data-jz-level="text"`／`"paragraph"` 標記（屬性優先、最近祖先勝）。
+     *  預設：塊級元素（blockTags）→ 段落級（全功能）。 */
+    level?: {
+        text?: string;
+    };
+
     /** 間隙標記沿用之 class（v1 相容；預設無額外 class）。 */
     autospaceClass?: string;
 
@@ -96,6 +105,8 @@ export interface ResolvedOptions
     ruleset: Ruleset;
     autospaceClass: string;
     justifyAtoms: boolean;
+    /** 功能分級之 text-level 選擇器（§6.5.0a）；null 表示未設。 */
+    levelText: string | null;
     scope: {
         root: Element | string | null;
         include: string | null;
@@ -148,11 +159,16 @@ export interface WrapRequest
 /** pass 種類。 */
 export type PassKind = "charify" | "standalone";
 
+/** 功能分級（§6.5.0a）：text＝任意文本片段皆適用；paragraph＝需行／段布局。 */
+export type FeatureLevel = "text" | "paragraph";
+
 interface BasePass
 {
     name: string;
     order: number;
     kind: PassKind;
+    /** 功能分級（§6.5.0a）。paragraph 級 pass 對 text-level 元素自動跳過。 */
+    level: FeatureLevel;
     enabled: (options: ResolvedOptions) => boolean;
     revert: (ctx: RenderContext) => void;
 }

src/typeset/jinze.ts

@@ -143,6 +143,7 @@ export const jinzePass: StandalonePass = {
     name: PASS,
     kind: "standalone",
     order: 40,
+    level: "paragraph",
     enabled: (o) => o.features.jinze,
     render(ctx: RenderContext): void
     {
@@ -151,6 +152,8 @@ export const jinzePass: StandalonePass = {
         const parents = new Set<Node>();
         ctx.root.querySelectorAll("jz-char").forEach((c) =>
         {
+            // 功能分級閘（§6.5.0a）：禁則為段落級，text-level 子樹（標題／按鈕）跳過。
+            if (!ctx.finder.levelAllows(c, "paragraph")) { return; }
             if (c.parentNode) { parents.add(c.parentNode); }
         });
         for (const parent of parents) { processParent(parent, ctx.finder, anyCjk); }

src/typeset/jiya.ts

@@ -55,6 +55,7 @@ export const jiyaPass: CharifyPass = {
     name: PASS,
     kind: "charify",
     order: 20,
+    level: "text",
     enabled: (o) => o.features.jiya,
     collect(node, ctx): WrapRequest[]
     {
@@ -123,6 +124,7 @@ export const jiyaAdjacencyPass: StandalonePass = {
     name: "jiyaAdjacency",
     kind: "standalone",
     order: 25,
+    level: "text",
     enabled: (o) => o.features.jiya,
     render(ctx: RenderContext): void
     {

src/typeset/lineedge.ts

@@ -122,6 +122,8 @@ function relayout(root: Element, finder: Finder): void
 
     for (const el of chars)
     {
+        // 行端為段落級（§6.5.0a）：text-level 子樹（單行標題等）不收行端半形。
+        if (!finder.levelAllows(el, "paragraph")) { continue; }
         if (!finder.featureEnabledFor(el, "jiya")) { continue; }
         // 行端僅處理括號引號：開類於行首收左、閉類於行尾收右。
         // **不**處理句末／句內點號（。！？，等）——行尾／行首之點號保持全形，
@@ -149,6 +151,7 @@ export const lineEdgePass: StandalonePass = {
     name: "jiyaLineEdge",
     kind: "standalone",
     order: 90,
+    level: "paragraph",
     enabled: (o) => o.features.jiya,
     render(ctx: RenderContext): void
     {
@@ -174,7 +177,7 @@ const TRIM = "jz-hws-trim";
 function trimGaps(root: Element, finder: Finder): void
 {
     const gaps = Array.from(root.querySelectorAll("jz-hws")).filter(
-        (g) => finder.inScope(g) && !finder.isAvoided(g),
+        (g) => finder.inScope(g) && !finder.isAvoided(g) && finder.levelAllows(g, "paragraph"),
     );
     if (!gaps.length) { return; }
 
@@ -207,6 +210,7 @@ export const gapTrimPass: StandalonePass = {
     name: "spacingGapTrim",
     kind: "standalone",
     order: 92,
+    level: "paragraph",
     enabled: (o) => o.features.spacing,
     render(ctx: RenderContext): void
     {

src/typeset/longword.ts

@@ -23,6 +23,7 @@ export const longWordPass: CharifyPass = {
     name: PASS,
     kind: "charify",
     order: 60,
+    level: "paragraph",
     enabled: (o) => o.features.longWord,
     collect(node, ctx): WrapRequest[]
     {

src/typeset/spacing.ts

@@ -306,6 +306,7 @@ export const spacingPass: StandalonePass = {
     name: PASS,
     kind: "standalone",
     order: 50,
+    level: "text",
     enabled: (o) => o.features.spacing,
     render(ctx: RenderContext): void
     {
@@ -318,6 +319,15 @@ export const spacingPass: StandalonePass = {
             if (!finder.featureEnabledFor(block, PASS)) { return; }
             processBlock(block, finder, R);
         });
+        // 文本級功能須支持單元素（§6.5.0a）：root 為行內／單一非塊元素（如消費端對
+        // <span> 標題呼叫 render）時 eachBlock 不含之，補處理 root 自身（collectRuns
+        // 遇巢狀 block 仍會 flush，故與上面逐 block 不重複；行內 root 通常無 block 子）。
+        if (!options.finder.blockTags.has(ctx.root.nodeName)
+            && finder.featureEnabledFor(ctx.root, PASS)
+            && finder.inScope(ctx.root) && !finder.isAvoided(ctx.root))
+        {
+            processBlock(ctx.root, finder, R);
+        }
         // Pass B：pill 邊界。
         processPills(ctx.root, finder, options.finder.pillSelector, R.pillNeighbor);
     },