astro-archify 0.3.4 → 0.3.5

package/README.md

@@ -1,6 +1,17 @@
 # astro-archify
 
-An Astro integration for rendering [Archify](https://github.com/tt-a1i/archify) system diagrams — architecture, workflow, sequence, data flow, and lifecycle — from JSON IR code blocks in your markdown/MDX content.
+An Astro integration for rendering [Archify](https://github.com/tt-a1i/archify) system diagrams — architecture, workflow, sequence, data flow, and lifecycle — from JSON IR code blocks in your markdown/MDX content. Works with standalone Astro projects and documentation frameworks like [Starlight](https://starlight.astro.build/).
+
+## Live demos
+
+| Demo | URL | Description |
+|------|-----|-------------|
+| **Starlight** | [astro-archify-starlight-demo.netlify.app](https://astro-archify-starlight-demo.netlify.app/) | Documentation site with Starlight |
+| **Standalone Astro** | [astro-archify-astro-demo.netlify.app](https://astro-archify-astro-demo.netlify.app/) | Pure Astro project template |
+
+See also [`starlight-demo/`](./starlight-demo/) and [`astro-demo/`](./astro-demo/) in this repo.
+
+Listed in the [Astro integrations directory](https://astro.build/integrations/?search=archify).
 
 Archify turns a typed JSON intermediate representation (IR) into a fully self-contained, already-interactive HTML artifact — inline SVG plus a small pan/zoom/focus viewer, with every script and its ~4800 lines of CSS inlined (the one exception is a Google Fonts `<link>`, which degrades gracefully if it can't load). This integration renders that artifact **at build time** using Archify's own renderer — bundled into this package, see [Attribution](#attribution) — and embeds it as a sandboxed `<iframe>`, so you get Archify's real viewer, not a re-implementation of it.
 
@@ -115,6 +126,54 @@ archify({
 })
 ```
 
+There is no `width` option. The iframe is always `width: 100%` and fills whatever container your layout gives it. Use `height`/`minHeight`/`maxHeight` to control vertical sizing; control horizontal sizing in your site CSS (see [Layout and width](#layout-and-width) below).
+
+## Layout and width
+
+Diagram width is owned by your page layout, not by `archify()`. Each fence becomes a wrapper (`.archify-diagram` by default, or your custom `className`) containing a full-width iframe — so whatever box that wrapper sits in is the diagram's width.
+
+In a plain Astro project, that usually means your layout's content column — e.g. a `max-width` on `<main>` in your layout component.
+
+In [Starlight](https://starlight.astro.build/), the prose column is controlled by `--sl-content-width` (default ~45rem). Three common approaches:
+
+**Widen all docs content** — add a custom CSS file via Starlight's `customCss` option:
+
+```css
+/* src/styles/custom.css */
+:root {
+  --sl-content-width: 60rem;
+}
+```
+
+**Widen only diagrams** — leave prose at the default and target the embed wrapper:
+
+```css
+/* src/styles/custom.css */
+.archify-diagram {
+  width: calc(100% + 8rem);
+  max-width: 80rem;
+  margin-inline: -4rem;
+}
+```
+
+Tune the values to taste. This is useful when body text should stay narrow but architecture or workflow diagrams need more room.
+
+**Per-page width** — in MDX, wrap a fence in a styled container:
+
+````mdx
+<div class="diagram-wide">
+
+```archify
+{ ... }
+```
+
+</div>
+````
+
+Then style `.diagram-wide` in your custom CSS.
+
+If you push `--sl-content-width` well past ~60rem, Starlight's table-of-contents layout can overflow at some viewport sizes — see [Starlight issue #3513](https://github.com/withastro/starlight/issues/3513) for workarounds.
+
 ## Astro Compatibility
 
 `astro-archify` follows the same markdown-engine detection as [astro-mermaid](https://github.com/joesaby/astro-mermaid) to work across Astro 4 through 7:
@@ -142,7 +201,7 @@ Static builds (`output: 'static'`, the default) are fully supported. Under SSR (
 
 ## Attribution
 
-Archify's own renderer and viewer are vendored into this package at [`vendor/archify/`](./vendor/archify) — copied from [tt-a1i/archify](https://github.com/tt-a1i/archify) (MIT licensed) at commit `12106be`, and used unmodified. See [`vendor/archify/NOTICE.md`](./vendor/archify/NOTICE.md) for exactly what was copied, why, and how to update it.
+Archify's own renderer and viewer are vendored into this package at [`vendor/archify/`](./vendor/archify) — copied from [tt-a1i/archify](https://github.com/tt-a1i/archify) (MIT licensed) at commit `39a2113`, and used unmodified. See [`vendor/archify/NOTICE.md`](./vendor/archify/NOTICE.md) for exactly what was copied, why, and how to update it.
 
 To be clear about the boundary: **everything under `vendor/archify/` is Archify's own code**, doing Archify's own layout, rendering, and the entire interactive viewer. Everything else in this repository — the remark/Sätteri plugin glue that finds `archify` code fences, spawning the renderer as a subprocess, content-addressed caching, serving artifacts from their own URLs, the iframe embedding and its auto-resize bridge, the Astro markdown-engine compatibility shim, the tests, and the demo — is original to `astro-archify` (the markdown-engine detection follows the same pattern used in [astro-mermaid](https://github.com/joesaby/astro-mermaid), also by this author).
 
@@ -150,9 +209,16 @@ To be clear about the boundary: **everything under `vendor/archify/` is Archify'
 
 Archify inlines its entire viewer stylesheet (~4800 lines) into every artifact — the only external stylesheet is a Google Fonts `<link>`, which degrades gracefully if it can't load. Combined with the iframe embedding, this means a diagram always renders pixel-identical to opening the artifact standalone: your site's CSS can never leak into it, and its CSS can never leak into your site.
 
-## Demo
+You can still style the **wrapper** around the iframe from your site CSS — margins, borders, and width (see [Layout and width](#layout-and-width)). The `className` option is there if you need a project-specific hook.
+
+## Demos
+
+| Demo | URL | Source |
+|------|-----|--------|
+| Starlight | [astro-archify-starlight-demo.netlify.app](https://astro-archify-starlight-demo.netlify.app/) | [`starlight-demo/`](./starlight-demo/) |
+| Standalone Astro | [astro-archify-astro-demo.netlify.app](https://astro-archify-astro-demo.netlify.app/) | [`astro-demo/`](./astro-demo/) |
 
-See [`demo/`](./demo) for a minimal Astro project rendering Archify's own architecture, sequence, and workflow examples.
+For Starlight, list `archify()` before `starlight()` in `astro.config.mjs` (see [Integration Order](#integration-order-important)).
 
 ## Supported Diagram Types
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "astro-archify",
-  "version": "0.3.4",
+  "version": "0.3.5",
   "description": "An Astro integration that renders Archify system diagrams (architecture, workflow, sequence, dataflow, lifecycle) from JSON IR code blocks at build time, with Archify's renderer bundled in",
   "type": "module",
   "main": "./astro-archify-integration.js",
@@ -20,6 +20,8 @@
   "keywords": [
     "astro",
     "astro-integration",
+    "withastro",
+    "utility",
     "archify",
     "diagrams",
     "markdown",
@@ -51,13 +53,14 @@
     "test": "vitest",
     "test:ui": "vitest --ui",
     "test:coverage": "vitest --coverage",
-    "update:vendor": "node scripts/update-vendor.mjs"
+    "update:vendor": "node scripts/update-vendor.mjs",
+    "vendor:verify": "node scripts/vendor-verify.mjs"
   },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/joesaby/astro-archify.git"
   },
-  "homepage": "https://github.com/joesaby/astro-archify#readme",
+  "homepage": "https://astro-archify-starlight-demo.netlify.app/",
   "bugs": {
     "url": "https://github.com/joesaby/astro-archify/issues"
   }

package/vendor/archify/NOTICE.md

@@ -3,9 +3,9 @@
 This directory contains source code copied verbatim from [tt-a1i/archify](https://github.com/tt-a1i/archify), used under its MIT license (see `LICENSE` in this directory).
 
 - **Source**: https://github.com/tt-a1i/archify
-- **Pinned commit**: `12106be58b34f94b108ab30f6ac0eb37c16a8f71`
-- **Upstream version**: `2.16.0-dev.0` (per `archify/package.json` at that commit)
-- **Vendored on**: 2026-08-28
+- **Pinned commit**: `39a21139a4661203888049d44e3b8c0da13fa576`
+- **Upstream version**: `2.16.0` (per `archify/package.json` at that commit)
+- **Vendored on**: 2026-08-30
 
 ## What was copied, and why
 
@@ -15,6 +15,8 @@ This directory contains source code copied verbatim from [tt-a1i/archify](https:
 renderers/architecture/render-architecture.mjs
 renderers/architecture/grid.mjs
 renderers/workflow/render-workflow.mjs
+renderers/workflow/workflow-compiler.mjs
+renderers/workflow/workflow-migration-geometry.mjs
 renderers/sequence/render-sequence.mjs
 renderers/dataflow/render-dataflow.mjs
 renderers/lifecycle/render-lifecycle.mjs
@@ -41,8 +43,9 @@ This re-traces the same import graph used to vendor these files originally (see
 ```bash
 git diff vendor/archify/   # review what actually changed upstream
 # update the Pinned commit / Upstream version / Vendored on fields above
-npm test
-cd demo && npm install && npm run build   # rebuild and spot-check a page
+npm run vendor:verify
 ```
 
+`vendor:verify` runs the full test suite and rebuilds both demos. For a quicker check while iterating, `npm test -- --run` is enough.
+
 The script only touches files under `vendor/archify/` — it never edits this file, `git`, or anything outside `vendor/`.

package/vendor/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.16.0-dev.0">
+  <meta name="generator" content="archify 2.16.0">
   <title>[PROJECT NAME] Architecture Diagram</title>
   <script>
     // Resolve the theme before first paint so light-preference users don't

package/vendor/archify/renderers/architecture/render-architecture.mjs

@@ -340,15 +340,6 @@ function validateArchitecture() {
     problems.push(resolvedBoundaryTitles.readabilityProblem);
   }
   const requiresNestedBoundaryMembership = arch.meta?.engineering_profile === 'deployment-ownership';
-  if (arch.schema_version !== 1) problems.push('Architecture files must set "schema_version": 1.');
-  if (arch.diagram_type !== 'architecture') problems.push('Architecture files must set "diagram_type": "architecture".');
-  if (!arch.meta?.title) problems.push('Architecture files must include meta.title.');
-  if (!Array.isArray(arch.components) || arch.components.length < 1) {
-    problems.push('Architecture diagrams need at least one component.');
-  }
-  if (arch.connections !== undefined && !Array.isArray(arch.connections)) problems.push('Architecture "connections" must be an array.');
-  if (arch.boundaries !== undefined && !Array.isArray(arch.boundaries)) problems.push('Architecture "boundaries" must be an array.');
-  if (arch.cards !== undefined && !Array.isArray(arch.cards)) problems.push('Architecture "cards" must be an array.');
   if (components.size !== asArray(arch.components).length) problems.push('Component ids must be unique.');
   if (grid) {
     validateGridPlacement(arch, grid, problems);
@@ -527,13 +518,11 @@ function validateArchitecture() {
   }));
   problems.push(...cleanFlowProblems({
     relations: arch.connections,
-    endpointIds: new Set(components.keys()),
     obstacles: components.values(),
     pathFor,
     diagramType: 'architecture',
     relationCollection: 'connections',
     obstacleKind: 'component',
-    profile: arch.meta?.quality_profile,
     routeHint: 'adjust fromSide/toSide, set route/via, or move the component'
   }));
   problems.push(...cleanCrossingProblems({
@@ -1046,7 +1035,7 @@ function renderLegend() {
 }
 
 function renderSvg() {
-  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(arch.meta, 'architecture diagram')}>
+  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(arch.meta)}>
 ${svgAccessibleText(arch.meta, 'architecture')}
 ${renderDefinitions()}
 

package/vendor/archify/renderers/dataflow/render-dataflow.mjs

@@ -117,17 +117,6 @@ for (const [index, node] of asArray(dataflow.nodes).entries()) {
 
 function validateDataflow() {
   const problems = [];
-  if (dataflow.schema_version !== 1) problems.push('Data-flow files must set "schema_version": 1.');
-  if (dataflow.diagram_type !== 'dataflow') problems.push('Data-flow files must set "diagram_type": "dataflow".');
-  if (!dataflow.meta?.title) problems.push('Data-flow files must include meta.title.');
-  if (!Array.isArray(dataflow.stages) || dataflow.stages.length < 2) {
-    problems.push('Data-flow diagrams need at least two stages.');
-  }
-  if (!Array.isArray(dataflow.nodes) || dataflow.nodes.length < 2) {
-    problems.push('Data-flow diagrams need at least two nodes.');
-  }
-  if (!Array.isArray(dataflow.flows)) problems.push('Data-flow diagrams must include a flows array.');
-  if (dataflow.cards !== undefined && !Array.isArray(dataflow.cards)) problems.push('Data-flow "cards" must be an array.');
   if (nodes.size !== asArray(dataflow.nodes).length) problems.push('Node ids must be unique.');
 
   const stageCount = asArray(dataflow.stages).length;
@@ -215,13 +204,11 @@ function validateDataflow() {
   }));
   problems.push(...cleanFlowProblems({
     relations: dataflow.flows,
-    endpointIds: new Set(nodes.keys()),
     obstacles: nodes.values(),
     pathFor,
     diagramType: 'dataflow',
     relationCollection: 'flows',
     obstacleKind: 'node',
-    profile: dataflow.meta?.quality_profile,
     routeHint: 'adjust fromSide/toSide, set route/via or channelX/channelY, or move the node to another stage/row'
   }));
   problems.push(...cleanCrossingProblems({
@@ -355,7 +342,21 @@ function pathFor(flow) {
   const { fromSide, toSide } = flowSides(flow);
   const start = ports?.from || anchor(from, fromSide);
   const end = ports?.to || anchor(to, toSide);
-  const points = [start, ...routeVia(flow, from, to, start, end), end];
+  // Drop consecutive duplicate points so a purely vertical (or horizontal)
+  // auto-route never emits a zero-length final segment — SVG derives
+  // marker-end orientation from the last segment, and a degenerate segment
+  // leaves the arrowhead angle undefined (see #169).
+  const rawPoints = [start, ...routeVia(flow, from, to, start, end), end];
+  const points = [];
+  for (const p of rawPoints) {
+    const prev = points.at(-1);
+    if (!prev || Math.abs(p[0] - prev[0]) > 0.0001 || Math.abs(p[1] - prev[1]) > 0.0001) {
+      points.push(p);
+    }
+  }
+  // Guard against an all-degenerate route (e.g. start === end): keep both
+  // endpoints so the path is still well-formed even if the marker is hidden.
+  if (points.length < 2) points.push(end);
   const routed = { d: polylinePath(points), points };
   pathCache.set(flow, routed);
   return routed;
@@ -447,7 +448,7 @@ function renderLegend() {
 }
 
 function renderSvg() {
-  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(dataflow.meta, 'data-flow diagram')}>
+  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(dataflow.meta)}>
 ${svgAccessibleText(dataflow.meta, 'dataflow')}
 ${renderDefinitions()}
 

package/vendor/archify/renderers/lifecycle/render-lifecycle.mjs

@@ -140,13 +140,6 @@ for (const [index, state] of asArray(lifecycle.states).entries()) {
 
 function validateLifecycle() {
   const problems = [];
-  if (lifecycle.schema_version !== 1) problems.push('Lifecycle files must set "schema_version": 1.');
-  if (lifecycle.diagram_type !== 'lifecycle') problems.push('Lifecycle files must set "diagram_type": "lifecycle".');
-  if (!lifecycle.meta?.title) problems.push('Lifecycle files must include meta.title.');
-  if (!Array.isArray(lifecycle.lanes) || lifecycle.lanes.length < 1) problems.push('Lifecycle diagrams need at least one lane.');
-  if (!Array.isArray(lifecycle.states) || lifecycle.states.length < 2) problems.push('Lifecycle diagrams need at least two states.');
-  if (!Array.isArray(lifecycle.transitions)) problems.push('Lifecycle diagrams must include a transitions array.');
-  if (lifecycle.cards !== undefined && !Array.isArray(lifecycle.cards)) problems.push('Lifecycle "cards" must be an array.');
   if (states.size !== asArray(lifecycle.states).length) problems.push('State ids must be unique.');
 
   // The three bands are fixed at y=112/264/436. Preserve the original
@@ -246,13 +239,11 @@ function validateLifecycle() {
   }));
   problems.push(...cleanFlowProblems({
     relations: lifecycle.transitions,
-    endpointIds: new Set(states.keys()),
     obstacles: states.values(),
     pathFor,
     diagramType: 'lifecycle',
     relationCollection: 'transitions',
     obstacleKind: 'state',
-    profile: lifecycle.meta?.quality_profile,
     routeHint: 'adjust fromSide/toSide, set route/via or channelX/channelY, or move the state with col/yOffset'
   }));
   problems.push(...cleanCrossingProblems({
@@ -532,7 +523,7 @@ function renderLifecycleRail() {
 }
 
 function renderSvg() {
-  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(lifecycle.meta, 'lifecycle diagram')}>
+  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(lifecycle.meta)}>
 ${svgAccessibleText(lifecycle.meta, 'lifecycle')}
 ${renderDefinitions()}
 

package/vendor/archify/renderers/sequence/render-sequence.mjs

@@ -134,20 +134,7 @@ function messagePath(message) {
 
 function validateSequence() {
   const problems = [];
-  if (sequence.schema_version !== 1) problems.push('Sequence files must set "schema_version": 1.');
-  if (sequence.diagram_type !== 'sequence') problems.push('Sequence files must set "diagram_type": "sequence".');
-  if (!sequence.meta?.title) problems.push('Sequence files must include meta.title.');
-  if (!Array.isArray(sequence.participants) || sequence.participants.length < 2) {
-    problems.push('Sequence diagrams need at least two participants.');
-  }
   if (participants.size !== asArray(sequence.participants).length) problems.push('Participant ids must be unique.');
-  if (!Array.isArray(sequence.messages) || sequence.messages.length < 1) {
-    problems.push('Sequence diagrams need at least one message.');
-  }
-  if (sequence.cards !== undefined && !Array.isArray(sequence.cards)) problems.push('Sequence "cards" must be an array.');
-  for (const arr of ['segments', 'activations']) {
-    if (sequence[arr] !== undefined && !Array.isArray(sequence[arr])) problems.push(`Sequence "${arr}" must be an array.`);
-  }
 
   if (layout.lifelineBottom - layout.lifelineTop < 120) {
     problems.push(`viewBox height ${viewBox[1]} leaves under 120px of timeline — set meta.viewBox[1] to at least ${layout.lifelineTop + 120 + 65}.`);
@@ -188,13 +175,11 @@ function validateSequence() {
   // segment bands remain intentional pass-through geometry and are excluded.
   problems.push(...cleanFlowProblems({
     relations: sequence.messages,
-    endpointIds: new Set(participants.keys()),
     obstacles: participants.values(),
     pathFor: messagePath,
     diagramType: 'sequence',
     relationCollection: 'messages',
     obstacleKind: 'participant header',
-    profile: sequence.meta?.quality_profile,
     clearance: 0,
     routeHint: 'move the message y below the participant headers or reorder participants'
   }));
@@ -427,7 +412,7 @@ function renderLegend() {
 
 function renderSvg() {
   const participantList = [...participants.values()];
-  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(sequence.meta, 'sequence diagram')}>
+  return `      <svg viewBox="0 0 ${viewBox[0]} ${viewBox[1]}" ${svgRootAttrs(sequence.meta)}>
 ${svgAccessibleText(sequence.meta, 'sequence')}
 ${renderDefinitions()}
 

package/vendor/archify/renderers/shared/cli.mjs

@@ -26,8 +26,6 @@ export function loadDiagram({ rendererDir, diagramType, defaultExample, argv = p
   validateEngineeringProfile(diagramType, diagram);
   const sourceEvidence = verifyRepositoryEvidence(diagramType, diagram, process.env.ARCHIFY_REPO_ROOT);
   const template = fs.readFileSync(path.join(skillRoot, 'assets/template.html'), 'utf8');
-  // Optional chaining: in degraded mode (no ajv) malformed input must still
-  // reach the renderer's friendly layout checks instead of crashing here.
   const outputRequest = {
     requestedOutput: argv[3],
     authoredOutput: diagram.meta?.output,
@@ -148,7 +146,7 @@ export function validateGuidedViews(diagramType, diagram) {
 }
 
 // Accessible name for the generated diagram SVG.
-export function svgRootAttrs(meta, kind) {
+export function svgRootAttrs(meta) {
   const animation = meta.animation === 'trace' ? ' data-animation="trace"' : '';
   const preset = ` data-preset="${esc(meta.visual_preset || 'classic')}"`;
   const engineeringProfile = meta.engineering_profile

package/vendor/archify/renderers/shared/diagnostics.mjs

@@ -5,6 +5,7 @@ const DIAGNOSTIC_MODE = process.env.ARCHIFY_DIAGNOSTIC_FORMAT === 'json';
 const recorded = [];
 const recordedMessages = new Set();
 const boundaryKey = Symbol.for('archify.renderer-diagnostic-boundary');
+let recordingSuppressionDepth = 0;
 
 function plainObject(value) {
   if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
@@ -22,17 +23,29 @@ function normalizedDiagnostic(diagnostic) {
     supportedFixes: Array.isArray(diagnostic?.supportedFixes)
       ? [...new Set(diagnostic.supportedFixes.map((fix) => String(fix).trim()).filter(Boolean))]
       : [],
+    ...(Array.isArray(diagnostic?.suppresses) ? {
+      suppresses: [...new Set(diagnostic.suppresses.map((code) => String(code).trim()).filter(Boolean))],
+    } : {}),
   };
 }
 
 export function recordDiagnostic(diagnostic) {
-  if (!DIAGNOSTIC_MODE) return;
+  if (!DIAGNOSTIC_MODE || recordingSuppressionDepth > 0) return;
   const normalized = normalizedDiagnostic(diagnostic);
   if (recordedMessages.has(normalized.message)) return;
   recordedMessages.add(normalized.message);
   recorded.push(normalized);
 }
 
+export function withDiagnosticRecordingSuppressed(callback) {
+  recordingSuppressionDepth += 1;
+  try {
+    return callback();
+  } finally {
+    recordingSuppressionDepth -= 1;
+  }
+}
+
 export function throwDiagnosticError(message, diagnostics) {
   for (const diagnostic of diagnostics || []) recordDiagnostic(diagnostic);
   const error = new Error(message);
@@ -42,17 +55,15 @@ export function throwDiagnosticError(message, diagnostics) {
 
 export function throwDiagnosticProblems(prefix, problems, { code = 'layout/constraint', subject = {} } = {}) {
   const messages = (problems || []).map((problem) => String(problem));
-  for (const message of messages) {
-    recordDiagnostic({
+  const diagnostics = messages.map((message) => normalizedDiagnostic({
       code,
       severity: 'error',
       message,
       subject,
       evidence: {},
       supportedFixes: [],
-    });
-  }
-  throw new Error(`${prefix}:\n- ${messages.join('\n- ')}`);
+    }));
+  throwDiagnosticError(`${prefix}:\n- ${messages.join('\n- ')}`, diagnostics);
 }
 
 function fallbackDiagnostic(error) {