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

slack_markdown_parser-2.2.1/CHANGELOG.md

@@ -0,0 +1,62 @@
+# 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]
+
+### Added
+
+- Added a contributor guide, issue templates, and a pull request template.
+- Added the `py.typed` marker and packaging rules for docs and tests in source distributions.
+
+### Changed
+
+- CI now runs the test suite on Python 3.10, 3.11, 3.12, and 3.13.
+- `.gitignore` no longer ignores the entire `tests/` directory, so new tests and sample fixtures can be tracked.
+
+## [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.1/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.1/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.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: slack-markdown-parser
-Version: 2.0.2
+Version: 2.2.1
 Summary: Convert LLM Markdown into Slack Block Kit markdown/table messages
 Author: darkgaldragon
 License-Expression: MIT
@@ -57,8 +57,11 @@ This library leans on Slack Block Kit's `markdown` block for standard Markdown a
 - 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
+- Support Markdown and Slack-style links inside table cells
 - Build fallback text for `chat.postMessage.text` from generated blocks
+- Accept raw LLM Markdown without tightly constraining the model prompt, using best-effort sanitize and table repair before Slack delivery
 
 ## Requirements
 
@@ -75,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 = """
@@ -88,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)
 ```
 
@@ -146,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. |
@@ -157,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
@@ -179,6 +179,15 @@ These are also part of the public package surface:
   - 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.1/README-ja.md

@@ -0,0 +1,154 @@
+# 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）を自動挿入してレンダリングを安定化。通常の半角スペースではなくゼロ幅スペースを使うことで、見た目上の不自然な空白を生じさせずに Slack の装飾解析を補助する |
+| テーブル非対応 | Markdown テーブルを検知して `table` ブロックに変換。LLM の出力する多様なテーブル記法の揺れも自動補完し `invalid_blocks` エラーを回避 |
+
+## 主な機能
+
+- 標準 Markdown テキストを `markdown` ブロックに変換
+- Markdown テーブルを `table` ブロックに変換（セル内の太字・斜体・取消線・インラインコードを認識）
+- LLM が生成する多様な Markdown テーブルで起こり得る記法の揺れ（外枠パイプ不足、セパレータ行不足、列数不一致、空セル）を検知し自動補完。Slack `table` ブロックの `invalid_blocks` エラーを未然に回避
+- テーブルごとにメッセージを自動分割（Slack の「1メッセージ1テーブル」制約に対応）
+- ANSI escape / 制御文字を除去し、不正な Slack 角括弧トークンを自動で無害化
+- 装飾記号の前後に ZWSP を付与して表示崩れを抑制（フェンスドコードブロック内は除外、インラインコードは付与対象）
+- テーブルセル内の Markdown link / Slack link を認識
+- `chat.postMessage.text` 用の fallback テキストを生成（ブロック内容をプレーンテキスト化して通知プレビュー等に利用）
+- モデル側で Markdown を厳密に制御しなくてもよいよう、Slack 送信前にベストエフォートでサニタイズとテーブル補完を行う
+
+## 利用前提
+
+- 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)
+- 非対応:
+  - `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.1}/README.md

@@ -26,8 +26,11 @@ This library leans on Slack Block Kit's `markdown` block for standard Markdown a
 - 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
+- Support Markdown and Slack-style links inside table cells
 - Build fallback text for `chat.postMessage.text` from generated blocks
+- Accept raw LLM Markdown without tightly constraining the model prompt, using best-effort sanitize and table repair before Slack delivery
 
 ## Requirements
 
@@ -44,8 +47,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 +59,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 +113,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 +125,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
@@ -148,6 +148,15 @@ These are also part of the public package surface:
   - 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.1/docs/spec-ja.md

@@ -0,0 +1,160 @@
+# パーサー挙動仕様
+
+このドキュメントは `slack-markdown-parser` の変換挙動を定義します。
+
+## 入力
+
+- UTF-8 の Markdown 文字列
+- 不正形テーブル、HTML エンティティ、プレーンテキスト混在を許容
+
+## 出力
+
+- Slack Block Kit ブロック（`markdown` / `table`）
+- 複数テーブル入力時は「1メッセージ1テーブル」を満たすメッセージ群
+
+## 変換パイプライン
+
+`convert_markdown_to_slack_blocks` の処理順序:
+
+1. **HTML エンティティデコード** — `>`, `&` 等を元の文字に復元
+2. **Slack 向けサニタイズ** — ANSI / 制御文字を除去し、不正な Slack 角括弧トークンを無害化
+3. **underscore 装飾正規化** — `_..._` / `__...__` を Slack 互換の `*...*` / `**...**` に変換
+4. **テーブル正規化** — 後述のルールで不正形テーブルを補完
+5. **セグメント分割** — テーブル領域（`|...|` 行の連続）と非テーブル領域に分割
+6. **ブロック生成** — セグメント種別ごとに処理:
+   - テーブル領域 → セル装飾を解析し `table` ブロックを生成。変換に失敗した場合（テーブル候補行が2行未満、パース結果が空など）は `markdown` ブロックにフォールバック
+   - 非テーブル領域 → ZWSP を付与して `markdown` ブロックを生成
+
+`convert_markdown_to_slack_messages` は上記の結果を「1メッセージ1テーブル」制約に沿って分割します。
+`convert_markdown_to_slack_payloads` は、同じ分割結果に `chat.postMessage.text` 用 fallback を付けた payload 群を返します。
+
+## Slack 向けサニタイズルール
+
+`sanitize_slack_text` の挙動:
+
+- ANSI escape を除去する
+- 一般的な制御文字を除去する
+- 有効な Slack 角括弧トークンは保持する
+  - 例: リンク、メンション、チャンネル参照、`<!here>`、`<!subteam^...>`、`<!date^...>`
+- Slack の特殊記法として解釈できない `<foo>` のようなトークンは `＜foo＞` に変換して無害化する
+- これには `<div>` や `<span>` のような生 HTML 風タグも含まれ、Slack 特殊記法として解釈されないよう自動で無害化する
+
+## underscore 装飾正規化ルール
+
+`normalize_underscore_emphasis` の挙動:
+
+- `_text_` を `*text*` に変換する
+- `__text__` を `**text**` に変換する
+- 変換対象は ASCII 英数字の単語境界に埋まっていない装飾用途の underscore に限定する
+- `snake_case` のような識別子は保持する
+- `\_escaped\_` は保持する
+- bare URL、Markdown リンク、Slack angle token、インラインコード内の underscore は保持する
+- フェンスドコードブロック（`` ``` `` / `~~~`）内の underscore は保持する
+
+## テーブル正規化ルール
+
+LLM は外枠パイプの省略、セパレータ行の欠落、列数の不一致など多様なテーブル記法を生成します。これらをそのまま Slack `table` ブロックに渡すと `invalid_blocks` エラーになるため、`normalize_markdown_tables` で事前に補完します。
+
+### テーブル候補の判定
+
+- 連続する `|` 含有行を候補としてバッファリング
+- 以下のいずれかで「テーブル」と判定:
+  - セパレータ行（`|---|---|` 形式）を含む
+  - 2行以上のデータ行があり、列数が一致または差が1以内で、最大列数が2以上
+
+### 正規化処理
+
+- 外枠パイプが欠けている行は `|...|` 形式に補完
+- セパレータ行が欠けていればヘッダ直後に自動生成
+- 各行の列数はヘッダ幅に合わせて不足分を空セルで補完、超過分を切り詰め
+- 空セルは `table` ブロック生成時に `-` に置換
+- `# 見出し |a|b|` 形式は見出し行とテーブル行に分離（見出し内のインラインコードに含まれるパイプは無視）
+- `### Heading ... Header A | Header B` のように見出しと表ヘッダが1行に潰れている場合、次行の列形状を手がかりに first header cell を推定する
+- フェンスドコードブロック（`` ``` `` / `~~~`）内の行はテーブル候補として扱わない
+
+### セル内パイプの保持
+
+- Slack リンク `<url|text>` 内のパイプはセル区切りとして扱わない
+- インラインコード `` `...` `` 内のパイプもセル区切りとして扱わない
+- エスケープされたパイプ `\|` はセル区切りとして扱わず、表示時にバックスラッシュを除去して `|` として出力
+
+## テーブルセル装飾
+
+セル内で次のインライン装飾を認識し、Slack `rich_text` 要素のスタイルに変換:
+
+| 記法 | スタイル |
+|---|---|
+| `**text**` | bold |
+| `*text*` | italic |
+| `~~text~~` | strike |
+| `` `text` `` | code |
+
+複数装飾のネストはプレーンテキストとして保持します。
+
+加えて、セル内では次のリンク記法を認識します。
+
+| 記法 | 出力 |
+|---|---|
+| `[label](https://example.com)` | Slack rich-text link |
+| `<https://example.com|label>` | Slack rich-text link |
+| `<https://example.com>` | Slack rich-text link |
+
+## ZWSP（ゼロ幅スペース）付与ルール
+
+`add_zero_width_spaces_to_markdown` の挙動:
+
+### 目的
+
+日本語等の語間スペースがない文で装飾記号が隣接文字と結合し、Slack のレンダリングが崩れる問題を回避します。通常の半角スペースではなくゼロ幅スペースを使うことで、見た目上の不自然な空白を生じさせずに Slack の装飾解析を補助します。
+
+### 対象パターン
+
+以下の装飾記号について、前後のどちらか一方でも隣接文字がスペース・タブ・改行・ZWSP でない場合、または行頭・行末に接している場合、装飾トークン全体を ZWSP（U+200B）で囲って Slack に独立した境界として認識させる:
+
+- `` `code` `` — インラインコード
+- `**bold**` — 太字
+- `*italic*` — 斜体
+- `~~strike~~` — 取消線
+
+### 除外範囲
+
+- **フェンスドコードブロック**（`` ``` ... ``` `` および `~~~ ... ~~~`）内は一切変更しない
+- インラインコード（`` `...` ``）は除外**しない**（付与対象）
+
+## ZWSP 除去ルール
+
+`strip_zero_width_spaces` はテーブルセル生成時および fallback テキスト生成時に呼ばれ、本ライブラリが挿入した制御文字を除去します。
+
+### 除去対象
+
+| コードポイント | 名称 | 除去理由 |
+|---|---|---|
+| U+200B | ZWSP（ゼロ幅スペース） | 本ライブラリが装飾安定化のために挿入したもの |
+| U+FEFF | BOM（バイト順マーク） | エンコーディング由来の不要な制御文字 |
+
+### 除去しない文字
+
+| コードポイント | 名称 | 保持理由 |
+|---|---|---|
+| U+200C | ZWNJ（ゼロ幅非接合子） | ペルシャ語・ヒンディー語等の語形制御に使用 |
+| U+200D | ZWJ（ゼロ幅接合子） | 結合絵文字（👨‍💻 = 👨+ZWJ+💻）の接着剤として使用。除去すると絵文字が分解される |
+
+## fallback テキスト
+
+`build_fallback_text_from_blocks` は `chat.postMessage.text` に設定する通知プレビュー用テキストを生成:
+
+- `markdown` ブロック → ZWSP を除去したテキスト
+- `table` ブロック → 各行のセルテキストを ` | ` で連結
+- 各ブロックの出力を空行で区切って結合
+
+テーブルセル内リンクの fallback テキストは、ラベルがあればラベル、なければ URL を使います。
+
+## 決定性
+
+同一入力に対して、環境差分に依存せず常に同一の出力を返します。
+
+## 非ゴール
+
+- `mrkdwn` 文字列の生成
+- 完全な Markdown AST の再現
+- HTML レンダリング互換