How Archify Preview Handles Failures: A Deep Dive into Error Recovery

Archify handles preview failures by monitoring iframe load events, checking for a data-preview-active attribute, stripping stale preview data attributes, and replacing the failed preview with a fallback error message while keeping the theme toggle functional.

The Archify diagramming tool renders interactive previews inside sandboxed iframes. When a preview fails to load—whether due to network errors, server failures, or malformed embed content—the system implements a multi-layered recovery mechanism that preserves UI stability and user control.

Iframe Load Monitoring and Failure Detection

Archify's preview system relies on a load-event listener that inspects the embedded document for the data-preview-active attribute. This attribute is set by successfully loaded artifacts to signal that the preview initialized correctly.

In scripts/build-gallery.mjs, the build script generates iframe tags with the embed query string:

<iframe
  src="https://example.com/artifact.json?embed=1&theme=dark"
  data-src-base="https://example.com/artifact.json"
  title="Diagram preview"
  loading="lazy">
</iframe>

When the iframe fires its load event, the runtime code in generated/maka-regenerated.workflow.html checks for the expected attribute:

function checkPreview(frame) {
  const doc = frame.contentDocument;
  // Failure detected: embedded document missing preview-active flag
  if (!doc || !doc.querySelector('[data-preview-active]')) {
    handlePreviewFailure(frame, doc);
  }
}

Error-State Cleanup to Prevent Corruption

Before displaying any fallback UI, Archify strips all preview-specific data attributes from the diagram DOM. This prevents stale state from corrupting subsequent render attempts.

The cleanup occurs in the attribute-stripping loops around lines 6070–6084 of generated/maka-regenerated.workflow.html. These loops remove:

• data-preview-active
• data-legend-preview-active
• data-relationship-preview-active

// Cleanup stale preview attributes from the cloned diagram DOM
doc.querySelectorAll(
  '[data-legend-preview-active],[data-relationship-preview-active]'
).forEach(el => {
  el.removeAttribute('data-legend-preview-active');
  el.removeAttribute('data-relationship-preview-active');
});

This sanitization ensures that retry attempts or theme switches start from a clean state.

Fallback UI Replacement

Once cleanup completes, Archify replaces the iframe container with a minimal error message:

const container = frame.parentElement;
container.innerHTML = '<div class="preview-error">Preview unavailable</div>';

The .preview-error class is defined in scripts/gallery-template.html to match the gallery's visual design. This approach keeps the layout intact while clearly communicating the failure to users.

Theme Preservation Across Failures

A key resilience feature: the preview-theme toggle (#preview-theme) remains fully operational even after a preview fails. The toggle stores the current theme value and regenerates the iframe src when clicked:

let previewTheme = 'dark';
document.getElementById('preview-theme').addEventListener('click', () => {
  previewTheme = previewTheme === 'dark' ? 'light' : 'dark';
  const frame = document.querySelector('.preview-shell iframe');
  // Re-issue request with new theme—failure handling repeats automatically
  frame.src = `${frame.dataset.srcBase}?embed=1&theme=${previewTheme}`;
});

This ensures users can retry with a different theme or recover from transient failures without page reloads.

Graceful Degradation Through Isolation

The iframe-based architecture provides critical fault isolation. JavaScript errors, infinite loops, or crashes inside the embedded artifact:

• Cannot access the host page's DOM
• Cannot leak memory or state to other previews
• Trigger the failure detection path without disrupting the gallery

Other previews on the same page continue operating normally when one fails.

Key Implementation Files

File	Responsibility
scripts/gallery-template.html	Defines preview containers, theme toggle markup, and .preview-error styling
scripts/build-gallery.mjs	Generates iframe tags with ?embed=1&theme= URLs and injects theme logic
generated/maka-regenerated.workflow.html	Contains runtime viewer code for failure detection, attribute cleanup (lines 6070–6084), and fallback UI insertion

Summary

• Archify preview failure handling starts with iframe load monitoring and data-preview-active attribute validation
• Stale state prevention through systematic removal of preview-specific data attributes before any fallback rendering
• User-friendly fallback UI replaces failed previews without breaking page layout
• Persistent theme controls allow recovery attempts and theme experimentation even after failures
• Iframe sandboxing ensures one preview's failure never impacts the host page or sibling previews

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