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

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 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, 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, the import map is injected as follows:

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 catches the failure and attempts CDN loading. The fallback uses jsdelivr's +esm endpoint, which rewrites internal imports to absolute URLs:

<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 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	Defines version, mirror/CDN URLs, and generates import-map JSON
src/officecli/Handlers/Pptx/PowerPointHandler.HtmlPreview.Shapes.cs	Injects import map and implements runtime fallback logic
src/officecli/Core/KatexAssets.cs	Demonstrates the same pattern for KaTeX assets, confirming architectural consistency

The 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
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}