slack-markdown-parser 2.0.2__tar.gz → 2.2.2__tar.gz

slack_markdown_parser-2.2.2/CHANGELOG.md

@@ -0,0 +1,69 @@
+# Changelog
+
+All notable changes to this project are documented in this file.
+
+The format is based on Keep a Changelog, and the project follows Semantic Versioning.
+
+## [Unreleased]
+
+## [2.2.2] - 2026-03-10
+
+### Added
+
+- Added Slack render-test tooling, generated regression fixtures, and maintainer docs for validating real Slack client rendering across Web, desktop, and mobile.
+
+### Changed
+
+- Refreshed the README and behavior spec to distinguish Slack renderer limitations from parser-owned normalization and repair behavior.
+- Clarified locale-aware formatting behavior and added public examples for the Slack render-test workflow.
+
+### Fixed
+
+- Stabilized nested inline-code emphasis rendering across English, Japanese, Chinese, and Korean contexts, including existing-ZWSP boundaries and CJK italic/strike cases.
+- Preserved user-authored spacing in fallback text while removing parser-inserted rendering-only padding.
+- Wrapped bare URLs into Slack-friendly autolink form before sending `markdown` blocks so adjacent lines no longer collapse into malformed angle-link text.
+
+## [2.2.1] - 2026-03-07
+
+### Changed
+
+- Normalized underscore emphasis (`_..._`, `__...__`) into Slack-compatible asterisk emphasis before table parsing.
+- Excluded fenced code blocks from table normalization and segment splitting so table-like rows inside code fences stay in `markdown` blocks.
+- Extended fenced-code preservation to tilde fences (`~~~ ... ~~~`) when inserting ZWSP.
+- Improved heading-plus-table rescue so inputs like `### Heading ... Header A | Header B` preserve multi-word first header cells more naturally.
+
+## [2.0.2] - 2026-03-06
+
+### Changed
+
+- Improved public API wording and refreshed the English and Japanese README files.
+- Clarified project scope for `mrkdwn`-only clients and fallback text behavior.
+- Refined validation samples and screenshots in the documentation.
+
+### Fixed
+
+- Improved ZWSP padding around punctuation-adjacent Markdown.
+- Expanded parser edge-case handling and related documentation.
+
+## [2.0.1] - 2026-03-05
+
+### Added
+
+- Added initial GitHub Actions coverage for tests and package builds.
+- Added OSS-facing documentation and a real rendering example in the README.
+
+### Changed
+
+- Trimmed the repository to the core distributable package and refreshed maintainer contact details.
+- Updated GitHub Actions dependencies to newer major versions.
+
+### Fixed
+
+- Added ZWSP padding for inline code markers when adjacent to surrounding text.
+
+## [2.0.0] - 2026-03-05
+
+### Added
+
+- Published the packaged OSS release of `slack-markdown-parser`.
+- Added packaging metadata, documentation, and review/reference materials for the open-source release.

slack_markdown_parser-2.2.2/CONTRIBUTING.md

@@ -0,0 +1,53 @@
+# Contributing
+
+Thanks for your interest in improving `slack-markdown-parser`.
+Small fixes, bug reports, documentation updates, and tests are all welcome.
+English and Japanese contributions are both welcome.
+
+## Development setup
+
+This project supports Python 3.10 through 3.13.
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+pip install -e ".[dev]"
+```
+
+## Local checks
+
+Run these commands before opening a pull request:
+
+```bash
+python -m pytest -q
+python -m ruff check .
+python -m black --check .
+python -m build
+```
+
+If you are changing Markdown parsing behavior, please add or update automated tests in `tests/`.
+
+## Pull requests
+
+- Keep changes focused and explain the user-facing impact.
+- Add or update tests when parser behavior changes.
+- Update `README.md`, `README-ja.md`, or `docs/spec*.md` when public behavior or examples change.
+- Conventional Commits are encouraged for commit messages, but not required for contributors.
+- Make sure CI passes before requesting review.
+
+## Reporting issues
+
+Use the GitHub issue templates when possible.
+Helpful reports usually include:
+
+- A short description of the problem
+- A minimal Markdown sample that reproduces it
+- Expected output and actual output
+- Python version and installation method
+- Slack rendering details if the issue is UI-specific
+
+## Release notes
+
+Project maintainers keep release history in `CHANGELOG.md`.
+If your pull request affects users, please include a short changelog note in the PR description.

slack_markdown_parser-2.2.2/MANIFEST.in

@@ -0,0 +1,10 @@
+include LICENSE
+include README.md
+include README-ja.md
+include CONTRIBUTING.md
+include CHANGELOG.md
+recursive-include docs *.md
+prune docs/_internal
+recursive-include tests *.py *.md
+recursive-include slack_markdown_parser py.typed
+global-exclude __pycache__ *.py[cod]

{slack_markdown_parser-2.0.2/slack_markdown_parser.egg-info → slack_markdown_parser-2.2.2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slack-markdown-parser
-Version: 2.0.2
+Version: 2.2.2
 Summary: Convert LLM Markdown into Slack Block Kit markdown/table messages
 Author: darkgaldragon
 License-Expression: MIT
@@ -48,17 +48,51 @@ This library leans on Slack Block Kit's `markdown` block for standard Markdown a
 | Problem | Approach |
 |---|---|
 | Conversion overhead | Send standard Markdown through Slack `markdown` blocks without rewriting it into `mrkdwn`. |
-| Formatting instability | Insert zero-width spaces (ZWSP, U+200B) around formatting tokens when needed so Slack parses inline styling more reliably without visible extra spaces. |
+| Formatting instability | Prefer zero-width spaces (ZWSP, U+200B) around formatting tokens, and fall back to locale-aware visible-space padding for CJK nested inline-code cases where Slack rendering still breaks. |
 | No table syntax in `mrkdwn` | Detect Markdown tables and convert them into Slack `table` blocks, including repair of common LLM-generated table inconsistencies. |
 
+The target is natural rendering on Slack, not full CommonMark or HTML fidelity.
+If Slack itself does not support a construct in `markdown` blocks, this library prefers safe plain-text rendering or explicit `table` blocks over aggressive rewrites into old `mrkdwn`.
+
 ## Features
 
 - Convert standard Markdown into Slack `markdown` blocks
 - Convert Markdown tables into Slack `table` blocks
 - Repair common LLM table issues such as missing outer pipes, missing separator rows, mismatched column counts, and empty cells
 - Split output into multiple Slack messages when needed to satisfy Slack's "one table per message" constraint
+- Sanitize ANSI/control characters and neutralize invalid Slack angle-bracket tokens before block generation
 - Add ZWSP around inline formatting tokens to reduce rendering issues outside fenced code blocks
-- Build fallback text for `chat.postMessage.text` from generated blocks
+- Use locale-aware visible-space padding for nested inline-code emphasis in dense Japanese, Chinese, and Korean text when Slack requires stronger boundaries than ZWSP alone
+- Support Markdown and Slack-style links inside table cells
+- Build fallback text for `chat.postMessage.text` from generated blocks, normalizing synthetic ZWSP and any parser-inserted visible-space padding used only for rendering stability
+- Accept raw LLM Markdown without tightly constraining the model prompt, using best-effort sanitize and table repair before Slack delivery
+
+## Observed Slack behavior
+
+The library is built around how Slack actually renders `markdown` and `table` blocks in practice.
+
+Reliable in current Slack rendering:
+
+- `**bold**`, `*italic*`, `~~strike~~`, inline code, and fenced code blocks
+- Bare URLs, autolinks, Markdown links, reference-style links, and mailto links
+- Bullet lists, ordered lists, task lists, and simple blockquotes
+- Explicit Slack `table` blocks generated from Markdown tables
+
+Known Slack-side limitations:
+
+- Heading syntax (`#`, setext headings) renders as plain text rather than true heading levels
+- Nested blockquotes are weak compared with full Markdown renderers
+- Horizontal rules render more like line text than semantic separators
+- Markdown image syntax does not become an embedded image in `markdown` blocks
+- Math, raw HTML, HTML comments, `<details>`, admonition syntax, and Mermaid are rendered as plain text or code, not as rich features
+
+What this library compensates for:
+
+- Normalizes underscore emphasis (`_..._`, `__...__`) into Slack-friendly asterisk emphasis
+- Wraps bare URLs into Slack-friendly autolink form before sending `markdown` blocks
+- Repairs malformed LLM-generated tables before converting them into Slack `table` blocks
+- Keeps table-like rows inside fenced code blocks out of table normalization
+- Neutralizes invalid Slack angle-bracket tokens such as raw HTML-like tags
 
 ## Requirements
 
@@ -75,8 +109,7 @@ pip install slack-markdown-parser
 
 ```python
 from slack_markdown_parser import (
-    build_fallback_text_from_blocks,
-    convert_markdown_to_slack_messages,
+    convert_markdown_to_slack_payloads,
 )
 
 markdown = """
@@ -88,11 +121,7 @@ markdown = """
 | UI | *In progress* |
 """
 
-for blocks in convert_markdown_to_slack_messages(markdown):
-    payload = {
-        "blocks": blocks,
-        "text": build_fallback_text_from_blocks(blocks) or "report",
-    }
+for payload in convert_markdown_to_slack_payloads(markdown):
     print(payload)
 ```
 
@@ -146,6 +175,7 @@ Example Slack bot rendering (`markdown` + `table` blocks):
 | Function | Description |
 |---|---|
 | `convert_markdown_to_slack_messages(markdown_text) -> list[list[dict]]` | Convert Markdown into Slack messages already split around table blocks. |
+| `convert_markdown_to_slack_payloads(markdown_text) -> list[dict]` | Convert Markdown into Slack-ready payloads with both `blocks` and fallback `text`. |
 | `convert_markdown_to_slack_blocks(markdown_text) -> list[dict]` | Convert Markdown into a flat Block Kit block list. |
 | `build_fallback_text_from_blocks(blocks) -> str` | Build fallback text suitable for `chat.postMessage.text`. |
 | `blocks_to_plain_text(blocks) -> str` | Convert blocks into plain text. |
@@ -157,6 +187,7 @@ Example Slack bot rendering (`markdown` + `table` blocks):
 | `normalize_markdown_tables(markdown_text) -> str` | Normalize Markdown table syntax before conversion. |
 | `add_zero_width_spaces_to_markdown(text) -> str` | Insert ZWSP around formatting tokens where Slack needs stronger boundaries. |
 | `decode_html_entities(text) -> str` | Decode HTML entities before parsing. |
+| `sanitize_slack_text(text) -> str` | Remove ANSI/control noise and neutralize invalid Slack angle-bracket tokens. |
 | `strip_zero_width_spaces(text) -> str` | Remove ZWSP (`U+200B`) and BOM (`U+FEFF`) while preserving join-control characters such as ZWJ. |
 
 ### Lower-level exported helpers
@@ -175,10 +206,22 @@ These are also part of the public package surface:
 
 - Behavior spec: [docs/spec.md](docs/spec.md)
 - Japanese behavior spec: [docs/spec-ja.md](docs/spec-ja.md)
+- Slack render-test workflow: [docs/slack-render-test-workflow.md](docs/slack-render-test-workflow.md)
+- Nested-modifier findings: [docs/slack-nested-modifier-findings.md](docs/slack-nested-modifier-findings.md)
+- Desktop/mobile manual checklist: [docs/slack-client-manual-checklist.md](docs/slack-client-manual-checklist.md)
 - Non-goals:
   - Generating Slack `mrkdwn` strings
   - Supporting clients or MCP tools that can only send `mrkdwn`
 
+## Contributing
+
+Contributions, bug reports, and documentation improvements are welcome.
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request.
+
+## Changelog
+
+Version history is maintained in [CHANGELOG.md](CHANGELOG.md).
+
 ## Contact
 
 - GitHub Issues / Pull Requests

slack_markdown_parser-2.2.2/README-ja.md

@@ -0,0 +1,189 @@
+# slack-markdown-parser
+
+LLM が生成する標準的な Markdown を Slack Block Kit（`markdown` + `table` ブロック）に変換する Python ライブラリです。
+
+## 背景
+
+Slack で AI BOT を運用する場合、従来は Slack 独自の `mrkdwn` 形式に変換していましたが、以下の課題がありました。
+
+- **変換コスト**: LLM は標準 Markdown を出力するため、`mrkdwn` に合わせる変換ロジックやプロンプト制御が必要
+- **装飾崩れ**: 日本語のように語間スペースがない文では、`mrkdwn` の装飾記号（`*`, `~` など）が正しくレンダリングされず記号がそのまま露出することがあり、ロジックやプロンプトでの制御も難しい
+- **テーブル非対応**: `mrkdwn` にはテーブル構文がなく、リストへ変換するなどの代替処理が必要
+
+## 設計方針
+
+Slack Block Kit の `markdown` ブロック（標準 Markdown 構文をそのまま受け付ける）と `table` ブロックを活用し、上記の課題を解消します。
+
+| 課題 | 解決手段 |
+|---|---|
+| 変換コスト | `markdown` ブロックが標準 Markdown をそのまま受け付けるため、LLM 出力を変換せず利用可能 |
+| 装飾崩れ | 基本は ZWSP（ゼロ幅スペース U+200B）で装飾境界を補強し、CJK の密着文脈でインラインコードを内包する装飾が崩れる場合のみ、言語別ルールで可視スペースも使ってレンダリングを安定化する |
+| テーブル非対応 | Markdown テーブルを検知して `table` ブロックに変換。LLM の出力する多様なテーブル記法の揺れも自動補完し `invalid_blocks` エラーを回避 |
+
+このライブラリの目標は、CommonMark や HTML を完全再現することではなく、Slack 上で自然に読める表示を作ることです。
+Slack の `markdown` ブロック自体が対応していない構文は、古い `mrkdwn` へ無理に書き換えるより、安全なプレーンテキスト表示や `table` ブロック化を優先します。
+
+## 主な機能
+
+- 標準 Markdown テキストを `markdown` ブロックに変換
+- Markdown テーブルを `table` ブロックに変換（セル内の太字・斜体・取消線・インラインコードを認識）
+- LLM が生成する多様な Markdown テーブルで起こり得る記法の揺れ（外枠パイプ不足、セパレータ行不足、列数不一致、空セル）を検知し自動補完。Slack `table` ブロックの `invalid_blocks` エラーを未然に回避
+- テーブルごとにメッセージを自動分割（Slack の「1メッセージ1テーブル」制約に対応）
+- ANSI escape / 制御文字を除去し、不正な Slack 角括弧トークンを自動で無害化
+- 装飾記号の前後に ZWSP を付与して表示崩れを抑制（フェンスドコードブロック内は除外、インラインコードは付与対象）
+- 日本語・中国語・韓国語の密着文脈で、インラインコードを内包する装飾には可視スペースを補って Slack 表示を安定化
+- テーブルセル内の Markdown link / Slack link を認識
+- `chat.postMessage.text` 用の fallback テキストを生成（表示安定化のために入れた ZWSP や人工的な可視スペースは通知文では自然な形に正規化）
+- モデル側で Markdown を厳密に制御しなくてもよいよう、Slack 送信前にベストエフォートでサニタイズとテーブル補完を行う
+
+## 実測ベースの Slack 挙動
+
+本ライブラリは、Slack の `markdown` / `table` ブロックが実際にどう見えるかを前提に設計しています。
+
+現在の Slack で安定して表示されるもの:
+
+- `**bold**`, `*italic*`, `~~strike~~`, インラインコード, フェンスドコード
+- bare URL, autolink, Markdown link, 参照リンク, mailto link
+- 箇条書き, 番号付きリスト, タスクリスト, 単純な引用
+- Markdown テーブルを変換した明示的な Slack `table` ブロック
+
+Slack 側の制約として残るもの:
+
+- `#` 見出しや setext 見出しは、真の見出しレベルではなくプレーンテキスト寄りに表示される
+- 多段引用はフル Markdown レンダラほどきれいに出ない
+- 水平線は semantic な区切りではなく線テキスト寄りに見える
+- Markdown 画像記法は `markdown` ブロック内では埋め込み画像にならない
+- 数式, 生 HTML, HTML comment, `<details>`, admonition 記法, Mermaid はリッチ機能としては扱われず、テキストまたはコードとして表示される
+
+本ライブラリが吸収するもの:
+
+- underscore 装飾 (`_..._`, `__...__`) を Slack 互換の asterisk 装飾へ正規化
+- bare URL を Slack の `markdown` ブロックで安定する autolink 形式へ正規化
+- LLM が崩したテーブル記法を補完して Slack `table` ブロックへ変換
+- フェンスドコード内の table 風行をテーブル正規化対象から除外
+- 生 HTML 風タグなど、不正な Slack angle token を無害化
+
+## 利用前提
+
+- Slack Block Kit の `blocks` で `markdown` / `table` ブロックを送信できる実装が必要です。
+- `text` / `mrkdwn` のみ送信可能な経路（例: 一部の Slack MCP ツール）では利用できません。
+
+## インストール
+
+```bash
+pip install slack-markdown-parser
+```
+
+## 最小利用例
+
+```python
+from slack_markdown_parser import (
+    convert_markdown_to_slack_payloads,
+)
+
+markdown = """
+# Weekly Report
+
+| Team | Status |
+|---|---|
+| API | **On track** |
+| UI | *In progress* |
+"""
+
+for payload in convert_markdown_to_slack_payloads(markdown):
+    print(payload)
+```
+
+`convert_markdown_to_slack_messages` は、複数テーブルを含む入力を Slack 制約に合わせて複数メッセージへ分割します。
+
+## 入出力イメージ
+
+検証テキスト:
+
+````markdown
+# 週次プロダクト更新
+
+今週は**検索速度改善**と*UI調整*を進めました。旧仕様は~~廃止予定~~です。
+詳細ログIDは`run-20260305-02`です。
+参考: https://example.com/changelog
+
+- APIの**レスポンス改善**
+  - *キャッシュヒット率*を改善
+  - タイムアウト設定を調整
+- バッチ処理の安定化
+  - リトライ回数を統一
+- ドキュメント更新
+
+カテゴリ | 状況 | 担当
+API | **進行中** | Team A
+UI | *確認中* | Team B
+QA | ~~保留~~ | Team C
+
+> 注意: 本番反映は 3/8 10:00 JST を予定
+
+1. リリースノート最終確認
+   1. 変更点の表記統一
+   2. 影響範囲の追記
+2. 監視アラートしきい値調整
+   1. `warning`閾値の更新
+3. QA再確認
+
+```bash
+./deploy.sh production
+```
+````
+
+実際のSlack BOTでの表示例（`markdown` + `table` ブロック）:
+
+![Slack BOT rendering example](Example_ja.png)
+
+## ライブラリの公開インターフェース
+
+### メイン関数（公開関数）
+
+| 関数 | 説明 |
+|---|---|
+| `convert_markdown_to_slack_messages(markdown_text) → list[list[dict]]` | Markdown をテーブル分割済みのメッセージ群に変換（主要エントリポイント） |
+| `convert_markdown_to_slack_payloads(markdown_text) → list[dict]` | `blocks` と fallback `text` を含む Slack 送信用 payload 群へ変換 |
+| `convert_markdown_to_slack_blocks(markdown_text) → list[dict]` | Markdown を Block Kit ブロックのリストに変換 |
+| `build_fallback_text_from_blocks(blocks) → str` | ブロックから `chat.postMessage.text` 用 fallback テキストを生成 |
+| `blocks_to_plain_text(blocks) → str` | ブロックからプレーンテキストを生成 |
+
+### ユーティリティ関数（公開関数）
+
+| 関数 | 説明 |
+|---|---|
+| `normalize_markdown_tables(markdown_text) → str` | テーブル記法を正規化（パイプ補完、セパレータ生成、列数調整） |
+| `add_zero_width_spaces_to_markdown(text) → str` | 装飾記号の前後に ZWSP を挿入（フェンスドコードブロック内は除外） |
+| `decode_html_entities(text) → str` | HTML エンティティをデコード |
+| `sanitize_slack_text(text) → str` | ANSI / 制御文字を除去し、不正な Slack 角括弧トークンを無害化 |
+| `strip_zero_width_spaces(text) → str` | ZWSP (U+200B) と BOM (U+FEFF) を除去（ZWJ 等の結合制御文字は保持） |
+
+## 仕様
+
+- 挙動仕様: [docs/spec-ja.md](docs/spec-ja.md)
+- 英語仕様: [docs/spec.md](docs/spec.md)
+- Slack 実レンダリング検証手順: [docs/slack-render-test-workflow.md](docs/slack-render-test-workflow.md)
+- nested modifier 実測メモ: [docs/slack-nested-modifier-findings.md](docs/slack-nested-modifier-findings.md)
+- Desktop / mobile 手動確認: [docs/slack-client-manual-checklist.md](docs/slack-client-manual-checklist.md)
+- 非対応:
+  - `mrkdwn` 文字列の生成
+  - `mrkdwn` のみ送信可能なクライアント／MCP ツール
+
+## コントリビュート
+
+不具合報告、ドキュメント改善、コードの提案を歓迎します。
+Issue / Pull Request を作成する前に [CONTRIBUTING.md](CONTRIBUTING.md) を参照してください。
+
+## 変更履歴
+
+リリース履歴は [CHANGELOG.md](CHANGELOG.md) で管理しています。
+
+## 連絡先
+
+- GitHub Issue / Pull Request
+- X: [@darkgaldragon](https://x.com/darkgaldragon)
+
+## ライセンス
+
+MIT

{slack_markdown_parser-2.0.2 → slack_markdown_parser-2.2.2}/README.md

@@ -17,17 +17,51 @@ This library leans on Slack Block Kit's `markdown` block for standard Markdown a
 | Problem | Approach |
 |---|---|
 | Conversion overhead | Send standard Markdown through Slack `markdown` blocks without rewriting it into `mrkdwn`. |
-| Formatting instability | Insert zero-width spaces (ZWSP, U+200B) around formatting tokens when needed so Slack parses inline styling more reliably without visible extra spaces. |
+| Formatting instability | Prefer zero-width spaces (ZWSP, U+200B) around formatting tokens, and fall back to locale-aware visible-space padding for CJK nested inline-code cases where Slack rendering still breaks. |
 | No table syntax in `mrkdwn` | Detect Markdown tables and convert them into Slack `table` blocks, including repair of common LLM-generated table inconsistencies. |
 
+The target is natural rendering on Slack, not full CommonMark or HTML fidelity.
+If Slack itself does not support a construct in `markdown` blocks, this library prefers safe plain-text rendering or explicit `table` blocks over aggressive rewrites into old `mrkdwn`.
+
 ## Features
 
 - Convert standard Markdown into Slack `markdown` blocks
 - Convert Markdown tables into Slack `table` blocks
 - Repair common LLM table issues such as missing outer pipes, missing separator rows, mismatched column counts, and empty cells
 - Split output into multiple Slack messages when needed to satisfy Slack's "one table per message" constraint
+- Sanitize ANSI/control characters and neutralize invalid Slack angle-bracket tokens before block generation
 - Add ZWSP around inline formatting tokens to reduce rendering issues outside fenced code blocks
-- Build fallback text for `chat.postMessage.text` from generated blocks
+- Use locale-aware visible-space padding for nested inline-code emphasis in dense Japanese, Chinese, and Korean text when Slack requires stronger boundaries than ZWSP alone
+- Support Markdown and Slack-style links inside table cells
+- Build fallback text for `chat.postMessage.text` from generated blocks, normalizing synthetic ZWSP and any parser-inserted visible-space padding used only for rendering stability
+- Accept raw LLM Markdown without tightly constraining the model prompt, using best-effort sanitize and table repair before Slack delivery
+
+## Observed Slack behavior
+
+The library is built around how Slack actually renders `markdown` and `table` blocks in practice.
+
+Reliable in current Slack rendering:
+
+- `**bold**`, `*italic*`, `~~strike~~`, inline code, and fenced code blocks
+- Bare URLs, autolinks, Markdown links, reference-style links, and mailto links
+- Bullet lists, ordered lists, task lists, and simple blockquotes
+- Explicit Slack `table` blocks generated from Markdown tables
+
+Known Slack-side limitations:
+
+- Heading syntax (`#`, setext headings) renders as plain text rather than true heading levels
+- Nested blockquotes are weak compared with full Markdown renderers
+- Horizontal rules render more like line text than semantic separators
+- Markdown image syntax does not become an embedded image in `markdown` blocks
+- Math, raw HTML, HTML comments, `<details>`, admonition syntax, and Mermaid are rendered as plain text or code, not as rich features
+
+What this library compensates for:
+
+- Normalizes underscore emphasis (`_..._`, `__...__`) into Slack-friendly asterisk emphasis
+- Wraps bare URLs into Slack-friendly autolink form before sending `markdown` blocks
+- Repairs malformed LLM-generated tables before converting them into Slack `table` blocks
+- Keeps table-like rows inside fenced code blocks out of table normalization
+- Neutralizes invalid Slack angle-bracket tokens such as raw HTML-like tags
 
 ## Requirements
 
@@ -44,8 +78,7 @@ pip install slack-markdown-parser
 
 ```python
 from slack_markdown_parser import (
-    build_fallback_text_from_blocks,
-    convert_markdown_to_slack_messages,
+    convert_markdown_to_slack_payloads,
 )
 
 markdown = """
@@ -57,11 +90,7 @@ markdown = """
 | UI | *In progress* |
 """
 
-for blocks in convert_markdown_to_slack_messages(markdown):
-    payload = {
-        "blocks": blocks,
-        "text": build_fallback_text_from_blocks(blocks) or "report",
-    }
+for payload in convert_markdown_to_slack_payloads(markdown):
     print(payload)
 ```
 
@@ -115,6 +144,7 @@ Example Slack bot rendering (`markdown` + `table` blocks):
 | Function | Description |
 |---|---|
 | `convert_markdown_to_slack_messages(markdown_text) -> list[list[dict]]` | Convert Markdown into Slack messages already split around table blocks. |
+| `convert_markdown_to_slack_payloads(markdown_text) -> list[dict]` | Convert Markdown into Slack-ready payloads with both `blocks` and fallback `text`. |
 | `convert_markdown_to_slack_blocks(markdown_text) -> list[dict]` | Convert Markdown into a flat Block Kit block list. |
 | `build_fallback_text_from_blocks(blocks) -> str` | Build fallback text suitable for `chat.postMessage.text`. |
 | `blocks_to_plain_text(blocks) -> str` | Convert blocks into plain text. |
@@ -126,6 +156,7 @@ Example Slack bot rendering (`markdown` + `table` blocks):
 | `normalize_markdown_tables(markdown_text) -> str` | Normalize Markdown table syntax before conversion. |
 | `add_zero_width_spaces_to_markdown(text) -> str` | Insert ZWSP around formatting tokens where Slack needs stronger boundaries. |
 | `decode_html_entities(text) -> str` | Decode HTML entities before parsing. |
+| `sanitize_slack_text(text) -> str` | Remove ANSI/control noise and neutralize invalid Slack angle-bracket tokens. |
 | `strip_zero_width_spaces(text) -> str` | Remove ZWSP (`U+200B`) and BOM (`U+FEFF`) while preserving join-control characters such as ZWJ. |
 
 ### Lower-level exported helpers
@@ -144,10 +175,22 @@ These are also part of the public package surface:
 
 - Behavior spec: [docs/spec.md](docs/spec.md)
 - Japanese behavior spec: [docs/spec-ja.md](docs/spec-ja.md)
+- Slack render-test workflow: [docs/slack-render-test-workflow.md](docs/slack-render-test-workflow.md)
+- Nested-modifier findings: [docs/slack-nested-modifier-findings.md](docs/slack-nested-modifier-findings.md)
+- Desktop/mobile manual checklist: [docs/slack-client-manual-checklist.md](docs/slack-client-manual-checklist.md)
 - Non-goals:
   - Generating Slack `mrkdwn` strings
   - Supporting clients or MCP tools that can only send `mrkdwn`
 
+## Contributing
+
+Contributions, bug reports, and documentation improvements are welcome.
+Please read [CONTRIBUTING.md](CONTRIBUTING.md) before opening an issue or pull request.
+
+## Changelog
+
+Version history is maintained in [CHANGELOG.md](CHANGELOG.md).
+
 ## Contact
 
 - GitHub Issues / Pull Requests

slack_markdown_parser-2.2.2/docs/slack-client-manual-checklist.md

@@ -0,0 +1,53 @@
+# Slack Client Manual Checklist
+
+Use this for quick smoke checks in Slack Desktop and mobile after parser changes.
+
+## How to run
+
+1. Open the link for each case in Slack Desktop or mobile.
+2. Confirm the expected visible text and formatting.
+3. Mark `PASS` only if all checks below hold.
+
+## Pass criteria
+
+- Outer emphasis is rendered for the whole target span.
+- Inline code remains monospace.
+- Raw markers such as `**`, `*`, or `~~` are not visible.
+- English cases do not show extra visible spaces before punctuation.
+- Japanese/Chinese/Korean nested-code cases may show visible spaces around the emphasized span when needed; that is expected.
+
+## Cases
+
+- `manual_en`
+  Expected: `Frontend (App.tsx)` is bold, `App.tsx` is code, no extra space before `:`
+  Link: paste your `manual_en` permalink here
+
+- `manual_ja`
+  Expected: `フロントエンド (App.tsx)` is bold, `App.tsx` is code, visible spaces around the bold span are acceptable
+  Link: paste your `manual_ja` permalink here
+
+- `manual_zh`
+  Expected: `外侧(内侧)` span is bold, inner code remains code, visible spaces around the bold span are acceptable
+  Link: paste your `manual_zh` permalink here
+
+- `manual_ko`
+  Expected: `바깥(내부)강조` span is bold, inner code remains code, trailing visible space before `입니다.` is acceptable
+  Link: paste your `manual_ko` permalink here
+
+- `manual_mix_ja_en`
+  Expected: `Frontend (App.tsx)` is bold inside Japanese text, `App.tsx` is code
+  Link: paste your `manual_mix_ja_en` permalink here
+
+- `manual_mix_ko_en`
+  Expected: `Frontend (App.tsx)` is bold inside Korean text, `App.tsx` is code
+  Link: paste your `manual_mix_ko_en` permalink here
+
+- `manual_mix_en_ja`
+  Expected: `機能A (ID-1)` is bold inside English text, `ID-1` is code, no extra visible spaces are introduced
+  Link: paste your `manual_mix_en_ja` permalink here
+
+## Recording
+
+- `PASS`: rendering matches the expectation above
+- `FAIL`: capture which marker leaked or which style was missing
+- If Desktop and mobile differ, record the client and version separately

slack_markdown_parser-2.2.2/docs/slack-nested-modifier-findings.md

@@ -0,0 +1,59 @@
+# Slack Nested Modifier Findings
+
+Observed on Slack Web against `#bot-test` on 2026-03-09.
+
+## Variants
+
+- `plain`: inner content without surrounding punctuation
+- `parens`: inner content wrapped in parentheses
+- `quotes`: inner content wrapped in quotes
+
+## Source fixtures
+
+- `tests/fixtures/slack_nested_modifier_matrix.md`
+- `tests/fixtures/slack_nested_modifier_matrix_parens.md`
+- `tests/fixtures/slack_nested_modifier_matrix_quotes.md`
+- `tests/fixtures/slack_cjk_inner_code_matrix.md`
+
+## Note on private artifacts
+
+The concrete Slack permalinks used during validation are intentionally omitted from the public repository. Re-run the workflow in `docs/slack-render-test-workflow.md` inside your own workspace if you want message-level links for manual verification.
+
+## Shared result before locale-aware fallback
+
+Before the locale-aware visible-space fallback was introduced, all three content variants produced the same high-level outcome:
+
+- English boundaries succeeded in `raw` and `parser`
+- Japanese `spaces_both` succeeded in `raw` and `parser`
+- Japanese `outer_zwsp` succeeded in `raw` and `parser`
+- Japanese `tight`, `space_left`, and `space_right` failed in `raw`
+- `parser` improved those Japanese boundary buckets from `0/5` to `4/5`
+- The remaining failures were concentrated in `inner_code`
+
+## Focused CJK result
+
+Fixture:
+
+- `tests/fixtures/slack_cjk_inner_code_matrix.md`
+
+This focused matrix contained `ja`, `zh`, and `ko`, testing only:
+
+- inner `plain`
+- inner `code`
+
+Boundary behavior after improvement:
+
+- `ja`, `zh`, and `ko` all still succeeded for `outer_zwsp`
+- `ja`, `zh`, and `ko` all still succeeded for `spaces_both`
+- raw `tight` and raw `space_left` remained fragile across all three locales
+- raw `space_right` remained fragile for `ja` and `zh`, but was already stable for `ko`
+- after the locale-aware fallback, `parser` reached `2/2` success in every tested bucket for `ja`, `zh`, and `ko`
+
+Current takeaway:
+
+- Treating Chinese like Japanese is reasonable based on current Slack Web behavior.
+- Korean still differs at the raw-rendering level, but the parser can now normalize all tested Korean buckets successfully with a lighter right-side spacing rule.
+- The current parser strategy for nested inline code is:
+  - `ja` / `zh`: add visible spaces on whichever outer side is missing
+  - `ko`: ensure a visible trailing space when needed
+  - English-like boundaries: preserve the original outer formatting span