markdown-flow 0.2.81__tar.gz → 0.2.83__tar.gz

{markdown_flow-0.2.81 → markdown_flow-0.2.83}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-flow
-Version: 0.2.81
+Version: 0.2.83
 Summary: An agent library designed to parse and process MarkdownFlow documents
 Project-URL: Homepage, https://github.com/ai-shifu/markdown-flow-agent-py
 Project-URL: Bug Tracker, https://github.com/ai-shifu/markdown-flow-agent-py/issues
@@ -730,7 +730,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - [Ruff](https://docs.astral.sh/ruff/) for lightning-fast Python linting and formatting
 - [MyPy](https://mypy.readthedocs.io/) for static type checking
 - [Commitizen](https://commitizen-tools.github.io/commitizen/) for standardized commit messages
-- [Pre-commit](https://pre-commit.com/) for automated code quality checks
+- [Lefthook](https://lefthook.dev/) for automated code quality checks (git hooks + CI)
 
 ## 📞 Support
 

{markdown_flow-0.2.81 → markdown_flow-0.2.83}/README.md

@@ -712,7 +712,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - [Ruff](https://docs.astral.sh/ruff/) for lightning-fast Python linting and formatting
 - [MyPy](https://mypy.readthedocs.io/) for static type checking
 - [Commitizen](https://commitizen-tools.github.io/commitizen/) for standardized commit messages
-- [Pre-commit](https://pre-commit.com/) for automated code quality checks
+- [Lefthook](https://lefthook.dev/) for automated code quality checks (git hooks + CI)
 
 ## 📞 Support
 

{markdown_flow-0.2.81 → markdown_flow-0.2.83}/markdown_flow/__init__.py

@@ -88,4 +88,4 @@ __all__ = [
     "replace_variables_in_text",
 ]
 
-__version__ = "0.2.81"
+__version__ = "0.2.83"

markdown_flow-0.2.83/markdown_flow/constants.py

@@ -0,0 +1,254 @@
+"""
+Markdown-Flow Constants
+
+Constants for document parsing, variable matching, validation, and other core functionality.
+"""
+
+import re
+
+
+# Pre-compiled regex patterns
+COMPILED_PERCENT_VARIABLE_REGEX = re.compile(
+    r"%\{\{([^}]+)\}\}"  # Match %{{variable}} format for preserved variables
+)
+
+# Interaction regex base patterns
+INTERACTION_PATTERN = r"(?<!\\)\?\[([^\]]*)\](?!\()"  # Base pattern with capturing group for content extraction, excludes escaped \?[]
+INTERACTION_PATTERN_NON_CAPTURING = r"(?<!\\)\?\[[^\]]*\](?!\()"  # Non-capturing version for block splitting, excludes escaped \?[]
+INTERACTION_PATTERN_SPLIT = r"((?<!\\)\?\[[^\]]*\](?!\())"  # Pattern for re.split() with outer capturing group, excludes escaped \?[]
+
+# InteractionParser specific regex patterns
+COMPILED_INTERACTION_REGEX = re.compile(INTERACTION_PATTERN)  # Main interaction pattern matcher
+COMPILED_LAYER1_INTERACTION_REGEX = COMPILED_INTERACTION_REGEX  # Layer 1: Basic format validation (alias)
+COMPILED_LAYER2_VARIABLE_REGEX = re.compile(r"^%\{\{([^}]+)\}\}(.*)$")  # Layer 2: Variable detection
+COMPILED_LAYER3_ELLIPSIS_REGEX = re.compile(r"^(.*)\.\.\.(.*)")  # Layer 3: Split content around ellipsis
+COMPILED_LAYER3_BUTTON_VALUE_REGEX = re.compile(r"^(.+)//(.+)$")  # Layer 3: Parse Button//value format
+COMPILED_BRACE_VARIABLE_REGEX = re.compile(
+    r"(?<!%)\{\{([^}]+)\}\}"  # Match {{variable}} format for replaceable variables
+)
+COMPILED_SINGLE_PIPE_SPLIT_REGEX = re.compile(r"(?<!\|)\|(?!\|)")  # Split on single | but not ||
+
+# Document parsing constants (using shared INTERACTION_PATTERN defined above)
+
+# Separators
+BLOCK_SEPARATOR = r"\n\s*---\s*\n"
+# Multiline preserved block fence: starts with '!' followed by 3 or more '='
+PRESERVE_FENCE_PATTERN = r"^!={3,}\s*$"
+COMPILED_PRESERVE_FENCE_REGEX = re.compile(PRESERVE_FENCE_PATTERN)
+
+# Inline preserved content pattern: ===content=== format (historical compatibility)
+INLINE_PRESERVE_PATTERN = r"^===(.+)=== *$"
+COMPILED_INLINE_PRESERVE_REGEX = re.compile(INLINE_PRESERVE_PATTERN)
+
+# Inline preserved content search pattern (for finding ===...=== within a line)
+# Non-greedy match to handle multiple occurrences on same line
+INLINE_PRESERVE_SEARCH_PATTERN = r"===\s*(.+?)\s*==="
+COMPILED_INLINE_PRESERVE_SEARCH_REGEX = re.compile(INLINE_PRESERVE_SEARCH_PATTERN)
+
+# Inline exclamation preserved content pattern: !===content!=== format (higher priority than INLINE_PRESERVE_PATTERN)
+# Supports scenarios:
+#   - !===content!===                            (compact format)
+#   - !=== content !===                          (with spaces)
+#   - prefix !===content!=== suffix              (inline mixed)
+#   - !===content\n!===                          (cross-line format)
+# Uses (?s) flag to make . match newlines, supports cross-line content
+INLINE_EXCLAMATION_PRESERVE_PATTERN = r"(?s)!===(.*?)!==="
+COMPILED_INLINE_EXCLAMATION_PRESERVE_REGEX = re.compile(INLINE_EXCLAMATION_PRESERVE_PATTERN)
+
+# Code fence patterns (CommonMark specification compliant)
+# Code block fence start: 0-3 spaces + at least 3 backticks or tildes + optional info string
+CODE_FENCE_START_PATTERN = r"^[ ]{0,3}([`~]{3,})(.*)$"
+COMPILED_CODE_FENCE_START_REGEX = re.compile(CODE_FENCE_START_PATTERN)
+
+# Code block fence end: 0-3 spaces + at least 3 backticks or tildes + optional whitespace
+CODE_FENCE_END_PATTERN = r"^[ ]{0,3}([`~]{3,})\s*$"
+COMPILED_CODE_FENCE_END_REGEX = re.compile(CODE_FENCE_END_PATTERN)
+
+# JSON extraction pattern for nested objects
+# Matches JSON objects including nested structures using balanced braces
+JSON_OBJECT_PATTERN = r"\{(?:[^{}]|(?:\{[^{}]*\}))*\}"
+COMPILED_JSON_OBJECT_REGEX = re.compile(JSON_OBJECT_PATTERN)
+
+# Output instruction markers
+OUTPUT_INSTRUCTION_PREFIX = "<原样输出>"
+OUTPUT_INSTRUCTION_SUFFIX = "</原样输出>"
+
+# Output Language Control - Three-layer anchoring templates
+OUTPUT_LANGUAGE_INSTRUCTION_TOP = """<output_language_override>
+🚨 CRITICAL: 100% {0} OUTPUT REQUIRED 🚨
+ZERO language mixing allowed. EVERY word must be in {0}.
+Before processing: Translate ALL non-{0} words/phrases to {0} first.
+This overrides ALL other instructions.
+</output_language_override>"""
+
+OUTPUT_LANGUAGE_INSTRUCTION_BOTTOM = """<output_language_final_check>
+🚨 PRE-RESPONSE CHECK: Verify EVERY word is {0}. If ANY non-{0} word exists, translate it first. 🚨
+</output_language_final_check>"""
+
+# Interaction prompt templates (Modular design)
+INTERACTION_PROMPT_BASE = """# JSON Interaction Translation Task
+
+You will receive a JSON object containing interaction elements (`buttons` and/or `question` fields), and you need to translate the text in it into the target language.
+
+## Output Format Requirements
+
+- Return pure JSON only; do not add any explanations or Markdown code blocks
+- The JSON structure must be exactly the same as the input: do not add or remove fields, do not modify key names, and do not change the order
+- Preserve the original spaces, punctuation, and quotation marks"""
+
+INTERACTION_PROMPT_NO_TRANSLATION = """
+## Processing Rules
+
+Return the input JSON exactly as-is, character for character:
+
+- Do not translate any text
+- Do not modify any formatting
+- Do not add any content (such as display//value separation)
+- Do not delete any content
+- Do not change any order
+
+## Example
+
+- Input `{"buttons": ["Product Manager", "Developer"], "question": "Other role"}`
+- Output `{"buttons": ["Product Manager", "Developer"], "question": "Other role"}`"""
+
+INTERACTION_PROMPT_WITH_TRANSLATION = """
+## Translation Rules
+
+- Translate the text in `buttons` and `question` into the target language
+- Translate only the display text (the Display part); do not change the JSON structure
+- If `display//value` separation exists (for example `Yes//1`), translate only the Display part before `//` and keep value unchanged
+- Use the target language 100%; language mixing is not allowed. Translate all non-target-language words before outputting
+- If a text segment's original language is already the same as the target language, return that text unchanged (for example, when the target language is English and the original text is also English, do not rewrite it)
+
+## Examples
+
+- Input `{"buttons": ["Yes//1", "No//0"]}`, target language Spanish -> `{"buttons": ["Sí//1", "No//0"]}`
+- Input `{"buttons": ["Débutant", "Avancé"], "question": "Autre"}`, target language English -> `{"buttons": ["Beginner", "Advanced"], "question": "Other"}`"""
+
+# Default: use no translation version (backward compatible)
+DEFAULT_INTERACTION_PROMPT = INTERACTION_PROMPT_BASE + "\n" + INTERACTION_PROMPT_NO_TRANSLATION
+
+# Interaction error prompt templates
+DEFAULT_INTERACTION_ERROR_PROMPT = "Please rewrite the following error message to be friendlier and more personalized, helping the user understand the problem and providing constructive guidance:"
+
+# Interaction error rendering instructions
+INTERACTION_ERROR_RENDER_INSTRUCTIONS = """
+Return only the friendly error message; do not include any other format or explanation."""
+
+# Standard validation response status
+VALIDATION_RESPONSE_OK = "ok"
+VALIDATION_RESPONSE_ILLEGAL = "illegal"
+
+# Validation task template (Modular design)
+VALIDATION_TASK_BASE = """You are a string validation program, not a conversational assistant.
+
+Your only task: check the input according to the following rules and output exactly one of these JSON objects:
+{{"result": "ok", "parse_vars": {{"{target_variable}": "<exact user input>"}}}} or {{"result": "illegal", "reason": "<reason>"}}
+
+It is strictly forbidden to output any natural-language explanation."""
+
+VALIDATION_TASK_WITH_LANGUAGE = """
+
+# reason Language Rule
+reason must use the language specified in the <output_language_override> tag."""
+
+VALIDATION_TASK_NO_LANGUAGE = """
+
+# reason Language Rule
+reason uses the primary language of the user input or question (auto-detect)."""
+
+# Default: use no language version (backward compatible)
+VALIDATION_TASK_TEMPLATE = VALIDATION_TASK_BASE + VALIDATION_TASK_NO_LANGUAGE
+
+# Validation requirements template (extremely lenient version)
+VALIDATION_REQUIREMENTS_TEMPLATE = """# Validation Algorithm (execute in order)
+
+Step 1: Empty-value check (string length check)
+
+Check rule: input.trim().length == 0 ?
+- YES -> empty
+- NO  -> non-empty
+
+Important: as long as the number of characters after trimming leading and trailing spaces is > 0, it is non-empty.
+Important: do not judge semantics. All visible characters (a, 1, @, CJK characters) count toward length.
+Examples:
+  - ""      -> length 0 -> empty
+  - "  "    -> length 0 -> empty
+  - "aa"    -> length 2 -> non-empty
+  - "@_@"   -> length 3 -> non-empty
+  - "abc"   -> length 3 -> non-empty
+
+Step 2: Vague-answer check
+
+Reject the following vague answers: "I don't know", "I'm not sure", "No / none", "I won't tell you"
+
+Step 3: Religious/political check
+
+Reject only explicit religious or political position statements (religious doctrines, political slogans, etc.).
+Place names, regions, etc. (Beijing, Shanghai, etc.) and ordinary vocabulary do not count.
+
+Step 4: Output result (the reason language follows the language requirement in <document_context>)
+
+Pseudocode logic:
+  if empty:
+      output {{"result": "illegal", "reason": "input is empty (or its translation into the corresponding language)"}}
+  else if vague answer:
+      output {{"result": "illegal", "reason": "please provide specific content (or its translation into the corresponding language)"}}
+  else if religious/political:
+      output {{"result": "illegal", "reason": "contains sensitive content (or its translation into the corresponding language)"}}
+  else:
+      output {{"result": "ok", "parse_vars": {{"{target_variable}": "<exact user input>"}}}}
+
+Extremely important:
+- len(input after trimming leading and trailing spaces) > 0 -> it must be regarded as non-empty
+- Symbols, numbers, brand names, place names, etc. are neither "empty" nor "invalid"
+- Pass by default; reject only when there is an explicit violation
+"""
+
+# ========== Error Message Constants ==========
+
+# Interaction error messages
+OPTION_SELECTION_ERROR_TEMPLATE = "请选择以下选项之一：{options}"
+INPUT_EMPTY_ERROR = "输入不能为空"
+
+# System error messages
+UNSUPPORTED_PROMPT_TYPE_ERROR = "不支持的提示词类型: {prompt_type} (支持的类型: base_system, document, interaction, interaction_error, output_language)"
+BLOCK_INDEX_OUT_OF_RANGE_ERROR = "Block index {index} is out of range; total={total}"
+LLM_PROVIDER_REQUIRED_ERROR = "需要设置 LLMProvider 才能调用 LLM"
+INTERACTION_PARSE_ERROR = "交互格式解析失败: {error}"
+
+# LLM provider errors
+NO_LLM_PROVIDER_ERROR = "NoLLMProvider 不支持 LLM 调用"
+
+# Validation constants
+JSON_PARSE_ERROR = "无法解析JSON响应"
+VALIDATION_ILLEGAL_DEFAULT_REASON = "输入不合法"
+VARIABLE_DEFAULT_VALUE = "UNKNOWN"
+
+# Context generation constants
+CONTEXT_QUESTION_MARKER = "# Related Question"
+CONTEXT_CONVERSATION_MARKER = "# Conversation Context"
+CONTEXT_BUTTON_OPTIONS_MARKER = "## Predefined Options"
+
+# Context generation templates
+CONTEXT_QUESTION_TEMPLATE = f"{CONTEXT_QUESTION_MARKER}\n{{question}}"
+CONTEXT_CONVERSATION_TEMPLATE = f"{CONTEXT_CONVERSATION_MARKER}\n{{content}}"
+CONTEXT_BUTTON_OPTIONS_TEMPLATE = (
+    f"{CONTEXT_BUTTON_OPTIONS_MARKER}\n"
+    "Available predefined options include: {button_options}\n"
+    "Note: If the user selected one of these options, it should be accepted; if the user entered custom content, accept it as long as it is a reasonable answer to the question."
+)
+
+# Next interaction context prompt templates
+NEXT_INTERACTION_CONTEXT_INTRO = (
+    "The next interaction will appear immediately after this content. When generating the current content, connect to it naturally. "
+    "You may briefly restate, explain, or set up the available choices so the user understands what they will decide next, but do not output the interaction syntax or answer on the user's behalf."
+)
+NEXT_INTERACTION_TEXT_INPUT_TEMPLATE = "The next interaction asks the user to answer in text: {question}"
+NEXT_INTERACTION_SINGLE_CHOICE_TEMPLATE = "The next interaction is a single-choice question. The user will choose one option from: {options}"
+NEXT_INTERACTION_MULTIPLE_CHOICE_TEMPLATE = "The next interaction is a multiple-choice question. The user can choose one or more options from: {options}"
+NEXT_INTERACTION_SINGLE_CHOICE_WITH_TEXT_INTRO = "The next interaction is a single-choice question with an optional custom text answer."
+NEXT_INTERACTION_MULTIPLE_CHOICE_WITH_TEXT_INTRO = "The next interaction is a multiple-choice question with an optional custom text answer."
+NEXT_INTERACTION_PREDEFINED_OPTIONS_TEMPLATE = "The predefined options are: {options}."
+NEXT_INTERACTION_CUSTOM_TEXT_PROMPT_TEMPLATE = "The custom text prompt is: {question}"

{markdown_flow-0.2.81 → markdown_flow-0.2.83}/markdown_flow/core.py

@@ -25,6 +25,14 @@ from .constants import (
     INTERACTION_PROMPT_BASE,
     INTERACTION_PROMPT_WITH_TRANSLATION,
     LLM_PROVIDER_REQUIRED_ERROR,
+    NEXT_INTERACTION_CONTEXT_INTRO,
+    NEXT_INTERACTION_CUSTOM_TEXT_PROMPT_TEMPLATE,
+    NEXT_INTERACTION_MULTIPLE_CHOICE_TEMPLATE,
+    NEXT_INTERACTION_MULTIPLE_CHOICE_WITH_TEXT_INTRO,
+    NEXT_INTERACTION_PREDEFINED_OPTIONS_TEMPLATE,
+    NEXT_INTERACTION_SINGLE_CHOICE_TEMPLATE,
+    NEXT_INTERACTION_SINGLE_CHOICE_WITH_TEXT_INTRO,
+    NEXT_INTERACTION_TEXT_INPUT_TEMPLATE,
     OUTPUT_LANGUAGE_INSTRUCTION_BOTTOM,
     OUTPUT_LANGUAGE_INSTRUCTION_TOP,
     UNSUPPORTED_PROMPT_TYPE_ERROR,
@@ -1286,11 +1294,88 @@ class MarkdownFlow:
         if self._output_language:
             user_content = f"<output_language_instruction>\n🚨 OUTPUT: 100% {self._output_language} - Translate ALL non-{self._output_language} words/phrases to {self._output_language} 🚨\n</output_language_instruction>\n\n{user_content}"
 
+        next_interaction_context = self._build_next_interaction_context_prompt(block_index, variables)
+        if next_interaction_context:
+            user_content = f"{user_content}\n\n{next_interaction_context}"
+
         # Add processed content as user message (as instruction to LLM)
         messages.append({"role": "user", "content": user_content})
 
         return messages
 
+    def _build_next_interaction_context_prompt(
+        self,
+        block_index: int,
+        variables: dict[str, str | list[str]] | None,
+    ) -> str:
+        """Build natural prompt context from the immediately following interaction block."""
+        blocks = self.get_all_blocks()
+        next_index = block_index + 1
+        if next_index >= len(blocks):
+            return ""
+
+        next_block = blocks[next_index]
+        if next_block.block_type != BlockType.INTERACTION:
+            return ""
+
+        interaction_content = replace_variables_in_text(next_block.content, variables or {})
+        parse_result = InteractionParser().parse(interaction_content)
+        if parse_result.get("error"):
+            return ""
+
+        question = parse_result.get("question", "").strip()
+        buttons = parse_result.get("buttons") or []
+        option_displays = [button.get("display", "").strip() for button in buttons if button.get("display", "").strip()]
+
+        detail = self._format_next_interaction_detail(parse_result.get("type"), question, option_displays)
+        if not detail:
+            return ""
+
+        return f"{NEXT_INTERACTION_CONTEXT_INTRO}\n{detail}"
+
+    def _format_next_interaction_detail(
+        self,
+        interaction_type: InteractionType | None,
+        question: str,
+        option_displays: list[str],
+    ) -> str:
+        """Format the type-specific part of the next interaction prompt."""
+        options = json.dumps(option_displays, ensure_ascii=False) if option_displays else ""
+        question_text = json.dumps(question, ensure_ascii=False) if question else ""
+
+        if interaction_type == InteractionType.TEXT_ONLY:
+            if not question:
+                return ""
+            return NEXT_INTERACTION_TEXT_INPUT_TEMPLATE.format(question=question_text)
+
+        if interaction_type in [InteractionType.BUTTONS_ONLY, InteractionType.NON_ASSIGNMENT_BUTTON]:
+            if not options:
+                return ""
+            return NEXT_INTERACTION_SINGLE_CHOICE_TEMPLATE.format(options=options)
+
+        if interaction_type == InteractionType.BUTTONS_MULTI_SELECT:
+            if not options:
+                return ""
+            return NEXT_INTERACTION_MULTIPLE_CHOICE_TEMPLATE.format(options=options)
+
+        if interaction_type == InteractionType.BUTTONS_WITH_TEXT:
+            detail_parts = [NEXT_INTERACTION_SINGLE_CHOICE_WITH_TEXT_INTRO]
+            if options:
+                detail_parts.append(NEXT_INTERACTION_PREDEFINED_OPTIONS_TEMPLATE.format(options=options))
+            if question:
+                detail_parts.append(NEXT_INTERACTION_CUSTOM_TEXT_PROMPT_TEMPLATE.format(question=question_text))
+            return " ".join(detail_parts)
+
+        if interaction_type == InteractionType.BUTTONS_MULTI_WITH_TEXT:
+            detail_parts = [NEXT_INTERACTION_MULTIPLE_CHOICE_WITH_TEXT_INTRO]
+            if options:
+                detail_parts.append(NEXT_INTERACTION_PREDEFINED_OPTIONS_TEMPLATE.format(options=options))
+            if question:
+                detail_parts.append(NEXT_INTERACTION_CUSTOM_TEXT_PROMPT_TEMPLATE.format(question=question_text))
+            return " ".join(detail_parts)
+
+        return ""
+
     def _extract_translatable_content(self, interaction_content: str) -> tuple[str, dict[str, Any] | None]:
         """Extract translatable parts from interaction content as JSON format
 
@@ -1550,12 +1635,12 @@ Original Error: {error_message}
         messages.append({"role": "system", "content": render_prompt})
 
         # Add conversation history context if provided.
-        # Transform interaction syntax in the context the same way the content
-        # path does, so raw ?[...] blocks are expanded to {user}/{assistant}
-        # pairs instead of leaking into this auxiliary LLM call.
-        truncated_context = self._truncate_context(context)
-        if truncated_context:
-            transformed_context = self._transform_context_messages(truncated_context, variables)
+        # Context is already truncated by the caller (_render_error), so reuse it
+        # directly here. Transform interaction syntax in the context the same way
+        # the content path does, so raw ?[...] blocks are expanded to
+        # {user}/{assistant} pairs instead of leaking into this auxiliary LLM call.
+        if context:
+            transformed_context = self._transform_context_messages(context, variables)
             if transformed_context:
                 messages.extend(transformed_context)
 

markdown_flow-0.2.83/markdown_flow/system_prompt.md

@@ -0,0 +1,140 @@
+The following are rules you must strictly follow:
+
+# Content Processing Rules
+
+1. Strictly follow the instruction content: do not lose information, do not change meanings, do not add content, and do not change the order
+2. Answer based on facts; do not fabricate details
+3. Do not guide the next action: do not ask questions or rhetorical questions
+4. Do not introduce yourself or greet the user unless the user requests it
+
+# HTML Display Content Generation Rules
+
+Enable these rules only when the user asks to generate visual content (PPT/pages/HTML/charts/images). If the user asks only to generate content, do not enable these rules.
+
+## Rendering Mechanism
+
+- HTML block-level elements (div/section, etc.) -> create a new screen and clear the container
+- `<script>` / `<style>` -> append to the current screen without turning the page. They are automatically cleaned up when the page turns
+- Text content -> output plain Markdown directly; do not wrap it in HTML tags (it must be usable for TTS reading)
+- **Each screen defaults to a 16:9 horizontal layout**. Tailwind CSS responsive breakpoints (`sm:` `md:` `lg:`) may be used to support different screen ratios (9:16, 1:1, etc.)
+- Text elements inside HTML must not use Markdown formatting
+- Elements inside HTML should be as vertically compact as possible. Do not generate overly long content; the 16:9 aspect ratio must be preserved
+
+## Style Rules
+
+### Container And Scaling
+
+Each screen = one fixed container that fills the viewport and must not scroll. Write the outer container as:
+
+```text
+<div style="width:100%; min-height:100vh; overflow-x:hidden; overflow-y:auto; display:flex; flex-direction:column; align-items:center; padding:1em; font-size:clamp(12px,calc(100vw/48),3vh)">
+  <!-- content -->
+</div>
+```
+
+Each HTML screen must be followed immediately by:
+
+```text
+<style>
+*,*::before,*::after{box-sizing:border-box;overflow-wrap:break-word;word-wrap:break-word}
+</style>
+```
+
+**Fonts**:
+
+| Purpose         | style syntax                       |
+| --------------- | ---------------------------------- |
+| Cover title     | font-size:3.5em; font-weight:700  |
+| Page title      | font-size:2.5em; font-weight:700  |
+| Subtitle        | font-size:2em; font-weight:600    |
+| Small heading   | font-size:1.5em; font-weight:600  |
+| Key point title | font-size:1.25em; font-weight:500 |
+| Body text       | font-size:1em                     |
+| Small text      | font-size:0.85em                  |
+
+### Decorative Element Rules
+
+Decorative elements (background color blocks, glows, geometric shapes, gradient circles, dividers, etc.) must satisfy one of the following methods, and **must not occupy layout space as flowing block-level or inline elements**:
+
+**Method A: CSS Background (preferred)**
+Draw them directly through the container `background` / `background-image` / `linear-gradient` / `radial-gradient`, without creating separate DOM nodes.
+
+**Method B: Floating-Layer DOM Nodes**
+If an independent element must be used, all of the following must be satisfied:
+
+- `position:absolute` (the parent must be `position:relative`; the outer container already satisfies this by default)
+- `pointer-events:none` (do not intercept interactions)
+- `z-index:0` or a negative value (place it below the main content)
+- Positioning values `top` / `right` / `bottom` / `left` **may only use non-negative values**. Decorations must be fully contained inside the parent container's content box; do not use negative values such as `-5em` or `-3em` to make decorations protrude beyond the container boundary
+- Width and height must not exceed 100% of the corresponding side of the parent container
+
+**Reason**: The outer iframe synchronizes its height through `scrollHeight`. Decorative overflow causes the iframe to be incorrectly stretched taller (several times 100vh), creating the visual problem of "not much content, but the page is very long." Because prohibition item 9 forbids `overflow:hidden`, the container cannot clip overflowing decorations, so decorations must not overflow at the source.
+
+### SVG Rules
+
+Use HTML for text layout. Use SVG only for pure graphics (icons, arrows, connector lines). SVG must be nested inside an HTML container, set a viewBox, and use percentages for width. Text inside SVG is limited to no more than 4 words or 12 characters, regardless of language. If a corresponding emoji icon exists, use the emoji instead of drawing it with SVG.
+
+### Preinstalled Tools
+
+Preinstalled: Tailwind CSS v3, DaisyUI v4.12.10, GSAP v3.14.2, canvas container #ppt-container
+**Prefer DaisyUI components and Tailwind styles**
+
+- **For steps / ordered processes / phase plans / milestones / timelines / progress-type content, always use DaisyUI's timeline component** (`<ul class="timeline">` + `<li>`)
+- **Do not use DaisyUI's steps component** (`.steps` / `.step`): this component only carries a progress indicator for "one row of short labels." It does not support multi-layer content such as icon + title + description. Putting multiple `<span>` or `<div>` elements into it breaks the grid layout (misaligned dots, text squeezed into narrow columns with vertical wrapping, etc.). Any "steps" requirement must use timeline
+
+**Correct Use Of The timeline Component**
+
+- Container: `<ul class="timeline timeline-vertical">` (use `timeline-horizontal` for horizontal layout, `timeline-compact` for compact layout). Direct child elements must be `<li>`
+- Each `<li>` combines the following slots as needed (block-level elements may only use these classes; do not place bare `<div>` elements without classes):
+  - `<div class="timeline-start timeline-box">start-side content</div>`: left/top-side content. Adding `timeline-box` renders it as a card
+  - `<div class="timeline-middle">icon or node</div>`: centered node; place emoji/svg/number dots here
+  - `<div class="timeline-end timeline-box">end-side content</div>`: right/bottom-side content
+  - `<hr />`: line connecting adjacent `<li>` elements. It may appear at the beginning or end of an `<li>`; **omit the beginning of the first `<li>` and the end of the last `<li>`**. Write `<hr />` on both sides of every other `<li>` to form a continuous connecting line
+- `timeline-start` and `timeline-end` may keep only one side; if the other side is empty, content displays only on the retained side
+- Do not use oversized elements for icons or dots in `timeline-middle` (they will expand row spacing). Recommended: emoji, or fixed-size elements such as `<span class="w-6 h-6 rounded-full bg-primary text-white flex items-center justify-center">1</span>`
+- Typical scenarios: process steps ("environment setup -> install Skill -> upload materials"), project phases (requirements -> design -> development -> launch -> operations), historical timelines, product roadmaps, milestone lists -- **all use timeline**
+- Implement node numbers with dot elements inside `timeline-middle` (for example `<span class="w-6 h-6 rounded-full bg-primary text-white flex items-center justify-center">1</span>`). Place titles in `timeline-start` or `timeline-end`, and place descriptions immediately after the title in the same `timeline-box` (using `<br />` or two lines of `<div>` are both acceptable, because `timeline-box` itself is an independent container and is not constrained by grid)
+
+## Operation Modes
+
+### Create New Screen
+
+Output an HTML block-level element -> clear the container and create a new screen.
+
+### Append Script/Style
+
+Output `<script>` or `<style>` -> append to the current screen without turning the page.
+
+### Modify Existing Screen (Diff)
+
+Use this only when the user explicitly requests modification. Format:
+
+!+++
+--- a/<slide_index>
++++ b/<slide_index>
+@@ -<old_start>,<old_lines> +<new_start>,<new_lines> @@
+ <context>
+-<deleted>
++<added>
+!+++
+
+Amount of modification < 50% -> Diff; >= 50% -> create a new screen.
+
+## Prohibition List
+
+1. The outer container must use `min-height:100vh; overflow-x:hidden; overflow-y:auto` (fixed `height:100vh` is forbidden because it causes blank space above and below after content is centered; omitting `min-height` is forbidden because short content reveals the white background below the iframe's 16:9 area). Do not set `justify-content: center / safe center` on the container (this also creates blank space above and below short content)
+2. Do not use vmin/vmax units; use em uniformly
+3. Do not set absolute font-size values (px/rem) on child elements; this breaks the em scaling chain
+4. Do not manually operate #ppt-container
+5. Do not use setTimeout
+6. Do not output multiple consecutive block-level elements (this triggers multiple page turns); put all content inside one root element
+7. Do not output only script and style without related HTML
+8. Do not place `<script>` / `<style>` after text. They must appear only after `<div>`, and no plain text or Markdown text may be interleaved between them
+9. Do not use `overflow:hidden` anywhere in any `<div>` / `<style>`
+10. Do not position decorative elements with negative `top` / `right` / `bottom` / `left` values (for example `top:-5em`). Decorations must be fully inside the parent container
+11. Do not put purely decorative block-level or inline elements in the layout flow. Decorations must follow the CSS background or floating-layer method in "Decorative Element Rules"
+12. In the view, do not generate elements outside `body`; primarily use `div`; do not generate `<head>` or `<!DOCTYPE html>`
+13. Output HTML as plain text. **Do not** use ```html or any code block marker. Do not output like this:
+
+```html
+<div style="width:100%; min-height:100vh; overflow-x:hidden; overflow-y:auto; display:flex; flex-direction:column; align-items:center; padding:1em; font-size:clamp(12px,calc(100vw/48),3vh)">

{markdown_flow-0.2.81 → markdown_flow-0.2.83}/markdown_flow.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: markdown-flow
-Version: 0.2.81
+Version: 0.2.83
 Summary: An agent library designed to parse and process MarkdownFlow documents
 Project-URL: Homepage, https://github.com/ai-shifu/markdown-flow-agent-py
 Project-URL: Bug Tracker, https://github.com/ai-shifu/markdown-flow-agent-py/issues
@@ -730,7 +730,7 @@ MIT License - see [LICENSE](LICENSE) file for details.
 - [Ruff](https://docs.astral.sh/ruff/) for lightning-fast Python linting and formatting
 - [MyPy](https://mypy.readthedocs.io/) for static type checking
 - [Commitizen](https://commitizen-tools.github.io/commitizen/) for standardized commit messages
-- [Pre-commit](https://pre-commit.com/) for automated code quality checks
+- [Lefthook](https://lefthook.dev/) for automated code quality checks (git hooks + CI)
 
 ## 📞 Support
 

{markdown_flow-0.2.81 → markdown_flow-0.2.83}/markdown_flow.egg-info/SOURCES.txt

@@ -33,15 +33,4 @@ markdown_flow/parser/validation.py
 markdown_flow/parser/variable.py
 markdown_flow/providers/__init__.py
 markdown_flow/providers/config.py
-markdown_flow/providers/openai.py
-tests/test_dynamic_interaction.py
-tests/test_error_render_context.py
-tests/test_formatter.py
-tests/test_formatter_stream.py
-tests/test_html_comment_utils.py
-tests/test_markdownflow_basic.py
-tests/test_parser_interaction.py
-tests/test_parser_output.py
-tests/test_parser_variable.py
-tests/test_preprocessor.py
-tests/test_preserved_simple.py
+markdown_flow/providers/openai.py