Release PPT workflow 0.7.2 with text and container constraints

references/charts.md

@@ -26,6 +26,8 @@ JSON顶层字段：`schema_version: 1`，`data_kind`（`synthetic-demo`／`obser
 
 `source`只作为显示文字与元数据保留，工具不会读取链接、补充出处或证明其真实性。所有原始数据同时放入marker的`component_data`，供工程审计；原生图表cache及内嵌XLSX保存未缩放的实际数值。
 
+遵循[文字与容器约束](text-and-containers.md)：小号灰色／弱化说明只承载补充背景、来源或非关键口径。图表的实质性解释、关键条件和时机、结论，以及影响解释范围的限定或免责说明，必须进入可读的主体层级，不得塞进`source`、小字或仅存讲稿。关键单位和口径也不能因字段名被降级。图表标题、说明和正文承担不同作用时，用字号、字重和／或调色板颜色作出明确区分，不能只换字体。
+
 ## 样式来源
 
 `style`和`theme`分别使用`template_ref.py export-style`的`style`、`theme_data`。字体从`typography.families.body`取得，字号默认取`caption`角色，缺少时取`label`；按`canvas.pt_to_px`换算。组件没有组织、字体名或十六进制配色的固定默认值。
@@ -80,6 +82,8 @@ slot.append(component)
 
 `render_chart(data, style, theme, bounds, component_id) -> xml.etree.ElementTree.Element`返回SVG `g`。使用当前页真实槽位的bounds；确认当前template确实有该槽位，不能把示例中的ID、坐标当通用约定。component_id在整页必须唯一。生成后不要单独改fallback图形或marker数据；修改JSON并重新生成，保持fallback指纹和元数据一致。
 
+同一种图表容器／变体共用内部排版实现，调用者只提供内容和整体bounds，不逐例移动标题、图例、图标或说明。需要新的说明区时定义共享组合规则，并重新生成整组；一个连续段落优先保持为一个原生文本框，必要拆分也必须共用一个逻辑文本块和换行规则。
+
 图例、标题、单位及来源位于marker外，编译为独立可编辑对象；marker内转换为真正的Chart和内嵌XLSX。此安排保持页面文字位置受模板控制。若在PowerPoint内改图表数据，外部图例或构成数量文字不会自动更新，需要一起修改，或从工程JSON重建。将图表JSON和生成工具声明为工程输入并锁定，可在迁移后重建；不能只交付生成的SVG与PPTX。
 
 ## 验证与限制

references/components.md

@@ -14,6 +14,8 @@ Each JSON uses `schema_version: 1` and `kind`. Examples are marked `data_kind: s
 
 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.
 
+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.
+
 ## Grouped table
 
 The default table remains unchanged. Select `kind: table, variant: grouped` for a denser comparison with two header levels. Each column is `{id, label, unit?, format?}` with a unique stable ID. `format` is `text` (default), `integer` (integral numbers only, with thousands separators), or `one-decimal`. Formatting changes display text, never original `rows`. `numeric_columns` contains zero-based indices and right-aligns those headers and values. Numeric columns require actual finite numbers rather than formatted strings.
@@ -40,4 +42,4 @@ The CLI protects existing files and symlinked output paths. The output canvas fo
 
 For Python composition, add the Skill's `scripts` directory to `sys.path`, import `render_component` from `basic_component`, and call `render_component(data, style, theme_data, (x,y,width,height), component_id)`. Take `style` and `theme_data` from `template_ref.py export-style`. Insert the returned `g` into the current template page's slot while retaining its existing Master/Layout/placeholder attributes and full roster. A slot label or example content must be removed as part of filling that slot, without removing inherited UI.
 
-After composition, validate native marker payloads using [native objects](native-objects.md). Compile with `native_export.py`, check `a:tbl` for the table and text/shapes/connectors for the other components, then inspect current renders. Keep separate evidence for native structure, application appearance, editing and projection. General architectures, branched flows and custom comparisons can be composed from the same native primitives; this limited helper is not a requirement to fit every diagram into a linear chain.
+After composition, validate native marker payloads using [native objects](native-objects.md). Compile with `native_export.py`, check `a:tbl` for the table and text/shapes/connectors for the other components, then inspect current renders. Keep separate evidence for native structure, application appearance, editing and projection. General architectures, branched flows and custom comparisons can use the same native primitives through shared container/node recipes; this limited helper is not a requirement to fit every diagram into a linear chain.

references/native-authoring.md

@@ -6,6 +6,8 @@ Start the current page from its selected layout source. Retain inheritance metad
 
 Use the template's discrete typography, grid, fixed content region and spacing. Resolve overflow by choosing a suitable layout, shortening content or dividing the page according to the user's workflow. Do not infer ad hoc font sizes and alignment guides from mockup pixels. Keep text as text, simple panels and connectors as geometry, and exact image exceptions as independent assets. Tables, charts and formulas must retain their 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.
+
 ## 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.
@@ -25,7 +27,7 @@ The exporter consumes released v2 manifests and retains all native layout defini
 
 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 and verifies slide/Layout/Master links, placeholders and supplied notes. Existing output is protected, including a concurrent writer appearing during compilation. A failed build does not replace old output.
+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.
 
 ## Template authors and review prototypes
 

references/object-reconstruction.md

@@ -14,6 +14,8 @@ Keep exact supplied logos, figures and screenshots as independent source assets.
 
 Start from the selected template layout source, retaining its Master/Layout/placeholder metadata. Recreate normal text as native text with the external style's font family, discrete size, line spacing and alignment. Build simple panels, rules, arrows and diagram nodes as separate structural objects. Fit to the declared grid, not pixel-by-pixel ad hoc anchors.
 
+Apply [text and container rules](text-and-containers.md) even when the reference image was built differently. Reconstruct a paragraph as one logical text block, preferably one native frame; do not turn each visible source line into an independently positioned box. Repeated container internals use one shared recipe. Essential explanations and limitations stay in the main information hierarchy, and different text functions need size/weight/color distinctions.
+
 Use actual data for native charts; if source values are unavailable, preserve the chart as an evidence image and say why. A native table uses native cells; native formulas require actual editable equation objects where the chosen compiler supports them. A formula bitmap, SVG picture or vector outline is still a picture/path exception. Preserve formula meaning and verify symbols against the source before conversion.
 
 Preserve crop, aspect ratio and source meaning for image objects. Independently editable text over an unchanged full-page screenshot is not a reconstructed page. Keep repeated UI in inherited layers, rather than covering it with copied slide objects.

references/page-collaboration.md

@@ -8,6 +8,8 @@ Agree audience, deck argument, page order and review cadence. Define stable IDs
 
 Freeze one template/version/theme, manifest and style input hashes, roster, fonts, glossary, shared data/assets. Use the project tools for the template snapshot and builder. Give each worker the same baseline, a visual reference when available, page brief and write allowlist. Read library examples from the selected template. Route shared changes to the coordinator before implementation.
 
+Freeze shared container renderers/recipes, named text roles and supported variants as part of that baseline. Workers instantiate them with content and whole-container bounds; they cannot hand-position child text/icons or create private offsets. Include the [text/container constraints](text-and-containers.md) in page review. Any necessary paragraph fragments retain one logical text source/frame and a documented layout implementation; route shared recipe changes to the coordinator.
+
 Adapt [plan.example.json](../assets/collaboration/plan.example.json) into `collaboration/plan.json` and [page-packet.example.json](../assets/collaboration/page-packet.example.json) into `pages/<id>/packet.json`. These are handoff examples, not files interpreted automatically by the compiler. Replace every placeholder with real inputs and project-relative paths. Include the plan in `build.inputs` and packets in each page's `data` list when they must travel in the source lock/package. Do not create a second event store.
 
 ## Write ownership

references/powerpoint-checks.md

@@ -6,6 +6,8 @@ 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.
+
 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.
 
 Report the evidence actually obtained: source/reference validation, native structure and object types, current-page rendering, PowerPoint opening, actual object editing, or projection readability. A successful export cannot establish every later level. If the host application or UI capability is unavailable, deliver the validated source and PPTX with that specific unresolved application check.

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 and rebuildable inputs. **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.
+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.
 
 ## Understand and compose
 
@@ -29,4 +29,11 @@ These rules apply across templates and authoring routes. **Required** rules prot
 - **C14 · Required:** before delivery, check missing pages, example residue, text overflow, occlusion, font substitution, chart data, asset resolution, alignment and object types as relevant to the change. Inspect actual current page renders. If a needed host check is unavailable, state it as unverified; old previews cannot replace new render evidence. Reuse unchanged evidence instead of repeating unrelated checks. See [PowerPoint checks](powerpoint-checks.md).
 - **C15 · Recommended:** identify affected pages after shared-input changes and rebuild/recheck them. Retain recoverable sources and accepted versions. Report versions, selected theme, object exceptions, evidence and remaining issues. Record content reasons and validation for departures from recommendations. Version new components/library entries independently; preserve frozen releases.
 
-Technical helpers enforce supported inputs, path safety, object consistency and capacity. They do not establish factual truth, design quality or application acceptance, and do not convert all recommendations into CLI errors.
+## Text and containers
+
+- **C16 · Required:** keep a paragraph as one logical text block, preferably one native text frame with wrapping, line breaks and styled runs. If a technical constraint requires several native frames, use one complete content source, one overall frame, one reading order and one layout implementation to generate and update all fragments together. Independent line strings/positions, or merely grouping manually positioned frames, do not satisfy this rule.
+- **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).
+
+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.

references/text-and-containers.md

@@ -0,0 +1,65 @@
+# 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.
+
+## One paragraph, one logical text block
+
+Prefer one native text frame for each paragraph, including a continuous multi-line heading or label. Use wrapping, internal line breaks and styled runs inside that frame. Separate subheadings, separate list items, table cells, axis labels and independently meaningful node labels may be separate objects; a visual line break does not create a new semantic item. Do not split a paragraph across independent boxes to fit a container or imitate a mockup.
+
+If the selected route has a concrete technical reason to fragment the text, preserve all of these properties:
+
+- One stable logical block ID and one complete text/runs source. Store line breaks as part of that source or compute them from it, never as independent authored line strings.
+- One overall frame, text-role contract, alignment, line spacing and reading order. A shared layout implementation derives fragment positions and wrapping from the whole block; the page author cannot override individual fragment coordinates or styles.
+- One update operation: changing text, width or typography regenerates the whole block. Preserve the logical ID and fragment mapping in project inputs; group exported fragments as one movable unit where the route supports it.
+- Record the reason for fragmentation and actual object behavior. Source-level unified editing does not prove PowerPoint-native text flow; if edits in PowerPoint cannot reflow across fragments, disclose that limit. Grouping existing independently authored lines alone does not create a logical text block.
+
+The project content model may represent this as `{id, content, runs?, bounds, text_role, layout_rule}`. This is an authoring pattern, not new compiler metadata or an automatically interpreted schema. The shared renderer consumes the block. Fragments, if necessary, are derived output and are never independently maintained content.
+
+### SVG and the bundled native route
+
+Use a single SVG `text` for the paragraph. For authored visual rows, use direct-child `tspan` elements: repeat the parent's `x`, start at `dy="0"`, then use the same positive line step. Inline styling may use nested spans without baseline jumps. Take all coordinates and text styles from the selected layout/renderer, not hand-measured mockup offsets.
+
+The bundled compiler's default `preserve` text flow retains eligible stacked rows as one native frame, with internal breaks. Arbitrary per-line `y`, unequal `x`, nested baseline jumps or prior line-flattening may produce separate frames. Do not assume that one SVG `text` guarantees one PPTX frame. Inspect the actual native object structure. Do not select split text flow for ordinary paragraph authoring.
+
+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.
+
+## 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.
+
+| Statement | Treatment |
+|---|---|
+| Data source, collection date or a nonessential terminology expansion | Supplementary note is allowed; retain source metadata too |
+| “Only proceed after approval”, “retry after timeout” | Main process/node text; the viewer needs it to follow the process |
+| “Method B is faster” | Main comparison/conclusion hierarchy |
+| “Only measured on this dataset; does not establish general performance” | Visible limitation alongside the claim, not small muted text or speaker-notes-only |
+| A unit/definition that changes what a chart means | Keep it visibly associated with the chart at a suitable readable level |
+
+Read the page without the small muted notes. Its workflow, conclusion and scope must still be accurate and complete. This check also applies to any field named `source`: the field name cannot make a substantive claim into provenance.
+
+## Different roles inside a container
+
+Assign named roles before rendering: for example `card_heading`, `card_body`, `value`, `unit` and `source_note`, mapped to the external template's declared typography and palette. If subheading and body have different functions, distinguish them perceptibly with size, weight and/or color. Using serif for one and sans serif for the other at otherwise identical styling is insufficient. Do not introduce arbitrary sizes or literal colors to create the difference.
+
+The required distinction is between functions, not every string. Peers with the same function share a role. Verify the distinction in the actual theme and normal viewing scale; two almost identical colors are not a useful hierarchy. A substantive statement remains a body/callout role even when the component offers a small `detail` field.
+
+## A shared layout implementation for each container type
+
+Reuse a template/component renderer when it fits. For a new container, define one shared recipe/function and a content interface before placing its instances. The same type/variant must use the same padding, slot order, text roles, wrapping/height policy, icon size/alignment and spacing rules across pages and authors.
+
+The caller may pass semantic content, an icon asset/role, a declared variant and the whole container's bounds/placement. Internal `title_x`, `body_y`, `icon_offset`, per-line coordinates and similar instance-level overrides are prohibited. The renderer may compute geometry from bounds, content and common style; deterministic calculation is how the rule is implemented. A shared content-driven height/wrapping policy can produce different heights for different text lengths.
+
+If content does not fit, use the recipe's supported wrapping/height rules, rewrite, enlarge the whole slot or change the page/layout. Add a named shared variant only for a meaningful repeated need; do not disguise each instance's manual offsets as its own variant. Do not stretch generated text or icons with a group transform to make them fit. Regenerate from new bounds.
+
+Diagram nodes may be arranged to express the actual topology. Each repeated node's internal label/icon layout still comes from the shared node recipe. Custom diagrams do not justify hand-positioning the contents of every repeated card or node.
+
+Keep the recipe, parameters, content and assets in the portable project's declared inputs. For multiple authors, the coordinator freezes the shared implementation/style/variant set; page workers only instantiate it. Shared changes return to the coordinator and trigger checks on affected pages.
+
+## Review before delivery
+
+1. Compare the complete paragraph source with native text frames. Confirm one frame, or the justified whole-block fallback with derived fragments; inspect actual breaks, reading order and edit behavior at the requested evidence level.
+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.
+
+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.