Skip to content

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

Share renderer utils, harden template slot replacement

tt-a1ib8e09a537842
diff --git a/archify/assets/template.html b/archify/assets/template.html
index c5433698..031c2f5d 100644
--- a/archify/assets/template.html
+++ b/archify/assets/template.html
@@ -448,6 +448,7 @@
<!-- Main Diagram -->
<div class="diagram-container">
+ <!-- ARCHIFY:SVG_SLOT_START -->
<svg viewBox="0 0 1000 680">
<!-- Definitions -->
<defs>
@@ -594,9 +595,10 @@
<rect x="720" y="178" width="16" height="10" rx="2" class="c-security-group" stroke-width="1"/>
<text x="742" y="186" class="t-muted" font-size="8">Security Group</text>
</svg>
+ <!-- ARCHIFY:SVG_SLOT_END -->
</div>
- <!-- Info Cards -->
+ <!-- ARCHIFY:CARDS_SLOT_START -->
<div class="cards">
<div class="card">
<div class="card-header">
@@ -637,6 +639,7 @@
</ul>
</div>
</div>
+ <!-- ARCHIFY:CARDS_SLOT_END -->
<!-- Footer -->
<p class="footer">
diff --git a/archify/renderers/dataflow/render-dataflow.mjs b/archify/renderers/dataflow/render-dataflow.mjs
index 3c3c6986..9a808478 100644
--- a/archify/renderers/dataflow/render-dataflow.mjs
+++ b/archify/renderers/dataflow/render-dataflow.mjs
@@ -1,6 +1,7 @@
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+import { esc, renderDefinitions, renderCards, applyTemplate } from '../shared/utils.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '../..');
@@ -52,16 +53,6 @@ const arrowClass = {
dashed: ['a-dashed', 'arrowhead-dashed']
};
-function esc(value) {
- return String(value ?? '').replace(/[&<>"']/g, (c) => ({
- '&': '&amp;',
- '<': '&lt;',
- '>': '&gt;',
- '"': '&quot;',
- "'": '&#39;'
- }[c]));
-}
-
function stageX(index) {
return layout.leftX + index * layout.colGap;
}
@@ -229,27 +220,6 @@ function labelPoint(flow, points) {
return [(a[0] + b[0]) / 2 + (flow.labelDx || 0), (a[1] + b[1]) / 2 - 10 + (flow.labelDy || 0)];
}
-function renderDefinitions() {
- return ` <!-- Definitions -->
- <defs>
- <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-default" />
- </marker>
- <marker id="arrowhead-emphasis" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-emphasis" />
- </marker>
- <marker id="arrowhead-security" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-security" />
- </marker>
- <marker id="arrowhead-dashed" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-dashed" />
- </marker>
- <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
- <path d="M 40 0 L 0 0 0 40" class="c-grid" stroke-width="0.5"/>
- </pattern>
- </defs>`;
-}
-
function renderStage(stage, index) {
const cx = stageX(index);
const x = cx - layout.stageW / 2;
@@ -337,33 +307,13 @@ ${renderLegend()}
</svg>`;
}
-function renderCards() {
- const cards = dataflow.cards || [];
- return ` <!-- Info Cards -->
- <div class="cards">
-${cards.map((card) => ` <div class="card">
- <div class="card-header">
- <div class="card-dot ${esc(card.dot)}"></div>
- <h3>${esc(card.title)}</h3>
- </div>
- <ul>
-${card.items.map((item) => ` <li>&bull; ${esc(item)}</li>`).join('\n')}
- </ul>
- </div>`).join('\n\n')}
- </div>`;
-}
-
-function applyTemplate(svg, cards) {
- return template
- .replace('<title>[PROJECT NAME] Architecture Diagram</title>', `<title>${esc(dataflow.meta.title)} Diagram</title>`)
- .replace('<h1>[PROJECT NAME] Architecture</h1>', `<h1>${esc(dataflow.meta.title)}</h1>`)
- .replace('<p class="subtitle">[Subtitle description]</p>', `<p class="subtitle">${esc(dataflow.meta.subtitle || '')}</p>`)
- .replace(/ <svg viewBox="0 0 1000 680">[\s\S]*? <\/svg>/, svg)
- .replace(/ <!-- Info Cards -->[\s\S]*? <!-- Footer -->/, `${cards}\n\n <!-- Footer -->`)
- .replace('[Project Name] &bull; [Additional metadata]', 'Data-flow diagram &bull; Built with Archify &bull; Press <kbd>T</kbd> for theme and <kbd>E</kbd> for export');
-}
-
validateDataflow();
fs.mkdirSync(path.dirname(outPath), { recursive: true });
-fs.writeFileSync(outPath, applyTemplate(renderSvg(), renderCards()));
+fs.writeFileSync(outPath, applyTemplate(template, {
+ title: dataflow.meta.title,
+ subtitle: dataflow.meta.subtitle,
+ footer: 'Data-flow diagram &bull; Built with Archify &bull; Press <kbd>T</kbd> for theme and <kbd>E</kbd> for export',
+ svg: renderSvg(),
+ cards: renderCards(dataflow.cards),
+}));
console.log(outPath);
diff --git a/archify/renderers/lifecycle/render-lifecycle.mjs b/archify/renderers/lifecycle/render-lifecycle.mjs
index ab3eebdc..94bb8088 100644
--- a/archify/renderers/lifecycle/render-lifecycle.mjs
+++ b/archify/renderers/lifecycle/render-lifecycle.mjs
@@ -1,6 +1,7 @@
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+import { esc, renderDefinitions, renderCards, applyTemplate } from '../shared/utils.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '../..');
@@ -56,16 +57,6 @@ const arrowClass = {
dashed: ['a-dashed', 'arrowhead-dashed']
};
-function esc(value) {
- return String(value ?? '').replace(/[&<>"']/g, (c) => ({
- '&': '&amp;',
- '<': '&lt;',
- '>': '&gt;',
- '"': '&quot;',
- "'": '&#39;'
- }[c]));
-}
-
function legendY() {
return 562;
}
@@ -286,27 +277,6 @@ function labelPoint(transition, points) {
return [(a[0] + b[0]) / 2 + (transition.labelDx || 0), (a[1] + b[1]) / 2 - 10 + (transition.labelDy || 0)];
}
-function renderDefinitions() {
- return ` <!-- Definitions -->
- <defs>
- <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-default" />
- </marker>
- <marker id="arrowhead-emphasis" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-emphasis" />
- </marker>
- <marker id="arrowhead-security" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-security" />
- </marker>
- <marker id="arrowhead-dashed" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-dashed" />
- </marker>
- <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
- <path d="M 40 0 L 0 0 0 40" class="c-grid" stroke-width="0.5"/>
- </pattern>
- </defs>`;
-}
-
function renderBands() {
return ` <path d="M 72 112 L 908 112" class="a-default" stroke-width="0.8" stroke-dasharray="3,8"/>
<text x="72" y="100" class="t-dim" font-size="10" font-weight="600">01 / Lifecycle phases</text>
@@ -406,33 +376,13 @@ ${renderLegend()}
</svg>`;
}
-function renderCards() {
- const cards = lifecycle.cards || [];
- return ` <!-- Info Cards -->
- <div class="cards">
-${cards.map((card) => ` <div class="card">
- <div class="card-header">
- <div class="card-dot ${esc(card.dot)}"></div>
- <h3>${esc(card.title)}</h3>
- </div>
- <ul>
-${card.items.map((item) => ` <li>&bull; ${esc(item)}</li>`).join('\n')}
- </ul>
- </div>`).join('\n\n')}
- </div>`;
-}
-
-function applyTemplate(svg, cards) {
- return template
- .replace('<title>[PROJECT NAME] Architecture Diagram</title>', `<title>${esc(lifecycle.meta.title)} Diagram</title>`)
- .replace('<h1>[PROJECT NAME] Architecture</h1>', `<h1>${esc(lifecycle.meta.title)}</h1>`)
- .replace('<p class="subtitle">[Subtitle description]</p>', `<p class="subtitle">${esc(lifecycle.meta.subtitle || '')}</p>`)
- .replace(/ <svg viewBox="0 0 1000 680">[\s\S]*? <\/svg>/, svg)
- .replace(/ <!-- Info Cards -->[\s\S]*? <!-- Footer -->/, `${cards}\n\n <!-- Footer -->`)
- .replace('[Project Name] &bull; [Additional metadata]', 'Lifecycle diagram &bull; Built with Archify &bull; Press <kbd>T</kbd> for theme and <kbd>E</kbd> for export');
-}
-
validateLifecycle();
fs.mkdirSync(path.dirname(outPath), { recursive: true });
-fs.writeFileSync(outPath, applyTemplate(renderSvg(), renderCards()));
+fs.writeFileSync(outPath, applyTemplate(template, {
+ title: lifecycle.meta.title,
+ subtitle: lifecycle.meta.subtitle,
+ footer: 'Lifecycle diagram &bull; Built with Archify &bull; Press <kbd>T</kbd> for theme and <kbd>E</kbd> for export',
+ svg: renderSvg(),
+ cards: renderCards(lifecycle.cards),
+}));
console.log(outPath);
diff --git a/archify/renderers/sequence/render-sequence.mjs b/archify/renderers/sequence/render-sequence.mjs
index 55f58ba7..f83b6822 100644
--- a/archify/renderers/sequence/render-sequence.mjs
+++ b/archify/renderers/sequence/render-sequence.mjs
@@ -1,6 +1,7 @@
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+import { esc, renderDefinitions, renderCards, applyTemplate } from '../shared/utils.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '../..');
@@ -51,16 +52,6 @@ const arrowClass = {
return: ['a-default', 'arrowhead']
};
-function esc(value) {
- return String(value ?? '').replace(/[&<>"']/g, (c) => ({
- '&': '&amp;',
- '<': '&lt;',
- '>': '&gt;',
- '"': '&quot;',
- "'": '&#39;'
- }[c]));
-}
-
function participantX(index) {
return layout.leftX + index * layout.colGap;
}
@@ -120,27 +111,6 @@ function validateSequence() {
}
}
-function renderDefinitions() {
- return ` <!-- Definitions -->
- <defs>
- <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-default" />
- </marker>
- <marker id="arrowhead-emphasis" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-emphasis" />
- </marker>
- <marker id="arrowhead-security" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-security" />
- </marker>
- <marker id="arrowhead-dashed" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-dashed" />
- </marker>
- <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
- <path d="M 40 0 L 0 0 0 40" class="c-grid" stroke-width="0.5"/>
- </pattern>
- </defs>`;
-}
-
function renderParticipant(participant) {
const fill = typeClass[participant.type] || 'c-external';
return ` <rect x="${participant.x}" y="${layout.topY}" width="${layout.participantW}" height="${layout.participantH}" rx="6" class="c-mask"/>
@@ -239,32 +209,13 @@ ${renderLegend()}
</svg>`;
}
-function renderCards() {
- return ` <!-- Info Cards -->
- <div class="cards">
-${(sequence.cards || []).map((card) => ` <div class="card">
- <div class="card-header">
- <div class="card-dot ${esc(card.dot)}"></div>
- <h3>${esc(card.title)}</h3>
- </div>
- <ul>
-${card.items.map((item) => ` <li>&bull; ${esc(item)}</li>`).join('\n')}
- </ul>
- </div>`).join('\n\n')}
- </div>`;
-}
-
-function applyTemplate(svg, cards) {
- return template
- .replace('<title>[PROJECT NAME] Architecture Diagram</title>', `<title>${esc(sequence.meta.title)} Diagram</title>`)
- .replace('<h1>[PROJECT NAME] Architecture</h1>', `<h1>${esc(sequence.meta.title)}</h1>`)
- .replace('<p class="subtitle">[Subtitle description]</p>', `<p class="subtitle">${esc(sequence.meta.subtitle || '')}</p>`)
- .replace(/ <svg viewBox="0 0 1000 680">[\s\S]*? <\/svg>/, svg)
- .replace(/ <!-- Info Cards -->[\s\S]*? <!-- Footer -->/, `${cards}\n\n <!-- Footer -->`)
- .replace('[Project Name] &bull; [Additional metadata]', 'Sequence diagram &bull; Built with Archify &bull; Press <kbd>T</kbd> for theme and <kbd>E</kbd> for export');
-}
-
validateSequence();
fs.mkdirSync(path.dirname(outPath), { recursive: true });
-fs.writeFileSync(outPath, applyTemplate(renderSvg(), renderCards()));
+fs.writeFileSync(outPath, applyTemplate(template, {
+ title: sequence.meta.title,
+ subtitle: sequence.meta.subtitle,
+ footer: 'Sequence diagram &bull; Built with Archify &bull; Press <kbd>T</kbd> for theme and <kbd>E</kbd> for export',
+ svg: renderSvg(),
+ cards: renderCards(sequence.cards),
+}));
console.log(outPath);
diff --git a/archify/renderers/shared/utils.mjs b/archify/renderers/shared/utils.mjs
new file mode 100644
index 00000000..4ff6bfcb
--- /dev/null
+++ b/archify/renderers/shared/utils.mjs
@@ -0,0 +1,75 @@
+const ESCAPE_MAP = { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' };
+
+export function esc(value) {
+ return String(value ?? '').replace(/[&<>"']/g, (c) => ESCAPE_MAP[c]);
+}
+
+export function renderDefinitions() {
+ return ` <!-- Definitions -->
+ <defs>
+ <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+ <polygon points="0 0, 10 3.5, 0 7" class="m-default" />
+ </marker>
+ <marker id="arrowhead-emphasis" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+ <polygon points="0 0, 10 3.5, 0 7" class="m-emphasis" />
+ </marker>
+ <marker id="arrowhead-security" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+ <polygon points="0 0, 10 3.5, 0 7" class="m-security" />
+ </marker>
+ <marker id="arrowhead-dashed" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
+ <polygon points="0 0, 10 3.5, 0 7" class="m-dashed" />
+ </marker>
+ <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
+ <path d="M 40 0 L 0 0 0 40" class="c-grid" stroke-width="0.5"/>
+ </pattern>
+ </defs>`;
+}
+
+export function renderCards(cards) {
+ const list = cards || [];
+ return ` <!-- Info Cards -->
+ <div class="cards">
+${list.map((card) => ` <div class="card">
+ <div class="card-header">
+ <div class="card-dot ${esc(card.dot)}"></div>
+ <h3>${esc(card.title)}</h3>
+ </div>
+ <ul>
+${card.items.map((item) => ` <li>&bull; ${esc(item)}</li>`).join('\n')}
+ </ul>
+ </div>`).join('\n\n')}
+ </div>`;
+}
+
+const SVG_SLOT_RE = / <!-- ARCHIFY:SVG_SLOT_START -->[\s\S]*? <!-- ARCHIFY:SVG_SLOT_END -->/;
+const CARDS_SLOT_RE = / <!-- ARCHIFY:CARDS_SLOT_START -->[\s\S]*? <!-- ARCHIFY:CARDS_SLOT_END -->/;
+
+const TEMPLATE_PLACEHOLDERS = [
+ '<title>[PROJECT NAME] Architecture Diagram</title>',
+ '<h1>[PROJECT NAME] Architecture</h1>',
+ '<p class="subtitle">[Subtitle description]</p>',
+ '[Project Name] &bull; [Additional metadata]',
+];
+
+// `footer` is injected as raw HTML so callers can embed <kbd> hints;
+// pass only trusted strings here, never user input.
+export function applyTemplate(template, { title, subtitle, footer, svg, cards }) {
+ if (!SVG_SLOT_RE.test(template)) {
+ throw new Error('applyTemplate: template missing ARCHIFY:SVG_SLOT sentinel');
+ }
+ if (!CARDS_SLOT_RE.test(template)) {
+ throw new Error('applyTemplate: template missing ARCHIFY:CARDS_SLOT sentinel');
+ }
+ for (const ph of TEMPLATE_PLACEHOLDERS) {
+ if (!template.includes(ph)) {
+ throw new Error(`applyTemplate: template missing placeholder ${JSON.stringify(ph)}`);
+ }
+ }
+ return template
+ .replace(TEMPLATE_PLACEHOLDERS[0], `<title>${esc(title)} Diagram</title>`)
+ .replace(TEMPLATE_PLACEHOLDERS[1], `<h1>${esc(title)}</h1>`)
+ .replace(TEMPLATE_PLACEHOLDERS[2], `<p class="subtitle">${esc(subtitle ?? '')}</p>`)
+ .replace(SVG_SLOT_RE, svg)
+ .replace(CARDS_SLOT_RE, cards)
+ .replace(TEMPLATE_PLACEHOLDERS[3], footer);
+}
diff --git a/archify/renderers/workflow/render-workflow.mjs b/archify/renderers/workflow/render-workflow.mjs
index 08ddac01..c41a9f28 100644
--- a/archify/renderers/workflow/render-workflow.mjs
+++ b/archify/renderers/workflow/render-workflow.mjs
@@ -1,6 +1,7 @@
import fs from 'node:fs';
import path from 'node:path';
import { fileURLToPath } from 'node:url';
+import { esc, renderDefinitions, renderCards, applyTemplate } from '../shared/utils.mjs';
const __dirname = path.dirname(fileURLToPath(import.meta.url));
const skillRoot = path.resolve(__dirname, '../..');
@@ -55,16 +56,6 @@ const arrowClass = {
const laneIndex = new Map(workflow.lanes.map((lane, index) => [lane.id, index]));
-function esc(value) {
- return String(value).replace(/[&<>"']/g, (c) => ({
- '&': '&amp;',
- '<': '&lt;',
- '>': '&gt;',
- '"': '&quot;',
- "'": '&#39;'
- }[c]));
-}
-
function laneTop(id) {
return layout.laneY + laneIndex.get(id) * (layout.laneH + layout.laneGap);
}
@@ -296,27 +287,6 @@ function labelPoint(edge, points) {
return [(a[0] + b[0]) / 2 + (edge.labelDx || 0), (a[1] + b[1]) / 2 - 10 + (edge.labelDy || 0)];
}
-function renderDefinitions() {
- return ` <!-- Definitions -->
- <defs>
- <marker id="arrowhead" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-default" />
- </marker>
- <marker id="arrowhead-emphasis" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-emphasis" />
- </marker>
- <marker id="arrowhead-security" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-security" />
- </marker>
- <marker id="arrowhead-dashed" markerWidth="10" markerHeight="7" refX="9" refY="3.5" orient="auto">
- <polygon points="0 0, 10 3.5, 0 7" class="m-dashed" />
- </marker>
- <pattern id="grid" width="40" height="40" patternUnits="userSpaceOnUse">
- <path d="M 40 0 L 0 0 0 40" class="c-grid" stroke-width="0.5"/>
- </pattern>
- </defs>`;
-}
-
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"/>
@@ -400,33 +370,14 @@ ${renderLegend()}
</svg>`;
}
-function renderCards() {
- const cards = workflow.cards || [];
- return ` <!-- Info Cards -->
- <div class="cards">
-${cards.map((card) => ` <div class="card">
- <div class="card-header">
- <div class="card-dot ${esc(card.dot)}"></div>
- <h3>${esc(card.title)}</h3>
- </div>
- <ul>
-${card.items.map((item) => ` <li>&bull; ${esc(item)}</li>`).join('\n')}
- </ul>
- </div>`).join('\n\n')}
- </div>`;
-}
-
-function applyTemplate(svg, cards) {
- return template
- .replace('<title>[PROJECT NAME] Architecture Diagram</title>', `<title>${esc(workflow.meta.title)} Diagram</title>`)
- .replace('<h1>[PROJECT NAME] Architecture</h1>', `<h1>${esc(workflow.meta.title)}</h1>`)
- .replace('<p class="subtitle">[Subtitle description]</p>', `<p class="subtitle">${esc(workflow.meta.subtitle || '')}</p>`)
- .replace(/ <svg viewBox="0 0 1000 680">[\s\S]*? <\/svg>/, svg)
- .replace(/ <!-- Info Cards -->[\s\S]*? <!-- Footer -->/, `${cards}\n\n <!-- Footer -->`)
- .replace('[Project Name] &bull; [Additional metadata]', 'Workflow diagram &bull; Built with Archify &bull; Press <kbd>T</kbd> for theme and <kbd>E</kbd> for export');
-}
fs.mkdirSync(path.dirname(outPath), { recursive: true });
validateWorkflow();
-fs.writeFileSync(outPath, applyTemplate(renderSvg(), renderCards()));
+fs.writeFileSync(outPath, applyTemplate(template, {
+ title: workflow.meta.title,
+ subtitle: workflow.meta.subtitle,
+ footer: 'Workflow diagram &bull; Built with Archify &bull; Press <kbd>T</kbd> for theme and <kbd>E</kbd> for export',
+ svg: renderSvg(),
+ cards: renderCards(workflow.cards),
+}));
console.log(outPath);