Skip to content

Turn any idea, plan, or codebase into a beautiful interactive diagram. An agent skill for Claude Code, Codex, and more.

release: archify 2.7.0

tt-a1ie98993ab2818
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 6305b348..37a6ea7e 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -4,6 +4,22 @@ All notable changes are documented here. Format loosely follows [Keep a Changelo
## [Unreleased]
+## [2.7.0] — 2026-07-03
+
+### Added
+- **Post-render artifact checker.** Added `scripts/check-render-output.mjs`, a zero-dependency final HTML/SVG gate that checks for a single SVG block, non-finite SVG values, accidental two-point diagonal arrows, and arrows crossing the legend.
+- **Workflow phase headers, groups, and exception lanes.** Workflow JSON now supports `phases`, `groups`, and `lane.variant: "exception"` so diagrams can make story beats, branch areas, and human/policy stop paths explicit.
+- **Workflow `mainPath` lint.** The workflow renderer can validate that happy-path node ids are linked in order and do not accidentally move backward.
+- **Artifact-check tests.** `test/render-output-checks.test.mjs` covers the new checker, including the legend-collision case that visual review exposed.
+
+### Changed
+- The renderer loop in `SKILL.md` and the workflow README now includes the post-render artifact checker as a standard delivery step.
+- The workflow example was regenerated to demonstrate phases, groups, an exception lane, and clearer return/trace paths.
+
+### Fixed
+- **Same-lane offset routing.** Default same-lane workflow edges with different `yOffset` values now route orthogonally instead of drawing a two-point diagonal.
+- **Legend collision in generated workflow previews.** The generated Archify renderer-pipeline preview now routes the compare path through a lane gap instead of crossing the legend.
+
## [2.6.0] — 2026-06-12
### Added
diff --git a/README.md b/README.md
index 97fad418..aa45f038 100644
--- a/README.md
+++ b/README.md
@@ -17,7 +17,7 @@ Archify is an agent skill for Claude, Codex CLI, and opencode. It turns a plain-
![License](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)
![Agent Skill](https://img.shields.io/badge/Agent-Skill-7C3AED?style=flat-square)
-![Version](https://img.shields.io/badge/version-2.6.0-0891b2?style=flat-square)
+![Version](https://img.shields.io/badge/version-2.7.0-0891b2?style=flat-square)
**Project page:** [tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)
@@ -97,21 +97,23 @@ Open the example here: [`examples/lifecycle-agent-run.html`](examples/lifecycle-
## What's new
-Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed a long-standing upsampling bug and made every raster export genuinely sharp at 4× source resolution (the 1× / 2× / 4× selector introduced in 2.1 was removed at the same time — it only encouraged picking a soft-looking scale). **2.4** upgraded the SVG export to a dual-theme self-contained file — drop the same `.svg` into a GitHub README and it follows the reader's dark/light preference automatically. **2.5** is a hardening release: a batch of verified renderer and validation bug fixes (template slot corruption, cross-lane lifecycle overlap detection, light-theme lane colors in PNG/SVG exports, Safari clipboard copy), LLM-ergonomic validation errors with numeric thresholds and fix suggestions, Mermaid accepted as an input dialect (mapped through `SKILL.md` prompts, not a parser), CJK-aware text measurement plus CJK font fallbacks, and a golden-file test suite with CI.
-
-| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 |
-|---|---|---|---|---|---|---|---|
-| Dark theme | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
-| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut | Same | Same |
-| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** | Same | **Light-export lane colors fixed** |
-| SVG download | — | Vector, styles inlined (single theme) | Same | Same | Same | **Dual-theme self-contained** (`@media prefers-color-scheme`) | Same (lane colors fixed) |
-| Copy PNG to clipboard | — | — | Yes | Same | Yes (up to 4×) | Same | **Safari fix** |
-| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same | Same | Same |
-| Accessibility | — | — | ARIA + focus-visible | Same | Same | Same | Same (+ menu a11y fixes) |
-| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) | Same | Same |
-| Local-font fallback on export | — | — | — | Yes | Yes | Same | **+ CJK font fallback** |
-| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same | Same | Same |
-| Typed renderers + schema validation | — | — | — | — | — | — | **Yes (with tests & CI)** |
+Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed the raster upsampling bug and made exports genuinely sharp at up to 4× source resolution. **2.4** upgraded SVG export to a dual-theme self-contained file. **2.5** added renderer-backed workflow / sequence / data-flow / lifecycle modes, Mermaid input guidance, CJK-aware text measurement, golden tests, and CI. **2.6** brought the architecture renderer to schema + layout validation parity. **2.7** hardens workflow diagrams with phase headers, groups, exception lanes, happy-path linting, same-lane orthogonal routing, and a post-render HTML/SVG checker that catches diagonal arrows and legend collisions before delivery.
+
+| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 | 2.6 | 2.7 |
+|---|---|---|---|---|---|---|---|---|---|
+| Dark theme | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut | Same | Same | Same | Same |
+| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** | Same | **Light-export lane colors fixed** | Same | Same |
+| SVG download | — | Vector, styles inlined (single theme) | Same | Same | Same | **Dual-theme self-contained** (`@media prefers-color-scheme`) | Same (lane colors fixed) | Same | Same |
+| Copy PNG to clipboard | — | — | Yes | Same | Yes (up to 4×) | Same | **Safari fix** | Same | Same |
+| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same | Same | Same | Same | Same |
+| Accessibility | — | — | ARIA + focus-visible | Same | Same | Same | Same (+ menu a11y fixes) | Same | Same |
+| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) | Same | Same | Same | Same |
+| Local-font fallback on export | — | — | — | Yes | Yes | Same | **+ CJK font fallback** | Same | Same |
+| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same | Same | Same | Same | Same |
+| Typed renderers + schema validation | — | — | — | — | — | — | Workflow / sequence / data-flow / lifecycle | **+ architecture** | Same |
+| Workflow structure aids | — | — | — | — | — | — | Lanes + routed edges | Same | **Phases, groups, exception lanes, mainPath lint** |
+| Post-render artifact checker | — | — | — | — | — | — | — | — | **Yes** |
## Quick start
@@ -163,6 +165,14 @@ cd ~/.agents/skills/archify && npm install
Without the dependency the renderers skip schema validation (layout checks still run).
+For renderer-backed diagrams, the skill also runs a post-render artifact check:
+
+```bash
+node scripts/check-render-output.mjs output.html
+```
+
+That final gate inspects the generated HTML/SVG for malformed output, non-finite SVG values, accidental two-point diagonal arrows, and arrows crossing the legend.
+
**Claude.ai Projects (alternative):**
Upload [`archify.zip`](archify.zip) to your Project Knowledge.
@@ -323,6 +333,7 @@ Each color has coordinated dark-mode and light-mode variants that switch togethe
- **Styling:** CSS custom properties on `:root` + `[data-theme="light"]`; SVG elements reference semantic classes (`c-frontend`, `t-muted`, `a-emphasis`, etc.). Toggling `data-theme` on `<html>` re-themes the entire diagram including gradient, grid, arrows, and mask rects.
- **Export pipeline:** The SVG is cloned, host `<style>` is inlined, and current theme variables are resolved and written into a `:root` rule on the clone. For raster formats the clone's `width`/`height` are set to `4 × viewBox` so the browser rasterizes the vectors at target resolution natively; the canvas is sized to match and the image is drawn at natural size (no bitmap upsampling). `toBlob(mime)` then produces the file. JPEG gets an explicit background fill since it has no alpha. If the target resolution would exceed the browser's canvas limits, the pipeline automatically falls back to 3× or 2× so the export still succeeds.
- **Self-contained output:** Single HTML file, Google Fonts link + inline SVG + ~19 KB of embedded JS. No build step, no JS framework, no server — the generated HTML itself has zero dependencies (the typed renderers need `npm install` for ajv, see [Install](#1-install-the-skill)).
+- **Output checks:** `scripts/check-render-output.mjs` validates generated HTML before delivery: one SVG, finite SVG values, no accidental two-point diagonal arrows, and no arrow segments crossing the legend.
- **Browser support:** Any modern browser (Chrome, Safari, Firefox, Edge). Needs `Image` + `canvas.toBlob` with `image/webp` support for WebP export.
## Attribution
@@ -337,6 +348,8 @@ Archify 2.x contributes:
- Dual-theme self-contained SVG export (single file follows the host's `prefers-color-scheme`)
- Keyboard navigation + accessibility semantics
- Print stylesheet + local-font fallback
+- Renderer-backed architecture, workflow, sequence, data-flow, and lifecycle diagrams with schema validation
+- Post-render artifact checks for final HTML/SVG quality
- Updated `SKILL.md` to guide Claude toward class-based (themeable) diagrams
Both projects are MIT-licensed.
diff --git a/README_EN.md b/README_EN.md
index 97fad418..aa45f038 100644
--- a/README_EN.md
+++ b/README_EN.md
@@ -17,7 +17,7 @@ Archify is an agent skill for Claude, Codex CLI, and opencode. It turns a plain-
![License](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)
![Agent Skill](https://img.shields.io/badge/Agent-Skill-7C3AED?style=flat-square)
-![Version](https://img.shields.io/badge/version-2.6.0-0891b2?style=flat-square)
+![Version](https://img.shields.io/badge/version-2.7.0-0891b2?style=flat-square)
**Project page:** [tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)
@@ -97,21 +97,23 @@ Open the example here: [`examples/lifecycle-agent-run.html`](examples/lifecycle-
## What's new
-Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed a long-standing upsampling bug and made every raster export genuinely sharp at 4× source resolution (the 1× / 2× / 4× selector introduced in 2.1 was removed at the same time — it only encouraged picking a soft-looking scale). **2.4** upgraded the SVG export to a dual-theme self-contained file — drop the same `.svg` into a GitHub README and it follows the reader's dark/light preference automatically. **2.5** is a hardening release: a batch of verified renderer and validation bug fixes (template slot corruption, cross-lane lifecycle overlap detection, light-theme lane colors in PNG/SVG exports, Safari clipboard copy), LLM-ergonomic validation errors with numeric thresholds and fix suggestions, Mermaid accepted as an input dialect (mapped through `SKILL.md` prompts, not a parser), CJK-aware text measurement plus CJK font fallbacks, and a golden-file test suite with CI.
-
-| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 |
-|---|---|---|---|---|---|---|---|
-| Dark theme | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
-| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut | Same | Same |
-| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** | Same | **Light-export lane colors fixed** |
-| SVG download | — | Vector, styles inlined (single theme) | Same | Same | Same | **Dual-theme self-contained** (`@media prefers-color-scheme`) | Same (lane colors fixed) |
-| Copy PNG to clipboard | — | — | Yes | Same | Yes (up to 4×) | Same | **Safari fix** |
-| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same | Same | Same |
-| Accessibility | — | — | ARIA + focus-visible | Same | Same | Same | Same (+ menu a11y fixes) |
-| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) | Same | Same |
-| Local-font fallback on export | — | — | — | Yes | Yes | Same | **+ CJK font fallback** |
-| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same | Same | Same |
-| Typed renderers + schema validation | — | — | — | — | — | — | **Yes (with tests & CI)** |
+Archify is based on [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0 (dark-only, HTML output). **2.0** rewrote the template around a themeable CSS-variable system and added a client-side export pipeline. **2.1** added copy-to-clipboard + keyboard nav. **2.2** added a print stylesheet + local-font fallback. **2.3** fixed the raster upsampling bug and made exports genuinely sharp at up to 4× source resolution. **2.4** upgraded SVG export to a dual-theme self-contained file. **2.5** added renderer-backed workflow / sequence / data-flow / lifecycle modes, Mermaid input guidance, CJK-aware text measurement, golden tests, and CI. **2.6** brought the architecture renderer to schema + layout validation parity. **2.7** hardens workflow diagrams with phase headers, groups, exception lanes, happy-path linting, same-lane orthogonal routing, and a post-render HTML/SVG checker that catches diagonal arrows and legend collisions before delivery.
+
+| Feature | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 | 2.6 | 2.7 |
+|---|---|---|---|---|---|---|---|---|---|
+| Dark theme | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes | Yes |
+| Light theme | — | Toggle | Toggle | Toggle | Toggle + <kbd>T</kbd> shortcut | Same | Same | Same | Same |
+| PNG / JPEG / WebP download | manual screenshot | 2× bitmap-upsampled | 1× / 2× / 4× selector (still upsampled) | same | **4× rasterized natively — no blur** | Same | **Light-export lane colors fixed** | Same | Same |
+| SVG download | — | Vector, styles inlined (single theme) | Same | Same | Same | **Dual-theme self-contained** (`@media prefers-color-scheme`) | Same (lane colors fixed) | Same | Same |
+| Copy PNG to clipboard | — | — | Yes | Same | Yes (up to 4×) | Same | **Safari fix** | Same | Same |
+| Keyboard shortcuts | — | — | <kbd>T</kbd> / <kbd>E</kbd> + menu nav | Same | Same | Same | Same | Same | Same |
+| Accessibility | — | — | ARIA + focus-visible | Same | Same | Same | Same (+ menu a11y fixes) | Same | Same |
+| Print stylesheet | — | — | — | Yes | Yes (+ landscape + 2-col cards) | Same | Same | Same | Same |
+| Local-font fallback on export | — | — | — | Yes | Yes | Same | **+ CJK font fallback** | Same | Same |
+| Styling model | Inline `fill` / `stroke` | CSS custom properties + semantic classes | Same | Same | Same | Same | Same | Same | Same |
+| Typed renderers + schema validation | — | — | — | — | — | — | Workflow / sequence / data-flow / lifecycle | **+ architecture** | Same |
+| Workflow structure aids | — | — | — | — | — | — | Lanes + routed edges | Same | **Phases, groups, exception lanes, mainPath lint** |
+| Post-render artifact checker | — | — | — | — | — | — | — | — | **Yes** |
## Quick start
@@ -163,6 +165,14 @@ cd ~/.agents/skills/archify && npm install
Without the dependency the renderers skip schema validation (layout checks still run).
+For renderer-backed diagrams, the skill also runs a post-render artifact check:
+
+```bash
+node scripts/check-render-output.mjs output.html
+```
+
+That final gate inspects the generated HTML/SVG for malformed output, non-finite SVG values, accidental two-point diagonal arrows, and arrows crossing the legend.
+
**Claude.ai Projects (alternative):**
Upload [`archify.zip`](archify.zip) to your Project Knowledge.
@@ -323,6 +333,7 @@ Each color has coordinated dark-mode and light-mode variants that switch togethe
- **Styling:** CSS custom properties on `:root` + `[data-theme="light"]`; SVG elements reference semantic classes (`c-frontend`, `t-muted`, `a-emphasis`, etc.). Toggling `data-theme` on `<html>` re-themes the entire diagram including gradient, grid, arrows, and mask rects.
- **Export pipeline:** The SVG is cloned, host `<style>` is inlined, and current theme variables are resolved and written into a `:root` rule on the clone. For raster formats the clone's `width`/`height` are set to `4 × viewBox` so the browser rasterizes the vectors at target resolution natively; the canvas is sized to match and the image is drawn at natural size (no bitmap upsampling). `toBlob(mime)` then produces the file. JPEG gets an explicit background fill since it has no alpha. If the target resolution would exceed the browser's canvas limits, the pipeline automatically falls back to 3× or 2× so the export still succeeds.
- **Self-contained output:** Single HTML file, Google Fonts link + inline SVG + ~19 KB of embedded JS. No build step, no JS framework, no server — the generated HTML itself has zero dependencies (the typed renderers need `npm install` for ajv, see [Install](#1-install-the-skill)).
+- **Output checks:** `scripts/check-render-output.mjs` validates generated HTML before delivery: one SVG, finite SVG values, no accidental two-point diagonal arrows, and no arrow segments crossing the legend.
- **Browser support:** Any modern browser (Chrome, Safari, Firefox, Edge). Needs `Image` + `canvas.toBlob` with `image/webp` support for WebP export.
## Attribution
@@ -337,6 +348,8 @@ Archify 2.x contributes:
- Dual-theme self-contained SVG export (single file follows the host's `prefers-color-scheme`)
- Keyboard navigation + accessibility semantics
- Print stylesheet + local-font fallback
+- Renderer-backed architecture, workflow, sequence, data-flow, and lifecycle diagrams with schema validation
+- Post-render artifact checks for final HTML/SVG quality
- Updated `SKILL.md` to guide Claude toward class-based (themeable) diagrams
Both projects are MIT-licensed.
diff --git a/README_ZH.md b/README_ZH.md
index 201c0709..a52b0ecf 100644
--- a/README_ZH.md
+++ b/README_ZH.md
@@ -17,7 +17,7 @@ Archify 是一个可用于 Claude、Codex CLI 和 opencode 的 agent skill:你
![License](https://img.shields.io/badge/license-MIT-22c55e?style=flat-square)
![Agent Skill](https://img.shields.io/badge/Agent-Skill-7C3AED?style=flat-square)
-![Version](https://img.shields.io/badge/version-2.6.0-0891b2?style=flat-square)
+![Version](https://img.shields.io/badge/version-2.7.0-0891b2?style=flat-square)
**[在线落地页 → tt-a1i.github.io/archify](https://tt-a1i.github.io/archify/)**
@@ -99,21 +99,23 @@ Needs Approval,缺少输入时进入 Blocked;工具失败可以 Failed 后
## 版本演进
-Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0(只有深色主题的 HTML 输出)fork 重写。**2.0** 把模板重构成 CSS 变量驱动的可主题化系统,加入客户端导出流水线。**2.1** 加入剪贴板复制 + 键盘导航。**2.2** 加入打印样式 + 本地字体回退。**2.3** 修了一个存在已久的位图升采样 bug,所有光栅导出改为 4× 原生渲染(同时移除了 v2.1 引入的 1×/2×/4× 选择器 —— 那个选择器只是在诱导用户选出更糊的图)。**2.4** SVG 导出升级成双主题自持版 —— 同一个 `.svg` 文件贴在 GitHub README 里,读者切深浅色图会自己跟着切。**2.5** 集中修复类型化渲染器的 bug 并强化 LLM 工程学(校验错误信息带数值阈值和修复建议),SKILL.md 新增 Mermaid 输入指引,字体栈加入 CJK 回退,修复浅色导出泳道配色和 Safari 剪贴板复制,并补齐 golden 测试与 CI。
-
-| 能力 | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 |
-|---|---|---|---|---|---|---|---|
-| 深色主题 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
-| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + <kbd>T</kbd> 快捷键 | 同 | 同 |
-| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图放大 | 1×/2×/4× 选择器(仍是放大)| 同 | **4× 原生光栅化,不糊** | 同 | **浅色导出泳道配色修复** |
-| SVG 下载 | — | 矢量 + 内联样式(单主题)| 同 | 同 | 同 | **双主题自持**(`@media prefers-color-scheme`)| 同(泳道配色修复)|
-| 复制 PNG 到剪贴板 | — | — | ✓ | 同 | 同(最高 4×)| 同 | **Safari 修复** |
-| 键盘快捷键 | — | — | <kbd>T</kbd>/<kbd>E</kbd> + 菜单导航 | 同 | 同 | 同 | 同 |
-| 可访问性 | — | — | ARIA + focus-visible | 同 | 同 | 同 | 同(+ 菜单 a11y 修复)|
-| 打印样式表 | — | — | — | ✓ | ✓(+ 横向 + 2 列卡片)| 同 | 同 |
-| 导出时本地字体回退 | — | — | — | ✓ | ✓ | 同 | **+ CJK 字体回退** |
-| 样式模型 | 内联 `fill` / `stroke` | CSS 变量 + 语义 class | 同 | 同 | 同 | 同 | 同 |
-| 类型化渲染器 + schema 校验 | — | — | — | — | — | — | **✓(含测试与 CI)** |
+Archify 基于 [Cocoon-AI/architecture-diagram-generator](https://github.com/Cocoon-AI/architecture-diagram-generator) v1.0(只有深色主题的 HTML 输出)fork 重写。**2.0** 把模板重构成 CSS 变量驱动的可主题化系统,加入客户端导出流水线。**2.1** 加入剪贴板复制 + 键盘导航。**2.2** 加入打印样式 + 本地字体回退。**2.3** 修了位图升采样 bug,所有光栅导出改为最高 4× 原生渲染。**2.4** SVG 导出升级成双主题自持版。**2.5** 加入 workflow / sequence / data-flow / lifecycle 四种渲染器、Mermaid 输入指引、CJK-aware 文本测量、golden 测试和 CI。**2.6** 把 architecture 模式也升级到 schema + layout 校验。**2.7** 强化 workflow:phase header、group、exception lane、mainPath 主路径 lint、同泳道正交连线,以及生成后 HTML/SVG 检查器,交付前自动抓出斜线和图例穿插问题。
+
+| 能力 | v1.0 | 2.0 | 2.1 | 2.2 | 2.3 | 2.4 | 2.5 | 2.6 | 2.7 |
+|---|---|---|---|---|---|---|---|---|---|
+| 深色主题 | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ | ✓ |
+| 浅色主题 | — | 切换 | 切换 | 切换 | 切换 + <kbd>T</kbd> 快捷键 | 同 | 同 | 同 | 同 |
+| PNG / JPEG / WebP 下载 | 手动截图 | 2× 位图放大 | 1×/2×/4× 选择器(仍是放大)| 同 | **4× 原生光栅化,不糊** | 同 | **浅色导出泳道配色修复** | 同 | 同 |
+| SVG 下载 | — | 矢量 + 内联样式(单主题)| 同 | 同 | 同 | **双主题自持**(`@media prefers-color-scheme`)| 同(泳道配色修复)| 同 | 同 |
+| 复制 PNG 到剪贴板 | — | — | ✓ | 同 | 同(最高 4×)| 同 | **Safari 修复** | 同 | 同 |
+| 键盘快捷键 | — | — | <kbd>T</kbd>/<kbd>E</kbd> + 菜单导航 | 同 | 同 | 同 | 同 | 同 | 同 |
+| 可访问性 | — | — | ARIA + focus-visible | 同 | 同 | 同 | 同(+ 菜单 a11y 修复)| 同 | 同 |
+| 打印样式表 | — | — | — | ✓ | ✓(+ 横向 + 2 列卡片)| 同 | 同 | 同 | 同 |
+| 导出时本地字体回退 | — | — | — | ✓ | ✓ | 同 | **+ CJK 字体回退** | 同 | 同 |
+| 样式模型 | 内联 `fill` / `stroke` | CSS 变量 + 语义 class | 同 | 同 | 同 | 同 | 同 | 同 | 同 |
+| 类型化渲染器 + schema 校验 | — | — | — | — | — | — | workflow / sequence / data-flow / lifecycle | **+ architecture** | 同 |
+| Workflow 结构辅助 | — | — | — | — | — | — | 泳道 + 路由连线 | 同 | **phase、group、exception lane、mainPath lint** |
+| 生成后 artifact 检查 | — | — | — | — | — | — | — | — | **✓** |
## 快速上手
@@ -167,6 +169,14 @@ cd ~/.agents/skills/archify && npm install
没装依赖时渲染器会跳过 schema 校验(布局检查仍然运行)。
+对渲染器生成的图,skill 还会跑一次生成后检查:
+
+```bash
+node scripts/check-render-output.mjs output.html
+```
+
+这道最终闸门会检查 HTML/SVG 是否结构异常、SVG 是否出现非有限值、是否误生成两点斜线箭头,以及箭头是否穿过图例。
+
**Claude.ai Projects:**
把 [`archify.zip`](archify.zip) 上传到 Project Knowledge 就行。
@@ -228,9 +238,9 @@ cd ~/.agents/skills/archify && npm install
| **Download PNG / JPEG / WebP** | 保存为光栅图。JPEG / WebP 会用当前主题的背景色填充(无透明);PNG 保留透明度 |
| **Download SVG** | 矢量导出,所有样式内联,**双主题自持**。内嵌了 dark + light 两套 CSS 变量 + `@media (prefers-color-scheme)` 规则 —— 同一个 `.svg` 贴到 GitHub README / 博客,读者切深浅色图自己跟着切。可以在 Figma / Illustrator 里继续编辑。无损缩放 |
-所有光栅导出(复制 + PNG/JPEG/WebP)都由浏览器在**最高 4× 源分辨率**下原生光栅化 —— 序列化后的 SVG 被设为 `4 × viewBox` 大小,浏览器直接在该分辨率下光栅化矢量,canvas 按自然大小绘制(没有位图升采样)。结果是视网膜屏、演示幻灯、打印输出都真正清晰。
+所有光栅导出(复制 + PNG/JPEG/WebP)都由浏览器在**最高 4× 源分辨率**下原生光栅化;超大图会自动降到 3× / 2× 以避开浏览器 canvas 上限。序列化后的 SVG 被设为 `4 × viewBox` 大小,浏览器直接在该分辨率下光栅化矢量,canvas 按自然大小绘制(没有位图升采样)。结果是视网膜屏、演示幻灯、打印输出都真正清晰。
-没有倍数选择器 —— 永远最高清晰度,默认也是唯一选项。如果偶尔需要小图,用下面的 URL 参数。
+没有倍数选择器 —— 永远选择当前浏览器能稳定生成的最高清晰度。
### 键盘快捷键
@@ -328,6 +338,7 @@ cd ~/.agents/skills/archify && npm install
- **样式模型**:`:root` + `[data-theme="light"]` 上的 CSS 变量;SVG 元素引用语义 class(`c-frontend`、`t-muted`、`a-emphasis` 等)。切换 `<html>` 上的 `data-theme` 会重写包括渐变、网格、箭头、遮罩在内的整张图。
- **导出流水线**:克隆 SVG,内联 host `<style>`,解析当前主题变量并写入 clone 的 `:root` 规则,然后用 `XMLSerializer` 序列化。光栅格式下,clone 的 `width`/`height` 被设为 `4 × viewBox`,浏览器按目标分辨率原生光栅化矢量;canvas 尺寸对齐 clone 后按自然大小绘制(无位图升采样),`toBlob(mime)` 生成文件。JPEG 会显式补背景色(无 alpha)。如果目标分辨率超过浏览器 canvas 上限,自动降到 3× 或 2×。
- **单文件**:一个 HTML,一个 Google Fonts `<link>`,内联 SVG,约 19 KB 嵌入 JS。生成的 HTML 零运行时依赖 —— 无构建步骤、无 JS 框架、无服务端(渲染器本身需要 `npm install`,见安装章节)。
+- **生成后检查**:`scripts/check-render-output.mjs` 在交付前检查生成的 HTML:单 SVG、SVG 坐标有限、没有误生成两点斜线箭头、箭头线段不穿过图例。
- **浏览器支持**:任何主流浏览器(Chrome、Safari、Firefox、Edge)。WebP 导出需要 canvas 支持 `image/webp`。
## 致谢
@@ -343,6 +354,8 @@ Archify 2.x 贡献:
- SVG 导出双主题自持(单文件跟随宿主 `prefers-color-scheme`)
- 键盘导航 + 可访问性语义
- 打印样式表 + 本地字体回退
+- Architecture、workflow、sequence、data-flow、lifecycle 五类渲染器 + schema 校验
+- 生成后 artifact 检查,约束最终 HTML/SVG 质量
- 更新后的 `SKILL.md` 引导 Claude 使用 class 化、可主题化的画图方式
两个项目都是 MIT 协议。
diff --git a/archify.zip b/archify.zip
index 12600d87..b1dbc891 100644
Binary files a/archify.zip and b/archify.zip differ
diff --git a/archify/SKILL.md b/archify/SKILL.md
index cda06669..93401523 100644
--- a/archify/SKILL.md
+++ b/archify/SKILL.md
@@ -3,7 +3,7 @@ name: archify
description: Create professional architecture, workflow, sequence, data-flow, and lifecycle/state diagrams as standalone HTML files with SVG graphics, a built-in dark/light theme toggle, and one-click export to PNG / JPEG / WebP / SVG. Accepts plain-language descriptions or pasted Mermaid code (flowchart, sequenceDiagram, stateDiagram) and lays the diagram out from scratch in archify style. Use when the user asks for system architecture diagrams, infrastructure diagrams, cloud architecture visualizations, security diagrams, network topology, technical workflows, approval flows, runbooks, CI/CD flows, process diagrams, API call sequences, request lifecycles, data pipelines, ETL/ELT maps, PII boundaries, data lineage, state machines, lifecycle diagrams, status transitions, or asks to convert/beautify a Mermaid diagram.
license: MIT
metadata:
- version: "2.6"
+ version: "2.7"
author: tt-a1i
based_on: Cocoon-AI/architecture-diagram-generator (MIT, v1.0)
---
@@ -57,7 +57,8 @@ All four modes follow the same loop:
1. **Read first**: the schema (`schemas/<type>.schema.json`) and the complete worked example (`examples/*.{workflow,sequence,dataflow,lifecycle}.json`) — copy its patterns instead of guessing field shapes.
2. Write `<name>.<type>.json`.
3. Render: `node renderers/<type>/render-<type>.mjs <input>.json <output>.html` (paths relative to this skill's folder).
-4. If it fails, the error names the JSON path or the fix (thresholds, valid ranges, which knob to change). Fix the JSON and re-run; never edit the renderer.
+4. Check the generated artifact: `node scripts/check-render-output.mjs <output>.html`. This catches malformed SVG output, non-finite SVG values, two-point diagonal arrows, and arrows crossing the legend.
+5. If either step fails, the error names the JSON path or the fix (thresholds, valid ranges, which knob to change). Fix the JSON and re-run; never edit the renderer.
Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/label: "router") must NOT have additional properties`. The renderers additionally fail fast on layout problems: node/state overlap (including cross-lane), labels colliding with nodes or other labels, labels wider than their node, out-of-range columns/rows, too-short edges, and legends outside the viewBox. CJK text is measured at double width automatically.
@@ -68,7 +69,10 @@ Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/l
"schema_version": 1,
"diagram_type": "workflow",
"meta": { "title": "Release Workflow", "subtitle": "PR to production", "output": "release.html" },
- "lanes": [ { "id": "dev", "label": "Developer" }, { "id": "ci", "label": "CI" } ],
+ "lanes": [ { "id": "dev", "label": "Developer" }, { "id": "ci", "label": "CI" }, { "id": "exceptions", "label": "Exception Handling", "variant": "exception" } ],
+ "phases": [ { "id": "intake", "label": "Intake", "fromCol": 0, "toCol": 1 } ],
+ "groups": [ { "id": "checks", "label": "Parallel checks", "lane": "ci", "fromCol": 1, "toCol": 3, "variant": "emphasis" } ],
+ "mainPath": ["pr", "build"],
"nodes": [
{ "id": "pr", "lane": "dev", "col": 0, "type": "frontend", "label": "Open PR", "sublabel": "feature branch" },
{ "id": "build", "lane": "ci", "col": 1, "type": "backend", "label": "Build", "sublabel": "lint + test", "tag": "blocking" }
@@ -80,7 +84,7 @@ Schema violations exit non-zero with path-prefixed messages like `/nodes/3 (id/l
}
```
-**Layout budget**: 6 columns (`col` 0–5) at fixed x positions `[88, 220, 300, 430, 500, 625]` — columns 1↔2 and 3↔4 are only 70–80px apart, so default-width (92px) nodes in those adjacent columns of the same lane overlap; skip a column or shrink `width`. Lane content width is 640px. Omit `meta.viewBox` — the renderer sizes height to the lane count automatically. Edge routes: `straight`, `drop` (bend between lanes; `bias` 0–1 picks where), `outside-right`, `return-left`, `bottom-channel`, `up-channel`, or explicit `via` points. Keep adjacent-step edges unlabeled; reserve labels for cross-lane transitions, approvals, async writes, and returns.
+**Layout budget**: 6 columns (`col` 0–5) at fixed x positions `[88, 220, 300, 430, 500, 625]` — columns 1↔2 and 3↔4 are only 70–80px apart, so default-width (92px) nodes in those adjacent columns of the same lane overlap; skip a column or shrink `width`. Lane content width is 640px. Omit `meta.viewBox` — the renderer sizes height to the lane count automatically. Use `phases` for top-of-diagram story beats, `groups` to frame parallel work or a branch inside one lane, and `lane.variant: "exception"` for error/retry/fallback lanes. `mainPath` is optional but recommended: list the happy-path node ids in order so the renderer can catch missing edges or accidental backward movement. Edge routes: `straight`, `drop` (bend between lanes; `bias` 0–1 picks where), `outside-right`, `return-left`, `bottom-channel`, `up-channel`, or explicit `via` points. Keep adjacent-step edges unlabeled; reserve labels for cross-lane transitions, approvals, async traces, and returns.
### Sequence
diff --git a/archify/assets/template.html b/archify/assets/template.html
index b400799c..5d6ce9a6 100644
--- a/archify/assets/template.html
+++ b/archify/assets/template.html
@@ -3,7 +3,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="archify 2.6.0">
+ <meta name="generator" content="archify 2.7.0">
<title>[PROJECT NAME] Architecture Diagram</title>
<script>
// Resolve the theme before first paint so light-preference users don't
diff --git a/archify/examples/agent-tool-call.workflow.json b/archify/examples/agent-tool-call.workflow.json
index 5b8e126f..cfe5b1c9 100644
--- a/archify/examples/agent-tool-call.workflow.json
+++ b/archify/examples/agent-tool-call.workflow.json
@@ -5,15 +5,27 @@
"title": "Agent Tool Call Workflow",
"subtitle": "Renderer-driven workflow prototype with lanes, anchored nodes, and orthogonal edges",
"output": "examples/workflow-agent-tool-call-rendered.html",
- "viewBox": [720, 780]
+ "viewBox": [720, 900]
},
"lanes": [
{ "id": "ui", "label": "User Interface" },
{ "id": "agent", "label": "Agent Runtime" },
{ "id": "policy", "label": "Policy Boundary" },
+ { "id": "exceptions", "label": "Exception Handling", "variant": "exception" },
{ "id": "tools", "label": "Tool Execution" },
{ "id": "trace", "label": "Observability" }
],
+ "phases": [
+ { "id": "intake", "label": "Intake", "fromCol": 0, "toCol": 1 },
+ { "id": "reasoning", "label": "Plan + route", "fromCol": 2, "toCol": 3, "variant": "emphasis" },
+ { "id": "execution", "label": "Execute + report", "fromCol": 4, "toCol": 5, "variant": "dashed" }
+ ],
+ "groups": [
+ { "id": "agent_loop", "label": "Planning loop", "lane": "agent", "fromCol": 2, "toCol": 3, "variant": "emphasis" },
+ { "id": "tool_work", "label": "Tool work", "lane": "tools", "fromCol": 4, "toCol": 5, "variant": "dashed" },
+ { "id": "exception_path", "label": "Human or policy stop", "lane": "exceptions", "fromCol": 3, "toCol": 5, "variant": "security" }
+ ],
+ "mainPath": ["user", "chat", "planner", "router", "approval", "tool", "external", "final"],
"nodes": [
{ "id": "user", "lane": "ui", "col": 0, "type": "external", "label": "User", "sublabel": "asks for work" },
{ "id": "chat", "lane": "ui", "col": 1, "type": "frontend", "label": "Chat Surface", "sublabel": "thread + files" },
@@ -21,6 +33,8 @@
{ "id": "planner", "lane": "agent", "col": 2, "type": "backend", "label": "Agent Planner", "sublabel": "plan next step", "tag": "context aware" },
{ "id": "router", "lane": "agent", "col": 3, "type": "backend", "label": "Tool Router", "sublabel": "choose capability" },
{ "id": "approval", "lane": "policy", "col": 3, "type": "security", "label": "Approval Gate", "sublabel": "scope + consent", "tag": "block risky ops" },
+ { "id": "blocked", "lane": "exceptions", "col": 4, "type": "security", "label": "Blocked", "sublabel": "wait or reject" },
+ { "id": "retry", "lane": "exceptions", "col": 5, "type": "messagebus", "label": "Retry Path", "sublabel": "revise request" },
{ "id": "tool", "lane": "tools", "col": 4, "type": "messagebus", "label": "Tool Call", "sublabel": "shell / browser / MCP", "tag": "structured result" },
{ "id": "external", "lane": "tools", "col": 5, "type": "cloud", "label": "External API", "sublabel": "network service" },
{ "id": "store", "lane": "trace", "col": 1, "type": "database", "label": "Context Store", "sublabel": "repo + memory" },
@@ -31,12 +45,13 @@
{ "from": "chat", "to": "planner", "label": "plan", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 1 },
{ "from": "planner", "to": "router", "variant": "default" },
{ "from": "router", "to": "approval", "label": "needs approval?", "variant": "security", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 0, "labelDx": 34, "labelDy": 18 },
- { "from": "approval", "to": "tool", "label": "approved", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 1, "labelDy": 14 },
+ { "from": "approval", "to": "tool", "variant": "emphasis", "fromSide": "bottom", "toSide": "top", "route": "drop" },
+ { "from": "approval", "to": "blocked", "label": "denied", "variant": "security", "role": "error", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 1, "labelDy": 12 },
+ { "from": "blocked", "to": "retry", "variant": "dashed", "role": "branch" },
{ "from": "tool", "to": "external", "variant": "default" },
+ { "from": "external", "to": "final", "variant": "emphasis", "role": "return", "fromSide": "right", "toSide": "right", "route": "outside-right", "width": 1.2 },
{ "from": "external", "to": "trace", "label": "record result", "variant": "dashed", "fromSide": "bottom", "toSide": "bottom", "route": "bottom-channel", "labelSegment": 1 },
- { "from": "trace", "to": "final", "label": "summarize outcome", "variant": "emphasis", "fromSide": "right", "toSide": "right", "route": "outside-right", "labelSegment": 1, "labelDx": -22 },
- { "from": "planner", "to": "store", "label": "load context", "variant": "dashed", "fromSide": "bottom", "toSide": "top", "route": "drop", "labelSegment": 1 },
- { "from": "store", "to": "trace", "label": "write trace + memory", "variant": "dashed", "labelAt": [380, 622] }
+ { "from": "store", "to": "trace", "label": "trace + memory", "variant": "dashed", "labelAt": [365, 735] }
],
"cards": [
{
diff --git a/archify/package-lock.json b/archify/package-lock.json
index 618a8f2c..60c95685 100644
--- a/archify/package-lock.json
+++ b/archify/package-lock.json
@@ -1,12 +1,12 @@
{
"name": "archify",
- "version": "2.6.0",
+ "version": "2.7.0",
"lockfileVersion": 3,
"requires": true,
"packages": {
"": {
"name": "archify",
- "version": "2.6.0",
+ "version": "2.7.0",
"license": "MIT",
"dependencies": {
"ajv": "^8.17.1"
diff --git a/archify/package.json b/archify/package.json
index f025a5df..08cea885 100644
--- a/archify/package.json
+++ b/archify/package.json
@@ -1,9 +1,9 @@
{
"name": "archify",
- "version": "2.6.0",
+ "version": "2.7.0",
"private": true,
"type": "module",
- "description": "JSON-IR diagram renderers (workflow / sequence / dataflow / lifecycle).",
+ "description": "JSON-IR diagram renderers (architecture / workflow / sequence / dataflow / lifecycle).",
"license": "MIT",
"engines": {
"node": ">=18"
diff --git a/archify/renderers/workflow/README.md b/archify/renderers/workflow/README.md
index e6d1df51..e4125ce4 100644
--- a/archify/renderers/workflow/README.md
+++ b/archify/renderers/workflow/README.md
@@ -15,6 +15,16 @@ still run.
If `output.html` is omitted, the renderer uses `meta.output` from the JSON file
or falls back to `workflow.html` in the current working directory.
+After rendering, run the artifact checker:
+
+```bash
+node archify/scripts/check-render-output.mjs output.html
+```
+
+It catches final-SVG issues that are easiest to see in a browser: non-finite
+SVG values, accidental two-point diagonal arrows, and arrows crossing the
+legend.
+
## Input
Workflow JSON files must set:
@@ -28,6 +38,9 @@ Workflow JSON files must set:
"subtitle": "Renderer-driven workflow prototype"
},
"lanes": [],
+ "phases": [],
+ "groups": [],
+ "mainPath": [],
"nodes": [],
"edges": [],
"cards": []
@@ -53,6 +66,10 @@ archify/schemas/workflow.schema.json
| Lane frame | x 40, width 640, height 104, gap 20; first lane top at y 52 |
| Lane title strip | top 30px of each lane; node boxes must stay below it |
| Column centers (`col` 0–5) | x = 88, 220, 300, 430, 500, 625 |
+| Phase headers | Optional `phases[]` render above the first lane, spanning `fromCol..toCol` |
+| Lane groups | Optional `groups[]` frame parallel work or branch work inside one lane |
+| Exception lanes | Set `lane.variant: "exception"` for retry, denial, fallback, or failure paths |
+| Main path lint | Optional `mainPath[]` checks that happy-path steps have matching edges and do not move backward |
| Default node | 92×52 (height 68 when `tag` is set) |
| Node spacing | ≥8px between nodes in the same lane |
| Edge length | straight segments must span ≥28px |
@@ -65,6 +82,10 @@ column or reduce `width`.
## Design Rules
- Use lanes for ownership or runtime boundaries.
+- Use phase headers for high-level story beats such as Intake, Plan, Execute, and Report.
+- Use groups for parallel checks, branch handling, or bounded work within a lane; every group must contain at least one node.
+- Use `lane.variant: "exception"` for human wait, denial, retry, fallback, and failure lanes instead of mixing those paths into the happy path.
+- Set `mainPath` when the diagram has a clear happy path; the renderer validates that consecutive ids have matching edges and move left-to-right.
- Place nodes with lane IDs and column indexes, not raw SVG coordinates.
- Leave short adjacent links unlabeled; the arrow is enough.
- Use labels for cross-lane decisions, approvals, async traces, and return paths.
@@ -76,8 +97,9 @@ column or reduce `width`.
Schema violations exit non-zero with path-prefixed messages annotated with the
element's id or label. The renderer additionally fails when it can detect
-layout problems, including node overlap, nodes outside their lanes, unknown
-edge targets, labels colliding with nodes or other labels, labels wider than
-their node, legends outside the viewBox, or straight arrows that are too short
-to read cleanly. Text width is estimated CJK-aware: fullwidth glyphs count as
-two units.
+layout problems, including node overlap, nodes outside their lanes, invalid
+phase/group column ranges, empty groups, broken `mainPath` steps, unknown edge
+targets, labels colliding with nodes or other labels, labels wider than their
+node, legends outside the viewBox, or straight arrows that are too short to
+read cleanly. Text width is estimated CJK-aware: fullwidth glyphs count as two
+units.
diff --git a/archify/renderers/workflow/render-workflow.mjs b/archify/renderers/workflow/render-workflow.mjs
index b37dfd44..f4094a8b 100644
--- a/archify/renderers/workflow/render-workflow.mjs
+++ b/archify/renderers/workflow/render-workflow.mjs
@@ -97,6 +97,15 @@ function validateWorkflow() {
if (!Array.isArray(workflow.edges)) {
problems.push('Workflow files must include an edges array.');
}
+ if (workflow.phases !== undefined && !Array.isArray(workflow.phases)) {
+ problems.push('Workflow "phases" must be an array.');
+ }
+ if (workflow.groups !== undefined && !Array.isArray(workflow.groups)) {
+ problems.push('Workflow "groups" must be an array.');
+ }
+ if (workflow.mainPath !== undefined && !Array.isArray(workflow.mainPath)) {
+ problems.push('Workflow "mainPath" must be an array of node ids.');
+ }
if (workflow.cards !== undefined && !Array.isArray(workflow.cards)) {
problems.push('Workflow "cards" must be an array.');
}
@@ -111,6 +120,14 @@ function validateWorkflow() {
if (nodes.size !== workflow.nodes.length) {
problems.push('Node ids must be unique.');
}
+ const phaseIds = new Set(asArray(workflow.phases).map((phase) => phase.id));
+ if (phaseIds.size !== asArray(workflow.phases).length) {
+ problems.push('Phase ids must be unique.');
+ }
+ const groupIds = new Set(asArray(workflow.groups).map((group) => group.id));
+ if (groupIds.size !== asArray(workflow.groups).length) {
+ problems.push('Group ids must be unique.');
+ }
for (const node of nodes.values()) {
if (!laneIds.has(node.lane)) {
@@ -141,6 +158,39 @@ function validateWorkflow() {
}
}
+ for (const phase of asArray(workflow.phases)) {
+ if (!Number.isInteger(phase.fromCol) || !Number.isInteger(phase.toCol)) {
+ problems.push(`Phase "${phase.id}" must use integer fromCol/toCol values.`);
+ continue;
+ }
+ if (phase.fromCol < 0 || phase.toCol >= layout.colXs.length || phase.fromCol > phase.toCol) {
+ problems.push(`Phase "${phase.id}" uses invalid columns ${phase.fromCol}..${phase.toCol}; use an ordered range within 0..${layout.colXs.length - 1}.`);
+ }
+ const estLabelW = textUnits(phase.label) * 5.6;
+ const width = spanForCols(phase.fromCol, phase.toCol).width;
+ if (estLabelW > width + 8) {
+ problems.push(`Phase label "${phase.label}" (~${Math.round(estLabelW)}px) is wider than its ${Math.round(width)}px span — shorten the label or widen the phase range.`);
+ }
+ }
+
+ for (const group of asArray(workflow.groups)) {
+ if (!laneIds.has(group.lane)) {
+ problems.push(`Group "${group.id}" uses unknown lane "${group.lane}".`);
+ continue;
+ }
+ if (!Number.isInteger(group.fromCol) || !Number.isInteger(group.toCol)) {
+ problems.push(`Group "${group.id}" must use integer fromCol/toCol values.`);
+ continue;
+ }
+ if (group.fromCol < 0 || group.toCol >= layout.colXs.length || group.fromCol > group.toCol) {
+ problems.push(`Group "${group.id}" uses invalid columns ${group.fromCol}..${group.toCol}; use an ordered range within 0..${layout.colXs.length - 1}.`);
+ }
+ const contained = [...nodes.values()].some((node) => node.lane === group.lane && node.col >= group.fromCol && node.col <= group.toCol);
+ if (!contained) {
+ problems.push(`Group "${group.id}" does not contain any nodes — align its lane/columns with the parallel or branch work it frames.`);
+ }
+ }
+
const byLane = new Map();
for (const node of nodes.values()) {
byLane.set(node.lane, [...(byLane.get(node.lane) || []), node]);
@@ -170,6 +220,28 @@ function validateWorkflow() {
}
}
+ if (Array.isArray(workflow.mainPath)) {
+ for (const id of workflow.mainPath) {
+ if (!nodes.has(id)) {
+ problems.push(`mainPath references unknown node "${id}".`);
+ }
+ }
+ for (let i = 0; i < workflow.mainPath.length - 1; i += 1) {
+ const fromId = workflow.mainPath[i];
+ const toId = workflow.mainPath[i + 1];
+ const from = nodes.get(fromId);
+ const to = nodes.get(toId);
+ if (!from || !to) continue;
+ const linked = workflow.edges.some((edge) => edge.from === fromId && edge.to === toId);
+ if (!linked) {
+ problems.push(`mainPath step "${fromId}" -> "${toId}" has no matching edge — add the edge or remove the pair from mainPath.`);
+ }
+ if (to.col < from.col) {
+ problems.push(`mainPath step "${fromId}" -> "${toId}" moves backward from col ${from.col} to ${to.col} — use a return edge outside mainPath for loops.`);
+ }
+ }
+ }
+
const labelRects = [];
for (const edge of workflow.edges) {
if (!edge.label || !nodes.has(edge.from) || !nodes.has(edge.to)) continue;
@@ -210,6 +282,18 @@ function gapYBetween(fromLane, toLane, bias = 0.5) {
return a + (b - a) * bias;
}
+function spanForCols(fromCol, toCol, pad = 46) {
+ const start = layout.colXs[fromCol] - pad;
+ const end = layout.colXs[toCol] + pad;
+ return { x: start, width: end - start, cx: (start + end) / 2 };
+}
+
+function sameLaneAutoVia(start, end) {
+ if (start[0] === end[0] || start[1] === end[1]) return [];
+ const midX = (start[0] + end[0]) / 2;
+ return [[midX, start[1]], [midX, end[1]]];
+}
+
function routeVia(edge, from, to, start, end) {
if (edge.via) return edge.via;
switch (edge.route || 'auto') {
@@ -237,7 +321,7 @@ function routeVia(edge, from, to, start, end) {
}
case 'auto':
default: {
- if (from.lane === to.lane) return [];
+ if (from.lane === to.lane) return sameLaneAutoVia(start, end);
const y = gapYBetween(from.lane, to.lane, edge.bias ?? 0.5);
return [[start[0], y], [end[0], y]];
}
@@ -260,8 +344,32 @@ function pathFor(edge) {
function renderLane(lane, index) {
const y = layout.laneY + index * (layout.laneH + layout.laneGap);
- return ` <rect x="${layout.laneX}" y="${y}" width="${layout.laneW}" height="${layout.laneH}" rx="10" class="c-lane" stroke-width="1"/>
- <text x="${layout.laneX + 14}" y="${y + 22}" class="t-dim" font-size="10" font-weight="600">${String(index + 1).padStart(2, '0')} / ${esc(lane.label)}</text>`;
+ const exception = lane.variant === 'exception'
+ ? `\n <rect x="${layout.laneX + 6}" y="${y + 6}" width="${layout.laneW - 12}" height="${layout.laneH - 12}" rx="8" class="c-security-group" stroke-width="1"/>`
+ : '';
+ const labelClass = lane.variant === 'exception' ? 't-security' : 't-dim';
+ const prefix = lane.variant === 'exception' ? 'EX' : String(index + 1).padStart(2, '0');
+ return ` <rect x="${layout.laneX}" y="${y}" width="${layout.laneW}" height="${layout.laneH}" rx="10" class="c-lane" stroke-width="1"/>${exception}
+ <text x="${layout.laneX + 14}" y="${y + 22}" class="${labelClass}" font-size="10" font-weight="600">${prefix} / ${esc(lane.label)}</text>`;
+}
+
+function renderPhase(phase) {
+ const span = spanForCols(phase.fromCol, phase.toCol, 46);
+ const accent = variantAccent(phase.variant);
+ const [lineClass] = arrowClassMap[phase.variant || 'default'] || arrowClassMap.default;
+ return ` <line x1="${span.x}" y1="35" x2="${span.x + span.width}" y2="35" class="${lineClass}" stroke-width="1.1"/>
+ <rect x="${span.x}" y="27" width="${span.width}" height="16" rx="4" class="c-mask"/>
+ <text x="${span.cx}" y="39" class="${accent}" font-size="8" font-weight="600" text-anchor="middle">${esc(phase.label)}</text>`;
+}
+
+function renderGroup(group) {
+ const span = spanForCols(group.fromCol, group.toCol, 50);
+ const y = laneTop(group.lane) + layout.laneTitleH + 8;
+ const height = layout.laneH - layout.laneTitleH - 16;
+ const cls = group.variant === 'security' ? 'c-security-group' : 'c-lane';
+ const textClass = variantAccent(group.variant);
+ return ` <rect x="${span.x}" y="${y}" width="${span.width}" height="${height}" rx="9" class="${cls}" stroke-width="1"/>
+ <text x="${span.x + 10}" y="${y + 14}" class="${textClass}" font-size="7" font-weight="600">${esc(group.label)}</text>`;
}
function renderNode(node) {
@@ -317,6 +425,12 @@ ${renderDefinitions()}
<!-- Swimlanes -->
${workflow.lanes.map(renderLane).join('\n\n')}
+ <!-- Phase headers -->
+${asArray(workflow.phases).map(renderPhase).join('\n')}
+
+ <!-- Workflow groups -->
+${asArray(workflow.groups).map(renderGroup).join('\n')}
+
<!-- Edge paths -->
${workflow.edges.map(renderEdgePath).join('\n')}
diff --git a/archify/schemas/README.md b/archify/schemas/README.md
index 166529f6..88f8ddf8 100644
--- a/archify/schemas/README.md
+++ b/archify/schemas/README.md
@@ -7,7 +7,7 @@ against one of the schemas in this folder before any layout work happens.
| Schema | Governs | Structural arrays |
|--------|---------|-------------------|
-| `workflow.schema.json` | `diagram_type: "workflow"` | `lanes`, `nodes`, `edges` |
+| `workflow.schema.json` | `diagram_type: "workflow"` | `lanes`, `phases`, `groups`, `mainPath`, `nodes`, `edges` |
| `sequence.schema.json` | `diagram_type: "sequence"` | `participants`, `segments`, `messages`, `activations` |
| `dataflow.schema.json` | `diagram_type: "dataflow"` | `stages`, `nodes`, `flows` |
| `lifecycle.schema.json` | `diagram_type: "lifecycle"` | `lanes`, `states`, `transitions` |
diff --git a/archify/schemas/workflow.schema.json b/archify/schemas/workflow.schema.json
index 8eda3c91..1ea46ceb 100644
--- a/archify/schemas/workflow.schema.json
+++ b/archify/schemas/workflow.schema.json
@@ -71,10 +71,107 @@
"label": {
"type": "string",
"minLength": 1
+ },
+ "variant": {
+ "enum": [
+ "normal",
+ "exception"
+ ]
+ }
+ }
+ }
+ },
+ "phases": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "id",
+ "label",
+ "fromCol",
+ "toCol"
+ ],
+ "properties": {
+ "id": {
+ "$ref": "common.schema.json#/$defs/id"
+ },
+ "label": {
+ "type": "string",
+ "minLength": 1
+ },
+ "fromCol": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 5
+ },
+ "toCol": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 5
+ },
+ "variant": {
+ "enum": [
+ "default",
+ "emphasis",
+ "security",
+ "dashed"
+ ]
}
}
}
},
+ "groups": {
+ "type": "array",
+ "items": {
+ "type": "object",
+ "additionalProperties": false,
+ "required": [
+ "id",
+ "label",
+ "lane",
+ "fromCol",
+ "toCol"
+ ],
+ "properties": {
+ "id": {
+ "$ref": "common.schema.json#/$defs/id"
+ },
+ "label": {
+ "type": "string",
+ "minLength": 1
+ },
+ "lane": {
+ "$ref": "common.schema.json#/$defs/id"
+ },
+ "fromCol": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 5
+ },
+ "toCol": {
+ "type": "integer",
+ "minimum": 0,
+ "maximum": 5
+ },
+ "variant": {
+ "enum": [
+ "default",
+ "emphasis",
+ "security",
+ "dashed"
+ ]
+ }
+ }
+ }
+ },
+ "mainPath": {
+ "type": "array",
+ "minItems": 2,
+ "items": {
+ "$ref": "common.schema.json#/$defs/id"
+ }
+ },
"nodes": {
"type": "array",
"minItems": 1,
@@ -149,6 +246,15 @@
"variant": {
"$ref": "common.schema.json#/$defs/variant"
},
+ "role": {
+ "enum": [
+ "main",
+ "branch",
+ "async",
+ "return",
+ "error"
+ ]
+ },
"fromSide": {
"$ref": "#/$defs/side"
},
diff --git a/archify/scripts/check-render-output.mjs b/archify/scripts/check-render-output.mjs
new file mode 100644
index 00000000..2e110377
--- /dev/null
+++ b/archify/scripts/check-render-output.mjs
@@ -0,0 +1,296 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import path from 'node:path';
+
+const input = process.argv[2];
+
+if (!input || input === '-h' || input === '--help') {
+ console.error('Usage: node scripts/check-render-output.mjs <diagram.html>');
+ process.exit(input ? 0 : 2);
+}
+
+const htmlPath = path.resolve(input);
+let html;
+try {
+ html = fs.readFileSync(htmlPath, 'utf8');
+} catch (err) {
+ console.error(JSON.stringify({
+ ok: false,
+ file: htmlPath,
+ checks: [{ name: 'file_readable', ok: false, details: [err.message] }],
+ }, null, 2));
+ process.exit(1);
+}
+
+const checks = [];
+
+function addCheck(name, ok, details = []) {
+ checks.push({ name, ok, details });
+}
+
+const svgMatches = [...html.matchAll(/<svg\b[\s\S]*?<\/svg>/gi)];
+addCheck('single_svg', svgMatches.length === 1, [`found ${svgMatches.length} <svg> block(s)`]);
+
+if (svgMatches.length === 1) {
+ const svg = svgMatches[0][0];
+ addCheck('finite_svg', !/\b(?:NaN|undefined|Infinity|-Infinity)\b/.test(svg));
+ const legendStart = svg.indexOf('<!-- Legend -->');
+ const beforeLegend = legendStart >= 0 ? svg.slice(0, legendStart) : svg;
+ const arrows = collectArrows(beforeLegend);
+ const diagonal = arrows.filter((arrow) => isTwoPointDiagonal(arrow));
+ addCheck(
+ 'orthogonal_arrows',
+ diagonal.length === 0,
+ diagonal.map((arrow) => `${arrow.kind} ${arrow.index}: ${arrow.raw}`),
+ );
+
+ if (legendStart >= 0) {
+ const legendFragment = svg.slice(legendStart);
+ const legendBoxes = collectLegendBoxes(legendFragment);
+ const collisions = collectLegendCollisions(arrows, legendBoxes);
+ addCheck(
+ 'legend_clearance',
+ collisions.length === 0,
+ collisions.map((hit) => `${hit.arrow.kind} ${hit.arrow.index} crosses legend ${hit.box.label}`),
+ );
+ } else {
+ addCheck('legend_clearance', true, ['no legend marker found']);
+ }
+}
+
+const ok = checks.every((check) => check.ok);
+console.log(JSON.stringify({ ok, file: htmlPath, checks }, null, 2));
+process.exit(ok ? 0 : 1);
+
+function collectArrows(fragment) {
+ const arrows = [];
+ let index = 0;
+
+ for (const tag of fragment.matchAll(/<(path|line)\b[^>]*>/gi)) {
+ const raw = tag[0];
+ if (!/\bclass="[^"]*\ba-(?:default|emphasis|security|dashed)\b/.test(raw)) continue;
+ const attrs = parseAttrs(raw);
+ const segments = tag[1].toLowerCase() === 'line'
+ ? lineSegments(attrs)
+ : pathSegments(attrs.d || '');
+ arrows.push({ kind: tag[1].toLowerCase(), index: index += 1, raw, segments });
+ }
+
+ return arrows;
+}
+
+function lineSegments(attrs) {
+ const start = [numberAttr(attrs, 'x1'), numberAttr(attrs, 'y1')];
+ const end = [numberAttr(attrs, 'x2'), numberAttr(attrs, 'y2')];
+ if (!isPoint(start) || !isPoint(end)) return [];
+ return [{ start, end }];
+}
+
+function pathSegments(d) {
+ const points = pointsFromPath(d);
+ const segments = [];
+ for (let i = 1; i < points.length; i += 1) {
+ segments.push({ start: points[i - 1], end: points[i] });
+ }
+ return segments;
+}
+
+function isTwoPointDiagonal(arrow) {
+ if (arrow.segments.length !== 1) return false;
+ const { start, end } = arrow.segments[0];
+ return Math.abs(start[0] - end[0]) > 0.01 && Math.abs(start[1] - end[1]) > 0.01;
+}
+
+function collectLegendBoxes(fragment) {
+ const boxes = [];
+
+ for (const match of fragment.matchAll(/<rect\b[^>]*>/gi)) {
+ const attrs = parseAttrs(match[0]);
+ const x = numberAttr(attrs, 'x');
+ const y = numberAttr(attrs, 'y');
+ const width = numberAttr(attrs, 'width');
+ const height = numberAttr(attrs, 'height');
+ if ([x, y, width, height].every(Number.isFinite)) {
+ boxes.push({ x1: x, y1: y, x2: x + width, y2: y + height, label: `rect@${x},${y}` });
+ }
+ }
+
+ for (const match of fragment.matchAll(/<text\b([^>]*)>([\s\S]*?)<\/text>/gi)) {
+ const attrs = parseAttrs(match[1]);
+ const box = textBox(attrs, stripTags(match[2]).trim());
+ if (box) boxes.push(box);
+ }
+
+ return boxes;
+}
+
+function collectLegendCollisions(arrows, boxes) {
+ const collisions = [];
+ for (const arrow of arrows) {
+ for (const segment of arrow.segments) {
+ for (const box of boxes) {
+ if (segmentIntersectsBox(segment, padBox(box, 2))) {
+ collisions.push({ arrow, box });
+ }
+ }
+ }
+ }
+ return collisions;
+}
+
+function textBox(attrs, text) {
+ const x = numberAttr(attrs, 'x');
+ const y = numberAttr(attrs, 'y');
+ const fontSize = Number.parseFloat(attrs['font-size'] || '10');
+ if (!Number.isFinite(x) || !Number.isFinite(y) || !Number.isFinite(fontSize)) return null;
+ const width = estimatedTextWidth(text, fontSize);
+ const anchor = attrs['text-anchor'] || 'start';
+ let x1 = x;
+ if (anchor === 'middle') x1 = x - width / 2;
+ if (anchor === 'end') x1 = x - width;
+ return {
+ x1,
+ y1: y - fontSize,
+ x2: x1 + width,
+ y2: y + fontSize * 0.25,
+ label: text || `text@${x},${y}`,
+ };
+}
+
+function estimatedTextWidth(text, fontSize) {
+ let units = 0;
+ for (const char of text) units += char.charCodeAt(0) > 255 ? 1.8 : 0.62;
+ return Math.max(fontSize, units * fontSize);
+}
+
+function pointsFromPath(d) {
+ const tokens = d.match(/[MLHVZmlhvz]|[-+]?(?:\d*\.)?\d+(?:e[-+]?\d+)?/g) || [];
+ const points = [];
+ let i = 0;
+ let command = '';
+ let current = [0, 0];
+ let start = null;
+
+ while (i < tokens.length) {
+ if (isCommand(tokens[i])) command = tokens[i++];
+ if (!command) break;
+
+ const absolute = command === command.toUpperCase();
+ switch (command.toUpperCase()) {
+ case 'M':
+ case 'L': {
+ while (i + 1 < tokens.length && !isCommand(tokens[i])) {
+ const x = Number.parseFloat(tokens[i++]);
+ const y = Number.parseFloat(tokens[i++]);
+ if (!Number.isFinite(x) || !Number.isFinite(y)) break;
+ current = absolute ? [x, y] : [current[0] + x, current[1] + y];
+ points.push(current);
+ if (!start) start = current;
+ }
+ break;
+ }
+ case 'H': {
+ while (i < tokens.length && !isCommand(tokens[i])) {
+ const x = Number.parseFloat(tokens[i++]);
+ if (!Number.isFinite(x)) break;
+ current = absolute ? [x, current[1]] : [current[0] + x, current[1]];
+ points.push(current);
+ }
+ break;
+ }
+ case 'V': {
+ while (i < tokens.length && !isCommand(tokens[i])) {
+ const y = Number.parseFloat(tokens[i++]);
+ if (!Number.isFinite(y)) break;
+ current = absolute ? [current[0], y] : [current[0], current[1] + y];
+ points.push(current);
+ }
+ break;
+ }
+ case 'Z': {
+ if (start) points.push(start);
+ break;
+ }
+ default:
+ return [];
+ }
+ }
+
+ return points.filter(isPoint);
+}
+
+function segmentIntersectsBox(segment, box) {
+ const { start, end } = segment;
+ if (pointInsideBox(start, box) || pointInsideBox(end, box)) return true;
+ const edges = [
+ [[box.x1, box.y1], [box.x2, box.y1]],
+ [[box.x2, box.y1], [box.x2, box.y2]],
+ [[box.x2, box.y2], [box.x1, box.y2]],
+ [[box.x1, box.y2], [box.x1, box.y1]],
+ ];
+ return edges.some(([a, b]) => segmentsIntersect(start, end, a, b));
+}
+
+function segmentsIntersect(a, b, c, d) {
+ const o1 = orientation(a, b, c);
+ const o2 = orientation(a, b, d);
+ const o3 = orientation(c, d, a);
+ const o4 = orientation(c, d, b);
+
+ if (o1 !== o2 && o3 !== o4) return true;
+ if (o1 === 0 && onSegment(a, c, b)) return true;
+ if (o2 === 0 && onSegment(a, d, b)) return true;
+ if (o3 === 0 && onSegment(c, a, d)) return true;
+ if (o4 === 0 && onSegment(c, b, d)) return true;
+ return false;
+}
+
+function orientation(a, b, c) {
+ const value = (b[1] - a[1]) * (c[0] - b[0]) - (b[0] - a[0]) * (c[1] - b[1]);
+ if (Math.abs(value) < 1e-9) return 0;
+ return value > 0 ? 1 : 2;
+}
+
+function onSegment(a, b, c) {
+ return b[0] <= Math.max(a[0], c[0]) + 1e-9
+ && b[0] + 1e-9 >= Math.min(a[0], c[0])
+ && b[1] <= Math.max(a[1], c[1]) + 1e-9
+ && b[1] + 1e-9 >= Math.min(a[1], c[1]);
+}
+
+function pointInsideBox(point, box) {
+ return point[0] >= box.x1 && point[0] <= box.x2 && point[1] >= box.y1 && point[1] <= box.y2;
+}
+
+function padBox(box, padding) {
+ return {
+ ...box,
+ x1: box.x1 - padding,
+ y1: box.y1 - padding,
+ x2: box.x2 + padding,
+ y2: box.y2 + padding,
+ };
+}
+
+function parseAttrs(tag) {
+ const attrs = {};
+ for (const match of tag.matchAll(/([\w:-]+)\s*=\s*"([^"]*)"/g)) attrs[match[1]] = match[2];
+ return attrs;
+}
+
+function numberAttr(attrs, name) {
+ return Number.parseFloat(attrs[name]);
+}
+
+function isCommand(token) {
+ return /^[A-Za-z]$/.test(token);
+}
+
+function isPoint(point) {
+ return Array.isArray(point) && point.length === 2 && point.every(Number.isFinite);
+}
+
+function stripTags(value) {
+ return value.replace(/<[^>]*>/g, '');
+}
diff --git a/archify/test/degraded.test.mjs b/archify/test/degraded.test.mjs
index 6556ed68..f28341c0 100644
--- a/archify/test/degraded.test.mjs
+++ b/archify/test/degraded.test.mjs
@@ -71,7 +71,7 @@ function assertFriendlyFailure(mode, doc, label) {
// ---- type-wrong-but-JSON-legal documents per mode ----
const ARRAY_FIELDS = {
- workflow: ['lanes', 'nodes', 'edges', 'cards'],
+ workflow: ['lanes', 'phases', 'groups', 'mainPath', 'nodes', 'edges', 'cards'],
sequence: ['participants', 'messages', 'segments', 'activations', 'cards'],
dataflow: ['stages', 'nodes', 'flows', 'cards'],
lifecycle: ['lanes', 'states', 'transitions', 'cards'],
diff --git a/archify/test/layout-rules.test.mjs b/archify/test/layout-rules.test.mjs
index 4a1a13b9..3da22e63 100644
--- a/archify/test/layout-rules.test.mjs
+++ b/archify/test/layout-rules.test.mjs
@@ -37,16 +37,17 @@ function load(mode) {
// Returns { code, stderr }. Never throws on non-zero exit.
function render(mode, doc) {
const input = path.join(tmp, `${mode}-${Math.abs(hash(JSON.stringify(doc)))}.json`);
+ const outPath = path.join(tmp, `${mode}-${Math.abs(hash(JSON.stringify(doc)))}.html`);
fs.writeFileSync(input, JSON.stringify(doc));
try {
execFileSync('node', [
path.join(skillRoot, `renderers/${mode}/render-${mode}.mjs`),
input,
- path.join(tmp, 'out.html'),
+ outPath,
], { stdio: ['ignore', 'ignore', 'pipe'] });
- return { code: 0, stderr: '' };
+ return { code: 0, stderr: '', outPath };
} catch (err) {
- return { code: err.status ?? 1, stderr: String(err.stderr || '') };
+ return { code: err.status ?? 1, stderr: String(err.stderr || ''), outPath };
}
}
@@ -67,6 +68,12 @@ const CASES = [
(d) => { d.meta.viewBox = [699, 900]; }, ['700']],
['workflow: nodes too close in a lane', 'workflow',
(d) => { d.nodes.push({ ...d.nodes[0], id: 'dupe', col: d.nodes[0].col }); }, ['less than 8px apart']],
+ ['workflow: empty group', 'workflow',
+ (d) => { d.groups = [{ id: 'empty', label: 'Empty group', lane: 'ui', fromCol: 3, toCol: 4 }]; }, ['does not contain any nodes']],
+ ['workflow: mainPath missing edge', 'workflow',
+ (d) => { d.mainPath = ['user', 'planner']; }, ['mainPath step "user" -> "planner" has no matching edge']],
+ ['workflow: mainPath moves backward', 'workflow',
+ (d) => { d.mainPath = ['external', 'trace']; }, ['moves backward from col']],
// ---- sequence layout rules ----
['sequence: message references unknown participant', 'sequence',
@@ -143,4 +150,23 @@ test('contract: ajv path errors are annotated with the element id', () => {
assert.match(stderr, /id\/label:/);
});
+test('workflow: same-lane offset auto edge stays orthogonal', () => {
+ const d = {
+ schema_version: 1,
+ diagram_type: 'workflow',
+ meta: { title: 'Same-lane offset route' },
+ lanes: [{ id: 'main', label: 'Main lane' }],
+ nodes: [
+ { id: 'left', lane: 'main', col: 1, type: 'backend', label: 'A', width: 32, height: 38, yOffset: -14 },
+ { id: 'right', lane: 'main', col: 2, type: 'backend', label: 'B', width: 32, height: 38, yOffset: 14 },
+ ],
+ edges: [{ from: 'left', to: 'right' }],
+ };
+ const { code, stderr, outPath } = render('workflow', d);
+ assert.equal(code, 0, stderr);
+ const html = fs.readFileSync(outPath, 'utf8');
+ assert.doesNotMatch(html, /M 236 105 L 284 133/);
+ assert.match(html, /M 236 105 L 260 105 L 260 133 L 284 133/);
+});
+
process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));
diff --git a/archify/test/render-output-checks.test.mjs b/archify/test/render-output-checks.test.mjs
new file mode 100644
index 00000000..0d0c5967
--- /dev/null
+++ b/archify/test/render-output-checks.test.mjs
@@ -0,0 +1,63 @@
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const skillRoot = path.resolve(__dirname, '..');
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'archify-output-checks-'));
+const checker = path.join(skillRoot, 'scripts/check-render-output.mjs');
+
+function checkHtml(name, svgBody) {
+ const htmlPath = path.join(tmp, `${name}.html`);
+ fs.writeFileSync(htmlPath, `<!doctype html><html><body><svg viewBox="0 0 240 160">${svgBody}</svg></body></html>`);
+ try {
+ const stdout = execFileSync('node', [checker, htmlPath], { encoding: 'utf8' });
+ return { code: 0, result: JSON.parse(stdout) };
+ } catch (err) {
+ return { code: err.status ?? 1, result: JSON.parse(String(err.stdout || '{}')) };
+ }
+}
+
+test('render output check: accepts orthogonal arrows away from legend', () => {
+ const { code, result } = checkHtml('clean', `
+ <path d="M 20 20 L 120 20 L 120 60" class="a-default" stroke-width="1.4"/>
+ <!-- Legend -->
+ <text x="40" y="120" class="t-primary" font-size="10">Legend</text>
+ <rect x="40" y="132" width="14" height="9" class="c-backend"/>
+ <text x="60" y="140" class="t-muted" font-size="7">Backend</text>
+ `);
+ assert.equal(code, 0);
+ assert.equal(result.ok, true);
+});
+
+test('render output check: rejects two-point diagonal arrows', () => {
+ const { code, result } = checkHtml('diagonal', `
+ <path d="M 20 20 L 120 80" class="a-default" stroke-width="1.4"/>
+ <!-- Legend -->
+ <text x="40" y="120" class="t-primary" font-size="10">Legend</text>
+ `);
+ assert.notEqual(code, 0);
+ const check = result.checks.find((item) => item.name === 'orthogonal_arrows');
+ assert.equal(check.ok, false);
+ assert.match(check.details[0], /path 1/);
+});
+
+test('render output check: rejects arrows crossing legend text', () => {
+ const { code, result } = checkHtml('legend-crossing', `
+ <path d="M 20 112 L 180 112" class="a-dashed" stroke-width="1.4"/>
+ <!-- Legend -->
+ <text x="40" y="120" class="t-primary" font-size="10">Legend</text>
+ <rect x="40" y="132" width="14" height="9" class="c-backend"/>
+ <text x="60" y="140" class="t-muted" font-size="7">Backend</text>
+ `);
+ assert.notEqual(code, 0);
+ const check = result.checks.find((item) => item.name === 'legend_clearance');
+ assert.equal(check.ok, false);
+ assert.match(check.details[0], /Legend/);
+});
+
+process.on('exit', () => fs.rmSync(tmp, { recursive: true, force: true }));
diff --git a/examples/dataflow-product-analytics.html b/examples/dataflow-product-analytics.html
index 34f2599b..2dd24601 100644
--- a/examples/dataflow-product-analytics.html
+++ b/examples/dataflow-product-analytics.html
@@ -3,7 +3,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="archify 2.6.0">
+ <meta name="generator" content="archify 2.7.0">
<title>Product Analytics Data Flow Diagram</title>
<script>
// Resolve the theme before first paint so light-preference users don't
diff --git a/examples/lifecycle-agent-run.html b/examples/lifecycle-agent-run.html
index 5c5301af..ace0d2f9 100644
--- a/examples/lifecycle-agent-run.html
+++ b/examples/lifecycle-agent-run.html
@@ -3,7 +3,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="archify 2.6.0">
+ <meta name="generator" content="archify 2.7.0">
<title>Agent Run Lifecycle Diagram</title>
<script>
// Resolve the theme before first paint so light-preference users don't
diff --git a/examples/sequence-cache-miss-request.html b/examples/sequence-cache-miss-request.html
index 48dbb926..cab5c4b8 100644
--- a/examples/sequence-cache-miss-request.html
+++ b/examples/sequence-cache-miss-request.html
@@ -3,7 +3,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="archify 2.6.0">
+ <meta name="generator" content="archify 2.7.0">
<title>Cache Miss Request Sequence Diagram</title>
<script>
// Resolve the theme before first paint so light-preference users don't
diff --git a/examples/web-app-rendered.html b/examples/web-app-rendered.html
index d05bde69..923c1ca9 100644
--- a/examples/web-app-rendered.html
+++ b/examples/web-app-rendered.html
@@ -3,7 +3,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="archify 2.6.0">
+ <meta name="generator" content="archify 2.7.0">
<title>Sample Web App Diagram</title>
<script>
// Resolve the theme before first paint so light-preference users don't
diff --git a/examples/web-app.html b/examples/web-app.html
index 338cf341..16f7b046 100644
--- a/examples/web-app.html
+++ b/examples/web-app.html
@@ -3,7 +3,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="archify 2.6.0">
+ <meta name="generator" content="archify 2.7.0">
<title>Sample Web App Architecture Diagram</title>
<script>
// Resolve the theme before first paint so light-preference users don't
diff --git a/examples/workflow-agent-tool-call-rendered.html b/examples/workflow-agent-tool-call-rendered.html
index 6bba3a24..e5b074ee 100644
--- a/examples/workflow-agent-tool-call-rendered.html
+++ b/examples/workflow-agent-tool-call-rendered.html
@@ -3,7 +3,7 @@
<head>
<meta charset="UTF-8">
<meta name="viewport" content="width=device-width, initial-scale=1.0">
- <meta name="generator" content="archify 2.6.0">
+ <meta name="generator" content="archify 2.7.0">
<title>Agent Tool Call Workflow Diagram</title>
<script>
// Resolve the theme before first paint so light-preference users don't
@@ -501,7 +501,7 @@
<!-- Main Diagram -->
<div class="diagram-container">
- <svg viewBox="0 0 720 780" role="img" aria-label="Agent Tool Call Workflow — Renderer-driven workflow prototype with lanes, anchored nodes, and orthogonal edges (workflow diagram)">
+ <svg viewBox="0 0 720 900" role="img" aria-label="Agent Tool Call Workflow — Renderer-driven workflow prototype with lanes, anchored nodes, and orthogonal edges (workflow diagram)">
<!-- Definitions -->
<defs>
<marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
@@ -535,22 +535,46 @@
<text x="54" y="322" class="t-dim" font-size="10" font-weight="600">03 / Policy Boundary</text>
<rect x="40" y="424" width="640" height="104" rx="10" class="c-lane" stroke-width="1"/>
- <text x="54" y="446" class="t-dim" font-size="10" font-weight="600">04 / Tool Execution</text>
+ <rect x="46" y="430" width="628" height="92" rx="8" class="c-security-group" stroke-width="1"/>
+ <text x="54" y="446" class="t-security" font-size="10" font-weight="600">EX / Exception Handling</text>
<rect x="40" y="548" width="640" height="104" rx="10" class="c-lane" stroke-width="1"/>
- <text x="54" y="570" class="t-dim" font-size="10" font-weight="600">05 / Observability</text>
+ <text x="54" y="570" class="t-dim" font-size="10" font-weight="600">05 / Tool Execution</text>
+
+ <rect x="40" y="672" width="640" height="104" rx="10" class="c-lane" stroke-width="1"/>
+ <text x="54" y="694" class="t-dim" font-size="10" font-weight="600">06 / Observability</text>
+
+ <!-- Phase headers -->
+ <line x1="42" y1="35" x2="266" y2="35" class="a-default" stroke-width="1.1"/>
+ <rect x="42" y="27" width="224" height="16" rx="4" class="c-mask"/>
+ <text x="154" y="39" class="t-muted" font-size="8" font-weight="600" text-anchor="middle">Intake</text>
+ <line x1="254" y1="35" x2="476" y2="35" class="a-emphasis" stroke-width="1.1"/>
+ <rect x="254" y="27" width="222" height="16" rx="4" class="c-mask"/>
+ <text x="365" y="39" class="t-backend" font-size="8" font-weight="600" text-anchor="middle">Plan + route</text>
+ <line x1="454" y1="35" x2="671" y2="35" class="a-dashed" stroke-width="1.1"/>
+ <rect x="454" y="27" width="217" height="16" rx="4" class="c-mask"/>
+ <text x="562.5" y="39" class="t-messagebus" font-size="8" font-weight="600" text-anchor="middle">Execute + report</text>
+
+ <!-- Workflow groups -->
+ <rect x="250" y="214" width="230" height="58" rx="9" class="c-lane" stroke-width="1"/>
+ <text x="260" y="228" class="t-backend" font-size="7" font-weight="600">Planning loop</text>
+ <rect x="450" y="586" width="225" height="58" rx="9" class="c-lane" stroke-width="1"/>
+ <text x="460" y="600" class="t-messagebus" font-size="7" font-weight="600">Tool work</text>
+ <rect x="380" y="462" width="295" height="58" rx="9" class="c-security-group" stroke-width="1"/>
+ <text x="390" y="476" class="t-security" font-size="7" font-weight="600">Human or policy stop</text>
<!-- Edge paths -->
<path d="M 134 119 L 174 119" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<path d="M 220 145 L 220 166 L 300 166 L 300 209" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
<path d="M 346 243 L 384 243" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
<path d="M 430 269 L 430 290 L 430 290 L 430 333" class="a-security" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
- <path d="M 430 401 L 430 414 L 500 414 L 500 457" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path d="M 546 491 L 579 491" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
- <path d="M 625 517 L 625 673 L 500 673 L 500 641" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <path d="M 546 615 L 692 615 L 692 119 L 671 119" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
- <path d="M 300 277 L 300 414 L 220 414 L 220 589" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
- <path d="M 266 615 L 454 615" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path d="M 430 401 L 430 476 L 500 476 L 500 581" class="a-emphasis" stroke-width="1.8" marker-end="url(#arrowhead-emphasis)"/>
+ <path d="M 430 401 L 430 414 L 500 414 L 500 465" class="a-security" stroke-width="1.4" marker-end="url(#arrowhead-security)"/>
+ <path d="M 546 491 L 579 491" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path d="M 546 615 L 579 615" class="a-default" stroke-width="1.4" marker-end="url(#arrowhead)"/>
+ <path d="M 671 615 L 692 615 L 692 119 L 671 119" class="a-emphasis" stroke-width="1.2" marker-end="url(#arrowhead-emphasis)"/>
+ <path d="M 625 641 L 625 797 L 500 797 L 500 765" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
+ <path d="M 266 739 L 454 739" class="a-dashed" stroke-width="1.4" marker-end="url(#arrowhead-dashed)"/>
<!-- Nodes -->
<rect x="42" y="93" width="92" height="52" rx="6" class="c-mask"/>
@@ -585,26 +609,36 @@
<text x="430" y="371" class="t-muted" font-size="8" text-anchor="middle">scope + consent</text>
<text x="430" y="389" class="t-security" font-size="7" text-anchor="middle">block risky ops</text>
- <rect x="454" y="457" width="92" height="68" rx="6" class="c-mask"/>
- <rect x="454" y="457" width="92" height="68" rx="6" class="c-messagebus" stroke-width="1.5"/>
- <text x="500" y="478" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">Tool Call</text>
- <text x="500" y="495" class="t-muted" font-size="8" text-anchor="middle">shell / browser / MCP</text>
- <text x="500" y="513" class="t-messagebus" font-size="7" text-anchor="middle">structured result</text>
+ <rect x="454" y="465" width="92" height="52" rx="6" class="c-mask"/>
+ <rect x="454" y="465" width="92" height="52" rx="6" class="c-security" stroke-width="1.5"/>
+ <text x="500" y="486" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">Blocked</text>
+ <text x="500" y="503" class="t-muted" font-size="8" text-anchor="middle">wait or reject</text>
<rect x="579" y="465" width="92" height="52" rx="6" class="c-mask"/>
- <rect x="579" y="465" width="92" height="52" rx="6" class="c-cloud" stroke-width="1.5"/>
- <text x="625" y="486" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">External API</text>
- <text x="625" y="503" class="t-muted" font-size="8" text-anchor="middle">network service</text>
-
- <rect x="174" y="589" width="92" height="52" rx="6" class="c-mask"/>
- <rect x="174" y="589" width="92" height="52" rx="6" class="c-database" stroke-width="1.5"/>
- <text x="220" y="610" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">Context Store</text>
- <text x="220" y="627" class="t-muted" font-size="8" text-anchor="middle">repo + memory</text>
-
- <rect x="454" y="589" width="92" height="52" rx="6" class="c-mask"/>
- <rect x="454" y="589" width="92" height="52" rx="6" class="c-database" stroke-width="1.5"/>
- <text x="500" y="610" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">Trace Log</text>
- <text x="500" y="627" class="t-muted" font-size="8" text-anchor="middle">events + output</text>
+ <rect x="579" y="465" width="92" height="52" rx="6" class="c-messagebus" stroke-width="1.5"/>
+ <text x="625" y="486" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">Retry Path</text>
+ <text x="625" y="503" class="t-muted" font-size="8" text-anchor="middle">revise request</text>
+
+ <rect x="454" y="581" width="92" height="68" rx="6" class="c-mask"/>
+ <rect x="454" y="581" width="92" height="68" rx="6" class="c-messagebus" stroke-width="1.5"/>
+ <text x="500" y="602" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">Tool Call</text>
+ <text x="500" y="619" class="t-muted" font-size="8" text-anchor="middle">shell / browser / MCP</text>
+ <text x="500" y="637" class="t-messagebus" font-size="7" text-anchor="middle">structured result</text>
+
+ <rect x="579" y="589" width="92" height="52" rx="6" class="c-mask"/>
+ <rect x="579" y="589" width="92" height="52" rx="6" class="c-cloud" stroke-width="1.5"/>
+ <text x="625" y="610" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">External API</text>
+ <text x="625" y="627" class="t-muted" font-size="8" text-anchor="middle">network service</text>
+
+ <rect x="174" y="713" width="92" height="52" rx="6" class="c-mask"/>
+ <rect x="174" y="713" width="92" height="52" rx="6" class="c-database" stroke-width="1.5"/>
+ <text x="220" y="734" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">Context Store</text>
+ <text x="220" y="751" class="t-muted" font-size="8" text-anchor="middle">repo + memory</text>
+
+ <rect x="454" y="713" width="92" height="52" rx="6" class="c-mask"/>
+ <rect x="454" y="713" width="92" height="52" rx="6" class="c-database" stroke-width="1.5"/>
+ <text x="500" y="734" class="t-primary" font-size="11" font-weight="600" text-anchor="middle">Trace Log</text>
+ <text x="500" y="751" class="t-muted" font-size="8" text-anchor="middle">events + output</text>
<!-- Edge labels -->
@@ -613,30 +647,29 @@
<rect x="423" y="277.5" width="82" height="14" rx="3" class="c-mask"/>
<text x="464" y="287.5" class="t-security" font-size="8" text-anchor="middle">needs approval?</text>
- <rect x="440.8" y="408" width="48.4" height="14" rx="3" class="c-mask"/>
- <text x="465" y="418" class="t-backend" font-size="8" text-anchor="middle">approved</text>
-
- <rect x="526.3" y="653" width="72.4" height="14" rx="3" class="c-mask"/>
- <text x="562.5" y="663" class="t-database" font-size="8" text-anchor="middle">record result</text>
- <rect x="624.2" y="347" width="91.6" height="14" rx="3" class="c-mask"/>
- <text x="670" y="357" class="t-backend" font-size="8" text-anchor="middle">summarize outcome</text>
- <rect x="226.2" y="394" width="67.6" height="14" rx="3" class="c-mask"/>
- <text x="260" y="404" class="t-database" font-size="8" text-anchor="middle">load context</text>
- <rect x="327" y="612" width="106" height="14" rx="3" class="c-mask"/>
- <text x="380" y="622" class="t-database" font-size="8" text-anchor="middle">write trace + memory</text>
+
+ <rect x="445.6" y="406" width="38.8" height="14" rx="3" class="c-mask"/>
+ <text x="465" y="416" class="t-security" font-size="8" text-anchor="middle">denied</text>
+
+
+
+ <rect x="526.3" y="777" width="72.4" height="14" rx="3" class="c-mask"/>
+ <text x="562.5" y="787" class="t-database" font-size="8" text-anchor="middle">record result</text>
+ <rect x="326.4" y="725" width="77.2" height="14" rx="3" class="c-mask"/>
+ <text x="365" y="735" class="t-database" font-size="8" text-anchor="middle">trace + memory</text>
<!-- Legend -->
- <text x="175" y="676" class="t-primary" font-size="10" font-weight="600">Legend</text>
- <rect x="175" y="688" width="14" height="9" rx="2" class="c-frontend" stroke-width="1"/>
- <text x="195" y="696" class="t-muted" font-size="7">User UI</text>
- <rect x="260" y="688" width="14" height="9" rx="2" class="c-backend" stroke-width="1"/>
- <text x="280" y="696" class="t-muted" font-size="7">Agent logic</text>
- <rect x="370" y="688" width="14" height="9" rx="2" class="c-security" stroke-width="1"/>
- <text x="390" y="696" class="t-muted" font-size="7">Policy</text>
- <rect x="455" y="688" width="14" height="9" rx="2" class="c-messagebus" stroke-width="1"/>
- <text x="475" y="696" class="t-muted" font-size="7">Tool action</text>
- <rect x="565" y="688" width="14" height="9" rx="2" class="c-database" stroke-width="1"/>
- <text x="585" y="696" class="t-muted" font-size="7">Context / trace</text>
+ <text x="175" y="800" class="t-primary" font-size="10" font-weight="600">Legend</text>
+ <rect x="175" y="812" width="14" height="9" rx="2" class="c-frontend" stroke-width="1"/>
+ <text x="195" y="820" class="t-muted" font-size="7">User UI</text>
+ <rect x="260" y="812" width="14" height="9" rx="2" class="c-backend" stroke-width="1"/>
+ <text x="280" y="820" class="t-muted" font-size="7">Agent logic</text>
+ <rect x="370" y="812" width="14" height="9" rx="2" class="c-security" stroke-width="1"/>
+ <text x="390" y="820" class="t-muted" font-size="7">Policy</text>
+ <rect x="455" y="812" width="14" height="9" rx="2" class="c-messagebus" stroke-width="1"/>
+ <text x="475" y="820" class="t-muted" font-size="7">Tool action</text>
+ <rect x="565" y="812" width="14" height="9" rx="2" class="c-database" stroke-width="1"/>
+ <text x="585" y="820" class="t-muted" font-size="7">Context / trace</text>
</svg>
</div>