fimo 0.14.0 → 0.15.0-staging.1

package/dist/runtime/primitives/lib/primitives.d.ts

@@ -1,4 +1,3 @@
-import type React from 'react';
 /**
  * Fimo Primitives - Source tracking for inline editing
  *
@@ -98,59 +97,6 @@ export interface FimoRichTextContent {
     }>;
     text?: string;
 }
-/**
- * Props passed to custom node renderers
- */
-export interface FimoRichTextNodeProps {
-    children?: React.ReactNode;
-    node: FimoRichTextContent;
-}
-/**
- * Props passed to custom mark renderers
- */
-export interface FimoRichTextMarkProps {
-    children: React.ReactNode;
-    mark: {
-        type: string;
-        attrs?: Record<string, unknown>;
-    };
-}
-/**
- * Custom renderer map for RichText component.
- *
- * Override how specific node types or mark types are rendered.
- * Unspecified types fall back to default HTML elements.
- *
- * @example
- * const components: FimoRichTextComponents = {
- *   heading: ({ node, children }) => <MyHeading level={node.attrs?.level}>{children}</MyHeading>,
- *   image: ({ node }) => <OptimizedImage src={node.attrs?.src} alt={node.attrs?.alt} />,
- *   link: ({ mark, children }) => <CustomLink href={mark.attrs?.href}>{children}</CustomLink>,
- * }
- */
-export interface FimoRichTextComponents {
-    paragraph?: React.ComponentType<FimoRichTextNodeProps>;
-    heading?: React.ComponentType<FimoRichTextNodeProps>;
-    bulletList?: React.ComponentType<FimoRichTextNodeProps>;
-    orderedList?: React.ComponentType<FimoRichTextNodeProps>;
-    listItem?: React.ComponentType<FimoRichTextNodeProps>;
-    blockquote?: React.ComponentType<FimoRichTextNodeProps>;
-    codeBlock?: React.ComponentType<FimoRichTextNodeProps>;
-    horizontalRule?: React.ComponentType<FimoRichTextNodeProps>;
-    hardBreak?: React.ComponentType<FimoRichTextNodeProps>;
-    image?: React.ComponentType<FimoRichTextNodeProps>;
-    table?: React.ComponentType<FimoRichTextNodeProps>;
-    tableRow?: React.ComponentType<FimoRichTextNodeProps>;
-    tableCell?: React.ComponentType<FimoRichTextNodeProps>;
-    tableHeader?: React.ComponentType<FimoRichTextNodeProps>;
-    iframe?: React.ComponentType<FimoRichTextNodeProps>;
-    bold?: React.ComponentType<FimoRichTextMarkProps>;
-    italic?: React.ComponentType<FimoRichTextMarkProps>;
-    underline?: React.ComponentType<FimoRichTextMarkProps>;
-    strike?: React.ComponentType<FimoRichTextMarkProps>;
-    code?: React.ComponentType<FimoRichTextMarkProps>;
-    link?: React.ComponentType<FimoRichTextMarkProps>;
-}
 /**
  * FimoRichText - Rich text content with source tracking
  *

package/dist/runtime/primitives/lib/primitives.js

@@ -1,3 +1,9 @@
+/**
+ * Fimo Primitives - Source tracking for inline editing
+ *
+ * All Fimo types carry hidden metadata that enables the preview editor
+ * to know where content comes from (schema field, translation key, etc.)
+ */
 var _a, _b, _c, _d, _e, _f;
 // Symbol for accessing fimo metadata (hidden from JSON.stringify)
 export const FIMO_SOURCE = Symbol.for('fimo.source');

package/dist/runtime/primitives/lib/render-rich-text.d.ts

@@ -0,0 +1,3 @@
+import type { FimoRichTextContent } from './primitives.js';
+export declare function renderRichTextHtml(document: FimoRichTextContent | null | undefined): string;
+//# sourceMappingURL=render-rich-text.d.ts.map

package/dist/runtime/primitives/lib/render-rich-text.js

@@ -0,0 +1,112 @@
+const IFRAME_STYLE = 'position:relative;width:100%;padding-bottom:56.25%;border-radius:0.375rem;overflow:hidden';
+const IFRAME_CONTENT_STYLE = 'position:absolute;top:0;left:0;width:100%;height:100%;border:0';
+function escapeHtml(value) {
+    return String(value ?? '')
+        .replace(/&/g, '&')
+        .replace(/</g, '&lt;')
+        .replace(/>/g, '&gt;')
+        .replace(/"/g, '&quot;')
+        .replace(/'/g, '&#39;');
+}
+function safeUrl(value, protocols) {
+    if (typeof value !== 'string' || value.trim() === '') {
+        return undefined;
+    }
+    const url = value.trim();
+    try {
+        const parsed = new URL(url, 'https://fimo.invalid');
+        return protocols.includes(parsed.protocol) ? url : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function attribute(name, value) {
+    return value == null || value === '' ? '' : ` ${name}="${escapeHtml(value)}"`;
+}
+function renderMarks(node) {
+    let content = escapeHtml(node.text);
+    for (const mark of node.marks ?? []) {
+        switch (mark.type) {
+            case 'bold':
+            case 'strong':
+                content = `<strong>${content}</strong>`;
+                break;
+            case 'italic':
+            case 'em':
+                content = `<em>${content}</em>`;
+                break;
+            case 'underline':
+                content = `<u>${content}</u>`;
+                break;
+            case 'strike':
+                content = `<s>${content}</s>`;
+                break;
+            case 'code':
+                content = `<code>${content}</code>`;
+                break;
+            case 'link': {
+                const href = safeUrl(mark.attrs?.href, ['http:', 'https:', 'mailto:', 'tel:']);
+                if (href) {
+                    content = `<a href="${escapeHtml(href)}"${attribute('target', mark.attrs?.target)}${attribute('rel', mark.attrs?.rel)}>${content}</a>`;
+                }
+                break;
+            }
+        }
+    }
+    return content;
+}
+function renderNode(node) {
+    if (node.type === 'text') {
+        return renderMarks(node);
+    }
+    const children = (node.content ?? []).map(renderNode).join('');
+    switch (node.type) {
+        case 'doc':
+            return children;
+        case 'paragraph':
+            return `<p>${children}</p>`;
+        case 'heading': {
+            const requestedLevel = Number(node.attrs?.level);
+            const level = Number.isInteger(requestedLevel) ? Math.min(6, Math.max(1, requestedLevel)) : 1;
+            return `<h${level}>${children}</h${level}>`;
+        }
+        case 'bulletList':
+            return `<ul>${children}</ul>`;
+        case 'orderedList':
+            return `<ol>${children}</ol>`;
+        case 'listItem':
+            return `<li>${children}</li>`;
+        case 'blockquote':
+            return `<blockquote>${children}</blockquote>`;
+        case 'codeBlock':
+            return `<pre><code>${children}</code></pre>`;
+        case 'horizontalRule':
+            return '<hr>';
+        case 'hardBreak':
+            return '<br>';
+        case 'image': {
+            const src = safeUrl(node.attrs?.src, ['http:', 'https:']);
+            return src ? `<img src="${escapeHtml(src)}" alt="${escapeHtml(node.attrs?.alt)}">` : '';
+        }
+        case 'table':
+            return `<table class="border-border w-full border-collapse border"><tbody>${children}</tbody></table>`;
+        case 'tableRow':
+            return `<tr class="border-border border-b last:border-b-0">${children}</tr>`;
+        case 'tableCell':
+            return `<td class="border-border border px-3 py-2 align-top">${children}</td>`;
+        case 'tableHeader':
+            return `<th class="border-border bg-muted border px-3 py-2 text-left align-top font-semibold">${children}</th>`;
+        case 'iframe': {
+            const src = safeUrl(node.attrs?.src, ['http:', 'https:']);
+            return src
+                ? `<div style="${IFRAME_STYLE}"><iframe src="${escapeHtml(src)}" style="${IFRAME_CONTENT_STYLE}" allowfullscreen></iframe></div>`
+                : '';
+        }
+        default:
+            return children;
+    }
+}
+export function renderRichTextHtml(document) {
+    return document ? renderNode(document) : '';
+}

package/dist/runtime/react/primitives/contracts.d.ts

@@ -1,6 +1,40 @@
-import type { ComponentPropsWithoutRef, ElementType, ReactNode } from 'react';
+import type { ComponentPropsWithoutRef, ComponentType, ElementType, ReactNode } from 'react';
 import type { ImageFit } from '../../primitives/lib/image-optimization.js';
-import type { FimoBoolean, FimoDate, FimoMedia, FimoRichText, FimoRichTextComponents, FimoString } from '../../primitives/lib/index.js';
+import type { FimoBoolean, FimoDate, FimoMedia, FimoRichText, FimoRichTextContent, FimoString } from '../../primitives/lib/index.js';
+export interface FimoRichTextNodeProps {
+    children?: ReactNode;
+    node: FimoRichTextContent;
+}
+export interface FimoRichTextMarkProps {
+    children: ReactNode;
+    mark: {
+        type: string;
+        attrs?: Record<string, unknown>;
+    };
+}
+export interface FimoRichTextComponents {
+    paragraph?: ComponentType<FimoRichTextNodeProps>;
+    heading?: ComponentType<FimoRichTextNodeProps>;
+    bulletList?: ComponentType<FimoRichTextNodeProps>;
+    orderedList?: ComponentType<FimoRichTextNodeProps>;
+    listItem?: ComponentType<FimoRichTextNodeProps>;
+    blockquote?: ComponentType<FimoRichTextNodeProps>;
+    codeBlock?: ComponentType<FimoRichTextNodeProps>;
+    horizontalRule?: ComponentType<FimoRichTextNodeProps>;
+    hardBreak?: ComponentType<FimoRichTextNodeProps>;
+    image?: ComponentType<FimoRichTextNodeProps>;
+    table?: ComponentType<FimoRichTextNodeProps>;
+    tableRow?: ComponentType<FimoRichTextNodeProps>;
+    tableCell?: ComponentType<FimoRichTextNodeProps>;
+    tableHeader?: ComponentType<FimoRichTextNodeProps>;
+    iframe?: ComponentType<FimoRichTextNodeProps>;
+    bold?: ComponentType<FimoRichTextMarkProps>;
+    italic?: ComponentType<FimoRichTextMarkProps>;
+    underline?: ComponentType<FimoRichTextMarkProps>;
+    strike?: ComponentType<FimoRichTextMarkProps>;
+    code?: ComponentType<FimoRichTextMarkProps>;
+    link?: ComponentType<FimoRichTextMarkProps>;
+}
 export type BooleanProps<T extends ElementType = 'span'> = {
     value: FimoBoolean;
     as?: T;
@@ -46,6 +80,10 @@ export type TextProps<T extends ElementType = 'span'> = {
     as?: T;
     children?: (value: string) => ReactNode;
 } & Omit<ComponentPropsWithoutRef<T>, 'value' | 'as' | 'children'>;
+export type LabelProps<T extends ElementType = 'span'> = Omit<TextProps<T>, 'value'> & {
+    /** Literal label key, e.g. `hero.title`. Dynamic keys cannot be validated. */
+    value: string;
+};
 export interface BaseVideoProps extends Omit<ComponentPropsWithoutRef<'video'>, 'src' | 'children'> {
     overrideSrc?: string;
 }

package/dist/runtime/react/primitives/renderers/ImageRenderer.js

@@ -1,50 +1,31 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { buildOptimizedUrl, clampQuality, computeImageOptimizationConfig, isOptimizableFimoUrl, resolveFit, toObjectFit, toPositiveInt, } from '../../../primitives/lib/image-optimization.js';
+import { resolveImagePresentation } from '../../../primitives/lib/image-optimization.js';
 import { FIMO_SOURCE } from '../../../primitives/lib/primitives.js';
 export function ImageRenderer({ value: media, children, quality, unoptimized = false, fit, width, height, alt: altOverride, overrideSrc, srcSet: srcSetOverride, sizes, style, hostSuffixes, elementRef, ...imgProps }) {
     const mediaSource = media[FIMO_SOURCE];
     if (children) {
         return (_jsx("span", { ref: elementRef, "data-fimo-source": mediaSource, children: children(media) }));
     }
-    const normalizedQuality = clampQuality(quality);
-    const normalizedFit = resolveFit(fit);
-    const requestedWidth = toPositiveInt(width);
-    const requestedHeight = toPositiveInt(height);
-    const displayWidth = requestedWidth ?? media.width;
-    const displayHeight = requestedHeight ?? media.height;
-    const originalSrc = media.url;
-    const resolvedAlt = altOverride ?? media.alt;
-    const hasSizesAttr = typeof sizes === 'string' && sizes.trim().length > 0;
-    const hasSizingHint = hasSizesAttr || requestedWidth !== undefined || requestedHeight !== undefined;
-    const canOptimizeSource = !unoptimized && isOptimizableFimoUrl(originalSrc, hostSuffixes);
-    const shouldOptimize = canOptimizeSource && hasSizingHint;
-    const { generatedSrcSet, transformWidth, transformDpr } = computeImageOptimizationConfig({
-        shouldOptimize,
-        hasSizesAttr,
-        srcSetOverride,
-        originalSrc,
+    const image = resolveImagePresentation({
+        src: media.url,
+        alt: altOverride ?? media.alt,
         mediaWidth: media.width,
-        renderWidth: displayWidth,
-        quality: normalizedQuality,
-        fit: normalizedFit,
+        mediaHeight: media.height,
+        quality,
+        fit,
+        unoptimized,
+        overrideSrc,
+        width,
+        height,
+        sizes,
+        srcSet: srcSetOverride,
         hostSuffixes,
     });
-    const finalSrcSet = srcSetOverride ?? generatedSrcSet;
-    const optimizedSrc = shouldOptimize
-        ? buildOptimizedUrl(originalSrc, {
-            width: transformWidth,
-            quality: normalizedQuality,
-            fit: normalizedFit,
-            dpr: transformDpr,
-            hostSuffixes,
-        })
-        : originalSrc;
-    const finalSrc = overrideSrc ?? optimizedSrc;
     const finalStyle = style?.objectFit
         ? style
         : {
             ...style,
-            objectFit: toObjectFit(normalizedFit),
+            objectFit: image.objectFit,
         };
-    return (_jsx("img", { ref: elementRef, src: finalSrc, alt: resolvedAlt, width: displayWidth, height: displayHeight, style: finalStyle, sizes: sizes, srcSet: finalSrcSet, ...imgProps, "data-fimo-source": mediaSource }));
+    return (_jsx("img", { ref: elementRef, src: image.src, alt: image.alt, width: image.width, height: image.height, style: finalStyle, sizes: image.sizes, srcSet: image.srcSet, ...imgProps, "data-fimo-source": mediaSource }));
 }

package/dist/runtime/react/primitives/renderers/RichTextRenderer.d.ts

@@ -1,5 +1,6 @@
 import { type ComponentPropsWithoutRef, type Ref } from 'react';
-import type { FimoRichTextComponents, FimoRichTextContent } from '../../../primitives/lib/index.js';
+import type { FimoRichTextContent } from '../../../primitives/lib/index.js';
+import type { FimoRichTextComponents } from '../contracts.js';
 interface RichTextRendererProps extends Omit<ComponentPropsWithoutRef<'div'>, 'children'> {
     document: FimoRichTextContent | null | undefined;
     source: string | undefined;

package/dist/runtime/react/primitives/renderers/StaticImage.js

@@ -1,5 +1,5 @@
 import { jsx as _jsx } from "react/jsx-runtime";
-import { clampQuality, resolveFit, toObjectFit, toPositiveInt, isOptimizableFimoUrl, buildOptimizedUrl, computeImageOptimizationConfig, } from '../../../primitives/lib/image-optimization.js';
+import { resolveImagePresentation } from '../../../primitives/lib/image-optimization.js';
 /**
  * Optimized image component for non-schema images.
  *
@@ -36,40 +36,23 @@ export function StaticImage(props) {
     if (!src) {
         return null;
     }
-    const normalizedQuality = clampQuality(quality);
-    const normalizedFit = resolveFit(fit);
-    const requestedWidth = toPositiveInt(width);
-    const requestedHeight = toPositiveInt(height);
-    const hasSizesAttr = typeof sizes === 'string' && sizes.trim().length > 0;
-    const hasSizingHint = hasSizesAttr || requestedWidth !== undefined || requestedHeight !== undefined;
-    const canOptimizeSource = !unoptimized && isOptimizableFimoUrl(src, hostSuffixes);
-    const shouldOptimize = canOptimizeSource && hasSizingHint;
-    const { generatedSrcSet, transformWidth, transformDpr } = computeImageOptimizationConfig({
-        shouldOptimize,
-        hasSizesAttr,
-        srcSetOverride,
-        originalSrc: src,
-        mediaWidth: undefined,
-        renderWidth: requestedWidth,
-        quality: normalizedQuality,
-        fit: normalizedFit,
+    const image = resolveImagePresentation({
+        src,
+        alt,
+        quality,
+        fit,
+        unoptimized,
+        width,
+        height,
+        sizes,
+        srcSet: srcSetOverride,
         hostSuffixes,
     });
-    const finalSrcSet = srcSetOverride ?? generatedSrcSet;
-    const optimizedSrc = shouldOptimize
-        ? buildOptimizedUrl(src, {
-            width: transformWidth,
-            quality: normalizedQuality,
-            fit: normalizedFit,
-            dpr: transformDpr,
-            hostSuffixes,
-        })
-        : src;
     const finalStyle = style?.objectFit
         ? style
         : {
             ...style,
-            objectFit: toObjectFit(normalizedFit),
+            objectFit: image.objectFit,
         };
-    return (_jsx("img", { src: optimizedSrc, alt: alt, width: requestedWidth, height: requestedHeight, style: finalStyle, sizes: sizes, srcSet: finalSrcSet, ...imgProps }));
+    return (_jsx("img", { src: image.src, alt: image.alt, width: image.width, height: image.height, style: finalStyle, sizes: image.sizes, srcSet: image.srcSet, ...imgProps }));
 }

package/dist/runtime/routing/AppRoutesProvider.js

@@ -7,11 +7,12 @@ import { RefreshContentProvider } from '../content/RefreshContentProvider.js';
 import { AppErrorBoundary, onError } from '../core/AppErrorBoundary.js';
 import { ViteLifecycles } from '../core/ViteLifecycles.js';
 import { ScreenshotProvider } from '../iframe/ScreenshotProvider.js';
-import { getPreviewLocationChange, getPreviewParentOrigin } from '../react-router/preview-location.js';
+import { getSafePreviewNavigationPath, isPreviewRuntimeEnabled } from '../preview/bridge.js';
+import { getPreviewLocationChange, getPreviewParentOrigin } from '../preview/location.js';
 import { OptionalTracking } from '../t/OptionalTracking.js';
 import { AppResetScrollOnNavigate } from './AppResetScrollOnNavigate.js';
 const titleCase = (seg) => seg
-    .replace(/[_\-]+/g, ' ')
+    .replace(/[_-]+/g, ' ')
     .replace(/([a-z])([A-Z])/g, '$1 $2')
     .split(/\s+/)
     .filter(Boolean)
@@ -54,23 +55,31 @@ export function AppRoutesProvider({ appRoutes, children }) {
     const navigate = useNavigate();
     const location = useLocation();
     const displayRoutes = useMemo(() => getDisplayRoutes(appRoutes ?? []), [appRoutes]);
+    // @ts-ignore - import.meta.env is provided by Vite.
+    const previewEnabled = isPreviewRuntimeEnabled(import.meta.env.VITE_PREVIEW_SCRIPT_URL);
     const sendRoutes = useCallback(() => {
-        if (!appRoutes?.length) {
+        if (!previewEnabled || !appRoutes?.length) {
             return;
         }
         window.parent.postMessage({ type: 'nav/routes', payload: { routes: displayRoutes } }, getPreviewParentOrigin() ?? '*');
-    }, [appRoutes, displayRoutes]);
+    }, [appRoutes, displayRoutes, previewEnabled]);
     const sendLocationChange = useCallback(() => {
+        if (!previewEnabled) {
+            return;
+        }
         const locationChange = getPreviewLocationChange(location);
         const parentOrigin = getPreviewParentOrigin();
         window.parent.postMessage({
             type: 'nav/locationChange',
             payload: parentOrigin ? locationChange : { path: locationChange.path },
         }, parentOrigin ?? '*');
-    }, [location.hash, location.pathname, location.search]);
+    }, [location.hash, location.pathname, location.search, previewEnabled]);
     useEffect(sendRoutes, [sendRoutes]);
     useEffect(sendLocationChange, [sendLocationChange]);
     useEffect(() => {
+        if (!previewEnabled) {
+            return;
+        }
         const handleMessage = (event) => {
             const parentOrigin = getPreviewParentOrigin();
             if (event.source !== window.parent || !parentOrigin || event.origin !== parentOrigin) {
@@ -80,8 +89,11 @@ export function AppRoutesProvider({ appRoutes, children }) {
             const payload = event.data?.payload;
             switch (type) {
                 case 'nav/navigate':
-                    if (payload?.to) {
-                        navigate(payload.to);
+                    {
+                        const target = getSafePreviewNavigationPath(payload?.to, window.location.origin);
+                        if (target) {
+                            navigate(target);
+                        }
                     }
                     return;
                 case 'nav/read-routes':
@@ -94,6 +106,6 @@ export function AppRoutesProvider({ appRoutes, children }) {
         return () => {
             window.removeEventListener('message', handleMessage);
         };
-    }, [navigate, sendRoutes, sendLocationChange]);
+    }, [navigate, previewEnabled, sendRoutes, sendLocationChange]);
     return (_jsx(ErrorBoundary, { FallbackComponent: AppErrorBoundary, onError: onError, children: _jsx(DataSourcesProvider, { children: _jsx(ScreenshotProvider, { children: _jsx(ViteLifecycles, { children: _jsxs(RefreshContentProvider, { children: [_jsx(OptionalTracking, { routes: displayRoutes }), _jsx(AppResetScrollOnNavigate, {}), appRoutes?.length ? routing : children] }) }) }) }) }));
 }

package/dist/runtime/shared/env-identity.d.ts

@@ -0,0 +1,43 @@
+/**
+ * How a local checkout names and addresses a Fimo env — runtime-safe copy.
+ *
+ * TRAP: this looks like a duplicate of `@fimo/api-contracts` and it is, on
+ * purpose. `dist/runtime/` and `dist/build/` ship UNBUNDLED inside the `fimo`
+ * npm package and can only import published dependencies; `@fimo/api-contracts`
+ * is a private workspace package, so a runtime import of it breaks every user
+ * project (`ERR_MODULE_NOT_FOUND` from `vite.config.ts`). The CLI binary is
+ * bundled and may import contracts freely — the runtime may not.
+ *
+ * The two copies must agree byte-for-byte or a checkout computes a different
+ * tenant host than the API hands out. `env-identity.test.ts` pins them
+ * together against a corpus; change one, and that test tells you to change the
+ * other.
+ */
+export declare const DEFAULT_ENV = "main";
+export declare const PROD_ENV_PREFIX = "release/";
+/** Mirror of `isValidEnv` in `@fimo/api-contracts`. */
+export declare function isValidEnv(env: string): boolean;
+/** Mirror of `envResourceKey` in `@fimo/api-contracts`. */
+export declare function envResourceKey(env: string): string;
+/** Mirror of `buildTenantApiUrl` in `@fimo/api-contracts`. */
+export declare function buildTenantApiUrl(projectId: string, env: string, tenantApiBaseUrl: string): string;
+/**
+ * Content-API aliases a local checkout exposes — one per framework family
+ * that has a Fimo startup hook (Vite/React Router, Next, Astro, SvelteKit).
+ * Add a key when its framework's hook lands, not before: an alias no runtime
+ * reads is one more line to reason about when a site talks to the wrong env.
+ */
+export declare const LOCAL_CONTENT_API_ENV_KEYS: readonly ['FIMO_CONTENT_API_URL', 'VITE_API_URL', 'NEXT_PUBLIC_FIMO_API_URL', 'PUBLIC_FIMO_API_URL'];
+/** Env selectors a runtime turns into the `X-Fimo-Env` request header. */
+export declare const LOCAL_ENV_SELECTOR_KEYS: readonly ['FIMO_ENV', 'NEXT_PUBLIC_FIMO_ENV'];
+/**
+ * Both halves move together. The tenant URL selects the env for content reads
+ * (each env has its own host); the selectors select it for every service that
+ * reads `X-Fimo-Env`. Setting one without the other points a checkout at two
+ * different envs.
+ */
+export declare function buildLocalRuntimeEnv(options: {
+    readonly tenantApiUrl: string;
+    readonly env: string;
+}): Record<string, string>;
+//# sourceMappingURL=env-identity.d.ts.map

package/dist/runtime/shared/env-identity.js

@@ -0,0 +1,88 @@
+/**
+ * How a local checkout names and addresses a Fimo env — runtime-safe copy.
+ *
+ * TRAP: this looks like a duplicate of `@fimo/api-contracts` and it is, on
+ * purpose. `dist/runtime/` and `dist/build/` ship UNBUNDLED inside the `fimo`
+ * npm package and can only import published dependencies; `@fimo/api-contracts`
+ * is a private workspace package, so a runtime import of it breaks every user
+ * project (`ERR_MODULE_NOT_FOUND` from `vite.config.ts`). The CLI binary is
+ * bundled and may import contracts freely — the runtime may not.
+ *
+ * The two copies must agree byte-for-byte or a checkout computes a different
+ * tenant host than the API hands out. `env-identity.test.ts` pins them
+ * together against a corpus; change one, and that test tells you to change the
+ * other.
+ */
+export const DEFAULT_ENV = 'main';
+export const PROD_ENV_PREFIX = 'release/';
+const ENV_ID_REGEX = /^[a-zA-Z0-9._/-]+$/;
+const MAX_ENV_LENGTH = 255;
+/** Mirror of `isValidEnv` in `@fimo/api-contracts`. */
+export function isValidEnv(env) {
+    if (typeof env !== 'string') {
+        return false;
+    }
+    if (env.length === 0 || env.length > MAX_ENV_LENGTH) {
+        return false;
+    }
+    if (env.startsWith('-') || env.startsWith('.')) {
+        return false;
+    }
+    if (env.includes('//') || env.includes('--')) {
+        return false;
+    }
+    if (env.split('/').some((segment) => segment === '..')) {
+        return false;
+    }
+    return ENV_ID_REGEX.test(env);
+}
+function fnv1a8(s) {
+    let h = 0x811c9dc5;
+    for (let i = 0; i < s.length; i++) {
+        h ^= s.charCodeAt(i);
+        h = Math.imul(h, 0x01000193);
+    }
+    return (h >>> 0).toString(16).padStart(8, '0');
+}
+/** Mirror of `envResourceKey` in `@fimo/api-contracts`. */
+export function envResourceKey(env) {
+    const base = env
+        .toLowerCase()
+        .replace(/[^a-z0-9]+/g, '-')
+        .replace(/^-+|-+$/g, '')
+        .slice(0, 15);
+    const hash = fnv1a8(env);
+    return base ? `${base}-${hash}` : hash;
+}
+/** Mirror of `buildTenantApiUrl` in `@fimo/api-contracts`. */
+export function buildTenantApiUrl(projectId, env, tenantApiBaseUrl) {
+    const url = new URL(tenantApiBaseUrl);
+    url.hostname = `${projectId}-${envResourceKey(env)}.${url.hostname}`;
+    return url.toString().replace(/\/$/, '');
+}
+/**
+ * Content-API aliases a local checkout exposes — one per framework family
+ * that has a Fimo startup hook (Vite/React Router, Next, Astro, SvelteKit).
+ * Add a key when its framework's hook lands, not before: an alias no runtime
+ * reads is one more line to reason about when a site talks to the wrong env.
+ */
+export const LOCAL_CONTENT_API_ENV_KEYS = [
+    'FIMO_CONTENT_API_URL',
+    'VITE_API_URL',
+    'NEXT_PUBLIC_FIMO_API_URL',
+    'PUBLIC_FIMO_API_URL',
+];
+/** Env selectors a runtime turns into the `X-Fimo-Env` request header. */
+export const LOCAL_ENV_SELECTOR_KEYS = ['FIMO_ENV', 'NEXT_PUBLIC_FIMO_ENV'];
+/**
+ * Both halves move together. The tenant URL selects the env for content reads
+ * (each env has its own host); the selectors select it for every service that
+ * reads `X-Fimo-Env`. Setting one without the other points a checkout at two
+ * different envs.
+ */
+export function buildLocalRuntimeEnv(options) {
+    return {
+        ...Object.fromEntries(LOCAL_CONTENT_API_ENV_KEYS.map((key) => [key, options.tenantApiUrl])),
+        ...Object.fromEntries(LOCAL_ENV_SELECTOR_KEYS.map((key) => [key, options.env])),
+    };
+}

package/dist/runtime/shared/local-runtime-env.d.ts

@@ -0,0 +1,65 @@
+/**
+ * Which Fimo env a local checkout is on, and how to reach it — derived, not
+ * stored.
+ *
+ * The env is the git branch. The project id and tenant API base URL sit in
+ * `.fimo/project.json`, written once at link and never on a switch. The tenant
+ * URL for the current env is a pure function of the three, so nothing has to
+ * be rewritten when the branch changes: `git checkout` alone is a complete env
+ * switch, offline.
+ *
+ * This module only DERIVES. Precedence against explicit values is the caller's
+ * job and is the same everywhere: a variable the user (or the sandbox) already
+ * set is left alone; derivation fills the rest, one variable at a time.
+ *
+ * Shared by the CLI, `fimo/vite`, and `fimo/next/config` so the three can
+ * never disagree about which env the app is calling.
+ */
+export type LocalRuntimeEnvSource = 'branch' | 'fallback';
+export interface LocalRuntimeEnv {
+    readonly env: string;
+    readonly tenantApiUrl: string;
+    /** Where `env` came from — surfaced so a wrong guess is diagnosable. */
+    readonly source: LocalRuntimeEnvSource;
+    /** Every alias and selector a framework should see, ready to inject. */
+    readonly values: Readonly<Record<string, string>>;
+    readonly link: LocalProjectLink;
+}
+export interface LocalProjectLink {
+    readonly projectId: string;
+    readonly tenantApiBaseUrl: string;
+}
+/**
+ * Derive the local runtime env, or `null` when this directory is not a linked
+ * Fimo project (or the link predates `tenantApiBaseUrl` — nothing safe to
+ * derive, so nothing is).
+ */
+export declare function resolveLocalRuntimeEnv(options: {
+    readonly cwd: string;
+}): LocalRuntimeEnv | null;
+/**
+ * The one case where "explicit wins" pins the app to the WRONG env: an
+ * explicit tenant URL that Fimo itself minted for this project (old-CLI
+ * `fimo clone` seeded the clone-time env's URL into `.env`) and that disagrees
+ * with the branch. A URL the user typed — `http://localhost:4000` — is never
+ * reported; that is the override the design exists to protect.
+ */
+export declare function findStaleFimoOverride(explicit: Readonly<Record<string, string | undefined>>, derived: LocalRuntimeEnv): {
+    readonly key: string;
+    readonly explicit: string;
+    readonly derived: string;
+} | null;
+/** One message for every surface (dev-server console, `fimo checkout`) so the fix reads the same everywhere. */
+export declare function staleOverrideMessage(stale: {
+    readonly explicit: string;
+    readonly derived: string;
+}): string;
+/** Whether `value` is a tenant URL Fimo minted for `link`'s project — for any env. */
+export declare function isFimoMintedTenantUrl(value: string, link: LocalProjectLink): boolean;
+/**
+ * `.env` then `.env.local` (later wins), the way every supported framework
+ * layers them. For CLI commands, which — unlike Vite and Next — do not load
+ * these files themselves but must see the same explicit values the app will.
+ */
+export declare function readLocalEnvFiles(cwd: string): Record<string, string>;
+//# sourceMappingURL=local-runtime-env.d.ts.map