ADR-0044：固定页区字体角色的上下文传递

• 状态：接受
• 日期：2026-10-16
• 范围：GAP-04 的固定页区角色传递、布局入口快照与兼容边界
• 关联：使用指南

背景

DocumentEngine 已保存显式字体角色，正文及语义组件也能使用 ComponentContext.fontRoles。固定页区由 ComponentDocumentRenderer 在最终分页后交给 PageComposer 合成。原调用只传入默认字体组，后者创建不含角色的兼容上下文，导致页眉、页脚、背景和前景无法取得引擎注册的角色。

这个丢失点位于上下文传递。正文编写时的 DocumentTheme 保存模型默认值，不能替代固定组件的字体上下文。直接新增主题属性、把文字转换为语义表格，或在页区重新解析字段，都会扩大本次范围并绕开现有约束。

决策

在布局核心的 PageComposer 增加下列入口，返回类型继续为 PageComposition：

composeDetailed(DisplayDocument body, List<PageSpec> specs,
        FontGroup fonts, Map<String, FontGroup> roles)

新入口在任何 placement 回调执行前，以 List.copyOf 和 Map.copyOf 固定规格与角色。map、key、value 的 null 沿用 JDK 不可变快照校验，空映射合法；不增加角色名称规则。字体组和字体资源仍由调用方借出，不关闭资源，不扫描系统字体，不引入隐式 I/O。

四类页区的 place 都传递同一映射，以现有七参数 ComponentContext 创建上下文。该构造器保留兼容的文字默认值；本次不改变字号、行距、颜色或继承规则。物理页索引、最终物理总页数和最终显示页号继续按已解析的 PageSpec 传入。

ComponentDocumentRenderer 的主六参数布局入口一开始就取得角色快照。正文、最终字段和最终页区由此使用同一组角色；不能等正文回调结束后才复制 map，否则回调修改调用方集合会造成同一布局中的字体不一致。DocumentEngine 已有构建时快照，无须建立新的引擎状态。

旧三参数 composeDetailed(body, specs, FontGroup) 委托 Map.of()。旧 List<FontFace> 重载和 compose 调用链保持空角色。原调用方无须添加参数，旧默认绘制与诊断通过精确行为对照检查。需要角色的低层调用使用新四参数入口，不从全局状态或字体文件名称推断角色。

组件使用与现有作用域

标准 TextComponent 尚无 fontRole setter。需要品牌字体的可信自定义组件，从 context.fontRoles() 读取显式名称，再以 context.withFonts(selected) 委托 TextComponent。未注册名称由自定义组件明确拒绝；合成器只负责保存和传递映射，不替组件决定角色选择或回退顺序。

FontScope 继续替换默认字体组，StyleScope 继续修改未声明文字属性的默认值；两者保留角色映射与最终页上下文。角色组自身的缺字策略保持，不能暗中改用正文默认组策略。警告继续保留原文 UTF-16、实际字体和最终页区来源，不新增库内部日志。

字体组与标准组件可以在其自身线程安全契约内复用；自定义组件仍需独立声明线程安全。入口快照不等于允许在复制过程中并发修改非线程安全调用方集合，也不使可变字体实现自动变得线程安全。没有新增缓存、后台线程或文档级共享可变状态。

固定页区边界

页眉、页脚的最大预留、目录前置页、分节首页／奇偶选择和最终字段解析时点保持。背景和前景仍按页矩形定位，页带仍按各自固定区域定位。后端只绘制已有指令，不重新换行、分页或选择字体。

固定调用继续要求一个完整片段。多片段 PageableComponent 明确拒绝，不能自行增加页面。含待解析语义的 SemanticTable 在固定页区仍因 commands() 不可用而失败；TableComponent 对字段、外链和具名字体角色的限制保持。不能把角色上下文修复标记为语义页区完成。

本单元不新增完整页区主题、标准组件角色 setter、XML 页区声明、全局角色级联、页区语义流或 DOCX 页眉页脚映射。不新增模块、依赖或字体资源，不改变包名和制品坐标。GAP-04 仍按已有子集保持部分支持。

验证要求

• 使用可信委托组件读取角色并输出实际字体，分别验证页眉、页脚、背景和前景；正文默认字体保持独立。
• 验证目录偏移、分节重启和首页／奇偶页模板下的最终物理索引、总页数和显示页号。
• 验证 FontScope／StyleScope 的两种嵌套顺序、角色缺字策略、原文 UTF-16 警告和最终页区诊断。
• 在同步正文或页区回调中修改调用方原 map，证明入口快照固定；验证映射不可修改和独立引擎的并发隔离。
• 对照全部旧合成重载的空角色和完整绘制；null map／key／value 在回调前失败；固定多片段和语义插槽拒绝保持。
• 仓库样例和隔离调用方分别生成固定页区文件，独立检查物理字体、颜色、位置、预留区域和最终页号；全部新增页双渲染并逐页查看。

实现与测试位置见使用指南。本记录定义决策和验收门槛，构建、独立验证及未验证范围由阶段验收记录登记。