@nextera.one/tps-standard 0.4.2

package/README.md

@@ -0,0 +1,309 @@
+# TPS — Temporal Positioning Standard
+
+> **A universal coordinate system for Space, Time, and Context.**
+
+TPS defines a deterministic way to represent **when** something happened, **where** it happened, and **under which calendar**, using a single, machine-readable identifier.
+
+## 📦 Installation
+
+```bash
+npm install tps-standard
+```
+
+## 🚀 Quick Start
+
+### Basic Example
+
+```ts
+import { TPS } from 'tps-standard';
+
+// Create a TPS time string from current date
+const nowTime = TPS.fromDate(new Date(), 'greg');
+console.log(nowTime);
+// Output: "T:greg.m3.c1.y26.M01.d07.h13.n20.s45"
+
+// Parse a full TPS URI with location and extensions
+const uri = 'tps://31.95,35.91,800@T:greg.m3.c1.y26.M01.d07.h13.n20;f4;r7';
+const parsed = TPS.parse(uri);
+console.log(parsed);
+// { latitude: 31.95, longitude: 35.91, altitude: 800, calendar: 'greg', year: 26, ... }
+
+// Convert back to URI
+const components = {
+  calendar: 'greg',
+  year: 26,
+  month: 1,
+  day: 7,
+  latitude: 31.95,
+  longitude: 35.91
+};
+const uriString = TPS.toURI(components);
+console.log(uriString);
+// Output: "tps://31.95,35.91@T:greg.y26.M01.d07"
+```
+
+## 📖 Core Concepts
+
+### Time Hierarchy
+
+TPS represents time as a coordinate using this hierarchy:
+
+```
+T:greg.m3.c1.y26.M01.d07.h13.n20.s45
+```
+
+| Component | Meaning |
+|-----------|---------|
+| `greg` | Calendar code (gregorian) |
+| `m3` | Millennium 3 (2000-2999) |
+| `c1` | Century 1 (2000-2099) |
+| `y26` | Year 26 (2026) |
+| `M01` | Month 01 (January) |
+| `d07` | Day 07 |
+| `h13` | Hour 13 (1:00 PM) |
+| `n20` | Minute 20 |
+| `s45` | Second 45 |
+
+Partial coordinates represent **time volumes** (entire year, century, etc.).
+
+### TPS URI Format
+
+**Canonical form:**
+```
+tps://[SPACE]@[TIME][;EXTENSIONS]
+```
+
+#### Components
+
+| Component | Description |
+|-----------|-------------|
+| `SPACE` | `lat,lon[,alt]m` (WGS84) or `unknown`/`hidden`/`redacted` |
+| `TIME` | TPS Time format (`T:calendar.hierarchy`) |
+| `EXTENSIONS` | Optional context (key-value pairs separated by dots) |
+
+#### Location Privacy
+
+- **Coordinates:** `31.95,35.91,800m` (latitude, longitude, altitude in meters)
+- **Unknown:** `unknown` (technical failure, no GPS)
+- **Hidden:** `hidden` (user masked their location)
+- **Redacted:** `redacted` (censored for legal/security)
+
+### Supported Calendars
+
+- `greg` — Gregorian calendar (default)
+- `unix` — Unix epoch seconds
+- `hij` — Hijri (Islamic) — *requires driver*
+- `jul` — Julian — *requires driver*
+- `holo` — Holocene — *requires driver*
+
+## 🔌 Plugin Architecture
+
+TPS supports custom calendar drivers for non-Gregorian systems.
+
+### CalendarDriver Interface
+
+```ts
+export interface CalendarDriver {
+  readonly code: CalendarCode;
+  fromGregorian(date: Date): Partial<TPSComponents>;
+  toGregorian(components: Partial<TPSComponents>): Date;
+  fromDate(date: Date): string;
+}
+```
+
+### Register a Custom Driver
+
+```ts
+import { TPS, CalendarDriver, TPSComponents } from 'tps-standard';
+
+class HijriDriver implements CalendarDriver {
+  readonly code = 'hij';
+
+  fromGregorian(date: Date): Partial<TPSComponents> {
+    // Convert Gregorian date to Hijri components
+    // ... conversion logic ...
+    return { year: 1445, month: 7, day: 15 };
+  }
+
+  toGregorian(components: Partial<TPSComponents>): Date {
+    // Convert Hijri components to Gregorian Date
+    // ... conversion logic ...
+    return new Date();
+  }
+
+  fromDate(date: Date): string {
+    const comp = this.fromGregorian(date);
+    return `T:hij.y${comp.year}.M${comp.month}.d${comp.day}`;
+  }
+}
+
+// Register the driver
+TPS.registerDriver(new HijriDriver());
+
+// Now use it
+const hijriTime = TPS.fromDate(new Date(), 'hij');
+console.log(hijriTime);
+```
+
+## 📚 API Reference
+
+### `TPS.validate(input: string): boolean`
+
+Validates whether a string is properly formatted TPS.
+
+```ts
+TPS.validate('tps://31.95,35.91@T:greg.m3.c1.y26'); // true
+TPS.validate('invalid'); // false
+```
+
+### `TPS.parse(input: string): TPSComponents | null`
+
+Parses a TPS string into components. Returns `null` if invalid.
+
+```ts
+const parsed = TPS.parse('tps://31.95,35.91,800@T:greg.m3.c1.y26.M01.d07.h13.n20;f4;r7');
+// {
+//   latitude: 31.95,
+//   longitude: 35.91,
+//   altitude: 800,
+//   calendar: 'greg',
+//   millennium: 3,
+//   century: 1,
+//   year: 26,
+//   month: 1,
+//   day: 7,
+//   hour: 13,
+//   minute: 20,
+//   extensions: { f: "4", r: "7" }
+// }
+```
+
+### `TPS.toURI(components: TPSComponents): string`
+
+Converts a components object into a canonical TPS URI string.
+
+```ts
+const components = {
+  calendar: 'greg',
+  year: 26,
+  month: 1,
+  day: 7,
+  latitude: 31.95,
+  longitude: 35.91,
+  altitude: 800,
+  extensions: { f: "4", r: "7" }
+};
+const uri = TPS.toURI(components);
+// "tps://31.95,35.91,800m@T:greg.y26.M01.d07;f4.r7"
+```
+
+### `TPS.fromDate(date: Date, calendar: CalendarCode): string`
+
+Generates a TPS time string from a JavaScript Date. Supports registered drivers.
+
+```ts
+const timeString = TPS.fromDate(new Date(), 'greg');
+// "T:greg.m3.c1.y26.M01.d07.h13.n20.s45"
+
+const unixTime = TPS.fromDate(new Date(), 'unix');
+// "T:unix.s1704729645.123"
+```
+
+### `TPS.toDate(tpsString: string): Date | null`
+
+Converts a TPS string back to a JavaScript Date object.
+
+```ts
+const date = TPS.toDate('T:greg.m3.c1.y26.M01.d07.h13.n20.s45');
+console.log(date); // Date object for 2026-01-07 13:20:45 UTC
+```
+
+### `TPS.to(targetCalendar: CalendarCode, tpsString: string): string | null`
+
+Converts a TPS string from one calendar to another using registered drivers.
+
+```ts
+const gregTime = 'T:greg.m3.c1.y26.M01.d07';
+const hijriTime = TPS.to('hij', gregTime);
+// Requires registered Hijri driver
+```
+
+### `TPS.registerDriver(driver: CalendarDriver): void`
+
+Registers a custom calendar driver plugin.
+
+```ts
+const hijriDriver = new HijriDriver();
+TPS.registerDriver(hijriDriver);
+```
+
+### `TPS.getDriver(code: CalendarCode): CalendarDriver | undefined`
+
+Retrieves a registered calendar driver.
+
+```ts
+const driver = TPS.getDriver('hij');
+if (driver) {
+  const components = driver.fromGregorian(new Date());
+}
+```
+
+## 📋 Types Reference
+
+### `TPSComponents`
+
+```ts
+interface TPSComponents {
+  // Temporal
+  calendar: CalendarCode;
+  millennium?: number;
+  century?: number;
+  year?: number;
+  month?: number;
+  day?: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  unixSeconds?: number;
+
+  // Spatial
+  latitude?: number;
+  longitude?: number;
+  altitude?: number;
+
+  // Location Privacy Flags
+  isUnknownLocation?: boolean;
+  isRedactedLocation?: boolean;
+  isHiddenLocation?: boolean;
+
+  // Context
+  extensions?: Record<string, string>;
+}
+```
+
+### `CalendarCode`
+
+```ts
+type CalendarCode = 'greg' | 'hij' | 'jul' | 'holo' | 'unix';
+```
+
+## 🎯 Use Cases
+
+- **Audit Trails:** Immutable timestamp logs with explicit calendar
+- **Distributed Systems:** Coordinate events across timezones
+- **Security & Forensics:** Evidence timestamps with location binding
+- **AI Agents:** Machine-readable event metadata
+- **Long-term Archives:** Deterministic time encoding for historical records
+
+## 🏗️ Design Principles
+
+- **No Assumptions:** Explicit calendar, timezone, precision
+- **Deterministic Parsing:** Same input always produces same output
+- **Human Auditable:** Readable hierarchical structure
+- **Machine Native:** Easy regex and parsing
+- **Backward Compatible:** Partial coordinates are valid
+- **Privacy First:** Built-in location masking
+
+## 📄 License
+
+MIT © 2026 TPS Standards Working Group

package/dist/index.d.ts

@@ -0,0 +1,106 @@
+/**
+ * TPS: Temporal Positioning System
+ * The Universal Protocol for Space-Time Coordinates.
+ * @packageDocumentation
+ * @version 0.4.2
+ * @license MIT
+ * @copyright 2026 TPS Standards Working Group
+ */
+export type CalendarCode = 'greg' | 'hij' | 'jul' | 'holo' | 'unix';
+export interface TPSComponents {
+    calendar: CalendarCode;
+    millennium?: number;
+    century?: number;
+    year?: number;
+    month?: number;
+    day?: number;
+    hour?: number;
+    minute?: number;
+    second?: number;
+    unixSeconds?: number;
+    latitude?: number;
+    longitude?: number;
+    altitude?: number;
+    /** Technical missing data (e.g. server log without GPS) */
+    isUnknownLocation?: boolean;
+    /** Removed for legal/security reasons (e.g. GDPR) */
+    isRedactedLocation?: boolean;
+    /** Masked by user preference (e.g. "Don't show my location") */
+    isHiddenLocation?: boolean;
+    extensions?: Record<string, string>;
+}
+/**
+ * Interface for Calendar Driver plugins.
+ * Implementations must provide conversion logic to/from Gregorian.
+ */
+export interface CalendarDriver {
+    /** The calendar code this driver handles (e.g., 'hij', 'jul'). */
+    readonly code: CalendarCode;
+    /**
+     * Converts a Gregorian 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>;
+    /**
+     * Converts this calendar's components to a Gregorian Date.
+     * @param components - Partial TPS components (year, month, day, etc.).
+     * @returns A JavaScript Date object.
+     */
+    toGregorian(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.m2.c5.y47...").
+     */
+    fromDate(date: Date): string;
+}
+export declare class TPS {
+    private static readonly drivers;
+    /**
+     * Registers a calendar driver plugin.
+     * @param driver - The driver instance to register.
+     */
+    static registerDriver(driver: CalendarDriver): void;
+    /**
+     * Gets a registered calendar driver.
+     * @param code - The calendar code.
+     * @returns The driver or undefined.
+     */
+    static getDriver(code: CalendarCode): CalendarDriver | undefined;
+    private static readonly REGEX_URI;
+    private static readonly REGEX_TIME;
+    static validate(input: string): boolean;
+    static parse(input: string): TPSComponents | null;
+    /**
+     * SERIALIZER: Converts a components object into a full TPS URI.
+     * @param comp - The TPS components.
+     * @returns Full URI string (e.g. "tps://...").
+     */
+    static toURI(comp: TPSComponents): string;
+    /**
+     * 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...").
+     */
+    static fromDate(date?: Date, calendar?: CalendarCode): string;
+    /**
+     * CONVERTER: Converts a TPS string to a Date in a target calendar format.
+     * Uses plugin drivers for cross-calendar conversion.
+     * @param tpsString - The source TPS string (any calendar).
+     * @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;
+    /**
+     * CONVERTER: Reconstructs a JavaScript Date object from a TPS string.
+     * Supports plugin drivers for non-Gregorian calendars.
+     * @param tpsString - The TPS string.
+     * @returns JS Date object or `null` if invalid.
+     */
+    static toDate(tpsString: string): Date | null;
+    private static _mapGroupsToComponents;
+    private static pad;
+}

package/dist/index.js

@@ -0,0 +1,242 @@
+"use strict";
+/**
+ * TPS: Temporal Positioning System
+ * The Universal Protocol for Space-Time Coordinates.
+ * @packageDocumentation
+ * @version 0.4.2
+ * @license MIT
+ * @copyright 2026 TPS Standards Working Group
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TPS = void 0;
+class TPS {
+    /**
+     * Registers a calendar driver plugin.
+     * @param driver - The driver instance to register.
+     */
+    static registerDriver(driver) {
+        this.drivers.set(driver.code, driver);
+    }
+    /**
+     * Gets a registered calendar driver.
+     * @param code - The calendar code.
+     * @returns The driver or undefined.
+     */
+    static getDriver(code) {
+        return this.drivers.get(code);
+    }
+    // --- CORE METHODS ---
+    static validate(input) {
+        if (input.startsWith('tps://'))
+            return this.REGEX_URI.test(input);
+        return this.REGEX_TIME.test(input);
+    }
+    static parse(input) {
+        if (input.startsWith('tps://')) {
+            const match = this.REGEX_URI.exec(input);
+            if (!match || !match.groups)
+                return null;
+            return this._mapGroupsToComponents(match.groups);
+        }
+        const match = this.REGEX_TIME.exec(input);
+        if (!match || !match.groups)
+            return null;
+        return this._mapGroupsToComponents(match.groups);
+    }
+    /**
+     * SERIALIZER: Converts a components object into a full TPS URI.
+     * @param comp - The TPS components.
+     * @returns Full URI string (e.g. "tps://...").
+     */
+    static toURI(comp) {
+        // 1. Build Space Part
+        let spacePart = 'unknown'; // Default safe fallback
+        if (comp.isHiddenLocation) {
+            spacePart = 'hidden';
+        }
+        else if (comp.isRedactedLocation) {
+            spacePart = 'redacted';
+        }
+        else if (comp.isUnknownLocation) {
+            spacePart = 'unknown';
+        }
+        else if (comp.latitude !== undefined && comp.longitude !== undefined) {
+            spacePart = `${comp.latitude},${comp.longitude}`;
+            if (comp.altitude !== undefined) {
+                spacePart += `,${comp.altitude}m`;
+            }
+        }
+        // 2. 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)}`;
+        }
+        // 3. Build Extensions
+        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('.')}`;
+        }
+        return `tps://${spacePart}@${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...").
+     */
+    static fromDate(date = new Date(), calendar = 'greg') {
+        // Check for registered driver first
+        const driver = this.drivers.get(calendar);
+        if (driver) {
+            return driver.fromDate(date);
+        }
+        // Built-in handlers
+        if (calendar === 'unix') {
+            const s = (date.getTime() / 1000).toFixed(3);
+            return `T:unix.s${s}`;
+        }
+        if (calendar === '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)}`;
+        }
+        throw new Error(`Calendar driver '${calendar}' not implemented. Register a driver.`);
+    }
+    /**
+     * CONVERTER: Converts a TPS string to a Date in a target calendar format.
+     * Uses plugin drivers for cross-calendar conversion.
+     * @param tpsString - The source TPS string (any calendar).
+     * @param targetCalendar - The target calendar code (e.g., 'hij').
+     * @returns A TPS string in the target calendar, or null if invalid.
+     */
+    static to(targetCalendar, tpsString) {
+        // 1. Parse to components and convert to Gregorian Date
+        const gregDate = this.toDate(tpsString);
+        if (!gregDate)
+            return null;
+        // 2. Convert Gregorian to target calendar using driver
+        return this.fromDate(gregDate, targetCalendar);
+    }
+    /**
+     * CONVERTER: Reconstructs a JavaScript Date object from a TPS string.
+     * Supports plugin drivers for non-Gregorian calendars.
+     * @param tpsString - The TPS string.
+     * @returns JS Date object or `null` if invalid.
+     */
+    static toDate(tpsString) {
+        const p = this.parse(tpsString);
+        if (!p)
+            return null;
+        // Check for registered driver first
+        const driver = this.drivers.get(p.calendar);
+        if (driver) {
+            return driver.toGregorian(p);
+        }
+        // Built-in handlers
+        if (p.calendar === 'unix' && p.unixSeconds !== undefined) {
+            return new Date(p.unixSeconds * 1000);
+        }
+        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;
+    }
+    // --- INTERNAL HELPERS ---
+    static _mapGroupsToComponents(g) {
+        const components = {};
+        components.calendar = g.calendar;
+        // 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);
+        }
+        // Space Mapping
+        if (g.space) {
+            if (g.space === 'unknown')
+                components.isUnknownLocation = true;
+            else if (g.space === 'redacted')
+                components.isRedactedLocation = true;
+            else if (g.space === 'hidden')
+                components.isHiddenLocation = true;
+            else {
+                if (g.lat)
+                    components.latitude = parseFloat(g.lat);
+                if (g.lon)
+                    components.longitude = parseFloat(g.lon);
+                if (g.alt)
+                    components.altitude = parseFloat(g.alt);
+            }
+        }
+        // Extensions Mapping
+        if (g.extensions) {
+            const extObj = {};
+            const parts = g.extensions.split('.');
+            parts.forEach((p) => {
+                const key = p.charAt(0);
+                const val = p.substring(1);
+                if (key && val)
+                    extObj[key] = val;
+            });
+            components.extensions = extObj;
+        }
+        return components;
+    }
+    static pad(n) {
+        const s = n.toString();
+        return s.length < 2 ? '0' + s : s;
+    }
+}
+exports.TPS = TPS;
+// --- PLUGIN REGISTRY ---
+TPS.drivers = new Map();
+// --- REGEX ---
+TPS.REGEX_URI = new RegExp('^tps://(?<space>unknown|redacted|hidden|(?<lat>-?\\d+(?:\\.\\d+)?),(?<lon>-?\\d+(?:\\.\\d+)?)(?:,(?<alt>-?\\d+(?:\\.\\d+)?)m?)?)@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+)?))?)?)?)?)?)?)?)?(?:;(?<extensions>[a-z0-9\\.\\-\\_]+))?$');
+TPS.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+)?))?)?)?)?)?)?)?)?$');

package/package.json

@@ -0,0 +1,43 @@
+{
+  "name": "@nextera.one/tps-standard",
+  "version": "0.4.2",
+  "description": "The Universal Protocol for Space-Time Coordinates. A standard URI scheme (tps://) combining WGS84 spatial data with hierarchical, multi-calendar temporal coordinates.",
+  "keywords": [
+    "tps",
+    "time-protocol",
+    "space-time",
+    "reality-address",
+    "stuid",
+    "coordinates",
+    "calendar",
+    "gregorian",
+    "hijri",
+    "unix",
+    "geolocation"
+  ],
+  "homepage": "https://tps-standard.org",
+  "bugs": {
+    "url": "https://github.com/nextera-one/tps/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nextera-one/tps.git"
+  },
+  "license": "MIT",
+  "author": "Mohammed Ayesh",
+  "types": "dist/index.d.ts",
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "test": "node dist/index.js"
+  },
+  "files": [
+    "dist",
+    "src"
+  ],
+  "devDependencies": {
+    "typescript": "^5.3.3",
+    "@types/node": "^20.10.6"
+  }
+}

package/src/index.ts

@@ -0,0 +1,324 @@
+/**
+ * TPS: Temporal Positioning System
+ * The Universal Protocol for Space-Time Coordinates.
+ * @packageDocumentation
+ * @version 0.4.2
+ * @license MIT
+ * @copyright 2026 TPS Standards Working Group
+ */
+
+export type CalendarCode = 'greg' | 'hij' | 'jul' | 'holo' | 'unix';
+
+export interface TPSComponents {
+  // --- TEMPORAL ---
+  calendar: CalendarCode;
+  millennium?: number;
+  century?: number;
+  year?: number;
+  month?: number;
+  day?: number;
+  hour?: number;
+  minute?: number;
+  second?: number;
+  unixSeconds?: number;
+
+  // --- SPATIAL ---
+  latitude?: number;
+  longitude?: number;
+  altitude?: number;
+
+  /** Technical missing data (e.g. server log without GPS) */
+  isUnknownLocation?: boolean;
+  /** Removed for legal/security reasons (e.g. GDPR) */
+  isRedactedLocation?: boolean;
+  /** Masked by user preference (e.g. "Don't show my location") */
+  isHiddenLocation?: boolean;
+
+  // --- CONTEXT ---
+  extensions?: Record<string, string>;
+}
+
+// --- PLUGIN ARCHITECTURE ---
+
+/**
+ * Interface for Calendar Driver plugins.
+ * Implementations must provide conversion logic to/from Gregorian.
+ */
+export interface CalendarDriver {
+  /** The calendar code this driver handles (e.g., 'hij', 'jul'). */
+  readonly code: CalendarCode;
+
+  /**
+   * Converts a Gregorian 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>;
+
+  /**
+   * Converts this calendar's components to a Gregorian Date.
+   * @param components - Partial TPS components (year, month, day, etc.).
+   * @returns A JavaScript Date object.
+   */
+  toGregorian(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.m2.c5.y47...").
+   */
+  fromDate(date: Date): string;
+}
+
+export class TPS {
+  // --- PLUGIN REGISTRY ---
+  private static readonly drivers: Map<CalendarCode, CalendarDriver> =
+    new Map();
+
+  /**
+   * Registers a calendar driver plugin.
+   * @param driver - The driver instance to register.
+   */
+  static registerDriver(driver: CalendarDriver): void {
+    this.drivers.set(driver.code, driver);
+  }
+
+  /**
+   * Gets a registered calendar driver.
+   * @param code - The calendar code.
+   * @returns The driver or undefined.
+   */
+  static getDriver(code: CalendarCode): CalendarDriver | undefined {
+    return this.drivers.get(code);
+  }
+
+  // --- REGEX ---
+  private static readonly REGEX_URI = new RegExp(
+    '^tps://(?<space>unknown|redacted|hidden|(?<lat>-?\\d+(?:\\.\\d+)?),(?<lon>-?\\d+(?:\\.\\d+)?)(?:,(?<alt>-?\\d+(?:\\.\\d+)?)m?)?)@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+)?))?)?)?)?)?)?)?)?(?:;(?<extensions>[a-z0-9\\.\\-\\_]+))?$',
+  );
+
+  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+)?))?)?)?)?)?)?)?)?$',
+  );
+
+  // --- CORE METHODS ---
+
+  static validate(input: string): boolean {
+    if (input.startsWith('tps://')) return this.REGEX_URI.test(input);
+    return this.REGEX_TIME.test(input);
+  }
+
+  static parse(input: string): TPSComponents | null {
+    if (input.startsWith('tps://')) {
+      const match = this.REGEX_URI.exec(input);
+      if (!match || !match.groups) return null;
+      return this._mapGroupsToComponents(match.groups);
+    }
+    const match = this.REGEX_TIME.exec(input);
+    if (!match || !match.groups) return null;
+    return this._mapGroupsToComponents(match.groups);
+  }
+
+  /**
+   * SERIALIZER: Converts a components object into a full TPS URI.
+   * @param comp - The TPS components.
+   * @returns Full URI string (e.g. "tps://...").
+   */
+  static toURI(comp: TPSComponents): string {
+    // 1. Build Space Part
+    let spacePart = 'unknown'; // Default safe fallback
+
+    if (comp.isHiddenLocation) {
+      spacePart = 'hidden';
+    } else if (comp.isRedactedLocation) {
+      spacePart = 'redacted';
+    } else if (comp.isUnknownLocation) {
+      spacePart = 'unknown';
+    } else if (comp.latitude !== undefined && comp.longitude !== undefined) {
+      spacePart = `${comp.latitude},${comp.longitude}`;
+      if (comp.altitude !== undefined) {
+        spacePart += `,${comp.altitude}m`;
+      }
+    }
+
+    // 2. 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)}`;
+    }
+
+    // 3. Build Extensions
+    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('.')}`;
+    }
+
+    return `tps://${spacePart}@${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...").
+   */
+  static fromDate(
+    date: Date = new Date(),
+    calendar: CalendarCode = 'greg',
+  ): string {
+    // Check for registered driver first
+    const driver = this.drivers.get(calendar);
+    if (driver) {
+      return driver.fromDate(date);
+    }
+
+    // Built-in handlers
+    if (calendar === 'unix') {
+      const s = (date.getTime() / 1000).toFixed(3);
+      return `T:unix.s${s}`;
+    }
+
+    if (calendar === '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)}`;
+    }
+
+    throw new Error(
+      `Calendar driver '${calendar}' not implemented. Register a driver.`,
+    );
+  }
+
+  /**
+   * CONVERTER: Converts a TPS string to a Date in a target calendar format.
+   * Uses plugin drivers for cross-calendar conversion.
+   * @param tpsString - The source TPS string (any calendar).
+   * @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 {
+    // 1. Parse to components and convert to Gregorian Date
+    const gregDate = this.toDate(tpsString);
+    if (!gregDate) return null;
+
+    // 2. Convert Gregorian to target calendar using driver
+    return this.fromDate(gregDate, targetCalendar);
+  }
+
+  /**
+   * CONVERTER: Reconstructs a JavaScript Date object from a TPS string.
+   * Supports plugin drivers for non-Gregorian calendars.
+   * @param tpsString - The TPS string.
+   * @returns JS Date object or `null` if invalid.
+   */
+  static toDate(tpsString: string): Date | null {
+    const p = this.parse(tpsString);
+    if (!p) return null;
+
+    // Check for registered driver first
+    const driver = this.drivers.get(p.calendar);
+    if (driver) {
+      return driver.toGregorian(p);
+    }
+
+    // Built-in handlers
+    if (p.calendar === 'unix' && p.unixSeconds !== undefined) {
+      return new Date(p.unixSeconds * 1000);
+    }
+
+    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;
+  }
+
+  // --- INTERNAL HELPERS ---
+
+  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);
+    }
+
+    // Space Mapping
+    if (g.space) {
+      if (g.space === 'unknown') components.isUnknownLocation = true;
+      else if (g.space === 'redacted') components.isRedactedLocation = true;
+      else if (g.space === 'hidden') components.isHiddenLocation = true;
+      else {
+        if (g.lat) components.latitude = parseFloat(g.lat);
+        if (g.lon) components.longitude = parseFloat(g.lon);
+        if (g.alt) components.altitude = parseFloat(g.alt);
+      }
+    }
+
+    // Extensions Mapping
+    if (g.extensions) {
+      const extObj: any = {};
+      const parts = g.extensions.split('.');
+      parts.forEach((p: string) => {
+        const key = p.charAt(0);
+        const val = p.substring(1);
+        if (key && val) extObj[key] = val;
+      });
+      components.extensions = extObj;
+    }
+
+    return components as TPSComponents;
+  }
+
+  private static pad(n: number): string {
+    const s = n.toString();
+    return s.length < 2 ? '0' + s : s;
+  }
+}