drawlib 0.3.0__tar.gz → 0.3.2__tar.gz

drawlib-0.3.0/docs/README_PYPI.md → drawlib-0.3.2/PKG-INFO

@@ -1,3 +1,25 @@
+Metadata-Version: 2.3
+Name: drawlib
+Version: 0.3.2
+Summary: Python drawing library. Illustration as Code.
+Author: Yuichi Ito
+Author-email: Yuichi Ito <yuichi@yuichi.com>
+License: Apache-2.0
+Requires-Dist: matplotlib>=3.8
+Requires-Dist: pydantic>=2.8
+Requires-Dist: pygments>=2.18
+Requires-Dist: markdown-it-py>=3.0
+Requires-Dist: jinja2>=3.1
+Requires-Dist: typer>=0.12.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: playwright>=1.49.0
+Requires-Dist: python-docx>=1.2.0
+Requires-Dist: python-pptx>=1.0.2
+Requires-Python: >=3.11
+Project-URL: Homepage, https://www.drawlib.com
+Project-URL: Repository, https://github.com/yuichi110/drawlib
+Description-Content-Type: text/markdown
+
 # Drawlib
 
 **Pure-Python Library for "Illustration as Code" & "Illustrated Documentation as Code"**
@@ -36,7 +58,7 @@ Compose presentation-ready infographics (`drawlib.smartarts`) and quantitative d
 ![Charts and SmartArts Showcase](https://www.drawlib.com/pypi_images/03_showcase_charts_smartarts.png)
 
 - **SmartArts (`drawlib.smartarts`)**: `ChevronProcess`, `Cycle`, `Table`, `TreeNode`, `MindMapNode`, `Pyramid`, `BoxList`, `BulletPoints`, `GridLayout`, and syntax-highlighted `SourceCode`.
-- **Charts (`drawlib.charts`)**: Pure-Python `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `ScatterChart`, and `GanttChart` styled with the same design tokens as your diagrams.
+- **Charts (`drawlib.charts`)**: Pure-Python `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `ScatterChart`, `GanttChart`, and `HeatmapChart` / `HeatmapOverlay` styled with the same design tokens as your diagrams.
 
 ---
 
@@ -63,8 +85,8 @@ Write Markdown files with embedded ```` ```drawlib ```` code blocks. A single `d
 
 - **4 Project Scaffolds (`drawlib init <type>`)**:
   - `drawlib init site`: Multi-page documentation website (`docs_html/`), GitHub Markdown (`docs/`), and PDF.
-  - `drawlib init doc`: Linear technical specification / whitepaper (`*_html/`, `*_markdown/`, `*.pdf`).
-  - `drawlib init slide`: 16:9 presentation slide deck with native SVG text and keyboard navigation (`slide_html/`, `slide.pdf`).
+  - `drawlib init doc`: Linear technical specification / whitepaper (`*_html/`, `*_markdown/`, `*.pdf`, plus on-demand editable MS Word `*.docx` via `drawlib build docx`).
+  - `drawlib init slide`: 16:9 presentation slide deck with native SVG text, Presenter View, and keyboard navigation (`slide_html/`, `slide.pdf`, plus on-demand editable MS PowerPoint `slide.pptx` via `drawlib build pptx`).
   - `drawlib init images`: Standalone batch Python illustration scripts (`images_src/` -> `images/`).
 
 ---
@@ -79,7 +101,7 @@ Drawlib is engineered from the ground up for **AI-native documentation and diagr
   2. **Code Synthesis & Grid Preview (`drawlib show -g`)**: The agent writes Python drawing blocks and Markdown prose, then renders a headless preview with a coordinate grid overlay.
   3. **Multimodal Inspection & Self-Repair**: The agent visually inspects the rendered PNG for text clipping, overlapping labels, or style imbalances, repairing coordinates and styles autonomously until the diagram passes inspection.
 - **Human Outer Loop (Intent & Review)**:
-  - The developer stays focused on high-level architecture and intent—providing initial goals, reviewing the compiled **Published Docs** (HTML / PDF / GitHub MD / Slide), and iterating on direction without ever nudging pixels in a GUI tool.
+  - The developer stays focused on high-level architecture and intent—providing initial goals, reviewing the compiled **Published Docs** (HTML / PDF / MS Word / GitHub MD / Slide / MS PowerPoint), and iterating on direction without ever nudging pixels in a GUI tool.
 
 ---
 
@@ -89,14 +111,13 @@ Install `drawlib` from PyPI using `pip` or `uv`:
 
 ```bash
 pip install drawlib
+# or: uv add drawlib
 ```
 
-To enable headless PDF export for documentation sites, linear documents, and slide decks, install the `[pdf]` extra and Chromium:
+PDF, MS Word (`.docx`), and MS PowerPoint (`.pptx`) export work out of the box—`playwright`, `python-docx`, and `python-pptx` are standard dependencies, and headless Chromium (`chromium-headless-shell`) is downloaded automatically on your first `drawlib build pdf` or `drawlib build pptx` run.
 
-```bash
-pip install "drawlib[pdf]"
-playwright install chromium
-```
+- **Offline / Air-Gapped / CI Environments**: Pre-download all fonts, icons, maps, and headless Chromium ahead of time with `drawlib cache download --all` (or headless Chromium only with `drawlib cache download --browser`).
+- **Minimal Linux Containers** (e.g., `python:3.12-slim` lacking OS shared libraries such as `libnss3` or `libgbm1`): Install OS browser dependencies once via `playwright install-deps chromium` (or `playwright install --with-deps --only-shell chromium`).
 
 Verify the installation:
 
@@ -201,6 +222,10 @@ Compile or preview with the `drawlib` CLI:
 # Build HTML site, GitHub Markdown, or PDF
 ./docs_src/build.sh
 
+# Optional on-demand export to editable MS Word (.docx) or MS PowerPoint (.pptx)
+drawlib build docx doc_src/ -o spec.docx --generate-index
+drawlib build pptx slide_src/ -o deck.pptx
+
 # Launch local HTTP server with broken-link check at http://localhost:8000
 drawlib serve docs_html/
 
@@ -215,11 +240,11 @@ drawlib show docs_src/index.md service_routing.png -g -o preview_grid.png
 | Command | Description |
 | :--- | :--- |
 | `drawlib init <site\|doc\|slide\|images>` | Scaffold a new documentation, slide deck, or image project |
-| `drawlib build <html\|markdown\|pdf\|image>` | Compile source files into HTML, Markdown, PDF, or PNG/WebP images |
+| `drawlib build <html\|markdown\|pdf\|docx\|slide\|pptx\|image>` | Compile source files into HTML, Markdown, PDF, MS Word (`.docx`), HTML Slides, MS PowerPoint (`.pptx`), or PNG/WebP images |
 | `drawlib serve <html_dir> [--check]` | Start a local HTTP server for built HTML docs/slides with pre-flight link checks |
 | `drawlib show <file> [target] [-g]` | Render and inspect a single script or embedded Markdown diagram (with optional grid) |
 | `drawlib rules show [topic]` | On-demand CLI reference for AI agents to look up detailed API specs & best practices (`overview`, `style-guide`, `api`, `lib-*`) |
-| `drawlib cache <list\|download\|clear>` | Manage local font and icon asset caches (supports offline pre-caching via `--all`) |
+| `drawlib cache <list\|download\|clear>` | Manage local font, icon, map, and headless Chromium caches (supports offline pre-caching via `--all` or `--browser`) |
 
 ---
 

drawlib-0.3.0/PKG-INFO → drawlib-0.3.2/docs/README_PYPI.md

@@ -1,24 +1,3 @@
-Metadata-Version: 2.3
-Name: drawlib
-Version: 0.3.0
-Summary: Python drawing library. Illustration as Code.
-Author: Yuichi Ito
-Author-email: Yuichi Ito <yuichi@yuichi.com>
-License: Apache-2.0
-Requires-Dist: matplotlib>=3.8
-Requires-Dist: pydantic>=2.8
-Requires-Dist: pygments>=2.18
-Requires-Dist: markdown-it-py>=3.0
-Requires-Dist: jinja2>=3.1
-Requires-Dist: typer>=0.12.0
-Requires-Dist: rich>=13.0.0
-Requires-Dist: playwright>=1.40.0 ; extra == 'pdf'
-Requires-Python: >=3.11
-Project-URL: Homepage, https://www.drawlib.com
-Project-URL: Repository, https://github.com/yuichi110/drawlib
-Provides-Extra: pdf
-Description-Content-Type: text/markdown
-
 # Drawlib
 
 **Pure-Python Library for "Illustration as Code" & "Illustrated Documentation as Code"**
@@ -57,7 +36,7 @@ Compose presentation-ready infographics (`drawlib.smartarts`) and quantitative d
 ![Charts and SmartArts Showcase](https://www.drawlib.com/pypi_images/03_showcase_charts_smartarts.png)
 
 - **SmartArts (`drawlib.smartarts`)**: `ChevronProcess`, `Cycle`, `Table`, `TreeNode`, `MindMapNode`, `Pyramid`, `BoxList`, `BulletPoints`, `GridLayout`, and syntax-highlighted `SourceCode`.
-- **Charts (`drawlib.charts`)**: Pure-Python `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `ScatterChart`, and `GanttChart` styled with the same design tokens as your diagrams.
+- **Charts (`drawlib.charts`)**: Pure-Python `BarChart`, `LineChart`, `AreaChart`, `PieChart`, `RadarChart`, `ScatterChart`, `GanttChart`, and `HeatmapChart` / `HeatmapOverlay` styled with the same design tokens as your diagrams.
 
 ---
 
@@ -84,8 +63,8 @@ Write Markdown files with embedded ```` ```drawlib ```` code blocks. A single `d
 
 - **4 Project Scaffolds (`drawlib init <type>`)**:
   - `drawlib init site`: Multi-page documentation website (`docs_html/`), GitHub Markdown (`docs/`), and PDF.
-  - `drawlib init doc`: Linear technical specification / whitepaper (`*_html/`, `*_markdown/`, `*.pdf`).
-  - `drawlib init slide`: 16:9 presentation slide deck with native SVG text and keyboard navigation (`slide_html/`, `slide.pdf`).
+  - `drawlib init doc`: Linear technical specification / whitepaper (`*_html/`, `*_markdown/`, `*.pdf`, plus on-demand editable MS Word `*.docx` via `drawlib build docx`).
+  - `drawlib init slide`: 16:9 presentation slide deck with native SVG text, Presenter View, and keyboard navigation (`slide_html/`, `slide.pdf`, plus on-demand editable MS PowerPoint `slide.pptx` via `drawlib build pptx`).
   - `drawlib init images`: Standalone batch Python illustration scripts (`images_src/` -> `images/`).
 
 ---
@@ -100,7 +79,7 @@ Drawlib is engineered from the ground up for **AI-native documentation and diagr
   2. **Code Synthesis & Grid Preview (`drawlib show -g`)**: The agent writes Python drawing blocks and Markdown prose, then renders a headless preview with a coordinate grid overlay.
   3. **Multimodal Inspection & Self-Repair**: The agent visually inspects the rendered PNG for text clipping, overlapping labels, or style imbalances, repairing coordinates and styles autonomously until the diagram passes inspection.
 - **Human Outer Loop (Intent & Review)**:
-  - The developer stays focused on high-level architecture and intent—providing initial goals, reviewing the compiled **Published Docs** (HTML / PDF / GitHub MD / Slide), and iterating on direction without ever nudging pixels in a GUI tool.
+  - The developer stays focused on high-level architecture and intent—providing initial goals, reviewing the compiled **Published Docs** (HTML / PDF / MS Word / GitHub MD / Slide / MS PowerPoint), and iterating on direction without ever nudging pixels in a GUI tool.
 
 ---
 
@@ -110,14 +89,13 @@ Install `drawlib` from PyPI using `pip` or `uv`:
 
 ```bash
 pip install drawlib
+# or: uv add drawlib
 ```
 
-To enable headless PDF export for documentation sites, linear documents, and slide decks, install the `[pdf]` extra and Chromium:
+PDF, MS Word (`.docx`), and MS PowerPoint (`.pptx`) export work out of the box—`playwright`, `python-docx`, and `python-pptx` are standard dependencies, and headless Chromium (`chromium-headless-shell`) is downloaded automatically on your first `drawlib build pdf` or `drawlib build pptx` run.
 
-```bash
-pip install "drawlib[pdf]"
-playwright install chromium
-```
+- **Offline / Air-Gapped / CI Environments**: Pre-download all fonts, icons, maps, and headless Chromium ahead of time with `drawlib cache download --all` (or headless Chromium only with `drawlib cache download --browser`).
+- **Minimal Linux Containers** (e.g., `python:3.12-slim` lacking OS shared libraries such as `libnss3` or `libgbm1`): Install OS browser dependencies once via `playwright install-deps chromium` (or `playwright install --with-deps --only-shell chromium`).
 
 Verify the installation:
 
@@ -222,6 +200,10 @@ Compile or preview with the `drawlib` CLI:
 # Build HTML site, GitHub Markdown, or PDF
 ./docs_src/build.sh
 
+# Optional on-demand export to editable MS Word (.docx) or MS PowerPoint (.pptx)
+drawlib build docx doc_src/ -o spec.docx --generate-index
+drawlib build pptx slide_src/ -o deck.pptx
+
 # Launch local HTTP server with broken-link check at http://localhost:8000
 drawlib serve docs_html/
 
@@ -236,11 +218,11 @@ drawlib show docs_src/index.md service_routing.png -g -o preview_grid.png
 | Command | Description |
 | :--- | :--- |
 | `drawlib init <site\|doc\|slide\|images>` | Scaffold a new documentation, slide deck, or image project |
-| `drawlib build <html\|markdown\|pdf\|image>` | Compile source files into HTML, Markdown, PDF, or PNG/WebP images |
+| `drawlib build <html\|markdown\|pdf\|docx\|slide\|pptx\|image>` | Compile source files into HTML, Markdown, PDF, MS Word (`.docx`), HTML Slides, MS PowerPoint (`.pptx`), or PNG/WebP images |
 | `drawlib serve <html_dir> [--check]` | Start a local HTTP server for built HTML docs/slides with pre-flight link checks |
 | `drawlib show <file> [target] [-g]` | Render and inspect a single script or embedded Markdown diagram (with optional grid) |
 | `drawlib rules show [topic]` | On-demand CLI reference for AI agents to look up detailed API specs & best practices (`overview`, `style-guide`, `api`, `lib-*`) |
-| `drawlib cache <list\|download\|clear>` | Manage local font and icon asset caches (supports offline pre-caching via `--all`) |
+| `drawlib cache <list\|download\|clear>` | Manage local font, icon, map, and headless Chromium caches (supports offline pre-caching via `--all` or `--browser`) |
 
 ---
 

{drawlib-0.3.0 → drawlib-0.3.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "drawlib"
-version = "0.3.0"
+version = "0.3.2"
 description = "Python drawing library. Illustration as Code."
 readme = "docs/README_PYPI.md"
 requires-python = ">=3.11"
@@ -18,6 +18,9 @@ dependencies = [
     "jinja2>=3.1",
     "typer>=0.12.0",
     "rich>=13.0.0",
+    "playwright>=1.49.0",
+    "python-docx>=1.2.0",
+    "python-pptx>=1.0.2",
 ]
 
 [project.urls]
@@ -27,11 +30,6 @@ Repository = "https://github.com/yuichi110/drawlib"
 [project.scripts]
 drawlib = "drawlib._cli.main:main"
 
-[project.optional-dependencies]
-pdf = [
-    "playwright>=1.40.0",
-]
-
 [dependency-groups]
 dev = [
     "types-pillow>=10.2.0.20240311",
@@ -44,7 +42,6 @@ dev = [
     "typer>=0.12.0",
     "rich>=13.0.0",
     "pytest-xdist>=3.8.0",
-    "playwright>=1.40.0",
 ]
 
 [tool.ruff]

{drawlib-0.3.0 → drawlib-0.3.2}/src/drawlib/__init__.py

@@ -14,44 +14,60 @@ from __future__ import annotations
 import importlib
 from typing import TYPE_CHECKING, Any, Final
 
-from drawlib._core.l1_core import LIB_NAME, LIB_VERSION
+from drawlib._core.l1_core._const import LIB_NAME, LIB_VERSION
 
 __version__: Final[str] = LIB_VERSION
 
 if TYPE_CHECKING:
     from drawlib import (
+        anim,
+        canvas,
+        charts,
+        diagrams,
+        fonts,
+        graph,
+        icons,
+        images,
+        lines,
+        math,
+        preset_colors,
+        preset_styles,
+        shapes,
+        slide,
+        smartarts,
+        styles,
+        text,
         tools,
+        types,
+        utils,
     )
 
-from drawlib import (
-    anim,
-    canvas,
-    charts,
-    diagrams,
-    fonts,
-    graph,
-    icons,
-    images,
-    lines,
-    math,
-    preset_colors,
-    preset_styles,
-    shapes,
-    slide,
-    smartarts,
-    styles,
-    text,
-    types,
-    utils,
-)
-
-_LAZY_MODULES: dict[str, str] = {
+_LAZY_MODULES: Final[dict[str, str]] = {
+    "anim": "drawlib.anim",
+    "canvas": "drawlib.canvas",
+    "charts": "drawlib.charts",
+    "diagrams": "drawlib.diagrams",
+    "fonts": "drawlib.fonts",
+    "graph": "drawlib.graph",
+    "icons": "drawlib.icons",
+    "images": "drawlib.images",
+    "lines": "drawlib.lines",
+    "math": "drawlib.math",
+    "preset_colors": "drawlib.preset_colors",
+    "preset_styles": "drawlib.preset_styles",
+    "shapes": "drawlib.shapes",
+    "slide": "drawlib.slide",
+    "smartarts": "drawlib.smartarts",
+    "styles": "drawlib.styles",
+    "text": "drawlib.text",
     "tools": "drawlib.tools",
+    "types": "drawlib.types",
+    "utils": "drawlib.utils",
 }
 
 
 def __getattr__(name: str) -> Any:  # noqa: ANN401
-    """Lazy-load heavy modules only when explicitly accessed."""
+    """Lazy-load submodules on first attribute access (PEP 562)."""
     if name in _LAZY_MODULES:
         module = importlib.import_module(_LAZY_MODULES[name])
         globals()[name] = module

{drawlib-0.3.0 → drawlib-0.3.2}/src/drawlib/_anim/_animation.py

@@ -17,8 +17,8 @@ from contextlib import contextmanager
 from typing import Literal
 
 from PIL import Image
-from pydantic import validate_call
 
+from drawlib._core.l1_core import validate_call
 from drawlib._core.l2_types import PosInt
 from drawlib._core.l4_canvas import canvas
 

{drawlib-0.3.0 → drawlib-0.3.2}/src/drawlib/_builder/_common/__init__.py

@@ -11,6 +11,11 @@
 
 from __future__ import annotations
 
+from drawlib._builder._common.browser import (
+    import_sync_playwright,
+    install_headless_chromium,
+    launch_headless_chromium,
+)
 from drawlib._builder._common.cache import (
     BuildImageCache,
     CliImageCache,
@@ -23,6 +28,11 @@ from drawlib._builder._common.cache_manager import (
     download_cache,
     list_cache,
 )
+from drawlib._builder._common.office import (
+    ensure_static_office_image,
+    normalize_opc_zip_timestamps,
+    resolve_office_datetime,
+)
 from drawlib._builder._common.progress import (
     BAR_WIDTH,
     FileBuildProgress,
@@ -44,13 +54,19 @@ __all__ = [
     "clear_cache",
     "clear_image_cache",
     "download_cache",
+    "ensure_static_office_image",
     "format_duplicate_output_error",
     "format_progress_line",
     "hash_file",
     "hash_text",
+    "import_sync_playwright",
+    "install_headless_chromium",
+    "launch_headless_chromium",
     "list_cache",
     "load_styles",
     "load_styles_and_utils",
     "load_utils",
+    "normalize_opc_zip_timestamps",
+    "resolve_office_datetime",
     "resolve_styles_and_utils",
 ]

drawlib-0.3.2/src/drawlib/_builder/_common/browser.py

@@ -0,0 +1,267 @@
+# Copyright (c) 2026 Yuichi Ito (yuichi@yuichi.com)
+#
+# This software is licensed under the Apache License, Version 2.0.
+# For more information, please visit: https://github.com/yuichi110/drawlib
+#
+# This software is provided "as is", without warranty of any kind,
+# express or implied, including but not limited to the warranties of
+# merchantability, fitness for a particular purpose and noninfringement.
+
+"""Shared Playwright headless Chromium launcher and on-demand installer."""
+
+from __future__ import annotations
+
+import contextlib
+import os
+import subprocess  # noqa: S404
+import sys
+import tempfile
+import threading
+from collections.abc import Callable, Iterator, Sequence
+from pathlib import Path
+from typing import TYPE_CHECKING, Final
+
+from drawlib._core.l1_core import logger
+
+if TYPE_CHECKING:
+    from playwright.sync_api import Browser, Playwright, PlaywrightContextManager
+
+_INSTALL_ARGS: Final[tuple[str, ...]] = ("install", "--only-shell", "chromium")
+_DEFAULT_CHROMIUM_ARGS: Final[tuple[str, ...]] = (
+    "--font-render-hinting=medium",
+    "--enable-font-antialiasing",
+)
+_INSTALL_THREAD_LOCK = threading.Lock()
+
+
+def _resolve_lock_file_paths() -> list[Path]:
+    """Return candidate per-user lock file paths in priority order."""
+    candidates: list[Path] = []
+    browsers_path = os.environ.get("PLAYWRIGHT_BROWSERS_PATH", "").strip()
+    if browsers_path and browsers_path != "0":
+        candidates.append(Path(browsers_path).expanduser() / ".drawlib_browser_install.lock")
+
+    if sys.platform == "win32":
+        local_app_data = os.environ.get("LOCALAPPDATA", str(Path.home()))
+        candidates.append(Path(local_app_data) / "drawlib" / "playwright_install.lock")
+    else:
+        xdg_cache = os.environ.get("XDG_CACHE_HOME", str(Path.home() / ".cache"))
+        candidates.append(Path(xdg_cache) / "drawlib" / "playwright_install.lock")
+
+    uid_suffix = str(os.getuid()) if hasattr(os, "getuid") else "user"
+    candidates.append(Path(tempfile.gettempdir()) / f"drawlib_{uid_suffix}" / "playwright_install.lock")
+    return candidates
+
+
+@contextlib.contextmanager
+def _browser_install_lock() -> Iterator[None]:
+    """Serialize concurrent headless Chromium downloads across threads and processes."""
+    with _INSTALL_THREAD_LOCK:
+        lock_handle = None
+        for lock_path in _resolve_lock_file_paths():
+            try:
+                lock_path.parent.mkdir(parents=True, exist_ok=True)
+                lock_handle = lock_path.open("a+", encoding="utf-8")
+                break
+            except OSError:
+                continue
+
+        if lock_handle is None:
+            yield
+            return
+
+        locked = False
+        try:
+            with contextlib.suppress(ImportError, OSError):
+                import fcntl
+
+                fcntl.flock(lock_handle.fileno(), fcntl.LOCK_EX)
+                locked = True
+            yield
+        finally:
+            if locked:
+                with contextlib.suppress(ImportError, OSError):
+                    import fcntl
+
+                    fcntl.flock(lock_handle.fileno(), fcntl.LOCK_UN)
+            with contextlib.suppress(OSError):
+                lock_handle.close()
+
+
+def _is_missing_browser_executable_error(err: BaseException) -> bool:
+    """Return True if Playwright failed because the browser binary is not downloaded yet."""
+    err_lower = str(err).lower()
+    return (
+        "executable doesn't exist" in err_lower
+        or "looks like playwright was just installed or updated" in err_lower
+    )
+
+
+def _is_missing_system_deps_error(err: BaseException) -> bool:
+    """Return True if Chromium failed due to missing Linux OS shared libraries."""
+    err_lower = str(err).lower()
+    return any(
+        marker in err_lower
+        for marker in (
+            "host system is missing dependencies",
+            "error while loading shared libraries",
+            "cannot open shared object file",
+            "install-deps",
+        )
+    )
+
+
+def _format_missing_playwright_error(context_label: str) -> str:
+    """Format an actionable error message when the playwright Python package is missing."""
+    return (
+        f"\n[{context_label} Error]\n"
+        f"{context_label} requires the 'playwright' package.\n\n"
+        "Reinstall drawlib or install Playwright:\n"
+        "  - For uv users:\n"
+        "      uv sync\n"
+        "    (or: uv add playwright)\n\n"
+        "  - For pip users:\n"
+        "      pip install drawlib\n"
+        "    (or: pip install playwright)\n"
+    )
+
+
+def _format_missing_system_deps_error(context_label: str, err: BaseException) -> str:
+    """Format an actionable error message for CI / minimal Linux containers missing OS libraries."""
+    return (
+        f"\n[{context_label} Error]\n"
+        "Headless Chromium could not start because required OS shared libraries are missing\n"
+        "(common in minimal Linux containers and CI pipelines).\n\n"
+        "Install the required system dependencies (requires root/sudo privileges):\n"
+        "  - For uv users:\n"
+        "      uv run playwright install --with-deps chromium\n"
+        "    (or OS libraries only: uv run playwright install-deps chromium)\n\n"
+        "  - For pip / Docker users:\n"
+        "      playwright install --with-deps chromium\n"
+        "    (or OS libraries only: playwright install-deps chromium)\n\n"
+        f"Details:\n{err}"
+    )
+
+
+def _format_missing_browser_error(context_label: str, detail: str = "") -> str:
+    """Format an actionable error message when headless Chromium cannot be downloaded."""
+    extra = f"\nDetails:\n{detail}\n" if detail else ""
+    return (
+        f"\n[{context_label} Error]\n"
+        "Headless Chromium browser is not installed and could not be downloaded automatically.\n\n"
+        "To pre-download headless Chromium manually, run:\n"
+        "  - Via drawlib CLI:\n"
+        "      uv run drawlib cache download --browser\n"
+        "    (or: drawlib cache download --browser)\n\n"
+        "  - Via Playwright CLI:\n"
+        "      uv run playwright install --only-shell chromium\n"
+        "    (or: playwright install --only-shell chromium)\n"
+        f"{extra}"
+    )
+
+
+def import_sync_playwright(
+    context_label: str = "PDF Export",
+) -> Callable[[], PlaywrightContextManager]:
+    """Lazily import and return `playwright.sync_api.sync_playwright`.
+
+    Args:
+        context_label (str): Human-readable feature name for error messages.
+
+    Returns:
+        Callable[[], PlaywrightContextManager]: Playwright sync context manager factory.
+
+    Raises:
+        RuntimeError: If the `playwright` package is not installed.
+    """
+    try:
+        from playwright.sync_api import sync_playwright
+    except ImportError as err:
+        raise RuntimeError(_format_missing_playwright_error(context_label)) from err
+    return sync_playwright
+
+
+def install_headless_chromium(context_label: str = "Browser Setup") -> None:
+    """Download Playwright's lightweight `chromium-headless-shell` via its bundled driver.
+
+    Args:
+        context_label (str): Human-readable feature name for error messages.
+
+    Raises:
+        RuntimeError: If Playwright is missing, driver binaries are invalid, or download fails.
+    """
+    try:
+        from playwright._impl._driver import (  # noqa: PLC2701
+            compute_driver_executable,
+            get_driver_env,
+        )
+    except ImportError as err:
+        raise RuntimeError(_format_missing_playwright_error(context_label)) from err
+
+    driver_executable, driver_cli = compute_driver_executable()
+    exec_path = Path(driver_executable).resolve()
+    cli_path = Path(driver_cli).resolve()
+    if not exec_path.is_file() or not cli_path.is_file():
+        detail = f"Playwright driver executable not found ({exec_path}, {cli_path})."
+        raise RuntimeError(_format_missing_browser_error(context_label, detail=detail))
+
+    with _browser_install_lock():
+        logger.info("Downloading headless Chromium browser (first-time setup)...")
+        proc = subprocess.run(  # noqa: S603
+            [str(exec_path), str(cli_path), *_INSTALL_ARGS],
+            env=get_driver_env(),
+            capture_output=True,
+            text=True,
+            check=False,
+        )
+        if proc.returncode != 0:
+            output = (proc.stderr or proc.stdout or "").strip()
+            detail = output or f"Playwright driver exited with status code {proc.returncode}."
+            raise RuntimeError(_format_missing_browser_error(context_label, detail=detail))
+        logger.info("Headless Chromium browser is ready.")
+
+
+def launch_headless_chromium(
+    playwright: Playwright,
+    *,
+    args: Sequence[str] | None = None,
+    auto_install: bool = True,
+    context_label: str = "PDF Export",
+) -> Browser:
+    """Launch headless Chromium, automatically downloading `chromium-headless-shell` on first use.
+
+    Args:
+        playwright (Playwright): Active Playwright instance from `sync_playwright()`.
+        args (Sequence[str] | None): Chromium launch flags. Uses font-hinting defaults when None.
+        auto_install (bool): Automatically download `chromium-headless-shell` if missing.
+        context_label (str): Human-readable feature name for error messages.
+
+    Returns:
+        Browser: Launched headless Chromium browser instance.
+
+    Raises:
+        RuntimeError: If browser launch or on-demand installation fails.
+    """
+    launch_args = list(args) if args is not None else list(_DEFAULT_CHROMIUM_ARGS)
+    try:
+        return playwright.chromium.launch(headless=True, args=launch_args)
+    except Exception as err:
+        if _is_missing_system_deps_error(err):
+            raise RuntimeError(_format_missing_system_deps_error(context_label, err)) from err
+        if not _is_missing_browser_executable_error(err):
+            raise RuntimeError(f"Failed to launch Chromium browser: {err}") from err
+        if not auto_install:
+            raise RuntimeError(_format_missing_browser_error(context_label, detail=str(err))) from err
+
+        install_headless_chromium(context_label=context_label)
+
+    try:
+        return playwright.chromium.launch(headless=True, args=launch_args)
+    except Exception as retry_err:
+        if _is_missing_system_deps_error(retry_err):
+            raise RuntimeError(_format_missing_system_deps_error(context_label, retry_err)) from retry_err
+        if _is_missing_browser_executable_error(retry_err):
+            raise RuntimeError(
+                _format_missing_browser_error(context_label, detail=str(retry_err))
+            ) from retry_err
+        raise RuntimeError(f"Failed to launch Chromium browser: {retry_err}") from retry_err