@olonjs/cli 3.0.151 → 3.0.152

package/assets/src_tenant_alpha.sh

@@ -1817,9 +1817,9 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
     "@tiptap/extension-link": "^2.11.5",
     "@tiptap/react": "^2.11.5",
     "@tiptap/starter-kit": "^2.11.5",
-    "@olonjs/core": "^1.1.18",
-    "@olonjs/react": "^0.1.1",
-    "@olonjs/studio": "^0.1.1",
+    "@olonjs/core": "^1.1.19",
+    "@olonjs/react": "^0.1.2",
+    "@olonjs/studio": "^0.1.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.474.0",
@@ -2952,7 +2952,7 @@ cat << 'END_OF_FILE_CONTENT' > "src/App.tsx"
  * Bootstrap, persistence, and engine wiring — logic lives in lib/hooks.
  */
 import { useEffect, useMemo } from 'react';
-import { JsonPagesEngine, OlonFormsContext } from '@olonjs/react';
+import { JsonPagesEngine, OlonFormsContext, createHotSaveHandler } from '@olonjs/react';
 import type { JsonPagesConfig, ProjectState } from '@olonjs/core';
 import { withBasePath } from '@olonjs/core';
 import { ComponentRegistry } from '@/lib/ComponentRegistry';
@@ -2985,7 +2985,7 @@ import {
   useInjectedTenantCss,
   useTenantFontsReady,
 } from '@/lib/tenantCss';
-import { APP_BASE_PATH, CLOUD_API_KEY, CLOUD_API_URL, TENANT_ID } from '@/lib/tenantEnv';
+import { APP_BASE_PATH, TENANT_ID, cloudPolicy } from '@/lib/tenantEnv';
 import { useAssetsManifest } from '@/lib/useAssetsManifest';
 import { useCloudSave } from '@/lib/useCloudSave';
 import { useTenantBootstrap } from '@/lib/useTenantBootstrap';
@@ -3010,16 +3010,40 @@ function App() {
     themeConfigSeed,
   });
   useAdminStudioContent({
-    enabled: bootstrap.isHotSaveMode,
+    enabled: bootstrap.bootSource === 'live',
     apiCandidates: bootstrap.cloudApiCandidates,
-    apiKey: CLOUD_API_KEY,
+    apiKey: cloudPolicy.apiKey,
     setPages: bootstrap.setPages,
     setSiteConfig: bootstrap.setSiteConfig,
-    setCollections: bootstrap.setCollections,
+    onSettled: bootstrap.markCloudContentReady,
   });
-  const { assetsManifest, loadAssetsManifest, cloudApiCandidates } = useAssetsManifest(bootstrap.isCloudMode);
+  const { assetsManifest, loadAssetsManifest, cloudApiCandidates } = useAssetsManifest(cloudPolicy.isCloudMode);
   const { cloudSaveUi, runCloudSave, closeCloudDrawer, retryCloudSave } = useCloudSave();
 
+  const hotSave = useMemo(
+    () =>
+      createHotSaveHandler({
+        apiUrl: cloudPolicy.apiUrl,
+        apiKey: cloudPolicy.apiKey,
+        onSuccess: ({ state, slug, apiUrl, apiKey }) => {
+          const keyFingerprint = cloudFingerprintFromUrl(apiUrl, apiKey);
+          const normalizedSlug = normalizeSlugForCache(slug);
+          const existing = readCachedCloudContent(keyFingerprint);
+          writeCachedCloudContent({
+            keyFingerprint,
+            savedAt: Date.now(),
+            siteConfig: state.site ?? null,
+            collections: state.collections,
+            pages: {
+              ...(existing?.pages ?? {}),
+              [normalizedSlug]: state.page,
+            },
+          });
+        },
+      }),
+    [],
+  );
+
   const tenantCssParts = useMemo(() => extractLeadingRemoteCssImports(tenantCss), []);
   const resolvedTenantCss = useMemo(
     () => [buildThemeFontVarsCss(bootstrap.themeConfig), tenantCssParts.rest].filter(Boolean).join('\n'),
@@ -3058,11 +3082,10 @@ function App() {
   }, [canPaintVisitor, bootstrap.enginePages, bootstrap.siteConfig]);
 
   const engineCollections =
-    bootstrap.isHotSaveMode || Object.keys(bootstrap.collections).length > 0
+    bootstrap.bootSource === 'live' || Object.keys(bootstrap.collections).length > 0
       ? bootstrap.collections
       : fileCollections;
 
-      // TOASK: why this if we have a menuConfig Object?
   const engineRefDocuments = useMemo(
     () => ({
       'menu.json': bootstrap.menuConfig,
@@ -3071,7 +3094,6 @@ function App() {
     }),
     [bootstrap.menuConfig],
   );
-  // TOASK END
   const config: JsonPagesConfig = {
     tenantId: TENANT_ID,
     basePath: APP_BASE_PATH,
@@ -3110,48 +3132,13 @@ function App() {
           setCollections: bootstrap.setCollections,
         });
       },
-      async hotSave(state: ProjectState, slug: string): Promise<void> {
-        if (!bootstrap.isCloudMode || !CLOUD_API_URL || !CLOUD_API_KEY) {
-          throw new Error('Cloud mode is not configured for hot save.');
-        }
-        const apiBase = CLOUD_API_URL.replace(/\/$/, '');
-        const res = await fetch(`${apiBase}/hotSave`, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${CLOUD_API_KEY}`,
-          },
-          body: JSON.stringify({
-            slug,
-            page: state.page,
-            siteConfig: state.site,
-            collections: state.collections,
-          }),
-        });
-        const body = (await res.json().catch(() => ({}))) as { error?: string; code?: string };
-        if (!res.ok) {
-          throw new Error(body.error || body.code || `Hot save failed: ${res.status}`);
-        }
-        const keyFingerprint = cloudFingerprintFromUrl(CLOUD_API_URL, CLOUD_API_KEY);
-        const normalizedSlug = normalizeSlugForCache(slug);
-        const existing = readCachedCloudContent(keyFingerprint);
-        writeCachedCloudContent({
-          keyFingerprint,
-          savedAt: Date.now(),
-          siteConfig: state.site ?? null,
-          collections: state.collections,
-          pages: {
-            ...(existing?.pages ?? {}),
-            [normalizedSlug]: state.page,
-          },
-        });
-      },
+      hotSave,
       async coldSave(state: ProjectState, slug: string): Promise<void> {
         await runCloudSave({ state, slug }, true);
       },
-      showLocalSave: !bootstrap.isCloudMode,
-      showHotSave: bootstrap.isHotSaveMode,
-      showColdSave: bootstrap.isSave2RepoMode,
+      showLocalSave: cloudPolicy.showLocalSave,
+      showHotSave: cloudPolicy.showHotSave,
+      showColdSave: cloudPolicy.showColdSave,
     },
     assets: {
       assetsBaseUrl: withBasePath('/assets', APP_BASE_PATH),
@@ -3159,9 +3146,9 @@ function App() {
       onAssetUpload: (file) =>
         uploadTenantAsset(file, {
           basePath: APP_BASE_PATH,
-          isCloudMode: bootstrap.isCloudMode,
-          cloudApiUrl: CLOUD_API_URL,
-          cloudApiKey: CLOUD_API_KEY,
+          isCloudMode: cloudPolicy.isCloudMode,
+          cloudApiUrl: cloudPolicy.apiUrl,
+          cloudApiKey: cloudPolicy.apiKey,
           apiBases: cloudApiCandidates,
           onUploaded: loadAssetsManifest,
         }),
@@ -3172,7 +3159,7 @@ function App() {
     <ThemeProvider>
       <OlonFormsContext.Provider value={formStates}>
         <TenantBootstrapChrome
-          isCloudMode={bootstrap.isCloudMode}
+          isCloudMode={cloudPolicy.isCloudMode}
           showTopProgress={bootstrap.showTopProgress || (bootstrap.shouldRenderEngine && !fontsReady)}
           contentMode={bootstrap.contentMode}
           contentFallback={bootstrap.contentFallback}
@@ -4089,15 +4076,15 @@ echo "Creating src/components/form-demo/View.tsx..."
 cat << 'END_OF_FILE_CONTENT' > "src/components/form-demo/View.tsx"
 import { Icon } from '@/lib/IconResolver';
 import { useFormState } from '@olonjs/react';
+import { cloudPolicy } from '@/lib/tenantEnv';
 import type { FormDemoData } from './types';
 
 type FormDemoViewProps = {
   data: FormDemoData;
 };
 
-const missingEnv =
-  !import.meta.env.VITE_JSONPAGES_CLOUD_URL &&
-  !import.meta.env.VITE_OLONJS_CLOUD_URL;
+const missingCloudUrl = !cloudPolicy.apiUrl;
+const hasCloudKey = Boolean(cloudPolicy.apiKey);
 
 function SetupGuide({ recipientEmail }: { recipientEmail?: string }) {
   const steps = [
@@ -4107,14 +4094,14 @@ function SetupGuide({ recipientEmail }: { recipientEmail?: string }) {
       code: '"recipientEmail": "tu@esempio.it"',
     },
     {
-      done: !missingEnv,
-      label: 'VITE_JSONPAGES_CLOUD_URL nel file .env',
-      code: 'VITE_JSONPAGES_CLOUD_URL=https://cloud.olonjs.io',
+      done: !missingCloudUrl,
+      label: 'VITE_OLONJS_CLOUD_URL (o VITE_JSONPAGES_CLOUD_URL) nel file .env',
+      code: 'VITE_OLONJS_CLOUD_URL=https://cloud.olonjs.io/api/v1',
     },
     {
-      done: !!import.meta.env.VITE_JSONPAGES_API_KEY || !!import.meta.env.VITE_OLONJS_API_KEY,
-      label: 'VITE_JSONPAGES_API_KEY nel file .env',
-      code: 'VITE_JSONPAGES_API_KEY=sk-...',
+      done: hasCloudKey,
+      label: 'VITE_OLONJS_API_KEY (o VITE_JSONPAGES_API_KEY) nel file .env',
+      code: 'VITE_OLONJS_API_KEY=sk-...',
     },
   ];
 
@@ -11610,9 +11597,8 @@ echo "Creating src/lib/cloud/useAdminStudioContent.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/cloud/useAdminStudioContent.ts"
 import { useEffect, useRef } from 'react';
 import type { Dispatch, SetStateAction } from 'react';
-import type { JsonPagesConfig } from '@olonjs/core';
 import { applyLegacyCloudPayload, fetchLegacyCloudContentPayload } from '@/lib/cloud/cloudContentClient';
-import { cloudFingerprint, writeCachedCloudContent } from '@/lib/cloud/cloudCache';
+import { cloudFingerprint, readCachedPages, writeCachedCloudContent } from '@/lib/cloud/cloudCache';
 import { isAdminPath, patchHistoryNavigation } from '@/lib/spp';
 import { APP_BASE_PATH } from '@/lib/tenantEnv';
 import type { PageConfig, SiteConfig } from '@/types';
@@ -11625,7 +11611,8 @@ type UseAdminStudioContentOptions = {
   apiKey: string;
   setPages: Dispatch<SetStateAction<Record<string, PageConfig>>>;
   setSiteConfig: Dispatch<SetStateAction<SiteConfig>>;
-  setCollections: Dispatch<SetStateAction<NonNullable<JsonPagesConfig['collections']>>>;
+  /** Fired when /admin may paint — after cache hit and/or network attempt settles. */
+  onSettled?: () => void;
 };
 
 /** Studio `/admin` sync via legacy `/content` — never mixed into visitor `/render` bootstrap. */
@@ -11635,13 +11622,28 @@ export function useAdminStudioContent({
   apiKey,
   setPages,
   setSiteConfig,
-  setCollections,
+  onSettled,
 }: UseAdminStudioContentOptions) {
   const loadedRef = useRef(false);
   const inFlightRef = useRef<Promise<void> | null>(null);
+  const settledRef = useRef(false);
 
   useEffect(() => {
-    if (!enabled || apiCandidates.length === 0 || !apiKey.trim()) return;
+    settledRef.current = false;
+    loadedRef.current = false;
+
+    if (!enabled) return;
+
+    const settle = () => {
+      if (settledRef.current) return;
+      settledRef.current = true;
+      onSettled?.();
+    };
+
+    if (apiCandidates.length === 0 || !apiKey.trim()) {
+      settle();
+      return;
+    }
 
     const syncIfAdmin = () => {
       if (!isAdminPath(window.location.pathname, APP_BASE_PATH)) return;
@@ -11650,6 +11652,14 @@ export function useAdminStudioContent({
       const controller = new AbortController();
       const fingerprint = cloudFingerprint(apiCandidates[0]!, apiKey);
 
+      // Paint from cache immediately when present — then refresh from network.
+      const { cachedPages, cachedSite } = readCachedPages(fingerprint);
+      if (cachedPages && Object.keys(cachedPages).length > 0) {
+        setPages(cachedPages);
+        if (cachedSite) setSiteConfig(cachedSite);
+        settle();
+      }
+
       inFlightRef.current = fetchLegacyCloudContentPayload(
         apiCandidates,
         apiKey,
@@ -11676,6 +11686,7 @@ export function useAdminStudioContent({
         })
         .finally(() => {
           inFlightRef.current = null;
+          settle();
         });
     };
 
@@ -11685,7 +11696,7 @@ export function useAdminStudioContent({
       unpatch();
       inFlightRef.current = null;
     };
-  }, [enabled, apiCandidates, apiKey, setPages, setSiteConfig, setCollections]);
+  }, [enabled, apiCandidates, apiKey, setPages, setSiteConfig, onSettled]);
 }
 
 END_OF_FILE_CONTENT
@@ -11893,40 +11904,31 @@ END_OF_FILE_CONTENT
 mkdir -p "src/lib/spp"
 echo "Creating src/lib/spp/cloudConfig.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/spp/cloudConfig.ts"
-function normalizeApiBase(raw: string): string {
-  return raw.trim().replace(/\/+$/, '');
-}
+import { buildApiCandidates } from '@olonjs/react';
 
-export function buildApiCandidates(raw: string): string[] {
-  const base = normalizeApiBase(raw);
-  const withApi = /\/api\/v1$/i.test(base) ? base : `${base}/api/v1`;
-  return Array.from(new Set([withApi, base].filter(Boolean)));
-}
+import { cloudPolicy } from '@/lib/tenantEnv';
+
+export { buildApiCandidates };
 
+/**
+ * Browser-runtime SPP cloud slices.
+ * Credentials ⇒ cloud usable. Save2Repo does not mean “cloud off”
+ * (boot may still be static; live slices remain available).
+ * SSG/bake: local JSON only (SPP §3).
+ */
 export function getSppCloudConfig(): {
   enabled: boolean;
   apiBases: string[];
   apiKey: string;
 } {
-  const apiUrl =
-    import.meta.env.VITE_OLONJS_CLOUD_URL?.trim() ||
-    import.meta.env.VITE_JSONPAGES_CLOUD_URL?.trim() ||
-    '';
-  const apiKey =
-    import.meta.env.VITE_OLONJS_API_KEY?.trim() ||
-    import.meta.env.VITE_JSONPAGES_API_KEY?.trim() ||
-    '';
-  const save2Repo = import.meta.env.VITE_SAVE2REPO === 'true';
-
-  // SSG/bake: local resolved JSON only. Cloud slices are browser-runtime (SPP §3).
-  if (import.meta.env.SSR || !apiUrl || !apiKey || save2Repo) {
+  if (import.meta.env.SSR || !cloudPolicy.isCloudMode) {
     return { enabled: false, apiBases: [], apiKey: '' };
   }
 
   return {
     enabled: true,
-    apiBases: buildApiCandidates(apiUrl),
-    apiKey,
+    apiBases: buildApiCandidates(cloudPolicy.apiUrl),
+    apiKey: cloudPolicy.apiKey,
   };
 }
 
@@ -13092,12 +13094,16 @@ END_OF_FILE_CONTENT
 echo "Creating src/lib/tenantEnv.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/tenantEnv.ts"
 import { normalizeBasePath } from '@olonjs/core';
+import { readCloudEnvFromVite, resolveCloudPolicy, type CloudPolicy } from '@olonjs/react';
 
-export const CLOUD_API_URL =
-  import.meta.env.VITE_OLONJS_CLOUD_URL ?? import.meta.env.VITE_JSONPAGES_CLOUD_URL;
-export const CLOUD_API_KEY =
-  import.meta.env.VITE_OLONJS_API_KEY ?? import.meta.env.VITE_JSONPAGES_API_KEY;
-export const SAVE2REPO_ENABLED = import.meta.env.VITE_SAVE2REPO === 'true';
+/** Single Vite → policy path. Prefer `cloudPolicy` over ad-hoc env reads. */
+export const cloudPolicy: CloudPolicy = resolveCloudPolicy(
+  readCloudEnvFromVite(import.meta.env as Record<string, unknown>),
+);
+
+/** Aliases of `cloudPolicy.apiUrl` / `apiKey` for DNA helpers. */
+export const CLOUD_API_URL = cloudPolicy.apiUrl;
+export const CLOUD_API_KEY = cloudPolicy.apiKey;
 export const APP_BASE_PATH = normalizeBasePath(import.meta.env.BASE_URL || '/');
 export const TENANT_ID = 'alpha';
 
@@ -13106,28 +13112,33 @@ echo "Creating src/lib/useAssetsManifest.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/useAssetsManifest.ts"
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import type { LibraryImageEntry } from '@olonjs/core';
-import { buildApiCandidates } from '@/lib/sppCloudConfig';
-import { CLOUD_API_KEY, CLOUD_API_URL } from '@/lib/tenantEnv';
+import { buildApiCandidates } from '@olonjs/react';
+
+import { cloudPolicy } from '@/lib/tenantEnv';
 
 function normalizeApiBase(raw: string): string {
   return raw.trim().replace(/\/+$/, '');
 }
 
-export function useAssetsManifest(isCloudMode: boolean) {
+/** Asset library — cloud list when `cloudPolicy.isCloudMode`, else local `/api/list-assets`. */
+export function useAssetsManifest(isCloudMode: boolean = cloudPolicy.isCloudMode) {
   const [assetsManifest, setAssetsManifest] = useState<LibraryImageEntry[]>([]);
   const cloudApiCandidates = useMemo(
-    () => (isCloudMode && CLOUD_API_URL ? buildApiCandidates(CLOUD_API_URL) : []),
+    () => (isCloudMode && cloudPolicy.apiUrl ? buildApiCandidates(cloudPolicy.apiUrl) : []),
     [isCloudMode],
   );
 
   const loadAssetsManifest = useCallback(async (): Promise<void> => {
-    if (isCloudMode && CLOUD_API_URL && CLOUD_API_KEY) {
-      const apiBases = cloudApiCandidates.length > 0 ? cloudApiCandidates : [normalizeApiBase(CLOUD_API_URL)];
+    if (isCloudMode && cloudPolicy.apiUrl && cloudPolicy.apiKey) {
+      const apiBases =
+        cloudApiCandidates.length > 0
+          ? cloudApiCandidates
+          : [normalizeApiBase(cloudPolicy.apiUrl)];
       for (const apiBase of apiBases) {
         try {
           const res = await fetch(`${apiBase}/assets/list?limit=200`, {
             method: 'GET',
-            headers: { Authorization: `Bearer ${CLOUD_API_KEY}` },
+            headers: { Authorization: `Bearer ${cloudPolicy.apiKey}` },
           });
           const body = (await res.json().catch(() => ({}))) as { items?: LibraryImageEntry[] };
           if (!res.ok) continue;
@@ -13401,6 +13412,8 @@ echo "Creating src/lib/useFormSubmit.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/useFormSubmit.ts"
 import { useState, useCallback } from 'react';
 
+import { cloudPolicy } from '@/lib/tenantEnv';
+
 export type SubmitStatus = 'idle' | 'submitting' | 'success' | 'error';
 
 interface UseFormSubmitOptions {
@@ -13413,22 +13426,20 @@ export function useFormSubmit({ source, tenantId }: UseFormSubmitOptions) {
   const [message, setMessage] = useState<string>('');
 
   const submit = useCallback(async (
-    formData: FormData, 
-    recipientEmail: string, 
-    pageSlug: string, 
+    formData: FormData,
+    recipientEmail: string,
+    pageSlug: string,
     sectionId: string
   ) => {
-    const cloudApiUrl = import.meta.env.VITE_JSONPAGES_CLOUD_URL as string | undefined;
-    const cloudApiKey = import.meta.env.VITE_JSONPAGES_API_KEY as string | undefined;
+    const { apiUrl, apiKey } = cloudPolicy;
 
-    if (!cloudApiUrl || !cloudApiKey) {
+    if (!apiUrl || !apiKey) {
       setStatus('error');
       setMessage('Configurazione API non disponibile. Riprova tra poco.');
       return false;
     }
 
-    // Trasformiamo FormData in un oggetto piatto per il payload JSON
-    const data: Record<string, any> = {};
+    const data: Record<string, string> = {};
     formData.forEach((value, key) => {
       data[key] = String(value).trim();
     });
@@ -13443,18 +13454,17 @@ export function useFormSubmit({ source, tenantId }: UseFormSubmitOptions) {
       submittedAt: new Date().toISOString(),
     };
 
-    // Idempotency Key per evitare doppi invii accidentali
     const idempotencyKey = `form-${sectionId}-${Date.now()}`;
 
     setStatus('submitting');
     setMessage('Invio in corso...');
 
     try {
-      const apiBase = cloudApiUrl.replace(/\/$/, '');
+      const apiBase = apiUrl.replace(/\/$/, '');
       const response = await fetch(`${apiBase}/forms/submit`, {
         method: 'POST',
         headers: {
-          Authorization: `Bearer ${cloudApiKey}`,
+          Authorization: `Bearer ${apiKey}`,
           'Content-Type': 'application/json',
           'Idempotency-Key': idempotencyKey,
         },
@@ -13484,23 +13494,18 @@ export function useFormSubmit({ source, tenantId }: UseFormSubmitOptions) {
   }, []);
 
   return { submit, status, message, reset };
-}
+}
+
 END_OF_FILE_CONTENT
 echo "Creating src/lib/useOlonForms.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/useOlonForms.ts"
 import { useCallback, useEffect, useState } from 'react';
 import type { FormState } from '@olonjs/react';
 
-const API_BASE =
-  (import.meta.env.VITE_OLONJS_CLOUD_URL as string | undefined) ??
-  (import.meta.env.VITE_JSONPAGES_CLOUD_URL as string | undefined);
-
-const API_KEY =
-  (import.meta.env.VITE_OLONJS_API_KEY as string | undefined) ??
-  (import.meta.env.VITE_JSONPAGES_API_KEY as string | undefined);
+import { cloudPolicy } from '@/lib/tenantEnv';
 
 interface UseOlonFormsOptions {
-  /** Override the submit endpoint. Defaults to VITE_OLONJS_CLOUD_URL/forms/submit */
+  /** Override the submit endpoint. Defaults to cloudPolicy.apiUrl/forms/submit */
   endpoint?: string;
 }
 
@@ -13519,13 +13524,16 @@ export function useOlonForms(options?: UseOlonFormsOptions): { states: Record<st
   }, []);
 
   useEffect(() => {
+    const apiUrl = cloudPolicy.apiUrl;
+    const apiKey = cloudPolicy.apiKey;
+
     const resolvedBase = options?.endpoint
       ? options.endpoint.replace(/\/$/, '')
-      : API_BASE
-        ? API_BASE.replace(/\/$/, '')
+      : apiUrl
+        ? apiUrl.replace(/\/$/, '')
         : null;
 
-    if (!resolvedBase || !API_KEY) {
+    if (!resolvedBase || !apiKey) {
       console.warn('[useOlonForms] Missing API endpoint or key — forms will not submit.');
       return;
     }
@@ -13568,7 +13576,7 @@ export function useOlonForms(options?: UseOlonFormsOptions): { states: Record<st
         const response = await fetch(endpoint, {
           method: 'POST',
           headers: {
-            Authorization: `Bearer ${API_KEY}`,
+            Authorization: `Bearer ${apiKey}`,
             'Content-Type': 'application/json',
             'Idempotency-Key': `form-${formId}-${Date.now()}`,
           },
@@ -13619,7 +13627,7 @@ export function useOlonForms(options?: UseOlonFormsOptions): { states: Record<st
 END_OF_FILE_CONTENT
 echo "Creating src/lib/useTenantBootstrap.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/useTenantBootstrap.ts"
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { logBootstrapEvent, toCloudLoadFailure } from '@/lib/cloud/bootstrapTelemetry';
 
@@ -13649,7 +13657,7 @@ import {
 
 import type { JsonPagesConfig } from '@olonjs/core';
 
-import { APP_BASE_PATH, CLOUD_API_KEY, CLOUD_API_URL, SAVE2REPO_ENABLED } from '@/lib/tenantEnv';
+import { APP_BASE_PATH, CLOUD_API_KEY, CLOUD_API_URL, cloudPolicy } from '@/lib/tenantEnv';
 
 import type { MenuConfig, PageConfig, SiteConfig, ThemeConfig } from '@/types';
 
@@ -13731,13 +13739,10 @@ export function useTenantBootstrap({
 
 }: UseTenantBootstrapOptions) {
 
-  const isCloudMode = Boolean(CLOUD_API_URL && CLOUD_API_KEY);
-
-  const isSave2RepoMode = isCloudMode && SAVE2REPO_ENABLED;
+  const { isCloudMode, bootSource } = cloudPolicy;
 
-  const isHotSaveMode = isCloudMode && !isSave2RepoMode;
-
-  const useRenderBootstrap = isHotSaveMode;
+  /** Live SPP render boot — only when bootSource is live (not static Save2Repo). */
+  const useRenderBootstrap = bootSource === 'live';
 
 
 
@@ -13801,7 +13806,11 @@ export function useTenantBootstrap({
 
   const isTenantEmpty = Object.keys(pages).length === 0;
 
-
+  /** Call when live /admin content sync has finished (success, cache, or error). */
+  const markCloudContentReady = useCallback(() => {
+    setShowTopProgress(false);
+    setHasInitialCloudResolved(true);
+  }, []);
 
   const retryBootstrap = () => {
 
@@ -13841,7 +13850,7 @@ export function useTenantBootstrap({
 
 
 
-    if (isSave2RepoMode) {
+    if (bootSource === 'static') {
 
       if (contentLoadInFlight.current) return;
 
@@ -13938,17 +13947,12 @@ export function useTenantBootstrap({
 
 
     if (isAdminPath(window.location.pathname, APP_BASE_PATH)) {
-
+      // Live /admin: content comes from useAdminStudioContent — do not paint empty first.
       setContentMode('cloud');
-
       setContentFallback(null);
-
-      setShowTopProgress(false);
-
-      setHasInitialCloudResolved(true);
-
+      setShowTopProgress(true);
+      setHasInitialCloudResolved(false);
       return;
-
     }
 
 
@@ -14245,7 +14249,7 @@ export function useTenantBootstrap({
 
     isCloudMode,
 
-    isSave2RepoMode,
+    bootSource,
 
     useRenderBootstrap,
 
@@ -14291,9 +14295,7 @@ export function useTenantBootstrap({
 
     isCloudMode,
 
-    isSave2RepoMode,
-
-    isHotSaveMode,
+    bootSource,
 
     contentMode,
 
@@ -14307,6 +14309,8 @@ export function useTenantBootstrap({
 
     isTenantEmpty,
 
+    markCloudContentReady,
+
     retryBootstrap,
 
   };

package/assets/templates/alpha/src_tenant.sh

@@ -1817,9 +1817,9 @@ cat << 'END_OF_FILE_CONTENT' > "package.json"
     "@tiptap/extension-link": "^2.11.5",
     "@tiptap/react": "^2.11.5",
     "@tiptap/starter-kit": "^2.11.5",
-    "@olonjs/core": "^1.1.18",
-    "@olonjs/react": "^0.1.1",
-    "@olonjs/studio": "^0.1.1",
+    "@olonjs/core": "^1.1.19",
+    "@olonjs/react": "^0.1.2",
+    "@olonjs/studio": "^0.1.2",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
     "lucide-react": "^0.474.0",
@@ -2952,7 +2952,7 @@ cat << 'END_OF_FILE_CONTENT' > "src/App.tsx"
  * Bootstrap, persistence, and engine wiring — logic lives in lib/hooks.
  */
 import { useEffect, useMemo } from 'react';
-import { JsonPagesEngine, OlonFormsContext } from '@olonjs/react';
+import { JsonPagesEngine, OlonFormsContext, createHotSaveHandler } from '@olonjs/react';
 import type { JsonPagesConfig, ProjectState } from '@olonjs/core';
 import { withBasePath } from '@olonjs/core';
 import { ComponentRegistry } from '@/lib/ComponentRegistry';
@@ -2985,7 +2985,7 @@ import {
   useInjectedTenantCss,
   useTenantFontsReady,
 } from '@/lib/tenantCss';
-import { APP_BASE_PATH, CLOUD_API_KEY, CLOUD_API_URL, TENANT_ID } from '@/lib/tenantEnv';
+import { APP_BASE_PATH, TENANT_ID, cloudPolicy } from '@/lib/tenantEnv';
 import { useAssetsManifest } from '@/lib/useAssetsManifest';
 import { useCloudSave } from '@/lib/useCloudSave';
 import { useTenantBootstrap } from '@/lib/useTenantBootstrap';
@@ -3010,16 +3010,40 @@ function App() {
     themeConfigSeed,
   });
   useAdminStudioContent({
-    enabled: bootstrap.isHotSaveMode,
+    enabled: bootstrap.bootSource === 'live',
     apiCandidates: bootstrap.cloudApiCandidates,
-    apiKey: CLOUD_API_KEY,
+    apiKey: cloudPolicy.apiKey,
     setPages: bootstrap.setPages,
     setSiteConfig: bootstrap.setSiteConfig,
-    setCollections: bootstrap.setCollections,
+    onSettled: bootstrap.markCloudContentReady,
   });
-  const { assetsManifest, loadAssetsManifest, cloudApiCandidates } = useAssetsManifest(bootstrap.isCloudMode);
+  const { assetsManifest, loadAssetsManifest, cloudApiCandidates } = useAssetsManifest(cloudPolicy.isCloudMode);
   const { cloudSaveUi, runCloudSave, closeCloudDrawer, retryCloudSave } = useCloudSave();
 
+  const hotSave = useMemo(
+    () =>
+      createHotSaveHandler({
+        apiUrl: cloudPolicy.apiUrl,
+        apiKey: cloudPolicy.apiKey,
+        onSuccess: ({ state, slug, apiUrl, apiKey }) => {
+          const keyFingerprint = cloudFingerprintFromUrl(apiUrl, apiKey);
+          const normalizedSlug = normalizeSlugForCache(slug);
+          const existing = readCachedCloudContent(keyFingerprint);
+          writeCachedCloudContent({
+            keyFingerprint,
+            savedAt: Date.now(),
+            siteConfig: state.site ?? null,
+            collections: state.collections,
+            pages: {
+              ...(existing?.pages ?? {}),
+              [normalizedSlug]: state.page,
+            },
+          });
+        },
+      }),
+    [],
+  );
+
   const tenantCssParts = useMemo(() => extractLeadingRemoteCssImports(tenantCss), []);
   const resolvedTenantCss = useMemo(
     () => [buildThemeFontVarsCss(bootstrap.themeConfig), tenantCssParts.rest].filter(Boolean).join('\n'),
@@ -3058,11 +3082,10 @@ function App() {
   }, [canPaintVisitor, bootstrap.enginePages, bootstrap.siteConfig]);
 
   const engineCollections =
-    bootstrap.isHotSaveMode || Object.keys(bootstrap.collections).length > 0
+    bootstrap.bootSource === 'live' || Object.keys(bootstrap.collections).length > 0
       ? bootstrap.collections
       : fileCollections;
 
-      // TOASK: why this if we have a menuConfig Object?
   const engineRefDocuments = useMemo(
     () => ({
       'menu.json': bootstrap.menuConfig,
@@ -3071,7 +3094,6 @@ function App() {
     }),
     [bootstrap.menuConfig],
   );
-  // TOASK END
   const config: JsonPagesConfig = {
     tenantId: TENANT_ID,
     basePath: APP_BASE_PATH,
@@ -3110,48 +3132,13 @@ function App() {
           setCollections: bootstrap.setCollections,
         });
       },
-      async hotSave(state: ProjectState, slug: string): Promise<void> {
-        if (!bootstrap.isCloudMode || !CLOUD_API_URL || !CLOUD_API_KEY) {
-          throw new Error('Cloud mode is not configured for hot save.');
-        }
-        const apiBase = CLOUD_API_URL.replace(/\/$/, '');
-        const res = await fetch(`${apiBase}/hotSave`, {
-          method: 'POST',
-          headers: {
-            'Content-Type': 'application/json',
-            Authorization: `Bearer ${CLOUD_API_KEY}`,
-          },
-          body: JSON.stringify({
-            slug,
-            page: state.page,
-            siteConfig: state.site,
-            collections: state.collections,
-          }),
-        });
-        const body = (await res.json().catch(() => ({}))) as { error?: string; code?: string };
-        if (!res.ok) {
-          throw new Error(body.error || body.code || `Hot save failed: ${res.status}`);
-        }
-        const keyFingerprint = cloudFingerprintFromUrl(CLOUD_API_URL, CLOUD_API_KEY);
-        const normalizedSlug = normalizeSlugForCache(slug);
-        const existing = readCachedCloudContent(keyFingerprint);
-        writeCachedCloudContent({
-          keyFingerprint,
-          savedAt: Date.now(),
-          siteConfig: state.site ?? null,
-          collections: state.collections,
-          pages: {
-            ...(existing?.pages ?? {}),
-            [normalizedSlug]: state.page,
-          },
-        });
-      },
+      hotSave,
       async coldSave(state: ProjectState, slug: string): Promise<void> {
         await runCloudSave({ state, slug }, true);
       },
-      showLocalSave: !bootstrap.isCloudMode,
-      showHotSave: bootstrap.isHotSaveMode,
-      showColdSave: bootstrap.isSave2RepoMode,
+      showLocalSave: cloudPolicy.showLocalSave,
+      showHotSave: cloudPolicy.showHotSave,
+      showColdSave: cloudPolicy.showColdSave,
     },
     assets: {
       assetsBaseUrl: withBasePath('/assets', APP_BASE_PATH),
@@ -3159,9 +3146,9 @@ function App() {
       onAssetUpload: (file) =>
         uploadTenantAsset(file, {
           basePath: APP_BASE_PATH,
-          isCloudMode: bootstrap.isCloudMode,
-          cloudApiUrl: CLOUD_API_URL,
-          cloudApiKey: CLOUD_API_KEY,
+          isCloudMode: cloudPolicy.isCloudMode,
+          cloudApiUrl: cloudPolicy.apiUrl,
+          cloudApiKey: cloudPolicy.apiKey,
           apiBases: cloudApiCandidates,
           onUploaded: loadAssetsManifest,
         }),
@@ -3172,7 +3159,7 @@ function App() {
     <ThemeProvider>
       <OlonFormsContext.Provider value={formStates}>
         <TenantBootstrapChrome
-          isCloudMode={bootstrap.isCloudMode}
+          isCloudMode={cloudPolicy.isCloudMode}
           showTopProgress={bootstrap.showTopProgress || (bootstrap.shouldRenderEngine && !fontsReady)}
           contentMode={bootstrap.contentMode}
           contentFallback={bootstrap.contentFallback}
@@ -4089,15 +4076,15 @@ echo "Creating src/components/form-demo/View.tsx..."
 cat << 'END_OF_FILE_CONTENT' > "src/components/form-demo/View.tsx"
 import { Icon } from '@/lib/IconResolver';
 import { useFormState } from '@olonjs/react';
+import { cloudPolicy } from '@/lib/tenantEnv';
 import type { FormDemoData } from './types';
 
 type FormDemoViewProps = {
   data: FormDemoData;
 };
 
-const missingEnv =
-  !import.meta.env.VITE_JSONPAGES_CLOUD_URL &&
-  !import.meta.env.VITE_OLONJS_CLOUD_URL;
+const missingCloudUrl = !cloudPolicy.apiUrl;
+const hasCloudKey = Boolean(cloudPolicy.apiKey);
 
 function SetupGuide({ recipientEmail }: { recipientEmail?: string }) {
   const steps = [
@@ -4107,14 +4094,14 @@ function SetupGuide({ recipientEmail }: { recipientEmail?: string }) {
       code: '"recipientEmail": "tu@esempio.it"',
     },
     {
-      done: !missingEnv,
-      label: 'VITE_JSONPAGES_CLOUD_URL nel file .env',
-      code: 'VITE_JSONPAGES_CLOUD_URL=https://cloud.olonjs.io',
+      done: !missingCloudUrl,
+      label: 'VITE_OLONJS_CLOUD_URL (o VITE_JSONPAGES_CLOUD_URL) nel file .env',
+      code: 'VITE_OLONJS_CLOUD_URL=https://cloud.olonjs.io/api/v1',
     },
     {
-      done: !!import.meta.env.VITE_JSONPAGES_API_KEY || !!import.meta.env.VITE_OLONJS_API_KEY,
-      label: 'VITE_JSONPAGES_API_KEY nel file .env',
-      code: 'VITE_JSONPAGES_API_KEY=sk-...',
+      done: hasCloudKey,
+      label: 'VITE_OLONJS_API_KEY (o VITE_JSONPAGES_API_KEY) nel file .env',
+      code: 'VITE_OLONJS_API_KEY=sk-...',
     },
   ];
 
@@ -11610,9 +11597,8 @@ echo "Creating src/lib/cloud/useAdminStudioContent.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/cloud/useAdminStudioContent.ts"
 import { useEffect, useRef } from 'react';
 import type { Dispatch, SetStateAction } from 'react';
-import type { JsonPagesConfig } from '@olonjs/core';
 import { applyLegacyCloudPayload, fetchLegacyCloudContentPayload } from '@/lib/cloud/cloudContentClient';
-import { cloudFingerprint, writeCachedCloudContent } from '@/lib/cloud/cloudCache';
+import { cloudFingerprint, readCachedPages, writeCachedCloudContent } from '@/lib/cloud/cloudCache';
 import { isAdminPath, patchHistoryNavigation } from '@/lib/spp';
 import { APP_BASE_PATH } from '@/lib/tenantEnv';
 import type { PageConfig, SiteConfig } from '@/types';
@@ -11625,7 +11611,8 @@ type UseAdminStudioContentOptions = {
   apiKey: string;
   setPages: Dispatch<SetStateAction<Record<string, PageConfig>>>;
   setSiteConfig: Dispatch<SetStateAction<SiteConfig>>;
-  setCollections: Dispatch<SetStateAction<NonNullable<JsonPagesConfig['collections']>>>;
+  /** Fired when /admin may paint — after cache hit and/or network attempt settles. */
+  onSettled?: () => void;
 };
 
 /** Studio `/admin` sync via legacy `/content` — never mixed into visitor `/render` bootstrap. */
@@ -11635,13 +11622,28 @@ export function useAdminStudioContent({
   apiKey,
   setPages,
   setSiteConfig,
-  setCollections,
+  onSettled,
 }: UseAdminStudioContentOptions) {
   const loadedRef = useRef(false);
   const inFlightRef = useRef<Promise<void> | null>(null);
+  const settledRef = useRef(false);
 
   useEffect(() => {
-    if (!enabled || apiCandidates.length === 0 || !apiKey.trim()) return;
+    settledRef.current = false;
+    loadedRef.current = false;
+
+    if (!enabled) return;
+
+    const settle = () => {
+      if (settledRef.current) return;
+      settledRef.current = true;
+      onSettled?.();
+    };
+
+    if (apiCandidates.length === 0 || !apiKey.trim()) {
+      settle();
+      return;
+    }
 
     const syncIfAdmin = () => {
       if (!isAdminPath(window.location.pathname, APP_BASE_PATH)) return;
@@ -11650,6 +11652,14 @@ export function useAdminStudioContent({
       const controller = new AbortController();
       const fingerprint = cloudFingerprint(apiCandidates[0]!, apiKey);
 
+      // Paint from cache immediately when present — then refresh from network.
+      const { cachedPages, cachedSite } = readCachedPages(fingerprint);
+      if (cachedPages && Object.keys(cachedPages).length > 0) {
+        setPages(cachedPages);
+        if (cachedSite) setSiteConfig(cachedSite);
+        settle();
+      }
+
       inFlightRef.current = fetchLegacyCloudContentPayload(
         apiCandidates,
         apiKey,
@@ -11676,6 +11686,7 @@ export function useAdminStudioContent({
         })
         .finally(() => {
           inFlightRef.current = null;
+          settle();
         });
     };
 
@@ -11685,7 +11696,7 @@ export function useAdminStudioContent({
       unpatch();
       inFlightRef.current = null;
     };
-  }, [enabled, apiCandidates, apiKey, setPages, setSiteConfig, setCollections]);
+  }, [enabled, apiCandidates, apiKey, setPages, setSiteConfig, onSettled]);
 }
 
 END_OF_FILE_CONTENT
@@ -11893,40 +11904,31 @@ END_OF_FILE_CONTENT
 mkdir -p "src/lib/spp"
 echo "Creating src/lib/spp/cloudConfig.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/spp/cloudConfig.ts"
-function normalizeApiBase(raw: string): string {
-  return raw.trim().replace(/\/+$/, '');
-}
+import { buildApiCandidates } from '@olonjs/react';
 
-export function buildApiCandidates(raw: string): string[] {
-  const base = normalizeApiBase(raw);
-  const withApi = /\/api\/v1$/i.test(base) ? base : `${base}/api/v1`;
-  return Array.from(new Set([withApi, base].filter(Boolean)));
-}
+import { cloudPolicy } from '@/lib/tenantEnv';
+
+export { buildApiCandidates };
 
+/**
+ * Browser-runtime SPP cloud slices.
+ * Credentials ⇒ cloud usable. Save2Repo does not mean “cloud off”
+ * (boot may still be static; live slices remain available).
+ * SSG/bake: local JSON only (SPP §3).
+ */
 export function getSppCloudConfig(): {
   enabled: boolean;
   apiBases: string[];
   apiKey: string;
 } {
-  const apiUrl =
-    import.meta.env.VITE_OLONJS_CLOUD_URL?.trim() ||
-    import.meta.env.VITE_JSONPAGES_CLOUD_URL?.trim() ||
-    '';
-  const apiKey =
-    import.meta.env.VITE_OLONJS_API_KEY?.trim() ||
-    import.meta.env.VITE_JSONPAGES_API_KEY?.trim() ||
-    '';
-  const save2Repo = import.meta.env.VITE_SAVE2REPO === 'true';
-
-  // SSG/bake: local resolved JSON only. Cloud slices are browser-runtime (SPP §3).
-  if (import.meta.env.SSR || !apiUrl || !apiKey || save2Repo) {
+  if (import.meta.env.SSR || !cloudPolicy.isCloudMode) {
     return { enabled: false, apiBases: [], apiKey: '' };
   }
 
   return {
     enabled: true,
-    apiBases: buildApiCandidates(apiUrl),
-    apiKey,
+    apiBases: buildApiCandidates(cloudPolicy.apiUrl),
+    apiKey: cloudPolicy.apiKey,
   };
 }
 
@@ -13092,12 +13094,16 @@ END_OF_FILE_CONTENT
 echo "Creating src/lib/tenantEnv.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/tenantEnv.ts"
 import { normalizeBasePath } from '@olonjs/core';
+import { readCloudEnvFromVite, resolveCloudPolicy, type CloudPolicy } from '@olonjs/react';
 
-export const CLOUD_API_URL =
-  import.meta.env.VITE_OLONJS_CLOUD_URL ?? import.meta.env.VITE_JSONPAGES_CLOUD_URL;
-export const CLOUD_API_KEY =
-  import.meta.env.VITE_OLONJS_API_KEY ?? import.meta.env.VITE_JSONPAGES_API_KEY;
-export const SAVE2REPO_ENABLED = import.meta.env.VITE_SAVE2REPO === 'true';
+/** Single Vite → policy path. Prefer `cloudPolicy` over ad-hoc env reads. */
+export const cloudPolicy: CloudPolicy = resolveCloudPolicy(
+  readCloudEnvFromVite(import.meta.env as Record<string, unknown>),
+);
+
+/** Aliases of `cloudPolicy.apiUrl` / `apiKey` for DNA helpers. */
+export const CLOUD_API_URL = cloudPolicy.apiUrl;
+export const CLOUD_API_KEY = cloudPolicy.apiKey;
 export const APP_BASE_PATH = normalizeBasePath(import.meta.env.BASE_URL || '/');
 export const TENANT_ID = 'alpha';
 
@@ -13106,28 +13112,33 @@ echo "Creating src/lib/useAssetsManifest.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/useAssetsManifest.ts"
 import { useCallback, useEffect, useMemo, useState } from 'react';
 import type { LibraryImageEntry } from '@olonjs/core';
-import { buildApiCandidates } from '@/lib/sppCloudConfig';
-import { CLOUD_API_KEY, CLOUD_API_URL } from '@/lib/tenantEnv';
+import { buildApiCandidates } from '@olonjs/react';
+
+import { cloudPolicy } from '@/lib/tenantEnv';
 
 function normalizeApiBase(raw: string): string {
   return raw.trim().replace(/\/+$/, '');
 }
 
-export function useAssetsManifest(isCloudMode: boolean) {
+/** Asset library — cloud list when `cloudPolicy.isCloudMode`, else local `/api/list-assets`. */
+export function useAssetsManifest(isCloudMode: boolean = cloudPolicy.isCloudMode) {
   const [assetsManifest, setAssetsManifest] = useState<LibraryImageEntry[]>([]);
   const cloudApiCandidates = useMemo(
-    () => (isCloudMode && CLOUD_API_URL ? buildApiCandidates(CLOUD_API_URL) : []),
+    () => (isCloudMode && cloudPolicy.apiUrl ? buildApiCandidates(cloudPolicy.apiUrl) : []),
     [isCloudMode],
   );
 
   const loadAssetsManifest = useCallback(async (): Promise<void> => {
-    if (isCloudMode && CLOUD_API_URL && CLOUD_API_KEY) {
-      const apiBases = cloudApiCandidates.length > 0 ? cloudApiCandidates : [normalizeApiBase(CLOUD_API_URL)];
+    if (isCloudMode && cloudPolicy.apiUrl && cloudPolicy.apiKey) {
+      const apiBases =
+        cloudApiCandidates.length > 0
+          ? cloudApiCandidates
+          : [normalizeApiBase(cloudPolicy.apiUrl)];
       for (const apiBase of apiBases) {
         try {
           const res = await fetch(`${apiBase}/assets/list?limit=200`, {
             method: 'GET',
-            headers: { Authorization: `Bearer ${CLOUD_API_KEY}` },
+            headers: { Authorization: `Bearer ${cloudPolicy.apiKey}` },
           });
           const body = (await res.json().catch(() => ({}))) as { items?: LibraryImageEntry[] };
           if (!res.ok) continue;
@@ -13401,6 +13412,8 @@ echo "Creating src/lib/useFormSubmit.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/useFormSubmit.ts"
 import { useState, useCallback } from 'react';
 
+import { cloudPolicy } from '@/lib/tenantEnv';
+
 export type SubmitStatus = 'idle' | 'submitting' | 'success' | 'error';
 
 interface UseFormSubmitOptions {
@@ -13413,22 +13426,20 @@ export function useFormSubmit({ source, tenantId }: UseFormSubmitOptions) {
   const [message, setMessage] = useState<string>('');
 
   const submit = useCallback(async (
-    formData: FormData, 
-    recipientEmail: string, 
-    pageSlug: string, 
+    formData: FormData,
+    recipientEmail: string,
+    pageSlug: string,
     sectionId: string
   ) => {
-    const cloudApiUrl = import.meta.env.VITE_JSONPAGES_CLOUD_URL as string | undefined;
-    const cloudApiKey = import.meta.env.VITE_JSONPAGES_API_KEY as string | undefined;
+    const { apiUrl, apiKey } = cloudPolicy;
 
-    if (!cloudApiUrl || !cloudApiKey) {
+    if (!apiUrl || !apiKey) {
       setStatus('error');
       setMessage('Configurazione API non disponibile. Riprova tra poco.');
       return false;
     }
 
-    // Trasformiamo FormData in un oggetto piatto per il payload JSON
-    const data: Record<string, any> = {};
+    const data: Record<string, string> = {};
     formData.forEach((value, key) => {
       data[key] = String(value).trim();
     });
@@ -13443,18 +13454,17 @@ export function useFormSubmit({ source, tenantId }: UseFormSubmitOptions) {
       submittedAt: new Date().toISOString(),
     };
 
-    // Idempotency Key per evitare doppi invii accidentali
     const idempotencyKey = `form-${sectionId}-${Date.now()}`;
 
     setStatus('submitting');
     setMessage('Invio in corso...');
 
     try {
-      const apiBase = cloudApiUrl.replace(/\/$/, '');
+      const apiBase = apiUrl.replace(/\/$/, '');
       const response = await fetch(`${apiBase}/forms/submit`, {
         method: 'POST',
         headers: {
-          Authorization: `Bearer ${cloudApiKey}`,
+          Authorization: `Bearer ${apiKey}`,
           'Content-Type': 'application/json',
           'Idempotency-Key': idempotencyKey,
         },
@@ -13484,23 +13494,18 @@ export function useFormSubmit({ source, tenantId }: UseFormSubmitOptions) {
   }, []);
 
   return { submit, status, message, reset };
-}
+}
+
 END_OF_FILE_CONTENT
 echo "Creating src/lib/useOlonForms.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/useOlonForms.ts"
 import { useCallback, useEffect, useState } from 'react';
 import type { FormState } from '@olonjs/react';
 
-const API_BASE =
-  (import.meta.env.VITE_OLONJS_CLOUD_URL as string | undefined) ??
-  (import.meta.env.VITE_JSONPAGES_CLOUD_URL as string | undefined);
-
-const API_KEY =
-  (import.meta.env.VITE_OLONJS_API_KEY as string | undefined) ??
-  (import.meta.env.VITE_JSONPAGES_API_KEY as string | undefined);
+import { cloudPolicy } from '@/lib/tenantEnv';
 
 interface UseOlonFormsOptions {
-  /** Override the submit endpoint. Defaults to VITE_OLONJS_CLOUD_URL/forms/submit */
+  /** Override the submit endpoint. Defaults to cloudPolicy.apiUrl/forms/submit */
   endpoint?: string;
 }
 
@@ -13519,13 +13524,16 @@ export function useOlonForms(options?: UseOlonFormsOptions): { states: Record<st
   }, []);
 
   useEffect(() => {
+    const apiUrl = cloudPolicy.apiUrl;
+    const apiKey = cloudPolicy.apiKey;
+
     const resolvedBase = options?.endpoint
       ? options.endpoint.replace(/\/$/, '')
-      : API_BASE
-        ? API_BASE.replace(/\/$/, '')
+      : apiUrl
+        ? apiUrl.replace(/\/$/, '')
         : null;
 
-    if (!resolvedBase || !API_KEY) {
+    if (!resolvedBase || !apiKey) {
       console.warn('[useOlonForms] Missing API endpoint or key — forms will not submit.');
       return;
     }
@@ -13568,7 +13576,7 @@ export function useOlonForms(options?: UseOlonFormsOptions): { states: Record<st
         const response = await fetch(endpoint, {
           method: 'POST',
           headers: {
-            Authorization: `Bearer ${API_KEY}`,
+            Authorization: `Bearer ${apiKey}`,
             'Content-Type': 'application/json',
             'Idempotency-Key': `form-${formId}-${Date.now()}`,
           },
@@ -13619,7 +13627,7 @@ export function useOlonForms(options?: UseOlonFormsOptions): { states: Record<st
 END_OF_FILE_CONTENT
 echo "Creating src/lib/useTenantBootstrap.ts..."
 cat << 'END_OF_FILE_CONTENT' > "src/lib/useTenantBootstrap.ts"
-import { useEffect, useMemo, useRef, useState } from 'react';
+import { useCallback, useEffect, useMemo, useRef, useState } from 'react';
 
 import { logBootstrapEvent, toCloudLoadFailure } from '@/lib/cloud/bootstrapTelemetry';
 
@@ -13649,7 +13657,7 @@ import {
 
 import type { JsonPagesConfig } from '@olonjs/core';
 
-import { APP_BASE_PATH, CLOUD_API_KEY, CLOUD_API_URL, SAVE2REPO_ENABLED } from '@/lib/tenantEnv';
+import { APP_BASE_PATH, CLOUD_API_KEY, CLOUD_API_URL, cloudPolicy } from '@/lib/tenantEnv';
 
 import type { MenuConfig, PageConfig, SiteConfig, ThemeConfig } from '@/types';
 
@@ -13731,13 +13739,10 @@ export function useTenantBootstrap({
 
 }: UseTenantBootstrapOptions) {
 
-  const isCloudMode = Boolean(CLOUD_API_URL && CLOUD_API_KEY);
-
-  const isSave2RepoMode = isCloudMode && SAVE2REPO_ENABLED;
+  const { isCloudMode, bootSource } = cloudPolicy;
 
-  const isHotSaveMode = isCloudMode && !isSave2RepoMode;
-
-  const useRenderBootstrap = isHotSaveMode;
+  /** Live SPP render boot — only when bootSource is live (not static Save2Repo). */
+  const useRenderBootstrap = bootSource === 'live';
 
 
 
@@ -13801,7 +13806,11 @@ export function useTenantBootstrap({
 
   const isTenantEmpty = Object.keys(pages).length === 0;
 
-
+  /** Call when live /admin content sync has finished (success, cache, or error). */
+  const markCloudContentReady = useCallback(() => {
+    setShowTopProgress(false);
+    setHasInitialCloudResolved(true);
+  }, []);
 
   const retryBootstrap = () => {
 
@@ -13841,7 +13850,7 @@ export function useTenantBootstrap({
 
 
 
-    if (isSave2RepoMode) {
+    if (bootSource === 'static') {
 
       if (contentLoadInFlight.current) return;
 
@@ -13938,17 +13947,12 @@ export function useTenantBootstrap({
 
 
     if (isAdminPath(window.location.pathname, APP_BASE_PATH)) {
-
+      // Live /admin: content comes from useAdminStudioContent — do not paint empty first.
       setContentMode('cloud');
-
       setContentFallback(null);
-
-      setShowTopProgress(false);
-
-      setHasInitialCloudResolved(true);
-
+      setShowTopProgress(true);
+      setHasInitialCloudResolved(false);
       return;
-
     }
 
 
@@ -14245,7 +14249,7 @@ export function useTenantBootstrap({
 
     isCloudMode,
 
-    isSave2RepoMode,
+    bootSource,
 
     useRenderBootstrap,
 
@@ -14291,9 +14295,7 @@ export function useTenantBootstrap({
 
     isCloudMode,
 
-    isSave2RepoMode,
-
-    isHotSaveMode,
+    bootSource,
 
     contentMode,
 
@@ -14307,6 +14309,8 @@ export function useTenantBootstrap({
 
     isTenantEmpty,
 
+    markCloudContentReady,
+
     retryBootstrap,
 
   };

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@olonjs/cli",
-    "version": "3.0.151",
+    "version": "3.0.152",
     "description": "The Sovereign CLI Engine for OlonJS.",
     "type": "module",
     "bin": {