ppt-cast

name	ppt-cast
description	Create or maintain quality-first character-video PowerPoint decks in which one consistent protagonist performs every content slide while text, data, charts, UI, logos, and sources remain native/editable. Use for 角色出演PPT, 每页视频PPT, mascot/character video decks, Deckformance, or /ppt-cast. Do not use for ordinary static decks or full-page AI videos with burned-in text.

Deckformance (ppt-cast)

Create an editable dynamic PPTX in which the same protagonist performs each content slide's idea. Cover and true section pages may be static; content and closing pages may not.

Non-negotiable contract

• Use v2 for every new job. Preserve v1 readers/builders for existing jobs; never rewrite a v1 job in place.
• Plan content, evidence, typography, composition, video slot, motion, and registered assets before generating media.
• Identity references determine who the character is, not crop, pose, background, scale, or camera distance. A bust/headshot must first produce a validated full-body performance model.
• A dynamic page has exactly one same-protagonist video layer. Never substitute a still, empty slot, unrelated old media, or secondary character when video fails.
• Dynamic slide video must be generated by a real external video-generation model. MotionPlan specifies direction and playback; it never synthesizes video bytes.
• Video owns action, emotion, and metaphor. Native PPT owns readable text, exact data, charts, tables, UI, logos, annotations, sources, and speaker notes.
• Poster/video bytes must already satisfy final aspect, codec, fps, silence, and size before five-frame QA. Any later crop/transcode/compression invalidates downstream evidence.
• External facts and structured values must be source-backed and compiled into the corresponding notes under [Sources].
• Fail closed on unresolved fonts, unreliable text fit, unsupported provider/renderer/player capabilities, stale hashes, or incomplete receipts. Do not hand-write success booleans.
• candidate.pptx means automatic package/render/evaluation gates passed. final.pptx additionally means the exact same bytes passed real PowerPoint playback. Human visual acceptance remains a separate state.

For required dynamic-slide media, fixture/synthetic bytes, import-video, local files, static images, native PowerPoint animation, CSS animation, canvas/programmatic motion, or any other non-model substitute are test/draft material only and must not enter candidate.pptx. This restriction does not change the static-native cover/section allowance or the use of native editable layers for text and evidence.

Route the task

For a new v2 production job, read v2-production.md. It covers the artifact chain, Typography, semantic composition, Hybrid layers, Motion, media receipts, deterministic deck compilation, candidate build, and v1 migration boundary.

Before starting a formal run, integrating provider/render infrastructure, generating host distributions, or attempting candidate/final release, read runtime-and-release.md.

For regression suites, real-generation evaluation, gallery publication, or v1/v2 blind review, read benchmarks-and-gallery.md. Benchmark definitions and old jobs are not proof that current acceptance gates passed.

For identity/body construction, additionally read character-model.md. For generation/frame/slot inspection details, read qa.md. Load the felt-specific human guide only for felt-yarn work: felt-yarn.md.

Focused felt editorial master

When the user asks for the reference-led premium felt card composition, choose felt_editorial_split_master instead of adding more Composition families. Read felt-master-template-design-principles.md and load .grok/skills/ppt-cast/scripts/felt_editorial_split_master.js.

The master has one 2.08:1 centered card and two strict mirrors only: media-left and media-right. Use the selected 57/43 media/panel ratio unless the user is explicitly reviewing the three ratio candidates. Keep the native headline, body, and closing line in the charcoal panel; generate the media at a near-6:5 aspect and keep its subject inside the central safe area. “Clean” does not mean backgroundless: final media needs a story-specific felt miniature environment with visible foreground, midground, and background depth, not a generic studio wall or empty tabletop.

Supported page inputs are intentionally narrow: mediaSide, eyebrowOrIcon, pageNumber, headline, body, closingLine, videoPoster, videoSlot, and optional characterSet. characterSet.referenceImages accepts one or two job-relative user uploads; there is no default mascot. Preserve the uploaded identity while recomposing the felt miniature scene, and never treat sample characters as template identity.

Before rendering, copy the packaged .grok/skills/ppt-cast/assets/felt-edge-negative-mask.png to <job>/assets/felt-edge-negative-mask.png. Apply it as the card-level negative alpha overlay so the warm canvas color remains adaptive around both panel and media. Build the charcoal panel from model.panelShape (or panelShapeConfigForFeltMaster) rather than reconstructing its stroke: it uses a true no-fill outline (fill: "none", width: 0). Never give the panel a zero-width solid charcoal line; PowerPoint exposes that as a one-pixel hairline outside the mask. As a final package gate, inspect every felt-panel-* in the exported PPTX and require <a:noFill/> with no solid line fill. Do not replace the mask with a sawtooth shape, generic scallop, or two independently rounded rectangles.

v2 default workflow

1. Run doctor, initialize the v2 job, and author approved content/visual contracts. Candidate does not require PowerPoint; final does.
2. Compile design-plan.json before media generation. Use preview_design_v2.js when an early native-layer/typography preview is useful; its video slots are placeholders and it is never releasable.
3. Route the host to a concrete external video-generation adapter, invoke the real model, and produce exact final MP4 bytes plus a hash-bound generate-video provider receipt. Then produce media-budget, five-frame, slot, and evaluation receipts. If the provider, final MP4, or receipt is missing, stop before media-ready; never fall back to import or synthetic motion.
4. Compile deterministic deck.json, build only candidate.staging.pptx, then run the independent v2 package validator.
5. True-render the exact staging bytes, inspect every slide, and bind the renderer implementation/hash and page outputs.
6. Run release preflight. Treat ready, degraded, and blocked literally, then let jobctl_v2 publish candidate.pptx only after all automatic gates pass.
7. On a PowerPoint-capable Mac, play and capture the exact candidate bytes. The builder/package gate proves timing XML was authored; only this real-player observation proves autoplay. Only the external exact-byte receipt may authorize jobctl_v2 to publish final.pptx.

Host adapters share one contract: Grok maps its real external video-generation tool/API to ProviderAdapter.generateVideo; Qwen maps a configured MCP or long-running generation service to that operation; a generic host registers an API/MCP/CLI-backed provider adapter. Merely declaring a host/provider name or supplying existing bytes is not a successful adapter invocation.

Core commands:

node <SKILL_DIR>/scripts/doctor.js --release candidate --json
node <SKILL_DIR>/scripts/jobctl_v2.js init jobs/<slug> --job-id <slug>
node <SKILL_DIR>/scripts/compile_design.js jobs/<slug>
node <SKILL_DIR>/scripts/compile_deck_v2.js jobs/<slug>
node <SKILL_DIR>/scripts/build_deck_v2.js \
  jobs/<slug> jobs/<slug>/build/candidate.staging.pptx \
  --release candidate --report jobs/<slug>/qa/build-report.json
node <SKILL_DIR>/scripts/validate_pptx_v2.js \
  jobs/<slug> build/candidate.staging.pptx \
  --release candidate --report qa/package-qa.json

Then follow the true-render and jobctl_v2 commands in v2-production.md. Do not skip directly from a successful build to a published candidate.

v1 compatibility only

For an existing v1 job, use the legacy chain documented in contracts.md: jobctl.js, compile_deck.js, build_deck.js, validate_pptx.js, and validate_job.js. Legacy jobs and fixtures remain useful regressions but are not v2 gallery successes.

migrate_v1.js creates a blocked v2 draft requiring explicit redesign. Migration alone never authorizes design compilation, candidate release, or gallery eligibility.

Claim discipline

Keep these states separate in reports:

• automated tests passed;
• real external video-generation model invoked with bound provider/model/request/output evidence;
• trusted true render passed;
• candidate released for exact bytes;
• PowerPoint playback passed for exact bytes;
• human visual/blind review accepted.

If no concrete external video provider is callable, stop at the design/preview stage and say so; a dynamic-slide candidate is not permitted. If this Mac has no PowerPoint, stop at candidate and say so. Never describe fixture/synthetic/import media as model-generated, package timing as real-player autoplay, or unexecuted fixed/real benchmarks, gallery generation, five-reviewer blind testing, or final-macOS playback as completed.