v2.x.md

📜 Version 2.x History

[v2.9.0] - 2026-05-06

🏗️ Alias Architecture Stabilization

• Unified Alias Engine: Completed the architectural migration to the AliasEngine, centralizing all registration and resolution logic for Events and Periods.
• Rich Metadata Results: Enhanced the resolution engine to return structured AliasResult objects, providing better traceability and granular control over alias-driven parses.
• Hardened Clock Snapping: Finalized the standardization of clock-like alias resolution, ensuring consistent sub-second precision clearing for all static and functional time aliases.
• Performance Optimized Monitoring: Introduced a lightweight version-tracking system to detect registry mutations, enabling O(1) change detection during the Tempo lifecycle.

⚙️ Parser & Registry Refinement

• Consolidated Host Context: Modularized the construction of the functional alias "pseudo-Tempo" context, improving separation of concerns in the parsing pipeline.
• Legacy Decoupling: Successfully decoupled term-based alias registration from internal raw objects, moving toward a more encapsulated and secure registry design.

📚 Documentation Fixes

• VitePress 404 Patch: Corrected root directory resolution to fix "404 Not Found" errors on the landing page.
• Build Resilience: Implemented targeted folder exclusion to prevent build-time dead-link errors in non-public directories.

---

[v2.8.0] - 2026-04-30

🚨 Immutability System Refined

• The project evaluated mutation-throwing Proxies for all immutable objects, but reverted to using Object.freeze for stability and compatibility.
• All core objects remain protected with Object.freeze. No mutation-throwing Proxies are used for core objects.
• See plan for architectural and migration details.

⚙️ Parse Planner Configuration

• Added Parse Planner: Introduced planner.layoutOrder to explicitly control the parsing priority of date layouts (like mdy or iso).
• Pre-Filtering Optimization: Moved parsePrefilter to planner.preFilter. Legacy parsePrefilter configurations remain fully backward compatible.

🛡️ Resilience & Bug Fixes

• MonthDay Auto-Detection: Hardened the monthDay options resolver so that boolean shortcuts (e.g. monthDay: true) and manual overrides are properly tracked and never overwritten by auto-detection heuristics.
• Sandbox Factory Stability: Fixed bugs in the Tempo.create() sandbox where period alias collisions were failing silently; console.warn is now properly emitted when aliases overlap in local sandboxes.
• Symbol Discovery Isolation: Patched the $setConfig resolution flow to correctly merge custom formats provided via discovery symbols before evaluating global option extensions.

---

[v2.7.0] - 2026-04-27

🧩 Configuration Rationalization

• Grouped Options: Consolidated regional parsing and relative time options into nested objects for improved discoverability and additive merging support.
  • mdyLocales and mdyLayouts → monthDay: { locales, layouts }
  • rtfFormat and rtfStyle → relativeTime: { format, style }
• Internal Hardening: Added isMonthDay internal detection to more accurately resolve parse-order layouts in regional contexts.

🛡️ Resilience & Bug Fixes

• Event Registry Overrides: Fixed $setEvents logic to ensure user-defined event aliases correctly override or merge with built-in patterns without duplication or stale matches.
• TimeZone Fallback Resilience: Enhanced the IANA TimeZone fallback mechanism with a cleaned-up, prioritized list of regional aliases.
• Intl.Locale Debugging: Improved diagnostic logging for Intl.Locale resolution to assist in cross-environment consistency issues.
• Ticker Stabilization: Further refined async generator pulse counts and termination logic.

⚙️ CI/CD & Infrastructure

• Performance Benchmarking: Integrated a dedicated bench/ suite into the CI pipeline to monitor performance impact on core parsing and mutation logic.
• Workflow Optimization: Refactored the GitHub Actions workflow for better test isolation and Node.js 24 compatibility.

[v2.6.0] - 2026-04-25

⚠️ Migration Notes

• New Features

Added normalizeUtcOffset utility for transforming informal UTC-offset strings to standard format. Added layoutOrder option to customize parsing element precedence.

• Breaking Changes

• Season Scope Simplification: Removed the Chinese-specific object previously attached to all term.season scope's output. For Chinese season interpretation, create a dedicated Tempo instance with {timeZone: 'Asia/Shanghai'} or {timeZone: '+08:00'}. Note that Chinese zodiac will still be supported on term.zodiac.CN as before.

• Bug Fixes

Fixed layout pattern resolution ordering to respect intended sequence. Enhanced timezone normalization for UTC offset handling.

• Documentation

Updated architecture documentation and configuration guidance. Clarified plugin/module callback parameter ordering in examples. Added v2.6.0 migration guide for season changes.

[v2.5.0] -2026-04-25

New Features

• Added Sandbox Factory pattern for isolated Tempo configurations via Tempo.create(options).
• User-defined aliases now evaluated before built-in aliases for custom precedence.
• Support for shorthand duration construction: new Tempo({ hours: 2 }).
• Debug option now accepts numeric log levels for granular control.
• Added fortnight event and half-hour period aliases.
• Improved compact time/date parsing for 6 and 8-digit inputs.

Documentation

• Enhanced installation guidance with Temporal polyfill details.
• New modularity documentation and sandbox factory pattern guide.
• Added parsing cookbook with digit-only string precedence examples.

[v2.4.0] - 2026-04-24

🧩 Parsing Infrastructure

• Layout Order Resolver: Extracted layout-ordering decision logic into a dedicated engine.layout module (src/engine/engine.layout.ts), improving internal modularity and enabling future per-input classification support. The resolver maintains 100% behavior parity with prior ordering semantics (locale-based dmy↔mdy swaps).
• Layout Controller Framework: Introduced a minimal but extensible controller-map structure to support future input classifications (e.g., "6 digits only", "contains colon"). Currently ships with a single default classification that mirrors the existing layout order, ensuring zero overhead today and a clear path for Release B/C enhancements.

🛡️ Isolation & Sandboxing

• Sandbox Factory Mode: Introduced Tempo.create(), a static factory method that generates a completely isolated Tempo subclass. Each sandbox maintains its own independent configuration, registry, and plugin state while inheriting from the parent, enabling multi-tenant or modular configurations within a single process without global state collisions.

⚙️ Internal Refactoring & Type Safety

• Modular Separation: Extracted the core ordering logic from Tempo.#swapLayout, improving code organization and unit testability without affecting public APIs.
• Symbol-Based Safety: Protected the default layout classification key with a Symbol('default'), reducing accidental tampering risk and improving internal API robustness.
• Determinism Coverage: Added comprehensive tests for layout order resolution, classification fallback, and multi-pair swap handling to ensure predictable behavior across locales and configurations.
• Module Path Flattening: Relocated core modules (e.g., mutate, duration) from src/plugin/module/ to a top-level src/module/ directory. This simplifies the internal architecture and provides cleaner internal import paths, reflecting their role as core library features rather than just "plugins".

📊 Diagnostics & Debug Support

• Layout Order Tracing: Added optional debug emission to show the final resolved layout order when debug: true is set, helping developers understand parse-order decisions.

[v2.3.0] - 2026-04-22

🧩 Parsing Innovations

• Standalone Logic: Extracted the natural language engine into a dedicated parse() function, enabling independent datetime string resolution without requiring a full Tempo instance.
• Noise Filtering: Introduced a configurable ignore option to strip "noise words" during parsing, significantly increasing the robustness of the natural language interpreter.
• Backtracking Security: Implemented a centralized regex safety guard (Match.backtrack) in the snippet registry to block potentially malicious patterns and prevent catastrophic backtracking.

📚 Documentation & UX

• Ecosystem Installation: Released a comprehensive installation guide covering Node.js (npm/pnpm/yarn), Deno, standard browser ESM, and specialized "Lite" build configurations.
• Interactive Demo: Enhanced the browser-based playground with a live timezone selector and real-time clock updates to demonstrate Temporal integration.
• Quick Start Refinement: Streamlined the README and configuration documentation to highlight simplified entry points and noise-filtering capabilities.

🛠️ Refactor & Type Safety

• State Management: Optimized the internal parser state machine to reduce memory pressure and improve resolution speed for complex strings.
• Type Safety: Hardened the TypeScript definitions for all parse and term resolution functions, ensuring strict type-checking without consumer-side casting.
• Automatic Context Sync: The engine now automatically synchronizes the hemisphere (sphere) configuration whenever the timezone is updated.
• Resilience: Hardened the resolution loop with safety-valves to prevent infinite loops during extreme date-range traversals and improved parse-error detection to prevent silent state corruption.

[v2.2.6] - 2026-04-20

🚑 Emergency Hotfix

• Isomorphic Export Architecture: Refactored tempo.entry.ts and Rollup configuration to ensure the browser ESM bundle exports Tempo as both a default and a named export. This guarantees that import { Tempo } from '@magmacomputing/tempo' functions identically across Node.js and browser environments without throwing resolution errors.
• Dependency Resolution: Added jsbi explicitly to all documentation importmap examples to correctly resolve @js-temporal/polyfill internal bare module references and eliminate Failed to resolve module specifier "jsbi" errors.
• Documentation & UI: Fixed orphaned markdown script tags, formatted HTML browser usage blocks, and completely revamped the browser test UI pages with a premium jazzy aesthetic.

[v2.2.5] - 2026-04-20

🏗️ Modular Hardening

• Singleton Resilience: Replaced instanceof checks in TempoRuntime with a cross-bundle brand check, ensuring singletons are correctly adopted across bundle boundaries and HMR reloads.
• Unified Discovery: Consolidated internal storage for term and extension plugins into a single, validated pluginsDb structure.
• Resolved Shadowing: Eliminated parameter shadowing in runtime hook methods to ensure reliable event emission.

🔍 Term Resolution Refinements

• Chronological Stability: Enforced chronological sorting in resolveCycleWindow for accurate cycle anchor identification.
• Absolute vs Relative Years: Normalized year handling to allow templates to mix relative offsets and absolute historical years seamlessly.

📚 Documentation & UX

• Standards Mode: Modernized all public demonstration files with proper HTML5 skeletons and metadata.
• Contextual Guidance: Updated architecture docs and READMEs with accurate module paths and functional importmap examples.

[v2.2.4] - 2026-04-19

🛡️ Production Safety

• Immutable Compatibility: Added redefinition guards to TickerModule to prevent errors on already-frozen classes.
• ESM Integrity: Bundled tslib into granular ESM builds to resolve resolution failures in standard browser environments.

[v2.2.3] - 2026-04-19

✨ New Features

• Modular Parsing: Initial decoupling of the parse engine to support standalone usage.
• Layout Snippets: Introduced pattern-based layout customization for granular formatting control.
• Project Governance: Integrated the MIT license and established a dedicated release history.

🐛 Bug Fixes

• Match Propagation: Ensured parse results correctly propagate through instance clones.
• Drift Resolution: Corrected timezone and calendar drift during intensive mutation cycles.

📚 Documentation & Chores

• Knowledge Architecture: Reorganized navigation into focused tracks: Cookbook, Advanced Reference, and Utility Library.
• API Reference: Expanded constructor documentation and added guidance for custom enum implementations.
• Diagnostics: Improved internal module-loading error messages for easier troubleshooting.

[v2.2.2] - 2026-04-18

🛡️ Registry Stabilization

• Globalized module and serialization registries using Symbol.for() on globalThis to ensure state consistency across module reloads, HMR, and bundled distributions.
• Implemented secure, local Proxy wrapping for registries to prevent closure persistence across library reloads.

🔍 Hardened Reflection

• Fixed static property reflection for decorated classes by implementing recursive prototype chain traversal in getAccessors.
• Refined prototype walking logic to prevent leaks from Object.prototype and Function.prototype.

📦 Production Optimization

• Achieved 100% build parity and test coverage in the production distribution (test:dist).
• Reduced NPM package size by nearly 50% by excluding non-essential documentation and image assets from the public package.
• Hardened Rollup build paths to be context-aware and defensive against missing artifacts.

🎨 Premium Documentation & UX

• Redesigned the documentation landing page with a custom, high-performance Hero section and a live Tempo-driven analog clock.
• Harmonized branding across README and documentation sites with "Tempo Blue" styling.
• Fixed routing and asset resolution for GitHub Pages deployments using VitePress base-path helpers.

🧬 Mutation Engine & State Preservation

• Stabilized the mutation engine (.add(), .set()) to correctly accumulate and preserve parse results across instance clones.
• Implemented robust parse result propagation in MutateModule using the internal state.matches registry.
• Standardized cross-module state access using the [sym.$Internal] symbol, enabling safe cloning without violating private encapsulation.
• Resolved timezone and calendar drift during complex mutations by enforcing authoritative state-merging in the mutation pipeline.

🧩 Modular Parse Engine

• Successfully decoupled internal parsing logic into ParseModule, reducing core class complexity.
• Implemented a hybrid static Tempo.parse configuration/method pattern to maintain full backward compatibility while supporting modular delegation.
• Hardened the interpret utility to ensure reliable method dispatching even when modules are loaded lazily or via HMR.

⚙️ CI/CD & Tooling

• Upgraded GitHub Actions pipeline to Node.js 24 to resolve deprecation warnings.
• Restored separate "Full" and "Core" test suite isolation in local and workspace Vitest configurations.
• Standardized documentation build order to ensure artifacts are compiled before generation.
• Achieved 100% Test Pass Rate (384/384) across all environments and distribution bundles.

[v2.1.3] - 2026-04-18

📚 Documentation & Ecosystem

• VitePress Migration: Launched a modern documentation system with integrated TypeDoc API references.
• Loading Patterns: Introduced interactive browser demos for ESM, IIFE, and granular module resolution.
• Standardized README: Refreshed the main project entry point with improved formatting and developer guides.

🚀 Performance & Extensibility

• Plugin Refactor: Migrated the plugin system to a flexible object-based API for better extensibility.
• Cache Optimization: Enhanced memoization performance across the core engine.
• Modular Exports: Streamlined library entry points to improve tree-shaking and reduce bundle sizes.

⏱️ Temporal Utilities

• High Precision: Expanded Temporal utility functions with native support for nanosecond-precision calculations.

[v2.1.2] - 2026-04-16

Tempo v2.1.2 is a major milestone, delivering a more reactive architecture and rock-solid stability.

🏗️ Modular Architecture

Tempo is now split into core and optional modules, allowing you to include only what you need. This reduces bundle size for users who only need the basic engine.

📝 Improved Logging

Internal logging now uses context-aware Symbols. This decouples the logging logic from the core engine, allowing for cleaner diagnostics without performance overhead.

⏱️ Static API

• Added Tempo.duration() static method for convenient duration creation without instantiating a full Tempo date object first.

🔌 Side Effect Registration

Plugins now support automatic registration.

• The full @magmacomputing/tempo package includes all modules by default.
• Core users (@magmacomputing/tempo/core) can activate features simply by importing the corresponding module (e.g., import '@magmacomputing/tempo/ticker').

🛡️ 100% Reliability

The engine passes all regression tests, ensuring complete stability across:

• Parsing complex date strings.
• Calculation and relative math.
• Formatting routines.

🗓️ Unified Term Logic

Terms (like Quarters and Seasons) are now fully integrated:

• Use # in set() to jump to boundaries (e.g., t.set({ start: '#quarter' })).
• Use {#term} in format() to embed semantic labels (e.g. "Second Quarter") directly into strings (e.g., t.format('Today is {yyyy}-{mm}-{dd} in the {#quarter}').

➗ Relational Term Math

A category-first feature. Shift dates by semantic "steps" with .add({ '#quarter': 1 }). Tempo preserves your relative duration within the term, jumping across gaps and handling overflows with mathematical precision.

🔗 Fluent Immutable Boundaries

Term ranges now return fully functional, frozen Tempo instances for start and end. This allows for seamless chaining:

t.term.qtr.start.format('{dd} {mmm}')

⚡ Ticker Reliability

Fully stabilized the Ticker subsystem:

• Resolved async generator hangs.
• Synchronized pulse counts ($N$ pulses for limit: N), guaranteeing 100% predictable reactive streams.

🚀 Parsing Engine Optimization

• Re-engineered pattern generation for $O(1)$ instance creation.
• Improved support for custom layout literals in local/one-off parsers.
• Significant refinements to the natural language engine for even more intuitive relative-date handling ("next Friday", "two days ago", etc.).