# What Is the Three Assets System in OfficeCLI and When to Use It for Media Handling

> Understand OfficeCLI's Three Assets system for reliable 3D model media handling. Learn when to use this mirror-first CDN-fallback infrastructure for PowerPoint HTML previews.

- Repository: [OfficeAI/OfficeCLI](https://github.com/iofficeai/OfficeCLI)
- Tags: deep-dive
- Published: 2026-08-08

---

**The Three Assets system in OfficeCLI is a mirror-first, CDN-fallback infrastructure for reliably loading Three.js and its add-ons when rendering 3-D models in PowerPoint HTML previews.**

This system ensures 3-D media displays correctly across network environments by prioritizing a version-pinned internal mirror, falling back to public CDNs, and ultimately degrading to a static image if all else fails. According to the iOfficeAI/OfficeCLI source code, it is implemented whenever a PowerPoint slide contains GLTF/GLB model references that require Three.js rendering.

## How the Three Assets System Works

The Three Assets system is defined in [`src/officecli/Core/ThreeAssets.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/ThreeAssets.cs) and consumed by the PowerPoint preview handler. It operates through three coordinated mechanisms that together guarantee resilient media loading.

### Single Source of Truth for URLs

The `ThreeAssets` class centralizes all Three.js-related URLs and metadata. As implemented in [`src/officecli/Core/ThreeAssets.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/ThreeAssets.cs), it exposes:

- The **version** of Three.js (e.g., `0.170.0`)
- A **private mirror URL** (`https://d.officecli.ai/assets/three-<version>/…`)
- The **CDN URL** for jsdelivr fallback
- An **import-map JSON** that maps bare specifiers to resolved URLs
- Explicit **CDN-only URLs** for the core module and `GLTFLoader`

This consolidation prevents version drift and ensures all components of the system reference identical assets.

### Mirror-First Loading Strategy

The generated HTML preview uses an import map to redirect bare module specifiers to the internal mirror. In [`src/officecli/Handlers/Pptx/PowerPointHandler.HtmlPreview.Shapes.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.HtmlPreview.Shapes.cs), the import map is injected as follows:

```csharp
sb.AppendLine($"<script type=\"importmap\">{Core.ThreeAssets.ImportMapJson}</script>");

```

The import map resolves `three` and `three/addons/` to the mirror location. This provides a stable, potentially firewall-friendly source that can be hosted behind corporate proxies.

### CDN Fallback Chain

When the mirror is unreachable, runtime code in [`PowerPointHandler.HtmlPreview.Shapes.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.HtmlPreview.Shapes.cs) catches the failure and attempts CDN loading. The fallback uses jsdelivr's `+esm` endpoint, which rewrites internal imports to absolute URLs:

```html
<script type="module">
  let THREE, GLTFLoader;
  try {
    // Mirror-first via importmap
    THREE = await import('three');
    ({ GLTFLoader } = await import('three/addons/loaders/GLTFLoader.js'));
  } catch (_) {
    // CDN fallback (+esm) when mirror is unreachable
    THREE = await import('https://cdn.jsdelivr.net/npm/three@0.170.0/+esm');
    ({ GLTFLoader } = await import('https://cdn.jsdelivr.net/npm/three@0.170.0/examples/jsm/loaders/GLTFLoader.js/+esm'));
  }
  // … render the GLB model …
</script>

```

If both sources fail, the system displays a fallback image extracted from the PowerPoint file, ensuring no empty slide appears.

## When to Use the Three Assets System for Media Handling

Use the Three Assets system in OfficeCLI whenever your workflow involves 3-D content in PowerPoint files.

### 3-D Model Embedding

Any PowerPoint slide containing a `<model3d>` element or direct GLTF/GLB reference requires Three.js rendering. The preview renderer in [`PowerPointHandler.HtmlPreview.Shapes.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/PowerPointHandler.HtmlPreview.Shapes.cs) automatically invokes the Three Assets system for these cases.

### Add-on Module Dependencies

Additional Three.js capabilities—**GLTFLoader**, **OrbitControls**, lighting utilities, or post-processing effects—are resolved through the same `three/addons/` import-map prefix. They inherit the identical mirror-first → CDN fallback behavior without additional configuration.

### Offline-First or Restricted Network Environments

The mirror URL can be deployed within private infrastructure, allowing 3-D previews to function without external internet access. When the mirror is unavailable, the CDN fallback maintains functionality; when both fail, the image fallback preserves user experience.

## Key Implementation Files

| File | Purpose |
|------|---------|
| [`src/officecli/Core/ThreeAssets.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/ThreeAssets.cs) | Defines version, mirror/CDN URLs, and generates import-map JSON |
| [`src/officecli/Handlers/Pptx/PowerPointHandler.HtmlPreview.Shapes.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Handlers/Pptx/PowerPointHandler.HtmlPreview.Shapes.cs) | Injects import map and implements runtime fallback logic |
| [`src/officecli/Core/KatexAssets.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/src/officecli/Core/KatexAssets.cs) | Demonstrates the same pattern for KaTeX assets, confirming architectural consistency |

The [`KatexAssets.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/KatexAssets.cs) parallel confirms this mirror-first/CDN-fallback pattern is the standard asset-loading approach across OfficeCLI's media subsystems.

## Summary

- **Three Assets** centralizes Three.js version management and URL resolution in [`ThreeAssets.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ThreeAssets.cs)
- **Mirror-first loading** prioritizes stable, potentially internal infrastructure over public CDNs
- **Automatic CDN fallback** activates when the mirror fails, using jsdelivr's `+esm` service
- **Image fallback** ensures slides never render empty even when all network sources fail
- **Use it** for any 3-D model preview, add-on dependency, or environment requiring resilient media handling

## Frequently Asked Questions

### What happens if both the mirror and CDN are unavailable?

The PowerPoint preview degrades gracefully to a static image extracted from the original `.pptx` file. This fallback is embedded in the HTML generation logic and requires no user intervention.

### Can I configure a custom mirror URL for the Three Assets system?

The [`ThreeAssets.cs`](https://github.com/iOfficeAI/OfficeCLI/blob/main/ThreeAssets.cs) implementation exposes the mirror URL as a configurable property. Organizations can repoint this to internally-hosted asset servers while maintaining the same fallback chain.

### Does the Three Assets system support other 3-D formats beyond GLB/GLTF?

Currently, the system targets Three.js's native capabilities via `GLTFLoader`. Additional loaders would require extending the import-map configuration and ensuring corresponding files are available on both mirror and CDN sources.

### How does the `+esm` CDN fallback handle Three.js's internal imports?

jsdelivr's `+esm` endpoint rewrites relative and bare-specifier imports within the Three.js bundle to absolute CDN URLs. This produces a self-contained module that loads without additional import-map infrastructure.