agentcss 0.16.0 → 0.24.0

package/dist/04-recipes/app-shell/shell-nav.js

@@ -0,0 +1,173 @@
+(function (global) {
+'use strict';
+
+var flEmit = function (el, name, detail) {
+if (!el || !el.dispatchEvent) return null;
+var type = name.indexOf('fl-') === 0 ? name : 'fl-' + name;
+var ev = null;
+
+if (typeof window.CustomEvent === 'function') {
+try {
+ev = new window.CustomEvent(type, {
+detail: detail || null, bubbles: true, cancelable: false
+});
+} catch (e) { ev = null; }
+}
+if (!ev) {
+try {
+ev = document.createEvent('CustomEvent');
+ev.initCustomEvent(type, true, false, detail || null);
+} catch (e2) { return null; }
+}
+el.dispatchEvent(ev);
+return ev;
+};
+
+var ICON =
+'<svg viewBox="0 0 16 16" width="18" height="18" fill="none" '+
+'stroke="currentColor" stroke-width="1.6" stroke-linecap="round" '+
+'aria-hidden="true" focusable="false"><path d="M2.5 4h11M2.5 8h11M2.5 12h11"/></svg>';
+
+function warn(msg) {
+if (global.console && global.console.warn) global.console.warn(msg);
+}
+
+function stripIds(node) {
+if (node.removeAttribute) node.removeAttribute('id');
+var all = node.querySelectorAll ? node.querySelectorAll('[id]') : [];
+for (var i = 0; i < all.length; i++) all[i].removeAttribute('id');
+}
+
+function ShellNav(root, opts) {
+if (!root) throw new Error('ShellNav: 缺少根元素');
+var o = this.opts = opts || {};
+var self = this;
+
+this.root = root;
+this.btn = null;
+this.handle = null;
+this.disabled = false;
+
+var side = root.querySelector('.shell__side');
+var topbar = root.querySelector('.shell__topbar');
+
+if (!side || !topbar) {
+this.disabled = true;
+warn('shell-nav: 缺少 ' + (!side ? '.shell__side' : '.shell__topbar') +
+'，已跳过该元素（不改别人的布局）。');
+return;
+}
+
+if (!global.Drawer || typeof global.Drawer.open !== 'function') {
+this.disabled = true;
+warn('shell-nav: 需要先加载 03-patterns/drawer/drawer.js。' +
+'本层只做接线，抽屉的 Esc / 焦点陷阱 / 焦点归位 / 锁滚动都由它提供。'+
+'已跳过，不注入菜单按钮。');
+return;
+}
+
+this.side = side;
+this.topbar = topbar;
+
+var title = root.getAttribute('data-shell-nav') || '导航';
+var btn = document.createElement('button');
+btn.type = 'button';
+btn.className = 'shell__menu';
+btn.setAttribute('aria-label', o.label || ('打开' + title));
+btn.setAttribute('aria-haspopup', 'dialog');
+btn.innerHTML = ICON;
+btn.addEventListener('click', function () { self.open(); });
+topbar.insertBefore(btn, topbar.firstChild);
+this.btn = btn;
+
+this.onResize = function () {
+if (!self.handle) return;
+
+if (self.btn && self.btn.offsetParent === null) self.close();
+};
+global.addEventListener('resize', this.onResize);
+}
+
+ShellNav.prototype = {
+constructor: ShellNav,
+
+open: function () {
+if (this.disabled || this.handle) return this.handle;
+var self = this;
+var title = this.root.getAttribute('data-shell-nav') || '导航';
+
+var content = this.side.cloneNode(true);
+stripIds(content);
+
+content.className += ' shell__side--drawer';
+
+var handle = this.handle = global.Drawer.open({
+place: this.opts.place || 'left',
+title: title,
+content: content,
+
+initialFocus: '[aria-current="page"]',
+onClose: function () {
+self.handle = null;
+flEmit(self.root, 'fl-shell-nav', { open: false });
+}
+});
+
+var el = handle.el;
+el.addEventListener('click', function (e) {
+var n = e.target;
+while (n && n !== el) {
+if (n.tagName === 'A') { self.close(); return; }
+n = n.parentNode;
+}
+});
+
+flEmit(this.root, 'fl-shell-nav', { open: true });
+return handle;
+},
+
+close: function () {
+var h = this.handle;
+if (!h) return false;
+
+this.handle = null;
+h.close();
+return true;
+},
+
+destroy: function () {
+this.close();
+if (this.onResize) {
+global.removeEventListener('resize', this.onResize);
+this.onResize = null;
+}
+if (this.btn && this.btn.parentNode) this.btn.parentNode.removeChild(this.btn);
+this.btn = null;
+if (this.root && this.root.shellNavInstance === this) this.root.shellNavInstance = null;
+this.disabled = true;
+}
+};
+
+global.ShellNav = ShellNav;
+
+function init() {
+var nodes = document.querySelectorAll('[data-shell-nav]');
+for (var i = 0; i < nodes.length; i++) {
+
+if (nodes[i].shellNavInstance) continue;
+try {
+nodes[i].shellNavInstance = new ShellNav(nodes[i]);
+} catch (e) {
+
+warn('shell-nav: 初始化失败，已跳过该元素 —— ' + (e && e.message));
+}
+}
+}
+
+if (typeof document === 'undefined') return;
+if (document.readyState === 'loading') {
+document.addEventListener('DOMContentLoaded', init);
+} else {
+init();
+}
+})(typeof window !== 'undefined' ? window : globalThis);

package/dist/04-recipes/table/table.css

@@ -1 +1 @@
-.table {position:relative;overflow:auto;max-height:var(--table-max-h, 70vh);background:var(--surface);border:1px solid var(--border-decor);border-radius:var(--r-md);}.table table {width:100%;border-collapse:separate;border-spacing:0;font-size:var(--fs-sm);}.table thead th {position:sticky;top:0;z-index:var(--z-sticky);background:var(--surface-raised);color:var(--text-secondary);font-weight:600;text-align:start;white-space:nowrap;padding:var(--sp-2) var(--sp-3);border-bottom:1px solid var(--border-decor);}.table__sort {display:inline-flex;align-items:center;gap:var(--sp-1);min-height:32px;padding:0 var(--sp-1);margin:0 calc(-1 * var(--sp-1));background:none;border:0;border-radius:var(--r-xs, 3px);color:inherit;font:inherit;cursor:pointer;}.table__sort:focus-visible {outline:var(--focus-ring-width) solid var(--focus-ring-color);outline-offset:var(--focus-ring-offset);}.table__sort::after {content:"";inline-size:.85em;block-size:.85em;flex:none;background-color:currentColor;opacity:.45;-webkit-mask:var(--sort-glyph) center / contain no-repeat;mask:var(--sort-glyph) center / contain no-repeat;--sort-glyph:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1.4 5.2 4.6h1.7v2.6h2.2V4.6h1.7z'/%3E%3Cpath d='M8 14.6 10.8 11.4h-1.7V8.8H6.9v2.6H5.2z'/%3E%3C/svg%3E");}.table th[aria-sort="ascending"] .table__sort::after, .table__sort[aria-sort="ascending"]::after {--sort-glyph:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1.6 4.6 6h2.1v8h2.6V6h2.1z'/%3E%3C/svg%3E");opacity:1;}.table th[aria-sort="descending"] .table__sort::after, .table__sort[aria-sort="descending"]::after {--sort-glyph:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 14.4 11.4 10h-2.1V2H6.7v8H4.6z'/%3E%3C/svg%3E");opacity:1;}.table tbody td, .table tbody th {padding:var(--sp-2) var(--sp-3);text-align:start;border-bottom:1px solid var(--border-decor);vertical-align:top;}.table tbody tr:last-child td {border-bottom:0;}@media (hover:hover) and (pointer:fine) {.table tbody tr:hover {background:var(--surface-sunken);}}.table .num {text-align:end;font-variant-numeric:tabular-nums;font-family:var(--mono);white-space:nowrap;}.table .num--pos {color:var(--success);}.table .num--neg {color:var(--danger);}.table .num--pos::before {content:"+";}.table .num--neg::before {content:"−";}.table__empty, .table__error, .table__loading {padding:var(--sp-7) var(--sp-4);text-align:center;color:var(--text-secondary);font-size:var(--fs-sm);}.table__empty {background:var(--surface-sunken);}.table__error {background:var(--surface-sunken);color:var(--danger);}.table__loading {color:var(--text-tertiary);}.table__bar {height:8px;margin:var(--sp-2) auto;max-width:220px;background:var(--surface-sunken);border-radius:999px;overflow:hidden;}@media (prefers-reduced-motion:no-preference) {.table__bar::after {content:"";display:block;height:100%;width:40%;background:var(--accent-soft);border-radius:999px;animation:table-shimmer 1.2s var(--ease-in-out, ease-in-out) infinite;}@keyframes table-shimmer {0% {transform:translateX(-100%);}100% {transform:translateX(250%);}}}.table__empty .btn, .table__error .btn {margin-top:var(--sp-3);}.table--compact {font-size:var(--fs-xs);}.table--compact thead th, .table--compact tbody td {padding:var(--sp-1) var(--sp-2);}.table__cap {caption-side:top;text-align:start;padding:var(--sp-2) var(--sp-3);font-size:var(--fs-xs);color:var(--text-tertiary);}.table__foot {margin:var(--sp-2) 0 0;padding:0 var(--sp-1);font-size:var(--fs-xs);color:var(--text-tertiary);line-height:1.6;}.table__foot ol {margin:0;padding-inline-start:var(--sp-4);}.table thead tr + tr th {top:2.4em;font-weight:500;font-size:var(--fs-xs);color:var(--text-tertiary);border-bottom:1px solid var(--border-decor);}.table thead th[colspan] {text-align:center;border-inline-start:1px solid var(--border-decor);}.table thead th[colspan]:first-child {border-inline-start:0;}.table--financial thead th {white-space:nowrap;}.table--financial tbody th {white-space:nowrap;}.table--financial thead th:not(:first-child) {text-align:end;}.table__unit {font-weight:400;font-size:inherit;color:var(--text-secondary);margin-inline-start:0.35em;white-space:nowrap;}.table .num--na, .table .cell--na {color:var(--text-tertiary);text-align:center;}.table--academic {border:0;border-radius:0;background:transparent;max-height:none;}.table--academic table {background:transparent;}.table--academic thead th {background:transparent;color:var(--text-primary);font-weight:600;border-top:2px solid var(--border-decor-str);border-bottom:1px solid var(--border-decor);position:static;}.table--academic thead tr + tr th {font-weight:400;border-top:0;border-bottom:1px solid var(--border-decor);}.table--academic tbody td, .table--academic tbody th {border-bottom:0;}.table--academic tbody tr:last-child td, .table--academic tbody tr:last-child th {border-bottom:1px solid var(--border-decor);}@media (hover:hover) and (pointer:fine) {.table--academic tbody tr:hover {background:transparent;}}.table--stats .stat__se {color:var(--text-tertiary);font-size:var(--fs-xs);}.table--stats .stat__p {font-family:var(--mono);font-variant-numeric:tabular-nums;}.table--stats .stat__p--sig {font-weight:700;color:var(--text-primary);}.table--stats .stat__ci {font-family:var(--mono);font-variant-numeric:tabular-nums;white-space:nowrap;}@media print {.table {max-height:none;overflow:visible;}.table thead th {position:static;}.table--academic thead th {border-top:2px solid var(--text-primary);}}
+.table {position:relative;overflow:auto;max-height:var(--table-max-h, 70vh);background:var(--surface);border:1px solid var(--border-decor);border-radius:var(--r-md);}.table table {width:100%;border-collapse:separate;border-spacing:0;font-size:var(--fs-sm);}.table thead th {position:sticky;top:0;z-index:var(--z-sticky);background:var(--surface-raised);color:var(--text-secondary);font-weight:600;text-align:start;white-space:nowrap;padding:var(--sp-2) var(--sp-3);border-bottom:1px solid var(--border-decor);}.table__sort {display:inline-flex;align-items:center;gap:var(--sp-1);min-height:32px;padding:0 var(--sp-1);margin:0 calc(-1 * var(--sp-1));background:none;border:0;border-radius:var(--r-xs, 3px);color:inherit;font:inherit;cursor:pointer;}.table__sort:focus-visible {outline:var(--focus-ring-width) solid var(--focus-ring-color);outline-offset:var(--focus-ring-offset);}.table__sort::after {content:"";inline-size:.85em;block-size:.85em;flex:none;background-color:currentColor;opacity:.45;-webkit-mask:var(--sort-glyph) center / contain no-repeat;mask:var(--sort-glyph) center / contain no-repeat;--sort-glyph:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1.4 5.2 4.6h1.7v2.6h2.2V4.6h1.7z'/%3E%3Cpath d='M8 14.6 10.8 11.4h-1.7V8.8H6.9v2.6H5.2z'/%3E%3C/svg%3E");}@media (forced-colors:active) {.table__sort::after {background-color:CanvasText;opacity:1;}}.table th[aria-sort="ascending"] .table__sort::after, .table__sort[aria-sort="ascending"]::after {--sort-glyph:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 1.6 4.6 6h2.1v8h2.6V6h2.1z'/%3E%3C/svg%3E");opacity:1;}.table th[aria-sort="descending"] .table__sort::after, .table__sort[aria-sort="descending"]::after {--sort-glyph:url("data:image/svg+xml,%3Csvg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 16 16'%3E%3Cpath d='M8 14.4 11.4 10h-2.1V2H6.7v8H4.6z'/%3E%3C/svg%3E");opacity:1;}.table tbody td, .table tbody th {padding:var(--sp-2) var(--sp-3);text-align:start;border-bottom:1px solid var(--border-decor);vertical-align:top;}.table tbody tr:last-child td {border-bottom:0;}@media (hover:hover) and (pointer:fine) {.table tbody tr:hover {background:var(--surface-sunken);}}.table .num {text-align:end;font-variant-numeric:tabular-nums;font-family:var(--mono);white-space:nowrap;}.table .num--pos {color:var(--success);}.table .num--neg {color:var(--danger);}.table .num--pos::before {content:"+";}.table .num--neg::before {content:"−";}.table__empty, .table__error, .table__loading {padding:var(--sp-7) var(--sp-4);text-align:center;color:var(--text-secondary);font-size:var(--fs-sm);}.table__empty {background:var(--surface-sunken);}.table__error {background:var(--surface-sunken);color:var(--danger);}.table__loading {color:var(--text-tertiary);}.table__bar {height:8px;margin:var(--sp-2) auto;max-width:220px;background:var(--surface-sunken);border-radius:999px;overflow:hidden;}@media (prefers-reduced-motion:no-preference) {.table__bar::after {content:"";display:block;height:100%;width:40%;background:var(--accent-soft);border-radius:999px;animation:table-shimmer 1.2s var(--ease-in-out, ease-in-out) infinite;}@keyframes table-shimmer {0% {transform:translateX(-100%);}100% {transform:translateX(250%);}}}.table__empty .btn, .table__error .btn {margin-top:var(--sp-3);}.table--compact {font-size:var(--fs-xs);}.table--compact thead th, .table--compact tbody td {padding:var(--sp-1) var(--sp-2);}.table__cap {caption-side:top;text-align:start;padding:var(--sp-2) var(--sp-3);font-size:var(--fs-xs);color:var(--text-tertiary);}.table__foot {margin:var(--sp-2) 0 0;padding:0 var(--sp-1);font-size:var(--fs-xs);color:var(--text-tertiary);line-height:1.6;}.table__foot ol {margin:0;padding-inline-start:var(--sp-4);}.table thead tr + tr th {top:2.4em;font-weight:500;font-size:var(--fs-xs);color:var(--text-tertiary);border-bottom:1px solid var(--border-decor);}.table thead th[colspan] {text-align:center;border-inline-start:1px solid var(--border-decor);}.table thead th[colspan]:first-child {border-inline-start:0;}.table--financial thead th {white-space:nowrap;}.table--financial tbody th {white-space:nowrap;}.table--financial thead th:not(:first-child) {text-align:end;}.table__unit {font-weight:400;font-size:inherit;color:var(--text-secondary);margin-inline-start:0.35em;white-space:nowrap;}.table .num--na, .table .cell--na {color:var(--text-tertiary);text-align:center;}.table--academic {border:0;border-radius:0;background:transparent;max-height:none;}.table--academic table {background:transparent;}.table--academic thead th {background:transparent;color:var(--text-primary);font-weight:600;border-top:2px solid var(--border-decor-str);border-bottom:1px solid var(--border-decor);position:static;}.table--academic thead tr + tr th {font-weight:400;border-top:0;border-bottom:1px solid var(--border-decor);}.table--academic tbody td, .table--academic tbody th {border-bottom:0;}.table--academic tbody tr:last-child td, .table--academic tbody tr:last-child th {border-bottom:1px solid var(--border-decor);}@media (hover:hover) and (pointer:fine) {.table--academic tbody tr:hover {background:transparent;}}.table--stats .stat__se {color:var(--text-tertiary);font-size:var(--fs-xs);}.table--stats .stat__p {font-family:var(--mono);font-variant-numeric:tabular-nums;}.table--stats .stat__p--sig {font-weight:700;color:var(--text-primary);}.table--stats .stat__ci {font-family:var(--mono);font-variant-numeric:tabular-nums;white-space:nowrap;}@media print {.table {max-height:none;overflow:visible;}.table thead th {position:static;}.table--academic thead th {border-top:2px solid var(--text-primary);}}

package/dist/COSTS.md

@@ -10,7 +10,7 @@
 实测两笔账，一笔不省：
 
 - `tokens` 源码版 gzip **20.4 KB** → min 版 **2.7 KB**（省 87%）——
-  源码多的那部分**全是注释**（全库 CSS 有 67% 是注释，字节口径），而注释是给维护者的，不是给浏览器的。
+  源码多的那部分**全是注释**（全库 CSS 有 68% 是注释，字节口径），而注释是给维护者的，不是给浏览器的。
 - tokens 的 min 版 2.7 KB **比任何一个组件自己都贵** ⇒
   "只用一个组件"的真实起步价就是它。不公开这张表，等于让人盲买。
 
@@ -21,21 +21,23 @@
 | primitive | `badge` | 2.7 KB | 0.5 KB | — | **3.2 KB** | 23.1 KB | −19.9 KB |
 | primitive | `button` | 2.7 KB | 1.0 KB | — | **3.7 KB** | 26.8 KB | −23.1 KB |
 | primitive | `card` | 2.7 KB | 0.9 KB | — | **3.7 KB** | 24.5 KB | −20.8 KB |
-| primitive | `choice` | 2.7 KB | 1.1 KB | — | **3.8 KB** | 25.8 KB | −22.0 KB |
+| primitive | `choice` | 2.7 KB | 1.1 KB | — | **3.8 KB** | 26.3 KB | −22.5 KB |
 | primitive | `combobox` | 2.7 KB | 1.0 KB | 5.4 KB | **9.1 KB** | 29.9 KB | −20.9 KB |
 | primitive | `date-range` | 2.7 KB | 0.8 KB | 2.5 KB | **6.1 KB** | 26.9 KB | −20.8 KB |
 | primitive | `delta` | 2.7 KB | 0.3 KB | — | **3.0 KB** | 23.1 KB | −20.2 KB |
-| primitive | `input` | 2.7 KB | 1.0 KB | — | **3.7 KB** | 24.0 KB | −20.3 KB |
+| primitive | `input` | 2.7 KB | 1.0 KB | — | **3.8 KB** | 24.3 KB | −20.6 KB |
 | primitive | `metric` | 2.7 KB | 0.5 KB | — | **3.2 KB** | 23.6 KB | −20.4 KB |
 | primitive | `popover` | 2.7 KB | 0.8 KB | 2.2 KB | **5.7 KB** | 27.7 KB | −22.0 KB |
-| primitive | `progress` | 2.7 KB | 0.7 KB | — | **3.4 KB** | 23.3 KB | −19.9 KB |
+| primitive | `progress` | 2.7 KB | 0.8 KB | — | **3.5 KB** | 24.7 KB | −21.2 KB |
 | primitive | `select` | 2.7 KB | 0.8 KB | 3.5 KB | **7.1 KB** | 30.0 KB | −22.9 KB |
 | primitive | `separator` | 2.7 KB | 0.2 KB | — | **3.0 KB** | 21.7 KB | −18.7 KB |
-| primitive | `skeleton` | 2.7 KB | 0.5 KB | — | **3.2 KB** | 21.8 KB | −18.6 KB |
-| primitive | `switch` | 2.7 KB | 0.8 KB | — | **3.5 KB** | 27.5 KB | −24.1 KB |
+| primitive | `skeleton` | 2.7 KB | 0.5 KB | — | **3.2 KB** | 22.3 KB | −19.1 KB |
+| primitive | `switch` | 2.7 KB | 0.8 KB | — | **3.5 KB** | 28.7 KB | −25.2 KB |
+| primitive | `timeline` | 2.7 KB | 0.5 KB | — | **3.2 KB** | 23.7 KB | −20.4 KB |
+| primitive | `upload` | 2.7 KB | 1.4 KB | 4.2 KB | **8.3 KB** | 37.8 KB | −29.5 KB |
 | pattern | `accordion` | 2.7 KB | 1.3 KB | 1.8 KB | **5.8 KB** | 34.9 KB | −29.1 KB |
 | pattern | `content` | 2.7 KB | 1.0 KB | — | **3.7 KB** | 25.0 KB | −21.2 KB |
-| pattern | `drawer` | 2.7 KB | 0.8 KB | 2.4 KB | **5.9 KB** | 26.9 KB | −21.0 KB |
+| pattern | `drawer` | 2.7 KB | 0.8 KB | 2.5 KB | **6.0 KB** | 27.5 KB | −21.5 KB |
 | pattern | `dropdown` | 2.7 KB | 0.8 KB | 3.4 KB | **6.9 KB** | 29.8 KB | −22.9 KB |
 | pattern | `form-validation` | 2.7 KB | 0.8 KB | — | **3.5 KB** | 24.9 KB | −21.4 KB |
 | pattern | `list` | 2.7 KB | 0.6 KB | — | **3.3 KB** | 22.8 KB | −19.5 KB |
@@ -50,9 +52,9 @@
 
 ## 三、全库
 
-- 全部组件都用上（min，含 tokens 一份）：**62.7 KB**
-- 源码版（带注释）全库 gzip：307.3 KB
+- 全部组件都用上（min，含 tokens 一份）：**69.0 KB**
+- 源码版（带注释）全库 gzip：348.5 KB
 
-> ⚠️ 源码版那个数字**不是**要付的钱：它包含我们的注释（全库 CSS 有 67% 是注释，字节口径）。
+> ⚠️ 源码版那个数字**不是**要付的钱：它包含我们的注释（全库 CSS 有 68% 是注释，字节口径）。
 > 它的用途只有一个 —— 让人看清"dist 到底省了多少"。
 

package/docs/ACCESSIBILITY.md

@@ -5,8 +5,8 @@
 
 | 项目 | 值 |
 |---|---|
-| 声明适用版本 | agentcss `0.16.0` |
-| 声明日期 | 2026-10-30 |
+| 声明适用版本 | agentcss `0.24.0` |
+| 声明日期 | 2026-10-31 |
 | 复核节奏 | 每次发版前重跑（`npm run gate` 内含全部证据） |
 | 范围 | 本库交付的 CSS / JS、全部 `demo.html`（组件页 + 图表页 + 组合页）、以及文档站生成的页面 |
 | 不在范围 | 使用者拿这些组件拼出来的业务页面（那是你的无障碍责任，不是库的） |
@@ -67,7 +67,7 @@
 | 3.3.2 | 标签或说明 | ✅ | 必填项有可见标记 + `required` |
 | 3.3.7 | 冗余输入（2.2 A） | — | 由业务表单决定，库不承载 |
 | 3.3.8 | 可访问的认证（2.2 AA） | — | 库不含登录流程 |
-| 4.1.2 | 名称、角色、值 | ✅ | `a11y-ax.js`：**全部 40 个 demo 页**的可访问性树逐节点判，每个可交互控件有非空名称；朗读序列逐页存快照防回归 |
+| 4.1.2 | 名称、角色、值 | ✅ | `a11y-ax.js`：**全部 43 个 demo 页**的可访问性树逐节点判，每个可交互控件有非空名称；朗读序列逐页存快照防回归。图标态（`.shell--rail`）的名字来自**视觉隐藏但仍可访问**的 `.shell__link-label`，不是 `aria-label` —— `app-shell-check` F12 / G4 两头守（改成 `display:none` 名字会消失） |
 | 4.1.3 | 状态消息 | ◐ | toast / 表单错误用 `role="status"` / `alert`；**未**在真实读屏里验证播报时机 |
 
 **统计：✅ 27 条 · ◐ 7 条 · ✗ 0 条 · — 12 条。**
@@ -80,7 +80,7 @@
 
 | 手段 | 覆盖 | 最近结果 |
 |---|---|---|
-| `axe-core`（`a11y-scan.js`） | 39 页（37 组件 demo + 2 个非组件页） | **0 类违规**，991 条规则通过 |
+| `axe-core`（`a11y-scan.js`） | 41 页（39 组件 demo + 2 个非组件页） | **0 类违规**，991 条规则通过 |
 | 反向控制（注入 5 类典型违规） | 证明上一条不是"没查" | 5 类全部抓到 |
 | `heading-outline.js`（人工工具） | **全部 HTML：96 页 / 887 个标题** | 0 处跳级 · 每页恰好 1 个 `h1` · DOM 标题数 == 无障碍树 heading 数 |
 | `a11y-ax.js` 可访问性树 | **全部 `demo.html`（现 40 个）**；清单与磁盘不一致即红 | 0 个无名控件；40 份朗读序列快照在 `10-review/a11y-tree/` |
@@ -121,10 +121,23 @@
    这是与 Carbon / Spectrum 那类一致性报告差距最大的一处。
 2. **没有 VPAT / ACR 正式报告**。采购流程要的那种文档本库没有出；
    上面那张 SC 表可以当它的替代品，但它不是法律意义上的 ACR。
-3. **强制色板（forced-colors）只覆盖 6 个 CSS**，Windows 高对比度模式未逐组件验证。
+3. **强制色板（forced-colors）已逐组件验到"信息不丢"，但没上过真机**：
+   2026-10-31 用 CDP 的 `Emulation.setEmulatedMedia` 把 `forced-colors` 打开，
+   扫了契约里全部有 demo 的组件页 + 7 个 fixture，修掉 7 类真实缺陷（进度条整块空白、开关滑块消失、
+   排序箭头与错误图标变白、骨架屏伪装成"加载完"、单选圆点消失、
+   侧栏"当前项"变成五项全都带竖线），
+   并由 `05-audit/forced-colors-check.js` 守着（含"剥掉修复必须变红"的反向控制）。
+   第 7 类（0.22.1）的教训是**透明边框不是免费预留**：`border-inline-start:
+   3px solid transparent` 在强制色里会被解析成实线（链接上是 LinkText，当前项是
+   CanvasText），于是每一项都长出一条竖线，当前项只剩色相差 —— 现在改用
+   「字重 + 系统色圆点」两条非颜色线索，并且圆点用 `content: ""` 画，
+   避免 `content: "•"` 把可访问名污染成「圆点 总览」。
+   **仍然缺的是**：真实 Windows 高对比度主题下的截图与人眼确认 ——
+   模拟色板与真机不是同一套（`GrayText` 在模拟里是深红，真机是灰），
+   所以本文档所有强制色结论都只到"语义可辨"这一层，不到"配色好看"。
 4. **RTL 已进渲染判据与视觉基线，但没进真机**：
-   `rtl-render.js` 判 37 页（RTL 不横滚 / 阿·希文字膨胀 1.3× 不破相 /
-   方向性字形镜像），`shot-baseline.py --dir rtl` 有 13 张视觉基线
+   `rtl-render.js` 判全部 demo 页（RTL 不横滚 / 阿·希文字膨胀 1.3× 不破相 /
+   方向性字形镜像），`shot-baseline.py --dir rtl` 另有整套 RTL 视觉基线
    （覆盖"镜像错了但不溢出不改字形"那一类）。
    **仍然缺的是**：母语 RTL 使用者的实际阅读体验、iOS/Android 真机 RTL 截图，
    以及「页面加载后再切 `dir`」时组件内部状态是否需要重算。

package/docs/AI-CONTRACT.md

@@ -176,6 +176,8 @@ h1 { font-size: 31px }          /* 改一个，14 页全变 */
 - `ai/validate.js` + `node ai/cli.js check <文件>` —— 零依赖校验
 - `ai/profiles.json` —— 三档严格程度；`strict` 只允许 `stable` 组件
 - `ai/capabilities.json` —— 按**能力**协商可用操作，不按模型名分支
+- `ai/pitfalls.json`（组件 / 版式 / 交付）+ `ai/pitfalls-writing.json`（写文案、做演示、发页面）
+  —— 已知翻车点；查：`node ai/cli.js pitfalls --json [--component=<id>] [--scope=writing]`
 - `ai/behaviors.json` —— **行为覆盖矩阵**：哪些组件必须有哪种微行为
   （状态：`core` 已收编 / `manual` 手写未收编 / `gap` 应做未做 / `n/a` 不适用）
   ⇒ **不登记就红**，不许靠省略跳过；`manual` 与 `gap` 的数量有棘轮，只能降不能升

package/docs/BUDGET.md

@@ -0,0 +1,179 @@
+# 体积预算
+
+> **一句话**：全库生效 CSS 的天花板是 **172 KB**，冻结。常规新增组件（每个 1~4 KB）
+> **不需要动任何数字**；吃光储备要给一次带理由的账，最多三次；之后只能删。
+> 数据在 `05-audit/budget.json`，判定在 `05-audit/perf-gate.py`，
+> 判据自己的判据在 `05-audit/budget-selftest.py`。
+
+---
+
+## 1 · 为什么要有这份文件
+
+因为**旧的治理方式已经坏过一次，而且坏得很安静**。
+
+`perf-gate.py` 里原本有一个常量 `MAX_ALL_CSS`。它在半年里被改过六次：
+
+| 版本 | 从 | 到 | 理由 |
+|---|---|---|---|
+| 0.10 | 120 KB | 124 KB | 容器级主题要在每个作用域重声明 L2 别名（规定动作） |
+| 0.10 | 124 KB | 125 KB | `page.css` 收了 `.cmp` 对错对照家族 |
+| 0.12 | 125 KB | 132 KB | `delta` + `metric` + `market.css` |
+| 0.18 | 132 KB | 139 KB | `upload` |
+| 0.18 | 139 KB | 142 KB | `app-shell` |
+| 0.19 | 142 KB | 143 KB | `shell-nav` 接线 |
+
+每一次都写了理由，每一次理由都成立。**问题不在任何一次改动，而在结构**：
+
+> 被约束的人手里握着那个数字。
+
+于是"加组件"和"改上限"变成了同一个动作的两步，而下一次必然重演。
+更加隐蔽的是：上限一旦抬到"随手加什么都装得下"，这道预算就**再也不会失败**了 ——
+它还在跑，还在打 `OK`，但已经不再约束任何东西。
+
+所以 0.22.2 换的不是数字，是**谁在什么时候能改它**。
+
+---
+
+## 2 · 五层，各拦一种不同的失效
+
+| 层 | 判据 | 拦的是什么 | 触发时怎么办 |
+|---|---|---|---|
+| L1 | 单文件 ≤ 24 KB | 一个文件变成怪物 | 拆文件 |
+| L2 | 单组件 ≤ 10 KB | 一个组件变成子框架 | 拆组件 / 承认它是框架并移出 `04-recipes` |
+| L3 | 总量 ≤ 授予 + 储备（10 KB） | 常规增长被卡住 | **不用管**，储备就是给这个的 |
+| L4 | 总量 ≤ 天花板（172 KB） | 产品承诺被越过 | 删，或走 ADR |
+| L5 | 总量 ≥ 授予 − 死区（2 KB） | 降下来之后没人收线 | `--ratchet`（安全，无需理由） |
+
+L3 和 L5 是一对：**L3 让正常更新免费，L5 让免费额度不会自己长大**。
+只有这两条同时在场，"不用动数字"才不等于"没有预算"。
+
+L1 / L2 管形状，L3 / L4 / L5 管总量 —— 它们不互相替代。
+一个 20 KB 的 `report.css` 不会因为总量还有余量就变得合理。
+
+---
+
+## 3 · 172 KB 是怎么来的
+
+不是审美，是三道约束夹出来的：
+
+**① 路线图要装得下。** 还剩 8~12 个候选组件，实测每个组件的生效 CSS 中位数
+**2.4 KB**（`delta` 1.5 / `metric` 1.5 / `app-shell` 2.4 / `shell-nav` 0.9 / `upload` 4.2）。
+当前 144.45 KB（2026-10-31 实测）⇒ 172 还差 **28.2 KB ≈ 11 个中等组件**。
+**这个数就是按"把剩下的组件做完也不用再开会"定的。**
+
+**② 不能低于 160 KB。** 低于它，做完路线图就会撞线 ——
+那就退回到"每加两个组件改一次数字"，等于没改。
+
+**③ 传输成本要站得住。** 46 个文件合并后 gzip 实测 **23.6 KB**
+（生效 144.45 KB，压缩比 6.13:1）。172 KB 对应约 **28 KB gzip**，
+仍在一套基础样式表该有的量级里；再往上就是"又一个 Bootstrap"，
+与本库"小而全、可整包引入"的定位冲突。
+
+⚠️ 量的是**剥掉注释后的 UTF-8 字节**（浏览器不解析注释），
+且经 `_bytes.read_norm` 归一化（行尾不影响结果）。
+用磁盘体积判会严重高估：全库磁盘体积里约七成是注释，真正生效的不到一半。
+口径与 `doc-facts-gate.py` 的 `real_css_size()` 一致。
+（这里**不写绝对值** —— 上一版写过「467.2 KB 里 318.4 KB」，
+加一个组件就漂，而漂了的数字没有任何门禁会叫。要具体数，看 `dist/COSTS.md`，
+那份是 `dist-cost-gate.py` 每次现算并当场比对的。）
+
+---
+
+## 4 · 三种动作，三种手续
+
+### 4.1 加组件（最常见）—— 零手续
+
+只要总量还在 `授予 + 储备` 以内，门禁直接放行。**不用改 `budget.json`，不用改代码。**
+
+```bash
+python3 05-audit/perf-gate.py
+#   OK    合计 144.4 KB / 152.7 KB ｜ 天花板还剩 27.6 KB ≈ 11 个中等组件
+#         本轮已用储备 1.8 KB / 10.0 KB；棘轮死区 2.0 KB
+```
+
+### 4.2 吃光储备 —— 一次带理由的账
+
+```bash
+python3 05-audit/perf-gate.py --grant --reason "为什么这 3.1 KB 是必要的"
+```
+
+`--reason` 至少 12 个字，会被写进 `budget.json` 的 `grants[]`（含日期与当次体积）。
+它会出现在 `git diff` 里 —— **这就是目的**：让"我又多要了 3 KB"这件事
+在代码评审里被看见，而不是消失在一次没有 diff 的常量修改里。
+
+**最多三次。** 储备 × 3 ≈ 天花板余量，所以三次之后天然撞天花板 ——
+那时候唯一的路是删。
+
+### 4.3 体积降了 —— 收线
+
+```bash
+python3 05-audit/perf-gate.py --ratchet
+```
+
+删掉 6 KB 死代码之后如果不收线，储备会从 10 KB 变成 16 KB，**预算悄悄放松**。
+所以门禁在反方向也判：比授予低 2 KB 以上就要求收线。2 KB 是死区，
+让"合并一条规则省 300 B"这种噪声不触发。
+
+---
+
+## 5 · 什么时候才允许动天花板
+
+**只有一种情况**：储备用尽（三次授予之后仍然不够），并且能同时给出这三样：
+
+1. 一段实测：新增的 X KB 具体是什么规则、为什么无法合并或删除；
+2. 一次代价换算：新的天花板对应多少 gzip（`perf-gate.py` 每次都会打当前总量）；
+3. 一段 ADR，写进本文件下面的表格 —— 不是写进 `perf-gate.py` 的注释。
+
+| 日期 | 从 | 到 | 谁批准 | 换来的是什么 | 代价（gzip） |
+|---|---|---|---|---|---|
+| 2026-10-31 | — | 172 KB | 初始冻结 | 路线图剩余 8~12 个组件的空间 | ≈28 KB |
+
+**不允许**的理由（历史上出现过，现在一律拒绝）：
+
+- "这次是真实增长" —— 每次都是真实增长，这不是理由，是现象；
+- "拆起来麻烦" —— L2 的存在就是为了让"麻烦"有一个具体的数字；
+- "先抬上去，回头再删" —— 回头不会来。
+
+---
+
+## 6 · 这份预算不管什么
+
+- **不管 gzip 总量**。压缩比会随内容变化（目前 6.1:1），把它做成硬门禁会得到
+  一条"复制粘贴反而更容易过"的判据 —— gzip 恰好能压掉重复内容。
+  重复内容由 `size-baseline.py` 的 `raw` 口径抓（那边同时看 raw 与 gzip）。
+- **不管第三方代码**（`vendor/`）。那些不是我们的字节。
+- **不管 demo 的内联 `<style>`** —— 那条单独卡在 8 KB，
+  因为内联样式会绕过 tokens 门禁，是完全不同的失效方式。
+- **不管注释**。本库的注释是刻意投入（取舍理由、踩过的坑），
+  剥掉注释后的字节才是浏览器要解析的东西。想看注释占比：
+  `python3 05-audit/doc-facts-gate.py` 会核 README 里那个数字。
+
+---
+
+## 7 · 判据自己怎么被验证
+
+体积门禁换模型时引入了一个新风险：**五个分支里只有一个会被日常触发**。
+天花板永远不会红（除非已经晚了），储备永远不会红（除非已经用光），
+棘轮只在删代码后才该红 —— 于是"写反不等号"可以绿着跑一百次。
+
+所以有两道互相独立的验证：
+
+| 文件 | 验什么 | 怎么验 |
+|---|---|---|
+| `perf-gate.py --selftest` | `verdict()` 的五个分支顺序 + `main()` 真的调它 | 8 条合成数字 + 一条字节码接线检查 |
+| `budget-selftest.py` | **端到端**行为：退出码、失败文案、`--grant`/`--ratchet` 写盘、账本缺失 | 15 条，用 `FL_BUDGET` 指向临时账本跑真实的 `perf-gate.py` |
+
+变异探针（一次性的，结论记在这里）：把五个分支逐一改成恒假、把 `main()` 改成
+绕过 `verdict`、去掉授予次数上限 —— **5/5 全部被 `budget-selftest.py` 判红**，
+且每次源码都逐字节还原（sha 核对）。
+
+---
+
+## 8 · 冻结声明
+
+自 `0.22.2` 起，`05-audit/budget.json` 的四个数字（天花板 / 储备 / 死区 / 单组件）
+**进入冻结**：改动它们需要一次显式的 ADR（第 5 节），
+而不是一次"顺手调大"。
+
+冻结不等于永远不会变 —— 它等于**变的时候必须留下痕迹**。
+账本里的 `grants[]` 就是那个痕迹。

package/docs/CONVENTIONS.md

@@ -260,6 +260,9 @@
 | 表格里的方向语义（涨跌嵌 `delta`、零值不带符号、口径只翻市场列） | `table-check.js` ⑫⑬⑭ |
 | 指标缺数是显式状态、数字等宽对齐 | `metric-check.js` |
 | 文档里的数字与实际一致（组件数/门禁数/精简档令牌数） | `doc-facts-gate.py` |
+| 体积不越过账面预算（天花板 / 储备 / 棘轮 / 单组件） | `perf-gate.py`（账本 `05-audit/budget.json`，规则 [BUDGET.md](BUDGET.md)） |
+| 预算判据自己的五个分支与接线 | `budget-selftest.py`（用临时账本端到端跑真实门禁） |
+| 公开名字不消失、d.ts 与运行时一致 | `deprecation-gate.py` + `api-contract-gate.py`（承诺见 [STABILITY.md](STABILITY.md)） |
 
 想加一条新规则？先在门禁里加判据、确认它会红，再写进本文 ——
 **顺序反了就会得到一条"写在文档里、没人执行"的规则。**

package/docs/STABILITY.md

@@ -0,0 +1,126 @@
+# 稳定性承诺（冻结声明）
+
+> **一句话**：从 `0.23.0` 起，这个库进入**只增不减**的冻结期。
+> 公开名字（令牌、类名、JS 成员、CLI 子命令、契约字段、文件路径）
+> 不消失、不改名、不改语义；渲染细节、注释、文档、门禁随时可改。
+> 冻结**不是**"停止维护"，是"改动必须对下游可见"。
+
+---
+
+## 1 · 为什么写这份文件
+
+"别动了"这句话有两种翻译，而它们的后果完全相反：
+
+| 翻译 | 后果 |
+|---|---|
+| 不再发布、不再修 | 下游遇到 bug 只能自己打补丁，一年后没人敢升级 |
+| 不再**破坏** | 下游可以放心把版本号写死，而修复继续到货 |
+
+这份文件选第二种。它把"冻结"定义成一组**可被机器检查**的承诺，
+每条承诺都指着一个正在跑的门禁 —— 没有判据的承诺不写在这里。
+
+---
+
+## 2 · 冻的是什么（承诺 ↔ 判据）
+
+| 承诺 | 具体到 | 谁在守 |
+|---|---|---|
+| 令牌名不消失 | `--text-primary`、`--sp-2` 这类名字 | `deprecation-gate.py` ⑦（`ai/surface.baseline.json` 只增不减） |
+| 类名不消失 | `.btn`、`.field`、`.shell__link` 这类名字 | 同上 |
+| JS 成员不消失 | `Select.open()`、`AccordionOptions.duration` 这类名字 | `deprecation-gate.py` ⑦ + `api-contract-gate.py`（d.ts ↔ 运行时**实测**比对） |
+| 声明的名字真的存在 | 不许出现"文档里有、代码里没有"的幻觉 API | `gen-ai-contract.py --check`、`dead-class-gate.py` |
+| 行为事件名不消失 | `fl:select` 这类事件名 | 只记在基线里，**没有运行时探针**（见 §6） |
+| CLI 子命令与 `--json` 形状 | `agentcss ai <cmd> --json` 的 11 个子命令、失败也是 JSON | `ai-layer-gate.js` ⑥′⑥″ |
+| 契约文件字段 | `ai/components.json` / `pitfalls*.json` / `behaviors.json` | `gen-ai-contract --check`、`ai-layer-gate` ⑦ |
+| 文件路径 | `02-primitives/button/button.css` 这类 `<link>` 直接指向的路径 | `dist-parity-check`、`pack-smoke.sh`、`assets-catalog-gate.py` |
+| 体积承诺 | 全库生效 CSS ≤ 172 KB，常规增长不涨价 | `perf-gate.py` + `budget-selftest.py`（见 [BUDGET.md](BUDGET.md)） |
+
+逐条清单与总数**不写在这份文件里** —— 那是 `ai/surface.baseline.json` 的职责
+（`deprecation-gate.py` 每次运行都会打印总数与「无未登记的移除」）。写在文档里的
+计数一定会漂 —— 这份文件的第一版就写死过「337 个类名」，后来基线涨到 379，
+没有任何门禁会因为那句话过时而变红。**数字只有一个来源，才不会有第二个版本。**
+
+⚠️ "不消失"包含**不改语义**。把 `.btn` 从 44px 高改成 36px 不会让门禁变红，
+但它一样是破坏性变更 —— 判据守不住的部分，靠这一行字约束。
+
+---
+
+## 3 · 没冻的（随时可以改，不需要任何流程）
+
+| 面 | 为什么可以随便改 |
+|---|---|
+| CSS 选择器的**写法** | 只要渲染结果等价。合并规则、换 `:is()`、调顺序都行 |
+| 注释 | 本库注释是给人读的取舍记录，跟着代码一起演进 |
+| demo 页 | 它们是文档，不是 API |
+| 文档、guide、README | 同上。数字由 `doc-facts-gate.py` 对账 |
+| 门禁脚本本身 | 门禁只约束产品，不约束自己 —— 但它自己要被 `selftest-all.py` 约束 |
+| 新增组件、新增令牌、新增类名 | 纯增量，不破坏任何下游 |
+| 内部实现（JS 私有函数、`data-*` 内部状态） | 没有承诺过，也从未写进 d.ts |
+
+⚠️ 有一条**反直觉**的：`data-state` 这类属性值是**公开的**
+（`.btn[data-state="loading"]` 是文档里教人写的选择器），
+所以它们属于 §2 而不是 §3，即使它们长得像内部实现。
+
+---
+
+## 4 · 版本语义（0.x 期间）
+
+| 变更类型 | 版本位 | 例子 |
+|---|---|---|
+| 修复（渲染错、对比度不达标、门禁误报） | patch | `0.23.0 → 0.23.1` |
+| 新增（组件、令牌、CLI 子命令、文档） | minor | `0.23.0 → 0.24.0` |
+| 删除 / 改名 / 改语义 | **必须走废弃流程** | 见 `docs/DEPRECATIONS.md` |
+
+废弃流程的硬要求（`deprecation-gate.py` ③）：**迁移窗口 ≥ 一个次版本**。
+也就是说，`0.24.0` 宣布废弃，最早 `0.26.0` 才能真的删 ——
+中间那个版本是给下游的。
+
+1.0 之后这条不变，只是"次版本"变成"主版本"。
+
+---
+
+## 5 · 什么情况下解冻
+
+解冻指"允许一次破坏性变更"。三个条件**全部**满足才成立：
+
+1. **有下游证据**：至少一个真实使用方（含本库自己的 `guide/` 与 demo）
+   明确表示旧名字挡路，且无法通过新增绕开；
+2. **有迁移路径**：新名字先发布、旧名字标 deprecated、`replacement` 字段非空
+   （`deprecation-gate.py` ⑥ 会验证替代品真的存在）；
+3. **有账**：写进 `docs/DEPRECATIONS.md`，并让 `deprecation-gate.py` 的
+   `retroactive` 计数**不增加** —— 那条是棘轮，只许降。
+
+不满足就只有一个选项：**新增，不动旧的**。
+本库已经这样做过多次（`metric` 与 `delta` 并存、`page.css` 里 `.cmp` 家族
+替代 22 份页内副本），代价是多几十行 CSS，收益是没人被迫改代码。
+
+---
+
+## 6 · 诚实边界：这份承诺覆盖不到的地方
+
+写出来，是因为"不说清就等于假绿"：
+
+- **事件名**（`fl:select` 等 6 个）只在基线里，**没有运行时探针**。
+  删了它，`deprecation-gate` 会红，但没有东西能证明它还会触发。
+- **`data-*` 属性值**（`data-state="loading"`、`data-shell-nav`）不在
+  `surface.baseline.json` 的自动采集里 —— 它们在 §2 表里是**人写的承诺**，
+  不是机器守的。
+- **视觉像素**。`10-review/shots/` 的 61 张基线只防"我们自己拍到的这些页面"，
+  下游自己组装的页面会怎么变，量不到。
+- **CSS 变量在 `@media` 里的重定义**（如强制色分支）。选择器结构和
+  `forced-colors-check.js` 覆盖了 7 类缺陷，但"用户自己的强制色主题"没有。
+
+---
+
+## 7 · 怎么确认冻结没被破坏
+
+```bash
+python3 05-audit/deprecation-gate.py     # 公开名字有没有无流程消失
+python3 05-audit/api-contract-gate.py    # d.ts 与运行时是否仍然一致
+node    05-audit/ai-layer-gate.js        # CLI 与契约文件是否仍可用
+python3 05-audit/perf-gate.py            # 体积有没有越线
+```
+
+四道全绿 ⇒ §2 的每一条都还成立。任何一道红，说明"冻结"已经被破坏，
+而破坏它的那次提交就在 `git log` 里 —— 这就是这份文件想要的效果：
+**让"我们改了什么"从记忆问题变成一个查询问题。**

package/esm/index.mjs

@@ -5,6 +5,7 @@ import '../02-primitives/combobox/combobox.js';
 import '../02-primitives/date-range/date-range.js';
 import '../02-primitives/popover/popover.js';
 import '../02-primitives/select/select.js';
+import '../02-primitives/upload/upload.js';
 import '../03-patterns/accordion/accordion.js';
 import '../03-patterns/drawer/drawer.js';
 import '../03-patterns/dropdown/dropdown.js';
@@ -24,6 +25,7 @@ export const Combobox = g.Combobox;
 export const DateRange = g.DateRange;
 export const Popover = g.Popover;
 export const Select = g.Select;
+export const Upload = g.Upload;
 export const Accordion = g.Accordion;
 export const Drawer = g.Drawer;
 export const Dropdown = g.Dropdown;

package/esm/upload.mjs

@@ -0,0 +1,7 @@
+/* ⚠️ 生成物，勿手改 —— 由 05-audit/gen-esm.py 从源码的 `global.X = …` 生成。
+   改源码后跑 `python3 05-audit/gen-esm.py` 重新生成，`--check` 会拦住漂移。 */
+import '../02-primitives/upload/upload.js';
+
+const g = typeof window !== 'undefined' ? window : globalThis;
+export const Upload = g.Upload;
+export default Upload;