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

> Discover how Archify preview handles failures. Learn about its robust error recovery, fallback messages, and seamless theme toggle functionality for a smooth user experience.

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

---

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

```html
<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`](https://github.com/tt-a1i/archify/blob/main/generated/maka-regenerated.workflow.html) checks for the expected attribute:

```js
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`](https://github.com/tt-a1i/archify/blob/main/generated/maka-regenerated.workflow.html). These loops remove:

- `data-preview-active`
- `data-legend-preview-active`
- `data-relationship-preview-active`

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

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

```

The `.preview-error` class is defined in [`scripts/gallery-template.html`](https://github.com/tt-a1i/archify/blob/main/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:

```js
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`](https://github.com/tt-a1i/archify/blob/main/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`](https://github.com/tt-a1i/archify/blob/main/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