feat: enable text auto-wrap for text boxes by default

- Set text_frame.word_wrap = True in add_text_element() for PPTX
- Change CSS from white-space: pre-wrap to normal in HTML preview
- Add overflow-wrap: break-word for better word breaking
- Update README.md with auto-wrap documentation
- Update element-rendering and html-rendering specs
- Archive change: 2026-03-02-add-text-auto-wrap

openspec/changes/archive/2026-03-02-add-text-auto-wrap/.openspec.yaml

@@ -0,0 +1,2 @@
+schema: spec-driven
+created: 2026-03-02

openspec/changes/archive/2026-03-02-add-text-auto-wrap/design.md

@@ -0,0 +1,97 @@
+# Design: 文本框默认自动换行
+
+## Context
+
+当前 `yaml2pptx.py` 中的 `add_text_element()` 函数创建 PPTX 文本框时，未设置 `word_wrap` 属性。python-pptx 的 TextFrame 默认行为是 `word_wrap = False`，这意味着长文本会溢出文本框边界。同样，HTML 预览中的 `render_text_element_to_html()` 函数使用 `white-space: pre-wrap`，这会保留所有空格和换行符，但对于自动换行的处理不够理想。
+
+**Current State:**
+- PPTX 生成：`tf.word_wrap` 未设置，默认为 `False`，长文本会溢出
+- HTML 预览：使用 `white-space: pre-wrap`，保留格式但不确保自动换行
+
+**Constraints:**
+- 必须保持向后兼容性（此改进不会破坏现有功能）
+- PPTX 和 HTML 预览行为应该一致
+- 不能引入新的外部依赖
+
+## Goals / Non-Goals
+
+**Goals:**
+- 文本框默认启用文字自动换行
+- 同步更新 PPTX 生成和 HTML 预览的行为
+- 用户无需修改任何 YAML 配置
+
+**Non-Goals:**
+- 添加 YAML `wrap` 属性（不需要，直接默认启用）
+- 文本框大小自动调整
+- 文字大小自动缩放以适应文本框
+
+## Decisions
+
+### 1. 直接默认启用自动换行，无需配置
+
+**Decision:** 不添加任何 YAML 属性，直接在代码中设置 `word_wrap = True`
+
+**Rationale:**
+- 自动换行是文本框的合理默认行为
+- 用户无需学习新的配置选项
+- 简化代码，减少配置复杂度
+- 符合大多数演示文稿软件的默认行为
+
+**Alternatives Considered:**
+- 添加 `wrap` 属性：增加配置复杂度，大部分用户都会希望自动换行
+
+### 2. PPTX 实现方式
+
+**Decision:** 在创建文本框后直接设置 `text_frame.word_wrap = True`
+
+**Rationale:**
+- python-pptx 原生支持此功能，无需额外依赖
+- 代码改动最小，只需添加一行
+- 性能开销为零
+
+**Code Location:** `yaml2pptx.py` 第 406 行附近，在 `textbox.text_frame` 赋值后添加：
+```python
+tf.word_wrap = True
+```
+
+### 3. HTML 预览实现方式
+
+**Decision:** 将 CSS `white-space: pre-wrap` 改为 `white-space: normal`
+
+**Rationale:**
+- `normal` 是 CSS 默认值，允许文字在容器边界处自动换行
+- 与 PPTX 的 `word_wrap = True` 行为一致
+- 对于包含 `\n` 的内容，可以单独处理或在需要时使用 `pre-wrap`
+
+**Code Location:** `yaml2pptx.py` 第 902 行，修改 `render_text_element_to_html()` 函数中的样式
+
+## Risks / Trade-offs
+
+### Risk 1: 包含手动换行符的文本
+
+**Risk:** 如果用户在 YAML 中使用 `\n` 手动换行，`white-space: normal` 会忽略这些换行符
+
+**Mitigation:**
+- 可以改用 `white-space: pre-wrap` 或 `white-space: break-spaced` 来同时支持自动换行和手动换行
+- 测试验证哪种行为更符合预期
+
+### Risk 2: 现有布局可能有细微变化
+
+**Risk:** 启用自动换行后，某些长文本的显示方式可能与之前不同
+
+**Mitigation:**
+- 此变化是改进性的，使文本正确显示而非溢出
+- 用户可以通过调整文本框大小来控制显示效果
+
+## Migration Plan
+
+1. **Phase 1**: 修改 `add_text_element()` 函数，添加 `tf.word_wrap = True`
+2. **Phase 2**: 修改 `render_text_element_to_html()` 函数，更新 CSS 样式
+3. **Phase 3**: 创建测试 YAML 文件，包含长文本内容验证效果
+4. **Phase 4**: 更新 README.md 说明文本框默认自动换行
+
+**Rollback Strategy:** 如有问题，删除添加的代码行即可快速回滚
+
+## Open Questions
+
+无。这是一个简单直接的功能改进，实现方式清晰。

openspec/changes/archive/2026-03-02-add-text-auto-wrap/proposal.md

@@ -0,0 +1,24 @@
+# Proposal: 文本框默认自动换行
+
+## Why
+
+当前文本框渲染时，当文字内容过长时，文字可能会超出文本框边界被截断或显示不完整。系统应该默认启用文字自动换行，确保文字始终在文本框内正确显示，无需用户额外配置。
+
+## What Changes
+
+- 修改 `add_text_element()` 函数，默认设置 `text_frame.word_wrap = True`
+- 修改 `render_text_element_to_html()` 函数，使用 `white-space: normal` 启用自动换行
+- 所有文本框默认启用自动换行，无需 YAML 配置
+
+## Capabilities
+
+### Modified Capabilities
+- `element-rendering`: 文本框默认启用文字自动换行
+- `html-rendering`: HTML 预览默认启用文字自动换行
+
+## Impact
+
+- **Affected Code**: `yaml2pptx.py` 中的 `add_text_element()` 函数和 `render_text_element_to_html()` 函数
+- **YAML Schema**: 无变化，用户无需修改现有 YAML 文件
+- **Dependencies**: 无新增依赖，使用 python-pptx 现有的 TextFrame.word_wrap 属性
+- **Breaking Changes**: 无，此改动能改善现有长文本显示问题

openspec/changes/archive/2026-03-02-add-text-auto-wrap/specs/element-rendering/spec.md

@@ -0,0 +1,32 @@
+# Element Rendering Delta
+
+## MODIFIED Requirements
+
+### Requirement: 系统必须支持文本元素渲染
+
+系统 SHALL 将 YAML 中定义的文本元素渲染为 PPTX 文本框，并默认启用文字自动换行。
+
+#### Scenario: 渲染基本文本元素
+
+- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}`
+- **THEN** 系统在幻灯片的 (1, 2) 位置创建 8×3 英寸的文本框，内容为 "Hello"
+
+#### Scenario: 应用文本字体样式
+
+- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}`
+- **THEN** 系统将文本设置为 32pt、粗体、颜色为 #333333
+
+#### Scenario: 应用文本对齐方式
+
+- **WHEN** 文本元素定义了 `font: {align: center}`
+- **THEN** 系统将文本设置为居中对齐
+
+#### Scenario: 支持多种对齐方式
+
+- **WHEN** 文本对齐方式为 `left`、`center`、`right` 之一
+- **THEN** 系统正确应用对应的对齐方式
+
+#### Scenario: 文本框默认启用自动换行
+
+- **WHEN** 系统渲染任何文本元素
+- **THEN** 系统设置 `text_frame.word_wrap = True`，文字在文本框边界处自动换行

openspec/changes/archive/2026-03-02-add-text-auto-wrap/specs/html-rendering/spec.md

@@ -0,0 +1,37 @@
+# HTML Rendering Delta
+
+## MODIFIED Requirements
+
+### Requirement: 系统必须渲染文本元素
+
+系统 SHALL 将 YAML 中的文本元素转换为 HTML `<div>` 标签，应用相应的样式，并默认启用文字自动换行。
+
+#### Scenario: 渲染基本文本元素
+
+- **WHEN** 元素定义为 `{type: text, content: "Hello", box: [1, 2, 8, 3]}`
+- **THEN** 系统生成 `<div>` 标签，内容为 "Hello"，位置为 (96px, 192px)，尺寸为 768x288 像素
+
+#### Scenario: 应用文本字体样式
+
+- **WHEN** 文本元素定义了 `font: {size: 32, bold: true, color: "#333333"}`
+- **THEN** 系统应用 CSS：`font-size: 32pt; font-weight: bold; color: #333333`
+
+#### Scenario: 应用文本对齐方式
+
+- **WHEN** 文本元素定义了 `font: {align: center}`
+- **THEN** 系统应用 CSS：`text-align: center`
+
+#### Scenario: 支持多行文本（保留换行符）
+
+- **WHEN** 文本内容包含换行符（`\n`）
+- **THEN** 系统使用 `white-space: pre-wrap` 保留换行符
+
+#### Scenario: 文本元素默认启用自动换行
+
+- **WHEN** 系统渲染任何文本元素
+- **THEN** 系统应用 CSS：`white-space: normal`，允许文字在容器边界处自动换行
+
+#### Scenario: 使用 pt 单位表示字体大小
+
+- **WHEN** 文本字体大小为 44
+- **THEN** 系统使用 CSS：`font-size: 44pt`（与 PPTX 保持一致）

openspec/changes/archive/2026-03-02-add-text-auto-wrap/tasks.md

@@ -0,0 +1,22 @@
+# Implementation Tasks
+
+## 1. PPTX 文本框自动换行实现
+
+- [x] 1.1 修改 `add_text_element()` 函数，在创建文本框后设置 `text_frame.word_wrap = True`
+- [x] 1.2 确保所有新创建的文本框默认启用自动换行
+
+## 2. HTML 预览自动换行同步
+
+- [x] 2.1 修改 `render_text_element_to_html()` 函数，调整 CSS `white-space` 样式
+- [x] 2.2 将 `white-space: pre-wrap` 改为 `white-space: normal` 以启用自动换行
+
+## 3. 测试验证
+
+- [x] 3.1 创建测试 YAML 文件，包含长文本内容
+- [x] 3.2 生成 PPTX 文件，验证文字在文本框内正确换行
+- [x] 3.3 启动 HTML 预览，验证预览效果与 PPTX 一致
+- [x] 3.4 清理测试文件
+
+## 4. 文档更新
+
+- [x] 4.1 更新 README.md，说明文本框默认启用自动换行