knight-imagetopptx-skill

name	knight-imagetopptx-skill
description	Use when Codex must rebuild an existing slide image, screenshot, or image-only PPTX page into an editable .pptx replica, especially Chinese business report slides with editable text, cards, arrows, complex visuals, and independently movable generated image assets.

Knight Image To PPTX

Scope

Use this only for existing visual slides:

• A PNG/JPG/WebP slide image that must become editable PowerPoint.
• A PPTX whose slides are image-only screenshots or generated full-page images.
• A PDF or multi-page image set where each page must become an editable PowerPoint slide.
• A rendered slide page that needs editable text, containers, arrows, icons, and layout objects.

Do not use this for creating a new deck from scratch, SVG-only conversion, or simple image packaging where the user does not need object-level editing.

Core Rule

Rebuild the slide semantically so the parts the user needs to edit are practical PowerPoint objects.

• Text, cards, panels, dividers, lines, simple arrows, bullets, badges, and tables: create as native PowerPoint objects.
• Icons, pictograms, complex badges, decorative marks, tiny UI glyphs, illustration-like elements, complex pictures, and complex visual objects: must be generated with the image generation model as independent transparent PNG assets, then inserted into the PPTX.
• Flowing ribbon arrows, migration streams, gradient arrow bands, multi-lane flow arrows, or any arrow system that needs soft fades, bundled curves, overlapping streams, or fused arrowheads is a complex visual object. Generate it separately with the image generation model and stitch it into the PPTX as one or a small number of transparent PNG visual assets; do not rebuild it from many native rectangles, triangles, or curve fragments.
• Source-image crops are reference material only. Do not use cropped screenshot fragments as final icon assets unless the user explicitly provides a real logo/brand mark that must remain exact.

Mandatory Execution Contract

When this skill is triggered, the workflow below is binding, not optional guidance. Do not jump directly from screenshot to PPTX, and do not deliver a file unless the required evidence exists.

Before building, track the execution state in memory or local notes. Write rebuild_execution_report.json only once near the end as a compact final summary; do not repeatedly rewrite a verbose phase log. The final summary must cover these required phases:

• input_prepared: source path, slide/page count, slide size, aspect ratio, and output target recorded.
• visual_inventory_done: major text blocks, native objects, connectors, tables, cards, icons, and complex visuals listed with stable IDs.
• asset_classification_done: every non-text visual marked as native_editable or imagegen_asset.
• imagegen_assets_done: every imagegen_asset has an image-generation source, final transparent PNG, manifest entry, and contact sheet or crop QA.
• text_fit_done: every visible PPT text object was checked with ppt_text_fit.py or has a recorded exception; the report may be compact.
• pptx_built: editable PPTX generated with native text/shapes and independent image assets.
• render_qa_done: PPTX rendered to PNG and compared against the reference at full-page level.
• local_crop_qa_done: tight regions such as icon buttons, dense cards, tables, labels, bottom bars, and user-flagged areas cropped and inspected.
• validation_done: asset checker and relevant script/compile checks run, or blockers recorded.

If any phase cannot be completed, stop and report the blocker instead of silently skipping it. If the user asks for speed or a rough pass, still perform the minimum compact execution summary, asset manifest, rendered preview, and validation; mark the result as draft if QA is intentionally incomplete.

Final answers must include the PPTX path and the most important evidence paths, normally rendered preview, asset contact sheet, compact text-fit report, and notable crop QA. Do not claim completion from code generation alone.

Non-Negotiable Image-Generation Gate

Final icon and complex-visual assets must come from the image generation model. Do not hand-draw, script-generate, trace, or approximate final icons with PIL, SVG, canvas, icon fonts, manually authored vector paths, or PowerPoint shape drawings. Those methods are allowed only for native editable primitives such as cards, lines, arrows, tables, separators, simple badges, and text containers.

Before rebuilding, classify every non-text visual region:

• native_editable: simple geometry that should remain editable in PowerPoint, such as panels, rounded rectangles, ordinary single arrows, table cells, divider lines, small numeric badges, and plain UI containers.
• imagegen_asset: icons, pictograms, logos that are not supplied as exact brand files, decorative skylines, illustration fragments, complex badges/seals, screenshots that should become stylized editable-adjacent assets, dense tiny glyph clusters, mascots/people/devices/scenes, complex pictures, flowing ribbon arrows, migration streams, multi-lane gradient arrows, or any visual whose faithful reconstruction would require custom drawing logic.

For every imagegen_asset, call the image generation model or reuse an asset that was already produced by that model for this rebuild. Keep the original generated file if the tool saves one, copy it into the working assets/ folder, then cut/repack/clean it as needed into independent transparent PNGs. Record the generated source path or prompt in the asset manifest.

If the image generation tool is unavailable, blocked, or fails repeatedly, stop and report the blocker. Do not silently replace the required asset with a script-drawn or hand-authored substitute, and do not describe such a substitute as generated.

Workflow

1. Prepare input

   • Create a working folder beside the source, e.g. editable-replica-XX/.
   • If the input is image-only PPTX or PDF, render/export each page/slide to PNG first and treat each rendered page as a reference image.
   • If the input is multiple images, preserve their order and treat each image as one target slide.
   • Record slide size, aspect ratio, source filenames/page numbers, and output path.
   • Start tracking the execution phases required by the Mandatory Execution Contract, but write the final rebuild_execution_report.json once after validation as a compact summary.
   • For multi-page inputs, each page is an independent single-slide rebuild task. Do not build page 2 by copying page 1 and making rough edits unless the visual page is genuinely repeated and the render check confirms it.

2. Inventory the page

   • Build a visual inventory: title/subtitle/body text, cards, panels, containers, arrows, connectors, icons, labels, footers, backgrounds.
   • Assign stable IDs to every non-text visual asset, e.g. process_log_parse, output_excel_sheet, bottom_human_reviewer.
   • Record approximate bounding boxes and target visual size for each asset.
   • Mark each non-text visual as either native_editable or imagegen_asset using the Non-Negotiable Image-Generation Gate above.
   • For every arrow or connector that is not a plain straight line, record its stable ID, tail-to-head direction, path class (straight, elbow, arc, U-turn, hook, loop, or ribbon), stroke/fill role, approximate bbox, and any attached label. Treat the arrow and its attached label as one visual component for later QA.

3. Generate icons and visual assets

   • Use the image generation model for every imagegen_asset. Prompt for isolated flat/vector-style assets with no text, no labels, no numbers, no card frame, no shadow unless visible in the reference.
   • Color fidelity is a first-pass requirement. Before prompting, sample/record every icon's reference colors: foreground stroke/fill, internal detail color, container/host color, and whether the icon is meant to be transparent, monochrome, white-on-color, color-on-white, or multi-color. The first image-generation prompt must state these color roles and approximate hex values per asset or per grid cell. Do not let the model choose a generic palette.

Implementation Patterns

• CJK font XML: after setting run.font.name, also set a:latin, a:ea, and a:cs typeface on the run XML. Use this for every Chinese text run.
• Text-fit preflight: for every dense table cell, card title/body, subtitle, button label, and icon-adjacent label, estimate text width/height before generating the PPTX. Prefer the bundled helper:

python scripts/ppt_text_fit.py --text="升级方向不是少做事，而是更会定义、拆解、验收和复盘。" \
  --box 980x42 --font "Microsoft YaHei" --max-pt 22 --min-pt 12 --max-lines 1

Use the returned recommended_pt and lines to set the first PPT build. For any high-risk title or mixed-language label, also pass --target-pt <reference-size>: the report then returns required_box_px and box_deficit_px, making it explicit whether the correct repair is a wider/taller text box rather than a smaller font. Keep the final text_fit_report.json compact: record called, notfits, exceptions, and representative high-risk long texts with their reference size and box deficit. Do not write every successful short-label fit by default; keep full per-shape details only in temporary debug data when actively diagnosing a failure. The helper uses Windows font files, slide export scale, visible glyph bounding boxes, CJK-aware wrapping, binary search, safety margins, robust argparse handling for leading-minus text, and forced UTF-8 stdout for Chinese/symbol JSON output. If the helper is unavailable, use PIL ImageFont.truetype() with Microsoft YaHei/SimHei/Arial and the same logic; only fall back to rough CJK estimates as a last resort. Do not use raw font ascent+descent as the only line-height estimate; it over-counts invisible YaHei padding and makes labels too small.

• Text argument safety: when calling ppt_text_fit.py from Python or shell, pass text as --text=<value> instead of --text <value>. This prevents values that begin with minus signs, plus signs, dash variants, arrows, parentheses, or symbol-heavy metric prefixes from being misread as command options. If a wrapper constructs subprocess arguments, build f"--text={text}" as one argv item.
• Strict text-fit coverage: do not restrict fitting to a single wrapper such as add_fitted_text(). Treat every text-producing operation as in scope, including add_run() branches, direct shape.text_frame edits, table cell text, manually composed numeric metrics, badge labels, split title/body runs, chart labels, and footer notes. For mixed-size metric lines such as number+unit, English acronym+number+unit, signed value+unit, or value+trend-symbol combinations, fit the full visible phrase against the whole bbox first, then derive number/unit run sizes from that fitted base size or fit the number and unit in explicit sub-boxes. Track coverage internally while building. The final compact text_fit_report.json should include called, notfits, exceptions, and representative key_long_texts; only failed, exceptional, or high-risk long text needs per-object detail.
• Manual run exception discipline: if a tiny decorative label, page number, or intentionally fixed-size badge truly cannot use ppt_text_fit.py, record it under exceptions in the compact report with its bbox and reason, then verify it with a local render crop. Unreported hard-coded text sizes are a defect.
• Reference line-count lock: derive the target max line count from the source image before fitting. One-line source labels must be fitted as one line; two-line source titles must remain two lines. Do not insert manual line breaks that create more lines than the reference unless the source visibly does so.
• PPT point-to-pixel scale: calculate from the actual export setup, not from memory. For 1672 px wide output on a 13.333333 in slide, px_per_pt = (1672 / 13.333333) / 72 ~= 1.742; the helper applies this scale plus a render fudge. If using a different slide size or export width, pass --slide-px and --slide-in.
• Role text hierarchy: keep font sizes flexible and derived from the reference page, not fixed numeric ranges. Preserve the relative hierarchy between title, subtitle, card titles, table headers, table body, tool names, labels, and notes. If text only fits by becoming visibly weaker than peer text in the same role, adjust geometry, margins, columns, or wrapping instead of silently accepting tiny text.

7. Validate before delivery
   • Run the bundled helper:

python scripts/check_rebuild_assets.py --asset-dir path/to/assets

• Open or inspect the rendered PNG before claiming completion.
• Write the compact final rebuild_execution_report.json once, and confirm it has no incomplete required phase unless the final answer explicitly labels the output as a draft and explains the missing evidence.

Lessons From Real Repairs

• Prevent icon clipping by requiring the generated grid itself to keep every icon fully inside its own cell, then cut by verified grid cells and repack content into a larger transparent canvas.
• Native transparent generation is the required asset path. Validate RGBA mode, alpha bbox, transparent corners, and non-transparent subject coverage immediately after generation; preserve valid alpha throughout cutting, repacking, and insertion.
• After cutting icons, center by alpha visual centroid, not just by the alpha bbox. Explorer thumbnails often expose this issue before PPT: asymmetric icons can pass padding checks while still looking visually off-center.
• After centroid-centered repacking, clamp the paste offset so the final alpha bbox still keeps the required transparent edge padding. Tall arrows and trend marks can be visually centered yet still touch the top edge; asset checker failures such as unsafe transparent padding (..., 0, ...) require repacking, not PPT scaling.
• Trust the actual input file dimensions, not the chat preview or apparent screenshot aspect. Open the source with PIL, record size and aspect, and choose the PowerPoint page size from that ratio before placing anything. For a 1536×1024 source, a 12×8 in slide gives a clean 128 px/in mapping and avoids accidental horizontal stretching.
• Grid cutting must stay generic. Use parameterized columns × rows / N×M logic and fail if the provided asset spec count does not match the grid; do not copy a previous slide's 4×2 or 5×4 constants into a new task.
• Generated sheets often contain outer margins even when the prompt asks for a strict grid. Detect the real content centers first, then cut from center-midpoint edges; naive equal slicing from the image origin can erase whole icons or clip edge cells while still producing a plausible contact sheet.
• Color fidelity must be specified during the first image-generation attempt. Assets with different foreground colors, container colors, internal detail colors, or state colors should be treated as distinct targets; do not rely on a generic icon palette when the reference assigns specific colors to specific assets or states. A contact sheet that looks structurally correct but uses the wrong color role is still a failed asset sheet.
• The word "generated" is not enough. A script-drawn PNG is still a hand-authored substitute and violates this skill for icons and complex visuals. Use the image generation model first, then post-process the generated image.
• Asset sheets can leak adjacent-cell fragments into button icons. Treat stray bottom arcs, dots, wedges, or partial marks as a real grid/cutting failure even if the cut asset passes padding checks. Fix the grid prompt, alpha-component cleanup, or recutting logic, then re-render the actual PPT crop.

Deliverables

Return the final .pptx path plus, when produced:

• Rendered PNG preview.
• assets/ folder of generated transparent icon PNGs.
• Asset manifest or visual inventory.

Mention any remaining limitation plainly, especially if a complex icon is a generated approximation rather than a perfect vector recreation.