fimo 0.9.0-experimental.8 → 0.9.0-experimental.9

package/dist/runtime/primitives/components/RichText.d.ts

@@ -3,7 +3,11 @@ import { type FimoRichText, type FimoRichTextComponents } from '../lib/index.js'
 type RichTextProps = {
     value: FimoRichText;
     components?: FimoRichTextComponents;
+    /** Wrapper element. Use `span` when the block sits inside phrasing
+     *  content (a `<p>`): a div there is invalid HTML — the browser closes
+     *  the paragraph early and React trashes the hydrated tree. */
+    as?: 'div' | 'span';
 } & Omit<ComponentPropsWithoutRef<'div'>, 'children'>;
-export declare function RichText({ value, components, ...props }: RichTextProps): import("react/jsx-runtime").JSX.Element;
+export declare function RichText({ value, components, as: Wrapper, ...props }: RichTextProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=RichText.d.ts.map

package/dist/runtime/primitives/components/RichText.js

@@ -128,8 +128,8 @@ function renderNode(node, components, key) {
     }
     return _jsx(Fragment, { children: children }, key);
 }
-export function RichText({ value, components, ...props }) {
+export function RichText({ value, components, as: Wrapper = 'div', ...props }) {
     const source = value[FIMO_SOURCE];
     const { value: liveContent, ref } = useFimoLiveValue(value.content);
-    return (_jsx("div", { ref: ref, ...props, "data-fimo-source": source, "data-fimo-richtext": "", children: renderNode(liveContent, components, 0) }));
+    return (_jsx(Wrapper, { ref: ref, ...props, "data-fimo-source": source, "data-fimo-richtext": "", children: renderNode(liveContent, components, 0) }));
 }

package/dist/runtime/react/FimoSpaProviders.js

@@ -1,10 +1,11 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
-import { useEffect, useMemo, useState } from 'react';
+import { useEffect, useMemo, useRef, useState } from 'react';
 import { getFimoDefaultLocale, getFimoLocales } from '../i18n/locale.js';
 import { fetchLabelBundle, serializeBundle } from '../shared/labels-fetch.pure.js';
 import { fetchWrappedContent } from '../wrapped/content-fetch.pure.js';
 import { WrappedProviders } from '../wrapped/WrappedProviders.js';
+import { readInitialSpaContent, writeSpaContentCache } from './spa-content-cache.js';
 /** Browser-safe stable signature (labelSignature uses Buffer, server-only). */
 function bundleSignature(bundle) {
     const serialized = serializeBundle(bundle);
@@ -34,37 +35,87 @@ function bundleSignature(bundle) {
  * router without depending on one.
  */
 export function FimoSpaProviders({ config, apiUrl, previewScriptUrl, media, richText, locale, children, }) {
-    const [labels, setLabels] = useState(undefined);
-    const [content, setContent] = useState(undefined);
+    // Synchronous first paint: baked SSG payload or the last visit's cached
+    // one renders IMMEDIATELY (the SDK owns rendering — no fallback flash
+    // while the network round-trips); the fetches below revalidate it.
+    const initial = useMemo(() => readInitialSpaContent(apiUrl), [apiUrl]);
+    const [labels, setLabels] = useState(initial?.labels ?? undefined);
+    const [content, setContent] = useState(initial?.content ?? undefined);
+    const latestRef = useRef({
+        labels: initial?.labels ?? undefined,
+        content: initial?.content ?? undefined,
+    });
     useEffect(() => {
         if (!apiUrl) {
             return;
         }
-        let cancelled = false;
-        const defaultLocale = getFimoDefaultLocale(config);
-        fetchLabelBundle(apiUrl, getFimoLocales(config), defaultLocale)
-            .then((bundle) => {
-            if (!cancelled) {
-                setLabels({ ...bundle, signature: bundleSignature(bundle) });
+        let disposed = false;
+        const persist = () => {
+            writeSpaContentCache(apiUrl, { labels: latestRef.current.labels, content: latestRef.current.content });
+        };
+        const revalidate = () => {
+            const defaultLocale = getFimoDefaultLocale(config);
+            fetchLabelBundle(apiUrl, getFimoLocales(config), defaultLocale)
+                .then((bundle) => {
+                if (!disposed) {
+                    const next = { ...bundle, signature: bundleSignature(bundle) };
+                    latestRef.current.labels = next;
+                    setLabels(next);
+                    persist();
+                }
+            })
+                .catch(() => {
+                // Unreachable API: keep rendering the cached/baked values or fallbacks.
+            });
+            // Wrapped rich text and media live in the plumbing types — without this
+            // fetch a client-rendered app only ever shows their inline fallbacks
+            // and Studio edits to them render nowhere.
+            fetchWrappedContent(apiUrl)
+                .then((fetched) => {
+                if (!disposed) {
+                    latestRef.current.content = fetched;
+                    setContent(fetched);
+                    persist();
+                }
+            })
+                .catch(() => {
+                // Unreachable API: keep rendering the cached/baked values or fallbacks.
+            });
+        };
+        revalidate();
+        // Live updates, no refresh needed:
+        // 1. Inside the Fimo Studio preview, every save posts
+        //    `{ type: 'content/refresh' }` into the iframe — refetch on the spot
+        //    (same contract the template runtime's RefreshContentProvider uses).
+        // 2. In a plain tab, coming back to the site (alt-tab from the Studio)
+        //    revalidates on focus/visibility — edits appear without a reload.
+        let lastRun = Date.now();
+        const throttledRevalidate = () => {
+            if (Date.now() - lastRun < 1500) {
+                return;
+            }
+            lastRun = Date.now();
+            revalidate();
+        };
+        const onMessage = (event) => {
+            if (event.data?.type === 'content/refresh') {
+                lastRun = Date.now();
+                revalidate();
             }
-        })
-            .catch(() => {
-            // Unreachable API: keep rendering the inline fallbacks.
-        });
-        // Wrapped rich text and media live in the plumbing types — without this
-        // fetch a client-rendered app only ever shows their inline fallbacks
-        // and Studio edits to them render nowhere.
-        fetchWrappedContent(apiUrl)
-            .then((fetched) => {
-            if (!cancelled) {
-                setContent(fetched);
+        };
+        const onVisibility = () => {
+            if (document.visibilityState === 'visible') {
+                throttledRevalidate();
             }
-        })
-            .catch(() => {
-            // Unreachable API: keep rendering the inline fallbacks.
-        });
+        };
+        window.addEventListener('message', onMessage);
+        window.addEventListener('focus', throttledRevalidate);
+        document.addEventListener('visibilitychange', onVisibility);
         return () => {
-            cancelled = true;
+            disposed = true;
+            window.removeEventListener('message', onMessage);
+            window.removeEventListener('focus', throttledRevalidate);
+            document.removeEventListener('visibilitychange', onVisibility);
         };
     }, [apiUrl, config]);
     // Explicitly-passed maps win over the fetched ones (caller override).

package/dist/runtime/react/index.d.ts

@@ -30,4 +30,5 @@ export type { FimoLocaleResolution } from '../i18n/locale.js';
 export { getDisplayRoutes } from '../shared/display-routes.js';
 export type { DisplayRoute, ParamInfo } from '../shared/display-routes.js';
 export type { FimoConfig, FimoRouteConfig, FimoSEO } from '../shared/fimo-config.types.js';
+export { serializeFimoSpaContent } from './spa-content-cache.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/runtime/react/index.js

@@ -37,3 +37,4 @@ export { FimoLocaleProvider, useLocale } from '../i18n/FimoLocaleContext.js';
 export { getFimoDefaultLocale, getFimoLocales, getFimoTextDirection, localizeFimoPath, resolveFimoLocale, toHtmlLang, } from '../i18n/locale.js';
 // Config + routes
 export { getDisplayRoutes } from '../shared/display-routes.js';
+export { serializeFimoSpaContent } from './spa-content-cache.js';

package/dist/runtime/react/spa-content-cache.d.ts

@@ -0,0 +1,27 @@
+import type { WrappedContent } from '../wrapped/content-fetch.pure.js';
+import type { WrappedLabels } from '../wrapped/WrappedProviders.js';
+/**
+ * Instant first paint for client-rendered wrapped apps: the SDK controls
+ * rendering, so it never has to flash fallbacks while the network round
+ * trips. Two synchronous sources, in priority order:
+ *
+ * 1. `window.__FIMO_CONTENT__` — baked by the site's SSG/prerender step
+ *    (`serializeFimoSpaContent`), zero flash even on the first ever visit;
+ * 2. the last fetched payload cached in localStorage — instant from the
+ *    second visit on, revalidated in the background (stale-while-revalidate).
+ */
+export interface SpaContentPayload {
+    labels?: WrappedLabels;
+    content?: WrappedContent;
+}
+declare global {
+    interface Window {
+        __FIMO_CONTENT__?: SpaContentPayload;
+    }
+}
+export declare function readInitialSpaContent(apiUrl: string | undefined): SpaContentPayload | null;
+export declare function writeSpaContentCache(apiUrl: string, payload: SpaContentPayload): void;
+/** SSG helper: a script tag baking the payload into prerendered HTML so the
+ *  provider hydrates it synchronously — zero content flash. */
+export declare function serializeFimoSpaContent(payload: SpaContentPayload): string;
+//# sourceMappingURL=spa-content-cache.d.ts.map

package/dist/runtime/react/spa-content-cache.js

@@ -0,0 +1,36 @@
+const CACHE_PREFIX = 'fimo:spa-content:';
+export function readInitialSpaContent(apiUrl) {
+    if (typeof window === 'undefined') {
+        return null;
+    }
+    if (window.__FIMO_CONTENT__ && typeof window.__FIMO_CONTENT__ === 'object') {
+        return window.__FIMO_CONTENT__;
+    }
+    if (!apiUrl) {
+        return null;
+    }
+    try {
+        const raw = window.localStorage.getItem(CACHE_PREFIX + apiUrl);
+        return raw ? JSON.parse(raw) : null;
+    }
+    catch {
+        return null;
+    }
+}
+export function writeSpaContentCache(apiUrl, payload) {
+    if (typeof window === 'undefined') {
+        return;
+    }
+    try {
+        window.localStorage.setItem(CACHE_PREFIX + apiUrl, JSON.stringify(payload));
+    }
+    catch {
+        // Quota/private mode: the cache is an optimization, never a requirement.
+    }
+}
+/** SSG helper: a script tag baking the payload into prerendered HTML so the
+ *  provider hydrates it synchronously — zero content flash. */
+export function serializeFimoSpaContent(payload) {
+    const json = JSON.stringify(payload).replace(/</g, '\\u003c');
+    return `<script>window.__FIMO_CONTENT__=${json}</script>`;
+}

package/dist/runtime/wrapped/FimoRichTextBlock.d.ts

@@ -7,6 +7,9 @@ interface FimoRichTextBlockProps {
     children?: ReactNode;
     components?: FimoRichTextComponents;
     className?: string;
+    /** Wrapper element — `span` when the block sits inside a `<p>` (a div
+     *  there is invalid HTML and breaks hydration). */
+    as?: 'div' | 'span';
 }
 /**
  * Wraps formatted text (bold, italic, underline, links) so it becomes
@@ -18,6 +21,6 @@ interface FimoRichTextBlockProps {
  *     <p>We help teams <strong>ship faster</strong> and <em>stay safe</em>.</p>
  *   </FimoRichTextBlock>
  */
-export declare function FimoRichTextBlock({ id, children, components, className }: FimoRichTextBlockProps): import("react/jsx-runtime").JSX.Element;
+export declare function FimoRichTextBlock({ id, children, components, className, as }: FimoRichTextBlockProps): import("react/jsx-runtime").JSX.Element;
 export {};
 //# sourceMappingURL=FimoRichTextBlock.d.ts.map

package/dist/runtime/wrapped/FimoRichTextBlock.js

@@ -13,10 +13,10 @@ import { useWrappedRichText } from './WrappedContentContext.js';
  *     <p>We help teams <strong>ship faster</strong> and <em>stay safe</em>.</p>
  *   </FimoRichTextBlock>
  */
-export function FimoRichTextBlock({ id, children, components, className }) {
+export function FimoRichTextBlock({ id, children, components, className, as }) {
     const entry = useWrappedRichText(id);
     if (!entry) {
         return _jsx(_Fragment, { children: children });
     }
-    return (_jsx(RichText, { value: new FimoRichText(entry.content, entry.source), components: components, className: className }));
+    return (_jsx(RichText, { value: new FimoRichText(entry.content, entry.source), components: components, className: className, as: as }));
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fimo",
-  "version": "0.9.0-experimental.8",
+  "version": "0.9.0-experimental.9",
   "description": "Fimo CLI - create, deploy, and manage Fimo projects",
   "bin": {
     "fimo": "dist/cli/index.js"

package/templates/react-router/package.json

@@ -21,7 +21,7 @@
     "cmdk": "^1.1.1",
     "date-fns": "^4.1.0",
     "embla-carousel-react": "^8.6.0",
-    "fimo": "0.9.0-experimental.8",
+    "fimo": "0.9.0-experimental.9",
     "input-otp": "^1.4.2",
     "isbot": "^5",
     "lucide-react": "^0.577.0",