base-paint 0.3.1 → 0.3.2

package/dist/controls.js

@@ -1,6 +1,6 @@
 /** base-paint/controls：#76 控件层运行时（契约 §3.3／§6.3）。
  *
- * 落地冻结面 44 条里 #76 的 13 条 `pending`（10 个运行时出口 ＋ 3 个类型出口）：
+ * 实施冻结面 44 条里 #76 的 13 条 `pending`（10 个运行时出口 ＋ 3 个类型出口）：
  * `copyText`／`createCopyRuntime`／`bindCopyAction`／`buildSharedHelpersJs`／
  * `renderToast`／`createToastController`／`renderActionBar`／`renderStatusBadge`／
  * `renderEmptyState`／`renderErrorReceipt`。签名逐字取 `src/spec/controls.ts`，本文件不改任何冻结值。
@@ -28,6 +28,12 @@
  *    `readDataText → undefined` 跳过）；`text === ''` → 仍写 `data-t=""`（binder 送进空串短路，无反馈）；
  *    场景按钮 `kind` 取冻结 `ACTION_BAR_KINDS` **全量**（含 `ghost`），不以 §3.3 表格的「primary／red」为限；
  *    `format` 不参与渲染（序列化归 #77）；
+ *  - `renderActionBar` 的 `CopyButtonInput.formats`（#247 三格式形态）→ 按钮只开合菜单、**不写** `data-t`，
+ *    菜单三项各写自己的 `data-t`（键取 `COPY_FORMATS`，值＝该格式已序列化文本）；菜单项的
+ *    `data-action-id` **留空**（三颗逐字不同的 id 与「同次渲染内唯一」口径不合，见
+ *    `CopyButtonInput.formats` 注释）；`formats` 与 `text` 同给 → `bad-input`；
+ *    `formats` 缺某个格式／非字符串 → `bad-input`；`hints` 非三个串 → `bad-input`；
+ *    菜单的开合／点外收起／选中后按该项 `data-t` 复制并报所选格式 → 归 helpers 运行时的委派；
  *  - `renderStatusBadge` 的 `text === ''` → 视为缺省（旧层口径）；非法 `status` 降级 `'empty'`（冻结语义）；
  *  - `renderEmptyState` 的 `actionHtml` → **受信 HTML 透传**（契约同口径，调用方负责其内容安全），可含
  *    内联 `onclick`；「零注入面」只约束 base-paint **自产**标记，不约束调用方透传的受信片段；
@@ -44,7 +50,7 @@
  *    （`base.js:96`）本就是页面侧代码。两侧分工见契约 §3.3「toast 移动端收窄的分工（FX-76-2）」。
  */
 import { STYLE_PREFIX } from './style.js';
-import { ACTION_BAR_DEFAULTS, ACTION_BAR_KINDS, ACTION_ID_ATTR, CONTROL_STYLE_SECTIONS, COPY_ACTION_IDS, COPY_TEXT_DEFAULTS, DEFAULT_DATA_ATTR, ESCAPE_HTML_CHARS, ESCAPE_HTML_ENTITIES, HELP_COPY_ACTIONS, HELP_SHELL_ID, STATUS_DEFAULT_TEXT, STATUS_KINDS, TOAST_DEFAULTS, } from './spec/index.js';
+import { ACTION_BAR_DEFAULTS, ACTION_BAR_KINDS, ACTION_ID_ATTR, CONTROL_STYLE_SECTIONS, COPY_ACTION_IDS, COPY_FORMATS, COPY_TEXT_DEFAULTS, DEFAULT_DATA_ATTR, ESCAPE_HTML_CHARS, ESCAPE_HTML_ENTITIES, HELP_COPY_ACTIONS, HELP_SHELL_ID, STATUS_DEFAULT_TEXT, STATUS_KINDS, TOAST_DEFAULTS, } from './spec/index.js';
 /* ── 错误形态（§3.3：与既有 RenderError 并列、互不继承、一律抛出、不返空） ── */
 /** 控件层错误。**不**从 `src/index.ts` 导出：`SPEC_FROZEN_SURFACE` 44 条内无该运行时条目，
  *  调用方按 `name === 'ControlsError'` ＋ `code` 判定（与 `fillTemplate` 的 `TemplateError` 同口径）。 */
@@ -85,15 +91,17 @@ function isStatusKind(value) {
     return STATUS_KINDS.includes(value);
 }
 /* ── toast（`renderToast` ＋ `createToastController`） ─────────────────── */
-/** 图标字形：`TOAST_ICONS` 是**冻结的枚举名**（不是字形），字形属文档未规定项（旧层 `base.js:74` 同值）。 */
-const TOAST_ICON_GLYPHS = Object.freeze({
+/** 图标字形：`TOAST_ICONS` 是**冻结的枚举名**（不是字形），字形属文档未规定项（旧层 `base.js:74` 同值）。
+ *  **导出（#154）**：区块层 B-12 的「页内静态提示」形态要把同一个图标放进浅色块里，
+ *  字形只此一份（`blocks.ts` 引用本表，不另抄）；本表**不进** `src/index.ts` 出口面。 */
+export const TOAST_ICON_GLYPHS = Object.freeze({
     copy: '📋',
     ok: '✅',
     warn: '⚠️',
     danger: '❌',
     info: '💡',
 });
-/** 徽章类型白名单：取冻结类型 `ToastBadge['type']` 的成员（非法值回落 `'ok'`，旧层口径）。 */
+/** 徽章类型允许清单：取冻结类型 `ToastBadge['type']` 的成员（非法值回落 `'ok'`，旧层口径）。 */
 const TOAST_BADGE_TYPES = ['ok', 'warn', 'danger'];
 /** 关闭按钮文案（文档无规定；沿用旧基线 `✓ 知道了`）。 */
 const TOAST_CLOSE_LABEL = '✓ 知道了';
@@ -347,7 +355,7 @@ export const createCopyRuntime = (ports) => {
  *  - id 来源**只有** `port.listActionIds()`：不猜 id、不通配前缀、不订阅未列出的 id；
  *  - 重复 id 由 binder 自行去重（同一 id 只订阅一次）；
  *  - 激活时读 `port.readDataText(actionId)`：非字符串（含 `undefined`）→ 跳过（不抛错、不产 toast），
- *    非复制按钮（场景按钮）即由此跳过，不另设白名单；
+ *    非复制按钮（场景按钮）即由此跳过，不另设允许清单；
  *  - 反馈一律走 `ports.toast`（`copyText` 内部），binder 不另出反馈；
  *  - **激活回调恒不产生未处理拒绝**（FX-76-6）：`copyText` 正常路径的失败已在内部 `settle()` 处理，
  *    这里只兜「逃出 `copyText` 的异常」（端口实现抛错／`ports.toast.mount` 抛错／回调抛错）——
@@ -417,7 +425,7 @@ function helpersDataAttr(input) {
 function styleSectionSlug(section) {
     return section.replace(/[A-Z]/g, (ch) => '-' + ch.toLowerCase());
 }
-/** HELP 壳类名命名空间 kebab 后缀（`help-shell`；缺省前缀下根 = `ilife-help-shell`）。
+/** HELP模板类名命名空间 kebab 后缀（`help-shell`；缺省前缀下根 = `ilife-help-shell`）。
  *  **延迟求值**（不在模块顶层）：`style.ts → charts.ts → controls.ts → style.ts` 存在模块环，
  *  顶层读 `STYLE_PREFIX` 会在 `style.js` 初始化完成前触发 TDZ（实测 `ReferenceError`），
  *  故派生式只在 `buildSharedHelpersJs()` **调用时**执行（此时全部模块已初始化）。 */
@@ -475,7 +483,7 @@ const HELP_HIT_EMPTY = '没有找到相关场景,换个词试试～';
  *
  *  **#88 S4 追加（HELP 速查台运行时增强；文档无规定 → 本文记账）**：全部挂进**既有 `boot()`**、
  *  共用**既有幂等 marker**（`MARKER_SEL` ＋ `querySelector` 早退），**不新增第二个标记**；每一项都
- *  先判 HELP 壳是否在页面（helpers 被所有技能页面共享，非 HELP 页逐项早退、零副作用）：
+ *  先判 HELP模板是否在页面（helpers 被所有技能页面共享，非 HELP 页逐项早退、零副作用）：
  *  - **卡级复制按钮**（`card-copy`）：每张场景卡的**卡头**注入 1 个按钮，`actionId`／文案恒读
  *    `HELP_COPY_ACTIONS.prompt`，`dataAttr` 取同卡 `<pre class="prompt">` 的原文（＝该卡 prompt 逐字；
  *    #88 S5 起改以 `<pre>` 为**主源**，读不到才回落 Sheet 内 prompt 按钮的 data-t），
@@ -502,7 +510,7 @@ export const buildSharedHelpersJs = (input) => {
     const dataAttr = helpersDataAttr(input);
     const markerAttr = 'data-' + prefix.replace(/-+$/, '') + '-helpers';
     const markerSelector = '[' + markerAttr + '="1"]';
-    // #88 S4：HELP 壳命名空间（缺省 `ilife-help-shell`；`prefix` 覆盖时随动，不残留缺省前缀）。
+    // #88 S4：HELP模板命名空间（缺省 `ilife-help-shell`；`prefix` 覆盖时随动，不残留缺省前缀）。
     const shellClass = prefix + helpShellSlug();
     const shellPart = (suffix) => shellClass + '-' + suffix;
     const promptAttr = 'data-' + prefix.replace(/-+$/, '') + '-help-prompt';
@@ -518,15 +526,21 @@ export const buildSharedHelpersJs = (input) => {
         '  var STACK_CLASS = ' + jsStr(prefix + 'toast-stack') + ';',
         '  var TOAST_CLASS = ' + jsStr(prefix + 'toast') + ';',
         '  var ICON_CLASS = ' + jsStr(prefix + 'toast-icon') + ';',
-        '  var ICON_GLYPH = ' + jsStr(TOAST_ICON_GLYPHS[TOAST_DEFAULTS.defaultIcon]) + ';',
+        '  var ICON_OK = ' + jsStr(TOAST_ICON_GLYPHS.copy) + ';',
+        '  var ICON_FAIL = ' + jsStr(TOAST_ICON_GLYPHS.danger) + ';',
+        '  var CHIP_CLASS = ' + jsStr(prefix + 'toast-chip') + ';',
+        '  var CHIP_DANGER_CLASS = ' + jsStr(prefix + 'toast-chip-danger') + ';',
         '  var TITLE_CLASS = ' + jsStr(prefix + 'toast-title') + ';',
         '  var BODY_CLASS = ' + jsStr(prefix + TOAST_BODY_CLASS) + ';',
         '  var TITLE_ROW_CLASS = ' + jsStr(prefix + TOAST_TITLE_ROW_CLASS) + ';',
         '  var DETAIL_CLASS = ' + jsStr(prefix + TOAST_DETAIL_CLASS) + ';',
         '  var CLOSE_CLASS = ' + jsStr(prefix + TOAST_CLOSE_CLASS) + ';',
         '  var OK_MSG = ' + jsStr(COPY_TEXT_DEFAULTS.okMessage) + ';',
+        '  var OK_DETAIL = ' + jsStr(COPY_TEXT_DEFAULTS.okDetail) + ';',
         '  var FAIL_MSG = ' + jsStr(COPY_TEXT_DEFAULTS.failMessage) + ';',
         '  var FAIL_DETAIL = ' + jsStr(COPY_TEXT_DEFAULTS.failDetail) + ';',
+        // 失败徽章文案取 `STATUS_DEFAULT_TEXT.danger`（与静态产出器 `copyText` 的失败徽章同一处常量，不产第二份真相）
+        '  var FAIL_BADGE = ' + jsStr(STATUS_DEFAULT_TEXT.danger) + ';',
         '  var CLOSE_LABEL = ' + jsStr(TOAST_CLOSE_LABEL) + ';',
         '  var TIMEOUT_MS = ' + TOAST_DEFAULTS.timeoutMs + ';',
         '  var MAX_STACK = ' + TOAST_DEFAULTS.maxStack + ';',
@@ -534,6 +548,16 @@ export const buildSharedHelpersJs = (input) => {
         '  var MOBILE_MAX_PX = ' + TOAST_DEFAULTS.mobileMaxPx + ';',
         '  var LF = String.fromCharCode(10);',
         '  var LF2 = LF + LF;',
+        // #247：复制数据的三格式形态（菜单开合器 ＋ 格式菜单项）。开合标记／格式键都是**属性**，
+        // 菜单容器、菜单项与按钮的共同父节点走类名——四者与渲染端（`copyMenuHtml`）逐字同值，
+        // 不产第二份真相。
+        '  var MENU_OPEN_SEL = ' + jsStr('[' + COPY_MENU_OPEN_ATTR + '="1"]') + ';',
+        '  var MENU_ITEM_SEL = ' + jsStr('[' + COPY_MENU_FMT_ATTR + ']') + ';',
+        '  var MENU_WRAP_CLASS = ' + jsStr(prefix + COPY_MENU_WRAP_CLASS) + ';',
+        '  var MENU_CLASS = ' + jsStr(prefix + COPY_MENU_CLASS) + ';',
+        '  var MENU_LABEL_CLASS = ' + jsStr(prefix + COPY_MENU_LABEL_CLASS) + ';',
+        '  var MENU_OPEN_CLASS = ' + jsStr(COPY_MENU_OPEN_CLASS) + ';',
+        '  var FORMAT_OK_MSG = ' + jsStr(COPY_FORMAT_OK_MSG) + ';',
         // #88 S4：HELP 速查台类名／选择器（同一命名空间，逐条由 `shellClass` 派生）
         '  var SHELL_SEL = ' + jsStr('.' + shellClass) + ';',
         '  var CARD_CLASS = ' + jsStr(shellPart('card')) + ';',
@@ -608,34 +632,93 @@ export const buildSharedHelpersJs = (input) => {
         '      if (box && box.parentNode) box.parentNode.removeChild(box);',
         '      return;',
         '    }',
+        '    if (onMenuClick(node)) return;',
         '    var btn = node.closest("[" + ACTION_ATTR + "]");',
         '    if (!btn) return;',
+        // 点同一行另一颗复制按钮（复制日志／复制指令）时顺手收起菜单：与「点别处收起」同效，
+        // 且不影响它自己的复制（菜单与按钮是两个互不干扰的路径）。
+        '    var menuOpen = document.querySelector("." + MENU_OPEN_CLASS);',
+        '    if (menuOpen) closeMenu(menuOpen.parentNode);',
         '    var text = btn.getAttribute(TEXT_ATTR);',
         '    if (text === null) return;',
         '    copy(text, btn);',
         '  }',
         '',
-        '  function copy(text, btn) {',
+        '  /* #247：复制数据的三格式形态——按钮（`data-fmt-open`）只开合菜单，菜单项（`data-fmt`）各自带',
+        '     自己的 `data-t`。两条分支都排在复制委派**之前**：开合器**没有** `data-action-id`，故不会与',
+        '     复制委派抢同一次点击；菜单项走复制但**不用** id 反查（读被点击元素自己的属性，与 HELP 速查台',
+        '     逐行写同一冻结 id 的口径一致）。返回真＝本次点击已被菜单消费。 */',
+        '  function onMenuClick(node) {',
+        '    var opener = node.closest(MENU_OPEN_SEL);',
+        '    if (!opener) {',
+        '      /* 菜单项：处理完**直接返回**，不下落到复制委派——它没有 `data-action-id`，落下去只会空转。',
+        '         复制仍然走同一条 `copy()`（双通道 ＋ `copied` 态 ＋ 提示），只是多了「报所选格式」这一项。 */',
+        '      var item = node.closest(MENU_ITEM_SEL);',
+        '      if (item) {',
+        '        var itemText = item.getAttribute(TEXT_ATTR);',
+        '        var itemWrap = item.closest("." + MENU_WRAP_CLASS);',
+        '        if (itemWrap) closeMenu(itemWrap);',
+        '        var itemLabel = item.querySelector("." + MENU_LABEL_CLASS);',
+        '        copy(itemText, item, itemLabel ? itemLabel.textContent : "");',
+        '        return true;',
+        '      }',
+        '      /* 点别处收起（老仓 `document` 上那条「不在 .fmt-wrap 里就收起」的同效）：',
+        '         页面上最多只开一个菜单，故扫到开着的就收。 */',
+        '      var open = document.querySelector("." + MENU_OPEN_CLASS);',
+        '      if (open) closeMenu(open.parentNode);',
+        '      return false;',
+        '    }',
+        '    var wrap = opener.closest("." + MENU_WRAP_CLASS);',
+        '    if (!wrap) return true;',
+        '    var menu = wrap.querySelector("." + MENU_CLASS);',
+        '    if (menu) toggleMenu(opener, menu);',
+        '    return true;',
+        '  }',
+        '',
+        '  /* 开合只翻**可视态**（`copy-menu-open` 类 ＋ `aria-expanded`），**不动 DOM**（#249 返修）：',
+        '     菜单是浮层，层叠归 CSS（`position:absolute` ＋ `z-index:20`），不在常规流里；而 DOM 序＝内容序',
+        '     ——ghost 行是两列网格、按序铺格，开时搬一颗，两颗就换位，且收起时回不去。 */',
+        '  function toggleMenu(opener, menu) {',
+        '    var open = hasClass(menu, MENU_OPEN_CLASS);',
+        '    if (open) {',
+        '      removeClass(menu, MENU_OPEN_CLASS);',
+        '      opener.setAttribute("aria-expanded", "false");',
+        '      return;',
+        '    }',
+        '    addClass(menu, MENU_OPEN_CLASS);',
+        '    opener.setAttribute("aria-expanded", "true");',
+        '  }',
+        '',
+        '  function closeMenu(wrap) {',
+        '    if (!wrap) return;',
+        '    var opener = wrap.querySelector(MENU_OPEN_SEL);',
+        '    var menu = wrap.querySelector("." + MENU_CLASS);',
+        '    if (!menu || !hasClass(menu, MENU_OPEN_CLASS)) return;',
+        '    removeClass(menu, MENU_OPEN_CLASS);',
+        '    if (opener) opener.setAttribute("aria-expanded", "false");',
+        '  }',
+        '',
+        '  function copy(text, btn, fmt) {',
         '    var clip = navigator.clipboard;',
         '    if (clip && typeof clip.writeText === "function") {',
         '      try {',
         '        var done = clip.writeText(text);',
         '        if (done && typeof done.then === "function") {',
-        '          done.then(function () { markCopied(btn); feedback(OK_MSG, false); }, function () { fallback(text, btn); });',
+        '          done.then(function () { markCopied(btn); feedback(OK_MSG, false, fmt); }, function () { fallback(text, btn, fmt); });',
         '          return;',
         '        }',
         '        markCopied(btn);',
-        '        feedback(OK_MSG, false);',
+        '        feedback(OK_MSG, false, fmt);',
         '        return;',
         '      } catch (err) {',
-        '        fallback(text, btn);',
+        '        fallback(text, btn, fmt);',
         '        return;',
         '      }',
         '    }',
-        '    fallback(text, btn);',
+        '    fallback(text, btn, fmt);',
         '  }',
         '',
-        '  function fallback(text, btn) {',
+        '  function fallback(text, btn, fmt) {',
         '    var sink = document.createElement("textarea");',
         '    sink.value = text;',
         '    sink.setAttribute("readonly", "readonly");',
@@ -648,7 +731,7 @@ export const buildSharedHelpersJs = (input) => {
         '    try { done = document.execCommand("copy"); } catch (err) { done = false; }',
         '    if (sink.parentNode) sink.parentNode.removeChild(sink);',
         '    if (done) markCopied(btn);',
-        '    feedback(done ? OK_MSG : FAIL_MSG, !done);',
+        '    feedback(done ? OK_MSG : FAIL_MSG, !done, fmt);',
         '  }',
         '',
         '  /* #121（H-16 双反馈的按钮通道）：成功态加 `copied` 类，450ms 后移除。',
@@ -660,7 +743,7 @@ export const buildSharedHelpersJs = (input) => {
         '    setTimeout(function () { removeClass(btn, COPIED_CLASS); }, COPIED_MS);',
         '  }',
         '',
-        '  function feedback(msg, bad) {',
+        '  function feedback(msg, bad, fmt) {',
         '    var cap = MAX_STACK;',
         '    if (window.matchMedia && window.matchMedia("(max-width: " + MOBILE_MAX_PX + "px)").matches) cap = MOBILE_MAX_STACK;',
         '    var host = document.querySelector("." + STACK_CLASS);',
@@ -686,22 +769,31 @@ export const buildSharedHelpersJs = (input) => {
         '    var icon = document.createElement("span");',
         '    icon.className = ICON_CLASS;',
         '    icon.setAttribute("aria-hidden", "true");',
-        '    icon.textContent = ICON_GLYPH;',
+        '    icon.textContent = bad ? ICON_FAIL : ICON_OK;',
         '    var body = document.createElement("div");',
         '    body.className = BODY_CLASS;',
         '    var titleRow = document.createElement("div");',
         '    titleRow.className = TITLE_ROW_CLASS;',
         '    var title = document.createElement("span");',
         '    title.className = TITLE_CLASS;',
-        '    title.textContent = msg;',
+        // #247：选了格式的那条**成功**提示报所选格式（「数据复制成功（纯文本／JSON／CSV）」）——格式名取
+        // 菜单项的标签文本（渲染期写死的那个键），不在运行时里另立一张中文表，选一个格式＝一个提示。
+        // **失败提示照旧**（`FAIL_MSG` ＋ ❌ ＋「失败」徽章）：失败与格式无关，别把它也套上格式名。
+        '    title.textContent = bad ? msg : (fmt ? FORMAT_OK_MSG + "（" + fmt + "）" : msg);',
         '    titleRow.appendChild(title);',
-        '    body.appendChild(titleRow);',
+        // 5a（2026-09-12 用户裁定「UI 上要统一」）：失败态与静态产出器／老仓同形——红底「失败」徽章进标题行。
         '    if (bad) {',
-        '      var detail = document.createElement("div");',
-        '      detail.className = DETAIL_CLASS;',
-        '      detail.textContent = FAIL_DETAIL;',
-        '      body.appendChild(detail);',
+        '      var chip = document.createElement("span");',
+        '      chip.className = CHIP_CLASS + " " + CHIP_DANGER_CLASS;',
+        '      chip.textContent = FAIL_BADGE;',
+        '      titleRow.appendChild(chip);',
         '    }',
+        '    body.appendChild(titleRow);',
+        // 详情行两态都有：成功「粘贴给 AI」、失败「长按选择文本手动复制」（都取 `COPY_TEXT_DEFAULTS`，与老仓逐字同）。
+        '    var detail = document.createElement("div");',
+        '    detail.className = DETAIL_CLASS;',
+        '    detail.textContent = bad ? FAIL_DETAIL : OK_DETAIL;',
+        '    body.appendChild(detail);',
         '    box.appendChild(icon);',
         '    box.appendChild(body);',
         '    var close = document.createElement("button");',
@@ -756,7 +848,7 @@ export const buildSharedHelpersJs = (input) => {
         '  /* 卡级复制按钮（#88 R1-1）：卡头注入 1 个按钮——actionId／文案恒读冻结常量，',
         '     文本取同卡 `<pre class="prompt">` 的**原文**（＝该卡 prompt 逐字，与 F3 卡面同源）；',
         '     读不到 <pre> 才回落同卡 Sheet 内 prompt 按钮的 data-t，两者都无才跳过',
-        '     （#88 S5／B 段红队 S3-a：真实壳恒有 <pre>，故 436/436 恒有按钮，不静默丢卡）→ 复用既有委派。 */',
+        '     （#88 S5／B 段红队 S3-a：真实help模板恒有 <pre>，故 436/436 恒有按钮，不静默丢卡）→ 复用既有委派。 */',
         '  function injectCardCopy(cards) {',
         '    for (var i = 0; i < cards.length; i++) {',
         '      var card = cards[i];',
@@ -831,7 +923,7 @@ export const buildSharedHelpersJs = (input) => {
         '  }',
         '',
         '  /* 复制按钮文本同步：prompt 目标（卡头 ＋ Sheet 内）＝ 预览文本；params 目标＝label: value 行，',
-        '     无字段时回落该卡 CLI 文本（与冻结壳 paramsText 同口径）。 */',
+        '     无字段时回落该卡 CLI 文本（与冻结help模板 paramsText 同口径）。 */',
         '  function syncCopyText(card, text, lines) {',
         '    var buttons = allOf(card, "[" + ACTION_ATTR + "]");',
         '    for (var i = 0; i < buttons.length; i++) {',
@@ -1052,15 +1144,88 @@ function normalizeButtons(buttons) {
         };
     });
 }
+/** 菜单形态的标记属性（#247；运行时委派据它分辨「开合菜单的按钮」与「直接复制的按钮」）。
+ *  该按钮**不写** `data-action-id`：它不是复制目标、也不是复制动作——点击的效果是开合菜单。
+ *  `CopyActionHostPort.listActionIds()` 与 `bindCopyAction` 因此天然不碰它（无需为此改冻结签名）。 */
+const COPY_MENU_OPEN_ATTR = 'data-fmt-open';
+/** 菜单项的**格式键**承载属性（三格式形态里唯一分辨三项的东西——值取 `COPY_FORMATS`）。
+ *  与老仓逐字同名：老仓 `.fmt-item` 就是靠 `data-fmt` 分辨纯文本／JSON／CSV。 */
+const COPY_MENU_FMT_ATTR = 'data-fmt';
+/** 格式菜单容器与按钮的共同父节点类名（运行时据**最近的这个父节点**开合／收起菜单）。 */
+const COPY_MENU_WRAP_CLASS = 'copy-menu-wrap';
+/** 菜单容器自身的类名（浮动那一层）。 */
+const COPY_MENU_CLASS = 'copy-menu';
+/** 菜单项的类名。 */
+const COPY_MENU_ITEM_CLASS = 'copy-menu-item';
+/** 菜单项**标签**文本的类名（`data-fmt` 只放格式键；标签是给人看的中文名，见 `COPY_FORMAT_LABELS`）。 */
+const COPY_MENU_LABEL_CLASS = 'copy-menu-label';
+/** 菜单项**可见标签**：格式键 → 中文名（#496）。
+ *
+ *  `data-fmt` 是机器面（键值恒为 `COPY_FORMATS` 成员，运行时与测试都按它分辨三项），
+ *  **上屏的是这张表的中文名**——原先是把格式键直接印给用户看，菜单点开是 `text` / `json` / `csv`
+ *  三个小写英文词，读不懂（`.scratch/t155o/text-review-P0.md` 第 20／44 条，卡路里 81 页 ＋
+ *  饼干记账的复制区页同形）。`JSON` 与 `CSV` 是这个仓既有写法里的通用缩写，保留原样。
+ *  运行时「数据复制成功（〈标签〉）」那条提示读回的就是这里的值，故它跟着一起变中文。 */
+const COPY_FORMAT_LABELS = { text: '纯文本', json: 'JSON', csv: 'CSV' };
+/** 菜单项**用途提示**（老仓原样：`粘贴给 AI / 自己看`／`结构化存档`／`表格导入`）的类名。
+ *  老仓靠 `.fmt-item span`（后代选择器）收这行灰小字；本仓**显式给类名**——一是不用后代选择器
+ *  把标签也一并染成 11px 灰（`.copy-menu-item span` 会连窗口里两个 span 一起命中），
+ *  二是 CSS 里每个类名都要指得出产出者（`style.test.mjs` T10）。 */
+const COPY_MENU_HINT_CLASS = 'copy-menu-hint';
+/** 菜单**开着**时加在容器上的类（`opacity` / `visibility` 的开合开关；`aria-expanded` 同步）。 */
+const COPY_MENU_OPEN_CLASS = 'copy-menu-open';
+/** 开合器 `aria-label` 的后半句（**#525 第二轮**：可见文字里的 `▾` 已删，那句「可以选格式」改住这里）。
+ *
+ *  为什么删那个字符：用户裁定第 5 条逐字「该问题是用这些符号简化了 UI 展示的设计」——
+ *  `复制数据 ▾` 里的三角是「这里能展开」的纯装饰，用一个字形顶替了一次设计。现在三角由
+ *  `style.ts` copyButton 区的 `::after` 用 `border` ＋ `rotate` 画出来（零字符），
+ *  而**语义不留白**：这句写进 `aria-label`，读屏与抓取器仍读得出「这颗按钮要选格式」。 */
+const COPY_MENU_OPENER_ARIA = '（点开选格式）';
+/** 选中某个格式后的成功提示词干（老仓 `.fmt-menu` 那张菜单当年报的是「…数据复制成功(格式)」；
+ *  本仓句头沿用既有「已复制」以外的**独立**一句，避免与单格式提示混同）。格式名由运行时从菜单项
+ *  标签读回（即 `COPY_FORMAT_LABELS` 的中文名），不在运行时另立第二张表。 */
+const COPY_FORMAT_OK_MSG = '数据复制成功';
+/** 三格式形态的校验 ＋ 归一（#247）：与 `text` 互斥；三格式恒齐、值恒为串；`hints` 恒三串。 */
+function normalizeFormats(formats, field, hasText) {
+    if (formats === undefined || formats === null)
+        return undefined;
+    assertPlainObject(formats, 'renderActionBar: input.' + field + '.formats');
+    if (hasText)
+        badInput('renderActionBar: input.' + field + '.formats 与 .text 只能给一个');
+    const texts = [];
+    for (const key of COPY_FORMATS) {
+        const value = formats[key];
+        if (typeof value !== 'string')
+            badInput('renderActionBar: input.' + field + '.formats.' + key + ' 必须是字符串');
+        texts.push(value);
+    }
+    const rawHints = formats.hints;
+    if (rawHints === undefined || rawHints === null)
+        return { texts, hints: [] };
+    if (!Array.isArray(rawHints) || rawHints.length !== COPY_FORMATS.length) {
+        badInput('renderActionBar: input.' + field + '.formats.hints 必须是 ' + COPY_FORMATS.length + ' 个字符串');
+    }
+    const hints = [];
+    for (const hint of rawHints) {
+        if (typeof hint !== 'string')
+            badInput('renderActionBar: input.' + field + '.formats.hints 必须是字符串');
+        hints.push(hint);
+    }
+    return { texts, hints };
+}
 function normalizeCopyButton(input, fallbackLabel, field) {
     if (input === undefined || input === null)
         return null;
     assertPlainObject(input, 'renderActionBar: input.' + field);
     assertNoInlineHandler(input, 'renderActionBar: input.' + field);
+    const button = input;
+    const formats = normalizeFormats(button.formats, field, typeof button.text === 'string');
     return {
-        label: typeof input.label === 'string' && input.label !== '' ? input.label : fallbackLabel,
-        actionId: assertActionId(input.actionId, 'renderActionBar: input.' + field + '.actionId'),
-        text: typeof input.text === 'string' ? input.text : undefined,
+        label: typeof button.label === 'string' && button.label !== '' ? button.label : fallbackLabel,
+        actionId: assertActionId(button.actionId, 'renderActionBar: input.' + field + '.actionId'),
+        text: typeof button.text === 'string' ? button.text : undefined,
+        // 三格式形态的按钮是**菜单开合器**，不是复制目标：`data-t` 恒缺（点了不直接复制）。
+        ...(formats === undefined ? {} : { formats }),
     };
 }
 function sceneButtonHtml(button) {
@@ -1069,8 +1234,42 @@ function sceneButtonHtml(button) {
 }
 function copyButtonHtml(button) {
     const textAttr = button.text === undefined ? '' : ' ' + DEFAULT_DATA_ATTR + '="' + esc(button.text) + '"';
+    const disabledAttr = button.disabled === true ? ' disabled' : '';
     return '<button type="button" class="' + STYLE_PREFIX + 'copy-btn ' + STYLE_PREFIX + 'copy-btn-ghost" '
-        + ACTION_ID_ATTR + '="' + esc(button.actionId) + '"' + textAttr + '>' + esc(button.label) + '</button>';
+        + ACTION_ID_ATTR + '="' + esc(button.actionId) + '"' + textAttr + disabledAttr + '>' + esc(button.label) + '</button>';
+}
+/** 复制数据的**三格式形态**（#247）：`<div class="ilife-copy-menu-wrap">` 里一颗开合器 ＋ 一个菜单。
+ *
+ *  按钮：`data-fmt-open` 是**开合标记**（不是 `data-action-id`——见 `COPY_MENU_OPEN_ATTR` 注释），
+ *  带 `aria-haspopup`／`aria-expanded`（`aria-expanded` 由运行时翻转）；
+ *  菜单：三个格式项，每项 `data-fmt="键"`（键取 `COPY_FORMATS`）＋ 自己的 `data-t`（该格式文本），
+ *  标签与用途提示取 `formats.hints`（对应位）。零内联脚本：开合与选中一律归 helpers 运行时的委派。
+ *  菜单容器**不加 `hidden`**：它是浮层，用 CSS 的 `opacity` 开合（`hidden` 的 `display:none` 会让浏览器
+ *  把 `opacity` 过渡整个跳过，且开合时重排整页——手机档上会看到内容跳一下）。 */
+function copyMenuHtml(button, formats) {
+    // #525 第二轮：开合器**不再把 `▾` 打上屏**（用户裁定第 5 条「用符号简化了 UI 展示的设计」是债）。
+    // 这颗三角是「这里可以展开」的纯装饰，可见文字里删掉、改由 CSS 画（`style.ts` 的 copyButton 区
+    // `.ilife-copy-menu-wrap > .ilife-copy-btn::after`，`border` ＋ `transform: rotate`，一个字符都不打）。
+    // 删字符不能删语义：`aria-label` 里把那句「可以选格式」写成文字（读屏与无图形环境仍读得出）。
+    const openLabel = button.label;
+    const items = [];
+    for (let i = 0; i < COPY_FORMATS.length; i += 1) {
+        const key = COPY_FORMATS[i];
+        const hint = formats.hints[i];
+        const hintHtml = hint === undefined || hint === '' ? '' : '<span class="' + STYLE_PREFIX + COPY_MENU_HINT_CLASS + '">' + esc(hint) + '</span>';
+        items.push('<button type="button" class="' + STYLE_PREFIX + COPY_MENU_ITEM_CLASS + '" ' + COPY_MENU_FMT_ATTR + '="' + esc(key) + '" '
+            + DEFAULT_DATA_ATTR + '="' + esc(formats.texts[i]) + '">'
+            + '<span class="' + STYLE_PREFIX + COPY_MENU_LABEL_CLASS + '">' + esc(COPY_FORMAT_LABELS[key] ?? key) + '</span>' + hintHtml + '</button>');
+    }
+    const opener = '<button type="button" class="' + STYLE_PREFIX + 'copy-btn ' + STYLE_PREFIX + 'copy-btn-ghost" '
+        + COPY_MENU_OPEN_ATTR + '="1" aria-haspopup="menu" aria-expanded="false" '
+        + 'aria-label="' + esc(openLabel + COPY_MENU_OPENER_ARIA) + '">' + esc(openLabel) + '</button>';
+    return '<div class="' + STYLE_PREFIX + COPY_MENU_WRAP_CLASS + '">' + opener
+        + '<div class="' + STYLE_PREFIX + COPY_MENU_CLASS + '" role="menu">' + items.join('') + '</div></div>';
+}
+/** 一颗复制按钮：单格式＝普通按钮（`actionId` ＋ 可选 `data-t`）；三格式＝菜单形态（见 `copyMenuHtml`）。 */
+function copyControlHtml(button) {
+    return button.formats === undefined ? copyButtonHtml(button) : copyMenuHtml(button, button.formats);
 }
 /** 冻结签名：`renderActionBar(input: ActionBarInput): string`。
  *
@@ -1078,13 +1277,26 @@ function copyButtonHtml(button) {
  *  （`ACTION_BAR_DEFAULTS.ghostOwnRow`）；复制文本渲染期写入 `DEFAULT_DATA_ATTR`、id 写入 `ACTION_ID_ATTR`，
  *  零内联脚本。缺 `actionId`／空串／同次渲染内重复 → `ControlsError` code `bad-input`。
  *  逐区尺寸（`minHeightPx`／`fontSizePx`／`fontWeight`／`ghostBorderAlpha`／`evenRowPairs`）由 #75 的
- *  共享样式区消费（本文件不产样式常量）。 */
+ *  共享样式区消费（本文件不产样式常量）。
+ *
+ *  #336 双按钮一行（base 侧兜底）：有数据位（`copyData` 在场）无日志位时自动补一颗禁用态复制日志
+ *  （文案／id 沿用 `ACTION_BAR_DEFAULTS.copyLogLabel`／`COPY_ACTION_IDS.actionBar.copyLog`，
+ *  无 `data-t` ＋ `disabled`，只占 ghost 行第二格，点不动、互不串味）。两边都在场／两边都不在场照旧；
+ *  仅日志位在场不补数据位。补位同样参与同次渲染内 id 唯一校验。 */
 export const renderActionBar = (input) => {
     assertPlainObject(input, 'renderActionBar: input');
     const bar = input;
     const buttons = normalizeButtons(bar.buttons);
     const copyData = normalizeCopyButton(bar.copyData, ACTION_BAR_DEFAULTS.copyDataLabel, 'copyData');
-    const copyLog = normalizeCopyButton(bar.copyLog, ACTION_BAR_DEFAULTS.copyLogLabel, 'copyLog');
+    let copyLog = normalizeCopyButton(bar.copyLog, ACTION_BAR_DEFAULTS.copyLogLabel, 'copyLog');
+    if (copyData !== null && copyLog === null) {
+        copyLog = {
+            label: ACTION_BAR_DEFAULTS.copyLogLabel,
+            actionId: COPY_ACTION_IDS.actionBar.copyLog,
+            text: undefined,
+            disabled: true,
+        };
+    }
     const ids = new Set();
     for (const button of buttons) {
         if (ids.has(button.actionId))
@@ -1099,7 +1311,7 @@ export const renderActionBar = (input) => {
         ids.add(copy.actionId);
     }
     const sceneHtml = buttons.map(sceneButtonHtml).join('');
-    const ghostHtml = [copyData, copyLog].filter((copy) => copy !== null).map(copyButtonHtml).join('');
+    const ghostHtml = [copyData, copyLog].filter((copy) => copy !== null).map(copyControlHtml).join('');
     const rowClass = STYLE_PREFIX + 'action-row';
     const ghostRowClass = rowClass + ' ' + STYLE_PREFIX + 'action-row-ghost';
     const rows = [];