fimo 0.17.0 → 0.19.0

package/dist/runtime/routes/index.js

@@ -0,0 +1,335 @@
+// ../../packages/routes/src/index.ts
+function normalizeFimoLocale(locale) {
+  const trimmed = locale?.trim();
+  if (!trimmed) {
+    return null;
+  }
+  const candidate = trimmed.replace(/_/g, "-");
+  try {
+    return Intl.getCanonicalLocales(candidate)[0] ?? null;
+  } catch {
+    return null;
+  }
+}
+function getFimoDefaultLocale(config) {
+  return normalizeFimoLocale(config?.i18n?.defaultLocale) ?? "en";
+}
+function getFimoLocales(config) {
+  const defaultLocale = getFimoDefaultLocale(config);
+  const locales = /* @__PURE__ */ new Set([defaultLocale]);
+  for (const locale of config?.i18n?.locales ?? []) {
+    const clean = normalizeFimoLocale(locale);
+    if (clean) {
+      locales.add(clean);
+    }
+  }
+  return [...locales];
+}
+var FIMO_LOCALE_PARAM = "locale";
+function normalizeRoutePath(path) {
+  const withSlash = path.startsWith("/") ? path : `/${path}`;
+  const collapsed = withSlash.replace(/\/{2,}/g, "/");
+  return collapsed.length > 1 ? collapsed.replace(/\/+$/, "") : collapsed;
+}
+function splitSegments(path) {
+  return path.split("/").filter(Boolean);
+}
+function isPlaceholder(segment) {
+  return segment.startsWith(":") && segment.length > 1;
+}
+function readPlaceholder(segment) {
+  if (!isPlaceholder(segment)) {
+    return null;
+  }
+  return {
+    name: segment.slice(1).replace(/[?*]$/, ""),
+    catchAll: segment.endsWith("*")
+  };
+}
+function hasLocaleSegment(path) {
+  return splitSegments(normalizeRoutePath(path)).some(
+    (segment) => segment === `:${FIMO_LOCALE_PARAM}` || segment === `:${FIMO_LOCALE_PARAM}?`
+  );
+}
+function resolveParamType(name, descriptor) {
+  if (descriptor?.type) {
+    return descriptor.type;
+  }
+  return name === FIMO_LOCALE_PARAM ? "locale" : "entry";
+}
+function buildLocaleParam(name, descriptor, index, issues) {
+  if (name !== FIMO_LOCALE_PARAM) {
+    issues.push({
+      param: name,
+      message: `Param "${name}" declares \`"type": "locale"\` but "${FIMO_LOCALE_PARAM}" is the only locale parameter name.`,
+      fix: `Rename the path segment and the descriptor to ":${FIMO_LOCALE_PARAM}", or use \`"type": "entry"\`.`
+    });
+    return null;
+  }
+  if (index !== 0) {
+    issues.push({
+      param: name,
+      message: `The ":${FIMO_LOCALE_PARAM}" segment must be the first segment of the path.`,
+      fix: `Move it to the front, for example "/:${FIMO_LOCALE_PARAM}/blog/:slug".`
+    });
+    return null;
+  }
+  for (const field of ["schema", "queryField", "displayField", "query"]) {
+    if (descriptor?.[field] !== void 0) {
+      issues.push({
+        param: name,
+        message: `Locale param "${name}" must not declare "${field}" \u2014 the locale is read from the URL, never from the CMS.`,
+        fix: `Remove "${field}" from \`params.${name}\`.`
+      });
+    }
+  }
+  return { type: "locale", name, optional: descriptor?.optional !== false };
+}
+function buildEntryParam(name, descriptor, issues) {
+  if (name === FIMO_LOCALE_PARAM) {
+    issues.push({
+      param: name,
+      message: `Param "${name}" is reserved for the locale segment and cannot use \`"type": "entry"\`.`,
+      fix: `Drop \`"type": "entry"\` from \`params.${name}\`, or rename the segment.`
+    });
+    return null;
+  }
+  if (!descriptor) {
+    issues.push({
+      param: name,
+      message: `":${name}" needs \`params\` metadata before its URLs can be generated.`,
+      fix: `Add \`"params": { "${name}": { "schema": "SchemaName", "queryField": "${name}" } }\`.`
+    });
+    return null;
+  }
+  if (descriptor.optional !== void 0) {
+    issues.push({
+      param: name,
+      message: `Entry param "${name}" cannot be optional \u2014 only the locale segment can be omitted from a URL.`,
+      fix: `Remove "optional" from \`params.${name}\`.`
+    });
+  }
+  if (!descriptor.schema || !descriptor.queryField) {
+    issues.push({
+      param: name,
+      message: `Entry param "${name}" is missing ${!descriptor.schema ? '"schema"' : '"queryField"'}.`,
+      fix: `Set \`"${name}": { "schema": "SchemaName", "queryField": "${name}" }\`.`
+    });
+    return null;
+  }
+  return {
+    type: "entry",
+    name,
+    schema: descriptor.schema,
+    queryField: descriptor.queryField,
+    ...descriptor.displayField ? { displayField: descriptor.displayField } : {}
+  };
+}
+function resolveRouteContract(id, route) {
+  const path = normalizeRoutePath(route.path ?? "/");
+  const segments = splitSegments(path);
+  const declared = route.params ?? {};
+  const issues = [];
+  const params = [];
+  const unresolvedParams = [];
+  const seen = /* @__PURE__ */ new Set();
+  segments.forEach((segment, index) => {
+    if (!isPlaceholder(segment)) {
+      return;
+    }
+    const placeholder = readPlaceholder(segment);
+    if (!placeholder) {
+      return;
+    }
+    const { name } = placeholder;
+    if (seen.has(name)) {
+      issues.push({
+        param: name,
+        message: `Placeholder ":${name}" appears more than once.`,
+        fix: "Give each placeholder a distinct name."
+      });
+      unresolvedParams.push(name);
+      return;
+    }
+    seen.add(name);
+    const descriptor = declared[name];
+    const resolved = resolveParamType(name, descriptor) === "locale" ? buildLocaleParam(name, descriptor, index, issues) : buildEntryParam(name, descriptor, issues);
+    if (resolved) {
+      params.push(resolved);
+    } else {
+      unresolvedParams.push(name);
+    }
+  });
+  for (const name of Object.keys(declared)) {
+    if (!seen.has(name)) {
+      issues.push({
+        param: name,
+        message: `Declared param "${name}" has no ":${name}" segment in the path.`,
+        fix: `Add ":${name}" to the path, or remove it from "params".`
+      });
+    }
+  }
+  const localeParam = params.find((param) => param.type === "locale") ?? null;
+  const canonicalPath = localeParam ? normalizeRoutePath(`/${segments.filter((segment) => segment !== `:${FIMO_LOCALE_PARAM}`).join("/")}`) : path;
+  return {
+    id,
+    config: route,
+    path,
+    canonicalPath,
+    params,
+    entryParams: params.filter((param) => param.type === "entry"),
+    localeParam,
+    unresolvedParams,
+    issues
+  };
+}
+function resolveRouteContracts(routes) {
+  return Object.entries(routes ?? {}).map(([id, route]) => resolveRouteContract(id, route));
+}
+function readLocaleVocabulary(config) {
+  return {
+    locales: config.i18n ? getFimoLocales(config) : null,
+    defaultLocale: getFimoDefaultLocale(config)
+  };
+}
+function acceptsLocaleSegment(segment, localeParam, vocabulary) {
+  if (!vocabulary.locales) {
+    return segment.length > 0;
+  }
+  if (!vocabulary.locales.includes(segment)) {
+    return false;
+  }
+  return localeParam.optional ? segment !== vocabulary.defaultLocale : true;
+}
+function matchContract(urlSegments, contract, vocabulary) {
+  const patternSegments = splitSegments(contract.path);
+  const localeParam = contract.localeParam;
+  const catchAllIndex = patternSegments.findIndex((segment) => readPlaceholder(segment)?.catchAll);
+  const hasCatchAll = catchAllIndex !== -1;
+  const hasLocaleLength = hasCatchAll ? urlSegments.length >= patternSegments.length : urlSegments.length === patternSegments.length;
+  const withLocale = localeParam?.optional ? hasLocaleLength && acceptsLocaleSegment(urlSegments[0] ?? "", localeParam, vocabulary) : hasLocaleLength;
+  const withoutLocale = Boolean(localeParam?.optional) && (hasCatchAll ? urlSegments.length >= patternSegments.length - 1 : urlSegments.length === patternSegments.length - 1);
+  if (!localeParam && !withLocale) {
+    return null;
+  }
+  if (localeParam && !withLocale && !withoutLocale) {
+    return null;
+  }
+  const params = {};
+  const entryParams = {};
+  let localeFromPath = null;
+  let score = 0;
+  let offset = 0;
+  for (const [index, patternSegment] of patternSegments.entries()) {
+    if (localeParam && patternSegment === `:${FIMO_LOCALE_PARAM}`) {
+      if (!withLocale) {
+        offset = -1;
+        continue;
+      }
+      const value2 = urlSegments[index];
+      if (!acceptsLocaleSegment(value2, localeParam, vocabulary)) {
+        return null;
+      }
+      localeFromPath = value2;
+      params[FIMO_LOCALE_PARAM] = value2;
+      continue;
+    }
+    const value = urlSegments[index + offset];
+    if (value === void 0) {
+      return null;
+    }
+    const placeholder = readPlaceholder(patternSegment);
+    if (placeholder) {
+      const { name, catchAll } = placeholder;
+      const rawValue = catchAll ? urlSegments.slice(index + offset).join("/") : value;
+      const decoded = safeDecode(rawValue);
+      params[name] = decoded;
+      entryParams[name] = decoded;
+      if (catchAll) {
+        break;
+      }
+      continue;
+    }
+    if (patternSegment !== value) {
+      return null;
+    }
+    score += 1;
+  }
+  return {
+    contract,
+    params,
+    entryParams,
+    locale: localeFromPath ?? vocabulary.defaultLocale,
+    localeFromPath: localeFromPath !== null,
+    score
+  };
+}
+function readPathname(input) {
+  try {
+    return new URL(input, "http://fimo.invalid").pathname;
+  } catch {
+    return input.split("#")[0].split("?")[0] || "/";
+  }
+}
+function safeDecode(value) {
+  try {
+    return decodeURIComponent(value);
+  } catch {
+    return value;
+  }
+}
+function matchFimoRoute(pathnameOrUrl, config) {
+  const urlSegments = splitSegments(normalizeRoutePath(readPathname(pathnameOrUrl)));
+  const vocabulary = readLocaleVocabulary(config);
+  let best = null;
+  for (const contract of resolveRouteContracts(config.routes)) {
+    if (!contract.config.path) {
+      continue;
+    }
+    const match = matchContract(urlSegments, contract, vocabulary);
+    if (match && (!best || match.score > best.score)) {
+      best = match;
+    }
+  }
+  return best;
+}
+function routeLocaleTargets(contract, config) {
+  const defaultLocale = getFimoDefaultLocale(config);
+  if (!contract.localeParam) {
+    return [{ locale: defaultLocale, prefixed: false }];
+  }
+  const optional = contract.localeParam.optional;
+  return getFimoLocales(config).map((locale) => ({
+    locale,
+    prefixed: optional ? locale !== defaultLocale : true
+  }));
+}
+function materializeRoutePath(contract, target) {
+  const params = target.params ?? {};
+  const substituted = splitSegments(contract.canonicalPath).map((segment) => {
+    const placeholder = readPlaceholder(segment);
+    if (!placeholder) {
+      return segment;
+    }
+    const value = params[placeholder.name];
+    if (value === void 0) {
+      return segment;
+    }
+    return placeholder.catchAll ? value.split("/").map((part) => encodeURIComponent(part)).join("/") : encodeURIComponent(value);
+  });
+  const prefix = target.prefixed ? [target.locale] : [];
+  return normalizeRoutePath(`/${[...prefix, ...substituted].join("/")}`);
+}
+export {
+  FIMO_LOCALE_PARAM,
+  getFimoDefaultLocale,
+  getFimoLocales,
+  hasLocaleSegment,
+  matchFimoRoute,
+  materializeRoutePath,
+  normalizeFimoLocale,
+  normalizeRoutePath,
+  resolveRouteContract,
+  resolveRouteContracts,
+  routeLocaleTargets
+};

package/dist/runtime/routing/AppRoutesProvider.js

@@ -8,7 +8,7 @@ import { AppErrorBoundary, onError } from '../core/AppErrorBoundary.js';
 import { ViteLifecycles } from '../core/ViteLifecycles.js';
 import { ScreenshotProvider } from '../iframe/ScreenshotProvider.js';
 import { getSafePreviewNavigationPath, isPreviewRuntimeEnabled } from '../preview/bridge.js';
-import { getPreviewLocationChange, getPreviewParentOrigin } from '../preview/location.js';
+import { getDocumentLocale, getPreviewLocationChange, getPreviewParentOrigin } from '../preview/location.js';
 import { OptionalTracking } from '../t/OptionalTracking.js';
 import { AppResetScrollOnNavigate } from './AppResetScrollOnNavigate.js';
 const titleCase = (seg) => seg
@@ -63,15 +63,16 @@ export function AppRoutesProvider({ appRoutes, children }) {
         }
         window.parent.postMessage({ type: 'nav/routes', payload: { routes: displayRoutes } }, getPreviewParentOrigin() ?? '*');
     }, [appRoutes, displayRoutes, previewEnabled]);
+    // This runtime predates locale-aware routing and has no fimo-config to read,
+    // so the document's own `lang` is the only locale the app has declared.
     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 },
+            payload: getPreviewLocationChange(location, getDocumentLocale(document, 'en'), parentOrigin),
         }, parentOrigin ?? '*');
     }, [location.hash, location.pathname, location.search, previewEnabled]);
     useEffect(sendRoutes, [sendRoutes]);

package/dist/runtime/seo/resolver.d.ts

@@ -28,6 +28,11 @@ import type { FimoConfig, FimoRouteConfig, FimoSEO } from '../shared/fimo-config
  */
 export declare const SEO_FIELD_KEYS: readonly ["title", "description", "siteName", "url", "image", "favicon", "twitterSite", "robots", "themeColor", "locale"];
 export declare function normalizePathname(pathname: string): string;
+/**
+ * Whether one pattern matches one path, and how specific the match is (the
+ * number of static segments it pinned down). Locale-aware: a pattern with a
+ * `:locale` segment matches both the prefixed and the canonical URL.
+ */
 export declare function matchRoutePath(pathname: string, pathPattern: string): {
     matched: boolean;
     score: number;

package/dist/runtime/seo/resolver.js

@@ -1,3 +1,4 @@
+import { matchFimoRoute } from '../routes/index.js';
 /**
  * Shared SEO resolver for the generated app.
  *
@@ -45,53 +46,20 @@ export function normalizePathname(pathname) {
     }
     return normalized;
 }
-function splitSegments(pathname) {
-    const normalized = normalizePathname(pathname);
-    if (normalized === '/') {
-        return [];
-    }
-    return normalized.slice(1).split('/');
-}
+/**
+ * Whether one pattern matches one path, and how specific the match is (the
+ * number of static segments it pinned down). Locale-aware: a pattern with a
+ * `:locale` segment matches both the prefixed and the canonical URL.
+ */
 export function matchRoutePath(pathname, pathPattern) {
-    const pathSegments = splitSegments(pathname);
-    const patternSegments = splitSegments(pathPattern);
-    if (pathSegments.length !== patternSegments.length) {
-        return { matched: false, score: -1 };
-    }
-    let staticSegments = 0;
-    for (let i = 0; i < patternSegments.length; i += 1) {
-        const routeSegment = patternSegments[i];
-        const inputSegment = pathSegments[i];
-        if (routeSegment.startsWith(':')) {
-            continue;
-        }
-        if (routeSegment !== inputSegment) {
-            return { matched: false, score: -1 };
-        }
-        staticSegments += 1;
-    }
-    return { matched: true, score: staticSegments };
+    const match = matchFimoRoute(pathname, { routes: { route: { path: pathPattern } } });
+    return match ? { matched: true, score: match.score } : { matched: false, score: -1 };
 }
 export function resolveRouteConfig(pathname, routes) {
     if (!routes) {
         return undefined;
     }
-    const normalizedPath = normalizePathname(pathname);
-    let bestMatch;
-    for (const routeConfig of Object.values(routes)) {
-        const pathPattern = routeConfig.path;
-        if (!pathPattern) {
-            continue;
-        }
-        const result = matchRoutePath(normalizedPath, pathPattern);
-        if (!result.matched) {
-            continue;
-        }
-        if (!bestMatch || result.score > bestMatch.score) {
-            bestMatch = { score: result.score, route: routeConfig };
-        }
-    }
-    return bestMatch?.route;
+    return matchFimoRoute(pathname, { routes })?.contract.config;
 }
 export function getNestedValue(input, path) {
     if (!input || typeof input !== 'object') {
@@ -124,7 +92,7 @@ function resolveSeoField(routeValue, globalValue, context) {
 }
 export function resolveSeoForPath(pathname, config, routeData) {
     const globalSeo = config.seo ?? {};
-    const routeConfig = resolveRouteConfig(pathname, config.routes);
+    const routeConfig = matchFimoRoute(pathname, config)?.contract.config;
     const routeSeo = routeConfig?.seo;
     if (!routeSeo) {
         return Object.keys(globalSeo).length > 0 ? globalSeo : undefined;

package/dist/runtime/shared/fimo-config.types.d.ts

@@ -1,3 +1,4 @@
+import type { FimoRouteConfig as SharedFimoRouteConfig, FimoRouteParamConfig as SharedFimoRouteParamConfig } from '../routes/index.js';
 export type FimoFramework = 'astro' | 'nextjs' | 'nuxtjs' | 'react-router' | 'remix' | 'sveltekit' | 'vite' | 'vue';
 export interface FimoRuntimeCommands {
     dev?: string;
@@ -40,20 +41,21 @@ export interface RouteSEO {
     locale?: string;
     siteName?: string;
 }
-export interface FimoRouteConfig {
-    label?: string;
-    path?: string;
-    params?: Record<string, {
-        schema: string;
-        queryField: string;
-        displayField: string;
-    }>;
-    seo?: RouteSEO;
-}
+/**
+ * A path parameter descriptor as it appears in `.fimo/config.json`.
+ *
+ * Deliberately permissive — it mirrors hand-written JSON. `resolveRouteContract`
+ * from the public `fimo/routes` entry narrows it into the discriminated
+ * `FimoRouteParam` union and reports whatever does not add up; `fimo validate`
+ * surfaces those issues.
+ */
+export type FimoRouteParamConfig = SharedFimoRouteParamConfig<import('@fimo/api-contracts').PageCollectionSourceQuery>;
+export type FimoRouteConfig = SharedFimoRouteConfig<import('@fimo/api-contracts').PageSources, import('@fimo/api-contracts').PageCollectionSourceQuery, RouteSEO>;
 export interface FimoI18nRoutingConfig {
     /**
-     * Supported now:
-     * - path-prefix: default locale renders at `/pricing`, non-default locales at `/es/pricing`.
+     * Legacy compatibility for projects that still carry a global routing
+     * setting. New projects declare locale ownership on each route with a
+     * `:locale` segment; the scaffold intentionally omits this block.
      *
      * Strategies we may support later:
      * - domain: `example.es/pricing`
@@ -63,7 +65,6 @@ export interface FimoI18nRoutingConfig {
      * - custom: framework code resolves locale and passes it to `<FimoProviders locale={...}>`
      */
     strategy?: 'path-prefix';
-    prefixDefaultLocale?: boolean;
 }
 export interface FimoI18nConfig {
     defaultLocale?: string;

package/dist/runtime/shared/preview-location.d.ts

@@ -1,23 +1,2 @@
-export interface PreviewLocationLike {
-    pathname: string;
-    search?: string;
-    hash?: string;
-}
-export interface PreviewLocationChange {
-    /** Safe workspace focus value; query/hash state stays navigation-only. */
-    path: string;
-    /** Exact app location used to keep the parent's iframe URL in sync. */
-    navigationPath: string;
-}
-export interface PreviewBrowserContext {
-    readonly window: Pick<Window, 'location' | 'sessionStorage'>;
-    readonly document: Pick<Document, 'referrer'>;
-}
-/** Prefer the immediate embedding document over a potentially stale referrer. */
-export declare function resolvePreviewParentOrigin(referrer: string | undefined, ancestorOrigins: readonly string[] | undefined): string | null;
-/** Resolve and remember the trusted Studio origin across full-page navigation. */
-export declare function getPreviewParentOrigin(browser?: PreviewBrowserContext): string | null;
-/** Keep sandbox credentials and the iframe cache-buster out of app navigation state. */
-export declare function getPreviewLocationPath(location: PreviewLocationLike): string;
-export declare function getPreviewLocationChange(location: PreviewLocationLike): PreviewLocationChange;
+export * from '../preview/location.js';
 //# sourceMappingURL=preview-location.d.ts.map

package/dist/runtime/shared/preview-location.js

@@ -1,93 +1,5 @@
-const PREVIEW_INTERNAL_QUERY_PARAMS = new Set(['bl_preview_token', 'preview_token', 't']);
-const PREVIEW_PARENT_ORIGIN_STORAGE_KEY = 'fimo-preview-parent-origin';
-let rememberedPreviewParentOrigin;
-const getOrigin = (value) => {
-    if (!value) {
-        return null;
-    }
-    try {
-        const origin = new URL(value).origin;
-        return origin === 'null' ? null : origin;
-    }
-    catch {
-        return null;
-    }
-};
-/** Prefer the immediate embedding document over a potentially stale referrer. */
-export function resolvePreviewParentOrigin(referrer, ancestorOrigins) {
-    return getOrigin(ancestorOrigins?.[0]) ?? getOrigin(referrer);
-}
-/** Resolve and remember the trusted Studio origin across full-page navigation. */
-export function getPreviewParentOrigin(browser) {
-    const browserWindow = browser?.window ?? (typeof window === 'undefined' ? undefined : window);
-    const browserDocument = browser?.document ?? (typeof document === 'undefined' ? undefined : document);
-    if (!browserWindow) {
-        return null;
-    }
-    const storage = readSessionStorage(browserWindow);
-    const ancestorOrigin = getOrigin(browserWindow.location.ancestorOrigins?.[0]);
-    if (ancestorOrigin) {
-        rememberPreviewParentOrigin(ancestorOrigin, storage);
-        return ancestorOrigin;
-    }
-    const rememberedOrigin = readRememberedPreviewParentOrigin(storage);
-    if (rememberedOrigin) {
-        return rememberedOrigin;
-    }
-    const referrerOrigin = getOrigin(browserDocument?.referrer);
-    if (referrerOrigin) {
-        rememberPreviewParentOrigin(referrerOrigin, storage);
-    }
-    return referrerOrigin;
-}
-function readSessionStorage(browserWindow) {
-    try {
-        return browserWindow.sessionStorage;
-    }
-    catch {
-        return undefined;
-    }
-}
-function readRememberedPreviewParentOrigin(storage) {
-    if (rememberedPreviewParentOrigin !== undefined) {
-        return rememberedPreviewParentOrigin;
-    }
-    if (!storage) {
-        rememberedPreviewParentOrigin = null;
-        return null;
-    }
-    try {
-        rememberedPreviewParentOrigin = getOrigin(storage.getItem(PREVIEW_PARENT_ORIGIN_STORAGE_KEY) ?? undefined);
-    }
-    catch {
-        rememberedPreviewParentOrigin = null;
-    }
-    return rememberedPreviewParentOrigin;
-}
-function rememberPreviewParentOrigin(origin, storage) {
-    rememberedPreviewParentOrigin = origin;
-    if (!storage) {
-        return;
-    }
-    try {
-        storage.setItem(PREVIEW_PARENT_ORIGIN_STORAGE_KEY, origin);
-    }
-    catch {
-        // Storage availability must not block the preview message channel.
-    }
-}
-/** Keep sandbox credentials and the iframe cache-buster out of app navigation state. */
-export function getPreviewLocationPath(location) {
-    const search = new URLSearchParams(location.search ?? '');
-    for (const key of PREVIEW_INTERNAL_QUERY_PARAMS) {
-        search.delete(key);
-    }
-    const query = search.toString();
-    return `${location.pathname}${query ? `?${query}` : ''}${location.hash ?? ''}`;
-}
-export function getPreviewLocationChange(location) {
-    return {
-        path: location.pathname,
-        navigationPath: getPreviewLocationPath(location),
-    };
-}
+// The SvelteKit bundle reaches the preview location contract through this
+// path. Only one implementation may exist: the remembered parent origin is
+// module state, and a second copy would let the two bridges disagree about
+// which Studio origin is trusted.
+export * from '../preview/location.js';

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

@@ -3,11 +3,20 @@ export interface PreviewNavigation {
     goto: (to: string) => unknown;
     /** SvelteKit `invalidateAll` — reruns every `load` against fresh content. */
     invalidateAll: () => Promise<unknown>;
+    /** Optional app-owned locale resolver, evaluated for every bridge message. */
+    locale?: () => string | undefined;
 }
 /** Load the platform preview script once. Empty configuration keeps preview disabled. */
 export declare function ensurePreviewScript(src: string | undefined): boolean;
-/** Report where the app is now. Studio keeps its URL and route selector in sync from this. */
-export declare function sendPreviewLocation(): void;
+/**
+ * Report where the app is now, and in which locale. Studio keeps its URL,
+ * route selector and content locale in sync from this.
+ *
+ * `locale` defaults to the locale the SvelteKit shell rendered into
+ * `<html lang>`; pass one explicitly when the app resolves it somewhere the
+ * document does not show, for example a cookie or a user preference.
+ */
+export declare function sendPreviewLocation(locale?: string): void;
 /**
  * Listen for the live Studio preview protocol and answer it with SvelteKit's
  * own navigation APIs. Returns the disconnect function.
@@ -15,5 +24,5 @@ export declare function sendPreviewLocation(): void;
  * Only messages from the established parent origin are honored. History stays
  * native, so Studio's back/forward controls need no protocol of their own.
  */
-export declare function connectPreview({ goto, invalidateAll }: PreviewNavigation): () => void;
+export declare function connectPreview({ goto, invalidateAll, locale }: PreviewNavigation): () => void;
 //# sourceMappingURL=preview.d.ts.map