S264 Platform Preview Overhaul

Documentation for Sessions

S264: Platform Preview — How We Fixed It and What's Next

Audience: Anyone (non-developer friendly). This explains what changed, why, and what it means for the product.

The Problem (What Was Broken)

When users create platforms in Vitto Studio, they see a Live Preview — a real-time rendering of their generated application. This preview was broken with a red error message:

"Failed to load Angular compiler from CDN. The injectable 'e' needs to be compiled using the JIT compiler, but '@angular/compiler' is not available."

In simple terms: The preview tried to download critical software components from a third-party website (esm.sh), and those downloads either failed or arrived broken. Without these components, the preview couldn't display anything.

What We Did (Timeline)

Step 1: Diagnosed the Root Cause

The third-party CDN (esm.sh) was re-packaging our software components in a way that broke an internal connection between them. Think of it like ordering parts for an engine from two different suppliers — each part works on its own, but they don't fit together because they were manufactured in separate factories.

Technical analogy: Component A needed to register itself with Component B, but each had its own separate copy of Component B. So A registered with its copy, while the app used a different copy — and the registration was never seen.

Step 2: Self-Hosted Angular Runtime (The Fix)

Instead of downloading components from a third-party CDN every time, we now pre-build and host them ourselves. This means:

We created a build script that packages 21 software components (totaling 3.7MB) into a self-contained bundle. This runs automatically when the development server starts.

Step 3: Fixed Animation Conflicts

After the CDN fix, we discovered a hidden bug — the animation system was creating conflicting copies of the rendering engine. This had always been there but was hidden because the CDN failure happened first.

Fix: Removed animation dependencies from the preview (they're cosmetic and not needed for previewing generated platforms). CSS transitions still work normally.

Step 4: Fixed Unknown Component Warnings

Generated platform code uses custom UI components (<ggs-*> elements). The preview didn't recognize all of them, causing red warning messages. We added a blanket rule that tells the preview to accept any custom element — appropriate for a preview context where we can't guarantee every component stub is perfect.

Step 5: Built Future-Proof Architecture (Strategy Pattern)

We created a pluggable system that lets us swap HOW the preview compiles code. Today it uses "JIT" (Just-In-Time compilation — the browser compiles on the fly). In the future, we can switch to "AOT" (Ahead-Of-Time compilation — code is pre-compiled before the browser sees it).

Why this matters: The JIT approach may be deprecated by Angular in future versions. Our architecture is ready to switch without any pipeline changes.

Step 6: Created a Lightweight Template Compiler (Innovation)

We built a custom mini-compiler that can convert Angular templates directly into machine-ready instructions. This is novel — instead of relying on Angular's heavyweight compiler at runtime, our system generates the compiled output directly.

What this enables (future):

Current State

Feature Status Impact
Self-hosted Angular runtime Active CDN error fixed, preview works
Animation conflict fix Active DI errors fixed
Unknown component suppression Active NG0304/NG0303 warnings fixed
Compilation strategy pattern Code ready Not yet wired into pipeline
Lightweight template compiler Code ready Not yet wired into pipeline

What Users See Now

What's Next

  1. Wire the strategy pattern — Connect the pluggable compilation system so we can switch between JIT and AOT
  2. Test the template compiler — Verify it handles all patterns our code generator produces
  3. Switch to AOT — Once verified, eliminate the runtime compiler dependency
  4. Re-add animations — Build animation support that doesn't conflict with the rendering engine
  5. Performance optimization — Measure and improve preview load times

Risk Summary

Risk Likelihood Mitigation
Angular deprecates JIT Medium (2-3 years) AOT strategy + template compiler ready
Self-hosted bundles become stale Low Auto-rebuilt on nx serve, re-run on version upgrade
Template compiler misses patterns Low Safe fallback to JIT if AOT transform fails
CDK component imports fail Low Verified at build time, subpath bundles working

Files Changed (For Developers)

New files (13):

Modified files (5):