# Archify Geometry Module Layout and Spacing: Immutable Geometry Architecture

> Learn how Archify separates immutable SVG geometry from layout transformations. Ensure spacing and positioning operate on cloned geometry without mutating the original source.

- Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify)
- Tags: internals
- Published: 2026-09-13

---

**Archify separates immutable canonical SVG geometry from runtime layout transformations, ensuring all spacing calculations and UI positioning operate on cloned geometry without mutating the original diagram source.**

The `tt-a1i/archify` codebase implements a strict geometry preservation architecture where layout and spacing operations never alter authored SVG paths. This technical guide examines how the Archify geometry module layout and spacing system maintains data integrity across Viewer chrome stabilization, adaptive Reader modes, and export pipelines.

## Core Architecture: Immutable Geometry and Runtime Clones

At the foundation of Archify's layout system lies a hard boundary between stored geometry and displayed geometry. The canonical source resides in [`viewer/template.source.html`](https://github.com/tt-a1i/archify/blob/main/viewer/template.source.html), containing the immutable SVG paths, viewBox definitions, and semantic IDs. No layout module ever rewrites these original elements.

Instead, runtime systems operate on cloned or transient geometry instances. When the Viewer initializes, it creates runtime copies that undergo transformations for zooming, panning, and pointer interactions. This separation ensures that layout algorithms can calculate docking positions, margins, and rail spacing without risking corruption of the authored diagram.

## Chrome Layout Stabilization

The [`viewer/viewer-chrome-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer/viewer-chrome-layout.js) module handles UI chrome spacing and dimension stabilization. Before rendering interface overlays, the system ensures the container has reached stable dimensions to prevent layout thrashing.

The module exposes `awaitStableLayout()`, which returns a Promise that resolves only after the chrome container achieves stable sizing:

```javascript
import { awaitStableLayout } from './viewer-chrome-layout.js';

// Wait for stable dimensions before showing UI chrome
await awaitStableLayout();
console.log('Viewer chrome layout reached stable dimensions.');

```

Spacing values are communicated via CSS custom properties. The module updates variables such as `--archify-radar-left` and `--archify-radar-right` to coordinate docking positions between the layout engine and UI components. These properties ensure consistent rail spacing across the chrome interface.

## Adaptive Reader Layout and Data Attributes

Reader layout modes toggle between adaptive and fixed positioning through the `data-reader-layout` HTML attribute. The [`viewer/reader-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer/reader-layout.js) module reads this attribute state, computes required dimensions based on the current viewport, and restores the attribute once calculations stabilize.

To switch the layout mode programmatically:

```javascript
// Enable adaptive layout mode
document.documentElement.setAttribute('data-reader-layout', 'adaptive');

import { applyReaderLayout } from './reader-layout.js';

// Recompute spacing based on current viewport
applyReaderLayout();

```

This approach allows the Archify geometry module layout and spacing system to respond dynamically to viewport changes while preserving the underlying SVG geometry. The layout engine temporarily modifies the data attribute during computation, then restores it upon completion.

## Semantic Lens Spacing and Positioning

The [`viewer/semantic-lens.js`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-lens.js) module provides layout helpers for positioning legend entries and bridges as semantic overlays. These functions calculate spatial relationships without touching the base SVG geometry.

Use `layoutLegendEntry()` to position descriptive elements relative to diagram features:

```javascript
import { layoutLegendEntry } from './semantic-lens.js';

const entry = document.createElement('div');
entry.textContent = 'User-Generated';

// Position entry without mutating SVG geometry
layoutLegendEntry(entry);

```

Similarly, `layoutLegendBridge()` coordinates connection lines between semantic markers and their referenced geometry. Both functions rely on the CSS custom properties defined by the chrome layout module to maintain consistent spacing across different viewport sizes.

## Export Pipeline Geometry Preservation

When capturing output, [`viewer/export.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js) clones geometry for each frame to ensure runtime transformations do not persist into exported artifacts. The pipeline strips temporary transforms—such as scale and clipping applied during interaction—before persisting the final image.

This cloning operation occurs on every captured canvas frame, ensuring that relationship geometry remains intact while removing viewer-specific modifications like zoom levels or pan offsets. The export module treats the canonical source as read-only, creating temporary instances solely for rasterization purposes.

## Practical Implementation Patterns

Implementing stable layout initialization requires coordinating the chrome and reader modules:

```javascript
import { awaitStableLayout } from './viewer-chrome-layout.js';
import { applyReaderLayout } from './reader-layout.js';

async function initializeViewer() {
  // Ensure chrome dimensions are stable
  await awaitStableLayout();
  
  // Apply adaptive layout calculations
  document.documentElement.setAttribute('data-reader-layout', 'adaptive');
  applyReaderLayout();
  
  console.log('Archify geometry module layout and spacing initialized.');
}

```

For adding semantic annotations without geometry mutation:

```javascript
import { layoutLegendEntry, layoutLegendBridge } from './semantic-lens.js';

function annotateNode(nodeId, label) {
  const entry = document.createElement('div');
  entry.textContent = label;
  entry.dataset.nodeId = nodeId;
  
  // Layout positions are calculated, not stored in SVG
  layoutLegendEntry(entry);
  layoutLegendBridge(entry, document.getElementById(nodeId));
}

```

## Summary

- **Immutable Source**: Canonical geometry in [`viewer/template.source.html`](https://github.com/tt-a1i/archify/blob/main/viewer/template.source.html) never changes; all layout operations use cloned instances.
- **Chrome Stabilization**: [`viewer/viewer-chrome-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer/viewer-chrome-layout.js) provides `awaitStableLayout()` and CSS custom properties like `--archify-radar-left` for consistent spacing.
- **Adaptive Layouts**: [`viewer/reader-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer/reader-layout.js) manages responsive behavior via the `data-reader-layout` attribute and `applyReaderLayout()`.
- **Semantic Overlays**: [`viewer/semantic-lens.js`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-lens.js) positions legends and bridges without SVG mutation using `layoutLegendEntry()` and `layoutLegendBridge()`.
- **Export Safety**: [`viewer/export.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js) clones geometry per frame to strip runtime transforms before persistence.

## Frequently Asked Questions

### How does Archify prevent layout operations from corrupting the original SVG?

Archify maintains the authored SVG in [`viewer/template.source.html`](https://github.com/tt-a1i/archify/blob/main/viewer/template.source.html) as read-only canonical geometry. Layout modules such as [`viewer-chrome-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer-chrome-layout.js) and [`viewer-reader-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer-reader-layout.js) operate on cloned DOM nodes or computed positioning data rather than modifying source path elements. During export, [`viewer/export.js`](https://github.com/tt-a1i/archify/blob/main/viewer/export.js) creates temporary geometry clones for each frame, ensuring runtime transformations never persist to saved files.

### What is the purpose of the `data-reader-layout` attribute?

The `data-reader-layout` attribute signals the current layout mode to the [`viewer/reader-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer/reader-layout.js) module. Setting this attribute to `adaptive` or `fixed` triggers recalculation of spacing and positioning algorithms. The module reads this state, computes required dimensions based on viewport metrics, and restores the attribute once layout stabilizes, enabling responsive behavior without JavaScript state management.

### How are spacing values shared between layout modules and UI components?

Spacing and docking coordinates propagate through CSS custom properties such as `--archify-radar-left` and `--archify-radar-right`. The chrome layout module updates these variables after calculating stable dimensions, while semantic overlay modules like [`viewer/semantic-lens.js`](https://github.com/tt-a1i/archify/blob/main/viewer/semantic-lens.js) consume them to position legends and bridges consistently across different screen sizes.

### What happens if `awaitStableLayout()` resolves before the container is actually stable?

The `awaitStableLayout()` function in [`viewer/viewer-chrome-layout.js`](https://github.com/tt-a1i/archify/blob/main/viewer/viewer-chrome-layout.js) includes internal checks to detect dimension thrashing. If the layout has not reached stable dimensions—indicated by fluctuating container sizes—the Promise remains pending until measurements converge. This prevents race conditions where UI chrome might render against incorrect spacing calculations.