From 231ccb1aebbb3b3f4b30ee945f5cbd5a44ba8898 Mon Sep 17 00:00:00 2001 From: Michael McRae Date: Thu, 11 Jun 2026 18:11:05 +1000 Subject: [PATCH 1/3] Browser Installation notes --- packages/tempo/README.md | 61 +++++++++++++++++++++++++--- packages/tempo/doc/installation.md | 64 +++++++++++++++++++++++++----- packages/tempo/importmap.json | 4 +- 3 files changed, 113 insertions(+), 16 deletions(-) diff --git a/packages/tempo/README.md b/packages/tempo/README.md index a2b995a6..440ebc71 100644 --- a/packages/tempo/README.md +++ b/packages/tempo/README.md @@ -64,25 +64,74 @@ deno add npm:@magmacomputing/tempo # deno ```
-🌐 Browser & Lite Environments +🌐 Browser & Native Environments + +Tempo provides multiple native browser distribution formats. Here is the quick breakdown of which approach to use: +- **Standard Usage** (No plugins): Use the Global Bundle. +- **Plugins without a bundler**: Use **esm.sh** (Easiest) OR use Granular Import Maps (Hardest, but maximum control). +- **Plugins with a bundler** (Vite/Webpack): Do nothing. Your bundler handles the resolution automatically. + +#### 1. The Global Bundle (Standard Usage) +The easiest way to use Tempo natively in the browser is via the pre-optimized ESM bundle. It includes the entire core engine in a single file, eliminating network waterfall effects. -For modern browsers using **Import Maps**: ```html ``` -For rapid prototyping without a package manager (UMD): +#### 2. Smart CDNs (The "Best-of-Both-Worlds") +If you want to use **external plugins** natively in the browser *without* configuring massive import maps, use an on-the-fly bundling CDN like [esm.sh](https://esm.sh). It reads the package resolution rules and bundles dependencies automatically. You do not need an import map! + ```html - + ``` -For granular "Lite" builds, see the [Full Installation Guide](https://magmacomputing.github.io/magma/doc/installation). +#### 3. Granular ESM (Advanced Plugin Architecture) +If you are strictly using a static CDN (like jsdelivr) and require external plugins, you must use the Granular ESM distribution. The bundled engine drops internal builder-utilities to keep the global scope clean, but plugins require them to resolve their own dependencies. + +To use Premium Plugins via static CDN, you must map the core library, its subpaths, and the internal licensing module directly to their granular equivalents: + +```html + +``` + +*(Note: When resolving version caching issues on jsdelivr, use explicit patch versions like `@3.0.1` instead of `@3`)* + +#### UMD (Rapid Prototyping) +For rapid prototyping without a package manager or module scope: +```html + +```
--- diff --git a/packages/tempo/doc/installation.md b/packages/tempo/doc/installation.md index b0d20e8a..31a023e8 100644 --- a/packages/tempo/doc/installation.md +++ b/packages/tempo/doc/installation.md @@ -93,27 +93,28 @@ const t = new Tempo(); --- -## 🌐 Browser (Modern ESM) +## 🌐 Browser & Native Environments -For browser environments that support **Import Maps**, you can use the granular ESM modules. This is the recommended way to use Tempo in the browser as it allows for better caching and modularity. +Tempo provides multiple native browser distribution formats. Here is the quick breakdown of which approach to use: +- **Standard Usage** (No plugins): Use the Global Bundle. +- **Plugins without a bundler**: Use **esm.sh** (Easiest) OR use Granular Import Maps (Hardest, but maximum control). +- **Plugins with a bundler** (Vite/Webpack): Do nothing. Your bundler handles the resolution automatically. -### 1. Import Map Setup -Add this to your `` to resolve the dependencies: +### 1. The Global Bundle (Standard Usage) -> Note: If you are self-hosting Tempo files, use the shipped `packages/tempo/importmap.json` as-is for your installed version instead of hand-authoring `dist/` paths. +The easiest way to use Tempo natively in the browser is via the pre-optimized ESM bundle. It includes the entire core engine in a single file, eliminating network waterfall effects. ```html ``` -### 2. Implementation ```html ``` +### 2. Smart CDNs (The "Best-of-Both-Worlds") + +If you want to use **external plugins** natively in the browser *without* configuring massive import maps, use an on-the-fly bundling CDN like [esm.sh](https://esm.sh). It reads the package resolution rules and bundles dependencies automatically. You do not need an import map! + +```html + +``` + +### 3. Granular ESM (Advanced Plugin Architecture) + +If you are strictly using a static CDN (like jsdelivr) and require external plugins, you must use the Granular ESM distribution. The bundled engine drops internal builder-utilities to keep the global scope clean, but plugins require them to resolve their own dependencies. + +To use Premium Plugins via static CDN, you must map the core library, its subpaths, and the internal licensing module directly to their granular equivalents: + +```html + +``` + +> [!WARNING] Cache Busting +> The jsdelivr CDN aggressively caches major version tags (like `@3`). When relying on precise granular resolution for plugins, it is highly recommended to use explicit patch versions (like `@3.0.1`) to avoid fetching mismatched or outdated sub-modules. + --- -## 📦 Browser (Legacy / Global Bundle) +## 📦 Browser (UMD / Global Variable) If you aren't using ESM or just want a simple ` + diff --git a/packages/tempo/importmap.json b/packages/tempo/importmap.json index 8bb124a2..12dfb649 100644 --- a/packages/tempo/importmap.json +++ b/packages/tempo/importmap.json @@ -6,6 +6,8 @@ "@magmacomputing/tempo/duration": "./dist/module/module.duration.js", "@magmacomputing/tempo/mutate": "./dist/module/module.mutate.js", "@magmacomputing/tempo/plugin": "./dist/plugin/plugin.index.js", - "@magmacomputing/tempo/library": "./dist/library.index.js" + "@magmacomputing/tempo/library": "./dist/library.index.js", + "@magmacomputing/tempo/enums": "./dist/support/support.enum.js", + "#tempo/license": "./dist/plugin/license/license.validator.js" } } \ No newline at end of file From 7fe9bbba42c3e4a5e296f0c591b440b88948589d Mon Sep 17 00:00:00 2001 From: Michael McRae Date: Fri, 12 Jun 2026 03:31:20 +1000 Subject: [PATCH 2/3] Update packages/tempo/doc/installation.md Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com> --- packages/tempo/doc/installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/tempo/doc/installation.md b/packages/tempo/doc/installation.md index 31a023e8..df131ec4 100644 --- a/packages/tempo/doc/installation.md +++ b/packages/tempo/doc/installation.md @@ -160,7 +160,7 @@ To use Premium Plugins via static CDN, you must map the core library, its subpat "#tempo/license": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo@3.0.1/dist/plugin/license/license.validator.js", - "@magmacomputing/tempo-plugin-astro": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo-plugin-astro@1.0.0/dist/index.js", + "`@magmacomputing/tempo-plugin-astro`": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo-plugin-astro@1.1.6/dist/index.js", "@magmacomputing/tempo-plugin-ticker": "https://cdn.jsdelivr.net/npm/@magmacomputing/tempo-plugin-ticker@1.0.4/dist/index.js" } } From 56e95779ffc5ce0450536475f152f589bdd3eb0d Mon Sep 17 00:00:00 2001 From: Michael McRae Date: Fri, 12 Jun 2026 09:51:13 +1000 Subject: [PATCH 3/3] tidy notes on ESM Bundles --- packages/tempo/README.md | 57 ++++-------------------------- packages/tempo/doc/installation.md | 27 ++++++++++---- packages/tempo/importmap.json | 2 ++ 3 files changed, 30 insertions(+), 56 deletions(-) diff --git a/packages/tempo/README.md b/packages/tempo/README.md index 440ebc71..efcaf6d6 100644 --- a/packages/tempo/README.md +++ b/packages/tempo/README.md @@ -66,13 +66,7 @@ deno add npm:@magmacomputing/tempo # deno
🌐 Browser & Native Environments -Tempo provides multiple native browser distribution formats. Here is the quick breakdown of which approach to use: -- **Standard Usage** (No plugins): Use the Global Bundle. -- **Plugins without a bundler**: Use **esm.sh** (Easiest) OR use Granular Import Maps (Hardest, but maximum control). -- **Plugins with a bundler** (Vite/Webpack): Do nothing. Your bundler handles the resolution automatically. - -#### 1. The Global Bundle (Standard Usage) -The easiest way to use Tempo natively in the browser is via the pre-optimized ESM bundle. It includes the entire core engine in a single file, eliminating network waterfall effects. +For standard usage natively in the browser, use the pre-optimized **Global ESM Bundle**. It includes the entire core engine in a single file: ```html -``` - -#### 2. Smart CDNs (The "Best-of-Both-Worlds") -If you want to use **external plugins** natively in the browser *without* configuring massive import maps, use an on-the-fly bundling CDN like [esm.sh](https://esm.sh). It reads the package resolution rules and bundles dependencies automatically. You do not need an import map! -```html -``` - -#### 3. Granular ESM (Advanced Plugin Architecture) -If you are strictly using a static CDN (like jsdelivr) and require external plugins, you must use the Granular ESM distribution. The bundled engine drops internal builder-utilities to keep the global scope clean, but plugins require them to resolve their own dependencies. - -To use Premium Plugins via static CDN, you must map the core library, its subpaths, and the internal licensing module directly to their granular equivalents: - -```html - ``` -*(Note: When resolving version caching issues on jsdelivr, use explicit patch versions like `@3.0.1` instead of `@3`)* +> **Advanced Usage (Plugins & CDNs)** +> If you need to use **Tempo Premium Plugins** natively in the browser, require granular module resolution, or want to use on-the-fly bundling CDNs (like `esm.sh`), please see our comprehensive [**Browser Installation Guide**](./doc/installation.md) for detailed import map configurations. -#### UMD (Rapid Prototyping) -For rapid prototyping without a package manager or module scope: -```html - -```
--- diff --git a/packages/tempo/doc/installation.md b/packages/tempo/doc/installation.md index df131ec4..f68f88a8 100644 --- a/packages/tempo/doc/installation.md +++ b/packages/tempo/doc/installation.md @@ -127,13 +127,27 @@ The easiest way to use Tempo natively in the browser is via the pre-optimized ES ### 2. Smart CDNs (The "Best-of-Both-Worlds") -If you want to use **external plugins** natively in the browser *without* configuring massive import maps, use an on-the-fly bundling CDN like [esm.sh](https://esm.sh). It reads the package resolution rules and bundles dependencies automatically. You do not need an import map! +If you want to use **Premium Plugins** natively in the browser *without* configuring the massive granular import map required by static CDNs, use an on-the-fly bundling CDN like [esm.sh](https://esm.sh). It reads the package resolution rules and bundles the complex internal dependencies automatically. + +While you *could* import directly from the URL everywhere, the best practice is to use a tiny, simple import map just for your top-level packages. This allows you to keep your actual application code clean and standard: ```html + + + + @@ -141,7 +155,7 @@ If you want to use **external plugins** natively in the browser *without* config ### 3. Granular ESM (Advanced Plugin Architecture) -If you are strictly using a static CDN (like jsdelivr) and require external plugins, you must use the Granular ESM distribution. The bundled engine drops internal builder-utilities to keep the global scope clean, but plugins require them to resolve their own dependencies. +If you are strictly using a static CDN (like jsdelivr) and require Premium Plugins, you must use the Granular ESM distribution. The bundled engine drops internal builder-utilities to keep the global scope clean, but plugins require them to resolve their own dependencies. To use Premium Plugins via static CDN, you must map the core library, its subpaths, and the internal licensing module directly to their granular equivalents: @@ -149,6 +163,7 @@ To use Premium Plugins via static CDN, you must map the core library, its subpat