@lark-apaas/coding-steering 0.1.32-dev.942e73f → 0.1.32-dev.b12eab4

package/package.json

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

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

@@ -130,19 +130,19 @@ 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 data-pptx-layout="<chosen archetype>">`.
+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. Before the regular slide preflight, verify every template logo against the selected archetype:
+8. Before the regular slide preflight, verify every background and fixed image asset against the selected archetype:
 
    ```bash
-   PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/verify_logo_scope.py <pack_dir> <index.html> --asset-prefix <copied-assets-prefix>
+   PYTHONDONTWRITEBYTECODE=1 python3 -B scripts/verify_layout_assets.py <pack_dir> <index.html> --asset-prefix <copied-assets-prefix>
    ```
 
-   `PPTX_LOGO_SCOPE: FAIL` means remove or move every listed logo according to `layouts.md`, then rerun this command.
+   `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/draft.py

@@ -981,6 +981,13 @@ def background_decor(background, canvas):
             '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
 
@@ -1236,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 = []
@@ -1539,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 = {}, {}
-    bg_of_layout = {row['part']: row.get('background') for row in d.get('layouts') or []}
+    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_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])):
@@ -1556,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)
@@ -1602,7 +1626,7 @@ def draft_layouts(d, outdir, effective_alpha=None):
                 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 bg_of_layout.get(layout_part)
+        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), 'background': background,
@@ -1632,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 的第一页是模板的门面，孤例也不能被名额挤掉。
@@ -1654,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%」这类固定比例切：
@@ -1739,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,
@@ -2382,7 +2408,9 @@ def emit_manifest(d, assets, vision_groups, ldir, archetypes=()):
          '  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:
@@ -2909,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')
@@ -3044,7 +3074,9 @@ def emit_body(d, tokens, fonts, roles, assets, archetypes, exceptions, cusage, l
           '页数多于页型时，挑最接近的一个原样套用它的 slot：用不到的槽删掉，'
           '内容比槽多就按同类槽的间距等距加，**坐标一律沿用该页型给的那套，不要自己另起网格**。'
           '每个生成页面的 `<section>` 都写 `data-pptx-layout="<页型名>"`，'
-          '交付前据此核验 logo 只出现在该页型的资产槽中。' % sidecar,
+          '多主题包默认只选兼容 `default-theme` 的页型；确需切换时，该页同时写 '
+          '`data-pptx-theme="<主题名>"`，且主题必须属于该页型的 `themes`。'
+          '交付前据此核验该页型绑定的背景与图片资产均已使用，且没有跨页型误用。' % sidecar,
           '3. **按页型给的形态落元素** —— 页型给 `flow` 就用流式，给 `slots` 就用绝对，'
           '两者只会出现一个。'
           '**flow**：整块用一个纵向 flex 容器，`top` 是它的起始 y，`margin` 是整块的左右边距，'
@@ -3063,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` 另加 '

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

@@ -61,7 +61,15 @@ class DesignConsumerContractTest(unittest.TestCase):
         self.assertIn('确认全部页型后再开始搭页', body)
         self.assertIn('不能只看摘要、前几个页型', body)
         self.assertIn('data-pptx-layout="<页型名>"', body)
-        self.assertIn('交付前据此核验 logo 只出现在该页型的资产槽中', body)
+        self.assertIn('data-pptx-asset="<asset id>"', body)
+        self.assertIn(
+            'position:absolute;left:<x>px;top:<y>px;width:<w>px;height:<h>px',
+            body,
+        )
+        self.assertIn('元素必须可见', body)
+        self.assertIn('`box` 使用全画布 `[0, 0, 1920, 1080]`', body)
+        self.assertIn('该页型绑定的背景与图片资产均已使用', body)
+        self.assertIn('不得省略或换图', body)
 
 
 if __name__ == '__main__':

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

@@ -15,6 +15,7 @@ from draft import (asset_vision_contexts, bound_visual_candidates,  # noqa: E402
                    cover_background_media,
                    emit_asset_vision_groups, emit_layouts, emit_manifest,
                    fullscreen_overlay_media,
+                   layouts_from_template,
                    needs_asset_judgment, preserve_image_bearing_groups,
                    select_asset_vision_groups, slide_image_marks, slot_style,
                    visual_slot_candidates)
@@ -24,6 +25,125 @@ from package import (FONTSIZE_RE, Fail, apply_asset_decisions,  # noqa: E402
 
 
 class LayoutCssTest(unittest.TestCase):
+    def test_template_layouts_use_sampled_theme_as_default_and_keep_theme_scope(self):
+        dark_master = 'ppt/slideMasters/slideMaster1.xml'
+        light_master = 'ppt/slideMasters/slideMaster2.xml'
+        dark_layout = 'ppt/slideLayouts/slideLayout1.xml'
+        light_layout = 'ppt/slideLayouts/slideLayout2.xml'
+        data = {
+            'layouts': [
+                {'part': dark_layout, 'name': 'Dark content', 'used_by_slides': 2},
+                {'part': light_layout, 'name': 'Light content', 'used_by_slides': 0},
+            ],
+            'slides': [],
+            'theme_topology': {
+                'themes': ['light', 'dark'],
+                'default': 'light',
+                'per_master': [
+                    {'master': dark_master, 'theme_label': 'dark'},
+                    {'master': light_master, 'theme_label': 'light'},
+                ],
+            },
+            'reference_graph': {
+                'master_of_layout': {
+                    dark_layout: dark_master,
+                    light_layout: light_master,
+                },
+                'layout_of_slide': {
+                    'ppt/slides/slide1.xml': dark_layout,
+                    'ppt/slides/slide2.xml': dark_layout,
+                },
+            },
+            'background_composites': {},
+        }
+        shapes = [
+            {
+                'part': part,
+                'layer': 'layout',
+                'kind': 'sp',
+                'box': {'x': 100, 'y': 100, 'w': 800, 'h': 100},
+                'ph': {'type': 'title', 'idx': '1'},
+                'text': {'paragraphs': [{'runs': [{'text': 'Title', 'sz_px': 40}]}]},
+            }
+            for part in (dark_layout, light_layout)
+        ]
+
+        archetypes = layouts_from_template(data, shapes, 1920, 1080)
+
+        self.assertEqual('dark', data['theme_topology']['default'])
+        self.assertEqual(
+            {'content': 'dark', 'content-2': 'light'},
+            {item['name']: item['theme'] for item in archetypes},
+        )
+        with tempfile.TemporaryDirectory() as output_dir:
+            emit_layouts(archetypes, output_dir)
+            emit_manifest(data, [], [], output_dir, archetypes)
+            with open(os.path.join(output_dir, 'layouts.yaml'), encoding='utf-8') as stream:
+                layouts = stream.read()
+            with open(os.path.join(output_dir, 'manifest.yaml'), encoding='utf-8') as stream:
+                manifest = stream.read()
+        self.assertIn('    themes: [dark]', layouts)
+        self.assertIn('    themes: [light]', layouts)
+        self.assertIn('default-theme: dark', manifest)
+
+    def test_template_twin_layouts_keep_topology_but_scope_retained_layout(self):
+        dark_master = 'ppt/slideMasters/slideMaster1.xml'
+        light_master = 'ppt/slideMasters/slideMaster2.xml'
+        dark_layout = 'ppt/slideLayouts/slideLayout1.xml'
+        light_layout = 'ppt/slideLayouts/slideLayout2.xml'
+        data = {
+            'layouts': [
+                {'part': dark_layout, 'name': 'Content', 'used_by_slides': 2},
+                {'part': light_layout, 'name': 'Content', 'used_by_slides': 0},
+            ],
+            'slides': [],
+            'theme_topology': {
+                'themes': ['light', 'dark'],
+                'default': 'light',
+                'per_master': [
+                    {'master': dark_master, 'theme_label': 'dark'},
+                    {'master': light_master, 'theme_label': 'light'},
+                ],
+            },
+            'reference_graph': {
+                'master_of_layout': {
+                    dark_layout: dark_master,
+                    light_layout: light_master,
+                },
+                'layout_of_slide': {
+                    'ppt/slides/slide1.xml': dark_layout,
+                    'ppt/slides/slide2.xml': dark_layout,
+                },
+            },
+            'background_composites': {},
+        }
+        shapes = [
+            {
+                'part': part,
+                'layer': 'layout',
+                'kind': 'sp',
+                'box': {'x': 100, 'y': 100, 'w': 800, 'h': 100},
+                'ph': {'type': 'title', 'idx': '1'},
+                'text': {'paragraphs': [{'runs': [{'text': 'Title', 'sz_px': 40}]}]},
+            }
+            for part in (dark_layout, light_layout)
+        ]
+
+        archetypes = layouts_from_template(data, shapes, 1920, 1080)
+
+        self.assertEqual(1, len(archetypes))
+        self.assertEqual('dark', archetypes[0]['theme'])
+        with tempfile.TemporaryDirectory() as output_dir:
+            emit_layouts(archetypes, output_dir)
+            emit_manifest(data, [], [], output_dir, archetypes)
+            with open(os.path.join(output_dir, 'layouts.yaml'), encoding='utf-8') as stream:
+                layouts = stream.read()
+            with open(os.path.join(output_dir, 'manifest.yaml'), encoding='utf-8') as stream:
+                manifest = stream.read()
+        self.assertIn('    themes: [dark]', layouts)
+        self.assertIn('themes: [light, dark]', manifest)
+        self.assertIn('default-theme: dark', manifest)
+
     def test_text_slot_emits_rendering_style_as_css_only(self):
         shape = {
             'text': {
@@ -1185,6 +1305,85 @@ layouts:
         self.assertIn('value: "[0, 0, 1920, 1080]"', manifest)
         self.assertIn('reason: "PPT 背景铺满画布"', manifest)
 
+    def test_sampled_layouts_group_inherited_structured_background(self):
+        layout_part = 'ppt/slideLayouts/slideLayout1.xml'
+        slides = [{
+            'part': 'ppt/slides/slide%d.xml' % index,
+            'layout': layout_part,
+            'background': None,
+        } for index in range(1, 4)]
+        data = {
+            'canvas': {'px': [1920, 1080]},
+            'form_hint': {'form': 1},
+            'layouts': [{
+                'part': layout_part,
+                'name': '内容',
+                'used_by_slides': 3,
+            }],
+            'slides': slides,
+            'images': [],
+            'media': [],
+            'theme_topology': {'themes': ['single'], 'per_master': [], 'default': 'single'},
+            'reference_graph': {
+                'master_of_layout': {},
+                'layout_of_slide': {
+                    slide['part']: layout_part for slide in slides
+                },
+            },
+            'background_composites': {},
+        }
+        shapes = [{
+            'part': slide['part'],
+            'layer': 'slide',
+            'kind': 'sp',
+            'box': {'x': 100, 'y': 100, 'w': 600, 'h': 100},
+            'ph': {'type': 'title', 'idx': '1'},
+            'text': {'paragraphs': [{'runs': [{
+                'text': 'Title %d' % index,
+                'sz_px': 40,
+            }]}]},
+        } for index, slide in enumerate(slides, 1)]
+
+        backgrounds = [{
+            'source': 'bgPr',
+            'type': 'solid',
+            'color': {'resolved': '#FAF9F5'},
+        }, {
+            'type': 'gradient',
+            'stops': [
+                {'pos': 0, 'color': {'resolved': '#4B5CF5'}},
+                {'pos': 100, 'color': {'resolved': '#233AFB'}},
+            ],
+            'angle_deg': 0,
+        }]
+        for background in backgrounds:
+            with self.subTest(background=background['type']):
+                data['layouts'][0]['background'] = background
+                with tempfile.TemporaryDirectory() as output_dir:
+                    os.makedirs(os.path.join(output_dir, 'ref'))
+                    with open(os.path.join(output_dir, 'ref', 'shapes.json'), 'w',
+                              encoding='utf-8') as stream:
+                        import json
+                        json.dump({'shapes': shapes}, stream)
+                    archetypes, pages, _ = draft_layouts(
+                        data, output_dir, effective_alpha={})
+
+                self.assertEqual([1, 2, 3], sorted(
+                    page for archetype in archetypes for page in archetype['pages']))
+                self.assertTrue(all(page['background'] == background for page in pages))
+                self.assertTrue(all(archetype['bg_raw'] is None
+                                    for archetype in archetypes))
+                self.assertTrue(all(
+                    any(decor.get('trace') == 'canvas-background'
+                        for decor in archetype['decor'])
+                    for archetype in archetypes
+                ))
+                self.assertTrue(all(
+                    all(isinstance(value, str)
+                        for value in archetype['_source_backgrounds'])
+                    for archetype in archetypes
+                ))
+
     def test_asset_vision_groups_fail_when_page_screenshot_is_unreadable(self):
         candidates = [{
             'id': 'asset-1',