@lark-apaas/coding-steering 0.1.32-beta.0 → 0.1.32-dev.3598eb3

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

@@ -1,5 +1,5 @@
 #!/usr/bin/env python3
-"""Stage-1 deterministic extractor for PPTX/POTX style packs (票 09 原型).
+"""Stage-1 deterministic extractor for PPTX/POTX style packs.
 
     python3 extract.py <pptx> <outdir> [--export-all-media]
 
@@ -11,6 +11,8 @@ as-is *and* re-encoded to a webp under ASSET_BUDGET_BYTES; without Pillow the
 transcode falls back to darwin `sips`, and failing that the row records
 transcode_blocked and extract.json records pillow_available: false.
 """
+import hashlib
+import io
 import json
 import os
 import re
@@ -21,7 +23,8 @@ from datetime import datetime, timezone
 
 sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
 
-from census import (DHASH_PREFILTER_MAX, FULLSCREEN_MIN_PCT, PIXDIFF_MAX, REPEAT_MIN,
+from census import (ASSET_WARN_SINGLE, DHASH_PREFILTER_MAX, FULLSCREEN_MIN_PCT, PIXDIFF_MAX,
+                    REPEAT_MIN, SMALL_IMG_W_PCT,
                     EPS_PX, color_census, content_clusters, detect_twins, font_census,
                     image_census, image_palette, layout_inventory, media_fingerprints,
                     font_scheme_by_part, radii_effects_census, read_guides,
@@ -32,7 +35,7 @@ from parts import (Package, PartCtx, build_graph, read_clrmap, read_part_shapes,
 
 SCHEMA = 'pptx-extract/stage1-v0.1'
 WEB_FORMATS = {'png', 'jpg', 'jpeg', 'gif', 'webp', 'svg'}
-ASSET_BUDGET_BYTES = 500 * 1024                       # D5b WARN line
+ASSET_BUDGET_BYTES = ASSET_WARN_SINGLE                # V2-6 单张 WARN 线
 # Quality ladder first, then resolution — dropping pixels is the more visible
 # loss, so it is only reached once the lowest quality still overshoots.
 WEBP_QUALITY_LADDER = (85, 75, 65, 55, 45)
@@ -161,6 +164,7 @@ def _webp_from_sips(part, raw, dst_base, budget):
 def export_media(pkg, images, outdir, pillow_ok, export_all=False):
     media_dir = os.path.join(outdir, 'media-out')
     os.makedirs(media_dir, exist_ok=True)
+    written = {}
     by_media = {i['media']: i for i in images}
     rows = []
     for part in pkg.media:
@@ -177,6 +181,12 @@ def export_media(pkg, images, outdir, pillow_ok, export_all=False):
                 reasons.append('variant_group')
             if info['stitch_candidate']:
                 reasons.append('crop_stitch')
+            if info.get('visible_instance_blocked'):
+                reasons.append('visible_instance_fallback')
+            if 0 < (info.get('max_w_pct') or 0) < SMALL_IMG_W_PCT and not info['fullscreen']:
+                # 小图（页内图标、角标）。不导出的话 L 层只能看着装饰容器里的空洞
+                # 自己编图形，编出来的与模板无关。
+                reasons.append('icon_candidate')
         if ext in ('svg', 'emf', 'wmf'):
             reasons.append('vector')
         row = {'media': part, 'ext': ext, 'bytes': size,
@@ -191,7 +201,15 @@ def export_media(pkg, images, outdir, pillow_ok, export_all=False):
             body = raw.decode('utf-8', 'replace')
             row['embedded_raster'] = 'data:image/' in body
         out_name = os.path.basename(part)
-        with open(os.path.join(media_dir, out_name), 'wb') as f:
+        dst_path = os.path.join(media_dir, out_name)
+        if dst_path in written:
+            # 两个 media part 落到同一个输出名。不覆盖——覆盖等于悄悄换掉一张图。
+            row['export_name_conflict'] = written[dst_path]
+            out_name = '%s~%d%s' % (os.path.splitext(out_name)[0], len(written),
+                                    os.path.splitext(out_name)[1])
+            dst_path = os.path.join(media_dir, out_name)
+        written[dst_path] = part
+        with open(dst_path, 'wb') as f:
             f.write(raw)
         row.update({'exported': True, 'out': 'media-out/' + out_name,
                     'out_bytes': len(raw), 'transcoded': False,
@@ -210,13 +228,11 @@ def export_media(pkg, images, outdir, pillow_ok, export_all=False):
         # rasterising it here would throw away the vector original.
         if needs and ext != 'svg':
             row['needs_transcode'] = needs
-            # The compressed file is only ever .webp (Pillow) or .jpg (sips). When
-            # the source already carries that extension the naive stem would point
-            # at the exported original and silently overwrite it.
-            stem = out_name.rsplit('.', 1)[0]
-            if ext in ('webp', 'jpg'):
-                stem += '-min'
-            base = os.path.join(media_dir, stem)
+            # 压缩产物必须用**完整原名**当前缀：只去掉扩展名的话，image4.png 的压缩版
+            # 就叫 image4.webp —— 而 ppt/media/image4.webp 往往是另一张真实存在的图，
+            # 两者抢同一个输出名，后写的覆盖先写的，且全程无人报错。实测某模板因此把
+            # 一张 109x109 的小图标当成了整页背景。
+            base = os.path.join(media_dir, out_name + '-min')
             done, why = None, 'pillow-unavailable' if not pillow_ok else None
             if pillow_ok:
                 try:
@@ -239,18 +255,463 @@ def export_media(pkg, images, outdir, pillow_ok, export_all=False):
     return rows
 
 
+# ---------------------------------------------------- rendered backgrounds
+def _is_full_canvas_picture(shape):
+    return (shape.get('kind') == 'pic' and shape.get('media')
+            and not shape.get('hidden')
+            and (shape.get('w_pct') or 0) >= 95
+            and (shape.get('h_pct') or 0) >= 95)
+
+
+def _shape_has_visible_text(shape):
+    text = shape.get('text') or {}
+    for paragraph in text.get('paragraphs') or []:
+        for run in paragraph.get('runs') or []:
+            if str(run.get('text') or '').strip():
+                return True
+    return False
+
+
+def _is_full_canvas_fill_overlay(shape):
+    fill = shape.get('fill') or {}
+    geometry = shape.get('geom') or {}
+    line = shape.get('line') or {}
+    return (shape.get('kind') == 'sp' and not shape.get('hidden')
+            and fill.get('type') in ('solid', 'gradient')
+            and not fill.get('path')
+            and geometry.get('prst') == 'rect'
+            and not shape.get('rot')
+            and not line.get('color') and not line.get('gradient')
+            and not _shape_has_visible_text(shape)
+            and (shape.get('w_pct') or 0) >= 95
+            and (shape.get('h_pct') or 0) >= 95)
+
+
+def _picture_has_appearance(shape):
+    return bool(shape.get('flipH') or shape.get('flipV') or shape.get('rot')
+                or shape.get('crop')
+                or (shape.get('opacity') is not None and shape.get('opacity') != 1.0))
+
+
+def _effective_background(parts, bg_by_part):
+    background = None
+    for part in parts:
+        if bg_by_part.get(part):
+            background = bg_by_part[part]
+    return background
+
+
+def _draw_picture(canvas, shape, pkg, image_cache=None):
+    """Replay one p:pic's crop, flip, rotation and blip opacity with Pillow."""
+    from PIL import Image, ImageEnhance, ImageOps
+
+    media = shape.get('media')
+    if media not in pkg.names:
+        return False
+    image_cache = image_cache if image_cache is not None else {}
+    box = shape.get('box_unrotated') or shape.get('box') or {}
+    if media not in image_cache:
+        try:
+            source = Image.open(io.BytesIO(pkg.zip.read(media))).convert('RGBA')
+            source.load()
+            image_cache[media] = source
+        except Exception:
+            return False
+    picture = image_cache[media].copy()
+
+    crop = shape.get('crop') or {}
+    left = max(0.0, min(float(crop.get('l', 0) or 0), 100.0))
+    top = max(0.0, min(float(crop.get('t', 0) or 0), 100.0))
+    right = max(0.0, min(float(crop.get('r', 0) or 0), 100.0))
+    bottom = max(0.0, min(float(crop.get('b', 0) or 0), 100.0))
+    bounds = (
+        int(round(picture.width * left / 100.0)),
+        int(round(picture.height * top / 100.0)),
+        int(round(picture.width * (1.0 - right / 100.0))),
+        int(round(picture.height * (1.0 - bottom / 100.0))),
+    )
+    if bounds[2] > bounds[0] and bounds[3] > bounds[1]:
+        picture = picture.crop(bounds)
+
+    width = max(1, int(round(box.get('w') or 0)))
+    height = max(1, int(round(box.get('h') or 0)))
+    resampling = getattr(Image, 'Resampling', Image)
+    picture = picture.resize((width, height), resampling.LANCZOS)
+    if shape.get('flipH'):
+        picture = ImageOps.mirror(picture)
+    if shape.get('flipV'):
+        picture = ImageOps.flip(picture)
+    opacity = shape.get('opacity')
+    if opacity is not None:
+        picture.putalpha(ImageEnhance.Brightness(picture.getchannel('A')).enhance(
+            max(0.0, min(float(opacity), 1.0))))
+
+    rotation = float(shape.get('rot') or 0)
+    if rotation:
+        picture = picture.rotate(-rotation, resample=resampling.BICUBIC, expand=True)
+    center_x = float(box.get('x') or 0) + width / 2.0
+    center_y = float(box.get('y') or 0) + height / 2.0
+    x = int(round(center_x - picture.width / 2.0))
+    y = int(round(center_y - picture.height / 2.0))
+    layer = Image.new('RGBA', canvas.size)
+    layer.alpha_composite(picture, (x, y))
+    canvas.alpha_composite(layer)
+    return True
+
+
+def _visible_picture_instance(shape, pkg, image_cache=None):
+    """Render one non-background picture exactly as its PPT instance appears."""
+    from PIL import Image
+
+    bounds = shape.get('box') or {}
+    source_box = shape.get('box_unrotated') or bounds
+    width = max(1, int(round(bounds.get('w') or 0)))
+    height = max(1, int(round(bounds.get('h') or 0)))
+    if not source_box.get('w') or not source_box.get('h'):
+        return None
+    local = dict(shape)
+    local['box_unrotated'] = {
+        'x': float(source_box.get('x') or 0) - float(bounds.get('x') or 0),
+        'y': float(source_box.get('y') or 0) - float(bounds.get('y') or 0),
+        'w': source_box['w'],
+        'h': source_box['h'],
+    }
+    canvas = Image.new('RGBA', (width, height))
+    if not _draw_picture(canvas, local, pkg, image_cache):
+        return None
+    return canvas if canvas.getchannel('A').getbbox() else None
+
+
+def _save_picture_instance_webp(canvas, path):
+    """Keep the instance alpha and shrink only after lossless output exceeds budget."""
+    def write(options):
+        temporary = path + '.tmp'
+        try:
+            canvas.save(temporary, 'WEBP', **options)
+            size = os.path.getsize(temporary)
+            os.replace(temporary, path)
+            return size
+        finally:
+            if os.path.exists(temporary):
+                os.unlink(temporary)
+
+    try:
+        size = write({'lossless': True, 'method': 0})
+    except Exception as exc:
+        return 'pillow-error: %s: %s' % (exc.__class__.__name__, exc)
+    if size <= ASSET_BUDGET_BYTES:
+        return None
+    for quality in (95, 90, 85, 75):
+        try:
+            size = write({'quality': quality, 'method': 6})
+        except Exception:
+            return None
+        if size <= ASSET_BUDGET_BYTES:
+            return None
+    return None
+
+
+def export_visible_picture_instances(pkg, shapes, outdir, pillow_ok, blocked=None):
+    """Replace transformed local pictures with rendered media consumers can reuse.
+
+    A raw media file cannot reproduce an instance-level crop, rotation, flip, or
+    opacity. Flattening only those non-fullscreen instances keeps the downstream
+    contract simple: every asset still resolves through ordinary ``source_media``.
+    """
+    if not pillow_ok:
+        return []
+    try:
+        from PIL import Image  # noqa: F401
+    except Exception:
+        return []
+
+    media_dir = os.path.join(outdir, 'media-out')
+    os.makedirs(media_dir, exist_ok=True)
+    blocked = blocked if blocked is not None else {}
+    rows_by_media, rendered_specs, image_cache = {}, {}, {}
+    for shape in shapes:
+        if (shape.get('kind') != 'pic' or shape.get('hidden')
+                or not shape.get('media') or shape.get('media') not in pkg.names
+                or _is_full_canvas_picture(shape) or not _picture_has_appearance(shape)):
+            continue
+        source = shape['media']
+        source_box = shape.get('box_unrotated') or shape.get('box') or {}
+        visible_box = shape.get('box') or {}
+        spec = json.dumps({
+            'source': source,
+            'source_size': [source_box.get('w'), source_box.get('h')],
+            'visible_size': [visible_box.get('w'), visible_box.get('h')],
+            'crop': shape.get('crop') or {},
+            'flipH': bool(shape.get('flipH')),
+            'flipV': bool(shape.get('flipV')),
+            'rot': shape.get('rot') or 0,
+            'opacity': shape.get('opacity', 1.0),
+        }, ensure_ascii=False, sort_keys=True)
+        media = rendered_specs.get(spec)
+        if media is None:
+            canvas = _visible_picture_instance(shape, pkg, image_cache)
+            if canvas is None:
+                continue
+            digest = hashlib.sha256(spec.encode('utf-8')).hexdigest()[:16]
+            media = 'generated/instance/picture-%s.webp' % digest
+            out = 'media-out/' + os.path.basename(media)
+            path = os.path.join(outdir, out)
+            if not os.path.exists(path):
+                reason = _save_picture_instance_webp(canvas, path)
+                if reason:
+                    row = blocked.setdefault(source, {
+                        'reason': reason, 'attempted_specs': 0, 'part_refs': [],
+                    })
+                    row['attempted_specs'] += 1
+                    row['part_refs'].append(shape.get('part'))
+                    shape['visible_instance_blocked'] = reason
+                    rendered_specs[spec] = False
+                    continue
+            rendered_specs[spec] = media
+            rows_by_media[media] = {
+                'media': media,
+                'ext': 'webp',
+                'bytes': os.path.getsize(path),
+                'used_n': 0,
+                'reasons': ['visible_picture_instance'],
+                'candidate': True,
+                'exported': True,
+                'out': out,
+                'out_bytes': os.path.getsize(path),
+                'transcoded': False,
+                'generated': True,
+                'rendered_from': source,
+                'rendered_with': {
+                    key: shape[key] for key in ('crop', 'flipH', 'flipV', 'rot', 'opacity')
+                    if shape.get(key) not in (None, False, {}, 0, 1.0)
+                },
+                'part_refs': [],
+            }
+        elif media is False:
+            blocked[source]['part_refs'].append(shape.get('part'))
+            shape['visible_instance_blocked'] = blocked[source]['reason']
+            continue
+        row = rows_by_media[media]
+        row['used_n'] += 1
+        row['part_refs'].append(shape.get('part'))
+        shape['media'] = media
+        shape.pop('media_svg', None)
+        shape['rendered_from'] = source
+    return list(rows_by_media.values())
+
+
+def _draw_background(canvas, background, pkg, image_cache=None):
+    """Draw the effective p:bg underneath picture layers."""
+    from PIL import Image
+    from render_pages import _grad_image, _grad_stops, _rgba, background_css
+
+    css = background_css(background)
+    canvas.paste(_rgba(css, (255, 255, 255, 255)),
+                 (0, 0, canvas.width, canvas.height))
+    gradient = _grad_stops(css or '')
+    if gradient:
+        canvas.alpha_composite(
+            _grad_image(Image, canvas.width, canvas.height, gradient[0], gradient[1]))
+    if background and background.get('type') == 'image' and background.get('media'):
+        _draw_picture(canvas, {
+            'media': background['media'],
+            'box_unrotated': {'x': 0, 'y': 0, 'w': canvas.width, 'h': canvas.height},
+            'crop': background.get('crop') or {},
+        }, pkg, image_cache)
+
+
+def _draw_background_fill_overlay(canvas, shape):
+    """Draw one full-canvas fill shape that visually modifies a background image."""
+    from PIL import Image
+    from render_pages import _grad_image, _grad_stops, _rgba, css_color, css_gradient
+
+    fill = shape.get('fill') or {}
+    box = shape.get('box_unrotated') or shape.get('box') or {}
+    width = max(1, int(round(box.get('w') or 0)))
+    height = max(1, int(round(box.get('h') or 0)))
+    x = int(round(box.get('x') or 0))
+    y = int(round(box.get('y') or 0))
+    if fill.get('type') == 'solid':
+        color = _rgba(css_color(fill.get('color')))
+        if color is None:
+            return False
+        overlay = Image.new('RGBA', (width, height), color)
+    elif fill.get('type') == 'gradient':
+        gradient = _grad_stops(css_gradient(fill) or '')
+        if not gradient:
+            return False
+        overlay = _grad_image(Image, width, height, gradient[0], gradient[1])
+    else:
+        return False
+    canvas.alpha_composite(overlay, (x, y))
+    return True
+
+
+def _background_layer_source(shape):
+    if shape.get('kind') == 'pic':
+        return {
+            'part': shape['part'], 'kind': 'picture', 'media': shape['media'],
+            'crop': shape.get('crop'), 'flipH': bool(shape.get('flipH')),
+            'flipV': bool(shape.get('flipV')), 'rot': shape.get('rot') or 0,
+            'opacity': shape.get('opacity', 1.0),
+        }
+    return {
+        'part': shape['part'], 'kind': 'fill_overlay',
+        'box': shape.get('box_unrotated') or shape.get('box'),
+        'fill': shape.get('fill'),
+    }
+
+
+def _save_background_webp(canvas, path):
+    """Prefer lossless output; fall back to a quality ladder when oversized."""
+    canvas.convert('RGB').save(path, 'WEBP', lossless=True, method=0)
+    if os.path.getsize(path) <= ASSET_BUDGET_BYTES:
+        return
+    rgb = canvas.convert('RGB')
+    for quality in (95, 90, 85, 75):
+        rgb.save(path, 'WEBP', quality=quality, method=6)
+        if os.path.getsize(path) <= ASSET_BUDGET_BYTES:
+            return
+
+
+def compose_backgrounds(pkg, graph, shapes, bg_by_part, units, outdir, pillow_ok):
+    """Flatten non-trivial full-canvas picture stacks into one web-safe asset."""
+    if not pillow_ok:
+        return {}, [], []
+    try:
+        from PIL import Image
+    except Exception:
+        return {}, [], []
+
+    by_part = defaultdict(list)
+    for shape in shapes:
+        by_part[shape['part']].append(shape)
+
+    chains = {}
+    for layout in pkg.layouts:
+        master = graph['master_of_layout'].get(layout)
+        show_master = pkg.xml(layout).get('showMasterSp', '1') != '0'
+        chains[layout] = [part for part in ((master if show_master else None), layout) if part]
+    for slide in pkg.slides:
+        layout = graph['layout_of_slide'].get(slide)
+        master = graph['master_of_layout'].get(layout)
+        show_master = pkg.xml(slide).get('showMasterSp', '1') != '0'
+        if layout:
+            show_master = show_master and pkg.xml(layout).get('showMasterSp', '1') != '0'
+        chains[slide] = [part for part in (
+            (master if show_master else None), layout, slide) if part]
+
+    media_dir = os.path.join(outdir, 'media-out')
+    os.makedirs(media_dir, exist_ok=True)
+    part_map, rows_by_media, images_by_media, rendered_specs = {}, {}, {}, {}
+    image_cache = {}
+    for target, chain in chains.items():
+        layers = [shape for part in chain for shape in by_part.get(part, [])
+                  if _is_full_canvas_picture(shape) or _is_full_canvas_fill_overlay(shape)]
+        pictures = [shape for shape in layers if shape.get('kind') == 'pic']
+        if not pictures or (len(pictures) == 1 and not _picture_has_appearance(pictures[0])
+                            and len(layers) == 1):
+            continue
+        source_layers = [_background_layer_source(shape) for shape in layers]
+        spec = json.dumps({
+            'background': _effective_background(chain, bg_by_part),
+            'layers': [{k: v for k, v in layer.items() if k != 'part'}
+                       for layer in source_layers],
+        }, ensure_ascii=False, sort_keys=True)
+        media = rendered_specs.get(spec)
+        if media is None:
+            canvas = Image.new('RGBA', (units.w, units.h))
+            _draw_background(
+                canvas, _effective_background(chain, bg_by_part), pkg, image_cache)
+            drawn = [
+                shape for shape in layers
+                if (_draw_picture(canvas, shape, pkg, image_cache)
+                    if shape.get('kind') == 'pic'
+                    else _draw_background_fill_overlay(canvas, shape))
+            ]
+            if len(drawn) != len(layers):
+                continue
+            digest = hashlib.sha256(canvas.tobytes()).hexdigest()[:16]
+            media = 'generated/background/bg-composite-%s.webp' % digest
+            out = 'media-out/' + os.path.basename(media)
+            path = os.path.join(outdir, out)
+            if not os.path.exists(path):
+                _save_background_webp(canvas, path)
+            rendered_specs[spec] = media
+        else:
+            out = rows_by_media[media]['out']
+            path = os.path.join(outdir, out)
+        part_map[target] = media
+        row = rows_by_media.setdefault(media, {
+            'media': media, 'ext': 'webp', 'bytes': os.path.getsize(path),
+            'used_n': 0, 'reasons': ['background_composite'], 'candidate': True,
+            'exported': True, 'out': out, 'out_bytes': os.path.getsize(path),
+            'transcoded': False, 'generated': True, 'composited_from': source_layers,
+            'part_refs': [],
+        })
+        row['used_n'] += 1
+        row['part_refs'].append(target)
+        image = images_by_media.setdefault(media, {
+            'media': media, 'n': 0, 'boxes': [], 'exact_boxes': [],
+            'fullscreen': True, 'fullscreen_n': 0, 'fullscreen_top_cluster_n': 0,
+            'repeat_fixed': [], 'max_w_pct': 100.0, 'bleed': False,
+            'crop_variants': [], 'stitch_candidate': False,
+            'svg_companion': None, 'variant_group': [],
+        })
+        image['n'] += 1
+        image['fullscreen_n'] += 1
+        image['fullscreen_top_cluster_n'] += 1
+        image['boxes'].append({
+            'box': {'x': 0, 'y': 0, 'w': units.w, 'h': units.h},
+            'box_emu': {'x': 0, 'y': 0, 'cx': units.cx, 'cy': units.cy},
+            'count': 1, 'exact_count': 1, 'exact_variants': 1,
+            'w_pct': 100.0, 'h_pct': 100.0, 'parts': [target],
+            'layers': ['composite'],
+        })
+    return part_map, list(rows_by_media.values()), list(images_by_media.values())
+
+
 # ---------------------------------------------------------------- form hint
+# PowerPoint 出厂版式名（中英两套）。设计师起的名字是「这一页干什么用」，
+# 出厂名只是「这个占位符组合叫什么」——后者不算模板声明了页型。
+STOCK_LAYOUT_NAMES = {
+    'default', 'blank', 'custom layout', 'title slide', 'title and content',
+    'section header', 'two content', 'comparison', 'title only',
+    'content with caption', 'picture with caption', 'title and vertical text',
+    'vertical title and text', 'name card', 'quote with caption', 'true or false',
+    '空白', '自定义版式', '标题幻灯片', '标题和内容', '节标题', '两栏内容', '比较',
+    '仅标题', '内容与标题', '图片与标题', '标题和竖排文字', '竖排标题与文本',
+}
+_NUM_PREFIX = re.compile(r'^\s*\d+[\s._-]*')
+
+
+def is_semantic_layout_name(name):
+    """版式名是不是设计师起的「页型名」，而不是出厂名或纯编号。
+
+    不能按字符数判断——中文页型名两个字就说清了（「封面」「目录」），任何长度门槛
+    都会把整套 CJK 命名的模板判成没有语义版式，进而走错 form 分支。
+    """
+    n = _NUM_PREFIX.sub('', (name or '').strip())
+    if not n or n.strip('0123456789 ._-') == '':
+        return False
+    return n.lower() not in STOCK_LAYOUT_NAMES
+
+
 def form_hint(pkg, graph, layouts):
     slides_with_ph = 0
     for sp in pkg.slides:
         if pkg.xml(sp).findall('.//p:ph', NS):
             slides_with_ph += 1
     names = [(l['name'] or '') for l in layouts]
-    semantic = sum(1 for n in names if len(n) > 3 and n.upper() not in ('DEFAULT', 'BLANK'))
+    semantic = sum(1 for n in names if is_semantic_layout_name(n))
     ev = {'slides_using_placeholders': '%d/%d' % (slides_with_ph, len(pkg.slides)),
           'layouts': len(pkg.layouts), 'masters': len(pkg.masters),
           'semantic_layout_names': semantic}
-    if slides_with_ph and len(pkg.layouts) >= 5 and semantic >= 5:
+    # 「模板自带页型声明」的判据是**比例**不是个数：一套只有 4 个版式但全部起了页型名的
+    # 精简模板，和一套 30 个版式里 5 个有名字的模板，前者才是真的按页型组织的。
+    semantic_ratio = semantic / float(len(pkg.layouts) or 1)
+    ev['semantic_layout_ratio'] = round(semantic_ratio, 3)
+    if slides_with_ph and semantic >= 2 and semantic_ratio >= 0.5:
         form = 3
     elif len(pkg.layouts) > 1 and not slides_with_ph:
         form = 2
@@ -404,7 +865,7 @@ REF_NOTES = """# ref/ 审计层说明（S12）
 4. **S6 XPath 口径**（写死并逐项声明）：design = `a:solidFill//` 下的颜色 + 渐变
    `a:gs` 的直接子颜色 + `p:bgRef` 的直接子颜色；editor = `p15:clr`（参考线）；
    aux = `a:buClr` 与 `p:style/a:*Ref`。effectLst 内的阴影色不计入频次。
-5. **S5 计数双口径**：`exact_boxes` 是坐标完全一致的计数（可与票 03 recon 逐数对齐）；
+5. **S5 计数双口径**：`exact_boxes` 是坐标完全一致的计数（可与逐形状人工点数对齐）；
    `boxes[]` 是 ±0.5%（{eps:.1f}px）epsilon 聚类计数，会把微偏移的同位实例并进同一簇。
    两者都落盘，差异即「容差带来的合并」。
 6. **满屏判定独立阈值**：w ≥ {fs}% 且 h ≥ {fs}%，上不封顶；出血图（>100%）同样计入满屏。
@@ -432,6 +893,30 @@ REF_NOTES = """# ref/ 审计层说明（S12）
 """
 
 
+def dump_source(pkg, outdir):
+    """把 PPTX 解压后的原文原样落到 ref/source/。
+
+    普查是有损的：它按既定口径抽数，抽不到的、口径外的东西就没了。遇到判断不了的
+    情况（这个形状为什么这么摆、某个字段是什么意思），能直接翻原始 XML 比对着二手
+    数据猜可靠得多。只进中间产物，交付包里没有。
+    """
+    dst = os.path.abspath(os.path.join(outdir, 'ref', 'source'))
+    n = 0
+    for name in pkg.zip.namelist():
+        if name.endswith('/'):
+            continue
+        p = os.path.abspath(os.path.join(dst, *name.split('/')))
+        # zip 条目名是文件里写什么就是什么，带 ../ 就能写到 ref/source 外面去
+        # （pptx 是用户上传的，当不可信输入处理）。落在目录外的条目一律不落盘。
+        if not p.startswith(dst + os.sep):
+            continue
+        os.makedirs(os.path.dirname(p), exist_ok=True)
+        with open(p, 'wb') as f:
+            f.write(pkg.zip.read(name))
+        n += 1
+    return n
+
+
 def write_ref(outdir, payload, ref_data, units, parts_ordered, shapes, bg_by_part):
     ref = os.path.join(outdir, 'ref')
     os.makedirs(ref, exist_ok=True)
@@ -551,6 +1036,9 @@ def extract(pptx, outdir, export_all=False):
                               'box_emu': {'x': 0, 'y': 0, 'cx': cx, 'cy': cy},
                               'crop': bg.get('crop'), 'placement': 'inside',
                               'w_pct': 100.0, 'h_pct': 100.0, 'in_group': False})
+    instance_blocked = {}
+    instance_media = export_visible_picture_instances(
+        pkg, shapes, outdir, pillow_ok, instance_blocked)
     images, variant_groups = image_census(shapes, bg_images, units)        # S5
     t = mark('S5_image_census', t)
 
@@ -570,11 +1058,20 @@ def extract(pptx, outdir, export_all=False):
     t = mark('derived_censuses', t)
 
     media_rows = export_media(pkg, images, outdir, pillow_ok, export_all)  # S9
+    for row in media_rows:
+        if row['media'] in instance_blocked:
+            row['visible_instance_blocked'] = instance_blocked[row['media']]
+    media_rows += instance_media
+    background_composites, composite_media, composite_images = compose_backgrounds(
+        pkg, graph, shapes, bg_by_part, units, outdir, pillow_ok)
+    media_rows += composite_media
+    images += composite_images
     t = mark('S9_media_export', t)
 
     # S5b + S14 run after S9 because the palette only covers exported assets.
-    fps = media_fingerprints(pkg, [i['media'] for i in images], pillow_ok)
-    clusters, cluster_evidence = content_clusters(images, fps)
+    source_images = [i for i in images if i['media'] in pkg.names]
+    fps = media_fingerprints(pkg, [i['media'] for i in source_images], pillow_ok)
+    clusters, cluster_evidence = content_clusters(source_images, fps)
     exported = {m['media'] for m in media_rows if m.get('exported')}
     image_palette(images, fps, exported)
     t = mark('S5b_S14_content_palette', t)
@@ -646,7 +1143,8 @@ def extract(pptx, outdir, export_all=False):
             'Pillow unavailable: byte-identical media only, no perceptual merging'),
         'palette_available': pillow_ok,
         'media': media_rows,
-        # S4 shape-facts are 49-64% of this file (volcano: 1.4 MB) and stage 2 reads
+        'background_composites': background_composites,
+        # S4 shape-facts dominate this file (roughly half its bytes) and stage 2 reads
         # them only when a derived statistic needs backing evidence, so they live in
         # a sidecar and extract.json keeps just the pointer plus the derived censuses.
         'shapes_ref': 'ref/shapes.json',
@@ -656,6 +1154,7 @@ def extract(pptx, outdir, export_all=False):
             'slides': len(pkg.slides), 'layouts': len(pkg.layouts),
             'masters': len(pkg.masters), 'themes': len(pkg.themes),
             'media': len(pkg.media),
+            'background_composites': len(composite_media),
             'shapes_total': len(shapes),
             'shapes_kept': len(kept_shapes),
             'shapes_dropped_off_canvas': len(dropped_shapes),
@@ -665,8 +1164,12 @@ def extract(pptx, outdir, export_all=False):
                                         if r.get('placement') == 'inherited'),
             'content_clusters': len(clusters),
             'content_clusters_multi_media': sum(1 for c in clusters if c['member_n'] > 1),
-            'media_exported': sum(1 for m in media_rows if m.get('exported')),
-            'media_transcoded': sum(1 for m in media_rows if m.get('transcoded')),
+            'media_exported': sum(1 for m in media_rows
+                                  if m.get('exported') and not m.get('generated')),
+            'media_instances': len(instance_media),
+            'media_instance_blocked': len(instance_blocked),
+            'media_transcoded': sum(1 for m in media_rows
+                                    if m.get('transcoded') and not m.get('generated')),
             'media_transcode_blocked': sum(1 for m in media_rows
                                            if m.get('transcode_blocked')),
             'media_over_budget': sum(1 for m in media_rows if m.get('over_budget')),
@@ -723,6 +1226,7 @@ def extract(pptx, outdir, export_all=False):
     with open(out_json, 'w') as f:
         json.dump(payload, f, ensure_ascii=False, indent=1)
     write_ref(outdir, payload, ref_data, units, parts_ordered, shapes, bg_by_part)
+    src_n = dump_source(pkg, outdir)
     perf['total'] = round(time.time() - t0, 3)
     with open(os.path.join(outdir, 'ref', 'perf.json'), 'w') as f:
         json.dump(perf, f, ensure_ascii=False, indent=1)
@@ -734,9 +1238,11 @@ def extract(pptx, outdir, export_all=False):
     print('  shapes %d kept / %d dropped off-canvas / %d bleed / %d clamped'
           % (payload['counts']['shapes_kept'], payload['counts']['shapes_dropped_off_canvas'],
              payload['counts']['shapes_bleed'], payload['counts']['shapes_clamped']))
-    print('  colors %d  fonts %d  images %d  media exported %d/%d  guides %d'
+    print('  colors %d  fonts %d  images %d  media exported %d/%d + %d composites  guides %d'
           % (len(color_freq), len(fonts), len(images),
-             payload['counts']['media_exported'], len(pkg.media), len(guides)))
+             payload['counts']['media_exported'], len(pkg.media),
+             len(composite_media), len(guides)))
+    print('  ref/source/ 原文 %d 个部件（判断不了时可直接翻）' % src_n)
     print('  extract.json %.1f KB  total %.2fs'
           % (os.path.getsize(out_json) / 1024.0, perf['total']))
     return payload
@@ -751,13 +1257,29 @@ def main(argv):
             print('unknown option(s): %s' % ' '.join(sorted(unknown)))
         print(__doc__)
         return 2
+    if not os.path.isfile(args[0]):
+        # 猜附件文件名是高频错误起手式，报错要把「去哪儿看真名」直接说清楚
+        print('找不到 %s' % args[0])
+        print('不要猜附件文件名。先列出真实文件：ls -la .agent/<conversation_id>/attachments/')
+        print('目录里没有 .pptx / .potx 时，说明这次上传没有落成沙箱本地文件——'
+              '如实告诉用户拿不到模板文件，不要退回附件文本摘要或自造配图当风格来源。')
+        return 2
     extract(args[0], args[1], export_all='--export-all-media' in flags)
     if '--no-draft' not in flags:
         import subprocess
         d = os.path.join(os.path.dirname(os.path.abspath(__file__)), 'draft.py')
+        sys.stdout.flush()
         r = subprocess.run([sys.executable, d, args[1]])
         if r.returncode:
-            print('  ⚠ 草案生成失败，可单独重跑 draft.py 看报错')
+            # 普查产物已经齐了，缺的只是草案。重跑整条抽取会同样失败在这一步，
+            # 所以给一个区别于成功的终止哨兵，并指明只需重跑 draft.py。
+            print('EXTRACT_PARTIAL 普查产物齐全，草案生成失败：'
+                  'python3 -B scripts/draft.py %s 单独重跑看报错' % args[1])
+            sys.stdout.flush()
+            return 1
+    # 最后一行是终止哨兵：stdout 被截断时退出码仍可能是 0，两个哨兵都没有就是没跑完。
+    print('EXTRACT_OK %s' % os.path.join(args[1], 'l-out'))
+    sys.stdout.flush()
     return 0