Session 231 — Vitto Studio: From Broken Preview to Working Platform Builder

Date: March 17, 2026 Focus: Fix the live preview, improve platform generation quality, design versioning system Platform: Claude Code (claude-opus-4-6) Branch: session-230-231

What This Session Achieved (Plain English)

When we started this session, the Vitto Studio — our platform builder where users design and build their own applications — was fundamentally broken. The Live Preview (the window that shows users what their platform looks like in real-time) showed nothing but a "Ready when you are" message, even when the platform had generated modules. The file explorer showed irrelevant JSON data files instead of actual code. And when users made edits, nothing happened.

By the end of this session:

• The Live Preview compiles and renders the generated platform in real-time
• Users can see and edit the actual application code (Angular components, routes, styles)
• Code edits update the preview within ~500ms (not instant, but fast enough to iterate)
• The platform generation pipeline produces higher-quality code (correct plurals, proper UI components, production patterns)
• We have a complete architectural design for how platform versions, generations, and user edits should work together — validated against how GitHub, Replit, and Lovable handle the same problem

Timeline of Changes

Phase 1: Fixing the Live Preview (S231.1 — S231.2)

Problem: The live preview showed "Ready when you are" forever, even when 5 modules existed.

What we found: A chain of THREE bugs working together to silently prevent compilation:

1. Race condition (S231.1): The system signaled "modules are loaded" the instant it got the list of module names from GitLab — but before any actual file contents were downloaded. The compiler then checked for .routes.ts files, found none (still downloading), and gave up.

2. Type mapping error (S231.2): This was the real killer. GitLab's API returns type: "blob" for files, but our code checked type === "file". Every file in the system was misidentified as a directory. Zero files were ever loaded into the virtual file system. The preview had directories but no code inside them.

3. Stale cache (S231.2): When the user navigated away from Studio and came back, old module slugs were cached, so the system thought everything was "already loaded" and skipped fetching entirely.

Impact: After these fixes, the live preview compiled and rendered the platform for the first time.

Phase 2: Generation Quality (S231.3)

Problem: The generated Angular code had quality issues compared to our reference codebase (gmodules1).

What we found: Four specific gaps in the LLM generation prompt:

1. The prompt contradicted itself about CSS vs SCSS files (said ".css" in one place, showed ".scss" in examples) — the AI generated both, creating duplicate files
2. File path examples had src/lib/ but actual files should be at src/ — confused the AI about directory structure
3. Entity pluralization was wrong ("Childs" instead of "Children") because the pipeline never computed the correct plural form before sending to the AI
4. No HTML template example was provided for the list component — the AI had to guess the shell component's API

What we fixed: Updated the generation prompt with correct instructions, added the pluralize() function call before the AI prompt, and added complete golden examples for list HTML, detail HTML, badge components, button components, checkbox selection, and route data.

Phase 3: File Tree and App Visibility (S231.4 — S231.5)

Problem: Users couldn't see "the app" in the file explorer. They saw raw JSON data files (pages, widgets) that weren't useful for coding. The Angular application entry point (app.component.ts, app.routes.ts, main.ts) was completely missing.

What we found:

• The file tree loaded pages/*.page.json and widgets/*.widget.json — these are database records, not code. They belong in the Data panel, not the code editor.
• The apps/ directory from GitLab was never loaded at all — users had no way to see or edit the Angular app shell.
• The VFS insertion helper hardcoded /modules/ as the base path, so app files ended up in the wrong directory.

What we fixed:

• Removed JSON data blobs from the code editor view
• Added a new backend endpoint and frontend loading for the apps/ directory
• Fixed the VFS path insertion to support any base directory
• The file tree now shows: apps/ (the Angular app), modules/ (generated code), config/, docs/

Phase 4: Live Editing (S231.6 — S231.7)

Problem: When users edited code in the Studio, changes weren't reflected in the preview.

What we found: An Angular reactivity bug — _fileChanges.set() was called inside _state.update() (a signal write inside another signal's write). Angular's reactive system doesn't reliably fire effects from nested signal writes. The preview's recompile trigger never fired.

What we fixed:

• Moved the signal write outside the update callback
• Reduced the debounce from 500ms to 150ms (edits feel more responsive)
• Added incremental compilation: instead of recompiling all 50+ files on every keystroke, the system now diffs the file maps and only sends changed files to the rspack WASM compiler. Subsequent compiles are 2-4x faster.

Phase 5: Preview Route Persistence (S231.8)

Problem: Every time the preview recompiled (after an edit), it reset to the first page. If the user was looking at /family-profiles/list and changed something, the preview jumped back to the default route.

What we fixed: Before each recompile, the system now saves the current route hash from the iframe. After the new app boots (~350ms), it sends a PREVIEW_NAVIGATE message to restore the previous route. The user stays on the same page across edits.

Phase 6: Pipeline Bug Fixes (S231.9)

Problem: Module names with special characters produced broken paths. "Family & Household" became family--household (double dash) which breaks imports and routing.

What we fixed: Added a third regex pass to the slug sanitizer that collapses multiple consecutive dashes. This affects both the execute phase and the template generator.

Also added a GET /module-generation/platform/sessions endpoint so Vitto can find its active generation session ID after a context reset.

Phase 7: Versioning Design (S231.10)

Problem: Each platform generation creates a Git branch, but there's no way for users to see what was generated, switch between versions, or understand which generation is active. Manual code edits go directly to the develop branch, creating conflicts with new generations.

What we designed: A complete versioning system inspired by how GitHub Copilot Agent, Replit, and Lovable handle AI-generated code:

• develop branch is sacred — only activated generations and published user edits live there
• Each generation gets its own branch — immutable snapshot, visible in a new "Generations" panel
• User edits go to draft branches — created automatically on first edit, never touch develop directly
• Activation is explicit — user reviews and clicks "Activate" to make a generation the active platform
• Unlimited draft branches — users can have as many editing sessions as they want

This design is documented in a full spec at docs/superpowers/specs/2026-03-17-generation-versioning-drafts-design.md.

What's Next

Technical Summary (for developers)

Commits in this session

Files changed across session

Backend (APIs):

• backend-api/git-provider/gitlab-provider.service.ts — type mapping fix
• backend-ai-api/module-files/studio-repo.controller.ts — app tree endpoint, type mapping
• backend-vitto-api/module-generation/phases/execute.phase.ts — pluralization, slug fix
• backend-vitto-api/module-generation/generators/template-generator.service.ts — slug fix
• backend-vitto-api/prompts/module-gen/implement.prompt.md — production quality patterns
• backend-vitto-api/module-generation/platform-generation.controller.ts — sessions endpoint
• backend-vitto-api/module-generation/platform-generation.service.ts — getActiveSessions

Frontend (libs):

• vitto-studio/services/vfs-sync.service.ts — forkJoin, apps loading, slug cache clearing
• vitto-studio/services/vfs.service.ts — signal reactivity fix
• vitto-studio/services/preview.service.ts — debounce, asset push on errors
• vitto-studio/services/studio-api.service.ts — app structure endpoint
• vitto-studio/components/studio-dock-shell/ — timer removal, module loading
• vitto-studio/components/file-tree/file-tree-node.component.ts — icons
• platform-preview/services/bundler.service.ts — incremental PATCH compilation
• platform-preview/services/preview-bridge.service.ts — route navigation
• platform-preview/components/preview-frame/preview-frame.component.ts — route persistence
• platform-preview/config/preview-bridge-client.ts — PREVIEW_NAVIGATE handler

Static assets:

• apps/gograb-space/src/rspack-compiler.worker.js — PATCH message support

Documentation:

• docs/superpowers/specs/2026-03-17-generation-versioning-drafts-design.md — versioning spec
• docs/english/sessions/S231/231-progress-report.md — this file