feat(drawio): export Archify diagrams as editable draw.io files - #72
feat(drawio): export Archify diagrams as editable draw.io files#72kidoln wants to merge 7 commits into
Conversation
…orthogonal routing - New CLI: archify export-drawio <type> <input.json> [output.drawio] [--json] - New viewer menu item: Export -> draw.io (browser-side conversion) - Geometry extracted from the rendered SVG (renderer-computed layout, 100% fidelity) - Edges bind source/target to vertex cell ids: dragging a box keeps connections - Interior route waypoints preserved via <Array as=points> - Nodes parented into boundary containers with parent-relative coordinates - Component/state types mapped to draw.io built-in shapes (cylinder, cloud, shield...) - Edge style: orthogonalEdgeStyle with rounded corners - Verified: 51 nodes across all 5 diagram types match SVG coordinates exactly; all edges topologically bound; 653 tests pass
…uals - CLI: archify export-drawio <type> <input.json> [output] --strict - Viewer: Export -> draw.io strict (exact shapes & colors) button - Strict mode keeps the authored rounded rectangles (no built-in shape substitution) with the exact corner radius (absoluteArcSize=1;arcSize=rx) - Colors are pre-composited from the artifact CSS: translucent fills are alpha-blended over the opaque mask/page background so draw.io renders the same pixel color; stroke widths and dash patterns come from the CSS classes - Edge corner radius is measured from the SVG path Q-curves and emitted as arcSize = 2 x radius (draw.io convention), reproducing radius 8 (architecture) and 10 (lifecycle) while workflow/dataflow stay sharp - Connection points pinned via exitX/exitY/entryX/entryY at the exact authored border anchors; edge labels placed at their authored position along the polyline - Dark page background (#020617) and JetBrains Mono font stack preserved - Browser variant resolves colors from live computed styles, so it follows the reader's current theme/preset - Verified: 51/51 nodes match SVG coordinates across all 5 types; colors, radii, and dash patterns cross-checked against the CSS; 657 tests pass
- CLI (export-drawio --strict): extractPalette resolves the [data-theme="light"] variable block first; the dark :root block is now only a fallback for custom templates without a light theme, so the .drawio file is a stable light-themed diagram regardless of the artifact's dark default or any viewer theme. - Viewer button (draw.io strict): drawioBuildStrictXml wraps the build in withLightTheme — a synchronous data-theme swap restored in finally — and drawioParseColor additionally parses #rrggbb/#rgb. Custom-property reads return authored hex tokens, which previously failed the rgba()-only parser and silently fell back to the hardcoded dark mask/bg/text, so light fills were composited over a dark mask and the boxes stayed dark even after the prior light-forcing attempt. - Palette fallbacks flipped to light values; call-site comments updated. - Regenerated all rendered examples (both examples/ copies, web-app.html), docs gallery, README showcase GIF/receipt, and the ten sample .drawio files (strict now background="#f8fafc", pastel fills, dark ink). - Verified: 658 tests pass; light-forcing and hex parsing extracted from the shipped artifact pass a Node harness; CLI strict output visually verified in draw.io light and dark themes.
Sequence geometry is a timeline, not a node graph: message endpoints hang on lifelines far below the participant header boxes, so the generic border- anchored edge model snapped every message to the header bottom and dropped the only y-carrying points — all 12 messages collapsed into a knot under the participant row, labels/activations/segment names were lost entirely, and return messages lost their dash. Both export paths now route sequence artifacts through a dedicated builder: - Participants become shape=umlLifeline cells spanning header→timeline foot (perimeter=lifelinePerimeter, container for activation children), so each message's authored y survives as exitY/entryY fractions of the full timeline; labels sit one label-height above the line like the artifact. - Activation bars render as kind-colored child rects of their lifeline; the sequence renderer now stamps them with data-graph-role="activation" + data-activation-participant identity. - Segment bands keep their authored labels (matched from the separate segment-label groups by id) instead of the literal kind "segment". - Message labels resolve from the outer focus group (data-edge-label) when the path carries none; return-message dashes read the path's inline stroke-dasharray. - Viewer export: drawio and drawio-strict buttons dispatch sequence artifacts to the same builder; strict still force-resolves light. Non-strict sequence uses the identical topology with draw.io's default palette. Verified: 661 tests pass; exported examples/sequence-strict.drawio visually compared against the artifact render in draw.io viewer — timeline, activations, segments, labels, and return dashes all restored.
…ple drawio pairs Six samples were last rendered at v2.14.0 or earlier and still embedded the pre-drawio viewer shell, so their Export menus had no draw.io entries while the five artifacts refreshed alongside the exporter work did. - Re-rendered all 12 example HTMLs with the current pipeline. sequence-cache-miss.html and workflow-agent-tool-call.html were v2.9.0-era renders of cache-miss-request.sequence.json / agent-tool-call.workflow.json and now match their sibling artifacts byte-for-byte. - checkout-platform-delta.html regenerated via compare; the receipt diff is only the artifact sha256/bytes of the new template (28/28 checks). - Added a drawio + drawio-strict pair for each of the 10 static samples (delta excluded: its before/delta/after states are JS-driven and static SVG extraction yields an empty shell). - Re-exported the five type-named drawio demo pairs; output is byte-identical to the committed versions, so they stay unchanged. Verified: archify check passes on all 12 HTMLs, all 30 .drawio files parse as XML with full node content, and the export-drawio suite passes 34/34.
Review of the four drawio feature commits surfaced one escaping inconsistency, two silent-corruption paths, and the open risk of the two hand-mirrored implementations drifting apart. Fixes, all verified to leave the 15 committed example pairs byte-identical: - Non-strict edge labels now go through escapeAttr like every other value path. The real CLI pipeline was safe only because the SVG emission pre-escapes attributes; direct builder calls (the unit tests' own usage) with a '"' in a label emitted malformed XML. escapeText had no other callers and is gone. - Wraps parenting matches JSON boundaries to parsed boundaries by data-composition-frame-id (the renderer stamps the array index) instead of raw position. A boundary the SVG parser skips (zero-size) used to shift every later boundary onto the wrong frame and onto a parent cell id that was never emitted; now only that boundary's own wraps are lost. Positional pairing remains the fallback for inputs without frame-ids. - Sequence footY falls back 0 → headers+60 → 400 like the viewer, so an empty participant set no longer feeds -Infinity into lifeline heights. - Default --strict output is now <name>-strict.drawio, matching the viewer button and the examples, instead of <name>.strict.drawio. - The node-group attribute-order contract (id first, data-node-* after) is now documented at both ends: focusNodeAttrs and NODE_G_RE. - New parity test extracts the viewer's non-strict converter section from the live template.html and asserts byte-identical XML against the Node converter over the rendered web-app artifact, so future one-sided edits fail loudly. Plus regressions for the quote label, skipped-boundary parenting, empty-sequence NaN, and the strict default name. Verified: drawio suite 39/39, full suite 666/666, and all ten re-exported sample pairs diff clean against the committed files.
The draw.io export work changed skill runtime files (template.html,
renderers/shared/{cli,svg-to-drawio}.mjs, scripts/export-drawio.mjs) but
left the checked-in archive at the pre-drawio tree, which no longer
shipped the exporter at all. Rebuilt per CONTRIBUTING so the packaged
skill matches the source; release identity still checks 2.14.0.
tt-a1i
left a comment
tt-a1i
left a comment
There was a problem hiding this comment.
Thanks for taking on draw.io export - this capability is still absent from main, so I would like to keep moving it forward.
However, this branch has diverged too far to safely rebase as-is. It now contains 74 changed files and about 95% of the textual diff is generated output. A merge simulation produces seven direct conflicts, including archify.zip, gallery/proof assets, and delta artifacts. The package is still based on Archify 2.14.0 while main is already 2.15.0.
Could you rebuild the change from current main, either by replacing this branch or opening a clean follow-up PR? Ideally split the work into:
- converter, CLI, and tests;
- viewer integration and documentation;
- regenerated examples, gallery, and ZIP only once, after the source is stable.
Before that version is ready, I found several correctness issues that need addressing:
- In
archify/renderers/shared/svg-to-drawio.mjs:1183-1186, strict export writes a second<mxGeometry as="geometry">inside the edge's existing geometry. The sequence implementation at line 796 puts label coordinates on the single geometry element instead. XML parsing alone does not verify that diagrams.net applies the nested geometry, so this needs a real import or round-trip assertion. - Current
mainsupports authored brand marks, but the converter only reads and emitsid,kind,label,sublabel, andtag(svg-to-drawio.mjs:182-187,552-560,1108-1117). Merging this implementation would silently drop brand identity, including in the advertised strict 1:1 export. - The Node converter and the large inline viewer converter are hand-maintained copies. The parity test explicitly covers only one non-strict architecture artifact and excludes strict and sequence paths (
export-drawio.test.mjs:624-647). Please derive both surfaces from one canonical implementation, or add parity coverage for all five diagram types, strict/non-strict, and browser/CLI paths.
Two smaller follow-ups:
- All boundaries currently use
parent="1"while nodes are assigned only to their innermost boundary. In nested region/security-group diagrams, moving the outer region therefore does not move the inner group and its nodes. - Please document the viewer export and
archify export-drawiocommand in the English/Chinese README and packaged Skill docs.
The 39 draw.io-specific tests pass locally. The remaining request is mainly to reduce generated churn, rebuild the implementation semantically on current main, and add diagrams.net-level correctness coverage.
|
Thank you for the substantial work on editable draw.io export. The capability remains valuable and is still absent from The current branch should not be rebased or extended further. It is based on an older Archify release, now conflicts with Please open a clean follow-up PR from the latest
The clean implementation should also meet these correctness requirements:
Once the clean follow-up is open, the current PR can be closed in favor of it. This preserves the design work already completed while giving the feature a realistic route to approval and merge. |
3 participants
Problem and value
Archify artifacts are self-contained HTML, but readers who want to keep editing a diagram in standard tooling had no way out. This adds draw.io export to every artifact, in two variants:
Sequence diagrams route through a dedicated UML-lifeline builder so the timeline survives export: participants become
shape=umlLifelinecells spanning header→foot, activation bars become lifeline children, and each message's authored y survives as an exit/entry fraction. A headless path is included:archify export-drawio <type> <input.json> [output] [--strict] [--json].Scope
archify/renderers/shared/svg-to-drawio.mjs(zero-dependency regex parsing of the self-describing SVG; the SVG is the sole geometry source, coordinates never recomputed) plusarchify/scripts/export-drawio.mjsand theexport-drawioCLI subcommand.archify/assets/template.html), mirroring the Node converter; artifacts now carrydata-diagram-typeso the viewer can dispatch sequence exports.render-sequence.mjsstamps activation bars withdata-graph-role="activation"+ participant identity..drawio+-strict.drawiopair for each of the 10 static samples; the five per-type demo pairs refreshed (byte-identical); gallery artifacts and showcase proof regenerated;archify.ziprebuilt.-strict.drawiodefault naming, documented attribute-order contract, and a parity test that extracts the viewer converter from the live template and asserts byte-identical output with the Node converter.mxfile/diagramwrapper (draw.io opens the baremxGraphModeldirectly) and no new runtime dependencies.Stability impact
archify checkpasses on every re-rendered sample.data-diagram-type; both are consumed only by the exporter. The packaged skill (archify.zip) is rebuilt so installed skills match the source tree; release identity still checks2.14.0.data-last-export-*receipt attributes; the CLI exits non-zero. Rollback is reverting the branch — no data or contract migrations.Tests run
cd archify && npm test→ 666/666 pass (validators, release identity, golden, full suite; includes 39 drawio tests: parsing units, builder units, 5-type CLI integrations, strict/sequence regressions, viewer↔Node parity).node --test archify/test/export-drawio.test.mjs→ 39/39 pass../scripts/build-zip.sh archify.zip && node scripts/check-release-identity.mjs→release identity ok: 2.14.0.xmllint --noouton all 30 example.drawiofiles → all well-formed.Visual evidence
Visual review passed during development: each feature commit documents its draw.io-viewer comparison (strict always-light palette under light and dark themes; sequence timeline, activations, segments, labels, and return dashes restored via UML lifelines). The committed
examples/*.drawiopairs can be opened directly for re-verification; screenshots can be attached on request.Generated artifacts
examples/: 12 sample HTMLs re-rendered, 20 new per-sample.drawiopairs, receipt for the delta sample.docs/: gallery artifacts (11),docs/gallery.html,docs/gallery/manifest.json, showcase proof (docs/assets/archify-live-proof.gif+.json) — all rebuilt from the new shell.archify.zip: rebuilt in a dedicated commit; previously it did not ship the exporter at all.Checklist
npm testinarchify/.