cardbuddy 0.14.3 → 0.16.0

package/dist/vendored/skills/dsl-card-generator/scripts/lib/component_contract.mjs

@@ -0,0 +1,315 @@
+/**
+ * component_contract.mjs — 组件契约（className 白名单 + 属性键白名单 + 样式组/子键白名单）单一来源。
+ *
+ * 为什么需要它（2026-09-24 gen-1 实测事故）：
+ *   模型给 Image 节点写了 `itemKey: "image"`，而 Image 组件元数据里**只有一个属性键 `value`**
+ *   （itemName「图片地址」，itemTypeRange "image,var"）。运行时按 itemKey 绑定组件 props，
+ *   不存在的键**被整条静默丢弃** ⇒ value 为空 ⇒ 图片走 DEFAULT_IMAGE_URL ⇒ 渲染成破图。
+ *   而当时的四道闸**全部放行**：
+ *     - validate_schema.py：只查结构，属性键不是它的管辖范围
+ *     - lint_card.mjs：没有属性键规则
+ *     - preflight.mjs：Check 3 / Check 5 都用 `getProp(n,'value')`，取不到就直接 `continue`
+ *       —— 键名写错反而把整条检查链**短路**了
+ *     - iterate 的 elements.missing：只比对文本，不比对图片
+ *   全仓 82 处 Image 里 81 处写 `value`，唯一写 `image` 的就是这一处 ⇒ 这是模型偶发编造键名，
+ *   必须有机械兜底，不能指望它每次都对。
+ *
+ * 口径同源：preflight / lint_card / readiness / gate 一律 import 本模块，
+ * **禁止各写一份白名单**（否则出现「文档教 A、门禁判 A 违规」的死结）。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+/**
+ * 渲染器内建、但不在 component-meta.json 里的类。
+ *
+ * `Root` = 卡片根容器。card-editor/runtime/node-model.js 明写：
+ *   「根节点 className "Root" 不在组件 meta 里，这里合成一份：无属性、无插槽、样式全开」。
+ * 所以：className 合法、样式组照常校验、**属性键不校验**（ROOT_META 里根本没有 properties 概念，
+ * 也就不存在「非法属性键」）。全仓 75 张卡的根节点实测 0 张带 properties。
+ */
+const BUILTIN_CLASSES = new Set(['Root'])
+
+/** 不做属性键校验的类（见 BUILTIN_CLASSES 说明）。 */
+const NO_PROP_CHECK = new Set(['Root'])
+
+/**
+ * 复现器（repeater）判定：**由元数据推导，不写类名**。
+ *
+ * 为什么需要：`slots[].slotKey` 实测**恒为 `default`**（全仓 1010 个 slot 无一例外，
+ * Row 597 / Column 328 / ListLayout 54 / AbsoluteLayout 20 / GridLayout 11），
+ * 所以「子节点存在 slot.components 里」**不等于**「处在列表项作用域里」——
+ * 按 slotKey 或按「有没有 slot」判断会把整棵树的引用都当成列表项字段（实测 gen-1 21 条引用
+ * 被全部误判进槽位，变量绑定门禁因此整条失效）。
+ *
+ * 判据 = 同时满足两条：① 元数据声明了 `value` 属性（数组数据源）；② 有 `default` 插槽。
+ * 命中者即「按数据源循环渲染子节点」的容器，其插槽内的 `$field` 才是 item 字段。
+ */
+function deriveRepeaterClasses(cm) {
+  const out = new Set()
+  for (const [cls, def] of Object.entries(cm?.components || {})) {
+    const hasValueProp = (def?.properties || []).some((p) => p && p.itemKey === 'value')
+    const slots = def?.slots || def?.slotList || []
+    const hasDefaultSlot = slots.some((s) => String(s?.slotKey || s?.key || s) === 'default')
+    if (hasValueProp && hasDefaultSlot) out.add(cls)
+  }
+  return out
+}
+
+/**
+ * 读取并编译契约。
+ *
+ * @param {object} opts
+ * @param {string} opts.metaDir 元数据目录（含 component-meta.json / style-meta.json）
+ * @returns {{
+ *   classes: Set<string>,
+ *   propKeys: Map<string, Set<string>>,
+ *   propMeta: Map<string, Map<string, object>>,
+ *   styleGroups: Map<string, Set<string>>,
+ *   repeaterClasses: Set<string>,
+ *   loaded: { components: boolean, styles: boolean },
+ * }}
+ */
+export function loadContract({ metaDir }) {
+  const out = {
+    classes: new Set(BUILTIN_CLASSES),
+    propKeys: new Map(),
+    propMeta: new Map(),
+    styleGroups: new Map(),
+    repeaterClasses: new Set(),
+    loaded: { components: false, styles: false },
+  }
+
+  // ── 组件契约 ──
+  const cmPath = path.join(metaDir, 'component-meta.json')
+  try {
+    const cm = JSON.parse(fs.readFileSync(cmPath, 'utf8'))
+    for (const [cls, def] of Object.entries(cm?.components || {})) {
+      out.classes.add(cls)
+      const keys = new Set()
+      const metaByKey = new Map()
+      for (const p of def?.properties || []) {
+        const k = p?.itemKey
+        // 关键：**跳过没有 itemKey 的属性项**。
+        // Text / Button 的元数据里有「常用样式」这类 UI 预置项，只有 itemId + itemType，没有 itemKey
+        // —— 它们不参与运行时绑定。全仓实测 443(Text) + 21(Button) 条这种键，若不跳过会造成大面积误报。
+        if (typeof k !== 'string' || !k) continue
+        keys.add(k)
+        metaByKey.set(k, p)
+      }
+      out.propKeys.set(cls, keys)
+      out.propMeta.set(cls, metaByKey)
+    }
+    out.repeaterClasses = deriveRepeaterClasses(cm)
+    out.loaded.components = out.classes.size > 0
+  } catch {
+    /* 拿不到组件元数据：契约退化为「空」，调用方据此跳过检查而不是误报 */
+  }
+
+  // ── 样式契约（13 组 + 每组合法子键）──
+  const smPath = path.join(metaDir, 'style-meta.json')
+  try {
+    const sm = JSON.parse(fs.readFileSync(smPath, 'utf8'))
+    for (const g of sm?.properties || []) {
+      const gk = g?.itemKey
+      if (typeof gk !== 'string' || !gk) continue
+      const childKeys = new Set()
+      for (const c of g?.itemChildren || []) {
+        const ck = c?.itemKey
+        if (typeof ck === 'string' && ck) childKeys.add(ck)
+      }
+      out.styleGroups.set(gk, childKeys)
+    }
+    out.loaded.styles = out.styleGroups.size > 0
+  } catch {
+    /* 同上 */
+  }
+
+  return out
+}
+
+/** 该组件的合法属性键集合（未知组件返回 null，表示「无从判断」而非「全部非法」）。 */
+export function legalPropKeys(contract, className) {
+  if (NO_PROP_CHECK.has(className)) return null
+  return contract.propKeys.has(className) ? contract.propKeys.get(className) : null
+}
+
+/**
+ * 编辑距离（只用于给「你是不是想写 X」的建议，不是判定依据）。
+ * 上限 2：键名普遍很短，距离 >2 的建议没有参考价值。
+ */
+function nearestKey(target, candidates) {
+  const t = String(target || '')
+  let best = null
+  let bestD = Infinity
+  for (const c of candidates) {
+    const d = levenshtein(t, c)
+    if (d < bestD) {
+      bestD = d
+      best = c
+    }
+  }
+  return bestD <= 2 ? best : null
+}
+
+function levenshtein(a, b) {
+  if (a === b) return 0
+  const m = a.length
+  const n = b.length
+  if (!m) return n
+  if (!n) return m
+  let prev = Array.from({ length: n + 1 }, (_, j) => j)
+  for (let i = 1; i <= m; i++) {
+    const cur = [i]
+    for (let j = 1; j <= n; j++) {
+      cur[j] = Math.min(prev[j] + 1, cur[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1))
+    }
+    prev = cur
+  }
+  return prev[n]
+}
+
+/**
+ * 遍历 schema 里所有节点（含 slots 子树，与渲染器一致）。
+ *
+ * @param {object} schema 卡片 schema
+ * @param {(node: object, where: string, parent: object|null) => void} cb
+ */
+export function walkSchemaNodes(schema, cb) {
+  const visit = (node, where, parent) => {
+    if (!node || typeof node !== 'object') return
+    cb(node, where, parent)
+    const kids = node.components || []
+    kids.forEach((c, i) => visit(c, `${where}>c${i}`, node))
+    ;(node.slots || []).forEach((s, si) => {
+      ;(s?.components || []).forEach((c, ci) => visit(c, `${where}>slot:${s?.slotKey || si}[${ci}]`, node))
+    })
+  }
+  if (schema?.view) visit(schema.view, 'view', null)
+}
+
+/**
+ * 采集组件契约违规。
+ *
+ * 返回项字段：
+ *   code        'unknown-class' | 'unknown-prop-key' | 'unknown-style-group' | 'unknown-style-key'
+ *   severity    'error' | 'warn'
+ *   componentId 节点 id（缺省 '(root)'）
+ *   className   节点类型
+ *   where       节点在树中的路径（定位用）
+ *   key         违规键名
+ *   legal       该处合法键数组（供调用方直接展示）
+ *   suggestion  近似合法键（编辑距离 ≤2 才有；用于「你是不是想写 value」）
+ *
+ * @param {object} schema
+ * @param {ReturnType<typeof loadContract>} contract
+ * @returns {Array<object>}
+ */
+export function collectContractViolations(schema, contract) {
+  const out = []
+  if (!contract || !contract.loaded.components) return out
+
+  walkSchemaNodes(schema, (node, where) => {
+    const cls = node.className
+    if (!cls) return
+    const cid = node.componentId || '(root)'
+
+    // 1) className 本身不在元数据里（渲染空白）——与 preflight Check 2 同源，这里也给一份，
+    //    让 readiness 能独立跑出完整结论。
+    if (!contract.classes.has(cls)) {
+      out.push({ code: 'unknown-class', severity: 'error', componentId: cid, className: cls, where, key: cls, legal: [...contract.classes].sort() })
+      return
+    }
+
+    // 2) 属性键白名单 —— 本次事故的正主
+    const legal = legalPropKeys(contract, cls)
+    if (legal) {
+      for (const p of node.properties || []) {
+        const k = p?.itemKey
+        // 无 itemKey 的属性项是「样式预置」类 UI 载体，不参与绑定，跳过（全仓实测 464 条）
+        if (typeof k !== 'string' || !k) continue
+        if (legal.has(k)) continue
+        out.push({
+          code: 'unknown-prop-key',
+          severity: 'error',
+          componentId: cid,
+          className: cls,
+          where,
+          key: k,
+          legal: [...legal].sort(),
+          suggestion: nearestKey(k, legal),
+        })
+      }
+    }
+
+    // 3) 样式组 / 组内子键白名单
+    if (contract.loaded.styles) {
+      for (const g of node.style?.properties || []) {
+        const gk = g?.itemKey
+        if (typeof gk !== 'string' || !gk) continue
+        if (!contract.styleGroups.has(gk)) {
+          // 空组（没有任何带值的子键）运行时本来就什么也不做 ⇒ 只是噪音，报 warn；
+          // 带值的未知组才是真丢样式，报 error。这条区分避免「模型随手写错一个空组」也把门禁打红。
+          const carrying = (g?.itemChildren?.properties || []).filter((c) => {
+            const v = c?.itemValue
+            if (v === undefined || v === null || v === '') return false
+            if (typeof v === 'object' && !Array.isArray(v)) return Object.keys(v).length > 0
+            return true
+          })
+          out.push({
+            code: 'unknown-style-group',
+            severity: carrying.length ? 'error' : 'warn',
+            componentId: cid,
+            className: cls,
+            where,
+            key: gk,
+            legal: [...contract.styleGroups.keys()].sort(),
+            suggestion: nearestKey(gk, [...contract.styleGroups.keys()]),
+            carrying: carrying.length,
+          })
+          continue
+        }
+        const childLegal = contract.styleGroups.get(gk)
+        for (const c of g?.itemChildren?.properties || []) {
+          const ck = c?.itemKey
+          if (typeof ck !== 'string' || !ck) continue
+          if (childLegal.has(ck)) continue
+          out.push({
+            code: 'unknown-style-key',
+            severity: 'error',
+            componentId: cid,
+            className: cls,
+            where: `${where}>style.${gk}`,
+            key: ck,
+            legal: [...childLegal].sort(),
+            suggestion: nearestKey(ck, childLegal),
+          })
+        }
+      }
+    }
+  })
+
+  return out
+}
+
+/** 把一条违规渲染成一行可执行的中文说明（脚本输出是程序文本，不放具体卡片/业务字段名）。 */
+export function describeViolation(v) {
+  const at = v.where ? `${v.where} ` : ''
+  const suffix = v.suggestion ? `（是不是想写 "${v.suggestion}"？）` : ''
+  switch (v.code) {
+    case 'unknown-class':
+      return `${at}${v.className} "${v.componentId}" 不在组件元数据白名单里 → 渲染空白。合法类型：${v.legal.join(' / ')}`
+    case 'unknown-prop-key':
+      return (
+        `${at}${v.className} "${v.componentId}" 的属性键 "${v.key}" 不在该组件的合法键里 → ` +
+        `运行时按 itemKey 绑定，**不存在的键被整条静默丢弃**，组件拿到空值（如 Image 会渲染成破图）。` +
+        `该组件合法键：${v.legal.length ? v.legal.join(' / ') : '（无：该组件不接受任何属性）'}${suffix}`
+      )
+    case 'unknown-style-group':
+      return `${at}${v.className} "${v.componentId}" 的样式组 "${v.key}" 不是 13 个合法组名之一 → 整组被丢弃。合法组：${v.legal.join(' / ')}${suffix}`
+    case 'unknown-style-key':
+      return `${at}${v.className} "${v.componentId}" 在样式组 "${String(v.where).split('.').pop()}" 下写了非法子键 "${v.key}" → 该条属性被静默丢弃。该组合法子键：${v.legal.join(' / ')}${suffix}`
+    default:
+      return `${at}${v.className} "${v.componentId}" 契约违规：${v.key}`
+  }
+}

package/dist/vendored/skills/dsl-card-generator/scripts/lib/geometry_audit.mjs

@@ -0,0 +1,131 @@
+/**
+ * geometry_audit.mjs —— 用**纯几何事实**判「节点是不是看不见 / 跑出画布 / 被折成一堆行」。
+ *
+ * 为什么需要它（2026-09-21 复盘）：上一轮建卡跑了 30 分钟不收敛，直接原因是模型**看不见渲染结果**
+ * （card_screenshot 只给人看、不进模型上下文），可观测输入只剩 match / heightDelta / bands 三个数字，
+ * 于是全程盲调参。而那两个致命缺陷（Row 内横向容器默认 100% 吃掉整行 → 文本被压成 0 宽、
+ * 兄弟被顶到 x=356 卡外）其实**不需要看图就能判定**：它们全是几何事实。
+ *
+ * 本模块只判可由 `getBoundingClientRect()` + computedStyle 直接证实的三类，不做任何猜测：
+ *  1. collapsed（**error**）：在流里、有可见内容、却被压成零尺寸 → 用户看不见它，千真万确。
+ *  2. outOfCard（**error**）：部分或全部落在卡片矩形之外 → 卡片根节 overflow:hidden，必然被裁。
+ *  3. overWrapped（**warn**）：文本高度 > 2 行（h / lineHeight > 2）→ 多半是被挤窄后逐字换行，
+ *     也可能是设计稿本来就是多行文本，故只提示不拦门禁。
+ *
+ * 判定阈值都用「1x 设计像素」，与 iterate 的 match/heightDelta 同一坐标系。
+ */
+
+/** 被视为「图形内容」的组件类：零尺寸时一定是缺陷（文本另有 text 判据）。 */
+const GRAPHIC_CLASSES = new Set(['Image', 'Icon', 'Video', 'Map', 'Svgsymbols', 'SvgSymbols', 'MultiText'])
+
+/** 文本节点折行阈值：h / lineHeight 超过这个倍数即提示（2 = 两行，>2 即三行以上）。 */
+const OVERWRAP_RATIO = 2
+
+const round1 = (n) => Math.round(Number(n) * 10) / 10
+
+/**
+ * @param {object} opts
+ * @param {Array<object>} opts.elements    render_card 产出的 elementBoxes（正常尺寸节点）
+ * @param {Array<object>} [opts.degenerate] render_card 产出的 elementBoxesDegenerate（零尺寸节点）
+ * @param {number} opts.cardWidth          卡片逻辑宽（1x，= `.phone__screen` 实测宽）
+ * @param {number} [opts.tolerance]        可接受误差（px），默认 1
+ * @returns {{collapsed:Array,outOfCard:Array,overWrapped:Array,counts:object}}
+ */
+export function auditGeometry({ elements, degenerate, cardWidth, tolerance = 1 }) {
+  const collapsed = []
+  const outOfCard = []
+  const overWrapped = []
+  const width = Number(cardWidth) || 0
+
+  for (const el of degenerate || []) {
+    const hasContent = Boolean(String(el.text || '').trim()) || GRAPHIC_CLASSES.has(el.cls)
+    if (!hasContent) continue // 空容器被压扁不报警（它本来就不显示东西）
+    collapsed.push({
+      cid: el.cid,
+      cls: el.cls,
+      text: String(el.text || '').slice(0, 24),
+      x: round1(el.x),
+      y: round1(el.y),
+      w: round1(el.w),
+      h: round1(el.h),
+      reason: Number(el.w) < tolerance
+        ? '宽被压成 0（同排兄弟把整行吃光了）→ 文本每字一行、实际不可读'
+        : '高被压成 0（父容器或兄弟把高度挤没了）',
+    })
+  }
+
+  for (const el of elements || []) {
+    const w = Number(el.w) || 0
+    const h = Number(el.h) || 0
+    if (w < tolerance || h < tolerance) {
+      // 正常集合里出现零尺寸（例如被 1px 容差漏过的边界情况）→ 同样按压扁处理
+      const hasContent = Boolean(String(el.text || '').trim()) || GRAPHIC_CLASSES.has(el.cls)
+      if (hasContent) collapsed.push({ cid: el.cid, cls: el.cls, text: String(el.text || '').slice(0, 24), x: round1(el.x), y: round1(el.y), w: round1(w), h: round1(h), reason: '尺寸被压到 1px 以下' })
+      continue
+    }
+    if (width > 0) {
+      const overRight = round1(el.x + w - width)
+      const overLeft = round1(-el.x)
+      if (overRight > tolerance || overLeft > tolerance) {
+        outOfCard.push({
+          cid: el.cid,
+          cls: el.cls,
+          text: String(el.text || '').slice(0, 24),
+          x: round1(el.x),
+          y: round1(el.y),
+          w: round1(w),
+          h: round1(h),
+          overflowRight: overRight > tolerance ? overRight : 0,
+          overflowLeft: overLeft > tolerance ? overLeft : 0,
+          reason: overRight > tolerance
+            ? `右缘超出卡片 ${overRight}px（卡宽 ${width}）→ 被根节点 overflow:hidden 裁掉`
+            : `左缘超出卡片 ${overLeft}px → 被裁掉`,
+        })
+      }
+    }
+    const lh = Number(el.lh) || 0
+    const text = String(el.text || '').trim()
+    if (text && lh > 0 && h / lh > OVERWRAP_RATIO) {
+      overWrapped.push({
+        cid: el.cid,
+        cls: el.cls,
+        text: text.slice(0, 24),
+        x: round1(el.x),
+        y: round1(el.y),
+        w: round1(w),
+        h: round1(h),
+        lines: Math.round(h / lh),
+        reason: `约占 ${Math.round(h / lh)} 行（h=${round1(h)} / 行高 ${round1(lh)}）→ 检查是否被挤窄后逐字换行；设计稿本来就是多行文本可忽略`,
+      })
+    }
+  }
+
+  return {
+    collapsed,
+    outOfCard,
+    overWrapped,
+    counts: { collapsed: collapsed.length, outOfCard: outOfCard.length, overWrapped: overWrapped.length },
+  }
+}
+
+/** 把审计结果压成一行给人/模型看的结论；无异常返回 null。 */
+export function describeGeometry(audit) {
+  if (!audit) return null
+  const parts = []
+  if (audit.collapsed.length) {
+    parts.push(
+      `被压成零尺寸（用户完全看不见）${audit.collapsed.length} 个：` +
+      audit.collapsed.slice(0, 4).map((c) => `${c.cls} ${c.cid}${c.text ? ` "${c.text}"` : ''}`).join('、'),
+    )
+  }
+  if (audit.outOfCard.length) {
+    parts.push(
+      `跑出卡片被裁掉 ${audit.outOfCard.length} 个：` +
+      audit.outOfCard.slice(0, 4).map((c) => `${c.cls} ${c.cid}${c.text ? ` "${c.text}"` : ''}（x=${c.x} w=${c.w}）`).join('、'),
+    )
+  }
+  if (audit.overWrapped.length) {
+    parts.push(`疑似折行异常 ${audit.overWrapped.length} 个：` + audit.overWrapped.slice(0, 3).map((c) => `${c.cls} ${c.cid} ≈${c.lines} 行`).join('、'))
+  }
+  return parts.length ? parts.join('；') : null
+}

package/dist/vendored/skills/dsl-card-generator/scripts/lib/layout-tokens.mjs

@@ -54,7 +54,7 @@ export const TOKEN = {
   COLOR: {
     pageBg: '#F5F6F8',        // 页面/画布背景
     cardBg: '#FFFFFF',        // 卡片背景
-    primary: '#00B578',       // 品牌主色（绿，geo/v3）
+    primary: '#00B578',       // 品牌主色（绿，v3）
     primaryBlue: '#0079F2',  // legacy 生成器历史主色（蓝）
     fallbackBg: '#F5F5F5',   // pickBg 兜底色
     danger: '#F6434F',        // 危险/未读红点

package/dist/vendored/skills/dsl-card-generator/scripts/lib/layout_rules.mjs

@@ -0,0 +1,160 @@
+/**
+ * layout_rules.mjs —— 布局类硬契约的共享判定（lint_card.mjs / preflight.mjs 单一来源）。
+ *
+ * 为什么要有这个模块：同一条布局规则在 lint（迭代门禁）与 preflight（生成前检查）里各写一遍，
+ * 迟早会打架——一处改了、另一处没改，模型就会看到「同一张卡两个门禁结论不同」。R25/R31/R32 已
+ * 经是双写的，这里不再复制第三份。
+ *
+ * 本模块只放**从渲染器契约推导出来的、可静态判定**的事实，不猜设计意图：
+ *  ① 宽度基线：component-meta.json 里声明了 slots 的组件（=容器）默认 `rect.width:"100%"`，
+ *     且该默认**只在 rect 组整体缺失（或没有 width 子项）时生效**；写了 `width:""` 就是 auto；
+ *  ② 主轴方向：CSS 强制 `.ce_root/.ce_column/.ce_singlecolumn` 为 column，其余默认 row。
+ */
+import fs from 'node:fs'
+import path from 'node:path'
+
+import { metaDir } from './paths.mjs'
+
+/** CSS 强制 flex-direction:column 的容器类（card-editor/styles/components.css）。 */
+export const COLUMN_FLOW_CLASSES = new Set(['Root', 'Column', 'SingleColumn'])
+
+let _metaCache = null
+function componentMeta() {
+  if (_metaCache === null) {
+    try {
+      _metaCache = JSON.parse(fs.readFileSync(path.join(metaDir, 'component-meta.json'), 'utf8')).components || {}
+    } catch {
+      _metaCache = {}
+    }
+  }
+  return _metaCache
+}
+
+/** 容器类 = component-meta 里声明了 slots（能装子节点）的组件。 */
+export function containerClasses() {
+  const out = new Set()
+  for (const [cls, def] of Object.entries(componentMeta())) {
+    if ((def?.slots || []).length > 0) out.add(cls)
+  }
+  // meta 读不到时的兜底（保持规则可用，不至于静默失效）
+  if (!out.size) for (const c of ['Row', 'Column', 'MultiColumn', 'ListLayout', 'GridLayout', 'AbsoluteLayout', 'Canvas', 'ViewContainer']) out.add(c)
+  return out
+}
+
+/**
+ * 容器的宽度基线是不是「填满父容器」（渲染器默认 100%）。
+ * 未写 rect.width 的容器会拿到 component-meta 的默认值，实测渲染为 100%。
+ */
+export function defaultWidth100Classes() {
+  const out = new Set()
+  for (const cls of containerClasses()) {
+    const w = componentMeta()[cls]?.styleState?.rect?.width
+    if (w === '100%') out.add(cls)
+  }
+  if (!out.size) for (const c of ['Row', 'Column', 'MultiColumn', 'ListLayout', 'GridLayout', 'AbsoluteLayout', 'Canvas', 'ViewContainer']) out.add(c)
+  return out
+}
+
+/** 取 style.<group>.<key> 的字面值与来源开关（itemValueFrom）。 */
+export function styleChild(node, group, key) {
+  for (const g of node?.style?.properties || []) {
+    if (g.itemKey !== group) continue
+    for (const c of g.itemChildren?.properties || []) {
+      if (c.itemKey === key) return { value: String(c.itemValue ?? '').trim(), from: String(c.itemValueFrom ?? '0') }
+    }
+  }
+  return null
+}
+
+/** 父容器的主轴是横向（row）吗？CSS 默认按类定，schema 显式写 flexDirection 才覆盖。 */
+export function isHorizontalFlow(parent) {
+  if (!parent) return false
+  const explicit = styleChild(parent, 'flex', 'flexDirection')?.value
+  if (COLUMN_FLOW_CLASSES.has(parent.className)) return explicit === 'row'
+  return (explicit || 'row') === 'row'
+}
+
+/**
+ * R22b：横向流父容器里的**容器类子节点**，`rect.width` 缺失且 `flexShrink:0`。
+ *
+ * 渲染契约（2026-09-21 实测定标，见下）：
+ *   | rect 写法            | 容器实测渲染宽     | 同排兄弟               |
+ *   |---------------------|------------------|-----------------------|
+ *   | rect 组缺失 / 无 width 子项 | **100%（吃满整行）** | 长文本被压成 w=0 → 每字一行、不可见 ❌ |
+ *   | `width: ""`          | auto（自然宽）      | 正常 ✓                 |
+ *   | `width: "100%"`      | 100%             | 被压成 0 ❌（R22 管这一半） |
+ *   | `width: "60"`        | 60px             | 正常 ✓                 |
+ * 叠加 `flexShrink:0` = 锁死不让位，于是「吃满整行」那个必然把兄弟挤没或顶出卡外。
+ *
+ * 与 R22 的关系：R22 拦的是 schema **显式写了** `width:"100%"` 那一半；本规则补的是
+ * **rect.width 整个缺失**（渲染等价于 100%）却完全没人管的另一半 ——
+ * 实测 demo/helloCard 的 6 个致命节点全落在这个盲区。
+ *
+ * 注意 `width: ""` **不算缺失**：它是这套 schema 的「auto」表示法，实测渲染为自然宽，安全。
+ *
+ * 仅在父容器有 ≥2 个子节点时成立（独子占满整行是合法用法）。
+ *
+ * @returns {{className:string,widthVal:null,shrinkVal:string}|null} 命中时返回证据
+ */
+export function rowChildContainerNoWidth({ node, parent, siblingCount }) {
+  if (!node || !parent) return null
+  if (siblingCount < 2) return null
+  if (!containerClasses().has(node.className)) return null
+  if (!defaultWidth100Classes().has(node.className)) return null
+  if (!isHorizontalFlow(parent)) return null
+  // width 子项「存在」就算已显式指定（含空串 ""：auto 表示法，实测安全）；
+  // 只有整组缺失 / 没有 width 子项才会落到 component-meta 默认 "100%"。
+  if (styleChild(node, 'rect', 'width')) return null
+  const shrink = styleChild(node, 'flex', 'flexShrink')
+  if (shrink?.value !== '0') return null
+  return { className: node.className, widthVal: null, shrinkVal: shrink.value }
+}
+
+/** 默认插槽直接子节点（兼容 Root.components 与普通节点 slots[0].components）。 */
+export function directChildren(node) {
+  if (!node) return []
+  const slot = (node.slots || [])[0]
+  if (slot && Array.isArray(slot.components)) return slot.components
+  return Array.isArray(node.components) ? node.components : []
+}
+
+/**
+ * 在 schema 树里收集全部 R22b 命中（供 lint / preflight 共用）。
+ * @param {object} view schema.view
+ * @returns {Array<{componentId:string,className:string,parentId:string,parentClass:string,siblingCount:number,message:string}>}
+ */
+export function collectRowChildNoWidth(view) {
+  const hits = []
+  // Root（view）自身是 column 流，其直接子节点不参与本规则 ⇒ 传 null 当作「非横向父容器」。
+  const visit = (node, isRoot) => {
+    const siblings = directChildren(node)
+    for (const child of siblings) {
+      const result = rowChildContainerNoWidth({
+        node: child,
+        parent: isRoot ? null : node,
+        siblingCount: siblings.length,
+      })
+      if (result) {
+        const parentLabel = `${node.className || 'Root'} "${node.componentId || '(root)'}"`
+        hits.push({
+          componentId: child.componentId || '',
+          className: result.className,
+          parentId: node.componentId || '(root)',
+          parentClass: node.className || 'Root',
+          siblingCount: siblings.length,
+          message:
+            `${result.className} "${child.componentId || '?'}" 是横向流 ${parentLabel} 的并列子节点（共 ${siblings.length} 个），` +
+            '它的 rect.width 整个缺失 —— 渲染器对「没有 width 子项」会回落到 component-meta 默认「100%」（吃满整行），' +
+            '又叠了 flexShrink:0 锁死不让位：同排兄弟会被压成 0 宽（文本每字一行、高度爆炸）或被顶出卡片右缘裁掉（R22b）。' +
+            '按设计稿给这个容器补一个明确宽度：实测 px（如 rect.width:"146"）、或 `rect.width:"60%"`；' +
+            '要「按内容自适应」就写 rect.width:""（空串 = auto，实测渲染为自然宽）；' +
+            '要「占满剩余空间」用 flexGrow:1 并把 flexShrink 改 1，不要靠缺失 + 锁死。',
+        })
+      }
+      visit(child, false)
+    }
+  }
+  visit(view, true)
+  return hits
+}
+

package/dist/vendored/skills/dsl-card-generator/scripts/lib/paths.mjs

@@ -49,6 +49,29 @@ export const slicesDir =
 export const baselinesDir =
   process.env.DSL_CARD_BASELINES_DIR || path.join(projectRoot, '.card-baselines')
 
+/**
+ * 机器产物目录 —— **门禁只认这里的落盘产物，不认模型自述**。
+ *
+ * 三类文件同住于此，路径必须单源（历史事故：`check_fidelity` 自己拼了
+ * `<cardDir>/.audit.json`，而真实位置是 `.cache/ai-scratch/<id>.audit.json` ⇒
+ * 切图覆盖数恒为 null，`.audit.json` 从未存在过却没人发现）：
+ *   - `.cache/ai-scratch/<id>.audit.json`    S2 审计全文（crop_slices --from-audit 与 readiness 都吃它）
+ *   - `.cache/ai-scratch/<id>.iterate.json`  最近一轮迭代报告（--gate 的唯一依据）
+ *   - `.cache/ai-scratch/<id>.ir.rNN.json`   每轮 IR 快照（回退用）
+ */
+export const scratchDir =
+  process.env.DSL_CARD_SCRATCH_DIR || path.join(projectRoot, '.cache', 'ai-scratch')
+
+/** S2 审计落盘路径（spec_audit.mjs --save 的默认目标）。 */
+export function cardAuditPath(id) {
+  return path.join(scratchDir, `${id}.audit.json`)
+}
+
+/** 最近一轮迭代报告路径。 */
+export function cardIteratePath(id) {
+  return path.join(scratchDir, `${id}.iterate.json`)
+}
+
 /** 兼容旧脚本的别名：宿主项目根目录。 */
 export const repoRoot = projectRoot