base-paint 0.3.13 → 0.3.15

package/dist/components/controls/helpers.js

@@ -0,0 +1,630 @@
+/** controls · helpers
+ *
+ *  自 `src/controls.ts` 原样切出。
+ *
+ *  **住址**：目录化批次⑤把 `src/controls.ts` 按段切成「族内一件一文件」，正文原样搬来；
+ *  搬迁判据＝产物逐字节相同（五个渲染器 ＋ 共享 helpers JS ＋ 出口名单），
+ *  见 `docs/base/base-render/组件目录架构.md`。
+ */
+import { COPY_FORMAT_OK_MSG, COPY_MENU_CLASS, COPY_MENU_FMT_ATTR, COPY_MENU_LABEL_CLASS, COPY_MENU_OPEN_ATTR, COPY_MENU_OPEN_CLASS, COPY_MENU_WRAP_CLASS } from './action-bar.js';
+import { HELP_BACKTOP_ARIA, HELP_BACKTOP_ID, HELP_BACKTOP_LABEL, HELP_BACKTOP_MIN_Y, HELP_CLEAR_ARIA, HELP_CLEAR_LABEL, HELP_COPY_COPIED_CLASS, HELP_COPY_COPIED_MS, HELP_HIT_EMPTY, HELP_HIT_PREFIX, HELP_HIT_SUFFIX, HELP_SEARCH_ARIA, HELP_SEARCH_PLACEHOLDER, helpShellSlug, helpersDataAttr, helpersPrefix, jsStr } from './helpers-meta.js';
+import { TOAST_BODY_CLASS, TOAST_CLOSE_CLASS, TOAST_CLOSE_LABEL, TOAST_DETAIL_CLASS, TOAST_ICON_GLYPHS, TOAST_TITLE_ROW_CLASS } from './toast.js';
+import { ACTION_ID_ATTR, COPY_TEXT_DEFAULTS, HELP_COPY_ACTIONS, STATUS_DEFAULT_TEXT, TOAST_DEFAULTS } from '../../spec/index.js';
+export const buildSharedHelpersJs = (input) => {
+    const prefix = helpersPrefix(input);
+    const dataAttr = helpersDataAttr(input);
+    const markerAttr = 'data-' + prefix.replace(/-+$/, '') + '-helpers';
+    const markerSelector = '[' + markerAttr + '="1"]';
+    // #88 S4：HELP模板命名空间（缺省 `ilife-help-shell`；`prefix` 覆盖时随动，不残留缺省前缀）。
+    const shellClass = prefix + helpShellSlug();
+    const shellPart = (suffix) => shellClass + '-' + suffix;
+    const promptAttr = 'data-' + prefix.replace(/-+$/, '') + '-help-prompt';
+    const copyAction = HELP_COPY_ACTIONS.prompt;
+    const paramsAction = HELP_COPY_ACTIONS.params;
+    const lines = [
+        '(function () {',
+        "  'use strict';",
+        '  var MARKER_ATTR = ' + jsStr(markerAttr) + ';',
+        '  var MARKER_SEL = ' + jsStr(markerSelector) + ';',
+        '  var ACTION_ATTR = ' + jsStr(ACTION_ID_ATTR) + ';',
+        '  var TEXT_ATTR = ' + jsStr(dataAttr) + ';',
+        '  var STACK_CLASS = ' + jsStr(prefix + 'toast-stack') + ';',
+        '  var TOAST_CLASS = ' + jsStr(prefix + 'toast') + ';',
+        '  var ICON_CLASS = ' + jsStr(prefix + 'toast-icon') + ';',
+        '  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 + ';',
+        '  var MOBILE_MAX_STACK = ' + TOAST_DEFAULTS.mobileMaxStack + ';',
+        '  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')) + ';',
+        '  var CARD_TOP_CLASS = ' + jsStr(shellPart('card-top')) + ';',
+        '  var CARD_COPY_CLASS = ' + jsStr(shellPart('card-copy')) + ';',
+        '  var CARD_MARK_CLASS = ' + jsStr(shellPart('card-mark')) + ';',
+        '  var CARD_HIDDEN_CLASS = ' + jsStr(shellPart('card-hidden')) + ';',
+        '  var SHEET_CLASS = ' + jsStr(shellPart('sheet')) + ';',
+        '  var PROMPT_CLASS = ' + jsStr(shellPart('prompt')) + ';',
+        '  var PROMPT_ATTR = ' + jsStr(promptAttr) + ';',
+        '  var FIELD_CLASS = ' + jsStr(shellPart('field')) + ';',
+        '  var FIELD_LABEL_CLASS = ' + jsStr(shellPart('field-label')) + ';',
+        '  var FIELD_VALUE_CLASS = ' + jsStr(shellPart('field-value')) + ';',
+        '  var FIELD_HINT_CLASS = ' + jsStr(shellPart('field-hint')) + ';',
+        '  var FIELD_INPUT_CLASS = ' + jsStr(shellPart('field-input')) + ';',
+        '  var TAB_BAR_CLASS = ' + jsStr(shellPart('tab-bar')) + ';',
+        '  var TAB_INPUT_CLASS = ' + jsStr(shellPart('tab-input')) + ';',
+        '  var SEARCH_BOX_CLASS = ' + jsStr(shellPart('tab-search')) + ';',
+        '  var SEARCH_INPUT_CLASS = ' + jsStr(shellPart('tab-search-input')) + ';',
+        '  var SEARCH_CLEAR_CLASS = ' + jsStr(shellPart('tab-search-clear')) + ';',
+        '  var HITCOUNT_CLASS = ' + jsStr(shellPart('page-hitcount')) + ';',
+        '  var PAGE_CLASS = ' + jsStr(shellPart('page')) + ';',
+        '  var SUBGROUP_CLASS = ' + jsStr(shellPart('subgroup')) + ';',
+        '  var SUBGROUP_HIDDEN_CLASS = ' + jsStr(shellPart('subgroup-hidden')) + ';',
+        '  var CLI_CLASS = ' + jsStr(shellPart('cli')) + ';',
+        '  var BACKTOP_CLASS = ' + jsStr(shellPart('btn-backtop')) + ';',
+        '  var BACKTOP_SHOW_CLASS = ' + jsStr(shellPart('btn-backtop-show')) + ';',
+        '  var BACKTOP_ID = ' + jsStr(HELP_BACKTOP_ID) + ';',
+        '  var BACKTOP_MIN_Y = ' + HELP_BACKTOP_MIN_Y + ';',
+        '  var BACKTOP_LABEL = ' + jsStr(HELP_BACKTOP_LABEL) + ';',
+        '  var BACKTOP_ARIA = ' + jsStr(HELP_BACKTOP_ARIA) + ';',
+        '  var SEARCH_PLACEHOLDER = ' + jsStr(HELP_SEARCH_PLACEHOLDER) + ';',
+        '  var SEARCH_ARIA = ' + jsStr(HELP_SEARCH_ARIA) + ';',
+        '  var CLEAR_LABEL = ' + jsStr(HELP_CLEAR_LABEL) + ';',
+        '  var CLEAR_ARIA = ' + jsStr(HELP_CLEAR_ARIA) + ';',
+        '  var HIT_PREFIX = ' + jsStr(HELP_HIT_PREFIX) + ';',
+        '  var HIT_SUFFIX = ' + jsStr(HELP_HIT_SUFFIX) + ';',
+        '  var HIT_EMPTY = ' + jsStr(HELP_HIT_EMPTY) + ';',
+        '  var COPY_ACTION = ' + jsStr(copyAction.actionId) + ';',
+        '  var COPY_LABEL = ' + jsStr(copyAction.label) + ';',
+        '  var COPIED_CLASS = ' + jsStr(HELP_COPY_COPIED_CLASS) + ';',
+        '  var COPIED_MS = ' + HELP_COPY_COPIED_MS + ';',
+        '  var PARAMS_ACTION = ' + jsStr(paramsAction.actionId) + ';',
+        '  var searchTerm = "";',
+        '  var clickBound = false;',
+        // #88 S5（B 段红队 S3-a）：委派去重的**跨实例**判据——同一页面里 helpers 被多次注入时，
+        // 每个实例各有自己的闭包（`clickBound` 管不住别人），故在**事件对象**上打一次性标记：
+        // 同一事件只会被第一个处理器消费，一次点击恒只复制 1 次／出 1 个 toast。
+        '  var HANDLED_PROP = ' + jsStr(prefix + 'help-click-handled') + ';',
+        '',
+        '  function boot() {',
+        '    if (!document.body) return;',
+        '    if (document.querySelector(MARKER_SEL)) return;',
+        '    var marker = document.createElement("span");',
+        '    marker.setAttribute(MARKER_ATTR, "1");',
+        '    marker.hidden = true;',
+        '    document.body.appendChild(marker);',
+        // #88 S5（B 段红队 S3-a）：委派**只挂一次**——marker 被删后重入 boot() 不得重复 addEventListener，
+        // 否则一次点击触发 N 次复制／N 个 toast。按钮／搜索框／#backTop 各自的幂等由自身早退保证。
+        '    if (!clickBound) { clickBound = true; document.addEventListener("click", onClick); }',
+        '    initHelpShell();',
+        '  }',
+        '',
+        '  function onClick(ev) {',
+        '    if (ev[HANDLED_PROP]) return;',
+        '    ev[HANDLED_PROP] = 1;',
+        '    var node = ev.target;',
+        '    if (!node || typeof node.closest !== "function") return;',
+        '    var close = node.closest("." + CLOSE_CLASS);',
+        '    if (close) {',
+        '      var box = close.parentNode;',
+        '      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);',
+        '  }',
+        '',
+        '  /* #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, fmt); }, function () { fallback(text, btn, fmt); });',
+        '          return;',
+        '        }',
+        '        markCopied(btn);',
+        '        feedback(OK_MSG, false, fmt);',
+        '        return;',
+        '      } catch (err) {',
+        '        fallback(text, btn, fmt);',
+        '        return;',
+        '      }',
+        '    }',
+        '    fallback(text, btn, fmt);',
+        '  }',
+        '',
+        '  function fallback(text, btn, fmt) {',
+        '    var sink = document.createElement("textarea");',
+        '    sink.value = text;',
+        '    sink.setAttribute("readonly", "readonly");',
+        '    sink.setAttribute("aria-hidden", "true");',
+        '    sink.style.position = "fixed";',
+        '    sink.style.left = "-9999px";',
+        '    document.body.appendChild(sink);',
+        '    sink.select();',
+        '    var done = false;',
+        '    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, fmt);',
+        '  }',
+        '',
+        '  /* #121（H-16 双反馈的按钮通道）：成功态加 `copied` 类，450ms 后移除。',
+        '     只在**成功**分支调用 → 失败路径不静默变绿；类名走 className 字符串（addClass／removeClass），',
+        '     不用 DOM 的类名列表 API（纯度口径）；按钮缺失／已离页时 removeClass 仍安全（操作的是节点自身）。 */',
+        '  function markCopied(btn) {',
+        '    if (!btn) return;',
+        '    addClass(btn, COPIED_CLASS);',
+        '    setTimeout(function () { removeClass(btn, COPIED_CLASS); }, COPIED_MS);',
+        '  }',
+        '',
+        '  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);',
+        '    if (!host) {',
+        '      host = document.createElement("div");',
+        '      host.className = STACK_CLASS;',
+        '      document.body.appendChild(host);',
+        '    }',
+        '    var box = document.createElement("div");',
+        '    box.className = bad ? TOAST_CLASS + " " + TOAST_CLASS + "-danger" : TOAST_CLASS;',
+        '    box.setAttribute("role", ' + jsStr(TOAST_DEFAULTS.role) + ');',
+        '    box.setAttribute("aria-live", ' + jsStr(TOAST_DEFAULTS.ariaLive) + ');',
+        // W1 根因修（结构对齐）＋ F-c 图标：运行时 DOM 与静态产出器／旧层同构——
+        //   box > .toast-icon ＋ .toast-body(> .toast-title-row(> .toast-title) ＋ 可选 .toast-title-detail) ＋ .toast-close
+        // 旧层为 `.hm-toast-icon + .hm-toast-body(> .hm-toast-title-row + .hm-toast-detail) + .hm-toast-close`
+        // （`.scratch/t76/old-controls.md` §1.1）。图标字形取 `TOAST_ICON_GLYPHS[TOAST_DEFAULTS.defaultIcon]`
+        // （📋，旧层 `base.js:74`／契约 `:141` 缺省；与静态产出器 `renderToast` 同源，不产第二份真相）。
+        // 缺 body 包裹时标题／详情／关闭被排进同一 flex 行，
+        // 靠 `flex-wrap` ＋ `flex:1 1 100%` 补丁才勉强分层，且把关闭按钮挤到第三行（R1 实测 113px 高）。
+        // F-c 自证：新增仅用 `document.createElement／className／setAttribute／textContent／appendChild`
+        // （`SHARED_HELPERS_JS_RULE.domAllowed=true` 允许 DOM 读取；未向 `window／globalThis` 赋值、
+        // 未引 `node:`、未用 `classList／show`），故不破坏 #76 冻结产出内容契约与 T28 纯 CSS 动效断言。
+        '    var icon = document.createElement("span");',
+        '    icon.className = ICON_CLASS;',
+        '    icon.setAttribute("aria-hidden", "true");',
+        '    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;',
+        // #247：选了格式的那条**成功**提示报所选格式（「数据复制成功（纯文本／JSON／CSV）」）——格式名取
+        // 菜单项的标签文本（渲染期写死的那个键），不在运行时里另立一张中文表，选一个格式＝一个提示。
+        // **失败提示照旧**（`FAIL_MSG` ＋ ❌ ＋「失败」徽章）：失败与格式无关，别把它也套上格式名。
+        '    title.textContent = bad ? msg : (fmt ? FORMAT_OK_MSG + "（" + fmt + "）" : msg);',
+        '    titleRow.appendChild(title);',
+        // 5a（2026-09-12 用户裁定「UI 上要统一」）：失败态与静态产出器／老仓同形——红底「失败」徽章进标题行。
+        '    if (bad) {',
+        '      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");',
+        '    close.type = "button";',
+        '    close.className = CLOSE_CLASS;',
+        '    close.textContent = CLOSE_LABEL;',
+        '    box.appendChild(close);',
+        '    host.appendChild(box);',
+        '    while (host.children.length > cap) host.removeChild(host.children[0]);',
+        '    setTimeout(function () {',
+        '      if (box.parentNode) box.parentNode.removeChild(box);',
+        '    }, TIMEOUT_MS);',
+        '  }',
+        '',
+        // ── #88 S4：HELP 速查台运行时增强（见上方产出内容契约的记账；全部由既有 boot() 调用） ──
+        '  function initHelpShell() {',
+        '    var shell = document.querySelector(SHELL_SEL);',
+        '    if (!shell) return;',
+        '    var cards = allOf(shell, "." + CARD_CLASS);',
+        '    if (cards.length === 0) return;',
+        '    injectCardCopy(cards);',
+        '    initSheetPreview(cards);',
+        '    initSearch(shell, cards);',
+        '    initBackTop();',
+        '  }',
+        '',
+        '  function allOf(root, sel) {',
+        '    return Array.prototype.slice.call(root.querySelectorAll(sel));',
+        '  }',
+        '',
+        '  function attrSel(name, value) {',
+        '    return "[" + name + "=\\"" + value + "\\"]";',
+        '  }',
+        '',
+        '  function hasClass(el, name) {',
+        '    return (" " + el.className + " ").indexOf(" " + name + " ") > -1;',
+        '  }',
+        '',
+        '  function addClass(el, name) {',
+        '    if (hasClass(el, name)) return;',
+        '    el.className = el.className ? el.className + " " + name : name;',
+        '  }',
+        '',
+        '  function removeClass(el, name) {',
+        '    if (!el.className) return;',
+        '    var parts = el.className.split(" ");',
+        '    var kept = [];',
+        '    for (var i = 0; i < parts.length; i++) { if (parts[i] && parts[i] !== name) kept.push(parts[i]); }',
+        '    el.className = kept.join(" ");',
+        '  }',
+        '',
+        '  /* 卡级复制按钮（#88 R1-1）：卡头注入 1 个按钮——actionId／文案恒读冻结常量，',
+        '     文本取同卡 `<pre class="prompt">` 的**原文**（＝该卡 prompt 逐字，与 F3 卡面同源）；',
+        '     读不到 <pre> 才回落同卡 Sheet 内 prompt 按钮的 data-t，两者都无才跳过',
+        '     （#88 S5／B 段红队 S3-a：真实help模板恒有 <pre>，故 436/436 恒有按钮，不静默丢卡）→ 复用既有委派。 */',
+        '  function injectCardCopy(cards) {',
+        '    for (var i = 0; i < cards.length; i++) {',
+        '      var card = cards[i];',
+        '      if (card.querySelector("." + CARD_COPY_CLASS)) continue;',
+        '      var pre = card.querySelector("." + PROMPT_CLASS);',
+        '      var src = pre !== null ? pre : card.querySelector(attrSel(ACTION_ATTR, COPY_ACTION));',
+        '      if (src === null) continue;',
+        '      var text = pre !== null ? pre.textContent : src.getAttribute(TEXT_ATTR);',
+        '      if (text === null) continue;',
+        '      var btn = document.createElement("button");',
+        '      btn.type = "button";',
+        '      btn.className = CARD_COPY_CLASS;',
+        '      btn.textContent = COPY_LABEL;',
+        '      btn.setAttribute(ACTION_ATTR, COPY_ACTION);',
+        '      btn.setAttribute(TEXT_ATTR, text);',
+        '      var head = card.querySelector("." + CARD_TOP_CLASS);',
+        '      if (head) head.appendChild(btn); else card.insertBefore(btn, card.firstChild);',
+        '    }',
+        '  }',
+        '',
+        '  /* Sheet 参数实时预览：静态值换输入框，输入即重组「prompt ＋ 空行 ＋ label: value 行」。 */',
+        '  function initSheetPreview(cards) {',
+        '    for (var i = 0; i < cards.length; i++) {',
+        '      var card = cards[i];',
+        '      var pre = card.querySelector("." + PROMPT_CLASS);',
+        '      if (!pre) continue;',
+        '      if (pre.getAttribute(PROMPT_ATTR) === null) pre.setAttribute(PROMPT_ATTR, pre.textContent);',
+        '      var fields = allOf(card, "." + FIELD_CLASS);',
+        '      for (var j = 0; j < fields.length; j++) bindField(card, fields[j]);',
+        '    }',
+        '  }',
+        '',
+        '  function bindField(card, field) {',
+        '    if (field.querySelector("." + FIELD_INPUT_CLASS)) return;',
+        '    var value = field.querySelector("." + FIELD_VALUE_CLASS);',
+        '    var input = document.createElement("input");',
+        '    input.type = "text";',
+        '    input.className = FIELD_INPUT_CLASS;',
+        '    input.value = value ? value.textContent : "";',
+        '    input.setAttribute("value", input.value);',
+        '    var hint = field.querySelector("." + FIELD_HINT_CLASS);',
+        '    if (hint) input.setAttribute("placeholder", hint.textContent);',
+        '    input.addEventListener("input", function () { refreshPreview(card); });',
+        '    if (value && value.parentNode === field) field.replaceChild(input, value);',
+        '    else field.appendChild(input);',
+        '  }',
+        '',
+        '  function refreshPreview(card) {',
+        '    var pre = card.querySelector("." + PROMPT_CLASS);',
+        '    if (!pre) return;',
+        '    var base = pre.getAttribute(PROMPT_ATTR);',
+        '    if (base === null) return;',
+        '    var lines = fieldLines(card);',
+        '    var text = lines.length > 0 ? base + LF2 + lines.join(LF) : base;',
+        '    pre.textContent = text;',
+        '    syncCopyText(card, text, lines);',
+        '    if (searchTerm !== "") markCard(card, searchTerm);',
+        '  }',
+        '',
+        '  function fieldLines(card) {',
+        '    var fields = allOf(card, "." + FIELD_CLASS);',
+        '    var lines = [];',
+        '    for (var i = 0; i < fields.length; i++) {',
+        '      var input = fields[i].querySelector("." + FIELD_INPUT_CLASS);',
+        '      var labelEl = fields[i].querySelector("." + FIELD_LABEL_CLASS);',
+        '      var label = labelEl ? labelEl.textContent : "";',
+        '      var raw = input ? input.value : "";',
+        '      var val = raw.replace(/^\\s+|\\s+$/g, "");',
+        '      if (val !== "") lines.push(label + ": " + val);',
+        '    }',
+        '    return lines;',
+        '  }',
+        '',
+        '  /* 复制按钮文本同步：prompt 目标（卡头 ＋ Sheet 内）＝ 预览文本；params 目标＝label: value 行，',
+        '     无字段时回落该卡 CLI 文本（与冻结help模板 paramsText 同口径）。 */',
+        '  function syncCopyText(card, text, lines) {',
+        '    var buttons = allOf(card, "[" + ACTION_ATTR + "]");',
+        '    for (var i = 0; i < buttons.length; i++) {',
+        '      var id = buttons[i].getAttribute(ACTION_ATTR);',
+        '      if (id === COPY_ACTION) buttons[i].setAttribute(TEXT_ATTR, text);',
+        '      else if (id === PARAMS_ACTION) buttons[i].setAttribute(TEXT_ATTR, lines.length > 0 ? lines.join(LF) : cliTextOf(card));',
+        '    }',
+        '  }',
+        '',
+        '  function cliTextOf(card) {',
+        '    var cli = card.querySelector("." + CLI_CLASS);',
+        '    return cli ? cli.textContent : "";',
+        '  }',
+        '',
+        '  /* 搜索：过滤 ＋ mark 标签高亮 ＋ 自动展开 ＋ 命中计数 ＋ 清空 ＋ 跳页。 */',
+        '  function initSearch(shell, cards) {',
+        '    var tabBar = shell.querySelector("." + TAB_BAR_CLASS);',
+        '    if (!tabBar || !tabBar.parentNode) return;',
+        '    if (shell.querySelector("." + SEARCH_BOX_CLASS)) return;',
+        '    var box = document.createElement("div");',
+        '    box.className = SEARCH_BOX_CLASS;',
+        '    var input = document.createElement("input");',
+        '    input.type = "search";',
+        '    input.className = SEARCH_INPUT_CLASS;',
+        '    input.setAttribute("placeholder", SEARCH_PLACEHOLDER);',
+        '    input.setAttribute("aria-label", SEARCH_ARIA);',
+        '    input.setAttribute("autocomplete", "off");',
+        '    var clear = document.createElement("button");',
+        '    clear.type = "button";',
+        '    clear.className = SEARCH_CLEAR_CLASS;',
+        '    clear.textContent = CLEAR_LABEL;',
+        '    clear.setAttribute("aria-label", CLEAR_ARIA);',
+        '    var count = document.createElement("span");',
+        '    count.className = HITCOUNT_CLASS;',
+        '    count.setAttribute("role", "status");',
+        '    box.appendChild(input);',
+        '    box.appendChild(clear);',
+        '    box.appendChild(count);',
+        '    tabBar.parentNode.insertBefore(box, tabBar.nextSibling);',
+        '    var state = { sheets: [], subgroups: [], pages: [], index: 0 };',
+        '    input.addEventListener("input", function () { runSearch(shell, cards, input, count, state); });',
+        '    input.addEventListener("keydown", function (ev) {',
+        '      if (ev.key !== "Enter") return;',
+        '      ev.preventDefault();',
+        '      if (state.pages.length === 0) return;',
+        '      state.index = (state.index + 1) % state.pages.length;',
+        '      jumpTo(state.pages[state.index]);',
+        '    });',
+        '    clear.addEventListener("click", function () {',
+        '      input.value = "";',
+        '      runSearch(shell, cards, input, count, state);',
+        '      input.focus();',
+        '    });',
+        '  }',
+        '',
+        '  function runSearch(shell, cards, input, count, state) {',
+        '    var term = input.value.replace(/^\\s+|\\s+$/g, "").toLowerCase();',
+        '    resetSearch(shell, cards, state);',
+        '    searchTerm = term;',
+        '    if (term === "") { count.textContent = ""; state.pages = []; state.index = 0; return; }',
+        '    var hits = [];',
+        '    var i;',
+        '    for (i = 0; i < cards.length; i++) {',
+        '      var card = cards[i];',
+        '      if (card.textContent.toLowerCase().indexOf(term) < 0) { addClass(card, CARD_HIDDEN_CLASS); continue; }',
+        '      hits.push(card);',
+        '      markCard(card, term);',
+        '      var sheet = card.querySelector("." + SHEET_CLASS);',
+        '      if (sheet && !sheet.open) { sheet.open = true; state.sheets.push(sheet); }',
+        '    }',
+        '    var subgroups = allOf(shell, "." + SUBGROUP_CLASS);',
+        '    for (i = 0; i < subgroups.length; i++) {',
+        '      var inner = allOf(subgroups[i], "." + CARD_CLASS);',
+        '      var visible = false;',
+        '      for (var j = 0; j < inner.length; j++) { if (hits.indexOf(inner[j]) > -1) { visible = true; break; } }',
+        '      if (visible) { if (!subgroups[i].open) { subgroups[i].open = true; state.subgroups.push(subgroups[i]); } }',
+        '      else addClass(subgroups[i], SUBGROUP_HIDDEN_CLASS);',
+        '    }',
+        '    var pages = allOf(shell, "." + PAGE_CLASS);',
+        '    var hitPages = [];',
+        '    for (i = 0; i < pages.length; i++) {',
+        '      var pageCards = allOf(pages[i], "." + CARD_CLASS);',
+        '      for (var k = 0; k < pageCards.length; k++) { if (hits.indexOf(pageCards[k]) > -1) { hitPages.push(pages[i]); break; } }',
+        '    }',
+        '    state.pages = hitPages;',
+        '    state.index = 0;',
+        '    count.textContent = hits.length > 0 ? HIT_PREFIX + hits.length + HIT_SUFFIX : HIT_EMPTY;',
+        '    jumpTo(hitPages[0]);',
+        '  }',
+        '',
+        '  function resetSearch(shell, cards, state) {',
+        '    var i;',
+        '    for (i = 0; i < cards.length; i++) {',
+        '      removeClass(cards[i], CARD_HIDDEN_CLASS);',
+        '      unmarkCard(cards[i]);',
+        '    }',
+        '    for (i = 0; i < state.sheets.length; i++) state.sheets[i].open = false;',
+        '    state.sheets = [];',
+        '    for (i = 0; i < state.subgroups.length; i++) state.subgroups[i].open = false;',
+        '    state.subgroups = [];',
+        '    var subgroups = allOf(shell, "." + SUBGROUP_CLASS);',
+        '    for (i = 0; i < subgroups.length; i++) removeClass(subgroups[i], SUBGROUP_HIDDEN_CLASS);',
+        '  }',
+        '',
+        '  function jumpTo(page) {',
+        '    if (!page) return;',
+        '    var radio = page.querySelector("." + TAB_INPUT_CLASS);',
+        '    if (radio && radio.checked !== true) radio.checked = true;',
+        '  }',
+        '',
+        '  function markCard(card, term) {',
+        '    unmarkCard(card);',
+        '    var nodes = [];',
+        '    collectText(card, nodes);',
+        '    for (var i = 0; i < nodes.length; i++) wrapTerm(nodes[i], term);',
+        '  }',
+        '',
+        '  function unmarkCard(card) {',
+        '    var marks = allOf(card, "." + CARD_MARK_CLASS);',
+        '    for (var i = 0; i < marks.length; i++) {',
+        '      var parent = marks[i].parentNode;',
+        '      if (!parent) continue;',
+        '      parent.replaceChild(document.createTextNode(marks[i].textContent), marks[i]);',
+        '      if (typeof parent.normalize === "function") parent.normalize();',
+        '    }',
+        '  }',
+        '',
+        '  function collectText(root, out) {',
+        '    var kids = root.childNodes;',
+        '    for (var i = 0; i < kids.length; i++) {',
+        '      var node = kids[i];',
+        '      if (node.nodeType === 3) { if (node.nodeValue) out.push(node); continue; }',
+        '      if (node.nodeType !== 1) continue;',
+        '      if (hasClass(node, CARD_MARK_CLASS)) continue;',
+        '      var tag = node.tagName;',
+        '      if (tag === "SCRIPT" || tag === "STYLE" || tag === "TEXTAREA" || tag === "INPUT") continue;',
+        '      collectText(node, out);',
+        '    }',
+        '  }',
+        '',
+        '  function wrapTerm(node, term) {',
+        '    var rest = node.nodeValue;',
+        '    var at = rest.toLowerCase().indexOf(term);',
+        '    if (at < 0) return;',
+        '    var frag = document.createDocumentFragment();',
+        '    while (at > -1) {',
+        '      if (at > 0) frag.appendChild(document.createTextNode(rest.slice(0, at)));',
+        '      var mark = document.createElement("mark");',
+        '      mark.className = CARD_MARK_CLASS;',
+        '      mark.textContent = rest.slice(at, at + term.length);',
+        '      frag.appendChild(mark);',
+        '      rest = rest.slice(at + term.length);',
+        '      at = rest.toLowerCase().indexOf(term);',
+        '    }',
+        '    if (rest !== "") frag.appendChild(document.createTextNode(rest));',
+        '    if (node.parentNode) node.parentNode.replaceChild(frag, node);',
+        '  }',
+        '',
+        '  /* 回到顶部（H-19）：scrollTop > BACKTOP_MIN_Y 才加 -show；点击平滑回顶。 */',
+        '  function initBackTop() {',
+        '    if (document.querySelector("." + BACKTOP_CLASS)) return;',
+        '    var btn = document.createElement("button");',
+        '    btn.type = "button";',
+        '    btn.id = BACKTOP_ID;',
+        '    btn.className = BACKTOP_CLASS;',
+        '    btn.textContent = BACKTOP_LABEL;',
+        '    btn.setAttribute("aria-label", BACKTOP_ARIA);',
+        '    btn.setAttribute("title", BACKTOP_ARIA);',
+        '    btn.addEventListener("click", function () {',
+        '      var root = scrollRoot();',
+        '      if (!root) return;',
+        '      if (typeof root.scrollTo === "function") {',
+        '        try { root.scrollTo({ top: 0, behavior: "smooth" }); return; } catch (err) { root.scrollTop = 0; return; }',
+        '      }',
+        '      root.scrollTop = 0;',
+        '    });',
+        '    document.body.appendChild(btn);',
+        '    document.addEventListener("scroll", syncBackTop, true);',
+        '    syncBackTop();',
+        '  }',
+        '',
+        '  function scrollRoot() {',
+        '    return document.scrollingElement || document.documentElement || document.body;',
+        '  }',
+        '',
+        '  function syncBackTop() {',
+        '    var btn = document.querySelector("." + BACKTOP_CLASS);',
+        '    if (!btn) return;',
+        '    var root = scrollRoot();',
+        '    var y = root ? root.scrollTop : 0;',
+        '    if (y > BACKTOP_MIN_Y) addClass(btn, BACKTOP_SHOW_CLASS); else removeClass(btn, BACKTOP_SHOW_CLASS);',
+        '  }',
+        '',
+        '  if (document.body) boot();',
+        '  else document.addEventListener("DOMContentLoaded", boot);',
+        '}());',
+    ];
+    return lines.join(String.fromCharCode(10));
+};