@lark-apaas/coding-steering 0.1.18-dev.e6a2787 → 0.1.18-dev.ec7b8c1

package/steering/design-html/skills/pptx-style-extract/scripts/draft.py

@@ -12,6 +12,7 @@
 （package.py 见 TODO 即 FAIL），由 L 层改掉。
 """
 import argparse
+import copy
 import json
 import os
 import re
@@ -264,9 +265,9 @@ OFFICE_DEFAULT_FONTS_NORM = {norm(x) for x in OFFICE_DEFAULT_FONTS}
 
 
 def cover_slot_colors(tokens, archetypes, rows, cusage):
-    """slot 里出现的每个色值都必须在色板里有名字。
+    """slot CSS 里出现的每个色值都必须在色板里有名字。
 
-    Hard Rules 写「颜色只用 colors 里的 token」，而 slot 的 color 是从模板直读的，
+    Hard Rules 写「颜色只用 colors 里的 token」，而 slot CSS 的 color 是从模板直读的，
     两者不对齐就等于产物自己违反自己的规则——slot 的色值直读自模板，未必都已进
     色板。这里把缺的补进色板，按用法归族命名。
     """
@@ -286,7 +287,7 @@ def cover_slot_colors(tokens, archetypes, rows, cusage):
     added = []
     for a in archetypes:
         for s in a['slots']:
-            h = (s.get('color') or '').upper()
+            h = (s.get('_color') or '').upper()
             if not h.startswith('#') or h in have:
                 continue
             have.add(h)
@@ -500,7 +501,8 @@ def draft_anchors(d, tokens, fonts, roles, assets, archetypes):
     # 6. 层级：字号跨度 + 字重是否单一（字重真单一才敢说「不靠字重」）
     disp, body = roles.get('display'), roles.get('body')
     if disp and body and disp['sz_px'] > body['sz_px']:
-        ws = {s.get('weight') for a in archetypes for s in a['slots'] if s.get('weight')}
+        ws = {s.get('_font_weight') for a in archetypes for s in a['slots']
+              if s.get('_font_weight')}
         tail = ('，字重只用 %s 一档' % list(ws)[0]) if len(ws) == 1 else ''
         A.append(('size-driven-hierarchy', 'pattern',
                   '最大字号档与正文档相差 %.1f 倍（见 typography）%s'
@@ -930,11 +932,23 @@ def slot_overlaps(slots):
     return out
 
 
+def css_number(value, digits=3):
+    """CSS 数值稳定格式：整数不带小数，其余去掉无意义尾零。"""
+    number = round(float(value), digits)
+    if number == int(number):
+        return str(int(number))
+    return ('%.*f' % (digits, number)).rstrip('0').rstrip('.')
+
+
 def slot_style(s):
-    """占位符自带的排版样式——字号/色值/对齐/字重都是直读，不给消费端留编的空间。
+    """占位符自带的排版样式，统一转成可直接写进 HTML style 的 CSS 声明串。
 
     样式可能在三层：lstStyle.lvl1pPr（版式占位符常用）、段落 defRPr（Mac Office
     导出把大量属性写在这一层）、段落 pPr（对齐）。逐层兜底，缺一层就往下取。
+
+    `box` 是布局几何，继续由 slot 独立承载；其余渲染属性不再泄漏成 size / color /
+    align / insets_px 等 PPTX 中间字段。下划线开头的键仅供 draft 内部统计，emit_layouts
+    不会写进消费者产物。
     """
     txt = s.get('text') or {}
     ls = dict((txt.get('lstStyle') or {}).get('lvl1pPr') or {})
@@ -955,12 +969,41 @@ def slot_style(s):
         anysz = shape_sz(s)
         if anysz:
             ls['sz_px'] = anysz
+    body = txt.get('bodyPr') or {}
+    css = []
     out = {}
+    insets = body.get('insets_px') or {}
+    if insets:
+        css.append('box-sizing: border-box')
+        css.append('padding: %spx %spx %spx %spx' % (
+            css_number(insets.get('tIns', 0) or 0),
+            css_number(insets.get('rIns', 0) or 0),
+            css_number(insets.get('bIns', 0) or 0),
+            css_number(insets.get('lIns', 0) or 0),
+        ))
     if ls.get('sz_px'):
-        out['size'] = round(ls['sz_px'])
+        size = round(ls['sz_px'])
+        css.append('font-size: %dpx' % size)
+        out['_font_size'] = size
+    weight = ls.get('weight') or (700 if ls.get('bold') else None)
+    if weight:
+        css.append('font-weight: %s' % weight)
+        out['_font_weight'] = weight
+    if ls.get('italic'):
+        css.append('font-style: italic')
+    decorations = []
+    if ls.get('underline'):
+        decorations.append('underline')
+    if ls.get('strike'):
+        decorations.append('line-through')
+    if decorations:
+        css.append('text-decoration: %s' % ' '.join(decorations))
+    if ls.get('spc_px') is not None:
+        css.append('letter-spacing: %spx' % css_number(ls['spc_px']))
     col = (ls.get('color') or {}).get('resolved')
     if col:
-        out['color'] = col
+        css.append('color: %s' % col)
+        out['_color'] = col
     else:
         # 占位符的字色也可以是 gradFill（章节页的大号序号常这么做）。解析层已经把
         # stops 和角度记全了，这里只取单色就会整条丢掉，消费端只能自己编一个平色。
@@ -969,17 +1012,30 @@ def slot_style(s):
         if f.get('type') == 'gradient':
             g = _load_query()._css_gradient(f)
             if g:
-                out['css'] = ('background-image: %s; -webkit-background-clip: text; '
-                              'background-clip: text; color: transparent' % g)
-    if ls.get('weight'):
-        out['weight'] = ls['weight']
-    elif ls.get('bold'):
-        out['weight'] = 700
-    if ls.get('algn') and ls['algn'] not in ('l', 'just'):
-        out['align'] = {'ctr': 'center', 'r': 'right'}.get(ls['algn'], ls['algn'])
-    anchor = ((s.get('text') or {}).get('bodyPr') or {}).get('anchor')
+                css += ['background-image: %s' % g, '-webkit-background-clip: text',
+                        'background-clip: text', 'color: transparent']
+    align = ls.get('algn')
+    if align:
+        css.append('text-align: %s' % {
+            'l': 'left', 'ctr': 'center', 'r': 'right', 'just': 'justify',
+        }.get(align, align))
+    line_spacing = ls.get('lnSpc') or {}
+    if line_spacing.get('mult'):
+        css.append('line-height: %s' % css_number(line_spacing['mult'] * 1.2))
+    elif line_spacing.get('px'):
+        css.append('line-height: %spx' % css_number(line_spacing['px']))
+    anchor = body.get('anchor')
     if anchor in ('ctr', 'b'):
-        out['valign'] = {'ctr': 'middle', 'b': 'bottom'}[anchor]
+        css += ['display: flex', 'flex-direction: column',
+                'justify-content: %s' % {'ctr': 'center', 'b': 'flex-end'}[anchor]]
+    if body.get('rot'):
+        try:
+            degrees = float(body['rot']) / 60000.0
+            css.append('rotate: %sdeg' % css_number(degrees))
+        except (TypeError, ValueError):
+            pass
+    if css:
+        out['css'] = '; '.join(css)
     return out
 
 
@@ -1021,7 +1077,8 @@ def layouts_from_template(d, shapes, cW, cH):
     """
     by_part = defaultdict(list)
     for s in shapes:
-        if s.get('layer') == 'layout' and s.get('ph'):
+        if (s.get('layer') == 'layout' and s.get('kind') == 'sp'
+                and (s.get('box') or {}).get('w') and (s.get('ph') or shape_text(s))):
             by_part[s['part']].append(s)
     bg_of_layout = {}
     composites = d.get('background_composites') or {}
@@ -1050,10 +1107,10 @@ def layouts_from_template(d, shapes, cW, cH):
         slots, seen_kind = [], set()
         for s in phs:
             t = PH_TO_TYPE.get((s['ph'] or {}).get('type'), 'body')
-            if t in ('slide-number', 'footer'):
-                continue                      # 页码/页脚属 chrome，不是内容槽
+            if t in ('slide-number', 'footer') and not shape_text(s):
+                continue                      # 空 chrome 占位符不是实际元素
             b = s['box']
-            role = t if t in ('title', 'subtitle') else 'body'
+            role = t if t in ('title', 'subtitle', 'footer', 'slide-number') else 'body'
             if t == 'title' and 'title' in seen_kind:
                 role, t = 'subtitle', 'subtitle'
             seen_kind.add(t)
@@ -1062,6 +1119,14 @@ def layouts_from_template(d, shapes, cW, cH):
                            round(b.get('w', 0)), round(b.get('h', 0))],
                    'txt': shape_text(s) or (s.get('name') or '')[:24]}
             row.update(slot_style(s))
+            if t == 'body':
+                ph = s.get('ph') or {}
+                row.update({
+                    '_needs_role': True,
+                    '_source_layer': 'layout',
+                    '_placeholder': '%s/%s' % (
+                        ph.get('type') or '-', ph.get('idx') or '-'),
+                })
             slots.append(row)
         # 非满屏的图片元素（logo / 联名标 / 装饰）——它们逐版式换位置换尺寸，
         # 必须按版式落进 slots，压成一条全局「固定位」规则就会撞标题。
@@ -1181,17 +1246,76 @@ def collect_decor(shapes, part, taken_boxes, canvas, limit=10):
     return out[:limit]                      # 同款不同位置都要留，位置本身是版式信息
 
 
+def placeholder_key(shape):
+    ph = shape.get('ph') or {}
+    if not ph:
+        return None
+    return (ph.get('type') or 'body', str(ph.get('idx') or ''))
+
+
+def merge_dict(base, override):
+    """把实例页的非空声明叠到版式声明上；空实例占位符继续继承版式事实。"""
+    out = copy.deepcopy(base or {})
+    for key, value in (override or {}).items():
+        if value is None or value == []:
+            continue
+        if isinstance(value, dict) and isinstance(out.get(key), dict):
+            out[key] = merge_dict(out[key], value)
+        else:
+            out[key] = copy.deepcopy(value)
+    return out
+
+
+def inherited_text_shapes(layout_shapes, slide_shapes):
+    """返回实例页可用的文字形状，并补齐其引用版式中的占位符几何与样式。"""
+    layout_text = []
+    for shape in layout_shapes:
+        if shape.get('kind') != 'sp' or not (shape.get('box') or {}).get('w'):
+            continue
+        ph = shape.get('ph') or {}
+        ph_type = ph.get('type')
+        if shape_text(shape) or (ph and ph_type not in ('ftr', 'dt', 'sldNum')):
+            layout_text.append(shape)
+    by_placeholder = {placeholder_key(s): s for s in layout_text if placeholder_key(s)}
+    used = set()
+    out = []
+    for shape in slide_shapes:
+        if shape.get('kind') != 'sp':
+            continue
+        key = placeholder_key(shape)
+        base = by_placeholder.get(key)
+        if base:
+            merged = merge_dict(base, shape)
+            merged['text'] = merge_dict(base.get('text'), shape.get('text'))
+            if not shape_text(shape):
+                merged['text']['paragraphs'] = copy.deepcopy(
+                    (base.get('text') or {}).get('paragraphs') or [])
+            used.add(key)
+            out.append((merged, 'slide+layout'))
+        elif (shape.get('box') or {}).get('w') and shape_text(shape):
+            out.append((shape, 'slide'))
+    for shape in layout_text:
+        key = placeholder_key(shape)
+        if key not in used:
+            out.append((shape, 'layout'))
+    return out
+
+
 def draft_layouts(d, outdir):
-    shapes = json.load(open(os.path.join(outdir, 'ref', 'shapes.json'), encoding='utf-8'))['shapes']
+    with open(os.path.join(outdir, 'ref', 'shapes.json'), encoding='utf-8') as stream:
+        shapes = json.load(stream)['shapes']
     cW, cH = d['canvas']['px']
     if (d.get('form_hint') or {}).get('form') == 3:
         arch = layouts_from_template(d, shapes, cW, cH)
         if len(arch) >= 3:
             return arch, [], []
     by_slide = defaultdict(list)
+    by_layout = defaultdict(list)
     for s in shapes:
         if s.get('layer') == 'slide':
             by_slide[s['part']].append(s)
+        elif s.get('layer') == 'layout':
+            by_layout[s['part']].append(s)
 
     bg_of_slide, layout_of_slide = {}, {}
     for s in d.get('slides', []):
@@ -1207,32 +1331,43 @@ def draft_layouts(d, outdir):
 
     pages = []
     for part, sh in sorted(by_slide.items(), key=lambda kv: slide_no(kv[0])):
+        layout_part = layout_of_slide.get(part)
+        layout_shapes = by_layout.get(layout_part) or []
         bg_media = top_bleed_media(sh)
         if bg_media is None:
-            bg_media = bg_of_layout.get(layout_of_slide.get(part))
+            bg_media = bg_of_layout.get(layout_part)
         rendered_bg = (composites.get(part)
-                       or composites.get(layout_of_slide.get(part))
+                       or composites.get(layout_part)
                        or bg_media)
         texts = []
-        for s in sh:
-            if s.get('kind') != 'sp':
-                continue
-            txt = shape_text(s)
-            if not txt:
-                continue
+        for s, source_layer in inherited_text_shapes(layout_shapes, sh):
+            txt = shape_text(s) or (s.get('name') or '')[:24]
             b = s.get('box') or {}
             if b.get('w', 0) < DECOR_MIN or b.get('h', 0) < 16:
                 continue
-            texts.append({'sz': shape_sz(s), 'box': b, 'txt': txt, 'style': slot_style(s)})
+            ph = s.get('ph') or {}
+            ph_type = ph.get('type')
+            direct_type = PH_TO_TYPE.get(ph_type, 'body')
+            texts.append({
+                'sz': shape_sz(s),
+                'box': b,
+                'txt': txt,
+                'style': slot_style(s),
+                'direct_type': direct_type,
+                'needs_role': direct_type == 'body',
+                'source_layer': source_layer,
+                'placeholder': '%s/%s' % (ph_type or '-', ph.get('idx') or '-'),
+            })
         texts.sort(key=lambda t: (-t['sz'], t['box'].get('y', 0)))
-        pics = [s for s in sh if s.get('kind') == 'pic' and s.get('w_pct', 0) < 95]
+        visible_shapes = layout_shapes + sh
+        pics = [s for s in visible_shapes if s.get('kind') == 'pic' and s.get('w_pct', 0) < 95]
         # 小图元素（logo / 角标 / 装饰）逐页记位置，供 archetype 落 slots
         marks = [{'media': s['media'], 'box': s['box']} for s in pics
                  if s.get('media') and (s.get('box') or {}).get('w') and s.get('w_pct', 0) < 30]
         pages.append({'part': part, 'no': slide_no(part), 'bg_media': bg_media,
                       'rendered_bg': rendered_bg,
                       'bg_color': bg_of_slide.get(part), 'texts': texts, 'pic_n': len(pics),
-                      'marks': marks, 'shape_n': len(sh)})
+                      'marks': marks, 'shape_n': len(visible_shapes), 'layout': layout_part})
 
     # 页型的**角色**（封面 / 章节页 / 内容页……）不在这里判：那是看图才能下的结论，
     # 交给读得到重建图的模型。脚本只做客观归并——同一张底图 + 文字块数量相近的页
@@ -1286,12 +1421,13 @@ def draft_layouts(d, outdir):
         rest.sort(key=lambda t: (t['box'].get('y', 0), t['box'].get('x', 0)))
         ordered = ([title] if title else []) + rest
         slots = []
-        note_truncation('文字槽', 6, len(ordered),
-                        '需要更多同类槽时，按已有同类槽的间距等距延续，不要另起一套网格'
-                        '——包里的坐标是模板量出来的，自创网格等于放弃这套版式', name)
-        for i, t in enumerate(ordered[:6]):
+        for i, t in enumerate(ordered):
             b = t['box']
-            if t is title:
+            if t.get('needs_role'):
+                role = typ = 'body'
+            elif t.get('direct_type') in ('title', 'subtitle', 'footer', 'slide-number'):
+                role = typ = t['direct_type']
+            elif t is title:
                 role = typ = 'title'
             elif (title and i == 1
                   # 副标题 = 紧跟在标题下方、与标题左对齐的那一块。三个量都相对标题
@@ -1307,6 +1443,12 @@ def draft_layouts(d, outdir):
                                         round(b.get('w', 0)), round(b.get('h', 0))],
                    'type': typ, 'sz': t['sz'], 'txt': t['txt']}
             row.update(t.get('style') or {})
+            if t.get('needs_role'):
+                row.update({
+                    '_needs_role': True,
+                    '_source_layer': t.get('source_layer'),
+                    '_placeholder': t.get('placeholder'),
+                })
             slots.append(row)
         # 代表页上的小图元素按位置去重后落 slots（同一 logo 在不同页型位置不同）
         seen_mark = set()
@@ -1320,7 +1462,15 @@ def draft_layouts(d, outdir):
                           'media': mk['media'],
                           'box': [round(b.get('x', 0)), round(b.get('y', 0)),
                                   round(b.get('w', 0)), round(b.get('h', 0))]})
-        decor = collect_decor(shapes, rep['part'], {tuple(s['box']) for s in slots}, (cW, cH))
+        taken = {tuple(s['box']) for s in slots}
+        decor = []
+        seen_decor = set()
+        for source_part in (rep.get('layout'), rep['part']):
+            for item in collect_decor(shapes, source_part, taken, (cW, cH)):
+                key = (tuple(item['box']), item['geom'], item['css'])
+                if key not in seen_decor:
+                    seen_decor.add(key)
+                    decor.append(item)
         archetypes.append({'name': name, 'bg': None, 'bg_raw': bg_raw, 'slots': slots,
                            'decor': decor,
                            'pages': sorted(p['no'] for p in ps), 'rep': rep['no'],
@@ -1470,10 +1620,11 @@ def emit_frontmatter(d, tokens, fonts, roles, anchors, gaps, ldir):
         L.append('spacing:')
         L.append('  page-padding: {top: %s, right: %s, bottom: %s, left: %s}'
                  % (edge['top'], edge['right'], edge['bottom'], edge['left']))
-    # 只排除「圆角量为零」（那是直角不是圆角），不再设「出现几次才算数」的门槛
-    radii = [r for r in (d.get('radii_census') or []) if r['px'] >= 1]
-    if radii:
-        top = max(radii, key=lambda r: r['n'])
+    # rounded.card 是全局 token，只能表达全档共同的一档圆角。多个非零档位或零/非零
+    # 混用时，圆角属于 layouts.md 里的局部形状事实，压成一个值会把直角容器也圆角化。
+    radii = d.get('radii_census') or []
+    if len(radii) == 1 and radii[0]['px'] >= 1:
+        top = radii[0]
         L.append('rounded:')
         L.append('  card: %dpx' % round(top['px']))
     if edges_full:
@@ -1509,9 +1660,13 @@ def draft_flow(a, facts, canvas):
     cW, cH = canvas
     # 装饰件也算进来：很多模板的版式层只有几个占位符，真正撑起版面的是卡片容器
     # （在 decor 里）。只看 slots 会把一页的主体结构整个漏掉。
-    items = [s for s in a['slots'] if s.get('box')]
-    items += [{'role': 'container', 'type': 'decor', 'box': dcr['box'], 'css': dcr.get('css')}
-              for dcr in (a.get('decor') or [])]
+    slots = [s for s in a['slots'] if s.get('box')]
+    fixed_roles = {'logo', 'slide-number', 'page-number', 'header', 'footer'}
+    fixed = [s for s in slots if s.get('role') in fixed_roles]
+    content_slots = [s for s in slots if s.get('role') not in fixed_roles]
+    containers = [{'role': 'container', 'type': 'decor', 'box': dcr['box'],
+                   'css': dcr.get('css')} for dcr in (a.get('decor') or [])]
+    items = group_flow_cards(content_slots, containers)
     if len(items) < 2:
         return None
     items.sort(key=lambda s: (s['box'][1], s['box'][0]))
@@ -1522,7 +1677,7 @@ def draft_flow(a, facts, canvas):
         return None
     # 区带边界 = 间距分布里的最大空档。同一区带内部的间距（网格行距之类）总是明显
     # 小于区带之间的间距，用本页自己的分布切，不设固定阈值。
-    cut = _gap_cut(pos, min(pos), max(pos)) if len(pos) > 1 else max(pos) + 1
+    cut = _gap_cut(pos, min(pos), max(pos)) if len(pos) > 1 else pos[0]
     regions, cur = [], [items[0]]
     for i, g in enumerate(gaps):
         if g >= cut:
@@ -1531,6 +1686,11 @@ def draft_flow(a, facts, canvas):
         cur.append(items[i + 1])
     regions.append(cur)
 
+    # 整页左右边距 = 所有内容的横向外包络，作为各区带的缺省。
+    lefts = [s['box'][0] for s in items]
+    rights = [s['box'][0] + s['box'][2] for s in items]
+    page_margin = [min(lefts), cW - max(rights)]
+
     out = []
     for reg in regions:
         if not reg:
@@ -1553,8 +1713,17 @@ def draft_flow(a, facts, canvas):
             if len(rows) > 1:
                 row_gap = round(rows[1][0]['box'][1]
                                 - (rows[0][0]['box'][1] + rows[0][0]['box'][3]))
-            out.append({'kind': 'grid', 'cols': cols, 'gap': [max(col_gap, 0), max(row_gap, 0)],
-                        'items': rows[0]})
+            region = {'kind': 'grid', 'cols': cols, 'gap': [max(col_gap, 0), max(row_gap, 0)],
+                      'items': rows[0]}
+            # 卡片组的横向范围常和整页不同（标题贴左、卡片居中）。整页边距是所有元素的
+            # 外包络，直接套给居中卡片组会把它拉偏成左对齐。区带范围和整页明显不一致时，
+            # 落这个区带自己的左右边距，消费端把网格放进它再填 1fr。按落盘的整数比较，
+            # 亚像素噪声不触发多余的区带边距。
+            reg_margin = [min(s['box'][0] for s in rows[0]),
+                          cW - max(s['box'][0] + s['box'][2] for s in rows[0])]
+            if [int(reg_margin[0]), int(reg_margin[1])] != [int(page_margin[0]), int(page_margin[1])]:
+                region['margin'] = reg_margin
+            out.append(region)
         elif len(rows) == len(reg):
             # 每行一个元素 = 真的竖着排
             inner = 0
@@ -1565,14 +1734,91 @@ def draft_flow(a, facts, canvas):
             # 每行元素数不一致（比如左列两张、右列一张跨两行）。硬说成 stack 会让消费端
             # 以为它们是竖排的，比不给还糟。如实说这块推不出规整结构，按坐标摆。
             out.append({'kind': 'free', 'items': reg})
+    if fixed:
+        out.append({'kind': 'free', 'items': fixed})
     if len(out) < 2:
         return None
-    lefts = [s['box'][0] for s in items]
-    rights = [s['box'][0] + s['box'][2] for s in items]
-    return {'top': items[0]['box'][1], 'margin': [min(lefts), cW - max(rights)],
+    return {'top': items[0]['box'][1], 'margin': page_margin,
             'gap': round(cut), 'regions': out}
 
 
+def box_contains(outer, inner):
+    return (outer[0] <= inner[0] and outer[1] <= inner[1]
+            and outer[0] + outer[2] >= inner[0] + inner[2]
+            and outer[1] + outer[3] >= inner[1] + inner[3])
+
+
+def boxes_overlap(a, b):
+    return (min(a[0] + a[2], b[0] + b[2]) > max(a[0], b[0])
+            and min(a[1] + a[3], b[1] + b[3]) > max(a[1], b[1]))
+
+
+def overlap_ratio(outer, inner):
+    width = min(outer[0] + outer[2], inner[0] + inner[2]) - max(outer[0], inner[0])
+    height = min(outer[1] + outer[3], inner[1] + inner[3]) - max(outer[1], inner[1])
+    if width <= 0 or height <= 0 or inner[2] <= 0 or inner[3] <= 0:
+        return 0
+    return width * height / (inner[2] * inner[3])
+
+
+def group_flow_cards(slots, containers):
+    """把并列卡片容器及其文字组成一层 group，避免拍平成多列元素。"""
+    candidates = []
+    for container in containers:
+        children = [slot for slot in slots if box_contains(container['box'], slot['box'])]
+        if len(children) >= 2:
+            candidates.append((container, children))
+    selected = []
+    for container, children in sorted(
+            candidates, key=lambda pair: pair[0]['box'][2] * pair[0]['box'][3]):
+        if not any(boxes_overlap(container['box'], other['box']) for other, _ in selected):
+            selected.append((container, children))
+    if len(selected) < 2:
+        return slots + containers
+
+    grouped_slots = {id(slot) for _, children in selected for slot in children}
+    nested_by_container = {}
+    for container, _ in selected:
+        nested_by_container[id(container)] = [
+            other for other in containers
+            if other is not container and overlap_ratio(container['box'], other['box']) >= 0.9
+        ]
+    grouped_containers = {
+        id(container)
+        for container, _ in selected
+        for container in [container] + nested_by_container[id(container)]
+    }
+    out = [slot for slot in slots if id(slot) not in grouped_slots]
+    out += [container for container in containers if id(container) not in grouped_containers]
+    for container, children in selected:
+        children = children + nested_by_container[id(container)]
+        children = sorted(children, key=lambda slot: (slot['box'][1], slot['box'][0]))
+        gaps = [children[i + 1]['box'][1]
+                - (children[i]['box'][1] + children[i]['box'][3])
+                for i in range(len(children) - 1)]
+        outer = container['box']
+        insets = [
+            min(child['box'][1] - outer[1] for child in children),
+            min(outer[0] + outer[2] - child['box'][0] - child['box'][2] for child in children),
+            min(outer[1] + outer[3] - child['box'][1] - child['box'][3] for child in children),
+            min(child['box'][0] - outer[0] for child in children),
+        ]
+        padding = max(0, round(min(insets)))
+        css = container.get('css') or ''
+        if padding:
+            css = '; '.join(part for part in (
+                css.rstrip('; '), 'box-sizing: border-box', 'padding: %dpx' % padding) if part)
+        out.append({
+            'role': 'group',
+            'type': 'group',
+            'box': outer,
+            'css': css,
+            'gap': max(0, round(min(gaps))) if gaps else 0,
+            'items': children,
+        })
+    return out
+
+
 def structure_facts(archetypes, d, shapes):
     """每个页型的**结构事实**：栅格、垂直间距序列、容器样式配方、样张里的实际字数。
 
@@ -1601,8 +1847,7 @@ def structure_facts(archetypes, d, shapes):
                                   'fill': fill, 'line': line, 'fx': fx, 'shapes': set()})
         g['n'] += 1
         g['parts'].add(s.get('part'))
-        if s.get('radius_px'):
-            g['radii'].append(s['radius_px'])
+        g['radii'].append(s.get('radius_px') or 0)
         g['shapes'].add(id(s))
     ranked = sorted(groups.values(), key=lambda g: -g['n'])
     recipe_id = {}
@@ -1645,7 +1890,8 @@ def structure_facts(archetypes, d, shapes):
 def emit_layouts(archetypes, ldir, busy_hints=None, facts=None, recipes=None):
     prefilled = sum(1 for a in archetypes if a.get('zh'))
     L = ['# 判断单草案 —— package.py 读它产出 layouts.md，deck 的版式坐标从 layouts.md 读。',
-         '# 只改 names / roles / bg_rules 三段（都是扁平键值，改完 package.py 自动并回各页型）。',
+         '# 只改 names / roles / text_roles / layout_modes / bg_rules 五段（都是扁平键值，'
+         '改完 package.py 自动并回各页型）。',
          '# 下面 layouts 段是普查数值，一个字都不要动——改它容易连带删掉 slots/confidence。']
     if prefilled:
         L.append('# names 已按模板自带的版式名填好 %d 条，读一遍确认表意即可，通常不用改。' % prefilled)
@@ -1674,6 +1920,32 @@ def emit_layouts(archetypes, ldir, busy_hints=None, facts=None, recipes=None):
                         len([s for s in a['slots'] if not s.get('asset')]),
                         '/'.join(str(x) for x in szs[:5]) or '未声明',
                         a.get('pic_n') or 0, '；有满屏底图' if a.get('bg_raw') else ''))
+    text_role_ids = {}
+    for a in archetypes:
+        index = 0
+        for slot in a.get('slots') or []:
+            if not slot.get('_needs_role'):
+                continue
+            index += 1
+            text_role_ids[id(slot)] = '%s-text-%d' % (a['name'], index)
+    if text_role_ids:
+        L.append('text_roles:   # 取值 title|subtitle|header|footer|body；只改角色，不删槽')
+        for a in archetypes:
+            for slot in a.get('slots') or []:
+                role_id = text_role_ids.get(id(slot))
+                if not role_id:
+                    continue
+                L.append('  %s: TODO文本角色   # 来源 %s；占位符 %s；样例 %s；'
+                         'box %s；字号 %s；css %s'
+                         % (role_id, slot.get('_source_layer') or '-',
+                            slot.get('_placeholder') or '-', q(slot.get('txt') or ''),
+                            slot.get('box'), round(slot.get('sz') or 0),
+                            q(slot.get('css') or '未声明')))
+    flow_archetypes = [a for a in archetypes if a.get('flow')]
+    if flow_archetypes:
+        L.append('layout_modes:   # 取值 flow|slots；内容会变的内容页优先 flow，固定构图页用 slots')
+        for a in flow_archetypes:
+            L.append('  %s: TODO布局模式   # 依据见 layouts 段该页型上方的结构事实' % a['name'])
     # 禁放区是**背景图**的属性，不是页型的属性——按背景资产分组，页型再多也不涨
     bgs = []
     for a in archetypes:
@@ -1740,8 +2012,6 @@ def emit_layouts(archetypes, ldir, busy_hints=None, facts=None, recipes=None):
             L.append('    background: %s' % a['bg'])
         fl = a.get('flow')
         if fl:
-            L.append('    # ↓ flow 与 slots 二选一：内容长度会变的页用 flow（区带依次排、'
-                     '高度由内容定、下面的自动被推下去），构图固定的页用 slots。删掉不要的那个。')
             L.append('    flow:')
             L.append('      top: %d' % fl['top'])
             L.append('      margin: [%d, %d]' % tuple(fl['margin']))
@@ -1752,6 +2022,10 @@ def emit_layouts(archetypes, ldir, busy_hints=None, facts=None, recipes=None):
                     L.append('        - kind: grid')
                     L.append('          cols: %d' % r['cols'])
                     L.append('          gap: [%d, %d]' % tuple(r['gap']))
+                    if r.get('margin'):
+                        L.append('          margin: [%d, %d]  # 本区带自己的左右边距，'
+                                 '和整页 margin 不同（居中卡片组不跟标题的左边距）'
+                                 % tuple(r['margin']))
                 elif r['kind'] == 'free':
                     L.append('        - kind: free   # 推不出规整结构，按 slots 的坐标摆')
                 else:
@@ -1759,6 +2033,32 @@ def emit_layouts(archetypes, ldir, busy_hints=None, facts=None, recipes=None):
                     L.append('          gap: %d' % r['gap'])
                 L.append('          items:')
                 for s in r['items']:
+                    if s.get('type') == 'group':
+                        L.append('            - role: group')
+                        L.append('              gap: %d' % s['gap'])
+                        if s.get('css'):
+                            L.append('              css: "%s"'
+                                     % str(s['css']).replace('"', "'"))
+                        L.append('              items:')
+                        for child in s['items']:
+                            role_id = text_role_ids.get(id(child))
+                            if role_id:
+                                L.append('                # text-role: %s' % role_id)
+                            if child.get('type') == 'decor':
+                                L.append('                - {role: container, css: "%s"}'
+                                         % str(child.get('css') or '').replace('"', "'"))
+                                continue
+                            extra = ''
+                            if child.get('css') is not None:
+                                extra += ', css: "%s"' % str(child['css']).replace('"', "'")
+                            if child.get('asset'):
+                                extra += ', asset: %s' % child['asset']
+                            L.append('                - {role: %s, type: %s%s}'
+                                     % (child['role'], child['type'], extra))
+                        continue
+                    role_id = text_role_ids.get(id(s))
+                    if role_id:
+                        L.append('            # text-role: %s' % role_id)
                     # free 区带按坐标摆，而 slots 会被删掉，所以坐标必须写在这里
                     bx = ', box: %s' % s['box'] if r['kind'] == 'free' else ''
                     if s.get('type') == 'decor':
@@ -1766,25 +2066,22 @@ def emit_layouts(archetypes, ldir, busy_hints=None, facts=None, recipes=None):
                                  % (bx, (s.get('css') or '').replace('"', "'")))
                         continue
                     extra = bx
-                    for k in ('size', 'weight', 'color', 'css', 'align', 'valign'):
-                        if s.get(k) is not None:
-                            # 色值与 css 串一律加引号：里面的逗号/冒号在 flow map 里是分隔符
-                            extra += ', %s: %s' % (
-                                k, '"%s"' % str(s[k]).replace('"', "'")
-                                if k in ('color', 'css') else s[k])
+                    if s.get('css') is not None:
+                        # CSS 串一律加引号：里面的逗号/冒号在 flow map 里是分隔符
+                        extra += ', css: "%s"' % str(s['css']).replace('"', "'")
                     if s.get('asset'):
                         extra += ', asset: %s' % s['asset']
                     L.append('            - {role: %s, type: %s%s}' % (s['role'], s['type'], extra))
         L.append('    slots:')
         for s in a['slots']:
+            role_id = text_role_ids.get(id(s))
+            if role_id:
+                L.append('      # text-role: %s' % role_id)
             extra = ''
             if s.get('asset'):
                 extra += ', asset: %s' % s['asset']
-            for k in ('size', 'weight', 'color', 'css', 'align', 'valign'):
-                if s.get(k) is not None:
-                    v = s[k]
-                    extra += ', %s: %s' % (
-                        k, '"%s"' % str(v).replace('"', "'") if k in ('color', 'css') else v)
+            if s.get('css') is not None:
+                extra += ', css: "%s"' % str(s['css']).replace('"', "'")
             L.append('      - {role: %s, box: %s, type: %s%s}'
                      % (s['role'], s['box'], s['type'], extra))
         if a.get('decor'):
@@ -1811,7 +2108,7 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
 
     L = ['## Overview', '',
          'TODO: 两三句话讲清这套模板的性格与适用场景——看过联系表和页面重建图之后再写。', '']
-    L.append(('模板自带 %d 种版式，页型、坐标、字号、色值都直读自版式层。'
+    L.append(('模板自带 %d 种版式，页型、坐标和 CSS 样式都直读自版式层。'
               % len(archetypes)) if (d.get('form_hint') or {}).get('form') == 3 else
              ('%d 页样张归纳出 %d 种页型。' % (d['counts']['slides'], len(archetypes))))
     L += ['', '## Usage', '',
@@ -1826,27 +2123,43 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
           % sidecar,
           '3. **按页型给的形态落元素** —— 页型给 `flow` 就用流式，给 `slots` 就用绝对，'
           '两者只会出现一个。'
-          '**flow**：整块用一个纵向 flex 容器，`top` 是它的起始 y，`margin` 是左右边距，'
+          '**flow**：整块用一个纵向 flex 容器，`top` 是它的起始 y，`margin` 是整块的左右边距，'
           '`gap` 是区带之间的间距；`regions` 从上往下依次排，**每个区带的高度由它自己的'
           '内容决定，不要写死高度**——上面的区带内容变多时，下面的自然被推下去，这正是'
           '这套表达要解决的事。区带内部：`kind: grid` 用 `grid-template-columns: repeat(cols, 1fr)` '
           '配 `gap: [行间距, 列间距]`；`kind: stack` 用纵向 flex 配 `gap`；`kind: free` '
-          '按该页型 `slots` 里的坐标绝对定位。`role: container` 的项是容器，把它的 `css` '
-          '原样写进 style，内容放进去。',
+          '按 item 自带的 `box` 绝对定位。区带自带 `margin: [左, 右]` 时用它的、'
+          '覆盖整块的 `margin`（模板里居中的卡片组和贴左的标题横向范围本就不同）；'
+          '没带就用整块的 `margin`。`grid` 在自己这份左右边距里再 `repeat(cols, 1fr)`。'
+          '`grid` 里的 `role: group` 是一张卡片：'
+          'group 的 `css` 用于外层容器，内部 `items` 按顺序纵向排布并使用 group 的 `gap`。'
+          '每个 `role: container` 的项是容器，把它的 `css` 逐项原样写进 style，内容放进去；'
+          '其中没有 `border-radius` 就按 `0`，不得自行补圆角。',
           '4. **按 slot 落元素（页型给的是 slots 时）** —— 每个 slot 渲染成一个绝对定位元素：`box` 是 '
-          '`[x, y, w, h]`（%dx%d 画布上的绝对像素），字号取 slot 的 `size`，'
-          '字重取 `weight`，颜色取 `color`，对齐取 `align` / `valign`。'
+          '`[x, y, w, h]`（%dx%d 画布上的绝对像素），机械展开成 `left/top/width/height`；'
+          'slot 的 `css` 是模板排版属性已转译好的声明串，原样写进 style，不要另选字号、'
+          '内边距、颜色或对齐。'
           '带 `asset` 的 slot 是图片元素（logo、角标），把该资产放在它自己的 `box` 里；'
           '这个页型没有 `asset` 槽，这一页就不出现该资产。' % (canvas[0], canvas[1]),
           '5. **铺装饰几何** —— 页型的 `decor` 是这一页的图形骨架（图标托底的圆、'
-          '卡片、分隔线）：每条渲染成一个绝对定位空元素，`box` 给位置，`css` 原样写进 style，'
-          '`geom: ellipse` 另加 `border-radius: 50%`。它们压在背景之上、slot 之下，'
+          '卡片、分隔线）：每条渲染成一个绝对定位空元素，`box` 给位置，`css` 逐项原样写进 '
+          'style；没有 `border-radius` 就按 `0`。只有 `geom: ellipse` 另加 '
+          '`border-radius: 50%`。它们压在背景之上、slot 之下，'
           '落在 slot 上的图标正是靠它们托住。',
-          '6. **配色与字体** —— 色板见下面 Colors 段，字体栈与 `@import` 见 Typography 段。']
+          '6. **落实全局设计** —— `design.md` frontmatter 的 `colors`、`typography`、'
+          '`spacing`、`rounded`、`components` 是全局 token；用 CSS variables、类名或内联'
+          '样式承载。局部 slot / decor 的 `css` 优先，不能再解释成另一套视觉系统。'
+          '字体使用 Typography 的完整栈与降级，不在运行时安装字体或依赖。',
+          '7. **保持标题结构** —— 有合适页型可参考时，沿用该页型已有的标题层级与局部 '
+          '`css`；只渲染该页型已有的文字槽，背景中已经可见的固定标题不再创建文本，'
+          '页型没有 `subtitle` 槽就不新增副标题。没有合适参考时，按本包整体视觉组织标题。']
     if assets:
         L += ['', '资产文件（背景由页型的 `background` 字段指定，'
               '图片资产的位置由该页型 `slots` 里带 `asset` 的槽给出）：', '',
-              '{{ASSET_TABLE}}']
+              '{{ASSET_TABLE}}', '',
+              '将包内 `assets/` 复制到项目内相对目录，再引用复制后的路径；最终 HTML 不引用'
+              '抽取工作目录或本机绝对路径。附件只提供 `assetRoot` / `assetPaths` 时，把'
+              '`assetRoot` 当作不透明前缀，只拼接清单中声明的相对路径。']
     L += ['', '文字与容器的外接矩形落在该页型 `background` 对应的 `text_safe` 内，'
           '避开 `avoid` 列出的区域（两者都在 %s 的 `backgrounds` 段）。内容装不下时换页型或拆页。'
           % sidecar, '',
@@ -1861,7 +2174,8 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
             '，源为商业/内部字体无 web 分发源，按气质降级到 %s' % f['stack'][1]
             if len(f['stack']) > 1 else ''))
     L += ['', '字号轴：' + '、'.join('%s %dpx' % (k, round(v['sz_px'])) for k, v in roles.items())
-          + '。slot 自带 `size` 时以 slot 为准；层级在轴上没有的，复用最接近的一档。', '',
+          + '。slot 自带 `css` 时以其中的 `font-size` 为准；没有 slot CSS 的新增层级，'
+          '复用轴上最接近的一档。', '',
           '字体加载（**HARD REQUIREMENT：下面这行 @import 原样写入全局样式首行，禁止替换为 '
           'fonts.googleapis.com 或其他域**）：', '', '```', imp, '```', '',
           '镜像只保证 wght 400 一档，更粗的字重由浏览器合成，字重不能作为唯一区分手段；'
@@ -1884,7 +2198,15 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
                  % (logo['id'], '、'.join('`%s`' % x for x in with_logo) or '（无）'))
     L += ['- 坐标、字号、色值、资产位置以 %s 为准；本文件的 Colors / Typography 是可用值的清单。'
           % sidecar,
-          '- 色板里没有绿/红这类语义色时，正负用同族颜色的深浅或透明度区分——先看 Colors 段确认。',
+          '- 强调色族以 Colors 和 %s 的 slot CSS 为主；必要时可以使用 Colors 之外的颜色，'
+          '但不能形成与模板主色竞争的第二强调色。' % sidecar,
+          '- 新增颜色应与模板整体的色相、明度和饱和度关系协调。允许新增中性色、低彩度辅助色'
+          '或局部语义色表达正负、风险、警告、状态、图表序列，但保持辅助层级；'
+          '只要新色通过高饱和、高对比、大面积或跨页重复获得主视觉权重，'
+          '或被用于标题、关键数字、图表主序列、卡片底色或渐变，就属于新的强调色，改用模板'
+          '强调色族的深浅、透明度，或改用线型、纹理、标签区分。',
+          '- 交付前逐页检查：色板、字体、版式、背景、资产和本段规则均来自本风格包；'
+          '页面无资源加载失败、内容溢出或画幅裁切。',
           '- 本包里的数值就是普查结果，照用即可，无需重新统计颜色、字体或版式。',
           '- 风格包以文本形式（zip 摘要等）到手时，直接用摘要里 design.md / layouts.md 的文本。',
           '', '## Exceptions', '']
@@ -1974,7 +2296,7 @@ def emit_brief(d, ctx, ldir):
     if leftover:
         L += ['', '未归入 archetype 的页：%s —— 都是单页孤例，需要就自己补一个 archetype。'
               % ', '.join(map(str, leftover))]
-    L += ['', '各 archetype 的 slot 原文（据此起中文页型名、改 role）：', '']
+    L += ['', '各 archetype 的 slot 原文（据此起中文页型名，并在 text_roles 判断文本角色）：', '']
     for a in archetypes:
         L.append('- `%s`（第 %s 页，覆盖 %s）' % (a['name'], a['rep'], a['pages']))
         for s in a['slots']:
@@ -2124,7 +2446,7 @@ def main(argv=None):
             gaps.append('源字体 %s 不在 font-fallback 表里，字体栈只有原名，消费端很可能装不上；'
                         '按气质挑一个有 web 分发源的近似体补进栈，不要照抄原名。' % f['names'][0])
     nosize = [(a['name'], s['box']) for a in archetypes for s in a['slots']
-              if not s.get('asset') and not s.get('size')]
+              if not s.get('asset') and not s.get('_font_size')]
     if nosize:
         gaps.append('这些文字槽在源文件任何层级都没有字号声明（都不是占位符，是普通文本框，'
                     '继承源是 presentation.xml 的 defaultTextStyle，本抽取按约定不解继承链）：'