agentcss 0.24.2 → 0.25.0

package/ai/components.meta.json

@@ -15,175 +15,392 @@
     "$whyFourth": "🔴 为什么 M8 要加第四条（0.7.6）：只用前三条时 27 个组件**全是 stable** ⇒ ladder 没有任何鉴别力（对标 Primer 六档阶梯，每档都有硬判据）。补上行为欠账这一条后：stable 20 / beta 7。",
     "$strictImpact": "⚠️ strict 档位只放行 stable ⇒ 这 7 个组件在 strict 下不可用（accordion / combobox / drawer / dropdown / overlay / select / tooltip）。这是**有意的**：它们的行为还有手写副本或缺一个该有的行为。要用就切 standard 档。"
   },
+  "printDefaults": {
+    "$comment": "库级打印约定：不属于任何组件，只由 01-tokens/tokens.css 的 @media print 兑现。policy 取值与组件相同（见 components.schema.json 的 printRule）。",
+    "rules": [
+      {
+        "selector": ".no-print",
+        "policy": "omit",
+        "why": "使用者显式排除操作区；全库唯一的 !important"
+      },
+      {
+        "selector": ".print-only",
+        "policy": "reveal",
+        "why": "只在纸上出现（打印版标题 / 落款 / 水印）"
+      },
+      {
+        "selector": "tr",
+        "policy": "keep-together",
+        "why": "切开的表行在下一页没有表头，读不出来"
+      },
+      {
+        "selector": "img",
+        "policy": "keep-together",
+        "why": "图片切一半等于没有这张图"
+      },
+      {
+        "selector": "figure",
+        "policy": "keep-together",
+        "why": "图与图注是一个整体"
+      },
+      {
+        "selector": "svg",
+        "policy": "keep-together",
+        "why": "图表都是 svg；切开后右半页是空白"
+      },
+      {
+        "selector": ".print-allow-break",
+        "policy": "allow-break",
+        "why": "退出开关：高块想省纸就加它（520px 块实测 −48% 页）"
+      }
+    ]
+  },
   "components": {
     "accordion": {
       "rootClass": "accordion",
-      "purpose": "可折叠分组"
+      "purpose": "可折叠分组",
+      "printPolicy": [
+        {
+          "selector": ".accordion .accordion__panel[hidden]",
+          "policy": "expand",
+          "why": "收起的面板也要展开；display / 行轨道 / visibility 三条缺一就一个字不印"
+        },
+        {
+          "selector": ".accordion__marker",
+          "policy": "omit",
+          "why": "展开箭头是交互提示；只藏箭头，不藏标题"
+        }
+      ]
     },
     "analysis-report": {
       "rootClass": "report",
       "tier": "recipe",
-      "purpose": "组合型研究报告页面：正文与辅助栏并排，窄屏自然退回单栏"
+      "purpose": "组合型研究报告页面：正文与辅助栏并排，窄屏自然退回单栏",
+      "printPolicy": [
+        {
+          "selector": ".report__aside",
+          "policy": "expand",
+          "why": "屏幕 sticky + 限高 + 可滚；不放开就只印可视区那几行"
+        }
+      ]
     },
     "app-shell": {
       "rootClass": "shell",
       "tier": "recipe",
-      "purpose": "应用外壳：侧栏 + 顶栏 + 主区三段式；sticky 侧栏自滚、min-width 防撑破、窄屏收走侧栏"
+      "purpose": "应用外壳：侧栏 + 顶栏 + 主区三段式；sticky 侧栏自滚、min-width 防撑破、窄屏收走侧栏",
+      "printPolicy": []
     },
     "badge": {
       "rootClass": "badge",
-      "purpose": "状态标签：计数、分类、结果标记"
+      "purpose": "状态标签：计数、分类、结果标记",
+      "printPolicy": []
     },
     "bar": {
       "rootClass": "bar",
       "tier": "asset",
-      "purpose": "柱状图：堆叠/分组两种语义、超量程裁剪、图例"
+      "purpose": "柱状图：堆叠/分组两种语义、超量程裁剪、图例",
+      "printPolicy": []
     },
     "button": {
       "rootClass": "btn",
-      "purpose": "动作触发：主/次/危险/纯文字四档"
+      "purpose": "动作触发：主/次/危险/纯文字四档",
+      "printPolicy": []
     },
     "card": {
       "rootClass": "card",
-      "purpose": "内容容器：媒体+正文+操作区三段"
+      "purpose": "内容容器：媒体+正文+操作区三段",
+      "printPolicy": [
+        {
+          "selector": ".card",
+          "policy": "keep-together",
+          "why": "切开后下半张没有标题"
+        }
+      ]
     },
     "choice": {
       "rootClass": "choice",
-      "purpose": "单选/多选/原生 select 外观的统一控件"
+      "purpose": "单选/多选/原生 select 外观的统一控件",
+      "printPolicy": []
     },
     "combobox": {
       "rootClass": "combo",
-      "purpose": "可搜索 + 可多选标签的输入控件"
+      "purpose": "可搜索 + 可多选标签的输入控件",
+      "printPolicy": []
     },
     "content": {
       "rootClass": "prose",
-      "purpose": "长文排版容器（标题/段落/列表/引用/代码）"
+      "purpose": "长文排版容器（标题/段落/列表/引用/代码）",
+      "printPolicy": []
     },
     "date-range": {
       "rootClass": "drange",
-      "purpose": "日期区间选择，含预设快捷范围"
+      "purpose": "日期区间选择，含预设快捷范围",
+      "printPolicy": []
     },
     "delta": {
       "rootClass": "delta",
-      "purpose": "变化量：涨跌方向 + 符号 + 颜色。只描述往哪边变，不判断好坏（等于好恶是 badge 的事，会计正负是 table 的事）"
+      "purpose": "变化量：涨跌方向 + 符号 + 颜色。只描述往哪边变，不判断好坏（等于好恶是 badge 的事，会计正负是 table 的事）",
+      "printPolicy": []
     },
     "drawer": {
       "rootClass": "drawer",
-      "purpose": "侧边抽屉，含遮罩"
+      "purpose": "侧边抽屉，含遮罩",
+      "printPolicy": []
     },
     "dropdown": {
       "rootClass": "dd",
-      "purpose": "下拉菜单"
+      "purpose": "下拉菜单",
+      "printPolicy": []
     },
     "form-validation": {
       "rootClass": "form",
-      "purpose": "表单校验反馈与错误汇总"
+      "purpose": "表单校验反馈与错误汇总",
+      "printPolicy": []
     },
     "input": {
       "rootClass": "field",
-      "purpose": "文本输入及其标签/帮助/错误三件套"
+      "purpose": "文本输入及其标签/帮助/错误三件套",
+      "printPolicy": []
     },
     "list": {
       "rootClass": "list",
-      "purpose": "键值列表/条目列表"
+      "purpose": "键值列表/条目列表",
+      "printPolicy": []
     },
     "model-viewer": {
       "rootClass": "mv",
       "tier": "asset",
-      "purpose": "3D 模型查看器：令牌驱动样式，不含渲染库本体"
+      "purpose": "3D 模型查看器：令牌驱动样式，不含渲染库本体",
+      "printPolicy": [
+        {
+          "selector": ".mv__btn",
+          "policy": "omit",
+          "why": "「加载 3D 模型」按钮由 JS 生成，纸上点了没反应"
+        },
+        {
+          "selector": ".mv__hint",
+          "policy": "omit",
+          "why": "拖拽旋转的操作提示在纸上不成立"
+        }
+      ]
     },
     "metric": {
       "rootClass": "metric",
-      "purpose": "指标块：一个标签 + 一个值 + 一句上下文。数字等宽、单位分离、缺数是一等状态"
+      "purpose": "指标块：一个标签 + 一个值 + 一句上下文。数字等宽、单位分离、缺数是一等状态",
+      "printPolicy": [
+        {
+          "selector": ".metric",
+          "policy": "keep-together",
+          "why": "数字、单位、标签是一个整体，切开就分家"
+        }
+      ]
     },
     "nav": {
       "rootClass": "nav",
-      "purpose": "顶部导航与目录"
+      "purpose": "顶部导航与目录",
+      "printPolicy": [
+        {
+          "selector": ".nav__list",
+          "policy": "omit",
+          "why": "导航链接是纯导航；不藏 .nav__brand（可能是标题）"
+        },
+        {
+          "selector": ".nav__toggle",
+          "policy": "omit",
+          "why": "汉堡按钮只在窄屏交互中存在"
+        }
+      ]
     },
     "overlay": {
       "rootClass": "toast",
-      "purpose": "吐司提示与模态遮罩"
+      "purpose": "吐司提示与模态遮罩",
+      "printPolicy": [
+        {
+          "selector": ".toast",
+          "policy": "omit",
+          "why": "通知是瞬时反馈，纸上没有对应物"
+        },
+        {
+          "selector": ".dialog-backdrop",
+          "policy": "expand",
+          "why": "fixed 半透明遮罩印出来盖满整页；拉回流式而不是隐藏（隐藏会吞掉弹窗内容）"
+        },
+        {
+          "selector": ".dialog",
+          "policy": "expand",
+          "why": "弹窗自己限高 100vh 且可滚；纸上不限高，否则只印可视区那几行"
+        }
+      ]
     },
     "pagination": {
       "rootClass": "pagination",
-      "purpose": "分页控件"
+      "purpose": "分页控件",
+      "printPolicy": [
+        {
+          "selector": ".pagination",
+          "policy": "omit",
+          "why": "纸上翻不了页；印出来只会让人以为还有下一页"
+        }
+      ]
     },
     "popover": {
       "rootClass": "popover",
-      "purpose": "锚定到触发元素的浮层"
+      "purpose": "锚定到触发元素的浮层",
+      "printPolicy": [
+        {
+          "selector": ".popover",
+          "policy": "omit",
+          "why": "同 tooltip；且 position:fixed 会盖住正文"
+        }
+      ]
     },
     "progress": {
       "rootClass": "progress",
-      "purpose": "进度条与进度环"
+      "purpose": "进度条与进度环",
+      "printPolicy": []
     },
     "report": {
       "rootClass": "rep",
       "tier": "recipe",
-      "purpose": "报告版式系统 v1：共享基础 + 三套版式（杂志/科研技术/金融研究），只换一个 rep--* 类即可切换取舍"
+      "purpose": "报告版式系统 v1：共享基础 + 三套版式（杂志/科研技术/金融研究），只换一个 rep--* 类即可切换取舍",
+      "printPolicy": [
+        {
+          "selector": ".rep__aside",
+          "policy": "omit",
+          "why": "边注是并排布局的产物；纸上没有第二栏，留着会被挤成 12em 一行"
+        },
+        {
+          "selector": ".rep__fig",
+          "policy": "keep-together",
+          "why": "图与图注同页；高于一整页时 avoid 会被静默忽略"
+        },
+        {
+          "selector": ".rep table",
+          "policy": "keep-together",
+          "why": "表格不从行中断；跨页表头由 HTML 默认重复"
+        }
+      ]
     },
     "scientific-plot": {
       "rootClass": "splot",
       "tier": "asset",
-      "purpose": "二维科学绘图：折线/区间带/对数轴，纯令牌驱动、零依赖"
+      "purpose": "二维科学绘图：折线/区间带/对数轴，纯令牌驱动、零依赖",
+      "printPolicy": [
+        {
+          "selector": ".splot",
+          "policy": "keep-together",
+          "why": "图、坐标轴、图例必须同页"
+        }
+      ]
     },
     "select": {
       "rootClass": "select",
-      "purpose": "自定义下拉选择（非原生）"
+      "purpose": "自定义下拉选择（非原生）",
+      "printPolicy": []
     },
     "timeline": {
       "rootClass": "timeline",
-      "purpose": "时间轴：按时间排的事件序列（公告 / 大事记 / 版本记录）。顺序即信息，用 ol；状态交给 badge，颜色在这里会失效"
+      "purpose": "时间轴：按时间排的事件序列（公告 / 大事记 / 版本记录）。顺序即信息，用 ol；状态交给 badge，颜色在这里会失效",
+      "printPolicy": []
     },
     "separator": {
       "rootClass": "separator",
-      "purpose": "分隔线，可带中间文字"
+      "purpose": "分隔线，可带中间文字",
+      "printPolicy": []
     },
     "skeleton": {
       "rootClass": "skeleton",
-      "purpose": "加载占位骨架"
+      "purpose": "加载占位骨架",
+      "printPolicy": [
+        {
+          "selector": ".skeleton",
+          "policy": "omit",
+          "why": "加载占位符；纸上永远是「还没加载完」的假象"
+        }
+      ]
     },
     "sparkline": {
       "rootClass": "sparkline",
       "tier": "asset",
-      "purpose": "迷你趋势图：无坐标轴、纯形状，适合表格内嵌的一行走势"
+      "purpose": "迷你趋势图：无坐标轴、纯形状，适合表格内嵌的一行走势",
+      "printPolicy": [
+        {
+          "selector": ".sparkline",
+          "policy": "keep-together",
+          "why": "趋势线切开就是两条断线"
+        }
+      ]
     },
     "states": {
       "rootClass": "state",
-      "purpose": "空/加载/错误/成功四种整块状态"
+      "purpose": "空/加载/错误/成功四种整块状态",
+      "printPolicy": []
     },
     "switch": {
       "rootClass": "switch",
-      "purpose": "开关切换"
+      "purpose": "开关切换",
+      "printPolicy": []
     },
     "upload": {
       "rootClass": "upload",
-      "purpose": "文件上传：零 JS 的原生形态 + 拖放/多文件/校验的增强形态"
+      "purpose": "文件上传：零 JS 的原生形态 + 拖放/多文件/校验的增强形态",
+      "printPolicy": []
     },
     "table": {
       "rootClass": "table",
       "tier": "recipe",
-      "purpose": "数据表格：排序/加载/空/错误四态；三种用途预设（财务/学术/统计）"
+      "purpose": "数据表格：排序/加载/空/错误四态；三种用途预设（财务/学术/统计）",
+      "printPolicy": [
+        {
+          "selector": ".table",
+          "policy": "expand",
+          "why": "屏幕是横向滚动容器（70vh 限高）；不放开只印可视区，最经典的静默截断"
+        }
+      ],
+      "pagination": "client"
     },
     "tabs": {
       "rootClass": "tabs",
-      "purpose": "选项卡切换"
+      "purpose": "选项卡切换",
+      "printPolicy": [
+        {
+          "selector": ".tabs .tabs__panel[hidden]",
+          "policy": "expand",
+          "why": "不展开就只印第一个 tab（实测少印 68% 字）；前缀丢了这个规则等于没写"
+        },
+        {
+          "selector": ".tabs__list",
+          "policy": "omit",
+          "why": "标签栏是导航；只藏它，面板是内容"
+        }
+      ]
     },
     "reveal": {
       "rootClass": "reveal",
-      "purpose": "入场动效：一个 data-reveal 属性六个方向，无 JS 时内容全可见"
+      "purpose": "入场动效：一个 data-reveal 属性六个方向，无 JS 时内容全可见",
+      "printPolicy": []
     },
     "tooltip": {
       "rootClass": "tooltip",
-      "purpose": "悬停/聚焦提示"
+      "purpose": "悬停/聚焦提示",
+      "printPolicy": [
+        {
+          "selector": ".tooltip",
+          "policy": "omit",
+          "why": "气泡靠 hover 出现，纸上没有 hover"
+        }
+      ]
     },
     "tree": {
       "rootClass": "tree",
-      "purpose": "可展开树形结构"
+      "purpose": "可展开树形结构",
+      "printPolicy": []
     },
     "detail-page": {
       "rootClass": "detail-page",
       "tier": "recipe",
-      "purpose": "实体详情页骨架：字段齐全 / 部分缺失 / 无数据三种状态同构，无数据是一等状态"
+      "purpose": "实体详情页骨架：字段齐全 / 部分缺失 / 无数据三种状态同构，无数据是一等状态",
+      "printPolicy": []
     }
   }
 }

package/ai/components.schema.json

@@ -28,6 +28,24 @@
     "maturityCriteria": {
       "type": "object"
     },
+    "printDefaults": {
+      "type": "object",
+      "required": [
+        "rules"
+      ],
+      "properties": {
+        "rules": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/printRule"
+          }
+        },
+        "$comment": {
+          "type": "string"
+        }
+      },
+      "$comment": "库级打印约定：不属于任何组件，只由 01-tokens/tokens.css 兑现（.no-print / tr / img 这些）。"
+    },
     "summary": {
       "type": "object"
     },
@@ -213,6 +231,84 @@
         },
         "behaviorRef": {
           "type": "string"
+        },
+        "pagination": {
+          "type": "string",
+          "enum": [
+            "none",
+            "client",
+            "server"
+          ],
+          "$comment": [
+            "内容是否被分页裁过（缺省 = none）。",
+            "",
+            "🔴 server 不许与 printPolicy 里的 expand 同时出现：",
+            "   服务端分页时 DOM 里只有当前一页的行，展开它 = 印出一页却看起来完整。",
+            "   页数正常、对比度合格、内容少九成 —— 这是静默截断的教科书案例。",
+            "   由 gen-ai-contract.py 与 print-policy-gate.js 双向拦。"
+          ]
+        },
+        "printPolicy": {
+          "type": "array",
+          "items": {
+            "$ref": "#/definitions/printRule"
+          },
+          "$comment": [
+            "这个组件在纸上会发生什么。空数组 = 原样保留（**明确值**，不是漏填）。",
+            "",
+            "🔴 为什么是记录数组而不是一句话：",
+            "   一个组件可以同时有多种打印行为（tabs = 展开面板 + 隐藏标签栏）。",
+            "   写成单个枚举就必须撒谎，而撒谎的契约比没有契约更坏。"
+          ]
+        }
+      }
+    },
+    "printRule": {
+      "type": "object",
+      "required": [
+        "selector",
+        "policy",
+        "why"
+      ],
+      "additionalProperties": false,
+      "properties": {
+        "selector": {
+          "type": "string",
+          "$comment": [
+            "单个 CSS 选择器（不许逗号）。",
+            "",
+            "🔴 为什么必须是单个：一条记录只认领一条声明。",
+            "   带逗号的记录会让「谁有权改坏它」没有答案，",
+            "   而 print-policy-gate 的 L2（实现 → 声明）正是按这条线判的。"
+          ]
+        },
+        "policy": {
+          "type": "string",
+          "enum": [
+            "omit",
+            "expand",
+            "reveal",
+            "keep-together",
+            "allow-break"
+          ],
+          "$comment": [
+            "有限枚举。每个值对应一组**可在浏览器里量**的断言（print-policy-gate L3）：",
+            "  omit          → 打印态 display === none",
+            "  expand        → 打印态 display≠none、visibility≠hidden、position≠fixed、",
+            "                   max-height=none、overflow 不裁切、高度>0（有文本时）",
+            "  reveal        → 屏幕 display===none 且打印态 display≠none",
+            "  keep-together → break-inside === avoid",
+            "  allow-break   → break-inside === auto",
+            "",
+            "⚠️ 没有 omit-parts：隐藏粒度由 selector 自己说明",
+            "   （等于 rootClass ⇒ 整块；是 __ 部件 ⇒ 少一块）。",
+            "   两个名字指同一件事、判据一模一样，只会多一处争论。"
+          ]
+        },
+        "why": {
+          "type": "string",
+          "minLength": 8,
+          "$comment": "必须能回答「不这么做会怎样」。写不出来的策略，多半是不该有的策略。"
         }
       }
     }

package/ai/contract.schema.json

@@ -52,6 +52,17 @@
       ],
       "$comment": "详见 ai/profiles.json。三档决定『允许多不成熟的东西进入文档』。"
     },
+    "pageBudget": {
+      "type": "integer",
+      "minimum": 1,
+      "$comment": [
+        "页数上限（建议值）。只在 paper 介质下必填 —— screen 介质里它是多余的字。",
+        "🔴 没有默认值：页数取决于内容，任何全局默认都是猜的。",
+        "   猜一个数比不写更坏：它会让『这份报告该印几页』变成一个没人负责的数字。",
+        "语义是**报错**，不是警告：超了要停下来给出路（拆文档 / 进附录 / 自己删），",
+        "   而不是悄悄印出 40 页。导出时对应 `agentcss pdf --max-pages=N`。"
+      ]
+    },
     "capabilities": {
       "$ref": "#/definitions/capabilities",
       "$comment": [

package/ai/pdf-pages.js

@@ -0,0 +1,79 @@
+/*
+ * pdf-pages.js — 从 PDF 字节里读页数与纸幅。零依赖、不联网。
+ *
+ * ============================================================================
+ * 🔴 为什么要有这个文件（而不是各写一份）
+ * ============================================================================
+ * 现在有两个地方要回答"这份 PDF 几页"：
+ *   · `05-audit/print-gate.js` —— 判分页有没有被改坏
+ *   · `ai/pdf.js`             —— 判导出产物有没有超出 `--max-pages`
+ *
+ * 各写一份的代价不是"多几行"，而是**两个数会在某次改动后不一致，且没人发现**：
+ * 门禁说 7 页、导出器说 8 页，两边各自"通过"。同一个判定写两遍必然漂移（E31）。
+ *
+ * ============================================================================
+ * ⚠️ 两种读法，必须一致
+ * ============================================================================
+ *   ① 数 `/Type /Page` 对象     —— Chromium 每页一个，直方图式可靠
+ *   ② 读页树根 `/Count`         —— 语义上的权威值
+ *
+ * 不一致意味着"这个文件长了两套说法"，此时**不能挑一个继续**：
+ * 预算判错的代价是"多印 40 页纸，而工具说通过"。
+ * 所以 `inspect()` 把两个值都返回，由调用方决定：
+ *   · 门禁（判分页变化）用 ①（历史基线就是按 ① 录的）
+ *   · 导出器（判预算）要求 ①② 一致，不一致就报错退出
+ *
+ * ⚠️ 本解析器**只认**未压缩的对象表。Chromium 的产物实测 679 个对象、0 个
+ *    `/Type /ObjStm`；若将来出现对象流，①② 会同时偏小 —— 这一条写在这里，
+ *    是为了让"某天页数突然变 0"能被想到，而不是当成新 bug 查一整天。
+ */
+'use strict';
+
+/** 数 `/Type /Page` 对象。正则与 print-gate 历史实现**逐字相同**（基线按它录的）。 */
+function countPageObjects(raw) {
+  return (raw.match(/\/Type\s*\/Page[^s]/g) || []).length;
+}
+
+/** 页树根声明的 `/Count`（取第一个；没有则 null）。 */
+function countFromTree(raw) {
+  const m = /\/Count\s+(\d+)/.exec(raw);
+  return m ? +m[1] : null;
+}
+
+/** 第一张纸的 `/MediaBox [x0 y0 x1 y1]` → `{width, height}`（pt，1/72 英寸）。 */
+function mediaBox(raw) {
+  const m = /\/MediaBox\s*\[\s*([-\d.]+)\s+([-\d.]+)\s+([-\d.]+)\s+([-\d.]+)\s*\]/.exec(raw);
+  if (!m) return null;
+  const x0 = +m[1];
+  const y0 = +m[2];
+  const x1 = +m[3];
+  const y1 = +m[4];
+  return {
+    width: Math.round((x1 - x0) * 100) / 100,
+    height: Math.round((y1 - y0) * 100) / 100,
+  };
+}
+
+/**
+ * @param {Buffer|String} raw PDF 字节（String 时按 latin1 处理）
+ * @returns {{pages:number, countFromTree:number|null, agree:boolean, mediaBox:object|null}}
+ */
+function inspect(raw) {
+  const s = Buffer.isBuffer(raw) ? raw.toString('latin1') : String(raw);
+  const pages = countPageObjects(s);
+  const tree = countFromTree(s);
+  return {
+    pages,
+    countFromTree: tree,
+    /* 没有 /Count 时不算分歧（有的生成器省它）；有就必须相等 */
+    agree: tree === null || tree === pages,
+    mediaBox: mediaBox(s),
+  };
+}
+
+/** 只要页数。等价于 `inspect(buf).pages`，给"只关心页数"的调用方用。 */
+function countPages(raw) {
+  return inspect(raw).pages;
+}
+
+module.exports = { inspect, countPages, countPageObjects, countFromTree, mediaBox };