@lark-apaas/coding-steering 0.1.32-dev.5abff3b → 0.1.32-dev.6ef2b6f

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@lark-apaas/coding-steering",
-  "version": "0.1.32-dev.5abff3b",
+  "version": "0.1.32-dev.6ef2b6f",
   "description": "Stack-specific steering content for miaoda-coding templates",
   "type": "module",
   "files": [

package/steering/design-html/skills/pptx-style-extract/SKILL.md

@@ -74,15 +74,15 @@ mkdir -p tmp/pptx-style-extract/<unique-id> && PYTHONDONTWRITEBYTECODE=1 python3
 1. 读 `<outdir>/l-out/BRIEF.md` 一次，确定待判断文件、视觉组和页型代表页；需要查候选的全部原始位置、尺寸、重复次数、透明度或近白比例时读 `asset-vision-groups.json`。没有候选图片的页无需做图片判断。
 2. 一次并行看全部 `vision-group-*.jpg` 与 `layout-sheet.png`。每张视觉组拼版都同时给出页面语境和带编号的候选卡；透明或近白候选会同时显示棋盘格和深灰底。除非拼版把图片标成 unreadable，不打开单张素材、不再读旧的 `contact-sheet` / `asset-context-sheet`。
 3. 在 `manifest.yaml` 按每个 `asset_vision_groups` 候选实例填写 `visual_kind`；同一素材在不同页型或位置可分别判断。仅在预算外候选或需要改写既有判断时追加 `asset_decisions`；位置例外写 `box: [x, y, w, h]`，同图同位置跨页型不同时再写 `layout`。可用值固定为 `logo|slogan|background|texture|icon|decorative|illustration|photo|chart|screenshot|footer-copyright|page-number|watermark|content-image|unknown`，不新造值；`package.py` 会把它映射回现有 v2 资产类型，视觉组字段不会进入最终包。
-4. 按页面语境判断用途：本 deck 自己的品牌标志才是 `logo`；客户或合作方 logo 墙、图表、截图、产品说明图是 `content-image`；非内容、非品牌的纹理和装饰图用 `decorative` 或 `illustration`；页码、水印和版权标记用对应的 omit 类值。脚本已直接保留不透明满屏背景和封面主视觉，不为它们补判断；半透明满屏叠加层仍要在视觉组中定性。拿不准的候选用 `unknown`，不要按品牌名、页码或图片数量猜用途。
+4. 按页面语境判断用途：本 deck 自己的品牌标志才是 `logo`；图表、截图、logo 墙，以及用于解释当前页具体产品、案例或信息的图片是 `content-image`；封面、目录、章节或封底中承担构图主视觉的局部图，即使是产品或摄影图，也用 `decorative` 或 `illustration` 保留为版式素材。页码、水印和版权标记用对应的 omit 类值。脚本已直接保留不透明满屏背景和封面主视觉，不为它们补判断；半透明满屏叠加层仍要在视觉组中定性。拿不准的候选用 `unknown`，不要按品牌名、页码或图片数量猜用途。
 5. 用一次 `multi_edit` 批量完成其余 TODO：风格气质，以及 `layout-controls.yaml` 中的页型/文本角色、布局模式和背景规则。普通文本槽默认 `body`，只把确实属于 `title|subtitle|header|footer` 的例外写进 `text_roles`；有 flow 与 slots 两种形态时默认保留 slots，只有样张明确需要内容随高度重排才填 `layout_modes: <页型>: flow`。不补不存在的标题、页眉或页脚。直接编辑草案，不写脚本改 YAML，也不修改 Skill 源码。
-6. `layout-controls.yaml` 的 `bg_rules:` 按**背景资产**分组（不是按页型），逐张背景填 `text_safe` / `avoid` / `pairing_rule`：看图标清视觉主体、强光斑、深色透明区，打包时自动并入用该背景的所有页型。标题、正文、关键数字、图表、卡片、时间线及其容器的外接矩形都不得压住背景主体，透明容器也不能跨进禁放区。
+6. `layout-controls.yaml` 的 `bg_rules:` 按**背景资产**分组（不是按页型），只编辑草案已有且被页型 `background:` 引用的真实图片背景；没有 `bg_rules` 就不要新增。纯色、渐变、外框、几何装饰和透明叠层不是这里的背景资产。逐张背景填 `text_safe` / `avoid` / `pairing_rule`：看图标清视觉主体、强光斑、深色透明区，打包时自动并入用该背景的所有页型。标题、正文、关键数字、图表、卡片、时间线及其容器的外接矩形都不得压住背景主体，透明容器也不能跨进禁放区。
 
 `layout-controls.yaml` 是唯一需要编辑的版式判断文件，只含 `names`、`roles`、`text_roles`、`layout_modes` 和 `bg_rules`。`layouts.yaml` 是兼容用的坐标事实——页型、坐标、字号、色值、对齐、以及各页型自带的 `role: logo` 资产槽全部直读，**不要打开或修改它**。打包时控制文件会覆盖旧文件中的同名判断区。
 
 判断口径：
 
-- **图片按用途三分**——整幅替换底图的艺术图/摄影图属**背景族**；服务于具体内容的图表、截图、产品说明图是**内容图，不进包**；剩下既不是 logo、也不服务于内容的纹理、装饰插画、色块、几何点缀是**装饰图，标 `texture` 进 assets**。不透明满屏图默认走背景；局部图和半透明满屏叠加层结合候选图与整页语境逐张定性，避免把重要装饰误当内容丢弃。首页、末页优先保留样张，但是否为 `cover` 或 `closing` 仍按页面意图判断。
+- **图片按用途三分**——整幅替换底图的艺术图/摄影图属**背景族**；服务于当前页具体内容的图表、截图、产品说明图是**内容图，不进包**；用于封面、目录、章节或封底构图的局部主视觉不解释内容，即使画面是产品或摄影图，也属**装饰图，标 `decorative` 或 `illustration` 进 assets**；其余纹理、插画、色块、几何点缀同属装饰图。不透明满屏图默认走背景；局部图和半透明满屏叠加层结合候选图与整页语境逐张定性，避免把重要装饰误当内容丢弃。首页、末页优先保留样张，但是否为 `cover` 或 `closing` 仍按页面意图判断。
 - **logo 特指这份 deck 自己的品牌标志**——看图确认是本 PPT 的品牌文字或标志图形才留 `logo`；一页若是 logo 墙（客户/合作方 logo 罗列），那些是内容图、不当风格 logo。拿不准就保留该候选并填 `unknown`，在 `gaps` 写一句；不要删除或合并 `asset_vision_groups` 条目。
 - **anchors 是事实不是结论**——草案里每条只报测到的数（覆盖率、计数、占比），没有「这套风格的特征是 X」这种断言。这一段在 design.md 里读起来像总纲，消费端会照它建全局样式，所以脚本不敢替你下结论：一条 1/8 覆盖率的元素被描述成「跨页不动」，消费端就会每页都摆它。看过重建图后，把真正是这套模板特征的那几条改写成设计要点，不是特征的直接删掉。
 - **数值只改名不改值**——草案里的坐标/色值/字号来自普查；确需推导值（CJK 行高转译、投影尺度上抬）在 manifest 写 `derived:` 声明理由，机检认声明。
@@ -130,13 +130,20 @@ Read `<pack_dir>/design.md` first, especially `## Usage`, `## Hard Rules`, color
 When generating a deck:
 
 1. Call `copy_starter_component` with `kind: "deck-stage.js"`.
-2. Build `<deck-stage width="<canvas width>" height="<canvas height>">` using the `canvas` declared in `layouts.md` — source decks are not always 16:9, and a default-sized stage shifts every coordinate on the page. Each slide is one static `<section>`.
+2. Build `<deck-stage width="<canvas width>" height="<canvas height>">` using the `canvas` declared in `layouts.md` — source decks are not always 16:9, and a default-sized stage shifts every coordinate on the page. Each slide is one static `<section data-pptx-layout="<chosen archetype>">`. For a multi-theme pack, choose layouts compatible with `default-theme` by default. When a page intentionally switches theme, add `data-pptx-theme="<theme>"`; the theme must be listed by that layout's `themes`.
 3. Inline CSS variables from `design.md` into the HTML `<style>` block using a `--ppt-*` prefix.
 4. **位移动画用独立的 `translate` 属性**：`@keyframes fadeUp { from{opacity:0; translate:0 24px} to{opacity:1; translate:0 0} }`。`transform` 是单一属性，动画里碰它会覆盖掉元素原有的那条（`left:50%; transform:translateX(-50%)` 的居中就此丢失）；`translate` / `rotate` / `scale` 各自独立，与已有 `transform` 叠加。
-5. Map `layouts.md` slots to absolute-positioned elements inside each section: expand `box: [x,y,w,h]` mechanically to `left/top/width/height`, then apply the slot's `css` declaration string unchanged. `box` owns geometry; `css` owns all rendering style, including the template's text padding, typography, alignment, line height, letter spacing, and rotation. Do not reinterpret PPTX fields or replace slot CSS with your own type scale. A slot with `asset` is a fixed image element (logo, mark): place that asset at that box on that archetype only. Do not reflow any of this as generic web grids.
+5. Map `layouts.md` slots to absolute-positioned elements inside each section: expand `box: [x,y,w,h]` mechanically to `left/top/width/height`, then apply the slot's `css` declaration string unchanged. `box` owns geometry; `css` owns all rendering style, including the template's text padding, typography, alignment, line height, letter spacing, and rotation. Do not reinterpret PPTX fields or replace slot CSS with your own type scale. A slot with `asset` is a fixed image element: use that exact asset at that box on that archetype only; do not omit or replace it. Do not reflow any of this as generic web grids.
 6. Copy `<pack_dir>/assets/` into the project, for example `assets/pptx-style/<pack-name>/`, and reference those copied files with relative URLs. The scratch `tmp/pptx-style-extract/...` path must never appear in the final HTML.
 7. Use the font stacks and fallback rules from `design.md`; do not install fonts or dependencies at runtime.
-8. Run the slide preflight checks: no resource failures, no section overflow, and sampled screenshots follow the package colors, typography, layouts, assets, and Hard Rules.
+8. Before the regular slide preflight, verify every background and fixed image asset against the selected archetype:
+
+   ```bash
+   PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/verify_layout_assets.py <pack_dir> <index.html> --asset-prefix <copied-assets-prefix>
+   ```
+
+   `PPTX_LAYOUT_ASSETS: FAIL` means fix every reported instance according to `layouts.md`, then rerun the same command. Do not deliver or call `run_commit` until it prints `PPTX_LAYOUT_ASSETS: PASS`.
+9. Run the slide preflight checks: no resource failures, no section overflow, and sampled screenshots follow the package colors, typography, layouts, assets, and Hard Rules.
 
 ## Export Consumer Attachments
 

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

@@ -66,6 +66,7 @@ def image_census(shape_recs, bg_images, units):
             'crop': r.get('crop'), 'placement': r.get('placement'),
             'w_pct': r.get('w_pct'), 'h_pct': r.get('h_pct'),
             'in_group': bool(r.get('group_path')), 'svg': r.get('media_svg'),
+            'visible_instance_blocked': r.get('visible_instance_blocked'),
         })
     for r in shape_recs:
         f = r.get('fill') or {}
@@ -124,6 +125,8 @@ def image_census(shape_recs, bg_images, units):
             'crop_variants': sorted(crop_sigs),
             'stitch_candidate': len(crop_sigs) > 1,
             'svg_companion': next((o.get('svg') for o in occs if o.get('svg')), None),
+            'visible_instance_blocked': any(
+                o.get('visible_instance_blocked') for o in occs),
         })
     images.sort(key=lambda i: (-i['n'], i['media']))
 
@@ -606,6 +609,8 @@ def layout_inventory(pkg, graph, shapes, bg_by_part):
     for lp in pkg.layouts:
         root = pkg.xml(lp)
         cSld = root.find('p:cSld', NS)
+        master = graph['master_of_layout'].get(lp)
+        background = bg_by_part.get(lp) or bg_by_part.get(master)
         phs = Counter()
         for r in shapes:
             if r['part'] == lp and r.get('ph'):
@@ -614,11 +619,12 @@ def layout_inventory(pkg, graph, shapes, bg_by_part):
             'part': lp,
             'name': cSld.get('name') if cSld is not None else None,
             'type_attr': root.get('type', 'cust'),
-            'master': graph['master_of_layout'].get(lp),
+            'master': master,
             'used_by_slides': graph['slides_per_layout'].get(lp, 0),
             'placeholders': dict(phs),
             'shape_n': sum(1 for r in shapes if r['part'] == lp),
-            'background': bg_by_part.get(lp),
+            'background': background,
+            'background_source': lp if bg_by_part.get(lp) else master,
             'ph_signature': _ph_signature(shapes, lp),
             'guides': [],
         })

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

@@ -648,14 +648,11 @@ def probe_image(path):
 def needs_asset_judgment(candidate):
     """局部图和半透明满屏叠加层需要看图定性；不透明满屏图按背景处理。"""
     effective_alpha = candidate.get('effective_alpha_mean')
-    if ((candidate.get('probe') or {}).get('near_blank')
-            or (effective_alpha is not None and effective_alpha < 13)):
-        return False
     if not candidate.get('fullscreen'):
         return True
     alpha = (effective_alpha if effective_alpha is not None
              else (candidate.get('probe') or {}).get('alpha_mean'))
-    return alpha is not None and alpha < OPAQUE_ENOUGH
+    return alpha is not None and 13 <= alpha < OPAQUE_ENOUGH
 
 
 def fullscreen_effective_alpha(data, outdir, shapes):
@@ -844,8 +841,8 @@ def draft_assets(d, outdir, bg_needed=(), cover_media=None, bg_under=None,
     canvas_w, canvas_h = d['canvas']['px']
     for c in kept:
         effective_am = c.get('effective_alpha_mean')
-        if (c['probe'].get('near_blank')
-                or (effective_am is not None and effective_am < 13)):
+        if (c['fullscreen'] and (c['probe'].get('near_blank')
+                                 or (effective_am is not None and effective_am < 13))):
             rejected.append((c, '近全透明（alpha 均值 %.0f/255），PPT 里看不见'
                              % (effective_am if effective_am is not None
                                 else c['probe']['alpha_mean'])))
@@ -962,6 +959,35 @@ def cover_background_media(archetypes):
                  if archetype['name'] == 'cover'), None)
 
 
+def background_decor(background, canvas):
+    """把可直接重放的 PPT 背景声明落到 layouts.md 的最底层装饰。
+
+    图片背景继续走 `background:` 资产引用；纯色和线性渐变没有可复制的素材文件，
+    但同样是页型视觉的一部分，必须随页型输出。path 渐变不能由 CSS 线性渐变准确表达，
+    保留给图片/渲染链路而不伪造。
+    """
+    if not isinstance(background, dict):
+        return None
+    if background.get('type') not in ('solid', 'gradient'):
+        return None
+    if background.get('path'):
+        return None
+    css = _load_query()._recipe_css(background, None, [], [])
+    css = [re.sub(r'\s*\n\s*', ' ', value).strip() for value in css if value]
+    if not css:
+        return None
+    width, height = canvas
+    return {'box': [0, 0, width, height], 'geom': 'rect', 'css': '; '.join(css),
+            'trace': 'canvas-background'}
+
+
+def background_identity(background):
+    """返回可用于聚类和审计的稳定背景标识，不改变背景的原始表达。"""
+    if isinstance(background, dict):
+        return json.dumps(background, sort_keys=True, separators=(',', ':'))
+    return background
+
+
 # ---------------------------------------------------------------- 版式聚类
 DECOR_MIN = 40.0
 
@@ -1217,7 +1243,21 @@ def layouts_from_template(d, shapes, cW, cH):
     sample_pages_of_layout = defaultdict(list)
     for slide_part, layout_part in lay_of_slide.items():
         sample_pages_of_layout[layout_part].append(slide_no(slide_part))
+    sampled_theme_counts = Counter(
+        theme_of_master.get(master_of.get(layout_part))
+        for layout_part in lay_of_slide.values()
+    )
+    sampled_theme_counts.pop(None, None)
     default_theme = topo.get('default')
+    if sampled_theme_counts:
+        highest = max(sampled_theme_counts.values())
+        leaders = sorted(
+            theme for theme, count in sampled_theme_counts.items()
+            if count == highest
+        )
+        if default_theme not in leaders:
+            default_theme = leaders[0]
+        topo['default'] = default_theme
     multi = len(topo.get('themes') or []) > 1
 
     rows = []
@@ -1273,7 +1313,17 @@ def layouts_from_template(d, shapes, cW, cH):
             slots, bgm = instance_override(
                 shapes, inst, slots, bgm, cW, cH, composites)
         taken = {tuple(s['box']) for s in slots}
-        decor = collect_decor(shapes, inst or l['part'], taken, (cW, cH))
+        decor = []
+        inherited_background = l.get('background')
+        direct_background = next(
+            (slide.get('background') for slide in d.get('slides') or []
+             if slide.get('part') == inst and slide.get('background')),
+            None)
+        background = direct_background or inherited_background
+        background_layer = background_decor(background, (cW, cH))
+        if background_layer:
+            decor.append(background_layer)
+        decor += collect_decor(shapes, inst or l['part'], taken, (cW, cH))
         named_role = role_of_name(l.get('name'))
         rows.append({'zh': clean_layout_name(l.get('name')),
                      'role': named_role or 'content', 'role_guessed': named_role is None,
@@ -1510,16 +1560,19 @@ def draft_layouts(d, outdir, effective_alpha=None):
     image_marks = slide_image_marks(d, overlay_media)
 
     bg_of_slide, layout_of_slide = {}, {}
+    background_of_layout = {
+        row['part']: row.get('background') for row in d.get('layouts') or []
+    }
     for s in d.get('slides', []):
         bg = s.get('background')
-        bg_of_slide[s['part']] = json.dumps(bg, sort_keys=True) if isinstance(bg, dict) else bg
+        bg_of_slide[s['part']] = background_identity(bg)
         layout_of_slide[s['part']] = s.get('layout')
     # 版式层的满屏底图（form=2 常态：底图挂在 layout 上）
     composites = d.get('background_composites') or {}
-    bg_of_layout = {}
+    bg_media_of_layout = {}
     for s in shapes:
         if s.get('layer') == 'layout' and is_bleed(s) and s.get('media'):
-            bg_of_layout[s['part']] = s['media']
+            bg_media_of_layout[s['part']] = s['media']
 
     pages = []
     for part, sh in sorted(by_slide.items(), key=lambda kv: slide_no(kv[0])):
@@ -1527,7 +1580,7 @@ def draft_layouts(d, outdir, effective_alpha=None):
         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_part)
+            bg_media = bg_media_of_layout.get(layout_part)
         rendered_bg = (composites.get(part)
                        or composites.get(layout_part)
                        or bg_media)
@@ -1571,9 +1624,13 @@ def draft_layouts(d, outdir, effective_alpha=None):
             if key not in seen_marks:
                 seen_marks.add(key)
                 marks.append(mark)
+        background = next((s.get('background') for s in d.get('slides') or []
+                           if s.get('part') == part and s.get('background')), None)
+        background = background or background_of_layout.get(layout_part)
         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),
+                      'bg_color': bg_of_slide.get(part), 'background': background,
+                      'texts': texts, 'pic_n': len(pics),
                       'marks': marks, 'shape_n': len(visible_shapes), 'layout': layout_part})
 
     # 页型的**角色**（封面 / 章节页 / 内容页……）不在这里判：那是看图才能下的结论，
@@ -1599,7 +1656,11 @@ def draft_layouts(d, outdir, effective_alpha=None):
             # 不替模型下结论。和首页一样，拆组只避免它被聚类代表页吞掉。
             groups[('__last__', -2)] = [p]
             continue
-        groups[(p['bg_media'] or p['bg_color'] or 'none', density_band(p))].append(p)
+        background_key = background_identity(
+            p.get('rendered_bg') or p.get('bg_media')
+            or p.get('background') or p.get('bg_color')
+        ) or 'none'
+        groups[(background_key, density_band(p))].append(p)
 
     ranked = sorted(groups.items(), key=lambda kv: (-len(kv[1]), kv[1][0]['no']))
     # 首页所在的组一定收——deck 的第一页是模板的门面，孤例也不能被名额挤掉。
@@ -1621,15 +1682,9 @@ def draft_layouts(d, outdir, effective_alpha=None):
     leftover = sorted(p['no'] for g in ranked if g not in kept for p in g[1])
 
     archetypes = []
-    for gi, ((bg_raw, _band), ps) in enumerate(kept, 1):
+    for gi, ((_background_key, _band), ps) in enumerate(kept, 1):
         rep = max(ps, key=lambda p: len(p['texts']))
-        if bg_raw == '__first__':
-            bg_raw = rep['bg_media'] or rep['bg_color'] or 'none'
-        elif bg_raw == '__last__':
-            bg_raw = rep['bg_media'] or rep['bg_color'] or 'none'
-        rendered_bg = rep.get('rendered_bg')
-        if rendered_bg:
-            bg_raw = rendered_bg
+        bg_raw = rep.get('rendered_bg') or rep.get('bg_media')
         name = 'layout-%d' % gi
         # 标题按「位置 + 跨度」认，不按字号——big-number 类的巨号数值常比标题还大
         # 标题 = 该页最靠上的那批文本里最宽的一块。不按「画布前 28%」这类固定比例切：
@@ -1688,6 +1743,9 @@ def draft_layouts(d, outdir, effective_alpha=None):
                                       round(b.get('w', 0)), round(b.get('h', 0))]})
         taken = {tuple(s['box']) for s in slots}
         decor = []
+        background_layer = background_decor(rep.get('background'), (cW, cH))
+        if background_layer:
+            decor.append(background_layer)
         seen_decor = set()
         for source_part in (rep.get('layout'), rep['part']):
             for item in collect_decor(shapes, source_part, taken, (cW, cH)):
@@ -1703,9 +1761,13 @@ def draft_layouts(d, outdir, effective_alpha=None):
                                p['layout'] for p in ps if p.get('layout')
                            }),
                            '_source_backgrounds': sorted({
-                               p.get('rendered_bg') or p.get('bg_media') or p.get('bg_color')
+                               background_identity(
+                                   p.get('rendered_bg') or p.get('bg_media')
+                                   or p.get('background') or p.get('bg_color')
+                               )
                                for p in ps
-                               if p.get('rendered_bg') or p.get('bg_media') or p.get('bg_color')
+                               if (p.get('rendered_bg') or p.get('bg_media')
+                                   or p.get('background') or p.get('bg_color'))
                            }),
                            '_text_n': len(rep['texts']),
                            '_last_page_candidate': rep['no'] == last_page_no,
@@ -2338,7 +2400,7 @@ def visual_slot_candidates(candidates, archetypes):
     return rows
 
 
-def emit_manifest(d, assets, vision_groups, ldir):
+def emit_manifest(d, assets, vision_groups, ldir, archetypes=()):
     L = ['version: alpha',
          'name: TODO-style-name        # 英文 kebab，体现气质，不要用文件名',
          'name_zh: TODO中文名',
@@ -2346,7 +2408,9 @@ def emit_manifest(d, assets, vision_groups, ldir):
          '  TODO: 一句话说清这套模板的视觉性格（底色 / 主色 / 字形 / 版面骨架），给消费模型定调。']
     themes = d['theme_topology'].get('themes') or ['single']
     if themes != ['single'] and len(themes) > 1:
-        L += ['themes: [%s]' % ', '.join(themes), 'default-theme: %s' % themes[0]]
+        default_theme = d['theme_topology'].get('default') or themes[0]
+        L += ['themes: [%s]' % ', '.join(themes),
+              'default-theme: %s' % default_theme]
     if assets:
         L.append('assets:')
         for a in assets:
@@ -2381,6 +2445,15 @@ def emit_manifest(d, assets, vision_groups, ldir):
             '  # - {source_media: example.png, visual_kind: chart}',
             '  # - {source_media: example.png, layout: layout-2, box: [0, 0, 100, 100], visual_kind: decorative}',
         ]
+    if any(decor.get('trace') == 'canvas-background'
+           for archetype in archetypes
+           for decor in archetype.get('decor') or []):
+        canvas = d['canvas']['px']
+        L += [
+            'derived:',
+            '  - value: "[0, 0, %d, %d]"' % (canvas[0], canvas[1]),
+            '    reason: "PPT 背景铺满画布"',
+        ]
     write(os.path.join(ldir, 'manifest.yaml'), '\n'.join(L) + '\n')
 
 
@@ -2727,7 +2800,11 @@ def emit_layout_controls(layout_lines, ldir, text_role_candidates, flow_archetyp
         ]
         controls.extend('# %s: flow' % archetype['name'] for archetype in flow_archetypes)
     if 'bg_rules' in blocks:
-        controls.extend([''] + blocks['bg_rules'])
+        controls += [
+            '',
+            '# 只编辑本草案已列出的真实图片背景；它们都已被 layouts 中的 background: 引用。',
+            '# 纯色、渐变、外框、几何装饰和透明叠层不新建 bg_rules；没有本段就保持没有。',
+        ] + blocks['bg_rules']
     write(os.path.join(ldir, 'layout-controls.yaml'), '\n'.join(controls) + '\n')
 
 
@@ -2860,6 +2937,8 @@ def emit_layouts(archetypes, ldir, busy_hints=None, facts=None, recipes=None):
         L.append('  %s:' % a['name'])
         if a.get('role'):
             L.append('    role: %s' % a['role'])
+        if a.get('theme'):
+            L.append('    themes: [%s]' % a['theme'])
         if a['bg']:
             L.append('    background: %s' % a['bg'])
         fl = a.get('flow')
@@ -2982,6 +3061,10 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
               % len(archetypes)) if (d.get('form_hint') or {}).get('form') == 3 else
              ('%d 页样张归纳出 %d 种页型。' % (d['counts']['slides'], len(archetypes))))
     L += ['', '## Usage', '',
+          '**生成前必须完整阅读本 `design.md` 和 %s，确认全部页型后再开始搭页。**'
+          '不能只看摘要、前几个页型或 `## Layouts` 清单；后续页型同样可能定义背景、'
+          '安全区、资产和固定元素。' % sidecar,
+          '',
           '搭一页 PPT 六步，中间四步的数据都在 %s：' % sidecar, '']
     L += ['1. **定画布** —— 舞台按 `layouts.md` 的 `canvas` 设成 %d×%d，'
           '别套用默认尺寸：源模板的长宽比不一定是 16:9，套错了整页坐标全偏。'
@@ -2990,7 +3073,10 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
           '2. **挑页型** —— 在 %s 里按用途选一个 archetype（清单见下面 Layouts 段）。'
           '页数多于页型时，挑最接近的一个原样套用它的 slot：用不到的槽删掉，'
           '内容比槽多就按同类槽的间距等距加，**坐标一律沿用该页型给的那套，不要自己另起网格**。'
-          % sidecar,
+          '每个生成页面的 `<section>` 都写 `data-pptx-layout="<页型名>"`，'
+          '多主题包默认只选兼容 `default-theme` 的页型；确需切换时，该页同时写 '
+          '`data-pptx-theme="<主题名>"`，且主题必须属于该页型的 `themes`。'
+          '交付前据此核验该页型绑定的背景与图片资产均已使用，且没有跨页型误用。' % sidecar,
           '3. **按页型给的形态落元素** —— 页型给 `flow` 就用流式，给 `slots` 就用绝对，'
           '两者只会出现一个。'
           '**flow**：整块用一个纵向 flex 容器，`top` 是它的起始 y，`margin` 是整块的左右边距，'
@@ -3009,8 +3095,13 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
           '`[x, y, w, h]`（%dx%d 画布上的绝对像素），机械展开成 `left/top/width/height`；'
           'slot 的 `css` 是模板排版属性已转译好的声明串，原样写进 style，不要另选字号、'
           '内边距、颜色或对齐。'
-          '带 `asset` 的 slot 是图片元素（logo、角标），把该资产放在它自己的 `box` 里；'
-          '这个页型没有 `asset` 槽，这一页就不出现该资产。' % (canvas[0], canvas[1]),
+          '带 `asset` 的 slot 是固定图片实例：元素写 `data-pptx-asset="<asset id>"`，'
+          '引用复制后的原资产，并把 `box` 直接写成 inline '
+          '`position:absolute;left:<x>px;top:<y>px;width:<w>px;height:<h>px`。'
+          '元素必须可见，不得省略或换图，也不得隐藏或只在 CSS 里伪装引用；'
+          '这个页型没有 `asset` 槽，这一页就不出现该资产。'
+          '页型的 `background` 是图片资产时遵循同一实例契约，`box` 使用全画布 '
+          '`[0, 0, %d, %d]`。' % (canvas[0], canvas[1], canvas[0], canvas[1]),
           '5. **铺装饰几何** —— 页型的 `decor` 是这一页的图形骨架（图标托底的圆、'
           '卡片、分隔线）：每条渲染成一个绝对定位空元素，`box` 给位置，`css` 逐项原样写进 '
           'style；没有 `border-radius` 就按 `0`。只有 `geom: ellipse` 另加 '
@@ -3357,7 +3448,7 @@ def main(argv=None):
         exceptions.append('源 deck 第 %s 页是单页孤例，没有归纳成 archetype；需要类似构图时按最接近的页型改。'
                           % '、'.join(map(str, leftover)))
 
-    emit_manifest(d, assets, selected_vision_groups, ldir)
+    emit_manifest(d, assets, selected_vision_groups, ldir, archetypes)
     emit_frontmatter(d, tokens, fonts, roles, anchors, gaps, ldir)
     # 每张背景量一次局部对比度，作为「哪里不能压文字」的客观依据摆进判断单。
     # 只报测到的数，不替人填 avoid——哪块算主体、要不要避让，是看图才能定的。