pubkit 0.1.0__tar.gz → 0.2.0__tar.gz

pubkit-0.2.0/CHANGELOG.md

@@ -0,0 +1,97 @@
+# Changelog
+
+Format follows [Keep a Changelog](https://keepachangelog.com/en/1.1.0/).
+Versioning is [semantic](https://semver.org/); adapters may change behaviour on
+a minor bump when a platform changes underneath them.
+
+## [0.2.0] — 2026-09-11
+
+The release that makes `pubkit publish --to medium --confirm` actually work
+unattended. 0.1.x could plan a Medium publish; it could not perform one.
+
+### Added
+
+- **Browser lifecycle** (`browserctl.BrowserPool`, `attached()`). This was the
+  missing seam: the runner called `adapter.authenticate()` on a `MediumAdapter`
+  whose `_page` was still `None`. Now one browser serves the whole run, one
+  context per platform so a Medium session is never presented to Substack, and
+  sessions are refreshed on the way out because cookies rotate. API-only runs
+  never launch Chromium at all.
+- **Table rendering** (`render.tables`, `core.assets.materialise`). The planner
+  said `table_to_image` and listed the asset ids; nothing produced the files.
+  Tables now render to quantised PNGs at 2x, cached on cell content so a re-run
+  neither re-renders nor re-uploads an unchanged table. The source IR is never
+  mutated — the same document keeps native tables on Dev.to in the same run.
+- `pubkit auth verify <platform>` — check a session before a publish depends on
+  it, rather than discovering it expired halfway through.
+- **Browser integration tests** against a deliberately hostile fixture editor
+  that reproduces multiple content roots, image stripping, figures landing
+  above the caret, and uploads that sit on a `blob:` URL before resolving.
+  They skip cleanly where Chromium is unavailable.
+
+### Fixed
+
+- `marker_regex` was double-escaped, so every `fingerprint()` call threw
+  `SyntaxError: Invalid regular expression` inside the page. Verification was
+  therefore broken on every browser adapter. Found by the new integration
+  tests on their first run.
+- `auth login` routed on a capability flag rather than the platform list, so
+  `pubkit auth login substack` took the API-token path and prompted for a token
+  that does not exist.
+
+## [0.1.1] — 2026-09-11
+
+### Added
+
+- Docker image on the Playwright base (`ghcr.io/arunsingh/pubkit`), so browser
+  adapters work in CI without hand-installing Chromium's system libraries.
+- `action.yml` — the repository is now a reusable GitHub Action.
+- `CITATION.cff`, and a Homebrew formula template under `packaging/`.
+
+### Fixed
+
+- `pubkit doctor` ignored `PLAYWRIGHT_BROWSERS_PATH` and reported Chromium as
+  missing on managed images (CI runners, devcontainers, the Playwright Docker
+  image) where it was in fact installed — sending people off to fix a problem
+  they did not have. Found by running the published package in exactly such an
+  environment.
+
+## [0.1.0] — 2026-09-11
+
+First release. Extracted from a real, painful publishing run: a 15,000-word
+illustrated three-part series to Medium that surfaced 21 distinct failure modes,
+all catalogued in `docs/FAILURE-MODES.md`.
+
+### Added
+
+- **Post IR** — a canonical, platform-agnostic document model with a
+  content-addressed id used as the idempotency key everywhere.
+- **Capability negotiation** — adapters declare what they support; the planner
+  emits explicit, printable degradations. `pubkit plan` shows them before
+  anything is sent.
+- **Check pipeline** — placeholders, numeric assertions, cross-references,
+  number drift, assets, budget, structure. Pluggable via `pubkit.checks`.
+- **Verified chunked transport** — per-chunk rolling-hash verification, probed
+  size ceilings, single-member gzip.
+- **Browser adapter toolkit** — paste-based document replace with a block-count
+  assertion, reload-then-fingerprint verification, caption-anchored `File`
+  image insertion, Unicode-folding anchor resolution, tag-chip post-conditions.
+- **Adapters** — Medium, Substack (browser); X, Dev.to, Hashnode (API).
+- **Runner** — six resumable steps per (document, platform), sqlite state store,
+  two-phase publish for series, hash-pinned `--confirm` gate, per-platform rate
+  limiting and jittered retry.
+- **CLI** — `init`, `validate`, `plan`, `publish`, `status`, `platforms`,
+  `doctor`, `auth login|logout|list`.
+- **Workflows** — GitHub Actions examples and Airflow operators.
+- **Extension points** — `pubkit.adapters`, `pubkit.renderers`, `pubkit.checks`,
+  `pubkit.hooks`, plus per-platform transforms.
+
+### Known limitations
+
+- Browser adapter selectors will need patching when a platform redesigns its
+  editor. They are isolated in one `EditorSelectors` dataclass per adapter
+  precisely so that is a small change.
+- Table→image rendering requires the `render` extra; without it, tables degrade
+  to lists on platforms that lack table support.
+- X media upload uses the v1.1 endpoint, which is what the v2 API still
+  requires.

{pubkit-0.1.0 → pubkit-0.2.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: pubkit
-Version: 0.1.0
+Version: 0.2.0
 Summary: Publish one source to many platforms, safely. Medium, Substack, X, Dev.to, Hashnode.
 Project-URL: Homepage, https://github.com/arunsingh/pubkit
 Project-URL: Issues, https://github.com/arunsingh/pubkit/issues
@@ -109,9 +109,10 @@ pubkit validate content/series/
 # 2. See exactly what each platform will get — including every degradation.
 pubkit plan content/series/ --to medium,devto,x
 
-# 3. Sign in. pubkit never accepts a password.
-pubkit auth login medium        # opens a window; you sign in; it keeps the session
+# 3. Sign in, once. pubkit never accepts a password.
+pubkit auth login medium        # a window opens; you sign in; it keeps the session
 pubkit auth login devto         # API token → OS keychain
+pubkit auth verify medium       # confirm before a publish depends on it
 
 # 4. Drafts everywhere. Safe to re-run; a dropped connection costs one step.
 pubkit publish content/series/ --to medium,devto,x
@@ -138,6 +139,31 @@ x: part-1 (bf9abfe78ce4)
 
 Nothing is a surprise at publish time. That is the whole design goal.
 
+## Sign in once, then it runs on its own
+
+```bash
+pubkit auth login medium
+```
+
+A real browser window opens at Medium's login page. You sign in — password
+manager, MFA, device confirmation, whatever it asks for. pubkit watches for the
+post-login URL, saves the session encrypted, and closes the window.
+
+From then on, unattended:
+
+```bash
+pubkit publish content/ --to medium,devto,x --confirm
+```
+
+One browser serves the whole run, one context per platform so a Medium session
+is never presented to Substack, and sessions refresh on the way out because
+cookies rotate. Publishing only to API platforms never launches Chromium at all.
+
+pubkit sees cookies. It never sees, types or stores a password — which is both
+the right security posture and the only thing that works, since platforms
+increasingly gate login behind challenges an automation layer has no business
+trying to defeat.
+
 ## Write once
 
 ````markdown
@@ -229,6 +255,28 @@ ghost = "my_pubkit_ghost:GhostAdapter"
 Five extension points, all first-class: `pubkit.adapters`, `pubkit.renderers`,
 `pubkit.checks`, `pubkit.hooks`, and per-platform `transforms:` in config.
 
+## Install it however you like
+
+```bash
+pip install "pubkit[all]"                       # the normal way
+pipx install "pubkit[all]"                      # isolated CLI
+uv tool install "pubkit[all]"                   # same, faster
+docker run --rm -v "$PWD:/work" ghcr.io/arunsingh/pubkit validate content/
+```
+
+The Docker image ships Chromium and its system libraries, which is the part
+nobody wants to install on a CI runner by hand.
+
+As a GitHub Action, no install step at all:
+
+```yaml
+- uses: arunsingh/pubkit@v1
+  with:
+    command: plan
+    path: content/
+    platforms: medium,devto
+```
+
 ## Fit it into a workflow
 
 **GitHub Actions** — plan on every PR, publish on merge:

{pubkit-0.1.0 → pubkit-0.2.0}/README.md

@@ -59,9 +59,10 @@ pubkit validate content/series/
 # 2. See exactly what each platform will get — including every degradation.
 pubkit plan content/series/ --to medium,devto,x
 
-# 3. Sign in. pubkit never accepts a password.
-pubkit auth login medium        # opens a window; you sign in; it keeps the session
+# 3. Sign in, once. pubkit never accepts a password.
+pubkit auth login medium        # a window opens; you sign in; it keeps the session
 pubkit auth login devto         # API token → OS keychain
+pubkit auth verify medium       # confirm before a publish depends on it
 
 # 4. Drafts everywhere. Safe to re-run; a dropped connection costs one step.
 pubkit publish content/series/ --to medium,devto,x
@@ -88,6 +89,31 @@ x: part-1 (bf9abfe78ce4)
 
 Nothing is a surprise at publish time. That is the whole design goal.
 
+## Sign in once, then it runs on its own
+
+```bash
+pubkit auth login medium
+```
+
+A real browser window opens at Medium's login page. You sign in — password
+manager, MFA, device confirmation, whatever it asks for. pubkit watches for the
+post-login URL, saves the session encrypted, and closes the window.
+
+From then on, unattended:
+
+```bash
+pubkit publish content/ --to medium,devto,x --confirm
+```
+
+One browser serves the whole run, one context per platform so a Medium session
+is never presented to Substack, and sessions refresh on the way out because
+cookies rotate. Publishing only to API platforms never launches Chromium at all.
+
+pubkit sees cookies. It never sees, types or stores a password — which is both
+the right security posture and the only thing that works, since platforms
+increasingly gate login behind challenges an automation layer has no business
+trying to defeat.
+
 ## Write once
 
 ````markdown
@@ -179,6 +205,28 @@ ghost = "my_pubkit_ghost:GhostAdapter"
 Five extension points, all first-class: `pubkit.adapters`, `pubkit.renderers`,
 `pubkit.checks`, `pubkit.hooks`, and per-platform `transforms:` in config.
 
+## Install it however you like
+
+```bash
+pip install "pubkit[all]"                       # the normal way
+pipx install "pubkit[all]"                      # isolated CLI
+uv tool install "pubkit[all]"                   # same, faster
+docker run --rm -v "$PWD:/work" ghcr.io/arunsingh/pubkit validate content/
+```
+
+The Docker image ships Chromium and its system libraries, which is the part
+nobody wants to install on a CI runner by hand.
+
+As a GitHub Action, no install step at all:
+
+```yaml
+- uses: arunsingh/pubkit@v1
+  with:
+    command: plan
+    path: content/
+    platforms: medium,devto
+```
+
 ## Fit it into a workflow
 
 **GitHub Actions** — plan on every PR, publish on merge:

{pubkit-0.1.0 → pubkit-0.2.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "pubkit"
-version = "0.1.0"
+version = "0.2.0"
 description = "Publish one source to many platforms, safely. Medium, Substack, X, Dev.to, Hashnode."
 readme = "README.md"
 requires-python = ">=3.11"

{pubkit-0.1.0 → pubkit-0.2.0}/src/pubkit/__init__.py

@@ -6,7 +6,7 @@ from .core.loader import load_document, load_series  # noqa: F401
 from .core.runner import Pipeline, RunReport  # noqa: F401
 from .registry import build_adapter, list_adapters, register  # noqa: F401
 
-__version__ = "0.1.0"
+__version__ = "0.2.0"
 __all__ = [
     "Document", "Series", "Asset", "Figure", "Table", "Heading", "Paragraph", "Code",
     "Pipeline", "RunReport", "load_document", "load_series",

{pubkit-0.1.0 → pubkit-0.2.0}/src/pubkit/adapters/medium.py

@@ -68,7 +68,7 @@ class MediumAdapter(BrowserAdapter):
 
     login_url = "https://medium.com/m/signin"
     new_story_url = "https://medium.com/new-story"
-    marker_regex = r"\\[\\[\\s*IMAGE"
+    marker_regex = r"\[\[\s*IMAGE"
 
     def __init__(self, page=None, upload=None) -> None:
         super().__init__()

pubkit-0.2.0/src/pubkit/browserctl.py

@@ -0,0 +1,213 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Browser lifecycle.
+
+Browser adapters need a live Playwright page and a way to hand real bytes to a
+file input. Nothing else in the pipeline should have to know that, so this
+module owns it: one browser for the whole run, one context per platform, and
+sessions refreshed on the way out.
+
+The login flow is deliberately human-in-the-loop:
+
+    pubkit auth login medium
+      → a *visible* window opens at the platform's login page
+      → you sign in: password manager, MFA, device confirmation, whatever
+      → pubkit waits until it sees you are through, saves the session, closes
+
+pubkit sees cookies. It never sees, types or stores a password. That is not
+only the right security posture, it is the only thing that works: platforms
+increasingly gate login behind challenges an automation layer has no business
+trying to defeat.
+"""
+from __future__ import annotations
+
+import asyncio
+import logging
+from collections.abc import Sequence
+from contextlib import AsyncExitStack, asynccontextmanager
+
+from .core.auth import CredentialError, SessionStore
+
+log = logging.getLogger(__name__)
+
+#: (where to send the user, how to tell they made it)
+LOGIN_FLOWS: dict[str, tuple[str, str]] = {
+    "medium": ("https://medium.com/m/signin", "medium.com/me/"),
+    "substack": ("https://substack.com/sign-in", "substack.com/home"),
+}
+
+#: Platforms whose adapters need a page injected.
+BROWSER_PLATFORMS = set(LOGIN_FLOWS)
+
+
+def _uploader(page):
+    """Hand real bytes to a file input.
+
+    Never click a file input to open a picker — a native dialog cannot be
+    driven and it blocks the whole session. `set_input_files` sets the files
+    directly, which is why `BrowserAdapter` injects its own hidden input.
+    """
+
+    async def upload(selector: str, paths: Sequence[str]) -> None:
+        await page.set_input_files(selector, list(paths))
+
+    return upload
+
+
+class BrowserPool:
+    """One browser for the run; one context per platform.
+
+    Separate contexts matter: each platform gets only its own cookies, so a
+    Medium session is never presented to Substack.
+    """
+
+    def __init__(self, sessions: SessionStore, *, headless: bool = True, slow_mo: int = 0) -> None:
+        self.sessions = sessions
+        self.headless = headless
+        self.slow_mo = slow_mo
+        self._stack = AsyncExitStack()
+        self._pw = None
+        self._browser = None
+        self._contexts: dict[str, object] = {}
+
+    async def __aenter__(self) -> BrowserPool:
+        from playwright.async_api import async_playwright
+
+        self._pw = await self._stack.enter_async_context(async_playwright())
+        self._browser = await self._pw.chromium.launch(headless=self.headless, slow_mo=self.slow_mo)
+        return self
+
+    async def __aexit__(self, *exc) -> None:
+        for platform, ctx in self._contexts.items():
+            # Cookies rotate. Refreshing on the way out is what stops a session
+            # silently expiring between runs.
+            try:
+                self.sessions.save(platform, await ctx.storage_state())
+            except Exception:  # noqa: BLE001
+                log.debug("could not refresh the %s session", platform)
+            try:
+                await ctx.close()
+            except Exception:  # noqa: BLE001
+                pass
+        if self._browser:
+            await self._browser.close()
+        await self._stack.aclose()
+
+    async def page_for(self, platform: str):
+        """A page carrying `platform`'s saved session, plus its uploader."""
+        if platform in self._contexts:
+            ctx = self._contexts[platform]
+            return ctx.pages[0], _uploader(ctx.pages[0])
+
+        state = self.sessions.load(platform)
+        if state is None:
+            raise CredentialError(
+                f"no saved {platform} session.\n"
+                f"  Run:  pubkit auth login {platform}\n"
+                f"  A browser window opens, you sign in yourself, and pubkit keeps\n"
+                f"  only the session — it never asks for your password."
+            )
+        ctx = await self._browser.new_context(
+            storage_state=state, viewport={"width": 1440, "height": 900}
+        )
+        page = await ctx.new_page()
+        self._contexts[platform] = ctx
+        return page, _uploader(page)
+
+
+@asynccontextmanager
+async def attached(adapters: Sequence, sessions: SessionStore, *, headless: bool = True):
+    """Yield `adapters` with browser ones wired to a live page.
+
+    This is the seam that was missing: the runner calls `adapter.authenticate()`
+    and friends, but a `MediumAdapter` built by the registry has `_page = None`
+    until something puts a page in it. That something is here.
+
+    API adapters pass through untouched, and no browser is launched at all if
+    none of the adapters need one — publishing to Dev.to should not pay for
+    Chromium.
+    """
+    needs_browser = [a for a in adapters if getattr(a, "name", None) in BROWSER_PLATFORMS]
+    if not needs_browser:
+        yield list(adapters)
+        return
+
+    # Check every session BEFORE a browser exists. A missing login is the most
+    # common reason a publish cannot start, and spending a Chromium launch to
+    # then say "run pubkit auth login" is both slow and the wrong order — it
+    # also leaves a browser process to clean up on the failure path.
+    missing = [a.name for a in needs_browser if sessions.load(a.name) is None]
+    if missing:
+        raise CredentialError(
+            "no saved session for: " + ", ".join(missing) + ".\n"
+            + "\n".join(f"  Run:  pubkit auth login {p}" for p in missing)
+            + "\n  A browser window opens, you sign in yourself, and pubkit keeps\n"
+            "  only the session — it never asks for your password."
+        )
+
+    async with BrowserPool(sessions, headless=headless) as pool:
+        for adapter in needs_browser:
+            page, upload = await pool.page_for(adapter.name)
+            adapter._page = page
+            adapter._upload = upload
+            log.debug("attached a browser page to %s", adapter.name)
+        yield list(adapters)
+
+
+async def interactive_login(platform: str, sessions: SessionStore, timeout: float = 300.0) -> None:
+    """Open a visible window, wait for the human, save the session."""
+    from playwright.async_api import async_playwright
+
+    login_url, success_marker = LOGIN_FLOWS.get(
+        platform, (f"https://{platform}.com/login", f"{platform}.com")
+    )
+
+    async with async_playwright() as pw:
+        browser = await pw.chromium.launch(headless=False)
+        ctx = await browser.new_context(viewport={"width": 1280, "height": 900})
+        page = await ctx.new_page()
+        await page.goto(login_url)
+
+        print(f"\n  A browser window is open at {login_url}")
+        print("  Sign in there — password manager, MFA, all of it.")
+        print(f"  Waiting up to {timeout / 60:.0f} minutes. Close this with Ctrl-C to cancel.\n")
+
+        deadline = asyncio.get_event_loop().time() + timeout
+        while asyncio.get_event_loop().time() < deadline:
+            try:
+                url = page.url
+            except Exception as exc:  # window closed by the user
+                await browser.close()
+                raise CredentialError(
+                    f"{platform} login window was closed before sign-in completed"
+                ) from exc
+
+            if success_marker in url:
+                await asyncio.sleep(2)  # let the last auth cookie land
+                sessions.save(platform, await ctx.storage_state())
+                await browser.close()
+                return
+            await asyncio.sleep(1.5)
+
+        await browser.close()
+        raise TimeoutError(
+            f"no {platform} sign-in detected within {timeout / 60:.0f} minutes. "
+            f"pubkit watches for a URL containing {success_marker!r}."
+        )
+
+
+async def verify_session(platform: str, sessions: SessionStore, *, headless: bool = True) -> bool:
+    """Is the saved session still good? Cheaper to find out now than mid-publish."""
+    _, success_marker = LOGIN_FLOWS.get(platform, ("", platform))
+    probe = {
+        "medium": "https://medium.com/me/stories/drafts",
+        "substack": "https://substack.com/home",
+    }.get(platform)
+    if probe is None or sessions.load(platform) is None:
+        return False
+
+    async with BrowserPool(sessions, headless=headless) as pool:
+        page, _ = await pool.page_for(platform)
+        await page.goto(probe, wait_until="domcontentloaded")
+        await asyncio.sleep(1.5)
+        return "signin" not in page.url and "sign-in" not in page.url

{pubkit-0.1.0 → pubkit-0.2.0}/src/pubkit/cli.py

@@ -147,11 +147,17 @@ def publish(
         )
 
     pipe = Pipeline(StateStore())
+    live = confirm and not draft_only
 
     async def go():
-        if hasattr(target, "documents"):
-            return await pipe.run_series(target, adapters, ctx_for, publish=confirm and not draft_only)
-        return await pipe.run([target], adapters, ctx_for, publish=confirm and not draft_only)
+        # Browser adapters get a live page here and nowhere else. API-only runs
+        # never launch Chromium.
+        from .browserctl import attached
+
+        async with attached(adapters, sessions, headless=headless) as ready:
+            if hasattr(target, "documents"):
+                return await pipe.run_series(target, ready, ctx_for, publish=live)
+            return await pipe.run([target], ready, ctx_for, publish=live)
 
     report = asyncio.run(go())
     console.print(f"\n[bold]{report.run_id}[/]")
@@ -254,10 +260,12 @@ def auth_login(
     Browser platforms: a real browser window opens and you sign in yourself —
     pubkit stores only the resulting session, never a password.
     """
+    from .browserctl import BROWSER_PLATFORMS
+
     tokens = TokenStore()
-    adapter = build_adapter(platform)
+    build_adapter(platform)  # fail fast on an unknown platform
 
-    if adapter.capabilities.image_upload != "browser_paste" and adapter.name not in ("substack",):
+    if platform not in BROWSER_PLATFORMS:
         if token is None:
             token = typer.prompt(f"{platform} API token", hide_input=True)
         tokens.set(platform, token.strip())
@@ -266,12 +274,15 @@ def auth_login(
 
     from .browserctl import interactive_login
 
+    try:
+        asyncio.run(interactive_login(platform, SessionStore()))
+    except Exception as exc:  # noqa: BLE001
+        console.print(f"[red]{exc}[/]")
+        raise typer.Exit(1) from exc
     console.print(
-        f"Opening a browser window for {platform}. Sign in there — including MFA — "
-        "and pubkit will save the session when it sees you are logged in."
+        f"[green]saved {platform} session (encrypted)[/]\n"
+        f"Verify any time with: pubkit auth verify {platform}"
     )
-    asyncio.run(interactive_login(platform, SessionStore()))
-    console.print(f"[green]saved {platform} session (encrypted)[/]")
 
 
 @auth_app.command("logout")
@@ -281,6 +292,24 @@ def auth_logout(platform: str = typer.Argument(...)):
     console.print(f"[green]forgot all {platform} credentials[/]")
 
 
+@auth_app.command("verify")
+def auth_verify(platform: str = typer.Argument(...)):
+    """Check a saved session is still valid — cheaper now than mid-publish."""
+    from .browserctl import BROWSER_PLATFORMS, verify_session
+
+    if platform not in BROWSER_PLATFORMS:
+        tok = TokenStore().get(platform) or TokenStore().get(platform, "bearer")
+        console.print(f"[green]{platform}: token present[/]" if tok else f"[red]{platform}: no token[/]")
+        raise typer.Exit(0 if tok else 1)
+
+    ok = asyncio.run(verify_session(platform, SessionStore()))
+    if ok:
+        console.print(f"[green]{platform}: session valid[/]")
+    else:
+        console.print(f"[red]{platform}: session missing or expired[/] — run `pubkit auth login {platform}`")
+    raise typer.Exit(0 if ok else 1)
+
+
 @auth_app.command("list")
 def auth_list():
     tokens, sessions = TokenStore(), SessionStore()

pubkit-0.2.0/src/pubkit/core/assets.py

@@ -0,0 +1,96 @@
+# Copyright 2026 The pubkit Authors
+# SPDX-License-Identifier: Apache-2.0
+"""Materialise the assets a plan promised.
+
+The planner says "8 tables → images" and lists the asset ids. Something has to
+actually produce those files, and it has to happen per-platform, because the
+same document keeps native tables on Dev.to and needs images on Medium.
+
+This runs between planning and publishing, and is cached on content: a table
+whose cells have not changed keeps its rendered file, so a re-run does not
+re-render or re-upload it.
+"""
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+
+from ..render.tables import RenderUnavailable, TableStyle, render_table, table_asset_id
+from .capabilities import Capabilities
+from .ir import Asset, Document, Figure, Table
+
+log = logging.getLogger(__name__)
+
+
+def materialise(
+    doc: Document,
+    caps: Capabilities,
+    workdir: Path,
+    *,
+    style: TableStyle | None = None,
+) -> Document:
+    """Return a copy of `doc` adapted to what `caps` can actually render.
+
+    Tables become Figures on platforms without table support; everything else is
+    left alone. The original document is never mutated — the same IR has to
+    serve every platform in the same run.
+    """
+    if caps.tables or not doc.tables:
+        return doc
+
+    if caps.image_upload == "none":
+        log.warning(
+            "%s supports neither tables nor images; %d table(s) will degrade to lists",
+            getattr(caps, "name", "platform"),
+            len(doc.tables),
+        )
+        return doc
+
+    out_dir = workdir / "rendered"
+    new_blocks: list = []
+    new_assets = dict(doc.assets)
+    rendered = 0
+    reused = 0
+    n = 0
+
+    for block in doc.blocks:
+        if not isinstance(block, Table):
+            new_blocks.append(block)
+            continue
+
+        n += 1
+        aid = table_asset_id(block, n)
+        path = out_dir / f"{aid}.png"
+
+        if not path.exists():
+            try:
+                render_table(block, path, style)
+                rendered += 1
+            except RenderUnavailable:
+                # Better a readable list than a crash at publish time.
+                log.warning("Pillow missing — table %d degrades to a list", n)
+                from .ir import ListBlock
+
+                new_blocks.append(
+                    ListBlock(
+                        ordered=False,
+                        items=[
+                            " · ".join(f"{h}: {c}" for h, c in zip(block.header, row, strict=False))
+                            for row in block.rows
+                        ],
+                    )
+                )
+                continue
+        else:
+            reused += 1
+
+        new_assets[aid] = Asset(
+            id=aid, path=path, alt=block.caption or "table", generated_from=f"table[{n}]"
+        )
+        new_blocks.append(Figure(asset_id=aid, caption=block.caption, alt=block.caption or "table"))
+
+    if rendered or reused:
+        log.info("tables → images: %d rendered, %d reused from cache", rendered, reused)
+
+    adapted = doc.model_copy(update={"blocks": new_blocks, "assets": new_assets})
+    return adapted

{pubkit-0.1.0 → pubkit-0.2.0}/src/pubkit/core/browser.py

@@ -221,7 +221,7 @@ class BrowserAdapter(BaseAdapter):
 
     selectors: EditorSelectors
     login_url: str = ""
-    marker_regex: str = r"\\[\\[\\s*IMAGE"
+    marker_regex: str = r"\[\[\s*IMAGE"   # a JS RegExp source string, not a Python pattern
 
     def __init__(self) -> None:
         super().__init__()