Feature/plans

README.md

@@ -7,6 +7,8 @@ Professional open-source software and architectural consulting for modern web an
 This monorepo contains the following core projects:
 
 - **[Tempo](packages/tempo/README.md)**: A premium, high-performance wrapper around the native JavaScript `Temporal` API.
+- **[Tempo-Fns](packages/functions/README.md)**: A tree-shakeable utility library for standalone functional operations.
+- **[Tempo-Plugins](packages/plugins/)**: An ecosystem of optional plugins that extend the core Tempo engine.
 - **[Library](packages/library/README.md)**: A collection of shared, tree-shakable utilities used across Magma projects.
 
 ## 📚 Resources
@@ -15,10 +17,11 @@ All technical documentation has been moved into the respective package directori
 
 - **Tempo Docs**: [packages/tempo/doc/](./packages/tempo/doc/)
 - **Visual Assets**: [packages/tempo/img/](./packages/tempo/img/)
+- **Project & Architecture Docs**: [doc/](./doc/)
 
 ## 💖 Community & Support
 
-For commercial support, architectural consulting, or custom plugin development, please visit our [Commercial Services](./packages/tempo/doc/commercial.md) guide or contact us at `hello@magmacomputing.com.au`.
+For commercial support, architectural consulting, or custom plugin development, please visit our [Commercial Services](./packages/tempo/doc/8-project-and-support/commercial.md) guide or contact us at `hello@magmacomputing.com.au`.
 
 ---
 

doc/build-pipeline-internals.md

@@ -0,0 +1,29 @@
+# ⚙️ Build Pipeline Internals
+
+The Magma monorepo utilizes a powerful **Dual-Build Pipeline** that perfectly balances strict TypeScript validation with hyper-optimized bundle distribution.
+
+## The Dual-Build Strategy
+
+When you run `npm run build` in the monorepo root (or `npm run build:tempo`), the pipeline executes two distinct phases:
+
+### Phase 1: TypeScript Compilation (`tsc -b`)
+We utilize TypeScript Project References (`tsconfig.json`) to compile the `.ts` files into raw `.js` modules and `.d.ts` declaration files inside the `dist/` folder.
+- **Preserve Module Structure**: We do not bundle during this phase. Every file in `src/` maps 1:1 to a file in `dist/`.
+- **Why?** This ensures that `package.json` sub-path exports (like `@magmacomputing/tempo/parse`) can point directly to individual compiled files, enabling aggressive tree-shaking for modern downstream bundlers.
+
+### Phase 2: Rollup Bundling (`rollup -c`)
+After `tsc` finishes, Rollup sweeps through the `dist/` folder to generate the `tempo.bundle.js` and `tempo.bundle.min.js` files.
+- **Target Audience**: These bundles are specifically for users operating via `<script>` tags on CDNs (e.g., unpkg, jsdelivr) who require the entire engine in a single network request.
+- **Alias Resolution**: Rollup resolves all internal `#library` and `#tempo/std` aliases, stitching them directly into the final IIFE/ESM bundle.
+
+## Managing Circular Dependencies: The "Type Stub" Pattern
+
+One of the most complex architectural challenges in this monorepo is how `tempo` bundles the "Standard Terms" (quarters, seasons) from `.std`.
+
+1. **The Problem**: `.std` imports `TermPlugin` types from `tempo`. If `tempo` directly imports `.std` source code, TypeScript throws a massive circular dependency error at compile-time.
+2. **The Type Stub (`std.d.ts`)**: In `packages/tempo/src/tsconfig.json`, we intentionally alias `#tempo/std` to `packages/tempo/src/plugin/term/std.d.ts`. 
+3. **The Result**: When `tsc` builds the core engine, it hits the `#tempo/std` import, reads the handwritten `.d.ts` stub, and safely resolves the types without tracing back into `.std/src`. 
+4. **The Rollup Override**: Later, when `Rollup` bundles the final JavaScript, it completely ignores `tsconfig.json`. Instead, it uses `package.json`'s export map, which points `#tempo/std` to the *actual* compiled JavaScript living in `.std/dist/index.js`.
+
+> [!CAUTION]
+> If you add a new built-in plugin to `.std`, you **must** update the `std.d.ts` type stub if the type signature changes. Otherwise, TypeScript will blindly trust the stub, leading to runtime failures during Rollup bundling.

doc/contributing-and-testing.md

@@ -0,0 +1,41 @@
+# 🤝 Contributing & Testing
+
+Welcome to the team! This guide covers the essential workflows for developing, testing, and debugging within the Magma monorepo.
+
+## 🛠️ Environment Setup
+
+1. **Node Version**: Ensure you are running Node.js **v20.0.0** or higher.
+2. **Install Dependencies**: Run `npm install` from the monorepo root. We rely on npm workspaces to automatically hoist and link cross-package dependencies.
+3. **Initial Build**: Before running tests or starting the REPL, execute a full build to establish the `dist/` folders:
+   ```bash
+   npm run build:tempo
+   npm run build:plugins
+   ```
+
+## 🧪 Testing Infrastructure (Vitest)
+
+We use [Vitest](https://vitest.dev/) for our unit testing framework. 
+
+### Running Tests
+- To run tests for a specific workspace: `cd packages/plugins/astro && npm test`
+- To run all tests across the monorepo: `npm test` from the root directory.
+
+### The `vitest.shared.ts` Configuration
+Because plugins depend on the core engine (and vice-versa), resolving module aliases during test hydration is critical.
+- **The Setup**: Inside `packages/plugins/vitest.shared.ts`, we explicitly map public API paths (e.g., `@magmacomputing/tempo/parse`) back to their raw TypeScript source files (`../tempo/src/module/module.parse.ts`).
+- **Why?** This ensures that Vitest runs against your live `.ts` source code, rather than forcing you to rebuild the `dist/` folders every time you make a change.
+
+> [!WARNING]
+> If you introduce a new public sub-path export in `packages/tempo/package.json`, you **must** also add a corresponding alias in `packages/plugins/vitest.shared.ts`, or the plugin CI tests will fail with an `ERR_MODULE_NOT_FOUND` error.
+
+## 💻 Interactive Debugging (REPL)
+
+For rapid iteration, we provide a custom, persistent Node.js REPL pre-loaded with the `Tempo` class and the native `Temporal` polyfill.
+
+To launch the interactive environment:
+```bash
+npm run repl
+```
+*(This maps to the `packages/tempo/bin/parse.ts` script via `tsx`).*
+
+This is the fastest way to test parsing behavior, benchmark logic, or validate Master Guard rejection patterns without writing a full test suite.

doc/monorepo-architecture.md

@@ -0,0 +1,40 @@
+# 🏗️ Monorepo Architecture
+
+Welcome to the Magma Computing monorepo! This document provides a high-level overview of how the repository is structured, how the different workspaces interact, and the critical architectural decisions that govern our dependencies.
+
+## Workspace Structure
+
+The project is organized as an `npm` workspace monorepo. It is broken down into several heavily decoupled packages:
+
+### 1. `packages/tempo` (Core Engine)
+This is the primary `@magmacomputing/tempo` package. It contains the core Object-Oriented engine, the Master Guard, and the primary date-time parsing/formatting logic.
+- **Role**: The consumer-facing library.
+- **Dependencies**: Relies entirely on the internal `#library` and plugins.
+
+### 2. `packages/library` (The Magma Utility Stack)
+The `@magmacomputing/library` package is a strictly private, internal utility library.
+- **Role**: Provides standalone, highly optimized utilities (type-checking, serialization, proxy delegation, caching, internationalization) used uniformly across all Magma packages.
+- **Encapsulation**: This package is **never** exposed to the end-user. It is consumed via TypeScript path aliases (`#library/*`) and statically bundled into the final distribution.
+
+### 3. `packages/plugins/*` (The Plugin Ecosystem)
+The `@magmacomputing/tempo-plugin-*` packages are standalone, publishable modules that extend the core Tempo engine (e.g., `astro`, `finance`, `sync`).
+- **Role**: Provide opt-in functionality for users without bloating the core engine bundle.
+- **Dependencies**: They depend on `@magmacomputing/tempo/plugin-api` for strict type-checking and structural validation.
+
+### 4. `packages/plugins/.std` (Standard Built-Ins)
+The `@magmacomputing/tempo-std` workspace is a highly specialized, private workspace containing the "standard" built-in plugins (e.g., quarters, seasons).
+- **The Circular Dependency Problem**: `tempo` needs these standard plugins to bundle them as batteries-included defaults. But these standard plugins need to import `TermPlugin` types from `tempo` to compile.
+- **The Solution**: `.std` is isolated into its own workspace. `tempo` imports it via a type stub (`std.d.ts`) during TypeScript compilation to break the circular dependency, and Rollup directly bundles the compiled output during the distribution phase.
+
+### 5. `packages/functions`
+A standalone workspace providing pure, tree-shakeable functions for specific business logic.
+
+## Aliasing Strategy (The `#` Prefix)
+
+To ensure strict module boundaries and simplify refactoring, we heavily utilize Node's subpath imports feature.
+
+- **`#library/*`**: Resolves to `packages/library/src/*`. Used across all workspaces to fetch common utilities.
+- **`#tempo/*`**: Resolves to specific internal domains within the `tempo` core (e.g., `#tempo/support`, `#tempo/parse`).
+
+> [!IMPORTANT]
+> **Never use relative paths (e.g., `../../../library/src`) to cross workspace boundaries.** Always use the `#` alias. This guarantees that your code will compile identically in both the TypeScript project graph and the Vite/Rollup build pipeline.

package.json

@@ -1,6 +1,6 @@
 {
   "name": "tempo-monorepo",
-  "version": "3.10.0",
+  "version": "3.10.1",
   "private": true,
   "engines": {
     "node": ">=20.0.0"

packages/functions/CHANGELOG.md

@@ -5,6 +5,11 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.1.3] - 2026-07-21
+
+### Fixed
+- **Dependencies**: Moved `@js-temporal/polyfill` from `peerDependencies` to `devDependencies` to prevent automatic forced downloads for end-users relying on native Temporal environment support.
+
 ## [0.1.0] - 2026-07-12
 
 ### Added

packages/functions/README.md

@@ -2,7 +2,7 @@
   <tbody>
     <tr>
       <td width="100" valign="top">
-        <img src="../img/functions-logo.svg" width="90" height="90" alt="@magmacomputing/tempo-fns">
+        <img src="https://raw.githubusercontent.com/magmacomputing/magma/main/packages/functions/img/functions-logo.svg" width="90" height="90" alt="@magmacomputing/tempo-fns">
       </td>
       <td valign="middle">
         <h1 style="border-bottom: none; margin-bottom: 0;"><code>@magmacomputing/tempo-fns</code></h1>

packages/functions/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@magmacomputing/tempo-fns",
-  "version": "0.1.0",
+  "version": "0.1.3",
   "description": "Tree-shakeable functional utilities for the Temporal API",
   "author": "Magma Computing Solutions",
   "license": "MIT",
@@ -13,13 +13,24 @@
     "scheduling",
     "cron"
   ],
+  "publishConfig": {
+    "registry": "https://registry.npmjs.org/",
+    "access": "public"
+  },
   "repository": {
     "type": "git",
     "url": "git+https://github.com/magmacomputing/magma.git",
     "directory": "packages/functions"
   },
   "type": "module",
   "sideEffects": false,
+  "files": [
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE",
+    "dist/",
+    "img/"
+  ],
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "browser": "dist/tempo-fns.global.js",
@@ -46,10 +57,13 @@
     "docs:build": "node ./bin/sync-docs.mjs && vitepress build doc"
   },
   "peerDependencies": {
-    "@magmacomputing/tempo": "^3.7.0",
-    "@js-temporal/polyfill": "^0.5.1"
+    "@js-temporal/polyfill": "^0.5.1",
+    "@magmacomputing/tempo": "^3.7.0"
   },
   "peerDependenciesMeta": {
+    "@js-temporal/polyfill": {
+      "optional": true
+    },
     "@magmacomputing/tempo": {
       "optional": true
     }
@@ -60,4 +74,4 @@
     "vitepress": "^1.6.4",
     "vue": "^3.5.39"
   }
-}
+}

packages/library/README.md

@@ -46,7 +46,7 @@ if (isType(val, 'String', 'Number')) {
 Sort complex collections of objects by multiple fields with ease.
 
 ```typescript
-import { sortKey } from '@magmacomputing/library/common/array';
+import { sortKey } from '@magmacomputing/library/array';
 
 const users = [
   { name: 'Alice', age: 30 },
@@ -62,7 +62,7 @@ const sorted = sortKey(users, 'name', { field: 'age', dir: 'desc' });
 Unlike standard `JSON.stringify`, Magma's serialization handles complex types like `Temporal` and `BigInt` out of the box.
 
 ```typescript
-import { stringify, parse } from '@magmacomputing/library/common/serialize';
+import { stringify, objectify } from '@magmacomputing/library/serialize';
 
 const data = {
   at: Temporal.Now.instant(),
@@ -71,7 +71,7 @@ const data = {
 };
 
 const json = stringify(data);
-const restored = parse(json); // Fully restored types!
+const restored = objectify(json); // Fully restored types!
 ```
 
 ---

packages/library/package.json

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