astro-archify 0.3.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Jose Sebastian
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,169 @@
+# 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.
+
+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.
+
+This is a different rendering model than diagram libraries like Mermaid: there is no client-side JS bundle to ship, because Archify does its layout work in Node during your Astro build, not in the browser.
+
+There's no separate CLI to install — `npm install astro-archify` is everything you need.
+
+## Installation
+
+```bash
+npm install astro-archify
+```
+
+## Quick Start
+
+```js
+// astro.config.mjs
+import { defineConfig } from 'astro/config';
+import archify from 'astro-archify';
+
+export default defineConfig({
+  integrations: [archify()]
+});
+```
+
+Then, in markdown or MDX:
+
+````markdown
+```archify
+{
+  "schema_version": 1,
+  "diagram_type": "architecture",
+  "meta": { "title": "Sample Web App" },
+  "components": [
+    { "id": "api", "type": "backend", "label": "API", "pos": [40, 40], "size": [120, 60] },
+    { "id": "db", "type": "database", "label": "Database", "pos": [260, 40], "size": [120, 60] }
+  ],
+  "connections": [
+    { "from": "api", "to": "db", "label": "SQL" }
+  ]
+}
+```
+````
+
+The `diagram_type` field in the IR (`architecture`, `workflow`, `sequence`, `dataflow`, or `lifecycle`) selects the renderer. You can also make the type explicit in the fence's language string instead of relying on the JSON body:
+
+````markdown
+```archify:sequence
+{ ... }
+```
+````
+
+## Integration Order (Important!)
+
+When using with Starlight or other markdown-processing integrations, place archify **first**:
+
+```js
+import { defineConfig } from 'astro/config';
+import starlight from '@astrojs/starlight';
+import archify from 'astro-archify';
+
+export default defineConfig({
+  integrations: [
+    archify(), // ⚠️ Must come BEFORE starlight
+    starlight({ title: 'My Docs' })
+  ]
+});
+```
+
+## Configuration
+
+```js
+archify({
+  // Advanced: use a different Archify checkout instead of the copy bundled
+  // with this package. Must be a directory laid out like Archify's own
+  // package root (containing renderers/<type>/render-<type>.mjs and
+  // assets/template.html). Most projects never need this.
+  rendererRoot: '/path/to/a/newer/archify/checkout',
+
+  // Archify quality profile: 'standard' | 'showcase'
+  quality: 'showcase',
+
+  // Fail the build instead of rendering a visible inline error block
+  strict: false,
+
+  // Initial iframe height in px, shown before the artifact reports its
+  // real content height
+  height: 480,
+
+  // The iframe never shrinks below this height (defaults to `height`)
+  minHeight: 480,
+
+  // The iframe never grows past this height, even for a very tall diagram
+  maxHeight: 4000,
+
+  // Wrapper class name
+  className: 'archify-diagram',
+
+  // iframe sandbox attribute
+  sandbox: 'allow-scripts allow-popups allow-downloads',
+
+  // iframe `allow` (Permissions Policy) attribute — needed for the
+  // viewer's clipboard-copy export and fullscreen presentation stage
+  allow: 'clipboard-write; fullscreen',
+
+  // Subdirectory diagram artifacts are served from, e.g. /_archify/<id>.html.
+  // Change only if it collides with existing content.
+  outDir: '_archify',
+
+  // Render timeout, in milliseconds
+  timeout: 30000
+})
+```
+
+## 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:
+
+| Astro version | Markdown engine | How Archify hooks in |
+|---------------|-----------------|-----------------------|
+| 7+ | Sätteri (`@astrojs/markdown-satteri`, the new default) | a Sätteri **mdast plugin** |
+| 6.4 – 6.x | `unified()` processor | a remark plugin via `markdown.processor` |
+| < 6.4 | legacy pipeline | `markdown.remarkPlugins` |
+
+## How It Works
+
+1. **Build time**: for each `archify` code fence, the JSON IR is written to a temp file and rendered by running Archify's own renderer script for that diagram type — `node vendor/archify/renderers/<type>/render-<type>.mjs <input.json> <output.html>` — as a subprocess. That's a real requirement, not just caution: Archify's renderer scripts call `process.exit()` directly on both success and failure, so they have to run out-of-process — importing them directly into the Astro build would let one bad diagram take down the whole build.
+2. The resulting self-contained HTML artifact is content-addressed (hashed from its diagram type, quality profile, and JSON source) and cached in memory under that id — so the same diagram appearing on multiple pages, or an unchanged diagram across incremental rebuilds, only renders once.
+3. Each artifact is served from its own real URL, `/_archify/<id>.html` by default — written to the final output directory on `astro:build:done` (which runs after Astro's own build, including copying `publicDir`, so this can't race or be clobbered), and served straight from memory by dev middleware in `astro dev`. The code fence is replaced with a sandboxed `<iframe src="/_archify/<id>.html">` plus a plain "Open full view ↗" link to that same URL.
+4. **Runtime**: the browser loads Archify's own artifact directly from that URL, inside the iframe — including its full viewer: guide overlay, node finder, guided story/chapter navigation, semantic passport panel, presentation stage, and PNG/JPEG/SVG/WebM exports. This integration doesn't reimplement any of that, and doesn't inline or re-encode it into the page either — it's a normal, separately-cacheable HTTP response.
+
+Archify's viewer assumes it owns the full browser viewport, so a fixed-size box would clip it badly. To avoid that, a small bridge script is appended to each artifact (the only modification this package makes to Archify's output) that reports its real content height to the parent page — on load and via `ResizeObserver` as the reader interacts with the viewer (opening a panel, entering presentation mode, etc.) — and the iframe grows or shrinks to match, bounded by `minHeight`/`maxHeight`.
+
+If a diagram fails to render (invalid JSON, an unknown `diagram_type`, or a schema/composition error from Archify itself), a visible inline error block is rendered in its place — using Archify's own structured diagnostic message and suggested fix when it provides one — and a build warning is logged. Set `strict: true` to fail the build instead.
+
+### A note on SSR
+
+Static builds (`output: 'static'`, the default) are fully supported. Under SSR (`output: 'server'`/`'hybrid'`), `astro:build:done`'s output directory is the client asset directory, which most adapters already serve as static files — so this should generally still work, but it's adapter-dependent and less thoroughly tested than the static case.
+
+## 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.
+
+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).
+
+## Styling
+
+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
+
+See [`demo/`](./demo) for a minimal Astro project rendering Archify's own architecture, sequence, and workflow examples.
+
+## Supported Diagram Types
+
+- Architecture
+- Workflow
+- Sequence
+- Data flow
+- Lifecycle
+
+See the [Archify repository](https://github.com/tt-a1i/archify) for the full JSON IR schemas and authoring guide.
+
+## License
+
+MIT © [Jose Sebastian](https://github.com/joesaby)

package/astro-archify-integration.d.ts

@@ -0,0 +1,100 @@
+import type { AstroIntegration } from 'astro';
+
+export interface AstroArchifyOptions {
+  /**
+   * Advanced: path to an Archify package root to use instead of the copy
+   * vendored into this package (see vendor/archify/NOTICE.md). Must be a
+   * directory laid out like Archify's own package root — containing
+   * `renderers/<type>/render-<type>.mjs` and `assets/template.html` for
+   * each diagram type.
+   */
+  rendererRoot?: string;
+
+  /**
+   * Archify rendering quality profile, forwarded as `ARCHIFY_QUALITY_PROFILE`.
+   */
+  quality?: 'standard' | 'showcase';
+
+  /**
+   * Fail the Astro build when a diagram fails to render, instead of
+   * embedding a visible inline error block.
+   * @default false
+   */
+  strict?: boolean;
+
+  /**
+   * Initial height of the diagram's iframe, shown before the artifact
+   * reports its real content height (see `minHeight`/`maxHeight`). A
+   * number is treated as pixels.
+   * @default 480
+   */
+  height?: number;
+
+  /**
+   * The iframe never shrinks below this height once auto-resized.
+   * @default the value of `height`
+   */
+  minHeight?: number;
+
+  /**
+   * The iframe never grows past this height even if Archify's viewer
+   * (guide overlay, story mode, semantic passport panel, etc.) reports a
+   * taller content size.
+   * @default 4000
+   */
+  maxHeight?: number;
+
+  /**
+   * CSS class name applied to the diagram wrapper element.
+   * @default 'archify-diagram'
+   */
+  className?: string;
+
+  /**
+   * `sandbox` attribute applied to the diagram's iframe.
+   * @default 'allow-scripts allow-popups allow-downloads'
+   */
+  sandbox?: string;
+
+  /**
+   * `allow` (Permissions Policy) attribute applied to the diagram's
+   * iframe, needed for the viewer's clipboard-copy export and fullscreen
+   * presentation stage to work inside the embed.
+   * @default 'clipboard-write; fullscreen'
+   */
+  allow?: string;
+
+  /**
+   * Subdirectory (under the site root, respecting a configured `base`)
+   * that rendered diagram artifacts are served from — e.g. `/_archify/<id>.html`.
+   * Change this only if it collides with existing content.
+   * @default '_archify'
+   */
+  outDir?: string;
+
+  /**
+   * Render timeout in milliseconds.
+   * @default 30000
+   */
+  timeout?: number;
+}
+
+/**
+ * Astro integration for rendering Archify system diagrams (architecture,
+ * workflow, sequence, dataflow, lifecycle) from JSON IR code fences.
+ *
+ * @example
+ * ```js
+ * import { defineConfig } from 'astro/config';
+ * import archify from 'astro-archify';
+ *
+ * export default defineConfig({
+ *   integrations: [
+ *     archify({
+ *       quality: 'showcase'
+ *     })
+ *   ]
+ * });
+ * ```
+ */
+export default function astroArchify(options?: AstroArchifyOptions): AstroIntegration;

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "astro-archify",
+  "version": "0.3.4",
+  "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",
+  "types": "./astro-archify-integration.d.ts",
+  "exports": {
+    ".": {
+      "import": "./astro-archify-integration.js",
+      "types": "./astro-archify-integration.d.ts"
+    }
+  },
+  "files": [
+    "astro-archify-integration.js",
+    "astro-archify-integration.d.ts",
+    "vendor/archify",
+    "README.md"
+  ],
+  "keywords": [
+    "astro",
+    "astro-integration",
+    "archify",
+    "diagrams",
+    "markdown",
+    "architecture",
+    "system-design",
+    "sequence-diagram"
+  ],
+  "author": "Jose Sebastian",
+  "license": "MIT",
+  "peerDependencies": {
+    "astro": ">=4"
+  },
+  "dependencies": {
+    "unist-util-visit": "^5.0.0"
+  },
+  "devDependencies": {
+    "@astrojs/markdown-satteri": "^0.3.2",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/github": "^11.0.6",
+    "@semantic-release/npm": "^12.0.2",
+    "astro": "^6.4.6",
+    "remark-parse": "^11.0.0",
+    "semantic-release": "^24.2.9",
+    "unified": "^11.0.5",
+    "vitest": "^4.1.8"
+  },
+  "scripts": {
+    "test": "vitest",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest --coverage",
+    "update:vendor": "node scripts/update-vendor.mjs"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/joesaby/astro-archify.git"
+  },
+  "homepage": "https://github.com/joesaby/astro-archify#readme",
+  "bugs": {
+    "url": "https://github.com/joesaby/astro-archify/issues"
+  }
+}

package/vendor/archify/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 tt-a1i (Archify)
+Copyright (c) 2025 Cocoon AI (original "architecture-diagram-generator")
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/vendor/archify/NOTICE.md

@@ -0,0 +1,48 @@
+# Vendored from Archify
+
+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
+
+## What was copied, and why
+
+`astro-archify` needs Archify's diagram renderers (JSON IR → self-contained HTML with inline SVG and its interactive viewer) to work without requiring a separately-installed `archify` CLI on `PATH`. The files below are the exact, minimal set those five renderers depend on, found by statically tracing their import graph — nothing else from the upstream repository (its CLI commands other than `render`, its architecture-compare/preview/visual-check tooling, its schema files, its scripts, its examples, its agent-skill prompt) is included or needed.
+
+```
+renderers/architecture/render-architecture.mjs
+renderers/architecture/grid.mjs
+renderers/workflow/render-workflow.mjs
+renderers/sequence/render-sequence.mjs
+renderers/dataflow/render-dataflow.mjs
+renderers/lifecycle/render-lifecycle.mjs
+renderers/shared/*.mjs        (16 files: layout, geometry, text-fit, legend,
+                                brand marks, i18n, diagnostics, validation, etc.)
+assets/template.html          (the viewer: CSS + interactive runtime JS)
+```
+
+These files are otherwise **unmodified** from upstream. `astro-archify`'s own code (in the repository root — `astro-archify-integration.js` and friends) invokes them exactly as Archify's own CLI does internally: as a Node subprocess, with the same `argv`/environment-variable contract (`node render-<type>.mjs <input.json> <output.html>`, `ARCHIFY_QUALITY_PROFILE`, `ARCHIFY_DIAGNOSTIC_FORMAT=json`). None of astro-archify's own rendering, embedding, resize, or Astro-integration logic is derived from Archify's code — see the root `README.md`'s "Attribution" section for that boundary.
+
+Confirmed at vendoring time: this file set has **zero npm runtime dependencies** — only Node.js builtins (`fs`, `path`, `crypto`, `child_process`, `url`, `dns/promises`, `http`, `https`, `net`). Archify's own `ajv`/`parse5`/`saxes`/`simple-icons` devDependencies are build-time-only (schema/brand-mark codegen) and are not required to run these files.
+
+## Keeping this in sync (patching)
+
+This is a point-in-time copy, not a live dependency — upstream fixes and features do not arrive automatically. To pull in a newer Archify:
+
+```bash
+git clone https://github.com/tt-a1i/archify /tmp/archify-latest
+npm run update:vendor -- /tmp/archify-latest
+```
+
+This re-traces the same import graph used to vendor these files originally (see `scripts/update-vendor.mjs`), overwrites this directory with whatever changed, and prints a summary of what's new or changed plus the exact "Pinned commit" / "Upstream version" values to put in this file. Then:
+
+```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
+```
+
+The script only touches files under `vendor/archify/` — it never edits this file, `git`, or anything outside `vendor/`.