# How Share Cards Work in Archify: A Complete Technical Guide

> Discover how Archify Share Cards work. Learn about this deterministic export feature that creates PNG images of your diagrams while preserving relationships and state. Get the technical guide.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: deep-dive
- Published: 2026-08-14

---

**Archify's Share Cards are deterministic export features that render 1200 × 630 PNG images of architecture diagrams with preserved relationships as dimmed backgrounds, using static data attributes and never affecting canonical diagram state.**

Share Cards in **tt-a1i/archify** provide a reliable way to generate visual exports for documentation, social media, and review artifacts. This feature creates reproducible images while guaranteeing that no live viewer state leaks into the final export. The system supports three variants—generic Share Card, Route Share Card, and Reach Share Card—each designed for specific workflow needs.

## Share Card Variants and UI Integration

The Archify viewer integrates Share Cards directly into its export toolbar. Understanding these three variants helps you choose the right export for your use case.

### Generic Share Card

The baseline **Share Card** button uses `data-format="share-card"` and creates a standard 1200 × 630 PNG of the current diagram view. This variant is always available in the toolbar.

### Route Share Card

The **Route Share Card** (`data-action="route-share-card"`) becomes enabled only after a successful **Route Probe** query. It captures the exact ordered node list from the resolved route, making it ideal for documenting specific dependency paths through your architecture.

### Reach Share Card

The **Reach Share Card** (`data-action="reach-share-card"`) activates following a completed **Authored Reachability** query. It re-uses the already-resolved upstream/downstream node set, perfect for illustrating dependency scope in reviews.

These button configurations appear in the viewer HTML. In [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) (lines 4813-4816), you'll find the toolbar markup that governs when each variant becomes available:

```html
<!-- Generic share card -- available always -->
<button data-format="share-card">Share Card</button>

<!-- Route variant -- enabled after route probe resolution -->
<button data-action="route-share-card" hidden>Route Share Card</button>

<!-- Reach variant -- enabled after reachability query -->
<button data-action="reach-share-card" hidden>Reach Share Card</button>

```

## The Static Decoration Contract

Share Cards enforce a strict **static decoration contract** that guarantees deterministic output. When you trigger an export, Archify performs these operations:

1. **Clone creation**: A fresh copy of the diagram is created
2. **Static attribute injection**: Only `data-share-route-*` or `data-share-reach-*` attributes are applied
3. **Live state exclusion**: Camera position, focus lens, story progress, and animations are deliberately omitted

This contract, documented in [`archify/references/viewer-runtime.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md), ensures that Share Cards are **download-only artifacts** that never become canonical outputs. The same diagram state always produces identical pixel output—critical for reproducible documentation.

## Export Receipt and Non-Canonical Status

Every Share Card export generates a **receipt record** that explicitly marks the export as non-canonical. According to the [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) entry for Route Share Card exports, this receipt structure includes:

```json
{
  "format": "share-card",
  "variant": "route",
  "canonical": false,
  "width": 1200,
  "height": 630,
  "routeStateClean": true
}

```

Key receipt behaviors:

- **Non-canonical flag**: The `canonical: false` field prevents Share Cards from affecting downstream CI or validation pipelines
- **Temporary storage**: Receipts are cleared on the next ordinary export
- **State verification**: `routeStateClean` confirms no runtime contamination occurred

The delivery contract in [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md) defines how these receipts integrate with Archify's broader export tracking system.

## Error Handling and Clipboard Integration

Failed Share Card exports surface through the **`data-last-export-error-format`** attribute. When an export fails—due to stale route data or unreachable nodes—the UI sets this attribute to `"share-card"` and displays an appropriate error message.

For rapid sharing, the **Copy Share Card** feature (`data-action="copy-share-card"`) writes PNG data directly to the system clipboard, bypassing the download step:

```js
// Enable copy-to-clipboard for immediate sharing
const copyBtn = menu.querySelector('button[data-action="copy-share-card"]');
copyBtn.addEventListener('click', async () => {
  const pngBlob = await renderShareCard(variant);
  await navigator.clipboard.write([
    new ClipboardItem({ 'image/png': pngBlob })
  ]);
});

```

## Programmatic Share Card Export

Embed Archify in your own applications using the exposed `archifyExport` helper:

```js
// Generic share card with download
await archifyExport({
  format: 'share-card',
  width: 1200,
  height: 630,
  download: true
});

// Route-specific variant
await archifyExport({
  format: 'share-card',
  variant: 'route',
  width: 1200,
  height: 630,
  download: true
});

// Reachability variant
await archifyExport({
  format: 'share-card',
  variant: 'reach',
  width: 1200,
  height: 630,
  download: true
});

```

The core rendering logic resides in `export.mjs` (referenced in the viewer HTML), while [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) contains the production implementation handling PNG generation, receipt recording, and error states.

## Key Source Files for Share Card Implementation

| File | Purpose |
|------|---------|
| [`archify/references/viewer-runtime.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md) | Defines export contracts, variant flags, and `data-share-*` decoration specifications |
| [`archify/references/delivery-contract.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/delivery-contract.md) | Documents receipt model and non-canonical artifact handling |
| [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html) (lines 4813-4816) | Toolbar button markup enabling Share Card variants |
| [`CHANGELOG.md`](https://github.com/tt-a1i/archify/blob/main/CHANGELOG.md) (Route Share Card section) | Feature rollout documentation and receipt field specifications |
| [`experiments/mco-showcase/mco-runtime.html`](https://github.com/tt-a1i/archify/blob/main/experiments/mco-showcase/mco-runtime.html) | Production JavaScript for PNG rendering, receipt recording, and error handling |

## Summary

- **Share Cards** produce deterministic 1200 × 630 PNG exports through three variants: generic, route, and reach
- **Static decoration contract** guarantees no live viewer state contamination—only `data-share-route-*` or `data-share-reach-*` attributes are applied to cloned diagrams
- **Non-canonical receipts** (`canonical: false`) prevent Share Cards from affecting CI or validation pipelines
- **Error handling** surfaces through `data-last-export-error-format` attributes when routes are stale or nodes unreachable
- **Clipboard integration** enables immediate sharing without file system interaction

## Frequently Asked Questions

### What makes Share Cards deterministic in Archify?

Share Cards are deterministic because they clone the diagram and apply only **static data attributes** (`data-share-route-*` or `data-share-reach-*`). Camera position, animations, focus lens, and story progress are explicitly excluded. The same input always produces identical pixel output, as enforced by the static decoration contract in [`archify/references/viewer-runtime.md`](https://github.com/tt-a1i/archify/blob/main/archify/references/viewer-runtime.md).

### When do Route Share Card and Reach Share Card buttons become available?

These variants are **initially hidden** and only enable after specific query completions. Route Share Card appears after a successful Route Probe resolves an ordered node path. Reach Share Card activates following a completed Authored Reachability query with resolved upstream/downstream nodes. The button state logic resides in [`examples/web-app.html`](https://github.com/tt-a1i/archify/blob/main/examples/web-app.html).

### Why are Share Card exports marked as non-canonical?

The `canonical: false` flag in export receipts ensures Share Cards remain **documentation artifacts only**. They never substitute for canonical diagram outputs in CI pipelines, validation workflows, or downstream automation. Receipts are also temporary—cleared on the next ordinary export—reinforcing their auxiliary role.

### Can Share Cards be generated programmatically without the UI?

Yes. Archify exposes the `archifyExport` global helper for scripted exports. Pass `format: 'share-card'` with optional `variant: 'route'` or `variant: 'reach'`. The function handles cloning, decoration, PNG rendering, receipt generation, and optional download triggering within a single async call.