PR 4th review

Author: magmacomputing

packages/tempo/doc/tempo.cookbook.md

@@ -101,7 +101,7 @@ new Tempo('tomorrow afternoon');
 
 ::: tip
 **Looking for Internationalized Parsing?**  
-Tempo can automatically translate months, weekdays, and relative terms (like 'yesterday', 'today', 'tomorrow') into foreign languages using your `locale` configuration. See the [Smart Parsing Guide](./tempo.parse.md#internationalized-parsing-locales) for full documentation and current capabilities.
+Tempo can automatically translate months, weekdays, and relative terms (like 'yesterday', 'today', 'tomorrow') into foreign languages using your `locale` configuration. This requires enabling the parser option `parse: { localize: true }` (or the top-level `localize: true` flag) alongside your locale setting. See the [Smart Parsing Guide](./tempo.parse.md#internationalized-parsing-locales) for full documentation and current capabilities.
 :::
 
 ### Parsing Unix Timestamps

packages/tempo/doc/tempo.parse.md

@@ -131,10 +131,10 @@ Tempo can be instructed to automatically generate language-specific parsing rule
 ```typescript
 Tempo.init({ locale: 'fr-FR', parse: { localize: true } });
 
-// Natively understand French input out-of-the-box!
+// Natively understand French dates and core events!
 new Tempo('demain');            // parses as "tomorrow"
 new Tempo('15 fevrier 2026');   // parses as "15 February 2026"
-new Tempo('vendredi prochain'); // parses as "next Friday"
+new Tempo('vendredi');          // parses as the closest "Friday"
 ```
 
 #### How it Works & Accent Normalization
@@ -144,24 +144,30 @@ It also automatically **normalizes and strips accents** from these generated rul
 
 #### ⚠️ Current Limitations (What is NOT Available)
 While `Intl` provides a robust foundation for month and weekday translations, there are limits to auto-localization:
-*   **English Affixes**: Grammatical connector words like "ago", "next", "last", "in", and "from now" are heavily English-biased syntax rules. `Intl` does not provide translations for these parsing connectors, meaning `2 days ago` will only parse correctly if the keyword `ago` is used.
+*   **English Affixes**: Grammatical connector words like "ago", "next", "last", "in", and "from now" are heavily English-biased syntax rules. `Intl` does not provide translations for these parsing connectors. When using the `Tempo` constructor with `parse: { localize: true }`, a relative string like `2 days ago` or `next Friday` will only parse correctly if the English connector keywords (`ago`, `next`) are used, unless Custom Aliases are used to bridge the gap.
 *   **Time Units**: Words representing time units ("days", "weeks", "months") inside natural language strings are currently English-only.
 *   **Grammar Structure**: The parser expects sequences matching standard English formats (e.g., `[value] [unit] [affix]`). Highly inflected languages or completely different phrase structures might fail to parse.
 
 To bridge these gaps, you can register **Custom Aliases** (see below) to map foreign syntax to specific relative offsets manually!
 
 ### Custom Aliases (Events & Periods)
-You can teach the parser new words:
+You can teach the parser new words or entire foreign phrases to bridge translation gaps:
 
 ```typescript
 Tempo.init({
+  locale: 'fr-FR',
+  parse: { localize: true },
   event: {
+    // Map a full foreign phrase directly to an English-equivalent relative string
+    'vendredi prochain': () => 'next Friday',
+    // Or standard static events
     'launch': '2026-12-01',
     'party': () => 'next Friday 8pm'
   }
 });
 
-const t = new Tempo('party');
+const t1 = new Tempo('vendredi prochain'); // Parses accurately to next Friday
+const t2 = new Tempo('party');
 ```
 
 ### 🧠 Functional Alias Context

packages/tempo/plan/localized_modifiers.md

@@ -0,0 +1,32 @@
+# Localized Mathematical Modifiers
+
+## Objective
+Enable full localization of mathematical modifier terms (e.g., mapping `"prochain"` to `">"` or `"next"`) and gracefully handle grammatical structure variations, such as inverted word ordering (e.g., trailing modifiers like `[weekday] [modifier]` vs. the English default `[modifier] [weekday]`).
+
+## Architectural Considerations
+
+### 1. Decoupling Math from Hardcoded English
+Currently, the `parseModifier` function in `engine.lexer.ts` uses a strict `switch` statement that evaluates literal English strings (e.g., `case 'next': return 1`). 
+- **Challenge**: Passing foreign strings like `"prochain"` directly to this switch fails and defaults to `0`.
+- **Solution Space**: Introduce a pre-lexing normalization step or a `modifier` registry that maps foreign string literals to standard internal mathematical tokens (like `>`, `<`, `+`, `-`) before they hit the mathematical evaluator.
+
+### 2. Lexer & Master Guard Layout Flexibility
+Tempo’s `Token.wkd` and standard layouts (e.g., `Pattern.WkdTime`) currently expect modifiers in specific positions (often as prefixes, with limited hardcoded suffixes like `next|last` for English).
+- **Challenge**: When `parse: { localize: true }` is enabled, the localized snippet overrides completely drop trailing suffix captures.
+- **Solution Space**: Update `support.init.ts` and `support.default.ts` to dynamically generate both prefix and suffix capture groups (`<mod_pre>` and `<mod_suf>`) in the localized regexes, allowing the parser to extract the modifier regardless of which side of the noun it appears.
+
+### 3. Locale-Specific Grammatical Nuances
+Different languages place modifiers in different structural positions depending on the entity.
+- **Challenge**: A language might use a suffix for days (e.g., "vendredi prochain") but a prefix for other temporal periods.
+- **Solution Space**: Should structural expectations be strictly tied to `Intl` locale codes, or should the engine use a "greedy" approach where it just attempts to extract modifiers from either side of the token without strictly enforcing grammatical correctness?
+
+### 4. Configuration API Design
+How will developers interact with this new capability?
+- **Option A**: A brand new top-level configuration registry: `Tempo.init({ modifier: { 'prochain': 'next', 'dernier': 'last' } })`.
+- **Option B**: Expanding the existing `event` or `snippet` objects.
+- **Option C**: Can we extract these modifier words automatically from `Intl.RelativeTimeFormat`? (Investigate if `Intl` provides sufficient grammatical connector data).
+
+### 5. Performance Implications
+The core speed of Tempo relies heavily on Master Guard (RegEx) optimization and caching.
+- **Challenge**: Adding multiple optional prefix and suffix capture branches to core snippets (like `wkd` and `rel`) will increase the complexity and backtracking potential of the Master Guard patterns.
+- **Solution Space**: Ensure careful benchmarking when adding dynamic `<sfx>` groups to localized patterns.

packages/tempo/src/tempo.class.ts

@@ -294,13 +294,10 @@ export class Tempo {
 
 	/** get first Canonical name of a supplied locale */
 	private static _locale = (locale?: string) => {
+		const global = Context.global;
 		let language: string | undefined;
 
-		try {																										// lookup locale
-			language = canonicalLocale(locale!);
-		} catch (error) { }																			// catch unknown locale
-
-		const global = Context.global;
+		if (locale) language = canonicalLocale(locale);
 
 		return language ??
 			global?.navigator?.languages?.[0] ??									// fallback to current first navigator.languages[]
@@ -320,7 +317,6 @@ export class Tempo {
 			? Object.assign(Tempo.readStore(storeKey), providedOptions)
 			: providedOptions;
 
-		console.log('[$setConfig] providedOptions:', providedOptions, 'mergedOptions:', mergedOptions, 'isEmpty:', isEmpty(mergedOptions));
 		if (isEmpty(mergedOptions)) return;
 
 		// Apply options using extendState
@@ -636,6 +632,7 @@ export class Tempo {
 	static create(options: t.Options = {}): typeof Tempo {
 		const SandboxTempo = class extends (this as any) {
 			static [Symbol.toStringTag] = 'TempoSandbox';
+			static [$IsBase] = false;
 		}
 
 		const discovery = options.discovery;
@@ -702,10 +699,13 @@ export class Tempo {
 			setLogLevel(options.debug ?? Default?.debug ?? LOG.Info);
 
 			const rt = getRuntime();
-			rt.state = undefined;																	// force fresh state
-			const state = init(options);
+			const isBase = !!this[$IsBase];
+			if (isBase) rt.state = undefined;											// force fresh state
+
+			const baseState = isBase ? undefined : Object.getPrototypeOf(this)[$Internal]();
+			const state = init(options, isBase, baseState);
 			(state as any)._count = 0;
-			if (this[$IsBase]) {
+			if (isBase) {
 				_global = state;
 			} else {
 				ClassStates.set(this, state);