src's highest version & evolution.

Why src/ is versioned

• Architectural Milestones: Each version records a key architectural leap (e.g. v11 sleek orchestration, v27 versioned listener delegation, v28 3-Chapter Story Architecture with preserved 0–5 elementBuilder).
• Zero Breaking Regressions: Existing projects or legacy tests can pin to a specific version (e.g. src/v27/) without risk of breakage.
• Safe Refactoring: New designs are isolated in a new version folder, allowing side-by-side benchmarking before promotion.

Dynamic highest version discovery

The CLI tool (bin/cli.js) never hardcodes a version. It dynamically inspects src/:

// Scans src/, filters v*, sorts descending
const versionFolders = readdirSync(srcDir, { withFileTypes: true })
  .filter(entry => entry.isDirectory() && /^v\d+$/.test(entry.name))
  .map(entry => ({ name: entry.name, n: Number(entry.name.slice(1)) }))
  .sort((a, b) => b.n - a.n);

const highest = versionFolders[0].name; // e.g. "v11"

Running npx json-to-dom always copies src's highest version automatically.

Developer's Guide: Wiring root index.js

The repository root contains an index.js proxy. It is the single entry point for packages and bundlers:

// Root index.js: Always re-exports src's highest version
export * from "./src/v11/index.js";
export { default } from "./src/v11/index.js";

How Consumers Import (No Version Hardcoding!)

Application code consuming json-to-dom should never hardcode version paths:

// ✅ From NPM package (automatically loads src's highest version)
import { buildSpecElement } from "json-to-dom";

// ✅ From local repository root proxy
import { buildSpecElement } from "./index.js";

// ✅ From local copy scaffolded by npx json-to-dom
import { buildSpecElement } from "./json-to-dom/index.js";

How to promote a new version (e.g. v12)

• Step 1: Clone current highest: cp -r src/v11 src/v12.
• Step 2: Implement new features and refactors inside src/v12/.
• Step 3: Update root index.js to point to ./src/v12/index.js.
• Step 4: Update package.json "module": "./src/v12/index.js".
• Step 5: Add test suite test/v12.unit.test.js.
• Result: npx json-to-dom automatically selects v12 with zero CLI changes!