feedscope 0.1.0__py3-none-any.whl

feedscope/ui/screens/source_setup.py

@@ -0,0 +1,217 @@
+"""源选择弹层：首启引导 + 日常源管理（F2）。
+
+两屏同一套 SelectionList 勾选交互（空格切换）：确认返回勾选的源 id 列表
+（**按勾选顺序**——展示顺序 = 勾选顺序，后勾上的排末尾；勾选行实时标
+1、2、3… 序号 = 站点排列位置），取消 / Esc 返回 None——引导里 None =
+放弃使用（App 退出），管理里 None = 不落盘。候选与初始勾选由 MainScreen 注入，
+屏不读写配置：选择生效路径（保存 + 重建站点栏）集中在 MainScreen（_start /
+_manage_sources）。
+
+可订阅源（Source.subscribable，目前 rss、reddit 与 telegram）在此层还有
+二级入口：→ 进订阅管理屏（SubsStore 按源分派），改动即时落盘；返回后
+同步该源勾选（有订阅 = 勾上，空 = 取消）与行文案，并回调 MainScreen 标脏。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Callable
+from typing import ClassVar
+
+from textual.app import ComposeResult
+from textual.containers import Horizontal, Vertical
+from textual.widgets import Button, Label, SelectionList
+from textual.widgets.selection_list import Selection
+
+from feedscope.core.i18n import t
+from feedscope.core.registry import get_class
+from feedscope.core.source import Source
+from feedscope.subscriptions import store_for
+from feedscope.ui import Bindings, feedback
+from feedscope.ui.focus_nav import ArrowModalScreen, FocusNavSelectionList
+from feedscope.ui.screens.subscriptions import SubscriptionsScreen
+
+
+def source_entry_text(source: Source) -> str:
+    """源选择列表的一行文案；空串 = 该源无可选流且非订阅型，不列出。
+
+    文案带上各源的信息流名（超 3 个截成计数，几十个订阅不至于刷屏）；
+    可订阅源空订阅也列出（→ 进订阅管理就地添加，否则零订阅的 rss 永远
+    进不了这个列表，鸡生蛋）。
+    """
+    labels = [source.feed_label(f) for f in source.feeds]
+    if not labels and not source.subscribable:
+        return ""
+    if labels:
+        feeds = t("common.enum_comma").join(labels[:3]) + (
+            t("source_setup.n_feeds_more", n=len(labels)) if len(labels) > 3 else ""
+        )
+    else:
+        feeds = t("source_setup.no_subs")
+    return f"{source.label_text} [dim]{feeds}[/dim]"
+
+
+class SourceSetupScreen(ArrowModalScreen[list[str] | None]):
+    """源勾选弹层基类：样式与交互共用，标题/文案/确认键由子类给出。"""
+
+    # 类级三件是文案键（import 期求值只能存键）；compose 时经 t() 解析
+    title_text: ClassVar[str] = ""
+    prompt_text: ClassVar[str] = ""
+    confirm_label: ClassVar[str] = "dialogs.confirm"
+
+    # Esc 取消继承自 ArrowModalScreen（action_cancel → dismiss(None)）
+    BINDINGS: ClassVar[Bindings] = [
+        # 二级入口走 →（与主屏 → 同构）：列表上按 = 高亮源的订阅管理，
+        # 按钮行上按 = 右移焦点（action_nav_right 分派）。Enter 不能用：
+        # SelectionList 把它截停转成勾选切换（widget 内 event.stop()），
+        # 屏级绑定与事件路径都压不过——留给勾选
+    ]
+
+    # 卡片三件套在 ArrowModalScreen.DEFAULT_CSS，这里只写差异（宽度约束与
+    # 勾选列表的尺寸）
+    CSS = """
+    #setup-dialog { max-width: 64; }
+    #setup-title { text-style: bold; padding-bottom:  1; }
+    #setup-prompt { padding-bottom: 1; }
+    #setup-list { width: auto; min-width: 44; height: auto; max-height: 14; margin-bottom: 1; }
+    """
+
+    def __init__(
+        self,
+        entries: list[tuple[str, str]],
+        initial_ids: list[str],
+        on_feeds_changed: Callable[[], None] | None = None,
+    ) -> None:
+        super().__init__()
+        self._entries = list(entries)  # (source_id, 行文案)，字母正序（见 sources/__init__）
+        self._labels: dict[str, str] = dict(entries)  # sid -> 不带序号的基础文案
+        self._initial = set(initial_ids)
+        self._on_feeds_changed = on_feeds_changed  # 订阅管理屏改过东西：App 标脏
+        # 勾选顺序（= 展示顺序）。初始勾选不触发 SelectionToggled（Textual 只对
+        # 显式切换发消息），沿用传入顺序；之后的每次切换在 handler 里维护。
+        self._order: list[str] = list(initial_ids)
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="setup-dialog", classes="modal-card"):
+            yield Label(t(self.title_text), id="setup-title")
+            yield Label(t(self.prompt_text), id="setup-prompt")
+            yield FocusNavSelectionList(
+                # option id = source id：改行文案（编号）时按 id 定位
+                *[Selection(text, sid, sid in self._initial, id=sid) for sid, text in self._entries]
+            )
+            with Horizontal(id="setup-actions"):
+                yield Button(t(self.confirm_label), id="setup-confirm", variant="primary")
+                yield Button(t("dialogs.cancel"), id="setup-cancel")
+
+    def on_mount(self) -> None:
+        self._renumber()  # 初始勾选也要带序号
+
+    def on_selection_list_selection_toggled(self, event: SelectionList.SelectionToggled) -> None:
+        """维护勾选顺序：勾上排到末尾、取消即移出（再勾上 = 挪到末尾，这就是调序动线）。
+
+        _toggle 先改状态后发消息，handler 里 selected 已是新状态，按成员关系
+        分支即可，不必依赖事件本身携带方向。
+        """
+        sid = event.selection.value
+        if sid in event.selection_list.selected:
+            if sid not in self._order:
+                self._order.append(sid)
+        else:
+            self._order = [s for s in self._order if s != sid]
+        self._renumber()
+
+    def _renumber(self) -> None:
+        """给勾选的行标序号（= 站点排列位置），未勾选的留空对齐。
+
+        序号随切换重排（取消 1 号后，原 2 号自动变 1）；列表行本身不动
+        （字母正序稳定，好找），只变文案。
+        """
+        sl = self.query_one(SelectionList)
+        pos = {sid: i + 1 for i, sid in enumerate(self.selected_ids)}
+        for sid, label in self._labels.items():
+            n = pos.get(sid)
+            sl.replace_option_prompt(sid, f"{n:>2} {label}" if n else f"   {label}")
+
+    @property
+    def selected_ids(self) -> list[str]:
+        """勾选的源 id，按勾选顺序返回（初始勾选沿用传入顺序）。"""
+        chosen = set(self.query_one(SelectionList).selected)
+        return [sid for sid in self._order if sid in chosen]
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        if event.button.id == "setup-confirm":
+            self.dismiss(self.selected_ids)
+        else:
+            self.dismiss(None)  # 只有确认/取消两键，if/else 即分派表
+
+    def action_cancel(self) -> None:
+        self.dismiss(None)
+
+    # ---- →：可订阅源的二级管理（订阅增删改名）----
+
+    def action_nav_right(self) -> None:
+        """→ 焦点感知分派：列表上 = 高亮源的订阅管理（原语义），按钮行 = 右移。"""
+        if isinstance(self.focused, SelectionList):
+            self.action_manage_feeds()
+            return
+        super().action_nav_right()
+
+    def action_manage_feeds(self) -> None:
+        """→：进高亮源的订阅管理屏；不可订阅的源按了要给反馈，不静默。"""
+        sl = self.query_one(SelectionList)
+        idx = sl.highlighted
+        if idx is None or not 0 <= idx < len(self._entries):
+            return
+        sid = self._entries[idx][0]
+        cls = get_class(sid)
+        if cls is None or not cls.subscribable:
+            feedback.info(
+                self.app, t("source_setup.not_subscribable", label=cls().label_text if cls else sid)
+            )
+            return
+        self.run_worker(self._manage_feeds(sid))
+
+    async def _manage_feeds(self, sid: str) -> None:
+        changed = await self.app.push_screen(
+            SubscriptionsScreen(store_for(sid)), wait_for_dismiss=True
+        )
+        if not changed:
+            return
+        self._sync_row(sid)
+        if self._on_feeds_changed is not None:
+            self._on_feeds_changed()
+
+    def _sync_row(self, sid: str) -> None:
+        """订阅管理返回后同步该源勾选与行文案：还有可选信息流 = 勾上（加订阅
+        显然想用，与 CLI 的 enabled 联动同语义）；删空 = 取消勾选。"""
+        cls = get_class(sid)
+        if cls is None:
+            return
+        source = cls()
+        want = bool(source.feeds)
+        self._labels[sid] = source_entry_text(source) or self._labels[sid]
+        sl = self.query_one(SelectionList)
+        if want and sid not in sl.selected:
+            sl.select(sid)
+            if sid not in self._order:
+                self._order.append(sid)
+        elif not want and sid in sl.selected:
+            sl.deselect(sid)
+            if sid in self._order:
+                self._order.remove(sid)
+        self._renumber()
+
+
+class OnboardingScreen(SourceSetupScreen):
+    """首启引导：勾选要启用的源，确认后进入主界面。"""
+
+    title_text = "source_setup.onboarding_title"
+    prompt_text = "source_setup.onboarding_prompt"
+    confirm_label = "source_setup.onboarding_confirm"
+
+
+class ManageSourcesScreen(SourceSetupScreen):
+    """F2 源管理：勾选 = 启用、取消勾选 = 停用，保存后立即生效。"""
+
+    title_text = "source_setup.manage_title"
+    prompt_text = "source_setup.manage_prompt"
+    confirm_label = "source_setup.manage_confirm"

feedscope/ui/screens/subscriptions.py

@@ -0,0 +1,196 @@
+"""订阅管理屏：F2 里 → 进入，列表 + 增删改名，改动即时落盘（源无关）。
+
+- 键位全非打印：↑↓ 选择、Enter 改名（走 ListView 的 Selected，与主列表
+  同一条路径）、Insert 添加、Delete 删除、Esc 返回
+- 添加框是全应用唯一的文本输入：可输入的形态因源而异（rss 收 feed 地址 /
+  站点首页 / OPML 路径，reddit 收 subreddit 名或地址），文案与分流都在
+  各源的 SubsStore 里，本屏零源特判
+- 改动即时落盘（config.update_feeds 原子写）：订阅是数据不是待确认的草稿，
+  Esc 只退出不回滚；删除有轻确认，误删可重新添加（显示名会再拉一次）
+- 业务编排全部复用顶层 subscriptions 模块，本屏只做展示与键位；源的差异
+  收在 SubsStore 适配器（Source.subscribable 门控入口 + store_for 分派）
+"""
+
+from __future__ import annotations
+
+from typing import ClassVar
+
+from rich.markup import escape
+from textual.app import ComposeResult
+from textual.binding import Binding
+from textual.containers import Horizontal, Vertical
+from textual.widgets import Button, Label, ListItem, ListView, Static
+
+from feedscope.core.config import Subscription  # 仅类型注解用（列表行的 key/label/url 三段）
+from feedscope.subscriptions import SubscriptionError, SubsStore
+from feedscope.core.i18n import t
+from feedscope.ui import Bindings, feedback
+from feedscope.ui.labels import retranslate_bindings
+from feedscope.ui.dialogs import ConfirmScreen, InputScreen
+from feedscope.ui.focus_nav import ArrowModalScreen, FocusNavListView
+
+
+class SubscriptionsScreen(ArrowModalScreen[bool]):
+    """订阅管理：dismiss(True) = 本次有过改动（调用方据此同步勾选与刷新）。"""
+
+    BINDINGS: ClassVar[Bindings] = [
+        Binding("escape", "back", "bindings.back"),
+        Binding("insert", "add", "bindings.add"),
+        Binding("delete", "remove", "bindings.remove"),
+    ]
+
+    CSS = """
+    #subs-dialog {
+        width: auto; min-width: 64; max-width: 96; height: auto;
+        background: $surface; border: ascii $primary; padding: 1 2;
+    }
+    #subs-title { text-style: bold; padding-bottom: 1; }
+    #subs-list { width: 1fr; height: auto; max-height: 14; padding: 0 1; }
+    #subs-empty { padding: 1 0; color: $text-muted; }
+    #subs-hint { padding-top: 1; color: $text-muted; }
+    #subs-actions { height: auto; margin-top: 1; }
+    #subs-actions Button { margin-right: 1; }
+    """
+
+    def __init__(self, store: SubsStore) -> None:
+        super().__init__()
+        self._store = store
+        self._changed = False
+
+    def compose(self) -> ComposeResult:
+        with Vertical(id="subs-dialog", classes="modal-card"):
+            yield Label(t("subscriptions.title", label=self._store.label), id="subs-title")
+            yield FocusNavListView(id="subs-list")
+            yield Label("", id="subs-empty")
+            yield Label(self._store.hint, id="subs-hint")
+            with Horizontal(id="subs-actions"):
+                yield Button(t("subscriptions.add"), id="subs-add", variant="primary")
+                yield Button(t("subscriptions.rename"), id="subs-rename")
+                yield Button(t("subscriptions.remove"), id="subs-remove")
+
+    async def on_mount(self) -> None:
+        retranslate_bindings(self)  # 键式键位文案解析（bindings.*），见 ui/labels.py
+        await self._rebuild()
+
+    # ---- 列表 ----
+
+    async def _rebuild(self) -> None:
+        """按当前配置重建列表（每条操作后调用），保持选中位尽量不动。"""
+        view = self.query_one("#subs-list", ListView)
+        idx = view.index
+        await view.remove_children()
+        feeds = self._store.feeds()
+        if feeds:
+            await view.mount(
+                *[
+                    ListItem(
+                        Static(
+                            f"{escape(f.key)}  [b]{escape(f.label)}[/b]\n[dim]{escape(f.url)}[/dim]"
+                        )
+                    )
+                    for f in feeds
+                ]
+            )
+            view.index = 0 if idx is None else min(idx, len(feeds) - 1)
+            view.display = True
+            self.query_one("#subs-empty", Label).update("")
+        else:
+            view.display = False
+            self.query_one("#subs-empty", Label).update(self._store.empty)
+        view.focus()
+
+    def _current(self) -> Subscription | None:
+        """当前选中的订阅（列表顺序 = 配置顺序，索引即位）。"""
+        view = self.query_one("#subs-list", ListView)
+        feeds = self._store.feeds()
+        if view.index is None or not feeds or view.index >= len(feeds):
+            return None
+        return feeds[view.index]
+
+    # ---- 动作（键盘与按钮共用路径）----
+
+    def action_add(self) -> None:
+        self.run_worker(self._add_flow())
+
+    async def _add_flow(self) -> None:
+        text = await self.app.push_screen(
+            InputScreen(
+                t("subscriptions.add_title"), placeholder=self._store.add_placeholder
+            ),
+            wait_for_dismiss=True,
+        )
+        if not text:
+            return
+        try:
+            _added, summary = await self._store.add(text)
+        except SubscriptionError as exc:
+            feedback.warn(self.app, str(exc), title=t("feedback.action_add_failed"))
+            return
+        except Exception as exc:
+            # 网络等意外：无源语境（source=None），前缀拼接走 failure_text 同一条规则
+            feedback.warn(
+                self.app,
+                feedback.failure_text(None, exc, action="feedback.action_add_failed"),
+                title=t("feedback.action_add_failed"),
+            )
+            return
+        self._changed = True
+        await self._rebuild()
+        feedback.info(self.app, summary)
+
+    def action_remove(self) -> None:
+        feed = self._current()
+        if feed is None:
+            feedback.info(self.app, t("subscriptions.pick_first"))
+            return
+        self.run_worker(self._remove_flow(feed.key, feed.label))
+
+    async def _remove_flow(self, key: str, label: str) -> None:
+        if not await self.app.push_screen(
+            ConfirmScreen(
+                t("subscriptions.remove_confirm", label=label),
+                confirm_label=t("subscriptions.remove"),
+            ),
+            wait_for_dismiss=True,
+        ):
+            return
+        if self._store.remove(key) is not None:
+            self._changed = True
+            await self._rebuild()
+            feedback.info(self.app, t("subscriptions.removed", label=label))
+
+    def action_rename(self) -> None:
+        feed = self._current()
+        if feed is None:
+            feedback.info(self.app, t("subscriptions.pick_first"))
+            return
+        self.run_worker(self._rename_flow(feed.key, feed.label))
+
+    async def _rename_flow(self, key: str, label: str) -> None:
+        text = await self.app.push_screen(
+            InputScreen(t("subscriptions.rename_title"), initial=label), wait_for_dismiss=True
+        )
+        if not text:
+            return
+        if self._store.rename(key, text) is None:
+            feedback.info(self.app, t("subscriptions.rename_noop"))
+            return
+        self._changed = True
+        await self._rebuild()
+        feedback.info(self.app, t("subscriptions.renamed", name=text))
+
+    def on_list_view_selected(self, event: ListView.Selected) -> None:
+        if event.list_view.id == "subs-list":
+            self.action_rename()  # Enter = 改名（与主列表 Enter 进详情同一事件路径）
+
+    def on_button_pressed(self, event: Button.Pressed) -> None:
+        by_id = {
+            "subs-add": self.action_add,
+            "subs-remove": self.action_remove,
+            "subs-rename": self.action_rename,
+        }
+        if handler := by_id.get(event.button.id or ""):
+            handler()
+
+    def action_back(self) -> None:
+        self.dismiss(self._changed)

feedscope/ui/theme.py

@@ -0,0 +1,45 @@
+"""克制的编辑器风深色主题：低饱和、灰阶层级，长时间阅读不刺眼。
+
+色板对齐 VS Code Dark+ 的克制取向：
+- 背景近黑灰（#1e1e1e）、前景浅灰（#d4d4d4），层级用 #252526/#2d2d30 的灰阶
+- 全主题唯一强调色是低饱和编辑器蓝 #569cd6（选中/焦点/链接），选中态由
+  Textual 从 primary 派生暗化色，贴近 VS Code 列表选中背景 #264f78
+- 语义色全部用暗色版：错误 #f48771、警告 #dcdcaa、成功 #6a9955
+- 不引入任何高饱和/荧光色
+
+Textual 8 的 Theme 是数据类：这些色直接喂给 ColorSystem，
+Header/Footer/Markdown/ListView 自动取色，无需逐组件写 CSS。两处派生
+不合意、经 variables/CSS 覆写（后者见 ui/screens/reading.py 的 READING_CSS）：
+- Markdown 标题取 primary 会整行变蓝（H5/H6 甚至 ansi_cyan）——抹平成
+  段落样式，所有源的正文同一种格式；
+- 链接缺省取前景灰，灰底灰字认不出可点——编辑器蓝只留给链接。
+"""
+
+from __future__ import annotations
+
+from textual.theme import Theme
+
+FEEDSCOPE_THEME = Theme(
+    name="feedscope-editor",
+    primary="#569cd6",  # 编辑器蓝：选中/高亮
+    secondary="#5c6b7a",  # 次级钢蓝灰
+    accent="#569cd6",  # 焦点环
+    warning="#dcdcaa",  # 暗黄（VS Code 警告色）
+    error="#f48771",  # 暗珊瑚红（VS Code 错误色）
+    success="#6a9955",  # 暗绿（VS Code 注释绿）
+    foreground="#d4d4d4",  # 编辑器前景
+    background="#1e1e1e",  # 编辑器背景
+    surface="#252526",  # 侧栏/面板
+    panel="#2d2d30",  # 边框/分隔
+    boost="#37373d",  # 悬浮
+    dark=True,
+    variables={
+        "footer-key-foreground": "#9aa0a6",
+        # 链接：缺省取前景灰（灰底灰字认不出可点），编辑器蓝只留给这里
+        # （Markdown 标题的统一格式见 reading.py 的 READING_CSS，不占强调色）
+        "link-color": "#569cd6",
+        # 侧栏未聚焦选中带（VS Code 未聚焦选中同款灰）：boost 字段在 CSS 变量
+        # $boost 里是 4% 半透明悬浮层（铺了看不见），实底只能走 variables
+        "nav-sel-background": "#37373d",
+    },
+)

feedscope/ui/wrap.py

@@ -0,0 +1,157 @@
+"""显示折行：UAX #14 中文场景的规范子集。
+
+- 汉字之间任意断行
+- ASCII 词（字母/数字/常见符号）内部不拆
+- 避头（挪字法）：句读/收尾符不落行首，连同上一行末字符一起带下来
+- 避尾：开括号/开引号不落行尾，挪到下一行行首
+
+wrap_display(text)：纯文本折行（列表标题）
+wrap_markdown(md)：markdown 折行（正文）——内联标记（**粗体**、[链接]()、`代码`、
+裸 URL）作为原子不拆；fenced 代码块与标题行原样保留。
+
+终端一格一字符，做不了印刷级的标点压缩/悬挂，挪字法是规范允许的简化。
+"""
+
+from __future__ import annotations
+
+import re
+
+from feedscope.core.text import display_width
+
+# 行首禁则：句读、收尾标点（UAX #14 CL/EX 类）
+_NO_START = set("。，、；：？！）】》」』〉…％·-～)〕")
+# 行尾禁则：开括号、开引号（UAX #14 OP/QU 类）
+_NO_END = set("（【《「『〈([{")
+
+# ASCII「词」成分：字母数字 + 混排常见符号；连续出现视为不可拆词
+_WORD_CHARS = set(
+    "abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ0123456789%+-./#@&=_"
+)
+
+# 内联标记原子：粗体/斜体/行内代码/链接/裸 URL
+# 链接文本可为空（知乎图片来源的空锚点会生成 [](url)），空文本也算一个原子
+_INLINE_RE = re.compile(
+    r"(\*\*[^*]+\*\*|\*[^*]+\*|`[^`]+`|\[[^\]]*\]\([^)\s]+\)|https?://\S+)"
+)
+_FENCED_RE = re.compile(r"(```.*?```)", re.DOTALL)  # 带捕获组：split 才会把代码块留在结果里
+
+
+# ---- 折行引擎：unit = (可见文本, 完整形态)，unit 内部不再拆 ----
+
+
+def _split_units(visible: str, full: str, breakable: bool) -> list[tuple[str, str]]:
+    """breakable 文本切成「单字符 / ASCII 词」unit；标记原子整体一个 unit。"""
+    if not breakable:
+        return [(visible, full)]
+    units: list[tuple[str, str]] = []
+    i, n = 0, len(visible)
+    while i < n:
+        ch = visible[i]
+        if ch in _WORD_CHARS:
+            j = i
+            while j < n and visible[j] in _WORD_CHARS:
+                j += 1
+            units.append((visible[i:j], visible[i:j]))
+            i = j
+        else:
+            units.append((ch, ch))
+            i += 1
+    return units
+
+
+def _wrap_units(units: list[tuple[str, str]], width: int) -> list[str]:
+    """贪心装箱 + 避头尾（挪字法），返回完整形态的行。
+
+    比行还宽的原子（长 URL 等）不再硬拆：整只占一行留给 Textual 自己折，
+    拆了会把 URL 断成两截，markdown-it 的 linkify 只认得前半截。
+    """
+    if width <= 0:
+        return ["".join(f for _, f in units)]
+
+    lines: list[list[tuple[str, str]]] = [[]]
+    w = 0
+
+    def open_line() -> None:
+        nonlocal w
+        carried: list[tuple[str, str]] = []
+        # 避尾：刚关闭的行若以开括号收尾，一并带到新行行首
+        while lines[-1] and lines[-1][-1][0] in _NO_END:
+            carried.insert(0, lines[-1].pop())
+        lines.append(carried)
+        w = sum(display_width(v) for v, _ in carried)
+
+    for visible, full in units:
+        cw = display_width(visible)
+        if w > 0 and w + cw > width:
+            if visible[0] in _NO_START and lines[-1]:
+                # 避头：句读要落行首 -> 把上一行末 unit 带下来陪它
+                carry = lines[-1].pop()
+                lines.append([carry])
+                w = display_width(carry[0])
+            else:
+                open_line()
+        lines[-1].append((visible, full))
+        w += cw
+
+    return ["".join(f for _, f in ln) for ln in lines if ln] or [""]
+
+
+def wrap_display(text: str, width: int) -> list[str]:
+    """纯文本按显示宽度折行；避头尾禁则用挪字法处理。"""
+    if width <= 0 or not text:
+        return [text]
+    return _wrap_units(_split_units(text, text, True), width)
+
+
+# ---- markdown 折行 ----
+
+
+def _wrap_inline_line(line: str, width: int) -> list[str]:
+    """一条物理行 -> 原子化后折行；内联标记原子不拆（宽度按可见文本计）。"""
+    atoms: list[tuple[str, str, bool]] = []
+    pos = 0
+    for m in _INLINE_RE.finditer(line):
+        if m.start() > pos:
+            atoms.append((line[pos:m.start()], line[pos:m.start()], True))
+        token = m.group(0)
+        if token.startswith("["):
+            inner = re.match(r"\[([^\]]+)\]", token)
+            atoms.append((inner.group(1) if inner else token, token, False))
+        else:
+            atoms.append((token, token, False))
+        pos = m.end()
+    if pos < len(line):
+        atoms.append((line[pos:], line[pos:], True))
+
+    units: list[tuple[str, str]] = []
+    for visible, full, breakable in atoms:
+        units.extend(_split_units(visible, full, breakable))
+    return _wrap_units(units, width)
+
+
+def wrap_markdown(md: str, width: int) -> str:
+    """markdown 正文折行：段落内避头尾；代码块与标题行原样保留。
+
+    段内行一律接成两空格硬换行（\"  \\n\"）——Textual 的 Markdown 按规范把
+    软换行折叠成空格（实测），既会抹掉源文本的真实换行（X 推文分行、引用
+    块行），也会把这里的预折行变回一行并留下「样 式」式的假空格；硬换行
+    让每一物理行原样上屏。
+    """
+    if width <= 0 or not md:
+        return md
+    out_blocks: list[str] = []
+    for part in _FENCED_RE.split(md):  # fenced 代码块原样保留
+        if part.startswith("```"):
+            out_blocks.append(part)
+            continue
+        for block in re.split(r"\n[ \t]*\n", part):  # 空行分段
+            if not block.strip():
+                continue
+            wrapped: list[str] = []
+            for hard_line in block.split("\n"):
+                if not hard_line.strip() or hard_line.lstrip().startswith("#"):
+                    wrapped.append(hard_line)  # 标题行短，不动
+                    continue
+                wrapped.extend(_wrap_inline_line(hard_line, width))
+            out_blocks.append("  \n".join(wrapped))
+    return "\n\n".join(out_blocks)