Feature/modular parse

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempo-monorepo",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "private": true,
   "description": "Magma Computing Monorepo",
   "repository": {

packages/library/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magmacomputing/library",
-  "version": "2.2.2",
+  "version": "2.2.3",
   "description": "Shared utility library for Tempo",
   "author": "Magma Computing Solutions",
   "license": "MIT",

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/CHANGELOG.md

@@ -5,6 +5,23 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.2.3] - 2026-04-20
+
+### Added
+- **Modular Parse Engine**: Successfully decoupled internal parsing logic into `ParseModule`, enabling standalone parsing support and reducing core class complexity.
+- **Carousel Accessibility**: Added ARIA roles, labels, and keyboard controls (Arrow keys) to the documentation carousel to improve screen reader and keyboard user experience.
+- **Layout Snippets**: Introduced layout patterns with snippet-based customization for more flexible date formatting.
+
+### Changed
+- **HMR Resilience**: Hardened the development-mode registry workaround by binding the original `Map.has` method and moving extension registration before class initialization, resolving "read only property" errors during hot reloads.
+- **Modular Registration**: Enforced standard `defineInterpreterModule` clash guards for all core modules (Parse, Mutate, Duration) to prevent registry collisions.
+
+### Fixed
+- **Resource Management**: Fixed interval leaks in the documentation clock by implementing proper cleanup for the fallback heartbeat timer during unmounting and visibility changes.
+- **Initialization Stability**: Added a sentinel guard and optimized `initPromise` handling to prevent redundant error logging and failed awaits during page visibility transitions.
+- **Mutation Engine Hardening**: Corrected preserves `state.options` and the `mutateDepth` recursion guard across all instance creation paths in `MutateModule`.
+- **Fluent Chaining Fallbacks**: Hardened `until()` and `since()` calls with explicit host-instance fallbacks to preserve fluent chaining when modules are missing in "catch" mode.
+
 ## [2.2.2] - 2026-04-18
 
 ### Fixed

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/README.md

@@ -5,7 +5,7 @@
         <img src="./img/logo.svg" width="120" alt="Tempo logo">
       </td>
       <td align="left" valign="middle">
-        <h1>Tempo</h1>
+        <h1><font color="#3498db">Tempo</font></h1>
         <p><strong>The Professional Date-Time Library for the Temporal API</strong></p>
       </td>
     </tr>
@@ -63,13 +63,15 @@ Ideal for organizations looking to move away from **Moment.js**, **Day.js**, or
 For those building complex, time-sensitive systems (such as financial platforms, scheduling engines, or global logistics trackers) that demand the precision of Temporal combined with a premium, type-safe developer experience.
 ## 📦 Installation
 
+### 💻 on the Server (or Bundler)
+For Node.js, Bun, Deno, or projects using a bundler (Vite, Webpack, etc.), install via npm:
+
 ```bash
 npm install @magmacomputing/tempo
 ```
 
-### 💻 on the Server
 Tempo is a native ESM package. In Node.js (20+), simply import the class.
-Node.js, Bun and Deno support native ESM out of the box.
+Node.js, Bun, and Deno support native ESM out of the box.
 
 ```javascript
 import { Tempo } from '@magmacomputing/tempo';
@@ -79,34 +81,58 @@ console.log(t.format('{dd} {mon} {yyyy}'));
 ```
 
 ### 🌐 in the Browser (Import Maps)
-Since Tempo is a native ESM package, you can use it directly in modern browsers using `importmap`:
+Since Tempo is a native ESM package, you can use it directly in modern browsers using `importmap`. The **bundle** entrypoint includes all standard modules pre-registered, but requires a separate `Temporal` polyfill for current browser environments.
 
 ```html
 <script type="importmap">
 {
   "imports": {
-    "@magmacomputing/tempo": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo/dist/tempo.index.js"
+    "@magmacomputing/tempo": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo/bundle"
   }
 }
 </script>
 <script type="module">
-  import { Tempo } from '@magmacomputing/tempo';
+  import Tempo from '@magmacomputing/tempo';
   const t = new Tempo('next friday');
   console.log(t.format('{mon} {day}'));
 </script>
 ```
 
 ### 📦 in the Browser (Script Tag)
-For environments without `importmap` support or simple prototypes, use the bundled version:
+For environments without `importmap` support or simple prototypes, use the global bundle. This automatically attaches the `Tempo` class to the `window` object.
 
 ```html
-<script src="https://cdn.jsdelivr.net/npm/@magmacomputing/tempo/dist/tempo.bundle.js"></script>
+<script src="https://cdn.jsdelivr.net/npm/@magmacomputing/tempo/global"></script>
 <script>
   const t = new Tempo('tomorrow');
   console.log(t.toString());
 </script>
 ```
 
+### 🧪 Advanced: Granular ESM (Lite Build)
+For maximum performance, you can use the lean **Core** engine and opt-in to specific modules. This prevents loading unused logic and keeps your production bundle minimal.
+
+```html
+<script type="importmap">
+{
+  "imports": {
+    "@magmacomputing/tempo/core": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo/core",
+    "@magmacomputing/tempo/mutate": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo/mutate"
+  }
+}
+</script>
+<script type="module">
+  import { Tempo } from '@magmacomputing/tempo/core';
+  import { MutateModule } from '@magmacomputing/tempo/mutate';
+
+  // Opt-in to mutation logic
+  Tempo.extend(MutateModule);
+
+  const t = new Tempo().add({ days: 1 });
+  console.log(t.toString());
+</script>
+```
+
 ---
 
 ## 📚 Documentation

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.