Feature/modular parse

packages/tempo/.vitepress/config.ts

@@ -18,27 +18,38 @@ export default defineConfig({
     nav: [
       { text: 'Guide', link: '/README' },
       { text: 'API', link: '/doc/tempo.api' },
-      { text: 'Releases', link: '/doc/releases/versions' }
+      { text: 'Releases', link: '/doc/releases/' }
     ],
     sidebar: [
       {
         text: 'Getting Started',
         items: [
           { text: 'Introduction', link: '/README' },
+          { text: 'Cookbook', link: '/doc/tempo.cookbook' },
           { text: 'Migration Guide', link: '/doc/migration-guide' },
-          { text: 'Version History', link: '/doc/releases/versions' }
+          { text: 'Release Notes', link: '/doc/releases/' }
         ]
       },
       {
         text: 'Core Concepts',
         items: [
           { text: 'Configuration', link: '/doc/tempo.config' },
           { text: 'Modularity', link: '/doc/tempo.modularity' },
-          { text: 'Shorthand Engine', link: '/doc/tempo.shorthand' },
+          { text: 'Layout Patterns', link: '/doc/tempo.layout' },
           { text: 'Terms System', link: '/doc/tempo.term' },
           { text: 'Ticker Plugin', link: '/doc/tempo.ticker' }
         ]
       },
+      {
+        text: 'Advanced Reference',
+        items: [
+          { text: 'API Reference', link: '/doc/tempo.api' },
+          { text: 'Types System', link: '/doc/tempo.types' },
+          { text: 'Shorthand Engine', link: '/doc/tempo.shorthand' },
+          { text: 'Weekday Engine', link: '/doc/tempo.weekday' },
+          { text: 'Debugging', link: '/doc/tempo.debugging' }
+        ]
+      },
       {
         text: 'Architecture & Internals',
         items: [
@@ -48,13 +59,30 @@ export default defineConfig({
           { text: 'Performance Benchmarks', link: '/doc/tempo.benchmarks' }
         ]
       },
+      {
+        text: 'Utility Library',
+        items: [
+          { text: 'Library Overview', link: '/doc/tempo.library' },
+          { text: 'Enumerators', link: '/doc/tempo.enumerators' },
+          { text: 'Serializers', link: '/doc/tempo.serializers' },
+          { text: 'Decorators', link: '/doc/tempo.decorators' },
+          { text: 'Advanced Promises (Pledge)', link: '/doc/tempo.pledge' },
+        ]
+      },
       {
         text: 'Ecosystem',
         items: [
           { text: 'Contribution Guide', link: '/CONTRIBUTING' },
           { text: 'Comparison', link: '/doc/comparison' },
+          { text: 'Tempo vs Temporal', link: '/doc/tempo-vs-temporal' },
           { text: 'Project Vision', link: '/doc/vision' }
         ]
+      },
+      {
+        text: 'Services & Support',
+        items: [
+          { text: 'Professional Services', link: '/doc/commercial' }
+        ]
       }
     ],
     socialLinks: [

packages/tempo/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Magma Computing
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

packages/tempo/bin/temporal-polyfill.ts

@@ -0,0 +1,10 @@
+import { Temporal } from '@js-temporal/polyfill';
+
+if (typeof globalThis.Temporal === 'undefined') {
+	Object.defineProperty(globalThis, 'Temporal', {
+		value: Temporal,
+		enumerable: false,
+		configurable: true,
+		writable: true,
+	});
+}

packages/tempo/doc/releases/index.md

@@ -0,0 +1,15 @@
+# 🚀 Releases
+
+Explore the evolution of Tempo through its version history.
+
+- [Version 2.x (Current)](./v2.x) - Modular architecture, Shorthand engine, and Ticker stability.
+- [Version 1.x (Legacy)](./v1.x) - Initial public release and Temporal polyfill integration.
+- [Version 0.x (Legacy)](./v0.x) - Initial release.
+
+---
+
+### Release Strategy
+Tempo follows [Semantic Versioning](https://semver.org/).
+- **Major**: Breaking changes and architectural shifts.
+- **Minor**: New features and significant enhancements.
+- **Patch**: Bug fixes and performance optimizations.

packages/tempo/doc/releases/v0.x.md

@@ -0,0 +1,31 @@
+# 📜 Version 0.x History
+
+## [v0.3.0] - 2025-07-31
+### New Features
+
+Introduced an immutable property decorator and a deep-freeze utility for objects and arrays.
+Added a secure, default configuration module for date/time parsing.
+Extended global browser support for the Temporal API via polyfill.
+### Bug Fixes
+
+Corrected the enumerable decorator to ensure proper closure.
+### Refactor
+
+Centralised and secured date/time parsing constants and layouts.
+Improved typing and immutability for enums and configuration objects.
+Updated logging and state management to use object-based constants instead of enums.
+Documentation
+
+Enhanced inline documentation and added detailed usage examples for enum utilities.
+### Chores
+
+Updated development dependencies to latest versions.
+Reformatted TypeScript configuration for clarity.
+
+## [v0.2.0] - 2024-10-30
+### New Features
+
+Updated the version of the Tempo class to 0.2.0, ensuring users have access to the latest enhancements.
+### Bug Fixes
+
+Resolved versioning discrepancies in the Default configuration object.

packages/tempo/doc/releases/v1.x.md

@@ -0,0 +1,59 @@
+# 📜 Version 1.x History
+
+## [v1.1.3] - 2026-03-31
+### New Features
+
+Browser: persistent storage wrapper, multi‑tap gesture helper, geolocation + maps/address utilities, simple alert/prompt/confirm helpers.
+Server: sandboxed temp‑file API, HTTP helpers with timeouts, Base64 encode/decode, JWT payload decoder.
+Tempo v2.0.0: lazy initialization, unified term math/format tokens (#{...}), anchor/term utilities and faster startup.
+### Documentation
+
+Expanded API/type docs, architecture, benchmarks, migration and cookbook guidance.
+### Branding
+
+Package scope renamed to @magmacomputing/*; new build/release scripts and updated TypeScript/test configs.
+
+## [v1.1.2] - 2026-03-23
+### New Features
+
+Unified plugin system via Tempo.load() for plugins, term plugins, and discovery configuration.
+Made Pledge thenable and awaitable via .then() method support.
+Enhanced makeTemplate() with safe placeholder substitution instead of code evaluation.
+### Bug Fixes
+
+Improved asCurrency() to properly coerce string inputs.
+Fixed constructor error handling to throw instead of returning empty objects.
+### Documentation
+
+Added Target Audience section describing intended users and migration scenarios.
+Expanded Node.js documentation with native subpath import details.
+
+## [v1.1.1] - 2026-03-22
+### New Features
+
+Plugin-based extension architecture for extending Tempo functionality
+Automatic plugin discovery via static Tempo.discover() method
+New subpath exports for enums, serialisation, Pledge utility, and ticker plugin
+### Changed
+
+Ticker functionality now available as optional plugin; requires explicit installation
+Selective immutability for decorated classes instead of full object freeze
+Core methods (format, add, set) are now protected from overwrites
+### Documentation
+
+Comprehensive overhaul reflecting new plugin architecture
+Dedicated Pledge utility documentation added
+
+## [v1.1.0] - 2026-03-19
+### New Features
+
+Introduced Tempo.ticker() — reactive clock streams via async-generator (for await...of) or callback subscription with stop control.
+### Documentation
+
+Added a dedicated ticker guide and updated Tempo docs with examples and API reference.
+### Tests
+
+Added unit tests covering callback mode, async-iterator mode and input validation.
+### Chores
+
+Bumped package version to 1.1.0.

packages/tempo/doc/releases/versions.md → packages/tempo/doc/releases/v2.x.md

@@ -1,4 +1,4 @@
-# 📜 Version History
+# 📜 Version 2.x History
 
 ## [v2.2.2] - 2026-04-18
 ### 🛡️ Registry Stabilization
@@ -19,10 +19,22 @@
 - 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
 ### New Features

packages/tempo/doc/tempo-vs-temporal.md

@@ -67,7 +67,6 @@ From that point, the plugin is available to new Tempo instances.
 
 See the section on [plugin](tempo.term.md) for more information.
 
-
 ```typescript
 const t = new Tempo();
 const isWeekend = t.term.isWeekend;             // through plugin

packages/tempo/doc/tempo.api.md

@@ -9,6 +9,26 @@ This document provides a comprehensive technical reference for the `Tempo` class
 
 ---
 
+## 🏗️ Constructor
+
+You can instantiate `Tempo` in several ways:
+
+- **`new Tempo()`**: Defaults to current time ("now").
+- **`new Tempo(dateTime)`**: Parses a date-time value.
+- **`new Tempo(dateTime, options)`**: Parses with specific configuration.
+- **`new Tempo(options)`**: Defaults to "now" with specific configuration.
+
+### Valid `dateTime` Types:
+- **`string`**: ISO 8601, natural language ("tomorrow", "next Friday"), or custom patterns.
+- **`number`**: Unix timestamps in milliseconds (default) or microseconds.
+- **`BigInt`**: Unix timestamps in nanoseconds.
+- **`Date`**: Standard JavaScript `Date` object.
+- **`Tempo`**: Clones another Tempo instance.
+- **`Function`**: A dynamic resolver (max depth 5).
+- **`Temporal.*`**: Any native Temporal object (ZonedDateTime, PlainDate, etc.).
+
+---
+
 ## 🏗️ Static Methods
 
 ### `Tempo.init(options?: Tempo.Options)`
@@ -39,7 +59,6 @@ Compares two `Tempo` instances or date-time values for sorting.
 - **Returns:** `Tempo.Duration`
 - **Example:** `Tempo.duration('P1Y')` or `Tempo.duration({ months: 2 })`
 
-
 ### `Tempo.now()`
 Returns the current Unix epoch in nanoseconds as a `BigInt`.
 
@@ -178,3 +197,9 @@ Returns a `Temporal.PlainDateTime` representation.
 - `fmt`: Registry of pre-calculated strings for all standard formats. (Note: These are enumerable for easy discovery).
 - `config`: The effective configuration for this specific instance (Note: `scope`, `anchor`, and `value` are excluded from the public object).
 - `parse`: The parsing rules and lineage for this instance.
+
+---
+
+> [!TIP]
+> **Looking for the full technical details?**  
+> For an exhaustive, auto-generated reference of every property, internal type, and class member, see our [Full Technical API Reference](./api/README.md).