Vitto Studio Live Platform Engine — Implementation Plan

For agentic workers: REQUIRED: Use superpowers:subagent-driven-development (if subagents available) or superpowers:executing-plans to implement this plan. Steps use checkbox (- [ ]) syntax for tracking.

Goal: Make Vitto Studio render AI-generated Angular 20 platforms in-browser via rspack WASM compilation with pre-built ESM SDK libraries.

Architecture: Pre-build 39 shared NX libraries to ESM bundles using esbuild, serve locally via dev server proxy. rspack compiles ONLY module code (feature modules), resolving libraries via browser import maps. A synthesized app shell wraps modules for preview.

Tech Stack: esbuild, rspack/browser WASM, Angular 20 JIT, browser import maps, Service Worker asset serving

Spec: docs/superpowers/specs/2026-03-14-vitto-studio-live-platform-engine-design.md

Chunk 1: Platform SDK Build Pipeline

Task 1: Create SDK build script

Files:

• Create: tools/scripts/build-platform-sdk.ts
• Create: tools/scripts/sdk-config.ts (library registry + dependency graph)

Description: A Node.js script that reads the platform-base-template's library source files, compiles each to an ESM bundle using esbuild, and outputs to dist/platform-sdk/. The script topologically sorts libraries by dependency order so that each library's dependencies are built first (though with all inter-library imports marked as externals, build order doesn't strictly matter for esbuild — it matters for validation).

• Step 1: Create tools/scripts/sdk-config.ts with library registry

Maps each @libs-* path alias to its source directory and declares external dependencies.

• Step 2: Create tools/scripts/build-platform-sdk.ts

Uses esbuild to compile each library:

• Input: {sourceRoot}/src/index.ts

• Output: dist/platform-sdk/{lib-name}/index.js

• Format: ESM

• Externals: @angular/*, rxjs, zone.js, all @libs-*, third-party deps

• SWC-compatible decorator handling via esbuild's TypeScript support

• Step 3: Generate dist/platform-sdk/manifest.json and dist/platform-sdk/import-map.json

Manifest lists all built libraries. Import map resolves all package specifiers to local dev server URLs (/sdk/v1/{lib}/index.js).

• Step 4: Add sdk:build script to root package.json

"sdk:build": "npx tsx tools/scripts/build-platform-sdk.ts"

• Step 5: Run yarn sdk:build and verify all 39 libraries compile to ESM

Expected: dist/platform-sdk/ contains 39 directories, each with index.js

• Step 6: Commit

[S224.2] feat: add platform SDK build pipeline for ESM library compilation

Task 2: Serve SDK locally via Angular dev server

Files:

• Modify: apps/gograb-space/project.json — Add assets glob for dist/platform-sdk/
• Alternative: Modify angular.json or proxy config to serve /sdk/ → dist/platform-sdk/

Description: The built SDK files need to be accessible at /sdk/v1/{lib}/index.js from the browser. The simplest approach is to add a proxy rule or asset copy in the Angular dev server config.

• Step 1: Add proxy configuration for /sdk/ → dist/platform-sdk/

• Step 2: Verify a library is loadable: curl http://localhost:6200/sdk/v1/core-models/index.js

• Step 3: Commit

[S224.2] feat: serve platform SDK via dev server proxy

Chunk 2: rspack Integration with SDK

Task 3: Expand ESM CDN map with SDK libraries

Files:

• Modify: libs/libs-structural/platform-preview/src/lib/config/esm-cdn-map.ts

Description: Add all 39 SDK libraries AND third-party dependencies to the CDN map. This tells rspack to treat them as externals (not bundled) and the import map resolves them at runtime.

• Step 1: Add SDK library entries and third-party deps to ESM_CDN_MAP

Each entry maps the package name to a URL:

• SDK libs → /sdk/v1/{lib}/index.js (local dev)

• Third-party → https://esm.sh/{package}@{version}

• Angular sub-paths (animations, cdk) → esm.sh

• Step 2: Verify EXTERNAL_PACKAGES array includes all new entries

• Step 3: Commit

[S224.2] feat: expand ESM CDN map with SDK libraries and third-party deps

Task 4: Enhance BundlerFilesystemService for synthesized app shell

Files:

• Modify: libs/libs-structural/platform-preview/src/lib/services/bundler-filesystem.service.ts
• Modify: libs/libs-structural/platform-preview/src/lib/models/bundler.types.ts

Description: The core of Phase 3. Instead of compiling the generated platform's app files (which have bugs), we synthesize a clean app shell from the module metadata in VFS. The synthesized shell includes main.ts, app.component.ts, app.routes.ts, app.config.ts, and an index.html with the import map.

• Step 1: Add SdkConfig and ModuleMetadata to bundler.types.ts

export interface SdkConfig {
  sdkBaseUrl: string;           // '/sdk/v1' for local dev
  modules: ModuleMetadata[];    // Detected modules from VFS
  spaceId: string;
  universeId: string;
}

export interface ModuleMetadata {
  slug: string;                 // 'match-center'
  routesFile: string;           // 'match-center.routes.ts'
  routesExport: string;         // 'MatchCenterRoutes' or detected export name
}

• Step 2: Add synthesizeAppShell() method to BundlerFilesystemService

This method:

1. Detects modules from VFS paths (/modules/{slug}/src/)
2. Finds each module's routes file (scans for *.routes.ts)
3. Generates main.ts, app.component.ts, app.routes.ts, app.config.ts
4. Generates index.html with full import map
5. Returns enriched file map

• Step 3: Modify enrichFileMap() to call synthesizeAppShell() when SDK config is present

• Step 4: Add generateImportMap() method that builds the <script type="importmap"> block from ESM_CDN_MAP

• Step 5: Commit

[S224.2] feat: synthesize app shell and import maps in BundlerFilesystemService

Task 5: Update rspack config for module compilation

Files:

• Modify: libs/libs-structural/platform-preview/src/lib/config/rspack-angular.config.ts
• Modify: libs/libs-structural/platform-preview/src/lib/models/bundler.types.ts

Description: rspack needs to know where module source files are in memfs and to treat all SDK libraries as externals.

• Step 1: Add moduleAliases to BundlerConfig

• Step 2: Pass aliases to rspack's resolve.alias config

• Step 3: Ensure all entries in EXTERNAL_PACKAGES are configured as module externals

• Step 4: Commit

[S224.2] feat: update rspack config for SDK external resolution

Task 6: Wire up PreviewService for end-to-end preview

Files:

• Modify: libs/libs-structural/vitto-studio/src/lib/services/preview.service.ts
• Modify: libs/libs-structural/vitto-studio/src/lib/services/vfs-sync.service.ts

Description: Connect VFS hydration → rspack compilation so the preview actually works.

• Step 1: Add module detection to VfsSyncService

Add getModuleMetadata(): ModuleMetadata[] method that scans VFS for module directories and detects route files.

• Step 2: Update PreviewService.compileRspack() to pass SdkConfig to bundler

Include module metadata, spaceId, universeId from project context.

• Step 3: Test end-to-end with vitto-uni-test-1 modules

Load the match-center and club-members modules into VFS, trigger rspack compilation, verify preview iframe renders.

• Step 4: Commit

[S224.2] feat: wire up end-to-end platform preview pipeline

Chunk 3: Generation Pipeline Fixes

Task 7: Fix module generation templates

Files:

• Modify: APIs/backend-vitto-api/src/app/module-generation/ (generation prompts/templates)

Description: Fix the template bugs that cause generated code to fail compilation.

• Step 1: Fix route file naming convention

Ensure generated modules export routes as {ModuleName}Routes from {module-slug}.routes.ts

• Step 2: Fix index.ts template

Export from ./ not ./lib/ (there is no lib/ directory)

• Step 3: Fix collection name pluralization

Use correct English plurals: matches (not matchs), coaches (not coachs)

• Step 4: Update generated styles to use CSS (not SCSS)

Change templates to output .css files for component styles. Theme variables available via CSS custom properties.

• Step 5: Commit

[S224.2] fix: correct module generation templates for route imports and exports

Chunk 4: Visual Editing Loop

Task 8: Create VisualEditorService

Files:

• Create: libs/libs-structural/vitto-studio/src/lib/services/visual-editor.service.ts
• Modify: libs/libs-structural/vitto-studio/src/lib/services/studio-interconnection.service.ts

Description: Bridge between click-to-select in preview and Vitto AI editing. When user clicks a component, reads its source from VFS and provides rich context to Vitto.

• Step 1: Create VisualEditorService

Signals:

• selectedComponentSource — full source (TS + HTML + CSS) of selected component
• editingContext — structured context for Vitto prompt

Methods:

• onComponentSelected(info) — reads source files from VFS

• applyModification(changes) — writes changes to VFS

• Step 2: Wire into StudioInterconnectionService

When focusContext changes with source='preview', trigger onComponentSelected.

• Step 3: Commit

[S224.2] feat: add VisualEditorService for click-to-edit bridge

Task 9: Create Vitto visual editing tools

Files:

• Create: APIs/backend-vitto-api/src/app/engine/tools/studio-visual-tools.ts
• Modify: Vitto tool registration

Description: Add tools that Vitto can use to modify component source code.

• Step 1: Create modify_component_template tool

• Step 2: Create modify_component_styles tool

• Step 3: Create modify_component_class tool

• Step 4: Register tools in Vitto Engine tool registry

• Step 5: Commit

[S224.2] feat: add Vitto visual editing tools for studio

Task 10: Wire visual editing end-to-end

Files:

• Modify: libs/libs-structural/vitto-studio/src/lib/services/studio-vitto-bridge.service.ts
• Modify: libs/libs-structural/vitto-studio/src/lib/components/studio-dock-shell/studio-dock-shell.component.ts

Description: Connect VisualEditorService → Vitto prompt context → tool execution → VFS update → recompile.

• Step 1: Pass visual editing context to Vitto via studio-vitto-bridge

• Step 2: Handle tool responses — apply VFS changes from Vitto tools

• Step 3: Verify click → edit → recompile → preview update cycle

• Step 4: Commit

[S224.2] feat: wire visual editing loop end-to-end

Execution Order

Task 1 (SDK build script) → Task 2 (serve locally)
  ↓
Task 3 (CDN map) → Task 4 (bundler fs) → Task 5 (rspack config)
  ↓
Task 6 (wire preview) ← MILESTONE: Preview renders!
  ↓
Task 7 (gen fixes) — can be parallel with above
  ↓
Task 8 (VisualEditorService) → Task 9 (Vitto tools) → Task 10 (wire editing)
  ↓
MILESTONE: Full editing loop works!