Placeholder overflow constraints: per-layout, per-placeholder line limits and overflow behaviour

[tmustier]

Placeholder overflow constraints: per-layout, per-placeholder line limits and overflow behaviour

Problem

Different placeholders across different layouts have different overflow tolerances, but the tool currently only handles this with a hardcoded text_limits block in the config:

text_limits:
  title_max_lines: 2
  subtitle_max_lines: 1
  title_slide_subtitle_max_lines: 1

This is too coarse. Real examples from a deck build:

• Quote layout title: The quote text placeholder has a decorative vertical accent bar alongside it. When the quote wraps to 3 lines, it overflows the bar. The placeholder needs a max of ~2 lines, but it's a title placeholder — so the generic title_max_lines: 2 happens to work, but for the wrong reason.
• Section layout title: Bottom-anchored, so overflow goes upward into the header divider. This is partly a template fix (change anchor to top), but the tool should also know this placeholder can't handle more than ~3 lines at its font size.
• Contrast 1/2 title: Narrower than Default — a title that fits on Default may wrap on Contrast 1/2.

The current approach conflates placeholder type (title/subtitle) with overflow tolerance, when what matters is the specific placeholder in the specific layout.

Proposed direction

Config structure

Extend the template config with per-layout placeholder constraints:

placeholder_constraints:
  "Quote":
    title:
      max_lines: 2
      overflow: warn        # warn | clip | error
      note: "Vertical accent bar covers ~2 lines"
    subtitle:
      max_lines: 1

  "Section":
    title:
      max_lines: 3
      overflow: warn
      note: "Bottom-anchored; overflow goes upward into header divider"

  "Title - Contrast":
    title:
      max_lines: 2
    subtitle:
      max_lines: 2

  "Default":
    title:
      max_lines: 2
    subtitle:
      max_lines: 1

  "2/3":
    title:
      max_lines: 2
      note: "Narrower than Default — titles wrap sooner"
    subtitle:
      max_lines: 1

Behaviour

• overflow: warn (default): emit a warning during generate / edit / verify — "Quote slide title wraps to ~3 lines (max 2); vertical accent bar may not cover all text"
• overflow: error: hard-fail (for placeholders where overflow is visually broken)
• overflow: clip: future — could auto-truncate or reduce font size (not v1)

Backwards compatibility

The existing text_limits block continues to work as global defaults. Per-layout constraints override them. If no constraint is specified for a layout+placeholder, fall back to text_limits.

Auto-generation

pptx init-config could generate a starter placeholder_constraints section by:

1. Iterating layouts and their placeholders
2. Estimating max lines from placeholder height ÷ (font size × line spacing)
3. Setting conservative defaults with # review comments

Relationship to #8

Issue #8 (verify placeholder line limits) covers the warning mechanism. This issue covers the data model — how constraints are defined per layout/placeholder. #8's implementation should read from this config structure.

Acceptance criteria

• Config supports placeholder_constraints keyed by layout name and placeholder role
• Each constraint can specify max_lines and overflow behaviour (warn/error)
• pptx generate respects per-layout constraints when filling title/subtitle/tracker
• pptx edit respects constraints when editing placeholder text
• pptx verify uses constraints for its overflow checks
• Existing text_limits works as global fallback
• pptx init-config generates starter constraints with estimated max lines