# Native page authoring

Read the selected external template's specification, style, theme and relevant layout first. The bundled compiler accepts the native SVG workspace convention: `templates/roster.json` maps every manifest layout ID to one SVG; each source SVG declares `data-pptx-master`, `data-pptx-layout` and friendly names. Layout and master objects use their declared `data-pptx-layer`. Placeholder groups carry `data-pptx-placeholder`, a stable `data-pptx-idx`, and `data-pptx-bounds`.

Create or continue the [mandatory buildable Skill project](project-workspace.md) before producing the page. Keep its selected template, page SVGs, notes, assets and real builder together; even a one-slide request must produce the PPTX through that project's build entrypoint, not a hand-assembled file or standalone export with no retained project.

Start the current page from its selected layout source. Retain inheritance metadata, inherited objects and placeholder indices. Fill the declared placeholder carrier; put independent content objects in the intended slide layer. Do not paint opaque slide-local copies over the master logo or layout watermarks. When a template supplies a custom composition generator, inspect it and use its declared content interface rather than approximating its source geometry.

Start with the template's typography, grid, fixed content region and spacing. For an approved mockup, use [controlled content-area adjustments](visual-design.md#controlled-adjustments-for-approved-mockups) to font sizes, bounds, spacing and necessary fit/alignment, with declared shared project values in integer/fixed-step units. Preserve fixed UI, locked structures, accepted relative positions, visualization forms, icons and text styling under [mockup fidelity](visual-design.md#approved-mockup-fidelity). Resolve remaining overflow through reflow or an authorized layout/content change; necessary quality repair does not permit silently dropping or redesigning elements. Do not trace raster artifacts or introduce unexplained multi-digit offsets. Keep text as text, simple panels and connectors as geometry, and exact image exceptions as independent assets. For an element that native components/SVG cannot conveniently reproduce faithfully, use [ImageGen](visual-design.md#elements-that-need-imagegen) and disclose its independent picture type. Tables, charts and formulas must retain any explicitly required native object type; a collection of lines/text or a formula picture does not automatically qualify.

Apply [text and container rules](text-and-containers.md) before authoring: prefer one native frame per paragraph, use a unified logical block for any necessary fragments, distinguish text functions by size/weight/color and instantiate repeated containers through a shared renderer. Inspect actual native paragraph structure after export; positional SVG spans can otherwise be split by the compiler.

Before emitting paragraph rows, check punctuation at both line edges and prohibit every singleton row, including one character surrounded by punctuation. Reflow the complete paragraph with measured text widths; keep derived rows inside the same native frame. Repeat the check against actual rendered lines if PowerPoint performs further wrapping.

Keep separate paragraphs separated by the active shared recipe's fixed paragraph gap, retaining their normal internal line height. Use template defaults or the declared project adjustment above. Spacing values and applicable relationships belong to the shared recipe; content callers cannot adjust them. Check exact fixed padding/gaps and actual glyph/edge clearance at normal scale. Use [text-block/spacing helpers](text-and-containers.md#spacing-and-paragraph-separation) for supported content. Explicit math markers use the [Office Math wrapper](mathematics.md), not the upstream table/chart marker kinds.

## Current-page project build

The installer provides Python 3.12+ and [runtime requirements](../runtime/requirements.txt). Metadata-only selection and project commands use Python 3.10+ without third-party packages.

Follow [project initialization and builder preparation](project-workspace.md#初始化与作者工作流), add the current authorized pages and their inputs, then build through the project. Source edits and quality repairs must be included in the locks before the next build:

```sh
python3 /path/to/report/tools/ppt_project.py lock --project /path/to/report
python3 /path/to/report/tools/ppt_project.py check --project /path/to/report
python3 /path/to/report/tools/ppt_project.py build --project /path/to/report
```

The project builder calls `native_export.py` as its low-level compiler, or imports its `export` function. That interface retains `--manifest`, `--theme`, repeatable `--source`, `--output` and optional `--notes`; it is not a projectless production shortcut. It may assemble only explicitly authorized, already authored pages in order. Source filename stems must be unique. `--notes` maps source stems to complete speaker-notes strings; unknown stems are rejected.

The exporter consumes released v2 manifests and retains all native layout definitions, even for a single visible page. It requires a complete layout roster, unique layout names, declared `page_title`/`body` family roles and sizes, and the twelve PowerPoint theme color indices. Optional `style.language` supplies the presentation's BCP-47 language tag. Without it, the exporter preserves the compiler's legacy language metadata behavior; record the deck language in the project when it matters.

Page SVG viewBox and layout ID must match the selected template. Source assets are only relative local PNG/JPEG references or embedded PNG/JPEG data. Fragment references are supported; external images, active SVG elements, document entities and external CSS URLs are refused. Default author resource boundary is each SVG's directory; template-internal sources use the template package root. For portable project pages that intentionally reference `../../assets/...`, pass `--source-root /path/to/project`. Boundaries and symlink checks apply before compilation. Other visual formats should be prepared as native geometry or explicit supported bitmap assets.

The exporter embeds images in temporary source copies, preserving canonical source bytes. It runs the bundled attribution guard, serial compiler and declared-font preservation context, then applies the external palette/theme fonts without overwriting resolved run weights, and verifies slide/Layout/Master links, placeholders and supplied notes. Authors/renderers must apply their selected role's actual size, weight and color to the source; family identity alone does not select a text function. Existing output is protected, including a concurrent writer appearing during compilation. A failed build does not replace old output.

Before marking each page complete, perform the [full-page hierarchy check](visual-design.md#full-page-hierarchy-check) on its current render, covering font sizes/families/weights, spacing and visual content groups across the entire page. Compare with any approved sample, repair the source and rebuild/reinspect as needed; a successful compile is not this visual check.

After any approved-mockup typography or geometry adjustment, also check [container and page overflow](visual-design.md#controlled-adjustments-for-approved-mockups): actual text/formula extents and paragraph height must fit their frames/containers, and complete visible groups must fit the usable page/canvas without unintended clipping, occlusion or collisions with fixed UI. Check the actual rebuilt render, repair source and repeat for affected shared instances.

## Template authors and review prototypes

Keep proposed styles and mockups outside the final template workspace until the user's design review allows formal construction. A proposal manifest cannot be consumed as a released production template. After approval, author the common style, independent themes, roster and native SVG layout definitions together; compare each theme against the same geometry and slot contract.

The bundled runtime also carries the upstream preview compiler at `runtime/ppt-master/scripts/template_preview_pptx.py` for author review workspaces. It is source tooling, not a second Skill. Read its command help for a new workspace. Its platform font mapping is general-purpose: a template review wrapper should import the compiler and use `scripts/finalize_theme.py`'s `preserve_declared_font_families(style)` context around the serial compile, then `finalize(...)`. This preserves the declared family before information can be lost to platform fallback. Do not globally replace a fallback font in finished XML: the author may have intentionally used that same font.

For native tables/charts and equations, read [specialized objects](native-objects.md) and its examples. For placeholder metadata, inspect the corresponding bundled compiler module and local CLI help. Do not claim specialized objects from a screenshot or from a successful ZIP export alone. Finish with [render and application checks](powerpoint-checks.md).

## Actual slide numbers

A template can declare one `slide-number` text-carrier placeholder in each applicable Layout. Its fixed geometry, typography and palette belong to that template. The native wrapper copies the Layout carrier into older page sources when needed, seeds its initial cache from the actual export order, and requires a Slide-local `a:fld type="slidenum"` rather than a literal text number. It also preserves the native `sldNum` placeholder binding and gives page-number fields distinct IDs. Templates without this placeholder retain their existing behavior.

Source previews may show a placeholder such as ‹#› because they have no deck position. Never replace it with a chapter number or a hand-maintained page counter. The exported field cache is an initial display value; PowerPoint controls its later value after insertion, deletion or rearrangement. Verify those operations in an independent PowerPoint copy before claiming application update behavior. The navigation header's upper-line text keeps its established report meaning and remains separate.