@nextera.one/tps-standard 0.5.1 → 0.5.2

package/src/index.ts

@@ -13,19 +13,54 @@
  * - Added geospatial cell systems (S2, H3, Plus Code, what3words)
  */
 
-export type CalendarCode = 'greg' | 'hij' | 'jul' | 'holo' | 'unix';
+// built-in drivers are registered automatically; importing them here
+// ensures they are included when the library bundler/tree-shaker runs.
+import { GregorianDriver } from "./drivers/gregorian";
+import { UnixDriver } from "./drivers/unix";
+import { TpsDriver } from "./drivers/tps";
+
+// Calendar codes are plain strings to allow arbitrary user-defined
+// calendars.  The library still exports constants for the built-in values but
+// callers may also supply their own codes.
+export const DefaultCalendars = {
+  TPS: "tps",
+  GREG: "greg",
+  HIJ: "hij",
+  JUL: "jul",
+  HOLO: "holo",
+  UNIX: "unix",
+} as const;
+
+/**
+ * Specifies the direction of the time-component hierarchy when serializing or
+ * deserializing a TPS string.  The default is `'descending'` (millennium → … →
+ * second), but `'ascending'` produces the reverse order.
+ */
+export enum TimeOrder {
+  DESC = "desc",
+  ASC = "asc",
+}
 
 export interface TPSComponents {
   // --- TEMPORAL ---
-  calendar: CalendarCode;
-  millennium?: number;
-  century?: number;
-  year?: number;
-  month?: number;
-  day?: number;
-  hour?: number;
-  minute?: number;
-  second?: number;
+  calendar: string;
+  // --- REQUIRED TEMPORAL FIELDS ---
+  // All of the traditional Gregorian components are now mandatory.  This
+  // reflects the fact that a valid TPS time object must contain a complete
+  // timestamp when using the canonical calendar formats.
+  millennium: number;
+  century: number;
+  year: number;
+  month: number;
+  day: number;
+  hour: number;
+  minute: number;
+  second: number;
+  /** Sub-second precision (0–999).  Encoded as the last `m` token. */
+  millisecond: number;
+  // --- OPTIONAL UNIX BACKUP ---
+  // `unixSeconds` remains optional to support the Unix driver and other
+  // cases where a simple epoch value is preferred.
   unixSeconds?: number;
 
   // --- SPATIAL: GPS Coordinates ---
@@ -53,6 +88,9 @@ export interface TPSComponents {
   /** Logical area within building */
   zone?: string;
 
+  /** Raw pre-@ space anchor (e.g. adm:city:SA:riyadh, node:api-1, net:ip4:203.0.113.10) */
+  spaceAnchor?: string;
+
   // --- SPATIAL: Privacy Markers ---
   /** Technical missing data (e.g. server log without GPS) */
   isUnknownLocation?: boolean;
@@ -69,6 +107,8 @@ export interface TPSComponents {
 
   // --- CONTEXT ---
   extensions?: Record<string, string>;
+
+  order?: TimeOrder;
 }
 
 // --- PLUGIN ARCHITECTURE ---
@@ -124,7 +164,7 @@ export interface TPSComponents {
  */
 export interface CalendarDriver {
   /** The calendar code this driver handles (e.g., 'hij', 'jul'). */
-  readonly code: CalendarCode;
+  readonly code: string;
 
   /**
    * Human-readable name for this calendar (optional).
@@ -133,25 +173,25 @@ export interface CalendarDriver {
   readonly name?: string;
 
   /**
-   * Converts a Gregorian Date to this calendar's components.
+   * Converts a Date to this calendar's components.
    * @param date - The Gregorian Date object.
    * @returns Partial TPS components for year, month, day, etc.
    */
-  fromGregorian(date: Date): Partial<TPSComponents>;
+  getComponentsFromDate(date: Date): Partial<TPSComponents>;
 
   /**
-   * Converts this calendar's components to a Gregorian Date.
+   * Converts this calendar's components to a Date.
    * @param components - Partial TPS components (year, month, day, etc.).
    * @returns A JavaScript Date object.
    */
-  toGregorian(components: Partial<TPSComponents>): Date;
+  getDateFromComponents(components: Partial<TPSComponents>): Date;
 
   /**
    * Generates a TPS time string for this calendar from a Date.
    * @param date - The Gregorian Date object.
-   * @returns A TPS time string (e.g., "T:hij.y1447.M07.d21...").
+   * @returns A TPS time string (e.g., "T:hij.y1447.m07.d21...").
    */
-  fromDate(date: Date): string;
+  getFromDate(date: Date): string;
 
   // --- NEW ENHANCED METHODS (Optional) ---
 
@@ -172,7 +212,7 @@ export interface CalendarDriver {
    * driver.parseDate('1447-07-21 14:30:00'); // → { year: 1447, month: 7, day: 21, hour: 14, ... }
    * ```
    */
-  parseDate?(input: string, format?: string): Partial<TPSComponents>;
+  parseDate(input: string, format?: string): Partial<TPSComponents>;
 
   /**
    * Format TPS components to a calendar-specific date string.
@@ -188,7 +228,7 @@ export interface CalendarDriver {
    * driver.format({ year: 1447, month: 7, day: 21 }, 'short'); // → '21/7/1447'
    * ```
    */
-  format?(components: Partial<TPSComponents>, format?: string): string;
+  format(components: Partial<TPSComponents>, format?: string): string;
 
   /**
    * Validate a calendar-specific date string or components.
@@ -202,7 +242,7 @@ export interface CalendarDriver {
    * driver.validate({ year: 1447, month: 7, day: 31 }); // → false (Rajab has 30 days)
    * ```
    */
-  validate?(input: string | Partial<TPSComponents>): boolean;
+  validate(input: string | Partial<TPSComponents>): boolean;
 
   /**
    * Get calendar metadata (month names, day names, etc.).
@@ -214,7 +254,7 @@ export interface CalendarDriver {
    * // → ['Muharram', 'Safar', 'Rabi I', ...]
    * ```
    */
-  getMetadata?(): CalendarMetadata;
+  getMetadata(): CalendarMetadata;
 }
 
 /**
@@ -241,8 +281,7 @@ export interface CalendarMetadata {
 
 export class TPS {
   // --- PLUGIN REGISTRY ---
-  private static readonly drivers: Map<CalendarCode, CalendarDriver> =
-    new Map();
+  private static readonly drivers: Map<string, CalendarDriver> = new Map();
 
   /**
    * Registers a calendar driver plugin.
@@ -257,63 +296,238 @@ export class TPS {
    * @param code - The calendar code.
    * @returns The driver or undefined.
    */
-  static getDriver(code: CalendarCode): CalendarDriver | undefined {
+  static getDriver(code: string): CalendarDriver | undefined {
     return this.drivers.get(code);
   }
 
   // --- REGEX ---
   // Updated for v0.5.0: supports L: anchors, A: actor, ! signature, structural & geospatial anchors
-  // Note: Complex regex - carefully balanced parentheses
+  // Tokens may appear in any order; actual semantic parsing happens in
+  // `parseTimeString()` so these patterns are intentionally permissive.
+  // regex simply ensures prefix, space, calendar, and token characters;
+  // token order is not enforced (parseTimeString handles semantics).
   private static readonly REGEX_URI = new RegExp(
-    '^tps://' +
-      // Location part (L: prefix optional for backward compat)
-      '(?:L:)?(?<space>' +
-      '~|-|unknown|redacted|hidden|' + // Privacy markers
-      's2=(?<s2>[a-fA-F0-9]+)|' + // S2 cell
-      'h3=(?<h3>[a-fA-F0-9]+)|' + // H3 cell
-      'plus=(?<plus>[A-Z0-9+]+)|' + // Plus Code
-      'w3w=(?<w3w>[a-z]+\\.[a-z]+\\.[a-z]+)|' + // what3words
-      'bldg=(?<bldg>[\\w-]+)(?:\\.floor=(?<floor>[\\w-]+))?(?:\\.room=(?<room>[\\w-]+))?(?:\\.zone=(?<zone>[\\w-]+))?|' + // Structural
-      '(?<lat>-?\\d+(?:\\.\\d+)?),(?<lon>-?\\d+(?:\\.\\d+)?)(?:,(?<alt>-?\\d+(?:\\.\\d+)?)m?)?' + // GPS
-      ')' +
-      // Optional Actor anchor
-      '(?:/A:(?<actor>[^/@]+))?' +
-      // Time part separator
-      '[/@]T:(?<calendar>[a-z]{3,4})\\.' +
-      // Time components
-      '(?:(?<unix>s\\d+(?:\\.\\d+)?)|m(?<millennium>-?\\d+)(?:\\.c(?<century>\\d+)(?:\\.y(?<year>\\d+)(?:\\.M(?<month>\\d{1,2})(?:\\.d(?<day>\\d{1,2})(?:\\.h(?<hour>\\d{1,2})(?:\\.n(?<minute>\\d{1,2})(?:\\.s(?<second>\\d{1,2}(?:\\.\\d+)?))?)?)?)?)?)?)?)' +
-      // Optional signature
-      '(?:!(?<signature>[^;?#]+))?' +
-      // Optional extensions
-      '(?:;(?<extensions>[a-z0-9.\\-_=]+))?' +
-      // Optional query params
-      '(?:\\?(?<params>[^#]+))?' +
-      // Optional context
-      '(?:#(?<context>.+))?$',
+    "^tps://" +
+      // Location part (preserve named captures for space subfields)
+      "(?:L:)?(?<space>" +
+      "~|-|unknown|redacted|hidden|" +
+      "s2=(?<s2>[a-fA-F0-9]+)|" +
+      "h3=(?<h3>[a-fA-F0-9]+)|" +
+      "plus=(?<plus>[A-Z0-9+]+)|" +
+      "w3w=(?<w3w>[a-z]+\\.[a-z]+\\.[a-z]+)|" +
+      "bldg=(?<bldg>[\\w-]+)(?:\\.floor=(?<floor>[\\w-]+))?(?:\\.room=(?<room>[\\w-]+))?(?:\\.zone=(?<zone>[\\w-]+))?|" +
+      "(?<lat>-?\\d+(?:\\.\\d+)?),(?<lon>-?\\d+(?:\\.\\d+)?)(?:,(?<alt>-?\\d+(?:\\.\\d+)?)m?)?|" +
+      "(?<generic>[^@/?#]+)" +
+      ")" +
+      "(?:/A:(?<actor>[^/@]+))?" +
+      "@T:(?<calendar>[a-z]{3,4})" +
+      "(?:\\.(?:m-?\\d+|c\\d+|y\\d+|d\\d{1,2}|h\\d{1,2}|s\\d+(?:\\.\\d+)?))*" +
+      "(?:![^;?#]+)?" +
+      "(?:;(?<extensions>[^?#]+))?" +
+      "(?:\\?[^#]+)?" +
+      "(?:#.+)?$",
   );
 
   private static readonly REGEX_TIME = new RegExp(
-    '^T:(?<calendar>[a-z]{3,4})\\.' +
-      '(?:(?<unix>s\\d+(?:\\.\\d+)?)|m(?<millennium>-?\\d+)(?:\\.c(?<century>\\d+)(?:\\.y(?<year>\\d+)(?:\\.M(?<month>\\d{1,2})(?:\\.d(?<day>\\d{1,2})(?:\\.h(?<hour>\\d{1,2})(?:\\.n(?<minute>\\d{1,2})(?:\\.s(?<second>\\d{1,2}(?:\\.\\d+)?))?)?)?)?)?)?)?)' +
-      '(?:!(?<signature>[^;?#]+))?$',
+    "^T:(?<calendar>[a-z]{3,4})" +
+      "(?:\\.(?:m-?\\d+|c\\d+|y\\d+|d\\d{1,2}|h\\d{1,2}|s\\d+(?:\\.\\d+)?))*" +
+      "(?:![^;?#]+)?$",
   );
 
   // --- CORE METHODS ---
 
+  /**
+   * SANITIZER: Normalises a raw TPS input string before validation.
+   *
+   * Pure string-based — no parsing into components, no regex beyond simple
+   * character checks, no re-serialisation via buildTimePart / toURI.
+   *
+   * Token ranks (descending): m(8) c(7) y(6) m(5) d(4) h(3) m(2) s(1) m(0)
+   */
+  static sanitizeTimeInput(input: string): string {
+    // ── 1. Whitespace ────────────────────────────────────────────────────────
+    let s = input.trim().replace(/\s+/g, "");
+    if (!s) return s;
+
+    // ── 1.5 Convert legacy "/T:" separators to the new canonical "@T:".
+    // The input may contain "/T:" from older versions; we normalise early so
+    // subsequent logic can assume only the '@' form.
+    if (s.includes("/T:")) {
+      s = s.replace(/\/T:/g, "@T:");
+    }
+
+    // ── 2. Scheme casing ─────────────────────────────────────────────────────
+    if (s.slice(0, 6).toLowerCase() === "tps://") {
+      s = "tps://" + s.slice(6);
+    }
+
+    // ── 3. T: prefix casing (time-only strings) ──────────────────────────────
+    if (!s.startsWith("tps://") && s.slice(0, 2).toLowerCase() === "t:") {
+      s = "T:" + s.slice(2);
+    }
+
+    // ── 4. Locate T: section ─────────────────────────────────────────────────
+    let tStart = -1;
+    if (s.startsWith("T:")) {
+      tStart = 0;
+    } else {
+      const atT = s.indexOf("@T:");
+      if (atT !== -1) tStart = atT + 1;
+    }
+    if (tStart === -1) return s; // no T: section — return as-is
+
+    const beforeT = s.slice(0, tStart); // URI prefix or empty
+    const timeAndRest = s.slice(tStart); // T:cal.tok...  [!sig][;ext]
+
+    // Isolate token section from any trailing suffix (!sig / ;ext / ?q / #f)
+    const suffixIdx = timeAndRest.search(/[!;?#]/);
+    const timeSuffix = suffixIdx !== -1 ? timeAndRest.slice(suffixIdx) : "";
+    const timePart =
+      suffixIdx !== -1 ? timeAndRest.slice(0, suffixIdx) : timeAndRest;
+    // timePart = "T:greg.m3.c1.y26.m01.d07.h13.m20.s45"
+
+    // Split off calendar code
+    const afterColon = timePart.slice(timePart.indexOf(":") + 1); // "greg.m3.c1..."
+    const firstDot = afterColon.indexOf(".");
+    const cal = (
+      firstDot !== -1 ? afterColon.slice(0, firstDot) : afterColon
+    ).toLowerCase();
+    const tokenStr = firstDot !== -1 ? afterColon.slice(firstDot + 1) : "";
+
+    // If no calendar code was provided at all (e.g. "T:"), bail out early
+    // rather than inventing a default calendar.  The string will remain
+    // unparsable so validation can report it as invalid.
+    if (!cal) {
+      return s;
+    }
+
+    // No tokens at all — fill every slot with 0 and return
+    // Use tps as the default calendar if none was specified
+    const resolvedCal = cal || DefaultCalendars.TPS;
+    if (!tokenStr) {
+      return `${beforeT}T:${resolvedCal}.m0.c0.y0.m0.d0.h0.m0.s0.m0${timeSuffix}`;
+    }
+
+    // ── 5. Tokenise ──────────────────────────────────────────────────────────
+    // Each raw token: first char = letter prefix, remainder = numeric value
+    type Tok = { p: string; v: string };
+    const tokens: Tok[] = tokenStr
+      .split(".")
+      .filter((t) => t.length >= 2 && /^[a-z]/.test(t))
+      .map((t) => ({ p: t[0], v: t.slice(1) }));
+
+    // ── 6. Detect order from non-m tokens (c=7, y=6, d=4, h=3, s=1) ─────────
+    const nonMRank: Record<string, number> = { c: 7, y: 6, d: 4, h: 3, s: 1 };
+    const nonMSeq = tokens
+      .filter((t) => t.p !== "m" && nonMRank[t.p] !== undefined)
+      .map((t) => nonMRank[t.p]);
+
+    let isAsc = false;
+    if (nonMSeq.length >= 2) {
+      // ascending when every consecutive rank-diff is positive
+      isAsc = nonMSeq.every((r, i) => i === 0 || r > nonMSeq[i - 1]);
+    }
+
+    // ── 7. Reverse tokens if ascending ───────────────────────────────────────
+    if (isAsc) tokens.reverse();
+
+    // ── 8. Disambiguate 'm' tokens by DESC position ──────────────────────────
+    // DESC slot order for m tokens: rank 8 (millennium), 5 (month), 2 (minute), 0 (ms)
+    const mDescRanks = [8, 5, 2, 0];
+    const byRank = new Map<number, string>();
+    let mIdx = 0;
+
+    for (const tok of tokens) {
+      if (tok.p === "m") {
+        if (mIdx < mDescRanks.length) byRank.set(mDescRanks[mIdx++], tok.v);
+      } else {
+        const r = nonMRank[tok.p];
+        if (r !== undefined) byRank.set(r, tok.v);
+      }
+    }
+
+    // ── 9. Build complete DESC token string, filling gaps with '0' ───────────
+    // Full DESC slot sequence: m(8) c(7) y(6) m(5) d(4) h(3) m(2) s(1) m(0)
+    const descSlots: Array<[string, number]> = [
+      ["m", 8],
+      ["c", 7],
+      ["y", 6],
+      ["m", 5],
+      ["d", 4],
+      ["h", 3],
+      ["m", 2],
+      ["s", 1],
+      ["m", 0],
+    ];
+
+    const finalTokenStr = descSlots
+      .map(([p, r]) => p + (byRank.get(r) ?? "0"))
+      .join(".");
+
+    return `${beforeT}T:${resolvedCal}.${finalTokenStr}${timeSuffix}`;
+  }
+
   static validate(input: string): boolean {
-    if (input.startsWith('tps://')) return this.REGEX_URI.test(input);
-    return this.REGEX_TIME.test(input);
+    const sanitized = this.sanitizeTimeInput(input);
+    if (sanitized.startsWith("tps://")) {
+      return this.REGEX_URI.test(sanitized);
+    }
+    return this.REGEX_TIME.test(sanitized);
   }
 
   static parse(input: string): TPSComponents | null {
-    if (input.startsWith('tps://')) {
+    // Always sanitize first so we operate on the canonical form.  This also
+    // rewrites any legacy "/T:" separators to "@T:" so the regex below can
+    // remain strict.
+    input = this.sanitizeTimeInput(input);
+
+    // quick fail via regex to rule out obviously bad strings
+    if (input.startsWith("tps://")) {
       const match = this.REGEX_URI.exec(input);
       if (!match || !match.groups) return null;
-      return this._mapGroupsToComponents(match.groups);
+      const comp: any = this._mapGroupsToComponents(match.groups);
+      // extract the raw time portion and parse it separately
+      const atIdx = input.indexOf("@T:");
+      let timeStr = "";
+      let signature: string | undefined;
+      if (atIdx !== -1) {
+        timeStr = input.slice(atIdx + 1); // include the leading 'T:'
+        // if there's a signature, capture it first
+        const sigMatch = timeStr.match(/!(?<sig>[^;?#]+)/);
+        if (sigMatch && sigMatch.groups && sigMatch.groups.sig) {
+          signature = sigMatch.groups.sig;
+        }
+        // cut off signature, extensions, query, or fragment
+        timeStr = timeStr.split(/[!;?#]/)[0];
+      }
+      if (timeStr) {
+        const parsed = this.parseTimeString(timeStr);
+        if (!parsed) return null;
+        Object.assign(comp, parsed.components);
+        comp.order = parsed.order;
+      }
+      if (signature) {
+        comp.signature = signature;
+      }
+      return comp as TPSComponents;
     }
+    // time-only string
     const match = this.REGEX_TIME.exec(input);
     if (!match || !match.groups) return null;
-    return this._mapGroupsToComponents(match.groups);
+    // isolate signature if present
+    let timeOnly = input;
+    let signature: string | undefined;
+    const sigMatch = input.match(/!(?<sig>[^;?#]+)/);
+    if (sigMatch && sigMatch.groups && sigMatch.groups.sig) {
+      signature = sigMatch.groups.sig;
+      timeOnly = input.split(/[!;?#]/)[0];
+    }
+    const parsed = this.parseTimeString(timeOnly);
+    if (!parsed) return null;
+    const comp = parsed.components as TPSComponents;
+    if (signature) comp.signature = signature;
+    comp.order = parsed.order;
+    return comp;
   }
 
   /**
@@ -323,14 +537,16 @@ export class TPS {
    */
   static toURI(comp: TPSComponents): string {
     // 1. Build Space Part (L: anchor)
-    let spacePart = 'L:-'; // Default: unknown
+    let spacePart = "L:-"; // Default: unknown
 
-    if (comp.isHiddenLocation) {
-      spacePart = 'L:~';
+    if (comp.spaceAnchor) {
+      spacePart = comp.spaceAnchor;
+    } else if (comp.isHiddenLocation) {
+      spacePart = "L:~";
     } else if (comp.isRedactedLocation) {
-      spacePart = 'L:redacted';
+      spacePart = "L:redacted";
     } else if (comp.isUnknownLocation) {
-      spacePart = 'L:-';
+      spacePart = "L:-";
     } else if (comp.s2Cell) {
       spacePart = `L:s2=${comp.s2Cell}`;
     } else if (comp.h3Cell) {
@@ -352,85 +568,87 @@ export class TPS {
     }
 
     // 2. Build Actor Part (A: anchor) - optional
-    let actorPart = '';
+    let actorPart = "";
     if (comp.actor) {
       actorPart = `/A:${comp.actor}`;
     }
 
-    // 3. Build Time Part
-    let timePart = `T:${comp.calendar}`;
-
-    if (comp.calendar === 'unix' && comp.unixSeconds !== undefined) {
-      timePart += `.s${comp.unixSeconds}`;
-    } else {
-      if (comp.millennium !== undefined) timePart += `.m${comp.millennium}`;
-      if (comp.century !== undefined) timePart += `.c${comp.century}`;
-      if (comp.year !== undefined) timePart += `.y${comp.year}`;
-      if (comp.month !== undefined) timePart += `.M${this.pad(comp.month)}`;
-      if (comp.day !== undefined) timePart += `.d${this.pad(comp.day)}`;
-      if (comp.hour !== undefined) timePart += `.h${this.pad(comp.hour)}`;
-      if (comp.minute !== undefined) timePart += `.n${this.pad(comp.minute)}`;
-      if (comp.second !== undefined) timePart += `.s${this.pad(comp.second)}`;
-    }
-
-    // 4. Add Signature (!) - optional
-    if (comp.signature) {
-      timePart += `!${comp.signature}`;
-    }
+    // 3. Build Time Part (handles order & signature)
+    const timePart = this.buildTimePart(comp);
 
     // 5. Build Extensions
-    let extPart = '';
+    let extPart = "";
     if (comp.extensions && Object.keys(comp.extensions).length > 0) {
       const extStrings = Object.entries(comp.extensions).map(
         ([k, v]) => `${k}=${v}`,
       );
-      extPart = `;${extStrings.join('.')}`;
+      extPart = `;${extStrings.join(".")}`;
     }
 
-    return `tps://${spacePart}${actorPart}/${timePart}${extPart}`;
+    // timePart already begins with 'T:'.  The new canonical separator is '@'
+    // instead of '/', so we interpolate it accordingly.  Actor anchor (if
+    // present) still uses a leading slash.
+    return `tps://${spacePart}${actorPart}@${timePart}${extPart}`;
   }
 
   /**
    * CONVERTER: Creates a TPS Time Object string from a JavaScript Date.
    * Supports plugin drivers for non-Gregorian calendars.
    * @param date - The JS Date object (defaults to Now).
-   * @param calendar - The target calendar driver (default 'greg').
-   * @returns Canonical string (e.g., "T:greg.m3.c1.y26...").
+   * @param calendar - The target calendar driver (default `"tps"`).
+   * @param opts - Optional parameters; for built-in calendars the only
+   *   supported key is `order` which may be `'ascending'` or `'descending'`.
+   * @returns Canonical string (e.g., "T:tps.m3.c1.y26...").
    */
   static fromDate(
     date: Date = new Date(),
-    calendar: CalendarCode = 'greg',
+    calendar: string = DefaultCalendars.TPS,
+    opts?: { order?: TimeOrder },
   ): string {
-    // Check for registered driver first
-    const driver = this.drivers.get(calendar);
+    const normalizedCalendar = calendar.toLowerCase();
+    const driver = this.drivers.get(normalizedCalendar);
     if (driver) {
-      return driver.fromDate(date);
+      // when caller requested an explicit order we can bypass the driver's
+      // `fromDate` helper and instead generate components ourselves so that
+      // order is honoured even if the driver doesn't know about it.  This
+      // keeps behaviour identical to the old built-in implementation.
+      if (opts?.order) {
+        const comp = driver.getComponentsFromDate(date) as TPSComponents;
+        comp.calendar = normalizedCalendar;
+        comp.order = opts.order;
+        return this.buildTimePart(comp);
+      }
+      return driver.getFromDate(date);
     }
 
-    // Built-in handlers
-    if (calendar === 'unix') {
+    // Fallback for old built-in calendars (shouldn't happen once drivers are
+    // registered, but kept for backwards compatibility).
+    const comp: TPSComponents = { calendar: normalizedCalendar } as any;
+
+    if (normalizedCalendar === DefaultCalendars.UNIX) {
       const s = (date.getTime() / 1000).toFixed(3);
-      return `T:unix.s${s}`;
+      comp.unixSeconds = parseFloat(s);
+      if (opts?.order) comp.order = opts.order;
+      return this.buildTimePart(comp);
     }
 
-    if (calendar === 'greg') {
+    if (normalizedCalendar === DefaultCalendars.GREG) {
       const fullYear = date.getUTCFullYear();
-      const m = Math.floor(fullYear / 1000) + 1;
-      const c = Math.floor((fullYear % 1000) / 100) + 1;
-      const y = fullYear % 100;
-      const M = date.getUTCMonth() + 1;
-      const d = date.getUTCDate();
-      const h = date.getUTCHours();
-      const n = date.getUTCMinutes();
-      const s = date.getUTCSeconds();
-
-      return `T:greg.m${m}.c${c}.y${y}.M${this.pad(M)}.d${this.pad(
-        d,
-      )}.h${this.pad(h)}.n${this.pad(n)}.s${this.pad(s)}`;
+      comp.millennium = Math.floor(fullYear / 1000) + 1;
+      comp.century = Math.floor((fullYear % 1000) / 100) + 1;
+      comp.year = fullYear % 100;
+      comp.month = date.getUTCMonth() + 1;
+      comp.day = date.getUTCDate();
+      comp.hour = date.getUTCHours();
+      comp.minute = date.getUTCMinutes();
+      comp.second = date.getUTCSeconds();
+      comp.millisecond = date.getUTCMilliseconds();
+      if (opts?.order) comp.order = opts.order;
+      return this.buildTimePart(comp);
     }
 
     throw new Error(
-      `Calendar driver '${calendar}' not implemented. Register a driver.`,
+      `Calendar driver '${normalizedCalendar}' not implemented. Register a driver.`,
     );
   }
 
@@ -441,7 +659,7 @@ export class TPS {
    * @param targetCalendar - The target calendar code (e.g., 'hij').
    * @returns A TPS string in the target calendar, or null if invalid.
    */
-  static to(targetCalendar: CalendarCode, tpsString: string): string | null {
+  static to(targetCalendar: string, tpsString: string): string | null {
     // 1. Parse to components and convert to Gregorian Date
     const gregDate = this.toDate(tpsString);
     if (!gregDate) return null;
@@ -457,45 +675,25 @@ export class TPS {
    * @returns JS Date object or `null` if invalid.
    */
   static toDate(tpsString: string): Date | null {
-    const p = this.parse(tpsString);
-    if (!p) return null;
+    const parsed = this.parse(tpsString);
+    if (!parsed) return null;
 
-    // Check for registered driver first
-    const driver = this.drivers.get(p.calendar);
-    if (driver) {
-      return driver.toGregorian(p);
-    }
+    const cal = parsed.calendar || DefaultCalendars.TPS;
 
-    // Built-in handlers
-    if (p.calendar === 'unix' && p.unixSeconds !== undefined) {
-      return new Date(p.unixSeconds * 1000);
+    const driver = this.drivers.get(cal);
+    if (!driver) {
+      console.error(`Calendar driver '${cal}' not registered.`);
+      return null;
     }
 
-    if (p.calendar === 'greg') {
-      const m = p.millennium || 0;
-      const c = p.century || 1;
-      const y = p.year || 0;
-      const fullYear = (m - 1) * 1000 + (c - 1) * 100 + y;
-
-      return new Date(
-        Date.UTC(
-          fullYear,
-          (p.month || 1) - 1,
-          p.day || 1,
-          p.hour || 0,
-          p.minute || 0,
-          Math.floor(p.second || 0),
-        ),
-      );
-    }
-    return null;
+    return driver.getDateFromComponents(parsed);
   }
 
   // --- DRIVER CONVENIENCE METHODS ---
 
   /**
    * Parse a calendar-specific date string into TPS components.
-   * Requires the driver to implement the optional `parseDate` method.
+   * Requires the driver to implement `parseDate`.
    *
    * @param calendar - The calendar code (e.g., 'hij')
    * @param dateString - Date string in calendar-native format (e.g., '1447-07-21')
@@ -508,11 +706,11 @@ export class TPS {
    * // { calendar: 'hij', year: 1447, month: 7, day: 21 }
    *
    * const uri = TPS.toURI({ ...components, latitude: 31.95, longitude: 35.91 });
-   * // "tps://31.95,35.91@T:hij.y1447.M07.d21"
+   * // "tps://31.95,35.91@T:hij.y1447.m07.d21"
    * ```
    */
   static parseCalendarDate(
-    calendar: CalendarCode,
+    calendar: string,
     dateString: string,
     format?: string,
   ): Partial<TPSComponents> | null {
@@ -522,11 +720,7 @@ export class TPS {
         `Calendar driver '${calendar}' not found. Register a driver first.`,
       );
     }
-    if (!driver.parseDate) {
-      throw new Error(
-        `Driver '${calendar}' does not implement parseDate(). Use fromGregorian() instead.`,
-      );
-    }
+    // parseDate is guaranteed by the interface, so we can call it directly.
     return driver.parseDate(dateString, format);
   }
 
@@ -543,19 +737,19 @@ export class TPS {
    * ```ts
    * // With coordinates
    * TPS.fromCalendarDate('hij', '1447-07-21', { latitude: 31.95, longitude: 35.91 });
-   * // "tps://31.95,35.91@T:hij.y1447.M07.d21"
+   * // "tps://31.95,35.91@T:hij.y1447.m07.d21"
    *
    * // With privacy flag
    * TPS.fromCalendarDate('hij', '1447-07-21', { isHiddenLocation: true });
-   * // "tps://hidden@T:hij.y1447.M07.d21"
+   * // "tps://hidden@T:hij.y1447.m07.d21"
    *
    * // Without location
    * TPS.fromCalendarDate('hij', '1447-07-21');
-   * // "tps://unknown@T:hij.y1447.M07.d21"
+   * // "tps://unknown@T:hij.y1447.m07.d21"
    * ```
    */
   static fromCalendarDate(
-    calendar: CalendarCode,
+    calendar: string,
     dateString: string,
     location?: {
       latitude?: number;
@@ -573,7 +767,7 @@ export class TPS {
 
     // Merge with location
     const fullComponents: TPSComponents = {
-      calendar,
+      calendar: calendar,
       ...components,
       ...location,
     } as TPSComponents;
@@ -583,7 +777,7 @@ export class TPS {
 
   /**
    * Format TPS components to a calendar-specific date string.
-   * Requires the driver to implement the optional `format` method.
+   * Requires the driver to implement `format`.
    *
    * @param calendar - The calendar code
    * @param components - TPS components to format
@@ -592,13 +786,13 @@ export class TPS {
    *
    * @example
    * ```ts
-   * const tps = TPS.parse('tps://unknown@T:hij.y1447.M07.d21');
+   * const tps = TPS.parse('tps://unknown@T:hij.y1447.m07.d21');
    * const formatted = TPS.formatCalendarDate('hij', tps);
    * // "1447-07-21"
    * ```
    */
   static formatCalendarDate(
-    calendar: CalendarCode,
+    calendar: string,
     components: Partial<TPSComponents>,
     format?: string,
   ): string {
@@ -606,33 +800,234 @@ export class TPS {
     if (!driver) {
       throw new Error(`Calendar driver '${calendar}' not found.`);
     }
-    if (!driver.format) {
-      throw new Error(`Driver '${calendar}' does not implement format().`);
-    }
+    // format is guaranteed by the interface, so we can call it directly.
     return driver.format(components, format);
   }
 
   // --- INTERNAL HELPERS ---
 
+  /**
+   * Generate the canonical `T:` time string for a set of components.  The
+   * `order` field (or `comp.order`) controls whether tokens are emitted in
+   * ascending or descending hierarchy; if undefined the default
+   * `'descending'` orientation is used.
+   *
+   * Drivers may ignore this helper and produce their own time strings if they
+   * implement custom ordering logic.
+   */
+  public static buildTimePart(comp: TPSComponents): string {
+    const calendar = (comp.calendar || "").toLowerCase();
+    if (!/^[a-z]{3,4}$/.test(calendar)) {
+      throw new Error(
+        `Invalid calendar code '${comp.calendar}'. Calendar code width must be 3–4 lowercase letters.`,
+      );
+    }
+
+    let time = `T:${calendar}`;
+    if (calendar === DefaultCalendars.UNIX) {
+      if (comp.unixSeconds !== undefined) {
+        time += `.s${comp.unixSeconds}`;
+      }
+      return time;
+    }
+
+    // sequence of [prefix, value, rank]
+    // All four of millennium / month / minute / millisecond share the prefix 'm'.
+    // Position within the ordered sequence disambiguates them during parsing.
+    const tokens: Array<[string, number | undefined, number]> = [
+      ["m", comp.millennium, 8], // m-token rank 8 → millennium
+      ["c", comp.century, 7],
+      ["y", comp.year, 6],
+      ["m", comp.month, 5], // m-token rank 5 → month
+      ["d", comp.day, 4],
+      ["h", comp.hour, 3],
+      ["m", comp.minute, 2], // m-token rank 2 → minute
+      ["s", comp.second, 1],
+      ["m", comp.millisecond, 0], // m-token rank 0 → millisecond
+    ];
+
+    const order: TimeOrder = comp.order || TimeOrder.DESC;
+    if (order === TimeOrder.ASC) tokens.reverse();
+
+    for (const [pref, val] of tokens) {
+      if (val !== undefined) {
+        // seconds may be fractional
+        time += `.${pref}${val}`;
+      }
+    }
+
+    if (comp.signature) {
+      time += `!${comp.signature}`;
+    }
+
+    return time;
+  }
+
+  /**
+   * Parse the *time* portion of a TPS string (optionally beginning with
+   * `T:`) into components and determine the component ordering.  This helper
+   * accepts tokens in **any** sequence and will return an `order` value of
+   * `'ascending'` or `'descending'`.
+   *
+   * The caller is responsible for stripping off a leading signature or other
+   * trailer characters; this method will drop anything after `!`, `;`, `?` or
+   * `#`.
+   *
+   * ### `m`-token disambiguation
+   * All four of millennium (rank 8), month (rank 5), minute (rank 2) and
+   * millisecond (rank 0) share the single-character prefix `m`.  They are told
+   * apart by their **position relative to the neighbouring tokens**.  The
+   * algorithm is:
+   *
+   * 1. Pre-scan the non-`m` tokens (c, y, d, h, s) whose ranks are fixed to
+   *    determine whether the string is ascending or descending.
+   * 2. While iterating, track `lastAssignedRank` – the rank of the most
+   *    recently processed token (m or non-m).
+   * 3. When an `m` token is encountered, derive its rank from `lastAssignedRank`
+   *    and the detected order:
+   *    - **DESC**  null → 8 (mill) | rank > 5 → 5 (month) | rank > 2 → 2 (min) | else → 0 (ms)
+   *    - **ASC**   null → 0 (ms)   | rank < 2 → 2 (min)   | rank < 5 → 5 (month) | else → 8 (mill)
+   *
+   * @param input - Time fragment (e.g. `"T:greg.m3.c1.y26"` or `"greg.m0.s25.m30"`)
+   */
+  static parseTimeString(
+    input: string,
+  ): { components: Partial<TPSComponents>; order: TimeOrder } | null {
+    let s = input.trim();
+    // strip off anything after signature or extensions/query/fragment
+    s = s.split(/[!;?#]/)[0];
+    if (s.startsWith("T:")) s = s.slice(2);
+    const parts = s.split(".");
+    if (parts.length === 0) return null;
+    const calendar = parts[0];
+    const comp: Partial<TPSComponents> = { calendar };
+
+    // Fixed-rank prefixes (unambiguous regardless of position)
+    const fixedRankMap: Record<string, number> = {
+      c: 7,
+      y: 6,
+      d: 4,
+      h: 3,
+      s: 1,
+    };
+
+    // ── Step 1: pre-scan non-m tokens to estimate order ─────────────────────
+    // This is only needed to handle the first 'm' token when lastAssignedRank
+    // is still null (nothing has been seen yet).
+    let initialOrder: TimeOrder = TimeOrder.DESC;
+    if (calendar !== DefaultCalendars.UNIX) {
+      const nonMRanks: number[] = [];
+      for (let i = 1; i < parts.length; i++) {
+        const pr = parts[i]?.charAt(0);
+        if (pr && pr in fixedRankMap) nonMRanks.push(fixedRankMap[pr]);
+      }
+      if (nonMRanks.length >= 2) {
+        const isAsc = nonMRanks.every((v, i, a) => i === 0 || a[i - 1] <= v);
+        if (isAsc) initialOrder = TimeOrder.ASC;
+      }
+    }
+
+    // ── Step 2: resolve the semantic rank of an 'm' token ───────────────────
+    const assignMRank = (lastRank: number | null, ord: TimeOrder): number => {
+      if (ord === TimeOrder.DESC) {
+        if (lastRank === null) return 8; // first token → millennium
+        if (lastRank > 5) return 5; // after century / year  → month
+        if (lastRank > 2) return 2; // after day / hour      → minute
+        return 0; // after second          → millisecond
+      } else {
+        if (lastRank === null) return 0; // first token → millisecond
+        if (lastRank < 2) return 2; // after millisecond / second → minute
+        if (lastRank < 5) return 5; // after minute / hour / day  → month
+        return 8; // after month / year / cent  → millennium
+      }
+    };
+
+    // ── Step 3: iterate and build components ────────────────────────────────
+    const ranks: number[] = [];
+    let lastAssignedRank: number | null = null;
+
+    for (let i = 1; i < parts.length; i++) {
+      const token = parts[i];
+      if (!token) continue;
+      const prefix = token.charAt(0);
+      const value = token.slice(1);
+
+      // UNIX calendar: single 's' token carries the full unix timestamp
+      if (calendar === DefaultCalendars.UNIX && prefix === "s") {
+        comp.unixSeconds = parseFloat(value);
+        ranks.push(9);
+        continue;
+      }
+
+      if (prefix === "m") {
+        const rank = assignMRank(lastAssignedRank, initialOrder);
+        switch (rank) {
+          case 8:
+            comp.millennium = parseInt(value, 10);
+            break;
+          case 5:
+            comp.month = parseInt(value, 10);
+            break;
+          case 2:
+            comp.minute = parseInt(value, 10);
+            break;
+          case 0:
+            comp.millisecond = parseInt(value, 10);
+            break;
+        }
+        ranks.push(rank);
+        lastAssignedRank = rank;
+      } else {
+        switch (prefix) {
+          case "c":
+            comp.century = parseInt(value, 10);
+            ranks.push(7);
+            lastAssignedRank = 7;
+            break;
+          case "y":
+            comp.year = parseInt(value, 10);
+            ranks.push(6);
+            lastAssignedRank = 6;
+            break;
+          case "d":
+            comp.day = parseInt(value, 10);
+            ranks.push(4);
+            lastAssignedRank = 4;
+            break;
+          case "h":
+            comp.hour = parseInt(value, 10);
+            ranks.push(3);
+            lastAssignedRank = 3;
+            break;
+          case "s":
+            comp.second = parseFloat(value);
+            ranks.push(1);
+            lastAssignedRank = 1;
+            break;
+          default:
+            // unknown prefix – ignore
+            break;
+        }
+      }
+    }
+
+    // ── Step 4: confirm order from the complete rank sequence ────────────────
+    let order: TimeOrder = TimeOrder.DESC;
+    if (ranks.length > 1) {
+      const isAsc = ranks.every((v, i, a) => i === 0 || a[i - 1] <= v);
+      const isDesc = ranks.every((v, i, a) => i === 0 || a[i - 1] >= v);
+      if (isAsc && !isDesc) order = TimeOrder.ASC;
+      // mixed / single direction → defaults to DESC
+    }
+
+    return { components: comp, order };
+  }
+
   private static _mapGroupsToComponents(
     g: Record<string, string>,
   ): TPSComponents {
     const components: any = {};
-    components.calendar = g.calendar as CalendarCode;
-
-    // Time Mapping
-    if (components.calendar === 'unix' && g.unix) {
-      components.unixSeconds = parseFloat(g.unix.substring(1));
-    } else {
-      if (g.millennium) components.millennium = parseInt(g.millennium, 10);
-      if (g.century) components.century = parseInt(g.century, 10);
-      if (g.year) components.year = parseInt(g.year, 10);
-      if (g.month) components.month = parseInt(g.month, 10);
-      if (g.day) components.day = parseInt(g.day, 10);
-      if (g.hour) components.hour = parseInt(g.hour, 10);
-      if (g.minute) components.minute = parseInt(g.minute, 10);
-      if (g.second) components.second = parseFloat(g.second);
-    }
+    components.calendar = g.calendar as string;
 
     // Signature Mapping
     if (g.signature) {
@@ -647,11 +1042,11 @@ export class TPS {
     // Space Mapping
     if (g.space) {
       // Privacy markers
-      if (g.space === 'unknown' || g.space === '-') {
+      if (g.space === "unknown" || g.space === "-") {
         components.isUnknownLocation = true;
-      } else if (g.space === 'redacted') {
+      } else if (g.space === "redacted") {
         components.isRedactedLocation = true;
-      } else if (g.space === 'hidden' || g.space === '~') {
+      } else if (g.space === "hidden" || g.space === "~") {
         components.isHiddenLocation = true;
       }
       // Geospatial cells
@@ -671,6 +1066,10 @@ export class TPS {
         if (g.room) components.room = g.room;
         if (g.zone) components.zone = g.zone;
       }
+      // Generic pre-@ anchor (adm/node/net/planet/etc)
+      else if (g.generic) {
+        components.spaceAnchor = g.generic;
+      }
       // GPS coordinates
       else {
         if (g.lat) components.latitude = parseFloat(g.lat);
@@ -682,9 +1081,9 @@ export class TPS {
     // Extensions Mapping
     if (g.extensions) {
       const extObj: any = {};
-      const parts = g.extensions.split('.');
+      const parts = g.extensions.split(".");
       parts.forEach((p: string) => {
-        const eqIdx = p.indexOf('=');
+        const eqIdx = p.indexOf("=");
         if (eqIdx > 0) {
           const key = p.substring(0, eqIdx);
           const val = p.substring(eqIdx + 1);
@@ -701,13 +1100,14 @@ export class TPS {
 
     return components as TPSComponents;
   }
-
-  private static pad(n: number): string {
-    const s = n.toString();
-    return s.length < 2 ? '0' + s : s;
-  }
 }
 
+// register built-in drivers and set default
+// (tps and gregorian provide canonical conversions before unix)
+TPS.registerDriver(new TpsDriver());
+TPS.registerDriver(new GregorianDriver());
+TPS.registerDriver(new UnixDriver());
+
 // --- TPS-UID v1 Types ---
 
 /**
@@ -715,7 +1115,7 @@ export class TPS {
  */
 export type TPSUID7RBDecodeResult = {
   /** Version identifier */
-  version: 'tpsuid7rb';
+  version: "tpsuid7rb";
   /** Epoch milliseconds (UTC) */
   epochMs: number;
   /** Whether the TPS payload was compressed */
@@ -756,7 +1156,7 @@ export type TPSUID7RBEncodeOptions = {
  *
  * @example
  * ```ts
- * const tps = 'tps://31.95,35.91@T:greg.m3.c1.y26.M01.d09';
+ * const tps = 'tps://31.95,35.91@T:greg.m3.c1.y26.m01.d09';
  *
  * // Encode to binary
  * const bytes = TPSUID7RB.encodeBinary(tps);
@@ -776,7 +1176,7 @@ export class TPSUID7RB {
   /** Version 1 */
   private static readonly VER = 0x01;
   /** String prefix for base64url encoded form */
-  private static readonly PREFIX = 'tpsuid7rb_';
+  private static readonly PREFIX = "tpsuid7rb_";
   /** Regex for validating base64url encoded form */
   public static readonly REGEX = /^tpsuid7rb_[A-Za-z0-9_-]+$/;
 
@@ -792,15 +1192,18 @@ export class TPSUID7RB {
    * @param opts - Encoding options (compress, epochMs override)
    * @returns Binary TPS-UID as Uint8Array
    */
-  static encodeBinary(tps: string, opts?: TPSUID7RBEncodeOptions): Uint8Array {
-    const compress = opts?.compress ?? false;
-    const epochMs = opts?.epochMs ?? this.epochMsFromTPSString(tps);
+  static encodeBinary(
+    tps: string,
+    opts: TPSUID7RBEncodeOptions = {},
+  ): Uint8Array {
+    const compress = opts.compress ?? false;
+    const epochMs = opts.epochMs ?? this.epochMsFromTPSString(tps);
 
     if (!Number.isInteger(epochMs) || epochMs < 0) {
-      throw new Error('epochMs must be a non-negative integer');
+      throw new Error("epochMs must be a non-negative integer");
     }
     if (epochMs > 0xffffffffffff) {
-      throw new Error('epochMs exceeds 48-bit range');
+      throw new Error("epochMs exceeds 48-bit range");
     }
 
     const flags = compress ? 0x01 : 0x00;
@@ -866,7 +1269,7 @@ export class TPSUID7RB {
   static decodeBinary(bytes: Uint8Array): TPSUID7RBDecodeResult {
     // Header min size: 4+1+1+6+4 + 1 (at least 1 byte varint) = 17
     if (bytes.length < 17) {
-      throw new Error('TPSUID7RB: too short');
+      throw new Error("TPSUID7RB: too short");
     }
 
     // MAGIC
@@ -876,7 +1279,7 @@ export class TPSUID7RB {
       bytes[2] !== 0x55 ||
       bytes[3] !== 0x37
     ) {
-      throw new Error('TPSUID7RB: bad magic');
+      throw new Error("TPSUID7RB: bad magic");
     }
 
     // VERSION
@@ -905,7 +1308,7 @@ export class TPSUID7RB {
     offset += bytesRead;
 
     if (offset + tpsLen > bytes.length) {
-      throw new Error('TPSUID7RB: length overflow');
+      throw new Error("TPSUID7RB: length overflow");
     }
 
     // TPS payload
@@ -913,7 +1316,7 @@ export class TPSUID7RB {
     const tpsUtf8 = compressed ? this.inflateRaw(payload) : payload;
     const tps = new TextDecoder().decode(tpsUtf8);
 
-    return { version: 'tpsuid7rb', epochMs, compressed, nonce, tps };
+    return { version: "tpsuid7rb", epochMs, compressed, nonce, tps };
   }
 
   /**
@@ -925,7 +1328,7 @@ export class TPSUID7RB {
    * @returns Base64url encoded TPS-UID with prefix
    */
   static encodeBinaryB64(tps: string, opts?: TPSUID7RBEncodeOptions): string {
-    const bytes = this.encodeBinary(tps, opts);
+    const bytes = this.encodeBinary(tps, opts ?? {});
     return `${this.PREFIX}${this.base64UrlEncode(bytes)}`;
   }
 
@@ -938,7 +1341,7 @@ export class TPSUID7RB {
   static decodeBinaryB64(id: string): TPSUID7RBDecodeResult {
     const s = id.trim();
     if (!s.startsWith(this.PREFIX)) {
-      throw new Error('TPSUID7RB: missing prefix');
+      throw new Error("TPSUID7RB: missing prefix");
     }
     const b64 = s.slice(this.PREFIX.length);
     const bytes = this.base64UrlDecode(b64);
@@ -967,9 +1370,23 @@ export class TPSUID7RB {
     longitude?: number;
     altitude?: number;
     compress?: boolean;
+    order?: TimeOrder;
   }): string {
     const now = new Date();
-    const tps = this.generateTPSString(now, opts);
+    const time = TPS.fromDate(now, DefaultCalendars.TPS, {
+      order: opts?.order,
+    });
+    let space = "unknown";
+
+    if (opts?.latitude !== undefined && opts?.longitude !== undefined) {
+      space = `${opts.latitude},${opts.longitude}`;
+      if (opts.altitude !== undefined) {
+        space += `,${opts.altitude}m`;
+      }
+    }
+
+    const tps = `tps://${space}@${time}`;
+
     return this.encodeBinaryB64(tps, {
       compress: opts?.compress,
       epochMs: now.getTime(),
@@ -983,27 +1400,36 @@ export class TPSUID7RB {
   /**
    * Generate a TPS string from a Date and optional location.
    */
+  // NOTE: this helper is primarily used by `generate()`; drivers and
+  // callers should prefer `TPS.fromDate()` when order or calendars matter.
   private static generateTPSString(
     date: Date,
-    opts?: { latitude?: number; longitude?: number; altitude?: number },
+    opts?: {
+      latitude?: number;
+      longitude?: number;
+      altitude?: number;
+      order?: TimeOrder;
+    },
   ): string {
     const fullYear = date.getUTCFullYear();
-    const m = Math.floor(fullYear / 1000) + 1;
-    const c = Math.floor((fullYear % 1000) / 100) + 1;
-    const y = fullYear % 100;
-    const M = date.getUTCMonth() + 1;
-    const d = date.getUTCDate();
-    const h = date.getUTCHours();
-    const n = date.getUTCMinutes();
-    const s = date.getUTCSeconds();
-
-    const pad = (num: number) => num.toString().padStart(2, '0');
-
-    const timePart = `T:greg.m${m}.c${c}.y${y}.M${pad(M)}.d${pad(d)}.h${pad(
-      h,
-    )}.n${pad(n)}.s${pad(s)}`;
-
-    let spacePart = 'unknown';
+    const comp: TPSComponents = {
+      calendar: DefaultCalendars.TPS,
+      millennium: Math.floor(fullYear / 1000) + 1,
+      century: Math.floor((fullYear % 1000) / 100) + 1,
+      year: fullYear % 100,
+      month: date.getUTCMonth() + 1,
+      day: date.getUTCDate(),
+      hour: date.getUTCHours(),
+      minute: date.getUTCMinutes(),
+      second: date.getUTCSeconds(),
+      millisecond: date.getUTCMilliseconds(),
+    };
+    if (opts?.order) comp.order = opts.order;
+
+    // note: this method belongs to TPSUID7RB, but buildTimePart lives on TPS
+    const timePart = TPS.buildTimePart(comp);
+
+    let spacePart = "unknown";
     if (opts?.latitude !== undefined && opts?.longitude !== undefined) {
       spacePart = `${opts.latitude},${opts.longitude}`;
       if (opts.altitude !== undefined) {
@@ -1019,63 +1445,15 @@ export class TPSUID7RB {
    * Supports both URI format (tps://...) and time-only format (T:greg...)
    */
   static epochMsFromTPSString(tps: string): number {
-    let time: string;
-
-    if (tps.includes('@')) {
-      // URI format: tps://...@T:greg...
-      const at = tps.indexOf('@');
-      time = tps.slice(at + 1).trim();
-    } else if (tps.startsWith('T:')) {
-      // Time-only format
-      time = tps;
-    } else {
-      throw new Error('TPS: unrecognized format');
-    }
-
-    if (!time.startsWith('T:greg.')) {
-      throw new Error('TPS: only T:greg.* parsing is supported');
-    }
-
-    // Extract m (millennium), c (century), y (year)
-    const mMatch = time.match(/\.m(-?\d+)/);
-    const cMatch = time.match(/\.c(\d+)/);
-    const yMatch = time.match(/\.y(\d{1,4})/);
-    const MMatch = time.match(/\.M(\d{1,2})/);
-    const dMatch = time.match(/\.d(\d{1,2})/);
-    const hMatch = time.match(/\.h(\d{1,2})/);
-    const nMatch = time.match(/\.n(\d{1,2})/);
-    const sMatch = time.match(/\.s(\d{1,2})/);
-
-    // Calculate full year from millennium, century, year
-    let fullYear: number;
-    if (mMatch && cMatch && yMatch) {
-      const millennium = parseInt(mMatch[1], 10);
-      const century = parseInt(cMatch[1], 10);
-      const year = parseInt(yMatch[1], 10);
-      fullYear = (millennium - 1) * 1000 + (century - 1) * 100 + year;
-    } else if (yMatch) {
-      // Fallback: interpret y as 2-digit year
-      let year = parseInt(yMatch[1], 10);
-      if (year < 100) {
-        year = year <= 69 ? 2000 + year : 1900 + year;
-      }
-      fullYear = year;
-    } else {
-      throw new Error('TPS: missing year component');
-    }
-
-    const month = MMatch ? parseInt(MMatch[1], 10) : 1;
-    const day = dMatch ? parseInt(dMatch[1], 10) : 1;
-    const hour = hMatch ? parseInt(hMatch[1], 10) : 0;
-    const minute = nMatch ? parseInt(nMatch[1], 10) : 0;
-    const second = sMatch ? parseInt(sMatch[1], 10) : 0;
-
-    const epoch = Date.UTC(fullYear, month - 1, day, hour, minute, second);
-    if (!Number.isFinite(epoch)) {
-      throw new Error('TPS: failed to compute epochMs');
-    }
-
-    return epoch;
+    const date = TPS.toDate(tps);
+    if (date) return date.getTime();
+
+    // If parse fails due to unsupported/extended extension payloads,
+    // strip extensions/query/fragment and retry. Epoch only depends on time.
+    const stripped = tps.replace(/;[^?#]*/, "").replace(/[?#].*$/, "");
+    const retryDate = TPS.toDate(stripped);
+    if (!retryDate) throw new Error("TPS: unable to parse date for epoch");
+    return retryDate.getTime();
   }
 
   // ---------------------------
@@ -1108,7 +1486,7 @@ export class TPSUID7RB {
 
     const n = Number(v);
     if (!Number.isSafeInteger(n)) {
-      throw new Error('TPSUID7RB: u48 not safe integer');
+      throw new Error("TPSUID7RB: u48 not safe integer");
     }
     return n;
   }
@@ -1116,7 +1494,7 @@ export class TPSUID7RB {
   /** Encode unsigned integer as LEB128 varint */
   private static uvarintEncode(n: number): Uint8Array {
     if (!Number.isInteger(n) || n < 0) {
-      throw new Error('uvarint must be non-negative int');
+      throw new Error("uvarint must be non-negative int");
     }
     const out: number[] = [];
     let x = n >>> 0;
@@ -1138,12 +1516,12 @@ export class TPSUID7RB {
     let i = 0;
     while (true) {
       if (offset + i >= bytes.length) {
-        throw new Error('uvarint overflow');
+        throw new Error("uvarint overflow");
       }
       const b = bytes[offset + i];
       if (b < 0x80) {
         if (i > 9 || (i === 9 && b > 1)) {
-          throw new Error('uvarint too large');
+          throw new Error("uvarint too large");
         }
         x |= b << s;
         return { value: x >>> 0, bytesRead: i + 1 };
@@ -1152,7 +1530,7 @@ export class TPSUID7RB {
       s += 7;
       i++;
       if (i > 10) {
-        throw new Error('uvarint too long');
+        throw new Error("uvarint too long");
       }
     }
   }
@@ -1164,35 +1542,35 @@ export class TPSUID7RB {
   /** Encode bytes to base64url (no padding) */
   private static base64UrlEncode(bytes: Uint8Array): string {
     // Node.js environment
-    if (typeof Buffer !== 'undefined') {
+    if (typeof Buffer !== "undefined") {
       return Buffer.from(bytes)
-        .toString('base64')
-        .replace(/\+/g, '-')
-        .replace(/\//g, '_')
-        .replace(/=+$/g, '');
+        .toString("base64")
+        .replace(/\+/g, "-")
+        .replace(/\//g, "_")
+        .replace(/=+$/g, "");
     }
     // Browser environment
-    let binary = '';
+    let binary = "";
     for (let i = 0; i < bytes.length; i++) {
       binary += String.fromCharCode(bytes[i]);
     }
     return btoa(binary)
-      .replace(/\+/g, '-')
-      .replace(/\//g, '_')
-      .replace(/=+$/g, '');
+      .replace(/\+/g, "-")
+      .replace(/\//g, "_")
+      .replace(/=+$/g, "");
   }
 
   /** Decode base64url to bytes */
   private static base64UrlDecode(b64url: string): Uint8Array {
     // Add padding
     const padLen = (4 - (b64url.length % 4)) % 4;
-    const b64 = (b64url + '='.repeat(padLen))
-      .replace(/-/g, '+')
-      .replace(/_/g, '/');
+    const b64 = (b64url + "=".repeat(padLen))
+      .replace(/-/g, "+")
+      .replace(/_/g, "/");
 
     // Node.js environment
-    if (typeof Buffer !== 'undefined') {
-      return new Uint8Array(Buffer.from(b64, 'base64'));
+    if (typeof Buffer !== "undefined") {
+      return new Uint8Array(Buffer.from(b64, "base64"));
     }
     // Browser environment
     const binary = atob(b64);
@@ -1210,33 +1588,33 @@ export class TPSUID7RB {
   /** Compress using zlib deflate raw */
   private static deflateRaw(data: Uint8Array): Uint8Array {
     // Node.js environment
-    if (typeof require !== 'undefined') {
+    if (typeof require !== "undefined") {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const zlib = require('zlib');
+        const zlib = require("zlib");
         return new Uint8Array(zlib.deflateRawSync(Buffer.from(data)));
       } catch {
-        throw new Error('TPSUID7RB: compression not available');
+        throw new Error("TPSUID7RB: compression not available");
       }
     }
     // Browser: would need pako or similar library
-    throw new Error('TPSUID7RB: compression not available in browser');
+    throw new Error("TPSUID7RB: compression not available in browser");
   }
 
   /** Decompress using zlib inflate raw */
   private static inflateRaw(data: Uint8Array): Uint8Array {
     // Node.js environment
-    if (typeof require !== 'undefined') {
+    if (typeof require !== "undefined") {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const zlib = require('zlib');
+        const zlib = require("zlib");
         return new Uint8Array(zlib.inflateRawSync(Buffer.from(data)));
       } catch {
-        throw new Error('TPSUID7RB: decompression failed');
+        throw new Error("TPSUID7RB: decompression failed");
       }
     }
     // Browser: would need pako or similar library
-    throw new Error('TPSUID7RB: decompression not available in browser');
+    throw new Error("TPSUID7RB: decompression not available in browser");
   }
 
   // ---------------------------
@@ -1271,7 +1649,7 @@ export class TPSUID7RB {
 
     // Validate epoch
     if (!Number.isInteger(epochMs) || epochMs < 0 || epochMs > 0xffffffffffff) {
-      throw new Error('epochMs must be a valid 48-bit non-negative integer');
+      throw new Error("epochMs must be a valid 48-bit non-negative integer");
     }
 
     // Flags: Bit 0 = compress, Bit 1 = sealed
@@ -1327,7 +1705,7 @@ export class TPSUID7RB {
     sealedBytes: Uint8Array,
     publicKey: string | Buffer | Uint8Array,
   ): TPSUID7RBDecodeResult {
-    if (sealedBytes.length < 18) throw new Error('TPSUID7RB: too short');
+    if (sealedBytes.length < 18) throw new Error("TPSUID7RB: too short");
 
     // Check Magic
     if (
@@ -1336,13 +1714,13 @@ export class TPSUID7RB {
       sealedBytes[2] !== 0x55 ||
       sealedBytes[3] !== 0x37
     ) {
-      throw new Error('TPSUID7RB: bad magic');
+      throw new Error("TPSUID7RB: bad magic");
     }
 
     // Check Flags for Sealed Bit (bit 1)
     const flags = sealedBytes[5];
     if ((flags & 0x02) === 0) {
-      throw new Error('TPSUID7RB: not a sealed UID');
+      throw new Error("TPSUID7RB: not a sealed UID");
     }
 
     // 1. Parse the structure to find where content ends
@@ -1357,7 +1735,7 @@ export class TPSUID7RB {
     const payloadEnd = offset + tpsLen;
 
     if (payloadEnd > sealedBytes.length) {
-      throw new Error('TPSUID7RB: length overflow (truncated)');
+      throw new Error("TPSUID7RB: length overflow (truncated)");
     }
 
     // The Content to verify matches exactly [0 ... payloadEnd]
@@ -1365,7 +1743,7 @@ export class TPSUID7RB {
 
     // After content: SealType (1 byte) + Signature
     if (sealedBytes.length <= payloadEnd + 1) {
-      throw new Error('TPSUID7RB: missing signature data');
+      throw new Error("TPSUID7RB: missing signature data");
     }
 
     const sealType = sealedBytes[payloadEnd];
@@ -1385,7 +1763,7 @@ export class TPSUID7RB {
     // Verify
     const isValid = this.verifyEd25519(content, signature, publicKey);
     if (!isValid) {
-      throw new Error('TPSUID7RB: signature verification failed');
+      throw new Error("TPSUID7RB: signature verification failed");
     }
 
     // Decode (reuse standard logic, but ignoring the extra bytes at end is fine?)
@@ -1403,10 +1781,10 @@ export class TPSUID7RB {
     data: Uint8Array,
     privateKey: string | Buffer | Uint8Array,
   ): Uint8Array {
-    if (typeof require !== 'undefined') {
+    if (typeof require !== "undefined") {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const crypto = require('crypto');
+        const crypto = require("crypto");
         // Node's crypto.sign uses PEM or KeyObject, but for raw Ed25519 keys we might need 'crypto.sign(null, data, key)'
         // or ensure key is properly formatted.
         // For simplicity in Node 20+, crypto.sign(null, data, privateKey) works if key is KeyObject.
@@ -1419,8 +1797,8 @@ export class TPSUID7RB {
           // Let's assume standard Ed25519 standard implementation pattern logic:
           keyObj = crypto.createPrivateKey({
             key: Buffer.from(privateKey),
-            format: 'der', // or 'pem' - strict.
-            type: 'pkcs8',
+            format: "der", // or 'pem' - strict.
+            type: "pkcs8",
           });
           // Actually, simpler: construct key object from raw bytes if possible?
           // Node's crypto is strict. Let's try the simplest:
@@ -1434,11 +1812,11 @@ export class TPSUID7RB {
         // Handling RAW Ed25519 keys in Node requires specific 'crypto.createPrivateKey' with 'raw' format (Node 11.6+).
 
         const key =
-          typeof privateKey === 'string' && !privateKey.includes('PRIVATE KEY')
+          typeof privateKey === "string" && !privateKey.includes("PRIVATE KEY")
             ? crypto.createPrivateKey({
-                key: Buffer.from(privateKey, 'hex'),
-                format: 'pem',
-                type: 'pkcs8',
+                key: Buffer.from(privateKey, "hex"),
+                format: "pem",
+                type: "pkcs8",
               }) // Fallback guess
             : privateKey;
 
@@ -1447,10 +1825,10 @@ export class TPSUID7RB {
         return new Uint8Array(crypto.sign(null, data, key));
       } catch (e) {
         // If standard crypto fails (e.g. key format issue), throw
-        throw new Error('TPSUID7RB: signing failed (check key format)');
+        throw new Error("TPSUID7RB: signing failed (check key format)");
       }
     }
-    throw new Error('TPSUID7RB: signing not available in browser');
+    throw new Error("TPSUID7RB: signing not available in browser");
   }
 
   private static verifyEd25519(
@@ -1458,16 +1836,16 @@ export class TPSUID7RB {
     signature: Uint8Array,
     publicKey: string | Buffer | Uint8Array,
   ): boolean {
-    if (typeof require !== 'undefined') {
+    if (typeof require !== "undefined") {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const crypto = require('crypto');
+        const crypto = require("crypto");
         return crypto.verify(null, data, publicKey, signature);
       } catch {
         return false;
       }
     }
-    throw new Error('TPSUID7RB: verification not available in browser');
+    throw new Error("TPSUID7RB: verification not available in browser");
   }
 
   // ---------------------------
@@ -1477,21 +1855,276 @@ export class TPSUID7RB {
   /** Generate cryptographically secure random bytes */
   private static randomBytes(length: number): Uint8Array {
     // Node.js environment
-    if (typeof require !== 'undefined') {
+    if (typeof require !== "undefined") {
       try {
         // eslint-disable-next-line @typescript-eslint/no-require-imports
-        const crypto = require('crypto');
+        const crypto = require("crypto");
         return new Uint8Array(crypto.randomBytes(length));
       } catch {
         // Fallback to crypto.getRandomValues
       }
     }
     // Browser or fallback
-    if (typeof crypto !== 'undefined' && crypto.getRandomValues) {
+    if (typeof crypto !== "undefined" && crypto.getRandomValues) {
       const bytes = new Uint8Array(length);
       crypto.getRandomValues(bytes);
       return bytes;
     }
-    throw new Error('TPSUID7RB: no crypto available');
+    throw new Error("TPSUID7RB: no crypto available");
+  }
+}
+
+/**
+ * `TpsDate` is a Date-like wrapper with native TPS conversion helpers.
+ *
+ * It mirrors common JavaScript `Date` construction patterns:
+ * - `new TpsDate()`
+ * - `new TpsDate(ms)`
+ * - `new TpsDate(isoString)`
+ * - `new TpsDate(tpsString)`
+ * - `new TpsDate(year, monthIndex, day?, hour?, minute?, second?, ms?)`
+ */
+export class TpsDate {
+  private readonly internal: Date;
+
+  private getTpsComponents(): TPSComponents {
+    const parsed = TPS.parse(this.toTPS(DefaultCalendars.TPS));
+    if (!parsed) {
+      throw new Error("TpsDate: failed to derive TPS components");
+    }
+    return parsed;
+  }
+
+  private getTpsFullYear(): number {
+    const comp = this.getTpsComponents();
+    return (comp.millennium - 1) * 1000 + (comp.century - 1) * 100 + comp.year;
+  }
+
+  constructor();
+  constructor(value: string | number | Date | TpsDate);
+  constructor(
+    year: number,
+    monthIndex: number,
+    day?: number,
+    hours?: number,
+    minutes?: number,
+    seconds?: number,
+    ms?: number,
+  );
+  constructor(
+    ...args:
+      | []
+      | [string | number | Date | TpsDate]
+      | [number, number, number?, number?, number?, number?, number?]
+  ) {
+    if (args.length === 0) {
+      this.internal = new Date();
+      return;
+    }
+
+    if (args.length === 1) {
+      const value = args[0];
+      if (value instanceof TpsDate) {
+        this.internal = new Date(value.getTime());
+        return;
+      }
+      if (value instanceof Date) {
+        this.internal = new Date(value.getTime());
+        return;
+      }
+      if (typeof value === "string" && TpsDate.looksLikeTPS(value)) {
+        const parsed = TPS.toDate(value);
+        if (!parsed) {
+          throw new RangeError(`Invalid TPS date string: ${value}`);
+        }
+        this.internal = parsed;
+        return;
+      }
+
+      this.internal = new Date(value);
+      return;
+    }
+
+    const [year, monthIndex, day, hours, minutes, seconds, ms] = args;
+    this.internal = new Date(
+      year,
+      monthIndex,
+      day ?? 1,
+      hours ?? 0,
+      minutes ?? 0,
+      seconds ?? 0,
+      ms ?? 0,
+    );
+  }
+
+  private static looksLikeTPS(input: string): boolean {
+    const s = input.trim();
+    return s.startsWith("tps://") || s.startsWith("T:") || s.startsWith("t:");
+  }
+
+  static now(): number {
+    return Date.now();
+  }
+
+  static parse(input: string): number {
+    if (this.looksLikeTPS(input)) {
+      const d = TPS.toDate(input);
+      return d ? d.getTime() : Number.NaN;
+    }
+    return Date.parse(input);
+  }
+
+  static UTC(
+    year: number,
+    monthIndex: number,
+    day?: number,
+    hours?: number,
+    minutes?: number,
+    seconds?: number,
+    ms?: number,
+  ): number {
+    return Date.UTC(
+      year,
+      monthIndex,
+      day ?? 1,
+      hours ?? 0,
+      minutes ?? 0,
+      seconds ?? 0,
+      ms ?? 0,
+    );
+  }
+
+  static fromTPS(tps: string): TpsDate {
+    return new TpsDate(tps);
+  }
+
+  toGregorianDate(): Date {
+    return new Date(this.internal.getTime());
+  }
+
+  toDate(): Date {
+    return this.toGregorianDate();
+  }
+
+  toTPS(
+    calendar: string = DefaultCalendars.TPS,
+    opts?: { order?: TimeOrder },
+  ): string {
+    return TPS.fromDate(this.internal, calendar, opts);
+  }
+
+  toTPSURI(
+    calendar: string = DefaultCalendars.TPS,
+    opts?: {
+      order?: TimeOrder;
+      latitude?: number;
+      longitude?: number;
+      altitude?: number;
+      isUnknownLocation?: boolean;
+      isHiddenLocation?: boolean;
+      isRedactedLocation?: boolean;
+    },
+  ): string {
+    const time = this.toTPS(calendar, { order: opts?.order });
+    const comp = TPS.parse(time) as TPSComponents;
+
+    if (opts?.latitude !== undefined && opts?.longitude !== undefined) {
+      comp.latitude = opts.latitude;
+      comp.longitude = opts.longitude;
+      if (opts.altitude !== undefined) comp.altitude = opts.altitude;
+    } else if (opts?.isHiddenLocation) {
+      comp.isHiddenLocation = true;
+    } else if (opts?.isRedactedLocation) {
+      comp.isRedactedLocation = true;
+    } else {
+      comp.isUnknownLocation = true;
+    }
+
+    return TPS.toURI(comp);
+  }
+
+  getTime(): number {
+    return this.internal.getTime();
+  }
+
+  valueOf(): number {
+    return this.internal.valueOf();
+  }
+
+  toString(): string {
+    return this.toTPS(DefaultCalendars.TPS);
+  }
+
+  toISOString(): string {
+    return this.internal.toISOString();
+  }
+
+  toUTCString(): string {
+    return this.internal.toUTCString();
+  }
+
+  toJSON(): string | null {
+    return this.internal.toJSON();
+  }
+
+  getFullYear(): number {
+    return this.getTpsFullYear();
+  }
+
+  getUTCFullYear(): number {
+    return this.getTpsFullYear();
+  }
+
+  getMonth(): number {
+    return this.getTpsComponents().month - 1;
+  }
+
+  getUTCMonth(): number {
+    return this.getTpsComponents().month - 1;
+  }
+
+  getDate(): number {
+    return this.getTpsComponents().day;
+  }
+
+  getUTCDate(): number {
+    return this.getTpsComponents().day;
+  }
+
+  getHours(): number {
+    return this.getTpsComponents().hour;
+  }
+
+  getUTCHours(): number {
+    return this.getTpsComponents().hour;
+  }
+
+  getMinutes(): number {
+    return this.getTpsComponents().minute;
+  }
+
+  getUTCMinutes(): number {
+    return this.getTpsComponents().minute;
+  }
+
+  getSeconds(): number {
+    return this.getTpsComponents().second;
+  }
+
+  getUTCSeconds(): number {
+    return this.getTpsComponents().second;
+  }
+
+  getMilliseconds(): number {
+    return this.getTpsComponents().millisecond;
+  }
+
+  getUTCMilliseconds(): number {
+    return this.getTpsComponents().millisecond;
+  }
+
+  [Symbol.toPrimitive](hint: string): string | number {
+    if (hint === "number") return this.valueOf();
+    return this.toString();
   }
 }