Release Notes & Migration Guide

Version 0.3.2

Release Date: 2026/10/30

Version 0.3.2 introduces native editable MS Word (.docx) and MS PowerPoint (.pptx) exporters, promotes headless Chromium, python-docx, and python-pptx into unified zero-config standard dependencies, and reorganizes embedded AI agent rules into modular category directories.

Highlights & New Features

1. MS Word (.docx) & MS PowerPoint (.pptx) Export (drawlib build docx, drawlib build pptx)

  • drawlib build docx & drawlib.tools.build_docx(): Compiles linear doc projects or single .md files into native editable MS Word (.docx) documents—complete with styled headings, prose, bullet/numbered lists, tables, blockquotes, syntax-highlighted code blocks, optional cover page, and automated Table of Contents (--generate-index)—rendering drawlib blocks (including SVG, WebP, and animated blocks) as crisp high-DPI static PNGs (--dpi 200 default).
  • drawlib build pptx & drawlib.slide.build_pptx() / drawlib.tools.build_pptx(): Measures 1920x1080 slide layouts and computed CSS styles via headless Chromium and exports native editable 16:9 (960x540 pt) MS PowerPoint (.pptx) decks—preserving ::: block cards with rgba alpha fills/borders, text boxes, bullet/numbered lists, tables, inline code, and ::: note speaker notes—while embedding drawlib diagrams as high-DPI static PNGs (--dpi 240 default, --anim-frame first|last defaulting to last).

2. Zero-Config Headless Chromium & Unified Standard Dependencies

  • Unified Standard Dependencies: Promoted playwright>=1.49.0, python-docx>=1.2.0, and python-pptx>=1.0.2 to standard dependencies and removed [project.optional-dependencies]. Installing drawlib via uv add drawlib or pip install drawlib now works out of the box for PDF, MS Word, and MS PowerPoint exports without extra flags.
  • Automatic Headless Browser Provisioning: Running drawlib build pdf or drawlib build pptx automatically installs chromium-headless-shell on first run via Playwright's bundled driver. Added explicit offline pre-download support via drawlib cache download --browser (also included in drawlib cache download --all) and actionable shared-library diagnostics (playwright install-deps chromium) for minimal Linux containers.

3. Modular Category-Based AI Agent Rules (drawlib rules)

  • Modular _rules/ Organization: Reorganized embedded rule manuals (src/drawlib/_rules/) into modular category directories (charts/, diagrams/, graph/, icons/, shapes/, smartarts/) for cleaner maintainability and fast topic lookup.

Version 0.3.1

Release Date: 2026/10/23

Version 0.3.1 introduces the drawlib.charts.heatmap visualization suite (HeatmapChart and HeatmapOverlay) alongside a comprehensive startup and import performance optimization across the library and CLI.

Highlights & New Features

1. 2D Matrix Heatmaps & Spatial Thermal Overlays (drawlib.charts.heatmap)

  • HeatmapChart: Declarative 2D matrix/grid heatmap across categorical x_categories and y_categories, featuring Style-based multi-stop color interpolation (styles=[...] or min_style / max_style), auto-contrasting in-cell value labels, configurable cell gaps and corner rounding (cell_gap, cell_r), continuous colorbars (draw_colorbar), and stepped swatch legends (draw_legend).
  • HeatmapOverlay: Spatial thermal and hotspot overlay engineered to render directly over existing diagrams (ClassDiagram, ArchitectureDiagram, ERDiagram, FlowDiagram, GeoMap, etc.) to highlight complexity, incident density, or regional hotspots in "smooth" (2D Gaussian thermal gradient) or "contour" (concentric vector isoline rings) modes with "add" and "max" accumulation (Spot).

2. Major Startup & Import Performance Optimization

  • PEP 562 Lazy Module & Icon Suite Loading: Deferred submodule imports across drawlib, drawlib.tools, drawlib.styles, drawlib.preset_styles, drawlib.preset_colors, drawlib.smartarts, drawlib.charts, drawlib.diagrams, drawlib.icons, and CLI subcommands. Importing drawlib, calling non-rendering drawlib.tools utilities, or running lightweight CLI commands (drawlib --version, drawlib init, drawlib serve) no longer loads matplotlib or unused domain modules, reducing startup latency by 15x–40x (and cutting import drawlib function calls by over 99%).
  • On-Demand Preset Themes & Fast Style Construction: Deferred preset theme instantiation (DefaultStyles, GoogleStyles, MonochromeStyles, etc.) until first access, adopted defer_build=True and model_construct fast paths for built-in style tokens, optimized _BaseStylesMeta attribute lookup, and deferred @validate_call schema compilation until first function call.

3. Bug Fixes & Compatibility

  • Resolved PydanticDeprecatedSince211 deprecation warnings triggered when accessing model_fields on BaseStyles instances in Pydantic v2.11+.

Version 0.3.0

Release Date: 2026/10/21

Version 0.3.0 represents a major architectural milestone for Drawlib, transforming it from a raw vector drawing tool into a comprehensive "Illustration & Documentation as Code" platform engineered for both software developers and autonomous AI coding agents.

Highlights & New Features

1. Modern Flat Package Architecture

  • Consolidated legacy version-namespaced packages into a modern, standard flat package structure (drawlib).
  • Clean, ergonomic public imports directly from domain modules:
    • drawlib.canvas, drawlib.math, drawlib.types, drawlib.fonts
    • drawlib.shapes, drawlib.lines, drawlib.text, drawlib.icons, drawlib.images
    • drawlib.graph, drawlib.smartarts, drawlib.charts, drawlib.diagrams
    • drawlib.anim, drawlib.slide, drawlib.tools
    • drawlib.styles, drawlib.preset_colors, drawlib.preset_styles, drawlib.utils

2. Built-in Integrated Documentation Builder, Slide Compiler & Developer Tools (drawlib.tools)

  • Native Markdown, HTML, Slide, and PDF compiler (drawlib build html, drawlib build markdown, drawlib build pdf, drawlib build slide, drawlib build image).
  • Compiles Markdown documents containing drawlib code blocks into:
    • Responsive multi-page static HTML documentation sites (docs_html/).
    • GitHub-optimized Markdown documents with embedded images (docs/).
    • Print-ready vector PDF documents (doc.pdf / slide.pdf).
    • Interactive 16:9 widescreen HTML presentation decks (slide_html/).
  • SQLite Incremental Build Cache (.drawlib/cache.db): Deterministic SHA-256 content-hash caching of code blocks, styles.py, utils.py, and local assets prevents unnecessary re-rendering of unchanged diagrams.
  • Programmatic Developer API (drawlib.tools): Full Python API (build_html, build_markdown, build_pdf, build_slide, build_image, export_code_block, init_project, serve_docs, list_cache, download_cache, clear_cache) for CI/CD and custom automation.

3. Auto-Layout Graph Engine (drawlib.graph)

  • Five specialized auto-layout graph solvers that eliminate manual coordinate math and support nested Cluster containers:
    • LayerGraph: Sugiyama-style hierarchical DAG layout.
    • ArchitectureGraph: Cloud and system topology solver with semantic tier alignment.
    • TreeGraph: Balanced parent-child hierarchy layout.
    • RadialGraph: Concentric radial ring layout.
    • GridGraph: Structured matrix placement solver.
  • 2-Step Layout Inspection & Diagram Rendering (get_layout()): Computes structured GraphLayout coordinates (xy, bottom_left, local_xy, local_bottom_left, points) with human- and AI-readable print(layout) inspection and offset() fine-tuning.

4. High-Level Technical Diagrams (drawlib.diagrams)

  • Architecture Diagrams (drawlib.diagrams.architecture.ArchitectureDiagram): Cloud topologies, nested cluster groups, and Phosphor / official GCP vector icons.
  • Flow Diagrams (drawlib.diagrams.flow.FlowDiagram): Standard flowchart symbols (ISO 5807 / JIS X 0121), decision branching, T-junction merging, and swimlanes (Lane).
  • Sequence Diagrams (drawlib.diagrams.sequence.SequenceDiagram): Client/server lifelines, activation bars, sync/async message arrows, self-calls, and interaction frames (alt, opt, loop, par).
  • ER Diagrams (drawlib.diagrams.er.ERDiagram): Full support for Information Engineering (IE / Crow's Foot) notation, table entity compartments, and automatic orthogonal routing.
  • UML Class Diagrams (drawlib.diagrams.class_diagram.ClassDiagram): 3-compartment class cards, stereotypes («interface»), visibility indicators, and relationship methods (inherit(), realize(), composite(), aggregate(), associate(), depend()).
  • State Machine Diagrams (drawlib.diagrams.state.StateDiagram): Declarative statecharts with initial/final pseudo-states, internal activity compartments (entry, do, exit), curved transitions with bend control, and self-loops.

5. Pure-Python Declarative Charts (drawlib.charts)

  • Zero external plotting dependencies:
    • BarChart: Vertical/horizontal, grouped, and stacked.
    • LineChart: Straight segments, smoothed spline curves, and custom markers.
    • AreaChart: Overlapping and cumulative stacked area plots.
    • PieChart: Solid pies and donut rings with center KPI badges.
    • RadarChart: Multiaxis spider webs and concentric circular rings.
    • ScatterChart: 2D scatter and bubble plots with custom marker shapes.
    • GanttChart: Project schedules, progress bars, milestones, and task dependency arrows.

6. Expanded SmartArts & Geographic Maps (drawlib.smartarts)

  • GeoMap: Offline vector world, regional, and country maps (World, Asia, Europe, USA, Japan, etc.) with country/prefecture highlighting, pins, connections, and choropleth coloring.
  • TreeNode & MindMapNode: Hierarchical node trees and radial brainstorming mind maps.
  • SourceCode: Syntax-highlighted source code cards with line numbers, window chrome, and dark/light themes.
  • ChevronProcess & Cycle: Sequential chevron process pipelines and radial circular life cycles with center hubs.
  • Table, GridLayout, Pyramid, BoxList, BulletPoints: Structured tabular and card-based visual components.

7. Multi-Frame Animations (drawlib.anim) & 16:9 Presentation Stage (drawlib.slide)

  • drawlib.anim.Animation: Declarative multi-frame animation builder exporting lossless APNG and Animated WebP with frame context managers (with anim.frame():), configurable FPS, and interpolation helpers in drawlib.math.
  • drawlib.slide: Universal 1920x1080 (16:9 widescreen) presentation coordinate stage with Markdown layout containers (::: block, ::: note), Presenter View (?presenter=1), and the current_slide runtime proxy (SlideContext, BoundingBox).

8. AI Agent Guidelines & Rule System (drawlib rules)

  • Integrated on-demand manual accessible via CLI:
    • drawlib rules show <topic>: Inject concise syntax documentation directly into agent context windows.
    • drawlib rules list: Explore all available drawing rules.
  • Autonomous visual self-correction loop via coordinate grid overlay (drawlib show -g).

9. Project Scaffolding (drawlib init)

  • Quickly scaffold complete starter projects for four primary use cases:
    • drawlib init doc: Linear technical document (HTML, PDF, Markdown, images).
    • drawlib init site: Multi-page documentation website.
    • drawlib init slide: 16:9 presentation slide deck (web & vector PDF).
    • drawlib init images: Standalone Python illustration batch project.

Breaking Changes & Migration from v0.2

If you are upgrading from Drawlib v0.2, review the following required changes:

  1. Python 3.11+ Required: Python 3.10 and earlier are no longer supported.
  2. Top-Level CLI drawlib export Removed:
    • Use drawlib show input.py -o output.png instead.
  3. Legacy dsart Namespace Removed & Tree Renamed to TreeNode:
    • Change from drawlib.apis import dsart to:
      from drawlib.smartarts import Table, TreeNode, MindMapNode, ChevronProcess, Cycle, GeoMap, SourceCode
  4. Semantic Style Naming Normalized:
    • Styles tokens unified to PascalCase (Styles.PrimaryFlat, Styles.AccentBold). Legacy snake-case style attributes are completely removed.
  5. Diagram Class Naming Unified:
    • All diagram containers follow PascalCase with the Diagram suffix:
      • ArchitectureDiagram
      • ERDiagram
      • FlowDiagram
      • SequenceDiagram
      • ClassDiagram
      • StateDiagram

Version 0.2.x Archive

  • v0.2.3 (2024/09/08): Added block arrow functions (arrow_polyline, arrow_l, arrow_u, arrow_arc) and initial SmartArts (Table, Tree, GridLayout, Pyramid, BoxList, BulletPoints).
  • v0.2.2 (2024/07/02): Initial public release of Drawlib 0.2.