Release PPT workflow 0.7.3 with fixed spacing, paragraphs and native math

references/charts.md

@@ -30,7 +30,9 @@ JSON顶层字段：`schema_version: 1`，`data_kind`（`synthetic-demo`／`obser
 
 ## 样式来源
 
-`style`和`theme`分别使用`template_ref.py export-style`的`style`、`theme_data`。字体从`typography.families.body`取得，字号默认取`caption`角色，缺少时取`label`；按`canvas.pt_to_px`换算。组件没有组织、字体名或十六进制配色的固定默认值。
+`style`和`theme`分别使用`template_ref.py export-style`的`style`、`theme_data`。每个文字角色通过`family_role`解析自己的字体、字号、字重和行高，按`canvas.pt_to_px`换算；不会把所有角色强制映射到body字体。图表标题使用`label`角色与`accent2`；没有`label`的旧样式沿用图表文字角色，通过颜色区分。单位、轴和图例使用显式`components.charts.text_role`（默认`caption`，缺少时为`label`）及`text_palette_index`；来源沿用标注角色的字体和字号，但颜色为`dk2`。组件没有组织、字体名或十六进制配色的固定默认值。
+
+原生Chart轴当前只支持Regular（400），对需要其他轴字重的角色明确报错，不只改变SVG预览。pie／doughnut没有轴，独立标题、图例和来源可按角色保留加粗。普通原生文字／Table使用常规与加粗的字重语义；中间字重仍需目标字体与应用验证，不能仅据SVG的数值声明推断精确字重。
 
 template可选择声明`style.components.charts`：
 

references/components.md

@@ -12,7 +12,7 @@
 
 Each JSON uses `schema_version: 1` and `kind`. Examples are marked `data_kind: synthetic-demo`; preserve this declaration and source metadata when demonstrating. Real reports retain observations, definitions, missing-value policy and sources under [production rules](production-rules.md). Metadata remains in SVG; save original JSON with the page. The table payload is canonical native metadata, with original data in `data-component-source`; other groups carry original JSON in metadata. Native PPTX does not retain arbitrary SVG metadata, so retain project sources separately.
 
-The table uses `style.components.table`, including theme-indexed header colors and padding. Text uses `typography.roles.label`, `caption` and `number`, their declared font families and `canvas.pt_to_px`. Other component colors use `dk1`, `dk2`, `accent1`, `line` and `lt1` from the palette. Internal spacing uses fixed 8px modules; derived equal columns/centers do not introduce new page alignment guides. Width checks are conservative estimates, not a font renderer. The tool rejects excess capacity instead of shrinking text. Rephrase, enlarge a slot, change layout or split content; inspect actual application output.
+The table uses `style.components.table`, including theme-indexed header colors and padding. Text uses `typography.roles.label`, `caption` and `number`, each role's declared family, size, weight and line height, and `canvas.pt_to_px`. A table's explicit `text_role` takes precedence. Number and unit runs resolve their roles independently; caption roles do not inherit the label's family or weight. SVG and native Table payloads carry the same role choices. Native regular/bold semantics do not by themselves verify intermediate font weights in the destination application. Other component colors use `dk1`, `dk2`, `accent1`, `line` and `lt1` from the palette. Internal spacing uses fixed 8px modules; derived equal columns/centers do not introduce new page alignment guides. Width checks are conservative estimates, not a font renderer. The tool rejects excess capacity instead of shrinking text. Rephrase, enlarge a slot, change layout or split content; inspect actual application output.
 
 Apply the required [text and container rules](text-and-containers.md). Callers provide data, declared style/variant and whole-component bounds; do not move generated child text/icons or add per-instance internal offsets. Custom containers need a shared renderer too. Distinct functions such as heading/body must differ perceptibly in size, weight and/or palette color, not just family. The `detail`/`caption` name does not authorize essential conditions, conclusions or limitations to become small muted notes. Choose a suitable main-text component or extend the shared renderer when the existing field/role cannot carry the content appropriately.
 

references/mathematics.md

@@ -0,0 +1,54 @@
+# Mathematical content
+
+Use the math family declared by the selected template or an explicit project-local math-style input. Keep that declaration with the project; do not silently substitute the prose font or a different math family. An OpenType math font supplies mathematical glyphs and layout tables; its name alone neither installs it nor proves application rendering. Keep ordinary Chinese/English explanations in their prose role. Variables, operators, upright function names, units and grouping must retain the author's meaning.
+
+## Supported native route
+
+`scripts/math_component.py` creates structured expressions and the maintained `native_export.py` wrapper emits Office Math. The preserved upstream compiler remains unchanged. The wrapper uses its own `data-native-math="1"` group, not the upstream `data-pptx-replace-with` table/chart kinds.
+
+Supported expression nodes:
+
+| Input | Native structure |
+|---|---|
+| A nonempty string, or `text` with explicit plain/italic/bold/bold-italic style | `m:r` runs |
+| `row` with ordered `items` | Ordered math expressions |
+| `fraction` with `numerator` and `denominator` | `m:f` |
+| `script` with `base` and `sub` and/or `sup` | `m:sSub`, `m:sSup`, `m:sSubSup` |
+| `radical` with `body` and optional `degree` | `m:rad` |
+| `delimiter` with `body`, `open`, `close` | `m:d` |
+| `nary` with explicit operator, `body` and optional `lower`/`upper` | `m:nary` |
+| Rectangular `matrix` with `rows` | `m:m` |
+
+The initial operator set is sum, product, integral, union and intersection. Unknown node types/fields, malformed matrices, empty expressions, unsupported transforms and excessive nesting are rejected. This is an explicit expression interface, **not a general LaTeX/MathML parser**. Do not strip unknown commands or flatten unsupported expressions to make a conversion appear successful.
+
+Use `render_math(data, style, theme, bounds, component_id, math_style=None)`:
+
+```python
+data = {
+    "schema_version": 1,
+    "display": "block",
+    "expression": {
+        "type": "fraction", "numerator": "a+b", "denominator": "c"
+    },
+}
+marker = render_math(data, style, theme, bounds, "equation-1", math_style)
+page.append(marker)
+```
+
+`math_style` is an explicit external dictionary with `font_family`, a declared `text_role` and a theme `palette_index`. It can extend a project whose template does not yet have math roles. Without it, the template must declare `typography.families.math` and `math_display`/`math_inline` roles. The selected role supplies the actual point size; no arbitrary font-size field is accepted in component data. Keep the style declaration and generator in build inputs, and declare the math font in the destination environment. A project-local declaration does not rewrite a frozen template or certify a new template release.
+
+`display: "block"` creates `a14:m > m:oMathPara > m:oMath`. `display: "inline"` creates `a14:m > m:oMath` in a standalone native equation frame; this first API does not yet mix prose and equations inside one flowing text frame. Use the ordinary logical paragraph policy for surrounding explanations and do not claim inline paragraph reflow from separately positioned objects.
+
+The SVG contains complete JSON math metadata and a derived **linear text compatibility view**. Complex equations are not visually typeset by that SVG fallback. `native_export.py` validates it, compiles a temporary unique token, then replaces that token with native math at the declared bounds. No temporary token remains in the PPTX. Equations cannot be inside transformed source groups; regenerate their bounds instead. Math markers currently belong to authored pages, not Master/Layout definitions.
+
+The resulting `mc:AlternateContent` has an Office Math choice and an ordinary linear-text fallback for applications without math support. The fallback preserves expression meaning but is not an editable equation or a faithful complex-equation preview. Inspect the supported choice in the target application. No online equation service, additional installed Skill, font download or global installation is invoked.
+
+## Verification
+
+- Check complete input expressions against OMML: correct fraction operands, script attachment, radical degree, delimiter grouping, limits and matrix dimensions. Ordinary Unicode text alone is not proof of an equation.
+- Check the declared family, actual destination font identity and OpenType MATH table. Verify glyph coverage and actual use in the application/export; do not silently replace a missing math font. Fonts are referenced, not distributed or embedded by this wrapper.
+- Inspect mathematical runs and control properties for the selected family, size and color. Confirm Office Math choice nodes are present, no WordprocessingML-only properties or temporary tokens remain, and Master/Layout/notes are preserved.
+- Render the current native file in a math-capable application. Check symbols, fraction bars, radicals, scripts, operators/limits, equation bounds and clearance from neighboring content. An SVG compatibility view or prior unrelated render cannot substitute.
+- Actual equation editing is a separate test: select and change a representative expression in a disposable copy, save, then confirm the resulting equation structure/content. Native XML establishes structure only.
+
+Technical basis: Microsoft's [DrawingML math extension](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-odrawxml/853b19c7-68a9-4f9a-a2ae-5e6cb0d02e62) and [native math example](https://learn.microsoft.com/en-us/openspecs/office_standards/ms-odrawxml/38b13e1f-1102-4bb7-819a-dd5d9abdb176). Font information: the [STIX project](https://www.stixfonts.org/) and its [official source](https://github.com/stipub/stixfonts).

references/native-authoring.md

@@ -8,6 +8,10 @@ Use the template's discrete typography, grid, fixed content region and spacing.
 
 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 template's fixed paragraph gap, retaining their normal internal line height. 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 export
 
 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.
@@ -35,4 +39,4 @@ Keep proposed styles and mockups outside the final template workspace until the
 
 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 formula limitations, read [specialized objects](native-objects.md) and its bundled minimal SVG 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).
+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).

references/native-objects.md

@@ -26,8 +26,8 @@ Implementation entry points:
 - [chart data normalization](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/chart_data.py) and [chart style](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/chart_style.py).
 - [fallback freshness](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/fallback_hash.py) and [validation/conversion](../runtime/ppt-master/scripts/svg_to_pptx/native_objects/__init__.py).
 
-## Formula boundary
+## Native mathematics and formula boundary
 
-This maintained native SVG route has no authoring interface that creates Office Math equations: its native replacement kinds are table and chart. Simple mathematical Unicode may remain editable ordinary text, but that is not an editable equation object. Raster formulas and vector outlines must be disclosed as pictures/paths. The bundled optional LaTeX rendering utility produces PNG and can use external services; it is not a mandatory self-contained compiler capability. Do not invoke a network provider implicitly.
+The preserved upstream snapshot's replacement kinds remain table and chart. The maintained wrapper adds a separate structured [Office Math authoring interface](mathematics.md) in `math_component.py`, with explicit font/style inputs. It supports common expression trees without changing upstream files or requiring another installed Skill. The source SVG contains a linear compatibility view; native equation rendering is checked in the target application.
 
-If truly editable equations are required, agree an additional host or project-local authoring route and verify its output before promising that result. Input OMML extraction does not establish native equation output support.
+Simple mathematical Unicode may remain editable ordinary text, but that is not an editable equation object. Raster formulas and vector outlines remain picture/path exceptions. Unsupported expressions require a separately declared compatible route; do not silently flatten them. The bundled optional LaTeX utility produces PNG and can use external services; it is not the maintained native equation route and must not be invoked as an implicit fallback. Input OMML extraction alone does not establish equation output or application editing support.

references/page-library.md

@@ -12,6 +12,8 @@ A template may declare `page_library: "page-library/catalog.json"`. This optiona
 
 The tool checks file SHA-256 and SVG href closure. It does not execute entry code. The native compiler still performs its own source/resource checks. A method may refer to a template-local generator; read it and invoke it only within the authorized project and host scope.
 
+`eligible: true` means that the selected design reference has valid version/theme/file bindings. It does not prove a reusable content interface or compliance with the current [text and container rules](text-and-containers.md). If a historical example contains repeated materialized SVG groups but no shared generator, first supply one shared recipe and complete content inputs in the report project. Generate every repeated instance through it; do not turn a reference's per-line coordinates into author-maintained content. Retain the historical preview as a visual reference and validate the regenerated page separately.
+
 ## Catalog contract
 
 The catalog has `schema_version: 1`, matching `template_id`, and `entries`. Each entry contains:

references/powerpoint-checks.md

@@ -6,7 +6,9 @@ Open the current generated file, verify the visible filename and page thumbnails
 
 For rendered evidence, export this file to PDF through PowerPoint's own export dialog using the intended quality setting and a task-owned destination. Check the export exists and belongs to the current file, render its pages and inspect the images. Compare page geometry, text wrapping, typography, images, transparent edges, alignment and separators. Confirm actual PDF font identities when font rendering is disputed; a declared PowerPoint face alone does not prove which font the application rendered.
 
-Use the four-part [text/container review](text-and-containers.md#review-before-delivery): paragraph frame or justified logical-block fallback, no substantive statements in small muted notes, visible size/weight/color hierarchy within containers, and one shared internal layout implementation per type/variant. Review content/source and native objects as well as the render. A screenshot cannot prove a shared renderer or unified text source; grouping cannot prove native paragraph flow. Test fragment reflow in the application only when that editing behavior is part of the requested evidence.
+Use the [text/container review](text-and-containers.md#review-before-delivery): paragraph frame or justified logical-block fallback, no substantive statements in small muted notes, visible size/weight/color hierarchy within containers, one shared internal layout implementation per type/variant, compliant punctuation/singleton handling on every paragraph line, exact template-owned spacing and visible fixed paragraph gaps. Reject caller spacing overrides. Check actual glyphs/edges and visual rows, not only boxes, authored breaks or XML paragraphs. Review content/source and native objects as well as the render. A screenshot cannot prove a shared renderer or unified text source; grouping cannot prove native paragraph flow. Test fragment reflow in the application only when that editing behavior is part of the requested evidence.
+
+For equations, inspect `mc:Choice/a14:m` and OMML structures separately from compatibility fallback text. Verify the declared math family on runs and operator/control properties, missing glyphs, fraction/radical/script/limit placement and clearance from adjacent prose. Actual equation editing requires selecting and changing the equation in a disposable copy; XML or a correctly shaped picture cannot establish that evidence. See [math checks](mathematics.md#verification).
 
 Opening and exporting are distinct from actual editing. When editing evidence is requested, use a disposable task-owned copy: select a representative text/shape/placeholder, change it through the UI, save or export, and verify the resulting independent object/content change. Check an appropriate inherited object separately if template behavior is in scope. Do not alter the authoritative source project or a user's finished original merely to demonstrate editing.
 

references/production-rules.md

@@ -1,6 +1,6 @@
 # Production rules
 
-These rules apply across templates and authoring routes. **Required** rules protect content, provenance, implementation claims, rebuildable inputs and the explicit text/container constraints below. **Recommended** methods can change for a content reason; record the reason and relevant validation. Template parameters remain external. Follow explicit user instructions and settled authorization; these rules add no approval gate. C16–C19 are requirements, including where C04–C06 offer broader design recommendations.
+These rules apply across templates and authoring routes. **Required** rules protect content, provenance, implementation claims, rebuildable inputs and the explicit text/container constraints below. **Recommended** methods can change for a content reason; record the reason and relevant validation. Template parameters remain external. Follow explicit user instructions and settled authorization; these rules add no approval gate. C16–C23 are requirements, including where C04–C06 offer broader design recommendations.
 
 ## Understand and compose
 
@@ -35,5 +35,9 @@ These rules apply across templates and authoring routes. **Required** rules prot
 - **C17 · Required:** small muted notes may supply nonessential background, sources or definitions. They must not carry substantive explanations of a chart/visualization, key process conditions or timing, conclusions, or qualifications/disclaimers that affect interpretation. Put those statements in the main information hierarchy; do not hide them in notes or metadata instead. Classify by meaning, not by a field named `detail`, `caption` or `source`.
 - **C18 · Required:** different text functions inside one container, such as subheading and body, must have a perceptible distinction in declared size, weight and/or palette color. A font-family change alone is insufficient. Bind functions to named text roles and apply the same distinction to all instances.
 - **C19 · Required:** every instance of a container type/variant uses the same shared layout implementation for padding, slots, text roles, wrapping, icon placement and alignment. Authors provide content and whole-container placement/bounds; the implementation computes internal geometry. Do not hand-position/nudge text or icons per instance. Resolve capacity through the shared layout's content-driven rules, a meaningful shared variant, rewriting or page/layout changes, never a one-off override. See [implementation and review](text-and-containers.md).
+- **C20 · Required:** paragraph lines obey punctuation rules for line starts and ends. Do not leave a line containing only one substantive character, whether alone, followed by punctuation, or surrounded by punctuation; this applies to every line, including the final line. Keep closing punctuation with preceding content and opening punctuation with following content; preserve unbreakable marks and words. Reflow the complete logical paragraph under its shared layout, then check the actual rendered lines. Do not fix this by deleting/changing content, splitting independent text boxes, or introducing undeclared font sizes, character spacing or per-line offsets. See [paragraph line breaking](text-and-containers.md#paragraph-line-breaking-rules).
+- **C21 · Required:** spacing is fixed by the template and shared component recipe for each relationship: text-to-container padding, heading-to-body distance, adjacent groups/columns and clearance around connectors, rules and formulas. Content callers cannot supply numeric gaps, thresholds, per-instance spacing overrides or invent variants. Check the declared fixed values, including unintended excess spacing, as well as collisions and actual glyph/edge clearance. Preserve intentional decorative contacts under their own template rules. Capacity changes must reflow content or change the whole supported layout, not loosen/tighten its spacing. See [fixed spacing](spacing.md).
+- **C22 · Required:** distinguish separate semantic paragraphs visually with the template's fixed paragraph spacing in addition to normal line spacing. Preserve paragraph boundaries in complete source content. The shared implementation owns this value; content callers cannot adjust it. Use native before/after paragraph spacing where the text-frame route supports it, or consistently positioned paragraph frames. Do not add empty paragraphs, repeated line breaks or per-instance offsets to simulate spacing. Reflowing a paragraph must preserve the fixed separation from the next paragraph.
+- **C23 · Required:** mathematical content uses an explicitly declared mathematical font and preserves symbols, operators, scripts, fractions and grouping. Keep ordinary prose in its own text role. Use native Office Math when native equations are required; ordinary Unicode text, linear compatibility text and formula images are different object types. Verify the declared math font and the actual equation structure/rendering; do not silently substitute the prose font or claim equation editability from its appearance. See [mathematics](mathematics.md).
 
-Technical helpers enforce supported inputs, path safety, object consistency and capacity. They do not infer paragraph identity, explanation importance or semantic text roles, and do not automatically enforce all four text/container rules. Inspect source and current native/rendered output; export success alone is insufficient.
+Technical helpers enforce supported inputs, path safety, object consistency and capacity. They do not infer paragraph identity, explanation importance or semantic text roles, and do not automatically enforce every text/container rule across arbitrary source files. The paragraph helper checks the lines supplied to it and reflows supported plain text; it does not intercept arbitrary SVG or PowerPoint reflow. Inspect source and current native/rendered output; export success alone is insufficient.

references/runtime-and-provenance.md

@@ -8,11 +8,13 @@ The compiler is the MIT-licensed `ppt-master` 4.6.0 snapshot from [hugohe3/ppt-m
 
 The preserved snapshot also contains optional upstream utilities and their documentation. Those legacy utility paths, remote services and optional executables are not this Skill's maintained authoring route or an installation requirement. Use the local native wrapper and host image/UI tools described here; do not invoke an optional utility while assuming its separate service configuration exists.
 
+The maintained wrapper's [math component](mathematics.md) builds native DrawingML Office Math from explicit expression trees using the existing `lxml` dependency. It does not modify the preserved compiler or add a network provider/TeX executable. Math fonts come from the template or a declared project-local math style; destination installation, glyph/MATH-table identity, current rendering and editing remain separate checks.
+
 Page/mockup planning and strict input-asset handling draw on the workflow concepts of [codex-ppt](https://github.com/ningzimu/codex-ppt-skill); object inventory, background/material separation and object-type verification draw on the source-reconstruction workflow available in the development environment. The guidance here is independently written and self-contained. No external workflow script, OCR service, mandatory CLI, review state or installation path is required. Complex automatic asset separation and OCR are not represented as bundled capabilities: use the host visual tools and review the result.
 
 The generic wrapper consumes declared palette/font/size data. `preserve_declared_font_families(style)` temporarily protects only those families from the compiler's platform replacement map during a serial compile, restoring process memory on success or failure. It preserves source identity before conversion; it does not replace arbitrary finished-document occurrences of a fallback font. Declared font names do not install, embed or license a font. Verify family, style, version/hash, source, license and actual rendering on the destination device.
 
-For a portable author project, [prepare_native_project.py](../scripts/prepare_native_project.py) copies the required runtime and wrappers into `vendor/native-workflow/`, supplies `tools/native_builder.py`, and records every compiler source as a build input. It accepts an initialized project with an untouched author lock, no builder and an empty dependency/font/tool declaration. It refuses existing destinations and custom environments/builders. It deliberately leaves the old author lock unchanged so the new source must be reviewed and explicitly locked.
+For a portable author project, [prepare_native_project.py](../scripts/prepare_native_project.py) copies the required runtime, wrappers, typography/paragraph/spacing and math modules into `vendor/native-workflow/`, supplies `tools/native_builder.py`, and records them as build inputs. It accepts an initialized project with an untouched author lock, no builder and an empty dependency/font/tool declaration. It refuses existing destinations and custom environments/builders. It deliberately leaves the old author lock unchanged so the new source must be reviewed and explicitly locked. If a project-local math style adds a font beyond the template families, add that font declaration to the project environment before locking.
 
 The prepared builder reads finalized page SVGs and Markdown speaker notes in project order. It checks the layout IDs and local asset boundaries, then compiles using the vendored template and compiler. `content.json` and declared `data` remain author inputs; this generic builder does not invent a binding schema or automatically regenerate SVG text from those files. If the deck needs data-driven generation, supply a reviewed project-local preprocessing/builder step and declare its inputs before locking.
 

references/spacing.md

@@ -0,0 +1,25 @@
+# Fixed spacing
+
+Spacing belongs to the selected template and shared component recipe. Content callers provide content and whole-container bounds/placement; they do not choose gap values, padding, checking thresholds or one-off variants. If content does not fit, reflow it or choose another supported whole layout/capacity policy. Do not tighten or loosen spacing to fit an instance.
+
+The external style declares `spacing.policy: "fixed"`, `caller_overrides: false` and named `roles`. Each role has a `kind` (`gap` or `padding`) and a `path` array pointing to its authoritative numeric value in the same style. Values stay external; the generic Skill does not prescribe a template's palette, geometry or organization. A role can point to an existing component field, so values are not duplicated. Padding may be a scalar, `[vertical,horizontal]` or `[top,right,bottom,left]`.
+
+The template owner fixes role names and values; the recipe fixes which roles apply to each relationship. Consumers cannot invent new spacing variants or edit a locked style to evade the policy. A shared owner change is a versioned template/recipe change and triggers affected validation. An older template without the `spacing` section can use supported fixed bindings to its existing fields; absent fields are reported, never filled with guessed numeric defaults.
+
+`resolve_spacing(style, role)` returns the declared scalar or normalized four-sided padding. `check_spacing(boxes, checks, *, style)` accepts only roles:
+
+```python
+checks = [
+    {"id": "body-gap", "kind": "gap", "a": "heading", "b": "body",
+     "axis": "y", "role": "heading_body"},
+    {"id": "padding", "kind": "padding", "outer": "frame", "inner": "usable",
+     "role": "text_padding"},
+]
+issues = check_spacing(boxes, checks, style=style)
+```
+
+The checker rejects caller-supplied `minimum`, `expected` or override numbers. Both too-small and too-large distances violate a fixed relationship. A padding relationship compares the full usable inner rectangle against its outer frame; it does not require text to occupy every pixel or fill the bottom of a container. Line-height slots and content height remain derived from complete text.
+
+`text_block.py` automatically records and checks its fixed text padding and paragraph gaps in `spacing_contract`. Callers cannot alter those values through content data. The same rules apply after a content/width change and to every instance of the type/variant.
+
+The checker measures declared layout geometry. Actual glyph ink, optical clearances, clipping, mathematical layout and decorative contacts still require the current render. Do not modify a fixed value to disguise a font/layout problem or declare visual acceptance from box equality.

references/text-and-containers.md

@@ -1,6 +1,6 @@
 # Text blocks and container layout
 
-Apply C16–C19 in [production rules](production-rules.md) to page authoring, reconstruction, reusable components and collaboration. These are required constraints. A page-library example is a design reference, not an exemption from current rules. Keep fonts, sizes, colors, grid and spacing tied to the selected external template.
+Apply C16–C23 in [production rules](production-rules.md) to page authoring, reconstruction, reusable components and collaboration. These are required constraints. A page-library example is a design reference, not an exemption from current rules. Keep fonts, sizes, colors, grid and spacing tied to the selected external template.
 
 ## One paragraph, one logical text block
 
@@ -23,6 +23,32 @@ The bundled compiler's default `preserve` text flow retains eligible stacked row
 
 For an object check, find the text-bearing `p:sp` objects and their `p:txBody` in the current slide XML. A normal paragraph should occupy one text-bearing shape; multiple `a:r` runs, `a:br` breaks or `a:p` elements inside the same `p:txBody` are internal text structure. Distinct semantic labels remain independent. If the fallback is used, check the whole-block source and fragment mapping as well as native counts. Group/native XML checks do not establish actual application editing or appearance.
 
+## Paragraph line-breaking rules
+
+Apply punctuation prohibitions at **every line start and end**. Closing punctuation, such as Chinese commas/full stops, closing brackets and closing quotation marks, stays with preceding text; opening brackets and opening quotation marks stay with following text. Do not split paired ellipses (`……`), paired dashes (`——`) or an unbreakable Western word/number merely to fill a line. Use the appropriate punctuation convention for the language and the selected template.
+
+No paragraph line may consist of only one substantive character after ignoring surrounding punctuation and whitespace. Examples of prohibited lines include `果`, `果。`, `（果）` and `“果”。`. Adding more punctuation or spaces does not make a singleton acceptable. Check **all lines, including the final line**, rather than checking only the paragraph's tail. Punctuation-only lines are also invalid.
+
+Independent short labels, standalone table values and separate mathematical symbols are not automatically paragraphs. Determine their actual function; do not relabel a sentence fragment as a label to evade this rule.
+
+Recompute the complete paragraph's break positions. Prefer intact phrases/clauses where they fit; move enough content between neighboring lines to satisfy both punctuation and singleton rules. If the existing bounds cannot support compliant lines, use the template's normal rewrite/layout/capacity policy. Preserve the complete content and logical text block. Do not delete punctuation, silently add words, compress glyphs, invent a smaller font size or independently position the last line.
+
+For supported plain horizontal text, `scripts/paragraph_layout.py` provides `wrap_paragraph(text, max_width, measure, *, max_lines=None)` and `validate_lines(lines)`. The caller supplies a width-measurement function using the actual selected font and size. The wrapper returns derived rows whose concatenation preserves the input; render them as internal lines of one text frame. Unsupported or impossible input raises an error instead of returning a known-invalid layout. Keep the helper with the shared renderer in the portable project's inputs.
+
+This helper is not a complete Unicode line-breaking or typesetting engine, and does not automatically run on arbitrary SVG, rich-text runs or PowerPoint objects. Mixed run sizes need measurements for those actual runs; application reflow must be checked in the current render even when the source rows passed validation. The punctuation/widow descriptions in the [W3C Chinese Layout Requirements working draft](https://www.w3.org/TR/clreq/#prohibition_rules_for_line_start_end) and [orphan discussion](https://www.w3.org/TR/clreq/#handling_of_widows_and_orphans) inform the implementation; the user's requirement here explicitly covers every line.
+
+## Spacing and paragraph separation
+
+Check more than overlap. Text must not crowd a border, a preceding explanation, a following module or a connector. Check heading/body spacing, four-sided container padding, column/group gaps, and the clearance around separators and formulas. Judge actual glyphs and visible edges at normal viewing scale; a text frame's nominal box may contain extra space or fail to describe its ink.
+
+Spacing is **fixed per relationship by the selected template and shared recipe**. Content callers cannot supply numeric gaps, minima, arbitrary padding or alternate spacing variants. The template owner provides moderate values and the recipe applies them; callers do not decide how wide a particular instance should look. See the [fixed spacing contract](spacing.md). Resolve crowding by reflow, shorter content or a different supported whole layout/capacity choice, not by changing spacing or shrinking text. Intentionally cropped watermarks, attached arrows and other decorative/semantic contacts retain their own fixed rules.
+
+Preserve separate paragraphs as separate complete strings or explicit paragraph nodes. Use the fixed positive paragraph gap beyond the normal line-height slots, consistently within the same text role/variant. A line wrap inside one paragraph is not a new paragraph. Prefer native paragraph before/after spacing when multiple paragraphs share a frame; one native frame per paragraph is also supported, with the shared layout deriving all positions. Avoid empty paragraphs, repeated hard breaks and blank text boxes used only as spacers.
+
+`scripts/text_block.py` provides `render_text_block(data, style, theme, bounds, component_id, measure)`. Data carries `schema_version: 1`, `paragraphs: [complete string, ...]` and optional declared `text_role`/`palette_index`. The renderer reads `components.text_group.padding_px` and `paragraph_gap_px`, resolves the role's line height and uses the measured paragraph helper. It emits one SVG text per paragraph with derived internal rows, rejects height overflow, and retains the full content and layout records in metadata. Paragraph bounds describe line-height slots, not exact font ink. Supply actual-font width measurements; check native frame counts and actual rendered spacing separately.
+
+`scripts/layout_spacing.py` provides `resolve_spacing(style, role)` and `check_spacing(boxes, checks, *, style)`. Boxes map stable IDs to `[x,y,width,height]`; shared recipes declare directional gaps or padding using template role names. Numeric `minimum`/`expected`/override fields are rejected. Checks compare the exact fixed value, reporting `too_narrow`, `too_wide`, `overlap` or `outside`. Padding compares the outer frame with its complete usable inner area; actual text need not fill that area. Only declared meaningful relationships are checked. Floating-point tolerance is not layout allowance. This geometric check supplements actual visual review.
+
 ## Keep substantive explanations visible
 
 Determine importance before assigning `caption`, `detail` or muted styles. Small muted text is for supplementary background, provenance and nonessential definitions. Key conditions, timing, dependencies, conclusions and interpretation-changing limitations belong in readable body, node, callout or heading roles. A qualifying statement is not supplementary merely because it sounds cautious.
@@ -61,5 +87,9 @@ Keep the recipe, parameters, content and assets in the portable project's declar
 2. Review every small muted note for meaning. Move essential statements into the main hierarchy and verify no qualification disappeared in the move.
 3. Compare subheading/body and other distinct roles within each container at normal viewing scale. Font family alone cannot pass.
 4. Compare all instances of each type/variant and inspect their creation calls/source. Confirm one shared implementation, no child-coordinate overrides and no post-generation nudges. Equal-looking screenshots alone cannot prove this.
+5. Read the actual line starts, line ends and last line of each paragraph. Reject forbidden punctuation positions, split unbreakable marks/words, punctuation-only rows and every singleton row, including a character surrounded by punctuation. Reflow and regenerate the whole logical paragraph when changing content, width or typography.
+6. Check the template's exact fixed values for text padding, heading/body, adjacent-group and formula/connector spacing. Verify no numeric spacing overrides or instance variants entered the caller input. Check actual glyph/edge clearance separately; non-overlap alone is insufficient.
+7. Locate semantic paragraph boundaries in the content source and render. Confirm visible extra separation between paragraphs while maintaining normal line spacing within each paragraph; no dummy empty paragraphs or manually positioned spacer objects.
+8. For mathematics, inspect [font and equation structure](mathematics.md), then the actual render. Confirm scripts/fractions/limits have not become ordinary unformatted text or a picture.
 
 The compiler cannot reliably infer these semantic properties from arbitrary SVG. Combine source review, native object checks and current rendered-page review; mark unavailable application checks explicitly.

references/visual-design.md

@@ -18,6 +18,8 @@ Inspect local reference images using the available image-viewing tool before edi
 
 Use generated text only as visual guidance. Native source text comes from verified content, with the template's declared fonts and sizes; do not copy misspellings or typography defects from the raster sample. Preserve original evidence/identity assets independently so the final native page can use those files exactly.
 
+Native paragraph lines must satisfy [punctuation and singleton rules](text-and-containers.md#paragraph-line-breaking-rules). Do not preserve a mockup's forbidden line-head/tail punctuation or a row containing only one character with optional punctuation; reflow the complete paragraph within the declared layout.
+
 ## Material generation and transparent assets
 
 For new bitmap illustrations, photos, textures or image edits, use the selected host image-generation capability. Request a transparent background when the final asset needs transparency. Preserve transparency on edits unless the user asks to change it. Use reference-image paths when all targets have paths, otherwise the smallest supported recent-image set that includes every target; do not silently omit a required target.