agentcss 0.24.0 → 0.24.2

package/01-tokens/focus-ring-demo.html

@@ -45,7 +45,7 @@ a { color: var(--accent); }
 .tip { font-size: var(--fs-xs); color: var(--text-tertiary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <div class="wrap">
 
   <h1>焦点环</h1>

package/01-tokens/page.css

@@ -197,6 +197,38 @@
   border-radius: var(--r-xs);
 }
 
+/* ============================================================================
+   4b. 代码块的兜底：任何 <pre> 自己横向滚，不许把页面撑宽
+   ----------------------------------------------------------------------------
+   🔴 为什么需要（0.24.1 实测，不是推演）
+     在 `.page` 环境里放一条 220 字符的长行：
+
+       裸 <pre>                    doc=2048 / vw=375   ❌ 撑破
+       <pre class="code">          doc=2211 / vw=375   ❌ 撑破   （没有 guide.css 时）
+       <div class="prose"><pre>    doc=2048 / vw=375   ❌ 撑破   （没有 content.css 时）
+
+     三种都是 `overflow-x: visible`、`white-space: pre`
+     ⇒ 长行直接顶到页面上，整页横向滚。
+
+     现有 84 个页面之所以没红，是因为每个 pre 恰好都另有来源：
+     `.prose > pre`（content.css）、`pre.code`（guide.css）。**但那是巧合，不是契约**
+     —— 使用者照 page.css 写一页文档、贴一段长代码，就会踩到。
+
+   🔴 为什么用 `:where(.page)` 而不是 `.page`
+     特异性压到 0,0,1（只算 `pre`）⇒ 任何带类的规则都能盖掉它：
+       `.prose > pre`  (0,1,1) 赢
+       `pre.code`      (0,1,1) 赢
+     这条的定位是**兜底**，不是"给所有 pre 定样式"。写成 `.page pre`（0,1,1）
+     会与上面两条**同权重**，胜负取决于加载顺序 —— 那就成了一个随时会翻的脸。
+
+   ⚠️ 只写 `overflow-x`，不写 padding / background / font：
+      那些是"代码块长什么样"，属于 content.css / guide.css 的决定。
+      这里只管"它不许撑破页面"。加了别的属性就会改动已有页面的观感。
+   ========================================================================= */
+:where(.page) pre {
+  overflow-x: auto;
+}
+
 /* ============================================================================
    5. 演示块 `.box`
    ----------------------------------------------------------------------------

package/01-tokens/responsive-demo.html

@@ -29,7 +29,7 @@ p { margin: 0 0 var(--sp-4); }
 .swatch { height: var(--sp-4); background: var(--accent); border-radius: 3px; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 
 <div id="meter">
   <span>视口 <b id="m-w">—</b></span>

package/01-tokens/scrollbar-demo.html

@@ -46,7 +46,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
                 border: 1px solid var(--border-control); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <div class="wrap">
 
   <h1>滚动条</h1>

package/02-primitives/badge/demo.html

@@ -15,7 +15,7 @@
          padding: var(--sp-4) 0; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>badge · 状态标记</h1>
   <p class="lede">

package/02-primitives/button/demo.html

@@ -24,7 +24,7 @@
 .btn--naive:disabled { opacity: 0.5; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>button · 七态矩阵</h1>

package/02-primitives/card/demo.html

@@ -26,7 +26,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
               var(--text-tertiary) 0 1px, transparent 1px 8px); opacity: .5; margin-bottom: var(--sp-2); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>card · hover 无布局跳动</h1>

package/02-primitives/choice/demo.html

@@ -30,7 +30,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
 .log { color: var(--text-tertiary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>checkbox / radio / select</h1>

package/02-primitives/combobox/demo.html

@@ -30,7 +30,7 @@ label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
 }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>combobox · 组合框 / 标签输入</h1>

package/02-primitives/date-range/demo.html

@@ -22,7 +22,7 @@
 .dr-bad-field .drange__input { border-color: var(--danger); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>date-range · 日期区间</h1>

package/02-primitives/delta/demo.html

@@ -30,7 +30,7 @@
                      color: var(--text-secondary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>delta · 变化量</h1>
   <p class="lede">

package/02-primitives/input/demo.html

@@ -29,7 +29,7 @@
 .bad-err { color: red; font-size: 13px; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>input · 五态矩阵</h1>

package/02-primitives/metric/demo.html

@@ -17,7 +17,7 @@
          padding: var(--sp-5); background: var(--surface); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>metric · 指标块</h1>
   <p class="lede">

package/02-primitives/popover/demo.html

@@ -44,7 +44,7 @@ th { font-weight: 600; }
 .pp-stage .popover__title { margin: 0; font-size: var(--fs-sm); font-weight: 500; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <!-- 🔴 0.8.9：axe 报 landmark-one-main（moderate）—— 本页原本没有任何 landmark 容器。
      加 <main> 是语义正确且不改布局的做法（<main> 默认不产生 box）。

package/02-primitives/progress/demo.html

@@ -27,7 +27,7 @@
 .pr-note { margin: var(--sp-2) 0 0; font-size: var(--fs-xs); color: var(--text-secondary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <!-- 🔴 0.8.9：axe 报 landmark-one-main（moderate）—— 本页原本没有任何 landmark 容器。
      加 <main> 是语义正确且不改布局的做法（<main> 默认不产生 box）。

package/02-primitives/select/demo.html

@@ -38,7 +38,7 @@ label.f { display: block; margin-bottom: var(--sp-1); font-size: var(--fs-sm); }
 }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>select · 下拉选择</h1>

package/02-primitives/separator/demo.html

@@ -13,7 +13,7 @@
 .row { padding: var(--sp-2) 0; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>separator · 分隔线</h1>
   <p class="lede">

package/02-primitives/skeleton/demo.html

@@ -28,7 +28,7 @@
 .sk-box { display: flex; flex-direction: column; gap: var(--sp-2); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <!-- 🔴 0.8.9：axe 报 landmark-one-main（moderate）—— 本页原本没有任何 landmark 容器。
      加 <main> 是语义正确且不改布局的做法（<main> 默认不产生 box）。

package/02-primitives/switch/demo.html

@@ -16,7 +16,7 @@
            color: var(--text-secondary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>switch · 开关</h1>
   <p class="lede">

package/02-primitives/timeline/demo.html

@@ -28,7 +28,7 @@
   }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>timeline · 时间轴</h1>
   <p class="lede">

package/03-patterns/accordion/demo.html

@@ -13,7 +13,7 @@
 p { margin: 0 0 var(--sp-3); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>accordion · 折叠面板</h1>
   <p class="lede">

package/03-patterns/content/demo.html

@@ -20,7 +20,7 @@
 .ct-p { margin: 0; font-size: var(--fs-sm); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 
 <main>
 <p class="demo-note">

package/03-patterns/drawer/demo.html

@@ -38,7 +38,7 @@ ul.demo-list li { margin: var(--sp-1) 0; }
 }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>drawer · 抽屉</h1>

package/03-patterns/dropdown/demo.html

@@ -35,7 +35,7 @@
 }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>dropdown · 下拉菜单</h1>

package/03-patterns/form-validation/demo.html

@@ -40,7 +40,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
      由 05-audit/css-imports.py 报出（它抓到过这个真问题） -->
 <link rel="stylesheet" href="../../02-primitives/button/button.css">
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>表单校验</h1>

package/03-patterns/list/demo.html

@@ -30,7 +30,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
 .cmp .ls-demo { max-width: 300px; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">">
 
   <h1>删掉一行，其余行不该瞬移</h1>

package/03-patterns/nav/demo.html

@@ -38,7 +38,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.7
 .toc-wrap { white-space: normal; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 
 <a class="skip" href="#main">跳到主内容</a>
 

package/03-patterns/overlay/demo.html

@@ -40,7 +40,7 @@ p.small { font-size: var(--fs-xs); color: var(--text-tertiary); line-height: 1.6
  }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>Toast vs Dialog</h1>

package/03-patterns/pagination/demo.html

@@ -33,7 +33,7 @@ th { font-size: var(--fs-xs); color: var(--text-secondary); font-weight: 500; }
 .pagination__list { flex-wrap: wrap; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>分页</h1>

package/03-patterns/states/demo.html

@@ -58,7 +58,7 @@ p.lead { color: var(--text-secondary); }
          margin-bottom: var(--sp-2); display: block; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>加载中和没有数据，是两件事</h1>

package/03-patterns/tabs/demo.html

@@ -15,7 +15,7 @@
          color: var(--text-secondary); min-height: 1.5em; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>tabs · 标签页</h1>
   <p class="lede">

package/03-patterns/tooltip/demo.html

@@ -21,7 +21,7 @@
 .tt-hint { margin: var(--sp-2) 0 0; font-size: var(--fs-xs); color: var(--text-tertiary); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>tooltip · 文字提示</h1>

package/03-patterns/tree/demo.html

@@ -30,7 +30,7 @@
           color: var(--text-tertiary); text-align: center; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>tree · 树形视图</h1>

package/04-recipes/app-shell/demo.html

@@ -151,8 +151,12 @@
     </header>
     <nav class="shell__side" aria-label="主导航（图标）">
       <!-- 品牌在 72px 里放不下名字 ⇒ 只留标记，名字视觉隐藏（不是删掉）。
-           标记与文字分成两段是**契约要求**，见 README「图标态的父级元素」。 -->
-      <a class="shell__brand" href="#">
+           标记与文字分成两段是**契约要求**，见 README「图标态的父级元素」。
+           ⚠️ `title` 在这里是**必要**的：rail 下只剩一个 20px 的图形，
+              鼠标用户没有别的线索知道它是什么。它只负责悬停提示 ——
+              名字仍然来自 `.shell__brand-text`（title 会兜出名字，
+              但 H2 判的是"文字是否被 display:none 掉"，不靠 title 兜）。 -->
+      <a class="shell__brand" href="#" title="金标准 · 财务台">
         <svg class="shell__brand-mark" viewBox="0 0 16 16" width="20" height="20" fill="none"
              stroke="currentColor" stroke-width="1.4" stroke-linejoin="round" aria-hidden="true"><path d="M8 1.6l5.4 3.1v6.6L8 14.4 2.6 11.3V4.7z"/></svg>
         <span class="shell__brand-text">金标准 · 财务台</span>

package/09-assets/bar/demo.html

@@ -19,7 +19,7 @@
   }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
 <h1>bar · 柱状图</h1>

package/09-assets/echarts-adapter/demo.html

@@ -33,7 +33,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
             vertical-align:middle; margin-right:4px; }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <div class="wrap">
   <h1>图表规范</h1>
   <p class="lede">

package/09-assets/model-viewer/demo.html

@@ -28,7 +28,7 @@ td.num { text-align: right; font-family: var(--mono); font-variant-numeric: tabu
 .ok { color: var(--success); }
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
 
   <h1>3D 模型查看器</h1>

package/09-assets/sparkline/demo.html

@@ -32,7 +32,7 @@
                     /* 🔴 但别小于 40 */
 </style>
 </head>
-<body class="page page">
+<body class="page">
 <main class="wrap">
   <h1>sparkline · 迷你趋势图</h1>
   <p class="lede">

package/AGENTS.md

@@ -1,6 +1,6 @@
 # agentcss — for coding agents
 
-- **Contract (machine-readable):** `ai/components.json` — 39 components with root class, slots, variants, states, ARIA and file paths. Query it; never guess class names.
+- **Contract (machine-readable):** `ai/components.json` — 40 components with root class, slots, variants, states, ARIA and file paths. Query it; never guess class names.
 - **Known failure modes:** `ai/pitfalls.json`, or `npx agentcss ai pitfalls --json --component=<id>`.
 - **Query:** `npx agentcss ai components --json [--maturity=stable]` · `ai tokens --json [--set=dark]` · `ai tree --json`.
 - **Validate:** `npx agentcss ai validate <file> --schema=components --json`. Every subcommand accepts `--json`; failures print `{"ok":false,…}` and exit non-zero.

package/CHANGELOG.md

@@ -16,6 +16,118 @@
 
 （无）
 
+## [0.24.2] - 2026-11-01
+
+**纯修订版：没有 CSS / JS / 类名 / 令牌的变更，下游不需要改任何代码。**
+改的是「发布出来的东西对不对」和「检查它们的手段对不对」。
+
+### 修复：`0.24.1` 的 npm 包里残留了旧数字
+
+`agentcss@0.24.1` 的 `llms-full.txt` 第 13 行写 `39 components`，
+同一文件第 24 行写 `Components (40)`；而站点上同路径文件已是 40。
+两个渠道同版本号、两份内容（sha256 不同）——
+原因是修复只重建了站点用的生成物，没有重新发版。
+
+这一版由当前源码重新生成后发布，两份内容一致。
+**不追溯修改历史版本**：`0.24.1` 在 registry 上保持原样，
+因为"已发布的版本不可变"比"历史看起来整齐"更重要。
+
+### 修复：`dist-fresh` 看不见产物改动
+
+`build-dist.py --check` 原先只比「源 sha 与 manifest 记录是否一致」。
+实测：给 `dist/01-tokens/tokens.css` 加一段注释、再把 `--sp-4` 的值改掉，
+`--check` 仍然打印 OK —— 而文档里写着「不要手改 dist，dist-fresh 会红」，
+等于一道不存在的保护。
+
+现在 `--check` 有两段判据：源 sha 一致 **且** 产物字节 == 生成器现算字节
+（干跑一遍、逐文件比、不写盘）。手改产物会报出从第几个字节开始不一样。
+发布路径同样受益：`npm run publish:check` 里就包含这道。
+
+### 修复：`md-render --check` 的表格判据比措辞窄
+
+文档写「表格必须是 `<table>`（不能是 div 模拟的）」，
+实现只有一句 `<div ... class="...table`。
+用 `class="grid"`、`role="table"`、或让 `<tr>` 跑出 `<table>` —— 三种都抓不到。
+
+现在拆成三条可独立关闭的规则（表格子元素越界 / ARIA 角色模拟 / class 含独立词 table），
+措辞同步收窄到"三种已知形态"，并写明"这是不是表格本身不可判定"。
+新增 `--selftest` 13 条，含三条元反向（关掉对应规则必须变绿）。
+
+### 发布治理
+
+- `docs/VERIFY-RELEASE.md`：怎么核验一个版本 —— npm `gitHead`、
+  attestation `subject` 与 registry `integrity` 的对应关系、Pages deployment 的 `sha`，
+  以及 L0–L3 证据分级（明确 L2「全量文件完整性」目前不存在）。
+- `docs/RELEASE-PROCESS.md`：生成链八个生成器的顺序、冻结点覆盖范围、
+  npm 链与站点链两条独立状态机、六种失败组合的恢复动作。
+- tag 从这一版起必须写成 `git tag -a vX.Y.Z -m "source-commit: <40 位>"`
+  ——`release-gate` 会验证它等于 tag 实际指向的提交，且该提交被远端分支包含。
+  `0.24.1` 及更早的 tag 没有该字段，走兼容判据。
+- 发布工作流先 `probe` 再发布：npm / GitHub Release 各自按已存在与否门控，
+  已存在的 npm 版本必须核 `provenance.gitCommit` 与 tag 指向一致，不一致判失败。
+  `dist` 的两道语义比对**无条件**执行，不与 npm 是否已存在共用跳过条件。
+
+---
+
+## [0.24.1] - 2026-10-31
+
+### `page.css` 补上 `<pre>` 的兜底（实测出来的，不是推演）
+
+在 `.page` 环境里放一条 220 字符的长行，实测三种写法：
+
+| 写法 | 结果 |
+|---|---|
+| 裸 `<pre>` | `doc=2048 / vw=375` ❌ 撑破 |
+| `<pre class="code">`（没有 guide.css 时） | `doc=2211 / vw=375` ❌ 撑破 |
+| `<div class="prose"><pre>`（没有 content.css 时） | `doc=2048 / vw=375` ❌ 撑破 |
+
+三种都是 `overflow-x: visible` + `white-space: pre` ⇒ 长行顶到页面上，整页横向滚。
+
+现有 84 个页面之所以没红，是因为每个 `<pre>` 恰好都另有来源
+（`.prose > pre` 在 content.css、`pre.code` 在 guide.css）—— **那是巧合，不是契约**。
+使用者照 `page.css` 写一页文档、贴一段长代码就会踩到。
+
+修法只有两行，关键是选择器：
+
+```css
+:where(.page) pre { overflow-x: auto; }
+```
+
+`:where()` 把特异性压到 `0,0,1`（只算 `pre`），任何带类的规则都能盖掉它 ——
+`.prose > pre` 与 `pre.code` 都是 `0,1,1`，稳赢。
+写成 `.page pre`（同权重）则会变成"胜负取决于加载顺序"的随时会翻的脸。
+
+只写 `overflow-x`，**不写** padding / background / font：那些是"代码块长什么样"，
+属于 content.css / guide.css 的决定；这里只管"它不许撑破页面"。
+实测确认：`.prose > pre` 的 `padding 16.3px` / 灰底 / `3px` 竖条 / 12px mono 一点没变，
+裸 `<pre>` 也没有因此获得任何"代码块外观"。
+
+### 图标态的品牌补上悬停提示
+
+rail 下品牌只剩一个 20px 图形，鼠标用户没有别的线索知道它是什么
+⇒ `demo` 的 `.shell__brand` 加 `title="金标准 · 财务台"`。
+
+⚠️ 它只负责悬停提示。名字仍然来自 `.shell__brand-text` —— `title` 会**兜出**名字，
+但 `H2` 判的是"文字是否被 `display: none` 掉"，不靠 `title` 兜，所以这条改动
+不会掩盖"把 brand-text 改成 display:none"的破坏。
+
+### 工程卫生：38 个页面写成了 `<body class="page page">`
+
+`class` 里同一个类写了两遍。浏览器匹配一次，渲染无差异，但它是手误的化石，
+而且会让人怀疑"是不是有两套 page 类"。
+
+全库排查：**没有任何生成器产生它**（`gen-docs.py` 里是 `class="page"`），
+也没有 CSS 选择器依赖双类（`.page.page` 零命中）、没有 JS 读 `className` 精确值
+—— 是纯手写遗留。38 个文件各 1 处，已全部改回 `class="page"`。
+
+### 版本同步
+
+这一版三处改动都**不改渲染**（`overflow-x` 对已有页面本就是 `auto`；
+`title` 不渲染；重复类名去掉后匹配结果不变），只改内容哈希。
+所以两平台视觉基线重录后应当逐字节不变 —— 变的只有 `_stamp.json` 里的指纹。
+
+---
+
 ## [0.24.0] - 2026-10-31
 
 ### 图标态：把"文档说的"和"示例做的"合回一份

package/CONTRIBUTING.md

@@ -29,7 +29,7 @@ npm run gate           # 全量：含浏览器类
 npm run gate:fast      # 只跑静态层，不用装浏览器
 ```
 
-全量是 **220 道门禁**（4 路并发实测约 9 分钟 / 退出码 0；单道耗时累加 1691 秒，
+全量是 **222 道门禁**（4 路并发实测约 9 分钟 / 退出码 0；单道耗时累加 1691 秒，
 组件层要起浏览器，还要逐张比 96 张视觉截图。0.11.15 起默认 4 路并发）。
 只想确认没改坏静态契约的话用 `gate:fast`，几秒到几分钟。
 

package/README.md

@@ -192,6 +192,8 @@ Three mistakes the template above already avoids:
 | `separator` | `separator` | Divider, optionally with centred text |
 | `skeleton` | `skeleton` | Loading placeholder |
 | `switch` | `switch` | Toggle switch |
+| `timeline` | `timeline` | Ordered event sequence: order is the information, so it is an `ol`; state belongs to `badge`, colour loses meaning here |
+| `upload` | `upload` | File upload: zero-JS native form, plus an enhanced form with drop, multiple files and validation |
 
 ### patterns (14)
 
@@ -217,6 +219,7 @@ Three mistakes the template above already avoids:
 | Component | Root class | Purpose |
 |---|---|---|
 | `analysis-report` | `report` | Research report page: body and side rail side by side, collapsing to one column |
+| `app-shell` | `shell` | App shell: sidebar, top bar, main area; sticky sidebar scrolls itself, folds away on narrow screens |
 | `detail-page` | `detail-page` | Entity detail skeleton: complete / partly missing / no records, three states sharing one DOM structure |
 | `report` | `rep` | Report layout system v1: shared base plus three layouts (magazine, scientific, financial research) |
 | `table` | `table` | Data table: sort / loading / empty / error states, three presets (financial, academic, statistical) |

package/README.zh-CN.md

@@ -85,9 +85,9 @@ npm install github:owain323/frontend-lib
 
 ## 组件一览
 
-共 **37** 个（stable 37 · 全部通过四条判据）。每个组件目录下有 `README.md`（为什么这么做）和 `demo.html`（能直接抄的结构）。
+共 **40** 个（stable 40 · 全部通过四条判据）。每个组件目录下有 `README.md`（为什么这么做）和 `demo.html`（能直接抄的结构）。
 
-### primitives · 基础件（15）
+### primitives · 基础件（17）
 
 | 组件 | 根类名 | 用途 |
 |---|---|---|
@@ -106,6 +106,8 @@ npm install github:owain323/frontend-lib
 | `separator` | `separator` | 分隔线，可带中间文字 |
 | `skeleton` | `skeleton` | 加载占位骨架 |
 | `switch` | `switch` | 开关切换 |
+| `timeline` | `timeline` | 时间轴：按时间排的事件序列（公告/大事记/版本记录）；顺序即信息，用 `ol`，状态交给 `badge`，颜色在这里会失效 |
+| `upload` | `upload` | 文件上传：零 JS 的原生形态 + 拖放/多文件/校验的增强形态 |
 
 ### patterns · 组合模式（14）
 
@@ -126,11 +128,12 @@ npm install github:owain323/frontend-lib
 | `tooltip` | `tooltip` | 悬停/聚焦提示 |
 | `tree` | `tree` | 可展开树形结构 |
 
-### recipes · 整页配方（4）
+### recipes · 整页配方（5）
 
 | 组件 | 根类名 | 用途 |
 |---|---|---|
 | `analysis-report` | `report` | 组合型研究报告页面：正文与辅助栏并排，窄屏自然退回单栏 |
+| `app-shell` | `shell` | 应用外壳：侧栏 + 顶栏 + 主区三段式；sticky 侧栏自滚、`min-width` 防撑破、窄屏收走侧栏 |
 | `detail-page` | `detail-page` | 实体详情页骨架：字段齐全 / 部分缺失 / 一条数据都没有，三态共用同一套 DOM |
 | `report` | `rep` | 报告版式系统 v1：共享基础 + 三套版式（杂志/科研技术/金融研究），只换一个 … |
 | `table` | `table` | 数据表格：排序/加载/空/错误四态；三种用途预设（财务/学术/统计） |

package/ai/components.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": "1.0.0",
   "generatedBy": "05-audit/gen-ai-contract.py",
-  "libraryVersion": "0.24.0",
+  "libraryVersion": "0.24.2",
   "$comment": "机器可读的组件契约。slots = BEM 元素名（在本库里元素名就是插槽名），states.enum = 组件会在 DOM 上写出的 data-* 取值，states.legacyClass = 仍未收敛到 data 属性的历史状态类（INVARIANT I-8 未达标）。",
   "maturityCriteria": {
     "alpha": "缺 demo.html 或缺 05-audit 下的专属门禁 ⇒ 还没被机器验证过，不要用",

package/dist/01-tokens/page.css

@@ -1 +1 @@
-.page {margin:0;min-height:100vh;min-height:100dvh;background:var(--paper);color:var(--text-primary);font-family:var(--sans);font-size:var(--fs-base);line-height:var(--lh-base);-webkit-text-size-adjust:100%;padding-block:calc(env(safe-area-inset-top, 0px) + var(--sp-6)) calc(env(safe-area-inset-bottom, 0px) + var(--sp-6));padding-inline:max(env(safe-area-inset-right, 0px), var(--sp-4)) max(env(safe-area-inset-left, 0px), var(--sp-4));}.page *, .page *::before, .page *::after {box-sizing:border-box;}.page .wrap {margin-inline:auto;max-width:min(var(--measure-page), 100%);}.page .wrap--prose {max-width:min(var(--measure-prose), 100%);}.page h1 {font-family:var(--sans);font-size:var(--fs-2xl);font-weight:500;letter-spacing:var(--tracking-title);line-height:var(--lh-tight);margin:0 0 var(--sp-3);max-width:var(--measure-title);}.page h2 {font-size:var(--fs-lg);margin:var(--sp-7) 0 var(--sp-3);}.page .rule-top {border-top:1px solid var(--border-decor);padding-top:var(--sp-4);}.page .rule-bottom {border-bottom:1px solid var(--border-decor);padding-bottom:var(--sp-2);margin-bottom:var(--sp-4);}.page code {font-family:var(--mono);font-size:0.9em;background:var(--surface-sunken);padding:1px 4px;border-radius:var(--r-xs);}.page .box {background:var(--surface);border:1px solid var(--border-decor);border-radius:var(--r-md);padding:var(--sp-5);}.page .box.bad {background:var(--surface-sunken);}.page .cmp {display:grid;grid-template-columns:minmax(0, 1fr) minmax(0, 1fr);gap:var(--sp-4);}.page .cmp--wide-first {grid-template-columns:minmax(0, 1.55fr) minmax(0, 1fr);}@media (max-width:640px) {.page .cmp, .page .cmp--wide-first, .page .cmp--clip {grid-template-columns:minmax(0, 1fr);}}.page .cmp__pane {padding:var(--sp-4);border:1px solid var(--border-decor);border-radius:var(--r-md);background:var(--surface-sunken);min-width:0;}.page .cmp--clip .cmp__pane {overflow:hidden;}.page .cmp__pane > h3 {margin:0 0 var(--sp-3);font-size:var(--fs-sm);font-weight:500;}.page .cmp__bad > h3 {color:var(--danger);}.page .cmp__good > h3 {color:var(--success);}.page .cmp__why {margin:var(--sp-3) 0 0;font-size:var(--fs-xs);line-height:1.6;color:var(--text-secondary);}
+.page {margin:0;min-height:100vh;min-height:100dvh;background:var(--paper);color:var(--text-primary);font-family:var(--sans);font-size:var(--fs-base);line-height:var(--lh-base);-webkit-text-size-adjust:100%;padding-block:calc(env(safe-area-inset-top, 0px) + var(--sp-6)) calc(env(safe-area-inset-bottom, 0px) + var(--sp-6));padding-inline:max(env(safe-area-inset-right, 0px), var(--sp-4)) max(env(safe-area-inset-left, 0px), var(--sp-4));}.page *, .page *::before, .page *::after {box-sizing:border-box;}.page .wrap {margin-inline:auto;max-width:min(var(--measure-page), 100%);}.page .wrap--prose {max-width:min(var(--measure-prose), 100%);}.page h1 {font-family:var(--sans);font-size:var(--fs-2xl);font-weight:500;letter-spacing:var(--tracking-title);line-height:var(--lh-tight);margin:0 0 var(--sp-3);max-width:var(--measure-title);}.page h2 {font-size:var(--fs-lg);margin:var(--sp-7) 0 var(--sp-3);}.page .rule-top {border-top:1px solid var(--border-decor);padding-top:var(--sp-4);}.page .rule-bottom {border-bottom:1px solid var(--border-decor);padding-bottom:var(--sp-2);margin-bottom:var(--sp-4);}.page code {font-family:var(--mono);font-size:0.9em;background:var(--surface-sunken);padding:1px 4px;border-radius:var(--r-xs);}:where(.page) pre {overflow-x:auto;}.page .box {background:var(--surface);border:1px solid var(--border-decor);border-radius:var(--r-md);padding:var(--sp-5);}.page .box.bad {background:var(--surface-sunken);}.page .cmp {display:grid;grid-template-columns:minmax(0, 1fr) minmax(0, 1fr);gap:var(--sp-4);}.page .cmp--wide-first {grid-template-columns:minmax(0, 1.55fr) minmax(0, 1fr);}@media (max-width:640px) {.page .cmp, .page .cmp--wide-first, .page .cmp--clip {grid-template-columns:minmax(0, 1fr);}}.page .cmp__pane {padding:var(--sp-4);border:1px solid var(--border-decor);border-radius:var(--r-md);background:var(--surface-sunken);min-width:0;}.page .cmp--clip .cmp__pane {overflow:hidden;}.page .cmp__pane > h3 {margin:0 0 var(--sp-3);font-size:var(--fs-sm);font-weight:500;}.page .cmp__bad > h3 {color:var(--danger);}.page .cmp__good > h3 {color:var(--success);}.page .cmp__why {margin:var(--sp-3) 0 0;font-size:var(--fs-xs);line-height:1.6;color:var(--text-secondary);}