+ :::
+Plain ``` fences still work via codehilite. Callouts use the admonition
+extension (note/tip/warning + custom 'spring').
+"""
+from __future__ import annotations
+import re
+from pathlib import Path
+import markdown
+from markdown.preprocessors import Preprocessor
+from markdown.extensions import Extension
+from pygments import highlight
+from pygments.lexers import get_lexer_by_name, guess_lexer
+from pygments.util import ClassNotFound
+from pygments.formatters import HtmlFormatter
+
+_FMT = HtmlFormatter(nowrap=True) # tokens only; we supply
+_EXT = {"py":"python","yaml":"yaml","yml":"yaml","toml":"toml","json":"json",
+ "sh":"bash","bash":"bash","sql":"sql","xml":"xml","html":"html","txt":"text"}
+
+class _Directives(Preprocessor):
+ FIG = re.compile(r'^:::\s*figure\s+(?P\S+)\s*\|\s*(?P.+?)\s*$')
+ LST = re.compile(r'^:::\s*listing\s+(?P[^|]+?)\s*(?:\|\s*(?P.+?))?\s*$')
+
+ def __init__(self, md, base: Path):
+ super().__init__(md)
+ self.base = Path(base)
+
+ def run(self, lines):
+ out, i = [], 0
+ while i < len(lines):
+ mf, ml = self.FIG.match(lines[i]), self.LST.match(lines[i])
+ if mf:
+ out.append(self.md.htmlStash.store(self._figure(mf["src"], mf["cap"])))
+ i += 1
+ elif ml:
+ body, i = [], i + 1
+ while i < len(lines) and lines[i].strip() != ":::":
+ body.append(lines[i]); i += 1
+ i += 1
+ out.append(self.md.htmlStash.store(
+ self._listing(ml["file"].strip(), ml["cap"], "\n".join(body))))
+ else:
+ out.append(lines[i]); i += 1
+ return out
+
+ def _figure(self, src: str, cap: str) -> str:
+ svg = (self.base / src).read_text(encoding="utf-8").strip()
+ svg = re.sub(r'^<\?xml[^>]*\?>\s*', "", svg)
+ return f'{svg}{cap}'
+
+ def _listing(self, file_label: str, cap: str | None, code: str) -> str:
+ lang = _EXT.get(file_label.rsplit(".", 1)[-1].lower(), "python") if "." in file_label else "python"
+ try:
+ lexer = get_lexer_by_name(lang)
+ except ClassNotFound:
+ lexer = guess_lexer(code)
+ body = highlight(code, lexer, _FMT)
+ cap_html = f'{cap}
' if cap else ""
+ return (f'{file_label}'
+ f'
{body}{cap_html}
')
+
+class PyflyExtension(Extension):
+ def __init__(self, base: Path, **kw):
+ self.base = base
+ super().__init__(**kw)
+ def extendMarkdown(self, md):
+ md.preprocessors.register(_Directives(md, self.base), "pyfly_directives", 28)
+
+def render_markdown(text: str, base: Path) -> str:
+ md = markdown.Markdown(
+ extensions=["extra", "admonition", "toc", "sane_lists", "codehilite",
+ PyflyExtension(base)],
+ extension_configs={"codehilite": {"css_class": "code", "guess_lang": False}},
+ output_format="html5",
+ )
+ return md.convert(text)
+```
+
+- [ ] **Step 4: Run tests to verify they pass**
+
+Run: `book/.venv/bin/python -m pytest tests/book/test_md.py -q`
+Expected: PASS (3 passed).
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add book/build/md.py tests/book/test_md.py
+git commit -m "feat(book): markdown pipeline — listings, SVG figures, callouts"
+```
+
+---
+
+## Task 4: EPUB3 assembler `epub.py` (TDD)
+
+**Files:**
+- Create: `book/build/epub.py`
+- Test: `tests/book/test_epub.py`
+
+- [ ] **Step 1: Write the failing test**
+
+```python
+# tests/book/test_epub.py
+import zipfile
+from pathlib import Path
+import sys
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "book" / "build"))
+from epub import EpubBuilder, Doc # noqa: E402
+
+def test_epub_is_valid_ocf(tmp_path):
+ out = tmp_path / "b.epub"
+ b = EpubBuilder(title="T", author="A", language="en", identifier="urn:uuid:1",
+ css=["body{color:#000}"])
+ b.add_doc(Doc(id="c1", title="One", xhtml_body="One
", in_nav=True))
+ b.build(out)
+ z = zipfile.ZipFile(out)
+ # mimetype must be first entry, stored (uncompressed), exact bytes
+ first = z.infolist()[0]
+ assert first.filename == "mimetype"
+ assert first.compress_type == zipfile.ZIP_STORED
+ assert z.read("mimetype") == b"application/epub+zip"
+ names = set(z.namelist())
+ assert "META-INF/container.xml" in names
+ assert "OEBPS/content.opf" in names
+ assert "OEBPS/nav.xhtml" in names
+ assert "OEBPS/c1.xhtml" in names
+ assert "One" in z.read("OEBPS/nav.xhtml").decode()
+```
+
+- [ ] **Step 2: Run test to verify it fails**
+
+Run: `book/.venv/bin/python -m pytest tests/book/test_epub.py -q`
+Expected: FAIL (ModuleNotFoundError: epub).
+
+- [ ] **Step 3: Implement `book/build/epub.py`**
+
+```python
+"""Minimal, correct EPUB3 (OCF) assembler using only the standard library."""
+from __future__ import annotations
+import zipfile
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+from pathlib import Path
+from xml.sax.saxutils import escape
+
+_MEDIA = {".svg":"image/svg+xml",".png":"image/png",".jpg":"image/jpeg",
+ ".jpeg":"image/jpeg",".css":"text/css",".woff2":"font/woff2",".woff":"font/woff"}
+
+@dataclass
+class Doc:
+ id: str
+ title: str
+ xhtml_body: str
+ in_nav: bool = True
+
+@dataclass
+class Asset:
+ id: str
+ href: str # relative to OEBPS, e.g. "art/cover.png"
+ data: bytes
+ media_type: str
+ properties: str = "" # e.g. "cover-image"
+
+@dataclass
+class EpubBuilder:
+ title: str
+ author: str
+ language: str
+ identifier: str
+ css: list[str] = field(default_factory=list)
+ docs: list[Doc] = field(default_factory=list)
+ assets: list[Asset] = field(default_factory=list)
+ cover_asset_id: str | None = None
+
+ def add_doc(self, d: Doc) -> None: self.docs.append(d)
+ def add_asset(self, a: Asset) -> None: self.assets.append(a)
+
+ def add_file(self, path: Path, href: str, aid: str, properties: str = "") -> Asset:
+ a = Asset(id=aid, href=href, data=Path(path).read_bytes(),
+ media_type=_MEDIA[Path(href).suffix.lower()], properties=properties)
+ self.assets.append(a)
+ if properties == "cover-image": self.cover_asset_id = aid
+ return a
+
+ def _xhtml(self, d: Doc) -> str:
+ links = "\n".join(f''
+ for i in range(len(self.css)))
+ return (f'\n'
+ f'\n'
+ f'{escape(d.title)}\n{links}\n\n'
+ f'\n\n')
+
+ def _nav(self) -> str:
+ items = "\n".join(f'{escape(d.title)}'
+ for d in self.docs if d.in_nav)
+ return ('\n'
+ ''
+ 'Contents'
+ f''
+ '')
+
+ def _opf(self) -> str:
+ modified = datetime.now(timezone.utc).strftime("%Y-%m-%dT%H:%M:%SZ")
+ man = ['
- 
+ 
diff --git a/docs/superpowers/plans/2026-06-07-pyfly-by-example-phase0.md b/docs/superpowers/plans/2026-06-07-pyfly-by-example-phase0.md
new file mode 100644
index 00000000..13b240c7
--- /dev/null
+++ b/docs/superpowers/plans/2026-06-07-pyfly-by-example-phase0.md
@@ -0,0 +1,1149 @@
+# PyFly by Example — Phase 0 (Build Pipeline + Vertical Slice) Implementation Plan
+
+> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
+
+**Goal:** Stand up the complete book build system and produce a polished, illustrated **EPUB + PDF** containing the front matter and a fully written, illustrated **Chapter 1** — the vertical slice that locks voice, formatting, and the toolchain.
+
+**Architecture:** Markdown manuscript → custom `markdown` pipeline (Pygments listings + admonition callouts + inlined SVG figures) → HTML, then two renderers: a stdlib `zipfile` **EPUB3** assembler (embeds SVG, raster cover) and **WeasyPrint** for the print-style **PDF**, both driven by one `book.yaml` and sharing one CSS theme. All illustrations are hand-authored SVG using the official PyFly logo and the "Sparky" mascot.
+
+**Tech Stack:** Python 3.12 (`book/.venv`), `markdown` 3.9, `pygments` 2.20, `weasyprint` 66, `cairosvg` 2.8.2, `Pillow` 11.3; Homebrew `pango/cairo/gdk-pixbuf`; build runs with `DYLD_FALLBACK_LIBRARY_PATH=/opt/homebrew/lib`.
+
+**Spec:** `docs/superpowers/specs/2026-06-07-pyfly-by-example-book-design.md`
+
+---
+
+## File Structure (created in this phase)
+
+```
+book/
+ book.yaml # metadata + ordered manifest of front/chapters/back
+ build/
+ run.sh # wrapper: exports DYLD path, calls build.py via book/.venv
+ md.py # markdown -> html (listings, figures, callouts)
+ epub.py # EPUB3 assembler (stdlib zipfile)
+ pdf.py # WeasyPrint HTML/CSS -> PDF
+ gen_cover.py # compose cover.svg (logo embedded) + rasterize cover.png
+ verify_code.py # extract python listings, syntax+import check vs pyfly
+ build.py # orchestrator
+ theme/
+ tokens.css # palette variables
+ book.css # shared screen/EPUB styles (Modern)
+ print.css # @page, running heads, page numbers (PDF only)
+ pygments.css # light code-highlight theme
+ art/
+ logo/pyfly-logo.png # copied from repo assets/ (source of truth)
+ cover.svg # generated by gen_cover.py
+ cover.png # generated by gen_cover.py (EPUB cover)
+ mascot/sparky.svg # Sparky badge (reusable)
+ openers/ch01.svg # Chapter 1 opener illustration
+ figures/01-choice.svg # "infinite choice vs cohesion"
+ figures/01-layers.svg # the four module layers
+ manuscript/
+ 00-front/
+ 00-title.md 00-copyright.md 00-preface.md 00-conventions.md 00-meet-sparky.md
+ 01-why-pyfly.md
+ dist/ # build output (git-ignored): pyfly-by-example.{epub,pdf}
+tests/book/
+ test_md.py # custom markdown directives
+ test_epub.py # EPUB structure validity
+ test_verify_code.py # code verifier
+```
+
+**Conventions for all tasks:** run build commands through the wrapper so libs load:
+`bash book/build/run.sh` (full build) or, for tests,
+`DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix)/lib" book/.venv/bin/python -m pytest tests/book -q`.
+
+---
+
+## Task 1: Project metadata + run wrapper
+
+**Files:**
+- Create: `book/book.yaml`
+- Create: `book/build/run.sh`
+
+- [ ] **Step 1: Write `book/book.yaml`**
+
+```yaml
+title: "PyFly by Example"
+subtitle: "Event-Driven Python Microservices with the Firefly Framework"
+author: "Firefly Software Foundation"
+publisher: "Firefly Software Foundation"
+language: "en"
+identifier: "urn:uuid:7c1b1f2e-0a9e-4e3a-9d2a-pyfly000book"
+rights: "Copyright (c) 2026 Firefly Software Foundation. Licensed under Apache-2.0."
+cover_svg: "art/cover.svg"
+cover_png: "art/cover.png"
+# Trim size for the PDF (US Royal-ish, Packt-style)
+trim_width: "7.5in"
+trim_height: "9.25in"
+# Ordered manifest. Only files that exist are built (others are skipped with a warning),
+# so this same manifest grows as later phases add chapters.
+front:
+ - {id: title, file: 00-front/00-title.md, nav: false}
+ - {id: copyright, file: 00-front/00-copyright.md, nav: false}
+ - {id: preface, file: 00-front/00-preface.md, title: "Preface"}
+ - {id: conventions, file: 00-front/00-conventions.md, title: "Conventions"}
+ - {id: sparky, file: 00-front/00-meet-sparky.md, title: "Meet Sparky"}
+parts:
+ - title: "Part I — Foundations"
+ chapters:
+ - {id: ch01, file: 01-why-pyfly.md, num: 1, title: "Why PyFly?", opener: art/openers/ch01.svg}
+back: []
+```
+
+- [ ] **Step 2: Write `book/build/run.sh`**
+
+```bash
+#!/usr/bin/env bash
+# Build wrapper: ensures Homebrew's cairo/pango are loadable, then runs the build
+# inside the isolated 3.12 venv. Pass-through args go to build.py (e.g. --epub-only).
+set -euo pipefail
+BOOK_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+BREW_PREFIX="$(brew --prefix 2>/dev/null || echo /opt/homebrew)"
+export DYLD_FALLBACK_LIBRARY_PATH="${BREW_PREFIX}/lib:/usr/local/lib:${DYLD_FALLBACK_LIBRARY_PATH:-}"
+exec "${BOOK_DIR}/.venv/bin/python" "${BOOK_DIR}/build/build.py" "$@"
+```
+
+- [ ] **Step 3: Make it executable**
+
+Run: `chmod +x book/build/run.sh`
+Expected: no output, exit 0.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add book/book.yaml book/build/run.sh
+git commit -m "build(book): metadata manifest + DYLD-aware run wrapper"
+```
+
+---
+
+## Task 2: Theme CSS (tokens, book, print, pygments)
+
+**Files:**
+- Create: `book/theme/tokens.css`, `book/theme/book.css`, `book/theme/print.css`, `book/theme/pygments.css`
+
+- [ ] **Step 1: Write `book/theme/tokens.css`**
+
+```css
+:root{
+ --green:#43b02a; --green-bright:#5fd13a; --lime:#86dd4c; --lime-soft:#a7e76a;
+ --green-deep:#2c8a1c; --green-ink:#1f5e16; --amber:#ffc24b; --amber-soft:#ffd86b;
+ --ink:#1c2420; --ink-soft:#33402e; --muted:#7a8472; --page:#fffef9;
+ --code-bg:#f7faf3; --code-border:#dde6d3; --rule:#e7ece1;
+ --note:#1f6fd6; --note-bg:#eef6ff; --tip:#2f8f3f; --warn:#c2410c; --warn-bg:#fff4ec;
+}
+```
+
+- [ ] **Step 2: Write `book/theme/book.css`** (Modern interior — shared by EPUB + PDF)
+
+```css
+@import "tokens.css";
+@import "pygments.css";
+body{ color:var(--ink); background:var(--page);
+ font-family:-apple-system,"Segoe UI",Inter,Roboto,Helvetica,Arial,sans-serif;
+ font-size:1rem; line-height:1.72; margin:0; }
+.chapter{ padding:0 0 2rem; }
+h1,h2,h3{ color:var(--ink); line-height:1.25; font-weight:800; }
+h1.chtitle{ font-size:2rem; margin:.2rem 0 1rem; color:#15351a; }
+h2{ font-size:1.25rem; font-weight:700; margin:1.6rem 0 .5rem; }
+h3{ font-size:1.05rem; font-weight:700; margin:1.2rem 0 .4rem; }
+p{ margin:0 0 .8rem; }
+a{ color:var(--green-deep); }
+code{ background:#eef3e8; color:var(--green-deep); padding:1px 5px; border-radius:4px;
+ font-family:"SF Mono","JetBrains Mono",Menlo,Consolas,monospace; font-size:.86em; }
+.eyebrow{ color:var(--green); font-weight:700; letter-spacing:2px; font-size:.72rem;
+ text-transform:uppercase; }
+.opener{ display:flex; align-items:center; gap:1rem; margin:.4rem 0 1rem; }
+.opener .badge{ flex:none; width:64px; height:64px; }
+.opener-illus{ width:100%; height:auto; margin:.6rem 0 1.2rem; }
+
+/* listings */
+.listing{ margin:1rem 0; }
+.filetab{ display:inline-block; background:#eef3e8; color:#3f6b34;
+ font:600 .72rem/1 "SF Mono",Menlo,monospace; padding:.4rem .6rem;
+ border:1px solid var(--code-border); border-bottom:none; border-radius:7px 7px 0 0; }
+pre.code{ margin:0; background:var(--code-bg); border:1px solid var(--code-border);
+ border-radius:0 7px 7px 7px; padding:.8rem .9rem; overflow-x:auto;
+ font-family:"SF Mono","JetBrains Mono",Menlo,Consolas,monospace; font-size:.8rem; line-height:1.6; }
+.lcap{ font-size:.74rem; color:var(--muted); margin-top:.4rem; font-style:italic; }
+
+/* figures */
+figure.fig{ margin:1.2rem 0; text-align:center; }
+figure.fig svg{ max-width:100%; height:auto; }
+figcaption{ font-size:.76rem; color:var(--muted); margin-top:.5rem; }
+figcaption b{ color:#3f6b34; }
+
+/* callouts (admonition extension output) */
+.admonition{ border-radius:11px; padding:.7rem .9rem; margin:1rem 0; font-size:.92rem;
+ border:1px solid var(--rule); background:#f6f8f1; }
+.admonition-title{ font-weight:700; font-size:.72rem; letter-spacing:1px; text-transform:uppercase;
+ margin:0 0 .3rem; }
+.admonition.note{ background:var(--note-bg); border-color:#cfe3fb; }
+.admonition.note>.admonition-title{ color:var(--note); }
+.admonition.tip{ background:#f0faef; border-color:#cdeccd; }
+.admonition.tip>.admonition-title{ color:var(--tip); }
+.admonition.warning{ background:var(--warn-bg); border-color:#fcd9c2; }
+.admonition.warning>.admonition-title{ color:var(--warn); }
+.admonition.spring{ background:#f3fae9; border-color:#d4e9bd; }
+.admonition.spring>.admonition-title{ color:var(--green-deep); }
+.admonition.spring>.admonition-title::before{ content:"\1F33F "; }
+
+/* recap / exercises */
+.recap{ background:#f3fae9; border:1px solid #d4e9bd; border-radius:11px; padding:.9rem 1rem; margin:1.4rem 0; }
+.recap h3,.exercises h3{ margin-top:0; color:var(--green-deep); }
+```
+
+- [ ] **Step 3: Write `book/theme/pygments.css`** (generate from Pygments, then hand-tune)
+
+Run to generate a base, then we override key tokens:
+```bash
+book/.venv/bin/python -c "from pygments.formatters import HtmlFormatter; print(HtmlFormatter().get_style_defs('.code'))" > book/theme/pygments.css
+```
+Then append these print-safe overrides to `book/theme/pygments.css`:
+```css
+.code .k,.code .kn,.code .kd{ color:#cf222e; } /* keyword */
+.code .s,.code .s1,.code .s2,.code .sb{ color:#0a3069; } /* string */
+.code .c,.code .c1,.code .cm{ color:#6e7781; font-style:italic; } /* comment */
+.code .nf,.code .fm{ color:#8250df; } /* function */
+.code .nd{ color:#953800; } /* decorator */
+.code .mi,.code .mf{ color:#0550ae; } /* number */
+.code .nb,.code .bp{ color:#116329; } /* builtin */
+.code .nc,.code .nn{ color:#0b3d2e; font-weight:600; } /* class/namespace */
+```
+
+- [ ] **Step 4: Write `book/theme/print.css`** (PDF page setup only)
+
+```css
+@page{
+ size: 7.5in 9.25in;
+ margin: 0.85in 0.8in 0.9in;
+ @bottom-center{ content: counter(page); font-family:-apple-system,sans-serif;
+ font-size:9px; color:#9aa6a0; }
+ @top-center{ content: string(runhead); font-family:-apple-system,sans-serif;
+ font-size:8.5px; letter-spacing:1.5px; text-transform:uppercase; color:#a7b0a0; }
+}
+@page :first{ @top-center{ content: none; } @bottom-center{ content: none; } }
+h1.chtitle{ string-set: runhead content(text); break-before: page; }
+.cover-page{ break-after: page; text-align:center; }
+.cover-page img{ width:100%; height:auto; }
+.listing,figure.fig,.admonition{ break-inside: avoid; }
+h2,h3{ break-after: avoid; }
+```
+
+- [ ] **Step 5: Commit**
+
+```bash
+git add book/theme/
+git commit -m "style(book): Modern theme — tokens, book, print, pygments"
+```
+
+---
+
+## Task 3: Markdown pipeline `md.py` (TDD)
+
+**Files:**
+- Create: `book/build/md.py`
+- Test: `tests/book/test_md.py`
+
+- [ ] **Step 1: Write the failing tests**
+
+```python
+# tests/book/test_md.py
+from pathlib import Path
+import sys
+sys.path.insert(0, str(Path(__file__).resolve().parents[2] / "book" / "build"))
+from md import render_markdown # noqa: E402
+
+def test_listing_renders_filetab_caption_and_highlight(tmp_path):
+ src = (
+ "::: listing wallet/app.py | Listing 1.1 — hello\n"
+ "from pyfly.core import pyfly_application\n"
+ "@pyfly_application(name=\"x\")\n"
+ "class App: ...\n"
+ ":::\n"
+ )
+ html = render_markdown(src, tmp_path)
+ assert 'class="filetab">wallet/app.py<' in html
+ assert "Listing 1.1" in html
+ assert 'class="listing"' in html
+ assert "
')
+ for (cid, title, path, in_nav) in docs:
+ parts_html.append(render_markdown(Path(path).read_text(encoding="utf-8"), Path(path).parent))
+ full = (""
+ + "\n".join(parts_html) + "")
+ render_pdf(full, base_url=BOOK,
+ css_paths=[THEME / "tokens.css", THEME / "pygments.css",
+ THEME / "book.css", THEME / "print.css"],
+ out=DIST / "pyfly-by-example.pdf")
+ print(f"Built {len(docs)} document(s) -> EPUB + PDF in {DIST}")
+ return 0
+
+if __name__ == "__main__":
+ raise SystemExit(main())
+```
+
+- [ ] **Step 3: Ensure PyYAML is in the build venv**
+
+Run: `book/.venv/bin/python -m pip install -q pyyaml`
+Expected: exit 0.
+
+- [ ] **Step 4: Commit**
+
+```bash
+git add book/build/pdf.py book/build/build.py
+git commit -m "feat(book): orchestrator + WeasyPrint PDF renderer"
+```
+
+---
+
+## Task 11: Full build + verification
+
+- [ ] **Step 1: Run the full build**
+
+Run: `bash book/build/run.sh`
+Expected: `Built N document(s) -> EPUB + PDF in .../book/dist`, exit 0.
+
+- [ ] **Step 2: Verify EPUB structure**
+
+Run:
+```bash
+book/.venv/bin/python - <<'PY'
+import zipfile
+z=zipfile.ZipFile("book/dist/pyfly-by-example.epub")
+assert z.infolist()[0].filename=="mimetype"
+print("entries:", len(z.namelist()))
+print("has opf/nav:", "OEBPS/content.opf" in z.namelist(), "OEBPS/nav.xhtml" in z.namelist())
+print("cover:", "OEBPS/art/cover.png" in z.namelist())
+PY
+```
+Expected: mimetype first; opf/nav/cover present.
+
+- [ ] **Step 3: Verify PDF opens and has pages**
+
+Run:
+```bash
+book/.venv/bin/python - <<'PY'
+import os; p="book/dist/pyfly-by-example.pdf"
+print("pdf bytes:", os.path.getsize(p))
+print("header ok:", open(p,"rb").read(5)==b"%PDF-")
+PY
+open book/dist/pyfly-by-example.pdf
+open book/dist/pyfly-by-example.epub
+```
+Expected: PDF > 100 KB, `%PDF-` header; both open and render the cover + front matter + Chapter 1
+with the Modern styling, highlighted listings, callouts, and figures.
+
+- [ ] **Step 4: Run the full book test suite**
+
+Run: `DYLD_FALLBACK_LIBRARY_PATH="$(brew --prefix)/lib" book/.venv/bin/python -m pytest tests/book -q`
+Expected: all pass.
+
+- [ ] **Step 5: Commit the build outputs are git-ignored — verify and commit any fixes**
+
+```bash
+git status --short # dist/ should NOT appear (ignored)
+git add -A book tests/book
+git commit -m "build(book): Phase 0 vertical slice builds to EPUB + PDF" || echo "nothing to commit"
+```
+
+---
+
+## Self-Review
+
+**Spec coverage:** Phase 0 of the spec (§10) = pipeline + theme + cover + Sparky + diagram kit +
+front matter + Chapter 1 → EPUB+PDF. Tasks 1–11 cover each: build system (1,3,4,5,10),
+theme (2), cover (6), mascot/figures (7), front matter (8), Chapter 1 (9), build+verify (11).
+Later parts (chapters 2–18, appendices) are explicitly **out of scope** for this plan and get their
+own plans, reusing this pipeline unchanged.
+
+**Placeholder scan:** Build code, CSS, EPUB/MD/verifier modules, cover generator, and Sparky SVG
+are fully specified. The three Chapter-1 *figures* (Task 7 steps 2–4) and prose (Task 9) are
+content authored during execution against an explicit spec (sections, captions, real listings) —
+this is intended creative work, not a code placeholder. All code steps include complete code.
+
+**Type/name consistency:** `render_markdown(text, base)` (md.py) is called consistently in
+build.py and tests. `EpubBuilder`/`Doc`/`add_file(...properties="cover-image")` match between
+epub.py, its test, and build.py. `extract_python_listings`/`check_syntax` match verify_code.py and
+its test. The `::: listing`/`::: figure` directive grammar is identical in md.py and verify_code.py.
+
+---
+
+## Notes for later phases (not part of this plan)
+
+- Each subsequent Part = one plan: write chapters + opener/figures, append to `book.yaml`, rebuild,
+ review. The pipeline, theme, and assemblers do not change.
+- Final phase: EPUB validation (epubcheck if installed), term index, full code-verification pass.
diff --git a/pyproject.toml b/pyproject.toml
index d16b0bc4..2be93607 100644
--- a/pyproject.toml
+++ b/pyproject.toml
@@ -7,7 +7,7 @@ name = "pyfly"
# CalVer YY.MM.PATCH — package metadata uses PEP 440 normalized form (26.5.4);
# git tag, GitHub release and human-readable display use leading-zero form
# (v26.05.04) to match the Java/.NET/Go siblings.
-version = "26.6.40"
+version = "26.6.41"
description = "The official Python implementation of the Firefly Framework — DI, CQRS, EDA, hexagonal architecture, and more."
readme = "README.md"
license = "Apache-2.0"
diff --git a/src/pyfly/__init__.py b/src/pyfly/__init__.py
index 5e259781..2029e2c4 100644
--- a/src/pyfly/__init__.py
+++ b/src/pyfly/__init__.py
@@ -13,4 +13,4 @@
# limitations under the License.
"""PyFly — Enterprise Python Framework."""
-__version__ = "26.06.40"
+__version__ = "26.06.41"
diff --git a/src/pyfly/context/__init__.py b/src/pyfly/context/__init__.py
index 03473931..8c517f84 100644
--- a/src/pyfly/context/__init__.py
+++ b/src/pyfly/context/__init__.py
@@ -28,6 +28,7 @@
from pyfly.context.events import (
ApplicationEvent,
ApplicationEventBus,
+ ApplicationEventPublisher,
ApplicationReadyEvent,
ContextClosedEvent,
ContextRefreshedEvent,
@@ -41,6 +42,7 @@
"ApplicationContext",
"ApplicationEvent",
"ApplicationEventBus",
+ "ApplicationEventPublisher",
"ApplicationReadyEvent",
"BeanPostProcessor",
"ContextClosedEvent",
diff --git a/src/pyfly/context/application_context.py b/src/pyfly/context/application_context.py
index eb919857..0a7ff6c4 100644
--- a/src/pyfly/context/application_context.py
+++ b/src/pyfly/context/application_context.py
@@ -38,6 +38,7 @@
from pyfly.context.events import (
ApplicationEvent,
ApplicationEventBus,
+ ApplicationEventPublisher,
ApplicationReadyEvent,
ContextClosedEvent,
ContextRefreshedEvent,
@@ -80,6 +81,10 @@ def __init__(self, config: Config) -> None:
self._container._registrations[Config].instance = config
self._container.register(Container, scope=Scope.SINGLETON)
self._container._registrations[Container].instance = self._container
+ # Injectable event publisher (Spring ApplicationEventPublisher) — beans can fire
+ # lifecycle or arbitrary domain events into the bus.
+ self._container.register(ApplicationEventPublisher, scope=Scope.SINGLETON)
+ self._container._registrations[ApplicationEventPublisher].instance = ApplicationEventPublisher(self._event_bus)
# ------------------------------------------------------------------
# Bean registration
@@ -688,13 +693,15 @@ def _wire_app_event_listeners(self) -> None:
# return annotation must not be mistaken for the event (audit #119).
hints = typing.get_type_hints(method)
hints.pop("return", None)
- event_type: type[ApplicationEvent] | None = None
+ # The first type-annotated parameter is the event type — any type, so a
+ # listener can subscribe to arbitrary domain events, not only ApplicationEvent.
+ event_type: type = ApplicationEvent
for param_type in hints.values():
- if isinstance(param_type, type) and issubclass(param_type, ApplicationEvent):
+ # A concrete class (not typing.Any, which is a class in 3.11+ but is
+ # the "untyped" catch-all here) becomes the subscribed event type.
+ if isinstance(param_type, type) and param_type is not typing.Any:
event_type = param_type
break
- if event_type is None:
- event_type = ApplicationEvent
self._event_bus.subscribe(event_type, method, owner_cls=type(reg.instance))
count += 1
self._wiring_counts["event_listeners"] = count
diff --git a/src/pyfly/context/events.py b/src/pyfly/context/events.py
index 3b10ea59..32e2ce15 100644
--- a/src/pyfly/context/events.py
+++ b/src/pyfly/context/events.py
@@ -54,30 +54,31 @@ class ApplicationEventBus:
def __init__(self) -> None:
self._listeners: dict[
- type[ApplicationEvent],
+ type,
list[tuple[Callable[..., Awaitable[None]], type | None]],
] = {}
def subscribe(
self,
- event_type: type[ApplicationEvent],
+ event_type: type,
listener: Callable[..., Awaitable[None]],
*,
owner_cls: type | None = None,
) -> None:
- """Register a listener for a specific event type."""
+ """Register a listener for a specific event type (any type, not only ApplicationEvent)."""
if event_type not in self._listeners:
self._listeners[event_type] = []
self._listeners[event_type].append((listener, owner_cls))
# Pre-sort so publish() doesn't need to sort per invocation
self._listeners[event_type].sort(key=lambda e: get_order(e[1]) if e[1] else 0)
- async def publish(self, event: ApplicationEvent) -> None:
+ async def publish(self, event: object) -> None:
"""Publish an event to all matching listeners (pre-sorted by @order).
- Listeners may be synchronous (``void``) or coroutine functions; the
- result is awaited only when awaitable, so a plain ``def`` listener does
- not crash startup (audit #115).
+ *event* may be any object — lifecycle ``ApplicationEvent`` subclasses or arbitrary
+ domain events. Listeners may be synchronous (``void``) or coroutine functions; the
+ result is awaited only when awaitable, so a plain ``def`` listener does not crash
+ startup (audit #115).
"""
for event_type, entries in self._listeners.items():
if isinstance(event, event_type):
@@ -85,3 +86,28 @@ async def publish(self, event: ApplicationEvent) -> None:
result = listener(event)
if inspect.isawaitable(result):
await result
+
+
+class ApplicationEventPublisher:
+ """Injectable publisher for firing application events into the context event bus.
+
+ Inject it into any bean and publish lifecycle or arbitrary domain events::
+
+ @service
+ class OrderService:
+ def __init__(self, events: ApplicationEventPublisher) -> None:
+ self._events = events
+
+ async def place(self, order: Order) -> None:
+ await self._events.publish(OrderPlacedEvent(order.id))
+
+ Any ``@app_event_listener`` whose parameter type matches the published event (by
+ ``isinstance``) is invoked. The Spring ``ApplicationEventPublisher`` equivalent.
+ """
+
+ def __init__(self, bus: ApplicationEventBus) -> None:
+ self._bus = bus
+
+ async def publish(self, event: object) -> None:
+ """Publish *event* (any object) to all matching listeners."""
+ await self._bus.publish(event)
diff --git a/tests/context/test_event_publisher.py b/tests/context/test_event_publisher.py
new file mode 100644
index 00000000..80641a38
--- /dev/null
+++ b/tests/context/test_event_publisher.py
@@ -0,0 +1,71 @@
+# Copyright 2026 Firefly Software Foundation.
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+# http://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+"""Injectable ApplicationEventPublisher + arbitrary domain events (v26.06.41)."""
+
+from __future__ import annotations
+
+import pytest
+
+from pyfly.container import service
+from pyfly.context.application_context import ApplicationContext
+from pyfly.context.events import ApplicationEventPublisher, app_event_listener
+from pyfly.core.config import Config
+
+
+class OrderPlaced:
+ """An arbitrary domain event — NOT an ApplicationEvent subclass."""
+
+ def __init__(self, order_id: str) -> None:
+ self.order_id = order_id
+
+
+_received: list[str] = []
+
+
+@service
+class OrderListener:
+ @app_event_listener
+ async def on_order(self, event: OrderPlaced) -> None:
+ _received.append(event.order_id)
+
+
+@service
+class OrderService:
+ def __init__(self, events: ApplicationEventPublisher) -> None:
+ self.events = events
+
+ async def place(self, order_id: str) -> None:
+ await self.events.publish(OrderPlaced(order_id))
+
+
+@pytest.mark.asyncio
+async def test_injectable_publisher_delivers_domain_event() -> None:
+ _received.clear()
+ ctx = ApplicationContext(Config({}))
+ ctx.register_bean(OrderListener)
+ ctx.register_bean(OrderService)
+ await ctx.start()
+
+ svc = ctx.get_bean(OrderService)
+ assert isinstance(svc.events, ApplicationEventPublisher) # publisher was injected
+
+ await svc.place("order-1")
+ assert _received == ["order-1"] # arbitrary domain event reached the @app_event_listener
+
+
+@pytest.mark.asyncio
+async def test_publisher_is_a_singleton_bean() -> None:
+ ctx = ApplicationContext(Config({}))
+ await ctx.start()
+ assert isinstance(ctx.get_bean(ApplicationEventPublisher), ApplicationEventPublisher)
diff --git a/uv.lock b/uv.lock
index 35e354da..21cf5380 100644
--- a/uv.lock
+++ b/uv.lock
@@ -1981,7 +1981,7 @@ wheels = [
[[package]]
name = "pyfly"
-version = "26.6.40"
+version = "26.6.41"
source = { editable = "." }
dependencies = [
{ name = "pydantic" },