fimo-next 0.21.0-experimental.1

package/README.md

@@ -0,0 +1,18 @@
+# fimo-next
+
+The Next.js runtime for Fimo projects. Install it alongside `fimo` and
+`fimo-react` at the same version, plus `@tanstack/react-query`:
+
+```bash
+npm install fimo fimo-react fimo-next @tanstack/react-query
+```
+
+Render `FimoProvider` once at the application root: from `fimo-next` in the
+App Router root layout (a Server Component), or from `fimo-next/client` in
+`pages/_app.tsx`. It resolves the connection to the linked Fimo project on the
+server and passes only public connection data to the browser; the application
+never manages Fimo runtime variables.
+
+Server Components, data functions, and route handlers import from `fimo-next`;
+Client Components import from `fimo-next/client`. The Next configuration
+wrapper for hosted preview origins is available from `fimo-next/config`.

package/dist/config.d.ts

@@ -0,0 +1,15 @@
+export interface FimoNextConfigContext {
+    readonly defaultConfig?: object;
+    readonly [key: string]: unknown;
+}
+export type FimoNextConfigFactory<TConfig extends object = object> = (phase: string, context: FimoNextConfigContext) => TConfig | Promise<TConfig>;
+export type FimoNextConfig<TConfig extends object = object> = TConfig | FimoNextConfigFactory<TConfig>;
+/**
+ * Connect `next dev` to Fimo's hosted preview gateway. The platform supplies
+ * the allowed preview origins at runtime, so applications do not need to know
+ * which preview provider Fimo currently uses. Every other phase returns the
+ * application config unchanged: the Fimo connection is resolved by
+ * `FimoProvider` and the server runtime, not by this config wrapper.
+ */
+export declare function withFimo<TConfig extends object>(applicationConfig: FimoNextConfig<TConfig>): FimoNextConfigFactory<TConfig>;
+//# sourceMappingURL=config.d.ts.map

package/dist/config.js

@@ -0,0 +1,33 @@
+const NEXT_DEVELOPMENT_PHASE = 'phase-development-server';
+const PREVIEW_ORIGINS_ENV = 'FIMO_PREVIEW_ALLOWED_ORIGINS';
+function readPreviewOrigins() {
+    return (process.env[PREVIEW_ORIGINS_ENV] ?? '')
+        .split(',')
+        .map((origin) => origin.trim())
+        .filter(Boolean);
+}
+/**
+ * Connect `next dev` to Fimo's hosted preview gateway. The platform supplies
+ * the allowed preview origins at runtime, so applications do not need to know
+ * which preview provider Fimo currently uses. Every other phase returns the
+ * application config unchanged: the Fimo connection is resolved by
+ * `FimoProvider` and the server runtime, not by this config wrapper.
+ */
+export function withFimo(applicationConfig) {
+    return async (phase, context) => {
+        const config = typeof applicationConfig === 'function' ? await applicationConfig(phase, context) : applicationConfig;
+        if (phase !== NEXT_DEVELOPMENT_PHASE) {
+            return config;
+        }
+        const previewOrigins = readPreviewOrigins();
+        if (previewOrigins.length === 0) {
+            return config;
+        }
+        const configuredOrigins = config.allowedDevOrigins;
+        const allowedDevOrigins = [
+            ...(Array.isArray(configuredOrigins) ? configuredOrigins : []),
+            ...previewOrigins,
+        ].filter((origin, index, origins) => origins.indexOf(origin) === index);
+        return { ...config, allowedDevOrigins };
+    };
+}

package/dist/runtime/next/client-runtime.d.ts

@@ -0,0 +1,10 @@
+import type { ContentRuntime } from 'fimo/content';
+import type { FimoConnection } from './connection/contract.js';
+/**
+ * Install the connection the generated client modules read from. Called by
+ * the provider during render, so it is in place before any descendant's
+ * effect starts a query or submits a form.
+ */
+export declare function connectClientRuntime(connection: FimoConnection): void;
+export declare const nextClientContentRuntime: ContentRuntime;
+//# sourceMappingURL=client-runtime.d.ts.map

package/dist/runtime/next/client-runtime.js

@@ -0,0 +1,36 @@
+let activeConnection = null;
+/**
+ * Install the connection the generated client modules read from. Called by
+ * the provider during render, so it is in place before any descendant's
+ * effect starts a query or submits a form.
+ */
+export function connectClientRuntime(connection) {
+    activeConnection = connection;
+}
+function requireConnection() {
+    if (!activeConnection) {
+        throw new Error('Fimo is not connected. Render FimoProvider above the component that reads content, labels, or forms.');
+    }
+    return activeConnection;
+}
+export const nextClientContentRuntime = {
+    apiBase() {
+        return requireConnection().apiUrl;
+    },
+    defaultLocale() {
+        // Provider and call-level locales are application-owned. Omitting a locale
+        // lets the tenant API use the project's configured default.
+        return undefined;
+    },
+    headers(extra) {
+        const headers = { ...extra };
+        const env = requireConnection().env;
+        if (env) {
+            headers['X-Fimo-Env'] = env;
+        }
+        return headers;
+    },
+    fetch(input, init) {
+        return globalThis.fetch(input, init);
+    },
+};

package/dist/runtime/next/client.d.ts

@@ -0,0 +1,20 @@
+import type { CollectionContentClient, ContentClientConfig, SingletonContentClient } from 'fimo-react/content';
+export declare function createContentClient<T extends {
+    id: string;
+}, TInput extends object>(config: ContentClientConfig): CollectionContentClient<T, TInput>;
+export declare function createSingletonClient<T extends {
+    id: string;
+}, TInput extends object>(config: ContentClientConfig): SingletonContentClient<T, TInput>;
+export type { CollectionContentClient, InfiniteListResult, SingletonContentClient } from 'fimo-react/content';
+export type { FormClient, FormSubmissionResult } from 'fimo/forms';
+export declare const formClient: import("fimo/forms").FormClient;
+export { createContentCore, createSingletonCore } from 'fimo/content';
+export type { CollectionContentCore, CollectionPage, CollectionPageInfo, ContentClientConfig, ContentClientHandle, ContentModuleMeta, ContentModuleRef, ContentReadOptions, ContentResult, ContentRuntime, ContentSchema, ContentSchemaField, SingletonContentCore, } from 'fimo/content';
+export { FIMO_PARTS, FIMO_SOURCE, FimoBoolean, FimoDate, FimoMedia, FimoRichText, FimoString, getFimoParts, getFimoSource, hasFimoSource, isFimoDate, isFimoString, } from 'fimo/content';
+export { Boolean, Date, DateTime, Image, Json, RichText, StaticImage, Text, Video } from 'fimo-react/primitives';
+export type { BoolOps, DateOps, Field, Fields, FilterFor, FimoPart, FimoPolymorphicReference, FimoReference, FimoRichTextContent, FimoSource, NullOnlyOps, NumberOps, Populate, Populated, PopulatedResult, Projected, ProjectedWithPopulate, Query, ReferenceField, ReferenceMap, ScalarOps, Sort, SortField, StringOps, Where, WithReferences, } from 'fimo/content';
+export type { FimoRichTextComponents, FimoRichTextMarkProps, FimoRichTextNodeProps } from 'fimo-react/primitives';
+export { FimoProvider, useLabels } from './provider.js';
+export type { FimoProviderProps } from './provider.js';
+export type { Labels, LabelsSnapshot } from 'fimo/labels';
+//# sourceMappingURL=client.d.ts.map

package/dist/runtime/next/client.js

@@ -0,0 +1,16 @@
+'use client';
+import { createReactContentClient, createReactSingletonClient } from 'fimo-react/content';
+import { createFormClient } from 'fimo/forms';
+import { nextClientContentRuntime } from './client-runtime.js';
+import { useNextContentLocale } from './provider.js';
+export function createContentClient(config) {
+    return createReactContentClient(config, nextClientContentRuntime, useNextContentLocale);
+}
+export function createSingletonClient(config) {
+    return createReactSingletonClient(config, nextClientContentRuntime, useNextContentLocale);
+}
+export const formClient = createFormClient(nextClientContentRuntime);
+export { createContentCore, createSingletonCore } from 'fimo/content';
+export { FIMO_PARTS, FIMO_SOURCE, FimoBoolean, FimoDate, FimoMedia, FimoRichText, FimoString, getFimoParts, getFimoSource, hasFimoSource, isFimoDate, isFimoString, } from 'fimo/content';
+export { Boolean, Date, DateTime, Image, Json, RichText, StaticImage, Text, Video } from 'fimo-react/primitives';
+export { FimoProvider, useLabels } from './provider.js';

package/dist/runtime/next/connection/browser.d.ts

@@ -0,0 +1,9 @@
+import { type ConnectionResolver } from './contract.js';
+/**
+ * The browser never discovers a connection; it reads the one the server
+ * rendered into the document. Remembered after the first read so a provider
+ * that remounts during client-side navigation does not depend on the script
+ * still being in the DOM.
+ */
+export declare const resolveConnection: ConnectionResolver;
+//# sourceMappingURL=browser.d.ts.map

package/dist/runtime/next/connection/browser.js

@@ -0,0 +1,21 @@
+import { FIMO_CONNECTION_SCRIPT_ID, parseConnection, } from './contract.js';
+let cached = null;
+/**
+ * The browser never discovers a connection; it reads the one the server
+ * rendered into the document. Remembered after the first read so a provider
+ * that remounts during client-side navigation does not depend on the script
+ * still being in the DOM.
+ */
+export const resolveConnection = () => {
+    if (cached) {
+        return cached;
+    }
+    const text = document.getElementById(FIMO_CONNECTION_SCRIPT_ID)?.textContent;
+    const connection = text ? parseConnection(text) : null;
+    if (!connection) {
+        throw new Error('Fimo is not connected in the browser. Render FimoProvider once at the application root: ' +
+            "from 'fimo-next' in the App Router root layout, or from 'fimo-next/client' in pages/_app.");
+    }
+    cached = connection;
+    return connection;
+};

package/dist/runtime/next/connection/contract.d.ts

@@ -0,0 +1,41 @@
+/**
+ * The connection between a Next application and its Fimo project. Every
+ * field is public: the browser receives the whole object, so nothing
+ * server-only (tokens, the management API URL, project secrets) may ever be
+ * added here.
+ */
+export interface FimoConnection {
+    /** Tenant content API base URL for the active Fimo Branch, no trailing slash. */
+    readonly apiUrl: string;
+    /** Branch name sent as `X-Fimo-Env`; omitted when the URL already pins a Branch. */
+    readonly env?: string;
+    /** Locale reads fall back to when neither the call nor the provider names one. */
+    readonly defaultLocale?: string;
+    /** Studio preview script; present only inside a Fimo-hosted preview. */
+    readonly previewScriptUrl?: string;
+}
+/**
+ * Implemented once per runtime (`node`, `edge`, `browser`) and selected
+ * through the `#connection` import map in `package.json`. The node and edge
+ * resolvers discover the connection; the browser resolver reads the one the
+ * server rendered.
+ */
+export type ConnectionResolver = () => FimoConnection;
+export declare const FIMO_CONNECTION_SCRIPT_ID = "fimo-connection";
+type ExplicitEnv = Readonly<Record<string, string | undefined>>;
+/** Public connection fields other than the URL, from explicit env only. */
+export declare function explicitConnectionOptions(env: ExplicitEnv): Omit<FimoConnection, 'apiUrl'>;
+/** The explicitly configured content API URL, or `undefined` to derive one. */
+export declare function explicitContentApiUrl(env: ExplicitEnv): string | undefined;
+/** `apiUrl` first, then the optional fields in a fixed order, without `undefined` holes. */
+export declare function normalizeConnection(connection: FimoConnection): FimoConnection;
+/**
+ * Canonical JSON for an inline `<script type="application/json">`. The server
+ * and the hydrating browser must produce the same text, so the output depends
+ * only on the field values. `<` is escaped so a value can never close the tag.
+ */
+export declare function serializeConnection(connection: FimoConnection): string;
+export declare function parseConnection(text: string): FimoConnection | null;
+export declare const NOT_CONNECTED_MESSAGE: string;
+export {};
+//# sourceMappingURL=contract.d.ts.map

package/dist/runtime/next/connection/contract.js

@@ -0,0 +1,72 @@
+export const FIMO_CONNECTION_SCRIPT_ID = 'fimo-connection';
+/**
+ * Explicit platform or custom-host values, read the same way on every server
+ * runtime. Hosted sandboxes and builds inject the first alias of each pair;
+ * the `NEXT_PUBLIC_*` aliases stay honored so a value a project set under the
+ * former browser name keeps winning over derivation.
+ */
+const EXPLICIT_KEYS = {
+    apiUrl: ['FIMO_CONTENT_API_URL', 'NEXT_PUBLIC_FIMO_API_URL'],
+    env: ['FIMO_ENV', 'NEXT_PUBLIC_FIMO_ENV'],
+    defaultLocale: ['FIMO_DEFAULT_LOCALE', 'NEXT_PUBLIC_FIMO_DEFAULT_LOCALE'],
+    previewScriptUrl: ['FIMO_PREVIEW_SCRIPT_URL', 'NEXT_PUBLIC_FIMO_PREVIEW_SCRIPT_URL'],
+};
+function firstValue(env, keys) {
+    for (const key of keys) {
+        const value = env[key]?.trim();
+        if (value) {
+            return value;
+        }
+    }
+    return undefined;
+}
+/** Public connection fields other than the URL, from explicit env only. */
+export function explicitConnectionOptions(env) {
+    return {
+        env: firstValue(env, EXPLICIT_KEYS.env),
+        defaultLocale: firstValue(env, EXPLICIT_KEYS.defaultLocale),
+        previewScriptUrl: firstValue(env, EXPLICIT_KEYS.previewScriptUrl),
+    };
+}
+/** The explicitly configured content API URL, or `undefined` to derive one. */
+export function explicitContentApiUrl(env) {
+    return firstValue(env, EXPLICIT_KEYS.apiUrl)?.replace(/\/$/, '');
+}
+/** `apiUrl` first, then the optional fields in a fixed order, without `undefined` holes. */
+export function normalizeConnection(connection) {
+    const normalized = { apiUrl: connection.apiUrl };
+    for (const key of ['env', 'defaultLocale', 'previewScriptUrl']) {
+        if (connection[key]) {
+            normalized[key] = connection[key];
+        }
+    }
+    return normalized;
+}
+/**
+ * Canonical JSON for an inline `<script type="application/json">`. The server
+ * and the hydrating browser must produce the same text, so the output depends
+ * only on the field values. `<` is escaped so a value can never close the tag.
+ */
+export function serializeConnection(connection) {
+    return JSON.stringify(normalizeConnection(connection)).replace(/</g, '\\u003c');
+}
+export function parseConnection(text) {
+    try {
+        const parsed = JSON.parse(text);
+        if (!parsed || typeof parsed !== 'object' || typeof parsed.apiUrl !== 'string') {
+            return null;
+        }
+        const { apiUrl, env, defaultLocale, previewScriptUrl } = parsed;
+        return normalizeConnection({
+            apiUrl: apiUrl,
+            env: typeof env === 'string' ? env : undefined,
+            defaultLocale: typeof defaultLocale === 'string' ? defaultLocale : undefined,
+            previewScriptUrl: typeof previewScriptUrl === 'string' ? previewScriptUrl : undefined,
+        });
+    }
+    catch {
+        return null;
+    }
+}
+export const NOT_CONNECTED_MESSAGE = 'This Next.js application is not connected to a Fimo project. ' +
+    'Run `fimo link` in the project directory, or set FIMO_CONTENT_API_URL to the tenant content API URL.';

package/dist/runtime/next/connection/edge.d.ts

@@ -0,0 +1,7 @@
+import { type ConnectionResolver } from './contract.js';
+/**
+ * Edge runtimes have no file system or git, so only the explicit platform env
+ * can connect them. Hosted builds always set it.
+ */
+export declare const resolveConnection: ConnectionResolver;
+//# sourceMappingURL=edge.d.ts.map

package/dist/runtime/next/connection/edge.js

@@ -0,0 +1,14 @@
+import { explicitConnectionOptions, explicitContentApiUrl, normalizeConnection, } from './contract.js';
+const EDGE_NOT_CONNECTED_MESSAGE = 'This Next.js Edge runtime is not connected to Fimo. ' +
+    'Configure FIMO_CONTENT_API_URL in the deployment environment; Edge runtimes cannot read a local Fimo link.';
+/**
+ * Edge runtimes have no file system or git, so only the explicit platform env
+ * can connect them. Hosted builds always set it.
+ */
+export const resolveConnection = () => {
+    const apiUrl = explicitContentApiUrl(process.env);
+    if (!apiUrl) {
+        throw new Error(EDGE_NOT_CONNECTED_MESSAGE);
+    }
+    return normalizeConnection({ apiUrl, ...explicitConnectionOptions(process.env) });
+};

package/dist/runtime/next/connection/node.d.ts

@@ -0,0 +1,7 @@
+import { type ConnectionResolver } from './contract.js';
+/**
+ * Server-side connection discovery: explicit platform/custom-host env first,
+ * then the linked project and its active git branch. Memoized per process.
+ */
+export declare const resolveConnection: ConnectionResolver;
+//# sourceMappingURL=node.d.ts.map

package/dist/runtime/next/connection/node.js

@@ -0,0 +1,54 @@
+import { findStaleFimoOverride, resolveLocalRuntimeEnv, staleOverrideMessage } from 'fimo/config';
+import { explicitConnectionOptions, explicitContentApiUrl, NOT_CONNECTED_MESSAGE, normalizeConnection, } from './contract.js';
+let cache = null;
+let warnedStaleOverride = false;
+function cacheKey() {
+    // Explicit env and cwd are the inputs; the git branch is not, on purpose —
+    // a checkout is a restart-level switch, the same way a dev server reads its
+    // env once at startup.
+    return JSON.stringify([
+        process.cwd(),
+        process.env.FIMO_CONTENT_API_URL,
+        process.env.NEXT_PUBLIC_FIMO_API_URL,
+        process.env.FIMO_ENV,
+        process.env.NEXT_PUBLIC_FIMO_ENV,
+        process.env.FIMO_DEFAULT_LOCALE,
+        process.env.NEXT_PUBLIC_FIMO_DEFAULT_LOCALE,
+        process.env.FIMO_PREVIEW_SCRIPT_URL,
+        process.env.NEXT_PUBLIC_FIMO_PREVIEW_SCRIPT_URL,
+    ]);
+}
+function discover() {
+    const explicit = explicitContentApiUrl(process.env);
+    const options = explicitConnectionOptions(process.env);
+    if (explicit) {
+        // The one override that silently points a checkout at the wrong Branch:
+        // a Fimo-minted URL from an older CLI's env file. A user-typed URL
+        // (`http://localhost:4000`) is the override this precedence exists for.
+        if (!warnedStaleOverride && process.env.NODE_ENV !== 'production') {
+            const derived = resolveLocalRuntimeEnv({ cwd: process.cwd() });
+            const stale = derived && findStaleFimoOverride({ FIMO_CONTENT_API_URL: explicit }, derived);
+            if (stale) {
+                warnedStaleOverride = true;
+                console.warn(staleOverrideMessage(stale));
+            }
+        }
+        return normalizeConnection({ apiUrl: explicit, ...options });
+    }
+    const derived = resolveLocalRuntimeEnv({ cwd: process.cwd() });
+    if (derived) {
+        return normalizeConnection({ apiUrl: derived.tenantApiUrl, ...options, env: derived.env });
+    }
+    throw new Error(NOT_CONNECTED_MESSAGE);
+}
+/**
+ * Server-side connection discovery: explicit platform/custom-host env first,
+ * then the linked project and its active git branch. Memoized per process.
+ */
+export const resolveConnection = () => {
+    const key = cacheKey();
+    if (cache?.key !== key) {
+        cache = { key, connection: discover() };
+    }
+    return cache.connection;
+};

package/dist/runtime/next/facade.d.ts

@@ -0,0 +1,8 @@
+import type { ContentClientHandle } from 'fimo/content';
+export type NextContentRegistry = Readonly<Record<string, ContentClientHandle>>;
+export interface CreateFimoOptions<TContent extends NextContentRegistry> {
+    content: TContent;
+    locale?: string;
+}
+export declare function createFimo<const TContent extends NextContentRegistry>({ content, locale, }: CreateFimoOptions<TContent>): TContent;
+//# sourceMappingURL=facade.d.ts.map

package/dist/runtime/next/facade.js

@@ -0,0 +1,34 @@
+function withLocale(options, locale) {
+    return { ...options, locale: options?.locale ?? locale };
+}
+function isCollectionClient(client) {
+    return 'list' in client && typeof client.list === 'function';
+}
+function isSingletonClient(client) {
+    return 'get' in client && typeof client.get === 'function';
+}
+function bindLocale(client, locale) {
+    if (isCollectionClient(client)) {
+        return {
+            ...client,
+            getById: (id, options) => client.getById(id, withLocale(options, locale)),
+            getBySlug: (slug, options) => client.getBySlug(slug, withLocale(options, locale)),
+            getByField: (fieldName, value, options) => client.getByField(fieldName, value, withLocale(options, locale)),
+            list: (params) => client.list(withLocale(params, locale)),
+            get: (params) => client.get(withLocale(params, locale)),
+        };
+    }
+    if (isSingletonClient(client)) {
+        return {
+            ...client,
+            get: (options) => client.get(withLocale(options, locale)),
+        };
+    }
+    return client;
+}
+export function createFimo({ content, locale, }) {
+    if (locale === undefined) {
+        return content;
+    }
+    return Object.fromEntries(Object.entries(content).map(([key, client]) => [key, bindLocale(client, locale)]));
+}

package/dist/runtime/next/labels.d.ts

@@ -0,0 +1,7 @@
+import { type GetLabelsOptions } from 'fimo/labels';
+/**
+ * Read the labels for an application-resolved locale. When omitted, the request
+ * carries no locale and the Fimo API answers with the project default locale.
+ */
+export declare function getLabels(options?: GetLabelsOptions): Promise<import("fimo/labels").Labels>;
+//# sourceMappingURL=labels.d.ts.map

package/dist/runtime/next/labels.js

@@ -0,0 +1,9 @@
+import { fetchLabels } from 'fimo/labels';
+import { nextServerContentRuntime } from './server-runtime.js';
+/**
+ * Read the labels for an application-resolved locale. When omitted, the request
+ * carries no locale and the Fimo API answers with the project default locale.
+ */
+export function getLabels(options) {
+    return fetchLabels(nextServerContentRuntime, options);
+}

package/dist/runtime/next/preview.d.ts

@@ -0,0 +1,13 @@
+interface NextPreviewBrowser {
+    readonly window: Pick<Window, 'addEventListener' | 'location' | 'parent' | 'removeEventListener' | 'sessionStorage'>;
+    readonly document: Pick<Document, 'referrer'>;
+}
+type NextPreviewConnection = {
+    readonly locale: string;
+    readonly navigate: (to: string) => unknown;
+    readonly pathname: string;
+    readonly previewScriptUrl: string | undefined;
+};
+export declare function connectNextPreview({ locale, navigate, pathname, previewScriptUrl }: NextPreviewConnection, browser?: NextPreviewBrowser): () => void;
+export {};
+//# sourceMappingURL=preview.d.ts.map

package/dist/runtime/next/preview.js

@@ -0,0 +1,33 @@
+import { getPreviewLocationChange, getPreviewParentOrigin, getSafePreviewNavigationPath, isPreviewRuntimeEnabled, } from 'fimo/preview';
+export function connectNextPreview({ locale, navigate, pathname, previewScriptUrl }, browser = { window, document }) {
+    if (!isPreviewRuntimeEnabled(previewScriptUrl)) {
+        return () => undefined;
+    }
+    const parentOrigin = getPreviewParentOrigin(browser);
+    const sendLocationChange = () => {
+        browser.window.parent.postMessage({
+            type: 'nav/locationChange',
+            payload: getPreviewLocationChange({ pathname, search: browser.window.location.search, hash: browser.window.location.hash }, locale, parentOrigin),
+        }, parentOrigin ?? '*');
+    };
+    const handleMessage = (event) => {
+        if (event.source !== browser.window.parent || !parentOrigin || event.origin !== parentOrigin) {
+            return;
+        }
+        if (event.data?.type === 'nav/navigate') {
+            const target = getSafePreviewNavigationPath(event.data?.payload?.to, browser.window.location.origin);
+            if (target) {
+                navigate(target);
+            }
+            return;
+        }
+        if (event.data?.type === 'nav/read-routes') {
+            sendLocationChange();
+        }
+    };
+    browser.window.addEventListener('message', handleMessage);
+    sendLocationChange();
+    return () => {
+        browser.window.removeEventListener('message', handleMessage);
+    };
+}

package/dist/runtime/next/primitives/Text.d.ts

@@ -0,0 +1,10 @@
+import type { TextProps } from 'fimo-react/primitives/server';
+import { type ElementType } from 'react';
+/**
+ * Server-safe text primitive for Next.js Server Components.
+ *
+ * It intentionally shares the same public props as the interactive React
+ * primitive while rendering source metadata without client hooks.
+ */
+export declare function Text<T extends ElementType = 'span'>({ value, as, children, ...props }: TextProps<T>): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=Text.d.ts.map

package/dist/runtime/next/primitives/Text.js

@@ -0,0 +1,18 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { getFimoParts, getFimoSource } from 'fimo/content';
+import { Fragment } from 'react';
+/**
+ * Server-safe text primitive for Next.js Server Components.
+ *
+ * It intentionally shares the same public props as the interactive React
+ * primitive while rendering source metadata without client hooks.
+ */
+export function Text({ value, as, children, ...props }) {
+    const Component = as || 'span';
+    const parts = getFimoParts(value);
+    if (parts && parts.length > 1 && !children) {
+        return (_jsx(Component, { ...props, children: parts.map((part, index) => part.source ? (_jsx("span", { "data-fimo-source": part.source, children: part.text }, index)) : (_jsx(Fragment, { children: part.text }, index))) }));
+    }
+    const text = String(value);
+    return (_jsx(Component, { ...props, "data-fimo-source": getFimoSource(value), children: children ? children(text) : text }));
+}

package/dist/runtime/next/primitives/server.d.ts

@@ -0,0 +1,11 @@
+import type { BooleanProps, DateProps, ImageProps, JsonProps, RichTextProps, VideoProps } from 'fimo-react/primitives/server';
+import { type ElementType } from 'react';
+export declare function Boolean<T extends ElementType = 'span'>({ value, as, children, ...props }: BooleanProps<T>): import("react/jsx-runtime").JSX.Element | null;
+export declare function Date({ value, ...props }: DateProps): import("react/jsx-runtime").JSX.Element | null;
+/** Renders a `datetime` field: the `dateTime` attribute keeps the whole instant. */
+export declare function DateTime({ value, ...props }: DateProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Image(props: ImageProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Json<T extends ElementType = 'span'>({ value, as, children, ...props }: JsonProps<T>): import("react/jsx-runtime").JSX.Element | null;
+export declare function RichText({ value, components, ...props }: RichTextProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function Video(props: VideoProps): import("react/jsx-runtime").JSX.Element | null;
+//# sourceMappingURL=server.d.ts.map

package/dist/runtime/next/primitives/server.js

@@ -0,0 +1,51 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { DateRenderer, ImageRenderer, RichTextRenderer, VideoRenderer } from 'fimo-react/primitives/server';
+import { FIMO_SOURCE, getFimoSource } from 'fimo/content';
+export function Boolean({ value, as, children, ...props }) {
+    if (!value) {
+        return null;
+    }
+    const Component = as || 'span';
+    const booleanValue = value.valueOf();
+    return (_jsx(Component, { ...props, "data-fimo-source": value[FIMO_SOURCE], children: children ? children(booleanValue) : String(booleanValue) }));
+}
+export function Date({ value, ...props }) {
+    if (!value) {
+        return null;
+    }
+    const source = typeof value === 'object' && FIMO_SOURCE in value ? (value[FIMO_SOURCE] ?? undefined) : undefined;
+    return _jsx(DateRenderer, { ...props, value: value, source: source });
+}
+/** Renders a `datetime` field: the `dateTime` attribute keeps the whole instant. */
+export function DateTime({ value, ...props }) {
+    if (!value) {
+        return null;
+    }
+    const source = typeof value === 'object' && FIMO_SOURCE in value ? (value[FIMO_SOURCE] ?? undefined) : undefined;
+    return _jsx(DateRenderer, { ...props, value: value, source: source, precision: "instant" });
+}
+export function Image(props) {
+    if (!props.value) {
+        return null;
+    }
+    return _jsx(ImageRenderer, { ...props });
+}
+export function Json({ value, as, children, ...props }) {
+    if (value === null || value === undefined) {
+        return null;
+    }
+    const Component = as || 'span';
+    return (_jsx(Component, { ...props, "data-fimo-source": getFimoSource(value), children: children ? children(value) : JSON.stringify(value) }));
+}
+export function RichText({ value, components, ...props }) {
+    if (!value) {
+        return null;
+    }
+    return _jsx(RichTextRenderer, { ...props, document: value.content, source: value[FIMO_SOURCE], components: components });
+}
+export function Video(props) {
+    if (!props.value) {
+        return null;
+    }
+    return _jsx(VideoRenderer, { ...props });
+}

package/dist/runtime/next/provider.d.ts

@@ -0,0 +1,32 @@
+import { QueryClient } from '@tanstack/react-query';
+import { type Labels, type LabelsSnapshot } from 'fimo/labels';
+import { type ReactNode } from 'react';
+import { type FimoConnection } from './connection/contract.js';
+export interface FimoProviderProps {
+    children: ReactNode;
+    labels?: LabelsSnapshot;
+    locale?: string;
+    /** Reuse an application-owned React Query client instead of the nearest one in context. */
+    queryClient?: QueryClient;
+}
+/**
+ * The client half of every Fimo Next integration: content-client connection,
+ * React Query, labels, and the Studio preview script. `FimoProvider` from
+ * `fimo-next` (App Router) and from `fimo-next/client` (Pages Router) both
+ * render it with the connection they resolved.
+ */
+export declare function FimoClientProvider({ children, connection, labels, locale, queryClient, }: FimoProviderProps & {
+    connection: FimoConnection;
+}): import("react/jsx-runtime").JSX.Element;
+/**
+ * Pages Router root provider for `pages/_app`. It resolves the connection
+ * while the server renders `_app` and writes it into the document as inline
+ * JSON, which is what the browser bundle reads back: Pages Router has no
+ * server boundary above `_app`, so the render itself is the transport.
+ *
+ * The App Router root layout uses `FimoProvider` from `fimo-next` instead.
+ */
+export declare function FimoProvider({ children, ...props }: FimoProviderProps): import("react/jsx-runtime").JSX.Element;
+export declare function useNextContentLocale(requestedLocale: string | undefined, defaultLocale: string): string;
+export declare function useLabels(): Labels;
+//# sourceMappingURL=provider.d.ts.map

package/dist/runtime/next/provider.js

@@ -0,0 +1,72 @@
+'use client';
+import { Fragment as _Fragment, jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+import { QueryClient, QueryClientContext, QueryClientProvider } from '@tanstack/react-query';
+import { createLabels } from 'fimo/labels';
+import { ensurePreviewScript } from 'fimo/preview';
+import { useRouter as usePagesRouter } from 'next/compat/router.js';
+import { usePathname } from 'next/navigation.js';
+import { createContext, Suspense, useCallback, useContext, useEffect, useMemo, useState } from 'react';
+import { resolveConnection } from '#connection';
+import { connectClientRuntime } from './client-runtime.js';
+import { FIMO_CONNECTION_SCRIPT_ID, serializeConnection } from './connection/contract.js';
+import { connectNextPreview } from './preview.js';
+const FimoNextContext = createContext({});
+/**
+ * The client half of every Fimo Next integration: content-client connection,
+ * React Query, labels, and the Studio preview script. `FimoProvider` from
+ * `fimo-next` (App Router) and from `fimo-next/client` (Pages Router) both
+ * render it with the connection they resolved.
+ */
+export function FimoClientProvider({ children, connection, labels, locale, queryClient, }) {
+    // Render-phase on purpose: descendants' effects, where React Query starts
+    // fetching, run before this component's own effects.
+    connectClientRuntime(connection);
+    const inheritedQueryClient = useContext(QueryClientContext);
+    const [client] = useState(() => queryClient ?? inheritedQueryClient ?? new QueryClient());
+    const activeLocale = locale?.trim() || labels?.locale;
+    const value = useMemo(() => ({ connection, labels, locale: activeLocale }), [activeLocale, connection, labels]);
+    const previewScriptUrl = connection.previewScriptUrl;
+    return (_jsx(FimoNextContext.Provider, { value: value, children: _jsxs(QueryClientProvider, { client: client, children: [previewScriptUrl ? (_jsx(Suspense, { fallback: null, children: _jsx(FimoPreviewRuntime, { previewScriptUrl: previewScriptUrl }) })) : null, children] }) }));
+}
+/**
+ * Pages Router root provider for `pages/_app`. It resolves the connection
+ * while the server renders `_app` and writes it into the document as inline
+ * JSON, which is what the browser bundle reads back: Pages Router has no
+ * server boundary above `_app`, so the render itself is the transport.
+ *
+ * The App Router root layout uses `FimoProvider` from `fimo-next` instead.
+ */
+export function FimoProvider({ children, ...props }) {
+    const [connection] = useState(resolveConnection);
+    return (_jsxs(_Fragment, { children: [_jsx("script", { id: FIMO_CONNECTION_SCRIPT_ID, type: "application/json", dangerouslySetInnerHTML: { __html: serializeConnection(connection) } }), _jsx(FimoClientProvider, { connection: connection, ...props, children: children })] }));
+}
+function FimoPreviewRuntime({ previewScriptUrl }) {
+    const context = useContext(FimoNextContext);
+    const locale = context.locale ?? context.connection?.defaultLocale ?? 'en';
+    const appPathname = usePathname();
+    const pagesRouter = usePagesRouter();
+    const pathname = appPathname ?? pagesRouter?.asPath.split(/[?#]/, 1)[0] ?? '/';
+    const navigate = useCallback((to) => {
+        if (pagesRouter) {
+            return pagesRouter.push(to);
+        }
+        window.history.pushState(null, '', to);
+    }, [pagesRouter]);
+    useEffect(() => {
+        ensurePreviewScript(previewScriptUrl);
+        return connectNextPreview({ locale, navigate, pathname, previewScriptUrl });
+    }, [locale, navigate, pathname, previewScriptUrl]);
+    return null;
+}
+export function useNextContentLocale(requestedLocale, defaultLocale) {
+    const context = useContext(FimoNextContext);
+    return requestedLocale ?? context.locale ?? defaultLocale;
+}
+export function useLabels() {
+    const context = useContext(FimoNextContext);
+    const locale = context.locale ?? context.connection?.defaultLocale ?? 'en';
+    const snapshot = context.labels?.locale === locale
+        ? context.labels
+        : { locale, labels: {}, updatedAt: null };
+    return useMemo(() => createLabels(snapshot), [snapshot]);
+}

package/dist/runtime/next/server-provider.d.ts

@@ -0,0 +1,17 @@
+import type { LabelsSnapshot } from 'fimo/labels';
+import type { ReactNode } from 'react';
+export interface FimoProviderProps {
+    children: ReactNode;
+    /** Label snapshot from `getLabels()`; it also supplies the locale for client hooks. */
+    labels?: LabelsSnapshot;
+    /** Application-resolved locale for client hooks when no label snapshot is passed. */
+    locale?: string;
+}
+/**
+ * App Router root integration: a Server Component that resolves the Fimo
+ * connection on the server (explicit env, else the linked project and active
+ * git branch) and hands only that public data to the client provider. Render
+ * it once in the root layout; no page or component receives a runtime prop.
+ */
+export declare function FimoProvider({ children, labels, locale }: FimoProviderProps): import("react/jsx-runtime").JSX.Element;
+//# sourceMappingURL=server-provider.d.ts.map

package/dist/runtime/next/server-provider.js

@@ -0,0 +1,12 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { resolveConnection } from '#connection';
+import { FimoClientProvider } from './provider.js';
+/**
+ * App Router root integration: a Server Component that resolves the Fimo
+ * connection on the server (explicit env, else the linked project and active
+ * git branch) and hands only that public data to the client provider. Render
+ * it once in the root layout; no page or component receives a runtime prop.
+ */
+export function FimoProvider({ children, labels, locale }) {
+    return (_jsx(FimoClientProvider, { connection: resolveConnection(), labels: labels, locale: locale, children: children }));
+}

package/dist/runtime/next/server-runtime.d.ts

@@ -0,0 +1,3 @@
+import type { ContentRuntime } from 'fimo/content';
+export declare const nextServerContentRuntime: ContentRuntime;
+//# sourceMappingURL=server-runtime.d.ts.map

package/dist/runtime/next/server-runtime.js

@@ -0,0 +1,23 @@
+import { resolveConnection } from '#connection';
+export const nextServerContentRuntime = {
+    apiBase() {
+        return resolveConnection().apiUrl;
+    },
+    defaultLocale() {
+        // `undefined` leaves `locale` off the request so the tenant API answers with
+        // the project default declared in `.fimo/config.json#i18n.defaultLocale`.
+        // Route-resolved locales reach Fimo through `createFimo`/`getLabels`.
+        return undefined;
+    },
+    headers(extra) {
+        const headers = { ...extra };
+        const env = resolveConnection().env;
+        if (env) {
+            headers['X-Fimo-Env'] = env;
+        }
+        return headers;
+    },
+    fetch(input, init) {
+        return globalThis.fetch(input, init);
+    },
+};

package/dist/runtime/next/server.d.ts

@@ -0,0 +1,23 @@
+import { StaticImage } from 'fimo-react/primitives/server';
+import type { CollectionContentCore, ContentClientConfig, SingletonContentCore } from 'fimo/content';
+export { StaticImage };
+export { Text } from './primitives/Text.js';
+export { Boolean, Date, DateTime, Image, Json, RichText, Video } from './primitives/server.js';
+export { createFimo } from './facade.js';
+export type { CreateFimoOptions, NextContentRegistry } from './facade.js';
+export { FimoProvider } from './server-provider.js';
+export type { FimoProviderProps } from './server-provider.js';
+export { getLabels } from './labels.js';
+export type { FormClient, FormSubmissionResult } from 'fimo/forms';
+export type { GetLabelsOptions, Labels, LabelsSnapshot } from 'fimo/labels';
+export type { FimoRichTextComponents, FimoRichTextMarkProps, FimoRichTextNodeProps, } from 'fimo-react/primitives/server';
+export declare function createContentClient<T extends {
+    id: string;
+}, TInput extends object>(config: ContentClientConfig): CollectionContentCore<T, TInput>;
+export declare function createSingletonClient<T extends {
+    id: string;
+}, TInput extends object>(config: ContentClientConfig): SingletonContentCore<T, TInput>;
+export declare const formClient: import("fimo/forms").FormClient;
+export type { CollectionContentCore as CollectionContentClient, SingletonContentCore as SingletonContentClient, } from 'fimo/content';
+export * from 'fimo/content';
+//# sourceMappingURL=server.d.ts.map

package/dist/runtime/next/server.js

@@ -0,0 +1,18 @@
+import { StaticImage } from 'fimo-react/primitives/server';
+import { createServerContentClient, createServerSingletonClient } from 'fimo/content';
+import { createFormClient } from 'fimo/forms';
+import { nextServerContentRuntime } from './server-runtime.js';
+export { StaticImage };
+export { Text } from './primitives/Text.js';
+export { Boolean, Date, DateTime, Image, Json, RichText, Video } from './primitives/server.js';
+export { createFimo } from './facade.js';
+export { FimoProvider } from './server-provider.js';
+export { getLabels } from './labels.js';
+export function createContentClient(config) {
+    return createServerContentClient(config, nextServerContentRuntime);
+}
+export function createSingletonClient(config) {
+    return createServerSingletonClient(config, nextServerContentRuntime);
+}
+export const formClient = createFormClient(nextServerContentRuntime);
+export * from 'fimo/content';

package/package.json

@@ -0,0 +1,73 @@
+{
+  "name": "fimo-next",
+  "version": "0.21.0-experimental.1",
+  "description": "Fimo runtime for Next.js projects.",
+  "files": [
+    "dist/",
+    "!dist/**/*.d.ts.map",
+    "README.md"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "imports": {
+    "#connection": {
+      "edge-light": "./dist/runtime/next/connection/edge.js",
+      "worker": "./dist/runtime/next/connection/edge.js",
+      "workerd": "./dist/runtime/next/connection/edge.js",
+      "browser": "./dist/runtime/next/connection/browser.js",
+      "default": "./dist/runtime/next/connection/node.js"
+    }
+  },
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/runtime/next/server.d.ts",
+      "import": "./dist/runtime/next/server.js"
+    },
+    "./client": {
+      "types": "./dist/runtime/next/client.d.ts",
+      "import": "./dist/runtime/next/client.js"
+    },
+    "./config": {
+      "types": "./dist/config.d.ts",
+      "import": "./dist/config.js",
+      "require": "./dist/config.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "tsc -b tsconfig.json",
+    "check:types": "tsc -b tsconfig.json --noEmit",
+    "clean": "rm -rf dist tsconfig.tsbuildinfo",
+    "test": "vitest run",
+    "test:watch": "vitest"
+  },
+  "dependencies": {
+    "fimo-react": "0.21.0-experimental.1"
+  },
+  "devDependencies": {
+    "@fimo/tsconfig": "0.21.0-experimental.1",
+    "@tanstack/react-query": "^5.80.6",
+    "@types/node": "^22.15.29",
+    "@types/react": "^19.2.14",
+    "@types/react-dom": "^19.2.3",
+    "fimo": "0.21.0-experimental.1",
+    "next": "16.3.0",
+    "react": "^19.2.4",
+    "react-dom": "^19.2.4",
+    "typescript": "7.0.2",
+    "vitest": "^4.1.6"
+  },
+  "peerDependencies": {
+    "@tanstack/react-query": "^5.80.6",
+    "fimo": ">=0.14.0",
+    "next": "^15.0.0 || ^16.0.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "react-dom": "^18.2.0 || ^19.0.0"
+  },
+  "engines": {
+    "node": ">=20.12.0"
+  }
+}