kingmadoc 0.3.0.dev7__tar.gz → 0.3.0.dev9__tar.gz

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/CHANGELOG.md

@@ -9,6 +9,22 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ### Changed
 
+- `kingmadoc render` links a PNG for each diagram, so the pictures show in every
+  Markdown preview (VS Code, Visual Studio, Rider, GitHub, GitLab, Bitbucket; several
+  block or mishandle SVG). The PNG is made offline with resvg (`resvg-py`, a small
+  wheel for every platform) using D2's own embedded fonts; the SVG (dark mode) and the
+  `.d2` source stay next to it, and `--format svg` links the SVG as before.
+  `explaining-code` 5.8 no longer lets the agent convert images itself.
+- `kingmadoc skills install --vscode-user`: VS Code opens explainers as a preview in
+  every folder (user settings); the question in a terminal sets that up.
+- Tidier diagrams: `kingmadoc render` lays figures out with ELK (straight,
+  right-angled arrows with fewer crossings; a diagram that sets its own
+  `layout-engine` keeps it) and warns about more than 12 arrows or two arrows between
+  the same shapes. `explaining-code` 5.7: one flow direction, one arrow per pair, at
+  most 12 arrows, labels of at most six words; C4 boundary labels sit top-left in a
+  small font so arrows do not cross them. At hand-over the agent asks whether VS Code
+  should open explainers as a preview (the pictures only show there) and sets it up on
+  yes.
 - Beta channel: every commit on `main` that passes CI is published to PyPI as a
   development version (`0.3.0.devN`); follow it with
   `pipx install --pip-args=--pre kingmadoc` and `pipx upgrade kingmadoc`.

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/CLAUDE.md

@@ -33,7 +33,7 @@ Flow for `plan "<description>"` (`cli.py`): `config.load_config` → `plan.analy
 - `plan/analyzer.py`: pathlib walk with fnmatch excludes ("glob", hard cap `MAX_FILES_LIMIT` = 5000), manifest parsing (`pyproject.toml`, `requirements.txt`, `package.json`, `go.mod`, `Cargo.toml`, compose files → `DEPENDENCY_TECH`), regex import scanning ("grep"). Returns an immutable `CodebaseReport` (`kingmadoc analyze` prints it via `format_report`, `--json` via `report_to_dict`); `source_dirs` drives container inference (descends into `src/` layouts, skips tests/docs/examples).
 - `skill/SKILL.md`: the product skill (Markdown-only KingmaDoc for users without Python; not the repo's `checking-conventions` dev skill): the workflow, under 250 lines. Its document formats live in `skill/reference/formats.md` and must keep the same headings as `src/kingmadoc/templates/plan_default.md.j2`, the extra-design templates and `verify/report.py` — `tests/test_skill.py` fails otherwise, so change both together; the Mermaid rules in `skill/reference/diagram-rules.md`. SKILL.md keeps a `## Output format` / `## Diagram rules` stub that links each reference. `skill/cursor.md`, `codex.md`, `copilot.md` are single files generated by `scripts/build_skill_variants.py`, which inlines each reference in place of its stub — never edit them; rerun the script after changing SKILL.md or a reference (`tests/test_skill.py` fails on stale variants). `kingmadoc skills install` copies SKILL.md plus `reference/`.
 - `adr.py` (`kingmadoc adr "<title>"`, gated by the top-level `adr.enabled`; `adr.template` selects the template): `adr_path` → `next_number` (max existing + 1, never reused) + `adr_filename` → `render_adr` (`templates/adr.md.j2`, bundled) → `docs/adr/<NNNN>-<slug>.md`. Not a mode; shares `naming.slugify` and `templating.load_template` with plan.
-- `render.py` (`kingmadoc render <doc>`): renders each ```` ```d2 ```` block to `img/<doc>-<n>.svg` (D2 via `d2_binary.ensure_d2`), moves its source to `img/<doc>-<n>.d2`, and leaves only `<!-- kingmadoc:diagram img/<doc>-<n>.d2 -->` + the image in the document (the comment is invisible in previews; re-rendering reads the `.d2` files, so edit those). Converts the older `<details>` format. Renders everything to a temp dir first, so a failing diagram changes nothing.
+- `render.py` (`kingmadoc render <doc>`): renders each ```` ```d2 ```` block with ELK to `img/<doc>-<n>.svg` (dark theme; D2 via `d2_binary.ensure_d2`) and, by default, `img/<doc>-<n>.png` via `raster.svg_to_png` (resvg; D2's embedded WOFF fonts unpacked to TTF and the `d2-N-font-*` CSS names mapped to family + weight, else text is missing), moves its source to `img/<doc>-<n>.d2`, and leaves only `<!-- kingmadoc:diagram img/<doc>-<n>.d2 -->` + the PNG (`--format svg`: the SVG) in the document; `diagram_warnings` = dark-mode styles (only reported for `--format svg`) + crowding (> 12 arrows, doubled pairs) (the comment is invisible in previews; re-rendering reads the `.d2` files, so edit those). Converts the older `<details>` format. Renders everything to a temp dir first, so a failing diagram changes nothing.
 - `d2_binary.py`: `ensure_d2` finds D2 (`KINGMADOC_D2`, PATH, cache) or downloads the pinned release once into the user cache; the SHA-256 per platform is pinned in `D2_ASSETS` (update version + all hashes together, cross-checked with the release's SHA256SUMS). `skills.py` + `kingmadoc skills install`: the skills in `skill/` ship as package data (hatch force-include) and are copied into the agent's skills dir; a `.kingmadoc-skill.json` manifest per skill folder records the installed hashes, so a reinstall updates unchanged files and only blocks local edits (`PREVIOUS_RELEASES` is the frozen hash list for installs from before the manifest).
 - `skill/explaining-code/`: second product skill; explains existing code (feature, branch, project, part) with D2 pictures, one folder per subject `docs/explain/<NNNN>-<slug>/README.md` (`explain.py` + `kingmadoc explain new`: next ID, never reused, same subject reuses its folder; regenerates the index `docs/explain/README.md`, also after `render` of such a file; `explain status` → `freshness`: `git diff --relative --name-only <Based on commit>` over the paths the explainer names in code spans (else the whole project), excluding `docs/explain`; `render` names a README's images `figure-<n>`). `SKILL.md` = workflow and D2 examples; the formats are `reference/arc42.md` (default) and `reference/c4.md`, chosen by `explain.format`; `reference/split.md` for `explain.documents: split` (cover + `functional.md` + `technical.md`); `reference/c4-model.md` (Simon Brown's C4: abstractions, 7 diagrams, notation, D2 style block, checklist) and `reference/models.md` (decision table + rules + one example per other model). `tests/test_skill_explaining_code.py` checks its format and compiles every D2 example with the real `d2` when available (`D2_BIN`); `tests/test_skill_models.py` checks every example obeys its model's rules. D2 pitfalls: quote labels with `[`/`:`; `source-arrowhead` only works on `<->`.
 - `facts/` (`kingmadoc explain facts`): pure parsers `projects.project_references` (.csproj) and `data_model.data_model` (EF Core via `DbSet<T>`, Prisma, Django, SQLAlchemy, TypeORM; regex, test files skipped) → frozen `Entity`/`Field`/`Relation`; `routes.routes` (ASP.NET controllers + minimal APIs, Next.js app/pages, Django urls + decorators, FastAPI, Flask, Express; `access` = what the code states), `services.services` (.NET DI), `js_modules.js_dependencies` (relative + tsconfig `paths` imports, `plan.dependencies.collapse` above 25 modules, `max_nodes=None` for the raw graph), `dominators.private_modules` (Cooper–Harvey–Kennedy on the raw Python + JS graphs; virtual root above the modules nothing imports; a single entry point is left out); `branch.branch_changes` (git I/O via `git.run_git`, merge base → working tree); `collect.collect_facts` reads files from the `CodebaseReport` and renders Markdown/JSON.

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: kingmadoc
-Version: 0.3.0.dev7
+Version: 0.3.0.dev9
 Summary: Feature docs for AI coding agents: a plan with C4 diagrams before the code, a verification doc after.
 Project-URL: Homepage, https://github.com/ATkingma/KingmaDoc
 Project-URL: Issues, https://github.com/ATkingma/KingmaDoc/issues
@@ -42,6 +42,7 @@ Requires-Python: >=3.11
 Requires-Dist: click>=8.1
 Requires-Dist: jinja2>=3.1
 Requires-Dist: pyyaml>=6.0
+Requires-Dist: resvg-py<0.6,>=0.5
 Provides-Extra: dev
 Requires-Dist: hypothesis>=6.100; extra == 'dev'
 Requires-Dist: import-linter>=2.1; extra == 'dev'
@@ -107,12 +108,11 @@ them are updated; files you edited are kept (`--force` replaces them too).
 
 Nothing else to install: the first `kingmadoc render` downloads the D2 diagram renderer by
 itself (pinned version, checksum-verified; `KINGMADOC_D2_DOWNLOAD=0` turns that off).
-VS Code opens a `.md` file as text, which shows no pictures. `kingmadoc skills install`
-asks whether VS Code should open explainers (`docs/explain/`) as a rendered preview
-instead, so you see the pictures right away (one setting in `.vscode/settings.json`;
-`--vscode` / `--no-vscode` answer up front). Without it, press Ctrl+Shift+V in an
-explainer. Visual Studio shows a preview by default. The pictures follow VS Code's light
-or dark theme.
+The pictures are PNG files linked from plain Markdown, so every Markdown preview shows
+them: Visual Studio and Rider (preview on by default), VS Code (Ctrl+Shift+V), GitHub,
+GitLab and Bitbucket. `render --format svg` links the SVG instead, which follows dark
+mode. VS Code opens `.md` as text: `kingmadoc skills install` offers to make it open
+explainers as a preview (`--vscode-user` for every folder, `--vscode` for this project).
 
 ### pip
 
@@ -158,8 +158,7 @@ agent adds the models the code calls for (UML sequence, state machine, class, ac
 with swimlanes, use case, ER, data flow with trust boundaries, context map), each drawn
 by its own notation rules. No stories, no audit. Install it next to the first one and ask the agent to "explain <feature / branch /
 project>". `kingmadoc skills install` installs it together with the first skill; the
-pictures are rendered with `kingmadoc render`; they follow the viewer's light or dark
-theme (`--light` for light only).
+pictures are rendered with `kingmadoc render` as PNG, which every editor shows.
 
 - The Codex and Copilot files are loaded in **every** session (about 17 KB). Codex
   stops reading `AGENTS.md` files after 32 KiB in total by default

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/README.md

@@ -53,12 +53,11 @@ them are updated; files you edited are kept (`--force` replaces them too).
 
 Nothing else to install: the first `kingmadoc render` downloads the D2 diagram renderer by
 itself (pinned version, checksum-verified; `KINGMADOC_D2_DOWNLOAD=0` turns that off).
-VS Code opens a `.md` file as text, which shows no pictures. `kingmadoc skills install`
-asks whether VS Code should open explainers (`docs/explain/`) as a rendered preview
-instead, so you see the pictures right away (one setting in `.vscode/settings.json`;
-`--vscode` / `--no-vscode` answer up front). Without it, press Ctrl+Shift+V in an
-explainer. Visual Studio shows a preview by default. The pictures follow VS Code's light
-or dark theme.
+The pictures are PNG files linked from plain Markdown, so every Markdown preview shows
+them: Visual Studio and Rider (preview on by default), VS Code (Ctrl+Shift+V), GitHub,
+GitLab and Bitbucket. `render --format svg` links the SVG instead, which follows dark
+mode. VS Code opens `.md` as text: `kingmadoc skills install` offers to make it open
+explainers as a preview (`--vscode-user` for every folder, `--vscode` for this project).
 
 ### pip
 
@@ -104,8 +103,7 @@ agent adds the models the code calls for (UML sequence, state machine, class, ac
 with swimlanes, use case, ER, data flow with trust boundaries, context map), each drawn
 by its own notation rules. No stories, no audit. Install it next to the first one and ask the agent to "explain <feature / branch /
 project>". `kingmadoc skills install` installs it together with the first skill; the
-pictures are rendered with `kingmadoc render`; they follow the viewer's light or dark
-theme (`--light` for light only).
+pictures are rendered with `kingmadoc render` as PNG, which every editor shows.
 
 - The Codex and Copilot files are loaded in **every** session (about 17 KB). Codex
   stops reading `AGENTS.md` files after 32 KiB in total by default

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/pyproject.toml

@@ -26,6 +26,8 @@ dependencies = [
     "click>=8.1",
     "jinja2>=3.1",
     "pyyaml>=6.0",
+    # SVG -> PNG for rendered diagrams (offline, wheels for every platform).
+    "resvg-py>=0.5,<0.6",
 ]
 
 [project.urls]
@@ -88,6 +90,10 @@ select = ["E", "W", "F", "I", "UP", "B", "S"]
 strict = true
 files = ["src"]
 
+[[tool.mypy.overrides]]
+module = ["resvg_py"]  # ships no type information
+ignore_missing_imports = true
+
 [tool.pytest.ini_options]
 testpaths = ["tests"]
 addopts = "-ra"
@@ -125,7 +131,7 @@ source_modules = [
     "kingmadoc.plan", "kingmadoc.verify", "kingmadoc.facts", "kingmadoc.diagrams",
     "kingmadoc.about", "kingmadoc.adr", "kingmadoc.config", "kingmadoc.d2_binary",
     "kingmadoc.documents", "kingmadoc.exceptions", "kingmadoc.explain", "kingmadoc.git",
-    "kingmadoc.naming", "kingmadoc.plandoc", "kingmadoc.render", "kingmadoc.skills",
+    "kingmadoc.naming", "kingmadoc.plandoc", "kingmadoc.raster", "kingmadoc.render", "kingmadoc.skills",
     "kingmadoc.templating", "kingmadoc.vscode",
 ]
 forbidden_modules = ["click", "kingmadoc.cli"]

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/skill/explaining-code/SKILL.md

@@ -1,7 +1,7 @@
 ---
 name: explaining-code
 description: "Explains existing code with rendered diagrams (C4 in Simon Brown's notation; UML sequence, state, class, activity, use case; ER; data flow) and short tables, as an arc42 or compact C4 document, one file or split into functional and technical. Fixes code blindness, e.g. after an agent wrote the code. Scope: a feature, a branch or PR, a whole project, or a folder, service or module. Use when the user asks to explain, describe, document, map, diagram, draw, visualise or give an overview of existing code or architecture; asks how something works, what it does, how the parts fit together, where something happens, or what a branch, PR, commit or task changed; wants onboarding, a walkthrough, a codebase tour, an architecture or design document, arc42, C4, UML, sequence, ER or deployment diagrams of existing code; or no longer understands the code. The request may be in any language. Not for features that are not built yet."
-version: 5.6.0
+version: 5.8.0
 allowed-tools: [Read, Write, Glob, Grep, Bash]
 ---
 
@@ -158,11 +158,17 @@ Write every diagram in **D2** (Step 5 turns them into images).
    eight figures in total.
 3. **Place them** where the format (or, when split, [reference/split.md](reference/split.md))
    says: e.g. arc42 section 6 for flows and lifecycles, section 8 for data and domain.
-4. **Readable in dark mode:** the images follow the viewer's light or dark theme. Give
+4. **Readable in dark mode:** the SVG next to each PNG follows the viewer's theme. Give
    every shape you fill (`fill:`) a `font-color` too, and black dots a grey `stroke`.
    Never set a `font-color` without a fill (titles, labels: the theme picks the colour),
    and never fill white: boundaries and nodes are `fill: transparent`. Put
    `shape: sequence_diagram` at the top level, or give its container the label `""`.
+5. **Tidy arrows:** set `direction: down` (people on top, data stores at the bottom;
+   `right` only for timelines and swimlanes), draw one arrow per pair of shapes with a
+   combined label, keep at most 12 arrows per figure (split it otherwise, e.g. one
+   figure per container), label each arrow in at most six words plus `[protocol]`, and
+   point arrows at the shapes inside a boundary, not at the boundary. `kingmadoc render`
+   lays figures out with straight, right-angled arrows (ELK) and warns about crowded ones.
 
 For a **branch**, mark changes by border, so the C4 colours stay meaningful, and add
 both to the legend:
@@ -174,6 +180,7 @@ classes: {
   changed: {style: {stroke: "#ef6c00"; stroke-width: 4}}
 }
 title: "[Container] Webshop - branch feature/invoices" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     n: New in this branch {class: [container; new]}
@@ -212,10 +219,12 @@ An explainer is not finished until its diagrams are pictures. Run:
 kingmadoc render docs/explain/<NNNN>-<slug>/*.md
 ```
 
-It replaces each diagram block with its image (`img/figure-<n>.svg` for `README.md`,
-`img/functional-<n>.svg` and `img/technical-<n>.svg` when split) and moves the D2
-source next to it (`.d2`), so the documents show only pictures. Each image has a light
-and a dark theme and follows the viewer's (`--light`: light only). To change a diagram
+It replaces each diagram block with a PNG (`img/figure-<n>.png` for `README.md`,
+`img/functional-<n>.png` and `img/technical-<n>.png` when split), which every editor
+and Git host shows: VS Code, Visual Studio, Rider, GitHub, GitLab, Bitbucket. Next to it
+go an `.svg` (sharp, follows dark mode) and the D2 source (`.d2`), so the documents show
+only pictures. Never convert the images yourself (PNG scripts, HTML or PDF exports):
+`render` already makes the PNG. To change a diagram
 later, edit its `.d2` file and render again. The first time it downloads D2 by itself
 (checksum-verified). **Never ask the user to install D2**, even when `d2` is not
 on the PATH: `kingmadoc render` does not need it.
@@ -225,7 +234,7 @@ on the PATH: `kingmadoc render` does not need it.
   `pipx upgrade kingmadoc` (installed from GitHub: `pipx reinstall kingmadoc`), then render.
 - `kingmadoc` is not installed at all: render with `d2` if it happens to be available
   (save each diagram as `img/figure-<n>.d2` in the subject's folder, run
-  `d2 --pad 20 <that>.d2 <that>.svg`, and replace the block with
+  `d2 --pad 20 --layout elk <that>.d2 <that>.svg`, and replace the block with
   `![<caption>](img/figure-<n>.svg)`); otherwise say that installing KingmaDoc gives
   the pictures.
 
@@ -236,6 +245,10 @@ Go through the checklist of each figure's model (end of
 and fix what fails; check that the document embeds every image. Then hand over in at most five lines:
 the path, one or two sentences on what the system is, the number of figures, and the
 "Couldn't work out" questions (at most three), which you then answer into the explainer.
-Do not paste the explainer or its figures into the chat. If VS Code opens it as text,
-say once that Ctrl+Shift+V shows the pictures, or `kingmadoc skills install --vscode`
-always does; never run that without the user's consent.
+Do not paste the explainer or its figures into the chat.
+
+VS Code shows the pictures only in its Markdown preview. If `.vscode/settings.json` does
+not yet open `docs/explain/` as a preview, Ask once: "Should VS Code open explainers
+directly as a preview, with the pictures?" and, on yes, run
+`kingmadoc skills install --vscode` (it adds one setting). Never run it without that yes;
+without it, mention that Ctrl+Shift+V shows the pictures.

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/skill/explaining-code/reference/arc42.md

@@ -63,7 +63,7 @@ Text in `<angle brackets>` is filled in; leave out subsections marked optional.
 | **Scope**        | <feature / branch `<branch>` vs `<base>` / project / part `<path>`>                 |
 | **Stack**        | <languages, frameworks, data stores>                                                |
 | **Entry points** | <`path`, …>                                                                         |
-| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.6.0 (arc42) |
+| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.8.0 (arc42) |
 
 ## What changed (branch only)
 

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/skill/explaining-code/reference/c4-model.md

@@ -106,10 +106,11 @@ classes: {
   container: {shape: rectangle; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   component: {shape: rectangle; style: {fill: "#85bbf0"; stroke: "#5d82a8"; font-color: "#000000"}}
-  boundary: {style: {fill: transparent; stroke: "#888888"; stroke-dash: 4}}
-  node: {style: {fill: transparent; stroke: "#888888"}}
+  boundary: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; stroke-dash: 4; font-size: 15}}
+  node: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; font-size: 15}}
 }
 title: "[System Context] Webshop" {
+direction: down
   shape: text
   near: top-center
   style: {font-size: 24; bold: true}
@@ -155,9 +156,10 @@ classes: {
   external: {shape: rectangle; style: {fill: "#999999"; stroke: "#6b6b6b"; font-color: "#ffffff"}}
   container: {shape: rectangle; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
-  boundary: {style: {fill: transparent; stroke: "#888888"; stroke-dash: 4}}
+  boundary: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; stroke-dash: 4; font-size: 15}}
 }
 title: "[Container] Webshop" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     p: Person {class: person}
@@ -213,9 +215,10 @@ classes: {
   container: {shape: rectangle; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   component: {shape: rectangle; style: {fill: "#85bbf0"; stroke: "#5d82a8"; font-color: "#000000"}}
-  boundary: {style: {fill: transparent; stroke: "#888888"; stroke-dash: 4}}
+  boundary: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; stroke-dash: 4; font-size: 15}}
 }
 title: "[Component] Webshop - API" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     c: Container {class: container}
@@ -262,9 +265,10 @@ instances they run; infrastructure (proxy, DNS) only when the code configures it
 classes: {
   container: {shape: rectangle; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
-  node: {style: {fill: transparent; stroke: "#888888"}}
+  node: {label.near: top-left; style: {fill: transparent; stroke: "#888888"; font-size: 15}}
 }
 title: "[Deployment] Webshop - production" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     n: Deployment node {class: node}
@@ -298,6 +302,7 @@ classes: {
   database: {shape: cylinder; style: {fill: "#438dd5"; stroke: "#3c7fc0"; font-color: "#ffffff"}}
 }
 title: "[Dynamic] Webshop - placing an order" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 vars: {
   d2-legend: {
     p: Person {class: person}

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/skill/explaining-code/reference/c4.md

@@ -22,7 +22,7 @@ Text in `<angle brackets>` is filled in.
 | **Scope**        | <feature / branch `<branch>` vs `<base>` / project / part `<path>`>         |
 | **Stack**        | <languages, frameworks, data stores>                                        |
 | **Entry points** | <`path`, …>                                                                 |
-| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.6.0 |
+| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.8.0 |
 
 ## In short
 

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/skill/explaining-code/reference/models.md

@@ -140,6 +140,7 @@ no methods, no types, multiplicities kept.
 
 ```d2
 title: "[Class] Diagram backends" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 backend: "«interface» DiagramBackend" {
   shape: class
   "+render_context(diagram)": str
@@ -171,6 +172,7 @@ inside it.
 
 ```d2
 title: "[Package] kingmadoc" {shape: text; near: top-center; style: {font-size: 24; bold: true}}
+direction: down
 cli: cli {shape: package}
 plan: plan {shape: package}
 diagrams: diagrams {shape: package}

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/skill/explaining-code/reference/split.md

@@ -43,7 +43,7 @@ in its first line. `kingmadoc render` takes all three files at once.
 | **Scope**        | <feature / branch `<branch>` vs `<base>` / project / part `<path>`>                 |
 | **Stack**        | <languages, frameworks, data stores>                                                |
 | **Entry points** | <`path`, …>                                                                         |
-| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.6.0 (split) |
+| **Based on**     | <commit hash (branch)> · <ISO date> · KingmaDoc skill explaining-code 5.8.0 (split) |
 
 <at most three plain sentences: what it is, for whom, what it does>
 

{kingmadoc-0.3.0.dev7 → kingmadoc-0.3.0.dev9}/src/kingmadoc/cli.py

@@ -49,7 +49,7 @@ from kingmadoc.plan.generator import (
     render_plan,
 )
 from kingmadoc.plandoc import check_plan, generated_at, parse_plan, set_status
-from kingmadoc.render import dark_mode_warnings, render_file
+from kingmadoc.render import IMAGE_FORMATS, diagram_warnings, render_file
 from kingmadoc.skills import AGENT_DIRS, install_skills
 from kingmadoc.verify.changes import detect_changes
 from kingmadoc.verify.commands import MARKER_FILES, detect_commands, run_check
@@ -61,7 +61,11 @@ from kingmadoc.verify.deviations import (
 )
 from kingmadoc.verify.locate import find_plan, verify_output_path
 from kingmadoc.verify.report import render_verify, verify_status
-from kingmadoc.vscode import enable_markdown_preview, preview_enabled
+from kingmadoc.vscode import (
+    enable_markdown_preview,
+    enable_user_markdown_preview,
+    preview_enabled,
+)
 
 ROOT_OPTION = click.option(
     "--root",
@@ -438,18 +442,29 @@ def adr(title: str, root: Path, config_path: Path | None, status: str) -> None:
     "--light", is_flag=True, help="Light images only (by default they follow dark mode too)."
 )
 @click.option("--verbose", is_flag=True, help="Print every image path (default: one line).")
-def render_command(documents: tuple[Path, ...], light: bool, verbose: bool) -> None:
-    """Render the D2 diagrams in DOCUMENTS to SVG images and embed them.
+@click.option(
+    "--format",
+    "image_format",
+    type=click.Choice(IMAGE_FORMATS),
+    default="png",
+    show_default=True,
+    help="What the document links: png shows in every Markdown viewer; svg follows dark mode.",
+)
+def render_command(
+    documents: tuple[Path, ...], light: bool, verbose: bool, image_format: str
+) -> None:
+    """Render the D2 diagrams in DOCUMENTS to images and embed them.
 
-    Images go to img/<document>-<n>.svg next to each document (img/figure-<n>.svg for a
-    README.md), their D2 sources to img/*.d2. D2 is downloaded once (pinned,
-    checksum-verified) unless it is on PATH or in KINGMADOC_D2. Prints the image paths.
+    Each diagram becomes img/<document>-<n>.png (linked: every Markdown viewer shows it)
+    and .svg (sharp, follows dark mode; --format svg links it instead), with its D2 source
+    in img/*.d2; a README.md's images are img/figure-<n>. D2 is downloaded once (pinned,
+    checksum-verified) unless it is on PATH or in KINGMADOC_D2.
     """
     try:
         d2 = ensure_d2(lambda message: click.echo(message, err=True))
         hinted = False
         for document in documents:
-            images = render_file(document, d2, dark=not light)
+            images = render_file(document, d2, dark=not light, image_format=image_format)
             index = index_path(document)
             if index is not None:
                 _write_explain_index(index.parent)
@@ -459,7 +474,7 @@ def render_command(documents: tuple[Path, ...], light: bool, verbose: bool) -> N
                     click.echo(
                         "VS Code shows the pictures in the preview: open the file and press "
                         "Ctrl+Shift+V (macOS: Cmd+Shift+V), or run `kingmadoc skills install "
-                        "--vscode` to always open explainers as a preview.",
+                        "--vscode-user` to always open explainers as a preview.",
                         err=True,
                     )
             if not images:
@@ -474,10 +489,12 @@ def render_command(documents: tuple[Path, ...], light: bool, verbose: bool) -> N
                 noun = "image" if len(images) == 1 else "images"
                 click.echo(f"{document}: {len(images)} {noun} ({span})")
             for image in images:
-                if not light:
-                    source = image.with_suffix(".d2")
-                    for warning in dark_mode_warnings(source.read_text(encoding="utf-8")):
-                        click.echo(f"{source}: {warning} (dark mode)", err=True)
+                source = image.with_suffix(".d2")  # next to the .png and .svg
+                for warning in diagram_warnings(source.read_text(encoding="utf-8")):
+                    dark_mode = not light and image_format == "svg"
+                    if not dark_mode and warning.endswith("(dark mode)"):
+                        continue
+                    click.echo(f"{source}: {warning}", err=True)
     except KingmaDocError as exc:
         raise click.ClickException(str(exc)) from exc
 
@@ -625,10 +642,18 @@ def skills_group() -> None:
 @click.option(
     "--vscode/--no-vscode",
     default=None,
-    help="Make VS Code open explainers as a rendered preview (.vscode/settings.json), or "
-    "not. Without either, a terminal asks; other runs only print a tip.",
+    help="Make VS Code open this project's explainers as a rendered preview "
+    "(.vscode/settings.json; only when this folder is the open workspace), or not.",
 )
-def skills_install(root: Path, agent: str, force: bool, vscode: bool | None) -> None:
+@click.option(
+    "--vscode-user",
+    is_flag=True,
+    help="Make VS Code open explainers as a rendered preview in every folder (user "
+    "settings). Without a VS Code option, a terminal asks; other runs print a tip.",
+)
+def skills_install(
+    root: Path, agent: str, force: bool, vscode: bool | None, vscode_user: bool
+) -> None:
     """Install the KingmaDoc skills into the project for AGENT (Agent Skills standard).
 
     Also offers to make VS Code open docs/explain/ as a rendered preview, so the pictures
@@ -636,16 +661,21 @@ def skills_install(root: Path, agent: str, force: bool, vscode: bool | None) ->
     """
     try:
         result = install_skills(root, agent, force)
-        if vscode is None and not preview_enabled(root) and _interactive():
+        asked = vscode is None and not vscode_user
+        if asked and not preview_enabled(root) and _interactive():
             try:
-                vscode = click.confirm(
+                vscode_user = click.confirm(
                     "Make VS Code open explainers (docs/explain/) as a rendered preview, so "
-                    "the pictures show right away?", default=True, err=True,
+                    "the pictures show right away? (VS Code user settings)",
+                    default=True, err=True,
                 )
             except click.Abort:  # stdin closed without an answer: change nothing
                 click.echo("", err=True)
-                vscode = False
-        preview = enable_markdown_preview(root) if vscode else None
+        preview = None
+        if vscode_user:
+            preview = enable_user_markdown_preview()
+        elif vscode:
+            preview = enable_markdown_preview(root)
     except KingmaDocError as exc:
         raise click.ClickException(str(exc)) from exc
     for path in result.written:
@@ -656,9 +686,10 @@ def skills_install(root: Path, agent: str, force: bool, vscode: bool | None) ->
         click.echo(f"{len(result.up_to_date)} skill file(s) already up to date.", err=True)
     if preview:
         click.echo(preview, err=True)
-    elif vscode is None and not preview_enabled(root):
+    elif asked and not preview_enabled(root):
         click.echo(
-            "Tip: --vscode makes VS Code open explainers (docs/explain/) as a rendered preview.",
+            "Tip: --vscode-user makes VS Code open explainers (docs/explain/) as a rendered "
+            "preview, with the pictures.",
             err=True,
         )
 

kingmadoc-0.3.0.dev9/src/kingmadoc/raster.py

@@ -0,0 +1,141 @@
+"""SVG to PNG for rendered diagrams, so every Markdown viewer shows them.
+
+VS Code, Visual Studio, Rider, GitHub, GitLab and Bitbucket all show a PNG in Markdown;
+several block or mishandle SVG. The conversion runs offline with resvg (a small wheel,
+no system libraries). D2 embeds its fonts (Source Sans Pro, as WOFF subsets) in each
+SVG; resvg cannot read WOFF or CSS ``@font-face``, so the fonts are unpacked to TrueType
+and the CSS names D2 made up (``d2-123-font-bold``) become the real family and weight.
+Without that, text is measured with another font and clipped.
+"""
+
+from __future__ import annotations
+
+import base64
+import re
+import struct
+import tempfile
+import zlib
+from collections.abc import Mapping
+from pathlib import Path
+from types import MappingProxyType
+
+import resvg_py
+
+from kingmadoc.exceptions import RenderError
+
+# 2x: sharp on high-DPI screens, still small (a typical diagram is 100-300 KB).
+ZOOM = 2
+_FONT_FACE = re.compile(
+    r"@font-face\s*\{\s*font-family:\s*(d2-\d+-font-[\w-]+);\s*"
+    r"src:\s*url\(\"data:application/font-woff;base64,([A-Za-z0-9+/=]+)\"\)[^}]*\}"
+)
+_FONT_USE = re.compile(r"font-family:\s*\"?d2-\d+-font-([\w-]+)\"?")
+_STYLES: Mapping[str, str] = MappingProxyType({
+    "regular": "font-weight: normal; font-style: normal",
+    "bold": "font-weight: bold; font-style: normal",
+    "semibold": "font-weight: 600; font-style: normal",
+    "italic": "font-weight: normal; font-style: italic",
+})
+
+
+def svg_to_png(svg: str) -> bytes:
+    """Rasterize a D2 SVG with its own fonts.
+
+    Args:
+        svg: The SVG text D2 wrote.
+
+    Returns:
+        PNG bytes at :data:`ZOOM` times the SVG size (light theme: resvg ignores the
+        dark-mode media query, so the picture reads on any background).
+
+    Raises:
+        RenderError: If the SVG cannot be rasterized.
+    """
+    faces = _FONT_FACE.findall(svg)
+    families: dict[str, str] = {}
+    with tempfile.TemporaryDirectory(prefix="kingmadoc-fonts-") as tmp:
+        files = []
+        for index, (name, data) in enumerate(faces):
+            try:
+                sfnt = woff_to_sfnt(base64.b64decode(data))
+                families[name] = font_family(sfnt) or "sans-serif"
+            except (RenderError, ValueError, struct.error, zlib.error):
+                continue  # an unreadable font: its text falls back to another font
+            path = Path(tmp) / f"{index}.ttf"
+            path.write_bytes(sfnt)
+            files.append(str(path))
+        family = next(iter(families.values()), "sans-serif")
+        text = _FONT_USE.sub(
+            lambda m: f'font-family: "{family}"; {_STYLES.get(m.group(1), _STYLES["regular"])}',
+            re.sub(r"@font-face\s*\{[^}]*\}", "", svg),
+        )
+        try:
+            png = resvg_py.svg_to_bytes(
+                svg_string=text, font_files=files, skip_system_fonts=bool(files), zoom=ZOOM
+            )
+        except Exception as exc:  # noqa: BLE001 - resvg raises bare exceptions (and panics)
+            raise RenderError(f"Could not convert the diagram to PNG: {exc}") from exc
+    return bytes(png)
+
+
+def woff_to_sfnt(data: bytes) -> bytes:
+    """Unpack a WOFF 1.0 font to the TrueType/OpenType file it wraps.
+
+    Args:
+        data: The WOFF file.
+
+    Returns:
+        The sfnt (``.ttf``/``.otf``) bytes.
+
+    Raises:
+        RenderError: If ``data`` is not WOFF 1.0.
+    """
+    if len(data) < 44 or data[:4] != b"wOFF":
+        raise RenderError("not a WOFF 1.0 font")
+    flavor, _length, count = struct.unpack(">4xIIH", data[:14])
+    tables = []
+    for i in range(count):
+        tag, offset, size, original, checksum = struct.unpack(
+            ">4sIIII", data[44 + 20 * i : 64 + 20 * i]
+        )
+        raw = data[offset : offset + size]
+        tables.append((tag, zlib.decompress(raw) if size < original else raw, checksum))
+    tables.sort()
+    search = 1
+    while search * 2 <= count:
+        search *= 2
+    header = struct.pack(
+        ">IHHHH", flavor, count, search * 16, search.bit_length() - 1, count * 16 - search * 16
+    )
+    offset = 12 + 16 * count
+    directory, body = b"", b""
+    for tag, table, checksum in tables:
+        directory += struct.pack(">4sIII", tag, checksum, offset + len(body), len(table))
+        body += table + b"\0" * (-len(table) % 4)
+    return header + directory + body
+
+
+def font_family(sfnt: bytes) -> str:
+    """Return a font's family name (name table, name ID 1), or "" when it has none.
+
+    Args:
+        sfnt: A TrueType/OpenType font.
+
+    Returns:
+        E.g. ``"Source Sans Pro"``.
+    """
+    count = struct.unpack(">H", sfnt[4:6])[0]
+    for i in range(count):
+        tag, _checksum, offset, length = struct.unpack(">4sIII", sfnt[12 + 16 * i : 28 + 16 * i])
+        if tag != b"name":
+            continue
+        table = sfnt[offset : offset + length]
+        _format, records, strings = struct.unpack(">HHH", table[:6])
+        for j in range(records):
+            platform, _enc, _lang, name_id, size, start = struct.unpack(
+                ">HHHHHH", table[6 + 12 * j : 18 + 12 * j]
+            )
+            if name_id == 1:
+                raw = table[strings + start : strings + start + size]
+                return raw.decode("utf-16-be" if platform in (0, 3) else "latin-1", "replace")
+    return ""