Feature/wrap up

.coderabbit.yaml

@@ -1,5 +1,6 @@
 # .coderabbit.yaml
 reviews:
+  auto_title_instructions: "Generate a concise PR title that starts with a conventional commit type (feat, fix, chore, etc.) followed by a short imperative description of the change."
   path_filters:
     # Use "! " at the start of a pattern to EXCLUDE it from the review
     - "!**/doc/api/**"            # Ignore ONLY the generated TypeDoc API documentation

CHANGELOG.md

@@ -5,7 +5,7 @@ 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.10.2] - 2026-05-22
+## [2.11.0] - 2026-05-25
 
 ### Fixed
 - **Open Core Build Fallback**: Updated the `build:resolve` script to gracefully fallback to Open Core licensing types when the proprietary `@core` module is unavailable, resolving CI build failures in public GitHub Actions environments.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempo-monorepo",
-  "version": "2.10.2",
+  "version": "2.11.0",
   "private": true,
   "description": "Magma Computing Monorepo",
   "repository": {
@@ -43,4 +43,4 @@
   "overrides": {
     "esbuild": "^0.25.0"
   }
-}
+}

packages/library/CHANGELOG.md

@@ -5,6 +5,11 @@ 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.11.0] - 2026-05-25
+
+### Added
+- **Intl Utilities**: Added `getNF` (`Intl.NumberFormat`) memoization, along with `formatNumber` and `formatUnit` helper methods to `#library/international.library.js` to natively support plural-aware duration string generation.
+
 ## [2.8.0] - 2026-04-30
 
 ### Changed

packages/library/package.json

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

packages/library/src/common/international.library.ts

@@ -16,6 +16,11 @@ const getDTF = memoizeFunction((locale?: string) => {
 	return new Intl.DateTimeFormat(locale);
 });
 
+/** memoized helper for Intl.NumberFormat instances */
+const getNF = memoizeFunction((locale?: string, options?: Intl.NumberFormatOptions) => {
+	return new Intl.NumberFormat(locale, options);
+});
+
 /**
  * International Cookbook  
  * (using 'Intl' namespace objects)
@@ -53,6 +58,24 @@ export function formatList(list: string[], locale?: string, type: Intl.ListForma
 	}
 }
 
+/** return a localized number string */
+export function formatNumber(value: number, locale?: string, options?: Intl.NumberFormatOptions) {
+	try {
+		return getNF(locale, options).format(value);
+	} catch (e) {
+		return value.toString();
+	}
+}
+
+/** return a localized unit string (e.g., '2 days') */
+export function formatUnit(value: number, unit: string, locale?: string, unitDisplay: Intl.NumberFormatOptions['unitDisplay'] = 'long') {
+	try {
+		return getNF(locale, { style: 'unit', unit, unitDisplay }).format(value);
+	} catch (e) {
+		return `${value} ${unit}`;
+	}
+}
+
 /** try to infer hemisphere using the timezone's daylight-savings setting */
 export function getHemisphere(timeZone: string = getDateTimeFormat().timeZone) {
 	try {

packages/library/src/common/string.library.ts

@@ -140,3 +140,15 @@ export const pad = (nbr: string | number | bigint = 0, len = 2, fill?: string |
 export const padString = (str: string | number | bigint, pad = 6) =>
 	(isNumeric(str) ? asNumber(str).toFixed(2).toString() : str.toString() ?? '').padStart(pad, '\u007F');
 
+/** 
+ * Reconstructs a string from an array of char codes.
+ * Useful for hiding strings from minifiers and reverse-engineers.
+ */
+export const reveal = (codes: number[]): string => codes.map(c => String.fromCharCode(c)).join('');
+
+/**
+ * Converts a string into an array of char codes.
+ * Useful as a developer utility to generate the array to paste into `reveal()`.
+ */
+export const conceal = (str: string): number[] => str.split('').map(c => c.charCodeAt(0));
+

packages/tempo/.vitepress/config.ts

@@ -46,7 +46,8 @@ export default defineConfig({
           { text: 'Parse Planner', link: '/doc/tempo.planner' },
           { text: 'Regional Parsing (MDY)', link: '/doc/tempo.month-day' },
           { text: 'Smart Formatting', link: '/doc/tempo.format' },
-          { text: 'Layout Patterns', link: '/doc/tempo.layout' }
+          { text: 'Layout Patterns', link: '/doc/tempo.layout' },
+          { text: 'Duration Logic', link: '/doc/tempo.duration' }
         ]
       },
       {

packages/tempo/CHANGELOG.md

@@ -4,6 +4,16 @@ 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.11.0] - 2026-05-25
+
+### Added
+- **Duration Mathematics**: Introduced the `.balance()` method to `Tempo.Duration` objects to allow intelligent mathematical roll-up of duration units (e.g., converting 365 days into 1 year), with support for both strict calendar math and nominal overrides (`{ nominal: true }`).
+- **Duration Formatting**: Introduced the `.format()` method to `Tempo.Duration` objects. This uses a shared, memoized `#library` implementation of `Intl.NumberFormat` to generate highly localized, plural-aware duration strings with excellent performance and robust cross-environment execution (no `navigator` dependencies).
+- **Cascading Configuration**: Added `numberFormat` to the `IntlOptions` interface, allowing developers to set global formatting defaults (like `unitDisplay: 'short'`) via `Tempo.init()` that seamlessly cascade down to all `.format()` calls.
+
+### Fixed
+- **Parsing**: Resolved an engine edge-case where combining relative weekday modifiers with string-based period aliases (e.g., `<3 Wed afternoon`) would cause the parser to prematurely abort the relative offset, instead applying the period to the current system date.
 
 ## [2.10.1] - 2026-05-22
 

packages/tempo/bin/resolve-types.ts

@@ -1,11 +1,10 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { fileURLToPath } from 'node:url';
 
 /**
  * resolve-types.ts
  * 
- * Post-build utility to handle Type Definitions (#library -> lib/)
+ * Post-build utility to handle Type Definitions (#library -> dist/lib/)
  * - Synchronizes used library types into dist/lib/
  * - Rewrites path aliases in all .d.ts files
  */
@@ -14,19 +13,11 @@ const DIST_DIR = path.resolve('dist');
 const LIB_SRC_DIR = path.resolve('../library/dist/common');
 const LIB_DEST_DIR = path.resolve(DIST_DIR, 'lib');
 
-const __dirname = path.dirname(fileURLToPath(import.meta.url));
-const LIC_SRC_DIR = process.env.LIC_SRC_DIR || path.resolve(__dirname, '../../../../tempo-plugin/internal/@core/dist');
-
-const isPremiumAvailable = fs.existsSync(LIC_SRC_DIR);
-
-const LIC_DEST_DIR = path.resolve(DIST_DIR, 'lic');
-
 console.log('Resolving type definitions...');
 
 // 1. Ensure lib directory exists
-if (!fs.existsSync(LIB_DEST_DIR)) {
+if (!fs.existsSync(LIB_DEST_DIR))
   fs.mkdirSync(LIB_DEST_DIR, { recursive: true });
-}
 
 // 2. Identify used library modules from Rollup's JS output
 const usedModules = fs.readdirSync(LIB_DEST_DIR)
@@ -37,28 +28,11 @@ const usedModules = fs.readdirSync(LIB_DEST_DIR)
 usedModules.forEach(mod => {
   const src = path.join(LIB_SRC_DIR, `${mod}.d.ts`);
   const dest = path.join(LIB_DEST_DIR, `${mod}.d.ts`);
-  if (fs.existsSync(src)) {
+  if (fs.existsSync(src))
     fs.copyFileSync(src, dest);
-  }
 });
 
-// 4. Copy licensing core types
-if (!fs.existsSync(LIC_DEST_DIR)) fs.mkdirSync(LIC_DEST_DIR, { recursive: true });
-
-if (isPremiumAvailable) {
-  const licFiles = fs.readdirSync(LIC_SRC_DIR).filter(f => f.endsWith('.d.ts'));
-  licFiles.forEach(file => {
-    fs.copyFileSync(path.join(LIC_SRC_DIR, file), path.join(LIC_DEST_DIR, file));
-  });
-} else {
-  console.log('ℹ️  Premium licensing not found. Falling back to Open Core types.');
-  const defaultLicType = path.resolve(DIST_DIR, 'support/support.license.d.ts');
-  if (fs.existsSync(defaultLicType)) {
-    fs.copyFileSync(defaultLicType, path.join(LIC_DEST_DIR, 'index.d.ts'));
-  }
-}
-
-// 5. Walk through all .d.ts files in dist/ to rewrite aliases
+// 4. Walk through all .d.ts files in dist/ to rewrite aliases
 function walk(dir: string) {
   const files = fs.readdirSync(dir);
   for (const file of files) {
@@ -89,26 +63,20 @@ function rewrite(filePath: string) {
   }
 
   // Handle #tempo/license resolution
-  let licReplacement: string;
-  const isInsideLic = relToDist.startsWith('lic');
-  if (isInsideLic) {
-    licReplacement = './';
-  } else {
-    let prefix = '';
-    for (let i = 0; i < depth; i++) prefix += '../';
-    licReplacement = `${prefix || './'}lic/`;
-  }
+  let prefix = '';
+  for (let i = 0; i < depth; i++) prefix += '../';
+  let licReplacement = `${prefix || './'}support/support.license.js`;
 
   const updatedContent = content
-    .replace(/#library\/([^"')]+\.js)/g, (match, libPath) => {
+    .replace(/#library\/([^"')]+\.js)/g, (_, libPath) => {
       // NOTE: We use path.basename here because the @magmacomputing/library distribution 
       // is currently flat (dist/common/*.js), and our resolve process flattens all 
       // used library modules into the local dist/lib/ directory.
       const fileName = path.basename(libPath);
       return `${replacement}${fileName}`;
     })
-    .replace(/#library(['"])/g, (match, quote) => `${replacement}index.js${quote}`)
-    .replace(/#tempo\/license(['"])/g, (match, quote) => `${licReplacement}index.js${quote}`);
+    .replace(/#library(['"])/g, (_, quote) => `${replacement}index.js${quote}`)
+    .replace(/#tempo\/license(['"])/g, (_, quote) => `${licReplacement}${quote}`);
 
   if (content !== updatedContent) {
     fs.writeFileSync(filePath, updatedContent);

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

@@ -1,6 +1,16 @@
 # 📜 Version 2.x History
 
-## [v2.10.11] - 2026-05-23
+## [v2.11.0] - 2026-05-25
+### New Features
+
+- **Duration Mathematics**: Introduced the `.balance()` method to `Tempo.Duration` objects to allow intelligent mathematical roll-up of duration units (e.g., converting 365 days into 1 year), with support for both strict calendar math and nominal overrides (`{ nominal: true }`).
+- **Duration Formatting**: Introduced the `.format()` method to `Tempo.Duration` objects. This uses a shared, memoized `#library` implementation of `Intl.NumberFormat` to generate highly localized, plural-aware duration strings with excellent performance and robust cross-environment execution.
+- **Cascading Configuration**: Added `numberFormat` to the `IntlOptions` interface, allowing developers to set global formatting defaults (like `unitDisplay: 'short'`) via `Tempo.init()` that seamlessly cascade down to all `.format()` calls.
+
+### Fixed
+- **Open Core Build Fallback**: Updated the `build:resolve` script to gracefully fallback to Open Core licensing types when the proprietary `@core` module is unavailable, resolving CI build failures in public GitHub Actions environments.
+
+## [v2.10.1] - 2026-05-23
 ### New Features
 
 - Added support for license key discovery via global browser context