pubkit 0.1.0__py3-none-any.whl

pubkit/core/state.py

@@ -0,0 +1,213 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Idempotency and resumption.
+
+A publishing run is a distributed transaction across platforms you do not
+control, over links that drop. During the run that motivated this tool the
+automation bridge disconnected eight times and the browser extension died
+mid-publish. The only sane response is to make every step resumable and every
+step safe to re-enter.
+"""
+from __future__ import annotations
+
+import json
+import sqlite3
+import time
+from contextlib import contextmanager
+from dataclasses import dataclass
+from enum import Enum
+from pathlib import Path
+
+SCHEMA = """
+CREATE TABLE IF NOT EXISTS runs (
+    run_id      TEXT PRIMARY KEY,
+    plan_hash   TEXT NOT NULL,
+    created_at  REAL NOT NULL,
+    status      TEXT NOT NULL
+);
+CREATE TABLE IF NOT EXISTS steps (
+    run_id      TEXT NOT NULL,
+    document_id TEXT NOT NULL,
+    platform    TEXT NOT NULL,
+    step        TEXT NOT NULL,
+    status      TEXT NOT NULL,
+    content_id  TEXT,
+    fingerprint TEXT,
+    remote_ref  TEXT,
+    error       TEXT,
+    updated_at  REAL NOT NULL,
+    PRIMARY KEY (run_id, document_id, platform, step)
+);
+CREATE TABLE IF NOT EXISTS remotes (
+    document_id TEXT NOT NULL,
+    platform    TEXT NOT NULL,
+    content_id  TEXT NOT NULL,
+    remote_ref  TEXT NOT NULL,
+    url         TEXT,
+    published   INTEGER NOT NULL DEFAULT 0,
+    updated_at  REAL NOT NULL,
+    PRIMARY KEY (document_id, platform)
+);
+CREATE TABLE IF NOT EXISTS channel_tuning (
+    channel     TEXT PRIMARY KEY,
+    chunk_size  INTEGER NOT NULL,
+    updated_at  REAL NOT NULL
+);
+"""
+
+
+class Step(str, Enum):
+    AUTH = "auth"
+    DRAFT = "draft"
+    CONTENT = "content"
+    MEDIA = "media"
+    VERIFY = "verify"
+    PUBLISH = "publish"
+
+    @classmethod
+    def order(cls) -> list[Step]:
+        return [cls.AUTH, cls.DRAFT, cls.CONTENT, cls.MEDIA, cls.VERIFY, cls.PUBLISH]
+
+
+class Status(str, Enum):
+    PENDING = "pending"
+    RUNNING = "running"
+    DONE = "done"
+    FAILED = "failed"
+    SKIPPED = "skipped"
+
+
+@dataclass
+class RemoteRecord:
+    document_id: str
+    platform: str
+    content_id: str
+    remote_ref: str
+    url: str | None
+    published: bool
+
+
+class StateStore:
+    def __init__(self, path: Path | str = ".pubkit/state.sqlite") -> None:
+        self.path = Path(path)
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self._conn = sqlite3.connect(self.path)
+        self._conn.row_factory = sqlite3.Row
+        self._conn.executescript(SCHEMA)
+        self._conn.commit()
+
+    # ------------------------------------------------------------------ runs
+    def start_run(self, run_id: str, plan_hash: str) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO runs VALUES (?,?,?,?)",
+            (run_id, plan_hash, time.time(), Status.RUNNING.value),
+        )
+        self._conn.commit()
+
+    def finish_run(self, run_id: str, status: Status) -> None:
+        self._conn.execute("UPDATE runs SET status=? WHERE run_id=?", (status.value, run_id))
+        self._conn.commit()
+
+    # ----------------------------------------------------------------- steps
+    def step_status(self, run_id: str, doc: str, platform: str, step: Step) -> Status:
+        row = self._conn.execute(
+            "SELECT status FROM steps WHERE run_id=? AND document_id=? AND platform=? AND step=?",
+            (run_id, doc, platform, step.value),
+        ).fetchone()
+        return Status(row["status"]) if row else Status.PENDING
+
+    def record_step(
+        self,
+        run_id: str,
+        doc: str,
+        platform: str,
+        step: Step,
+        status: Status,
+        *,
+        content_id: str | None = None,
+        fingerprint: dict | None = None,
+        remote_ref: str | None = None,
+        error: str | None = None,
+    ) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO steps VALUES (?,?,?,?,?,?,?,?,?,?)",
+            (
+                run_id,
+                doc,
+                platform,
+                step.value,
+                status.value,
+                content_id,
+                json.dumps(fingerprint) if fingerprint else None,
+                remote_ref,
+                error,
+                time.time(),
+            ),
+        )
+        self._conn.commit()
+
+    def resume_point(self, run_id: str, doc: str, platform: str) -> Step:
+        """First step that is not `done`. Re-running picks up exactly here."""
+        for step in Step.order():
+            if self.step_status(run_id, doc, platform, step) is not Status.DONE:
+                return step
+        return Step.PUBLISH
+
+    # --------------------------------------------------------------- remotes
+    def remember_remote(
+        self, doc: str, platform: str, content_id: str, ref: str, url: str | None = None, published: bool = False
+    ) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO remotes VALUES (?,?,?,?,?,?,?)",
+            (doc, platform, content_id, ref, url, int(published), time.time()),
+        )
+        self._conn.commit()
+
+    def remote(self, doc: str, platform: str) -> RemoteRecord | None:
+        row = self._conn.execute(
+            "SELECT * FROM remotes WHERE document_id=? AND platform=?", (doc, platform)
+        ).fetchone()
+        if not row:
+            return None
+        return RemoteRecord(
+            document_id=row["document_id"],
+            platform=row["platform"],
+            content_id=row["content_id"],
+            remote_ref=row["remote_ref"],
+            url=row["url"],
+            published=bool(row["published"]),
+        )
+
+    def needs_update(self, doc: str, platform: str, content_id: str) -> bool:
+        """False when the remote already holds exactly this content.
+
+        This is what stops a re-run creating a second draft — the mistake that
+        turns a retry into a mess someone has to clean up by hand (failure D2).
+        """
+        rec = self.remote(doc, platform)
+        return rec is None or rec.content_id != content_id
+
+    # -------------------------------------------------------- channel tuning
+    def tuned_chunk_size(self, channel: str) -> int | None:
+        row = self._conn.execute(
+            "SELECT chunk_size FROM channel_tuning WHERE channel=?", (channel,)
+        ).fetchone()
+        return row["chunk_size"] if row else None
+
+    def save_chunk_size(self, channel: str, size: int) -> None:
+        self._conn.execute(
+            "INSERT OR REPLACE INTO channel_tuning VALUES (?,?,?)", (channel, size, time.time())
+        )
+        self._conn.commit()
+
+    @contextmanager
+    def transaction(self):
+        try:
+            yield self._conn
+            self._conn.commit()
+        except Exception:
+            self._conn.rollback()
+            raise
+
+    def close(self) -> None:
+        self._conn.close()

pubkit/core/transport.py

@@ -0,0 +1,170 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Verified chunked transport.
+
+Written because a 12,368-character payload once arrived with exactly one byte
+mutated (`h` → `g`) and nothing anywhere reported an error. gzip failed three
+steps later with `invalid distance too far back`, which is a spectacularly
+unhelpful way to learn your channel is lossy.
+
+The rules this module enforces:
+
+  A1  every chunk is hash-verified end to end
+  A2  the per-call size ceiling is *probed*, never assumed
+  A3  staging survives navigation, and re-pushing is a no-op
+  A4  exactly one gzip member per payload
+"""
+from __future__ import annotations
+
+import base64
+import gzip
+import io
+import zlib
+from collections.abc import Awaitable, Callable
+from dataclasses import dataclass, field
+from typing import Protocol
+
+# The rolling hash below is deliberately trivial and identical on both sides:
+# a 32-bit FNV-ish accumulation that a page can compute in three lines of JS
+# without pulling in a crypto library. It is an integrity check against a lossy
+# channel, not a security primitive.
+_MASK = 0xFFFFFFFF
+
+
+def rolling_hash(s: str) -> str:
+    h = 0
+    for ch in s:
+        h = (h * 31 + ord(ch)) & _MASK
+    return format(h, "x")
+
+
+#: The JavaScript twin of :func:`rolling_hash`. Kept next to it on purpose —
+#: if one changes and the other does not, verification breaks silently, which
+#: is the exact failure this module exists to prevent.
+ROLLING_HASH_JS = """
+window.__pkHash = function (s) {
+  let h = 0;
+  for (let i = 0; i < s.length; i++) { h = (h * 31 + s.charCodeAt(i)) >>> 0; }
+  return h.toString(16);
+};
+"""
+
+
+def encode_payload(text: str) -> str:
+    """gzip + base64, guaranteed single-member (failure A4).
+
+    `gzip.compress` emits one member; concatenating two independently
+    compressed halves does not, and `DecompressionStream('gzip')` rejects that
+    with `Junk found after end of compressed data` while Python's
+    `gzip.decompress` happily accepts it. Divergent behaviour between the two
+    ends of a pipe is how a bug hides for an hour.
+    """
+    buf = io.BytesIO()
+    with gzip.GzipFile(fileobj=buf, mode="wb", mtime=0) as fh:
+        fh.write(text.encode("utf-8"))
+    raw = buf.getvalue()
+    assert raw.count(b"\x1f\x8b") >= 1, "not gzip"
+    return base64.b64encode(raw).decode("ascii")
+
+
+def decode_payload(b64: str) -> str:
+    return gzip.decompress(base64.b64decode(b64)).decode("utf-8")
+
+
+class Channel(Protocol):
+    """Anything that can move a string to the far side and run code there."""
+
+    async def push_chunk(self, key: str, index: int, data: str) -> None: ...
+    async def remote_hash(self, key: str) -> str | None: ...
+    async def remote_length(self, key: str) -> int: ...
+    async def assemble(self, key: str, count: int) -> None: ...
+
+
+@dataclass
+class ChunkedTransport:
+    """Move a large payload across a channel with an unknown, undocumented
+    per-call size ceiling, and prove it arrived intact."""
+
+    channel: Channel
+    #: Starting guess. The real ceiling is discovered, not trusted.
+    chunk_size: int = 5_600
+    max_chunk: int = 45_000
+    min_chunk: int = 1_024
+    probed: bool = False
+    _stats: dict = field(default_factory=dict)
+
+    async def probe_ceiling(self, probe: Callable[[int], Awaitable[bool]]) -> int:
+        """Binary-search the largest chunk the channel accepts (failure A2).
+
+        Called once per channel; the result belongs in the state store so the
+        next run starts from the known-good value.
+        """
+        lo, hi = self.min_chunk, self.max_chunk
+        best = self.min_chunk
+        while lo <= hi:
+            mid = (lo + hi) // 2
+            if await probe(mid):
+                best, lo = mid, mid + 1
+            else:
+                hi = mid - 1
+        # Back off 20%: the ceiling is not always stable under load, and a
+        # chunk that fails mid-run costs a retry plus a reassembly.
+        self.chunk_size = max(self.min_chunk, int(best * 0.8))
+        self.probed = True
+        return self.chunk_size
+
+    async def send(self, key: str, text: str, *, compress: bool = True) -> str:
+        """Push `text` under `key`, verify it, and return the payload hash.
+
+        Idempotent: if the far side already holds a payload with the right hash
+        the whole thing is a no-op, which is what makes a dropped bridge cost
+        one step rather than one run (failure D1).
+        """
+        payload = encode_payload(text) if compress else text
+        want = rolling_hash(payload)
+
+        existing = await self.channel.remote_hash(key)
+        if existing == want:
+            self._stats["skipped"] = self._stats.get("skipped", 0) + 1
+            return want
+
+        chunks = [payload[i : i + self.chunk_size] for i in range(0, len(payload), self.chunk_size)]
+        for i, chunk in enumerate(chunks):
+            await self._push_verified(key, i, chunk)
+
+        await self.channel.assemble(key, len(chunks))
+
+        got = await self.channel.remote_hash(key)
+        if got != want:
+            remote_len = await self.channel.remote_length(key)
+            raise TransportCorruption(
+                f"payload {key!r} corrupted in transit: "
+                f"sent {len(payload)} chars hash={want}, "
+                f"remote has {remote_len} chars hash={got}"
+            )
+        self._stats["sent"] = self._stats.get("sent", 0) + len(chunks)
+        return want
+
+    async def _push_verified(self, key: str, index: int, chunk: str, *, attempts: int = 3) -> None:
+        want = rolling_hash(chunk)
+        last: str | None = None
+        for _ in range(attempts):
+            await self.channel.push_chunk(key, index, chunk)
+            got = await self.channel.remote_hash(f"{key}:{index}")
+            if got == want:
+                return
+            last = got
+        raise TransportCorruption(
+            f"chunk {index} of {key!r} failed {attempts} verification attempts "
+            f"(want {want}, got {last}); channel is lossy at {len(chunk)} chars"
+        )
+
+
+class TransportCorruption(RuntimeError):
+    """The channel altered the payload. Never retry blindly past this."""
+
+
+def crc(text: str) -> int:
+    """A second, independent checksum. Used where a payload crosses two hops
+    and you want to know *which* hop ate it."""
+    return zlib.crc32(text.encode("utf-8")) & _MASK

pubkit/registry.py

@@ -0,0 +1,81 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Adapter registry and plugin discovery.
+
+Built-ins are registered here; third-party adapters are discovered through the
+`pubkit.adapters` entry point, so adding a platform never requires touching
+this repository.
+
+    # in your own package's pyproject.toml
+    [project.entry-points."pubkit.adapters"]
+    ghost = "my_pubkit_ghost:GhostAdapter"
+"""
+from __future__ import annotations
+
+import logging
+from collections.abc import Callable
+from importlib.metadata import entry_points
+
+log = logging.getLogger(__name__)
+
+_BUILTIN: dict[str, Callable[..., object]] = {}
+
+
+def register(name: str, factory: Callable[..., object]) -> None:
+    _BUILTIN[name] = factory
+
+
+def _load_builtins() -> None:
+    if _BUILTIN:
+        return
+    from .adapters.devto import DevToAdapter, HashnodeAdapter
+    from .adapters.medium import MediumAdapter
+    from .adapters.substack import SubstackAdapter
+    from .adapters.x import XAdapter
+
+    register("medium", MediumAdapter)
+    register("substack", SubstackAdapter)
+    register("x", XAdapter)
+    register("twitter", XAdapter)
+    register("devto", DevToAdapter)
+    register("hashnode", HashnodeAdapter)
+
+
+def _plugins() -> dict[str, Callable[..., object]]:
+    found: dict[str, Callable[..., object]] = {}
+    try:
+        eps = entry_points(group="pubkit.adapters")
+    except TypeError:  # pragma: no cover - older importlib
+        eps = entry_points().get("pubkit.adapters", [])  # type: ignore[assignment]
+    for ep in eps:
+        try:
+            found[ep.name] = ep.load()
+        except Exception:  # noqa: BLE001
+            log.exception("could not load adapter plugin %s", ep.name)
+    return found
+
+
+def build_adapter(name: str, **kwargs):
+    _load_builtins()
+    factories = {**_BUILTIN, **_plugins()}
+    if name not in factories:
+        raise KeyError(f"unknown platform {name!r}; available: {', '.join(sorted(factories))}")
+    factory = factories[name]
+    if name == "substack" and "publication" not in kwargs:
+        import os
+
+        kwargs["publication"] = os.environ.get("PUBKIT_SUBSTACK_URL", "https://example.substack.com")
+    return factory(**kwargs)
+
+
+def list_adapters() -> list[tuple[str, object]]:
+    _load_builtins()
+    out = []
+    for name in sorted({**_BUILTIN, **_plugins()}):
+        if name == "twitter":
+            continue
+        try:
+            out.append((name, build_adapter(name)))
+        except Exception:  # noqa: BLE001
+            continue
+    return out

pubkit/render/__init__.py

@@ -0,0 +1,2 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0

pubkit/render/html.py

@@ -0,0 +1,221 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Renderers: IR → what a platform will actually accept."""
+from __future__ import annotations
+
+import html as _html
+import re
+from dataclasses import dataclass
+
+from ..core.ir import (
+    Callout,
+    Code,
+    Document,
+    Embed,
+    Figure,
+    Heading,
+    ListBlock,
+    Paragraph,
+    Quote,
+    Rule,
+    Table,
+)
+
+_INLINE = [
+    (re.compile(r"\*\*(.+?)\*\*", re.S), r"<strong>\1</strong>"),
+    (re.compile(r"(?<!\*)\*([^*]+?)\*(?!\*)"), r"<em>\1</em>"),
+    (re.compile(r"`([^`]+?)`"), r"<code>\1</code>"),
+    (re.compile(r"\[([^\]]+?)\]\(([^)]+?)\)"), r'<a href="\2">\1</a>'),
+]
+
+
+def inline(text: str) -> str:
+    out = _html.escape(text, quote=False)
+    for pattern, repl in _INLINE:
+        out = pattern.sub(repl, out)
+    return out
+
+
+@dataclass
+class EditorHtmlRenderer:
+    """HTML shaped for a contenteditable editor, not for the web.
+
+    Two deliberate constraints:
+
+    * **No images.** Figures render as a caption paragraph only. The image
+      arrives later through the editor's own upload path, because both `data:`
+      URIs and remote URLs are stripped from pasted HTML (failure B5).
+      The caption doubles as the insertion anchor.
+
+    * **Tables are pre-rendered to images upstream.** By the time a table gets
+      here it is already a Figure, or the planner decided the platform supports
+      tables and a different renderer is in use.
+
+    Heading levels are remapped because editors reserve h1/h2 for title and
+    subtitle; article headings start at h3.
+    """
+
+    heading_offset: int = 2
+    max_heading: int = 4
+
+    def render(self, doc: Document) -> str:
+        parts: list[str] = [f"<h3>{inline(doc.title)}</h3>"]
+        if doc.subtitle:
+            parts.append(f"<h4>{inline(doc.subtitle)}</h4>")
+        for block in doc.blocks:
+            parts.append(self.block(block, doc))
+        return "".join(p for p in parts if p)
+
+    def block(self, b, doc: Document) -> str:
+        if isinstance(b, Heading):
+            lvl = min(self.max_heading, b.level + self.heading_offset)
+            prefix = f"{b.number}. " if b.number else ""
+            return f"<h{lvl}>{inline(prefix + b.text)}</h{lvl}>"
+        if isinstance(b, Paragraph):
+            return f"<p>{inline(b.text)}</p>"
+        if isinstance(b, Code):
+            return f"<pre><code>{_html.escape(b.text)}</code></pre>"
+        if isinstance(b, Quote):
+            attr = f"<br><em>— {inline(b.attribution)}</em>" if b.attribution else ""
+            return f"<blockquote>{inline(b.text)}{attr}</blockquote>"
+        if isinstance(b, ListBlock):
+            tag = "ol" if b.ordered else "ul"
+            items = "".join(f"<li>{inline(i)}</li>" for i in b.items)
+            return f"<{tag}>{items}</{tag}>"
+        if isinstance(b, Callout):
+            title = f"<strong>{inline(b.title)}</strong><br>" if b.title else ""
+            return f"<blockquote>{title}{inline(b.text)}</blockquote>"
+        if isinstance(b, Rule):
+            return "<hr>"
+        if isinstance(b, Embed):
+            return f'<p><a href="{_html.escape(b.url, quote=True)}">{_html.escape(b.url)}</a></p>'
+        if isinstance(b, Figure):
+            # Caption only. It is both the visible caption and the anchor the
+            # image will be inserted above.
+            cap = b.caption or (doc.assets[b.asset_id].alt if b.asset_id in doc.assets else "")
+            return f"<p><em>{inline(cap)}</em></p>" if cap else ""
+        if isinstance(b, Table):
+            head = "".join(f"<th>{inline(h)}</th>" for h in b.header)
+            rows = "".join(
+                "<tr>" + "".join(f"<td>{inline(c)}</td>" for c in row) + "</tr>" for row in b.rows
+            )
+            cap = f"<caption>{inline(b.caption)}</caption>" if b.caption else ""
+            return f"<table>{cap}<thead><tr>{head}</tr></thead><tbody>{rows}</tbody></table>"
+        return ""
+
+    def caption_anchors(self, doc: Document) -> list[tuple[str, str]]:
+        """(asset_id, caption) in document order — the insertion plan."""
+        out = []
+        for b in doc.blocks:
+            if isinstance(b, Figure):
+                cap = b.caption or (doc.assets[b.asset_id].alt if b.asset_id in doc.assets else "")
+                if cap:
+                    out.append((b.asset_id, cap))
+        return out
+
+
+@dataclass
+class MarkdownRenderer:
+    """Plain Markdown for API platforms (Dev.to, Hashnode, Ghost, static sites)."""
+
+    image_url_for: object = None  # Callable[[str], str] | None
+
+    def render(self, doc: Document) -> str:
+        lines: list[str] = []
+        for b in doc.blocks:
+            lines.append(self.block(b, doc))
+        return "\n\n".join(x for x in lines if x).strip() + "\n"
+
+    def block(self, b, doc: Document) -> str:
+        if isinstance(b, Heading):
+            prefix = f"{b.number}. " if b.number else ""
+            return "#" * min(6, b.level + 1) + " " + prefix + b.text
+        if isinstance(b, Paragraph):
+            return b.text
+        if isinstance(b, Code):
+            return f"```{b.language}\n{b.text}\n```"
+        if isinstance(b, Quote):
+            body = "\n".join("> " + ln for ln in b.text.splitlines())
+            return body + (f"\n>\n> — {b.attribution}" if b.attribution else "")
+        if isinstance(b, ListBlock):
+            return "\n".join(
+                (f"{i+1}. " if b.ordered else "- ") + item for i, item in enumerate(b.items)
+            )
+        if isinstance(b, Callout):
+            title = f"**{b.title}**\n>\n" if b.title else ""
+            return "> " + title.replace("\n", "\n> ") + b.text
+        if isinstance(b, Rule):
+            return "---"
+        if isinstance(b, Embed):
+            return b.url
+        if isinstance(b, Figure):
+            asset = doc.assets.get(b.asset_id)
+            alt = b.alt or (asset.alt if asset else "")
+            url = self.image_url_for(b.asset_id) if self.image_url_for else (str(asset.path) if asset else "")
+            cap = f"\n*{b.caption}*" if b.caption else ""
+            return f"![{alt}]({url}){cap}"
+        if isinstance(b, Table):
+            align = b.align or ["l"] * len(b.header)
+            sep = {"l": ":---", "c": ":---:", "r": "---:"}
+            head = "| " + " | ".join(b.header) + " |"
+            rule = "| " + " | ".join(sep.get(a, ":---") for a in align) + " |"
+            rows = "\n".join("| " + " | ".join(r) + " |" for r in b.rows)
+            cap = f"\n*{b.caption}*" if b.caption else ""
+            return f"{head}\n{rule}\n{rows}{cap}"
+        return ""
+
+
+MD_STRIP = [
+    (re.compile(r"\*\*(.+?)\*\*", re.S), r"\1"),
+    (re.compile(r"(?<!\*)\*([^*]+?)\*(?!\*)"), r"\1"),
+    (re.compile(r"`([^`]+?)`"), r"\1"),
+    (re.compile(r"\[([^\]]+?)\]\(([^)]+?)\)"), r"\1"),
+    (re.compile(r"<!--.*?-->", re.S), ""),
+]
+
+
+def plain(text: str) -> str:
+    """Strip inline markdown.
+
+    Platforms that take plain text render `**bold**` literally, which reads as
+    a formatting bug to every reader who sees it.
+    """
+    for pattern, repl in MD_STRIP:
+        text = pattern.sub(repl, text)
+    return re.sub(r"\s+", " ", text).strip()
+
+
+@dataclass
+class ThreadRenderer:
+    """Split a document into a numbered thread for X/Bluesky/Mastodon."""
+
+    limit: int = 280
+    reserve: int = 12  # room for " (3/11)"
+
+    def render(self, doc: Document) -> list[str]:
+        chunks: list[str] = []
+        budget = self.limit - self.reserve
+        buf = ""
+        for b in doc.blocks:
+            if isinstance(b, (Heading, Rule, Figure, Table)):
+                if buf:
+                    chunks.append(buf.strip())
+                    buf = ""
+                if isinstance(b, Heading):
+                    buf = b.text.strip() + "\n\n"
+                continue
+            text = getattr(b, "text", "") or (
+                "\n".join(b.items) if isinstance(b, ListBlock) else ""
+            )
+            for sentence in re.split(r"(?<=[.!?])\s+", plain(text)):
+                if not sentence:
+                    continue
+                if len(buf) + len(sentence) + 1 > budget:
+                    chunks.append(buf.strip())
+                    buf = ""
+                buf += sentence + " "
+        if buf.strip():
+            chunks.append(buf.strip())
+
+        total = len(chunks)
+        return [f"{c} ({i+1}/{total})" if total > 1 else c for i, c in enumerate(chunks)]