# How the `archify preview` Command Watches and Reloads Verified JSON Files During Desktop Authoring > Learn how the archify preview command watches and reloads verified JSON files during desktop authoring. Understand its live-reload loop for efficient development. - Repository: [tt-a1i/archify](https://github.com/tt-a1i/archify) - Tags: internals - Published: 2026-08-05 --- **`archify preview` runs a self-contained live-reload loop that watches a JSON source file for changes, rebuilds a verified HTML artifact when the source stabilizes, and pushes updates to the browser via Server-Sent Events (SSE).** The `archify preview` command in the `tt-a1i/archify` repository provides desktop authors with instant visual feedback while editing JSON diagram files. Rather than running manual builds after every change, the tool monitors the source file, coalesces rapid edits, validates each build, and automatically refreshes the browser—only when a verified artifact is ready. This article breaks down the complete watch-and-reload pipeline as implemented in the source code. --- ## Live Preview Architecture Overview The preview system combines **file system watching**, **digest-based change detection**, **debounced builds**, **bounded child processes**, and **SSE-driven live reload**. These components work together to ensure the browser always displays the latest valid diagram without flashing intermediate errors or stale versions. Key modules in `archify/bin/preview.mjs`: - `runPreview` – entry point that initializes the server, resolves paths, and starts the watch loop. - `observeSource` – polls and hashes the source file to detect changes. - `queueStableBuild` – debounces build requests and triggers `beginBuild` on stable sources. - `commitCandidate` – verifies build receipts and promotes artifacts to the live view. - `broadcast` – pushes state updates to connected browsers via SSE. --- ## File Watching Strategy: Native Watches Plus Polling `archify preview` uses a hybrid watching strategy to avoid missing rapid editor events. ### Native `fs.watch` with Directory Monitoring The tool attaches a native watcher to the source file's directory: ```js // From archify/bin/preview.mjs, lines 89-95 watcher = fs.watch(path.dirname(inputPath), (eventType, filename) => { if (filename === path.basename(inputPath)) { observeSource(); } }); ``` Native `fs.watch` is efficient but unreliable during rapid rename bursts common in editors like VS Code or Vim. ### Periodic Poll Backup To close the reliability gap, a polling timer runs every 800 milliseconds by default: ```js // From archify/bin/preview.mjs, lines 98-100 pollTimer = setInterval(() => observeSource(), pollMs); ``` This dual approach ensures changes are detected without excessive CPU usage or missed events. --- ## Digest-Based Change Detection and Debouncing Every detected change triggers `observeSource`, which computes a SHA-256 hash of the file contents: ```js // From archify/bin/preview.mjs, lines 24-28 async function sourceDigest(inputPath) { const bytes = await fs.promises.readFile(inputPath); return sha256(bytes); // stable canonical representation } ``` The hash—**not timestamps**—determines whether the source has meaningfully changed. ### Debounced Build Queue When a new hash appears, `queueStableBuild` schedules a build with a 400ms debounce: ```js // From archify/bin/preview.mjs, lines 55-58 function queueStableBuild(newHash) { queuedHash = newHash; clearTimeout(buildTimer); buildTimer = setTimeout(() => beginBuild(newHash), debounceMs); } ``` If the source stabilizes (same hash after debounce), the build launches. If it changes again, the timer resets with the newer hash. --- ## Bounded Child Process Builds The `beginBuild` function spawns `archify deliver` as a detached child process: ```js // From archify/bin/preview.mjs, lines 71-82 const child = spawn(process.argv[0], [ binPath, 'deliver', type, inputPath, '--output', candidatePath, '--json-receipt' ], { detached: true, stdio: ['ignore', 'pipe', 'pipe'] }); ``` ### Process Lifecycle Management The preview enforces strict boundaries on build processes: - **Graceful shutdown**: `stopGraceTimer` allows the child to complete naturally. - **Forced termination**: `stopKillTimer` sends `SIGKILL` if the child lingers. - **Pending build tracking**: If new changes arrive during a build, `pendingBuild = true` schedules a follow-up build immediately after the current child exits. This prevents zombie processes and ensures the queue never stalls. --- ## Verification, Commit, and State Promotion Build output goes through cryptographic verification before reaching the browser. ### Receipt Parsing and Hash Validation The child writes a JSON receipt to stdout. `parseReceipt` extracts the expected artifact hash, and `commitCandidate` validates: ```js // From archify/bin/preview.mjs, lines 42-50 const digest = await artifactDigest(candidatePath); if (digest !== receipt?.artifact?.sha256) { throw new VerificationError('Artifact hash mismatch'); } ``` ### Atomic Promotion to Live View Verified artifacts are moved from the staging directory (`.archify-preview-…`) to the output path, stored in `artifactBuffer`, and marked as **verified**: ```js // From archify/bin/preview.mjs, lines 61-68 if (digest !== lastArtifactDigest) { await fs.promises.rename(candidatePath, outputPath); artifactBuffer = await fs.promises.readFile(outputPath); lastArtifactDigest = digest; revision++; state = { status: 'verified', revision, updatedAt: Date.now() }; broadcast(); } ``` If the source changed during the build (`supersededBy`), the newer hash is re-queued for the next cycle. --- ## Live Reload via Server-Sent Events The preview server exposes three endpoints that enable real-time browser updates: | Endpoint | Purpose | |----------|---------| | `/` | Serves `previewPage` with an `