Archify Geometry Module Layout and Spacing: Immutable Geometry Architecture

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

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

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

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

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:

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 never changes; all layout operations use cloned instances.
• Chrome Stabilization: viewer/viewer-chrome-layout.js provides awaitStableLayout() and CSS custom properties like --archify-radar-left for consistent spacing.
• Adaptive Layouts: viewer/reader-layout.js manages responsive behavior via the data-reader-layout attribute and applyReaderLayout().
• Semantic Overlays: viewer/semantic-lens.js positions legends and bridges without SVG mutation using layoutLegendEntry() and layoutLegendBridge().
• Export Safety: 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 as read-only canonical geometry. Layout modules such as viewer-chrome-layout.js and viewer-reader-layout.js operate on cloned DOM nodes or computed positioning data rather than modifying source path elements. During export, 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 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 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 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.

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