How Share Cards Work in Archify: A Complete Technical Guide

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 (lines 4813-4816), you'll find the toolbar markup that governs when each variant becomes available:

<!-- 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, 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 entry for Route Share Card exports, this receipt structure includes:

{
  "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 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:

// 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:

// 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 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	Defines export contracts, variant flags, and data-share-* decoration specifications
archify/references/delivery-contract.md	Documents receipt model and non-canonical artifact handling
examples/web-app.html (lines 4813-4816)	Toolbar button markup enabling Share Card variants
CHANGELOG.md (Route Share Card section)	Feature rollout documentation and receipt field specifications
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.

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.

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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}